Learn how to edit and manage data tables in a Terra workspace: edit individual cells, add or delete table rows or columns, sort by or hide metadata (columns), etc.
Edit in Terra: Step-by-step instructions
You can edit and manage tables in the Data page of your Terra workspace much as you would any other spreadsheet. For example, if you want to change the subject ID (or other metadata), add or delete particular subjects, add or delete a column altogether, you can do so in the table below:
Click for step-by-step instructions of how to do each action in Terra.
-
To rename a table, click the three vertical dots to the right of the table name and fill in the New Name field in the form.
-
You can edit individual cells only by clicking on the pencil icon in the cell you want to change and working directly in the popup that appears.
Specify the metadata type
i.e. string, reference, number, or Boolean
Generate an array
Select Attribute is a list and add items.
-
1. Select the rows to edit.
2. Click the Edit icon (above the table, left corner).
3. Choose Edit selected rows from the menu.
4. Select the column to edit.
5. Edit metadata type and value in popup.
Don't forget to click the Save Edits button!
-
1. Click Edit (pencil icon) at the top of the table.
2. Select Add row from the menu box.
3. Add ID and metadata type and value for each column (expand column header for menu).
4. Click the Add button at the bottom of the form.
-
1. Check the box to the left of the row(s) you want to delete. To delete the entire table, select all rows from the dropdown.
2. Click Edit (pencil icon) at the top and select Delete Data.
-
1. Click the three vertical dots at the top right of the column you want to delete.
2. Select Delete/Clear column from the menu.
-
1. Click the three vertical dots at the top right of the column you want to delete.
2. Select Sort Ascending/Descending from the menu.
-
If you just want to hide columns, click the gear icon at the top right of the table. You'll see a popup where you can choose what columns of metadata to show. You can choose to save this view, especially useful for collaborators working in the same workspace.
-
Edit metadata (column cells) in bulk
If you want to update the values in a column for several (or all) rows in a table - if the study name or dates have changed, for example - follow the instructions below.
1. First select the row(s) to edit.
2. Click Edit (pencil icon) at the top of the data table.
3. Select Edit selected rows in the menu.
4. Select the attribute (column to edit)
5. Enter the new value and click Save changes
-
1. Starting in the workspace you want to copy from, select the rows you want to export (or all rows, if you want the entire table).
2. Click Export at the top and select the option you wish
- Download as TSV
- Export to workspace
- Copy to clipboardThere is no cost to copying data in a table to a workspaceExporting a data table to another workspace or downloading the TSV metadata does not incur any egress costs because you are not moving/copying the files in the table, merely copying the metadata and references to the new workspace.
Note: Readers of your workspace will need "Read" access to the bucket or workspace which actually owns the data to access files linked in the table.
How to edit or add data in a spreadsheet editor
If you need the full functionality of a spreadsheet, you can modify a TSV outside of Terra following the step-by-step instructions below.
Step 1. Download the existing table
1.1. Select rows to download (edit) in check boxes at left.
1.2. Click Export in the menu above the table.
1.3. Select Download as TSV from the popup.
Step 2. Edit and save the TSV file using your favorite spreadsheet editor
2.1. Open in your favorite spreadsheet editor and edit.
Beware of the characters you use! Note: ID cells (i.e., the first column of your table) can only include alphanumeric characters, "-" and "_" and no spaces. Single quotes are not allowed (use double quotes instead).
All formatting will be lost when you save the file in TSV format.
2.2. Save the file as "tab-separated values" or "tab-delimited text".
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 "root entity" in the first column header determines the table name in the workspace.
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
Click the Import Data button at the top left of the workspace data page and follow the directions.
TSV uploads are additive
TSV uploads are additive: a note about overwriting table rows When your TSV load file has the same entity (name) as a table already in the workspace, you may get an error message when you try to upload about overwriting data.
Terra will only overwrite data rows with the same ID (in the first column). If the TSV (load) file includes different IDs, these rows will be added to the existing table.
Uploading TSVs with missing columns or rows does not remove that data. This allows you to upload new TSVs that only contain the rows or columns you want to be added (but must include the entity ID column, which is used as the key).
Making tables programmatically (i.e., scripting)
You can automate the process of making and modifying tables using a special API called the FIreCloud Service Selector (FISS). Learn more in Managing data and automating workflows with the FISS API.
Next steps: Adding workspace-level (reference) data
Once your data entities are organized in a data table, you might want to add reference data to the workspace so you can perform data processing like alignment or calculate quality control metrics. Learn how to add workspace-level metadata to a table in Creating Workspace Data tables.
Additional resources
- Managing data with tables
- Overview: How to add a Table to a Terra workspace
- Creating Workspace Data tables
- Adding pair tables to a workspace for tumor-normal analysis
- Managing data and automating workflows with the FISS API