# Bttoxin Shotter 使用指南（User Guide）

本指南面向使用 Bttoxin Shotter 的研究者/工程师，说明工具的使用流程、参数、生成结果与方法学原理。本文档与当前代码严格对应：
- 评分主程序：`scripts/bttoxin_shoter.py`
- 绘图与报告：`scripts/plot_shotter.py`

如需论文式报告，绘图脚本已支持“paper”模式（中英文可选）。

---

## 一、快速上手（Quick Start）

1. 准备输入
   - BPPRC Specificity Database（CSV），路径默认：`Data/toxicity-data.csv`
   - BtToxin_Digger 产物 `All_Toxins.txt`，例如：`tests/output/Results/Toxins/All_Toxins.txt`

2. 运行评分（Shotter）
```bash
python scripts/bttoxin_shoter.py \
  --toxicity_csv Data/toxicity-data.csv \
  --all_toxins tests/output/Results/Toxins/All_Toxins.txt \
  --output_dir shotter_outputs \
  --min_identity 0.50 \
  --min_coverage 0.60 \
  --disallow_unknown_families \
  --require_index_hit
```
输出将保存在 `shotter_outputs/`（或可写的回退路径）。

3. 绘图与报告
```bash
python scripts/plot_shotter.py \
  --strain_scores shotter_outputs/strain_target_scores.tsv \
  --toxin_support shotter_outputs/toxin_support.tsv \
  --species_scores shotter_outputs/strain_target_species_scores.tsv \
  --out_dir shotter_outputs \
  --merge_unresolved \
  --per_hit_strain <你的菌株名> \
  --report_mode paper \
  --lang zh
```
生成：
- 热图：`strain_target_scores.png`、（可选）`per_hit_<strain>.png`、（可选）`strain_target_species_scores.png`
- 论文式报告：`shotter_report_paper.md`（可用 pandoc 导出 HTML/PDF）

---

## 二、输出文件说明
- `toxin_support.tsv`
  - 每条命中（Hit）的详细信息与对各“昆虫目”的贡献列，含 TopOrder/TopScore。
- `strain_target_scores.tsv`
  - 每个菌株在各“昆虫目”的合成分数，含 TopOrder/TopScore。
- `strain_scores.json`
  - 与上同内容的 JSON 版本。
- 若 CSV 含 `target_species`：
  - `strain_target_species_scores.tsv`、`strain_species_scores.json`
- 热图与报告：
  - `strain_target_scores.png`、（可选）`per_hit_<strain>.png`、`strain_target_species_scores.png`
  - `shotter_report_paper.md`（或 `shotter_summary.md`）

---

## 三、方法学与实现（与代码一致）

### 3.1 数据来源与阳性筛选
- BPPRC Specificity Database CSV 仅保留 `activity == "Yes"` 的阳性样本作为证据（`SpecificityIndex.from_csv`）。
- 若存在 `target_species` 列，则同时建立物种维度的特异性分布。

### 3.2 效价（potency）映射与归一
- 字段：`lc50` 与/或 `percentage_mortality`。
- 单位归一：`units` 中的 `ppm` 合并到 `ug/g` 的桶（diet 语境），在同一个单位桶内分布。
- 规则（`_potency_from_row`）：
  - 若 `lc50` 为数值：先保留，稍后在单位桶内按分位做“越小越强”的反排归一，得到 [0,1]。
  - 否则按 `percentage_mortality` 文本粗映射：>80%→0.9；60-100%/50-80%→~0.65；低效/部分效应→~0.25。
  - 全缺省但为阳性 → 0.55。

### 3.3 特异性索引：P(order|·) 与 P(species|·)
- 对“蛋白名称 name”聚合：按 `target_order`（或 `target_species`）对 `_potency` 求和并整体归一。
- 回退聚合：若名称无分布，则尝试亚家族（首字母）、再尝试家族（前缀+数字）。
- 由此得到：`name_to_orders`、`subfam_to_orders`、`fam_to_orders`；以及（可选）物种维度映射。

### 3.4 Digger 命中解析与家族判定
- 读取 `All_Toxins.txt`，标准化字段，并计算：
  - `coverage = Aln_length / Hit_length`；`identity01 = Identity / 100`
  - `HMM` 转布尔（`YES` → True）
  - `Hit_id_norm`：移除后缀 `-other` 等噪声（`normalize_hit_id`）
  - `family_key`：使用正则在命名中解析家族与亚家族（支持：Cry/Cyt/Vip/Vpa/Vpb/Mpp/Tpp/Spp/App/Mcf/Mpf/Pra/Prb/Txp/Gpp/Mtx/Xpp）。解析失败标记为 `unknown`。

### 3.5 命中权重（w_hit）计算（`compute_similarity_weight`）
- `base(identity, coverage)`：
  - 若 `identity≥0.78` 且 `coverage≥0.8`：`base=1.0`
  - 若 `0.45≤identity<0.78`：`base=(identity-0.45)/(0.78-0.45)`（截断到 [0,1]）
  - 否则 `base=0`
- `w = min(1, base×coverage + 0.1×I(HMM))`
- 配对要求（`partner_fulfilled_for_hit`）：
  - 家族层面启发式对（Vip1-Vip2、Vpa-Vpb、BinA-BinB）。
  - 若需配对但该菌株内不存在满足 `w≥0.3` 的搭档，`w×=0.2` 作为惩罚。

