mojolearn.resample#

Resampling statistics: bootstrap intervals, permutation tests, Monte Carlo integration and scikit-learn style row resampling.

The public functions are bootstrap(), permutation_test(), monte_carlo_integrate(), resample() and resample_indices(). Their parameters mean what SciPy’s (or scikit-learn’s) parameters of the same name mean. The random draws and the per-replicate statistics run on the device, one block per replicate; the point estimate, interval, standard error and p-value are then computed from those replicates in compiled code.

Inputs are converted to float32. Unknown statistic, method, alternative or integrand names raise ValueError, as does a sample that is not 1-D or 2-D, a non-finite value, a confidence_level outside (0, 1), a statistic that reads a column the sample does not have, 'std' on fewer than two rows, or an n_resamples too large to address.

r_first (and i_first for Monte Carlo) selects where a run starts in the replicate stream: replicates [r_first, r_first + n_resamples) are bit-identical to the same slice of one whole run, so a long run can be split into batches.

Every function takes numeric_mode ('identical', 'deterministic', or 'fast' on Apple); None uses the package default.

Examples

>>> import numpy as np, mojolearn
>>> x = np.random.default_rng(0).random(1000, dtype=np.float32)
>>> res = mojolearn.resample.bootstrap(x, statistic="mean", n_resamples=999)
>>> low, high = res.confidence_interval

Module Attributes

STATISTICS

Statistic names accepted by bootstrap() and permutation_test(), with their integer codes.

METHODS

Confidence-interval methods accepted by bootstrap() (method is case-insensitive).

ALTERNATIVES

Alternative hypotheses accepted by bootstrap() and permutation_test().

INTEGRANDS

Integrands accepted by monte_carlo_integrate().

Functions

bootstrap(data[, statistic, n_resamples, ...])

Bootstrap confidence interval for a statistic.

permutation_test(x[, y, statistic, ...])

Permutation test of a statistic.

monte_carlo_integrate(integrand, lower, ...)

Monte Carlo estimate of a 2-D integral over a box.

resample(*arrays[, replace, n_samples, ...])

Resample arrays consistently along the first axis.

resample_indices(n[, n_samples, replace, ...])

Row indices for a scikit-learn style resample.

Classes

BootstrapResult(point_estimate, ...)

Result of bootstrap(), SciPy's BootstrapResult with extra fields.

PermutationTestResult(statistic, ...)

Result of permutation_test(), SciPy's PermutationTestResult with extra fields.

MonteCarloResult(integral, mean, volume, ...)

Result of monte_carlo_integrate().
mojolearn.resample.bootstrap(data, statistic='mean', n_resamples=9999, confidence_level=0.95, method='percentile', alternative='two-sided', random_state=0, q_or_prop=0.5, r_first=0, numeric_mode=None, paired=True)[source]#

Bootstrap confidence interval for a statistic.

Follows scipy.stats.bootstrap((data,), statistic, n_resamples=..., rng=random_state, method=..., confidence_level=..., alternative=...). The statistic is chosen by name from a compiled set rather than passed as a callable. The resampling and the per-replicate statistic run on the device.

Parameters:

  • data (array-like of shape (n,) or (n, 2), or a pair (x, y)) – The sample, converted to float32. A two-column sample keeps its row pairing (SciPy’s paired=True), which 'pearson' and 'diff_means' read. With paired=False, a pair of 1-D samples of any lengths.

  • statistic (str or int, default=’mean’) – 'mean', 'std', 'quantile', 'pearson', 'diff_means' or 'trimmed_mean', or its code in STATISTICS.

  • n_resamples (int, default=9999) – Number of bootstrap replicates.

  • confidence_level (float, default=0.95) – Confidence level of the interval, in (0, 1).

  • method ({‘percentile’, ‘basic’, ‘BCa’}, default=’percentile’) – Interval method, case-insensitive as in SciPy. 'BCa' is available for 'mean', 'std' and 'diff_means' and raises ValueError for the other statistics or a degenerate interval.

  • alternative ({‘two-sided’, ‘less’, ‘greater’}, default=’two-sided’) – Which side(s) of the interval to bound.

  • random_state (int, default=0) – Seed of the replicate stream.

  • q_or_prop (float, default=0.5) – q for 'quantile' and proportiontocut for 'trimmed_mean'; ignored otherwise.

  • r_first (int, default=0) – Index of the first replicate. Replicates [r_first, r_first + n_resamples) equal the same slice of one whole run, bit for bit.

  • numeric_mode ({‘identical’, ‘deterministic’, ‘fast’} or None, default=None) – Numeric mode ('fast' is Apple only); None uses the package default.

  • paired (bool, default=True) – False with data=(x, y) and statistic='diff_means' runs SciPy’s unpaired two-sample bootstrap, each sample resampled independently; any other statistic raises ValueError. A single sample ignores paired, as SciPy does.

