Repository Public
1import Foundation2import SheetCore34/// Result of an augmented Dickey–Fuller test.5public struct ADFResult: Sendable, Hashable, Codable, TableReport {6 /// t statistic of γ in Δy_t = [c + δt] + γ y_{t−1} + Σ φ_i Δy_{t−i} + e_t.7 public var statistic: Double8 /// MacKinnon (1994) approximate p-value. Lower-tail (one-sided): small values reject the unit root.9 public var pValue: Double10 public var usedLag: Int11 /// Observations in the test regression.12 public var nobs: Int13 /// MacKinnon (2010) finite-sample critical values at 1 %, 5 % and 10 %.14 public var critical1: Double15 public var critical5: Double16 public var critical10: Double17 /// "n" (no deterministic term), "c" (constant) or "ct" (constant and trend).18 public var regression: String19 /// Value of the criterion at the selected lag when the lag was chosen automatically.20 public var informationCriterion: Double?21 public var assumptions: String2223 public func table() -> [[Value]] {24 [25 Report.row("Test", "Augmented Dickey–Fuller (H0: unit root)"),26 Report.row("Deterministic terms", regression == "n" ? "none" : (regression == "c" ? "constant" : "constant and trend")),27 Report.row("Statistic", statistic),28 Report.row("p-value (one-sided, MacKinnon)", pValue),29 Report.row("Lags used", usedLag),30 Report.row("Observations", nobs),31 Report.row("Critical value 1%", critical1),32 Report.row("Critical value 5%", critical5),33 Report.row("Critical value 10%", critical10),34 Report.row("Assumptions", assumptions),35 ]36 }37}3839/// Unit-root tests.40public enum UnitRootTest {41 public enum Regression: String, Sendable, Codable, CaseIterable {42 /// No constant, no trend.43 case none = "n"44 /// Constant only.45 case constant = "c"46 /// Constant and linear trend.47 case constantTrend = "ct"48 }4950 public enum LagSelection: Sendable, Hashable {51 /// Use exactly this many lagged differences.52 case fixed(Int)53 /// Choose the lag ≤ maxLag minimising the AIC / BIC of the test regression, all candidates54 /// estimated on the common sample (nil maxLag = ⌈12·(n/100)^¼⌉, as statsmodels).55 case aic(maxLag: Int?)56 case bic(maxLag: Int?)57 }5859 /// Augmented Dickey–Fuller test, following `statsmodels.tsa.stattools.adfuller`: same regression,60 /// lag selection, MacKinnon (1994) p-value surface and MacKinnon (2010) critical values.61 public static func augmentedDickeyFuller(_ x: [Double], regression: Regression = .constant,62 lags: LagSelection = .aic(maxLag: nil)) throws -> ADFResult {63 let n = x.count64 guard x.allSatisfy(\.isFinite) else { throw StatError.invalidInput("series contains non-finite values") }65 let ntrend = regression == .none ? 0 : (regression == .constant ? 1 : 2)66 guard n >= 8 + ntrend else { throw StatError.insufficientData("ADF needs more observations") }67 guard Descriptive.sumSquaredDeviations(x) > 0 else { throw StatError.invalidInput("series is constant") }68 let dx = TimeSeries.difference(x)69 func defaultMax() -> Int { min(n / 2 - ntrend - 1, Int((12 * pow(Double(n) / 100, 0.25)).rounded(.up))) }7071 /// Design for `lag` lagged differences, restricted to the sample that allows `sampleLag` lags.72 /// Columns: y_{t−1}, Δy_{t−1}…Δy_{t−lag}, then deterministic terms.73 func design(lag: Int, sampleLag: Int) -> (y: [Double], cols: [[Double]]) {74 let rows = dx.count - sampleLag75 var cols = [[Double]]()76 cols.append((0..<rows).map { x[sampleLag + $0] }) // level lagged once: x[t] pairs with dx[t]77 for l in 1...max(lag, 1) where l <= lag { cols.append((0..<rows).map { dx[sampleLag + $0 - l] }) }78 if ntrend >= 1 { cols.append([Double](repeating: 1, count: rows)) }79 if ntrend == 2 { cols.append((0..<rows).map { Double($0 + 1) }) }80 return (Array(dx[sampleLag...]), cols)81 }82 func ols(_ y: [Double], _ cols: [[Double]]) throws -> (beta: [Double], se: [Double], ssr: Double) {83 let xm = Matrix(columns: cols)84 let (q, r) = try LinearAlgebra.qr(xm)85 let beta = try LinearAlgebra.backSubstitute(r, q.transposed * y)86 let fitted = xm * beta87 let ssr = zip(y, fitted).reduce(0) { $0 + ($1.0 - $1.1) * ($1.0 - $1.1) }88 let k = cols.count89 // (XᵀX)⁻¹ = R⁻¹ R⁻ᵀ90 var se = [Double](repeating: 0, count: k)91 let s2 = ssr / Double(y.count - k)92 // rows of R⁻¹: (XᵀX)⁻¹_jj = Σ_m (R⁻¹)_jm²93 var rinv = Matrix(rows: k, cols: k)94 for j in 0..<k {95 var e = [Double](repeating: 0, count: k); e[j] = 196 let col = try LinearAlgebra.backSubstitute(r, e)97 for i in 0..<k { rinv[i, j] = col[i] }98 }99 for j in 0..<k {100 var s = 0.0101 for m in 0..<k { s += rinv[j, m] * rinv[j, m] }102 se[j] = (s2 * s).squareRoot()103 }104 return (beta, se, ssr)105 }106107 var usedLag: Int108 var icBest: Double?109 switch lags {110 case .fixed(let l):111 guard l >= 0 else { throw StatError.invalidInput("lag must be ≥ 0") }112 usedLag = l113 case .aic(let m), .bic(let m):114 let maxLag = m ?? defaultMax()115 guard maxLag >= 0 else { throw StatError.insufficientData("series too short for automatic lag selection") }116 guard dx.count - maxLag > maxLag + 1 + ntrend + 1 else { throw StatError.insufficientData("maxLag is too large for the sample") }117 var useBIC = false118 if case .bic = lags { useBIC = true }119 usedLag = 0120 for lag in 0...maxLag {121 let (y, cols) = design(lag: lag, sampleLag: maxLag)122 let fit = try ols(y, cols)123 let nn = Double(y.count), k = Double(cols.count)124 let llf = -nn / 2 * (log(2 * Double.pi) + log(fit.ssr / nn) + 1)125 let ic = -2 * llf + (useBIC ? k * log(nn) : 2 * k)126 if icBest == nil || ic < icBest! { icBest = ic; usedLag = lag }127 }128 }129 let (y, cols) = design(lag: usedLag, sampleLag: usedLag)130 guard y.count > cols.count + 1 else { throw StatError.insufficientData("too many lags for the sample") }131 let fit = try ols(y, cols)132 let stat = fit.beta[0] / fit.se[0]133 let nobs = y.count134 let crit = criticalValues(regression, nobs: nobs)135 return ADFResult(statistic: stat, pValue: mackinnonP(stat, regression), usedLag: usedLag, nobs: nobs,136 critical1: crit[0], critical5: crit[1], critical10: crit[2], regression: regression.rawValue,137 informationCriterion: icBest,138 assumptions: "H0: the series has a unit root (is non-stationary); H1: stationary" +139 (regression == .constantTrend ? " around a linear trend" : "") +140 ". Errors of the test regression are assumed serially uncorrelated once the lagged differences are included. The p-value is one-sided (lower tail), from MacKinnon's (1994) response surface.")141 }142143 /// MacKinnon (1994) approximate p-value of a Dickey–Fuller τ statistic (one variable).144 public static func mackinnonP(_ stat: Double, _ regression: Regression) -> Double {145 let tauMax: Double, tauMin: Double, tauStar: Double146 let small: [Double], large: [Double]147 switch regression {148 case .none:149 tauMax = .infinity; tauMin = -19.04; tauStar = -1.04150 small = [0.6344, 1.2378, 3.2496e-2]151 large = [0.4797, 9.3557e-1, -0.6999e-1, 3.3066e-2]152 case .constant:153 tauMax = 2.74; tauMin = -18.83; tauStar = -1.61154 small = [2.1659, 1.4412, 3.8269e-2]155 large = [1.7339, 9.3202e-1, -1.2745e-1, -1.0368e-2]156 case .constantTrend:157 tauMax = 0.7; tauMin = -16.18; tauStar = -2.89158 small = [3.2512, 1.6047, 4.9588e-2]159 large = [2.5261, 6.1654e-1, -3.7956e-1, -6.0285e-2]160 }161 if stat > tauMax { return 1 }162 if stat < tauMin { return 0 }163 let coef = stat <= tauStar ? small : large164 var poly = 0.0165 for c in coef.reversed() { poly = poly * stat + c }166 return NormalDistribution.standard.cdf(poly)167 }168169 /// MacKinnon (2010) critical values [1 %, 5 %, 10 %] for a sample of `nobs` (nil = asymptotic).170 public static func criticalValues(_ regression: Regression, nobs: Int?) -> [Double] {171 let table: [[Double]]172 switch regression {173 case .none: table = [[-2.56574, -2.2358, -3.627, 0], [-1.941, -0.2686, -3.365, 31.223], [-1.61682, 0.2656, -2.714, 25.364]]174 case .constant: table = [[-3.43035, -6.5393, -16.786, -79.433], [-2.86154, -2.8903, -4.234, -40.04], [-2.56677, -1.5384, -2.809, 0]]175 case .constantTrend: table = [[-3.95877, -9.0531, -28.428, -134.155], [-3.41049, -4.3904, -9.036, -45.374], [-3.12705, -2.5856, -3.925, -22.38]]176 }177 guard let nobs else { return table.map { $0[0] } }178 let inv = 1 / Double(nobs)179 return table.map { c in c[0] + inv * (c[1] + inv * (c[2] + inv * c[3])) }180 }181}182