handstats 0.8.0__py3-none-any.whl

handstats/__init__.py

@@ -0,0 +1,92 @@
+"""handstats —— 面向学习的数理统计工具包。
+
+设计理念
+--------
+1. 每个统计过程都返回“富结果对象”（TestResult / IntervalResult / FitResult），
+   而不是一个裸数字：统计量、p 值、结论、中间步骤一次拿全；
+2. steps 机制输出【手算核对表】：把教材里的每一步计算（标准误、统计量、
+   自由度、p 值来源）逐行打印，方便和考试手算互相核对；
+3. 底层数值统一走 distributions.py 一个接口（目前由 scipy 提供支持），
+   以后想换成自己实现的数值算法，只改那一个文件。
+
+目录结构（可延展性）
+--------
+hypothesis/     假设检验（已有 z/t/卡方/F/比例/GLRT）
+interval/       区间估计（已有均值/均值差/配对/方差/比例区间）
+regression/     回归分析（已有 OLS/非线性 + 诊断与预测）
+anova/          方差分析（已有单/双因素、Tukey、Levene）
+nonparametric/  非参数检验（预留）
+resampling/     Bootstrap / 置换检验（预留）
+multivariate/   多元统计分析（预留）
+
+无代码外壳（规划）：外壳遍历 list_procedures() 即可自动生成方法菜单，
+展示统一结果对象的 conclusion() / show_steps() 文本即可，
+新增过程时外壳自动发现、零改动。雏形见 `python -m handstats`。
+"""
+from __future__ import annotations
+
+from handstats._registry import PROCEDURES, register
+from handstats.anova import anova_oneway, anova_twoway, levene_test, tukey_hsd
+from handstats.base import FitResult, IntervalResult, TestResult
+from handstats.hypothesis import (
+    chisquare_gof,
+    chisquare_ind,
+    ftest_2samp_var,
+    glrt_exponential_mean,
+    glrt_normal_mean,
+    glrt_test,
+    ttest_1samp,
+    ttest_2samp_ind,
+    ztest_1prop,
+    ztest_1samp,
+    ztest_2prop,
+)
+from handstats.interval import (
+    ci_mean,
+    ci_mean_2samp,
+    ci_paired_diff,
+    ci_proportion,
+    ci_var,
+)
+from handstats.regression import lin_reg, nonlin_reg
+
+__version__ = "0.8.0"
+
+__all__ = [
+    "TestResult",
+    "IntervalResult",
+    "FitResult",
+    "ztest_1samp",
+    "ttest_1samp",
+    "ttest_2samp_ind",
+    "chisquare_gof",
+    "chisquare_ind",
+    "ftest_2samp_var",
+    "ztest_1prop",
+    "ztest_2prop",
+    "glrt_test",
+    "glrt_normal_mean",
+    "glrt_exponential_mean",
+    "ci_mean",
+    "ci_mean_2samp",
+    "ci_paired_diff",
+    "ci_var",
+    "ci_proportion",
+    "lin_reg",
+    "nonlin_reg",
+    "anova_oneway",
+    "anova_twoway",
+    "tukey_hsd",
+    "levene_test",
+    "register",
+    "list_procedures",
+]
+
+
+def list_procedures() -> dict:
+    """返回 {过程名: 函数}——当前已注册的所有统计过程一览。
+
+    将来做命令行界面或图形界面时，直接遍历这个注册表就能自动生成
+    “可用方法”菜单，不需要改动任何已有代码。
+    """
+    return dict(PROCEDURES)

handstats/__main__.py

@@ -0,0 +1,17 @@
+"""`python -m handstats`：命令行一览当前包里所有可用的统计过程。
+
+这是未来“无代码外壳”的雏形：外壳程序同样只需要遍历注册表，
+就能自动生成方法菜单——新增过程时不需要为它写任何界面代码。
+"""
+from handstats import __version__, list_procedures
+
+
+def main() -> None:
+    procs = sorted(list_procedures())
+    print(f"handstats v{__version__} —— 可用统计过程（{len(procs)} 个）：")
+    for i, name in enumerate(procs, start=1):
+        print(f"  {i:>2}. {name}")
+
+
+if __name__ == "__main__":
+    main()

