polars-bio

Was macht polars-bio?

Übersicht

polars-bio ist eine Hochleistungs-Python-Bibliothek für genomische Intervalloperationen und Bioinformatik-Datei-I/O, aufgebaut auf Polars, Apache Arrow und Apache DataFusion. Sie bietet eine vertraute DataFrame-zentrierte API für Intervallarithmetik (Überlappung, nächste, Zusammenführung, Abdeckung, Komplement, Subtraktion) und das Lesen/Schreiben gängiger Bioinformatikformate (BED, VCF, BAM, CRAM, GFF/GTF, FASTA, FASTQ).

Wichtige Wertversprechen:

• 6-38x schneller als bioframe in realen genomischen Benchmarks
• Streaming/Out-of-Core-Unterstützung für große Genome über DataFusion
• Cloud-nativ Datei-I/O (S3, GCS, Azure) mit Prädikat-Pushdown
• Zwei API-Stile: funktional (pb.overlap(df1, df2)) und Method-Chaining (df1.lazy().pb.overlap(df2))
• SQL-Schnittstelle für Genomdaten über die DataFusion-SQL-Engine

Wann dieses Skill verwendet werden sollte

Verwenden Sie dieses Skill, wenn Sie:

• Genomische Intervalloperationen durchführen (Überlappung, nächste, Zusammenführung, Abdeckung, Komplement, Subtraktion)
• Bioinformatik-Dateiformate lesen/schreiben (BED, VCF, BAM, CRAM, GFF/GTF, FASTA, FASTQ)
• Große genomische Datensätze verarbeiten, die nicht in den Arbeitsspeicher passen (Streaming-Modus)
• SQL-Abfragen auf Genomdateien ausführen
• Von bioframe zu einer schnelleren Alternative migrieren
• Lesetiefe/Pileup aus BAM/CRAM-Dateien berechnen
• Mit Polars DataFrames arbeiten, die genomische Intervalle enthalten

Kurzanleitung

Installation

Erfordert Python 3.11–3.14 (siehe PyPI).

uv pip install "polars-bio==0.31.0"

Für pandas-Kompatibilität (pandas ≥3.0):

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

Grundlegendes Überlappungsbeispiel

import polars as pl
import polars_bio as pb

# Erstelle zwei Intervall-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],
})

# Funktionale API (gibt standardmäßig LazyFrame zurück)
ergebnis = pb.overlap(df1, df2)
ergebnis_df = ergebnis.collect()

# Erhalte direkt einen DataFrame
ergebnis_df = pb.overlap(df1, df2, output_type="polars.DataFrame")

# Method-Chaining-API (über .pb-Accessor auf LazyFrame)
ergebnis = df1.lazy().pb.overlap(df2)
ergebnis_df = ergebnis.collect()

Lesen einer BED-Datei

import polars_bio as pb

# Eager-Lesen (lädt gesamte Datei)
df = pb.read_bed("regions.bed")

# Lazy-Scan (Streaming, für große Dateien)
lf = pb.scan_bed("regions.bed")
ergebnis = lf.collect()

Kernfunktionen

1. Genomische Intervalloperationen

polars-bio bietet 8 Kern-Intervalloperationen für genomische Bereichsarithmetik. Alle Operationen akzeptieren Polars DataFrames mit den Spalten chrom, start, end (konfigurierbar). Alle Operationen geben standardmäßig ein LazyFrame zurück (verwenden Sie output_type="polars.DataFrame" für sofortige Ergebnisse).

Operationen:

• overlap / count_overlaps - Finden oder zählen sich überlappender Intervalle zwischen zwei Sätzen (overlap_output="left" gibt nur Treffer aus df1 seit 0.30.0)
• nearest - Finden der nächsten Intervalle (mit konfigurierbaren k-, overlap-, distance-Parametern)
• merge - Zusammenführen sich überlappender/aneinandergrenzender Intervalle innerhalb eines Satzes
• cluster - Zuweisen von Cluster-IDs zu sich überlappenden Intervallen
• coverage - Berechnen von Abdeckungszahlen pro Intervall (Zwei-Eingabe-Operation)
• complement - Finden von Lücken zwischen Intervallen innerhalb eines Genoms
• subtract - Entfernen von Teilen von Intervallen, die einen anderen Satz überlappen

Beispiel:

import polars_bio as pb

# Finde sich überlappende Intervalle (gibt LazyFrame zurück)
ergebnis = pb.overlap(df1, df2, suffixes=("_1", "_2"))

# Zähle Überlappungen pro Intervall
anzahl = pb.count_overlaps(df1, df2)

# Führe sich überlappende Intervalle zusammen
zusammengefuehrt = pb.merge(df1)

