Struct noodles_bam::record::Record

pub struct Record { /* fields omitted */ }

A BAM record.

A BAM record encodes the same fields as a SAM record:

• reference sequence ID (RNAME equiv.),
• position (POS),
• mapping quality (MAPQ),
• flags (FLAG),
• mate reference sequence ID (RNEXT equiv.),
• mate position (PNEXT),
• template length (TLEN),
• read name (QNAME),
• CIGAR operations (CIGAR),
• sequence (SEQ),
• quality scores (QUAL), and
• optional data fields.

Additionally, it encodes the BAM index bin (bin).

A bam::Record and its fields store raw values and care should be taken when manipulating them.

Implementations

impl Record

pub fn try_from_sam_record(
    reference_sequences: &ReferenceSequences,
    sam_record: &Record
) -> Result<Self>

Converts a SAM record to a BAM record.

Examples

use noodles_bam as bam;
use noodles_sam::{self as sam, header::ReferenceSequences};

let reference_sequences = ReferenceSequences::default();
let sam_record = sam::Record::default();

let record = bam::Record::try_from_sam_record(&reference_sequences, &sam_record)?;
assert_eq!(record, bam::Record::default());

pub fn try_into_sam_record(
    &self,
    reference_sequences: &ReferenceSequences
) -> Result<Record>

Converts this record to a SAM record.

Examples

use noodles_bam as bam;
use noodles_sam as sam;

let reference_sequences = sam::header::ReferenceSequences::default();

let record = bam::Record::default();
let sam_record = record.try_into_sam_record(&reference_sequences)?;

assert_eq!(sam_record, sam::Record::default());

impl Record

pub fn builder() -> Builder

Creates a BAM record builder.

Examples

use noodles_bam as bam;
let builder = bam::Record::builder();
let record = builder.build()?;

pub fn reference_sequence_id(&self) -> Option<ReferenceSequenceId>

Returns the reference sequence ID of this record.

The reference sequence ID is the index of the associated reference sequence in the SAM header or BAM reference sequences.

Examples

use noodles_bam as bam;
let record = bam::Record::default();
assert!(record.reference_sequence_id().is_none());

pub fn reference_sequence_id_mut(&mut self) -> &mut Option<ReferenceSequenceId>

Returns a mutable reference to the reference sequence ID.

Examples

use noodles_bam::{self as bam, record::ReferenceSequenceId};

let mut record = bam::Record::default();
*record.reference_sequence_id_mut() = ReferenceSequenceId::try_from(1).map(Some)?;

assert_eq!(record.reference_sequence_id().map(i32::from), Some(1));

pub fn position(&self) -> Option<Position>

Returns the start position of this record.

Despite the BAM format using 0-based positions, this normalizes the value as a 1-based position.

Examples

use noodles_bam as bam;
let record = bam::Record::default();
assert!(record.position().is_none());

pub fn mapping_quality(&self) -> MappingQuality

Returns the mapping quality of this record.

Examples

use noodles_bam as bam;
let record = bam::Record::default();
assert!(record.mapping_quality().is_none());

pub fn mapping_quality_mut(&mut self) -> &mut MappingQuality

Returns a mutable reference to the mapping quality.

Examples

use noodles_bam as bam;
use noodles_sam::record::MappingQuality;

let mut record = bam::Record::default();
*record.mapping_quality_mut() = MappingQuality::from(13);

assert_eq!(record.mapping_quality().map(u8::from), Some(13));

pub fn bin(&self) -> u16

Returns the index bin that includes this record.

Examples

use noodles_bam as bam;
let record = bam::Record::default();
assert_eq!(record.bin(), 4680);

pub fn flags(&self) -> Flags

Returns the SAM flags of this record.

Examples

use noodles_bam as bam;
use noodles_sam as sam;
let record = bam::Record::default();
assert_eq!(record.flags(), sam::record::Flags::UNMAPPED);

pub fn flags_mut(&mut self) -> &mut Flags

Returns a mutable reference to the flags.

Examples

use noodles_bam as bam;
use noodles_sam::record::Flags;
let mut record = bam::Record::default();
*record.flags_mut() = Flags::PAIRED | Flags::READ_1;
assert_eq!(record.flags(), Flags::PAIRED | Flags::READ_1);

pub fn mate_reference_sequence_id(&self) -> Option<ReferenceSequenceId>

Returns the reference sequence ID of the mate of this record.

The mate reference sequence ID is the index of the associated reference sequence in the SAM header or BAM reference sequences.

Examples

use noodles_bam as bam;
let record = bam::Record::default();
assert!(record.mate_reference_sequence_id().is_none());

pub fn mate_reference_sequence_id_mut(
    &mut self
) -> &mut Option<ReferenceSequenceId>

Returns a mutable reference to the mate reference sequence ID.

Examples

use noodles_bam::{self as bam, record::ReferenceSequenceId};

let mut record = bam::Record::default();
*record.mate_reference_sequence_id_mut() = ReferenceSequenceId::try_from(1).map(Some)?;

assert_eq!(record.mate_reference_sequence_id().map(i32::from), Some(1));

