Repository Public
1import Foundation23/// A fitted binary logistic regression (logit link, maximum likelihood by IRLS).4///5/// Conventions (statsmodels `Logit`): standard errors from the inverse observed information6/// (XᵀWX)⁻¹, z statistics with two-sided normal p-values, McFadden pseudo-R² = 1 − ℓ/ℓ₀ where ℓ₀ is the7/// log-likelihood of the constant-only model, likelihood-ratio χ²(df_model) test (upper tail),8/// AIC = −2ℓ + 2k, BIC = −2ℓ + k ln n.9public struct LogisticResult: Codable, Sendable, Hashable {10 public var dependentName: String11 public var names: [String]12 public var hasIntercept: Bool13 public var nobs: Int14 public var dfModel: Int15 public var dfResidual: Int16 public var coefficients: [Double]17 public var standardErrors: [Double]18 /// z statistics.19 public var statistics: [Double]20 /// Two-sided normal p-values.21 public var pValues: [Double]22 /// Wald confidence limits of the coefficients.23 public var ciLower: [Double]24 public var ciUpper: [Double]25 public var confidenceLevel: Double26 /// exp(coefficient); exponentiate `ciLower`/`ciUpper` for their limits.27 public var oddsRatios: [Double]28 public var covariance: Matrix29 public var logLikelihood: Double30 /// Log-likelihood of the constant-only model.31 public var nullLogLikelihood: Double32 public var pseudoRSquared: Double33 /// Likelihood-ratio statistic 2(ℓ − ℓ₀) ~ χ²(dfModel).34 public var lrStatistic: Double35 /// Upper-tail p-value of the likelihood-ratio test (nil for a model without regressors besides the constant).36 public var lrPValue: Double?37 public var aic: Double38 public var bic: Double39 public var iterations: Int40 public var converged: Bool41 /// Fitted probabilities P(y = 1).42 public var fittedProbabilities: [Double]43 public var threshold: Double44 /// Classification counts at `threshold` (predicted 1 when p̂ > threshold): [[TN, FP], [FN, TP]] — rows = actual 0/1, columns = predicted 0/1.45 public var classificationTable: [[Int]]4647 public var accuracy: Double {48 Double(classificationTable[0][0] + classificationTable[1][1]) / Double(nobs)49 }50 /// True-positive rate TP / (TP + FN).51 public var sensitivity: Double { Double(classificationTable[1][1]) / Double(classificationTable[1][0] + classificationTable[1][1]) }52 /// True-negative rate TN / (TN + FP).53 public var specificity: Double { Double(classificationTable[0][0]) / Double(classificationTable[0][0] + classificationTable[0][1]) }5455 /// P(y = 1) for new rows of regressors (without the constant column when the model added one).56 public func predict(_ x: Matrix) throws -> [Double] {57 let expect = names.count - (hasIntercept ? 1 : 0)58 guard x.cols == expect else { throw StatError.invalidInput("expected \(expect) regressors, got \(x.cols)") }59 return (0..<x.rows).map { r in60 var s = hasIntercept ? coefficients[0] : 061 for c in 0..<x.cols { s += x[r, c] * coefficients[c + (hasIntercept ? 1 : 0)] }62 return 1 / (1 + exp(-s))63 }64 }65}6667public enum LogisticRegression {68 /// Fits P(y = 1 | x) = 1 / (1 + exp(−x'β)) by iteratively reweighted least squares (Newton–Raphson69 /// with step halving), each step solved by QR.70 ///71 /// - Parameters:72 /// - y: outcomes coded 0 or 1.73 /// - x: regressors without a constant column.74 /// - threshold: cut-off for the classification table.75 /// - Throws: `.notConverged` on complete or quasi-complete separation (the MLE does not exist) or when the76 /// iteration limit is reached; `.singular` for collinear regressors; `.invalidInput` when y is not binary or has a single class.77 public static func fit(y: [Double], x: Matrix, names: [String]? = nil, intercept: Bool = true, threshold: Double = 0.5,78 confidenceLevel: Double = 0.95, maxIterations: Int = 100, tolerance: Double = 1e-10,79 dependentName: String = "y") throws -> LogisticResult {80 let n = y.count81 guard x.rows == n else { throw StatError.invalidInput("y has \(n) observations but X has \(x.rows) rows") }82 guard y.allSatisfy({ $0 == 0 || $0 == 1 }) else { throw StatError.invalidInput("the dependent variable must be coded 0/1") }83 if let names, names.count != x.cols { throw StatError.invalidInput("\(names.count) names for \(x.cols) regressors") }84 guard confidenceLevel > 0, confidenceLevel < 1 else { throw StatError.invalidInput("confidence level must be in (0, 1)") }85 let ones = y.reduce(0, +)86 guard ones > 0, ones < Double(n) else { throw StatError.invalidInput("the dependent variable has a single class") }87 var colNames = names ?? (0..<x.cols).map { "x\($0 + 1)" }88 var design = x89 if intercept {90 var d = Matrix(rows: n, cols: x.cols + 1)91 for i in 0..<n { d[i, 0] = 1; for j in 0..<x.cols { d[i, j + 1] = x[i, j] } }92 design = d93 colNames.insert("const", at: 0)94 }95 let k = design.cols96 guard k > 0 else { throw StatError.invalidInput("the model has no regressors") }97 guard n > k else { throw StatError.insufficientData("\(n) observations for \(k) coefficients") }98 _ = try RegressionMath.solve(design, y, names: colNames) // rank check with a clear message99100 func logLik(_ beta: [Double]) -> (ll: Double, eta: [Double]) {101 let eta = design * beta102 var ll = 0.0103 for i in 0..<n {104 // ln σ(η) = −ln(1 + e^{−η}); ln(1 − σ(η)) = −ln(1 + e^{η}), written stably105 let e = y[i] == 1 ? -eta[i] : eta[i]106 ll -= e > 0 ? e + log1p(exp(-e)) : log1p(exp(e))107 }108 return (ll, eta)109 }110 func separated(_ eta: [Double]) -> Bool {111 // every observation on the correct side of the boundary with a (near) certain prediction112 var minMargin = Double.infinity113 for i in 0..<n { minMargin = min(minMargin, y[i] == 1 ? eta[i] : -eta[i]) }114 return minMargin > 0115 }116117 var beta = [Double](repeating: 0, count: k)118 var (ll, eta) = logLik(beta)119 var converged = false120 var iterations = 0121 var xtwxInv = Matrix(rows: k, cols: k)122 while iterations < maxIterations {123 iterations += 1124 var xw = design125 var z = [Double](repeating: 0, count: n)126 for i in 0..<n {127 let p = 1 / (1 + exp(-eta[i]))128 let w = max(p * (1 - p), 1e-300)129 let s = w.squareRoot()130 for j in 0..<k { xw[i, j] *= s }131 z[i] = s * (eta[i] + (y[i] - p) / w)132 }133 let core: RegressionMath.Core134 do { core = try RegressionMath.solve(xw, z, names: colNames) } catch {135 if separated(eta) { throw StatError.notConverged("perfect separation: the regressors predict the outcome exactly, so the maximum-likelihood estimate does not exist") }136 throw error137 }138 xtwxInv = core.xtxInverse139 var step = zip(core.beta, beta).map { $0 - $1 }140 var (newLL, newEta) = logLik(core.beta)141 var candidate = core.beta142 var halvings = 0143 while !(newLL >= ll - 1e-12 * abs(ll)) && halvings < 30 {144 halvings += 1145 step = step.map { $0 / 2 }146 candidate = zip(beta, step).map(+)147 (newLL, newEta) = logLik(candidate)148 }149 let change = zip(candidate, beta).map { abs($0 - $1) }.max() ?? 0150 let scale = max(1, candidate.map { abs($0) }.max() ?? 1)151 let llChange = abs(newLL - ll)152 beta = candidate; ll = newLL; eta = newEta153 if separated(eta) && (ll > -1e-6 || (beta.map { abs($0) }.max() ?? 0) > 1e3 || iterations > 25) {154 throw StatError.notConverged("perfect separation: the regressors predict the outcome exactly, so the maximum-likelihood estimate does not exist")155 }156 if change <= tolerance * scale && llChange <= tolerance * max(1, abs(ll)) { converged = true; break }157 }158 guard converged else {159 throw StatError.notConverged("logistic regression did not converge in \(maxIterations) iterations (possible quasi-complete separation)")160 }161 // covariance at the solution162 var xw = design163 var probs = [Double](repeating: 0, count: n)164 for i in 0..<n {165 let p = 1 / (1 + exp(-eta[i]))166 probs[i] = p167 let s = (p * (1 - p)).squareRoot()168 for j in 0..<k { xw[i, j] *= s }169 }170 if let (_, r) = try? LinearAlgebra.qr(xw), let rinv = try? LinearAlgebra.inverse(r) { xtwxInv = rinv * rinv.transposed }171 let se = (0..<k).map { xtwxInv[$0, $0].squareRoot() }172 if se.contains(where: { !$0.isFinite || $0 > 1e6 * max(1, (beta.map { abs($0) }.max() ?? 1)) }) {173 throw StatError.notConverged("quasi-complete separation: at least one coefficient is not identified (its standard error diverges)")174 }175 let stat = (0..<k).map { beta[$0] / se[$0] }176 let normal = NormalDistribution.standard177 let crit = normal.isf((1 - confidenceLevel) / 2)178 let nd = Double(n)179 let pbar = ones / nd180 let llNull = ones * log(pbar) + (nd - ones) * log(1 - pbar)181 let hasConst = intercept || (0..<k).contains { RegressionMath.isConstantColumn(design, $0) }182 let dfModel = k - (hasConst ? 1 : 0)183 var table = [[0, 0], [0, 0]]184 for i in 0..<n { table[Int(y[i])][probs[i] > threshold ? 1 : 0] += 1 }185 let lr = 2 * (ll - llNull)186 return LogisticResult(187 dependentName: dependentName, names: colNames, hasIntercept: intercept, nobs: n, dfModel: dfModel, dfResidual: n - k,188 coefficients: beta, standardErrors: se, statistics: stat, pValues: stat.map { 2 * normal.sf(abs($0)) },189 ciLower: (0..<k).map { beta[$0] - crit * se[$0] }, ciUpper: (0..<k).map { beta[$0] + crit * se[$0] },190 confidenceLevel: confidenceLevel, oddsRatios: beta.map { exp($0) }, covariance: xtwxInv, logLikelihood: ll,191 nullLogLikelihood: llNull, pseudoRSquared: 1 - ll / llNull, lrStatistic: lr,192 lrPValue: dfModel > 0 ? ChiSquaredDistribution(df: Double(dfModel)).sf(lr) : nil,193 aic: -2 * ll + 2 * Double(k), bic: -2 * ll + log(nd) * Double(k), iterations: iterations, converged: true,194 fittedProbabilities: probs, threshold: threshold, classificationTable: table)195 }196}197