Interactive Forest Plot of Top/Bottom DELTA/Stouffer Statistics

Plotly version of forestplot() that highlights the most extreme positive and negative features within a chosen rank. The plot shows the top n_pos_each features on the positive side and the top n_neg_each features on the negative side, ordered by the selected statistic (statistic_to_plot).

Usage

forestplot_interactive(
  results_tbl,
  rank_of_interest,
  statistic_to_plot = c("T", "T_stand", "Z_from_p"),
  n_neg_each = 15,
  n_pos_each = 15,
  filter_significant = "none",
  sig_level = 0.05,
  left_label = "More in group1",
  right_label = "More in group2",
  arrow_length_frac = 0.35,
  label_x_gap_frac = 0.06,
  label_y_offset = 0,
  arrow_color = "red",
  arrow_linewidth = 0.6,
  arrow_head_length_mm = 3,
  use_diverging_colors = FALSE,
  show_grid = FALSE,
  base_text_pt = 12,
  font_family = "Montserrat",
  seg_width = 1.6,
  point_size = 11
)

Arguments

results_tbl: Data frame/tibble with at least: rank, feature, group1, group2, design, T_obs, p_perm.
rank_of_interest: Character scalar specifying the rank to plot (e.g., "species").
statistic_to_plot: Which statistic to rank/plot: "T" (raw T_obs), "T_stand" (permutation-standardized), or "Z_from_p" (signed Z from permutation p).
n_neg_each: Number of most negative features to show. Default 15.
n_pos_each: Number of most positive features to show. Default 15.
filter_significant: Column name to filter on, or "none" to disable filtering. If the column is numeric, keep rows where col <= sig_level.
sig_level: Significance threshold used when filter_significant is numeric. Default 0.05.
left_label: Text for the left arrow/side label.
right_label: Text for the right arrow/side label.
arrow_length_frac: Fraction of max \(|T|\) used as half-length of arrows.
label_x_gap_frac: Horizontal label gap for arrow labels beyond arrow tips (fraction of max \(|T|\)).
label_y_offset: Additional vertical offset for arrow-end labels (y-axis units).
arrow_color: Arrow/label color.
arrow_linewidth: Arrow line width (plotly units).
arrow_head_length_mm: Arrow head size (approximate, plotly units).
use_diverging_colors: Logical; if TRUE, lines/points are shaded blue (negative) to red (positive) with higher contrast; otherwise monochrome.
show_grid: Logical; show grid lines.
base_text_pt: Base text size.
font_family: Font family name.
seg_width: Segment line width.
point_size: Point size.

Value

A list with data and plot (plotly object).

Details

The y-axis lists feature names (sorted by the chosen statistic), and the x-axis shows the signed effect size for each feature. Each feature is drawn as a horizontal segment from zero to its statistic value, with a point at the end of the segment. A dashed vertical line marks zero to separate negative from positive shifts. The title and subtitle report the contrast and how many features are shown.

If use_diverging_colors = TRUE, segments/points are colored by magnitude on a blue-to-red scale (negative to positive), otherwise a single color is used. Arrow annotations label the direction of enrichment for each group.

statistic_to_plot controls the statistic used for both ranking and plotting: raw T_obs, permutation-standardized T_obs_stand, or Z_from_p (signed Z from permutation p-values).

Examples

# \donttest{
  set.seed(1)
  n <- 20
  results_tbl <- data.frame(
    rank = rep("species", n),
    feature = paste0("feat_", seq_len(n)),
    group1 = "control",
    group2 = "treated",
    design = "case-control",
    T_obs = rnorm(n, sd = 2),
    p_perm = runif(n),
    T_obs_stand = rnorm(n),
    Z_from_p = qnorm(1 - runif(n) / 2) * sign(rnorm(n))
  )

  out <- forestplot_interactive(
    results_tbl,
    rank_of_interest = "species",
    statistic_to_plot = "T",
    n_neg_each = 5,
    n_pos_each = 5,
    left_label = "More in control",
    right_label = "More in treated",
    use_diverging_colors = TRUE,
    label_x_gap_frac = 0,
    label_y_offset = -0.05
  )

  out$plot

# }