Extracting Clinical Information Using the Genomicdatacommons Package

This short post introducds the gdc_clinical() function recently added to the GenomicDataCommons package.

The rich data model at the NCI Genomic Data Commons (GDC) includes clinical and biospecimen details. A recently added feature to the NCI GDC Data Portal is the ability to download tab-delimited files or JSON files for clinical and biospecimen details of samples. The details available in these simplified formats are also available via the GDC API.

library(GenomicDataCommons)

The clinical infomation at the GDC is encapsulated in the cases records. Here, I introduce the gdc_clinical() function from the GenomicDataCommons package that takes as input GDC case IDs and returns a set of four related data.frames:

  • main: important case metadata
  • demographics: basic demographic information
  • exposures: zero or more documented exposures
  • diagnoses: zero or more diagnoses per case

As an example application, we will examine the clinical details for 100 lung adenocarcinoma patients from TCGA (“TCGA-LUAD”). The case ids are available through a basic cases() query, filtered to include only samples that belong to the project from TCGA-LUAD (stored in the project.project_id field). The query to get these case_ids, then, looks like:

case_ids = cases() %>%
    filter(~ project.project_id == 'TCGA-LUAD') %>%
    results(size=100) %>%
    ids()
head(case_ids)
## [1] "ffb0c0b7-165e-4439-b3e6-62431f40b7fe"
## [2] "f98ecd8a-b878-4f53-b911-20cd8e17281c"
## [3] "ccfdad76-cc45-447f-bed8-ede8f6a8844d"
## [4] "9fcdccae-676e-4071-93c3-23d2d3ab0c00"
## [5] "0232d299-4cdf-4fd7-9a5e-8d13c208b40c"
## [6] "bc4c4079-b449-485d-84e4-a40496e563e8"

These case_ids, each representing a single case (patient) in the GDC, can be be fed directly to gdc_clinical.

clin_res = gdc_clinical(case_ids)

The result is a list of data.frames:

names(clin_res)
## [1] "demographic" "diagnoses"   "exposures"   "main"

The the dimensions of these data.frames is instructive.

sapply(clin_res, dim) %>%
    t() %>%
    data.frame() %>%
    set_names(c('rows','columns'))
##             rows columns
## demographic  100      11
## diagnoses     82      23
## exposures     82      13
## main         100       8

And the column names for each are helpful to examine:

sapply(clin_res, colnames)
## $demographic
##  [1] "updated_datetime" "created_datetime" "gender"          
##  [4] "year_of_birth"    "submitter_id"     "state"           
##  [7] "race"             "demographic_id"   "ethnicity"       
## [10] "year_of_death"    "case_id"         
## 
## $diagnoses
##  [1] "case_id"                          
##  [2] "classification_of_tumor"          
##  [3] "last_known_disease_status"        
##  [4] "updated_datetime"                 
##  [5] "primary_diagnosis"                
##  [6] "submitter_id"                     
##  [7] "tumor_stage"                      
##  [8] "age_at_diagnosis"                 
##  [9] "vital_status"                     
## [10] "morphology"                       
## [11] "days_to_death"                    
## [12] "days_to_last_known_disease_status"
## [13] "created_datetime"                 
## [14] "state"                            
## [15] "days_to_recurrence"               
## [16] "diagnosis_id"                     
## [17] "tumor_grade"                      
## [18] "tissue_or_organ_of_origin"        
## [19] "days_to_birth"                    
## [20] "progression_or_recurrence"        
## [21] "prior_malignancy"                 
## [22] "site_of_resection_or_biopsy"      
## [23] "days_to_last_follow_up"           
## 
## $exposures
##  [1] "case_id"            "cigarettes_per_day" "weight"            
##  [4] "updated_datetime"   "alcohol_history"    "alcohol_intensity" 
##  [7] "bmi"                "years_smoked"       "submitter_id"      
## [10] "created_datetime"   "state"              "exposure_id"       
## [13] "height"            
## 
## $main
## [1] "updated_datetime" "submitter_id"     "case_id"         
## [4] "id"               "disease_type"     "created_datetime"
## [7] "state"            "primary_site"

Note the each data.frame contains a case_id column by design to allow arbitrary joining of the tables to each other. In this case, the data relationships are not too complicated, but one might imagine situations arising that include many-to-many relationships that are hard to handle in a fully general way without some understanding of downstream use (what do we want to do with the clinical information?). In this relatively simple case, we can create a “master” data.frame by joining all the records from each data.frame.

library(dplyr)
full_clin = with(clin_res,
     main %>%
     left_join(demographic, by = "case_id") %>%
     left_join(exposures, by = "case_id") %>%
     left_join(diagnoses, by = "case_id"))

Above, I have used the tidyverse approach, applying dplyr left_join()s. Using base R merge would also work.

