Struct IndexedReader

pub struct IndexedReader { /* private fields */ }

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

start and stop are zero-based. start is inclusive, stop is exclusive.

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

pub fn index(&self) -> &IndexView

pub fn index_stats(&mut self) -> Result<Vec<(i64, u64, u64, u64)>>

Similar to samtools idxstats, this returns a vector of tuples containing the target id, length, number of mapped reads, and number of unmapped reads. The last entry in the vector corresponds to the unmapped reads for the entire file, with the tid set to -1.

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.

fn set_cram_options( &mut self, fmt_opt: hts_fmt_option, fields: sam_fields, ) -> Result<()>

If the underlying file is in CRAM format, allows modifying CRAM options. Note that this method does not check that the underlying file actually is in CRAM format.

impl Send for IndexedReader