Struct SamRecordClipper 

pub struct SamRecordClipper { /* private fields */ }

Utility for clipping BAM/SAM records in various ways

Implementations

impl SamRecordClipper

pub fn new(mode: ClippingMode) -> SamRecordClipper

Creates a new clipper with the specified mode

pub fn with_auto_clip( mode: ClippingMode, auto_clip_attributes: bool, ) -> SamRecordClipper

Creates a new clipper with auto-clip attributes enabled

When enabled with hard clipping mode, any tags that are the same length as the read’s sequence will be automatically clipped to match. This ensures per-base tags (like quality arrays, per-base depths, etc.) stay synchronized with the sequence.

pub fn clip_start_of_alignment( &self, record: &mut RecordBuf, bases_to_clip: usize, ) -> usize

Clips a specified number of bases from the start (left side) of the alignment

Returns the number of bases actually clipped

pub fn clip_end_of_alignment( &self, record: &mut RecordBuf, bases_to_clip: usize, ) -> usize

Clips a specified number of bases from the end (right side) of the alignment

Returns the number of bases actually clipped

pub fn clip_5_prime_end_of_alignment( &self, record: &mut RecordBuf, bases_to_clip: usize, ) -> usize

Clips bases from the 5’ end of the read (strand-aware)

For positive strand reads, clips from the start of alignment. For negative strand reads, clips from the end of alignment.

Returns the number of bases actually clipped

pub fn clip_3_prime_end_of_alignment( &self, record: &mut RecordBuf, bases_to_clip: usize, ) -> usize

Clips bases from the 3’ end of the read (strand-aware)

For positive strand reads, clips from the end of alignment. For negative strand reads, clips from the start of alignment.

Returns the number of bases actually clipped

pub fn clip_overlapping_reads( &self, r1: &mut RecordBuf, r2: &mut RecordBuf, ) -> (usize, usize)

Clips overlapping portions of an FR read pair

Important: Only clips reads that are in FR (forward-reverse) orientation. Non-FR pairs (FF, RR, RF) are not clipped.

This implementation matches fgbio’s midpoint approach: calculates the midpoint between the 5’ ends of the two reads and clips both reads at that position.

Returns (bases_clipped_r1, bases_clipped_r2)

pub fn num_bases_extending_past_mate( record: &RecordBuf, mate_unclipped_start: usize, mate_unclipped_end: usize, ) -> usize

Calculates the number of bases in a read that extend past the mate’s unclipped boundary

This matches fgbio’s numBasesExtendingPastMate function exactly.

Arguments

• record - The SAM record to check
• mate_unclipped_start - The mate’s unclipped start position
• mate_unclipped_end - The mate’s unclipped end position

Returns

The number of bases that extend past the mate’s boundary, or 0 if not applicable

pub fn clip_extending_past_mate_ends( &self, r1: &mut RecordBuf, r2: &mut RecordBuf, ) -> (usize, usize)

Clips reads that extend beyond their mate’s alignment ends

This matches fgbio’s clipExtendingPastMateEnds function exactly.

Important: Only clips reads that are in FR (forward-reverse) orientation. Non-FR pairs (FF, RR, RF) are not clipped.

Returns (bases_clipped_r1, bases_clipped_r2)

pub fn clip_start_of_read( &self, record: &mut RecordBuf, clip_length: usize, ) -> usize

Ensures at least clip_length bases are clipped at the start of the read

This includes any existing hard and soft clipping. If more clipping is needed, delegates to clip_start_of_alignment.

Returns the number of additional bases clipped (not including existing clips)

pub fn clip_end_of_read( &self, record: &mut RecordBuf, clip_length: usize, ) -> usize

Ensures at least clip_length bases are clipped at the end of the read

This includes any existing hard and soft clipping. If more clipping is needed, delegates to clip_end_of_alignment.

Returns the number of additional bases clipped (not including existing clips)

pub fn clip_5_prime_end_of_read( &self, record: &mut RecordBuf, clip_length: usize, ) -> usize

Ensures at least clip_length bases are clipped at the 5’ end (strand-aware)

For positive strand: clips from start. For negative strand: clips from end.

Returns the number of additional bases clipped

pub fn clip_3_prime_end_of_read( &self, record: &mut RecordBuf, clip_length: usize, ) -> usize

Ensures at least clip_length bases are clipped at the 3’ end (strand-aware)

For positive strand: clips from end. For negative strand: clips from start.

Returns the number of additional bases clipped

pub fn upgrade_all_clipping( &self, record: &mut RecordBuf, ) -> Result<(usize, usize), Error>

Upgrades all existing clipping in a read to the current clipping mode

E.g., converts soft clips to hard clips if mode is Hard, or soft clips to soft-with-mask if mode is SoftWithMask

Returns (leading_clipped, trailing_clipped) - the number of soft-clipped bases that were converted to hard clips at the 5’ and 3’ ends respectively. Returns (0, 0) if no conversion occurred.

Panics

Panics if an adjacent hard-clip CIGAR op disappears between the last() check and the subsequent access (should not happen in practice), or if a BAM tag is not exactly 2 bytes.

Errors

Returns Result for API compatibility, but the current implementation is infallible and always returns Ok.

pub fn clipped_bases(record: &RecordBuf) -> usize

Returns the number of bases that are currently clipped in the read