pbbam Documentation Release Derek Barnett

Transcription

1 pbbam Documentation Release Derek Barnett Nov 16, 2017

2

3 Contents 1 Getting Started 3 2 C++ API Reference 7 3 Additional Languages Command Line Utilities 213 i

4 ii

5 As of the 3.0 release of SMRTanalysis, PacBio is embracing the industry standard BAM format for (both aligned and unaligned) basecall data files. We have also formulated a BAM companion file format (bam.pbi) enabling fast access to a richer set of per-read information as well as compatibility for software built around the legacy cmp.h5 format. The pbbam software package provides components to create, query, & edit PacBio BAM files and associated indices. These components include a core C++ library, bindings for additional languages, and command-line utilities. Contents 1

6 2 Contents

7 CHAPTER 1 Getting Started 1.1 Requirements These components will almost certainly already be on your system. gcc (4.8+) OR clang (v3.1+) pthreads zlib Double-check your compiler version, to be sure it is compatible. $ g++ -v $ clang -v Additional requirements: Boost (1.55+) CMake (3.0+) Google Test htslib (1.3.1+) For additional languages: SWIG (3.0.5+) For building API documentation locally: Doxygen For maximal convenience, install htslib and google test in the same parent directory you plan to install pbbam. 3

8 1.2 Clone & Build Note: The following steps are for building the C++ library and command-line utilities. If you are integrating pbbam into a C#, Python, or R project, take a look at the instructions for additional languages. The basic steps for obtaining pbbam and building it from source are as follows: Build and install htslib, per the project s instructions (or on OSX brew install htslib ) Clone You should first clone the repository: $ git clone $ cd pbbam Building with CMake When building with CMake, create a separate build directory: $ mkdir build $ cd build $ cmake.. $ make -j 4 # compiles using 4 threads Output: Library : <pbbam_root>/lib Headers : <pbbam_root>/include Utilities : <pbbam_root>/bin You may need to set a few options on the cmake command, to point to dependencies install locations. Common installation-related options include: GTEST_SRC_DIR Add these using the -D argument, like this: $ cmake.. -DGTEST_SRC_DIR="path/to/googletest" To run the test suite, run: $ make test To build a local copy of the (Doxygen-style) API documentation, run: $ make doc And then open <pbbam_root>/docs/html/index.html in your favorite browser. 4 Chapter 1. Getting Started

