--- 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: All information regarding the upcoming sections can also be found within our SOP on Github, which is found under the following link: . 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 ( 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 (). 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() ```