polars-bio 是一个面向基因组区间运算与生物信息学文件 I/O 的高性能 Python 库，构建在 Polars、Apache Arrow 和 Apache DataFusion 之上。它提供以 DataFrame 为中心的 API，用于区间算术（overlap、nearest、merge、coverage、complement、subtract）以及常见生物信息学格式（BED、VCF、BAM、CRAM、GFF/GTF、FASTA、FASTQ）的读写。
主要能力
-
基因组区间运算：提供 8 种核心区间操作，包括 overlap / count_overlaps（查找或计数重叠区间）、nearest（查找最近区间，可配置 k、overlap、distance 参数）、merge（合并重叠或首尾相接的区间）、cluster（为重叠区间分配簇 ID）、coverage（计算每个区间的覆盖计数）、complement（查找基因组内区间之间的空隙）、subtract（移除与另一集合重叠的部分）。所有操作默认接受含 chrom、start、end 列的 Polars DataFrame，默认返回 LazyFrame，可通过 output_type="polars.DataFrame" 获取即时结果。
-
生物信息学文件 I/O：支持 BED、VCF、VCF Zarr、BAM、CRAM、GFF、GTF、FASTA、FASTQ、SAM、Hi-C pairs 等格式，提供 read_、scan_、write_、sink_ 函数。支持云存储（S3、GCS、Azure）和压缩（GZIP、BGZF）。
-
SQL 数据处理：可将生物信息学文件注册为表，使用 DataFusion SQL 查询，也可将 Polars DataFrame 注册为 SQL 表。
-
Pileup 操作：从 BAM/CRAM 文件计算逐碱基读取深度，支持 CIGAR 感知的深度计算和映射质量过滤。
使用方式
安装：需要 Python 3.11–3.14，使用 uv pip install "polars-bio==0.31.0"；如需 pandas 兼容（pandas ≥3.0），使用 uv pip install "polars-bio[pandas]==0.31.0"。
两种 API 风格：函数式 API（如 pb.overlap(df1, df2)）和方法链式 API（如 df1.lazy().pb.overlap(df2)）。注意 .pb 访问器上的区间操作仅适用于 LazyFrame；DataFrame 上的 .pb 仅提供写入操作。
坐标系统：默认使用 1-based 坐标，可通过 pb.set_option("datafusion.bio.coordinate_system_zero_based", True) 切换为 0-based 半开区间。BED 文件始终为 0-based 半开格式，polars-bio 读取时自动转换。
流式与核外处理：对于超出内存的数据集，使用 scan_* 函数和流式执行（lf.collect(engine="streaming")）。DataFusion 流式处理默认对区间操作启用。
适用场景
适用于执行基因组区间操作、读写生物信息学文件格式、处理无法放入内存的大型基因组数据集（流式模式）、对基因组数据文件运行 SQL 查询、从 bioframe 迁移到更快的替代方案、从 BAM/CRAM 文件计算读取深度/pileup，以及处理包含基因组区间的 Polars DataFrame。
限制与注意事项
- 区间操作和 pb.sql() 默认返回 LazyFrame，需调用 .collect() 或指定 output_type。
- 默认期望列名为 chrom、start、end，可通过 cols1/cols2 参数自定义。
- 双输入操作采用 probe-build 连接策略，第一个 DataFrame 为 probe，第二个为 build；建议将较大的 DataFrame 作为第一个参数以获得最佳性能。
- 基因组位置以 32 位整数存储，坐标上限约 21 亿。
- read_bam 和 scan_bam 需要 .bai 索引文件。
- DataFusion 并行度默认仅 1 个分区，大数据集需通过 pb.set_option("datafusion.execution.target_partitions", ...) 启用。
- CRAM 使用独立函数（read_cram/scan_cram/register_cram），需要 reference_path 参数。
- 坐标系统元数据缺失时会回退到全局设置并发出警告；输入间坐标系统不匹配会引发 CoordinateSystemMismatchError。
- 官方称在真实基因组基准上比 bioframe 快 6-38 倍。
具体版本功能、参数细节和最新变化请以官方文档为准。