# MACSr

#### 15 April 2025

# 1 Introduction

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

This package is a wrapper of the MACS toolkit based on `basilisk`.

# 2 Load the package

The package is built on basilisk. The dependent python library macs3 will be installed automatically inside its conda environment.

    library(MACSr)

# 3 Usage

## 3.1 MACS3 functions

There are 13 functions imported from MACS3. Details of each function can be checked from its manual.

Functions | Description
--- | ---
`callpeak` | Main MACS3 Function to call peaks from alignment results.
`bdgpeakcall` | Call peaks from bedGraph output.
`bdgbroadcall` | Call broad peaks from bedGraph output.
`bdgcmp` | Comparing two signal tracks in bedGraph format.
`bdgopt` | Operate the score column of bedGraph file.
`cmbreps` | Combine BEDGraphs of scores from replicates.
`bdgdiff` | Differential peak detection based on paired four bedGraph files.
`filterdup` | Remove duplicate reads, then save in BED/BEDPE format.
`predictd` | Predict d or fragment size from alignment results.
`pileup` | Pileup aligned reads (single-end) or fragments (paired-end)
`randsample` | Randomly choose a number/percentage of total reads.
`refinepeak` | Take raw reads alignment, refine peak summits.
`callvar` | Call variants in given peak regions from the alignment BAM files.
`hmmratac` | Dedicated peak calling based on Hidden Markov Model for ATAC-seq data.

## 3.2 Function `callpeak`

We have uploaded multipe test datasets from MACS to a data package `MACSdata` in the `ExperimentHub`. For example, Here we download a pair of single-end bed files to run the `callpeak` function.

    eh <- ExperimentHub::ExperimentHub()
    eh <- AnnotationHub::query(eh, "MACSdata")
    CHIP <- eh[["EH4558"]]
    #> see ?MACSdata and browseVignettes('MACSdata') for documentation
    #> loading from cache
    CTRL <- eh[["EH4563"]]
    #> see ?MACSdata and browseVignettes('MACSdata') for documentation
    #> loading from cache

