Plot ClockSHAP waterfall for a single sample — plot_clockshap

Create a horizontal waterfall plot showing age-adjusted ClockSHAP contributions for a single sample, highlighting the top contributing features and aggregating the remainder as "Other".

Usage

plot_clockshap_waterfall(
  x,
  sample,
  top_n = 10,
  show_age_labels = TRUE,
  show_delta_label = TRUE,
  show_effect_labels = TRUE,
  effect_label_mode = "auto",
  effect_label_min_frac = 0.03,
  effect_label_outside_nudge_frac = 0.02,
  show_effect_label_connectors = TRUE,
  x_axis_title = "Age (years)",
  y_axis_title = NULL,
  deviation_label = "Deviation = {value} yr",
  expected_age_label = "Expected Age\n{value} yr",
  predicted_age_label = "Predicted Age\n{value} yr",
  effect_label = "{value}",
  top_label_digits = NULL,
  effect_label_digits = NULL,
  digits = 1
)

Arguments

x: A clockshap object.
sample: A sample index (integer) or row name (character).
top_n: Number of top absolute contributions to display.
show_age_labels: Logical; show the expected/predicted age text labels.
show_delta_label: Logical; show the deviation label above the arrow.
show_effect_labels: Logical; show the contribution values inside bars.
effect_label_mode: Label placement strategy for effect labels. "auto" places labels inside sufficiently large bars and outside small bars. "inside" places all labels inside, "outside" places all labels outside, and "hide_small" hides labels for small bars.
effect_label_min_frac: Numeric scalar giving the minimum bar width (as a fraction of x-axis span) required for inside placement.
effect_label_outside_nudge_frac: Numeric scalar giving outside-label horizontal offset (as a fraction of x-axis span).
show_effect_label_connectors: Logical; draw connector segments from bar ends to outside labels.
x_axis_title: Character scalar for the x-axis title.
y_axis_title: Character scalar for the y-axis title. Use NULL for no title.
deviation_label: Text template for the deviation annotation. Use {value} as a placeholder for the numeric value.
expected_age_label: Text template for the expected age annotation. Use {value} as a placeholder for the numeric value.
predicted_age_label: Text template for the predicted age annotation. Use {value} as a placeholder for the numeric value.
effect_label: Text template for effect labels shown inside bars. Use {value} as a placeholder for the numeric value.
top_label_digits: Deprecated compatibility argument. Use digits.
effect_label_digits: Deprecated compatibility argument. Use digits.
digits: Number of decimal places used for all numeric labels.

Value

A ggplot object.

Details

The plot visualizes how feature-level contributions bridge the expected age (conditioned on chronological age) to the predicted age.

Labels use reconciled rounding from clockshap_waterfall_values(), so displayed contributions sum to the displayed deviation and displayed expected age plus deviation equals displayed predicted age. To preserve these identities, an endpoint label may differ from independently rounding its stored value by one unit in the last displayed decimal place.