Functions

sam_open: Open a SAM file for reading, either uncompressed or compressed by gzip/zlib.
sam_close: Close a SAM file handler
sam_read1: Read one alignment from a SAM file handler
sam_header_read2: Read header information from a TAB-delimited list file.
sam_header_read: Read header from a SAM file (if present)
sam_header_parse: Parse @SQ lines a update a header struct
sam_header_parse_rg: Parse @RG lines a update a header struct
bam_header_init: Initialize a header structure.
bam_header_destroy: Destroy a header structure.
bam_header_read: Read a header structure from BAM.
bam_header_write: Write a header structure to BAM.
bam_read1: Read an alignment from BAM.
bam_write1_core: Write an alignment to BAM.
bam_write1: It is equivalent to: bam_write1_core(fp, &b->core, b->data_len, b->data)
bam_format1: Format a BAM record in the SAM format
bam_plbuf_reset: Reset a pileup buffer for another pileup process
bam_plbuf_init: Initialize a buffer for pileup.
bam_plbuf_destroy: Destroy a pileup buffer.
bam_plbuf_push: Push an alignment to the pileup buffer.
bam_lplbuf_init: bam_plbuf_init() equivalent with level calculated.
bam_lplbuf_destroy: bam_plbuf_destroy() equivalent with level calculated.
bam_lplbuf_push: bam_plbuf_push() equivalent with level calculated.
bam_lpileup_file: bam_plbuf_file() equivalent with level calculated.
bam_index_build: Build index for a BAM file.
bam_index_load: Load index from file "fn.bai".
bam_index_destroy: Destroy an index structure.
bam_fetch: Retrieve the alignments that are overlapped with the specified region.
bam_parse_region: Parse a region in the format: "chr2:100,000-200,000".
bam_aux_get: Retrieve data of a tag
bam_calend: Calculate the rightmost coordinate of an alignment on the reference genome.
bam_cigar2qlen: Calculate the length of the query sequence from CIGAR.
bam_reg2bin: Calculate the minimum bin that contains a region [beg,end).
bam_copy1: Copy an alignment
bam_dup1: Duplicate an alignment

sam_read1

Read one alignment from a SAM file handler

int sam_read1(
    tamFile fp,
    bam_header_t *header,
    bam1_t *b);

Parameters

fp: SAM file handler
header: header information (ordered names of chromosomes)
b: read alignment; all members in b will be updated

Return Value

0 if successful; otherwise negative

sam_header_read2

Read header information from a TAB-delimited list file.

bam_header_t *sam_header_read2(
    const char *fn_list);

Parameters

fn_list: file name for the list

Return Value

a pointer to the header structure

Discussion

Each line in this file consists of chromosome name and the length of chromosome.

sam_header_read

Read header from a SAM file (if present)

bam_header_t *sam_header_read(
    tamFile fp);

Parameters

fp: SAM file handler

Return Value

pointer to header struct; 0 if no @SQ lines available

sam_header_parse

Parse @SQ lines a update a header struct

int sam_header_parse(
    bam_header_t *h);

Parameters

h: pointer to the header struct to be updated

Return Value

number of target sequences

Discussion

bam_header_t::{n_targets,target_len,target_name} will be destroyed in the first place.

sam_header_parse_rg

Parse @RG lines a update a header struct

int sam_header_parse_rg(
    bam_header_t *h);

Parameters

h: pointer to the header struct to be updated

Return Value

number of @RG lines

Discussion

bam_header_t::rg2lib will be destroyed in the first place.

bam_header_init

Initialize a header structure.

bam_header_t *bam_header_init();

Return Value

the pointer to the header structure

Discussion

This function also modifies the global variable bam_is_be.

bam_header_read

Read a header structure from BAM.

bam_header_t *bam_header_read(
    bamFile fp);

Parameters

fp: BAM file handler, opened by bam_open()

Return Value

pointer to the header structure

Discussion

The file position indicator must be placed at the beginning of the file. Upon success, the position indicator will be set at the start of the first alignment.

bam_header_write

Write a header structure to BAM.

int bam_header_write(
    bamFile fp,
    const bam_header_t *header);

Parameters

fp: BAM file handler
header: pointer to the header structure

Return Value

always 0 currently

bam_read1

Read an alignment from BAM.

int bam_read1(
    bamFile fp,
    bam1_t *b);

Parameters

fp: BAM file handler
b: read alignment; all members are updated.

Return Value

number of bytes read from the file

Discussion

The file position indicator must be placed right before an alignment. Upon success, this function will set the position indicator to the start of the next alignment. This function is not affected by the machine endianness.

bam_write1_core

Write an alignment to BAM.

int bam_write1_core(
    bamFile fp,
    const bam1_core_t *c,
    int data_len,
    uint8_t *data);

Parameters

fp: BAM file handler
c: pointer to the bam1_core_t structure
data_len: total length of variable size data related to the alignment
data: pointer to the concatenated data

Return Value

number of bytes written to the file

Discussion

This function is not affected by the machine endianness.

bam_write1

It is equivalent to: bam_write1_core(fp, &b->core, b->data_len, b->data)

int bam_write1(
    bamFile fp,
    const bam1_t *b);

Parameters

fp: BAM file handler
b: alignment to write

Return Value

number of bytes written to the file

bam_format1

Format a BAM record in the SAM format

char *bam_format1(
    const bam_header_t *header,
    const bam1_t *b);

Parameters

header: pointer to the header structure
b: alignment to print

