domains / research / ensembl-rest-queries / ensembl-database

ensembl-database

Skill card

combined

The two copies overlap on Ensembl REST use cases (gene lookup, sequence, VEP, homology, assembly mapping) but each has material steps the other lacks. The aipoch copy is a packaged skill centered on scripts/query_ensembl.py with a CLI contract (--action lookup|sequence|vep, --species, --symbol, --id, --hgvs) and references/api_endpoints.md, but it omits rate-limiting, error handling, and direct REST examples. The FreedomIntelligence copy provides direct REST endpoints, ensembl_rest Python examples, rate-limiting (15 req/s, Retry-After), error handling, and assembly-mapping server selection, but it does not define the packaged CLI or the repository's script-based execution path. Crowning one would hide a real alternative workflow.

Repositories

Other copies

Combined skill

---
name: ensembl-database
description: Query the Ensembl REST API for vertebrate genomic data. Use for gene/ID lookups, sequence retrieval, VEP variant effect prediction, homology/ortholog queries, and assembly coordinate mapping.
---

# Ensembl Database Skill

## When to Use

- Resolve gene symbols or genomic regions to Ensembl identifiers and annotations.
- Retrieve DNA, cDNA, or protein sequences in FASTA or JSON.
- Predict variant consequences with VEP from HGVS notation.
- Find orthologs/paralogs across vertebrate species.
- Map coordinates between assemblies (e.g., GRCh37 to GRCh38).
- Integrate Ensembl data into reproducible genomic research pipelines.

## Execution Path

1. Confirm the user's input, output path, and any required configuration values.
2. Choose the execution method:
   - **Packaged CLI** (preferred when `scripts/query_ensembl.py` is available): run the script with the appropriate `--action`.
   - **Direct REST / Python client**: use `requests` or the `ensembl_rest` package when the CLI is unavailable or custom logic is needed.
3. Run the query with validated inputs.
4. Review the generated output and return the final artifact with any assumptions called out.

## Packaged CLI (scripts/query_ensembl.py)

### Core Parameters

- `--action`: Operation selector. Supported values: `lookup`, `sequence`, `vep`.
- `--species`: Target species name (e.g., `human`).
- `--symbol`: Gene symbol for lookup actions (e.g., `BRCA2`).
- `--id`: Ensembl stable ID for sequence retrieval (e.g., `ENSG...`, `ENST...`, `ENSP...`).
- `--hgvs`: HGVS notation string for VEP (e.g., `ENST...:c.123A>G`).

### Examples

```bash
# Gene lookup by symbol
python scripts/query_ensembl.py --action lookup --species human --symbol BRCA2

# Retrieve sequence by Ensembl ID
python scripts/query_ensembl.py --action sequence --id ENSG00000139618

# Variant effect prediction (VEP) by HGVS
python scripts/query_ensembl.py --action vep --species human --hgvs "ENST00000380152.8:c.68_69delAG"
```

## Direct REST API

Base URL: `https://rest.ensembl.org`

For GRCh37/hg19 queries, use: `https://grch37.rest.ensembl.org`

### Gene Lookup by Symbol

```python
import requests

server = "https://rest.ensembl.org"
response = requests.get(
    f"{server}/lookup/symbol/homo_sapiens/BRCA2",
    headers={"Content-Type": "application/json"}
)
gene_data = response.json()
```

### Sequence Retrieval

```python
# Using ensembl_rest package
from ensembl_rest import EnsemblClient

client = EnsemblClient()
sequence = client.sequence_id(
    id='ENSG00000139618',
    content_type='application/json'
)

# Get sequence for a genomic region
region_seq = client.sequence_region(
    species='human',
    region='7:140424943-140624564'
)
```

### VEP Variant Effect Prediction

```python
vep_result = client.vep_hgvs(
    species='human',
    hgvs_notation='ENST00000380152.7:c.803C>T'
)
```

### Homology / Orthologs

```python
orthologs = client.homology_ensemblgene(
    id='ENSG00000139618',
    target_species='mouse'
)
```

### Assembly Mapping

```python
from ensembl_rest import AssemblyMapper

mapper = AssemblyMapper(
    species='human',
    asm_from='GRCh37',
    asm_to='GRCh38'
)
mapped = mapper.map(chrom='7', start=140453136, end=140453136)
```

## API Best Practices

### Rate Limiting

- Maximum 15 requests per second for anonymous users.
- Handle 429 responses by checking the `Retry-After` header and waiting.
- Use batch endpoints where available.
- Cache frequently accessed data to reduce API calls.

### Error Handling

```python
import requests
import time

def query_ensembl(endpoint, params=None, max_retries=3):
    server = "https://rest.ensembl.org"
    headers = {"Content-Type": "application/json"}

    for attempt in range(max_retries):
        response = requests.get(
            f"{server}{endpoint}",
            headers=headers,
            params=params
        )

        if response.status_code == 200:
            return response.json()
        elif response.status_code == 429:
            retry_after = int(response.headers.get('Retry-After', 1))
            time.sleep(retry_after)
        else:
            response.raise_for_status()
    return None
```

## Dependencies

- Python `>=3.8` (use `3.10+` if following the aipoch repository baseline).
- `ensembl_rest` Python client (version depends on environment).
- Network access to `https://rest.ensembl.org` (and `https://grch37.rest.ensembl.org` for GRCh37).

## Reference

- Endpoint reference: `references/api_endpoints.md` (when available in the packaged skill).
- Ensembl REST documentation: https://rest.ensembl.org