Struct bam::record::Record

pub struct Record { /* fields omitted */ }

BAM Record.

Allows to get and set name, sequence, qualities, CIGAR, flag, tags and all other BAM/SAM record fields.

You can use aligned_pairs and matching_pairs to iterate over record/reference aligned indices.

Methods

impl Record

pub fn new() -> Record

Creates an empty record. Can be filled using read_into.

pub fn clear(&mut self)

Clears the record.

pub fn fill_from_sam(
    &mut self,
    line: &str,
    header: &Header
) -> Result<(), Error>

Fills the record from SAM. If an error is return, the record may be corrupted.

pub fn shrink_to_fit(&mut self)

Shrinks record contents. The more records were read into the same Record instance, the bigger would be inner vectors (to save time on memory allocation). Use this function if you do not plan to read into this record in the future.

pub fn name(&self) -> &[u8]

Returns record name as bytes.

pub fn sequence(&self) -> &Sequence

Returns record sequence.

pub fn qualities(&self) -> Option<&Qualities>

Returns record qualities, if present.

pub fn cigar(&self) -> &Cigar

Returns record CIGAR (can be empty).

pub fn ref_id(&self) -> i32

Returns 0-based reference index. Returns -1 for unmapped records.

pub fn start(&self) -> i32

Returns 0-based left-most aligned reference position. Same as POS - 1 in SAM specification. Returns -1 for unmapped records.

pub fn calculate_end(&self) -> i32

For a mapped record aligned to reference positions [start-end), the function returns end. The first calculation takes O(n), where n is the length of Cigar. Consecutive calculations take O(1). If the record was fetched from a specific region, it should have end already calculated.

Returns 0 for unmapped records.

pub fn calculate_bin(&self) -> u16

Returns BAI bin. If the bin is unknown and the end has not been calculated, the bin will be calculated in O(n_cigar), otherwise O(1).

Returns 4680 for unmapped reads.

pub fn mapq(&self) -> u8

Returns record MAPQ.

pub fn mate_ref_id(&self) -> i32

Returns 0-based reference index for the pair record. Returns -1 for unmapped records, and records without a pair.

pub fn mate_start(&self) -> i32

Returns 0-based left-most aligned reference position for the pair record. Same as PNEXT - 1 in SAM specification. Returns -1 for unmapped records and records without a pair.

pub fn template_len(&self) -> i32

Observed template length (TLEN in SAM specification).

pub fn tags(&self) -> &TagViewer

Returns TagViewer, which provides operations of tags.

pub fn tags_mut(&mut self) -> &mut TagViewer

Returns mutable TagViewer, which provides operations of tags.

pub fn write_sam<W: Write>(&self, f: &mut W, header: &Header) -> Result<()>

Write the record in SAM format to f. The function needs header, as the record itself does not store reference names.

pub fn write_bam<W: Write>(&self, stream: &mut W) -> Result<()>

Writes a record in BAM format.

pub fn set_name<T: IntoIterator<Item = u8>>(&mut self, name: T)

Sets record name (only first 254 letters will be used).

pub fn flag(&self) -> Flag

Returns record flag.

It supports predicates like record.flag().is_paired(). You can compare with flags directly using record.flag().0 & RECORD_PAIRED != 0.

pub fn flag_mut(&mut self) -> &mut Flag

Returns mutable record flag.

It can be changed like record.flag_mut().set_paired(true). You can change it directly record.flag_mut().0 |= RECORD_PAIRED. You can also you set_flag.

pub fn set_flag(&mut self, flag: u16)

pub fn set_ref_id(&mut self, ref_id: i32) -> Result<(), &'static str>

Sets reference id. It cannot be less than -1.

pub fn set_start(&mut self, start: i32) -> Result<(), &'static str>

Sets record 0-based start. It cannot be less than -1.

If the end position was already calculated, it is updated.

pub fn set_mapq(&mut self, mapq: u8)

pub fn set_mate_ref_id(&mut self, mate_ref_id: i32) -> Result<(), &'static str>

Sets reference id of the mate record. It cannot be less than -1.

pub fn set_mate_start(&mut self, mate_start: i32) -> Result<(), &'static str>

Sets record 0-based start of the mate record. It cannot be less than -1.

pub fn set_template_len(&mut self, template_len: i32)

pub fn reset_seq(&mut self)

Sets empty sequence and qualities.

pub fn set_seq<T: IntoIterator<Item = u8>>(
    &mut self,
    sequence: T
) -> Result<(), String>

Sets a sequence for a record and removes record qualities. Sequence should be in text format (for example b"ACGT").

The function returns an error if there was an unexpected nucleotide. In that case the sequence and qualities are cleared.

pub fn set_seq_qual<T, U>(
    &mut self,
    sequence: T,
    qualities: U
) -> Result<(), String> where
    T: IntoIterator<Item = u8>,
    U: IntoIterator<Item = u8>, 

Sets a sequence and qualities for a record. If you do not need to set qualities, use seq_seq. Both iterators should have the same length.

Arguments

• sequence - in text format (for example b"ACGT"),
• qualities - in raw format (without +33 added).

If the function returns an error, the sequence and qualities are cleared.

pub fn set_raw_seq(&mut self, raw_seq: &[u8], len: usize)

Sets raw sequence (4 bits for a nucleotide) for a record and removes record qualities.

The function panics if the length does not match sequence length.

pub fn set_raw_seq_qual<U>(
    &mut self,
    raw_seq: &[u8],
    qualities: U
) -> Result<(), String> where
    U: IntoIterator<Item = u8>, 

Sets raw sequence (4 bits for a nucleotide) for a record and record qualities. Qualities should be in raw format (without +33 added), and non-empty.

If the sequence and qualities length do not match, the function returns an error clears the record sequence and qualities.

pub fn set_cigar<I: IntoIterator<Item = u8>>(
    &mut self,
    cigar: I
) -> Result<(), String>

Sets record cigar. This resets end position and BAI bin.

pub fn set_raw_cigar<I: IntoIterator<Item = u32>>(&mut self, cigar: I)

Sets raw record cigar. This resets end position and BAI bin.

Important traits for AlignedPairs<'a>

impl<'a> Iterator for AlignedPairs<'a> type Item = (Option<u32>, Option<u32>);

pub fn aligned_pairs(&self) -> AlignedPairs

Returns an iterator over pairs (Option<u32>, Option<u32>). The first element represents a sequence index, and the second element represents a reference index. If the current operation is an insertion or a deletion, the respective element will be None.

If the record is unmapped, returns an empty iterator.

Important traits for MatchingPairs<'a>

impl<'a> Iterator for MatchingPairs<'a> type Item = (u32, u32);

pub fn matching_pairs(&self) -> MatchingPairs

Returns an iterator over pairs (u32, u32). The first element represents a sequence index, and the second element represents a reference index. This iterator skips insertions and deletions.

If the record is unmapped, returns an empty iterator.