# CoreGx: Class and Function Abstractions for PharmacoGx, RadioGx and ToxicoGx

## list(name = “Petr Smirnov”) list(name = “Ian Smith”) list(name = “Christopher Eeles”) list(name = “Benjamin Haibe-Kains”)

###

# CoreGx

This package provides a foundation for the PharmacoGx, RadioGx and ToxicoGx packages. It is not intended for standalone use, only as a dependency for the aforementioned software. Its existence allows abstracting generic definitions, method definitions and class structures common to all three of the Gx suite packages.

## Importing and Using CoreGx

Load the pacakge:

    library(CoreGx)
    library(Biobase)
    library(SummarizedExperiment)

## The CoreSet Class

The `CoreSet` class is intended as a general purpose data structure for storing multiomic treatment response data. Extensions of this class have been customized for their respective fields of study. For example, the `PharmacoSet` class inherits from the `CoreSet` and is specialized for storing and analyzing drug sensitivity and perturbation experiments on cancer cell lines together with associated multiomic data for each treated sample. The RadioSet class serves a role similar to the PharmacoSet with radiation instead of drug treatments. Finally, the ToxicoSet class is used to store toxicity data for healthy human and rat hepatocytes along with the associated multiomic profile for each treatment.

    getClass("CoreSet")

    ## Class "CoreSet" [package "CoreGx"]
    ##
    ## Slots:
    ##
    ## Name:  treatmentResponse        annotation molecularProfiles            sample
    ## Class: list_OR_LongTable              list       list_OR_MAE        data.frame
    ##
    ## Name:          treatment       datasetType      perturbation          curation
    ## Class:        data.frame         character              list              list

The `annotation` slot holds the CoreSet name, the original constructor call, and a range of metadata about the R session in which the constructor was called. This allows easy comparison of `CoreSet` versions across time and ensures the code used to generate a `CoreSet` is well-documented and reproducible.

The `molecularProfiles` slot contains a list of `SummarizedExperiment` objects for each multi-omic molecular datatype available for a given experiment. Within the `SummarizedExperiments` are feature and sample annotations for each data type. We are currently in the process of adopting the `MultiAssayExperiment` class instead of a `list` for storing molecular profile `SummarizedExperiment`s. However, the `list` version of the `molecularProfiles` slot is still supported for backwards compatability.

The `sample` slot contains a `data.frame` with annotations for samples used in the molecularProfiles or sensitivity slot. It should at minimum have the standardized column ‘sampleid’, with a unique identifier for each sample in the `CoreSet`.

The `treatment` slot contains a `data.frame` of metadata for treatments applied to samples in the `molecularProfiles` or `treatmentResponse` slot. It should at minimum have the standarized column ‘treatmentid’, containing a unique identifier for each treatment in the `CoreSet`.

The `datasetType` slot contains a character vector indicating the experiment type the `CoreSet` contains. This slot is soft deprecated and may be removed in future updates.

The `treatmentResponse` slot contains a list of raw, curated and meta data for treatment-response experiments. We are currently in the process of adopting our new S4-class, the `TreamtentResponseExperiment` to store treatment-response data within a `CoreSet` and inheriting classes. However, the old `list` format for sensitivity experiments will continue to be support for backwards compatability.

The `perturbation` slot contains a list of raw, curated and meta data for perturbation experiments. This slot is soft-deprecated and may be removed in the future. The reason is that treatment perturbation experiments can be efficiently stored in the `colData` slot of their respective `SummarizedExperiment` objects and thus no longer require their own space within a `CoreSet`.

The `curation` slot contains a list of manually curated identifiers such as standardized cell-line, tissue and treatment names. Inclusion of such identifiers ensures a consistent nomenclature is used across all datasets curated into the classes inheriting from the `CoreSet`, enabling results from such datasets to be easily compared to validate results from published studies or combine them for use in larger meta-analyses. The slot contains a list of `data.frame`s, one for each entity, and should at minimum include a mapping from curated identifiers used throughout the object to those used in the original dataset publication.

