Struct bam::bam_reader::IndexedReader

pub struct IndexedReader<R: Read + Seek> { /* fields omitted */ }

BAM file reader. In contrast to BamReader the IndexedReader allows to fetch records from arbitrary positions, but does not allow to read all records consecutively.

The following code would load BAM file in.bam and its index in.bam.bai, take all records from 3:600001-700000 and print them on the stdout.

extern crate bam;

use std::io;
// You need to import RecordWriter to write records
use bam::RecordWriter;

fn main() {
    let mut reader = bam::IndexedReader::from_path("in.bam").unwrap();
    let output = io::BufWriter::new(io::stdout());
    let mut writer = bam::SamWriter::build()
        .write_header(false)
        .from_stream(output, reader.header().clone()).unwrap();

    for record in reader.fetch(&bam::Region::new(2, 600_000, 700_000)).unwrap() {
        writer.write(&record.unwrap()).unwrap();
    }
}

Additionally, you can use read_into(&mut record) to save time on record allocation (you would need to use RecordReader trait):

extern crate bam;

use std::io;
use bam::{RecordReader, RecordWriter};

fn main() {
    let mut reader = bam::IndexedReader::from_path("in.bam").unwrap();
    let output = io::BufWriter::new(io::stdout());
    let mut writer = bam::SamWriter::build()
        .write_header(false)
        .from_stream(output, reader.header().clone()).unwrap();

    let mut viewer = reader.fetch(&bam::Region::new(1, 100_000, 200_000)).unwrap();
    let mut record = bam::Record::new();
    loop {
        match viewer.read_into(&mut record) {
            Ok(true) => {},
            Ok(false) => break,
            Err(e) => panic!("{}", e),
        }
        writer.write(&record).unwrap();
    }
}

If only records with specific MAPQ or FLAGs are needed, you can use fetch_by. For example,

reader.fetch_by(&bam::Region::new(1, 100_000, 200_000),
    |record| record.mapq() >= 30 && !record.flag().is_secondary())

to load only records with MAPQ at least 30 and skip all secondary alignments. In some cases it helps to save time by not calculating the right-most aligned read position, as well as skip unnecessary allocations.

You can also use IndexedReaderBuilder, which gives more control over loading IndexedReader. For example you can create a reader using a different BAI path, and with additional threads:

let mut reader = bam::IndexedReader::build()
    .bai_path("other_dir/test.bai")
    .additional_threads(4)
    .from_path("in.bam").unwrap();

To read all records from an indexed BAM file you can use methods full and full_by.

To fetch unmapped records from an indexed BAM file you can use methods unmapped and unmapped_by. You can safely call fetch, full and unmapped in any order.

By default, during the construction of the IndexedReader, we compare modification times of the BAI index and the BAM file. If the index is older, the function returns an error. This can be changed:

use bam::bam_reader::ModificationTime;
let mut reader = bam::IndexedReader::build()
    .modification_time(ModificationTime::warn(|e| eprintln!("{}", e)))
    .from_path("in.bam").unwrap();

You can also ignore the error completely: .modification_time(ModificationTime::Ignore).

Implementations

impl IndexedReader<File>

pub fn build() -> IndexedReaderBuilder

Creates IndexedReaderBuilder.

pub fn from_path<P: AsRef<Path>>(path: P) -> Result<Self>

Opens bam file from path. Bai index will be loaded from {path}.bai.

Same as Self::build().from_path(path).

impl<R: Read + Seek> IndexedReader<R>

pub fn fetch<'a>(&'a mut self, region: &Region) -> Result<RegionViewer<'a, R>>

Returns an iterator over records aligned to the reference region.

pub fn fetch_by<'a, F>(
    &'a mut self,
    region: &Region,
    predicate: F
) -> Result<RegionViewer<'a, R>> where
    F: 'static + Fn(&Record) -> bool, 

Returns an iterator over records aligned to the reference region.

Records will be filtered by predicate. It helps to slightly reduce fetching time, as some records will be removed without allocating new memory and without calculating alignment length.

pub fn full<'a>(&'a mut self) -> RegionViewer<'a, R>

Returns an iterator over all records from the start of the BAM file.

pub fn full_by<'a, F>(&'a mut self, predicate: F) -> RegionViewer<'a, R> where
    F: 'static + Fn(&Record) -> bool, 

Returns an iterator over all records from the start of the BAM file.

Records will be filtered by predicate, which allows to skip some records without allocating new memory.

pub fn unmapped<'a>(&'a mut self) -> RegionViewer<'a, R>

Returns an iterator over unmapped records at the end of the BAM file.

pub fn unmapped_by<'a, F>(&'a mut self, predicate: F) -> RegionViewer<'a, R> where
    F: 'static + Fn(&Record) -> bool, 

Returns an iterator over unmapped records at the end of the BAM file.

Records will be filtered by predicate, which allows to skip some records without allocating new memory.

pub fn fetch_chunks<'a, I>(&'a mut self, chunks: I) -> RegionViewer<'a, R> where
    I: IntoIterator<Item = Chunk>, 

Returns an iterator over records at the specific offsets into the BAM file (see Chunk).

pub fn fetch_chunks_by<'a, F, I>(
    &'a mut self,
    chunks: I,
    predicate: F
) -> RegionViewer<'a, R> where
    F: 'static + Fn(&Record) -> bool,
    I: IntoIterator<Item = Chunk>, 

Returns an iterator over records at the specific offsets into the BAM file (see Chunk).

Records will be filtered by predicate. It helps to slightly reduce fetching time, as some records will be removed without allocating new memory and without calculating alignment length.

pub fn header(&self) -> &Header

Returns header.

pub fn index(&self) -> &Index

Returns BAI index.

pub fn pause(&mut self)

Pauses multi-thread reader until the next read operation. Does nothing to a single-thread reader.

Use with caution: pausing and unpausing takes some time.

pub fn current_offset(&self) -> VirtualOffset

Returns current virtual offset.

If the reader has not started, returns the start of the first chunk. If the reader finished the current queue, returns the end of the last chunk.