102 lines
3.8 KiB
Markdown
102 lines
3.8 KiB
Markdown
# Phase 1 How-To: BAM → VCF → Annotate → Panel Report
|
||
|
||
本文件說明如何用現有 CLI 從 BAM 執行到報告輸出，選項意義，以及可跳過步驟的用法。假設已安裝 GATK、VEP、bcftools/tabix，並以 `pip install -e .` 安裝本專案。
|
||
|
||
## 流程總覽
|
||
1) Trio variant calling → joint VCF
|
||
2) VEP 註解 → annotated VCF + 平坦 TSV
|
||
3) Panel/phenotype 查詢 + ACMG 標籤 → Markdown/JSON 報告
|
||
可用 `phase1-run` 一鍵（可跳過 call/annotate），或分步 `run-call` / `run-annotate` / `panel-report`。
|
||
|
||
## 分步執行
|
||
|
||
### 1) Variant calling（GATK）
|
||
```bash
|
||
genomic-consultant run-call \
|
||
--sample proband:/path/proband.bam \
|
||
--sample father:/path/father.bam \
|
||
--sample mother:/path/mother.bam \
|
||
--reference /refs/GRCh38.fa \
|
||
--workdir /tmp/trio \
|
||
--prefix trio \
|
||
--log /tmp/trio/run_call_log.json \
|
||
--probe-tools
|
||
```
|
||
- `--sample`: `sample_id:/path/to.bam`，可重複。
|
||
- `--reference`: 參考序列。
|
||
- `--workdir`: 輸出與中間檔位置。
|
||
- `--prefix`: 輸出檔名前綴。
|
||
- `--log`: run log（JSON）路徑。
|
||
- 輸出：joint VCF (`/tmp/trio/trio.joint.vcf.gz`)、run log（含指令/returncode）。
|
||
|
||
### 2) Annotation（VEP + bcftools）
|
||
```bash
|
||
genomic-consultant run-annotate \
|
||
--vcf /tmp/trio/trio.joint.vcf.gz \
|
||
--workdir /tmp/trio/annot \
|
||
--prefix trio \
|
||
--reference /refs/GRCh38.fa \
|
||
--plugin 'SpliceAI,snv=/path/spliceai.snv.vcf.gz,indel=/path/spliceai.indel.vcf.gz' \
|
||
--plugin 'CADD,/path/whole_genome_SNVs.tsv.gz,/path/InDels.tsv.gz' \
|
||
--extra-flag "--cache --offline" \
|
||
--log /tmp/trio/annot/run_annot_log.json \
|
||
--probe-tools
|
||
```
|
||
- `--plugin`: VEP plugin 規格，可重複（示範 SpliceAI/CADD）。
|
||
- `--extra-flag`: 附加給 VEP 的旗標（如 cache/offline）。
|
||
- 輸出：annotated VCF (`trio.vep.vcf.gz`)、平坦 TSV (`trio.vep.tsv`)、run log。
|
||
|
||
### 3) Panel/Phenotype 報告
|
||
使用 panel 檔：
|
||
```bash
|
||
genomic-consultant panel-report \
|
||
--tsv /tmp/trio/annot/trio.vep.tsv \
|
||
--panel configs/panel.example.json \
|
||
--acmg-config configs/acmg_config.example.yaml \
|
||
--individual-id proband \
|
||
--max-af 0.05 \
|
||
--format markdown \
|
||
--log /tmp/trio/panel_log.json
|
||
```
|
||
使用 phenotype 直譯 panel：
|
||
```bash
|
||
genomic-consultant panel-report \
|
||
--tsv /tmp/trio/annot/trio.vep.tsv \
|
||
--phenotype-id HP:0000365 \
|
||
--phenotype-mapping configs/phenotype_to_genes.hpo_seed.json \
|
||
--acmg-config configs/acmg_config.example.yaml \
|
||
--individual-id proband \
|
||
--max-af 0.05 \
|
||
--format markdown
|
||
```
|
||
- `--max-af`: 過濾等位基因頻率上限。
|
||
- `--format`: `markdown` 或 `json`。
|
||
- 輸出：報告文字 + run log（記錄 panel/ACMG config 的 hash）。
|
||
|
||
## 一鍵模式（可跳過 call/annotate）
|
||
已經有 joint VCF/TSV 時，可跳過前兩步：
|
||
```bash
|
||
genomic-consultant phase1-run \
|
||
--workdir /tmp/trio \
|
||
--prefix trio \
|
||
--tsv /tmp/trio/annot/trio.vep.tsv \
|
||
--skip-call --skip-annotate \
|
||
--panel configs/panel.example.json \
|
||
--acmg-config configs/acmg_config.example.yaml \
|
||
--max-af 0.05 \
|
||
--format markdown \
|
||
--log-dir /tmp/trio/runtime
|
||
```
|
||
若要實際跑 VEP，可移除 `--skip-annotate` 並提供 `--plugins/--extra-flag`；若要跑 calling，移除 `--skip-call` 並提供 `--sample`/`--reference`。
|
||
|
||
## 主要輸出
|
||
- joint VCF（呼叫結果）
|
||
- annotated VCF + 平坦 TSV（含 gene/consequence/ClinVar/AF/SpliceAI/CADD 等欄位）
|
||
- run logs（JSON，含指令、return code、config hash；在 `--log` 或 `--log-dir`）
|
||
- Panel 報告（Markdown 或 JSON），附 ACMG 自動標籤，需人工複核
|
||
|
||
## 注意
|
||
- Call/annotate 依賴外部工具與對應資源（參考序列、VEP cache、SpliceAI/CADD 資料）。
|
||
- 若無 BAM/資源，可用 sample TSV：`phase1-run --tsv sample_data/example_annotated.tsv --skip-call --skip-annotate ...` 演示報告。
|
||
- 安全：`.gitignore` 已排除大型基因檔案；建議本地受控環境執行。
|