SPB Git

Repository Public

ResamplingTools.swift 13.1 KB 177 lines swift

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
Files main
Menu

Theme