Assemble policy-tree plots, table, and standard text — margot_report_policy

Convenience wrapper for the standard policy-tree reporting artefacts. The returned components are ordinary objects that can be edited, replaced, or omitted in manuscript workflows.

Usage

margot_report_policy_tree(
  result_object,
  model_name,
  policy_cv = NULL,
  depth = NULL,
  original_df = NULL,
  weights = NULL,
  digits = 3L,
  ci_level = 0.95,
  label_mapping = NULL,
  include_plots = TRUE,
  include_table = TRUE,
  include_text = TRUE,
  include_policy_value = !is.null(policy_cv),
  layout = list(heights = c(1, 2)),
  annotation = list(tag_levels = "A"),
  projection_args = list(),
  decision_tree_args = list(),
  reporting_data = NULL,
  reporting_heights = c(1.5, 1.7, 1),
  reporting_layout = c("standard", "compact", "two_panel"),
  panel_labels = list()
)

Arguments

result_object: A margot_causal_forest()-style object.
model_name: Character scalar naming the model to report.
policy_cv: Optional margot_policy_tree_cv object with held-out policy-tree diagnostics.
depth: Optional integer tree depth. If NULL and policy_cv is supplied, the selected depth from policy_cv$depth_map is used when available; otherwise depth one is used.
original_df: Optional data frame with original-scale variables.
weights: Optional evaluation weights.
digits: Integer; rounding used in formatted table columns.
ci_level: Confidence level for leaf score intervals.
label_mapping: Optional named list used for display labels.
include_plots: Logical. Include plot components.
include_table: Logical. Include the leaf table.
include_text: Logical. Include standard interpretation text.
include_policy_value: Logical. Include held-out value summaries when policy_cv is supplied.
layout: List passed to margot_plot_policy_tree_panels().
annotation: List passed to margot_plot_policy_tree_panels().
projection_args: Optional list of arguments for the projection plot.
decision_tree_args: Optional list of arguments for the decision tree.
reporting_data: Optional margot_policy_reporting_data() object. Enables the stored four-panel report: A/B use the existing combo; C/D show supplied leaf contrasts and value gain. This path consumes supplied estimates and intervals, requires matching rule and reference rows, and uses the stored weights and margin. Calls with reporting_data = NULL retain their existing calculations and return shape.
reporting_heights: Relative heights of A, B and the C/D row for a stored report (two numbers also accepted for two-panel reporting); default c(1.5, 1.7, 1). When omitted with compact reporting, depth-adaptive shorter tree rows are used.
reporting_layout: "two_panel" combines only the tree and weighted projection without stamped captions, retaining uncertainty plots and text as separate report components. "standard" preserves the stored report's layout. "compact" uses compact tree geometry, smaller margins and legend spacing, and prints the outcome heading once. Applies only with reporting_data.
panel_labels: Named list of ggplot label overrides for stored panels A, B, C, and D; each may name title, subtitle, x, y, and caption. Values are character scalars or NULL. Presentation overrides leave numerical tables and provenance unchanged; retain the applicable inferential qualifications in the figure or accompanying caption.

Value

A list with table, text, plots, and metadata.

Details

This helper reports display-tree artefacts and can also attach held-out policy-value summaries when supplied a margot_policy_tree_cv object. Leaf tables use the signed evaluation-sample T-C contrast $$ \Delta_L = \frac{\sum_{j \in E_L} w_j\{\Gamma_{jT} - \Gamma_{jC}\}} {\sum_{j \in E_L} w_j} $$ where $\Gamma_{ja}$ is the action score for observation $j$ under action $a$ and $E_L$ are evaluation observations in leaf $L$. The selected action is reported separately as the fitted tree's stored action, 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}. $$ Tree-level value summaries compare the learned rule with all-control, all-treatment, and best-constant baselines. Between-leaf differences in $\Delta_L$ describe variation in magnitude, not the policy-tree decision rule.