polars-bio

¿Qué hace polars-bio?

Resumen

polars-bio es una biblioteca Python de alto rendimiento para operaciones con intervalos genómicos y E/S de archivos bioinformáticos, construida sobre Polars, Apache Arrow y Apache DataFusion. Proporciona una API familiar centrada en DataFrames para aritmética de intervalos (superposición, vecino más cercano, fusión, cobertura, complemento, sustracción) y lectura/escritura de formatos bioinformáticos comunes (BED, VCF, BAM, CRAM, GFF/GTF, FASTA, FASTQ).

Propuestas de valor clave:

• 6-38 veces más rápido que bioframe en benchmarks genómicos reales
• Soporte de transmisión/fuera de núcleo para genomas grandes mediante DataFusion
• E/S nativa en la nube (S3, GCS, Azure) con pushdown de predicados
• Dos estilos de API: funcional (pb.overlap(df1, df2)) y encadenamiento de métodos (df1.lazy().pb.overlap(df2))
• Interfaz SQL para datos genómicos mediante el motor SQL de DataFusion

Cuándo Usar Esta Habilidad

Usa esta habilidad cuando:

• Realices operaciones con intervalos genómicos (superposición, vecino más cercano, fusión, cobertura, complemento, sustracción)
• Leas/escribas formatos de archivos bioinformáticos (BED, VCF, BAM, CRAM, GFF/GTF, FASTA, FASTQ)
• Proceses grandes conjuntos de datos genómicos que no caben en memoria (modo de transmisión)
• Ejecutes consultas SQL sobre archivos de datos genómicos
• Migres desde bioframe a una alternativa más rápida
• Calcules profundidad de lectura/cobertura (pileup) a partir de archivos BAM/CRAM
• Trabajes con DataFrames de Polars que contengan intervalos genómicos

Inicio Rápido

Instalación

Requiere Python 3.11–3.14 (ver PyPI).

uv pip install "polars-bio==0.31.0"

Para compatibilidad con pandas (pandas ≥3.0):

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

Ejemplo Básico de Superposición

import polars as pl
import polars_bio as pb

# Crear dos DataFrames de intervalos
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],
})

# API funcional (devuelve LazyFrame por defecto)
result = pb.overlap(df1, df2)
result_df = result.collect()

# Obtener un DataFrame directamente
result_df = pb.overlap(df1, df2, output_type="polars.DataFrame")

# API de encadenamiento de métodos (a través del accessor .pb en LazyFrame)
result = df1.lazy().pb.overlap(df2)
result_df = result.collect()

Leyendo un Archivo BED

import polars_bio as pb

# Lectura eager (carga todo el archivo)
df = pb.read_bed("regions.bed")

# Escaneo lazy (transmisión, para archivos grandes)
lf = pb.scan_bed("regions.bed")
result = lf.collect()

Capacidades Principales

1. Operaciones con Intervalos Genómicos

polars-bio proporciona 8 operaciones principales con intervalos para aritmética de rangos genómicos. Todas las operaciones aceptan DataFrames de Polars con columnas chrom, start, end (configurables). Todas las operaciones devuelven un LazyFrame por defecto (usa output_type="polars.DataFrame" para resultados eager).

Operaciones:

• overlap / count_overlaps - Encontrar o contar intervalos superpuestos entre dos conjuntos (overlap_output="left" devuelve solo aciertos de df1 desde 0.30.0)
• nearest - Encontrar intervalos más cercanos (con parámetros configurables k, overlap, distance)
• merge - Fusionar intervalos superpuestos/contiguos dentro de un conjunto
• cluster - Asignar IDs de clúster a intervalos superpuestos
• coverage - Calcular recuentos de cobertura por intervalo (operación de dos entradas)
• complement - Encontrar huecos entre intervalos dentro de un genoma
• subtract - Eliminar partes de intervalos que se superponen con otro conjunto

Ejemplo:

import polars_bio as pb

