-// ***************************************************************************\r
-// BamMultiReader.h (c) 2010 Erik Garrison\r
-// Marth Lab, Department of Biology, Boston College\r
-// All rights reserved.\r
-// ---------------------------------------------------------------------------\r
-// Last modified: 3 September 2010 (DB)\r
-// ---------------------------------------------------------------------------\r
-// Functionality for simultaneously reading multiple BAM files\r
-// ***************************************************************************\r
-\r
-#ifndef BAMMULTIREADER_H\r
-#define BAMMULTIREADER_H\r
-\r
-// C++ includes\r
-#include <string>\r
-#include <map>\r
-#include <utility> // for pair\r
-#include <sstream>\r
-\r
-using namespace std;\r
-\r
-// BamTools includes\r
-#include "BamAux.h"\r
-#include "BamReader.h"\r
-\r
-namespace BamTools {\r
-\r
-// index mapping reference/position pairings to bamreaders and their alignments\r
-typedef multimap<pair<int, int>, pair<BamReader*, BamAlignment*> > AlignmentIndex;\r
-\r
-\r
-class BamMultiReader {\r
-\r
- // constructor / destructor\r
- public:\r
- BamMultiReader(void);\r
- ~BamMultiReader(void);\r
-\r
- // public interface\r
- public:\r
-\r
- // positioning\r
- int CurrentRefID;\r
- int CurrentLeft;\r
-\r
- // region under analysis, specified using SetRegion\r
- BamRegion Region;\r
-\r
- // ----------------------\r
- // BAM file operations\r
- // ----------------------\r
-\r
- // close BAM files\r
- void Close(void);\r
-\r
- // opens BAM files (and optional BAM index files, if provided)\r
- // @openIndexes - triggers index opening, useful for suppressing\r
- // error messages during merging of files in which we may not have\r
- // indexes.\r
- // @coreMode - setup our first alignments using GetNextAlignmentCore();\r
- // also useful for merging\r
- // @preferStandardIndex - look for standard BAM index ".bai" first. If false, \r
- // will look for BamTools index ".bti". \r
- bool Open(const vector<string> filenames, bool openIndexes = true, bool coreMode = false, bool preferStandardIndex = true);\r
-\r
- // returns whether underlying BAM readers ALL have an index loaded\r
- // this is useful to indicate whether Jump() or SetRegion() are possible\r
- bool IsIndexLoaded(void) const;\r
- \r
- // performs random-access jump to reference, position\r
- bool Jump(int refID, int position = 0);\r
-\r
- // sets the target region\r
- bool SetRegion(const BamRegion& region);\r
- bool SetRegion(const int&, const int&, const int&, const int&); // convenience function to above\r
-\r
- // returns file pointers to beginning of alignments\r
- bool Rewind(void);\r
-\r
- // ----------------------\r
- // access alignment data\r
- // ----------------------\r
- // updates the reference id marker to match the lower limit of our readers\r
- void UpdateReferenceID(void);\r
-\r
- // retrieves next available alignment (returns success/fail) from all files\r
- bool GetNextAlignment(BamAlignment&);\r
- // retrieves next available alignment (returns success/fail) from all files\r
- // and populates the support data with information about the alignment\r
- // *** BUT DOES NOT PARSE CHARACTER DATA FROM THE ALIGNMENT\r
- bool GetNextAlignmentCore(BamAlignment&);\r
- // ... should this be private?\r
- bool HasOpenReaders(void);\r
-\r
- // ----------------------\r
- // access auxiliary data\r
- // ----------------------\r
-\r
- // returns unified SAM header text for all files\r
- const string GetHeaderText(void) const;\r
- // returns number of reference sequences\r
- const int GetReferenceCount(void) const;\r
- // returns vector of reference objects\r
- const BamTools::RefVector GetReferenceData(void) const;\r
- // returns reference id (used for BamMultiReader::Jump()) for the given reference name\r
- const int GetReferenceID(const std::string& refName) const;\r
- // validates that we have a congruent set of BAM files that are aligned against the same reference sequences\r
- void ValidateReaders() const;\r
-\r
- // ----------------------\r
- // BAM index operations\r
- // ----------------------\r
-\r
- // creates index for BAM files which lack them, saves to files (default = bamFilename + ".bai")\r
- bool CreateIndexes(bool useDefaultIndex = true);\r
-\r
- //const int GetReferenceID(const string& refName) const;\r
-\r
- // utility\r
- void PrintFilenames(void);\r
- void DumpAlignmentIndex(void);\r
- void UpdateAlignments(void); // updates our alignment cache\r
-\r
- // private implementation\r
- private:\r
-\r
- // the set of readers and alignments which we operate on, maintained throughout the life of this class\r
- vector<pair<BamReader*, BamAlignment*> > readers;\r
-\r
- // readers and alignments sorted by reference id and position, to keep track of the lowest (next) alignment\r
- // when a reader reaches EOF, its entry is removed from this index\r
- AlignmentIndex alignments;\r
-\r
- vector<string> fileNames;\r
-};\r
-\r
-} // namespace BamTools\r
-\r
-#endif // BAMMULTIREADER_H\r
+// ***************************************************************************
+// BamMultiReader.h (c) 2010 Erik Garrison, Derek Barnett
+// Marth Lab, Department of Biology, Boston College
+// ---------------------------------------------------------------------------
+// Last modified: 14 January 2013 (DB)
+// ---------------------------------------------------------------------------
+// Convenience class for reading multiple BAM files.
+// ***************************************************************************
+
+#ifndef BAMMULTIREADER_H
+#define BAMMULTIREADER_H
+
+#include "api/api_global.h"
+#include "api/BamReader.h"
+#include <map>
+#include <sstream>
+#include <string>
+#include <utility>
+
+namespace BamTools {
+
+namespace Internal {
+ class BamMultiReaderPrivate;
+} // namespace Internal
+
+class API_EXPORT BamMultiReader {
+
+ // enums
+ public:
+ // possible merge order strategies
+ enum MergeOrder { RoundRobinMerge = 0
+ , MergeByCoordinate
+ , MergeByName
+ };
+
+ // constructor / destructor
+ public:
+ BamMultiReader(void);
+ ~BamMultiReader(void);
+
+ // public interface
+ public:
+
+ // ----------------------
+ // BAM file operations
+ // ----------------------
+
+ // closes all open BAM files
+ bool Close(void);
+ // close only the requested BAM file
+ bool CloseFile(const std::string& filename);
+ // returns list of filenames for all open BAM files
+ const std::vector<std::string> Filenames(void) const;
+ // returns curent merge order strategy
+ BamMultiReader::MergeOrder GetMergeOrder(void) const;
+ // returns true if multireader has any open BAM files
+ bool HasOpenReaders(void) const;
+ // performs random-access jump within current BAM files
+ bool Jump(int refID, int position = 0);
+ // opens BAM files
+ bool Open(const std::vector<std::string>& filenames);
+ // opens a single BAM file, adding to any other current BAM files
+ bool OpenFile(const std::string& filename);
+ // returns file pointers to beginning of alignments
+ bool Rewind(void);
+ // sets an explicit merge order, regardless of the BAM files' SO header tag
+ void SetExplicitMergeOrder(BamMultiReader::MergeOrder order);
+ // sets the target region of interest
+ bool SetRegion(const BamRegion& region);
+ // sets the target region of interest
+ bool SetRegion(const int& leftRefID,
+ const int& leftPosition,
+ const int& rightRefID,
+ const int& rightPosition);
+
+ // ----------------------
+ // access alignment data
+ // ----------------------
+
+ // retrieves next available alignment
+ bool GetNextAlignment(BamAlignment& alignment);
+ // retrieves next available alignment (without populating the alignment's string data fields)
+ bool GetNextAlignmentCore(BamAlignment& alignment);
+
+ // ----------------------
+ // access auxiliary data
+ // ----------------------
+
+ // returns unified SAM header for all files
+ SamHeader GetHeader(void) const;
+ // returns unified SAM header text for all files
+ std::string GetHeaderText(void) const;
+ // returns number of reference sequences
+ int GetReferenceCount(void) const;
+ // returns all reference sequence entries.
+ const BamTools::RefVector GetReferenceData(void) const;
+ // returns the ID of the reference with this name.
+ int GetReferenceID(const std::string& refName) const;
+
+ // ----------------------
+ // BAM index operations
+ // ----------------------
+
+ // creates index files for current BAM files
+ bool CreateIndexes(const BamIndex::IndexType& type = BamIndex::STANDARD);
+ // returns true if all BAM files have index data available
+ bool HasIndexes(void) const;
+ // looks for index files that match current BAM files
+ bool LocateIndexes(const BamIndex::IndexType& preferredType = BamIndex::STANDARD);
+ // opens index files for current BAM files.
+ bool OpenIndexes(const std::vector<std::string>& indexFilenames);
+
+ // ----------------------
+ // error handling
+ // ----------------------
+
+ // returns a human-readable description of the last error that occurred
+ std::string GetErrorString(void) const;
+
+ // private implementation
+ private:
+ Internal::BamMultiReaderPrivate* d;
+};
+
+} // namespace BamTools
+
+#endif // BAMMULTIREADER_H
projects / bamtools.git / blobdiff