Accessing TCGA controlled-access workspaces in Terra

Tiffany Miller
  • Updated

How to access and use the dedicated TCGA controlled-access data workspaces on Terra. 

How to access TCGA Controlled Data workspaces

To use TCGA Controlled Data in Terra, you must follow two steps. 

Step 1. Have an eRA Commons or NIH account with dbGaP authorization 

For instructions on how to set up an eRA Commons or NIH account with dbGaP authorization, follow this link.

Step 2. Link to your eRA Commons/NIH Account and the NCI CRDC Framework Services

2.1. Go to your Profile page by selecting the main menu icon in the top left from any page in Terra

2.2. Log in with your NIH credentials

Screenshot of linked NIH account


What to expect

Once you meet these requirements, you will receive Reader access to all prepopulated TCGA Controlled-Access workspaces.

Derived data from Controlled-Access workspaces

The National Cancer Institute (NCI) and dbGaP consider any data derived from TCGA Controlled Data to also be TCGA Controlled Data.

Terra users can derive data (also controlled-access) from Controlled Data by

  • Cloning a TCGA Controlled-Access workspace and running analyses in the cloned workspace

  • Creating a new workspace, copying entities referencing Controlled Data into the new workspace, and running analyses in that workspace

Rather than track specific data objects as "controlled-access", Terra identifies workspaces as TCGA Controlled-Access, and restricts access to those workspaces to users who meet the requirements above.

Creating and cloning a TCGA Controlled-Access workspace

When you create a new workspace, you can add the "TCGA-dbGap-Authorized" group to the Authorization Domain to protect any TCGA Controlled Data in your workspace. Once a workspace has this Authorization Domain set up, it remains a TCGA Controlled-Access workspace.

When you clone a TCGA Controlled-Access workspace, the cloned workspace will automatically have "TCGA-dbGap-Authorized" group in the Authorization Domain.

If you are granted access (Reader, Writer, or Owner) to a TCGA Controlled-Access Workspace but don't meet the requirements listed above, you can view the workspace in your workspaces list, but won't be able to open it. For example, this may occur if another user shared a TCGA Controlled-Access workspace with you but your dbGaP authorization has not yet been approved or the linkage of your Terra and eRA Commons accounts has expired.

If you can't enter a TCGA Controlled-Access workspace, but believe you have dbGaP authorization for Controlled Data, you may need to relink your eRA Commons / NIH account. Go to "Main Navigation" --> "User Profile" to check your dbGaP authorization status. If your login has expired, click Log-In to NIH to relink your account.

Sharing a TCGA Controlled-Access workspace

If you are the Owner of a TCGA Controlled-Access workspace, Terra won't prevent you from sharing the workspace with a user who doesn't meet the requirements to access Controlled-Access workspaces. However, these users won't be able to access the workspace you shared unless they met the requirements (above).

Google buckets for TCGA Controlled-Access workspaces

Google buckets associated with TCGA Controlled-Access workspaces will be accessible to Terra users who

  1. Meet the requirements for TCGA Controlled-Access workspaces
  2. Have the appropriate permission (Reader, Writer, or Owner) for that workspace

Users who meet these requirements can access the buckets using the workspace Summary tab or gsutil.

Copying entities from TCGA Controlled-Access workspaces

To copy entities from a Controlled-Access workspace, the destination workspace must also be in the Authorization Domain with the "TCGA-dbGap-Authorized" group. When copying entities to an open-access workspace, Terra won't offer the choice to copy from a Controlled-Access workspace.

Disclaimer about TSV load files

Terra doesn't identify controlled-access data within TSV load files. Therefore, Terra can't prevent users from uploading TSV Load Files referencing controlled data to an open-access workspace.

All users accessing controlled-access data are bound by the dbGaP TCGA DATA USE CERTIFICATION AGREEMENT (DUCA).

In addition, users must adhere to Terra's Terms of Service.

Was this article helpful?

1 out of 1 found this helpful



Please sign in to leave a comment.