基因家族分析阶段类型与命名规则建议

日期：2026-05-26

本文档是命名规范建议和代码审计结论，不表示当前代码已经全部实现。当前代码中仍有多处直接使用 {prefix}.{scope_id} 拼接输出名。

1. 基本原则

scope 不能取消。 scope_id、scope_mode、目标物种、参考物种和比较物种必须继续保留。

文件名不应完整暴露 scope_id。 用户文件名应该短，机器身份应该放在 manifest。

当前问题命名：
Lc.SPL.SPL.target-Lc.ref-At.target_plus_reference.structure.png

推荐思路：
用户文件名 = short_output_prefix + stage + ext
机器身份 = manifest 内记录 scope_id + analysis_route + member_set_id + subfamily_source

2. scope 类型

scope_mode	含义	实际参与物种	示例
`target_only`	只分析目标物种	target	Lc
`target_plus_reference`	目标 + 参考	target + reference	Lc + At
`target_plus_comparative`	目标 + 比较物种	target + comparative	Lc + Os
`target_plus_reference_plus_comparative`	目标 + 参考 + 比较	target + reference + comparative	Lc + At + Os

3. 分析身份类型

编号	类型	analysis_route	典型用户表达	建议 short_output_prefix
1	单目标传统分析	`single_species`	执行 Lc 的结构、motif、domain、树	`Lc.SPL`
2	多目标传统分析	`multi_target`	执行 Lc 和 Dl 的多物种树	`Target.SPL.target-Lc-Dl`
3	目标 + 比较物种分析	`multi_species`	Lc、Dl、Os 做比较树	`Target.SPL.target-Lc-Dl.comp-Os`
4	目标 + 参考亚家族预测	`subfamily_prediction`	用 At 给 Lc 分类	`Target.SPL.target-Lc.ref-At.subfamily_prediction`
5	目标 + 参考 + 比较分类证据	`subfamily_prediction`	Lc、Dl、At、Os 一起建树并分类	`Target.SPL.target-Lc-Dl.ref-At.comp-Os.subfamily_prediction`
6	确认亚家族后正式分析	`confirmed_subfamily`	用确认后的亚家族重画结构图	`Lc.SPL.confirmed_subfamily`
7	子家族/成员子集分析	`subset_subfamily`	只分析 SPL7 亚家族	`Lc.SPL.subfamily-SPL7`
8	重绘或参数重跑	`replot_only` / hash	只重绘树；bootstrap 改成 1000	`Lc.SPL.replot` / `Lc.SPL.param-a1b2c3`

4. 各阶段命名矩阵