handstats/_registry.py

@@ -0,0 +1,35 @@
+"""过程注册表：包里所有统计过程的“花名册”。
+
+设计目的（可延展性的关键一环）
+--------
+- 每写一个新过程（检验/区间/回归……），只要在函数头上加
+  @register("名字")，它就自动出现在 handstats.list_procedures() 里；
+- 将来做 CLI / GUI / 自动生成文档时，遍历 PROCEDURES 即可，零改动；
+- 重复登记同名过程会直接抛错，防止笔误悄悄覆盖别人的函数。
+"""
+from __future__ import annotations
+
+from typing import Callable
+
+# {过程名: 函数}。包内模块通过 @register 写入，外部通过 list_procedures() 读取。
+PROCEDURES: dict[str, Callable] = {}
+
+
+def register(name: str) -> Callable:
+    """装饰器：把一个统计过程登记进注册表。
+
+    用法::
+
+        @register("ttest_1samp")
+        def ttest_1samp(x, mu0, ...):
+            ...
+    """
+
+    def decorator(func: Callable) -> Callable:
+        if name in PROCEDURES:
+            raise ValueError(f"过程名 {name!r} 已被注册，请换一个名字")
+        PROCEDURES[name] = func
+        func._procedure_name = name # 反查用：从函数找到它的注册名
+        return func
+
+    return decorator

handstats/anova/__init__.py

@@ -0,0 +1,17 @@
+"""方差分析子包（阶段 4）。
+
+已有：
+- anova_oneway：单因素方差分析（ANOVA 表、η² 效应量）
+- tukey_hsd：事后多重比较（族错误率控制在 α，Tukey-Kramer 支持不等样本量）
+- levene_test：方差齐性检验（Levene / Brown-Forsythe，ANOVA 的前提检查）
+- anova_twoway：双因素（无重复 r×c / 等重复 r×c×m 含交互检验），
+  返回复合结果 TwoWayResult
+
+规划：随机区组设计、非平衡双因素、多元方差分析（见 multivariate）。
+"""
+from handstats.anova.levene import levene_test
+from handstats.anova.oneway import anova_oneway
+from handstats.anova.posthoc import tukey_hsd
+from handstats.anova.twoway import TwoWayResult, anova_twoway
+
+__all__ = ["anova_oneway", "anova_twoway", "tukey_hsd", "levene_test", "TwoWayResult"]

handstats/anova/levene.py