Here is an example to call narrow and broad peaks on the SE bed files.

    cp1 <- callpeak(CHIP, CTRL, gsize = 5.2e7, store_bdg = TRUE,
                    name = "run_callpeak_narrow0", outdir = tempdir(),
                    cutoff_analysis = TRUE)
    #> + /Users/biocbuild/Library/Caches/org.R-project.R/R/basilisk/1.20.0/0/bin/conda create --yes --prefix /Users/biocbuild/Library/Caches/org.R-project.R/R/basilisk/1.20.0/MACSr/1.16.0/env_macs 'python=3.10' --quiet -c conda-forge --override-channels
    #> + /Users/biocbuild/Library/Caches/org.R-project.R/R/basilisk/1.20.0/0/bin/conda install --yes --prefix /Users/biocbuild/Library/Caches/org.R-project.R/R/basilisk/1.20.0/MACSr/1.16.0/env_macs 'python=3.10' -c conda-forge --override-channels
    #> + /Users/biocbuild/Library/Caches/org.R-project.R/R/basilisk/1.20.0/0/bin/conda install --yes --prefix /Users/biocbuild/Library/Caches/org.R-project.R/R/basilisk/1.20.0/MACSr/1.16.0/env_macs -c conda-forge 'python=3.10' 'python=3.10' --override-channels
    #> INFO  @ 15 Apr 2025 18:33:11: [720 MB]
    #> # Command line:
    #> # ARGUMENTS LIST:
    #> # name = run_callpeak_narrow0
    #> # format = AUTO
    #> # ChIP-seq file = ['/Users/biocbuild/Library/Caches/org.R-project.R/R/ExperimentHub/b78613837304_4601']
    #> # control file = ['/Users/biocbuild/Library/Caches/org.R-project.R/R/ExperimentHub/b7861af4159e_4606']
    #> # effective genome size = 5.20e+07
    #> # band width = 300
    #> # model fold = [5.0, 50.0]
    #> # qvalue cutoff = 5.00e-02
    #> # The maximum gap between significant sites is assigned as the read length/tag size.
    #> # The minimum length of peaks is assigned as the predicted fragment length "d".
    #> # Larger dataset will be scaled towards smaller dataset.
    #> # Range for calculating regional lambda is: 1000 bps and 10000 bps
    #> # Broad region calling is off
    #> # Additional cutoff on fold-enrichment is: 0.10
    #> # Paired-End mode is off
    #>
    #> INFO  @ 15 Apr 2025 18:33:11: [720 MB] #1 read tag files...
    #> INFO  @ 15 Apr 2025 18:33:11: [720 MB] #1 read treatment tags...
    #> INFO  @ 15 Apr 2025 18:33:11: [724 MB] Detected format is: BED
    #> INFO  @ 15 Apr 2025 18:33:11: [724 MB] * Input file is gzipped.
    #> INFO  @ 15 Apr 2025 18:33:11: [728 MB] #1.2 read input tags...
    #> INFO  @ 15 Apr 2025 18:33:11: [728 MB] Detected format is: BED
    #> INFO  @ 15 Apr 2025 18:33:11: [728 MB] * Input file is gzipped.
    #> INFO  @ 15 Apr 2025 18:33:11: [730 MB] #1 tag size is determined as 101 bps
    #> INFO  @ 15 Apr 2025 18:33:11: [730 MB] #1 tag size = 101.0
    #> INFO  @ 15 Apr 2025 18:33:11: [730 MB] #1  total tags in treatment: 49622
    #> INFO  @ 15 Apr 2025 18:33:11: [730 MB] #1 user defined the maximum tags...
    #> INFO  @ 15 Apr 2025 18:33:11: [730 MB] #1 filter out redundant tags at the same location and the same strand by allowing at most 1 tag(s)
    #> INFO  @ 15 Apr 2025 18:33:11: [730 MB] #1  tags after filtering in treatment: 48047
    #> INFO  @ 15 Apr 2025 18:33:11: [730 MB] #1  Redundant rate of treatment: 0.03
    #> INFO  @ 15 Apr 2025 18:33:11: [730 MB] #1  total tags in control: 50837
    #> INFO  @ 15 Apr 2025 18:33:11: [730 MB] #1 user defined the maximum tags...
    #> INFO  @ 15 Apr 2025 18:33:11: [730 MB] #1 filter out redundant tags at the same location and the same strand by allowing at most 1 tag(s)
    #> INFO  @ 15 Apr 2025 18:33:11: [730 MB] #1  tags after filtering in control: 50783
    #> INFO  @ 15 Apr 2025 18:33:11: [730 MB] #1  Redundant rate of control: 0.00
    #> INFO  @ 15 Apr 2025 18:33:11: [730 MB] #1 finished!
    #> INFO  @ 15 Apr 2025 18:33:11: [730 MB] #2 Build Peak Model...
    #> INFO  @ 15 Apr 2025 18:33:11: [730 MB] #2 looking for paired plus/minus strand peaks...
    #> INFO  @ 15 Apr 2025 18:33:11: [730 MB] #2 Total number of paired peaks: 469
    #> INFO  @ 15 Apr 2025 18:33:11: [730 MB] #2 Model building with cross-correlation: Done
    #> INFO  @ 15 Apr 2025 18:33:11: [730 MB] #2 finished!
    #> INFO  @ 15 Apr 2025 18:33:11: [730 MB] #2 predicted fragment length is 228 bps
    #> INFO  @ 15 Apr 2025 18:33:11: [730 MB] #2 alternative fragment length(s) may be 228 bps
    #> INFO  @ 15 Apr 2025 18:33:11: [730 MB] #2.2 Generate R script for model : /tmp/RtmpsgghYK/run_callpeak_narrow0_model.r
    #> INFO  @ 15 Apr 2025 18:33:11: [730 MB] #3 Call peaks...
    #> INFO  @ 15 Apr 2025 18:33:11: [730 MB] #3 Pre-compute pvalue-qvalue table...
    #> INFO  @ 15 Apr 2025 18:33:11: [730 MB] #3 Cutoff vs peaks called will be analyzed!
    #> INFO  @ 15 Apr 2025 18:33:11: [769 MB] #3 Analysis of cutoff vs num of peaks or total length has been saved in b'/tmp/RtmpsgghYK/run_callpeak_narrow0_cutoff_analysis.txt'
    #> INFO  @ 15 Apr 2025 18:33:11: [769 MB] #3 In the peak calling step, the following will be performed simultaneously:
    #> INFO  @ 15 Apr 2025 18:33:11: [769 MB] #3   Write bedGraph files for treatment pileup (after scaling if necessary)... run_callpeak_narrow0_treat_pileup.bdg
    #> INFO  @ 15 Apr 2025 18:33:11: [769 MB] #3   Write bedGraph files for control lambda (after scaling if necessary)... run_callpeak_narrow0_control_lambda.bdg
    #> INFO  @ 15 Apr 2025 18:33:11: [769 MB] #3   Pileup will be based on sequencing depth in treatment.
    #> INFO  @ 15 Apr 2025 18:33:11: [769 MB] #3 Call peaks for each chromosome...
    #> INFO  @ 15 Apr 2025 18:33:12: [780 MB] #4 Write output xls file... /tmp/RtmpsgghYK/run_callpeak_narrow0_peaks.xls
    #> INFO  @ 15 Apr 2025 18:33:12: [780 MB] #4 Write peak in narrowPeak format file... /tmp/RtmpsgghYK/run_callpeak_narrow0_peaks.narrowPeak
    #> INFO  @ 15 Apr 2025 18:33:12: [780 MB] #4 Write summits bed file... /tmp/RtmpsgghYK/run_callpeak_narrow0_summits.bed
    #> INFO  @ 15 Apr 2025 18:33:12: [780 MB] Done!
    cp2 <- callpeak(CHIP, CTRL, gsize = 5.2e7, store_bdg = TRUE,
                    name = "run_callpeak_broad", outdir = tempdir(),
                    broad = TRUE)
    #>

