From fa84fa2a7199085efdc60e2e8b5a6d822b4abc81 Mon Sep 17 00:00:00 2001 From: Tao Liu Date: Fri, 26 Apr 2024 15:40:56 -0400 Subject: [PATCH] update docs --- .github/workflows/build-and-test-MACS3-macos.yml | 2 - .github/workflows/build-and-test-MACS3-non-x64.yml | 2 - .github/workflows/build-and-test-MACS3-x64.yml | 2 - MACS3/Utilities/OptValidator.py | 4 +- .../Advanced_Step-by-step_Peak_Calling.md | 0 docs/{source/docs => }/INSTALL.md | 0 docs/{source/docs => }/bdgbroadcall.md | 0 docs/{source/docs => }/bdgcmp.md | 0 docs/{source/docs => }/bdgdiff.md | 0 docs/{source/docs => }/bdgopt.md | 0 docs/{source/docs => }/bdgpeakcall.md | 0 docs/{source/docs => }/callpeak.md | 0 docs/{source/docs => }/callvar.md | 0 docs/{source/docs => }/callvar_algorithm.jpeg | Bin docs/{source/docs => }/cmbreps.md | 0 docs/{source/docs => }/filterdup.md | 0 docs/{source/docs => }/hmmratac.md | 0 docs/{source/docs => }/pileup.md | 0 docs/{source/docs => }/pileup.png | Bin docs/{source/docs => }/predictd.md | 0 docs/{source/docs => }/qa.md | 0 docs/{source/docs => }/randsample.md | 0 docs/{source/docs => }/refinepeak.md | 0 docs/source/conf.py | 4 +- .../docs/Advanced_Step-by-step_Peak_Calling.md | 292 +------------ docs/source/docs/BED.md | 1 - docs/source/docs/BEDPE.md | 26 -- docs/source/docs/INSTALL.md | 154 +------ docs/source/docs/SAMBAMBAMPE.md | 2 - docs/source/docs/bdgbroadcall.md | 80 +--- docs/source/docs/bdgcmp.md | 93 +--- docs/source/docs/bdgdiff.md | 208 +-------- docs/source/docs/bdgopt.md | 81 +--- docs/source/docs/bdgpeakcall.md | 123 +----- docs/source/docs/bedGraph.md | 1 - docs/source/docs/broadPeak.md | 1 - docs/source/docs/callpeak.md | 478 +-------------------- docs/source/docs/callpeakxls.md | 1 - docs/source/docs/callvar.md | 225 +--------- docs/source/docs/callvar_algorithm.jpeg | Bin 163926 -> 36 bytes docs/source/docs/cmbreps.md | 65 +-- docs/source/docs/cutoffanalysis.md | 1 - docs/source/docs/fileformats_index.md | 19 - docs/source/docs/filterdup.md | 98 +---- docs/source/docs/gappedPeak.md | 1 - docs/source/docs/hmmratac.md | 268 +----------- docs/source/docs/hmmratacModel.md | 1 - .../source/docs/{subcommands_index.md => index.md} | 0 docs/source/docs/narrowPeak.md | 1 - docs/source/docs/pileup.md | 75 +--- docs/source/docs/pileup.png | Bin 34709 -> 24 bytes docs/source/docs/predictd.md | 90 +--- docs/source/docs/qa.md | 2 +- docs/source/docs/randsample.md | 85 +--- docs/source/docs/refinepeak.md | 67 +-- docs/source/docs/tutorial.md | 2 +- docs/source/docs/vcf.md | 1 - docs/source/index.md | 3 +- docs/{source/docs => }/tutorial.md | 0 59 files changed, 24 insertions(+), 2535 deletions(-) copy docs/{source/docs => }/Advanced_Step-by-step_Peak_Calling.md (100%) copy docs/{source/docs => }/INSTALL.md (100%) copy docs/{source/docs => }/bdgbroadcall.md (100%) copy docs/{source/docs => }/bdgcmp.md (100%) copy docs/{source/docs => }/bdgdiff.md (100%) copy docs/{source/docs => }/bdgopt.md (100%) copy docs/{source/docs => }/bdgpeakcall.md (100%) copy docs/{source/docs => }/callpeak.md (100%) copy docs/{source/docs => }/callvar.md (100%) copy docs/{source/docs => }/callvar_algorithm.jpeg (100%) copy docs/{source/docs => }/cmbreps.md (100%) copy docs/{source/docs => }/filterdup.md (100%) copy docs/{source/docs => }/hmmratac.md (100%) copy docs/{source/docs => }/pileup.md (100%) copy docs/{source/docs => }/pileup.png (100%) copy docs/{source/docs => }/predictd.md (100%) copy docs/{source/docs => }/qa.md (100%) copy docs/{source/docs => }/randsample.md (100%) copy docs/{source/docs => }/refinepeak.md (100%) rewrite docs/source/docs/Advanced_Step-by-step_Peak_Calling.md (100%) mode change 100644 => 120000 delete mode 100644 docs/source/docs/BED.md delete mode 100644 docs/source/docs/BEDPE.md rewrite docs/source/docs/INSTALL.md (100%) mode change 100644 => 120000 delete mode 100644 docs/source/docs/SAMBAMBAMPE.md rewrite docs/source/docs/bdgbroadcall.md (100%) mode change 100644 => 120000 rewrite docs/source/docs/bdgcmp.md (100%) mode change 100644 => 120000 rewrite docs/source/docs/bdgdiff.md (100%) mode change 100644 => 120000 rewrite docs/source/docs/bdgopt.md (100%) mode change 100644 => 120000 rewrite docs/source/docs/bdgpeakcall.md (100%) mode change 100644 => 120000 delete mode 100644 docs/source/docs/bedGraph.md delete mode 100644 docs/source/docs/broadPeak.md rewrite docs/source/docs/callpeak.md (100%) mode change 100644 => 120000 delete mode 100644 docs/source/docs/callpeakxls.md rewrite docs/source/docs/callvar.md (100%) mode change 100644 => 120000 rewrite docs/source/docs/callvar_algorithm.jpeg (100%) mode change 100644 => 120000 rewrite docs/source/docs/cmbreps.md (100%) mode change 100644 => 120000 delete mode 100644 docs/source/docs/cutoffanalysis.md delete mode 100644 docs/source/docs/fileformats_index.md rewrite docs/source/docs/filterdup.md (100%) mode change 100644 => 120000 delete mode 100644 docs/source/docs/gappedPeak.md rewrite docs/source/docs/hmmratac.md (100%) mode change 100644 => 120000 delete mode 100644 docs/source/docs/hmmratacModel.md rename docs/source/docs/{subcommands_index.md => index.md} (100%) delete mode 100644 docs/source/docs/narrowPeak.md rewrite docs/source/docs/pileup.md (100%) mode change 100644 => 120000 rewrite docs/source/docs/pileup.png (100%) mode change 100644 => 120000 rewrite docs/source/docs/predictd.md (100%) mode change 100644 => 120000 rewrite docs/source/docs/qa.md (100%) mode change 100644 => 120000 rewrite docs/source/docs/randsample.md (100%) mode change 100644 => 120000 rewrite docs/source/docs/refinepeak.md (100%) mode change 100644 => 120000 rewrite docs/source/docs/tutorial.md (100%) mode change 100644 => 120000 delete mode 100644 docs/source/docs/vcf.md copy docs/{source/docs => }/tutorial.md (100%) diff --git a/.github/workflows/build-and-test-MACS3-macos.yml b/.github/workflows/build-and-test-MACS3-macos.yml index 2c45f9e..2dc60db 100644 --- a/.github/workflows/build-and-test-MACS3-macos.yml +++ b/.github/workflows/build-and-test-MACS3-macos.yml @@ -8,14 +8,12 @@ on: paths-ignore: - 'docs/**' - '**.md' - - 'ChangeLog' - '.github/workflows/**' - '!.github/workflows/build-and-test-MACS3-macos.yml' pull_request: paths-ignore: - 'docs/**' - '**.md' - - 'ChangeLog' - '.github/workflows/**' - '!.github/workflows/build-and-test-MACS3-macos.yml' diff --git a/.github/workflows/build-and-test-MACS3-non-x64.yml b/.github/workflows/build-and-test-MACS3-non-x64.yml index 83c55d6..155ad18 100644 --- a/.github/workflows/build-and-test-MACS3-non-x64.yml +++ b/.github/workflows/build-and-test-MACS3-non-x64.yml @@ -8,14 +8,12 @@ on: paths-ignore: - 'docs/**' - '**.md' - - 'ChangeLog' - '.github/workflows/**' - '!.github/workflows/build-and-test-MACS3-non-x64.yml' pull_request: paths-ignore: - 'docs/**' - '**.md' - - 'ChangeLog' - '.github/workflows/**' - '!.github/workflows/build-and-test-MACS3-non-x64.yml' diff --git a/.github/workflows/build-and-test-MACS3-x64.yml b/.github/workflows/build-and-test-MACS3-x64.yml index 2f7c7db..d9aa9ed 100644 --- a/.github/workflows/build-and-test-MACS3-x64.yml +++ b/.github/workflows/build-and-test-MACS3-x64.yml @@ -8,14 +8,12 @@ on: paths-ignore: - 'docs/**' - '**.md' - - 'ChangeLog' - '.github/workflows/**' - '!.github/workflows/build-and-test-MACS3-x64.yml' pull_request: paths-ignore: - 'docs/**' - '**.md' - - 'ChangeLog' - '.github/workflows/**' - '!.github/workflows/build-and-test-MACS3-x64.yml' diff --git a/MACS3/Utilities/OptValidator.py b/MACS3/Utilities/OptValidator.py index f1a1a8c..b317ce2 100644 --- a/MACS3/Utilities/OptValidator.py +++ b/MACS3/Utilities/OptValidator.py @@ -1,4 +1,4 @@ -# Time-stamp: <2024-04-19 15:11:59 Tao Liu> +# Time-stamp: <2023-07-28 12:17:28 Tao Liu> """Module Description @@ -32,6 +32,8 @@ from MACS3.Utilities.Constants import EFFECTIVEGS as efgsize import logging import MACS3.Utilities.Logger +logger = logging.getLogger(__name__) + # ------------------------------------ # Misc functions # ------------------------------------ diff --git a/docs/source/docs/Advanced_Step-by-step_Peak_Calling.md b/docs/Advanced_Step-by-step_Peak_Calling.md similarity index 100% copy from docs/source/docs/Advanced_Step-by-step_Peak_Calling.md copy to docs/Advanced_Step-by-step_Peak_Calling.md diff --git a/docs/source/docs/INSTALL.md b/docs/INSTALL.md similarity index 100% copy from docs/source/docs/INSTALL.md copy to docs/INSTALL.md diff --git a/docs/source/docs/bdgbroadcall.md b/docs/bdgbroadcall.md similarity index 100% copy from docs/source/docs/bdgbroadcall.md copy to docs/bdgbroadcall.md diff --git a/docs/source/docs/bdgcmp.md b/docs/bdgcmp.md similarity index 100% copy from docs/source/docs/bdgcmp.md copy to docs/bdgcmp.md diff --git a/docs/source/docs/bdgdiff.md b/docs/bdgdiff.md similarity index 100% copy from docs/source/docs/bdgdiff.md copy to docs/bdgdiff.md diff --git a/docs/source/docs/bdgopt.md b/docs/bdgopt.md similarity index 100% copy from docs/source/docs/bdgopt.md copy to docs/bdgopt.md diff --git a/docs/source/docs/bdgpeakcall.md b/docs/bdgpeakcall.md similarity index 100% copy from docs/source/docs/bdgpeakcall.md copy to docs/bdgpeakcall.md diff --git a/docs/source/docs/callpeak.md b/docs/callpeak.md similarity index 100% copy from docs/source/docs/callpeak.md copy to docs/callpeak.md diff --git a/docs/source/docs/callvar.md b/docs/callvar.md similarity index 100% copy from docs/source/docs/callvar.md copy to docs/callvar.md diff --git a/docs/source/docs/callvar_algorithm.jpeg b/docs/callvar_algorithm.jpeg similarity index 100% copy from docs/source/docs/callvar_algorithm.jpeg copy to docs/callvar_algorithm.jpeg diff --git a/docs/source/docs/cmbreps.md b/docs/cmbreps.md similarity index 100% copy from docs/source/docs/cmbreps.md copy to docs/cmbreps.md diff --git a/docs/source/docs/filterdup.md b/docs/filterdup.md similarity index 100% copy from docs/source/docs/filterdup.md copy to docs/filterdup.md diff --git a/docs/source/docs/hmmratac.md b/docs/hmmratac.md similarity index 100% copy from docs/source/docs/hmmratac.md copy to docs/hmmratac.md diff --git a/docs/source/docs/pileup.md b/docs/pileup.md similarity index 100% copy from docs/source/docs/pileup.md copy to docs/pileup.md diff --git a/docs/source/docs/pileup.png b/docs/pileup.png similarity index 100% copy from docs/source/docs/pileup.png copy to docs/pileup.png diff --git a/docs/source/docs/predictd.md b/docs/predictd.md similarity index 100% copy from docs/source/docs/predictd.md copy to docs/predictd.md diff --git a/docs/source/docs/qa.md b/docs/qa.md similarity index 100% copy from docs/source/docs/qa.md copy to docs/qa.md diff --git a/docs/source/docs/randsample.md b/docs/randsample.md similarity index 100% copy from docs/source/docs/randsample.md copy to docs/randsample.md diff --git a/docs/source/docs/refinepeak.md b/docs/refinepeak.md similarity index 100% copy from docs/source/docs/refinepeak.md copy to docs/refinepeak.md diff --git a/docs/source/conf.py b/docs/source/conf.py index c6435ab..7893dc3 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -16,8 +16,8 @@ release = '3.0.1' extensions = [ 'myst_parser', - #'sphinx.ext.autodoc', - #'sphinx.ext.viewcode', + 'sphinx.ext.autodoc', + 'sphinx.ext.viewcode', 'sphinx.ext.mathjax', 'sphinx.ext.githubpages' ] diff --git a/docs/source/docs/Advanced_Step-by-step_Peak_Calling.md b/docs/source/docs/Advanced_Step-by-step_Peak_Calling.md deleted file mode 100644 index 899f808..0000000 --- a/docs/source/docs/Advanced_Step-by-step_Peak_Calling.md +++ /dev/null @@ -1,291 +0,0 @@ -# Advanced Step-by-step peak calling using MACS3 commands - -Over the years, I have got many emails from users asking if they can -analyze their X-Seq (not ChIP-Seq) data using MACS, or if they can -turn on or off some features in `callpeak` for their special needs. In -most of cases, I would simply reply that they may have to find more -dedicated tool for the type of your data, because the `callpeak` -module is specifically designed and tuned for ChIP-Seq data. However, -MACS3 in fact contains a suite of subcommands and if you can design a -pipeline to combine them, you can control every single step and -analyze your data in a highly customized way. In this tutorial, I show -how the MACS3 main function `callpeak` can be decomposed into a -pipeline containing MACS3 subcommands, -including `filterdup`, `predictd`, `pileup`, `bdgcmp`, `bdgopt`, -and `bdgpeakcall` (or `bdgbroadcall` in case of broad mark). To -analyze your special data in a special way, you may need to skip some -of the steps or tweak some of the parameters of certain steps. Now -let\'s suppose we are dealing with the two testing -files `CTCF_ChIP_200K.bed.gz` and `CTCF_Control_200K.bed.gz`, that you -can find in MACS3 github repository. - -*Note, currently this tutorial is for single-end datasets. Please -modify the command line for paired-end data by yourself.* - -## Step 1: Filter duplicates - -In the first step of ChIP-Seq analysis by `callpeak`, ChIP and control -data need to be read and the redundant reads at each genomic loci have -to be removed. I won\'t go over the rationale, but just tell you how -this can be done by `filterdup` subcommand. By default, the maximum -number of allowed duplicated reads is 1, or `--keep-dup=1` for -`callpeak`. To simulate this behavior, do the following: - -`$ macs3 filterdup -i CTCF_ChIP_200K.bed.gz --keep-dup=1 -o CTCF_ChIP_200K_filterdup.bed` -`$ macs3 filterdup -i CTCF_Control_200K.bed.gz --keep-dup=1 -o CTCF_Control_200K_filterdup.bed` - -You can set different number for `--keep-dup` or let MACS3 -automatically decide the maximum allowed duplicated reads for each -genomic loci for ChIP and control separately. Check `macs3 filterdup --h` for detail, and remember if you go with auto way, the genome size -should be set accordingly. *Note*, in the output, MACS3 will give -you the final number of reads kept after filtering, you\'d better -write the numbers down since we need them when we have to scale the -ChIP and control signals to the same depth. In this case, the number -is 199583 for ChIP and 199867 for control, and the ratio between them -is 199583/199867=.99858 - -## Step 2: Decide the fragment length `d` - -This is an important step for MACS3 to analyze ChIP-Seq and also for -other types of data since the location of sequenced read may only tell -you the end of a DNA fragment that you are interested in (such as TFBS -or DNA hypersensitive regions), and you have to estimate how long this -DNA fragment is in order to recover the actual enrichment. You can also -regard this as a data smoothing technic. You know that `macs3 callpeak` -will output something like, it can identify certain number of pairs of -peaks and it can predict the fragment length, or `d` in MACS3 -terminology, using cross-correlation. In fact, you can also do this -using `predictd` module. Normally, we only need to do this for ChIP -data: - -` -$ macs3 predictd -i CTCF_ChIP_200K_filterdup.bed -g hs -m 5 50 -` - -Here the `-g` (the genome size) need to be set according to your sample, -and the mfold parameters have to be set reasonably. To simulate the -default behavior of `macs3 callpeak`, set `-m 5 50`. Of course, you can -tweak it. The output from `predictd` will tell you the fragment length -`d`, and in this example, it is *254*. Write the number down on your -notebook since we will need it in the next step. Of course, if you do -not want to extend the reads or you have a better estimation on fragment -length, you can simply skip this step. - -## Step 3: Extend ChIP sample to get ChIP coverage track - -Now you have estimated the fragment length, next, we can use MACS3 -`pileup` subcommand to generate a pileup track in BEDGRAPH format for -ChIP sample. Since we are dealing with ChIP-Seq data in this tutorial, -we need to extend reads in 5\' to 3\' direction which is the default -behavior of `pileup` function. If you are dealing with some DNAse-Seq -data or you think the cutting site, that is detected by short read -sequencing, is just in the `middle` of the fragment you are interested -in, you need to use `-B` option to extend the read in both direction. -Here is the command to simulate `callpeak` behavior: - -` -$ macs3 pileup -i CTCF_ChIP_200K_filterdup.bed -o CTCF_ChIP_200K_filterdup.pileup.bdg --extsize 254 -` - -The file `CTCF_ChIP_200K_filterdup.pileup.bdg` now contains the -fragment pileup signals for ChIP sample. - -## Step 4: Build local bias track from control - -By default, MACS3 `callpeak` function computes the local bias by taking -the maximum bias from surrounding 1kb (set by `--slocal`), 10kb (set by -`--llocal`), the size of fragment length `d` (predicted as what you got -from `predictd`), and the whole genome background. Here I show you how -each of the bias is calculated and how they can be combined using the -subcommands. - -### The `d` background - -Basically, to create the background noise track, you need to extend the -control read to both sides (-B option) using `pileup` function. The idea -is that the cutting site from control sample contains the noise -representing a region surrounding it. To do this, take half of `d` you -got from `predictd`, 127 (1/2 of 254) for our example, then: - -` -$ macs3 pileup -i CTCF_Control_200K_filterdup.bed -B --extsize 127 -o d_bg.bdg -` - -The file `d_bg.bdg` contains the `d` background from control. - -### The slocal background - -Next, you can create a background noise track of slocal local window, or -1kb window by default. Simply imagine that each cutting site (sequenced -read) represent a 1kb (default, you can tweak it) surrounding noise. So: - -` -$ macs3 pileup -i CTCF_Control_200K_filterdup.bed -B --extsize 500 -o 1k_bg.bdg -` - -Note, here 500 is the 1/2 of 1k. Because the ChIP signal track was built -by extending reads into `d` size fragments, we have to normalize the 1kb -noise by multiplying the values by `d/slocal`, which is 254/1000=0.254 -in our example. To do so, use the `bdgopt` subcommand: - -` -$ macs3 bdgopt -i 1k_bg.bdg -m multiply -p 0.254 -o 1k_bg_norm.bdg -` - -The file`1k_bg_norm.bdg` contains the slocal background from control. -Note, we don\'t have to do this for `d` background because the -multiplier is simply 1. - -### The llocal background - -The background noise from larger region can be generated in the same way -as slocal backgound. The only difference is the size for extension. -MACS3 `callpeak` by default asks for 10kb (you can change this value) -surrounding window, so: - -` -$ macs3 pileup -i CTCF_Control_200K_filterdup.bed -B --extsize 5000 -o 10k_bg.bdg -` - -The extsize has to be set as 1/2 of llocal. Then, the multiplier now is -`d/llocal`, or 0.0254 in our example. - -` -$ macs3 bdgopt -i 10k_bg.bdg -m multiply -p 0.0254 -o 10k_bg_norm.bdg -` - -The file `10k_bg_norm.bdg` now contains the slocal background from -control. - -### The genome background - -The whole genome background can be calculated as -`the_number_of_control_reads\fragment_length/genome_size`, and in our -example, it is $199867*254/2700000000 ~= .0188023$. You don\'t need to -run subcommands to build a genome background track since it\'s just a -single value. - -### Combine and generate the maximum background noise - -Now all the above background noises have to be combined and the maximum -bias for each genomic location need be computed. This is the default -behavior of MACS3 `callpeak`, but you can have your own pipeline to -include some of them or even make more noise (such as 5k or 50k -background) then include more tracks. Here is the way to combine and get -the maximum bias. - -Take the maximum between slocal (1k) and llocal (10k) background: - -` -macs3 bdgcmp -m max -t 1k_bg_norm.bdg -c 10k_bg_norm.bdg -o 1k_10k_bg_norm.bdg -` - -Then, take the maximum then by comparing with `d` background: - -` -macs3 bdgcmp -m max -t 1k_10k_bg_norm.bdg -c d_bg.bdg -o d_1k_10k_bg_norm.bdg -` - -Finally, combine with the genome wide background using `bdgopt` -subcommand - -` -macs3 bdgopt -i d_1k_10k_bg_norm.bdg -m max -p .0188023 -o local_bias_raw.bdg -` - -Now the file `local_bias_raw.bdg` is a BEDGRAPH file containing the -raw local bias from control data. - -## Step 5: Scale the ChIP and control to the same sequencing depth - -In order to compare ChIP and control signals, the ChIP pileup and -control lambda have to be scaled to the same sequencing depth. The -default behavior in `callpeak` module is to scale down the larger sample -to the smaller one. This will make sure the noise won\'t be amplified -through scaling and improve the specificity of the final results. In our -example, the final number of reads for ChIP and control are 199583 and -199867 after filtering duplicates, so the control bias have to be scaled -down by multiplying with the ratio between ChIP and control which is -199583/199867=.99858. To do so: - -` -$ macs3 bdgopt -i local_bias_raw.bdg -m multiply -p .99858 -o local_lambda.bdg -` - -Now, I name the output file as `local_lambda.bdg` since the values in -the file can be regarded as the lambda (or expected value) and can be -compared with ChIP signals using the local Poisson test. - -## Step 6: Compare ChIP and local lambda to get the scores in pvalue or qvalue - -Next, to find enriched regions and predict the so-called \'peaks\', -the ChIP signals and local lambda stored in BEDGRAPH file have to be -compared using certain statistic model. To do so, you need to use -`bdgcmp` module, which will output score for each basepair in the -genome. You may wonder it may need a huge file to save score for each -basepair in the genome, however the format BEDGRAPH can deal with the -problem by merging nearby regions with the same score. So -theoratically, the size of the output file for scores depends on the -complexity of your data, and the maximum number of data points, if -`d`, `slocal`, and `llocal` background are all used, is the minimum -value of the genome size and approximately -`(#read_ChIP+#reads_control\*3)\*2`, in our case about 1.6 million. -The command to generate score tracks is - -` -$ macs3 bdgcmp -t CTCF_ChIP_200K_filterdup.pileup.bdg -c local_lambda.bdg -m qpois -o CTCF_ChIP_200K_qvalue.bdg -` -or - -` -$ macs3 bdgcmp -t CTCF_ChIP_200K_filterdup.pileup.bdg -c local_bias.bdg -m ppois -o CTCF_ChIP_200K_pvalue.bdg -` - -The `CTCF_ChIP_200K_pvalue.bdg` or `CTCF_ChIP_200K_qvalue.bdg` file -contains the -log10(p-value)s or -log10(q-value)s for each basepair -through local Poisson test, which means the ChIP signal at each basepair -will be tested against the corresponding local lambda derived from -control with Poisson model. *Note*, if you follow this tutorial, then -you won\'t get any `0` in the local lambda track because the smallest -value is the whole genome background; however if you do not include -genome background, you will see many `0`s in local lambda which will -crash the Poisson test. In this case, you need to set the -`pseudocount` for `bdgcmp` through `-p` option. The pseudocount will -be added to both ChIP and local lambda values before Poisson test. The -choice of pseudocount is mainly arbitrary and you can search on the web -to see some discussion. But in general, higher the pseudocount, higher -the specificity and lower the sensitivity. - -## Step 7: Call peaks on score track using a cutoff - -The final task of peak calling is to just take the scores and call those -regions higher than certain cutoff. We can use the `bdgpeakcall` -function for narrow peak calling and `bdgrroadcall` for broad peak -calling, and I will only cover the usage of `bdgpeakcall` in this -tutorial. It looks simple however there are extra two parameters for the -task. First, if two nearby regions are both above cutoff but the region -in-between is lower, and if the region in-between is small enough, we -should merge the two nearby regions together into a bigger one and -tolerate the fluctuation. This value is set as the read length in MACS3 -`callpeak` function since the read length represent the resolution of -the dataset. As for `bdgpeakcall`, you need to get the read length -information from Step 1 or by checking the raw fastq file and set the -`-g` option. Secondly, we don\'t want to call too many small `peaks` -so we need to have a minimum length for the peak. MACS3 `callpeak` -function automatically uses the fragment size `d` as the parameter of -minimum length of peak, and as for `bdgpeakcall`, you need to set the -`-l` option as the `d` you got from Step 2. Last, you have to set the -cutoff value. Remember the scores in the output from `bdgcmp` are in --log10 form, so if you need the cutoff as 0.05, the -log10 value is -about 1.3. The final command is like: - -` -$ macs3 bdgpeakcall -i CTCF_ChIP_200K_qvalue.bdg -c 1.301 -l 245 -g 100 -o CTCF_ChIP_200K_peaks.bed -` - -The output is in fact a narrowPeak format file (a type of BED file) -which contains locations of peaks and the summit location in the last -column. - - diff --git a/docs/source/docs/Advanced_Step-by-step_Peak_Calling.md b/docs/source/docs/Advanced_Step-by-step_Peak_Calling.md new file mode 120000 index 0000000..f137a3d --- /dev/null +++ b/docs/source/docs/Advanced_Step-by-step_Peak_Calling.md @@ -0,0 +1 @@ +../../../docs/Advanced_Step-by-step_Peak_Calling.md \ No newline at end of file diff --git a/docs/source/docs/BED.md b/docs/source/docs/BED.md deleted file mode 100644 index 800e0f6..0000000 --- a/docs/source/docs/BED.md +++ /dev/null @@ -1 +0,0 @@ -# BED format diff --git a/docs/source/docs/BEDPE.md b/docs/source/docs/BEDPE.md deleted file mode 100644 index 3ee3ff1..0000000 --- a/docs/source/docs/BEDPE.md +++ /dev/null @@ -1,26 +0,0 @@ -# BEDPE format - -The BEDPE format is specifically designed for keeping the alignment -locations of each read pair from Paired-End library. This is not a -general format but only a format for MACS3. It only contains three -columns -- the chromosome, the leftmost position of read pair, and the -rightmost position of the read pair. These three columns All other information from -alignment will not be kept in this format, such as the length of the -read, the mismatches/gaps in the alignment, and etc. An example is as -followed: - -``` -chrXIII 0 60 -chrXIII 1 64 -chrXIII 1 211 -chrXIII 2 46 -chrXIII 3 154 -chrXIII 3 209 -chrXIII 9 71 -chrXIII 11 67 -chrXIII 11 71 -chrXIII 14 71 -... -``` - - diff --git a/docs/source/docs/INSTALL.md b/docs/source/docs/INSTALL.md deleted file mode 100644 index 3740779..0000000 --- a/docs/source/docs/INSTALL.md +++ /dev/null @@ -1,153 +0,0 @@ -# INSTALL Guide For MACS3 - -Please check the following instructions to complete your installation. - -## Prerequisites - -Here we list some prerequisites for installing and running MACS3. But -if you are using conda or pip to install, the installer will check the -dependencies and install them if necessary. Therefore, this section is -for reference purpose, and if you are just looking for steps to -install MACS3, please go to the next section. Please note that, we -haven't tested installation on any Windows OS, so currently only Linux -and Mac OS systems are supported. - -### Python3 - -MACS v3 requires Python3. We have tested MACS in Python3.9 to 3.12. - -### NumPy, hmmlearn, Scipy, scikit-learn - -MACS calls functions from [NumPy](https://numpy.org/) and -[hmmlearn](https://hmmlearn.readthedocs.io/). Since hmmlearn further -requires [scikit-learn](https://scikit-learn.org/) which requires -[SciPy](https://scipy.org/), and these libraries are crucial for -reproducing your results, we also add them into the requirement list -with specific version numbers. So here is the list of the required -python libraries that will impact the numerical calculation in MACS3: - - - numpy>=1.25 - - hmmlearn>=0.3.2 - - scikit-learn>=1.3 - - scipy>=1.12 - -### Cython - -[Cython](http://cython.org/) is required to translate .pyx codes to .c -code. The version of Cython has to be >=3.0. - -### cykhash - -[cykhash](https://github.com/realead/cykhash) is a fast and efficient -hash implementation in Cython. It can be seen as the cython -implementation of -[khash](https://github.com/attractivechaos/klib/blob/master/khash.h). It -is used to replace python dictionary in MACS3 codes. We require -cykhash version 2. - -### fermi-lite and simde - -A newly added `callvar` subcommand in MACS3 uses -[fermi-lite](https://github.com/lh3/fermi-lite) to assemble the DNA -sequence in a peak region while necessary. A modified fermi-lite has -been included in MACS3 package. Since fermi-lite was implemented using -intel SSE2 intrinsics for x86 CPUs, we added -[simde](https://github.com/simd-everywhere/simde) as submodule to -solve the compatibility issues on non-x86 architectures. Note that, we -may remove this submodule and add simde in *dependencies* of MACS3 -later. - -### GCC, Python-dev, meson ... - -GCC is required to compile `.c` codes in MACS v3 package, and python -header files are needed. If you are using Mac OSX, we recommend you -install Xcode; if you are using Linux, you need to make sure -`python-dev` package is installed -- the actual package name depends -on the Linux OS distribution, you are using. Also, since the most -recent Numpy/Scipy use [meson](https://mesonbuild.com/) to build the -libraries, make sure they have been installed. - -## Prepare a virtual Python environment - -We strongly recommend installing your MACS program in a virtual -environment, so that you have full control of your installation and -won't mess up with your system libraries. To learn about virtual -environment, read [this -article](https://docs.python.org/3/library/venv.html). A simple way to -create a virtual environment of Python3 is - -`$ python3 -m venv MACS3env/` - -Then activate it by - -`$ source MACS3env/bin/activate` - -If you use 'conda', it will also provide virtual environment. Please -read: -[conda](https://docs.conda.io/projects/conda/en/latest/user-guide/getting-started.html) -or [miniconda](https://docs.conda.io/en/latest/miniconda.html) For -example, after installing 'conda', you can use `conda create -n MACS3` -to create a new environment called 'MACS3' then switch to this -environment with `conda activate MACS3`. - -There is another solution, [pipx](https://pipx.pypa.io/), to make a -clean isolated python environment to run python tools such as -MACS3. We won't explore it here but if you are insterested in it, -please click the link above and read the tutorial. - -## Install through PyPI - -The easiest way to install MACS is through PyPI system. Get `pip` if -it's not available in your system. If you create a virtual environment -as described before, your `pip` command will install everything under -the folder you specified previously through `python3 -m env` command, -or to your active conda environment. - -Then under the command line, type `pip install macs3`. PyPI will -install dependencies automatically if it is absent. By default, `pip` -will install the newest version of dependencies that satisfy the -requirements of MACS3. When you run the command without virtual -environment, you may need to be the root user or system administrator -so as to complete the installation. Please contact the system -administrator if you want their help. - -To upgrade MACS3, type `pip install --upgrade macs3`. It will check -currently installed MACS3, compare the version with the one on PyPI -repository, download and install a newer version while necessary. - -## Install through conda - -To install MACS3 using 'conda', simply execute `conda install -c -bioconda macs3` in your conda environment. This command installs MACS3 -along with its dependencies from the Bioconda channel. Please ensure -conda is installed and a dedicated conda environment has been created -and activated beforehand for a smooth installation process. - -## Install from source through pip - -MACS uses `pip` for source code installations. To install a source -distribution of MACS, unpack the distribution tarball, or clone Git -repository with `git clone --recurse-submodules -git@github.com:macs3-project/MACS.git`. Go to the directory where you -cloned MACS from github or unpacked from tarball, and simply run the -install command: - - `$ pip install .` - -The command will treat the current working directory as the 'package' -to be installed. The behavior will be the same as `pip install macs3` -as described in the previous section "Install through PyPI". - -You can also install MACS3 from source code in a "modern" two-steps -way. First, use the build system to make a wheel (in this case, you -need to install `build` first by `pip install build`): - -`$ python -m build --wheel` - -This will make a '.whl' file under 'dist' directory. Then you can -install the wheel through `pip`: - -`$ pip install dist/MACS3-3.x.x-x-x-x.whl` - -Please use the real filename in the 'dist' directory. - diff --git a/docs/source/docs/INSTALL.md b/docs/source/docs/INSTALL.md new file mode 120000 index 0000000..ea47b62 --- /dev/null +++ b/docs/source/docs/INSTALL.md @@ -0,0 +1 @@ +../../../docs/INSTALL.md \ No newline at end of file diff --git a/docs/source/docs/SAMBAMBAMPE.md b/docs/source/docs/SAMBAMBAMPE.md deleted file mode 100644 index bc583ed..0000000 --- a/docs/source/docs/SAMBAMBAMPE.md +++ /dev/null @@ -1,2 +0,0 @@ -# SAM/BAM/BAMPE format - diff --git a/docs/source/docs/bdgbroadcall.md b/docs/source/docs/bdgbroadcall.md deleted file mode 100644 index 805ba21..0000000 --- a/docs/source/docs/bdgbroadcall.md +++ /dev/null @@ -1,79 +0,0 @@ -# bdgbroadcall - -## Overview -The `bdgbroadcall` subcommand of the MACS3 suite identifies 'nested' -broad peaks from a single bedGraph track for scores, a function -essential in certain ChIP-Seq analyses. - -## Detailed Description - -The `bdgbroadcall` command takes an input bedGraph file and produces -an output file with broad peaks called. It is important to note: only -bedGraph files from MACS3 are acceptable to use in the `bdgbroadcall` -command, as All regions on the same chromosome in the bedGraph file -should be continuous. - -Unlike narrow peak calling performed using `bdgpeakcall` or `callpeak` -without the `--broad` option, this command, along with the `--broad` -option in `callpeak`, facilitates broad peak calling, producing -results in the UCSC gappedPeak format which encapsulates a nested -structure of peaks. To conceptualize 'nested' peaks, picture a gene -structure housing regions analogous to exons (strong peaks) and -introns coupled with UTRs (weak peaks). The broad peak calling process -utilizes two distinct cutoffs to discern broader, weaker peaks and -narrower, stronger peaks, which are subsequently nested to provide a -detailed peak landscape. - -Please note that, if you only want to call 'broader' peak and not -interested in the nested peak structure, please simply use -`bdgpeakcall` with weaker cutoff. - -## Command Line Options - -The command line options for `bdgbroadcall` are defined in `macs3 -bdgbroadcall --help` command. Here is a brief overview of these -options: - -- `-i` or `--ifile`: Genome-wide score for each possible location in - bedGraph format. This is REQUIRED. -- `-c` or `--cutoff-peak`: Cutoff for stronger and narrower peaks - depending on which method you used for the score track. If the file - contains qvalue scores from MACS3, score 2 means qvalue 0.01. - DEFAULT: 2 -- `-C` or `--cutoff-link`: Cutoff for weaker and broader regions - depending on which method you used for the score track. If the file - contains qvalue scores from MACS3, score 1 means qvalue 0.1, and - score 0.3 means qvalue 0.5. DEFAULT: 1 -- `-l` or `--min-length`: Minimum length of stronger peak, better to - set it as d value. DEFAULT: 200 -- `-g` or `--lvl1-max-gap`: Maximum gap between stronger peaks, better - to set it as the tag size. DEFAULT: 30 -- `-G` or `--lvl2-max-gap`: Maximum gap between weaker peaks, better - to set it as 4 times the d value. DEFAULT: 800 -- `--no-trackline`: Tells MACS not to include a trackline with - bedGraph files. The trackline is used by UCSC for display. -- `--verbose`: Set verbose level of runtime messages. 0: only show - critical messages, 1: show additional warning messages, 2: show - process information, 3: show debug messages. DEFAULT: 2 -- `--outdir`: If specified, all output files will be written to that - directory. Default: the current working directory -- `-o` or `--ofile`: Output file name. Mutually exclusive with - `--o-prefix`. -- `--o-prefix`: Output file prefix. Mutually exclusive with - `-o/--ofile`. - -## Example Usage - -Here is an example of how to use the `bdgbroadcall` command: - -``` -macs3 bdgbroadcall -i input.bedGraph -o output.gappedPeak -c 2 -C 1.5 -l 500 -g 500 -G 1000 -``` - -In this example, the program will call broad peaks from the -`input.bedGraph` file and write the result to `output.gappedPeak`. The -cutoff value for calling stronger peaks is set to 2.0, the minimum -length of stronger peaks is set to 500, the maximum gap between -stronger peaks is set to 500, the cutoff value for weaker peaks is set -to 1.5, and the maximum gap for weaker peaks is set to 1000. - diff --git a/docs/source/docs/bdgbroadcall.md b/docs/source/docs/bdgbroadcall.md new file mode 120000 index 0000000..c22e540 --- /dev/null +++ b/docs/source/docs/bdgbroadcall.md @@ -0,0 +1 @@ +../../../docs/bdgbroadcall.md \ No newline at end of file diff --git a/docs/source/docs/bdgcmp.md b/docs/source/docs/bdgcmp.md deleted file mode 100644 index 099f929..0000000 --- a/docs/source/docs/bdgcmp.md +++ /dev/null @@ -1,92 +0,0 @@ -# bdgcmp - -## Overview -The `bdgcmp` command is part of the MACS3 suite of tools and is used -to compare two bedGraph files in each basepair that are commonly -covered by the two files. The typical use case is to calculate pvalue -or qvalue using Poisson model for each basepair given a treatment -pileup signal file in bedGraph format and a control lambda bedGraph -file. But we provides more functions rather than pvalue and qvalue, -including subtract, division (FE) and more. - -## Detailed Description - -The `bdgcmp` command takes two input bedGraph files (e.g. a control -and a treatment bedgraph) and produces an output bedGraph of -comparison scores for each genomic position involved in the bedGraph -files. The `bdgcmp` command normally is used to deduct noise from a -signal track in bedGraph (e.g. ChIP treatment) over another signal -track in bedGraph (e.g. control). Note: All regions on the same -chromosome in the bedGraph file should be continuous so we recommand -you use the bedGraph files from MACS3. We provide the following -function to 'compare two tracks': - -- `ppois` Poisson p-value (-log10(pvalue) form) using the second file - (-c) as lambda and treatment (-t) as observation -- `qpoi`s The q-value through a BH process for poisson pvalues -- `subtract` Subtraction from treatment -- `FE` linear scale fold enrichment, or the score from file A divided - by the score from file B -- `logFE` log10 fold enrichment(need to set pseudocount) -- `logLR` log10 likelihood between ChIP-enriched model and open - chromatin model (need to set pseudocount) -- `slogLR` symmetric log10 likelihood between two ChIP-enrichment - models using Poison distribution, and this can be used to compare - ChIP signals from two differen conditions (differential binding) -- `max` Maximum value between the two tracks. - -## Command Line Options - -Here is a brief description of the command line options for `bdgcmp` : - -- `-t` or `--tfile`: Treatment bedGraph file, e.g. *_treat_pileup.bdg - from MACS. REQUIRED -- `-c` or `--cfile`: Control bedGraph file, e.g. *_control_lambda.bdg - from MACS. REQUIRED -- `-S` or `--scaling-factor`: Scaling factor for treatment and control - track. Keep it as 1.0 or default in most cases. Set it ONLY while - you have SPMR output from MACS3 callpeak, and plan to calculate - scores as MACS3 callpeak module. If you want to simulate 'callpeak' - w/o '--to-large', calculate effective smaller sample size after - filtering redundant reads in million (e.g., put 31.415926 if - effective reads are 31,415,926) and input it for '-S'; for 'callpeak - --to-large', calculate effective reads in a larger sample. DEFAULT: - 1.0 -- `-p` or `--pseudocount`: The pseudocount used for calculating logLR, - logFE or FE. The count will be applied after normalization of - sequencing depth. DEFAULT: 0.0, no pseudocount is applied. -- `-m` or `--method`: Method to use while calculating a score in any - bin by comparing the treatment value and control value. Available - choices are: `ppois`, `qpois`, `subtract`, `logFE`,` logLR`, - `slogLR`, and `max`. They represent Poisson P-value (-log10(pvalue) - form) using control as lambda and treatment as observation, q-value - through a BH process for Poisson p-values, subtraction from - treatment, linear scale fold enrichment, log10 fold enrichment (need - to set pseudocount), log10 likelihood between ChIP-enriched model - and open chromatin model (need to set pseudocount), symmetric log10 - likelihood between two ChIP-enrichment models, or the maximum value - between the two tracks. The default option is ppois. -- `--verbose`: Set the verbose level of runtime messages. 0: only show - critical messages, 1: show additional warning messages, 2: show - process information, 3: show debug messages. DEFAULT: 2 -- `--outdir`: If specified, all output files will be written to that - directory. Default: the current working directory -- `--o-prefix`: The PREFIX of the output bedGraph file to write - scores. If it is given as A, and the method is 'ppois', the output - file will be A_ppois.bdg. Mutually exclusive with -o/--ofile. -- `-o` or `--ofile`: Output filename. Mutually exclusive with - --o-prefix. The number and the order of arguments for --ofile must - be the same as for -m. - -## Example Usage - -Here is an example of how to use the `bdgcmp` command: - -```bash -macs3 bdgcmp -t treatment.bedGraph -c control.bedGraph -m ppois -p 1.0 -S 1.0 -o output.bedGraph -``` - -In this example, the program will compare the `treatment.bedGraph` -file and the `control.bedGraph` file and write the result to -`output.bedGraph`. The method used for comparison is `ppois`, the -pseudo-count is set to 1.0, and the scaling factor is set to 1.0. diff --git a/docs/source/docs/bdgcmp.md b/docs/source/docs/bdgcmp.md new file mode 120000 index 0000000..62bf82a --- /dev/null +++ b/docs/source/docs/bdgcmp.md @@ -0,0 +1 @@ +../../../docs/bdgcmp.md \ No newline at end of file diff --git a/docs/source/docs/bdgdiff.md b/docs/source/docs/bdgdiff.md deleted file mode 100644 index dd22107..0000000 --- a/docs/source/docs/bdgdiff.md +++ /dev/null @@ -1,207 +0,0 @@ -# bdgdiff - -## Overview -The `bdgdiff` command is part of the MACS3 suite of tools and is used -to call differential peaks from four bedGraph tracks of scores, -including treatment and control track for each condition. - - -## Detailed Description - -The `bdgdiff` command takes four input bedGraph files (two treatment -and two control files) and produces three output files with -differential peaks called. Users should provide paired four bedgraph -files: for each condition, a treatment pileup signal track in bedGraph -format, and a control lambda track in bedGraph format. This -differential calling can only handle one replicate per condition, so -if you have multiple replicates, you should either combine the -replicates when `callpeak`, or choose other tool that can consider -within-group variation (such as DESeq2 or edgeR). The method we use to -define the differential peaks is based on multiple likelihood tests, -based on the poisson distribution. Suppose that we have two conditions -A and B, the unique binding sites in condition A over condition B -should be *more likely* to be a binding event in treatment A over -treatment B, and also *more likely* to be a real binding site in -condition A while comparing treatment A over control A; the unique -binding sites in condition B is defined in the same way; the common -peaks of both condition should be *more likely* to be a real binding -sites in condition A while comparing treatment A and control A, and in -condition B while comparing treatment B over control B, and also the -likelihood test while comparing treatment A and treatment B can't -decide which condition is stronger. - -The likelihood function we used while comparing two conditions: ChIP -(enrichment) or control (chromatin bias) is: - -$$ln(LR) = x*(ln(x)-ln(y)) + y - x$$ - -Here $LR$ is the likelihood ratio, x is the signal (fragment pileup) -we observed in condition 1, and y is the signal in condition -2. And $ln$ is the natural logarithm. - -Note: All regions on the same chromosome in the bedGraph file should -be continuous so only bedGraph files from MACS3 are acceptable. - -## Command Line Options - -The command line options for `bdgdiff` are defined in `/MACS3/Commands/bdgdiff_cmd.py` and `/bin/macs3` files. Here is a brief overview of these options: - -- `--t1`: MACS pileup bedGraph for condition 1. Incompatible with - callpeak --SPMR output. REQUIRED -- `--t2`: MACS pileup bedGraph for condition 2. Incompatible with - callpeak --SPMR output. REQUIRED -- `--c1`: MACS control lambda bedGraph for condition 1. Incompatible - with callpeak --SPMR output. REQUIRED -- `--c2`: MACS control lambda bedGraph for condition 2. Incompatible - with callpeak --SPMR output. REQUIRED -- `-C` or `--cutoff`: log10LR cutoff. Regions with signals lower than - the cutoff will not be considered as enriched regions. DEFAULT: 3 - (likelihood ratio=1000) -- `-l` or `--min-len`: Minimum length of the differential region. Try - a bigger value to remove small regions. DEFAULT: 200 -- `-g` or `--max-gap`: Maximum gap to merge nearby differential - regions. Consider a wider gap for broad marks. The maximum gap - should be smaller than the minimum length (-g). DEFAULT: 100 -- `--d1` or `--depth1`: Sequencing depth (# of non-redundant reads in - million) for condition 1. It will be used together with --d2. See - the description for --d2 below for how to assign them. Default: 1 -- `--d2` or `--depth2`: Sequencing depth (# of non-redundant reads in - million) for condition 2. It will be used together with --d1. DEPTH1 - and DEPTH2 will be used to calculate the scaling factor for each - sample, to down-scale the larger sample to the level of the smaller - one. For example, while comparing 10 million condition 1 and 20 - million condition 2, use --d1 10 --d2 20, then the pileup value in - bedGraph for condition 2 will be divided by 2. Default: 1 -- `--verbose`: Set the verbose level of runtime messages. 0: only show - critical messages, 1: show additional warning messages, 2: show - process information, 3: show debug messages. DEFAULT: 2 -- `--outdir`: If specified, all output files will be written to that - directory. Default: the current working directory -- `--o-prefix`: Output file prefix. Actual files will be named as - PREFIX_cond1.bed, PREFIX_cond2.bed, and PREFIX_common.bed. Mutually - exclusive with -o/--ofile. -- `-o` or `--ofile`: Output filenames. Must give three arguments in - order: 1. file for unique regions in condition 1; 2. file for unique - regions in condition 2; 3. file for common regions in both - conditions. Note: mutually exclusive with --o-prefix. - - -## Example Usage - -Here is an example of how to use the `bdgdiff` command: - -```bash -macs3 bdgdiff -t1 treatment1.bedGraph -c1 control1.bedGraph -t2 treatment2.bedGraph -c2 control2.bedGraph --depth1 1.0 --depth2 1.0 -o output.bedGraph --minlen 500 --maxgap 1000 --cutoff 1.0 -``` - -In this example, the program will call differential peaks from the two -pairs of treatment and control bedGraph files and write the result to -`output.bedGraph`. The depth of the first and second condition is set -to 1.0, the minimum length of differential peaks is set to 500, the -maximum gap between differential peaks is set to 1000, and the cutoff -for log10LR to call differential peaks is set to 1.0 (or likelihood -ratio 10). - -## Step-by-step Instruction for calling differential peaks - -In this chatper, we will describe how to use MACS3 to identify -differential regions by comparing pileup tracks of two conditions, -starting from the alignment files. Two modules will be involved: -`callpeak` and `bdgdiff` ( `predictd` is optional ). We will use human -ChIP-seq data as example, and filenames of raw data are: -cond1_ChIP.bam and cond1_Control.bam for condition 1; cond2_ChIP.bam -and cond2_Control.bam for condition 2. - -### Step 1: Generate pileup tracks using callpeak module - -Purpose of this step is to use `callpeak` with -B option to generate -bedGraph files for both conditions. There are several things to -remember: 1. `--SPMR` is not compatible with `bdgdiff`, so avoid using -it; 2. prepare a pen to write down the number of non-redundant reads -of both conditions -- you will find such information in runtime -message or xls output from `callpeak`; 3. keep using the same -`--extsize` for both conditions ( you can get it from `predictd` -module). - -To get a uniform extension size for running `callpeak`, run `predictd`: - -``` - $ macs3 predictd -i cond1_ChIP.bam - - $ macs3 predictd -i cond2_ChIP.bam -``` - -An easy solution is to use the average of two 'fragment size' -predicted in `callpeak`, however any reasonable value will work. For -example, you can use `200` for most ChIP-seq datasets for -transcription factors, or ''147'' for most histone modification -ChIP-seq. The only requirement is that you have to keep using the same -extsize for the following commands: - -``` - $ macs3 callpeak -B -t cond1_ChIP.bam -c cond1_Control.bam -n cond1 --nomodel --extsize 120 - - $ macs3 callpeak -B -t cond2_ChIP.bam -c cond2_Control.bam -n cond2 --nomodel --extsize 120 -``` - -Pay attention to runtime message, or extract the "tags after filtering in treatment" and "tags after filtering in control" lines from xls to see the effective sequencing depths for both conditions. In our previous command lines, '--to-large' is not used, so the effective sequencing depth is the smaller number of treatment and control. For example: - -``` - $ egrep "tags after filtering in treatment|tags after filtering in control" cond1_peaks.xls - # tags after filtering in treatment: 19291269 - # tags after filtering in control: 12914669 - - $ egrep "tags after filtering in treatment|tags after filtering in control" cond2_peaks.xls - # tags after filtering in treatment: 19962431 - # tags after filtering in control: 14444786 -``` - -Then actual effective depths of condition 1 and 2 are: 12914669 -and 14444786. Keep record of these two numbers and we will use them -later. After successfully running '''callpeak''', you will have -''cond1_treat_pileup.bdg'', ''cond1_control_lambda.bdg'', -''cond2_treat_pileup.bdg'', and ''cond2_control_lambda.bdg'' in the -working directory. - -### Step 2: Call differential regions - -The purpose of this step is to do a three ways comparisons to find out -where in the genome has differential enrichment between two -conditions. A basic requirement is that this region should be at least -enriched in either condition. A log10 likelihood ratio cutoff (C) will -be applied in this step. Three types of differential regions will be -reported: 1. those having more enrichment in condition 1 over -condition 2 ( cond1_ChIP > cond1_Control and cond1_ChIP > cond2_ChIP -); 2. those having more enrichment in condition 2 over condition 1 ( -cond2_ChIP > cond2_Control and cond2_ChIP > cond1_ChIP ); those having -similar enrichment in both conditions ( cond1_ChIP > cond1_Control and -cond2_ChIP > cond2_Control and cond1_ChIP ≈ cond1_ChIP ). - -Run this: - -``` - $ macs3 bdgdiff --t1 cond1_treat_pileup.bdg --c1 cond1_control_lambda.bdg --t2 cond2_treat_pileup.bdg\ - --c2 cond2_control_lambda.bdg --d1 12914669 --d2 14444786 -g 60 -l 120 --o-prefix diff_c1_vs_c2 -``` - -You will get the following three files in working directory: - - 1. `diff_c1_vs_c2_c3.0_cond1.bed` This file stores regions that are - highly enriched in condition 1 comparing to condition 2. The last - column in the file represent the log10 likelihood ratio to show how - likely the observed signal in condition 1 in this region is from - condition 1 comparing to condition 2. The higher the value, the - greater the difference. - - 2. `diff_c1_vs_c2_c3.0_cond2.bed` This file stores regions that are - highly enriched in condition 2 comparing to condition 1. The last - column in the file represent the log10 likelihood ratio to show how - likely the observed signal in condition 2 in this region is from - condition 2 comparing to condition 1. Higher the value, bigger the - difference. - - 3. `diff_c1_vs_c2_c3.0_common.bed` This file stores regions that are - highly enriched in both condition 1 and condition 2, and the - difference between condition 1 and condition 2 is not - significant. The last column in the file represent the difference - between condition 1 and condition 2 in log10 likelihood ratios. diff --git a/docs/source/docs/bdgdiff.md b/docs/source/docs/bdgdiff.md new file mode 120000 index 0000000..365bae0 --- /dev/null +++ b/docs/source/docs/bdgdiff.md @@ -0,0 +1 @@ +../../../docs/bdgdiff.md \ No newline at end of file diff --git a/docs/source/docs/bdgopt.md b/docs/source/docs/bdgopt.md deleted file mode 100644 index 8bd7e0b..0000000 --- a/docs/source/docs/bdgopt.md +++ /dev/null @@ -1,80 +0,0 @@ -# bdgopt - -## Overview -The `bdgopt` command is part of the MACS3 suite of tools and is used -to modify a single bedGraph file. It provides various operations to -modify the value in the fourth column of the bedGraph file -- the -score column. - -## Detailed Description - -The `bdgopt` command takes an input bedGraph file and produces an -output file with modified scores. It uses various methods to modify -the scores in the bedGraph files, greatly improving the flexibility of -your data for further analysis. Operations on score column of bedGraph -file include multiplication, addition, maximization with a given -value, minimization with a given value, and pvalue-to-qvalue -conversion (-log10 form). Note: All regions on the same chromosome in -the bedGraph file should be continuous. We recommend to use the -bedGraph files from MACS3. - -## Command Line Options - -Here is a brief overview of the commandline options: - -- `-i` or `--ifile`: A bedGraph file containing scores. Note: this - must be a bedGraph file covering the ENTIRE genome. REQUIRED -- `-m` or `--method`: Method to modify the score column of the - bedGraph file. Available choices are: multiply, add, max, min, or - p2q. - - `multiply`: The EXTRAPARAM is required and will be multiplied to - the score column. If you intend to divide the score column by X, - use the value of 1/X as EXTRAPARAM. - - `add`: The EXTRAPARAM is required and will be added to the score - column. If you intend to subtract the score column by X, use the - value of -X as EXTRAPARAM. - - `max`: The EXTRAPARAM is required and will take the maximum - value between the score and the EXTRAPARAM. - - `min`: The EXTRAPARAM is required and will take the minimum - value between the score and the EXTRAPARAM. - - `p2q`: This will convert p-value scores to q-value scores using - the Benjamini-Hochberg process. The EXTRAPARAM is not - required. This method assumes the scores are -log10 p-value from - MACS3. Any other types of scores will cause unexpected errors. -- `-p` or `--extra-param`: The extra parameter for METHOD. Check the - detail of the -m option. -- `--outdir`: If specified, all output files will be written to that - directory. Default: the current working directory -- `-o` or `--ofile`: Output BEDGraph filename. -- `--verbose`: Set the verbose level of runtime messages. 0: only show - critical messages, 1: show additional warning messages, 2: show - process information, 3: show debug messages. DEFAULT: 2 - - -## Example Usage - -Here is an example of how to use the `bdgopt` command: - -```bash -macs3 bdgopt -i input.bedGraph -o output.bedGraph --method multiply --extraparam 2.0 -``` - -In this example, the program will modify the scores in the -`input.bedGraph` file and write the result to `output.bedGraph`. The -method used for modification is `multiply`, and the extra parameter is -set to 2.0, meaning that all scores will be multiplied by 2.0. - -Some use cases for `bdgopt`: - -1. If you plan to scale up or down the scores in the bedGraph file, - you can use `-m multiply` with a larger than 1 (>1) EXTRAPARAM in - `-p` to scale up, or a positive value smaller than 1 (>0 and <1) - EXTRAPARAM in `-p` to scale up; or `-m add` with a positive value - in `-p` to increase the scores by a fixed amount or a negative - value to decrease the scores. -2. If you want to cap the score in the bedGraph, you can use `-m max` - with the upper limit score you want to use in `-p`. If you want to - set the minimum score in the bedGraph, for example to set the whole - genome background signal in the MACS control lambda track, you can - use `-m min` with the value in `-p`. - diff --git a/docs/source/docs/bdgopt.md b/docs/source/docs/bdgopt.md new file mode 120000 index 0000000..33d6517 --- /dev/null +++ b/docs/source/docs/bdgopt.md @@ -0,0 +1 @@ +../../../docs/bdgopt.md \ No newline at end of file diff --git a/docs/source/docs/bdgpeakcall.md b/docs/source/docs/bdgpeakcall.md deleted file mode 100644 index 9ae7821..0000000 --- a/docs/source/docs/bdgpeakcall.md +++ /dev/null @@ -1,122 +0,0 @@ -# bdgpeakcall - -## Overview -The `bdgpeakcall` command is part of the MACS3 suite of tools and is -used to call peaks from a single bedGraph track for scores. - -## Detailed Description -The `bdgpeakcall` command takes an input bedGraph file, a cutoff -value, and the options to control peak width, then produces an output -file with peaks called. This tool can be used as a generic peak caller -that can be applied to any scoring system in a BedGraph file, no -matter the score is the pileup, the p-value, or the fold change -- or -any other measurement to decide the 'significancy' of the genomic -loci. - -Note: All regions on the same chromosome in the bedGraph file should -be continuous. - -## Command Line Options - -Here is a brief overview of the command line options for `bdgpeakcall`: - -- `-i` or `--ifile`: MACS score, or any numerical measurement score in - bedGraph. The only assumption on the score is that higher the score - is, more significant the genomic loci is. REQUIRED -- `-c` or `--cutoff`: Cutoff depends on which method you used for the - score track. If the file contains -log10(p-value) scores from - MACS3, score 5 means pvalue 1e-5. Regions with signals lower than - the cutoff will not be considered as enriched regions. DEFAULT: 5 -- `-l` or `--min-length`: Minimum length of peak, better to set it as - d value if we will deal with MACS3 generated scores. DEFAULT: 200 -- `-g` or `--max-gap`: Maximum gap between significant points in a - peak, better to set it as the tag size if we will deal with MACS3 - generated scores. DEFAULT: 30 -- `--cutoff-analysis`: While set, bdgpeakcall will analyze the number - or total length of peaks that can be called by different cutoff - then output a summary table to help the user decide a better - cutoff. Note, minlen and maxgap may affect the results. Also, if - this option is on, `bdgpeakcall` will analyze the outcome of - different cutoff values and then quit without calling any peaks. - DEFAULT: False -- `--cutoff-analysis-steps`: Steps for performing cutoff analysis. It - will be used to decide which cutoff value should be included in the - final report. Larger the value, higher resolution the cutoff - analysis can be. The cutoff analysis function will first find the - smallest (at least 0) and the largest (at most 1,000) score in the - bedGraph, then break the range of score into - `CUTOFF_ANALYSIS_STEPS` intervals. It will then use each score as - cutoff to call peaks and calculate the total number of candidate - peaks, the total basepairs of peaks, and the average length of peak - in basepair. Please note that the final report ideally should - include `CUTOFF_ANALYSIS_STEPS` rows, but in practice, if the - cutoff yield zero peak, the row for that value won't be included. - DEFAULT: 100", default = 100 ) -- `--no-trackline`: Tells MACS not to include a trackline with - bedGraph files. The trackline is used by UCSC for the options for - display. -- `--verbose`: Set the verbose level of runtime messages. 0: only show - critical messages, 1: show additional warning messages, 2: show - process information, 3: show debug messages. DEFAULT: 2 -- `--outdir`: If specified, all output files will be written to that - directory. Default: the current working directory -- `-o` or `--ofile`: Output file name. Mutually exclusive with - `--o-prefix`. -- `--o-prefix`: Output file prefix. Mutually exclusive with - `-o/--ofile`. - - -## Example Usage - -Here is an example of how to use the `bdgpeakcall` command: - -```bash -macs3 bdgpeakcall -i input.bedGraph -o output.narrowPeak --cutoff 1.0 --minlen 500 --maxgap 1000 -``` - -In this example, the program will call peaks from the `input.bedGraph` -file and write the result to `output.narrowPeak`. The cutoff for -calling peaks is set to 1.0, the minimum length of peaks is set to -500, and the maximum gap between peaks is set to 1000. - -## Cutoff Analysis - -The cutoff analysis function is provided by `--cutoff-analysis` option -in `callpeak`, `bdgpeakcall`, and `hmmratac`. However, the function is -`bdgpeakcall` is more flexible and can be applied on any scoring -scheme. We will separate this function into a dedicated subcommand in -the future. - -Please note that if this `--cutoff-anlaysis` option is on, the -`bdgpeakcall` won't write any results of the peaks into narrowPeak -format file, ignoring `-c` you specified. Instead, it will write a -cutoff analysis report (`-o`) and quit. - -When the option is on, we will first calculate the window of step for -increasing the cutoff from the lowest (`min_v`) to the highest -(`max_v`), using the `--cutoff-analysis-steps`: - -`win_step = (max_v-min_v)/steps`. - -Then for each cutoff we plan to investigate, we will check the number -of peaks that can be called, their average peak length, and their -total length. The smallest cutoff (close to `min_v`) and any cutoff -that can't lead to any peak will be excluded in the final report. - -The report consists of four columns: - -1. score: the possible fold change cutoff value. -2. npeaks: the number of peaks under this cutoff. -3. lpeaks: the total length of all peaks. -4. avelpeak: the average length of peaks. - -While there's no universal rule to suggest the best cutoff, here are a -few suggestions: - -- You can use elbow analysis to find the cutoff that dramatically - change the trend of npeaks, lpeaks, or avelpeak. But you need to - think about how to define 'dramatical change'. -- You can use some common expectation to decide the cutoff. For - example, the number of peaks should be thousands/ or the avelpeak - should be around 500bps. Of course, it's arbitrary but the table - will give you some insight. diff --git a/docs/source/docs/bdgpeakcall.md b/docs/source/docs/bdgpeakcall.md new file mode 120000 index 0000000..e31f54d --- /dev/null +++ b/docs/source/docs/bdgpeakcall.md @@ -0,0 +1 @@ +../../../docs/bdgpeakcall.md \ No newline at end of file diff --git a/docs/source/docs/bedGraph.md b/docs/source/docs/bedGraph.md deleted file mode 100644 index 6aa5bbc..0000000 --- a/docs/source/docs/bedGraph.md +++ /dev/null @@ -1 +0,0 @@ -# bedGraph format diff --git a/docs/source/docs/broadPeak.md b/docs/source/docs/broadPeak.md deleted file mode 100644 index 523509b..0000000 --- a/docs/source/docs/broadPeak.md +++ /dev/null @@ -1 +0,0 @@ -# broadPeak format diff --git a/docs/source/docs/callpeak.md b/docs/source/docs/callpeak.md deleted file mode 100644 index 5ff6fb6..0000000 --- a/docs/source/docs/callpeak.md +++ /dev/null @@ -1,477 +0,0 @@ -# callpeak - -## Overview -This is the main function in MACS3. It will take alignment files in -various format (please check the detail below) and call the -significantly enriched regions in the genome as 'peaks'. It can be -invoked by `macs3 callpeak` . If you type this command with `-h`, you -will see a full description of command-line options. Here we only list -the essentials. - -## Essential Commandline Options - -### Input and Output - -- `-t`/`--treatment` - - This is the only REQUIRED parameter for MACS3. The file can be in - any supported format -- see detail in the `--format` option. If you - have more than one alignment file, you can specify them as `-t A B - C`. MACS3 will pool up all these files together. - -- `-c`/`--control` - - The control, genomic input or mock IP data file. Please follow the - same direction as for `-t`/`--treatment`. - -- `-n`/`--name` - - The name string of the experiment. MACS3 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`, `SAM`, `BAM`, `BOWTIE`, `BAMPE`, or `BEDPE`. Default - is `AUTO` which will allow MACS3 to decide the format - automatically. `AUTO` is also useful when you combine different - formats of files. Note that MACS3 can't detect `BAMPE` or `BEDPE` - format with `AUTO`, and you have to implicitly specify the format - for `BAMPE` and `BEDPE`. - - Nowadays, the most common formats are `BED` or `BAM` (including - `BEDPE` and `BAMPE`). Our recommendation is to convert your data to - `BED` or `BAM` first. - - Also, MACS3 can detect and read gzipped file. For example, `.bed.gz` - file can be directly used without being uncompressed with `--format - BED`. - - Here are detailed explanation of the recommended formats: - - - `BED` - - The BED format can be found at [UCSC genome browser - website](http://genome.ucsc.edu/FAQ/FAQformat#format1). - - The essential columns in BED format input are the 1st column - `chromosome name`, the 2nd `start position`, the 3rd `end - position`, and the 6th, `strand`. - - Note that, for `BED` format, the 6th column of strand information - is required by MACS3. And please pay attention that the - coordinates in BED format are zero-based and half-open. See more - detail at [UCSC - site](http://genome.ucsc.edu/FAQ/FAQtracks#tracks1). - - - `BAM`/`SAM` - - If the format is `BAM`/`SAM`, please check the definition in - [samtools](https://samtools.github.io/hts-specs/SAMv1.pdf). If - the `BAM` file is generated for paired-end data, MACS3 will only - keep the left mate(5' end) tag. However, when format `BAMPE` is - specified, MACS3 will use the real fragments inferred from - alignment results for reads pileup. - - - `BEDPE` or `BAMPE` - - A special mode will be triggered while the format is specified as - `BAMPE` or `BEDPE`. In this way, MACS3 will process the `BAM` or - `BED` files as paired-end data. Instead of building a bimodal - distribution of plus and minus strand reads to predict fragment - size, MACS3 will use actual insert sizes of pairs of reads to - build fragment pileup. - - The `BAMPE` format is just a `BAM` format containing paired-end - alignment information, such as those from `BWA` or `BOWTIE`. - - The `BEDPE` format is a simplified and more flexible `BED` format, - which only contains the first three columns defining the - chromosome name, left and right position of the fragment from - Paired-end sequencing. Please note, this is NOT the same format - used by `bedtools`, and the `bedtools` version of `BEDPE` is - actually not in a standard `BED` format. You can use MACS3 - subcommand [`randsample`](./randsample.md) or - [`filterdup`](./filterdup.md) to convert a `BAMPE` file containing - paired-end information to a `BEDPE` format file: - - ``` - macs3 randsample -i the_BAMPE_file.bam -f BAMPE -p 100 -o the_BEDPE_file.bed - ``` - or - - ``` - macs3 filterdup -i the_BAMPE_file.bam -f BAMPE --keep-dup all -o the_BEDPE_file.bed - ``` - - -- `--outdir` - - MACS3 will save all output files into the specified folder for this - option. A new folder will be created if necessary. - -- `-B`/`--bdg` - - If this flag is on, MACS3 will store the fragment pileup, control - lambda in bedGraph files. The bedGraph files will be stored in the - current directory named `NAME_treat_pileup.bdg` for treatment data, - `NAME_control_lambda.bdg` for local lambda values from control. - -### Options controling peak calling behaviors - -- `-g`/`--gsize` - - 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 chromosomes, the actual mappable genome - size will be smaller than the original size, about 90% or 70% of the - genome size. The default *hs* ~2.9e9 is recommended for human - genome. Here are all precompiled parameters for effective genome - size from - [deeptools](https://deeptools.readthedocs.io/en/develop/content/feature/effectiveGenomeSize.html): - - * hs: 2,913,022,398 for GRCh38 - * mm: 2,652,783,500 for GRCm38 - * ce: 100,286,401 for WBcel235 - * dm: 142,573,017 for dm6 - - Please check deeptools webpage to find the appropriate effective - genome size if you want a more accurate estimation regarding - specific assembly and read length. - - Users may want to use k-mer tools to simulate mapping of Xbps long - reads to target genome, and to find the ideal effective genome - size. However, usually by taking away the simple repeats and Ns from - the total genome, one can get an approximate number of effective - genome size. A slight difference in the number won't cause a big - difference of peak calls, because this number is used to estimate a - genome-wide noise level which is usually the least significant one - compared with the *local biases* modeled by MACS3. - -- `-s`/`--tsize` - - The size of sequencing tags. If you don't specify it, MACS3 will try - to use the first 10 sequences from your input treatment file to - determine the tag size. Specifying it will override the - automatically determined tag size. - -- `-q`/`--qvalue` - - The q-value (minimum FDR) cutoff to call significant - regions. Default is 0.05. For broad marks, you can try 0.01 as the - cutoff. The q-values are calculated from p-values using the - [Benjamini-Hochberg - procedure](https://en.wikipedia.org/wiki/False_discovery_rate#Benjamini%E2%80%93Hochberg_procedure). - -- `-p`/`--pvalue` - - The p-value cutoff. If `-p` is specified, MACS3 will use p-value - instead of q-value. - -- `--min-length`, `--max-gap` - - These two options can be used to fine-tune the peak calling behavior - by specifying the minimum length of a called peak and the maximum - allowed a gap between two nearby regions to be merged. In other - words, a called peak has to be longer than `min-length`, and if the - distance between two nearby peaks is smaller than `max-gap` then - they will be merged as one. If they are not set, MACS3 will set the - DEFAULT value for `min-length` as the predicted fragment size `d`, - and the DEFAULT value for `max-gap` as the detected read - length. Note, if you set a `min-length` value smaller than the - fragment size, it may have NO effect on the result. For broad peak - calling with `--broad` option set, the DEFAULT `max-gap` for merging - nearby stronger peaks will be the same as narrow peak calling, and 4 - times of the `max-gap` will be used to merge nearby weaker (broad) - peaks. You can also use `--cutoff-analysis` option with the default - setting, and check the column `avelpeak` under different cutoff - values to decide a reasonable `min-length` value. - -- `--nolambda` - - With this flag on, MACS3 will use the background lambda as local - lambda. This means MACS3 will not consider the local bias at peak - candidate regions. It is particularly recommended while calling - peaks without control sample. - -- `--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, MACS3 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 a significant peak. - -- `--nomodel` - - While on, MACS3 will bypass building the shifting model. Please - combine the usage of `--extsize` and `--shift` to achieve the effect - you expect. - -- `--extsize` - - While `--nomodel` is set, MACS3 uses this parameter to extend reads - in 5'->3' direction to fix-sized fragments. For example, if the size - of the binding region for your transcription factor is 200 bp, and - you want to bypass the model building by MACS3, this parameter can - be set as 200. This option is only valid when `--nomodel` is set or - when MACS3 fails to build model and `--fix-bimodal` is on. - -- `--shift` - - Note, this is NOT the legacy `--shiftsize` option which is replaced - by `--extsize` from MACS version 2! You can set an arbitrary shift - in bp here to adjust the alignment positions of reads in the whole - library. Please use discretion while setting it other than the - default value (0). When `--nomodel` is set, MACS3 will use this - value to move cutting ends (5') then apply `--extsize` from 5' to 3' - direction to extend them to fragments. When this value is negative, - the cutting ends (5') will be moved toward 3'->5' direction, - otherwise 5'->3' direction. Recommended to keep it as default 0 for - ChIP-Seq datasets, or -1 * half of *EXTSIZE* together with - `--extsize` option for detecting enriched cutting loci such as - certain DNAseI-Seq datasets. Note, you can't set values other than 0 - if the format is BAMPE or BEDPE for paired-end data. The default is - 0. - - Here are some examples for combining `--shift` and `--extsize`: - - 1. To find enriched cutting sites such as some DNAse-Seq - datasets. In this case, all 5' ends of sequenced reads should be - extended in both directions to smooth the pileup signals. If the - wanted smoothing window is 200bps, then use `--nomodel --shift - -100 --extsize 200`. - - 2. For certain nucleosome-seq data, we need to pile up the centers - of nucleosomes using a half-nucleosome size for wavelet analysis - (e.g. NPS algorithm). Since the DNA wrapped on nucleosome is about - 147bps, this option can be used: `--nomodel --shift 37 --extsize - 73`. - -- `--keep-dup` - - It controls the MACS3 behavior towards duplicate tags at the exact - same location -- the same coordination and the same strand. You can - set this as `auto`, `all`, or an integer value. The `auto` option - makes MACS3 calculate the maximum tags at the exact same location - based on binomial distribution using 1e-5 as p-value cutoff; and the - `all` option keeps every tag. If an integer is given, at most this - number of tags will be kept at the same location. The default is to - keep one tag at the same location. Default: 1 - -- `--broad` - - This option, along with the `bdgbroadcall` command, facilitates - broad peak calling, producing results in the UCSC gappedPeak format - which encapsulates a nested structure of peaks. To conceptualize - 'nested' peaks, picture a gene structure housing regions analogous - to exons (strong peaks) and introns coupled with UTRs (weak - peaks). The broad peak calling process utilizes two distinct cutoffs - to discern broader, weaker peaks (`--broad-cutoff`) and narrower, - stronger peaks (`-p` or `-q`), which are subsequently nested to - provide a detailed peak landscape. Please note that, the `max-gap` - value for merging nearby weaker/broad peaks is 4 times of `max-gap` - for merging nearby stronger peaks. The later one can be controlled - by `--max-gap` option, and by default it is the average - fragment/insertion length in the PE data. DEFAULT: False - - Please note that, if you only want to call 'broader' peak and not - interested in the nested peak structure, please simply use `-p` or - `-q` with weaker cutoff instead of using `--broad` option. - -- `--broad-cutoff` - - Cutoff for the broad region. This option is not available unless - `--broad` is set. Please note that if `-p` is set, this is a p-value - cutoff, otherwise, it's a q-value cutoff. DEFAULT: 0.1 - -- `--scale-to ` - - When set to `large`, linearly scale the smaller dataset to the same - depth as the larger dataset. By default or being set as `small`, the - larger dataset will be scaled towards the smaller dataset. Beware, - to scale up small data would cause more false positives. So the - default behavior `small` is recommended. - -- `--call-summits` - - MACS3 will now reanalyze the shape of signal profile (p or q-score - depending on the cutoff setting) to deconvolve subpeaks within each - peak called from the general procedure. It's highly recommended to - detect adjacent binding events. While used, the output subpeaks of a - big peak region will have the same peak boundaries, and different - scores and peak summit positions. - -### Other options - -- `--buffer-size` - - MACS3 uses a buffer size for incrementally increasing internal array - size to store reads alignment information for each chromosome or - contig. To increase the buffer size, MACS3 can run faster but will - waste more memory if certain chromosome/contig only has very few - reads. In most cases, the default value 100000 works fine. However, - if there are a large number of chromosomes/contigs in your alignment - and reads per chromosome/contigs are few, it's recommended to - specify a smaller buffer size in order to decrease memory usage (but - it will take longer time to read alignment files). Minimum memory - requested for reading an alignment file is about # of CHROMOSOME * - BUFFER_SIZE * 8 Bytes. DEFAULT: 100000 - -- `--cutoff-analysis` - - While set, MACS3 will analyze the number or total length of peaks - that can be called by different cutoff then output a summary table - to help the user decide a better cutoff. Note, minlen and maxgap may - affect the results. DEFAULT: False - - Different with the option in `bdgpeakcall`, `callpeak` will perform - both tasks to call peaks and to generate a report for cutoff - analysis. Please check the section *Cutoff Analysis* for more - detail. - -## 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 from BED - format. When `--broad` is enabled for broad peak calling, the - pileup, p-value, q-value, and fold change in the XLS file will be - the mean value across the entire peak region, since peak summit - won't be called in broad peak calling mode. - -2. `NAME_peaks.narrowPeak` is BED6+4 format file which contains the - peak locations together with peak summit, p-value, and q-value. You - can load it to the UCSC genome browser. Definition of some specific - columns are: - - - 5th: integer score for display. It's calculated as - `int(-10*log10pvalue)` or `int(-10*log10qvalue)` depending on - whether `-p` (pvalue) or `-q` (qvalue) is used as score - cutoff. Please note that currently this value might be out of the - [0-1000] range defined in [UCSC ENCODE narrowPeak - format](https://genome.ucsc.edu/FAQ/FAQformat.html#format12). You - can let the value saturated at 1000 (i.e. p/q-value = 10^-100) by - using the following 1-liner awk: `awk -v OFS="\t" - '{$5=$5>1000?1000:$5} {print}' NAME_peaks.narrowPeak` - - 7th: fold-change at peak summit - - 8th: -log10pvalue at peak summit - - 9th: -log10qvalue at peak summit - - 10th: relative summit position to peak start - - The file can be loaded directly to the UCSC genome browser. Remove - the beginning track line if you want to analyze it by other tools. - -3. `NAME_summits.bed` is in BED format, which contains the peak - summits locations for every peak. The 5th column in this file is - the same as what is in the `narrowPeak` file. If you want to find - the motifs at the binding sites, this file is recommended. The file - can be loaded directly to the UCSC genome browser. Remove the - beginning track line if you want to analyze it by other tools. - -4. `NAME_peaks.broadPeak` is in BED6+3 format which is similar to - `narrowPeak` file, except for missing the 10th column for - annotating peak summits. This file and the `gappedPeak` file will - only be available when `--broad` is enabled. Since in the broad - peak calling mode, the peak summit won't be called, the values in - the 5th, and 7-9th columns are the mean value across all positions - in the peak region. Refer to `narrowPeak` if you want to fix the - value issue in the 5th column. - -5. `NAME_peaks.gappedPeak` is in BED12+3 format which contains both - the broad region and narrow peaks. The 5th column is the score for - showing grey levels on the UCSC browser as in `narrowPeak`. The 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 block and 12th for the start of each block. 13th: - fold-change, 14th: *-log10pvalue*, 15th: *-log10qvalue*. The file can - be loaded directly to the UCSC genome browser. Refer to - `narrowPeak` if you want to fix the value issue in the 5th column. - -6. `NAME_model.r` is an R script which you can use to produce a PDF - image of the model based on your data. Load it to R by: - - `$ Rscript 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 `NAME_treat_pileup.bdg` and `NAME_control_lambda.bdg` files are - in bedGraph format which can be imported to the UCSC genome browser - or be converted into even smaller bigWig files. The - `NAME_treat_pielup.bdg` contains the pileup signals (normalized - according to `--scale-to` option) from ChIP/treatment sample. The - `NAME_control_lambda.bdg` contains local biases estimated for each - genomic location from the control sample, or from treatment sample - when the control sample is absent. The subcommand `bdgcmp` can be - used to compare these two files and make a bedGraph file of scores - such as p-value, q-value, log-likelihood, and log fold changes. - -## Cutoff Analysis - -Since cutoff can be an arbitrary value during peak calling, there are -many approaches proposed in the community to guide the cutoff -selection such as the [IDR -approach](https://doi.org/doi:10.1214%2F11-AOAS466). In MACS3, we -provide a simple way to do the cutoff analysis. The cutoff analysis -function is provided by `--cutoff-analysis` option in `callpeak`, -`bdgpeakcall`, and `hmmratac`. Among them, the function in -`bdgpeakcall` is more flexible and can be applied on any scoring -scheme. We will sperate this function into a dedicated subcommand in -the future. - -Please note that if this `--cutoff-anlaysis` option is on, the report -will be written into a file named `NAME_cutoff_analysis.txt`. - -When the option is on, we will generate a list of possible pvalue -cutoffs to check from pscore cutoff from 0.3 to 10, with a step of -0.3. When -log10(pvalue) is 0.3, it represents an extremely loose -cutoff pvalue 0.5; and when it's 10, it represents an extremely -strigent cutoff pvalue 1e-10. Please note that the is different with -`bdgpeakcall` where users can control how the cutoff should be -calculated. - -Then for each cutoff we plan to investigate, we will check the number -of peaks that can be called, their average peak length, and their -total length. - -The report consists of four columns: - -1. score: the possible fold change cutoff value. -2. npeaks: the number of peaks under this cutoff. -3. lpeaks: the total length of all peaks. -4. avelpeak: the average length of peaks. - -While there's no universal rule to suggest the best cutoff, here are a -few suggestions: - -- You can use elbow analysis to find the cutoff that dramatically - change the trend of npeaks, lpeaks, or avelpeak. But you need to - think about how to define 'dramatical change'. -- You can use some common expectation to decide the cutoff. For - example, the number of peaks should be thousands/ or the avelpeak - should be around 500bps. Of course, it's arbitrary but the table - will give you some insight. diff --git a/docs/source/docs/callpeak.md b/docs/source/docs/callpeak.md new file mode 120000 index 0000000..b33b82a --- /dev/null +++ b/docs/source/docs/callpeak.md @@ -0,0 +1 @@ +../../../docs/callpeak.md \ No newline at end of file diff --git a/docs/source/docs/callpeakxls.md b/docs/source/docs/callpeakxls.md deleted file mode 100644 index a50fd14..0000000 --- a/docs/source/docs/callpeakxls.md +++ /dev/null @@ -1 +0,0 @@ -# `callpeak` output XLS format diff --git a/docs/source/docs/callvar.md b/docs/source/docs/callvar.md deleted file mode 100644 index f27bc86..0000000 --- a/docs/source/docs/callvar.md +++ /dev/null @@ -1,224 +0,0 @@ -# callvar - -## Overview -The `callvar` command is part of the MACS3 suite of tools and is used -to call variants (SNVs and small INDELs) in given peak regions from -the alignment BAM files. - -## Detailed Description of usage - -The `callvar` command takes in treatment and control BAM files along -with a bed file containing peak regions. The command identifies -variants in these regions using a multi-process approach, greatly -improving the speed and efficiency of variant calling. Please check -the section *Callvar Algorithm* for detail on this variant calling -algorithm. - -The `callvar` command assumes you have two types of BAM files. The -first type, what we call `TREAT`, is from DNA enrichment assay such as -ChIP-seq or ATAC-seq where the DNA fragments in the sequencing library -are enriched in certain genomics regions with potential allele biases; -the second type, called `CTRL` for control, is from genomic assay in -which the DNA enrichment is less biased in multiploid chromosomes and -more uniform across the whole genome (the later one is optional). In -order to run `callvar`, please sort (by coordinates) and index the BAM -files. - -Example: - -1. Sort the BAM file: - `$ samtools sort TREAT.bam -o TREAT_sorted.bam` - `$ samtools sort CTRL.bam -o CTRL_sorted.bam` -2. Index the BAM file: - `$ samtools index TREAT_sorted.bam` - `$ samtools index CTRL_sorted.bam` -3. Make sure .bai files are available: - `$ ls TREAT_sorted.bam.bai` - `$ ls CTRL_sorted.bam.bai` - -To call variants: - `$ macs3 callvar -b peaks.bed -t TREAT_sorted.bam -c CTRL_sorted.bam -o peaks.vcf` - -## Command Line Options - -Here is a brief overview of these options: - -### Input files Options: - -- `-b` or `--peak`: The peak regions in BED format, sorted by - coordinates. This option is required. -- `-t` or `--treatment`: The ChIP-seq/ATAC-seq treatment file in BAM - format, sorted by coordinates. Make sure the .bai file is avaiable - in the same directory. This option is required. -- `-c` or `--control`: Optional control file in BAM format, sorted by - coordinates. Make sure the .bai file is avaiable in the same - directory. - -### Output Options: -- `--outdir`: The directory for all output files to be written - to. Default: writes output files to the current working directory. -- `-o` or `--ofile`: The output VCF file name. Please check the - section *Customized fields in VCF* section for detail. -- `--verbose`: Set the verbose level of runtime messages. 0: only show - critical messages, 1: show additional warning messages, 2: show - process information, 3: show debug messages. DEFAULT: 2 - -### Variant calling Options: -- `-g` or `--gq-hetero`: The Genotype Quality score - (-10log10((L00+L11)/(L01+L00+L11))) cutoff for Heterozygous allele - type. Default is 0, or there is no cutoff on GQ. -- `-G` or `--gq-homo`: The Genotype Quality score - (-10log10((L00+L01)/(L01+L00+L11))) cutoff for Homozygous allele - (not the same as reference) type. Default is 0, or there is no - cutoff on GQ. -- `-Q`: The cutoff for the quality score. Only consider bases with - quality score greater than this value. Default is 20, which means - Q20 or 0.01 error rate. -- `-F` or `--fermi`: The option to control when to apply local - assembly through fermi-lite. By default (set as 'auto'), while - `callvar` detects any INDEL variant in a peak region, it will - utilize fermi-lite to recover the actual DNA sequences to refine the - read alignments. If set as 'on', fermi-lite will always be - invoked. It can increase specificity, however sensivity and speed - will be significantly lower. If set as 'off', fermi-lite won't be - invoked at all. If so, speed and sensitivity can be higher but - specificity will be significantly lower. -- `--fermi-overlap`: The minimal overlap for fermi to initially - assemble two reads. Must be between 1 and read length. A longer - fermiMinOverlap is needed while read length is small (e.g. 30 for - 36bp read, but 33 for 100bp read may work). Default is 30. -- `--top2alleles-mratio`: The reads for the top 2 most frequent - alleles (e.g. a ref allele and an alternative allele) at a loci - shouldn't be too few comparing to total reads mapped. The minimum - ratio is set by this optoin. Must be a float between 0.5 - and 1. Default:0.8 which means at least 80% of reads contain the top - 2 alleles. -- `--altallele-count`: The count of the alternative (non-reference) - allele at a loci shouldn't be too few. By default, we require at - least two reads support the alternative allele. Default:2 -- `--max-ar`: The maximum Allele-Ratio allowed while calculating - likelihood for allele-specific binding. If we allow higher maxAR, we - may mistakenly assign some homozygous loci as - heterozygous. Default:0.95 - -### Misc Options: -- `-m` or `--multiple-processing`: The CPU used for mutliple - processing. Please note that, assigning more CPUs does not guarantee - the process being faster. Creating too many parrallel processes need - memory operations and may negate benefit from multi - processing. Default: 1 - -## Example Usage - -Here is an example of how to use the `callvar` command: - -``` -macs3 callvar -b peaks.bed -t treatment.bam -c control.bam -o experiment1 -``` - -In this example, the program will identify variants in the -`treatment.bam` file relative to the `control.bam` file. The name of -the experiment is 'experiment1'. All tags that pass quality filters -will be stored in a BAM file. - -## `callvar` Algorithm - -![Callvar Algorithm](callvar_algorithm.jpeg) - -Functional sequencing assays which targeted at particular sequences, -such as ChIP-Seq, were thought to be unsuitable for *de novo* -variation predictions because their genome-wide sequencing coverage is -not as uniform as Whole Genome Sequencing (WGS). However, if we aim at -discovering the variations and allele usage at the targeted genomic -regions, the coverage should be much higher and sufficient. We -therefore proposed a novel method to call the variants directly at the -called peaks by MACS3. - -At each peak region, we extract the reads and assembled the DNA -sequences using [fermi-lite](https://github.com/lh3/fermi-lite), a -unitig graph based assembly algorithm developed by Heng Li. Then, we -align the unitigs (i.e., assembled short DNA sequences) to the -reference genome sequence using Smith-Waterman algorithm. Differences -between the reference sequence and the unitigs reveal possible SNVs -and INDELs. Please note that, by default, we only peform the *de novo* -assembly using fermi-lite for detecting INDELs to save time. For each -possible SNV or INDEL, we build a statistical model incorporating the -sequences and sequencing errors (base qualities) from both treatment -(ChIP) and control (genomic input) to predict the most likely genotype -using Bayesian Information Criterion (BIC) among four allele types: -homozygous loci (genotype 1/1), heterozygous loci (genotype 0/1 or -1/2) with allele bias, and heterozygous loci without allele bias. The -detailed explanation of our statistical model is as follows: we -retrieve the base quality scores $\epsilon$, which represents -sequencing errors, then we calculate the likelihoods of each of the -four types. We assume the independence of ChIP and control experiments -so that the generalized likelihood function is the product of the -likelihood functions of ChIP and control data: - -$$L(\omega,\phi,g_c,g_i:D)=L(\omega,g_c:D_c)L(\phi,g_i:D_i)$$ - -where $D_c$ and $D_i$ represent the ChIP-Seq and control (e.g., -genomic input) data observed at the position including base coverage -and base qualities. The parameter $\omega$ stands for the allele ratio -of allele A (chosen as the more abundant or stronger allele compared -with the others) from the ChIP-Seq data and $\phi$ represents the -allele ratio in the control. The parameter $g_c$ represents the actual -number of ChIPed DNA fragments containing allele A, which could differ -from the observed count $r_{c,A}$ considering that some observations -could be due to sequencing errors. The symbol $g_i$ represents the -control analogously to $g_c$. We use $r_c$ to denote the total number -of observed allele A ($r_{c,A}$) and allele B ($r_{c,B}$). We assume -the occurrence of the allele A ($g_c$) is from a Bernoulli trial from -$r_c$ with the allele ratio $\omega$. The probability of observing the -ChIP-Seq data at a certain position is as follows: - - -$$Pr(D_c|g_c) = \sum^{r_{c,A}}_{j=1}\left((1-\epsilon_j)g_c/r_c+\epsilon_j(1-g_c/r_c)\right)\sum_{j=1}^{r_{c,B}}\left((1-\epsilon_j)(1-g_c/r_c)+\epsilon_j g_c/r_c\right)$$ - -where $\epsilon_j$ represents the sequencing error of the base showing -difference with reference genome in case of mismatch (corresponding to -SNV) and insertion. In case of deletion, the sequencing errors from -the two bases on sequenced read surrounding the deletion would be -considered. We model the control data in the similar way. We assess -the likelihood functions of the 4 major type using the following -parameters: $\omega=1,\phi=1,g_c=r_{c,0},g_i=r_{i,0}$ for A/A -genotype; $\omega=0,\phi=0,g_c=0,g_i=0$ for B/B genotype, -$\omega=0.5,\phi=0.5$ and $g_c,g_i$ as free variables for A/B genotype -with unbiased binding; $\phi=0.5$ and $\omega,g_c,g_i$ as free -variables for A/B genotype with biased binding or allele usage. Next, -we apply the Bayesian Information Criterion (BIC) to select the best -type as our prediction with the minimal BIC value among the 4 -models. If the best type is either “A/B, noAS” or “A/B, AS”, we -conclude that the genotype is heterozygous (A/B). We consider two -types of data from the same assay independently: ChIP sample that can -have biased allele usage, and control sample that won’t have biased -allele usage. So that in case control is not available, such as in -ATAC-Seq assay, our model can still work. Furthermore, in case a good -quality WGS is available, it can be regarded as the control sample and -be inserted into our calculation to further increase the sensitivity. - -## Customized fields in the Output VCF file - -The result VCF file from MACS3 `callvar` will have the following -customized fields in VCF flavor: - -``` -##INFO= -##INFO= -##INFO= -##INFO= -##INFO= -##INFO= -##INFO= -##INFO= -##INFO= -##INFO= -##INFO= -##INFO= -##INFO= -##INFO= -##FORMAT= -##FORMAT= -##FORMAT= -##FORMAT= -``` diff --git a/docs/source/docs/callvar.md b/docs/source/docs/callvar.md new file mode 120000 index 0000000..8876e49 --- /dev/null +++ b/docs/source/docs/callvar.md @@ -0,0 +1 @@ +../../../docs/callvar.md \ No newline at end of file diff --git a/docs/source/docs/callvar_algorithm.jpeg b/docs/source/docs/callvar_algorithm.jpeg deleted file mode 100644 index f44a57cd2ed88c91df44dc4159786507e607c3a5..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcwPel00001 literal 163926 zcwX$fc|26_`#*jdyO1RknaWyXN{WO@vL#KWQi(~(7LzU1m{X~Qq9~G>HmOuo*2*&3 zlS;Bv#*8i5X2>|qnKR#`dc9ts_wrlb@5lG?`2O*I-P|+R+~>Zp`@Zh`TAtTAN6;bY z1r~0zb+845gaE)E{R0F{z{@7m?LI8sj#9QNWa3?i&_%+zf{c3N`fbA|3HI^dtr1B0Y}d z)*7zC0p|F~;~t&?-eJp*c>DMTS*(~Sp|4ox=Vh_NWxdlHr{mV%zJB&6L%f|&?%3mb zGQe}A*9yGlGV@5Y$iU-)-eDfgA_I>Fg_=cLtoX^?45jCraVwVn>=G7Wv0}f|&Slo5 z5btFh4A&U0S%HoY@j7a@d#mm5vFI<06~7l55fNb+vCfbb;)7eeapOkZ8Y7&MkpbGn zAT%l{%p=kuC{*(g4qLrLJwyDChxw6$md*e6I6?{!vskeLhhE41o?@Q-bFG%k{w{x) zzsuj{@A7x~yZql*{z5z6K`6wDK(P!U7z0dq`jWy(p}wT!%hnmL0Zg|zIEje-1XsUk z?VsermZg_ElYl&t;nR{gMxiYf0ZZ>!}D0!l-EUO)Szw6K(Kxc%N={e{&%L#@$01C&vEjhDw( zN0e4aY1^PlLrA-S&m~-RG{oBK zcl%q9ke~C;&(#wiu-EE0|4CnOhu{1$vL}7_xS+HYN^70)+qVOyWl`ENG{D*McOUbU zzScYb=o1pYdw%^|D81V|$ZpFo{+JU-Lu_~d?jIi*`iH!j+rEAdJATu7VZM9pf9(&Z z+SB9b`cYXhpS**t_Wr@gJ9Pi{KV&ZIW;fry0;P>ZPdNV`E3z*PRmflbMUEa1+qvi0Iz>+Udu-eJYds=YfbD=auoYMa zgroHcKmz;$zmKEEqv)?+S8M?fAO!FMya9vXEq{z~`FSM>{d5LS0%IuU4TSzVZp+WB z-oOd8o&RU+uTKNu=+CPsevSwL22nZ?a0HH_zr%ly3i@-leLz3j;`cAJd!W@5UGFip z&R_rc?SHiX)nbLVZ2#R7{>O~VW+S#$%wEh^Y^BH&5lfLxBHPi=&1f|eF%{YP zha7+P7abIB5@m_DiuQ_j68+AG{L?C(fL@fp?eD!f@;~=NLIhOX~geNZD1g>;L33 zzt{hBe}1j?$e;Ud{pXc`p8u~aet;MH?fB0ZGr$EP0k{HO2W|pX;2!W0cnahJ#Xu=g0n`Ewz$c&;=ti|?02l$- z02km12?>b{$p|S5sS06*w1xDAjD$>uEQM@@whQeRIv{jd$VVthC|rmv6eE-%lq_^p z=#J1Mp%+50gervUg_?vqg_uIaLX$#s!WiKN!b-wRg>{5+!luGj!j8gwgx!RFgoA}o z3ZD~B6uu#RSNMr=k#L1@gK(>GukeWQGzP#(W0Wz=F$Ne@j5UUUIfyxm3Bgb>@t9Q1 zUCcAgYxJC(F};{k%&dr*h@!|c5d&0%?M3#Ac!~szP(&_?+!T2zQY2C>(k#LhVT&N5 zGNS6D`l4o{4x;--eMBQfFNmg!J`gPwtwC*RK$I&cCZ;T=D`tY);sG&#u~TA~#4^Qb zVsFHn#QMah#l^){#r4H4#0laa;$h+!#M8x}h||SCiw}rH64DY_2_p$xiGvbB5@#h+ zB_2zZOMI3XlHf@$l+>0qlO#xbNk&N~N#2)yE!ikJAjy-Gm(rE8klG{VFLg%hhSW2u z8mTW*Q_|AXE2K9{?~?YDJ}rGi`nmL5X{Pk-0)+*u7FaJhv><#z;)0w7Zx(ben39o^ z(UI9Kb5JHsCQ;^*OqEQJ3?!>4Ybfg=>m>`yX2=%FewH1Vla$kzvyyX{J1LhcmoL{S zH@Z-Aq0U0|Q4k(E!=_)xW`70$TJyrUs#9pMZ$avAdMUjg#7L_gPRmLdm zC_5-0Q%+LOQ*Kk9Q(3BFrQ)p;r}9kYv&zh3wZ)qkdoPY(Ok3Q#cusYhs*P%Z>Q&WZ z)vrrLmaJN`Ye~eCtR*!|M%9$mHmP~4#jEA1b*T%huTtNweoFnG`g`^1r5a1^mL6Z4 zzO-uTsD`q}W(|LhYZ~Pm!&pVECDspn4NJ#))zS?Qpb=osJx;id8 zu{y;%-*gx2I_RF%&DH&)C!>eg3)Z`<*RoPL!ulKZ z{q!^Sn^udi-ncqw_1)F&1`7(&o&I3Xqg-~xnx!Zk#pSU>0VUXEw3PU{k=R$D6*H z>zaF;-#72GSYhE|amS+9a+&2}%iET{_~m#H{9Qb2v*u>6%?~yYS*^74w|ZhVzGcmp zkS&EE6`hIBkDa-Dw(LpT)4f-3Z}{HIeRBH_?R&Iu#$~HZ zvPBsT6_ow>L1P}sp0tClgj?n@o0uKki3Q`CP2&yJ&kRnM<$Muh2 zINlp<7JNOJ9pV`BAXF&SE%arW5(?zshwFu(4`-gRJdtq%ir5#CA1NOh6!|`CRa9Km z&`H~q*{4KKd7i2yFDIWNGo!7d?@)v&M<|t`CU_1UIBj?O;Tfqj0cSp(U2``1?2j0i znAhi)o;!W6@4Vgl+zYZ7LN2t&Zi=N|6uIbk@nhV&xb!$A-YfoH!kUEC1o)EYrFWOt zUcPZzka#rlW73ACtSe$yg08e(#b14xET4Qbxi7^jrRdtSYw_29TqjH(34M3 zw?2LO%;4D_nldfnIq*FE`S%xxU$o^p=2hmK=07XYF1S^wSQuXYeGk;)V?kMeoJ6fCC_O^AjA8POI@ap*1d90Jub)t*cefo>&m-w#>zoz!6 z_uOTyWYBsy^p-KVGT*bDS>1h}eIxy${qVrKL7BnSA?(njZ${rrhi!*HeRusnFmil^ zH+o@Ae(ct`-gv>p=85<0{pESr0LUBw07W!ElXCr)|NSgN zzj9XK*Q1I52l`iz__J&PfM+Ov-!+P&n|1(rejiQ0Q2ug<0AQyK0PNWa2(MfBXZ>A% z<(2bA49x>>@8BN^JOcci@+;>A{#y4xe*^Peje&pu7Q6xEB`|IxEf}E{fUvv}MqWrz z4Peo=iwgZLe@q}Gj1dtP6PJ*bl14ieE(C;yFc@JGjHu}RjRT=*^g19SFRHM7t(BPK zE)Ve)!AeGFuHKQ*-14Gg(e5U;*197hXCh({7~SynF9{_Jf>< zj~?gc7Zes1zkKz&vZ}hKw(f2HyU)!nt!?ccon1^;U;n`1(6{05oXM#l)7%+oc5YrS zApj%vNBOsM$)j=!i-=%E#OLJ_5{{VfATJ`ie65&*)h=<5V8sj4 z9{9Wd=T-3O@4fqPtDx!cz58#g;PZd8cjZp}Lb^X)gi_7OqhF@`V>L#T>nab1r8$sF zmzR{_ONxtjP~i3jSCeKQVn$Z!&z|5X3V`0z0wAxrj&^#^WlUZGi0ZJPP9&5YlkH9= zDMh9ZI=SwA!Lz8PEr02_OSJI)uACIL)n13w)4u>XCER&8=rQj-N|Y zXwaPtuMC@#ZPZs1;_uvLqXhg_!R3rR6<8sMyOd9-2N1fZSlBT)rYh|4_#3Da?qv4P ztCjSm$aOZjKHs~rdKWdb(H}rceQA|)(1lz?f++yDzMc{QQU;y^AVp6AT=b{+CSrd$ z((vrNZTMNE)A)#Qe|P>r*;#*JqGKJ`jGsmKz(a-tAgNp&d4F?t7M9(@5L-QMn|G=q zWAw|1-1{N;^w8CLVK%qrz6;0e-Tudl_@Lh5i2%qKuOM}+AyUmeEu@iJV4I@zifIsP z!>Q`&%x>Xk^n7fSz9;~q0=0I7Pqxx-ga54bx8=Uh>9b@0o$CLKf&5?EcUF_TjUR_U zO7BoXWTo+90>JyJ7*RG7bcRGNi!BO@i%ojG`(OV!F=@$5_fEONycmv10Z8`4e;Wws z81&$1)J1Rvhf&ibh0eB>@-c1dKqS4-ZjP7`u11=^sd9D<%QuS<070XguGMA^Q#mfy zo3Z6eF1@XESj|}gh=j!}T_9dC2{8t1dzQCOGG;eAgVpQtY}<)B?Fb^YD*y{;Y{r)S zaAAtW*7E~`1i)RFZ~<^$`Go+eFQ9W|@UVO?66e;4C@rZI06IIx$EO!THUeN_vjC`2 z6#(C^5zy{p^WCq3)y4vVZ41t6D+&On)e~^i8=#Cg5zk>cGB{X14T&>mKs)^f0Gwe5 zTf3n1p_+cz0got|wWGX0iI4LaL8z--*oyLAjPg#N=Pg_KdnrU%J_(6ar$akOh(Fie z(zq6E6abIulD`g0j<28!vTwK1XE!AMG^r}oq%II)z4bK22|YU62Hb?)6x1|W!{^Kj zfawu-+OLybBLJF~r=g}N6M&kYAA=)9`Z<>pI#gVCb#@VC;#0z(7vo_|wGm0)Qg} z!tyD|#UE5uA`pI#MwTb@ivgQ7Qs&(NNdTlO3Gt}h48rVp`V7j<{izE_0H8CBqWuDp znk7_N*#$ioWdYzdA*vgTETMc{lXKzefJyPmcz^eG*Rf+EQE6$4@?432-*+d{ysq<4 z?-a68`md_Ep!q+CH2SmO`FZG?MHitfz7JcXpV5Blub~LG-6%tzqUm|Vun;?Y&Mz5c zfWE2gs$bxFi{_?yZph~>fS(8+r7uRBsR{(x0meRPh~(&tB(n&wMC7RxAM~|$@yf_* z=w`U{GfE@a3EU$k{M(47jsQr&FP%O>4rbMRIVEqMOPVlP{o>O76K&(S?F7K;{)lbB z5FR~e$ROuUQl}?3ri7nnuGkAMArm>=6hHpGr+${=&0s;swxW(?(#wWRl<}=(yDJz9 zJKOURs+dvqBMC_z&#>JoRm$$mT8&M~jwGhzm};O$!hz=SP33XHB55nuP9B~}JYYG) zgWym6(|BLTY2tGicoCi3&XyZ1W;x;CESX3oJCIm1(tF#z9qn<(B%|+4g^m5yhcAvF zsgB|gqQ{yQKA8hAa^$A+uj2#dAZ>b5`AVdYC_`roHIXQ|;hWLz7yCYs88@+_H>=Us z?IPq;xVfUf#jQ~&sE8c+lN$0_%xU&MFP&SP{Q#;3})@}OgNnnpBWFPD%*n7l zB_F`I+Ns=dqF9h^_}4Ab)2%Sa_vV(HK|;JWGS2pF+GWrOD<80=HS@!C4Ts*cp{H)h zenw%NJK@Kkl&s`Uqr85XH(lYe)nACKi>j4nTS+$$)Sb*{;9g2l7RMok~q zqP~pkLrhsIfdELvzEFXcb-5tF5Hb0V#x-M&g`Bi1@ZxKmH14e|4Ng%SKO@3`T3>Eo zmyW}{KXgCq0FA<@gT1#I;`H83qSR_jU9ww#%XBV%q5oCi*RtpDRB+22_q3pDRHLkjbY&6i90?L%B2QJkHs2@r;M-bz zTTh;I-GF2M1gCvS030B$1S{;<6XUbY`8UlMd85i-Rh-1MEE53I!XNR%kt)o)jn1?k z3&X2+L|>hFA`Tav;Ryg0v9&W;QLY7rZjk*O&at|Oun@ z{V31kL^L2q3{u87YJxouI&-MQaym*caHKvrZWtV8P)(P^t=Vo?LH$8ZuCZ|>alo0w-mRdLgl&>8;0!C*T3;V$FH<({K%AKI+p^@y9hSUaqE58lE@{k(tU8M+61yqMJ(-((-I zF8~%dJ|l0T7n_v3Rek^DYUk%In!_)#TbL)yW{GI!5ZE1=9w@d~X*xYD>=#=2T#dsBn< z*P(Rf`ZZUh@}kOpzNkk{&!I?Bto$H(V{sY(@v-uS{>4j%&Ur#fD|}yH|56@ZGY~t0 zG@2)a4R)y(G!j&R0h}c69xGlnSmB0fBb`%8g^}XisI!C%Swiw^Q9}hyj~AoB;9U)a$7ZdaM0$07Iv&OR`~T2K%bq0NT3$0 zE6MW{0G_>5v%AjKMV}Y zmy>N#v(?~M?d1eM%Q`kTGYk5kb?kWR^tFz^u|_3>n2vu@o6mDW-hk{wd>y$iUPYD$ z6p@WI-;``JFlH=ps}H@eJ$_z9{-F6$2U#utJ3BPHZT?CLqI_gbUcz-WBOgO>e2r^D z{2|zyUx4=_og*$xs!WQfD#H3qhLT;N_Q>$f3$y^g6GctSulGl0r<~MHy{tn}Q?Ym~ zejD#Q@lP}}UvOrS1M*ENXKyu#0{QJI)`0_VKfi z^3%&@ApyXhg8X>VWRsRc#^tQ_t<#xACim%v8#B8>9|UpSRI;fQyxZMX*I&On9s8Pq zgUnygBz2nf=2SLziF5N&{}E0$g_@W=tP(^aoI6ltUIXeETZxa1 z(77y)fK%^e= zHn@WowiEc?jLQ!X>c%}qof~${rR6E5b}shTRnYrB#V4IB0I2VI__;=d(0I5@0K`O* zakt@(&?BA?c{SVS^>F!8Hlx;JU&Hq2v3#4t0%wA{-;xv6zE=gn8~uJ-S9hfVkSSM3 zRir{=W%JXpr+90QOEoD*CAD0nJa7{~BGK@E1_-MQJP{|8k$*O=g>E%R8pxYIs43 zUjH=w5cA+}ydH*~!9}6ewPB=|$`yiQ1i*tIw68Z|9X^_}448p0a`>ky%LKr1nf}aC z)MeC_<6shG#g=|E32%eGvfOYL2(~z~FJ)JoVe-4L8qSkCv-WC@Uf%<*L5e(Q$_GZF z?D=38v9r1EBsS4tb*93=4@W5IL;gF!FBe! z1Dp-%0eu!BU5+C%vaSz5Bj0S?6$yax z25ri?3v=lV{Dh9W`lH>bKVE%Ji1+FrP(B&tc~H6-!gLSZg*L1z-j_FWS+jEHW?A`V zojWomU$qO0Pn8xYn@-` z*AHllm=$7s+!ynCJ{@2ayYPMORY{$pz0^1X;7d#>KHE^0weWe`uCfeO&~Pp58AD!%J72In+KjmRi`dvDz0IsVP zn-6iqQO9sA;{~xJgUs?*2FhNSjipVAvT3b zk8$F$kY3XH^^C<30a;k4$+K*%@(b7Q@&}JLm!ihDC3WQq3HTG4@zp!|G@ib+yIs$3 z8WyL#1=%}kU9O0vBPtrZC2c$V!(hq-@^*+CoDCZkLD#0btL}X}r8zbJ>=V}5wWb_5 zO?*8?9>$O441=R+UMM=qzg?~usoytIMOX1d01l&?bnf*6_hp|7Y0}?wwy~eleDte= zCJC0gtBF3m)hYK=RJD^n%=RT3C*yBn=1NodGcRXfEqWaO@aee6>&rfc-dC|uDm{UL zhCNrXi@;6h;HvQ*^uDo~Dym8q3wPdKw=HEq6v1uQNQ+XYhHIso$ekSA6dP~aok22M zTZTV5ZH-7cpi9$(x;dd$Kkr>+pi#&sHuiRNsStDIgDXp;n6>|zF7<7oRd@a8!xvaB zrBu2-JZ%29`tr;!->e5cPDLZqE|6xb8>H9<&S5ef<`0(G~wO~;u#M`SvpvRqQ!bg@Zn>fxUf(>%x*27@K0Ne9me;{}%G3v*c}Ck>Y$odL z$c?yu+7Wg!tVBShv`_IIVRuxPD5OVYAzO*WOp3WV6L0v8ykWhn!L*BndGY1`mlyUF zr*15L<=l`+T#s$IDhhzR&4RLX{JDM){qpTXNw}3-PGxG7tU`ULntz?%o6XRmEJiAb zdAg(5c|v4Mc2)+*q>l(|UG@xk_~BvwZQr7kCvu_(H!6H_>%nK_9l%G0>Rv~6Jz_?a zc7Q{NRTR1X{47f$N;6fC?n{({Z1G9N{1@zjmUa6LTI*s9-SBSoyds4tF_u1cUBhb! zQxwS6^9nliHp`8~$0NRYpGIh99jugM&o4nFDIe)Y^cYw=C(@OB_S3WVWl{v``cno- zT7RcQRKL4JsBW4Tb(L269(Q-*Ovut3v^Yy?G}j~+wbwAZqF}WE4|e0WIPwwlCX=eC zC%#YEakiV0cOP3<_prx7IYYZn4x2WJVpO=~lQ=j0XSlcpviH!t#Yi2Y+|?XHEkW*f z3Fmy5-JQrC6^ieZr>d94t?j%Yd}}t#HD%)t&erLBf~(=-phlv##3nOwL06*dgdGEhY2EinWtXClSXQgg^)aXaH9IG zN()RN6Uk{e2XAjJPA;WRHY;EaO;8tSe|>JzKir}JkE)QMxqBf@ zAGXVyb*_A0Y%kv^(6(QWj!QwFDWQ=r`RzVa`tZGY01o7rHNxiW5UEYN`N zwUfiApI&?2mLWQt`ZlUltzI>3i^Dt2rMB{7-WtjWcU{OWhrF=8Tq81QrsAffEqBSH z+LV9|na9`yAlG-y9lvrxRG-A!o72Q4k@=gUDCSbvx*q+Pu1@;a`7c{=K0)N%Q+tf; zhrY!-f#$^gc36ejS6Am2P{B}?8>O={h-Vn`yc<@Tdw*E~yyo|3xt*M;B|?Vov>ftIXeGOWYYpK~aVS%Lv~#Z2h{pNwjOZm{ zS0twbgSi(6;>_vVsE_?(^Wx=606CZYv0M{2hC(@DMKN8DqVH=4#)Vl}2_G8ndio^d zM82GZ=C#F)Nm{=emx;QqL8O(sX#OS$Vg_Ah>%N&wtHfT!%9)2^&yhVtZWbuk-){$nJAa}?p;sZq!K8(sX22)-@aU7Q&d^Du`I5x&*DMC`&<{-_oSnTHN@xXo7 zQ6lp7>UjjNr_!rr{JKqQGpF!ThjOa%-L<5y7({A44?{i(NwVC0wzI`+mf~tm+Ph4; zvLtkp)m#WGCMEji9kicTnv-X#WyG&2+Wk%+Yd|CZM}8(4K)--ps9aZ3uJQuP?2{3j zurK69kEf6f_ysAIM=rldTrzkCd& zu2Ym$RPYDwYb!OT36S`rNgr5=he+9=!Bd3824lo8l&YQLsIkPW-GcD4kaN|E2&{KN zcm1}c9>Tzffx5J<*b?pjFm+)!yei(4*4@m_=cK{PihbpUJZng;)>0{>0x#j!;tdf= zpiYSZP*mGkFfl7`MM9E-wLjy>@5ft`M>QUt#^3R!_udi!&y^H<98@aggvQIul6Fxo z)tfskzPNI?gTY9i#Y9XC37oh!*MiOW866AAjx4F#R}Qd0?BSDixoR9r9WX$!m{g=@*vM zr^c2?DYWk@;F<5<@31-!O;7L7hSAa=By_})yAy^qj6vyG2p5?}gds#>`cl*B6N zS-|;tCuexW$-R?AH`gBV;zTDE@4|w-IzJD!*~#x3hpu{j!_4jB%!~%`wBdd14d>Y< zEMgT_Isj2+zrO4HdN22CK(J4aR`A85gB4mwO&8j3ICe=WQU4P~l`IJ@XK(f=vLBeM z-hu2#B7{eFA=S-?U+}yeqjY)Z!Lvz7cYk|-EUcJ|NC^NIv0Ib-kV72xoFy zAi@?jYrkNX9hul%-9_dewbx8u7wpY@IljVV4KiV*IK}^XotLv&l!Bu9iv0p0Ad|pd z$G=$W%+ak-8{`xf9AOWgGw@IwHzZr-DvI8Y$Itq5$jzhUE7s3>5F1ICTj{;GLH5C? zD$KX|04SWNd7$pu_Z(#Zp~&X_#2cJ)0$L8i0Q$$m^-p$ zoVc!jU14(J=5)5iH)DL;Jw$T;p^~USKOXG8SH3urbh=#2zSK@hbb`G0@%f_GvFAoZ zZ*^zt>*l&cwJ6h5DzJPbvO|&EjAH!O$KbacBOGT$@_+yk%a3fRaM$`o_oa0=RJ)v% z&B<|EI-PW$yzZez*%u?QxhFeNcbtKwccR$>NsR6X_Flfa8jBSGfr~Z2?6q9)pD#zfdUbUEPTGZmDa#u zRNu=u^NWE@pUG01ku&U>O*x1(p?ekVGIokR)2C8R6ee4yFppl9t2kirBQpSnhQ;@s zIhHT{cx6t;)O>r*MAICHt(GJnc0_t~v)q`s*Anf7+s>%W2C;Bn5UNN_)0#un%cQAa@9DCi(kSR&S>VFp};Z; zwQMf6k@so?>9*WBB_8qodCO-n9<|*97g&kNQW@p2r7MvIX-t!ZA)O?nOy_+k; zHS!2Y;S}vF|8^Ws`w~5c_mGuPPg*w-4>#tc$xSxsyY{Io<Kbf==4eyh5=$_0cq^XmO6taNZ?cO=8`&{j9d_*b zrxZgtswvzpU}sA8jRx@wrBQf7`9+D{jjbgMJ{SX`9X4 z9NApwG8Zu>$1$nwk%#VR#Z+f0#_md-af-}A^Ld$^u6rq?SL}9@{Ci=!FN1By7?A?e#M%E=@gS_mt87s}4qTy&nfP z4xO?*F83|#VZC3#>NxYaPdNNqZ(bohOKG99chVp|d_2DQ-fJ4H*p5h+F+p+vgVfVx z6Y)6MIl6CS(C(FF0bpo9X7C|D$)G>c_jIz804ODAUQAD!de@A|ZsgzVMKv|DgYroO z$EKY(rp3AApfs>IaD`f9LB(Ca6RF3$8njW3p4*yN-_Or!NNY%4-k1(+96F8dIQgw> z_xGgS>;mvu*ko5AwR9!_D<3@AN$V?Sy1?oNJnQdNA=F!y>DNg1$|=J((Aql(pjexB zvOc#vX~Bqc=%KFe`tprl@x2a;UveBYc>>@&Lg+cwSOG%%I9Ms6l2Je%W!#~3_DHc8 z#a7X~0vt_VtFrrxbDW#E?rZvzT9Q0SSdE|CZWKjvnR_4r4h-7<5aMrdBG$>EAxXIb zk)ri6I{Rv|>^<1Ch%kE%Khs?E*<}-+%I*LLCjMrI2hx?@%>P^+2TDuCpHl+S{Jt z1|t-|y3Qs`jP>%nXIJ8GQtYNIVbXqTp*XCb&a;c$)K^^NKoQ4Px#C1%z4rS}&Q*x+ z%Q6jZ4!%=&!;Ip7i{d%sVEBQ3X(Jprqle+`qg4{oeScTyz6o{2DmmaVi+%v~!C%(U z;NPbRLHgV?>}y6=4q_BzRAYIPs01?yyYh&kSsmS zwDJ(Ql7DqH=hUW&cuV=SUV(|p0VnLgBj;34HiQ2rBo4aN64}1Q(Sbg^%J-f%r4XIv z8dZ3zbHZ!ui^59P`%`NVp{HY2$3wH~CQl9?0lGekPopV?Od4-F+T_BHK;({r&={88 z3Fcw>i$HO(cm8f|V*BKX09Y7|pmz0RKTHq+r#BRU)#_kAp0A8oM4hM1QvlpW{Fh+^ zI9Pdtdyk(^4nSdW4%EyfiIcaoYiW<&zg@kryzgXL!PGke;2$$?r(VKf(@_5ZhzDqB z2)x5!AG3P{cF?&7&>7xNh{(E7_Ou5w*^$VVR?FSA|Mrd9VGXTF0l>H|_aO<=se{#b z@qCcVBX!K;>VPyTo6QnZ$9A49tEQ6jcTm5XFv_mtM{boLBTh9o&?XwVqNuVwrqqJ$ zT?}af;74h+)U$10mh`@y-IHC^?vf|YB_o`ikV@avG98xjDk1;B6)oJSjL{&{Cn>=i_1`oxD}yEbu$IO}_^)BK#Z zxtUC=G_l^#q96vLOzZoZzu{9HH==S-W32A*)Ocv-@GeXMcoKN%p$UNIlP=>QDDsq! zb9ShLH}fx}NA^&zT8?j$O&R}m6kG|i_kiM&crFU7&(0tX^gQC2+7f?Iy6!?aexXiM zB;%XO+#6ny=5_o)4jk1DXKFR3!Qs;vUh(w63KQ@!ty`srT3|BT&ibmtB-Gd=SpPJm z$mQV@#tfM+9Tn>B*r4*~@m;PLdlT*V4kUM6k_ge{u?WTU-Wk#%jG{1KRGHl#Yb*dR z8TogaTr^h=A(i4;1i3>AOI-=q<4KeKYa28=%?mzyHa1KunYTA$^K;;ZLtFx+n*&?7 zP?iU{>p{7!#(1+ubr%X5@=)V09_4;mNx@|QSxNI31DxWS*!OAugr4Bd*fXe&Vc|tI zL`p_wEQN>vMlpe2MRS}{46=B7BvaRgXLlC=+}t?!qz#s9n5|v*^uy3~`unt*U9&{p z^g$9WuG|=Whn|yPBhRcm9?3$K!HRN5KA{SyPR2p8p`1-D(nTC1^Zg1ja`#f_eT7+{ zYkO2N{CHE#nt?i!Va*hoZn#@qLHnfcJbXBh&$COg6pkF>o@gm`U`;n!E{o(Nn%~#i zMR;>x7CNIkaTt8DxQ5PCu+yUc_5;1^-Ae)DvXC$>sV`*tw zGtT_}%gLY>Sk2jxy49pcpG)ybFs#c9K|8zBk2W-RDsr>=_bgX`LroKw=GnOU9<;s3 z)Q^^Jt93M;4vTr0wQ;O(%IoFiAa83qF-;|dN5?gE5}SzdB4=i7HTDvny@PNGl%y>3 za}J@ZdFR2UT%4y4GQH6cYEbj&M z(ii%piO#36rQlnKAoGjnFSL&8(|e+hIAd?Vn*E01n4rVh2eFVoq0X8{X$OVY6Xd_Q z6=|$aZrl!eW<#RWZc>2?3b9^uExTr4d^tvLz|Jw|{4}6G+B0-ZAK=-0NZkol)B;>} z6dgqYms~W|QCNPVfbWmu+C}WJEX|UFhl?6`?%9t<%H@X|MKM= zO<0p1E&$FLk60WDSUHCK5$&LxxRsu`Nw4^2{6L==PJd@`cgVMqDF75Ytb&J<^!F7et_^6D@2@8r)S~XxH@uO6NY$xn_?DN!;J`n5cuFb(Fkx3lofT&U{R?;H3x`;<^(P?06Mqj+a)yora zG;YCh#Owm#pC6=M=e;7Hi(pLV@u~a_5;B^%Q~Vt4G!L`!y%}@~OYO)crd@miRc%8q z^YV@f`_h0wqptnsO+M?o>j$Vs!aMC_#pC+~0Ly>|X;1Kl%}=4WkU>PY(@;#d2&~Yg z_oh>fI2*EA0zes-XQ$qK>_4;HopI>H;l!yg+Yzs1%af%^^-m_CP#mm~i(J%=p|cNB znVYexc#d*AtT2O|(Xc=b*@-3qbkM9yJ`k+Hf#2l&7_d^80GRZq;`68 zU79Yp=LMRS2b3luw*v8@TGZ*!1Vj9spSD=+G#U&<3g;gkp^8E5Zamb4NRxdE!3zRF zY5f6(wyyfloX_EoF>f6mlV*LiZm{$(fgu~U%-g@CveUWkpTWZdpmWn9sGbza&t*Ne z>T5FByjNQ?&>GISTif|2u9Xc&>6qCj9U{Ug3PL3Hc}l2Irlo7u@j~Pc$xz~cDR+pv zS3flOOTR~5mfg5Bb$TDml%I>j|1(}_*M0cjoSW1!x9AM|Sz^A^*SgqJSv0A$YlRQg zaW6bDn@DW$PgEJsOtx#=wxF>b-qFJ1| z)kCUL-wbu~vnjo`X0!x#neD@c^ABlm;AO$y%zOxgNL}TKBT~D|alBoe_H$z}3I-*Z z&sTCii?h{L9v%yC7yowrN9U_J5kqD!S-g}q0pmgn>gOQJi-juIp z>%0=bSh|j-77$h%pbwoYmE}k-%uLrfJmAtyjhm)IE9kX^%fx(q4K)T^q%wxdh5D-T zN}A8@!=)_@m+Ct-;q#9sq6-|}FeyR&ki2MJDE6kfn%4WvlO|~9Y-+-V(1>b8M7og0 zd=wTJS}OTceWR@p7I8A4M|z?`Eh&~~o(lT%+xa21r+B~lH%}Wc!=g-DXKpn%k5sv_ zT zN5@o~WnJyHaD5}c-xb;+V^-Vk)bixnQ%&WoT|Ks%llNZ-#F5|jPZ6*sy*W1QPz24C znn526A8r(s!4_v7b64e{3ZYe!*S7v48P7{n_M1r~9A~?A*F~wM@m^&off>3C0dT}3 ztLZjaVGH)&Enfr?I4*rEV>Y<1h~C#h{SNdt9j^LggG z``%Ylrrz;dgy!abi#2NIARSgp;s(Ef#IXr-FiI~` z=#;u_>5J!1$RDdqQ>T|)PbI9??{9>(+eh0uecbyfr;FsHsOb>oBO7bV7jbkea~ma` zIO4VLSfna>YER20`O$*sQ}`BF+e9+m1TtfOYM+i_w{zS1R}iB}HCI#(Qdkie$W}~- zl(qK9;)fmnsqM;hfu;77=4nCdv-0O`qbC=xxzBxam3N9##prk)8z){Xhh{HFhmRjP z)YFrBvSF0V_9t?_O*#zD`Wk`*iD27_4* zlBL0^d3Gf+r7qX4K0-^eqaj#t5&?1P_ZRnU55jtTfz|k~#zg#4T4MP^Xo!U*yjvTw!7qLHAR>+Tlw7TK*`F(q*+T`pA!KVrF~)Fqll>T2X3WD_bK<&qEsD2Z8y ze{=F~?J=@d@MBk<^zgyx#ufeb1NJ-G-fRJ_H)EB^ThJ+vIQG%Ha=2mq96ZxBz!nm^ z+cS*q%zZG#BaWp~y{62W$1NL@=x5Z+(A(q<+W^x^X|cf0P%~OA8_r1;CE9cke0Dv}^s>uJFIc&Ri4XVdmfRpNG&psa;c5 z^ykH+XZpY{PuKlJFF&nLH*VN~=gdBK!>;-$OP~B4u{l~Xn5K$uh%M!9x#qm<^R&R) zLbpFeaMWsNA~e=;3i}xx&W4g)mTS^F{>uw*@x6;U5n~(dU?poriqVVj=&DwuqOmbQ z-WA@$DHnr+$PRe;% z3gfCvsCf`rY35z~h}<#z{kx@dwsoB&n^esxrj7}THOA2k zE<7}Mdsr&~C{_0ONr@NM{I^f(QDbxu-r3Xmpd<07p8M~)Jz3Y9S_j%Un^4uKA8qpL1#+ze5F~o}FO2TB!g(ZsJhj);w?PfNY z-etqbsG(A51>g>TWmmbXkmdlMW=DT)%$X~(Xg}MWeWR(NrZ9w<#a&NH1Sfv!{WQMj zFnfJVE1u`^ud^^)WS0CKR)aHFroPYgPqORe+4KcULRsMTLa)b7G>*BbV6NxN{oRo@ zF%Ge-G*7GO(0&-Fe%XtY!!*VbygQaL8%Y{~JG-q{fRc^j%97`j22mJl!qmBJ+fb^W z-tH>?0FgWt-;!OFgc=~5+vD_&qz3)WYuCa%FeDzG8Kw`#zUU+qLn!K~DOtVc!e+h5 zmd_k%;&VpL=KMTTA9kv5)A}a|M-?5+fw~=}kLi^p#0Wr_kOaI6UK_ET^qP3bW&yMi z@(RjmA3kGqQu=k$c9Hn_IQG?-T&w>k+W1NYrSq4g8_>kT4onBfc%7mkSWOHJ`D8LI zB}?xI3oTk9N6DP0MJ+7bVufO)AbQj?RfD_UmD=X+Kh_lod=E_ZQ|r>SXCd$K=*MMu z2$OM1k?l)ff}U60x7q!a4vOMSDVjtLdO%K=iS&F6Ppx_(cI-&Lp5O-SF3ch6p%v%^ z9FJ-eu?1cd3vnKIwC$+$F%m9Rx2`1VGMAmAZ)u~ zqhbH-bVrQ`79U{lOfjdJug%3qYsN|EdAA{WH;Ak~R1B+#WkXp)a2c`%P(^Twvze`N zWuJUs%ABgl>+6~0hnkA=i?Ty&qSpa_JxW6Ap0H0iWe2|+;oV=4n{f*uh$ZD%3?^T9zrvA(-_|HItiCw*-5&V`as4F!0szvD!Kf;;>y zVkG22`TCJtsU$3SaFlEk)ed1clKT~6t=#7?*;Z~cgJVI9)4i<3FBvs6+nZFS!??-9 zXEr2-ob?JQfLS*US)#Ct-(1~%Y;C1paT|k9{R?1h$EBy=zb<3_m%^x(J7b?aNs5<{ zJ8v0Q>-s(Pu6|;4dH-9lc&p>yw?u1u5t2MMNZhF(9 z>omV@Ao!erPe}l*eq~N__3iFygJYjJFOmJEjcZktKbx`>9`l@y<$o&ohi)YV~W4c5aNr zni58FST9hta$mSY7sr{HnIR?%L7pO)JR56iF0n2tUixoWeYrp#M_a!STyN61tco_IMxc%hW;*6ls>6MW`yPVxx}) zaW1zHvGrn%Lgy7ZJ;CWiNM@7ZBW;qHKi^95u=I{BGM#3f}SUD9Z!@#XfVqz zcQ2sEE5f@@Qaqqfa(lTeV;C75#zw4rO7wH_2F|572)Sk8wR-Fmq;CR)xJzEUnoz|~ zM=CrIe{=CZ9$4JeRB@Mb#_ZD@ZnxrvCwJ6vnZJVnZA?i>`?ywRsznlyF7^g*gKypM z!{uC1&t`8X<8)ooSq#WRLP0|Q4?e0MAL5AXqOE~@)FI4cx~>O&L%oE(hu&BW&&Tz3 zVkKJ(^tQOuf_Er`B4V$eCw3&S(An4EE8y1nxcSN-8|G8D95lX4j5X?{G&{@rKB*d?$oC% zFxtJI3krURJ;2Al;JNa>A^uHUMlcdC-^e(RILLowerdrhB~F!vropzBYbQJ}Tsf`T zR(~#5p=F<&AF;`>#CeJ{v-$4vsFY8_{c>%Jgc}W<19cq5yew9$`=?g5%V|@guC*_t zAQWZ21-Wrb!W3PuBn+LyKH%Q`u?m;Lb9)&-=D~U4(0R&De)iRuLUwCb)%ISgG(~W( z?&oC55B(;s;zq;RPh(?|O2T@{n8`!^`_nW56)_6Cf$3o#6gd?kRiser9wBE`%WZ)& zCE@39W-rYSl5w)=Bi~1@*?$DE_^2f0-k%okC4k!sKy>jB{Yt`XVwuI)W9actXaTm$ zPRt+9dVHCAHl`n|k%GCH7$ZZ?0dIqOlgx((+i=_Hp+0rkc66_VHU!Fd@zL*LyUJQm zAIzw3Ro%))+T)^)HnBN3(YN!>7QVFxGbWewbp!kqhIKpiRj)Hh9s<(rezNMDf`XDz z`?q;-?MKg#j~Jg=yw5OU*P!x)jw;^b3WK7CwL)1|kT+D54Ve?Y_})q(JvQl z?9Qk0_r7p$A2{Ccx6tYJ$XHM7$~BB2UR)rnd!W%tO$_SN9fX{a99Fo&wvtGPy3MAh zQFez5ABNb`d@tOxHv~QFHhQXzIbmvAatgy9b}FZ;W0j=0U9Cv1WO|IE-nV*-v7E7EtcavWwakA3owSc+`6go|AMdRy2>X3tN$g)iw@oMyQU_yy}pxO2VZ}QqZ)P z^-E0a6Plmt9w1*2OOzvC`{iwYl95{S$iVCnkI$w?S0Z#Ppt7BXO1kev{0 zP1&FN=~tqeczp4_WK-mBeaT`&D!hZ(+AczwOMLC#ZwD*aO@a~jDed4>YX8!}sBfM! z+OlzjttlM_=YYb_`&hJ}-lKaqd80c>y~8gDsaauMT3eR%!5`lG6)cmI-Vbk*{vz3T zUlf^Sjn84)xi!OTTzcJ7!<4vw-&`YE8U!CSc~i zxSmJ?UgMD#GS$Z>K*AG!0F38`vKW?gu-4EU#q~+zhGDG95FBs7Sy>!=yg|ku1Oupd zNejqEh|kQ3(plz5*X79L$MhgfL(U>0<>XD0;8!V`o+Wx?$<35buPsOR()ZCGnjkKx zQ(fzg9o08`t;$P0rszrWda5LR+PLk43>yI^kMr^5;6#1PU(PrW`-lN91u?3}s$iU_ zxGM?X-UU(l_3LYYTikjwI8yGSAk{>k*|^)k_h(QAvL2_l-ejyx$I7XT5~aOtsYF6f z33x$|Xehsjxb19sddxvx_Y;)(i?nas_{eGgr})tBy!iTSoLL zXOVabK-*BXGgn)1Fuyrxpb+MwnD#Z~o zH`)AQgB$l!26L>lrFnC1-d7vWl*bxdX2t&oO#h<=R5t%@!XCQ}35uruhj&WS4JngG1zBjopg zs#Gi`3uO5nF$YzE3NwA{_ zYK*tHgINa{*ys=|SRvH6R#7%C!ojeZt$t>DC+kOF8pi01b!hJIT6b@flZwZqz;rJ( z!?Dm`@+Rts(v$?q`DTWaa9}DPQ@>Csr=prxWl|+!e3au8t|Y|nqbQQE*}7l`#qvvF z9ShyBB)o6`9uN-l^K=x;l!OWvs{WSK5x7_9>Ac)zZ}@2>oV4dY6}!4$qp(Zx{2RGRP?#*{eS905>CZI6}CQKUm& z`!{o1gQ}<+*|ghiO+TV$zw;~BB_H*|)>_?t>_OlgXW&Q#;SUpEf7CsH+J6}`*MC;~ z$5kuhNSEg;GRW3oscVsk{5NY*Vv&d`KGS6W<`+YHv6-fK=qU7w9A2@IzR zr@sI(WF-MUI=lwYcmXpCe`fi(5AQlOKZhUD=2Wh*sEjK}i@PmJy*-_+(f(cyr=Kby zGUqA)PmZ=nVs}819X7YsX{1f>UDpuqP&>HpF?bnZ}?zx*Ut55gy_ zfeZXdzDkij%qnZ9s-A;?B}41ArV4I2m$_co!+X(o^}{!qxMd>vPxv%C43-8e3Bp%Q za|Qs@h7#pu)ItJ8Gjv2ryV{fl(VWq+JHI#>vplu~(kogY#5FN}kH^p9`Tp<=g_5vo zi9)k(2kDvtjsYPLm|tDz!BvR@-h8YKTD-Z##4hjF$B*@$W0jiARvp&ARK@-lMOe}Z zmbU;GS<@RvZ}Sn-d2ETCgA*-nC84|-y2$?5f4kYCwmwo^Vx<@$QA)yfsipkoU#R7X zyJH5{p(ISW@ihS0%?-1ZzrpKi;q{u71e}4+)MO(Y-Y5yWfN(%b$O9G2WEB*2*;geY ziaCU9NSxEala%&C?2f;Pge}bU=^|=_r5}+pasnz)y$1NXCVr(}Z8dp7*lZ)mJ zVG9($J^A;8CH~F=C|mwE((;!IdKY)=f%d4~*nA^N+c!T0gK=QA5r!r>VW6N%t<)c9 z=TEY5A<71q49=gL+6WF!POIYpmho1H3Ll`bF5xQT#vz=8%-p6+0cRp{+&zg~+LCG?PgN{-1~VFbH?_!^7mCGG=tqL2!{@Z(9UfZ!l(qsQv2RNY zKmR2&UnuoS1WX&4#bb>osL(?Y8m39OI(|1fZ!oDd$m7l5#xZ8ARDA4DG6!J zRd`1~(lNC_wc@#PVF=lXn%A4wk5h$nkB9@5U&6kh_Q*dqp^vb3671JI6a@d=L3fbuspF7M z2PJ4E6LU{|lA2t<$dz9@6{O3 z?VDVZDe>+=182P1B!3*|S5NPKQJq*NXW#~`;=>dr;p=k?#u`EG3G{>{CwBt-2!E?K z%G|gRN4?yp&-+?Q@u;3dh z5WD@-*KEiv?sL=9wQi@M-7eIa8N`E7t)tjHbvd3Otvk!PM^3VDQ#FP$5V5z+KdR8( z*)p^R8o*JGujqm%>Y=Nie;ug*-U9r;KQZ|oNvqR4&?1aBd3sT4jzf)0fJw+_tNool zCmOo$SfjVkt#PLu?72ohh{sA?yV@vXV#OV_m>PxKE4`-r{lA0QctYINJX))`$uv4C zi{!@O5dvNrBw?#dt}1Xd2nI;4gCdJkN;oy^4tpMhn&Pt^i_D~7+zpz&2#ywwEH@*v zNe_G6w;6VCpx&dxdufPy`ZYjspQM6P;lwI~S&cSltimmyP14=7iX2V|6%|+IK!85< z?GbT;{{-3s2_BO2qVw>SLsBG$4O?234?+ab__iC;f?ckiM&IJUIJ3=0X6+Y$P4=Wq zLO)tEW4`>g!w3I!%aTOD0IxF_Wbtp;|4@;b)RFtdh~RaY$^vtUsE!*pKUi*LRFx>^ zL@Xt*Y4%07JKa*1R@TMJqorN#Rakw^3eXl<4hjZFai)a}?e>{r69<7`6ZSmdx19W@ zv+NU%sj5hxv%$SzUW}Nc5@(^RYA-ZfkEdpEF zjucY!NMm#0xZ2~rGjpOBB~WV$I6b)84{he4nmlZg0qz8uwFX)8E9egPd$LARIXN-I zH9%tuoZ#(ifczk=gz?-I=W9}29EY9+1xfr_%$ir|#qI3M;Xq>2=S=?DhS|x_JudFE zlWWzO5tv6&++9NNL4q`Po>Sy2rUqDQiV;tFy|o`x>&gxWe~R8DGiKOHO>zHgIML0* z5{{P4Om^pi@DWaXdDRvr0XM`8zRpN?-sPgNwmfN1<~=2WH&00jkecFeF&K}>{i#8D zFyaB{3E8Eb`7U&#&>}3GuhtjmCflOxn0fX1n^46E(RUlBoYKCicFBf*!YR!Oys1~2 zrNielP=A-nLpVptpjo%l}-?|%>Tzw2;sXc^$mM!t`) zU|(nFF6kZefdK*KHq#slqrgqPuepuC*LtsOk0{Er7VRouq0atVRStE1i|!4tUO zjQ>x%J2T#sj{Q4LPTD~#m~fgQ-+&aw$+sTP?lAR<0YHeWmAqcXGCm9UE?WAJsw2fq z{vg`^h*Qt7>ES7y#?N>!s@LB*3&p*$w2=fK^hc~EOg^?i4UT@Fehc;YlTx)RHKXDZ zdUzcjq&)>u0K7^M3!2$DH;c(7TPuojkxZM%tie>&RR(2{WJA$jzEqt|>U2E~wy(vh zXUoZ}cBmhA9msAOX30-7n}J!3pXA$6s^SJ3>@OT$dcwi&3cGFk>cmK_9Zru{-(7zX zY}o6JhTtAxj%q5haSZ$IEyAmEHB{V1X=2)PBu$hRdgRu~$2zmk`A|UDz8Hsf{Pp=U zG}&Ts&fGBB92gYZT`!r-uz+Qy(5)eeNwbMffoF!RsYPM*8so1|H#h~I|5B-2C&$2CRi7R%xuD)JMH&p zovnfknLiA2{85+xS!Wae`EvgkyqxP^NhGEgEO%snX3mcld2o5Hs#VEL;o9QboR?K; z0U0Nkoe6qZ-)S@D8Tesv2dOUYuL`C=DNDF?sLDVCUK$ESFfL~}dj|Twp6gRHRo^_D zC+oU3QzD)S||y=!=91 z0abAj>rUROCe={rEH7kx^t<4zB5Mb>=IMZ6Z9=i%*B7;t;CGw_fEFMagpjp8pirxB zl60d)uXrn8y@;$Cy^JSGjfW(7_JDq^-a%^btz@%EbFf*6H$?~iRpQPP46g&b$6cUX zWh(g7jeaqOv!u8X4t)d(;(_l{@*9dYUV1}XmM6%&X~G(l#q(`PM#;4rlxeT!cb&TJ z%0Ogux!9r-(!|Lj{38%OK2VS^=A&_`caWPS;P4bEVV3|9UN{o1zx!I zaj+r}26M;e3EzfdZCtan<+vSj_8cMuOYO~_W{wEB#W)4d?>h=Tn09~uOi}2Cp@GMf zu#m9!+B+?>%R<&d`sLC5(U$?$j=`(%yh}dH){TXjQ zo*4zd1GD4Qsp5kLyh`7bv;46p_Rx0E_-1RDRob}7J?j#_7u-owB@=MyOhSK1UWjN2 zSLl_t9l4k2Xz)>QZDL2oek%xambU#>mG_SSDREXnhKSxfMbD$smTAcm&)0+HYlAY>`Fx3!EkF*Wgk<$_}o;8I)~ zf#sxWzZ^XFU;ICk2Tlyx9P1#xVZFcVhtx_u%E-$T$OpII%JN-^eZ5iLV8GYoU7Qwx5>TeTh%^zhpc+l;okiM5l}8azZkrlT4~^RpU;64w9Pj#ETm zoWqh4uKWb{iJDcLaT@hUZVDmQwR5C{x@kF)ua$%|Mt614IZS|Y1^3fLKoASgX%1RJ zta4_vMg{uqblQOg%Eut~+jc;a^;=7KZz%`a1PNn4C-8l5oRRx(QJur#$-xax)8>#2trlLM%Q{!aAHDu7Tc9G}oz^`%%^h=}%a$ph2rtxv9zgOE*fbL=xI>*|9mlveqB zG70{v@F`c2yr2JRtQ*_9%ZNW+`Y=s?uQy~8_&%vr`b65=~HvVhJvkb+SrQeOjA19kyt5X zrF-H~-+mQ5-#8)!*9o$JtLf&gjO|*t+!(@JiWs*HY?&NrJm7wn)gFo=i1nhA+1UR-I3`8mRjL@u60xxhAy#wuO#GHRRD9n zr&Whq#E=gCNxR@%!AmZB;L6Kiy#%abSG(zF;wepF`n)->(_Tv5cnx?>X~hY~3b`J$ z0a#LEfo^R;9a8(2^5+?onQy?%RyA7(3JXkp=A0jo*{=SYd=47mCj355rMfWNm4r7h zN5lLe{gdc%_)dYvt>J8WlG9<`CQj>mL6g&`teAj1$!O6_0JoCHM{n~ZTt0~8KXLEV zR>if~@JVs<`fEV;=nW{lcc@n~SmxvkAV%V1mC6M3WV?2YiKu;Qg+a7fa5UL!HF;aP z^p#2}kmoc+k(eH6@f!^TmKEu}a;Cesj{1dX`n9hUz0M08UmwHX^!a!$5(J)oc3z+vr%*bRqbr5LZ4Y__&OZ zo0M&G;o8o> z$u?T=J3p4HxxYrvZI!z&62h~mya8Yf(;25sD$y$3A@t4kAkrqUUUG|&ZcJtmh zkyU=Q4%ykU8~W`O@rN~Tk2y~!fp#_Nk$M|{tFl@Lk;lzp^f2vtt7lB#XhvIPSL399 za7>e6+@{WkKlaha{ZJE5lflyGohy+|G`TuGQs{p3Jng*1qHKDiU%Zz5UYgfu90R_7 zS^k^e`}tPCC0|H(;>k8ejI+PCOAjNvXAbndC-*=dB~aL~C2I)-D1nE0H_iR#Xc{Ly zb5yHd(dbDZUmeqC@jYeAqwN}yx(xCqwk`ngu;g1yC6qFrxUWZUO%L|-p$=PQgFI5! zRIia(ui3aD1H%h_Ig>-ZL4w zb==w=s*M+_mieljLW14o8yTl0SCTalxvyja1-bi`L1zCX>6JcJ5;}N_9BB<@;~%<; zNtNf)z=t;GBai$%!B(Nn<*4Cl`0zCX(j z0=*9s_RFv(FgT=zKa7gd|9P9S`vKQ5HLU z#_UdSt75kwkFnQgdyI7ywc5Nh8b7LV86E4wv*2zHF3_{7@4+^Q@+0(eDN~XhEYn`h|@84#xbW(acTNsk(Gz+bn(n}E$YQcxN0QiX~7C)#tQlK2BfczqokbM*xc9e zzDz`26w4A<2F-WN$&D77jk2>&v}5C+$E`-~4eJ%Jf$r_p<vnZZrhoLBUaP38~Nzxp&g>F9Xjjalz?Lk;o6L;biS67u5Dp;Hev zl&l(L>s&~IB-%ghOSoTgq;mi=j1|{jVGT87#{yQbTE-2m#(VIMH!zQ^!|dc|J4IZu z^qFT_>^|_>*Xccf32N9vZBO1mCXOwi&be3cE_xdiJrRE>zUB(+(-d%ZmLj(eYr%df znh_bmkgvhbCqNi6lpC&flDfEcOJ>VlaDBOg)f1fefeUzzp+%B}DLv`TD(hzKGn7TT zVYAI2wswZOl`n&iNOJEBhL76U7wuMU+g#CjBv^LDEWaRjgZ(0&g-Tp^C3ErKr;O7` znEcm)0%933{}f_TRggY(T6%g-`7ic1v0q(l7ud~tVQ+|stVXN8>$zl)Z{uJ9^&WGz zBoEbsjw!++ckm{AHmYYFFBvam+B7t910(y7wtw5HlVtPjPJe$x=BeZhB~JHA59OS7 zP?JoZIN^=3^$(a_{T9fl zb7h^4*^|=|Mb8=>N_b0@M9AXIi2}*($)b3HrTne*? z8|1EtiBv4v8x}grUOve8hQB3nL)<0DIWPLP9D%RE>ygTe)%E*dVm#9Hhl)ZQXp@Y# z0zA)L23tgwEXN7-VsnP7*ri>uOG(&=0N{nO0V(@uXiQw+HC8VoZltZ=-*DkqZjb#( zzek_sre*BBupxUfv>aES>gXH^SX#ip&Dgn|eXt?Zvc@zrqk=SEwzb=sQf`?d0i^Yc zyX1NF9D$rDd^Ixw51D*8a;o!R{&95xXn0PHOxmnv!5Jwzso&N z2x;@N4j^YV1iT1npP&OLCCSB7j(T+_-I%t-d-~PA%?*lB`J$myyUYwD_(M3PWZrSe zsu>5aO1`L0FGepaG68pDYqISYN}HZYC(LG%<=MUQ(vkEzthNoZB53r1PxltU{Ub1_C!=y>v9;`OT<4p`D*`kwc z5{GMy;HjCzRDgObVLF$8oxOb0%wrF-Q+!&b(!WGE-^KAPe_!LHl2}UqD(?MX?%J=q zwd?S$Y64(-sX3p&1p5lT^$$UP0^ph|Kohk{Lt-ffuNy|LM80%wwni>aZoDKd@z1p5Fr`~F<0S({fAC63u~ zxV!VI;ns~;Ye79Qi-h92b3b2BM8=hbL%%px299LNS20W#v5+^h)lJ$3ADfOJ4iym% zyfrWxWFytNpzDp%r?K)Mp{tE&ZT~Em0lJbJap> zC7a4Rmo`oe8a9q(TAn`JTtA|>?c7+5e~A6;?~#yd$HW3 zn6ui88TI8qx!3p%ajDcYf!C39qa5|nk|XW5<;yR zyAqEzFm}%NuY3A@esmip+iqR_r{uLg^iN3)Ugsj8@yn%5O@s>K>21$Dm|u~hBxoT1 zyI^Qo;~AO#vfp{5&-9@?XWq^%n$LM@m>;QFI5jH&AbzL7G0w^4VRydj^n8Yn;t8gL z)w}A(R*|w~cP1#h{l5V5mY>5x^@&S(BDCq+ux*U52rK1W=5!tX`;$Lb(D#RNCtO-0 zTSu|O6wyo%x#2yOn^nUMw%``*{T-b640P<>K^j z!m+8AhDv{ZUhgRldG_5QQUQxhrED0KHbWm-*gRZ1&e^EQgMN-8ay#`DEV53yWDTYn zFflbrvT|&+w0KkP9?K=60roo69iv#5{Qk^wyTq!QIl-cfHf&X9P023cTTJ`=&Q%~9 zZdCE+M^#zSUT_}X>~8>km0iJ_T2iv~bf2}7FyNe%qa-v$?P1`2RyCS&f+X42$l1L0 z90ugzTnN{**Z4(`h$GU+ar+-rw(M(r-VELF$D6hXPX#<+nVx?IvCY7D(K?`c_hqr; zk=aTD6nN!V?vZp<_on<3dh(vTA_el4JH&&~gB>4{!^ZOYAq+cWF`KDD}W#dR1alqF#O=|Y8FR&wDyIP(64>jNl3+E zrgrq&G?Rxo1G%UP}d zQcuK6-xm%O@^0Cfb}M*8!K<6OG{sc(b^>Ouit3;K!y()$$0}!TD*BRml3Q*0G&Ex{ znk}v0wu+@BtU97d!4_ePXZ#CZ&*-EB`ID!$c8q~iDO7Y|tqQW01pCe$t_VmI4qFZ1 zm)n&a<-DH~6gFErGVzzs{dH;sQSM
E(Y3;PrgH~U4YSD!iX_> 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 diff --git a/docs/source/docs/callvar_algorithm.jpeg b/docs/source/docs/callvar_algorithm.jpeg new file mode 120000 index 0000000..4c88b31 --- /dev/null +++ b/docs/source/docs/callvar_algorithm.jpeg @@ -0,0 +1 @@ +../../../docs/callvar_algorithm.jpeg \ No newline at end of file diff --git a/docs/source/docs/cmbreps.md b/docs/source/docs/cmbreps.md deleted file mode 100644 index fa5334e..0000000 --- a/docs/source/docs/cmbreps.md +++ /dev/null @@ -1,64 +0,0 @@ -# cmbreps - -## Overview -The `cmbreps` command is part of the MACS3 suite of tools and is used -to combine bedGraph files from replicates. It is particularly useful -in ChIP-Seq analysis where multiple replicates of the same experiment -are performed. - -## Detailed Description - -The `cmbreps` command takes a list of input bedGraph files -(replicates) and produces an output file with combined scores. Note: -All regions on the same chromosome in the bedGraph file should be -continuous so bedGraph files from MACS3 are recommended. - -The `cmbreps` command provides different way to combine replicates, -compared with the `callpeak` command where all replicates will be -simply pooled. A possible usage is that: for each replicate, we can -first follow the instructions in the [Advanced Step-by-step Peak -Calling](./Advanced_Step-by-step_Peak_Calling.md) to generate the -p-value scores through `bdgcmp -m ppois`, use `cmbreps -m fisher` to -use Fisher's combined probability test to combine all the p-value -score tracks and generate a single BedGraph, then call peaks using -`bdgpeakcall`. - -## Command Line Options - -Here is a brief overview of command line options: - -- `-i IFILE1 IFILE2 [IFILE3 ...]`: MACS score in bedGraph for each - replicate. Require at least 2 files. REQUIRED -- `-m` or `--method`: Method to use while combining scores from - replicates. - - `fisher`: Fisher's combined probability test. It requires scores - in ppois form (-log10 pvalues) from `bdgcmp`. Other types of - scores for this method may cause cmbreps unexpected errors. - - `max`: Take the maximum value from replicates for each genomic - position. - - `mean`: Take the average value. Note, except for Fisher's method, - max or mean will take scores AS IS which means they won't convert - scores from log scale to linear scale or vice versa. -- `--outdir`: If specified, all output files will be written to that - directory. Default: the current working directory -- `-o` or `--ofile`: Output BEDGraph filename for combined scores. -- `--verbose`: Set the verbose level of runtime messages. 0: only show - critical messages, 1: show additional warning messages, 2: show - process information, 3: show debug messages. DEFAULT: 2 - - -## Example Usage - -Here is an example of how to use the `cmbreps` command: - -```bash -macs3 cmbreps -i replicate1.bedGraph replicate2.bedGraph replicate3.bedGraph -o combined.bedGraph --method mean -``` - -In this example, the program will combine the scores in the -`replicate1.bedGraph`, `replicate2.bedGraph`, and -`replicate3.bedGraph` files and write the result to -`combined.bedGraph`. The method used for combining scores is `mean` so -it will take the average score from the three replicates at each -genomic location. - diff --git a/docs/source/docs/cmbreps.md b/docs/source/docs/cmbreps.md new file mode 120000 index 0000000..efafc47 --- /dev/null +++ b/docs/source/docs/cmbreps.md @@ -0,0 +1 @@ +../../../docs/cmbreps.md \ No newline at end of file diff --git a/docs/source/docs/cutoffanalysis.md b/docs/source/docs/cutoffanalysis.md deleted file mode 100644 index a3a5385..0000000 --- a/docs/source/docs/cutoffanalysis.md +++ /dev/null @@ -1 +0,0 @@ -# cutoff analysis output format diff --git a/docs/source/docs/fileformats_index.md b/docs/source/docs/fileformats_index.md deleted file mode 100644 index d42cfb4..0000000 --- a/docs/source/docs/fileformats_index.md +++ /dev/null @@ -1,19 +0,0 @@ -# Formats of Input and Output files - -This document the formats and examples of all the input and output -files used in MACS3. - -```{toctree} -:maxdepth: 2 - -callpeakxls.md -SAMBAMBAMPE.md -BED.md -BEDPE.md -bedGraph.md -cutoffanalysis.md -narrowPeak.md -broadPeak.md -gappedPeak.md -vcf.md -hmmratacModel.md diff --git a/docs/source/docs/filterdup.md b/docs/source/docs/filterdup.md deleted file mode 100644 index 4d28db6..0000000 --- a/docs/source/docs/filterdup.md +++ /dev/null @@ -1,97 +0,0 @@ -# filterdup - -## Overview -The `filterdup` command is part of the MACS3 suite of tools and is -used on alignment files to remove duplicate reads. - -## Detailed Description - -The `filterdup` command takes an input alignment file and produces an -output file in BED format with duplicate reads removed according to -the setting. When the input is in BAMPE format (BAM file from aligning -paired-end data), it will produce a BEDPE format file where each row -represent a read-pair. - -The `filteredup` command can also be used to convert any acceptable -format of MACS3 to BED or BEDPE (in case of `-f BAMPE`) format, if you -use `--keep-dup all` option. - -Please note that, when writing BED format output for single-end -dataset, MACS3 assume all the reads having the same length either from -`-s` setting or from auto-detection. - -## Command Line Options - -Here is a brief overview of the command line options: - -- `-i` or `--ifile`: The input alignment file. If multiple files are - given as '-t A B C', then they will all be read and pooled. REQUIRED. -- `-f`or `--format`: The format of the alignment file. Options - include: "AUTO", "BED" or "ELAND" or "ELANDMULTI" or "ELANDEXPORT" - or "SAM" or "BAM" or "BOWTIE" or "BAMPE" or "BEDPE". The default - AUTO option will let `filterdup` decide which format the file - is. Please check the [`callpeak`](./callpeak.md) for detail. Choices - can be `ELAND/ELANDMULTI/ELANDEXPORT/SAM/BAM/BOWTIE` or - `BAMPE/BEDPE`. DEFAULT: `AUTO` -- `-g` or `--gsize`: Please check [`callpeak`](./callpeak.md) for - detail. DEFAULT:hs -- `-s` or `--tsize`: The tag size. This will override the auto - detected tag size. DEFAULT: Not set -- `-p` or `--pvalue`: The pvalue cutoff for binomial distribution - test. DEFAULT:1e-5 -- `--keep-dup`: The number of duplicates to keep. It controls the - 'macs3 filterdup' behavior towards duplicate tags/pairs at the exact - same location -- the same coordination and the same strand. If the - value is `auto`, `filterdup` will calculate the maximum tags at the - exact same location based on a binomal distribution using given `-p` - as pvalue cutoff; and the `all` value will keep every tags (useful - if you only want to convert formats). If an integer is given, at - most this number of tags will be kept at the same location. Note, - MACS3 `callpeak` function uses `--keep-dup=1` as default. Note, if - you've used `samtools` or `picard` to flag reads as 'PCR/Optical - duplicate' in bit 1024, MACS3 will still read them although the - reads may be decided by MACS3 as duplicate later. Default: `auto` -- `--buffer-size`: The buffer size for incrementally increasing - internal array size to store reads alignment information. In most - cases, you don't have to change this parameter. However, if there - are large number of chromosomes/contigs/scaffolds in your alignment, - it's recommended to specify a smaller buffer size in order to - decrease memory usage (but it will take longer time to read - alignment files). Minimum memory requested for reading an alignment - file is about `# of CHROMOSOME * BUFFER_SIZE * 8` Bytes. DEFAULT: - 100000 -- `--verbose`: The verbose level. 0: only show critical message, 1: - show additional warning message, 2: show process information, 3: - show debug messages. If you want to know where are the duplicate - reads, use 3. DEFAULT:2 -- `--outdir`: If specified all output files will be written to that - directory. Default: the current working directory -- `-o` or `--ofile`: The output BED file name. If not specified, will - write to standard output. Note, if the input format is BAMPE or - BEDPE, the output will be in BEDPE format. DEFAULT: stdout -- `-d` or `--dry-run`: When set, filterdup will only output numbers - instead of writing output files, including maximum allowable - duplicates, total number of reads before filtering, total number of - reads after filtering, and redundant rate. Default: not set - -## Example Usage - -Here is an example of how to use the `filterdup` command: - -```bash -macs3 filterdup -i input.bam -o output.bed --gsize hs --format AUTO --keep-dup 1 --buffer-size 100000 -``` - -In this example, the program will remove duplicate reads from the -`input.bam` file and write the result to `output.bed`. The mappable -genome size is set to `hs` (Homo Sapiens), the format of the input -file is determined automatically, and the program keeps only one -duplicate. - -Here is an example to convert BAMPE file into BEDPE. Please note that -`-f BAMPE` and `--keep-dup all` are both necessary for format -conversion: - -```bash -macs3 filterdup -i input.bam -o output.bedpe -f BAMPE --keep-dup all -``` diff --git a/docs/source/docs/filterdup.md b/docs/source/docs/filterdup.md new file mode 120000 index 0000000..032b72a --- /dev/null +++ b/docs/source/docs/filterdup.md @@ -0,0 +1 @@ +../../../docs/filterdup.md \ No newline at end of file diff --git a/docs/source/docs/gappedPeak.md b/docs/source/docs/gappedPeak.md deleted file mode 100644 index 84cedc2..0000000 --- a/docs/source/docs/gappedPeak.md +++ /dev/null @@ -1 +0,0 @@ -# gappedPeak format diff --git a/docs/source/docs/hmmratac.md b/docs/source/docs/hmmratac.md deleted file mode 100644 index e6bc4d8..0000000 --- a/docs/source/docs/hmmratac.md +++ /dev/null @@ -1,267 +0,0 @@ -# hmmratac - -## Description - -HMMRATAC (`macs3 hmmratac`) is a dedicated peak calling algorithm -based on Hidden Markov Model for ATAC-seq data. The basic idea behind -HMMRATAC is to digest ATAC-seq data according to the fragment length -of read pairs into four signal tracks: short fragments, -mono-nucleosomal fragments, di-nucleosomal fragments and -tri-nucleosomal fragments. Then integrate the four tracks using Hidden -Markov Model to consider three hidden states: open region, nucleosomal -region, and background region. The [orginal -paper](https://academic.oup.com/nar/article/47/16/e91/5519166) was -published in 2019, and the original software was written in JAVA, by -the then PhD student Evan Tarbell, a mohawk bioinformatician. In MACS3 -project, we implemented HMMRATAC idea in Python/Cython and optimize -the whole process using existing MACS functions and hmmlearn. - -Here's an example of how to run the `hmmratac` command: - -``` -$ macs3 hmmratac -i yeast.bam -n yeast -``` - -or with the BEDPE format - -``` -$ macs3 hmmratac -i yeast.bedpe.gz -f BEDPE -n yeast -``` - -Note: you can convert BAMPE to BEDPE by using - -``` -$ macs3 filterdup --keep-dup all -f BAMPE -i yeast.bam -o yeast.bedpe -``` - -Please use `macs3 hmmratac --help` to see all the options. Here we -list the essential ones. - -## Essential Options - -### `-i INPUT_FILE [INPUT_FILE ...]` / `--input INPUT_FILE [INPUT_FILE ...]` - -This is the only REQUIRED parameter for `hmmratac`. Input files -containing the aligment results for ATAC-seq paired end reads. If -multiple files are given as '-t A B C', then they will all be read and -pooled together. The file should be in BAMPE or BEDPE format (aligned -in paired end mode). Files can be gzipped. Note: all files should be -in the same format. REQUIRED. - -### `-f {BAMPE,BEDPE}` / `--format {BAMPE,BEDPE}` - -Format of input files, "BAMPE" or "BEDPE". If there are multiple -files, they should be in the same format -- either BAMPE or -BEDPE. Please note that the BEDPE only contains three columns -- -chromosome, left position of the whole pair, right position of the -whole pair-- and is NOT the same BEDPE format used by BEDTOOLS. To -convert BAMPE to BEDPE, you can use this command `macs3 filterdup ---keep-dup all -f BAMPE -i input.bam -o output.bedpe`. DEFAULT: -"BAMPE". - -### `--outdir OUTDIR` - -If specified all output files will be written to that -directory. Default: the current working directory - -### `-n NAME`/ `--name NAME` -Name for this experiment, which will be used as a prefix to generate -output file names. DEFAULT: "NA" - -### `--modelonly` - This option will only generate the HMM model as a JSON file and - quit. This model can then be applied using the `--model` - option. Default: False - -### `--model` - If provided, HMM training will be skipped and a JSON file generated - from a previous HMMRATAC run will be used instead of creating new - one. Default: NA - -### `-t HMM_TRAINING_REGIONS` / `--training HMM_TRAINING_REGIONS` - Customized training regions can be provided through this option. `-t` - takes the filename of training regions (previously was BED_file) to - use for training HMM, instead of using foldchange settings to - select. Default: NA - -### `--min-frag-p MIN_FRAG_P` - We will exclude the abnormal fragments that can't be assigned to any - of the four signal tracks. After we use EM to find the means and - stddevs of the four distributions, we will calculate the likelihood - that a given fragment length fit any of the four using normal - distribution. The criteria we will use is that if a fragment length - has less than MIN_FRAG_P probability to be like either of short, - mono, di, or tri-nuc fragment, we will exclude it while generating - the four signal tracks for later HMM training and prediction. The - value should be between 0 and 1. Larger the value, more abnormal - fragments will be allowed. So if you want to include more 'ideal' - fragments, make this value smaller. Default = 0.001 - -### `--cutoff-analysis-only` - - Only run the cutoff analysis and output a report. After generating - the report, the process will stop. The report will help user decide - the three crucial parameters for `-l`, `-u`, and `-c`. So it's highly - recommanded to run this first! Please read the report and - instructions in [Choices of cutoff values](#choices-of-cutoff-values) - on how to decide the three crucial parameters. - -### `--cutoff-analysis-steps` - -Steps for performing cutoff analysis. It will be used to decide which -cutoff value should be included in the final report. Larger the value, -higher resolution the cutoff analysis can be. The cutoff analysis -function will first find the smallest and the largest foldchange score -in the data, then break the range of foldchange score into -`CUTOFF_ANALYSIS_STEPS` intervals. It will then use each foldchange -score as cutoff to call peaks and calculate the total number of -candidate peaks, the total basepairs of peaks, and the average length -of peak in basepair. Please note that the final report ideally should -include `CUTOFF_ANALYSIS_STEPS` rows, but in practice, if the -foldchange cutoff yield zero peak, the row for that foldchange value -won't be included. DEFAULT: 100 - -### `--hmm-type` - -We provide two types of emissions for the Hidden Markov Model -- the -Gaussian model and the Poisson model. By default, the Gaussian -emission will be used (as `--hmm-type gaussian`). To choose Poisson -emission, use `--hmm-type poisson`. The Gaussian emission can be -described by mean and variance for each state, while the simpler -Poisson only needs the lambda value. The difference can be found in -the saved json file for HMM. - -### `-u HMM_UPPER` / `--upper HMM_UPPER` - -Upper limit on fold change range for choosing training sites. This is -an important parameter for training so please read. The purpose of -this parameter is to EXCLUDE those unusually highly enriched chromatin -regions so we can get training samples in 'ordinary' regions -instead. It's highly recommended to run the `--cutoff-analysis-only` -first to decide the lower cutoff `-l`, the upper cutoff `-u`, and the -pre-scanning cutoff `-c`. The upper cutoff should be the cutoff in the -cutoff analysis result that can capture some (typically hundreds of) -extremely high enrichment and unusually wide peaks. Default: 20 - -### `-l HMM_LOWER` / `--lower HMM_LOWER` -Lower limit on fold change range for choosing training sites. This is -an important parameter for training so please read. The purpose of -this parameter is to ONLY INCLUDE those chromatin regions having -ordinary enrichment so we can get training samples to learn the common -features through HMM. It's highly recommended to run the -`--cutoff-analysis-only` first to decide the lower cutoff `-l`, the -upper cutoff `-u`, and the pre-scanning cutoff `-c`. The lower cutoff -should be the cutoff in the cutoff analysis result that can capture -moderate number ( about 10k ) of peaks with normal width ( average -length 500-1000bps long). Default: 10 - -### `-c PRESCAN_CUTOFF` / `--prescan-cutoff PRESCAN_CUTOFF` - -The fold change cutoff for prescanning candidate regions in the whole -dataset. Then we will use HMM to predict/decode states on these -candidate regions. The higher the prescan cutoff, the fewer regions -will be considered. Must be > 1. This is an important parameter for -decoding so please read. The purpose of this parameter is to EXCLUDE -those chromatin regions having noises/random enrichment so we can have -a large number of possible regions to predict the HMM states. It's -highly recommended to run the `--cutoff-analysis-only` first to decide -the lower cutoff `-l`, the upper cutoff `-u`, and the pre-scanning -cutoff `-c`. The pre-scanning cutoff should be the cutoff close to the -BOTTOM of the cutoff analysis result that can capture a large number -of possible peaks with normal length (average length 500-1000bps). In -most cases, please do not pick a cutoff too low that captures almost -all the background noises from the data. Default: 1.2 - - -## Choices of cutoff values - -Before you proceed, it's highly recommended to run with -`--cutoff-analysis-only` for the initial attempt. When this option is -activated, `hmmratac` will use EM to estimate the best parameters for -fragment sizes of short fragments, mono-, di-, and tri-nucleosomes, -pileup fragments, convert the pileup values into fold-change, and -analyze each possible cutoff. This analysis includes the number of -peaks that can be called, their average peak length, and their total -length. After the report is generated, you can review its contents and -decide on the optimal `-l`, `-u`, and `-c`. - -The report consists of four columns: - -1. Score: the possible fold change cutoff value. -2. npeaks: the number of peaks. -3. lpeaks: the total length of all peaks. -4. avelpeak: the average length of peaks. - -While there's no universal rule, here are a few suggestions: - -- The lower cutoff should be the cutoff in the report that captures a - moderate number (about 10k) of peaks with a normal width (average - length 500-1000bps long). -- The upper cutoff should capture some (typically hundreds of) - extremely high enrichment and unusually wide peaks in the - report. The aim here is to exclude abnormal enrichment caused by - artifacts such as repetitive regions. -- The pre-scanning cutoff should be the cutoff close to the BOTTOM of - the report that can capture a large number of potential peaks with a - normal length (average length 500-1000bps). However, it's - recommended not to use the lowest cutoff value in the report as this - may include too much noise from the genome. - -## Tune the HMM model - -It's highly recommended to check the runtime message of the HMM model -after training. An example is like this: - -``` -#4 Train Hidden Markov Model with Multivariate Gaussian Emission -# Extract signals in training regions with bin size of 10 -# Use Baum-Welch algorithm to train the HMM -# HMM converged: True -# Write HMM parameters into JSON: test_model.json -# The Hidden Markov Model for signals of binsize of 10 basepairs: -# open state index: state2 -# nucleosomal state index: state1 -# background state index: state0 -# Starting probabilities of states: -# bg nuc open -# 0.7994 0.1312 0.06942 -# HMM Transition probabilities: -# bg nuc open -# bg-> 0.9842 0.01202 0.003759 -# nuc-> 0.03093 0.9562 0.01287 -# open-> 0.007891 0.01038 0.9817 -# HMM Emissions (mean): -# short mono di tri -# bg: 0.2551 1.526 0.4646 0.07071 -# nuc: 6.538 17.94 3.422 0.05819 -# open: 5.016 17.47 6.897 2.121 -``` - -We will 'guess' which hidden state is for the open region, which is -the nucleosomal region, and which is the background. We compute from -the HMM Emission matrix to pick the state with the highest sum of mean -signals as the open state, the lowest as the backgound state, then the -rest is the nucleosomal state. However it may not work in every -case. In the above example, it may be tricky to call the second row as -'nuc' and the third as 'open'. If the users want to exchange the state -assignments of the 'nuc' and 'open', they can modify the state -assignment in the HMM model file (e.g. test_model.json). For the above -example, the model.json looks like this (we skipped some detail): - -``` -{"startprob": [...], "transmat": [...], "means": [...], "covars": [...], -"covariance_type": "full", "n_features": 4, -"i_open_region": 2, "i_background_region": 0, "i_nucleosomal_region": 1, -"hmm_binsize": 10} -``` - -We can modify the assignment of: `"i_open_region": 2, -"i_background_region": 0, "i_nucleosomal_region": 1,` by assigning `1` -to open, and `2` to nucleosomal as: `"i_open_region": 1, -"i_background_region": 0, "i_nucleosomal_region": 2,` Then save the -HMM in a new model file such as `new_model.json`. - -Then next, we can re-run `macs3 hmmratac` with the same parameters -plus an extra option for the HMM model file like `macs3 hmmratac ---model new_model.json` - diff --git a/docs/source/docs/hmmratac.md b/docs/source/docs/hmmratac.md new file mode 120000 index 0000000..21189ed --- /dev/null +++ b/docs/source/docs/hmmratac.md @@ -0,0 +1 @@ +../../../docs/hmmratac.md \ No newline at end of file diff --git a/docs/source/docs/hmmratacModel.md b/docs/source/docs/hmmratacModel.md deleted file mode 100644 index 25a5f65..0000000 --- a/docs/source/docs/hmmratacModel.md +++ /dev/null @@ -1 +0,0 @@ -# `hmmratac` HMM model json file format diff --git a/docs/source/docs/subcommands_index.md b/docs/source/docs/index.md similarity index 100% rename from docs/source/docs/subcommands_index.md rename to docs/source/docs/index.md diff --git a/docs/source/docs/narrowPeak.md b/docs/source/docs/narrowPeak.md deleted file mode 100644 index aec8e10..0000000 --- a/docs/source/docs/narrowPeak.md +++ /dev/null @@ -1 +0,0 @@ -# narrowPeak format diff --git a/docs/source/docs/pileup.md b/docs/source/docs/pileup.md deleted file mode 100644 index 6563439..0000000 --- a/docs/source/docs/pileup.md +++ /dev/null @@ -1,74 +0,0 @@ -# pileup - -## Overview -The `pileup` command is part of the MACS3 suite of tools and is used -to pile up alignment files. It is a fast algorithm to generate -coverage track from alignment file -- either single-end or paired-end -data. - -## Detailed Description - -The `pileup` command takes in one or multiple input files and produces -an output file with the piled-up genomic coverage. It uses an -efficient algorithm to pile up the alignments. - -![Pileup Algorithm](pileup.png) - -Pileup aligned reads with a given extension size (fragment size or d -in MACS language). Note there will be no step for duplicate reads -filtering or sequencing depth scaling, so you may need to do certain -pre/post-processing, such as using `filterdup` or `randsample` -command. - -## Command Line Options - -Here is a brief overview of the command line options for `pileup`: - -- `-i` or `--ifile`: Alignment file. If multiple files are given as - '-t A B C', then they will all be read and combined. REQUIRED. -- `-o` or `--ofile`: Output bedGraph file name. If not specified, will - write to standard output. REQUIRED. -- `--outdir`: If specified, all output files will be written to that - directory. Default: the current working directory -- `-f ` or `--format`: Format of the tag file. - - `AUTO`: MACS3 will pick a format from "AUTO", "BED", "ELAND", - "ELANDMULTI", "ELANDEXPORT", "SAM", "BAM", and "BOWTIE". If the - format is BAMPE or BEDPE, please specify it explicitly. - - `BAMPE` or `BEDPE`: When the format is BAMPE or BEDPE, the -B and - --extsize options would be ignored. - - Other options correspond to specific formats. -- `-B` or `--both-direction`: By default, any read will be extended - towards the downstream direction by the extension size. If this - option is set, aligned reads will be extended in both upstream and - downstream directions by the extension size. This option will be - ignored when the format is set as BAMPE or BEDPE. DEFAULT: False -- `--extsize`: The extension size in bps. Each alignment read will - become an EXTSIZE of the fragment, then be piled up. Check - description for -B for details. This option will be ignored when the - format is set as BAMPE or BEDPE. DEFAULT: 200 -- `--buffer-size`: Buffer size for incrementally increasing the - internal array size to store read alignment information. In most - cases, you don't have to change this parameter. However, if there - are a large number of chromosomes/contigs/scaffolds in your - alignment, it's recommended to specify a smaller buffer size in - order to decrease memory usage (but it will take longer time to read - alignment files). Minimum memory requested for reading an alignment - file is about # of CHROMOSOME * BUFFER_SIZE * 8 Bytes. DEFAULT: - 100000 -- `--verbose`: Set verbose level. 0: only show critical messages, 1: - show additional warning messages, 2: show process information, 3: - show debug messages. If you want to know where are the duplicate - reads, use 3. DEFAULT: 2 - -## Example Usage - -Here is an example of how to use the `pileup` command: - -```bash -macs3 pileup -i treatment.bam -o piledup.bedGraph -f BAM --extsize 147 -``` - -In this example, the program will pile up the alignments in the -`treatment.bam` file and write the result to `piledup.bedGraph`. The -input file is in BAM format, and we extend each sequencing tag into a -147bps fragment for pileup. diff --git a/docs/source/docs/pileup.md b/docs/source/docs/pileup.md new file mode 120000 index 0000000..af4bcf3 --- /dev/null +++ b/docs/source/docs/pileup.md @@ -0,0 +1 @@ +../../../docs/pileup.md \ No newline at end of file diff --git a/docs/source/docs/pileup.png b/docs/source/docs/pileup.png deleted file mode 100644 index bdabcc38aa3c3b1ce070a4e06d324abfaca3ad96..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcwPel00001 literal 34709 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 diff --git a/docs/source/docs/pileup.png b/docs/source/docs/pileup.png new file mode 120000 index 0000000..496476e --- /dev/null +++ b/docs/source/docs/pileup.png @@ -0,0 +1 @@ +../../../docs/pileup.png \ No newline at end of file diff --git a/docs/source/docs/predictd.md b/docs/source/docs/predictd.md deleted file mode 100644 index fc327c5..0000000 --- a/docs/source/docs/predictd.md +++ /dev/null @@ -1,89 +0,0 @@ -# predictd - -## Overview -The `predictd` command is part of the MACS3 suite of tools and is used -to predict the expected DNA fragment size from alignment files. It -uses the cross-correlation method to find the best shift to correlate -the cutting ends on plus and minus strands. - -## Detailed Description - -The `predictd` command takes an input bedGraph file and predicts *d* -or fragment size from alignment results. In case of paired-end data, -it will report the average insertion/fragment size from all -pairs. Note there will be no step for duplicate reads filtering or -sequencing depth scaling, so you may need to do certain -pre/post-processing, such as using `filterdup` or `randsample` -command. - -If the alignment file is a single-end file, a model file (from -`--rfile`) will be saved which can be used to visualize the model in -PDF. And the command line output will tell the predicted *d* size in -the line of `predicted fragment length is` and alternative *d* sizes -in the line of `alternative fragment length(s) may be`. - -If the alignment file is a paired-end file (`-f BAMPE` or `-f BEDPE`), -the model file won't be generated. Instead, you can find the average -fragment size in the command line output in the line of: `Average -insertion length of all pairs is`. - -## Command Line Options - -Here is a brief overview of the `predictd` options: - -- `-i` or `--ifile`: ChIP-seq alignment file. If multiple files are - given as '-t A B C', then they will all be read and - combined. REQUIRED. -- `-f` or `--format`: Format of the tag file. - - `AUTO`: MACS3 will pick a format from "AUTO", "BED", "ELAND", - "ELANDMULTI", "ELANDEXPORT", "SAM", "BAM", "BOWTIE", "BAMPE", and - "BEDPE". However, if you want to decide the average insertion - size/fragment size from PE data such as BEDPE or BAMPE, please - specify the format as BAMPE or BEDPE since MACS3 won't - automatically recognize these two formats with -f AUTO. Please be - aware that in PE mode, -g, -s, --bw, --d-min, -m, and --rfile have - NO effect. DEFAULT: "AUTO" -- `-g` or `--gsizeE`: Please check [`callpeak`](./callpeak.md) for - detail. DEFAULT:hs -- `-s` or `--tsize`: Tag size. This will override the auto-detected - tag size. DEFAULT: Not set -- `--bw`: Bandwidth for picking regions to compute the fragment - size. This value is only used while building the shifting - model. DEFAULT: 300 -- `--d-min`: Minimum fragment size in base pairs. Any predicted - fragment size less than this will be excluded. DEFAULT: 20 -- `-m` or `--mfoldD`: Select the regions within MFOLD range of - high-confidence enrichment ratio against background to build the - model. Fold-enrichment in regions must be lower than the upper limit - and higher than the lower limit. Use as "-m 10 30". DEFAULT: 5 50 -- `--outdir`: If specified, all output files will be written to that - directory. Default: the current working directory -- `--rfile`: PREFIX of the filename of the R script for drawing the - X-correlation figure. DEFAULT: 'predictd_model.R' and the R file - will be predicted_model.R -- `--buffer-size`: Buffer size for incrementally increasing the - internal array size to store read alignment information. In most - cases, you don't have to change this parameter. However, if there is - a large number of chromosomes/contigs/scaffolds in your alignment, - it's recommended to specify a smaller buffer size in order to - decrease memory usage (but it will take longer time to read - alignment files). Minimum memory requested for reading an alignment - file is about # of CHROMOSOME * BUFFER_SIZE * 8 Bytes. DEFAULT: - 100000 -- `--verbose`: Set the verbose level of runtime messages. 0: only show - critical messages, 1: show additional warning messages, 2: show - process information, 3: show debug messages. DEFAULT: 2 - -## Example Usage - -Here is an example of how to use the `predictd` command: - -```bash -macs3 predictd -i input.bedGraph --rfile model.R -``` - -Then you can use R to make a figure for the model: - -```bash -Rscript model.R -``` diff --git a/docs/source/docs/predictd.md b/docs/source/docs/predictd.md new file mode 120000 index 0000000..287ad16 --- /dev/null +++ b/docs/source/docs/predictd.md @@ -0,0 +1 @@ +../../../docs/predictd.md \ No newline at end of file diff --git a/docs/source/docs/qa.md b/docs/source/docs/qa.md deleted file mode 100644 index b69f856..0000000 --- a/docs/source/docs/qa.md +++ /dev/null @@ -1 +0,0 @@ -# Common Q & A diff --git a/docs/source/docs/qa.md b/docs/source/docs/qa.md new file mode 120000 index 0000000..87dcbab --- /dev/null +++ b/docs/source/docs/qa.md @@ -0,0 +1 @@ +../../../docs/qa.md \ No newline at end of file diff --git a/docs/source/docs/randsample.md b/docs/source/docs/randsample.md deleted file mode 100644 index 8344e22..0000000 --- a/docs/source/docs/randsample.md +++ /dev/null @@ -1,84 +0,0 @@ -# randsample - -## Overview -The `randsample` command is part of the MACS3 suite of tools and is -used to randomly sample a certain number or percentage of tags from -alignment files. This can be useful in ChIP-Seq analysis when a -subset of the data is required for downstream analysis. - -## Detailed Description - -The `randsample` command takes in one or multiple input alignment -files and produces an output file with the randomly sampled tags. It -will randomly sample the tags, according to setting for percentage or -for total number of tags to be kept. - -When `-p 100` is used, which means we want to keep all reads, the -`randsample` command can be used to convert any format MACS3 supported -to BED (or BEDPE if the input is BAMPE format) format. It can generate -the same result as `filterdup --keep-dup all` to convert other formats -into BED/BEDPE format. - -Please note that, when writing BED format output for single-end -dataset, MACS3 assume all the reads having the same length either from -`-s` setting or from auto-detection. - -## Command Line Options - -Here is a brief overview of the `randsample` options: - -- `-i` or `--ifile`: Alignment file. If multiple files are given as - '-t A B C', then they will all be read and combined. REQUIRED. -- `-p` or `--percentage`: Percentage of tags you want to keep. Input - 80.0 for 80%. This option can't be used at the same time with - -n/--num. If the setting is 100, it will keep all the reads and - convert any format that MACS3 supports into BED or BEDPE (if input - is BAMPE) format. REQUIRED -- `-n` or `--number`: Number of tags you want to keep. Input 8000000 - or 8e+6 for 8 million. This option can't be used at the same time - with -p/--percent. Note that the number of tags in the output is - approximate as the number specified here. REQUIRED -- `--seed`: Set the random seed while downsampling data. Must be a - non-negative integer in order to be effective. If you want more - reproducible results, please specify a random seed and record - it. DEFAULT: not set -- `-o` or `--ofile`: Output BED file name. If not specified, will - write to standard output. Note, if the input format is BAMPE or - BEDPE, the output will be in BEDPE format. DEFAULT: stdout -- `--outdir`: If specified, all output files will be written to that - directory. Default: the current working directory -- `-s` or `--tsize`: Tag size. This will override the auto-detected - tag size. DEFAULT: Not set -- `-f` or `--format`: Format of the tag file. - - `AUTO`: MACS3 will pick a format from "AUTO", "BED", "ELAND", - "ELANDMULTI", "ELANDEXPORT", "SAM", "BAM", "BOWTIE", "BAMPE", and - "BEDPE". Please check the definition in the README file if you - choose ELAND/ELANDMULTI/ELANDEXPORT/SAM/BAM/BOWTIE or - BAMPE/BEDPE. DEFAULT: "AUTO" -- `--buffer-size`: Buffer size for incrementally increasing the - internal array size to store read alignment information. In most - cases, you don't have to change this parameter. However, if there - are a large number of chromosomes/contigs/scaffolds in your - alignment, it's recommended to specify a smaller buffer size in - order to decrease memory usage (but it will take longer time to read - alignment files). Minimum memory requested for reading an alignment - file is about # of CHROMOSOME * BUFFER_SIZE * 8 Bytes. DEFAULT: - 100000 -- `--verbose`: Set the verbose level. 0: only show critical messages, - 1: show additional warning messages, 2: show process information, 3: - show debug messages. If you want to know where the duplicate reads - are, use 3. DEFAULT: 2 - - -## Example Usage - -Here is an example of how to use the `randsample` command: - -```bash -macs3 randsample -i treatment.bam -o sampled.bed -f BAM -p 10 -``` - -In this example, the program will randomly sample 10 percent of total -tags from the `treatment.bam` file and write the result to -`sampled.bed`. - diff --git a/docs/source/docs/randsample.md b/docs/source/docs/randsample.md new file mode 120000 index 0000000..52a4931 --- /dev/null +++ b/docs/source/docs/randsample.md @@ -0,0 +1 @@ +../../../docs/randsample.md \ No newline at end of file diff --git a/docs/source/docs/refinepeak.md b/docs/source/docs/refinepeak.md deleted file mode 100644 index fe0dc67..0000000 --- a/docs/source/docs/refinepeak.md +++ /dev/null @@ -1,66 +0,0 @@ -# refinepeak - -## Overview -The `refinepeak` command is part of the MACS3 suite of tools and is -used to refine peak summits. It is particularly useful in ChIP-Seq -analysis where refining the peak summits can lead to more accurate -results. - -## Detailed Description - -The `refinepeak` command takes in a BED file containing peaks and raw -reads alignment, then produces an output BED file with refined peak -summits. It will refine peak summits and give scores measuring the -balance of Watson/Crick tags, inspired by SPP. Basically, we assume -that a good summit in a peak region should have balanced Watson/Crick -tags around. - -## Command Line Options - -Here is a brief overview of the `refinepeak` options: - -- `-b`: Candidate peak file in BED format. REQUIRED. -- `-i` or `--ifile`: ChIP-seq alignment file. If multiple files are - given as '-t A B C', then they will all be read and combined. Note - that pair-end data is not supposed to work with this - command. REQUIRED. -- `-f` or `--format`: Format of the tag file. - - `AUTO`: MACS3 will pick a format from "AUTO", "BED", "ELAND", - "ELANDMULTI", "ELANDEXPORT", "SAM", "BAM", "BOWTIE". Please check - the definition in the README file if you choose - ELAND/ELANDMULTI/ELANDEXPORT/SAM/BAM/BOWTIE. DEFAULT: "AUTO" -- `-c` or `--cutoff`: Cutoff. Regions with SPP wtd score lower than - cutoff will not be considered. DEFAULT: 5 -- `-w` or `--window-size`: Scan window size on both sides of the - summit (default: 100bp) -- `--buffer-size`: Buffer size for incrementally increasing the - internal array size to store read alignment information. In most - cases, you don't have to change this parameter. However, if there - are a large number of chromosomes/contigs/scaffolds in your - alignment, it's recommended to specify a smaller buffer size in - order to decrease memory usage (but it will take longer time to read - alignment files). Minimum memory requested for reading an alignment - file is about # of CHROMOSOME * BUFFER_SIZE * 8 Bytes. DEFAULT: - 100000 -- `--verbose`: Set the verbose level. 0: only show critical messages, - 1: show additional warning messages, 2: show process information, 3: - show debug messages. If you want to know where the duplicate reads - are, use 3. DEFAULT: 2 -- `--outdir`: If specified, all output files will be written to that - directory. Default: the current working directory -- `-o` or `--ofile`: Output file name. Mutually exclusive with - --o-prefix. -- `--o-prefix`: Output file prefix. Mutually exclusive with - -o/--ofile. - -## Example Usage - -Here is an example of how to use the `refinepeak` command: - -```bash -macs3 refinepeak -b peaks.bed -i alignment.bam -o refined_peaks.bed -``` - -In this example, the program will refine the peak summits in the -`peaks.bed` file taking in the alignment file `alignment.bam`, and -write the result to `refined_peaks.bed`. diff --git a/docs/source/docs/refinepeak.md b/docs/source/docs/refinepeak.md new file mode 120000 index 0000000..a8fb630 --- /dev/null +++ b/docs/source/docs/refinepeak.md @@ -0,0 +1 @@ +../../../docs/refinepeak.md \ No newline at end of file diff --git a/docs/source/docs/tutorial.md b/docs/source/docs/tutorial.md deleted file mode 100644 index 4f50ecc..0000000 --- a/docs/source/docs/tutorial.md +++ /dev/null @@ -1 +0,0 @@ -# Tutorial diff --git a/docs/source/docs/tutorial.md b/docs/source/docs/tutorial.md new file mode 120000 index 0000000..4b6ed79 --- /dev/null +++ b/docs/source/docs/tutorial.md @@ -0,0 +1 @@ +../../../docs/tutorial.md \ No newline at end of file diff --git a/docs/source/docs/vcf.md b/docs/source/docs/vcf.md deleted file mode 100644 index 947df29..0000000 --- a/docs/source/docs/vcf.md +++ /dev/null @@ -1 +0,0 @@ -# VCF format diff --git a/docs/source/index.md b/docs/source/index.md index 94398a0..ba39bcd 100644 --- a/docs/source/index.md +++ b/docs/source/index.md @@ -258,8 +258,7 @@ contributions over the years. :hidden: docs/INSTALL.md -docs/subcommands_index.md -docs/fileformats_index.md +docs/index.md docs/Advanced_Step-by-step_Peak_Calling.md docs/qa.md docs/tutorial.md diff --git a/docs/source/docs/tutorial.md b/docs/tutorial.md similarity index 100% copy from docs/source/docs/tutorial.md copy to docs/tutorial.md -- 2.11.4.GIT