Struct noodles_sam::record::Record

pub struct Record { /* fields omitted */ }

A SAM record.

A SAM record has 11 required fields:

1. read name (QNAME),
2. flags (FLAG),
3. reference sequence name (RNAME),
4. position (POS),
5. mapping quality (MAPQ),
6. CIGAR string (CIGAR),
7. mate reference sequence name (RNEXT),
8. mate position (PNEXT),
9. template length (TLEN),
10. sequence (SEQ), and
11. quality scores (QUAL).

Additionally, optional data fields can be included with any record.

Implementations

impl Record

pub fn builder() -> Builder

Returns a builder to create a record from each of its fields.

Examples

use noodles_sam::{self as sam, record::Flags};

let record = sam::Record::builder()
    .set_read_name("r0".parse()?)
    .set_flags(Flags::UNMAPPED)
    .build()?;

assert_eq!(record.read_name().map(|name| name.as_str()), Some("r0"));
assert_eq!(record.flags(), Flags::UNMAPPED);
assert!(record.reference_sequence_name().is_none());
assert!(record.position().is_none());

pub fn read_name(&self) -> Option<&ReadName>

Returns the read name of this record.

This is also called the query name.

Examples

use noodles_sam as sam;

let record = sam::Record::default();
assert!(record.read_name().is_none());

let record = sam::Record::builder()
    .set_read_name("r0".parse()?)
    .build()?;
assert_eq!(record.read_name().map(|name| name.as_str()), Some("r0"));

pub fn read_name_mut(&mut self) -> &mut Option<ReadName>

Returns a mutable reference to the read name.

This is also called the query name.

Examples

use noodles_sam as sam;

let mut record = sam::Record::default();
record.read_name_mut().insert("r0".parse()?);
assert_eq!(record.read_name().map(|name| name.as_str()), Some("r0"));

*record.read_name_mut() = None;
assert!(record.read_name().is_none());

pub fn flags(&self) -> Flags

Returns the SAM flags of this record.

Examples

use noodles_sam::{self as sam, record::Flags};

let record = sam::Record::default();
assert_eq!(record.flags(), Flags::UNMAPPED);
assert_eq!(u16::from(record.flags()), 4);

let record = sam::Record::builder()
    .set_flags(Flags::PAIRED | Flags::READ_1)
    .build()?;
assert_eq!(record.flags(), Flags::PAIRED | Flags::READ_1);

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

Returns a mutable reference to the SAM flags.

Examples

use noodles_sam::{self as sam, record::Flags};

let mut record = sam::Record::builder()
    .set_flags(Flags::PAIRED | Flags::READ_1)
    .build()?;
record.flags_mut().set(Flags::DUPLICATE, true);
assert_eq!(record.flags(), Flags::PAIRED | Flags::READ_1 | Flags::DUPLICATE);

record.flags_mut().set(Flags::PAIRED | Flags::QC_FAIL, false);
assert_eq!(record.flags(), Flags::READ_1 | Flags::DUPLICATE);

pub fn reference_sequence_name(&self) -> Option<&ReferenceSequenceName>

Returns the reference sequence name of this record.

Examples

use noodles_sam as sam;

let record = sam::Record::default();
assert_eq!(record.reference_sequence_name(), None);

let record = sam::Record::builder()
    .set_reference_sequence_name("sq0".parse()?)
    .build()?;
assert_eq!(record.reference_sequence_name().map(|name| name.as_str()), Some("sq0"));

pub fn reference_sequence_name_mut(
    &mut self
) -> &mut Option<ReferenceSequenceName>

Returns a mutable reference to the reference sequence name.

Examples

use noodles_sam as sam;

let mut record = sam::Record::default();
*record.reference_sequence_name_mut() = Some("sq0".parse()?);
assert_eq!(record.reference_sequence_name().map(|name| name.as_str()), Some("sq0"));

*record.reference_sequence_name_mut() = None;
assert!(record.reference_sequence_name().is_none());

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

Returns the start position of this record.

This value is 1-based.

Examples

use noodles_sam::{self as sam, record::Position};

let record = sam::Record::default();
assert!(record.position().is_none());

let record = sam::Record::builder()
    .set_position(Position::try_from(13)?)
    .build()?;
assert_eq!(record.position().map(i32::from), Some(13));

pub fn position_mut(&mut self) -> &mut Option<Position>

Returns a mutable reference to the start position.