dim(full_clin)
## [1] 100  52
colnames(full_clin)
##  [1] "updated_datetime.x"               
##  [2] "submitter_id.x"                   
##  [3] "case_id"                          
##  [4] "id"                               
##  [5] "disease_type"                     
##  [6] "created_datetime.x"               
##  [7] "state.x"                          
##  [8] "primary_site"                     
##  [9] "updated_datetime.y"               
## [10] "created_datetime.y"               
## [11] "gender"                           
## [12] "year_of_birth"                    
## [13] "submitter_id.y"                   
## [14] "state.y"                          
## [15] "race"                             
## [16] "demographic_id"                   
## [17] "ethnicity"                        
## [18] "year_of_death"                    
## [19] "cigarettes_per_day"               
## [20] "weight"                           
## [21] "updated_datetime.x.x"             
## [22] "alcohol_history"                  
## [23] "alcohol_intensity"                
## [24] "bmi"                              
## [25] "years_smoked"                     
## [26] "submitter_id.x.x"                 
## [27] "created_datetime.x.x"             
## [28] "state.x.x"                        
## [29] "exposure_id"                      
## [30] "height"                           
## [31] "classification_of_tumor"          
## [32] "last_known_disease_status"        
## [33] "updated_datetime.y.y"             
## [34] "primary_diagnosis"                
## [35] "submitter_id.y.y"                 
## [36] "tumor_stage"                      
## [37] "age_at_diagnosis"                 
## [38] "vital_status"                     
## [39] "morphology"                       
## [40] "days_to_death"                    
## [41] "days_to_last_known_disease_status"
## [42] "created_datetime.y.y"             
## [43] "state.y.y"                        
## [44] "days_to_recurrence"               
## [45] "diagnosis_id"                     
## [46] "tumor_grade"                      
## [47] "tissue_or_organ_of_origin"        
## [48] "days_to_birth"                    
## [49] "progression_or_recurrence"        
## [50] "prior_malignancy"                 
## [51] "site_of_resection_or_biopsy"      
## [52] "days_to_last_follow_up"

In conclusion, the gdc_clinical functionality from the GenomicDataCommons is a high-level function for capturing unified and harmonized clinical information for any case in the NCI GDC repository.

sessionInfo()
## R version 3.5.1 (2018-07-02)
## Platform: x86_64-apple-darwin15.6.0 (64-bit)
## Running under: macOS Sierra 10.12.6
## 
## Matrix products: default
## BLAS: /Library/Frameworks/R.framework/Versions/3.5/Resources/lib/libRblas.0.dylib
## LAPACK: /Library/Frameworks/R.framework/Versions/3.5/Resources/lib/libRlapack.dylib
## 
## locale:
## [1] en_US.UTF-8/en_US.UTF-8/en_US.UTF-8/C/en_US.UTF-8/en_US.UTF-8
## 
## attached base packages:
## [1] stats     graphics  grDevices utils     datasets  methods   base     
## 
## other attached packages:
## [1] dplyr_0.7.7              GenomicDataCommons_1.4.3
## [3] magrittr_1.5             knitr_1.20              
## 
## loaded via a namespace (and not attached):
##  [1] SummarizedExperiment_1.10.1 tidyselect_0.2.5           
##  [3] xfun_0.3                    purrr_0.2.5                
##  [5] lattice_0.20-35             htmltools_0.3.6            
##  [7] stats4_3.5.1                yaml_2.2.0                 
##  [9] rlang_0.3.0.1               pillar_1.3.0               
## [11] glue_1.3.0                  BiocParallel_1.14.2        
## [13] rappdirs_0.3.1              BiocGenerics_0.26.0        
## [15] bindrcpp_0.2.2              matrixStats_0.54.0         
## [17] GenomeInfoDbData_1.1.0      bindr_0.1.1                
## [19] stringr_1.3.1               zlibbioc_1.26.0            
## [21] blogdown_0.8                codetools_0.2-15           
## [23] evaluate_0.12               Biobase_2.40.0             
## [25] IRanges_2.14.12             GenomeInfoDb_1.16.0        
## [27] parallel_3.5.1              curl_3.2                   
## [29] Rcpp_0.12.19                readr_1.1.1                
## [31] backports_1.1.2             DelayedArray_0.6.6         
## [33] S4Vectors_0.18.3            jsonlite_1.5               
## [35] XVector_0.20.0              hms_0.4.2                  
## [37] digest_0.6.18               stringi_1.2.4              
## [39] bookdown_0.7                GenomicRanges_1.32.7       
## [41] grid_3.5.1                  rprojroot_1.3-2            
## [43] tools_3.5.1                 bitops_1.0-6               
## [45] RCurl_1.95-4.11             lazyeval_0.2.1             
## [47] tibble_1.4.2                crayon_1.3.4               
## [49] pkgconfig_2.0.2             Matrix_1.2-14              
## [51] xml2_1.2.0                  assertthat_0.2.0           
## [53] rmarkdown_1.10              httr_1.3.1                 
## [55] R6_2.3.0                    compiler_3.5.1
Avatar
Sean Davis
National Cancer Institute, NIH

Related

comments powered by Disqus