[7] Tests for Equality of Distributions#

pysht.equaldist contains tests whose null hypothesis concerns the complete data-generating distribution rather than a single parameter such as a mean or variance.

The current public function is bg_2samp. It supports exact or corrected Monte Carlo permutation calibration; the unverified legacy asymptotic calibration is not exposed.

See the validation record for the formula, exchangeability assumptions, tie handling, numerical normalization, and independent exact-enumeration checks.

Functions#

Tests for equality of two probability distributions.

This module currently provides the distance-based two-sample test of Biswas and Ghosh (2014). Only permutation calibration is exposed: the asymptotic variance estimator in the legacy SHT implementation is order-dependent and is therefore not used as a correctness oracle here.

pysht.equaldist.bg_2samp(x, y, *, calibration='permutation', n_resamples=9_999, rng=None)[source]#

Test whether two univariate or multivariate distributions are equal.

The Biswas-Ghosh statistic compares the average within-sample and between-sample Euclidean distances. Its permutation calibration is exact under exchangeability when all labelings are enumerated; this implementation uses Monte Carlo label permutations and the nonzero correction (exceedances + 1) / (n_resamples + 1).

Parameters:
x, y

Independent samples. One-dimensional inputs represent univariate data; two-dimensional inputs use rows for observations and columns for features. The samples must have the same number of features and at least two observations each.

calibration

"permutation" (the default) automatically enumerates all labelings when their count does not exceed n_resamples and otherwise uses Monte Carlo permutations. Use "exact" to require enumeration or "monte-carlo" to require sampling. No asymptotic selector is exposed because the legacy variance calculation is not row-order invariant.

n_resamples

Monte Carlo sample size and computational budget for exact enumeration. Must be a positive integer.

rng

None, an integer seed, or a numpy.random.Generator. Exact enumeration validates but does not consume the generator.

Returns
——-
DistanceTestResult

An immutable result whose string form follows R’s htest display.

Parameters:

  • x (ArrayLike)

  • y (ArrayLike)

  • calibration (str)

  • n_resamples (int)

  • rng (int | integer | Generator | None)

Return type:

DistanceTestResult

Notes

The permutation null requires exchangeability of the pooled observations. A fixed integer seed gives identical results after reordering rows or swapping the two samples. Calibration uses coordinates and distances divided by positive common scales. This leaves the permutation ordering unchanged in exact arithmetic and prevents scale-dependent overflow and underflow. result.statistic remains the raw statistic from the paper; the dimensionless value and maximum-distance scale are retained as result.normalized_statistic and result.distance_scale. The raw statistic may be zero or infinite when its scale lies outside float64, while the normalized calibration remains valid. Numerically tied permutation statistics are included in the upper tail using a relative tolerance of 100 double-precision epsilons. For Monte Carlo calibration, the reported standard error estimates the conditional standard deviation of the corrected estimator using q_hat = exceedances / B. A 95 percent Clopper–Pearson interval records uncertainty in the underlying permutation tail probability.

References

Biswas, M. and Ghosh, A. K. (2014). A nonparametric two-sample test applicable to high dimensional data. Journal of Multivariate Analysis, 123, 160-171. https://doi.org/10.1016/j.jmva.2013.09.004