Intro to your Terra workspace

User Ed
  • Updated

Workspaces are the building blocks of Terra - a dedicated space where you and your collaborators can access and organize the same data and tools and run analyses together.

Learn how to set up and use everything you need to collaborate in a Terra workspace.

Workspaces: All your analysis needs in one place

Your Terra workspace can contain data, metadata, and analysis tools like workflows and Jupyter Notebooks. You’ll run, monitor, and troubleshoot your analyses right in the workspace. For provenance, there’s a record of all workflow submissions kept permanently in your workspaces tab. It's easy to collaborate by sharing the workspace with colleagues. 

Expand the sections below for more details about how to access the resources you need.

Terra-onAzure_Workspace-tabs-dashboard-data-analyses-workflows_Screenshot.png

  • The landing page (i.e., Dashboard) is your project overview - where you can document the questions you’re trying to answer, the data and analysis tools you'll use, etc. Good documentation makes your analysis easy to share (with others, as well as with your future self) and reproduce.

    Terra-on-Azure_Dashboard_Screenshot.png

    Editing the dashboard

    To start editing, click the pencil icon to the right of the About the Workspace header at the top. The dashboard uses the Markdown language, which lets you organize with headers and include links and additional references. 

    To learn how to make the most of your dashboard, see Documentation best practices.

    Useful details on the right

    Workspace details are populated automatically in the right column of the Dashboard (scroll down for screenshots). Expandable sections include:

    Workspace information
    The workspace creation date, date last updated, and your access level.

    Cloud information
    The cloud infrastructure, location, Azure Resource Group ID, workspace storage URL, and storage SAS URL. Here is where you can open the workspace storage file system (Google bucket structure in Google Cloud console).

    Workspace owners
    If you need access to the workspace, ask the workspace owners. 

    Workspace tags
    Only visible to owners, tags are useful for searching and indexing. 

    Notifications
    Toggle to be notified when a workflow submission finishes. 

    Screenshot 2023-10-30 at 1.56.09 PM.png

    Screenshot 2023-10-30 at 1.56.40 PM.png

    Screenshot 2023-10-30 at 1.56.29 PM.png

    Screenshot 2023-10-30 at 1.56.52 PM.png

  • Each workspace comes with its own Azure Cloud "blob" storage. Data generated by a workflow analysis as well as interactive analysis (i.e., notebook.ipynb) files are stored here by default. Your workspace cloud storage is located in the region of your Terra Environment AMA.

    To access the dedicated workspace storage

    Select the File icon in the right sidebar.
    Access-cloud-storage-in-your-Terra-on-Azure-workspace_Screenshot.png

    From here, you can create folders to organize your storage, as well as upload and delete data files. 

    To upload your own data

    Small numbers, small files (use Terra's file manager)

    Click the File icon in the right sidebar to display your workspace storage directory. You can upload smaller files from your local machine by clicking the upload button.

    Access-cloud-storage-in-your-Terra-on-Azure-workspace_Screenshot.png

    Large numbers and/or large data files (use AzCopy command line interface)

    You can also use AzCopy in a terminal to copy data from a local machine or other cloud storage.

    For more detailed instructions, see Bring your own data to Azure.

  • Like spreadsheets built right into the workspace, data tables help keep track of all project data, no matter where files are physically located in the cloud. This becomes especially useful as the number of participants or samples in your study grows.

    Genomic data

    ToA_sample-table_Screenshot.png

    Phenotypic data

    ToA_subject-table_Screenshot.png

    Tables spare you from copying/storing input data for a workflow analysis

    Analyze data stored in the cloud without copying files to workspace cloud storage. Associate generated data with inputs by writing outputs to the input data table. 

    Learn how to combine data from different studies or across datasets in a single table in this video.

  • Interactive analysis - built into your workspace

    Interrogate and visualize your data in real-time using JupyterLab, Terra's integrated interactive analysis app. JupyterLab runs on a virtual machine or clusters of machines in a workspace Cloud Environment.

    ToA_Analyses-tab_Screenshot.png

    Interactive app resources

  • Collect, configure (set up) and run workflows for bulk analyses from the Workflows page. Workflows are the sorts of repetitive analyses that can be automated, such as aligning sequencer reads or calling variants. You can set up and run a workflow by clicking on the workflow name in the card. To save cloud costs, call caching is available in Terra.

    ToA-Workflows-tab_Screenshot.png

    Finding the workflow you need

    Not a coding expert? Browse and import published workflows from a curated list or Dockstore, or import from GitHub by selecting from the options in the left column of the Workspaces page.

    ToA-Find-and-add-workflows_Screenshot.png

  • The Submissions History (on the left of the Workflows page) is where you can check on the status of all current and past workflow submissions. 

    Troubleshooting

    For additional details - error messages and logs - click the link in the Submission name column.

    ToA-Submission-History-in-Workflows-page_Screenshot.png

    Troubleshooting resourcesRead more in Troubleshooting Azure workflows.

  • To collaborate, you can share your workspace with all the data, tools, and generated data. Workspace owners control how much access collaborators have to resources, including funding, by assigning roles with different permission levels.

    ToA-Save-workspace_Screencapture.gif

    Learn more in How to collaborate in a shared workspace.

Explore curated workspaces or create your own

Showcase workspaces

You'll find a number of template and tutorial workspaces for different use cases in the Terra Showcase Library. To access the library, click the main menu icon (three horizontal lines) at the top left of any page and open Showcases in the Library menu.  

Screenshot of Terra Libraries in the main menu

You can filter by Cloud Provider to identify curated workspaces developed for Terra on Azure. 

To make your own copy 

If you find a workspace of interest that you want to clone, click the three dot action icon at the top right corner and select Clone from the menu. Choosing an Azure-backed Terra Billing project assures that the new workspace is in your Terra on Azure Environment. 

To create your own workspace

1. Go to Your Workspaces (select from the main menu by clicking the three parallel lines at the top right of any page in Terra). 

2. Click the blue + icon at the top of the page (next to Workspaces).

3. Fill in the Create a New Workspace popup with a unique name and choose an Azure-backed Terra Billing Project from the dropdown menu. 

Screenshot-of-workspace-page-with-arrow-pointing-to-the-blue-plus-sign-and-popup-to-create-a-workspace-with-an-Azure-billing-project-selected.png

 

Was this article helpful?

Comments

0 comments

Please sign in to leave a comment.