Repository Public MIT
1// ORIX Calc2// File: Packages/ORIXStatistics/Tests/ORIXStatisticsTests/DistributionTests.swift3// Description: Distribution behaviour — round trips, discrete-quantile definition, moments, interval probabilities, edges and errors.4//5// Author: Simon-Pierre Boucher6// Contact: contact@spboucher.ai7import Foundation8import Testing9import ORIXNumerics10@testable import ORIXStatistics1112@Suite struct DistributionBehaviourTests {13 static func continuous() throws -> [any ContinuousDistribution] {14 [try NormalDistribution(mean: 3, standardDeviation: 0.5), StandardNormalDistribution(),15 try StudentTDistribution(degreesOfFreedom: 1), try StudentTDistribution(degreesOfFreedom: 7.3), try StudentTDistribution(degreesOfFreedom: 2.5e6),16 try ChiSquareDistribution(degreesOfFreedom: 1), try ChiSquareDistribution(degreesOfFreedom: 23),17 try FDistribution(numeratorDegreesOfFreedom: 4, denominatorDegreesOfFreedom: 17), try FDistribution(numeratorDegreesOfFreedom: 1, denominatorDegreesOfFreedom: 3),18 try GammaDistribution(shape: 0.6, rate: 3), try GammaDistribution(shape: 12, scale: 2),19 try BetaDistribution(alpha: 0.7, beta: 1.8), try BetaDistribution(alpha: 14, beta: 6),20 try ExponentialDistribution(rate: 4), try ExponentialDistribution(mean: 10), try UniformDistribution(lowerBound: 2, upperBound: 9)]21 }2223 static func discrete() throws -> [any DiscreteDistribution] {24 [try BinomialDistribution(trials: 30, probability: 0.42), try BinomialDistribution(trials: 2000, probability: 0.003),25 try PoissonDistribution(mean: 0.8), try PoissonDistribution(mean: 65),26 try GeometricDistribution(probability: 0.3), try GeometricDistribution(probability: 0.05, counting: .failures),27 try NegativeBinomialDistribution(successes: 3, probability: 0.25), try NegativeBinomialDistribution(successes: 0.7, probability: 0.6),28 try DiscreteUniformDistribution(lowerBound: -2, upperBound: 9)]29 }3031 @Test func quantileOfCdfRoundTripsInBothTails() throws {32 for d in try Self.continuous() {33 for p in [1e-12, 1e-6, 0.003, 0.05, 0.25, 0.5, 0.8, 0.99] {34 let x = try d.quantile(p)35 // Tolerance: 1e-11 relative, or what one ulp of x is worth when the quantile sits next to a finite support bound.36 #expect(close(d.cdf(x), p, rtol: 1e-11, atol: 4 * d.pdf(x) * x.ulp), "\(d.name): cdf(quantile(\(p))) = \(d.cdf(x))")37 let u = try d.quantile(upperTail: p)38 #expect(close(d.survival(u), p, rtol: 1e-11, atol: 4 * d.pdf(u) * u.ulp), "\(d.name): sf(isf(\(p))) = \(d.survival(u))")39 }40 // quantile(1 − q) and quantile(upperTail: q) are the same point41 #expect(close(try d.quantile(0.75), try d.quantile(upperTail: 0.25), rtol: 1e-12, atol: 1e-12), "\(d.name)")42 #expect(try d.quantile(0) == d.supportLowerBound)43 #expect(try d.quantile(1) == d.supportUpperBound)44 #expect(try d.quantile(upperTail: 0) == d.supportUpperBound)45 #expect(try d.quantile(upperTail: 1) == d.supportLowerBound)46 }47 }4849 @Test func cdfAndSurvivalAreComplementaryAndMonotone() throws {50 for d in try Self.continuous() as [any ProbabilityDistribution] + (try Self.discrete()) {51 var previous = -1.052 for p in [0.001, 0.02, 0.2, 0.5, 0.8, 0.98, 0.999] {53 let x = try d.quantile(p)54 let c = d.cdf(x), s = d.survival(x)55 #expect(abs(c + s - 1) < 1e-14, "\(d.name) at \(x)")56 #expect(c >= previous, "\(d.name) not monotone")57 previous = c58 }59 #expect(d.cdf(-.infinity) == 0 && d.cdf(.infinity) == 1 && d.survival(.infinity) == 0 && d.survival(-.infinity) == 1, "\(d.name)")60 #expect(d.cdf(.nan).isNaN && d.survival(.nan).isNaN)61 }62 }6364 @Test func pdfIntegratesToTheCdf() throws {65 // Independent check of pdf against cdf by adaptive Gauss–Kronrod quadrature (ORIXNumerics).66 for d in try Self.continuous() {67 let a = try d.quantile(0.2), b = try d.quantile(0.9)68 let integral = Quadrature.integrate({ d.pdf($0) }, from: a, to: b, absoluteTolerance: 1e-13, relativeTolerance: 1e-12)69 #expect(close(integral.value, 0.7, rtol: 1e-9), "\(d.name): ∫pdf = \(integral.value)")70 #expect(close(d.logPDF(a), log(d.pdf(a)), rtol: 1e-12, atol: 1e-12), "\(d.name)")71 #expect(d.pdf(d.supportLowerBound - 1) == 0 || d.supportLowerBound == -.infinity)72 }73 }7475 @Test func momentsMatchNumericalIntegration() throws {76 for d in try Self.continuous() {77 guard let mean = d.mean, let variance = d.variance, variance.isFinite else { continue }78 // E[X] and Var[X] as integrals of the quantile function over (0, 1): tanh–sinh handles the endpoint singularities.79 let m = Quadrature.tanhSinh({ (try? d.quantile($0)) ?? 0 }, from: 0, to: 1, relativeTolerance: 1e-11)80 #expect(close(m.value, mean, rtol: 1e-6, atol: 1e-7), "\(d.name): mean \(m.value) vs \(mean)")81 let v = Quadrature.tanhSinh({ let q = (try? d.quantile($0)) ?? 0; return (q - mean) * (q - mean) }, from: 0, to: 1, relativeTolerance: 1e-10)82 #expect(close(v.value, variance, rtol: 2e-3), "\(d.name): variance \(v.value) vs \(variance)")83 }84 for d in try Self.discrete() {85 let mean = try #require(d.mean), variance = try #require(d.variance)86 let lo = Int(d.supportLowerBound), hi = Int(try d.quantile(upperTail: 1e-15)) + 587 var total = 0.0, m = 0.0, m2 = 0.088 for k in lo...hi { let w = d.pmf(k); total += w; m += w * Double(k); m2 += w * Double(k) * Double(k) }89 #expect(close(total, 1, rtol: 1e-12), "\(d.name): Σpmf = \(total)")90 #expect(close(m, mean, rtol: 1e-10, atol: 1e-12), "\(d.name)")91 #expect(close(m2 - m * m, variance, rtol: 1e-8), "\(d.name)")92 }93 }9495 @Test func momentsMatchScipy() throws {96 let moments = (try Reference.load("distributions")["moments"] as? [[String: Any]]) ?? []97 #expect(moments.count > 60)98 for m in moments {99 let d = try makeDistribution(m.string("dist"), m.doubles("params"))100 // scipy reports inf or nan where the moment is infinite or undefined; the JSON stores null for both.101 if m.has("mean") { #expect(close(try #require(d.mean), m.double("mean"), rtol: 1e-12, atol: 1e-300), "\(d.name)") }102 else { #expect(d.mean == nil || d.mean == .infinity, "\(d.name)") }103 if m.has("variance") { #expect(close(try #require(d.variance), m.double("variance"), rtol: 1e-12), "\(d.name)") }104 else { #expect(d.variance == nil || d.variance == .infinity, "\(d.name)") }105 }106 }107108 @Test func undefinedMomentsAreNilNotNaN() throws {109 #expect(try StudentTDistribution(degreesOfFreedom: 1).mean == nil)110 #expect(try StudentTDistribution(degreesOfFreedom: 1).variance == nil)111 #expect(try StudentTDistribution(degreesOfFreedom: 2).variance == .infinity)112 #expect(try StudentTDistribution(degreesOfFreedom: 5).standardDeviation == (5.0 / 3).squareRoot())113 #expect(try FDistribution(numeratorDegreesOfFreedom: 3, denominatorDegreesOfFreedom: 2).mean == .infinity)114 #expect(try FDistribution(numeratorDegreesOfFreedom: 3, denominatorDegreesOfFreedom: 2).variance == nil)115 #expect(try FDistribution(numeratorDegreesOfFreedom: 3, denominatorDegreesOfFreedom: 4).variance == .infinity)116 }117118 @Test func discreteQuantileIsTheSmallestKWithCdfAtLeastP() throws {119 for d in try Self.discrete() {120 for p in [1e-9, 0.001, 0.05, 0.25, 0.5, 0.6180339887, 0.9, 0.999, 1 - 1e-10] {121 let k = try d.quantile(p)122 #expect(k == k.rounded() && d.cdf(k) >= p, "\(d.name) p=\(p) k=\(k)")123 if k > d.supportLowerBound { #expect(d.cdf(k - 1) < p, "\(d.name) p=\(p): \(k) is not the smallest") }124 let u = try d.quantile(upperTail: p)125 #expect(d.survival(u) <= p, "\(d.name)")126 if u > d.supportLowerBound { #expect(d.survival(u - 1) > p, "\(d.name) q=\(p): \(u) is not the smallest") }127 }128 // A probability that is itself a CDF value maps back to its own k.129 let k0 = try d.quantile(0.4)130 #expect(try d.quantile(d.cdf(k0)) == k0, "\(d.name)")131 #expect(try d.quantile(0) == d.supportLowerBound)132 #expect(try d.quantile(1) == d.supportUpperBound)133 let v = try d.verifiedQuantile(0.37)134 #expect(v.verification.isVerified, "\(d.name): \(v.verification.checks)")135 }136 // Exact textbook values137 let die = try DiscreteUniformDistribution(lowerBound: 1, upperBound: 6)138 #expect(try die.quantile(0.5) == 3)139 #expect(try die.quantile(0.51) == 4)140 #expect(try die.quantile(1.0 / 6) == 1)141 let coin = try BinomialDistribution(trials: 10, probability: 0.5)142 #expect(try coin.quantile(0.623046875) == 5) // cdf(5) = 638/1024 exactly143 #expect(try coin.quantile(0.6230468751) == 6)144 }145146 @Test func knownValues() throws {147 // Hand-checkable numbers.148 let coin = try BinomialDistribution(trials: 10, probability: 0.5)149 #expect(coin.pmf(3) == 120.0 / 1024 || close(coin.pmf(3), 120.0 / 1024, rtol: 1e-14))150 #expect(close(coin.cdf(3), 176.0 / 1024, rtol: 1e-14))151 #expect(close(coin.probability(from: 4, to: 6), 672.0 / 1024, rtol: 1e-14))152 #expect(coin.pmf(11) == 0 && coin.pmf(-1) == 0 && coin.pmf(at: 2.5) == 0)153 let poisson = try PoissonDistribution(mean: 2)154 #expect(close(poisson.pmf(0), exp(-2), rtol: 1e-15))155 #expect(close(poisson.pmf(3), 8.0 / 6 * exp(-2), rtol: 1e-14))156 #expect(close(poisson.cdf(1), 3 * exp(-2), rtol: 1e-14))157 let z = NormalDistribution.standard158 #expect(close(z.cdf(1.959963984540054), 0.975, rtol: 1e-14))159 #expect(close(try z.quantile(0.975), 1.959963984540054, rtol: 1e-15))160 #expect(close(z.probability(from: -1, to: 1), 0.6826894921370859, rtol: 1e-14))161 #expect(close(z.pdf(0), 0.3989422804014327, rtol: 1e-15))162 #expect(close(try StudentTDistribution(degreesOfFreedom: 1).cdf(1), 0.75, rtol: 1e-14)) // Cauchy163 #expect(close(try StudentTDistribution(degreesOfFreedom: 1).quantile(0.975), 12.706204736174694, rtol: 1e-13))164 #expect(close(try ChiSquareDistribution(degreesOfFreedom: 2).survival(5.991464547107979), 0.05, rtol: 1e-13))165 #expect(close(try ExponentialDistribution(rate: 2).quantile(0.5), log(2) / 2, rtol: 1e-15))166 let geom = try GeometricDistribution(probability: 0.25)167 #expect(geom.pmf(1) == 0.25 && close(geom.pmf(3), 0.140625, rtol: 1e-15) && geom.pmf(0) == 0 && geom.mean == 4)168 #expect(try GeometricDistribution(probability: 0.25, counting: .failures).pmf(0) == 0.25)169 let nb = try NegativeBinomialDistribution(successes: 1, probability: 0.25) // = geometric failures170 #expect(close(nb.pmf(2), 0.140625, rtol: 1e-14) && close(nb.cdf(2), 1 - pow(0.75, 3), rtol: 1e-14))171 #expect(try GammaDistribution(shape: 3, scale: 2) == GammaDistribution(shape: 3, rate: 0.5))172 #expect(try ExponentialDistribution(mean: 4).rate == 0.25)173 #expect(try NormalDistribution(mean: 100, standardDeviation: 15).zScore(130) == 2)174 }175176 @Test func intervalProbabilityIsTailAware() throws {177 let z = NormalDistribution.standard178 // Far upper tail: 1 − cdf would be 0; the survival difference keeps full accuracy.179 let p = z.probability(from: 9, to: 10)180 #expect(close(p, z.survival(9) - z.survival(10), rtol: 1e-14) && p > 1e-19 && p < 2e-19)181 #expect(close(z.probability(from: -10, to: -9), p, rtol: 1e-12))182 #expect(z.probability(from: 2, to: 1) == 0)183 #expect(z.probability(from: -.infinity, to: .infinity) == 1)184 #expect(z.probability(from: 1, to: .nan).isNaN)185 let b = try BinomialDistribution(trials: 20, probability: 0.3)186 // Both ends included for a discrete distribution.187 #expect(close(b.probability(from: 5, to: 5), b.pmf(5), rtol: 1e-12))188 #expect(close(b.probability(from: 4.2, to: 7.9), b.pmf(5) + b.pmf(6) + b.pmf(7), rtol: 1e-12))189 #expect(close(b.probabilityBelow(5), b.cdf(4), rtol: 1e-15) && close(b.probabilityAtLeast(5), b.survival(4), rtol: 1e-15))190 #expect(close(b.probability(from: 0, to: 20), 1, rtol: 1e-15))191 }192193 @Test func edgeParameters() throws {194 // Degenerate but legal parameters.195 let never = try BinomialDistribution(trials: 8, probability: 0), always = try BinomialDistribution(trials: 8, probability: 1)196 #expect(never.pmf(0) == 1 && never.cdf(0) == 1 && never.survival(0) == 0)197 #expect(try never.quantile(0.9) == 0)198 #expect(always.pmf(8) == 1 && always.cdf(7) == 0)199 #expect(try always.quantile(0.1) == 8)200 #expect(try BinomialDistribution(trials: 0, probability: 0.4).pmf(0) == 1)201 let sure = try GeometricDistribution(probability: 1)202 #expect(sure.pmf(1) == 1 && sure.cdf(1) == 1 && sure.pmf(2) == 0)203 #expect(try sure.quantile(0.5) == 1)204 #expect(try NegativeBinomialDistribution(successes: 2, probability: 1).pmf(0) == 1)205 // Unbounded densities at the edge of the support are +∞, never NaN.206 #expect(try ChiSquareDistribution(degreesOfFreedom: 1).pdf(0) == .infinity)207 #expect(try ChiSquareDistribution(degreesOfFreedom: 2).pdf(0) == 0.5)208 #expect(try ChiSquareDistribution(degreesOfFreedom: 3).pdf(0) == 0)209 #expect(try BetaDistribution(alpha: 0.5, beta: 2).pdf(0) == .infinity)210 #expect(try BetaDistribution(alpha: 1, beta: 2).pdf(0) == 2)211 #expect(close(try BetaDistribution(alpha: 3, beta: 1).pdf(1), 3, rtol: 1e-15))212 #expect(try FDistribution(numeratorDegreesOfFreedom: 2, denominatorDegreesOfFreedom: 9).pdf(0) == 1)213 #expect(try GammaDistribution(shape: 2, rate: 1).pdf(-1) == 0)214 // Far tails stay finite and positive, and logPDF goes where pdf underflows.215 let z = NormalDistribution.standard216 #expect(z.cdf(-38) > 0 && z.pdf(40) == 0 && close(z.logPDF(40), -800 - 0.9189385332046727, rtol: 1e-15))217 #expect(try PoissonDistribution(mean: 1e6).cdf(1e6) > 0.5)218 // 50-digit mpmath values (scipy itself is off by 1e-12 here)219 #expect(close(try PoissonDistribution(mean: 1e6).cdf(1e6), 0.5002659614862837, rtol: 1e-12))220 #expect(close(try BinomialDistribution(trials: 1_000_000, probability: 0.5).cdf(500_000), 0.5003989421806658, rtol: 1e-12))221 // A heavy-tailed quantile beyond the range of doubles is an explicit overflow, not ∞ or NaN.222 #expect(throws: StatisticsError.self) { try StudentTDistribution(degreesOfFreedom: 0.5).quantile(1e-200) }223 #expect(close(try StudentTDistribution(degreesOfFreedom: 1).quantile(upperTail: 1e-200), 3.183098861837907e199, rtol: 1e-13))224 }225226 @Test func verifiedQuantileReportsARealRoundTrip() throws {227 let t = try StudentTDistribution(degreesOfFreedom: 12)228 let r = try t.verifiedQuantile(0.975)229 #expect(close(r.value, 2.1788128296672288, rtol: 1e-13)) // mpmath230 #expect(r.verification.isVerified && r.verification.checks[0].kind == .residual)231 #expect(try t.verifiedQuantile(1).verification.checks[0].kind == .domain)232 #expect(try t.median() == 0)233 }234235 @Test func parameterAndProbabilityErrors() throws {236 #expect(throws: StatisticsError.self) { try NormalDistribution(mean: 0, standardDeviation: 0) }237 #expect(throws: StatisticsError.self) { try NormalDistribution(mean: 0, standardDeviation: -1) }238 #expect(throws: StatisticsError.self) { try NormalDistribution(mean: .nan, standardDeviation: 1) }239 #expect(throws: StatisticsError.self) { try StudentTDistribution(degreesOfFreedom: 0) }240 #expect(throws: StatisticsError.self) { try ChiSquareDistribution(degreesOfFreedom: -2) }241 #expect(throws: StatisticsError.self) { try FDistribution(numeratorDegreesOfFreedom: 0, denominatorDegreesOfFreedom: 5) }242 #expect(throws: StatisticsError.self) { try GammaDistribution(shape: 1, rate: .infinity) }243 #expect(throws: StatisticsError.self) { try BetaDistribution(alpha: 0, beta: 1) }244 #expect(throws: StatisticsError.self) { try ExponentialDistribution(rate: 0) }245 #expect(throws: StatisticsError.self) { try UniformDistribution(lowerBound: 2, upperBound: 2) }246 #expect(throws: StatisticsError.self) { try BinomialDistribution(trials: -1, probability: 0.5) }247 #expect(throws: StatisticsError.self) { try BinomialDistribution(trials: 5, probability: 1.2) }248 #expect(throws: StatisticsError.self) { try PoissonDistribution(mean: 0) }249 #expect(throws: StatisticsError.self) { try GeometricDistribution(probability: 0) }250 #expect(throws: StatisticsError.self) { try NegativeBinomialDistribution(successes: 0, probability: 0.5) }251 #expect(throws: StatisticsError.self) { try DiscreteUniformDistribution(lowerBound: 5, upperBound: 4) }252 for d in try Self.continuous() as [any ProbabilityDistribution] + (try Self.discrete()) {253 #expect(throws: StatisticsError.probabilityOutOfRange(-0.1)) { try d.quantile(-0.1) }254 #expect(throws: StatisticsError.probabilityOutOfRange(1.1)) { try d.quantile(1.1) }255 #expect(throws: StatisticsError.self) { try d.quantile(.nan) }256 #expect(throws: StatisticsError.probabilityOutOfRange(2)) { try d.quantile(upperTail: 2) }257 }258 }259}260