案例教你搞定API變更)
卡方檢驗表避坑指南：3個實戰(zhàn)案例教你搞定API變更
版本升級后 API 全變了？別慌，這篇避坑指南專治各種統(tǒng)計庫升級導致的“水土不服”。
在水利工程的數據分析里，卡方檢驗表是檢驗獨立性、擬合優(yōu)度的核心工具。很多老手都遇到過：項目從 Python 3.8 升到 3.11，或者 scipy 從 1.5 升到 1.12，原本跑得飛快的腳本突然報錯 ValueError: Input must be non-negative，或者 P 值計算結果對不上。這不僅是代碼問題，更是工程化思維的缺失。
今天不聊虛的，直接從一個真實的“洪水頻率分析”項目入手，從零搭建一個穩(wěn)健的卡方檢驗模塊。我們會深入剖析 scipy.stats.chi2 的底層邏輯，拆解 GitHub 上幾個主流開源倉庫的陷阱，并給出一套可復現、可維護的代碼方案。無論你是剛入門的水利工程師，還是被升級坑過的老兵，這套實戰(zhàn)經驗都能幫你省下至少半天調錯時間。
項目目標與場景拆解
在動手寫代碼前，必須明確我們要解決什么具體問題。在水利工程中，卡方檢驗主要應用在兩個場景：擬合優(yōu)度檢驗：驗證觀測到的洪水峰值分布是否符合某個理論分布（如皮爾遜III型分布、對數正態(tài)分布）。這是水工設計中最常見的應用，直接關系到設計洪水標準的準確性。
獨立性檢驗：分析不同流域、不同季節(jié)的降雨量與徑流量之間是否存在統(tǒng)計上的顯著關聯。核心痛點：大多數教程只給一行 chi2_contingency 的代碼，但忽略了輸入數據的預處理。在實際工程中，原始水文數據往往存在缺失值、負值（如流量低于基流線時的處理誤差）或非整數（如經過率化處理的數據）。直接扔給 scipy 就會報錯。
項目目標：構建一個封裝良好的 ChiSquareValidator 類。
實現自動數據清洗、非負校驗、自由度動態(tài)計算。
輸出標準化的檢驗報告，包含卡方值、P值、臨界值及結論。
確保代碼在 scipy 1.7 至 1.12 版本間向后兼容。目錄結構與依賴管理
為了保持工程化規(guī)范，我們采用模塊化的目錄結構。不要把所有代碼塞在一個 main.py 里，那是新手最容易犯的錯。
chi_square_project/
├── requirements.txt # 依賴鎖定，防止環(huán)境漂移
├── 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 之后，某些底層數組操作發(fā)生了變更，可能導致 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是統(tǒng)計學上的一種保守處理，具體策略需根據水文特性決定。
2. 核心檢驗模塊 (chi_square_core.py)
這里涉及 scipy 的 API 變更。舊版本中，chi2.cdf 和 chi2.ppf 的參數順序在不同版本間有過細微調整（主要是尾概率 upper_tail 的處理）。我們采用最穩(wěn)定的 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:執(zhí)行擬合優(yōu)度檢驗: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)# 計算卡方統(tǒng)計量: 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:執(zhí)行獨立性檢驗（列聯表）使用 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 的計算：在擬合優(yōu)度中，df = k - 1 - m，其中 k 是組數，m 是估計參數的個數。比如用皮爾遜III型分布，估計了均值和偏度兩個參數，若分5組，df = 5 - 1 - 2 = 2。很多初學者直接寫死 df=k-1，導致 P 值錯誤。3. 報告生成模塊 (reporter.py)
水利工程從業(yè)者需要向非技術領導匯報。純數字沒有意義，需要轉化為業(yè)務語言。
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']}統(tǒng)計量 (Chi-Square): {results['chi2_stat']:.4f}
P 值: {results['p_value']:.6f}
臨界值: {results['critical_value']:.4f}結論: {verdict}
建議: {advice}
=====================================================
return report運行與測試：如何驗證正確性
代碼寫完了，怎么證明它是靠譜的？單元測試是工程化的底線。
在 tests/test_chi_square.py 中，我們構造一組已知的數據，驗證輸出是否符合統(tǒng)計軟件（如 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):測試用例：模擬一個符合正態(tài)分布的離散化數據參考數據來自 NIST/SEMATECH e-Handbook of Statistical Methods# 構造觀測頻數observed = np.array([5, 10, 20, 30, 20, 10, 5])# 構造期望頻數（基于正態(tài)分布理論值）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，因為數據設計得比較“像”正態(tài)分布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()運行測試：
在終端執(zhí)行 python -m unittest discover tests。
如果全部通過，說明核心邏輯無誤。
實戰(zhàn)演示：
在 main.py 中，我們加載一份模擬的“某流域年最大洪峰流量”數據，進行皮爾遜III型分布的擬合優(yōu)度檢驗。
# 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. 執(zhí)行檢驗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})優(yōu)化擴展與進階技巧
基礎功能跑通后，如何讓它更“工程化”？日志記錄 (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，繪制觀測值與期望值的對比柱狀圖，并在圖上標注卡方統(tǒng)計量。視覺化能讓非技術同事一眼看出哪一組數據偏差最大。支持多種分布：
擴展 ChiSquareValidator，使其能接受分布類型參數（'normal', 'exponential', 'gamma'），內部自動調用對應的 scipy.stats 函數計算期望頻數。GitHub 開源倉庫參考：
在實現過程中，可以參考 scipy 官方倉庫的 tests 目錄，學習他們如何構造邊界測試用例。此外，GitHub 上的 hydrostats 或 hydroR 等水文專用庫，其底層卡方檢驗的實現方式值得借鑒，特別是它們如何處理小樣本修正。小結
這篇避坑指南帶你從零搭建了一個穩(wěn)健的卡方檢驗模塊。我們重點解決了三個問題：API 兼容性：通過鎖定依賴版本和使用 sf 函數，避免了 scipy 升級帶來的陷阱。
數據陷阱：通過預處理模塊，自動處理了負值和缺失值，防止了運行時錯誤。
工程化規(guī)范：通過模塊化設計、單元測試和日志記錄，確保了代碼的可維護性和可審計性。對于水利工程從業(yè)者來說，統(tǒng)計檢驗不是目的，服務于設計決策才是。一個穩(wěn)健的代碼框架，能讓你從繁瑣的調錯中解放出來，專注于數據背后的水文規(guī)律。
你在項目里踩過這個坑嗎？是遇到了 API 報錯，還是 P 值計算偏差？評論區(qū)聊聊，我們一起拆解。 卡方檢驗表避坑指南：3個實戰(zhàn)案例教你搞定API變更
卡方檢驗表避坑指南：3個實戰(zhàn)案例教你搞定API變更
版本升級后 API 全變了？別慌，這篇避坑指南專治各種統(tǒng)計庫升級導致的“水土不服”。
在水利工程的數據分析里，卡方檢驗表是檢驗獨立性、擬合優(yōu)度的核心工具。很多老手都遇到過：項目從 Python 3.8 升到 3.11，或者 scipy 從 1.5 升到 1.12，原本跑得飛快的腳本突然報錯 ValueError: Input must be non-negative，或者 P 值計算結果對不上。這不僅是代碼問題，更是工程化思維的缺失。
今天不聊虛的，直接從一個真實的“洪水頻率分析”項目入手，從零搭建一個穩(wěn)健的卡方檢驗模塊。我們會深入剖析 scipy.stats.chi2 的底層邏輯，拆解 GitHub 上幾個主流開源倉庫的陷阱，并給出一套可復現、可維護的代碼方案。無論你是剛入門的水利工程師，還是被升級坑過的老兵，這套實戰(zhàn)經驗都能幫你省下至少半天調錯時間。
項目目標與場景拆解
在動手寫代碼前，必須明確我們要解決什么具體問題。在水利工程中，卡方檢驗主要應用在兩個場景：擬合優(yōu)度檢驗：驗證觀測到的洪水峰值分布是否符合某個理論分布（如皮爾遜III型分布、對數正態(tài)分布）。這是水工設計中最常見的應用，直接關系到設計洪水標準的準確性。
獨立性檢驗：分析不同流域、不同季節(jié)的降雨量與徑流量之間是否存在統(tǒng)計上的顯著關聯。核心痛點：大多數教程只給一行 chi2_contingency 的代碼，但忽略了輸入數據的預處理。在實際工程中，原始水文數據往往存在缺失值、負值（如流量低于基流線時的處理誤差）或非整數（如經過率化處理的數據）。直接扔給 scipy 就會報錯。
項目目標：構建一個封裝良好的 ChiSquareValidator 類。
實現自動數據清洗、非負校驗、自由度動態(tài)計算。
輸出標準化的檢驗報告，包含卡方值、P值、臨界值及結論。
確保代碼在 scipy 1.7 至 1.12 版本間向后兼容。目錄結構與依賴管理
為了保持工程化規(guī)范，我們采用模塊化的目錄結構。不要把所有代碼塞在一個 main.py 里，那是新手最容易犯的錯。
chi_square_project/
├── requirements.txt # 依賴鎖定，防止環(huán)境漂移
├── 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 之后，某些底層數組操作發(fā)生了變更，可能導致 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是統(tǒng)計學上的一種保守處理，具體策略需根據水文特性決定。
2. 核心檢驗模塊 (chi_square_core.py)
這里涉及 scipy 的 API 變更。舊版本中，chi2.cdf 和 chi2.ppf 的參數順序在不同版本間有過細微調整（主要是尾概率 upper_tail 的處理）。我們采用最穩(wěn)定的 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:執(zhí)行擬合優(yōu)度檢驗: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)# 計算卡方統(tǒng)計量: 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:執(zhí)行獨立性檢驗（列聯表）使用 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 的計算：在擬合優(yōu)度中，df = k - 1 - m，其中 k 是組數，m 是估計參數的個數。比如用皮爾遜III型分布，估計了均值和偏度兩個參數，若分5組，df = 5 - 1 - 2 = 2。很多初學者直接寫死 df=k-1，導致 P 值錯誤。3. 報告生成模塊 (reporter.py)
水利工程從業(yè)者需要向非技術領導匯報。純數字沒有意義，需要轉化為業(yè)務語言。
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']}統(tǒng)計量 (Chi-Square): {results['chi2_stat']:.4f}
P 值: {results['p_value']:.6f}
臨界值: {results['critical_value']:.4f}結論: {verdict}
建議: {advice}
=====================================================
return report運行與測試：如何驗證正確性
代碼寫完了，怎么證明它是靠譜的？單元測試是工程化的底線。
在 tests/test_chi_square.py 中，我們構造一組已知的數據，驗證輸出是否符合統(tǒng)計軟件（如 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):測試用例：模擬一個符合正態(tài)分布的離散化數據參考數據來自 NIST/SEMATECH e-Handbook of Statistical Methods# 構造觀測頻數observed = np.array([5, 10, 20, 30, 20, 10, 5])# 構造期望頻數（基于正態(tài)分布理論值）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，因為數據設計得比較“像”正態(tài)分布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()運行測試：
在終端執(zhí)行 python -m unittest discover tests。
如果全部通過，說明核心邏輯無誤。
實戰(zhàn)演示：
在 main.py 中，我們加載一份模擬的“某流域年最大洪峰流量”數據，進行皮爾遜III型分布的擬合優(yōu)度檢驗。
# 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. 執(zhí)行檢驗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})優(yōu)化擴展與進階技巧
基礎功能跑通后，如何讓它更“工程化”？日志記錄 (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，繪制觀測值與期望值的對比柱狀圖，并在圖上標注卡方統(tǒng)計量。視覺化能讓非技術同事一眼看出哪一組數據偏差最大。支持多種分布：
擴展 ChiSquareValidator，使其能接受分布類型參數（'normal', 'exponential', 'gamma'），內部自動調用對應的 scipy.stats 函數計算期望頻數。GitHub 開源倉庫參考：
在實現過程中，可以參考 scipy 官方倉庫的 tests 目錄，學習他們如何構造邊界測試用例。此外，GitHub 上的 hydrostats 或 hydroR 等水文專用庫，其底層卡方檢驗的實現方式值得借鑒，特別是它們如何處理小樣本修正。小結
這篇避坑指南帶你從零搭建了一個穩(wěn)健的卡方檢驗模塊。我們重點解決了三個問題：API 兼容性：通過鎖定依賴版本和使用 sf 函數，避免了 scipy 升級帶來的陷阱。
數據陷阱：通過預處理模塊，自動處理了負值和缺失值，防止了運行時錯誤。
工程化規(guī)范：通過模塊化設計、單元測試和日志記錄，確保了代碼的可維護性和可審計性。對于水利工程從業(yè)者來說，統(tǒng)計檢驗不是目的，服務于設計決策才是。一個穩(wěn)健的代碼框架，能讓你從繁瑣的調錯中解放出來，專注于數據背后的水文規(guī)律。
你在項目里踩過這個坑嗎？是遇到了 API 報錯，還是 P 值計算偏差？評論區(qū)聊聊，我們一起拆解。