Author: Marcel Ramos
Date: 2026-05-18

# terraTCGAdata Introduction

Marcel Ramos

#### May 18, 2026

# Contents

# 1 terraTCGAData

## 1.1 Installation

    if (!require("BiocManager", quietly = TRUE))
        install.packages("BiocManager")

    BiocManager::install("terraTCGAdata")

# 2 Overview

The `terraTCGAdata` R package aims to import TCGA datasets, as MultiAssayExperiment, available on the Terra platform. The package provides a set of functions that allow the discovery of relevant datasets. It provides one main function and two helper functions:

1. `terraTCGAdata` allows the creation of the `MultiAssayExperiment` object from the different indicated resources.

2. The `getClinicalTable` and `getAssayTable` functions allow for the discovery of datasets within the Terra data model. The column names from these tables can be provided as inputs to the `terraTCGAdata` function.

## 2.1 Data

Some public Terra workspaces come pre-packaged with TCGA data (i.e., cloud data resources are linked within the data model). Particularly the workspaces that are labelled `OpenAccess_V1-0`. Datasets harmonized to the hg38 genome, such as those from the Genomic Data Commons data repository, use a different data model / workflow and are not compatible with the functions in this package. For those that are, we make use of the Terra data model and represent the data as `MultiAssayExperiment`.

For more information on `MultiAssayExperiment`, please see the vignette in that package.

# 3 Requirements

## 3.1 Loading packages

    library(AnVIL)
    library(terraTCGAdata)

## 3.2 gcloud sdk installation

A valid GCloud SDK installation is required to use the package. To get set up, see the Bioconductor tutorials for running RStudio on Terra. Use the `gcloud_exists()` function from the GCPtools package to identify whether it is installed in your system.

    library(GCPtools)

    ##
    ## Attaching package: 'GCPtools'

    ## The following objects are masked from 'package:AnVILGCP':
    ##
    ##     gcloud_access_token, gcloud_account, gcloud_cmd, gcloud_help,
    ##     gcloud_project, gcloud_storage, gcloud_storage_buckets, gsutil_cat,
    ##     gsutil_exists, gsutil_help, gsutil_pipe, gsutil_requesterpays,
    ##     gsutil_rsync, gsutil_stat

    gcloud_exists()

    ## [1] FALSE

You can also use the `gcloud_project` to set a project name by specifying the project argument:

    gcloud_project()

# 4 Default Data Workspace

To get a table of available TCGA workspaces, use the `selectTCGAworkspace()` function:

    selectTCGAworkspace()

You can also set the package-wide option with the `terraTCGAworkspace` function and check the setting with `getOption('terraTCGAdata.workspace')` or by running `terraTCGAworkspace` function.

    terraTCGAworkspace("TCGA_COAD_OpenAccess_V1-0_DATA")
    getOption("terraTCGAdata.workspace")

# 5 Clinical data resources

In order to determine what datasets to download, use the `getClinicalTable` function to list all of the columns that correspond to clinical data from the different collection centers.

    ct <- getClinicalTable(workspace = "TCGA_COAD_OpenAccess_V1-0_DATA")
    ct
    names(ct)

# 6 Clinical data download

After picking the column in the `getClinicalTable` output, use the column name as input to the `getClinical` function to obtain the data:

    column_name <- "clin__bio__nationwidechildrens_org__Level_1__biospecimen__clin"
    clin <- getClinical(
        columnName = column_name,
        participants = TRUE,
        workspace = "TCGA_COAD_OpenAccess_V1-0_DATA"
    )
    clin[, 1:6]
    dim(clin)

# 7 Assay data resources

We use the same approach for assay data. We first produce a list of assays from the `getAssayTable` and then we select one along with any sample codes of interest.

    at <- getAssayTable(workspace = "TCGA_COAD_OpenAccess_V1-0_DATA")
    at
    names(at)

# 8 Summary of sample types in the data

You can get a summary table of all the samples in the adata by using the `sampleTypesTable`:

    sampleTypesTable(workspace = "TCGA_COAD_OpenAccess_V1-0_DATA")

# 9 Intermediate function for obtaining only the data

Note that if you have the package-wide option set, the workspace argument is not needed in the function call.

    prot <- getAssayData(
        assayName = "protein_exp__mda_rppa_core__mdanderson_org__Level_3__protein_normalization__data",
        sampleCode = c("01", "10"),
        workspace = "TCGA_COAD_OpenAccess_V1-0_DATA",
        sampleIdx = 1:4
    )
    head(prot)

