1 // ***************************************************************************
2 // BamAlignment.h (c) 2009 Derek Barnett
3 // Marth Lab, Department of Biology, Boston College
4 // All rights reserved.
5 // ---------------------------------------------------------------------------
6 // Last modified: 21 March 2011 (DB)
7 // ---------------------------------------------------------------------------
8 // Provides the BamAlignment data structure
9 // ***************************************************************************
11 #ifndef BAMALIGNMENT_H
12 #define BAMALIGNMENT_H
14 #include <api/api_global.h>
15 #include <api/BamAux.h>
21 // forward declaration of BamAlignment's friend classes
23 class BamReaderPrivate;
24 class BamWriterPrivate;
25 } // namespace Internal
27 // BamAlignment data structure
28 struct API_EXPORT BamAlignment {
30 // constructors & destructor
33 BamAlignment(const BamAlignment& other);
36 // queries against alignment flags
38 bool IsDuplicate(void) const; // returns true if this read is a PCR duplicate
39 bool IsFailedQC(void) const; // returns true if this read failed quality control
40 bool IsFirstMate(void) const; // returns true if alignment is first mate on read
41 bool IsMapped(void) const; // returns true if alignment is mapped
42 bool IsMateMapped(void) const; // returns true if alignment's mate is mapped
43 bool IsMateReverseStrand(void) const; // returns true if alignment's mate mapped to reverse strand
44 bool IsPaired(void) const; // returns true if alignment part of paired-end read
45 bool IsPrimaryAlignment(void) const; // returns true if reported position is primary alignment
46 bool IsProperPair(void) const; // returns true if alignment is part of read that satisfied paired-end resolution
47 bool IsReverseStrand(void) const; // returns true if alignment mapped to reverse strand
48 bool IsSecondMate(void) const; // returns true if alignment is second mate on read
50 // manipulate alignment flags
52 void SetIsDuplicate(bool ok); // sets value of "PCR duplicate" flag
53 void SetIsFailedQC(bool ok); // sets value of "failed quality control" flag
54 void SetIsFirstMate(bool ok); // sets value of "alignment is first mate" flag
55 void SetIsMapped(bool ok); // sets value of "alignment is mapped" flag
56 void SetIsMateMapped(bool ok); // sets value of "alignment's mate is mapped" flag
57 void SetIsMateReverseStrand(bool ok); // sets value of "alignment's mate mapped to reverse strand" flag
58 void SetIsPaired(bool ok); // sets value of "alignment part of paired-end read" flag
59 void SetIsPrimaryAlignment(bool ok); // sets value of "position is primary alignment" flag
60 void SetIsProperPair(bool ok); // sets value of "alignment is part of read that satisfied paired-end resolution" flag
61 void SetIsReverseStrand(bool ok); // sets value of "alignment mapped to reverse strand" flag
62 void SetIsSecondMate(bool ok); // sets value of "alignment is second mate on read" flag
64 // legacy methods (consider deprecated, but still available)
65 void SetIsMateUnmapped(bool ok); // complement of using SetIsMateMapped()
66 void SetIsSecondaryAlignment(bool ok); // complement of using SetIsPrimaryAlignment()
67 void SetIsUnmapped(bool ok); // complement of using SetIsMapped()
69 // tag data access methods
72 // -------------------------------------------------------------------------------------
73 // N.B. - The following tag access methods may not be used on BamAlignments fetched
74 // using BamReader::GetNextAlignmentCore(). Attempting to use them will not result in
75 // error message (to keep output clean) but will ALWAYS return false. Only user-created
76 // BamAlignments or those retrieved using BamReader::GetNextAlignment() are valid here.
78 // You can call BuildCharData() on such an alignment retrieved by GetNextAlignmentCore().
79 // This populates all the character data, and will enable subsequent queries on tag data.
80 // -------------------------------------------------------------------------------------
83 bool AddTag(const std::string& tag, const std::string& type, const std::string& value);
84 bool AddTag(const std::string& tag, const std::string& type, const uint32_t& value);
85 bool AddTag(const std::string& tag, const std::string& type, const int32_t& value);
86 bool AddTag(const std::string& tag, const std::string& type, const float& value);
89 bool EditTag(const std::string& tag, const std::string& type, const std::string& value);
90 bool EditTag(const std::string& tag, const std::string& type, const uint32_t& value);
91 bool EditTag(const std::string& tag, const std::string& type, const int32_t& value);
92 bool EditTag(const std::string& tag, const std::string& type, const float& value);
94 // retrieves data for a tag
95 bool GetTag(const std::string& tag, std::string& destination) const;
96 bool GetTag(const std::string& tag, uint32_t& destination) const;
97 bool GetTag(const std::string& tag, int32_t& destination) const;
98 bool GetTag(const std::string& tag, float& destination) const;
100 // retrieves the BAM tag-type character for a tag
101 bool GetTagType(const std::string& tag, char& type) const;
103 // legacy methods (consider deprecated, but still available)
104 bool GetEditDistance(uint32_t& editDistance) const; // retrieves value of "NM" tag
105 bool GetReadGroup(std::string& readGroup) const; // retrieves value of "RG" tag
108 bool RemoveTag(const std::string& tag);
110 // additional methods
112 // populates alignment string fields
113 bool BuildCharData(void);
114 // calculates alignment end position
115 int GetEndPosition(bool usePadded = false, bool zeroBased = true) const;
117 // public data fields
119 std::string Name; // read name
120 int32_t Length; // length of query sequence
121 std::string QueryBases; // 'original' sequence (as reported from sequencing machine)
122 std::string AlignedBases; // 'aligned' sequence (includes any indels, padding, clipping)
123 std::string Qualities; // FASTQ qualities (ASCII characters, not numeric values)
124 std::string TagData; // tag data (use provided methods to query/modify)
125 int32_t RefID; // ID number for reference sequence
126 int32_t Position; // position (0-based) where alignment starts
127 uint16_t Bin; // BAM (standard) index bin number for this alignment
128 uint16_t MapQuality; // mapping quality score
129 uint32_t AlignmentFlag; // alignment bit-flag (use provided methods to query/modify)
130 std::vector<CigarOp> CigarData; // CIGAR operations for this alignment
131 int32_t MateRefID; // ID number for reference sequence where alignment's mate was aligned
132 int32_t MatePosition; // position (0-based) where alignment's mate starts
133 int32_t InsertSize; // mate-pair insert size
134 std::string Filename; // name of BAM file which this alignment comes from
139 struct BamAlignmentSupportData {
142 std::string AllCharData;
143 uint32_t BlockLength;
144 uint32_t NumCigarOperations;
145 uint32_t QueryNameLength;
146 uint32_t QuerySequenceLength;
150 BamAlignmentSupportData(void)
152 , NumCigarOperations(0)
154 , QuerySequenceLength(0)
158 BamAlignmentSupportData SupportData;
159 friend class Internal::BamReaderPrivate;
160 friend class Internal::BamWriterPrivate;
164 typedef std::vector<BamAlignment> BamAlignmentVector;
166 } // namespace BamTools
168 #endif // BAMALIGNMENT_H