121 lines
6.7 KiB
Markdown
121 lines
6.7 KiB
Markdown
# 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或重复计数。
|