Loading...
Searching...
No Matches
BamTools::BamMultiReader Class Reference

Convenience class for reading multiple BAM files. More...

`#include <BamMultiReader.h>`

## Public Types

enum | MergeOrder { RoundRobinMerge = 0 , MergeByCoordinate , MergeByName }

## Public Member Functions

| BamMultiReader ()
| constructor
| ~BamMultiReader ()
| destructor
bool | Close ()
| Closes all open BAM files.
bool | CloseFile (const std::string &filename)
| Closes requested BAM file.
const std::vector< std::string > | Filenames () const
| Returns list of filenames for all open BAM files.
BamMultiReader::MergeOrder | GetMergeOrder () const
| Returns curent merge order strategy.
bool | HasOpenReaders () const
| Returns `true` if there are any open BAM files.
bool | Jump (int refID, int position=0)
| Performs a random-access jump within current BAM files.
bool | Open (const std::vector< std::string > &filenames)
| Opens BAM files.
bool | OpenFile (const std::string &filename)
| Opens a single BAM file.
bool | Rewind ()
| Returns the internal file pointers to the beginning of alignment records.
bool | SetExplicitMergeOrder (BamMultiReader::MergeOrder order)
| Sets an explicit merge order, regardless of the BAM files' SO header tag.
bool | SetRegion (const BamRegion &region)
| Sets a target region of interest.
bool | SetRegion (const int &leftRefID, const int &leftPosition, const int &rightRefID, const int &rightPosition)
| Sets a target region of interest.
bool | GetNextAlignment (BamAlignment &alignment)
| Retrieves next available alignment.
bool | GetNextAlignmentCore (BamAlignment &alignment)
| Retrieves next available alignment.
SamHeader | GetHeader () const
| Returns unified SAM-format header for all files.
std::string | GetHeaderText () const
| Returns unified SAM-format header text for all files.
int | GetReferenceCount () const
| Returns number of reference sequences.
const BamTools::RefVector | GetReferenceData () const
| Returns all reference sequence entries.
int | GetReferenceID (const std::string &refName) const
| Returns the ID of the reference with this name.
bool | CreateIndexes (const BamIndex::IndexType &type=BamIndex::STANDARD)
| Creates index files for the current BAM files.
bool | HasIndexes () const
| Returns `true` if all BAM files have index data available.
bool | LocateIndexes (const BamIndex::IndexType &preferredType=BamIndex::STANDARD)
| Looks for index files that match current BAM files.
bool | OpenIndexes (const std::vector< std::string > &indexFilenames)
| Opens index files for current BAM files.
std::string | GetErrorString () const
| Returns a human-readable description of the last error that occurred.

## Detailed Description

Convenience class for reading multiple BAM files.

## Member Enumeration Documentation

## MergeOrder

enum BamTools::BamMultiReader::MergeOrder

Enumerator
RoundRobinMerge | Merge strategy when BAM files are unsorted, or their sorted status is either unknown or ignored.
MergeByCoordinate | Merge strategy when BAM files are sorted by position ('coordinate').
MergeByName | Merge strategy when BAM files are sorted by read name ('queryname').

## Constructor & Destructor Documentation

## BamMultiReader()

BamMultiReader::BamMultiReader | ( |  | ) |

constructor

## ~BamMultiReader()

BamMultiReader::~BamMultiReader | ( |  | ) |

destructor

## Member Function Documentation

## Close()

bool BamMultiReader::Close | ( |  | ) |

Closes all open BAM files.

Also clears out all header and reference data.

See also
  CloseFile(), IsOpen(), Open(), BamReader::Close()

## CloseFile()

bool BamMultiReader::CloseFile | ( | const std::string & | filename | ) |

Closes requested BAM file.

Leaves any other file(s) open, along with header and reference data.

Parameters

  [in] | filename | name of specific BAM file to close

See also
  Close(), IsOpen(), Open(), BamReader::Close()

## CreateIndexes()

bool BamMultiReader::CreateIndexes | ( | const BamIndex::IndexType & | type = BamIndex::STANDARD | ) |

Creates index files for the current BAM files.

Parameters

  [in] | type | file format to create, see BamIndex::IndexType for available formats

Returns
  `true` if index files created OK

See also
  LocateIndexes(), OpenIndexes(), BamReader::CreateIndex()

## Filenames()

const std::vector< std::string > BamMultiReader::Filenames | ( |  | ) | const

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.

