Sidereon.Statistics (Sidereon v0.22.0)

Residual-distribution diagnostics: sample moments and normality tests.

Post-fit residuals from a converged least-squares solve should look like zero-mean Gaussian noise. These primitives quantify departures from that ideal on an arbitrary residual set: sample skewness and kurtosis, the combined moments, the Jarque-Bera moment test, and the Shapiro-Wilk W test.

The moment definitions match scipy.stats (the central moments are the population/biased moments), so a caller can cross-check against the reference implementation. The numerical modeling lives in the sidereon-core Rust core; this module marshals the residual list and convention flags and decodes the results.

Each function returns {:ok, value} or {:error, reason}, where reason is a typed atom: :non_finite, :insufficient_data, :zero_variance, or :zero_range.

Summary

Types

moments()

Sample moments: mean, the biased variance, skewness, and the excess kurtosis (Gaussian -> 0 when fisher: true).

Functions

jarque_bera(x)

Jarque-Bera normality test (scipy.stats.jarque_bera).

kurtosis(x, opts \\ [])

Sample kurtosis.

moments(x, opts \\ [])

Mean, biased variance, skewness, and excess kurtosis in one pass.

shapiro_wilk(x)

Shapiro-Wilk W test for normality (Royston AS R94, the scipy.stats.shapiro algorithm).

skewness(x, opts \\ [])

Sample skewness.

Types

moments()

@type moments() :: %{
  mean: float(),
  variance: float(),
  skewness: float(),
  kurtosis: float()
}

Sample moments: mean, the biased variance, skewness, and the excess kurtosis (Gaussian -> 0 when fisher: true).

Functions

jarque_bera(x)

@spec jarque_bera([number()]) ::
  {:ok, %{statistic: float(), p_value: float()}} | {:error, atom()}

Jarque-Bera normality test (scipy.stats.jarque_bera).

Returns {:ok, %{statistic: jb, p_value: p}} with the chi-square(2) upper-tail p-value exp(-jb/2). Needs at least two residuals.

kurtosis(x, opts \\ [])

@spec kurtosis(
  [number()],
  keyword()
) :: {:ok, float()} | {:error, atom()}

Sample kurtosis.

fisher: true (default) returns the excess kurtosis m4 / m2^2 - 3 (Gaussian -> 0); fisher: false returns the Pearson kurtosis (Gaussian -> 3). bias: false applies the sample correction, which needs at least four residuals.

moments(x, opts \\ [])

@spec moments(
  [number()],
  keyword()
) :: {:ok, moments()} | {:error, atom()}

Mean, biased variance, skewness, and excess kurtosis in one pass.

:fisher and :bias select the kurtosis convention and the bias correction, exactly as in skewness/2 and kurtosis/2.

shapiro_wilk(x)

@spec shapiro_wilk([number()]) ::
  {:ok, %{w: float(), p_value: float()}} | {:error, atom()}

Shapiro-Wilk W test for normality (Royston AS R94, the scipy.stats.shapiro algorithm).

Returns {:ok, %{w: w, p_value: p}} with w in (0, 1] (closer to one is more Gaussian). Needs at least three residuals; returns {:error, :zero_range} when every residual is equal.

skewness(x, opts \\ [])

@spec skewness(
  [number()],
  keyword()
) :: {:ok, float()} | {:error, atom()}

Sample skewness.

bias: true (default) is the Fisher-Pearson coefficient g1 = m3 / m2^(3/2) (scipy.stats.skew); bias: false applies the sample correction (scipy.stats.skew(bias=False)), which needs at least three residuals.