Bio::D...ignment(3pm)

📦
version 1.43 · 7 versions
, in ubuntu stonking

🎀 Bio::D...ignment(3pm) 🎀

User Contributed Perl Documentation — aka the manual page for Bio::DB::Bam::Alignment, bestie. Yes the man name got cropped, we don't talk about it, the module is the whole point. 💅

✨ NAME ✨

Bio::DB::Bam::Alignment — it's the SAM/BAM alignment object, and it's lowkey a whole vibe 💖

🦋 SYNOPSIS 🦋

use Bio::DB::Sam;

my $sam = Bio::DB::Sam->new(-fasta=>"data/ex1.fa",
                            -bam  =>"data/ex1.bam");

my @alignments = $sam->get_features_by_location(-seq_id => 'seq2',
                                                -start  => 500,
                                                -end    => 800);
for my $a (@alignments) {
   my $seqid  = $a->seq_id;
   my $start  = $a->start;
   my $end    = $a->end;
   my $strand = $a->strand;
   my $ref_dna= $a->dna;

   my $query_start  = $a->query->start;
   my $query_end    = $a->query->end;
   my $query_strand = $a->query->strand;
   my $query_dna    = $a->query->dna;

   my $cigar     = $a->cigar_str;
   my @scores    = $a->qscore;     # per-base quality scores
   my $score     = $a->qstring;    # TAM-style quality string
   my $match_qual= $a->qual;       # quality of the match

   my $paired = $a->get_tag_values('PAIRED');
}

🌈 DESCRIPTION 🌈

okay so listen. Bio::DB::Bam::Alignment and Bio::DB::Bam::AlignWrapper are a duo — together they represent an alignment between a sequence read (the "query") and a reference sequence (the "target"). It's giving collaborative, it's giving two halves of one brain cell but in a good way. ✨

