SPB Git

Repository Public MIT

DistributionTests.swift 17.4 KB 260 lines swift

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
Files main
Menu

Theme