[8] Tests for Normality#

pysht.normality provides five univariate goodness-of-fit procedures. Every function tests the composite null that the observations follow some normal distribution; location and scale are not specified under the null.

Procedure	Function	Authoritative calibration
Shapiro–Wilk	`shapiro_wilk`	Royston approximation
Shapiro–Francia	`shapiro_francia`	Royston approximation
Jarque–Bera	`jarque_bera`	Monte Carlo normal null
Adjusted Jarque–Bera	`adjusted_jarque_bera`	Monte Carlo normal null
Robust Jarque–Bera	`robust_jarque_bera`	Monte Carlo normal null

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.

See the normality validation ledger for formulas, null-size audits, Monte Carlo semantics, and deliberate corrections to SHT.

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:

HypothesisTestResult | ResamplingTestResult

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.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:

HypothesisTestResult | ResamplingTestResult

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:

HypothesisTestResult | ResamplingTestResult

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 W and Royston’s approximate p-value.

Parameters:

x (ArrayLike)

Return type:

HypothesisTestResult

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 W statistic and its approximate p-value.

Parameters:

x (ArrayLike)

Return type:

HypothesisTestResult

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.