src/api/BamWriter.cpp

   1 // ***************************************************************************\r
   2 // BamWriter.cpp (c) 2009 Michael Str�mberg, Derek Barnett\r
   3 // Marth Lab, Department of Biology, Boston College\r
   4 // All rights reserved.\r
   5 // ---------------------------------------------------------------------------\r
   6 // Last modified: 4 March 2011 (DB)\r
   7 // ---------------------------------------------------------------------------\r
   8 // Provides the basic functionality for producing BAM files\r
   9 // ***************************************************************************\r
  10 \r
  11 #include <api/BamAlignment.h>\r
  12 #include <api/BamWriter.h>\r
  13 #include <api/SamHeader.h>\r
  14 #include <api/internal/BamWriter_p.h>\r
  15 using namespace BamTools;\r
  16 using namespace BamTools::Internal;\r
  17 \r
  18 #include <iostream>\r
  19 using namespace std;\r
  20 \r
  21 /*! \class BamTools::BamWriter\r
  22     \brief Provides write access for generating BAM files.\r
  23 */\r
  24 /*! \enum BamTools::BamWriter::CompressionMode\r
  25     \brief This enum describes the compression behaviors for output BAM files.\r
  26 */\r
  27 /*! \var BamWriter::CompressionMode BamWriter::Compressed\r
  28     \brief Use normal BAM compression\r
  29 */\r
  30 /*! \var BamWriter::CompressionMode BamWriter::Uncompressed\r
  31     \brief Disable BAM compression\r
  32 \r
  33     Useful in situations where the BAM data is streamed (e.g. piping).\r
  34     It would be wasteful to compress, and then immediately decompress\r
  35     the data.\r
  36 */\r
  37 \r
  38 /*! \fn BamWriter::BamWriter(void)\r
  39     \brief constructor\r
  40 */\r
  41 BamWriter::BamWriter(void)\r
  42     : d(new BamWriterPrivate)\r
  43 { }\r
  44 \r
  45 /*! \fn BamWriter::~BamWriter(void)\r
  46     \brief destructor\r
  47 */\r
  48 BamWriter::~BamWriter(void) {\r
  49     delete d;\r
  50     d = 0;\r
  51 }\r
  52 \r
  53 /*! \fn BamWriter::Close(void)\r
  54     \brief Closes the current BAM file.\r
  55     \sa Open()\r
  56 */\r
  57 void BamWriter::Close(void) {\r
  58     d->Close();\r
  59 }\r
  60 \r
  61 /*! \fn bool BamWriter::IsOpen(void) const\r
  62     \brief Returns \c true if BAM file is open for writing.\r
  63     \sa Open()\r
  64 */\r
  65 bool BamWriter::IsOpen(void) const {\r
  66     return d->IsOpen();\r
  67 }\r
  68 \r
  69 /*! \fn bool BamWriter::Open(const std::string& filename,\r
  70                              const std::string& samHeaderText,\r
  71                              const RefVector& referenceSequences)\r
  72     \brief Opens a BAM file for writing.\r
  73 \r
  74     Will overwrite the BAM file if it already exists.\r
  75 \r
  76     \param filename           name of output BAM file\r
  77     \param samHeaderText      header data, as SAM-formatted string\r
  78     \param referenceSequences list of reference entries\r
  79 \r
  80     \return \c true if opened successfully\r
  81     \sa Close(), IsOpen(), BamReader::GetHeaderText(), BamReader::GetReferenceData()\r
  82 */\r
  83 bool BamWriter::Open(const std::string& filename,\r
  84                      const std::string& samHeaderText,\r
  85                      const RefVector& referenceSequences)\r
  86 {\r
  87     return d->Open(filename, samHeaderText, referenceSequences);\r
  88 }\r
  89 \r
  90 /*! \fn bool BamWriter::Open(const std::string& filename,\r
  91                              const SamHeader& samHeader,\r
  92                              const RefVector& referenceSequences)\r
  93     \brief Opens a BAM file for writing.\r
  94 \r
  95     This is an overloaded function.\r
  96 \r
  97     Will overwrite the BAM file if it already exists.\r
  98 \r
  99     \param filename           name of output BAM file\r
 100     \param samHeader          header data, wrapped in SamHeader object\r
 101     \param referenceSequences list of reference entries\r
 102 \r
 103     \return \c true if opened successfully\r
 104     \sa Close(), IsOpen(), BamReader::GetHeader(), BamReader::GetReferenceData()\r
 105 */\r
 106 bool BamWriter::Open(const std::string& filename,\r
 107                      const SamHeader& samHeader,\r
 108                      const RefVector& referenceSequences)\r
 109 {\r
 110     return d->Open(filename, samHeader.ToString(), referenceSequences);\r
 111 }\r
 112 \r
 113 /*! \fn void BamWriter::SaveAlignment(const BamAlignment& alignment)\r
 114     \brief Saves an alignment to the BAM file.\r
 115 \r
 116     \param alignment BamAlignment record to save\r
 117     \sa BamReader::GetNextAlignment(), BamReader::GetNextAlignmentCore()\r
 118 */\r
 119 void BamWriter::SaveAlignment(const BamAlignment& alignment) {\r
 120     d->SaveAlignment(alignment);\r
 121 }\r
 122 \r
 123 /*! \fn void BamWriter::SetCompressionMode(const CompressionMode& compressionMode)\r
 124     \brief Sets the output compression mode.\r
 125 \r
 126     Default mode is BamWriter::Compressed.\r
 127 \r
 128     N.B. - Changing the compression mode is disabled on open files (i.e. the request will be ignored).\r
 129     Be sure to call this function before opening the BAM file.\r
 130 \r
 131     \code\r
 132         BamWriter writer;\r
 133         writer.SetCompressionMode(BamWriter::Uncompressed);\r
 134         writer.Open( ... );\r
 135         // ...\r
 136     \endcode\r
 137 \r
 138     \param compressionMode desired output compression behavior\r
 139     \sa IsOpen(), Open()\r
 140 */\r
 141 void BamWriter::SetCompressionMode(const CompressionMode& compressionMode) {\r
 142     d->SetWriteCompressed( compressionMode == BamWriter::Compressed );\r
 143 }\r