c_cpp/lib/htslib/tabix.1

   1 .TH tabix 1 "21 June 2017" "htslib-1.5" "Bioinformatics tools"
   2 .SH NAME
   3 .PP
   4 bgzip \- Block compression/decompression utility
   5 .PP
   6 tabix \- Generic indexer for TAB-delimited genome position files
   7 .\"
   8 .\" Copyright (C) 2009-2011 Broad Institute.
   9 .\"
  10 .\" Author: Heng Li <lh3@sanger.ac.uk>
  11 .\"
  12 .\" Permission is hereby granted, free of charge, to any person obtaining a
  13 .\" copy of this software and associated documentation files (the "Software"),
  14 .\" to deal in the Software without restriction, including without limitation
  15 .\" the rights to use, copy, modify, merge, publish, distribute, sublicense,
  16 .\" and/or sell copies of the Software, and to permit persons to whom the
  17 .\" Software is furnished to do so, subject to the following conditions:
  18 .\"
  19 .\" The above copyright notice and this permission notice shall be included in
  20 .\" all copies or substantial portions of the Software.
  21 .\"
  22 .\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
  23 .\" IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
  24 .\" FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
  25 .\" THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
  26 .\" LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
  27 .\" FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
  28 .\" DEALINGS IN THE SOFTWARE.
  29 .\"
  30 .SH SYNOPSIS
  31 .PP
  32 .B bgzip
  33 .RB [ -cdhB ]
  34 .RB [ -b
  35 .IR virtualOffset ]
  36 .RB [ -s
  37 .IR size ]
  38 .RI [ file ]
  39 .PP
  40 .B tabix
  41 .RB [ -0lf ]
  42 .RB [ -p
  43 gff|bed|sam|vcf]
  44 .RB [ -s
  45 .IR seqCol ]
  46 .RB [ -b
  47 .IR begCol ]
  48 .RB [ -e
  49 .IR endCol ]
  50 .RB [ -S
  51 .IR lineSkip ]
  52 .RB [ -c
  53 .IR metaChar ]
  54 .I in.tab.bgz
  55 .RI [ "region1 " [ "region2 " [ ... "]]]"
  56
  57 .SH DESCRIPTION
  58 .PP
  59 Tabix indexes a TAB-delimited genome position file
  60 .I in.tab.bgz
  61 and creates an index file (
  62 .I in.tab.bgz.tbi
  63 or
  64 .I in.tab.bgz.csi
  65 ) when
  66 .I region
  67 is absent from the command-line. The input data file must be position
  68 sorted and compressed by
  69 .B bgzip
  70 which has a
  71 .BR gzip (1)
  72 like interface.
  73
  74 After indexing, tabix is able to quickly retrieve data lines overlapping
  75 .I regions
  76 specified in the format "chr:beginPos-endPos".
  77 (Coordinates specified in this region format are 1-based and inclusive.)
  78
  79 Fast data retrieval also
  80 works over network if URI is given as a file name and in this case the
  81 index file will be downloaded if it is not present locally.
  82
  83 .SH INDEXING OPTIONS
  84 .TP 10
  85 .B -0, --zero-based
  86 Specify that the position in the data file is 0-based (e.g. UCSC files)
  87 rather than 1-based.
  88 .TP
  89 .BI "-b, --begin " INT
  90 Column of start chromosomal position. [4]
  91 .TP
  92 .BI "-c, --comment " CHAR
  93 Skip lines started with character CHAR. [#]
  94 .TP
  95 .BI "-C, --csi"
  96 Produce CSI format index instead of classical tabix or BAI style indices.
  97 .TP
  98 .BI "-e, --end " INT
  99 Column of end chromosomal position. The end column can be the same as the
 100 start column. [5]
 101 .TP
 102 .B "-f, --force "
 103 Force to overwrite the index file if it is present.
 104 .TP
 105 .BI "-m, --min-shift " INT
 106 set minimal interval size for CSI indices to 2^INT [14]
 107 .TP
 108 .BI "-p, --preset " STR
 109 Input format for indexing. Valid values are: gff, bed, sam, vcf.
 110 This option should not be applied together with any of
 111 .BR -s ", " -b ", " -e ", " -c " and " -0 ;
 112 it is not used for data retrieval because this setting is stored in
 113 the index file. [gff]
 114 .TP
 115 .BI "-s, --sequence " INT
 116 Column of sequence name. Option
 117 .BR -s ", " -b ", " -e ", " -S ", " -c " and " -0
 118 are all stored in the index file and thus not used in data retrieval. [1]
 119 .TP
 120 .BI "-S, --skip-lines " INT
 121 Skip first INT lines in the data file. [0]
 122
 123 .SH QUERYING AND OTHER OPTIONS
 124 .TP
 125 .B "-h, --print-header "
 126 Print also the header/meta lines.
 127 .TP
 128 .B "-H, --only-header "
 129 Print only the header/meta lines.
 130 .TP
 131 .B "-l, --list-chroms "
 132 List the sequence names stored in the index file.
 133 .TP
 134 .B "-r, --reheader " FILE
 135 Replace the header with the content of FILE
 136 .TP
 137 .B "-R, --regions " FILE
 138 Restrict to regions listed in the FILE. The FILE can be BED file (requires .bed, .bed.gz, .bed.bgz
 139 file name extension) or a TAB-delimited file with CHROM, POS, and,  optionally,
 140 POS_TO columns, where positions are 1-based and inclusive.  When this option is in use, the input
 141 file may not be sorted.
 142 regions.
 143 .TP
 144 .B "-T, --targets" FILE
 145 Similar to
 146 .B -R
 147 but the entire input will be read sequentially and regions not listed in FILE will be skipped.
 148 .PP
 149 .SH EXAMPLE
 150 (grep ^"#" in.gff; grep -v ^"#" in.gff | sort -k1,1 -k4,4n) | bgzip > sorted.gff.gz;
 151
 152 tabix -p gff sorted.gff.gz;
 153
 154 tabix sorted.gff.gz chr1:10,000,000-20,000,000;
 155
 156 .SH NOTES
 157 It is straightforward to achieve overlap queries using the standard
 158 B-tree index (with or without binning) implemented in all SQL databases,
 159 or the R-tree index in PostgreSQL and Oracle. But there are still many
 160 reasons to use tabix. Firstly, tabix directly works with a lot of widely
 161 used TAB-delimited formats such as GFF/GTF and BED. We do not need to
 162 design database schema or specialized binary formats. Data do not need
 163 to be duplicated in different formats, either. Secondly, tabix works on
 164 compressed data files while most SQL databases do not. The GenCode
 165 annotation GTF can be compressed down to 4%.  Thirdly, tabix is
 166 fast. The same indexing algorithm is known to work efficiently for an
 167 alignment with a few billion short reads. SQL databases probably cannot
 168 easily handle data at this scale. Last but not the least, tabix supports
 169 remote data retrieval. One can put the data file and the index at an FTP
 170 or HTTP server, and other users or even web services will be able to get
 171 a slice without downloading the entire file.
 172
 173 .SH AUTHOR
 174 .PP
 175 Tabix was written by Heng Li. The BGZF library was originally
 176 implemented by Bob Handsaker and modified by Heng Li for remote file
 177 access and in-memory caching.
 178
 179 .SH SEE ALSO
 180 .PP
 181 .BR samtools (1)