---
name: ensembl-database
description: Access Ensembl REST API for vertebrate genomic data; use when you need gene/ID lookups, sequence retrieval, variant effect prediction (VEP), or homology/assembly coordinate mapping.
license: MIT
author: AIPOCH
---
> **Source**: [https://github.com/aipoch/medical-research-skills](https://github.com/aipoch/medical-research-skills)

# Ensembl Database Skill

## When to Use

- Use this skill when you need access ensembl rest api for vertebrate genomic data; use when you need gene/id lookups, sequence retrieval, variant effect prediction (vep), or homology/assembly coordinate mapping in a reproducible workflow.
- Use this skill when a evidence insight task needs a packaged method instead of ad-hoc freeform output.
- Use this skill when the user expects a concrete deliverable, validation step, or file-based result.
- Use this skill when `scripts/query_ensembl.py` is the most direct path to complete the request.
- Use this skill when you need the `ensembl-database` package behavior rather than a generic answer.

## Key Features

- Scope-focused workflow aligned to: Access Ensembl REST API for vertebrate genomic data; use when you need gene/ID lookups, sequence retrieval, variant effect prediction (VEP), or homology/assembly coordinate mapping.
- Packaged executable path(s): `scripts/query_ensembl.py`.
- Reference material available in `references/` for task-specific guidance.
- Structured execution path designed to keep outputs consistent and reviewable.

## Dependencies

- `Python`: `3.10+`. Repository baseline for current packaged skills.
- `Third-party packages`: `not explicitly version-pinned in this skill package`. Add pinned versions if this skill needs stricter environment control.

## Example Usage

```bash
cd "20260316/scientific-skills/Evidence Insight/ensembl-database"
python -m py_compile scripts/query_ensembl.py
python scripts/query_ensembl.py --help
```

Example run plan:
1. Confirm the user input, output path, and any required config values.
2. Edit the in-file `CONFIG` block or documented parameters if the script uses fixed settings.
3. Run `python scripts/query_ensembl.py` with the validated inputs.
4. Review the generated output and return the final artifact with any assumptions called out.

## Implementation Details

- Execution model: validate the request, choose the packaged workflow, and produce a bounded deliverable.
- Input controls: confirm the source files, scope limits, output format, and acceptance criteria before running any script.
- Primary implementation surface: `scripts/query_ensembl.py`.
- Reference guidance: `references/` contains supporting rules, prompts, or checklists.
- Parameters to clarify first: input path, output path, scope filters, thresholds, and any domain-specific constraints.
- Output discipline: keep results reproducible, identify assumptions explicitly, and avoid undocumented side effects.

## 1. When to Use

- **Gene-centric queries**: When you need to resolve a gene symbol or region to Ensembl identifiers and basic annotations (e.g., `BRCA2` in human).
- **Sequence extraction**: When you need DNA/cDNA/protein sequences for a known Ensembl gene/transcript/protein ID in FASTA or JSON.
- **Variant interpretation**: When you need to predict functional consequences of variants using **VEP** from HGVS notation.
- **Comparative genomics**: When you need ortholog/paralog relationships across vertebrate species.
- **Assembly/coordinate mapping**: When you need to map coordinates between assemblies (e.g., GRCh37 ↔ GRCh38).

## 2. Key Features

- Query Ensembl REST endpoints for:
  - **Gene lookup** by symbol, Ensembl ID, or genomic region
  - **Sequence retrieval** (DNA, cDNA, protein) in FASTA/JSON
  - **Variant Effect Predictor (VEP)** analysis from HGVS inputs
  - **Homology** retrieval (orthologs/paralogs)
  - **Assembly/coordinate mapping** between common human assemblies
- CLI helper script for repeatable queries:
  - `scripts/query_ensembl.py` (wrapper around an `ensembl_rest` client)
- Reference documentation for endpoints:
  - `references/api_endpoints.md`
  - Ensembl REST base URL: https://rest.ensembl.org

## 3. Dependencies

- Python `>=3.8`
- `ensembl_rest` (Python client; version depends on your environment)
- Network access to `https://rest.ensembl.org`

## 4. Example Usage

### CLI: Gene lookup by symbol

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

### CLI: Retrieve sequence by Ensembl ID

```bash
python scripts/query_ensembl.py --action sequence --id ENSG00000139618
```

### CLI: Variant effect prediction (VEP) by HGVS

```bash
python scripts/query_ensembl.py --action vep --species human --hgvs "ENST00000380152.8:c.68_69delAG"
```

## 5. Implementation Details

### Script entry point

- **Tool**: `scripts/query_ensembl.py`
- **Purpose**: Provide a simple command-line interface that dispatches to Ensembl REST calls via an `ensembl_rest` client.

### Core parameters

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

### Data types and outputs

- **Lookup**: Returns gene/transcript metadata as provided by Ensembl REST.
- **Sequence**: Returns DNA/cDNA/protein sequence; format depends on the endpoint/options (commonly FASTA or JSON).
- **VEP**: Returns consequence annotations and (when available) population frequency fields as provided by Ensembl VEP REST responses.

### Endpoint reference

For the exact REST paths, required parameters, and response schemas, see:
- `references/api_endpoints.md`
- https://rest.ensembl.org


---
Source attribution: aipoch
Original project: https://github.com/aipoch/medical-research-skills/blob/686e09dfdb45d9fa1a08664f06bb93769b3c9d91/scientific-skills/Evidence%20Insight/ensembl-database/SKILL.md
License: MIT
License information: https://opensource.org/license/mit
Original upstream instructions; downloaded from Mega AI Hub.

## Upstream license notice

MIT License

Copyright (c) 2026 AIpoch

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.



# Mega AI Hub resource metadata

Creator / publisher: aipoch
Original project: https://github.com/aipoch/medical-research-skills/blob/686e09dfdb45d9fa1a08664f06bb93769b3c9d91/scientific-skills/Evidence%20Insight/ensembl-database/SKILL.md
Attribution basis: Source repository record

Fields of work: Data & Analytics, Education & Research
Roles: Business Intelligence Analyst, Data Scientist, Researcher
Specialties: API, Backend
Tools: Ensembl Rest Api
Country applicability: Country not specified
Classification basis: Source catalog labels
Instruction SHA-256: 233e6554f40c700a5c3ef73b4d3ab87f2323390f474c5805692a7735384ecb33