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
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
|
.. include:: includeme.rst
.. _installation:
Installation
------------
:mod:`pybedtools` is a Python package that wraps BEDTools, so you'll need both
installed.
.. _condainstall:
Install via `conda`
~~~~~~~~~~~~~~~~~~~
This is by far the easiest option. If you're usng the `Anaconda Python
distribution <http://continuum.io/downloads>`_ on Linux, then the following
will install :mod:`pybedtools`::
conda install --channel conda-forge --channel bioconda pybedtools
You can also install Tabix and BEDTools via conda::
conda install --channel conda-forge --channel bioconda bedtools htslib
Otherwise, read on for installation on other platforms and in other
environments.
Required
++++++++
:Python_: version 3.6 or greater (Python 3 is supported). If you're setting up
Python for the first time, the `Anaconda Python distribution
<http://continuum.io/downloads>`_ is highly recommended.
:BEDTools_:
The version is not important, but later versions will have more features so
it's a good idea to get the latest. Follow the instructions at
https://github.com/arq5x/bedtools2 to install, and make sure the programs
are on your path. That is, you should be able to call `bedtools` from
any directory
:A C/C++ compiler:
* **OSX:** Install Xcode from http://developer.apple.com/xcode/
* **Linux:** `gcc`, usually already installed; on Ubuntu, install with `sudo apt-get install
build-essentials`
* **Windows:** may work with conda compliers or Cygwin but this is
untested. Windows is not supported.
Optional
++++++++
The following external tools are **optional**:
:Tabix_ [`download page`_]:
Required for fast, random access to BED/GFF/GTF/VCF files by providing
a chrom:start-stop coordinate. Similar to the above, you should be able to
call `tabix` from any directory.
Installing :mod:`pybedtools`
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Install latest release via `conda` (recommended)
++++++++++++++++++++++++++++++++++++++++++++++++
See :ref:`condainstall` section above.
Install latest release using `pip`
++++++++++++++++++++++++++++++++++
:mod:`pybedtools` is on PyPI, so you can install via `pip` like most Python
packages. Depending on your Python installation, this may require admin
rights::
pip install pybedtools
Install development version via github
++++++++++++++++++++++++++++++++++++++
Assumptions:
1. `git` is installed
2. Cython is installed (`conda install cython` or `pip install cython`)
The following commands will clone the repository
.. code-block:: bash
git clone https://github.com/daler/pybedtools.git
cd pybedtools
The only time the C++ files will be rebuilt from Cython .pyx source is if the
`cythonize` subcommand is used. To rebuild the C++ files using Cython, run:
.. code-block:: bash
python setup.py cythonize
To install in develop mode, where changes to Python files will be picked up
without having to re-install, use:
.. code-block:: bash
python setup.py develop
The above will not update when the .pyx files are updated, so if the Cython
source files have been changed, run:
.. code-block:: bash
python setup.py cythonize develop
See `python setup.py --usage` for more information.
Quick test
~~~~~~~~~~
Paste the following into a new file called `mytest.py`::
import pybedtools
a = pybedtools.example_bedtool('a.bed')
b = pybedtools.example_bedtool('b.bed')
print a.intersect(b)
Run the script with `python mytest.py`. You should get the results::
chr1 155 200 feature2 0 +
chr1 155 200 feature3 0 -
chr1 900 901 feature4 0 +
Running tests, compiling docs
-----------------------------
There are several modes of testing described below, and in each mode both unit
tests and doctests can be run.
The following instructions assume that you have a working copy of the
:mod:`pybedtools` repository and that you're in the top-level dir of repo,
e.g., by running::
git clone https://github.com/daler/pybedtools.git
cd pybedtools
Test current installation
~~~~~~~~~~~~~~~~~~~~~~~~~
To test within the existing installation, install the additional packages for
testing::
conda install --channel conda-forge --channel bioconda \
--file requirements.txt \
--file test-requirements.txt \
--file optional-requirements.txt
Then run unit tests along with module doctests::
pytest --doctest-modules
Finally, run sphinx doctests::
(cd docs && make doctest)
Test within isolated conda environments
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Run the `condatest.sh` script in the top-level dir of the repo. This script
creates a new isolated conda environment and runs both unit tests and doctests.
To run tests under Python 2::
./condatest.sh 2
To run tests under Python 3::
./condatest.sh 3
Compile docs
~~~~~~~~~~~~
To compile the docs, from the top-level `pybedtools` directory::
(cd docs && make html)
Then point a browser to `docs/build/html/index.html`.
Contributing
~~~~~~~~~~~~
Any and all contributions are welcome. Here's how to contribute:
#. Fork the `pybedtools repository <http://github.com/daler/pybedtools>`_ on
github (see `forking help <http://help.github.com/fork-a-repo/>`_).
#. Make your changes/fixes/improvements locally.
#. Optional, but much-appreciated: write some tests for your changes.
(Don't worry about integrating your tests into the test framework. You
can just attach the tests either as a commited script or as comments to
the commit and I can integrate them later)
#. Send a pull request (see `pull request help <http://help.github.com/send-pull-requests/>`_)
|
