hts.h File Reference

#include <stddef.h>
#include <stdint.h>

Go to the source code of this file.

Classes
struct	__kstring_t
struct	htsFormat
struct	htsFile
struct	hts_pair64_t
struct	hts_itr_t

Macros
#define	HTS_BGZF_TYPEDEF
#define	KSTRING_T   kstring_t
#define	kroundup32(x)   (--(x), (x)|=(x)>>1, (x)|=(x)>>2, (x)|=(x)>>4, (x)|=(x)>>8, (x)|=(x)>>16, ++(x))
#define	hts_expand(type_t, n, m, ptr)
#define	hts_expand0(type_t, n, m, ptr)
#define	HTS_IDX_NOCOOR   (-2)
#define	HTS_IDX_START   (-3)
#define	HTS_IDX_REST   (-4)
#define	HTS_IDX_NONE   (-5)
#define	HTS_FMT_CSI   0
#define	HTS_FMT_BAI   1
#define	HTS_FMT_TBI   2
#define	HTS_FMT_CRAI   3
#define	hts_bin_first(l)   (((1<<(((l)<<1) + (l))) - 1) / 7)
#define	hts_bin_parent(l)   (((l) - 1) >> 3)

Typedefs
typedef struct BGZF	BGZF
typedef struct __kstring_t	kstring_t
typedef struct htsFormat	htsFormat
typedef struct __hts_idx_t	hts_idx_t
typedef int	hts_readrec_func (BGZF *fp, void *data, void *r, int *tid, int *beg, int *end)
typedef int(*	hts_name2id_f )(void *, const char *)
typedef const char *(*	hts_id2name_f )(void *, int)
typedef hts_itr_t *	hts_itr_query_func (const hts_idx_t *idx, int tid, int beg, int end, hts_readrec_func *readrec)

Enumerations
enum	htsFormatCategory {   unknown_category, sequence_data, variant_data, index_file,   region_list, category_maximum = 32767 }
enum	htsExactFormat {   unknown_format, binary_format, text_format, sam,   bam, bai, cram, crai,   vcf, bcfv1, bcf, csi,   gzi, tbi, bed, format_maximum = 32767 }
enum	htsCompression {   no_compression, gzip, bgzf, custom,   compression_maximum = 32767 }
enum	sam_fields {   SAM_QNAME = 0x00000001, SAM_FLAG = 0x00000002, SAM_RNAME = 0x00000004, SAM_POS = 0x00000008,   SAM_MAPQ = 0x00000010, SAM_CIGAR = 0x00000020, SAM_RNEXT = 0x00000040, SAM_PNEXT = 0x00000080,   SAM_TLEN = 0x00000100, SAM_SEQ = 0x00000200, SAM_QUAL = 0x00000400, SAM_AUX = 0x00000800,   SAM_RGAUX = 0x00001000 }
enum	cram_option {   CRAM_OPT_DECODE_MD, CRAM_OPT_PREFIX, CRAM_OPT_VERBOSITY, CRAM_OPT_SEQS_PER_SLICE,   CRAM_OPT_SLICES_PER_CONTAINER, CRAM_OPT_RANGE, CRAM_OPT_VERSION, CRAM_OPT_EMBED_REF,   CRAM_OPT_IGNORE_MD5, CRAM_OPT_REFERENCE, CRAM_OPT_MULTI_SEQ_PER_SLICE, CRAM_OPT_NO_REF,   CRAM_OPT_USE_BZIP2, CRAM_OPT_SHARED_REF, CRAM_OPT_NTHREADS, CRAM_OPT_THREAD_POOL,   CRAM_OPT_USE_LZMA, CRAM_OPT_USE_RANS, CRAM_OPT_REQUIRED_FIELDS }

