Gene Structure Mapper

---

name: gene-structure-mapper

description: Visualize gene structure with exon-intron diagrams, domain annotations, and mutation position markers. Produces SVG, PNG, or PDF figures suitable for publication from a gene symbol input.

license: MIT

skill-author: AIPOCH

status: beta

---

# Gene Structure Mapper

Generate exon-intron structure diagrams for any gene symbol using the Ensembl REST API. Optionally overlay protein domain annotations (UniProt) and mark mutation hotspot positions. Outputs publication-ready SVG, PNG, or PDF figures.

> ✅ **IMPLEMENTED** — `scripts/main.py` is fully functional. Ensembl REST API, caching, matplotlib visualization, `--domains`, `--mutations`, and `--demo` are all implemented.

Quick Check

python -m py_compile scripts/main.py
python scripts/main.py --help
python scripts/main.py --demo --output demo.png

When to Use

Workflow

1. Confirm the user objective, required inputs, and non-negotiable constraints before doing detailed work.

2. Validate that the request matches the documented scope and stop early if the task would require unsupported assumptions.

3. Use the packaged script path or the documented reasoning path with only the inputs that are actually available.

4. Return a structured result that separates assumptions, deliverables, risks, and unresolved items.

5. If execution fails or inputs are incomplete, switch to the fallback path and state exactly what blocked full completion.

**Fallback template:** If `scripts/main.py` fails or the gene symbol is unrecognized, report: (a) the failure point, (b) whether a manual Ensembl/UCSC lookup can substitute, (c) which output formats are still generatable.

Parameters

| Parameter | Type | Required | Description |

|-----------|------|----------|-------------|

| `--gene`, `-g` | string | Yes* | Gene symbol or Ensembl ID (e.g., `TP53`, `BRCA1`, `ENSG00000141510`) |

| `--species` | string | No | Species name for Ensembl lookup (default: `homo_sapiens`) |

| `--format` | string | No | Output format: `png`, `svg`, `pdf` (default: `png`) |

| `--output`, `-o` | string | No | Output file path (default: `<gene>_structure.<format>`) |

| `--domains` | flag | No | Fetch and overlay UniProt protein domain annotations |

| `--mutations` | string | No | Comma-separated codon positions to mark (e.g., `248,273`) |

| `--demo` | flag | No | Use hardcoded TP53 GRCh38 data — no internet required |

*Required unless `--demo` is used.

Usage

python scripts/main.py --gene TP53 --format png
python scripts/main.py --gene BRCA1 --format png --domains --output brca1_structure.png
python scripts/main.py --gene KRAS --mutations 12,13,61 --format pdf
python scripts/main.py --demo
python scripts/main.py --demo --output demo.png --format svg

Implementation Notes (for script developer)

The script must implement:

1. **Gene lookup** — `GET https://rest.ensembl.org/lookup/symbol/homo_sapiens/{gene}?expand=1` to fetch exon coordinates. Cache response to `.cache/{gene}_ensembl.json` to avoid repeated API calls. Add a 0.1 s delay between requests for batch lookups. The unauthenticated rate limit is 15 requests/second.

2. **Unknown gene handling** — catch HTTP 400/404 from Ensembl and exit with code 1: `Error: Gene not found: {gene_name}. Check the gene symbol and try again.`

3. **SVG/PNG/PDF output** — use `matplotlib` or `svgwrite` to draw exon blocks (filled rectangles) and intron lines scaled to genomic coordinates.

4. **`--domains` flag** — fetch UniProt domain annotations and overlay colored domain blocks on the gene structure.

5. **`--mutations` flag** — accept comma-separated codon positions; map to exon coordinates and draw vertical markers.

6. **`--demo` flag** — use hardcoded TP53 GRCh38 exon coordinates (no internet required) to generate a demo visualization.

Known Limitations

Features

Output Requirements

Every response must make these explicit:

Input Validation

This skill accepts: gene symbol inputs for structure visualization, with optional domain and mutation overlays.

If the request does not involve gene structure visualization — for example, asking to perform sequence alignment, predict protein structure, or analyze expression data — do not proceed. Instead respond:

> "`gene-structure-mapper` is designed to visualize gene exon-intron structure. Your request appears to be outside this scope. Please provide a gene symbol and desired output format, or use a more appropriate tool for your task."

Error Handling

Response Template

1. Objective

2. Inputs Received

3. Assumptions

4. Workflow

5. Deliverable

6. Risks and Limits

7. Next Checks