pytyche.analysis.recommendation_summary

pytyche.analysis.recommendation_summary(posterior, treatment, segment=None, *, thresholds=None, min_practical_effect=0.02)[source]

Act-now SHIP / CONTINUE / STOP recommendation for one treatment.

The act-now risk assessment for treatment vs control: what committing to either side costs in expectation, how confident the posterior is, and what one more round of data is worth. The treatment’s metric-native contrast draws are reduced to a per-draw mean lift over the scope’s visitors, then summarized under the legacy compare.variants decision rule (SHIP iff the expected loss and both probability gates clear their thresholds; else STOP on harm; else STOP on futility; else CONTINUE).

v0.2 raw scope: probabilities and expected losses are computed from the raw draws even on a calibrated posterior — interval corrections land where intervals are built, never here.

Parameters:

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

  • treatment (str) – Treatment variant name; selects contrast column observed.treatment_names.index(treatment).

  • segment (DiscoveredSegment | None) – None computes the global snapshot (per-draw mean over ALL visitors); a DiscoveredSegment restricts the mean to its rule’s members.

  • thresholds (DecisionThresholds | None) – Decision thresholds; DecisionThresholds() defaults when None.

  • min_practical_effect (float) – Minimum meaningful lift for probability_better / probability_harmful.

Return type:

RecommendationSummary

Returns:

RecommendationSummary with the decision, its decision-theoretic evidence, the thresholds used, and expected_value_of_one_more_round always populated (never NaN; closed-form preposterior EVSI documented in docs/concepts/decision-theoretic-inputs.md).

Raises:

  • ValueError – When posterior.observed is None; when treatment is not one of the observed treatment names; or when the segment’s rule matches zero visitors.

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