Return Value

a pointer to the SAM string

bam_plbuf_reset

Reset a pileup buffer for another pileup process

void bam_plbuf_reset(
    bam_plbuf_t *buf);

Parameters

buf: the pileup buffer to be reset

bam_plbuf_init

Initialize a buffer for pileup.

bam_plbuf_t *bam_plbuf_init(
    bam_pileup_f func,
    void *data);

Parameters

func: fucntion to be called by bam_pileup_core()
data: user provided data

Return Value

pointer to the pileup buffer

bam_plbuf_destroy

Destroy a pileup buffer.

void bam_plbuf_destroy(
    bam_plbuf_t *buf);

Parameters

buf: pointer to the pileup buffer

bam_plbuf_push

Push an alignment to the pileup buffer.

See:

bam_plbuf_init()" -->

int bam_plbuf_push(
    const bam1_t *b,
    bam_plbuf_t *buf);

Parameters

b: alignment to be pushed
buf: pileup buffer

Return Value

always 0 currently

Discussion

If all the alignments covering a particular site have been collected, this function will call the user defined function as is provided to bam_plbuf_init(). The coordinate of the site and all the alignments will be transferred to the user defined function as function parameters.

When all the alignments are pushed to the buffer, this function needs to be called with b equal to NULL. This will flush the buffer. A pileup buffer can only be reused when bam_plbuf_reset() is called.

bam_lplbuf_init

bam_plbuf_init() equivalent with level calculated.

bam_lplbuf_t *bam_lplbuf_init(
    bam_pileup_f func,
    void *data);

bam_lplbuf_destroy

bam_plbuf_destroy() equivalent with level calculated.

void bam_lplbuf_destroy(
    bam_lplbuf_t *tv);

bam_lplbuf_push

bam_plbuf_push() equivalent with level calculated.

int bam_lplbuf_push(
    const bam1_t *b,
    bam_lplbuf_t *buf);

bam_lpileup_file

bam_plbuf_file() equivalent with level calculated.

int bam_lpileup_file(
    bamFile fp,
    int mask,
    bam_pileup_f func,
    void *func_data);

bam_index_build

Build index for a BAM file.

int bam_index_build(
    const char *fn);

Parameters

fn: name of the BAM file

Return Value

always 0 currently

Discussion

Index file "fn.bai" will be created.

bam_index_load

Load index from file "fn.bai".

bam_index_t *bam_index_load(
    const char *fn);

Parameters

fn: name of the BAM file (NOT the index file)

Return Value

pointer to the index structure

bam_index_destroy

Destroy an index structure.

void bam_index_destroy(
    bam_index_t *idx);

Parameters

idx: pointer to the index structure

bam_fetch

Retrieve the alignments that are overlapped with the specified region.

int bam_fetch(
    bamFile fp,
    const bam_index_t *idx,
    int tid,
    int beg,
    int end,
    void *data,
    bam_fetch_f func);

Parameters

fp: BAM file handler
idx: pointer to the alignment index
tid: chromosome ID as is defined in the header
beg: start coordinate, 0-based
end: end coordinate, 0-based
data: user provided data (will be transferred to func)
func: user defined function

Discussion

A user defined function will be called for each retrieved alignment ordered by its start position.

bam_parse_region

Parse a region in the format: "chr2:100,000-200,000".

void bam_parse_region(
    bam_header_t *header,
    const char *str,
    int *ref_id,
    int *begin,
    int *end);

Parameters

header: pointer to the header structure
str: string to be parsed
ref_id: the returned chromosome ID
begin: the returned start coordinate
end: the returned end coordinate

Discussion

bam_header_t::hash will be initialized if empty.

bam_aux_get

Retrieve data of a tag

uint8_t *bam_aux_get(
    const bam1_t *b,
    const char tag[2]);

Parameters

b: pointer to an alignment struct
tag: two-character tag to be retrieved

Return Value

pointer to the type and data. The first character is the type that can be 'iIsScCdfAZH'.

Discussion

Use bam_aux2?() series to convert the returned data to the corresponding type.

bam_calend

Calculate the rightmost coordinate of an alignment on the reference genome.

uint32_t bam_calend(
    const bam1_core_t *c,
    const uint32_t *cigar);

Parameters

c: pointer to the bam1_core_t structure
cigar: the corresponding CIGAR array (from bam1_t::cigar)

Return Value

the rightmost coordinate, 0-based

bam_cigar2qlen

Calculate the length of the query sequence from CIGAR.

int32_t bam_cigar2qlen(
    const bam1_core_t *c,
    const uint32_t *cigar);

Parameters

c: pointer to the bam1_core_t structure
cigar: the corresponding CIGAR array (from bam1_t::cigar)

Return Value

length of the query sequence

bam_reg2bin

Calculate the minimum bin that contains a region [beg,end).

static inline int bam_reg2bin(
    uint32_t beg,
    uint32_t end)

Parameters

beg: start of the region, 0-based
end: end of the region, 0-based

Return Value

bin

bam_copy1

Copy an alignment

static inline bam1_t *bam_copy1(
    bam1_t *bdst,
    const bam1_t *bsrc)

Parameters

bdst: destination alignment struct
bsrc: source alignment struct

Return Value

pointer to the destination alignment struct

bam_dup1

Duplicate an alignment

static inline bam1_t *bam_dup1(
    const bam1_t *src)

Parameters

src: source alignment struct

Return Value

pointer to the destination alignment struct