Initial commit

docs/phase1_howto.md

@@ -0,0 +1,101 @@
+# 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` 已排除大型基因檔案；建議本地受控環境執行。