9 1.2.3 Building with Meson Building with Meson is generally faster and more versatile. Meson strictly requires building out of source: $ mkdir build $ cd build $ meson --prefix /my/install/prefix -Denable-tests=true.. $ ninja where ninja will by default utilize a number of threads for compilation equal to the number of logical cores on your system. Here -Denable-tests=true enables pulling in dependencies for testing. In order to run the test suite, run: $ ninja test If you wish to install pbbam, run: $ ninja install and ninja will install pbbam to /my/install/prefix. 1.3 Integrate For CMake-based projects that will ship with or otherwise live alongside pbbam, you can use the approach described here. Before defining your library or executable, add the following: add_subdirectory(<path/to/pbbam> external/build/pbbam) When it s time to run make this will ensure that pbbam will be built, inside your own project s build directory. After this point in the CMakeLists.txt file(s), a few variables will be available that can be used to setup your include paths and library linking targets: include_directories( ${PacBioBAM_INCLUDE_DIRS} # other includes that your project needs ) add_executable(foo) target_link_libraries(foo ${PacBioBAM_LIBRARIES} # other libs that your project needs ) If you re using something other than CMake for your project s build system, then you need to point it to pbbam s include directory & library, as well as those of its dependencies (primarily htslib). If you built and installed pbbam using Meson, pkg-config files will be available to be consumed by projects wishing to utilize pbbam. Autoconf, CMake, Waf, SCons and Meson all have means to determine dependency information from pkg-config files Integrate 5

10 6 Chapter 1. Getting Started

11 CHAPTER 2 C++ API Reference Watch this space for more recipes & how-tos. 2.1 Accuracy #include <pbbam/accuracy.h> class PacBio::BAM::Accuracy The Accuracy class represents the expected accuracy of a BamRecord. Values are clamped to fall within [0,1]. Constructors & Related Methods Accuracy(float accuracy) Constructs an Accuracy object from a floating-point number. Note This is not an explicit ctor, to make it as easy as possible to use in numeric operations. We really just want to make sure that the acceptable range is respected. Accuracy(const Accuracy &other) Accuracy(Accuracy &&other) Accuracy &operator=(const Accuracy &other) Accuracy &operator=(accuracy &&other) ~Accuracy() 7

12 Public Functions operator float() const Return Accuracy as float primitive Public Static Attributes const float MIN Minimum valid accuracy value [0.0]. const float MAX Maximum valid accuracy value [1.0]. 2.2 AlignmentPrinter #include <pbbam/alignmentprinter.h> class PacBio::BAM::AlignmentPrinter The AlignmentPrinter class pretty-prints an alignment with respect to its associated reference sequence. Example output: Read Reference : singleinsertion2 : lambda_neb3011 Read-length : 49 Concordance : : GGCTGCAGTGTACAGCGGTCAGGAGGCC-ATTGATGCCGG : : GGCTGCAG-GTACAGCGGTCAGGAGGCCAATTGATGCCGG : : ACTGGCTGAT : : ACTGGCTGAT : 49 Constructors & Related Methods AlignmentPrinter(const IndexedFastaReader &ifr) Constructs the alignment printer with an associated FASTA file reader. Exceptions ifr: FASTA reader std::runtime_error: if FASTA file cannot be opened for reading. AlignmentPrinter() AlignmentPrinter(const AlignmentPrinter&) 8 Chapter 2. C++ API Reference

13 AlignmentPrinter(AlignmentPrinter&&) AlignmentPrinter &operator=(const AlignmentPrinter&) AlignmentPrinter &operator=(alignmentprinter&&) ~AlignmentPrinter() Printing std::string Print(const BamRecord &record, const Orientation orientation = Orientation::GENOMIC) Pretty-prints an aligned BamRecord to std::string. Note The current implementation includes ANSI escape sequences for coloring terminal output. Future versions of this method will likely make this optional. Return formatted string containing the alignment and summary information 2.3 AlignmentSet #include <pbbam/datasettypes.h> class PacBio::BAM::AlignmentSet The AlignmentSet class represents an AlignmentSet root element in DataSetXML. Inherits from PacBio::BAM::DataSetBase Public Functions AlignmentSet() Creates an empty AlignmentSet dataset. 2.4 BaiIndexedBamReader #include <pbbam/baiindexedbamreader.h> class PacBio::BAM::BaiIndexedBamReader The BaiIndexedBamReader class provides read-only iteration over BAM records, bounded by a particular genomic interval. The SAM/BAM standard index (*.bai) is used to allow random-access operations. Inherits from PacBio::BAM::BamReader Constructors & Related Methods BaiIndexedBamReader(const GenomicInterval &interval, const std::string &filename) Constructs BAM reader, bounded by a genomic interval. All reads that overlap the interval will be available AlignmentSet 9

14 Exceptions interval: iteration will be bounded by this GenomicInterval. filename: input BAM filename std::runtime_error: if either file (*.bam or *.bai) fails to open for reading, or if the interval is invalid BaiIndexedBamReader(const GenomicInterval &interval, const BamFile &bamfile) Constructs BAM reader, bounded by a genomic interval. All reads that overlap the interval will be available. Exceptions interval: iteration will be bounded by this GenomicInterval. bamfile: input BamFile object std::runtime_error: if either file (*.bam or *.bai) fails to open for reading, or if the interval is invalid BaiIndexedBamReader(const GenomicInterval &interval, BamFile &&bamfile) Constructs BAM reader, bounded by a genomic interval. All reads that overlap the interval will be available. Exceptions interval: iteration will be bounded by this GenomicInterval. bamfile: input BamFile object std::runtime_error: if either file (*.bam or *.bai) fails to open for reading, or if the interval is invalid Random-Access const GenomicInterval &Interval() const Return the current GenomicInterval in use by this reader BaiIndexedBamReader &Interval(const GenomicInterval &interval) Sets a new genomic interval on the reader. Return reference to this reader interval: 10 Chapter 2. C++ API Reference

15 Protected Functions int ReadRawData(BGZF *bgzf, bam1_t *b) Performs the actual raw read of the next record from the BAM file. Default implementation will read records, sequentially, until EOF. Derived readers may use additional criteria to decide which record is next and when reading is done. Return value should be equivalent to htslib s bam_read1(): >= 0 : normal -1 : EOF (not an error) < -1 : error Return integer status code, see description bgzf: BGZF stream pointer b: BAM record pointer 2.5 BamFile #include <pbbam/bamfile.h> class PacBio::BAM::BamFile The BamFile class represents a BAM file. It provides access to header metadata and methods for finding/creating associated index files. Constructors & Related Methods BamFile(const std::string &filename) Creates a BamFile object on the provided filename & loads header information. Exceptions filename: BAM filename std::exception: on failure to open BAM file for reading BamFile(const BamFile &other) BamFile(BamFile &&other) BamFile &operator=(const BamFile &other) BamFile &operator=(bamfile &&other) ~BamFile() 2.5. BamFile 11

16 Index & Filename Methods void CreatePacBioIndex() const Creates a.pbi file for this BAM file. Note Existing index file will be overwritten. Use EnsurePacBioIndexExists() if this is not desired. Exceptions if: PBI file could not be properly created and/or written to disk void CreateStandardIndex() const Creates a.bai file for this BAM file. Note Existing index file will be overwritten. Use EnsureStandardIndexExists() if this is not desired. Exceptions if: BAI file could not be properly created (e.g. this BAM is not coordinate-sorted) or could not be written to disk void EnsurePacBioIndexExists() const Creates a.pbi file if one does not exist or is older than its BAM file. Equivalent to: if (!file.pacbioindexexists()) file.createpacbioindex(); Note As of v , no timestamp check is performed. Previously we requr with an additional timestamp check. Exceptions if: PBI file could not be properly created and/or written to disk void EnsureStandardIndexExists() const Creates a.bai file if one does not exist or is older than its BAM file. Equivalent to: if (!file.standardindexexists()) file.createstandardindex(); Note As of v0.4.2, no timestamp check is performed. Exceptions if: BAI file could not be properly created (e.g. this BAM is not coordinate-sorted) or could not be written to disk std::string Filename() const Return BAM filename bool HasEOF() const Return true if BAM file has EOF marker (empty BGZF block). Streamed input (filename: - ) 12 Chapter 2. C++ API Reference

17 bool PacBioIndexExists() const Return true if.pbi exists and is newer than this BAM file. std::string PacBioIndexFilename() const Return filename of PacBio index file (.pbi ) Note No guarantee is made on the existence of this file. This method simply returns the expected filename. bool PacBioIndexIsNewer() const Return true if.pbi has a more recent timestamp than this file bool StandardIndexExists() const Return true if.bai exists std::string StandardIndexFilename() const Note No guarantee is made on the existence of this file. This method simply returns the expected filename. bool StandardIndexIsNewer() const Return true if.bai has a more recent timestamp than this file File Header Data bool HasReference(const std::string &name) const Return true if header metadata has this reference name const BamHeader &Header() const Return const reference to BamHeader containing the file s metadata bool IsPacBioBAM() const Return true if file is a PacBio BAM file (i.e. has non-empty version associated with header pb tag) int ReferenceId(const std::string &name) const Return ID for reference name (can be used for e.g. GenomicIntervalQuery), or -1 if not found std::string ReferenceName(const int id) const Return name of reference matching id, empty string if not found uint32_t ReferenceLength(const std::string &name) const Return length of requested reference name. 0 if not found uint32_t ReferenceLength(const int id) const Return length of requested reference id. 0 if not found Additional Attributes int64_t FirstAlignmentOffset() const Return virtual offset of first alignment. Intended mostly for internal use. Note that this is a BGZF virtual offset, not a normal file position BamFile 13

18 2.6 BamHeader #include <pbbam/bamheader.h> class PacBio::BAM::BamHeader The BamHeader class represents the header section of the BAM file. It provides metadata about the file including file version, reference sequences, read groups, comments, etc. A BamHeader may be fetched from a BamFile to view an existing file s metadata. Or one may be created/edited for use with writing to a new file (via BamWriter). Note A particular BamHeader is likely to be re-used in lots of places throughout the library, for read-only purposes. For this reason, even though a BamHeader may be returned by value, it is essentially a thin wrapper for a shared-pointer to the actual data. This means, though, that if you need to edit an existing BamHeader for use with a BamWriter, please consider using BamHeader::DeepCopy. Otherwise any modifications will affect all BamHeaders that are sharing its underlying data. Constructors & Related Methods BamHeader() Creates an empty BamHeader. BamHeader(const std::string &samheadertext) Creates a BamHeader from SAM-formatted text. samheadertext: BamHeader(const BamHeader &other) BamHeader(BamHeader &&other) BamHeader &operator=(const BamHeader &other) BamHeader &operator=(bamheader &&other) ~BamHeader() BamHeader DeepCopy() const Detaches underlying data from the shared-pointer, returning a independent copy of the header contents. This ensures that any modifications to the newly returned BamHeader do not affect other BamHeader objects that were sharing its underlying data. Operators BamHeader &operator+=(const BamHeader &other) Merges another header with this one. Headers must be compatible for merging. This means that their Version, SortOrder, PacBioBamVersion (and in the case of aligned BAM data, Sequences) must all match. If not, an exception will be thrown. Return reference to this header 14 Chapter 2. C++ API Reference

19 Exceptions other: header to merge with this one std::runtime_error: if the headers are not compatible BamHeader operator+(const BamHeader &other) const Creates a new, merged header. Headers must be compatible for merging. This means that their Version, SortOrder, PacBioBamVersion (and in the case of aligned BAM data, Sequences) must all match. If not, an exception will be thrown. Both original headers (this header and other) will not be modified. Return merged header Exceptions other: header to merge with this one std::runtime_error: if the headers are not compatible General Attributes std::string PacBioBamVersion() const Return the PacBio BAM version number (@HD:pb) Note This is different from the SAM/BAM version number See BamHeader::Version. std::string SortOrder() const Valid values: unknown, unsorted, queryname, or coordinate Return the sort order used std::string Version() const Return the SAM/BAM version number (@HD:VN) Note This is different from the PacBio BAM version number See BamHeader::PacBioBamVersion BamHeader &PacBioBamVersion(const std::string &version) Sets this header s PacBioBAM version number (@HD:pb). Return reference to this object Exceptions std::runtime_error: if version number cannot be parsed or is less than the minimum version allowed BamHeader 15

20 BamHeader &SortOrder(const std::string &order) Sets this header s sort order label (@HD:SO). Valid values: unknown, unsorted, queryname, or coordinate Return reference to this object BamHeader &Version(const std::string &version) Sets this header s SAM/BAM version number (@HD:VN). Return reference to this object Read Groups bool HasReadGroup(const std::string &id) const Return true if the header contains a read group with id (@RG:ID) ReadGroupInfo ReadGroup(const std::string &id) const Return a ReadGroupInfo object representing the read group matching id (@RG:ID) Exceptions std::runtime_error: if id is unknown std::vector<std::string> ReadGroupIds() const Return vector of read group IDs listed in this header std::vector<readgroupinfo> ReadGroups() const Return vector of ReadGroupInfo objects, representing all read groups listed in this header BamHeader &AddReadGroup(const ReadGroupInfo &readgroup) Appends a read group entry (@RG) to this header. Return reference to this object BamHeader &ClearReadGroups() Removes all read group entries from this header. Return reference to this object BamHeader &ReadGroups(const std::vector<readgroupinfo> &readgroups) Replaces this header s list of read group entries with those in readgroups. Return reference to this object Sequences bool HasSequence(const std::string &name) const Return true if header contains a sequence with name (@SQ:SN) size_t NumSequences() const 16 Chapter 2. C++ API Reference

21 Return number of sequences entries) stored in this header int32_t SequenceId(const std::string &name) const This is the numeric ID used elsewhere throughout the API. Return numeric ID for sequence matching name See BamReader::ReferenceId, PbiReferenceIdFilter, PbiRawMappedData::tId_ Exceptions std::runtime_error: if name is unknown std::string SequenceLength(const int32_t id) const Return the length of the sequence e.g. chromosome length) at index id See SequenceInfo::Length, BamHeader::SequenceId std::string SequenceName(const int32_t id) const Return the name of the sequence at index id See SequenceInfo::Name, BamHeader::SequenceId std::vector<std::string> SequenceNames() const Position in the vector is equivalent to SequenceId. Return vector of sequence names stored in this header SequenceInfo Sequence(const int32_t id) const Return SequenceInfo object at index id See BamHeader::SequenceId Exceptions std::out_of_range: if is an invalid or unknown index SequenceInfo Sequence(const std::string &name) const Return SequenceInfo for the sequence matching name std::vector<sequenceinfo> Sequences() const Return vector of SequenceInfo objects representing the sequences entries) stored in this header BamHeader &AddSequence(const SequenceInfo &sequence) Appends a sequence entry (@SQ) to this header. Return reference to this object BamHeader &ClearSequences() Removes all sequence entries from this header. Return reference to this object BamHeader &Sequences(const std::vector<sequenceinfo> &sequences) Replaces this header s list of sequence entries with those in sequences. Return reference to this object 2.6. BamHeader 17

