peak-classifier classify ChIP/ATAC-Seq peaks based on features provided in a GFF file.
Peaks are provided in a BED file sorted by chromosome and position. Typically these are output from a peak caller such as MACS2, or the differential analysis that follows. The GFF must also be sorted by chromosome, position, and subfeature, which is the default for common data sources.
Peak-classifier generates features that are not explicitly identified in the GFF, such as introns and potential promoter regions, and outputs the augmented feature list to a BED file. It then identifies overlapping features by running bedtools intersect on the augmented feature list and peak list, outputting an annotated BED-like TSV file with additional columns to describe the feature. If a peak overlaps multiple features, a separate line is output for each.
Alternative approaches to this problem include R scripting with a tool such as ChIPpeakAnno or multistage processing of the GFF using awk and bedtools.
In contrast, peak-classifier is a simple Unix command that takes a BED file and a GFF file as inputs and reports all peak classifications in a matter of seconds.
Admittedly, an optimal C program isn't really necessary to solve this problem, since the crappiest implementation I can imagine would not take more than hours to run for a typical ATAC-Seq peak set. However:
* It's an opportunity to develop and test biolibc code that will be
useful for other problems and bigger data
* It's more about making peak classification convenient than fast
* It never hurts to hone your C skills
* There's no such thing as a program that's too fast
The code is organized following basic object-oriented design principals, but implemented in C to minimize overhead and keep the source code accessible to scientists who don't have time to master the complexities of C++.
Structures are treated as classes, with accessor macros and mutator functions provided, so dependent applications and libraries need not access structure members directly. Since the C language cannot enforce this, it's up to application programmers to exercise self-discipline.
peak-classifier is intended to build cleanly in any POSIX environment on any CPU architecture. Please don't hesitate to open an issue if you encounter problems on any Unix-like system.
Primary development is done on FreeBSD with clang, but the code is frequently tested on Linux, MacOS, NetBSD, and OpenIndiana as well. MS Windows is not supported, unless using a POSIX environment such as Cygwin or Windows Subsystem for Linux.
The Makefile is designed to be friendly to package managers, such as Debian packages, FreeBSD ports, MacPorts, dreckly, etc.
End users should install using a package manager, to ensure that dependencies are properly managed.
I maintain a FreeBSD port and a dreckly package, which is sufficient to install cleanly on virtually any POSIX platform. If you would like to see a package in another package manager, please consider creating a package yourself. This will be one of the easiest packages in the collection and hence a good vehicle to learn how to create packages.
Note that dreckly can be used by anyone, on virtually any POSIX operating system, with or without administrator privileges.
For an overview of available package managers, see the Repology website.
FreeBSD is a highly underrated platform for scientific computing, with over 2,000 scientific libraries and applications in the FreeBSD ports collection (of more than 30,000 total), modern clang compiler, fully-integrated ZFS filesystem, and renowned security, performance, and reliability. FreeBSD has a somewhat well-earned reputation for being difficult to set up and manage compared to user-friendly systems like Ubuntu. However, if you're a little bit Unix-savvy, you can very quickly set up a workstation, laptop, or VM using desktop-installer. GhostBSD offers an experience very similar to Ubuntu, but is built on FreeBSD rather than Debian Linux. GhostBSD packages lag behind FreeBSD ports slightly, but this is not generally an issue and there are workarounds.
To install the binary package on FreeBSD:
pkg install peak-classifier
You can just as easily build and install from source. This is useful for FreeBSD ports with special build options, for building with non-portable optimizations such as -march=native, and for work-in-progress ports, for which binary packages are not yet maintained.
cd /usr/ports/biology/peak-classifier && env CFLAGS='-march=native -O2' make install
cd /usr/ports/wip/peak-classifier && make install
Dreckly is a cross-platform package manager that works on any Unix-like platform. It is derived from pkgsrc, which is part of NetBSD, and well-supported on Illumos, MacOS, RHEL/CentOS, and many other Linux distributions. Unlike most package managers, using dreckly does not require admin privileges. You can install a dreckly tree in any directory to which you have write access and easily install any of the nearly 20,000 packages in the collection.
The auto-dreckly-setup script will help you install dreckly in about 10 minutes. Just download it and run
sh auto-dreckly-setup
Then, assuming you selected current packages and the default prefix
source ~/Dreckly/pkg/etc/dreckly.sh # Or dreckly.csh for csh or tcsh
cd ~/Dreckly/dreckly/biology/peak-classifier
sbmake install clean clean-depends
If you would like to add this project to another package manager rather than use FreeBSD ports or dreckly, basic manual build instructions for package can be found here. Your contribution is greatly appreciated!