Returns:

BootstrapResult

Raises:

  • ValueError – For an unknown name, a sample that is not 1-D or 2-D, a non-finite value, a confidence_level outside (0, 1), 'std' on fewer than two rows, or an unsupported method / statistic combination.

  • TypeError – For a parameter of the wrong type.

Examples

>>> import numpy as np, mojolearn
>>> x = np.random.default_rng(0).random(1000, dtype=np.float32)
>>> res = mojolearn.resample.bootstrap(x, statistic="mean", method="BCa")
>>> low, high = res.confidence_interval
mojolearn.resample.permutation_test(x, y=None, statistic='diff_means', n_resamples=9999, alternative='two-sided', random_state=0, r_first=0, numeric_mode=None, permutation_type='independent')[source]#

Permutation test of a statistic.

Follows scipy.stats.permutation_test((x, y), statistic, permutation_type=..., n_resamples=..., rng=random_state, alternative=...), with the statistic chosen by name. Unlike SciPy, the null distribution is always sampled with n_resamples permutations, never enumerated exhaustively; the p-value is conservative.

Parameters:

  • x (array-like of shape (n_x,)) – First sample, converted to float32.

  • y (array-like of shape (n_y,) or None, default=None) – Second sample. Required for permutation_type='independent'. With 'samples', y is the paired second sample, or None for a one-sample sign-flip test.

  • statistic (str or int, default=’diff_means’) – The statistic, by name or by its code in STATISTICS. With permutation_type='samples' it must be 'diff_means' for two paired samples and 'mean' for one sample.

  • n_resamples (int, default=9999) – Number of permutations.

  • alternative ({‘two-sided’, ‘less’, ‘greater’}, default=’two-sided’) – The alternative hypothesis.

  • random_state (int, default=0) – Seed of the permutation stream.

  • r_first (int, default=0) – Index of the first permutation; a slice of permutations equals the same slice of one whole run, bit for bit.

  • numeric_mode ({‘identical’, ‘deterministic’, ‘fast’} or None, default=None) – Numeric mode ('fast' is Apple only); None uses the package default.

  • permutation_type ({‘independent’, ‘samples’}, default=’independent’) – 'independent' reassigns pooled observations between x and y. 'samples' swaps the two observations of each pair at random (two paired samples), or flips the sign of each observation (one sample), as in SciPy. 'pairings' raises ValueError.

Returns:

PermutationTestResult

Raises:

ValueError – For an unknown name, a missing y, a refused permutation_type or statistic combination, or a non-finite value.

Examples

>>> import numpy as np, mojolearn
>>> rng = np.random.default_rng(0)
>>> x = rng.random(200, dtype=np.float32)
>>> y = rng.random(300, dtype=np.float32) + 0.1
>>> res = mojolearn.resample.permutation_test(x, y, n_resamples=999)
>>> res.pvalue
mojolearn.resample.monte_carlo_integrate(integrand, lower, upper, n_samples, random_state=0, i_first=0, numeric_mode=None)[source]#

Monte Carlo estimate of a 2-D integral over a box.

Computes volume * mean(f(x_i)) over n_samples uniform draws from the two-dimensional box [lower, upper). The exact value of the same integral is returned beside the estimate.

Parameters:

  • integrand ({‘const’, ‘sum’, ‘product’} or int) – 'const' (f = 1), 'sum' (x0 + x1) or 'product' (x0 * x1), or its code in INTEGRANDS.

  • lower, upper (sequence of 2 floats) – Lower and upper corners of the box; ValueError if either does not hold exactly two values.

  • n_samples (int) – Number of uniform draws.

  • random_state (int, default=0) – Seed of the draw stream.

  • i_first (int, default=0) – Index of the first draw, so a long run can be split into batches.

  • numeric_mode ({‘identical’, ‘deterministic’, ‘fast’} or None, default=None) – Numeric mode ('fast' is Apple only); None uses the package default.

Returns:

MonteCarloResult

Examples

>>> import mojolearn
>>> res = mojolearn.resample.monte_carlo_integrate("product", [0, 0], [1, 2], 100000)
>>> round(res.closed_form, 6)
1.0
mojolearn.resample.resample(*arrays, replace=True, n_samples=None, random_state=0, stratify=None, sample_weight=None, numeric_mode=None)[source]#

Resample arrays consistently along the first axis.

Follows sklearn.utils.resample(*arrays, replace=..., n_samples=..., random_state=...): every array is indexed by the same rows, from resample_indices(). One array returns the resampled array, several return a list, as in scikit-learn. The rows drawn differ from scikit-learn’s for the same random_state.

