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.
- 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.
- 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.
- 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 for up to 1,000 bp (default
--max_window_size).
4. Inspect Atlas Database Metadata (metadata)
Dump or search registered scorers, the 18 biological feature definitions, or
experimental track catalogs:
# List all registered scorers:
uv run scripts/alphagenome_atlas_avi.py metadata --scorers --format json
# List the 18 biological feature attribution modalities:
uv run scripts/alphagenome_atlas_avi.py metadata --features --format json
# Search experimental tracks by query keyword with a controlled preview (top 20):
uv run scripts/alphagenome_atlas_avi.py metadata --tracks --query "GATA1" --top_n 20
# Dump complete 9,440-track catalog to Parquet or TSV for offline search:
uv run scripts/alphagenome_atlas_avi.py metadata --tracks --output atlas_tracks.parquet
- Output Size & Redirection:
--features (1.3 KB) and --scorers table
(1.7 KB) are safely under 4 KB. The experimental track catalog contains
9,440 tracks (~972 KB table / ~2.55 MB JSON). Never dump unfiltered
tracks to stdout; always supply a narrow --query, specify --top_n 20,
or export to --output atlas_tracks.parquet.
- Typical Runtime: ~1.5–2.5 s.
5. Inspect Gene Structure & Splice Junctions (gtf)
Query GENCODE v46 gene annotations, extract 1-based exon boundaries with
donor/acceptor coordinates, and compute canonical and exon-skipping splice
junction coordinates:
# Query MANE Select exon boundaries for a gene (stdout JSON preview):
uv run scripts/alphagenome_atlas_avi.py gtf --gene CAPN3 --exons --format json
# Query canonical and exon-skipping splice junctions for a variant locus:
uv run scripts/alphagenome_atlas_avi.py gtf --variant "chr15:42387805:C>G" --junctions --format json
# Extract CDS and UTR segments for an Ensembl transcript ID:
uv run scripts/alphagenome_atlas_avi.py gtf --transcript_id ENST00000397163.8 --cds --utr --format json
- Output Size & Redirection: Single-gene MANE Select queries with
--exons are compact
(<2.5 KB). Always export to --output <file.tsv|parquet>or redirect (> gtf_out.json) when passing --all_transcripts(30–500
KB),--region($>50\text{ kb}$),--format json, or querying genes with
$>30$ exons (e.g.TTN, DMD).
- Typical Runtime & Memory: Ingests the 318 MB GENCODE v46 feather dataset
(
4.37 GB RAM). Cached queries execute in **4–6 s**. Cold-start runs
downloading the file from GCS take ~5–10 s on corp/Cloudtop networks,
but can take up to 60–90 s on external networks. Do not kill the process
prematurely during initial download.
Programmatic Python SDK Usage
When querying AlphaGenome programmatically in Python:
- Client Factory: Always instantiate the client using
atlas.create(api_key) — do NOT instantiate atlas.AtlasClient()
directly (which requires an internal gRPC stub).
- Coordinate System:
genome.Interval operates with 0-based half-open
indexing ([start, end)). When querying a 1-based closed interval
chr:start_1_based-end_1_based, pass start = start_1_based - 1 and end = end_1_based.
- Single Variants:
genome.Variant.from_str("chr:pos:ref>alt") expects
1-based position coordinates.
import os
from alphagenome.atlas import atlas
from alphagenome.data import genome
import dotenv
dotenv.load_dotenv(os.path.expanduser('~/.env'))
client = atlas.create(os.environ['ALPHAGENOME_API_KEY'])
# Query 1-based closed interval chr11:5225727-5226575 using 0-based half-open [5225726, 5226575)
interval = genome.Interval(chromosome='chr11', start=5225726, end=5226575)
results = client.query_interval(
interval,
requested_scorers=['AVI_SCORE', 'AVI_SCORE_FEATURE_IMPORTANCE'],
)
# Query single variant with 1-based coordinate
variant = genome.Variant.from_str('chr11:5225488:A>T')
variant_scores = client.query_variant(
variant,
requested_scorers=['AVI_SCORE', 'AVI_SCORE_FEATURE_IMPORTANCE'],
)
Output Schemas & Response Structures
1. VCF CSQ & INFO Tag Schema (annotate)
When writing annotated VCF files, the following annotations are injected:
- Ensembl VEP
CSQ Format String:
Allele|AVI_PHRED|AVI_RAW|AVI_QUANTILE|AVI_TOP_PERCENTILE|AVI_TOP_FEATURE
- Subfield Definitions:
Allele (string): Alternate allele base(s) (e.g. A).
AVI_PHRED (float): Calibrated Phred impact score ($\text{Phred} =
-10 \cdot \log_{10}(1.0 - \text{quantile})$). Range: [0.0, ~70.0].
Higher = greater functional impact.
AVI_RAW (float): Raw continuous model prediction.
AVI_QUANTILE (float): Calibrated tail quantile ($1 - \text{CDF}$).
Range: (0.0, 1.0].
AVI_TOP_PERCENTILE (float): Top percentile of genome-wide SNVs
($10^{-\text{Phred}/10} \times 100%$, e.g. 0.0380 for Top 0.038%).
AVI_TOP_FEATURE (string): Display name of the top contributing
biological modality (e.g. Splicing, AlphaMissense, ChIP-TF,
DNASE-seq, Cactus).
- Standalone INFO Tags (unless
--vep_csq_only): AVI_PHRED=Float,
AVI_RAW=Float, AVI_QUANTILE=Float, AVI_TOP_PERCENTILE=Float,
AVI_TOP_FEATURE=String.
2. Tabular & JSON Record Schema (query, region, --top_output)
Output records exported to JSON, TSV, CSV, or Parquet contain the following
fields:
rank (integer, present in --top_output and region tabular exports):
1-based candidate rank sorted by Phred descending.
variant (string): Genomic variant string in chr:pos_1_based:ref>alt
format (e.g. chr9:128225994:G>A, where coordinate is 1-based).
chromosome (string): Contig name with chr prefix (e.g. chr9).
position (integer): 1-based genomic coordinate.
ref (string): Reference allele base(s).
alt (string): Alternate allele base(s).
avi_phred (float): Calibrated Phred-scaled score.
avi_raw (float): Raw continuous model score.
avi_quantile (float): Tail quantile ($1 - \text{CDF}$).
top_percentile (float): Exact top percentile value (e.g. 0.3421 for
Top 0.34%).
top_modality (string): Display name of the top contributing biological
modality (e.g. Splicing, AlphaMissense, ChIP-TF).
top_feature_importance (float): Attribution weight (SHAP value) of the
top modality.
- Optional Attribution Weights (
--include_features): 18 columns
fi_<MODALITY> (e.g. fi_MERGED_SPLICING, fi_ALPHAMISSENSE,
fi_MAX_ABS_RNA_SEQ, fi_CACTUS_241_WAY).
- Optional Track Provenance (
--include_track_info):
track_idx_<MODALITY>, track_name_<MODALITY>,
track_biosample_<MODALITY>, track_gene_<MODALITY>.
3. GTF Query Schema (gtf)
When querying gene structure with gtf --format json, each transcript object
provides:
- Gene & Transcript Metadata:
gene_name, gene_id, transcript_id,
transcript_type, chromosome, start, end, strand, is_mane_select,
num_exons (coordinates are 1-based closed).
- Exons Array (
--exons):
exon_number (int): 1-based exon index in 5' to 3' transcript order.
start, end, width (int): 1-based closed exon coordinates and
length in bp.
acceptor, donor (int): 1-based 5' splice acceptor and 3' splice
donor coordinates.
overlaps_variant (bool): True if overlapping the query mutation
site.
- Junctions Array (
--junctions):
type (string): Canonical Intron {i} or Exon {k} Skipping.
upstream_exon, downstream_exon (int): 1-based flanking exon
numbers in 5' to 3' transcript order.
junction_start, junction_end (int): 1-based genomic donor and
acceptor coordinates.
intron_length (int): Intron length in bp.
score_id (string): Constructed Atlas track comparison token.
atlas_url (string): Clickable deep-link to Atlas track predictions.
- CDS & UTR Arrays (
--cds, --utr): 1-based closed start, end,
width (int).
Score Metrics & Interpretation
- AVI Phred: Calibrated score (
Phred = -10 * log10(1.0 - quantile)):
Phred >= 40: Top 0.01% predicted impact of all genome-wide SNVs.
Phred >= 30: Top 0.10% predicted impact of all genome-wide SNVs.
Phred >= 20: Top 1.0% predicted impact of all genome-wide SNVs.
Phred >= 15: Top 3.16% predicted impact of all genome-wide SNVs.
Phred >= 10: Top 10.0% predicted impact of all genome-wide SNVs.
Phred < 10: Bottom 90% of all genome-wide SNVs.
- Top Percentile: Exact percentage of genome-wide SNVs with equal or
greater impact:
Top Percentile = 10^(-Phred/10) * 100% (e.g. Phred 29.7
$\implies$ Top 0.11%).
- Top Modality: Leading biological feature attribution (
metadata --features).
Visualizations & Atlas Deep-Linking
[!IMPORTANT] Mandatory Atlas Deep-Linking with Variant Scores: Whenever
reporting, discussing, or displaying an AVI score for a variant (whether for a
single variant query, a ranked candidate table, or a genomic region scan), you
MUST always provide a clickable deep-link to the
AlphaGenome Atlas
for each variant.
- User Context Prioritization: Always prioritize context from the user
first (e.g., disease, tissue, or relevant cell types). When absent, use
--include_track_info with query to discover the driving biosample, cell
line, ontology CURIE, and track index.
- Mandatory Splicing & RNA-seq Co-Plotting Rule: Whenever plotting or
visualizing splicing variants, always plot continuous RNA-seq expression
alongside splicing tracks (
SPLICE_JUNCTIONS, SPLICE_SITE_USAGE,
SPLICE_SITES) to evaluate both structural splice disruption and resulting
transcript abundance changes.
- Atlas Link Construction: Use the
alphagenome-atlas-website-links
skill (scripts/alphagenome_atlas_links.py) for all URL generation,
layout configuration (lItems), biosample filtering (f), and
/atlas/track-predictions comparison chart links.
1---
2name: alphagenome-variant-impact-score
3description: >-
4 Score, annotate, and analyze the functional impact of genetic variants using AlphaGenome Variant Impact
5 (AVI) scores. Query variants in chr:pos:ref>alt format, annotate VCF/tabular callsets, perform
6 saturation mutagenesis window scans (1-based closed chr:start-end), and extract GENCODE v46 GTF
7 gene/exon/junction coordinates all via the AlphaGenome Atlas API.
8metadata:
9 source: https://skillmd.com/skills/google-deepmind/alphagenome-variant-impact-score
10---
11
12# AlphaGenome Variant Impact (AVI) Analysis
13
14Score and prioritize genetic variants using AlphaGenome Variant Impact (AVI)
15models via `scripts/alphagenome_atlas_avi.py`.
16
17> [!IMPORTANT] **Research Use Only & Clinical Safety Rules**: The AlphaGenome
18> AVI Skill and the underlying AlphaGenome model/Atlas are **strictly research
19> tools**. Access to outputs requires an AlphaGenome API key subject to terms of
20> service prohibiting clinical use.
21>
22> 1. **No Medical Advice or Clinical Diagnosis**: You **MUST NOT** provide
23> medical advice, clinical diagnoses, disease management strategies, or
24> treatment recommendations based on outputs from this skill or the
25> AlphaGenome Atlas.
26> 2. **Strict Molecular & Functional Framing**: A high AVI score reflects
27> **predicted molecular/functional impact** (e.g., disruption of splicing,
28> alteration of transcription factor binding, chromatin accessibility
29> changes, or coding consequences). Frame all findings in terms of molecular
30> mechanisms and biological annotations—never as clinical diagnoses or
31> medical conclusions.
32> 3. **No Diagnostic Leaps**: Never extrapolate high functional impact to
33> clinical disease causation, penetrance, or patient prognosis. If a user
34> asks a clinical or diagnostic question, explicitly clarify that
35> AlphaGenome is a research tool and restrict your answer to the predicted
36> molecular and functional effects.
37
38> [!IMPORTANT] **Always Use AlphaGenome GENCODE v46 GTF
39> (`scripts/alphagenome_atlas_avi.py gtf`) for Gene Annotations**: When
40> retrieving gene models, transcript IDs, exon coordinates, CDS/UTR regions, or
41> splice junction donor/acceptor boundaries, **always use the built-in
42> `scripts/alphagenome_atlas_avi.py gtf` command**. Do **NOT** query external
43> sources (e.g., Ensembl REST API, UCSC, external GTF databases, or NCBI) for
44> gene annotations or transcript coordinates. This ensures that the annotations
45> match the scores and website.
46
47--------------------------------------------------------------------------------
48
49## Prerequisites
50
51Run `scripts/alphagenome_atlas_avi.py` using `uv run`:
52
53```bash
54# Display CLI help:
55uv run scripts/alphagenome_atlas_avi.py --help
56```
57
58> [!TIP] **Agent & Programmatic Execution Format**: When invoking the CLI in
59> agent workflows, prefer `--format json` or direct file export (`-o <file>`)
60> for deterministic, structured parsing rather than extracting fields from
61> stdout markdown tables.
62
63### 1. Query Variants (`query`)
64
65Query single or multiple variants in 1-based `chr:pos:ref>alt` format to inspect
66scores and the 18 biological feature attribution weights:
67
68```bash
69# Query single variant with basic feature importances (stdout JSON preview):
70uv run scripts/alphagenome_atlas_avi.py query "chr9:128225994:G>A" --format json
71
72# Query variant with exact underlying Atlas track indices, biosamples, and target genes:
73uv run scripts/alphagenome_atlas_avi.py query "chr9:128225994:G>A" --include_track_info --format json
74
75# Query multiple variants and export full track info to a file (prevents stdout overflow):
76uv run scripts/alphagenome_atlas_avi.py query "chr9:128225994:G>A" "chr22:36201698:A>C" \
77 --include_track_info --format json -o query_results.json
78```
79
80* **Output Size & Redirection**: Single variant table/JSON queries are compact
81 (~1.0–1.5 KB). When querying $>3$ variants or passing `--include_track_info
82 --format json` (which generates ~3.9 KB per variant), **always export
83 directly to a file** using `-o <file.json>` or `-o <file.tsv>` to avoid
84 exceeding context window limits.
85* **Typical Runtime**: ~0.5–1.0 s per variant (~12–15 s total including
86 environment startup). Single calls with $>100$ variants take $>1$ minute.
87
88### 2. Annotate & Rank Variant Files (`annotate`)
89
90Annotate a VCF (or CSV/TSV/Parquet) in standard Ensembl VEP `CSQ` format:
91
92```bash
93uv run scripts/alphagenome_atlas_avi.py annotate \
94 --input test_data/example_variants.vcf \
95 --output annotated_variants.vcf \
96 --top_k 20 \
97 --min_phred 15.0 \
98 --top_output top_variants.json
99```
100
101* **Output Size & Redirection**: `annotate` streams the full callset directly
102 to disk via `--output` (`.vcf`, `.vcf.gz`, `.parquet`, `.tsv`, `.csv`).
103 Stdout displays a bounded summary (top candidate table + top 3 modality
104 breakdowns, ~4.0–5.5 KB). Use `--top_output <file.json>` when downstream
105 tools need machine-readable top candidate data.
106* **Typical Runtime & Callset Scaling**: Throughput is ~10 variants/s
107 (default) and ~5 variants/s (with track info). Small callsets ($\le 100$
108 variants) take ~15 s. Callsets $\ge 500$ variants execute silently for $>1$
109 minute (e.g., 1,000 variants take ~2–3 min; 10,000 variants take ~20 min).
110
111### 3. Saturation Mutagenesis Window Scan (`region`)
112
113Scan a 1-based closed genomic window (`chr:start-end`) to score all possible
114single nucleotide substitutions ($3 \times N$ variants for an $N$-bp window):
115
116```bash
117uv run scripts/alphagenome_atlas_avi.py region \
118 --region chr9:128225990-128226000 \
119 --min_phred 15.0 \
120 --top_k 20 \
121 --output region_hotspots.tsv
122```
123
124* **Output Size & Redirection**: Scanning a 100 bp window produces 300 SNVs
125 (~42 KB TSV / ~105 KB JSON), while a 1,000 bp window produces 3,000 SNVs
126 (~421 KB TSV / ~1.06 MB JSON). **Always specify `--output
127 <file.tsv|parquet>`** to save the complete dataset; stdout will only show a
128 top-20 candidate preview.
129* **Typical Runtime**: Queries precomputed dense scores over gRPC in **1.5–3.0
130 s** for up to 1,000 bp (default `--max_window_size`).
131
132### 4. Inspect Atlas Database Metadata (`metadata`)
133
134Dump or search registered scorers, the 18 biological feature definitions, or
135experimental track catalogs:
136
137```bash
138# List all registered scorers:
139uv run scripts/alphagenome_atlas_avi.py metadata --scorers --format json
140
141# List the 18 biological feature attribution modalities:
142uv run scripts/alphagenome_atlas_avi.py metadata --features --format json
143
144# Search experimental tracks by query keyword with a controlled preview (top 20):
145uv run scripts/alphagenome_atlas_avi.py metadata --tracks --query "GATA1" --top_n 20
146
147# Dump complete 9,440-track catalog to Parquet or TSV for offline search:
148uv run scripts/alphagenome_atlas_avi.py metadata --tracks --output atlas_tracks.parquet
149```
150
151* **Output Size & Redirection**: `--features` (~1.3 KB) and `--scorers` table
152 (~1.7 KB) are safely under 4 KB. The experimental track catalog contains
153 **9,440 tracks** (~972 KB table / ~2.55 MB JSON). **Never dump unfiltered
154 tracks to stdout**; always supply a narrow `--query`, specify `--top_n 20`,
155 or export to `--output atlas_tracks.parquet`.
156* **Typical Runtime**: ~1.5–2.5 s.
157
158### 5. Inspect Gene Structure & Splice Junctions (`gtf`)
159
160Query GENCODE v46 gene annotations, extract 1-based exon boundaries with
161donor/acceptor coordinates, and compute canonical and exon-skipping splice
162junction coordinates:
163
164```bash
165# Query MANE Select exon boundaries for a gene (stdout JSON preview):
166uv run scripts/alphagenome_atlas_avi.py gtf --gene CAPN3 --exons --format json
167
168# Query canonical and exon-skipping splice junctions for a variant locus:
169uv run scripts/alphagenome_atlas_avi.py gtf --variant "chr15:42387805:C>G" --junctions --format json
170
171# Extract CDS and UTR segments for an Ensembl transcript ID:
172uv run scripts/alphagenome_atlas_avi.py gtf --transcript_id ENST00000397163.8 --cds --utr --format json
173```
174
175* **Output Size & Redirection**: Single-gene MANE Select queries with
176 `--exons` are compact
177 (<2.5 KB). **Always export to `--output <file.tsv|parquet>`or redirect (`>
178 gtf_out.json`)** when passing `--all_transcripts`(30–500
179 KB),`--region`($>50\text{ kb}$),`--format json`, or querying genes with
180 $>30$ exons (e.g.`TTN`, `DMD`).
181* **Typical Runtime & Memory**: Ingests the 318 MB GENCODE v46 feather dataset
182 (~4.37 GB RAM). Cached queries execute in **~4–6 s**. Cold-start runs
183 downloading the file from GCS take **~5–10 s** on corp/Cloudtop networks,
184 but can take up to **60–90 s** on external networks. Do not kill the process
185 prematurely during initial download.
186
187--------------------------------------------------------------------------------
188
189## Programmatic Python SDK Usage
190
191When querying AlphaGenome programmatically in Python:
192
1931. **Client Factory**: Always instantiate the client using
194 `atlas.create(api_key)` — do **NOT** instantiate `atlas.AtlasClient()`
195 directly (which requires an internal gRPC stub).
1962. **Coordinate System**: `genome.Interval` operates with **0-based half-open
197 indexing** (`[start, end)`). When querying a 1-based closed interval
198 `chr:start_1_based-end_1_based`, pass `start = start_1_based - 1` and `end =
199 end_1_based`.
2003. **Single Variants**: `genome.Variant.from_str("chr:pos:ref>alt")` expects
201 **1-based** position coordinates.
202
203```python
204import os
205from alphagenome.atlas import atlas
206from alphagenome.data import genome
207import dotenv
208
209dotenv.load_dotenv(os.path.expanduser('~/.env'))
210client = atlas.create(os.environ['ALPHAGENOME_API_KEY'])
211
212# Query 1-based closed interval chr11:5225727-5226575 using 0-based half-open [5225726, 5226575)
213interval = genome.Interval(chromosome='chr11', start=5225726, end=5226575)
214results = client.query_interval(
215 interval,
216 requested_scorers=['AVI_SCORE', 'AVI_SCORE_FEATURE_IMPORTANCE'],
217)
218
219# Query single variant with 1-based coordinate
220variant = genome.Variant.from_str('chr11:5225488:A>T')
221variant_scores = client.query_variant(
222 variant,
223 requested_scorers=['AVI_SCORE', 'AVI_SCORE_FEATURE_IMPORTANCE'],
224)
225```
226
227--------------------------------------------------------------------------------
228
229## Output Schemas & Response Structures
230
231### 1. VCF CSQ & INFO Tag Schema (`annotate`)
232
233When writing annotated VCF files, the following annotations are injected:
234
235* **Ensembl VEP `CSQ` Format String**:
236 `Allele|AVI_PHRED|AVI_RAW|AVI_QUANTILE|AVI_TOP_PERCENTILE|AVI_TOP_FEATURE`
237* **Subfield Definitions**:
238 * `Allele` (*string*): Alternate allele base(s) (e.g. `A`).
239 * `AVI_PHRED` (*float*): Calibrated Phred impact score ($\text{Phred} =
240 -10 \cdot \log_{10}(1.0 - \text{quantile})$). Range: `[0.0, ~70.0]`.
241 Higher = greater functional impact.
242 * `AVI_RAW` (*float*): Raw continuous model prediction.
243 * `AVI_QUANTILE` (*float*): Calibrated tail quantile ($1 - \text{CDF}$).
244 Range: `(0.0, 1.0]`.
245 * `AVI_TOP_PERCENTILE` (*float*): Top percentile of genome-wide SNVs
246 ($10^{-\text{Phred}/10} \times 100\%$, e.g. `0.0380` for Top 0.038%).
247 * `AVI_TOP_FEATURE` (*string*): Display name of the top contributing
248 biological modality (e.g. `Splicing`, `AlphaMissense`, `ChIP-TF`,
249 `DNASE-seq`, `Cactus`).
250* **Standalone INFO Tags** (unless `--vep_csq_only`): `AVI_PHRED=Float`,
251 `AVI_RAW=Float`, `AVI_QUANTILE=Float`, `AVI_TOP_PERCENTILE=Float`,
252 `AVI_TOP_FEATURE=String`.
253
254### 2. Tabular & JSON Record Schema (`query`, `region`, `--top_output`)
255
256Output records exported to JSON, TSV, CSV, or Parquet contain the following
257fields:
258
259* `rank` (*integer*, present in `--top_output` and `region` tabular exports):
260 1-based candidate rank sorted by Phred descending.
261* `variant` (*string*): Genomic variant string in `chr:pos_1_based:ref>alt`
262 format (e.g. `chr9:128225994:G>A`, where coordinate is 1-based).
263* `chromosome` (*string*): Contig name with `chr` prefix (e.g. `chr9`).
264* `position` (*integer*): 1-based genomic coordinate.
265* `ref` (*string*): Reference allele base(s).
266* `alt` (*string*): Alternate allele base(s).
267* `avi_phred` (*float*): Calibrated Phred-scaled score.
268* `avi_raw` (*float*): Raw continuous model score.
269* `avi_quantile` (*float*): Tail quantile ($1 - \text{CDF}$).
270* `top_percentile` (*float*): Exact top percentile value (e.g. `0.3421` for
271 Top 0.34%).
272* `top_modality` (*string*): Display name of the top contributing biological
273 modality (e.g. `Splicing`, `AlphaMissense`, `ChIP-TF`).
274* `top_feature_importance` (*float*): Attribution weight (SHAP value) of the
275 top modality.
276* **Optional Attribution Weights (`--include_features`)**: 18 columns
277 `fi_<MODALITY>` (e.g. `fi_MERGED_SPLICING`, `fi_ALPHAMISSENSE`,
278 `fi_MAX_ABS_RNA_SEQ`, `fi_CACTUS_241_WAY`).
279* **Optional Track Provenance (`--include_track_info`)**:
280 `track_idx_<MODALITY>`, `track_name_<MODALITY>`,
281 `track_biosample_<MODALITY>`, `track_gene_<MODALITY>`.
282
283### 3. GTF Query Schema (`gtf`)
284
285When querying gene structure with `gtf --format json`, each transcript object
286provides:
287
288* **Gene & Transcript Metadata**: `gene_name`, `gene_id`, `transcript_id`,
289 `transcript_type`, `chromosome`, `start`, `end`, `strand`, `is_mane_select`,
290 `num_exons` (coordinates are 1-based closed).
291* **Exons Array (`--exons`)**:
292 * `exon_number` (*int*): 1-based exon index in 5' to 3' transcript order.
293 * `start`, `end`, `width` (*int*): 1-based closed exon coordinates and
294 length in bp.
295 * `acceptor`, `donor` (*int*): 1-based 5' splice acceptor and 3' splice
296 donor coordinates.
297 * `overlaps_variant` (*bool*): True if overlapping the query mutation
298 site.
299* **Junctions Array (`--junctions`)**:
300 * `type` (*string*): `Canonical Intron {i}` or `Exon {k} Skipping`.
301 * `upstream_exon`, `downstream_exon` (*int*): 1-based flanking exon
302 numbers in 5' to 3' transcript order.
303 * `junction_start`, `junction_end` (*int*): 1-based genomic donor and
304 acceptor coordinates.
305 * `intron_length` (*int*): Intron length in bp.
306 * `score_id` (*string*): Constructed Atlas track comparison token.
307 * `atlas_url` (*string*): Clickable deep-link to Atlas track predictions.
308* **CDS & UTR Arrays (`--cds`, `--utr`)**: 1-based closed `start`, `end`,
309 `width` (*int*).
310
311--------------------------------------------------------------------------------
312
313## Score Metrics & Interpretation
314
315* **AVI Phred**: Calibrated score (`Phred = -10 * log10(1.0 - quantile)`):
316 * `Phred >= 40`: **Top 0.01%** predicted impact of all genome-wide SNVs.
317 * `Phred >= 30`: **Top 0.10%** predicted impact of all genome-wide SNVs.
318 * `Phred >= 20`: **Top 1.0%** predicted impact of all genome-wide SNVs.
319 * `Phred >= 15`: **Top 3.16%** predicted impact of all genome-wide SNVs.
320 * `Phred >= 10`: **Top 10.0%** predicted impact of all genome-wide SNVs.
321 * `Phred < 10`: **Bottom 90%** of all genome-wide SNVs.
322* **Top Percentile**: Exact percentage of genome-wide SNVs with equal or
323 greater impact: `Top Percentile = 10^(-Phred/10) * 100%` (e.g. Phred 29.7
324 $\implies$ Top 0.11%).
325* **Top Modality**: Leading biological feature attribution (`metadata
326 --features`).
327
328--------------------------------------------------------------------------------
329
330## Visualizations & Atlas Deep-Linking
331
332> [!IMPORTANT] **Mandatory Atlas Deep-Linking with Variant Scores**: Whenever
333> reporting, discussing, or displaying an AVI score for a variant (whether for a
334> single variant query, a ranked candidate table, or a genomic region scan), you
335> **MUST always provide a clickable deep-link to the
336> [AlphaGenome Atlas](https://deepmind.google.com/science/alphagenome/atlas)**
337> for each variant.
338
3391. **User Context Prioritization**: Always prioritize **context from the user
340 first** (e.g., disease, tissue, or relevant cell types). When absent, use
341 `--include_track_info` with `query` to discover the driving biosample, cell
342 line, ontology CURIE, and track index.
3432. **Mandatory Splicing & RNA-seq Co-Plotting Rule**: Whenever plotting or
344 visualizing splicing variants, **always plot continuous RNA-seq expression
345 alongside splicing tracks** (`SPLICE_JUNCTIONS`, `SPLICE_SITE_USAGE`,
346 `SPLICE_SITES`) to evaluate both structural splice disruption and resulting
347 transcript abundance changes.
3483. **Atlas Link Construction**: Use the **`alphagenome-atlas-website-links`
349 skill** (`scripts/alphagenome_atlas_links.py`) for all URL generation,
350 layout configuration (`lItems`), biosample filtering (`f`), and
351 `/atlas/track-predictions` comparison chart links.