Functions
const char *	hts_version (void)
int	hts_detect_format (struct hFILE *fp, htsFormat *fmt)
const char *	hts_format_description (const htsFormat *format)
htsFile *	hts_open (const char *fn, const char *mode)
htsFile *	hts_hopen (struct hFILE *fp, const char *fn, const char *mode)
int	hts_close (htsFile *fp)
const htsFormat *	hts_get_format (htsFile *fp)
int	hts_set_opt (htsFile *fp, enum cram_option opt,...)
int	hts_getline (htsFile *fp, int delimiter, kstring_t *str)
char **	hts_readlines (const char *fn, int *_n)
char **	hts_readlist (const char *fn, int is_file, int *_n)
int	hts_set_threads (htsFile *fp, int n)
int	hts_set_fai_filename (htsFile *fp, const char *fn_aux)
hts_idx_t *	hts_idx_init (int n, int fmt, uint64_t offset0, int min_shift, int n_lvls)
void	hts_idx_destroy (hts_idx_t *idx)
int	hts_idx_push (hts_idx_t *idx, int tid, int beg, int end, uint64_t offset, int is_mapped)
void	hts_idx_finish (hts_idx_t *idx, uint64_t final_offset)
void	hts_idx_save (const hts_idx_t *idx, const char *fn, int fmt)
hts_idx_t *	hts_idx_load (const char *fn, int fmt)
uint8_t *	hts_idx_get_meta (hts_idx_t *idx, int *l_meta)
void	hts_idx_set_meta (hts_idx_t *idx, int l_meta, uint8_t *meta, int is_copy)
int	hts_idx_get_stat (const hts_idx_t *idx, int tid, uint64_t *mapped, uint64_t *unmapped)
uint64_t	hts_idx_get_n_no_coor (const hts_idx_t *idx)
const char *	hts_parse_reg (const char *s, int *beg, int *end)
hts_itr_t *	hts_itr_query (const hts_idx_t *idx, int tid, int beg, int end, hts_readrec_func *readrec)
void	hts_itr_destroy (hts_itr_t *iter)
hts_itr_t *	hts_itr_querys (const hts_idx_t *idx, const char *reg, hts_name2id_f getid, void *hdr, hts_itr_query_func *itr_query, hts_readrec_func *readrec)
int	hts_itr_next (BGZF *fp, hts_itr_t *iter, void *r, void *data)
const char **	hts_idx_seqnames (const hts_idx_t *idx, int *n, hts_id2name_f getid, void *hdr)

Variables
int	hts_verbose
const unsigned char	seq_nt16_table [256]
const char	seq_nt16_str []

Macro Definition Documentation

#define HTS_BGZF_TYPEDEF

#define hts_bin_first

(

l

)

(((1<<(((l)<<1) + (l))) - 1) / 7)

#define hts_bin_parent

(

l

)

(((l) - 1) >> 3)

#define hts_expand	(		type_t,
			n,
			m,
			ptr
	)

Value:

if ((n) > (m)) { \
        (m) = (n); kroundup32(m); \
        (ptr) = (type_t*)realloc((ptr), (m) * sizeof(type_t)); \
    }

hts_expand() - expands memory block pointed to by $ptr; hts_expand0() the latter sets the newly allocated part to 0.

Parameters

n	requested number of elements of type type_t
m	size of memory allocated

#define hts_expand0	(		type_t,
			n,
			m,
			ptr
	)

Value:

if ((n) > (m)) { \
        int t = (m); (m) = (n); kroundup32(m); \
        (ptr) = (type_t*)realloc((ptr), (m) * sizeof(type_t)); \
        memset(((type_t*)ptr)+t,0,sizeof(type_t)*((m)-t)); \
    }

#define HTS_FMT_BAI   1

#define HTS_FMT_CRAI   3

#define HTS_FMT_CSI   0

#define HTS_FMT_TBI   2

#define HTS_IDX_NOCOOR   (-2)

These HTS_IDX_* macros are used as special tid values for hts_itr_query()/etc, producing iterators operating as follows:

• HTS_IDX_NOCOOR iterates over unmapped reads sorted at the end of the file
• HTS_IDX_START iterates over the entire file
• HTS_IDX_REST iterates from the current position to the end of the file
• HTS_IDX_NONE always returns "no more alignment records" When one of these special tid values is used, beg and end are ignored. When REST or NONE is used, idx is also ignored and may be NULL.

#define HTS_IDX_NONE   (-5)

#define HTS_IDX_REST   (-4)

#define HTS_IDX_START   (-3)

#define kroundup32

(

x

)

(--(x), (x)|=(x)>>1, (x)|=(x)>>2, (x)|=(x)>>4, (x)|=(x)>>8, (x)|=(x)>>16, ++(x))

#define KSTRING_T   kstring_t

Typedef Documentation

typedef struct BGZF BGZF

typedef const char*(* hts_id2name_f)(void *, int)

typedef struct __hts_idx_t hts_idx_t

typedef hts_itr_t* hts_itr_query_func(const hts_idx_t *idx, int tid, int beg, int end, hts_readrec_func *readrec)

typedef int(* hts_name2id_f)(void *, const char *)

typedef int hts_readrec_func(BGZF *fp, void *data, void *r, int *tid, int *beg, int *end)

typedef struct htsFormat htsFormat

typedef struct __kstring_t kstring_t

Enumeration Type Documentation

enum cram_option

Enumerator
CRAM_OPT_DECODE_MD
CRAM_OPT_PREFIX
CRAM_OPT_VERBOSITY
CRAM_OPT_SEQS_PER_SLICE
CRAM_OPT_SLICES_PER_CONTAINER
CRAM_OPT_RANGE
CRAM_OPT_VERSION
CRAM_OPT_EMBED_REF
CRAM_OPT_IGNORE_MD5
CRAM_OPT_REFERENCE
CRAM_OPT_MULTI_SEQ_PER_SLICE
CRAM_OPT_NO_REF
CRAM_OPT_USE_BZIP2
CRAM_OPT_SHARED_REF
CRAM_OPT_NTHREADS
CRAM_OPT_THREAD_POOL
CRAM_OPT_USE_LZMA
CRAM_OPT_USE_RANS
CRAM_OPT_REQUIRED_FIELDS

enum htsCompression

Enumerator
no_compression
gzip
bgzf
custom
compression_maximum

enum htsExactFormat

Enumerator
unknown_format
binary_format
text_format
sam
bam
bai
cram
crai
vcf
bcfv1
bcf
csi
gzi
tbi
bed
format_maximum

enum htsFormatCategory

Enumerator
unknown_category
sequence_data
variant_data
index_file
region_list
category_maximum

enum sam_fields

Enumerator
SAM_QNAME
SAM_FLAG
SAM_RNAME
SAM_POS
SAM_MAPQ
SAM_CIGAR
SAM_RNEXT
SAM_PNEXT
SAM_TLEN
SAM_SEQ
SAM_QUAL
SAM_AUX
SAM_RGAUX

Function Documentation

int hts_close

(

htsFile *

fp

)

Close a file handle, flushing buffered data for output streams

Parameters

fp	The file handle to be closed

Returns

0 for success, or negative if an error occurred.

int hts_detect_format	(	struct hFILE *	fp,
		htsFormat *	fmt
	)

Determine format by peeking at the start of a file

Parameters

fp	File opened for reading, positioned at the beginning
fmt	Format structure that will be filled out on return

Returns

0 for success, or negative if an error occurred.

const char* hts_format_description

(

const htsFormat *

format

)

Get a human-readable description of the file format

const htsFormat* hts_get_format

(

htsFile *

fp

)

Returns the file's format information

Parameters

fp	The file handle

Returns

Read-only pointer to the file's htsFormat.

int hts_getline	(	htsFile *	fp,
		int	delimiter,
		kstring_t *	str
	)

htsFile* hts_hopen	(	struct hFILE *	fp,
		const char *	fn,
		const char *	mode
	)

Open an existing stream as a SAM/BAM/CRAM/VCF/BCF/etc file