# Encontrar intervalos superpuestos (devuelve LazyFrame)
result = pb.overlap(df1, df2, suffixes=("_1", "_2"))

# Contar superposiciones por intervalo
counts = pb.count_overlaps(df1, df2)

# Fusionar intervalos superpuestos
merged = pb.merge(df1)

# Encontrar intervalos más cercanos
nearest = pb.nearest(df1, df2)

# Recolectar cualquier resultado LazyFrame a DataFrame
result_df = result.collect()

Referencia: Consulta references/interval_operations.md para documentación detallada de todas las operaciones, parámetros, esquemas de salida y consideraciones de rendimiento.

2. E/S de Archivos Bioinformáticos

Lee y escribe formatos bioinformáticos comunes con funciones read_*, scan_*, write_* y sink_*. Soporta almacenamiento en la nube (S3, GCS, Azure) y compresión (GZIP, BGZF).

Formatos soportados:

• BED - Intervalos genómicos (read_bed, scan_bed, write_* vía genérica)
• VCF - Variantes genéticas (read_vcf, scan_vcf, write_vcf, sink_vcf)
• VCF Zarr - Almacenes Zarr listos para análisis (read_vcf_zarr, scan_vcf_zarr; rutas de directorio local)
• BAM - Lecturas alineadas (read_bam, scan_bam, write_bam, sink_bam)
• CRAM - Alineamientos comprimidos (read_cram, scan_cram, write_cram, sink_cram)
• GFF - Anotaciones génicas (read_gff, scan_gff)
• GTF - Anotaciones génicas (read_gtf, scan_gtf)
• FASTA - Secuencias de referencia (read_fasta, scan_fasta, write_fasta, sink_fasta)
• FASTQ - Lecturas de secuenciación (read_fastq, scan_fastq, write_fastq, sink_fastq)
• SAM - Alineamientos de texto (read_sam, scan_sam, write_sam, sink_sam)
• Pares Hi-C - Contactos de cromatina (read_pairs, scan_pairs)

Ejemplo:

import polars_bio as pb

# Leer archivo VCF
variants = pb.read_vcf("samples.vcf.gz")

# Escaneo lazy de archivo BAM (transmisión)
alignments = pb.scan_bam("aligned.bam")

# Leer anotaciones GFF
genes = pb.read_gff("annotations.gff3")

# Almacenamiento en la nube (parámetros individuales, no un diccionario)
df = pb.read_bed("s3://bucket/regions.bed",
                 allow_anonymous=True)

Referencia: Consulta references/file_io.md para esquemas de columnas por formato, parámetros, opciones de almacenamiento en la nube y soporte de compresión.

3. Procesamiento de Datos SQL

Registra archivos bioinformáticos como tablas y consúltalos usando SQL de DataFusion. Combina el poder de SQL con los lectores conscientes de genómica de polars-bio.

import polars as pl
import polars_bio as pb

# Registrar archivos como tablas SQL (ruta primero, nombre= palabra clave)
pb.register_vcf("samples.vcf.gz", name="variants")
pb.register_bed("target_regions.bed", name="regions")

# Consultar con SQL (devuelve LazyFrame)
result = pb.sql("SELECT chrom, start, end, ref, alt FROM variants WHERE qual > 30")
result_df = result.collect()

# Registrar un DataFrame de Polars como tabla SQL
pb.from_polars("my_intervals", df)
result = pb.sql("SELECT * FROM my_intervals WHERE chrom = 'chr1'").collect()

Referencia: Consulta references/sql_processing.md para funciones de registro, sintaxis SQL y ejemplos.

4. Operaciones de Pileup (Cobertura por Base)

Calcula la profundidad de lectura por base a partir de archivos BAM/CRAM con cálculo de profundidad consciente de CIGAR.

import polars_bio as pb

# Calcular profundidad en un archivo BAM
depth_lf = pb.depth("aligned.bam")
depth_df = depth_lf.collect()

