1############
2FAQ
3############
4
5
6====================
7Installation issues
8====================
9
10--------------------------------------------------
11Why am I getting all of these zlib errors?
12--------------------------------------------------
13
14On certain operating systems (especially free Linux distributions) the complete
15zlib libraries are not installed.  Bedtools depends upon zlib in order to
16decompress gzipped files.
17
18.. code-block:: bash
19
20    - Building main bedtools binary.
21    obj/gzstream.o: In function gzstreambuf::open(char const*, int):
22    gzstream.C:(.text+0x2a5): undefined reference to gzopen64'
23    collect2: ld returned 1 exit status
24    make: *** [all] Error 1
25
26If you see an error such as the above, it suggests you need to install the
27``zlib`` and ``zlib1g-dev`` libraries.  This is typically straightforward using
28package managers.  For example, on Debian/Ubuntu this would be:
29
30.. code-block:: bash
31
32    apt-get install zlib
33    apt-get install zlib1g-dev
34
35and on Fedora/Centos this would be:
36
37.. code-block:: bash
38
39    yum install zlib
40    yum install zlib1g-dev
41
42--------------------------------------------------
43Compiling with a specific zlib library
44--------------------------------------------------
45If you need to override the location of the zlib library used to compile bedtools, you can run `make` and specify the `LIBS` argument. For example:
46
47.. code-block:: bash
48
49    make LIBS='/PATH/TO/ZLIB/lib/libz.a'
50
51====================
52General questions
53====================
54
55
56--------------------------------------------------
57How do I know what version of bedtools I am using?
58--------------------------------------------------
59
60Use the --version option.
61
62.. code-block:: bash
63
64    $ bedtools --version
65    bedtools v2.17.0
66
67
68--------------------------------------------------
69How do I bring up the help/usage menu?
70--------------------------------------------------
71
72To receive a high level list of available tools in bedtools, use ```-h``:
73
74.. code-block:: bash
75
76    $ bedtools -h
77    bedtools: flexible tools for genome arithmetic and DNA sequence analysis.
78    usage:    bedtools <subcommand> [options]
79
80    The bedtools sub-commands include:
81
82    [ Genome arithmetic ]
83        intersect     Find overlapping intervals in various ways.
84        window        Find overlapping intervals within a window around an interval.
85        closest       Find the closest, potentially non-overlapping interval.
86        coverage      Compute the coverage over defined intervals.
87        map           Apply a function to a column for each overlapping interval.
88        genomecov     Compute the coverage over an entire genome.
89        merge         Combine overlapping/nearby intervals into a single interval.
90        cluster       Cluster (but don't merge) overlapping/nearby intervals.
91        complement    Extract intervals _not_ represented by an interval file.
92    ...
93
94To display the help for a specific tool (e.g., ``bedtools shuffle``), use:
95
96.. code-block:: bash
97
98    $ bedtools merge -h
99
100    Tool:    bedtools merge (aka mergeBed)
101    Version: v2.17.0
102    Summary: Merges overlapping BED/GFF/VCF entries into a single interval.
103
104    Usage:   bedtools merge [OPTIONS] -i <bed/gff/vcf>
105
106    Options:
107    	-s	Force strandedness.  That is, only merge features
108    		that are the same strand.
109    		- By default, merging is done without respect to strand.
110
111    	-n	Report the number of BED entries that were merged.
112    		- Note: "1" is reported if no merging occurred.
113
114
115
116
117
118====================
119Issues with output
120====================
121
122------------------------------------------------------------------------
123I *know* there are overlaps, but none are reported. What might be wrong?
124------------------------------------------------------------------------
125
126There are two common causes of this problem.  The first cause is non-obvious
127differences in the way chromosomes are named in files being compared.
128For example, "1" is not the same as "chr1" just as "   chr1" is not the same
129as "chr1".  Secondly, users often copy files from a Windows machine to a UNIX
130machine.  This causes issues because Windows uses two bytes to represent
131the end of a line (``\r\n``) whereas the UNIX convention uses a single byte
132(``\n``).  If your files don't conform to the UNIX convention, you will have
133problems.  One can convert files from Windows to UNIX with
134the following command:
135
136.. code-block:: bash
137
138   perl -i -p -e 's/\r\n/\n/g;' file.windows > file.unix
139
140
141
142====================
143Installation issues
144====================
145
146
147---------------------------------------------------------------------------
148Bedtools compilation fails with errors related to zlib.  How do I fix this?
149---------------------------------------------------------------------------
150
151Some systems, especially Ubuntu, do not come pre-installed with up to date
152versions of the zlib compression utilities that tools such as `bedtools` and
153`samtools` depend upon. This can cause compilation errors when you try to
154compile `bedtools`.  Errors include:
155
156.. code-block:: bash
157
158    ../utils//gzstream/gzstream.h:50: error: ‘gzFile’ does not name a type
159
160
161or
162
163.. code-block:: bash
164
165    fatal error: zlib.h: No such file or directory
166
167This indicates that you need to install the zlib libraries on your system, which
168turns out to not be too difficult through the use of package installers.  For
169example, on Ubuntu, you'd want to run:
170
171.. code-block:: bash
172
173    sudo apt-get install zlib1g-dev
174    sudo apt-get install zlib
175
176
177