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. If a session matches a template pattern but does not meet its requirements, it is flagged for review. 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. Click the Templates tab.

   

4. Click Create new template.

5. Fill out the template:

   • Session name: The text pattern that identifies which sessions this template applies to. If empty, the template applies to all sessions in the project. 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 with the specified label required for validation.
   • Acquisition label: The full or partial acquisition label to match. 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 with the specified classification required in the acquisition.
   • File Classification: The classification value that files must have (for example, T1, T2, FLAIR, Structural). 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 have multiple file rules for an acquisition.

2. Click Add Acquisitions to have multiple acquisition rules for a session.

3. Click Save.

The template evaluates any existing session in the project. If the sessions don't follow the template, they are flagged.

Example:

In this example, Flywheel evaluates sessions that have a label starting with anxiety_protocol_pre. The template will flag any session that does not have:

• At least 1 acquisition with the label MPRAGE
• Two files that are classified as T1

This means the MPRAGE acquisition would have to have a DICOM file and a NIFTI file that both have been classified correctly.

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. Click the Templates tab
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. Click the Templates tab
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. Click the Templates tab

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 flagged incorrectly

Problem: Sessions are being flagged even though they appear to match the template requirements. Session labels contain parentheses, for example: Baseline (Visit 1).

Cause: Session Templates use regular expressions (regex) for pattern matching. Parentheses and other special characters have special meaning in regex and must be escaped with backslashes.

Solution:

Edit your Session Template and escape special characters in the session name pattern.

Example:

• 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: \ → \\

Testing your templates:

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

Template does not match any sessions

Problem: You created a template but no sessions are being matched or flagged.

Possible causes:

• The session name pattern is too specific
• Regex pattern contains errors
• Sessions do not actually match the pattern

Solution:

1. Check if your session name pattern is correct (pattern matching is case-sensitive)
2. Try leaving the session name field empty to match all sessions
3. Use regex testing tools to validate your pattern
4. Review actual session labels in the Sessions tab

All sessions are flagged after creating template

Problem: After creating a template, all sessions in the project are suddenly flagged.

Possible causes:

• The session name field was left empty (applies to all sessions)
• The requirements are too strict for your existing data
• Measurement classifications are not set correctly

Solution:

1. Review your template configuration
2. Add a specific session name pattern to limit which sessions are validated
3. Adjust acquisition count or file count requirements
4. Verify measurement classifications are applied to your files

Resources

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