sequana-chipseq 0.12.0

Installation

pip install sequana_chipseq --upgrade

You will also need the third-party tools listed under Requirements below.

Quick Start

1. Prepare a design file design.csv:

type,condition,replicat,sample_name
IP,EXP1,1,IP_EXP1_rep1
IP,EXP1,2,IP_EXP1_rep2
Input,EXP1,1,Input_EXP1

• type must be IP (immunoprecipitated) or Input (control).

• sample_name must match the prefix of the corresponding FastQ file (e.g. IP_EXP1_rep1 matches IP_EXP1_rep1_R1_.fastq.gz).

• At least two IP replicates per condition are required for IDR analysis.

2. Prepare a genome directory named after the genome, containing:

• <name>.fa — reference genome FASTA

• <name>.gff or <name>.gff3 — gene annotation

Example:

ecoli_MG1655/
├── ecoli_MG1655.fa
└── ecoli_MG1655.gff

3. Set up the pipeline:

sequana_chipseq \
    --input-directory DATAPATH \
    --genome-directory /path/to/ecoli_MG1655 \
    --design-file design.csv

4. Run the pipeline:

cd chipseq
sh chipseq.sh

Usage

sequana_chipseq --help

Key pipeline-specific options:

--genome-directory

Path to the genome directory (must contain <name>.fa and <name>.gff).

--design-file

CSV experimental design file (see Quick Start above).

--aligner-choice

Aligner to use. Currently only bowtie2 is supported.

--blacklist-file

BED3 file of genomic regions to exclude from analysis (tab-separated: chromosome, start, end).

--genome-size

Effective genome size for macs3 peak calling. Automatically computed from the FASTA file if not provided; override with a plain integer.

--do-fingerprints

Enable plotFingerprint QC to assess ChIP enrichment quality.

Run on a SLURM cluster:

cd chipseq
sbatch chipseq.sh

Or drive Snakemake directly:

snakemake -s chipseq.rules --cores 4 --stats stats.txt

Usage with Apptainer

Run every tool inside pre-built containers — no local tool installation needed:

sequana_chipseq \
    --input-directory DATAPATH \
    --genome-directory /path/to/genome \
    --design-file design.csv \
    --use-apptainer

Store images in a shared location to avoid re-downloading:

sequana_chipseq ... --use-apptainer --apptainer-prefix ~/.sequana/apptainers

Then run as usual:

cd chipseq
sh chipseq.sh

Requirements

The following tools must be available (install via conda/bioconda):

mamba env create -f environment.yml

• bowtie2 — read alignment

• fastp — adapter trimming and quality filtering

• fastqc — per-read quality control

• samtools — BAM sorting, indexing, and flagstat

• bedtools — bedGraph generation from BAM files (genomeCoverageBed)

• ucsc-bedgraphtobigwig — bedGraph to bigWig conversion (bedGraphToBigWig)

• deeptools — fingerprint QC (plotFingerprint) and multi-sample bigwig summary (multiBigwigSummary)

• macs3 — narrow and broad peak calling

• homer — peak annotation (annotatePeaks.pl)

• idr — Irreproducibility Discovery Rate between replicates (installed from sequana/idr fork via pip; the upstream bioconda package is Python 3.10-only)

• multiqc — aggregated QC report

Pipeline overview

1. Trimming — fastp removes low-quality reads and adapters.

2. QC — FastQC on raw and cleaned reads.

3. Alignment — bowtie2 maps reads to the reference genome.

4. [Optional] Mark duplicates — Picard marks PCR duplicates.

5. [Optional] Blacklist removal — bedtools removes artefact-prone regions.

6. bigwig — per-sample coverage tracks for genome browsers (bedtools genomeCoverageBed → UCSC bedGraphToBigWig); an IGV session file (igv.xml) is generated to preload all tracks.

7. [Optional] Fingerprints — plotFingerprint QC to assess ChIP enrichment.

8. Phantom peak — strand cross-correlation analysis (NSC, RSC, Qtag scores).

9. Peak calling — macs3 detects narrow and broad peaks for each IP vs Input pair.

10. FRiP — Fraction of Reads in Peaks per sample and comparison.

11. IDR — Irreproducibility Discovery Rate on true replicates, pseudo-replicates, and self-pseudo-replicates.

12. Annotation — homer annotates peaks relative to genomic features.

13. MultiQC — aggregated QC across all samples.

14. HTML report — summary with phantom peaks, FRiP plots, IDR tables, and annotation plots.

Configuration

Here is the latest documented configuration file. Key sections:

• general — aligner choice and genome directory path

• fastp — trimming options (length, quality, adapters)

• fastqc — FastQC options and threads

• bowtie2_mapping / bowtie2_index — mapping options, threads, memory

• macs3 — peak calling parameters (genome size, bandwidth, q-value, broad cutoff)

• idr — IDR thresholds, rank metric, number of pseudo-replicates

• fingerprints — enable/disable and number of bins

• mark_duplicates — enable/disable PCR duplicate marking

• remove_blacklist — enable/disable and path to BED blacklist

• trimming — enable/disable read trimming and choice of trimming tool

• phantom — use SPP (use_spp: true) instead of the built-in sequana phantom-peak detection

• igv — enable/disable generation of the IGV session file (igv.xml)

• multiqc — MultiQC options

Changelog

Contribute & Code of Conduct

To contribute to this project, please take a look at the Contributing Guidelines first. Please note that this project is released with a Code of Conduct. By contributing to this project, you agree to abide by its terms.