PlantAI-dev/docs/subfamily_gene_family_chain_identity.md

PlantAI Chain Identity: Subfamily Classification and Gene-Family Analysis

This note records the current contract for the two overlapping PlantAI analysis routes. It is intentionally narrow: it describes execution identity and artifact ownership, not biological review decisions.

Workflow Shape

PlantAI currently has one data-preparation phase, three main analysis chains, and one extension-analysis system:

• Data preparation: genome/input normalization and candidate family member identification.
• Subfamily classification: produce evidence, predict subfamilies, then confirm labels.
• Gene-family analysis: run the formal downstream family analyses after confirmed subfamily labels are available.
• RNA-seq: run expression/RNA-seq stages under the RNA-seq route.
• Extension analysis: execute user-defined extension stages outside the fixed gene-family chain.

The subfamily-classification chain and gene-family-analysis chain share the same implementation for overlapping stages such as phylogeny, motif, domain, structure, and combo. They are separated by route identity, member-set identity, subfamily-label source, and output naming.

Subfamily Classification Chain

The subfamily route is a gate before formal gene-family analysis.

Expected order:

1. identify creates candidate target members only.
2. phylogeny, motif, domain, structure, and combo run as evidence stages with analysisRoute=subfamily_evidence.
3. reference_classification predicts target labels with analysisRoute=subfamily_prediction.
4. subfamily_confirm saves reviewed labels with analysisRoute=confirmed_subfamily.

Identity rules:

• identify output is candidate input, not a final subfamily result.
• Evidence-stage member sets use {scope_id}:subfamily_evidence:domain_refined.
• reference_classification member sets use {scope_id}:subfamily_prediction:all_members.
• reference_classification.subfamily.tsv and geneID.subfamily are predicted labels and must not be treated as final downstream inputs.
• subfamily_confirm member sets use {scope_id}:confirmed_subfamily:all_members.
• confirmed_subfamily.tsv is the first final subfamily label table.

Formal Gene-Family Analysis Chain

Formal gene-family analysis starts after a confirmed subfamily table exists or the user explicitly supplies an equivalent confirmed/uploaded subfamily table.

Rules:

• Downstream stages that need subfamily labels must request subfamilyLabelSource=confirmed_or_uploaded_subfamily.
• If confirmed labels are missing, planning should pause or insert subfamily_confirm instead of silently consuming predicted labels.
• The same CLI scripts may run again after confirmation, but their route and output names must be formal downstream identities, not subfamily_evidence or subfamily_prediction.
• Frontend result display must keep evidence/prediction artifacts separate from formal gene-family artifacts even when the visible stage name is the same.

Owning Files

• Planning and gates: gfa_core/mas/agents/planning_v2.py and apps/web/vue3/main.py.
• Route, output prefix, result group, and member set: gfa_core/gene_family_stage_context.py.
• Backend command construction: apps/web/pipeline_backend.py.
• Prediction outputs: apps/cli/run_reference_classification.py.
• Confirmed outputs: apps/cli/run_subfamily_confirm.py.
• Frontend scheduling and display: apps/web/vue3/index.html.
• Strict status checks: gfa_core/mas/tools/stage_identity.py and gfa_core/mas/tools/stage_status.py.

Any future change to route names, output names, or member-set IDs must be checked across these layers together.