bttoxin-pipeline/docs/shotter_workflow_zh.md

Bttoxin_Shoter v1 工作流（中文）

本文档说明 Shotter 如何将 BtToxin_Digger 的识别结果转换为“靶标目”的预测与打分，并给出变量定义与计算理由。

输入与输出

• 输入（来自 Digger）
  • tests/output/Results/Toxins/All_Toxins.txt（必须）
  • 说明：该文件包含每条蛋白命中的毒素条目、Identity、比对长度、HMM 标记等。
• 输入（来自 BPPRC）
  • Data/toxicity-data.csv（正向活性记录）
• 输出（由 Shotter 生成）
  • toxin_support.tsv：逐命中的“命中×目”贡献矩阵（per-hit）
  • strain_target_scores.tsv：每个菌株的“菌株×目”分数矩阵（per-strain）
  • strain_scores.json：同上 JSON 版
  • 若 CSV 含 target_species：
    • strain_target_species_scores.tsv：每个菌株的“菌株×物种”分数矩阵
    • strain_species_scores.json：同上 JSON 版

总体流程

flowchart TD
  A[Genome .fna] --> B0[ORF/CDS 预测]
  B0 --> B1[CDS 翻译为蛋白]
  B1 --> B2[毒素识别 (BLAST/HMM/SVM)]
  B2 --> AT[All_Toxins.txt]
  C[BPPRC specificity CSV] --> D[构建靶标分布索引]
  AT --> E[逐命中解析]
  D --> F[逐命中打分]
  E --> F
  F --> G[菌株层合成]
  G --> H[toxin_support.tsv / strain_target_scores.tsv / strain_scores.json]

变量与符号说明

• id（Identity）：Digger 的 Identity 字段/100，范围 [0,1]
• Aln_length：比对长度；Hit_length：参考长度
• cov（Coverage）：cov = Aln_length / Hit_length，范围 [0,1]
• hmm：Digger HMM 列，YES→1/NO→0
• base：基于 id 与阈值的分段线性权重
• w_hit：单命中的相似性权重（结合了 base、coverage、HMM）
• P(order | name/subfamily/family)：从 CSV 学得的“蛋白名/亚家族/家族 → 目标目分布”
• c(order)：单命中对某“目”的贡献
• Score(strain, order)：某菌株对“目”的综合分数（noisy-OR 合成）

CSV→靶标分布：P(order | ·) 的构建

1. 仅保留阳性记录（activity==Yes）。
2. 为每条记录计算“证据强度”potency：
   • 若含 lc50：在单位桶内按反分位归一：potency = 1 - rank_percentile(lc50)。理由：LC50 越低毒力越强，反分位能将不同条目在同单位下归一到 [0,1]。
   • 若含 percentage_mortality：文本→分数：
     • ≥80% 或“greater than 80%”→0.90
     • 50–80%（含 60–80%、60–100%）→0.65
     • 0–60%/0–50%/“25%”/“some”/“stunting”→0.25
   • 否则（仅“有活性”）→0.55
3. 单位合并与理由：饮食掺喂实验中 ppm≈µg/g，故将 ppm/µg/g/ug/g/μg/g 合并到同一桶做归一；其它单位各自成桶，避免不合理跨单位比较。
4. 以“蛋白名 name”“亚家族（如 Cry1A）”“家族（如 Cry1）”三个层级分别聚合至各 target_order 的 potency 和，并在每层归一化为分布 P(order | ·)。

相似性权重 w_hit（为什么这样算）

• 分段阈值来源：Bt 命名规范广泛使用 ~0.45/0.78 作为家族/亚家族划界。
• 覆盖度约束：≥0.8 能抑制“碎片/部分结构域”的误判。
• HMM 加分：HMM 表明结构域级别的支持，但不应压倒序列一致性，因此只 +0.1 尾数，且上限 1。
• 具体公式：
  • 若 id ≥ 0.78 且 cov ≥ 0.80：base = 1.0
  • elif 0.45 ≤ id < 0.78：base = (id - 0.45) / (0.78 - 0.45)
  • else：base = 0.0
  • w_hit = min(1, base × cov + 0.1 × hmm)
