polars-bio

polars-bio

概述

polars-bio 是一个高性能 Python 库，用于基因组区间操作和生物信息学文件 I/O，基于 Polars、Apache Arrow 和 Apache DataFusion 构建。它提供熟悉的、以 DataFrame 为中心的 API，用于区间运算（重叠、最近邻、合并、覆盖度、补集、相减）以及读取和写入常见的生物信息学格式（BED、VCF、BAM、CRAM、GFF/GTF、FASTA、FASTQ）。

核心优势：

• 在真实基因组基准测试中，速度比 bioframe 快 6–38 倍
• 通过 DataFusion 支持大型基因组的流式处理/外存计算
• 云原生文件 I/O（S3、GCS、Azure），支持谓词下推
• 两种 API 风格：函数式（pb.overlap(df1, df2)）和方法链式（df1.lazy().pb.overlap(df2)）
• 通过 DataFusion SQL 引擎为基因组数据提供 SQL 接口

何时使用此技能

适用于以下场景：

• 执行基因组区间操作（重叠、最近邻、合并、覆盖度、补集、相减）
• 读取/写入生物信息学文件格式（BED、VCF、BAM、CRAM、GFF/GTF、FASTA、FASTQ）
• 处理无法装入内存的大型基因组数据集（流式模式）
• 对基因组数据文件运行 SQL 查询
• 从 bioframe 迁移到更快的替代方案
• 根据 BAM/CRAM 文件计算读段深度/堆积
• 使用包含基因组区间的 Polars DataFrame

快速入门

安装

需要 Python 3.11–3.14（参见 PyPI）。

uv pip install "polars-bio==0.31.0"

如需兼容 pandas（pandas ≥3.0）：

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

基本重叠示例

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()

读取 BED 文件

import polars_bio as pb

# Eager read (loads entire file)
df = pb.read_bed("regions.bed")

# Lazy scan (streaming, for large files)
lf = pb.scan_bed("regions.bed")
result = lf.collect()

核心功能

1. 基因组区间操作

polars-bio 提供 8 种核心区间操作，用于基因组范围运算。所有操作均接受包含 chrom、start、end 列（可配置）的 Polars DataFrame。所有操作默认返回 LazyFrame（如需立即计算结果，请使用 output_type="polars.DataFrame"）。

操作：

• overlap / count_overlaps - 查找或统计两组之间重叠的区间（自 0.30.0 起，overlap_output="left" 会仅返回 df1 中命中的区间）
• nearest - 查找最近区间（可配置 k、overlap、distance 参数）
• merge - 合并一组中重叠或首尾相接的区间
• cluster - 为重叠区间分配簇 ID
• coverage - 计算每个区间的覆盖计数（双输入操作）
• complement - 查找基因组中区间之间的空隙
• subtract - 移除与另一组区间重叠的部分

示例：

import polars_bio as pb

# Find overlapping intervals (returns LazyFrame)
result = pb.overlap(df1, df2, suffixes=("_1", "_2"))

# Count overlaps per interval
counts = pb.count_overlaps(df1, df2)

# Merge overlapping intervals
merged = pb.merge(df1)

# Find nearest intervals
nearest = pb.nearest(df1, df2)

# Collect any LazyFrame result to DataFrame
result_df = result.collect()

**参考：**有关所有操作、参数、输出架构和性能注意事项的详细文档，请参阅 references/interval_operations.md。

2. 生物信息学文件 I/O

使用 read_*、scan_*、write_* 和 sink_* 函数读取和写入常见的生物信息学格式。支持云存储（S3、GCS、Azure）和压缩格式（GZIP、BGZF）。

支持的格式：

• BED - 基因组区间（read_bed、scan_bed、通过通用接口使用 write_*）
• VCF - 遗传变异（read_vcf、scan_vcf、write_vcf、sink_vcf）
• VCF Zarr - 可用于分析的 Zarr 存储（read_vcf_zarr、scan_vcf_zarr；本地目录路径）
• BAM - 比对后的读段（read_bam、scan_bam、write_bam、sink_bam）
• CRAM - 压缩比对文件（read_cram、scan_cram、write_cram、sink_cram）
• GFF - 基因注释（read_gff、scan_gff）
• GTF - 基因注释（read_gtf、scan_gtf）
• FASTA - 参考序列（read_fasta、scan_fasta、write_fasta、sink_fasta）
• FASTQ - 测序读段（read_fastq、scan_fastq、write_fastq、sink_fastq）
• SAM - 文本比对文件（read_sam、scan_sam、write_sam、sink_sam）
• Hi-C pairs - 染色质接触（read_pairs、scan_pairs）

示例：

import polars_bio as pb

# Read VCF file
variants = pb.read_vcf("samples.vcf.gz")

# Lazy scan BAM file (streaming)
alignments = pb.scan_bam("aligned.bam")

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

# Cloud storage (individual params, not a dict)
df = pb.read_bed("s3://bucket/regions.bed",
                 allow_anonymous=True)