This value is 1-based.

Examples

use noodles_sam::{self as sam, record::Position};

let mut record = sam::Record::default();
*record.position_mut() = Some(Position::try_from(13)?);
assert_eq!(record.position().map(i32::from), Some(13));

*record.position_mut() = None;
assert!(record.position().is_none());

pub fn mapping_quality(&self) -> MappingQuality

Returns the mapping quality of this record.

Mapping quality ranges from 0 to 254, inclusive. A value of 255 means no mapping quality is set.

Examples

use noodles_sam::{self as sam, record::MappingQuality};

let record = sam::Record::default();
assert!(record.mapping_quality().is_none());
assert_eq!(u8::from(record.mapping_quality()), 255);

let record = sam::Record::builder().set_mapping_quality(MappingQuality::from(8)).build()?;
assert_eq!(*record.mapping_quality(), Some(8));

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

Returns a mutable reference to the mapping quality.

Examples

use noodles_sam::{self as sam, record::MappingQuality};

let mut record = sam::Record::default();
*record.mapping_quality_mut() = MappingQuality::from(8);
assert_eq!(*record.mapping_quality(), Some(8));

*record.mapping_quality_mut() = MappingQuality::from(255);
assert!(record.mapping_quality().is_none());

pub fn cigar(&self) -> &Cigar

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

Examples

use noodles_sam::{self as sam, record::cigar::{op, Op}};

let record = sam::Record::default();
assert!(record.cigar().is_empty());
assert_eq!(record.cigar().to_string(), "*");

let record = sam::Record::builder().set_cigar("34M2S".parse()?).build()?;
assert_eq!(record.cigar().to_string(), "34M2S");

let mut ops = record.cigar().iter();
assert_eq!(ops.next(), Some(&Op::new(op::Kind::Match, 34)));
assert_eq!(ops.next(), Some(&Op::new(op::Kind::SoftClip, 2)));
assert_eq!(ops.next(), None);

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

Returns a mutable reference to the CIGAR operations.

Examples

use noodles_sam::{self as sam, record::{cigar::{op, Op}, Cigar}};

let mut record = sam::Record::default();
assert!(record.cigar().is_empty());

let cigar = Cigar::from(vec![
    Op::new(op::Kind::Match, 36),
    Op::new(op::Kind::SoftClip, 2),
]);
*record.cigar_mut() = cigar.clone();

assert_eq!(record.cigar(), &cigar);

pub fn mate_reference_sequence_name(&self) -> Option<&ReferenceSequenceName>

Returns the mate reference sequence name of this record.

Examples

use noodles_sam as sam;

let record = sam::Record::default();
assert!(record.mate_reference_sequence_name().is_none());

let record = sam::Record::builder()
    .set_mate_reference_sequence_name("sq0".parse()?)
    .build()?;

assert_eq!(
    record.mate_reference_sequence_name().map(|name| name.as_str()),
    Some("sq0")
);

pub fn mate_reference_sequence_name_mut(
    &mut self
) -> &mut Option<ReferenceSequenceName>

Returns a mutable reference to the mate reference sequence name.

Examples

use noodles_sam as sam;

let mut record = sam::Record::default();
*record.mate_reference_sequence_name_mut() = Some("sq0".parse()?);
assert_eq!(record.mate_reference_sequence_name().map(|name| name.as_str()), Some("sq0"));

*record.mate_reference_sequence_name_mut() = None;
assert!(record.mate_reference_sequence_name().is_none());

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

Returns the start position of the mate of this record.

This value is 1-based.

Examples

use noodles_sam::{self as sam, record::Position};

let record = sam::Record::default();
assert!(record.mate_position().is_none());

let record = sam::Record::builder()
    .set_mate_position(Position::try_from(21)?)
    .build()?;
assert_eq!(record.mate_position().map(i32::from), Some(21));

pub fn mate_position_mut(&mut self) -> &mut Option<Position>

Returns a mutable reference to the start position of the mate.

This value is 1-based.

Examples

use noodles_sam::{self as sam, record::Position};

let mut record = sam::Record::default();
*record.mate_position_mut() = Some(Position::try_from(13)?);
assert_eq!(record.mate_position().map(i32::from), Some(13));

*record.mate_position_mut() = None;
assert!(record.mate_position().is_none());

pub fn template_length(&self) -> i32

Returns the template length of this record.

Examples

use noodles_sam as sam;