# Finde die nächsten Intervalle
naechste = pb.nearest(df1, df2)

# Sammle jedes LazyFrame-Ergebnis in ein DataFrame
ergebnis_df = ergebnis.collect()

Referenz: Siehe references/interval_operations.md für detaillierte Dokumentation aller Operationen, Parameter, Ausgabeschemata und Leistungsüberlegungen.

2. Bioinformatik-Datei-I/O

Lesen und Schreiben gängiger Bioinformatikformate mit den Funktionen read_*, scan_*, write_* und sink_*. Unterstützt Cloud-Speicher (S3, GCS, Azure) und Komprimierung (GZIP, BGZF).

Unterstützte Formate:

• BED - Genomische Intervalle (read_bed, scan_bed, write_* über generisch)
• VCF - Genetische Varianten (read_vcf, scan_vcf, write_vcf, sink_vcf)
• VCF Zarr - Analysebereite Zarr-Stores (read_vcf_zarr, scan_vcf_zarr; lokale Verzeichnispfade)
• BAM - Alignierte Reads (read_bam, scan_bam, write_bam, sink_bam)
• CRAM - Komprimierte Alignments (read_cram, scan_cram, write_cram, sink_cram)
• GFF - Genannotationen (read_gff, scan_gff)
• GTF - Genannotationen (read_gtf, scan_gtf)
• FASTA - Referenzsequenzen (read_fasta, scan_fasta, write_fasta, sink_fasta)
• FASTQ - Sequenzierungsreads (read_fastq, scan_fastq, write_fastq, sink_fastq)
• SAM - Text-Alignments (read_sam, scan_sam, write_sam, sink_sam)
• Hi-C-Paare - Chromatinkontakte (read_pairs, scan_pairs)

Beispiel:

import polars_bio as pb

# Lesen einer VCF-Datei
varianten = pb.read_vcf("proben.vcf.gz")

# Lazy-Scan einer BAM-Datei (Streaming)
alignments = pb.scan_bam("aligned.bam")

# Lesen von GFF-Annotationen
gene = pb.read_gff("annotationen.gff3")

# Cloud-Speicher (einzelne Parameter, kein Dict)
df = pb.read_bed("s3://bucket/regionen.bed",
                 allow_anonymous=True)

Referenz: Siehe references/file_io.md für Spaltenschemata pro Format, Parameter, Cloud-Speicheroptionen und Komprimierungsunterstützung.

3. SQL-Datenverarbeitung

Registrieren Sie Bioinformatikdateien als Tabellen und fragen Sie sie mit der DataFusion SQL ab. Kombiniert die Leistungsfähigkeit von SQL mit den genomisch bewussten Readern von polars-bio.

import polars as pl
import polars_bio as pb

# Registriere Dateien als SQL-Tabellen (Pfad zuerst, name= als Schlüsselwortargument)
pb.register_vcf("proben.vcf.gz", name="varianten")
pb.register_bed("zielregionen.bed", name="regionen")

# Abfrage mit SQL (gibt LazyFrame zurück)
ergebnis = pb.sql("SELECT chrom, start, end, ref, alt FROM varianten WHERE qual > 30")
ergebnis_df = ergebnis.collect()

# Registriere einen Polars DataFrame als SQL-Tabelle
pb.from_polars("meine_intervalle", df)
ergebnis = pb.sql("SELECT * FROM meine_intervalle WHERE chrom = 'chr1'").collect()

Referenz: Siehe references/sql_processing.md für Registerfunktionen, SQL-Syntax und Beispiele.

4. Pileup-Operationen

Berechnen Sie die pro-Base-Lesetiefe aus BAM/CRAM-Dateien mit CIGAR-bewusster Tiefenberechnung.

import polars_bio as pb

# Berechne Tiefe über eine BAM-Datei
tiefe_lf = pb.depth("aligned.bam")
tiefe_df = tiefe_lf.collect()

# Mit Qualitätsfilter
tiefe_lf = pb.depth("aligned.bam", min_mapping_quality=20)

Referenz: Siehe references/pileup_operations.md für Parameter und Integrationsmuster.

Schlüsselkonzepte

Koordinatensysteme

polars-bio verwendet standardmäßig 1-basierte Koordinaten (genomische Konvention). Dies kann global geändert werden:

import polars_bio as pb

# Wechsel zu 0-basierten halboffenen Koordinaten (Standard ist 1-basiert / False)
pb.set_option("datafusion.bio.coordinate_system_zero_based", True)

# Zurück zu 1-basiert (Standard)
pb.set_option("datafusion.bio.coordinate_system_zero_based", False)

I/O-Funktionen akzeptieren auch use_zero_based, um Koordinatenmetadaten im resultierenden DataFrame zu setzen:

# Lese BED mit expliziten 0-basierten Metadaten
df = pb.read_bed("regionen.bed", use_zero_based=True)

Wichtig: BED-Dateien sind im Dateiformat immer 0-basiert halboffen. polars-bio übernimmt die Konvertierung automatisch beim Lesen von BED-Dateien. Koordinatenmetadaten werden von I/O-Funktionen an DataFrames angehängt und durch Operationen propagiert.

Zwei API-Stile

Funktionale API - eigenständige Funktionen, explizite Eingaben:

ergebnis = pb.overlap(df1, df2, suffixes=("_1", "_2"))
zusammengefuehrt = pb.merge(df)

Method-Chaining-API - über .pb-Accessor auf LazyFrames (nicht DataFrames):

ergebnis = df1.lazy().pb.overlap(df2)
zusammengefuehrt = df.lazy().pb.merge()

Wichtig: Der .pb-Accessor für Intervalloperationen ist nur auf LazyFrame verfügbar. Auf DataFrame bietet .pb nur Schreiboperationen (write_bam, write_vcf, etc.).

Method-Chaining ermöglicht fließende Pipelines:

# Verkette Intervalloperationen (Hinweis: overlap gibt Spalten mit Suffixen aus,
# daher vor merge umbenennen, das chrom/start/end erwartet)
ergebnis = (
    df1.lazy()
    .pb.overlap(df2)
    .filter(pl.col("start_2") > 1000)
    .select(
        pl.col("chrom_1").alias("chrom"),
        pl.col("start_1").alias("start"),
        pl.col("end_1").alias("end"),
    )
    .pb.merge()
    .collect()
)

Probe-Build-Architektur

Für Zwei-Eingabe-Operationen (overlap, nearest, count_overlaps, coverage) verwendet polars-bio eine Probe-Build-Join-Strategie:

• Der erste DataFrame ist die Probe (über die iteriert wird)
• Der zweite DataFrame ist der Build (für die Suche indiziert)

Für beste Leistung übergeben Sie den größeren DataFrame als erstes Argument (Probe) und den kleineren als zweites (Build).

Spaltenkonventionen

Standardmäßig erwartet polars-bio Spalten mit den Namen chrom, start, end. Benutzerdefinierte Spaltennamen können über Listen angegeben werden:

ergebnis = pb.overlap(
    df1, df2,
    cols1=["chromosom", "anfang", "ende"],
    cols2=["chr", "pos_start", "pos_end"],
)

Rückgabetypen und Sammeln von Ergebnissen

Alle Intervalloperationen und pb.sql() geben standardmäßig ein LazyFrame zurück. Verwenden Sie .collect(), um Ergebnisse zu materialisieren, oder übergeben Sie output_type="polars.DataFrame" für sofortige Auswertung:

# Lazy (Standard) - sammle bei Bedarf
ergebnis_lf = pb.overlap(df1, df2)
ergebnis_df = ergebnis_lf.collect()

# Eager - erhalte direkt DataFrame
ergebnis_df = pb.overlap(df1, df2, output_type="polars.DataFrame")

Streaming und Out-of-Core-Verarbeitung

Verwenden Sie für Datensätze, die größer als der verfügbare Arbeitsspeicher sind, scan_*-Funktionen und Streaming-Ausführung:

# Scanne Dateien lazy
lf = pb.scan_bed("grosse_intervalle.bed")

# Verarbeite mit Polars-Streaming (erfordert polars ≥1.37, das mit polars-bio gebündelt ist)
ergebnis = lf.collect(engine="streaming")

DataFusion-Streaming ist standardmäßig für Intervalloperationen aktiviert und verarbeitet Daten in Batches, ohne den vollständigen Datensatz in den Arbeitsspeicher zu laden.

Häufige Fallstricke

1. .pb-Accessor auf DataFrame vs LazyFrame: Intervalloperationen (overlap, merge, etc.) sind nur auf LazyFrame.pb verfügbar. DataFrame.pb hat nur Schreibmethoden. Verwenden Sie .lazy(), um vor dem Verketten von Intervallops zu konvertieren.

2. LazyFrame-Rückgaben: Alle Intervalloperationen und pb.sql() geben standardmäßig LazyFrame zurück. Vergessen Sie nicht .collect() oder verwenden Sie output_type="polars.DataFrame".

3. Spaltennamen-Konflikte: polars-bio erwartet standardmäßig chrom, start, end. Verwenden Sie die Parameter cols1/cols2 (als Listen), wenn Ihre Spalten andere Namen haben.