The `CoreSet` class provides a set of standardized accessor methods which simplify curation, annotation, and retrieval of data associated with a specfic treatment response experiment. All accessors are implemented as generics to allow new methods to be defined on classes inheriting from the `CoreSet`.

    methods(class="CoreSet")

    ##  [1] annotation              annotation<-            curation
    ##  [4] curation<-              datasetType             datasetType<-
    ##  [7] dateCreated             dateCreated<-           fNames
    ## [10] fNames<-                featureInfo             featureInfo<-
    ## [13] mDataNames              mDataNames<-            molecularProfiles
    ## [16] molecularProfiles<-     molecularProfilesSlot   molecularProfilesSlot<-
    ## [19] name                    name<-                  pertNumber
    ## [22] pertNumber<-            phenoInfo               phenoInfo<-
    ## [25] sampleInfo              sampleInfo<-            sampleNames
    ## [28] sampleNames<-           sensNumber              sensNumber<-
    ## [31] sensitivityInfo         sensitivityInfo<-       sensitivityMeasures
    ## [34] sensitivityMeasures<-   sensitivityProfiles     sensitivityProfiles<-
    ## [37] sensitivityRaw          sensitivityRaw<-        show
    ## [40] subsetByFeature         subsetBySample          subsetByTreatment
    ## [43] treatmentInfo           treatmentInfo<-         treatmentNames
    ## [46] treatmentNames<-        treatmentResponse       treatmentResponse<-
    ## [49] updateObject
    ## see '?methods' for accessing help and source code

We have provided a sample `CoreSet` (cSet) in this package. In the below code we load the example cSet and demonstrate a few of the accessor methods.

    data(clevelandSmall_cSet)
    clevelandSmall_cSet

    ## <CoreSet>
    ## Name:  Cleveland
    ## Date Created:  Sat Feb 18 15:10:56 2023
    ## Number of samples:  10
    ## Molecular profiles:
    ##    A MultiAssayExperiment object of 2 listed
    ##    experiments with user-defined names and respective classes.
    ##    Containing an ExperimentList class object of length 2:
    ##    [1] rna: SummarizedExperiment with 1000 rows and 9 columns
    ##    [2] rnaseq: SummarizedExperiment with 1000 rows and 9 columns
    ## Treatment response:
    ##    <TreatmentResponseExperiment>
    ##   dim:  9 10
    ##   assays(2): sensitivity profiles
    ##   rownames(9): radiation:1:1 radiation:1:2 ... radiation:8:1 radiation:10:1
    ##   rowData(3): treatment1id treatment1dose replicate_id
    ##   colnames(10): CHP-212 IMR-32 KP-N-S19s ... SK-N-SH SNU-245 SNU-869
    ##   colData(2): sampleid rn
    ##   metadata(1): experiment_metadata

Access a specific molecular profiles:

    mProf <- molecularProfiles(clevelandSmall_cSet, "rna")
    mProf[seq_len(5), seq_len(5)]

    ##                 NIECE_P_NCLE_RNA3_HG-U133_PLUS_2_G10_296152
    ## ENSG00000000003                                   10.280970
    ## ENSG00000000005                                    3.647436
    ## ENSG00000000419                                   11.883769
    ## ENSG00000000457                                    7.515721
    ## ENSG00000000460                                    7.808139
    ##                 GILDS_P_NCLE_RNA11_REDO_HG-U133_PLUS_2_G02_587654
    ## ENSG00000000003                                         10.304971
    ## ENSG00000000005                                          4.895494
    ## ENSG00000000419                                         11.865191
    ## ENSG00000000457                                          7.187144
    ## ENSG00000000460                                          7.789921
    ##                 BUNDS_P_NCLE_RNA5_HG-U133_PLUS_2_B11_419860
    ## ENSG00000000003                                    9.596987
    ## ENSG00000000005                                    3.793174
    ## ENSG00000000419                                   12.498285
    ## ENSG00000000457                                    8.076655
    ## ENSG00000000460                                    8.456691
    ##                 SILOS_P_NCLE_RNA9_HG-U133_PLUS_2_A04_523474
    ## ENSG00000000003                                    8.620860
    ## ENSG00000000005                                    3.674918
    ## ENSG00000000419                                   11.674671
    ## ENSG00000000457                                    6.790332
    ## ENSG00000000460                                    6.663846
    ##                 WATCH_P_NCLE_RNA8_HG-U133_PLUS_2_B04_474582
    ## ENSG00000000003                                    9.866551
    ## ENSG00000000005                                    3.748959
    ## ENSG00000000419                                   12.228260
    ## ENSG00000000457                                    7.292420
    ## ENSG00000000460                                    8.869378

