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 8And 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 52colnames(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