add usage markdown file

docs/shotter_workflow_zh.md

@@ -0,0 +1,120 @@
+# 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或重复计数。