[9] Tests for Rectangular Uniformity#

pysht.uniformity tests whether multivariate observations are uniform on a declared hyperrectangle. Bounds default to the unit hypercube and are treated as part of the null hypothesis, not estimated from the data.

Question

Function

Is the complete nearest-neighbor geometry compatible with uniformity?

ehy

Do squared interpoint distances have their uniform-null moments?

ym_interpoint

Do coordinatewise normal quantiles have mean zero?

ym_quantile

ehy implements the Ebner–Henze–Yukich statistic. Both alpha and n_neighbors are required because they affect power and must be fixed before testing. Here n_neighbors=J means that the score sums the contributions from each of the first \(J\) neighbors, not only the \(J\)th distance. The supported domain is \(\alpha>0\), \(\alpha\ne1\), and \(1\le J<n\). It rejects in the lower tail for \(0<\alpha<1\) and in the upper tail for \(\alpha>1\). Unlike the older Yang–Modarres interpoint routine, EHY is also defined for one-dimensional rectangles.

ym_interpoint provides the Yang–Modarres q1, q2, and q3 statistics. Parametric Monte Carlo calibration is the finite-sample default. The optional asymptotic calibration uses chi-square limits for q1 and q2; for q3, it uses the correlated-normal-square limit implied by the exact covariance of the two signed components. It does not reproduce the paper’s invalid independence approximation. Integer rng seeds reproduce the complete Monte Carlo calibration.

ym_quantile has an exact chi-square null after its transformation. It requires every observation to lie strictly inside the declared bounds: endpoints map to infinite normal quantiles and are rejected rather than clipped.

See the rectangular-uniformity validation ledger for the formulas, boundary policy, and calibration audit. See the method-specific EHY rectangular ledger for its primary equations and release gates.

Functions#

Goodness-of-fit tests for multivariate rectangular uniformity.

pysht.uniformity.ehy(x, *, alpha, n_neighbors, lower=None, upper=None, calibration='monte-carlo', n_resamples=9_999, rng=None)[source]#

Perform the EHY nearest-neighbor test of rectangular uniformity.

alpha and n_neighbors are scientifically consequential tuning parameters and therefore have no data-selected defaults. The paper’s statistic rejects in the lower tail for 0 < alpha < 1 and in the upper tail for alpha > 1. alpha=1 is rejected because its probability limit is distribution-free and cannot identify non-uniform alternatives.

Parameters:

  • x (ArrayLike)

  • alpha (float)

  • n_neighbors (int)

  • lower (ArrayLike | None)

  • upper (ArrayLike | None)

  • calibration (str)

  • n_resamples (int)

  • rng (int | integer | Generator | None)

Return type:

ResamplingTestResult

pysht.uniformity.ym_interpoint(x, *, statistic='q1', lower=None, upper=None, calibration='monte-carlo', n_resamples=9_999, rng=None)[source]#

Perform a Yang–Modarres interpoint-distance uniformity test.

Parameters:
x

An (n, d) matrix with n >= 2 and d >= 2. Rows are observations.

statistic

"q1" tests the mean squared interpoint distance, "q2" tests its centered second moment, and "q3" sums the two standardized components.

lower, upper

Finite length-d support bounds. Defaults are zero and one in every coordinate. Observations may lie on the boundary.

calibration

"monte-carlo" (the default) simulates the finite-sample null. "asymptotic" uses the paper’s one-component chi-square limits for "q1" and "q2". For "q3" it uses the correlated-square limit implied by the exact nonzero covariance of those components; it does not use the paper’s invalid independence approximation.

n_resamples

Positive number of simulated uniform samples for Monte Carlo calibration.

rng

None, an integer seed, or a NumPy generator. It never affects NumPy’s global random state.

Parameters:

  • x (ArrayLike)

  • statistic (str)

  • lower (ArrayLike | None)

  • upper (ArrayLike | None)

  • calibration (str)

  • n_resamples (int)

  • rng (int | integer | Generator | None)

Return type:

HypothesisTestResult | ResamplingTestResult

Notes

The one-component chi-square calibrations follow the U-process limits in Yang and Modarres (2017). For q3, the two signed standardized components are not independent: pySHT uses their exact null covariance in the corresponding correlated-normal-square approximation instead of the paper’s anti-conservative chi-square approximation. Monte Carlo remains the authoritative finite-sample default for all variants.

References

Yang, M. and Modarres, R. (2017). Multivariate tests of uniformity. Statistical Papers, 58, 627–639.

pysht.uniformity.ym_quantile(x, *, lower=None, upper=None)[source]#

Perform the Yang–Modarres normal-quantile uniformity test.

Every observation must lie strictly inside its declared bounds because a boundary point maps to an infinite normal quantile. Under rectangular uniformity, coordinatewise normal quantiles have mean zero and the statistic Cn = n ||mean(Z)||^2 has a chi-square distribution with d degrees of freedom.

References

Yang, M. and Modarres, R. (2017). Multivariate tests of uniformity. Statistical Papers, 58, 627–639.

Parameters:

  • x (ArrayLike)

  • lower (ArrayLike | None)

  • upper (ArrayLike | None)

Return type:

HypothesisTestResult