Diverging heatmap of a difference matrix (post - pre)

Usage

HeatmapDistanceDiff(
  df_diff,
  df_original = NULL,
  title = "Change in energy distance (post − pre)",
  subtitle = NULL,
  custom_order = NULL,
  relative = FALSE,
  limits = NULL,
  scale_mode = c("auto", "symmetric", "asymmetric", "symlog"),
  linthresh = NULL,
  min_limit = 0,
  quantile_clip = 1,
  show_values = NULL,
  digits = 3,
  diverging_palette = NULL
)

Arguments

df_diff

Signed difference matrix or data.frame (post - pre).

df_original

Optional pre-perturbation matrix. Required when relative = TRUE; also used to report effect size in the subtitle.

title, subtitle

Plot title / subtitle. subtitle = NULL auto-generates one reporting magnitude and the scale in use.

custom_order

Character vector giving row/column order.

relative

If TRUE, plot 100 * (post - pre) / pre. Needs df_original.

limits

Optional c(lower, upper) fixing the colour range in plotted units. Must bracket zero. Supply the SAME value to several calls to make figures directly comparable side by side; see DiffLimits() to derive one pair covering a set of matrices. Values outside the range are squished to the end colour rather than dropped. When set, quantile_clip and min_limit are ignored, and scale_mode = "auto" resolves to "symmetric" so every figure shares one transform as well as one range.

scale_mode

One of "auto", "symmetric", "asymmetric", "symlog".

symmetric: One linear scale. Magnitude comparable everywhere.
asymmetric: Each arm linear to its own extreme, so a small positive arm stays visible beside a large negative one. Magnitude NOT comparable across zero — the bar labels both endpoints and the subtitle says so.
symlog: One signed-log scale. Comparable across sign AND across orders of magnitude — the right choice when values span e.g. -40 to +0.05, where per-arm linear scaling still crushes everything between.
auto: symlog when max|v| exceeds ~50x the 10th percentile of |v|, symmetric otherwise. Reports its choice in the subtitle.

linthresh

symlog only: below this magnitude the scale is linear. NULL = 10th percentile of |v|.

min_limit

Floor on the auto-fitted arm limits, in plotted units. Stops tiny differences being magnified into a dramatic-looking result. Ignored when limits is supplied.

quantile_clip

Quantile of |value| used to set auto-fitted extremes. Default 1 (true max); e.g. 0.95 stops one outlier pair flattening the map. Ignored when limits is supplied.

show_values

Draw the value in each cell. NULL = show when <= 12 groups.

digits

Rounding for cell labels.

diverging_palette

Colours low -> mid -> high. Must be odd length.

Value

A ggplot object.