Variant Analysis and Annotation

CRISPR sgRNA Design Reasoning

• PAM sequence (NGG for SpCas9) must lie 3' of the target on the non-target strand; the guide RNA targets the 20 nt immediately upstream of the PAM
• For exon targeting: choose guides that cut early in the coding sequence for maximum frameshift/disruption
• Off-target risk increases with fewer mismatches; always check for genomic sites with 0-3 mismatches to the guide

When to Use This Skill

Triggers:

• User provides a VCF file (SNV/indel or SV) and asks questions about its contents
• Questions about variant allele frequency (VAF) filtering
• Mutation type classification queries (missense, nonsense, synonymous, etc.)
• Structural variant interpretation requests (deletions, duplications, CNVs)
• Variant annotation requests (ClinVar, gnomAD, CADD, dbSNP)
• CNV pathogenicity assessment using ClinGen dosage sensitivity
• Cohort comparison questions
• Population frequency filtering (SNVs or SVs)
• Intronic/intergenic variant filtering
• Gene dosage sensitivity queries

Example Questions:

• "What fraction of variants with VAF < 0.3 are annotated as missense mutations?"
• "After filtering intronic/intergenic variants, how many non-reference variants remain?"
• "What is the clinical significance of this deletion affecting BRCA1?"
• "Which dosage-sensitive genes overlap this 500kb duplication on chr17?"
• "How many variants have clinical significance annotations?"
• "Compare variant counts between samples"

Core Capabilities

Workflow Overview

Phase 1: Parse VCF → Extract CHROM/POS/REF/ALT/QUAL/FILTER/INFO, per-sample GT/VAF/depth, annotations (ANN/CSQ/FUNCOTATION). Pure Python or cyvcf2.

Phase 2: Classify → Variant type (SNV/INS/DEL/MNV/SV), mutation type (missense/nonsense/synonymous/frameshift/splice/etc.), impact (HIGH/MODERATE/LOW/MODIFIER).

Phase 3: Filter → VAF range, depth, quality, PASS, variant/mutation type, consequence exclusion, population frequency, chromosome, SV size.

Phase 4: Statistics → Type/mutation/impact/chromosome distributions, Ti/Tv ratio, per-sample VAF/depth, gene mutation counts.

Phase 5: Annotate (optional) → MyVariant.info (ClinVar/dbSNP/gnomAD/CADD), Ensembl VEP consequence prediction.

Phase 6: Report → Markdown tables, direct answers, DataFrame export.

Phase 7: SV/CNV Analysis (if applicable) → gnomAD SV frequencies, ClinGen dosage sensitivity, ACMG pathogenicity classification.

Phase Summaries

Phase 1: VCF Parsing

Use pandas for:

• Reading VCF as structured data
• Quick exploratory analysis
• When you need to manipulate columns and rows

Use python_implementation tools for:

• Production parsing with annotation extraction
• Multi-sample VCF handling
• VAF extraction from FORMAT fields
• Large file streaming

Key functions:

vcf_data = parse_vcf("input.vcf")           # Pure Python (always works)
vcf_data = parse_vcf_cyvcf2("input.vcf")    # Fast C-based (if installed)
df = variants_to_dataframe(vcf_data.variants, sample="TUMOR")  # For pandas

Phase 2: Variant Classification

Automatic classification from annotations:

• SnpEff ANN field
• VEP CSQ field
• GATK Funcotator FUNCOTATION field
• Standard INFO keys: EFFECT, EFF, TYPE

Mutation types supported: missense, nonsense, synonymous, frameshift, splice_site, splice_region, inframe_insertion, inframe_deletion, intronic, intergenic, UTR_5, UTR_3, upstream, downstream, stop_lost, start_lost

See references/mutation_classification_guide.md for full details

Phase 3: Filtering

Common filtering patterns:

# Somatic-like variants
criteria = FilterCriteria(
    min_vaf=0.05, max_vaf=0.95,
    min_depth=20, pass_only=True,
    exclude_consequences=["intronic", "intergenic", "upstream", "downstream"]
)

# High-confidence germline
criteria = FilterCriteria(
    min_vaf=0.25, min_depth=30, pass_only=True,
    chromosomes=["1", "2", ..., "22", "X", "Y"]
)

# Rare pathogenic candidates
criteria = FilterCriteria(
    min_depth=20, pass_only=True,
    mutation_types=["missense", "nonsense", "frameshift"]
)

See references/vcf_filtering.md for all filter options

Phase 4-6: Statistics, Annotation, Reporting

