MinSampleSize

class hypex.executor.MinSampleSize(grouping_role=None, key='', *, mde, power=0.2, quantile_1=None, quantile_2=None, initial_estimate=0, power_iteration_size=3000, alpha=0.05, iteration_size=5000, equal_variance=False, random_state=42, variances=None)[source]

Bases: Calculator

A calculator for estimating the minimum required sample size for multi-group comparisons.

This class estimates the minimum per-group sample size needed to achieve a desired statistical power for detecting a specified minimum detectable effect (MDE) when comparing multiple groups (e.g., control vs one or more test groups). Quantiles used in the calculation can be provided explicitly or estimated internally using MultitestQuantile.

The calculator supports both:

  • Equal-variance mode (equal_variance=True): closed-form sample size approximation based on a pooled/assumed common variance.

  • Unequal-variance mode (equal_variance=False): simulation-based sample size search that accounts for different variances across groups.

Parameters:

  • grouping_role (ABCRole | None, optional) – Role used to locate the grouping (treatment) field in the dataset. If not provided, defaults to TreatmentRole().

  • key (Any, optional) – Key used by the base Calculator for storing results. Defaults to “”.

  • mde (float) – Minimum Detectable Effect (absolute effect size in the same units as the target metric) to be detected.

  • power (float, optional) – Power-related quantile level used in the internal quantile computation (kept consistent with the original function implementation). Defaults to 0.2.

  • quantile_1 (float | list[float] | None, optional) – Precomputed critical quantile(s) for the multiple testing threshold. If a float is provided, it is broadcast to all groups. If None, computed via MultitestQuantile.quantile_of_marginal_distribution. Defaults to None.

  • quantile_2 (float | list[float] | None, optional) – Precomputed quantile(s) used for power calibration. If a float is provided, it is broadcast to all groups. If None, computed via MultitestQuantile.quantile_of_marginal_distribution. Defaults to None.

  • initial_estimate (int, optional) – Starting sample size guess (used only when equal_variance=False). Defaults to 0.

  • power_iteration_size (int, optional) – Number of Monte Carlo iterations used to estimate achieved power during the sample size search (equal_variance=False). Defaults to 3000.

  • alpha (float, optional) – Significance level used in multiple testing quantile computation. Defaults to 0.05.

  • iteration_size (int, optional) – Internal iteration size for MultitestQuantile quantile estimation. Defaults to 5000.

  • equal_variance (bool, optional) – If True, uses the equal-variance closed-form approximation. If False, uses the unequal-variance simulation-based search. Defaults to False.

  • random_state (int | None, optional) – Random seed for reproducibility of Monte Carlo simulation and quantile estimation. Defaults to 42.

  • variances (list[float] | float | None, optional) –

    Variance specification. If provided: - when equal_variance=True, may be a single float (common variance) or a list (first/pooled

    usage depends on implementation).

    • when equal_variance=False, must be a list of variances per group (order matching grouping).

    If None, variances are estimated from the grouped data for each target metric. Defaults to None.

Examples

ds = Dataset(
    data="data.csv",
    roles={
        "user_id": InfoRole(int),
        "treat": TreatmentRole(),
        "pre_spends": TargetRole(),
        "post_spends": TargetRole(),
    },
)

mss = MinSampleSize(mde=10.0, alpha=0.05, equal_variance=True)
result = mss.calc(data=ds)