MACS2 2.0.10.07032012

Model Based Analysis for ChIP-Seq data

README for MACS (2.0.9)
Time-stamp: <2011-11-02 15:21:38 Tao Liu>

* Introduction

With the improvement of sequencing techniques, chromatin
immunoprecipitation followed by high throughput sequencing (ChIP-Seq)
is getting popular to study genome-wide protein-DNA interactions. To
address the lack of powerful ChIP-Seq analysis method, we present a
novel algorithm, named Model-based Analysis of ChIP-Seq (MACS), for
identifying transcript factor binding sites. MACS captures the
influence of genome complexity to evaluate the significance of
enriched ChIP regions, and MACS improves the spatial resolution of
binding sites through combining the information of both sequencing tag
position and orientation. MACS can be easily used for ChIP-Seq data
alone, or with control sample with the increase of specificity.

* Install

Please check the file 'INSTALL' in the distribution.

* Usage of macs2

Usage: macs2 <-t tfile> [-n name] [-g genomesize] [options]

Example: macs2 -t ChIP.bam -c Control.bam -f BAM -g hs -n test -B -q 0.01

or example for broad peak calling: macs2 -t ChIP.bam -c Control.bam --broad -g hs



macs2 -- Model-based Analysis for ChIP-Sequencing

Options:
--version show program's version number and exit
-h, --help show this help message and exit.
-t TFILE, --treatment=TFILE
ChIP-seq treatment file. REQUIRED.
-c CFILE, --control=CFILE
Control file.
-n NAME, --name=NAME Experiment name, which will be used to generate output
file names. DEFAULT: "NA"
-f FORMAT, --format=FORMAT
Format of tag file, "AUTO", "BED" or "ELAND" or
"ELANDMULTI" or "ELANDEXPORT" or "SAM" or "BAM" or
"BOWTIE". The default AUTO option will let MACS decide
which format the file is. Please check the definition
in 00README file if you choose
ELAND/ELANDMULTI/ELANDEXPORT/SAM/BAM/BOWTIE. DEFAULT:
"AUTO"
-g GSIZE, --gsize=GSIZE
Effective genome size. It can be 1.0e+9 or 1000000000,
or shortcuts:'hs' for human (2.7e9), 'mm' for mouse
(1.87e9), 'ce' for C. elegans (9e7) and 'dm' for
fruitfly (1.2e8), Default:hs
-s TSIZE, --tsize=TSIZE
Tag size. This will overide the auto detected tag
size. DEFAULT: Not set
--bw=BW Band width. This value is only used while building the
shifting model. DEFAULT: 300
-q QVALUE, --qvalue=QVALUE
Minimum FDR (q-value) cutoff for peak detection.
DEFAULT: 0.01
-p PVALUE, --pvalue=PVALUE
Pvalue cutoff for peak detection. When set (e.g. -q
0.05 or -q 1e-5), qvalue cutoff will be ignored.
Default is not set.
-m MFOLD, --mfold=MFOLD
Select the regions within MFOLD range of high-
confidence enrichment ratio against background to
build model. The regions must be lower than upper
limit, and higher than the lower limit. DEFAULT:10,30
--nolambda If True, MACS will use fixed background lambda as
local lambda for every peak region. Normally, MACS
calculates a dynamic local lambda to reflect the local
bias due to potential chromatin structure.
--slocal=SMALLLOCAL The small nearby region in basepairs to calculate
dynamic lambda. This is used to capture the bias near
the peak summit region. Invalid if there is no control
data. If you set this to 0, MACS will skip slocal
lambda calculation. *Note* that MACS will always
perform a d-size local lambda calculation. The final
local bias should be the maximum of the lambda value
from d, slocal, and llocal size windows. DEFAULT: 1000
--llocal=LARGELOCAL The large nearby region in basepairs to calculate
dynamic lambda. This is used to capture the surround
bias. If you set this to 0, MACS will skip llocal
lambda calculation. *Note* that MACS will always
perform a d-size local lambda calculation. The final
local bias should be the maximum of the lambda value
from d, slocal, and llocal size windows. DEFAULT:
10000.
--auto-bimodal Whether turn on the auto pair model process. If set,
when MACS failed to build paired model, it will use
the nomodel settings, the '--shiftsize' parameter to
shift and extend each tags. Not to use this automate
fixation is a default behavior now. DEFAULT: False
--nomodel Whether or not to build the shifting model. If True,
MACS will not build model. by default it means
shifting size = 100, try to set shiftsize to change
it. DEFAULT: False
--shiftsize=SHIFTSIZE
The arbitrary shift size in bp. When nomodel is true,
MACS will use this value as 1/2 of fragment size.
DEFAULT: 100
--keep-dup=KEEPDUPLICATES
It controls the MACS behavior towards duplicate tags
at the exact same location -- the same coordination
and the same strand. The default 'auto' option makes
MACS calculate the maximum tags at the exact same
location based on binomal distribution using 1e-5 as
pvalue cutoff; and the 'all' option keeps every tags.
If an integer is given, at most this number of tags
will be kept at the same location. Default: auto
--to-large When set, scale the small sample up to the bigger
sample. By default, the bigger dataset will be scaled
down towards the smaller dataset, which will lead to
smaller p/qvalues and more specific results. Keep in
mind that scaling down will bring down background
noise more. DEFAULT: False
--down-sample When set, random sampling method will scale down the
bigger sample. By default, MACS uses linear scaling.
Warning: This option will make your result unstable
and irreproducible since each time, random reads would
be selected. Consider to use 'randsample' script
instead. DEFAULT: False
--shift-control When set, control tags will be shifted just as ChIP
tags according to their strand before the extension of
d, slocal and llocal. By default, control tags are
extended centered at their current positions
regardless of strand. You may consider to turn this
option on while comparing two ChIP datasets of
different condition but the same factor. DEFAULT:
False
--half-ext When set, MACS extends 1/2 d size for each fragment
centered at its middle point. DEFAULT: False
-B, --bdg Whether or not to save extended fragment pileup, local
lambda and score tracks at every bp into a bedGraph
file. DEFAULT: False
--broad If set, MACS will try to call broad peaks by linking
nearby highly enriched regions. The linking region is
controlled by another cutoff through --linking-cutoff.
The maximum linking region length is 4 times of d from
MACS. DEFAULT: False
--broad-cutoff=BROADCUTOFF
Cutoff for broad region. This option is not available
unless --broad is set. If -p is set, this is a pvalue
cutoff, otherwise, it's a qvalue cutoff. DEFAULT: 0.1
--verbose=VERBOSE Set verbose level. 0: only show critical message, 1:
show additional warning message, 2: show process
information, 3: show debug messages. DEFAULT:2

