Repository Public
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