Struct TwobitReader 

pub struct TwobitReader { /* private fields */ }

A reader for a 2bit file.

Use open and open_masked to construct an instance.

Implementations

impl TwobitReader

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

Opens a 2bit file for reading.

Example

let tbr = TwobitReader::open("hg38.2bit")?; // Human genome, build 38
let seq = tbr.get("chr2", 10000, 10010);    // -> "CGTATCCCAC"

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

Opens a 2bit file for reading, with lowercase masks applied.

The lowercase mask feature of 2bit files is mainly relevant for sequence search, for example with the BLAT suite of tools. Specifically, lowercase letters typically indicate a region that should be ignored (not searched) during a sequence search.

Example

let tbr = TwobitReader::open_masked("hg38.2bit")?; // Human genome, build 38
let seq = tbr.get("chr2", 10000, 10010);           // -> "CGTATcccac" (mixed case)

pub fn num_seqs(&self) -> usize

Returns the number of sequence records in the file.

pub fn iter_names(&self) -> impl Iterator<Item = &str> + '_

Iterates over the sequence record names, in the order they appear in the file.

pub fn names(&self) -> Vec<&str>

Returns a vector of sequence record names, in the order they appear in the file.

pub fn contains_name<N: AsRef<str>>(&self, name: N) -> bool

Returns whether name matches a sequence record in the file.

pub fn seq_len<N: AsRef<str>>(&self, name: N) -> usize

Returns the number of nucleotides in the named sequence record.

Panics

Panics if the sequence name was not found. Panics if an IO error occurs due to a malformed file.

pub fn get<N: AsRef<str>>(&self, name: N, start: usize, end: usize) -> String

Extracts range start..end (0-based, exclusive end) from the named sequence record.

Example

let tbr = TwobitReader::open("hg38.2bit")?;
let seq = tbr.get("chr2", 10000, 10010); // -> "CGTATCCCAC"

Panics

Panics if the sequence name was not found or the range was invalid. Panics if an IO error occurs due to a malformed file.

pub fn get_into<N: AsRef<str>>( &self, name: N, start: usize, end: usize, dst: &mut String, )

A version of get where the result is stored in dst.

Example

let tbr = TwobitReader::open("hg38.2bit")?;
let mut dst = String::new();
tbr.get_into("chr2", 10000, 10010, &mut dst); // dst = "CGTATCCCAC"

Panics

See get.

pub fn get_batch<'a, N, T, I>( &'a self, batch: I, ) -> impl Iterator<Item = String> + 'a

where N: AsRef<str>, T: Borrow<(N, usize, usize)>, I: IntoIterator<Item = T>, I::IntoIter: 'a,

Returns an iterator that calls get for each query in the batch, for convenience.

Example

let exons = [("chr1", 10000, 15000),
             ("chr2", 30000, 35000), /* ... */ ];
let seq = tbr.get_batch(&exons);

Panics

See get.

pub fn get_inclusive<N: AsRef<str>>( &self, name: N, start: usize, end: usize, ) -> String

A version of get using 1-based inclusive ranges; see genomic interval notations.

Example

let tbr = TwobitReader::open("hg38.2bit")?;
let seq = tbr.get_inclusive("chr2", 10001, 10010); // -> "CGTATCCCAC"

Panics

See get.

pub fn get_inclusive_into<N: AsRef<str>>( &self, name: N, start: usize, end: usize, dst: &mut String, )

A version of get_into using 1-based inclusive ranges; see genomic interval notations.

Example

let tbr = TwobitReader::open("hg38.2bit")?;
let mut dst = String::new();
tbr.get_inclusive_into("chr2", 10001, 10010, &mut dst); // dst = "CGTATCCCAC"

Panics

See get.

pub fn get_batch_inclusive<'a, N, T, I>( &'a self, batch: I, ) -> impl Iterator<Item = String> + 'a

where N: AsRef<str>, T: Borrow<(N, usize, usize)>, I: IntoIterator<Item = T>, I::IntoIter: 'a,

A version of get_batch using 1-based inclusive ranges; see genomic interval notations.

Example

