Session Templates

Overview

Session Templates define data quality requirements for imaging sessions in a project. They specify which acquisitions and file classifications must be present for a session to be considered complete.

When to use Session Templates:

• Quality Control: Ensure all sessions contain required scans before processing
• Clinical Trials: Validate that sites submit complete imaging protocols
• Standardization: Enforce consistent data structure across a multi-site study
• Automated Workflows: Trigger processing only when complete datasets are available

How it works:

When a session is uploaded or modified, Flywheel checks it against all configured templates on the project. A session is flagged only if it fails to satisfy all session templates — if it passes at least one template, it is not flagged. This allows administrators and data managers to identify incomplete or non-compliant sessions quickly.

Prerequisites

To create and manage Session Templates, you must have:

• Project Admin or Site Admin role
• Access to the project where templates will be configured
• Knowledge of your study's imaging protocol requirements
• Familiarity with regular expressions (optional, for advanced pattern matching)

Creating a Session Template

Prefer videos?

Watch this webinar to learn how to create a session template.

1. Sign in to Flywheel as a Project Admin.

2. Navigate to a project.

3. Select the options menu and choose Templates.

   

4. Click Create new template.

5. Choose how the template matches text. The template has a single Use Regex / Use Exact Match toggle that applies to every text field in the template: the session label, every acquisition label, and every file classification.

   • Use Regex (default): Each text field is a regular expression (regex). Matching is case-insensitive and succeeds if the pattern matches anywhere in the label or classification value.
   • Use Exact Match: Each text field is a literal string. Matching is case-insensitive and succeeds only if the whole label or classification value equals the field. You do not need to escape special characters.

   See Choosing Between Regex and Exact Match for guidance.

6. Fill out the template:

   • Session name: The text that identifies which sessions this template applies to. Flywheel compares it to the session label using the matching mode you chose in step 5.
   • Acquisition count: The minimum number of acquisitions required in the session. This count is evaluated independently from the acquisition label — it represents how many acquisitions the session must contain, not how many must match the label pattern. When Use Exact Match is selected, Flywheel sets this field to 1 and disables it, because acquisition labels are unique within a session, so an exact label can match at most one acquisition. A tooltip on the disabled field explains this. If you switch back to Use Regex, Flywheel restores the count you previously entered.
   • Acquisition label: The full or partial acquisition label to match. Each acquisition label rule only needs to match at least one acquisition in the session. Multiple rules can match the same acquisition without causing a validation failure.
   • File Count: The minimum number of files required in the acquisition. This count is evaluated independently from the file classification — it represents how many files the acquisition must contain, not how many must match the classification.
   • File Classification: The classification value that files must have (for example, T1, T2, FLAIR, Structural). Each file classification rule only needs to match at least one file in the acquisition. Multiple rules can match the same file without causing a validation failure. Matches against classification values only, not classification scheme names like Measurement, Intent, or Features. For example, a file with classification {"Measurement": ["T1"], "Intent": ["Structural"]} will match T1 or Structural, but not Measurement or Intent. Learn more about classifications in Flywheel.

1. Click Add File to add additional file rules for an acquisition. Each file rule is evaluated independently — the acquisition must satisfy every file rule (count and classification) to pass validation.

2. Click Add Acquisitions to add additional acquisition rules for a session. Each acquisition rule is evaluated independently — the session must satisfy every acquisition rule to pass validation.

3. Click Save.

Flywheel evaluates any existing session in the project against all templates. Sessions that fail to satisfy all templates are flagged.

Example:

In this example, the template uses Use Regex mode, so Flywheel evaluates sessions whose label contains anxiety_protocol_pre. The template defines one acquisition rule with the following requirements:

• Acquisition count: 1 — the session must contain at least 1 acquisition
• Acquisition label: MPRAGE — at least one acquisition must match this label
• File count: 2 — the matched acquisition must contain at least 2 files
• File classification: T1 — at least one file in the acquisition must be classified as T1

Note that the file count (2) and file classification (T1) are evaluated independently. The acquisition must contain at least 2 files total and at least one file classified as T1, but the 2 files do not all need to be classified as T1.

Choosing Between Regex and Exact Match

Choose Use Exact Match when:

• Your session labels, acquisition labels, and classification values are fixed strings that you can list in full
• Your labels contain characters such as parentheses or periods that would otherwise need escaping
• Each acquisition rule should match exactly one acquisition label

Choose Use Regex when:

• One template must cover several label variants, such as Baseline and Follow-up
• You need to match a label that contains a value that changes, such as a visit number or a date
• You need a partial match, such as any acquisition label that contains MPRAGE
• An acquisition rule needs an Acquisition count greater than 1

The toggle applies to the whole template. If some rules need a regex and others need a literal string, keep the template in Use Regex mode and anchor the literal rules with ^ and $, escaping any special characters.

Templates for the Case Uploader

Set every template that the Case Uploader uses to Use Exact Match.

The Case Uploader populates its session and acquisition drop-down menus from the template's session name and acquisition labels, and it creates the session and acquisitions with the labels the contributor selects. It does not evaluate regex patterns. If a template is in Use Regex mode, contributors see the raw pattern in the drop-down menu, and a pattern such as ^Baseline.*$ becomes the literal session label of the uploaded data.

In Use Exact Match mode, each template field is the exact label the contributor sees and the exact label Flywheel assigns, so uploaded sessions match the template and are not flagged. Create a separate template for each session label that contributors can choose.

View Flagged Sessions

Flywheel automatically flags any session that does not meet the requirements set in the template. These are called flagged sessions. To view flagged sessions in a project:

1. From the project, click the Sessions tab.

2. From the Advanced Filter menu, select Only Flagged

   

