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/Autocorrelation.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/// Autocorrelation or partial autocorrelation function with confidence bands.91public struct AutocorrelationResult: Sendable, Hashable, Codable, TableReport {92 /// "ACF" or "PACF".93 public var kind: String94 /// Lags 0…maxLag.95 public var lags: [Int]96 /// Coefficient at each lag (lag 0 is 1).97 public var values: [Double]98 /// Standard error of each coefficient. ACF: Bartlett's formula99 /// se(r_k) = √((1 + 2·Σ_{j<k} r_j²)/n) (se(r_0) = 0); PACF: 1/√n for every lag ≥ 1.100 public var standardErrors: [Double]101 /// values − z·se and values + z·se (interval around the estimate, as statsmodels reports it).102 public var lower: [Double]103 public var upper: [Double]104 /// z/√n: the usual white-noise significance bound drawn on a correlogram (|coefficient| above it is105 /// significant at 1 − confidence under the white-noise null).106 public var whiteNoiseBound: Double107 public var confidence: Double108 public var n: Int109110 public func table() -> [[Value]] {111 var out: [[Value]] = [[.text("Lag"), .text(kind), .text("Std. error"), .text("Lower"), .text("Upper"), .text("±\(Int((confidence * 100).rounded()))% white-noise bound")]]112 for i in lags.indices {113 out.append([Report.int(lags[i]), Report.num(values[i]), Report.num(standardErrors[i]), Report.num(lower[i]), Report.num(upper[i]), Report.num(whiteNoiseBound)])114 }115 return out116 }117}118119/// Transformations and correlograms for equally spaced series.120public enum TimeSeries {121 // MARK: Differencing122123 /// Differences a series: (1 − B^lag)^order x. Each pass shortens the series by `lag`124 /// (`lag` = 1: regular differencing; `lag` = season length: seasonal differencing).125 public static func difference(_ x: [Double], lag: Int = 1, order: Int = 1) -> [Double] {126 precondition(lag >= 1 && order >= 0, "difference: lag ≥ 1 and order ≥ 0 required")127 var out = x128 for _ in 0..<order {129 guard out.count > lag else { return [] }130 out = (lag..<out.count).map { out[$0] - out[$0 - lag] }131 }132 return out133 }134135 /// Inverse of one differencing pass at `lag`: rebuilds the series whose first `lag` values are136 /// `initial` and whose lag-differences are `differences`. Result length = initial.count + differences.count.137 public static func integrate(_ differences: [Double], initial: [Double], lag: Int = 1) throws -> [Double] {138 guard lag >= 1, initial.count == lag else { throw StatError.invalidInput("integrate needs exactly `lag` initial values") }139 var out = initial140 out.reserveCapacity(lag + differences.count)141 for (i, d) in differences.enumerated() { out.append(out[i] + d) }142 return out143 }144145 /// Inverse of `difference(x, lag:, order:)`. `heads[k]` holds the first `lag` values of the series after146 /// k differencing passes (k = 0 … order − 1); `differenceHeads` produces them.147 public static func integrate(_ differences: [Double], heads: [[Double]], lag: Int = 1) throws -> [Double] {148 var out = differences149 for head in heads.reversed() { out = try integrate(out, initial: head, lag: lag) }150 return out151 }152153 /// The leading values needed to undo `difference(x, lag:, order:)` with `integrate(_:heads:lag:)`.154 public static func differenceHeads(_ x: [Double], lag: Int = 1, order: Int = 1) -> [[Double]] {155 var heads = [[Double]]()156 var cur = x157 for _ in 0..<order {158 heads.append(Array(cur.prefix(lag)))159 cur = difference(cur, lag: lag)160 }161 return heads162 }163164 // MARK: Autocovariance165166 /// Sample autocovariances γ̂_0…γ̂_maxLag with divisor n (the biased, positive semi-definite estimator):167 /// γ̂_k = (1/n) Σ_{t} (x_t − x̄)(x_{t+k} − x̄).168 public static func autocovariance(_ x: [Double], maxLag: Int) -> [Double] {169 let n = x.count170 guard n > 0 else { return [] }171 let m = Descriptive.mean(x)172 let d = x.map { $0 - m }173 return (0...max(0, min(maxLag, n - 1))).map { k in174 var s = 0.0175 for t in 0..<(n - k) { s += d[t] * d[t + k] }176 return s / Double(n)177 }178 }179180 /// Default number of lags, as statsmodels: min(⌊10·log10(n)⌋, n − 1).181 public static func defaultLags(_ n: Int) -> Int { max(1, min(Int(10 * log10(Double(max(n, 2)))), n - 1)) }182183 /// Autocorrelation function r_k = γ̂_k/γ̂_0 (divisor-n autocovariances, as `statsmodels.tsa.stattools.acf`184 /// with `adjusted=False`), with Bartlett standard errors and the white-noise bound z/√n.185 public static func acf(_ x: [Double], maxLag: Int? = nil, confidence: Double = 0.95) throws -> AutocorrelationResult {186 let n = x.count187 guard n >= 2 else { throw StatError.insufficientData("ACF needs at least 2 observations") }188 guard confidence > 0, confidence < 1 else { throw StatError.invalidInput("confidence must be in (0, 1)") }189 let k = min(maxLag ?? defaultLags(n), n - 1)190 guard k >= 0 else { throw StatError.invalidInput("maxLag must be ≥ 0") }191 let g = autocovariance(x, maxLag: k)192 guard g[0] > 0 else { throw StatError.invalidInput("series is constant") }193 let r = g.map { $0 / g[0] }194 let z = SpecialFunctions.normalQuantile(upper: (1 - confidence) / 2)195 var se = [Double](repeating: 0, count: k + 1)196 var cum = 0.0197 for j in 1..<max(1, k + 1) {198 se[j] = ((1 + 2 * cum) / Double(n)).squareRoot()199 cum += r[j] * r[j]200 }201 return AutocorrelationResult(kind: "ACF", lags: Array(0...k), values: r, standardErrors: se,202 lower: zip(r, se).map { $0 - z * $1 }, upper: zip(r, se).map { $0 + z * $1 },203 whiteNoiseBound: z / Double(n).squareRoot(), confidence: confidence, n: n)204 }205206 /// Partial autocorrelation function by the Durbin–Levinson recursion on the divisor-n sample207 /// autocorrelations (equal to `statsmodels.tsa.stattools.pacf` with `method="ldb"` / `"ywm"`).208 /// Standard error 1/√n for every lag ≥ 1 (large-sample result under an AR model of lower order).209 public static func pacf(_ x: [Double], maxLag: Int? = nil, confidence: Double = 0.95) throws -> AutocorrelationResult {210 let n = x.count211 guard n >= 3 else { throw StatError.insufficientData("PACF needs at least 3 observations") }212 guard confidence > 0, confidence < 1 else { throw StatError.invalidInput("confidence must be in (0, 1)") }213 let k = max(1, min(maxLag ?? defaultLags(n), n - 2))214 let g = autocovariance(x, maxLag: k)215 guard g[0] > 0 else { throw StatError.invalidInput("series is constant") }216 let r = g.map { $0 / g[0] }217 let p = durbinLevinson(r).pacf218 let z = SpecialFunctions.normalQuantile(upper: (1 - confidence) / 2)219 let s = 1 / Double(n).squareRoot()220 let se = [0.0] + [Double](repeating: s, count: k)221 return AutocorrelationResult(kind: "PACF", lags: Array(0...k), values: p, standardErrors: se,222 lower: zip(p, se).map { $0 - z * $1 }, upper: zip(p, se).map { $0 + z * $1 },223 whiteNoiseBound: z * s, confidence: confidence, n: n)224 }225226 /// Durbin–Levinson recursion on autocorrelations ρ_0 = 1, ρ_1…ρ_K. Returns the partial autocorrelations227 /// (index 0 = 1) and the AR(K) coefficients of the Yule–Walker fit.228 public static func durbinLevinson(_ rho: [Double]) -> (pacf: [Double], ar: [Double]) {229 let k = rho.count - 1230 guard k >= 1 else { return ([1], []) }231 var pacf = [1.0]232 var phi = [Double]()233 var v = 1.0234 for m in 1...k {235 var num = rho[m]236 for j in 0..<phi.count { num -= phi[j] * rho[m - 1 - j] }237 let a = v > 0 ? num / v : .nan238 var next = [Double](repeating: 0, count: m)239 for j in 0..<phi.count { next[j] = phi[j] - a * phi[m - 2 - j] }240 next[m - 1] = a241 phi = next242 v *= (1 - a * a)243 pacf.append(a)244 }245 return (pacf, phi)246 }247}248