Access cell-line metadata:

    cInfo <- sampleInfo(clevelandSmall_cSet)
    cInfo[seq_len(5), seq_len(5)]

    ##            sampleid          tissueid CellLine       Primarysite     Histology
    ## SK-N-FI     SK-N-FI autonomic_ganglia    SKNFI autonomic_ganglia neuroblastoma
    ## IMR-32       IMR-32 autonomic_ganglia    IMR32 autonomic_ganglia neuroblastoma
    ## SK-N-AS     SK-N-AS autonomic_ganglia    SKNAS autonomic_ganglia neuroblastoma
    ## CHP-212     CHP-212 autonomic_ganglia   CHP212 autonomic_ganglia neuroblastoma
    ## KP-N-S19s KP-N-S19s autonomic_ganglia  KPNSI9S autonomic_ganglia neuroblastoma

Access treatment-response data:

    sensProf <- sensitivityProfiles(clevelandSmall_cSet)
    sensProf[seq_len(5), seq_len(5)]

    ## [1] 1 2 3 4 5

For more information about the accessor methods available for the `CoreSet` class please see the `class?CoreSet` help page.

## Extending the CoreSet Class

Given that the CoreSet class is intended for extension, we will show some examples of how to define a new class based on it and implement new methods for the generics provided for the CoreSet class.

Here we will define a new class, the `DemoSet`, with an additional slot, the `demoSlot`. We will then view the available methods for this class as well as define new S4 methods on it.

    DemoSet <- setClass("DemoSet",
                        representation(demoSlot="character"),
                        contains="CoreSet")
    getClass("DemoSet")

    ## Class "DemoSet" [in ".GlobalEnv"]
    ##
    ## Slots:
    ##
    ## Name:           demoSlot treatmentResponse        annotation molecularProfiles
    ## Class:         character list_OR_LongTable              list       list_OR_MAE
    ##
    ## Name:             sample         treatment       datasetType      perturbation
    ## Class:        data.frame        data.frame         character              list
    ##
    ## Name:           curation
    ## Class:              list
    ##
    ## Extends: "CoreSet"

Here we can see the class extending `CoreSet` has all of the same slots as the original `CoreSet`, plus the new slot we defined: `demoSlot`.

We can see which methods are available for this new class.

    methods(class="DemoSet")

    ##  [1] annotation              annotation<-            curation
    ##  [4] curation<-              datasetType             datasetType<-
    ##  [7] dateCreated             dateCreated<-           fNames
    ## [10] fNames<-                featureInfo             featureInfo<-
    ## [13] mDataNames              mDataNames<-            molecularProfiles
    ## [16] molecularProfiles<-     molecularProfilesSlot   molecularProfilesSlot<-
    ## [19] name                    name<-                  pertNumber
    ## [22] pertNumber<-            phenoInfo               phenoInfo<-
    ## [25] sampleInfo              sampleInfo<-            sampleNames
    ## [28] sampleNames<-           sensNumber              sensNumber<-
    ## [31] sensitivityInfo         sensitivityInfo<-       sensitivityMeasures
    ## [34] sensitivityMeasures<-   sensitivityProfiles     sensitivityProfiles<-
    ## [37] sensitivityRaw          sensitivityRaw<-        show
    ## [40] subsetByFeature         subsetBySample          subsetByTreatment
    ## [43] treatmentInfo           treatmentInfo<-         treatmentNames
    ## [46] treatmentNames<-        treatmentResponse       treatmentResponse<-
    ## [49] updateObject
    ## see '?methods' for accessing help and source code