** Parameters:

*** -t/--treatment FILENAME

This is the only REQUIRED parameter for MACS.

*** -c/--control

The control or mock data file in either BED format or any ELAND output
format specified by --format option. Please follow the same direction
as for -t/--treatment.

*** -n/--name

The name string of the experiment. MACS will use this string NAME to
create output files like 'NAME_peaks.xls', 'NAME_negative_peaks.xls',
'NAME_peaks.bed' , 'NAME_summits.bed', 'NAME_model.r' and so on. So
please avoid any confliction between these filenames and your existing
files.

*** -f/--format FORMAT

Format of tag file, can be "ELAND", "BED", "ELANDMULTI",
"ELANDEXPORT", "ELANDMULTIPET" (for pair-end tags), "SAM", "BAM" or
"BOWTIE". Default is "AUTO" which will allow MACS to decide the format
automatically. Please use "AUTO" only when you combine different
formats of files.

The BED format is defined in "http://genome.ucsc.edu/FAQ/FAQformat#format1".

If the format is ELAND, the file must be ELAND result output file,
each line MUST represents only ONE tag, with fields of:

1. Sequence name (derived from file name and line number if format is not Fasta)
2. Sequence
3. Type of match:
NM - no match found.
QC - no matching done: QC failure (too many Ns basically).
RM - no matching done: repeat masked (may be seen if repeatFile.txt was specified).
U0 - Best match found was a unique exact match.
U1 - Best match found was a unique 1-error match.
U2 - Best match found was a unique 2-error match.
R0 - Multiple exact matches found.
R1 - Multiple 1-error matches found, no exact matches.
R2 - Multiple 2-error matches found, no exact or 1-error matches.
4. Number of exact matches found.
5. Number of 1-error matches found.
6. Number of 2-error matches found.
Rest of fields are only seen if a unique best match was found (i.e. the match code in field 3 begins with "U").
7. Genome file in which match was found.
8. Position of match (bases in file are numbered starting at 1).
9. Direction of match (F=forward strand, R=reverse).
10. How N characters in read were interpreted: ("."=not applicable, "D"=deletion, "I"=insertion).
Rest of fields are only seen in the case of a unique inexact match (i.e. the match code was U1 or U2).
11. Position and type of first substitution error (e.g. 12A: base 12 was A, not whatever is was in read).
12. Position and type of first substitution error, as above.

