polars-bio

polars-bio

Overview

polars-bio is a high-performance Python library for genomic interval operations and bioinformatics file I/O, built on Polars, Apache Arrow, and Apache DataFusion. It provides a familiar DataFrame-centric API for interval arithmetic (overlap, nearest, merge, coverage, complement, subtract) and reading/writing common bioinformatics formats (BED, VCF, BAM, CRAM, GFF/GTF, FASTA, FASTQ).

Key value propositions:

• 6-38x faster than bioframe on real-world genomic benchmarks
• Streaming/out-of-core support for large genomes via DataFusion
• Cloud-native file I/O (S3, GCS, Azure) with predicate pushdown
• Two API styles: functional (pb.overlap(df1, df2)) and method-chaining (df1.lazy().pb.overlap(df2))
• SQL interface for genomic data via DataFusion SQL engine

When to Use This Skill

Use this skill when:

• Performing genomic interval operations (overlap, nearest, merge, coverage, complement, subtract)
• Reading/writing bioinformatics file formats (BED, VCF, BAM, CRAM, GFF/GTF, FASTA, FASTQ)
• Processing large genomic datasets that don't fit in memory (streaming mode)
• Running SQL queries on genomic data files
• Migrating from bioframe to a faster alternative
• Computing read depth/pileup from BAM/CRAM files
• Working with Polars DataFrames containing genomic intervals

Quick Start

Installation

Requires Python 3.11–3.14 (see PyPI).

uv pip install "polars-bio==0.31.0"

For pandas compatibility (pandas ≥3.0):

uv pip install "polars-bio[pandas]==0.31.0"

Basic Overlap Example

import polars as pl
import polars_bio as pb

# Create two interval DataFrames
df1 = pl.DataFrame({
    "chrom": ["chr1", "chr1", "chr1"],
    "start": [1, 5, 22],
    "end":   [6, 9, 30],
})

df2 = pl.DataFrame({
    "chrom": ["chr1", "chr1"],
    "start": [3, 25],
    "end":   [8, 28],
})

# Functional API (returns LazyFrame by default)
result = pb.overlap(df1, df2)
result_df = result.collect()

# Get a DataFrame directly
result_df = pb.overlap(df1, df2, output_type="polars.DataFrame")

# Method-chaining API (via .pb accessor on LazyFrame)
result = df1.lazy().pb.overlap(df2)
result_df = result.collect()