# 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 版

## 总体流程
```mermaid
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或重复计数。