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 withdefault-features = falseto inflate them in pure Rust.testing: addsstreampile::testing, whoseSamBuilderbuilds test records as fgbio’s does and piles them up in memory with aStreamingPileupBuilder.python: builds thestreampile._nativeextension 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
SamBuilderbuilds them, with full mate information on pairs, and a way to pile them up in memory with aStreamingPileupBuilder.
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.
- Pileup
Entry - One read at one pileup position.
- Pileup
Template - One template at one pileup position: the reads of one name, their bases called into one.
- Records
- A
RecordSourceover any iterator of records. - Streaming
Pileup Builder - Builds pileups from coordinate-sorted records in one forward pass.
Enums§
- Agreement
Strategy - How the quality of a template is made from two of its reads holding the same base.
- Array
Subtype - 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.
- Disagreement
Strategy - How a template’s base and quality are made from two of its reads holding different bases.
- Entry
Kind - 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()andsamtools mpileup. - MISSING_
BASE_ QUALITY - The base quality of every base of a read with no stored qualities (QUAL
*), as in htslib.
Traits§
- Alignment
Record - 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.
- Record
Source - 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
Nonefor 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.getPairOrientationclassifies 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.