htslurp

A noodles-based htsget client that lazily deserializes alignment records in memory. It provides a Rust API with Python bindings, so you can consume remote CRAM/BAM records over the network without storing them locally.

Documentation: https://cmdoret.github.io/htslurp/

Install

pip install htslurp

Usage

import htslurp

records = htslurp.stream_records(
    "https://htsget.ga4gh.org/reads",
    "giab.NA12878",
    "CRAM",
    region="11:4900000-5000000",
)

header_text = records.header.decode()
for line in records:
    fields = line.decode().split("\t")
    # ... or feed `line.decode()` and a pysam.AlignmentHeader built from
    # `header_text` to pysam.AlignedSegment.fromstring.

See the quickstart for more.

Context

The aim is to provide a convenient interface to consume remote CRAM/BCF records over the network without storing them locally. The noodles crate fetches a binary stream from the server and builds a reader over it that lazily instantiates records.

flowchart LR
    htsget[htsget-server] -->|bytes| Reader
    Reader -->|Cram records| python

Development

This project requires: * a working rust (>=1.76) and python (>=3.10) installation * maturin * uv * just

To build the python package:

just build

To install in editable mode for development:

just develop

To preview the docs locally:

just docs