Metadata-Version: 2.4
Name: gtfparse
Version: 3.0.4
Summary: Parsing library for extracting data frames of genomic features from GTF files
Author-email: Alex Rubinsteyn <alex.rubinsteyn@unc.edu>
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/openvax/gtfparse
Project-URL: Bug Tracker, https://github.com/openvax/gtfparse/issues
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Operating System :: OS Independent
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pyarrow>=18.0.0
Requires-Dist: pandas>=2.2.2
Provides-Extra: polars
Requires-Dist: polars>=0.20.31; extra == "polars"
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Requires-Dist: ruff; extra == "dev"
Requires-Dist: coveralls; extra == "dev"
Dynamic: license-file

[![Tests](https://github.com/openvax/gtfparse/actions/workflows/tests.yml/badge.svg)](https://github.com/openvax/gtfparse/actions/workflows/tests.yml)
[![Coverage Status](https://coveralls.io/repos/openvax/gtfparse/badge.svg?branch=master&service=github)](https://coveralls.io/github/openvax/gtfparse?branch=master)
<a href="https://pypi.python.org/pypi/gtfparse/">
    <img src="https://img.shields.io/pypi/v/gtfparse.svg?maxAge=1000" alt="PyPI" />
</a>

gtfparse
========
Read GTF (gene transfer format) annotations into a pandas DataFrame, with one
row per feature and attribute values such as gene and transcript IDs expanded
into columns.

## Install

```sh
python -m pip install gtfparse
```

Python 3.9 or later is required. For optional Polars output, install
`gtfparse[polars]`.

## Read an annotation and find genes

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

```python
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)
```

```text
['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`.


<a id="version-3-migration"></a>
<a id="reporting-parsing-progress"></a>
<a id="example-usage"></a>
<a id="parsing-all-rows-of-a-gtf-file-into-a-pandas-dataframe"></a>
<a id="getting-gene-fpkm-values-from-a-stringtie-gtf-file"></a>

## Documentation

- [Filter features, select chromosomes, write GTF and read numeric attributes](docs/guides/annotations.md)
- [Progress callbacks](docs/guides/progress.md)
- [Version 3 migration and optional Polars output](docs/guides/migration.md)
- [Complete API reference](docs/reference.md)

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.