We see that all the accessors defined for the `CoreSet` are also defined for the inheriting `DemoSet`. These methods all assume the inherit slots have the same structure as the `CoreSet`. If this is not true, for example, if molecularProfiles holds `ExpressionSet`s instead of `SummarizedExperiment`s, we can redefine existing methods as follows:

    clevelandSmall_dSet <- DemoSet(clevelandSmall_cSet)
    class(clevelandSmall_dSet@molecularProfiles[['rna']])

    ## [1] "SummarizedExperiment"
    ## attr(,"package")
    ## [1] "SummarizedExperiment"

    expressionSets <- lapply(molecularProfilesSlot(clevelandSmall_dSet), FUN=as,
      'ExpressionSet')
    molecularProfilesSlot(clevelandSmall_dSet) <- expressionSets

    # Now this will error
    tryCatch({molecularProfiles(clevelandSmall_dSet, 'rna')},
             error=function(e)
                 print(paste("Error: ", e$message)))

    ## [1] "Error:  unable to find an inherited method for function 'assay' for signature '\"ExpressionSet\", \"numeric\"'"

Since we changed the data in the `molecularProfiles` slot of the `DemoSet`, the original method from `CoreGx` no longer works. Thus we get an error when trying to access that slot. To fix this we will need to set a new S4 method for the molecularProfiles generic function defined in `CoreGx`.

    setMethod(molecularProfiles,
              signature("DemoSet"),
              function(object, mDataType) {
                pData(object@molecularProfiles[[mDataType]])
              })

This new method is now called whenever we use the `molecularProfiles` method on a `DemoSet`. Since the new method uses `ExpressionSet` accessor methods instead of `SummarizedExperiment` accessor methods, we now expect to be able to access the data in our modified slot.

    # Now we test our new method
    mProf <- molecularProfiles(clevelandSmall_dSet, 'rna')
    head(mProf)[seq_len(5), seq_len(5)]

    ##                                                                                          samplename
    ## NIECE_P_NCLE_RNA3_HG-U133_PLUS_2_G10_296152             NIECE_p_NCLE_RNA3_HG-U133_Plus_2_G10_296152
    ## GILDS_P_NCLE_RNA11_REDO_HG-U133_PLUS_2_G02_587654 GILDS_p_NCLE_RNA11_Redo_HG-U133_Plus_2_G02_587654
    ## BUNDS_P_NCLE_RNA5_HG-U133_PLUS_2_B11_419860             BUNDS_p_NCLE_RNA5_HG-U133_Plus_2_B11_419860
    ## SILOS_P_NCLE_RNA9_HG-U133_PLUS_2_A04_523474             SILOS_p_NCLE_RNA9_HG-U133_Plus_2_A04_523474
    ## WATCH_P_NCLE_RNA8_HG-U133_PLUS_2_B04_474582             WATCH_p_NCLE_RNA8_HG-U133_Plus_2_B04_474582
    ##                                                                                                   filename
    ## NIECE_P_NCLE_RNA3_HG-U133_PLUS_2_G10_296152             NIECE_p_NCLE_RNA3_HG-U133_Plus_2_G10_296152.CEL.gz
    ## GILDS_P_NCLE_RNA11_REDO_HG-U133_PLUS_2_G02_587654 GILDS_p_NCLE_RNA11_Redo_HG-U133_Plus_2_G02_587654.CEL.gz
    ## BUNDS_P_NCLE_RNA5_HG-U133_PLUS_2_B11_419860             BUNDS_p_NCLE_RNA5_HG-U133_Plus_2_B11_419860.CEL.gz
    ## SILOS_P_NCLE_RNA9_HG-U133_PLUS_2_A04_523474             SILOS_p_NCLE_RNA9_HG-U133_Plus_2_A04_523474.CEL.gz
    ## WATCH_P_NCLE_RNA8_HG-U133_PLUS_2_B04_474582             WATCH_p_NCLE_RNA8_HG-U133_Plus_2_B04_474582.CEL.gz
    ##                                                         chiptype
    ## NIECE_P_NCLE_RNA3_HG-U133_PLUS_2_G10_296152       HG-U133_Plus_2
    ## GILDS_P_NCLE_RNA11_REDO_HG-U133_PLUS_2_G02_587654 HG-U133_Plus_2
    ## BUNDS_P_NCLE_RNA5_HG-U133_PLUS_2_B11_419860       HG-U133_Plus_2
    ## SILOS_P_NCLE_RNA9_HG-U133_PLUS_2_A04_523474       HG-U133_Plus_2
    ## WATCH_P_NCLE_RNA8_HG-U133_PLUS_2_B04_474582       HG-U133_Plus_2
    ##                                                   hybridization.date
    ## NIECE_P_NCLE_RNA3_HG-U133_PLUS_2_G10_296152                 07/15/08
    ## GILDS_P_NCLE_RNA11_REDO_HG-U133_PLUS_2_G02_587654         2010-05-21
    ## BUNDS_P_NCLE_RNA5_HG-U133_PLUS_2_B11_419860                 12/19/08
    ## SILOS_P_NCLE_RNA9_HG-U133_PLUS_2_A04_523474               2009-12-08
    ## WATCH_P_NCLE_RNA8_HG-U133_PLUS_2_B04_474582               2009-08-14
    ##                                                   hybridization.hour
    ## NIECE_P_NCLE_RNA3_HG-U133_PLUS_2_G10_296152                 12:54:10
    ## GILDS_P_NCLE_RNA11_REDO_HG-U133_PLUS_2_G02_587654          16:45:06Z
    ## BUNDS_P_NCLE_RNA5_HG-U133_PLUS_2_B11_419860                 11:43:19
    ## SILOS_P_NCLE_RNA9_HG-U133_PLUS_2_A04_523474                20:44:59Z
    ## WATCH_P_NCLE_RNA8_HG-U133_PLUS_2_B04_474582                17:15:45Z

