---
title: "gDRplots"
author: "gDR team"
output: BiocStyle::html_document
vignette: >
  %\VignetteIndexEntry{gDRplots}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

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

```{r lib, echo=FALSE}
library(gDRplots)
library(gDRutils)
```

# Overview

The `gDRplots` package belongs to the `gDR` suite app.

# Content

The `gDRplots` package stores functions for gDR static visualizations and their dedicated helpers. The package allows users to visualize different metrics for combinations of drugs and cell lines of interest, both during and after processing.

The `gDRplots` package supports the following metrics:

| Metrics | Definition |
| ---- | ---------- |
| **GR value** | Normalized Growth Rate (GR) value; calculated by normalizing treated samples with the corresponding vehicle-treated samples. |
| **Relative Viability** | (RV); calculated by normalizing treated samples with the corresponding vehicle-treated samples. |


**Assumptions**

1. input data

All plot functions require as an input `data.table` representation of the data in selected assay with added information from `colData` created based on the gDR data model (MultiAssayExperiment). such format is provided by the `gDRutils::convert_se_assay_to_dt` function.

More details about the gDR data model user can find in the [gDRcore](https://www.bioconductor.org/packages/release/bioc/html/gDRcore.html){target="_blank"} package.

2. function naming convention

If a function is dedicated to only one type of experiment - it will be marked in the name with the symbol **sa** for an experiment with a single-agent (e.g. `pheatmap_with_anno_sa`)
or **combo** - for a combined experiment (e.g. `pheatmap_with_anno_combo`).

3. function output

Basically all functions return **a ggplot object**, except for a few that return **a pheatmap object**. But this is indicated in the function names and description, e.g. `pheatmap_qc`, `pheatmap_with_anno_sa`, and `pheatmap_with_anno_combo`.

There is a group of functions that return **a panel** with a group of basic plots. The name of these functions always contains a word **panel**. E.g. a basic ggplot object - <u>one heatmap</u> for selected drug, co-drug and one cell line - is returned by `heatmap_combo_with_isoref`. And `heatmap_combo_with_isoref_panel` returns a ggplot object with <u>a panel with heatmaps</u> for selected drug, co-drug and list of cell lines.


<u>Used data</u>:

* single-agent experiment (synthetic data)
```{r sa_data, warning = FALSE, message = FALSE}
mae <- get_synthetic_data("combo_matrix")
sa_name <- get_supported_experiments("sa")
se_sa <- mae[[sa_name]]

dt_norm_sa <-
  convert_se_assay_to_dt(se = se_sa,
                         assay_name =  "Normalized",
                         unify_metadata = TRUE,
                         merge_additional_variables = TRUE)
dt_metrics_sa <-
  convert_se_assay_to_dt(se = se_sa,
                         assay_name = "Metrics",
                         unify_metadata = TRUE,
                         merge_additional_variables = TRUE)
dt_average_sa <-
  convert_se_assay_to_dt(se = se_sa,
                         assay_name = "Averaged",
                         unify_metadata = TRUE,
                         merge_additional_variables = TRUE)
dt_metrics_sa_capped <-
  cap_assay_infinities(conc_assay_dt = dt_average_sa,
                       assay_dt = dt_metrics_sa,
                       experiment_name = sa_name,
                       col = "xc50",
                       capping_fold = 5)
```

* codilution experiment (synthetic data)
```{r cd_data, warning = FALSE, message = FALSE}
mae <- get_synthetic_data("combo_codilution_small")
cd_name <- get_supported_experiments("cd")
se_cd <- mae[[cd_name]]

dt_norm_cd <-
  convert_se_assay_to_dt(se = se_cd,
                         assay_name =  "Normalized",
                         unify_metadata = TRUE,
                         merge_additional_variables = TRUE)
dt_metrics_cd <-
  convert_se_assay_to_dt(se = se_cd,
                         assay_name = "Metrics",
                         unify_metadata = TRUE,
                         merge_additional_variables = TRUE)
dt_average_cd <-
  convert_se_assay_to_dt(se = se_cd,
                         assay_name = "Averaged",
                         unify_metadata = TRUE,
                         merge_additional_variables = TRUE)
```

* combination experiment (synthetic data)
```{r combo_data, warning = FALSE, message = FALSE}
mae <- get_synthetic_data("combo_matrix")
combo_name <- get_supported_experiments("combo")
se_combo <- mae[[combo_name]]

dt_norm_combo <-
  convert_se_assay_to_dt(se = se_combo,
                         assay_name =  "Normalized",
                         unify_metadata = TRUE,
                         merge_additional_variables = TRUE)
dt_metrics_combo <-
  convert_se_assay_to_dt(se = se_combo,
                         assay_name = "Metrics",
                         unify_metadata = TRUE,
                         merge_additional_variables = TRUE)
dt_average_combo <-
  convert_se_assay_to_dt(se = se_combo,
                         assay_name = "Averaged",
                         unify_metadata = TRUE,
                         merge_additional_variables = TRUE)
dt_scores <-
  convert_se_assay_to_dt(se = se_combo,
                         assay_name = "scores",
                         unify_metadata = TRUE,
                         merge_additional_variables = TRUE)
dt_excess <-
  convert_se_assay_to_dt(se = se_combo,
                         assay_name = "excess",
                         unify_metadata = TRUE,
                         merge_additional_variables = TRUE)
dt_isobolograms <-
  convert_se_assay_to_dt(se = se_combo,
                         assay_name = "isobolograms",
                         unify_metadata = TRUE,
                         merge_additional_variables = TRUE)
```

* single-agent experiment for PRISM data
```{r sa_prism_data, warning = FALSE, message = FALSE}
mae_prism <- get_synthetic_data("prism")
sa_name <- get_supported_experiments("sa")
se_sa_prism <- mae_prism[[sa_name]]

dt_norm_prism_sa <-
  convert_se_assay_to_dt(se = se_sa_prism,
                         assay_name =  "Normalized")
dt_metrics_prism_sa <-
  convert_se_assay_to_dt(se = se_sa_prism,
                         assay_name = "Metrics")
dt_average_prism_sa <-
  convert_se_assay_to_dt(se = se_sa_prism,
                         assay_name = "Averaged")
dt_metrics_prism_sa_capped <-
  cap_assay_infinities(conc_assay_dt = dt_average_prism_sa,
                       assay_dt = dt_metrics_prism_sa,
                       experiment_name = sa_name,
                       col = "xc50",
                       capping_fold = 5)
```

<br>

::: {.chunk .alert .alert-warning}
**TIP**<br>
It is highly recommended to use `convert_se_assay_to_dt` with 
`unify_metadata = TRUE` and `merge_additional_variables = TRUE`. This prevents 
errors caused by non-unique combinations of values in the `DrugName` and 
`CellLineName` columns.
:::

<br>

## Dose Response Plots

The dose-response plots are classic visualizations of drug response curves in a consolidated way.

The overview with many curves presented on the same scale gives the user a comprehensive view of the dataset. This is particularly useful in large compound screening datasets, where a drug with a universal resistance pattern across all cell lines can be easily identified. The compound generates different sigmoid curves, suggesting inhibitory or cytotoxic effects, which are worth exploring further.

### Single-agent Data

The **plot_dose_response_sa** function is dedicated to single-agent experiments.

Users can also use  **plot_dose_response_sa_by_CLs** or **plot_dose_response_sa_by_drugs** to get a list of dose-response plots by cell line names or by drugs accordingly.

```{r plot_dose_response_sa, warning = FALSE, message = FALSE}
plot_dose_response_sa(
  dt_metrics = dt_metrics_sa,
  dt_average = dt_average_sa,
  selection_name = "drug_002",
  group_var = "CellLineName",
  group_names = c("cellline_BC", "cellline_FD", "cellline_JE"))
```

### Combination Data

The **plot_dose_response_combo** function is dedicated to combination experiments.

Users can also use **plot_dose_response_combo_panel** to get a panel with dose-response plots by selected cell line name.

```{r plot_dose_response_combo, warning = FALSE, message = FALSE}
plot_dose_response_combo(
  dt_average = dt_average_combo,
  drug1_name = "drug_011",
  drug2_name = "drug_021",
  cl_name = "cellline_NE")
```

## Metrics plot

A heat map built for all combinations of drugs and cell lines, colored according to the value of the selected metric, is a very common way to explore datasets. Boxplots are also commonly used to explore the distribution of metric values across interest groups.

### Single-agent Data

The **pheatmap_with_anno_sa** function is dedicated to single-agent experiments to generate a heatmap.

Additionally, rows are annotated by `Tissue` and columns - by `drug MOA`. Users can also use their own annotations.

This function returns the heatmap itself and a list of tables with data: a matrix and annotation vectors.

```{r pheatmap_with_anno_sa, warning = FALSE, message = FALSE}
annotation_manual_col <-
  unique(dt_metrics_sa[, c("CellLineName", "Tissue"), with = FALSE])
annotation_manual_row <-
  unique(dt_metrics_sa[, c("DrugName", "drug_moa"), with = FALSE])

output <- pheatmap_with_anno_sa(
  dt_metrics = dt_metrics_sa,
  dt_metrics_capped = dt_metrics_sa_capped,
  annotation_row = annotation_manual_row,
  annotation_col = annotation_manual_col)
hm <- output[["heatmap"]]
patchwork::wrap_elements(hm[["gtable"]])

knitr::kable(output[["data"]][["matrix"]], escape = FALSE)
```


The **plot_boxplot_metric_sa_by_CLs** and **plot_boxplot_metric_sa_by_drugs** functions are dedicated to single-agent experiments to generate boxplots grouped by `CellLineName` or `DrugName`, respectively.

```{r plot_boxplot_metric_sa_by_CLs, warning = FALSE, message = FALSE}
plot_boxplot_metric_sa_by_CLs(dt_metrics_sa_capped)
```

```{r plot_boxplot_metric_sa_by_drugs, warning = FALSE, message = FALSE}
plot_boxplot_metric_sa_by_drugs(dt_metrics_sa_capped)
```

Additionally, user can colored boxplots by secondary variable - by `Tissue` or `drug MOA` respectively.

```{r plot_boxplot_metric_sa_by_CLs_group, warning = FALSE, message = FALSE}
plot_boxplot_metric_sa_by_CLs(dt_metrics_sa_capped,
                              grouped_flag = TRUE)
```

```{r plot_boxplot_metric_sa_by_drugs_group, warning = FALSE, message = FALSE}
plot_boxplot_metric_sa_by_drugs(dt_metrics_sa_capped,
                                grouped_flag = TRUE)
```

Or user can colored points by opposite primary variable - by `DrugName` or `CellLineName` respectively.

```{r plot_boxplot_metric_sa_by_CLs_pts, warning = FALSE, message = FALSE}
plot_boxplot_metric_sa_by_CLs(dt_metrics_sa_capped,
                              colored_pts_flag = TRUE)
```

```{r plot_boxplot_metric_sa_by_drugs_pts, warning = FALSE, message = FALSE}
plot_boxplot_metric_sa_by_drugs(dt_metrics_sa_capped,
                                colored_pts_flag = TRUE)
```

There is also a possibility to generate boxplot grouped by chosen variable for dedicated `DrugName` or `CellLineName`.
Additionally, the n-bottom points are colored.

```{r plot_boxplot_metric_sa_by_grp_d, warning = FALSE, message = FALSE}
plot_boxplot_metric_sa_by_grp(dt_metrics_sa_capped,
                              selection_var = "DrugName",
                              selection_name = "drug_002",
                              group_var = "Tissue",
                              named_n = 3)
```
```{r plot_boxplot_metric_sa_by_grp_cl, warning = FALSE, message = FALSE}
plot_boxplot_metric_sa_by_grp(dt_metrics_sa_capped,
                              selection_var = "CellLineName",
                              selection_name = "cellline_BC",
                              group_var = "drug_moa",
                              named_n = 3)
```

### Co-dilution Data

The **pheatmap_with_anno_cd** function is dedicated to co-dilution experiments to generate a heatmap.

Additionally, rows are annotated by `Tissue` and columns - by `drug MOA` and `drug MOA 2`. Users can also use their own annotations.

This function returns the heatmap itself and a list of tables with data: a matrix and annotation vectors.

```{r pheatmap_with_anno_cd, warning = FALSE, message = FALSE}
annotation_manual_col <-
  unique(dt_metrics_cd[, c("CellLineName", "Tissue"), with = FALSE])
annotation_manual_row <-
  unique(dt_metrics_cd[, c("DrugName", "DrugName_2", "Concentration_2",
                           "drug_moa", "drug_moa_2"), with = FALSE])

output <- pheatmap_with_anno_cd(
  dt_metrics = dt_metrics_cd,
  annotation_row = annotation_manual_row,
  annotation_col = annotation_manual_col)
hm <- output[["heatmap"]]
patchwork::wrap_elements(hm[["gtable"]])

knitr::kable(output[["data"]][["matrix"]], escape = FALSE)
```

### Combination Data

The **pheatmap_with_anno_combo** function is dedicated to combination experiments to generate a heatmap.

Additionally, rows are annotated by `Tissue` and columns - by `drug MOA` and `co-drug MOA`. Users can also use their own annotations.

This function returns the heatmap itself and a list of tables with data: a matrix and annotation vectors.

```{r pheatmap_with_anno_combo, warning = FALSE, message = FALSE}
annotation_manual_col <-
  unique(dt_scores[, c("CellLineName", "Tissue"), with = FALSE])
annotation_manual_row <-
  unique(dt_scores[, c("DrugName", "DrugName_2",
                       "drug_moa", "drug_moa_2"), with = FALSE])

output <- pheatmap_with_anno_combo(
  dt_scores = dt_scores,
  annotation_row = annotation_manual_row,
  annotation_col = annotation_manual_col)
hm <- output[["heatmap"]]
patchwork::wrap_elements(hm[["gtable"]])

knitr::kable(output[["data"]][["matrix"]], escape = FALSE)
```

The **plot_boxplot_metric_sa_by_CLs** and **plot_boxplot_metric_sa_by_drugs** functions are dedicated to single-agent experiments to generate boxplots grouped by `CellLineName` or combination of `DrugName` with `DrugName_2`, respectively.

Additionally, for boxplots grouped by `CellLineName` user can colored boxplots by secondary variable - by `Tissue`.

```{r plot_boxplot_metric_combo_by_CLs, warning = FALSE, message = FALSE}
plot_boxplot_metric_combo_by_CLs(dt_scores)
```

```{r plot_boxplot_metric_combo_by_drugs, warning = FALSE, message = FALSE}
plot_boxplot_metric_combo_by_drugs(dt_scores)
```

There is also a possibility to generate boxplot grouped by chosen variable for dedicated `DrugName` or `CellLineName`.
Additionally, the n-top points are colored.

```{r plot_boxplot_metric_combo_by_grp_d, warning = FALSE, message = FALSE}
plot_boxplot_metric_combo_by_grp(dt_scores,
                                 selection_var = "DrugName",
                                 selection_name = c("drug_002", "drug_026"),
                                 group_var = "Tissue",
                                 named_n = 3)
```

```{r plot_boxplot_metric_combo_by_grp_cl, warning = FALSE, message = FALSE}
plot_boxplot_metric_combo_by_grp(dt_scores,
                                 selection_var = "CellLineName",
                                 selection_name = "cellline_BC",
                                 group_var = "drug_moa_2",
                                 named_n = 3)
```

For experiments with drug combinations, users can visualize the full response matrix by using **heatmap_combo_metrics** function.

Users get at once a view with smooth value, HSA (highest single-agent) excess, or Bliss excess for selected normalization type across combinations of concentrations, with isobolograms overlaid. Further, the CI plot is also shown (the Combination Index is displayed at different ratios of the two drugs).

Users can also use **heatmap_combo_metrics_panel** to get a panel with heatmaps for all combo metrics, with isobolograms overlaid. The CI plot is also shown (the Combination Index is displayed at different ratios of the two drugs).

Note that by default, this function returns a panel, but it can also return a list with the panel's items (param `as_list = TRUE`).

```{r heatmap_combo_metrics_panel, warning = FALSE, message = FALSE}
heatmap_combo_metrics(dt_excess = dt_excess,
                      dt_isobolograms = dt_isobolograms,
                      drug1_name = "drug_001",
                      drug2_name = "drug_026",
                      cl_name = "cellline_NE",
                      iso_levels = "0.5",
                      metric = "smooth")

heatmap_combo_metrics(dt_excess = dt_excess,
                      dt_isobolograms = dt_isobolograms,
                      drug1_name = "drug_001",
                      drug2_name = "drug_026",
                      cl_name = "cellline_NE",
                      iso_levels = "0.5",
                      metric = "hsa_excess")

heatmap_combo_metrics(dt_excess = dt_excess,
                      dt_isobolograms = dt_isobolograms,
                      drug1_name = "drug_001",
                      drug2_name = "drug_026",
                      cl_name = "cellline_NE",
                      iso_levels = "0.5",
                      metric = "bliss_excess")
```

The **plot_combination_index** function allows users to explore the dose-sparing effects for experiments with drug combinations. The Combination Index is displayed at different ratios of the two drugs.

```{r plot_combination_index, warning = FALSE, message = FALSE}
plot_combination_index(dt_excess = dt_excess,
                       dt_isobolograms = dt_isobolograms,
                       drug1_name = "drug_001",
                       drug2_name = "drug_026",
                       cl_name = "cellline_NE",
                       iso_levels = c("0.2", "0.5", "0.8"))
```

The **heatmap_combo_with_isoref** function allows users to explore the reference isobolograms (additive Loewe model) compared to the measured isobolograms on the background of smooth value of normalization type.

Users can also use **heatmap_combo_with_isoref_panel** to get a panel with heatmap for selected drug name and co-drug name and list of cell line names.

```{r heatmap_combo_with_isoref, warning = FALSE, message = FALSE}
heatmap_combo_with_isoref(dt_excess = dt_excess,
                          dt_isobolograms = dt_isobolograms,
                          drug1_name = "drug_001",
                          drug2_name = "drug_026",
                          cl_name = "cellline_NE",
                          iso_levels = c("0.2", "0.5", "0.8"))
```


## Quality Control

This group of functions is very useful during processing raw data from experiments into the gDR model through the gDR pipeline (for more details visit [gDRcore article](https://www.bioconductor.org/packages/release/bioc/vignettes/gDRcore/inst/doc/gDRcore.html){target="_blank"}).

Users can control data quality at each processing step.

Also, when using the gDR model, the same control might be performed for the corresponding assay.


### Merging of Manifest, Treatment and Raw data using gDRimport

Before running the gDR pipeline, data are imported using the gDRimport package. This package facilitates the loading of data from Envision, Tecan, and other technologies. More information about the supported technologies and examples of how to import data can be found in our documentation.

The `plot_plate_stack_info` and `plot_plate` functions allow for visualizing the plate design of the experiment. The `plot_plate_stack_info` function shows all the plate information on a single plot, while the plot_plate function displays information for a single plate on the plot.


```{r plot_plate, warning = FALSE, message = FALSE, eval = FALSE}
# Load test data using gDRimport
td <- gDRimport::get_test_data()

# Load data from manifest, template, and results files
l_tbl <- gDRimport::load_data(
  manifest_file = gDRimport::manifest_path(td),
  df_template_files = gDRimport::template_path(td),
  results_file = gDRimport::result_path(td)
)

# Merge the manifest, treatments, and raw data
merged_data <- gDRcore::merge_data(
  l_tbl$manifest,
  l_tbl$treatments,
  l_tbl$data
)

# Visualize the plate design of the experiment
plate_stack_vis <- plot_plate_stack_info(merged_data)
plate_vis <- plot_plate(merged_data, "ReadoutValue")
plate_stack_vis[["201904197a"]]
plate_vis[["201904197a"]]
```
![](plate_stack_vis.png)
![](plate_vis.png)


### Mapping Controls to Treated

The first stage of the gDR pipeline involves dispatching the raw data and controls into the appropriate nested tables.

The **heatmap_control_mapping_qc** function is dedicated to single-agent, co-dilution and combination experiments.

It allows to visually check whether the raw data and the control are correct and have been correctly assigned and nothing is missing.

```{r heatmap_control_mapping_qc, warning = FALSE, message = FALSE}
dt_treat <-
  convert_se_assay_to_dt(se_sa,
                         assay_name = "RawTreated",
                         unify_metadata = TRUE,
                         merge_additional_variables = TRUE)
dt_controls <-
  convert_se_assay_to_dt(se_sa,
                         assay_name = "Controls",
                         unify_metadata = TRUE,
                         merge_additional_variables = TRUE)

heatmap_control_mapping_qc(dt_treat = dt_treat,
                           dt_controls = dt_controls)

dt_treat <-
  convert_se_assay_to_dt(se_combo,
                         assay_name = "RawTreated",
                         unify_metadata = TRUE,
                         merge_additional_variables = TRUE)
dt_controls <-
  convert_se_assay_to_dt(se_combo,
                         assay_name = "Controls",
                         unify_metadata = TRUE,
                         merge_additional_variables = TRUE)

heatmap_control_mapping_qc(dt_treat = dt_treat,
                           dt_controls = dt_controls)
```

### Degree of Errors in Normalization Values

In the gDR pipeline during the normalization stage, the raw data are normalized based on the control.

The **plot_var_distribution_qc** function is dedicated to single-agent, co-dilution and combination experiments.

It allows to visually check whether the data distribution after normalization is correct and as expected on a set of violin plots by drug names.

```{r plot_var_distribution_qc, warning = FALSE, message = FALSE}
plot_var_distribution_qc(dt_assay = dt_norm_sa,
                         cl_name = "cellline_NE")
plot_var_distribution_qc(dt_assay = dt_norm_cd,
                         cl_name = "cellline_BA")
plot_var_distribution_qc(dt_assay = dt_norm_combo,
                         cl_name = "cellline_NE")
```

### Averaged Values

In the gDR pipeline during the averaging stage, technical replicates that are stored in the same nested table are averaged.

The **pheatmap_qc** function is dedicated to single-agent, co-dilution and combination experiments.

It allows to visually check whether the average values of selected metrics are as expected.

The control heatmap is built for selected cell line names and drugs (for the combination experiment - also for co-drug) that are ordered by concentration.

```{r pheatmap_qc_sa, warning = FALSE, message = FALSE}
hm_sa <- pheatmap_qc(dt_average = dt_average_sa)
patchwork::wrap_elements(hm_sa[["gtable"]])
```

```{r pheatmap_qc_cd, warning = FALSE, message = FALSE}
hm_cd <- pheatmap_qc(dt_average = dt_average_cd)
patchwork::wrap_elements(hm_cd[["gtable"]])
```

```{r pheatmap_qc_combo, warning = FALSE, message = FALSE}
hm_combo <- pheatmap_qc(dt_average = dt_average_combo)
patchwork::wrap_elements(hm_combo[["gtable"]])
```

### Accuracy of Fitting Dose-response Curves

In the gDR pipeline during the fitting stage, the dose-response curves are fitted and the response metrics for each normalization type are calculated.

The **plot_dose_response_sa_qc** function is dedicated to single-agent experiments.

It allows to visually check whether the fitted dose-response curves reflect correctly the measured data after normalization.

Users can also use **plot_dose_response_sa_qc_panel** to get a panel with the dose-response curves - fitted and averaged - for list of cell line names.

```{r plot_dose_response_sa_qc, warning = FALSE, message = FALSE}
plot_dose_response_sa_qc(dt_metrics = dt_metrics_sa,
                         dt_average = dt_average_sa,
                         cl_name = "cellline_AA",
                         d_name = "drug_001")
```

### Quality Control - Fitting Precision

The **plot_var_stat_qc** function is dedicated to single-agent experiments.

It allows to visually check values for the selected metric (from _metric assay_) and selected cell line name on lollipop plots by the list of drugs.

```{r plot_var_stat_qc, warning = FALSE, message = FALSE}
plot_var_stat_qc(dt_assay = dt_metrics_sa,
                 cl_name = "cellline_AA",
                 metric = "x_mean")
```

The **plot_fitting_acc** function is dedicated to single-agent experiments.

It allows to visually check the fitting precision (`R2` and `RSS` values on one panel) on lollipop plots for selected cell line name by the list of drugs.

```{r plot_fitting_acc, warning = FALSE, message = FALSE}
plot_fitting_acc(dt_assay = dt_metrics_sa,
                 cl_name = "cellline_EA")
```

## Correlation between PRISM and DepMap

Generating visualization with PRISM and DepMap is generetde for selected drug
```{r sel_drug, warning = FALSE, message = FALSE}
sel_drug <- unique(dt_norm_prism_sa$DrugName)[1]
print(sel_drug)
```
and requires dedicated inputs. 
 
First part is based on PRISM data prapred with one of functions:
- `prep_dt_response_metric_sa` based on the "Metrics" assay for single-agent experiment
- `prep_dt_response_dose_sa` based on the "Averaged" assay for single-agent experiment
- `prep_dt_response_scores` based on the "scores" assay for combination experiment
- `prep_dt_response_metric_diff` based on the "Metrics" assay for combination experiment

```{r prism_dt_res, warning = FALSE, message = FALSE}
dt_response <- prep_dt_response_metric_sa(
  dt_metrics = dt_metrics_prism_sa,
  d_name = sel_drug,
  normalization_type = "RV",
  metric = "x_mean"
)
```

The second part based on DepMap data prapred with one of functions:

- `prep_dt_depmap_meta` for metadata columns for selected cell line annotations or donor demographics

```{r obj_meta, warning = FALSE, message = FALSE}
meta_data_path <- 
  system.file("depmap_data/Model.csv.gz", package = "gDRtestData")

meta_col <- "OncotreeLineage"
obj_depmap_meta <- prep_dt_depmap_meta(
    meta_data_path = meta_data_path, 
    metadata_col = meta_col)
```

- `prep_dt_depmap_feat` for selected feature

```{r obj_feat, warning = FALSE, message = FALSE}
feat_data_path <- system.file("depmap_data", package = "gDRtestData")

feature_set <- "OmicsCNGene"
obj_depmap_feat <- prep_dt_depmap_feat(
    feat_data_path = feat_data_path,
    meta_data_path = meta_data_path,
    feature_set = feature_set)

feature_set_2 <- "OmicsSomaticMutationsMatrixDamaging"
obj_depmap_feat_2 <- prep_dt_depmap_feat(
    feat_data_path = feat_data_path,
    meta_data_path = meta_data_path,
    feature_set = feature_set_2,
    with_decoding = TRUE)
```

For volcano visualization is also required object with calculated linear associations genarated with `prep_dt_assoc` function.

```{r obj_assoc, warning = FALSE, message = FALSE}
obj_assoc_meta <- prep_dt_assoc(
  dt_response = dt_response,
  dt_depmap = obj_depmap_meta$dt_depmap,
  selected_feat_meta_col = obj_depmap_meta$selected_feat_meta_col)

obj_assoc_feta <- prep_dt_assoc(
  dt_response = dt_response,
  dt_depmap = obj_depmap_feat$dt_depmap,
  selected_feat_meta_col = obj_depmap_feat$selected_feat_meta_col)
```

### Volcano plot

The **plot_volcano_assoc** function is dedicated to PRISM experiments. This function returns the volcano plot with associations between the molecular features or the metadata and readout of interest.

```{r plot_vol_meta, warning = FALSE, message = FALSE}
plot_volcano_assoc(
  dt_assoc = obj_assoc_meta$dt_assoc,
  selected_feat_meta_col = obj_assoc_meta$selected_feat_meta_col,
  selected_metric = obj_assoc_meta$selected_metric,
  condition_info = obj_assoc_meta$condition_info)
```

```{r plot_vol_feat, warning = FALSE, message = FALSE}
plot_volcano_assoc(
  dt_assoc = obj_assoc_feta$dt_assoc,
  selected_feat_meta_col = obj_assoc_feta$selected_feat_meta_col,
  selected_metric = obj_assoc_feta$selected_metric,
  condition_info = obj_assoc_feta$condition_info)
```

Users can also use **plot_volcano_assoc_panel** to get a panel with the volcano plot and scatter plots or box plots for interesting variables - according to the type of data. 

This function returns the volcano panel itself and table with associations.

```{r plot_vol_meta_panel, warning = FALSE, message = FALSE}
obj_res <- plot_volcano_assoc_panel(
  dt_response = dt_response,
  dt_depmap = obj_depmap_meta$dt_depmap,
  selected_metric = "RV_gDR_x_mean",
  selected_feat_meta_col = obj_depmap_meta$selected_feat_meta_col)

obj_res[["panel"]]

generate_datatable(
  obj_res[["assoc_data"]],
  col_to_round = c("rho", "q_value", "neglog_q_value"))
```

```{r plot_vol_feat_panel, warning = FALSE, message = FALSE}
obj_res <- plot_volcano_assoc_panel(
  dt_response = dt_response,
  dt_depmap = obj_depmap_feat$dt_depmap,
  selected_metric = "RV_gDR_x_mean",
  selected_feat_meta_col = obj_depmap_feat$selected_feat_meta_col)

obj_res[["panel"]]

generate_datatable(
  obj_res[["assoc_data"]],
  col_to_round = c("rho", "q_value", "neglog_q_value"))
```

### Scatter plot with correlation

Users can explore more detailed correlation between one selected feature and selected metric using **plot_scatter_with_corr** function.

```{r plot_scatt, warning = FALSE, message = FALSE}
plot_scatter_with_corr(
  dt_response = dt_response,
  dt_depmap = obj_depmap_feat$dt_depmap,
  selected_feat = names(obj_depmap_feat$dt_depmap)[42],
  selected_feat_meta_col = obj_depmap_feat$selected_feat_meta_col)
```

Users can also use **plot_scatter_with_corr_panel** to get a panel with the scatter plot with correlation for list of the DepMap features.

```{r plot_scatt_panel, warning = FALSE, message = FALSE}
plot_scatter_with_corr_panel(
  dt_response = dt_response,
  dt_depmap = obj_depmap_feat$dt_depmap,
  selected_feat = names(obj_depmap_feat$dt_depmap)[12:17],
  selected_feat_meta_col = obj_depmap_feat$selected_feat_meta_col,
  ncol = 3)
```

### Boxplots

Users can explore more detailed distribution of selected metric for selected level of metadata using **plot_boxplot_num** function.

```{r plot_box_num_meta, warning = FALSE, message = FALSE}
plot_boxplot_num(
  dt_response = dt_response,
  dt_depmap = obj_depmap_meta$dt_depmap,
  selected_feat = names(obj_depmap_meta$dt_depmap)[10],
  selected_feat_meta_col = obj_depmap_meta$selected_feat_meta_col)
```


Users can also use **plot_boxplot_num_panel** to get a panel with the box plot with category distribution for list of the DepMap matadata.

```{r plot_box_meta_panel, warning = FALSE, message = FALSE}
plot_boxplot_num_panel(
  dt_response = dt_response,
  dt_depmap = obj_depmap_meta$dt_depmap,
  selected_feat = names(obj_depmap_meta$dt_depmap)[10:13],
  selected_feat_meta_col = obj_depmap_meta$selected_feat_meta_col,
  ncol = 2)
```

Users can also explore more detailed distribution for all lveles of selected metadata and selected metric using **plot_boxplot_meta** function.

```{r plot_box_meta, warning = FALSE, message = FALSE}
plot_boxplot_meta(
  dt_response = dt_response,
  dt_depmap = obj_depmap_meta$dt_depmap,
  selected_feat_meta_col = obj_depmap_meta$selected_feat_meta_col)
```

# SessionInfo {-}

```{r sessionInfo}
sessionInfo()
```