---
title: "Introduction to prolfqua"
author:
  - name: Witold E. Wolski
    affiliation: Functional Genomics Center Zurich (FGCZ), ETH Zurich and University of Zurich
  - name: Christian Panse
    affiliation: Functional Genomics Center Zurich (FGCZ), ETH Zurich and University of Zurich
package: prolfqua
output: BiocStyle::html_document
vignette: >
  %\VignetteIndexEntry{Introduction to prolfqua}
  %\VignetteEncoding{UTF-8}
  %\VignetteEngine{knitr::rmarkdown}
bibliography:
  - prolfqua.bib
---

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

# Introduction

prolfqua covers the steps of a label-free quantification (LFQ) proteomics analysis: quality control, normalization, aggregation of peptides to proteins, modelling, hypothesis testing and sample size estimation [@Wolski2022.06.07.494524].

The package works with data in long format, one row per measured feature (protein, peptide, precursor) and sample. Three building blocks carry an analysis:

- `AnalysisConfiguration` maps the columns of the table to their roles: the feature hierarchy (protein, peptide, ...), the explanatory factors, the sample and the intensity column.
- `LFQData` holds the data together with its configuration. Its methods return helpers for transformation (`get_Transformer()`), aggregation (`get_Aggregator()`), summary statistics (`get_Stats()`), missing-value summaries (`get_Summariser()`) and plots (`get_Plotter()`).
- `build_contrast_analysis()` fits a model per protein and computes the requested contrasts. The `method` argument selects the model: linear models (`lm`, `rlm`, `rfit`), limma and limma-voom, DEqMS variance moderation, Firth logistic regression for presence/absence, mixed models and ROPECA on peptide-level data, and variants that impute groups without observations at the limit of detection.

Every method returns an object with the same interface: `get_contrasts()`, `get_Plotter()`, `get_missing()` and `to_wide()`. Results of different methods therefore have the same columns and can be compared or combined directly.

# Installation

Install prolfqua from Bioconductor with:

```{r install, eval = FALSE}
if (!requireNamespace("BiocManager", quietly = TRUE)) {
  install.packages("BiocManager")
}
BiocManager::install("prolfqua")
```

The development version is available on GitHub:

```{r install-dev, eval = FALSE}
BiocManager::install("fgcz/prolfqua")
```

# Quick start

We simulate peptide-level intensities for 100 proteins measured in three groups (`A`, `B` and `Ctrl`). `sim_lfq_data_peptide_config()` returns the data together with a matching `AnalysisConfiguration`.

```{r simulate}
library(prolfqua)
istar <- sim_lfq_data_peptide_config(Nprot = 100, seed = 1234)
lfqdata <- LFQData$new(istar$data, istar$config)
lfqdata$factors() |> head()
```

We $\log_2$ transform the intensities, scale them robustly, and aggregate the peptides to proteins with Tukey's median polish.

```{r transform}
lfqdata <- lfqdata$get_Transformer()$log2()$robscale()$lfq
lfqprot <- lfqdata$get_Aggregator()$aggregate()
```

```{r density, fig.cap = "Distribution of the normalized protein intensities per sample."}
lfqprot$get_Plotter()$intensity_distribution_density()
```

We compare groups `A` and `B` with the control group, using limma's moderated linear model.

```{r contrasts}
contrasts <- c(
  "A_vs_Ctrl" = "group_A - group_Ctrl",
  "B_vs_Ctrl" = "group_B - group_Ctrl"
)
fa <- build_contrast_analysis(lfqprot, "~ group_", contrasts, method = "limma")
res <- fa$get_contrasts()
head(res[, c("protein_Id", "contrast", "diff", "p.value", "FDR")])
```

```{r volcano, fig.cap = "Volcano plot of the two contrasts."}
fa$get_Plotter()$volcano()$FDR
```

All available methods are listed by `list_facades()`:

```{r facades}
names(list_facades())
```

# Further documentation

The package website <https://fgcz.github.io/prolfqua/> holds the full set of tutorials:

- [Comparing two groups](https://fgcz.github.io/prolfqua/articles/Comparing2Groups.html): QC, normalization, linear models and moderated contrasts
- [Creating configurations](https://fgcz.github.io/prolfqua/articles/CreatingConfigurations.html): reading your own data into an `AnalysisConfiguration`
- [QC and sample size estimation](https://fgcz.github.io/prolfqua/articles/QualityControlAndSampleSizeEstimation.html)
- [Contrast facades with parallel designs](https://fgcz.github.io/prolfqua/articles/ContrastFacades.html): all `build_contrast_analysis()` methods side by side
- [Contrast facades with a two-factor design](https://fgcz.github.io/prolfqua/articles/ContrastFacade2Factor.html)
- [Modelling a dataset with two factors](https://fgcz.github.io/prolfqua/articles/Modelling2Factors.html)
- [Contrasts from factors](https://fgcz.github.io/prolfqua/articles/Contrasts_from_factors.html)
- [Limma backend](https://fgcz.github.io/prolfqua/articles/LimmaBackend.html)
- [DEqMS count-dependent variance moderation](https://fgcz.github.io/prolfqua/articles/DEqMS_Moderation.html)
- [Using limpa](https://fgcz.github.io/prolfqua/articles/limpa_example.html)
- [Simulating peptide-level data](https://fgcz.github.io/prolfqua/articles/SimulateData.html)
- [Imputing data at the limit of detection](https://fgcz.github.io/prolfqua/articles/TestingMissingInference.html)

The vignette [Comparing two groups with prolfqua](Comparing2Groups.html) is also part of this package.

# Session info

```{r session-info}
sessionInfo()
```

# References