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

> 版本：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`）随机互作 | trial_study / 年份维度 |
| `gxr` | 砧木×接穗随机互作（rootstock 由固定效应升入随机效应，占用第二随机效应槽 Z₂，故与 G×E **互斥**） | rootstock |
| `spatial` | 残差 AR1×AR1：`R_ij = ρ_row^(|Δrow|) · ρ_col^(|Δcol|)`（1.4.0 起 aniso 双参 ρ_row/ρ_col，纯 numpy eigh REML） | 观测株均有 row_no/col_no |
| `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。