Struct Template 

pub struct Template {
    pub name: Vec<u8>,
    pub records: Vec<RecordBuf>,
    pub raw_records: Option<Vec<Vec<u8>>>,
    pub r1: Option<(usize, usize)>,
    pub r2: Option<(usize, usize)>,
    pub r1_supplementals: Option<(usize, usize)>,
    pub r2_supplementals: Option<(usize, usize)>,
    pub r1_secondaries: Option<(usize, usize)>,
    pub r2_secondaries: Option<(usize, usize)>,
    pub mi: MoleculeId,
}

A template representing all reads with the same query name.

In paired-end sequencing, this typically includes R1 and R2, plus any secondary or supplementary alignments. All records with the same name are grouped together.

This structure mirrors the Scala Template class from fgbio, organizing reads into:

• Primary R1 and R2 reads
• Supplementary alignments for R1 and R2
• Secondary alignments for R1 and R2

Fields

name: Vec<u8>

The query name (QNAME) shared by all records in this template

records: Vec<RecordBuf>

The records (empty in raw-byte mode)

raw_records: Option<Vec<Vec<u8>>>

Raw BAM record bytes (without block_size prefix). Present only in raw-byte mode.

r1: Option<(usize, usize)>

Primary R1 read (first segment, non-secondary, non-supplementary)

r2: Option<(usize, usize)>

Primary R2 read (second segment, non-secondary, non-supplementary)

r1_supplementals: Option<(usize, usize)>

Supplementary alignments for R1

r2_supplementals: Option<(usize, usize)>

Supplementary alignments for R2

r1_secondaries: Option<(usize, usize)>

Secondary alignments for R1

r2_secondaries: Option<(usize, usize)>

Secondary alignments for R2

mi: MoleculeId

Assigned molecule ID from UMI grouping (set during group command)

Implementations

impl Template

pub fn r1(&self) -> Option<&RecordBuf>

Returns the primary R1 read if present.

The primary R1 is the main (non-secondary, non-supplementary) alignment for the first read in a pair (or the only read for single-end data).

Returns

Reference to the primary R1 record, or None if not present. Returns None in raw-byte mode (use raw_r1() instead).

pub fn r2(&self) -> Option<&RecordBuf>

Returns the primary R2 read if present. Returns None in raw-byte mode (use raw_r2() instead).

The primary R2 is the main (non-secondary, non-supplementary) alignment for the second read in a paired-end template.

Returns

Reference to the primary R2 record, or None if not present

pub fn r1_supplementals(&self) -> &[RecordBuf]

Returns supplementary alignments for R1. Returns empty in raw-byte mode.

pub fn r2_supplementals(&self) -> &[RecordBuf]

Returns supplementary alignments for R2. Returns empty in raw-byte mode.

pub fn r1_secondaries(&self) -> &[RecordBuf]

Returns secondary alignments for R1. Returns empty in raw-byte mode.

pub fn r2_secondaries(&self) -> &[RecordBuf]

Returns secondary alignments for R2. Returns empty in raw-byte mode.

pub fn new(name: Vec<u8>) -> Self

Creates a new empty template with the given name

Arguments

• name - The query name for this template

Returns

An empty template with no records

pub fn from_records<I>(records: I) -> Result<Self>

where I: IntoIterator<Item = RecordBuf>,

Creates a Template from an iterator of records with the same query name

Automatically organizes records into r1/r2, primary/supplementary/secondary categories. Assumes all records have the same query name.

Arguments

• records - Iterator of records to organize into a template

Returns

A Template with records organized by type, or an error if multiple primary reads found

Errors

Returns an error if:

• Multiple non-secondary, non-supplemental R1s are found
• Multiple non-secondary, non-supplemental R2s are found
• Iterator is empty (no name available)

Panics

• If not all the records have the same query name

pub fn primary_reads(&self) -> impl Iterator<Item = &RecordBuf>

Returns an iterator over primary (non-secondary, non-supplementary) reads in this template

Returns both R1 and R2 primary reads if present.

Returns

Iterator over primary read records

pub fn into_primary_reads(self) -> (Option<RecordBuf>, Option<RecordBuf>)

Consumes the template and returns owned primary reads.

This method takes ownership of the template and returns the primary R1 and R2 reads without cloning. Use this when you need owned records and won’t access the template again.

Returns

Tuple of (Option<RecordBuf>, Option<RecordBuf>) containing owned R1 and R2 records

Example

