From 89eb63412c5d8dbf7f1a8dd25b75b72f90272056 Mon Sep 17 00:00:00 2001
From: Kemal Yaylali <kemal.yaylali@gmail.com>
Date: Tue, 29 Sep 2026 17:15:43 +0100
Subject: [PATCH] docs: user guide sections for CN/LOH/mosaicism and
 pharmacogenomics

---
 docs/user_guide.md | 51 ++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 51 insertions(+)

diff --git a/docs/user_guide.md b/docs/user_guide.md
index 9dbf8a1..f8005f9 100644
--- a/docs/user_guide.md
+++ b/docs/user_guide.md
@@ -139,6 +139,57 @@ simurg methyl qc --manifest infinium-methylationepic-v-1-0-b5-manifest-file.csv
 * Sample sheets may use `Sentrix_ID`/`Sentrix_Position` (minfi/sesame convention) as key columns.
 * `simurg qc controls --array-type methylation --csv MANIFEST.csv` computes only the control tables.
 
+## Copy number, LOH and mosaicism
+
+Genome-wide CNV / LOH / mosaic calling from GTCs (spec CYTO-001 … CYTO-042; validation in
+`docs/validation/V2_cn.md`).
+
+```bash
+# once per manifest + batch: GC covariates, population BAF, and a batch reference from ≥ 24 normal GTCs
+simurg cn build-model --bpm GSA.bpm --fasta GRCh38.fa --egt GSA.egt --reference-gtcs normals/ --out gsa.simurg-cyto
+simurg cn call --bpm GSA.bpm --model gsa.simurg-cyto --gtcs run/ --fasta GRCh38.fa --out run/cn
+simurg cn annotate --vcfs run/cn --annotation-bundle simurg-cyto-annot-GRCh38-….zip   # ISCN, cytobands, genes
+```
+
+* Per sample `<id>.cyto.cnv.vcf.gz` (+ `.tbi`) with DEL/DUP/LOH/mosaic calls, `<id>.cn_segments.parquet`, and
+  `cn_sample_summary.tsv` / `cn_call_manifest.json` for the batch. `scripts/build_annotation_bundle.sh` builds the
+  annotation bundle from UCSC tables.
+* Mosaic fractions are estimated from the noise-normalised BAF split (CYTO-041); losses without heterozygotes are
+  promoted to constitutional deletions. Per-probe LRR noise from the reference is on by default
+  (`--no-probe-lrr-sd` turns it off).
+* Array CN calling finds rare events; CNVs common in the reference batch are normalised away (K-027).
+
+## Pharmacogenomics
+
+Targeted copy number, star alleles and phenotypes (spec PCN-001 … PCN-017, PGX-001 … PGX-035; validation in
+`docs/validation/V2_pgx_cn.md` and `V2_pgx_star.md`). GRCh38 only.
+
+```bash
+bash scripts/pgx/fetch_sources.sh                      # CPIC (CC0), PharmVar, ClinPGx → data/pgx/sources/
+simurg pgx db build --sources data/pgx/sources --fasta GRCh38.fa --manifests GSA-PGx.bpm --csv GSA-PGx.csv \
+    [--mask GSA-PGx.mask.tsv] --out pgxdb/              # → pgx_db-1-<sha12>.sqlite
+simurg pgx coverage --bpm GSA-PGx.bpm --db pgxdb/pgx_db-….sqlite     # which alleles this array can call
+simurg pgx copy-number train --gtcs cohort/ --bpm GSA-PGx.bpm --csv GSA-PGx.csv --fasta GRCh38.fa --out cnmodel/
+simurg pgx copy-number call --gtcs run/ --model cnmodel/GSA-PGx.simurg-pgxcn --fasta GRCh38.fa --out run/vcf
+simurg gtc-to-vcf --gtcs run/ --bpm GSA-PGx.bpm --csv GSA-PGx.csv --fasta GRCh38.fa --out run/vcf
+simurg pgx star-allele call --vcfs run/vcf --db pgxdb/pgx_db-….sqlite --out run/pgx
+simurg pgx phenotype --calls run/pgx --db pgxdb/pgx_db-….sqlite [--guideline cpic|dpwg]
+```
+
+* **Targeted CN** for CYP2D6 (5′ region, intron 2, exon 9), CYP2A6, GSTM1, GSTT1 (alt contig), UGT2B17, SULT1A1 and
+  CYP2E1: one record per region in `<id>.pgx_cn.vcf.gz`. Training needs ≥ 96 samples (`--min-samples` lowers it
+  for research use) and the platform from `--csv` or `--platform`.
+* **Star alleles**: CPIC star-allele genes, PharmVar genes CPIC does not define (CYP1A2, CYP2A6, CYP2A13, CYP2C8,
+  CYP3A4), G6PD, HLA-A/B tag variants, genotype-only variant-based genes (CPIC and ClinPGx), and `*0` genotypes
+  for GSTM1/GSTT1/UGT2B17. CYP2D6 structures (`*5`, `xN`, `*68+*4`, `*36+*10`, `*13`) come from the sub-region CNs.
+* **Probe mask** (PGX-010): `scripts/pgx/derive_masks.py` compares array calls with 1000 Genomes 30x for the batch's
+  1000G individuals and masks probes below 95 % concordance.
+* **Outputs**: `diplotype_summary.tsv`, `supporting_variants.tsv`, `unresolved_variants.tsv`,
+  `variants_not_covered.tsv`, `pgx_calls.json`; after `phenotype`, `<id>.pgx.json` (`simurg.pgx/1`) and
+  `diplotype_annotations.tsv`. Array-equivalent alleles, no-call impact and alternatives are listed per gene.
+* **DPWG**: genes CPIC covers use the CPIC mappings (as ClinPGx does); DPWG-only genes (CYP1A2, CYP3A4, F5) get no
+  phenotype (K-029).
+
 ## Presets and reproducibility
 
 * `--preset current` (default): normalization 1.2.0, sex rule 2, GTC v5 — the current vendor software behaviour.