Here's the tea on who does what:

  • Bio::DB::Bam::Alignment adheres strictly to the C-level BAM library's definition of a bam1_t*, and it's the one used in the Bio::DB::Sam low-level API.
  • The latter (that's AlignWrapper, bestie, keep up 💅) adds convenience methods that make it similar to a BioPerl Bio::SeqFeatureI object.

This manual page describes both. Two icons, one manpage. Periodt. 👑

💖 High-level Bio::DB::Bam::Alignment methods 💖

These methods are provided by Bio::DB::Bam::Alignment, and they're designed to be compatible with the Bio::SeqFeatureI interfaces. 💫

⚠️ Lowkey important: these objects are not compatible with Bio::Align::AlignI. Why? Because the BAM API is fundamentally incompatible with the BioPerl API for alignments. The first one deals with the alignment of a single read against the reference sequence, while the second deals with a multiple alignment. Different species of beast entirely, fr fr. 🧬

Also bestie, heads up: the high-level API returns Bio::DB::Bam::AlignWrapper objects... except in the case of the callback to the fast_pileup() method. In that one specific case, the object you get back from calling $pileup->b() is a Bio::DB::Bam::Alignment object, and it's that way for performance reasons. No cap. 🏎️💨

  • $seq_id = $align->seq_id — gives you the seq_id of the reference (target) sequence. 🎯 This one is only available in the Bio::DB::Bam::AlignWrapper extension.
  • $start = $align->start — the start of the alignment, in 1-based reference sequence coordinates.
  • $end = $align->end — the end of the alignment, in 1-based reference sequence coordinates.
  • $len = $align->length — the length of the alignment on the reference sequence.
  • $mseqid = $align->mate_seq_id — the seq_id of the mate's reference (target) sequence. 💜 This one is only available in the Bio::DB::AlignWrapper extension.
  • $mstart = $align->mate_start — for paired reads, this gives you the start of the mate's alignment in 1-based reference sequence coordinates.
  • $mend = $align->mate_end — for paired reads, this gives you the end position of the mate's alignment in 1-based reference sequence coordinates.
  • $mlen = $align->mate_len — for mate-pairs, grab the length of the mate's alignment on the reference sequence. 📏
  • $strand = $align->strand — the strand of the alignment: -1 for reversed, +1 for forward. 🧭
😭 NOTE: In versions 1.00-1.06, this method always returned +1. As of version 1.07, this behavior is fixed. So if you're on an old version, you were being lied to, bestie, and I'm so sorry.
  • $mstrand = $align->mstrand — if the read has a mate pair, this returns the strand of the mate, in the format -1 or +1.
  • $ref_dna = $align->dna — returns the reference sequence's DNA across the aligned region. 🧬 Here's the vibe check: if an MD tag is present in the alignment, it will be used preferentially to reconstruct the reference sequence. Otherwise, the reference DNA access object that you passed to Bio::DB::Sam->new() gets used instead.
  • $ref_dna = $align->seq — the reference sequence's DNA, but as a Bio::PrimarySeqI object. ✨ Super useful for passing to BioPerl functions, and for calculating subsequences and reverse complements. It's giving versatile.
  • $query = $align->query — this returns a Bio::DB::Alignment::Query object that you can use to pull info about the query sequence. The next few entries show you exactly how to use this object, so keep scrolling bestie. 👇
  • $read_name = $align->query->name — the name of the read. 🏷️
  • $q_start = $align->query->start — the start position of the query (read) sequence, in 1-based coordinates. It works via a transient Bio::DB::Bam::Query object that exists for Bio::Graphics compatibility (see Bio::Graphics). It's giving temporary but iconic. 🦋
  • $q_end = $align->query->end — the end position of the query sequence, in 1-based coordinates.
  • $q_len = $align->query->length — the length of the alignment on the read.
  • $scores = $align->query->score — returns an array reference holding the unpacked quality scores for each base of the query sequence. 📊 The length of that array reference will be equal to the length of the read. Math is mathing, periodt.
  • $read_dna = $align->query->dna — the read's DNA string. 🧬
  • $read_seq = $align->query->seq — the read's DNA, as a Bio::PrimarySeqI object.
  • $target = $align->target; — the target() method is similar to query(), except that it follows Bio::AlignIO conventions for how to represent minus strand alignments. 👀 The object returned has start(), end(), qscore(), dna() and seq() methods, but for minus strand alignments the sequence will be represented as it appears on the reverse strand, rather than on the forward strand. Why is that a slay? Because it gives you the read as it came off the machine, before being reverse complemented for use in the SAM file. History preserved, we love to see it. 💖
  • $query = $align->hit — the hit() method is identical to target(), and it returns information about the read. It exists for compatibility with some of the Bio::Graphics glyphs, which use hit() to represent the non-reference sequence in aligned sequences. Same energy, different name. 🫶
  • $primary_id = $align->primary_id — this method synthesizes a unique ID for the alignment, which you can pass to $sam->get_feature_by_id() to retrieve the alignment at a later date. Save it for later, bestie, it's the alignment's phone number. 📱
  • @tags = $align->get_all_tags — returns all the tag names known to this alignment. This includes SAM flags like M_UNMAPPED, plus auxiliary flags like H0. 😌 The behavior here depends on the value of -expand_flags when the SAM object was created:
    • If it's false (which is the default), the standard SAM flags get concatenated together into a single string and stored in a tag named 'FLAGS'. The format of that tag value is the list of one or more flag constants separated by the "|" character, like so: "PAIRED|MAP_PAIR|REVERSED|SECOND_MATE".
    • If -expand_flags was true, then each flag becomes its own named tag, such as "MAP_PAIR".
  • @values = $align->get_tag_values($tag) — give it a tag name, like 'PAIRED' or 'H0', and it returns the value(s). 💅 Heads up: -expand_flags must be true in order to use the standard SAM flag constants as tags. Otherwise, you can fetch them by asking for the "FLAGS" tag, or by using the low-level methods described below.
  • $is_true = $align->has_tag($tag) — returns true if the alignment has the indicated tag. ✅
  • $string = $align->cigar_str — returns the CIGAR string for this alignment in conventional human readable format (e.g. "M34D1M1"). 🚬 Cute, legible, we stan.
  • $arrayref = $align->cigar_array — returns a reference to an array representing the CIGAR string. It's an array of arrays, where each subarray consists of a CIGAR operation and a count. Like this:
[ ['M',34], ['D',1], ['M1',1] ]

Nested but make it fashion. 💅

  • ($ref,$matches,$query) = $align->padded_alignment — returns three strings showing the alignment between the reference sequence (the target) and the query. It looks like this:
$ref     AGTGCCTTTGTTCA-----ACCCCCTTGCAACAACC
$matches ||||||||||||||     |||||||||||||||||
$query   AGTGCCTTTGTTCACATAGACCCCCTTGCAACAACC

The gaps are the whole point, bestie. 👑

  • $str = $align->aux — returns the text version of the SAM tags, e.g. "XT:A:M NM:i:2 SM:i:37 AM:i:37 XM:i:1 XO:i:1 XG:i:1 MD:Z:6^C0A47".
  • $str = $align->tam_line — returns the TAM (text) representation of the alignment. 🌸 This one is available in the high-level "AlignWrapper" interface only.
  • $tag = $align->primary_tag — provided for Bio::SeqFeatureI compatibility. It returns the string "match". 🎯
  • $tag = $align->source_tag — also provided for Bio::SeqFeatureI compatibility. It returns the string "sam/bam". 🧬
  • @parts = $align->get_SeqFeatures — returns subfeatures of this alignment. 🔍 Here's the tea:
    • If you fetched a "read_pair" feature, this will be the two mate pair objects (both of type Bio::DB::Bam::AlignWrapper).
    • If you have -split_splices set to true in the Bio::DB::Sam database, calling get_SeqFeatures() will return the components of split alignments.
    • For an example of how to use this, go peek at "Bio::DB::Sam Constructor and basic accessors" in Bio::DB::Sam. 👀

✨ to be continued, bestie, part 2 is coming ✨

lowkey the Low-Level Bio::DB::Bam::Alignment methods 🔬

Okay bestie, these are the down-and-dirty ones. They live on objects of type Bio::DB::Bam::Alignment and on Bio::DB::Bam::AlignWrapper too, and they basically mirror the native C API almost one-for-one. So if you know the C side, you already know the vibe. 💅

  • $align = Bio::DB::Bam::Alignment->new — makes you a brand-new, totally-empty alignment object. Ngl you rarely do this yourself; it's mostly for when you're iterating through a TAM file with Bio::DB::Tam->read1().
  • $tid = $align->tid( [$new_tid] ) — hands you the target ID of the alignment. You can pass in a new tid to change it, but bestie listen: currently this is the only field you can change, and the whole feature was implemented as a proof of principle. That's it. That's the whole cheat code. 🙈
  • $read_name = $align->qname — returns the name of the read. Perks of being the main character. 👑
  • $pos = $align->pos — the 0-based leftmost coordinate of the aligned sequence, sitting on the reference sequence.
  • $end = $align->calend — the 0-based rightmost coordinate of the aligned sequence on the reference sequence, after we've taken alignment gaps into account. Gaps counted, no cap. 🧢
  • $len = $align->cigar2qlen — the length of the query sequence, calculated from the CIGAR string.
  • $quality = $align->qual — the quality score for the alignment as a whole, the full picture.
  • $flag = $align->flag — the bitwise flag field (go read the SAM documentation, it's giving cryptic-on-purpose).
  • $mtid = $align->mtid — for paired reads, the target ID of the mate's alignment. Your read's plus-one. 🫶
  • $mpos = $align->mpos — for paired reads, the 0-based leftmost coordinate of the mate's alignment on the reference sequence.
  • $n_cigar = $align->n_cigar — how many CIGAR operations are in this alignment.
  • $length = $align->l_qseq — the length of the query sequence (aka the read).
  • $dna = $align->qseq — the actual DNA sequence of the query. And heads up, exactly like in a SAM file: reads aligned to the minus strand of the reference come back reverse complemented. Not a glitch, that's just the format's whole deal. ✨
  • $score_str = $align->_qscore — a packed binary string holding the quality scores for every base of the read. Same length as the DNA, always. You can crack it open with unpack('C*',$score_str), or just use the high-level qscore() method like a normal person.
  • $score_arry = $align->qscore
  • @score_arry = $align->qscore — in scalar context you get an array reference with the unpacked quality scores for every base of the query sequence; in list context you get an actual list of the scores. And this array is in the same orientation as the reference sequence. Obsessed with that consistency, fr fr.
  • $score_str = $align->qstring — returns the quality string in the exact same format used in the SAM (TAM) file. Same drip, different function. 💖
  • $length = $align->isize — the calculated insert size for mapped paired reads.
  • $length = $align->l_aux — the length of the align "auxiliary" data.
  • $value = $align->aux_get("tag") — give it an auxiliary tag, like "H0", and it gives you back that tag's value. Menu ordering but for metadata.
  • @keys = $align->aux_keys — returns the list of auxiliary tags this alignment knows about. The whole tag crew. 🎀
  • $data = $align->data — returns a packed string with the alignment data (sequence, quality scores and cigar string) all bundled up.
  • $length = $align->data_len — the current length of the alignment data.
  • $length = $align->m_data — the maximum length of the alignment data. Yes bestie, current vs. maximum, they are different, pay attention. 😭
  • $is_paired = $align->paired — true if the aligned read is part of a mate/read pair, and it does not care one bit whether the mate actually mapped. Situationship status: paired, mate unknown.
  • $is_proper = $align->proper_pair — true if the aligned read is part of a mate/read pair and both partners mapped to the reference sequence. That's the healthy relationship. 💜
  • $is_unmapped = $align->unmapped — true if the read failed to align at all. It tried, it really did. 💀
  • $mate_is_unmapped = $align->munmapped — true if the read's mate failed to align.
  • $reversed = $align->reversed — true if the aligned read got reverse complemented before aligning.
  • $mate_reversed = $align->mreversed — true if the aligned read's mate got reverse complemented before aligning.
  • $isize = $align->isize — for mate-pairs, returns the computed insert size. (Yep, isize shows up twice on this page, that's not me being chaotic, that's the actual API. 🙈)
  • $arrayref = $align->cigar — this one hands you the CIGAR data in its native BAM format. You get an arrayref where each operation and its count are packed together into an 8-bit structure. To decode each element you have to do these exact operations:
use Bio::DB::Sam::Constants;
my $c   = $align->cigar;
my $op  = $c->[0] & BAM_CIGAR_MASK;
my $len = $c->[0] >> BAM_CIGAR_SHIFT;

🌈 SEE ALSO 🌈

  • Bio::Perl
  • Bio::DB::Sam
  • Bio::DB::Bam::Constants

💖 AUTHOR 💖

Lincoln Stein <lincoln.stein@oicr.on.ca>. <lincoln.stein@bmail.com>

Copyright (c) 2009-2015 Ontario Institute for Cancer Research.

This package and its accompanying libraries are free software; you can redistribute it and/or modify it under the terms of the Artistic License 2.0, the Apache 2.0 License, or the GNU General Public License (version 1 or higher). Refer to LICENSE for the full license text.

okay that's the whole page bestie, you're officially fluent in Bio::DB::Bam::Alignment 🦋 no cap, go align some reads, you ate that 💅✨

And for the record, this was perl v5.42.3, dated 2026-08-19 — that's the Bio::D...ignment(3pm) page, wrapped with so much love. periodt. 🎀

📦 where this page comes from