3. Enter a date range to narrow down the results or leave blank to view all flagged sessions.

Managing Templates

Edit a Template

To modify an existing template:

1. Navigate to the project
2. Select the options menu and choose Templates
3. Click the template you want to modify
4. Update the fields as needed
5. Click Save

When you edit a template, Flywheel re-evaluates all existing sessions in the project against the updated criteria.

Delete a Template

To remove a template:

1. Navigate to the project
2. Select the options menu and choose Templates
3. Click the template you want to remove
4. Click Delete
5. Confirm the deletion

Deleting a template does not modify your session data. Sessions that were previously flagged by this template will be re-evaluated against any remaining templates.

View All Templates

To see all templates configured for a project:

1. Navigate to the project
2. Select the options menu and choose Templates

All templates are listed with their session name pattern and acquisition requirements.

Common Regex Patterns

In Use Regex mode, Session Templates support regular expressions for flexible pattern matching. Matching is case-insensitive and succeeds if the pattern matches anywhere in the label. Here are common patterns:

Match specific sessions:

• Baseline - Matches sessions whose label contains "Baseline", such as Baseline or Pre-Baseline
• ^Visit 1$ - Matches sessions with label exactly "Visit 1" (start ^ and end $ anchors). Use Exact Match mode gives the same result without a regex.
• Baseline \(Visit 1\) - Matches sessions with parentheses (parentheses must be escaped)

Match multiple options:

• Baseline|Follow-up - Matches sessions whose label contains "Baseline" OR "Follow-up"
• Visit [123] - Matches "Visit 1", "Visit 2", or "Visit 3"

Match patterns:

• ^Visit - Matches any session whose label starts with "Visit"
• \d+ - Matches one or more digits (for example, session IDs)

Important: Special characters ( ) [ ] { } . * + ? | ^ $ \ must be escaped with backslashes when used literally.

Troubleshooting

Sessions are unexpectedly flagged

Special characters in session labels are not escaped

In Use Regex mode, Session Templates use regular expressions (regex) for pattern matching. Characters like parentheses have special meaning in regex and must be escaped with backslashes. For example, a session label Baseline (Visit 1) requires the pattern Baseline \(Visit 1\).

Solution: Edit your Session Template and escape special characters in the session name pattern, or switch the template to Use Exact Match if you do not need regex features.

• Incorrect pattern: Baseline (Visit 1)
• Correct pattern: Baseline \(Visit 1\)

Common special characters requiring escaping:

• Parentheses: ( ) → \( \)
• Square brackets: [ ] → \[ \]
• Curly braces: { } → \{ \}
• Period: . → \.
• Plus: + → \+
• Question mark: ? → \?
• Asterisk: * → \*
• Pipe: | → \|
• Caret: ^ → \^
• Dollar sign: $ → \$
• Backslash: \ → \\

After updating your template with escaped characters, verify it works correctly:

1. Create a test session with the actual label (for example, Baseline (Visit 1))
2. Check if the session is correctly matched by the template
3. If still flagged incorrectly, verify all special characters are escaped

Exact match value differs from the label

In Use Exact Match mode, a field matches only when the whole label or classification value equals the field. A partial value such as MPRAGE does not match an acquisition labeled MPRAGE_1, and extra whitespace or punctuation in the field prevents a match. Case differences do not prevent a match.

Solution: Enter the complete label exactly as it appears in Flywheel, or switch the template to Use Regex if you need a partial match.

Requirements are too strict for existing data

Acquisition counts, file counts, or classification requirements may not match what is actually present.

Solution:

1. Review your template configuration
2. Adjust acquisition count or file count requirements
3. Verify classifications are applied to your files

Sessions are not flagged when expected

Session passes another template on the project

A session is flagged only when it fails to satisfy all templates on the project. If the session passes at least one template, it is not flagged — even if it fails other templates.

Solution: Review all templates on the project. If a session should always meet a specific template regardless of other templates, consider whether the template's session name pattern is specific enough to avoid overlap with other templates.

Multiple rules match the same acquisition or file

Each acquisition label rule only needs to match at least one acquisition in the session, and each file classification rule only needs to match at least one file in the acquisition. Multiple rules can match the same acquisition or file without causing a validation failure. This means a single acquisition may satisfy several acquisition rules at once, and a single file may satisfy several file rules at once.

Solution: Design templates with distinct label and classification patterns when you need to enforce that specific separate acquisitions or files are present. For example, if a session must contain both an MPRAGE and a FLAIR acquisition, use acquisition labels that uniquely identify each one rather than patterns that could match the same acquisition.

Session name pattern matches more sessions than intended

In Use Regex mode, the session name pattern is case-insensitive and matches anywhere in the session label. A pattern such as Visit 1 also matches Visit 10 and Follow-up Visit 1, so a session you expected to be flagged may pass a template that was not meant for it.

Solution:

1. Anchor the pattern with ^ and $ to match the whole label, or switch the template to Use Exact Match
2. Use regex testing tools to validate your pattern
3. Review actual session labels in the Sessions tab

Count does not filter by label or classification

The acquisition count represents how many acquisitions the session must contain, not how many must match the acquisition label pattern. Similarly, the file count represents how many files the acquisition must contain, not how many must match the file classification.

A session with 3 acquisitions where only 1 matches the label will still satisfy an acquisition count of 3, because the count applies to all acquisitions in the session.

Solution: Do not rely on counts to enforce a minimum number of acquisitions matching a specific label or files matching a specific classification. Instead, use separate acquisition or file rules with distinct patterns to validate that the expected data is present.

Resources

• Case Uploader - Specialized interface for clinical trial data upload with Session Template validation