Use python_implementation for standard stats (Ti/Tv, type distributions, per-sample VAF/depth); pandas for custom aggregations. For annotation, prefer MyVariant.info (batch: ClinVar + dbSNP + gnomAD + CADD); limit to 50-100 variants per batch. Reports include type/mutation/impact/chromosome distributions, VAF stats, clinical significance, and top mutated genes.

See references/annotation_guide.md for detailed examples

Phase 7: Structural Variant & CNV Analysis

When VCF contains SV calls (SVTYPE=DEL/DUP/INV/BND):

1. Identify affected genes (from VCF annotation or coordinate overlap)
2. Query ClinGen dosage sensitivity:

   clingen = ClinGen_dosage_by_gene(gene_symbol="BRCA1")
   # Returns: haploinsufficiency_score, triplosensitivity_score
   

3. Check population frequency:

   gnomad_sv = gnomad_get_sv_by_gene(gene_symbol="BRCA1")
   # Returns: SVs with AF, AC, AN
   

4. Classify pathogenicity:
   • Pathogenic: Deletion + HI score = 3, AF < 0.0001
   • Likely Pathogenic: Deletion + HI score = 2, AF < 0.001
   • VUS: HI/TS score = 0-1, AF 0.001-0.01
   • Benign: AF > 0.01

ClinGen dosage score interpretation:

• 3: Sufficient evidence for dosage pathogenicity (HIGH impact)
• 2: Some evidence (MODERATE impact)
• 1: Little evidence (LOW impact)
• 0: No evidence (MINIMAL impact)
• 40: Dosage sensitivity unlikely

See references/sv_cnv_analysis.md for full SV workflow

Answering BixBench Questions

Pattern 1: VAF + Mutation Type Fraction

Question: "What fraction of variants with VAF < X are annotated as Y mutations?"

result = answer_vaf_mutation_fraction(
    vcf_path="input.vcf",
    max_vaf=0.3,
    mutation_type="missense",
    sample="TUMOR"
)
# Returns: fraction, total_below_vaf, matching_mutation_type

Pattern 2: Cohort Comparison

Question: "What is the difference in mutation frequency between cohorts?"

result = answer_cohort_comparison(
    vcf_paths=["cohort1.vcf", "cohort2.vcf"],
    mutation_type="missense",
    cohort_names=["Treatment", "Control"]
)
# Returns: cohorts, frequency_difference

Pattern 3: Filter and Count

Question: "After filtering X, how many Y remain?"

result = answer_non_reference_after_filter(
    vcf_path="input.vcf",
    exclude_intronic_intergenic=True
)
# Returns: total_input, non_reference, remaining

ToolUniverse Tools Reference

SNV/Indel Annotation

Structural Variant Annotation

See references/annotation_guide.md for detailed tool usage examples

Common Use Patterns

# Quick summary
report = variant_analysis_pipeline("input.vcf", output_file="report.md")

# Filtered analysis
report = variant_analysis_pipeline("input.vcf",
    filters=FilterCriteria(min_vaf=0.1, min_depth=20, pass_only=True))

# Annotated report (top 50 variants with ClinVar/gnomAD/CADD)
report = variant_analysis_pipeline("input.vcf", annotate=True, max_annotate=50)

pandas vs python_implementation: Use python_implementation for parsing/classification/annotation, then convert to DataFrame for custom aggregations:

vcf_data = parse_vcf("input.vcf")
passing, _ = filter_variants(vcf_data.variants, criteria)
df = variants_to_dataframe(passing, sample="TUMOR")

Limitations

• VCF annotation required for mutation classification: If VCF has no ANN/CSQ/FUNCOTATION in INFO, mutation types will be "unknown" until ToolUniverse annotation is applied
• Multi-allelic variants: Parser takes first ALT allele for type classification
• ToolUniverse annotation rate: API-based, limited to ~100 variants per batch by default to respect rate limits
• gnomAD tool: Returns basic metadata only (not full allele frequencies); use MyVariant.info for gnomAD AF
• Large VCFs: Pure Python parser streams line-by-line; cyvcf2 is recommended for files with >100K variants

Reference Documentation

• references/vcf_filtering.md: Complete filter options and examples
• references/mutation_classification_guide.md: Detailed mutation type classification rules
• references/annotation_guide.md: ToolUniverse annotation workflows with examples
• references/sv_cnv_analysis.md: Complete SV/CNV interpretation workflow

Additional Resources

• Scripts: scripts/parse_vcf.py, scripts/filter_variants.py, scripts/annotate_variants.py
• Quick start recipes and MCP examples: QUICK_START.md