PyEnsembl

PyEnsembl looks up genes, transcripts, exons and their protein and transcript sequences in a pinned Ensembl release or in your own GTF and FASTA files. It downloads and indexes an annotation once; after that, queries run locally. It is the gene annotation layer of the OpenVax tools: Varcode, Isovar, Topiary and Vaxrank use it, and it builds on datacache for downloads and gtfparse for reading GTF files.

Install

Use Python 3.11 or later. Install the package and one annotation release:

python -m pip install pyensembl
pyensembl install --release 93 --species human

The second command selects human GRCh38 and downloads and indexes Ensembl release 93's annotation, transcript and protein files, about 1.3 GB. It takes several minutes. Whole-genome DNA is a separate, optional download.

Quick start

After installing the data above:

from pyensembl import EnsemblRelease

with EnsemblRelease(93, species="human") as data:
    gene = data.gene_by_id("ENSG00000141510")
    print(gene.name, gene.contig, gene.start, gene.end, gene.strand)
    transcript = data.transcript_by_id("ENST00000269305")
    print(transcript.name, transcript.protein_sequence[:30])

TP53 17 7661779 7687550 -
TP53-201 MEEPQSDPSVEPPLSQETFSDLWKLLPENN

Coordinates are one-based and inclusive; TP53 is on the minus strand. Pin the release you analyze: coordinates, IDs and sequences can change between releases. A gene name can match several loci, so data.genes_by_name("TP53") returns a list.

Command line

The pyensembl command installs and manages local data:

pyensembl install --release 93 --species human  # download and index a release
pyensembl list                                  # installed genomes and their status
pyensembl inspect --release 93                  # files, sizes and provenance, offline
pyensembl available                             # supported species, assemblies and releases
pyensembl delete-all-files --release 93         # remove one release's local data
pyensembl prune --dry-run                       # shared reference DNA that no release uses

The command-line reference lists every option. For Tab completion, run activate-global-python-argcomplete once, or add eval "$(register-python-argcomplete pyensembl)" to your shell's startup file.

Documentation

The documentation starts with installation and a first lookup, then covers one task per page. In reading order:

1. Find genes and transcripts by name, ID, position or biotype.
2. Get protein and transcript sequences, coding sequences, UTRs and exons.
3. Read genomic DNA for introns and flanking sequence.
4. Choose a reference: species, assembly, and numbered or dated Ensembl releases.
5. Install and manage data from Python, check what is installed and free disk space.
6. Use your own annotations from GTF and FASTA files.

Also see gene name aliases, genetic codes and the API reference.

Development

From a clone of this repository:

python -m pip install -e '.[dev]'
./lint.sh   # ruff and mypy
./test.sh   # pytest with coverage
./docs.sh   # strict docs build and link checks; needs '.[docs]'

Most tests need the Ensembl releases that the Tests workflow installs. Every PR bumps pyensembl/version.py, including documentation changes. See contributing and releasing.

License

Apache License 2.0