Installation

pybedtools is a Python package that wraps BEDTools, so you’ll need both installed.

Install via conda

This is by far the easiest option. If you’re usng the Anaconda Python distribution on Linux, then the following will install 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 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 pybedtools

Install latest release using pip

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

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:

python setup.py cythonize

To install in develop mode, where changes to Python files will be picked up without having to re-install, use:

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:

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 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:

  1. Fork the pybedtools repository on github (see forking help).

  2. Make your changes/fixes/improvements locally.

  3. 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)

  4. Send a pull request (see pull request help)