1 of 26

Session 02: Using Terra for data discovery and access

Allie Hajian

Data Sciences Platform, Broad Institute

2 of 26

Learning Objectives

Understand how the Terra platform fits into the AnVIl ecosystem�
Understand how to use the components of cloud-native Terra for research

Data
Bulk Analysis
Interactive analysis
Security�

Understand the function of billing and permissions in Terra�
Understand how to protect controlled-access data with Authorization Domains

3 of 26

The Big Data Problem

Research relies on vast stores of data generated by individual labs and large community-wide projects

How can researchers take advantage of this wealth of information?

… find and download the right data?

…interpret the format correctly?

…perform computations quickly?

Data is getting too big to practically download and store!

4 of 26

Solution: use the cloud to share data

Traditional Way�Bring data to the researchers

Cloud Way�Bring researchers to the data

Problems

Data sharing = data copying

High storage costs

Individual security implementations

Solutions

True data sharing

Store once, access by many

Centralized security implementation

5 of 26

Leveraging the Cloud for Research

Oct 2017: https://medium.com/@benedictpaten/a-data-biosphere-for-biomedical-research-d212bbfae95d

“…we propose the idea of creating a vibrant ecosystem… containing modular and interoperable components that can be assembled into diverse data environments”

6 of 26

How should a data biosphere be structured?

Modular	Comprised of functional components with well-specified interface
Community focused	Created by many groups to foster a diversity of ideas
Open	Open-source licenses, software, architecture to enable extensibility
Standards Based	Consistent with standards developed by coalitions such as GA4GH

7 of 26

A cloud-based analysis platform to access and analyze data

8 of 26

NIH Interoperability Example

TOOLS

WORKSPACES

Scientific Discoveries

NHLBI DATA

(TOPMed)

Dockstore

NHGRI DATA

(CCDG, CMG)

BRING YOUR OWN DATA

9 of 26

Terra: An end-to-end, cloud-native platform

10 of 26

The Workspace - The fundamental unit in Terra

It all starts with the Terra workspace, your dedicated project space. The landing page gives an overview of the project components you’ll bring together:

1) Documentation Edit the dashboard in markdown to ensure collaborators and others can understand and reproduce your work

2) Data – Keep track of all project data no matter what size or where it is with built-in tables

3) Two modes of analysis tools

Notebooks (i.e.Interactive analysis) Python or R-based Jupyter notebooks.

Bulk analysis workflows

4) Job History which allows you to monitor and troubleshoot bulk analysis submissions

-------------

Transition: Let’s look closer at each of these…

We are going to interact with the workspace a little more in our hands on, but this is basically what it looks like. Review tabs and what they contain.

11 of 26

Organize data and tools in the Terra workspace

12 of 26

Data in dedicated CCDG and CMG workspaces

13 of 26

Two different modes of computation

Bulk analysis workflows �Some jobs take a while, so launch them and come back later! (WDL and Cromwell)

Interactive analysis

Run R or Python via Jupyter Notebooks, or run shell scripts on the terminal
Interrogate data in real time
Interactive Jupyter Notebooks
GWAS with Hail

14 of 26

Accessible, findable bulk analysis tools

Align & QC sequence data per sample
Call short variants per sample
Joint-call across population
Filter & QC variants

Broad Methods�Repository

15 of 26

Interactive analysis with Jupyter Notebooks

16 of 26

Containers for portability and reproducibility

GATK 2.8

Java 7

R 2.5.0

GATK 4.0

Java 8

R 3.0.1

BWA

Picard

A Docker container encapsulates

all the software dependencies associated with running a program

Takes the guesswork out of running workflows or notebooks on different platforms.

Standardize the analysis environment by specifying a Docker container that includes the exact libraries and packages used for your analysis.

Anyone using the same Docker image will get the same results

Containers are a way to standardize computing environments making it easier to set up standardized computing environments and ensure reproducibility. I’m sure many of you had to work with the same data on more than one computer and you’ve run into problems with either the version of software or having a dependency on the right form of JAVA? It hinders your progress and if you don’t have the right versions, it might change your results. Containers eliminate these issues.

-------------

A Docker container is a package that holds software and all of its dependencies
The Docker takes care of software requirements, makes it easy to set up the right environment with the dependencies you need without having to worry about it
They’re like a Virtual Machine with an isolated environment where you can control the software installed – the version and libraries – and the compute power
By controlling exactly what version of GATK, Picard and BWA you used, you enable others to use those same versions to reproduce your results

------------

Transition: If you want to explore or try out any of these tools, we have preloaded featured workspaces that showcase different workflows and Jupyter Notebooks

17 of 26

Curated analyses in pre-loaded Showcase Workspaces

18 of 26

How to collaborate and share in Terra

