Metadata-Version: 2.4
Name: genetics1003
Version: 2.1.0
Summary: Chi-Square Calculator for Genetics and Statistics (Goodness-of-Fit, Contingency Tables, Hardy-Weinberg)
Author-email: wangblog0 <your-email@example.com>
License: MIT
Project-URL: Homepage, https://github.com/wangblog0/chi_square
Project-URL: Repository, https://github.com/wangblog0/chi_square
Project-URL: Issues, https://github.com/wangblog0/chi_square/issues
Keywords: chi-square,statistics,genetics,hardy-weinberg,contingency-table,goodness-of-fit
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Education
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Classifier: Topic :: Scientific/Engineering :: Mathematics
Classifier: Topic :: Education
Requires-Python: >=3.7
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# Genetics1003: Chi-Square Calculator

一个功能完整的Python卡方检验计算器，支持：

1. **拟合优度检验** (Goodness-of-fit test)
2. **列联表独立性检验** (Contingency table test)
   - 2×2列联表（支持Yates连续性校正）
   - 2×3列联表
   - R×C列联表（任意行列数）
3. **哈温平衡检验** (Hardy-Weinberg Equilibrium test)

## 功能特点

### 拟合优度检验

- ✅ 计算卡方统计量
- ✅ 计算自由度
- ✅ 计算p值（使用Wilson-Hilferty近似）
- ✅ 支持等比例期望分布
- ✅ 支持自定义期望频数
- ✅ 支持自定义期望比例
- ✅ 数据输入验证
- ✅ 支持零期望频数的特殊处理

### 列联表检验

- ✅ 支持2×2、2×3及任意R×C列联表
- ✅ 标准卡方检验
- ✅ Yates连续性校正（仅适用于2×2表）
- ✅ 自动判断是否需要校正（当期望频数<5时）
- ✅ 支持手动强制使用或禁用校正
- ✅ 计算边际总计
- ✅ 计算期望频数
- ✅ 显示观察频数与期望频数对比

### 哈温平衡检验

- ✅ 自动计算等位基因频率
- ✅ 计算期望基因型频率
- ✅ 卡方检验判断是否符合哈温平衡
- ✅ 显示观察基因型与期望基因型对比
- ✅ 显示等位基因频率和基因型频率

## 安装要求

- Python 3.6+
- 无额外依赖（仅使用标准库）

## 使用方法

### 1. 运行示例

```bash
python genetics1003.py
```

这将运行多个预设的示例，包括拟合优度检验、列联表检验和哈温平衡检验。

### 2. 命令行参数

#### 拟合优度检验 - 等比例期望分布

```bash
python genetics1003.py -o 10 15 20 25
```

#### 拟合优度检验 - 指定期望频数

```bash
python genetics1003.py -o 10 15 20 25 -e 12 14 18 26
```

#### 拟合优度检验 - 指定期望比例

```bash
python genetics1003.py -o 45 55 -p 0.5 0.5
```

#### 2×2列联表检验

```bash
# 输入格式：按行输入所有值
python genetics1003.py -t 20 10 5 15
# 自动识别为2×2表：[[20, 10], [5, 15]]
```

#### 2×2列联表检验 - 使用Yates校正

```bash
# 不带--yates参数：自动判断（期望频数<5时自动使用校正）
python genetics1003.py -t 4 20 20 99
# 输出会显示：(with Yates' continuity correction)

# 带--yates参数：强制使用校正（无论期望频数大小）
python genetics1003.py -t 20 10 5 15 --yates

# 带--no-auto-yates参数：禁用自动校正（即使期望频数<5）
python genetics1003.py -t 4 20 20 99 --no-auto-yates
# 输出不会显示：(with Yates' continuity correction)
```

**Yates校正的使用规则：**

1. **默认行为（不带任何参数）**：
   - 程序会自动检测所有单元格的期望频数
   - 如果**任何一个**期望频数 < 5，自动使用Yates连续性校正
   - 如果所有期望频数 ≥ 5，不使用校正

2. **强制使用校正（`--yates`）**：
   - 无论期望频数大小，强制使用Yates校正

3. **禁用自动校正（`--no-auto-yates`）**：
   - 即使期望频数 < 5，也不使用Yates校正
   - 使用标准卡方检验

