---
title: "MACSr"
output:
  BiocStyle::html_document:
    toc: true
    toc_float: true
vignette: >
  %\VignetteIndexEntry{MACSr}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)
```

# 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`.

# Load the package
The package is built on
[basilisk](https://bioconductor.org/packages/release/bioc/html/basilisk.html). The
dependent python library
[macs3](https://github.com/macs3-project/MACS) will be installed
automatically inside its conda environment.

```{r setup}
library(MACSr)
```

# Usage
## 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. |


## 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.

```{r}
eh <- ExperimentHub::ExperimentHub()
eh <- AnnotationHub::query(eh, "MACSdata")
CHIP <- eh[["EH4558"]]
CTRL <- eh[["EH4563"]]
```

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

```{r}
cp1 <- callpeak(CHIP, CTRL, gsize = 5.2e7, store_bdg = TRUE,
                name = "run_callpeak_narrow0", outdir = tempdir(),
                cutoff_analysis = TRUE)
cp2 <- callpeak(CHIP, CTRL, gsize = 5.2e7, store_bdg = TRUE,
                name = "run_callpeak_broad", outdir = tempdir(),
                broad = TRUE)
```

Here are the outputs.
```{r}
cp1
cp2
```

## 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.
```{r}
cp1$arguments
```

The files of all the outputs are collected.
```{r}
cp1$outputs
```

The `log` is especially important for `MACS` to check. Detailed
information was given in the log when running.
```{r}
cat(paste(cp1$log, collapse="\n"))
```

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


# SessionInfo
```{r}
sessionInfo()
```