• 配对家族（如 Vip1/Vip2、Vpa/Vpb）：若同菌株内未检测到配对家族且其权重≥0.3，则下调：w_hit := 0.2 × w_hit（保留弱证据）。

单命中→各“目”的贡献 c(order)

• 回退顺序：name → subfamily → family；若能解析到家族但无证据，贡献计入 other；若无法解析家族前缀，贡献计入 unknown。
• c(order) = w_hit × P(order | name/subfamily/family)

菌株层合成（noisy-OR）

• Score(strain, order) = 1 − Π_hits (1 − c(order))
• 理由：在 0–1 范围内自然累积多条独立证据，避免简单相加的“溢出/重复计数”。

特殊列

• other：可解析出家族但 CSV 无证据的命中所汇总的贡献。
• unknown：无法解析家族前缀的命中所汇总的贡献。

结果解读

• per-hit（toxin_support.tsv）：检查具体哪条毒蛋白对哪些“目”贡献较大；Weight（w_hit）综合反映一致性、覆盖与 HMM；PartnerFulfilled=NO 时仅做弱证据。
• per-strain（strain_target_scores.tsv）：看每个菌株对哪些“目”分数高；可取 Top-N 或设阈值（如 ≥0.5）标注高置信目标。

可视化与热力图

• 建议用热力图查看：
  • 菌株ד目”分数热力图（per-strain 矩阵）
  • 单菌株命中ד目”贡献热力图（per-hit 矩阵）
• 我们提供了独立脚本 scripts/plot_shotter.py 以生成 PNG：
  • 避免将绘图依赖耦合到核心打分脚本；
  • 也便于以后替换成别的可视化方案。

物种维度热图与报告

• 若生成了 strain_target_species_scores.tsv，绘图脚本会输出菌株×物种热图。
• 绘图脚本还支持论文式报告（--report_mode paper，--lang zh|en），自动汇总 Top 列与热图。

展示开关

• --merge_unresolved：仅在可视化层面合并 other+unknown → unresolved（不改变计算）。
• --per_hit_strain <Strain>：选择一个菌株绘制“每命中×目标目”的贡献热图，用于解释该菌株的 TopOrder/TopScore 来源。

Top 列与未解析桶

• TopOrder/TopScore（命中与菌株）：在“目标目”维度下的最高分及其数值。
• 若存在真实“目”，Top 排名会优先在真实“目”中选择，不以 other/unknown 决定 Top。
• other：家族可解析但索引无证据；unknown：家族不可解析。

命令行参数（评分脚本 bttoxin_shoter.py）

• 基本输入：--toxicity_csv，--all_toxins，--output_dir。
• 过滤与阈值：
  • --min_identity [0-1]，--min_coverage [0-1]
  • --allow_unknown_families（默认） / --disallow_unknown_families
  • --require_index_hit：仅保留可在索引中回退到 name/亚家族/家族之一的命中。

物种维度（可选）

• 若 toxicity-data.csv 含 target_species，将构建 P(species | name/subfamily/family) 并用与“目标目”相同的公式合成菌株层分数：
  • 命中贡献：c(species) = w_hit × P(species | ·)
  • 菌株层合成：Score(strain, species) = 1 − Π_hits(1 − c(species))

常见问答

• 是否需要再做 BLAST？不需要，直接使用 Digger 的相似性结果。
• 为什么只用阳性记录？与“无活性/阴性”混用容易引入语义歧义，v1 选择保守做法：阳性证据做加权统计。
• 为什么 noisy-OR？它能够把多条独立证据以概率意义进行合成，避免简单相加导致的>1或重复计数。