**注意**：`--yates` 和 `--no-auto-yates` 不能同时使用

#### 2×3列联表检验

```bash
# 输入格式：按行输入所有6个值，然后指定行数和列数
python genetics1003.py -t 20 10 15 5 8 12 --rows 2 --cols 3
# 表格结构：
# [[20, 10, 15],
#  [5,  8,  12]]
```

#### 3×3列联表检验

```bash
python genetics1003.py -t 10 15 20 5 8 12 7 9 14 --rows 3 --cols 3
# 表格结构：
# [[10, 15, 20],
#  [5,  8,  12],
#  [7,  9,  14]]
```

#### 哈温平衡检验

```bash
# 提供三种基因型的计数（AA Aa aa）
python genetics1003.py --hw 50 40 10
```

#### 自定义显著性水平

```bash
python genetics1003.py -o 20 30 25 15 -a 0.01
```

### 3. 参数说明

#### 通用参数

- `-a, --alpha`: 显著性水平（可选，默认0.05）

#### 拟合优度检验参数

- `-o, --observed`: 观察频数（必需）
- `-e, --expected`: 期望频数（可选）
- `-p, --proportions`: 期望比例（可选，必须和为1.0）

#### 列联表检验参数

- `-t, --table`: 列联表的所有值，按行输入（必需）
- `--rows`: 表格行数（可选，2×2表会自动识别）
- `--cols`: 表格列数（可选，2×2表会自动识别）
- `--yates`: 强制使用Yates连续性校正（仅适用2×2表）
- `--no-auto-yates`: 禁用自动Yates校正，即使期望频数<5也不使用校正（仅适用2×2表）

**重要说明**：
- 对于2×2表（4个值），如果不指定`--rows`和`--cols`，程序会自动识别为2×2表
- 对于其他尺寸的表格，必须同时指定`--rows`和`--cols`参数
- 输入值按行的顺序输入，如2×3表：row1_col1 row1_col2 row1_col3 row2_col1 row2_col2 row2_col3

#### 哈温平衡检验参数

- `--hw, --hardy-weinberg`: 三种基因型的计数（必需，格式：AA Aa aa）

## 输出解释

### 拟合优度检验输出

计算器会输出：

- 卡方统计量
- 自由度
- p值
- 显著性水平
- 检验结论（拒绝或接受原假设）
- 观察频数与期望频数对比表

### 列联表检验输出

计算器会输出：

- 表格维度（如2×2、2×3等）
- 卡方统计量
- 是否使用Yates校正（仅2×2表）
- 自由度
- p值
- 显著性水平
- 检验结论（变量是否相关）
- 观察频数表（含行列边际总计）
- 期望频数表

### 哈温平衡检验输出

计算器会输出：

- 卡方统计量
- 自由度（双等位基因系统固定为1）
- p值
- 显著性水平
- 检验结论（是否符合哈温平衡）
- 等位基因频率（p和q）
- 观察基因型频率与期望基因型频率对比表
- 理论哈温平衡比例（p²:2pq:q²）

## 数学原理

### 拟合优度检验

#### 卡方统计量计算

χ² = Σ[(观察频数 - 期望频数)² / 期望频数]

#### 自由度计算

df = 类别数 - 1

### 列联表检验

#### R×C列联表格式

对于R行C列的列联表：

```
        列1    列2    列3   ...  列C
行1     n11    n12    n13   ...  n1C
行2     n21    n22    n23   ...  n2C
...     ...    ...    ...   ...  ...
行R     nR1    nR2    nR3   ...  nRC
```

#### 期望频数计算

E_ij = (行i总计 × 列j总计) / 总计

#### 卡方统计量计算

χ² = ΣΣ[(O_ij - E_ij)² / E_ij]

对所有行i和列j求和

#### 自由度

df = (行数 - 1) × (列数 - 1)

例如：
- 2×2表：df = (2-1) × (2-1) = 1
- 2×3表：df = (2-1) × (3-1) = 2
- 3×3表：df = (3-1) × (3-1) = 4

#### Yates连续性校正（仅适用于2×2表）

当期望频数 < 5 时建议使用：

χ² = Σ[(|O_ij - E_ij| - 0.5)² / E_ij]

