Suppl. Ch. 3 - Creating Data Objects

Gabriel Odom

2019-10-29

1. Overview

This vignette is the third chapter in the “Pathway Significance Testing with pathwayPCA” workflow, providing a detailed perspective to the Creating Data Objects section of the Quickstart Guide. This vignette builds on the material covered in the “Import and Tidy Data” vignette. This guide will outline the major steps needed to create a data object for analysis with the pathwayPCA package. These objects are called Omics-class objects.

1.1 Outline

Before we move on, we will outline our steps. After reading this vignette, you should be able to

  1. Describe the data components within the Omics object class.
  2. Create a few Omics objects.
  3. Inspect and edit individual elements contained in these objects.

First, load the pathwayPCA package and the tidyverse package suite.

1.2 Import Data

Because this is the third chapter in the workflow, we assume that

  1. Your assay is “tidy”.
  2. Your gene pathways list is stored in a pathwayCollection object.
  3. Your phenotype and assay data have already been ID-matched.

If you are unsure about any of the three points above (or you don’t know what these mean), please review the Import and Tidy Data vignette first. It isn’t very long, but it will help you set up your data in the right way. If your data is not in the proper form, the steps in this vignette may be very difficult.

For the purpose of example, we will load some “toy” data: a combined assay / phenotype data frame and a pathwayCollection list. These objects already fit the three criteria above. This tidy data set has 656 gene expression measurements (columns) on 250 colon cancer patients (rows).

Notice that the assay and survival response information have already been merged, so we have two additional columns (for Overall Survival Time and its corresponding death indicator). We also have a small collection of 15 pathways which correspond to our example colon cancer assay.

The pathway collection and tidy assay (with matched phenotype information) are all the information we need to create an Omics-class data object.


2. Omics-Class Objects Defined

Now that we have our data loaded, we can create an analysis object for the pathwayPCA package.

2.1 Class Overview

In this package, all primary input data will be in an Omics data object. There are three classes of Omics* objects, but one function (CreateOmics) creates all of them. Each class contains a tidy assay and pathwayCollection list. The classes differ in the type of response information they can hold. The classes, and their responses, are

  1. OmicsSurv—a data object for survival information, which includes event time (the time of last follow-up with a subject) and event indicator (did the subject die, or was the observation right-censored).
  2. OmicsReg—a data object for continuous responses (usually a linear regression response).
  3. OmicsCateg—a data object for categorical responses, the dependent variable of a generalized linear model. Currently, we only support binary classification (through logistic regression).
  4. OmicsPathway—a data object with no response. This is the “parent” class for the other three Omics classes.

2.2 Review of Data Types in R

Take a quick look back at the structure of our colonSurv_df object. We have a table data frame with the first two columns as subject response information and the rest as an expression design matrix. Look at the types of the columns of this data frame (the <dbl> and <int> tags directly under the column names): these tags tell us that the columns contain “double / numeric” (dbl) and “integer” (int) information. The other tags we could potentially see here are <chr> (character), <lgl> (logical), or <fct> (factor). These tags are important because they identify which “class” of data is in each column.

Here are some examples of how to change data between types. We inspect the first 10 entries of each object.

The CreateOmics function puts the response information into specific classes:

These restrictions are on purpose: the internal data creation functions in the pathwayPCA package have very specific requirements about the types of data they take as inputs. This ensures the integrity of your data analysis.


3. Create New Omics Objects

3.1 Overview of Subtypes

All new Omics objects are created with the CreateOmics function. You should use this function to create Omics-class objects for survival, regression, or categorical responses. This CreateOmics function internally calls on a specific creation function for each response type:

In order to create example Omics-class objects, we will consider the overall patient survival time (and corresponding censoring indicator) as our survival response, the event time as our regression response, and event indicator as our binary classification response.

3.2 Create a Survival Omics Data Object

Now we are prepared to create our first survival Omics object for later analysis with either AES-PCA or Supervised PCA. Recall that the colonSurv_df data frame has the survival time in the first column, the event indicator in the second column, and the assay expression data in the subsequent columns. Therefore, the four arguments to the CreateOmics function will be:

Also, when you create an Omics*-class object, the CreateOmics() function prints helpful diagnostic messages about the overlap between the features in the supplied assay data and those in the pathway collection.

The last three sentences inform you of how strong the overlap is between the genes measured in your data and the genes selected in your pathway collection. This messages tells us that 9% of the 676 total genes included in all pathways were not measured in the assay; zero pathways were removed from the pathways list for having too few genes after gene trimming; and the genes in the pathways list call for 93.8% of the 656 genes measured in the assay. The last number is the most important: it measures how well your pathway collection overlaps with the genes measured in your assay. This number should be as close to 100% as possible. These diagnostic messages depend on the overlap between the pathway collection and the assay, so these messages are response agnostic.

