---
title: "Amendments in pepr"
author: "Michal Stolarczyk"
date: "`r Sys.Date()`"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Amendments in pepr}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

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

# Learn amendments in `pepr`

This vignette will show you how and why to use the amendments functionality of the `pepr` package. 

 - basic information about the PEP concept on the [project website](https://pep.databio.org/).

 - broader theoretical description in the amendments [documentation section](https://pep.databio.org/spec/specification/#project-attribute-amendments).


## Problem/Goal

The example below demonstrates how and why to use amendments project attribute to, e.g. **define numerous similar projects in a single project config file**. This functionality is extremely convenient when one has to define projects with small settings discreptancies, like different attributes in the annotation sheet. For example libraries `ABCD` and `EFGH` instead of the original `RRBS`.

```{r ,echo=FALSE, warning=FALSE, message=FALSE}
branch = "master"
library(knitr)
library(pepr)
sampleAnnotation = system.file(
"extdata",
paste0("example_peps-", branch),
"example_amendments1",
"sample_table.csv",
package = "pepr"
)
sampleAnnotationDF = read.table(sampleAnnotation, sep = ",", header = T)
knitr::kable(sampleAnnotationDF, format = "html") 
```

----

## Solution

This can be achieved by using amendments section of `project_config.yaml` file (presented below). The attributes specified in the lowest levels of this section (here: `sample_table`) overwrite the original ones. Consequently, a completely new set of settings is determined with just this value changed. Moreover, multiple amendments can be defined in a single config file *and* activated at the same time. Based on the file presented below, two subprojects will be defined: `newLib` and `newLib2`.

```{r, echo=FALSE,message=TRUE,collapse=TRUE,comment=" "}
projectConfig = system.file(
"extdata",
paste0("example_peps-", branch),
"example_amendments1",
"project_config.yaml",
package = "pepr"
)
.printNestedList(yaml::read_yaml(projectConfig))
```

Obviously, the amendments functionality can be combined with other `pepr` package options, e.g. imply and derive sample modifiers. The derive modifier is used in the example considered here (`derive` key in the `sample_modifiers` section of the config file).


Files `sample_table_newLib.csv` and `sample_table_newLib2.csv` introduce different the `library` attributes. They are used in the subprojects `newLib` and `newLib2`, respectively.

```{r ,echo=FALSE}
sampleAnnotation = system.file(
  "extdata",
  paste0("example_peps-", branch),
  "example_amendments1",
  "sample_table_newLib.csv",
  package = "pepr"
  )
  sampleAnnotationDF = read.table(sampleAnnotation, sep = ",", header = T)
  knitr::kable(sampleAnnotationDF, format = "html") 
```

```{r ,echo=FALSE}
sampleAnnotation = system.file(
"extdata",
paste0("example_peps-", branch),
"example_amendments1",
"sample_table_newLib2.csv",
package = "pepr"
)
sampleAnnotationDF = read.table(sampleAnnotation, sep = ",", header = T)
knitr::kable(sampleAnnotationDF, format = "html") 
```

----

## Code

Load `pepr` and read in the project metadata by specifying the path to the `project_config.yaml`:

```{r}
projectConfig = system.file("extdata", paste0("example_peps-", branch),"example_amendments1", "project_config.yaml", package="pepr")
p=Project(projectConfig)
```
An appropriate message is displayed, which informs you what are the names of the amendments that you have defined in the `project_config.yaml` file. Nontheless, just the main project is "active".

Let's inspect it:

```{r}
sampleTable(p)
```

The column `file_path` was derived and the `library` column holds the original attributes: `RRBS` for each sample.

To "activate" any of the amendments just pass the names of the desired amendments to the `amendments` argument in the `Project` object constructor. 

In case you don't remember the subproject names run the `listAmendments()` metohods on the `Project` object, just like that:

```{r}
listAmendments(p)
```


```{r}
pNewLib = Project(file = projectConfig, amendments = "newLib")
```

Let's inspect it:

```{r}
sampleTable(pNewLib)
```

As you can see, the `library` columns consists of new attributes (`ABCD`), which were defined in the `sample_table_newLib.csv` file.

Amendments can be also activated interactively, after `Project` object has been crated. Let's activate the second amendment this way:

```{r}
pNewLib2 = activateAmendments(p, "newLib2")
sampleTable(pNewLib2)
```

What is more, the `p` object consists of all the information from the project config file (`project_config.yaml`). Run the following line to explore it:

```{r}
config(p)
```