Here are the outputs.

    cp1
    #> macsList class
    #> $outputs:
    #>  /tmp/RtmpsgghYK/run_callpeak_narrow0_control_lambda.bdg
    #>  /tmp/RtmpsgghYK/run_callpeak_narrow0_cutoff_analysis.txt
    #>  /tmp/RtmpsgghYK/run_callpeak_narrow0_model.r
    #>  /tmp/RtmpsgghYK/run_callpeak_narrow0_peaks.narrowPeak
    #>  /tmp/RtmpsgghYK/run_callpeak_narrow0_peaks.xls
    #>  /tmp/RtmpsgghYK/run_callpeak_narrow0_summits.bed
    #>  /tmp/RtmpsgghYK/run_callpeak_narrow0_treat_pileup.bdg
    #> $arguments: tfile, cfile, gsize, outdir, name, store_bdg, cutoff_analysis
    #> $log:
    #>  INFO  @ 15 Apr 2025 18:33:11: [720 MB]
    #>  # Command line:
    #>  # ARGUMENTS LIST:
    #>  # name = run_callpeak_narrow0
    #>  # format = AUTO
    #> ...
    cp2
    #> macsList class
    #> $outputs:
    #>  /tmp/RtmpsgghYK/run_callpeak_broad_control_lambda.bdg
    #>  /tmp/RtmpsgghYK/run_callpeak_broad_model.r
    #>  /tmp/RtmpsgghYK/run_callpeak_broad_peaks.broadPeak
    #>  /tmp/RtmpsgghYK/run_callpeak_broad_peaks.gappedPeak
    #>  /tmp/RtmpsgghYK/run_callpeak_broad_peaks.xls
    #>  /tmp/RtmpsgghYK/run_callpeak_broad_treat_pileup.bdg
    #> $arguments: tfile, cfile, gsize, outdir, name, store_bdg, broad
    #> $log:
    #>

