/alphagenome_single_variant_analysis

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.

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 .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. 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 can register for a key at https://deepmind.google.com/science/alphagenome/. You **MUST** use the safe credentials protocol in the `credentials` skill to check for and request this key if this skill looks relevant to the user's request. 5. **`ALPHAGENOME_GTF_PATH` (Optional)**: Accelerate gene/transcript lookup by pointing to a local copy of the GTF feather file instead of downloading from GCS:

    echo "ALPHAGENOME_GTF_PATH=/path/to/local/gencode.v46.annotation.gtf.gz.feather" >> ~/.env

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.

• **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](#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](docs/alphagenome-api.md) — API reference and code

patterns

• [interpretation-guide.md](docs/interpretation-guide.md) — Interpretation

guide, score magnitude rules, ISM, and checklist.

• [report-templates.md](docs/report-te