SPB Git

Repository Public

Distributions.swift 12.3 KB 263 lines swift

1import Foundation23/// A continuous probability distribution with the functions inference needs.4public protocol ContinuousDistribution: Sendable {5    /// Density.6    func pdf(_ x: Double) -> Double7    /// P(X ≤ x).8    func cdf(_ x: Double) -> Double9    /// Survival function P(X > x), computed without cancellation in the upper tail.10    func sf(_ x: Double) -> Double11    /// Inverse CDF: the x with P(X ≤ x) = p.12    func quantile(_ p: Double) -> Double13    /// Inverse survival function: the x with P(X > x) = q (accurate for tiny q).14    func isf(_ q: Double) -> Double15}1617extension ContinuousDistribution {18    /// p-value of an observed statistic for the given alternative, for a statistic whose null19    /// distribution is this one. `twoSided` doubles the smaller tail (symmetric distributions).20    public func pValue(_ statistic: Double, alternative: Alternative) -> Double {21        switch alternative {22        case .less: cdf(statistic)23        case .greater: sf(statistic)24        case .twoSided: min(1, 2 * min(cdf(statistic), sf(statistic)))25        }26    }27}2829/// Normal distribution N(mean, sd²).30public struct NormalDistribution: ContinuousDistribution, Hashable, Codable {31    public var mean: Double32    public var sd: Double33    public init(mean: Double = 0, sd: Double = 1) { self.mean = mean; self.sd = sd }34    public static let standard = NormalDistribution()3536    public func pdf(_ x: Double) -> Double {37        let z = (x - mean) / sd38        return exp(-0.5 * z * z) / (sd * (2 * Double.pi).squareRoot())39    }40    public func cdf(_ x: Double) -> Double { 0.5 * erfc(-(x - mean) / (sd * 2.0.squareRoot())) }41    public func sf(_ x: Double) -> Double { 0.5 * erfc((x - mean) / (sd * 2.0.squareRoot())) }42    public func quantile(_ p: Double) -> Double { mean + sd * SpecialFunctions.normalQuantile(p) }43    public func isf(_ q: Double) -> Double { mean + sd * SpecialFunctions.normalQuantile(upper: q) }44}4546/// Student's t distribution with `df` degrees of freedom (df > 0, not necessarily integer).47public struct StudentTDistribution: ContinuousDistribution, Hashable, Codable {48    public var df: Double49    public init(df: Double) { self.df = df }5051    public func pdf(_ x: Double) -> Double {52        guard df > 0 else { return .nan }53        let lg = SpecialFunctions.logGamma((df + 1) / 2) - SpecialFunctions.logGamma(df / 2) - 0.5 * log(df * Double.pi)54        let ax = abs(x)55        let l = ax > 1e150 ? 2 * log(ax) - log(df) : log1p(x * x / df)56        return exp(lg - (df + 1) / 2 * l)57    }5859    /// Upper-tail probability P(T > |t|) through the incomplete beta function.60    private func upperTail(_ t: Double) -> Double {61        // I_{df/(df+t²)}(df/2, 1/2); both x and 1 − x are formed without cancellation.62        if abs(t) > 1e150 {         // t² would overflow63            // leading term of I_x(a, ½) ≈ x^a / (a·B(a, ½)) with x = df/t²: exact to double precision here64            let a = df / 265            return 0.5 * exp(df * (0.5 * log(df) - log(abs(t))) - log(a) - SpecialFunctions.logBeta(a, 0.5))66        }67        let t2 = t * t68        let denom = df + t269        return 0.5 * SpecialFunctions.betaIPair(df / 2, 0.5, x: df / denom, y: t2 / denom).p70    }7172    public func cdf(_ x: Double) -> Double {73        guard df > 0, !x.isNaN else { return .nan }74        if x.isInfinite { return x > 0 ? 1 : 0 }75        let tail = upperTail(x)76        return x > 0 ? 1 - tail : tail77    }78    public func sf(_ x: Double) -> Double { cdf(-x) }7980    public func quantile(_ p: Double) -> Double {81        guard df > 0, p >= 0, p <= 1 else { return .nan }82        if p == 0 { return -.infinity }83        if p == 1 { return .infinity }84        if p == 0.5 { return 0 }85        return p < 0.5 ? -upperQuantile(p) : upperQuantile(1 - p)86    }87    public func isf(_ q: Double) -> Double {88        guard df > 0, q >= 0, q <= 1 else { return .nan }89        if q == 0 { return .infinity }90        if q == 1 { return -.infinity }91        if q == 0.5 { return 0 }92        return q < 0.5 ? upperQuantile(q) : -upperQuantile(1 - q)93    }9495    /// The t > 0 with P(T > t) = q, for 0 < q < 0.5.96    private func upperQuantile(_ q: Double) -> Double {97        // Start from the normal quantile with the Cornish–Fisher correction, then polish.98        let z = SpecialFunctions.normalQuantile(upper: q)99        var guess = z + (z * z * z + z) / (4 * df)100        if df < 3 || !guess.isFinite || guess <= 0 {101            // heavy tails: invert the leading term of the tail, P(T>t) ≈ C t^{-df}102            let lc = SpecialFunctions.logGamma((df + 1) / 2) - SpecialFunctions.logGamma(df / 2) - 0.5 * log(df * Double.pi) + (df + 1) / 2 * log(df) - log(df)103            let alt = exp((lc - log(q)) / df)104            if alt.isFinite, alt > 0, !(guess.isFinite && guess > 0 && q > 0.05) { guess = alt }105        }106        return SpecialFunctions.invertMonotone(target: q, increasing: false, lo: 0, hi: .infinity, guess: guess,107                                               f: { self.upperTail($0) }, derivative: { self.pdf($0) })108    }109}110111/// Chi-square distribution with `df` degrees of freedom.112public struct ChiSquaredDistribution: ContinuousDistribution, Hashable, Codable {113    public var df: Double114    public init(df: Double) { self.df = df }115116    public func pdf(_ x: Double) -> Double {117        guard df > 0 else { return .nan }118        if x < 0 { return 0 }119        if x == 0 { return df < 2 ? .infinity : (df == 2 ? 0.5 : 0) }120        let k = df / 2121        return exp(SpecialFunctions.logGammaPrefix(k, x / 2)) / x122    }123    public func cdf(_ x: Double) -> Double { x <= 0 ? 0 : SpecialFunctions.gammaPQ(df / 2, x / 2).p }124    public func sf(_ x: Double) -> Double { x <= 0 ? 1 : SpecialFunctions.gammaPQ(df / 2, x / 2).q }125126    private func guess(upper q: Double) -> Double {127        // Wilson–Hilferty128        let z = SpecialFunctions.normalQuantile(upper: q)129        let c = 2 / (9 * df)130        let w = 1 - c + z * c.squareRoot()131        let g = df * w * w * w132        if g.isFinite, g > 0, w > 0 { return g }133        // small-x expansion of P(a, x) ≈ x^a / Γ(a+1)134        let a = df / 2135        let lp = q < 0.5 ? log1p(-q) : log(1 - q)136        return 2 * exp((lp + SpecialFunctions.logGamma(a + 1)) / a)137    }138139    public func quantile(_ p: Double) -> Double {140        guard df > 0, p >= 0, p <= 1 else { return .nan }141        if p == 0 { return 0 }142        if p == 1 { return .infinity }143        if p > 0.5 { return isfCore(1 - p) }144        var g = guess(upper: 1 - p)145        if p < 0.01 {146            let a = df / 2147            let alt = 2 * exp((log(p) + SpecialFunctions.logGamma(a + 1)) / a)148            if alt.isFinite, alt > 0, p < 1e-6 || !(g.isFinite && g > 0) { g = alt }149        }150        return SpecialFunctions.invertMonotone(target: p, increasing: true, lo: 0, hi: .infinity, guess: g,151                                               f: { self.cdf($0) }, derivative: { self.pdf($0) })152    }153    public func isf(_ q: Double) -> Double {154        guard df > 0, q >= 0, q <= 1 else { return .nan }155        if q == 0 { return .infinity }156        if q == 1 { return 0 }157        if q > 0.5 { return quantile(1 - q) }158        return isfCore(q)159    }160    private func isfCore(_ q: Double) -> Double {161        SpecialFunctions.invertMonotone(target: q, increasing: false, lo: 0, hi: .infinity, guess: guess(upper: q),162                                        f: { self.sf($0) }, derivative: { self.pdf($0) })163    }164}165166/// Fisher–Snedecor F distribution with (d1, d2) degrees of freedom.167public struct FisherFDistribution: ContinuousDistribution, Hashable, Codable {168    public var d1: Double169    public var d2: Double170    public init(d1: Double, d2: Double) { self.d1 = d1; self.d2 = d2 }171172    public func pdf(_ x: Double) -> Double {173        guard d1 > 0, d2 > 0 else { return .nan }174        if x < 0 { return 0 }175        if x == 0 { return d1 < 2 ? .infinity : (d1 == 2 ? 1 : 0) }176        let lg = 0.5 * (d1 * log(d1) + d2 * log(d2)) + (d1 / 2 - 1) * log(x) - (d1 + d2) / 2 * log(d2 + d1 * x) - SpecialFunctions.logBeta(d1 / 2, d2 / 2)177        return exp(lg)178    }179    private func pair(_ x: Double) -> (p: Double, q: Double) {180        let denom = d1 * x + d2181        return SpecialFunctions.betaIPair(d1 / 2, d2 / 2, x: d1 * x / denom, y: d2 / denom)182    }183    public func cdf(_ x: Double) -> Double { x <= 0 ? 0 : (x.isInfinite ? 1 : pair(x).p) }184    public func sf(_ x: Double) -> Double { x <= 0 ? 1 : (x.isInfinite ? 0 : pair(x).q) }185186    public func quantile(_ p: Double) -> Double {187        guard d1 > 0, d2 > 0, p >= 0, p <= 1 else { return .nan }188        if p == 0 { return 0 }189        if p == 1 { return .infinity }190        // Invert through the beta distribution: X = d2 B / (d1 (1 − B)), B ~ Beta(d1/2, d2/2).191        let (b, c) = BetaDistribution(a: d1 / 2, b: d2 / 2).quantilePair(p: p, q: 1 - p, usePUpper: false)192        let start = d2 * b / (d1 * c)193        return polish(start, target: p, lower: true)194    }195    public func isf(_ q: Double) -> Double {196        guard d1 > 0, d2 > 0, q >= 0, q <= 1 else { return .nan }197        if q == 0 { return .infinity }198        if q == 1 { return 0 }199        let (b, c) = BetaDistribution(a: d1 / 2, b: d2 / 2).quantilePair(p: 1 - q, q: q, usePUpper: true)200        let start = d2 * b / (d1 * c)201        return polish(start, target: q, lower: false)202    }203    private func polish(_ start: Double, target: Double, lower: Bool) -> Double {204        let g = start.isFinite && start > 0 ? start : 1205        return SpecialFunctions.invertMonotone(target: target, increasing: lower, lo: 0, hi: .infinity, guess: g,206                                               f: { lower ? self.cdf($0) : self.sf($0) }, derivative: { self.pdf($0) })207    }208}209210/// Beta distribution on [0, 1] with shape parameters a, b > 0.211public struct BetaDistribution: ContinuousDistribution, Hashable, Codable {212    public var a: Double213    public var b: Double214    public init(a: Double, b: Double) { self.a = a; self.b = b }215216    public func pdf(_ x: Double) -> Double {217        guard a > 0, b > 0 else { return .nan }218        if x < 0 || x > 1 { return 0 }219        if x == 0 { return a < 1 ? .infinity : (a == 1 ? b : 0) }220        if x == 1 { return b < 1 ? .infinity : (b == 1 ? a : 0) }221        return exp((a - 1) * log(x) + (b - 1) * log1p(-x) - SpecialFunctions.logBeta(a, b))222    }223    public func cdf(_ x: Double) -> Double { x <= 0 ? 0 : (x >= 1 ? 1 : SpecialFunctions.betaIPair(a, b, x: x, y: 1 - x).p) }224    public func sf(_ x: Double) -> Double { x <= 0 ? 1 : (x >= 1 ? 0 : SpecialFunctions.betaIPair(a, b, x: x, y: 1 - x).q) }225226    public func quantile(_ p: Double) -> Double {227        guard a > 0, b > 0, p >= 0, p <= 1 else { return .nan }228        return quantilePair(p: p, q: 1 - p, usePUpper: false).x229    }230    public func isf(_ q: Double) -> Double {231        guard a > 0, b > 0, q >= 0, q <= 1 else { return .nan }232        return quantilePair(p: 1 - q, q: q, usePUpper: true).x233    }234235    /// Solves I_x(a,b) = p and returns both x and y = 1 − x, each accurate near its own end of the236    /// interval. `usePUpper` says the upper-tail probability `q` is the exactly known one.237    func quantilePair(p: Double, q: Double, usePUpper: Bool) -> (x: Double, y: Double) {238        if p <= 0 || q >= 1 { return (0, 1) }239        if q <= 0 || p >= 1 { return (1, 0) }240        // Work in the variable whose tail is the small one: solve for x when p is small, for y otherwise.241        let solveLower = usePUpper ? q > 0.5 : p <= 0.5242        if solveLower {243            let target = usePUpper ? 1 - q : p244            let x = BetaDistribution.solve(a, b, target)245            return (x, 1 - x)246        }247        let target = usePUpper ? q : 1 - p248        let y = BetaDistribution.solve(b, a, target)     // I_y(b, a) = upper tail249        return (1 - y, y)250    }251252    /// The x in (0,1) with I_x(a,b) = p (intended for p ≤ ~0.5; any p works).253    private static func solve(_ a: Double, _ b: Double, _ p: Double) -> Double {254        // Initial guess: small-x expansion I_x ≈ x^a / (a B(a,b)), else the mean.255        let lb = SpecialFunctions.logBeta(a, b)256        var g = exp((log(p) + log(a) + lb) / a)257        if !(g > 0 && g < 1) || g > 0.9 { g = a / (a + b) }258        let pdf: (Double) -> Double = { x in exp((a - 1) * log(x) + (b - 1) * log1p(-x) - lb) }259        return SpecialFunctions.invertMonotone(target: p, increasing: true, lo: 0, hi: 1, guess: g,260                                               f: { SpecialFunctions.betaIPair(a, b, x: $0, y: 1 - $0).p }, derivative: pdf)261    }262}263
Files main
Menu

Theme