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/RegressionOLSTests.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 AnalyticsTestSupport90import SheetCore91@testable import Statistics9293let regressionFixture = Fixture.load("regression", .module)9495/// Compares coefficient-level inference of a fit with a fixture block produced by `summary()` in the generator.96func expectInference(_ r: LinearModelResult, _ f: JSON, _ label: String, rel: Double = 1e-9) {97 #expect(allClose(r.coefficients, f["params"].arr, rel: rel), "\(label) params \(maxRelativeError(r.coefficients, f["params"].arr))")98 #expect(allClose(r.standardErrors, f["bse"].arr, rel: rel), "\(label) se \(maxRelativeError(r.standardErrors, f["bse"].arr))")99 #expect(allClose(r.statistics, f["t"].arr, rel: rel), "\(label) t")100 #expect(allClose(r.pValues, f["p"].arr, rel: 1e-8, abs: 1e-300), "\(label) p \(maxRelativeError(r.pValues, f["p"].arr))")101 #expect(allClose(r.ciLower, f["ci_lo"].arr, rel: rel, abs: 1e-11), "\(label) ci lo")102 #expect(allClose(r.ciUpper, f["ci_hi"].arr, rel: rel, abs: 1e-11), "\(label) ci hi")103 #expect(allClose(r.covariance.data, f["cov"].mat.flatMap { $0 }, rel: 1e-8, abs: 1e-13), "\(label) cov")104 #expect(isClose(r.fStatistic ?? .nan, f["fvalue"].d, rel: 1e-8), "\(label) F \(r.fStatistic ?? .nan) vs \(f["fvalue"].d)")105 #expect(isClose(r.fPValue ?? .nan, f["f_pvalue"].d, rel: 1e-7, abs: 1e-300), "\(label) F p \(r.fPValue ?? .nan) vs \(f["f_pvalue"].d)")106}107108@Suite struct RegressionOLSTests {109 let f = regressionFixture["ols"]110 var y: [Double] { f["y"].arr }111 var x: Matrix { Matrix(f["X"].mat) }112113 @Test func olsMatchesStatsmodels() throws {114 let r = try LinearRegression.fit(y: y, x: x, names: ["x1", "x2", "x3"])115 expectInference(r, f, "OLS", rel: 1e-10)116 #expect(r.names == ["const", "x1", "x2", "x3"])117 #expect(r.method == "OLS" && r.usesT && r.hasIntercept && r.hasConstant)118 #expect(r.nobs == 60 && r.dfModel == f["df_model"].i && r.dfResidual == f["df_resid"].i)119 #expect(isClose(r.rSquared, f["rsquared"].d, rel: 1e-12))120 #expect(isClose(r.adjustedRSquared, f["rsquared_adj"].d, rel: 1e-12))121 #expect(isClose(r.logLikelihood, f["llf"].d, rel: 1e-12))122 #expect(isClose(r.aic, f["aic"].d, rel: 1e-12))123 #expect(isClose(r.bic, f["bic"].d, rel: 1e-12))124 #expect(isClose(r.sigma2, f["mse_resid"].d, rel: 1e-11))125 #expect(isClose(r.residualStandardError, f["mse_resid"].d.squareRoot(), rel: 1e-11))126 #expect(isClose(r.ssr, f["ssr"].d, rel: 1e-11))127 #expect(isClose(r.tss, f["tss"].d, rel: 1e-12))128 #expect(allClose(r.residuals, f["resid"].arr, rel: 1e-8, abs: 1e-10))129 #expect(allClose(r.fitted, f["fitted"].arr, rel: 1e-11))130 #expect(allClose(r.leverage, f["hat"].arr, rel: 1e-10))131 #expect(allClose(r.cooksDistance, f["cooks"].arr, rel: 1e-8, abs: 1e-14))132 #expect(allClose(r.studentizedResiduals, f["student"].arr, rel: 1e-8, abs: 1e-10))133 #expect(r.vif[0] == nil)134 #expect(allClose(r.vif[1...].map { $0 ?? .nan }, f["vif"].arr, rel: 1e-10))135 #expect(isClose(r.conditionNumber, f["cond"].d, rel: 1e-10))136 #expect(isClose(r.leverage.reduce(0, +), 4, rel: 1e-12)) // trace of the hat matrix = k137 #expect(abs(r.residuals.reduce(0, +)) < 1e-9) // residuals sum to zero with a constant138 #expect(allClose(try r.predict(Matrix(f["predict_X"].mat)), f["predict"].arr, rel: 1e-11))139 #expect(throws: StatError.self) { try r.predict(Matrix([[1, 2]])) }140 }141142 @Test func confidenceLevelAndColumnsOverload() throws {143 let r = try LinearRegression.fit(y: y, columns: x.columnArrays, confidenceLevel: 0.90)144 #expect(allClose(r.ciLower, f["ci90_lo"].arr, rel: 1e-10))145 #expect(allClose(r.ciUpper, f["ci90_hi"].arr, rel: 1e-10))146 #expect(r.names == ["const", "x1", "x2", "x3"])147 #expect(throws: StatError.self) { try LinearRegression.fit(y: y, x: x, confidenceLevel: 1) }148 }149150 @Test func heteroskedasticityRobustCovariances() throws {151 let cases: [(String, CovarianceType)] = [("HC0", .hc0), ("HC1", .hc1), ("HC2", .hc2), ("HC3", .hc3)]152 let base = try LinearRegression.fit(y: y, x: x)153 for (key, type) in cases {154 let r = try LinearRegression.fit(y: y, x: x, covariance: type)155 #expect(!r.usesT)156 expectInference(r, f[key], key)157 expectInference(try LinearRegression.fit(y: y, x: x, covariance: type, useT: true), f[key + "_t"], key + " (t)")158 // re-estimating an existing fit gives the same thing as fitting with the option159 let again = try LinearRegression.reestimate(base, covariance: type)160 #expect(again.standardErrors == r.standardErrors && again.pValues == r.pValues && again.fStatistic == r.fStatistic)161 #expect(allClose(try LinearRegression.covarianceMatrix(base, type).data, f[key]["cov"].mat.flatMap { $0 }, rel: 1e-8, abs: 1e-13))162 }163 #expect(CovarianceType.hc3.label == "HC3")164 }165166 @Test func neweyWestHAC() throws {167 expectInference(try LinearRegression.fit(y: y, x: x, covariance: .hac(maxLags: 4, smallSample: false)), f["HAC4"], "HAC4")168 expectInference(try LinearRegression.fit(y: y, x: x, covariance: .hac(maxLags: 4, smallSample: true)), f["HAC4_small"], "HAC4 small")169 expectInference(try LinearRegression.fit(y: y, x: x, covariance: .hac(maxLags: 4, smallSample: false), useT: true), f["HAC4_t"], "HAC4 t")170 let hac0 = try LinearRegression.fit(y: y, x: x, covariance: .hac(maxLags: 0, smallSample: false))171 expectInference(hac0, f["HAC0"], "HAC0")172 // with zero lags Newey–West is White's HC0173 let hc0 = try LinearRegression.fit(y: y, x: x, covariance: .hc0)174 #expect(allClose(hac0.standardErrors, hc0.standardErrors, rel: 1e-13))175 #expect(throws: StatError.self) { try LinearRegression.fit(y: y, x: x, covariance: .hac(maxLags: 60, smallSample: false)) }176 #expect(throws: StatError.self) { try LinearRegression.fit(y: y, x: x, covariance: .hac(maxLags: -1, smallSample: false)) }177 }178179 @Test func clusterRobust() throws {180 let g = f["groups"].ints181 let r = try LinearRegression.fit(y: y, x: x, covariance: .cluster(groups: g, smallSample: true))182 expectInference(r, f["cluster"], "cluster")183 #expect(r.dfInference == 9)184 let t = try LinearRegression.fit(y: y, x: x, covariance: .cluster(groups: g, smallSample: true), useT: true)185 expectInference(t, f["cluster_t"], "cluster (t)")186 expectInference(try LinearRegression.fit(y: y, x: x, covariance: .cluster(groups: g, smallSample: false)), f["cluster_nocorr"], "cluster no correction")187 // one observation per cluster without correction is HC0188 let own = try LinearRegression.fit(y: y, x: x, covariance: .cluster(groups: Array(0..<60), smallSample: false))189 #expect(allClose(own.standardErrors, try LinearRegression.fit(y: y, x: x, covariance: .hc0).standardErrors, rel: 1e-12))190 #expect(throws: StatError.self) { try LinearRegression.fit(y: y, x: x, covariance: .cluster(groups: [1, 2], smallSample: true)) }191 #expect(throws: StatError.self) { try LinearRegression.fit(y: y, x: x, covariance: .cluster(groups: Array(repeating: 1, count: 60), smallSample: true)) }192 }193194 @Test func noIntercept() throws {195 let g = regressionFixture["ols_noconst"]196 let r = try LinearRegression.fit(y: y, x: x, intercept: false)197 expectInference(r, g, "no-const", rel: 1e-10)198 #expect(!r.hasIntercept && !r.hasConstant && r.names == ["x1", "x2", "x3"])199 #expect(r.dfModel == g["df_model"].i && r.dfResidual == g["df_resid"].i)200 #expect(isClose(r.rSquared, g["rsquared"].d, rel: 1e-12)) // uncentred201 #expect(isClose(r.adjustedRSquared, g["rsquared_adj"].d, rel: 1e-12))202 #expect(isClose(r.tss, g["tss"].d, rel: 1e-12))203 #expect(isClose(r.logLikelihood, g["llf"].d, rel: 1e-12))204 #expect(isClose(r.aic, g["aic"].d, rel: 1e-12) && isClose(r.bic, g["bic"].d, rel: 1e-12))205 #expect(r.vif == [nil, nil, nil])206 expectInference(try LinearRegression.fit(y: y, x: x, intercept: false, covariance: .hc1), g["HC1"], "no-const HC1")207 // a constant supplied by the caller is recognised: same fit as intercept = true208 var withOnes = Matrix(rows: 60, cols: 4)209 for i in 0..<60 { withOnes[i, 0] = 1; for j in 0..<3 { withOnes[i, j + 1] = x[i, j] } }210 let manual = try LinearRegression.fit(y: y, x: withOnes, intercept: false)211 #expect(manual.hasConstant && !manual.hasIntercept)212 #expect(isClose(manual.rSquared, f["rsquared"].d, rel: 1e-12))213 #expect(isClose(manual.fStatistic ?? .nan, f["fvalue"].d, rel: 1e-9))214 #expect(allClose(manual.coefficients, f["params"].arr, rel: 1e-10))215 }216217 @Test func simpleRegressionClosedForm() throws {218 let g = regressionFixture["ols_simple"]219 let x1 = x.column(0)220 let r = try LinearRegression.fit(y: y, columns: [x1], names: ["x1"])221 expectInference(r, g, "simple", rel: 1e-10)222 // textbook formulas: slope = cov/var, intercept = ȳ − slope·x̄, R² = r², F = t²223 let slope = Descriptive.covariance(x1, y) / Descriptive.variance(x1)224 #expect(isClose(r.coefficients[1], slope, rel: 1e-12))225 #expect(isClose(r.coefficients[0], Descriptive.mean(y) - slope * Descriptive.mean(x1), rel: 1e-11))226 #expect(isClose(r.rSquared, pow(Descriptive.pearson(x1, y), 2), rel: 1e-12))227 #expect(isClose(r.fStatistic ?? .nan, r.statistics[1] * r.statistics[1], rel: 1e-10))228 #expect(isClose(r.vif[1] ?? .nan, 1, rel: 1e-12))229 }230231 @Test func exactFitAndInterceptOnly() throws {232 // y is an exact linear function: coefficients recovered, R² = 1233 let xs = (0..<12).map { Double($0) }, zs = xs.map { sin($0) }234 let exact = try LinearRegression.fit(y: zip(xs, zs).map { 3 - 2 * $0 + 0.5 * $1 }, columns: [xs, zs])235 #expect(allClose(exact.coefficients, [3, -2, 0.5], rel: 1e-11))236 #expect(isClose(exact.rSquared, 1, rel: 1e-12))237 // intercept only: coefficient = mean, SE = s/√n, no F238 let only = try LinearRegression.fit(y: y, columns: [])239 #expect(isClose(only.coefficients[0], Descriptive.mean(y), rel: 1e-13))240 #expect(isClose(only.standardErrors[0], Descriptive.standardDeviation(y) / 60.0.squareRoot(), rel: 1e-12))241 #expect(only.fStatistic == nil && only.fPValue == nil && only.dfModel == 0)242 #expect(isClose(only.rSquared, 0, abs: 1e-13))243 }244245 @Test func degenerateDesignsAreRejected() {246 let n = 20247 let a = (0..<n).map { Double($0) }, b = a.map { 2 * $0 + 1 }, yy = a.map { $0 * 1.5 + cos($0) }248 // perfect collinearity (b = 2a + 1 with an intercept)249 #expect(throws: StatError.singular("the design matrix is rank deficient: 'b' is (numerically) a linear combination of the preceding columns")) {250 try LinearRegression.fit(y: yy, columns: [a, b], names: ["a", "b"])251 }252 // constant regressor next to the intercept253 #expect(throws: StatError.self) { try LinearRegression.fit(y: yy, columns: [a, Array(repeating: 7, count: n)]) }254 // all-zero column255 #expect(throws: StatError.self) { try LinearRegression.fit(y: yy, columns: [a, Array(repeating: 0, count: n)]) }256 // duplicated column without intercept257 #expect(throws: StatError.self) { try LinearRegression.fit(y: yy, columns: [a, a], intercept: false) }258 // n ≤ k259 #expect(throws: StatError.insufficientData("3 observations for 3 coefficients: at least 4 are needed")) {260 try LinearRegression.fit(y: [1, 2, 4], columns: [[1, 2, 3], [1, 4, 9]])261 }262 #expect(throws: StatError.self) { try LinearRegression.fit(y: [1, 2], columns: [[1, 2, 3]]) } // length mismatch263 #expect(throws: StatError.self) { try LinearRegression.fit(y: yy, columns: [a], names: ["a", "b"]) } // names mismatch264 #expect(throws: StatError.self) { try LinearRegression.fit(y: yy, columns: [], intercept: false) } // nothing to estimate265 var bad = yy; bad[3] = .nan266 #expect(throws: StatError.self) { try LinearRegression.fit(y: bad, columns: [a]) }267 // nearly collinear but identified: still estimated268 let nearly = zip(a, yy).map { 2 * $0 + 1 + 1e-4 * $1 }269 #expect((try? LinearRegression.fit(y: yy, columns: [a, nearly])) != nil)270 }271272 @Test func weightedLeastSquares() throws {273 let g = regressionFixture["wls"]274 let w = g["w"].arr275 let r = try LinearRegression.fit(y: y, x: x, weights: w)276 expectInference(r, g, "WLS", rel: 1e-10)277 #expect(r.method == "WLS")278 #expect(isClose(r.rSquared, g["rsquared"].d, rel: 1e-12))279 #expect(isClose(r.adjustedRSquared, g["rsquared_adj"].d, rel: 1e-12))280 #expect(isClose(r.logLikelihood, g["llf"].d, rel: 1e-12))281 #expect(isClose(r.aic, g["aic"].d, rel: 1e-12) && isClose(r.bic, g["bic"].d, rel: 1e-12))282 #expect(isClose(r.sigma2, g["mse_resid"].d, rel: 1e-11) && isClose(r.ssr, g["ssr"].d, rel: 1e-11) && isClose(r.tss, g["tss"].d, rel: 1e-12))283 #expect(allClose(r.residuals, g["resid"].arr, rel: 1e-8, abs: 1e-10))284 #expect(allClose(r.fitted, g["fitted"].arr, rel: 1e-11))285 #expect(allClose(r.leverage, g["hat"].arr, rel: 1e-10))286 expectInference(try LinearRegression.fit(y: y, x: x, weights: w, covariance: .hc1), g["HC1"], "WLS HC1")287 expectInference(try LinearRegression.fit(y: y, x: x, weights: w, covariance: .hc3), g["HC3"], "WLS HC3")288 // equal weights reproduce OLS; rescaling the weights changes nothing but the likelihood289 let equal = try LinearRegression.fit(y: y, x: x, weights: Array(repeating: 1, count: 60))290 #expect(allClose(equal.standardErrors, f["bse"].arr, rel: 1e-10) && isClose(equal.logLikelihood, f["llf"].d, rel: 1e-12))291 let scaled = try LinearRegression.fit(y: y, x: x, weights: w.map { $0 * 10 })292 #expect(allClose(scaled.coefficients, r.coefficients, rel: 1e-11) && allClose(scaled.standardErrors, r.standardErrors, rel: 1e-10))293 #expect(throws: StatError.self) { try LinearRegression.fit(y: y, x: x, weights: Array(repeating: 0, count: 60)) }294 #expect(throws: StatError.self) { try LinearRegression.fit(y: y, x: x, weights: [1, 2]) }295 }296297 @Test func categoricalDummies() throws {298 let g = regressionFixture["categorical"]299 var b = DesignBuilder()300 b.addNumeric("x1", g["x1"].arr)301 try b.addCategorical("region", g["region"].strings)302 try b.addCategorical("size", g["size"].strings)303 #expect(b.names == ["x1", "region[north]", "region[south]", "region[west]", "size[M]", "size[S]"])304 #expect(g["columns"].strings == ["region_north", "region_south", "region_west", "size_M", "size_S"]) // same order as pandas305 #expect(b.baselines == ["region": "east", "size": "L"])306 let r = try LinearRegression.fit(y: g["y"].arr, x: try b.matrix(), names: b.names)307 expectInference(r, g, "categorical", rel: 1e-9)308 #expect(isClose(r.rSquared, g["rsquared"].d, rel: 1e-12))309 // the dummy-variable trap is caught310 var trap = DesignBuilder()311 try trap.addCategorical("region", g["region"].strings, dropFirst: false)312 #expect(throws: StatError.self) { try LinearRegression.fit(y: g["y"].arr, x: try trap.matrix(), names: trap.names) }313 #expect((try? LinearRegression.fit(y: g["y"].arr, x: try trap.matrix(), names: trap.names, intercept: false)) != nil)314315 let enc = try Categorical.dummies(["b", "a", "c", "a"], prefix: "k")316 #expect(enc.levels == ["a", "b", "c"] && enc.baseline == "a" && enc.names == ["k[b]", "k[c]"])317 #expect(enc.columns == [[1, 0, 0, 0], [0, 0, 1, 0]])318 let ordered = try Categorical.dummies(["b", "a", "c", "a"], prefix: "k", dropFirst: false, levels: ["c", "b", "a"])319 #expect(ordered.names == ["k[c]", "k[b]", "k[a]"] && ordered.baseline == nil && ordered.columns[2] == [0, 1, 0, 1])320 #expect(throws: StatError.self) { try Categorical.dummies(["x"], prefix: "k", levels: ["a"]) }321 #expect(throws: StatError.self) { try Categorical.dummies(["a"], prefix: "k", levels: ["a", "a"]) }322 var inter = DesignBuilder()323 inter.addNumeric("p", [1, 2, 3]); inter.addNumeric("q", [2, 2, 5])324 try inter.addInteraction("p", "q")325 #expect(inter.names.last == "p:q" && inter.columns.last == [2, 4, 15])326 #expect(throws: StatError.self) { try inter.addInteraction("p", "zz") }327 inter.addNumeric("short", [1])328 #expect(throws: StatError.self) { try inter.matrix() }329 }330331 @Test func reportTableAndCodable() throws {332 let r = try LinearRegression.fit(y: y, x: x, names: ["x1", "x2", "x3"], covariance: .hc1)333 let t = r.table()334 #expect(t.allSatisfy { $0.count == 7 })335 #expect(t[0][0] == .text("OLS regression"))336 func row(_ label: String) -> [Value]? { t.first { $0[0] == .text(label) } }337 #expect(row("Observations")?[1] == .number(60))338 #expect(row("Covariance type")?[1] == .text("HC1"))339 #expect(row("R-squared")?[1] == .number(r.rSquared))340 #expect(row("x2")?[1] == .number(r.coefficients[2]) && row("x2")?[2] == .number(r.standardErrors[2]))341 #expect(t.contains { $0[3] == .text("z") && $0[4] == .text("P>|z|") && $0[5] == .text("Lower 95%") })342 #expect(row("Durbin–Watson")?[1] == .number(f["diag"]["dw"].d) || isClose(row("Durbin–Watson")?[1].numberValue ?? .nan, f["diag"]["dw"].d, rel: 1e-9))343 #expect(isClose(row("Jarque–Bera")?[1].numberValue ?? .nan, f["diag"]["jb"][0].d, rel: 1e-8))344 #expect(isClose(row("Skewness")?[1].numberValue ?? .nan, f["diag"]["jb"][2].d, rel: 1e-8))345 #expect(isClose(row("Kurtosis")?[1].numberValue ?? .nan, f["diag"]["jb"][3].d, rel: 1e-8))346 #expect(row("Variance inflation factors") != nil)347 // results stay JSON-encodable (no NaN) even when F and VIF are undefined348 _ = try JSONEncoder().encode(try LinearRegression.fit(y: y, columns: []))349 // a constant dependent variable is rejected350 #expect(throws: StatError.self) { try LinearRegression.fit(y: Array(repeating: 2, count: 60), x: x) }351 let back = try JSONDecoder().decode(LinearModelResult.self, from: JSONEncoder().encode(r))352 #expect(back == r)353 }354}355