Repository Public
1import Foundation2import SheetCore3import Statistics4import AnalysisKit56/// ARIMA(p, d, q) by exact maximum likelihood, with forecasts.7enum ARIMATool {8 static let descriptor: ToolDescriptor = {9 var t = ToolDescriptor(10 id: "timeseries.arima", title: L("ARIMA(p, d, q)"), group: L("Time series"), systemImage: "function",11 summary: L("Fits a non-seasonal ARIMA model by exact Gaussian maximum likelihood and forecasts with prediction intervals."),12 fields: [13 .range("data", L("Data range")),14 .column("series", L("Series")),15 .column("time", L("Dates or x values"), optional: true, help: L("Optional increasing dates or numbers for the chart axis.")),16 .integer("p", L("AR order p"), 1, min: 0, max: 8),17 .integer("d", L("Differencing order d"), 1, min: 0, max: 2),18 .integer("q", L("MA order q"), 1, min: 0, max: 8),19 .choice("mean", L("Constant term"), [FieldOption("auto", L("Automatic")), FieldOption("yes", L("Include")), FieldOption("no", L("Omit"))],20 help: L("Automatic: a mean when d = 0, no drift when d > 0.")),21 .integer("horizon", L("Forecast horizon"), 12, min: 1, max: 500),22 .percent("level", L("Prediction level"), 0.95, min: 0.5, max: 0.9999),23 .integer("lags", L("Ljung–Box lags"), 10, min: 1, max: 100),24 .alpha(L("Significance level α")),25 ],26 info: [27 L("Estimation: exact Gaussian likelihood (Kalman filter on the differenced series) maximised by Nelder–Mead from 3 starts. Conditional sum of squares is not offered."),28 L("At fixed parameters the log-likelihood matches statsmodels to 1e-10. Optimised estimates agree with statsmodels ARIMA.fit() to about 2e-3 in the parameters and 1e-4 in the log-likelihood."),29 L("Standard errors come from the numerically differentiated observed information and agree with statsmodels to about 2 %."),30 L("Seasonal ARIMA (P, D, Q)m and exogenous regressors are not shipped."),31 L("Prediction intervals include state uncertainty but ignore parameter uncertainty."),32 ],33 run: run)34 t.demo = { _, v in35 v.set("data", range: "Series!A1:B85"); v.set("series", column: 1); v.set("time", column: 0)36 v.set("p", int: 2); v.set("d", int: 1); v.set("q", int: 1)37 }38 return t39 }()4041 static func order(_ input: ToolInput) -> ARIMA.Order { ARIMA.Order(p: input.values.int("p"), d: input.values.int("d"), q: input.values.int("q")) }42 static func includeMean(_ input: ToolInput) -> Bool? {43 switch input.values.choice("mean") {44 case "yes": true45 case "no": false46 default: nil47 }48 }4950 static func parameterName(_ raw: String) -> String {51 if raw == "mean" { return L("Mean μ") }52 if raw == "drift" { return L("Drift μ") }53 if raw == "sigma2" { return L("Innovation variance σ²") }54 if raw.hasPrefix("ar.L") { return "φ" + raw.dropFirst(4) + " (AR)" }55 if raw.hasPrefix("ma.L") { return "θ" + raw.dropFirst(4) + " (MA)" }56 return raw57 }5859 static func run(_ input: ToolInput) throws -> ToolResult {60 let o = order(input)61 let s = try Sup.series(input, minimum: o.p + o.q + o.d + 8)62 let fit = try ARIMA.fit(s.values, order: o, includeMean: includeMean(input))63 let h = max(input.values.int("horizon"), 1), level = Sup.level(input), alpha = Sup.alpha(input), loc = input.locale64 let fc = try fit.forecast(h, confidence: level)65 let f = ForecastSupport.Forecast(mean: fc.mean, lower: fc.lower, upper: fc.upper, standardError: fc.standardError)66 let axis = Sup.axis(input, "time", rows: s.rows)6768 var rows: [[Value]] = [[.text(L("Parameter")), .text(L("Estimate")), .text(L("Std. error")), .text("z"), .text(L("p-value"))]]69 let z = fit.zStatistics, p = fit.pValues70 for i in fit.parameterNames.indices {71 let isVariance = fit.parameterNames[i] == "sigma2"72 rows.append([.text(parameterName(fit.parameterNames[i])), .finite(fit.estimates[i]), .finite(fit.standardErrors[i]),73 isVariance ? .blank : .finite(z[i]), isVariance ? .blank : .finite(p[i])])74 }75 let params = ReportTable(title: L("Parameters"), rows: rows, columnFormats: [1: .fixed(4), 2: .fixed(4), 3: .fixed(3), 4: .pValue],76 note: fit.standardErrors.contains { $0 == nil } ? L("A standard error is missing where the information matrix could not be inverted.") : nil)77 var blocks: [ResultBlock] = [78 .metrics([Metric(L("Log-likelihood"), fit.logLikelihood, .fixed(3)), Metric("AIC", fit.aic, .fixed(3)), Metric("BIC", fit.bic, .fixed(3)),79 Metric(L("Observations used"), Double(fit.nobs), .integer)]),80 .chart(ForecastSupport.chart(title: L("%@ — one-step predictions and forecast", s.name), series: s, axis: axis, fitted: fit.fitted, fittedOffset: o.d,81 forecast: f, level: level, locale: loc)),82 .table(params),83 ]84 let lags = min(max(input.values.int("lags"), o.p + o.q + 1), max(fit.residuals.count - 2, 1))85 var notes = [String]()86 do {87 let lb = try RegressionDiagnostics.ljungBox(fit.residuals, lags: lags, modelDF: o.p + o.q)88 blocks.append(.table(ReportTable.keyValue(title: L("Ljung–Box test on the residuals"), header: (L("Quantity"), L("Value")), [89 (L("Lags"), .finite(Double(lags)), .integer), (L("Q statistic"), .finite(lb.statistic), .fixed(4)),90 (L("Degrees of freedom"), .finite(lb.df.first), .integer), (L("p-value"), .finite(lb.pValue), .pValue),91 ])))92 if let pv = lb.pValue { blocks.append(.interpretation(Interpret.decision(p: pv, alpha: alpha, null: L("the residuals are not autocorrelated up to the chosen lag"), locale: loc))) }93 } catch { notes.append(L("%@ could not be computed: %@", L("Ljung–Box"), ToolError.describe(error))) }94 blocks.append(.table(ForecastSupport.table(axis: axis, forecast: f, level: level, locale: loc)))95 if !fit.converged { notes.append(L("The likelihood optimisation did not report convergence; the best parameters found are shown.")) }96 if let n = Sup.droppedNote(s) { notes.append(n) }97 notes.append(L("Estimates are approximate to the documented tolerances (about 2e-3 against statsmodels); see the method notes."))98 blocks.append(.note(notes))99 return ToolResult(title: L("ARIMA(%d, %d, %d)", o.p, o.d, o.q), subtitle: L("%@ — series: %@", s.frame.label, s.name), blocks: blocks,100 actions: [ForecastSupport.writeAction(series: s, column: try input.column("series"), forecast: f)], sheetName: "ARIMA")101 }102}103