Getting Started in the new Researcher Workbench 2.0

The new Researcher Workbench brings a refreshed user experience, optimized tools, enhanced performance, and more to your research journey. The following getting started guide includes information for accessing and exploring Researcher Workbench 2.0. For a video overview, see the Office Hours session Researcher Workbench 2.0. 

For a PDF copy of this guide, see here. 

Table of Contents

• Introduction to the Researcher Workbench 2.0
• Accessing Researcher Workbench 2.0
• Exploring Researcher Workbench 2.0
  • How to create a workspace
  • How to add a data collection to your workspace
    • Data Collections and Data Collection policies
• To navigate a workspace
• Analysis Tools
  • Data Explorer
• Billing and Managing Cost
• Sharing Feedback

Introduction to Researcher Workbench 2.0

Researcher Workbench 2.0, powered by Verily Pre, enables researchers to access, analyze, and collaborate on complex biomedical datasets by expanding the analysis capabilities and user experience. 

Similar to the existing Researcher Workbench, the updated Researcher Workbench can be used by researchers at varying levels of computational expertise and skill through the point-and-click interfaces and customizable programming tools. Opting for Researcher Workbench 2.0 allows users to explore its enhanced features, including access to Jupyter Lab, a new Data Explorer, and integration with Git repositories. Users will still have the capability to use All of Us initial credits in Researcher Workbench 2.0 or create their own billing pod.

Additional resources

Accessing Researcher Workbench 2.0

You can access the Researcher Workbench 2.0 using your @researchallofus.org credentials. Please ensure your data access requirements are up to date before login to Researcher Workbench 2.0. 

Access to Researcher Workbench 2.0

1. Navigate to the Researcher Workbench at https://workbench.researchallofus.org/login. 
2. Upon login, on the landing page, you will see a section that says "Migrate your Workspaces to Researcher Workbench 2.0". 
   • Select “Go to My Workspaces” to review your workspaces and begin migration.
   • Note: If you wish to create a workspace in Researcher Workbench 1.0, select “+ Create Legacy Workspace.”

3. Before migrating, you must log into Researcher Workbench 2.0 and accept the Terms of Service. In Workspaces, you will select “Open Verily Workbench”.

4. You will be redirected to https://workbench.verily.com/ and prompted to input your login credentials. 

5. Select “Continue with Google” and log in with your @researchallofus.org credentials. Note: If you do not know your login credentials, email support@researchallofus.org.

6. You will be prompted to agree to the Terms of Use and Privacy Policy. When prompted, review and click “Accept and continue.”

Note: You will only need to review and accept the Terms of Use and Privacy Policy the first time you log in to Researcher Workbench 2.0.

7. After you log in and accept the Terms of Use and Privacy Policy, Researcher Workbench 2.0 will launch. 

Note: Workspaces created with Researcher Workbench 2.0 will not be listed in the main All of Us Researcher Workbench landing page.

In order to see a full list of your Researcher Workbench 2.0 workspaces, please select “Workspaces” on the Researcher Workbench 2.0 landing page to see a comprehensive list.

Exploring Researcher Workbench 2.0

The new Researcher Workbench has similar and expanded functionality and concepts in comparison to the existing Researcher Workbench.

How to create a workspace

There are two ways to create a workspace – directly on the home landing page, or from within the Workspaces page. Full instructions for creating a workspace are listed here. 

1. Select “+New Workspace” on the Researcher Workbench 2.0 landing page or under “Workspaces” tab.
2. Complete information about the workspace via the three dialogue pages noted here. The workspace name and pod are required; other prompts may either be optional or prefilled. Please review the “Workspace setup” to learn more about the fields to include. Specifically, you will need to know the following: 
   • Billing pod information (All of Us Credits or your own GCP billing account).
     • Note: Once you select a billing pod for the workspace, it cannot be changed. You will be required to duplicate the workspace to add a new billing pod. 
   • Summary of the workspace to provide an overview description.
3. Click the “Create workspace” button on the last screen. It may take several minutes for the workspace to create.

4. Once your workspace is created, you will then need to add your All of Us Data Collection in the Resource tab in order to access the All of Us dataset. 

   
    

Note: Workspaces created with Researcher Workbench 2.0 will not be listed in the main All of Us Researcher Workbench landing page.

In order to see a full list of your Researcher Workbench 2.0 workspaces, please select “Workspaces” on the Researcher Workbench 2.0 landing page to see a comprehensive list.

