Alphagenome Single Variant Analysis

Variant Analysis using AlphaGenome

Prerequisites

1. `uv`: Read the uv skill and follow its Setup instructions to ensure uv is installed and on PATH. 2. User Notification: If LICENSE_NOTIFICATION.txt does not already exist in this skill directory then (1) prominently notify the user to check the terms at https://deepmind.google.com/science/alphagenome/, then (2) create the file recording the notification text and timestamp. 3. `.env` file: Make sure the .env file exists in your home directory. Create one if it does not exist. 4. `ALPHAGENOME_API_KEY`: This skill requires an API key to function. You must ask the user for an API key if this skill looks relevant to their request and you do not have one in .env. The user can sign up at https://deepmind.google.com/science/alphagenome/. Do NOT ask the user to paste their key into the chat (this would leak the key into the agent's context). Instead, explain that a key is necessary to use AlphaGenome and give the user this command substituting `ENV_FILE` with the resolved literal path to the `.env` file:

    printf "Enter AlphaGenome API key (typing hidden): " && read -s key && echo && echo "ALPHAGENOME_API_KEY=$key" >> "ENV_FILE" && echo "Saved."

The scripts load credentials automatically via dotenv. NEVER read, print, or inspect the .env file or its variables (e.g. no cat, grep, echo, printenv, or os.environ.get on keys). Credentials must stay out of the agent's context.

When running in sandbox, dotenv.load_dotenv() will be a no-op, and instead the sandbox will read credentials and inject them directly.

Core Rules

• NEVER run `python3` or `python3 -c` directly. The system Python does not

necessarily have pandas, numpy, and other key dependencies. ALWAYS use uv run to run ALL Python code — including scripts, ad-hoc analysis files, and one-liners. Do not attempt to pip install or create new venvs — uv manages an isolated environment automatically.

• Offline Only: NEVER use external APIs (e.g., MyGene.info, Ensembl REST)

for gene/transcript lookup. Use lookup_gene_info.py with the local GTF. If it fails, fix the environment/paths, do not switch to external APIs.

• API Key is required: ALPHAGENOME_API_KEY must be set before running

any script (in sandbox, credentials are injected automatically).

• Notification: If this skill is used, ensure this is mentioned in the

output.

• Report Format: Always use the templates in docs/report-templates.md

for generating analysis reports, and ensure to include the table of top hits from the discovery scan.

Environment Setup & Troubleshooting

Python Environment

All scripts must be executed using uv run, which manages an isolated virtual environment with the correct dependencies via uv.

uv run <script_name> [args...]

For ad-hoc scripts (e.g., inline analysis code saved to a temp file), pass the full path instead of a short name:

uv run --project $SKILL_DIR /tmp/my_analysis.py --arg1 val1

[!NOTE] The first invocation resolves and installs dependencies (~10s).

Subsequent runs use the cached environment and start instantly. The cache

lives in ~/.cache/uv/.

Common Issues

• Column Names: tidy_scores and metadata often use gene_name (not

gene_symbol) and output_type (not modality). Always inspect df.columns before filtering.

• Large Genes: Genes > 500kb (e.g., USH2A) break the whole_gene view.

Use --view detail or manual regional windows instead.

• Sashimi Strand Error: plot_components.Sashimi does NOT accept a

strand argument directly. Filter input tracks instead.

• KeyError: 'ontology_curie': Not all tracks have ontology_curie. Check

track.metadata.columns before filtering.

• Python Path: If exec: "python": executable file not found occurs,

ensure you are using uv run instead of bare python/python3.

• NotImplementedError (pandas): "iLocation based boolean indexing on an

integer type is not available". This occurs when using boolean masks with .iloc on integer-indexed DataFrames in newer pandas versions. Fix: Convert boolean masks to integer indices using np.flatnonzero(mask).

• GTF Feather Case Sensitivity: The AlphaGenome GTF Feather file uses

Capitalized column names (Feature, Start, End, Strand) unlike standard GTF files. Always check df.columns if getting KeyErrors.

• `score_variant` ontology filtering: score_variant does NOT accept

ontology_terms as an argument. You must filter the returned AnnData objects manually by inspecting adata.var columns. In contrast, predict_variant DOES accept ontology_terms directly.

• Sashimi Zoom Logic: To ensure "skipping" arcs are visible, expand the

zoom to include the flanking exons rather than relying on junction overlap alone.

• Junction Scores: Raw Junction objects from prediction may be simple

Intervals. Use junction_data.get_junctions_to_plot(predictions=..., name=...) to retrieve objects with the .k (abundance/score) attribute.

• `uv` Not Found: If exec: uv: not found, follow the installation

instructions in Prerequisites.

• Registry Authentication Error (401): If uv fails with 401 Unauthorized

for a private registry, set UV_INDEX_URL=https://pypi.org/simple before running the script.

References

• alphagenome-api.md — API reference and code

patterns

• interpretation-guide.md — Interpretation

guide, score magnitude rules, ISM, and checklist.

• report-templates.md — Full report templates
• `scripts/visualize_variant_effects.py`

— Single-variant visualization template (Ref/Alt comparisons, Splicing).

• Splicing Zoom Strategy: Uses a Hybrid Approach for optimal

visibility: 1. Base Interval: Variant +/- 1 downstream and upstream exon (Structural Context). 2. Junction Expansion: Expands to include the full span of any significant splicing junction (e.g., exon skipping events that span multiple exons). 3. Anchor Enforcement: Ensures the exons anchoring these long junctions are fully visible. Lesson: Simple fixed windows (e.g., 2kb) or nearest-exon logic often fail for skipping events. Always use the observed junction data to drive zoom levels.

• `examples/splicing/` — Splicing analysis examples
• `examples/model_limitation_RNU4ATAC/`

— ncRNA structure limitation case study

• `examples/polyadenylation_HBA2/` — 3'

UTR / Polyadenylation case study

• `examples/regulatory/` — Regulatory variant

examples

• `examples/negative_result_GATA4/` —

Negative results (mathematical artefact)

• `examples/negative_result_TGFB3/` —

Negative results (proxies)

• `scripts/lookup_gene_info.py` — Gene &

transcript lookup

• `scripts/resolve_ontology_terms.py` —

Ontology term resolution (UBERON/CL IDs)

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

Code Patterns

Broad Discovery Scan

Use score_variant across differential scorers only to discover unexpected tissue effects.

from alphagenome.models import dna_client
from alphagenome.models import variant_scorers
from alphagenome.data import genome
import os
import pandas as pd

# Setup API Key and Client
dna_model = dna_client.create(api_key=os.environ.get('ALPHAGENOME_API_KEY'),
                              address='dns:///gdmscience.googleapis.com:443')

# Define Variant (example)
variant_str = "chr2:1234:A>C"
chrom, pos_str, ref_alt = variant_str.split(':')
ref, alt = ref_alt.split('>')
pos = int(pos_str)