Parameters:

  • *arrays (sequence of array-like) – Arrays with the same first dimension. NumPy arrays are indexed as arrays; other sequences return lists.

  • replace (bool, default=True) – Draw with replacement.

  • n_samples (int or None, default=None) – Number of rows to draw; None means the length of the arrays. With replace=False it must be at most that length.

  • random_state (int, default=0) – Seed.

  • stratify (None) – Not supported; any other value raises ValueError.

  • sample_weight (None) – Not supported; any other value raises ValueError.

  • numeric_mode ({‘identical’, ‘deterministic’, ‘fast’} or None, default=None) – Numeric mode ('fast' is Apple only); None uses the package default.

Returns:

array or list of arrays – None when no arrays are given.

Raises:

ValueError – If the arrays have different lengths, or stratify or sample_weight is given.

Examples

>>> import numpy as np, mojolearn
>>> X = np.random.default_rng(0).random((1000, 8), dtype=np.float32)
>>> y = np.arange(1000, dtype=np.float32)
>>> Xb, yb = mojolearn.resample.resample(X, y, n_samples=500)
mojolearn.resample.resample_indices(n, n_samples=None, replace=True, random_state=0, numeric_mode=None)[source]#

Row indices for a scikit-learn style resample.

Returns the indices resample() gathers. With replace=True each position draws a row independently; with replace=False the result is the first n_samples entries of a random permutation of range(n). The draw is integer only, so the same seed gives the same indices on every device. The indices differ from scikit-learn’s for the same random_state.

Parameters:

  • n (int) – Number of rows to draw from.

  • n_samples (int or None, default=None) – Number of indices; None means n. With replace=False it must be at most n.

  • replace (bool, default=True) – Draw with replacement.

  • random_state (int, default=0) – Seed.

  • numeric_mode ({‘identical’, ‘deterministic’, ‘fast’} or None, default=None) – Numeric mode ('fast' is Apple only); None uses the package default.

Returns:

Array of int32, shape (n_samples,)

Examples

>>> import mojolearn
>>> idx = mojolearn.resample.resample_indices(1000, n_samples=100, replace=False)
class mojolearn.resample.BootstrapResult(point_estimate, distribution, sorted_distribution, standard_error, low, high, order_low, order_high)[source]#

Bases: object

Result of bootstrap(), SciPy’s BootstrapResult with extra fields.

Variables:

  • point_estimate (float) – The statistic on the original sample.

  • distribution (Array of float32, shape (n_resamples,)) – The bootstrap replicates, in replicate order.

  • sorted_distribution (Array of float32, shape (n_resamples,)) – The same replicates sorted ascending.

  • standard_error (float) – Standard deviation of the bootstrap distribution.

  • confidence_interval (ConfidenceInterval) – (low, high); also available as .low and .high.

  • order_high (order_low,) – Positions in sorted_distribution used for the interval ends (for method='BCa', the positions at its adjusted levels).

class mojolearn.resample.PermutationTestResult(statistic, null_distribution, pvalue, count_less, count_greater)[source]#

Bases: object

Result of permutation_test(), SciPy’s PermutationTestResult with extra fields.

Variables:

  • statistic (float) – The statistic on the observed samples.

  • null_distribution (Array of float32, shape (n_resamples,)) – The statistic on each permutation.

  • pvalue (float) – The p-value for the requested alternative.

  • count_greater (count_less,) – The two counts the p-value was computed from: null values on the low side and on the high side of the observed statistic.

class mojolearn.resample.MonteCarloResult(integral, mean, volume, closed_form)[source]#

Bases: object

Result of monte_carlo_integrate().

Variables:

  • integral (float) – The estimate, volume * mean.

  • mean (float) – Mean of the integrand over the draws.

  • volume (float) – Area of the integration box.

  • closed_form (float) – The exact integral of the same integrand over the same box, so the estimate’s error can be read without a second call.

mojolearn.resample.STATISTICS = {'diff_means': 4, 'mean': 0, 'pearson': 3, 'quantile': 2, 'std': 1, 'trimmed_mean': 5}#

Statistic names accepted by bootstrap() and permutation_test(), with their integer codes.

mojolearn.resample.METHODS = {'basic': 1, 'bca': 2, 'percentile': 0}#

Confidence-interval methods accepted by bootstrap() (method is case-insensitive).

mojolearn.resample.ALTERNATIVES = {'greater': 2, 'less': 1, 'two-sided': 0}#

Alternative hypotheses accepted by bootstrap() and permutation_test().

mojolearn.resample.INTEGRANDS = {'const': 0, 'product': 2, 'sum': 1}#

Integrands accepted by monte_carlo_integrate().