WeGene Breeding & IBD Simulation Engine

本项目是一个基于 GPU 加速的遗传模拟引擎，旨在利用 WeGene 格式的基因型数据模拟繁衍过程（减数分裂），生成具有生物学合理性的数字后代。项目包含用于构建参考面板、优化遗传干涉参数以及验证 IBD (Identity-by-Descent) 统计数据的工具。

功能特性

• GPU 加速模拟: 利用 CUDA (CuPy) 并行计算，支持大规模后代模拟。
• 生物学减数分裂模型:
  • 采用 Gamma 干涉模型 (Gamma Interference Model) 模拟染色体交叉互换。
  • 针对 HLA (MHC) 区域的专门化 Phasing: 在 6 号染色体 MHC 区域 (28Mb-34Mb) 自动切换至 "Template Matching" 算法，并支持加载独立的泛亚群/汉族 HLA 参考面板 (chr6_hla_pan_asian.npz)，以提高复杂区域的定相准确率。
  • 支持基于父系年龄的从头突变 (De Novo Mutation) 模拟。
  • 包含 CpG 岛脱氨基等特定突变逻辑。
  • 模拟 UPD (单亲二倍体) 和 CNV (拷贝数变异) 等罕见事件（配置中包含致病区域定义）。
• 贝叶斯参数优化: 使用 Optuna 自动调整干涉模型参数 (gamma_scale, gamma_shape)，以逼近真实的同胞 IBD 分布 (Mean 50%, SD 3.6%)。
• 参考面板构建: 支持从千人基因组计划 (1000 Genomes Project) 数据构建用于定相 (Phasing) 和插补 (Imputation) 的参考面板（主要针对汉族人群 CHB+CHS）。
• 高效存储: 使用位压缩 (Bit-packing) 和 .npz 格式高效存储模拟数据。

环境要求

项目运行在 Windows 环境下（需支持 CUDA），主要依赖 Python 3.8+。

核心依赖库

• numpy: 数值计算
• pandas: 数据处理
• scipy: 统计分布函数
• cupy: GPU 加速 (需配合对应版本的 CUDA Toolkit)
• optuna: 参数自动优化
• tqdm: 进度条显示
• psutil: 内存监控

安装示例：

pip install numpy pandas scipy cupy-cuda12x optuna tqdm psutil

(注意: 请根据你的 CUDA 版本选择合适的 cupy 包，例如 cupy-cuda11x 或 cupy-cuda12x)

项目结构

• breeding_sim.py: 主程序。负责加载数据、定相、执行减数分裂模拟、突变处理及结果输出。
• optimize_ibd_parameters.py: 优化脚本。调用主程序，使用 TPE 算法寻找最佳的交叉互换参数。
• build_reference_panel.py: 工具脚本。解析 VCF 文件，提取特定人群（如汉族）数据并构建参考面板。
• gpu_kernels.py: CUDA 内核。包含定制的 CUDA C 代码，用于在 GPU 上进行高效的数据位压缩 (gather_packed)。
• check_gpu_fix.py: GPU 环境检查工具。

使用说明

1. 构建参考面板 (Build Reference Panel)

如果需要从 VCF 文件构建参考数据：

python build_reference_panel.py --chrom all

该脚本会自动在 reference_panel/ 目录下搜索 VCF 文件，并提取 CHB/CHS 样本生成 .npz 面板。

2. 运行繁衍模拟 (Run Simulation)

直接运行主程序进行模拟。支持通过命令行参数调整配置（部分参数需在脚本内配置或扩展 CLI）：

python breeding_sim.py --n_sim 50 

• --n_sim: 模拟生成的后代数量。
• (注: 脚本内部包含对 CUDA 路径的自动修复逻辑，适用于 Windows 环境)

3. 参数优化 (Optimize Parameters)

寻找最佳的 Gamma 模型参数以符合 IBD 预期：

python optimize_ibd_parameters.py

该脚本会运行多次模拟，计算 IBD 均值和标准差，并最小化与目标值 (50% / 3.6%) 的差异。结果存储在 ibd_opt.db 数据库中。

关键算法说明

遗传图谱与重组

• 使用 Haldane 或 Kosambi 映射函数的变体，结合遗传距离 (cM)。
• Gamma Model: 交叉互换事件的间隔服从 Gamma 分布，模拟生物学上的正干涉效应（即一个交叉互换发生会抑制附近再次发生互换）。

GPU 优化

• 数据在传输到 GPU 前进行预处理。
• 核心模拟逻辑（交叉互换掩码生成、位操作）完全在 GPU 上执行。
• 使用自定义 CUDA Kernel (gpu_kernels.py) 将结果压缩为 2-bit 编码 (A/C/G/T) 的 uint32 数组，大幅减少显存占用和传输带宽。

注意事项

• 确保 resources/ 目录下存在遗传图谱文件 (genetic_map_hg19_withX.txt.gz)。
• 模拟过程中会自动生成临时文件到 temp_partitions/，并在完成后清理。
• 如遇到 DLL 加载错误 (nvcuda.dll 等)，脚本尝试自动添加路径，但确保显卡驱动已更新。