Skip to main content

Crate streampile

Crate streampile 

Source
Expand description

§streampile

Forward-only pileups streamed from coordinate-sorted BAM records.

A StreamingPileupBuilder reads records once, from an indexed file or an unindexed pipe, and piles them up at the 0-based positions asked for, moving forward only. Each record’s CIGAR is decoded once into a footprint, and a pileup borrows the records it holds, so building one allocates nothing per entry, and per-base auxiliary arrays are read in place. Entries follow htslib: a deletion carries the quality of the read’s next base, a read with no stored qualities has quality 255 at every base, and an N base is a no-call. Insertions are reported at both ends of an alignment.

use noodles::bam;
use streampile::StreamingPileupBuilder;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let mut reader = bam::io::reader::Builder::default().build_from_path("reads.bam")?;
    let header = reader.read_header()?;
    let mut builder = StreamingPileupBuilder::new(reader, &header)?
        .min_mapping_quality(20)
        .min_base_quality(30);

    let mut columns = builder.columns("chr1", 0, 1_000)?;
    while let Some(pileup) = columns.next_pileup() {
        let pileup = pileup?;
        for entry in pileup.iter().filter(|entry| entry.passes(30)) {
            let ends = (entry.five_prime_distance(), entry.template_end_distance()?);
            let base = entry.base().map(char::from);
            println!("{} {:?} {:?}", pileup.position(), base, ends);
        }
    }
    builder.close()?;
    Ok(())
}

The template_end_distance() method counts the template’s bases to the 5′ end of the mate of a read in an FR pair, walking the mate’s CIGAR from the MC tag and never reading the template length (TLEN), and is an error for a read without a usable MC tag that needs one: a forward read whose mate is mapped to its contig on the other strand, or a reverse read of an FR pair. A pair is FR, as is_fr_pair() says, when the forward read’s aligned 5′ position is at or before the reverse read’s, as in htsjdk 5.0.0, so a read of any other pair has no template end. A pileup’s templates() sees each template once, calling the bases of overlapping mates at the quality floor into one with the agreement and disagreement strategies of fgbio’s CallOverlappingConsensusBases, as fgumi implements them. A tap receives every record once, in input order, so records can be written on as they are passed. The functions five_prime_distance, template_end_distance, and is_fr_pair give the same answers for any noodles alignment record. A source of records can be any coordinate-sorted stream, and a record type can carry more beside its BAM record.

§Features

  • libdeflate (default): inflates BGZF blocks with libdeflate, which compiles C code. Build with default-features = false to inflate them in pure Rust.
  • testing: adds streampile::testing, whose SamBuilder builds test records as fgbio’s does and piles them up in memory with a StreamingPileupBuilder.
  • python: builds the streampile._native extension module of the Python package with PyO3. It adds no Rust API and needs a Python interpreter to build.

The same core runs the streampile Python package, which reads records with pysam.

Modules§

testing
Test records built as fgbio’s SamBuilder builds them, with full mate information on pairs, and a way to pile them up in memory with a StreamingPileupBuilder.

Structs§

AuxArray
A numeric array auxiliary field, read element by element from the record’s bytes.
Columns
A forward sweep of the pileup at every position of a span, from columns.
Pileup
The reads at one reference position, borrowed from the builder that built it.
PileupEntry
One read at one pileup position.
PileupTemplate
One template at one pileup position: the reads of one name, their bases called into one.
Records
A RecordSource over any iterator of records.
StreamingPileupBuilder
Builds pileups from coordinate-sorted records in one forward pass.

Enums§

AgreementStrategy
How the quality of a template is made from two of its reads holding the same base.
ArraySubtype
The element type of a numeric array auxiliary field.
AuxElement
One element of a string or array auxiliary field.
AuxValue
The value of a record’s auxiliary field, borrowed from the record without copying.
DisagreementStrategy
How a template’s base and quality are made from two of its reads holding different bases.
EntryKind
What a read holds at a pileup’s position.
Error
An error from building pileups.

Constants§

DEFAULT_EXCLUDE_FLAGS
Secondary, QC-fail, duplicate, and supplementary reads, which are left out by default.
DEFAULT_MIN_BASE_QUALITY
The default minimum base quality of a pileup’s filtered views and template votes, as in pysam’s pileup() and samtools mpileup.
MISSING_BASE_QUALITY
The base quality of every base of a read with no stored qualities (QUAL *), as in htslib.

Traits§

AlignmentRecord
A record a builder piles up: a BAM record, or a BAM record with something its source keeps beside it, such as the object it was read from.
RecordSource
A coordinate-sorted stream of records, which may be an unindexed pipe.

Functions§

five_prime_distance
The distance of a read’s base, at a query offset, from the read’s 5′ end, in bases as sequenced: the offset for a forward read and counted from the other end for a reverse one, so soft-clipped bases count and hard-clipped ones do not. It is None for an offset past the read.
is_fr_pair
Whether a record is a read of an FR pair, as htsjdk 5.0.0’s SamPairUtil.getPairOrientation classifies it (samtools/htsjdk#1771), which fgbio pins.
template_end_distance
The number of the template’s bases between a 0-based reference position of a record and the 5′ end of its mate in an FR pair: 0 at the mate’s 5′ end.

Type Aliases§

Result
A result whose error is an Error.