Struct rust_htslib::bam::IndexedReader

pub struct IndexedReader { /* fields omitted */ }

Implementations

impl IndexedReader

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

Create a new Reader from path.

Arguments

• path - the path to open.

pub fn from_path_and_index<P: AsRef<Path>>(
    path: P,
    index_path: P
) -> Result<Self>

pub fn from_url(url: &Url) -> Result<Self>

pub fn fetch<'a, T: Into<FetchDefinition<'a>>>(
    &mut self,
    fetch_definition: T
) -> Result<()>

Define the region from which .read() or .records will retrieve reads.

Both iterating (with .records()) and looping without allocation (with .read() are a two stage process:

1. ‘fetch’ the region of interest
2. iter/loop trough the reads.

Example:

use rust_htslib::bam::{IndexedReader, Read};
let mut bam = IndexedReader::from_path(&"test/test.bam").unwrap();
bam.fetch(("chrX", 10000, 20000)); // coordinates 10000..20000 on reference named "chrX"
for read in bam.records() {
    println!("read name: {:?}", read.unwrap().qname());
}

The arguments may be anything that can be converted into a FetchDefinition such as

• fetch(tid: u32) -> fetch everything on this reference
• fetch(reference_name: &u8 | &str) -> fetch everything on this reference
• fetch((tid: i32, start: i64, stop: i64)): -> fetch in this region on this tid
• fetch((reference_name: &u8 | &str, start: i64, stop: i64) -> fetch in this region on this tid
• fetch(FetchDefinition::All) or fetch(“.”) -> Fetch overything
• fetch(FetchDefinition::Unmapped) or fetch(“*”) -> Fetch unmapped (as signified by the ‘unmapped’ flag in the BAM - might be unreliable with some aligners.

The start / stop coordinates will take i64 (the correct type as of htslib’s ‘large coordinates’ expansion), i32, u32, and u64 (with a possible panic! if the coordinate won’t fit an i64).

This replaces the old fetch and fetch_str implementations.

pub fn set_reference<P: AsRef<Path>>(&mut self, path: P) -> Result<()>

Set the reference path for reading CRAM files.

Arguments

• path - path to the FASTA reference

Trait Implementations

impl Debug for IndexedReader

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Drop for IndexedReader

fn drop(&mut self)

Executes the destructor for this type.

impl Read for IndexedReader

fn records(&mut self) -> Records<'_, Self>

Iterator over the records of the fetched region. Note that, while being convenient, this is less efficient than pre-allocating a Record and reading into it with the read method, since every iteration involves the allocation of a new Record.

fn read(&mut self, record: &mut Record) -> Option<Result<()>>

Read next BAM record into given record. Use this method in combination with a single allocated record to avoid the reallocations occurring with the iterator.

fn rc_records(&mut self) -> RcRecords<'_, Self>

Records iterator using an Rc to avoid allocating a Record each turn. This is about 1% slower than the read based API in micro benchmarks, but has nicer ergonomics (and might not actually be slower in your applications).

fn pileup(&mut self) -> Pileups<'_, Self>

Iterator over pileups.

fn htsfile(&self) -> *mut htsFile

Return the htsFile struct

fn header(&self) -> &HeaderView

Return the header.

fn set_thread_pool(&mut self, tpool: &ThreadPool) -> Result<()>

Use a shared thread-pool for writing. This permits controlling the total thread count when multiple readers and writers are working simultaneously. A thread pool can be created with crate::tpool::ThreadPool::new(n_threads)

fn seek(&mut self, offset: i64) -> Result<()>

Seek to the given virtual offset in the file

fn tell(&self) -> i64

Report the current virtual offset

fn set_threads(&mut self, n_threads: usize) -> Result<()>

Activate multi-threaded BAM read support in htslib. This should permit faster reading of large BAM files.

impl Send for IndexedReader