ngs_server 0.1

data/ext/bamtools/src/api/BamConstants.h

@@ -0,0 +1,127 @@
+// ***************************************************************************
+// BamConstants.h (c) 2011 Derek Barnett
+// Marth Lab, Department of Biology, Boston College
+// ---------------------------------------------------------------------------
+// Last modified: 19 April 2011 (DB)
+// ---------------------------------------------------------------------------
+// Provides basic constants for handling BAM files.
+// ***************************************************************************
+
+#ifndef BAM_CONSTANTS_H
+#define BAM_CONSTANTS_H
+
+#include <string>
+
+/*! \namespace BamTools::Constants
+    \brief Provides basic constants for handling BAM files.
+*/
+
+namespace BamTools {
+namespace Constants {
+
+const int BAM_SIZEOF_INT = 4;
+
+// header magic number
+const char* const  BAM_HEADER_MAGIC = "BAM\1";
+const unsigned int BAM_HEADER_MAGIC_LENGTH = 4;
+
+// BAM alignment core size
+const int BAM_CORE_SIZE = 32;
+const int BAM_CORE_BUFFER_SIZE = 8;
+
+// BAM alignment flags
+const int BAM_ALIGNMENT_PAIRED              = 0x0001;
+const int BAM_ALIGNMENT_PROPER_PAIR         = 0x0002;
+const int BAM_ALIGNMENT_UNMAPPED            = 0x0004;
+const int BAM_ALIGNMENT_MATE_UNMAPPED       = 0x0008;
+const int BAM_ALIGNMENT_REVERSE_STRAND      = 0x0010;
+const int BAM_ALIGNMENT_MATE_REVERSE_STRAND = 0x0020;
+const int BAM_ALIGNMENT_READ_1              = 0x0040;
+const int BAM_ALIGNMENT_READ_2              = 0x0080;
+const int BAM_ALIGNMENT_SECONDARY           = 0x0100;
+const int BAM_ALIGNMENT_QC_FAILED           = 0x0200;
+const int BAM_ALIGNMENT_DUPLICATE           = 0x0400;
+
+// CIGAR constants
+const char* const BAM_CIGAR_LOOKUP = "MIDNSHP=X";
+const int BAM_CIGAR_MATCH    = 0;
+const int BAM_CIGAR_INS      = 1;
+const int BAM_CIGAR_DEL      = 2;
+const int BAM_CIGAR_REFSKIP  = 3;
+const int BAM_CIGAR_SOFTCLIP = 4;
+const int BAM_CIGAR_HARDCLIP = 5;
+const int BAM_CIGAR_PAD      = 6;
+const int BAM_CIGAR_SEQMATCH = 7;
+const int BAM_CIGAR_MISMATCH = 8;
+
+const char BAM_CIGAR_MATCH_CHAR    = 'M';
+const char BAM_CIGAR_INS_CHAR      = 'I';
+const char BAM_CIGAR_DEL_CHAR      = 'D';
+const char BAM_CIGAR_REFSKIP_CHAR  = 'N';
+const char BAM_CIGAR_SOFTCLIP_CHAR = 'S';
+const char BAM_CIGAR_HARDCLIP_CHAR = 'H';
+const char BAM_CIGAR_PAD_CHAR      = 'P';
+const char BAM_CIGAR_SEQMATCH_CHAR = '=';
+const char BAM_CIGAR_MISMATCH_CHAR = 'X';
+
+const int BAM_CIGAR_SHIFT    = 4;
+const int BAM_CIGAR_MASK     = ((1 << BAM_CIGAR_SHIFT) - 1);
+
+// BAM tag types
+const char BAM_TAG_TYPE_ASCII  = 'A';
+const char BAM_TAG_TYPE_UINT8  = 'c';
+const char BAM_TAG_TYPE_INT8   = 'C';
+const char BAM_TAG_TYPE_UINT16 = 's';
+const char BAM_TAG_TYPE_INT16  = 'S';
+const char BAM_TAG_TYPE_UINT32 = 'i';
+const char BAM_TAG_TYPE_INT32  = 'I';
+const char BAM_TAG_TYPE_FLOAT  = 'f';
+const char BAM_TAG_TYPE_STRING = 'Z';
+const char BAM_TAG_TYPE_HEX    = 'H';
+const char BAM_TAG_TYPE_ARRAY  = 'B';
+
+const size_t BAM_TAG_TAGSIZE  = 2;
+const size_t BAM_TAG_TYPESIZE = 1;
+const int BAM_TAG_ARRAYBASE_SIZE = 8;
+
+// DNA bases
+const char* const BAM_DNA_LOOKUP = "=ACMGRSVTWYHKDBN";
+const unsigned char BAM_BASECODE_EQUAL = 0;
+const unsigned char BAM_BASECODE_A     = 1;
+const unsigned char BAM_BASECODE_C     = 2;
+const unsigned char BAM_BASECODE_G     = 4;
+const unsigned char BAM_BASECODE_T     = 8;
+const unsigned char BAM_BASECODE_N     = 15;
+
+const char BAM_DNA_EQUAL   = '=';
+const char BAM_DNA_A       = 'A';
+const char BAM_DNA_C       = 'C';
+const char BAM_DNA_G       = 'G';
+const char BAM_DNA_T       = 'T';
+const char BAM_DNA_N       = 'N';
+const char BAM_DNA_DEL     = '-';
+const char BAM_DNA_PAD     = '*';
+
+// zlib constants
+const int GZIP_ID1   = 31;
+const int GZIP_ID2   = 139;
+const int CM_DEFLATE = 8;
+const int FLG_FEXTRA = 4;
+const int OS_UNKNOWN = 255;
+const int BGZF_XLEN  = 6;
+const int BGZF_ID1   = 66;
+const int BGZF_ID2   = 67;
+const int BGZF_LEN   = 2;
+const int GZIP_WINDOW_BITS    = -15;
+const int Z_DEFAULT_MEM_LEVEL = 8;
+
+// BZGF constants
+const int BGZF_BLOCK_HEADER_LENGTH = 18;
+const int BGZF_BLOCK_FOOTER_LENGTH = 8;
+const int BGZF_MAX_BLOCK_SIZE      = 65536;
+const int BGZF_DEFAULT_BLOCK_SIZE  = 65536;
+
+} // namespace Constants
+} // namespace BamTools
+
+#endif // BAM_CONSTANTS_H

