1 // ***************************************************************************
\r
2 // BamWriter.cpp (c) 2009 Michael Str�mberg, Derek Barnett
\r
3 // Marth Lab, Department of Biology, Boston College
\r
4 // ---------------------------------------------------------------------------
\r
5 // Last modified: 25 October 2011 (DB)
\r
6 // ---------------------------------------------------------------------------
\r
7 // Provides the basic functionality for producing BAM files
\r
8 // ***************************************************************************
\r
10 #include "api/BamAlignment.h"
\r
11 #include "api/BamWriter.h"
\r
12 #include "api/SamHeader.h"
\r
13 #include "api/internal/bam/BamWriter_p.h"
\r
14 using namespace BamTools;
\r
15 using namespace BamTools::Internal;
\r
16 using namespace std;
\r
18 /*! \class BamTools::BamWriter
\r
19 \brief Provides write access for generating BAM files.
\r
21 /*! \enum BamTools::BamWriter::CompressionMode
\r
22 \brief This enum describes the compression behaviors for output BAM files.
\r
24 /*! \var BamWriter::CompressionMode BamWriter::Compressed
\r
25 \brief Use normal BAM compression
\r
27 /*! \var BamWriter::CompressionMode BamWriter::Uncompressed
\r
28 \brief Disable BAM compression
\r
30 Useful in situations where the BAM data is streamed (e.g. piping).
\r
31 It would be wasteful to compress, and then immediately decompress
\r
35 /*! \fn BamWriter::BamWriter(void)
\r
38 BamWriter::BamWriter(void)
\r
39 : d(new BamWriterPrivate)
\r
42 /*! \fn BamWriter::~BamWriter(void)
\r
45 BamWriter::~BamWriter(void) {
\r
50 /*! \fn BamWriter::Close(void)
\r
51 \brief Closes the current BAM file.
\r
54 void BamWriter::Close(void) {
\r
58 /*! \fn std::string BamWriter::GetErrorString(void) const
\r
59 \brief Returns a human-readable description of the last error that occurred
\r
61 This method allows elimination of STDERR pollution. Developers of client code
\r
62 may choose how the messages are displayed to the user, if at all.
\r
64 \return error description
\r
66 std::string BamWriter::GetErrorString(void) const {
\r
67 return d->GetErrorString();
\r
70 /*! \fn bool BamWriter::IsOpen(void) const
\r
71 \brief Returns \c true if BAM file is open for writing.
\r
74 bool BamWriter::IsOpen(void) const {
\r
78 /*! \fn bool BamWriter::Open(const std::string& filename,
\r
79 const std::string& samHeaderText,
\r
80 const RefVector& referenceSequences)
\r
81 \brief Opens a BAM file for writing.
\r
83 Will overwrite the BAM file if it already exists.
\r
85 \param[in] filename name of output BAM file
\r
86 \param[in] samHeaderText header data, as SAM-formatted string
\r
87 \param[in] referenceSequences list of reference entries
\r
89 \return \c true if opened successfully
\r
90 \sa Close(), IsOpen(), BamReader::GetHeaderText(), BamReader::GetReferenceData()
\r
92 bool BamWriter::Open(const std::string& filename,
\r
93 const std::string& samHeaderText,
\r
94 const RefVector& referenceSequences)
\r
96 return d->Open(filename, samHeaderText, referenceSequences);
\r
99 /*! \fn bool BamWriter::Open(const std::string& filename,
\r
100 const SamHeader& samHeader,
\r
101 const RefVector& referenceSequences)
\r
102 \brief Opens a BAM file for writing.
\r
104 This is an overloaded function.
\r
106 Will overwrite the BAM file if it already exists.
\r
108 \param[in] filename name of output BAM file
\r
109 \param[in] samHeader header data, wrapped in SamHeader object
\r
110 \param[in] referenceSequences list of reference entries
\r
112 \return \c true if opened successfully
\r
113 \sa Close(), IsOpen(), BamReader::GetHeader(), BamReader::GetReferenceData()
\r
115 bool BamWriter::Open(const std::string& filename,
\r
116 const SamHeader& samHeader,
\r
117 const RefVector& referenceSequences)
\r
119 return d->Open(filename, samHeader.ToString(), referenceSequences);
\r
122 /*! \fn void BamWriter::SaveAlignment(const BamAlignment& alignment)
\r
123 \brief Saves an alignment to the BAM file.
\r
125 \param[in] alignment BamAlignment record to save
\r
126 \sa BamReader::GetNextAlignment(), BamReader::GetNextAlignmentCore()
\r
128 bool BamWriter::SaveAlignment(const BamAlignment& alignment) {
\r
129 return d->SaveAlignment(alignment);
\r
132 /*! \fn void BamWriter::SetCompressionMode(const BamWriter::CompressionMode& compressionMode)
\r
133 \brief Sets the output compression mode.
\r
135 Default mode is BamWriter::Compressed.
\r
137 \note Changing the compression mode is disabled on open files (i.e. the request will
\r
138 be ignored). Be sure to call this function before opening the BAM file.
\r
142 writer.SetCompressionMode(BamWriter::Uncompressed);
\r
143 writer.Open( ... );
\r
147 \param[in] compressionMode desired output compression behavior
\r
148 \sa IsOpen(), Open()
\r
150 void BamWriter::SetCompressionMode(const BamWriter::CompressionMode& compressionMode) {
\r
151 d->SetWriteCompressed( compressionMode == BamWriter::Compressed );
\r