### 哈温平衡检验

#### 等位基因频率计算

对于双等位基因系统（A和a），根据观察的基因型计数：

- p（等位基因A的频率）= (2×AA + Aa) / (2×总数)
- q（等位基因a的频率）= (2×aa + Aa) / (2×总数)

其中 p + q = 1

#### 期望基因型频率（哈温平衡下）

在哈温平衡状态下，基因型频率应该满足：

- AA的频率 = p²
- Aa的频率 = 2pq
- aa的频率 = q²

其中 p² + 2pq + q² = 1

#### 期望基因型计数

期望计数 = 期望频率 × 总数

- 期望AA数 = p² × N
- 期望Aa数 = 2pq × N
- 期望aa数 = q² × N

#### 卡方统计量计算

χ² = Σ[(观察基因型数 - 期望基因型数)² / 期望基因型数]

#### 自由度

df = 基因型数 - 等位基因数 = 3 - 2 = 1

### p值计算

使用Wilson-Hilferty近似方法将卡方分布转换为正态分布进行计算。

## 示例输出

### 拟合优度检验示例

```text
============================================================
CHI-SQUARE GOODNESS-OF-FIT TEST RESULTS
============================================================
Chi-square statistic: 4.6000
Degrees of freedom: 5
P-value: 0.467802
Significance level (α): 0.05
Conclusion: Fail to reject H0

Observed vs Expected Frequencies:
----------------------------------------
Category        Observed        Expected        Difference
----------------------------------------
1               8               10.00           -2.00
2               12              10.00           2.00
3               10              10.00           0.00
4               15              10.00           5.00
5               7               10.00           -3.00
6               8               10.00           -2.00
============================================================
```

### 2×2列联表检验示例

```text
============================================================
CHI-SQUARE TEST FOR 2×2 CONTINGENCY TABLE
============================================================
Chi-square statistic: 18.1818
  (with Yates' continuity correction)
Degrees of freedom: 1
P-value: 0.000020
Significance level (α): 0.05
Conclusion: Reject H0 (variables are associated)

Observed Frequencies:
----------------------------------------
          Column 1    Column 2    Total
Row 1           60          40      100
Row 2           30          70      100
Total           90         110      200

Expected Frequencies:
----------------------------------------
          Column 1    Column 2
Row 1        45.00       55.00
Row 2        45.00       55.00
============================================================
```

### 2×3列联表检验示例

```text
============================================================
CHI-SQUARE TEST FOR 2×3 CONTINGENCY TABLE
============================================================
Chi-square statistic: 5.8447
Degrees of freedom: 2
P-value: 0.053876
Significance level (α): 0.05
Conclusion: Fail to reject H0 (variables are independent)

Observed Frequencies:
------------------------------------------------------------
          Col  1    Col  2    Col  3    Total
Row  1         20        10        15       45
Row  2          5         8        12       25
Total          25        18        27       70

Expected Frequencies:
------------------------------------------------------------
          Col  1    Col  2    Col  3    
Row  1      16.07     11.57     17.36    
Row  2       8.93      6.43      9.64    
============================================================
```

### 哈温平衡检验示例

```text
============================================================
HARDY-WEINBERG EQUILIBRIUM TEST
============================================================
Chi-square statistic: 0.0000
Degrees of freedom: 1
P-value: 1.000000
Significance level (α): 0.05
Conclusion: Fail to reject H0 (in Hardy-Weinberg equilibrium)

Allele Frequencies:
----------------------------------------
Frequency of A allele (p): 0.6000
Frequency of a allele (q): 0.4000
p + q = 1.0000

Genotype Frequencies:
----------------------------------------
Genotype    Observed    Expected    Difference
----------------------------------------
AA                36       36.00         0.00
Aa                48       48.00         0.00
aa                16       16.00         0.00
----------------------------------------
Total            100      100.00

Expected Hardy-Weinberg Proportions:
  AA (p^2):  0.3600
  Aa (2pq):  0.4800
  aa (q^2):  0.1600
============================================================
```

## 注意事项

### 拟合优度检验

1. 所有频数必须为非负数
2. 期望比例必须和为1.0
3. **期望频数可以为零，但有特殊处理：**
   - 如果期望频数为0且观察频数也为0：对卡方统计量的贡献为0
   - 如果期望频数为0但观察频数不为0：卡方统计量为正无穷（拒绝原假设）
