explain_pareto_selection: Describe the Pareto-Frontier Selection in Words

View source: R/explain_pareto_selection.R

explain_pareto_selectionR Documentation

Describe the Pareto-Frontier Selection in Words

Description

Wraps pareto_frontier_table with a verbal account of the selection: why the chosen subgroup satisfies the configured sg_focus + selection_rule criterion, and, for each non-dominated alternative, on which lexicographic axis it lost to the winner.

Usage

explain_pareto_selection(
  fs,
  ci_table = NULL,
  effect_label = NULL,
  digits = 3L,
  verbosity = c("medium", "compact", "detailed"),
  format = c("markdown", "character", "list")
)

Arguments

fs

A forestsearch result object.

ci_table

Optional data.table from compute_frontier_cis. When supplied, the Naive 95\ Loser paragraphs do not reference CIs by design – the selection rule does not consider CIs.

effect_label

Optional character override for the effect- measure label in prose, e.g. "Hazard ratio". Defaults to a sensible string for the outcome type.

digits

Integer. Decimal places for effect estimates and bound values in the prose. Default 3L.

verbosity

One of "compact", "medium" (default), or "detailed".

format

One of "markdown" (default), "character", or "list".

Details

The wrapper is descriptive, not algorithmic: it reads the frontier and the configuration off the returned fs object and renders prose. It does not re-run the selection. A future change to the lexicographic key in forestsearch would require updating this wrapper to remain accurate.

Value

Depending on format:

"markdown"

A single string with embedded line breaks and bullet markers, ready for cat() in a Quarto chunk with results = "asis".

"character"

A character vector with one element per logical paragraph or bullet (no markdown markers).

"list"

A structured list with named elements criterion, selected, losers, closing, and meta.

Verbosity

"compact"

Criterion sentence + selected line + a one-line bullet per loser.

"medium" (default)

Criterion sentence + selected paragraph (including the Naive CI if ci_table is given) + one short paragraph per loser, each naming the lex-key axis on which the loser was beaten.

"detailed"

Medium + a closing paragraph that reproduces the formal lex key, the resolved indicator values, and a note about any ties broken downstream.

Loser ordering

Losers are sorted by "closeness-to-winning", which is operationalised as: later loss-axis comes first, then smaller gap on that axis. Specifically, a loser that lost on K (the last tiebreaker) is reported before one that lost on N (an early axis), and a loser that beat the winner on every axis until the final one is reported before a loser that fell off the band entirely. This puts the boundary cases first, which is the most informative order for understanding how the rule made its choice.

See Also

pareto_frontier_table, plot_pareto_frontier, compute_frontier_cis.

Examples

## Not run: 
ci_tab <- compute_frontier_cis(fs, n_splits = 1000, seed = 1)

# Inline in a Quarto chunk
cat(explain_pareto_selection(fs, ci_table = ci_tab))

# Or get the structured object
explain_pareto_selection(fs, ci_table = ci_tab, format = "list")

## End(Not run)


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