Workspaces are shareable and you’re in control

Invite people to work with you; control who has access to the research assets in your workspaces

Workspaces are private by default. Sharing permissions include:

Reader
Writer
Owner

Enforce privacy and security with Authorization Domains

Owners of controlled-access data can restrict the list of people with whom

any derived workspaces can be shared

19 of 26

Security is a priority that’s built in to the platform

Certified FISMA moderate from the NCI for hosting controlled-access data owned by NCI and the NIH

Leverages security features in Google Cloud Platform for Federal Risk and Authorization Management Program (FedRAMP) authorization

15-minute timeout for clinical researchers�

Terra configures workspace resources appropriately so you can work confidently in the cloud and spend less time and effort on management

20 of 26

Workspace permissions set data access, billing

To manage access to resources, resource owners will assign permissions (roles) to individuals or groups.

Examples of resources

Terra Billing Projects
Workspaces (including data stored in the workspace bucket)
Workflow collections

Examples of roles

Owner - may add/remove users (grant access), lock workspace, etc.
Writer - may write to the metadata, method configs, etc.
Reader - may read the metadata, method configs, etc.
Can-compute - able to launch batch compute and interactive analyses (notebooks)
Share-writer - able to grant others write access
Share-reader - able to grant others read access

21 of 26

How workspace permissions set data access

Shared data resources

Workspace #1

Generated data

Workspace #2 (clone)

User A is owner

Shares with User B (writer - can copy)�
User B can access shared data�
User A’s Billing Project covers all costs

User B is owner

User B’s Billing Project covers costs
Shares with User C �(writer - can compute)

Note: User C now has unauthorized access to derived data

This scenario illustrates how using permissions alone can lead to unauthorized access

22 of 26

How much it costs and how to pay

Terra itself won’t cost you anything - To enable scientists to get work done, the open-source platform is available and free for everyone

Pay only for what you use - Storage, compute, and egress

Terra Billing Accounts linked to Google Billing - Securely-configured billing project linked to Billing Account on the Google Cloud Platform can be shared with members of your lab or department for use in Terra.�

Institutional billing accounts �
STRIDES�
Free credits

23 of 26

Protecting Controlled-Access Data

Terra uses Authorization Domains to enforce limits on data access

Workspace access only to users in the Authorization Domain
AD stays with workspace copies
Protects all data in the workspace

Phenotype data
Derived data
Data from multiple sources

24 of 26

How Authorization Domains protect data

Authorization� Domain #1

User A and User B

Shared data resources

Workspace #1

User A is owner

Generated data

Workspace #2 (clone)

User B is owner

Authorization� Domain #1

User A and User B

User B cannot share with anyone outside the Authorization Domain.

Any new collaborator must be added to the Authorization Domain to access the shared or generated data resources

This scenario demonstrates how Authorization Domains work to protect controlled-access data from unauthorized use CLICK for animation

User A sets up Authorization Domain #1 including User A and User B only as authorized for access

He then creates Workspace #1 with AD#1 and stores shared, controlled-access data in the workspace bucket

Only Users A &B, in the AD, can access the data (CRAM files in Google bucket, phenotypic data in tables)

CLICK for animation

User B, also in AD#1, clones Workspace #1:

Workspace #2 inherits AD #1 and includes the data tables with i. Phenotypic data and ii. Links to CRAM files in Workspace #1
User B can run workflows, for example, to generate VCF files from CRAM files in Workspace #1’s bucket
Only Users A & B can access the generated data and the phenotypic data

CLICK for animation

Terra takes care of the details so you don’t have to.

Transition: Let me mention a couple of important things to know about Authorization Domains...

25 of 26

Authorization Domains Instructions and Caveats

Authorization Domains must be set up before creating a workspace. You cannot apply or change Authorization Domains for an existing workspace.

Include all collaborators that you want to share your data with. Note that this list can be updated!

ADs protect access to all data, including derived files

Create a Group from the main menu (top left). Note this is also where you can AD members.

2. Select the group as an authorization Domain when creating a workspace

A couple of caveats… and instructions CLICK for animation

Authorization Domains must be set up before creating a workspace. You cannot apply or change Authorization Domains for an existing workspace

Since you know you have to create an Authorization Domain before you create the workspace, how do you create one? CLICK for animation

Step one is to create a Group - start from the main menu (we’ll cover this in the walkthrough) CLICK for animation

Next is to select the Group as an Authorization Domain when creating a workspace CLICK for animation

Include all collaborators you want to share data with. This list can be updated! CLICK for animation

And finally, Authorization domains protect access to all data, including derived files.

Transition: We’ve covered a lot of ground. Last but not least, let’s talk about costs.

26 of 26

anvil.terra.bio

Spend time doing science… �Not wrangling software

For hands-on practice try