mixle.inference.resampling module

Bootstrap and permutation inference for arbitrary statistics.

Honest uncertainty without distributional assumptions, by resampling the data itself:

  • bootstrap() – a confidence interval for any statistic T(data), with the resampling scheme matched to the data’s dependence structure: plain i.i.d., stratified (resample within groups), cluster/hierarchical (resample whole clusters – the unit of independence), moving block (preserve autocorrelation in a series), or m-out-of-n subsampling. Interval types: percentile, basic (pivotal), and bca (bias-corrected and accelerated – the second-order-accurate default for i.i.d. data).

  • wild_bootstrap() – residual bootstrap for regression that is robust to heteroscedasticity (Rademacher or Mammen two-point multipliers on the residuals).

  • permutation_test() – an exact/Monte-Carlo test for an arbitrary statistic under a sharp null, with stratified / restricted (within-group) shuffling and a paired (sign-flip) mode; when the number of distinct rearrangements is small it enumerates them for an exact p-value.

Everything is pure NumPy. data may be a single array (resampled along axis 0) or a tuple of arrays sharing their first axis (e.g. (X, y)); the statistic is then called as statistic(*parts).

class BootstrapResult(estimate, ci_low, ci_high, distribution, method, ci_level, standard_error)[source]

Bases: object

Result of a bootstrap() call.

Parameters:
estimate

the statistic on the original data (scalar or vector).

Type:

numpy.ndarray

ci_low / ci_high

confidence-interval endpoints (same shape as estimate).

distribution

(n_boot, ...) array of bootstrap replicates.

Type:

numpy.ndarray

method

the interval method used.

Type:

str

ci_level

the central probability of the interval.

Type:

float

standard_error

bootstrap standard error (std of the replicates).

Type:

numpy.ndarray

estimate: ndarray
ci_low: ndarray
ci_high: ndarray
distribution: ndarray
method: str
ci_level: float
standard_error: ndarray
bootstrap(data, statistic, *, n_boot=2000, method='bca', ci_level=0.95, seed=0, groups=None, clusters=None, block_length=None, m=None)[source]

Bootstrap confidence interval for statistic(data).

Parameters:

  • data (Any) – a single array (resampled along axis 0) or a tuple of arrays sharing their first axis (the statistic is then called as statistic(*parts)).

  • statistic (Callable[[...], Any]) – maps the data to a scalar or fixed-length vector.

  • n_boot (int) – number of bootstrap resamples.

  • method (str) – "percentile", "basic" (pivotal), or "bca" (bias-corrected & accelerated). "bca" is only second-order accurate for plain i.i.d. resampling; with groups / clusters / block_length / m set it falls back to "percentile".

  • ci_level (float) – central probability of the interval.

  • seed (int | RandomState | None) – RNG seed.

  • groups (ndarray | None) – (n,) labels for stratified resampling (resample within each group).

  • clusters (ndarray | None) – (n,) labels for cluster resampling (resample whole clusters with replacement).

  • block_length (int | None) – moving-block length for serially dependent (time-series) data.

  • m (int | None) – subsample size for m-out-of-n subsampling (without replacement).

Returns:

A BootstrapResult.

Return type:

BootstrapResult

block_bootstrap(data, statistic, block_length, *, n_boot=2000, ci_level=0.95, seed=0)[source]

Moving-block bootstrap for serially dependent (time-series) data.

Convenience wrapper over bootstrap() with block_length set: resamples contiguous blocks so within-block autocorrelation is preserved. Choose block_length on the order of the series’ correlation length.

Parameters:
Return type:

BootstrapResult

wild_bootstrap(fitted, residuals, statistic, *, n_boot=2000, kind='rademacher', ci_level=0.95, seed=0)[source]

Wild (residual-multiplier) bootstrap, robust to heteroscedasticity.

Builds synthetic responses y* = fitted + residual * v where v are mean-zero, unit-variance two-point multipliers drawn independently per observation, then recomputes the statistic on each y*. Because each residual keeps its own magnitude, the procedure preserves heteroscedasticity that an i.i.d. residual resample would destroy.

Parameters:

  • fitted (ndarray) – (n,) fitted values from the model.

  • residuals (ndarray) – (n,) residuals y - fitted.

  • statistic (Callable[[ndarray], Any]) – maps a synthetic response vector y* to a scalar or vector (e.g. refit and return coefficients).

  • n_boot (int) – number of resamples.

  • kind (str) – "rademacher" (v in {-1, +1}) or "mammen" (Mammen’s two-point distribution).

  • ci_level (float) – central probability of the percentile interval.

  • seed (int | RandomState | None) – RNG seed.

Returns:

A BootstrapResult (percentile interval).

Return type:

BootstrapResult

class PermutationResult(statistic, pvalue, null_distribution, n_perm, exact, alternative)[source]

Bases: object

Result of a permutation_test().

Parameters:
statistic

the observed test statistic.

Type:

float

pvalue

the (one- or two-sided) p-value.

Type:

float

null_distribution

the statistic under each sampled/enumerated rearrangement.

Type:

numpy.ndarray

n_perm

number of rearrangements used.

Type:

int

exact

True if the full permutation set was enumerated.

Type:

bool

alternative

the alternative hypothesis.

Type:

str

statistic: float
pvalue: float
null_distribution: ndarray
n_perm: int
exact: bool
alternative: str
permutation_test(x, y, *, statistic=None, n_perm=10000, alternative='two-sided', paired=False, stratify=None, seed=0, exact_max=10000)[source]

Two-sample permutation test for an arbitrary statistic under a sharp null.

Under the null that the two samples are exchangeable, the labels can be shuffled freely; the statistic’s permutation distribution is the reference. For two-sided the statistic is centered at zero by construction (difference statistics) and compared on absolute value.

Parameters:

  • x (ndarray) – the two samples (1-D). For paired=True they must have equal length and pairing is preserved by sign-flipping the within-pair differences.

  • y (ndarray) – the two samples (1-D). For paired=True they must have equal length and pairing is preserved by sign-flipping the within-pair differences.

  • statistic (Callable[[ndarray, ndarray], float] | None) – f(x, y) -> float; defaults to the difference in means. For paired it is applied to (differences, zeros) so the default reduces to the mean paired difference.

  • n_perm (int) – number of random rearrangements (ignored if the exact set is enumerated).

  • alternative (str) – "two-sided", "greater", or "less".

  • paired (bool) – paired (sign-flip) permutation instead of label shuffling.

  • stratify (ndarray | None) – (n,) group labels (concatenated x-then-y) for restricted permutation – labels are shuffled only within each group, preserving group structure.

  • seed (int | RandomState | None) – RNG seed.

  • exact_max (int) – if the number of distinct rearrangements is <= exact_max they are enumerated for an exact p-value.

Returns:

A PermutationResult.

Return type:

PermutationResult