## 3.3 The `macsList` class

The `macsList` is designed to contain everything of an execution, including function, inputs, outputs and logs, for the purpose of reproducibility.

For example, we can the function and input arguments.

    cp1$arguments
    #> [[1]]
    #> callpeak
    #>
    #> $tfile
    #> CHIP
    #>
    #> $cfile
    #> CTRL
    #>
    #> $gsize
    #> [1] 5.2e+07
    #>
    #> $outdir
    #> tempdir()
    #>
    #> $name
    #> [1] "run_callpeak_narrow0"
    #>
    #> $store_bdg
    #> [1] TRUE
    #>
    #> $cutoff_analysis
    #> [1] TRUE

The files of all the outputs are collected.

    cp1$outputs
    #> [1] "/tmp/RtmpsgghYK/run_callpeak_narrow0_control_lambda.bdg"
    #> [2] "/tmp/RtmpsgghYK/run_callpeak_narrow0_cutoff_analysis.txt"
    #> [3] "/tmp/RtmpsgghYK/run_callpeak_narrow0_model.r"
    #> [4] "/tmp/RtmpsgghYK/run_callpeak_narrow0_peaks.narrowPeak"
    #> [5] "/tmp/RtmpsgghYK/run_callpeak_narrow0_peaks.xls"
    #> [6] "/tmp/RtmpsgghYK/run_callpeak_narrow0_summits.bed"
    #> [7] "/tmp/RtmpsgghYK/run_callpeak_narrow0_treat_pileup.bdg"

