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. Fill out the template:

   • Session name: The text pattern that identifies which sessions this template applies to. Supports case-sensitive regular expressions that match from the beginning of the session label (see pattern matching details below).
   • 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.
   • 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. Supports case-insensitive regular expressions that can match anywhere within the acquisition label (see pattern matching details below).
   • 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 patterns T1 or Structural, but not Measurement or Intent. Supports case-insensitive regular expressions for pattern matching. 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, Flywheel evaluates sessions that have a label starting with 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.

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

Session Templates support regular expressions for flexible pattern matching. Here are common patterns:

Match specific sessions:

• Baseline - Matches sessions with labels starting with "Baseline"
• ^Visit 1$ - Matches sessions with label exactly "Visit 1" (start ^ and end $ anchors)
• Baseline \(Visit 1\) - Matches sessions with parentheses (parentheses must be escaped)

Match multiple options:

• Baseline|Follow-up - Matches sessions starting with "Baseline" OR "Follow-up"
• Visit [123] - Matches "Visit 1", "Visit 2", or "Visit 3"

Match patterns:

• Visit.* - Matches any session starting with "Visit" followed by anything
• \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

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.

• 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

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 is too specific or contains errors

Solution:

1. Check if your session name pattern is correct (pattern matching is case-sensitive)
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