1bgzip(1) Bioinformatics tools bgzip(1)
2
3
4
6 bgzip - Block compression/decompression utility
7
9 bgzip [-cdfhir] [-b virtualOffset] [-I index_name] [-l compres‐
10 sion_level] [-s size] [-@ threads] [file]
11
13 Bgzip compresses files in a similar manner to, and compatible with,
14 gzip(1). The file is compressed into a series of small (less than 64K)
15 'BGZF' blocks. This allows indexes to be built against the compressed
16 file and used to retrieve portions of the data without having to decom‐
17 press the entire file.
18
19 If no files are specified on the command line, bgzip will compress (or
20 decompress if the -d option is used) standard input to standard output.
21 If a file is specified, it will be compressed (or decompressed with
22 -d). If the -c option is used, the result will be written to standard
23 output, otherwise when compressing bgzip will write to a new file with
24 a .gz suffix and remove the original. When decompressing the input
25 file must have a .gz suffix, which will be removed to make the output
26 name. Again after decompression completes the input file will be
27 removed.
28
29
31 -b, --offset INT
32 Decompress to standard output from virtual file position
33 (0-based uncompressed offset). Implies -c and -d.
34
35 -c, --stdout
36 Write to standard output, keep original files unchanged.
37
38 -d, --decompress
39 Decompress.
40
41 -f, --force
42 Overwrite files without asking.
43
44 -h, --help
45 Displays a help message.
46
47 -i, --index
48 Create a BGZF index while compressing. Unless the -I option
49 is used, this will have the name of the compressed file with
50 .gzi appended to it.
51
52 -I, --index-name FILE
53 Index file name.
54
55 -l, --compress-level INT
56 Compression level to use when compressing. From 0 to 9, or
57 -1 for the default level set by the compression library. [-1]
58
59 -r, --reindex
60 Rebuild the index on an existing compressed file.
61
62 -g, --rebgzip
63 Try to use an existing index to create a compressed file with
64 matching block offsets. Note that this assumes that the same
65 compression library and level are in use as when making the
66 original file. Don't use it unless you know what you're
67 doing.
68
69 -s, --size INT
70 Decompress INT bytes (uncompressed size) to standard output.
71 Implies -c.
72
73 -@, --threads INT
74 Number of threads to use [1].
75
77 The BGZF format written by bgzip is described in the SAM format speci‐
78 fication available from http://samtools.github.io/hts-specs/SAMv1.pdf.
79
80 It makes use of a gzip feature which allows compressed files to be con‐
81 catenated. The input data is divided into blocks which are no larger
82 than 64 kilobytes both before and after compression (including compres‐
83 sion headers). Each block is compressed into a gzip file. The gzip
84 header includes an extra sub-field with identifier 'BC' and the length
85 of the compressed block, including all headers.
86
87
89 The index format is a binary file listing pairs of compressed and
90 uncompressed offsets in a BGZF file. Each compressed offset points to
91 the start of a BGZF block. The uncompressed offset is the correspond‐
92 ing location in the uncompressed data stream.
93
94 All values are stored as little-endian 64-bit unsigned integers.
95
96 The file contents are:
97
98 uint64_t number_entries
99
100 followed by number_entries pairs of:
101
102 uint64_t compressed_offset
103 uint64_t uncompressed_offset
104
105
106
108 # Compress stdin to stdout
109 bgzip < /usr/share/dict/words > /tmp/words.gz
110
111 # Make a .gzi index
112 bgzip -r /tmp/words.gz
113
114 # Extract part of the data using the index
115 bgzip -b 367635 -s 4 /tmp/words.gz
116
117 # Uncompress the whole file, removing the compressed copy
118 bgzip -d /tmp/words.gz
119
120
121
123 The BGZF library was originally implemented by Bob Handsaker and modi‐
124 fied by Heng Li for remote file access and in-memory caching.
125
126
128 gzip(1), tabix(1)
129
130
131
132htslib-1.9 18 July 2018 bgzip(1)