Repository Public
1import Foundation2import SheetCore3import Statistics4import AnalysisKit56/// OLS / WLS regression with robust covariance options, diagnostics and residual plots.7enum LinearRegressionTool {8 static let covarianceOptions: [FieldOption] = [9 FieldOption("classical", L("Classical")), FieldOption("hc0", "HC0"), FieldOption("hc1", "HC1"), FieldOption("hc2", "HC2"), FieldOption("hc3", "HC3"),10 FieldOption("hac", L("HAC (Newey–West)")), FieldOption("cluster", L("Clustered")),11 ]1213 static let descriptor: ToolDescriptor = {14 var t = ToolDescriptor(15 id: "regression.linear", title: L("Linear Regression"), group: L("Regression"), systemImage: "chart.line.uptrend.xyaxis",16 summary: L("Ordinary or weighted least squares with classical, heteroskedasticity-robust, HAC or clustered standard errors, diagnostics and residual plots."),17 fields: [18 .range("data", L("Data range")),19 .column("y", L("Dependent variable (y)")),20 .columns("x", L("Regressors (X)")),21 .columns("cat", L("Categorical regressors"), numeric: false, all: false,22 help: L("Each chosen column is expanded into indicator variables; the first level (sorted) is the reference.")),23 .column("weights", L("Weights (WLS)"), optional: true, help: L("Positive weights proportional to the inverse error variances. None = ordinary least squares.")),24 .toggle("intercept", L("Include an intercept"), true),25 .choice("cov", L("Standard errors"), covarianceOptions),26 .integer("hacLags", L("HAC lags"), 4, min: 0, max: 200, visible: { $0.choice("cov") == "hac" }),27 .column("cluster", L("Cluster by"), numeric: false, optional: true, visible: { $0.choice("cov") == "cluster" }),28 .toggle("smallSample", L("Small-sample correction"), true, visible: { ["hac", "cluster"].contains($0.choice("cov")) }),29 .percent("level", L("Confidence level"), 0.95, min: 0.5, max: 0.9999),30 .integer("lags", L("Lags for the autocorrelation tests"), 2, min: 1, max: 60),31 .alpha(L("Significance level α")),32 ],33 info: [34 L("Coefficients, standard errors and fit statistics follow statsmodels OLS / WLS (validated to 1e-10)."),35 L("With a robust covariance, p-values and intervals use the normal distribution and F is the robust Wald test."),36 L("HAC uses the Bartlett kernel on observations in sheet order; the clustered estimator uses the statsmodels scaling G/(G−1)·(n−1)/(n−k) (Stata's xtreg scaling is not shipped)."),37 L("For WLS only HC1 and HC3 are validated among the heteroskedasticity-robust estimators."),38 L("Durbin–Watson is reported as a statistic only (no p-value)."),39 L("Studentized residuals are internally studentized; externally studentized residuals, DFFITS and DFBETAS are not shipped."),40 ],41 run: run)42 t.demo = { _, v in43 v.set("data", range: "Regression!A1:G121")44 v.set("y", column: 0); v.set("x", columns: [1, 2, 3]); v.set("cat", columns: [4]); v.set("cov", choice: "hc3")45 }46 return t47 }()4849 static func covariance(_ input: ToolInput, design d: RegressionDesign) throws -> CovarianceType {50 let small = input.values.bool("smallSample")51 switch input.values.choice("cov") {52 case "hc0": return .hc053 case "hc1": return .hc154 case "hc2": return .hc255 case "hc3": return .hc356 case "hac": return .hac(maxLags: input.values.int("hacLags"), smallSample: small)57 case "cluster":58 guard let labels = d.labelExtras["cluster"] else { throw ToolError(L("Choose the column that identifies the clusters.")) }59 let (codes, levels) = Sup.codes(labels)60 guard levels.count >= 2 else { throw ToolError(L("At least two clusters are needed.")) }61 return .cluster(groups: codes, smallSample: small)62 default: return .nonrobust63 }64 }6566 static func covarianceLabel(_ input: ToolInput, design d: RegressionDesign) -> String {67 switch input.values.choice("cov") {68 case "hc0", "hc1", "hc2", "hc3": return L("heteroskedasticity-robust (%@)", input.values.choice("cov").uppercased())69 case "hac": return L("HAC Newey–West, %d lags", input.values.int("hacLags"))70 case "cluster": return L("clustered by %@ (%d clusters)", d.labelExtraNames["cluster"] ?? "", Set(d.labelExtras["cluster"] ?? []).count)71 default: return L("classical")72 }73 }7475 static func fit(_ input: ToolInput) throws -> (model: LinearModelResult, design: RegressionDesign) {76 let clustered = input.values.choice("cov") == "cluster"77 let d = try RegressionDesign.build(input, numericExtras: ["weights"], labelExtras: clustered ? ["cluster"] : [])78 let weights = d.numericExtras["weights"]79 if let w = weights, w.contains(where: { $0 <= 0 }) { throw ToolError(L("Weights must be strictly positive.")) }80 let model = try LinearRegression.fit(y: d.y, x: d.x, names: d.names, intercept: input.values.bool("intercept"), weights: weights,81 covariance: try covariance(input, design: d), confidenceLevel: Sup.level(input), dependentName: d.yName)82 return (model, d)83 }8485 static func run(_ input: ToolInput) throws -> ToolResult {86 let (m, d) = try fit(input)87 let alpha = Sup.alpha(input), loc = input.locale88 var blocks: [ResultBlock] = [.metrics([89 Metric(L("Observations"), Double(m.nobs), .integer), Metric("R²", m.rSquared, .fixed(4)), Metric(L("Adjusted R²"), m.adjustedRSquared, .fixed(4)),90 Metric(L("Residual std. error"), m.residualStandardError),91 Metric(L("F statistic"), m.fStatistic ?? .nan, .fixed(3)), Metric(L("p-value (F)"), m.fPValue ?? .nan, .pValue),92 ])]93 blocks.append(.table(Sup.coefficientTable(title: L("Coefficients"), names: m.names, estimates: m.coefficients, se: m.standardErrors,94 statistics: m.statistics, pValues: m.pValues, lower: m.ciLower, upper: m.ciUpper,95 usesT: m.usesT, level: m.confidenceLevel, locale: loc)))96 blocks.append(.table(fitTable(m, covariance: covarianceLabel(input, design: d))))97 if let f = m.fPValue {98 blocks.append(.interpretation(Interpret.decision(p: f, alpha: alpha, null: L("all slope coefficients are zero"), locale: loc)))99 }100 let diag = RegressionOutput.diagnostics(m, lags: input.values.int("lags"), alpha: alpha, locale: loc)101 blocks.append(.table(diag.table))102 if let vif = RegressionOutput.vifTable(m) { blocks.append(.table(vif)) }103 blocks.append(.charts(RegressionOutput.residualCharts(m, locale: loc)))104 blocks.append(.assumptions(diag.nulls, title: L("Null hypotheses of the diagnostic tests")))105 blocks.append(.note(d.notes + diag.notes + [106 m.usesT ? L("Inference uses Student's t with %@ degrees of freedom.", Fmt.df(m.dfInference, locale: loc))107 : L("Inference uses the normal distribution (robust covariance)."),108 ]))109 let actions = [Sup.writeColumns(id: "write-fitted", title: L("Write Fitted Values and Residuals"), label: L("Write Fitted Values and Residuals"), frame: d.frame,110 names: [L("Fitted %@", d.yName), L("Residual %@", d.yName)],111 columns: [d.frame.expand(m.fitted, rows: d.rows), d.frame.expand(m.residuals, rows: d.rows)])]112 return ToolResult(title: L("Linear Regression (%@)", m.method), subtitle: L("%@ — dependent variable: %@", d.frame.label, d.yName),113 blocks: blocks, actions: actions, sheetName: L("Regression"))114 }115116 static func fitTable(_ m: LinearModelResult, covariance: String) -> ReportTable {117 ReportTable.keyValue(title: L("Fit statistics"), header: (L("Quantity"), L("Value")), [118 (L("Method"), .text(m.method), .auto), (L("Standard errors"), .text(covariance), .auto),119 (L("Observations"), .finite(Double(m.nobs)), .integer),120 (L("Degrees of freedom (model)"), .finite(Double(m.dfModel)), .integer), (L("Degrees of freedom (residual)"), .finite(Double(m.dfResidual)), .integer),121 ("R²", .finite(m.rSquared), .fixed(6)), (L("Adjusted R²"), .finite(m.adjustedRSquared), .fixed(6)),122 (L("F statistic"), .finite(m.fStatistic), .fixed(4)), (L("p-value (F)"), .finite(m.fPValue), .pValue),123 (L("Residual std. error"), .finite(m.residualStandardError), .auto), (L("Sum of squared residuals"), .finite(m.ssr), .auto),124 (L("Log-likelihood"), .finite(m.logLikelihood), .fixed(4)), ("AIC", .finite(m.aic), .fixed(4)), ("BIC", .finite(m.bic), .fixed(4)),125 (L("Condition number"), .finite(m.conditionNumber), .fixed(2)),126 ], note: m.hasConstant ? nil : L("No constant in the model: R² is uncentred."))127 }128}129