---
title: "HarmonizR_Vignette"
author: "Simon Schlumbohm"
date: "`r Sys.Date()`"
output: rmarkdown::html_vignette
vignette: >
    %\VignetteIndexEntry{HarmonizR_Vignette}
    %\VignetteEngine{knitr::rmarkdown}
    %\VignetteEncoding{UTF-8}
---

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


## Introduction

HarmonizR is a framework around the popular batch effect reduction algorithms
`ComBat` and `limma`, who, on their own, are unable to deal with missing data
points within the data. Missing values are not uncommon in biological data,
especially in the field of proteomics, for which the tool has originally been
developed. HarmonizR uses a matrix dissection approach to circumvent the
problematic existence of missing values and still apply established batch effect
reduction strategies. Recent updates to the HarmonizR algorithm include but are
not limited to increased computational efficiency and more reliable rescue of
features (e.g. proteins/genes). For a full overview we would like to direct the
reader to our paper published in 2022 in Nature Communications: 
<https://doi.org/10.1038/s41467-022-31007-x>

All information regarding the upcoming sections can also be found within our
SOP on Github, which is found under the following link:
<https://www.github.com/HSU-HPC/HarmonizR/tree/HarmonizR-1.1/HarmonizR_SOP.pdf>.

Please have a look over there as well.


## Installation

The HarmonizR implementation is 100 % written in the programming language `R`.
The easiest way to install it is using the package `devtools` that can be 
installed from CRAN via `install.packages("devtools")` while in the `R` 
environment. For further information, please refer to the `devtools`
documentation.

Installation from Github Repository:

The HarmonizR package 
(<https://github.com/HSU-HPC/HarmonizR/tree/HarmonizR-1.1> leads to the package
as well as example data) can be installed directly from GitHub via the command 
`devtools::install_github("HSU-HPC/HarmonizR/HarmonizR@HarmonizR-1.1")`, while
in the `R` software environment.

Installation from HarmonizR.zip file:

Please make sure to have `devtools` installed. Download the code via the green
Code button (<https://github.com/HSU-HPC/HarmonizR/tree/HarmonizR-1.1>). Unzip
the downloaded .zip file. The HarmonizR package is the folder called HarmonizR,
which was within the .zip file. While in the `R` environment and while in the
parent directory of said HarmonizR, enter in the command line:
`devtools::install("HarmonizR")` to install the package. Alternatively, while
inside the HarmonizR folder, enter `devtools::install()`.

Once installed, the HarmonizR package can be used via:

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


## Example Usage

For this example, we create a simple dataframe containing 3 features and 6 
samples:

```{r}
# create a dataframe with 3 rows and 6 columns filled with random numbers
df <- data.frame(matrix(rnorm(n = 3*6), ncol = 6))
# set the column names
colnames(df) <- c("A", "B", "C", "D", "E", "F")
# create a vector of row names
row_names <- c("F1", "F2", "F3")
# set the row names
rownames(df) <- row_names
# this is what it looks like:
df
```

Now we create a fitting description, which assigns 2 samples to a batch
(3 batches total):

```{r}
# create a vector of batch numbers
batch <- rep(1:3, each = 2)
# create a dataframe with 6 rows and 3 columns
des <- data.frame(ID = colnames(df), sample = 1:6, batch = batch)
# this is what it looks like:
des
```

HarmonizR usage requires a single function call of the `harmonizR()` function.
Here, we pass the created dataframes directly for a sequential run of
HarmonizR. Alternatively, a path to the respective input files can be passed.

```{r}
# use the harmonizR() function; turning off creation of an output .tsv file
result <- harmonizR(df, des, output_file = FALSE, cores = 1)
```

The result mirrors the input `data.frame` closely, yet the batch-effect
has been reduced by either `ComBat` or `limma`:

```{r}
result
```

Alternatively, S4 data may be used as input. In this case, no description
file is needed as long as a batch description is included within the 
`SummarizedExperiment`. An example input may look like this:

```{r}
nrows <- 20
ncols <- 8
counts <- matrix(runif(nrows * ncols, 1, 1e4), nrows)
colData <- data.frame(Batch=c(1,1,1,1,2,2,2,2))
SummExp = SummarizedExperiment::SummarizedExperiment(
    assays=list(counts=counts), 
    colData=colData)
```

It may be passed instead of `data_as_input` (following parameter explanation).

### Parameters

HarmonizR expects 2 mandatory and a total of nine optional arguments. 
First, the mandatory ones:

-   `data_as_input`

-   `description_as_input`

The first argument `data_as_input`, is the path to the raw data, the second 
argument, `description_as_input`, is the path to the description file. Both 
input files can be given via their file path and do not have to be read in 
separately by hand. This method is recommended, as it ensures correct operation
if the notes regarding Input above are followed. Alternatively, both parameters
can be passed as dataframes or matrices as long as they are fitting the expected
input layout.

Next will be four optional arguments found also within the already published
HarmonizR:

-   `algorithm`

-   `ComBat_mode`

-   `plot`

-   `output_file`

The first optional argument is the algorithm of choice. `ComBat` will be used
by default, but using the parameter `algorithm`, either `"ComBat"` or `"limma"`
can be chosen for data adjustment. `"ComBat"` serves as the default. The second
optional argument is `ComBat_mode`. This parameter is only valid once 
`ComBat` is chosen for the adjustment.

The `ComBat` mode is abbreviated for simplicity by using integers:

```
ComBat_mode     Corresponding ComBat Arguments

1 (default)     par.prior = TRUE, mean.only = FALSE

2               par.prior = TRUE, mean.only = TRUE

3               par.prior = FALSE, mean.only = FALSE

4               par.prior = FALSE, mean.only = TRUE
```

Please refer to the `ComBat` documentation for further details.

The third optional parameter is `plot`. `plot` can be set to either
`"samplemeans"`, `"featuremeans"` or `"CV"` and will show a boxplot with a box
for each batch depicting the chosen method. This plot will also be saved to a
.pdf. This will be either the mean for all samples, the mean for all features
or the coefficient of variation. There will be a separate plot for the original,
unaltered input dataset and for the `ComBat`/`limma` adjusted dataset. By
default, this parameter is turned off. Since a log transformation is assumed,
this will also be accounted for before plotting. Trying to plot data that has
not been log transformed prior may lead to an unplottable result. 

The fourth optional parameter is `output_file`. Setting this parameter will
grant the user the ability to choose the name of their output .tsv file. Also,
a path can be set. A string is expected as input. This parameter will default to
`"cured_data"`, yielding a file called `cured_data.tsv`.

Further, the five new parameters will be explained one-by-one:

-   `sort`

`sort` takes one of three available sorting algorithms as input. Either 
`"sparcity_sort"`, for a sparcity-based sorting, `"seriation_sort"`, using the
`seriation` package and `"jaccard_sort"`, using a Jaccard-index-based sorting
approach. Sorting happens prior to the adjustment and may change the way
blocking is executed on the data. Sorting does not yield any benefit when the
`block` parameter is unused.

-   `block`

`block` takes an integer as input which dictates, how many batches should be
packed together during matrix dissection. This parameter may greatly reduce
the amount of sub-dataframes produced and therefore decrease the algorithm’s
runtime.

-   `verbosity`

`verbosity` takes an integer with the lowest accepted integer being `0`. The
higher the number, the more feedback will the HarmonizR provide in the
command line. A verbosity of `1` is the default and should be sufficient. `0` or
`"mute"` will prevent HarmonizR from showing anything in the command line.

-   `cores`

`cores` gives the user the ability to control the number of cores used by their
machine during HarmonizR execution. By default, all available cores will be
used.

-   `ur`

`ur`, short for unique removal, can be set to either `TRUE` or `FALSE` to
toggle the newly implemented removal of unique combinations for increased
feature rescue. By default, this feature is applied, and it is strongly
suggested to not turn it off. The parameter is available for result
reproducibility.


## Session Information

```{r}
sessionInfo()
```