See also
  IsOpen(), BamReader::GetFilename()

## GetErrorString()

std::string BamMultiReader::GetErrorString | ( |  | ) | const

Returns a human-readable description of the last error that occurred.

This method allows elimination of STDERR pollution. Developers of client code may choose how the messages are displayed to the user, if at all.

Returns
  error description

## GetHeader()

SamHeader BamMultiReader::GetHeader | ( |  | ) | const

Returns unified SAM-format header for all files.

Note
  Modifying the retrieved text does NOT affect the current BAM files. These files 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

See also
  GetHeaderText(), BamReader::GetHeader()

## GetHeaderText()

std::string BamMultiReader::GetHeaderText | ( |  | ) | const

Returns unified SAM-format header text for all files.

Note
  Modifying the retrieved text does NOT affect the current BAM files. These files 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

See also
  GetHeader(), BamReader::GetHeaderText()

## GetMergeOrder()

BamMultiReader::MergeOrder BamMultiReader::GetMergeOrder | ( |  | ) | const

Returns curent merge order strategy.

Returns
  current merge order enum value

See also
  BamMultiReader::MergeOrder, SetExplicitMergeOrder()

## GetNextAlignment()

bool BamMultiReader::GetNextAlignment | ( | BamAlignment & | alignment | ) |

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 their sort order.

Parameters

  [out] | alignment | destination for alignment record data

Returns
  `true` if a valid alignment was found

See also
  GetNextAlignmentCore(), SetExplicitMergeOrder(), SetRegion(), BamReader::GetNextAlignment()

## GetNextAlignmentCore()

bool BamMultiReader::GetNextAlignmentCore | ( | BamAlignment & | alignment | ) |

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 their sort order.

Parameters

  [out] | alignment | destination for alignment record data

Returns
  `true` if a valid alignment was found

See also
  GetNextAlignment(), SetExplicitMergeOrder(), SetRegion(), BamReader::GetNextAlignmentCore()

## GetReferenceCount()

int BamMultiReader::GetReferenceCount | ( |  | ) | const

Returns number of reference sequences.

See also
  BamReader::GetReferenceCount()

## GetReferenceData()

const BamTools::RefVector BamMultiReader::GetReferenceData | ( |  | ) | const

Returns all reference sequence entries.

See also
  RefData, BamReader::GetReferenceData()

## GetReferenceID()

int BamMultiReader::GetReferenceID | ( | const std::string & | refName | ) | const

Returns the ID of the reference with this name.

If refName is not found, returns -1.

Parameters

  [in] | refName | name of reference to look up

See also
  BamReader::GetReferenceID()

## HasIndexes()

bool BamMultiReader::HasIndexes | ( |  | ) | const

Returns `true` if all BAM files have index data available.

See also
  BamReader::HasIndex()

## HasOpenReaders()

bool BamMultiReader::HasOpenReaders | ( |  | ) | const

Returns `true` if there are any open BAM files.

## Jump()

bool BamMultiReader::Jump | ( | int | refID,
|  | int | position = 0 )

Performs a random-access jump within current BAM files.

This is a convenience method, equivalent to calling SetRegion() with only a left boundary specified.

Parameters

  [in] | refID | ID of reference to jump to
  [in] | position | (0-based) left boundary

Returns
  `true` if jump was successful

See also
  HasIndex(), BamReader::Jump()

## LocateIndexes()

bool BamMultiReader::LocateIndexes | ( | const BamIndex::IndexType & | preferredType = BamIndex::STANDARD | ) |

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 preferredType whenever possible. However, if an index file of 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:

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 any BAM files that still lack one
// do interesting stuff using random-access...
BamTools::BamMultiReader::LocateIndexes
bool LocateIndexes(const BamIndex::IndexType &preferredType=BamIndex::STANDARD)
Looks for index files that match current BAM files.
Definition BamMultiReader.cpp:302
BamTools::BamMultiReader::BamMultiReader
BamMultiReader()
constructor
Definition BamMultiReader.cpp:44
BamTools::BamMultiReader::CreateIndexes
bool CreateIndexes(const BamIndex::IndexType &type=BamIndex::STANDARD)
Creates index files for the current BAM files.
Definition BamMultiReader.cpp:90

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.

Parameters

  [in] | preferredType | desired index file format, see BamIndex::IndexType for available formats

