BaMM!motif - v2

Bayesian Markov Model motif discovery software (version 2).

(C) Johannes Soeding, Wanwan Ge, Anja Kiesel, Matthias Siebert

Requirements

To compile from source, you need:

• GCC compiler 4.7 or later (we suggest GCC-5.x)
• CMake 2.8.11 or later

C++ packages

• Boost

To plot BaMM logos you need R and several R packages

• R 2.14.1 or later
• install.packages( "zoo" )
• install.packages( "argparse" )
• install.packages( "fdrtool" )
• install.packages( "LSD" )
• install.packages( "grid" )
• install.packages( "gdata" )

Installation

Clone it from GIT

  git clone https://github.com/soedinglab/BaMMmotif2.git BaMMmotif
  cd BaMMmotif

How to compile BaMM!motif?

Linux

  mkdir build
  cd build
  cmake -DCMAKE_INSTALL_PREFIX=${HOME}/opt/BaMM ..
  make
  make install

Adjust ${HOME}/opt/BaMM if you want to change the directory for installation

OS X

OS X ships clang instead of gcc. We recommend using Homebrew to install gcc.

Having installed Homebrew, all required dependencies can be installed using the brew command

  brew tap homebrew/versions
  brew tap homebrew/science
  brew install gcc5 cmake R

Compilation

  export CXX=g++-5
  export CC=gcc-5
  export LDFLAGS="-static-libgcc -static-libstdc++"

  mkdir build
  cd build
  cmake -DCMAKE_INSTALL_PREFIX=${HOME}/opt/BaMM ..
  make 
  make install

Environment setup

Add this line to your $HOME/.bashrc (or .zshrc...) to add BaMMmotif to your PATH:

export PATH=${PATH}:${HOME}/opt/BaMM/bin

Update your environment:

source $HOME/.bashrc

How to use BaMM!motif from the command line?

SYNOPSIS

  BaMMmotif DIRPATH FILEPATH [OPTIONS]

DESCRIPTION

  Bayesian Markov Model motif discovery software.

  DIRPATH
      Output directory for the results.

  FILEPATH
      FASTA file with positive sequences of equal length.

OPTIONS

Sequence options

  --alphabet <STRING>
      STANDARD.         For alphabet type ACGT, default setting;
      METHYLC.          For alphabet type ACGTM;
      HYDROXYMETHYLC.   For alphabet type ACGTH;
      EXTENDED.         For alphabet type ACGTMH.
  
  --ss
      Search motif only on single strand strands (positive sequences).
      This option is not recommended for analyzing ChIP-seq data.
      By default, BaMM searches motifs on both strands.
      
  --negSeqSet <FILEPATH>
      FASTA file with negative/background sequences used to learn the
      (homogeneous) background BaMM. If not specified, the background BaMM
      is learned from the positive sequences.

Options to initialize BaMM(s) from file

  --bindingSiteFile <FILEPATH>
      File with binding sites of equal length (one per line).
  
  --PWMFile <STRING>
      File that contains position weight matrices (PWMs).
  
  --BaMMFile <STRING>
      File that contains a model in bamm file format.

  --maxPWM <INTEGER>
      Number of models to be learned by BaMM!motif, specific for PWMs.

Options for the (inhomogeneous) motif BaMMs

  -k|--order <INTEGER>
      Model order. The default is 2.

  -a|--alpha <FLOAT> [<FLOAT>...]
      Order-specific prior strength. The default is 1.0 (for k = 0) and
      beta x gamma^k (for k > 0). The options -b and -g are ignored.

  -b|--beta <FLOAT>
      Calculate order-specific alphas according to beta x gamma^k (for
      k > 0). The default is 7.0.

  -g|--gamma <FLOAT>
      Calculate order-specific alphas according to beta x gamma^k (for
      k > 0). The default is 3.0.

  --extend <INTEGER>{1,2}
      Extend BaMMs by adding uniformly initialized positions to the left
      and/or right of initial BaMMs. Invoking e.g. with --extend 0 2 adds
      two positions to the right of initial BaMMs. Invoking with --extend 2
      adds two positions to both sides of initial BaMMs. By default, BaMMs
      are not being extended.
  
  -q <FLOAT>
      Prior probability for a positive sequence to contain a motif. The
      default is 0.9.
      
  -s, --sOrder <INTERGER>
      The order of k-mer for sampling pseudo/negative set. The default is 2.

