SPB Git

Repository Public

ARIMA.swift 18.4 KB 358 lines swift

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
Files main
Menu

Theme