The `log` is especially important for `MACS` to check. Detailed information was given in the log when running.

    cat(paste(cp1$log, collapse="\n"))
    #> INFO  @ 15 Apr 2025 18:33:11: [720 MB]
    #> # Command line:
    #> # ARGUMENTS LIST:
    #> # name = run_callpeak_narrow0
    #> # format = AUTO
    #> # ChIP-seq file = ['/Users/biocbuild/Library/Caches/org.R-project.R/R/ExperimentHub/b78613837304_4601']
    #> # control file = ['/Users/biocbuild/Library/Caches/org.R-project.R/R/ExperimentHub/b7861af4159e_4606']
    #> # effective genome size = 5.20e+07
    #> # band width = 300
    #> # model fold = [5.0, 50.0]
    #> # qvalue cutoff = 5.00e-02
    #> # The maximum gap between significant sites is assigned as the read length/tag size.
    #> # The minimum length of peaks is assigned as the predicted fragment length "d".
    #> # Larger dataset will be scaled towards smaller dataset.
    #> # Range for calculating regional lambda is: 1000 bps and 10000 bps
    #> # Broad region calling is off
    #> # Additional cutoff on fold-enrichment is: 0.10
    #> # Paired-End mode is off
    #>
    #> INFO  @ 15 Apr 2025 18:33:11: [720 MB] #1 read tag files...
    #> INFO  @ 15 Apr 2025 18:33:11: [720 MB] #1 read treatment tags...
    #> INFO  @ 15 Apr 2025 18:33:11: [724 MB] Detected format is: BED
    #> INFO  @ 15 Apr 2025 18:33:11: [724 MB] * Input file is gzipped.
    #> INFO  @ 15 Apr 2025 18:33:11: [728 MB] #1.2 read input tags...
    #> INFO  @ 15 Apr 2025 18:33:11: [728 MB] Detected format is: BED
    #> INFO  @ 15 Apr 2025 18:33:11: [728 MB] * Input file is gzipped.
    #> INFO  @ 15 Apr 2025 18:33:11: [730 MB] #1 tag size is determined as 101 bps
    #> INFO  @ 15 Apr 2025 18:33:11: [730 MB] #1 tag size = 101.0
    #> INFO  @ 15 Apr 2025 18:33:11: [730 MB] #1  total tags in treatment: 49622
    #> INFO  @ 15 Apr 2025 18:33:11: [730 MB] #1 user defined the maximum tags...
    #> INFO  @ 15 Apr 2025 18:33:11: [730 MB] #1 filter out redundant tags at the same location and the same strand by allowing at most 1 tag(s)
    #> INFO  @ 15 Apr 2025 18:33:11: [730 MB] #1  tags after filtering in treatment: 48047
    #> INFO  @ 15 Apr 2025 18:33:11: [730 MB] #1  Redundant rate of treatment: 0.03
    #> INFO  @ 15 Apr 2025 18:33:11: [730 MB] #1  total tags in control: 50837
    #> INFO  @ 15 Apr 2025 18:33:11: [730 MB] #1 user defined the maximum tags...
    #> INFO  @ 15 Apr 2025 18:33:11: [730 MB] #1 filter out redundant tags at the same location and the same strand by allowing at most 1 tag(s)
    #> INFO  @ 15 Apr 2025 18:33:11: [730 MB] #1  tags after filtering in control: 50783
    #> INFO  @ 15 Apr 2025 18:33:11: [730 MB] #1  Redundant rate of control: 0.00
    #> INFO  @ 15 Apr 2025 18:33:11: [730 MB] #1 finished!
    #> INFO  @ 15 Apr 2025 18:33:11: [730 MB] #2 Build Peak Model...
    #> INFO  @ 15 Apr 2025 18:33:11: [730 MB] #2 looking for paired plus/minus strand peaks...
    #> INFO  @ 15 Apr 2025 18:33:11: [730 MB] #2 Total number of paired peaks: 469
    #> INFO  @ 15 Apr 2025 18:33:11: [730 MB] #2 Model building with cross-correlation: Done
    #> INFO  @ 15 Apr 2025 18:33:11: [730 MB] #2 finished!
    #> INFO  @ 15 Apr 2025 18:33:11: [730 MB] #2 predicted fragment length is 228 bps
    #> INFO  @ 15 Apr 2025 18:33:11: [730 MB] #2 alternative fragment length(s) may be 228 bps
    #> INFO  @ 15 Apr 2025 18:33:11: [730 MB] #2.2 Generate R script for model : /tmp/RtmpsgghYK/run_callpeak_narrow0_model.r
    #> INFO  @ 15 Apr 2025 18:33:11: [730 MB] #3 Call peaks...
    #> INFO  @ 15 Apr 2025 18:33:11: [730 MB] #3 Pre-compute pvalue-qvalue table...
    #> INFO  @ 15 Apr 2025 18:33:11: [730 MB] #3 Cutoff vs peaks called will be analyzed!
    #> INFO  @ 15 Apr 2025 18:33:11: [769 MB] #3 Analysis of cutoff vs num of peaks or total length has been saved in b'/tmp/RtmpsgghYK/run_callpeak_narrow0_cutoff_analysis.txt'
    #> INFO  @ 15 Apr 2025 18:33:11: [769 MB] #3 In the peak calling step, the following will be performed simultaneously:
    #> INFO  @ 15 Apr 2025 18:33:11: [769 MB] #3   Write bedGraph files for treatment pileup (after scaling if necessary)... run_callpeak_narrow0_treat_pileup.bdg
    #> INFO  @ 15 Apr 2025 18:33:11: [769 MB] #3   Write bedGraph files for control lambda (after scaling if necessary)... run_callpeak_narrow0_control_lambda.bdg
    #> INFO  @ 15 Apr 2025 18:33:11: [769 MB] #3   Pileup will be based on sequencing depth in treatment.
    #> INFO  @ 15 Apr 2025 18:33:11: [769 MB] #3 Call peaks for each chromosome...
    #> INFO  @ 15 Apr 2025 18:33:12: [780 MB] #4 Write output xls file... /tmp/RtmpsgghYK/run_callpeak_narrow0_peaks.xls
    #> INFO  @ 15 Apr 2025 18:33:12: [780 MB] #4 Write peak in narrowPeak format file... /tmp/RtmpsgghYK/run_callpeak_narrow0_peaks.narrowPeak
    #> INFO  @ 15 Apr 2025 18:33:12: [780 MB] #4 Write summits bed file... /tmp/RtmpsgghYK/run_callpeak_narrow0_summits.bed
    #> INFO  @ 15 Apr 2025 18:33:12: [780 MB] Done!

