perm_test

perm_test(y_obs, z_obs, alloc, *, contrast=(1.0, -1.0), tau=0.0, method='mean', alternative='two-sided', exact=False)[source]

Fisher randomization test of a sharp null hypothesis.

For two groups the null is c_1 Y_i(1) + c_2 Y_i(2) = tau for every unit. Both coefficients must be nonzero. Under this null the missing potential outcomes are imputed from the observed ones, and the statistic sum_g c_g * mean_g (of outcomes, or of their ranks) is recomputed for each assignment in alloc. Two-sided p-values measure distance from tau. With more than two groups, only the sharp null of identical potential outcomes in every group is supported: tau=0 and coefficients summing to zero. A single contrast constraint does not identify the missing potential outcomes in that case.

Rank statistics are supported only under the no-effect null (tau=0 and coefficients summing to zero). For a nonzero effect, outcome units and rank units cannot be used interchangeably.

Parameters:

  • y_obs (np.ndarray) – Observed outcome per unit.

  • z_obs (np.ndarray) – Observed group label per unit.

  • alloc (np.ndarray) – Reference assignments, one row per assignment. By default, supply independent draws from the design that produced z_obs; do not prepend the observed assignment. Random draws that happen to match it are retained. With exact=True, supply the full equally weighted assignment distribution, including z_obs.

  • contrast (Sequence[float]) – Coefficient for each group, in sorted label order.

  • tau (float) – Value of the contrast under the sharp null.

  • method (Literal['mean', 'rank']) – Use outcomes ("mean") or their ranks ("rank").

  • alternative (Literal['two-sided', 'greater', 'less']) – Direction of the alternative hypothesis.

  • exact (bool) – If True, return the fraction of reference statistics at least as extreme. Otherwise use (b + 1) / (B + 1), where b of B sampled statistics are at least as extreme, to include the observed statistic and avoid zero Monte Carlo p-values.

Returns:

The observed statistic, the reference statistics and the p-value.

Raises:

ValueError – If inputs are invalid or the null is unsupported.

Return type:

PermTestResult