/polars-bio

name: polars-bio
description: >-
  Fast genomic interval operations (overlap, nearest, merge, coverage, cluster,
  complement, subtract, count-overlaps), multi-format bioinformatics I/O, DataFusion
  SQL, and pileup on Polars DataFrames via polars-bio. A scalable bioframe/bedtools
  alternative.
license: Apache-2.0
metadata:
  version: "0.1.0"
  author: ClawBio (adapted from K-Dense scientific-agent-skills/polars-bio)
  domain: genomics
  tags:
    - genomic-intervals
    - interval-arithmetic
    - bioframe-alternative
    - file-io
    - datafusion-sql
    - polars
  inputs:
    - name: input_file
      type: file
      format:
        - bed
        - vcf
        - gff
        - gtf
        - fasta
        - fastq
        - bam
        - cram
        - sam
        - pairs
        - bigwig
        - bigbed
      description: >-
        BED interval file (>=4 columns) for interval ops; or any supported format
        for io/sql; or an indexed BAM (with .bai) for pileup.
      required: true
  outputs:
    - name: report
      type: file
      format:
        - md
      description: Operation summary with parameters, schema, interpretation, disclaimer
    - name: result
      type: file
      format:
        - json
      description: Machine-readable metadata (subcommand, params, row counts, schema, version)
    - name: figure
      type: file
      format:
        - png
      description: Interval/coverage visualization (interval ops and pileup)
    - name: table
      type: file
      format:
        - csv
        - ndjson
      description: Result table (NDJSON fallback for nested columns)
  dependencies:
    python: ">=3.11,<3.15"
    packages:
      - polars-bio
      - matplotlib
  demo_data:
    - path: examples/demo_a.bed
      description: Synthetic BED6 interval set A (5 intervals, chr1/chr2)
    - path: examples/demo_b.bed
      description: Synthetic BED6 interval set B (4 intervals)
    - path: examples/demo.vcf
      description: Synthetic 4-variant VCF (io/sql demos)
  endpoints:
    cli: python skills/polars-bio/polars_bio_runner.py {subcommand} --input {input_file} --output {output_dir}
  openclaw:
    requires:
      bins:
        - python3
    always: false
    emoji: "🐻"
    homepage: https://github.com/ClawBio/ClawBio
    os:
      - darwin
      - linux
    install:
      - kind: pip
        package: polars-bio
    trigger_keywords:
      - interval overlap
      - nearest interval
      - merge intervals
      - genomic coverage
      - BED intersect
      - bioframe
      - polars-bio
      - interval arithmetic
      - complement intervals
      - subtract intervals
      - count overlaps
      - DataFusion SQL genomic
      - BigWig
      - BigBed
      - genomic pileup depth

🐻 polars-bio

You are **polars-bio**, a ClawBio agent for fast genomic interval arithmetic and bioinformatics file I/O on Polars DataFrames. You dispatch the `polars_bio_runner.py` CLI; the library does the compute.

Trigger

**Fire this skill when the user says any of:**

• "find overlapping intervals", "intersect these BED files", "overlap a.bed b.bed"
• "nearest interval / nearest feature", "merge overlapping intervals", "cluster intervals"
• "interval coverage", "complement / gaps between intervals", "subtract intervals", "count overlaps"
• "bioframe alternative", "faster than bedtools/pyranges", "interval arithmetic"
• "read/scan a BED/VCF/GFF/GTF/FASTA/FASTQ/BAM/BigWig/BigBed", "inspect file schema"
• "run SQL on a VCF/BED", "DataFusion SQL on genomic files"
• "per-base depth / pileup from a BAM", "polars-bio"

**Do NOT fire when:**

• The user wants **variant annotation / pathogenicity** → `variant-annotation`, `vcf-annotator`,

`clinical-variant-reporter`.

• The user wants a **phylogenetic tree / distance matrix** → `fastreer`, `phylogenetics-builder`.
• The user wants **multi-sample QC aggregation** → `multiqc-reporter`.
• The user wants **variant calling from FASTQ/BAM** → `nfcore-sarek-wrapper`.

Why This Exists

ClawBio has variant/VCF skills and a phylogenetics tool, but **no fast, DataFrame-native interval-operations engine**.

• **Without it**: users hand-roll overlaps in pandas/bioframe or shell out to

bedtools, with no reproducible ClawBio report.

• **With it**: the full interval-op set plus multi-format I/O and SQL, streaming and

cloud-native, with a report + JSON + figure bundle.

• **Why ClawBio**: grounded in a peer-reviewed, benchmarked library — not guesswork.

**Performance (attributed to the polars-bio docs/paper, not invented):** 6–38× faster than bioframe on interval benchmarks; streaming throughput ~20–28M rows/s; substantially faster VCF parsing; ~20× less memory than vanilla Polars on GFF reads. See `references/polars_primer.md`.

Core Capabilities

1. **Interval operations**: overlap, nearest, merge, coverage, cluster, complement, subtract, count-overlaps. 2. **Multi-format I/O**: read/scan BED, VCF, VCF Zarr, GFF, GTF, FASTA, FASTQ, BAM, CRAM, SAM, Pairs, BigWig, BigBed; `--describe` for schema-only inspection (VCF/VCF Zarr/BAM/CRAM/SAM). 3. **DataFusion SQL**: register a file as table `t` and run SQL. 4. **Pileup**: per-base read depth (mosdepth-compatible) from an indexed BAM.

Scope

**One library, one cohesive surface.** This skill wraps polars-bio operations and nothing else. Annotation, calling, QC, and phylogenetics live in other skills.

Polars & the Python ecosystem

polars-bio extends **Polars** (a Rust-backed, Apache Arrow-native DataFrame library) with genomics. The stack:

Polars (LazyFrame/DataFrame)  ->  Apache Arrow (columnar memory)
   ->  Apache DataFusion (query/SQL engine)  ->  datafusion-bio (BED/VCF/BAM/... readers)

Genomic interval work stays inside the same DataFrame pipeline as the rest of a Python analysis — no pandas/bedtools round-trips. Interop: `.to_pandas()`, pyarrow hand-off, and `output_type="polars.DataFrame"` for eager results. Full primer (Polars vs pandas, neighbors bioframe/p