Repository Public
1import Foundation2import SheetCore3import Statistics4import AnalysisKit56/// Bootstrap confidence interval of a statistic of one column.7enum BootstrapTool {8 static let statistics: [FieldOption] = [9 FieldOption("mean", L("Mean")), FieldOption("median", L("Median")), FieldOption("sd", L("Standard deviation")),10 FieldOption("trimmed", L("Trimmed mean")), FieldOption("quantile", L("Quantile")),11 ]1213 static let descriptor: ToolDescriptor = {14 var t = ToolDescriptor(15 id: "resampling.bootstrap", title: L("Bootstrap Confidence Interval"), group: L("Resampling"), systemImage: "arrow.triangle.2.circlepath",16 summary: L("Resamples the data with replacement to estimate the sampling variability of a statistic: percentile and BCa intervals."),17 fields: [18 .range("data", L("Data range")),19 .column("x", L("Variable")),20 .choice("statistic", L("Statistic"), statistics),21 .percent("trim", L("Proportion trimmed from each tail"), 0.10, min: 0, max: 0.45, visible: { $0.choice("statistic") == "trimmed" }),22 .percent("prob", L("Quantile probability"), 0.90, min: 0.01, max: 0.99, visible: { $0.choice("statistic") == "quantile" }),23 .integer("resamples", L("Resamples"), 9999, min: 99, max: 1_000_000),24 .percent("level", L("Confidence level"), 0.95, min: 0.5, max: 0.9999),25 .integer("seed", L("Random seed"), 1, min: 0, max: 2_000_000_000),26 ],27 info: [28 L("Percentile interval: type-7 quantiles of the bootstrap replicates. BCa: bias correction z₀ (ties counted ½) and jackknife acceleration. Both match scipy.stats.bootstrap on the same resamples."),29 L("The generator is xoshiro256**: equal seeds give bit-identical results."),30 L("Bootstrap-t (studentized), stratified and block bootstraps are not shipped; the plain bootstrap assumes independent observations."),31 ],32 run: run)33 t.demo = { _, v in v.set("data", range: "Regression!A1:G121"); v.set("x", column: 0); v.set("statistic", choice: "median") }34 return t35 }()3637 static func statistic(_ input: ToolInput) -> (name: String, f: @Sendable ([Double]) -> Double) {38 switch input.values.choice("statistic") {39 case "median": return (L("Median"), { Descriptive.median($0) })40 case "sd": return (L("Standard deviation"), { Descriptive.standardDeviation($0) })41 case "trimmed":42 let p = min(max(input.values.number("trim"), 0), 0.45)43 return (L("Trimmed mean (%@ per tail)", Fmt.percent(p, 0, locale: input.locale)), { Descriptive.trimmedMean($0, proportion: p) })44 case "quantile":45 let p = min(max(input.values.number("prob"), 0.01), 0.99)46 return (L("Quantile %@", Fmt.percent(p, 0, locale: input.locale)), { Descriptive.quantile($0, p) })47 default: return (L("Mean"), { Descriptive.mean($0) })48 }49 }5051 static func run(_ input: ToolInput) throws -> ToolResult {52 let frame = try input.frame()53 let col = try input.column("x")54 let x = col.present55 guard x.count >= 3 else { throw ToolError(L("“%@” has %d numeric observations; at least %d are needed.", col.name, x.count, 3)) }56 let b = max(input.values.int("resamples"), 99), level = Sup.level(input), seed = Sup.seed(input), loc = input.locale57 let stat = statistic(input)58 var calls = 059 let total = Double(b + x.count + 1)60 let r = try Bootstrap.run(x, resamples: b, confidenceLevel: level, seed: seed) { sample in61 calls += 162 if calls % 512 == 0 { try input.checkCancelled(); input.progress(Double(calls) / total) }63 return stat.f(sample)64 }65 input.progress(1)66 let pct = Fmt.percent(level, level * 100 == (level * 100).rounded() ? 0 : 1, locale: loc)67 var rows: [[Value]] = [[.text(L("Method")), .text(L("%@ lower", pct)), .text(L("%@ upper", pct))],68 [.text(L("Percentile")), .finite(r.percentile.lower), .finite(r.percentile.upper)]]69 if let bca = r.bca { rows.append([.text(L("BCa (bias-corrected and accelerated)")), .finite(bca.lower), .finite(bca.upper)]) }70 let details = ReportTable.keyValue(title: L("Bootstrap summary"), header: (L("Quantity"), L("Value")), [71 (L("Statistic"), .text(stat.name), .auto), (L("Estimate"), .finite(r.estimate), .auto), (L("Bootstrap standard error"), .finite(r.standardError), .auto),72 (L("Bootstrap bias"), .finite(r.bias), .auto), (L("Bias correction z₀"), .finite(r.biasCorrection), .fixed(4)),73 (L("Acceleration"), .finite(r.acceleration), .fixed(4)), (L("Observations"), .finite(Double(r.sampleSize)), .integer),74 (L("Resamples"), .finite(Double(r.resamples)), .integer), (L("Random seed"), .finite(Double(seed)), .integer),75 ])76 var hist = ChartKit.histogram(r.replicates.filter(\.isFinite), xTitle: stat.name, yTitle: L("Frequency"))77 hist.annotations = [.referenceLine(.vertical, at: r.estimate, label: L("Estimate")), .referenceLine(.vertical, at: r.percentile.lower), .referenceLine(.vertical, at: r.percentile.upper)]78 var notes = [L("%d resamples with replacement of %d observations, seed %d.", r.resamples, r.sampleSize, Int(seed))]79 if r.bca == nil { notes.append(L("The BCa interval is not available for this sample (degenerate jackknife or replicates).")) }80 if col.missingCount > 0 { notes.append(L("%d missing values were skipped.", col.missingCount)) }81 let blocks: [ResultBlock] = [82 .metrics([Metric(stat.name, r.estimate), Metric(L("Bootstrap standard error"), r.standardError),83 Metric(L("%@ interval (BCa)", pct), text: Fmt.number((r.bca ?? r.percentile).lower, locale: loc) + " – " + Fmt.number((r.bca ?? r.percentile).upper, locale: loc))]),84 .table(ReportTable(title: L("Confidence intervals"), rows: rows)),85 .table(details),86 .chart(ChartBlock(title: L("Bootstrap distribution"), spec: hist,87 summary: L("Histogram of %d bootstrap replicates of the %@; estimate %@, percentile interval %@ to %@.", r.resamples, stat.name,88 Fmt.number(r.estimate, locale: loc), Fmt.number(r.percentile.lower, locale: loc), Fmt.number(r.percentile.upper, locale: loc)), height: 240)),89 .assumptions([L("Observations are independent draws from the same distribution."),90 L("The sample is large enough to represent the population; intervals for extreme quantiles of small samples are unreliable.")], title: L("Assumptions")),91 .note(notes),92 ]93 return ToolResult(title: L("Bootstrap Confidence Interval"), subtitle: L("%@ — %@ of %@", frame.label, stat.name, col.name), blocks: blocks, sheetName: L("Bootstrap"))94 }95}9697/// Permutation test for two samples.98enum PermutationTool {99 static let descriptor: ToolDescriptor = {100 var t = ToolDescriptor(101 id: "resampling.permutation", title: L("Permutation Test"), group: L("Resampling"), systemImage: "shuffle",102 summary: L("Compares two samples without distributional assumptions by re-randomising the group labels (or the signs of paired differences)."),103 fields: [104 .range("data", L("Data range")),105 .column("x", L("Sample 1")),106 .column("y", L("Sample 2")),107 .choice("design", L("Design"), [FieldOption("independent", L("Independent samples")), FieldOption("paired", L("Paired samples"))]),108 .choice("statistic", L("Statistic"), [FieldOption("mean", L("Difference of means")), FieldOption("median", L("Difference of medians"))]),109 .choice("alternative", L("Alternative hypothesis"), Sup.alternatives),110 .integer("resamples", L("Resamples"), 9999, min: 99, max: 1_000_000, help: L("The test is exact when the number of distinct arrangements does not exceed this value.")),111 .integer("seed", L("Random seed"), 1, min: 0, max: 2_000_000_000),112 .alpha(L("Significance level α")),113 ],114 info: [115 L("Rule and p-value convention of scipy.stats.permutation_test: exact enumeration when C(n+m, n) (or 2ⁿ for pairs) ≤ resamples, otherwise a Monte Carlo p-value (b + 1)/(m + 1)."),116 L("Two-sided p-value: 2·min(lower, upper), capped at 1."),117 L("For paired samples the statistic is the mean (or median) of the differences."),118 ],119 run: run)120 t.demo = { _, v in v.set("data", range: "Groups!A1:C31"); v.set("x", column: 0); v.set("y", column: 1) }121 return t122 }()123124 static func run(_ input: ToolInput) throws -> ToolResult {125 let frame = try input.frame()126 let cx = try input.column("x"), cy = try input.column("y")127 guard cx.index != cy.index else { throw ToolError(L("Choose two different columns.")) }128 let paired = input.values.choice("design") == "paired", median = input.values.choice("statistic") == "median"129 let alt = Sup.alternative(input), alpha = Sup.alpha(input), seed = Sup.seed(input), loc = input.locale130 let b = max(input.values.int("resamples"), 99)131 let r: PermutationTestResult132 let n1: Int, n2: Int133 var calls = 0134 func tick() throws { calls += 1; if calls % 512 == 0 { try input.checkCancelled(); input.progress(min(Double(calls) / Double(b), 1)) } }135 if paired {136 let (_, cols) = DataFrame.listwise([cx.numbers, cy.numbers])137 guard cols[0].count >= 2 else { throw ToolError(L("At least two complete pairs are needed.")) }138 n1 = cols[0].count; n2 = n1139 r = try PermutationTest.paired(cols[0], cols[1], alternative: alt, resamples: b, seed: seed) { d in140 try tick(); return median ? Descriptive.median(d) : Descriptive.mean(d)141 }142 } else {143 let x = cx.present, y = cy.present144 guard x.count >= 2, y.count >= 2 else { throw ToolError(L("Each sample needs at least two numeric observations.")) }145 n1 = x.count; n2 = y.count146 r = try PermutationTest.twoSample(x, y, alternative: alt, resamples: b, seed: seed) { a, c in147 try tick(); return median ? Descriptive.median(a) - Descriptive.median(c) : Descriptive.mean(a) - Descriptive.mean(c)148 }149 }150 input.progress(1)151 let statName = paired ? (median ? L("Median of the differences") : L("Mean of the differences")) : (median ? L("Difference of medians") : L("Difference of means"))152 let table = ReportTable.keyValue(title: L("Permutation test"), header: (L("Quantity"), L("Value")), [153 (statName, .finite(r.statistic), .auto), (L("p-value"), .finite(r.pValue), .pValue), (L("p-value refers to"), .text(Interpret.sidedness(alt)), .auto),154 (L("Design"), .text(paired ? L("paired samples (sign flips)") : L("independent samples (labels reshuffled)")), .auto),155 (L("Type"), .text(r.exact ? L("exact (all arrangements enumerated)") : L("Monte Carlo (random arrangements)")), .auto),156 (L("Arrangements evaluated"), .finite(Double(r.permutations)), .integer),157 (L("Observations, sample 1"), .finite(Double(n1)), .integer), (L("Observations, sample 2"), .finite(Double(n2)), .integer),158 (L("Random seed"), r.exact ? .text("—") : .finite(Double(seed)), .integer),159 ])160 var hist = ChartKit.histogram(r.nullDistribution.filter(\.isFinite), xTitle: statName, yTitle: L("Frequency"))161 hist.annotations = [.referenceLine(.vertical, at: r.statistic, label: L("Observed"))]162 let null = paired ? L("the paired differences are symmetric around zero (no systematic difference)") : L("the two samples come from the same distribution (labels are exchangeable)")163 let blocks: [ResultBlock] = [164 .metrics([Metric(statName, r.statistic), Metric(L("p-value"), r.pValue, .pValue, detail: "(" + Interpret.sidedness(alt) + ")"),165 Metric(L("Arrangements"), Double(r.permutations), .integer), Metric(L("Type"), text: r.exact ? L("exact") : L("Monte Carlo"))]),166 .table(table),167 .interpretation(Interpret.decision(p: r.pValue, alpha: alpha, null: null, locale: loc)),168 .chart(ChartBlock(title: L("Null distribution of the statistic"), spec: hist,169 summary: L("Histogram of the statistic over %d arrangements; the observed value is %@ (p = %@).", r.permutations,170 Fmt.number(r.statistic, locale: loc), Fmt.p(r.pValue, locale: loc)), height: 240)),171 .assumptions([paired ? L("Pairs are independent of one another.") : L("Observations are independent and exchangeable between the groups under the null hypothesis."),172 L("No normality assumption is needed.")], title: L("Assumptions")),173 ]174 return ToolResult(title: L("Permutation Test"), subtitle: L("%@ — %@ vs %@", frame.label, cx.name, cy.name), blocks: blocks, sheetName: L("Permutation test"))175 }176}177