Generate standard policy-tree reporting text — margot_text_policy

Produces cautious stock text for policy-tree reports. The text describes the reporting convention without making substantive claims about moderators.

Usage

margot_text_policy_tree(
  source = c("generic", "heldout_cv", "display_tree"),
  include_ci = TRUE,
  include_plot_convention = TRUE,
  collapse = TRUE,
  object = NULL,
  action_names = c(control = "control", treated = "treatment"),
  label_mapping = NULL,
  value_units = "stored outcome units",
  digits = 3L,
  include_definitions = TRUE
)

Arguments

source: Character. Reporting source to describe.
include_ci: Logical. Include the interval-interpretation sentence.
include_plot_convention: Logical. Include the two-panel plot sentence.
collapse: Logical. If TRUE, return one character string; otherwise return a character vector of sentences.
object: Optional margot_policy_tree_cv object. With source heldout_cv, append an interpretation of its stored selected-depth values and leaf summaries. No policy is fitted or re-evaluated.
action_names: Named character vector with control and treated labels, in that order of action coding.
label_mapping: Optional named labels for outcome identifiers.
value_units: Character scalar describing the stored outcome units.
digits: Integer from 0 to 8; display precision only.
include_definitions: Logical; prepend the general explanatory text.

Value

A character string or character vector.

Details

Policy-tree reporting separates the selected action learned by the fitted tree from the signed treatment-control score contrast computed on evaluation rows. Let $\Gamma_{ja}$ denote the action score for observation $j$ under action $a$, let $L$ denote a policy-tree leaf, and let $E_L$ denote the evaluation observations routed to that leaf. For binary actions $C$ and $T$, the reported contrast is $$ \Delta_L = \frac{\sum_{j \in E_L} w_j\{\Gamma_{jT} - \Gamma_{jC}\}} {\sum_{j \in E_L} w_j}. $$ The stored selected action is learned on training observations $S_L$: $$ \pi(L) = \arg\max_{a \in \{C,T\}} \frac{\sum_{j \in S_L} w_j \Gamma_{ja}}{\sum_{j \in S_L} w_j}. $$ If every displayed leaf has the same selected action, the tree describes variation in score-contrast magnitude rather than a selective rule that changes actions across leaves.