22 Programs bool HasProgram(const std::string &id) const Return true if this header contains a program entry with ID (@PG:ID) matching id ProgramInfo Program(const std::string &id) const Return ProgramInfo object for the program entry matching id Exceptions std::runtime_error: if id is unknown std::vector<std::string> ProgramIds() const Return vector of program IDs (@PG:ID) std::vector<programinfo> Programs() const Return vector of ProgramInfo objects representing program entries (@PG) stored in this heder BamHeader &AddProgram(const ProgramInfo &pg) Appends a program entry (@PG) to this header. Return reference to this object BamHeader &ClearPrograms() Removes all program entries from this header. Return reference to this object BamHeader &Programs(const std::vector<programinfo> &programs) Replaces this header s list of program entries with those in programs. Return reference to this object Comments std::vector<std::string> Comments() const Return vector of comment (@CO) strings BamHeader &AddComment(const std::string &comment) Appends a comment (@CO) to this header. Return reference to this object BamHeader &ClearComments() Removes all comments from this header. Return reference to this object BamHeader &Comments(const std::vector<std::string> &comments) Replaces this header s list of comments with those in comments. Return reference to this object 18 Chapter 2. C++ API Reference

23 Conversion Methods std::string ToSam() const Return SAM-header-formatted string representing this header s data 2.7 BamReader #include <pbbam/bamreader.h> class PacBio::BAM::BamReader The BamReader class provides basic read-access to a BAM file. The base-class implementation provides a sequential read-through of BAM records. Derived classes may implement other access schemes (e.g. genomic region, PBI-enabled record filtering). Subclassed by PacBio::BAM::BaiIndexedBamReader, PacBio::BAM::PbiIndexedBamReader Constructors & Related Methods BamReader(const std::string &fn) Opens BAM file for reading. Exceptions fn: BAM filename std::runtime_error: if failed to open BamReader(const BamFile &bamfile) Opens BAM file for reading. Exceptions bamfile: BamFile object std::runtime_error: if failed to open BamReader(BamFile &&bamfile) Opens BAM file for reading. Exceptions bamfile: BamFile object std::runtime_error: if failed to open virtual ~BamReader() 2.7. BamReader 19