let template = Template::from_records(records)?;
let (r1, r2) = template.into_primary_reads();
if let Some(r1) = r1 {
    writer.write_record(r1)?; // No clone needed
}

pub fn all_supplementary_and_secondary( &self, ) -> impl Iterator<Item = &RecordBuf>

Returns an iterator over all supplementary and secondary reads

Returns

Iterator over non-primary reads

pub fn all_reads(&self) -> impl Iterator<Item = &RecordBuf>

Returns an iterator over all reads in this template

Includes primary, supplementary, and secondary alignments.

Returns

Iterator over all records

pub fn into_records(self) -> Vec<RecordBuf>

Consumes the template and returns all records as a vector.

This is useful when you need to take ownership of all records for further processing.

pub fn all_r1s(&self) -> impl Iterator<Item = &RecordBuf>

Returns an iterator over all R1 reads (primary, supplementary, and secondary)

Returns

Iterator over all R1 records

pub fn all_r2s(&self) -> impl Iterator<Item = &RecordBuf>

Returns an iterator over all R2 reads (primary, supplementary, and secondary)

Returns

Iterator over all R2 records

pub fn read_count(&self) -> usize

Returns the total count of records in this template

Returns

Total number of records (primary, supplementary, and secondary)

pub fn is_raw_byte_mode(&self) -> bool

Returns true if this template is in raw-byte mode.

pub fn raw_r1(&self) -> Option<&[u8]>

Returns the raw R1 bytes if in raw-byte mode.

pub fn raw_r2(&self) -> Option<&[u8]>

Returns the raw R2 bytes if in raw-byte mode.

pub fn all_raw_records(&self) -> Option<&[Vec<u8>]>

Returns all raw records if in raw-byte mode.

pub fn into_raw_records(self) -> Option<Vec<Vec<u8>>>

Consumes self and returns the raw records if in raw-byte mode.

pub fn all_raw_records_mut(&mut self) -> Option<&mut [Vec<u8>]>

Returns mutable access to all raw records if in raw-byte mode.

pub fn from_raw_records(raw_records: Vec<Vec<u8>>) -> Result<Self>

Build a Template from raw BAM byte records, categorizing by flags.

The records are categorized using bam_fields::flags() to determine R1/R2/supplementary/secondary status, with the same index-pair scheme as Builder::build().

Errors

Returns an error if multiple primary R1s or R2s are found.

pub fn pair_orientation(&self) -> Option<PairOrientation>

Returns the pair orientation if both R1 and R2 are present and mapped to the same chromosome.

This matches htsjdk’s SamPairUtil.getPairOrientation() and fgbio’s Template.pairOrientation.

Returns

• Some(PairOrientation::FR) - Forward-Reverse (“innie”) orientation
• Some(PairOrientation::RF) - Reverse-Forward (“outie”) orientation
• Some(PairOrientation::Tandem) - Both reads on the same strand
• None - If R1 or R2 is missing, unmapped, or they’re on different chromosomes

Examples

let template = Template::from_records(records)?;
if let Some(orientation) = template.pair_orientation() {
    match orientation {
        PairOrientation::FR => println!("Innie pair"),
        PairOrientation::RF => println!("Outie pair"),
        PairOrientation::Tandem => println!("Tandem pair"),
    }
}

pub fn fix_mate_info(&mut self) -> Result<()>

Fixes mate information for paired-end reads.

This method follows htsjdk’s SamPairUtil.setMateInfo behavior exactly:

For primary R1/R2 pairs:

• Case 1 (both mapped): Sets mate ref, mate pos, mate strand flag, mate unmapped=false, MQ tag, MC tag (if valid CIGAR), and computes TLEN
• Case 2 (both unmapped): Clears ref/pos to unmapped values, sets mate unmapped=true, removes MQ and MC tags, sets TLEN=0
• Case 3 (one mapped, one unmapped): Places unmapped read at mapped read’s coordinates, sets appropriate mate info, MQ only on unmapped read, TLEN=0

For supplementary alignments:

• Sets mate information based on the mate’s primary alignment
• Sets ms (mate score) tag if AS (alignment score) is available

Errors

Returns an error if the CIGAR operations cannot be parsed (malformed CIGAR data)

Trait Implementations

impl Clone for Template

fn clone(&self) -> Template

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for Template

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

Formats the value using the given formatter.

impl MemoryEstimate for Template

fn estimate_heap_size(&self) -> usize

Returns an estimate of the heap memory used by this value in bytes.