causalis.shared.srm

Sample Ratio Mismatch (SRM) utilities for randomized experiments.

This module provides a chi-square goodness-of-fit SRM check for randomized experiments. It accepts observed assignments as labels or aggregated counts and returns a compact result object with diagnostics.

Module Contents

Classes

SRMResult

Result of a Sample Ratio Mismatch (SRM) check.

Functions

check_srm

Check Sample Ratio Mismatch (SRM) for an RCT via a chi-square goodness-of-fit test.

Data

Number
__all__

API

causalis.shared.srm.Number

None

class causalis.shared.srm.SRMResult

Result of a Sample Ratio Mismatch (SRM) check.

Attributes

chi2 : float The calculated chi-square statistic. p_value : float The p-value of the test, rounded to 5 decimals. expected : dict[Hashable, float] Expected counts for each variant. observed : dict[Hashable, int] Observed counts for each variant. alpha : float Significance level used for the check. is_srm : bool True if an SRM was detected (chi-square p-value < alpha), False otherwise. warning : str or None Warning message if the test assumptions might be violated (e.g., small expected counts).

chi2: float

None

p_value: float

None

expected: Dict[Hashable, float]

None

observed: Dict[Hashable, int]

None

alpha: float

None

is_srm: bool

None

warning: str | None

None

__repr__() → str

causalis.shared.srm.check_srm(assignments: Union[Iterable[Hashable], pandas.Series, causalis.dgp.causaldata.CausalData, collections.abc.Mapping[Hashable, causalis.shared.srm.Number]], target_allocation: Dict[Hashable, causalis.shared.srm.Number], alpha: float = 0.001, min_expected: float = 5.0, strict_variants: bool = True) → causalis.shared.srm.SRMResult

Check Sample Ratio Mismatch (SRM) for an RCT via a chi-square goodness-of-fit test.

Parameters

assignments : Iterable[Hashable] or pandas.Series or CausalData or Mapping[Hashable, Number] Observed variant assignments. If iterable or Series, elements are labels per unit (user_id, session_id, etc.). If CausalData is provided, the treatment column is used. If a mapping is provided, it is treated as {variant: observed_count} with non-negative integer counts. target_allocation : dict[Hashable, Number] Mapping {variant: p} describing intended allocation as probabilities. alpha : float, default 1e-3 Significance level. Use strict values like 1e-3 or 1e-4 in production. min_expected : float, default 5.0 If any expected count < min_expected, a warning is attached. strict_variants : bool, default True - True: fail if observed variants differ from target keys. - False: drop unknown variants and test only on declared ones.

Returns

SRMResult The result of the SRM check.

Raises

ValueError If inputs are invalid or empty. ImportError If scipy is required but not installed.

Notes

• Target allocation probabilities must sum to 1 within numerical tolerance.

• is_srm is computed using the unrounded p-value; the returned p_value is rounded to 5 decimals.

• Missing assignments are dropped and reported via warning.

• Requires SciPy for p-value computation.

Examples

assignments = [“control”] * 50 + [“treatment”] * 50 check_srm(assignments, {“control”: 0.5, “treatment”: 0.5}, alpha=1e-3) SRMResult(status=no SRM, p_value=1.00000, chi2=0.0000)

counts = {“control”: 70, “treatment”: 30} check_srm(counts, {“control”: 0.5, “treatment”: 0.5}) SRMResult(status=SRM DETECTED, p_value=0.00006, chi2=16.0000)

causalis.shared.srm.__all__

[‘SRMResult’, ‘check_srm’]