@@ -0,0 +1,68 @@
+"""方差齐性检验：Levene / Brown-Forsythe（做 ANOVA 前的前提检查）。
+
+原理很巧：把每个观测换成“到组中心的绝对离差”z_ij = |y_ij - 中心_i|，
+再对 z 做一遍单因素 ANOVA——方差大的组，离差的平均幅度自然也大。
+中心用均值 = 经典 Levene；用中位数 = Brown-Forsythe（对偏态/离群更稳健）。
+"""
+from __future__ import annotations
+
+import numpy as np
+
+from handstats import distributions
+from handstats._registry import register
+from handstats.base import TestResult
+from handstats.anova.oneway import _as_groups, _oneway_core
+from handstats.validate import check_alpha
+
+
+@register("levene_test")
+def levene_test(groups, alpha=0.05, center="mean"):
+    """Levene 方差齐性检验：H0: k 个总体方差全相等。
+
+    参数
+    ----
+    groups : 若干组样本的序列
+    center : "mean" 经典 Levene（正态数据下功效高）；
+             "median" Brown-Forsythe（数据偏态或有离群点时更稳健）
+    alpha : 显著性水平
+
+    注：两总体场合可用 hypothesis.ftest_2samp_var（精确 F 检验，
+    但要求正态）；多总体场合用本检验。
+    """
+    alpha = check_alpha(alpha)
+    center = str(center).strip().lower()
+    if center not in ("mean", "median"):
+        raise ValueError(f'center 只能是 "mean" 或 "median"，收到 {center!r}')
+    arrays = _as_groups(groups)
+
+    if center == "mean":
+        centers = [float(np.mean(a)) for a in arrays]
+        desc = "均值"
+    else:
+        centers = [float(np.median(a)) for a in arrays]
+        desc = "中位数（Brown-Forsythe）"
+    z = [np.abs(a - c) for a, c in zip(arrays, centers)]
+    core = _oneway_core(z)
+    W = core["f_stat"]
+    p = distributions.f_sf(W, core["df_a"], core["df_e"])
+
+    centers_str = ", ".join(f"{c:.6g}" for c in centers)
+    steps = [
+        f"组数 k = {core['k']}，各组中心（{desc}） = ({centers_str})",
+        "离差 z_ij = |y_ij - 组中心|（若方差齐，各组 z 的平均水平应接近）",
+        f"对 z 做单因素 ANOVA：W = MS_A/MS_E = {W:.6g}，"
+        f"df = ({core['df_a']}, {core['df_e']})",
+        f"p = P(F ≥ W) = {p:.6g}（F 分布）",
+    ]
+    return TestResult(
+        statistic=W,
+        pvalue=p,
+        method=f"Levene 方差齐性检验（{desc}）",
+        alternative="greater",
+        alpha=alpha,
+        h0=f"{core['k']} 个总体方差全相等",
+        h1="至少有两个总体方差不相等",
+        params={"k": core["k"], "df_a": core["df_a"], "df_e": core["df_e"],
+                "centers": centers, "center": center},
+        steps=steps,
+    )

handstats/anova/oneway.py

