dpb/doc/桃育种系统统计分析技术说明.md

桃育种系统统计分析技术说明

版本：v1.0（2026-08-07） 面向读者：统计方法学 / 研发与维护人员（需了解混合线性模型、REML、基因组选择的背景） 配套文档：使用操作见《桃育种系统统计分析操作手册》；逐版本迭代记录见《桃育种系统统计引擎实施记录》；运行维护见《桃育种系统生产上线与运营手册》。

本文说明每个统计分析的模型与公式、参数与边界、输入数据依赖、结果落库与接口，是操作手册的底层技术对位。

---

一、总体架构

1.1 任务系统

重计算分析（ABLUP/EBV、配合力、交叉验证、稳定性、遗传相关、Type-B、基因组选择、GWAS）以异步任务方式执行，任务记录落 bre_statistics_job：

• 状态：SUCCESS / FAILED（error_msg 携带失败原因）；
• 调度 jobstore 持久化到 PostgreSQL（apscheduler_jobs），重启自动恢复；
• 轻量计算（描述统计、ANOVA、选择指数、聚类、数据质量、ΔG、选配、MABC、决选预览、公平性、模型健康）同步直出。

1.2 确定性

统计引擎输入顺序敏感性已收口：blup._order_pedigree 对 base 与同世代并列个体一律按 id 确定性排序（sorted(key=str)），系谱与表型键空间以统一 _tree_individual_keys 生成。服务层构建系谱不再受 DB 行序影响，同输入必同输出（复现性 / MLOps input_hash 语义的前提）。

1.3 MLOps

每次批次落库 input_hash（输入快照哈希）：漂移检测重算当前哈希对比；相邻批次对比输出 h² 跌幅 / EBV 排名翻转 / 可靠性变化（模型健康）；手动重训同参数重跑、版本回滚把指定批次设为当前生效版本（同性状其余 inactive）。

---

二、输入数据依赖

2.1 硬依赖（缺则报错）

数据	表	说明
性状	bre_trait	核心数值性状（统计下拉仅列 core 性状）
观测	bre_trait_observation	逐株观测值，是建模的 y
树	bre_tree	个体身份（单株/克隆/家系/区组），是建模的单位
基因型调用	基因型四表 + bre_genotyping_dataset	仅分子分析（GBLUP/ssGBLUP/rrBLUP/BayesB/GWAS/QTL/MAS）硬依赖；缺则报"基因型数据集不存在"/"该数据集无基因型调用记录"

2.2 可选增强（缺则静默降级，不阻断）

数据	表	降级行为
系谱	parent_of 亲子关系	无系谱 A → 按单株独立建模；近交/亲缘/ΔG 的 σ_A 不可用
种质	germplasm	无种质编号回显；配合力亲本、S-等位过滤不可用
克隆	clone	无无性系级聚合/EBV 排行
砧木	rootstock	G×R 不可用
研究点	trial_study	G×E（site）、稳定性环境表不可用

2.3 数据就绪门禁（G1）

data_gate=true 时对每 clone/家系最小 n（min_clone_n）、系谱完整率（min_pedigree_rate）、缺失率（max_missing_rate）做前置校验，不达标返回明确拒绝原因。

---

三、模型与算法

3.1 ABLUP / EBV（混合线性模型）

模型（以克隆随机效应为例，含固定环境效应与协变量）：

y = Xβ + Z₁u_clone + e,   u_clone ~ N(0, Aσ²a)（有系谱）或 N(0, Iσ²a)（无系谱）

• 求解：MME，solve（稠密）/ solve_spatial / solve_multi 分派；结果落 bre_prediction（批次级：h²、σ²a、σ²e、PA）+ bre_prediction_value（逐树 EBV / reliability / PA / rank）。
• 发育阶段拆分：stage=juvenile|evaluation 只取该阶段观测建模并拆独立批次（避免童期/成株混合）。
• 协变量：crop_load（负载量）等用于 BLUP 校正。

3.2 MET 扩展（G×E / G×R / AR1×AR1 / 区组）——四者互斥

