Ensembl gene lookup

Purpose

Resolve a gene symbol through Ensembl REST and return the corresponding gene lookup payload.

When to use

• You need a quick official Ensembl gene identifier lookup.
• You want lightweight gene metadata before a larger genomics workflow.

When not to use

• You need transcript-level or large-batch annotation.
• You need local-only execution.

Inputs

• Gene symbol
• Optional species and output path

Outputs

• JSON payload containing the xref candidates and the selected lookup record

Requirements

• Python 3.13+
• Network access to rest.ensembl.org
• Example asset fallback exists for the curated BRCA1 and BRCA2 examples if the live API is temporarily unavailable.

Procedure

1. Run python3 skills/genomics/ensembl-gene-lookup/scripts/lookup_gene.py --symbol BRCA1 --out skills/genomics/ensembl-gene-lookup/assets/brca1_lookup.json.
2. Inspect xrefs to confirm the chosen gene ID.
3. Use the lookup block for coordinates and display name.

Validation

• Command exits successfully.
• At least one xref is returned for a known symbol.
• Lookup block includes id, display_name, and coordinates.

Failure modes and fixes

• No hits: confirm species and capitalization.
• Multiple matches: filter by type == gene and inspect the candidates.
• Official API timeout: rerun once; the curated BRCA example assets can still support deterministic example execution.

Safety and limits

• Metadata lookup only.
• Large-scale annotation should use more specialized batch tooling.

Examples

• python3 .../lookup_gene.py --symbol TP53 --species homo_sapiens

Provenance

• Ensembl REST API: https://rest.ensembl.org/
• Ensembl lookup documentation: https://rest.ensembl.org/documentation/info/lookup

Related skills

• scanpy-qc-starter