@@ -0,0 +1,119 @@
+"""单因素方差分析（ANOVA）与它的两个配套：ANOVA 表、事后比较的公共底座。
+
+方差分析的骨架是一张表（教材核心）：
+    SS_A（组间/因素） + SS_E（组内/误差） = SS_T（总）
+    F = MS_A/MS_E = (SS_A/(k-1))/(SS_E/(n-k))
+H0: k 个总体均值全相等；H1: 至少两个不等。F 越大越异常（右尾）。
+本文件提供 _as_groups / _oneway_core / _anova_table 三个内部工具，
+tukey_hsd（posthoc.py）与 levene_test（levene.py）都复用它们。
+"""
+from __future__ import annotations
+
+import numpy as np
+
+from handstats import distributions
+from handstats._registry import register
+from handstats.base import TestResult
+from handstats.validate import as_sample, check_alpha
+
+
+def _as_groups(groups):
+    """把“若干组样本”统一为若干一维数组并检查（单因素家族共用）。"""
+    if isinstance(groups, (str, bytes)):
+        raise ValueError("groups 应是若干组样本的序列（列表/元组），不是字符串")
+    try:
+        items = list(groups)
+    except TypeError:
+        raise ValueError("groups 应是若干组样本的序列（列表/元组）")
+    if len(items) < 2:
+        raise ValueError(f"方差分析至少需要 2 组，收到 {len(items)} 组")
+    arrays = [as_sample(g, f"groups[{i}]") for i, g in enumerate(items)]
+    n = int(sum(a.size for a in arrays))
+    if n - len(arrays) < 1:
+        raise ValueError("总观测数必须大于组数（否则误差自由度 n - k = 0）")
+    return arrays
+
+
+def _oneway_core(arrays):
+    """单因素 ANOVA 的 SS 分解与 F（Levene 内部对 |离差| 复用同一函数）。"""
+    k = len(arrays)
+    n = int(sum(a.size for a in arrays))
+    means = np.array([float(a.mean()) for a in arrays])
+    grand = float(np.concatenate(arrays).mean())
+    ss_a = float(sum(arrays[i].size * (means[i] - grand) ** 2 for i in range(k)))
+    ss_e = float(sum(float(np.sum((a - a.mean()) ** 2)) for a in arrays))
+    df_a, df_e = k - 1, n - k
+    ms_a, ms_e = float(ss_a / df_a), float(ss_e / df_e)
+    return {
+        "k": k, "n": n, "means": means, "sizes": [int(a.size) for a in arrays],
+        "grand": grand, "ss_a": ss_a, "ss_e": ss_e, "df_a": df_a, "df_e": df_e,
+        "ms_a": ms_a, "ms_e": ms_e,
+        # ms_e = 0（组内无变异）时 F 视为无穷；调用方负责给出友好的 ValueError
+        "f_stat": float("inf") if ms_e == 0 else float(ms_a / ms_e),
+    }
+
+
+def _anova_table(rows):
+    """渲染方差分析表：rows = [(来源, ss, df, ms, f, p), ...]，None 表示空格。
+
+    教材里的方差分析表（来源 / SS / df / MS / F / p）逐行对应。
+    """
+    lines = [f"{'来源':<6}{'SS':>14}{'df':>6}{'MS':>14}{'F':>11}{'p':>11}"]
+    for src, ss, df, ms, f_, p in rows:
+        ms_s = f"{ms:>14.6g}" if ms is not None else f"{'':>14}"
+        f_s = f"{f_:>11.6g}" if f_ is not None else f"{'':>11}"
+        p_s = f"{p:>11.6g}" if p is not None else f"{'':>11}"
+        lines.append(f"{src:<6}{ss:>14.6g}{df:>6g}{ms_s}{f_s}{p_s}")
+    return lines
+
+
+@register("anova_oneway")
+def anova_oneway(groups, alpha=0.05):
+    """单因素方差分析：H0: k 个总体均值全相等。
+
+    参数
+    ----
+    groups : 若干组样本的序列（各组样本量可以不同）
+    alpha : 显著性水平
+
+    返回 TestResult；params 里带完整 SS 分解、各组均值和 η²（效应量：
+    因素解释的方差占比，SS_A/SS_T）以及 anova_table（表格文本行）。
+    前提：各组近似正态、方差齐（用 levene_test 检查）。
+    """
+    alpha = check_alpha(alpha)
+    arrays = _as_groups(groups)
+    core = _oneway_core(arrays)
+    k = core["k"]
+    if core["ms_e"] <= 0:
+        raise ValueError("组内均方为 0（每组内部数据完全相同），F 无定义")
+    F = core["f_stat"]
+    p = distributions.f_sf(F, core["df_a"], core["df_e"])
+
+    means_str = ", ".join(f"{m:.6g}" for m in core["means"])
+    ss_t = core["ss_a"] + core["ss_e"]
+    table = _anova_table([
+        ("因素A", core["ss_a"], core["df_a"], core["ms_a"], F, p),
+        ("误差E", core["ss_e"], core["df_e"], core["ms_e"], None, None),
+        ("总和T", ss_t, core["n"] - 1, None, None, None),
+    ])
+    steps = [
+        f"组数 k = {k}，各组样本量 = {core['sizes']}，总 n = {core['n']}",
+        f"各组均值 = ({means_str})，总均值 = {core['grand']:.6g}",
+        f"SS_A = Σn_i·(组均值_i - 总均值)² = {core['ss_a']:.6g}，"
+        f"SS_E = ΣΣ(y_ij - 组均值_i)² = {core['ss_e']:.6g}",
+        "方差分析表：", *table,
+        f"p = P(F ≥ {F:.6g}) = {p:.6g}"
+        f"（F 分布，dfn = {core['df_a']}，dfd = {core['df_e']}）",
+    ]
+    return TestResult(
+        statistic=F,
+        pvalue=p,
+        method="单因素方差分析",
+        alternative="greater",
+        alpha=alpha,
+        h0=f"{k} 个总体均值全相等",
+        h1="至少有两个总体均值不相等",
+        params={**core, "ss_t": ss_t, "eta_sq": core["ss_a"] / ss_t,
+                "anova_table": table},
+        steps=steps,
+    )

