Repository Public
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