Returns
  `true` if index files could be found for ALL open BAM files

See also
  BamReader::LocateIndex()

## Open()

bool BamMultiReader::Open | ( | const std::vector< std::string > & | filenames | ) |

Opens BAM files.

Note
  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.

Parameters

  [in] | filenames | list of BAM filenames to open

Returns
  `true` if BAM files were opened successfully

See also
  Close(), HasOpenReaders(), OpenFile(), OpenIndexes(), BamReader::Open()

## OpenFile()

bool BamMultiReader::OpenFile | ( | const std::string & | filename | ) |

Opens a single BAM file.

Adds another BAM file to multireader "on-the-fly".

Note
  Opening a BAM file 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.

Parameters

  [in] | filename | BAM filename to open

Returns
  `true` if BAM file was opened successfully

See also
  Close(), HasOpenReaders(), Open(), OpenIndexes(), BamReader::Open()

## OpenIndexes()

bool BamMultiReader::OpenIndexes | ( | const std::vector< std::string > & | indexFilenames | ) |

Opens index files for current BAM files.

Note
  Currently assumes that index filenames match the order (and number) of BAM files passed to Open().

Parameters

  [in] | indexFilenames | list of BAM index file names

Returns
  `true` if BAM index file was opened & data loaded successfully

See also
  LocateIndex(), Open(), SetIndex(), BamReader::OpenIndex()

## Rewind()

bool BamMultiReader::Rewind | ( |  | ) |

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
  `true` if rewind operation was successful

See also
  Jump(), SetRegion(), BamReader::Rewind()

## SetExplicitMergeOrder()

bool BamMultiReader::SetExplicitMergeOrder | ( | BamMultiReader::MergeOrder | order | ) |

Sets an explicit merge order, regardless of the BAM files' SO header tag.

The default behavior of the BamMultiReader is to check the SO tag in the BAM files' SAM header text to determine the merge strategy". The merge strategy is used to determine from which BAM file the next alignment should come when either GetNextAlignment() or GetNextAlignmentCore() are called. If files share a 'coordinate' or 'queryname' value for this tag, then the merge strategy is selected accordingly. If any of them do not match, or if any fileis marked as 'unsorted', then the merge strategy is simply a round-robin.

This method allows client code to explicitly override the lookup behavior. This method can be useful when you know, for example, that your BAM files are sorted by coordinate but upstream processes did not set the header tag properly.

Note
  This method should not be called while reading alignments via GetNextAlignment() or GetNextAlignmentCore(). For proper results, you should call this method before (or immediately after) opening files, rewinding, jumping, etc. but not once alignment fetching has started. There is nothing in the API to prevent you from doing so, but the results may be unexpected.

Returns
  `true` if merge order could be successfully applied

See also
  BamMultiReader::MergeOrder, GetMergeOrder(), GetNextAlignment(), GetNextAlignmentCore()

## SetRegion() [1/2]

bool BamMultiReader::SetRegion | ( | const BamRegion & | region | ) |

Sets a target region of interest.

Equivalent to calling BamReader::SetRegion() on all open BAM files.

Warning
  BamRegion now represents a zero-based, HALF-OPEN interval. In previous versions of BamTools (0.x & 1.x) all intervals were treated as zero-based, CLOSED.

Parameters

  [in] | region | desired region-of-interest to activate

Returns
  `true` if ALL readers set the region successfully

See also
  HasIndexes(), Jump(), BamReader::SetRegion()

## SetRegion() [2/2]

bool BamMultiReader::SetRegion | ( | const int & | leftRefID,
|  | const int & | leftPosition,
|  | const int & | rightRefID,
|  | const int & | rightPosition )

Sets a target region of interest.

This is an overloaded function. Equivalent to calling BamReader::SetRegion() on all open BAM files.

Warning
  This function now expects a zero-based, HALF-OPEN interval. In previous versions of BamTools (0.x & 1.x) all intervals were treated as zero-based, CLOSED.

Parameters

  [in] | leftRefID | referenceID of region's left boundary
  [in] | leftPosition | position of region's left boundary
  [in] | rightRefID | reference ID of region's right boundary
  [in] | rightPosition | position of region's right boundary

Returns
  `true` if ALL readers set the region successfully

See also
  HasIndexes(), Jump(), BamReader::SetRegion()

The documentation for this class was generated from the following files:

- BamMultiReader.h
- BamMultiReader.cpp