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