If the format is ELANDMULTI, the file must be ELAND output file from
multiple-match mode, each line MUST represents only ONE tag, with
fields of:

1. Sequence name
2. Sequence
3. Either NM, QC, RM (as described above) or the following:
4. x:y:z where x, y, and z are the number of exact, single-error, and 2-error matches found
5. Blank, if no matches found or if too many matches found, or the following:
BAC_plus_vector.fa:163022R1,170128F2,E_coli.fa:3909847R1 This says
there are two matches to BAC_plus_vector.fa: one in the reverse
direction starting at position 160322 with one error, one in the
forward direction starting at position 170128 with two
errors. There is also a single-error match to E_coli.fa.

If the data is from Pair-End sequencing. You can sepecify the format
as ELANDMULTIPET ( stands for ELAND Multiple-match Pair-End Tags),
then the --treat (and --control if needed) parameter must be two file
names separated by comma. Each file must be in ELAND multiple-match
format described above. e.g.

macs2 --format ELANDMULTIPET -t s_1_1_eland_multi.txt,s_2_1_eland_multi.txt ...

If you use ELANDMULTIPET, you may need to modify --petdist parameter.

If the format is BAM/SAM, please check the definition in
(http://samtools.sourceforge.net/samtools.shtml). Pair-end mapping
results can be saved in a single BAM file, if so, MACS will
automatically keep the left mate(5' end) tag.

If the format is BOWTIE, you need to provide the ASCII bowtie output
file with the suffix '.map'. Please note that, you need to make sure
that in the bowtie output, you only keep one location for one
read. Check the bowtie manual for detail if you want at
(http://bowtie-bio.sourceforge.net/manual.shtml)

Here is the definition for Bowtie output in ASCII characters I copied
from the above webpage:

1. Name of read that aligned

2. Orientation of read in the alignment, - for reverse complement,
+ otherwise

3. Name of reference sequence where alignment occurs, or ordinal ID
if no name was provided

4. 0-based offset into the forward reference strand where leftmost
character of the alignment occurs

5. Read sequence (reverse-complemented if orientation is -)

6. ASCII-encoded read qualities (reversed if orientation is -). The
encoded quality values are on the Phred scale and the encoding is
ASCII-offset by 33 (ASCII char !).

7. Number of other instances where the same read aligns against the
same reference characters as were aligned against in this
alignment. This is not the number of other places the read aligns
with the same number of mismatches. The number in this column is
generally not a good proxy for that number (e.g., the number in
this column may be '0' while the number of other alignments with
the same number of mismatches might be large). This column was
previously described as "Reserved".

8. Comma-separated list of mismatch descriptors. If there are no
mismatches in the alignment, this field is empty. A single
descriptor has the format offset:reference-base>read-base. The
offset is expressed as a 0-based offset from the high-quality (5')
end of the read.

Notes:

1) For BED format, the 6th column of strand information is required by
MACS. And please pay attention that the coordinates in BED format is
zero-based and half-open
(http://genome.ucsc.edu/FAQ/FAQtracks#tracks1).

2) For plain ELAND format, only matches with match type U0, U1 or U2 is
accepted by MACS, i.e. only the unique match for a sequence with less
than 3 errors is involed in calculation. If multiple hits of a single
tag are included in your raw ELAND file, please remove the redundancy
to keep the best hit for that sequencing tag.

3) For the experiment with several replicates, it is recommended to
concatenate several ChIP-seq treatment files into a single file. To do
this, under Unix/Mac or Cygwin (for windows OS), type:

$ cat replicate1.bed replicate2.bed replicate3.bed > all_replicates.bed

For BAM or SAM files, samtools can be used to combine replicates.

4) ELAND export format support sometimes may not work on your
datasets, because people may mislabel the 11th and 12th column. MACS
uses 11th column as the sequence name which should be the chromosome
names.

** --petdist=PETDIST

Best distance between Pair-End Tags. Only available when format is
'ELANDMULTIPE'. Default is 200bps. When MACS reads mapped positions
for 5' tag and 3' tag, it will decide the best pairing for them using
this best distance parameter. A simple scoring system is used as following,

score = abs(abs(p5-p3)-200)+e5+e5

Where p5 is one of the position of 5' tag, and e5 is the
mismatch/error for this mapped position of 5' tag. p3 and e3 are for
3' tag. Then the lowest scored paring is regarded as the best
pairing. The 5' tag position of the pair is kept in model building and
peak calling.

*** -g/--gsize

PLEASE assign this parameter to fit your needs!

It's the mappable genome size or effective genome size which is
defined as the genome size which can be sequenced. Because of the
repetitive features on the chromsomes, the actual mappable genome size
will be smaller than the original size, about 90% or 70% of the genome
size. The default hs -- 2.7e9 is recommended for UCSC human hg18
assembly. Here are all precompiled parameters for effective genome size:

-g hs = -g 2.7e9
-g mm = -g 1.87e9
-g ce = -g 9e7
-g dm = -g 1.2e8

*** -s/--tsize

The size of sequencing tags. If you don't specify it, MACS will try to
use the first 10 sequences from your input treatment file to determine
the tag size. Specifying it will override the automatic determined tag
size.

*** --bw

The band width which is used to scan the genome ONLY for model
building. You can set this parameter as the sonication fragment size
expected from wet experiment. The previous side effect on the peak
detection process has been removed. So this parameter only affects the
model building.

*** -q/--qvalue

The qvalue (minimum FDR) cutoff to call significant regions. Default
is 0.01. For broad marks, you can try 0.05 as cutoff. Q-values are
calculated from p-values using Benjamini-Hochberg procedure.

*** -p/--pvalue

The pvalue cutoff. If -p is specified, MACS2 will use pvalue instead of qvalue.

*** -m/--mfold

This parameter is used to select the regions within MFOLD range of
high-confidence enrichment ratio against background to build
model. The regions must be lower than upper limit, and higher than the
lower limit of fold enrichment. DEFAULT:10,30 means using all regions
not too low (>10) and not too high (<30) to build paired-peaks
model. If MACS can not find more than 100 regions to build model, it
will use the --shiftsize parameter to continue the peak detection.

Check related *--off-auto* and *--shiftsize* for detail.

** --nolambda

With this flag on, MACS will use the background lambda as local
lambda. This means MACS will not consider the local bias at peak
candidate regions.

** --slocal, --llocal

These two parameters control which two levels of regions will be
checked around the peak regions to calculate the maximum lambda as
local lambda. By default, MACS considers 1000bp for small local
region(--slocal), and 10000bps for large local region(--llocal)
which captures the bias from a long range effect like an open
chromatin domain. You can tweak these according to your
project. Remember that if the region is set too small, a sharp spike
in the input data may kill the significant peak.

** --off-auto

Whether turn off the auto paired-peak model process. If not set, when
MACS failed to build paired model, it will use the nomodel settings,
the '--shiftsize' parameter to shift and extend each tags. If set,
MACS will be terminated if paried-peak model is failed.

** --nomodel

While on, MACS will bypass building the shifting model.

** --shiftsize

While '--nomodel' is set, MACS uses this parameter to shift tags to
their midpoint. For example, if the size of binding region for your
transcription factor is 200 bp, and you want to bypass the model
building by MACS, this parameter can be set as 100. This option is
only valid when --nomodel is set or when MACS fails to build
paired-peak model.

** --keep-dup

It controls the MACS behavior towards duplicate tags at the exact same
location -- the same coordination and the same strand. The default
'auto' option makes MACS calculate the maximum tags at the exact same
location based on binomal distribution using 1e-5 as pvalue cutoff;
and the 'all' option keeps every tags. If an integer is given, at
most this number of tags will be kept at the same location. Default:
auto

** --broad

When this flag is on, MACS will try to composite broad regions in
BED12 ( a gene-model-like format ) by putting nearby highly enriched
regions into a broad region with loose cutoff. The broad region is
controlled by another cutoff through --broad-cutoff. The maximum
length of broad region length is 4 times of d from MACS. DEFAULT:
False

** --broad-cutoff

Cutoff for broad region. This option is not available unless --broad
is set. If -p is set, this is a pvalue cutoff, otherwise, it's a
qvalue cutoff. DEFAULT: 0.1

** --to-large

When set, linearly scale the smaller dataset to the same depth as
larger dataset, by default, the smaller dataset will be scaled towards
the larger dataset. Beware, to scale up small data would cause more
false positives.

** --down-sample

When set, random sampling method will scale down the bigger sample. By
default, MACS uses linear scaling. This option will make the results
unstable and irreproducible since each time, random reads would be
selected, especially the numbers (pileup, pvalue, qvalue) would
change. Consider to use 'randsample' script before MACS2 runs instead.

** -B/--bdg

If this flag is on, MACS will store the fragment pileup, control
lambda, -log10pvalue and -log10qvalue scores in bedGraph files. The
bedGraph files will be stored in current directory named
NAME+'_treat_pileup.bdg' for treatment data,
NAME+'_control_lambda.bdg' for local lambda values from control,
NAME+'_treat_pvalue.bdg' for Poisson pvalue scores (in -log10(pvalue)
form), and NAME+'_treat_qvalue.bdg' for q-value scores from
Benjamini–Hochberg–Yekutieli procedure
<http://en.wikipedia.org/wiki/False_discovery_rate#Dependent_tests>

** --half-ext (experimental option)

When this flag is on, MACS will only extend each tag with 1/2 d
(predicted ChIP fragment size) instead of full d.

** -w/--wig is obsolete.

** -S/--single-profile is obsolete.

** --space=SPACE is obsolete since we don't generate wiggle file.

** --call-subpeaks is currently not functional.

If set, MACS will invoke Mali Salmon's PeakSplitter software through
system call. If PeakSplitter can't be found, an instruction will be
shown for downloading and installing the PeakSplitter package. The
PeakSplitter can refine the MACS peaks and split the wide peaks into
smaller subpeaks. For more information, please check the following URL:

http://www.ebi.ac.uk/bertone/software/PeakSplitter_Cpp_usage.txt

Note this option doesn't work if -B/--bdg is on.

*** --verbose

If you don't want to see any message during the running of MACS, set
it to 0. But the CRITICAL messages will never be hidden. If you want
to see rich information like how many peaks are called for every
chromosome, you can set it to 3 or larger than 3.

** --diag is currently not functional.

A diagnosis report can be generated through this option. This report
can help you get an assumption about the sequencing saturation. This
funtion is only in beta stage.

** --fe-min, --fe-max & --fe-step are currently not functional.

For diagnostics, FEMIN and FEMAX are the minimum and maximum fold
enrichment to consider, and FESTEP is the interval of fold
enrichment. For example, "--fe-min 0 --fe-max 40 --fe-step 10" will
let MACS choose the following fold enrichment ranges to consider:
[0,10), [10,20), [20,30) and [30,40).

* Output files

1. NAME_peaks.xls is a tabular file which contains information about
called peaks. You can open it in excel and sort/filter using excel
functions. Information include: chromosome name, start position of
peak, end position of peak, length of peak region, absolute peak
summit position, pileup height at peak summit, -log10(pvalue) for the
peak summit (e.g. pvalue =1e-10, then this value should be 10), fold
enrichment for this peak summit against random Poisson distribution
with local lambda, -log10(qvalue) at peak summit. Coordinates in XLS
is 1-based which is different with BED format.

2. NAME_peaks.bed is BED format file which contains the peak
locations. You can load it to UCSC genome browser or Affymetrix IGB
software. The file can be loaded directly to UCSC genome
browser. Remove the beginning track line if you want to analyze it by
other tools.

3. NAME_peaks.encodePeak is BED6+4 format file which contains the
peak locations together with peak summit, pvalue and qvalue. You can
load it to UCSC genome browser. Definition of some specific columns
are: 5th: -log10pvalue*10, 7th: fold-change, 8th: -log10pvalue, 9th:
-log10qvalue, 10th: relative summit position to peak start. The file
can be loaded directly to UCSC genome browser. Remove the beginning
track line if you want to analyze it by other tools.

4. NAME_summits.bed is in BED format, which contains the peak summits
locations for every peaks. The 5th column in this file is
-log10pvalue the same as NAME_peaks.bed. If you want to find the
motifs at the binding sites, this file is recommended. The file can
be loaded directly to UCSC genome browser. Remove the beginning track
line if you want to analyze it by other tools.

5. NAME_broad_peaks.bed is in BED12 format which contains both the
broad region and narrow peaks. The 5th column is 100*-log10pvalue, to
be more compatible to UCSC standard. Tht 7th is the start of the
first narrow peak in the region, and the 8th column is the end. The
9th column should be RGB color key, however, we keep 0 here to use
the default color, so change it if you want. The 10th column tells
how many blocks including the starting 1bp and ending 1bp of broad
regions. The 11th column shows the length of each blocks, and 12th
for the starts of each blocks. The file can be loaded directly to
UCSC genome browser. Remove the beginning track line if you want to
analyze it by other tools.

6. NAME_model.r is an R script which you can use to produce a PDF
image about the model based on your data. Load it to R by:

$ R --vanilla < NAME_model.r

Then a pdf file NAME_model.pdf will be generated in your current
directory. Note, R is required to draw this figure.

7. The .bdg files are in bedGraph format which can be imported to
UCSC genome browser or be converted into even smaller bigWig
files. Four kinds of bdg files include treat_pileup, control_lambda,
treat_pvalue, and treat_qvalue.

8. NAME_pqtable.txt store the -log10pvalue, -log10qvalue, rank of
this pvalue, and number of bp having this pvalue.

* Usage of macs2diff

Will update it later...

* Other useful links

Cistrome web server for ChIP-chip/seq analysis: http://cistrome.org/ap/

bedTools -- a super useful toolkits for genome annotation files: http://code.google.com/p/bedtools/

UCSC toolkits: http://hgdownload.cse.ucsc.edu/admin/exe/

* Tips of fine-tuning peak calling

Check the three scripts within MACSv2 package:

1. bdgcmp can be used on *_treat_pileup.bdg and *_control_lambda.bdg
or bedGraph files from other resources to calculate score track;

2. bdgpeakcall can be used on *_treat_pvalue.bdg or the file
generated from bdgcmp or bedGraph file from other resources to call
peaks with given cutoff, maximum-gap between nearby mergable peaks
and minimum length of peak. bdgbroadcall works similarly to
bdgpeakcall, however it will output _broad_peaks.bed in BED12 format.

3. Differential calling tool -- bdgdiff, can be used on 4 bedgraph
files which are scores between treatment 1 and control 1, treatment 2
and control 2, treatment 1 and treatment 2, treatment 2 and treatment
1. It will output the consistent and unique sites according to
parameter settings for minimum length, maximum gap and cutoff.