Repository Public
1import Foundation2import SheetCore34/// Chi-square test on a contingency table, with the expected counts.5public struct ContingencyResult: Sendable, Hashable, Codable, TableReport {6 public var test: HypothesisTest7 public var observed: Matrix8 /// Expected counts under independence: row total × column total / grand total.9 public var expected: Matrix10 /// Pearson residuals (O − E)/√E.11 public var residuals: Matrix12 public var rowTotals: [Double]13 public var columnTotals: [Double]14 public var total: Double15 /// Cramér's V = √(χ²/(n·min(r−1, c−1))), from the uncorrected χ².16 public var cramersV: Double17 /// Smallest expected count (the usual rule of thumb asks for ≥ 5).18 public var minimumExpected: Double1920 public func table() -> [[Value]] {21 var out = test.table()22 out.append(Report.row("Minimum expected count", minimumExpected))23 out.append([.blank])24 out.append([.text("Expected counts")])25 for r in 0..<expected.rows { out.append(expected.row(r).map { Report.num($0) }) }26 return Report.rectangular(out)27 }28}2930extension Inference {31 /// Pearson chi-square goodness-of-fit test. `expected` are expected COUNTS (same total as the32 /// observed counts); nil = equal counts. `estimatedParameters` reduces the degrees of freedom:33 /// df = k − 1 − estimatedParameters. The p-value is the upper tail of χ²(df).34 public static func chiSquareGoodnessOfFit(observed: [Double], expected: [Double]? = nil, estimatedParameters: Int = 0) throws -> HypothesisTest {35 let k = observed.count36 guard k >= 2, observed.allSatisfy({ $0 >= 0 }) else { throw StatError.invalidInput("need at least two non-negative observed counts") }37 let total = Descriptive.sum(observed)38 let e = expected ?? Array(repeating: total / Double(k), count: k)39 guard e.count == k, e.allSatisfy({ $0 > 0 }) else { throw StatError.invalidInput("expected counts must be positive, one per category") }40 guard isRoughlyEqual(Descriptive.sum(e), total) else { throw StatError.invalidInput("observed and expected counts must have the same total") }41 let df = k - 1 - estimatedParameters42 guard df >= 1 else { throw StatError.insufficientData("no degrees of freedom left") }43 var chi = 0.044 for i in 0..<k { chi += (observed[i] - e[i]) * (observed[i] - e[i]) / e[i] }45 return HypothesisTest(name: "Chi-square goodness-of-fit test", statisticName: "χ²", statistic: chi, df: Double(df),46 pValue: ChiSquaredDistribution(df: Double(df)).sf(chi), alternative: .greater,47 pValueDescription: "upper tail of χ²(\(df))",48 effectSize: NamedValue("Cohen's w", (chi / total).squareRoot()),49 details: [NamedValue("Categories", Double(k)), NamedValue("Total count", total), NamedValue("Minimum expected count", e.min()!)],50 assumptions: ["Observations are independent and each falls in exactly one category",51 "Expected counts are large enough (rule of thumb: all ≥ 5)"])52 }5354 /// Goodness of fit against hypothesised category probabilities (normalised to sum to 1).55 public static func chiSquareGoodnessOfFit(observed: [Double], probabilities: [Double], estimatedParameters: Int = 0) throws -> HypothesisTest {56 guard probabilities.count == observed.count, probabilities.allSatisfy({ $0 > 0 }) else {57 throw StatError.invalidInput("one positive probability per category is required")58 }59 let total = Descriptive.sum(observed), ps = Descriptive.sum(probabilities)60 return try chiSquareGoodnessOfFit(observed: observed, expected: probabilities.map { $0 / ps * total }, estimatedParameters: estimatedParameters)61 }6263 private static func isRoughlyEqual(_ a: Double, _ b: Double) -> Bool { abs(a - b) <= 1e-8 * max(abs(a), abs(b)) }6465 /// Pearson chi-square test of independence (or homogeneity) on an r×c table of counts.66 /// df = (r−1)(c−1); p-value = upper tail of χ²(df). `yatesCorrection` applies the continuity67 /// correction, and only to 2×2 tables (as SciPy's `chi2_contingency(correction=True)`); it is off by default.68 public static func chiSquareIndependence(_ table: [[Double]], yatesCorrection: Bool = false) throws -> ContingencyResult {69 let r = table.count, c = table.first?.count ?? 070 guard r >= 2, c >= 2, table.allSatisfy({ $0.count == c }) else { throw StatError.invalidInput("need a rectangular table with at least 2 rows and 2 columns") }71 guard table.allSatisfy({ $0.allSatisfy { $0 >= 0 } }) else { throw StatError.invalidInput("counts must be non-negative") }72 let obs = Matrix(table)73 let rowTotals = (0..<r).map { Descriptive.sum(obs.row($0)) }74 let colTotals = (0..<c).map { Descriptive.sum(obs.column($0)) }75 let n = Descriptive.sum(rowTotals)76 guard rowTotals.allSatisfy({ $0 > 0 }), colTotals.allSatisfy({ $0 > 0 }) else { throw StatError.invalidInput("every row and column needs a positive total") }77 var expected = Matrix(rows: r, cols: c), resid = Matrix(rows: r, cols: c)78 var chi = 0.0, chiRaw = 0.079 let useYates = yatesCorrection && r == 2 && c == 280 for i in 0..<r {81 for j in 0..<c {82 let e = rowTotals[i] * colTotals[j] / n83 expected[i, j] = e84 let d = obs[i, j] - e85 resid[i, j] = d / e.squareRoot()86 chiRaw += d * d / e87 if useYates {88 let adj = max(0, abs(d) - 0.5) // never over-corrects past zero89 chi += adj * adj / e90 } else {91 chi += d * d / e92 }93 }94 }95 let df = Double((r - 1) * (c - 1))96 let v = (chiRaw / (n * Double(min(r - 1, c - 1)))).squareRoot()97 let test = HypothesisTest(name: "Chi-square test of independence" + (useYates ? " (Yates correction)" : ""), statisticName: "χ²",98 statistic: chi, df: df, pValue: ChiSquaredDistribution(df: df).sf(chi), alternative: .greater,99 pValueDescription: "upper tail of χ²(\(Int(df)))", effectSize: NamedValue("Cramér's V", v),100 details: [NamedValue("Rows", Double(r)), NamedValue("Columns", Double(c)), NamedValue("Total count", n)],101 assumptions: ["Observations are independent and each is counted in exactly one cell",102 "Expected counts are large enough (rule of thumb: all ≥ 5, else consider Fisher's exact test)"])103 return ContingencyResult(test: test, observed: obs, expected: expected, residuals: resid, rowTotals: rowTotals, columnTotals: colTotals,104 total: n, cramersV: v, minimumExpected: expected.data.min() ?? .nan)105 }106}107