Skip to content

Latest commit

 

History

History
157 lines (122 loc) · 13.3 KB

README.md

File metadata and controls

157 lines (122 loc) · 13.3 KB
Raw

JetBrains Research license tests

SPAN Peak Analyzer

+----------------------------------+
|SPAN Semi-supervised Peak Analyzer|
+----------------------------|/----+
           ,        ,
      __.-'|'-.__.-'|'-.__
    ='=====|========|====='=
    ~_^~-^~~_~^-^~-~~^_~^~^~^

SPAN Peak Analyzer is a universal HMM-based peak caller capable of processing a broad range of ChIP-seq, ATAC-seq, and single-cell ATAC-seq datasets of different quality.

Open Access Paper: Shpynov O, Dievskii A, Chernyatchik R, Tsurinov P, Artyomov MN. Semi-supervised peak calling with SPAN and JBR Genome Browser. Bioinformatics. 2021 May 21. https://doi.org/10.1093/bioinformatics/btab376

Features

  • Supports both narrow and broad footprint experiments
  • Produces robust results on datasets of different signal-to-noise ratio, including Ultra-Low-Input ChIP-seq
  • Produces highly consistent results in multiple-replicates experiment setup
  • Tolerates missing control experiment
  • Integrated into the JetBrains Research ChIP-seq analysis pipeline from raw reads to visualization and peak calling
  • Integrated with the JBR Genome Browser, uploaded data model allows for interactive visualization and fine-tuning
  • Experimentally supports multi-replicated mode and differential peak calling mode
  • In semi-supervised mode it is capable to robustly handle multiple replicates and noise by leveraging limited manual annotation information.

Latest release

See releases section for actual information.

Requirements

Download and install Java 8+.

Peak calling

To analyze a single (possibly replicated) biological condition use analyze command. See details with command:

$ java -jar span.jar analyze --help

The <output.bed> file will contain predicted and FDR-controlled peaks in the ENCODE broadPeak (BED 6+3) format:

<chromosome> <peak start offset> <peak end offset> <peak_name> <score> . <coverage or fold/change> <-log p-value> <-log Q-value>

Examples:

  • Regular peak calling
    java -Xmx8G -jar span.jar analyze -t ChIP.bam -c Control.bam --cs Chrom.sizes -p Results.peak
  • Semi-supervised peak calling
    java -Xmx8G -jar span.jar analyze -t ChIP.bam -c Control.bam --cs Chrom.sizes -l Labels.bed -p Results.peak
  • Model fitting only
    java -Xmx8G -jar span.jar analyze -t ChIP.bam -c Control.bam --cs Chrom.sizes -m Model.span

Differential peak calling

Experimental! To compare two (possibly replicated) biological conditions use the compare. See help for details:

$ java -jar span.jar compare --help

Command line options

Parameter Description
-t, --treatment TREATMENT
required		 Treatment file. Supported formats: BAM, BED, or BED.gz file.
If multiple files are provided, they are treated as replicates.
Multiple files should be separated by commas: -t A,B,C.
Multiple files are processed as replicates on the model level.
-c, --control CONTROL Control file. Multiple files should be separated by commas.
A single control file, or a separate file per each treatment file is required.
Follow the instructions for -t, --treatment.
-cs, --chrom.sizes CHROMOSOMES_SIZES
required		 Chromosome sizes file for the genome build used in TREATMENT and CONTROL files.
Can be downloaded at UCSC.
-b, --bin BIN_SIZE Peak analysis is performed on read coverage tiled into consequent bins of configurable size. Default: 100
-f, --fdr FDR False Discovery Rate cutoff to call significant regions. Default: 0.05
-p, --peaks PEAKS Resulting peaks file in ENCODE broadPeak* (BED 6+3) format.
If omitted, only the model fitting step is performed.
--fragment FRAGMENT Fragment size. If provided, reads are shifted appropriately.
If not provided, the shift is estimated from the data.
--fragment 0 is recommended for ATAC-Seq data processing.
-kd, --keep-duplicates Keep duplicates. By default, SPAN filters out redundant reads aligned at the same genomic position.
Recommended for bulk single cell ATAC-Seq data processing.
--blacklist BLACKLIST_BED Blacklisted regions of the genome to be excluded from peak calling results.
--labels LABELS Labels BED file. Used in semi-supervised peak calling.
-m, --model MODEL This option is used to specify SPAN model path. Required for further semi-supervised peak calling.
-w, --workdir PATH Path to the working directory. Used to save coverage and model cache.
--bigwig Create beta-control corrected counts per million normalized track.
--sensitivity SENSITIVITY Configures log sensitivity for candidates selection.
Automatically estimated from the data, or during semi-supervised peak calling.
--gap GAP Configures minimal gap between peaks.
Generally, not required, but used in semi-supervised peak calling.
--noclip Disables local coverage based clipping of peaks, useful for low quality data.
--multiple TEST Method applied for multiple hypothesis testing.
BH for Benjamini-Hochberg, BF for Bonferroni. Default: BH
-i, --iterations Maximum number of iterations for Expectation Maximisation (EM) algorithm.
--tr, --threshold Convergence threshold for EM algorithm, use --debug option to see detailed info.
--ext Save extended states information to model file.
Required for model visualization in JBR Genome Browser.
--deep-analysis Perform additional track analysis - coverage (roughness) and creates multi-sensitivity bed track.
--threads THREADS Configure the parallelism level.
-l, --log LOG Path to log file, if not provided, it will be created in working directory.
-d, --debug Print debug information, useful for troubleshooting.
-q, --quiet Turn off standard output.
-kc, --keep-cache Keep cache files. By default SPAN creates cache files in working directory and removes them after computation is done.

Example

Step-by-step example with test dataset is available here.

Build from sources

Clone bioinf-commons library under the project root.

git clone [email protected]:JetBrains-Research/bioinf-commons.git

Launch the following command line to build SPAN jar:

./gradlew shadowJar

The SPAN jar file will be generated in the folder build/libs.

FAQ

  • Q: What is the average running time?
    A: SPAN is capable of processing a single ChIP-Seq track in less than 20 minutes on an average laptop.
  • Q: Which operating systems are supported?
    A: SPAN is developed in modern Kotlin programming language and can be executed on any platform supported by java.
  • Q: Where did you get this lovely span picture?
    A: From ascii.co.uk, the original author goes by the name jgs.

Errors Reporting

Use GitHub issues to suggest new features or report bugs.

Authors

JetBrains Research BioLabs