---
title: "Getting started with PRONE"
author: 
- name: Lis Arend
bibliography: references.bib
biblio-style: apalike
link-citation: yes
colorlinks: yes
output: 
  bookdown::html_document2:
    toc: true
    toc_depth: 2
    number_sections: true
    fig_caption: true
pkgdown:
  as_is: true
vignette: >
  %\VignetteIndexEntry{1. Getting started with PRONE}
  %\VignetteEngine{knitr::rmarkdown}
  \usepackage[utf8]{inputenc}
---

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>", message = TRUE, warning = FALSE,
  fig.width=8,
  fig.height =6
)
```

# Introduction

High-throughput omics data are often affected by systematic biases
introduced throughout all the steps of a clinical study, from sample
collection to quantification. Failure to account for these biases can
lead to erroneous results and misleading conclusions in downstream
analysis. Normalization methods aim to adjust for these biases to make
the actual biological signal more prominent. However, selecting an
appropriate normalization method is challenging due to the wide range of
available approaches. Therefore, a comparative evaluation of
unnormalized and normalized data is essential in identifying an
appropriate normalization strategy for a specific data set. This R
package provides different functions for preprocessing, normalizing, and
evaluating different normalization approaches. Furthermore,
normalization methods can be evaluated on downstream steps, such as
differential expression analysis and statistical enrichment analysis.
Spike-in data sets with known ground truth and real-world data sets of
biological experiments acquired by either tandem mass tag (TMT) or
label-free quantification (LFQ) can be analyzed.

# Installation

```{r loading, eval = FALSE}
# Official BioC installation instructions
if (!require("BiocManager", quietly = TRUE))
    install.packages("BiocManager")

BiocManager::install("PRONE")
```

```{r, message = FALSE}
# Load and attach PRONE
library(PRONE)
```

# Workflow

A six-step workflow was developed in R version 4.2.2 to evaluate the
effectiveness of the previously defined normalization methods on
proteomics data. The workflow incorporates a set of novel functions and
also integrates various methods adopted by state-of-the-art tools.

```{r, echo=FALSE, fig.cap="Six-step workflow of PRONE.", out.width="700px"}
knitr::include_graphics("../man/figures/Workflow_PRONE.png")
```

Following the upload of the proteomics data into a SummarizedExperiment
object, proteins with too many missing values can be removed, outlier
samples identified, and normalization carried out. Furthermore, an
exploratory analysis of the performance of normalization methods can be
conducted. Finally, differential expression analysis can be executed to
further evaluate the effectiveness of normalization methods. For data
sets with known ground truth, such as spike-in and simulated data sets,
performance metrics, such as true positives (TPs), false positives
(FPs), and area under the curve (AUC) values, can be computed. The
evaluation of DE results of real-world experiments is based on visual
quality inspection, for instance, using volcano plots, and an
intersection analysis of the DE proteins of different normalization
methods is available.

# Usage

This guide serves as an introduction to the PRONE R package, designed to facilitate the preparation of your data set for utilization of the PRONE package's functionalities. It begins by delineating the underlying data structure essential for the application of the package, followed by a brief description of how to apply different normalization techniques to your data. Additionally, this tutorial shows how to export the normalized data at the end.

Beyond the scope of this introductory tutorial, PRONE encompassess a broad spectrum of functionalities, ranging from preprocessing steps, imputation, normalization and evaluation of the performance of different normalization techniques, to the identification of differentially expressed proteins. These functionalities are detailed in dedicated vignettes, offering detailed insights and instructions for leveraging full capabilities of the PRONE package:

* [Preprocessing Tutorial](Preprocessing.html)
* [Imputation Tutorial](Imputation.html)
* [Normalization Tutorial](Normalization.html)
* [Differential Expression Tutorial](Differential_Expression.html)

Furthermore, PRONE provides additional functionalities for the analysis of spike-in data sets, which are detailed in the following vignette:

* [Spike-In Tutorial](Spike_In_Data.html)

# Load Data

PRONE uses the [SummarizedExperiment](https://bioconductor.org/packages/release/bioc/html/SummarizedExperiment.html) class as storage for protein intensities and meta data information on the proteomics data set. Hence, before being able to execute the functionalities of PRONE, the data needs to be saved accordingly. For this, the `load_data()` function was implemented and requires different parameters which are explained in the following: 

* __data__: refers to the data.frame containing the protein intensities
* __md__: refers to the data.frame containing the meta-data information
* __protein_column__: refers to the column in the data frame that contains the protein IDs
* __gene_column__ (optional): refers to the column in the data frame that contains the gene IDs
* __condition_column__ (optional): refers to the column in the meta-data table that contains the condition information - this can also be specified later
* __label_column__ (optional): refers to the column in the meta-data table that contains sample label information - sometimes the sample names are very long and this column gives the option to label the samples with shorter names for visualization purposes

If you have a tandem mass tag (TMT) data set with samples being measured in different batches than you have to specify the batch information. If reference samples were included in each batch, then additionally specify the samples names of the reference samples.

* __batch_column__ (optional): refers to the column in the meta-data table that contains the batch information
* __ref_samples__ (optional): refers to the samples that should be used as reference samples for normalization

<b>Attention:</b> You need to make sure that the sample names are saved in a column named "Column" in the meta-data table and are named accordingly in the protein intensity table.

## Example 1: TMT Data Set

The example TMT data set originates from [@biadglegne_mycobacterium_2022].

```{r load_real_tmt}
data_path <- readPRONE_example("tuberculosis_protein_intensities.csv")
md_path <- readPRONE_example("tuberculosis_metadata.csv")

