gtfparse

gtfparse reads GTF (Gene Transfer Format) annotation files, such as those from Ensembl and GENCODE, into pandas DataFrames: one row per feature, with attributes such as gene and transcript IDs expanded into columns. It can also write a table back to GTF. In the OpenVax tools, PyEnsembl uses it to read Ensembl and custom annotations before indexing them.

Install

python -m pip install gtfparse

Python 3.11 or later is required. gtfparse depends on pandas and PyArrow; for optional Polars output, install gtfparse[polars].

Quick start

This small artificial GTF runs without a download. Replace the stream with your annotation filename when working with a real dataset.

from io import StringIO
from gtfparse import read_gtf

annotation = StringIO(
    '1\texample\tgene\t101\t200\t.\t+\t.\tgene_id "g1"; gene_name "EXAMPLE";\n'
    '1\texample\texon\t101\t150\t.\t+\t.\tgene_id "g1"; transcript_id "t1";\n'
)
features = read_gtf(annotation)
genes = features.loc[features["feature"] == "gene"]
print(genes["gene_name"].tolist())
for row in features.itertuples():
    print(row.feature, row.seqname, row.start, row.end, row.gene_id)

['EXAMPLE']
gene 1 101 200 g1
exon 1 101 150 g1

feature identifies the row type. seqname is the chromosome or contig name; it is not the gene ID. The ninth GTF field supplies attributes such as gene_id, gene_name and transcript_id. Coordinates stay one-based and inclusive, as in the file.

Documentation

The guides are Markdown files in docs/. In reading order:

1. Filter and write annotations: select chromosomes and features, write GTF and read numeric attributes.
2. Report parsing progress with your own progress bar.
3. Version 3 migration: pandas by default, and optional Polars output.
4. API reference for every public function.

To build the documentation locally, run python -m pip install -r requirements-docs.txt and ./docs.sh. python scripts/check_docs_examples.py checks the printed example output.

Development

python -m pip install -e ".[dev]"
./lint.sh   # ruff check and ruff format --check
./test.sh   # pytest with coverage

./format.sh applies ruff formatting.

License

Apache 2.0; see LICENSE.