plot_sg_distribution: Plot Distribution of Identified Subgroups

View source: R/plot_sg_distribution.R

plot_sg_distributionR Documentation

Plot Distribution of Identified Subgroups

Description

Bar chart of subgroups identified across simulations, filtered to those appearing in at least min_pct of the found simulations. Supports two column schemas (MRCT and run_simulation_analysis), top-K capping with a pooled "Other" bar, automatic threshold halving when no label clears the initial cut, and an n_bars attribute for adaptive figure-height computation.

Usage

plot_sg_distribution(
  results,
  min_pct = 5,
  title = "Distribution of Identified Subgroups",
  wrap_width = 25,
  any_col = "any_found",
  label_col = "sg_found",
  top_k = NULL,
  show_other = TRUE,
  min_floor_pct = 0.5,
  max_halvings = 0L,
  bar_label_inside = FALSE,
  placeholder_on_empty = FALSE
)

Arguments

results

data.frame or data.table with at least two columns: a per-replicate detection flag (0/1) and an identified-subgroup label string. Column names are configurable via any_col and label_col. The defaults ("any_found", "sg_found") match mrct_region_sims(); pass any_col = "any.H", label_col = "sg.def" to plot run_simulation_analysis() output.

min_pct

Numeric. Minimum percentage threshold for display (0-100). Default: 5.

title

Character. Plot title.

wrap_width

Integer. Character width for wrapping long subgroup labels. Default: 25.

any_col

Character. Column name of the per-replicate detection flag. Default: "any_found".

label_col

Character. Column name of the identified-subgroup label string. Default: "sg_found".

top_k

Integer or NULL. Maximum number of bars to display; additional passing labels are pooled into a single "Other (k labels)" bar (see show_other). Prevents unreadable charts under diffuse null hypotheses where finds are fragmented across many singleton labels. Default: NULL (no cap, i.e. the original behaviour).

show_other

Logical. When top_k is set and extra labels are pooled, attach the "Other" bar. Default: TRUE. Set to FALSE to suppress the pooled bar entirely; its count and percent are still reported in the subtitle for honesty.

min_floor_pct

Numeric. Lower bound on automatic threshold halving. Default: 0.5.

max_halvings

Integer. Maximum number of halvings applied to min_pct when no label clears the initial threshold. Default: 0 (no halving, i.e. the original behaviour). Set to 2 to match the extended-diagnostic behaviour used in the benefit-search vignettes.

bar_label_inside

Logical. Render bar labels inside bars (hjust = 1.05) instead of outside (hjust = -0.1). Prevents small-count labels from clipping off the right edge. Default: FALSE (original outside-of-bar placement).

placeholder_on_empty

Logical. When no subgroups clear the threshold (even after halving), return a minimal "no data" placeholder plot with attr(p, "n_bars") = 0L instead of invisible(NULL). Default: FALSE (the original behaviour). Set to TRUE to simplify adaptive- figure-height rendering in vignettes.

Value

A ggplot2 object, or invisible(NULL) when no subgroups are found and placeholder_on_empty = FALSE. When a plot is returned it carries two attributes:

n_bars

Integer. Number of bars in the plot (0 in the placeholder case). Use sgdist_fig_height() to compute an adaptive figure height for knitr.

effective_min_pct

Numeric. The threshold in effect after any automatic halving.

See Also

sgdist_fig_height for computing an adaptive figure height from n_bars, and run_simulation_analysis / mrct_region_sims for the upstream simulation engines.

Examples

## Not run: 
# MRCT / mrct_region_sims() output (default column schema): one row per
# simulated trial, a 0/1 detection flag (any_found) and the label of the
# subgroup found (sg_found).  A small stand-in table is built here.
sims_mrct <- data.frame(
  any_found = rep(c(1L, 0L), c(40L, 10L)),
  sg_found  = rep(c("{z_regA <= 0}", "{z_age <= 50}", "{z_er <= 0}",
                    "none"), c(24L, 10L, 6L, 10L))
)
plot_sg_distribution(sims_mrct)

# run_simulation_analysis() output with top-K cap and auto-halving.
# A stand-in with its analysis, any.H and sg.def columns: 30 replicates
# each find a different subgroup, so no label reaches min_pct = 5.
results_alt <- data.frame(
  analysis = "FS",
  any.H    = rep(c(1L, 0L), c(30L, 20L)),
  sg.def   = c(sprintf("{er <= %d}", 1:30), rep("", 20L))
)
fs_rows <- results_alt[results_alt$analysis == "FS", ]
p <- plot_sg_distribution(
  fs_rows,
  any_col              = "any.H",
  label_col            = "sg.def",
  top_k                = 15L,
  show_other           = FALSE,
  max_halvings         = 2L,
  bar_label_inside     = TRUE,
  placeholder_on_empty = TRUE,
  title                = "HTE: Subgroups Identified (H-hat)"
)
fig_h <- sgdist_fig_height(attr(p, "n_bars"))

## End(Not run)


forestsearch documentation built on Nov. 15, 2026, 9:06 a.m.