data <- read.csv(data_path)
md <- read.csv(md_path)

md$Column <- stringr::str_replace_all(md$Column, " ", ".")

ref_samples <- md[md$Group == "ref",]$Column

se <- load_data(data, md, protein_column = "Protein.IDs", 
                gene_column = "Gene.names", ref_samples = ref_samples, 
                batch_column = "Pool", condition_column = "Group", 
                label_column = "Label")

```

## Example 2: Label-free (LFQ) Data Set

The example data set originates from [@vehmas_liver_2016]. This data set is used for the subsequent examples in this tutorial.

```{r load_real_lfq}
data_path <- readPRONE_example("mouse_liver_cytochrome_P450_protein_intensities.csv")
md_path <- readPRONE_example("mouse_liver_cytochrome_P450_metadata.csv")

data <- read.csv(data_path, check.names = FALSE)
md <- read.csv(md_path)

se <- load_data(data, md, protein_column = "Accession", 
                gene_column = "Gene names", ref_samples = NULL, 
                batch_column = NULL, condition_column = "Condition", 
                label_column = NULL)
```

# Data Structure

The SummarizedExperiment object contains the protein intensities as "assay", the meta-data table as "colData", and additional columns for instance resulting from MaxQuant as "rowData". Furthermore, information on the different columns, for instance, which columns contains the batch information, can be found in the "metadata" slot.

```{r}
se
```

The different data types can be accessed by using the `assays()` function. Currently, only the raw data and log2-transformed data are stored in the SummarizedExperiment object.

```{r}
assays(se)
```

# Preprocessing, Imputation, Normalization, Evaluation, and Differential Expression

As already mentioned in the introduction section, many functionalities are available in PRONE. All these functionalities are mainly based on the SummarizedExperiment object.

In this tutorial, we will only perform simple normalization of the data using median and LoessF normalization. 

```{r}
se <- normalize_se(se, c("Median", "LoessF"))
```

The normalized intensities will be saved as additional assays in the SummarizedExperiment object.

```{r}
assays(se)
```

Again, more information on the individual processes can be find in dedicated vignettes.

# Download Data

Finally, you can easily download the normalized data by using the `export_data()` function. This function will save the specified assays as CSV files and the SummarizedExperiment object as an RDS file in a specified output directory. Make sure that the output directory exists.

```{r, eval = FALSE}
if(!dir.exists("output/")) dir.create("output/")

export_data(se, out_dir = "output/", ain = c("log2", "Median", "LoessF"))
```

# Session Info

```{r}
utils::sessionInfo()
```

# References