Tag Management
Introduction
Use data tags in Flywheel to annotate your data, so you can then search on and filter data based on those tags. Creating tags is a 2-step process. First create your new tags at the group level. Next, you can add those tags to containers in Flywheel.
Use Gear job tags to keep track of Gear runs and also to allocate the runs to specific compute engines (if configured). The Gear Job tags are a separate pool of tags, different from the data tags,that you can attach to a gear run and see in the Jobs Log.
Instruction Steps for Data Tags
Step 1: Create new tags in Groups
Any new tags must be created at the group level. To create new tags:
- Sign in to Flywheel.
- Click Groups in the left navigation menu.
- Select a group.
-
Click the Tags tab.
-
Enter a tag name, and click Add.
This tag is now available to add to other containers.
Note
- Tag names are not case sensitive. Meaning if the tag CONTROL already exists in a group, you cannot add a control tag.
- You can use the same tag name across multiple groups in Flywheel. When you search, all data associated with that tag name appears.
- Editing or deleting a tag name will change it throughout Flywheel.
Step 2: Add tags
In Flywheel you can add tags to sessions and subjects. To do this:
Add Tags to Sessions via the UI
- Click Projects.
- Select a project.
-
Select the Sessions tab.
All sessions for that project appear.
-
Select a session.
-
In the left panel, click Sessions and go to Tags.
- Start typing in a tag name. Available tag names appear in a list.
- Continue with each session that you want to tag.
Add Tags to Subjects via the UI
- Click Projects.
- Select a project.
- Select the Sessions tab.
- (Optional) Click to enable Subject View.
-
Select the subject you want to tag.
-
In left panel click the Subject tab, and go to Tags.
- Start typing a tag name. Available tag names appear in the list.
- Continue with each subject you want to tag.
Add tags via the SDK
Use the SDK to add tags in batches. Below is an example of interacting with session tags. See the Flywheel SDK for more information.
Example Use Case
Search for Tagged Data
Basic Search: Enter the tag name in the search bar
- Search results include any data that is associated with the group where the tag was created.
- If you added the same tag name to multiple groups, data associated with each group appears in the results.
Advanced Search:
- In the Search bar, hit enter.
- Click Advanced Search.
-
In Field, enter
tags
to bring up a list of all of your tag fields. By default, those fields aregroup.tags
orsubject.tags
.Tip
If you added tags using the SDK, you will have additional fields.
-
Choose an operator. See our Advanced Search documentation for more information.
- In Value(s), enter one or more tag names.
- Add more Terms or Term Groups.
- Once complete, click Run Query.
Instruction Steps for Gear Run Tags
Add tags to Gear runs via the UI
- Navigate to a session, and click the checkbox.
-
Select an acquisition.
Batch run Gears
To run a Gear against multiple sessions or acquisitions at the same time, use batch processing
-
Click Run Gear.
-
Select Utility or Analysis.
- Choose a gear from the list.
-
Enter one or more tag in the Job Tags field and press the
Enter
(orReturn
) key.Arbitrary Tags Allowed
Tags added to gear runs do NOT need to have been previously created at the group level. Thus, gear runs can be tagged with arbitrary strings. This is different to tags added to subjects or sessions as these cannot be arbitrary and must already exist at the group level.
-
Select the Configuration tab to edit any additional settings.
- Click Run Gear.
The tag is now associated with the job.
See the SDK documentation for how tags can be applied to gear runs..
Use Cases
Filtering on Specific Gear Runs using Tags
- Add the same tag to a set of gear runs at the time you create each gear run.
- On the Jobs Log, use the Tags column filter to narrow the list to your specific runs.
Allocate Gear Runs to Specific Engines
Certain gears may require specific resources, such as higher memory or larger storage capacities. Additionally, some gears might consume more compute resources than usual depending on the size of the input data. In some instances, these demands can exceed the capabilities of your site's standard compute engines.
With assistance from Flywheel support, you can configure compute engines on your site tailored to meet the needs of specific gears or resource requirements. Tags can then be used to designate which engine should be used for a particular gear run.
The steps below assume that your site has three size-based engines named small
, medium
, and large
.
- Follow steps 1-5 from Add tags to Gear runs via the UI above.
-
In the Job Tags field, enter either
small
,medium
, andlarge
to send the job to that specific engine.Info
Tagging every gear run is not necessary. However, tagging can be beneficial for jobs expected to be resource-intensive or for re-trying jobs that fail.