Struct Reader

Source

pub struct Reader<R> { /* private fields */ }

Expand description

A BAM reader.

The BAM format is an encoded and compressed version of a SAM format.

The reader reads records sequentially but can use virtual positions to seek to offsets from the start of a seekable stream.

§Examples

§Read from a file

use noodles_bam as bam;

let mut reader = File::open("sample.bam").map(bam::io::Reader::new)?;
let header = reader.read_header()?;

for result in reader.records() {
    let record = result?;
    // ...
}

§Use a custom BGZF decoder

Reader::new wraps the input stream with a default BGZF decoder. This can be swapped for a custom decoder, e.g., flate2::read::MultiGzDecoder, noodles_bgzf::MultithreadedReader, etc., using Reader::from.

§`flate2::read::MultiGzDecoder`

use flate2::read::MultiGzDecoder;
use noodles_bam as bam;

let decoder = MultiGzDecoder::new(io::empty());
let _reader = bam::io::Reader::from(decoder);

§`noodles_bgzf::MultithreadedReader`

use noodles_bam as bam;
use noodles_bgzf as bgzf;

let worker_count = thread::available_parallelism().unwrap_or(NonZeroUsize::MIN);
let decoder = bgzf::MultithreadedReader::with_worker_count(worker_count, io::empty());
let _reader = bam::io::Reader::from(decoder);

Implementations§

Source §

impl<R> Reader<R>

Source

pub fn get_ref(&self) -> &R

Returns a reference to the underlying reader.

§Examples

use noodles_bam as bam;
let reader = bam::io::Reader::from(io::empty());
let _inner = reader.get_ref();

Source

pub fn get_mut(&mut self) -> &mut R

Returns a mutable reference to the underlying reader.

§Examples

use noodles_bam as bam;
let mut reader = bam::io::Reader::from(io::empty());
let _inner = reader.get_mut();

Source

pub fn into_inner(self) -> R

Returns the underlying reader.

§Examples

use noodles_bam as bam;
let reader = bam::io::Reader::from(io::empty());
let _inner = reader.into_inner();

Source §

impl<R> Reader<R>
where R: Read,

Source

pub fn read_header(&mut self) -> Result<Header>

Reads the SAM header.

This verifies the BAM magic number, reads and parses the raw SAM header, and reads the binary reference sequences. If the SAM header has a reference sequence dictionary, it must match the binary reference sequences; otherwise, the binary reference sequences are added to the SAM header.

The position of the stream is expected to be at the start.

§Examples

use noodles_bam as bam;
let mut reader = File::open("sample.bam").map(bam::io::Reader::new)?;
let header = reader.read_header()?;

Source

pub fn read_record_buf( &mut self, _header: &Header, record: &mut RecordBuf, ) -> Result<usize>

Reads a record into an alignment record buffer.

The record block size (bs) is read from the underlying stream and bs bytes are read into an internal buffer. This buffer is then used to decode fields into the given record.

The stream is expected to be directly after the reference sequences or at the start of another record.

It is more ergonomic to read records using an iterator (see Self::records and Self::query), but using this method directly allows the reuse of a single RecordBuf buffer.

If successful, the record block size is returned. If a block size of 0 is returned, the stream reached EOF.

§Examples

use noodles_bam as bam;
use noodles_sam::alignment::RecordBuf;

let mut reader = File::open("sample.bam").map(bam::io::Reader::new)?;
let header = reader.read_header()?;

let mut record = RecordBuf::default();
reader.read_record_buf(&header, &mut record)?;

Source

pub fn read_record(&mut self, record: &mut Record) -> Result<usize>

Reads a record.

The record block size (bs) is read from the underlying stream and bs bytes are read into the record’s buffer. No fields are decoded, meaning the record is not necessarily valid. However, the structure of the buffer is guaranteed to be record-like.

The stream is expected to be directly after the reference sequences or at the start of another record.

If successful, the record block size is returned. If a block size of 0 is returned, the stream reached EOF.

§Examples

use noodles_bam as bam;

let mut reader = File::open("sample.bam").map(bam::io::Reader::new)?;
reader.read_header()?;

let mut record = bam::Record::default();
reader.read_record(&mut record)?;

Source

pub fn record_bufs<'a>(&'a mut self, header: &'a Header) -> RecordBufs<'_, R> ⓘ

Returns an iterator over alignment record buffers starting from the current stream position.

The stream is expected to be directly after the reference sequences or at the start of another record.

§Examples

use noodles_bam as bam;

let mut reader = File::open("sample.bam").map(bam::io::Reader::new)?;
let header = reader.read_header()?;

for result in reader.record_bufs(&header) {
    let record = result?;
    println!("{:?}", record);
}

Source

pub fn records(&mut self) -> Records<'_, R> ⓘ

Returns an iterator over records.

The stream is expected to be directly after the reference sequences or at the start of another record.

§Examples

use noodles_bam as bam;

let mut reader = File::open("sample.bam").map(bam::io::Reader::new)?;
reader.read_header()?;

for result in reader.records() {
    let record = result?;
    // ...
}

Source §

impl<R> Reader<Reader<R>>
where R: Read,

Source

pub fn new(reader: R) -> Self

Creates a BAM reader.

The given reader must be a raw BGZF stream, as the underlying reader wraps it in a decoder.

§Examples

use noodles_bam as bam;
let data = [];
let reader = bam::io::Reader::new(&data[..]);

Source §

impl<R> Reader<R>
where R: BufRead + Seek,

Source

pub fn query<I>( &mut self, header: &Header, index: &I, region: &Region, ) -> Result<Query<'_, R>>
where I: BinningIndex,

Returns an iterator over records that intersect the given region.

To query for unmapped records, use Self::query_unmapped.

§Examples

use noodles_bam::{self as bam, bai};

let mut reader = File::open("sample.bam").map(bam::io::Reader::new)?;
let header = reader.read_header()?;

let index = bai::read("sample.bam.bai")?;
let region = "sq0:8-13".parse()?;
let query = reader.query(&header, &index, &region)?;

for result in query {
    let record = result?;
    // ...
}

Source

pub fn query_unmapped<'r, I>( &'r mut self, index: &I, ) -> Result<impl Iterator<Item = Result<Record>> + 'r>
where I: BinningIndex,

Returns an iterator of unmapped records after querying for the unmapped region.

§Examples

use noodles_bam::{self as bam, bai};

let mut reader = File::open("sample.bam").map(bam::io::Reader::new)?;
reader.read_header()?;

let index = bai::read("sample.bam.bai")?;
let query = reader.query_unmapped(&index)?;

for result in query {
    let record = result?;
    // ...
}