From 5745cb72ad095d9cc4e1994d56d457873746e8ca Mon Sep 17 00:00:00 2001 From: Tao Liu Date: Thu, 28 Mar 2024 16:02:33 -0400 Subject: [PATCH 01/18] update instructions for conda install --- README.md | 8 ++++---- docs/INSTALL.md | 15 +++++++++++++-- docs/source/index.md | 8 ++++---- 3 files changed, 21 insertions(+), 10 deletions(-) diff --git a/README.md b/README.md index aa22f4dd..6b742c57 100644 --- a/README.md +++ b/README.md @@ -6,12 +6,12 @@ download](https://img.shields.io/pypi/dm/macs3?label=pypi%20downloads)](https://pypistats.org/packages/macs3) Latest Release: - -* Github: [![Github Release](https://img.shields.io/github/v/release/macs3-project/MACS)](https://github.com/macs3-project/MACS/releases) -* PyPI: [![PyPI Release](https://img.shields.io/pypi/v/macs3.svg)![PyPI Python Version](https://img.shields.io/pypi/pyversions/MACS3)![PyPI Format](https://img.shields.io/pypi/format/macs3)](https://pypi.org/project/macs3/) -* Anaconda: [![Anaconda-Server Badge](https://anaconda.org/macs3/macs3/badges/version.svg)](https://anaconda.org/macs3/macs3) +* Github: [![Github Release](https://img.shields.io/github/v/release/macs3-project/MACS)](https://github.com/macs3-project/MACS/releases) +* PyPI: [![PyPI Release](https://img.shields.io/pypi/v/macs3.svg) +* Bioconda:[![Bioconda Badge](https://anaconda.org/bioconda/macs3/badges/version.svg)](https://anaconda.org/bioconda/macs3) * Debian Med: [![Debian Stable](https://img.shields.io/debian/v/macs/stable?label=debian%20stable)](https://packages.debian.org/stable/macs)[![Debian Unstable](https://img.shields.io/debian/v/macs/sid?label=debian%20sid)](https://packages.debian.org/sid/macs) + ## Introduction With the improvement of sequencing techniques, chromatin diff --git a/docs/INSTALL.md b/docs/INSTALL.md index cd8b11c0..37407794 100644 --- a/docs/INSTALL.md +++ b/docs/INSTALL.md @@ -7,7 +7,7 @@ Please check the following instructions to complete your installation. 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 looking for steps to build and +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. @@ -85,7 +85,10 @@ Then activate it by 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) +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 @@ -112,6 +115,14 @@ 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 diff --git a/docs/source/index.md b/docs/source/index.md index 68bf9743..044581bb 100644 --- a/docs/source/index.md +++ b/docs/source/index.md @@ -1,14 +1,14 @@ # MACS: Model-based Analysis for ChIP-Seq -![Status](https://img.shields.io/pypi/status/macs3.svg) ![License](https://img.shields.io/github/license/macs3-project/MACS) ![Programming languages](https://img.shields.io/github/languages/top/macs3-project/MACS) ![CI x64](https://github.com/macs3-project/MACS/workflows/MACS3%20CI%20x64/badge.svg) ![CI non x64](https://github.com/macs3-project/MACS/workflows/MACS3%20CI%20non%20x64/badge.svg) ![CI MacOS](https://github.com/macs3-project/MACS/workflows/MACS3%20CI%20Mac%20OS/badge.svg) +![Status](https://img.shields.io/pypi/status/macs3.svg) ![License](https://img.shields.io/github/license/macs3-project/MACS) ![Programming languages](https://img.shields.io/github/languages/top/macs3-project/MACS) ![CI x64](https://github.com/macs3-project/MACS/workflows/MACS3%20CI%20x64/badge.svg?branch=master) ![CI non x64](https://github.com/macs3-project/MACS/workflows/MACS3%20CI%20non%20x64/badge.svg?branch=master) ![CI Mac OS](https://github.com/macs3-project/MACS/actions/workflows/build-and-test-MACS3-macos.yml/badge.svg?branch=master) [![PyPI download](https://img.shields.io/pypi/dm/macs3?label=pypi%20downloads)](https://pypistats.org/packages/macs3) Latest Release: -* Github: [![Github Release](https://img.shields.io/github/v/release/macs3-project/MACS)](https://github.com/macs3-project/MACS/releases) -* PyPI: [![PyPI Release](https://img.shields.io/pypi/v/macs3.svg)![PyPI Python Version](https://img.shields.io/pypi/pyversions/MACS3)![PyPI Format](https://img.shields.io/pypi/format/macs3)](https://pypi.org/project/macs3/) -* Anaconda: [![Anaconda-Server Badge](https://anaconda.org/macs3/macs3/badges/version.svg)](https://anaconda.org/macs3/macs3) +* Github: [![Github Release](https://img.shields.io/github/v/release/macs3-project/MACS)](https://github.com/macs3-project/MACS/releases) +* PyPI: [![PyPI Release](https://img.shields.io/pypi/v/macs3.svg) +* Bioconda:[![Bioconda Badge](https://anaconda.org/bioconda/macs3/badges/version.svg)](https://anaconda.org/bioconda/macs3) * Debian Med: [![Debian Stable](https://img.shields.io/debian/v/macs/stable?label=debian%20stable)](https://packages.debian.org/stable/macs)[![Debian Unstable](https://img.shields.io/debian/v/macs/sid?label=debian%20sid)](https://packages.debian.org/sid/macs) ## Introduction From 2368754686081e31103c71491b3d86468c5bfc1a Mon Sep 17 00:00:00 2001 From: Tao Liu Date: Thu, 28 Mar 2024 17:02:40 -0400 Subject: [PATCH 02/18] update hmmratac --- ChangeLog | 15 ++++++++++++++- docs/hmmratac.md | 10 ++++++++++ 2 files changed, 24 insertions(+), 1 deletion(-) diff --git a/ChangeLog b/ChangeLog index 99f718c2..b48b7039 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,5 +1,18 @@ +2024-03-30 Tao Liu + MACS 3.0.2 (pending) + + * Features added + + 1) Introduce a new emission model for the `hmmratac` function. Now + users can choose the simpler Poisson emission `--hmm-type poisson` + instead of the default Gaussian emission. As a consequence, the + saved HMM model file in json will include the hmm-type information + as well. Note that in order to be compatible with the HMM model + file from previous version, if there is no hmm-type information in + the model file, the hmm-type will be assigned as gaussian. #635 + 2024-02-19 Tao Liu - MACS 3.0.1 + MACS 3.0.1 * Bugs fixed diff --git a/docs/hmmratac.md b/docs/hmmratac.md index 9e342115..6a91328b 100644 --- a/docs/hmmratac.md +++ b/docs/hmmratac.md @@ -106,6 +106,16 @@ output file names. DEFAULT: "NA" instructions in [Choices of cutoff values](#choices-of-cutoff-values) on how to decide the three crucial parameters. +### `--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 From b8a267566703a6097cd59b0ece7a7b8db8ab0f9d Mon Sep 17 00:00:00 2001 From: Tao Liu Date: Tue, 9 Apr 2024 17:23:58 -0400 Subject: [PATCH 03/18] add cutoff-analysis-steps to hmmratac --- MACS3/Commands/hmmratac_cmd.py | 20 +++++++------------- bin/macs3 | 4 +++- 2 files changed, 10 insertions(+), 14 deletions(-) diff --git a/MACS3/Commands/hmmratac_cmd.py b/MACS3/Commands/hmmratac_cmd.py index 85da05af..4842553b 100644 --- a/MACS3/Commands/hmmratac_cmd.py +++ b/MACS3/Commands/hmmratac_cmd.py @@ -1,4 +1,4 @@ -# Time-stamp: <2024-04-26 11:47:02 Tao Liu> +# Time-stamp: <2024-04-26 15:38:54 Tao Liu> """Description: Main HMMR command @@ -177,18 +177,13 @@ def run( args ): if options.pileup_short: options.info( f"# Pile up ONLY short fragments" ) fc_bdg = digested_atac_signals[ 0 ] - (sum_v, n_v, max_v, min_v, mean_v, std_v) = fc_bdg.summary() - #print(sum_v, n_v, max_v, min_v, mean_v, std_v) - options.info( f"# Convert pileup to fold-change over average signal" ) - fc_bdg.apply_func(lambda x: x/mean_v) else: options.info( f"# Pile up all fragments" ) fc_bdg = petrack.pileup_bdg( [1.0,], baseline_value = 0 ) - (sum_v, n_v, max_v, min_v, mean_v, std_v) = fc_bdg.summary() - options.info( f"# Convert pileup to fold-change over average signal" ) - fc_bdg.apply_func(lambda x: x/mean_v) - - + (sum_v, n_v, max_v, min_v, mean_v, std_v) = fc_bdg.summary() + options.info( f"# Convert pileup to fold-change over average signal" ) + fc_bdg.apply_func(lambda x: x/mean_v) + # if cutoff_analysis only, generate and save the report and quit if options.cutoff_analysis_only: # we will run cutoff analysis only and quit @@ -197,11 +192,10 @@ def run( args ): # Let MACS3 do the cutoff analysis to help decide the lower and upper cutoffs with open(cutoffanalysis_file, "w") as ofhd_cutoff: - ofhd_cutoff.write( fc_bdg.cutoff_analysis( min_length=minlen, max_gap=options.hmm_training_flanking, max_score = 100 ) ) + ofhd_cutoff.write( fc_bdg.cutoff_analysis( min_length=minlen, max_gap=options.hmm_training_flanking, max_score = 100, steps=options.cutoff_analysis_steps ) ) #raise Exception("Cutoff analysis only.") sys.exit(1) - - + ############################################# # 3. Define training set by peak calling ############################################# diff --git a/bin/macs3 b/bin/macs3 index 7b8c442a..23903c66 100644 --- a/bin/macs3 +++ b/bin/macs3 @@ -1,5 +1,5 @@ #!/usr/bin/env python -# Time-stamp: <2023-11-15 10:41:42 Tao Liu> +# Time-stamp: <2024-04-09 17:23:02 Tao Liu> """Description: MACS v3 main executable. @@ -908,6 +908,8 @@ plus an extra option for the HMM model file like `macs3 hmmratac group_output.add_argument( "--cutoff-analysis-only", dest = "cutoff_analysis_only", action = "store_true", help = "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` on how to decide the three crucial parameters", default = False ) + group_output.add_argument( "--cutoff-analysis-steps", dest="cutoff_analysis_steps", type = int, + help = "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. But please note, the final report won't necessarily include the same number of cutoff values as specified here since we won't output the cutoff that yield zero peak. DEFAULT: 100", default = 100 ) group_output.add_argument( "--save-digested", dest = "save_digested", action = "store_true", help = "Save the digested ATAC signals of short-, mono-, di-, and tri- signals in three BedGraph files with the names NAME_short.bdg, NAME_mono.bdg, NAME_di.bdg, and NAME_tri.bdg. DEFAULT: False", default = False ) From 4875baf97c80081317e00ab41754482a468729bc Mon Sep 17 00:00:00 2001 From: Tao Liu Date: Wed, 10 Apr 2024 01:09:28 -0400 Subject: [PATCH 04/18] cutoff-analysis-steps option for bdgpeakcall and hmmratac --- bin/macs3 | 7 ++++--- docs/bdgpeakcall.md | 15 ++++++++++++++- docs/hmmratac.md | 15 +++++++++++++++ 3 files changed, 33 insertions(+), 4 deletions(-) diff --git a/bin/macs3 b/bin/macs3 index 23903c66..8951ff75 100644 --- a/bin/macs3 +++ b/bin/macs3 @@ -1,5 +1,5 @@ #!/usr/bin/env python -# Time-stamp: <2024-04-09 17:23:02 Tao Liu> +# Time-stamp: <2024-04-10 01:08:20 Tao Liu> """Description: MACS v3 main executable. @@ -420,7 +420,7 @@ def add_bdgpeakcall_parser( subparsers ): argparser_bdgpeakcall.add_argument( "--cutoff-analysis", dest="cutoff_analysis", action="store_true", help = "While set, bdgpeakcall will analyze number or total length of peaks that can be called by different cutoff then output a summary table to help user decide a better cutoff. Note, minlen and maxgap may affect the results. DEFAULT: False", default = False ) argparser_bdgpeakcall.add_argument( "--cutoff-analysis-steps", dest="cutoff_analysis_steps", type = int, - help = "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. But please note, the final report won't necessarily include the same number of cutoff values as specified here since we won't output the cutoff that yield zero peak. DEFAULT: 100", default = 100 ) + help = "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 ) argparser_bdgpeakcall.add_argument("--no-trackline", dest="trackline", action="store_false", default=True, help="Tells MACS not to include trackline with bedGraph files. The trackline is used by UCSC for the options for display.") argparser_bdgpeakcall.add_argument( "--verbose", dest = "verbose", type = int, default = 2, @@ -909,7 +909,8 @@ plus an extra option for the HMM model file like `macs3 hmmratac help = "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` on how to decide the three crucial parameters", default = False ) group_output.add_argument( "--cutoff-analysis-steps", dest="cutoff_analysis_steps", type = int, - help = "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. But please note, the final report won't necessarily include the same number of cutoff values as specified here since we won't output the cutoff that yield zero peak. DEFAULT: 100", default = 100 ) + help = "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) 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", + default = 100 ) group_output.add_argument( "--save-digested", dest = "save_digested", action = "store_true", help = "Save the digested ATAC signals of short-, mono-, di-, and tri- signals in three BedGraph files with the names NAME_short.bdg, NAME_mono.bdg, NAME_di.bdg, and NAME_tri.bdg. DEFAULT: False", default = False ) diff --git a/docs/bdgpeakcall.md b/docs/bdgpeakcall.md index c28ed6ab..9ae78212 100644 --- a/docs/bdgpeakcall.md +++ b/docs/bdgpeakcall.md @@ -39,9 +39,22 @@ Here is a brief overview of the command line options for `bdgpeakcall`: 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. + 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 diff --git a/docs/hmmratac.md b/docs/hmmratac.md index 6a91328b..e6bc4d88 100644 --- a/docs/hmmratac.md +++ b/docs/hmmratac.md @@ -106,6 +106,21 @@ output file names. DEFAULT: "NA" 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 From 755adb0f3f3de1277478f7e586fccba433b0197f Mon Sep 17 00:00:00 2001 From: Tao Liu Date: Wed, 10 Apr 2024 01:14:44 -0400 Subject: [PATCH 05/18] fix a missing url --- README.md | 2 +- docs/source/index.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 6b742c57..ec98aef9 100644 --- a/README.md +++ b/README.md @@ -7,7 +7,7 @@ download](https://img.shields.io/pypi/dm/macs3?label=pypi%20downloads)](https:// Latest Release: * Github: [![Github Release](https://img.shields.io/github/v/release/macs3-project/MACS)](https://github.com/macs3-project/MACS/releases) -* PyPI: [![PyPI Release](https://img.shields.io/pypi/v/macs3.svg) +* PyPI: [![PyPI Release](https://img.shields.io/pypi/v/macs3.svg)](https://pypi.org/project/MACS3/) * Bioconda:[![Bioconda Badge](https://anaconda.org/bioconda/macs3/badges/version.svg)](https://anaconda.org/bioconda/macs3) * Debian Med: [![Debian Stable](https://img.shields.io/debian/v/macs/stable?label=debian%20stable)](https://packages.debian.org/stable/macs)[![Debian Unstable](https://img.shields.io/debian/v/macs/sid?label=debian%20sid)](https://packages.debian.org/sid/macs) diff --git a/docs/source/index.md b/docs/source/index.md index 044581bb..ba39bcdf 100644 --- a/docs/source/index.md +++ b/docs/source/index.md @@ -7,7 +7,7 @@ download](https://img.shields.io/pypi/dm/macs3?label=pypi%20downloads)](https:// Latest Release: * Github: [![Github Release](https://img.shields.io/github/v/release/macs3-project/MACS)](https://github.com/macs3-project/MACS/releases) -* PyPI: [![PyPI Release](https://img.shields.io/pypi/v/macs3.svg) +* PyPI: [![PyPI Release](https://img.shields.io/pypi/v/macs3.svg)](https://pypi.org/project/MACS3/) * Bioconda:[![Bioconda Badge](https://anaconda.org/bioconda/macs3/badges/version.svg)](https://anaconda.org/bioconda/macs3) * Debian Med: [![Debian Stable](https://img.shields.io/debian/v/macs/stable?label=debian%20stable)](https://packages.debian.org/stable/macs)[![Debian Unstable](https://img.shields.io/debian/v/macs/sid?label=debian%20sid)](https://packages.debian.org/sid/macs) From 75d82c8459333595166c074a8661ea1dcf1823dc Mon Sep 17 00:00:00 2001 From: Tao Liu Date: Wed, 10 Apr 2024 09:38:06 -0400 Subject: [PATCH 06/18] #637 -O3 replaces -Ofast --- setup.py | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/setup.py b/setup.py index e7028022..c15f468c 100644 --- a/setup.py +++ b/setup.py @@ -54,9 +54,7 @@ def main(): numpy_include_dir = [ numpy.get_include() ] # CFLAG - # I intend to use -Ofast, however if gcc version < 4.6, this option is unavailable so... - # should I care about old gcc compiler?... - extra_c_args = ["-w","-Ofast", "-g0"] # for C, -Ofast implies -O3 and -ffast-math + extra_c_args = ["-w","-O3", "-g0"] # CFLAG for fermi-lite related codes clang = False From 78ecce0c2df492890feed640d0b64118e0863880 Mon Sep 17 00:00:00 2001 From: Tao Liu Date: Sat, 13 Apr 2024 11:34:41 -0500 Subject: [PATCH 07/18] update docs --- ChangeLog | 13 ++++ README.md | 200 +----------------------------------------------------- 2 files changed, 15 insertions(+), 198 deletions(-) diff --git a/ChangeLog b/ChangeLog index b48b7039..fb0b1f0f 100644 --- a/ChangeLog +++ b/ChangeLog @@ -11,6 +11,19 @@ file from previous version, if there is no hmm-type information in the model file, the hmm-type will be assigned as gaussian. #635 + 2) Add `--cutoff-analysis-steps` for `hmmratac` so that we can + have finer resolution of the cutoff analysis report. #636 + + * Bugs fixed + + 1) Use `-O3` instead of `-Ofast` for compatibility. #637 + + * Documentation + + 1) Update instruction to install macs3 through conda/bioconda + + 2) + 2024-02-19 Tao Liu MACS 3.0.1 diff --git a/README.md b/README.md index ec98aef9..b71569c6 100644 --- a/README.md +++ b/README.md @@ -30,198 +30,8 @@ applied to any "DNA enrichment assays" if the question to be asked is simply: *where we can find significant reads coverage than the random background*. -## Changes for MACS (3.0.1) - -*Bugs fixed* - -1) Fixed a bug that the `hmmatac` can't correctly save the digested - signal - files. [#605](https://github.com/macs3-project/MACS/issues/605) - [#611](https://github.com/macs3-project/MACS/pull/611) - -2) Applied a patch to remove cython requirement from the installed - system. (it's needed for building the - package). [#606](https://github.com/macs3-project/MACS/issues/606) - [#612](https://github.com/macs3-project/MACS/pull/612) - -3) Relax the testing script while comparing the peaks called from - current codes and the standard peaks. To implement this, we added - 'intersection' function to 'Regions' class to find the - intersecting regions of two Regions object (similar to PeakIO but - only recording chromosome, start and end positions). And we - updated the unit test 'test_Region.py' then implemented a script - 'jaccard.py' to compute the Jaccard Index of two peak files. If - the JI > 0.99 we would think the peaks called and the standard - peaks are similar. This is to avoid the problem caused by - different Numpy/SciPy/sci-kit learn libraries, when certain peak - coordinates may have 10bps - difference. [#615](https://github.com/macs3-project/MACS/issues/615) - [#619](https://github.com/macs3-project/MACS/pull/619) - -4) Due to [the changes in scikit-learn - 1.3.0](https://scikit-learn.org/1.3/whats_new/v1.3.html), the way - hmmlearn 0.3 uses Kmeans will end up with inconsistent results - between sklearn <1.3 and sklearn >=1.3. Therefore, we patched the - class hmm.GaussianHMM and adjusted the standard output from - `hmmratac` subcommand. The change is based on [hmmlearn - PR#545](https://github.com/hmmlearn/hmmlearn/pull/545). The idea - is to do the random seeding of KMeans 10 times. Now the `hmmratac` - results should be more consistent (at least - JI>0.99). [#615](https://github.com/macs3-project/MACS/issues/615) - [#620](https://github.com/macs3-project/MACS/pull/620) - -*Other* - -1) We added some dependencies to MACS3. `hmmratc` subcommand needs - `hmmlearn` library, `hmmlearn` needs `scikit-learn` and - `scikit-learn` needs `scipy`. Since major releases have happened - for both`scipy` and `scikit-learn`, we have to set specific - version requirements for them in order to make sure the output - results from `hmmratac` are consistent. - -2) We updated our documentation website using - Sphinx. https://macs3-project.github.io/MACS/ - -## Changes for MACS (3.0.0) - -1) Call variants in peak regions directly from BAM files. The - function was originally developed under code name SAPPER. Now - SAPPER has been merged into MACS as the `callvar` command. It can - be used to call SNVs and small INDELs directly from alignment - files for ChIP-seq or ATAC-seq. We call `fermi-lite` to assemble - the DNA sequence at the enriched genomic regions (binding sites or - accessible DNA) and to refine the alignment when necessary. We - added `simde` as a submodule in order to support fermi-lite - library under non-x64 architectures. - -2) HMMRATAC module is added as subcommand `hmmratac`. HMMRATAC is a - dedicated software to analyze 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 again - using Hidden Markov Model to consider three hidden states: open - region, nucleosomal region, and background region. The orginal - paper was published in 2019 written in JAVA, by Evan Tarbell. We - implemented it in Python/Cython and optimize the whole process - using existing MACS functions and hmmlearn. Now it can run much - faster than the original JAVA version. Note: evaluation of the - peak calling results is still underway. - -3) Speed/memory optimization. Use the cykhash to replace python - dictionary. Use buffer (10MB) to read and parse input file (not - available for BAM file parser). And many optimization tweaks. We - added memory monitoring to the runtime messages. - -4) R wrappers for MACS -- MACSr for bioconductor. - -5) Code cleanup. Reorganize source codes. - -6) Unit testing. - -7) Switch to Github Action for CI, support multi-arch testing - including x64, armv7, aarch64, s390x and ppc64le. We also test on - Mac OS 12. - -8) MACS tag-shifting model has been refined. Now it will use a naive - peak calling approach to find ALL possible paired peaks at + and - - strand, then use all of them to calculate the - cross-correlation. (a related bug has been fix - [#442](https://github.com/macs3-project/MACS/issues/442)) - -9) BAI index and random access to BAM file now is - supported. [#449](https://github.com/macs3-project/MACS/issues/449). - -10) Support of Python > 3.10 [#498](https://github.com/macs3-project/MACS/issues/498) - -11) The effective genome size parameters have been updated - according to deeptools. [#508](https://github.com/macs3-project/MACS/issues/508) - -12) Multiple updates regarding dependencies, anaconda built, CI/CD - process. - -13) Cython 3 is supported. - -14) Documentations for each subcommand can be found under /docs - -*Other* - -1) Missing header line while no peaks can be called -[#501](https://github.com/macs3-project/MACS/issues/501) -[#502](https://github.com/macs3-project/MACS/issues/502) - -2) Note: different numpy, scipy, sklearn may give slightly - different results for hmmratac results. The current standard - results for automated testing in `/test` directory are from Numpy - 1.25.1, Scipy 1.11.1, and sklearn 1.3.0. - -## Install - -The common way to install MACS is through -[PYPI](https://pypi.org/project/macs3/)). Please check the -[INSTALL](docs/INSTALL.md) document for detail. - -MACS3 has been tested using GitHub Actions for every push and PR in -the following architectures: - - * x86_64 (Ubuntu 22, Python 3.9, 3.10, 3.11, 3.12) - * aarch64 (Ubuntu 22, Python 3.10) - * armv7 (Ubuntu 22, Python 3.10) - * ppc64le (Ubuntu 22, Python 3.10) - * s390x (Ubuntu 22, Python 3.10) - * Apple chips (Mac OS 13, Python 3.9, 3.10, 3.11, 3.12) - -In general, you can install through PyPI as `pip install macs3`. To -use virtual environment is highly recommended. Or you can install -after unzipping the released package downloaded from Github, then use -`pip install .` command. Please note that, we haven't tested -installation on any Windows OS, so currently only Linux and Mac OS -systems are supported. Also, for aarch64, armv7, ppc64le and s390x, -due to some unknown reason potentially related to the scientific -calculation libraries MACS3 depends on, such as Numpy, Scipy, -hmm-learn, scikit-learn, the results from `hmmratac` subcommand may -not be consistent with the results from x86 or Apple chips. Please be -aware. - -## Usage - -Example for regular peak calling on TF ChIP-seq: - -`macs3 callpeak -t ChIP.bam -c Control.bam -f BAM -g hs -n test -B -q 0.01` - -Example for broad peak calling on Histone Mark ChIP-seq: - -`macs3 callpeak -t ChIP.bam -c Control.bam --broad -g hs --broad-cutoff 0.1` - -Example for peak calling on ATAC-seq (paired-end mode): - -`macs3 callpeak -f BAMPE -t ATAC.bam -g hs -n test -B -q 0.01` - -There are currently 14 functions available in MACS3 serving as -sub-commands. Please click on the link to see the detail description -of the subcommands. - -Subcommand | Description ------------|---------- -[`callpeak`](docs/callpeak.md) | Main MACS3 Function to call peaks from alignment results. -[`bdgpeakcall`](docs/bdgpeakcall.md) | Call peaks from bedGraph file. -[`bdgbroadcall`](docs/bdgbroadcall.md) | Call nested broad peaks from bedGraph file. -[`bdgcmp`](docs/bdgcmp.md) | Comparing two signal tracks in bedGraph format. -[`bdgopt`](docs/bdgopt.md) | Operate the score column of bedGraph file. -[`cmbreps`](docs/cmbreps.md) | Combine bedGraph files of scores from replicates. -[`bdgdiff`](docs/bdgdiff.md) | Differential peak detection based on paired four bedGraph files. -[`filterdup`](docs/filterdup.md) | Remove duplicate reads, then save in BED/BEDPE format file. -[`predictd`](docs/predictd.md) | Predict d or fragment size from alignment results. In case of PE data, report the average insertion/fragment size from all pairs. -[`pileup`](docs/pileup.md) | Pileup aligned reads (single-end) or fragments (paired-end) -[`randsample`](docs/randsample.md) | Randomly choose a number/percentage of total reads, then save in BED/BEDPE format file. -[`refinepeak`](docs/refinepeak.md) | Take raw reads alignment, refine peak summits. -[`callvar`](docs/callvar.md) | Call variants in given peak regions from the alignment BAM files. -[`hmmratac`](docs/hmmratac.md) | Dedicated peak calling based on Hidden Markov Model for ATAC-seq data. - -For advanced usage, for example, to run `macs3` in a modular way, -please read the [advanced usage](docs/Advanced_Step-by-step_Peak_Calling.md). There is a -[Q&A](docs/qa.md) document where we collected some common questions -from users. +Please find MACS3 documentations through [MACS3 +website](https://macs3-project.github.io/MACS/). ## Contribute @@ -245,9 +55,3 @@ contributions over the years. 2008: [Model-based Analysis of ChIP-Seq (MACS)](https://genomebiology.biomedcentral.com/articles/10.1186/gb-2008-9-9-r137) -## Other useful links - - * [Cistrome](http://cistrome.org/) - * [bedTools](http://code.google.com/p/bedtools/) - * [UCSC toolkits](http://hgdownload.cse.ucsc.edu/admin/exe/) - * [deepTools](https://github.com/deeptools/deepTools/) From 1d0160a113716ee4c38fa7c9c00be066cc8d6a9e Mon Sep 17 00:00:00 2001 From: Tao Liu Date: Sat, 13 Apr 2024 12:01:19 -0500 Subject: [PATCH 08/18] reorg md files --- docs/Advanced_Step-by-step_Peak_Calling.md | 291 ----------- docs/INSTALL.md | 153 ------ docs/bdgbroadcall.md | 79 --- docs/bdgcmp.md | 92 ---- docs/bdgdiff.md | 207 -------- docs/bdgopt.md | 80 --- docs/bdgpeakcall.md | 122 ----- docs/callpeak.md | 477 ----------------- docs/callvar.md | 224 -------- docs/callvar_algorithm.jpeg | Bin 163926 -> 0 bytes docs/cmbreps.md | 64 --- docs/filterdup.md | 97 ---- docs/hmmratac.md | 267 ---------- docs/pileup.md | 74 --- docs/pileup.png | Bin 34709 -> 0 bytes docs/predictd.md | 89 ---- docs/qa.md | 1 - docs/randsample.md | 84 --- docs/refinepeak.md | 66 --- .../Advanced_Step-by-step_Peak_Calling.md | 292 ++++++++++- docs/source/docs/INSTALL.md | 154 +++++- 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/callpeak.md | 478 +++++++++++++++++- docs/source/docs/callvar.md | 225 ++++++++- docs/source/docs/callvar_algorithm.jpeg | Bin 36 -> 163926 bytes docs/source/docs/cmbreps.md | 65 ++- docs/source/docs/filterdup.md | 98 +++- docs/source/docs/hmmratac.md | 268 +++++++++- docs/source/docs/pileup.md | 75 ++- docs/source/docs/pileup.png | Bin 24 -> 34709 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/tutorial.md | 1 - 40 files changed, 2468 insertions(+), 2486 deletions(-) delete mode 100644 docs/Advanced_Step-by-step_Peak_Calling.md delete mode 100644 docs/INSTALL.md delete mode 100644 docs/bdgbroadcall.md delete mode 100644 docs/bdgcmp.md delete mode 100644 docs/bdgdiff.md delete mode 100644 docs/bdgopt.md delete mode 100644 docs/bdgpeakcall.md delete mode 100644 docs/callpeak.md delete mode 100644 docs/callvar.md delete mode 100644 docs/callvar_algorithm.jpeg delete mode 100644 docs/cmbreps.md delete mode 100644 docs/filterdup.md delete mode 100644 docs/hmmratac.md delete mode 100644 docs/pileup.md delete mode 100644 docs/pileup.png delete mode 100644 docs/predictd.md delete mode 100644 docs/qa.md delete mode 100644 docs/randsample.md delete mode 100644 docs/refinepeak.md mode change 120000 => 100644 docs/source/docs/Advanced_Step-by-step_Peak_Calling.md mode change 120000 => 100644 docs/source/docs/INSTALL.md mode change 120000 => 100644 docs/source/docs/bdgbroadcall.md mode change 120000 => 100644 docs/source/docs/bdgcmp.md mode change 120000 => 100644 docs/source/docs/bdgdiff.md mode change 120000 => 100644 docs/source/docs/bdgopt.md mode change 120000 => 100644 docs/source/docs/bdgpeakcall.md mode change 120000 => 100644 docs/source/docs/callpeak.md mode change 120000 => 100644 docs/source/docs/callvar.md mode change 120000 => 100644 docs/source/docs/callvar_algorithm.jpeg mode change 120000 => 100644 docs/source/docs/cmbreps.md mode change 120000 => 100644 docs/source/docs/filterdup.md mode change 120000 => 100644 docs/source/docs/hmmratac.md mode change 120000 => 100644 docs/source/docs/pileup.md mode change 120000 => 100644 docs/source/docs/pileup.png mode change 120000 => 100644 docs/source/docs/predictd.md mode change 120000 => 100644 docs/source/docs/qa.md mode change 120000 => 100644 docs/source/docs/randsample.md mode change 120000 => 100644 docs/source/docs/refinepeak.md mode change 120000 => 100644 docs/source/docs/tutorial.md delete mode 100644 docs/tutorial.md diff --git a/docs/Advanced_Step-by-step_Peak_Calling.md b/docs/Advanced_Step-by-step_Peak_Calling.md deleted file mode 100644 index 899f808e..00000000 --- a/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/INSTALL.md b/docs/INSTALL.md deleted file mode 100644 index 37407794..00000000 --- a/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/bdgbroadcall.md b/docs/bdgbroadcall.md deleted file mode 100644 index 805ba213..00000000 --- a/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/bdgcmp.md b/docs/bdgcmp.md deleted file mode 100644 index 099f9292..00000000 --- a/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/bdgdiff.md b/docs/bdgdiff.md deleted file mode 100644 index dd221077..00000000 --- a/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/bdgopt.md b/docs/bdgopt.md deleted file mode 100644 index 8bd7e0bf..00000000 --- a/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/bdgpeakcall.md b/docs/bdgpeakcall.md deleted file mode 100644 index 9ae78212..00000000 --- a/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/callpeak.md b/docs/callpeak.md deleted file mode 100644 index 5ff6fb6d..00000000 --- a/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/callvar.md b/docs/callvar.md deleted file mode 100644 index f27bc862..00000000 --- a/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/callvar_algorithm.jpeg b/docs/callvar_algorithm.jpeg deleted file mode 100644 index f44a57cd2ed88c91df44dc4159786507e607c3a5..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 163926 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

D6E^Rq;j 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�o^g#(vUbvS$H=IJ2^ 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 Z`21U&kAFGt^FNuP>@Vm2SJ-|Q{wIW?F_QoQ diff --git a/docs/cmbreps.md b/docs/cmbreps.md deleted file mode 100644 index fa5334eb..00000000 --- a/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/filterdup.md b/docs/filterdup.md deleted file mode 100644 index 4d28db6e..00000000 --- a/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/hmmratac.md b/docs/hmmratac.md deleted file mode 100644 index e6bc4d88..00000000 --- a/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/pileup.md b/docs/pileup.md deleted file mode 100644 index 65634390..00000000 --- a/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/pileup.png b/docs/pileup.png deleted file mode 100644 index bdabcc38aa3c3b1ce070a4e06d324abfaca3ad96..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 34709 zcmeFYWmFv9x-Qx@?ruSYg+TB?;}YBh!X3bgeeD!%IVJb?}m}oE1Kp+sNtc=8a5C|Rz1cLj5f&`p7 z(6$H%fiOfZ#l=-*#l@*r9PQ05ZOlL*nXp7nWUUWBi86KLVnjdX$fLHQ(s27F;OKz< zNLJ#;fpUUKP?%huRlDlGqRdaIog}ni-BMAa>-+{$eH4tMo2Y6vgiag~{6T zvLIz|5zdk*8E)@;Z>dFWep25l1+v*K2hJ~5P}b^P0>(k&ZHN4)tUuRl^bl#ztsXRu zM1{|vN}b2p?IAT6-9NMte+wJyd?e^i!|}yA{RqR!OHh#g6tGOmy|q(gH0FoZt0bso z#M}D?2N~UohL!-T(@dR$$)Wdh@2wb|0HujgDDl}v;BNw+^j?oDG{aBg%_)6qr@Oo+ zsfI-rcX5XZ`R|@w7_!PH2GqWCZpKsRi`u9%%0vWd5t~}~jQSZZ13NdsPwPhO8_iId#{8!F{WqM~_DEIMKE~fn-ehWl zh`;MmDH9V)3=D7fey!#;o;-Iy-KGXtic)98qn27yV}FDblQuM^YK^}_fXBiK#OOrE zLNos)5mzdWQt>$(X(U8=~z*jiC0S+l_~uo=(U76VW$E{nZzrPHtYp1bTuLf&yYOJieD;YU2fl`uD1suul>}I=w&J z3xW+Ej9vOk8+RuJ+n4Y&arjZOQRh%sf^_2%`+jHTlA|~0_*BvmTZ-&}8v@eo+(F0i zGdY~)fn*@$Wx`wI-#!yHWFNJ|8-Hl$Jbiy?AiY0*OW^wP6{p-R{aw7R4`q>6!9GtZ z&FE$HP3%A#&o}#7hw<@8ZIO>z$V;bLELD>8aHW_6!5ITlCXs$o8J%gBu7@cE*cIgi z)ic~%EE+`0Jkz-MJ!=#3iRPSZMPo&Cf4;U>_=zaqMj@37PC8dn)7JQn1sNg;XRvJX zM|~F%;A;UeBppcgklohz|G=?{int>S)1th4SBQc+DXoAb z-%I&fiX@Z`FGzyAN`^Bo{3G={iGUG_9a^(Nx$k%j5z{nxF+GE?w*-HMEx)6rZX2}T z!Vk}3DkQQB(#gqFK^l_inRIuiN%L0{`#OQR_r4ZfCgzrdx%c`njVHyClwmeJNoN8F z#R!2@CkYAq*Y5X~&I%Eu{c=@~rAQ?MX&X-M;V!1$^U~i!ryTf?L7EPXnSM@Zudi*O zs0Lvton)sP_e_tVlYtK0LIm*up{}o;3=y;+aq{uxP_~0?gT#Zl9M~>#R&m25C~~|a?J9o2h+FmWd8#F*Jw*I1>P@)%DUs)U3@ zg@kX30g3Mug5>(-w&es8qnPzoJ&XUQmMYcLdBx@p3Z6TkbDnEBa^2uHh1{p+idE%b ztNebgo#2sxCMUFwvCX<2SzTS7T3z56Q7!6G?ihS-u zMw73|QGOdUQLZlc_QQul#OWW?I{TLU-uuYvX~lU=x`_q+(sgomVwd6j^4!&FKVE#W zjnj$MX3$I@?Y4n^O{aT-dP7-p&W<)!o8DT=8?cW!Z5|OAhF}HfsnIv z@}P0xk(P1s+fG}QnjYGJGizPEZv0$KAm;9W3 zys6QAiu|n6(owvT@KIRG3Rgi2*T~eUW_m-)m2QewL|uxds>SD}IGdl9BeiR4@eqBH)!E3+|}7ORiNgryMjE`&b>If_3DH>xixGKx)FJ3@}M&O~jg&|b+- ziBCy4<2YiLoPwv>-T7i~Zp?K|ZrwW8Qj_M?-ROtIvG42ycxV#bh8ZY%4iBYsnbGs z(~a7jtPEsy=yB=qWnPE9UV4wzj~r>p)ou~66cmRFVbD?j#&dR07bwdYAEl^~K9ULr zEH*8nnd=h$RrrSNo6g=H79Jig1oFx9c{wIJesID@=MG-zo)z3|we-lK@lp*d^a`I# z;QnyixAEKdM&_~iJ|E0-O}oZg6?;$Pp|Yo|rG9N}^?MqA>TN!1L7j3#db|7WRPK82 zn)y0cBbSbO+SoV9Mc131($SjO1r2QQA-IvE-H{dp&t= zX6+??T-C|iF_V>Z7egj4<_b+jwWA`QQUkpQA0hjPM9fFBeaH*jH%r%+@kUdlqc79R ztV*qh8gLp2>^!QuKU*)^N32;jklHXW!CYD#yso0=Daz_7>*@qB-B?S+59nOlS{M$S zTLm24KD3EH>jOfJXa6yH_#){BZ*hocxqefsBTw|uEZ&hDKL`-S-JIL zt;@@N`4`uO9n1ygNCrY)k={qYF9#1YAb57mhiMZt-tlf13uWJQE9{6@AE6e<`rRwP zy!Nk#PRLd(ZhBzRLMz8B1C$8DpL|KKPRD4E^N6D_sC@rup9bB2zc2bZwP-Om9tA_X zGVl?8^cY8<{5tMU?`w6h{qSpNyQ|~=$?Ak^ZtX(u-s-{IoD#EB#1@T7m- zGJYa2vgbR07JF88^x;=QK~{m!OYfpsa51(X!w zW?Hi5ii#j6;1~sj0QUlf2pquyn=l;Ne;-T1F@oU#bsh`?g;;_R{_7qkVE_Dy0k-Eh z|K7vLeE}f@zwm&~JsbSL?}o?8hX3Eka9@CHAh8ePva-PbgQ=sLnVr)od*@i}Zhqhd zs)LNS69_~^|GdG;zNb3{oJB=_JH8r)M<41G; z_YzY7)g1UGMDxkn*@2&p&CSh?)s2hQ-qC`MgO87ojh&N?lamFwgT=|i&e_$p{r9thrh?CB`Bg04&1|$KENuaq0euK_@v#g3>;C`8mH+ASKU!-2PfG~z+y89& zA6Nd*mg-Jsj^g&VK$p(K|1(|x)%ZUz{#Qdmw&yqh4@vx6%>OzI$XOUoknO+cOc)JY zFP#vWMsiCDWi?tN$SgBnpz15L0u9J8T0AfWFHoUzJJ| zMF}xPRTVl|W~i#FDh`k;%lG0%_TvdK%zGh5($^b>Ntv=4g|$gYys1JbLO=~b6vz&( ze7aaTv4@EW2(-AJw0ULiuHHd+E(0=FGBVCHyxV<;Q#!-ghRuD;>!3T{O8vZKN}QFMu;Ex&!?#Ptqc6KHC;?P2r+cIFeT<6?PdJH z2y1Y7)c^VQUq%21Ak`Q2pS=Ue1k~49{}?I=b&Ek1jt0WSK=+^R;qbCSU2gvzrwla& z7=Du~$IE}dEeH{%9sd95rwLWXZ!j_(Rra5cU=%&2_{TWm@CFtAz!G+93Nrr?6rCts zz{x-55hH2`4Bs)&R7Vqt#Xq$IBT_ z`8(KAk1qwkbLek$w${owT9u+PI|Ed{5swSIVmLAbQ50sWW=XM$ng-hStDXnn=($Ky zr;+_DIv#ay|Nf!1Z@)3u%GplRWhFr2S%Y3^A$B~#bekS;56p%VUZ0N%oD5o5v@uY5 z|5Z&e520|4k*4&ZOP(!}Hd>HVV_Pf`>8JPA3USL9w-)JW$|`Hv&+?XIrmJPAXz#Gkzzgz-0=7xE z_mL+SL55lhR800N!#NIm`={W1`h)V%5Go%MWtIMg`XxJNWx+EEQe}3_8vM>XmnlWa z&$5P9raY<0IJ=eR8U1+Qv#*AOjh{D7F1z>1G#HZf9DnZJLe`-8^=ADMq{h0!H(T+0 zlr&yPb;--ni_t1;K|rLRd;oh->xfxJ6u6NP zM&A!O&PC93$Jy}<62SXAgAJi)!S`FQL}cmw{6L$NwGM|>14EL;`gFv44*nQqJa1S? zD;jXY?3~A|ZC<%`B-uSO9h5y}_N^})mL0#2q;g3cVF)>_caB&^k@LNe5;$(uN~4Y9 zeaG6g6*teF2}FgrB0z_uYXdfb>4+lvpS0g8W#?{v3B=-O{5!p60NGWszugsiB7Kp2 zTs_RX!x?Rx08(4xciAVf7FsP?sIeF*=RW_roovYJdpnh7qUcAB=^~5-48C3x(4(b& z`}!mVna-D>=ynQLr#LrLQ3}IyT>FcPy4A=p zZmlB+chY)cGUxsdOgC{4gtxc8R5igs+@VK#Q$KIQ>2|!V#WYgeJ!8fV zM`>%<@!;BYcigfags&7+R=+6M{`BZ|bGPFN6}6)?xv`}5=u1%iuNUHjm1rF0&a z(xpY~3YLTNmU0_F!K(L*OBjCLv5I={R1Hv~>pS_Jb|Hhkp@+8qqaEv{C^us2CFIHV z?L5Y77=_)Pd4#PnBWldRWy6PkP1HL)8@(^J^YTW2ek2psT4%V-#vau#DJ|An?^=Jk zdV!H-oQ;uZ=#I4i>xX>dyV@nYmhEajzx@}jbX_smhc)9#k&sobo$)L-$f|o@XC>v4 z=mRx^Xx+dHRaY6ot;<;-akRdH(rKvtTNpQ~t8YZU(3M2nioxNoHSJ>Tysy z99qJK`@K=Rg}h)GYg~tlandemwmv(l7Vo^MTCJ~Ez3i|9ASJ0+OxI=vDC z&mDm|Z6v7T`{<8#4DTZLV#lypaZcY&{}ga=i2R+fSwgeoNEtP5{Yg}3l>FKw{+Mp|EcG7$<1!p75JrJkL%l>q> z+jod9-U6~_r*%5R|$n_Hr`7~O8N5TS^3 zX{rtV+m#a^Vtp=K4r%T^ECctAV2MX%kq2i#x3h!~N~q4*Ax6Q38lmSZy4ez*cLBwR zl9q~m?rw6ya<>Ya&H=kwzQRzd8CfyED{;iyLa6>_Xt=uDNY`ex2xYa@+NM4BiGNXE zb86%-n)mYURRMq{C@O%sNHCt0uZetAqxFwSWIHJgqDG>jZ}*>s`xPvv@jX&n9eT5m z8af_qX)uujQTV@7=>Y@tA6tF(YyKvsajdw1s6pA;Tu9~NPD}XiutquC3lG5xA)P-I z;<0)Ccz1&QWAS_crvF&=z);l%`x!E&JGH3ysK?^x0SdR;blk6|oe^S!2#gnkND0=Z zRZ`hpCzISx*ny__3<@bRjrPAb3cUglO3LbW%wK$;N<@n{bC&23LkXfb-~ID7FG5gE zQ5L)xlj#v);sV1s|hVadihpjE+TZ%A&bAj&V34EUz3( zs_(Z@?Mc(w-ARXt+*cWvn|`$4sHkr_00*YH++_0taA3kZGU_T^Hu-d3GY=aFR1$!7Jj_ z&34C|q5gkcPTI*z;FYF@ENI$_Q+t0I_pgi%N1FCi1a`c)t&*v zW%$4nb>6Vsg9_w_yDMzZtK*EqSBuET^9U%rS_|^{;HQhMrvG;vLp#&`<$3Zys({?H}Zt{4%tnkG|%s<;4So+!Hu9H4JFR0>{?Z4=R z5G{Bv6Vv}*h#%P=M>V0z{U4L4dwdiG#@%;1@Ib`t@EkygUl^ia2 zQ22s_o!QM5F~@P&>nVFInF#7Z+yyBUGkK? zc3CuJBdxW6-{3Y(pElx)rGyt~f#SPep3SrsX@;H^MJ;&V4vyy@*F?W*TJ0L_T?MoOnnhC6hDb``t_y#2{d+?P44K1iMDDz!hu^DD~o$BjO} z;x|8Kzs?bUb2kq5zHF+RofL1L;*UFrd)pe`M9mqvSxS@UX8h?2t8$I!422MN0MB37sKv-{=6DU^=b*5>vr$^#J;(668kBTGArXWnapL=I> z(srdZO~@nLUI`@s^uOMXzG0aTx7YD#RRWK`1Jb0LzjRAtU^*2JxGa!ATn$@__Pl8n zU%#6`Yks;lJrYNG%WQ3ku{o@sN#pQrV@TcxIS-6sqJ=l_tSL=oxdGy({g^NW%t0a zg|WrikKF=~x#B+Q7P)m6(ERXv->4m8P^8zt{jJ4&N0-G3Gf$Bos)P&$*UB0)w=?)s z%4TZ=)&8g1OtY4MmENbLiw9DUtGmV}pa*LbtOCSFL>FWQ%Rt+B3`;Xiyx&oAPPb1SyD49|UJn~S z#>oU)WXmBDzATmM)Wt<8$Z%Wbo4yM1B!wCHA+u;IVq7hAP9dPoyEj^%G;U(Gc&d`S zve+%ssHIS=G~Jk^;>-(lDW24j`ft>wmnVQWxCpL};8mToZV*sP9k1UtfhEeWZ}HSdcCqI1bPl9pup=1wY>L*$%aUKLZuYtNpMx%ENWtAA<*2Gh+k2!?@HipcIgJ z_!Wfd9_*MJXj|8%x%LLGdpDPuGIm)d3Nx1qIp>Bf<6jSuPuWmca-;*wUT)0W29bMzCnJ1)WmQKL@ez;^R~Wm=}n*PNM~ls~=BF zQ)PU5Kk2>0mD|4))b7{zX4%!)h3)@c$#LQ4$s6IZzV(Q!{OBs^_V3cv@e>NxMXnJE z^2pbN10(f2Y=lFRF-UNXVlaqH*fTRA_L)C9MqhKWKyk zcsw=*l8FVlz;3f7ZH7r#6nd$)VI@PR<3(S;KbLccC*C6s9tLS-npp?$8!JZ7L0c@- zO22x>%P+okF6m19?)aKFI_bW zEGV>586}FkhqOU0wJOZ*mfL6isBh7qNB=9{1{oN=B*LoillMt>p8Z-o;dV&KGMpe1 zmlm!Jdb_{X)$s~EhDOy=<#-CQN4IwoS-xUAQE}NkJfr(Ymk~v|@)<@eM2y~YzS1~n zSi2BYECZ#4(vnHBou>vc8&i0$QaI3%M5D#y_kDrLgXKDx)t5Ej zy$w@jd&o5p*2Sp#CZA2|PEz_#6md&Pi{&+}Ruh~N!e#q5YV5k2X3;y;iTRU&({=ANL*|uV! zGZpmIzao62PUlRKB?cmsEsFv;sko?*T!52eqK(;MAjk}4_c}OM(JLl!e^_wn!Nd+>$yUkQ@>&z4L@qj{f|+FzKa6k9q_uM z9OI&j)??rJ!g9m+xjr7&;Bsy+NzZXtHSOYaDh6Bk&25d-qP}H*p6JCI8)9Ihncxcl z8dcWr<$h&AQZ=72j;f^H18PooRKj23FA+{Ctbg3tXLY0jPV-PHVy@r%|J$%j;Zk z8?tJaj)l`*GkH4eF6uUMa@zqEruOjN=FM1!fY(wm)W|u~Z65#|&@VcpX0$K^H=6aM zD5QPMYJbW3w>0T;dz(W*-RKCqEeen*ex`M`ZNba=V*+hX^>KfYg_aVH;#+?X(3K&uBjo$=49IbpB{Yf=3mR}|q zRaPHX4}ZB49YyL!D}PCaf_7|f>Hb(;QZ7g0N7J_8hjqJ4vYewdh9+DrYM-`kDaptD(oese4~)Jg?Sm2F2ThKsPM>G z7zbgn(&qhQu?D*pFosfE|K>(SXtRWd(^fq1e zzkL~Xu0VD~>OS&mlmC~oN~G_ea_#4b%em-t2yW@LD8-0bbp8ChOxdj66gR)GkA8C6 zMTA_nh!LGQR!W~l9ydJndhW0^%tI_I;o+CX`B6S!>uTH9&AjV+;T>XeMtN<1%Y4L@ zJo+jNiU%M~l&d}=yYz*}FSExdkZMOC1pGPb$-;LIcE+9XK52lDCfFZvxc<#7)N;a6 zRDQKXU|=c@#qyDW(BRJ;v9@S5lU426lgkfQDSQ0#b;3l8!$|z)Q z-7D`6<6QN=(w`)~>Am!9%np<#74c~;wDTI2Lwq;c)mHc-x{&$3s_}RAk|L>=mmf~m zjpdxpU4i|tDK-Sqs!g=D2RV`(`?#lU>6NNX%6d43F7R4Hj`vE+M zZtN3^M3U;G62afXb(Y>hnXLq=X#AM~?@$P)q@sUDG(2gtnM88;l^g+VA$aE3g85`3 zoN9W+w3P{{xP|v?@m=q)!p}{Gtloz&lyx#YUxtv=H1iWOYeC}h)z!oGH)YKb1{*l- zpy7b#{hROr67FoKH=NMx(?V`5Bj(~<+>8QAsVH*N^7kos#g4Q%Qfh<)dcUg@QOKPq z#B!}{s(!r|?R8LddDpJKvDst$T)FWq-`Ma2M(u>F;#QfP?k*Yme)CYJkG44mPc^w9 zx8=RG+e}75D-gaX`Dn|eMTJ2BbA13m@@4 zU<($^JaUnoCf{+u&Ay?XjH_4#)HW|>`hGU>`#_tI0NQEN^)8d;d3c=QQx*8=xAjhK zqmVVd>EOb@2Xkz*Ix9c5l!R|Ss?McPy0~)&5Hq?=k?Na%cR{sj+D^)4wKPrilbiCn zJ0foBj~_ybu{T@3CIIr&|02^AB|u0Gr*F7?AMdqFoX0~aRtjzhlV5+xA8c6jA#15f zZ~o~rr~j&XT{Spx^vS-4JF~aXyj@<4OkKHnF zDu?M8qYK`ZBFM5c=Dyr~kh~i%YpI~Q8iv1ijrmUiJ!EV)b^i1iD#@|5^v=)Qrt z00grj^)d~^gxKg`;4_}*Q6r1GtQNkzNPBfxHaL4B@UZvgZ- z?NR6nnDMQSrw9A_9fLN{pFjZBeW51y`V`{2=6&_^VqAnxQ{N@g`Czsz`y2iJ&c+Gx zQ?u(46Tpp_8G8_C;C8@E;*Ta%`J6odEfD!h^YsnQZibtI`^XjDhna9dH*{jn+UZn~ z`~l2=xc%;!3=RHhsUdmJz)SHNgi3?|^>pmkf$lqTBtfk2982!~ck=we@JZ*mX*ctf z$Y*aHph;vZE2khP_bYB|n8+OXuapSx$wYjhyx9=jCIGB3J6-SEsg2p(`WbIlkl~7# zV2gYo^KdinThGRA0|kgM$Gf8j^e8~yPu;#EkJow5`_r--I+j09*LKqFS>cf|Vtyp) zFwKrVlNbQ0#s3G$Pp+{=&O^l=`Z^HNiFzMLvqTKpN$Q_ouH=4YWug#p#aLVWk!--P z@x_bt<6z9`3E~`X$7YnkGM%E!BaoiUX9;_60iFnBsczYEI2hjUuk0k;NhiQ+ee4cG zJ%=sXqieXGDy5tP>G=>tx{Zm_FhAgi8o(}G31H$TEM{ZC%t%=OWWlvx^Esp9}pkp>Ug7{Mme9X z3YCsak=YWo-(B-?)Y8Bu?vntTsT13|+~gE!Tfe|CF)n(25`fM+SUL)@9ppBxXZ@<4 z7vxdTc=Rd2ro8&B>`M(6oWs}vk__)$ZytF4myETk03zvF`8%B1bGUUU%^HoRgqza~ zsICG4u8Ug>@a1i`wF@-mf%iu1o&Nsic9Js>Tk*<{LI*pEuH}JqjP`~S$b9}-*?F8U z+}+8gMdg32Os5TcY$vkCxGgtvrO9Le1>h<#%gA!3j_@mXF2Ow0(VO;+zDu}kyh>KwKVpKdj?iiHU}uc@aFMK0A%Sf5kj^5L5YuE&J=sP_-3-%d_DhT^wj4nlD~ouFpVbW#KgR(Ar zpNsU|NYRrIG+1D?m0cKS*6;A zOwx*4e}HR_M8zI#&{pg0+yXo-nwl?fKbDoOc8OtQ$bxa@^}@JMQaI5`@xyT{uQ^r? zI0*fFADV8FQOP|8^t9_o9Hh^CO~3=7cxPK}MIQbr<3AL^aDo%8(F1mb__kui(SEjs zDnLil{|JDjv^dxgk2V47C0;bN!}hA7PtXZici=IVeg~^sv=@7Ne8}TB#p_kilT!;K zwtB`06)QPE;4vy1E!j3i3I|*_nqwjXDbbde&iC;&%Yo?SREtc~^#PKb{86Ihax?D& zEw>dHd_AC$*Kql91jnRhN>rcPU8tIew_KT~&QzG=e7(%(dow)!9p~*K={qimQ%spd zh01gP+RBrkXe6ie%;J&dQb{u!SF1o4LwUc==8I~S#}2TKSFVacFj~rr;6@NW7zLue0WilA`&e}%g{K_TQGT9* zU)|H)cAkUZchM1@bivWHdDCbXx)T~sOW28@@fQBIvBeI$iojcMGpeg4dl5s&iU*0h zHSi^6qDtA_(%Rz=OBS*9e+PaUdZWK>qsUqh^9A{Rm|4e`xLil6!91OcE4**cOksZt zvNY743a?UpI0gW`C%;(m;K(>@{Sp{dLTP^UUyR7VE+T#-wUwsqha;+2BZE+elTiTa zWf&rR7+28+li5^?^)CIT4{D`;`1yaV*h}@1x%28nh?F&@ zGA1}due&7@jr_&hF$)uIudlnbUPgYmCW?gjNftbRDtAPRAPiIVQ+B!5P)5J4!g#1! zx|*4N`FGUbux4{#iEa6n$=|)n+||$Tul!YJ5*-W?ZE%9yUSSCwvJ0d$K0aKnh5V`P zqS%jWgFDRd%L{s93ut?zR-s=BM+lTuJ<(ToEk_LdL^Fz+9#Nx9>tBJ=HtRDt12OkL z;UzEOO&^4GpT?{t_q{)Bx)9F+2yO!X zuJFWY#WdEozrW_|@4e0e?zZ`5n!vNJW3@ z2Ft06&@FpZB>u)6<(+KdkoL8*g@*Xr<*BXxqj9|0AtZ;Hc;gOX?dm#YSK&qP6c4Qg z-ySyMx;SjVPf9J3RiT2i5ULI{D5*76m9|L<#iUb3KJ1WAZJOQ0s z2ie2zhk5ItURi|Hc4(^S;Zu|@$@cKV5<8{x?FwfaKz9r)?wgTSzbh+H+N&^FB(lro zRcu61Yv01TXH1Hm%!`!Dd`EQGIB)6?I%s{B=}t4Dm>lrT-U8X;Bknh^<0d%sC}8Ep zSI|C1KKZ=(Je-T)%k*(kPTSY>nKzQ{4o|!2r^#4Xp7}Ocp$n`JpV3_Gy~mg4*f-k% z0wsTEdnfY3YKFOzEr89Cq%5!r%kv#1p_!~ge}+9uh*z!fT=-PTBmr!d%zlY#U7u+=~1$1}><)4Qr@)Fv6D-ZQu0fNwe(k z)}Q@e05klQIw)Yvur!uEXdjVLK~b?I;0JxNt?Spk=vAE3uJnPvXBEN_$=5x@Z4(d8 z(O3g71?Cim+zITKU{?@I`!Ol>Ree;Vi}?zQNE<~SC+Fb3LTnrxUcBlOG~C}qLv%<_ zg<&8>?`C?jYEWdHMWE8L8_cG5YrVj*abXb5PY>Td;GWf@g_XXBSobiJtmy+8SCJP^ ziXc?lE3ifjQU03|JRJ$RTe67F@ahEuqCjWk1kqv)rJY;OiPyS6vZwF&vmW%TRtC{* zhvBMmj+mfzV?*)#BwafW?Ja&vx8=`af`@{W7QozFFvh&&Wtls`QfoiF#~H_?j+ih* zy0VOH{F9%a3pGv-P$W_0{qsE@tgjsgETa)8nOZmo37_J!qezmu{CEk&*vE?g)URIT zLF|IOs>KiSb&7hxUsh4O*%8Qy;9>l~U*VHyklvv~%}Yq*x!CqHKJLiDXu8AcSG79*NihuWl;Wm?P;!BH9QC_G{Y(0n9$R z7n^8||G_{hA=VzNCSGMpv88DyEz&uIQ5Hfn?V*lMpdI@KX;0poLT3ca*c6Z3`NKqB zd2zo<^`MJFy8fsY#JpX-jYaR}YxPk32|smwlyMx_iDWH~KrF#lv{Y^HkrWF=b=}Zg zl#?Jb_Nf!yFwwQ|qcJ9l!?k23rpHVux4p{)QCsd$#_anwn4hWJfuB6k*_P_XoKo&RiZ$uTM&ja;YNc|H_$j_u>s@)^VXym zUDrj+fit+DV9lBnfR>!OB@(WPe;xw zd>^c7L@J==#e=-dL!)t^e%bvX0XFEQ6k`=O{}fl-Yv@3TXSl14Hv$ z5`j>cy+)TFDHWFi=w2hdbkhYmu7dI*gk_mDZPR$7Kb1O0$(FzEns!p(OW#u)dr$_x zxRS=M8DGcPG$xNl;+ki;M$%RhcZ5eu%Fl%17L(h_eBkPK()#1KOBX-zT+&{h#qDa5 za*QW?1*PdFSsNuAuHNV5CJ-LBsQ`f5AH{HW0Yi^Hh@q%3gOKZvOW-~%O ziZ~LN>bw(5Wd$)xT3T+1o_8U)BHBYQJQCfOi_}^fkk1T^KfoMeEl^wDy;>niAeK$7?U4Tmrd;eS|mP z>5N$5TC~$v$&zs*`|8>Fhhy*(@$iLJK_4}qJg{K>YPmhyJxS-QG6{2c-$y=p5 z&s+{gIr1v8_$8^s!Xu<>W4EcBh@%<}@Uo!y?!Gs(8t$<5o$-FqU(0&jcCo;cD-1ZC zcM(GIDKm3gKe){De5=72%ZfTqL8ssuN`dU7oyX&r6T7t`ijMUF^jtv&gGvrr^h8+6 z_>-{OZzk03>4hsu5(BxogTHO~hEbHTx97A##j^qClN)S9kz?%he9(U(pwyz`i|k*% zQPWq$4ro-h=we@iaNzJEs!R!skX>)(eRtWncf9( zBUH@N6=&XtHeltGCyrIM4-T}ZgM~%(TCJbmG=r$pYTdCjJa|bdE1U?4u?|fIKQIzi zO|o+Go4v}$tib5qhfJ}+m8f$4mM;ns8`a+9y;X9iLm?qqrG9Rm7Jnn$Cb3{vqO$^a zBBsCB5!pVqtCP3lTju=o368N}w2#_G!%3W8XfWAnFLBkKgyj3|d|EhS&N^ zbvm~BP7M>x4J>Pe?hzVZZ_o$=L-9W$4MzJipyD;q~dLly=O$HE2JO^hH-7ZC_(5W#p_S2cTJ&fi(J9QJGE%SK5zr zzYr)`A`KG(>2625ll%e=$DzV9vnpEaiz{+tz5qvK^%PAM>7paNx!VfVAv511`reyK z0a$Q!jO3LfDUaSRM3^0(NJI%BK@tMqV7VXgqqUAl2P$kmos|i;5f2!82rUnJEt*TR zx$cwjcq4M@)l)p|5oirG?OklG$_q%>^A>$5RkL}<1l=VE?@2B@DH+&PB>m9!KR}%R zdZ?r0ANVH1tPS9D_xSJh&@50dwQSkRM{xQ7wzFGJ7fR@qPBi8K0VdtP=;B!&N`L^f zCqJbO<2bT!A>g|5nOpR&aZU;06&F^ECpB8?oud zeJCz1o(PHu47C%~r-5JPtAI1mIZO;C+cfUX;2u2P4kZ25pzy7y%tS{E0JiYQ30{ge z){IURD5F~e|>ztSwK-*X)J=CW(azC-A&RiN@573a7=($$;!NE4%brT$uj zI=q|<<9@|)3W2qD>OrH+>;2+T+<4suutdam6KxX+7rRV!$**hJt})3Fx-n&WT3%qkUAQ`3I+n+tlh($b(w z;-9@fwGwRSRo6xMeO-u&Tjo0I7}5(>7(6=^~Mcd+o<=XTK%Y$4hy=Wo+QP>vQPK&UbAZw#-EG!` zZw+p1Ds&BeA36VE_S+I)O1pL03$Tg9dt_|NZ-s7)a>)X6j`W=GEgIWH_g=8eGOh&R?fSEhB z|NG)Pz%i%WB>5}n#_PfR`GtYn#MD|&@41!8cxu5Ph=p-Ye^j$-x1BL!4sU6qR#I2| z;2P4)@p48+iFc(aP}9>E^t>%UV_L3n^p-0xmRGFX7jT^kG9#O3e>$nOY4Hf=muNDm zH!3jRU#FBWyYF%x@b1^I@{4UsXOIsr0)mHFi*D5TlIEm~tHp+D$Xl2G=YML^kT!fc zbQ@{V3CG-DRsjm*QGtWyhnBHhEb1(&d!p}U_e93ZDt{X~kC`{!yY3Zjn*Zd(Z2NWn z0D^+ZZ-hpslimS9$ohOfo#8sSoz9ONn13oUugwz3q|fr#)b?0hf|g^FaUBO3T^Pjh?{g#r?5YCSZlb_#W!@0`dM;rfkGnPaYcyRXx^?uxD$)n;yEd#Bi8B?gH>J_jSoZ`*ACf}uXjO`S9WwB)tJJ^#zPhG(=I&%Zk7>yG z0DgMQhc0|+%e;P;hLbILT_t4A$j)+z@M%8Fd$|?@>@hNnhDV$q=5VfyEN@L>$m78l%BZe>^+YE{d_AQc^E{n4n%8GO(tWh$>~Eg0m1%ABBxSn91vpkA zW*w9=P*QY{TI&HCXI?^^TP5<#WtZ;IxSa$wh27j~=9t>C#y0LVoU(Pud@K>t7+4kf zu4jN2g5_KsT>f>lf43?OFpwk*v}~1c@3&05e!_oM;rn4)&bIJz75Nf|$Q6!P9RB;s zTs=bl-2&T`n6jzW0k?^zcCaptiqzRGh}L+`ZsIw#zvcXfz;QbRfxFK6idr~6XzIDt z%Itzbc1At(!i_#3s8@zp#VOZ=PxVLkISAUiYSt08z4v}IPwet0a4hOm%EuC*KCi&9}4bx@31~JcL4%&C4!4f7SAAz_e@o)ozloyOS0-Z7HwR4?uwTi#kWRhyRnURa>qzx968`D;mKjNTy~{#iaP%b zbxg3ApK_2JY^sT;SduzpXWw&|Yv_(3o;xlGloqHSQs#Z(jqe;C;n}<*Fu`}ncip)* zD_ih_uU@qS&c#Lo54;CsQUd8xiQR$$yiEhQeNXq{`(!3+L?6gcO-KCQ9&64Ep{F=L zG}v3fEX$$UIf&xx^C6xfZQe{tyoRtix^`GKiB|lv z#irNs8!jCrwg?6^C}8K#+g|k!T)0?k5H!ojU<*8*4>9=16do75kK?6y`h+@-N+2UQ z1Xr<9DPbD4AiPHNIbQ#I}N`c8ol*VLC^Rt)Me?{61G6$c6AQTb%s zRAuW#W#>&7lO5Ewiq`TmeGO846l9Z4I&PbTAlVJear6WyT*{UtlHZDWb?rfbR-pED zC5(za2vB~StfCVPA90(GpM6dWnq&IMhtJ(PF$djPLl&hL(&zM5N23Tsx!GVJe zKr{7pEV_sayJJui!~tAyr_`Rb4to%wDqubHAN$QXSh4pDQIaobzD z{mSlvAcqQ_vx;LLuf&_P*RtqoXGeZK7VjW$^xwL*az34DRpba?Keo4C*(s}gQhG?^pap7rLK{t9D;&Uzx+_(6{b@wt46XShS%1)ZTZlQr5d1?-nOr;~kSnG(2_a z?#O4DwRn;Jr9RMkos>D{7z8kGq~l`5Pi#J2>ObByxEHth-fqcr0?Y&yt_ob*7~1Az zRF#ZqbaPkM4&&vkk4X}QJ$3SHKYJd@S{A{YnT(Uw=wKdulbc&#>z@~lNqFskTQ2>o zB>3MIc7y=#I_X6>8$iR*KOlYgmFVQCy$j#cvoE*S>jvw!!qBG6@~-b}gf4wD9~iVD z=>%bhKRP21#>ct2!2o7;7@~%L99pS=iN>m=AaBqIx@WyC*6AwUn-iK1Y@04@AJy>cPiG@}0+bZ~4LZP?{t z*rv2qbSU;Umgw1aT!klHzBFEu{zyw=%-;)E5T)4@;`uZ<+}Ba7NB@|Th2pYcUE{6d zYLv=>zrD4nNNU^3Qj?p#Opp)~=-|Y<^6=Ex2Ra$7EHS^WGgJoX%}bmj5JRVS?~NV0 z;dztsb0fvVwEG@^%Dj;V0uM?5R4e@^jPSz*zJZb(7n%i%%FcR*hGkJ=sY zf!g&PFq!XRgvm_JK2_=*E2@8??zKkBH8;1dh+FiSxXSVJT{b5g#?F0xrMM-8+l&C) z3*j|r!qLXU!i0|am6u`RqI5q<8GiDgym3SUR=qP8kh2yJtGJKsp%hUQaXb1FB-g)& zNmvm{_+tivg8H{XbY;m(s@Xrm~AY9RD99*E68m_ryW4+eBy zAFZd`B7M%trNDd)ksG~XTVKT=6*KBVZ2wJqrj8)41=j(-&>n6g>Lbgrt;lcwaJ z%xG9F&^a}n$OzPa;R8&PpPb+KT|jvwA-spXEP)Y*nk=IoVoMpIpD>7NPYP=?fUs}K z%W|!wJ_IwS++s|!6VtU47?lTRlOFUy9pl^VFNOZ4)^VtVCAqq8#D6gG{B0Q~Oz?_h zPsY_9nNhl77~09JIiY$*-H__%ehGeG#{dB_tZMP*9pXSPk+he$(cobPvQKykTW#P{ z*f5Mv@>d^H^pO0iznmO&q#z&#D;j13sXulI@UZJ?Fzy?#Y+qUIH%xF?>yKw9;GjjZ zV4&<1n1a`!g|uK!QKD?Zza}o#Q_T0UTGW>@zq$#w2&`NWl|Jq7SD^5}S5Y0<3k>E4 zwYxe8R>$;$9ev~O#`D`t?Oetm@ip6tm>r`gE>hp%GH|_@DP-roBfqcb6wUg%isc^- z_JM?;cHt*!T@jED=$+$tIh<};-5(jZzOsKIep#9)MxT<5O?mMEP z>!p=ePD?=xNx!xGKL&E^Ijjo9FR_9dmR~i5Ub?waHf}8R%OHa>z(0anxrIm1MGN1; zxylOL8TtNb*zW7%oTi@=Dm?cWd{6}I#opJDlPDVtWwk2y1=V=@_hNL^VqO18I}(PX zNHTyBJ(0xlzeI3M!$3j#%$^w$B>4-30OWx(f87&JRtDn)zwD7l>i@7u+9oyV7?_p@ zcGl3rOtk5yX3IZ{gauZj3RK=y5<~lsMbeh3-RHf#`EaqS?QFumC)FWczJ49CpkIbV za7AdtC&~NlQ017MgD5*sKVY80Zo8XLZm3W%u_nrj3N=10p!r&NuG7PHh_e0B;9+x_ zW8Ru-tEOe}_j@Cjb0F#K#Yh`A4w4QYOw8B;vYyl<)Qyr+O8JHXyo!V{bJ4?Z!Xw&* zS)Vl=aXK0OuML>(4mMWM{q;tK%DDw32;RidQA=~0r^c7uCoaG`^wt_?%nZ;MISPyf zEU{@IG$5ugJXI&C9dlS}zs{6)$5tY9UrE#tkgJG3J5WAcSd@C_k!TI_Xb4n>I91yq zOxK`q#s{D6J5;o`u`ROZIqH{(>weA!wxV1e%Y&dAV+OV}&ZdUtB8@6Njr$+41%0Lvwg=g@9gA7d3_|a(x0x25gX0Q16!XAv zcRHF1FQ*7t@XCxR*~my0le0=q)hL-^3(+e4h8dx11 zd9snu)oF%?4iv(K?mS^WG~IGn8K_?4mqt)NRrtq{qv2dd(O`X%NHFLmQl|1@pKxPk zDLZ{hg%!}QJv|U**6v497)h_OL|b=7NX)c;ORW3~X3Fv}@L^)2vLO7|ESt=UW}cgJ zT8Zkl!S&^^`AR{%o z$ev23zqsPvP^!kN8p&^;=ce)yYE~Tgi|sS8!D8ngRs5WBuqpC;nWOzdqxFT@SJ_}I z-mk3ex;{A$+}8;B+nXg+R;=3+{vdrc+MdmUTc2PF_hior_f}fDOIB>U?zx`P{!un!&;}aDZZzRVp zPt~=B?kf14>P((CjYPq212vZ=oH?z&v9b9+%VbT{pmm9BKQv)$%azf8s5p2`Adr%@ zCL(&yy@*lHQCIjW6=^HAbELedi-Uu0!P|?U?zg29CUc=Eaoivdy2OiB$ILm`TvlFA zlCUJCxhIX45ogrs4O|uE8IUmpgvx?Wboat`eT9aOc<12heqW4L+pecu^^P~9;&TF~ZTy&23L=y29vXZHC;Q!lMD)pK zyhop3QQm#GDZ>$82Iaz980uOfO%sC>!dZxdB;MajG{;aR4r0HsA8jqyQ2u(L`W#wi z_wCtWc{p7(qf#7*c9LrA4ZaJ*0MtUUNl8h#x#O z8DB()^-o06UA#iRd%77W)3=b;NjbEtffa=#(WL0wXL1tb2ZA)*rH1$WNi3;|utR+b zArG%X;dZg{9fUA6bWPB!hjZO09pdy-85^BdrH_}+KMi6%OaInRsM|X}ajKyf2a(B*>6+tGrob#7Y7(}Gw~A`FLRwj&J5X#?GGbr8b{UjAmY3EC z4WphI3g6I+Z=HP8&BfT6Tk>uWrgE<<*6rk3igBfg;JiHv6qLgL@dJ_bfqXPO^?Wp{ zap>q?@+DV*RYzt($I%dBHyM#=viHXFTkmHod$&sczS15APTK{T?xCfKHd93+Z)LX; z20BW}s2}KijGF`^%g6K)6O4(b@|-%c3#XSZ;$AX#t9+Q)zH3kzZ86+X_TS!6VNeMMTTtH>uL@H_CE!Dz^NMnTVrP42&jRN zW%6ch-jKBBv#)G_O27gDN;cLCY^M0!I3uRLzjvOb?9rK@F!&%=v7s~`Y0-z&xSy- zaB({#toiYfb6yzva_Xc?b-gehRt2Mme{^ED`byaahcfHPeb`t2S3hPJI|z0wiLab& zL!oQ%Gg&m98Mnx7lm<@S_Yy z$?0+i=l8e?!iwOBe9jeWq7`s!YT}=&cc2GUZ(UgaI0-uvcJrt9bUpDYKmq?v^$%W>;=ZVBe~Mn^lF?w1>jR~(vtYXpm8uo z#c*V^_e2`74<>Ms!zE=gDBp7&)T+o9GF+`&Jrut(5^Ka} zhK}Jy0)^jk=R0}OROnsAnVE~sWp&go=Z%**J=ybTG+y<4s#>N({E5sXb>+Y`!RqYE zYjs2m&*@y63cGf{ei*+D6yYJDM}ptbPh!!tcqzlClNaIYmGp|+{3YJ?J0Btx-YJL> zY1MmFJ+y1Yx^4NTUrCe|kmE^fd#d^QP+%}?<*HRD=*ntNK7@u8*DhvU1KY zg}15+?XzbeQzO`3v4*j)(#Ga$#AeXZU>khisUN^EI694Y@Hla`9LbAnhomj*_Gfqn zDn7M!>wod7^xGGA>p2;y6{S2hQUjeRsC=tzlN+ptbexoKS`eIw)69`1K^#lln6Mg@nTC0QGy2v`zJj%x_s0l72+D+{khFS zK+h%K*}D<%`nuc1`5u-PKTS;l(904pr`IqK2Wzw88uPk}A?`oB@(-CSVTs)s-d$I3 zWyk~TbZMe+E5K9KCT{q7VU)O_bNk}Bn@pz&->2HQnAUj@w?C=ojF(saHaLwx6zBUt zd-PsF!nj~ZeJVn0Ir8V6!N?)B=b1VCLk^zD2jbL*{$*yTIyq`pAxP`t`N&J8W9gR!3~|nn;;)GiaG|tdkwBUO9`u4s z2jl5!{BpX^-a2h4M>tAh31DC;p*aaC+($z{zw|x|wxe6BpF5a4>n)@cgem}#JdQ+_ zP@~>^!xr36Jv~?0&{&7W-T$baJKxsW{?rUtbLKzVzTGos+6+ z3Y=#APCl8rr8NetqPo4;cvJ$&)MT+d54tum z_JBo$Xn~hMBrEmfgO{EBvVpx((SDWi82p<-HFF=M#I}h+IX@?g*5vZ&)NcilF<&BWBl{3H!O2^M&nDqW|-0&eL%e1ViTg*|X@1<@^1 zZW)+QDg5zOmOicXTJK}ToW;zyBq!A@*G}U3JhES#FoJct^1wYur>4+aKbH|C zYc1f9}-t16>XVY9j_FXJc&-)bARe|rO)dr;#YZB2zEQEHzb2$agW*as}mjZSvsiC#E@ zL|@Rd3Ta_qZJnY^>>oPc;XK<$9uZb|GT=Nug11ZS1Ea(+Vr;8VKa5-3rLS?Cus zTMKmv$1z#xWfIa5xA>L-^YspZyoM3O{6(P$i+B(-4Xg1^2nO~OCK$$B^EN_W4D5y5 zQ|cJgT8xxWK1I=~=2$HDtIK*FD==jo1ZxI*4>O0-ROuoD*yC}jgvoin^%t$syRwHz zRLjRFBx!%i$O@lfw^4Ije;ngcSd6adzJxA!2{K5vYx>A{Jczp@6@~fCLV7SgeW@Aq?G*G5A5<`x< zj@{$1|K__@Zx5rF+|>)E_EgBCZC%o?xYl?lj?YdkREMww`^^0UN1fec_QivP?ZNWP zbocI-rHLC5&|zS|rvtJJXRbiuefU*rZuqTGHC{OXv#HgW$L;+lp{}A-_34&F4Vq-5 z1*&<7?D*|izJtRqS=UulGGOk-!4kTDD$k5^MwB3`$*?5h1;xAG2j1>P?yeNUwYP;+ z7{w1aL3t4taWwcN039HC4d$%CCQaqSa*2Zwl@s)Sa&MQSndhHyZxK&53h=-8+Gzz9_S`8@mO@Mub+il z>wl9NHdq=x;)b`!a4|>iy`Tev*~E>6H8aN=S6#p-ZwFjJ(GL>`2?+39U#btSn)tKZdnUq+r45bmaruI!a}x?oJ(>omqzv?> ziV+n%=zA@4uLl7X6d5|l>&-vlE8E7tyHxNM1wIUw>3}6fOem?myGLg}Q5Rud_4< z(KhCyi`+%^4f!Ym9o){%l%A1M z3ir|_R?_=1nX%Zr{!;uG7=h<*0MdK16*@bZB_qJO;c^2E&!2Pj2j~itd-HAMan99xcB#_R zn`-uIANitWH0CxOUSG^IgQ8U7wf3+O%EC^KLJUDX>lPsR{Z#9^Z47`$U#W@Qr_N5U zvx+BQ#QN80t$u(}2W$xj0(`+anfT2IM7VShdh%}~v2jrgvJK*q0LwRM&_CM<6ull% zD+o?5=C(T7<71gM$(1fDD@nKkf}?N2jJ2MH{O*)L?1vo|suOnZesRED5Tj4h6HxHk z!~oijE|;-!5NAh+A^>Mi?GZVaFRVYZm@Uagk)4C6)n=X69~KD6`3D$RW0|UfqyeTd zz^RQ(K=$4jlX_!PX?<9Ua1|GM<3cR8>;VqsRJ2nFQ3 zH9*--i((@IoHMDtcDuCH>i6+MFkTWKjmU`~XV(v*{`!G0VARV(0j)Y6>XPB<;M@1_ zwG@SSk=X?z%lT#B0P8}0I2E`9%8+{(_n6^VH-Gds>DE*pWF~;ZCh}7>W2h{_V1cf) zp=CsO6-e?oJ~`M_r9a93&@?S|f%8Z4Uq8Usg7%Qn@gyu-kA!j^r$730V1Z1m+e#vb z=_MXLDZ($4lc~yBF8y_12w+q1eTs;J04tyF*7kOWSx?FqU@W1wHAyG|-0LdTZVNYz z3f(M-*Zpr{HsAcGj~oyn6KT6-Zpc-3f{^q}6`cE9f$nKr>4x z21+Y_pA_-4fsv&FzWY+oW2eQTqSUAC&6}npZGe-7hfKgBo8#H)NJZM`hj;#CU@fSD zb;-R#3PO=`vxfL!w)1y=tLohMWx*Yz;WZPHe|m;3fqlRPfB)^Jobl#Ni~Y1eX-BC^ zC+%x<8g<(@fJCM|ia#6Ti~hSusJ_h*Z>VE@$x@<85b>-==4mQ9t$e)!>`q9o9dJQA z%gy`00dk6H6os$_nJH@1{i#z>pAW%5<~WRk5d?Eqe(BKSlZuatkv=`zH32tBoEFGi zDrR&)J%wLV07Q@m^aTF?{`Mp0Su(e-aiS41#-j4*N@qFq^^H&^Oqpo96^bU+a=xq0__{izc@9)gq$A!U2Gpt^dbCWrA> z$$;?oA0flYft8lsl!5lWCoVPr`;sR>L$b#q5V2IxIO)HG?gQvoB}54$sx>)M0c9M2 zj%Wb@JCza5n*>KIWfCF3pF$(=0}n>kgD8l5&CiPb&oE)&U^=L;o)+F~mP)Vsr%gCF zKt3@u(XjNVjK=+cMRf#D+G6&u;rNLhvqb&X;&c_@cU?_|(1r=#Nc=0rUMZA2RwNDG z88!?4J2B8Ol&5uYlfZloXPEoX@O?y3k3A(Z-l7OT|F&s<6$-!Avaf&nNbXpsfpJ$N5T9w59r|D_#+RXd?3~gTgoH<-^nTlGW8vpEGPLR z2{d#m(0=%V7TMoN|AAY7*BB07rQ9sx{L^tXj7D&;h^^t>uk%NM=n%j|1>>JFGWq9` zFFg!{F#jyG;_u+F`N6Ap&21h3JVG6*(`ub6SpFR(fgQkj(?Joj|2)Eu14>(blsNcz z9-vd;0_-Cp4f9`hfD*8P8Gf|OS0MRYVg#@c;9Ay?PDJDHRKcKHVDybkwmN@L!u}V6 z(_tV;^*YJ{MA71a)a;h^NO=_C%Tla%Se(KB*d5z|`d|ZKi1`K>JK|SXtP()dL}KE0 z{#vT{nf8RsEWS24-b8JWDBO-Bd`b~^cOwyJuv!3&50StskzJMwr;GwP&lP;SAp`JW zB@m>%yY66_XtVh`xy)tL@CPqj7gtXV$Y9a~7dU2YvIk|^+0r6s2S(ZmtAuagzjp#! zbOyj1Q})ntKpki3nx%iuTD6?h`UEQ=jEWIGKkO+9Y2h)bbeXk4mWWkXbcebSZ{}rN zWl}yraeGnJKKaRhyuR(Od7kYMzB#YomD0C%W?#=tOicXG_9`1pjO9KWT(Bw`EYuUE zo0aFzR?pM$|7Z|tZOwITg3MM4*2uCxB&549!Gq0+cnc`QBuAZcJ~;jufuI!sBA!3- z1xrykKt9$jiQ`Q|LK3hvRAf6~a+a!=3QkgVKJH5DKJH7G(KrPahiTkgbFFTnaBljD z1*#z3WSG%Z8J53$;c)l5K~zKZT(xJ!vpx;cB4z;|8?YS=!kJGjoo}5mYh|1FXSNE( zN}K==ua5WgLK`12-^Q`(1^{9v7COa-n*>V2yD?uGa7jjFeM zcXP8j##`Om;17#~yp^*G&1@;93HEqf%N!ypBGQ>J!Y5~6nwt>}egT{GW-CPjW_$vR z2cYK~6xyX{dvMVas(Dcl3}ssGrWigsH?~5m$T;nJf9jd>uK!Xz6mMy0*1-F8z{29d zo~;w+$$@n3EwHX`$=eG9%x4s4TOZ?j0{|%-r_toom#}Psf%ud58y+%mRn~K|QpoQL z=4=8^|E}y#`Iuw|0w(P783l-9C8CPVmeyu7rn}rIax#2#bLSqXiNhInyuABqZMX)G zM4m>$i|3lNtzp)lX_sFtb-IostgW}X%xST`AATItrZ`p3kd5sHUwh#So{ZK4XpOWQ zoZsW1c=LHkm1uyi z)8*B%s{Su)eE=vK(a->rxF_AOd0Jg^iGGMt6^N10mRA2$oWedw`+D1f@iD!<@OVR; zB*K4FSvnCSruV>>8V?+{SuEEyKEFuOiS#4@pHxb;*3OhaIE)CbPLe-m$~lr6*ILao zn3x^+22}aNqY86iUay=2Mv!3V-4|?Gx}y$3npDy#R=?TvE&$D5oJ9y>mH>}Y>ew&0 z;X#(-ec!Y*gIxBb9zcWH=lJJR`)74!rE@m$L3Y)itcZb_8Zb+pvY1q#YE zT$*5qx3$e7GVFD`CS`4MwgbVq&_8mMAorc(-MOo?(7^_8Z{3E3h8H>PB?$rtyAhoz z3M)?b8+j`4?%z7O-Yvh1F*K`ckU!s*V6^gXNiMNEc!2%6jdkaaOH+ha#U8QacIDAf zx(u;V%8_7}7oK*FQ^D*wk)YiW=E6If>Pdj~ z)m~a}C@JJ#r3ToY&!w!le`(w?fp0YK%V-EpJA4sOvcw)+c3`iFdfKja9X|O&v(B zPt+CEXDJJlSj5-ytz6d9PhBeSX{ znv*nS)bl&5z<5)@c=e9OPIcnqNwt2Q5*4*xSC%wtPXPMiR!r(d96ooPP0EJ@|rF3Yfy_F6&ca!h_(RJ znKqW3(e=@#>*J?DKX%5*4Q*@yEyDcPv2H);42}j9$NzNo>$900%}STGCLo#N8JzeQn|3KjlaQpbt{TbrNo!3vC?t=h$cEpJa{tpzMsspfhf8L7lFT($Qt%V`= zw}lVxpoR7BVcLIsG6MXeC!>y#AJ=ZbTG$6IOeB^`{)6z#!NGqoVi}wApBC0pr@VY- zq5mNKC(Pis!Fq`B$BpMN7i|LEw7A%QCi!Pry&51GWVDdZ?w=NFNkMGRL=x*ip#Mz) y7#2cLYU-aB{!eiKC%FI9xZexH=f5u118*mlEIGJx#{udC#4?hK5`|)qeE%PDD_8yi diff --git a/docs/predictd.md b/docs/predictd.md deleted file mode 100644 index fc327c5f..00000000 --- a/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/qa.md b/docs/qa.md deleted file mode 100644 index b69f8568..00000000 --- a/docs/qa.md +++ /dev/null @@ -1 +0,0 @@ -# Common Q & A diff --git a/docs/randsample.md b/docs/randsample.md deleted file mode 100644 index 8344e221..00000000 --- a/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/refinepeak.md b/docs/refinepeak.md deleted file mode 100644 index fe0dc67c..00000000 --- a/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/Advanced_Step-by-step_Peak_Calling.md b/docs/source/docs/Advanced_Step-by-step_Peak_Calling.md deleted file mode 120000 index f137a3d8..00000000 --- a/docs/source/docs/Advanced_Step-by-step_Peak_Calling.md +++ /dev/null @@ -1 +0,0 @@ -../../../docs/Advanced_Step-by-step_Peak_Calling.md \ No newline at end of file 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 100644 index 00000000..899f808e --- /dev/null +++ b/docs/source/docs/Advanced_Step-by-step_Peak_Calling.md @@ -0,0 +1,291 @@ +# 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/INSTALL.md b/docs/source/docs/INSTALL.md deleted file mode 120000 index ea47b620..00000000 --- a/docs/source/docs/INSTALL.md +++ /dev/null @@ -1 +0,0 @@ -../../../docs/INSTALL.md \ No newline at end of file diff --git a/docs/source/docs/INSTALL.md b/docs/source/docs/INSTALL.md new file mode 100644 index 00000000..37407794 --- /dev/null +++ b/docs/source/docs/INSTALL.md @@ -0,0 +1,153 @@ +# 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/bdgbroadcall.md b/docs/source/docs/bdgbroadcall.md deleted file mode 120000 index c22e5402..00000000 --- a/docs/source/docs/bdgbroadcall.md +++ /dev/null @@ -1 +0,0 @@ -../../../docs/bdgbroadcall.md \ No newline at end of file diff --git a/docs/source/docs/bdgbroadcall.md b/docs/source/docs/bdgbroadcall.md new file mode 100644 index 00000000..805ba213 --- /dev/null +++ b/docs/source/docs/bdgbroadcall.md @@ -0,0 +1,79 @@ +# 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/bdgcmp.md b/docs/source/docs/bdgcmp.md deleted file mode 120000 index 62bf82af..00000000 --- a/docs/source/docs/bdgcmp.md +++ /dev/null @@ -1 +0,0 @@ -../../../docs/bdgcmp.md \ No newline at end of file diff --git a/docs/source/docs/bdgcmp.md b/docs/source/docs/bdgcmp.md new file mode 100644 index 00000000..099f9292 --- /dev/null +++ b/docs/source/docs/bdgcmp.md @@ -0,0 +1,92 @@ +# 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/bdgdiff.md b/docs/source/docs/bdgdiff.md deleted file mode 120000 index 365bae00..00000000 --- a/docs/source/docs/bdgdiff.md +++ /dev/null @@ -1 +0,0 @@ -../../../docs/bdgdiff.md \ No newline at end of file diff --git a/docs/source/docs/bdgdiff.md b/docs/source/docs/bdgdiff.md new file mode 100644 index 00000000..dd221077 --- /dev/null +++ b/docs/source/docs/bdgdiff.md @@ -0,0 +1,207 @@ +# 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/bdgopt.md b/docs/source/docs/bdgopt.md deleted file mode 120000 index 33d6517b..00000000 --- a/docs/source/docs/bdgopt.md +++ /dev/null @@ -1 +0,0 @@ -../../../docs/bdgopt.md \ No newline at end of file diff --git a/docs/source/docs/bdgopt.md b/docs/source/docs/bdgopt.md new file mode 100644 index 00000000..8bd7e0bf --- /dev/null +++ b/docs/source/docs/bdgopt.md @@ -0,0 +1,80 @@ +# 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/bdgpeakcall.md b/docs/source/docs/bdgpeakcall.md deleted file mode 120000 index e31f54d5..00000000 --- a/docs/source/docs/bdgpeakcall.md +++ /dev/null @@ -1 +0,0 @@ -../../../docs/bdgpeakcall.md \ No newline at end of file diff --git a/docs/source/docs/bdgpeakcall.md b/docs/source/docs/bdgpeakcall.md new file mode 100644 index 00000000..9ae78212 --- /dev/null +++ b/docs/source/docs/bdgpeakcall.md @@ -0,0 +1,122 @@ +# 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/callpeak.md b/docs/source/docs/callpeak.md deleted file mode 120000 index b33b82ad..00000000 --- a/docs/source/docs/callpeak.md +++ /dev/null @@ -1 +0,0 @@ -../../../docs/callpeak.md \ No newline at end of file diff --git a/docs/source/docs/callpeak.md b/docs/source/docs/callpeak.md new file mode 100644 index 00000000..5ff6fb6d --- /dev/null +++ b/docs/source/docs/callpeak.md @@ -0,0 +1,477 @@ +# 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/callvar.md b/docs/source/docs/callvar.md deleted file mode 120000 index 8876e49f..00000000 --- a/docs/source/docs/callvar.md +++ /dev/null @@ -1 +0,0 @@ -../../../docs/callvar.md \ No newline at end of file diff --git a/docs/source/docs/callvar.md b/docs/source/docs/callvar.md new file mode 100644 index 00000000..f27bc862 --- /dev/null +++ b/docs/source/docs/callvar.md @@ -0,0 +1,224 @@ +# 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_algorithm.jpeg b/docs/source/docs/callvar_algorithm.jpeg deleted file mode 120000 index 4c88b318..00000000 --- a/docs/source/docs/callvar_algorithm.jpeg +++ /dev/null @@ -1 +0,0 @@ -../../../docs/callvar_algorithm.jpeg \ No newline at end of file diff --git a/docs/source/docs/callvar_algorithm.jpeg b/docs/source/docs/callvar_algorithm.jpeg new file mode 100644 index 0000000000000000000000000000000000000000..f44a57cd2ed88c91df44dc4159786507e607c3a5 GIT binary patch literal 163926 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

D6E^Rq;j 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�o^g#(vUbvS$H=IJ2^ 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 Z`21U&kAFGt^FNuP>@Vm2SJ-|Q{wIW?F_QoQ literal 0 HcmV?d00001 diff --git a/docs/source/docs/cmbreps.md b/docs/source/docs/cmbreps.md deleted file mode 120000 index efafc47c..00000000 --- a/docs/source/docs/cmbreps.md +++ /dev/null @@ -1 +0,0 @@ -../../../docs/cmbreps.md \ No newline at end of file diff --git a/docs/source/docs/cmbreps.md b/docs/source/docs/cmbreps.md new file mode 100644 index 00000000..fa5334eb --- /dev/null +++ b/docs/source/docs/cmbreps.md @@ -0,0 +1,64 @@ +# 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/filterdup.md b/docs/source/docs/filterdup.md deleted file mode 120000 index 032b72a3..00000000 --- a/docs/source/docs/filterdup.md +++ /dev/null @@ -1 +0,0 @@ -../../../docs/filterdup.md \ No newline at end of file diff --git a/docs/source/docs/filterdup.md b/docs/source/docs/filterdup.md new file mode 100644 index 00000000..4d28db6e --- /dev/null +++ b/docs/source/docs/filterdup.md @@ -0,0 +1,97 @@ +# 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/hmmratac.md b/docs/source/docs/hmmratac.md deleted file mode 120000 index 21189edb..00000000 --- a/docs/source/docs/hmmratac.md +++ /dev/null @@ -1 +0,0 @@ -../../../docs/hmmratac.md \ No newline at end of file diff --git a/docs/source/docs/hmmratac.md b/docs/source/docs/hmmratac.md new file mode 100644 index 00000000..e6bc4d88 --- /dev/null +++ b/docs/source/docs/hmmratac.md @@ -0,0 +1,267 @@ +# 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/pileup.md b/docs/source/docs/pileup.md deleted file mode 120000 index af4bcf33..00000000 --- a/docs/source/docs/pileup.md +++ /dev/null @@ -1 +0,0 @@ -../../../docs/pileup.md \ No newline at end of file diff --git a/docs/source/docs/pileup.md b/docs/source/docs/pileup.md new file mode 100644 index 00000000..65634390 --- /dev/null +++ b/docs/source/docs/pileup.md @@ -0,0 +1,74 @@ +# 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.png b/docs/source/docs/pileup.png deleted file mode 120000 index 496476eb..00000000 --- a/docs/source/docs/pileup.png +++ /dev/null @@ -1 +0,0 @@ -../../../docs/pileup.png \ No newline at end of file diff --git a/docs/source/docs/pileup.png b/docs/source/docs/pileup.png new file mode 100644 index 0000000000000000000000000000000000000000..bdabcc38aa3c3b1ce070a4e06d324abfaca3ad96 GIT binary patch literal 34709 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 literal 0 HcmV?d00001 diff --git a/docs/source/docs/predictd.md b/docs/source/docs/predictd.md deleted file mode 120000 index 287ad163..00000000 --- a/docs/source/docs/predictd.md +++ /dev/null @@ -1 +0,0 @@ -../../../docs/predictd.md \ No newline at end of file diff --git a/docs/source/docs/predictd.md b/docs/source/docs/predictd.md new file mode 100644 index 00000000..fc327c5f --- /dev/null +++ b/docs/source/docs/predictd.md @@ -0,0 +1,89 @@ +# 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/qa.md b/docs/source/docs/qa.md deleted file mode 120000 index 87dcbab3..00000000 --- a/docs/source/docs/qa.md +++ /dev/null @@ -1 +0,0 @@ -../../../docs/qa.md \ No newline at end of file diff --git a/docs/source/docs/qa.md b/docs/source/docs/qa.md new file mode 100644 index 00000000..b69f8568 --- /dev/null +++ b/docs/source/docs/qa.md @@ -0,0 +1 @@ +# Common Q & A diff --git a/docs/source/docs/randsample.md b/docs/source/docs/randsample.md deleted file mode 120000 index 52a49313..00000000 --- a/docs/source/docs/randsample.md +++ /dev/null @@ -1 +0,0 @@ -../../../docs/randsample.md \ No newline at end of file diff --git a/docs/source/docs/randsample.md b/docs/source/docs/randsample.md new file mode 100644 index 00000000..8344e221 --- /dev/null +++ b/docs/source/docs/randsample.md @@ -0,0 +1,84 @@ +# 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/refinepeak.md b/docs/source/docs/refinepeak.md deleted file mode 120000 index a8fb6302..00000000 --- a/docs/source/docs/refinepeak.md +++ /dev/null @@ -1 +0,0 @@ -../../../docs/refinepeak.md \ No newline at end of file diff --git a/docs/source/docs/refinepeak.md b/docs/source/docs/refinepeak.md new file mode 100644 index 00000000..fe0dc67c --- /dev/null +++ b/docs/source/docs/refinepeak.md @@ -0,0 +1,66 @@ +# 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/tutorial.md b/docs/source/docs/tutorial.md deleted file mode 120000 index 4b6ed794..00000000 --- a/docs/source/docs/tutorial.md +++ /dev/null @@ -1 +0,0 @@ -../../../docs/tutorial.md \ No newline at end of file diff --git a/docs/source/docs/tutorial.md b/docs/source/docs/tutorial.md new file mode 100644 index 00000000..4f50eccc --- /dev/null +++ b/docs/source/docs/tutorial.md @@ -0,0 +1 @@ +# Tutorial diff --git a/docs/tutorial.md b/docs/tutorial.md deleted file mode 100644 index 4f50eccc..00000000 --- a/docs/tutorial.md +++ /dev/null @@ -1 +0,0 @@ -# Tutorial From bf6611caadb80c22af3e822cda5a10d58e6777bb Mon Sep 17 00:00:00 2001 From: Tao Liu Date: Sat, 13 Apr 2024 12:28:50 -0500 Subject: [PATCH 09/18] add more format related files --- .../workflows/build-and-test-MACS3-macos.yml | 2 ++ .../build-and-test-MACS3-non-x64.yml | 2 ++ .../workflows/build-and-test-MACS3-x64.yml | 2 ++ docs/source/docs/BED.md | 1 + docs/source/docs/BEDPE.md | 1 + docs/source/docs/SAMBAMBAMPE.md | 2 ++ docs/source/docs/bedGraph.md | 1 + docs/source/docs/broadPeak.md | 1 + docs/source/docs/callpeakxls.md | 1 + docs/source/docs/cutoffanalysis.md | 1 + docs/source/docs/fileformats_index.md | 19 ++++++++++++ docs/source/docs/gappedPeak.md | 1 + docs/source/docs/hmmratacModel.md | 1 + docs/source/docs/input_output_file_formats.md | 29 +++++++++++++++++++ docs/source/docs/narrowPeak.md | 1 + .../docs/{index.md => subcommands_index.md} | 0 docs/source/docs/vcf.md | 1 + docs/source/index.md | 2 +- 18 files changed, 67 insertions(+), 1 deletion(-) create mode 100644 docs/source/docs/BED.md create mode 100644 docs/source/docs/BEDPE.md create mode 100644 docs/source/docs/SAMBAMBAMPE.md create mode 100644 docs/source/docs/bedGraph.md create mode 100644 docs/source/docs/broadPeak.md create mode 100644 docs/source/docs/callpeakxls.md create mode 100644 docs/source/docs/cutoffanalysis.md create mode 100644 docs/source/docs/fileformats_index.md create mode 100644 docs/source/docs/gappedPeak.md create mode 100644 docs/source/docs/hmmratacModel.md create mode 100644 docs/source/docs/input_output_file_formats.md create mode 100644 docs/source/docs/narrowPeak.md rename docs/source/docs/{index.md => subcommands_index.md} (100%) create mode 100644 docs/source/docs/vcf.md diff --git a/.github/workflows/build-and-test-MACS3-macos.yml b/.github/workflows/build-and-test-MACS3-macos.yml index 2dc60dbd..2c45f9eb 100644 --- a/.github/workflows/build-and-test-MACS3-macos.yml +++ b/.github/workflows/build-and-test-MACS3-macos.yml @@ -8,12 +8,14 @@ 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 155ad180..83c55d65 100644 --- a/.github/workflows/build-and-test-MACS3-non-x64.yml +++ b/.github/workflows/build-and-test-MACS3-non-x64.yml @@ -8,12 +8,14 @@ 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 d9aa9ed5..2f7c7db5 100644 --- a/.github/workflows/build-and-test-MACS3-x64.yml +++ b/.github/workflows/build-and-test-MACS3-x64.yml @@ -8,12 +8,14 @@ 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/docs/source/docs/BED.md b/docs/source/docs/BED.md new file mode 100644 index 00000000..800e0f62 --- /dev/null +++ b/docs/source/docs/BED.md @@ -0,0 +1 @@ +# BED format diff --git a/docs/source/docs/BEDPE.md b/docs/source/docs/BEDPE.md new file mode 100644 index 00000000..3634a25c --- /dev/null +++ b/docs/source/docs/BEDPE.md @@ -0,0 +1 @@ +# BEDPE format diff --git a/docs/source/docs/SAMBAMBAMPE.md b/docs/source/docs/SAMBAMBAMPE.md new file mode 100644 index 00000000..bc583edf --- /dev/null +++ b/docs/source/docs/SAMBAMBAMPE.md @@ -0,0 +1,2 @@ +# SAM/BAM/BAMPE format + diff --git a/docs/source/docs/bedGraph.md b/docs/source/docs/bedGraph.md new file mode 100644 index 00000000..6aa5bbcf --- /dev/null +++ b/docs/source/docs/bedGraph.md @@ -0,0 +1 @@ +# bedGraph format diff --git a/docs/source/docs/broadPeak.md b/docs/source/docs/broadPeak.md new file mode 100644 index 00000000..523509b0 --- /dev/null +++ b/docs/source/docs/broadPeak.md @@ -0,0 +1 @@ +# broadPeak format diff --git a/docs/source/docs/callpeakxls.md b/docs/source/docs/callpeakxls.md new file mode 100644 index 00000000..a50fd149 --- /dev/null +++ b/docs/source/docs/callpeakxls.md @@ -0,0 +1 @@ +# `callpeak` output XLS format diff --git a/docs/source/docs/cutoffanalysis.md b/docs/source/docs/cutoffanalysis.md new file mode 100644 index 00000000..a3a5385c --- /dev/null +++ b/docs/source/docs/cutoffanalysis.md @@ -0,0 +1 @@ +# cutoff analysis output format diff --git a/docs/source/docs/fileformats_index.md b/docs/source/docs/fileformats_index.md new file mode 100644 index 00000000..64c365e8 --- /dev/null +++ b/docs/source/docs/fileformats_index.md @@ -0,0 +1,19 @@ +# 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/gappedPeak.md b/docs/source/docs/gappedPeak.md new file mode 100644 index 00000000..84cedc2f --- /dev/null +++ b/docs/source/docs/gappedPeak.md @@ -0,0 +1 @@ +# gappedPeak format diff --git a/docs/source/docs/hmmratacModel.md b/docs/source/docs/hmmratacModel.md new file mode 100644 index 00000000..25a5f651 --- /dev/null +++ b/docs/source/docs/hmmratacModel.md @@ -0,0 +1 @@ +# `hmmratac` HMM model json file format diff --git a/docs/source/docs/input_output_file_formats.md b/docs/source/docs/input_output_file_formats.md new file mode 100644 index 00000000..a074a823 --- /dev/null +++ b/docs/source/docs/input_output_file_formats.md @@ -0,0 +1,29 @@ +# Formats of Input and Output files + +This document the formats and examples of all the input and output +files used in MACS3. + + + +## SAM/BAM + +## BAMPE + +## + + +## BED + +## NarrowPeak + +## BroadPeak + +## GappedPeak + +## VCF + +## BEDPE + +## HMM model + +## bedGraph diff --git a/docs/source/docs/narrowPeak.md b/docs/source/docs/narrowPeak.md new file mode 100644 index 00000000..aec8e107 --- /dev/null +++ b/docs/source/docs/narrowPeak.md @@ -0,0 +1 @@ +# narrowPeak format diff --git a/docs/source/docs/index.md b/docs/source/docs/subcommands_index.md similarity index 100% rename from docs/source/docs/index.md rename to docs/source/docs/subcommands_index.md diff --git a/docs/source/docs/vcf.md b/docs/source/docs/vcf.md new file mode 100644 index 00000000..947df29f --- /dev/null +++ b/docs/source/docs/vcf.md @@ -0,0 +1 @@ +# VCF format diff --git a/docs/source/index.md b/docs/source/index.md index ba39bcdf..be982d1a 100644 --- a/docs/source/index.md +++ b/docs/source/index.md @@ -258,7 +258,7 @@ contributions over the years. :hidden: docs/INSTALL.md -docs/index.md +docs/subcommands_index.md docs/Advanced_Step-by-step_Peak_Calling.md docs/qa.md docs/tutorial.md From 5628d9da65c17aaf42cad4fead385a352bccf9f0 Mon Sep 17 00:00:00 2001 From: Tao Liu Date: Sat, 13 Apr 2024 12:29:07 -0500 Subject: [PATCH 10/18] update --- docs/source/docs/input_output_file_formats.md | 29 ------------------- 1 file changed, 29 deletions(-) delete mode 100644 docs/source/docs/input_output_file_formats.md diff --git a/docs/source/docs/input_output_file_formats.md b/docs/source/docs/input_output_file_formats.md deleted file mode 100644 index a074a823..00000000 --- a/docs/source/docs/input_output_file_formats.md +++ /dev/null @@ -1,29 +0,0 @@ -# Formats of Input and Output files - -This document the formats and examples of all the input and output -files used in MACS3. - - - -## SAM/BAM - -## BAMPE - -## - - -## BED - -## NarrowPeak - -## BroadPeak - -## GappedPeak - -## VCF - -## BEDPE - -## HMM model - -## bedGraph From 295c64d4a2ffd8e00d31d11d89307613ab3a0c96 Mon Sep 17 00:00:00 2001 From: Tao Liu Date: Thu, 25 Apr 2024 10:32:14 -0400 Subject: [PATCH 11/18] update docs --- MACS3/Utilities/OptValidator.py | 4 +--- docs/source/conf.py | 4 ++-- docs/source/docs/BEDPE.md | 25 +++++++++++++++++++++++++ docs/source/docs/fileformats_index.md | 2 +- docs/source/index.md | 1 + 5 files changed, 30 insertions(+), 6 deletions(-) diff --git a/MACS3/Utilities/OptValidator.py b/MACS3/Utilities/OptValidator.py index b317ce27..f1a1a8c2 100644 --- a/MACS3/Utilities/OptValidator.py +++ b/MACS3/Utilities/OptValidator.py @@ -1,4 +1,4 @@ -# Time-stamp: <2023-07-28 12:17:28 Tao Liu> +# Time-stamp: <2024-04-19 15:11:59 Tao Liu> """Module Description @@ -32,8 +32,6 @@ import logging import MACS3.Utilities.Logger -logger = logging.getLogger(__name__) - # ------------------------------------ # Misc functions # ------------------------------------ diff --git a/docs/source/conf.py b/docs/source/conf.py index 7893dc36..c6435ab1 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -16,8 +16,8 @@ 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/BEDPE.md b/docs/source/docs/BEDPE.md index 3634a25c..3ee3ff1f 100644 --- a/docs/source/docs/BEDPE.md +++ b/docs/source/docs/BEDPE.md @@ -1 +1,26 @@ # 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/fileformats_index.md b/docs/source/docs/fileformats_index.md index 64c365e8..d42cfb47 100644 --- a/docs/source/docs/fileformats_index.md +++ b/docs/source/docs/fileformats_index.md @@ -9,7 +9,7 @@ files used in MACS3. callpeakxls.md SAMBAMBAMPE.md BED.md -BEDPE.md +BEDPE.md bedGraph.md cutoffanalysis.md narrowPeak.md diff --git a/docs/source/index.md b/docs/source/index.md index be982d1a..94398a0f 100644 --- a/docs/source/index.md +++ b/docs/source/index.md @@ -259,6 +259,7 @@ contributions over the years. docs/INSTALL.md docs/subcommands_index.md +docs/fileformats_index.md docs/Advanced_Step-by-step_Peak_Calling.md docs/qa.md docs/tutorial.md From fa84fa2a7199085efdc60e2e8b5a6d822b4abc81 Mon Sep 17 00:00:00 2001 From: Tao Liu Date: Fri, 26 Apr 2024 15:40:56 -0400 Subject: [PATCH 12/18] update docs --- .../workflows/build-and-test-MACS3-macos.yml | 2 - .../build-and-test-MACS3-non-x64.yml | 2 - .../workflows/build-and-test-MACS3-x64.yml | 2 - MACS3/Utilities/OptValidator.py | 4 +- docs/Advanced_Step-by-step_Peak_Calling.md | 291 +++++++++++ docs/INSTALL.md | 153 ++++++ docs/bdgbroadcall.md | 79 +++ docs/bdgcmp.md | 92 ++++ docs/bdgdiff.md | 207 ++++++++ docs/bdgopt.md | 80 +++ docs/bdgpeakcall.md | 122 +++++ docs/callpeak.md | 477 +++++++++++++++++ docs/callvar.md | 224 ++++++++ docs/callvar_algorithm.jpeg | Bin 0 -> 163926 bytes docs/cmbreps.md | 64 +++ docs/filterdup.md | 97 ++++ docs/hmmratac.md | 267 ++++++++++ docs/pileup.md | 74 +++ docs/pileup.png | Bin 0 -> 34709 bytes docs/predictd.md | 89 ++++ docs/qa.md | 1 + docs/randsample.md | 84 +++ docs/refinepeak.md | 66 +++ docs/source/conf.py | 4 +- .../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 - .../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/tutorial.md | 1 + 59 files changed, 2492 insertions(+), 2535 deletions(-) create mode 100644 docs/Advanced_Step-by-step_Peak_Calling.md create mode 100644 docs/INSTALL.md create mode 100644 docs/bdgbroadcall.md create mode 100644 docs/bdgcmp.md create mode 100644 docs/bdgdiff.md create mode 100644 docs/bdgopt.md create mode 100644 docs/bdgpeakcall.md create mode 100644 docs/callpeak.md create mode 100644 docs/callvar.md create mode 100644 docs/callvar_algorithm.jpeg create mode 100644 docs/cmbreps.md create mode 100644 docs/filterdup.md create mode 100644 docs/hmmratac.md create mode 100644 docs/pileup.md create mode 100644 docs/pileup.png create mode 100644 docs/predictd.md create mode 100644 docs/qa.md create mode 100644 docs/randsample.md create mode 100644 docs/refinepeak.md mode change 100644 => 120000 docs/source/docs/Advanced_Step-by-step_Peak_Calling.md delete mode 100644 docs/source/docs/BED.md delete mode 100644 docs/source/docs/BEDPE.md mode change 100644 => 120000 docs/source/docs/INSTALL.md delete mode 100644 docs/source/docs/SAMBAMBAMPE.md mode change 100644 => 120000 docs/source/docs/bdgbroadcall.md mode change 100644 => 120000 docs/source/docs/bdgcmp.md mode change 100644 => 120000 docs/source/docs/bdgdiff.md mode change 100644 => 120000 docs/source/docs/bdgopt.md mode change 100644 => 120000 docs/source/docs/bdgpeakcall.md delete mode 100644 docs/source/docs/bedGraph.md delete mode 100644 docs/source/docs/broadPeak.md mode change 100644 => 120000 docs/source/docs/callpeak.md delete mode 100644 docs/source/docs/callpeakxls.md mode change 100644 => 120000 docs/source/docs/callvar.md mode change 100644 => 120000 docs/source/docs/callvar_algorithm.jpeg mode change 100644 => 120000 docs/source/docs/cmbreps.md delete mode 100644 docs/source/docs/cutoffanalysis.md delete mode 100644 docs/source/docs/fileformats_index.md mode change 100644 => 120000 docs/source/docs/filterdup.md delete mode 100644 docs/source/docs/gappedPeak.md mode change 100644 => 120000 docs/source/docs/hmmratac.md 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 mode change 100644 => 120000 docs/source/docs/pileup.md mode change 100644 => 120000 docs/source/docs/pileup.png mode change 100644 => 120000 docs/source/docs/predictd.md mode change 100644 => 120000 docs/source/docs/qa.md mode change 100644 => 120000 docs/source/docs/randsample.md mode change 100644 => 120000 docs/source/docs/refinepeak.md mode change 100644 => 120000 docs/source/docs/tutorial.md delete mode 100644 docs/source/docs/vcf.md create mode 100644 docs/tutorial.md diff --git a/.github/workflows/build-and-test-MACS3-macos.yml b/.github/workflows/build-and-test-MACS3-macos.yml index 2c45f9eb..2dc60dbd 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 83c55d65..155ad180 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 2f7c7db5..d9aa9ed5 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 f1a1a8c2..b317ce27 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 @@ import logging import MACS3.Utilities.Logger +logger = logging.getLogger(__name__) + # ------------------------------------ # Misc functions # ------------------------------------ diff --git a/docs/Advanced_Step-by-step_Peak_Calling.md b/docs/Advanced_Step-by-step_Peak_Calling.md new file mode 100644 index 00000000..899f808e --- /dev/null +++ b/docs/Advanced_Step-by-step_Peak_Calling.md @@ -0,0 +1,291 @@ +# 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/INSTALL.md b/docs/INSTALL.md new file mode 100644 index 00000000..37407794 --- /dev/null +++ b/docs/INSTALL.md @@ -0,0 +1,153 @@ +# 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/bdgbroadcall.md b/docs/bdgbroadcall.md new file mode 100644 index 00000000..805ba213 --- /dev/null +++ b/docs/bdgbroadcall.md @@ -0,0 +1,79 @@ +# 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/bdgcmp.md b/docs/bdgcmp.md new file mode 100644 index 00000000..099f9292 --- /dev/null +++ b/docs/bdgcmp.md @@ -0,0 +1,92 @@ +# 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/bdgdiff.md b/docs/bdgdiff.md new file mode 100644 index 00000000..dd221077 --- /dev/null +++ b/docs/bdgdiff.md @@ -0,0 +1,207 @@ +# 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/bdgopt.md b/docs/bdgopt.md new file mode 100644 index 00000000..8bd7e0bf --- /dev/null +++ b/docs/bdgopt.md @@ -0,0 +1,80 @@ +# 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/bdgpeakcall.md b/docs/bdgpeakcall.md new file mode 100644 index 00000000..9ae78212 --- /dev/null +++ b/docs/bdgpeakcall.md @@ -0,0 +1,122 @@ +# 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/callpeak.md b/docs/callpeak.md new file mode 100644 index 00000000..5ff6fb6d --- /dev/null +++ b/docs/callpeak.md @@ -0,0 +1,477 @@ +# 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/callvar.md b/docs/callvar.md new file mode 100644 index 00000000..f27bc862 --- /dev/null +++ b/docs/callvar.md @@ -0,0 +1,224 @@ +# 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/callvar_algorithm.jpeg b/docs/callvar_algorithm.jpeg new file mode 100644 index 0000000000000000000000000000000000000000..f44a57cd2ed88c91df44dc4159786507e607c3a5 GIT binary patch literal 163926 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

D6E^Rq;j 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�o^g#(vUbvS$H=IJ2^ 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 Z`21U&kAFGt^FNuP>@Vm2SJ-|Q{wIW?F_QoQ literal 0 HcmV?d00001 diff --git a/docs/cmbreps.md b/docs/cmbreps.md new file mode 100644 index 00000000..fa5334eb --- /dev/null +++ b/docs/cmbreps.md @@ -0,0 +1,64 @@ +# 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/filterdup.md b/docs/filterdup.md new file mode 100644 index 00000000..4d28db6e --- /dev/null +++ b/docs/filterdup.md @@ -0,0 +1,97 @@ +# 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/hmmratac.md b/docs/hmmratac.md new file mode 100644 index 00000000..e6bc4d88 --- /dev/null +++ b/docs/hmmratac.md @@ -0,0 +1,267 @@ +# 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/pileup.md b/docs/pileup.md new file mode 100644 index 00000000..65634390 --- /dev/null +++ b/docs/pileup.md @@ -0,0 +1,74 @@ +# 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/pileup.png b/docs/pileup.png new file mode 100644 index 0000000000000000000000000000000000000000..bdabcc38aa3c3b1ce070a4e06d324abfaca3ad96 GIT binary patch literal 34709 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 literal 0 HcmV?d00001 diff --git a/docs/predictd.md b/docs/predictd.md new file mode 100644 index 00000000..fc327c5f --- /dev/null +++ b/docs/predictd.md @@ -0,0 +1,89 @@ +# 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/qa.md b/docs/qa.md new file mode 100644 index 00000000..b69f8568 --- /dev/null +++ b/docs/qa.md @@ -0,0 +1 @@ +# Common Q & A diff --git a/docs/randsample.md b/docs/randsample.md new file mode 100644 index 00000000..8344e221 --- /dev/null +++ b/docs/randsample.md @@ -0,0 +1,84 @@ +# 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/refinepeak.md b/docs/refinepeak.md new file mode 100644 index 00000000..fe0dc67c --- /dev/null +++ b/docs/refinepeak.md @@ -0,0 +1,66 @@ +# 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/conf.py b/docs/source/conf.py index c6435ab1..7893dc36 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -16,8 +16,8 @@ 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 899f808e..00000000 --- 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 00000000..f137a3d8 --- /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 800e0f62..00000000 --- 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 3ee3ff1f..00000000 --- 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 37407794..00000000 --- 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 00000000..ea47b620 --- /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 bc583edf..00000000 --- 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 805ba213..00000000 --- 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 00000000..c22e5402 --- /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 099f9292..00000000 --- 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 00000000..62bf82af --- /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 dd221077..00000000 --- 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 00000000..365bae00 --- /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 8bd7e0bf..00000000 --- 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 00000000..33d6517b --- /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 9ae78212..00000000 --- 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 00000000..e31f54d5 --- /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 6aa5bbcf..00000000 --- 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 523509b0..00000000 --- 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 5ff6fb6d..00000000 --- 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 00000000..b33b82ad --- /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 a50fd149..00000000 --- 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 f27bc862..00000000 --- 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 00000000..8876e49f --- /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 HcmV?d00001 literal 163926 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

D6E^Rq;j zz6TQ@tXo(N>OGc27XJg&J8#&s=m~U?){-TpmYQoVV62f+!^ERCY~9}CHFb+J;|{%6%=~)9 zwPf)y_IcQV7~15fVA0MfmxEXf#!j*$DCAn-BC~gbIjah_MBF)OspUibThGp_5c(z3 znyM@?^OHzW0(Df+a6H+ys;UGwsL}V3gX$I5{+N^%B0eq~Za)NTbkH|66?e=*1&I$GyI0Xso8&4wztVdp@Yzf}&uk`Jj3>5Y05{ zZdMp6t7mZdF!<38c9`Cj_KqRK~hKLY_4pG;HL9?rS*IEGtI>a~Zb4XC0xsGDFW z^NZ{JI>y0tmcD-|?qCnZvZ+sqCG2An65hBmJ>j+yi9)yiiO5vGO@D@#TmjVEf!o3o z<%ySys5AVVx98(#flvF2S4)$hrf&DnXrZP7e=FiU_5(7SR5|O#GVNk&zLto36KlUu zlOE>Yz%tcCh`GJ4^P1f1xs{r-^fo`V>a3~q@->} zpIO3?<9oIt`YVTr%0Yev`v5883cOib%{0W_L^~zdEDNo@XBSN?zFp;!J|61?VIt4? zZhMj9=YZGtdJ=crA*}0x8cHQWYMLGuNTyR!Pt{DhdwrpG2W?6}u|9Ki$PJ0|mnW!4 z-^6Hf*`h$lb=AvEqmGnI7DVss@$uB zD^Ch;=p$i;^JJEy`6))+$c&scXX;?UlEfy58_A!jeEV{3d(Cn;WaN|m24IDosrVkK z0SoLTr$rz-CYVV!5YiShoUpoVb9AovYn)W5TCNd4W z?R9b}f)M|nBKnk;o`Z- zN;II`B$5$3SE>1(IcUl+s+X7tm4_UaS(YI;n%UXN4f3A$bgi;nx4p7EeC_12Lv?_M zAVK4b9S4p%*K`&p9|7$0ENk653i|jQ)_#wjXFF&k)0NWzymXh`)F(w=V&BrA&3Wt} z@ow|ET)AA%<_*)1oy*1=pC%rIT*kK!X7|k`dZEfZ)faU>O}dkVFSn^+wGPW~t6o?Z zI;NdIh_5f@ePij}v^wirI&CFSQb@r5=1>ME*-$Mmc(^Lt? z>i!8Gf*Zvqp2?<}#j0eBk%FR&CQ~ymO}F-o-s1N=P#LS*DZZPA8Jy7p6A_OBZ+kSmcZ$&J#u<}o?IF9)?T=szKTUep3~Vnv~yvCsyIhT zk{(3xrCMU3f`+>shQM_#P2JZ{QoO+bW%Ks>;^l=2hcheBjBGt@AS>258EvoZ72YD- z8r}%lZUxv+INF{?%i^+p*&6=pLU&`cyyoH+%C(Km#a>Pia_-)(lFxtOpa=0pmci29mr(tM6=?oAKM;B8O) z3TofuODm6Gb1v~WFAWvXfo1V14&`QU;o!@9zPC@yQzaMvq_91W=v$Gud$fO~3%RAY z$C|QKdA1GbI2<6m6CG5)Zvs&ilJPNi5o0XF0$6k~>3-4;^mlB~_JYvzmbr*-%;Zum z8ZJrZ;P#guY_2;Me0G;ZzOn$@;CyDVg~+hi;*L>pHRBu`rJkp8};Ol|4Lc-GQ#j+m8P{Gl20PmK-mHpL0% zA5PdiZYX6@J$arif!a)uE355|&*GgHxaTpRj(%-kd+cbn_Y!2j?5l?9Zr=GVk(Y&G}AfrDXQeBlzY3%U2I1-=^KaL^nkW*dMM2J>K!-IdY~X+V(v= zvq!0`B^Tnq$R^9DG&6$QeNLX09;m6j?ca!HkBn_TlUUe%zzKbs59UWwx0y09fIZT5 zmGZO*)aiZnMB94XLRp}43(hvXIbv~f&rB!T51#w%p8;*SGN1T-!AKYxka{mp<+Ydb zR@EUJt0F;`1ao>nmTeP0IyIzJe|6OAf=i4^$5rfEi08T`SN)ih7~1>fn{Za&sNSx^ z+HbP6NrPvI$unhURcvkd=Ip3Nr#A=aT_*AL4;5cvi%F+gYn>g2>{nf6Jb1lcHH861 zZIH|e*Yg`FS_F3t0)bIV$B1_^eTjz#R!*Y7+<7`?5Y$d%isYc-#gWJuv(sugl-mKE z82pX-5zFqW6ikESqIbv~@?<~RYK?D7gXehaE(e$O&UwK$v9@{1=3zc#T6D{AfP8P{ zaIp4AuwA&pB)R{ZG2Yy1|)8ITjkQQ4j*Z(?VL36ncM#%@{~dawNaCJODo z+3v;N*geY@JwhW0w#qc=n7B-_o>_-!Q)YN?woxt`cF!Sxmi4m+RimpQrIHH_1yNNgB6L}zVsz84mb1| zjH_D3KRysm&ba4wSKpIb@#gc_5H(z6^oqryzhSZ`0QuPBe91HOR}t92{6lTl6&M7X+@;_ zQ+IB%c%<*VmdHFDPag?vv<)^Ig25se&J=q>Q~8(@sbZ)2u?qLZ);hq9FSi?6Jn7S$ zwwwI|-9?M)yZp^tc`bK6zO0XP5wB7;DVdQ_s2x@X)haLQTP5Vj9;Bg>2kf8M=Z&6; zQk4yICcFc3zoi?*YIZy5*!I|R)20(gyrVx>-}-_+AD||XFEf;Pf+Q4MDh$VQU@21~ z6en4ah7U-YIq#U+X^bmWlP5KYGh+?%<0qE|Z*}zf5Zq|>vo6`ssJqI~X9ftQRsd*- z%|}#fAg$1V(O&?DEAVpD$qJao*I7?ZPV?FOB?k{nI~!rpeBiU?u-<@Pf6EB<4K5fu zPk1Q~qggZ2GyFjC_j+^{=WuFiZxWEa1J!5-ctoA%mh^rTySr=2JHeK%>XQ;Yza25U zV9$ldmnUfFdxX!O#6FZDL$bOUH;;W=;%+ph_K1_X#^dnWwA(`O<4QIyhQalRqOHEs z+5J5>>cbFv0IBUNAYD=24KHoi1(#*7U?OX@?Y)dm$5N*RNwoI4xOl)%>uqVN)vtH9 z5Y4Hx1^4xdbzm0Rl|xJkVcG~3If{k6SvW^3lN#O1U`X!XGCuqz13MdC+Sl9QrLxt+f6;2hB()J#`5oJI` zWN0Z2SsoJl^+%QN=8W&k2Gi4t9UGrqK_Lg8o5UF)w(i8MG7{QoECs;?hpFKvFNNC^ zt~fz{79^+k7&q}|<0>J-@KhbGFYAeUogd^!t+P+Bzp_5f%gf(>Ti8a|!W;ZM{4F}; z#j(i_@c1A$+mBQ+k-EwA319Y(dX36VeU{%A-%Sq#rt=NWfB4X8Wx(qJkF~c~ZMO{9 z7?CI(;r2QrXX5B!%)9Gk>J6GVmX(kOSho2wRKwZI!9}kTnVK)JB-wLnt>*ODqu@LXClJouy&`f7PXgJrn`<{(RhuIoCnJmrqRr(~`CnO@Xdxu|YTDaH)? zlv;|&5GVy)%ENAe9;OpO*u9)n{@Ll+Ja{+FQO5P-n2ie&9s9@z@gMTCE4q5q>iivQ z97_io6rvdv;lh zJN2F?Pv@fP%}oL1MFbo)=@H~QheCvMR&l-}(mjB4indEEqi&CNqG^0tgCj0X`}O_A z3*yH1sFh0Y@i7oA19I z{MEwK;na+Mu@RJBaZ%9x)3jOZR*%r6mbe-SlnSI!v1LZtJe6wJ-Y=z1npyk+b*xvI zT{(K~SNZ4*tuH&9Ox3oV*yj76LLD>hi=8NU6`!WH=&jXGLCf)>fwQo~$}2f}^-Hitjg%U* z9a8;V2dT%kpAub)w+`NQEa~m--CNuJ%B=o+Oq2n6GP<~twqtZem_teEgRF^MOuQoX zIAU>9Wp)vI)!2@`yn?DC;Z76A+d11t-s<_P9>ZLgd+f*a!dAMGNFNGAYrOO$4)WB& z6&9!XCP3S9Jn)roNf9xH@2R@>Y=R6sL0mEI4w2?8TD*i(g zK4$3G?d_^qh^fmzO6wyUxoU^mR*)Hy=zOLcJU*yLE_qWiDKPjj!7El93Hr5JWv5w4 zk+{_|Y7YbpHA^X&fjm_46J_QEX|GtK3`7~viRYEg6_axWA9rk}Q7*9V~(%bA;u&pc}^0!7U z;lxC(UJwnP|Jqp@!mz8CX|Z?Bn^`j{2HZ8z0?c{Ghp ze2*lNz4Zqh-lPWX8sRxs&2Y+mXMg~g_aa!l3l&PHx=Kl!QNVe|w3P^yosfkU4{gh0U=^^x;bmP#QIncpns z#5UCFvBE0%+eGeoGMqYZ9mDE;YvK91^hD9y{-!XSF{O%jk{DmkSt0GKJzjS5OOjxEhKlwVI`d9O`cuhWIMye;bV!!9V9NBum7zdE_#k*i6oUCaE!KxjPFkJ&v>`AP+=vHw-^r2M_cZ{Q}P0Ybf26hOMP!t zy(4E2RyZF~%Ur@Z#uDdWa0PeXwTs(UIBV^gl3~Kgft=J{m%*PQ={TNv{4Mzi9y(?a zi>pV=p{92wguNyK+o~{U?<=J)lH5SWojQ~<1BXEK6TSK$ndiNkdcodNM&Yxk@1;iSgN3f&N$+mNq{i6xQ(HY<$D znLe1Xky$MurzKO~ix(aK+M(RI{090!ObU8+O6Eiz~^|7Tf|AG zL^xy7m=eJHx)yPMK(qAG=9vl$wAvjyVMCX35&ewy++tAvk^Khu`Oivo2{)_&Uf75UB`nS)J# z59*w%(ZrqXiPlEVmF*9&ayN5~>G+n*zS|_eGZ3_RZHU%*Jm7*gh zL(}7KZTQf;;HAO0A-Tb;GZ=k0n>i*NJH^JMx?%fw1j!fc_aTqbDAR22EHY25gu5xG z;(+eEV$XVQW7*_)bI4n#vT@OU-)H87!v}_=Eai`!50EDXCyBPZl<=1EiAZP>vhIz7 zUv;;EnF~Or;hsc=1M97crmQW87f|zo<=m+?@*uVJlx9kly>QZnkqcHv_gjkef;@TY z3@~{mH};ed)~(eI-}@%8?&P`ar_SBIH+amYl~Us(|A1*J^g5#^lw_{2uRByEGtLc* znp;9EK0B;6q?OH13Mrzb(}6SKF)a9|9k0d|5biyV^aWTV$oOoN_ROg)&hTz%FH%2H zM%~1uMuw(FoPS#7{GHwOm4+?idPOlI8cnTM2=uYk2V?<+keax9pL`is)OcV0aB0$1 za%EmaymMRr!lJsVYy@n5hEI=7=t8NcjVXodhiV6%Vd0`+c!?jpcjQ;~MD3^FS8qjx zOSCMT4rG?9hPU+|<<;|>m~u7Zn!rI^V?j>$R_tVz9t)GVSzu=IEThBHOrAYQ*3suR zSLf8VvZ!MaS-lo2_huBTj<%5m=X*+xeuKv^ppJimN@;gUqZkYaGKWuF^ZgR(*Gd&4 zMwa6pYo*u0<=I}zxcK46O!G`2f5 z_HV|m)8D4bO!K<#e^;5a$715g5UW@{qm4nr(N~iS1IUdW14kr5)T0VwxE#CH0It1d zK(n;(GCp0(%^ASWecOKY-Y_+z$1va8zx$lb`_Vv;s!=FYA=+Rg15AYbHH8&>3ULLu zl39`}9Zg0WE@}K5nL4ZjR>;nB>i(vph{3pYLftBg(v9^3t@3QWy+<<6TiwA6QoNz1 zDsN1Q$*Xk(h7dwz)Jmr)MeZmvZUlGuo{uo^FQ@7oMliv0P);2JNfh=@lJPYa&{U zp}{WOdi|blUp~}oY);;vl9pU%5Y}4~=6LdGL3?elRm<&qxBk?PG zf>%?SO-WGYl8af1lEH9})|a706LS_mTBP|yR4=pcv2UUq^XZA{@xek5{XTYq0A7>| zgB4E+v@%Uu`x zp(HLQ_vlM?$-Fm!i-s|pqmSiXCKqphNRJuWeO6I^Sh&BGU*p(qs2lMBHMEIOw;xlw zSUK{QETSatue^pf1PhX&J;g<`U!KNU!`hciTP&@=BDW2BoEZ{bPd}v-OP#%)d`VCI z`gMHn;IZ70VK37PKCV7p&K{=|?y-}aZpDr_a{a;<(sM;q>z#C{(p0|;+ZQeic>zi9 zEa@m5fK!$nHO%fc=+h5xt@XU1-%GYAp(oH+&^O4Jg!ce|nS1?`Y8HPQE39aXbk^hL zw@KY{1ACucW&Fh#f*(ict+_g4e-fs_Huu-f+FaS85f&Tk{4?tMDr(asB>&bsWG$oB z&p|qrIT=jLY|ghZFHg4=|AagpSRwh|3DHRu#(JI}T za>wQoTu^^xBxr=M5JdfgeD><8i1G++eM#Jv_ktBh>z{TfFEZPoX!Bk6!L}<~e+|{T zM9CL?@@Qgo=O}lBnwhi)T!yXe^<~MPMl`dog*x|TT6;6f92C0k=PkYEW-Fd!VvRq*zKP}A zpTX-g`>fnvKJJfltU;=dBF*>NbH^KMrCrc(Cavt+&Y6#9vB`}rM9w5aX^YrrWY6j6 zV_A$wp^u4YPfrMYVENrkMtVC36z^I$GPJM0KG~asN-gYrlptvi*9%8J>KANJbmph!>uQC3Da$gNsKkzsI~h`kf<#j9kt?I~3AV zXfg!?dBYRiyw`zOyB&3M<}irF z8z}xNkY10vGJqdjMX>?RGS8f8higKQ&Ysvq&jRff9WclD*^w2xqIBMiV7FQ|;g|JW z^OV?hklQd=&t78n(in-38&mplBEuXe)-WOeURr;j@wog?KHWlrk3(T2u4Ar^%o}3qF3K%(qV&6@ znt0*0m%Yb*jfO(JxtgkT6d!`9_Far8$=cUnue4JB0DJ`$S=&uE6O886a>a6&%z4=K zC!7+>w1&@v-iUDXqyr)KT@`8_6+wrHxSjomOM~?NC20XiRP;tF&D1~guLw?xs~N%p z5|FRZZwRm4jUh6+#OS??=vt=!>&hgGmfhDKqxlK$v2~VCGjGKN+pOtpHGg|!`1Q^W zZ$?bJ`Q0M~bVYatcPU>iK>+482x}LO#{?w}VLztwn|EGEtHSTTB z^2{d>R3#zV;#Y!vD}g-&)7QL~%jj3WN6RcP+Xw86M3BI7#9f4~{76&B92yU;!M#)H1c;N^QtA0l=UpN#T?o_7jdN`O_99l)lI? z^>CARY7P5*ccAoz>xrleYa2|(IJ<8RhcPO=gr6Dbx1W@X6+#U(I=_CJjBzd59h$&(78ciu#H zw@EXn_AZa&7&Re8lKRUacWy^u*rmtsV$=(yBbpEZ#vCeIY6rTF+A`9_4-z;apwdz- zZy-+msy-oSHF(Cptc(eb@lngU`=ybN_4A}(Q$2Qj`o~mtRP6DN5;r>;_UftS4bxf+ zR}-^*NN^=H!N)>mG7 z`Wr%ALj{FaksH@S4h*|@G7^otn`Bz@t5`W8PHN@}As%cl%P^91k9|gyX-jJkIh`*) z?-^TXCyY6K(9WsE8f`8#?ag?rtKfAC3%Ep4$rcJ|gIs!*ZPOHgNWx@b%!c7BnQAWn zGRr+>4Qb^`)~?fzH!e6y)<)V4)Cwsz^ii4!=tGKJIb1tV!RBs;l(9$?Mo+Fb<6&D| zGgY2Mxih*wk=OR+RH09S!ZKWrLh@!9j!d+=M(_l9FL4EDK0b{|&s2evUkQP|U>2JF zR7MLTZplo46v#}z(o}8sI=-nadsl=F@02v6F<5^=jOI9o*J>WMbY{ki6NYLzD$@;Sy1&qXru=+kEjneovCGMgOk#9lcRjrDWQT zr*Wf;WwyRAGHfNT*4e|U>RGcMyDm!#vD8!PFmR0`@|G@aaZZE_n26^D6BLCW zB6$vh+e^lv(?V5JyNE&V-vbz9TUgPBF{S98pHXQm81??=0=sr#p;E=11=#9vV&M)S z@aNW5LWubznzJ7y?uelM%X$jFDNKMr=U0pZ532>akWWr)fq*aQ0VD%If~(N7pYji~ z>irwDkIu)CYT9fIkR_Y^FV@hUu6s=L-VWQ~& z@+E6diK2ogx_J=)DIHU|D(13wAPdDE&!R=~Xm)&9?r6qh~M+4I+C-cii}{ZSf_dCYV0zCy@yZwD|ygj z`QOWHR!nS0!2^3G>~@hF2~8<;$*JtsQvTHpOE;}(=Sw?6TpiqBGcs@J?YZKwf9~q( z^y$oM7y0Q#sfRyJyBar>e!!Udrt6#+%70C>;a9m^zfJKBIhxfnvafJ?UQvOHndRg2 zNXl@}aS6SOD?b3E%B-6f84lRKl3oiwY97iRRroIt-nevE(^P7q`bW;T^DPS77TazJ zTPDB2{1q1Wtr=L06yUC^lMi9X2J%Ersx!Jiv*Iihlaj9W>eLY3(UgEx1c1XfdbK)%WHG`SwV@g)ZQD*a(PMD*0&Yt*a9~-Wt z{!JP(ms7}l4SfO}^$r+TlW|wDg5{5Hc>rFFD?Y9~LE({;k z#WDo6)bUpMtSrXd_1~wACZ^^#qBq-kR(s7uw z^JCNzn^vp&3dp{xK&#YDsfC30_Bo3$L41$r4rUbw0M>8K;q&+F}k zVT|17n>*=Yn=jc0VRz+I3BL@7MsJsVXe}^lxbI*qGs1lh`!bMI=g*@9F}w~{y=_H` z0<}*Nfoiqr29Vt`y06K|qf42Ayy;Yf#y067q?bY45* z6}Ne0$|s)y++-a4J$bNf2vNperIkYF)eZ?GfHFB_wb4z%t24Nz%X6pEOy0bYo(n@? zT-Xt;x_OCyZ?l4YSh5&{7-(`Ame9lq5KLUp4WuN#d?p=!&r8y(t%gLL!!e(|#`V?- zYvtQg19tX&4Au|T%lt8T8(Xx-`-2ieVmzsjgef#qwrQZ;(pmT=!%or_9%waKclwK# z!b(T8{%*s4y_hK#agI6T8+qm4Y6U?OqZnkW}Lq0D0k|4;dJikyCn4Mt!9e^ zq)OXXGSr7_rb1K^K;745be)$t++EbjxDIY_hI*qDb@fv$XGd9RUu(v-&t_RM1n*<; z+IRHP_taDi-F(jXcjW+ExI%PMlsTJ$9)#XqD*Xkw{6d@KBy~Qvww%e{?)reLbHS54 zIYx7B(K4t{jh0aQCS7kT5{kA^GBTmjgfo%VB+)}B;HMhmmG?`xoy%kDTy}eswLCIt zJJ&!rd1cEEU16_OIlSgAZw4vkz4p6I&K9$kU^FLVMo0amvdh84IZ~$s&z^i06b^`( zEh86@-b$mz`Yk%4AMyD_+wN70WuyEI(V#4!F6paUEe9U15X!a8nXIL`wH+P{SFP8f zytZBFT2l}{FFkk5h`P$-Il_+@nBF7xZi9Z8sgoOc*GRQjQstccbBc0m=7rBrO)O2S zy_lSodJ~;=ZrdbB-j>x;+eToE3Tdj$VSIycmX;59i(hP&2^z`7r-xblBt$)bk|w1( z%xQsUs>iWoiw8`bEnChf;Dx$Vk7e{Su#H-|IunUVax*4qip@&r&wy!5yw;MCqtacY zxfiy&G2`lMt7D`LA#(*GzISr*_Qm-hcPhv&s_m*k8DQkYP{}ZO%F>nCUR_V0=@@xG zcQ`y{;r^=|Hl(W84d?}1&ONb7hcV*ZrZ@a@VuQH*s6vnYMCuD|?leDO0np`IwE`z5-uOLn0%QB!j9j=M)Nx0{68_O1WzuE1?!lseZ#%-c*6)yTXRL z8JKD}5BBRSQ?XgKo1ch^R9|~?=;5R=JYYcVCr)5?UzP$*Q=*hB5oGsGYX>;V9M|%s zI2)Y`GxP1|xr0x0z4W^v&u7di)W>Hx$=?!58OjQGY~L0lm2LOJCDOF#s6FwkWbzf(IeK zOT7)NOSc6ty1VebC)ysx2)ncPOn#p5`^IEu6;EznK^g-x%Y`uwH}GsKXbqH5w{8e= zS^mKAM9Xr;R=V*=?%7EZ_2w=kCLl@Y$Oc#x9FR z@x7@rhsAVl2h6l+ff-T-z1G!-4mrsaoGQM3@$LJ&_S=p=eTw)d|7G^~JhUN|H;cLi zhL)X!>3zILlZdh;iaLH&x;*GvttJasnAPpwsLy3@0}h9?IV+1frMAriT%(kSF94>AEV@vX?(`ar>wnlfS4S!nYGg)z0BZjNqKQ{h3xgjj^VhW zy%32)w%^wew(ve$k_^2|=j{I_!2S&AyM6r84e=8pFE9gzaJ&@KLj$JdLJBzzBHkV4 z4^T-KnELV1-2!}@AE5suNfqC?_P02H*V6~8AH|p>imj|9v<_T`IDZQAFIfRqu&0|L zE8zSYkv0f_%OR|T@WvRGJOrg3%NTS$tW0Xphsmapa9EGvbGyh}aa$na;6oYDP7Hqd z-@0fA;sKO;x!4M*EJ^p}Q7DYc|Fp?uNz>Kz4JA45GjjyD*SDt6W+x1W%8?TZ5>mSNk+23Xn|2jAMKmB+7 z9=ysAFm*>u?hA#xt|kGo>U+YTUns)Kb_)XZ5hvquoh)W;JCbZIBi z<$56wG!F&X@~lm0Lp1LdzdKfO09y@MU8)8kdYV!zsIE^@ryNkQDkd-7mI4GM&5}|r z@LFgfh|rHv#0=1^5D!L8yjxm5H<}f`i)T^UEy+wsw+XTPbVKjLLsHptJ_3Zah4lAO zVwo;)liB(RPExQH!fq8lwyri8>i74xvNuQFZ918@f$OkFbww1CVA+b88Yu*IO((oZ z3sV8t2s}1Ud^I!+$v6anIcpjJ8Z&blVBM?UU=a_U9YaJhbt4t8>@rMcMa)+H`w8_2 z8v}NdZKI!DMr9=zZ74ZuHktkp?Y28OI8j1o%w8P0@$<#~Ti?gmD3SX!p-&%TD(5=8 z29aU#(&w8?V&;n#_ z_#7Yk4HPH zhm^2Q)N0cL_NU&clNZkLyLaV_K1F?ighCB#c3v?21?QsNf4GfSkNGFpNxkbZsl*LUT8Ra3&3 zF7*Uw*M5Lj(vQaVX9z}}7!~({l>mb2$y?!4d2vdh<&{0J-`Q}PdQd8UXE9tlk@zXXFG6P%UM>^hvrFX?;vqSaQ%X^TbO3!G%bYal zeCA3pUF#`nsnXui*mjSU@NW=mZIN56=g)mYj+N)V18~VxXz%Y>OqgJq_+zaxEDAq}|E`8c(4> zjy5ESC!kDKE+tvB+oF+wZ9}9{zW0s~ojch-j>c5p7RKtvpy?@z{jf6tKUm}(eUWo;a(UR@nO7MZ8&cGSu10rYN4A9w z2i4}ISxcVnsU4aM~L!$$5GLpsv@ zeCsLetObT2M?3>J?bW>gfy3Ft?>qpdQUI2ppkTWCz`1TDPa}Bb`Xeqni{424vc*?l zW2T1#DjK_bJQlXp_4KslR>%s^&ark|CLx-Gg+_!izhm8B17-_RXlubk_*Z!HBhX9U zQNNIIWt&W(d++#C;uBF7=CBsSouGY z={xxaX}F6dGjo{Q*uXI&3UMlCyuU;V#BHCmQoMDHrnjg4`txvPQvJ!x`WXR-rYhdK zK+4khTM$^dwIwZGJZu{atXfdqU#7PF$-h1Q=WqOTul|=xNt~}tA6Ivfzs4RnawmV~ z0CZvsz>HNfv%E|CH#99nveOLjrD|T%_;PFu*Zkg|?|oKmw(ZfFtF&kPfB4UY5$L9v z4EO5S18lGj3C2G{qI-3JDmfEC@xLDJqR5d>!Kk%8<2gfmh&i&|K`2tFo6w1G0I$>V z1wN=x0BcNw<&H^NKY`fxpIE~9vL}pH{Nre-|LI_0#iKVc2&OFy&;#RhKZb>A$x)Xd zIh`{vZjFBWDJ&&SYFXYA`JL{qwO^wKCrDNCd3NNUL$U!fw|L)}(iZ*)F}D6LxyR!L z3Ux8SByb82AX&RPQg0y+Wh1_e)V9lL)rc^P`V_-|-JQRk|__;=>B5 z=@CnB#}aF(pe)Wg(QeNQe(4^i0Vn7W}w z`9VMTB@X*hs0{Or*bILjptiL+#V~;+QUk3Y4HJp=(A-Hfm= z98=oW$Ylq^PijyXVFV$9gn}*4CIMKP;NEr}pK!vEql=r^-E!DEHTqNfFR`OX!|fIA zpQ%St?>V+De0*U9xQgY>Z*cQ6pq}B)OR7r~1lWgINw4mEsk3P9$!ZTT@!e;-{f&eE z+T6P0tq+M^;|&9^xjD?LyK;M}U$;=2pe%Q|wq|eL%W2nwdmHe9uZ7$ZAhqw;xs>dE zX#3m+*ZwN<|4Rno|MipdX9G3=JC(s|8IPQ9BvDmmTVqaAYf1RcC0_T{a|H|7OCEO~ zC|ZBp`_ZRPtES*}GAniN+F2V-6l)nU)p~y))=%6=p_Z--L7>f+S&(R?pjk$O_B#|@ z#~Jz&?pop-6~DFMZ-bDyVE`P+<{IKB$T;dlP$d*gt@}ooD?{}%QZS~p9KwQG(DHJH zftGxWVAOKRLT(To9EXVj*!ui1K1V_NUj~1)l@ENfK%+11SM_w71IEL zgOb|baH^Tmq4X0f^#ps+?@Ez2^~{|zGYn{iYmlo7DiZC5f78B9HyM4Qk0P}iHpn8RjB^LbBeWBRw8 zHCS%VUuQ0}(!PU_hfscN&@5v?djt>H?&RSSFw#PqaOm!W%zJt^s&HpKE1NK454zwW z=mH0{#26?z%8`+ET& z-r%H9paf3Cyus&a|0zx^BnrY1X$u!y?m?&<|ac+vmmYmKXg{hSML88I(GZ-Zb)=p5ut z+zV$o8OHPfV_Wh6PZ8q>4~eT%<<0~bX?V;_Tq915x~vcBen62d*!t{Ir)KJ&uaBRE zWEyn1onJvz{|w;F2dnT`L_E^641H}&c*ulgMEk@c+FvGy{)UDA-L#+oPXA>5yI1#n zkkgvrk1a@?D?`HC&r^2e2Qc<5 zUG?7M&pt5~0c{a?+BVL})G4K0zotQqJmomlpdFO9xo8Y}&o);q?MJHo$bgw#LILi? zEpTB}b&2a}`vVAp#BV_})?Gq6Nf!u@LXmNnfP#LcG711P5AUnu6gnuNjflTM`aRSO z_>IGXLll1sp|427MW{LMtnl$_f;X_q7c_>`P^i1I!QI_RUm19M&auS7k7)axSaJf=uV2gZ#4!pE)ePfYkh5Zjlx{St zZiq^uz%o9_zLk&ZhZ8E{2)3aN8Cm)+k<{6$n1hyByn@m0pq6FN5lJ&8L7$jwrm7f1 zAQ>F}S6{E{Drp;NK>NkGNd3R?4Y))0YauQAJrA1%=VYGh#}k3KS%eNy>7+I|qmuyF z_HbPrlyz(TU{K5+uu$ORUhzafN4SAGakYTSGplR=u<$>=TKP>Od3hDu0E=HNuh&6o z$^Z`;Q~D?as6R|BC?c;G@o+6?3La#MZ;B&TTE>*VJ0&7#CaaP=`DgyH^V~l+Fw&QJoWvA(rk36NNjqzv>cpnW>8^1=)NJEA- zf0JGyyo^Q@CQ2S-mropYC%(dUIGaZC6Q`XVmUm2sOGb2Eazbnq^kW=Ysd-|MsBo9;!C4(q3{qn=O40S3c_;v~5Dm z>jCe@|C(Z)Fk%e40d_tpTplxCLvN%LOH1R1A_dFQhERw<*O6sB`B65g&zQsRoW$J| zem6aC+}ZrS2V6exRF2mX5B+A@&PsV?9XOjx_S;w6ESPrAl6g2$W$nvqO=hOsp4!}3 zFDvI4v+HCYasZr?lbtJSRPz{fYaPQ=gCdRxoD8b_JUcyen|YVx@y?3y#OPU0o~udQ zjpyG6YE9nWxHefb)hKnt1A%%6V~{%#fP6td0U;yiN$Ca=**--`5+cy}?Qq^fWG*te z`wZImn~1+N8bVF}MPVAE%`CJ_G!y;&$&XY8&$#eD1xPIya72RShb02ZCC4wFZP3e| zxc1nQ!;?&pF(P=0g=%L;tjgs4NIzT+l$_MIReH3L=5wG-nfw|#ybMH@%gMFu!@qll z$UmW^>8@~c+E#^HDn-hxG9?nnt!)`?!N(_KN_FG9luAA3@czy7`dZEF*+0Y%w{49w z`ZEPRF7dxNc^W-DX}@Y!2pO=*j~E^QVmN5k#e_f7{;&!agBr!kPmwQ9BZDgYAS=Zi z(I#tiMB|A67QslA{(t3TD4qFm@Z-LM3N#^kF;x-XMCg?tQ)*@L{$L9r%qjnaS+Y$* za|)0X^wAYRQ-(WH(!>&{`pESl6!JShro@4>Y5Eb3Tfim0ftcpKKDo6ggG#bhNq{Rw zG(xM`-&$tw?=8}?>OX7^<@cNS*IT8WA{`i!A~59F!5^;pA6yH#tAFbpcscyZdVlvu zqX~E5x-X;S-=NJp|2&F+m(qWnqgV;I!eQLp=w!}(t4n78<}&StTDc{z{?T1J?#}#X zzrNg>o||SFaM28z?Pv@f2>9BswI2lM8$&IkiK&YN>YXUhv{3EJh#{7xBgI-rRnlP@ zx$(ckW-vzY=0LB{1kiDlb8v2v;6G(-x#OnRhp>^1DUB*Ug!h$@mMvm@)9=hQ+|(kt zsd8{2H?)BRIqC-vq;04EzZ$WBGitB=`Z-(4C(o9++4c{;z9mwhv`JhA=Z)O~(>v^mZz9>qXeE=QgORk=_gav2f} zDWeYjveEx%y!g9W3jb*F;-`yWx9LCTSYrdEiUt%Mw#YIQn~LrCR6I(n=!+G+oh_R4 zAh;uOr%o}rWX zs`YZr(VS4hY1Ppg5Cvjt;HWGBafnxZi+;9efC|2jV#S=il4JbQmV2Ppj?&-pHbLhp z|0<02w4?VTix9~NaiTIY1#B%o6$IyI37q`_;ttZj7QBvzZ3uo^aH2h$xbO*WH;k>% zA(t?~czjObedTQayB=-%Z%_8azsrQEF@W4B5h$-`;a~mIFpm$#^$@o4FizMHEraT zPVa7{QA5fjraKYBrr19&@ekWq*?n{_`tp#7m|Ui)LUUJ3kkNUi3a)Sh+|YeQcykWw z>Qc=dWoj}Nr)(J5($sE&KBe~3FlDgDh%{mFhmB@zDKc7vz)|oSBBNV^h6F?lf@v3^ zM3pYPdb^`Cu_l`OMHyXAH`*vn_S&R#DsNLv+l+Zjqnk-Wu&?<|oUXLb@Awa%DRb^^ zf&#aEkaqvK=j6`?S0@8(^-GyOxL*5s#M%k=q>wz)%?1t4gBkdDm0>> zwPqmu$bQ!Gr@M~~3?qK~aPAv{m(K1~hXb^5;e79*-@g zeedQ>rqBvuH-z1pwhr?849(I{zdb#M4dtaPhk+MHS!S^dOP1WXw#_I@`Z?%D`P&Zt?8FY0Ziqr^2H?ME*q%D$ zb8FSU`wK(ZA>!fNkgI5Wm2p(EVPVqR^(&tKpffri$rX@6aucnE0+{#c?I1K7RqICk zpmV^6A{`Y4G6r?W(>wsuij*Ra3uVf<0$g7Z{Rq(XG98vFc?IqR#NgZxBl|rGaU-BL z{VLcO;D+f4Nzxh!Cg3iszQD#Kd~+^=hXcb$G`WO78x;xgDBg%4ZW%QbE|))?9^6aa zQR}L*GtQ(dA{pXo3)(FcAYBp+k6MrBbkR1UpSd75D7emzjxgcbC6_YLH>RW?OCBFn zQfu=;+n1uhr8damzw4F$=8f*4xteu zy5Gq>4nyy#ZVswJ-F{+ySKV2aLSH|49jdm_yjChH87P$VKhL(>7ZQ28uDrxYcp$4n zjyd(y)2JD>%d%Qo4nD%twkM;;f2SrJ{x?-NV)VaThtmI`VII1l2Yh9W;m?rUdeSujWCFe`kXj2^aT}Zyk_9&3%0!*8gQ@@>k@vabbmfA6#Hf zP)tuuaWzE#6Jz9NmyoQ@1B=roSGm+4i( zyA_;|yg^N{uzffKKMOX}ue%WJp*Kp7DgE}?CNbs>B;uoLXOO<`e^ESrfr7!M5SUhj z-We5i2bzv4@kHQN=HMbIc~#J-B5m2=Jnlyd6dIs7ZX&N0^fVhr?l%@?-j9q(7aLD__Y9;Fa|V+vga$ul?@)C&8~?RbT(i9Dvn`N8r0y z{KvKAbZc4uekVPt$uBFpzgjP!g*KSS6?_2oP7`B_!cycl-d6zlp4N7g+ZXyC{Hv%_Cj0vzhF!QR_A>4LU`^8%biu?>_~w!>&4@DF3axgI-0`7FGgp&QMn zNu%yI@Ku|uoi^M)RNK4h_}tYA#+~Qhxg;1*QQSzUTtiLw!gjfkX3wg~Nu>o~e&L(1 zZR1G~^8;@bNSE_`YCnbGli6SKO`_(J7Es%uQyuE}%1WTpdoODQ$Ivtl}E;p}>!m(>yXu)OtfejXF3hir&R|oPAqbkcV@l6#4~BrNnaoLju!Gy$`YOBl z`^-%_MQ~z^zu~ z(N@VSxo4A)uKG~vU3_n03sEXs5Huxgx^RG49Yh2O>|y*5KbK!!Ya#Q<;cC}8ZeG+> zKm91p+j+FGq5ny+>6A&_qFn`nm<~8&ug?i;7`sP@XvgSIqWDa+3$AFFTiSv^d&Aj0 zjWsE$NJS>Ud(FF8DG{3@#!&k*GW}J3((!jLBROyYY&7dfr2VNWIX5yKY(_M>NCxk} z8&Yi##MoYE(C6>aA*S+}lEo^NJ2KwOp*DRZ{3{B7`xWj!$^G^}@@3qA|1M>G+nOfQ zAGaLe9ph1I&ZQFHA%2_cA6LM|JcPK01sULjO01rtvNWVTgF?)BMk37=+3ZB_sJ@Ic zLdQkz;-ZrydlIm{#=CZGXcC*?%{)wBglm{{+VbY@0cfpG^tcgB#}EaqKFbPUDYMuj z)4xU2D@3EKoDWoLRtS$~-Ya5i#clSyuwyCvsqXRjwB*nqDA_w^p*8EpVsb|nhgR&c zcWztIi6y8MjUXnMY}e?I?Nn|S;d2D!4n|D~5U}_ogExNQS2*JlV2*6T0WVVQ9p~28 zCxe{IM~nZhjqWcXx^Ym)kCY)ERE5L(K=<{Ob7F1(B%@yT_o9*~^lykzEM-q9K^(nA zHL*6IGkDtK9R|H7l%%heb;!!aS$@U+Ncp3iBc4tCOQR=PJy%`N>}Xuuf5BKB?wr(6yx}wN; zzBczmsKpx3{i3Elw}Thk57WnEx4A&`aune_ zzsw*v_5Wk;&BK~Xwsvt86_Lh>GPF!l0a2M85EMe9A|j0#XB33k4T^}EMnD3DY{dZ) zAp$BYN>oHtgebENiHs3ZnL$9vB=eAjA=!{*`zyLnpFX$S?|0AnzWdzg{?QE&?o_I3 zuUb>R>s@OK2}yoFoB2xDkiaDI9I(sjYkt8+e>yP9x;m*wlSOqfH!{7UcBXhh#0D(& z2IZ7lqT>kl<-pl4^R#Dm&$>GtpJ75g-Ae+WP(U12BJUIU73u47u7 zQUu+_Y`A-3Gh=`9iNIRFy`(k2K7ZF(N(oD;OGqiT_yqZXCc3Td&XaLLQka3`yg*MJ z0A_H33ox!Tm*@*&Ft2A&!yck+^+pTC+B1E+;35c{ZsAxmDsUXGUcL`C;I4uKW~di( zyz?K8<@o1N7m*d30RZEJ7<^M$4Z=3L{?DZ+E5h2wL2UomDLBe(`N)DtKv`~O3ZFF3 zxGRI*DCEikQ06s;g0CK7$(O)X8So4yLa$7wstyr8q5u97p@0gniIQsoYh9iQ+zx&a zltIExFWoPL-r;!5eb5tl9&U^_MQivFnuuCfL$9TEd{_@o+)t2qw#^g*^hc9jM22ul z1!IE{RaU1;^5PwwYS}oXhn;UR`hjXq3)KF_u^X^geH~ByNZv1X1FvZ2!>`igadDtc zoXOY0rkP^eiE%V?Olshreyq3->b;yF_sn^(CSE|9VmG4?$<(P?oj_w z2}mJbX+$GO!Mp#V3}{h*P^6wE>_c>RLQ{cT&@a_pzk>AF1|^wB0TNeSL4*C5gX*(f1iaVSfVEY!jMh=oW}1DCzUh*`S3rc z{6Blx3A~pUuz4i#ULFhSh)&SV_A5}b8wd%&>HJ6&x>BcYEEYiALOgP`iOIc>aHqU(8Uz6$>h)rAo`8s`#cr5rT-BtaCB3ahS z%v7M{H~dQli|bc`Od}j{-1rcr=8XBEoTupq^y#6=q zPG+g?*~tn^3k{ij`AJfUh+fv*1k}8fA@}ZW>sncOW&N=z zq@y+;m*JWSm096@M!Wz6auh`u*y(dq7{`ToHtK}}C3kqb`lTS8A`po0_Ry0-%$P}!ZRD43&Cf8ale#X07!RlNoW1dLHff{`v3ch zo@qvl&b4Uw0sU_!BU(HoCo}TWN1msW(N7x7bbbU@IzQY0I#lWj^z@uYcrFjso-Wpd zLxnlj;mMV>_KOEZbErtR3-M4$=}cFEg6I?m1(@)MDA>c(64sK=??lEdqLGaSEqVRa z=>j49QosvO1F7?`x54E$XvX64>|YB-73ei=c#T9BO8LYD&(ob7+1{d<>{5$a`A(ZzJ!qUc>gpH zR?a9_#x5@zLYAOlpeN)@1ee+H;Zp!i=Gr~6N2v@gyaSa1)6`ERn*$?V0kSl`VN`e* zj*|}V3-O?Wp8InKG;T)-Z`h*mEW9n{+W|NY{|!8p*59#%*}Ey+e*qG)qp21_vA?*x z?K~=x*P|O*RkrkN`T9!5C9rk+fLlTIo@#&pyo~nTA*HFPyS@0irC*}Q&Qz~RyzlxP zAeHAppz3>)#Tx zW$MYU$Xj_NWexjwJF}wg5QqWkH-K?&AAE_+mW&)YTOqzBI>wT3nX&Qji)78NLt*=(m?ihdnUr&^t*Q@hMuR6O<0@`yglivCm_lz5L zpZb_1TT|J0=Lg&N)~C#|z{yTAURWSo&dzZ?Pc|taihZIilaE4eI^OsJf_=94x@p(9 zHbg-4uxCJX-CSJ1nD)faYm)>YPROnOu_ zE$_Jv?E~TQtBo0c(yleUCj6W5)yJb-%+>Zji3W+MsQ0>IY6Os5t1zd4y6LlsDNx2* z08u-2a95@D(=~VlvNTYf0i-rbIkEuKSt}3Dv9B$XLBtnky zh;u-oDIo5mUgJj7$N}cj+@@D3PE8}YhMt%ud7vTmk*)6=aRv6!f>$R~n<+q@;R^cO zbhn^)lMk1|wLf#0o?$2rgjvz)f~|UtV#w-&Zw~<5`V{0B-%#t692^7Q*GkZ?7JPv* zTZJin)dHX|&;Pb2dP%<`=R1eR@$Vm|mjY&pM1~qEO5EBkJMxtrCQQF*8KLqnQ2aoN zz-T@rlgXmL9`!vGKMa_AKGx+$c>Qja|7*aNDia)&Ss;JDYpE4$-gL!pXrr)L2W zW%jFAiGXnFDA2=p3eZ_XhZW5q`7oYX*Uqd3Jt78*ax-8+DRS{3z054d{uv*>b3~04_n8H5Vrf%D1O7JEai|L3rhZ7r#uGX)C^DKWybf}nA+k1a0bOT;tAl@ zA)O~YtltuTxc4RJM{T0!sjEG>&aIEUaQ46}{;$4LXgniV2k_IzKt)1A`ixMf&M5XZ z#&X~wU1q|rgENYq9kgeTa_^L1uN>Tsb?$F)P*DG^;{su|>=AEG>gGOpuUzlAy!s~GDUB8y056MV63+Q04gvWDTH%*DOk zo%5eby-S*U3j+-=hO#Y00o8LABJMhnwSdQ7EOmt%YG?Xd&+*g&4!Z|hSj)@{k?S&J zAfW@7i5#p~>b~h(2L1KVZLJWh1ji#PldLK#7#3}#ph1kgV>W1Z@Z++So`MKTT*szg z@bH{tArDboA77iY=hc-FMAcr6J<1-;^ftA4;=GLE6Ze4}qnW;V&WruB3c~ zfvj!G`KIt}68D|Qr~SA-7fS*_FZQe`K4{5DAhGu?wuL~4){c%(@4_sSj?Y;aFrueG z1|kTo<-aZ3LJZanyyxW5LC_>qwsz4O(Awt5Q&IrC)u%INn1=s~ei@p?GEH%Q_$epC z@U3qO9u8^X3PZ3h<{NGlT!(ZU7t^$$^BaU5Xi zAw(rnx*zuATUQg>8*4dZFpg^+o%d1mWH6kk<2RM)M6Cm_Is|KHdod zC5S2I9Zk56HVbJcD1lxQdPoanwkRZuOd|X9sPJ~rzL5^s4zv7-$Bm>BLwU=WvtMkH z@%M=z>38#}?Ox)(H=qs!sODJ2T!^aFTTPjBDrH%N%;_mi+$u#~3(5#D{`@t!+04}3 zA6%Lnw>RJ#G4#o3X$^*z@RI^kluL(A@v)3 z^PR_WTmwPR(oIvW(J4BAzxbg%C6A~GBz!f~*P_D;I2E|Xm~}+ahH8dZ!e)w5=}YaD zSK^TUHAa%pW-mvuHNC(rjWr&@uwf+uZcDJ>B9v<(QwQx)mvc~y$$GE~kJdi^6a2Gq zs8V0MWs(LxRV(iKvYjOz6H#Ct#K$OcM7yfHK;%fJwfwY$LkbK znbejP!mGMf%?t?xgub+FkF2{J`|jq{#!25x*NGE9jL~x19+APOMOH$9O6x>jtajb7 zKorB%_Vu)?H=h_XDP86($#Ll$e3!IHeQe~zS<0wGg6sA8Ma1r3nDG(zT#FHRkv*au z!y&>e&Lv4LV3s4C^O*Few^ZcPo0wB^gC!pLDh&}Qm7EQw_)ODR>u@)@}|&&xS{z_9SzszxX8ka=I? z4Sx>(X$s^Ofc}|lB7cRk13%Roz_;JWy>6v*P*ENCQ*@}6){K>KvQ-acbz!UBX!VR~2INDuk8f&h#<{3u*h!3pnow`6LNRPaT#s-i=W zdMRVdUkgg2tk@A^r=DtZcQ$(6D#eFz?eF13Bn<%=`d#c8oG#NBb!8eIMKLC?Z_E9- z0pDD5w@=8vYHDGTdT}H_ek$JSqCSFYkR;#}v4_8w0F5=b3r>CkHqDfQMm~R2m>)Ev z4cau;#Z540lbS$d);^NyM!g()PHoi3YlkZtN6&6IOu(C4k9|6BPq<+dGQ3~vR|8bd zWBKzEJt2$BtaL_Sp{x=aUs(ws=Rk|x>cV+H9s{j|Yik%~x|GwtJyV{|sSR9%V zE|FQ&ybZc5X*`b$`=$Ui5xmN$+QlAOa9p|-DM#o1baI;VfTOy;vx=g|%#L*Tp;e3| z6((@M-rj3ap;uM3)Ig28ZYBQ$6(x^?IC)mxE9B7|X`MsJ0*&Vd%#QX?D`%O280aLrNC({ZxfjR#rr=#jE8;=D)n57tuu@!N)}t#^vPG?yQ+*6J(OhXeDPvJBqZDo8fSB~E@5>@ zP1Tyr`J*qp`zmP*EilYQFlFq=ea^8vx|@c_l9^VJ6<>1JJ#^pWU$#F)brZm=5|7Jo zGS3K91}W?0w@VH)4D%aS#&sUJoY|LGl$~;P*ojjZw|b9^T7TNsJ!=zi?mHck1<$3x zuPMWB%(SRL=NZQ(Zfgy`4);!@M8C{j+fzIIdv#k8&D5iUhiqm^vd96;RqL&4%&3A;8? z?j0~?JmTvkiV}k(8Tpw6@cl|W=0%Dr%o6sox@X5!beu*OH{tTlb0fB)m+LQGG3WH+ zDb)D8u%o|#lUNdW9_IsWxSx1#(p!QmvZhnEEwZnItvN}WK&uccj)z-n**prO4(FUc zALC?Qh#tVYLZfXiz%Q6#J$4c{@sg;FAISEiFWOe6LgtQwwvs(bnr%+Rr|n%+IG=HI z3_YhLLH-oIW`0k?5o?hiWC6SeP}70SO^;)8K)AOw7qHL6>!sybOe-cZMCAT9Me{IC z>g;0m9F;WZSLkIN&pilq9>z`HPYdmffjIX;Fpe7u1!sZ|e^Zd|h52PR`N^U>zGGY_ z#yODdS9`=P*x*tBKFqI29OqUBIQ6QI)u{W(Pw%y-avq`vn#6v;t6f{j&&9T?Bk3*k zYW!d=Io85?p3CuxHngwBu&x*+7|gukiKBQ>Km!$N!g0X zdxlL+RnhI_w5p6QM~w%~vsFT$j5U3bZr}Th3otHq^5c*>;eXgeNea~ToFC*5&ft6q zfPJBYh$6Ad_LEGiL)M)N^xJdFE&T8)BBtnagMF}We3iv?X^Lxd-L35N*z@vNIL=Gj zEA%j$4u&fGV&~uPc=|6enro5Od&sV9d$iE zwN&Q@iXTOSIr!-qQy}pYVWl z5^d}n?Y>NR{Q1mSH#6SLYtC(6-v=w{igDSSpQX;I zZbx*Tr=sz&pVS>@Bg%kcK<4)vcH~+7P$S(!s@>jFV!%;v@`>;_Guv1=YM4B%#_DyH zzR5x8$l(&&V7}{M>m%U?{zb58Psj^>O{uJdEi>@cf)7IJer^w&(xnUUo(qyblf^tQ z5B>Eg@1U)^_s6%On?M%*j?5EI;}RkX3&<{_#Om=-8{DOd;x11ye$>5v+c>a}amyc~ zK3be#hSbx92dUR-XhZpEv@p=230ZnF4ohP1DH)rL@RdJ_iMXx{on?9sjqwrXy&Qi> zuEnq#$je4UKYop4Rip=Is(5SCtUhxJK@)ppJrOXk>8Njz+ z6#qIC7c#w^Phw3;jdnu7HA*DOY<*UN_(Vh*8%MgBz{a{%DL{vsU3uxUMMUu{Kz{5` zd3%nT>o~F`V&rC0s@p zlFZp$$t9oW(bJ~gj&Uwt2TEIssC%7tcSD}x0|Sk5H(!UpeE38Q}?1Te(}nf(xDU%I*nu@ zGhzzu3DcXs!J_zdXnZSyabS-Uzpo6{0pvnMigSAIA{2*@smo1AYL^NzcTgsLI#*Y)U4mTHP zWN9Z)D~fzBh_H6YZ zK~3ZI*Yq}@vL^*LgQNEA1AP7ThH9E{FZHt`mmRYarAXcaw{c>ZxHW)|?N zl-Yrn(T_liR8c4Z&;x(lnfh(Pi&ctOg~V%^jeJODfU!yFA=7>u`_io<{CI@#nvcXl zqD@rX$*;Thj2ydlb=BU{jo>Ef5lSsP$D=3ifpnW}yRhxTXzh9KBx64Fa%KsdUmJU>`;*EO zhGRo;spFQyaf4X?tWnG2hD{@4qYAD^omZUfjv3s9nRmQ0wrQZyNB$BsiuIzCr+`K-{DVz6G#7 zYo38PA0D`)`>P_yT|RW;FP7D&@;Od z4=luYbE!yo-ge{w3bsl|R8YUXX~g+L1*CoHcrW56 zuPaG8V!L~NG!AfLkkXOvqb0_McrL;w z1FUnQyqK7bci2xA9->19^zucxyJK5lcy?9k^vv_LTTLYq*DRz9V_ zu+?+WL~nP8vv0?z-f)%JMDvQCFYXxEMGWQ2_;(4*`yJh;RK9cM7%+HgRv16&0)z#c zU#xxxOL$74#p|Q~d%G4N?Pe2Xc+pYK+w~5$CDfHUJ=H01s>tAlDidXk0IKB(P6!XN zW%aItTY$A1gyYxILI+|L!#rD*9>w%ES;=fn->@YKBvJDscGNSa=aTLM9(Zjo>3|m?ViH_efZ!DcEPUiisNt;)DD!{J z37EORXnsP(-YxoSLN9TgoW?vUUoj5)`IHbJk$CURi7N*ATbq|PdqwWEo;qt+k}!uH zc5e_dlI?*5gv2r}=3_BA(GUS*PHs{s8MFxt6PnmWHsLMj@hHpHG>tUVaLIp zhQ;@+%c}o)^1}>mN;lv$)T*vq+D_g8D7nMS_1B0rA0BlZC^}T&7ZPH9lWLf};@Xb* z%7D~2%YN0`C)u6G97&|!-uW&b$F@(AXYlCXk?{Xm zxx*W_f&GRkb&MZH8c|n+BJ5e&M+e&0d2CO@Eh=#hCNhlKQIY>37Gez6cb7VVHRaJ$$6JZPz^0TiKy4-CEpo-Nt|?l z=kGsizS1#aQ=`-Tg=0J7IEwG^nb0bl5RYq5V{)Fcg-*ndVqRU$eyJnRm_^qZ(uy|y zwDeJ7edFed7{auV?grU?sCFg&0q!_H4nWDTnNg`R28pNG5KdF_jA458wn z+IZQ=i;ogV!&?Qhpsi6m1X?GJ*zyag*cGIZpM<-M8d&LmZ8rCnpL*1+v1NVrAdb<( z4AfrTAK66jwFb6Xx`FZuSHK!!NquEU&0ZRa0m1@Ir+Hg(i%WjsJ zdg3A|Wa*9AG4jiE3;jgNi1HiZ2HvL&(j7ES@^Sg)5=E(PChf%yZa8_0v_Vy;7xQ+dL^h1#^pi7RIa}*Yn?BG77?!dPw2R;k!;Uv zF*6O`?6YP1dUQZl_r8;>s-NQeU$u`PqSqNZmY|@_Z+`{{d+(8+#7YK!4u<@ z_umx88&?&CQatx|XTTt>mk3hHE9EZ*ke8~Kc(>@x1EIhZo_a{SuyL}akz11OEZ6HR zND;3ZHMn2;meRl$9w-6AqZ6fEhOG^7E^-o#6ikk%n13b?!lV{9$5 zE9}du^*A$L6*d{0K=Q*U9%#|%!>|AJN!`M5Y$dt!y0NHDgp!_v$~?gp!6T+JWfjQ# zGlj1Fps?OV4oXXP1-l~UM`1t<#@OfQzTvS+|8wH*w%X!PpGBvSFLtUty9`PkCbnz6 zW$Q9l0DV*i>L|DJm{(_yyEG&E?L%RVd(&pmokx}&awg>T7sIRd=nu4}x5$SXcmb{z zz!Q#m&JhVNGK^u9pWt}m(BAx3OS7}Bwq01HajT)0)%dcYcwK0g(zVfyDHd=8gGyX8 zNg-S`$auBScCI1j;v*sTjddtem@n-^d)gGMHVTplJAqI$KTodvCvOcQ9-uvA-XI2K zBOxG(d9p!X%x}9MRQH32sY|p${fIYG-_nbAwspM@y1}{01L^MwsI~IPIL_;$-cpqxb0`3&7RXyk5#Xr~oIX zRthfGrfoMvrSuU1?VB%#S@^%{4M#+ zE7N3p6R+c5)eS3h>FqTB^>ad)x~+NgX`!Doqru-Ykl3P)NA)1mM1c<((kAQNCCH z0^$hlHXvA;QYcRTHVC8^8V<1GGj!P2*7=(Pm3~PA-1#qgiXb^sgpBk*L~)G~eLP5@ z9UOo}lR~R8NP5#4l4}_S+CU?<;DEl8KZJmL*xtvb%hVOQmfa}f7Wg&SHn*8j5mH2$ zCc6@f@mQxH$kl?e5W3*(cal8+px*m;il1Jv6r^oE_>mtgDw)Cqxc1J9_ge`lUxsN* z8h(1jS63OVp>6QVM=7U}UK2B51Zt}_;~FbvLQ**QdXl32?x-LV>YrU05MSb()fClB zeaiibQO#J%9IMY_3XfZZl@f7B`yXE$#d`lc^Z75zO$doNApnL>Erm{jHgOEYZwifO zHq0acD_C*nF8@D-==>{_`2Xnl{~qw5{(nzh-Xq(~^H(a@*J&;}&a=Il*A$fDYhnHr zdZWH*d8n>@$x0@GB68vo-PTETyA81;u==*Zmxqq)Ue|)`k3mmG- zK*~Jf$0E0Zdk!x(&;4rgW*y`c zAvbD7DU;HiGDnmiM_CB7Duu~}MPFbYSLCCMo9UcD%!$pEP%j6i69zY^>kmIkyw@Uf zl`X0jFK@&BVu7N(4O3{t*mBq?_zFrRxpe&~YQ)Zd|7HCRc3&l$O*?uW$cqei&Dl=% zJ~@}t+OTCVd7X4WrJSY=`LUyM%9PczUCkR~^qe_;(Ox3#wW6R`tRE!tm@|v}o#&+S z?0^*1j+8GGsW^mP<* zdGTTgvk!D>b>fF5j&~`c)@=imfF<|VbEs?`WA-3Z7i%Yjid(>C=m^w-uJGj&7jIAO zj7aJDWTM_w@j1Qy!|R$JEvnw)T+Atw!cZQtKy=`sv z)V)UbwXl;ysm8pMJmf7u<2U&UwB;co;GmYh!Mz6QiFYM|TxTkp?9f17$}c^KSI2Wb zOpZjFX*V57*&b39sciaHb=meY-Z;6=9IGVDSv|qL%H-T*qOd4RBM|Yj9aya)PwQq( z1Q)HeGTI_4w^Mr9AG2RS`FKy++^>*N%!dSzc&K(KcYH7Um(%pmZmSeU>>1(?4f0kX zTHZ^O`1eixMQGmcVu+7ZFTZZ6*>>-C{p~X8)ZWKF$UQCk=YPq8FZ8LTtZ2j-JR-mu zmHX4uuH2oIWW67!tiJY9JX<)MxfaKvhAqs?q}007@*J-pBW)B=DTd9+@-LPAzAJTy zZmdiOM{YpaIm?yFd4-s@LEJcFISr$Hwl!rX+>lmFwPRaea|Yz?0C_XhCk*B})Pn&*FRymoxjZ2$J0 z(&D7rt=hzUCqKl^Uh{A%C!q1XT@#|Ib%EKxF&)Ur0Z4WbEqqm?3KEu?IKVKI3ZQ-& zy$~D{C0jC%Ty?Dw$W~ek5Jym^$p!g28Gu%62&Et&5({z#@%@SeRQRwbNY+1Wr2%&x zBoagiOVbJMgZWMo=`OnU@34;11*w!33?~r8lb|vjuKzL_3$hGeGntRDY2&x(g(a%O z)N(7zY}n`VVN$sLD|54nku~jRX3NHpzC(_#yP$o-(dVrmk~^zq@LpEpEqmU$Qxf~};`MQXC%~O71ot_S6sTbV905R+)ek`Vcr(f4LoZV88nj3u_#cX2tnLo^FP`t;ko4^fSo)>T-YR%7YP_-CCSE;*EU#~sNO zjixrfpqv>8nEr_uiiW$*VFTeHzpNvz5_L*)&!T*U2%y!W9_ZSTf`-SCMVRqBr=A0C z4Ulk**6xgik(l5zmbiEZU3nfWc|22m6Lk}LPZ)0kX-wFj1kzKtf(3+mxRcZ?5Zcrt z4}Hbw(8-CuxXp1Hsi$l=EZ@^Qu&XVqL)3^N$(wPop84lVMokn?njWS$v(rgJ~#|;5qPPo)uA0C2w8*}&44H=!AK1) zpY=9YN&H&=kYNg6g=5}{4rQcnJ<-b0XwCX6#U`E)e){J2SslOfs&FPrqxi#be@?7WS)az*u^BOEr^9R#lIkbMIq)Vhd*SN7d45HKYHQ|V%ba>Ri#!zAiZYqIDmzN8zG#9BmCc~9Z}b-J1AC9$yZpsU^DO(Qrpbac{tsWXq`9-w9cGFgP^$s5 zr7s=a^a-zsz)r2{|Bg%q&61R!b!Ds<-cAk@huwbeJEuWDaWBXbU(Nvc7JnC^@pGko zCT!SOO}lEAMPhR?`Uawf1(v>6k6x0^T6_xc?b~NLK58Bm_;zaTn9~;Y3-(_%4LDbq zFLQ{~s=h!lHGun}LD&GU=>EDp=)Y~i7W6LYFPoor?UT4}Pl0po(tRhr(FUo+Lo&aw z0G|98MMh5}YjEiEWSfPVv`EaXCrA3jcF@p?em|$Xr)9oeN9DwA0wP+!N68Nqa{b>d zvOc7lp4H!>>u3HtMD+#keI_R6N8GN~5fZx!cY!b$YddhL$hcad)K6KTlbcjmP|z0C zzwt+IB6>*8-0Oycv|j1>UnS`8s(BnIv#t1zaA3O$SAs0j4gnNF4c`~i?`Xh=CbAQ^ zE1=tK1=2mhmm<5KudI8|0JiBns(k{yT3n9xaG!AT==dI3hl5^7TF>7TYfzN5t#Kr% z@4<>5O?#ql_}gKW`mE7Wp5-_??=0@G0+R9QO8!g1w zO)n>)n8G_v%qjiz*gJm{B*(w1?i3*?w>AR8#|o;m;D)u^e6{(k9d zs16VA5xA;6!fych$q%PIR|&gg1H^WOy#={9T&uD59_ajyM+95WL@*fG3Ued zjivf+dkfWptw19Ypi6--&B3Spp3>pwTlpbq_Sf?u!H^mpGU@TZoE2WLKe z_Dj^d93&yz%i1RB31HcOmATSdu20#FjL#w4AgZu6H`ch^&Gx-yCCee_O7)jIV>YyA zKA#%e@n%z+BS6qhzk1cSE01)L0=K8)tLMly5glB>*IjFx};QOZF3LTPyIrYr;7dH~+O zt`F0}HNkf@gu=AfU+m?{ffR%K;4VPxA5z~v1wrrP(LO!*rrf`Oa9b!#D4(Dl$y+N1 zP7$NR70d;&oT*>Nr7FAfn=Y4KdUO4q8J`Lzm5Nf5J6q4&wSK3zK#r%^qB@$8eXdd? zs14GE22#%B_Jah7!XL5nw|}E!gY1InDzU=^QBmXKmCAo8(i#?VhG>gDhe5e1$VIk= zn^*!C^d?U64XEvuoI>vn5wDgP%QS@H)sQyBf_x747r9`57TL1yU3rdBId-RpYU(GN zsrbg_;|BS5rrdGIl1u^xSVkVsM=)(n13hZlLy#;Ml=$bmer=Os4aDGIABT$k09F<$ z01j+38z%b<14n)PIIj)S83F$g4}e1{*JMCdMpaSj*q|uW4B|3cL7qmN3X@%j<=|oI zZx4gl`;Uk3{{ApDv5b5ed_9y2oXU-8Axv)=`#p93$MA@r_~`fcEu_VVw7z`&3XVR{h)24=J|rxyM`E^TJn{NIKp%B(wPh6VNw zbzOcR>bHl%^sh)gLF8ehAV2Y#xe}af5itHf*m<^_etNLSV^-4oV8dKI_g0XTie!t_t%n%Qg3Bv%RvJL;QkDF;s0bdMt z<2U@46a4(23&L^7(BM{H8K;5!eIfsp4f`4R>my@c`X9>y3wcKY&?-aOfj`!v;6)OI zjDWyp?j<4qJP&*BvJ?y3j8}ye<61yY5PrnQzXCze)A%D>LqK6tR^GInkO&E#(W<11 zs(Yv^T&D?dcl@)H_axPH?LqCdyp+sS;v{j$yu@z`i%VB1a}xWm%Tqc>e&ox8DcOG} z#s4Ul|4w5x!pnnGwqQcwbx|#VRMgTVaT7t!v!<*5_|X66=iHzvzcBz-+N#@;M`xjQ zzXY{mjfZl!u_wyW=9Y*HA*1oAsZ%Mu_kJ57A6Ba}ER|oir0Kpdgw*}CTc7fgBEoK( z)F|MccRfJu6f+S7EV4yHM}<&_Y+%zxam2i94*{~S35;f zliwnTpsogI>VN6-^v!YWI_zP@ykjsPZ|)WIff{ZsFc_ar+{Gu+8{Ph?EdNlNfToP9 z16OQ;134evS=}bd!yPB0eXx(h*B(mr)_mq2FE&29Vo8<4xe3=gTn=u;NEjo23mZH} z8ql-yj9bY@JdHws8xiMTL$79&T?wtIFmCgb#oH@x*ibf3Y*bKpeNR}x1X6t-w-mvW z?d5k7^r`GFQU%xRi1F2z9j&C)e4EIn%i0aE8YC`<&fj-!$^Db);HYaHneb3%E!_QD zgsKYEiP*3`yReyf{9sphcgqh6R%~y3Pgm(WN+Sf+!fDh6H`IuR&}!Oae|d_b^OdI2 zv@6c8Q1%D$7-e*e;VvhYI0uD@B@Uzz7ODfqp$|84`YFrFVIm{y+F zk31F7ho-ocxE9vWa?t2uYBJ1Zn_w*=C=JUI5#91Z4&qACPMLJ%CsDq8XZ6t?Dk&A= z0HL$*aUsaIz^N4sj4(f$Pn+-Q_{`U)^odr!_1baW*71i4o0oKKKelxutNiaBIsbck z?*GR*r~eePKdtot^0yg(?G!!+SuLD*7bLB&pjGZ|;4`m=MK?@X-`yVHemS1aug%W_bkWSDL1 zWFktate-r5{u^h%3dUJzEnX*7 zDi`RuMO<`kJZ-3To13szee9!QTrqzNWzoT?Ur&*|8$PwlW8vq=Ia)22QeTFlU*)U-)xbMulPD6u@3wOZmA zlFkl(HUQ=EZz5E05)7ZOv8i6^yI>KeC!&RGvCxC$zJuzRyuY}`ZC%yJaf45QMDq^+ zD*F9-+rM9_&}oP@dA-P(O4jQoTQ|>(=5?tdU5^Nx17~}%62E>imgVLq%Z~yJTW7U$ zeZrHo%arQXUC)EOzV-waoCa~c$k8P?X?M!_h-OC|&Gt%RQ=aYWlis4`9Rs#QrT5inVD;*ym%JF7o`~4K^P=WnH@>26tt8`rRY}$qN4Kfd0mcT%TmWU{vyX!1&JSG zKU2ikLtD_*v?#nlG=78i<#3EC|)MN9W3ZLLF|xt2wxS!7lI$v zaEmh?1m^d2V%HoMxt0IlV+o5jILQvfNJz_3Z~*cN@Hk|77NPnY8yTxb)c|qa3f1a2D@9Z zi^x8O4VGrA8{e>ZNihX`9F6bl(n=C=Y~w`q^s{{2C=zNi+K)9y+99C}yECV%dr3C@ zh6iX&U&9y0;VsyecpqLTyXoH53FRFXR^{ zQIY!A@_VB)Wo8*cO}2%+muF^qswmDP7+Sv>1E{@5u&1Gt%cvyX_-ZTpr#E6-=I1Ce zp-BF4g4U5BC@&}KpG?sOan`oBeSXF14h;~A@?Hp&_gRzpEah~Kt2{Ke$ z89bpi0!fb}ZP07uDs%@EbS3iT)6`Fa3#CVy@Yz1@+^W{}V7s3C`YVb+swec9&HI>-XqTCwwih;vDyxgjXXpBy$EqLcASLZCv5CFo*V#UNnvSVk>oWIA z(!BN`h)9NnQ1m(F(8ovy9nO;~Qfg>A002!@qO_tlO7!MsicoKrwNKhq;LpbT^*9;6 zMtGYkb;e1C*F{sW-+37u0H|s-(&o8bUQ_~dOLOP7LYxQPOGUIQGaqMoxsdIY@E$)8 zexZum-<*eg?N)=$d+sslsyGrbB{Azo#y?WOj)^J4wuuVxf=<9`QYYDwnM6Bm?IF*y zFq_2be6Ed1KRS4>ODQQMN*x2eyxr?$qBdRKpkVShp0Wt4%k?M|iL=| zwP`8`qEnPqD`!swd{CT4SB>sjJIZ;oUn|8L=_2IPK#d#|OgJ>Ikpk7UfukBI&H-Tz=RWkhpaRz}A++YvP_<7<^t~d~ zd5kje8D=xzWjo|Ii1T?Z%^>d+G)3Y)VCX#Q{!U%a`+KbVOo z6|>w}mrC|Vq_R=EZid?8TZX=Ku2l23nm!$RZ_XN79D0`AeIyQNx=c*h2TN3kIClY& zDPsX?17~-skZVwn=x0_^bQ9Y4mc~t&+dl6eJ>XpS>ltq+#GHKYE z58~DsZRRzMhPaj%r`BG<_dyz)7Y#n0ZP!NUX*q% zv^wsjg_cY^TYi6eJ6CT>MObmaIG(lGDe81NqmvM;-XXhYdY93^I8TY}{@u^jPvAhxg`W)EQ_QV2;jP9_29^Z7HXjw{b+ zm_X&D^2Zc?Rt72C`vePe7>^y2-l9!1*;~$f(tMoUuJ$(KDarfpyO=a!AFt!8I zh!Gr6rYM78Gc^LD5E2y;5D{l&Oe-jp7!i>mAyJW8h=77XOB_&CgvcZcfiOn|jLb5I zB+O$%AZ$po`&-^qx9Z;W_Nnup_k4BhyWby{WvY;!z1Lprd4A7tsI(6&Pv>U!m|FCx zCtAb?%#c$=pwPHY3K{8M3{aew7459%Qlm%;3)Ho)7yL2OSMzVqt+VqEw0y60u7VSK zI{OyiR-e^;0u#Eq8<`7e3G|Bz*O;8t%ser=q(dLxhjsNs8^_H~PU06WnhvO4xYDE5 zuoFMf!{`xLhVu_1n<&#VqC;YT$cC@WAypwB4C+JlA&R0SkK)?-o`B>|0dm8XeP)xZ zH)+N}`~2=5J4Iy8Q;dKSfH;8j@ZoEX`KL}?#7ql68kR{AsazmfKzBLFZG-+ZoG|J( zytges*=Nv91M1z(*PwA%NM~i10o%FJozNZ z^ilj+!AFw=*;7rqGsjj|NYlCW#ncZKEp=H(yy5gv+?)e{Oe~)X%h378Ly8gfEA-7` zvv^pZ6ix9_Q@&t0m%QX4a%1^Yn#x6oKBK*&L!C8mOTnO>_G2m!z+f(W>}X~^Qjw@L zrLF2+z3iDvUgkvr;Cq5)Sf7GZZch z2(M$o?nNPOpk3tSoOtwVN2v*c518dWz~^_{bWvx~P5u^>D|rLc4<+SalgFCUkhEn? z#8Q^`LKA?Gt9N3Co~~f0bKk%X+rY4Ah$JT`|%=CYCBVf;|jL?skce+ zm0_>%(t@NsF?dbx#fWe4mZs%+PMoy*7E%?g!JjSXI?6$5ZoH6~oli?#W$jEB?uAes zl3n-AdX|PH?$H#WK8M)BA8D?_h*skM3&d}f((Y*|z6KYONV~`;-8HLJ>=a{yawq33 z2flisS{waI+G3iE{g_4*PV`Cq<+S5KxA1^3c>6{q53U-*3U0oYYd;p??mC8Q-&^~% zr9*z=w4Vh^IREmYjm6hf9!EbZj8qfzhv`n>dU3=CwOyUCo_`tR9`|z@#FZ;4P4MvV z>vlMAVNxgc{L}oU&>+o1()(Meig49`bR;BRAa+salj%LWa5)4Z&f|+K6l^N8BuAW06#}|l z{=eDWg0#B-#fNj%U;p3rd_P9>T4u;-X zcDlfwhP@lH7*h3xV)rw3SSgy;tI3PecP~K^Y+b6VYR*?R<>*s(21>;AQUy(n-?&D6 zSfl8Je;bgzfqEW!j%V2ocJe6FMm-a(B9m|LR?1t*26aPD-F_mHlV@d{>DGQENIBQ?*ta%Y?&ta4^PH6Cl2Eq5 zGgSvl-$49>H6k_}lDpAY1>Cz42_8mJ1Gr@0NwhLApEC4m&55?A7gnkR^?;AM8LFxf zc+4RuKOXkNphEk3cgVt*5?V2}ck0k5D_%L<=6;E#qE%<@B{@$g{)Uf*EXOrZBqLAr zD*iND2JPqY(W1j(?gKGXz!#VxJPhMHIFdH!S-6Pm!f`_%|mO&x8tCQ`b!Hx4iu#8Z=d)sdEvP5 zcGD4%Kp_?w1a)tjGKBns!f}%P%B>=UVSzY`Cb&gHrezsVP#P*RlDFucc;sQQ(4yd$ zvZDog6T&njaFN)`9r>pZIJLC5dw+4fEww@hr9%m}W^R=`RI+%MmgxY6sM6p)9RZzc z?KaNOMK&uob8B+GmU?}9WTTShb|T+@QfI_@lP%>IeT|sp89ao&OX8h0l!40jnK#f$ z?nl?2T(*m#vI`(Y%@nFlUnJm4CYBQ$}us>?cyNbMHAPVeWEH> z57V^1>F~w!_|u7Y>d8n0yY|XdWnb(D;&-ef>eSF&0;afRt~%Tq^HHyx{ijR$k7Lx39G?`A zMqKWIcADtNV7FtkuNhFn8ZH74YnC-}7qNqghKkt0{O>4_G+n^C@`1NVuTgb!?V|JGELDSg4qofQ&tx5v=l3_l|8H8dVh0=CO}tym>|nD8U7JBFy{t7Z{z zTV7bfN5)absyV(PI3pEBx1V`b`kyJJ$zo2!>1IArlw?FOg$()7zb za+S-`q$}IKuRZ59y`7x{ZTPAM5mGcsx62h63mpX*_7J87*K1TRa;;IuOhpSfYzH&0 z%qdU!S4-ehbpsRWVkovaibOPV=4LKRKtU=ab4XeklA_%&*e^gaf4hS@I!+zIiEQAF zKu7Y7RErQzBH;rzLb6!(F^EP5n;CMc10%k12lMWjE|{nS$S$IgK91zo!arjb6HiHA z0@mDR(sv9yTC#}vOG@P#Vlp`nJ`Y+t($F+@MOyqju=N8S828anWlnVub^!rh{7Wj_ z3e@>Jt5>pL&>z!hkdTEgd>5don7KD3Xaw1d;oWkQtcJIfSSJBD@T-*Mq2zt#I`}(Q z8Eq`y*^N@Z$QJ!%z9X#ip`np5_8l3zjP)7N<1u{Oi}5_^05&@o%!uey{xSVez4wqqo5Kkyg|z}0;Y zq1IFX{gvH78}P=&st(+|z53d9N+Gp&yQ1*3DPPJ&y4fGl5UV-SHd_^Zt&Nh$m3#11 zPG?TyqD6(H$h&sMJ9c&fiva!#vhkVW=IhnVLpKoJPLt}Y+!@LYmC#s4DhqSTY5vp@ zOO90C4)~1+6z_|-z98rqeE68`WP9pGQ=={|*>(TI+YMX*C^S^Op z;kP>frxw6t(XvR%PISs%v=8#b^;w&Ig0;7NhWi|pkrxH1Wfa*E{t=2z^jSRy4x+>> zJj0oCAn{)tA@AFL1|o6RKEm{aoj$JD-=Y9nP~PSd1f+1gZ%cHjV7Myl39F58NxE>X zVx*WQR`n-hVJ0>kFrke>#YF{!>Hh7lQDzs#R_XnPICEMB#Nu9;+mob6kRqC5C6lfl^mgLed6vLCBYw*e`O z)+g5A_8Y*bHuO33$gy4`hmzMU#MHy(6Z7G(ZE1Be0H7=mEF`E`Tbs#lAXCR#h~j{C zvI)2o9oN_;<)4ygG}OG1S7JvLuh^%n$DR1OAU6|xk${JcqxZC1OI}y53op1ShhsWw zoQydXf}w`QD5BTdpU+@E+g{{VF`hHL0XRZ1?a3QwIF)U(x5DKHxF;c zhC!9HzB`5%_{yg-kliPDhLn0Sj9eT_nc7R4Jc^%RnmY~(q~bKOqJ}U?@+SZ@HW8cm zWv%8fk;U#W#=Ek1%@ee;8E-sGl|53Sjs<8;R6!S7=*)3yZS$dW5S zC>AC>EO`JbO~=(h){4T4T*QZX@e^trx?qLzETxb1)Y-4Tm}0g&hFLN{^eGiPu)Gn) zT=d2%V79E9GB*<|8VfD?Ara_xV(afW=M)^+bh6qmO3jK#w(vS*yIeP z>3;d;i>AU6%H*Fx*d{O(8_L3LBYA^tGiDt|mgK)(AFU!j3WajQz)%|RHo5PFXGIZd zpUJ(juvpKq*nrAbl~WAE^wCRnU-}S>a*y~suXNhdaOMC%(h3rA;R+I8)|qmpX5vj_ z=1I&%di)YU%;BI~w8)!O?G3Mkzp&IO!i%jac`i1t5>)_7@{fxN+SN+l!ap<4MI%Pt zi9#df?11Ln{NB(^v)81(q@lN1p4-z9XUUyPMe#MTTLkn&agDGpKG{+oyQ%i&q2S#Q zFKsk1nb7!@@|Aoh^+W6SKrvcarJp_FY? zWv}{c9~O!Ohd#gxW3zPHrWa*>^ow(i159Z#$#$AXb|Xh0E*JEXnrukAMCR{zhywUK zvIJSr>T!i-v_eFn`}D%6)vK9*M0Q+|HD<`|RM%cRy_QBo6GNEUi2UY}D@I zIvde16SqUaS4cKQc z?;W^|_A1=^z(zYw`^ls^VX=eQfaE#P^@xOx5Zha1F@QI0U~NFT=lg17d6Kk*n5v9;?Z$6mQs)Zz%NS80salnE713KO%#su>(h(EaeO8e5mWb+kJm%bI z+Q)4xsn4Hl#rGfPGj@HB*uBFOp%=&)y_%Bo8Ej0YU^U$$gtyVJVnJP}QfW&3_LA*| zl`FOj80{{hs(L_Ku;6TR&&(^hr8H6K8Wt8RJ7?6Sk`x0a+96gxAXsy~6yXBoB+?LH zfUJ3*oPFuJgMRcKK;3C`)4BM^v*f|SF@j9xcq8hxX6Vxc4{XD8>j_{_Tzg%T1*;N{ zgNMs2b@@&>(#pnsMe+ zT%olhJNOH6TQtK%2h!%Aw0qkb}n;e@6Is{X4RA+#YPfA8p^@! z5Ic*mi~XQJ-fLD(8H+*xrDq~bsqOt@pX@@|mw?kcGY*V�o^g#(vUbvS$H=IJ2^ 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 Z`21U&kAFGt^FNuP>@Vm2SJ-|Q{wIW?F_QoQ diff --git a/docs/source/docs/callvar_algorithm.jpeg b/docs/source/docs/callvar_algorithm.jpeg new file mode 120000 index 00000000..4c88b318 --- /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 fa5334eb..00000000 --- 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 00000000..efafc47c --- /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 a3a5385c..00000000 --- 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 d42cfb47..00000000 --- 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 4d28db6e..00000000 --- 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 00000000..032b72a3 --- /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 84cedc2f..00000000 --- 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 e6bc4d88..00000000 --- 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 00000000..21189edb --- /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 25a5f651..00000000 --- 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 aec8e107..00000000 --- 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 65634390..00000000 --- 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 00000000..af4bcf33 --- /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 HcmV?d00001 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 00000000..496476eb --- /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 fc327c5f..00000000 --- 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 00000000..287ad163 --- /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 b69f8568..00000000 --- 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 00000000..87dcbab3 --- /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 8344e221..00000000 --- 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 00000000..52a49313 --- /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 fe0dc67c..00000000 --- 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 00000000..a8fb6302 --- /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 4f50eccc..00000000 --- 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 00000000..4b6ed794 --- /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 947df29f..00000000 --- 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 94398a0f..ba39bcdf 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/tutorial.md b/docs/tutorial.md new file mode 100644 index 00000000..4f50eccc --- /dev/null +++ b/docs/tutorial.md @@ -0,0 +1 @@ +# Tutorial From 96ba7e1f687c4ce3ab49d00b50f0f77553275e33 Mon Sep 17 00:00:00 2001 From: Tao Liu Date: Fri, 26 Apr 2024 15:45:10 -0400 Subject: [PATCH 13/18] reorg docs --- .../workflows/build-and-test-MACS3-macos.yml | 2 + .../build-and-test-MACS3-non-x64.yml | 2 + .../workflows/build-and-test-MACS3-x64.yml | 2 + MACS3/Utilities/OptValidator.py | 4 +- docs/Advanced_Step-by-step_Peak_Calling.md | 291 ----------- docs/INSTALL.md | 153 ------ docs/bdgbroadcall.md | 79 --- docs/bdgcmp.md | 92 ---- docs/bdgdiff.md | 207 -------- docs/bdgopt.md | 80 --- docs/bdgpeakcall.md | 122 ----- docs/callpeak.md | 477 ----------------- docs/callvar.md | 224 -------- docs/callvar_algorithm.jpeg | Bin 163926 -> 0 bytes docs/cmbreps.md | 64 --- docs/filterdup.md | 97 ---- docs/hmmratac.md | 267 ---------- docs/pileup.md | 74 --- docs/pileup.png | Bin 34709 -> 0 bytes docs/predictd.md | 89 ---- docs/qa.md | 1 - docs/randsample.md | 84 --- docs/refinepeak.md | 66 --- docs/source/conf.py | 4 +- .../Advanced_Step-by-step_Peak_Calling.md | 292 ++++++++++- docs/source/docs/INSTALL.md | 154 +++++- 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/callpeak.md | 478 +++++++++++++++++- docs/source/docs/callvar.md | 225 ++++++++- docs/source/docs/callvar_algorithm.jpeg | Bin 36 -> 163926 bytes docs/source/docs/cmbreps.md | 65 ++- docs/source/docs/filterdup.md | 98 +++- docs/source/docs/hmmratac.md | 268 +++++++++- docs/source/docs/index.md | 22 - docs/source/docs/pileup.md | 75 ++- docs/source/docs/pileup.png | Bin 24 -> 34709 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/index.md | 3 +- docs/tutorial.md | 1 - 47 files changed, 2479 insertions(+), 2514 deletions(-) delete mode 100644 docs/Advanced_Step-by-step_Peak_Calling.md delete mode 100644 docs/INSTALL.md delete mode 100644 docs/bdgbroadcall.md delete mode 100644 docs/bdgcmp.md delete mode 100644 docs/bdgdiff.md delete mode 100644 docs/bdgopt.md delete mode 100644 docs/bdgpeakcall.md delete mode 100644 docs/callpeak.md delete mode 100644 docs/callvar.md delete mode 100644 docs/callvar_algorithm.jpeg delete mode 100644 docs/cmbreps.md delete mode 100644 docs/filterdup.md delete mode 100644 docs/hmmratac.md delete mode 100644 docs/pileup.md delete mode 100644 docs/pileup.png delete mode 100644 docs/predictd.md delete mode 100644 docs/qa.md delete mode 100644 docs/randsample.md delete mode 100644 docs/refinepeak.md mode change 120000 => 100644 docs/source/docs/Advanced_Step-by-step_Peak_Calling.md mode change 120000 => 100644 docs/source/docs/INSTALL.md mode change 120000 => 100644 docs/source/docs/bdgbroadcall.md mode change 120000 => 100644 docs/source/docs/bdgcmp.md mode change 120000 => 100644 docs/source/docs/bdgdiff.md mode change 120000 => 100644 docs/source/docs/bdgopt.md mode change 120000 => 100644 docs/source/docs/bdgpeakcall.md mode change 120000 => 100644 docs/source/docs/callpeak.md mode change 120000 => 100644 docs/source/docs/callvar.md mode change 120000 => 100644 docs/source/docs/callvar_algorithm.jpeg mode change 120000 => 100644 docs/source/docs/cmbreps.md mode change 120000 => 100644 docs/source/docs/filterdup.md mode change 120000 => 100644 docs/source/docs/hmmratac.md delete mode 100644 docs/source/docs/index.md mode change 120000 => 100644 docs/source/docs/pileup.md mode change 120000 => 100644 docs/source/docs/pileup.png mode change 120000 => 100644 docs/source/docs/predictd.md mode change 120000 => 100644 docs/source/docs/qa.md mode change 120000 => 100644 docs/source/docs/randsample.md mode change 120000 => 100644 docs/source/docs/refinepeak.md mode change 120000 => 100644 docs/source/docs/tutorial.md delete mode 100644 docs/tutorial.md diff --git a/.github/workflows/build-and-test-MACS3-macos.yml b/.github/workflows/build-and-test-MACS3-macos.yml index 2dc60dbd..2c45f9eb 100644 --- a/.github/workflows/build-and-test-MACS3-macos.yml +++ b/.github/workflows/build-and-test-MACS3-macos.yml @@ -8,12 +8,14 @@ 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 155ad180..83c55d65 100644 --- a/.github/workflows/build-and-test-MACS3-non-x64.yml +++ b/.github/workflows/build-and-test-MACS3-non-x64.yml @@ -8,12 +8,14 @@ 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 d9aa9ed5..2f7c7db5 100644 --- a/.github/workflows/build-and-test-MACS3-x64.yml +++ b/.github/workflows/build-and-test-MACS3-x64.yml @@ -8,12 +8,14 @@ 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 b317ce27..f1a1a8c2 100644 --- a/MACS3/Utilities/OptValidator.py +++ b/MACS3/Utilities/OptValidator.py @@ -1,4 +1,4 @@ -# Time-stamp: <2023-07-28 12:17:28 Tao Liu> +# Time-stamp: <2024-04-19 15:11:59 Tao Liu> """Module Description @@ -32,8 +32,6 @@ import logging import MACS3.Utilities.Logger -logger = logging.getLogger(__name__) - # ------------------------------------ # Misc functions # ------------------------------------ diff --git a/docs/Advanced_Step-by-step_Peak_Calling.md b/docs/Advanced_Step-by-step_Peak_Calling.md deleted file mode 100644 index 899f808e..00000000 --- a/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/INSTALL.md b/docs/INSTALL.md deleted file mode 100644 index 37407794..00000000 --- a/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/bdgbroadcall.md b/docs/bdgbroadcall.md deleted file mode 100644 index 805ba213..00000000 --- a/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/bdgcmp.md b/docs/bdgcmp.md deleted file mode 100644 index 099f9292..00000000 --- a/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/bdgdiff.md b/docs/bdgdiff.md deleted file mode 100644 index dd221077..00000000 --- a/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/bdgopt.md b/docs/bdgopt.md deleted file mode 100644 index 8bd7e0bf..00000000 --- a/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/bdgpeakcall.md b/docs/bdgpeakcall.md deleted file mode 100644 index 9ae78212..00000000 --- a/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/callpeak.md b/docs/callpeak.md deleted file mode 100644 index 5ff6fb6d..00000000 --- a/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/callvar.md b/docs/callvar.md deleted file mode 100644 index f27bc862..00000000 --- a/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/callvar_algorithm.jpeg b/docs/callvar_algorithm.jpeg deleted file mode 100644 index f44a57cd2ed88c91df44dc4159786507e607c3a5..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 163926 zcmeFYdpJ~I`#-)JXCa43WGcrJQ&J>MQVvN|sZ?U#LQXL`g&MPqPAH0^64Oa4)s$o9 zFgYic-+gU*YCQ1e|(=^d-lE8UZ?wB_qx~XzSkmX z6Ldohx7*m;Kte(gWC#91f*#0oTZHdX2y%3URzVOX0f`8SK{!AOLBili;SU-V5YqcQ z{emwf@+%JnS%N173EvU^GexB74(?AH=Q{sU&?C9rCp7f98G#TOV(9KkIpSsLK?xv4 zxF091HC#i0%!v`l-97xhLYE!!^7ak1STRw=T(Qj8(_)45ddD@6$F045eCQzsE+;6-3Kr<`HHQ0mlQpLfw}|1RM(tF^jNR@vCw(K+h)=RxJCKCDh+y#R11% z%d9EEUduKZt}$G*0+bH+JZiRQtIZ!}!JEa3KROv69&Q-E&X5x9O<22e<3_?7BZ85U z0mxwx5*Zlk9$^p|qWNbHTfIU&f_;yN`ceXy&DZFDgc25Nv0?=Qv_SZyiFxv`zFIE( z&-EV({6_-+k-&c>@E-~MM*{!vN#Jj^;}r-XPB_3akYEfl-Q`0GrG)rUjxSqhxCS!a zV(%z253<1Zi`M={E^JzQsXY?H9I_d+UDu z_%Y#y5EKv?8obAL%d!Ip4=ocPg2W+JXd$#7GIRF`Ic~LU*N*u*|9t+c|F0iz3xI&& zYBZRy>#yYh86ocpU=e_fyFm6Mo*^CqfX;&;k=q`}gF_)mY(8BxJoNZH4Q@y&7<3TO z7w2j3-|5@)^pW4`7r*lC-D3^%R05Q`z}-FA8-ip%gY;!5JiI|2vTQ)F3H0<0gdn+P zfVK<>pm+lMH$dxwJjVe&U%%;*f2ha%A82>?BY)ND?(Y2;{W~w9Bxrc6Z^-du?vcM< z{=fVQI2H!v_3P3BzYBbV?e>7D5|CS)KgD65UI6IPz#}_JfK~uB;tRO@ofekz3A5V= zXpmo6-6O;r$P!Wp^cqk1tqy=z2eeJ#v7PhdJ)eH$sIQGZpceuuG{`ma2}VSDELuLaWgcm>*S0W{zRcj9QU%{=e( z`QrjY0QHM^+#MfZ`}wj!4!E39pS{49nU@c)(!>2%{{b(!&t8F6f5-%P!Yky!eBVHR z;Q~*ut=j+%c*lMB3fwo(?|ePT@z5>vZGo~PQpb<|nj0WpWQEr;+xherfHn>};q*sY zk^P~;d*{tdq^cM%v-=pzIKFKwb!jdYInP@kbAE7je0`8eAE!7FUcbgqGo$xL3FjxRQDLkM?bT zjjs1!t?l{MAAc||zJKNUlixo_d|p37)?}|4UW5K#OQ=^wD9~rfnsPic*w@=9beR=c z5xkb!2YMK;US_n$XdML2uP^g?AZTj$uXRI6`NQ97F)RqOUNLDf(l^ciY~I)U~KKqC+v z;zB$jAt7-g86ia>RUy2PwvfJ%k&vm7rO-B^9YTAA4hsDy{4p!luGj!VbcFg^G?7apw?rO^6o^!cG>Y_yuthLY z8BujneNi(}d(i`;-lE~6=S5RQAByISR)M)RAj%aJ6H^w`6*B>I@t~NW*eS6~V(DTG zvA1FkVtr!M;^N|};`-ti;v{i*@lf&e;y1;giZjK(h!2P(64DZQ2_p#`i9-^B644SV z5>F&bCB8@uN$?~WN@`1*Ns=TzB_kyhB_Bw>k*t>-kmO0pOX*5kNbQyKlR6`HL+ZIy zmDE?MDQRix71A4}cT4+9pO(HM{X+VkbdU7x0)+*u7FaJhydZ2r!h);?Zx^&Ln39o^ z(UI9Kb4VssCPC)0OodFB3?i#2Yba|k>nRJ%rpXq_evuuQla$kzvyyX@J1LhUmn&B< zH@Z-Aq0U0m{a6Zu;C?+W4yIttqqJQdC=+*hbj z=u^ZgYARYQdML&yK2WSu98eNd(p9oo@>7aedZzSAiM>c+k@2Gaiy{`KEh<^mt&CIF zQMOk;rktppquioAr?OPVO2tbhR^_?M7nPaCYKu27_F5dbn6bEd@to>1)orT&s#jGD zRlh9}S+Z)$?j_+%GL}>=8C6qK+oa~97N?e@)}bz}zDj+M`YHAM>L1jnmuf7vU3z@! z&7~DfM>Ui+Hf#84T+=Ak7{)8&E%CniYj`I9$FfDstd<>Hc4JxPGWK%y<#x-%mfv0e zX*q9&?uvaYqE|3heAATDG}Sz+c}=rildXl_PA^~TkKtM9FDHCSL^WpKhE+n~o#*>Hzpv|*v)I6;eWh;WrqL%`OoUvq5D zgEgIN71nNF8@=|;+DW5TMjl3KMosHv*4eCs*S%WDG1fQsGR`n=Td%m@as7q$c)nrSM9btiliMb(rb?!}OfQ+f+bFtm%SL!(@y1!R4Q8QcIc5`^3^w_1da~)e zxvsgF`2+Jlixn2`7I!VWEtgsTW_ic5o4B0lPP|9#-K@FUbMwQ^Lsl!T{H&f@jc-}A zC3s8zmKkd^>nQ8DTX9=$x5jP#v`t~#zHPU*b=j=2@wUmfVcV{^J!SjWPSno9?y6m@ z{Ze}m`^Wa|?Izo!wpThVaByu^~e%-0PGjL}i2_o5(l1blo z>Fx^JRkT}d_paS(y9f8I-9z0|_hZP@fr2C_PyoH@w4-z`_1^1{ImQ8$DEHb0we-{3wRx<5a=IRNztH0P#TWw zA3uM*JIE~PdJsF5^Dt578XI?deBnq|W%C`53(>Iw|^R zjC0JJvrEsOKHGQB_FVRP+4I5YTQ6+7K))z*(f8t~*mbctW3f2TxcBjE;#1<$OCFcr zUtW9p#$`dm(S%Ql8xk|Fh+PT1(sGq}^-+?1(#fR0WXI%!Ys;?1UHf^Re7!csIE9`n zl^T}XePhRsS2wk8Ub%_h^10QVwk3^mTm5$I?U{7X^e-8kGoI6z(&OoKcYN=(-L<`2 za8Ku6%6+l>C+-hE*#Dp=(=_w(!zB;nAM&#Tv$`Mcc~tq>Q550g|ox5ho2sP z`uW+`XRn?cJip6OX2idMUWC2)@$$EqEjbQ3<+-N0&-1kNZs#lJ#}x<_L>90MeG0o@ z9emaBdi(40H=Ew%7a1016)!JND_K;MSSnR|wp748$((+B{OxF&cUfOKxxBODKt)sK z?#fS94pr}}ZK^A3tZJC=EZ!B@n$^C3Z~DHlZbMzchxH%wKd%3n|7pXgf_jtsSD!b2 ze$!yyQ2K@VrL1vlV|9~#Q(g1U=7yGiEp4rbTf5sl+rGCSYv**F=-_pp{wn%4?%Tp| zDP8Ja_gE`gjP4EHB|TevKJ+^EcJ_Jnjr51~qXTCLWd>7*@I#Nk8+|Vxwi*8X!{x`o z$ng>0==m}EvD@Q%<9QRCCqA$bum?E79KqzJDb=a0pTe2+{%d%N>TGT`~}~cOxXc zZrxw^uOh&w{^eKBzlZ@J;?7R~k$@wAeEKhs-+fMy^k={S`3bmLx6XLJ%zt?b-a_&c zI9HJ-oX`qLSY8MxFC?gh@PH3d08+s9XDdR&I1y1XaS2H&X^!wHMvL`CNV z2SQQcJ0v16s<3>mm6+mgckvZLN=9d{-j&eY^0I8vo(8tox+B5Sl2Xbli&d9s>*(sO zTxGm|gNf-zGwZF}Y;5i9w>$0Kx8E7SGY?O%quxHgej%Y@C&D8lPsW@*cmBe~*tn$R zYu8g!Z`{0f@BV|#hgpvvKgr3>%P%N=_4-YDMP*fW&AZz7UmBa5TUy)NJ9>Ki`UeJw zz7PN4Oiulr=FT9qbMt%&LAc-9`irxF;!7UzB`hL>6A_>1OGr2z+&Fm=(dBE!6s&fO zy9X(*FghclwB_pEmt~Tg>-Ml09SLrbQr0r=(dNvv_KUOs8Dr7^7H5Ak_BUUhz_s|D zD`6qfTVY`^R5)+}^frHqi30!zE&#NCT@t@8$@vT5qCYMHs6=SKBn~GE{!2@UN&NZg zfBqDF1AB2h1s%`=9N5v5$H_xP2*dR5#X!zW{g@)ON>&c@GSd&QF`86Ueke56o>IKLsEAlpSg@0Zwl27uIP(ZMvPysU1V2Fl zb)ObMIfXTh({s*a@&ZUyhy83KzSNj%dn!>WB4yCgW!FodMKxpjD~H{p`5$&?C9AFW z^xz+zo6E+QKM_FDrf`E{u>dNMKOlhm-$Q)XJ*EV)cL@X0yueo&sYmtl6R{ol|C9Is zA_q|hv%8atXxh;I4F&{Ig~N^C&X{Z}yf}S!tCawvT%WW>)#`YvRH+7(!b!!XaBM=w zvz`f&hzb{axd4(2c$jhOu~WsZtCT0fhfc}X>njQIckSM$1pR%(%UL-p zs6rNZDWA#oCv{Bq;>TQjR8jjU-(i(7N3-{y&6KAFF0(<7Wbn<1-nLbu(K`ym{scjv#} zm^ZKvPX$n}cp0Tr4U=l*X<_yBJey>l*F6Ry+c*_n?U_y7w60Gr(ia6#WPsKl_~};0 z9r&Lo{~ft+bNcL<|IP&bi=p^`H1Dh?cRN3pc$C?ug2_q~#RQPoGcmGk1nh)}S{7R5 z6&9LwdG){fd1BI%chf8RM$g4CObWs>AN{w$j)?;U$Dl7l!#S*~E-7H7x6(ePP92P3 z_Sw#nH zjtmi%&&Fb1>oKJzH3CRym-zVfB4nEYTG%Ln%2Wl=_iH4OU2H!4HMr7P0I_Z0Ic-G& z)MND&p7erf;|=7qc#aGKl~2WDjakSpKLLcM*`n6YpgmxI?%5MDC9_sg_h<2O{vrgJ z%7x9K?!}<)r1`pK^Z)1y8I@1OV%3?*t`YLDemB*xh3f^-6Q<o|M#{uj*(e-x&U&!$J;?>9YR+Fqv;QKUxI(yWrC$M<`7sqJHk|zM0tC>|Jpshp8}*Qdoh0z5$>#(RM+Qdald+3G>3|~`eF0WjFjb@1zzrJ7 z^R}5HfKrr%cyw+WY4!(m28hV*nKMTKffhzVK7Xug2_02-2E(E(fIKHebuVB`XrI<( zoqsl9Qg|}X&u!gx{8(^gYO10-^KZgtjUDTerBN@qZ6#^k;wYb3mU( z7l9r>KrO*`Mm3Pk@gy z7h{cd1rlnH;vd#UaP&ozdP%QEwtdTTu$leW$!P8h6ydFjE4mhn5b0%&!A_;zTB2*w#P$aI;-{J`cEd}k zWDYmkmw*46ucde+oR_w}pe>2=s_qhPd@I%V3XaCk^f(L@Gm?2EKC$gNzB9Q(*=<>~ zu_@Jo(&I3u8sHv(urX{?X>5>4>Wa0KzfB|@w4C7~=x6?Eq7Umd`GqsOh{Fz*!N}3xS=;{vl?UFZc;9d+l^x0H-mWfbp9NKeZjO* zCpN2m;=JWbg#IX{IFFr>9{ISd%J2P@Qtr8-&}tf1*&W8H5`V5G{c6 zWmDNR)pLA$&8BZ2B=&fG=AlkfHvhien++7TPW}T*(m`Ugt;!8Yngw+m|GFg@-7<4x zcXp{6BE(xG<7CHXT!y{z^8QPj(?3pEahOdTx@v~(W)!x&k$&z?&Pduc%IkN2+Yxr5 z@|zPTISfXT*=Q-n>hN_Vyhbkco^3Fk=;dw81XCZ?qQ8pl!%TaV10a};f2o2h>vCa! zK4$U*tZT*^3puG3@WnUVQn|M?G&lvR{IqZbdTps)%}oOC!{G-R2N^Uz6Yjpl5@&X& zlciQ$>QY^Eo2Ijw3;nM8ypcV3w~Slju(t`Qjq?I|@5eRdw?}Qa60Zv&Nnn9*lG(fK zFR=3Hm%vLVtVUZA;nGX4aUe;2jW|{I#(clr!|!YDY&>{QH3JU06P(r|0d$bO5-zh_ zPmaql=if44O`BSu{V43Gb)>e74=8vwp26eiJq_!+brZ zIiQD|&gQNIv!o0q@}F1|ztL*(@}=rXO*gAbZgi&QSSV4oE$ZsTQ*ku!3{L>5h^?K$ zi*hY!%x&4eh0e*oFTUDpSK?_}l=P6fR(5?4sZ*c(8Ij?UKl02_Bc!v3*eNx%4+-fl znvjdgwrvau%pVh*a{Mw82rSx{u}jR6KzYr{{x`3usH|CUO>AmPg)7Q_{-8^fpU(6V zKxey%Z2Wmk1AmS60x0$}+O?{AqS&QZRi|Wfe09Eoj((&^VFK_Y!Ut*N8#UoBd!0F8 zupEyv^Bm|ejOzwRS-IgKb07Zr!kF?vG9Li;7MChu9dI6LjMW$Uli5Mp%Aq~ZL_8c` zH+Ox(HkrC=7Ut*WO%cBs46qD}8)o;+?ym*Yc!UQmZL}|vfES0$G-=WiIm3op7aS4q z`>tk(bZ-U?RAp5QpdwOV@=^;&h<05k%YA*H@5_&Bhi!_w4BEp!+8az~KH6>kq|{^7 z^<#@Qx*l_N6Kh2k@1tAzz|Q;CpJBSQ#|wMw;~MP3^aar3`sdUw%tDh=*NPvXU2J{5 zM6>uswyV<``JSix8O75As4cPEyJq47%-%!kaPHl^$>PBXbKQoHTy$H6My@y3}@A?$2wD)+?h$ks1UR~7{h1;k7-&I5x^>FnzXAB*p+ zkB4PTHGB^}q@QAkSA|>3x8Qdl*uN>Q&Nj*9RESbivWB}muS}Ku6SJggkFcbOe)tYu z?n>k!P&`{s*vHf|m-;ie_7@y&&R=QVDPvu!v7@0*``ge><=Qn@BXc54y}znQPS1G@ zAhFUz)QyED{3pjs7y1=089M8MB(CszbNy>+RMo(R39Q~c39hqEv0yMuAoxJj?rjha zs5-^c6zQuV<{Dn-tw5z-O_u7=8qA8_aGz6%(^op(ym{M4#IGvt2ZND9n)Mo5ou2)3 zh#P|7yP56uZpvAr_r!&@i;aom!zbok@6>dvfFD^A%J{zJw3Obx-*5el)-b+w zd57nlp^KC|jZg2WCJhd5JFkTwE50E7W(lOvPR1m_jMbIo`3j(Rzh>gk9bvpe@>x3D zmN;ul>Lg)x`yYeF+yj7zH-FYT%i!ko@1gntN`G`SkbKPJTlVmF%!S!Kz|f%DB4yq1Sr*%&zI|>{6V;c)th6_7aigSM&ho_<^HKWb zr*%O&K&5|ZV-QA*rcYJdttXe&ffZ8z1_f1c(YVL^f16 zx-Gmr9bmdYXmh&zS&@}j6FP5G?L z8S9&;)5$&DXB%$J?18;8%wbc}regSBXGcwc?dqHOHzWdL{$?hz-K0CKyuL%6n+xnm z7}XSM=;7g&5E|+1p{frZZkZzC`%@JT!9KMbNWa)hVnnPisr!!HxMmNjnspYhVZKzQ zQZ70}?@O`s-JJs-%r69wl0qZ7ZkFN|wPv$8WPcqd^_aK84KA~pAatkK$@{L6KhnH2Mhl@LrrAj-AE@Q0m$+ zR!!#$Au$5z;ZMf5Tc{2nxGV!^@XIXzY1%RYG+d%TbM&;7eoZL>r65*p>9>>UcH~>H zE1?X-7e@3Y?`|^DF$jX;J7t~8`Z>%|qPcT@Wt}yV^ z0SWw=``&Wv%@x7Bu70+U_Q8FBug6FZBX)*!Exw>jv#Fb#Fg@gmjI>pY+=Vc;nP!78 z(iVr|x@%ulD#P(V-}RFGpt<*ddGj2;Q=e_Qg>>)3>+E$0IU8>J_gMsYIE={1x;*-V z{pecSIhcTp)iA9LNX6l`Pl^7L(IUh)N&x8-+JXEE1kiY$Hf`LwXXy<3lnG4z(N18G zS6>t2z5a6)em$u$&z;u65@xy+&bQ!Ii9WoM%bMjgw@OMc>)e$o`lg*%c&fNC$#ja4 zI;no6?+P!R5rKGc9C~W1>9{u35wT|+K+-Da?nSoTN=Y+wb@`|YU~I6>aUa~5`A908 z+(GPXtw?MS>88gDARlskVRT(Z#=;k=yGznkVZ+runyRz?*SR$c;a9JPFPa75NhB1J z=4e(PBE>ViA2Rc%>FwA`+UJm($Il*=gc7C8iM`HQHpG}27tb{H+Q~?I@pcZgQ#KOr zehjdioE(@R8;dQgCwf%M9? z+~6a8a_Bj_t*1^BtBHaGM1~O0>+(RETdm1&$*7VWu}y3WlOE&5;Ss&WbL&})5fZkr zM3ZM(U*Q|3-QfoxZ7c?pZA;3^6B6iWD(jn9(rF@dX=kgR?=&h-dk3?3F*;l@Ne93h zyD4=C`{Q8pL+TEM9+Zh16d>28IxFsfKczV}{`@oE*rlqJFin0lMI9!NWDUckz%LXX zu2Vi1Q_Njdvwf!ngr`3&hFS=-sq8Q%I8fs-W5?A2s%-s=L})ejyxI)q5{!@SWN){g=GP{+gqk%&F!;><-DKTnqM(j@m=?BmrJcuhW9u! zf(_7i&{|mRgY}4B)@XJw4AJWFYR4>9s2h>ozDERehsS;$V^t%F|CZ0p$fdUx)O@wC zkN2l^c_wZ4yhOc`I5Z0ppLb*j87ns!&&WQyihlUmunk`32BHr!muaR{TYlWnXQZCi z81qfpRBEf`icWNW<5=&lNb~h!Aty3C55>`@KJv`dTGryzfw8036Z#oP*oCMP36s)3 z#dAR2056ePm&QW25~U|G=GIJ{;dAPS^{NKb&JyN@m-}Cx-&>fnvG}!9T>^PMzV50h z1n)5m%*^uR`abf_wGE*VR%$txs7?0f>m!x?>&)&eJWNy|Fh1K(3aT*PgRkZX_-a z^C5cIBP(lArDQvP5hh9d#4KROpwd|pF5KwP&)1hok)&%+8DOdX?e>xVZuTL%sao_^ zTBUp4+{iP*OK&h@Ev134NiJxuVs%8KYX0u*`t7mQBh*bM70*umn6TySFr)4{wyx$; zm%VbDc8wf9br4`wwCJ-qH*DTWk#EE7z06KAN?QnbHHTD9lDkvHIoDx(H)3a*;)kTE z$|bRD+aCnop3QJc-nf&qb$V_ix!yK@H}K%@6WIsHOv;p5!(?gL)9!xrdJSU3ggNE0 zVSr}$<-uy>Dd2jo&a}0j`HuT(f=OQHsh9Dju_|mKB2OKhsEk%=LP=CIHTBluovnpQ z#q`NW1-zjNFmZO*=NA2!2>m}s>;JE`kf7;*8(Jxi;%Cu_5z^d!2(Ay`VcmPSbpM5J zzEOZpzZ{d0j6GKZD_zpN{ie*}`*9E&z%Qvs&DUX4o7nZ3WNPN%$Xi$jtLNzU(pb|W zk-AH4Zt619HD_~e1(12V7AA$A)8}|#64^Xr1h0&q`ze>_hJD^eM-DObECD2zWLz|1 zOaweLWcI6iV3j8d>MJAo4cGfHDSp-+xf?W7S`9geKDOnUH~$`{hJ;j44xfH@?M+LX z=xEBj$ab|_)zB^W?{Sw}N(*^wXdm5l5!Wp0!q!rah`^b$TMjndC5x(){Wqi^V+){c zpD{P$$_0^q5^HZwlb1x~Zbl+|mb%n*>A!Mu)VI!k)kN?Pq-LMmYh*X{JT22FvF-|8RG{9F)9jH{#wEBhgIf2 zToyoY`288KCuge3h@l%Ji@FP0$*$vCBg9i2+EgFotV<=PaV{(^YDwr7$*F)K?!|#v zbEY=1v0t~ne037S&Srlq)kKYv5Dr{c$dse$`JsUE?%@)T?D)QiMoj1TkJlD8vm z3}x!ic)Gt`w(xr@X-^*ZqRy$G#z zgAZiyIQ{*%zee7lh@_D@pT$9R^X)_%i|fe0p~#vg?{{>vZtB$Ez^Fm9(f05_ z_K;EdN17)38{lmWrM*OAInF!zU`h3MsE^H1M5Hp!VTNU)*say$0sE~ZMdWMMb4Xkd zrPoQsb(_>?P7xyyXH^nAt0^5ZnACb6j(P}@>~;0t!4|JtN~khv?J()ckkCm|b0)2r zl<1eY*M3%RPMxKfkiP-6`-3@F2Uh$~{B+o#c^gMLr}6UmEIcu_W+!t8t(q@NB}$4IHjppV+u zR%%R>5b;Hm-l!4}liCIrPZ16qjuAg!tagf{)+=7=8c38yoGMO)?_UZStDxImP%=5LdG)rGqQ z4#ILQCSsZ>@Wk!8CVZ~<=$L4Vu|TjmYSmT`;Noes12lR9U%^8qIDVP2-Il`0{Ly?I>=IG^rj4R1KP zZ<6fl(j{J);Hcu2pO;hP>#jCC`9tIIRrl|>xxJj3QGcE`x}Uw_9J{EOT!EMN$5h#G z?)kjg$Gz$wzUOF3&t@HWBOWZ|%Q;DrRF~cc+)!smXoBA&+`+vU>6hD<(7$(iY&gpSQ}4 zNNB9=pmLAeX(p`;^5VT3UtzKan=n$G;(xl%%i1hT18BYs1l;`7N!)e(i^WbH-7>X7 zPC?!g_Rv`aceQats#Uh4=$$y?tPh9UI6A&!{hT|wo^rXF*?k9QA9|+J^N#3`gz+>F z);#}_g&jB?(RhITQ;#{E)o##OUytTqU#f>2A-7pq;B!DYR?&s)#10=l*N4C8w)jgi zsi#galcPZPIENRtb6IpqD(8W4FW2+tTelPYqKeaIHZQh0#5MYP5lEj}Fv` zUkZ13Ohn@g>&F6mSsnG&EQS0roD;{pjXEN&@1qqh@9iaeqiu5Pi@a`2DUifP;Kd$= z=T_5nfo)Jb1Y!4>J)k$9#JN?NED*pLh)P0aPP}|jFUPjy^fD8P=U9@M4mF6=oLE7M>B2XeJM_vpa$S5oLgm8D znQV#g#>AHUnB@GXlBgd)4(`5Rx;TMyx>U=q*j7n&g1Yv}xq{}g7e+(xbZ2U7<~l>P zXwy?FsC+%PQ<2*UFn;qB`1_3!4hZ5O1Odd{h`KU2tEPF0 zo>l?6*!`W=Av!%q>6?jpW~ojr=i@8s?F%DTjrVeiOIX7ou51Q?Wg?i_TzWn4^#%$E zLeb(dk6$65eMB&K^PEv7a<9rLhb>)>ElBM#sfco_m`lm+wXkz_VYx&c;V7J9eBQZ+7 zTjseFAH92+62mQXN7JQWCT%Uuvs&CGfT|I7UhC9N9tkcx3Y3%4R>8Gz7-#yC&(W5$ zN!5u85gjBc-*A<}otSbe>73@(Y53b=hY)TMvu+aoAb{$2fZJ?_fN0XuMV-ASV?~_0 zUi|1?P76tVq)U(Om|pPGy_X_v(fIw%b2=eaJ#EjF(Sxh@Aa?j^P~-3^%j0t2Gal9Y z`mc^PfA^HbulC~QqqDRoI*1n_dc-(l_x(2vRIwG4Ea`#8{SMJjQ%%HUQKzWBje&bs zQU#Eq-I&40+(d)^1fSDMjsmEdntt(S^3?lAOm-vxemBt6h&I}14Fa2S&X^JFMnF>G z?tm3)^?7CYd{3kt@2JxT8a=l)r?#J;RhL?qvb_E#s&V)oid(njoW{1Cn$s1L6 ze_@tWrM4L{vn^Z8{Hp2{A776?kM7Gb}gIn|q7duhn~tI2+yjS8k7lYRWYi6oMN>}KMl zIN+2cU~^w|5R^?BAucGD!rI}5w55n_UH4EWLG@sS-0tX4{;e&~34`H^-&|&sB*wb= zowF+mw`jIgmMG-_JzpGEzsa+W*wj~8Wls|)RJagCP`%a%4Neu9?yC|FZ4R+rcf*Y0 z0gJ*p;~?~*U2#1cJEMo=?Prvef!yEMxNQQ4SS1S{?qwc?y@{7KH24o_LWn;14Evgq z)kB1}wQ;)cfHtu>&cbH#xUfC;)twD*M{lw5=+m%1CU5!4a4ZAtJSq=y%lTJFvrcWA zh_jTB_6$f!@;_ns13RmFvJw7omc&8lYBJl0JUY-vRQb`hrWj%Nx9b=-7D+-k539TAt?`BC0AYWR&rJhae zvcwOi?5@m$R_7dX9=9JI2H~V5M%%D&a8hD9J_fH0mYlhop71h~te?h8j>bct!PC(1 z8oq6Eb3-6#0V3F0Xbxkn@mFL~>@`B~@s10{cWmMgan^TTXZSj4bJKh1(&SoSi@X?& zHm&b#{+3U3*a-Nb$5`Fvsquj4@IF)kd60Nu&_ERar1SVknmn!TtSwORM*d|mWRK)3 z<@hF$}O^TV9~%b>cu4 z8rg}aYt^TsVbkYd^Yq{{6Zkhqr%Dw)&t$Z<_nS%&smcz+`=uI1EDw_~X32bQD^qX9 z2bR8w>u|Z)onW_bAgS$=M6f2Wmjt{`3Iow0jRKf2s?2V^01h2pGV<#%xoEB$OerSz zlH?A@FLfbZkE2ZXudUN)H_!XzQC~NyWZqhj&&@&?4sl6{ZWe0YL|g9friWyMEnc%l zHRtnL@<{z|9_>MBQQl;Kw50jV0Z!q}g%7Fyq^_XN_%mRR;n775OiD&&ESX3APBTGX zM{%6Wz}E2eNV={w&o-L)!rb`6$!&P9VWxJ;vyVg9nIBSTcF&S^Zw^uzv8BfFdoWJE z^*poAI4lEGhRaG>xugn$I+cK22;pq%rCcOnGC!`6BlawH+Ml2CrMgQM$B#3$tQx4H z7*MS6qn^l3o;g6wmY4w=h-`ZVdqmJHG?o^ZG!o1oyqXMLf!CZ3 zu31f~_r4T|1);jUV365`d9<#+U6Gr~zi+wvJD8fNG;f=$&mo)pJ^E3yE!7UD)1fi% zGd7O(O?keW9OP{+C8w&S@tB0Vc5(w5UF6hrp%Qi;l5dI zo%pW9B*IqGNff}6XewMLhRH-IRtO+rq7S75=fY{p?xhR+m|5QU?*?Z!fTQy{bSeDK zKG6K4`Ae;%`pmA#BTo2RuV=sGI3}PN`w$+{C)HRpXsxi&dXoH)mI95{N%cDrk4!{# z+Epq*LE(buT+{B^mtT)j>+o}|IbRK=kMSIc^dXVGm(m$uLC+&pMlt~kxa6#%4q*BD zJiZ^mwTsxH8Jb0TN&a@@hQuDNqLSRWu8Ilf+~Yv=M*^tDR{b&g@tamut%9fNM^p%l z@~*&)ku!G?oLej0qt$GwF?@2UooW*DC}@hGVS4tAtSo$LP}aQAF*c#TuN7Sw&UHhk zI5E8@l`LcjHLRPzuD2?0A;PFARc&7W;>-G#tNSL$29pT6c84oTH#C#1<%2Lr9YOsx z{!{o^CYTJi$Yu6@ZZiKGv-`mk=7mN#&hy7?qsi}WhwjET@|<=jaETim`IPqF{q&+qls#=!vxS7;}MG^ z{wv1_Kcnn*6SguFHt7|S*-RDd6f5nR$q$e&=Y^w!Qx2L zP?d&E%Zlcn#J%k1ftGrsO_KKtE~vk?*gi7*qqf+mk;#(tN?6GqN4= z=kPC5iuz!@kDE3JpGc)}l>H-%t$Gs|xz>a~c8yAfQ_}k446a_Dc&l+6jU{L1LI1pw zcAfW{d^VglnZu{^(}8J|MrD7T^t zGuRmo3owx#8Q`EL@T%kk;4%XIUA~WnDuK=CNiSL!TyYcbzE1vWWxf){ z+1nX&%Q9p^(O~!-L<86x z3m{o9P|-fPK?JPx(#fcv0J>lVDq6+-9vuN7i)byTB!pgt%Ywk%E2h6Bp-Rr&75Lnm zx0~>a9V0CEl>>fh`SB9J6)rra)pb-WVUSE8WDGfQ!FFx*6|9xTCK1))a(CXkh@7ZZ z9X)8>H;tj0IUsg^cpf;;1-welNw7#{1Uqv9=n&TgZJWdH6YcSsLGNr)l@ANgez7V;52J^#>JNI%?aq zzJxi%ymN3!ob}ea(W`$64&JC`-ueUZ4$cOCfkAAtebZs2mJ-0v?tNy}*I=%Bzq)9k zIgD?+w*75vGaHW7F|$cLOhy3;!X)*1N`NWT;lS^?H7bo6P0j^JKrR%^0;kTl89i9TJ^#>bBB8ZE zL1j2S$+l(tg8EWocMAFChAf^U_TdDkid+uozvSpvJLe)lQhQ1XyxpAEvt#Hw0VL7$VkOr@t}U0? zfqkadBU8P^TwN9qbsnCk{f6+kbGJG%DP1sk+i*R!GqSH?@$(eaz0Y9#!3^UDvK+~U={Gfg8*px<$4=9c70hbVWpXaDiXMY6P#MEzBYl-bCCwLhVbT_c zOZDv=h`C1-KnI66OiGYHCM{YQg1;rMruE_SqzUkxO-;B6SW%70SO>P4528@{mP$T! zpD61?1)TI35guSsOT54{Pl0{-t^8odGotVO$%zW2x`@r%3ps?yPO>5KIO@IvD&7IX4nX zV~h75b5rF2h0rR>X<7e>O5`Of`_812jOHSX zXl~xNSc7Q}Gf|~PZqQ3a93L+i1LvaFStI30+fv)e#u;p=j<@ZxFqrS~hrTbx`j`|j zTp|S=(wH~k>@B?jKRU!wEmfu-V2fU^z8UbuF|+L1fp5c8v-H;)U;1ag-ESSXpW;tl zt4|r8+xHBG5v#kXG%+usuvc1|ERwEc;Jf}*>=!kgoLj^V8_jFiE>_SqBz7_C$cPRF zRaU8>7bd=?EX5jG%6av2s2ta!DYD6nnA#}6Lv>PkOZH_B!E zkvZQd?FVOl4B>$UxaGu0h-T@>VsHLvTLI?`y`@9w5~M7=hZ0ZDZR&Um&gfP>zmkw# zlkHj?uBF&k7o<0d!GxO+7I*Ck#Cv(dmBfzv1maOfLg_+eh?6o>$x>$e*yn|}qCr9T zwT^d`Js?|!t1Hh@o!2g~@1OOI^;q0~@v}}1|MDv!lC!k(6D^j@nzfMH?(6yN+p)4> zCFtb3xyHQ1_Gp()NnE-qmm)+QvD{hg9MwzdsOKJHlgb_B5-|fLv8ROi_T;_lV^pi4 zCoVcS!v>@3SM=8o*zIh2y9EY+TA@S*k?80n4tl((lXFnX` zk;hW#o>S&M$1Up;nP=2XZ%&YJ;^mp$-{_a{ONtMI9r8YSO#W0KeBmUmL?iDqy^vvo98ZUL{tj4r$aBfw>DY-$r?-|oo!v?z@}8P3h84)V)e1iyz`IDT_05o zAX>su?uC%}sIxZ!`pWZp0&WM3;;zhj1x5;FP4cAH2vMe~&7Mcs#FvRGQg? zJWsqB_RYxUu^};cT%nh!W1Ref+Q$dybf=S!E#h16-i)uc1!~fLh0fkfj^Q$w5|6@d z^lCR8UX@kc82tA4tMC>t;n=SjI@GGQ-tfH7`@Eza&U#8BJn>84yYV##S?gQdfS(61 zXA+j6C*TxO2O?L7w)gZ;(koVT0zl2HBIru7*TZHSdxNlOp65!Np2)fwyVzB#F0(ag z-;Yy2>;b`H8vPJ>9LpFV$tsXLtG$npTj`_KWlzOT!f@Pxp>ff&sa!d|!&USKA$!O_ zCp!ZS7Ru%HI(#N8AwP3F)W8D_jmKwT`Y_^yMlvasqKq3_DYu^8q7~Wto-IjyO0U~e zSU~P4j`wd~|7icHypu85u!HnRFBJ(t9BS<2J-z zJoj-)E7P)6F8@*#J!+Dw!ddT1ZFlz{>yCrIgQfSK$+AJg!P2zV#9t ziwZcS?S~}~u?T^(c{N#+vFv!j)^^GQ%R%e3GxO}It5oz0xNR22KC!@jrw0?m@@XRD z$pexIkpRdiRE=n-&IWh|tF2Y!A8`qkBSB4uC-HxP6ejIBLTip~~EhjRq*GHffPh=CMm3rpqFUfJH1xit^h zH!{W#G?x^XH6p`5}+`SsOqx_+3*Gxa)7&QJ|}fmqUs~JSd;ua;m>7 zEVr{4Zx+@M6BgooRU)u8%;Kk`)rlKr5*x7TJC`v}al10okB!!;z3M@jI z*L0b}@T$A6Zr+xb60f*T!N-4ZFw8*e>H7y7>+k8T^m>^S@xF^J&qCa}%K)qVJLFa4 z#OU&YmtOIvN6%aruI-ienD&^q#xtrx)WB;a6APyJC-}^^u!^|p%?GZ~e7D2!Q{J7g z3Xtgq#w17E`i?q0_I}F}=}+n)S2g&HdY$wf=$Ye3!(+d&@>%k@tizyDj7f>xIjNj{Ak)7ocRIjr(e$GB);bA#xFI!P^X?BW4ES^UK-v9m8{$w zA=d#(b`gGURK29v#uFiY&dITPRr{W1ld-or&Y5hT6jyBRkq2F zh%)%q8g+QB1Jb(C`M3wRM_5V|NQXORHr_f4n1PV2W-HuI-*_SgwB>m_*KXx*YHvL{ zZq=mjdfZzl_^QsS3#y|A6Rn_u;b)=_LJxS8+A<`C*rbeNCroP{E;F@FjeS(gydzK4 zxvx~6!!=c%B0L$e|5D4L@rwd7zL+BNcpc)yP{VcPX(sGNxFWM^leZXisWL!1iuawG8$(KbL~uq7}1CDgFeu`17lpPkPD zRJ*yk>Ne$s(YtI;kNlY@XH<8Yznu4Z?5jfB+qJW&S^=?R@fr9A{L=j%TFHU6EcRs5 zT^dSG5>O5n1}hYP@2%+ZCXTc&+8nw=9VR@c8+zev>UrWdl5IS)0OZ$+)hspmjPb2j z@IdJlA#3$~k-gOljlE4id`_LWn~&_FZXtE+etkbutX>!8qZ9bhdElGpV^+o>&OHQB z120&?o2tPec_*(#e{Ol;tv|ci=gj7^Cu2$sh!p z1Fi}+#H5m|;OD-8;Md^e(_08qfYc6)3w;HW(nGKa*(UmF%ue~C2*wwG4~hmaNEODPj^IbTkZ*}q)*{|W&cln0 zlQ9ECodnJ&M1&R668JKNJIT1OvmLCB7Vh0ZnBjZGv|(8G0}uZWwXUxB^d|HgRyC~r zNPAea$s#uI8vb&D(ZZMJaK_|vo@Su0T(@C|w&E2!*@I7>Ghn5dT~t&SX8W?>rS0hH z@h|$v7Vp(f_+inMZp|tBg#+H=*w^q_b}NV_hOZ6qrUTfW&v3mzt3652{E_Wmc3A!r zWEd1Bq7BJ0jYLiZ15EAo3ZmRHa?5#DoZZ%!dh*mA32m-vkNM5%mp2u#SjiS}BQT>D z+`PeM4hUe|f-C%{zuBKH&z}lsJ>eA+=8;dKKm&`ZKo#(0*Ec9Gk#vGkS716r8(9ZR z8_@7q>;&x4JZ6N>_OeL3hAoDMQPu~G z?}u8`e9m6C)rCD9HhIn-b0Cz|WE8qB>QG5lCIGRpyA7)sPmfWQ`&Vz(w>PKEKal=x zTg@SJ=MWxrvV-&4WLiz8%Xo(4M?)MD|crByGeP{=GRx+ZUp)F3>d}f+=-2!^%6>EzJom%>0w;%jMshZquIPJr} zio-G$j8x6bF9?NbE7X1}`#?V}u-6~2Y_0Rk8J>QBConv^rGHz`iFj$YdX4S_(s%$i zI};pO6JH9Z&%9xw2ns5ssz_>7>w;(SDa>Jaod1V&0J!U^3_;>0v<;4119_$6hLZrH zT5{g%3aUmd0IZ}3eMiu_N!MeA^XWejD+-AEkHcFqs(m!KHgwxph4benuwgy(t^8wR zhJ0cF1Cmfl;9tYT^v*q$=@8BELgWN;6H=l33w_)G@yGaFR*8?%M|780`VR4E*t>%8 zy4ZL3z580g8YIy*F)=W4&`i9RB5`Xp870%b#q%Q40?zq-SGk|{Cg=9?)EJA{H*?^@ zCc-gRDsup+2yj^;_*VIEV9Q^pqWght2%`>K3J4gJC{o#BqUERwP1}?X_%U^0X;9Q>PbqELxX!ke zPMuRwao0T}+E?qr9gBj|9pt`|tRZSnIEU7rBl-1r-}*T!m5^VLY?k~Y-g{3NnPh4g zYu&iP*EZ8*OccFf4Y*Ij5>U>2;JW3fvZ&F#mj$okPzd#Q4Hvr!c-Kd^jH(Bq0YNgC z=7SskLkuKgwaa1-3@rVs&}luv9%b4!=GHI$;5BWZ>(^k6?oL#j$O4?N4L%^BNP=E~ z%p!EEpQV5Zj`c$*@C_9)Os5dF;cWSpNz%pYr_^@dmWX zOm)XV6V=Z&;^G_{0!3l7U*ucDvw3L>6Qkd_BfT^sf7 zmA81UDo8vc?@jS~{8i!IrtN2?#20AtC=WOX2kJ}Sa{6i1TLf_^m|i1MgMv849n_`I z6h##_uCKqlxXm#nQsyit*F~P#w9CKmXLvSZK2B}BMqigsR8kiuO8Qt5vDhjl@L9mk zrph~*+s>xPN9>d}-yw;=Ncy*re{tcxix2B5hzE7QA$B}`mefvt&CBKt*NLF^i$Zfi zik|Nk)3r?MW2%P6q55#NSKDf4XLZOPDi>hU%ShN-MO^(b;CHC0?W^X5mVA2>ix)$* zjU`K?=f$VnzTvi~g^Y1p>n_D&YiIY5VrvwK>qYEP_~k8@CSkcQR#;FYKP2KLZ@Ay& z#yOwC80%_n*^*!I$$|~KiY*yc|I*3zd*kqL4eEd7|M1tAzb&yRE+YIAz#G~rPT!B6 zmYLwIF?%63g1m@rGDKS(Kv>RCbswv=PtsA|Oh?AsclO$GzDQQF4*>Wm^a-QAJ*3F- z7^9M<^6=)|_8SFpHaA0&0C4^*m{^c>1Vm(eA@Q283bW5X0Ywfr<1=-_4OE^Wbn9Eh z_y5#oed$67U&@puVJ3WV8X};j&?%C3fJf!@No&2{l#Da&zFA2x?pJyBQglPN$VHDr z>^*ROaKD|521v(3gH*)~rM@(cvTzm*g~x33HPUiy9L>^=(HQGgwdr1WXOay-NIu_i z4+36eiT_eC(Kwv;RRM9jmhn|#-&8!Ie70Cd#Z^r!BwrQAN7>$>Y#qCoB2T_-=}hR9 z%Fe?LOxy+_wH@C)1s606A0i3j^$#gujA2v3uBjsG8alE14@# zN4#vdu-k%bs4BU%8!S~{lInodbLM$(<>Iz_&AqH4=reop5NN(w`{#S&&o@nm)b*d2 z{o7OYpIeX;wq$vsJj2QyE_W^Qke$ZeuysP?tI3)r*a?~-_)@Fua*LrlmpvP-aMvfJ zUlr&M6ApiAhF~C8f*u}O13X^fOol&0ANK~T01NVXH`^U5<;K-oLTh4Po5Pn<0O)|Un&c`kMEW^|E@0i=BmZA|O#o*&++XHM zG{UH3Ep(O_$(vnbi!v)(sEVi13s%T_wW*@3P8F_Kw1CO9Tzx;A5VcN({OQ^+!AIco zAb^NJXKbKDC~Y`VW`!Gzp=i2>FzE+StQO844Zrn^oj%jU43b<@dn2lg>3=wW3i$hj z&*WbfHZPH@0tD}}4zMPnzcN0#&PQt!`P>CW1+sWcr-60B^|x;uyT+(&eIC_JJkxvs#WNZ*%XZNG29$dUuo5;qo`hCMZ0jbwaipiK*raxU#kBQ8 zFZ@E?s$;?fW0tTc75#yHjRo$O|CkD>AU9a(F;>)4lJ~=Y|5i7fy>cP!)mbU=4n7h~ zI9Z=ap9Gy{OcfxB04kY5@gpO^`I(EAK+YQn3BVHBNr1UeS%F;xb#OZ}3Yx8Fny?9- zG+8j*5RHQpN_iR+I|NqaBSJ%_H?nV#F_Wet=}BM$*MYTr%HXjk+!zqJu8d_14h}_* zK>am1s3V4jnEi`8g#kiO+@gVe4l`})2d@LJr+fztE)1Tz5W>BGXH>rfe@TbScOd;W zB{P3WGRM6?!2H{A4ylHE-F2>*H{vKeHsF&6(1AYTa(tK2(DZbS{nobzF_xPTj4K|= z%f}0bL0jA1KZr{FQ3m4g_z8V&{o8_;za~D3-v--yup??0u|QAU{@GVYXB-;+h$0j0 zaG2k$RPGOQibpy5fYk>t8CozkwFw@coK^+~EaRmH72QW+o(EaP)dL{)7;Vud?oDNZ z2ls1dB;cK-bz6>xI4&AY3c`e%>8fo?wGz6k$}(O9>0R! z@(uw=!|+oH4;;6bl(sS>d{3lQ$2Yfl!VtX2K&p8B5;()4+$v?9Efr1SZxzIy-Y)W2;Ajm{ z+KWh}{;jPL3HG4Q?i%%nyLNg3%t03zF8`oZU=5xz^@9W$VFc&$8B)6!`hJ$L?GdcIyKXAt>Z%T)>IF344FqEqm9DKOj2DsBhnJF#2<6 zfSqJ_1KY}QNQ_4^2=~NCsmYBtEKinVdc3N&ftUAKD!u|(!0TW$7RM;>5;k`O5|owN z8OMu0elebAo1K#>@$OI)d%VS>Pv9~0;0 zPY`d>&$W7)n-;>HW`e;bBk{d&S>x}Kq_#W++t7+@+dTmUnx)uj)NJ|(EgCDWpK>nP z{Hp@zeI|ZM=QR61=rkUZj!S@T3iE<~rnRYL;-|$28Yz*CjaSzs@)qxAwY_))^mc&+|WT$p1xQ=+B%0^q*HuennR6Ium3ZPMdUDRGw#7 z=NxDd`rg#0tM^z__bqe$#;G;#l>NPztpM^98rPvTiW!)4hK#31(T-}bsR93Q5EgKV zn_EWf<<}T`j?zd@3^*b1r6Dr0y39`wmVrM=ZW|IBms29BIk#Bz>C_Z&Ga@oG;M^|Q z=vhd#@XK-|5{rDl*L}Ng&qnGUD!PY;ZAiZi@$Zpm<5V=UMrYPXixZ|1CQl{<+;d9o zjtS&deljRf8~OZzGy$Z8w*syrxgfd#xE!)PF?__tv~mbh@QiQ2Dk=KGwM*}F{0AqN z(U(~^qEE@50phT?CXAR5f3GOvKjw8y5`6=`PMnp-zg+))RboaL#!-X(%n%*G}f(vEurNwe{d8;S|HKxn1M~~ z_`c1=)4;oVh0P~f$3CViVzKs3W#G>pj-Yqrc44y8F->7lv&y_)cMBti38Mvse6Czf z-+DMeYDT+Btn9#wsRiV*xoBMd(Y|*et~)12+EU=@p)J063maGE5{q=eCdjPU$&p>c zcd%YtsgzV&C1$t=s!YKX+`UbRFG7^jpBjRAO#;&FFh@YhwdHyfuM(mp75 zONV~~A_!Um7PobB^$Oqa+gx=6 z*vcge3~mGU8X27c`)2%K!rdn`K`rsGVRF(AauE=51;IBY!9nn?1)@7bd14R}41nyS zPri%?>KrI79jLdKF8N(D`X@0pfFt0MDG|R`J;NvVD?8fqsWOTnjW-ey%h;Nn9 z=-27jaerS4RjpbzDlVay+u2FpT@(eOtF(yVnZ~(U433q#yc8tKwE2uWVz%;ZplK-H zSh9yFQMMv?xw^m|YeDGQ>gZ>U`w~~6+}07M%#qOon5#d@w&PU!RXoIBFuL@Zo!cc= z`?TN0mso2M9<9E;{tn!<#|aMwJ75E@D$fNr?Cwj9TjQ!Lzm3yGwB=ZuFemKL^)GLM zTv;I!*u6K#ZXIuZVGK>W7@j*XTsjwp1=d%}=FyE&X*qJ;Z(X{ljz-hSM5$GqnYE8+ z=oa#A_5t<`l=r9009Q7FUK8&0MuZGLlXu|3J9+CP1kj@YbX5=jd5&@!@&)SI|NFNi zbp{#Epj<2&18#`IzAAtiXWI8K9``}Pe^AN4kzYk+Hmz-&&UJo!{y(@z-NLzwl$ z1_noPjOS>09ZS_E@Pb7c z@!R^6HZuB({Vk*h@rMv>Z7(cPYnUWoEz>I9##1h_QjK256{p4{V&FZH3$;7Q9evd- zCV4I~3p+#6z%Pj1nf#G;aL>3ia=l_U_;kHr4AC43NQA>4ApCgfo0P()5|ykoh?>bU zt6elfox$P-mS0A#>QyMyUdwMg^jKHG*p^C>aW$d}fhOkE(`JLu4eU|1>}ZtF&Wp6 z1rg4V^8Cp_y-~N0W%q@Q(UhtsR&kRmA4lyXO)d9f;dUq|4TB%e=lpC z{dcKJqwxYDVCN>*Al@+I0lCIW-p;O|hV#aF5nD?l#TApCF-|Tvh&qCtU)!JTDKG50#USYOSiffmHjdKe-62nOg_yQW#P4oFv zw>>p~`uLm7?m}G4C}u~!$6E&R#k8xECaXl58GT7hUajubs`x6iTV`Hd`7Z_0qp)D@ z1JcM3H;IL-ehT2m{(S2hp1mOFHZh=^Nmnp26= zxsoBxw7kd{UlmU1-PXY8G9Ws@P{I-ci4UIJ61;*`%C!b+XW>K@K z^8g5lMW@L`r^BzTTRhayctr9F^$*V@T?$%!th&>GOjd?|I`T8=Y`7{gP6mP03EoBPlE*{*ZJ4>E5 zTvoT7GVNjTtKsyvN0+UFvCXm##Cvj%->;V_ZL-%^Wb~)v#~e-lq`7x~fy%^t0sQ)U zochCmva0$Ysl5Js*T8?fhS^P^!22IR(1-!d&qC0HY|uAr!kCZk62hS+Br#i zx8k-}7A#MSpsh@{;k_H{A-4VCM&?j6f5Nlj@>cG{T{3mLexW#|swLqN{b*xZhb4O& z^C_!*GQ}jz7_OePM~&M++ckK`cLUhMtg=MeNk*N7r&zYax!tA9+iF9RI4%jMJx)u@ zjMq7Jr#h_XzKYwXQ}Zin77qQ|)co+_5YuZGmZAWLVStrAsancR_XMWC!w)|F@rwXn z$Irc6*TY>I+r4hNJ_1Y^rr$aO!rM99u@f?i(;#^cV=KPDb+UAqb@Qq?9!JCBuxG88 zaz>X6_xrf6wXttQ+rBCU*fShJ=QPOY+C~N8_!9Hipxwx{3YvFjT5-5lglGgj>fnDa z%HrVrE@fTt;xk8Ft*4)erc|Nn(;K*5wh}5B?DB#F`rnjR$g~(u&=Meax~&PfOYL9E zo3C%h$c8i9lq~Hip!Mg8Q(-(|x%yM`DP)k7@Y^_*>dff)s*s&E8t#i|I|4nVTSdm# zM{;FJ4hJ=x*=_6j%?|H!Vghd^J1N~gbfQ+?ceYi0EjW$Ah3Az3H#HZ+mTg&KTG?e1 zYgbZ=)~A~N9BM;{=Erikvei$nH3B_%UNU4Ww7FZ<{RYI>o~$cK4s|#MEYV^4uNJlf z_*%jokudqGz=%@KSl8P0Ba8B)B%vkHt?c82mxVW--w0(taqiJp#dXy2$Z@j9%TVs< zRV23$^Z*T2IJiQXo~U$ob;5>Z>ki|IsJ%+X!L(R-G}&~u)%Hrs^V#K4fx|FGY`Cx0 zcQhPYR-*OXDZsUD)Hfp2w_}~~MM3x|*IXAVjwBMGFGJWI%rPZkyoRR?bXbyS%i|{l zN+^Mu0kn$gG&a7b9gt-=4i;IMzOW6njE*Hw7sJ`bAoDrK18IERq--O&sg4$)eFLcK zBdbujocGeByttHBt*KEtuu6O`$K$kKbi~g&jlW7>_s zqfB|UUxrebAwHzGZ{b@^*|u^qrGhK!@0FPcg!p<>M~rh}(7!*G>~S9y>BVI^Wh)sS zylid-E8-4a3ri6@RJg7XpAEI}(u~XV23%6m$Pjqbc1}d^WaPGSb9baZUZ7avGy6Ce z;s&^&$HkYDRWO;4_*)8g8wmEXeiHXd9s~XnSDq)Sqip)!qhipeKaN`(AXR zjt`~#fR32Ty{(tnph>-^g|V?sev{BHZM8Vew)XIq)gP8QNgUl8eJqeJ_+jArKxZQy zF_y+Cz>f-QDD4>%cX`se+)`5!ugZ84wrTWuNCMrd>#5Jr(*021uL(9%VhL#40hPkJ zRG{|ez<9?nlRqK0R;J>H=x7-I#FGG5?<6~is1Z%`Ems-?H|W~9?OOXAJt<@AY70)2 zt)`m*0~Q&uS>%B)3EN3qN?#`qe@$Jui*HvqV&&sr;f-WF21aO~*F^?&JlX+DV3B%X z*UIryOqneP35>6{bMeK`f+-O!G!`?rZ3M^AuCBv=A9pWhv6E-auJraAR>#p8TXmMl zSZ7I_#Vft>!*b`*v2Nf6cdUIc(=riD^Yu@vK z(9Ij}r+@NpanR840vl~j^r2JuceDs3UpgF!ItcZU3iuYJPG2XWs&%H)bmB9-m*&Us z(HBCUwJX>4!gUs36*5Pt70(~aw$PO@UvSiq$|Dgk-rNA{fu^!mLoAK6DTrA8`@ISG zst$DxBD%4n`b*5=7UD?Y>Q&1)LABrsW}kuPTWK)5c)1QY&zgA8Hz{==eDCA%nzsbk zZKZZ3+l+}~E2s1B6upYx&cKhwABeBJ#C$ge`OT8&w-c?z_a)#>u0z8DL@F8*j zJ^sjH+s2YzitSsfJ{}5@9x^H{irr|th-*AMuBV!@c+X?H3l=WBFjz#YfEFCbjBAS0 zhg~EtYbt-SwTS)XTK}!}+-J7B;K-`9X}g|E_V_#w$ar@ctHlMl8gfJ)fw;rhSaWbK z{dna`vto<0lOFl?S!uirbvfJIb$ix8flWbVg?eCcu#oPBy0H) z?+p4mffMR3KFWSJpk@z!f?j;7u3Ft_lSOdJ({HMZEs)Jp+6wqIV;O3EvursCpcikT zD~g;ue%oq(KrcrC*T6S*mZIqq z#toVs`&&$coec|YZRb~PKjrwnJbF8OJP~aM>V;wlV!@;v1|U_27fvZI8#8 z|Dgs#(W}MGKZ+hGaOSBDIh9qiDKin;$1dPlLm3SiTW6i>=;V2aTmuR4&)diQ!`>JP@}0Jox{7r zT0Uvyu^Zbda+zK2U#1BJX;1R@etb|CODSB%x%bO$+f~2$TtiHwK(MYG_hLVeEZl)J_Q!!^tS%edmlr7TzZNaKbOzBR;Uib>@CGwit zP9_!|ls~a>5NA}zCF{OIx84yL?b_{JJ+9g~E;BzMpEmGX(JNQ!Lb0BhM{ zNx;Xlb(m8JC+1z;fM6=m8?+LSp||C~z0n;fd5TM>LAap`pM}~W&>N=&U4xcd=?Az~ zx*C*)zYp8j?Cb4q_iA-tpGw`z5Z0QD)ZT|Fxb6o7G#zyHQrpu(2h%Oww*-q?Q^xc` zr$a7sG^Vd|$??8k86l6F6+7Q zab8U2Bv4o=?^vQu@T(1OGIe5iOT5Zdwo@RrpEwJI_KfvJ1j*<%#O6k_3P$4Yi7)aE zu9wX!xMmT^=iVxce(DX~SR;02d7fa}d#>T7JC~HXKc=^>(6e(Pj+Xa^OiQWSGg6D$ z%u3@(6?_pEDW+Bgkt5Rr9uaSl7N4JsRqG4tqC_z}4)%0C*4?(ruO8NdbI3UGoi;of z2^$9;w!b)32Ytzqt)d&sW05l?Fl?$DJu)3X5+)?+oKf|3Fg4rX8kE-^Pb0PU<`$0; zHaK@HWxX8{tNyg-zA1j0+;1%2C3z!{EmIsSa8(0C-Q|4`dG$&Rtz;~PUKKk$HNTn-}%y+nMFc3Gmsj9DF}bQ@ng+Hl+yUbaCxb&NOW zVHq$)ttAZ?%XGcS%K(V<0#+(hCc3(o=8B_p1V~%P4~a*b=sV~5H#~m2AiABBYrQW1 zUGm!AfOkoBZr393@r&gQRg4NaIdgWuLU~nyccg;(|9~PRDo?CfSp!a+yr&P`I`MLb zG@qBHTNo){I5jGJBYGtVHqOD|eovv|^a8pD5Qm;kG`ecW){t|gw1HVA=ChsF) z<%#pa5n6O_+&;#WhnKT2vbzue{m!2#`h6EMz>2VKqr^dqaOMfQfhUxoC(EN=MbPs+ z{1K}fk&saik>oRjA(a`(vuBj1+NhFmuwTHAM?g5Rq@(|6V_@XzQ%D(7b_Wh^>D;WF z+^2IqP{-{-FR~KigD@XG2DJwh3%G*95j%*g|$b?c3qIO1Sy%-egr-$TwUB=*6u!4QR!4vPH&OJNG zgX_SG-vItP*BD{(a{@UEW<0`V;+r#7{rWKX4 zaY)jFyk!#eCqZPnNnU{b97W=EX#qe&qf)$vPz{`znk1Xre>5@9u62*)knuoUjp@!& zB1d*_MsAl>GgA{RIcLFAWYm@Y0DX?>c-^%M#v}BqvVT;R2JeCAgWLWLp?<6?=G2n1 zr7r#EK;q9SFAo$6qju9lJgXQ@KSmaB|H$65?Gyp!fmjISvzK`#K-5z5FwW*7W$WJd zr!B};e{gHNfh*ub%e4HfNbNd4i`GFcyDp0C56uBsOwgqZoI~lj<~7-Q-0_aPJO%NT z*~P=iuX)NB0q6KM0N{o*03|GsJDiT@Yp{fH74O@C^KP=Q3hfEa_a1X)Q)__`*GljS zmmq!&tQ^Ktq5GmewM@3;aQ!nt`cc2=AfN&>Q$Konn!&}KAk9g+n~c{Mv|sZaJlb90 zE0Ka=5i`*s7C7)fq*r+fM*;j7EOR)vyK_>uq%=*zd4?RQ2oiMzd@&pJK!b|d&61xF z0|f7sXD`TeDFt?3)LA&V%dj_Aq=APIz_bx-rw|#8Za(VLa4k z^x95Xpo6V=*!l93S@H29^0f2%W+@Mh(D0XdVy4Cr=rb3 zs{{}gbO8_hi9F><^~|KA4~dSPT9e0N8AH)5N#pia%&!Wo4#`u9MTGnb@2uC80P?=V zNf)&pW3WVmlOjlB;TWwr5vy&eQ(1=qPGDV-Ig-1 zEb_mOy78wl?SJfZpubgJV2024w?JNhz^}iB+;e5t9e&1%QHc_qm$Y@PvFXPGZ@W(| zo~M>w^6knr`~kc#`9R~A`tSE`=?ECXrN#zvS4>|KYi@peba^eu%UhjkvG&exb(3EgJKm$Ivsg8m>7#y1Xej%kV(M`dIr$BT;?<^UEI9 zIeYNAXBze>EaCF{%{HX_&i#_&F=yOK6)nlmD6y7@-MZNirq$+*WUe34jSD{3VwzO& z<}E^(wSbRg`lk)V7cAzvI&-$G=B(A&mHQ4X<==cA`HB|n}qz4Pd} zy>=6bFs$Ay8dHzB3WAAby#XDSo6z{a*QW1Pgri`p;XY%; z^AGTLnX2C>uFL| zfIaI5zR`^yAGE)v(I9@cllA%KGJ^!uz%oZ-Yk&9>85Q)XPs%nkxR5e@3Rp%$L;jo9 zV&_tJIDO5jI6qs%`1`NMS9D)&vDI~t*%fW)aZ^$prDa?4@nrKkpGV#q=kxSV)jfea z-MBr@M}D03)45flz51boC5@DO_lmyHIP&AXqxaIh+Vx_*iuRQFwTR_!9__e+T+VX( z!^Ggfp~BHVs*br;0xI%k-&Op?>#;;{UrM_z)Du>P;ee|bzaxDJ5HmaQa|I>$hkH0k9^v3Fmpa-+z~@@2WZzdUpKh|%t+HN0{yyYlHJ|_9eMfcDCj%F z1CY_Fa{*fL9ap&QBAWDn|J1?$xVN=5Jp6Rx7|p2zp66 zBF_Y1x%(B6iFIM?*0)-1!0zjnzAsj0am@x?{o`rgSG#RPe))CeR{^Mf$K8{8gDbDd zFK>Y{1LNU60{BW}rHc5cc4g;kjrp_2eS>p%tqx3bH9xh0rU4C#mf!_&`NFaV^j#nq z0u2h~Khi-~G}lL-=3_Ae8uOpLY8**5=M$gWh%4S?nWjrwEi}ZA)q{gSDjfX#XHfl5 zcW>!G2GUB24KQBOth4Ei#we1b-ar?v-dag zhKffvO_TJ7rt{?>xjh38A}^aXTp%)ThlS?znsCGP(kj1>(9+J&;dKT1Ox9%Vfq`Wc zJn9=R4*Is%;XCEe!OM(qkkMlxCA}L`M)({ZQ(n+RiScnAC7=x{fOhZqVq1PVxp<1F zU7@T19|it|LjJ@lM_w2Vhw(w}7cLLo?)*bO>1o%apLv59Pudknf41E~e*iaEsX~1A ztN$Muu>ad^X-Z9UP5ufw#cHD*2ct1$yD_OP8l93+uGf4oKgBp+_rnje6;08rlNkUo${M!<9a3RHFd@B?C6!Q!)yRIpgaHLuj1H#m zC=!vBaA=qpth530@DdiQ!vx=~sHN5T}V zpkET7Q@<*l{`4l!-+^t?76pos=Gz{}S{*+Z1S^L)Qo(wn2azcNG`Fb{Z*y7GCz?IK zA!7^;T+NWUIaf-knSpf95P%!u0=Rq=(*J-83pTUiu_D9~a8YYn|Gf17`4#Yj_=O0% z|HhiYG%SpMha&EIUlnZEJRmik z`D;vDyrCJSOB-DQ*znRc69D?72iT2+f91CiNR5Mke1pjMk-dFieAzWj%t$}pU+fLS ztO_uJ(ypxNB^(8-T0jC>Tc+;V7eV82=cHY&2%bK@0?^~A%xUScmQ1yumuoPRCbGO( z+3E%cO*7{Ygi;n+v7gvJ9%Sfh9-qD{ZJLTFBgOeq!cb$=ck*to!F0OZ3h)NB3`6Zqvrnn!a)sU`(1vas3!=3pQ)!JvCu4`j|j8V2~m~;;QwfY^% zJ{-#v7@IGUzlTwGJ^7ACyvE&Rs<>4V4XY}fg@piMHd3+|+mn7q(GHsw zchoEfqdz1%D*`4}frtvy4W_2Ug}n(8`E1M_)h1}(nzDtysx5Z86%@@fsWSFn zQ*QeCqV}(sxTUaaJ6&fE;9P;=aqgU!TpzXaX=>Q;CECJ(t#y0QtxqpL!F=(Zemzzn zV?R$>osty9Zxz?AytxgpVzlujqm`t~ER+(pS!7*3dYPPW(i`uMQY0r(1W+R>%Aa`_ znx{Lv*y*t6nV^X{@f*G3k~m6drNJmPz#7#7e7DgEP^>Zt17x2M0AxelOI>RSDHVI{ z>zD2QWAdIf zW%;1%YA}I=a+x(hx8OQS{W!%NaL`0{ZIkoYe9RBrv`qNoy75Hd4p~I6{4M4n@MDWT zYN&u_*&)-!*U1*$M_Ywoa>TQ1*blwSR+geYQNZL+jO?Yn@FKS#6?cBtL*f7@EDm^z z7VDfZp!WB3=5wokXAg1K$~(@ng+l`WP!n%*+gAk>Bl57X=hjOnI znjQ4-#FVi2S5iQyeMS4IgcCMtcwaU6#+Tu7^+VQvYTd=QaNxMXeOWyi3bv?r%R%ej zHysWwkJ&vi@hw&CETD`i%JyTjU9A?-gMf?*B!{@RqToiX(D-I|1KrT)$>2tL4qeke z>9^LRC~2Eyua50*NBQT2Q|Te}YT0@QSIWv`S0JApB>Gs|^TCV#`CaN_>uQ?nt`ko> zcbR*|Ukubd{mg~4_Ej{G&{w7r1@c2PN9DJvY&ZaB)ugid-qkvb8j1CE6Hvo95I(P_=a;J)wt3+=_RIs z*)Xh6JYs?6GkiDp3gk`R0le4bg$09Vu@=7;w+v4Rbi}%4$5~~?%csQp)MU@u69w}6@y{Nl5BPWtxEGTl71$KO05+X zX1R_#8%O9zTS9e^`%P%Qb({?-MW+RFsz{4)CHZ53@ZU3q3eu}Hdc^4?)?%hp8$Ukh zBTMFN)1u#O#eM7*w9ne$%bFJev7{GrJ_iDkzL8$rN4JcB?eM>p7I#cYF7e63_cJ;( zQUg+)fJCPYem1faun3uzT2Z_9qd#RF^Y%AWyoImI^y+eD1tgeUt1f8kE|j^Ia=!(1=+B53hMewWE{!MBUP;u@Y;>}qhX?#SjhR*GiD>L;kYBe)6JHW%_~cYan|xK zesxY?X5DUqY_;8LP5uG^@pN9hsf67Cxu-RoaF=0j$4gNnLSXM!9hCga>zl1f9`kO8 z?m9aLG!_R;m5^HIE7#^>cs{YJTzpYL4Y$&7cl_-2RA|4c>5!fI3zk=&#_d$$_L3ak zle-t0X?si(J75}Rxo1%-FL&#GHWvP4V=gtDzFyAC&7wLN^3E>|ihP`&RqHo16t7`P zNmQRLkj6PU)K;dC*-6~wVX#kNnE_l5K_B=S1@*7d(Zdp9k0+ET9LD%=)~D~O-1Rwu z@nfB-O~bL$GS^Dt8L%tNHfu==3XPmcA5o*=MVYkB31}q5*(N`3>Y!DVJl0?Dx7g~Q z+Lhni>KgYX7mhTRJ!1<}Dj;R6RX~*S3g{c6MI^viO{n4IZ_3mHXigt-LlL6h8Q^SN z)@os`)#Wl6D^F;r70Bc4(ZCDDpb=1w<*@s~$nYfKJk`Oh-erv)M_PPLsHCCx_c_3>x}m69x52_U4SQs{L1q`sQzE^v*6Y0XE_@iYiXG4$hntc6J*oG) zS@TQIi;S_g61Geohvcaxrrw=TwlwkcEUc-D#b_P}xw3+yHR~PdRCwO4p#MYPXgx6sSur9s`}ztGFsp zg?X?$seSY{HP0L0n}h1Jo_KA>H;bQV@IwwLA6#RrBehkDPne}0=kM1Dks+IP=d8XIt$mzGMxYPTZuwapl^6HG{Nh|#vihNi%zA##!Iy<`> zw66)Zm00%%+7QRBXG{0pohAKa>m)e=LLEk@tgWl4(k+O5TYKw(FT)cASX88E1z83D z42aMZB5!Kip8%}0{?}dLh#6o^w)Y9)*YIL|8@5WeEx_AeOsg8bX_i<0JofRKf(wqv zDo>>EkeW(!>eUb1+^Mp7g54q{r_^Un8|`821Lipd1SJSSwY<@bU>s8vNaF4tf&c1n zXH7T%^CkaWvA=1rwk1&1Sk?yBF>dq3Pu+UWo4cr|9nlixP34+@0KA3rltcCgJAPC|Cgx3%S5bMpo zY=8{Eg#PkX8Qk;f|GeXW*6P1tCCeEr0P$LMXgll!%_BhOtX?#`Q+`i#j;=+eNpWvj zZhHIP5Pj>M*bmWG(SlFSgn8!5RZ(~|R7%S``nS56eHWlTDEJTuAjuv8EM#aCfA~A# zzp_DL0$tC;9>GH(k2~u?#WxS+%$h0vIY*}g%0q^&UNAnw^AiNlaZfYzO`XfVByJBs z?9}4c(oRpXt2sZ79VHA_q5+<>h9we6x(|68q1)0tCDe#>9lZ%(ek=K;)Ay#fL8q)< z68K#K)(^Xwnt4y>`@`QSOO{$7vu!sTK*cuw~WGy@_HsG?N; z1nmTf{Mqz9Nxr%3|RCl5A$TA41Ffjm*@aa`%(n`3R{)X zrom`JralHlVy$M%K^icz9z6YDXXE>X`ZF8gu`ev}dw4rdgwe=wy$LA4m4?D%;2qEs z;5DB5gDPw2Jdk-F!!@SiUhDw{87J(>gCx=qna{}pzC22r)VYoHrGgPL`(W%o#{ciG zl>z*3D+T?}LjA`^_5aO6Z6b>tc@fL@?4z6Hz8~^w1Gc>YKa7VXp2Jj0K6=Doh`a2u zTj1rr*K4_tLPy|fmGtmWrOo~!rC}{)!nPeRk5n49H`Uw*+~7MwC-c1G1nYx0t(*Og zJB_FGqTAZ|BWi;EO8RX*LEI*fA2QmnZ$en2-6MStG`)tg8L%LYGHWTZ=eK1?b1n!mxIYSaU9S_C3+y?AvflG=<+Q2A@m4;?GFcRb;(U(&`tiCgr}VEOr`g|n`3dE9R(uk8v~MOU ze4*=PQhofN_aF2yD*G}f__Qa!eMECZWQVq8;O(o^XD@EKMmx&$G%`8+`@1--dTx=<#bRg22I%Wj_=mmVJN4zKpC&-y{Ov$WDs~Z0n4z-qvT(sM&8H zSZsQ;OE#gqYV5mTgOj?TIGBZHYN)5bBklFyT`grNi$iixmb49)J{^-Is7)LsT*RBTHb-5H^0^HM$0t2B$FPFb`S;F8)h2wR>TRO|Z~O+XVn(sl%+)&3 zWFcJskR9f{?#rZY@tQ%~0@m>BI*G+tyMt2%Uuv21WLzQXR8YC^P7TBb3}gM2kU2|RfBmlWPzCuMHj#8JNg$ZBk{&PRHPRGIMsG;k0q?%-rB z(WGw??O)Gl+?HJqeA2P?6hscD8 zg;0wzm<7!gMK^;sT248SJbMNOf+mn>8n(`DG9Ow-kO>87Z zCv8XF_}(s6&WFOK7eE0gHwiqL3Ee_&jHdPs0$L{?T@t*5!r| zwirEp2A^@TOYMK%T0QT6ui5+DJIOl_^SA*CAIXK|s*G*4KOV3##dK#>U2Jtsq&>_N zJ%evtIqJL^5oa==Kg*r>Rubj3)moU;Bv1`Z9@B^DNvC|PH(eb0ru89{39J}X$QFvx zHc|F_D97i04J(|n5^XlD%)e=Py!qEgHver{tL+DV;{-Y^FkV0wl^(w; z)~u4HwgPHsk|w}-Rn4^6WCT;M|z& zj9wE@3FfGT5A}<}Xe%*&>I$Z;r^f26CVt4d+NflYb;;}QC>F(}-Z;z<6=hp#$4R;R z0D-U*#Y*h(Kg?wYudpMD*>sAC7wT{3jnzmKm)quLJpeY>V0CM=ogX2G--2DKVKhZH z!<4=qb>Vw2ud*N28Xvr@VwnM|?{-91Nxj;cQy-zGap|W?OhPo!@{}uh>Va=ek(Q+L zDu?_??5xzH4Lx*8m9})+*Yh2%ypRUsP^mG#-@!Yzu7cszGEPIg?(uM^;I!dw;I?+7 z{B+_2D_6OUsT`=}bCbM+Q1fWrduMLu{a4S@)nWq&aguG)Ct~}sFXdth6*S*mKBzYN zZI*N?X~%N+qvA^ zh^YPwQijO42lnkx&}G}DI+_9UmZmf|DAhP9Ip;oal=grDg5&Efw7e74_>h~dY<77e z^R|iodtGxgeU8SuM!Kzc@<^jW`q7vX`9r_Oey4R7CO0>|t;N9#X*k_y?9wyjCIh z7Qy0hNh|&eKFgaQ=p}JM?*Q16L(Z|USqPvbUh>Qwy663iNvOn5KDq$5xv{ z-}-6$PM&P>$h+6_t>Sh0FGG7QzugLLMIIpEEF=dSki5=EPD0OoO65sP(KN%&%uA#yIYL9V!(NCt4hoD*fyJujN|Epf zXF0bn3>6)F8JMZQ&en{=5Y_s-ug-h4Xi$o5j_oJjlmK6Qed_>CsfY@o-flElOclnn z;mkl5$Crmb9S{)RBPn~nj`S4dM?>32tP~3?)qE#@xeD!k3dUExAw_1>y+g}pPMPb! z%OYwXI@@lCb9x%er>}n<$qRZ$+Hwp_)=nsx9X;2Cbc40PyF}|0=JrNZl|YKh9BQyD zXkPYlZDV&fsYgEGom@|msfdnjtKph?jWPKwOfgs>%i%>V@g!%bm93<^iHa#_DC*Ax z!#IvNCm(LryOZ+Z_5*|CWBcNl+DOaB>eQ0#M=3@2!*Me7D6y?X6~6=A(e7-NEzalr z+$?ewM9ql?GfeFFm0y`%EkfRt znC&I36uTZz(0{ed|2bo1gDjSvKgA9JyYrOsIcXb8l5TMBqsgwFEudC7N})M{TLSo1 zS((s1H5?H(K}G(ox+`|8&8C~(2{p2FiQi|S4MeqANx_!}% zu~{a=zN|GCyY-z_4JolQxGDCPN7CvB-P~fO9@B?91&7_wMdqhu)qLCv(QnD{o|aHp zl1cnl21CUOb16pI{O#Dt_v=!}Nw;eni~&r5fbz5Xf{``>--xKjEnk1O-;`@R|&xAOAvjIlHLl2>6Z zl#X!H6bothV9{~f3N*F~UIZG|X4CZxV;U-1IeTBz^~QI@up7VN2)CJSm2-Jl22jsU zEju_*A6v%W|CO=b39|wQ5*Jvt;Y<>9rzaizn~dt=^stVvlma1jrYG{6Q^wy1wM~N*b}qn* zVww0oXeiwVoQLYikrO&&pqvhlIc>6Z4cu}(7PM`dWXLdHg9Vx;)*j9kF@^S3+|Z~_ z-qi=9&xWPJ3#AUF$p$*-9>sUGf}I|W*!>H!3{9lrthF@TSk z(MP5=ikZU{05=femL32dJ}T&yb&jpk98Iuu7KF zB9T5>fXFoi0%cF<|ZX0T01%WRJ zBii@C!z#EXlUU#XG-UgPj_&eBC&?rz(1;!ye19o;LyKm}DeU{fpAfU31)E!R9 zGpEVmub23(COiRLY@RmF`XmS5#O#4h_zbBS3nRfc&B@8lEsNt0{FbOyT-$v|dvX)?^T4Jcg3U zyIDAB9yIzZ_A0whokko{iPcO;fdjIg&*(d$*yE1VGUUQZL#!5nIE>G%9BMS;ihNt3 zuK{Z1+^YcA%boAGTdSE5Ixfd` zQxZPPz1dE{Tg>t$?xDm2vXBd8+8*Lh0DR+Q`rg923A1z)2_V#ZR6m)hED$-xI2JWU zdVA})4x88e`$}Id%G#`9-}_^!t%%UxsZv_|s!vPR>nC0!)pq`@p~ zCa{5!OORU8^--5jZVT@{p(Y}6kg($pie+9`^ef0{!gsig78GLE-BCRE`(^u!#1z-P zt{?{5Xh2=x+z(;PT_hG_66mg03$zE*AH&|fYkHDw_=uE_7$NgzY?oFzc{xC zhF5%s-7|Vyil)z}nru49^G0T%R;v-9qE_R#mcap(7#TDwJ#e-p>oY^g3&2@m&e2P+ zB@P2Bj@8gNgB>{q6UAm)%Q%ZKtl1N^_6`&f&zCk2W`JSh4Fm@k*+7wC)HkbKA9aG| zfr#WbTa>2$DB&IF=7hVUcR-~{^rNIxM{In9)5;}twr)JNPduHl?wG)OupR2m%EC^A zaB>?Eaf?UXUR+|M`wh7oQ1og$@AgYAzlzM#dDHfL*LVNEOSh(tQ?h+b&H?Yr^c0rA zQ}0Ok5y%bkgQeD8))$-&x9yI>C#*W31&`Osz~(@t5L-4VDaYT@w+Kh0SUGyxe7o6# zy-%KaT+zRtV`ezwGqGqRkNQW8kPdzoXL~~-f0fLM(l25jQBNsC4 z;!@u@PBSHuE-^b?W2o&D>Es1J+hcNlqF@hR7@QN%fn+fwk#-bA)yej`SI1_NU9EV4 z*wIJ{XW|<>OigXwbw^U*t)sQ$X91Y#dp;UTH38zvv8WHQlN#V`qKGDF{nrMS>YhtV;r|F2kT5}Fu{t9-7R0baS zRFZBpv_9vORRe1T+;B>WSi#Zo;|V<`-#ta;!kuT+_kv0G(gs%jZ?N&BeX4&4izFm}%FfF3wE zh+#jf31rxGW~>0Av`z?JhhD1!Jb8|GR-V`??WX>vVWYAB4*6ZL+AG&-2kg231+WSK2pCCbGA`zY4?d!*~8qaaUl5*PAEW_28y99oB}C;q`(JVmrwz> z6bju+sS0TF!TQXiEkG4t7F&HhPvW}4&^F|F>U4$+ncKGAh8O!AH&i_j(NWwAHo z@Fl=!8=Tqtw2<^Wln8@^MFKp-^#aTci1u%h&Vz25ufR-2jHr~#C*RT7@@<|E(juH2 zQXB7D`T2Nw&#g%1EhBH<>!_LJRg3~toHPCt=cha2kBTh8|D;)>&7!oSVLt9+`(*-A z;SCsNPF=}a+De(u%6S-!C(@?E=Tz&6X~mZg$_lkB5impHIJuQ7p`xXt<$~`td5Y;v zw7J|~WnHKrA3tLMz##Tet@6C#k@Mm4EVqEMqUWi2w;1`#d0xshajb7ccZz?%>)6p^>7$*n(XvM?#&3m>Cw>>S(maH~Mu==j zTj44wmsZ9FOv4)@Ryi9?t>zc^H&QHx&}^#7AY*&cnAYuSk>%Ob-gA_p-q9BKbM+F>nB$T(;}Kom zgIDUnoL`9dm=rj8o+}Em2V>2&j8uYdk!IX< z%bUBKuQKE@H9Q}vXER%um$UMYGtUZb;V@@~FBx=ge(^bl!q;J++`YA8e6l|*yg;c* zi=DbEuw~Bl(m)t3IzVelI0l5-T-l2;V{w;Ys;c!KtHN9#(WWOPt!mOT4j2Q`Jb9E> zBU|L2JI?tzL2^zI&O*H5s0a4LYe|umW1>RAg*#r76-9QPiPj$ZUs^FV8gBnc)^NeZ z(-(zP47Y?z83vFPwu4={-$*~p``3Ml7GfzLMe)%6l={*cH6N|$m>+fU`T(cAd8t>P zGwq&_8pAs)Avm%WM0AAI;wF*ce?V?}rla^u6_k_Dt8d+!jz@oY3L z=qxPYD%1rn;zaoCB$|(yeo*g??>O;Vi#ZZxrp}$==+lm&`5;yXL)!rctzQbaIv)O- z`yqGqn#$QvagQw)isT(5^oC37Ru@`aaJ`3>B%Qj40}r=T?1rUJi#4arVeG6rry2)= zX!|8+ zy|qB%M>&DW|AhC>yu%-YUAz7ZgA+h|W0WmjVJpyI3ACv)1E+~Kb$*f>{oy%Z_iym& zPGOxHt3={iejmr7{#3>Q(EUi0ULwBo7DJtHe(pQ(7BZJI8_yT5>$QIOxhEQQTGlQ> z-E6+Jv(3H1i!-YI?p;XH|?!5ro!kJRBg^#1!xX^IyDv&bV&hF-cxD zxYziug?1ceTbaPRCv4Z0)}5+d>{{wINVJQ66<%1f8Az-`m8?kKGIM=fQAgkieM1V` zc1p^)pL)tN`(w=ZIfocyx{=*3H4*1&?Vn}Gvp}H%)g@tyX~HK!l@hrMyxpXiBT31| z?HPT`7wngr%$r7$au#nwJlA92MvTnQGI1Z=fJygl?yo|mu5jr==mM*aDvZ7+)xazp zh()M{B)Hx{${o7nviJIooy)Q5%k6= zS*&f}M2Cdb2o=&*!{Gp8ncWfoNJ3^vLV18mI2mdYMp!TD?42t4RakTB+aCk47Z+Va z9vYVJ#+<~o;T?Rk0?OkPh#+J|f5+-CMXKrWxo?4C>z~M}Df>oL2X-&GSEFLBnegHl zYR5s@SHN*DL_E0BP#zhK=z7ls=3HBX(jGi9NY1GbVPF)sPuE4*0 zec3{Lt%!2KL%ax;7yC%g0c&y&lp+A8shH6go$G`V>8C3ee4 znJ&sPz8x5nq1Z@Q71+W#9<9YWc>xFGTT0|UbJoxwjok+c4!?!=x)+}hlE%)E(H}Be z_8mtL%Jz)jhC5lHfrA=eqSRRAA%x{xJ+AD%=dIh`JzSLJyhKh zZH;_IM)l?kO6ousnGDtiklXt5QBcU3_Zb#{lrFC-(FXiE)3PhfTMi#bj~OkY2pSGV z4J-Qvxr|tl#czkqyucZVUTCAvX#E7DMfV^6kcmDhTlX$M3hs=iJjiS>+ zXldQtoGoo$nHTh2$0U0r6^v&?g$Fk4^i$Ex_Cw&CcdNlDIT)~V6nOvqiHAVU*9OQA zdzb>4SiTKhn@j*^sv`lJ-;>1N=x67qFJwvA-4BIH5@*-d^Cz!*l@|)xK3)AFZu41T^A5A-E|k4sk)E?7V!yO zUJo|o5nu^9Vk<$o;|`(SA!6DBFF3FL88gG#ox``Uc*xE=AiAGXWHM%<{X36gJU(w? zV$IbJfBD}0)PWiM2!p{8zrBeU&X2B%c0aebBRb}G@{1`&u@z?QorW)iBEcr?2b;)Q z52QGTa{!cNB?e%b+F3oAD1Bwa27XLJw0xeZ-tHi}#2^PJOzE`6WO6ern7T z*NE=LX9BtEZ`q%qJ8*V0woG4gp|D}t+zhaOA-j_We;lcOt8Sd> zOWO^m%wBGV>orjpc)n_R*u|3fqJT)wZTf~Z^vR~oiE?<3A0B%!>O*08E%_oi*RFAV zAIM<)|7(kRhM|ugisF-QG*{|B_HtfZTVLjFpkrK8i1*r$m3}Jy-dqR$`6d$>i;2%< zktKXpV?C@wUx&tZCTboHw$BY}sQBfgch9A}Psa7M)DM~1_wh=3t(p=Te|E{t>JX|b zz%{Fm8(j>EA9LE+uP3}^qdcZxscRjmx@r#Sk^i(CGzYqwh;)Nk8E8xuDPMa47H%Q{gI* zi^`i~gAqw-2Fqr6l0Boo2EMZ-5!yj|Ya>oMRDZLK)VvgnVg=y7 zs8Ku>b47y7T0BXOf>bEGfO#$USTa2Y+T^wG&H2@jhkgp&mEiZD-N_;rfCGH)W)wub zb9+%{8rXhwFx3#4|Jf#NgU3s&7kV#(JXsgs#*^Fe^xD{|D`(R_mDeUr#mxJKst+gZ zBtJ+3r*3F8+?mBNVfknv2XN)cnrY0R^w@- zkPBPYeOsw`0oQ@Ki)lw?eJZ;D#T3>gu2|_!#H@t6Umb`e?zD~$Jp_TjA5eIq4i)pS zsfCsSxcEjuK0t}}jmO;|yh`wc+Z@A#fGoh%mp~R^TQA%yF9}5bq&9)8FbIuPXgCqn z|C?n|nD)44|M=`t8c6xefyZ-6b$Z4<1ld;0PQK&;3L2^-I|PECIhi8XO}d@9#`bIO zL*|P1?`DK6L1h|t$vu7t7JnGu$U9lP`S$^85g)F_0LeHU zVsL2V!WVGoc_4y-?T|`L01H{&76|Wy+(`xB)sU;I?p$xUXlvkzclS!0HNWkl|XQEmV_xWYe}fz)DQsi z%}o-BdDVmgT+TvV*wf-hL}Wx2vm58<+L;fGI2p+`GblDD^v4hyy){17;NH%)OI1YlBkx*=YS zoMSE|8fo$d(qT<2F|DmGBR-=mbqscEw{crHaqFauZ0(JSyON(517gL0y&B$4xbGzJ z>2uj*=5(;ACIkl>?|%*=Ay))DMi%wbzV#9zhGcAE0$>fYe?=Xof!H=QOL`u&!*5&) zQ9T-3Nt3^XZ#&%RqrD^~OklQeh1>1jd!E^K9(cQKZ>X8haJudhYNLv4R{V|!vSVHI z`FYS3^~n?Qxqu%syW${`F>xBK%0FBOq#uqgl}eyHimjYO-~E8ez5&lD)4l;DQ$rpi zd&zN@{aci}s8(5}wJj>tcS{1k7k{+8Uo(K6o&prXcL#rws}QsPpci{3C|9hEUjvGE z5s&yiZKhj^`5!i~h&c25#Dd>ms6TrgE3JE}V|HQa0i2~3)w|KBrLebUkd^?56_}zA znC&roH3{_KA?~B|0?YYG7=4x?mLEiR{Gt^dVmX!K+wNf1WNYL4+nQJk0b2KtGScg5 z8lL1_gFHAlFI=iq+DTPtZ}VcPf=D5pScab8#&7fK*w1oJ8hq+R^uh^!{ev|7MfUrH zBfXUb+q5)$oysrvTs3rm6`Wyjn_U!6eOquxPj6fI-rCuSw5X}_-!TIMM>*d#dOO|j zthv*w6e54{VEZ@Gv>$bo2lZX|xIWEP;LE|3RLXstM|qc|;)TYkkp!rx5R zy3C2)w#r5;EMzOyq=VR=&(f|LUn|5<`4cx0V3PkC(Re4B+dKqZo9uDASyQgB$ctET zgm23XcV3_E>*br-|9QXU7vI*As$G(YR-Po4PafHLhsqS54yZ}DAG z8vy{pf@PKi_t{+y0v~MY5n_QD+~aL=YA*+{6~dXhB$YsKRqnfnOOq`xC@$o+O>x=} zePFJI#&mFm@G)t$>=t2)oQ6>ogwKpL^#9o$G*?RmGR#HvBOcl<=bDCoO`Ir&)SMh_ zh*)>*5EuZA{KSmxlY^J~|Y&Yu-wlQd8gstN*L2- z16DfstBKB7HlZ?`SOC1%UNK0X_{Tg51-N`CTzVAl>o8zp8#ACXraO7?oH9YT2Ul?g zJW;RkBTo?>i2oSsd?)<70hv?A^ZZNT5XY{1q_uKl0%b&b_)7Vb;J ztulh_E18kb8bG>x${vjq%8nU0E%+2X$l+S^oq9V;X8SNfZ(W`fQ%dP~<`B!$_X8%G zeQ*9SBF>gfp<^Xv{1)Yi=qYz+V^NT)Q%H1kh0@e==M(*VPJLo({i-Fmu42}AVT?)B zibrRXsgI_%yO3|x`R!Y=p{!^XKFuAN#6SK9=F{;fZm2?gkWL`VuxK)!)FK%djxuA3 zjd0Y=?5gyJ(pr1J11NovqakqxJ(^4QK;TgaQ4xu*7VX2du}aKIemhow3CK zi*DylC7nym%Hx0R0kdme(tcsL5uahvQF_jAfM0)LuQ6PC%mei&e|#Br)8w~noJYPR zs+((d&UEia5I~U9=_{#F9w90WCLsIu|5bBsZq`uQ7fd@k7b&SVC19czuyjLJh|?OOZKi zLIrNOqoGSP6(whp@bf9c@MS^GQW7TKhf~okF;oW4DOrI=38pF>b6Rn=f+%zzrIfmD)_+dPr&0uN5pDtfYVFJm zMa|25;L-zdZyP@x{~_}gLEA$Hfrhr?KfkKshADuMsAL7q!yN$;r@15NpzI_17V}tSvNgU4pI1bwFr;K_vGlS0*Yus8d!@lY7$U-+PX-rd5Pb>Gy z3gUJJjSnz<;;OjYmI~p_?d*3z0_!@32MTxC47M4hh8aJ<=cl&*0uT+Evlc?5LcaG^M z8QhGzMgKEyBk(memSuSBAJ6XtIO!JQkRX5HWo@!H^X zOsU0?Dp4c3!zvo1a9K6u+q$P82?|aAbrkM2Rl>!eQ6Q-XQPW|7Cu6(jzoW@}jM;g) zZVzsoh66l2K{njO7ev6wPO_YPFQKYWEU1RrShL1lJRTg#LsDm`euVBVSYh$qJcuM& zL`ex8RLhrDly0NVf=jo<=ZgI#C-7K`X(tllCy!_ZUbn%hLe=lgt>YC}%E5pXs~ywW zTk=O)BB&y6%4xVe{-MX(?uqn;oAsswyd$2Q_08Ugtc5zCfdrh@Vhc1cJDEB31C4M# z-8*P$h)&s+^N|uMYs8>EV|cvjBsBc!A~^;DIaB9zM0C-c8ID;Q58VOJGCL0}%Q$D| zhVX!fc24N9T|{gPAj zR;wXzPyes?e#rRQVxJ&&| zX|&^DH4+r^{QG*%Plc?N_qfjWAXnQ|FRM727YV2VYF~yg>66+l&z^N#_*=Qp1<>(f zr93|(^v1!tmwul$-6jqt83i-7GOLl3wKQ(QQsX{=QVj90VhdkGCbxBT0pe%I1gx|{N-oa!MT8DMJ^*@3T{=bB|!KE zKq3_giEfITWzu~_v{IjWJPeBFTE=e|zHT;b^AIMDS>3gfen<&A0|?peTEv1e9V&AQ zRzo^@fDquqyF*@b2DKMbZ?cv=7U`ub6{}CR=nKO?734RtJ3e-t)YZj`#nUm26B?>f_z@ZoKGiiqwuf zlDQ859=s7kwe@eO;6OlafRIB?`FBhj1jn;Pa7BQ#N|U)F`ec&3cu-m8a)Q6Fk9o$k zYRL=DqIl~gghLyg@)SDt=d>Nqhh zjECB%S%uNoyr~$Ql42KO^AJuf9tDoSCS)E321!R@F7oOWXO0r(mJ)@nX zj8|_8$6fnkLXPAzOi_zncqBy?_=yML11#xE;*9pR;gDqXtL~*5+eOC%8i!+tvx9zf z{1(IlDq(}ZJyzsVJtyHf6x7{3bD9R47qgo(1c{neSHiDikWtoS4`yZnd<^Yu$1F6FGT`9-fq_?=f0 z@{R;t!&)#;zr(cTh+1~=XW6k0Qa2QwMxb)hwj5BEh1?q%erafH8$a#(!iN6LeqS%O zrgwV+#;mm90W3YB0NzHN^d8r#0t^?3^r}RSXs2Z}Z^Le+l^8{Yb0a6@l)+5aFpT=j z>m4h?yE`{XJN9sPaFF+q&ze{|%Pr=FF#0IaNqj61_iGfX)E)T%TyE_2vqzE*s! z=<=1O*Lh2HiDd6(^S|h%-$^I2vdI}&jarqZPAtlh{0amCVruB6LGHR zh8&s`VE=C2Juer^J!U6Q;n$&`IGzkc1uhMtJMr0JP%boNDUK4%{q8^uqwEkvwO)2Z||@mx*7I#3zQ?OkzB=}Af3-)#S)U&amE@^H$Vox^;DhqR-Ne0 zd21BEx$T3vTItL^$_Lt19R8Z_h^`d*34x(L>BvA2Le0x{KQ?jYnTN9q<{}*L;I> z6Et&tIf_MGpYAG6W=&fqoh=^cyIrHZ02@rkGfLKZwYtA+Dq1bI9N6j+pqgl2hbNn* z0%b4|4p#SYq)5jC070mZwjh$gk~~rL!;nt>#dY2yKzuD1-GOT(k3fP_?dGy zyJEZ4#5>6!)0mgwc|V2v0l8`G8$49$%OJHLI-7BZHg{cuKc0MHYN^dDvx4h>T8MjH zDS7-0l0=O(ArCD##+EPVr&W&5N1LV&;m?X_LXdplX#L`JIA~-fgZS#dI=IG0YfNJK zro%cDYO>YL$FqOP*e1$KtnoyOx^6UE)K;n@do#CP-a27dy?>&zi^Q zMXxanEoK+Z$&oR7jy6h&dV2>|4$2CwFh$y4(YzPZV4|M9vdHpP;1Qu>e7N7)MUuFe zfnif+fZX@efie1_-flG3+gHk+mP8$j8Ugf!*j{1?K0{XbfR_WL^d@Zy&>{0X`wF$U zetQ)SvoLzqZ}`eJB$KMAzZISy)Q+DM-aC4TegeONoZ&`yYy&w;754_AAa;w;l_)kE zI<0FR;bZK##a*{YIloT-Qu6Xm_L~N8&Frkm(_wSJMMPyO%I3;={6o*itZvqS0U)ED z#z3$hqb(#!fAJ*GtR56{Q7ssIDwV*XC3aL;Lv!Ulkg04Mp?pKWvAYHZ0oc-DVgX1l=D_0AQ4Seh z%V8Rl)dGM0a1Nkejg`{JgnaQjs!<2iA}%bPcp?R9y{ftk|HvtSpry=dcNg~Haz3Ym9gZl|l~0SoD81s-0yEhoc3{Ny!`~7vXIl-# z?A-?dJRp_)-vjP8KRNj8MBSl_D{I}`e1{+G{X=V0g6xW_(f%)p0(>6ujfn*$(YP@0 z1z-PKhgy=fd~@XmNw#Im!}`@R3R_8=edA*Nuk1K}=*Z@bp$$iG7<63GFPcu$7Th+n z3=7+~{6I=)Z?&|*4=LS)fME)&c)hqY?7~wTIj9Q_E~(ZiO5O4~U-wb!I>l z+8r?8)ENAs)n9!6!7SQ@q6MIttOAnR&2iw176Zs}4lL=N$Oji?b)TF88?Z#JfE>x1 zSw0Gh5+8y;1jSGbVnGA&o*})&^6a0=_s>tTXBIpGm9r&q#n0A;K3QdO<&e~G#&KM8 zG8tSI@_>qZlTaNhE;q$O57hl#vVReH&s+~spfLxwFV}*gx1h#N_W0a`zycy5fnhg1 zF*^$Un~cB3b*KM(OGO?~(jl%thdV3CVwEvuW>zIIF(&byh{rzQ?%=Z6JplCh=Q}BP zhf5vcK57vFFfaQMYnYSr0D9VW6cU{wp?894xQqZGQC2@>F2J@7S4Ixlzvgip0I>b} zPX4q5|F(6q*xn*Gan%<_H31zLN=3k)Q9j^a(*S?{^QM#kv;+9=O8E0J61F0g&~ygJ z!p`jowiJZ3tS>yUXBw`IT5T#{2W;~VM9a*p^E1a2Hlo^PH<=&2H?7F+s=j@}Mi2UmNWV^pi`yi?OI?2) z==FXpM-Z|gL~C%FRZ7eL8O_qwMa8DewmWfW#>2MEF0Hf@k%XXWi!BL4cRitNpdnxm zxvsWFc+D+nXr-&47Q5%;h;)mzT79r4VeXlY!g!Svw=@L3NDfWXOYo-1emBH!x-|u! z&%8HjXtI_=r{@mg#6EhQ4prD7Oj|rMscge)(*KVaB6h+M?%z3hZ~6YH z)i9|>WxjO0wb=N5;J?`PQV~zA^5!25DDL^wTWF|c)qj9j%^n910taF)eP|TXlK|Rm zR2_b{vHYjH`b~d@&t+$34iD)*80&9Z@8a}nq;07JU@Y@6g*PW54{j8g?%8?YWVUh^ z8vdN65I9=X`%wgkyMj{CfkJa$kR*6#h%aA|vO!5@-J&8S2WFN44^v8|?0Hp> z9sUYsQIyt^#lxLk5+z;|ok&OWzlS^>J4CeF4<-J)QkBBLjJf-N^CzJ7N%ud;+2H(w z7eX$m+*?sX*$N^0MCk0N${USY^h>q)9t)}~+Jem6ei%7!u1&WRF-y7OKLcu3guO>v zpZSW05ktG(-7^;69;($ktfw2;!aN`Y<5S8;wW0SU1mR@_z!hkk?Cb5M5DQtH5H0UgFeW}^5(FoacCaDuWU zxh;GCVT+QHpSk@eU2o2)_TAoV8i8GW9rOmum;MG;)ecaap{M}Xo2en2Cr*KyosG-R zf7ME&t&>{?abC4sHb7$^Kk09FBZ7yAlzs?5jmNAw+HN@+nhu93!VJ^b}Ircp0EU5Z8_>@9doz-$g z?692YWsWT;pH=8qxnAz>ilI(>Xx*q@-4(l&{D>y9Wua@*hCuyi&PP#^NpG09)h%MJ zQ+fA*xh}%QHSbz*Jjk{u%#!gg)>xCxcEF8lE^e>G9zp zL$k})-5RH+lz?XLn%z*a(g$JhR9qMG8XSzOg5Du@aKU}(Db^CYwtyVTQ!ar56Al)M ziZryvkG651w^Yu3bG>KYRxIy)%b4xQ>A##l)xdQvpIibaCG*=X+5_RqZFH<{TQ+2VZ1rlBIu$EUnrJ9s82srY9m>ZUeEu0;~at*OPA;&*7> zZsjP!K@X+}t5_lnxV0Pv=F5TDY^h@(p%7>x(5}dU_ZD3*FMB|f7==Fj=CQ5lx}4td zPT44ZF~l!7smiy>_nKdg}YL zr}0^3H&+N`67tGt1&Ow&#IoU-&I@c|jyUq| zS8PvwhjMgt~>-;$9y1pL*2CC|*XIR6%*1DJE z)&Zy`iG%duv73B{B=(XzfjIrbYsGxDAnrJn5pC;893frDq_$Y-TblT~kOS6~F}sv7 z#RE=CO&sw3>0UD}KE&~9yakk6kxgDW^4f0k89Vo3DyiV17BI;Lw-Y>LeHnGIOqx*1 z&g4|2xok%kGHjll&MThPeBgpSK+Jg(=p44{sfl~C)0?OX@q}XyJDV+zla&c+PL!=C8DD3<%D{sbim%{x&KQItB=MDElybmJ^SL|L26OPeaIzzF|Vy1oLZzcg_xex zP76h|B*Dy?%y&#fX?$;n=tIcD_NEmIowjnxF>sKm+ z*!%VlEP}b5*-9)cmQA}k?SaCf_boF?SZROGHE>JBmZM8PDp3yulVKyY(cbb~@8oW} z8XV<|kc!Q|iDV&zqtJc;ok5MFY-a3}Ruprl=qH4o$sXA9z<7arLRy=^fpnJ+zHNdP z+k-J(UhK||XH^o7H0eRXd}fnCy5}%V*j?gN?gXn$5Gu&BVL|v!XeuqEsa|TtaUHhQ ztT2suAN{TF$hTO){aGr9j#P3U3v0iH=GjD$Nm2t*Q_)FjQiVX9G7~?8&ybWEFS<3M zDCHGjI~8kt+=^w&^lM!*{500pB;v!D6GNqE7@SrFI7{9rOwkfkYvfC+YeWeLs1@$Z zD(^q`O0>P|>uGg%EmHR|f5>g9Bm8Jb_(syl{5Q~cye9x1srylDAVuiM$|gn7Gyy$1 zSUOI8lu;7A(s*kG-I>`ti>)Uc>}7YP-7C{u6DhXN1XocF>L@^6iai>+^ zNnF*AKbFmjsJUML)^=ikj)uBM($%%=w8neR$5x1G@6CWI&4jC*zn++0-(et$g4RHE z!+v8#8Wson7FG?2x9B2+p z!PEF04U*3ozU0@nM22uFi-&O`Yb8&yknt;QxlIf^Om&+=QhL0Vk*-sg_MtqR#H~-V zj{G6N03Cr9&`>bEE1y9LLW<8?5 znh`}W(<}Cie{Y`jPd|UWQ+|9U^Z2-Gu$v3cmi93dO?cKJhs?Omga)D*hJ61&BH-S?<77BD><*7 zpJH0_(BTL76~6^Gr`~Co`iJ)?AE$k(lT>p#k11|pS*u#rZ{6ITq&}MX8{`j>S18!r z041wIfFDIQ!4EuM58l#Z1P30@lS*(yABBLa@a_hWA|WcvFMx8PuGdn5&J3lC%TGlUfrd|3}En;71zNahA+D>|Dw2hXY) z&I_ZE`VaOW=54%@d-pk9Vg3!?<8~2E( z+x8TIf4e3zL^;O;LX_fF2^akHc7vmB!l0`-oq4U%i+WUATaYH^06{?-iD6av1Xz@d z;~yB7Zep6{4OiGifW-kue5#FjvD~bwxt|#&GDeey zE8H7iugV*6EIs%ju=!ch&44$ba;D~t8xYI#-YC+bxre0?Q_b3p5>vp$nr92lQ}E^^ zYx)31nZs88!UWr=EDW~xDhr-4MQCZw_k!8&v)Pc92*H_({eOKJEd-T{jv&3yZN7)Sa#{F=Riu$a0Q^i5 zs9J6R&l_uvX0ec7Smv6yw%^SDIzp24H38SumZgF*yA757g8Ti~1@(l4M4b}YT0ddZ zJ%6gTWuqscPakZOp_@Pc|9iy4p2eoMh1*Zlv$y1*dvuuRr0%$ne_uV_`~8O-xr3zL zj^!xOCO%Lf43lyXNas=((dTF$Jb2btJgs%Gz-Fi6$qfOqD0kH;vHGq&JGN|Pww<5x z#=da8@R!Y21A7+)4A&Du*feIsof8-CMb6v&Wx}|!z*T9<{X^kmaA^O|U$0#I&M5rf zObTiKyVGet1YqQ6nL$M}ZK{>!muBJARvs>qUvKOH9LS0`uqwMc?qlQVET18#zCIgO zwlAkiU+J!jH=*(r#0)c;t-PYJqUr{7t|>N?JO>GO_~XH9>w$)euK|ZIIFODAQ71Lk z5!_okP>M{a826H9FiB3!9z61=Q}gOZ6z+=KtxmgQDzEp3o7eUNbhn(-WdM1$RUCXJ zXewP1^?Rz~Oj

J-mW&aNGN`X;0#4{LdQEB)nZ`zcACaW$q71CkNI)|g%7{BoA* zok^-=pJ|`atBj+HgJ_8sa1fx8$Xoz%Bw<>z6d@Xtk#6wrz(*f4e?`FRuN89h>eY|6 zV@z4|O%=NzZ_NnO$%9Ks_$p4-Ruq`?P{lgp>z`_qEGaYh$Zmad2DQ;|d-VF@U}<^s z@moTZaFZ$bI*2P83#Y_X6<6?$QVH2~r;a{<7N_)jVI0~=3Q+$Bi$#{8ODX~m8 zi?Zy-(^p*`QRI6|v%-%a8~^Mv#yk{Qhpe|u1bq-9knW?l(!ow}wZZis;ivi~!d)rt zTY{Wg?SoEyUL4_&>~D*@q2n9%jt-O*ra&C!iIuw^9fV3udO{-wtTfd?;`mb!m{VC5#~8kijp1MG-k3FBO2 z@iOJ&T=365(gZizT9mCWup>;$`!ardsnJyf_}ps3vpTa#gJP?hm#4 zE`}2fkOtS0xy5FT1D`RkFy>O6^^44;kF-#^Jr#gIo@1PgD*BVQR>Blx?-;}Vz`}}i zde{9&!@+ju;(o#cWdC)^D0@2*+L2@PoJW0=QC^fO%=Ld@|&hbFF4MmUj$ zbQvmtQ_DDtrr;*+Unz^~ECeTWpYWIEX4_0hfLQ;BgMD$ws+21sQe35)4|H-+k`H^| zGA#|iBpr~~ekOYyf2BNvKNWJdd)MmOI9+1hcv7F5)OkMHrKIs(?r}Lbk^1Q?lq_{2 ze|@39eW0idSHmp{y*zOvRQOG6h2y255w;voq4o=ZmXkD^o#tQmv;MLdK0j=2y!zlA z!8O~HeDPOA(GfoW1A0Rs-EVV0DzB0|eHReJN`v>JG%=5cAEHV3v!E1b4y?>}?H54d|pHOeWU+x=6qxf^oLF-M24~rgZ6?qFasU0lwo3k&z zI(e~wu*gX7xNPSE7rkym)*+JdQ-YBJn%`&0LxKm$Rd2E0tF5Sz=KU|Oq`!PHD#i@R zW{T~2vc+cV)nw~BhH>pG>@3kx%XYF+8yu3KDau-Vk3h%!Fuya7VgImdTDYqq&rvnU zfUYzbqvOWK-8u1&*WBMwE#%6+g3AIK=N2m5kCyC0pnh{Zyu~JLJjnL%3;2ApfdZ9 zW5m5ePi%I*F|i^~E$@D}dQrhJnHyK=-zu;ku~uW~foyD*_k*P{`79iQATUtBb5#B9 zv*uLBN$3D{P=w5BCwd%|1YvzEWM(b9slMrjjKvf*~Q{>;$P{7Y0YOy0cSn6ly;zcAwO_xgwF zrc}%3@zXpW3ivp)_OxGZiFvEj_+!$BA5%{Rglw@%hQ3Tue>gp-b>3z}1zsX_)*GWNsE4R^sMPPz{i$ z^H?C%QZDKS?`>4g6Zh_*idirHqs#WnY)b5`qBe-SmuGP5E9Td$;x*hC_Y76!uUk;x zGgM{vG{{1>-C0(3Q>o{dp|q*3FMr#H#am>z&~?hGZ)!IVx0!0(_^Q1AAYVdT_4f&6 z{r&h&`iHIXkK3bwp)0Kt&lIK^^b%YAtL$Yrvfdil)LYqpCf^}3>{x+*-MY!x(!kMw z-g3=e(i%~fc#nv_kk^aNW9qj0JKDy$>*atoHb`5X}rMn0Qdz$}c z+hFy*7uobe#ZIB|P4h=E#^2#tX2mn$>p_YJuo;LrmOErkw_>qdO1l{55RW!4L;@@T zB8krg$ETy`xq3hU!Hc8)^0lY0xQA^m?2X;IYWG4T)86+x&ooPq!ka#XyQVSx;Hv|J zkwj>~XH)k?cl<1^yzjdzd(R26vgGkN1_vBM&lV$Z(5^e|A@QGT$1o7veodQi#=r0| zPEGv~_tR!|d+j`vWt5=~t4V2KAx`@KkM;l@&5*&TfQZDCW)<$2npM1|U5D@W6(nh_ z^RfO3-^9DWr4HI0W;&M`m8%o3KE&@qJk=aPa?L=t!HasJy*Z5aAZ}NW!E1qXOM$Th z2L1W;cS_+KE)p15+Gsc|;?;Z{bo11!1&tP?t(-{GO!vZU+au>l@5WBqF$5UQNRB^I zG~h?fBPr+m5fP4Mh;oSp9Y0HZ1$CmG5+&q{Qod+xW`Rf7&6S# z<3=eLBzS>+E1}0g6 zsd!(hb$Mu;yFy{u|Asoi$9`Q7eQ*W;Fm}>Ejaqf$zcbk|eDcuW zXB`yPU*{V;0_n^D9~-%B7)*aPtUc3sm9+b*@a(}3$1>XM{`l8UAG1pQ3Y2f+YS8g; zMROY|Q}8a3+u|cXjQc4z_3MWZ==zh&c+AkTYQ5VDmM3RGyDzsb>$9E)+3fsVh|3?X zLRgqOc8YT=F{BcSE?$%;t-6&RN8*i|7x8x(`-Ik`@mjLmcZm~-biaxwcTlCFr~gzl zAR0(>5U&WjwyQsDpI-=7+H-Ss3n#OsOi|!)C}_KavVxrEYo{!MHjpRL=j;kgbp{#8 z-0NMXNJWi-3$>J2bVvR+Cta@js_Ei0Qyq_}r1go=l!n`i2|0seh#TYr={wqDQ>oE` zhVYn=mU!vEv=p!u$sWqWfCF@vSexi~Np?q>SIK#mZ)t;LPpf+vl;*GTYAMW%z8jkz$Gd53uSxcA%6OUpCxo_qviH95XYd< zu(gow5!OemR)=I2`DR)x&?>H%4hUzbd&oJn`^KTH1PoUO zyBe$wdUU>Wx4tfn%_jv^_cL?)PhNVBABy`R+*GDWL>k7UmzMS9c$T>T@}kslO!e63 zFl92Fen-VR`-1mULD>DIg~mH`XKw|%^2N9=F|+020LjprrS9KTQePpo>nvdHP5yXC z032#Vg?OhgP|d|HYjIZRVIJSGa>CDQ(3a{$^eDrc`^_&9gpef{Q_GP2Q(m|!+0;asoT z^C@HY(+9QhPBq{m+S@MmZ2RK4S2x>ySb52s$4@l?meL~CeL&=n$;?#W5x&lFL^y_J zA*z|l0A*tH1@-bCFkC(N#>6O)z(lAMIJiD_U?UI)Ww z34y$!4DFoKn19T+BYJqLI!qcHB^vE&{ODy9@+j+HKqkNzNB~navSEU zZbMt2UJ^d#4*KtpqU4lfBbqb_WLgqCkSxXy$Z8oxh?ySXN+<*^Y~m(Y2Ngun2|MU8 z^p{7?8>1=La0YLJ*CGKV>78i`vA|Kj4J5eVL$qCI|7gZMxEmZzd@VY(Sd}C)Q>h;Z z?cq!T1R#V@d;p+rwSOF;bVi4ElK%2I&Rb9>|27RIX({$vPo-Nl`Fkc7EB!o2H5vAI zNd!2ZT7v>@q<4!J?9G=pKS zh}=~b2kj#m>qEq@6q#WYp(j0iTQTNp(o7m`@=Sibf+W@f(0O@s(LuSDDzVV!d&L4V zQ}r9!a!o-*nLgw4m`$pL?^>;>DM$s!zgyUO2Q~$5djIu*l`L?*Q#9*wJ-JhTMdvt@ z|3;PUHMS3@ZcPtnvXoQ1M+LN%BxY z{k{zowh@Jv9m~H>OL{(YXY|INaA+{{?snM_bHKoGJlfQk)5`=l$m7-|d`XD-sA4Zs ziRm+zDtwhR$|5{X=CePm@fEYmqOs~$;ilC|i~Sd6=f%A*wJ+*Ov=c>+2dYbE(Bs_N ztCYGv#0)oCy}SZnudst+phCy?7gp%i4SCx5<+75}e&;BMeGhby9G7YzLswTu{*${HrEmZyjKNPA`ti@&u zT6tZ+kI}(x0pG+He6KoD-B0pRu{*lb?%>DB(Ms|sAKFHS6+GVoF5FM7$7|#$eo_(W z&wZCJO_I}#>LuA2zKhbfEIq^iiK&-|9Lu(y3!=rYD{c&}QoON|aQd6TeuGUNe3%LA ztcM=2v5cCJ&bJ(SU`xzL${)B@OgMY#?y-qG{vv?sbWG!{uw~;HzbV5e@TScJPyZ_^ z-M=i)|7n5#KmAUNgFSTEGA!95qJ3AK!jz$3;7unn(8d%gCC18a-BGVGJNL#>tuYI$ zk^5uAVGGTn`T~5eQ*YG8fnds+;P(|SGuagzEqLNllR=a z(75=Dn(7elEajGxrVYe$cCH8)8U$ZXo+L- zCbVQZ@!dn5@(MnBVLCw#@lE6W-kaDqFn)a}oYFLqM?>|y6Nn?#kY9ogu)h++X)?jT zGVZ3t;O6j34)`(#k~XEbcoEKAK`V1L*)cARi#?kvS^6aP<)ujWI*R{!t!8iY0*k$M zTep>-Ow>rYxOu~f@74-0$M3yDr+{V-eyuzYUmY12ftCm)*wlj#4@hMbTR&XhyeyB& z_mG=CAkt0Qgp=35oFvvbcx16v49RJJmAml*SgH!9AU3m6g)dnI;CU#7}3lmPzr1sc^1y4&g z44S8MB^@`FD6e6jbj9l8EfC#&!fD#9ri8JE^r0mX^ytm=M8-Zg|EabBl)zJXQWD7c zHt?4OHZRXWa0Q0mZ$h|91_j5bsTYVI%3F&}*fi}=59`@bjQf4vhjSS2Ls zQ50WBE$0~Y3T78hmPPDn$l=bRIeR5uy5o)9zvSmH+Gs*;n|;!6pZTah1}=Vk27734 z@eH)(0uK8*)!%dS=;QwxoG&!#;8qE4kg}+yMbr-4Ds+yMzgwBpskWj zITlQ%RUJRNZhtpGvjq79CQSPiT9zfy6=pwqUpw#t9|wEVW$UItOea%FdExWp0LS+1PWG z>l}vo=_yDBc@Jl&$umF{gfRJR>3OWmoc#p~;Cdbl{5^!G)IZg99qtSMQ0(~~#U~mw zK)&y%|EWfP)iKNvOn8|kbP=P_x}XM>`rG z7DSB2RR4OOS#5a0r;9bp9%>F^zWLs8D>GqmTrrDbSWlTke54q&e)@byI=sQJ&Gi^* zG(pct`~Fh&4-fa_CTdz7&&lK0;5k>I8i%cew*RKzTnSWVwTEl%MGtI`P-pj!-Hwud z^^Cu^n$oBtHfo4YsR4Lm7au!hjgIej41x5m0c0YuK5gVJW_9VmeDr+s$lGx9C>aoc zSxW^aiC8&x!Ljt{m`5$#=YnI%*Kl6rtk_KxOX7YscJWf|VREmqD;1oU*Hx7hh63$X zj}$uy0|y+*7O~tf(gSJhKUT%}nf;{5<^G&0!gyQSZLSiFZAwuCyvDYky!S1+co9*Z zUl?VHWGx;h*KiiyCU!6#x_7&E(!n>g#zK%hvog8{(d0T0mZkJ`@`nAgEl2Q@=X*H* z_T)aZ9I0!{4}emTm7F$b)nkFmLsmwsql+P`J~a=n=00$;rK||rtl~}hOe&rt^>KYIvk9?A*R-5=I@7oHRjHo; z*QzDwFD%)tv*iWn5J%V}_fzF#XSpQidqJk&Afi}-r|ra#LN9ZBQA8W9T<$cRZ8-n3 z)2>HBiUQ~9>7v)v4I62yWBaRD6(9k|W3dGfpu!xSgsGcx7iqoxo7AsD5`G!%>j>0i zz*38c2RhdKKAg^CsWZahS2$xGS|HH0A#YtQzcT@L zpj#1h4-Qq`;1x^_0~}&0^CJ-FQNv04R$N_w8cbh$p~-XqwS}A9yo&kGY0s5o1>uOz zhxjck(8h7*VF>>{gZO16?kA7OCv|B0RTLXYIgumY3W?gMc)sbaE#;O^xT{rRe%x;w zU-03zW2c*P6x$eDQjEp0kY<&;TGXWjjkc;1hJPoNXsGt-I6WRId~2j_zPbWuK}X}ymV>r}7G z3~)W77;w82Yc?`W*eD3qFxVM7?eg@*59r;-~+3dlg zudS;1t?|Uk?96JPtTAk0`DBImW9&Lf7X;oe5O}ZAIY|2h%J)pWB3!HEaEy>W0}Dkn zvjvkg!rU$_d*C7eV)0r0t&6qpmefNIiKgN8 z<;V=m0{iwox`#fKe|dy&YcAJ6m6qPt`V+XkygCrK#(h17nd6uF9(RqaDO_M7Aezi$ zq>^x@r6}~9yOjU*?DO>B(&|x76H-W#8(r8`_dhIktX0vu4$W zfFwrslA+G3?LU&RyCUG>qEHy~RmtS}0&Rlq&-qz;IXKRC64tc3?!DmCJ!M$&0g6ww zZaTV1kV6%Jh7E6vJ17o#V$!|loXEF@#*3vMH#=p(yX+xECRK^HsJ!;-klm>2~xU%FWpUDRw9>LjVd29K7iBHyk z<$W#pv$fJ)6l=4+-fgkyZ8)J>YzZzRY`;_g{7&qPiM47_=V5Vh5DrB17_3t1sC z1M$g=3hN?x$MytWn0vtXS;ULQ0gI#8c2(&HTo_!@?bw27W9R6&xrdmlpfl#G5}-sF zo&S^cz_5r`QiII(zg6Z~E6gXV8YzuIMqg!B7Z$!5Mn1=GOo^qL17z8!c&|phTh0+W z%OhZqyaG~Ra-d?rk`8q7Ex_B_ds{iDks4w})57WRP-)yxoYVTgvCeJ9PyMp~A_=}saBa{^<@0ky2Q7+NTP?j$ zcCm;gdE`Z#UL$yCl~`6l^2t)$53Y`P-%?i>=c-b$(~z$LJe+yZ2u>gp@C-z@H!15` zvs=6z+KW5}Z}+{;DdMMG(kv)~_EU;X!~LIzc6K|MC7J#_i(U9ot3NlK*p9X*(DGQy zx%G~!9EK(|5UPC9p%o6rHpPp2V~?FqJzueOWnm9d#5u zgG+|!P`#Lrua<~y6n?~~&9-F*oR*t~+aLO?AH<3wQqfUP=+r)v%};;UTKc={feycO zdWyYYje@(5a!_?5s9Ftq^xhl~1$x){_3}KapHlaS)+&J(Vcv`BGW|! zx++hMk2`Li`37ii>fG}bh&-e^G==ps{6}1e9O_f6w1DM=UzY5`PI7MvNbYzaT|^5@ z)|b+6m^3LDc395$UxrS{@qDHR+liUO>SZV!^GfZ#o@!_M<*2`$S^L zUm8aZJk2O4pX?XS+%uFaF&XMmbo9Kpb#j8Tm0@DW#|~OctNfQ*Q6lXoX&!U2a#xYm zEc9ek;pUjC=e9(IJW%l3wKYr!S=|Fg)I){U+V9?}+SE|521nV047B7INH(SYZiwaD zl#qA^mAS}*!tK)S4pP(pV8b~^#3C8^S=O! z)Jq^ygv;|jriw@0C3E~0LREf|>{Eu+pI(x?;6p;PX_M*vc|Rrmgn6mP96*bX5|9i%-^Id4mQir41w z?Ls&vuB7mTLXOUKU=5n}U{CtH0RU*8cUDsGlQwB7yC6XwYfq=?W9ZG?l_*(Btix9=@_P zP;62$c5`v?r;T?CZwmlSqIfJ!_^pC?jda+msV>X3A`2G_Ng8~AMTLG;@q@=loQlLv zk1niy`s(oK)O*9^8#lCXbYi<56PO>6Y)+|V>&*7}7{yP@X$@E|*)n4*@2Km7WGyS+ zvFfvC)r)j2C5wMuXRf?QEJ91bjX7&MpZMbnq^FLRyOP=aak@~^V!Qyb-~b=GmNJl6 zjZ9QqECFHxw>Smx;MjKksdkbk^)wSNAiF6{l{-|4qepAna8mjH{@g!$Ze%r^AWH&+ z9`n2qF?5v!)2U>|f@L=q+jY508qEmpJK&h|ot-W?q(!+*Mm&}FcL>$XIdgLF!LIe} zozUZ*F?&x}ec*cv`sz9JdO$hatEzUY9$kQNZgUknap>;EQ`7p&i|Rwq6SL~$`Q{bbSdnk$DHuL-wL z6SuseW>he4s`Z|RUwMG3=0MXMd@qUEVyoP`S3rc?RA5Ro@Cb}Jjj!^aE~Njw>7=q` zbXGla9UHPE-NB@zThNI`g84AY-w@?x;9L9mo6ypZ(tlpZzjLu>{CfYwRFyi~c^g@Q z{&h&CzuW~o{F;9UM%k4xtlqGmIx!oe!AAm;Ob_wDxASaxeYKLueQD2D%0`4o`3 z7p)NZpN4}`djmFnNA};RO662@WqU|h zX}ag%Zz@I2A71VIUF^x*@>*45sE^Z{|JfZPB;O zxi0!Bx+Z8lfZ-1%%2@R-%fHNj%3p8Q+~4F}7n%3e@HO%4|6ay_+wuRri~yD6E20u2 z84l0CVH<})CNr@q|UJ4u{UTl3cO0@0Tnsz1Al=)sA#8F$lgjFzLAhwHB+>zP_lZ~XUrA~fVnWVnUyk!w7 zB}Py0-i)-LT2!b#Yss#d$R!u*3QqqAL)qV2=Y20j{!4>B=%&X3qv*7xrS(TuI_kli zM|@1)*f{E-ib~|NMNx8>agm=k8O4w=? zO+2+Dq+G*EQ@vE*rJM8I?)oZ=!HxjaminI3ed_OwE#Y+me=J_B3VWownZdBiEjA3X z&#KcsniJf#)jz@}ddC|Z^c2#kW0&lnv1F*)V_a?Ht0X8+;tY;pa|&0;HY+MzS2yI) zrYqN=H{`EfTwDHF`q|XJWBp!Am7=C7!D6^`=Md+c3N<5Ef^zUc&uLBi9=e)RyoT>p ztXoU=Q|$K77(%pM@Q|Qq;LvG}%c{JVDw9vSe>j&gjq#`2OOLqsW3(hD1c>vfyAy$66qJ-;QaeO@;P+l9dS%*zWYK3ytam!HKR3_rk!_q?wMF6n zCpT7_xxIi(TaaaX8P{%F9HfvUlmF1r$>H|c3Yz{eW(O7nW z!`8MZp!LrBcSYLVHQkRO-!?wf3Y0l2btkuzB9xAb&3M+~Ch|{4&4blv&N5cr{_1q2 zAhN`pPOy{Qx*73aMA{#nc^T&Q7@hTHOFMW2wDwIZb}`xE#gV?u(;Fs=9>}BC{e*g; zURX_{hH3PXlIh>rg`tsa0g!oA2TM}O)+*ehaARnwqKQS^r~QbOjZ=3N%Sh0f!)4E} zxy{x!%fGD>W(Paa*NVSI{vKn>?oUY=D?Vy({sB8-iEq-9do?r6U-pq8pYkYh1r`pc|CfK5U`&DjTef^W<*gFJY%o%K!P8NkkP}U~!nn@c3)z0L(Lbt%lL*r9rS z8(C`DC00wn<^gWm#Q{Beo^ep|lO%EkHnL{O_N?AFvCjGh;a2-UGCsqsmN-#XKw(@C z=0Unfo6%AGNa|OvbxRx2$EK%&b7SqF^$k0dW6s<@W;-umCpBTk9s8?&G&?06=iq*5 z{lc_i?99hcN)@74HcoGMURbr(A@%f}ip#m4L-z83rMcRFTs9Hvu5)0ug*=4Ls`3Q5 zZYNPs)9#Qpzhgn@#WqT*mF~}}(01+XJKN#lED6!S67YFEG5Dvh3bXsGJU@?L3`jmi zB{-c!0~0^tS#XY*;?^>Uiq}f2w7HyZq_mbHq2x`_?qvSQcGZ3hi%SDrw(Q6*mpaV7 zu5wy#l-aoc2r8vQzJsONpitoi9C%eS^^RpJss1D??)=i_&HbiuI(Q^ctj}T`j7&ILJs? zF}0%b0C&N_y&LQxr1-wtghcM7N}|jKayT`mrNWvq?{#ch8AT_1LvGmm`%8Vy3uDQ# zb8M+T!)NF0F~-{1QhxT%Rt>L4^ZRKO?_;IThBcQpCK= zHRok}Nu9%{UK*hR7wN3{s{CS_(pHr2iCr~}m36#+<$ znmBw=Q=qyw)xCBwbyRs?_PU;1rUh6(8;YjC`v z2Nw=cLjnj+&qGb>msY5GhPL%T<73_ms<*4Pj8j1~^psDwt>q}`FPA;@4Yc4G*X-Uo zpW9|9>v92G@;UfU#p%<45m^Jp{gr2#$1O{-`A2cg-evWX5JWB_&z%*q3g6dU5ubk6HayJ&&YnHyc zV8B|pHF{}e#XY$Zo?%|b{+_LiFKZ4*JfJ8jqmHt4Clbss3GztwcBHlNuD<;}zX)AD zCAoeOj<~T~r}|JNYVI?nuU4bV22mEvo`#&EMM5Jwi)a2-mB@_{s+lxb$x> zD!e%+D5@wd-El`HS-z7se(K;41+1$WpcP*Z%3JVjB2r6-99lKFrQzQ`)yc&BUuEn! z673F<20h#OxFCAP`k1*zb2>W52M|KTLg9mB@-|iSB`=EAk+Kx!LEJ}V0Pzz4rqY(5 zw;R7m-DK?URXx-d$$Aprr<^-UNXw=w=OoC_;0jq;1vockqysZnZh*X0R+mkbFI(Mv z#WSzB!`tlIE@_7!!}!C~g?Vp8wtk2s4$q4L^)Xq_f!?A4?Jsg7G~M1APh$zcv7SCH zzvvbAWXF(QB;mfRtH;=fIV>ja+v`0N3=!-#s>f*i4J^x}N)T;qiT8mMVuX(g^OUR5 z6@}hU@GVF8tl!g|sIzO}dE|jEV(gx+W)W9s%bSUMp$Cwa%6;(_io<=7h%6}!yA){Q zW-GPE$_6Z!f3;nfG@s?!XL@$H{G2PJ^7@C^P8lu5cb~dYRi&KcCSUzl6>H7<(l0q6 zBToQ`6PYUON`5`|`?Jg^13r~8{PA@Rai8wGGU+v^_?TY;){-G#0Y{h%t#@vOPcMAlpJ)UHo+JB)m(Z zhn5&pG`~B)3*aP1+n{rl0kZYZQhvNIRTEs(lWD4AOpCB{f2U=NLz zcl+6SRHd$gP)}Sf5=>VfZYbO%LPH4XDZ@j5FFYtT5V}2gPUla4wA55**%mkaD{9c( z_YofIk&2c~#!hTPPfF%7Ke%ozgoa)cvbV?*cNnGWop!7?3w1tbe5xk@8=14po^;=m zAH92=(@p1l=YHolnsNjrlaarNh{BRZloM<4>gURXbe7_gfA(6rJZwpXNVNEy0AQjk^1D zq{Y{~$(FC{til(FJN{7h#BXY$1$=kZuU|ym=n)X!jCkeh-y@=gJW^5{mNt!IvwC?v z=ib++FXrEN3D9wVZyLYCrqI>neph@4zE(8@lF7r^B&Bh9--Ov4?w zH!vK$^xn~RY{IjT?&)05eR2BYTl-ascVb(sy8}4-V0J1f>ea?270gn2@*UT$Ac(dT z)!2N>TE=<20?NxCoTBq4@2bzHYWLM2`$@jwMBRbu;?5lH)-bnZle2TLb;eWqv$vX8 zqV58GF>A0uu|a7^4L7!w(Ibm3XkLVIzBD6DE85z$;jC}a>^@_@gR@;nxTS^ZHU1K$ zG2l#z3Cmg$0y*(Blr!MrfO(N7Q&#$WS2)pGlqKGj+0tFV1FuHm%$Ea9G{kp6OnAmX zQfrl}+r1=VEJWpTKY=Ux<-cEnTK8WOO;O=l2sO=OY?7Yi$Yxgh#q{wgAtx_DAijpk zFbF)f&K~wvv(@hAZcAvxQ^Gfud4QQepWvhO&YEV)P_b?rYi@up`YKbZT+!)ym?nQ; zb0&mH+&y{?;Ie%UqonA!K-G;e3%PzWW_7W3KOYS@y_UO`ecftZf_{obee6{4_~8pO z?r;3N6CF?c^j$+ze@gM%_cZ6}OWRp%DhsqtBEBtQomOju-?3{+%UZdK`*@Y1&?JCAkCm$Sf2#{a<9w6-wWLDaudSk$*ZAq@|AJLm_* zpeZOxmCfm018S8{-Xtw+SAQqKVcTmd9bx*Skhz6RJw#rNh3#k82xt}btaUEqI(D

D6E^Rq;j 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�o^g#(vUbvS$H=IJ2^ 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 Z`21U&kAFGt^FNuP>@Vm2SJ-|Q{wIW?F_QoQ diff --git a/docs/cmbreps.md b/docs/cmbreps.md deleted file mode 100644 index fa5334eb..00000000 --- a/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/filterdup.md b/docs/filterdup.md deleted file mode 100644 index 4d28db6e..00000000 --- a/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/hmmratac.md b/docs/hmmratac.md deleted file mode 100644 index e6bc4d88..00000000 --- a/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/pileup.md b/docs/pileup.md deleted file mode 100644 index 65634390..00000000 --- a/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/pileup.png b/docs/pileup.png deleted file mode 100644 index bdabcc38aa3c3b1ce070a4e06d324abfaca3ad96..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 34709 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 diff --git a/docs/predictd.md b/docs/predictd.md deleted file mode 100644 index fc327c5f..00000000 --- a/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/qa.md b/docs/qa.md deleted file mode 100644 index b69f8568..00000000 --- a/docs/qa.md +++ /dev/null @@ -1 +0,0 @@ -# Common Q & A diff --git a/docs/randsample.md b/docs/randsample.md deleted file mode 100644 index 8344e221..00000000 --- a/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/refinepeak.md b/docs/refinepeak.md deleted file mode 100644 index fe0dc67c..00000000 --- a/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/conf.py b/docs/source/conf.py index 7893dc36..c6435ab1 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -16,8 +16,8 @@ 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 120000 index f137a3d8..00000000 --- a/docs/source/docs/Advanced_Step-by-step_Peak_Calling.md +++ /dev/null @@ -1 +0,0 @@ -../../../docs/Advanced_Step-by-step_Peak_Calling.md \ No newline at end of file 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 100644 index 00000000..899f808e --- /dev/null +++ b/docs/source/docs/Advanced_Step-by-step_Peak_Calling.md @@ -0,0 +1,291 @@ +# 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/INSTALL.md b/docs/source/docs/INSTALL.md deleted file mode 120000 index ea47b620..00000000 --- a/docs/source/docs/INSTALL.md +++ /dev/null @@ -1 +0,0 @@ -../../../docs/INSTALL.md \ No newline at end of file diff --git a/docs/source/docs/INSTALL.md b/docs/source/docs/INSTALL.md new file mode 100644 index 00000000..37407794 --- /dev/null +++ b/docs/source/docs/INSTALL.md @@ -0,0 +1,153 @@ +# 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/bdgbroadcall.md b/docs/source/docs/bdgbroadcall.md deleted file mode 120000 index c22e5402..00000000 --- a/docs/source/docs/bdgbroadcall.md +++ /dev/null @@ -1 +0,0 @@ -../../../docs/bdgbroadcall.md \ No newline at end of file diff --git a/docs/source/docs/bdgbroadcall.md b/docs/source/docs/bdgbroadcall.md new file mode 100644 index 00000000..805ba213 --- /dev/null +++ b/docs/source/docs/bdgbroadcall.md @@ -0,0 +1,79 @@ +# 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/bdgcmp.md b/docs/source/docs/bdgcmp.md deleted file mode 120000 index 62bf82af..00000000 --- a/docs/source/docs/bdgcmp.md +++ /dev/null @@ -1 +0,0 @@ -../../../docs/bdgcmp.md \ No newline at end of file diff --git a/docs/source/docs/bdgcmp.md b/docs/source/docs/bdgcmp.md new file mode 100644 index 00000000..099f9292 --- /dev/null +++ b/docs/source/docs/bdgcmp.md @@ -0,0 +1,92 @@ +# 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/bdgdiff.md b/docs/source/docs/bdgdiff.md deleted file mode 120000 index 365bae00..00000000 --- a/docs/source/docs/bdgdiff.md +++ /dev/null @@ -1 +0,0 @@ -../../../docs/bdgdiff.md \ No newline at end of file diff --git a/docs/source/docs/bdgdiff.md b/docs/source/docs/bdgdiff.md new file mode 100644 index 00000000..dd221077 --- /dev/null +++ b/docs/source/docs/bdgdiff.md @@ -0,0 +1,207 @@ +# 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/bdgopt.md b/docs/source/docs/bdgopt.md deleted file mode 120000 index 33d6517b..00000000 --- a/docs/source/docs/bdgopt.md +++ /dev/null @@ -1 +0,0 @@ -../../../docs/bdgopt.md \ No newline at end of file diff --git a/docs/source/docs/bdgopt.md b/docs/source/docs/bdgopt.md new file mode 100644 index 00000000..8bd7e0bf --- /dev/null +++ b/docs/source/docs/bdgopt.md @@ -0,0 +1,80 @@ +# 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/bdgpeakcall.md b/docs/source/docs/bdgpeakcall.md deleted file mode 120000 index e31f54d5..00000000 --- a/docs/source/docs/bdgpeakcall.md +++ /dev/null @@ -1 +0,0 @@ -../../../docs/bdgpeakcall.md \ No newline at end of file diff --git a/docs/source/docs/bdgpeakcall.md b/docs/source/docs/bdgpeakcall.md new file mode 100644 index 00000000..9ae78212 --- /dev/null +++ b/docs/source/docs/bdgpeakcall.md @@ -0,0 +1,122 @@ +# 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/callpeak.md b/docs/source/docs/callpeak.md deleted file mode 120000 index b33b82ad..00000000 --- a/docs/source/docs/callpeak.md +++ /dev/null @@ -1 +0,0 @@ -../../../docs/callpeak.md \ No newline at end of file diff --git a/docs/source/docs/callpeak.md b/docs/source/docs/callpeak.md new file mode 100644 index 00000000..5ff6fb6d --- /dev/null +++ b/docs/source/docs/callpeak.md @@ -0,0 +1,477 @@ +# 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/callvar.md b/docs/source/docs/callvar.md deleted file mode 120000 index 8876e49f..00000000 --- a/docs/source/docs/callvar.md +++ /dev/null @@ -1 +0,0 @@ -../../../docs/callvar.md \ No newline at end of file diff --git a/docs/source/docs/callvar.md b/docs/source/docs/callvar.md new file mode 100644 index 00000000..f27bc862 --- /dev/null +++ b/docs/source/docs/callvar.md @@ -0,0 +1,224 @@ +# 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_algorithm.jpeg b/docs/source/docs/callvar_algorithm.jpeg deleted file mode 120000 index 4c88b318..00000000 --- a/docs/source/docs/callvar_algorithm.jpeg +++ /dev/null @@ -1 +0,0 @@ -../../../docs/callvar_algorithm.jpeg \ No newline at end of file diff --git a/docs/source/docs/callvar_algorithm.jpeg b/docs/source/docs/callvar_algorithm.jpeg new file mode 100644 index 0000000000000000000000000000000000000000..f44a57cd2ed88c91df44dc4159786507e607c3a5 GIT binary patch literal 163926 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

D6E^Rq;j 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�o^g#(vUbvS$H=IJ2^ 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 Z`21U&kAFGt^FNuP>@Vm2SJ-|Q{wIW?F_QoQ literal 0 HcmV?d00001 diff --git a/docs/source/docs/cmbreps.md b/docs/source/docs/cmbreps.md deleted file mode 120000 index efafc47c..00000000 --- a/docs/source/docs/cmbreps.md +++ /dev/null @@ -1 +0,0 @@ -../../../docs/cmbreps.md \ No newline at end of file diff --git a/docs/source/docs/cmbreps.md b/docs/source/docs/cmbreps.md new file mode 100644 index 00000000..fa5334eb --- /dev/null +++ b/docs/source/docs/cmbreps.md @@ -0,0 +1,64 @@ +# 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/filterdup.md b/docs/source/docs/filterdup.md deleted file mode 120000 index 032b72a3..00000000 --- a/docs/source/docs/filterdup.md +++ /dev/null @@ -1 +0,0 @@ -../../../docs/filterdup.md \ No newline at end of file diff --git a/docs/source/docs/filterdup.md b/docs/source/docs/filterdup.md new file mode 100644 index 00000000..4d28db6e --- /dev/null +++ b/docs/source/docs/filterdup.md @@ -0,0 +1,97 @@ +# 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/hmmratac.md b/docs/source/docs/hmmratac.md deleted file mode 120000 index 21189edb..00000000 --- a/docs/source/docs/hmmratac.md +++ /dev/null @@ -1 +0,0 @@ -../../../docs/hmmratac.md \ No newline at end of file diff --git a/docs/source/docs/hmmratac.md b/docs/source/docs/hmmratac.md new file mode 100644 index 00000000..e6bc4d88 --- /dev/null +++ b/docs/source/docs/hmmratac.md @@ -0,0 +1,267 @@ +# 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/index.md b/docs/source/docs/index.md deleted file mode 100644 index ae514eff..00000000 --- a/docs/source/docs/index.md +++ /dev/null @@ -1,22 +0,0 @@ -# Subcommands - -This section provides detailed documentation for each subcommand in -MACS3. Use `macs3 --help` to see the list of subcommands. - -```{toctree} -:maxdepth: 2 - -callpeak.md -callvar.md -hmmratac.md -bdgbroadcall.md -bdgcmp.md -bdgdiff.md -bdgopt.md -bdgpeakcall.md -cmbreps.md -filterdup.md -pileup.md -predictd.md -randsample.md -refinepeak.md diff --git a/docs/source/docs/pileup.md b/docs/source/docs/pileup.md deleted file mode 120000 index af4bcf33..00000000 --- a/docs/source/docs/pileup.md +++ /dev/null @@ -1 +0,0 @@ -../../../docs/pileup.md \ No newline at end of file diff --git a/docs/source/docs/pileup.md b/docs/source/docs/pileup.md new file mode 100644 index 00000000..65634390 --- /dev/null +++ b/docs/source/docs/pileup.md @@ -0,0 +1,74 @@ +# 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.png b/docs/source/docs/pileup.png deleted file mode 120000 index 496476eb..00000000 --- a/docs/source/docs/pileup.png +++ /dev/null @@ -1 +0,0 @@ -../../../docs/pileup.png \ No newline at end of file diff --git a/docs/source/docs/pileup.png b/docs/source/docs/pileup.png new file mode 100644 index 0000000000000000000000000000000000000000..bdabcc38aa3c3b1ce070a4e06d324abfaca3ad96 GIT binary patch literal 34709 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 literal 0 HcmV?d00001 diff --git a/docs/source/docs/predictd.md b/docs/source/docs/predictd.md deleted file mode 120000 index 287ad163..00000000 --- a/docs/source/docs/predictd.md +++ /dev/null @@ -1 +0,0 @@ -../../../docs/predictd.md \ No newline at end of file diff --git a/docs/source/docs/predictd.md b/docs/source/docs/predictd.md new file mode 100644 index 00000000..fc327c5f --- /dev/null +++ b/docs/source/docs/predictd.md @@ -0,0 +1,89 @@ +# 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/qa.md b/docs/source/docs/qa.md deleted file mode 120000 index 87dcbab3..00000000 --- a/docs/source/docs/qa.md +++ /dev/null @@ -1 +0,0 @@ -../../../docs/qa.md \ No newline at end of file diff --git a/docs/source/docs/qa.md b/docs/source/docs/qa.md new file mode 100644 index 00000000..b69f8568 --- /dev/null +++ b/docs/source/docs/qa.md @@ -0,0 +1 @@ +# Common Q & A diff --git a/docs/source/docs/randsample.md b/docs/source/docs/randsample.md deleted file mode 120000 index 52a49313..00000000 --- a/docs/source/docs/randsample.md +++ /dev/null @@ -1 +0,0 @@ -../../../docs/randsample.md \ No newline at end of file diff --git a/docs/source/docs/randsample.md b/docs/source/docs/randsample.md new file mode 100644 index 00000000..8344e221 --- /dev/null +++ b/docs/source/docs/randsample.md @@ -0,0 +1,84 @@ +# 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/refinepeak.md b/docs/source/docs/refinepeak.md deleted file mode 120000 index a8fb6302..00000000 --- a/docs/source/docs/refinepeak.md +++ /dev/null @@ -1 +0,0 @@ -../../../docs/refinepeak.md \ No newline at end of file diff --git a/docs/source/docs/refinepeak.md b/docs/source/docs/refinepeak.md new file mode 100644 index 00000000..fe0dc67c --- /dev/null +++ b/docs/source/docs/refinepeak.md @@ -0,0 +1,66 @@ +# 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/tutorial.md b/docs/source/docs/tutorial.md deleted file mode 120000 index 4b6ed794..00000000 --- a/docs/source/docs/tutorial.md +++ /dev/null @@ -1 +0,0 @@ -../../../docs/tutorial.md \ No newline at end of file diff --git a/docs/source/docs/tutorial.md b/docs/source/docs/tutorial.md new file mode 100644 index 00000000..4f50eccc --- /dev/null +++ b/docs/source/docs/tutorial.md @@ -0,0 +1 @@ +# Tutorial diff --git a/docs/source/index.md b/docs/source/index.md index ba39bcdf..94398a0f 100644 --- a/docs/source/index.md +++ b/docs/source/index.md @@ -258,7 +258,8 @@ contributions over the years. :hidden: docs/INSTALL.md -docs/index.md +docs/subcommands_index.md +docs/fileformats_index.md docs/Advanced_Step-by-step_Peak_Calling.md docs/qa.md docs/tutorial.md diff --git a/docs/tutorial.md b/docs/tutorial.md deleted file mode 100644 index 4f50eccc..00000000 --- a/docs/tutorial.md +++ /dev/null @@ -1 +0,0 @@ -# Tutorial From 758d9091da8608df5f10875967e5336ae0fe3634 Mon Sep 17 00:00:00 2001 From: Tao Liu Date: Fri, 26 Apr 2024 16:05:13 -0400 Subject: [PATCH 14/18] add option --cutoff-analysis-max for hmmratac --- MACS3/Commands/hmmratac_cmd.py | 6 ++--- bin/macs3 | 9 +++++--- docs/source/docs/hmmratac.md | 42 +++++++++++++++++++++++----------- 3 files changed, 38 insertions(+), 19 deletions(-) diff --git a/MACS3/Commands/hmmratac_cmd.py b/MACS3/Commands/hmmratac_cmd.py index 4842553b..9de0cd98 100644 --- a/MACS3/Commands/hmmratac_cmd.py +++ b/MACS3/Commands/hmmratac_cmd.py @@ -1,4 +1,4 @@ -# Time-stamp: <2024-04-26 15:38:54 Tao Liu> +# Time-stamp: <2024-04-26 15:46:03 Tao Liu> """Description: Main HMMR command @@ -192,7 +192,7 @@ def run( args ): # Let MACS3 do the cutoff analysis to help decide the lower and upper cutoffs with open(cutoffanalysis_file, "w") as ofhd_cutoff: - ofhd_cutoff.write( fc_bdg.cutoff_analysis( min_length=minlen, max_gap=options.hmm_training_flanking, max_score = 100, steps=options.cutoff_analysis_steps ) ) + ofhd_cutoff.write( fc_bdg.cutoff_analysis( min_length=minlen, max_gap=options.hmm_training_flanking, max_score = options.cutoff_analysis_max, steps=options.cutoff_analysis_steps ) ) #raise Exception("Cutoff analysis only.") sys.exit(1) @@ -238,7 +238,7 @@ def run( args ): # Let MACS3 do the cutoff analysis to help decide the lower and upper cutoffs with open(cutoffanalysis_file, "w") as ofhd_cutoff: - ofhd_cutoff.write( fc_bdg.cutoff_analysis( min_length=minlen, max_gap=options.hmm_training_flanking, max_score = 100 ) ) + ofhd_cutoff.write( fc_bdg.cutoff_analysis( min_length=minlen, max_gap=options.hmm_training_flanking, max_score = options.cutoff_analysis_max ) ) # we will check if anything left after filtering if peaks.total > options.hmm_maxTrain: diff --git a/bin/macs3 b/bin/macs3 index 8951ff75..2de7df1b 100644 --- a/bin/macs3 +++ b/bin/macs3 @@ -1,5 +1,5 @@ #!/usr/bin/env python -# Time-stamp: <2024-04-10 01:08:20 Tao Liu> +# Time-stamp: <2024-04-26 15:55:13 Tao Liu> """Description: MACS v3 main executable. @@ -906,10 +906,13 @@ plus an extra option for the HMM model file like `macs3 hmmratac help = "Name for this experiment, which will be used as a prefix to generate output file names. DEFAULT: \"NA\"", default = "NA" ) group_output.add_argument( "--cutoff-analysis-only", dest = "cutoff_analysis_only", action = "store_true", - help = "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` on how to decide the three crucial parameters", + help = "Only run the cutoff analysis and output a report. After generating the report, the process will stop. By default, the cutoff analysis will be included in the whole process, but won't quit after the report is generated. 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` on how to decide the three crucial parameters. The resolution of cutoff analysis can be controlled by --cutoff-analysis-max and --cutoff-analysis-steps options.", default = False ) + group_output.add_argument( "--cutoff-analysis-max", dest="cutoff_analysis_max", type = int, + help = "The maximum cutoff score for performing cutoff analysis. Together with --cutoff-analysis-steps, the resolution in the final report can be controlled. Please check the description in --cutoff-analysis-steps for detail. DEFAULT: 100", + default = 100 ) group_output.add_argument( "--cutoff-analysis-steps", dest="cutoff_analysis_steps", type = int, - help = "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) 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", + help = "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 100, and controlled by --cutoff-analysis-max) 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", default = 100 ) group_output.add_argument( "--save-digested", dest = "save_digested", action = "store_true", help = "Save the digested ATAC signals of short-, mono-, di-, and tri- signals in three BedGraph files with the names NAME_short.bdg, NAME_mono.bdg, NAME_di.bdg, and NAME_tri.bdg. DEFAULT: False", diff --git a/docs/source/docs/hmmratac.md b/docs/source/docs/hmmratac.md index e6bc4d88..bb52b56e 100644 --- a/docs/source/docs/hmmratac.md +++ b/docs/source/docs/hmmratac.md @@ -22,18 +22,25 @@ Here's an example of how to run the `hmmratac` command: $ macs3 hmmratac -i yeast.bam -n yeast ``` -or with the BEDPE format +or with the BEDPE format of a much smaller size: ``` $ macs3 hmmratac -i yeast.bedpe.gz -f BEDPE -n yeast ``` -Note: you can convert BAMPE to BEDPE by using +You can convert BAMPE to BEDPE by using ``` $ macs3 filterdup --keep-dup all -f BAMPE -i yeast.bam -o yeast.bedpe ``` +Please note that in order to save memory usage and fasten the process, +`hmmratac` will save intermediate temporary file to the disk. The file +size can range from megabytes to gigabytes, depending on how many +candidate regions `hmmratac` needs to decode. The temporary file will +be removed after the job is done. So please make sure there is enough +space in the 'tmp' directory of your system. + Please use `macs3 hmmratac --help` to see all the options. Here we list the essential ones. @@ -98,28 +105,37 @@ output file names. DEFAULT: "NA" 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. +Only run the cutoff analysis and output a report. After generating the +report, the whole process will stop. By default, the cutoff analysis +will be included in the whole process, but won't quit after the report +is generated. 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. The resolution of cutoff analysis can be +controlled by `--cutoff-analysis-max` and `--cutoff-analysis-steps` +options. + +### `--cutoff-analysis-max` +The maximum cutoff score for performing cutoff analysis. Together with +`--cutoff-analysis-steps`, the resolution in the final report can be +controlled. Please check the description in `--cutoff-analysis-steps` +for detail. The default value is 100. ### `--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 +function will first find the smallest (at least 0) and the largest (at +most 100, and controlled by --cutoff-analysis-max) 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 +won't be included. The default is 100. ### `--hmm-type` From 3f3d5d3c8064886a555e81f0161554d3bb9d4420 Mon Sep 17 00:00:00 2001 From: Tao Liu Date: Sat, 27 Apr 2024 11:35:50 -0400 Subject: [PATCH 15/18] update changelog --- ChangeLog | 18 +++-- docs/source/index.md | 156 +++++++++---------------------------------- 2 files changed, 47 insertions(+), 127 deletions(-) diff --git a/ChangeLog b/ChangeLog index fb0b1f0f..1e2dea0c 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,4 +1,4 @@ -2024-03-30 Tao Liu +2024-04-27 Tao Liu MACS 3.0.2 (pending) * Features added @@ -11,8 +11,15 @@ file from previous version, if there is no hmm-type information in the model file, the hmm-type will be assigned as gaussian. #635 - 2) Add `--cutoff-analysis-steps` for `hmmratac` so that we can - have finer resolution of the cutoff analysis report. #636 + 2) Add `--cutoff-analysis-steps` and `--cutoff-analysis-max` for + `callpeak`, `bdgpeakcall`, and `hmmratac` so that we can + have finer resolution of the cutoff analysis report. #636 #642 + + 3) Reduce memory usage of `hmmratac` during decoding step, by + writing decoding results to a temporary file on disk (file + location depends on the environmental TEMP setting), then loading + it back while identifying state pathes. This change will decrease + the memory usage dramatically. #628 #640 * Bugs fixed @@ -22,7 +29,10 @@ 1) Update instruction to install macs3 through conda/bioconda - 2) + 2) Reorganize MACS3 docs and publish through + https://macs3-project.github.io/MACS + + 3) Description on various file formats used in MACS3. 2024-02-19 Tao Liu MACS 3.0.1 diff --git a/docs/source/index.md b/docs/source/index.md index 94398a0f..0b0c1125 100644 --- a/docs/source/index.md +++ b/docs/source/index.md @@ -29,130 +29,40 @@ applied to any "DNA enrichment assays" if the question to be asked is simply: *where we can find significant reads coverage than the random background*. -## Changes for MACS (3.0.1) - -*Bugs fixed* - -1) Fixed a bug that the `hmmatac` can't correctly save the digested - signal - files. [#605](https://github.com/macs3-project/MACS/issues/605) - [#611](https://github.com/macs3-project/MACS/pull/611) - -2) Applied a patch to remove cython requirement from the installed - system. (it's needed for building the - package). [#606](https://github.com/macs3-project/MACS/issues/606) - [#612](https://github.com/macs3-project/MACS/pull/612) - -3) Relax the testing script while comparing the peaks called from - current codes and the standard peaks. To implement this, we added - 'intersection' function to 'Regions' class to find the - intersecting regions of two Regions object (similar to PeakIO but - only recording chromosome, start and end positions). And we - updated the unit test 'test_Region.py' then implemented a script - 'jaccard.py' to compute the Jaccard Index of two peak files. If - the JI > 0.99 we would think the peaks called and the standard - peaks are similar. This is to avoid the problem caused by - different Numpy/SciPy/sci-kit learn libraries, when certain peak - coordinates may have 10bps - difference. [#615](https://github.com/macs3-project/MACS/issues/615) - [#619](https://github.com/macs3-project/MACS/pull/619) - -4) Due to [the changes in scikit-learn - 1.3.0](https://scikit-learn.org/1.3/whats_new/v1.3.html), the way - hmmlearn 0.3 uses Kmeans will end up with inconsistent results - between sklearn <1.3 and sklearn >=1.3. Therefore, we patched the - class hmm.GaussianHMM and adjusted the standard output from - `hmmratac` subcommand. The change is based on [hmmlearn - PR#545](https://github.com/hmmlearn/hmmlearn/pull/545). The idea - is to do the random seeding of KMeans 10 times. Now the `hmmratac` - results should be more consistent (at least - JI>0.99). [#615](https://github.com/macs3-project/MACS/issues/615) - [#620](https://github.com/macs3-project/MACS/pull/620) - -*Other* +## Changes for MACS (3.0.2) + +### Features added + +1) Introduce a new emission model for the `hmmratac` function. Now + users can choose the simpler Poisson emission `--hmm-type poisson` + instead of the default Gaussian emission. As a consequence, the + saved HMM model file in json will include the hmm-type information + as well. Note that in order to be compatible with the HMM model + file from previous version, if there is no hmm-type information in + the model file, the hmm-type will be assigned as gaussian. #635 + +2) Add `--cutoff-analysis-steps` and `--cutoff-analysis-max` for + `callpeak`, `bdgpeakcall`, and `hmmratac` so that we can + have finer resolution of the cutoff analysis report. #636 #642 + +3) Reduce memory usage of `hmmratac` during decoding step, by + writing decoding results to a temporary file on disk (file + location depends on the environmental TEMP setting), then loading + it back while identifying state pathes. This change will decrease + the memory usage dramatically. #628 #640 + +### Bugs fixed -1) We added some dependencies to MACS3. `hmmratc` subcommand needs - `hmmlearn` library, `hmmlearn` needs `scikit-learn` and - `scikit-learn` needs `scipy`. Since major releases have happened - for both`scipy` and `scikit-learn`, we have to set specific - version requirements for them in order to make sure the output - results from `hmmratac` are consistent. - -2) We updated our documentation website using - Sphinx. https://macs3-project.github.io/MACS/ - -## Changes for MACS (3.0.0) - -1) Call variants in peak regions directly from BAM files. The - function was originally developed under code name SAPPER. Now - SAPPER has been merged into MACS as the `callvar` command. It can - be used to call SNVs and small INDELs directly from alignment - files for ChIP-seq or ATAC-seq. We call `fermi-lite` to assemble - the DNA sequence at the enriched genomic regions (binding sites or - accessible DNA) and to refine the alignment when necessary. We - added `simde` as a submodule in order to support fermi-lite - library under non-x64 architectures. - -2) HMMRATAC module is added as subcommand `hmmratac`. HMMRATAC is a - dedicated software to analyze 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 again - using Hidden Markov Model to consider three hidden states: open - region, nucleosomal region, and background region. The orginal - paper was published in 2019 written in JAVA, by Evan Tarbell. We - implemented it in Python/Cython and optimize the whole process - using existing MACS functions and hmmlearn. Now it can run much - faster than the original JAVA version. Note: evaluation of the - peak calling results is still underway. - -3) Speed/memory optimization. Use the cykhash to replace python - dictionary. Use buffer (10MB) to read and parse input file (not - available for BAM file parser). And many optimization tweaks. We - added memory monitoring to the runtime messages. - -4) R wrappers for MACS -- MACSr for bioconductor. - -5) Code cleanup. Reorganize source codes. - -6) Unit testing. - -7) Switch to Github Action for CI, support multi-arch testing - including x64, armv7, aarch64, s390x and ppc64le. We also test on - Mac OS 12. - -8) MACS tag-shifting model has been refined. Now it will use a naive - peak calling approach to find ALL possible paired peaks at + and - - strand, then use all of them to calculate the - cross-correlation. (a related bug has been fix - [#442](https://github.com/macs3-project/MACS/issues/442)) - -9) BAI index and random access to BAM file now is - supported. [#449](https://github.com/macs3-project/MACS/issues/449). - -10) Support of Python > 3.10 [#498](https://github.com/macs3-project/MACS/issues/498) - -11) The effective genome size parameters have been updated - according to deeptools. [#508](https://github.com/macs3-project/MACS/issues/508) - -12) Multiple updates regarding dependencies, anaconda built, CI/CD - process. - -13) Cython 3 is supported. - -14) Documentations for each subcommand can be found under /docs - -*Other* - -1) Missing header line while no peaks can be called -[#501](https://github.com/macs3-project/MACS/issues/501) -[#502](https://github.com/macs3-project/MACS/issues/502) - -2) Note: different numpy, scipy, sklearn may give slightly - different results for hmmratac results. The current standard - results for automated testing in `/test` directory are from Numpy - 1.25.1, Scipy 1.11.1, and sklearn 1.3.0. +1) Use `-O3` instead of `-Ofast` for compatibility. #637 + +*Documentation* + +1) Update instruction to install macs3 through conda/bioconda + +2) Reorganize MACS3 docs and publish through + https://macs3-project.github.io/MACS + +3) Description on various file formats used in MACS3. ## Install From 2a6068662d538e69b594756856c28542fa0b80c6 Mon Sep 17 00:00:00 2001 From: Tao Liu Date: Fri, 3 May 2024 16:13:11 -0400 Subject: [PATCH 16/18] edit adv tutorial. Add empty files for file formats. --- .../Advanced_Step-by-step_Peak_Calling.md | 471 ++++++++++-------- docs/source/docs/BED.md | 1 + docs/source/docs/BEDPE.md | 26 + docs/source/docs/SAMBAMBAMPE.md | 2 + docs/source/docs/bedGraph.md | 1 + docs/source/docs/broadPeak.md | 1 + docs/source/docs/callpeakxls.md | 1 + docs/source/docs/cutoffanalysis.md | 1 + docs/source/docs/gappedPeak.md | 1 + docs/source/docs/hmmratacModel.md | 1 + docs/source/docs/narrowPeak.md | 1 + docs/source/docs/vcf.md | 1 + docs/source/index.md | 1 + 13 files changed, 299 insertions(+), 210 deletions(-) create mode 100644 docs/source/docs/BED.md create mode 100644 docs/source/docs/BEDPE.md create mode 100644 docs/source/docs/SAMBAMBAMPE.md create mode 100644 docs/source/docs/bedGraph.md create mode 100644 docs/source/docs/broadPeak.md create mode 100644 docs/source/docs/callpeakxls.md create mode 100644 docs/source/docs/cutoffanalysis.md create mode 100644 docs/source/docs/gappedPeak.md create mode 100644 docs/source/docs/hmmratacModel.md create mode 100644 docs/source/docs/narrowPeak.md create mode 100644 docs/source/docs/vcf.md diff --git a/docs/source/docs/Advanced_Step-by-step_Peak_Calling.md b/docs/source/docs/Advanced_Step-by-step_Peak_Calling.md index 899f808e..113876f2 100644 --- a/docs/source/docs/Advanced_Step-by-step_Peak_Calling.md +++ b/docs/source/docs/Advanced_Step-by-step_Peak_Calling.md @@ -1,291 +1,342 @@ # 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.* +Over the years, many users have asked us questions about whether they +can analyze their X-Seq (not ChIP-Seq) data using MACS, or customize +the `callpeak` function to suit their specific needs. Typically, we +recommend finding a tool that's more suited to their data type, as +`callpeak` is specifically optimized for ChIP-Seq. However, MACS3 does +offer a range of subcommands that allow you to customize every step of +your analysis. In this tutorial, I will demonstrate how to break down +the main `callpeak` function into a pipeline using various MACS3 +subcommands, such as `filterdup`, `predictd`, `pileup`, `bdgcmp`, +`bdgopt`, and `bdgpeakcall` (or `bdgbroadcall` for broad marks). This +approach allows you to adjust or skip steps and modify parameters to +analyze your data in a highly customized way. Additionally, you will +have a complete idea of how `callpeak` works. We'll use two test +files, `CTCF_ChIP_200K.bed.gz` and `CTCF_Control_200K.bed.gz`, which +you can find in the MACS3 GitHub repository in the `test` directory. + +*Note, currently this tutorial is mainly for single-end +datasets. Please read the tutorial carefully and modify the command +line for paired-end data accordingly.* ## 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 +In the initial step of ChIP-Seq analysis with `callpeak`, we read both +ChIP and control data and remove redundant reads from each genomic +location. While we won't delve into the reasons behind this process, +we'll explain how you can accomplish this using the `filterdup` +subcommand. By default, `callpeak` permits only one duplicate read per +location, which is set with `--keep-dup=1`. To replicate this setting, +you can 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 choose a different setting for `--keep-dup` or allow MACS3 to +automatically determine the maximum number of allowed duplicated reads +for each genomic loci for ChIP and control separately. For more +details, check `macs3 filterdup -h`. If you opt for the `--keep-dup +auto` setting, ensure the genome size is set appropriately. MACS3 will +report the final number of reads retained after filtering. It’s +crucial to record these numbers as we need them to normalize the ChIP +and control signals to the same depth. In this example, the numbers +are 199,583 for ChIP and 199,867 for control, resulting in a ratio of +approximately 0.99858. The output files from `filterdup` are in BED +format. Please note that if you are using Paired-end data in BAM +format as input and specify the `-f BAMPE` option, you will get the +output in `BEDPE` format. Check [this document for detail](./BEDPE.md) +on this `BEDPE` format. ## 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: - -` +This is a crucial step for analyzing ChIP-Seq with MACS3, as well as +other types of data. The location of a sequenced read typically +indicates only the end of a DNA fragment of interest originated from +such as transcription factor binding sites (TFBS) or DNA +hypersensitive sites. To accurately determine the enrichment, you +must estimate the actual length of this DNA fragment. This process can +also be seen as a data smoothing technique. With `macs3 callpeak`, the +output will typically include the identification of a certain number +of peak pairs and the predicted fragment length, denoted as `d` in +MACS3 terminology. This can also be accomplished using the `predictd` +subcommand, which we need to apply only to 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. +``` + +In this process, the `-g` (genome size) needs to be set based on your +sample, and the mfold parameters for `-m` must be reasonably +established. To mimic the default behavior of macs3 `callpeak`, use +`-m 5 50`. Of course, you can adjust these parameters as needed. The +output from `predictd` will provide the fragment length `d`, which in +this example is `254`. Make sure to write this number down, as we'll +need it in the next step. However, if you prefer not to extend the +reads or if you have a more accurate estimate of the fragment length, +you can skip this step. + +Please note that for paired-end data, this step is still necessary +since this function will tell us the average fragment length defined +by the mapping locations of read pairs. For example, if you run this +on the `CTCF_PE_ChIP_chr22_50k.bedpe.gz` file in the test directory: + +``` +$ macs3 predictd -f BEDPE -i CTCF_PE_ChIP_chr22_50k.bedpe.gz +``` + +This function will print out that `# Average insertion length of all +pairs is 253 bps`. You should write down this number `253` for +building the control bias track for pair-end data in Step 4. ## 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: +Now that you've estimated the fragment length, we can proceed to +generate a pileup track for the ChIP sample using the MACS3 `pileup` +subcommand. The following command replicates the behavior of callpeak: ` $ 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. +This command produces a file in BEDGRAPH format, +`CTCF_ChIP_200K_filterdup.pileup.bdg`, which contains the fragment +pileup signals for the ChIP sample. We use `--extsize 254`, where +`254` is the number obtained from the `predictd` step. In ChIP-Seq +data processing, as demonstrated in this tutorial, we extend reads in +the 5' -> 3' direction, which is the default behavior of the `pileup` +function. + +If you are analyzing DNAse-Seq data, or if the cutting site detected +by short read sequencing (the 5' mapping location of the read) is +believed to be centrally located within the DNA region of interest, +you should use the `-B` option. This setting allows for the extension +of the 5' location in both directions. For example, `-B 100` would +extend the 5' cutting site on each side by 100 base pairs (200bps in +total) before generating the pileup signal. + +For paired-end data, there is no need to specify `--extsize` as +`pileup` will automatically pile up the entire region between the two +5' mapping locations of the read pair. However, it is crucial to use +`-f BEDPE` or `-f BAMPE` to indicate to MACS3 that the input file +contains paired-end data. ## 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. +By default, the MACS3 `callpeak` function calculates local bias by +considering the maximum bias from the surrounding 1kb (set by +`--slocal`), 10kb (set by `--llocal`), the fragment length `d` +(predicted from the `predictd` function), and the whole genome +background. In this section, we demonstrate how each bias is +calculated and how they can be combined using the subcommands. + +Please note that, for paired-data data, we should treat the control as +single-end data by NOT specifying `-f BAMPE` or `-f BEDPE`. Also, we +should use the average fragment length from Step 2 as `d` in the +following steps. ### 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: +To create the background noise track, extend the control read to both +sides using the `-B` option in the `pileup` function. This approach +assumes that the cutting site from the control sample represent +certain noise from the exact same location. To accomplish this, use +half of `d` obtained from the `predictd` module. For instance, with +`d` equaling 254, use 127 (half of 254) as follows: -` +``` $ 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 BEDGRAPH file `d_bg.bdg` contains the background noise data (`d` +background) from the control sample. ### 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: +Next, you can create a background noise track for the `slocal`bps +local window, or a 1kb window by default. Imagine that each cutting +site represents a surrounding noise of 1kb (this value is +adjustable). Use the following command: -` +``` $ 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: +Here, 500 represents half of 1k, as the default `slocal` for +`callpeak`. Since the ChIP signal track was constructed by extending +reads to `d` size fragments, we need to normalize the 1kb noise by +multiplying the values by `d/slocal`, which is 254/1000 = 0.254 in our +example. To do this, apply 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 file `1k_bg_norm.bdg` contains the normalized slocal background +from the control sample. Note, normalization for the `d` background is +not necessary since 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: +The background noise from a larger region can be generated similarly +to the previous approach for the slocal background, with the only +difference being the extension size. By default, MACS3 `callpeak` uses +a 10kb surrounding window, but this value can be adjusted: -` +``` $ 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. +Here, the `extsize` should be set as half of the llocal, which is 5000 +in this case. The appropriate multiplier 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 file `10k_bg_norm.bdg` now contains the normalized llocal +background from the 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. +The whole genome background is calculated using the formula: +`number_of_control_reads * fragment_length / genome_size`. In our +example, this calculation would be: + +``` +199867 * 254 / 2700000000 ≈ 0.0188023 +``` + +You don't need to execute any subcommands to create a genome +background track, as it's represented by 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. +To compute the maximum bias for each genomic location, you can follow +the default behavior of MACS3 `callpeak` or customize your pipeline to +include additional noise backgrounds (such as 5k or 50k). Here's how +to combine the background noises and determine the maximum bias: -Take the maximum between slocal (1k) and llocal (10k) background: +First, take the maximum between the slocal (1k) and llocal (10k) +backgrounds: -` +``` 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: +Next, compare this maximum with the `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 +Finally, combine this with the genome-wide background using the +`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. +The resulting file `local_bias_raw.bdg` is a BEDGRAPH file containing +the maximum 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: +To ensure accurate comparison between ChIP and control signals, both +must be scaled to the same sequencing depth. The `callpeak` module +typically scales down the larger sample to match the smaller one, +preventing inflation of smaller values and enhancing the specificity +of the results. In our example, after duplicate filtering, the final +read counts are 199,583 for ChIP and 199,867 for control. Therefore, +the control bias needs to be scaled down using the ratio between ChIP +and control, which is 199,583/199,867 = 0.99858. To accomplish this: -` + +``` $ 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. +The output file is named `local_lambda.bdg`, as it contains values +that represent the lambda (or expected value), which 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 - -` +To identify enriched regions and predict peaks, the ChIP signals and +local lambda stored in the BEDGRAPH file must be compared using a +statistical model. This is done using the `bdgcmp` module, which +outputs a score for each base pair in the genome. Despite potentially +large data sizes, the BEDGRAPH format efficiently manages this by +merging nearby regions with identical scores. Theoretically, the size +of the output file for scores depends on the complexity of your +data. The maximum number of data points, when using `d`, `slocal`, and +`llocal` backgrounds, is the minimum between the genome size and +approximately `(number_of_ChIP_reads + number_of_control_reads*3)*2`, +which in our case is about 1.6 million. + +The commands to generate score tracks are: + +``` $ 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 -` +``` +$ macs3 bdgcmp -t CTCF_ChIP_200K_filterdup.pileup.bdg -c local_lambda.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. +contains the `-log10(p-values)` or `-log10(q-values)` for each base +pair, derived through a local Poisson test. This means the ChIP signal +at each base pair will be compared against the corresponding local +lambda from the control using a Poisson model. *Note*, following this +tutorial ensures that there are no zeros in the local lambda track, as +the smallest value is the whole genome background. However, if the +genome background is not included, many zeros in the local lambda can +disrupt the Poisson test. In such cases, you need to set the +`pseudocount` for `bdgcmp` using the `-p` option. This pseudocount +will be added to both ChIP and local lambda values before the +test. The choice of pseudocount is largely arbitrary, and you may find +various discussions online. Generally, a higher pseudocount increases +specificity but decreases 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: +The final step in peak calling is to identify regions that surpass a +specific score cutoff using the `bdgpeakcall` function for narrow peak +calling. Although this process may seem straightforward, it involves +two additional parameters: -` +1. **Merging Nearby Regions**: If two regions exceed the cutoff and + are separated by a smaller, lower-scoring region, they should be + merged into a single larger region to account for + fluctuations. This merging threshold is set as the read length in + the MACS3 `callpeak` function, reflecting the dataset's + resolution. For `bdgpeakcall`, you must obtain the read length from + Step 1 or by examining the raw fastq file and set this with the + `-g` option. + +2. **Minimum Peak Length**: To avoid calling excessively small peaks, + a minimum peak length is required. The MACS3 `callpeak` function + automatically uses the fragment size `d` for this purpose. In + `bdgpeakcall`, set the `-l` option to the `d` value determined in + Step 2. + +Finally, set the cutoff value. Remember, the scores from `bdgcmp` are +in -log10 format. For example, to set a cutoff of 0.05, use a -log10 +value of approximately 1.3. The command is as follows: + + +``` $ 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. +The output is essentially a narrowPeak format file (a type of BED +file), which includes the locations of peaks with the summit location +noted in the last column. If you want to explore how to better decide +the cutoff, please read the [tutorial for cutoff analysis](./cutoffanalysis.md) - diff --git a/docs/source/docs/BED.md b/docs/source/docs/BED.md new file mode 100644 index 00000000..800e0f62 --- /dev/null +++ b/docs/source/docs/BED.md @@ -0,0 +1 @@ +# BED format diff --git a/docs/source/docs/BEDPE.md b/docs/source/docs/BEDPE.md new file mode 100644 index 00000000..3ee3ff1f --- /dev/null +++ b/docs/source/docs/BEDPE.md @@ -0,0 +1,26 @@ +# 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/SAMBAMBAMPE.md b/docs/source/docs/SAMBAMBAMPE.md new file mode 100644 index 00000000..bc583edf --- /dev/null +++ b/docs/source/docs/SAMBAMBAMPE.md @@ -0,0 +1,2 @@ +# SAM/BAM/BAMPE format + diff --git a/docs/source/docs/bedGraph.md b/docs/source/docs/bedGraph.md new file mode 100644 index 00000000..6aa5bbcf --- /dev/null +++ b/docs/source/docs/bedGraph.md @@ -0,0 +1 @@ +# bedGraph format diff --git a/docs/source/docs/broadPeak.md b/docs/source/docs/broadPeak.md new file mode 100644 index 00000000..523509b0 --- /dev/null +++ b/docs/source/docs/broadPeak.md @@ -0,0 +1 @@ +# broadPeak format diff --git a/docs/source/docs/callpeakxls.md b/docs/source/docs/callpeakxls.md new file mode 100644 index 00000000..a50fd149 --- /dev/null +++ b/docs/source/docs/callpeakxls.md @@ -0,0 +1 @@ +# `callpeak` output XLS format diff --git a/docs/source/docs/cutoffanalysis.md b/docs/source/docs/cutoffanalysis.md new file mode 100644 index 00000000..a3a5385c --- /dev/null +++ b/docs/source/docs/cutoffanalysis.md @@ -0,0 +1 @@ +# cutoff analysis output format diff --git a/docs/source/docs/gappedPeak.md b/docs/source/docs/gappedPeak.md new file mode 100644 index 00000000..84cedc2f --- /dev/null +++ b/docs/source/docs/gappedPeak.md @@ -0,0 +1 @@ +# gappedPeak format diff --git a/docs/source/docs/hmmratacModel.md b/docs/source/docs/hmmratacModel.md new file mode 100644 index 00000000..25a5f651 --- /dev/null +++ b/docs/source/docs/hmmratacModel.md @@ -0,0 +1 @@ +# `hmmratac` HMM model json file format diff --git a/docs/source/docs/narrowPeak.md b/docs/source/docs/narrowPeak.md new file mode 100644 index 00000000..aec8e107 --- /dev/null +++ b/docs/source/docs/narrowPeak.md @@ -0,0 +1 @@ +# narrowPeak format diff --git a/docs/source/docs/vcf.md b/docs/source/docs/vcf.md new file mode 100644 index 00000000..947df29f --- /dev/null +++ b/docs/source/docs/vcf.md @@ -0,0 +1 @@ +# VCF format diff --git a/docs/source/index.md b/docs/source/index.md index 0b0c1125..fda11441 100644 --- a/docs/source/index.md +++ b/docs/source/index.md @@ -171,6 +171,7 @@ docs/INSTALL.md docs/subcommands_index.md docs/fileformats_index.md docs/Advanced_Step-by-step_Peak_Calling.md +docs/cutoffanalysis.md docs/qa.md docs/tutorial.md CODE_OF_CONDUCT.md From 0fae030a966c13f976e30dcbb4c74a39a0e995ee Mon Sep 17 00:00:00 2001 From: Tao Liu Date: Fri, 3 May 2024 17:31:07 -0400 Subject: [PATCH 17/18] cutoff analysis --- docs/source/docs/cutoffanalysis.md | 46 +++++++++++++++++++++++++++++- 1 file changed, 45 insertions(+), 1 deletion(-) diff --git a/docs/source/docs/cutoffanalysis.md b/docs/source/docs/cutoffanalysis.md index a3a5385c..4a4894dd 100644 --- a/docs/source/docs/cutoffanalysis.md +++ b/docs/source/docs/cutoffanalysis.md @@ -1 +1,45 @@ -# cutoff analysis output format +# 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 use `bdgpeakcall` as example. + +The cutoff analysis will generate a list of possible cutoffs to check +from a loose cutoff to a stringent cutoff, with a given step. For +example, if the `--cutoff-analysis-min` is set as 0, the +`--cutoff-analysis-max` is set as 10, and the +`--cutoff-analysis-steps` is set as 20, then the list of cutoff values +to be investigated will range from 0 to 10, with an increase of 0.5 +for each step. + +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. + +Please check the document for [`hmmratac`](./hmmratac.md) function for +choosing lower, upper and pre-scan cutoff values from cutoff-analysis +result. From 759e10099b9c08fa70e3f10c70520e416e275910 Mon Sep 17 00:00:00 2001 From: Tao Liu Date: Tue, 7 May 2024 14:24:42 -0400 Subject: [PATCH 18/18] handle error correctly #643 --- MACS3/Commands/callvar_cmd.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/MACS3/Commands/callvar_cmd.py b/MACS3/Commands/callvar_cmd.py index 390e1674..1ae96c7a 100644 --- a/MACS3/Commands/callvar_cmd.py +++ b/MACS3/Commands/callvar_cmd.py @@ -1,4 +1,4 @@ -# Time-stamp: <2022-09-15 17:25:49 Tao Liu> +# Time-stamp: <2024-05-07 11:47:04 Tao Liu> """Description: Call variants directly @@ -194,7 +194,7 @@ def run( args ): else: ra_collection = RACollection( chrom, peak, tbam.get_reads_in_region( chrom, peak["start"], peak["end"], maxDuplicate=maxDuplicate ) ) except: - info ("No reads found in peak: ", chrom.decode(), peak["start"], peak["end"], ". Skipped!") + info ("No reads found in this peak. Skipped" ) # while there is no reads in peak region, simply skip it. continue