24 BAM File Attributes const BamFile &File() const Return the underlying BamFile std::string Filename() const Return BAM filename const BamHeader &Header() const Return BamHeader object from BAM header contents BAM File I/O bool GetNext(BamRecord &record) Fetches the next BAM record. Default implementation will read records until EOF. Derived readers may use additional criteria to decide which record is next and when reading is done. Return true if record was read successfully. Returns false if EOF (or end of iterator in derived readers). False is not an error, it indicates end of data. Exceptions record: next BamRecord object. Should not be used if method returns false. std::runtime_error: if failed to read from file (e.g. possible truncated or corrupted file). void VirtualSeek(int64_t virtualoffset) Seeks to virtual offset in BAM. Note This is NOT a normal file offset, but the virtual offset used in BAM indexing. Exceptions std::runtime_error: if failed to seek int64_t VirtualTell() const Return current (virtual) file position. Note This is NOT a normal file offset, but the virtual offset used in BAM indexing. BGZF *Bgzf() const Helper method for access to underlying BGZF stream pointer. Useful for derived readers contact points with htslib methods. Return BGZF stream pointer 20 Chapter 2. C++ API Reference

25 virtual int ReadRawData(BGZF *bgzf, bam1_t *b) Performs the actual raw read of the next record from the BAM file. Default implementation will read records, sequentially, until EOF. Derived readers may use additional criteria to decide which record is next and when reading is done. Return value should be equivalent to htslib s bam_read1(): >= 0 : normal -1 : EOF (not an error) < -1 : error Return integer status code, see description bgzf: BGZF stream pointer b: BAM record pointer 2.8 BamRecord #include <pbbam/bamrecord.h> enum PacBio::BAM::ClipType This enum defines the modes supported by BamRecord clipping operations. Methods like BamRecord::Clip accept Position parameters - which may be in either polymerase or reference coorindates. Using this enum as a flag indicates how the positions should be interpreted. Values: CLIP_NONE No clipping will be performed. CLIP_TO_QUERY Clipping positions are in polymerase coordinates. CLIP_TO_REFERENCE Clipping positions are in genomic coordinates. enum PacBio::BAM::RecordType This enum defines the possible PacBio BAM record types. See ReadGroupInfo::ReadType Values: ZMW Polymerase read. HQREGION High-quality region. SUBREAD Subread (. CCS Circular consensus sequence. SCRAP Additional sequence (barcodes, adapters, etc.) 2.8. BamRecord 21

26 UNKNOWN Unknown read type. POLYMERASE = ZMW enum PacBio::BAM::FrameEncodingType This enum defines the possible encoding modes used in Frames data (e.g. Record::PulseWidth). BamRecord::IPD or Bam- The LOSSY mode is the default in production output; LOSSLESS mode being used primarily for internal applications. See for more information on pulse frame encoding schemes. Values: LOSSY 8-bit compression (using CodecV1) of frame data LOSSLESS 16-bit native frame data class PacBio::BAM::BamRecord The BamRecord class represents a PacBio BAM record. PacBio BAM records are extensions of normal SAM/BAM records. Thus in addition to normal fields like bases, qualities, mapping coordinates, etc., tags are used extensively to annotate records with additional PacBiospecific data. Mapping and clipping APIs are provided as well to ensure that such operations trickle down to all data fields properly. See for more information on standard BAM data, and https: //github.com/pacificbiosciences/pacbiofileformats/blob/3.0/bam.rst for more information on PacBio BAM fields. Subclassed by PacBio::BAM::VirtualZmwBamRecord Constructors & Related Methods BamRecord() BamRecord(BamHeader header) BamRecord(BamRecordImpl impl) BamRecord(const BamRecord &other) BamRecord(BamRecord &&other) BamRecord &operator=(const BamRecord &other) BamRecord &operator=(bamrecord &&other) virtual ~BamRecord() 22 Chapter 2. C++ API Reference

