Quickstart + Usage¶

After installing Consenrich, you can run it via the command line (consenrich -h) or programmatically using the Python/Cython API.

Getting Started: Minimal Example¶

A brief analysis using H3K27ac (narrow) ChIP-seq data generated from human tissue samples is carried out for demonstration.

Input Data¶

The input data in this example consists of four donors’ treatment and control samples (epidermal tissue) from ENCODE.

Input Data¶
Experiment	Biosample	H3K27ac Alignment	Control Alignment
ENCSR214UZE	Epidermis/Female/71	ENCFF793ZHL.bam	ENCFF444WVG.bam
ENCSR334DRN	Epidermis/Male/67	ENCFF647VPO.bam	ENCFF619NYP.bam
ENCSR340ZTB	Epidermis/Female/80	ENCFF809VKT.bam	ENCFF898LKJ.bam
ENCSR386CKJ	Epidermis/Male/75	ENCFF295EFL.bam	ENCFF490MWV.bam

Download Alignment Files from ENCODE¶

Copy+paste the following to your terminal to download and index the BAM files for this demo.

You can also use curl -O <URL> in place of wget <URL> if the latter is not available on your system.

encodeFiles=https://www.encodeproject.org/files
for file in ENCFF793ZHL ENCFF647VPO ENCFF809VKT ENCFF295EFL; do
    wget "$encodeFiles/$file/@@download/$file.bam"
done
for ctrl in ENCFF444WVG ENCFF619NYP ENCFF898LKJ ENCFF490MWV; do
    wget "$encodeFiles/$ctrl/@@download/$ctrl.bam"
done
samtools index -M *.bam

Using a YAML Configuration file¶

Tip

Refer to the <process,observation,etc.>Params classes in module in the API for complete documentation of configuration options.

Copy and paste the following YAML into a file named demoHistoneChIPSeq.yaml:

experimentName: demoHistoneChIPSeq
genomeParams.name: hg38
genomeParams.chromosomes: [chr21, chr22] # remove this line to run genome-wide
genomeParams.excludeForNorm: [chrX, chrY]
inputParams.bamFiles: [ENCFF793ZHL.bam,
ENCFF647VPO.bam,
ENCFF809VKT.bam,
ENCFF295EFL.bam]

inputParams.bamFilesControl: [ENCFF444WVG.bam,
ENCFF619NYP.bam,
ENCFF898LKJ.bam,
ENCFF490MWV.bam]

# Optional: call 'structured peaks' via `consenrich.matching`
matchingParams.templateNames: [haar, haar, db2, db2, sym3, sym3]
matchingParams.cascadeLevels: [1,2,1,2,1,2]

Control Inputs

Omit inputParams.bamFilesControl for ATAC-seq, DNase-seq, Cut&Run, and other assays where no control is available or applicable.

Run Consenrich¶

% consenrich --config demoHistoneChIPSeq.yaml --verbose

Results¶

We display Consenrich results (blue) over a 150 kb locus in human chromosome 22

Output Consenrich Signal Estimates :width: 600px :align: left

Miscellaneous Guidance¶

Consensus Peak Calling + Downstream Differential Analyses¶

Consenrich can improve between-group differential analyses that depend on a good set of initial ‘candidate’ consensus peaks (see Enhanced Consensus Peak Calling and Differential Analyses in Complex Human Disease in the manuscript preprint.)

ROCCO can accept Consenrich bigWig files as input and is well-suited to leverage high-resolution open chromatin signal estimates while balancing regularity for simultaneous broad/narrow peak calling.

For example, to run the Consenrich+ROCCO protocol as it is used in the manuscript,

% python -m pip install rocco --upgrade
% rocco -i <experimentName>_consenrich_state.bw \
   -g hg38 -o consenrichRocco_<experimentName>.bed \
   # <...>

Only Consenrich+ROCCO has been benchmarked for differential accessibility analyses to date, but alternative peak calling methods can be considered downstream, too. For example, the `matching` algorithm packaged that is packaged with Consenrich.
Other methods supporting bedGraph/bigWig input, e.g., MACS’ bdgpeakcall, LanceOTron may also be effective.