We can see our new method works! In order to finish updating the methods for our new class, we would have to redefine all the methods which access the modified slot.

However, additional work needs to be done to define accessors for the new `demoSlot`. Since no generics are available in CoreGx to access this slot, we need to first define a generic, then implement methods which dispatch on the ‘DemoSet’ class to retrieve data in the slot.

    # Define generic for setter method
    setGeneric('demoSlot<-', function(object, value) standardGeneric('demoSlot<-'))

    ## [1] "demoSlot<-"

    # Define a setter method
    setReplaceMethod('demoSlot',
                     signature(object='DemoSet', value="character"),
                     function(object, value) {
                       object@demoSlot <- value
                       return(object)
                     })

    # Lets add something to our demoSlot
    demoSlot(clevelandSmall_dSet) <- c("This", "is", "the", "demoSlot")

    # Define generic for getter method
    setGeneric('demoSlot', function(object, ...) standardGeneric("demoSlot"))

    ## [1] "demoSlot"

    # Define a getter method
    setMethod("demoSlot",
              signature("DemoSet"),
              function(object) {
                paste(object@demoSlot, collapse=" ")
              })

    # Test our getter method
    demoSlot(clevelandSmall_dSet)

    ## [1] "This is the demoSlot"

Now you should have all the knowledge you need to extend the CoreSet class for use in other treatment-response experiments!

For more information about this package and the possibility of collaborating on its extension please contact benjamin.haibe.kains@utoronto.ca.