27 General Data std::string FullName() const Return this record s full name See BamRecordImpl::Name BamHeader Header() const Return shared pointer to this record s associated BamHeader int32_t HoleNumber() const Return ZMW hole number Exceptions if: missing zm tag & record name does not contain hole number PacBio::BAM::LocalContextFlags LocalContextFlags() const Return this record s LocalContextFlags std::string MovieName() const Return this record s movie name int32_t NumPasses() const Return number of complete passes of the insert Position QueryEnd() const Return the record s query end position, or Sequence().length() if not stored Note QueryEnd is in polymerase read coordinates, NOT genomic coordinates. Position QueryStart() const Return the record s query start position, or 0 if not stored Note QueryStart is in polymerase read coordinates, NOT genomic coordinates. Accuracy ReadAccuracy() const Return this record s expected read accuracy [0, 1000] ReadGroupInfo ReadGroup() const Return ReadGroupInfo object for this record std::string ReadGroupId() const Return string ID of this record s read group See ReadGroupInfo::Id int32_t ReadGroupNumericId() const Return integer value for this record s read group ID VirtualRegionType ScrapRegionType() const Return this scrap record s scrap region type 2.8. BamRecord 23

28 ZmwType ScrapZmwType() const Return this scrap record s scrap ZMW type std::vector<float> SignalToNoise() const Return this record s average signal-to-noise for each of A, C, G, and T RecordType Type() const Return this record s type See RecordType BamRecord &HoleNumber(const int32_t holenumber) Sets this record s ZMW hole number. Return reference to this record holenumber: BamRecord &LocalContextFlags(const PacBio::BAM::LocalContextFlags flags) Sets this record s local context flags. Return reference to this record flags: BamRecord &NumPasses(const int32_t numpasses) Sets this record s number of complete passes of the insert. Return reference to this record numpasses: BamRecord &QueryEnd(const PacBio::BAM::Position pos) Sets this record s query end position. Note Changing this will modify the name of non-ccs records. Return reference to this record pos: BamRecord &QueryStart(const PacBio::BAM::Position pos) Sets this record s query start position. Note Changing this will modify the name of non-ccs records. Return reference to this record pos: 24 Chapter 2. C++ API Reference

29 BamRecord &ReadAccuracy(const Accuracy &accuracy) Sets this record s expected read accuracy [0, 1000]. Return reference to this record accuracy: BamRecord &ReadGroup(const ReadGroupInfo &rg) Attaches this record to the provided read group, changing the record name & RG tag. Return reference to this record rg: BamRecord &ReadGroupId(const std::string &id) Attaches this record to the provided read group, changing the record name & RG tag. Return reference to this record id: BamRecord &ScrapRegionType(const VirtualRegionType type) Sets this scrap record s ScrapRegionType. Return reference to this record type: BamRecord &ScrapRegionType(const char type) Sets this scrap record s ScrapRegionType. Return reference to this record type: character equivalent of VirtualRegionType BamRecord &ScrapZmwType(const ZmwType type) Sets this scrap record s ScrapZmwType. Return reference to this record type: BamRecord &ScrapZmwType(const char type) Sets this scrap record s ScrapZmwType. Return reference to this record 2.8. BamRecord 25

30 type: character equivalent of ZmwType BamRecord &SignalToNoise(const std::vector<float> &snr) Sets this record s average signal-to-noise in each of A, C, G, and T. Return reference to this record snr: average signal-to-noise of A, C, G, and T (in this order) Mapping Data Position AlignedEnd() const Return the record s aligned end position Note AlignedEnd is in polymerase read coordinates, NOT genomic coordinates. Position AlignedStart() const Return the record s aligned start position Note AlignedStart is in polymerase read coordinates, NOT genomic coordinates. Strand AlignedStrand() const Return the record s strand as a Strand enum value Cigar CigarData(bool exciseallclips = false) const Return the record s CIGAR data as a Cigar object exciseallclips: if true, remove all clipping operations (hard & soft) [default:false] bool IsMapped() const Return true if this record was mapped by aligner uint8_t MapQuality() const Return this record s mapping quality. A value of 255 indicates unknown size_t NumDeletedBases() const Return the number of deleted bases (relative to reference) size_t NumInsertedBases() const Return the number of inserted bases (relative to reference) size_t NumMatches() const Return the number of matching bases (sum of = CIGAR op lengths) std::pair<size_t, size_t> NumMatchesAndMismatches() const Return a tuple containing NumMatches (first) and NumMismatches (second) size_t NumMismatches() const 26 Chapter 2. C++ API Reference

31 Return the number of mismatching bases (sum of X CIGAR op lengths) int32_t ReferenceId() const Return this record s reference ID, or -1 if unmapped. Note This is only a valid identifier within this BAM file std::string ReferenceName() const Return this record s reference name. Exceptions an: exception if unmapped record. Position ReferenceEnd() const Return the record s reference end position, or UnmappedPosition if unmapped Note ReferenceEnd is in reference coordinates, NOT polymerase read coordinates. Position ReferenceStart() const Return the record s reference start position, or UnmappedPosition if unmapped Note ReferenceStart is in reference coordinates, NOT polymerase read coordinates. Barcode Data int16_t BarcodeForward() const Return forward barcode id See HasBarcodes Exceptions std::runtime_error: if barcode data is absent or malformed. uint8_t BarcodeQuality() const Return barcode call confidence (Phred-scaled posterior probability of correct barcode call) See HasBarcodeQuality int16_t BarcodeReverse() const Return reverse barcode id See HasBarcodes Exceptions std::runtime_error: if barcode data is absent or malformed. std::pair<int16_t, int16_t> Barcodes() const Return the forward and reverse barcode ids See HasBarcodes Exceptions std::runtime_error: if barcode data is absent or malformed BamRecord 27

32 BamRecord &Barcodes(const std::pair<int16_t, int16_t> &barcodeids) Sets this record s barcode IDs ( bc tag) Return reference to this record barcodeids: BamRecord &BarcodeQuality(const uint8_t quality) Sets this record s barcode quality ( bq tag) Return reference to this record quality: Phred-scaled confidence call Auxiliary Data Queries bool HasAltLabelQV() const Return true if this record has AltLabelQV data bool HasAltLabelTag() const Return true if this record has AltLabelTag data bool HasBarcodes() const Return true if this record has Barcode data bool HasBarcodeQuality() const Return true is this record has BarcodeQuality data bool HasDeletionQV() const Return true if this record has DeletionQV data bool HasDeletionTag() const Return true if this record has DeletionTag data bool HasHoleNumber() const Return true if this record has a HoleNumber bool HasInsertionQV() const Return true if this record has InsertionQV data bool HasIPD() const Return true if this record has IPD data bool HasLabelQV() const Return true if this record has LabelQV data bool HasLocalContextFlags() const Return true if this record has LocalContextFlags (absent in CCS) 28 Chapter 2. C++ API Reference

