From 4677fb6842ee468dc79b562e0b0e3e219a1dd92d Mon Sep 17 00:00:00 2001
From: Alex Rubinsteyn <alex.rubinsteyn@gmail.com>
Date: Mon, 14 Sep 2026 12:18:16 -0400
Subject: [PATCH] Fix README examples for the Polars DataFrame read_gtf returns

read_gtf returns a Polars DataFrame by default, so the pandas-style
boolean-mask indexing in the first example raises ValueError. The
StringTie example keyed its dict by seqname and filtered on "gene"
features, which StringTie GTFs don't contain, so it always produced an
empty dict. Use DataFrame.filter, key transcript FPKMs by transcript_id,
note result_type="pandas", and show a gene_id lookup.

Closes #13

Claude-Session: https://claude.ai/code/session_01DctgBZ5rJiuNzpWXqrNguT
---
 README.md            | 24 ++++++++++++++----------
 gtfparse/__init__.py |  2 +-
 2 files changed, 15 insertions(+), 11 deletions(-)

diff --git a/README.md b/README.md
index 8f711ba..f854b0a 100644
--- a/README.md
+++ b/README.md
@@ -10,9 +10,13 @@ Parsing tools for GTF (gene transfer format) files.
 
 # Example usage
 
-## Parsing all rows of a GTF file into a Pandas DataFrame
+## Parsing all rows of a GTF file into a DataFrame
+
+`read_gtf` returns a Polars DataFrame. Pass `result_type="pandas"` to get a
+pandas DataFrame instead.
 
 ```python
+import polars
 from gtfparse import read_gtf
 
 # returns GTF with essential columns such as "feature", "seqname", "start", "end"
@@ -20,26 +24,26 @@ from gtfparse import read_gtf
 df = read_gtf("gene_annotations.gtf")
 
 # filter DataFrame to gene entries on chrY
-df_genes = df[df["feature"] == "gene"]
-df_genes_chrY = df_genes[df_genes["seqname"] == "Y"]
+df_genes = df.filter(polars.col("feature") == "gene")
+df_genes_chrY = df_genes.filter(polars.col("seqname") == "Y")
+
+# all rows (gene, transcripts, exons, ...) for one gene
+df_tp53 = df.filter(polars.col("gene_id") == "ENSG00000141510")
 ```
 
 
-## Getting gene FPKM values from a StringTie GTF file
+## Getting transcript FPKM values from a StringTie GTF file
 
 ```python
+import polars
 from gtfparse import read_gtf
 
 df = read_gtf(
     "Transcripts.gtf",
     column_converters={"FPKM": float})
 
-gene_fpkms = {
-    gene_name: fpkm
-    for (gene_name, fpkm, feature)
-    in zip(df["seqname"], df["FPKM"], df["feature"])
-    if feature == "gene"
-}
+transcripts = df.filter(polars.col("feature") == "transcript")
+transcript_fpkms = dict(zip(transcripts["transcript_id"], transcripts["FPKM"]))
 ```
 
 
diff --git a/gtfparse/__init__.py b/gtfparse/__init__.py
index 7b83e16..bbf3afb 100644
--- a/gtfparse/__init__.py
+++ b/gtfparse/__init__.py
@@ -24,7 +24,7 @@
 )
 from .write_gtf import write_gtf
 
-__version__ = "2.8.0"
+__version__ = "2.8.1"
 
 __all__ = [
     "GENCODE_BIOTYPE_ALIASES",