# 10 MultiAssayExperiment

Finally, once you have collected all the relevant column names, these can be inputs to the main `terraTCGAdata` function:

    mae <- terraTCGAdata(
        clinicalName = "clin__bio__nationwidechildrens_org__Level_1__biospecimen__clin",
        assays =
            c("protein_exp__mda_rppa_core__mdanderson_org__Level_3__protein_normalization__data",
            "rnaseqv2__illuminahiseq_rnaseqv2__unc_edu__Level_3__RSEM_genes_normalized__data"),
        sampleCode = NULL,
        split = FALSE,
        sampleIdx = 1:4,
        workspace = "TCGA_COAD_OpenAccess_V1-0_DATA"
    )
    mae

We expect that most `OpenAccess_V1-0` cancer datasets follow this data model. If you encounter any errors, please provide a minimally reproducible example at https://github.com/waldronlab/terraTCGAdata.

# 11 Session Info

    sessionInfo()

    ## R version 4.6.0 Patched (2026-05-01 r89994)
    ## Platform: aarch64-apple-darwin23
    ## Running under: macOS Tahoe 26.3.1
    ##
    ## Matrix products: default
    ## BLAS:   /Library/Frameworks/R.framework/Versions/4.6/Resources/lib/libRblas.0.dylib
    ## LAPACK: /Library/Frameworks/R.framework/Versions/4.6/Resources/lib/libRlapack.dylib;  LAPACK version 3.12.1
    ##
    ## locale:
    ## [1] C/en_US.UTF-8/en_US.UTF-8/C/en_US.UTF-8/en_US.UTF-8
    ##
    ## 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] GCPtools_1.3.0              terraTCGAdata_1.17.1
    ##  [3] MultiAssayExperiment_1.39.0 SummarizedExperiment_1.43.0
    ##  [5] Biobase_2.73.1              GenomicRanges_1.65.0
    ##  [7] Seqinfo_1.3.0               IRanges_2.47.1
    ##  [9] S4Vectors_0.51.2            BiocGenerics_0.59.2
    ## [11] generics_0.1.4              MatrixGenerics_1.25.0
    ## [13] matrixStats_1.5.0           AnVILGCP_1.7.0
    ## [15] AnVIL_1.25.1                AnVILBase_1.7.0
    ## [17] dplyr_1.2.1                 BiocStyle_2.41.0
    ##
    ## loaded via a namespace (and not attached):
    ##  [1] xfun_0.57            bslib_0.11.0         httr2_1.2.2
    ##  [4] htmlwidgets_1.6.4    lattice_0.22-9       vctrs_0.7.3
    ##  [7] tools_4.6.0          tibble_3.3.1         pkgconfig_2.0.3
    ## [10] BiocBaseUtils_1.15.1 rapiclient_0.1.8     Matrix_1.7-5
    ## [13] lifecycle_1.0.5      compiler_4.6.0       codetools_0.2-20
    ## [16] keyring_1.4.1        httpuv_1.6.17        htmltools_0.5.9
    ## [19] sass_0.4.10          yaml_2.3.12          later_1.4.8
    ## [22] pillar_1.11.1        jquerylib_0.1.4      tidyr_1.3.2
    ## [25] DT_0.34.0            DelayedArray_0.39.2  cachem_1.1.0
    ## [28] abind_1.4-8          mime_0.13            tidyselect_1.2.1
    ## [31] digest_0.6.39        purrr_1.2.2          bookdown_0.46
    ## [34] fastmap_1.2.0        grid_4.6.0           SparseArray_1.13.2
    ## [37] cli_3.6.6            magrittr_2.0.5       S4Arrays_1.13.0
    ## [40] promises_1.5.0       rappdirs_0.3.4       XVector_0.53.0
    ## [43] rmarkdown_2.31       lambda.r_1.2.4       httr_1.4.8
    ## [46] otel_0.2.0           futile.logger_1.4.9  shiny_1.13.0
    ## [49] evaluate_1.0.5       knitr_1.51           miniUI_0.1.2
    ## [52] rlang_1.2.0          futile.options_1.0.1 Rcpp_1.1.1-1.1
    ## [55] xtable_1.8-8         glue_1.8.1           BiocManager_1.30.27
    ## [58] formatR_1.14         jsonlite_2.0.0       R6_2.6.1