Struct noodles_bam::AsyncReader

pub struct AsyncReader<R> where
    R: AsyncRead,  { /* fields omitted */ }

An async BAM reader.

Examples

use futures::TryStreamExt;
use noodles_bam as bam;
use tokio::fs::File;

let mut reader = File::open("sample.bam").await.map(bam::AsyncReader::new)?;
reader.read_header().await?;
reader.read_reference_sequences().await?;

let mut records = reader.records();

while let Some(record) = records.try_next().await? {
    // ...
}

Implementations

impl<R> Reader<R> where
    R: AsyncRead + Unpin, 

pub fn builder(inner: R) -> Builder<R>

Creates an async BAM reader builder.

Examples

use noodles_bam as bam;
let data = [];
let builder = bam::AsyncReader::builder(&data[..]);
let reader = builder.build();

pub fn new(reader: R) -> Self

Creates an async BAM reader.

Examples

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

pub async 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;
use tokio::fs::File;

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

pub async 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;
use tokio::fs::File;

let mut reader = File::open("sample.bam").await.map(bam::AsyncReader::new)?;
reader.read_header().await?;
let reference_sequences = reader.read_reference_sequences().await?;

pub async 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 the given record buffer.

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 a stream (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 tokio::fs::File;

let mut reader = File::open("sample.bam").await.map(bam::AsyncReader::new)?;
reader.read_header().await?;
reader.read_reference_sequences().await?;

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

pub fn records(&mut self) -> impl Stream<Item = Result<Record>> + '_

Returns an (async) stream over records starting from the current (input) stream position.

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

Examples

use futures::TryStreamExt;
use noodles_bam as bam;
use tokio::fs::File;

let mut reader = File::open("sample.bam").await.map(bam::AsyncReader::new)?;
reader.read_header().await?;
reader.read_reference_sequences().await?;

let mut records = reader.records();

while let Some(record) = records.try_next().await? {
    // ...
}

pub fn virtual_position(&self) -> VirtualPosition

Returns the current virtual position of the underlying BGZF reader.

Examples

use noodles_bam as bam;
use noodles_bgzf as bgzf;

let data = Vec::new();
let reader = bam::AsyncReader::new(&data[..]);
let virtual_position = reader.virtual_position();

assert_eq!(reader.virtual_position(), bgzf::VirtualPosition::from(0));

impl<R> Reader<R> where
    R: AsyncRead + AsyncSeek + Unpin, 

pub async 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 data = [];
let mut reader = bam::AsyncReader::new(Cursor::new(data));

let virtual_position = bgzf::VirtualPosition::default();
reader.seek(virtual_position).await?;

pub fn query<I, RS>(
    &mut self,
    reference_sequences: &ReferenceSequences,
    index: &I,
    region: &Region
) -> Result<impl Stream<Item = Result<Record>> + '_> where
    I: BinningIndex<RS>,
    RS: ReferenceSequenceExt, 

Returns a stream over records that intersect the given region.

Examples

use futures::TryStreamExt;
use noodles_bam::{self as bam, bai};
use noodles_core::Region;
use noodles_sam as sam;
use tokio::fs::File;

let mut reader = File::open("sample.bam").await.map(bam::AsyncReader::new)?;
let header: sam::Header = reader.read_header().await?.parse()?;

let reference_sequences = header.reference_sequences();
let index = bai::r#async::read("sample.bam.bai").await?;
let region = Region::mapped("sq0", 8..=13);
let mut query = reader.query(reference_sequences, &index, &region)?;

while let Some(record) = query.try_next().await? {
    // ...
}