brapi-java/docs/architecture/03-genotyping-data-flow.md

Genotyping 模块数据流与表关系

本文档分析 Genotyping 模块的数据录入顺序、核心表关系，以及 Java 实体名与真实数据库表名之间的对应关系。

结论

Genotyping 模块的数据主线是：

Core/Pheno 上游数据 -> sample / plate
ReferenceSet -> Reference -> ReferenceBases
ReferenceSet + Study -> VariantSet -> Variant
Sample -> CallSet
CallSet + Variant -> Call
GenomeMap -> LinkageGroup -> MarkerPosition -> Variant

更贴近业务录入的顺序是：

1. 先有 Core/Phenotyping 上游：crop、program、trial、study、observation_unit
2. 录入 Plate 和 Sample
3. 录入 ReferenceSet、Reference、ReferenceBases
4. 录入 VariantSet
5. 录入 Variant
6. 录入 CallSet
7. 录入 Call，也就是 allele_call 表里的基因型结果
8. 录入 GenomeMap、LinkageGroup、MarkerPosition

初始化脚本中与 Genotyping 相关的执行顺序是：

R__init_data_21_samples.sql
R__init_data_22_references.sql
R__init_data_23_variant_set_1.sql
R__init_data_24_genome_maps.sql
src/main/resources/db/sql/variant_set_4/variant_set_4.sql
src/main/resources/db/sql/variant_set_4/variant_set_4_alleles.sql

实体与真实表名

业务概念	Java 实体	数据库表	说明
Call	CallEntity	allele_call	单个样本在某个 variant 上的 genotype 结果
CallSet	CallSetEntity	callset	某个 sample 的一组 call，通常对应一个样本的基因型调用集合
Sample	SampleEntity	sample	送检样本/测序样本
Plate	PlateEntity	plate	样本板，包含多个 sample
MarkerPosition	MarkerPositionEntity	marker_position	variant 在 linkage group 上的位置
Variant	VariantEntity	variant	变异位点，如 SNP/Indel
ReferenceSet	ReferenceSetEntity	reference_set	参考基因组集合
GenomeMap	GenomeMapEntity	genome_map	遗传图谱
VariantSet	VariantSetEntity	variantset	一批 variant 的集合
Reference	ReferenceEntity	reference	参考序列，如 chromosome/contig
ReferenceBases	ReferenceBasesPageEntity	reference_bases	reference 的序列分页
LinkageGroup	LinkageGroupEntity	linkageGroup	图谱中的连锁群；注意表名是驼峰 linkageGroup

核心表说明

表	作用	主要上游依赖	主要下游
plate	样本板	program、trial、study，可选 vendor submission	sample
sample	样本	plate、observation_unit、program、trial、study	callset
reference_set	参考基因组集合	可选 germplasm	reference、variantset、variant
reference	参考序列	reference_set	reference_bases
reference_bases	参考序列片段/分页	reference	无
variantset	变异集合	reference_set、study	variant、callset_variant_sets、variantset_analysis、variantset_format
variant	变异位点	reference_set、variantset	allele_call、marker_position
callset	样本的 call 集合	sample	allele_call、callset_variant_sets
allele_call	genotype 调用结果	callset、variant	无
genome_map	遗传图谱	crop，可关联 study	linkageGroup
linkageGroup	连锁群	genome_map	marker_position
marker_position	marker/variant 在图谱上的位置	linkageGroup、variant	无

建议录入顺序

1. 准备 Core/Phenotyping 上游数据

Genotyping 数据通常挂在 Core 和 Phenotyping 之上。

必须或常见上游包括：

crop
program
trial
study
observation_unit

sample 可以关联 observation_unit，也会冗余关联 program/trial/study，用于查询和筛选。

2. 录入 Plate

先录入 plate，表示样本板。

plate 可关联：

program
trial
study
plate_submission

如果样本不走板，也可以直接录入 sample；但当前模型中 sample 支持挂到 plate 上。

3. 录入 Sample

录入 sample，它是 genotyping 流程的样本入口。

主要关系：

sample -> plate
sample -> observation_unit
sample -> program / trial / study
sample -> germplasm_taxon

4. 录入 ReferenceSet 和 Reference

录入 reference_set，表示参考基因组集合。

然后录入 reference，表示具体参考序列，例如 chromosome、contig。

如需保存具体序列片段，再录入：

reference_bases

5. 录入 VariantSet

录入 variantset，它把一批 variant 组织成集合。

主要关系：

variantset -> reference_set
variantset -> study

附属表包括：

variantset_analysis
variantset_format
variantset_additional_info
variantset_external_references

6. 录入 Variant

录入 variant，表示具体变异位点。

主要关系：

variant -> reference_set
variant -> variantset

附属表包括：

variant_entity_alternate_bases
variant_entity_ciend
variant_entity_cipos
variant_entity_filters_failed

7. 录入 CallSet

