Significance Plot Configuration — SignificanceConfig • rtemis.draw

One portable specification for volcano plots and categorical significance bars. The latter is the MassGLM Manhattan view, not a genomic-position plot. Compiles to ScatterSeriesOption / BarSeriesOption in ECharts src/chart/scatter/ScatterSeries.ts and src/chart/bar/BarSeries.ts, with MarkLineOption from src/component/marker/MarkLineModel.ts. to_list() serializes the semantic configuration using schema keys; compile() produces the ECharts option.

Usage

SignificanceConfig(
  dat_path = NULL,
  title = NULL,
  origin = NULL,
  writer = NULL,
  legend_position = "top",
  legend_placement = "outside",
  view = "volcano",
  estimate = "estimate",
  p_value = "p_value",
  label = NULL,
  group = NULL,
  palette = NULL,
  p_adjust_method = "holm",
  n_tests = NULL,
  p_transform = "neg_log10",
  p_thresh = 0.05,
  x_thresh = 0,
  zero_cap = NULL,
  annotate_n = 7L,
  reference = TRUE,
  legend = TRUE,
  negative_color = "#BE2E5F",
  neutral_color = "#808080",
  positive_color = "#0F6A66",
  alpha = 0.8,
  point_size = 8,
  xlab = NULL,
  ylab = NULL,
  xlim = NULL,
  ylim = NULL,
  margin_top = NULL,
  margin_right = NULL,
  margin_bottom = NULL,
  margin_left = NULL
)

Arguments

dat_path: Optional Character: Path to the data, read at draw time. The serializable alternative to passing data to draw().
title: Optional Character: Chart title. Declared here because it is the one property every chart type has; palette is not (four take a colormap instead), and axis labels and margins are cartesian-only.
origin: Optional Named character {"user", "default", "derived"}: Where each value came from, one entry per settable property. Absent on an authored config; written by the interface that resolved it.
writer: Optional Named character: Which interface wrote the config, as name and version. Absent on an authored config.
legend_position: Character {"top", "bottom", "left", "right", "top-left", "top-right", "bottom-left", "bottom-right"}: Legend anchor. Top/bottom anchors use horizontal rows; left/right anchors use a vertical column. Corner anchors align within the top or bottom row.
legend_placement: Character {"outside", "inside"}: Relation to the plotting area. Outside placement reserves space for the complete legend; inside placement overlays the data. Neither setting adds a missing legend.
view: Character {"volcano", "manhattan"}: Scatter or categorical bar view.
estimate: Character: Column containing coefficients or other signed effects.
p_value: Character: Column containing unadjusted p-values.
label: Optional Character: Outcome-label column. Unset generates row labels.
group: Optional Character: Display-group column. Unset colors by significance and effect direction. Missing groups omit marks after full-family adjustment. Groups never change significance thresholds or annotation ranking.
palette: Optional Character vector: Display-group colors in first-appearance order; unset uses the theme. Requires a group binding.
p_adjust_method: Character: Method from stats::p.adjust.methods. Adjustment precedes transformation.
n_tests: Optional Integer [1, Inf): Hypothesis-family size, at least the number of supplied rows. Unset counts all rows, including missing p-values.
p_transform: Character {"neg_log10", "identity", "one_minus"}: Named display transform of adjusted p-values.
p_thresh: Numeric (0, 1]: Significance threshold on adjusted p-values; the comparison is strict.
x_thresh: Numeric: Effect threshold separating low and high significant results.
zero_cap: Optional Numeric (0, Inf): Finite display height for zero p-values under neg_log10; must exceed all finite heights and the significance reference. Unset computes a cap one unit above their rounded-up maximum.
annotate_n: Integer [0, Inf): Maximum significant feature labels per side in the volcano view, ranked by raw p-value with input-order ties.
reference: Logical: Show the transformed significance threshold and, for volcanoes, the effect threshold.
legend: Logical: Show the nonempty significance groups.
negative_color: Character: Color for significant effects below x_thresh.
neutral_color: Character: Color for other results, including effects equal to x_thresh.
positive_color: Character: Color for significant effects above x_thresh.
alpha: Numeric [0, 1]: Mark opacity.
point_size: Numeric (0, Inf): Scatter symbol size in pixels.
xlab: Optional Character: X-axis label.
ylab: Optional Character: Y-axis label.
xlim: Optional Numeric: Exactly two increasing finite volcano x-axis limits. Not used by the categorical view.
ylim: Optional Numeric: Exactly two increasing finite y-axis limits.
margin_top: Optional Integer [0, Inf): Top plot margin in pixels.
margin_right: Optional Integer [0, Inf): Right plot margin in pixels.
margin_bottom: Optional Integer [0, Inf): Bottom plot margin in pixels.
margin_left: Optional Integer [0, Inf): Left plot margin in pixels.

Value

A SignificanceConfig object.

Statistical semantics

P-values are adjusted once over the full supplied family before rows with missing estimates or p-values are omitted from the marks. Missing hypotheses still count in n_tests; they do not become observed p-values of one. Raw and adjusted values remain in the compiled data. Function-valued transforms are not accepted by this portable configuration.

Under neg_log10, zero p-values have infinite mathematical height. They retain their zero value but are displayed at zero_cap, identified by triangles and a caption. No positive p-value is clamped. For identity and one-minus transforms, zeros are finite and no cap is used.

Examples

cfg <- setup_SignificanceConfig(estimate = "effect", p_value = "p")
draw(cfg, data = data.frame(effect = c(-2, 0.1, 3), p = c(0.001, 0.6, 0.002)))