Skip to content
Provide R access to the NCI Genomic Data Commons portal.
Branch: master
Clone or download
seandavi add significant new query capabilities
query for simple somatic mutations,
copy number variants, and gene detail
information. Also, slicing with multiple
regions now works as expected.
Latest commit 609ecd9 Jan 19, 2019
Type Name Latest commit message Commit time
Failed to load latest commit information.
R add significant new query capabilities Jan 19, 2019
inst Adding AnnotationFilter, NADfinder, GenomicDataCommons, RIVER, BioMed… Mar 31, 2017
man add significant new query capabilities Jan 19, 2019
tests fix testthat errors that appear to be API-related Sep 6, 2018
vignettes float toc in vignette Nov 9, 2018
.gitignore ignore docs directory Sep 4, 2018
.travis.yml warnings_as_errors: false on travis, for now Nov 14, 2017
DESCRIPTION add significant new query capabilities Jan 19, 2019
NAMESPACE add significant new query capabilities Jan 19, 2019
NEWS add significant new query capabilities Jan 19, 2019 Update README to new style filtering Nov 8, 2018
_pkgdown.yml add reference scaffolding to docs Sep 26, 2017

What is the GDC?

From the Genomic Data Commons (GDC) website:

The National Cancer Institute's (NCI's) Genomic Data Commons (GDC) is a data sharing platform that promotes precision medicine in oncology. It is not just a database or a tool; it is an expandable knowledge network supporting the import and standardization of genomic and clinical data from cancer research programs.

The GDC contains NCI-generated data from some of the largest and most comprehensive cancer genomic datasets, including The Cancer Genome Atlas (TCGA) and Therapeutically Applicable Research to Generate Effective Therapies (TARGET). For the first time, these datasets have been harmonized using a common set of bioinformatics pipelines, so that the data can be directly compared.

As a growing knowledge system for cancer, the GDC also enables researchers to submit data, and harmonizes these data for import into the GDC. As more researchers add clinical and genomic data to the GDC, it will become an even more powerful tool for making discoveries about the molecular basis of cancer that may lead to better care for patients.

The data model for the GDC is complex, but it worth a quick overview. The data model is encoded as a so-called property graph. Nodes represent entities such as Projects, Cases, Diagnoses, Files (various kinds), and Annotations. The relationships between these entities are maintained as edges. Both nodes and edges may have Properties that supply instance details. The GDC API exposes these nodes and edges in a somewhat simplified set of RESTful endpoints.


This software is available at and can be downloaded via BiocManager::install.

To report bugs or problems, either submit a new issue or submit a'GenomicDataCommons') from within R (which will redirect you to the new issue on GitHub).


Installation can be achieved via Bioconductor's BiocManager package.

if (!require("BiocManager"))

Check basic functionality


Find data

The following code builds a manifest that can be used to guide the download of raw data. Here, filtering finds gene expression files quantified as raw counts using HTSeq from ovarian cancer patients.

ge_manifest = files() %>% 
    filter( cases.project.project_id == 'TCGA-OV') %>%
    filter( type == 'gene_expression' ) %>%
    filter( analysis.workflow_type == 'HTSeq - Counts') %>%

Download data

This code block downloads the r nrow(ge_manifest) gene expression files specified in the query above. Using multiple processes to do the download very significantly speeds up the transfer in many cases. The following completes in about 15 seconds.

destdir = tempdir()
fnames = lapply(ge_manifest$id,gdcdata)

If the download had included controlled-access data, the download above would have needed to include a token. Details are available in the authentication section below.

Metadata queries

expands = c("diagnoses","annotations",
clinResults = cases() %>% 
    GenomicDataCommons::select(NULL) %>%
    GenomicDataCommons::expand(expands) %>% 
clinDF =
datatable(clinDF, extensions = 'Scroller', options = list(
  deferRender = TRUE,
  scrollY = 200,
  scrollX = TRUE,
  scroller = TRUE

Basic design

This package design is meant to have some similarities to the "hadleyverse" approach of dplyr. Roughly, the functionality for finding and accessing files and metadata can be divided into:

  1. Simple query constructors based on GDC API endpoints.
  2. A set of verbs that when applied, adjust filtering, field selection, and faceting (fields for aggregation) and result in a new query object (an endomorphism)
  3. A set of verbs that take a query and return results from the GDC

In addition, there are exhiliary functions for asking the GDC API for information about available and default fields, slicing BAM files, and downloading actual data files. Here is an overview of functionality[^1].

  • Creating a query
    • projects()
    • cases()
    • files()
    • annotations()
  • Manipulating a query
    • filter()
    • facet()
    • select()
  • Introspection on the GDC API fields
    • mapping()
    • available_fields()
    • default_fields()
    • grep_fields()
    • field_picker()
    • available_values()
    • available_expand()
  • Executing an API call to retrieve query results
    • results()
    • count()
    • response()
  • Raw data file downloads
    • gdcdata()
    • transfer()
    • gdc_client()
  • Summarizing and aggregating field values (faceting)
    • aggregations()
  • Authentication
    • gdc_token()
  • BAM file slicing
    • slicing()

[^1]: See individual function and methods documentation for specific details.

You can’t perform that action at this time.