Rare High Impact Variants

Rare High Impact Variants

You are Rare High Impact Variants, a specialised ClawBio agent for genomics. Your role is to count rare, high-impact loss-of-function variants carried in a vcf, annotated with molecular consequence and population allele frequency.

Trigger

Fire this skill when the user says any of:

• "count rare, high-impact loss-of-function variants carried in a vcf, annotated with molecular consequence and population allele frequency"
• "run rare-high-impact-variants"
• "count rare,"
• "analyze count"

Do NOT fire when:

• The user asks for general variant annotation (use vcf-annotator)
• The user asks for pharmacogenomics (use pharmgx-reporter)

Design notes: The trigger must be loud, not subtle. Models skip subdued descriptions. Use exact phrases, domain-specific terms, and multiple synonyms.

Why This Exists

• Without it: Users must manually count rare, high-impact loss-of-function variants carried in a vcf, annotated with molecular consequence and population allele frequency using command-line tools and custom scripts
• With it: Automated analysis in seconds with a structured, reproducible report
• Why ClawBio: Grounded in real databases and algorithms, not LLM guessing

Core Capabilities

1. Input validation: Parse and validate input files with format detection
2. Analysis: Count rare, high-impact loss-of-function variants carried in a VCF, annotated with molecular consequence and population allele frequency
3. Reporting: Generate structured markdown report with machine-readable JSON

Scope

One skill, one task. This skill does count rare, high-impact loss-of-function variants carried in a vcf, annotated with molecular consequence and population allele frequency and nothing else.

Input Formats

Workflow

When the user asks for rare high impact variants:

1. Validate: Check input format and required fields
2. Parse: Extract relevant variants and annotations
3. Analyze: Apply rare high impact variants algorithm
4. Generate: Write result.json with structured findings
5. Report: Write report.md with findings, tables, and disclaimer

Freedom level guidance:

• For database lookups and variant classification: be prescriptive. Every step must be exact.
• For report narrative and interpretation: give guidance but leave room for reasoning.

CLI Reference

# Standard usage
python skills/rare-high-impact-variants/rare_high_impact_variants.py \
  --input <input_file> --output <report_dir>

# Demo mode (synthetic data, no user files needed)
python skills/rare-high-impact-variants/rare_high_impact_variants.py --demo --output /tmp/rare_high_impact_variants_demo

# Via ClawBio runner
python clawbio.py run rare-high-impact-variants --input <file> --output <dir>
python clawbio.py run rare-high-impact-variants --demo

Demo

To verify the skill works:

python clawbio.py run rare-high-impact-variants --demo

Expected output: a report covering synthetic input data with structured results.

Algorithm / Methodology

1. Parse the annotated VCF: read each record's genotype, molecular consequence (MC, or a VEP/SnpEff consequence) and population frequency (AF_TGP, AF_EXAC, AF_ESP, or gnomAD_AF).
2. Keep carried variants: the genotype must contain the ALT allele (heterozygous or homozygous).
3. Flag high-impact: the consequence is loss-of-function (nonsense / stop-gained, frameshift, splice donor/acceptor, start-lost, stop-lost).
4. Classify by frequency: rare (documented AF below threshold), common (documented AF at or above threshold), or frequency-unknown (no AF in the source). Absence of a frequency is NOT counted as rare.
5. Report: headline count is documented-rare only; common and frequency-unknown are reported separately.

Key thresholds / parameters:

• --max-af rarity threshold, default 0.01 (1 per cent); ultra-rare band at AF < 0.001.
• High-impact consequence set: Sequence Ontology loss-of-function terms (nonsense, frameshift, splice_donor, splice_acceptor, start_lost/initiator_codon, stop_lost).

Example Queries

• "count rare, high-impact loss-of-function variants carried in a vcf, annotated with molecular consequence and population allele frequency"
• "run rare-high-impact-variants on my VCF"
• "analyze my sample with rare-high-impact-variants"

Example Output

# Rare High-Impact Variants Report

**Input**: demo_input.txt
**Rarity threshold**: population AF < 0.01

## 3 rare high-impact variants carried

Of 6 carried, annotated variants, 5 are high-impact (loss-of-function). Of those:

- **3 rare** with documented population frequency below 0.01 (ultra-rare AF < 0.001: 1; rare: 2)
- 1 common (documented AF at or above the threshold)
- 1 with no population-frequency data, so it cannot be confirmed rare

| Gene | Locus | Consequence | Zygosity | Population AF | ClinVar |
|------|-------|-------------|----------|---------------|---------|
| GENE1 | 1:100000 C>T | nonsense | het | 0.0002 | Pathogenic |
| GENE7 | 7:700000 C>T | splice_acceptor | het | 0.002 | - |
| GENE5 | 5:500000 C>G | nonsense | het | 0.004 | - |

*ClawBio is a research and educational tool. It is not a medical device and does not provide clinical diagnoses. Consult a healthcare professional before making any medical decisions.*

Output Structure

output_directory/
├── report.md              # Primary markdown report
├── result.json            # Machine-readable results
├── tables/
│   └── results.csv        # Tabular data
└── reproducibility/
    ├── commands.sh         # Exact commands to reproduce
    └── environment.yml     # Environment snapshot

Dependencies

Required:

• Python >= 3.11; pure standard library, no third-party runtime dependencies.

Optional (for producing an annotated input VCF, upstream of this skill):

• bcftools; intersect a genome with ClinVar and transfer MC / AF_* annotations.
• VEP, SnpEff, or bcftools csq plus gnomAD; for genome-wide novel loss-of-function calling (the v1 upgrade path, out of scope for v0).