API Reference

BAM Reading

Constructors

BamReader(std::string file_name, int n_thread = 8, bool is_tgs = false);

Creates a BAM reader for the specified file.

• n_thread: Number of threads used for decompression and parsing (default: 8)

• is_tgs: Whether the input BAM file is from third-generation sequencing

BamReader(std::string file_name, int read_block, int compress_block, int compress_complete_block, int n_thread = 8, bool is_tgs = false);

Creates a BAM reader with fine-grained control over memory usage.

• read_block, compress_block, compress_complete_block: Maximum number of blocks in Queue1, Queue2, and Queue3 respectively

• Useful for tuning memory and performance in large-scale pipelines

Functions

bool getBam1_t(bam1_t *b);

Retrieves the next parsed BAM record. Returns true if successful, or false if end-of-file is reached.

BAM Writing

Constructors

BamWriter(std::string file_name, int threadNumber = 1, int level = 6, int BufferSize = 200, bool is_tgs = false);

Creates a BAM writer that writes directly to a file.

• threadNumber: Number of compression threads

• level: Compression level (default: 6)

• BufferSize: Maximum number of blocks in Queue4 and Queue5

• is_tgs: Whether the BAM is from third-generation sequencing

BamWriter(std::string file_name, sam_hdr_t *hdr, int threadNumber = 1, int level = 6, int BufferSize = 200, bool is_tgs = false);

Initializes a writer with both file path and BAM header.

Functions

void hdr_write(sam_hdr_t *hdr);

Writes the BAM header to the output stream. Must be called before writing records if not set in the constructor.

void bam_write(bam1_t *b);

Writes a single BAM record to the output.

void over();

Finalizes and closes the output stream. Should be called after all records are written.

Usage Example

Below is a C++ demo program that illustrates how to use the above APIs. Source:

#include <iostream>
#include <cstdlib>
#include <unistd.h>
#include <thread>

#include "BamTools.h"
#include "BamReader.h"
#include "BamWriter.h"

int main(int argc, char* argv[]) {
    std::string input_file;
    std::string output_file;
    int n_thread = 1;

    int opt;
    while ((opt = getopt(argc, argv, "i:t:o:")) != -1) {
        switch (opt) {
            case 'i': input_file = optarg; break;
            case 't': n_thread = std::atoi(optarg); break;
            case 'o': output_file = optarg; break;
            default:
                std::cerr << "Usage: " << argv[0] << " -i input_file -t thread_num -o output_file\n";
                return EXIT_FAILURE;
        }
    }

    if (input_file.empty() || output_file.empty() || n_thread <= 0) {
        std::cerr << "Invalid arguments. Usage: " << argv[0] << " -i input_file -t thread_num -o output_file\n";
        return EXIT_FAILURE;
    }

    std::cout << "Input file: " << input_file << "\n";
    std::cout << "Total thread number: " << n_thread << "\n";
    std::cout << "Output file: " << output_file << "\n";

    int compress_level = 6;
    int block_size = 256;
    bool single_parser = true;

    int n_thread_read = n_thread / 5;
    int n_thread_write = n_thread - n_thread_read;
    if(n_thread_read <= 0) n_thread_read = 1;
    if(n_thread_write <= 0) n_thread_write = 1;

    BamReader *reader = new BamReader(input_file, n_thread_read, single_parser);
    BamWriter *writer = new BamWriter(output_file, reader->getHeader(), n_thread_write, compress_level, block_size, single_parser);

    bam1_t *b;
    if ((b = bam_init1()) == NULL) {
        fprintf(stderr, "[E::%s] Out of memory allocating BAM struct.\n", __func__);
    }

    long long num = 0;
    while (reader->getBam1_t(b)) {
        num++;
        writer->write(b);
    }

    writer->over();
    printf("num %lld\n", num);

    return 0;
}

Compile:

export HTSLIB_INSTALL_PATH=<path-to-htslib-installation-directory>
export RABBITBAM_INSTALL_PATH=<path-to-RabbitBAM-installation-directory>
export LIBDEFLATE_INSTALL_PATH=<path-to-libdeflate-installation-directory>
export LD_LIBRARY_PATH=$RABBITBAM_INSTALL_PATH:$LD_LIBRARY_PATH

g++ -o main main.cpp \
  -I$HTSLIB_INSTALL_PATH/include \
  -I$RABBITBAM_INSTALL_PATH/htslib \
  -I$RABBITBAM_INSTALL_PATH \
  -I$LIBDEFLATE_INSTALL_PATH/include \
  -L$HTSLIB_INSTALL_PATH/lib \
  -L$RABBITBAM_INSTALL_PATH \
  -L$LIBDEFLATE_INSTALL_PATH/lib \
  -lhts -lz -fopenmp -lpthread \
  -lrabbitbamtools -lrabbitbamread -lrabbitbamwrite

Run:

time ./main -i in.bam -o out.bam -t 40