4. 观察频数和期望频数（或比例）的长度必须相同

### 列联表检验

1. 所有频数必须为非负数
2. 表格必须至少有2行2列
3. **Yates校正的自动判断机制（仅适用2×2表）：**
   - 程序会自动计算所有单元格的期望频数
   - 当**任何一个**期望频数 < 5时，**自动使用**Yates校正
   - 当所有期望频数 ≥ 5时，不使用校正
   - 使用 `--yates` 参数可以强制使用校正（无论期望频数大小）
   - 使用 `--no-auto-yates` 参数可以禁用自动校正（即使期望频数<5）
   - 输出会明确显示是否使用了校正："(with Yates' continuity correction)"
4. 总计不能为0
5. **R×C表注意事项：**
   - 对于大于2×2的表格，不支持Yates校正
   - 建议每个单元格的期望频数 ≥ 5
   - 如果期望频数过小，考虑合并相邻类别

### 哈温平衡检验

1. 必须提供恰好3种基因型的计数（AA, Aa, aa）
2. 所有计数必须为非负数
3. 总计数不能为0
4. 适用于双等位基因系统
5. **假设条件：**
   - 种群足够大（无遗传漂变）
   - 随机交配
   - 无突变
   - 无迁入迁出
   - 无自然选择
6. 如果拒绝哈温平衡假设，可能原因包括：
   - 非随机交配（近亲繁殖或异型交配）
   - 自然选择作用
   - 种群分层
   - 基因型判定错误
   - 样本量过小

## 应用场景

### 拟合优度检验应用

- 遗传学：检验观察比例是否符合理论比例
- 质量控制：检验产品缺陷率是否符合标准
- 市场调研：检验消费者偏好是否符合预期分布
- 教育评估：检验考试成绩分布是否符合正态分布
- 骰子/硬币公平性检验

### 列联表检验应用

**2×2列联表：**
- 医学研究：检验治疗效果与疾病结果的关联性
- 社会学：检验性别与偏好的独立性
- 流行病学：检验暴露因素与疾病的关联
- A/B测试：检验不同版本与转化率的关联

**2×3列联表：**
- 医学研究：检验三种治疗方案与疾病结果（治愈/未治愈）的关联
- 市场调研：检验产品类型（三种）与客户满意度（满意/不满意）的关系
- 教育研究：检验教学方法（三种）与学生成绩（及格/不及格）的关联
- 遗传学：检验基因型（三种）与表型（两种）的关联

**R×C列联表（一般情况）：**
- 社会调查：检验年龄组与职业类别的关联性
- 生物学：检验物种类型与栖息地类型的关联
- 教育评估：检验专业与就业行业的关联
- 市场分析：检验地区与产品偏好的关联

### 哈温平衡检验应用

- 群体遗传学：检验种群是否处于遗传平衡状态
- 疾病基因研究：检验疾病相关基因型频率分布
- 进化生物学：检测选择压力或非随机交配
- 法医学：验证基因型频率数据库的可靠性
- 育种学：评估种群遗传结构
- 人类遗传学：检测种群分层或近亲繁殖
- 保护生物学：评估濒危物种的遗传多样性

## 更新日志

### v2.1 (2025-12-02)
- ✨ 新增 `--no-auto-yates` 参数，可手动禁用自动Yates校正功能
- 🐛 修复2×2表不带参数时无法自动使用Yates校正的bug
- 📝 完善Yates校正使用规则的文档说明
- 🔧 优化2×2表的校正逻辑判断

### v2.0 (2025-12-02)
- ✨ 新增支持2×3及任意R×C列联表卡方检验
- ✨ 改进命令行参数处理，支持自动识别2×2表
- ✨ 统一列联表输入方式，使用更直观的行列参数
- 📝 更新README文档，添加详细的2×3列联表使用说明
- 🔧 优化代码结构，添加通用列联表计算器类

### v1.0 (2025)
- 初始版本
- 支持拟合优度检验
- 支持2×2列联表检验（含Yates校正）
- 支持哈温平衡检验

## 作者

AI Assistant - 2025