阶段	单目标传统	多目标/比较	亚家族预测	确认后/子集
`identify`	`Lc.SPL.final_members.*`	`Target.SPL.identify.manifest.json`，并保留每个物种成员文件	reference 不当作 target 鉴定	`Lc.SPL.member_set-{id}.final_members.*`
`phylogeny`	`Lc.SPL.tree.*`	`Target.SPL.target-Lc-Dl.tree.` / `.comp-Os.tree.`	`Target.SPL.target-Lc.ref-At.subfamily_prediction.tree.*`	`Lc.SPL.confirmed_subfamily.tree.` / `Lc.SPL.subfamily-SPL7.tree.`
`reference_classification`	不适用	不作为普通多物种阶段	`Target.SPL.target-Lc.ref-At.subfamily_prediction.reference_classification.*`	确认后不再叫 prediction
`subfamily_confirm`	不适用	不适用	输入 prediction	`Lc.SPL.confirmed_subfamily.tsv`
`motif`	`Lc.SPL.motif.*`	`Target.SPL.target-Lc-Dl.motif.*`	`Target.SPL.target-Lc.ref-At.subfamily_prediction.motif.*`	`Lc.SPL.confirmed_subfamily.motif.*`
`domain`	`Lc.SPL.domain.*`	`Target.SPL.target-Lc-Dl.domain.*`	`Target.SPL.target-Lc.ref-At.subfamily_prediction.domain.*`	`Lc.SPL.confirmed_subfamily.domain.*`
`structure`	`Lc.SPL.structure.*`	`Target.SPL.target-Lc-Dl.structure.*`	`Target.SPL.target-Lc.ref-At.subfamily_prediction.structure.*`	`Lc.SPL.confirmed_subfamily.structure.*`
`combo`	`Lc.SPL.combo.*`	`Target.SPL.target-Lc-Dl.combo.*`	`Target.SPL.target-Lc.ref-At.subfamily_prediction.combo.*`	`Lc.SPL.confirmed_subfamily.combo.*`
`promoter`	`Lc.SPL.promoter.*`	建议按目标物种拆分	不属于 prediction 核心	`Lc.SPL.confirmed_subfamily.promoter.*`
`synteny`	`Lc.SPL.synteny.*`	建议按目标物种拆分	不属于 prediction 核心	`Lc.SPL.subfamily-SPL7.synteny.*`
`interspecies_synteny`	不适合纯单物种	`Target.SPL.target-Lc.ref-At.interspecies_synteny.*`	可作为证据，但需带 route	`Target.SPL.target-Lc.ref-At.confirmed_subfamily.interspecies_synteny.*`
`karyotype`	`Lc.SPL.karyotype.*`	`Target.SPL.target-Lc-Dl.karyotype.*`	通常不是 prediction 核心	`Lc.SPL.confirmed_subfamily.karyotype.*`
`pep`	`Lc.SPL.pep.*`	`Target.SPL.target-Lc-Dl.pep.*`	可做证据，不冒充分类结果	`Lc.SPL.subfamily-SPL7.pep.*`
`ortholog`	不适合纯单物种	`Target.SPL.target-Lc.ref-At.ortholog.*`	可服务后续 PPI/KaKs	`Target.SPL.target-Lc.ref-At.confirmed_subfamily.ortholog.*`
`ppi`	`Lc.SPL.ppi.*`	`Target.SPL.target-Lc.ref-At.ppi.*`	不应叫 prediction	`Lc.SPL.confirmed_subfamily.ppi.*`
`kaks`	不适合纯单物种	`Target.SPL.target-Lc.ref-At.kaks.*`	不应叫 prediction	`Lc.SPL.subfamily-SPL7.kaks.*`
`expression`	`Lc.SPL.expression.*`	多物种表达应分物种或标明矩阵来源	不属于 prediction	`Lc.SPL.confirmed_subfamily.expression.*`

5. manifest 必须记录的字段

{
  "prefix": "Lc.SPL",
  "output_prefix": "Lc.SPL",
  "scope_id": "SPL.target-Lc.ref-At.target_plus_reference",
  "scope_mode": "target_plus_reference",
  "analysis_route": "subfamily_prediction",
  "member_set_id": "SPL.target-Lc.ref-At.target_plus_reference:subfamily_prediction:all_members",
  "subfamily_source": "predicted",
  "target_species": ["Lc"],
  "reference_species": ["At"],
  "comparative_species": [],
  "selected_species": ["Lc", "At"]
}

6. 最小示例

单目标传统分析 Lc SPL

Lc.SPL.tree.nwk
Lc.SPL.structure.png
Lc.SPL.motif.png
Lc.SPL.domain.tsv
Lc.SPL.combo.png
Lc.SPL.phylogeny.manifest.json

用 At 给 Lc 做亚家族预测

Target.SPL.target-Lc.ref-At.subfamily_prediction.tree.nwk
Target.SPL.target-Lc.ref-At.subfamily_prediction.reference_classification.subfamily.tsv
Target.SPL.target-Lc.ref-At.subfamily_prediction.structure.png
Target.SPL.target-Lc.ref-At.subfamily_prediction.motif.png
Target.SPL.target-Lc.ref-At.subfamily_prediction.domain.png
Target.SPL.target-Lc.ref-At.subfamily_prediction.combo.png

用户确认后正式结果

Lc.SPL.confirmed_subfamily.tsv
Lc.SPL.confirmed_subfamily.tree.png
Lc.SPL.confirmed_subfamily.structure.png
Lc.SPL.confirmed_subfamily.motif.png
Lc.SPL.confirmed_subfamily.domain.png
Lc.SPL.confirmed_subfamily.combo.png

子家族 SPL7

Lc.SPL.subfamily-SPL7.tree.png
Lc.SPL.subfamily-SPL7.structure.png
Lc.SPL.subfamily-SPL7.motif.png
Lc.SPL.subfamily-SPL7.domain.png
Lc.SPL.subfamily-SPL7.expression.tsv

7. 当前代码迁移建议

定义唯一的 user_output_prefix_for(stage, prefix, scope_data, analysis_route, member_set_id)。
保留 legacy_output_prefix 读取旧结果。
CLI 阶段只调用统一函数，不再自行拼 {prefix}.{scope_id}。
stage-status 同时支持新命名和旧命名。
result parser / frontend 以 manifest 字段分区，而不是靠文件名猜测。