# Con filtro de calidad
depth_lf = pb.depth("aligned.bam", min_mapping_quality=20)

Referencia: Consulta references/pileup_operations.md para parámetros y patrones de integración.

Conceptos Clave

Sistemas de Coordenadas

polars-bio utiliza por defecto coordenadas basadas en 1 (convención genómica). Esto se puede cambiar globalmente:

import polars_bio as pb

# Cambiar a coordenadas semiabiertas basadas en 0 (por defecto es basado en 1 / False)
pb.set_option("datafusion.bio.coordinate_system_zero_based", True)

# Volver a basado en 1 (por defecto)
pb.set_option("datafusion.bio.coordinate_system_zero_based", False)

Las funciones de E/S también aceptan use_zero_based para establecer metadatos de coordenadas en el DataFrame resultante:

# Leer BED con metadatos explícitos basados en 0
df = pb.read_bed("regions.bed", use_zero_based=True)

Importante: Los archivos BED siempre son semiabiertos basados en 0 en el formato de archivo. polars-bio maneja la conversión automáticamente al leer archivos BED. Los metadatos de coordenadas se adjuntan a los DataFrames mediante funciones de E/S y se propagan a través de las operaciones.

Dos Estilos de API

API funcional - funciones independientes, entradas explícitas:

result = pb.overlap(df1, df2, suffixes=("_1", "_2"))
merged = pb.merge(df)

API de encadenamiento de métodos - a través del accessor .pb en LazyFrames (no DataFrames):

result = df1.lazy().pb.overlap(df2)
merged = df.lazy().pb.merge()

Importante: El accessor .pb para operaciones con intervalos solo está disponible en LazyFrame. En DataFrame, .pb solo proporciona operaciones de escritura (write_bam, write_vcf, etc.).

El encadenamiento de métodos permite pipelines fluidos:

# Encadenar operaciones con intervalos (nota: overlap genera columnas con sufijos,
# así que renombrar antes de merge que espera chrom/start/end)
result = (
    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()
)

Arquitectura de Sonda-Construcción (Probe-Build)

Para operaciones de dos entradas (overlap, nearest, count_overlaps, coverage), polars-bio utiliza una estrategia de combinación sonda-construcción:

• El primer DataFrame es la sonda (se itera sobre él)
• El segundo DataFrame es la construcción (se indexa para búsqueda)

Para mejor rendimiento, pasa el DataFrame más grande como primer argumento (sonda) y el más pequeño como segundo (construcción).

Convenciones de Columnas

Por defecto, polars-bio espera columnas llamadas chrom, start, end. Se pueden especificar nombres de columna personalizados mediante listas:

result = pb.overlap(
    df1, df2,
    cols1=["chromosome", "begin", "finish"],
    cols2=["chr", "pos_start", "pos_end"],
)

Tipos de Retorno y Recolección de Resultados

Todas las operaciones con intervalos y pb.sql() devuelven un LazyFrame por defecto. Usa .collect() para materializar los resultados, o pasa output_type="polars.DataFrame" para evaluación eager:

# Lazy (por defecto) - recolectar cuando sea necesario
result_lf = pb.overlap(df1, df2)
result_df = result_lf.collect()

# Eager - obtener DataFrame directamente
result_df = pb.overlap(df1, df2, output_type="polars.DataFrame")

Transmisión y Procesamiento Fuera de Núcleo

Para conjuntos de datos más grandes que la RAM disponible, usa funciones scan_* y ejecución en transmisión:

# Escanear archivos de forma perezosa
lf = pb.scan_bed("large_intervals.bed")

# Procesar con transmisión de Polars (requiere polars ≥1.37, incluido con polars-bio)
result = lf.collect(engine="streaming")

La transmisión de DataFusion está habilitada por defecto para operaciones con intervalos, procesando datos en lotes sin cargar el conjunto de datos completo en memoria.

Errores Comunes

