pytyche.analysis.fit_policy_tree

pytyche.analysis.fit_policy_tree(posterior, *, max_depth=3, min_segment_share=0.1, n_bootstrap=50, bootstrap_seed=0)[source]

Discover interpretable segments from the posterior’s per-visitor treatment effects, by fitting a shallow decision tree.

Each visitor is labeled with the arm the posterior expects to be best for them: their posterior-mean contrast vector, reduced to the largest-lift treatment — or control, when no lift is positive. A multiclass DecisionTreeClassifier is then fit on the visitors’ features (the same feature encoding the fit entry points use), so each leaf groups visitors the model treats alike. Each leaf becomes a DiscoveredSegment:

  • rule reproduces the leaf’s membership exactly through pytyche.summarize.apply_rule() (verified; mismatch raises RuntimeError). A root-only tree yields one catch-all segment with clauses == ().

  • arm_best_probabilities are per-draw best-arm win frequencies over the leaf’s per-draw mean contrasts — the same code path thompson_allocation uses.

  • gate_estimate / gate_ci (mean and the 80% interval) are computed on the recommended arm’s in-segment contrast draws; for control-recommended leaves, on the maximum-mean contrast (the strongest challenger — non-positive by construction). The interval is the raw 10th/90th percentiles, or the calibrated remap when the posterior carries an attached Calibration artifact.

  • stability_score is bootstrap-replicability: the fraction of n_bootstrap row-resampled tree refits in which some leaf has Jaccard overlap >= 0.5 with the segment’s member set.

Parameters:

  • posterior (HurdleBCFResult | ContinuousBCFResult | BinaryBCFResult) – One of the three posterior result types, carrying observed data (raises otherwise).

  • max_depth (int) – Maximum tree depth.

  • min_segment_share (float) – Minimum fraction of visitors per leaf (sklearn min_weight_fraction_leaf).

  • n_bootstrap (int) – Bootstrap refits behind stability_score; 0 skips stability — every score is NaN and a UserWarning is emitted.

  • bootstrap_seed (int) – Seed for the bootstrap resampling RNG.

Return type:

PolicyTreeResult

Returns:

PolicyTreeResult with one segment per leaf (ordered by sklearn leaf id); result.observed is posterior.observed by identity.

Raises:

  • ValueError – When posterior.observed is None, or when n_bootstrap is negative.

  • TypeError – When posterior is not an accepted result type.

  • RuntimeError – When an extracted segment rule fails to reproduce its leaf’s membership (rule extraction is wrong — fail loud).