data/ext/bamtools/src/api/BamIndex.h

@@ -0,0 +1,79 @@
+// ***************************************************************************
+// BamIndex.h (c) 2009 Derek Barnett
+// Marth Lab, Department of Biology, Boston College
+// ---------------------------------------------------------------------------
+// Last modified: 5 April 2011 (DB)
+// ---------------------------------------------------------------------------
+// Provides basic BAM index interface
+// ***************************************************************************
+
+#ifndef BAM_INDEX_H
+#define BAM_INDEX_H
+
+#include <api/api_global.h>
+#include <api/BamAux.h>
+#include <string>
+
+namespace BamTools {
+
+namespace Internal {
+    class BamReaderPrivate;
+} // namespace Internal
+
+/*! \class BamTools::BamIndex
+    \brief Provides methods for generating & loading BAM index files.
+
+    This class straddles the line between public API and internal
+    implementation detail. Most client code should never have to use this
+    class directly.
+
+    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 {
+
+    // enums
+    public:
+        // specify index-caching behavior
+        enum IndexCacheMode { FullIndexCaching = 0 // store entire index file contents in memory
+                            , LimitedIndexCaching  // store only index data for current reference
+                            , NoIndexCaching       // do not store any index data between jumps
+                            };
+
+        // list of supported BamIndex types
+        enum IndexType { BAMTOOLS = 0
+                       , STANDARD
+                       };
+  
+    // ctor & dtor
+    public:
+        BamIndex(Internal::BamReaderPrivate* reader) : m_reader(reader) { }
+        virtual ~BamIndex(void) { }
+        
+    // index interface
+    public:
+        // builds index from associated BAM file & writes out to index file
+        virtual bool Create(void) =0; // creates index file from BAM file
+        // returns whether reference has alignments or no
+        virtual bool HasAlignments(const int& referenceID) const =0;
+        // attempts to use index data to jump to @region, returns success/fail
+        // a "successful" jump indicates no error, but not whether this region has data
+        //   * thus, the method sets a flag to indicate whether there are alignments
+        //     available after the jump position
+        virtual bool Jump(const BamTools::BamRegion& region, bool* hasAlignmentsInRegion) =0;
+        // loads existing data from file into memory
+        virtual bool Load(const std::string& filename) =0;
+        // change the index caching behavior
+        virtual void SetCacheMode(const BamIndex::IndexCacheMode& mode) =0;
+
+    // data members
+    protected:
+        Internal::BamReaderPrivate* m_reader; // copy, not ownedprivate:
+};
+
+} // namespace BamTools
+
+#endif // BAM_INDEX_H

data/ext/bamtools/src/api/BamMultiReader.cpp

@@ -0,0 +1,395 @@
+// ***************************************************************************
+// BamMultiReader.cpp (c) 2010 Erik Garrison, Derek Barnett
+// Marth Lab, Department of Biology, Boston College
+// ---------------------------------------------------------------------------
+// Last modified: 15 March 2011 (DB)
+// ---------------------------------------------------------------------------
+// Convenience class for reading multiple BAM files.
+//
+// This functionality allows applications to work on very large sets of files
+// without requiring intermediate merge, sort, and index steps for each file
+// subset.  It also improves the performance of our merge system as it
+// precludes the need to sort merged files.
+// ***************************************************************************
+
+#include <api/BamMultiReader.h>
+#include <api/internal/BamMultiReader_p.h>
+using namespace BamTools;
+
+#include <string>
+#include <vector>
+using namespace std;
+
+/*! \class BamTools::BamReader
+    \brief Convenience class for reading multiple BAM files.
+*/
+
+/*! \fn BamMultiReader::BamMultiReader(void)
+    \brief constructor
+*/
+BamMultiReader::BamMultiReader(void)
+    : d(new Internal::BamMultiReaderPrivate)
+{ }
+
+/*! \fn BamMultiReader::~BamMultiReader(void)
+    \brief destructor
+*/
+BamMultiReader::~BamMultiReader(void) {
+    delete d;
+    d = 0;
+}
+
+/*! \fn void BamMultiReader::Close(void)
+    \brief Closes all open BAM files.
+
+    Also clears out all header and reference data.
+
+    \sa CloseFile(), IsOpen(), Open(), BamReader::Close()
+*/
+void BamMultiReader::Close(void) {
+    d->Close();
+}
+
+/*! \fn void BamMultiReader::CloseFile(const std::string& filename)
+    \brief Closes requested BAM file.
+
+    Leaves any other file(s) open, along with header and reference data.
+
+    \sa Close(), IsOpen(), Open(), BamReader::Close()
+*/
+void BamMultiReader::CloseFile(const std::string& filename) {
+    d->CloseFile(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
+    \return \c true if index files created OK
+    \sa LocateIndexes(), OpenIndexes(), BamReader::CreateIndex()
+*/
+bool BamMultiReader::CreateIndexes(const BamIndex::IndexType& type) {
+    return d->CreateIndexes(type);
+}
+
+/*! \fn const std::vector<std::string> BamMultiReader::Filenames(void) const
+    \brief Returns list of filenames for all open BAM files.
+
+    Retrieved filenames will contain whatever was passed via Open().
+    If you need full directory paths here, be sure to include them
+    when you open the BAM files.
+
+    \returns names of open BAM files. If no files are open, returns an empty vector.
+    \sa IsOpen(), BamReader::GetFilename()
+*/
+const std::vector<std::string> BamMultiReader::Filenames(void) const {
+    return d->Filenames();
+}
+
+/*! \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,
+    your modified header text can be used in conjunction with BamWriter
+    to generate a new BAM file with the appropriate header information.
+
+    \returns header data wrapped in SamHeader object
+    \sa GetHeaderText(), BamReader::GetHeader()
+*/
+SamHeader BamMultiReader::GetHeader(void) const {
+    return d->GetHeader();
+}
+
+/*! \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,
+    your modified header text can be used in conjunction with BamWriter
+    to generate a new BAM file with the appropriate header information.
+
+    \returns SAM-formatted header text
+    \sa GetHeader(), BamReader::GetHeaderText()
+*/
+std::string BamMultiReader::GetHeaderText(void) const {
+    return d->GetHeaderText();
+}
+
+/*! \fn bool BamMultiReader::GetNextAlignment(BamAlignment& alignment)
+    \brief Retrieves next available alignment.
+
+    Equivalent to BamReader::GetNextAlignment() with respect to what is a valid
+    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.
+
+    \param alignment destination for alignment record data
+    \returns \c true if a valid alignment was found
+    \sa GetNextAlignmentCore(), SetRegion(), SetSortOrder(), BamReader::GetNextAlignment()
+*/
+bool BamMultiReader::GetNextAlignment(BamAlignment& nextAlignment) {
+    return d->GetNextAlignment(nextAlignment);
+}
+
+/*! \fn bool BamMultiReader::GetNextAlignmentCore(BamAlignment& alignment)
+    \brief Retrieves next available alignment.
+
+    Equivalent to BamReader::GetNextAlignmentCore() with respect to what is a valid
+    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.
+
+    \param alignment destination for alignment record data
+    \returns \c true if a valid alignment was found
+    \sa GetNextAlignment(), SetRegion(), SetSortOrder(), BamReader::GetNextAlignmentCore()
+*/
+bool BamMultiReader::GetNextAlignmentCore(BamAlignment& nextAlignment) {
+    return d->GetNextAlignmentCore(nextAlignment);
+}
+
+/*! \fn int BamMultiReader::GetReferenceCount(void) const
+    \brief Returns number of reference sequences.
+    \sa BamReader::GetReferenceCount()
+*/
+int BamMultiReader::GetReferenceCount(void) const {
+    return d->GetReferenceCount();
+}
+
+/*! \fn const RefVector& BamMultiReader::GetReferenceData(void) const
+    \brief Returns all reference sequence entries.
+    \sa RefData, BamReader::GetReferenceData()
+*/
+const BamTools::RefVector BamMultiReader::GetReferenceData(void) const {
+    return d->GetReferenceData();
+}
+
+/*! \fn int BamMultiReader::GetReferenceID(const std::string& refName) const
+    \brief Returns the ID of the reference with this name.
+
+    If \a refName is not found, returns -1.
+
+    \sa BamReader::GetReferenceID()
+*/
+int BamMultiReader::GetReferenceID(const std::string& refName) const {
+    return d->GetReferenceID(refName);
+}
+
+/*! \fn bool BamMultiReader::HasIndexes(void) const
+    \brief Returns \c true if all BAM files have index data available.
+    \sa BamReader::HasIndex()
+*/
+bool BamMultiReader::HasIndexes(void) const {
+    return d->HasIndexes();
+}
+
+/*! \fn bool BamMultiReader::HasOpenReaders(void) const
+    \brief Returns \c true if there are any open BAM files.
+*/
+bool BamMultiReader::HasOpenReaders(void) const {
+    return d->HasOpenReaders();
+}
+
+/*! \fn bool BamMultiReader::IsIndexLoaded(void) const
+    \brief Returns \c true if all BAM files have index data available.
+
+    \deprecated Instead use HasIndexes()
+    \cond
+    See explanation in BamReader.cpp for more details on the deprecation decision.
+    \endcond
+*/
+
+bool BamMultiReader::IsIndexLoaded(void) const {
+    return d->HasIndexes();
+}
+
+/*! \fn bool BamMultiReader::Jump(int refID, int position)
+    \brief Performs a random-access jump within current BAM files.
+
+    This is a convenience method, equivalent to calling SetRegion()
+    with only a left boundary specified.
+
+    \returns \c true if jump was successful
+    \sa HasIndex(), BamReader::Jump()
+*/
+
+bool BamMultiReader::Jump(int refID, int position) {
+    return d->Jump(refID, position);
+}
+
+/*! \fn bool BamMultiReader::LocateIndexes(const BamIndex::IndexType& preferredType)
+    \brief Looks for index files that match current BAM files.
+
+    Use this function when you need index files, and perhaps have a
+    preferred index format, but do not depend heavily on which indexes
+    actually get loaded at runtime.
+
+    For each BAM file, this function will defer to your \a preferredType
+    whenever possible. However, if an index file of \a preferredType can
+    not be found, then it will look for any other index file that matches
+    that BAM file.
+
+    An example case would look this:
+    \code
+
+        BamMultiReader reader;
+        // 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
+
+        // do interesting stuff
+        // ...
+
+    \endcode
+
+    If you want precise control over which index files are loaded, use OpenIndexes()
+    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
+    \returns \c true if index files could be found for \b ALL open BAM files
+    \sa BamReader::LocateIndex()
+*/
+bool BamMultiReader::LocateIndexes(const BamIndex::IndexType& preferredType) {
+    return d->LocateIndexes(preferredType);
+}
+
+/*! \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.
+
+    \param filenames list of BAM filenames to open
+    \returns \c true if BAM files were opened successfully
+    \sa Close(), HasOpenReaders(), OpenFile(), OpenIndexes(), BamReader::Open()
+*/
+bool BamMultiReader::Open(const std::vector<std::string>& filenames) {
+    return d->Open(filenames);
+}
+
+/*! \fn bool BamMultiReader::OpenFile(const std::string& filename)
+    \brief Opens a single BAM file.
+
+    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.
+
+    \param filename BAM filename to open
+    \returns \c true if BAM file was opened successfully
+    \sa Close(), HasOpenReaders(), Open(), OpenIndexes(), BamReader::Open()
+*/
+bool BamMultiReader::OpenFile(const std::string& filename) {
+    return d->OpenFile(filename);
+}
+
+/*! \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
+    BAM files passed to Open().
+
+    \param 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()
+*/
+bool BamMultiReader::OpenIndexes(const std::vector<std::string>& indexFilenames) {
+    return d->OpenIndexes(indexFilenames);
+}
+
+/*! \fn void BamMultiReader::PrintFilenames(void) const
+    \brief Convenience method for printing filenames to stdout.
+    \deprecated Doesn't really belong as an API function. Clients should
+                determine how the data is reported.
+    \sa Filenames(), BamReader::GetFilename()
+*/
+void BamMultiReader::PrintFilenames(void) const {
+    d->PrintFilenames();
+}
+
+/*! \fn bool BamMultiReader::Rewind(void)
+    \brief Returns the internal file pointers to the beginning of alignment records.
+
+    Useful for performing multiple sequential passes through BAM files.
+    Calling this function clears any prior region that may have been set.
+
+    \returns \c true if rewind operation was successful
+    \sa Jump(), SetRegion(), BamReader::Rewind()
+*/
+bool BamMultiReader::Rewind(void) {
+    return d->Rewind();
+}
+
+/*! \fn void BamMultiReader::SetIndexCacheMode(const BamIndex::IndexCacheMode& mode)
+    \brief Changes the caching behavior of the index data.
+
+    Default mode is BamIndex::LimitedIndexCaching.
+
+    \param 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) {
+    d->SetIndexCacheMode(mode);
+}
+
+/*! \fn bool BamMultiReader::SetRegion(const BamRegion& region)
+    \brief Sets a target region of interest
+
+    Equivalent to calling BamReader::SetRegion() on all open BAM files.
+
+    \param region desired region-of-interest to activate
+    \returns \c true if ALL readers set the region successfully
+    \sa HasIndexes(), Jump(), BamReader::SetRegion()
+*/
+bool BamMultiReader::SetRegion(const BamRegion& region) {
+    return d->SetRegion(region);
+}
+
+/*! \fn bool BamMultiReader::SetRegion(const int& leftRefID,
+                                       const int& leftPosition,
+                                       const int& rightRefID,
+                                       const int& rightPosition)
+    \brief Sets a target region of interest
+
+    This is an overloaded function.
+
+    Equivalent to calling BamReader::SetRegion() on all open BAM files.
+
+    \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
+
+    \returns \c true if ALL readers set the region successfully
+    \sa HasIndexes(), Jump(), BamReader::SetRegion()
+*/
+bool BamMultiReader::SetRegion(const int& leftRefID,
+                               const int& leftPosition,
+                               const int& rightRefID,
+                               const int& rightPosition)
+{
+    BamRegion region(leftRefID, leftPosition, rightRefID, rightPosition);
+    return d->SetRegion(region);
+}
+
+/*! \fn void BamMultiReader::SetSortOrder(const SortOrder& order)
+    \brief Sets the expected sorting order for reading across multiple BAM files.
+
+    Default is BamMultiReader::SortedByPosition.
+
+    The SortOrder determines how the reader determines which alignment is "next"
+    from among its open readers.
+
+    \param order expected sort order
+*/
+void BamMultiReader::SetSortOrder(const SortOrder& order) {
+    d->SetSortOrder(order);
+}