Struct ReferenceReader 

pub struct ReferenceReader { /* private fields */ }

A thread-safe reference genome reader with all sequences preloaded into memory.

This reader loads the entire FASTA file into memory at construction time, providing O(1) lookup performance for sequence fetches. This approach matches fgbio’s nmUqMdTagRegeneratingWriter which reads all contigs into a Map upfront.

For a typical human reference (e.g., hs38DH at ~3GB), this uses approximately 3GB of memory (raw byte storage like htsjdk) and provides the fastest load times.

Implementations

impl ReferenceReader

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

Creates a new reference reader, loading all sequences into memory.

This reads the entire FASTA file into memory at construction time. For a typical human reference (~3GB), this takes a few seconds but provides O(1) lookup performance for all subsequent fetches.

Arguments

• path - Path to the reference FASTA file (may be gzipped)

Errors

Returns an error if:

• The file does not exist
• The file cannot be read or parsed as FASTA

Examples

use fgumi_lib::reference::ReferenceReader;

let reader = ReferenceReader::new("reference.fasta")?;

pub fn fetch( &self, chrom: &str, start: Position, end: Position, ) -> Result<Vec<u8>>

Retrieves a subsequence from the reference genome.

Since all sequences are preloaded into memory, this is an O(1) lookup followed by a slice copy.

Arguments

• chrom - Chromosome/sequence name (e.g., “chr1”, “1”)
• start - Start position (1-based, inclusive)
• end - End position (1-based, inclusive)

Returns

The requested subsequence as a vector of bytes (preserving original case)

Errors

Returns an error if:

• The chromosome is not found in the reference
• The requested region exceeds the chromosome length

Examples

use fgumi_lib::reference::ReferenceReader;
use noodles::core::Position;

let reader = ReferenceReader::new("reference.fasta")?;

// Fetch first 100 bases of chr1
let seq = reader.fetch("chr1", Position::try_from(1)?, Position::try_from(100)?)?;
assert_eq!(seq.len(), 100);

pub fn fetch_slice( &self, chrom: &str, start: Position, end: Position, ) -> Result<&[u8]>

Borrowed-slice variant of [fetch] that returns a reference into the in-memory sequence — same lookup semantics, no allocation.

Prefer this over [fetch] in hot loops (e.g., per-record reference access in fgumi zipper’s --restore-unconverted-bases path) where allocating a fresh Vec<u8> per call adds up to gigabytes of churn.

Errors

Same as [fetch]: returns an error if the chromosome is missing or the requested region exceeds the sequence length.

pub fn base_at(&self, chrom: &str, pos: Position) -> Result<u8>

Gets a single base from the reference at the specified position.

This is a convenience method that delegates to fetch() with a single-base region.

Arguments

• chrom - Chromosome/sequence name (e.g., “chr1”, “1”)
• pos - Position (1-based)

Returns

The base at the specified position (preserving original case from FASTA)

Errors

Returns an error if:

• The chromosome is not found in the reference
• The position exceeds the chromosome length

Examples

use fgumi_lib::reference::ReferenceReader;
use noodles::core::Position;

let reader = ReferenceReader::new("reference.fasta")?;

// Get the base at position 1000 of chr1
let base = reader.base_at("chr1", Position::try_from(1000)?)?;
assert!(matches!(base, b'A' | b'C' | b'G' | b'T' | b'N'));

Trait Implementations

impl Clone for ReferenceReader

fn clone(&self) -> ReferenceReader

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl RefBaseProvider for ReferenceReader

Available on crate feature simplex only.

fn base_at_0based(&self, chrom: &str, pos: u64) -> Option<u8>

Returns the base at a 0-based position, or None if out of bounds.

fn sequence_for(&self, chrom: &str) -> Option<&[u8]>

Returns the full sequence for a chromosome, or None if not found.

impl ReferenceProvider for ReferenceReader

fn fetch(&self, chrom: &str, start: Position, end: Position) -> Result<Vec<u8>>

Fetches a subsequence from the reference genome.