3.3 View the New Object

In order to view a summary of the contents of the colon_OmicsSurv object, you need simply to print it to the R console.

Also notice that the CreateOmics() function stores a “cleaned” copy of the pathway collection. The object creation functions within the pathwayPCA package subset the feature data frame by the genes in each pathway. Therefore, if we have genes in the pathways that are not recorded in the data frame, then we will necessarily create missing (NA) predictors. To circumvent this issue, we check if each gene in each pathway is recorded in the data frame, and remove from each pathway the genes for which the assay does not have recorded expression levels. However, if we remove genes from pathways which do not have recorded levels in the predictor data frame, we could theoretically remove all the genes from a given pathway. Thus, we also check to make sure that each pathway in the given pathways list still has some minimum number of genes present (defaulting to three or more) after we have removed genes without corresponding expression levels.

The IntersectOmicsPwyCollct() function performs these two actions simultaneously, and this function is called and executed automatically within the object creation step. This function removes the unrecorded genes from each pathway, trims the pathways that have fewer than the minimum number of genes allowed, and returns a “trimmed” pathway collection. If there are any pathways removed by this execution, the pathways list within the trimPathwayCollection object within the Omics object will have a character vector of the pathways removed stored as the "missingPaths" attribute. Access this attribute with the attr() function.

3.4 Regression and Classification Omics Data Objects

We create regression- and categorical-type Omics data objects identically to survival-type Omics objects. We will use the survival time as our toy regression response and the death indicator as the toy classification response.


4. Inspecting and Editing Omics-Class Objects

In order to access or edit a specific component of an Omics object, we need to use specific accessor functions. These functions are named with the component they access.

4.1 Example “Get” Function

The get* functions access the part of the data object you specify. You can save these objects to their own variables, or simply print them to the screen for inspection. Here we print the assay data frame contained in the colon_OmicsSurv object to the screen:

This function is rather simple: it shows us what object is stored in the assayData_df slot of the colon_OmicsSurv data object. As we should expect, we see all the columns of the colonSurv_df data frame except for the first two (the survival time and event indicator).

4.2 Example “Set” Function

If we needed to edit the assay data frame in the colon_OmicsSurv object, we can use the “replacement” syntax of the getAssay function. These are the “set” functions, and they use the getSLOT(object) <- value syntax. For example, if we wanted to remove all of the genes except for the first ten from the assay data, we can replace this assay data with a subset of the the original colonSurv_df data frame. The SLOT shorthand name is Assay, and the replacement value is the first ten gene expression columns (in columns 3 through 12) of the colonSurv_df data frame: colonSurv_df[, (3:12)].

Now, when we inspect the colon_OmicsSurv data object, we see only ten variables measured in the assayData_df slot, instead of our original 656.

Before we move on, we should resest the data in the assayData_df slot to the full data by

4.3 Table of Accessors

Here is a table listing each of the “get” and “set” methods for the Omics class, and which sub-classes they can access or modify.

Command Omics Sub-class Function
getAssay(object) All Extract the assayData_df data frame stored in object.
getAssay(object) <- value All Set assayData_df stored in object to value.
getSampleIDs(object) All Extract the sampleIDs_char vector stored in object.
getSampleIDs(object) <- value All Set sampleIDs_char stored in object to value.
getPathwayCollection(object) All Extract the pathwayCollection list stored in object.
getPathwayCollection(object) <- value All Set pathwayCollection stored in object to value.
getEventTime(object) Surv Extract the eventTime_num vector stored in object.
getEventTime(object) <- value Surv Set eventTime_num stored in object to value.
getEvent(object) Surv Extract the eventObserved_lgl vector stored in object.
getEvent(object) <- value Surv Set eventObserved_lgl stored in object to value.
getResponse(object) Reg or Categ Extract the response vector stored in object.
getResponse(object) <- value Reg or Categ Set response stored in object to value.

The response vector accessed or edited with the getResponse method depends on if the object supplied is a “regression” Omics-class object or a “categorical” one. For regression Omics objects, getResponse(object) and getResponse(object) <- value get and set, respectively, the response_num slot. However, for categorical Omics objects, getResponse(object) and getResponse(object) <- value get and set, respectively, the response_fact slot. This is because regression objects contain numeric response vectors while categorical objects contain factor response vectors.

4.4 Inspect the Updated pathwayCollection List

As we mentioned in the Importing with the read_gmt Function subsection of the previous vignette, the pathwayCollection object will be modified upon Omics-object creation. Before, this list only had two elements, pathways and TERMS (we skipped importing the “description” field). Now, it has a third element: setsize—the number of genes contained in each pathway.


