checkpoint: 统计分析文档化——操作手册与技术说明双文档

按用户澄清的「操作手册与技术说明分开」落地：操作手册面向育种团队（20 个核心分析
四段式：目的/数据准备/操作步骤/结果解读），技术说明面向方法学/开发者（模型公式、
输入依赖与降级、落库表、API 索引）。常用核心表型分析优先，分子类第二批。

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

@@ -0,0 +1,284 @@
+# 桃育种系统统计分析技术说明
+
+> 版本：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。