Class BamAlignmentRecord

Represent a record from a BAM or SAM file.

/*!
 * @class BamAlignmentRecord
 * 
 * @headerfile <seqan/bam_io.h>
 * 
 * @brief Represent a record from a BAM or SAM file.
 * 
 * @signature class BamAlignmentRecord;
 * 
 * @section Remarks
 * 
 * While also used to represent SAM records, the type is called
 * <tt>BamAlignmentRecord</tt> since the data directly reflects a BAM records
 * (0-based positions, identify references by id, and tags are stored in BAM
 * format.
 * 
 * @fn BamAlignmentRecord::BamAlignmentRecord
 * 
 * @brief Default constructor.
 * 
 * @signature BamAlignmentRecord::BamAlignmentRecord();
 * 
 * @var __uint32 BamAlignmentRecord::INVALID_POS;
 * 
 * @brief Static member with invalid sentinel/position value (-1).
 * 
 * @var __uint32 BamAlignmentRecord::INVALID_REFID;
 * 
 * @brief Static member with invalid sentinel/position value (-1).
 * 
 * @var __uint32 BamAlignmentRecord::INVALID_LEN;
 * 
 * @brief Static member with invalid/sentinel reference ids (0 as in BAM/SAM).
 * 
 * @var CharString BamAlignmentRecord::qName;
 * 
 * @brief The query/read name.
 * 
 * Note that the reads of a template all of the same query name and are
 * differentiated by their position and the
 * <tt>BAM_FLAG_FIRST</tt>/<tt>BAM_FLAG_LAST</tt> flag values.
 * 
 * @var __uint16 BamAlignmentRecord::flag;
 * 
 * @brief The flag of this mapping.
 * 
 * See @link BamFlags @endlink for flag constants and also see the
 * <tt>hasFlag*()</tt> functions.
 * 
 * @var __int32 BamAlignmentRecord::rID;
 * 
 * @brief ID of reference for this fragment mapping (0-based,
 *        <tt>INVALID_REFID</tt> for '*' in SAM).
 * 
 * @var __int32 BamAlignmentRecord::beginPos;
 * 
 * @brief Begin position of the alignment (0-based, <tt>INVALID_POS</tt> for '0'
 *        in SAM).
 * 
 * @var __uint8 BamAlignmentRecord::mapQ;
 * 
 * @brief Mapping quality (255 for '*').
 * 
 * @var __uint16 BamAlignmentRecord::bin;
 * 
 * @brief The bin of the alignment, automatically computed when writing BAM.
 * 
 * @var TCigarString BamAlignmentRecord::cigar;
 * 
 * @brief The CIGAR string for the BAM alignment (of type String<CigarElement<>
 *        >).
 * 
 * @var __int32 BamAlignmentRecord::rNextId;
 * 
 * @brief The ID of the reference where the next fragment in this template
 *        aligns.
 * 
 * <tt>INVALID_REFID</tt> for '*'.
 * 
 * @var __int32 BamAlignmentRecord::pNext;
 * 
 * @brief Position on the reference where the next fragment in this template
 *        aligns.
 * 
 * <tt>INVALID_POS</tt> for '*'.
 * 
 * @var __int32 BamAlignmentRecord::tLen;
 * 
 * @brief The inferred template size.
 * 
 * <tt>INVALID_LEN</tt> for '*'.
 * 
 * @var CharString BamAlignmentRecord::seq;
 * 
 * @brief The fragment sequence.
 * 
 * @var CharString BamAlignmentRecord::qual;
 * 
 * @brief The PHRED quality values of the sequence (as in SAM), empty for '*'.
 * 
 * @var CharString BamAlignmentRecord::tags;
 * 
 * @brief Raw BAM tag string, use @link BamTagsDict @endlink for comfortable
 *        access.
 * 
 * @fn BamAlignmentRecord#clear
 * 
 * @brief Clear BamAlignmentRecord.
 * 
 * @signature void clear(record);
 * 
 * @param[in,out] record The BamAlignmentRecord to clear.
 * 
 * Clears all strings and resets it to default initialization state.
 * 
 * @fn BamAlignmentRecord#hasFlagMultiple
 * 
 * @headerfile <seqan/bam_io.h>
 * 
 * @brief Return true if a @link BamAlignmentRecord @endlink has the "multiple"
 *        flag set.
 * 
 * @signature bool hasFlagMultiple(record);
 * 
 * @param[in] record The BamAlignmentRecord to query.
 * 
 * @return bool <tt>true</tt> if the flag is set, <tt>false</tt> otherwise.
 * 
 * @see BamFlags
 * 
 * @fn BamAlignmentRecord#hasFlagAllProper
 * 
 * @headerfile <seqan/bam_io.h>
 * 
 * @brief Return true if a @link BamAlignmentRecord @endlink has the "all
 *        properly aligned" flag set.
 * 
 * @signature bool hasFlagAllProper(record);
 * 
 * @param[in] record The BamAlignmentRecord to query.
 * 
 * @return bool <tt>true</tt> if the flag is set, <tt>false</tt> otherwise.
 * 
 * @see BamFlags
 * 
 * @fn BamAlignmentRecord#hasFlagUnmapped
 * 
 * @headerfile <seqan/bam_io.h>
 * 
 * @brief Return true if a @link BamAlignmentRecord @endlink has the "unmapped"
 *        flag set.
 * 
 * @signature bool hasFlagUnmapped(record);
 * 
 * @param[in] record The BamAlignmentRecord to query.
 * 
 * @return bool <tt>true</tt> if the flag is set, <tt>false</tt> otherwise.
 * 
 * @see BamFlags
 * 
 * @fn BamAlignmentRecord#hasFlagNextUnmapped
 * 
 * @headerfile <seqan/bam_io.h>
 * 
 * @brief Return true if a @link BamAlignmentRecord @endlink has the "next
 *        unmapped" flag set.
 * 
 * @signature bool hasFlagNextUnmapped(record);
 * 
 * @param[in] record The BamAlignmentRecord to query.
 * 
 * @return bool <tt>true</tt> if the flag is set, <tt>false</tt> otherwise.
 * 
 * @see BamFlags
 * 
 * @fn BamAlignmentRecord#hasFlagRC
 * 
 * @headerfile <seqan/bam_io.h>
 * 
 * @brief Return true if a @link BamAlignmentRecord @endlink has the "reverse-
 *        complemented" flag set.
 * 
 * @signature bool hasFlagRC(record);
 * 
 * @param[in] record The BamAlignmentRecord to query.
 * 
 * @return bool <tt>true</tt> if the flag is set, <tt>false</tt> otherwise.
 * 
 * @see BamFlags
 * 
 * @fn BamAlignmentRecord#hasFlagNextRC
 * 
 * @headerfile <seqan/bam_io.h>
 * 
 * @brief Return true if a @link BamAlignmentRecord @endlink has the "next
 *        reverse-complemented" flag set.
 * 
 * @signature bool hasFlagNextRC(record);
 * 
 * @param[in] record The BamAlignmentRecord to query.
 * 
 * @return bool <tt>true</tt> if the flag is set, <tt>false</tt> otherwise.
 * 
 * @see BamFlags
 * 
 * @fn BamAlignmentRecord#hasFlagFirst
 * 
 * @headerfile <seqan/bam_io.h>
 * 
 * @brief Return true if a @link BamAlignmentRecord @endlink has the "first in
 *        template" flag set.
 * 
 * @signature bool hasFlagFirst(record);
 * 
 * @param[in] record The BamAlignmentRecord to query.
 * 
 * @return bool <tt>true</tt> if the flag is set, <tt>false</tt> otherwise.
 * 
 * @see BamFlags
 * 
 * @fn BamAlignmentRecord#hasFlagLast
 * 
 * @headerfile <seqan/bam_io.h>
 * 
 * @brief Return true if a @link BamAlignmentRecord @endlink has the "last in
 *        template" flag set.
 * 
 * @signature bool hasFlagLast(record);
 * 
 * @param[in] record The BamAlignmentRecord to query.
 * 
 * @return bool <tt>true</tt> if the flag is set, <tt>false</tt> otherwise.
 * 
 * @see BamFlags
 * 
 * @fn BamAlignmentRecord#hasFlagSecondary
 * 
 * @headerfile <seqan/bam_io.h>
 * 
 * @brief Return true if a @link BamAlignmentRecord @endlink has the "secondary"
 *        flag set.
 * 
 * @signature bool hasFlagSecondary(record);
 * 
 * @param[in] record The BamAlignmentRecord to query.
 * 
 * @return bool <tt>true</tt> if the flag is set, <tt>false</tt> otherwise.
 * 
 * @see BamFlags
 * 
 * @fn BamAlignmentRecord#hasFlagQCNoPass
 * 
 * @headerfile <seqan/bam_io.h>
 * 
 * @brief Return true if a @link BamAlignmentRecord @endlink has the "did not
 *        pass QC" flag set.
 * 
 * @signature bool hasFlagQCNoPass(record);
 * 
 * @param[in] record The BamAlignmentRecord to query.
 * 
 * @return bool <tt>true</tt> if the flag is set, <tt>false</tt> otherwise.
 * 
 * @see BamFlags
 * 
 * @fn BamAlignmentRecord#hasFlagDuplicate
 * 
 * @headerfile <seqan/bam_io.h>
 * 
 * @brief Return true if a @link BamAlignmentRecord @endlink has the "duplicate"
 *        flag set.
 * 
 * @signature bool hasFlagDuplicate(record);
 * 
 * @param[in] record The BamAlignmentRecord to query.
 * 
 * @return bool <tt>true</tt> if the flag is set, <tt>false</tt> otherwise.
 * 
 * @see BamFlags
 * 
 * @fn BamAlignmentRecord#hasFlagSupplementary
 * 
 * @headerfile <seqan/bam_io.h>
 * 
 * @brief Return true if a @link BamAlignmentRecord @endlink has the
 *        "supplementary" flag set.
 * 
 * @signature bool hasFlagSupplementary(record);
 * 
 * @param record The BamAlignmentRecord to query.
 * 
 * @return bool <tt>true</tt> if the flag is set, <tt>false</tt> otherwise.
 * 
 * @fn BamAlignmentRecord#getAlignmentLengthInRef
 * 
 * @headerfile <seqan/bam_io.h>
 * 
 * @brief Return the alignment length in the record's projection in the
 *        reference.
 * 
 * @signature unsigned getAlignmentLengthInRef(record);
 * 
 * @param[in] record The BamAlignmentRecord to compute length for.
 * 
 * @return unsigned The alignment length.
 * 
 * @see BamFlags
 * 
 * @fn BamAlignmentRecord#bamRecordToAlignment
 * 
 * @headerfile <seqan/bam_io.h>
 * 
 * @brief Construct an @link Align @endlink object from a BamAlignmentRecord
 *        object.
 * 
 * @signature void bamRecordToAlignment(align, reference, record);
 * 
 * @param[out] align The @link Align @endlink object to create the alignment
 *                   object in.
 * @param[in] reference The string with the reference that <tt>record</tt> lies
 *                      on.
 * @param[in] record The @link BamAlignmentRecord @endlink to construct
 *                   alignment from.
 * 
 * The function will resize <tt>align</tt> to have two rows. The part of the
 * reference that the read from <tt>record</tt> aligns to will be copied to the
 * first row and the sequence from record will be copied to the second row (and
 * reverse-complemented if appropriate). Then, the gaps from the CIGAR string in
 * <tt>record</tt> will be copied to <tt>align</tt>.
 * 
 * @section Example
 * 
 * Here is an example:
 * 
 * @code{.cpp}
 * StringSet<Dna5String> references;
 * BamAlignment record;
 * // Read references and record.
 * Align<Dna5String> align;
 * if (record.rID != BamAlignmentRecord::INVALID_REFID)
 *     bamRecordToAlignment(align, references[record.refId], record);
 * @endcode
 */