pub fn mate_position(&self) -> Option<Position>

Returns the start position of the mate of this record.

Despite the BAM format using 0-based positions, this normalizes the value as a 1-based position.

Examples

use noodles_bam as bam;
let record = bam::Record::default();
assert!(record.mate_position().is_none());

pub fn template_length(&self) -> i32

Returns the template length of this record.

Examples

use noodles_bam as bam;
let record = bam::Record::default();
assert_eq!(record.template_length(), 0);

pub fn read_name(&self) -> Result<&CStr, FromBytesWithNulError>

Returns the read name of this record.

This is also called the query name.

Examples

use noodles_bam as bam;
let record = bam::Record::default();
assert_eq!(record.read_name()?.to_bytes(), b"*");

pub fn cigar(&self) -> &Cigar

Returns the CIGAR operations that describe how the read was mapped.

Examples

use noodles_bam as bam;
let record = bam::Record::default();
assert!(record.cigar().is_empty());

pub fn cigar_mut(&mut self) -> &mut Cigar

Returns a mutable reference to the CIGAR.

Examples

use noodles_bam::{self as bam, record::cigar::Op};
use noodles_sam::record::cigar::op::Kind;

let mut record = bam::Record::default();

let op = Op::new(Kind::Match, 36)?;
record.cigar_mut().push(op);

assert_eq!(record.cigar().as_ref(), [0x00000240]);
Ok::<_, bam::record::cigar::op::LengthError>(())

pub fn sequence(&self) -> &Sequence

Returns the bases in the sequence of this record.

Examples

use noodles_bam as bam;
let record = bam::Record::default();
assert!(record.sequence().is_empty());

pub fn sequence_mut(&mut self) -> &mut Sequence

Returns a mutable reference to the sequence.

Examples

use noodles_bam::{self as bam, record::sequence::Base};

let mut record = bam::Record::default();

let sequence = record.sequence_mut();
sequence.push(Base::A);
sequence.set_len(1);

assert_eq!(record.sequence().as_ref(), [0x10]); // A
assert_eq!(record.sequence().len(), 1);

pub fn quality_scores(&self) -> &QualityScores

Returns the quality score for each base in the sequence.

Examples

use noodles_bam as bam;
let record = bam::Record::default();
assert!(record.quality_scores().is_empty());

pub fn quality_scores_mut(&mut self) -> &mut QualityScores

Returns a mutable reference to the quality scores.

Examples

use noodles_bam as bam;
use noodles_sam::record::quality_scores::Score;

let mut record = bam::Record::default();
record.quality_scores_mut().push(Score::try_from(8)?);

assert_eq!(record.quality_scores().as_ref(), [8]);

pub fn data(&self) -> &Data

Returns the optional data fields for this record.

Examples

use noodles_bam as bam;
let record = bam::Record::default();
assert!(record.data().is_empty());

pub fn data_mut(&mut self) -> &mut Data

Returns a mutable reference to the data.

Examples

use noodles_bam::{self as bam, record::data::{field::Value, Field}};
use noodles_sam::record::data::field::Tag;

let mut record = bam::Record::default();

let nh = Field::new(Tag::AlignmentHitCount, Value::UInt8(1));
record.data_mut().insert(nh).transpose()?;

assert_eq!(record.data().len(), 1);

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, fmt: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for Record

fn default() -> Self

Returns the “default value” for a type.

impl PartialEq<Record> for Record

fn eq(&self, other: &Record) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Record) -> bool

This method tests for !=.

impl RecordExt for Record

fn reference_sequence<'rs>(
    &self,
    reference_sequences: &'rs ReferenceSequences
) -> Option<Result<&'rs ReferenceSequence>>

Returns the associated reference sequence.

Examples

use noodles_bam as bam;
use noodles_sam::{header::ReferenceSequences, RecordExt};

let record = bam::Record::default();
let reference_sequences = ReferenceSequences::default();

assert!(record.reference_sequence(&reference_sequences).is_none());

fn alignment_start(&self) -> Option<Position>

Returns the start position.

Examples

use noodles_bam as bam;
use noodles_sam::RecordExt;
let record = bam::Record::default();
assert!(record.alignment_start().is_none());

fn alignment_span(&self) -> Result<u32>

Calculates the alignment span over the reference sequence.

Examples

use noodles_bam as bam;
use noodles_sam::RecordExt;
let record = bam::Record::default();
assert_eq!(record.alignment_span()?, 0);

fn mate_reference_sequence<'rs>(
    &self,
    reference_sequences: &'rs ReferenceSequences
) -> Option<Result<&'rs ReferenceSequence>>

Returns the associated reference sequence of the mate.

Examples

use noodles_bam as bam;
use noodles_sam::{header::ReferenceSequences, RecordExt};

let record = bam::Record::default();
let reference_sequences = ReferenceSequences::default();

assert!(record.mate_reference_sequence(&reference_sequences).is_none());

fn alignment_end(&self) -> Option<Result<Position, Error>>

Calculates the end position.

impl Eq for Record

impl StructuralEq for Record

impl StructuralPartialEq for Record