录入 callset，表示某个样本的一组 genotype calls。

主要关系：

callset -> sample
callset_variant_sets -> variantset

callset_variant_sets 是 callset 和 variantset 的多对多关系表。

8. 录入 Call

录入 allele_call，业务上就是 Call。

它是最终基因型调用结果，核心关系是：

allele_call -> callset
allele_call -> variant

也就是说，一条 call 表示“某个 sample/callset 在某个 variant 上的 genotype、read depth、likelihood 等结果”。

9. 录入 GenomeMap 和 MarkerPosition

如果需要遗传图谱定位，录入：

genome_map -> linkageGroup -> marker_position -> variant

marker_position 实际上把 variant 放到某个 linkage group 的具体位置上。

Genotyping 数据流图

flowchart TD
    C["Core: crop"] --> GM["genome_map 遗传图谱"]
    C --> P["Core: program"]
    P --> T["Core: trial"]
    T --> ST["Core: study"]
    ST --> PL["plate 样本板"]
    ST --> VS["variantset 变异集合"]
    ST --> SM["sample 样本"]

    OU["Pheno: observation_unit"] --> SM
    PL --> SM

    GER["Germplasm 可选"] --> RS["reference_set 参考集合"]
    RS --> R["reference 参考序列"]
    R --> RB["reference_bases 参考序列分页"]

    RS --> VS
    VS --> V["variant 变异位点"]
    RS --> V

    SM --> CS["callset 样本调用集合"]
    CS --> CSV["callset_variant_sets"]
    VS --> CSV

    CS --> CALL["allele_call / Call 基因型结果"]
    V --> CALL

    GM --> LG["linkageGroup 连锁群"]
    LG --> MP["marker_position 图谱位置"]
    V --> MP

    VS --> VSA["variantset_analysis"]
    VS --> VSF["variantset_format"]

Genotyping ER 关系图

erDiagram
    program ||--o{ plate : "program_id"
    trial ||--o{ plate : "trial_id"
    study ||--o{ plate : "study_id"

    plate ||--o{ sample : "plate_id"
    observation_unit ||--o{ sample : "observation_unit_id"
    program ||--o{ sample : "program_id"
    trial ||--o{ sample : "trial_id"
    study ||--o{ sample : "study_id"

    germplasm ||--o{ reference_set : "source_germplasm_id"
    reference_set ||--o{ reference : "reference_set_id"
    reference ||--o{ reference_bases : "reference_id"

    reference_set ||--o{ variantset : "reference_set_id"
    study ||--o{ variantset : "study_id"
    variantset ||--o{ variant : "variant_set_id"
    reference_set ||--o{ variant : "reference_set_id"

    sample ||--o{ callset : "sample_id"
    callset ||--o{ callset_variant_sets : "call_sets_id"
    variantset ||--o{ callset_variant_sets : "variant_sets_id"

    callset ||--o{ allele_call : "call_set_id"
    variant ||--o{ allele_call : "variant_id"

    crop ||--o{ genome_map : "crop_id"
    genome_map ||--o{ linkageGroup : "genome_map_id"
    linkageGroup ||--o{ marker_position : "linkage_group_id"
    variant ||--o{ marker_position : "variant_id"

    variantset ||--o{ variantset_analysis : "variant_set_id"
    variantset ||--o{ variantset_format : "variant_set_id"

API 与表的对应关系

API	主表	说明
/brapi/v2/samples	sample	样本查询、新增、修改
/brapi/v2/plates	plate	样本板查询、新增、修改
/brapi/v2/callsets	callset	样本调用集合
/brapi/v2/calls	allele_call	genotype 调用结果
/brapi/v2/variants	variant	变异位点
/brapi/v2/variantsets	variantset	变异集合
/brapi/v2/referencesets	reference_set	参考基因组集合
/brapi/v2/references	reference	参考序列
/brapi/v2/maps	genome_map	遗传图谱
/brapi/v2/markerpositions	marker_position	variant/marker 在图谱上的位置

关键注意点

1. CallEntity 对应的数据库表不是 call，而是 allele_call。
2. CallSetEntity 对应 callset，不是 call_set。
3. VariantSetEntity 对应 variantset，不是 variant_set。
4. LinkageGroupEntity 对应表名是 linkageGroup，schema 里另有外键引用时大小写需要特别注意。
5. sample 是基因型流程的样本入口，向上关联 plate/observation_unit/study/trial/program。
6. variant 是位点定义，allele_call 是样本在位点上的结果；不要把二者混成同一层数据。
7. reference_set/reference/reference_bases 是参考基因组侧；variantset/variant/callset/allele_call 是变异和结果侧。
8. genome_map/linkageGroup/marker_position 是遗传图谱定位侧，marker_position 通过 variant_id 与变异位点相连。
9. 与前两篇一样，*_additional_info 和 *_external_references 是通用扩展关系，用于补充业务字段和外部引用。