Parameters

fn	The already-open file handle
mode	Open mode, as per hts_open()

void hts_idx_destroy

(

hts_idx_t *

idx

)

void hts_idx_finish	(	hts_idx_t *	idx,
		uint64_t	final_offset
	)

uint8_t* hts_idx_get_meta	(	hts_idx_t *	idx,
		int *	l_meta
	)

uint64_t hts_idx_get_n_no_coor

(

const hts_idx_t *

idx

)

int hts_idx_get_stat	(	const hts_idx_t *	idx,
		int	tid,
		uint64_t *	mapped,
		uint64_t *	unmapped
	)

hts_idx_t* hts_idx_init	(	int	n,
		int	fmt,
		uint64_t	offset0,
		int	min_shift,
		int	n_lvls
	)

hts_idx_t* hts_idx_load	(	const char *	fn,
		int	fmt
	)

int hts_idx_push	(	hts_idx_t *	idx,
		int	tid,
		int	beg,
		int	end,
		uint64_t	offset,
		int	is_mapped
	)

void hts_idx_save	(	const hts_idx_t *	idx,
		const char *	fn,
		int	fmt
	)

const char** hts_idx_seqnames	(	const hts_idx_t *	idx,
		int *	n,
		hts_id2name_f	getid,
		void *	hdr
	)

void hts_idx_set_meta	(	hts_idx_t *	idx,
		int	l_meta,
		uint8_t *	meta,
		int	is_copy
	)

void hts_itr_destroy

(

hts_itr_t *

iter

)

int hts_itr_next	(	BGZF *	fp,
		hts_itr_t *	iter,
		void *	r,
		void *	data
	)

hts_itr_t* hts_itr_query	(	const hts_idx_t *	idx,
		int	tid,
		int	beg,
		int	end,
		hts_readrec_func *	readrec
	)

hts_itr_t* hts_itr_querys	(	const hts_idx_t *	idx,
		const char *	reg,
		hts_name2id_f	getid,
		void *	hdr,
		hts_itr_query_func *	itr_query,
		hts_readrec_func *	readrec
	)

htsFile* hts_open	(	const char *	fn,
		const char *	mode
	)

const char* hts_parse_reg	(	const char *	s,
		int *	beg,
		int *	end
	)

char** hts_readlines	(	const char *	fn,
		int *	_n
	)

char** hts_readlist	(	const char *	fn,
		int	is_file,
		int *	_n
	)

Parse comma-separated list or read list from a file

Parameters

list	File name or comma-separated list
is_file
_n	Size of the output array (number of items read)

Returns

NULL on failure or pointer to newly allocated array of strings

int hts_set_fai_filename	(	htsFile *	fp,
		const char *	fn_aux
	)

Set .fai filename for a file opened for reading

Returns

0 for success, negative on failure Called before *_hdr_read(), this provides the name of a .fai file used to provide a reference list if the htsFile contains no headers.

int hts_set_opt	(	htsFile *	fp,
		enum cram_option	opt,
			...
	)

Sets a specified CRAM option on the open file handle.

Parameters

fp	The file handle open the open file.
opt	The CRAM_OPT_* option.
...	Optional arguments, dependent on the option used.

Returns

0 for success, or negative if an error occurred.

int hts_set_threads	(	htsFile *	fp,
		int	n
	)

Create extra threads to aid compress/decompression for this file

Parameters

fp	The file handle
n	The number of worker threads to create

Returns

0 for success, or negative if an error occurred. THIS THREADING API IS LIKELY TO CHANGE IN FUTURE.

const char* hts_version

(

void

)

Get the htslib version number

Returns

For released versions, a string like "N.N[.N]"; or git describe output if using a library built within a Git repository.

Variable Documentation

int hts_verbose

const char seq_nt16_str[]

Table for converting a 4-bit encoded nucleotide to a letter.

const unsigned char seq_nt16_table[256]

Table for converting a nucleotide character to the 4-bit encoding.