---
title: "MACSQuantifyR - Step-by-step analysis"
author:
- name: Raphaël Bonnet, Jean-François Peyron 
  email: raphael.bonnet@unice.fr
  affiliation: Université Côte d’Azur, Inserm, C3M, France 
date: "`r Sys.Date()`"
output:
    prettydoc::html_pretty:
        theme: cayman
        toc: true
        css: MACSQuantifyR.css
bibliography: REFERENCES.bib
csl: clinical-pharmacology-and-therapeutics.csl
vignette: >
    %\VignetteIndexEntry{MACSQuantifyR_step_by_step_analysis}
    %\VignetteEngine{knitr::rmarkdown}
    %\VignetteEncoding{UTF-8}
---

```{r setup, include = FALSE}
knitr::opts_chunk$set(
    fig.width = 8,
    fig.height = 8
)
```

```{r, echo = FALSE, fig.width=10, fig.height=8,fig.asp=0.6}
library(png)
library(grid)
path_intro <- system.file("extdata", "manual.png", package = "MACSQuantifyR")
intro <- readPNG(path_intro)
grid.raster(intro)
```

# Introduction 

This is an example of how to run MACSQuantifyR with combination drug analysis.
To know more about the package, have a look at the [introduction 
vignette](MACSQuantifyR.html)

In this vignette we will run the MACSQuantifyR package on the example given 
in the introduction of the previous vignette.
More precisely, this experiment corresponds to the screening 
of the combination effects of two drugs on human cells. 


Here is the plate template chosen by the user that represents drugs alone 
(up part of the well plate) and combinations (low part of the well plate).

```{r, echo = FALSE}
path_img1 <- system.file("extdata", "combo.png", package = "MACSQuantifyR")
img1 <- readPNG(path_img1)
grid.raster(img1)
```


# Pipeline

Load the packages 
```{r load}
library(MACSQuantifyR)
library(knitr)
library(grid)
library(gridExtra)
library(ggplot2)
library(tools)
library(readxl)
library(lattice)
library(latticeExtra)
suppressMessages(library(R.utils))
```


## Create a new object MACSQuant: new_class_MQ() 

---

---

This function allows the user to create a new object of class MACSQuant.

This will allow the user to set specific options regarding the experiment and
the output of some functions before running other functions. 

---

---

* Create the MACSQuant object:

```{r}
MACSQuant <- new_class_MQ(path = "output_path")
```


* Define experiment name:

```{r}
slot(MACSQuant, "experiment_name") <- "Combo drug1-drug2 HC line 101"
```


* Define output path:

`slot(MACSQuant,"param.output")$path`


## Import your data: load_MACSQuant()


Once the excel file has been generated by miltenyi 
MACSQuantify software. The user can load the data with the 
following function.

It will generate a variable called my_data, 
necessary for the next steps of the analysis.

Load the data: 

```{r load_file, include = TRUE}
filepath <- system.file("extdata", "drugs.xlsx",
    package = "MACSQuantifyR")
MACSQuant <- load_MACSQuant(filepath,
    sheet_name = "combo_drugs",
    MACSQuant.obj = MACSQuant)
```

## Sort your replicates: on_plate_selection()

---

---

By calling the function on_plate_selection() with the number 
of conditions in the experiment and the number of replicates
by conditions, the user will be asked to select sequentially 
the replicates for each conditions. 

Before running the function, 
the user can define one of the experiment parameters called 
c_names in which condition names are stored.

---

---

Experiment parameters are:

* c_names: condition names to plot

`slot(MACSQuant,"param.experiment")$c_names`


* doses: colors for the barplots

`slot(MACSQuant,"param.experiment")$doses`


```{r}
# this line is used to created c_names variable
# for this experiment according to selection
slot(MACSQuant, "param.experiment")$c_names <-
    c(sprintf("Drug1_c%d", 1:4), # DRUG1 ALONE
        sprintf("Drug2_c%d", 1:3), # DRUG2 ALONE
        sprintf("D2[1]_D1[%d]", 1:4), # DRUG2_C1 + DRUG1_Cs
        sprintf("D2[2]_D1[%d]", 1:4), # DRUG2_C2 + DRUG1_Cs
        sprintf("D2[3]_D1[%d]", 1:4)) # DRUG2_C3 + DRUG1_Cs

# custom colors can be defined (with control if selected)
plt.col <- c(heat.colors(length(slot(MACSQuant, "param.experiment")$c_names)),
    1)

# dose vector of concentration each condition
slot(MACSQuant, "param.experiment")$doses <-
    c(1, 3, 5, 10, # DRUG1 ALONE
        0, 0, 0,                  # DRUG2 ALONE
        1, 3, 5, 10, # DRUG2_C1 ++ DRUG1_Cs
        1, 3, 5, 10, # DRUG2_C2 + DRUG1_Cs
        1, 3, 5, 10  # DRUG2_C3 + DRUG1_Cs
    )
slot(MACSQuant, "param.experiment")$doses.alt <-
    c(0, 0, 0, 0,                # DRUG1 ALONE
        10, 50, 100,              # DRUG2 ALONE
        10, 10, 10, 10,            # DRUG2_C1 + DRUG1_Cs
        50, 50, 50, 50,            # DRUG2_C2 ++ DRUG1_Cs
        100, 100, 100, 100          # DRUG2_C3 ++ DRUG1_Cs
    )
```

