SPB Git

Repository Public

Autocorrelation.swift 11.6 KB 248 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/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
Files main
Menu

Theme