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