**参考：**有关各格式的列架构、参数、云存储选项和压缩支持，请参阅 references/file_io.md。

3. SQL 数据处理

将生物信息学文件注册为表，并使用 DataFusion SQL 进行查询。结合 SQL 的强大功能与 polars-bio 对基因组数据的感知型读取器。

import polars as pl
import polars_bio as pb

# Register files as SQL tables (path first, name= keyword)
pb.register_vcf("samples.vcf.gz", name="variants")
pb.register_bed("target_regions.bed", name="regions")

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

# Register a Polars DataFrame as a SQL table
pb.from_polars("my_intervals", df)
result = pb.sql("SELECT * FROM my_intervals WHERE chrom = 'chr1'").collect()

**参考：**请参阅 references/sql_processing.md，了解注册函数、SQL 语法和示例。

4. Pileup 操作

使用考虑 CIGAR 的深度计算，从 BAM/CRAM 文件计算每个碱基的读段深度。

import polars_bio as pb

# Compute depth across a BAM file
depth_lf = pb.depth("aligned.bam")
depth_df = depth_lf.collect()

# With quality filter
depth_lf = pb.depth("aligned.bam", min_mapping_quality=20)

**参考：**请参阅 references/pileup_operations.md，了解参数和集成模式。

核心概念

坐标系

polars-bio 默认使用 1-based 坐标（基因组惯例）。可全局更改此设置：

import polars_bio as pb

# Switch to 0-based half-open coordinates (default is 1-based / False)
pb.set_option("datafusion.bio.coordinate_system_zero_based", True)

# Switch back to 1-based (default)
pb.set_option("datafusion.bio.coordinate_system_zero_based", False)

I/O 函数还接受 use_zero_based，用于设置结果 DataFrame 的坐标元数据：

# Read BED with explicit 0-based metadata
df = pb.read_bed("regions.bed", use_zero_based=True)

**重要：**BED 文件格式始终使用 0-based 半开区间。读取 BED 文件时，polars-bio 会自动进行转换。I/O 函数会将坐标元数据附加到 DataFrame，并在操作过程中传递这些元数据。

两种 API 风格

函数式 API——独立函数，显式传入输入：

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

方法链式 API——通过 LazyFrame（而非 DataFrame）上的 .pb 访问器调用：

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

**重要：**用于区间操作的 .pb 访问器仅适用于 LazyFrame。在 DataFrame 上，.pb 仅提供写入操作（write_bam、write_vcf 等）。

方法链式调用支持流畅的管道操作：

# Chain interval operations (note: overlap outputs suffixed columns,
# so rename before merge which expects 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()
)

Probe-Build 架构

对于双输入操作（overlap、nearest、count_overlaps、coverage），polars-bio 使用 probe-build 连接策略：

• 第一个 DataFrame 是 probe（遍历对象）
• 第二个 DataFrame 是 build（建立索引以供查询）

为获得最佳性能，请将较大的 DataFrame 作为第一个参数（probe），较小的 DataFrame 作为第二个参数（build）。

列约定

默认情况下，polars-bio 预期列名为 chrom、start、end。可通过列表指定自定义列名：

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

返回类型与收集结果

所有区间操作和 pb.sql() 默认均返回 LazyFrame。使用 .collect() 将结果物化，或传入 output_type="polars.DataFrame" 以进行即时求值：

# Lazy (default) - collect when needed
result_lf = pb.overlap(df1, df2)
result_df = result_lf.collect()

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

流式处理与外存处理

对于大于可用 RAM 的数据集，请使用 scan_* 函数和流式执行：

# Scan files lazily
lf = pb.scan_bed("large_intervals.bed")

# Process with Polars streaming (requires polars ≥1.37, bundled with polars-bio)
result = lf.collect(engine="streaming")

区间操作默认启用 DataFusion 流式处理，以批次方式处理数据，而无需将完整数据集载入内存。

常见陷阱

1. DataFrame 与 LazyFrame 上的 .pb 访问器： 区间操作（重叠、合并等）仅适用于 LazyFrame.pb。DataFrame.pb 只有写入方法。请先使用 .lazy() 转换，再链接区间操作。

2. LazyFrame 返回值： 所有区间操作和 pb.sql() 默认都返回 LazyFrame。别忘了调用 .collect()，或使用 output_type="polars.DataFrame"。

3. 列名不匹配： polars-bio 默认要求 chrom、start、end。如果列名不同，请使用 cols1/cols2 参数（以列表形式传入）。

4. 坐标系元数据： 区间操作会从 I/O 函数或 DataFrame config_meta 中读取坐标元数据。对于手动构建的 DataFrame，请设置 df.config_meta.set(coordinate_system_zero_based=True)（0-based）或 False（1-based）。如果缺少元数据，polars-bio 会回退到全局 datafusion.bio.coordinate_system_zero_based 设置（并发出警告）。设置 pb.set_option("datafusion.bio.coordinate_system_check", True) 可改为抛出 MissingCoordinateSystemError。输入之间的坐标系不匹配会引发 CoordinateSystemMismatchError。