选项	加入项	前置
gxe	clone×site（或组合×site；`gxe_env=site	year`）随机互作
gxr	砧木×接穗随机互作（rootstock 由固定效应升入随机效应，占用第二随机效应槽 Z₂，故与 G×E 互斥）	rootstock
spatial	残差 AR1×AR1：`R_ij = ρ_row^(	Δrow
block	bre_tree.block_no 作第二随机效应（不完全区组/增广/α-格子），需 ≥2 区组	block_no 已生成

3.3 ANOVA / 广义遗传力

单因素方差分解 + block=true 走 RCBD 双因素（从残差析出区组效应）；输出 F、p、σ²g、σ²e、家系均值、广义遗传力 H²。试验设计生成（trial-design）三种：

• rcbd：随机完全区组；
• augmented：增广——对照种质每区组重复、新品系不重复（check_germplasm_ids）；
• alpha：α-格子——block_no 复合编码 rep*100+block，区组大小 k、重复 r。

3.4 配合力 GCA / SCA

交配设计 design_type：

• full_diallel 完全双列 / partial_diallel 部分双列；
• line_tester：line×tester（NCII）；
• nciii：NCIII 测交。

输出 GCA（亲本）+ SCA（组合）+ ANOVA 摘要，落 bre_combining_ability。

3.5 遗传相关（MT-BLUP 成对双性状）

对选入性状两两跑双性状 BLUP，逐对 REML 估计 r_g = σa₁₂ / √(σa₁·σa₂)，同时给出 σa₁、σa₂、σe₁、σe₂、共同个体数 n_common、收敛标记 converged，落 bre_genetic_corr_result（矩阵 JSON）。

3.6 Type-B 多环境遗传相关

把环境当"性状"，同一性状逐对双性状 BLUP 估 r_B；env_dim：

• site：跨研究点一致性（r_B→1 则 G×E 弱）；
• year：跨年份；
• stage：童期-成株遗传相关（幼年选择有效性）。

方法 reml / calo；结果含热图数据，落 bre_type_b_result。

3.7 选择指数

方法	权重向量
zsum	加权标准分：I = Σ w_i·z_i
smith_hazel	真 Smith-Hazel：b = P⁻¹·G·a（P=表型协方差，G=遗传协方差，a=经济权重）
restricted	受限指数：b = P⁻¹G(I−M)a，其中 M = C'(CG·P⁻¹G·C')⁻¹·CG·P⁻¹G（C 为受限性状约束行），使受限性状 ΔG = 0（机器精度）

• g_method：遗传相关来源 calo（可靠性校正 EBV 相关）/ mtblup（成对双性状 REML），smith_hazel / restricted 生效；
• economic_weights：绝对尺度经济权重（不归一化，未列性状按 0）；
• auto_weights：按实测 h² 生成权重（强制 use_h2=False 防双重相乘，缺省 default_h2=0.1 兜底）；
• aggregate=clone|tree：聚合层级；
• 结果落 bre_selection_index；apply 前 N 名写决选 bre_selection_result（EBV 可靠性低于 min_reliability 跳过）。

3.8 交叉验证（k-fold）

• 表型模式：ABLUP 模型 k 折（k=2~10）掩蔽留出（masked leave-out），评估 EBV 外部预测准确度；
• GS 模式：dataset_id + method（gblup/ssgblup/rrblup/bayesb）+ maf_min + split：
  • random：固定种子随机分层（可复现）；
  • family：家系阻塞折——同父半同胞同折，防亲缘泄漏。
• 输出：mean_pearson / mean_rmse / pooled_* / cv_accuracy / h2，落 bre_cv_result + 折明细 bre_cv_fold。

3.9 稳定性 AMMI / Finlay-Wilkinson

基于两因素均值表（genotype × environment）：

• AMMI：主效应 + 乘性互作项分解，输出 IPC1/IPC2、ASV = √(IPC1² + IPC2²)、ecovalence（互作方差）、ASV 排名；ipc_variance 给出各 IPC 占比；
• FW：基因型对环境指数回归 y = a + b·x，输出斜率 b、截距、r²、se_b、dev_ms、flag_stable（b≈1 稳定型）。

结果落 bre_stability_result（detail_json）。

3.10 UPGMA 层次聚类

distance=corr|euclidean，mode=pheno|genetic，entity_type=tree|clone；k 空时按合并距离最大跳变自动定类；计算端点，不落库。

3.11 数据质量（离群值诊断）

• 缺失率统计；
• IQR 超界；
• MAD 稳健 z 双通道；
• 方向语义：同向偏离 = 精英（高值方向离群）；反向偏离 = 疑似记录错误。

3.12 遗传增益 ΔG

ΔG = k · r_g · σ_A，逐批次投影：

• k：截断选择强度，标准正态分位数 φ 经 Acklam 算法近似 Φ⁻¹（无 scipy 依赖）由 top_p / top_n 换算；
• r_g：预测准确性（取批次 PA）；
• σ_A：遗传标准差。

ΔG 是期望投影，前提为模型无偏、无近交负效应累积。

3.13 近交 / 亲缘 / 近交衰退

• 系谱 A 矩阵（relationship_matrix）→ 近交系数 F = A_ii − 1、个体对亲缘 A_ij；阈值预警，落亲缘分析结果；
• 近交衰退：F → 表型 线性回归（lstsq），斜率即衰退代价；inbreeding 字典只含 F>0 个体，样本为空时兜底为 0 处理。

3.14 主动选配推荐

评分 EBV 互补 − w_kin·亲缘惩罚，过滤逻辑：

• S-等位不相容硬过滤（germplasm.s_alleles + 交配兼容性 409/半兼容）；
• 花期软警示四态：overlap（花期重叠）/ store（花粉库存可用）/ offset（花期错开，需贮藏）/ unknown（花期未知），overlap 不进 flags、不硬阻断；
• 亲缘多源解析（系谱 + 分子指纹），EBV 缺失时回退方法学（direct 优先 / 子代测验降权）。

OCS 最优贡献选择：max Σcᵢ·ebvᵢ − λ·c'Ac，约束 Σc = n_select、c ≥ 0，投影梯度求解，纯计算不落库。

3.15 MABC 标记辅助回交

前景面板命中数 + 背景面板恢复率 + 回交代建议（generation 判定是否该继续回交 / background_target），纯计算不落库；前景/背景面板来自 MAS 面板数据。

3.16 基因组选择（GBLUP / ssGBLUP / rrBLUP / BayesB）

• GBLUP：dosage 0/1/2 → VanRaden G 矩阵 → u ~ N(0, Gσ²a) 求解 MME；
• ssGBLUP：单步法，H 矩阵合并系谱 A 与基因型 G（非基因型亲属通过系谱信息参与）；
• rrBLUP：岭回归逐标记（与 GBLUP 对偶——EBV 逐位一致），输出标记效应；
• BayesB：Gibbs 采样 + 确定性 seed（可复现），可变选择（大部分标记效应收缩为 0）。

参数：maf_min、seed；结果统一落 bre_prediction（method=GBLUP/ssGBLUP/RRBLUP/BayesB）+ bre_prediction_value。大群体走稀疏生产档（索引化 Z / 稀疏 A⁻¹ / EM-REML / 精确迹二分，可靠性分档：n≤1000 稠密逆精确、n 大 Hutchinson 近似）。

3.17 GWAS / QTL / MAS

• GLM+PC 求解器：纯 numpy，显著性经 fdist 计算；共线时岭回归兜底；
• EMMAX：零模型 _profile_solve + eigh 估方差分量再逐标记检验（gwas 1.1.0）；
• ssGWAS：单步 GWAS，MEM 对角近似（gwas 1.2.0）；
• QTL×E 分层 GWAS：按环境分层分别关联；
• MAS 面板：显著标记构建面板（bre_mas_panel + bre_mas_panel_marker），供 MABC 前景/背景选择与决策预览（童期幼苗可标记辅助选入）。

数据设计教训：PC 数量过大会吞噬 QTL 信号，需控制协变量维度。

---

四、结果数据表（落库）

表	内容
bre_prediction	育种值批次（ABLUP / GXEBLUP / GXRBLUP / GBLUP / ssGBLUP / RRBLUP / BayesB）；h²、σ²、PA、input_hash、engine_version、is_active
bre_prediction_value	逐树 EBV / reliability / PA / rank
bre_combining_ability	配合力 GCA/SCA 结果
bre_selection_index	选择指数批次
bre_selection_result	决选写入（前 N 名）
bre_anova_result	ANOVA / H²
bre_cv_result / bre_cv_fold	交叉验证批次 + 折明细
bre_statistics_job	异步任务记录（状态 / error_msg / result_ref）
bre_genetic_corr_result	遗传相关矩阵
bre_type_b_result	Type-B 多环境遗传相关
bre_stability_result	AMMI / FW 稳定性
bre_gwas_result / bre_gwas_snp / bre_qtl	GWAS 结果、SNP、QTL 定位
bre_mas_panel / bre_mas_panel_marker	MAS 面板与标记

---

五、API 索引

统一前缀 /bre/statistics（前端 frontend/web/src/api/module_bre/statistics.ts）：

端点	方法	说明
/describe	GET	描述性统计（均值/标准差/CV/极值/缺失）
/trait-values	GET	统一性状值长表视图
/correlation	GET	相关性矩阵（pheno/genetic）
/ablup/run	POST	ABLUP/EBV（异步，MET/G×E/G×R/空间/区组/stage）
/predictions	GET	育种值批次列表
/predictions/{id}/values	GET	EBV 排行
/predictions/{id}/clones	GET	无性系级 EBV 排行
/predictions/{id}/compare	GET	模型健康（相邻批次对比）
/combining/run	POST	配合力 GCA/SCA（异步）
/combining / /combining/{id}	GET	配合力列表 / 详情
/anova/run	POST	ANOVA / H²（同步）
/anova / /anova/{id}	GET	ANOVA 列表 / 详情
/trial-design	POST	试验设计生成（RCBD/增广/α-格子）
/cv/run	POST	交叉验证（异步，ABLUP/GS）
/cv / /cv/{id}	GET	CV 列表 / 详情（含折明细）
/stability/run	POST	稳定性 AMMI/FW（异步）
/stability / /stability/{id}	GET	稳定性列表 / 详情
/genetic-corr/run	POST	遗传相关（异步）
/genetic-corr / /genetic-corr/{id}	GET	遗传相关列表 / 详情
/type-b-heredity	POST	Type-B（异步）
/type-b / /type-b/{id}	GET	Type-B 列表 / 详情
/selection-index	POST	选择指数（同步）
/selection-index	GET	指数批次列表
/selection-index/{id}/apply	POST	写入决选
/cluster	POST	UPGMA 聚类（不落库）
/combination-funnel	GET	组合得失漏斗
/data-quality	POST	数据质量诊断
/inbreeding-depression	POST	近交衰退回归
/genetic-gain	POST	ΔG 投影
/kinship	POST	亲缘/近交
/mating-recommend	POST	主动选配推荐
/ocs	POST	OCS 最优贡献选择（不落库）
/mabc-progress	POST	MABC 进度（不落库）
/gblup/run	POST	GBLUP/ssGBLUP/rrBLUP/BayesB（异步）
/gblup/datasets	GET	基因型数据集列表
/decision-preview	POST	决选预览
/fairness	GET	按 site 公平性报告
/jobs / /jobs/{id}	GET	任务列表 / 状态
/traits	GET	可用性状下拉（core/selection）
/model/drift	GET	漂移检测
/model/retrain	POST	手动重训
/model/activate/{id}	POST	版本回滚/设当前

GWAS/QTL/MAS（独立页面，frontend/web/src/api/module_bre/gwas.ts）：/bre/statistics/gwas/run、/qtl、/mas-panel、/gwas-qtl-x-e。

---

六、数值与工程注意事项

1. 引擎版本：blup 1.6.0、genomic 1.4.0、gwas 1.2.0；_DATA_VERSION 随结构演进（当前 v2.14+），input_hash 语义一致。
2. 确定性：任何新增走系谱/表型键的求解必须经 _order_pedigree（id 排序）与 _tree_individual_keys 收口，禁止依赖 DB 行序。
3. 互斥约束：G×E / G×R / AR1×AR1 / 区组四选项互斥（第二随机效应槽 Z₂ 与残差结构 R 只能择一）。
4. 分子分析前置：GBLUP/GWAS 等必须先有基因型数据集与调用记录；基因型四表与表型观测的键空间必须对齐（_tree_individual_keys）。
5. 数值坑：numeric 列量化（如 numeric(12,4)）会引入舍入差；跨端比对注意服务层 3 位舍入 vs 引擎高精度。
6. 回归基线：全量回归 run_regression（72 套）串行跑，均写真 PG。