The chompR package is designed to perform peak-calling and differential analysis of ChIP or ATAC-seq data. It provides tools to:
The chompR package does not attempt to replace the tools it uses, but instead provides an automated environment in which to use them.
The website for chompR may be found here.
The workflow used by chompR requires the installation of several command-line tools: Fastqc (v0.11.7), MultiQC (v1.6), fastp (v0.19.4), SAMtools (v1.9), Sambamba (v0.6.7), HISAT2 (v2.1.0), MACS (v2.1.0), and featureCounts (v1.6.2). Installation instructions for these may be found at their respective websites, but a guide is given below for convenience.
If using a Unix-based system, open up a terminal and follow the commands as is. If using the windows subsystem for linux (WSL) on Windows 10 then WSL must first be set up as detailed here. Once WSL is up and running, then the tools may be installed as on any Unix-based system.
It is assumed that root priviliges are available (if necessary) - if not, then a system administrator may need to install these for you.
To run MACS2 ensure there is a working python (>2.7) distribution. GCC is also required to compile .c
codes (this should be pre-installed with your UNIX distribution) and python header files are needed. Therefore, python-dev
must also be installed.
cd ~
wget -O subread.tar.gz https://sourceforge.net/projects/subread/files/subread-1.6.2/subread-1.6.2-Linux-x86_64.tar.gz/download
tar xvf subread.tar.gz
# If using WSL
cd /usr/local/bin
sudo ln -s ~/subread-1.6.2-Linux-x86_64/bin/sub* .
sudo ln -s ~/subread-1.6.2-Linux-x86_64/bin/exactSNP .
sudo ln -s ~/subread-1.6.2-Linux-x86_64/bin/featureCounts .
sudo ln -s ~/subread-1.6.2-Linux-x86_64/bin/utilities/* .
# If using other Unix
cd ~/bin
sudo ln -s ~/subread-1.6.2-Linux-x86_64/bin/sub* .
sudo ln -s ~/subread-1.6.2-Linux-x86_64/bin/exactSNP .
sudo ln -s ~/subread-1.6.2-Linux-x86_64/bin/featureCounts .
sudo ln -s ~/subread-1.6.2-Linux-x86_64/bin/utilities/* .
There are a number of dependencies to the chompR package detailed in the DESCRIPTION
file. These are either CRAN or Bioconductor packages. These dependencies will automatically install when installing chompR.
The entire workflow of chompR may be run by a call to a single function run_chip()
or run_atac()
, as shown below.
result_chip <- run_chip(sample.info = `system.file("extdata", "paired-example.txt", pkg ="chompR")`,
reference = c("WT", "KO1", "KO2"), species = "human", output.dir = "results-chip",
threads = NULL, index.dir = NULL)
The arguments to the run_chip()
and run_atac()
functions are:
This is the path to a tab-delimited file with at least the columns:
condition
: treatment or condition labels on the basis of which the differential analysis will be performed (e.g. “CONTROL”, “TREATED”; or “WILD-TYPE”, “KNOCK-OUT1”, “KNOCK-OUT2”).sample
: names of the samples - these labels will be used in plots and as sample column headers in the output.file1
: absolute or relative path to fastq files.Optional columns include:
file2
: if fastq files and PE reads, then this column should also be present, specifying the absolute or relative paths to the second pair of fastq reads.batch
: if a batch effect is to be included in the design, then this should be identified under this column (e.g. litter number or sequencing run). # input1
: if ChIP-seq and input samples were used then the path to the fastq file for the input matching file1 in the same row should be included here. # input2
: same as input1, but if PE reads, then the second pair should be specified here.Dummy examples of the tab-delimited files accepted by chompR may be found at system.file("extdata", "paired-example.txt", pkg = "chompR")
, system.file("extdata", "sinle-example.txt", pkg = "chompR")
, and system.file("extdata", "quants-example.txt", pkg = "chompR")
.
The order in which the condition labels should be evaluated when performing differential analysis. For example, c(“A”, “B”, “C”, “D”) would mean “A” is the reference condition to which “B”, “C” and “D” are compared; in addition, “C” and “D” will be compared to “B”, and “D” will be compared to “C”. If then the comparisons will be arranged alphabetically.
Number of threads to be used when parallelisation is possible. If NULL
then one less than the maximum numbre of threads available will be used.
The path to the hisat2 index.
Other arguments are also possible, and details for these may be found in the manual, but for most users, the default settings are satisfactory.
Importantly, if the user has already run the analysis once and read QC and alignment has already occurred, then this will be detected and these steps will be skipped (provided the same output directory is specified).
The package also contains several functions to directly run several tools from within R. These all begin with and include , , , , , , , , . Additional functions include those to import MACS2 format peak files into R () and to annotate peaks ().
Once complete, all the results will be saved in the specified output directory with the following structure:
#> levelName
#> 1 results
#> 2 ¦--alignment_stats.txt
#> 3 ¦--bam
#> 4 ¦--consensus
#> 5 ¦--cross-correlation
#> 6 ¦--differential
#> 7 ¦--fastqc
#> 8 ¦--index
#> 9 ¦--multiqc
#> 10 ¦--filteredbam
#> 11 ¦--shifted
#> 12 ¦--trimmed
#> 13 ¦--peaks
#> 14 ¦--DESeq2
#> 15 °--fragmentLength
The directories DESeq2
, fastqc
, and multiqc
contain the results of the respective analyses including relevant plots. The index
directory contains the hisat2 index for human or mouse; it will only be creeated if a pre-existing index was not specified beforehand. The bam
, filteredbam
, trimmedbam
, and shifted
directories contain BAM files. The shifted
directory only exists for ATAC-seq analysis and contains BAM files whose reads have been shifted to take account of transposon insertion. The peaks
and consensus
directories contain MACS2 called peaks and consensus peaks respectively. The differential
directory contains the results of the a binary differential analysis i.e. peaks present or absent in each sample. The cross-correlation
and fragmentlength
directories are only created for ChIP_seq or ATAC-seq respectively (i.e. they are mutually exclusive) and contain QC plots following alignment. The alignment_stats.txt
file contains simple alignment statistics.
Importantly, if the user has already run the analysis once and read QC and alignment has already occurred, then this will be detected and these steps will be skipped (provided the same output directory is specified).
GREAT analysis (using the GREAT website) is performed using the package rGREAT. A wrapper script, which converts regions into hg19 co-ordinates (if using “human”) and then runs the rGREAT package, is included.
peaks <- peak2Granges("peaks/results.narrowPeak")
pathway <- run_great(regions = peaks, species = "human")
This may be repeated as necessary for the other comparisons.