### 3.6 贡献计算与菌株层合成（noisy-OR）
- 对命中 `i`，在目标目 `o` 的贡献：`c_i(o) = w_i × P(o|·)`；
- 菌株层合成：`score(o) = 1 - ∏_i (1 - c_i(o))`；
- `other` 与 `unknown` 桶：
  - 若能解析家族但在索引中没有任何证据 → 贡献计入 `other`；
  - 若无法解析出家族前缀 → 贡献计入 `unknown`；
  - Top 排名时优先在真实“目标目”中选择，不以 `other/unknown` 决定 Top（除非没有任何真实目分数）。

### 3.7 物种维度（可选）
- 若 CSV 含 `target_species`，同样按上式计算 `species` 的潜在活性分数与 TopSpecies。

### 3.8 Top 列含义
- `TopOrder/TopScore`（命中或菌株）：在“目标目”维度下的最高分及数值，用于快速汇报与排序。
- `TopSpecies/TopSpeciesScore`：在“物种”维度下的最高分及数值（若存在物种维度）。

---

## 四、命令行参数（CLI）

### 4.1 评分程序：`scripts/bttoxin_shoter.py`
- 必要输入
  - `--toxicity_csv`：BPPRC CSV（默认：`Data/toxicity-data.csv`）
  - `--all_toxins`：Digger 的 `All_Toxins.txt`（默认示例路径见代码）
  - `--output_dir`：输出目录（自动检测可写路径并回退）
- 过滤与阈值（与代码一致）
  - `--min_identity [0-1]`、`--min_coverage [0-1]`
  - `--allow_unknown_families`（默认启用）/ `--disallow_unknown_families`
  - `--require_index_hit`：仅保留能在特异性索引中回退到 name/亚家族/家族之一的命中

### 4.2 绘图与报告：`scripts/plot_shotter.py`
- 基本输入
  - `--strain_scores`、`--toxin_support`、`--species_scores`（可选）
  - `--out_dir`、`--cmap`、`--vmin`、`--vmax`、`--figsize`
- 可视化与报告
  - `--merge_unresolved`：将 `other+unknown` 合并为 `unresolved`（仅影响可视化/汇总）
  - `--per_hit_strain <Strain>`：仅用于绘制“单菌株每命中×目标目”的热图，不改变计算
  - `--report_mode {paper,summary}`：论文式或简版报告（默认 paper）
  - `--lang {zh,en}`：报告语言（默认 zh）
  - `--summary_md <PATH>`：报告写入路径（不指定则自动命名）

---

## 五、常见问题（FAQ）

- Q：`other` 与 `unknown` 有何区别？
  - A：`other` 表示能解析出家族名，但在 BPPRC 特异性索引里没有任何证据；`unknown` 表示连家族前缀都解析不出来。两者都不能合理分配到具体“昆虫目”，但含义不同，有助溯源是“命名/解析问题”还是“索引覆盖不足”。

- Q：这是否意味着“都不知道杀什么虫子”？
  - A：是“没有证据支撑分配到具体目”，不等于“无活性”。`other/unknown` 不会增加任何真实“目”的分数，仅计为未解析部分。

- Q：如何减少 `other/unknown`？
  - A：
    - 提高阈值：`--min_identity`、`--min_coverage`；
    - 过滤：`--require_index_hit`、`--disallow_unknown_families`；
    - 清洗命名、补充 BPPRC 数据或构建别名映射。

- Q：`--per_hit_strain` 是做什么的？
  - A：仅用于选择一个菌株生成“每命中×目标目”的热图，帮助解释哪些命中支撑了某个 TopOrder/TopScore。不会改变任何评分结果。

- Q：`TopOrder/TopScore` 是什么？
  - A：在“目标目”维度下的最高分及其数值（命中或菌株），用于快速汇报与排序。若存在真实“目”，Top 不会选 `other/unknown`。

---

## 六、示例（Examples）

- 推荐的初筛参数：
```bash
python scripts/bttoxin_shoter.py \
  --toxicity_csv Data/toxicity-data.csv \
  --all_toxins tests/output/Results/Toxins/All_Toxins.txt \
  --output_dir shotter_outputs \
  --min_identity 0.50 --min_coverage 0.60 \
  --disallow_unknown_families --require_index_hit
```
- 绘图与报告（paper/中文）：
```bash
python scripts/plot_shotter.py \
  --strain_scores shotter_outputs/strain_target_scores.tsv \
  --toxin_support shotter_outputs/toxin_support.tsv \
  --species_scores shotter_outputs/strain_target_species_scores.tsv \
  --out_dir shotter_outputs \
  --merge_unresolved \
  --per_hit_strain C15 \
  --report_mode paper --lang zh
```
- 将报告导出为 HTML（示例）：
```bash
pandoc -s shotter_outputs/shotter_report_paper.md -o shotter_outputs/shotter_report_paper.html
```

---

## 七、再现性与路径策略
- 输出目录写入策略：优先 `--output_dir`；不可写则回退到 `<output_dir>/Shotter`；再回退到 `./shotter_outputs/`。
- 若未提供 `species_scores` 或 CSV 无 `target_species`，物种热图与报告章节将自动跳过。

---

## 八、附录：家族/亚家族解析
- 受支持的家族前缀（正则）：
  - `Cry`、`Cyt`、`Vip`、`Vpa`、`Vpb`、`Mpp`、`Tpp`、`Spp`、`App`、`Mcf`、`Mpf`、`Pra`、`Prb`、`Txp`、`Gpp`、`Mtx`、`Xpp`
- 例如：
  - `Cry1Ac1` → family=`Cry1`，subfamily=`Cry1A`
  - `Bmp1-other` 标准化后 → `Bmp1`（若索引中无证据，将落入 `other`）

---

如需在“计算层面”将 `other+unknown` 永久合并为 `unresolved`，或希望在报告中插入自定义方法学/参考文献段落，请提出需求，我可在现有脚本中加入相应开关与模板扩展。