33 bool HasMergeQV() const Return true if this record has MergeQV data bool HasNumPasses() const Return true if this record has NumPasses data bool HasPkmean() const Return true if this record has Pkmean data bool HasPkmid() const Return true if this record has Pkmid data bool HasPkmean2() const Return true if this record has Pkmean2 data bool HasPkmid2() const Return true if this record has Pkmid2 data bool HasPreBaseFrames() const Return true if this record has PreBaseFrames aka IPD data bool HasPrePulseFrames() const Return true if this record has PrePulseFrames data bool HasPulseCall() const Return true if this record has PulseCall data bool HasPulseCallWidth() const Return true if this record has PulseCallWidth data bool HasPulseExclusion(void) const Return true if this record has PulseExclusion data bool HasPulseMergeQV() const Return true if this record has PulseMergeQV data bool HasPulseWidth() const Return true if this record has PulseWidth data bool HasReadAccuracy() const Return true if this record has ReadAccuracyTag data bool HasQueryEnd() const Return true if this record has QueryEnd data bool HasQueryStart() const Return true if this record has QueryStart data bool HasScrapRegionType() const Return true if this record has ScrapRegionType data (only in SCRAP) 2.8. BamRecord 29

34 bool HasScrapZmwType() const Return true if this record has scrap ZMW type data (only in SCRAP) bool HasSignalToNoise() const Return true if this record has signal-to-noise data (absent in POLYMERASE) bool HasStartFrame() const Return true if this record has StartFrame data bool HasSubstitutionQV() const Return true if this record has SubstitutionQV data bool HasSubstitutionTag() const Return true if this record has SubstitutionTag data Sequence & Tag Data std::string AltLabelTag(Orientation orientation = Orientation::NATIVE, bool aligned = false, bool excisesoftclips = false, PulseBehavior pulsebehavior = PulseBehavior::ALL) const Fetches this record s AltLabelTag values ( pt tag). Note If aligned is true, and gaps/padding need to be inserted, the new gap chars will be - and padding chars will be *. Return AltLabelTags string orientation: Orientation of output. std::string DeletionTag(Orientation orientation = Orientation::NATIVE, bool aligned = false, bool excisesoftclips = false) const Fetches this record s DeletionTag values ( dt tag). Note If aligned is true, and gaps/padding need to be inserted, the new gap chars will be - and padding chars will be *. Return DeletionTag string orientation: Orientation of output. aligned: if true, gaps/padding will be inserted, per Cigar info. excisesoftclips: if true, any soft-clipped positions will be removed from query ends std::string Sequence(const Orientation orientation = Orientation::NATIVE, bool aligned = false, bool excisesoftclips = false) const Fetches this record s DNA sequence (SEQ field). Note If aligned is true, and gaps/padding need to be inserted, the new gap chars will be - and padding chars will be *. Return sequence string 30 Chapter 2. C++ API Reference

35 orientation: Orientation of output. aligned: if true, gaps/padding will be inserted, per Cigar info. excisesoftclips: if true, any soft-clipped positions will be removed from query ends std::string SubstitutionTag(Orientation orientation = Orientation::NATIVE, bool aligned = false, bool excisesoftclips = false) const Fetches this record s SubstitutionTag values ( st tag). Note If aligned is true, and gaps/padding need to be inserted, the new gap chars will be - and padding chars will be *. Return SubstitutionTags string orientation: Orientation of output. aligned: if true, gaps/padding will be inserted, per Cigar info. excisesoftclips: if true, any soft-clipped positions will be removed from query ends BamRecord &AltLabelTag(const std::string &tags) Sets this record s AltLabelTag values ( at tag). Return reference to this record tags: BamRecord &DeletionTag(const std::string &tags) Sets this record s DeletionTag values ( dt tag). Return reference to this record tags: BamRecord &SubstitutionTag(const std::string &tags) Sets this record s SubstitutionTag values ( st tag). Return reference to this record tags: Quality Data QualityValues AltLabelQV(Orientation orientation = Orientation::NATIVE, bool aligned = false, bool excisesoftclips = false, PulseBehavior pulsebehavior = PulseBehavior::ALL) const Fetches this record s AltLabelQV values ( pv tag) BamRecord 31

36 Note If aligned is true, and gaps/padding need to be inserted, the new QVs will have a value of 0. Return AltLabelQV as QualityValues object orientation: Orientation of output. QualityValues DeletionQV(Orientation orientation = Orientation::NATIVE, bool aligned = false, bool excisesoftclips = false) const Fetches this record s DeletionQV values ( dq tag). Note If aligned is true, and gaps/padding need to be inserted, the new QVs will have a value of 0. Return DeletionQV as QualityValues object orientation: Orientation of output. aligned: if true, gaps/padding will be inserted, per Cigar info. excisesoftclips: if true, any soft-clipped positions will be removed from query ends QualityValues InsertionQV(Orientation orientation = Orientation::NATIVE, bool aligned = false, bool excisesoftclips = false) const Fetches this record s InsertionQV values ( iq tag). Note If aligned is true, and gaps/padding need to be inserted, the new QVs will have a value of 0. Return InsertionQVs as QualityValues object orientation: Orientation of output. aligned: if true, gaps/padding will be inserted, per Cigar info. excisesoftclips: if true, any soft-clipped positions will be removed from query ends QualityValues LabelQV(Orientation orientation = Orientation::NATIVE, bool aligned = false, bool excisesoftclips = false, PulseBehavior pulsebehavior = PulseBehavior::ALL) const Fetches this record s LabelQV values ( pq tag). Note If aligned is true, and gaps/padding need to be inserted, the new QVs will have a value of 0. Return LabelQV as QualityValues object orientation: Orientation of output. QualityValues MergeQV(Orientation orientation = Orientation::NATIVE, bool aligned = false, bool excisesoftclips = false) const Fetches this record s MergeQV values ( mq tag). Note If aligned is true, and gaps/padding need to be inserted, the new QVs will have a value of 0. Return MergeQV as QualityValues object 32 Chapter 2. C++ API Reference