Options for the (homogeneous) background BaMM

  -K <INTEGER>
      Order. The default is 2.

  -A|--Alpha <FLOAT>
      Prior strength. The default is 10.0.
  
  --bgModelFile <STRING>
      Read in background model from a bamm-formatted file. 

EM options

  --EM
      Triggers Expectation Maximization (EM) algorithm.

Gibbs sampling options

  --CGS
      Triggers Collapsed Gibbs Sampling (CGS) algorithm.
  
  --maxCGSIterations <INTEGER> 
      Limit the number of CGS iterations.
      It should be larger than 5 and defaults to 100.

Options for model evaluation

  --FDR
      Triggers False-Discovery-Rate (FDR) estimation.
    
  -m|--mFold <INTEGER>
      Number of negative sequences as multiple of positive sequences.
      The default is 10.
  
  -n, --cvFold <INTEGER>
      Fold number for cross-validation. 
      The default is 5, which means the training set is 4-fold of the test set.

Output options

  --saveBaMMs
      Write optimized BaMM(s) to disk.

  --saveInitBaMMs
      Write initialized BaMM(s) to disk.
      
  --verbose
      Verbose terminal printouts.

  -h, --help
      Printout this help.

Downstream analysis

Evaluate the performance of BaMMs

For evaluating the optimized BaMM models, a file with extension .stats is required. It can be generated either by running BaMMmotif with --FDR flag, or by running FDR program independently.

Either

${HOME}/opt/BaMM/bin/BaMMmotif [OUTPUT_FIR] [FASTAFILE] [MOTIF_FILE] [options] --FDR

or

${HOME}/opt/BaMM/bin/FDR [OUTPUT_FIR] [FASTAFILE] [MOTIF_FILE]

R script evaluateBaMM.R is provided in the installation directory ${HOME}/opt/BaMM/bin to calculate the performance score AUSFC and optionally plot precision-recall curve, partial ROC, and sensitivity-FDR curve. You can run it like:

${HOME}/opt/BaMM/bin/evaluateBaMM.R [INPUT_DIR] [PREFIX_OF_STATS_FILE] [options]

The options are:

--SFC 1 for plotting the sensitivity-false discovery rate curve.

--ROC5 1 for plotting the partial ROC with the first 5% of TPR.

--PRC 1 for plotting the precision-recall curve.

You will get the following plots:

The performance scores such as AUSFC, pAUC amd AUPRC are written in the .bmscore file.

How to plot BaMM logos?

R script platBaMMLogo.R is provided in the installation directory ${HOME}/opt/BaMM/bin to plot the BaMM logo from a BaMM flat file.

It requires output files with extension .ihbcp, .ihbp, .hbcp or .hbp from BaMMmotif as input.

The logo order is an integer between 0 to 2.

plotBaMMLogo.R [INPUT_DIR] [PREFIX_OF_OCCURRENCE_FILE] [LOGO_ORDER]

You will get the following plots:

Motif distribution analysis

For visualizing the distribution of motifs in the sequence set, you need to generate either a .occurrence file by executing BaMMmotif with a --scoreSeqset flag or by executing BaMMScan.

Either

${HOME}/opt/BaMM/bin/BaMMmotif [OUTPUT_FIR] [FASTAFILE] [MOTIF_FILE] [options] --scoreSeqset

or

${HOME}/opt/BaMM/bin/BaMMScan [OUTPUT_FIR] [FASTAFILE] [MOTIF_FILE]

After obtaining a .occurrence file, you can run R script plotMotifDistribution.R provided in the installation directory ${HOME}/opt/BaMM/bin to visualise the motif distribution:

${HOME}/opt/BaMM/bin/plotMotifDistribution.R [INPUT_DIR] [PREFIX_OF_OCCURRENCE_FILE] [option]

The option is:

--ss 1 for only plotting the distribution of motif on single strand. Otherwise, it will visualize motif distribution on both strands.

You will get one of the following plots:

Note that, this analysis currently only work for sequences set with sequences of the same length.

BaMM flat file format

BaMM!motif generates two files for each inhomogeneous BaMM:

1. file with extension .ihbp contains probabilities of BaMM model;

2. file with extension .ihbcp contains conditional probabilities of BaMM model.

The format is the same for these two files. While blank lines separate BaMM positions, lines 1 to k+1 of each BaMM position contain the (conditional) probabilities for order 0 to order k. For instance, the format for a BaMM of order 2 and length W is as follows:

Filename extension: .ihbp

P₁(A) P₁(C) P₁(G) P₁(T)
P₁(AA) P₁(AC) P₁(AG) P₁(AT) P₁(CA) P₁(CC) P₁(CG) ... P₁(TT)
P₁(AAA) P₁(AAC) P₁(AAG) P₁(AAT) P₁(ACA) P₁(ACC) P₁(ACG) ... P₁(TTT)

P₂(A) P₂(C) P₂(G) P₂(T)
P₂(AA) P₂(AC) P₂(AG) P₂(AT) P₂(CA) P₂(CC) P₂CG) ... P₂(TT)
P₂(AAA) P₂(AAC) P₂(AAG) P₂(AAT) P₂(ACA) P₂(ACC) P₂(ACG) ... P₂(TTT)
...

P_W(A) P_W(C) P_W(G) P_W(T)
P_W(AA) P_W(AC) P_W(AG) P_W(AT) P_W(CA) P_W(CC) P_WCG) ... P_W(TT)
P_W(AAA) P_W(AAC) P_W(AAG) P_W(AAT) P_W(ACA) P_W(ACC) P_W(ACG) ... P_W(TTT)

Filename extension: .ihbcp

P₁(A) P₁(C) P₁(G) P₁(T)
P₁(A|A) P₁(C|A) P₁(G|A) P₁(T|A) P₁(A|C) P₁(C|C) P₁(G|C) ... P₁(T|T)
P₁(A|AA) P₁(C|AA) P₁(G|AA) P₁(T|AA) P₁(A|AC) P₁(C|AC) P₁(G|AC) ... P₁(T|TT)

P₂(A) P₂(C) P₂(G) P₂(T)
P₂(A|A) P₂(C|A) P₂(G|A) P₂(T|A) P₂(A|C) P₂(C|C) P₂(G|C) ... P₂(T|T)
P₂(A|AA) P₂(C|AA) P₂(G|AA) P₂(T|AA) P₂(A|AC) P₂(C|AC) P₂(G|AC) ... P₂(T|TT)
...

P_W(A) P_W(C) P_W(G) P_W(T)
P_W(A|A) P_W(C|A) P_W(G|A) P_W(T|A) P_W(A|C) P_W(C|C) P_W(G|C) ... P_W(T|T)
P_W(A|AA) P_W(C|AA) P_W(G|AA) P_W(T|AA) P_W(A|AC) P_W(C|AC) P_W(G|AC) ... P_W(T|TT)

In addition, BaMM!motif generates two files for the homogeneous background BaMM:

1. file with extension .ihbp contains probabilities of background model;

2. file with extension .ihbcp contains conditional probabilities of background model.

For instance, the format for a background BaMM of order 2 is as follows:

Filename extension: .hbp

P(A) P(C) P(G) P(T)
P(AA) P(AC) P(AG) P(AT) P(CA) P(CC) P(CG) ... P(TT)
P(AAA) P(AAC) P(AAG) P(AAT) P(ACA) P(ACC) P(ACG) ... P(TTT)

Filename extension: .hbcp

P(A) P(C) P(G) P(T)
P(A|A) P(C|A) P(G|A) P(T|A) P(A|C) P(C|C) P(G|C) ... P(T|T)
P(A|AA) P(C|AA) P(G|AA) P(T|AA) P(A|AC) P(C|AC) P(G|AC) ... P(T|TT)

License

BaMM!motif is released under the GNU General Public License v3 or later. See LICENSE for more details.

Notes

We are welcoming bug reports! Please contact us at soeding@mpibpc.mpg.de .

For the seeding phase, we recommend to use our de novo motif discovery tool PEnG-motif.