The function is ready to run:
```{r,eval=FALSE}

MACSQuant <- on_plate_selection(MACSQuant,
    number_of_replicates = 3,
    number_of_conditions = 19,
    control = TRUE,
    save.files = TRUE)
```

Once the replicates of all conditions have been identified by the user, 
the on_plate_selection function will automatically reorder the data stored 
in the variable my_data into a new variable called my_data_sorted. 

During the process of sorting replicates basic statistical analysis 
for each condition is done (mean and standard deviation of replicates).

This will generate a new variable called statistics necessary for the 
next part of the pipeline. 

##  2D/3D data representation: barplot_data()

---

---

This function allows the user to generate 2D and 3D plots corresponding
to two flavours (cell counts, percentages).

Before running the function, 
the user can define one of the experiment parameters


---

---

flavours are:

* `counts`: cell count

* `percent`: fluorochrome positive cell percentage

Output.parameters are:

are:

* plt.title: Barplot title

`slot(MACSQuant,"param.output")$plt.title` this will be used as
subtitle for the Word document.


* plt.labels: Barplot labels

`slot(MACSQuant,"param.output")$plt.labels`


* the user can also load specific colors:

```{r,include=F}
filepath <- system.file("extdata", "drugs.Rdata",
    package = "MACSQuantifyR")
load(filepath)
```

```{r}
plt.col <-
    c(
        heat.colors(length(slot(MACSQuant, "param.experiment")$c_names)), 1)

plt.labels <- c(slot(MACSQuant, "param.experiment")$c_names, "Control")

slot(MACSQuant, "param.output")$plt.title <- "Custom title example"
```

The barplot_data() function is ready to run

```{r,fig.width=31.75,  fig.height=15.875,fig.asp=0.5,fig.asp=0.5}
flav <- "counts"
p_counts <- barplot_data(MACSQuant,
    plt.col = plt.col,
    plt.flavour = flav,
    plt.labels = plt.labels,
    plt.combo = TRUE,
    xlab = "Drug1",
    ylab = "Drug2")
grid.arrange(p_counts)


flav <- "percent"
p_percent <- barplot_data(MACSQuant,
    plt.col = plt.col,
    plt.flavour = flav,
    plt.labels = plt.labels,
    plt.combo = TRUE,
    xlab = "Drug1",
    ylab = "Drug2")
grid.arrange(p_percent)
```
Save the generated plots else they will not appear 
in the excel document:

```{r eval =FALSE}
# flav='counts'
ggsave(paste(MACSQuant@param.output$path,
    "/outputMQ/barplot_", flav, ".png", sep = ""),
width = 31.75, height = 15.875,
units = "cm", p_counts)
# flav='percent'
ggsave(paste(MACSQuant@param.output$path,
    "/outputMQ/barplot_", flav, ".png", sep = ""),
width = 31.75, height = 15.875,
units = "cm", p_percent)
```


## Combination index computation: combination_index() 

---

---

This function allows the user to compute combination index as computed by
Chou TC, Pharmacol Rev. 2006[@chou2006theoretical].

Four plots are generated by this function:

* The dose response plot for drugs alone
* The median effect plot (log dose vs log(response/1-response))
* The normalized isobologram with synergism decision
* The 3D barplot with synergy corresponding color code

---

---


```{r}
MACSQuant <- combination_index(MACSQuant)
```

## Report generation: generate_report()

---

---

This function uses all the files saved during the analysis 
(argument <span style="color:red">save.files=T</span>).

The save.files option creates a folder called outputMQ 
in your current directory (default) or at specified 
path and save: 

* The well plate template image (plate_template.png)
* The sorted_replicates data table (sorted_table.txt)
* The statistic table (statistics.txt)
* Plots barplot_counts, barplot_percent
* Any other generated plots

Be careful to avoid overriding data, content of 
existing outputMQ folder could be erased. 

---

---

You can run generate_report at any steps of the pipeline to generate the 
Word document named results.docx.

```{r,eval=FALSE}
generate_report(MACSQuant)
```




# Links

* You can find an example of the report generated
by the step-by-step analysis() 
at this address: https://github.com/Peyronlab/MACSQuantifyR


* Also a version of this package is available as an excel 
macro at this address:
https://github.com/Peyronlab/MACSQuantifyXL

# Reference

