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

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

# Data Annotation Process for gDR Pipeline

## Introduction
Before running the gDR pipeline, it is essential to annotate the data properly with drug and cell line information. This document outlines the process of data annotation and the requirements for the annotation files.

## Annotation Files
gDR uses two types of annotation: drug annotation and cell line annotation. These annotations are added to a data table before running the pipeline. The scripts for adding data annotation are located in `R/add_annotation.R`, which contains several primary functions: `annotate_dt_with_cell_line`, `annotate_dt_with_drug`, `get_cell_line_annotation`, and `get_drug_annotation` for receiving the default annotation for the data. Additionally, `annotate_se_with_drug`, `annotate_mae_with_drug`, `annotate_se_with_cell_line`, and `annotate_mae_with_cell_line` are provided to annotate `SummarizedExperiment` and `MultiAssayExperiment` objects. It is recommended to run the `cleanup_metadata` function, which adds annotations and performs some data cleaning.

### Annotation File Locations
Both drug and cell line annotation files are stored in `gDRtestData/inst/annotation_data`. There are two files:

- `cell_lines.csv`
- `drugs.csv`

Users can edit these files to add their own annotations. After updating, it is required to reinstall `gDRtestData` to use the new annotations.

Alternatively, users can use other annotation files stored outside of this package. For this purpose, it is necessary to set two environmental variables:

- `GDR_CELLLINE_ANNOTATION`: Represents the path to the cell line annotation CSV file.
- `GDR_DRUG_ANNOTATION`: Represents the path to the drug annotation CSV file.

```{r, eval=FALSE}
Sys.setenv(GDR_CELLLINE_ANNOTATION = "some/path/to/cell_line_annotation.csv")
Sys.setenv(GDR_DRUG_ANNOTATION = "some/path/to/drug_annotation.csv")
```

**NOTE:** gDR annotation can be sourced from different locations. Setting environmental variables with paths for annotation has the highest priority and will be used as the first source of annotation, even if other sources are available. To clarify, if both the environmental variables and the internal annotation databases are set, gDR will prioritize the environmental variables for annotation.

To turn off the usage of external paths for data annotation, please set these two environmental variables to empty.

```{r, eval=FALSE}
Sys.setenv(GDR_CELLLINE_ANNOTATION = "")
Sys.setenv(GDR_DRUG_ANNOTATION = "")
```

## Annotation Requirements
gDR has specific requirements for the annotation files to properly annotate the data.

### Drug Annotation Requirements
The obligatory fields for drug annotation are:

- `Gnumber`: Represents the ID of the drug.
- `DrugName`: Represents the name of the drug.
- `drug_moa`: Represents the drug mechanism of action.

### Cell Line Annotation Requirements
The obligatory fields for cell line annotation are:

- `clid`: Represents the cell line ID.
- `CellLineName`: Represents the name of the cell line.
- `Tissue`: Represents the primary tissue of the cell line.
- `ReferenceDivisionTime`: Represents the doubling time of the cell line in hours.
- `parental_identifier`: Represents the name of the parental cell line.
- `subtype`: Represents the subtype of the cell line.

If some information is not known for the cell line or drug, the corresponding field should be left empty or NA. Nonetheless, since the fill parameter is consistently specified in the annotation function, the default value of 'unknown' can be altered by the user.

## Annotating SummarizedExperiment and MultiAssayExperiment Objects

To annotate `SummarizedExperiment` and `MultiAssayExperiment` objects, use the functions `annotate_se_with_drug`, `annotate_mae_with_drug`, `annotate_se_with_cell_line`, and `annotate_mae_with_cell_line`. These functions take the experiment objects and the corresponding annotation tables as input and return the annotated objects.

```{r, eval=FALSE}
# Example for SummarizedExperiment
se <- SummarizedExperiment::SummarizedExperiment(
  rowData = data.table::data.table(Gnumber = c("D1", "D2", "D3"))
)
drug_annotation <- get_drug_annotation(data.table::as.data.table(SummarizedExperiment::rowData(se)))
annotated_se <- annotate_se_with_drug(se, drug_annotation)

# Example for MultiAssayExperiment
mae <- MultiAssayExperiment::MultiAssayExperiment(
  experiments = list(exp1 = SummarizedExperiment::SummarizedExperiment(
    rowData = data.table::data.table(clid = c("CL1", "CL2", "CL3"))
  ))
)
cell_line_annotation <- get_cell_line_annotation(data.table::as.data.table(
  SummarizedExperiment::rowData(
    MultiAssayExperiment::experiments(mae)[[1]])))
annotated_mae <- annotate_mae_with_cell_line(mae, cell_line_annotation)
```

## Additional Information for Genentech/Roche Users
For users within Genentech/Roche, we recommend utilizing our internal annotation databases. We provide the `gDRinternal` package specifically for internal users, which includes functions for managing internal annotation data. If you are an internal user, you can install the `gDRinternal` package, and `gDRcore` will automatically utilize this package as a source of data annotation.

## Conclusion
Proper annotation of drug and cell line data is crucial for running the gDR pipeline effectively. By adhering to the annotation requirements and following the outlined process, users can ensure accurate and reliable results from the pipeline.

# SessionInfo {-}

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