tabix.tex

   1 \documentclass[10pt]{article}
   2 \usepackage{color}
   3 \definecolor{gray}{rgb}{0.7,0.7,0.7}
   4
   5 \setlength{\topmargin}{0.0cm}
   6 \setlength{\textheight}{21.5cm}
   7 \setlength{\oddsidemargin}{0cm}
   8 \setlength{\textwidth}{16.5cm}
   9 \setlength{\columnsep}{0.6cm}
  10
  11 \begin{document}
  12
  13 \title{The Tabix index file format}
  14 \author{Heng Li}
  15 \date{}
  16
  17 \maketitle
  18
  19 \begin{center}
  20 \begin{tabular}{|l|l|l|l|l|l|l|}
  21 \hline
  22 \multicolumn{4}{|c|}{\bf Field} & \multicolumn{1}{c|}{\bf Descrption} & \multicolumn{1}{c|}{\bf Type} & \multicolumn{1}{c|}{\bf Value} \\
  23 \hline\hline
  24 \multicolumn{4}{|l|}{\tt magic} & Magic string & {\tt char[4]} & TBI$\backslash$1 \\
  25 \hline
  26 \multicolumn{4}{|l|}{\tt n\_ref} & \# sequences & {\tt int32\_t} & \\
  27 \hline
  28 \multicolumn{4}{|l|}{\tt format} & Format (0: generic; 1: SAM; 2: VCF) & {\tt int32\_t} & \\
  29 \hline
  30 \multicolumn{4}{|l|}{\tt col\_seq} & Column for the sequence name & {\tt int32\_t} & \\
  31 \hline
  32 \multicolumn{4}{|l|}{\tt col\_beg} & Column for the start of a region & {\tt int32\_t} & \\
  33 \hline
  34 \multicolumn{4}{|l|}{\tt col\_end} & Column for the end of a region & {\tt int32\_t} & \\
  35 \hline
  36 \multicolumn{4}{|l|}{\tt meta} & Leading character for comment lines & {\tt int32\_t} & \\
  37 \hline
  38 \multicolumn{4}{|l|}{\tt skip} & \# lines to skip at the beginning & {\tt int32\_t} & \\
  39 \hline
  40 \multicolumn{4}{|l|}{\tt l\_nm} & Length of concatenated sequence names & {\tt int32\_t} & \\
  41 \hline
  42 \multicolumn{4}{|l|}{\tt names} & Concatenated names, each zero terminated & {\tt char[l\_nm]} & \\
  43 \hline
  44 \multicolumn{7}{|c|}{\textcolor{gray}{\it List of indices (n=n\_ref)}}\\
  45 \cline{2-7}
  46 \hspace{0.1cm} & \multicolumn{3}{l|}{\tt n\_bin} & \# distinct bins (for the binning index) & {\tt int32\_t} & \\
  47 \cline{2-7}
  48  & \multicolumn{6}{c|}{\textcolor{gray}{\it List of distinct bins (n=n\_bin)}} \\
  49 \cline{3-7}
  50  & \hspace{0.1cm} & \multicolumn{2}{l|}{\tt bin} & Distinct bin number & {\tt uint32\_t} & \\
  51 \cline{3-7}
  52  & & \multicolumn{2}{l|}{\tt n\_chunk} & \# chunks & {\tt int32\_t} & \\
  53 \cline{3-7}
  54  & & \multicolumn{5}{c|}{\textcolor{gray}{\it List of chunks (n=n\_chunk)}} \\
  55 \cline{4-7}
  56  & & \hspace{0.1cm} & {\tt cnk\_beg} & Virtual file offset of the start of the chunk & {\tt uint64\_t} & \\
  57 \cline{4-7}
  58  & & & {\tt cnk\_end} & Virtual file offset of the end of the chunk & {\tt uint64\_t} & \\
  59 \cline{2-7}
  60  & \multicolumn{3}{l|}{\tt n\_intv} & \# 16kb intervals (for the linear index) & {\tt int32\_t} & \\
  61 \cline{2-7}
  62  & \multicolumn{6}{c|}{\textcolor{gray}{\it List of distinct intervals (n=n\_intv)}} \\
  63 \cline{3-7}
  64  & & \multicolumn{2}{l|}{\tt ioff} & File offset of the first record in the interval & {\tt uint64\_t} & \\
  65 \hline
  66 \end{tabular}
  67 \end{center}
  68
  69 {\bf Notes:}
  70
  71 \begin{itemize}
  72 \item The index file is BGZF compressed.
  73 \item All integers are little-endian.
  74 \item When {\tt (format\&0x10000)} is true, the coordinate follows the
  75   {\tt BED} rule (i.e. half-closed-half-open and zero based); otherwise,
  76   the coordinate follows the {\tt GFF} rule (closed and one based).
  77 \item For the SAM format, the end of a region equals {\tt POS} plus the
  78   reference length in the alignment, inferred from {\tt CIGAR}. For the
  79   VCF format, the end of a region equals {\tt POS} plus the size of the
  80   deletion.
  81 \item Field {\tt col\_beg} may equal {\tt col\_end}, and in this case,
  82   the end of a region is {\tt end}={\tt beg+1}.
  83 \item Example. For {\tt GFF}, {\tt format}=0, {\tt col\_seq}=1, {\tt
  84     col\_beg}=4, {\tt col\_end}=5, {\tt meta}=`{\tt \#}' and {\tt
  85     skip}=0. For {\tt BED}, {\tt format}=0x10000, {\tt col\_seq}=1, {\tt
  86     col\_beg}=2, {\tt col\_end}=3, {\tt meta}=`{\tt \#}' and {\tt
  87     skip}=0.
  88 \item Given a zero-based, half-closed and half-open region {\tt
  89     [beg,end)}, the {\tt bin} number is calculated with the following C
  90   function:
  91 \begin{verbatim}
  92 int reg2bin(int beg, int end) {
  93   --end;
  94   if (beg>>14 == end>>14) return ((1<<15)-1)/7 + (beg>>14);
  95   if (beg>>17 == end>>17) return ((1<<12)-1)/7 + (beg>>17);
  96   if (beg>>20 == end>>20) return  ((1<<9)-1)/7 + (beg>>20);
  97   if (beg>>23 == end>>23) return  ((1<<6)-1)/7 + (beg>>23);
  98   if (beg>>26 == end>>26) return  ((1<<3)-1)/7 + (beg>>26);
  99   return 0;
 100 }
 101 \end{verbatim}
 102 \item The list of bins that may overlap a region {\tt [beg,end)} can be
 103   obtained with the following C function.
 104 \begin{verbatim}
 105 #define MAX_BIN (((1<<18)-1)/7)
 106 int reg2bins(int rbeg, int rend, uint16_t list[MAX_BIN])
 107 {
 108   int i = 0, k;
 109   --rend;
 110   list[i++] = 0;
 111   for (k =    1 + (rbeg>>26); k <=    1 + (rend>>26); ++k) list[i++] = k;
 112   for (k =    9 + (rbeg>>23); k <=    9 + (rend>>23); ++k) list[i++] = k;
 113   for (k =   73 + (rbeg>>20); k <=   73 + (rend>>20); ++k) list[i++] = k;
 114   for (k =  585 + (rbeg>>17); k <=  585 + (rend>>17); ++k) list[i++] = k;
 115   for (k = 4681 + (rbeg>>14); k <= 4681 + (rend>>14); ++k) list[i++] = k;
 116   return i; // #elements in list[]
 117 }
 118 \end{verbatim}
 119 \end{itemize}
 120
 121 \end{document}