Workspace setup

When you create a workspace in the Researcher Workbench 2.0, you will be prompted to enter workspace details such as “workspace name” and “summary” of the workspace. Additionally you will be prompted to select a pod. Billing pods are created and linked to a Google Cloud Platform billing account. Consider a billing pod as the GCP billing account. When setting up your workspace, use the following as an example: 

• Pod: Example using All of Us initial credits - “user-pod-<username>-XXXX”
  • If your username is moirad@researchallofus.org your All of Us initial credit billing pod would be “user-pod-moirad-XXXX” with XXX being a random string. 
  • If you would like to use your own GCP billing account, see instructions here to set up your billing pod in the new Researcher Workbench. 
    • Note: Once you select a billing pod for the workspace, it cannot be changed. You will be required to duplicate the workspace to add a new billing pod.
• Group Policy: “No, don’t apply policy”
  • Note: Once you add an All of Us data collection, a group policy will be enforced. Learn more about the data collection policies here. 
• Region: us-central1 (Iowa)

How to add a data collection to your workspace

After you create a workspace, you can add a data collection to that workspace. You will add either the “All of Us Registered Tier” or “All of Us Controlled Tier” to your workspace via the Resources tab of your workspace.  

1. In the workspace, navigate to the Resource tab. Select Data from Catalog. 

   

2. Select the Data Collection of your choice. The All of Us Registered and Controlled Tiers will be available. 

   

3. Select appropriate resources in the Data Collection. For example, for All of Us Registered Tier data, you will select R2024Q3R8, which is CDRv8 Registered Tier. 

   A full list of CDR versions are noted in the Data Dictionary here. 

   • CDR v8 Registered Tier = R2024Q3R8
   • CDR v8 Controlled Tier = C2024Q3R8

1. Review the Data Collection policies, complete the “Researcher Use Statement Questions,” and select “I'm sure. I understand that all policies and terms above will be permanently applied to this workspace.”

   

2. You will have the option to select where in your resources you want this data collection to live. We recommend using your workspace folder path.
3. Select “Add to your workspace.” 

Data Collections and Data Collection policies 

Data Collections Policies

Data collections are curated datasets published in Verily Pre, the platform that powers the Researcher Workbench 2.0.  There are currently two All of Us data collections available in the new Researcher Workbench 2.0: CDRv8 “All of Us Registered Tier” and “All of Us Controlled Tier.” These two data collections are synonymous with the curated datasets available in the legacy Researcher Workbench. When you log in to the Researcher Workbench using your @researchallofus.org username, you will automatically be provided access to any All of Us data collections for which you have completed the associated data access requirements. The same data access requirements that you are familiar with from the legacy Researcher Workbench (e.g., ID verification, Responsible Conduct of Research Training, Data User Code of Conduct attestation, etc.) are in place for gaining access to these data collections.

All data collections available in the Verily Pre platform, including the All of Us Research Program data collections, come with data collection policies that explicitly delineate built-in technical parameters to enforce data access and use restrictions. The same parameters are in place for All of Us data on the legacy Researcher Workbench. These parameters, for which Verily Pre broadly uses the term ‘policy,’ are distinct from the All of Us data access and use policies that you are already familiar with, which outline the program’s rules for access and use of All of Us data on the Researcher Workbench. These All of Us policies have not changed, and researchers are still responsible for reviewing and complying with them independent from the data collection policies.  

When adding either the Registered Tier or Controlled Tier data collection to your workspace, you will be prompted to first review the data collection policies. Please note the selections for the data collection policies are automatically set by the All of Us Research Program and cannot be changed.

After reviewing and accepting the data collection policies associated with your workspace, you will be prompted to complete the Researcher Use Statement Questions , which includes the same questions as the Workspace Description form in the legacy Researcher Workbench. 

This guide describes each type of data collection policy that applies to the All of Us data collections. 

• Region Policy
• Network Policy
• Perimeter Policy
• Group Policy 
• Researcher Use Statement Questions

Region Policy

A region policy is a type of policy that limits which regions of a platform, like Workbench 2.0, may be used to create cloud resources and apps. The Researcher Workbench 2.0 uses Google Cloud Platform (GCP), and will utilize regions within GCP. All of Us data collections and workspaces are restricted and automatically assigned to the region us-central1(Iowa). When you create a workspace in Researcher Workbench 2.0, it will automatically keep cloud resources and apps created in the workspace within this region. This is the same region restriction that exists in the legacy Researcher Workbench. 