37 orientation: Orientation of output. aligned: if true, gaps/padding will be inserted, per Cigar info. excisesoftclips: if true, any soft-clipped positions will be removed from query ends QualityValues Qualities(Orientation orientation = Orientation::NATIVE, bool aligned = false, bool excisesoftclips = false) const Fetches this record s BAM quality values (QUAL field). Note If aligned is true, and gaps/padding need to be inserted, the new QVs will have a value of 0. Return BAM qualities as QualityValues object orientation: Orientation of output. aligned: if true, gaps/padding will be inserted, per Cigar info. excisesoftclips: if true, any soft-clipped positions will be removed from query ends QualityValues SubstitutionQV(Orientation orientation = Orientation::NATIVE, bool aligned = false, bool excisesoftclips = false) const Fetches this record s SubstitutionQV values ( sq tag). Note If aligned is true, and gaps/padding need to be inserted, the new QVs will have a value of 0. Return SubstitutionQV as QualityValues object orientation: Orientation of output. aligned: if true, gaps/padding will be inserted, per Cigar info. excisesoftclips: if true, any soft-clipped positions will be removed from query ends BamRecord &AltLabelQV(const QualityValues &altlabelqvs) Sets this record s AltLabelQV values ( pv tag). Return reference to this record altlabelqvs: BamRecord &DeletionQV(const QualityValues &deletionqvs) Sets this record s DeletionQV values ( dq tag). Return reference to this record deletionqvs: BamRecord &InsertionQV(const QualityValues &insertionqvs) Sets this record s InsertionQV values ( iq tag). Return reference to this record 2.8. BamRecord 33

38 insertionqvs: BamRecord &LabelQV(const QualityValues &labelqvs) Sets this record s LabelQV values ( pq tag). Return reference to this record labelqvs: BamRecord &MergeQV(const QualityValues &mergeqvs) Sets this record s MergeQV values ( mq tag). Return reference to this record mergeqvs: BamRecord &SubstitutionQV(const QualityValues &substitutionqvs) Sets this record s SubstitutionQV values ( sq tag). Return reference to this record substitutionqvs: Pulse Data const float photonfactor Frames IPD(Orientation orientation = Orientation::NATIVE, bool aligned = false, bool excisesoftclips = false) const Fetches this record s IPD values ( ip tag). Note If aligned is true, and gaps/padding need to be inserted, the new frames will have a value of 0; Return IPD as Frames object orientation: Orientation of output. aligned: if true, gaps/padding will be inserted, per Cigar info. excisesoftclips: if true, any soft-clipped positions will be removed from query ends Frames IPDRaw(Orientation orientation = Orientation::NATIVE) const Fetches this record s IPD values ( ip tag), but does not upscale. Return IPD as Frames object orientation: Orientation of output. 34 Chapter 2. C++ API Reference

39 std::vector<float> Pkmean(Orientation orientation = Orientation::NATIVE, bool aligned = false, bool excisesoftclips = false, PulseBehavior pulsebehavior = PulseBehavior::ALL) const Fetches this record s Pkmean values ( pa tag). Return Pkmean as vector<float> object orientation: Orientation of output. std::vector<float> Pkmid(Orientation orientation = Orientation::NATIVE, bool aligned = false, bool excisesoftclips = false, PulseBehavior pulsebehavior = PulseBehavior::ALL) const Fetches this record s Pkmid values ( pm tag). Return Pkmid as vector<float> object orientation: Orientation of output. std::vector<float> Pkmean2(Orientation orientation = Orientation::NATIVE, bool aligned = false, bool excisesoftclips = false, PulseBehavior pulsebehavior = PulseBehavior::ALL) const Fetches this record s Pkmean2 values ( pi tag). Return Pkmean as vector<float> object orientation: Orientation of output. std::vector<float> Pkmid2(Orientation orientation = Orientation::NATIVE, bool aligned = false, bool excisesoftclips = false, PulseBehavior pulsebehavior = PulseBehavior::ALL) const Fetches this record s Pkmid2 values ( ps tag). Return Pkmid as vector<float> object orientation: Orientation of output. Frames PreBaseFrames(Orientation orientation = Orientation::NATIVE, bool aligned = false, bool excisesoftclips = false) const Fetches this record s PreBaseFrames aka IPD values ( ip tag). Note If aligned is true, and gaps/padding need to be inserted, the new frames will have a value of 0; Return IPD as Frames object orientation: Orientation of output. aligned: if true, gaps/padding will be inserted, per Cigar info. excisesoftclips: if true, any soft-clipped positions will be removed from query ends 2.8. BamRecord 35

40 Frames PrePulseFrames(Orientation orientation = Orientation::NATIVE, bool aligned = false, bool excisesoftclips = false, PulseBehavior pulsebehavior = PulseBehavior::ALL) const Fetches this record s PrePulseFrames values ( pd tag). Return PrePulseFrames as Frames object orientation: Orientation of output. std::string PulseCall(Orientation orientation = Orientation::NATIVE, bool aligned = false, bool excisesoftclips = false, PulseBehavior pulsebehavior = PulseBehavior::ALL) const Fetches this record s PulseCall values ( pc tag). Return PulseCalls string orientation: Orientation of output. Frames PulseCallWidth(Orientation orientation = Orientation::NATIVE, bool aligned = false, bool excisesoftclips = false, PulseBehavior pulsebehavior = PulseBehavior::ALL) const Fetches this record s PulseCallWidth values ( px tag). Return PulseCallWidth as Frames object orientation: Orientation of output. std::vector<pacbio::bam::pulseexclusionreason> PulseExclusionReason(Orientation orientation = Orientation::NATIVE, bool aligned = false, bool excisesoftclips = false, PulseBehavior pulsebehavior = PulseBehavior::ALL) const Fetches this record s PulseExclusionReason values ( pe tag). Return vector of pulse exclusion reason value QualityValues PulseMergeQV(Orientation orientation = Orientation::NATIVE, bool aligned = false, bool excisesoftclips = false, PulseBehavior pulsebehavior = PulseBehavior::ALL) const Fetch this record s PulseMergeQV values ( pg tag). Return PulseMergeQV as QualityValues object orientation: Orientation of output. 36 Chapter 2. C++ API Reference