# 4 Resources

More details about `MACS3` can be found: https://macs3-project.github.io/MACS/.

# 5 SessionInfo

    sessionInfo()
    #> R version 4.5.0 RC (2025-04-04 r88126)
    #> Platform: x86_64-apple-darwin20
    #> Running under: macOS Monterey 12.7.6
    #>
    #> Matrix products: default
    #> BLAS:   /Library/Frameworks/R.framework/Versions/4.5-x86_64/Resources/lib/libRblas.0.dylib
    #> LAPACK: /Library/Frameworks/R.framework/Versions/4.5-x86_64/Resources/lib/libRlapack.dylib;  LAPACK version 3.12.1
    #>
    #> locale:
    #> [1] C/en_US.UTF-8/en_US.UTF-8/C/en_US.UTF-8/en_US.UTF-8
    #>
    #> time zone: America/New_York
    #> tzcode source: internal
    #>
    #> attached base packages:
    #> [1] stats     graphics  grDevices utils     datasets  methods   base
    #>
    #> other attached packages:
    #> [1] MACSdata_1.15.0  MACSr_1.16.0     BiocStyle_2.36.0
    #>
    #> loaded via a namespace (and not attached):
    #>  [1] KEGGREST_1.48.0         dir.expiry_1.16.0       xfun_0.52
    #>  [4] bslib_0.9.0             Biobase_2.68.0          lattice_0.22-7
    #>  [7] vctrs_0.6.5             tools_4.5.0             generics_0.1.3
    #> [10] stats4_4.5.0            curl_6.2.2              parallel_4.5.0
    #> [13] tibble_3.2.1            AnnotationDbi_1.70.0    RSQLite_2.3.9
    #> [16] blob_1.2.4              pkgconfig_2.0.3         Matrix_1.7-3
    #> [19] dbplyr_2.5.0            S4Vectors_0.46.0        lifecycle_1.0.4
    #> [22] GenomeInfoDbData_1.2.14 compiler_4.5.0          Biostrings_2.76.0
    #> [25] GenomeInfoDb_1.44.0     htmltools_0.5.8.1       sass_0.4.10
    #> [28] yaml_2.3.10             pillar_1.10.2           crayon_1.5.3
    #> [31] jquerylib_0.1.4         cachem_1.1.0            mime_0.13
    #> [34] ExperimentHub_2.16.0    AnnotationHub_3.16.0    basilisk_1.20.0
    #> [37] tidyselect_1.2.1        digest_0.6.37           dplyr_1.1.4
    #> [40] purrr_1.0.4             bookdown_0.43           BiocVersion_3.21.1
    #> [43] fastmap_1.2.0           grid_4.5.0              cli_3.6.4
    #> [46] magrittr_2.0.3          withr_3.0.2             filelock_1.0.3
    #> [49] UCSC.utils_1.4.0        rappdirs_0.3.3          bit64_4.6.0-1
    #> [52] rmarkdown_2.29          XVector_0.48.0          httr_1.4.7
    #> [55] bit_4.6.0               reticulate_1.42.0       png_0.1-8
    #> [58] memoise_2.0.1           evaluate_1.0.3          knitr_1.50
    #> [61] IRanges_2.42.0          basilisk.utils_1.20.0   BiocFileCache_2.16.0
    #> [64] rlang_1.1.6             Rcpp_1.0.14             glue_1.8.0
    #> [67] DBI_1.2.3               BiocManager_1.30.25     BiocGenerics_0.54.0
    #> [70] jsonlite_2.0.0          R6_2.6.1