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.
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.
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:
The workspace creation date, date last updated, and your access level.
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).
If you need access to the workspace, ask the workspace owners.
Only visible to owners, tags are useful for searching and indexing.
Toggle to be notified when a workflow submission finishes.
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.
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.
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.
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.
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.
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.
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.
For additional details - error messages and logs - click the link in the Submission name column.
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.
Learn more in How to collaborate in a shared workspace.
Explore curated 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.