SPB Git

Repository Public

TimeSeriesTests.swift 18.8 KB 316 lines swift

1// =============================================================================2//                  SP BOUCHER | SOFTWARE & RESEARCH3//             ARTIFICIAL INTELLIGENCE • FINANCE • ENGINEERING4// =============================================================================5//6// PROJECT METADATA7// -----------------------------------------------------------------------------8// Project          : ORIX Sheet9// File             : Packages/SheetAnalytics/Tests/StatisticsTests/TimeSeriesTests.swift10// Module           : StatisticsTests11// 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 Testing89import AnalyticsTestSupport90@testable import Statistics9192private let tsFixture = Fixture.load("timeseries", .module)93private func series(_ name: String) -> [Double] {94    name == "trend_stationary" ? tsFixture["adf_series"][name].arr : tsFixture["series"][name].arr95}9697@Suite struct TimeSeriesDifferencingTests {98    @Test func differencesMatchNumPy() {99        let y = series("seasonal"), f = tsFixture["diff"]100        #expect(allClose(TimeSeries.difference(y), f["d1"].arr, rel: 1e-13, abs: 1e-12))101        #expect(allClose(TimeSeries.difference(y, order: 2), f["d2"].arr, rel: 1e-13, abs: 1e-12))102        #expect(allClose(TimeSeries.difference(y, lag: 12), f["s12"].arr, rel: 1e-13, abs: 1e-12))103        #expect(allClose(TimeSeries.difference(TimeSeries.difference(y, lag: 12)), f["s12_d1"].arr, rel: 1e-13, abs: 1e-12))104        #expect(TimeSeries.difference([1, 2], lag: 3).isEmpty)105        #expect(TimeSeries.difference([1, 4, 9, 16], order: 0) == [1, 4, 9, 16])106        #expect(TimeSeries.difference([1, 4, 9, 16]) == [3, 5, 7])107        #expect(TimeSeries.difference([1, 4, 9, 16], order: 2) == [2, 2])108    }109110    @Test func integrationInvertsDifferencing() throws {111        let y = series("seasonal")112        let back = try TimeSeries.integrate(TimeSeries.difference(y), initial: [y[0]])113        #expect(allClose(back, y, rel: 1e-12))114        let s = try TimeSeries.integrate(TimeSeries.difference(y, lag: 12), initial: Array(y.prefix(12)), lag: 12)115        #expect(allClose(s, y, rel: 1e-12))116        let heads = TimeSeries.differenceHeads(y, order: 2)117        #expect(heads.count == 2 && heads[0] == [y[0]] && heads[1] == [y[1] - y[0]])118        let twice = try TimeSeries.integrate(TimeSeries.difference(y, order: 2), heads: heads)119        #expect(allClose(twice, y, rel: 1e-11))120        let sh = TimeSeries.differenceHeads(y, lag: 12, order: 2)121        let stwice = try TimeSeries.integrate(TimeSeries.difference(y, lag: 12, order: 2), heads: sh, lag: 12)122        #expect(allClose(stwice, y, rel: 1e-11))123        #expect(throws: StatError.self) { try TimeSeries.integrate([1, 2], initial: [1, 2], lag: 1) }124    }125}126127@Suite struct TimeSeriesAutocorrelationTests {128    @Test func acfMatchesStatsmodels() throws {129        let y = series("arma"), f = tsFixture["acf"]130        let r = try TimeSeries.acf(y, maxLag: 20)131        #expect(r.lags == Array(0...20) && r.n == y.count)132        #expect(allClose(r.values, f["values"].arr, rel: 1e-12, abs: 1e-14))133        #expect(allClose(r.lower, f["lower"].arr, rel: 1e-10, abs: 1e-12))134        #expect(allClose(r.upper, f["upper"].arr, rel: 1e-10, abs: 1e-12))135        #expect(r.values[0] == 1 && r.standardErrors[0] == 0)136        #expect(isClose(r.standardErrors[1], 1 / Double(y.count).squareRoot(), rel: 1e-14))137        #expect(isClose(r.whiteNoiseBound, 1.959963984540054 / Double(y.count).squareRoot(), rel: 1e-12))138        #expect(try TimeSeries.acf(y).lags.count - 1 == tsFixture["acf_default_lags"].i)139        let s = try TimeSeries.acf(series("seasonal"), maxLag: 30)140        #expect(allClose(s.values, tsFixture["acf_seasonal"].arr, rel: 1e-12, abs: 1e-14))141        #expect(r.table().count == 22 && r.table()[0].count == 6)142    }143144    @Test func pacfMatchesStatsmodels() throws {145        let y = series("arma"), f = tsFixture["pacf"]146        let r = try TimeSeries.pacf(y, maxLag: 15)147        #expect(allClose(r.values, f["ldb"].arr, rel: 1e-11, abs: 1e-13))148        #expect(allClose(r.values, f["ywm"].arr, rel: 1e-9, abs: 1e-11))149        #expect(allClose(Array(r.lower.dropFirst()), Array(f["lower"].arr.dropFirst()), rel: 1e-10, abs: 1e-12))150        #expect(allClose(Array(r.upper.dropFirst()), Array(f["upper"].arr.dropFirst()), rel: 1e-10, abs: 1e-12))151        // lag-1 partial autocorrelation equals the lag-1 autocorrelation152        #expect(isClose(r.values[1], try TimeSeries.acf(y, maxLag: 1).values[1], rel: 1e-14))153    }154155    @Test func durbinLevinsonRecoversARCoefficients() {156        // exact autocorrelations of an AR(2) with φ = (0.5, −0.3)157        let p1 = 0.5 / 1.3, p2 = 0.5 * p1 - 0.3, p3 = 0.5 * p2 - 0.3 * p1158        let dl = TimeSeries.durbinLevinson([1, p1, p2, p3])159        #expect(isClose(dl.pacf[1], p1, rel: 1e-14))160        #expect(isClose(dl.pacf[2], -0.3, rel: 1e-13))161        #expect(abs(dl.pacf[3]) < 1e-14)162        #expect(allClose(dl.ar, [0.5, -0.3, 0], rel: 1e-12, abs: 1e-14))163    }164165    @Test func invalidInputs() {166        #expect(throws: StatError.self) { try TimeSeries.acf([1]) }167        #expect(throws: StatError.self) { try TimeSeries.acf([2, 2, 2, 2]) }168        #expect(throws: StatError.self) { try TimeSeries.acf([1, 2, 3], confidence: 1.2) }169        #expect(throws: StatError.self) { try TimeSeries.pacf([1, 2]) }170    }171}172173@Suite struct TimeSeriesExponentialSmoothingTests {174    func config(_ f: JSON) -> (ExponentialSmoothing.Trend, ExponentialSmoothing.Seasonal, ExponentialSmoothing.Parameters, ExponentialSmoothing.Initialization) {175        let trend: ExponentialSmoothing.Trend = f["trend"].s == "damped" ? .dampedAdditive : (f["trend"].s == "add" ? .additive : .none)176        let seasonal: ExponentialSmoothing.Seasonal = f["seasonal"].s == "add" ? .additive : (f["seasonal"].s == "mul" ? .multiplicative : .none)177        let p = f["params"]178        let params = ExponentialSmoothing.Parameters(alpha: p["alpha"].d, beta: p["beta"].isNull ? nil : p["beta"].d,179                                                     gamma: p["gamma"].isNull ? nil : p["gamma"].d, phi: p["phi"].isNull ? nil : p["phi"].d)180        var initialization = ExponentialSmoothing.Initialization.heuristic181        if !f["known"].isNull {182            initialization = .known(level: f["known"]["level"].d, trend: f["known"]["trend"].isNull ? 0 : f["known"]["trend"].d,183                                    seasonal: f["known"]["seasonal"].arr)184        }185        return (trend, seasonal, params, initialization)186    }187188    @Test func recursionsMatchStatsmodelsAtFixedParameters() throws {189        for (name, f) in tsFixture["ets_fixed"].dict {190            let y = series(f["y"].s)191            let (trend, seasonal, params, initialization) = config(f)192            let fit = try ExponentialSmoothing.fit(y, trend: trend, seasonal: seasonal, period: f["period"].i,193                                                   parameters: params, initialization: initialization)194            #expect(!fit.optimized)195            #expect(isClose(fit.initialLevel, f["l0"].d, rel: 1e-12), "\(name) l0")196            if !f["b0"].isNull { #expect(isClose(fit.initialTrend ?? .nan, f["b0"].d, rel: 1e-11), "\(name) b0") }197            #expect(allClose(fit.initialSeasonal, f["s0"].arr, rel: 1e-11, abs: 1e-12), "\(name) s0")198            #expect(allClose(fit.fitted, f["fitted"].arr, rel: 1e-10), "\(name) fitted \(maxRelativeError(fit.fitted, f["fitted"].arr))")199            #expect(allClose(fit.level, f["level"].arr, rel: 1e-10), "\(name) level")200            #expect(allClose(fit.trendComponent, f["trend_states"].arr, rel: 1e-9, abs: 1e-10), "\(name) trend")201            #expect(allClose(fit.seasonalComponent, f["season_states"].arr, rel: 1e-9, abs: 1e-10), "\(name) season")202            #expect(isClose(fit.sse, f["sse"].d, rel: 1e-10), "\(name) sse")203            let fc = fit.forecast(15), want = f["forecast"].arr204            let m = f["period"].i, n = y.count205            for h in 1...15 {206                if seasonal != .none && h % m == 0 {207                    // statsmodels' Holt–Winters reuses the seasonal state of time n − m at horizons that are208                    // multiples of m, where the textbook formula (ours) uses the latest state s_n. Check that this209                    // is the only difference: swapping s_n for s_{n−m} reproduces the statsmodels number.210                    let sNew = fit.seasonalComponent[n - 1], sOld = fit.seasonalComponent[n - m - 1]211                    let swapped = seasonal == .additive ? fc[h - 1] - sNew + sOld : fc[h - 1] / sNew * sOld212                    #expect(isClose(swapped, want[h - 1], rel: 1e-10), "\(name) forecast h=\(h) (stale-state check)")213                } else {214                    #expect(isClose(fc[h - 1], want[h - 1], rel: 1e-10), "\(name) forecast h=\(h): \(fc[h - 1]) vs \(want[h - 1])")215                }216            }217            #expect(isClose(fit.aic, f["aic"].d, rel: 1e-10), "\(name) aic \(fit.aic) vs \(f["aic"].d)")218            #expect(isClose(fit.bic, f["bic"].d, rel: 1e-10), "\(name) bic")219            #expect(allClose(zip(fit.fitted, fit.residuals).map { $0 + $1 }, y, rel: 1e-13), "\(name) residuals")220        }221    }222223    @Test func optimisedFitIsAtLeastAsGoodAsStatsmodels() throws {224        let cases: [(String, String, ExponentialSmoothing.Trend, ExponentialSmoothing.Seasonal, Int)] = [225            ("ses", "flat", .none, .none, 1), ("holt", "trendy", .additive, .none, 1), ("damped", "trendy", .dampedAdditive, .none, 1),226            ("hw_add", "seasonal", .additive, .additive, 12), ("hw_mul", "seasonal_mul", .additive, .multiplicative, 4),227            ("seasonal_only", "seasonal", .none, .additive, 12),228        ]229        for (key, name, trend, seasonal, m) in cases {230            let f = tsFixture["ets_opt"][key]231            let fit = try ExponentialSmoothing.fit(series(name), trend: trend, seasonal: seasonal, period: m)232            #expect(fit.optimized)233            // same model, same fixed initial states: our least-squares fit must not be worse than statsmodels'234            #expect(fit.sse <= f["sse"].d * (1 + 1e-6), "\(key): SSE \(fit.sse) vs statsmodels \(f["sse"].d)")235            #expect(fit.parameters.alpha >= 0 && fit.parameters.alpha <= 1)236            if let phi = fit.parameters.phi { #expect(phi >= 0.8 && phi <= 0.995) }237            // refitting at the reported parameters reproduces the SSE238            let again = try ExponentialSmoothing.fit(series(name), trend: trend, seasonal: seasonal, period: m, parameters: fit.parameters)239            #expect(isClose(again.sse, fit.sse, rel: 1e-12))240        }241        // where the optimum is interior and well identified the parameters agree as well242        let ses = try ExponentialSmoothing.fit(series("flat"))243        #expect(isClose(ses.parameters.alpha, tsFixture["ets_opt"]["ses"]["alpha"].d, rel: 1e-3))244    }245246    @Test func predictionVarianceMultipliersMatchClosedForms() throws {247        func fit(_ key: String) throws -> ExponentialSmoothingFit {248            let f = tsFixture["ets_relvar"][key]249            let trend: ExponentialSmoothing.Trend = !f["phi"].isNull ? .dampedAdditive : (!f["beta"].isNull ? .additive : .none)250            let seasonal: ExponentialSmoothing.Seasonal = f["gamma"].isNull ? .none : .additive251            let p = ExponentialSmoothing.Parameters(alpha: f["alpha"].d, beta: f["beta"].isNull ? nil : f["beta"].d,252                                                    gamma: f["gamma"].isNull ? nil : f["gamma"].d, phi: f["phi"].isNull ? nil : f["phi"].d)253            return try ExponentialSmoothing.fit(series("seasonal"), trend: trend, seasonal: seasonal,254                                                period: f["m"].isNull ? 1 : f["m"].i, parameters: p)255        }256        for key in ["ANN", "AAN", "AAdN", "ANA", "AAA", "AAdA"] {257            let m = try fit(key)258            let want = tsFixture["ets_relvar"][key]["v"].arr259            let got = m.relativeForecastVariance(want.count)!260            #expect(allClose(got, want, rel: 1e-11), "\(key): \(maxRelativeError(got, want))")261            let pi = m.forecastInterval(8, confidence: 0.9)!262            #expect(pi.mean == m.forecast(8))263            #expect(isClose(pi.standardError[0], m.residualVariance.squareRoot(), rel: 1e-14))264            #expect(isClose(pi.upper[3] - pi.mean[3], 1.6448536269514722 * (m.residualVariance * want[3]).squareRoot(), rel: 1e-11))265            #expect(isClose(pi.mean[3] - pi.lower[3], pi.upper[3] - pi.mean[3], rel: 1e-12))266        }267        let mul = try ExponentialSmoothing.fit(series("seasonal_mul"), trend: .additive, seasonal: .multiplicative, period: 4,268                                               parameters: .init(alpha: 0.4, beta: 0.1, gamma: 0.3))269        #expect(mul.relativeForecastVariance(5) == nil && mul.forecastInterval(5) == nil)270    }271272    @Test func simpleCasesByHand() throws {273        // SES with α = 0.5 from l0 = y1: levels 10, 11, 10.5, 12.25274        let fit = try ExponentialSmoothing.fit([10, 12, 10, 14], parameters: .init(alpha: 0.5))275        #expect(fit.level == [10, 11, 10.5, 12.25])276        #expect(fit.fitted == [10, 10, 11, 10.5])277        #expect(fit.forecast(3) == [12.25, 12.25, 12.25])278        #expect(fit.sse == 0 + 4 + 1 + 12.25)279        #expect(fit.mae == (0 + 2 + 1 + 3.5) / 4)280        #expect(isClose(fit.mape, 100 * (0 + 2.0 / 12 + 1.0 / 10 + 3.5 / 14) / 4, rel: 1e-13))281        // a perfectly linear series is reproduced exactly by Holt, whatever the parameters282        let line = (0..<12).map { 3 + 2 * Double($0) }283        let holt = try ExponentialSmoothing.fit(line, trend: .additive, parameters: .init(alpha: 0.3, beta: 0.7),284                                                initialization: .known(level: 1, trend: 2, seasonal: []))285        #expect(holt.sse < 1e-20)286        #expect(allClose(holt.forecast(3), [27, 29, 31], rel: 1e-12))287        #expect(holt.table().count >= 10)288        // an exactly periodic series is reproduced and continued, including at horizons that are multiples of m289        let pattern = [5.0, -2, -3]290        let periodic = (0..<12).map { 100 + pattern[$0 % 3] }291        let add = try ExponentialSmoothing.fit(periodic, seasonal: .additive, period: 3, parameters: .init(alpha: 0.4, gamma: 0.3),292                                               initialization: .known(level: 100, trend: 0, seasonal: pattern))293        #expect(add.sse < 1e-20)294        #expect(allClose(add.forecast(7), [105, 98, 97, 105, 98, 97, 105], rel: 1e-13))295        let mul = try ExponentialSmoothing.fit(periodic, seasonal: .multiplicative, period: 3, parameters: .init(alpha: 0.4, gamma: 0.3),296                                               initialization: .known(level: 100, trend: 0, seasonal: pattern.map { 1 + $0 / 100 }))297        #expect(allClose(mul.forecast(4), [105, 98, 97, 105], rel: 1e-12))298        // α = 0, γ = 1: the level stays at 100 and each seasonal state is the latest deviation, so the299        // forecast at h = m must use the state updated in the LAST season (−5), not the one before (−3)300        let latest = try ExponentialSmoothing.fit([105, 98, 97, 106, 99, 95], seasonal: .additive, period: 3,301                                                  parameters: .init(alpha: 0, gamma: 1),302                                                  initialization: .known(level: 100, trend: 0, seasonal: pattern))303        #expect(latest.forecast(4) == [106, 99, 95, 106])304    }305306    @Test func invalidInputs() {307        #expect(throws: StatError.self) { try ExponentialSmoothing.fit([1, 2, 3, 4], seasonal: .additive, period: 4) }308        #expect(throws: StatError.self) { try ExponentialSmoothing.fit([1, 2, 3, 4, 5, 6], seasonal: .additive, period: 1) }309        #expect(throws: StatError.self) { try ExponentialSmoothing.fit([1, -2, 3, 4, 5, 6, 7, 8], seasonal: .multiplicative, period: 2) }310        #expect(throws: StatError.self) { try ExponentialSmoothing.fit([1, 2, 3], parameters: .init(alpha: 1.5)) }311        #expect(throws: StatError.self) { try ExponentialSmoothing.fit([1, 2, 3, 4], trend: .additive, parameters: .init(alpha: 0.5)) }312        #expect(throws: StatError.self) { try ExponentialSmoothing.fit([1, .nan, 3]) }313        #expect(throws: StatError.self) { try ExponentialSmoothing.fit([1]) }314    }315}316
Files main
Menu

Theme