Perimeter Policy

A perimeter policy restricts data movement - such as copy, transfer and retrieval of data -  to the cloud boundaries. It limits copy, transfer and retrieval of data. In the Researcher Workbench 2.0, data collections and workspaces can be placed within a perimeter to enforce these limits. The All of Us Research Program requires workspaces using All of Us data collections (Registered Tier and Controlled Tier) to be restricted within a perimeter, and each workspace can belong to only one perimeter. A workspace perimeter is automatically and permanently assigned when you add an All of Us data collection to your workspace (see image below). 

Group Policy

A group policy limits workspace access and data sharing to users of the selected groups. The All of Us data collections group policy only allows users with the affiliated @researchallofus.org usernames to access a workspace that has an All of Us data collection in it. To collaborate on a workspace, all users must be approved for access to the data collection attached to the workspace. For example, only users who have access to Controlled Tier data can access workspaces with the All of Us Controlled Tier data collection in it. Users are automatically added to the All of Us data collections once they complete applicable data access requirements. Similar to the legacy Researcher Workbench, users are not allowed to add both Registered and Controlled Tier data collections to your workspace, meaning you are only able to add Registered Tier or Controlled Tier data collections to a given workspace.

Researcher Use Statement Questions

The All of Us Data User Code of Conduct (DUCC) requires researchers to provide transparency into their study plans for each workspace. Before you can create a workspace, you must provide a thorough, meaningful description of your research project and study plans in the  “Workspace Description Form”. These questions are the same as the prompts provided in the Workspace Description Form in the legacy Researcher Workbench. 

To navigate a workspace 

Each workspace includes four tabs: Overview, Resources, Apps, and Workflows.

1. The Overview tab includes an editable version of the workspace description provided during the workspace creation process. Note: When adding an All of Us data collection, you must adhere to the policies attached to the data collection. At that time, you will enter information such as the workspace description information under the “Researcher Use Statement Questions.” Learn more here. 

2. The Resources tab houses the data resources for facilitating analysis. In many cases, resources are simply multimodal data that can be managed within a workspace. There are two main types of data resources in Verily Workbench: 

• Object-based data resources contain files and folders (i.e., storage buckets and objects).
• Tabular data resources contain BigQuery datasets and tables (i.e., All of Us Curated Data Repositories [CDRs], aka data collections).

3. The Apps tab includes the cloud computing resources such as JupyterLab, R Analysis Environment, Visual Studio Code, etc.

4. The Workflows tab is where you can add, run, and monitor workflows after they have been added to the workspace.

Tutorial Workspace

The All of Us Researcher Workbench 2.0 tutorial workspace, “All of Us Tutorial Workspace: Getting Started with Registered Tier Data (v8)” and "All of Us Tutorial Workspace: Getting Started with Controlled Tier Data (v8)" helps researchers get started accessing All of Us data in Researcher Workbench 2.0. These workspace demonstrate how to set up a workspace in Verily Workbench and how to access the All of Us V8 datasets.

You have received reader access to the “All of Us Tutorial Workspace: Getting Started with Registered Tier Data (v8)” and "All of Us Tutorial Workspace: Getting Started with Controlled Tier Data (v8)." To work in the workspace, please duplicate the workspace using the following steps: 

1. On the landing page of the Researcher Workspace, this tutorial workspace will be listed. Alternatively, you can navigate to “Workspaces” and it will be listed there. We recommend you “favorite” this workspace.

2. You will only have read-only access to the tutorial workspace. To access contents of the workspace, duplicate the workspace as shown below. 

3. Follow the prompts on the pop-up screen to duplicate the workspace. You can rename the workspace and change any editable field. 

4. After completing the prompts, open the duplicated workspace and dive into exploring All of Us data with the updated Researcher Workbench. 

Additional resources

Analysis tools

Researcher Workbench 2.0 allows for new and improved computation analysis tools such as JupyterLab, R Analysis Environment (i.e., RStudio), Visual Studio Code, and workflow tools. 

At beta launch, some applications and features will be limited in Researcher Workbench 2.0. Learn more in the support article What to expect during the Researcher Workbench Migration. 

At beta, you will be able to use the following: 