5. Review

We now summarize our steps so far. We have

  1. Defined the Omics class and three sub-classes: survival, regression, and categorical (and the “parent” class).
  2. Created an Omics object for the three sub-classes.
  3. Inspected and edited individual elements contained in these objects.

Now we are prepared to analyze our created data objects with either AES-PCA or Supervised PCA. Please read vignette chapter 4 next: Test Pathway Significance.

Here is the R session information for this vignette:

sessionInfo()
#> R version 3.6.1 (2019-07-05)
#> Platform: x86_64-pc-linux-gnu (64-bit)
#> Running under: Ubuntu 18.04.3 LTS
#> 
#> Matrix products: default
#> BLAS:   /home/biocbuild/bbs-3.10-bioc/R/lib/libRblas.so
#> LAPACK: /home/biocbuild/bbs-3.10-bioc/R/lib/libRlapack.so
#> 
#> locale:
#>  [1] LC_CTYPE=en_US.UTF-8       LC_NUMERIC=C              
#>  [3] LC_TIME=en_US.UTF-8        LC_COLLATE=C              
#>  [5] LC_MONETARY=en_US.UTF-8    LC_MESSAGES=en_US.UTF-8   
#>  [7] LC_PAPER=en_US.UTF-8       LC_NAME=C                 
#>  [9] LC_ADDRESS=C               LC_TELEPHONE=C            
#> [11] LC_MEASUREMENT=en_US.UTF-8 LC_IDENTIFICATION=C       
#> 
#> attached base packages:
#> [1] stats4    parallel  stats     graphics  grDevices utils     datasets 
#> [8] methods   base     
#> 
#> other attached packages:
#>  [1] SummarizedExperiment_1.16.0 DelayedArray_0.12.0        
#>  [3] BiocParallel_1.20.0         matrixStats_0.55.0         
#>  [5] Biobase_2.46.0              GenomicRanges_1.38.0       
#>  [7] GenomeInfoDb_1.22.0         IRanges_2.20.0             
#>  [9] S4Vectors_0.24.0            BiocGenerics_0.32.0        
#> [11] survminer_0.4.6             ggpubr_0.2.3               
#> [13] magrittr_1.5                survival_2.44-1.1          
#> [15] pathwayPCA_1.2.0            forcats_0.4.0              
#> [17] stringr_1.4.0               dplyr_0.8.3                
#> [19] purrr_0.3.3                 readr_1.3.1                
#> [21] tidyr_1.0.0                 tibble_2.1.3               
#> [23] ggplot2_3.2.1               tidyverse_1.2.1            
#> 
#> loaded via a namespace (and not attached):
#>  [1] httr_1.4.1             jsonlite_1.6           splines_3.6.1         
#>  [4] modelr_0.1.5           assertthat_0.2.1       GenomeInfoDbData_1.2.2
#>  [7] cellranger_1.1.0       yaml_2.2.0             pillar_1.4.2          
#> [10] backports_1.1.5        lattice_0.20-38        glue_1.3.1            
#> [13] digest_0.6.22          ggsignif_0.6.0         XVector_0.26.0        
#> [16] rvest_0.3.4            colorspace_1.4-1       htmltools_0.4.0       
#> [19] Matrix_1.2-17          pkgconfig_2.0.3        broom_0.5.2           
#> [22] haven_2.1.1            zlibbioc_1.32.0        xtable_1.8-4          
#> [25] scales_1.0.0           km.ci_0.5-2            KMsurv_0.1-5          
#> [28] generics_0.0.2         ellipsis_0.3.0         withr_2.1.2           
#> [31] lazyeval_0.2.2         cli_1.1.0              crayon_1.3.4          
#> [34] readxl_1.3.1           evaluate_0.14          fansi_0.4.0           
#> [37] nlme_3.1-141           xml2_1.2.2             tools_3.6.1           
#> [40] data.table_1.12.6      hms_0.5.1              lifecycle_0.1.0       
#> [43] munsell_0.5.0          compiler_3.6.1         rlang_0.4.1           
#> [46] grid_3.6.1             RCurl_1.95-4.12        rstudioapi_0.10       
#> [49] bitops_1.0-6           labeling_0.3           rmarkdown_1.16        
#> [52] gtable_0.3.0           lars_1.2               R6_2.4.0              
#> [55] gridExtra_2.3          zoo_1.8-6              lubridate_1.7.4       
#> [58] knitr_1.25             survMisc_0.5.5         utf8_1.1.4            
#> [61] zeallot_0.1.0          stringi_1.4.3          Rcpp_1.0.2            
#> [64] vctrs_0.2.0            tidyselect_0.2.5       xfun_0.10