genomics-phasing

genomics-phasing

When to use

The user has a phased VCF (from WhatsHap, SHAPEIT5, Eagle2, etc.) and wants phasing QC: total het count, phased fraction, phase-block count, phase-block N50 (in bp), per-block sizes. Phasing detection relies on the PS (Phase Set) FORMAT field plus pipe-delimited genotype encoding (0|1 vs 0/1).

This skill does NOT phase variants — it summarises a VCF that has already been phased.

Inputs & Outputs

Inputs

• File types: .vcf
• Accepts artifact genomics.filtered_variants (vcf)

Outputs

• tables/phase_blocks.csv
• tables/phased_variants.csv
• report.md
• result.json
• Produces artifact genomics.phased_variants as tables/phased_variants.csv (csv)

Flow

1. Load VCF (--input <phased.vcf>) or generate a demo phased VCF at output_dir/demo_phased.vcf with --n-variants records (genomics_phasing.py:200).
2. Parse records; classify each het as phased (| in GT and PS populated) or unphased (/).
3. Group phased variants by PS; compute per-block start / end / length / variant count.
4. Compute phase-block N50 (bp); phased fraction across all hets.
5. Write tables/phased_variants.csv (genomics_phasing.py:327) + tables/phase_blocks.csv (:345) + report.md + result.json (:348).

Gotchas

• No phaser is invoked. This skill ingests an already-phased VCF — it does not run WhatsHap / SHAPEIT5 / Eagle2. Run a phaser upstream and feed its VCF here.
• --input REQUIRED unless --demo. genomics_phasing.py:314 raises ValueError("--input required when not using --demo"); non-existent paths raise FileNotFoundError at :317.
• Unphased VCFs produce empty phase-block tables. A VCF without any | genotypes or PS fields will report phased_fraction = 0 and an empty phase_blocks.csv — but the run does NOT fail. Always check the summary before drawing conclusions.
• PS is required for block grouping — without it you get ZERO blocks. When PS is absent, genomics_phasing.py:126 falls back to str(pos) so every variant becomes a singleton phase-set; then :157 filters out blocks with < 2 variants, producing zero phase blocks and phase_block_n50_bp = 0. WhatsHap output always includes PS; some other phasers do not — verify before interpreting an "unphased" report.
• Multi-sample VCFs are NOT supported. Only the first sample column is parsed; multi-sample phasing comparison is out of scope.
• Demo VCF synthesises ~80% phased het variants in 5–20 blocks. Useful for orchestrator smoke tests; not biologically meaningful.