handstats/anova/posthoc.py

@@ -0,0 +1,76 @@
+"""事后多重比较（post-hoc）：Tukey HSD。
+
+为什么 ANOVA 拒绝 H0 之后不直接逐对做 t 检验？
+--------
+k 组有 k(k-1)/2 个均值对；逐对 t 检验会让“至少一个假阳性”的族错误率
+随对数膨胀（3 组时 3 对、6 组时 15 对）。Tukey HSD 把族错误率精确控制
+在 α：用学生化极差分布的临界值 q(α; k, df)，所有对共用同一个
+“诚实显著差”HSD = q·SE，一次比较全部对。
+"""
+from __future__ import annotations
+
+import numpy as np
+
+from handstats import distributions
+from handstats._registry import register
+from handstats.base import TestResult
+from handstats.anova.oneway import _as_groups, _oneway_core
+from handstats.validate import check_alpha
+
+
+@register("tukey_hsd")
+def tukey_hsd(groups, alpha=0.05):
+    """Tukey HSD 事后多重比较（族错误率 = α）：到底哪些组的均值不同？
+
+    参数
+    ----
+    groups : 若干组样本的序列（与 anova_oneway 相同的输入）
+    alpha : 族错误率（整体犯第一类错误的概率上限）
+
+    返回 list[TestResult]，按 (组i, 组j) 字典序排列（i < j）；
+    每个的 params 里有均值差 diff、区间 [lower, upper]、HSD 半宽。
+    组样本量不同时自动用 Tukey-Kramer 公式。
+    """
+    alpha = check_alpha(alpha)
+    arrays = _as_groups(groups)
+    core = _oneway_core(arrays)
+    if core["ms_e"] <= 0:
+        raise ValueError("组内均方为 0（每组内部数据完全相同），无法做多重比较")
+    k, df_e, mse = core["k"], core["df_e"], core["ms_e"]
+    q_crit = distributions.studentized_range_ppf(1 - alpha, k, df_e)
+
+    results = []
+    for i in range(k):
+        for j in range(i + 1, k):
+            ni, nj = arrays[i].size, arrays[j].size
+            diff = float(core["means"][i] - core["means"][j])
+            se = float(np.sqrt(mse / 2.0 * (1.0 / ni + 1.0 / nj)))
+            q = abs(diff) / se
+            p = distributions.studentized_range_sf(q, k, df_e)
+            half = q_crit * se
+            steps = [
+                f"前提：ANOVA 的 MSE = {mse:.6g}，误差自由度 df = {df_e}，组数 k = {k}",
+                f"均值{i + 1} = {core['means'][i]:.6g}（n = {ni}），"
+                f"均值{j + 1} = {core['means'][j]:.6g}（n = {nj}），"
+                f"均值差 = {diff:.6g}",
+                f"SE = √(MSE/2·(1/n_i + 1/n_j)) = {se:.6g}",
+                f"统计量 q = |均值差|/SE = {q:.6g}",
+                f"临界值 q(α; k, df) = {q_crit:.6g}，"
+                f"诚实显著差 HSD = 临界值×SE = {half:.6g}",
+                f"区间 = 均值差 ± HSD = [{diff - half:.6g}, {diff + half:.6g}]，"
+                f"p = P(Q ≥ q) = {p:.6g}（学生化极差分布，k = {k}，df = {df_e}）",
+            ]
+            results.append(TestResult(
+                statistic=float(q),
+                pvalue=float(p),
+                method=f"Tukey HSD：组{i + 1} vs 组{j + 1}",
+                alternative="greater",
+                alpha=alpha,
+                h0=f"μ{i + 1} = μ{j + 1}",
+                h1=f"μ{i + 1} ≠ μ{j + 1}",
+                params={"diff": diff, "se": se, "lower": diff - half,
+                        "upper": diff + half, "hsd": half, "q_crit": q_crit,
+                        "n_i": ni, "n_j": nj, "k": k, "df": df_e},
+                steps=steps,
+            ))
+    return results