How to add workspace-level input data (workspace data table)

Liz Kiernan

Learn how to generate a dedicated table to hold workspace-level resources such as reference files or Docker containers. 

Why use a Workspace Data table?

The Workspace Data table can hold variables and resources - like the genomic reference sequence file, or a Docker container - that stay the same regardless of the particular sample data analyzed. Keeping these workspace-level resources in one place can make your analysis more efficient. 

Save time and reduce errors

The Workspace Data table lets you configure resource files once and point to them in the workflow configuration pane whenever you need them. You don't need to look up reference file paths (URL), and if you update the resource files, you only need to update in one place.

Workspace Data table in Terra workspace

Screenshot of the workspace data page with workspace data under other files circled on the left and three reference files in the center ref_dict, ref_fasta, and ref_fasta_inxed highlighted
The Workspace Data table (above) includes reference files (URL under Values column) and a key. The files can be called in any workflow analysis, regardless of what data are analyzed. 

How to add a Workspace Data table (in the UI)

If you only have a few files or variables to add as  Workspace Data table, you can add them manually one-by-one right in your workspace.

1. In your Data tab, click on the Workspace Data link under Other Data (left hand side).

Screenshot of the workspace data page with an arrow pointing to the workspace data link under other files on the left

2. Click the "+" icon at the bottom right of the page.

Screenshot of the workspace data page with an arrow pointing to the blue plus icon at the bottom right

3. Fill in the data key, value (use gs:// format for files in a Google bucket), and a description (optional), and select the type of data from the dropdown. To add the data to the table, click on the check icon at the far right. 

Screenshot of the workspace data page with a circle around the reference key, value, and description input fields and an arrow pointing to the check icon to the right of the input fields. The reference key in the example is my-reference and the value is a <code>gs://</code> path

What to expect

You should see the key, value and description you added in the Workspace Data table under Other Data

Screenshot of the Workspace data table with an arrow pointing to the workspace data link on the left and the key my-reference and value link to mother_variants200k.vcg circled in the table.

How to add a Workspace Data table (TSV)

If you have a lot of files to include in a Workspace data table, or if you already have them stored in a spreadsheet, follow the directions below to add the table to your workspace. 

Note: Once you upload a Workspace data table, you can edit the table in Terra. To learn more, see How to edit and modify data tables.

Step 1: Create the TSV file

1.1. Download a template Workspace Data table here.

1.2. Open in your favorite spreadsheet editor.

1.3. Complete the top left column with the first reference file key after "workspace:".

1.4. Fill in the cloud location of the first reference file in the second row of the first column.

1.5. Fill in the key and cloud locations fields (in the header and 2nd row, respectively) for the rest of your workspace-level reference files.

Workspace Data TSV file in a spreadsheet

workspace:ref_fasta ref_fasta_index ref_dict
  • Parts in red (i.e., "workspace:" must be typed exactly as shown.
  • Customize the resource file key (header row) and full path (second row).
  • Note: Terra will reorganize the files in alphabetical order.

Step 2: Save in tab separated values or tab delimited text format

Your editor may give you a warning, but we assure you, it's fine! Also, Terra will completely ignore the name you give the file. The "workspace:" formatting will tell Terra it is a Workspace data table.
Screenshot of spreadsheet editor with the option tab delimited text circled in the file format dropdown

A note about  .tsv  versus  .txt  file extensions Depending on what spreadsheet editor you use, when you save in the proper format your spreadsheet may have either a ".tsv" or a ".txt" extension. Terra will accept either one.

Step 3. Upload the TSV file to your workspace

3.1. Click the Import Data button at the top left of the workspace data page.

3.2. Select Upload TSV and follow the directions.
Screenshot of the top of the data page with an arrow pointing to the import data button and the menu option upload TSV circled

The screenshot below is what you'll see when you upload the spreadsheet above to a Workspace Data table. The first column (the "key" - circled on the left) identifies what the file is. The other (circled on the right) includes a link to the cloud location of the file (for example, in a Google bucket):

Example: Workspace Data table in Terra

A closeup of the workspace data table in the data tab with circles highlighting the key and values columns. There are three reference keys - ref_dict, ref_fasta, and ref_fasta_index and three corresponding values - links to Homo Sapiens assembly 38.dict, Homo Sapiens assembly 38.fasta, and Homo Sapiens assembly 38.fasta.fai

Additional resources

See these articles for more detailed information on different aspects of data tables. 

Was this article helpful?

0 out of 0 found this helpful


1 comment

  • Comment author
    Andrew Davidson
    • Edited

    to upload the workspace tsv file. You must go to the workspace data tab. Under 'other data' click on 'workspace data', the use the upload tsv. You can not upload using the plus sign next to "TABLE +"


Please sign in to leave a comment.