Repository Public
1// =============================================================================2// SP BOUCHER | SOFTWARE & RESEARCH3// ARTIFICIAL INTELLIGENCE • FINANCE • ENGINEERING4// =============================================================================5//6// PROJECT METADATA7// -----------------------------------------------------------------------------8// Project : ORIX Sheet9// File : Packages/SheetAnalytics/Sources/Statistics/TimeSeries/ARIMA.swift10// Module : Statistics11// Repository : https://git.spboucher.ai/orix-sheet12// Created : 2026-11-2113// Last Modified : 2026-11-2114//15// =============================================================================16// AUTHOR & PROFESSIONAL AFFILIATION17// =============================================================================18//19// Author : Simon-Pierre Boucher20// Position : Professor of Finance21// Institution : Université du Québec en Outaouais (UQO)22// Department : Département des sciences administratives23// Organization : SP Boucher24//25// Website : https://spboucher.ai26// Git : https://git.spboucher.ai27//28// =============================================================================29// OFFICIAL CONTACT DIRECTORY30// =============================================================================31//32// General : info@spboucher.ai33// Professional : contact@spboucher.ai34// Direct : simon@spboucher.ai35// Research : research@spboucher.ai36// Development : dev@spboucher.ai37// Support : support@spboucher.ai38// Security/Admin : admin@spboucher.ai39// Notifications : notifications@spboucher.ai40//41// Preferred Contact: support@spboucher.ai42//43// =============================================================================44// COPYRIGHT & INTELLECTUAL PROPERTY45// =============================================================================46//47// Copyright (c) 202648// Simon-Pierre Boucher49//50// All rights reserved where applicable.51//52// This file is governed by the applicable project license,53// copyright notices, institutional agreements and relevant law.54//55// Unless expressly authorized by the applicable license or56// rights holder, copying, redistribution, sublicensing,57// publication and commercial exploitation are not permitted.58//59// Existing third-party rights and notices remain unaffected.60//61// =============================================================================62// CONFIDENTIALITY & SECURITY63// =============================================================================64//65// Classification : Public66// Distribution : Public repository; use is governed by the project license67// Security Contact : admin@spboucher.ai68//69// Access to this source does not independently grant permission70// to redistribute or disclose confidential materials.71//72// Do not embed credentials, private keys, access tokens,73// certificates or confidential personal information.74//75// =============================================================================76// LICENSE & MAINTENANCE77// =============================================================================78//79// License : None specified (no license file in this repository)80// Maintainer : Simon-Pierre Boucher81// Technical Contact: dev@spboucher.ai82//83// =============================================================================84// END OF SP BOUCHER SOURCE HEADER85// =============================================================================8687import Foundation88import SheetCore8990/// ARIMA(p, d, q) models estimated by exact Gaussian maximum likelihood.91///92/// Model for w_t = (1 − B)^d y_t:93///94/// (w_t − μ) = φ_1 (w_{t−1} − μ) + … + φ_p (w_{t−p} − μ) + ε_t + θ_1 ε_{t−1} + … + θ_q ε_{t−q}, ε_t ~ N(0, σ²)95///96/// (the MA sign convention of R and statsmodels). Estimation: the series is differenced d times, then97/// the exact likelihood of the stationary ARMA(p, q) is evaluated with the Kalman filter (stationary98/// initial state covariance) and maximised by Nelder–Mead over parameters transformed to keep the AR part99/// stationary and the MA part invertible; σ² is concentrated out (σ̂² = (1/n) Σ v_t²/f_t). This equals100/// `statsmodels` `ARIMA(w, order=(p, 0, q)).fit()` on the differenced series (SARIMAX with101/// `simple_differencing=True`). μ is the mean of the differenced series: the process mean when d = 0,102/// the drift when d = 1.103public enum ARIMA {104 public struct Order: Sendable, Hashable, Codable {105 public var p: Int106 public var d: Int107 public var q: Int108 public init(p: Int, d: Int, q: Int) { self.p = p; self.d = d; self.q = q }109 }110111 public struct Parameters: Sendable, Hashable, Codable {112 /// φ_1…φ_p.113 public var ar: [Double]114 /// θ_1…θ_q.115 public var ma: [Double]116 /// μ; nil = no mean/drift term.117 public var mean: Double?118 /// Innovation variance σ².119 public var sigma2: Double120 public init(ar: [Double] = [], ma: [Double] = [], mean: Double? = nil, sigma2: Double) {121 self.ar = ar; self.ma = ma; self.mean = mean; self.sigma2 = sigma2122 }123 }124125 /// Exact log-likelihood of the differenced series at the given parameters126 /// (−∞-like failures throw: non-stationary AR part).127 public static func logLikelihood(_ y: [Double], order: Order, parameters: Parameters) throws -> Double {128 try evaluate(y, order: order, parameters: parameters).logLikelihood129 }130131 /// Fits the model. With `fixed` parameters nothing is estimated: the filter is run at those values132 /// (standard errors are then not reported).133 /// - Parameter includeMean: nil = include μ when d = 0 and omit it when d > 0.134 public static func fit(_ y: [Double], order: Order, includeMean: Bool? = nil, fixed: Parameters? = nil) throws -> ARIMAFit {135 if let fixed { return try evaluate(y, order: order, parameters: fixed) }136 let (p, d, q) = (order.p, order.d, order.q)137 guard p >= 0, d >= 0, q >= 0, d <= 3 else { throw StatError.invalidInput("ARIMA order must have p, q ≥ 0 and 0 ≤ d ≤ 3") }138 guard y.allSatisfy(\.isFinite) else { throw StatError.invalidInput("series contains non-finite values") }139 let w = TimeSeries.difference(y, order: d)140 let withMean = includeMean ?? (d == 0)141 let k = p + q + (withMean ? 1 : 0)142 guard w.count >= max(10, 2 * (k + 1) + max(p, q)) else { throw StatError.insufficientData("too few observations for ARIMA(\(p),\(d),\(q))") }143 let wbar = Descriptive.mean(w)144 let scale = max(Descriptive.standardDeviation(w, sample: false), 1e-300)145 let n = Double(w.count)146147 func unpack(_ v: [Double]) -> (mean: Double?, ar: [Double], ma: [Double]) {148 var i = 0149 var mu: Double?150 if withMean { mu = wbar + v[0] * scale; i = 1 }151 let ar = ARMAKalman.stationaryCoefficients(Array(v[i..<(i + p)]))152 let ma = ARMAKalman.stationaryCoefficients(Array(v[(i + p)..<(i + p + q)])).map { -$0 }153 return (mu, ar, ma)154 }155 // concentrated negative log-likelihood (up to constants): n/2·ln(σ̂²) + ½ Σ ln f156 let objective: ([Double]) -> Double = { v in157 let u = unpack(v)158 let centred = u.mean.map { m in w.map { $0 - m } } ?? w159 guard let out = ARMAKalman(ar: u.ar, ma: u.ma).filter(centred), out.sumSquares > 0 else { return .greatestFiniteMagnitude }160 let val = 0.5 * n * log(out.sumSquares / n) + 0.5 * out.sumLogF161 return val.isFinite ? val : .greatestFiniteMagnitude162 }163 var best: MinimizeResult?164 if k == 0 {165 best = MinimizeResult(x: [], value: objective([]), iterations: 0, functionEvaluations: 1, converged: true, method: "none")166 } else {167 var opt = Minimizer.NelderMeadOptions()168 opt.xtol = 1e-9; opt.ftol = 1e-11169 opt.maxIterations = 3000 * k; opt.maxEvaluations = 6000 * k170 opt.restarts = 6171 var starts = [[Double](repeating: 0.1, count: k), [Double](repeating: -0.3, count: k)]172 var alt = [Double](repeating: 0.5, count: k)173 for i in alt.indices where i % 2 == 1 { alt[i] = -0.5 }174 starts.append(alt)175 for var s in starts {176 if withMean { s[0] = 0 }177 let r = try Minimizer.nelderMead(objective, start: s, options: opt)178 if best == nil || r.value < best!.value { best = r }179 }180 }181 let u = unpack(best!.x)182 let centred = u.mean.map { m in w.map { $0 - m } } ?? w183 guard let out = ARMAKalman(ar: u.ar, ma: u.ma).filter(centred) else { throw StatError.notConverged("ARIMA likelihood could not be evaluated") }184 let params = Parameters(ar: u.ar, ma: u.ma, mean: u.mean, sigma2: out.sumSquares / n)185 var fit = try evaluate(y, order: order, parameters: params)186 fit.estimated = true187 fit.converged = best!.converged188 fit.standardErrors = standardErrors(w, params)189 return fit190 }191192 /// Full (unconcentrated) log-likelihood in the natural parameters [μ?, φ…, θ…, σ²].193 private static func fullLogLikelihood(_ w: [Double], _ x: [Double], p: Int, q: Int, withMean: Bool) -> Double {194 var i = 0195 var centred = w196 if withMean { let m = x[0]; centred = w.map { $0 - m }; i = 1 }197 let ar = Array(x[i..<(i + p)]), ma = Array(x[(i + p)..<(i + p + q)])198 let s2 = x[i + p + q]199 guard s2 > 0, let out = ARMAKalman(ar: ar, ma: ma).filter(centred) else { return .nan }200 let n = Double(w.count)201 return -0.5 * n * log(2 * Double.pi * s2) - 0.5 * out.sumLogF - 0.5 * out.sumSquares / s2202 }203204 /// Standard errors from the observed information: inverse of the numerical Hessian (central205 /// differences) of the negative log-likelihood in [μ?, φ…, θ…, σ²]. Nil entries when the Hessian206 /// is not positive definite (e.g. an estimate on the boundary of the admissible region).207 private static func standardErrors(_ w: [Double], _ prm: Parameters) -> [Double?] {208 let withMean = prm.mean != nil209 let p = prm.ar.count, q = prm.ma.count210 let x0 = (prm.mean.map { [$0] } ?? []) + prm.ar + prm.ma + [prm.sigma2]211 let k = x0.count212 let sd = Descriptive.standardDeviation(w, sample: false)213 var steps = [Double](repeating: 1e-4, count: k)214 if withMean { steps[0] = 1e-4 * max(sd, abs(x0[0]) * 1e-2) }215 steps[k - 1] = 1e-4 * prm.sigma2216 func f(_ x: [Double]) -> Double { -fullLogLikelihood(w, x, p: p, q: q, withMean: withMean) }217 let f0 = f(x0)218 var h = Matrix(rows: k, cols: k)219 for i in 0..<k {220 var xp = x0, xm = x0221 xp[i] += steps[i]; xm[i] -= steps[i]222 h[i, i] = (f(xp) - 2 * f0 + f(xm)) / (steps[i] * steps[i])223 for j in 0..<i {224 var a = x0, b = x0, c = x0, d = x0225 a[i] += steps[i]; a[j] += steps[j]226 b[i] += steps[i]; b[j] -= steps[j]227 c[i] -= steps[i]; c[j] += steps[j]228 d[i] -= steps[i]; d[j] -= steps[j]229 let v = (f(a) - f(b) - f(c) + f(d)) / (4 * steps[i] * steps[j])230 h[i, j] = v; h[j, i] = v231 }232 }233 guard h.data.allSatisfy(\.isFinite), let inv = try? LinearAlgebra.inverse(h) else { return Array(repeating: nil, count: k) }234 return (0..<k).map { inv[$0, $0] > 0 ? inv[$0, $0].squareRoot() : nil }235 }236237 private static func evaluate(_ y: [Double], order: Order, parameters prm: Parameters) throws -> ARIMAFit {238 guard order.p == prm.ar.count, order.q == prm.ma.count else { throw StatError.invalidInput("parameter counts do not match the order") }239 guard order.d >= 0, order.d <= 3 else { throw StatError.invalidInput("0 ≤ d ≤ 3 required") }240 guard prm.sigma2 > 0 else { throw StatError.invalidInput("sigma2 must be positive") }241 let w = TimeSeries.difference(y, order: order.d)242 guard w.count >= 2 else { throw StatError.insufficientData("too few observations after differencing") }243 let mu = prm.mean ?? 0244 let kf = ARMAKalman(ar: prm.ar, ma: prm.ma)245 guard let out = kf.filter(w.map { $0 - mu }) else { throw StatError.invalidInput("the AR part is not stationary") }246 let n = Double(w.count)247 let ll = -0.5 * n * log(2 * Double.pi * prm.sigma2) - 0.5 * out.sumLogF - 0.5 * out.sumSquares / prm.sigma2248 let k = Double(order.p + order.q + 1 + (prm.mean != nil ? 1 : 0))249 var names = [String]()250 if prm.mean != nil { names.append(order.d == 0 ? "mean" : "drift") }251 names += (0..<order.p).map { "ar.L\($0 + 1)" } + (0..<order.q).map { "ma.L\($0 + 1)" } + ["sigma2"]252 var lastLevels = [Double]() // last value of y, Δy, Δ²y … (for integrating forecasts)253 var cur = y254 for _ in 0..<order.d { lastLevels.append(cur.last ?? 0); cur = TimeSeries.difference(cur) }255 return ARIMAFit(order: order, parameters: prm, parameterNames: names,256 estimates: (prm.mean.map { [$0] } ?? []) + prm.ar + prm.ma + [prm.sigma2],257 standardErrors: Array(repeating: nil, count: names.count),258 logLikelihood: ll, aic: -2 * ll + 2 * k, bic: -2 * ll + k * log(n), nobs: w.count,259 residuals: out.innovations,260 standardizedResiduals: zip(out.innovations, out.scaledVariances).map { $0 / ($1 * prm.sigma2).squareRoot() },261 fitted: zip(y.suffix(w.count), out.innovations).map { $0 - $1 },262 estimated: false, converged: true,263 finalState: out.state, finalCovariance: out.covariance, lastLevels: lastLevels)264 }265}266267/// A fitted (or evaluated) ARIMA model.268public struct ARIMAFit: Sendable, Hashable, Codable, TableReport {269 public var order: ARIMA.Order270 public var parameters: ARIMA.Parameters271 /// "mean"/"drift", "ar.L1"…, "ma.L1"…, "sigma2".272 public var parameterNames: [String]273 public var estimates: [Double]274 /// Observed-information standard errors (nil when parameters were fixed or the Hessian is unusable).275 public var standardErrors: [Double?]276 /// Exact Gaussian log-likelihood of the differenced series.277 public var logLikelihood: Double278 /// −2·lnL + 2k, k = p + q + 1 (σ²) + 1 if a mean is included.279 public var aic: Double280 /// −2·lnL + k·ln(n), n = observations after differencing.281 public var bic: Double282 /// Observations after differencing.283 public var nobs: Int284 /// One-step prediction errors (innovations) for observations d+1…N.285 public var residuals: [Double]286 /// Innovations divided by their predicted standard deviations.287 public var standardizedResiduals: [Double]288 /// One-step-ahead predictions of y for observations d+1…N.289 public var fitted: [Double]290 public var estimated: Bool291 public var converged: Bool292 var finalState: [Double]293 var finalCovariance: [Double]294 var lastLevels: [Double]295296 /// z statistics estimate/se (nil without a standard error).297 public var zStatistics: [Double?] { zip(estimates, standardErrors).map { e, s in s.map { e / $0 } } }298 /// Two-sided normal p-values of the z statistics.299 public var pValues: [Double?] { zStatistics.map { z in z.map { 2 * NormalDistribution.standard.sf(abs($0)) } } }300301 /// Forecasts of y for horizons 1…h with exact finite-sample prediction standard errors (state302 /// uncertainty at the end of the sample included; parameter uncertainty ignored) and normal intervals.303 public func forecast(_ h: Int, confidence: Double = 0.95) throws -> ForecastInterval {304 guard h > 0 else { throw StatError.invalidInput("horizon must be ≥ 1") }305 guard confidence > 0, confidence < 1 else { throw StatError.invalidInput("confidence must be in (0, 1)") }306 let kf = ARIMA.ARMAKalman(ar: parameters.ar, ma: parameters.ma)307 let r = kf.r308 let mu = parameters.mean ?? 0309 // forecasts of the differenced series and the covariance of their errors (σ² = 1)310 var a = finalState, p = finalCovariance311 var wMean = [Double]()312 var cov = Matrix(rows: h, cols: h)313 for i in 0..<h {314 wMean.append(a[0] + mu)315 var g = Array(p[0..<r]) // Z P_i316 for j in i..<h {317 cov[i, j] = g[0]; cov[j, i] = g[0]318 if j + 1 < h { // g ← g Tᵀ319 var next = [Double](repeating: 0, count: r)320 for c in 0..<r { next[c] = (c < parameters.ar.count ? parameters.ar[c] * g[0] : 0) + (c + 1 < r ? g[c + 1] : 0) }321 g = next322 }323 }324 a = kf.transition(a)325 p = kf.propagate(p)326 }327 // integrate d times: cumulative sums of means (from the last observed levels) and of the error covariance328 var mean = wMean329 for level in lastLevels.reversed() {330 var acc = level331 mean = mean.map { acc += $0; return acc }332 for i in 0..<h { for j in 1..<max(h, 1) { cov[i, j] += cov[i, j - 1] } } // C Sᵀ333 for j in 0..<h { for i in 1..<max(h, 1) { cov[i, j] += cov[i - 1, j] } } // S C334 }335 let z = SpecialFunctions.normalQuantile(upper: (1 - confidence) / 2)336 let se = (0..<h).map { (parameters.sigma2 * max(cov[$0, $0], 0)).squareRoot() }337 return ForecastInterval(horizon: Array(1...h), mean: mean, standardError: se,338 lower: zip(mean, se).map { $0 - z * $1 }, upper: zip(mean, se).map { $0 + z * $1 },339 confidence: confidence)340 }341342 public func table() -> [[Value]] {343 var out: [[Value]] = [344 Report.row("Model", "ARIMA(\(order.p),\(order.d),\(order.q)) — exact maximum likelihood"),345 Report.row("Observations used", nobs),346 Report.row("Log-likelihood", logLikelihood),347 Report.row("AIC", aic),348 Report.row("BIC", bic),349 [.text("Parameter"), .text("Estimate"), .text("Std. error"), .text("z"), .text("p-value (two-sided)")],350 ]351 let z = zStatistics, pv = pValues352 for i in parameterNames.indices {353 out.append([.text(parameterNames[i]), Report.num(estimates[i]), Report.num(standardErrors[i]), Report.num(z[i]), Report.num(pv[i])])354 }355 return Report.rectangular(out)356 }357}358