[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

Do squared interpoint distances have their uniform-null moments?

ym_interpoint

Do coordinatewise normal quantiles have mean zero?

ym_quantile

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.

Functions#

Goodness-of-fit tests for multivariate rectangular uniformity.

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