4. Koordinatensystem-Metadaten: Intervalloperationen lesen Koordinatenmetadaten von I/O-Funktionen oder dem DataFrame config_meta. Setzen Sie für manuell erstellte DataFrames df.config_meta.set(coordinate_system_zero_based=True) (0-basiert) oder False (1-basiert). Wenn Metadaten fehlen, fällt polars-bio auf die globale Einstellung datafusion.bio.coordinate_system_zero_based zurück (mit einer Warnung). Setzen Sie pb.set_option("datafusion.bio.coordinate_system_check", True), um stattdessen MissingCoordinateSystemError auszulösen. Unterschiedliche Systeme zwischen Eingaben lösen CoordinateSystemMismatchError aus.

5. Probe-Build-Reihenfolge ist wichtig: Bei overlap, nearest und coverage wird der erste DataFrame gegen den zweiten geprüft. Das Vertauschen der Argumente ändert, welche Intervalle in den linken vs. rechten Ausgabespalten erscheinen, und kann die Leistung beeinflussen.

6. INT32-Positionsgrenze: Genomische Positionen werden als 32-Bit-Ganzzahlen gespeichert, was Koordinaten auf ~2,1 Milliarden begrenzt. Dies ist für alle bekannten Genome ausreichend, könnte aber bei benutzerdefinierten Koordinatenräumen ein Problem sein.

7. BAM-Index-Anforderungen: read_bam und scan_bam erfordern eine .bai-Indexdatei neben der BAM. Erstellen Sie eine mit samtools index, falls nicht vorhanden.

8. Parallele Ausführung standardmäßig deaktiviert: DataFusion-Parallelität standardmäßig auf 1 Partition. Aktivieren Sie sie für große Datensätze:

   pb.set_option("datafusion.execution.target_partitions", 8)
   

9. CRAM hat separate Funktionen: Verwenden Sie read_cram/scan_cram/register_cram für CRAM-Dateien (nicht read_bam). CRAM-Funktionen erfordern einen Parameter reference_path.

Best Practices

1. Verwenden Sie scan_* für große Dateien: Bevorzugen Sie scan_bed, scan_vcf, etc. gegenüber read_* für Dateien, die größer als der verfügbare Arbeitsspeicher sind. Scan-Funktionen ermöglichen Streaming und Prädikat-Pushdown.

2. Konfigurieren Sie Parallelität für große Datensätze:

   import os
   pb.set_option("datafusion.execution.target_partitions", os.cpu_count())
   

3. Verwenden Sie BGZF-Komprimierung: BGZF-komprimierte Dateien (.bed.gz, .vcf.gz) unterstützen parallele Block-Dekomprimierung, die deutlich schneller als einfaches GZIP ist.

4. Wählen Sie Spalten frühzeitig aus: Wenn nur bestimmte Spalten benötigt werden, wählen Sie sie frühzeitig aus, um die Speichernutzung zu reduzieren:

   df = pb.read_vcf("gross.vcf.gz").select("chrom", "start", "end", "ref", "alt")
   

5. Verwenden Sie Cloud-Pfade direkt: Übergeben Sie S3/GCS/Azure-URIs direkt an Lese-/Scan-/Register-Funktionen, anstatt Dateien zuerst herunterzuladen. Authentifizierter Zugriff verwendet Ihre Cloud-SDK-Anmeldeinformationen (AWS_ACCESS_KEY_ID/AWS_SECRET_ACCESS_KEY, GOOGLE_APPLICATION_CREDENTIALS, Azure-Standardwerte) nur, wenn auf diese Cloud-Pfade zugegriffen wird:

   df = pb.read_bed("s3://my-bucket/regionen.bed", allow_anonymous=True)
   

6. Bevorzugen Sie die funktionale API für einzelne Operationen, Method-Chaining für Pipelines: Verwenden Sie pb.overlap() für einmalige Operationen und .lazy().pb.overlap(), wenn Sie mehrstufige Pipelines erstellen.

Ressourcen

references/

Detaillierte Dokumentation für jede Hauptfunktion:

• interval_operations.md - Alle 8 Intervalloperationen mit Parametern, Beispielen, Ausgabeschemata und Leistungstipps. Kernreferenz für genomische Bereichsarithmetik.

• file_io.md - Tabelle der unterstützten Formate, Spaltenschemata pro Format, Parameter, Cloud-Speicheroptionen und Komprimierungsunterstützung. Vollständige I/O-Parameterdokumentation.

• sql_processing.md - SQL-Tabellenregistrierung, Beispiele und Syntaxreferenz. Vollständige Anleitung zum Abfragen von Genomdaten mit SQL.

• pileup_operations.md - Tiefenberechnungsparameter, Filteroptionen und Integrationsmuster für BAM/CRAM-Pileup.

Weitere Informationen

• Beiträge: Siehe CONTRIBUTING.md für Richtlinien, wie Sie zu polars-bio beitragen können.
• Lizenz: Apache-2.0