• JupyterLab 
• R analysis environment (aka RStudio)
• Workflow tools (Cromwell, Nextflow, dsub via command line (CLI) and UI tools)
• Data Explorer
• Expanded cloud environment settings 
• Two new NVIDIA GPU - accelerated libraries
  • JupyterLab - NVIDIA NeMo for AI Development (NeMo)
  • JupyterLab - NVIDIA Parabricks and CUDA-X Data Science
    • Please note: these environments are resource‑intensive and can incur significant computational costs. Be sure to review the associated expenses and confirm appropriate cloud resource allocations before provisioning these environments.

Additional resources

Data Explorer

In Researcher Workbench 2.0, cohorts and datasets will be created through the new Data Explorer, powered by Verily Pre. This updated tool is similar to the Cohort Builder and Dataset Builder in Researcher Workbench 1.0, and lets you visually explore data, design custom cohorts, and export datasets directly to your workspaces.

You can start working with it by creating a cohort in the Resources tab of your workspace. For a step-by-step guide to creating a cohort, see support article New Data Explorer in Researcher Workbench 2.0.

Billing and Managing Cost

Similar to the existing Researcher Workbench, computational costs are incurred based on the amount of data used, the analysis tools used, any environment customizations, and storage usage. 

When you create a workspace in the Researcher Workbench 2.0, you will be prompted to select a pod. Billing pods are created and linked to a Google Cloud Platform billing account. Consider a billing pod as the GCP billing account. In the Researcher Workbench 2.0, you can use your All of Us initial credits, but once initial credits are exhausted or expire, a Google Cloud Platform (GCP) billing account must be set up to proceed with analyses on the Workbench.  

Adding All of Us Credits to your workspace

To use your All of Us initial credits in the Researcher Workbench 2.0, you will select the pod with your name formatted like “user-pod-<username>-XXXX.” For example, if your All of Us username is jane.doe@researchallofus.org your All of Us initial credit billing pod would be “user-pod-jane-doe-XXXX” with XXX being a random string. 

Adding your own billing pod to your workspace

To create a billing pod in the new Researcher Workbench, the first step is to set up a Google Cloud Platform (GCP) billing account if you do not have one already. You have two options: via a self-managed GCP Billing Account or through a third-party reseller. To learn more about establishing a GCP billing account, see Paying for Your Research. 

Once your GCP billing account is established, you will need to grant permission to the workbench to use the billing account. To do so you can follow the detailed steps here. 

1. Log in to GCP Console Billing.
2. Select the billing account to be used.
3. Choose “Account Management” on the left hand panel.
4. Navigate to “My Billing Account” on the right hand panel.
5. Select “Add Principal.”
6. Add billing@workbench.verily.com as a "Billing Account User" and save.

After you create your GCP billing account or receive permission from your research team to use an existing one, you will complete a couple of tasks to set up use within the Researcher Workbench 2.0.

1. In the Researcher Workbench 2.0, select your profile > “Linked accounts”
2. Select “Link Account” under the Google section.
3. This will bring up a dialog window. You will need to sign in with your @researchallofus.org username and check the "View and manage your Google Cloud Platform billing accounts" box.

4. Allow Verily Workbench access to the GCP account. 

   

• To later unlink your account, you can click the “Disconnect” button.

  

5. After you have linked your account, create the new pod. You will need to know the 18-character Google Billing account ID of the GCP account that you want to use. Navigate back to the Researcher Workbench 2.0 landing page. Select “Pods” on the left hand menu. 

   

6. On the next page, select “New Pod” on the upper right hand side. 

   

7. Enter in the appropriate information related to the GCP billing account for this pod. Then select “Create Pod.”

   

8. After pod creation, you can view your new pod under the “Pods” page. This page will show both the pods that you have created, and those to which others have granted you access.
9. You can now use the pod when creating new workspaces.

Additional Resources

Sharing feedback

Your feedback is invaluable to us. Using the Feedback for Researcher Workbench 2.0 form, you can provide different types of feedback:

• Experience with Researcher Workbench 2.0: Share your experience with the various features and products of the new Researcher Workbench.
• Feature or tool: Recommend a feature or tool for the new Researcher Workbench (e.g., analysis tools, workflow recommendations, etc.).

You may complete the feedback form multiple times, and we encourage you to share your initial feedback. 

If you have any questions regarding the new Researcher Workbench, please contact us at support@researchallofus.org. 

• Public Beta - Getting Started in the new Researcher Workbench.pdf3 MB