# sessionInfo

    sessionInfo()

    ## R version 4.3.0 RC (2023-04-13 r84269 ucrt)
    ## Platform: x86_64-w64-mingw32/x64 (64-bit)
    ## Running under: Windows Server 2022 x64 (build 20348)
    ##
    ## Matrix products: default
    ##
    ##
    ## locale:
    ## [1] LC_COLLATE=C
    ## [2] LC_CTYPE=English_United States.utf8
    ## [3] LC_MONETARY=English_United States.utf8
    ## [4] LC_NUMERIC=C
    ## [5] LC_TIME=English_United States.utf8
    ##
    ## time zone: America/New_York
    ## tzcode source: internal
    ##
    ## attached base packages:
    ## [1] stats4    stats     graphics  grDevices utils     datasets  methods
    ## [8] base
    ##
    ## other attached packages:
    ##  [1] knitr_1.42                  data.table_1.14.8
    ##  [3] CoreGx_2.4.0                SummarizedExperiment_1.30.0
    ##  [5] Biobase_2.60.0              GenomicRanges_1.52.0
    ##  [7] GenomeInfoDb_1.36.0         IRanges_2.34.0
    ##  [9] S4Vectors_0.38.0            MatrixGenerics_1.12.0
    ## [11] matrixStats_0.63.0          BiocGenerics_0.46.0
    ## [13] formatR_1.14                BiocStyle_2.28.0
    ##
    ## loaded via a namespace (and not attached):
    ##  [1] tidyselect_1.2.0            dplyr_1.1.2
    ##  [3] bitops_1.0-7                fastmap_1.1.1
    ##  [5] RCurl_1.98-1.12             BumpyMatrix_1.8.0
    ##  [7] shinyjs_2.1.0               promises_1.2.0.1
    ##  [9] digest_0.6.31               mime_0.12
    ## [11] lifecycle_1.0.3             cluster_2.1.4
    ## [13] ellipsis_0.3.2              magrittr_2.0.3
    ## [15] compiler_4.3.0              rlang_1.1.0
    ## [17] sass_0.4.5                  tools_4.3.0
    ## [19] utf8_1.2.3                  igraph_1.4.2
    ## [21] yaml_2.3.7                  htmlwidgets_1.6.2
    ## [23] bench_1.1.2                 DelayedArray_0.26.0
    ## [25] marray_1.78.0               BiocParallel_1.34.0
    ## [27] KernSmooth_2.23-20          grid_4.3.0
    ## [29] fansi_1.0.4                 relations_0.6-13
    ## [31] caTools_1.18.2              xtable_1.8-4
    ## [33] colorspace_2.1-0            ggplot2_3.4.2
    ## [35] scales_1.2.1                gtools_3.9.4
    ## [37] MultiAssayExperiment_1.26.0 cli_3.6.1
    ## [39] rmarkdown_2.21              crayon_1.5.2
    ## [41] generics_0.1.3              BiocBaseUtils_1.2.0
    ## [43] visNetwork_2.1.2            sets_1.0-24
    ## [45] cachem_1.0.7                zlibbioc_1.46.0
    ## [47] parallel_4.3.0              BiocManager_1.30.20
    ## [49] XVector_0.40.0              vctrs_0.6.2
    ## [51] Matrix_1.5-4                jsonlite_1.8.4
    ## [53] slam_0.1-50                 lsa_0.73.3
    ## [55] bookdown_0.33               limma_3.56.0
    ## [57] jquerylib_0.1.4             glue_1.6.2
    ## [59] codetools_0.2-19            DT_0.27
    ## [61] cowplot_1.1.1               gtable_0.3.3
    ## [63] later_1.3.0                 shinydashboard_0.7.2
    ## [65] munsell_0.5.0               tibble_3.2.1
    ## [67] pillar_1.9.0                htmltools_0.5.5
    ## [69] gplots_3.1.3                fgsea_1.26.0
    ## [71] GenomeInfoDbData_1.2.10     R6_2.5.1
    ## [73] evaluate_0.20               shiny_1.7.4
    ## [75] lattice_0.21-8              highr_0.10
    ## [77] backports_1.4.1             SnowballC_0.7.1
    ## [79] httpuv_1.6.9                bslib_0.4.2
    ## [81] fastmatch_1.1-3             Rcpp_1.0.10
    ## [83] checkmate_2.1.0             xfun_0.39
    ## [85] piano_2.16.0                pkgconfig_2.0.3