卡方检验表避坑指南：3个实战案例教你搞定API变更
版本升级后 API 全变了？别慌，这篇避坑指南专治各种统计库升级导致的“水土不服”。
在水利工程的数据分析里，卡方检验表是检验独立性、拟合优度的核心工具。很多老手都遇到过：项目从 Python 3.8 升到 3.11，或者 scipy 从 1.5 升到 1.12，原本跑得飞快的脚本突然报错 ValueError: Input must be non-negative，或者 P 值计算结果对不上。这不仅是代码问题，更是工程化思维的缺失。
今天不聊虚的，直接从一个真实的“洪水频率分析”项目入手，从零搭建一个稳健的卡方检验模块。我们会深入剖析 scipy.stats.chi2 的底层逻辑，拆解 GitHub 上几个主流开源仓库的陷阱，并给出一套可复现、可维护的代码方案。无论你是刚入门的水利工程师，还是被升级坑过的老兵，这套实战经验都能帮你省下至少半天调错时间。
项目目标与场景拆解
在动手写代码前，必须明确我们要解决什么具体问题。在水利工程中，卡方检验主要应用在两个场景：拟合优度检验：验证观测到的洪水峰值分布是否符合某个理论分布（如皮尔逊III型分布、对数正态分布）。这是水工设计中最常见的应用，直接关系到设计洪水标准的准确性。
独立性检验：分析不同流域、不同季节的降雨量与径流量之间是否存在统计上的显著关联。核心痛点：大多数教程只给一行 chi2_contingency 的代码，但忽略了输入数据的预处理。在实际工程中，原始水文数据往往存在缺失值、负值（如流量低于基流线时的处理误差）或非整数（如经过率化处理的数据）。直接扔给 scipy 就会报错。
项目目标：构建一个封装良好的 ChiSquareValidator 类。
实现自动数据清洗、非负校验、自由度动态计算。
输出标准化的检验报告，包含卡方值、P值、临界值及结论。
确保代码在 scipy 1.7 至 1.12 版本间向后兼容。目录结构与依赖管理
为了保持工程化规范，我们采用模块化的目录结构。不要把所有代码塞在一个 main.py 里，那是新手最容易犯的错。
chi_square_project/
├── requirements.txt # 依赖锁定，防止环境漂移
├── data/
│ └── sample_rainfall.csv # 模拟的水文观测数据
├── src/
│ ├── __init__.py
│ ├── preprocessor.py # 数据清洗与预处理模块
│ ├── chi_square_core.py# 核心检验逻辑
│ └── reporter.py # 报告生成模块
├── tests/
│ └── test_chi_square.py# 单元测试
└── main.py # 入口文件依赖管理关键点：
在 requirements.txt 中，不要只写 scipy。必须锁定大版本，甚至小版本。
numpy=1.21.0,1.25.0
scipy=1.7.0,1.13.0
pandas=1.3.0为什么这样写？因为 numpy 2.0 之后，某些底层数组操作发生了变更，可能导致 scipy 的旧版本出现兼容性问题。锁定范围能避免“在我电脑上能跑，在你电脑上崩”的经典悲剧。
核心代码实现：逐行拆解
这是本文的重点。我们将分三个模块实现，每个模块都针对“API变更”和“数据陷阱”做了防御性编程。
1. 数据预处理模块 (preprocessor.py)
很多报错源于数据本身。scipy.stats.chi2 要求输入必须是非负实数。在水利工程中，经过对数变换或标准化后的数据可能出现负值，必须处理。
import numpy as np
import pandas as pdclass DataPreprocessor:def __init__(self, data_path: str):self.data_path = data_pathself.data = Nonedef load_data(self) - pd.DataFrame:加载CSV数据，自动处理缺失值try:self.data = pd.read_csv(self.data_path)# 水利工程数据常见NaN，这里用中位数填充，比均值更鲁棒self.data.fillna(self.data.median(), inplace=True)return self.dataexcept FileNotFoundError:raise FileNotFoundError(fData file {self.data_path} not found)def prepare_observed(self, column_name: str) - np.ndarray:提取观测值并转换为非负数组核心逻辑：如果数据为负，说明参考基准线选取有误，需重新校准if column_name not in self.data.columns:raise ValueError(fColumn {column_name} does not exist)values = self.data[column_name].valuesif np.any(values 0):# 简单处理：将负值视为0，但在实际工程中应警告用户print(fWarning: Detected {np.sum(values 0)} negative values. Clipping to 0.)values = np.clip(values, 0, None)return values.astype(float)避坑点：np.clip 的使用。直接删除负值会导致样本量变化，影响自由度计算。将其置为0是统计学上的一种保守处理，具体策略需根据水文特性决定。
2. 核心检验模块 (chi_square_core.py)
这里涉及 scipy 的 API 变更。旧版本中，chi2.cdf 和 chi2.ppf 的参数顺序在不同版本间有过细微调整（主要是尾概率 upper_tail 的处理）。我们采用最稳定的 chi2.sf (Survival Function，即 1 - CDF) 来计算 P 值，因为它在尾部计算上比 1 - cdf 数值精度更高。
from scipy import stats
import numpy as npclass ChiSquareValidator:def __init__(self, alpha: float = 0.05):self.alpha = alphadef fit_goodness_test(self, observed: np.ndarray, expected: np.ndarray, df: int) - dict:执行拟合优度检验:param observed: 观测频数数组:param expected: 期望频数数组:param df: 自由度:return: 包含检验结果的字典# 校验：观测值和期望值长度必须一致if len(observed) != len(expected):raise ValueError(Observed and expected arrays must have the same length)# 校验：期望频数不能为0，否则卡方公式分母为0if np.any(expected == 0):raise ValueError(Expected frequencies cannot be zero)# 计算卡方统计量: sum((O-E)^2 / E)# 使用 np.sum 而非 sum，确保处理的是数组chi2_stat = np.sum((observed - expected) ** 2 / expected)# 计算 P 值# 注意：scipy.stats.chi2.sf 返回的是 P(X x)，即右尾概率# 这正是我们需要的 P 值p_value = stats.chi2.sf(chi2_stat, df)# 获取临界值critical_value = stats.chi2.ppf(1 - self.alpha, df)# 结论判断is_significant = p_value self.alphareturn {chi2_stat: float(chi2_stat),p_value: float(p_value),critical_value: float(critical_value),df: df,alpha: self.alpha,is_significant: bool(is_significant),conclusion: Reject H0: Data does not fit distribution if is_significant else Fail to reject H0: Data fits distribution}def independence_test(self, observed_matrix: np.ndarray) - dict:执行独立性检验（列联表）使用 scipy.stats.chi2_contingency# 检查输入是否为2D数组if observed_matrix.ndim != 2:raise ValueError(Input must be a 2D array for independence test)# chi2_contingency 返回 (chi2, p, dof, expected_freq)chi2, p, dof, expected_freq = stats.chi2_contingency(observed_matrix)return {chi2_stat: float(chi2),p_value: float(p),df: int(dof),expected_freq: expected_freq,is_significant: bool(p self.alpha)}深度解析：为什么用 sf 而不是 1-cdf？ 当卡方值很大时，P 值极小（如 1e-10），1 - cdf 会因为浮点数精度损失变成 0，而 sf 能保留有效数字。这是数值计算的经典避坑点。
自由度 df 的计算：在拟合优度中，df = k - 1 - m，其中 k 是组数，m 是估计参数的个数。比如用皮尔逊III型分布，估计了均值和偏度两个参数，若分5组，df = 5 - 1 - 2 = 2。很多初学者直接写死 df=k-1，导致 P 值错误。3. 报告生成模块 (reporter.py)
水利工程从业者需要向非技术领导汇报。纯数字没有意义，需要转化为业务语言。
class ReportGenerator:@staticmethoddef generate_report(results: dict, distribution_name: str = Unknown) - str:生成人类可读的报告字符串if results[is_significant]:verdict = ⚠️ 警告：数据分布不符合预期模型advice = f建议重新选择分布模型或检查数据异常值。当前卡方值 {results['chi2_stat']:.4f} 超过临界值 {results['critical_value']:.4f}。else:verdict = ✅ 通过：数据分布符合预期模型advice = f在 {results['alpha']:.2f} 显著性水平下，可以认为观测数据来自 {distribution_name} 分布。report = f
==================== 卡方检验报告 ====================
分布模型: {distribution_name}
显著性水平 (Alpha): {results['alpha']}
自由度 (DF): {results['df']}统计量 (Chi-Square): {results['chi2_stat']:.4f}
P 值: {results['p_value']:.6f}
临界值: {results['critical_value']:.4f}结论: {verdict}
建议: {advice}
=====================================================
return report运行与测试：如何验证正确性
代码写完了，怎么证明它是靠谱的？单元测试是工程化的底线。
在 tests/test_chi_square.py 中，我们构造一组已知的数据，验证输出是否符合统计软件（如 SPSS 或 R 语言）的结果。
import unittest
import numpy as np
from src.chi_square_core import ChiSquareValidatorclass TestChiSquare(unittest.TestCase):def test_fit_goodness_known_data(self):测试用例：模拟一个符合正态分布的离散化数据参考数据来自 NIST/SEMATECH e-Handbook of Statistical Methods# 构造观测频数observed = np.array([5, 10, 20, 30, 20, 10, 5])# 构造期望频数（基于正态分布理论值）expected = np.array([5.5, 9.8, 19.6, 29.4, 19.6, 9.8, 5.5])# 7组数据，估计2个参数，df = 7-1-2 = 4df = 4alpha = 0.05validator = ChiSquareValidator(alpha=alpha)result = validator.fit_goodness_test(observed, expected, df)# 断言：P值应该大于0.05，因为数据设计得比较“像”正态分布self.assertGreater(result['p_value'], alpha)self.assertFalse(result['is_significant'])# 验证卡方值计算manual_chi2 = np.sum((observed - expected) ** 2 / expected)self.assertAlmostEqual(result['chi2_stat'], manual_chi2, places=5)if __name__ == '__main__':unittest.main()运行测试：
在终端执行 python -m unittest discover tests。
如果全部通过，说明核心逻辑无误。
实战演示：
在 main.py 中，我们加载一份模拟的“某流域年最大洪峰流量”数据，进行皮尔逊III型分布的拟合优度检验。
# main.py
from src.preprocessor import DataPreprocessor
from src.chi_square_core import ChiSquareValidator
from src.reporter import ReportGenerator
import numpy as npif __name__ == __main__:# 1. 加载数据preprocessor = DataPreprocessor(data/sample_rainfall.csv)data = preprocessor.load_data()observed = preprocessor.prepare_observed(peak_flow)# 2. 模拟期望分布（实际项目中应通过最大似然估计拟合得到）# 这里假设我们已经通过其他方法拟合出了期望频数expected = np.array([12.5, 25.3, 45.1, 30.2, 15.1, 7.5]) df = len(observed) - 1 - 2 # 假设估计了2个参数# 3. 执行检验validator = ChiSquareValidator(alpha=0.05)try:results = validator.fit_goodness_test(observed, expected, df)# 4. 生成报告report = ReportGenerator.generate_report(results, Pearson Type III)print(report)except Exception as e:print(fError: {e})优化扩展与进阶技巧
基础功能跑通后，如何让它更“工程化”？日志记录 (Logging)：
不要只用 print。使用 logging 模块，将检验过程、警告信息（如负值截断）写入文件。水利工程数据审计要求可追溯，日志是证据链的一部分。
import logging
logging.basicConfig(filename='chi_square.log', level=logging.INFO, format='%(asctime)s - %(levelname)s - %(message)s')
logging.warning(fNegative values clipped: {count})可视化集成：
结合 matplotlib，绘制观测值与期望值的对比柱状图，并在图上标注卡方统计量。视觉化能让非技术同事一眼看出哪一组数据偏差最大。支持多种分布：
扩展 ChiSquareValidator，使其能接受分布类型参数（'normal', 'exponential', 'gamma'），内部自动调用对应的 scipy.stats 函数计算期望频数。GitHub 开源仓库参考：
在实现过程中，可以参考 scipy 官方仓库的 tests 目录，学习他们如何构造边界测试用例。此外，GitHub 上的 hydrostats 或 hydroR 等水文专用库，其底层卡方检验的实现方式值得借鉴，特别是它们如何处理小样本修正。小结
这篇避坑指南带你从零搭建了一个稳健的卡方检验模块。我们重点解决了三个问题：API 兼容性：通过锁定依赖版本和使用 sf 函数，避免了 scipy 升级带来的陷阱。
数据陷阱：通过预处理模块，自动处理了负值和缺失值，防止了运行时错误。
工程化规范：通过模块化设计、单元测试和日志记录，确保了代码的可维护性和可审计性。对于水利工程从业者来说，统计检验不是目的，服务于设计决策才是。一个稳健的代码框架，能让你从繁琐的调错中解放出来，专注于数据背后的水文规律。
你在项目里踩过这个坑吗？是遇到了 API 报错，还是 P 值计算偏差？评论区聊聊，我们一起拆解。 卡方检验表避坑指南：3个实战案例教你搞定API变更
卡方检验表避坑指南：3个实战案例教你搞定API变更
版本升级后 API 全变了？别慌，这篇避坑指南专治各种统计库升级导致的“水土不服”。
在水利工程的数据分析里，卡方检验表是检验独立性、拟合优度的核心工具。很多老手都遇到过：项目从 Python 3.8 升到 3.11，或者 scipy 从 1.5 升到 1.12，原本跑得飞快的脚本突然报错 ValueError: Input must be non-negative，或者 P 值计算结果对不上。这不仅是代码问题，更是工程化思维的缺失。
今天不聊虚的，直接从一个真实的“洪水频率分析”项目入手，从零搭建一个稳健的卡方检验模块。我们会深入剖析 scipy.stats.chi2 的底层逻辑，拆解 GitHub 上几个主流开源仓库的陷阱，并给出一套可复现、可维护的代码方案。无论你是刚入门的水利工程师，还是被升级坑过的老兵，这套实战经验都能帮你省下至少半天调错时间。
项目目标与场景拆解
在动手写代码前，必须明确我们要解决什么具体问题。在水利工程中，卡方检验主要应用在两个场景：拟合优度检验：验证观测到的洪水峰值分布是否符合某个理论分布（如皮尔逊III型分布、对数正态分布）。这是水工设计中最常见的应用，直接关系到设计洪水标准的准确性。
独立性检验：分析不同流域、不同季节的降雨量与径流量之间是否存在统计上的显著关联。核心痛点：大多数教程只给一行 chi2_contingency 的代码，但忽略了输入数据的预处理。在实际工程中，原始水文数据往往存在缺失值、负值（如流量低于基流线时的处理误差）或非整数（如经过率化处理的数据）。直接扔给 scipy 就会报错。
项目目标：构建一个封装良好的 ChiSquareValidator 类。
实现自动数据清洗、非负校验、自由度动态计算。
输出标准化的检验报告，包含卡方值、P值、临界值及结论。
确保代码在 scipy 1.7 至 1.12 版本间向后兼容。目录结构与依赖管理
为了保持工程化规范，我们采用模块化的目录结构。不要把所有代码塞在一个 main.py 里，那是新手最容易犯的错。
chi_square_project/
├── requirements.txt # 依赖锁定，防止环境漂移
├── data/
│ └── sample_rainfall.csv # 模拟的水文观测数据
├── src/
│ ├── __init__.py
│ ├── preprocessor.py # 数据清洗与预处理模块
│ ├── chi_square_core.py# 核心检验逻辑
│ └── reporter.py # 报告生成模块
├── tests/
│ └── test_chi_square.py# 单元测试
└── main.py # 入口文件依赖管理关键点：
在 requirements.txt 中，不要只写 scipy。必须锁定大版本，甚至小版本。
numpy=1.21.0,1.25.0
scipy=1.7.0,1.13.0
pandas=1.3.0为什么这样写？因为 numpy 2.0 之后，某些底层数组操作发生了变更，可能导致 scipy 的旧版本出现兼容性问题。锁定范围能避免“在我电脑上能跑，在你电脑上崩”的经典悲剧。
核心代码实现：逐行拆解
这是本文的重点。我们将分三个模块实现，每个模块都针对“API变更”和“数据陷阱”做了防御性编程。
1. 数据预处理模块 (preprocessor.py)
很多报错源于数据本身。scipy.stats.chi2 要求输入必须是非负实数。在水利工程中，经过对数变换或标准化后的数据可能出现负值，必须处理。
import numpy as np
import pandas as pdclass DataPreprocessor:def __init__(self, data_path: str):self.data_path = data_pathself.data = Nonedef load_data(self) - pd.DataFrame:加载CSV数据，自动处理缺失值try:self.data = pd.read_csv(self.data_path)# 水利工程数据常见NaN，这里用中位数填充，比均值更鲁棒self.data.fillna(self.data.median(), inplace=True)return self.dataexcept FileNotFoundError:raise FileNotFoundError(fData file {self.data_path} not found)def prepare_observed(self, column_name: str) - np.ndarray:提取观测值并转换为非负数组核心逻辑：如果数据为负，说明参考基准线选取有误，需重新校准if column_name not in self.data.columns:raise ValueError(fColumn {column_name} does not exist)values = self.data[column_name].valuesif np.any(values 0):# 简单处理：将负值视为0，但在实际工程中应警告用户print(fWarning: Detected {np.sum(values 0)} negative values. Clipping to 0.)values = np.clip(values, 0, None)return values.astype(float)避坑点：np.clip 的使用。直接删除负值会导致样本量变化，影响自由度计算。将其置为0是统计学上的一种保守处理，具体策略需根据水文特性决定。
2. 核心检验模块 (chi_square_core.py)
这里涉及 scipy 的 API 变更。旧版本中，chi2.cdf 和 chi2.ppf 的参数顺序在不同版本间有过细微调整（主要是尾概率 upper_tail 的处理）。我们采用最稳定的 chi2.sf (Survival Function，即 1 - CDF) 来计算 P 值，因为它在尾部计算上比 1 - cdf 数值精度更高。
from scipy import stats
import numpy as npclass ChiSquareValidator:def __init__(self, alpha: float = 0.05):self.alpha = alphadef fit_goodness_test(self, observed: np.ndarray, expected: np.ndarray, df: int) - dict:执行拟合优度检验:param observed: 观测频数数组:param expected: 期望频数数组:param df: 自由度:return: 包含检验结果的字典# 校验：观测值和期望值长度必须一致if len(observed) != len(expected):raise ValueError(Observed and expected arrays must have the same length)# 校验：期望频数不能为0，否则卡方公式分母为0if np.any(expected == 0):raise ValueError(Expected frequencies cannot be zero)# 计算卡方统计量: sum((O-E)^2 / E)# 使用 np.sum 而非 sum，确保处理的是数组chi2_stat = np.sum((observed - expected) ** 2 / expected)# 计算 P 值# 注意：scipy.stats.chi2.sf 返回的是 P(X x)，即右尾概率# 这正是我们需要的 P 值p_value = stats.chi2.sf(chi2_stat, df)# 获取临界值critical_value = stats.chi2.ppf(1 - self.alpha, df)# 结论判断is_significant = p_value self.alphareturn {chi2_stat: float(chi2_stat),p_value: float(p_value),critical_value: float(critical_value),df: df,alpha: self.alpha,is_significant: bool(is_significant),conclusion: Reject H0: Data does not fit distribution if is_significant else Fail to reject H0: Data fits distribution}def independence_test(self, observed_matrix: np.ndarray) - dict:执行独立性检验（列联表）使用 scipy.stats.chi2_contingency# 检查输入是否为2D数组if observed_matrix.ndim != 2:raise ValueError(Input must be a 2D array for independence test)# chi2_contingency 返回 (chi2, p, dof, expected_freq)chi2, p, dof, expected_freq = stats.chi2_contingency(observed_matrix)return {chi2_stat: float(chi2),p_value: float(p),df: int(dof),expected_freq: expected_freq,is_significant: bool(p self.alpha)}深度解析：为什么用 sf 而不是 1-cdf？ 当卡方值很大时，P 值极小（如 1e-10），1 - cdf 会因为浮点数精度损失变成 0，而 sf 能保留有效数字。这是数值计算的经典避坑点。
自由度 df 的计算：在拟合优度中，df = k - 1 - m，其中 k 是组数，m 是估计参数的个数。比如用皮尔逊III型分布，估计了均值和偏度两个参数，若分5组，df = 5 - 1 - 2 = 2。很多初学者直接写死 df=k-1，导致 P 值错误。3. 报告生成模块 (reporter.py)
水利工程从业者需要向非技术领导汇报。纯数字没有意义，需要转化为业务语言。
class ReportGenerator:@staticmethoddef generate_report(results: dict, distribution_name: str = Unknown) - str:生成人类可读的报告字符串if results[is_significant]:verdict = ⚠️ 警告：数据分布不符合预期模型advice = f建议重新选择分布模型或检查数据异常值。当前卡方值 {results['chi2_stat']:.4f} 超过临界值 {results['critical_value']:.4f}。else:verdict = ✅ 通过：数据分布符合预期模型advice = f在 {results['alpha']:.2f} 显著性水平下，可以认为观测数据来自 {distribution_name} 分布。report = f
==================== 卡方检验报告 ====================
分布模型: {distribution_name}
显著性水平 (Alpha): {results['alpha']}
自由度 (DF): {results['df']}统计量 (Chi-Square): {results['chi2_stat']:.4f}
P 值: {results['p_value']:.6f}
临界值: {results['critical_value']:.4f}结论: {verdict}
建议: {advice}
=====================================================
return report运行与测试：如何验证正确性
代码写完了，怎么证明它是靠谱的？单元测试是工程化的底线。
在 tests/test_chi_square.py 中，我们构造一组已知的数据，验证输出是否符合统计软件（如 SPSS 或 R 语言）的结果。
import unittest
import numpy as np
from src.chi_square_core import ChiSquareValidatorclass TestChiSquare(unittest.TestCase):def test_fit_goodness_known_data(self):测试用例：模拟一个符合正态分布的离散化数据参考数据来自 NIST/SEMATECH e-Handbook of Statistical Methods# 构造观测频数observed = np.array([5, 10, 20, 30, 20, 10, 5])# 构造期望频数（基于正态分布理论值）expected = np.array([5.5, 9.8, 19.6, 29.4, 19.6, 9.8, 5.5])# 7组数据，估计2个参数，df = 7-1-2 = 4df = 4alpha = 0.05validator = ChiSquareValidator(alpha=alpha)result = validator.fit_goodness_test(observed, expected, df)# 断言：P值应该大于0.05，因为数据设计得比较“像”正态分布self.assertGreater(result['p_value'], alpha)self.assertFalse(result['is_significant'])# 验证卡方值计算manual_chi2 = np.sum((observed - expected) ** 2 / expected)self.assertAlmostEqual(result['chi2_stat'], manual_chi2, places=5)if __name__ == '__main__':unittest.main()运行测试：
在终端执行 python -m unittest discover tests。
如果全部通过，说明核心逻辑无误。
实战演示：
在 main.py 中，我们加载一份模拟的“某流域年最大洪峰流量”数据，进行皮尔逊III型分布的拟合优度检验。
# main.py
from src.preprocessor import DataPreprocessor
from src.chi_square_core import ChiSquareValidator
from src.reporter import ReportGenerator
import numpy as npif __name__ == __main__:# 1. 加载数据preprocessor = DataPreprocessor(data/sample_rainfall.csv)data = preprocessor.load_data()observed = preprocessor.prepare_observed(peak_flow)# 2. 模拟期望分布（实际项目中应通过最大似然估计拟合得到）# 这里假设我们已经通过其他方法拟合出了期望频数expected = np.array([12.5, 25.3, 45.1, 30.2, 15.1, 7.5]) df = len(observed) - 1 - 2 # 假设估计了2个参数# 3. 执行检验validator = ChiSquareValidator(alpha=0.05)try:results = validator.fit_goodness_test(observed, expected, df)# 4. 生成报告report = ReportGenerator.generate_report(results, Pearson Type III)print(report)except Exception as e:print(fError: {e})优化扩展与进阶技巧
基础功能跑通后，如何让它更“工程化”？日志记录 (Logging)：
不要只用 print。使用 logging 模块，将检验过程、警告信息（如负值截断）写入文件。水利工程数据审计要求可追溯，日志是证据链的一部分。
import logging
logging.basicConfig(filename='chi_square.log', level=logging.INFO, format='%(asctime)s - %(levelname)s - %(message)s')
logging.warning(fNegative values clipped: {count})可视化集成：
结合 matplotlib，绘制观测值与期望值的对比柱状图，并在图上标注卡方统计量。视觉化能让非技术同事一眼看出哪一组数据偏差最大。支持多种分布：
扩展 ChiSquareValidator，使其能接受分布类型参数（'normal', 'exponential', 'gamma'），内部自动调用对应的 scipy.stats 函数计算期望频数。GitHub 开源仓库参考：
在实现过程中，可以参考 scipy 官方仓库的 tests 目录，学习他们如何构造边界测试用例。此外，GitHub 上的 hydrostats 或 hydroR 等水文专用库，其底层卡方检验的实现方式值得借鉴，特别是它们如何处理小样本修正。小结
这篇避坑指南带你从零搭建了一个稳健的卡方检验模块。我们重点解决了三个问题：API 兼容性：通过锁定依赖版本和使用 sf 函数，避免了 scipy 升级带来的陷阱。
数据陷阱：通过预处理模块，自动处理了负值和缺失值，防止了运行时错误。
工程化规范：通过模块化设计、单元测试和日志记录，确保了代码的可维护性和可审计性。对于水利工程从业者来说，统计检验不是目的，服务于设计决策才是。一个稳健的代码框架，能让你从繁琐的调错中解放出来，专注于数据背后的水文规律。
你在项目里踩过这个坑吗？是遇到了 API 报错，还是 P 值计算偏差？评论区聊聊，我们一起拆解。