let record = sam::Record::default();
assert_eq!(record.template_length(), 0);

let record = sam::Record::builder().set_template_length(101).build()?;
assert_eq!(record.template_length(), 101);

pub fn template_length_mut(&mut self) -> &mut i32

Returns a mutable reference to the template length.

Examples

use noodles_sam::{self as sam, record::MappingQuality};

let mut record = sam::Record::default();
*record.template_length_mut() = 101;
assert_eq!(record.template_length(), 101);

pub fn sequence(&self) -> &Sequence

Returns the bases in the sequence of this record.

Examples

use noodles_sam::{self as sam, record::sequence::Base};

let record = sam::Record::default();
assert!(record.sequence().is_empty());
assert_eq!(record.sequence().to_string(), "*");

let record = sam::Record::builder()
    .set_sequence("AT".parse()?)
    .build()?;

assert_eq!(record.sequence().to_string(), "AT");

let mut bases = record.sequence().iter();
assert_eq!(bases.next(), Some(&Base::A));
assert_eq!(bases.next(), Some(&Base::T));
assert_eq!(bases.next(), None);

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

Returns a mutable reference to the sequence.

Examples

use noodles_sam::{self as sam, record::{sequence, Sequence}};

let mut record = sam::Record::default();
assert!(record.sequence().is_empty());

let sequence: Sequence = "ACGT".parse()?;
*record.sequence_mut() = sequence.clone();

assert_eq!(record.sequence(), &sequence);

pub fn quality_scores(&self) -> &QualityScores

Returns the quality score for each base in the sequence.

Examples

use noodles_sam::{self as sam, record::quality_scores::Score};

let record = sam::Record::default();
assert!(record.quality_scores().is_empty());
assert_eq!(record.quality_scores().to_string(), "*");

let record = sam::Record::builder()
    .set_sequence("AC".parse()?)
    .set_quality_scores("ND".parse()?)
    .build()?;

assert_eq!(record.quality_scores().to_string(), "ND");

let mut scores = record.quality_scores().iter().copied().map(u8::from);
assert_eq!(scores.next(), Some(45));
assert_eq!(scores.next(), Some(35));
assert_eq!(scores.next(), None);

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

Returns a mutable reference to the quality scores.

Examples

use noodles_sam::{self as sam, record::{quality_scores, QualityScores}};

let mut record = sam::Record::default();
assert!(record.quality_scores().is_empty());

let quality_scores: QualityScores = "NDLS".parse()?;
*record.quality_scores_mut() = quality_scores.clone();

assert_eq!(record.quality_scores(), &quality_scores);

pub fn data(&self) -> &Data

Returns the optional data fields for this record.

Examples

use noodles_sam::{self as sam, record::{data, Data}};

let record = sam::Record::default();
assert!(record.data().is_empty());

let data = Data::try_from(vec![data::Field::new(
    data::field::Tag::AlignmentHitCount,
    data::field::Value::Int(1),
)])?;
let record = sam::Record::builder().set_data(data).build()?;
assert_eq!(record.data().to_string(), "NH:i:1");

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

Returns a mutable reference to the data fields for this record.

Examples

use noodles_sam::{self as sam, record::data};

let mut record = sam::Record::default();
assert!(record.data().is_empty());

let field = data::Field::new(
    data::field::Tag::AlignmentHitCount,
    data::field::Value::Int(1),
);

let data = record.data_mut();
data.insert(field.clone());

let data = record.data();
assert_eq!(data.len(), 1);
assert_eq!(data.get(field.tag()), Some(&field));

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

Formats the value using the given formatter.

impl Default for Record

fn default() -> Self

Returns the “default value” for a type.

impl Display for Record

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

Formats the value using the given formatter.

impl FromStr for Record

type Err = ParseError

The associated error which can be returned from parsing.

fn from_str(s: &str) -> Result<Self, Self::Err>

Parses a string s to return a value of this 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_sam::{self as sam, header::ReferenceSequences, RecordExt};
let record = sam::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_sam::{self as sam, RecordExt};
let record = sam::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_sam::{self as sam, RecordExt};
let record = sam::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_sam::{self as sam, header::ReferenceSequences, RecordExt};
let record = sam::Record::default();
let reference_sequences = ReferenceSequences::default();
assert!(record.mate_reference_sequence(&reference_sequences).is_none());

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

Calculates the end position.

impl StructuralPartialEq for Record