Repository Public
1import Foundation2import SheetCore3import SheetCharts4import Statistics5import AnalysisKit67/// Helpers shared by the Describe / Compare / Relationships tools.8enum Common {9 static var groupDescribe: String { L("Describe") }10 static var groupCompare: String { L("Compare") }11 static var groupRelate: String { L("Relationships") }1213 /// Choice of the alternative hypothesis.14 static func alternativeField(visible: @escaping @Sendable (FormValues) -> Bool = { _ in true }) -> FormField {15 .choice("alternative", L("Alternative hypothesis"), [16 FieldOption("twoSided", L("Two-sided (≠)")), FieldOption("less", L("Less than (<)")), FieldOption("greater", L("Greater than (>)")),17 ], visible: visible)18 }1920 static func alternative(_ v: FormValues) -> Alternative {21 switch v.choice("alternative") {22 case "less": .less23 case "greater": .greater24 default: .twoSided25 }26 }2728 static func levelField(visible: @escaping @Sendable (FormValues) -> Bool = { _ in true }) -> FormField {29 .percent("level", L("Confidence level"), 0.95, min: 0.5, max: 0.9999, visible: visible)30 }3132 static func alpha(_ v: FormValues) throws -> Double {33 let a = v.number("alpha")34 guard a > 0, a < 1 else { throw ToolError(L("The significance level α must be between 0 and 1.")) }35 return a36 }3738 static func level(_ v: FormValues) throws -> Double {39 let l = v.number("level")40 guard l > 0, l < 1 else { throw ToolError(L("The confidence level must be between 0 % and 100 %.")) }41 return l42 }4344 /// Rows where both columns hold a number.45 static func pairs(_ a: DataColumn, _ b: DataColumn) -> (x: [Double], y: [Double]) {46 let (_, cols) = DataFrame.listwise([a.numbers, b.numbers])47 return (cols[0], cols[1])48 }4950 /// "n values were missing and skipped" note for independent samples (nil when nothing is missing).51 static func missingNote(_ columns: [DataColumn]) -> String? {52 let missing = columns.reduce(0) { $0 + $1.missingCount }53 return missing > 0 ? L("%d missing values (blank cells, text or errors) were skipped.", missing) : nil54 }5556 static func pairedNote(_ a: DataColumn, _ b: DataColumn, kept: Int) -> String? {57 kept < a.count ? L("%d of %d rows have both values and were used; incomplete pairs were dropped.", kept, a.count) : nil58 }5960 /// Localizes the name and the sidedness text of an engine test.61 static func localized(_ t: HypothesisTest) -> HypothesisTest {62 var t = t63 if t.pValueDescription == t.alternative.label { t.pValueDescription = Interpret.sidedness(t.alternative) }64 t.name = testName(t.name)65 return t66 }6768 /// Localized name of an engine test (the engine names are English).69 static func testName(_ name: String) -> String {70 switch name {71 case "One-sample t-test": L("One-sample t-test")72 case "Two-sample t-test (pooled variance)": L("Two-sample t-test (pooled variance)")73 case "Welch two-sample t-test": L("Welch two-sample t-test")74 case "Paired t-test": L("Paired t-test")75 case "One-sample z-test": L("One-sample z-test")76 case "Two-sample z-test": L("Two-sample z-test")77 case "One-sample proportion z-test": L("One-sample proportion z-test")78 case "Two-sample proportion z-test": L("Two-sample proportion z-test")79 case "Chi-square goodness-of-fit test": L("Chi-square goodness-of-fit test")80 case "Chi-square test of independence": L("Chi-square test of independence")81 case "Chi-square test of independence (Yates correction)": L("Chi-square test of independence (Yates correction)")82 case "F-test for equality of variances": L("F-test for equality of variances")83 case "Levene's test for equality of variances": L("Levene's test for equality of variances")84 case "Brown–Forsythe test for equality of variances": L("Brown–Forsythe test for equality of variances")85 case "Bartlett's test for equality of variances": L("Bartlett's test for equality of variances")86 case "Shapiro–Wilk normality test": L("Shapiro–Wilk normality test")87 case "Jarque–Bera normality test": L("Jarque–Bera normality test")88 case "Mann–Whitney U test": L("Mann–Whitney U test")89 case "Wilcoxon signed-rank test": L("Wilcoxon signed-rank test")90 case "Kruskal–Wallis H test": L("Kruskal–Wallis H test")91 case "Pearson correlation test": L("Pearson correlation test")92 case "Spearman rank correlation test": L("Spearman rank correlation test")93 case "Kendall rank correlation test": L("Kendall rank correlation test")94 default: name95 }96 }9798 /// The kit's standard blocks of a test, with whole-number detail rows (sample sizes, counts) shown as integers.99 static func testBlocks(_ test: HypothesisTest, alpha: Double, null: String, locale: Locale) -> [ResultBlock] {100 let t = localized(test)101 var blocks = TestBlocks.blocks(t, alpha: alpha, null: null, locale: locale)102 // degrees of freedom and counts: whole numbers without decimals (the statistic in the first row keeps them)103 if let i = blocks.firstIndex(where: { if case .table = $0 { true } else { false } }), case .table(var table) = blocks[i] {104 for (r, row) in table.rows.enumerated() where r > table.headerRows {105 if row.count > 1, case .number(let x) = row[1], x == x.rounded(), abs(x) < 1e12, table.rowFormats[r] == nil || table.rowFormats[r] == .auto {106 table.rowFormats[r] = .integer107 }108 }109 blocks[i] = .table(table)110 }111 return blocks112 }113114 /// Standard result of a hypothesis test: headline, table, interpretation, assumptions, then extra blocks.115 static func testResult(_ test: HypothesisTest, title: String, subtitle: String, alpha: Double, null: String, locale: Locale,116 notes: [String?] = [], extra: [ResultBlock] = [], sheetName: String) -> ToolResult {117 var blocks = testBlocks(test, alpha: alpha, null: null, locale: locale)118 blocks.append(contentsOf: extra)119 let lines = notes.compactMap { $0 }120 if !lines.isEmpty { blocks.append(.note(lines)) }121 return ToolResult(title: title, subtitle: subtitle, blocks: blocks, sheetName: sheetName)122 }123124 /// Count, mean, standard deviation of each sample.125 static func samplesTable(_ samples: [(label: String, values: [Double])], title: String? = nil) -> ReportTable {126 var rows: [[Value]] = [[.text(L("Sample")), .text(L("n")), .text(L("Mean")), .text(L("Standard deviation")), .text(L("Minimum")), .text(L("Maximum"))]]127 for s in samples {128 rows.append([.text(s.label), .number(Double(s.values.count)), .finite(Descriptive.mean(s.values)),129 .finite(Descriptive.standardDeviation(s.values)), .finite(s.values.min()), .finite(s.values.max())])130 }131 return ReportTable(title: title ?? L("Sample statistics"), rows: rows, columnFormats: [1: .integer])132 }133134 /// Box plots of several samples.135 static func boxPlot(_ samples: [(label: String, values: [Double])], title: String, yTitle: String, locale: Locale) -> ChartBlock {136 var spec = ChartSpec(kind: .boxPlot)137 spec.series = samples.map { SeriesSpec(name: $0.label, values: .literal($0.values)) }138 spec.yAxis.title = yTitle139 spec.options.showMean = true140 spec.legend = LegendSpec(position: .none)141 let parts = samples.map { L("%@: median %@", $0.label, Fmt.number(Descriptive.median($0.values), locale: locale)) }142 return ChartBlock(title: title, spec: spec, summary: L("Box plots of %d samples.", samples.count) + " " + parts.joined(separator: "; ") + ".", height: 230)143 }144}145146/// Input of several independent samples: either one column per group, or a value column with a grouping column.147enum GroupFields {148 static func fields(visible: @escaping @Sendable (FormValues) -> Bool = { _ in true }) -> [FormField] {149 [150 .choice("layout", L("Data layout"), [FieldOption("columns", L("One column per group")), FieldOption("long", L("Values and a group column"))],151 visible: visible),152 .columns("groupCols", L("Group columns"), visible: { visible($0) && $0.choice("layout") != "long" }),153 .column("value", L("Value column"), visible: { visible($0) && $0.choice("layout") == "long" }),154 .column("factor", L("Group column"), numeric: false, visible: { visible($0) && $0.choice("layout") == "long" }),155 ]156 }157158 /// The groups with their missing values removed; throws when fewer than `minimum` groups are given.159 static func read(_ input: ToolInput, minimum: Int = 2) throws -> (groups: [(label: String, values: [Double])], missing: Int) {160 var groups: [(label: String, values: [Double])]161 var missing = 0162 if input.values.choice("layout") == "long" {163 let value = try input.column("value"), factor = try input.column("factor")164 guard value.index != factor.index else { throw ToolError(L("The value column and the group column must be different.")) }165 groups = DataFrame.groups(values: value, by: factor)166 missing = value.count - groups.reduce(0) { $0 + $1.values.count }167 } else {168 let cols = try input.columns("groupCols", atLeast: minimum)169 groups = cols.map { ($0.name, $0.present) }170 missing = cols.reduce(0) { $0 + $1.missingCount - $1.blankCount }171 }172 guard groups.count >= minimum else { throw ToolError(L("At least %d groups are required.", minimum)) }173 guard groups.allSatisfy({ !$0.values.isEmpty }) else { throw ToolError(L("Every group needs at least one numeric value.")) }174 return (groups, missing)175 }176177 static func missingNote(_ missing: Int) -> String? {178 missing > 0 ? L("%d rows without a usable value or group were skipped.", missing) : nil179 }180}181