Documentation

Distribution

@statili/math ·v0.0.1-beta.0 ·5 exports

signature
logGamma(x: number): number
Natural logarithm of the gamma function, ln Γ(x), via the Lanczos approximation.

Γ(x) overflows a double for x greater than about 171, so the log form is used throughout — every consumer here needs ratios of gamma functions, which become differences of logs and stay in range.

Accurate to roughly 15 significant digits across the positive reals. Values of x below 0.5 are handled by the reflection formula Γ(x)Γ(1−x) = π / sin(πx).

Parameters

NameTypeDescription
x number Any real number that is not a non-positive integer.

Returns

number
ln Γ(x), or NaN at the poles (x = 0, −1, −2, …).

Example

logGamma(1)   // 0        (Γ(1) = 1)
logGamma(5)   // ≈ 3.1781 (Γ(5) = 24)
logGamma(0.5) // ≈ 0.5724 (Γ(½) = √π)

# regularizedIncompleteBeta function

packages/math/src/distribution.ts:128
signature
regularizedIncompleteBeta(a: number, b: number, x: number): number
The regularised incomplete beta function I_x(a, b).

This is the CDF of the Beta(a, b) distribution, and the workhorse behind the Student’s t, F, and binomial tail probabilities.

The continued fraction converges quickly for x < (a+1)/(a+b+2); outside that range the symmetry I_x(a, b) = 1 − I_{1−x}(b, a) is applied first.

Parameters

NameTypeDescription
a number First shape parameter, must be > 0.
b number Second shape parameter, must be > 0.
x number Upper limit of integration, in [0, 1].

Returns

number
I_x(a, b) in [0, 1], or NaN for invalid parameters.

Example

regularizedIncompleteBeta(1, 1, 0.4)  // 0.4   — Beta(1,1) is uniform
regularizedIncompleteBeta(1, 2, 0.5)  // 0.75  — 1 − (1 − x)²
signature
studentTCdf(df: number, t: number): number
Cumulative distribution function of Student’s t distribution: P(T ≤ t) for a t variate with df degrees of freedom.

Computed from the regularised incomplete beta function via P(|T| > t) = I_{df/(df+t²)}(df/2, ½).

Degrees of freedom are the slowly-varying parameter, so they come first — matching round(precision, value) and quantile(p, numbers) elsewhere in this package, and making the function partial-application friendly.

Parameters

NameTypeDescription
df number Degrees of freedom, must be > 0. Need not be an integer.
t number The t-statistic.

Returns

number
P(T ≤ t) in (0, 1), or NaN if df <= 0.

Example

studentTCdf(1, 0)   // 0.5   — symmetric about zero for every df
studentTCdf(1, 1)   // 0.75  — df = 1 is Cauchy: ½ + atan(t)/π
studentTCdf(10, -2) // ≈ 0.0367

# studentTQuantile function

packages/math/src/distribution.ts:224
signature
studentTQuantile(df: number, p: number): number
Inverse CDF (quantile function) of Student’s t distribution: the value t for which P(T <= t) = p.

This is what turns a confidence level into a multiplier — a 95% interval on a coefficient is estimate ± studentTQuantile(df, 0.975) · standardError.

Found by bisection on {@link studentTCdf}, which is monotonic, so convergence is guaranteed. Cost is irrelevant in practice: an interval band needs one quantile for the whole curve, not one per point, because the multiplier depends only on df and the level.

Parameters

NameTypeDescription
df number Degrees of freedom, must be > 0.
p number Probability in [0, 1].

Returns

number
The t value at that quantile, or NaN for invalid input. Returns -Infinity at p = 0 and Infinity at p = 1.

Example

studentTQuantile(10, 0.975)  // ≈ 2.228 — the classic 5% two-tailed multiplier
studentTQuantile(1, 0.75)    // 1       — df = 1 is Cauchy: tan(pi(p - 1/2))
studentTQuantile(30, 0.5)    // 0       — symmetric about zero

# studentTTwoTailedP function

packages/math/src/distribution.ts:194
signature
studentTTwoTailedP(df: number, t: number): number
Two-tailed p-value for a t-statistic: P(|T| > |t|).
This is the quantity reported alongside a regression coefficient — the probability of observing a coefficient at least this far from zero if the true coefficient were zero.

Parameters

NameTypeDescription
df number Degrees of freedom, must be > 0.
t number The observed t-statistic. Sign is irrelevant; the test is two-tailed.

Returns

number
A p-value in [0, 1], or NaN if df <= 0.

Example

studentTTwoTailedP(10, 2.228)  // ≈ 0.05  — the classic 5% critical value
studentTTwoTailedP(10, 0)      // 1       — no evidence of any effect