alphagenome-single-variant-analysis
Analyzes genetic variant effects on gene expression (RNA-seq), chromatin accessibility (DNASE), histone marks (ChIP), and transcription factors using the AlphaGenome API. Use when the user asks about non-coding variant effects, pathogenicity, clinical significance, disease associations, functional effects, gene expression changes, splicing disruption, or regulatory effects in promoters and enhancers. Also use for resolving biological terms to tissue/cell-type ontologies (UBERON/CL) or analyzing variants in chr:pos:ref>alt format.
- License 许可
- MIT
- 最近更新
- 2026-10-23
- Stars
- ★ 5
- Forks
- 0
01 前言 Front Matter
- name
- alphagenome-single-variant-analysis
- description
- Analyzes genetic variant effects on gene expression (RNA-seq), chromatin accessibility (DNASE), histone marks (ChIP), and transcription factors using the AlphaGenome API. Use when the user asks about non-coding variant effects, pathogenicity, clinical significance, disease associations, functional effects, gene expression changes, splicing disruption, or regulatory effects in promoters and enhancers. Also use for resolving biological terms to tissue/cell-type ontologies (UBERON/CL) or analyzing variants in chr:pos:ref>alt format.
02 资源文件 47
- 参考文档docs/alphagenome-api.md13.3 KB
- 资产文件docs/examples/model_limitation_RNU4ATAC/ism_skeletal_muscle_RNA_SEQ.png12.1 KB
- 资产文件docs/examples/model_limitation_RNU4ATAC/plot_skeletal_muscle_RNU4ATAC_detail.png76.3 KB
- 资产文件docs/examples/model_limitation_RNU4ATAC/plot_skeletal_muscle_RNU4ATAC_effects.png72.9 KB
- 资产文件docs/examples/model_limitation_RNU4ATAC/plot_skeletal_muscle_RNU4ATAC_wholegene.png78.3 KB
- 参考文档docs/examples/model_limitation_RNU4ATAC/README.md1.7 KB
- 参考文档docs/examples/model_limitation_RNU4ATAC/report.md3.7 KB
- 资产文件docs/examples/negative_result_GATA4/ism_heart_DNASE.png11.7 KB
- 资产文件docs/examples/negative_result_GATA4/plot_heart_GATA4_detail.png73.5 KB
- 资产文件docs/examples/negative_result_GATA4/plot_heart_GATA4_effects.png70.2 KB
- 资产文件docs/examples/negative_result_GATA4/plot_heart_GATA4_wholegene.png78.2 KB
- 参考文档docs/examples/negative_result_GATA4/README.md1.1 KB
- 参考文档docs/examples/negative_result_GATA4/report.md3.6 KB
- 资产文件docs/examples/negative_result_TGFB3/ism_heart_ATAC.png6.5 KB
- 资产文件docs/examples/negative_result_TGFB3/ism_heart_RNA_SEQ.png10.3 KB
- 资产文件docs/examples/negative_result_TGFB3/plot_heart_TGFB3_detail.png51.5 KB
- 资产文件docs/examples/negative_result_TGFB3/plot_heart_TGFB3_effects.png64.0 KB
- 资产文件docs/examples/negative_result_TGFB3/plot_heart_TGFB3_wholegene.png43.9 KB
- 参考文档docs/examples/negative_result_TGFB3/README.md1.2 KB
- 参考文档docs/examples/negative_result_TGFB3/report.md3.0 KB
- 资产文件docs/examples/polyadenylation_HBA2/ism_K562_RNA_SEQ.png10.8 KB
- 资产文件docs/examples/polyadenylation_HBA2/plot_K562_HBA2_effects.png158.5 KB
- 资产文件docs/examples/polyadenylation_HBA2/plot_K562_HBA2_wholegene.png159.3 KB
- 参考文档docs/examples/polyadenylation_HBA2/README.md1.1 KB
- 参考文档docs/examples/polyadenylation_HBA2/report.md3.1 KB
- 资产文件docs/examples/regulatory/apoa1_promoter/ism_heart_left_ventricle_RNA_SEQ.png8.6 KB
- 资产文件docs/examples/regulatory/apoa1_promoter/ism_liver_RNA_SEQ.png8.6 KB
- 资产文件docs/examples/regulatory/apoa1_promoter/plot_heart_left_ventricle_APOA1_effects.png73.0 KB
- 资产文件docs/examples/regulatory/apoa1_promoter/plot_liver_APOA1_effects.png221.5 KB
- 参考文档docs/examples/regulatory/apoa1_promoter/report.md3.4 KB
- 参考文档docs/examples/regulatory/README.md1.2 KB
- 资产文件docs/examples/splicing/col6a2_exon_extension.png101.4 KB
- 参考文档docs/examples/splicing/col6a2_report.md2.2 KB
- 资产文件docs/examples/splicing/dlg1_exon_skipping.png73.1 KB
- 参考文档docs/examples/splicing/dlg1_report.md1.9 KB
- 参考文档docs/examples/splicing/README.md1.3 KB
- 参考文档docs/interpretation-guide.md17.4 KB
- 参考文档docs/report-templates.md2.8 KB
- 其他pyproject.toml269 B
- 参考文档references/citation.bib823 B
- 脚本scripts/analyze_ism.py10.1 KB
- 脚本scripts/generate_ontology_mapping.py4.8 KB
- 脚本scripts/interpret_splicing.py9.5 KB
- 脚本scripts/lookup_gene_info.py9.4 KB
- 脚本scripts/resolve_ontology_terms.py4.7 KB
- 脚本scripts/visualize_genome_tracks.py12.0 KB
- 脚本scripts/visualize_variant_effects.py35.6 KB
03 SKILL.md 正文
Variant Analysis using AlphaGenome
Prerequisites
uv: Read theuvskill and follow its Setup instructions to ensureuvis installed and on PATH.- User Notification: If .licenses/alphagenome_single_variant_analysis_LICENSE.txt does not already exist in the workspace root 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.
.envfile: Make sure the.envfile exists in your home directory. Create one if it does not exist.ALPHAGENOME_API_KEY: This skill requires an API key to function. You can register for a key at https://deepmind.google.com/science/alphagenome/. You MUST use the safe credentials protocol in thecredentialsskill to check for and request this key if this skill looks relevant to the user's request.
Core Rules
- NEVER run
python3orpython3 -cdirectly. The system Python does not necessarily have pandas, numpy, and other key dependencies. ALWAYS useuv runto run ALL Python code — including scripts, ad-hoc analysis files, and one-liners. Do not attempt topip installor create new venvs —uvmanages an isolated environment automatically. - Offline Only: NEVER use external APIs (e.g., MyGene.info, Ensembl REST)
for gene/transcript lookup. Use
lookup_gene_info.pywith the local GTF. If it fails, fix the environment/paths, do not switch to external APIs. - API Key is required:
ALPHAGENOME_API_KEYmust be set before running any script. - Notification: If this skill is used, ensure this is mentioned in the output.
- Report Format: Always use the templates in
docs/report-templates.mdfor 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_scoresand metadata often usegene_name(notgene_symbol) andoutput_type(notmodality). Always inspectdf.columnsbefore filtering. - Large Genes: Genes > 500kb (e.g.,
USH2A) break thewhole_geneview. Use--view detailor manual regional windows instead. - Sashimi Strand Error:
plot_components.Sashimidoes NOT accept astrandargument directly. Filter input tracks instead. - KeyError: 'ontology_curie': Not all tracks have
ontology_curie. Checktrack.metadata.columnsbefore filtering. - Python Path: If
exec: "python": executable file not foundoccurs, ensure you are usinguv runinstead of barepython/python3. - NotImplementedError (pandas): "iLocation based boolean indexing on an
integer type is not available". This occurs when using boolean masks with
.ilocon integer-indexed DataFrames in newer pandas versions. Fix: Convert boolean masks to integer indices usingnp.flatnonzero(mask). - GTF Feather Case Sensitivity: The AlphaGenome GTF Feather file uses
Capitalized column names (
Feature,Start,End,Strand) unlike standard GTF files. Always checkdf.columnsif getting KeyErrors. score_variantontology filtering:score_variantdoes NOT acceptontology_termsas an argument. You must filter the returned AnnData objects manually by inspectingadata.varcolumns. In contrast,predict_variantDOES acceptontology_termsdirectly.- 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
Junctionobjects frompredictionmay be simple Intervals. Usejunction_data.get_junctions_to_plot(predictions=..., name=...)to retrieve objects with the.k(abundance/score) attribute. uvNot Found: Ifexec: uv: not found, follow the installation instructions in Prerequisites.- Registry Authentication Error (401): If
uvfails with 401 Unauthorized for a private registry, setUV_INDEX_URL=https://pypi.org/simplebefore 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:
- Base Interval: Variant +/- 1 downstream and upstream exon (Structural Context).
- Junction Expansion: Expands to include the full span of any significant splicing junction (e.g., exon skipping events that span multiple exons).
- 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.
- Splicing Zoom Strategy: Uses a Hybrid Approach for optimal
visibility:
examples/splicing/— Splicing analysis examplesexamples/model_limitation_RNU4ATAC/— ncRNA structure limitation case studyexamples/polyadenylation_HBA2/— 3' UTR / Polyadenylation case studyexamples/regulatory/— Regulatory variant examplesexamples/negative_result_GATA4/— Negative results (mathematical artefact)examples/negative_result_TGFB3/— Negative results (proxies)scripts/lookup_gene_info.py— Gene & transcript lookupscripts/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
import dotenv
# Load environment variables from ~/.env
dotenv.load_dotenv(os.path.expanduser('~/.env'))
# 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
| Script | Purpose |
|---|---|
lookup_gene_info |
Comprehensive gene and transcript lookup using |
| : : 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 |
04 同仓库更多 Skills
writing-guidelines
Review docs/prose for Writing Guidelines compliance. Use when asked to "review my docs", "check writing style", "audit prose", "review docs voice and tone", or "check this page against the writing handbook".
writing-for-agents
Writing documents for agents. Use when creating or editing skills, or modifying AGENTS.md or CLAUDE.md.
wrangler
Cloudflare Workers CLI for deploying, developing, and managing Workers, KV, R2, D1, Vectorize, Hyperdrive, Workers AI, Containers, Queues, Workflows, Pipelines, and Secrets Store. Load before running wrangler commands to ensure correct syntax and best practices. Biases towards retrieval from Cloudflare docs over pre-trained knowledge.
workers-best-practices
Reviews and authors Cloudflare Workers code against production best practices. Load when writing new Workers, reviewing Worker code, configuring wrangler.jsonc, or checking for common Workers anti-patterns (streaming, floating promises, global state, secrets, bindings, observability). Biases towards retrieval from Cloudflare docs over pre-trained knowledge.
web-perf
Analyzes web performance using Chrome DevTools MCP. Measures Core Web Vitals (LCP, INP, CLS) and supplementary metrics (FCP, TBT, Speed Index), identifies render-blocking resources, network dependency chains, layout shifts, caching issues, and accessibility gaps. Use when asked to audit, profile, debug, or optimize page load performance, Lighthouse scores, or site speed. Biases towards retrieval from current documentation over pre-trained knowledge.
using-agent-skills
Discovers and invokes agent skills. Use when starting a session, or when you need to decide which skill or workflow applies to the piece of work at hand. This is the meta-skill that governs how all other skills are discovered and invoked.