# AClass::ANamespace, ANamespace::*Test
EXCLUDE_SYMBOLS = BamTools::Internal \
- BamTools::BamAlignment::BamAlignmentSupportData
+ BamTools::BamAlignment::BamAlignmentSupportData \
+ BamTools::RaiiBuffer \
+ UsesCharData \
+ sort_helper \
+ AlignmentSortBase
# The EXAMPLE_PATH tag can be used to specify one or more files or
# directories that contain example code fragments that are included (see
// Marth Lab, Department of Biology, Boston College
// All rights reserved.
// ---------------------------------------------------------------------------
-// Last modified: 29 September 2011 (DB)
+// Last modified: 10 October 2011 (DB)
// ---------------------------------------------------------------------------
// Provides generic algorithms that are intended to work with BamTools data
// structures. Where possible, these are intended to be STL-compatible.
#include <api/algorithms/Sort.h>
+/*! \namespace BamTools::Algorithms
+ \brief Provides convenient classes & methods for working with BAM data
+*/
#endif // BAM_ALGORITHMS_H
// BamAlignment.cpp (c) 2009 Derek Barnett
// Marth Lab, Department of Biology, Boston College
// ---------------------------------------------------------------------------
-// Last modified: 8 October 2011 (DB)
+// Last modified: 10 October 2011 (DB)
// ---------------------------------------------------------------------------
// Provides the BamAlignment data structure
// ***************************************************************************
*/
BamAlignment::~BamAlignment(void) { }
-///*! \fn bool BamAlignment::AddTag(const std::string& tag, const std::string& type, const std::string& value)
-// \brief Adds a field with string data to the BAM tags.
-
-// Does NOT modify an existing tag - use \link BamAlignment::EditTag() \endlink instead.
-
-// \param[in] tag 2-character tag name
-// \param[in] type 1-character tag type (must be "Z" or "H")
-// \param[in] value string data to store
-// \return \c true if the \b new tag was added successfully
-// \sa \samSpecURL for more details on reserved tag names, supported tag types, etc.
-//*/
-
-
-///*! \fn bool AddTag(const std::string& tag, const std::vector<uint8_t>& values);
-// \brief Adds a numeric array field to the BAM tags.
-
-// Does NOT modify an existing tag - use \link BamAlignment::EditTag() \endlink instead.
-
-// \param tag 2-character tag name
-// \param values vector of uint8_t values to store
-
-// \return \c true if the \b new tag was added successfully
-// \sa \samSpecURL for more details on reserved tag names, supported tag types, etc.
-//*/
-
/*! \fn bool BamAlignment::BuildCharData(void)
\brief Populates alignment string fields (read name, bases, qualities, tag data).
memcpy((char*)(TagData.data()), tagData, tagDataLength);
}
- // clear the core-only flag
+ // clear core-only flag & return success
SupportData.HasCoreOnly = false;
-
- // return success
return true;
}
-///*! \fn bool BamAlignment::EditTag(const std::string& tag, const std::string& type, const std::string& value)
-// \brief Edits a BAM tag field containing string data.
-
-// If \a tag does not exist, a new entry is created.
-
-// \param tag 2-character tag name
-// \param type 1-character tag type (must be "Z" or "H")
-// \param value string data to store
-
-// \return \c true if the tag was modified/created successfully
-
-// \sa BamAlignment::RemoveTag()
-// \sa \samSpecURL for more details on reserved tag names, supported tag types, etc.
-//*/
-
-///*! \fn bool EditTag(const std::string& tag, const std::vector<uint8_t>& values);
-// \brief Edits a BAM tag field containing a numeric array.
-
-// If \a tag does not exist, a new entry is created.
-
-// \param tag 2-character tag name
-// \param value vector of uint8_t values to store
-
-// \return \c true if the tag was modified/created successfully
-// \sa \samSpecURL for more details on reserved tag names, supported tag types, etc.
-//*/
-
-/*! \fn bool BamAlignment::FindTag(const std::string& tag, char*& pTagData, const unsigned int& tagDataLength, unsigned int& numBytesParsed)
+/*! \fn bool BamAlignment::FindTag(const std::string& tag, char*& pTagData, const unsigned int& tagDataLength, unsigned int& numBytesParsed) const
\internal
Searches for requested tag in BAM tag data.
- \param tag requested 2-character tag name
- \param pTagData pointer to current position in BamAlignment::TagData
- \param tagDataLength length of BamAlignment::TagData
- \param numBytesParsed number of bytes parsed so far
+ \param[in] tag requested 2-character tag name
+ \param[in,out] pTagData pointer to current position in BamAlignment::TagData
+ \param[in] tagDataLength length of BamAlignment::TagData
+ \param[in,out] numBytesParsed number of bytes parsed so far
\return \c true if found
return false;
}
-/*! \fn bool BamAlignment::GetEditDistance(uint32_t& editDistance) const
- \brief Retrieves value of edit distance tag ("NM").
-
- \deprecated Instead use BamAlignment::GetTag()
- \code
- BamAlignment::GetTag("NM", editDistance);
- \endcode
-
- \param editDistance destination for retrieved value
-
- \return \c true if found
-*/
-
-// TODO : REMOVE THIS METHOD
-bool BamAlignment::GetEditDistance(uint32_t& editDistance) const {
- return GetTag("NM", (uint32_t&)editDistance);
-}
-
-/*! \fn int BamAlignment::GetEndPosition(bool usePadded = false, bool closedInterval = USE_CLOSED_DEFAULT) const
- \brief Calculates alignment end position, based on starting position and CIGAR data.
+/*! \fn int BamAlignment::GetEndPosition(bool usePadded = false, bool closedInterval = false) const
+ \brief Calculates alignment end position, based on its starting position and CIGAR data.
\warning The position returned now represents a zero-based, HALF-OPEN interval.
In previous versions of BamTools (0.x & 1.x) all intervals were treated
- as zero-based, CLOSED. I whole-heartedly apologize for any inconsistencies this
- may have caused if you assumed that BT was always half-open; full aplogies also
- to those who recognized that BamTools originally used a closed interval, but may
- need to update their code to reflect this new change.
-
- \param usePadded Allow inserted bases to affect the reported position. Default is false, so that
- reported position stays synced with reference coordinates.
+ as zero-based, CLOSED.
- \param closedInterval Setting this to true will return a 0-based end coordinate. Default is false,
- so that his value represents a standard, half-open interval.
+ \param[in] usePadded Allow inserted bases to affect the reported position. Default is
+ false, so that reported position stays synced with reference
+ coordinates.
+ \param[in] closedInterval Setting this to true will return a 0-based end coordinate. Default is
+ false, so that his value represents a standard, half-open interval.
\return alignment end position
*/
alignEnd += op.Length;
break;
- // increase end position when CIGAR char is 'I' only if @usePadded is true
+ // increase end position on insertion, only if @usePadded is true
case Constants::BAM_CIGAR_INS_CHAR :
if ( usePadded )
alignEnd += op.Length;
}
/*! \fn std::string BamAlignment::GetErrorString(void) const
- \brief Returns a description of the last error that occurred
+ \brief Returns a human-readable description of the last error that occurred
- This method allows elimnation of STDERR pollution. Developers of client code
+ This method allows elimination of STDERR pollution. Developers of client code
may choose how the messages are displayed to the user, if at all.
- \return description of last error that occurred
+ \return error description
*/
std::string BamAlignment::GetErrorString(void) const {
return ErrorString;
}
-/*! \fn bool BamAlignment::GetReadGroup(std::string& readGroup) const
- \brief Retrieves value of read group tag ("RG").
-
- \deprecated Instead use BamAlignment::GetTag()
- \code
- BamAlignment::GetTag("RG", readGroup);
- \endcode
-
- \param readGroup destination for retrieved value
-
- \return \c true if found
-*/
-
-// TODO : REMOVE THIS METHOD
-bool BamAlignment::GetReadGroup(std::string& readGroup) const {
- return GetTag("RG", readGroup);
-}
-
-///*! \fn bool BamAlignment::GetTag(const std::string& tag, std::string& destination) const
-// \brief Retrieves the string value associated with a BAM tag.
-
-// \param tag 2-character tag name
-// \param destination destination for retrieved value
-
-// \return \c true if found
-//*/
-
-///*! \fn bool BamAlignment::GetTag(const std::string& tag, std::vector<uint32_t>& destination) const
-// \brief Retrieves the numeric array data associated with a BAM tag
-
-// \param tag 2-character tag name
-// \param destination destination for retrieved data
-
-// \return \c true if found
-//*/
-
/*! \fn bool BamAlignment::GetTagType(const std::string& tag, char& type) const
\brief Retrieves the BAM tag type-code associated with requested tag name.
- \param tag 2-character tag name
- \param type destination for the retrieved (1-character) tag type
+ \param[in] tag 2-character tag name
+ \param[out] type retrieved (1-character) type-code
\return \c true if found
\sa \samSpecURL for more details on reserved tag names, supported tag types, etc.
/*! \fn bool BamAlignment::HasTag(const std::string& tag) const
\brief Returns true if alignment has a record for requested tag.
- \param tag 2-character tag name
+
+ \param[in] tag 2-character tag name
\return \c true if alignment has a record for tag
*/
bool BamAlignment::HasTag(const std::string& tag) const {
return ( (AlignmentFlag & Constants::BAM_ALIGNMENT_READ_2) != 0 );
}
-/*! \fn bool BamAlignment::IsValidSize(const string& tag, const string& type) const
+/*! \fn bool BamAlignment::IsValidSize(const std::string& tag, const std::string& type) const
\internal
Checks that tag name & type strings are expected sizes.
- \a tag should have length
- \a type should have length 1
- \param tag BAM tag name
- \param type BAM tag type-code
-
- \return \c true if both \a tag and \a type are correct sizes
+ \param tag[in] BAM tag name
+ \param type[in] BAM tag type-code
+ \return \c true if both input strings are valid sizes
*/
bool BamAlignment::IsValidSize(const std::string& tag, const std::string& type) const {
return (tag.size() == Constants::BAM_TAG_TAGSIZE) &&
/*! \fn void BamAlignment::RemoveTag(const std::string& tag)
\brief Removes field from BAM tags.
+
+ \param[in] tag 2-character name of field to remove
*/
void BamAlignment::RemoveTag(const std::string& tag) {
\internal
Sets a formatted error string for this alignment.
+
+ \param[in] where class/method where error occurred
+ \param[in] what description of error
*/
void BamAlignment::SetErrorString(const std::string& where, const std::string& what) const {
static const string SEPARATOR = ": ";
else AlignmentFlag |= Constants::BAM_ALIGNMENT_MATE_UNMAPPED;
}
-/*! \fn void BamAlignment::SetIsMateUnmapped(bool ok)
- \brief Complement of using SetIsMateMapped().
- \deprecated For sake of symmetry with the query methods
- \sa IsMateMapped(), SetIsMateMapped()
-*/
-void BamAlignment::SetIsMateUnmapped(bool ok) {
- SetIsMateMapped(!ok);
-}
-
/*! \fn void BamAlignment::SetIsMateReverseStrand(bool ok)
\brief Sets "alignment's mate mapped to reverse strand" flag to \a ok.
*/
else AlignmentFlag &= ~Constants::BAM_ALIGNMENT_REVERSE_STRAND;
}
-/*! \fn void BamAlignment::SetIsSecondaryAlignment(bool ok)
- \brief Complement of using SetIsPrimaryAlignment().
- \deprecated For sake of symmetry with the query methods
- \sa IsPrimaryAlignment(), SetIsPrimaryAlignment()
-*/
-void BamAlignment::SetIsSecondaryAlignment(bool ok) {
- SetIsPrimaryAlignment(!ok);
-}
-
/*! \fn void BamAlignment::SetIsSecondMate(bool ok)
\brief Sets "alignment is second mate on read" flag to \a ok.
*/
else AlignmentFlag &= ~Constants::BAM_ALIGNMENT_READ_2;
}
-/*! \fn void BamAlignment::SetIsUnmapped(bool ok)
- \brief Complement of using SetIsMapped().
- \deprecated For sake of symmetry with the query methods
- \sa IsMapped(), SetIsMapped()
-*/
-void BamAlignment::SetIsUnmapped(bool ok) {
- SetIsMapped(!ok);
-}
-
-/*! \fn bool BamAlignment::SkipToNextTag(const char storageType, char*& pTagData, unsigned int& numBytesParsed)
+/*! \fn bool BamAlignment::SkipToNextTag(const char storageType, char*& pTagData, unsigned int& numBytesParsed) const
\internal
Moves to next available tag in tag data string
- \param storageType BAM tag type-code that determines how far to move cursor
- \param pTagData pointer to current position (cursor) in tag string
- \param numBytesParsed report of how many bytes were parsed (cumulatively)
+ \param[in] storageType BAM tag type-code that determines how far to move cursor
+ \param[in,out] pTagData pointer to current position (cursor) in tag string
+ \param[in,out] numBytesParsed report of how many bytes were parsed (cumulatively)
\return \c if storageType was a recognized BAM tag type
- \post \a pTagData will point to the byte where the next tag data begins.
+
+ \post \a pTagData will point to the byte where the next tag data begins.
\a numBytesParsed will correspond to the cursor's position in the full TagData string.
*/
bool BamAlignment::SkipToNextTag(const char storageType,
// BamAlignment.h (c) 2009 Derek Barnett
// Marth Lab, Department of Biology, Boston College
// ---------------------------------------------------------------------------
-// Last modified: 7 October 2011 (DB)
+// Last modified: 10 October 2011 (DB)
// ---------------------------------------------------------------------------
// Provides the BamAlignment data structure
// ***************************************************************************
namespace BamTools {
-// forward declaration of BamAlignment's friend classes
+//! \cond
+// forward declaration of BamAlignment's "friends"
namespace Internal {
class BamReaderPrivate;
class BamWriterPrivate;
} // namespace Internal
+//! \endcond
// BamAlignment data structure
struct API_EXPORT BamAlignment {
// queries against alignment flags
public:
- bool IsDuplicate(void) const; // returns true if this read is a PCR duplicate
- bool IsFailedQC(void) const; // returns true if this read failed quality control
- bool IsFirstMate(void) const; // returns true if alignment is first mate on read
- bool IsMapped(void) const; // returns true if alignment is mapped
- bool IsMateMapped(void) const; // returns true if alignment's mate is mapped
- bool IsMateReverseStrand(void) const; // returns true if alignment's mate mapped to reverse strand
- bool IsPaired(void) const; // returns true if alignment part of paired-end read
- bool IsPrimaryAlignment(void) const; // returns true if reported position is primary alignment
- bool IsProperPair(void) const; // returns true if alignment is part of read that satisfied paired-end resolution
- bool IsReverseStrand(void) const; // returns true if alignment mapped to reverse strand
- bool IsSecondMate(void) const; // returns true if alignment is second mate on read
+ bool IsDuplicate(void) const; // returns true if this read is a PCR duplicate
+ bool IsFailedQC(void) const; // returns true if this read failed quality control
+ bool IsFirstMate(void) const; // returns true if alignment is first mate on read
+ bool IsMapped(void) const; // returns true if alignment is mapped
+ bool IsMateMapped(void) const; // returns true if alignment's mate is mapped
+ bool IsMateReverseStrand(void) const; // returns true if alignment's mate mapped to reverse strand
+ bool IsPaired(void) const; // returns true if alignment part of paired-end read
+ bool IsPrimaryAlignment(void) const; // returns true if reported position is primary alignment
+ bool IsProperPair(void) const; // returns true if alignment is part of read that satisfied paired-end resolution
+ bool IsReverseStrand(void) const; // returns true if alignment mapped to reverse strand
+ bool IsSecondMate(void) const; // returns true if alignment is second mate on read
// manipulate alignment flags
public:
- void SetIsDuplicate(bool ok); // sets value of "PCR duplicate" flag
- void SetIsFailedQC(bool ok); // sets value of "failed quality control" flag
- void SetIsFirstMate(bool ok); // sets value of "alignment is first mate" flag
- void SetIsMapped(bool ok); // sets value of "alignment is mapped" flag
- void SetIsMateMapped(bool ok); // sets value of "alignment's mate is mapped" flag
- void SetIsMateReverseStrand(bool ok); // sets value of "alignment's mate mapped to reverse strand" flag
- void SetIsPaired(bool ok); // sets value of "alignment part of paired-end read" flag
- void SetIsPrimaryAlignment(bool ok); // sets value of "position is primary alignment" flag
- void SetIsProperPair(bool ok); // sets value of "alignment is part of read that satisfied paired-end resolution" flag
- void SetIsReverseStrand(bool ok); // sets value of "alignment mapped to reverse strand" flag
- void SetIsSecondMate(bool ok); // sets value of "alignment is second mate on read" flag
-
- // legacy methods (consider deprecated, but still available)
- void SetIsMateUnmapped(bool ok); // complement of using SetIsMateMapped()
- void SetIsSecondaryAlignment(bool ok); // complement of using SetIsPrimaryAlignment()
- void SetIsUnmapped(bool ok); // complement of using SetIsMapped()
+ void SetIsDuplicate(bool ok); // sets value of "PCR duplicate" flag
+ void SetIsFailedQC(bool ok); // sets value of "failed quality control" flag
+ void SetIsFirstMate(bool ok); // sets value of "alignment is first mate" flag
+ void SetIsMapped(bool ok); // sets value of "alignment is mapped" flag
+ void SetIsMateMapped(bool ok); // sets value of "alignment's mate is mapped" flag
+ void SetIsMateReverseStrand(bool ok); // sets value of "alignment's mate mapped to reverse strand" flag
+ void SetIsPaired(bool ok); // sets value of "alignment part of paired-end read" flag
+ void SetIsPrimaryAlignment(bool ok); // sets value of "position is primary alignment" flag
+ void SetIsProperPair(bool ok); // sets value of "alignment is part of read that satisfied paired-end resolution" flag
+ void SetIsReverseStrand(bool ok); // sets value of "alignment mapped to reverse strand" flag
+ void SetIsSecondMate(bool ok); // sets value of "alignment is second mate on read" flag
// tag data access methods
public:
template<typename T> bool GetTag(const std::string& tag, T& destination) const;
template<typename T> bool GetTag(const std::string& tag, std::vector<T>& destination) const;
- // retrieves the BAM type-code for requested tag
- // (returns whether or not tag exists, and type-code is valid)
+ // retrieves the SAM/BAM type-code for requested tag name
bool GetTagType(const std::string& tag, char& type) const;
- // legacy methods (consider deprecated, but still available)
- bool GetEditDistance(uint32_t& editDistance) const; // retrieves value of "NM" tag
- bool GetReadGroup(std::string& readGroup) const; // retrieves value of "RG" tag
-
// returns true if alignment has a record for this tag name
bool HasTag(const std::string& tag) const;
int32_t InsertSize; // mate-pair insert size
std::string Filename; // name of BAM file which this alignment comes from
- //! \cond
+ //! \internal
// internal utility methods
private:
bool FindTag(const std::string& tag,
char*& pTagData,
const unsigned int& tagDataLength,
unsigned int& numBytesParsed) const;
- bool IsValidSize(const std::string& tag,
- const std::string& type) const;
- void SetErrorString(const std::string& where,
- const std::string& what) const;
+ bool IsValidSize(const std::string& tag, const std::string& type) const;
+ void SetErrorString(const std::string& where, const std::string& what) const;
bool SkipToNextTag(const char storageType,
char*& pTagData,
unsigned int& numBytesParsed) const;
friend class Internal::BamWriterPrivate;
mutable std::string ErrorString; // mutable to allow updates even in logically const methods
- //! \endcond
+ //! \endinternal
};
// ---------------------------------------------------------
// BamAlignment tag access methods
+/*! \fn bool AddTag(const std::string& tag, const std::string& type, const T& value)
+ \brief Adds a field to the BAM tags.
+
+ Does NOT modify an existing tag - use \link BamAlignment::EditTag() \endlink instead.
+
+ \param[in] tag 2-character tag name
+ \param[in] type 1-character tag type
+ \param[in] value data to store
+ \return \c true if the \b new tag was added successfully
+ \sa \samSpecURL for more details on reserved tag names, supported tag types, etc.
+*/
template<typename T>
-inline bool BamAlignment::AddTag(const std::string& tag,
- const std::string& type,
- const T& value)
-{
+inline bool BamAlignment::AddTag(const std::string& tag, const std::string& type, const T& value) {
+
// if char data not populated, do that first
if ( SupportData.HasCoreOnly )
BuildCharData();
return true;
}
+/*! \fn template<typename T> bool AddTag(const std::string& tag, const std::vector<T>& values)
+ \brief Adds a numeric array field to the BAM tags.
+
+ Does NOT modify an existing tag - use \link BamAlignment::EditTag() \endlink instead.
+
+ \param[in] tag 2-character tag name
+ \param[in] values vector of data values to store
+ \return \c true if the \b new tag was added successfully
+ \sa \samSpecURL for more details on reserved tag names, supported tag types, etc.
+*/
template<typename T>
-inline bool BamAlignment::AddTag(const std::string& tag,
- const std::vector<T>& values)
-{
+inline bool BamAlignment::AddTag(const std::string& tag, const std::vector<T>& values) {
+
// if char data not populated, do that first
if ( SupportData.HasCoreOnly )
BuildCharData();
return true;
}
+/*! \fn template<typename T> bool EditTag(const std::string& tag, const std::string& type, const T& value)
+ \brief Edits a BAM tag field.
+
+ If \a tag does not exist, a new entry is created.
+
+ \param tag[in] 2-character tag name
+ \param type[in] 1-character tag type (must be "Z" or "H")
+ \param value[in] new data value
+
+ \return \c true if the tag was modified/created successfully
+
+ \sa BamAlignment::RemoveTag()
+ \sa \samSpecURL for more details on reserved tag names, supported tag types, etc.
+*/
template<typename T>
-inline bool BamAlignment::EditTag(const std::string& tag,
- const std::string& type,
- const T& value)
-{
+inline bool BamAlignment::EditTag(const std::string& tag, const std::string& type, const T& value) {
+
// if char data not populated, do that first
if ( SupportData.HasCoreOnly )
BuildCharData();
return AddTag(tag, type, value);
}
+/*! \fn template<typename T> bool EditTag(const std::string& tag, const std::vector<T>& values)
+ \brief Edits a BAM tag field containing a numeric array.
+
+ If \a tag does not exist, a new entry is created.
+
+ \param tag[in] 2-character tag name
+ \param value[in] vector of data values
+
+ \return \c true if the tag was modified/created successfully
+ \sa \samSpecURL for more details on reserved tag names, supported tag types, etc.
+*/
template<typename T>
-inline bool BamAlignment::EditTag(const std::string& tag,
- const std::vector<T>& values)
-{
+inline bool BamAlignment::EditTag(const std::string& tag, const std::vector<T>& values) {
+
// if char data not populated, do that first
if ( SupportData.HasCoreOnly )
BuildCharData();
return AddTag(tag, values);
}
+
+/*! \fn template<typename T> bool GetTag(const std::string& tag, T& destination) const
+ \brief Retrieves the value associated with a BAM tag.
+
+ \param tag[in] 2-character tag name
+ \param destination[out] retrieved value
+ \return \c true if found
+*/
template<typename T>
-inline bool BamAlignment::GetTag(const std::string& tag,
- T& destination) const
-{
+inline bool BamAlignment::GetTag(const std::string& tag, T& destination) const {
+
// skip if alignment is core-only
if ( SupportData.HasCoreOnly ) {
// TODO: set error string?
return true;
}
-// retrieves "binary-array" tag data
+/*! \fn template<typename T> bool GetTag(const std::string& tag, std::vector<T>& destination) const
+ \brief Retrieves the numeric array associated with a BAM tag.
+
+ \param tag[in] 2-character tag name
+ \param destination[out] retrieved values
+ \return \c true if found
+*/
template<typename T>
-inline bool BamAlignment::GetTag(const std::string& tag,
- std::vector<T>& destination) const
-{
+inline bool BamAlignment::GetTag(const std::string& tag, std::vector<T>& destination) const {
+
// skip if alignment is core-only
if ( SupportData.HasCoreOnly ) {
// TODO: set error string?
// BamAux.h (c) 2009 Derek Barnett, Michael Str�mberg\r
// Marth Lab, Department of Biology, Boston College\r
// ---------------------------------------------------------------------------\r
-// Last modified: 8 October 2011 (DB)\r
+// Last modified: 10 October 2011 (DB)\r
// ---------------------------------------------------------------------------\r
// Provides data structures & utility methods that are used throughout the API.\r
// ***************************************************************************\r
\r
Provides data structures & utility methods that are used throughout the API.\r
*/\r
+\r
/*! \namespace BamTools\r
\brief Contains all BamTools classes & methods.\r
\r
/*! \struct BamTools::CigarOp\r
\brief Represents a CIGAR alignment operation.\r
\r
- \sa http://samtools.sourceforge.net/SAM-1.3.pdf for more details on using CIGAR operations.\r
+ \sa \samSpecURL for more details on using CIGAR operations.\r
*/\r
struct API_EXPORT CigarOp {\r
\r
- char Type; //!< CIGAR operation type (MIDNSHP)\r
+ char Type; //!< CIGAR operation type (MIDNSHPX=)\r
uint32_t Length; //!< CIGAR operation length (number of bases)\r
\r
//! constructor\r
\r
\warning BamRegion now represents a zero-based, HALF-OPEN interval.\r
In previous versions of BamTools (0.x & 1.x) all intervals were treated\r
- as zero-based, CLOSED. I whole-heartedly apologize for any inconsistencies this\r
- may have caused if you assumed that BT was always half-open; full aplogies also\r
- to those who recognized that BamTools originally used a closed interval, but may\r
- need to update their code to reflect this new change.\r
+ as zero-based, CLOSED.\r
*/\r
struct API_EXPORT BamRegion {\r
\r
// General utility methods\r
\r
/*! \fn bool FileExists(const std::string& filename)\r
- \brief checks if file exists\r
-\r
- Attempts to open file in a read-only mode.\r
-\r
- \return \c true if file can be opened successfully\r
+ \brief returns true if the file exists\r
*/\r
API_EXPORT inline bool FileExists(const std::string& filename) {\r
std::ifstream f(filename.c_str(), std::ifstream::in);\r
\r
/*! \fn void SwapEndian_16(int16_t& x)\r
\brief swaps endianness of signed 16-bit integer, in place\r
-\r
- Swaps endian representation of value in \a x.\r
*/\r
API_EXPORT inline void SwapEndian_16(int16_t& x) {\r
x = ((x >> 8) | (x << 8));\r
\r
/*! \fn void SwapEndian_16(uint16_t& x)\r
\brief swaps endianness of unsigned 16-bit integer, in place\r
-\r
- Swaps endian representation of value in \a x.\r
*/\r
API_EXPORT inline void SwapEndian_16(uint16_t& x) {\r
x = ((x >> 8) | (x << 8));\r
\r
/*! \fn void SwapEndian_32(int32_t& x)\r
\brief swaps endianness of signed 32-bit integer, in place\r
-\r
- Swaps endian representation of value in \a x.\r
*/\r
API_EXPORT inline void SwapEndian_32(int32_t& x) {\r
x = ( (x >> 24) | \r
\r
/*! \fn void SwapEndian_32(uint32_t& x)\r
\brief swaps endianness of unsigned 32-bit integer, in place\r
-\r
- Swaps endian representation of value in \a x.\r
*/\r
API_EXPORT inline void SwapEndian_32(uint32_t& x) {\r
x = ( (x >> 24) | \r
\r
/*! \fn void SwapEndian_64(int64_t& x)\r
\brief swaps endianness of signed 64-bit integer, in place\r
-\r
- Swaps endian representation of value in \a x.\r
*/\r
API_EXPORT inline void SwapEndian_64(int64_t& x) {\r
x = ( (x >> 56) | \r
\r
/*! \fn void SwapEndian_64(uint64_t& x)\r
\brief swaps endianness of unsigned 64-bit integer, in place\r
-\r
- Swaps endian representation of value in \a x.\r
*/\r
API_EXPORT inline void SwapEndian_64(uint64_t& x) {\r
x = ( (x >> 56) | \r
\r
/*! \fn void SwapEndian_16p(char* data)\r
\brief swaps endianness of the next 2 bytes in a buffer, in place\r
-\r
- Swaps endian representation the next 2 bytes in \a data.\r
*/\r
API_EXPORT inline void SwapEndian_16p(char* data) {\r
uint16_t& value = (uint16_t&)*data; \r
\r
/*! \fn void SwapEndian_32p(char* data)\r
\brief swaps endianness of the next 4 bytes in a buffer, in place\r
-\r
- Swaps endian representation the next 4 bytes in \a data.\r
*/\r
API_EXPORT inline void SwapEndian_32p(char* data) {\r
uint32_t& value = (uint32_t&)*data; \r
\r
/*! \fn void SwapEndian_64p(char* data)\r
\brief swaps endianness of the next 8 bytes in a buffer, in place\r
-\r
- Swaps endian representation the next 8 bytes in \a data.\r
*/\r
API_EXPORT inline void SwapEndian_64p(char* data) {\r
uint64_t& value = (uint64_t&)*data; \r
/*! \fn void PackUnsignedInt(char* buffer, unsigned int value)\r
\brief stores unsigned integer value in a byte buffer\r
\r
- \param buffer destination buffer\r
- \param value unsigned integer to 'pack' in buffer\r
+ \param[out] buffer destination buffer\r
+ \param[in] value value to 'pack' in buffer\r
*/\r
API_EXPORT inline void PackUnsignedInt(char* buffer, unsigned int value) {\r
buffer[0] = (char)value;\r
/*! \fn void PackUnsignedShort(char* buffer, unsigned short value)\r
\brief stores unsigned short integer value in a byte buffer\r
\r
- \param buffer destination buffer\r
- \param value unsigned short integer to 'pack' in buffer\r
+ \param[out] buffer destination buffer\r
+ \param[in] value value to 'pack' in buffer\r
*/\r
API_EXPORT inline void PackUnsignedShort(char* buffer, unsigned short value) {\r
buffer[0] = (char)value;\r
/*! \fn double UnpackDouble(const char* buffer)\r
\brief reads a double value from byte buffer\r
\r
- \param buffer source byte buffer\r
+ \param[in] buffer source byte buffer\r
\return the (double) value read from the buffer\r
*/\r
API_EXPORT inline double UnpackDouble(const char* buffer) {\r
\r
This is an overloaded function.\r
\r
- \param buffer source byte buffer\r
+ \param[in] buffer source byte buffer\r
\return the (double) value read from the buffer\r
*/\r
API_EXPORT inline double UnpackDouble(char* buffer) {\r
/*! \fn double UnpackFloat(const char* buffer)\r
\brief reads a float value from byte buffer\r
\r
- \param buffer source byte buffer\r
+ \param[in] buffer source byte buffer\r
\return the (float) value read from the buffer\r
*/\r
API_EXPORT inline float UnpackFloat(const char* buffer) {\r
\r
This is an overloaded function.\r
\r
- \param buffer source byte buffer\r
+ \param[in] buffer source byte buffer\r
\return the (float) value read from the buffer\r
*/\r
API_EXPORT inline float UnpackFloat(char* buffer) {\r
/*! \fn signed int UnpackSignedInt(const char* buffer)\r
\brief reads a signed integer value from byte buffer\r
\r
- \param buffer source byte buffer\r
+ \param[in] buffer source byte buffer\r
\return the (signed int) value read from the buffer\r
*/\r
API_EXPORT inline signed int UnpackSignedInt(const char* buffer) {\r
\r
This is an overloaded function.\r
\r
- \param buffer source byte buffer\r
+ \param[in] buffer source byte buffer\r
\return the (signed int) value read from the buffer\r
*/\r
API_EXPORT inline signed int UnpackSignedInt(char* buffer) {\r
/*! \fn signed short UnpackSignedShort(const char* buffer)\r
\brief reads a signed short integer value from byte buffer\r
\r
- \param buffer source byte buffer\r
+ \param[in] buffer source byte buffer\r
\return the (signed short) value read from the buffer\r
*/\r
API_EXPORT inline signed short UnpackSignedShort(const char* buffer) {\r
\r
This is an overloaded function.\r
\r
- \param buffer source byte buffer\r
+ \param[in] buffer source byte buffer\r
\return the (signed short) value read from the buffer\r
*/\r
API_EXPORT inline signed short UnpackSignedShort(char* buffer) {\r
/*! \fn unsigned int UnpackUnsignedInt(const char* buffer)\r
\brief reads an unsigned integer value from byte buffer\r
\r
- \param buffer source byte buffer\r
+ \param[in] buffer source byte buffer\r
\return the (unsigned int) value read from the buffer\r
*/\r
API_EXPORT inline unsigned int UnpackUnsignedInt(const char* buffer) {\r
\r
This is an overloaded function.\r
\r
- \param buffer source byte buffer\r
+ \param[in] buffer source byte buffer\r
\return the (unsigned int) value read from the buffer\r
*/\r
API_EXPORT inline unsigned int UnpackUnsignedInt(char* buffer) {\r
/*! \fn unsigned short UnpackUnsignedShort(const char* buffer)\r
\brief reads an unsigned short integer value from byte buffer\r
\r
- \param buffer source byte buffer\r
+ \param[in] buffer source byte buffer\r
\return the (unsigned short) value read from the buffer\r
*/\r
API_EXPORT inline unsigned short UnpackUnsignedShort(const char* buffer) {\r
\r
This is an overloaded function.\r
\r
- \param buffer source byte buffer\r
+ \param[in] buffer source byte buffer\r
\return the (unsigned short) value read from the buffer\r
*/\r
API_EXPORT inline unsigned short UnpackUnsignedShort(char* buffer) {\r
// ----------------------------------------------------------------\r
// 'internal' helper structs\r
\r
+/*! \struct RaiiBuffer\r
+ \internal\r
+*/\r
struct RaiiBuffer {\r
- RaiiBuffer(const unsigned int n)\r
+ RaiiBuffer(const size_t n)\r
: Buffer( new char[n]() )\r
{ }\r
~RaiiBuffer(void) {\r
// BamConstants.h (c) 2011 Derek Barnett
// Marth Lab, Department of Biology, Boston College
// ---------------------------------------------------------------------------
-// Last modified: 7 October 2011 (DB)
+// Last modified: 10 October 2011 (DB)
// ---------------------------------------------------------------------------
// Provides basic constants for handling BAM files.
// ***************************************************************************
const int BAM_CIGAR_SHIFT = 4;
const int BAM_CIGAR_MASK = ((1 << BAM_CIGAR_SHIFT) - 1);
-// BAM tag types
+// BAM tag types & sizes
const char BAM_TAG_TYPE_ASCII = 'A';
const char BAM_TAG_TYPE_UINT8 = 'c';
const char BAM_TAG_TYPE_INT8 = 'C';
const char BAM_DNA_DEL = '-';
const char BAM_DNA_PAD = '*';
-// zlib constants
+// zlib & BGZF constants
const char GZIP_ID1 = 31;
const char GZIP_ID2 = 139;
const char CM_DEFLATE = 8;
const char BGZF_ID1 = 66;
const char BGZF_ID2 = 67;
const char BGZF_LEN = 2;
-const int8_t GZIP_WINDOW_BITS = -15;
-const int8_t Z_DEFAULT_MEM_LEVEL = 8;
-// BZGF constants
+const int8_t GZIP_WINDOW_BITS = -15;
+const int8_t Z_DEFAULT_MEM_LEVEL = 8;
const uint8_t BGZF_BLOCK_HEADER_LENGTH = 18;
const uint8_t BGZF_BLOCK_FOOTER_LENGTH = 8;
const uint32_t BGZF_MAX_BLOCK_SIZE = 65536;
} // namespace Constants
+//! \cond
// -------------------------
// tag-type helper structs
// -------------------------
static char TypeCode(void) { return Constants::BAM_TAG_TYPE_STRING; }
};
+//! \endcond
+
} // namespace BamTools
#endif // BAM_CONSTANTS_H
// BamIndex.h (c) 2009 Derek Barnett
// Marth Lab, Department of Biology, Boston College
// ---------------------------------------------------------------------------
-// Last modified: 6 October 2011 (DB)
+// Last modified: 9 October 2011 (DB)
// ---------------------------------------------------------------------------
// Provides basic BAM index interface
// ***************************************************************************
It is exposed to the public API to allow advanced users to implement
their own custom indexing schemes.
-
- More documentation on methods & enums coming soon.
*/
class API_EXPORT BamIndex {
// change the index caching behavior
virtual void SetCacheMode(const BamIndex::IndexCacheMode& mode) =0;
+ //! \cond
+
// internal methods
protected:
void SetErrorString(const std::string& where, const std::string& what) const {
protected:
Internal::BamReaderPrivate* m_reader; // copy, not owned
mutable std::string m_errorString;
+
+ //! \endcond
};
} // namespace BamTools
// BamMultiReader.cpp (c) 2010 Erik Garrison, Derek Barnett
// Marth Lab, Department of Biology, Boston College
// ---------------------------------------------------------------------------
-// Last modified: 8 October 2011 (DB)
+// Last modified: 10 October 2011 (DB)
// ---------------------------------------------------------------------------
// Convenience class for reading multiple BAM files.
//
#include <vector>
using namespace std;
-/*! \class BamTools::BamReader
+/*! \class BamTools::BamMultiReader
\brief Convenience class for reading multiple BAM files.
*/
Leaves any other file(s) open, along with header and reference data.
+ \param[in] filename name of specific BAM file to close
+
\sa Close(), IsOpen(), Open(), BamReader::Close()
*/
bool BamMultiReader::CloseFile(const std::string& filename) {
/*! \fn bool BamMultiReader::CreateIndexes(const BamIndex::IndexType& type)
\brief Creates index files for the current BAM files.
- \param type file format to create, see BamIndex::IndexType for available formats
+ \param[in] type file format to create, see BamIndex::IndexType for available formats
\return \c true if index files created OK
\sa LocateIndexes(), OpenIndexes(), BamReader::CreateIndex()
*/
return d->Filenames();
}
-// returns a description of the last error that occurred
+/*! \fn std::string BamMultiReader::GetErrorString(void) const
+ \brief Returns a human-readable description of the last error that occurred
+
+ This method allows elimination of STDERR pollution. Developers of client code
+ may choose how the messages are displayed to the user, if at all.
+
+ \return error description
+*/
std::string BamMultiReader::GetErrorString(void) const {
return d->GetErrorString();
}
/*! \fn SamHeader BamMultiReader::GetHeader(void) const
\brief Returns unified SAM-format header for all files
- N.B. - Modifying the retrieved text does NOT affect the current
- BAM files. Thesse file have been opened in a read-only mode. However,
+ \note Modifying the retrieved text does NOT affect the current
+ BAM files. These files have been opened in a read-only mode. However,
your modified header text can be used in conjunction with BamWriter
to generate a new BAM file with the appropriate header information.
/*! \fn std::string BamMultiReader::GetHeaderText(void) const
\brief Returns unified SAM-format header text for all files
- N.B. - Modifying the retrieved text does NOT affect the current
- BAM files. Thesse file have been opened in a read-only mode. However,
+ \note Modifying the retrieved text does NOT affect the current
+ BAM files. These files have been opened in a read-only mode. However,
your modified header text can be used in conjunction with BamWriter
to generate a new BAM file with the appropriate header information.
overlapping alignment and what data gets populated.
This method takes care of determining which alignment actually is 'next'
- across multiple files, depending on current SortOrder.
+ across multiple files, depending on their sort order.
- \param alignment destination for alignment record data
+ \param[out] alignment destination for alignment record data
\returns \c true if a valid alignment was found
- \sa GetNextAlignmentCore(), SetRegion(), SetSortOrder(), BamReader::GetNextAlignment()
+ \sa GetNextAlignmentCore(), SetRegion(), BamReader::GetNextAlignment()
*/
bool BamMultiReader::GetNextAlignment(BamAlignment& nextAlignment) {
return d->GetNextAlignment(nextAlignment);
overlapping alignment and what data gets populated.
This method takes care of determining which alignment actually is 'next'
- across multiple files, depending on current SortOrder.
+ across multiple files, depending on their sort order.
- \param alignment destination for alignment record data
+ \param[out] alignment destination for alignment record data
\returns \c true if a valid alignment was found
- \sa GetNextAlignment(), SetRegion(), SetSortOrder(), BamReader::GetNextAlignmentCore()
+ \sa GetNextAlignment(), SetRegion(), BamReader::GetNextAlignmentCore()
*/
bool BamMultiReader::GetNextAlignmentCore(BamAlignment& nextAlignment) {
return d->GetNextAlignmentCore(nextAlignment);
If \a refName is not found, returns -1.
+ \param[in] refName name of reference to look up
\sa BamReader::GetReferenceID()
*/
int BamMultiReader::GetReferenceID(const std::string& refName) const {
This is a convenience method, equivalent to calling SetRegion()
with only a left boundary specified.
+ \param[in] refID ID of reference to jump to
+ \param[in] position (0-based) left boundary
+
\returns \c true if jump was successful
\sa HasIndex(), BamReader::Jump()
*/
An example case would look this:
\code
-
BamMultiReader reader;
- // do setup
+
+ // do setup...
// ensure that all files have an index
if ( !reader.LocateIndexes() ) // opens any existing index files that match our BAM files
- reader.CreateIndexes(); // creates index files for BAM files that still lack one
+ reader.CreateIndexes(); // creates index files for any BAM files that still lack one
- // do interesting stuff
- // ...
+ // do interesting stuff using random-access...
\endcode
with the desired index filenames. If that function returns false, you can use
CreateIndexes() to then build index files of the exact requested format.
- \param preferredType desired index file format, see BamIndex::IndexType for available formats
+ \param[in] preferredType desired index file format, see BamIndex::IndexType for available formats
\returns \c true if index files could be found for \b ALL open BAM files
\sa BamReader::LocateIndex()
*/
/*! \fn bool BamMultiReader::Open(const std::vector<std::string>& filenames)
\brief Opens BAM files.
- N.B. - Opening BAM files will invalidate any current region set on the multireader.
- All file pointers will be returned to the beginning of the alignment data.
- Follow this with Jump() or SetRegion() to establish a region of interest.
+ \note Opening BAM files will invalidate any current region set on the multireader.
+ All file pointers will be returned to the beginning of the alignment data. Follow
+ this with Jump() or SetRegion() to establish a region of interest.
- \param filenames list of BAM filenames to open
+ \param[in] filenames list of BAM filenames to open
\returns \c true if BAM files were opened successfully
\sa Close(), HasOpenReaders(), OpenFile(), OpenIndexes(), BamReader::Open()
*/
Adds another BAM file to multireader "on-the-fly".
- N.B. - Opening a BAM file invalidates any current region set on the multireader.
- All file pointers will be returned to the beginning of the alignment data.
- Follow this with Jump() or SetRegion() to establish a region of interest.
+ \note Opening a BAM file will invalidate any current region set on the multireader.
+ All file pointers will be returned to the beginning of the alignment data. Follow
+ this with Jump() or SetRegion() to establish a region of interest.
- \param filename BAM filename to open
+ \param[in] filename BAM filename to open
\returns \c true if BAM file was opened successfully
\sa Close(), HasOpenReaders(), Open(), OpenIndexes(), BamReader::Open()
*/
/*! \fn bool BamMultiReader::OpenIndexes(const std::vector<std::string>& indexFilenames)
\brief Opens index files for current BAM files.
- N.B. - Currently assumes that index filenames match the order (and number) of
+ \note Currently assumes that index filenames match the order (and number) of
BAM files passed to Open().
- \param indexFilenames list of BAM index file names
+ \param[in] indexFilenames list of BAM index file names
\returns \c true if BAM index file was opened & data loaded successfully
\sa LocateIndex(), Open(), SetIndex(), BamReader::OpenIndex()
*/
Default mode is BamIndex::LimitedIndexCaching.
- \param mode desired cache mode for index, see BamIndex::IndexCacheMode for
- description of the available cache modes
+ \param[in] mode desired cache mode for index, see BamIndex::IndexCacheMode for
+ description of the available cache modes
\sa HasIndex(), BamReader::SetIndexCacheMode()
*/
void BamMultiReader::SetIndexCacheMode(const BamIndex::IndexCacheMode& mode) {
Equivalent to calling BamReader::SetRegion() on all open BAM files.
- \param region desired region-of-interest to activate
+ \warning BamRegion now represents a zero-based, HALF-OPEN interval.
+ In previous versions of BamTools (0.x & 1.x) all intervals were treated
+ as zero-based, CLOSED.
+
+ \param[in] region desired region-of-interest to activate
\returns \c true if ALL readers set the region successfully
\sa HasIndexes(), Jump(), BamReader::SetRegion()
*/
const int& rightPosition)
\brief Sets a target region of interest
- This is an overloaded function.
+ This is an overloaded function. Equivalent to calling BamReader::SetRegion() on all open BAM files.
- Equivalent to calling BamReader::SetRegion() on all open BAM files.
+ \warning This function now expects a zero-based, HALF-OPEN interval.
+ In previous versions of BamTools (0.x & 1.x) all intervals were treated
+ as zero-based, CLOSED.
- \param leftRefID referenceID of region's left boundary
- \param leftPosition position of region's left boundary
- \param rightRefID reference ID of region's right boundary
- \param rightPosition position of region's right boundary
+ \param[in] leftRefID referenceID of region's left boundary
+ \param[in] leftPosition position of region's left boundary
+ \param[in] rightRefID reference ID of region's right boundary
+ \param[in] rightPosition position of region's right boundary
\returns \c true if ALL readers set the region successfully
\sa HasIndexes(), Jump(), BamReader::SetRegion()
// BamReader.cpp (c) 2009 Derek Barnett, Michael Str�mberg
// Marth Lab, Department of Biology, Boston College
// ---------------------------------------------------------------------------
-// Last modified: 7 October 2011 (DB)
+// Last modified: 10 October 2011 (DB)
// ---------------------------------------------------------------------------
// Provides read access to BAM files.
// ***************************************************************************
/*! \fn bool BamReader::CreateIndex(const BamIndex::IndexType& type)
\brief Creates an index file for current BAM file.
- \param type file format to create, see BamIndex::IndexType for available formats
+ \param[in] type file format to create, see BamIndex::IndexType for available formats
\return \c true if index created OK
\sa LocateIndex(), OpenIndex()
*/
return d->CreateIndex(type);
}
+/*! \fn std::string BamReader::GetErrorString(void) const
+ \brief Returns a human-readable description of the last error that occurred
+
+ This method allows elimination of STDERR pollution. Developers of client code
+ may choose how the messages are displayed to the user, if at all.
+
+ \return error description
+*/
string BamReader::GetErrorString(void) const {
return d->GetErrorString();
}
Header data is wrapped in a SamHeader object that can be conveniently queried & modified.
- N.B. - Modifying the retrieved SamHeader object does NOT affect the
+ \note Modifying the retrieved SamHeader object does NOT affect the
current BAM file. This file has been opened in a read-only mode.
However, your modified SamHeader object can be used in conjunction with
BamWriter to generate a new BAM file with the appropriate header information.
/*! \fn std::string BamReader::GetHeaderText(void) const
\brief Returns SAM header data, as SAM-formatted text.
- N.B. - Modifying the retrieved text does NOT affect the current
+ \note Modifying the retrieved text does NOT affect the current
BAM file. This file has been opened in a read-only mode. However,
your modified header text can be used in conjunction with BamWriter
to generate a new BAM file with the appropriate header information.
are required, consider using GetNextAlignmentCore() for a significant
performance boost.
- \param alignment destination for alignment record data
+ \param[out] alignment destination for alignment record data
\returns \c true if a valid alignment was found
*/
bool BamReader::GetNextAlignment(BamAlignment& alignment) {
when these fields are not required for every alignment. These fields can be
populated 'lazily' (as needed) by calling BamAlignment::BuildCharData() later.
- \param alignment destination for alignment record data
+ \param[out] alignment destination for alignment record data
\returns \c true if a valid alignment was found
\sa SetRegion()
*/
\brief Returns the ID of the reference with this name.
If \a refName is not found, returns -1.
+
+ \param[in] refName name of reference to look up
*/
int BamReader::GetReferenceID(const std::string& refName) const {
return d->GetReferenceID(refName);
return d->HasIndex();
}
-/*! \fn bool BamReader::IsIndexLoaded(void) const
- \brief Returns \c true if index data is available.
-
- \deprecated Instead use HasIndex()
- \cond
- Deprecated purely for API semantic clarity - HasIndex() should be clearer
- than IsIndexLoaded() in light of the new caching modes that may clear the
- index data from memory, but leave the index file open for later random access
- seeks.
-
- For example, what would (IsIndexLoaded() == true) mean when cacheMode has been
- explicitly set to NoIndexCaching? This is confusing at best, misleading about
- current memory behavior at worst.
- \endcond
-*/
-bool BamReader::IsIndexLoaded(void) const {
- return d->HasIndex();
-}
-
/*! \fn bool BamReader::IsOpen(void) const
\brief Returns \c true if a BAM file is open for reading.
*/
This is a convenience method, equivalent to calling SetRegion()
with only a left boundary specified.
+ \param[in] refID left-bound reference ID
+ \param[in] position left-bound position
+
\returns \c true if jump was successful
\sa HasIndex()
*/
with the desired index filename. If that function returns false, you can use
CreateIndex() to then build an index of the exact requested format.
- \param preferredType desired index file format, see BamIndex::IndexType for available formats
+ \param[in] preferredType desired index file format, see BamIndex::IndexType for available formats
+
\returns \c true if (any) index file could be found
*/
bool BamReader::LocateIndex(const BamIndex::IndexType& preferredType) {
If BamReader is already opened on another file, this function closes
that file, then attempts to open requested \a filename.
- \param filename name of BAM file to open
+ \param[in] filename name of BAM file to open
+
\returns \c true if BAM file was opened successfully
\sa Close(), IsOpen(), OpenIndex()
*/
/*! \fn bool BamReader::OpenIndex(const std::string& indexFilename)
\brief Opens a BAM index file.
- \param indexFilename name of BAM index file
+ \param[in] indexFilename name of BAM index file to open
\returns \c true if BAM index file was opened & data loaded successfully
\sa LocateIndex(), Open(), SetIndex()
Useful for performing multiple sequential passes through a BAM file.
Calling this function clears any prior region that may have been set.
- N.B. - Note that this function sets the file pointer to first alignment record
+ \note This function sets the file pointer to first alignment record
in the BAM file, NOT the beginning of the file.
\returns \c true if rewind operation was successful
reader.SetIndex(new MyCustomBamIndex);
\endcode
- N.B. - BamReader takes ownership of \a index - i.e. BamReader will
- take care of deleting the pointer when the reader is destructed,
- when the current BAM file is closed, or when a new index is requested.
+ \note BamReader takes ownership of \a index - i.e. the BamReader will
+ take care of deleting it when the reader is destructed, when the current
+ BAM file is closed, or when a new index is requested.
- \param index custom BamIndex subclass created by client
+ \param[in] index custom BamIndex subclass created by client
\sa CreateIndex(), LocateIndex(), OpenIndex()
*/
void BamReader::SetIndex(BamIndex* index) {
Default mode is BamIndex::LimitedIndexCaching.
- \param mode desired cache mode for index, see BamIndex::IndexCacheMode for
- description of the available cache modes
+ \param[in] mode desired cache mode for index, see BamIndex::IndexCacheMode for
+ description of the available cache modes
\sa HasIndex()
*/
void BamReader::SetIndexCacheMode(const BamIndex::IndexCacheMode& mode) {
that all alignments that lie downstream of the left boundary are
considered valid, continuing to the end of the BAM file.
- \param region desired region-of-interest to activate
+ \warning BamRegion now represents a zero-based, HALF-OPEN interval.
+ In previous versions of BamTools (0.x & 1.x) all intervals were treated
+ as zero-based, CLOSED.
+
+ \param[in] region desired region-of-interest to activate
+
\returns \c true if reader was able to jump successfully to the region's left boundary
\sa HasIndex(), Jump()
*/
This is an overloaded function.
- \param leftRefID referenceID of region's left boundary
- \param leftPosition position of region's left boundary
- \param rightRefID reference ID of region's right boundary
- \param rightPosition position of region's right boundary
+ \warning This function expects a zero-based, HALF-OPEN interval.
+ In previous versions of BamTools (0.x & 1.x) all intervals were treated
+ as zero-based, CLOSED.
+
+ \param[in] leftRefID referenceID of region's left boundary
+ \param[in] leftPosition position of region's left boundary
+ \param[in] rightRefID reference ID of region's right boundary
+ \param[in] rightPosition position of region's right boundary
\returns \c true if reader was able to jump successfully to the region's left boundary
\sa HasIndex(), Jump()
\r
// returns a human-readable description of the last error that occurred\r
std::string GetErrorString(void) const;\r
-\r
- // deprecated methods\r
- public:\r
- // returns true if index data is available\r
- bool IsIndexLoaded(void) const;\r
\r
// private implementation\r
private:\r
// BamWriter.cpp (c) 2009 Michael Str�mberg, Derek Barnett\r
// Marth Lab, Department of Biology, Boston College\r
// ---------------------------------------------------------------------------\r
-// Last modified: 4 October 2011 (DB)\r
+// Last modified: 10 October 2011 (DB)\r
// ---------------------------------------------------------------------------\r
// Provides the basic functionality for producing BAM files\r
// ***************************************************************************\r
d->Close();\r
}\r
\r
-// returns a human-readable description of the last error that occurred\r
+/*! \fn std::string BamWriter::GetErrorString(void) const\r
+ \brief Returns a human-readable description of the last error that occurred\r
+\r
+ This method allows elimination of STDERR pollution. Developers of client code\r
+ may choose how the messages are displayed to the user, if at all.\r
+\r
+ \return error description\r
+*/\r
std::string BamWriter::GetErrorString(void) const {\r
return d->GetErrorString();\r
}\r
\r
Will overwrite the BAM file if it already exists.\r
\r
- \param filename name of output BAM file\r
- \param samHeaderText header data, as SAM-formatted string\r
- \param referenceSequences list of reference entries\r
+ \param[in] filename name of output BAM file\r
+ \param[in] samHeaderText header data, as SAM-formatted string\r
+ \param[in] referenceSequences list of reference entries\r
\r
\return \c true if opened successfully\r
\sa Close(), IsOpen(), BamReader::GetHeaderText(), BamReader::GetReferenceData()\r
\r
Will overwrite the BAM file if it already exists.\r
\r
- \param filename name of output BAM file\r
- \param samHeader header data, wrapped in SamHeader object\r
- \param referenceSequences list of reference entries\r
+ \param[in] filename name of output BAM file\r
+ \param[in] samHeader header data, wrapped in SamHeader object\r
+ \param[in] referenceSequences list of reference entries\r
\r
\return \c true if opened successfully\r
\sa Close(), IsOpen(), BamReader::GetHeader(), BamReader::GetReferenceData()\r
/*! \fn void BamWriter::SaveAlignment(const BamAlignment& alignment)\r
\brief Saves an alignment to the BAM file.\r
\r
- \param alignment BamAlignment record to save\r
+ \param[in] alignment BamAlignment record to save\r
\sa BamReader::GetNextAlignment(), BamReader::GetNextAlignmentCore()\r
*/\r
bool BamWriter::SaveAlignment(const BamAlignment& alignment) {\r
\r
Default mode is BamWriter::Compressed.\r
\r
- N.B. - Changing the compression mode is disabled on open files (i.e. the request will be ignored).\r
- Be sure to call this function before opening the BAM file.\r
+ \note Changing the compression mode is disabled on open files (i.e. the request will\r
+ be ignored). Be sure to call this function before opening the BAM file.\r
\r
\code\r
BamWriter writer;\r
// ...\r
\endcode\r
\r
- \param compressionMode desired output compression behavior\r
+ \param[in] compressionMode desired output compression behavior\r
\sa IsOpen(), Open()\r
*/\r
void BamWriter::SetCompressionMode(const BamWriter::CompressionMode& compressionMode) {\r
// BamWriter.h (c) 2009 Michael Str�mberg, Derek Barnett\r
// Marth Lab, Department of Biology, Boston College\r
// ---------------------------------------------------------------------------\r
-// Last modified: 5 October 2011 (DB)\r
+// Last modified: 10 October 2011 (DB)\r
// ---------------------------------------------------------------------------\r
// Provides the basic functionality for producing BAM files\r
// ***************************************************************************\r
class BamAlignment;\r
class SamHeader;\r
\r
+//! \cond\r
namespace Internal {\r
class BamWriterPrivate;\r
} // namespace Internal\r
+//! \endcond\r
\r
class API_EXPORT BamWriter {\r
\r
// SamHeader.cpp (c) 2010 Derek Barnett
// Marth Lab, Department of Biology, Boston College
// ---------------------------------------------------------------------------
-// Last modified: 6 October 2011 (DB)
+// Last modified: 10 October 2011 (DB)
// ---------------------------------------------------------------------------
// Provides direct read/write access to the SAM header data fields.
// ***************************************************************************
/*! \var SamHeader::Version
\brief corresponds to \@HD VN:\<Version\>
- Required for valid SAM header, if @HD record is present.
+ Required for valid SAM header, if \@HD record is present.
*/
/*! \var SamHeader::SortOrder
\brief corresponds to \@HD SO:\<SortOrder\>
\brief corresponds to \@RG entries
\sa SamReadGroup, SamReadGroupDictionary
*/
-/*! \var SamHeader::ProgramName
- \brief corresponds to \@PG ID:\<ProgramName\>
-*/
-/*! \var SamHeader::ProgramVersion
- \brief corresponds to \@PG VN:\<ProgramVersion\>
-*/
-/*! \var SamHeader::ProgramCommandLine
- \brief corresponds to \@PG CL:\<ProgramCommandLine\>
+/*! \var SamHeader::Programs
+ \brief corresponds to \@PG entries
+ \sa SamProgram, SamProgramChain
*/
/*! \var SamHeader::Comments
\brief corresponds to \@CO entries
}
/*! \fn std::string SamHeader::GetErrorString(void) const
- \brief Returns human-readable description of last error encountered
+ \brief Returns a human-readable description of the last error that occurred
+
+ This method allows elimination of STDERR pollution. Developers of client code
+ may choose how the messages are displayed to the user, if at all.
+
+ \return error description
*/
std::string SamHeader::GetErrorString(void) const {
return m_errorString;
/*! \fn bool SamHeader::IsValid(bool verbose = false) const
\brief Checks header contents for required data and proper formatting.
- \param verbose If set to true, validation errors & warnings will be printed to stderr.
- Otherwise, messages are available through SamHeader::GetErrorString().
+
+ \param[in] verbose If set to true, validation errors & warnings will be printed to stderr.
+ Otherwise, messages are available through SamHeader::GetErrorString().
\return \c true if SAM header is well-formed
*/
bool SamHeader::IsValid(bool verbose) const {
/*! \fn void SamHeader::SetHeaderText(const std::string& headerText)
\brief Replaces header contents with \a headerText.
- \param headerText SAM formatted-text that will be parsed into data fields
+
+ \param[in] headerText SAM formatted-text that will be parsed into data fields
*/
void SamHeader::SetHeaderText(const std::string& headerText) {
// SamHeader.h (c) 2010 Derek Barnett
// Marth Lab, Department of Biology, Boston College
// ---------------------------------------------------------------------------
-// Last modified: 6 October 2011 (DB)
+// Last modified: 10 October 2011 (DB)
// ---------------------------------------------------------------------------
// Provides direct read/write access to the SAM header data fields.
// ***************************************************************************
std::string ToString(void) const; // returns the printable, SAM-formatted header text
// convenience query methods
- bool HasVersion(void) const; // returns true if header contains format version entry
- bool HasSortOrder(void) const; // returns true if header contains sort order entry
- bool HasGroupOrder(void) const; // returns true if header contains group order entry
- bool HasSequences(void) const; // returns true if header contains any sequence entries
- bool HasReadGroups(void) const; // returns true if header contains any read group entries
- bool HasPrograms(void) const; // returns true if header contains any program record entries
- bool HasComments(void) const; // returns true if header contains comments
+ bool HasVersion(void) const; // returns true if header contains format version entry
+ bool HasSortOrder(void) const; // returns true if header contains sort order entry
+ bool HasGroupOrder(void) const; // returns true if header contains group order entry
+ bool HasSequences(void) const; // returns true if header contains any sequence entries
+ bool HasReadGroups(void) const; // returns true if header contains any read group entries
+ bool HasPrograms(void) const; // returns true if header contains any program record entries
+ bool HasComments(void) const; // returns true if header contains comments
// --------------
// data members
// --------------
// header metadata (@HD line)
- std::string Version; // VN:<Version> *Required, if @HD record is present*
- std::string SortOrder; // SO:<SortOrder>
- std::string GroupOrder; // GO:<GroupOrder>
+ std::string Version; // VN:<Version> *Required, if @HD record is present*
+ std::string SortOrder; // SO:<SortOrder>
+ std::string GroupOrder; // GO:<GroupOrder>
// header sequences (@SQ entries)
SamSequenceDictionary Sequences;
// header comments (@CO entries)
std::vector<std::string> Comments;
+ // internal data
private:
mutable std::string m_errorString;
};
// SamProgram.h (c) 2011 Derek Barnett
// Marth Lab, Department of Biology, Boston College
// ---------------------------------------------------------------------------
-// Last modified: 19 April 2011 (DB)
+// Last modified: 10 October 2011 (DB)
// ---------------------------------------------------------------------------
// Provides direct read/write access to the SAM header program records.
// ***************************************************************************
~SamProgram(void);
// query/modify entire program record
- void Clear(void); // clears all data fields
+ void Clear(void); // clears all data fields
// convenience query methods
- bool HasCommandLine(void) const; // returns true if program record has a command line entry
- bool HasID(void) const; // returns true if program record has an ID
- bool HasName(void) const; // returns true if program record has a name
- bool HasPreviousProgramID(void) const; // returns true if program record has a 'previous program ID'
- bool HasVersion(void) const; // returns true if program record has a version
+ bool HasCommandLine(void) const; // returns true if program record has a command line entry
+ bool HasID(void) const; // returns true if program record has an ID
+ bool HasName(void) const; // returns true if program record has a name
+ bool HasPreviousProgramID(void) const; // returns true if program record has a 'previous program ID'
+ bool HasVersion(void) const; // returns true if program record has a version
// data members
- std::string CommandLine; // CL:<CommandLine>
- std::string ID; // ID:<ID> *Required for valid SAM header*
- std::string Name; // PN:<Name>
- std::string PreviousProgramID;
// PP:<PreviousProgramID>
- std::string Version; // VN:<Version>
+ std::string CommandLine; // CL:<CommandLine>
+ std::string ID; // ID:<ID> *Required for valid SAM header*
+ std::string Name; // PN:<Name>
+ std::string PreviousProgramID; // PP:<PreviousProgramID>
+ std::string Version; // VN:<Version>
// internal (non-standard) methods & fields
private:
// SamProgramChain.cpp (c) 2011 Derek Barnett
// Marth Lab, Department of Biology, Boston College
// ---------------------------------------------------------------------------
-// Last modified: 19 April 2011 (DB)
+// Last modified: 10 October 2011 (DB)
// ---------------------------------------------------------------------------
// Provides methods for operating on a SamProgram record "chain"
// ***************************************************************************
Provides methods for operating on a collection of SamProgram records.
- N.B. - Underlying container is *NOT* ordered by linkage, but by order of
+ \note Underlying container is *NOT* ordered by linkage, but by order of
appearance in SamHeader and subsequent Add() calls. Using the current
iterators will not allow you to step through the header's program history.
Instead use First()/Last() to access oldest/newest records, respectively.
Duplicate entries are silently discarded.
- N.B. - Underlying container is *NOT* ordered by linkage, but by order of
+ \note Underlying container is *NOT* ordered by linkage, but by order of
appearance in SamHeader and subsequent Add() calls. Using the current
iterators will not allow you to step through the header's program history.
Instead use First()/Last() to access oldest/newest records, respectively.
- \param program entry to be appended
+ \param[in] program entry to be appended
*/
void SamProgramChain::Add(SamProgram& program) {
m_data.push_back(program);
}
-/*! \fn void SamProgramChain::Add(const std::vector<SamProgram>& programs)
+/*! \fn void SamProgramChain::Add(std::vector<SamProgram>& programs)
\brief Appends a batch of programs to the end of the chain.
This is an overloaded function.
- \param programs batch of program records to append
+ \param[in] programs batch of program records to append
\sa Add()
*/
void SamProgramChain::Add(std::vector<SamProgram>& programs) {
This is an overloaded function.
- \param program SamProgram to search for
+ \param[in] program SamProgram to search for
\return \c true if chain contains program (matching on ID)
*/
bool SamProgramChain::Contains(const SamProgram& program) const {
/*! \fn bool SamProgramChain::Contains(const std::string& programId) const
\brief Returns true if chains has a program record with this ID
- \param programId search for program matching this ID
+
+ \param[in] programId search for program matching this ID
\return \c true if chain contains a program record with this ID
*/
bool SamProgramChain::Contains(const std::string& programId) const {
/*! \fn SamProgram& SamProgramChain::First(void)
\brief Fetches first (oldest) record in the chain.
- N.B. - This function will fail if the chain is empty. If this is possible,
+ \warning This function will fail if the chain is empty. If this is possible,
check the result of IsEmpty() before calling this function.
\return a modifiable reference to the first (oldest) program entry
}
// otherwise error
- cerr << "SamProgramChain ERROR - could not find any record without a PP tag" << endl;
+ cerr << "SamProgramChain::First: could not find any record without a PP tag" << endl;
exit(1);
}
This is an overloaded function.
- N.B. - This function will fail if the chain is empty. If this is possible,
+ \warning This function will fail if the chain is empty. If this is possible,
check the result of IsEmpty() before calling this function.
\return a read-only reference to the first (oldest) program entry
}
// otherwise error
- cerr << "SamProgramChain ERROR - could not find any record without a PP tag" << endl;
+ cerr << "SamProgramChain::First: could not find any record without a PP tag" << endl;
exit(1);
}
/*! \fn SamProgram& SamProgramChain::Last(void)
\brief Fetches last (newest) record in the chain.
- N.B. - This function will fail if the chain is empty. If this is possible,
+ \warning This function will fail if the chain is empty. If this is possible,
check the result of IsEmpty() before calling this function.
\return a modifiable reference to the last (newest) program entry
}
// otherwise error
- cerr << "SamProgramChain ERROR - could not determine last record" << endl;
+ cerr << "SamProgramChain::Last: could not determine last record" << endl;
exit(1);
}
This is an overloaded function.
- N.B. - This function will fail if the chain is empty. If this is possible,
+ \warning This function will fail if the chain is empty. If this is possible,
check the result of IsEmpty() before calling this function.
\return a read-only reference to the last (newest) program entry
}
// otherwise error
- cerr << "SamProgramChain ERROR - could not determine last record" << endl;
+ cerr << "SamProgramChain::Last: could not determine last record" << endl;
exit(1);
}
/*! \fn const std::string SamProgramChain::NextIdFor(const std::string& programId) const
\internal
+
\return ID of program record, whose PreviousProgramID matches \a programId.
Otherwise, returns empty string if none found.
*/
/*! \fn SamProgram& SamProgramChain::operator[](const std::string& programId)
\brief Retrieves the modifiable SamProgram record that matches \a programId.
- NOTE - If the chain contains no read group matching this ID, this function will
- print an error and terminate.
+ \warning If the chain contains no read group matching this ID, this function will
+ print an error and terminate. Check the return value of Contains() if this may be
+ possible.
- \param programId ID of program record to retrieve
+ \param[in] programId ID of program record to retrieve
\return a modifiable reference to the SamProgram associated with the ID
*/
SamProgram& SamProgramChain::operator[](const std::string& programId) {
// if record not found
if ( index == (int)m_data.size() ) {
- cerr << "SamProgramChain ERROR - unknown programId: " << programId << endl;
+ cerr << "SamProgramChain::operator[] - unknown programId: " << programId << endl;
exit(1);
}
// SamProgramChain.h (c) 2011 Derek Barnett
// Marth Lab, Department of Biology, Boston College
// ---------------------------------------------------------------------------
-// Last modified: 19 April 2011 (DB)
+// Last modified: 10 October 2011 (DB)
// ---------------------------------------------------------------------------
// Provides methods for operating on a SamProgram record "chain"
// ***************************************************************************
// SamReadGroup.h (c) 2010 Derek Barnett
// Marth Lab, Department of Biology, Boston College
// ---------------------------------------------------------------------------
-// Last modified: 18 April 2011 (DB)
+// Last modified: 10 October 2011 (DB)
// ---------------------------------------------------------------------------
// Provides direct read/write access to the SAM read group data fields.
// ***************************************************************************
~SamReadGroup(void);
// query/modify entire read group
- void Clear(void); // clears all data fields
+ void Clear(void); // clears all data fields
// convenience query methods
- bool HasDescription(void) const; // returns true if read group has a description
- bool HasFlowOrder(void) const; // returns true if read group has a flow order entry
- bool HasID(void) const; // returns true if read group has a group ID
- bool HasKeySequence(void) const; // returns true if read group has a key sequence
- bool HasLibrary(void) const; // returns true if read group has a library name
- bool HasPlatformUnit(void) const; // returns true if read group has a platform unit ID
- bool HasPredictedInsertSize(void) const; // returns true if read group has a predicted insert size
- bool HasProductionDate(void) const; // returns true if read group has a production date
- bool HasProgram(void) const; // returns true if read group has a program entry
- bool HasSample(void) const; // returns true if read group has a sample name
- bool HasSequencingCenter(void) const; // returns true if read group has a sequencing center ID
- bool HasSequencingTechnology(void) const; // returns true if read group has a sequencing technology ID
+ bool HasDescription(void) const; // returns true if read group has a description
+ bool HasFlowOrder(void) const; // returns true if read group has a flow order entry
+ bool HasID(void) const; // returns true if read group has a group ID
+ bool HasKeySequence(void) const; // returns true if read group has a key sequence
+ bool HasLibrary(void) const; // returns true if read group has a library name
+ bool HasPlatformUnit(void) const; // returns true if read group has a platform unit ID
+ bool HasPredictedInsertSize(void) const; // returns true if read group has a predicted insert size
+ bool HasProductionDate(void) const; // returns true if read group has a production date
+ bool HasProgram(void) const; // returns true if read group has a program entry
+ bool HasSample(void) const; // returns true if read group has a sample name
+ bool HasSequencingCenter(void) const; // returns true if read group has a sequencing center ID
+ bool HasSequencingTechnology(void) const; // returns true if read group has a sequencing technology ID
// data fields
- std::string Description; // DS:<Description>
- std::string FlowOrder; // FO:<FlowOrder>
- std::string ID; // ID:<ID> *Required for valid SAM header*
- std::string KeySequence; // KS:<KeySequence>
- std::string Library; // LB:<Library>
- std::string PlatformUnit;
// PU:<PlatformUnit>
- std::string PredictedInsertSize;
// PI:<PredictedInsertSize>
- std::string ProductionDate;
// DT:<ProductionDate>
- std::string Program;
// PG:<Program>
- std::string Sample; // SM:<Sample>
- std::string SequencingCenter; // CN:<SequencingCenter>
- std::string SequencingTechnology; // PL:<SequencingTechnology>
+ std::string Description; // DS:<Description>
+ std::string FlowOrder; // FO:<FlowOrder>
+ std::string ID; // ID:<ID> *Required for valid SAM header*
+ std::string KeySequence; // KS:<KeySequence>
+ std::string Library; // LB:<Library>
+ std::string PlatformUnit; // PU:<PlatformUnit>
+ std::string PredictedInsertSize; // PI:<PredictedInsertSize>
+ std::string ProductionDate; // DT:<ProductionDate>
+ std::string Program; // PG:<Program>
+ std::string Sample; // SM:<Sample>
+ std::string SequencingCenter; // CN:<SequencingCenter>
+ std::string SequencingTechnology; // PL:<SequencingTechnology>
};
/*! \fn bool operator==(const SamReadGroup& lhs, const SamReadGroup& rhs)
// SamReadGroupDictionary.cpp (c) 2010 Derek Barnett
// Marth Lab, Department of Biology, Boston College
// ---------------------------------------------------------------------------
-// Last modified: 1 October 2011 (DB)
+// Last modified: 10 October 2011 (DB)
// ---------------------------------------------------------------------------
// Provides methods for operating on a collection of SamReadGroup entries.
// ***************************************************************************
SamReadGroupDictionary::~SamReadGroupDictionary(void) { }
/*! \fn void SamReadGroupDictionary::Add(const SamReadGroup& readGroup)
- \brief Adds a read group to the dictionary.
+ \brief Appends a read group to the dictionary.
Duplicate entries are silently discarded.
- \param readGroup entry to be added
+ \param[in] readGroup entry to be added
*/
void SamReadGroupDictionary::Add(const SamReadGroup& readGroup) {
-
- // TODO: report error on attempted duplicate?
-
if ( IsEmpty() || !Contains(readGroup) )
m_data.push_back(readGroup);
}
/*! \fn void SamReadGroupDictionary::Add(const std::string& readGroupId)
- \brief Adds a read group to the dictionary.
+ \brief Appends a read group to the dictionary.
This is an overloaded function.
- \param readGroupId ID of read group to be added
+ \param[in] readGroupId ID of read group to be added
\sa Add()
*/
void SamReadGroupDictionary::Add(const std::string& readGroupId) {
Add( SamReadGroup(readGroupId) );
}
+/*! \fn void SamReadGroupDictionary::Add(const SamReadGroupDictionary& readGroups)
+ \brief Appends another read group dictionary to this one.
+
+ This is an overloaded function.
+
+ \param[in] readGroups entries to be added
+ \sa Add()
+*/
void SamReadGroupDictionary::Add(const SamReadGroupDictionary& readGroups) {
SamReadGroupConstIterator rgIter = readGroups.ConstBegin();
SamReadGroupConstIterator rgEnd = readGroups.ConstEnd();
}
/*! \fn void SamReadGroupDictionary::Add(const std::vector<SamReadGroup>& readGroups)
- \brief Adds multiple read groups to the dictionary.
+ \brief Appends multiple read groups to the dictionary.
This is an overloaded function.
- \param readGroups entries to be added
+ \param[in] readGroups entries to be added
\sa Add()
*/
void SamReadGroupDictionary::Add(const std::vector<SamReadGroup>& readGroups) {
}
/*! \fn void SamReadGroupDictionary::Add(const std::vector<std::string>& readGroupIds)
- \brief Adds multiple read groups to the dictionary.
+ \brief Appends multiple read groups to the dictionary.
This is an overloaded function.
- \param readGroupIds IDs of read groups to be added
+ \param[in] readGroupIds IDs of read groups to be added
\sa Add()
*/
void SamReadGroupDictionary::Add(const std::vector<std::string>& readGroupIds) {
/*! \fn bool SamReadGroupDictionary::Contains(const std::string& readGroupId) const
\brief Returns true if dictionary contains read group.
- \param readGroupId search for read group matching this ID
+
+ \param[in] readGroupId search for read group matching this ID
\return \c true if dictionary contains a read group with this ID
*/
bool SamReadGroupDictionary::Contains(const std::string& readGroupId) const {
This is an overloaded function.
- \param readGroup search for this read group
+ \param[in] readGroup search for this read group
\return \c true if dictionary contains read group (matching on ID).
*/
bool SamReadGroupDictionary::Contains(const SamReadGroup& readGroup) const {
This is an overloaded function.
- \param readGroup read group to remove (matches on ID)
+ \param[in] readGroup read group to remove (matches on ID)
*/
void SamReadGroupDictionary::Remove(const SamReadGroup& readGroup) {
Remove( readGroup.ID );
/*! \fn void SamReadGroupDictionary::Remove(const std::string& readGroupId)
\brief Removes read group from dictionary, if found.
- \param readGroupId ID of read group to remove
+
+ \param[in] readGroupId ID of read group to remove
\sa Remove()
*/
void SamReadGroupDictionary::Remove(const std::string& readGroupId) {
This is an overloaded function.
- \param readGroups read groups to remove
+ \param[in] readGroups read groups to remove
\sa Remove()
*/
void SamReadGroupDictionary::Remove(const std::vector<SamReadGroup>& readGroups) {
This is an overloaded function.
- \param readGroupIds IDs of the read groups to remove
+ \param[in] readGroupIds IDs of the read groups to remove
\sa Remove()
*/
void SamReadGroupDictionary::Remove(const std::vector<std::string>& readGroupIds) {
/*! \fn SamReadGroup& SamReadGroupDictionary::operator[](const std::string& readGroupId)
\brief Retrieves the modifiable SamReadGroup that matches \a readGroupId.
- NOTE - If the dictionary contains no read group matching this ID, this function inserts
- a new one with this ID, and returns a reference to it.
-
- If you want to avoid this insertion behavior, check the result of Contains() before
- using this operator.
+ \note If the dictionary contains no read group matching this ID, this function inserts
+ a new one with this ID, and returns a reference to it. If you want to avoid this insertion
+ behavior, check the result of Contains() before using this operator.
- \param readGroupId ID of read group to retrieve
+ \param[in] readGroupId ID of read group to retrieve
\return a modifiable reference to the SamReadGroup associated with the ID
*/
SamReadGroup& SamReadGroupDictionary::operator[](const std::string& readGroupId) {
// SamSequence.h (c) 2010 Derek Barnett
// Marth Lab, Department of Biology, Boston College
// ---------------------------------------------------------------------------
-// Last modified: 18 April 2011 (DB)
+// Last modified: 10 October 2011 (DB)
// ---------------------------------------------------------------------------
// Provides direct read/write access to the SAM sequence data fields.
// ***************************************************************************
~SamSequence(void);
// query/modify entire sequence
- void Clear(void); // clears all contents
+ void Clear(void); // clears all contents
// convenience query methods
- bool HasAssemblyID(void) const; // returns true if sequence has an assembly ID
- bool HasChecksum(void) const; // returns true if sequence has an MD5 checksum
- bool HasLength(void) const; // returns true if sequence has a length
- bool HasName(void) const; // returns true if sequence has a name
- bool HasSpecies(void) const; // returns true if sequence has a species ID
- bool HasURI(void) const; // returns true if sequence has a URI
+ bool HasAssemblyID(void) const; // returns true if sequence has an assembly ID
+ bool HasChecksum(void) const; // returns true if sequence has an MD5 checksum
+ bool HasLength(void) const; // returns true if sequence has a length
+ bool HasName(void) const; // returns true if sequence has a name
+ bool HasSpecies(void) const; // returns true if sequence has a species ID
+ bool HasURI(void) const; // returns true if sequence has a URI
// data members
- std::string AssemblyID;
// AS:<AssemblyID>
- std::string Checksum; // M5:<Checksum>
- std::string Length; // LN:<Length> *Required for valid SAM header*
- std::string Name; // SN:<Name> *Required for valid SAM header*
- std::string Species; // SP:<Species>
- std::string URI; // UR:<URI>
+ std::string AssemblyID; // AS:<AssemblyID>
+ std::string Checksum; // M5:<Checksum>
+ std::string Length; // LN:<Length> *Required for valid SAM header*
+ std::string Name; // SN:<Name> *Required for valid SAM header*
+ std::string Species; // SP:<Species>
+ std::string URI; // UR:<URI>
};
/*! \fn bool operator==(const SamSequence& lhs, const SamSequence& rhs)
// SamSequenceDictionary.cpp (c) 2010 Derek Barnett
// Marth Lab, Department of Biology, Boston College
// ---------------------------------------------------------------------------
-// Last modified: 1 October 2011 (DB)
+// Last modified: 10 October 2011 (DB)
// ---------------------------------------------------------------------------
// Provides methods for operating on a collection of SamSequence entries.
// *************************************************************************
SamSequenceDictionary::~SamSequenceDictionary(void) { }
/*! \fn void SamSequenceDictionary::Add(const SamSequence& sequence)
- \brief Adds a sequence to the dictionary.
+ \brief Appends a sequence to the dictionary.
Duplicate entries are silently discarded.
- \param sequence entry to be added
+ \param[in] sequence entry to be added
*/
void SamSequenceDictionary::Add(const SamSequence& sequence) {
-
- // TODO: report error on attempted duplicate?
-
if ( IsEmpty() || !Contains(sequence) )
m_data.push_back(sequence);
}
/*! \fn void SamSequenceDictionary::Add(const std::string& name, const int& length)
- \brief Adds a sequence to the dictionary.
+ \brief Appends a sequence to the dictionary.
This is an overloaded function.
- \param name name of sequence entry to be added
- \param length length of sequence entry to be added
+ \param[in] name name of sequence entry to be added
+ \param[in] length length of sequence entry to be added
\sa Add()
*/
void SamSequenceDictionary::Add(const std::string& name, const int& length) {
Add( SamSequence(name, length) );
}
+/*! \fn void SamSequenceDictionary::Add(const SamSequenceDictionary& sequences)
+ \brief Appends another sequence dictionary to this one
+
+ This is an overloaded function.
+
+ \param[in] sequences sequence dictionary to be appended
+ \sa Add()
+*/
void SamSequenceDictionary::Add(const SamSequenceDictionary& sequences) {
SamSequenceConstIterator seqIter = sequences.ConstBegin();
SamSequenceConstIterator seqEnd = sequences.ConstEnd();
}
/*! \fn void SamSequenceDictionary::Add(const std::vector<SamSequence>& sequences)
- \brief Adds multiple sequences to the dictionary.
+ \brief Appends multiple sequences to the dictionary.
This is an overloaded function.
- \param sequences entries to be added
+ \param[in] sequences entries to be added
\sa Add()
*/
void SamSequenceDictionary::Add(const std::vector<SamSequence>& sequences) {
}
/*! \fn void SamSequenceDictionary::Add(const std::map<std::string, int>& sequenceMap)
- \brief Adds multiple sequences to the dictionary.
+ \brief Appends multiple sequences to the dictionary.
This is an overloaded function.
- \param sequenceMap map of sequence entries (name => length) to be added
+ \param[in] sequenceMap map of sequence entries (name => length) to be added
\sa Add()
*/
void SamSequenceDictionary::Add(const std::map<std::string, int>& sequenceMap) {
/*! \fn bool SamSequenceDictionary::Contains(const std::string& sequenceName) const
\brief Returns true if dictionary contains sequence.
- \param sequenceName search for sequence matching this name
+
+ \param[in] sequenceName search for sequence matching this name
\return \c true if dictionary contains a sequence with this name
*/
bool SamSequenceDictionary::Contains(const std::string& sequenceName) const {
This is an overloaded function.
- \param sequence search for this sequence
+ \param[in] sequence search for this sequence
\return \c true if dictionary contains sequence (matching on name)
*/
bool SamSequenceDictionary::Contains(const SamSequence& sequence) const {
This is an overloaded function.
- \param sequence SamSequence to remove (matching on name)
+ \param[in] sequence SamSequence to remove (matching on name)
*/
void SamSequenceDictionary::Remove(const SamSequence& sequence) {
Remove( sequence.Name );
/*! \fn void SamSequenceDictionary::Remove(const std::string& sequenceName)
\brief Removes sequence from dictionary, if found.
- \param sequenceName name of sequence to remove
+ \param[in] sequenceName name of sequence to remove
\sa Remove()
*/
void SamSequenceDictionary::Remove(const std::string& sequenceName) {
This is an overloaded function.
- \param sequences sequences to remove
+ \param[in] sequences sequences to remove
\sa Remove()
*/
void SamSequenceDictionary::Remove(const std::vector<SamSequence>& sequences) {
This is an overloaded function.
- \param sequenceNames names of the sequences to remove
+ \param[in] sequenceNames names of the sequences to remove
\sa Remove()
*/
void SamSequenceDictionary::Remove(const std::vector<std::string>& sequenceNames) {
/*! \fn SamSequence& SamSequenceDictionary::operator[](const std::string& sequenceName)
\brief Retrieves the modifiable SamSequence that matches \a sequenceName.
- NOTE - If the dictionary contains no sequence matching this name, this function inserts
- a new one with this name (length:0), and returns a reference to it.
-
- If you want to avoid this insertion behavior, check the result of Contains() before
- using this operator.
+ \note If the dictionary contains no sequence matching this name, this function inserts
+ a new one with this name (length:0), and returns a reference to it. If you want to avoid
+ this insertion behavior, check the result of Contains() before using this operator.
- \param sequenceName name of sequence to retrieve
+ \param[in] sequenceName name of sequence to retrieve
\return a modifiable reference to the SamSequence associated with the name
*/
SamSequence& SamSequenceDictionary::operator[](const std::string& sequenceName) {
// Marth Lab, Department of Biology, Boston College
// All rights reserved.
// ---------------------------------------------------------------------------
-// Last modified: 29 September 2011 (DB)
+// Last modified: 10 October 2011 (DB)
// ---------------------------------------------------------------------------
// Provides sorting functionality.
// ***************************************************************************
#include <api/BamAlignment.h>
#include <api/BamReader.h>
#include <api/BamMultiReader.h>
-#include <algorithm>
#include <cassert>
+#include <algorithm>
#include <functional>
#include <string>
#include <vector>
namespace BamTools {
namespace Algorithms {
+/*! \struct BamTools::Algorithms::Sort
+ \brief Provides classes & methods related to sorting BamAlignments
+*/
struct API_EXPORT Sort {
+ //! Provides explicit values for specifying desired sort ordering
enum Order { AscendingOrder = 0
, DescendingOrder
};
+ /*! \fn template<typename ElemType> static inline bool sort_helper(const Sort::Order& order, const ElemType& lhs, const ElemType& rhs)
+ \internal
+
+ Determines necessary STL function object depending on requested Sort::Order
+ */
template<typename ElemType>
- static inline bool sort_helper(const Sort::Order& order,
- const ElemType& lhs,
- const ElemType& rhs)
- {
+ static inline bool sort_helper(const Sort::Order& order, const ElemType& lhs, const ElemType& rhs) {
switch ( order ) {
case ( Sort::AscendingOrder ) : { std::less<ElemType> comp; return comp(lhs, rhs); }
case ( Sort::DescendingOrder ) : { std::greater<ElemType> comp; return comp(lhs, rhs); }
- default : assert(false);
+ default : BT_ASSERT_UNREACHABLE;
}
return false; // <-- unreachable
}
+ //! Base class for our sorting function objects
typedef std::binary_function<BamAlignment, BamAlignment, bool> AlignmentSortBase;
- // compare alignments by name
+ /*! \struct BamTools::Algorithms::Sort::ByName
+ \brief Function object for comparing alignments by name
+
+ Default sort order is Sort::AscendingOrder.
+
+ \code
+ std::vector<BamAlignment> a;
+
+ // sort by name, in ascending order (the following two lines are equivalent):
+ std::sort( a.begin(), a.end(), Sort::ByName() );
+ std::sort( a.begin(), a.end(), Sort::ByName(Sort::AscendingOrder) );
+
+ // OR sort in descending order
+ std::sort( a.begin(), a.end(), Sort::ByName(Sort::DescendingOrder) );
+ \endcode
+ */
struct ByName : public AlignmentSortBase {
+ // ctor
ByName(const Sort::Order& order = Sort::AscendingOrder)
: m_order(order)
{ }
- bool operator()(const BamTools::BamAlignment& lhs,
- const BamTools::BamAlignment& rhs)
- {
+ // comparison function
+ bool operator()(const BamTools::BamAlignment& lhs, const BamTools::BamAlignment& rhs) {
return sort_helper(m_order, lhs.Name, rhs.Name);
}
+ // used by BamMultiReader internals
static inline bool UsesCharData(void) { return true; }
+ // data members
private:
const Sort::Order& m_order;
};
- // compare alignments by position
+ /*! \struct BamTools::Algorithms::Sort::ByPosition
+ \brief Function object for comparing alignments by position
+
+ Default sort order is Sort::AscendingOrder.
+
+ \code
+ std::vector<BamAlignment> a;
+
+ // sort by position, in ascending order (the following two lines are equivalent):
+ std::sort( a.begin(), a.end(), Sort::ByPosition() );
+ std::sort( a.begin(), a.end(), Sort::ByPosition(Sort::AscendingOrder) );
+
+ // OR sort in descending order
+ std::sort( a.begin(), a.end(), Sort::ByPosition(Sort::DescendingOrder) );
+ \endcode
+ */
struct ByPosition : public AlignmentSortBase {
+ // ctor
ByPosition(const Sort::Order& order = Sort::AscendingOrder)
: m_order(order)
{ }
- bool operator()(const BamTools::BamAlignment& lhs,
- const BamTools::BamAlignment& rhs)
- {
+ // comparison function
+ bool operator()(const BamTools::BamAlignment& lhs, const BamTools::BamAlignment& rhs) {
+
// force unmapped aligmnents to end
if ( lhs.RefID == -1 ) return false;
if ( rhs.RefID == -1 ) return true;
return sort_helper(m_order, lhs.RefID, rhs.RefID);
}
+ // used by BamMultiReader internals
static inline bool UsesCharData(void) { return false; }
+ // data members
private:
Sort::Order m_order;
};
- // compare alignments by tag value
+ /*! \struct BamTools::Algorithms::Sort::ByTag
+ \brief Function object for comparing alignments by tag value
+
+ Default sort order is Sort::AscendingOrder.
+
+ \code
+ std::vector<BamAlignment> a;
+
+ // sort by edit distance, in ascending order (the following two lines are equivalent):
+ std::sort( a.begin(), a.end(), Sort::ByTag<int>("NM") );
+ std::sort( a.begin(), a.end(), Sort::ByTag<int>("NM", Sort::AscendingOrder) );
+
+ // OR sort in descending order
+ std::sort( a.begin(), a.end(), Sort::ByTag<int>("NM", Sort::DescendingOrder) );
+ \endcode
+ */
template<typename T>
struct ByTag : public AlignmentSortBase {
+ // ctor
ByTag(const std::string& tag,
const Sort::Order& order = Sort::AscendingOrder)
: m_tag(tag)
, m_order(order)
{ }
- bool operator()(const BamTools::BamAlignment& lhs,
- const BamTools::BamAlignment& rhs)
- {
+ // comparison function
+ bool operator()(const BamTools::BamAlignment& lhs, const BamTools::BamAlignment& rhs) {
+
// force alignments without tag to end
T lhsTagValue;
T rhsTagValue;
return sort_helper(m_order, lhsTagValue, rhsTagValue);
}
+ // used by BamMultiReader internals
static inline bool UsesCharData(void) { return true; }
+ // data members
private:
std::string m_tag;
Sort::Order m_order;
};
- // essentially a placeholder comparison object, ignores the alignments' data
- // N.B. - returning false tends to retain insertion order
+ /*! \struct BamTools::Algorithms::Sort::Unsorted
+ \brief Placeholder function object
+
+ This function object exists purely to allow for dropping a "do not care" ordering
+ into methods, containers, etc that are designed to work with the other sorting objects.
+
+ \code
+ std::set<BamAlignment, Sort::ByName>; // STL set, ordered on alignment name
+ std::set<BamAlignment, Sort::Unsorted>; // STL set, unsorted (but probably insertion order)
+ \endcode
+ */
struct Unsorted : public AlignmentSortBase {
- inline bool operator()(const BamTools::BamAlignment& /*lhs*/,
- const BamTools::BamAlignment& /*rhs*/)
- {
- return false;
+
+ // comparison function
+ inline bool operator()(const BamTools::BamAlignment&, const BamTools::BamAlignment&) {
+ return false; // returning false tends to retain insertion order
}
+ // used by BamMultiReader internals
static inline bool UsesCharData(void) { return false; }
};
-};
-// in-place sorting of alignment vector
-template<typename Compare>
-inline
-void SortAlignments(std::vector<BamAlignment>& data,
- const Compare& comp = Compare())
-{
- std::sort(data.begin(), data.end(), comp);
-}
-
-// returns sorted copy of input alignment vector
-template<typename Compare>
-inline
-std::vector<BamAlignment> SortAlignmentsCopy(const std::vector<BamAlignment>& input,
- const Compare& comp = Compare())
-{
- std::vector<BamAlignment> output(input);
- SortAlignments(output, comp);
- return output;
-}
-
-// pulls a region from a position-sorted BAM file
-// returns the alignments sorted by user-defined Compare type
-template<typename Compare>
-std::vector<BamAlignment> GetSortedRegion(BamReader& reader,
- const BamRegion& region,
- const Compare& comp = Compare())
-{
- // return empty container if unable to find region
- if ( !reader.IsOpen() ) return std::vector<BamAlignment>();
- if ( !reader.SetRegion(region) ) return std::vector<BamAlignment>();
-
- // iterate through region, grabbing alignments
- BamAlignment al;
- std::vector<BamAlignment> results;
- while ( reader.GetNextAlignmentCore(al) )
- results.push_back(al);
-
- // sort & return alignments
- SortAlignments(results, comp);
- return results;
-}
-
-template<typename Compare>
-std::vector<BamAlignment> GetSortedRegion(BamMultiReader& reader,
- const BamRegion& region,
- const Compare& comp = Compare())
-{
- // return empty container if unable to find region
- if ( !reader.HasOpenReaders() ) return std::vector<BamAlignment>();
- if ( !reader.SetRegion(region) ) return std::vector<BamAlignment>();
-
- // iterate through region, grabbing alignments
- BamAlignment al;
- std::vector<BamAlignment> results;
- while ( reader.GetNextAlignmentCore(al) )
- results.push_back(al);
-
- // sort & return alignments
- SortAlignments(results, comp);
- return results;
-}
+ /*! Sorts a std::vector of alignments (in-place), using the provided compare function.
+
+ \code
+ std::vector<BamAlignemnt> a;
+ // populate data
+
+ // sort our alignment list by edit distance
+ Sort::SortAlignments(a, Sort::ByTag<int>("NM"));
+ \endcode
+
+ \param[in,out] data vector of alignments to be sorted
+ \param[in] comp comparison function object
+ */
+ template<typename Compare>
+ static inline void SortAlignments(std::vector<BamAlignment>& data,
+ const Compare& comp = Compare())
+ {
+ std::sort(data.begin(), data.end(), comp);
+ }
+
+ /*! Returns a sorted copy of the input alignments, using the provided compare function.
+
+ \code
+ std::vector<BamAlignemnt> a;
+ // populate data
+
+ // get a copy of our original data, sorted by edit distance (descending order)
+ std::vector<BamAligment> sortedData;
+ sortedData = Sort::SortAlignments(a, Sort::ByTag<int>("NM", Sort::DescendingOrder));
+ \endcode
+
+ \param[in] input vector of alignments to be sorted
+ \param[in] comp comparison function object
+ \return sorted copy of the input data
+ */
+ template<typename Compare>
+ static inline std::vector<BamAlignment> SortAlignments(const std::vector<BamAlignment>& input,
+ const Compare& comp = Compare())
+ {
+ std::vector<BamAlignment> output(input);
+ SortAlignments(output, comp);
+ return output;
+ }
+
+ /*! Reads a region of alignments from a position-sorted BAM file,
+ then sorts by the provided compare function
+
+ \code
+ BamReader reader;
+ // open BAM file & index file
+
+ BamRegion region;
+ // define a region of interest (i.e. a exon or some other feature)
+
+ // get all alignments covering that region, sorted by read group name
+ std::vector<BamAlignments> a;
+ a = Sort::GetSortedRegion(reader, region, Sort::ByTag<std::string>("RG"));
+ \endcode
+
+ \param[in] reader BamReader opened on desired BAM file
+ \param[in] region desired region-of-interest
+ \param[in] comp comparison function object
+ \return sorted vector of the region's alignments
+ */
+ template<typename Compare>
+ static std::vector<BamAlignment> GetSortedRegion(BamReader& reader,
+ const BamRegion& region,
+ const Compare& comp = Compare())
+ {
+ // return empty container if unable to find region
+ if ( !reader.IsOpen() ) return std::vector<BamAlignment>();
+ if ( !reader.SetRegion(region) ) return std::vector<BamAlignment>();
+
+ // iterate through region, grabbing alignments
+ BamAlignment al;
+ std::vector<BamAlignment> results;
+ while ( reader.GetNextAlignmentCore(al) )
+ results.push_back(al);
+
+ // sort & return alignments
+ SortAlignments(results, comp);
+ return results;
+ }
+
+ /*! Reads a region of alignments from position-sorted BAM files,
+ then sorts by the provided compare function
+
+ \code
+ BamMultiReader reader;
+ // open BAM files & index files
+
+ BamRegion region;
+ // define a region of interest (i.e. a exon or some other feature)
+
+ // get all alignments covering that region, sorted by read group name
+ std::vector<BamAlignments> a;
+ a = Sort::GetSortedRegion(reader, region, Sort::ByTag<std::string>("RG"));
+ \endcode
+
+ \param[in] reader BamMultiReader opened on desired BAM files
+ \param[in] region desired region-of-interest
+ \param[in] comp comparison function object
+ \return sorted vector of the region's alignments
+ */
+ template<typename Compare>
+ static std::vector<BamAlignment> GetSortedRegion(BamMultiReader& reader,
+ const BamRegion& region,
+ const Compare& comp = Compare())
+ {
+ // return empty container if unable to find region
+ if ( !reader.HasOpenReaders() ) return std::vector<BamAlignment>();
+ if ( !reader.SetRegion(region) ) return std::vector<BamAlignment>();
+
+ // iterate through region, grabbing alignments
+ BamAlignment al;
+ std::vector<BamAlignment> results;
+ while ( reader.GetNextAlignmentCore(al) )
+ results.push_back(al);
+
+ // sort & return alignments
+ SortAlignments(results, comp);
+ return results;
+ }
+};
} // namespace Algorithms
} // namespace BamTools
// bamtools_global.h (c) 2010 Derek Barnett
// Marth Lab, Department of Biology, Boston College
// ---------------------------------------------------------------------------
-// Last modified: 7 October 2011 (DB)
+// Last modified: 10 October 2011 (DB)
// ---------------------------------------------------------------------------
// Provides the basic definitions for exporting & importing library symbols.
// Also provides some platform-specific rules for definitions.
# endif
#endif // BAMTOOLS_TYPES
+//! \internal
inline void bamtools_noop(void) { }
+/*! \brief Assert definitions
+ \internal
+*/
#ifndef BAMTOOLS_ASSERTS
#define BAMTOOLS_ASSERTS
-# include <cassert>
-# include <stdexcept>
# ifdef NDEBUG
-# define BT_ASSERT_UNREACHABLE bamtools_noop()
+# define BT_ASSERT_UNREACHABLE bamtools_noop()
# define BT_ASSERT_X( condition, message ) bamtools_noop()
# else
-# define BT_ASSERT_UNREACHABLE assert( false )
+# include <cassert>
+# include <stdexcept>
+# define BT_ASSERT_UNREACHABLE assert( false )
# define BT_ASSERT_X( condition, message ) if (!( condition )) { throw std::runtime_error( message ); }
# endif
#endif // BAMTOOLS_ASSERTS
projects / bamtools.git / commitdiff