Struct noodles_bam::reader::Reader
source · [−]pub struct Reader<R> { /* private fields */ }
Expand description
A BAM reader.
A BAM file is an encoded and compressed version of a SAM file. While a SAM file has a header and a list of records, a BAM is comprised of three parts:
- a SAM header,
- a list of reference sequences, and
- a list of encoded SAM records.
The reader reads records sequentially but can use virtual positions to seek to offsets from the start of a seekable stream.
Examples
use noodles_bam as bam;
let mut reader = File::open("sample.bam").map(bam::Reader::new)?;
reader.read_header()?;
reader.read_reference_sequences()?;
for result in reader.records() {
let record = result?;
println!("{:?}", record);
}
Implementations
sourceimpl<R> Reader<R> where
R: Read,
impl<R> Reader<R> where
R: Read,
sourcepub fn get_ref(&self) -> &R
pub fn get_ref(&self) -> &R
Returns a reference to the underlying reader.
Examples
use noodles_bam as bam;
let data = [];
let reader = bam::Reader::from(&data[..]);
assert!(reader.get_ref().is_empty());
sourcepub fn get_mut(&mut self) -> &mut R
pub fn get_mut(&mut self) -> &mut R
Returns a mutable reference to the underlying reader.
Examples
use noodles_bam as bam;
let data = [];
let mut reader = bam::Reader::from(&data[..]);
assert!(reader.get_mut().is_empty());
sourcepub fn into_inner(self) -> R
pub fn into_inner(self) -> R
Returns the underlying reader.
Examples
use noodles_bam as bam;
let data = [];
let reader = bam::Reader::from(&data[..]);
assert!(reader.into_inner().is_empty());
sourcepub fn read_header(&mut self) -> Result<String>
pub fn read_header(&mut self) -> Result<String>
Reads the raw SAM header.
The BAM magic number is also checked.
The position of the stream is expected to be at the start.
This returns the raw SAM header as a String
. It can subsequently be parsed as a
noodles_sam::Header
.
Examples
use noodles_bam as bam;
let mut reader = File::open("sample.bam").map(bam::Reader::new)?;
let header = reader.read_header()?;
sourcepub fn read_reference_sequences(&mut self) -> Result<ReferenceSequences>
pub fn read_reference_sequences(&mut self) -> Result<ReferenceSequences>
Reads the binary reference sequences after the SAM header.
This is not the same as the @SQ
records in the SAM header. A BAM has a list of reference
sequences containing name and length tuples after the SAM header and before the list of
records.
The position of the stream is expected to be directly after the header.
This returns a reference sequence dictionary (noodles_sam::header::ReferenceSequences
),
which can be used to build a minimal noodles_sam::Header
if the SAM header is empty.
Examples
use noodles_bam as bam;
let mut reader = File::open("sample.bam").map(bam::Reader::new)?;
reader.read_header()?;
let reference_sequences = reader.read_reference_sequences()?;
sourcepub fn read_record(&mut self, record: &mut Record) -> Result<usize>
pub fn read_record(&mut self, record: &mut Record) -> Result<usize>
Reads a single record.
The record block size (bs
) is read from the underlying stream and bs
bytes are read
into an internal buffer. This buffer is used to populate 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 Record
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::Record;
let mut reader = File::open("sample.bam").map(bam::Reader::new)?;
reader.read_header()?;
reader.read_reference_sequences()?;
let mut record = Record::default();
reader.read_record(&mut record)?;
sourcepub fn read_lazy_record(&mut self, record: &mut Record) -> Result<usize>
pub fn read_lazy_record(&mut self, record: &mut Record) -> Result<usize>
Reads a single record without eagerly decoding its fields.
The record block size (bs
) is read from the underlying stream and bs
bytes are read
into the lazy record’s buffer. No fields are decoded, meaning the record is not necessarily
valid. However, the structure of the byte stream 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::Reader::new)?;
reader.read_header()?;
reader.read_reference_sequences()?;
let mut record = bam::lazy::Record::default();
reader.read_lazy_record(&mut record)?;
sourcepub fn records(&mut self) -> Records<'_, R>ⓘNotable traits for Records<'a, R>impl<'a, R> Iterator for Records<'a, R> where
R: Read, type Item = Result<Record>;
pub fn records(&mut self) -> Records<'_, R>ⓘNotable traits for Records<'a, R>impl<'a, R> Iterator for Records<'a, R> where
R: Read, type Item = Result<Record>;
R: Read, type Item = Result<Record>;
Returns an iterator over records 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::Reader::new)?;
reader.read_header()?;
reader.read_reference_sequences()?;
for result in reader.records() {
let record = result?;
println!("{:?}", record);
}
sourcepub fn lazy_records(&mut self) -> LazyRecords<'_, R>ⓘNotable traits for LazyRecords<'a, R>impl<'a, R> Iterator for LazyRecords<'a, R> where
R: Read, type Item = Result<Record>;
pub fn lazy_records(&mut self) -> LazyRecords<'_, R>ⓘNotable traits for LazyRecords<'a, R>impl<'a, R> Iterator for LazyRecords<'a, R> where
R: Read, type Item = Result<Record>;
R: Read, type Item = Result<Record>;
Returns an iterator over lazy 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::Reader::new)?;
reader.read_header()?;
reader.read_reference_sequences()?;
for result in reader.lazy_records() {
let record = result?;
// ...
}
sourceimpl<R> Reader<Reader<R>> where
R: Read,
impl<R> Reader<Reader<R>> where
R: Read,
sourcepub fn new(reader: R) -> Self
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::Reader::new(&data[..]);
sourcepub fn virtual_position(&self) -> VirtualPosition
pub fn virtual_position(&self) -> VirtualPosition
Returns the current virtual position of the underlying BGZF reader.
Examples
use noodles_bam as bam;
let data = Vec::new();
let reader = bam::Reader::new(&data[..]);
let virtual_position = reader.virtual_position();
assert_eq!(virtual_position.compressed(), 0);
assert_eq!(virtual_position.uncompressed(), 0);
sourceimpl<R> Reader<Reader<R>> where
R: Read + Seek,
impl<R> Reader<Reader<R>> where
R: Read + Seek,
sourcepub fn seek(&mut self, pos: VirtualPosition) -> Result<VirtualPosition>
pub fn seek(&mut self, pos: VirtualPosition) -> Result<VirtualPosition>
Seeks the underlying BGZF reader to the given virtual position.
Virtual positions typically come from the associated BAM index file.
Examples
use noodles_bam as bam;
use noodles_bgzf as bgzf;
let mut reader = bam::Reader::new(Cursor::new(Vec::new()));
let virtual_position = bgzf::VirtualPosition::default();
reader.seek(virtual_position)?;
sourcepub fn query<I>(
&mut self,
reference_sequences: &ReferenceSequences,
index: &I,
region: &Region
) -> Result<Query<'_, R>> where
I: BinningIndex,
pub fn query<I>(
&mut self,
reference_sequences: &ReferenceSequences,
index: &I,
region: &Region
) -> Result<Query<'_, R>> where
I: BinningIndex,
Returns an iterator over records that intersect the given region.
Examples
use noodles_bam::{self as bam, bai};
use noodles_core::Region;
use noodles_sam as sam;
let mut reader = File::open("sample.bam").map(bam::Reader::new)?;
let header: sam::Header = reader.read_header()?.parse()?;
let reference_sequences = header.reference_sequences();
let index = bai::read("sample.bam.bai")?;
let region = "sq0:8-13".parse()?;
let query = reader.query(reference_sequences, &index, ®ion)?;
for result in query {
let record = result?;
println!("{:?}", record);
}
sourcepub fn query_unmapped(
&mut self,
index: &Index
) -> Result<UnmappedRecords<'_, R>>
pub fn query_unmapped(
&mut self,
index: &Index
) -> Result<UnmappedRecords<'_, R>>
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::Reader::new)?;
let index = bai::read("sample.bam.bai")?;
let query = reader.query_unmapped(&index)?;
for result in query {
let record = result?;
println!("{:?}", record);
}
Trait Implementations
sourceimpl<R> AlignmentReader for Reader<R> where
R: Read,
impl<R> AlignmentReader for Reader<R> where
R: Read,
sourcefn read_alignment_header(&mut self) -> Result<Header>
fn read_alignment_header(&mut self) -> Result<Header>
Reads a SAM header.
sourcefn alignment_records<'a>(
&'a mut self,
_: &'a Repository,
_: &'a Header
) -> Box<dyn Iterator<Item = Result<Record>> + 'a>
fn alignment_records<'a>(
&'a mut self,
_: &'a Repository,
_: &'a Header
) -> Box<dyn Iterator<Item = Result<Record>> + 'a>
Returns an iterator over records.
Auto Trait Implementations
impl<R> RefUnwindSafe for Reader<R> where
R: RefUnwindSafe,
impl<R> Send for Reader<R> where
R: Send,
impl<R> Sync for Reader<R> where
R: Sync,
impl<R> Unpin for Reader<R> where
R: Unpin,
impl<R> UnwindSafe for Reader<R> where
R: UnwindSafe,
Blanket Implementations
sourceimpl<T> BorrowMut<T> for T where
T: ?Sized,
impl<T> BorrowMut<T> for T where
T: ?Sized,
const: unstable · sourcefn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
Mutably borrows from an owned value. Read more
sourceimpl<T> Instrument for T
impl<T> Instrument for T
sourcefn instrument(self, span: Span) -> Instrumented<Self>
fn instrument(self, span: Span) -> Instrumented<Self>
sourcefn in_current_span(self) -> Instrumented<Self>
fn in_current_span(self) -> Instrumented<Self>
sourceimpl<T> WithSubscriber for T
impl<T> WithSubscriber for T
sourcefn with_subscriber<S>(self, subscriber: S) -> WithDispatch<Self> where
S: Into<Dispatch>,
fn with_subscriber<S>(self, subscriber: S) -> WithDispatch<Self> where
S: Into<Dispatch>,
Attaches the provided Subscriber
to this type, returning a
WithDispatch
wrapper. Read more
sourcefn with_current_subscriber(self) -> WithDispatch<Self>
fn with_current_subscriber(self) -> WithDispatch<Self>
Attaches the current default Subscriber
to this type, returning a
WithDispatch
wrapper. Read more