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
- Input validation: Parse and validate input files with format detection
- Analysis: Count rare, high-impact loss-of-function variants carried in a VCF, annotated with molecular consequence and population allele frequency
- 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
| Format |
Extension |
Required Fields |
Example |
| VCF |
.vcf |
CHROM, POS, REF, ALT, GT |
demo_input.txt |
| TSV |
.tsv |
variant columns |
sample.tsv |
Workflow
When the user asks for rare high impact variants:
- Validate: Check input format and required fields
- Parse: Extract relevant variants and annotations
- Analyze: Apply rare high impact variants algorithm
- Generate: Write result.json with structured findings
- 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
- 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).
- Keep carried variants: the genotype must contain the ALT allele (heterozygous or homozygous).
- Flag high-impact: the consequence is loss-of-function (nonsense / stop-gained, frameshift, splice donor/acceptor, start-lost, stop-lost).
- 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.
- 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
└── checksums.sha256 # SHA-256 of outputs (sha256sum -c from output_directory)
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).
Gotchas
- Gotcha 1 (the big one): absence of a population frequency is NOT evidence of rarity. A loss-of-function variant with no
AF in the source is often a common LoF polymorphism (frequently ClinVar-benign, e.g. CASP12 nonsense). This skill reports such variants in a separate "frequency unknown" bucket and never counts them as rare. Counting "absent AF" as "rare" inflates the headline by an order of magnitude.
- Gotcha 2 (scope): the count is only as complete as the annotation. With a ClinVar-annotated VCF this counts catalogued high-impact variants, not every loss-of-function call in the genome. Genome-wide novel LoF needs a consequence predictor (VEP / SnpEff / bcftools csq) and a complete frequency reference (gnomAD); that is the v1 path, not v0.
- Gotcha 3: the input must carry consequence and frequency annotations. A raw caller VCF whose
AF is the sample genotype frequency (0.5 / 1.0), not a population frequency, will produce meaningless rarity calls. Annotate first (e.g. with bcftools against ClinVar or gnomAD).
- Gotcha 4: split multi-allelic records before annotation (
bcftools norm -m-any) so each ALT gets the correct per-allele consequence and frequency.
Safety
- Local-first: No data upload without explicit consent
- Disclaimer: Every report includes: "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."
- Audit trail: Log all operations to reproducibility bundle
- No hallucinated science: All parameters trace to cited databases
Agent Boundary
The agent (LLM) dispatches and explains. The skill (Python) executes.
The agent must NOT override thresholds or invent associations.
Integration with Bio Orchestrator
Trigger conditions: the orchestrator routes here when:
- User mentions count or rare-high-impact-variants
- Input file contains relevant loci
Chaining partners: this skill connects with:
pharmgx-reporter: downstream pharmacogenomic implications
profile-report: feeds into unified patient profile
Maintenance
- Review cadence: Re-evaluate monthly or when upstream databases update
- Staleness signals: new reference database release, API endpoint change
- Deprecation: If superseded by a more comprehensive skill, archive to
skills/_deprecated/
Citations
- TODO: Add relevant database and paper citations
1---2name: rare-high-impact-variants3description: >-4 Count rare, high-impact loss-of-function variants carried in a VCF, annotated with molecular consequence and population allele frequency5license: MIT6metadata:7 source: https://skillmd.com/skills/clawbio/rare-high-impact-variants8 version: 0.1.09 author: Manuel Corpas10 domain: genomics11 inputs:12 - name: input_file13 type: file14 format:15 - vcf16 - csv17 - tsv18 - txt19 description: Primary input data file20 required: true21 outputs:22 - name: report23 type: file24 format: md25 description: Analysis report26 - name: result27 type: file28 format: json29 description: Machine-readable results30 dependencies:31 python: ">=3.11"32 tags:33 - count34 - rare35 - high-impact36 - loss-of-function37 - variant-burden38 - lof39 demo_data:40 - path: demo_input.txt41 description: Synthetic test data42 endpoints:43 cli: python skills/rare-high-impact-variants/rare_high_impact_variants.py --input {input_file} --output {output_dir}44 openclaw:45 requires:46 bins:47 - python348 always: false49 homepage: https://github.com/ClawBio/ClawBio50 os:51 - macos52 - linux53 install:54 - kind: pip55 package: pandas56 trigger_keywords:57 - count58 - rare,59 - high-impact60---6162# Rare High Impact Variants6364You 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.6566## Trigger6768**Fire this skill when the user says any of:**69- "count rare, high-impact loss-of-function variants carried in a vcf, annotated with molecular consequence and population allele frequency"70- "run rare-high-impact-variants"71- "count rare,"72- "analyze count"7374**Do NOT fire when:**75- The user asks for general variant annotation (use vcf-annotator)76- The user asks for pharmacogenomics (use pharmgx-reporter)7778**Design notes:** The trigger must be loud, not subtle. Models skip subdued79descriptions. Use exact phrases, domain-specific terms, and multiple synonyms.8081## Why This Exists8283- **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 scripts84- **With it**: Automated analysis in seconds with a structured, reproducible report85- **Why ClawBio**: Grounded in real databases and algorithms, not LLM guessing8687## Core Capabilities88891. **Input validation**: Parse and validate input files with format detection902. **Analysis**: Count rare, high-impact loss-of-function variants carried in a VCF, annotated with molecular consequence and population allele frequency913. **Reporting**: Generate structured markdown report with machine-readable JSON9293## Scope9495**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.9697## Input Formats9899| Format | Extension | Required Fields | Example |100|--------|-----------|-----------------|---------|101| VCF | `.vcf` | CHROM, POS, REF, ALT, GT | `demo_input.txt` |102| TSV | `.tsv` | variant columns | `sample.tsv` |103104## Workflow105106When the user asks for rare high impact variants:1071081. **Validate**: Check input format and required fields1092. **Parse**: Extract relevant variants and annotations1103. **Analyze**: Apply rare high impact variants algorithm1114. **Generate**: Write result.json with structured findings1125. **Report**: Write report.md with findings, tables, and disclaimer113114**Freedom level guidance:**115- For database lookups and variant classification: be prescriptive. Every step must be exact.116- For report narrative and interpretation: give guidance but leave room for reasoning.117118## CLI Reference119120```bash121# Standard usage122python skills/rare-high-impact-variants/rare_high_impact_variants.py \123 --input <input_file> --output <report_dir>124125# Demo mode (synthetic data, no user files needed)126python skills/rare-high-impact-variants/rare_high_impact_variants.py --demo --output /tmp/rare_high_impact_variants_demo127128# Via ClawBio runner129python clawbio.py run rare-high-impact-variants --input <file> --output <dir>130python clawbio.py run rare-high-impact-variants --demo131```132133## Demo134135To verify the skill works:136137```bash138python clawbio.py run rare-high-impact-variants --demo139```140141Expected output: a report covering synthetic input data with structured results.142143## Algorithm / Methodology1441451. **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`).1462. **Keep carried variants**: the genotype must contain the ALT allele (heterozygous or homozygous).1473. **Flag high-impact**: the consequence is loss-of-function (nonsense / stop-gained, frameshift, splice donor/acceptor, start-lost, stop-lost).1484. **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.1495. **Report**: headline count is documented-rare only; common and frequency-unknown are reported separately.150151**Key thresholds / parameters**:152- `--max-af` rarity threshold, default `0.01` (1 per cent); ultra-rare band at AF < `0.001`.153- High-impact consequence set: Sequence Ontology loss-of-function terms (nonsense, frameshift, splice_donor, splice_acceptor, start_lost/initiator_codon, stop_lost).154155## Example Queries156157- "count rare, high-impact loss-of-function variants carried in a vcf, annotated with molecular consequence and population allele frequency"158- "run rare-high-impact-variants on my VCF"159- "analyze my sample with rare-high-impact-variants"160161## Example Output162163```markdown164# Rare High-Impact Variants Report165166**Input**: demo_input.txt167**Rarity threshold**: population AF < 0.01168169## 3 rare high-impact variants carried170171Of 6 carried, annotated variants, 5 are high-impact (loss-of-function). Of those:172173- **3 rare** with documented population frequency below 0.01 (ultra-rare AF < 0.001: 1; rare: 2)174- 1 common (documented AF at or above the threshold)175- 1 with no population-frequency data, so it cannot be confirmed rare176177| Gene | Locus | Consequence | Zygosity | Population AF | ClinVar |178|------|-------|-------------|----------|---------------|---------|179| GENE1 | 1:100000 C>T | nonsense | het | 0.0002 | Pathogenic |180| GENE7 | 7:700000 C>T | splice_acceptor | het | 0.002 | - |181| GENE5 | 5:500000 C>G | nonsense | het | 0.004 | - |182183*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.*184```185186## Output Structure187188```189output_directory/190├── report.md # Primary markdown report191├── result.json # Machine-readable results192├── tables/193│ └── results.csv # Tabular data194└── reproducibility/195 ├── commands.sh # Exact commands to reproduce196 ├── environment.yml # Environment snapshot197 └── checksums.sha256 # SHA-256 of outputs (sha256sum -c from output_directory)198```199200## Dependencies201202**Required**:203- Python >= 3.11; pure standard library, no third-party runtime dependencies.204205**Optional (for producing an annotated input VCF, upstream of this skill)**:206- `bcftools`; intersect a genome with ClinVar and transfer `MC` / `AF_*` annotations.207- VEP, SnpEff, or `bcftools csq` plus gnomAD; for genome-wide novel loss-of-function calling (the v1 upgrade path, out of scope for v0).208209## Gotchas210211- **Gotcha 1 (the big one)**: absence of a population frequency is NOT evidence of rarity. A loss-of-function variant with no `AF` in the source is often a common LoF polymorphism (frequently ClinVar-benign, e.g. CASP12 nonsense). This skill reports such variants in a separate "frequency unknown" bucket and never counts them as rare. Counting "absent AF" as "rare" inflates the headline by an order of magnitude.212- **Gotcha 2 (scope)**: the count is only as complete as the annotation. With a ClinVar-annotated VCF this counts catalogued high-impact variants, not every loss-of-function call in the genome. Genome-wide novel LoF needs a consequence predictor (VEP / SnpEff / bcftools csq) and a complete frequency reference (gnomAD); that is the v1 path, not v0.213- **Gotcha 3**: the input must carry consequence and frequency annotations. A raw caller VCF whose `AF` is the sample genotype frequency (0.5 / 1.0), not a population frequency, will produce meaningless rarity calls. Annotate first (e.g. with bcftools against ClinVar or gnomAD).214- **Gotcha 4**: split multi-allelic records before annotation (`bcftools norm -m-any`) so each ALT gets the correct per-allele consequence and frequency.215216## Safety217218- **Local-first**: No data upload without explicit consent219- **Disclaimer**: Every report includes: *"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."*220- **Audit trail**: Log all operations to reproducibility bundle221- **No hallucinated science**: All parameters trace to cited databases222223## Agent Boundary224225The agent (LLM) dispatches and explains. The skill (Python) executes.226The agent must NOT override thresholds or invent associations.227228## Integration with Bio Orchestrator229230**Trigger conditions**: the orchestrator routes here when:231- User mentions count or rare-high-impact-variants232- Input file contains relevant loci233234**Chaining partners**: this skill connects with:235- `pharmgx-reporter`: downstream pharmacogenomic implications236- `profile-report`: feeds into unified patient profile237238## Maintenance239240- **Review cadence**: Re-evaluate monthly or when upstream databases update241- **Staleness signals**: new reference database release, API endpoint change242- **Deprecation**: If superseded by a more comprehensive skill, archive to `skills/_deprecated/`243244## Citations245246- TODO: Add relevant database and paper citations