An introduction to workspaces

  • Updated

What is a Workspace?

All Researcher Workbench analyses happen within the context of a workspace. A workspace is your place to store and analyze data for a specific project. You can share this workspace with other users, allowing them to view or edit your work. 

For each project, we recommend that you create a new workspace. When creating a new workspace, you can choose from the Registered Tier dataset or the Controlled Tier dataset. To learn more about the difference between Registered Tier and Controlled Tier datasets, you can read more here. To gain access to the Controlled Tier dataset, your institution needs to sign an Institutional Data User Agreement provisioning access to that tier (visit to submit a request, if your institution has not signed one and you would like access). For more information, please refer to the article found here. Whether choosing either Registered Tier or Controlled Tier, the workspace will always default to the most recent version of each dataset available in the Curated Data Repository (CDR). 

Note: You may not start a new workspace using an archived dataset, unless you are attempting to replicate a published study that utilized a previous version of the CDR.

You will also need to set up a billing account.  For more information, see our article  Initial credits and how to create a billing account. Access to the All of Us Researcher Workbench is free, but because data analysis occurs in the Google Cloud environment, we do require you to pay for your own compute time once you have used all of your initial credits.

Next, you will select the primary purpose of your project from the menu displaying the following options (in the form, you will be encouraged to select all that apply):

  • Disease-focused research
  • Methods development/validation study
  • Research control
  • Genetic research
  • Social/behavioral research
  • Population health/public health research
  • Drug/therapeutics development research
  • For-profit research
  • Educational purpose
  • Other purpose

You are required to provide the reason you are choosing to use All of Us data for your investigation, the specific scientific question(s) you intend to study, and the anticipated findings from the study. Please keep in mind that the responses you provide will be posted publicly on the All of Us Research Hub website to inform research participants on how their data are being used. Click here for examples to help with completing this section.

An important characteristic of the All of Us participant cohort is that it includes groups that have been historically underrepresented in biomedical research. We ask that you indicate if your study will focus on a specific population(s) or if you intend to study a phenotype, disease, or condition with a focus on comparative analysis of a specific demographic group (for example, a group based on race and ethnicity, gender, or age).

You are also given the opportunity to request a review of your research purpose by the Resource Access Board for potential stigmatization of research participants. This is not required. You can still create a workspace and begin your study if you choose to have your research purpose reviewed.

After creating your workspace, you will be directed to the Data tab in your new workspace. The other tabs you will see are Analysis and About.

From the Data tab you can create new cohorts and datasets.

  • A cohort is a group of participants created based on specific criteria that you define. 
  • A dataset is a table containing data (i.e., concepts) about a cohort. You can export a dataset for analysis in a notebook. 

From the Analysis tab you can create new notebooks or access notebooks created when you export a dataset to a notebook. 

The About tab gives you a look back at the information you provided when creating your workspace, such as the primary purpose of your project and the area of intended study. Here, you can also see which version of the All of Us dataset your workspace is accessing, the date you created the workspace, and whom you have designated as collaborators on your workspace.

Note: If you have access to Controlled Tier, any notebooks created using Controlled Tier data will display a small orange shield in the bottom right corner of the thumbnail, as shown below: 



Duplicating, Editing, Sharing, and Deleting a Workspace

After you create a workspace, you have the option to duplicate it, edit the About section (e.g., changing the primary purpose of your project), share it with collaborators, as well as delete it permanently. 


Duplicating a workspace

To duplicate a workspace, click on the three dots at the top right of your workspace screen Ellipses.png, then select Duplicate


Next, you will want to rename your new, duplicated workspace and make any needed changes to the workspace description prompts on that page. 


When you are finished, click Duplicate Workspace at the bottom of the screen.



Editing a workspace

To edit a workspace, click on the three dots at the top right of your workspace screen Ellipses.png, then select Edit


Next, you will be taken to the page where you can edit the About section of your workspace.


When you are finished, click Update Workspace



Sharing a workspace

To share a workspace, click on the three dots at the top right of your workspace screen Ellipses.png, then select Share


In the next prompt, enter the name of the person you would like to share your workspace with in the search bar (they must also be a Registered Tier researcher). You will then need to assign them a role, either as a "reader," "writer," or "owner." If you click the Workspace_Info_Icon.png in the top right corner, you will be provided with a description of each role. They are also listed below:

  • Reader: can view notebooks, but can't edit them. Readers can't delete or share contents of the workspace.
  • Writer: can view notebooks and edit them, as well as delete files in the workspace bucket. They can't delete or share workspaces.
  • Owner: can view notebooks and edit them, as well as delete workspace bucket files. All owners can delete and share workspaces, so make sure you're only providing this level of access when necessary

The workspace will use the billing credits associated with the account of the person who created the workspace (creator, which is separate from the owner and can't be changed). For more information about billing, check out the Paying for Your Work in the Researcher Workbench section in the Getting Started category or search our FAQs.

When sharing a Controlled Tier workspace with a collaborator, all collaborators must also have access to the Controlled Tier dataset.  If the researcher does not yet have access, when they try to enter the workspace, a prompt will ask them to complete additional requirements as detailed in this article here.

When you have assigned your collaborator a role, click Save.



Deleting a workspace

To delete a workspace, click on the three dots at the top right of your workspace screen Ellipses.png, then select Delete.


When you click Delete, you will be asked to confirm that you want to delete the workspace. Click Delete Workspace to permanently delete your workspace.


Note: If you delete a workspace, your research purpose will remain accessible on the All of Us Research Hub public website, however, all data tied to your workspace will be deleted and will not be able to be recovered. 

If you delete a shared workspace, you will be deleting this workspace for everyone collaborating on the workspace.

Was this article helpful?

4 out of 5 found this helpful

Have more questions? Submit a request



Article is closed for comments.