Skip to content

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:

  1. Sign in to Flywheel.
  2. Click Groups in the left navigation menu.
  3. Select a group.

  4. Click the Tags tab.

    TagsGroupCreateTags.png

  5. 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

  1. Click Projects.
  2. Select a project.

  3. Select the Sessions tab.

    All sessions for that project appear.

  4. Select a session.

    SessionTags.png

  5. In the left panel, click Sessions and go to Tags.

  6. Start typing in a tag name. Available tag names appear in a list.
  7. Continue with each session that you want to tag.

Add Tags to Subjects via the UI

  1. Click Projects.
  2. Select a project.
  3. Select the Sessions tab.
  4. (Optional) Click The subject view button to enable Subject View.

  5. Select the subject you want to tag.

    SubjectTags.png

  6. In left panel click the Subject tab, and go to Tags.

  7. Start typing a tag name. Available tag names appear in the list.
  8. 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.

# See tags on a session
session = fw.get(session_id)
print(', '.join(session.tags)) 

# Add a tag named Control to a session
session.add_tag('Control') 

# Remove a tag from a session
session.delete_tag('Analysis Required')

# Add a tag to a file 
acq = fw.get('60eda95598612d4e6d5b8da9')
for file in acq.files:  
  file.add_tag('Alpha')

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:

  1. In the Search bar, hit enter.
  2. Click Advanced Search.

  3. In Field, enter tags to bring up a list of all of your tag fields. By default, those fields are group.tags or subject.tags.

    Tip

    If you added tags using the SDK, you will have additional fields.

  4. Choose an operator. See our Advanced Search documentation for more information.

  5. In Value(s), enter one or more tag names.
  6. Add more Terms or Term Groups.
  7. Once complete, click Run Query.

Instruction Steps for Gear Run Tags

Add tags to Gear runs via the UI

  1. Navigate to a session, and click the checkbox.

  2. Select an acquisition.

    Batch run Gears

    To run a Gear against multiple sessions or acquisitions at the same time, use batch processing

  3. Click Run Gear.

    RunAGear.gif

  4. Select Utility or Analysis.

  5. Choose a gear from the list.

  6. Enter one or more tag in the Job Tags field and press the Enter (or Return) 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.

  7. Select the Configuration tab to edit any additional settings.

  8. 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

  1. Add the same tag to a set of gear runs at the time you create each gear run.
  2. 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.

  1. Follow steps 1-5 from Add tags to Gear runs via the UI above.

  2. In the Job Tags field, enter either small, medium, and large 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.