# Use supported sequence length (e.g., 2**20 for optimal performance)
SEQ_LENGTH = 2**20
interval = genome.Interval(chrom, pos - SEQ_LENGTH // 2, pos + SEQ_LENGTH // 2)
variant = genome.Variant(chrom, pos, ref, alt)

scorers = [
    variant_scorers.RECOMMENDED_VARIANT_SCORERS[m]
    for m in variant_scorers.RECOMMENDED_VARIANT_SCORERS
    if "ACTIVE" not in m and "CAGE" not in m and "PROCAP" not in m
]

print(f"Scoring variant {variant_str}...")
scores_list = dna_model.score_variant(interval=interval, variant=variant, variant_scorers=scorers)

# Process and Display Results
all_dfs = []
for score_adata in scores_list:
    df = variant_scorers.tidy_scores([score_adata], match_gene_strand=True)
    if df is not None:
        all_dfs.append(df)

if all_dfs:
    df = pd.concat(all_dfs)
    significant = df[df['quantile_score'].abs() > 0.995]
    ranked = significant.sort_values('raw_score', key=abs, ascending=False)
    print("Top Significant Hits:")
    print(ranked[['biosample_name', 'gene_name', 'output_type', 'quantile_score', 'raw_score']])

Extended Search for Disease-Relevant Tissues

# Define keywords based on disease context
disease_keywords = ["liver", "hepatocyte"]

# Filter for any match
mask = df['biosample_name'].str.contains('|'.join(disease_keywords), case=False, na=False)

relevant_hits = df[mask].sort_values('raw_score', key=abs, ascending=False)
print(f"\n--- Extended Analysis (Keywords: {disease_keywords}) ---")
print(relevant_hits.head(20)[['biosample_name', 'output_type', 'raw_score', 'quantile_score']])

Workflow Checklist

Variant Analysis Progress:
- [ ] Step 0: Review Golden Examples (MANDATORY)
- [ ] Step 1: Create Output Folder and Setup
- [ ] Step 2: Parse User Query & Research
- [ ] Step 3: Resolve Tissues & Modalities
- [ ] Step 4: Visualize & Save Plots
- [ ] Step 5: Analyze Predictions (view plots, no code). MANDATORY: Read [interpretation-guide.md](docs/interpretation-guide.md) before interpreting results.
- [ ] Step 6: Write Report, save it as `report.md` (MANDATORY)
- [ ] Step 7: Self-Critique (view `report.md` to verify links & claims)
- [ ] Step 8: Make artifact out of `report.md`

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

Multi-Variant Workflow

If multiple variants are specified, spawn sub-agents to run each variant analysis and then synthesize each report.md into a single report.

Script Reference

: : GTF data : | resolve_ontology_terms | Biological terms → UBERON/CL/EFO IDs | | visualize_variant_effects | REF/ALT visualization (expression, regulatory, | : : splicing) : | analyze_ism | In-Silico Mutagenesis SeqLogo generation | | interpret_splicing | Quantitative splicing analysis (delta scores, | : : junctions) : | visualize_genome_tracks | Genomic track visualization for a region |

AlphaGenome API Reference

Pip package: alphagenome

Setup and Imports

Standard imports for AlphaGenome workflows:

from alphagenome.data import gene_annotation
from alphagenome.data import genome
from alphagenome.data import track_data
from alphagenome.data import transcript as transcript_utils
from alphagenome.interpretation import ism
from alphagenome.models import dna_client
from alphagenome.models import variant_scorers
from alphagenome.visualization import plot_components
import matplotlib.pyplot as plt
import pandas as pd

Client Initialization

The API key is automatically loaded by dotenv from the .env file in the agent configuration dir.

To initialize a client:

from alphagenome.models import dna_client

dna_model = dna_client.create(
    api_key=os.environ.get('ALPHAGENOME_API_KEY'),
    address='dns:///gdmscience.googleapis.com:443',
)

Core Data Types

genome.Interval

0-based half-open interval (includes start, excludes end).

interval = genome.Interval(chromosome='chr1', start=1_000, end=1_010)

interval.center()     # Returns center position (int)
interval.width        # Returns 10
interval.resize(100)  # Resizes around center
interval.overlaps(other_interval)
interval.contains(other_interval)
interval.intersect(other_interval)

genome.Variant

Position is 1-based (VCF-compatible).

variant = genome.Variant(
    chromosome='chr22',
    position=36201698,  # 1-based!
    reference_bases='A',
    alternate_bases='C',
)
# Get interval around variant
interval = variant.reference_interval.resize(dna_client.SEQUENCE_LENGTH_1MB)

Predictions

Predict from DNA Sequence

output = dna_model.predict_sequence(
    sequence='GATTACA'.center(dna_client.SEQUENCE_LENGTH_1MB, 'N'),
    requested_outputs=[dna_client.OutputType.DNASE],
    ontology_terms=['UBERON:0002048'],  # Lung
)
# Access predictions
print(output.dnase.values.shape)  # (sequence_length, num_tracks)
print(output.dnase.metadata)      # Track metadata DataFrame

Predict from Genome Interval

interval = genome.Interval('chr1', 1000000, 1000001)
interval = interval.resize(dna_client.SEQUENCE_LENGTH_1MB)

output = dna_model.predict_interval(
    interval=interval,
    requested_outputs=[dna_client.OutputType.RNA_SEQ],
    ontology_terms=['UBERON:0001114'],  # Right liver lobe
)

Mouse Predictions

Specify organism=dna_client.Organism.MUS_MUSCULUS for mouse models.

output = dna_model.predict_sequence(
    ...,
    organism=dna_client.Organism.MUS_MUSCULUS,
)

Variant Analysis

Predict Variant Effects (Raw Tracks)

Compare predictions for Reference (REF) vs Alternate (ALT) alleles.

variant_output = dna_model.predict_variant(
    interval=interval,
    variant=variant,
    requested_outputs=[dna_client.OutputType.RNA_SEQ],
    ontology_terms=['UBERON:0001157'],  # Colon - Transverse
)

ref_tracks = variant_output.reference.rna_seq
alt_tracks = variant_output.alternate.rna_seq

Score Variants (Aggregated Scores)

Get aggregated scores using recommended scorers.

scorer = variant_scorers.RECOMMENDED_VARIANT_SCORERS['RNA_SEQ']

variant_scores_list = dna_model.score_variant(
    interval=interval,
    variant=variant,
    variant_scorers=[scorer],
)
scores = variant_scores_list[0]

# Tidy scores to DataFrame
df = variant_scorers.tidy_scores([scores], match_gene_strand=True)
print(df[['gene_symbol', 'raw_score', 'quantile_score']])

Available recommended scorers: ATAC, CAGE, DNASE, PROCAP, RNA_SEQ, CHIP_TF, CHIP_HISTONE, SPLICE_SITES, SPLICE_SITE_USAGE, SPLICE_JUNCTIONS, POLYADENYLATION, CONTACT_MAPS

Batch Variant Scoring

# Parse variants from VCF-like DataFrame
for _, row in vcf_df.iterrows():
    variant = genome.Variant(
        chromosome=str(row.CHROM),
        position=int(row.POS),
        reference_bases=row.REF,
        alternate_bases=row.ALT,
    )
    interval = variant.reference_interval.resize(
        dna_client.SEQUENCE_LENGTH_1MB
    )
    scores = dna_model.score_variant(
        interval=interval,
        variant=variant,
        variant_scorers=list(
            variant_scorers.RECOMMENDED_VARIANT_SCORERS.values()
        ),
    )

In Silico Mutagenesis (ISM)

Systematically mutate a region to find important motifs.

from alphagenome.interpretation import ism

sequence_interval = genome.Interval(
    'chr20', 3_753_000, 3_753_400
).resize(dna_client.SEQUENCE_LENGTH_16KB)
ism_interval = sequence_interval.resize(256)  # Mutate center 256bp

scorer = variant_scorers.CenterMaskScorer(
    requested_output=dna_client.OutputType.DNASE,
    width=501,
    aggregation_type=variant_scorers.AggregationType.DIFF_MEAN,
)

variant_scores = dna_model.score_ism_variants(
    interval=sequence_interval,
    ism_interval=ism_interval,
    variant_scorers=[scorer],
)

TrackData Operations

Properties

tdata = output.dnase
tdata.values      # numpy array (sequence_length, num_tracks)
tdata.metadata    # pandas DataFrame with track info
tdata.resolution  # bp per position
tdata.interval    # genome.Interval

Filtering by Strand

pos_tracks = tdata.filter_to_positive_strand()
neg_tracks = tdata.filter_to_negative_strand()
unstranded = tdata.filter_to_unstranded()

Filtering by Track Name

track1_tdata = tdata.select_tracks_by_name(names='track1')

Filtering by Metadata (Manual)

mask = tracks.metadata['histone_mark'] == 'H3K27ac'
filtered_tracks = track_data.TrackData(
    values=tracks.values[:, mask],
    metadata=tracks.metadata[mask],
    resolution=tracks.resolution,
    interval=tracks.interval,
    uns=tracks.uns,
)

Slicing

# By position indices
tdata.slice_by_positions(start=2, end=4)

# By genomic interval
tdata.slice_by_interval(
    genome.Interval(chromosome='chr1', start=1_002, end=1_004)
)

Resizing

tdata.resize(width=2)  # Crop to center 2 positions
tdata.resize(width=8)  # Pad with zeros

Resolution Conversion

tdata.change_resolution(resolution=128)  # Downsample
tdata.change_resolution(resolution=1)    # Upsample

Track Metadata Reference

[!CAUTION] CHIP_HISTONE uses histone_mark, NOT target. target is for

CHIP_TF.

Visualization

plot_components.plot(
    components=[
        plot_components.TranscriptAnnotation(transcripts),
        plot_components.Tracks(output.rna_seq),
        plot_components.OverlaidTracks(
            tdata={'REF': ref_tracks, 'ALT': alt_tracks},
            colors={'REF': 'dimgrey', 'ALT': 'red'},
        ),
    ],
    interval=interval,
    annotations=[plot_components.VariantAnnotation([variant], alpha=0.8)],
)
plt.show()

[!CAUTION] VariantAnnotation must be in annotations=, NOT components.

Putting it in components causes `AttributeError: 'VariantAnnotation' object

has no attribute 'num_axes'`.

Get Human-Readable Tissue Names

tissue = tracks.metadata[
    tracks.metadata['ontology_curie'] == ontology_id
]['biosample_name'].iloc[0]
plt.title(f"{gene_symbol} - {tissue} - {modality.name}")

Gene Annotations (GTF)

gtf = pd.read_feather(
    'https://storage.googleapis.com/alphagenome/reference/gencode/'
    'hg38/gencode.v46.annotation.gtf.gz.feather'
)

# Filter for MANE Select transcripts
gtf_transcripts = gene_annotation.filter_protein_coding(gtf)
gtf_transcripts = gene_annotation.filter_to_mane_select_transcript(
    gtf_transcripts
)

# Get stranded interval for a gene
interval = gene_annotation.get_gene_interval(gtf, gene_symbol='CYP2B6')

GTF feather uses capitalized column names for core fields:

Other columns (gene_name, gene_id, gene_type) remain lowercase.

Best Practices

1. Interval Resizing: Always resize to a supported length before prediction. Use dna_client.SUPPORTED_SEQUENCE_LENGTHS.keys() for options.

2. Efficient Predictions: Always specify requested_outputs and ontology_terms to reduce compute and data transfer.

3. Variant Scoring: Use tidy_scores(..., match_gene_strand=True) to filter irrelevant strand matches. quantile_score allows comparison across different scorers.

4. ISM: Expensive (scores 3 variants per position). Use shorter context intervals (16KB) and narrower mutation regions.

5. Saving Figures: Use plt.savefig('plot.png', bbox_inches='tight') to prevent cut-off labels.

Common Pitfalls

OverlaidTracks has no title argument

# Wrong:
plot_components.OverlaidTracks(..., title="My Title")  # ERROR!

# Correct:
plot_components.plot([plot_components.OverlaidTracks(...)], interval=...)
plt.suptitle("My Title")

TrackData has no subset() method

Use manual filtering with boolean masks on metadata, or use select_tracks_by_name() for name-based selection.

uv run fails

Clear the cached environment and retry: uv cache clean && uv run <script_name>. If the issue persists, check that pyproject.toml exists in the skill root and contains alphagenome>=0.6.1 in dependencies.

Client initialization needs correct address

Always use the production address for API access: address='dns:///gdmscience.googleapis.com:443'

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

Output Types

Defined as dna_client.OutputType, used in requested_outputs:

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

Variant Scoring Details

Gene Expression (RNA-seq)

Quantifies impact on overall gene transcript abundance.

• Comparison: Predicted RNA coverage between REF and ALT alleles.
• Mask: Exons for a gene of interest.
• Aggregation: Log-fold change: `log(mean(ALT) + 0.001) - log(mean(REF) +

0.001)`.

Polyadenylation Site (PAS) Usage

Captures variant's impact on RNA isoform production (paQTLs).

• Mask: Local 400bp windows around 3' cleavage junctions.
• Aggregation: Maximum absolute log-fold change of isoform ratios

(distal/proximal PAS usage).

TSS Activity (CAGE, PRO-cap)

Quantifies local changes at TSSs.

• Mask: Local 501bp window centered at variant.
• Aggregation: log2[(sum(ALT) + 1) / (sum(REF) + 1)].

Chromatin Accessibility (ATAC-seq, DNase-seq)

• Mask: Local 501bp window centered at variant.
• Aggregation: log2[(sum(ALT) + 1) / (sum(REF) + 1)].

Transcription Factor Binding (ChIP-TF)

• Mask: Local 501bp window centered at variant.
• Aggregation: log2[(sum(ALT) + 1) / (sum(REF) + 1)].

Histone Modifications (ChIP-Histone)

• Mask: Local 2001bp window centered at variant.
• Aggregation: log2[(sum(ALT) + 1) / (sum(REF) + 1)].

Splicing (Splice Sites)

Changes in class assignment probabilities (acceptor, donor) across gene body.

• Aggregation: max(|ALT - REF|) across gene body.

Splicing (Splice Site Usage)

Changes in fraction of splice site usage.

• Aggregation: max(|ALT - REF|) across gene body.

Splicing (Splice Junctions)

Changes in predicted RNA-seq reads spanning junctions.

• Aggregation: max(|log(ALT) - log(REF)|) across splice site pairs.

3D Genome Contact (Contact Maps)

Local contact disruption.

• Mask: Local 1MB window centered at variant.
• Aggregation: Mean absolute difference of contact frequencies for

variant-containing bin.

Active Allele Scorers

Capture absolute activity level (not REF/ALT difference): max(aggregated_signal(ALT), aggregated_signal(REF)) over masked region.

Quantile Scores

Quantile scores are empirical percentile ranks vs common variants (MAF>0.01 in gnomAD v3). A quantile of 0.99 means the score is at the 99th percentile. Maximum value is ±0.999990 (~300K variant background). For signed scorers, quantiles are linearly mapped to [-1, 1] to preserve directionality.

Practical rule: Use quantile as significance indicator; use raw_score for magnitude comparison within the same scorer.

Example: Model Limitation (RNA Secondary Structure)

Variant: chr2:121530927:G>A Gene: RNU4ATAC (U4atac snRNA) Phenotype: Roifman Syndrome Mechanism: RNA Secondary Structure / Stability (Post-Transcriptional)

Why this is a Critical Example

This analysis illustrates a specific Blind Spot of the model:

1. The Signal: The variant has High Quantiles (0.998) but Low Raw Scores (~0.01). 2. The Reality: A high quantile with a near-zero raw score typically reflects low variance in the model's background predictions for that track—it is a statistical artifact, not a meaningful biological signal. Furthermore, the model does not simulate the physical folding of the RNA molecule. 3. True Mechanism: Variants in snRNAs often affect secondary structure/folding, preventing proper spliceosome assembly. This is a post-transcriptional physics problem, not a DNA-to-RNA transcription problem.

Key Takeaway

AlphaGenome is a DNA-to-Expression model, not an RNA Folding model.

• If the agent is analyzing an ncRNA (snRNA, tRNA, rRNA), it must

acknowledge that AlphaGenome predicts transcription from DNA, but does not simulate post-transcriptional RNA folding or secondary structure stability.

• Strict Rule: A pattern of High Quantile + Low Raw Score should be

reported as "No Significant Molecular Effect Predicted by AlphaGenome". Do not invent proxy mechanisms (e.g., "structural importance") based on statistical artifacts.

• Do not over-interpret "Regulatory" scores for mechanisms that occur after

transcription. The true pathogenic mechanism (e.g., RNA folding defect) is likely invisible to the model.

Variant Analysis Report: chr2:121530927:G>A (RNU4ATAC)

Summary

The variant chr2:121530927:G>A is located in the *RNU4ATAC gene, an snRNA associated with Roifman syndrome. AlphaGenome analysis identified a "High Quantile" signal in RNA-seq models (e.g., Skeletal Muscle). However, the absolute magnitude of this change (Raw Score ~0.01) is negligible. This pattern of high quantiles and near-zero raw scores is typically a statistical artifact driven by low variance in the model's background predictions for that track. Furthermore, the true disease mechanism of RNU4ATAC variants involves post-transcriptional RNA folding and secondary structure stability, which AlphaGenome does not* simulate. Therefore, no significant molecular effect is predicted by the model.

Genomic Context

• Variant: chr2:121530927:G>A
• Overlapping Gene: RNU4ATAC (U4atac snRNA)
• Disease Association: Roifman Syndrome
• Mechanism: RNA Secondary Structure / Stability

1. Top Discovery Hits (Statistical Artifact)

High quantiles but negligible raw scores indicate lack of strong functional driver.

Observations:

• Magnitude: Raw scores are ~0.01, well below the threshold of biological

relevance.

• Quantile Inflation: The high quantiles likely reflect low variance in

the model background, where even tiny deviations are "rare" but not impactful.

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

Plots and Visual Analysis

Whole-Gene Expression View

!Whole-Gene View

Visual Observation:

• Overview: The macro-scale expression profile of RNU4ATAC remains

virtually identical between REF and ALT.

Regulatory Effects: Skeletal Muscle

!Regulatory Effects

Visual Observation:

• Broader Context: The broader regulatory context shows no loss or gain of

distinct promoter or enhancer peaks.

Detail View (+/- 50bp)

!Detail View

Visual Observation (Zoomed):

• Variant Site: Zooming in reveals that the absolute magnitude of change

predicted by the model is negligible, visually confirming that the "High Quantile" flag represents noise rather than a major disruption.

Comparative ISM Analysis

!ISM SeqLogo

Interpretation:

• Motif Stability: The ISM matrix lacks the characteristic strong,

isolated motif disruption that defines definitive regulatory variants, further supporting the "statistical artifact" diagnosis.

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

Conclusion

AlphaGenome predicts no significant molecular effect for chr2:121530927:G>A in RNU4ATAC. The "significant" quantile hits reported by the model are statistical artifacts tracking near-zero raw score variations. Because RNU4ATAC is an snRNA, the true disease mechanism likely involves macromolecular folding defects post-transcription. AlphaGenome is a DNA-to-Expression model and cannot simulate RNA folding.

Recommendation: Assess predictions with RNA secondary structure tooling; do not rely on proxy regulatory scores from AlphaGenome.

Example: True Negative Result (GATA4 / VSD)

Variant: chr8:11703860:G>T Phenotype: Ventricular Septal Defect (Alleged) Verdict: Likely Benign / No Functional Effect

Why this is a good example

This analysis demonstrates a True Negative result where:

1. Statistical Artefacts: The Discovery Scan reported high quantiles (~0.99) for Heart RNA-seq, which can be misleading. 2. Magnitude Check: The Raw Scores were negligible (~0.01 or <1% change), revealing the "significance" was likely due to low variance in the model background rather than true biological impact. 3. Visual Confirmation:

• Whole-Gene Plot: Shows identical REF/ALT expression profiles.
• Detail Plot: Shows preserved chromatin accessibility (DNASE) at the

variant site.

• ISM: Shows minimal motif disruption logic.

Key Takeaway

Always verify statistically significant hits (High Quantile) with Magnitude (Raw Score) and Visual Inspection. If the raw score is low and the plot shows no change, the Quantile is a false alarm.

Variant Analysis Report: chr8:11703860:G>T

Summary

The variant chr8:11703860:G>T is implicated in Ventricular Septal Defect (VSD) and located in/near the * GATA4 gene. AlphaGenome analysis predicted no significant molecular impact* in Heart tissues. While some RNA-seq scores achieve high statistical quantiles (0.99), the absolute magnitude of change is negligible (<1% change, raw score ~ -0.01), suggesting these are likely background noise rather than functional biological effects. No evidence of splicing disruption, promoter loss, or enhanceosome destabilization was found in the modeled tissues.

Genomic Context

• Variant: chr8:11703860:G>T
• Overlapping Gene: GATA4
• Disease Association: Ventricular Septal Defect (VSD)

1. Top Discovery Hits (Heart Assessment)

High quantiles but negligible raw scores indicate lack of strong functional driver.

Observations:

• Magnitude: Raw scores are ~0.01 (approx 0.7% change), which is typically

below the threshold of biological relevance.

• Quantile Inflation: The high quantiles likely reflect the tight

regulation of GATA4 in the model background, where even tiny deviations are "rare" but not necessarily impactful.

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

Plots and Visual Analysis

Regulatory Effects: Heart

!Heart Regulatory Effects

Visual Observation:

• Overview: The REF and ALT tracks appear identical. No loss of DNASE

peaks or H3K27ac marks is visible at the variant site.

Whole-Gene Expression View

!Whole-Gene RNA-seq

Visual Observation:

• Expression: The RNA-seq coverage across the entire GATA4 gene is

visually indistinguishable between REF (Blue) and ALT (Red). There is no evidence of global downregulation or isoform loss.

Detail View (+/- 50bp)

!Detail View

Visual Observation (Zoomed):

• Variant Site: At the exact variant position, the chromatin accessibility

(DNASE) and transcription factor binding signals remain unchanged.

Comparative ISM Analysis (Regulatory)

!ISM SeqLogo

Interpretation:

• Motif Stability: The ISM analysis shows a complex consensus motif but

minimal disruption scoring (Top score: 0.030). The G>T change does not significantly alter the binding potential of the predicted factors.

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

Conclusion

AlphaGenome does not support a standard loss-of-function or regulatory disruption mechanism for chr8:11703860:G>T in GATA4 based on adult/fetal heart models. The variant may be: 1. Non-functional (if VSD association is weak/conflicting). 2. Act via a mechanism not modeled (e.g., protein-coding missense change affecting protein structure, which this tool does not score). 3. developmentally specific to a timeframe not captured in the training data.

Recommendation: Assess protein-coding effect (missense?) and structural variation potential.

Example: True Negative Result (TGFB3 / ARVC)

Variant: chr14:75958692:G>A Gene: TGFB3 Phenotype: Arrhythmogenic Right Ventricular Cardiomyopathy (ARVC) Verdict: Likely Benign Regulatory Effect / Protein-Coding Mechanism?

Why this is a good example

This analysis demonstrates a True Negative for Regulatory Disruption where:

1. Low Signal: Discovery scores were universally low (<0.1), unlike the GATA4 example which had high quantiles but low magnitude. Here, both were low. 2. Visual Confirmation:

• Whole-Gene Plot: Shows identical expression profiles.
• Detail Plot: Shows stable chromatin.
• ISM: Empty matrices for ATAC, indicating no sensitive enhancer logic

at this site.

Key Takeaway

When a known disease gene (TGFB3) shows zero regulatory impact in relevant tissue models (Heart), consider:

1. Protein-Coding Effect: Is it a missense variant? (AlphaGenome only scores regulatory potential). 2. Missing Context: Is it a cryptic splicing event not captured? (Splicing scores were also low here). 3. Benign: It might just be a benign variant in a disease gene.

Variant Analysis Report: chr14:75958692:G>A

Summary

The variant chr14:75958692:G>A is implicated in Arrhythmogenic Right Ventricular Cardiomyopathy (ARVC) and located in the * TGFB3 gene (associated with Loeys-Dietz syndrome and arrhythmogenic phenotypes). AlphaGenome analysis predicted no significant molecular impact* in Heart tissues. All discovery scores were low (<0.1), and visual inspection of RNA-seq and regulatory tracks showed no discernible difference between REF and ALT alleles. This suggests the variant may be likely to have no effect, act via a protein-coding mechanism (missense/synonymous) not modeled here, or affect a context not captured in the current heart models.

Genomic Context

• Variant: chr14:75958692:G>A
• Overlapping Gene: TGFB3
• Disease Association: ARVC / Loeys-Dietz Syndrome

1. Top Discovery Hits (Negative Result)

No tissue showed significant regulatory disruption.

Observations:

• Magnitude: Raw scores are consistently near zero.
• Quantile: Even the "best" hits are well below the significance threshold

(0.995).

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

Plots and Visual Analysis

Regulatory Effects: Heart

!Heart Regulatory Effects

Visual Observation:

• Overview: The REF and ALT tracks are visually identical. No loss of

promoter activity or enhancer signal is observed at the variant site.

Whole-Gene Expression View

!Whole-Gene RNA-seq

Visual Observation:

• Expression: The RNA-seq coverage across TGFB3 is indistinguishable

between REF and ALT, confirming no global expression change.

Detail View (+/- 50bp)

!Detail View

Visual Observation (Zoomed):

• Variant Site: High-resolution view confirms the stability of the local

chromatin environment (DNASE/ATAC).

Comparative ISM Analysis

!Heart ISM SeqLogo

Interpretation:

• Motif Stability: The ISM analysis yielded low scores (max 0.15) and no

clear motif disruption. The ATAC ISM matrix was empty, indicating no sensitive enhancer elements were detected at this position in the model.

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

Conclusion

AlphaGenome does not predict a regulatory function for chr14:75958692:G>A in TGFB3 using Heart models. The variant is likely non-regulatory (check for missense/coding effects) or likely to have no effect in this context.

Recommendation: Verify protein-coding status.

Example: Polyadenylation Signal Disruption (HBA2 / Alpha-Thalassemia)

Variant: chr16:173692:A>G Gene: HBA2 (3' UTR) Phenotype: Hemoglobin H Disease / Alpha-Thalassemia Mechanism: Disruption of PolyA Signal (`AATAAA` -> `AATAAG`)

Why this is a good example

This analysis demonstrates a textbook 3' End Processing Defect:

1. Discovery Signal: The strongest hits (+1.07) are in Splice Junctions tracks (K562). In the 3' UTR context, this indicates failure to terminate or read-through, rather than splicing of introns. 2. ISM Smoking Gun: The ISM analysis for RNA-seq/Splicing unequivocally identifies the `AATAAA` hexamer as the critical motif (Score 2.45) which is destroyed by the variant. 3. Visuals: The Regulatory plots show the disruption at the transcript end.

Key Takeaway

When analyzing 3' UTR variants:

• Look for Splice Junction scores (indicating read-through).
• Look for RNA-seq changes (stability).
• Use ISM to check for AATAAA or ATTAAA motifs. This is often the

"smoking gun" for regulatory pathology in 3' UTRs.

Variant Analysis Report: chr16:173692:A>G (Hemoglobin H)

Summary

The variant chr16:173692:A>G is a pathogenic mutation in the 3' UTR of * HBA2 (Hemoglobin Subunit Alpha 2), causative for Hemoglobin H Disease (Alpha-Thalassemia). AlphaGenome analysis definitively identifies the molecular mechanism as the disruption of the canonical Polyadenylation Signal (`AATAAA`)*. This is evidenced by a severe perturbation of transcript processing in Erythroid models (K562), where the variant causes a massive increase in aberrant "Splice Junction" scores (+1.07), likely reflecting transcriptional read-through or failure to terminate. ISM analysis confirms the destruction of the critical AATAAA motif.

Genomic Context

• Variant: chr16:173692:A>G
• Overlapping Gene: HBA2 (3' UTR)
• Disease Association: Hemoglobin H Disease / Alpha-Thalassemia

1. Top Discovery Hits (Processing Defect)

High scores in "Splice Junctions" for a 3' UTR variant indicate processing failure.

Observations:

• Mechanism: The consistent high "Splicing" scores in the 3' UTR are

characteristic of PolyA signal loss, where the transcription machinery fails to terminate/cleave, reading through into downstream regions or utilizing cryptic sites.

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

Plots and Visual Analysis

Whole-Gene Expression View

!Whole-Gene RNA-seq

Visual Observation:

• Context: The plot shows the HBA2 locus. While global expression levels

may appear similar, the structure of the 3' end is likely altered (see ISM).

Regulatory Effects: K562

!K562 Regulatory Effects

Visual Observation:

• 3' UTR Disruption: The variant lies in the 3' region (AATAAA). The

high splicing score suggests the model detects a structural change in the transcript boundaries here.

ISM Analysis: The "Smoking Gun"

!K562 ISM SeqLogo

Interpretation:

• Motif Disruption: The ISM analysis cleanly identifies the `AATAAA`

hexamer as the most critical motif at this position (Score 2.45).

• Variant Effect: The A>G mutation destroys this canonical PolyA signal,

which is the textbook mechanism for this form of Alpha-Thalassemia.

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

Conclusion

The variant chr16:173692:A>G is a classic Regulatory Mutation that abolishes the * HBA2 Polyadenylation Signal (`AATAAA`)*. AlphaGenome correctly predicts this with high confidence in Erythroid models, flagging it as a major processing defect (+1.07 Score). This leads to unstable mRNA and alpha-globin deficiency.

Analysis Report: chr11:116837649:T>G (APOA1)

1. Variant Context

• Variant: chr11:116837649:T>G
• Gene: APOA1 (Apolipoprotein A-I)
• Location: Promoter Region (27 bp upstream of TSS on negative

strand).

• Disease: Hypoalphalipoproteinemia (HDL Deficiency).
• Tissues: Liver is the primary tissue for APOA1 expression.

2. Molecular Mechanism Hypothesis

The variant is located in the proximal promoter of APOA1. The AlphaGenome model predicts a Regulatory effect leading to altered expression.

3. Predicted Effects & Tissue Specificity

Primary Findings

: : : : : disruption : | Liver | RNA-seq | +0.14 | 0.999 | Significant |

Tissue Specificity Comparison

• Top Discovery Hit vs Disease-Relevant Tissue: The strongest signal is

actually in the Heart (Left Ventricle, Cardiac Septum), where the model predicts a very strong quantile score. The Liver signal, while significant, is lower in magnitude.

• Interpretation:
• APOA1 is expressed in multiple tissues. The variant likely disrupts a

broadly active regulatory element (promoter).

• The Heart signal suggests the variant has a **strong regulatory

potential in cardiac tissue. While Hypoalphalipoproteinemia is a metabolic (Liver) disease, this finding raises the possibility of subclinical cardiac effects** or simply reflects that the promoter is more "active/sensitive" in the model's Heart context.

• Result: We prioritize the Liver effect for the disease phenotype

(HDL deficiency), but acknowledge the Heart effect as the strongest molecular signal.

4. Visualizations

Liver (Expression/Regulation)

Clinical Target !Liver Effects

• Observation: Increased expression (+0.14) and local chromatin changes.

Heart (Left Ventricle)

Top Discovery Hit !Heart Effects

• Observation: Strong regulatory disruption. Note the specific track

changes compared to Liver.

5. Motif Analysis (ISM)

Heart (Left Ventricle) - RNA-seq

!Heart ISM

• Motif Analysis: The SeqLogo shows the specific nucleotides driving the

high score. A tall letter at the center (variant position) indicates direct motif disruption.

Liver - RNA-seq

!Liver ISM

• Motif Analysis: Comparison with Heart shows whether the same or

different motifs are active.

6. Conclusion

The variant chr11:116837649:T>G is a functional PROMOTER variant. 1. Clinical Impact: It alters APOA1 regulation in the Liver, consistent with Hypoalphalipoproteinemia. 2. Molecular Insight: The effect is broad, with the strongest regulatory signals observed in Heart tissue, suggesting a pleiotropic effect on the APOA1 promoter. 3. Mechanism: Disruption of TF binding leading to expression changes (Gain in Liver, potential Loss/Change in Heart), supported by ISM analysis showing motif sensitivity at the variant locus.

Regulatory Analysis Examples

This directory contains verified examples of successful regulatory variant analyses (Promoters, Enhancers).

Examples

1. Promoter Variant (Expression gain/loss) - APOA1

• Report: apoa1_promoter/report.md
• Plots:
• Liver Tracks (Clinical)
• Heart Tracks (Top Hit)
• Liver ISM
• Key Features:
• Promoter Zoom: Minimal zoom (~200bp) to show local chromatin

changes.

• Modality Integration: Concordant RNA-seq and DNASE/ChIP changes.
• Tissue Specificity: Comparing Clinical Target (Liver) vs Top

Discovery Hit (Heart).

• ISM: Identifying disrupted motifs.

Best Practices

• Local Zoom: Use tight 200bp windows for DNASE/ChIP to see local shape.
• Separate Plots: Do not combine RNA-seq (gene-scale) and DNASE

(local-scale) on the same X-axis unless they align perfectly; separate files are often cleaner.

• ISM: Always run ISM for strong regulatory hits to identify the

transcription factor involved.

Variant Analysis Report: COL6A2 chr21:46126238:G>C

1. Summary

The variant chr21:46126238:G>C in COL6A2 is predicted to have a critical impact on splicing in Aorta and other vascular tissues. The substitution abolishes the canonical splice donor site (Score decrease > 14) and activates a refined cryptic splice donor site 60bp downstream (Score increase > 14). This results in a 60bp exon extension, which leads to the in-frame insertion of 20 amino acids into the COL6A2 protein. The effect is highly significant (Quantile Score > 0.99999) across multiple vascular tissues, aligning with the gene's function in connective tissue structure.

2. Visual Analysis (Aorta)

!Aorta Variant Effects

Interpretation:

• Junction Tracks (Sashimi):
• Ref (Blue): Canonical donor usage is dominant.
• Alt (Red): Canonical donor is lost (0 reads). A new cryptic junction

appears 60bp downstream (high read count).

• Splice Sites:
• Confirms the loss of the canonical donor site at 46126238 and the gain

of a strong cryptic donor site at 46126298.

• Net Effect: 60bp extension of the exon.

3. Genomic Context & Mechanism

• Gene: COL6A2 (Collagen Type VI Alpha 2 Chain)
• Strand: Plus (+)
• Mechanism: Cryptic Splice Donor Activation causing Exon Extension

1. Canonical Loss: The G>C mutation disrupts the consensus sequence of the canonical splice donor at chr21:46126237. 2. Cryptic Gain: This forces the spliceosome to utilize a cryptic donor site located 60bp downstream at chr21:46126297. 3. Consequence: The exon is extended by 60 base pairs. 4. Protein Impact: 60bp / 3 = 20 codons. This is an in-frame insertion of 20 amino acids, potentially disrupting the triple-helical domain or other structural properties of COL6A2.

4. Conclusion

The chr21:46126238:G>C variant in COL6A2 disrupts the canonical splice donor and activates a cryptic site 60bp downstream. This drives a 20-amino acid in-frame insertion, likely destabilizing the collagen triple helix—a well-established mechanism for COL6A-related muscular disorders.

Variant Analysis Report: DLG1 chr3:197081044:TACTC>T

1. Summary

The variant chr3:197081044:TACTC>T (a 4bp deletion) in DLG1 is predicted to cause significant exon skipping in Tibial Artery and other vascular tissues. The deletion is located intronic, 6bp downstream of a canonical splice donor site. This disruption abolishes the usage of the canonical donor, forcing the splicing machinery to skip the adjacent exon entirely. This effect is highly significant (Quantile Score > 0.99999) and is consistent across multiple arterial tissues (Coronary, Umbilical).

2. Visual Analysis (Tibial Artery)

!Tibial Artery Variant Effects

Interpretation:

• Junction Tracks (Sashimi):
• Ref (Blue): Canonical splicing inclusion of the exon. Two arcs

connect the exon to its upstream and downstream neighbors.

• Alt (Red): The canonical arcs are lost. A single new arc

connects the upstream donor directly to the downstream acceptor, skipping the exon completely.

• Mechanism:
• The variant deletes 4bp (ACTC) from the intronic region relative to

the donor site (positions +2 to +5 or similar relative to the splice site boundary).

• This disrupts the recognition of the donor site by the spliceosome (U1

snRNP).

• Result: The exon is skipped.

3. Genomic Context & Mechanism

• Gene: DLG1 (Discs Large MAGUK Scaffold Protein 1)
• Strand: Minus (-)
• Variant Location: Intronic, near the 5' Splice Site (Donor) of an exon.
• Molecular Consequence: Disruption of the splice donor consensus sequence

-> Exon Skipping.

4. Conclusion

The 4bp deletion chr3:197081044:TACTC>T destroys a canonical splice donor site in DLG1, leading to the skipping of the associated exon in tibial artery tissue. This is a robust, high-confidence prediction validated by deep learning models.

Splicing Analysis Examples

This directory contains verified examples of successful splicing analyses and reports.

Examples

1. Exon Skipping (Donor Disruption) - DLG1

• Report: dlg1_report.md
• Plot: dlg1_exon_skipping.png
• Key Feature: Hybrid Zoom. Notice how the plot zooms out (~9kb) to

show the full skipping event and its anchor exons, rather than just the variant's immediate vicinity. This is critical for visualizing skipping.

2. Exon Extension (Cryptic Donor) - COL6A2

• Report: col6a2_report.md
• Plot: col6a2_exon_extension.png
• Key Feature: Site Shift. The Sashimi arcs and Splice Site tracks

clearly show the donor site moving 60bp downstream.

Best Practices Checklist

• Deduplication: Ensure redundant RNA-seq tracks (Total vs PolyA) are

filtered.

• Raw Counts: Sashimi plots should show raw integer counts (not

normalized) for clarity.

• Strand Aware: Always verify the gene strand and filter tracks

accordingly.

• Dynamic Zoom: Use the "Hybrid Span" logic (Junctions + Anchors) for

skipping events, but tighter zooms for local shifts (extensions).

Interpretation Guide

This guide covers biological interpretation, signal patterns, motif analysis, and the pre-report reasoning checklist. Read this before writing any report.

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

Signal Patterns Reference

Use this table to identify mechanisms from model outputs.

Expression & Regulatory

Some example mechanisms (non-exhaustive, use your reasoning ability):

: Loss : Enhancer : peak) + RNA-seq : motif (Strong : : : : loss : REF) : | TF Binding | Promoter/TSS or | DNASE gain (narrow | Created TF motif | : Site Creation : Enhancer : peak) + RNA-seq : (Strong ALT) : : : : gain : : | Enhancer | Distal | DNASE loss | Disrupted TF | : Disruption : : (distal) + RNA-seq : motif (Strong : : : : loss (linked : REF) : : : : gene). : : : : : H3K27ac/p300 loss : : : : : confirms. : : | Enhancer | Distal | DNASE gain | Created TF motif | : Creation : : (distal) + RNA-seq : (Strong ALT) : : : : gain (linked : : : : : gene). : : : : : H3K27ac/p300 gain : : : : : confirms. : : | TSS Shift | 5' UTR | RNA-seq shape | — | : : : change (5' end) or : : : : : CAGE peak shift : : | uORF | 5' UTR | Context-dependent: | — | : Creation : : may show weak : : : : : Expression score. : : : : : Verify ATG : : : : : creation in 5' : : : : : UTR. : : | mRNA | 3' UTR (Note: | RNA-seq loss | — | : Stability : Model does not : WITHOUT : : : : explicitly model : chromatin/splicing : : : : this, unlikely to : defects. Possible : : : : reliably pick up) : miRNA binding site : : : : : alteration. : : | Statistical | Any | High Quantile | Empty/noise | : Artifact** : (low-expression : (>0.999) + Zero : : : : genes) : Plot Difference. : : : : : Caused by variance : : : : : stabilization in : : : : : low-signal : : : : : regions. : :

Splicing

: : junction + new junctions : flanking exons, bypassing : : : spanning skipped exon : variant : | Intron Retention | Low Splice Site + high | — | : : RNA-seq in intron : : : : (read-through) : : | Cryptic Exon | New Splice Site (high | Junction starts/ends near | : (Pseudo-exon) : score) + new junctions : variant : : : flanking cryptic exon : : | Exon Extension | New donor/acceptor near | Junction shifted by N bp | : : existing site : from canonical : | PolyA Signal Loss | 3' UTR variant: high | AATAAA motif in ISM | : : Splice Junctions : : : : (read-through) + RNA-seq : : : : loss : :

Splicing Interpretation Rules

• Specific mechanisms only: Do NOT write "likely exon skipping or intron

retention" if data allows you to distinguish. Use the junction coordinates.

• Proxy signals: If Expression Loss (-0.999) >>> Splicing Disruption

(0.99), the primary mechanism is likely transcriptional (promoter/enhancer loss), not splicing. Exception: clearly aberrant new splice junction.

• Complex outcome: If multiple new cryptic sites compete with canonical

site, describe as "complex outcome of new candidate sites."

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

Tissue and Location Verification

• Verify Tissue Lineage: Both top hits and disease-relevant tissues are

valuable. Do NOT ignore unexpected top hits (e.g., "Mesenchymal Stem Cell" for an erythroid gene), as they may reveal regulatory potential. However, you MUST also search for and include the expected disease-relevant tissues (e.g., K562/Erythroblast) to ensure the report directly addresses the clinical context.

• Verify Tissue Relevance:
• Match Disease to Organ System: If the disease is "Cardiomyopathy",

you MUST use "heart", "atrium", "ventricle", or "cardiomyocyte".

• Avoid Generic Proxies: Do NOT use "Smooth Muscle Cell" for Heart

(Cardiac Muscle != Smooth Muscle). Do NOT use "Fibroblast" for Brain.

• Search Strategy: If a specific cell type query (e.g.,

"cardiomyocyte") yields 0 hits, search for the organ (e.g., "heart", "cardiac"). While you should report unexpected top hits in other tissues, ensure you also include the relevant organ/tissue to address the clinical context.

• Verify Location (GTF Overlap): Do NOT guess "Promoter" vs "5' UTR".

Check the GTF coordinates. A variant at -30 might be in the 5' UTR if the TSS is upstream. Use lookup_gene_info.py --coord='chr:pos' or bedtools intersect to confirm.

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

Score Interpretation

Raw Score vs Quantile Score

• Raw score: Effect magnitude, scorer-specific scale. Use for comparing

tissues WITHIN the same scorer only.

• Quantile score: Percentile rank vs common variants. Use to assess

significance. Saturates at ±0.999990.

• See variant-scoring-info section in alphagenome-api.md

for mathematical details.

Magnitude Rules

[!NOTE] Disclaimer: The interpretation of raw scores depends heavily on

the specific modality and assay type. The thresholds below are general rules

of thumb, primarily derived from RNA-seq data, and should not be treated as

absolute rules. Always validate quantitative scores by visually inspecting the

plotted tracks.

• < 0.1: Typically indicates No Significant Effect or background

noise, even if the quantile score is high.

• 0.1 - 0.5: Often represents a subtle or weak effect. Report as a

potential subtle change.

• 0.5 - 1.0: Suggests a moderate effect (roughly corresponding to a 1.4-2x

fold change in RNA-seq).

• > 1.0: Strong effect (generally >2x fold change for RNA-seq).
• RNA-seq raw_score ≈ log2 fold-change: -4 ≈ 16-fold reduction, -1 ≈

2-fold reduction, -0.35 ≈ 1.27-fold reduction.

• NO percentage interpretation: Raw scores are NOT percentages. Do not

interpret "0.09" as "9%".

• Relative Magnitude: Use relative comparisons (e.g., "low magnitude

compared to TERT's 1.5") or qualitative terms (e.g., "marginal effect").

• Always cite the raw score in reports (e.g., "Raw Score -1.89").

High Quantile + Low Raw Score

This is the most common trap. A quantile of 0.99+ with |raw_score| < 0.1 is effectively NO MOLECULAR EFFECT. This occurs in low-expression genes where variance stabilization inflates quantiles. Report as "No Significant Effect" and explain the statistical artifact.

Negative Results & Scientific Integrity

[!CRITICAL] Most variants are Benign. Do not "stretch" to find a mechanism

where none exists.

• Value of Negative Results: Reporting "AlphaGenome predicts NO molecular

effect" is a valuable scientific finding.

• Strict Anti-Speculation: Do not invent mechanisms (e.g., "cryptic splice

site", "enhancer disruption") unless explicitly shown by the model. If distinct evidence is missing, use broad terms like "predicted splicing disruption".

• Occupancy ≠ Disruption: A variant landing in an active enhancer (e.g.,

H3K27ac peak present) or promoter (e.g. before gene TSS) does not imply disruption. If REF and ALT tracks are identical and scores are near zero, the variant has no predicted effect. Do not claim disruption based on location alone.

• Model Limitations: AlphaGenome is a DNA-to-molecular phenotype model but

has limited scope of modeled molecular phenotypes. For example, it does NOT model:

• Post-Transcriptional RNA Biology: Beyond splicing (e.g., RNA

secondary structure folding, macromolecular assembly, transport).

• miRNA Processing: Due to low abundance or short length of

transcripts.

• Protein Coding Effects: Missense, nonsense, or frameshift mutations

affecting protein structure or function.

• Developmental Specificity: Effects restricted to specific

developmental timeframes not represented in the training data.

• Environmental or Dynamic Contexts: Effects triggered by specific

external stimuli or dynamic cell states not captured by the static biosample profiles.

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

ISM (In-Silico Mutagenesis) Interpretation

Reading SeqLogo Plots

• Tall letters at variant position: Mutation directly disrupts an

important motif.

• Positive height = activating when present; Negative = repressive.
• REF vs ALT: Strong REF letter → ALT disrupts binding site. Strong ALT

letter → ALT creates new binding site.

Motif Identification Rules

Use your base knowledge about sequences (semantic knowledge) to identify motifs when available. For well-known canonical sequences, you can identify directly:

For less obvious sequences: use your knowledge of TF motifs, and if no confident match is found, report the consensus sequence with "resembles" or "potential" qualifier (e.g., "Disrupted motif resembling GATA consensus").

Reverse Complement

ALWAYS check the reverse complement. The model sees double-stranded DNA, so the motif may be on the minus strand (e.g., AATAAA ↔ TTTATT).

Negative ISM

If the ISM plot shows only tiny bars (<0.1 height) or random noise, report "No specific motif disruption identified." Do not force a match.

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

Model Limitations

AlphaGenome predicts transcription and splicing from DNA sequence. It does NOT model:

• miRNA processing (low abundance / short length)
• RNA secondary structure (e.g., 3' UTR selenocysteine insertion

sequences, snRNA stem-loops)

• Protein folding or stability (missense effects)
• Catalytic activity (variant may produce stable but non-functional RNA)
• Developmental timing or stress-response contexts

Rules:

• If the gene is a non-coding RNA (snRNA, tRNA, rRNA) and you see High

Quantile + Low Raw Score: report "No Significant Effect" and state the structural limitation.

• If the known mechanism is protein stability: state that benign

regulatory scores do not rule out protein-level pathogenicity.

• If the known mechanism is enzymatic/catalytic: do not rule out

pathogenicity from neutral expression scores.

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

Ontology Resolution Best Practices

The resolve_ontology_terms script implements smart matching. Key principles:

1. Specificity first: Prefer "Naive thymus-derived CD4-positive..." over generic "T-cell". 2. No silent fallbacks: Better to return [NOT FOUND] than silently map "Kupffer cell" → "Liver". 3. You bridge disease → tissue: The script matches terms, not diseases. You must identify that "Multiple Sclerosis" → Oligodendrocyte, T-cell, Brain, then query those terms. 4. Abbreviation handling: Common abbreviations (lv → left ventricle, huvec → human umbilical vein endothelial) are built in. 5. Conservation of specificity: A match is rejected if any substantive query token is missing from the target. Only generic stopwords ("human", "tissue", "sample") can be safely dropped. 6. Partial match flagging: If a partial match or fallback is necessary, it must be explicitly flagged as [PARTIAL MATCH] in the output.

Tissue selection for reports:

• Match disease to organ system: "Cardiomyopathy" → heart, atrium,

ventricle, cardiomyocyte.

• Avoid generic proxies: Do NOT use "Smooth Muscle Cell" for heart

(cardiac ≠ smooth), "Fibroblast" for brain.

• Search strategy: If specific query (e.g., "cardiomyocyte") yields 0

hits, search for the organ ("heart", "cardiac").

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

Pre-Report Reasoning Checklist

Complete this BEFORE writing the report. Ground every interpretation in specific visual observations from the plots.

[!CAUTION] Do not pursue only the "obvious" answer (nearest gene,

literature-known tissue). Focus on where the model shows the strongest signal.

Ensure you have examined ALL significant scores, not just a convenient "top

5".

1. Cross-Tissue & Cross-Modality Patterns

• [ ] Analyze tissue specificity: Determine if the effect is universal or

tissue-restricted, and explain why.

• [ ] Check modality agreement: Verify if different modalities agree

within each tissue (concordant = strong evidence; discordant = complex regulation or potential model limitation).

• [ ] Identify largest effect: Pinpoint which tissue shows the largest

effect and assess its biological plausibility.

2. Hypothesis Validation

• [ ] Cite supporting plots: Explicitly state which plots support or

refute the proposed molecular mechanism.

• [ ] Cite supporting scores: Explicitly state which variant scores

support or refute the proposed molecular mechanism.

3. ISM SeqLogo

• [ ] Identify motif disruptions: Detail the motif disruptions evident

from REF vs ALT differences.

• [ ] Check consistency: Determine if disruptions are consistent across

tissues or tissue-specific.

• [ ] Explain magnitude differences: Use ISM plots to explain magnitude

differences between tissues.

4. Synthesis

• [ ] Define primary molecular mechanism: Trace the chain of events: E.g.

motif disruption → chromatin effect → transcriptional consequence → potential disease link.

• [ ] Avoid speculation: If scores are low and plots are flat, report "No

Significant Effect" instead of forcing a story.

• [ ] Address original query: Ensure the report directly answers the

user's initial question.

5. Report Readiness

• [ ] Write a narrative: Focus on telling a biological story, not just

dumping data.

• [ ] Verify references: Ensure all plot files are present and correctly

referenced.

• [ ] Embed all views: Include ISM plots, Detail Views, and Whole-Gene

Views where applicable.

• [ ] Confirm evidence: Verify that allegations of splicing have the

required splicing-related plots showing effects, expression changes have RNA-seq differences, and regulatory effects have DNASE/ChIP peak changes.

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

Report Templates

This file provides simplified templates for reporting AlphaGenome variant analysis results. Follow the structure below to ensure all critical sections are covered.

[!IMPORTANT] DO NOT use the agent's default artifact directory for this

report. Save it as a regular file named report.md directly in the variant's

output directory (e.g., analysis_chr1_12345_A_G/report.md) in the workspace.

Use relative paths for embedded plots (filename.png).

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

1. Standard Analysis Report Template

Use this template for variants that show significant functional effects.

# Analysis Report: {variant_str} ({gene_name})

## 1. Summary of Findings
[Detailed biological narrative, not generic. State gene function, specific mechanism (e.g., "Pseudo-exon", "Enhancer Disruption"), and effect with raw scores. Quantify effect in biological terms (e.g., fold-change) rather than just citing raw scores or quantiles.]

## 2. Genomic Context
- **Variant**: {variant_str}
- **Gene**: {gene_name} ({ENSG_ID})
- **Location**: [e.g., Promoter, 5' UTR, Exon, Intron, 3' UTR]
- **Disease**: {disease_name} (if applicable)

## 3. Discovery Hits & Disease-Relevant Scores
[Table of top hits from discovery scan, limited to top 15-20. Include disease-relevant tissues even if they are not top hits.]

| Biosample Name | Gene Name | Output Type | Raw Score | Quantile Score |
| :--- | :--- | :--- | :--- | :--- |
| [Tissue] | [Gene] | [Modality] | [Score] | [Quantile] |

*Note: Discuss any disease-relevant tissues that were not in the top hits but show significant effects.*

## 4. Plots and Visual Analysis
[Embed all plots generated using standard markdown syntax: `![caption](filename.png)`. Every ISM plot must have a specific interpretation caption. If visual inspection is ambiguous for AI agents, state the reliance on quantitative scores.]

![Main View](plot_{tissue}_{gene}_effects.png)
*Fig 1: Main view showing [modality] tracks.*

![Detail View](plot_{tissue}_{gene}_detail.png)
*Fig 2: Detail view centered on variant.*

![ISM Plot](ism_{tissue}_{modality}.png)
*Fig 3: ISM SeqLogo showing [motif description].*

## 5. Hypothesis Evaluation
[Explicitly state whether the hypothesis is SUPPORTED, REFUTED, or PARTIALLY SUPPORTED by the model scores.]

## 6. Primary Molecular Mechanism
[Synthesize the causal pathway: e.g., Variant disrupts X motif → causes chromatin closure → reduces expression of Y gene.]

## 7. Limitations
[State model blind spots (e.g., secondary structure, protein folding) and any unresolved questions or data gaps (e.g., missing modalities, proxy tissues used).]

## 8. Conclusion
[Narrative synthesis addressing primary finding, mechanism, biological impact, and confidence.]

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