5. 探测与构建的顺序很重要： 对于重叠、最近邻和覆盖率操作，第一个 DataFrame 会与第二个进行比对。交换参数会改变哪些区间出现在左侧与右侧输出列中，也可能影响性能。

6. INT32 位置限制： 基因组位置以 32 位整数存储，因此坐标限制在约 21 亿以内。这足以涵盖所有已知基因组，但自定义坐标空间可能会遇到问题。

7. BAM 索引要求： read_bam 和 scan_bam 要求 BAM 文件旁有 .bai 索引文件。如果缺少索引，请使用 samtools index 创建。

8. 默认禁用并行执行： DataFusion 默认使用 1 个分区进行并行处理。处理大型数据集时请启用：

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

9. CRAM 使用独立函数： 处理 CRAM 文件时请使用 read_cram/scan_cram/register_cram（不要使用 read_bam）。CRAM 函数需要 reference_path 参数。

最佳实践

1. 大型文件使用 scan_*： 对于大于可用 RAM 的文件，优先使用 scan_bed、scan_vcf 等函数，而不是 read_*。扫描函数支持流式处理和谓词下推。

2. 为大型数据集配置并行处理：

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

3. 使用 BGZF 压缩： BGZF 压缩文件（.bed.gz、.vcf.gz）支持并行块解压，速度显著快于普通 GZIP。

4. 尽早选择列： 如果只需要特定列，请尽早选择，以减少内存使用：

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

5. 直接使用云端路径： 将 S3/GCS/Azure URI 直接传递给读取/扫描/注册函数，而不是先下载文件。只有在访问这些云端路径时，经过身份验证的访问才会使用云 SDK 凭据（AWS_ACCESS_KEY_ID/AWS_SECRET_ACCESS_KEY、GOOGLE_APPLICATION_CREDENTIALS、Azure 默认凭据）：

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

6. 单次操作优先使用函数式 API，流水线优先使用方法链： 单次操作请使用 pb.overlap()；构建多步流水线时，请使用 .lazy().pb.overlap()。

资源

references/

各项主要功能的详细文档：

• interval_operations.md - 全部 8 种区间操作，包括参数、示例、输出架构和性能提示。基因组范围运算的核心参考资料。

• file_io.md - 支持的格式表、各格式的列架构、云存储配置、压缩支持和常用参数。

• sql_processing.md - 注册函数、DataFusion SQL 语法、结合 SQL 与区间操作，以及示例查询。

• pileup_operations.md - 从 BAM/CRAM 文件计算逐碱基读取深度、相关参数，以及与区间操作的集成。

• configuration.md - 全局设置（并行度、坐标系、流式处理模式）、日志记录和元数据管理。

• bioframe_migration.md - 操作映射表、API 差异、性能比较、迁移代码示例，以及 pandas 兼容模式。

Agent 操作流程

1. 检查环境。 确认工具版本、参考基因组/注释版本和输入格式（FASTQ、BAM、VCF、h5ad）。
2. 明确输入。 根据数据或用户确认格式、标识符和参数。对于任何会影响结果的值，不要猜测，应先询问。
3. 先运行小规模版本。 先用较小的子集（一个样本、一条染色体、几千个细胞）运行流程。
4. 按照上述说明和参考资料执行完整任务。
5. 验证结果。 在解读结果前，检查 QC 指标、样本身份、基因组版本一致性和批次效应。
6. 报告。 说明运行了什么（版本、命令、参数）、检查了什么，以及哪些方面仍不确定。

如果发生这种情况	应执行的操作
输入之间的基因组版本或标识符不匹配	停止并先统一（liftover、ID 映射），再继续。
这些说明中提到的函数、标志或端点在已安装版本中缺失	查阅已安装版本自身的文档（help()、--help、官方文档），调整操作并告知用户。切勿杜撰 API。
必需的输入、标识符或参数不明确	询问用户，或在运行前明确说明所作假设。

诚信规则

• 切勿伪造结果、参数、标识符、引文或统计数据。如果无法运行或验证某项内容，应明确说明。
• 不要作出超出统计数据支持范围的生物学意义解读；报告多重检验校正。
• 此处与特定版本相关的细节可能已过时：请对照已安装版本的官方文档进行确认。
• 对于会产生费用、占用共享 GPU 或云配额、涉及个人或患者数据，或无法撤销的操作，必须先征求同意。

相关技能

• pysam：用于基因组文件的 Python/HTSlib 工作流。
• gtars：使用 Gtars（用于基因组区间的 Rust/Python/CLI 工具包）检查和规划工作：BED RegionSet 集合运算（reduce、setdiff、intersec…
• genomic-coordinates：在坐标约定之间转换基因组区间、规范化并比较变异表示形式，以及检测组装版本或 contig 名称差异…