let exons = [("chr1", 10001, 15000),
             ("chr2", 30001, 35000), /* ... */ ];
let seq = tbr.get_batch_inclusive(&exons);

Panics

See get.

pub fn concat<N, R>(&self, name: N, ranges: R) -> String

where N: AsRef<str>, R: AsRef<[(usize, usize)]>,

Concatenates a batch of sequence ranges into a single string.

Example

let tbr = TwobitReader::open("hg38.2bit")?;
let ranges = [(10000, 10006), (10006, 10010)]; // "CGTATC" "CCAC"
let seq = tbr.concat("chr2", &ranges);         // -> "CGTATCCCAC"

This version performs one allocation only, of the required total length. However, it requires ranges to be iterable twice. See concat_iter for a version that grows rather than pre-allocates.

Panics

Panics if the sequence name was not found or if any range was invalid. Panics if an IO error occurs due to a malformed file.

pub fn concat_iter<N, I>(&self, name: N, ranges: I) -> String

where N: AsRef<str>, I: IntoIterator<Item = (usize, usize)>,

A version of concat that iterates through ranges, consuming it.

Example

let tbr = TwobitReader::open("hg38.2bit")?;
let starts = [10000, 10006];
let ends = [10006, 10010];
let seq = tbr.concat_iter("chr2", zip(starts, ends)); // -> "CGTATCCCAC"

This version iterates through ranges exactly once, growing the output String as needed.

Panics

See concat.

pub fn concat_inclusive<N, R>(&self, name: N, ranges: R) -> String

where N: AsRef<str>, R: AsRef<[(usize, usize)]>,

A version of concat using 1-based inclusive ranges; see genomic interval notations.

Example

let tbr = TwobitReader::open("hg38.2bit")?;
let ranges = [(10001, 10006), (10007, 10010)];  // "CGTATC" "CCAC"
let seq = tbr.concat_inclusive("chr2", ranges); // -> "CGTATCCCAC"

Panics

See concat.

pub fn concat_iter_inclusive<N, I>(&self, name: N, ranges: I) -> String

where N: AsRef<str>, I: IntoIterator<Item = (usize, usize)>,

A version of concat_iter using 1-based inclusive ranges; see genomic interval notations.

Example

let tbr = TwobitReader::open("hg38.2bit")?;
let starts = [10001, 10007];
let ends = [10006, 10010];
let seq = tbr.concat_iter_inclusive("chr2", zip(starts, ends)); // -> "CGTATCCCAC"

Panics

See concat.

pub fn prefetch<N, T, I>(&self, batch: I)

where N: AsRef<str>, T: Borrow<(N, usize, usize)>, I: IntoIterator<Item = T>,

Asks the operating system ensure that the data for all the ranges gets paged into memory, and returns without waiting for the data to arrive.

Use this method only if are reading a “cold” file that is not already paged in from disk. Accessing a cold file is almost entirely IO-bound. This function provides a hint to the operating system, specifying what data you’ll soon be asking for. It does not affect the output of subsequent calls to get and concat, only their speed. For maximum benefit, prefetch the largest batch of ranges that you can in one call.

Example

let exons = [("chr1", 10000, 15000),
             ("chr2", 30000, 35000), /* ... */ ];
tbr.prefetch(&exons);             // Ask the operating system to start paging this data from disk.
let seqs = tbr.get_batch(&exons); // Access the memory as it arrives.

Panics

Panics if any sequence name was not found or if start > end. Panics if an IO error occurs while processing any newly-accessed sequence records.

pub fn prefetch_inclusive<N, T, I>(&self, batch: I)

where N: AsRef<str>, T: Borrow<(N, usize, usize)>, I: IntoIterator<Item = T>,

A version of prefetch using 1-based inclusive ranges; see genomic interval notations.

Example

let exons = [("chr1", 10001, 15000),
             ("chr2", 30001, 35000), /* ... */ ];
tbr.prefetch_inclusive(&exons);             // Ask the operating system to start paging.
let seqs = tbr.get_batch_inclusive(&exons); // Access the memory as it arrives.

Panics

See prefetch.

Trait Implementations

impl Debug for TwobitReader

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

Formats the value using the given formatter.