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;

fn main() {
    let mut reader = bam::IndexedReader::from_path("in.bam").unwrap();

    // We need to clone the header to have access to reference names as the
    // reader will be blocked during fetch.
    let header = reader.header().clone();
    let mut stdout = std::io::BufWriter::new(std::io::stdout());

    for record in reader.fetch(2, 600_000, 700_000).unwrap() {
        record.unwrap().write_sam(&mut stdout, &header).unwrap();
    }
}

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

extern crate bam;

// You need to import RecordReader trait
use bam::RecordReader;

fn main() {
    let mut reader = bam::IndexedReader::from_path("in.bam").unwrap();

    let header = reader.header().clone();
    let mut stdout = std::io::BufWriter::new(std::io::stdout());

    let mut viewer = reader.fetch(1, 100_000, 200_000).unwrap();
    let mut record = bam::Record::new();
    loop {
        match viewer.read_into(&mut record) {
            Ok(()) => {},
            Err(bam::Error::NoMoreRecords) => break,
            Err(e) => panic!("{}", e),
        }
        record.write_sam(&mut stdout, &header).unwrap();
    }
}

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

reader.fetch_by(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 a different cache capacity:

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

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).

Methods

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,
    ref_id: u32,
    start: u32,
    end: u32
) -> Result<RegionViewer<'a, R>>

Returns an iterator over records aligned to the reference ref_id (0-based), and intersecting half-open interval [start-end).

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

Returns an iterator over records aligned to the reference ref_id (0-based), and intersecting half-open interval [start-end).

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 write_record_as_sam<W: Write>(
    &self,
    writer: &mut W,
    record: &Record
) -> Result<()>

Writes record in sam format. Same as Record::write_sam.