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 positions.

If the record has an MD tag, you can use alignment_entries to get record/reference positions and corresponding nucleotides.

Implementations

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_bam<R: Read>(&mut self, stream: &mut R) -> Result<bool>

Fills the record from a stream of uncompressed BAM contents. Returns false, if the file ended and the record was not read.

Use BamReader or IndexedReader instead of this function whenever possible.

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

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. You can check if sequence is present in the record using sequence().available().

pub fn qualities(&self) -> &Qualities

Returns record qualities. You can check if qualities are present in the record using qualities().available().

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 zero for unmapped records.

pub fn query_len(&self) -> u32

Returns query length. The function returns the length of the sequence if it is present. Otherwise, the function returns the length calculated from the CIGAR. Unmapped records without sequence would get length 0.

pub fn aligned_query_start(&self) -> u32

Returns the index of the first aligned base in the record. Returns the length of the query for unmapped records.

pub fn aligned_query_end(&self) -> u32

Returns the index after the last aligned base in the record. Returns zero 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)

Sets reference id. Panics if less than -1. This function does not update record flag.

pub fn set_start(&mut self, start: i32)

Sets record 0-based start. Panics if 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)

Sets reference id of the mate record. Panics if argument is less than -1. This function does not update record flag.

pub fn set_mate_start(&mut self, mate_start: i32)

Sets record 0-based start of the mate record. Panics if less than -1.

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

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 std::iter::empty for qualities. If qualities are non-empty, 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_qual<U>(
    &mut self,
    raw_seq: &[u8],
    qualities: U,
    len: usize
) -> Result<(), String> where
    U: IntoIterator<Item = u8>, 

Sets raw sequence and qualities for a record. If you do not need to set qualities, use std::iter::empty for qualities.

Arguments

• sequence - in raw format: each nucleotide takes 4 bits,
• qualities - in raw format (without +33 added).
• len - number of nucleotides. If qualities are non-empty, they should have the same number of bytes.

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

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

Sets record cigar from u8 iterator. 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.

pub fn aligned_pairs(&self) -> AlignedPairs<'_>

Returns an iterator over pairs (Option<u32>, Option<u32>). The first element contains a sequence index, and the second element contains 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.

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.

pub fn alignment_entries(&self) -> Result<EntriesIter<'_>, EntriesError>

Returns an iterator over AlignmentEntry, which stores information about a single position in the record-reference alignment.

The function returns EntriesError if the record does not have a sequence or an MD tag.

for entry in record.alignment_entries().unwrap() {
    if let Some((record_pos, record_nt)) = entry.record_pos_nt() {
        print!("{} {}", record_pos, record_nt as char);
    } else {
        print!("-");
    }
    print!(", ");
    if let Some((ref_pos, ref_nt)) = entry.ref_pos_nt() {
        println!("{} {}", ref_pos, ref_nt as char);
    } else {
        println!("-");
    }
}

Iterator may panic if the MD tag does not match the alignment.

Trait Implementations

impl Clone for Record

fn clone(&self) -> Record

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for Record

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

Formats the value using the given formatter.