Diagnostics and robustness
sample_ratio_mismatch
Section titled “sample_ratio_mismatch”sample_ratio_mismatch(counts, expected, alpha, inference, grain, unit_counts)Detect allocation sample-ratio mismatch with fixed or anytime-valid evidence.
inference="always_valid" (default) evaluates the exact
uniform-Dirichlet mixture e-process against the normalized expected
allocation and alarms when its log evidence reaches -log(alpha).
The time-uniform guarantee needs cumulative prefixes with the same
known conditional arm probabilities at every assignment; static
marginal shares alone do not suffice, and blocked, adaptive,
dependent, quota, exact-balance, without-replacement, and ramped or
reset assignment streams are unsupported (independently assigned
clusters satisfy the contract at cluster grain). log_e_value is
stateless and may decrease, since this result retains no historical
maximum.
inference="fixed" uses the ordinary Pearson chi-square p-value
for one predeclared look or a caller-managed scheduled-look alpha
budget; without expected it falls back to equal observed-arm
shares and log_e_value is unavailable.
Apply to all assigned or targeted units, or to a demonstrably pre-treatment, arm-invariant exposure - a treatment-affected triggered subset is selection or telemetry evidence, not evidence that randomization failed.
counts’ "(unassigned)"/"(mixed assignment)" accounting
keys are split out and never treated as arms. expected is
required for always_valid; its keys declare the arms, and
missing observed arms receive zero counts. unit_counts is
descriptive per-arm context for a cluster-grain test, never a
second allocation sample.
allocation_posterior_bands
Section titled “allocation_posterior_bands”allocation_posterior_bands(counts, credible_level, prior)Compute per-arm Beta posterior credible bands on allocation share.
counts carries ds/group_id/n_cumulative (the shape
daily_exposure_counts produces, minus experiment_id/
n_daily); accepts any narwhals-supported frame or an iterable
of row mappings. prior is the Beta(a, b) prior on each
arm’s share (default uniform); both parameters must be finite and
positive.
Every ds is pooled across all arms present to compute that
day’s n_total - rows spanning more than one experiment_id
raise ValueError, since silently mixing experiments sharing a
date would inflate the total and produce spuriously narrow, wrong
bands. Returns one band per input row, in input order.
absorb_factor
Section titled “absorb_factor”absorb_factor(summary, factor, control_group, pooling, alpha)Absorb factor and return the sharpened average treatment effect.
Parameters
Section titled “Parameters”summary : IntoDataFrame
group_summary-shaped table, one row per factor level x arm,
carrying factor plus group_id, n, ref_y, cy1, cy2.
factor : str
Name of the factor-level column.
control_group : str
Which group_id is the control arm.
pooling : {“partial”, “hard”, “none”}
Passed through; prefer the default.
alpha : float
Two-sided significance level.
Returns
Section titled “Returns”AbsorptionResult Effect on the absolute scale, with a level-clustered interval.
Raises
Section titled “Raises”ValueError If required columns are missing, the control group is absent, or the table does not describe exactly two arms.
RuntimeWarning
Below 40 levels survive absorption — see _check_level_count.
absorb_one_way takes raw sum(y)/sum(y**2) per cell, so centered
moments are re-expressed against one global reference (the
count-weighted pooled mean) instead of raw sums. This is exact: the
model y = mu + tau*D + b_g + e is invariant to a location shift of
y - only the intercept moves, so no field on AbsorptionResult
reports an absolute level (effect is a contrast; se/icc/
mean_shrinkage are all shift-invariant).