[8] Tests for Normality#
pysht.normality provides five univariate and two multivariate
goodness-of-fit procedures. Every function tests a composite normal null;
location, scale, and (for multivariate samples) covariance are not specified.
Procedure |
Function |
Authoritative calibration |
|---|---|---|
Shapiro–Wilk |
|
Royston approximation |
Shapiro–Francia |
|
Royston approximation |
Jarque–Bera |
|
Monte Carlo normal null |
Adjusted Jarque–Bera |
|
Monte Carlo normal null |
Robust Jarque–Bera |
|
Monte Carlo normal null |
Henze–Zirkler |
|
Monte Carlo normal null with refitting |
Energy |
|
Monte Carlo normal null with refitting |
The three moment tests default to calibration="monte-carlo". Pass an integer
to rng for a replayable result. Their calibration="asymptotic" option is an
explicit chi-square approximation, not a finite-sample guarantee.
Constant samples are outside the domain of every normality statistic. The Shapiro procedures also enforce the sample-size ranges over which their p-value approximations are supported.
The multivariate functions require a two-dimensional sample with more rows than columns and positive-definite sample covariance. They re-estimate the mean and covariance in every simulated null sample. Thus their Monte Carlo calibration tests the intended composite null rather than a known-parameter standard-normal null. Henze–Zirkler uses maximum-likelihood covariance scaling; the energy procedure uses the ordinary sample covariance, matching the published procedure and its authors’ reference implementation.
See the normality validation ledger for formulas, null-size audits, Monte Carlo semantics, and deliberate corrections to SHT. The native multivariate additions have separate ledgers for Henze–Zirkler and energy normality.
Functions#
Univariate goodness-of-fit tests for a normal distribution.
All procedures test the composite null that a finite real sample comes from some normal distribution. The implementations are location- and scale-invariant, reject constant samples explicitly, and never use NumPy’s global random state.
- pysht.normality.adjusted_jarque_bera(x, *, calibration='monte-carlo', n_resamples=9_999, rng=None)[source]#
Perform Urzúa’s finite-sample adjusted Jarque–Bera test.
- Parameters:
- x
One-dimensional sample with at least four finite real observations.
- calibration
"monte-carlo"(the default) or"asymptotic".- n_resamples
Positive number of simulated normal samples for Monte Carlo calibration.
- rng
None, an integer seed, or a NumPy generator.
- Parameters:
x (ArrayLike)
calibration (str)
n_resamples (int)
rng (int | integer | Generator | None)
- Return type:
Notes
The statistic centers kurtosis at its exact normal-sample expectation and scales skewness and kurtosis by their exact normal-sample variances. A sample size of at least four is required. Monte Carlo calibration uses the corrected p-value
(b + 1) / (B + 1).References
Urzúa, C. M. (1996). On the correct use of omnibus tests for normality. Economics Letters, 53, 247–251.
- pysht.normality.energy(x, *, calibration='monte-carlo', n_resamples=9_999, rng=None)[source]#
Perform the energy test of multivariate normality (2005).
The statistic compares the empirical distribution of affine-standardized residuals with the standard multivariate normal distribution. Its two population expectation terms are evaluated analytically; calibration simulates and refits the complete composite-null procedure.
With exactly
n = p + 1observations the fitted geometry is constant: every null statistic ties, and the p-value is 1. This boundary case has no power against nonnormal alternatives and is flagged in diagnostics.- Parameters:
x (ArrayLike)
calibration (str)
n_resamples (int)
rng (int | integer | Generator | None)
- Return type:
- pysht.normality.henze_zirkler(x, *, calibration='monte-carlo', n_resamples=9_999, rng=None)[source]#
Perform the Henze–Zirkler test of multivariate normality (1990).
The smoothing parameter is
beta = ((2 p + 1) n / 4)**(1 / (p + 4)) / sqrt(2). The sample is centered and whitened with the maximum-likelihood empirical covariance. Every Monte Carlo null sample is independently re-centered and re-whitened; treating the estimated parameters as known would calibrate a different hypothesis.With exactly
n = p + 1observations the fitted geometry is constant: every null statistic ties, and the p-value is 1. This boundary case has no power against nonnormal alternatives and is flagged in diagnostics.- Parameters:
x (ArrayLike)
calibration (str)
n_resamples (int)
rng (int | integer | Generator | None)
- Return type:
- pysht.normality.jarque_bera(x, *, calibration='monte-carlo', n_resamples=9_999, rng=None)[source]#
Perform the Jarque–Bera omnibus test of univariate normality.
- Parameters:
- x
One-dimensional sample with at least three finite real observations.
- calibration
"monte-carlo"(the default) simulates the finite-sample normal null."asymptotic"explicitly uses the limiting chi-square approximation with two degrees of freedom.- n_resamples
Positive number of simulated normal samples for Monte Carlo calibration.
- rng
None, an integer seed, or a NumPy generator.
- Parameters:
x (ArrayLike)
calibration (str)
n_resamples (int)
rng (int | integer | Generator | None)
- Return type:
Notes
Monte Carlo calibration reports the corrected p-value
(b + 1) / (B + 1). The asymptotic option has no finite-sample size guarantee and is not the authoritative default.References
Jarque, C. M. and Bera, A. K. (1980). Efficient tests for normality, homoscedasticity and serial independence of regression residuals. Economics Letters, 6, 255–259.
- pysht.normality.robust_jarque_bera(x, *, c1=6.0, c2=64.0, calibration='monte-carlo', n_resamples=9_999, rng=None)[source]#
Perform the Gel–Gastwirth robust Jarque–Bera normality test.
- Parameters:
- x
One-dimensional sample with at least three finite real observations.
- c1, c2
Positive standardizing constants. The defaults 6 and 64 are the constants recommended by Gel and Gastwirth. Legacy SHT used 24 for
c2; that value does not reproduce the published procedure. Custom constants require Monte Carlo calibration.- calibration
"monte-carlo"(the default) or"asymptotic". The latter is an explicit chi-square approximation without a finite-sample size guarantee.- n_resamples
Number of simulated normal samples for Monte Carlo calibration.
- rng
None, an integer seed, or a NumPy generator.
- Parameters:
x (ArrayLike)
c1 (float)
c2 (float)
calibration (str)
n_resamples (int)
rng (int | integer | Generator | None)
- Return type:
References
Gel, Y. R. and Gastwirth, J. L. (2008). A robust modification of the Jarque–Bera test of normality. Economics Letters, 99, 30–32.
- pysht.normality.shapiro_francia(x)[source]#
Perform the Shapiro–Francia test of univariate normality.
- Parameters:
- x
One-dimensional sample of 5 to 5,000 finite real observations. The sample must not be constant.
- Returns:
- HypothesisTestResult
The squared normal-score correlation
Wand Royston’s approximate p-value.
- Parameters:
x (ArrayLike)
- Return type:
References
Shapiro, S. S. and Francia, R. S. (1972). An approximate analysis of variance test for normality. JASA, 67, 215–216.
- pysht.normality.shapiro_wilk(x)[source]#
Perform the Shapiro–Wilk test of univariate normality.
- Parameters:
- x
One-dimensional sample of 3 to 5,000 finite real observations. The sample must not be constant.
- Returns:
- HypothesisTestResult
The Shapiro–Wilk
Wstatistic and its approximate p-value.
- Parameters:
x (ArrayLike)
- Return type:
Notes
SciPy’s implementation of the Shapiro–Wilk statistic and Royston p-value approximation is used after a location/scale normalization. The 5,000 observation limit is enforced because the p-value approximation is not validated beyond it.
References
Shapiro, S. S. and Wilk, M. B. (1965). An analysis of variance test for normality (complete samples). Biometrika, 52, 591–611.