Repository Public
1import Foundation23/// Numerical kernels shared by the regression routines (not public API).4enum RegressionMath {5 struct Core {6 var beta: [Double]7 /// Thin Q (n×k) of the design.8 var q: Matrix9 /// R⁻¹ (k×k upper triangular).10 var rInverse: Matrix11 /// (XᵀX)⁻¹ = R⁻¹ R⁻ᵀ.12 var xtxInverse: Matrix13 var fitted: [Double]14 var residuals: [Double]15 var leverage: [Double]16 var ssr: Double17 }1819 /// Relative size of a diagonal element of R below which the design is declared rank deficient.20 static let rankTolerance = 1e-102122 /// Least squares by Householder QR. Throws `.insufficientData` when n < k and `.singular`23 /// (naming the first dependent column) when the design does not have full column rank.24 static func solve(_ x: Matrix, _ y: [Double], names: [String]? = nil) throws -> Core {25 let n = x.rows, k = x.cols26 guard k > 0 else { throw StatError.invalidInput("the model has no regressors") }27 guard y.count == n else { throw StatError.invalidInput("y has \(y.count) observations but X has \(n) rows") }28 guard n >= k else { throw StatError.insufficientData("\(n) observations cannot identify \(k) coefficients") }29 guard y.allSatisfy(\.isFinite), x.data.allSatisfy(\.isFinite) else { throw StatError.invalidInput("data contain non-finite values") }30 let (q, r) = try LinearAlgebra.qr(x)31 // column scale: a column is dependent when its R diagonal is negligible relative to its own norm32 for j in 0..<k {33 var norm = 0.034 for i in 0..<n { norm += x[i, j] * x[i, j] }35 norm = norm.squareRoot()36 if !(abs(r[j, j]) > rankTolerance * max(norm, Double.leastNormalMagnitude)) || norm == 0 {37 let label = names.flatMap { j < $0.count ? $0[j] : nil } ?? "column \(j + 1)"38 throw StatError.singular("the design matrix is rank deficient: '\(label)' is (numerically) a linear combination of the preceding columns")39 }40 }41 var rinv = Matrix(rows: k, cols: k)42 for j in 0..<k {43 var e = [Double](repeating: 0, count: k)44 e[j] = 145 let col = try LinearAlgebra.backSubstitute(r, e)46 for i in 0..<k { rinv[i, j] = col[i] }47 }48 let qty = q.transposed * y49 let beta = rinv * qty50 let fitted = x * beta51 var resid = [Double](repeating: 0, count: n)52 var ssr = 0.053 for i in 0..<n { resid[i] = y[i] - fitted[i]; ssr += resid[i] * resid[i] }54 var lev = [Double](repeating: 0, count: n)55 for i in 0..<n {56 var s = 0.057 for j in 0..<k { s += q[i, j] * q[i, j] }58 lev[i] = min(1, s)59 }60 return Core(beta: beta, q: q, rInverse: rinv, xtxInverse: rinv * rinv.transposed, fitted: fitted, residuals: resid, leverage: lev, ssr: ssr)61 }6263 static func centeredSS(_ y: [Double]) -> Double {64 let m = Descriptive.mean(y)65 return y.reduce(0) { $0 + ($1 - m) * ($1 - m) }66 }6768 static func uncenteredSS(_ y: [Double]) -> Double { y.reduce(0) { $0 + $1 * $1 } }6970 /// Sandwich A · M · A for symmetric A.71 static func sandwich(_ bread: Matrix, _ meat: Matrix) -> Matrix { bread * meat * bread }7273 /// Σ ωᵢ xᵢ xᵢᵀ.74 static func weightedGram(_ x: Matrix, _ w: [Double]) -> Matrix {75 let n = x.rows, k = x.cols76 var m = Matrix(rows: k, cols: k)77 for i in 0..<n {78 let wi = w[i]79 for a in 0..<k {80 let xa = x[i, a] * wi81 for b in a..<k { m[a, b] += xa * x[i, b] }82 }83 }84 for a in 0..<k { for b in 0..<a { m[a, b] = m[b, a] } }85 return m86 }8788 /// Wald statistic bᵀ V⁻¹ b for the sub-vector `idx` of the coefficients.89 static func wald(_ beta: [Double], _ cov: Matrix, _ idx: [Int]) throws -> Double {90 let q = idx.count91 var v = Matrix(rows: q, cols: q)92 for (a, i) in idx.enumerated() { for (b, j) in idx.enumerated() { v[a, b] = cov[i, j] } }93 let b = idx.map { beta[$0] }94 let sol = try LinearAlgebra.solve(v, b)95 return zip(b, sol).reduce(0) { $0 + $1.0 * $1.1 }96 }9798 /// Indices of a maximal set of linearly independent columns (greedy modified Gram–Schmidt, in order).99 static func independentColumns(_ cols: [[Double]], tolerance: Double = 1e-9) -> [Int] {100 var basis = [[Double]]()101 var keep = [Int]()102 for (j, c) in cols.enumerated() {103 let norm0 = c.reduce(0) { $0 + $1 * $1 }.squareRoot()104 guard norm0 > 0 else { continue }105 var v = c106 for _ in 0..<2 { // re-orthogonalise once for stability107 for b in basis {108 var d = 0.0109 for i in v.indices { d += v[i] * b[i] }110 for i in v.indices { v[i] -= d * b[i] }111 }112 }113 let norm = v.reduce(0) { $0 + $1 * $1 }.squareRoot()114 if norm > tolerance * norm0 {115 basis.append(v.map { $0 / norm })116 keep.append(j)117 }118 }119 return keep120 }121122 /// Whether a column is constant and non-zero.123 static func isConstantColumn(_ x: Matrix, _ j: Int) -> Bool {124 guard x.rows > 0, x[0, j] != 0 else { return false }125 let v = x[0, j]126 for i in 1..<max(1, x.rows) where x[i, j] != v { return false }127 return true128 }129}130