Understanding Entity Types

You may have seen the term "entity types" in a workspace data table or workflow configuration card. This article will help you understand what entities are, and some of the more technical details of Terra's five default root entity types.

What is a "root entity"?
What are the default entity types?
How to associate data in different tables
Working with data tables resources

If you're new to Terra, you may first see reference to "entity types" in a workflow configuration form:

Understanding-entities_Workflow-config-form_Screen_shot.png

What's an "entity"? It's a piece of data, a "thing"

According to the dictionary, an "entity" is "a thing with distinct and
independent existence." In Terra, entities are pieces of information -
almost like "variables" - traditionally used in workflow analysis.

An entity is the type of primary data stored in a data table. It's also
the name of the table in the workspace Data page. You can have
tables of sample data (a "sample" entity table) or tissues (a "tissue"
table), or unicorns (a "unicorn" table), for example.

Example: sample entities in a sample table

This sample table includes genomic data (BAM and BAM index files) of various samples. Note that the first column is each sample's unique ID and the fourth column is the participant ID, also found in the participant table.

	What's a workflow's "root entity" type?
	The "root entity" is the smallest piece of data a workflow can use as input. You select the root entity type of input when setting up a workflow. To learn more about how to configure a workflow, see this article.

What are the default entity types?

In Terra, five default root entity types are predefined kind of data with specific relationships. They were originally developed based on the data typically used in cancer research analyses. Using default entity names helps standardize workflows where the end result depends on grouping and associating the data properly.

Default entity types
Sample | Sample set | Participant | Participant set | Pair set

Sample: The most basic genomic data entity is the nucleotide sequence
from a single lane

Sample set: A grouping of particular samples. You can use this entity
type for running a single-input workflow on the same samples over and
over.You can also use this nested entity type in workflows that require
arrays (multiple samples) as input, such as joint genotyping or panel-of-
normals generation.

Participant: An individual, such as someone in a study. Participant IDs
help keep track of samples that belong to the same individual. They're
useful, for instance, if survey subjects provide multiple types of biological
samples (spit, blood, etc).

Participant set: A grouping of particular participants. This entity type
can be multiply nested, as it can group multiple participants, each with
multiple samples.

Pair set: A set of paired tumor and normal samples taken from the same
patient. This entity type is tailored for somatic workflows. For example, a
cancer study may include multiple pairs of samples from multiple study
participants.

Origins of the default entity types in Terra

Terra's five default entity types are not native to the Workflow Description
Language (WDL). The concept of entity types in Terra/GATK is inherited from
TCGA's metadata style, which was designed to categorize different types of
data files typically used in cancer research - such as files that track
treatment regimens, files that track the progress of samples through
pipelines, etc. Using the same entity names and default relationships made it
easier to standardize workflows for similar sorts of analyses.

Terra now uses flexible entity types
The analyses you can do on the Terra platform has expanded beyond cancer
research and you can use any entity description you want. However, you can
take advantage of these predefined relationships by using these default root
entity types.

Default entity types streamline linking data in different tables

In a table, each distinct entity (sample or specimen or participant) has its own row and its own unique ID. However, data in different tables are often related, such as phenotypic data (in a participant table)and genomic data (in a sample table) for a single participant.

Terra can connect some types of data automatically if (and only if) you use the default entity types and make sure to upload tables in a specific order. See how to use the participant, sample, and pairs IDs to associate different kinds of data together.

Linking study participants to genomic data (samples)

Participants
Imagine a study with thousands of participants. You define the participants' unique IDs in a participant table. The first column includes the unique participant ID and additional columns include other information associated with the participant. Traditionally a participant table only included participant IDs, but today a participant table can also include phenotypic data, or other data related to that participant (as in the screenshot below):

Samples
Traditionally a sample table (or entity) included genomic data files plus additional data. The sample entity table shown below includes 1) the unique ID for each sample, 2) links to the sample data files in the cloud, and 3) the participant_ID (from the participant table). The participant ID links the sample back to the ID (as well as any phenotypic data) in the participant table.

Grouping samples with sets

To group the three samples in the above example together for analysis, you would use a sample_set entity (table):

Notice that the sample-set table only includes the name of the set and the sample IDs. In order to analyze the genomic data, Terra would reference the metadata in the samples entity table using the participant ID.

Linking participants and their tumor-normal pairs of sample data

Our Somatic Variant Discovery Best Practice guidelines stress the importance of comparing a matched normal sample to the tumor sample. Workflows that compare tumor tissue with normal tissue typically expect a pair set as the input entity. If you attempt to launch a Mutect2 workflow by selecting the tumor and the normal files as individual samples, the workflow will fail.

The tables you would include in your workspace are (in order of how they must be loaded):

1. Participant table (notice this doesn't reference any other table or entity)
Understanding-entities_Participant-table_Screen_shot.png

2. Sample table (notice this references the participant_id from the first table)

3. Pairs table (notice this references both the participant and sample IDs)

For a detailed explanation of configuring your workflow inputs in the Terra interface, see this article. To learn more about scripting in WDL, you can read our WDL user guide or check out the OpenWDL community that was formed to steward the WDL language specification and advocate its adoption.

Working with data tables resources

How to modify, delete, and create tables
in this article

For hands-on practice using and creating data tables
try the Data QuickStart workspace

To learn to use data tables for input to a workflow
see this article.

Need Help?

Search our documentation and community forum

Articles in this section

What's an "entity"? It's a piece of data, a "thing"

Example: sample entities in a sample table

This sample table includes genomic data (BAM and BAM index files) of various samples. Note that the first column is each sample's unique ID and the fourth column is the participant ID, also found in the participant table.

What's a workflow's "root entity" type?

What are the default entity types?

Origins of the default entity types in Terra

Default entity types streamline linking data in different tables

Linking study participants to genomic data (samples)

Grouping samples with sets

Linking participants and their tumor-normal pairs of sample data

Working with data tables resources

Comments

Need Help?

Search our documentation and community forum

Articles in this section

What's an "entity"? It's a piece of data, a "thing"

Example: sample entities in a sample tableThis sample table includes genomic data (BAM and BAM index files) of various samples. Note that the first column is each sample's unique ID and the fourth column is the participant ID, also found in the participant table.

What's a workflow's "root entity" type?

What are the default entity types?

Origins of the default entity types in Terra

Default entity types streamline linking data in different tables

Linking study participants to genomic data (samples)

Grouping samples with sets

Linking participants and their tumor-normal pairs of sample data

Working with data tables resources

Related articles

Example: sample entities in a sample table

This sample table includes genomic data (BAM and BAM index files) of various samples. Note that the first column is each sample's unique ID and the fourth column is the participant ID, also found in the participant table.