Data model

The data model is built on the MultiAssayExperiments (MAE) structure. Within an MAE, each SummarizedExperiment (SE) contains a different unit type (e.g. single-agent, or combination treatment). Columns of the MAE are defined by the cell lines and any modification of them and are shared with the SEs. Rows are defined by the treatments (e.g drugs, perturbations) and are specific to each SE. Assays of the SE are the different levels of data processing (raw, control, normalized, averaged data, as well as metrics). Each nested element of the assays of the SEs comprises the series themselves as a table (data.table in practice). Although not all elements need to have a series or the same number of elements, the attributes (columns of the table) should be consistent across the SE.

Drug processing

For drug response data, the input files need to be merged such that each measurement (data) is associated with the right metadata (cell line properties and treatment definition). Metadata can be added with the function cleanup_metadata if the right reference databases are in place.

When the data and metadata are merged into a long table, the wrapper function runDrugResponseProcessingPipeline can be used to generate an MAE with processed and analyzed data.

.

In practice runDrugResponseProcessingPipeline does the following steps:

• create_SE creates the structure of the MAE and the associated SEs by assigning metadata into the row and column attributes. The assignment is performed in the function split_SE_components (see details below for the assumption made when building SE structures). create_SE also dispatches the raw data and controls into the right nested tables. Note that data may be duplicated between different SEs to make them self-contained.
• normalize_SE normalizes the raw data based on the control. Calculation of the GR value is based on a cell line division time provided by the reference database if no pre-treatment control is provided. If both information are missing, GR values cannot be calculated. Additional normalization can be added as new rows in the nested table.
• average_SE averages technical replicates that are stored in the same nested table are averaged.
• fit_SE fits the dose-response curves and calculates response metrics for each normalization type.
• fit_SE.combinations calculates synergy scores for drug combination data and, if the data is appropriate, fits along the two drugs and matrix-level metrics (e.g. isobolograms) are calculated. This is also performed for each normalization type independently.

.

The functions to process the data have parameters for specifying the names of the variables and assays. Additional parameters are available to personalize the processing steps such as force the nesting (or not) of an attribute, specify attributes that should be considered as technical replicates or not.

Data preprocessing

Please familiarize with gDRimport package containing bunch of tools allowing to prepare input data for gDRcore.

This example is made up based on the artificial dataset called data1 available within gDRimport package. gDR required three types of data that should be used as the raw input: Template, Manifest, and RawData. More info about these three types of data you could find in our general documentation.

td <- gDRimport::get_test_data()

Provided dataset needs to be merged into the one data.table object to be able to run gDR pipeline. This process can be done using two functions – gDRimport::load_data() and gDRcore::merge_data().

Running gDR pipeline

We provide an all-in-one function that splits data into appropriate data types, creates the SummarizedExperiment object for each data type, splits data into treatment and control assays, normalizes, averages, calculates gDR metrics, and finally, creates the MultiAssayExperiment object. This function is called runDrugResponseProcessingPipeline.

mae <- runDrugResponseProcessingPipeline(input_df)

mae
#> A MultiAssayExperiment object of 2 listed
#>  experiments with user-defined names and respective classes.
#>  Containing an ExperimentList class object of length 2:
#>  [1] combination: SummarizedExperiment with 2 rows and 6 columns
#>  [2] single-agent: SummarizedExperiment with 3 rows and 6 columns
#> Functionality:
#>  experiments() - obtain the ExperimentList instance
#>  colData() - the primary/phenotype DataFrame
#>  sampleMap() - the sample coordination DataFrame
#>  `$`, `[`, `[[` - extract colData columns, subset, or experiment
#>  *Format() - convert into a long or wide DataFrame
#>  assays() - convert ExperimentList to a SimpleList of matrices
#>  exportClass() - save data to flat files

And we can subset the MultiAssayExperiment to receive the SummarizedExperiment specific to any data type, e.g.

mae[["single-agent"]]
#> class: SummarizedExperiment 
#> dim: 3 6 
#> metadata(5): identifiers experiment_metadata Keys fit_parameters
#>   .internal
#> assays(5): RawTreated Controls Normalized Averaged Metrics
#> rownames(3): G00002_drug_002_moa_A_168 G00004_drug_004_moa_A_168
#>   G00011_drug_011_moa_B_168
#> rowData names(4): Gnumber DrugName drug_moa Duration
#> colnames(6): CL00011_cellline_BA_breast_cellline_BA_unknown_26
#>   CL00012_cellline_CA_breast_cellline_CA_unknown_30 ...
#>   CL00015_cellline_FA_breast_cellline_FA_unknown_42
#>   CL00018_cellline_IB_breast_cellline_IB_unknown_54
#> colData names(6): clid CellLineName ... subtype ReferenceDivisionTime

Data extraction

Extraction of the data from either MultiAssayExperiment or SummarizedExperiment objects into more user-friendly structures as well as other data transformations can be done using gDRutils. We encourage to read gDRutils vignette to familiarize with these functionalities.