41 Frames PulseWidth(Orientation orientation = Orientation::NATIVE, bool aligned = false, bool excisesoftclips = false) const Fetches this record s PulseWidth values ( pw tag). Note If aligned is true, and gaps/padding need to be inserted, the new frames will have a value of 0. Return PulseWidths as Frames object orientation: Orientation of output. aligned: if true, gaps/padding will be inserted, per Cigar info. excisesoftclips: if true, any soft-clipped positions will be removed from query ends Frames PulseWidthRaw(Orientation orientation = Orientation::NATIVE, bool aligned = false, bool excisesoftclips = false) const Fetches this record s PulseWidth values ( pw tag), but does not upscale. Return PulseWidth as Frames object orientation: Orientation of output. std::vector<uint32_t> StartFrame(Orientation orientation = Orientation::NATIVE, bool aligned = false, bool excisesoftclips = false, PulseBehavior pulsebehavior = PulseBehavior::ALL) const Fetches this record s StartFrame values ( sf tag). Return StartFrame as uint32_t vector orientation: Orientation of output BamRecord &IPD(const Frames &frames, const FrameEncodingType encoding) Sets this record s IPD values ( ip tag). Return reference to this record frames: encoding: specify how to encode the data (8-bit lossy, or 16-bit lossless) BamRecord &Pkmean(const std::vector<float> &photons) Sets this record s Pkmean values ( pm tag). Return reference to this record photons: BamRecord &Pkmean(const std::vector<uint16_t> &encodedphotons) Sets this record s Pkmean values ( pm tag) BamRecord 37

42 Return reference to this record encodedphotons: BamRecord &Pkmid(const std::vector<float> &photons) Sets this record s Pkmid values ( pa tag). Return reference to this record photons: BamRecord &Pkmid(const std::vector<uint16_t> &encodedphotons) Sets this record s Pkmid values ( pa tag). Return reference to this record encodedphotons: BamRecord &Pkmean2(const std::vector<float> &photons) Sets this record s Pkmean2 values ( ps tag). Return reference to this record photons: BamRecord &Pkmean2(const std::vector<uint16_t> &encodedphotons) Sets this record s Pkmean2 values ( ps tag). Return reference to this record encodedphotons: BamRecord &Pkmid2(const std::vector<float> &photons) Sets this record s Pkmid2 values ( pi tag). Return reference to this record photons: BamRecord &Pkmid2(const std::vector<uint16_t> &encodedphotons) Sets this record s Pkmid2 values ( pi tag). Return reference to this record encodedphotons: 38 Chapter 2. C++ API Reference

43 BamRecord &PreBaseFrames(const Frames &frames, const FrameEncodingType encoding) Sets this record s PreBaseFrames aka IPD values ( ip tag). Return reference to this record frames: encoding: specify how to encode the data (8-bit lossy, or 16-bit lossless) BamRecord &PrePulseFrames(const Frames &frames, const FrameEncodingType encoding) Sets this record s PrePulseFrames values ( pd tag). Return reference to this record frames: encoding: specify how to encode the data (8-bit lossy, or 16-bit lossless) BamRecord &PulseCall(const std::string &tags) Sets this record s PulseCall values ( pc tag). Return reference to this record tags: BamRecord &PulseCallWidth(const Frames &frames, const FrameEncodingType encoding) Sets this record s PulseCallWidth values ( px tag). Return reference to this record frames: encoding: specify how to encode the data (8-bit lossy, or 16-bit lossless) BamRecord &PulseExclusionReason(const std::vector<pacbio::bam::pulseexclusionreason> &reasons) \brief Sets this record s PulseExclusionReason values ( pe tag). Return reference to this record reasons: BamRecord &PulseMergeQV(const QualityValues &pulsemergeqvs) Sets this record s PulseMergeQV values ( pg tag). Return reference to this record pulsemergeqvs: 2.8. BamRecord 39

44 BamRecord &PulseWidth(const Frames &frames, const FrameEncodingType encoding) Sets this record s PulseWidth values ( pw tag). Return reference to this record frames: encoding: specify how to encode the data (8-bit lossy, or 16-bit lossless) BamRecord &StartFrame(const std::vector<uint32_t> &startframe) Sets this record s StartFrame values ( sf tag). Return reference to this record startframe: static std::vector<uint16_t> EncodePhotons(const std::vector<float> &data) Low-Level Access & Operations const BamRecordImpl &Impl() const Warning This method should be considered temporary and avoided as much as possible. Direct access to the internal object is likely to disappear as BamRecord interface matures. Return const reference to underlying BamRecordImpl object BamRecordImpl &Impl() Warning This method should be considered temporary and avoided as much as possible. Direct access to the internal object is likely to disappear as BamRecord interface matures. Return reference to underlying BamRecordImpl object void ResetCachedPositions() const Resets cached aligned start/end. Note This method should not be needed in most client code. It exists primarily as a hook for internal reading loops (queries, index build, etc.) It s essentially a workaround and will likely be removed from the API. void ResetCachedPositions() Resets cached aligned start/end. Note This method should not be needed in most client code. It exists primarily as a hook for internal reading loops (queries, index build, etc.) It s essentially a workaround and will likely be removed from the API. void UpdateName() Updates the record s name (BamRecord::FullName) to reflect modifications to name components (movie name, ZMW hole number, etc.) 40 Chapter 2. C++ API Reference