/alphagenome_variant_impact_score

name: alphagenome-variant-impact-score
description: >-
  Score, annotate, and analyze the functional impact of genetic variants using AlphaGenome Variant Impact
  (AVI) scores. Query variants in chr:pos:ref>alt format, annotate VCF/tabular callsets, perform
  saturation mutagenesis window scans (1-based closed chr:start-end), and extract GENCODE v46 GTF
  gene/exon/junction coordinates all via the AlphaGenome Atlas API.

AlphaGenome Variant Impact (AVI) Analysis

Score and prioritize genetic variants using AlphaGenome Variant Impact (AVI) models via `scripts/alphagenome_atlas_avi.py`.

> [!IMPORTANT] **Research Use Only & Clinical Safety Rules**: The AlphaGenome > AVI Skill and the underlying AlphaGenome model/Atlas are **strictly research > tools**. Access to outputs requires an AlphaGenome API key subject to terms of > service prohibiting clinical use. > > 1. **No Medical Advice or Clinical Diagnosis**: You **MUST NOT** provide > medical advice, clinical diagnoses, disease management strategies, or > treatment recommendations based on outputs from this skill or the > AlphaGenome Atlas. > 2. **Strict Molecular & Functional Framing**: A high AVI score reflects > **predicted molecular/functional impact** (e.g., disruption of splicing, > alteration of transcription factor binding, chromatin accessibility > changes, or coding consequences). Frame all findings in terms of molecular > mechanisms and biological annotations—never as clinical diagnoses or > medical conclusions. > 3. **No Diagnostic Leaps**: Never extrapolate high functional impact to > clinical disease causation, penetrance, or patient prognosis. If a user > asks a clinical or diagnostic question, explicitly clarify that > AlphaGenome is a research tool and restrict your answer to the predicted > molecular and functional effects.

> [!IMPORTANT] **Always Use AlphaGenome GENCODE v46 GTF > (`scripts/alphagenome_atlas_avi.py gtf`) for Gene Annotations**: When > retrieving gene models, transcript IDs, exon coordinates, CDS/UTR regions, or > splice junction donor/acceptor boundaries, **always use the built-in > `scripts/alphagenome_atlas_avi.py gtf` command**. Do **NOT** query external > sources (e.g., Ensembl REST API, UCSC, external GTF databases, or NCBI) for > gene annotations or transcript coordinates. This ensures that the annotations > match the scores and website.

--------------------------------------------------------------------------------

Prerequisites

Run `scripts/alphagenome_atlas_avi.py` using `uv run`:

# Display CLI help:
uv run scripts/alphagenome_atlas_avi.py --help

> [!TIP] **Agent & Programmatic Execution Format**: When invoking the CLI in > agent workflows, prefer `--format json` or direct file export (`-o <file>`) > for deterministic, structured parsing rather than extracting fields from > stdout markdown tables.

1. Query Variants (`query`)

Query single or multiple variants in 1-based `chr:pos:ref>alt` format to inspect scores and the 18 biological feature attribution weights:

# Query single variant with basic feature importances (stdout JSON preview):
uv run scripts/alphagenome_atlas_avi.py query "chr9:128225994:G>A" --format json

# Query variant with exact underlying Atlas track indices, biosamples, and target genes:
uv run scripts/alphagenome_atlas_avi.py query "chr9:128225994:G>A" --include_track_info --format json

# Query multiple variants and export full track info to a file (prevents stdout overflow):
uv run scripts/alphagenome_atlas_avi.py query "chr9:128225994:G>A" "chr22:36201698:A>C" \
  --include_track_info --format json -o query_results.json

• **Output Size & Redirection**: Single variant table/JSON queries are compact

(~1.0–1.5 KB). When querying $>3$ variants or passing `--include_track_info --format json` (which generates ~3.9 KB per variant), **always export directly to a file** using `-o <file.json>` or `-o <file.tsv>` to avoid exceeding context window limits.

• **Typical Runtime**: ~0.5–1.0 s per variant (~12–15 s total including

environment startup). Single calls with $>100$ variants take $>1$ minute.

2. Annotate & Rank Variant Files (`annotate`)

Annotate a VCF (or CSV/TSV/Parquet) in standard Ensembl VEP `CSQ` format:

uv run scripts/alphagenome_atlas_avi.py annotate \
  --input test_data/example_variants.vcf \
  --output annotated_variants.vcf \
  --top_k 20 \
  --min_phred 15.0 \
  --top_output top_variants.json

• **Output Size & Redirection**: `annotate` streams the full callset directly

to disk via `--output` (`.vcf`, `.vcf.gz`, `.parquet`, `.tsv`, `.csv`). Stdout displays a bounded summary (top candidate table + top 3 modality breakdowns, ~4.0–5.5 KB). Use `--top_output <file.json>` when downstream tools need machine-readable top candidate data.

• **Typical Runtime & Callset Scaling**: Throughput is ~10 variants/s

(default) and ~5 variants/s (with track info). Small callsets ($\le 100$ variants) take ~15 s. Callsets $\ge 500$ variants execute silently for $>1$ minute (e.g., 1,000 variants take ~2–3 min; 10,000 variants take ~20 min).

3. Saturation Mutagenesis Window Scan (`region`)

Scan a 1-based closed genomic window (`chr:start-end`) to score all possible single nucleotide substitutions ($3 \times N$ variants for an $N$-bp window):

uv run scripts/alphagenome_atlas_avi.py region \
  --region chr9:128225990-128226000 \
  --min_phred 15.0 \
  --top_k 20 \
  --output region_hotspots.tsv

• **Output Size & Redirection**: Scanning a 100 bp window produces 300 SNVs

(~42 KB TSV / ~105 KB JSON), while a 1,000 bp window produces 3,000 SNVs (~421 KB TSV / ~1.06 MB JSON). **Always specify `--output <file.tsv|parquet>`** to save the complete dataset; stdout will only show a top-20 candidate preview.

• **Typical Runtime**: Queries precomputed dense scores over gRPC in **1.5–3.0

s*