1. Accessor .pb en DataFrame vs LazyFrame: Las operaciones con intervalos (overlap, merge, etc.) solo están en LazyFrame.pb. DataFrame.pb solo tiene métodos de escritura. Usa .lazy() para convertir antes de encadenar operaciones con intervalos.

2. Retornos de LazyFrame: Todas las operaciones con intervalos y pb.sql() devuelven LazyFrame por defecto. No olvides .collect() o usa output_type="polars.DataFrame".

3. Desajustes de nombres de columna: polars-bio espera chrom, start, end por defecto. Usa los parámetros cols1/cols2 (como listas) si tus columnas tienen nombres diferentes.

4. Metadatos del sistema de coordenadas: Las operaciones con intervalos leen metadatos de coordenadas de funciones de E/S o del config_meta del DataFrame. Para DataFrames construidos manualmente, establece df.config_meta.set(coordinate_system_zero_based=True) (basado en 0) o False (basado en 1). Si faltan metadatos, polars-bio recurre a la configuración global datafusion.bio.coordinate_system_zero_based (con una advertencia). Establece pb.set_option("datafusion.bio.coordinate_system_check", True) para lanzar MissingCoordinateSystemError en su lugar. Sistemas no coincidentes entre entradas lanzan CoordinateSystemMismatchError.

5. El orden de sonda-construcción importa: Para overlap, nearest y coverage, el primer DataFrame se sonda contra el segundo. Intercambiar argumentos cambia qué intervalos aparecen en las columnas de salida izquierda vs derecha, y puede afectar el rendimiento.

6. Límite de posición INT32: Las posiciones genómicas se almacenan como enteros de 32 bits, limitando las coordenadas a ~2.1 mil millones. Esto es suficiente para todos los genomas conocidos, pero puede ser un problema con espacios de coordenadas personalizados.

7. Requisitos de índice BAM: read_bam y scan_bam requieren un archivo de índice .bai junto al BAM. Crea uno con samtools index si falta.

8. Ejecución paralela deshabilitada por defecto: La paralelización de DataFusion por defecto es de 1 partición. Habilita para conjuntos de datos grandes:

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

9. CRAM tiene funciones separadas: Usa read_cram/scan_cram/register_cram para archivos CRAM (no read_bam). Las funciones CRAM requieren un parámetro reference_path.

Mejores Prácticas

1. Usa scan_* para archivos grandes: Prefiere scan_bed, scan_vcf, etc. sobre read_* para archivos más grandes que la RAM disponible. Las funciones de escaneo habilitan transmisión y pushdown de predicados.

2. Configura paralelismo para conjuntos de datos grandes:

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

3. Usa compresión BGZF: Los archivos comprimidos con BGZF (.bed.gz, .vcf.gz) soportan descompresión paralela por bloques, significativamente más rápido que GZIP simple.

4. Selecciona columnas temprano: Cuando solo se necesitan columnas específicas, selecciónalas temprano para reducir el uso de memoria:

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

5. Usa rutas de nube directamente: Pasa URIs de S3/GCS/Azure directamente a funciones read/scan/register en lugar de descargar archivos primero. El acceso autenticado usa las credenciales de tu SDK de nube (AWS_ACCESS_KEY_ID/AWS_SECRET_ACCESS_KEY, GOOGLE_APPLICATION_CREDENTIALS, valores predeterminados de Azure) solo cuando se accede a esas rutas de nube:

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

6. Prefiere API funcional para operaciones individuales, encadenamiento de métodos para pipelines: Usa pb.overlap() para operaciones puntuales y .lazy().pb.overlap() al construir pipelines de múltiples pasos.

Recursos

references/

Documentación detallada para cada capacidad principal:

• interval_operations.md - Las 8 operaciones con intervalos con parámetros, ejemplos, esquemas de salida y consejos de rendimiento. Referencia principal para aritmética de rangos genómicos.

• file_io.md - Tabla de formatos soportados, esquemas de columnas por formato,…

[truncado para traducción]