Skip to content

DICOM Connector Advanced Configuration Guide

Introduction

This document provides comprehensive specifications for advanced DICOM Connector configuration options including custom metadata extraction, acquisition naming strategies, and data organization.

For information about how DICOM maps to the Flywheel hierarchy, see the Hierarchy Mapping Guide. For metadata processing mechanics, see the Metadata Extraction Guide. For deployment and networking information, see the Infrastructure Reference.

Advanced Metadata Extraction

Beyond the default metadata mappings, the DICOM Connector supports advanced extraction capabilities for custom metadata patterns and routing strategies.

Custom Metadata Patterns

The Connector can parse custom DICOM tags using flexible pattern matching:

Pattern Syntax:

  • Curly brackets {}: Capture metadata fields (e.g., {group._id}, {project.label})
  • Square brackets []: Indicate optional parts (e.g., [/{session.label}])
  • Multiple patterns: Can be applied in sequence with precedence

Example Pattern:

1
fw://{group._id}/{project.label}[/{subject.label}][/{session.label}]

This pattern:

  • Requires group._id and project.label
  • Makes subject.label and session.label optional
  • Allows partial routing strings like fw://group/project or fw://group/project/subject

Use Cases:

  • Parse custom tags selected by your institution
  • Support flexible routing string formats
  • Extract metadata from non-standard DICOM fields
  • Implement institution-specific naming conventions

Tag Selection Guidance

When selecting DICOM tags for custom metadata extraction, consider these characteristics:

Ideal Tag Properties:

  • Not currently utilized for clinical purposes
  • Prominently displayed on scanner console UI
  • Free-form string type (Long String or Person Name)
  • No length or character restrictions
  • Not deprecated or retired in DICOM standard

Common Tag Choices:

  • PatientComments - Often unused and available on most scanners
  • AdditionalPatientHistory - Free-form text field
  • StudyComments - Study-level free text (deprecated in DICOM standard but historically used for this purpose)

Work with Flywheel to identify the most appropriate tag for your scanners and workflow.

Metadata Defaults and Overrides

The Connector supports setting default values and overriding extracted metadata:

Default Values:

  • Applied when a field is empty or not set
  • Useful for providing fallback organization or project names
  • Multiple defaults can be specified

Override Values:

  • Force-set specific field values regardless of DICOM content
  • Useful for standardizing certain metadata across all uploads
  • Last override wins if multiple are specified for the same field

Advanced Regex Extraction

For complex parsing requirements, the Connector supports full regular expression patterns:

Capabilities:

  • Named capture groups for metadata fields
  • Full regex syntax support
  • Manual anchor specification (^ and $)
  • Complex conditional matching

When to Use:

  • Standard patterns cannot capture required metadata structure
  • Complex string parsing from free-text fields
  • Institution-specific formats requiring precise control

Example Use Case:

Extract research project code and subject identifier from patient ID formatted as STUDY123-SUBJECT456:

  • Pattern extracts project code STUDY123 to project label
  • Extracts subject identifier SUBJECT456 to subject label

Metadata Formatting

Construct metadata values from multiple DICOM fields:

Example:

1
{SeriesNumber}-{SeriesDescription}

Results in acquisition labels like 003-T1_MPRAGE or 015-BOLD_resting_state.

Use Cases:

  • Create descriptive filenames combining multiple fields
  • Generate consistent acquisition naming
  • Include series numbers in labels for sorting
  • Combine timestamp and description information

Configuration Considerations

Custom metadata extraction is configured by Flywheel during deployment:

  • Patterns should be tested against sample DICOM data from your scanners when possible
  • Multiple extraction rules can be applied in sequence
  • First successful match determines final metadata values
  • Pattern validation requires collaboration between Flywheel and customer to verify correct behavior

Custom metadata extraction enables flexible workflows while maintaining data organization and traceability.

Advanced Acquisition Naming Options

Beyond default SeriesDescription mapping, the Connector supports various acquisition naming strategies.

Series Number Prefixing

Add series numbers to acquisition labels for consistent sorting and identification:

Configuration Option: Series number prefix

Result:

  • Series 3 with description T1_MPRAGE becomes 003 - T1_MPRAGE
  • Series 15 with description BOLD_resting becomes 015 - BOLD_resting

Benefits:

  • Maintains scan order in acquisition lists
  • Distinguishes repeated sequences
  • Facilitates automated processing pipelines

Zero-Padded Series Numbers

Control series number padding for consistent string sorting:

Padding Options:

  • 2 digits: 01, 02, ... 99
  • 3 digits: 001, 002, ... 999
  • 4 digits: 0001, 0002, ... 9999

Example:

Without padding: 1 - T1, 10 - T2, 2 - PD (incorrect sort order)

With 2-digit padding: 01 - T1, 02 - PD, 10 - T2 (correct sort order)

Timestamp-Based Labeling

Incorporate acquisition timestamps into labels for precise timing information:

Concept:

  • Combine timestamp information with series descriptions
  • Support time-based sorting and identification
  • Maintain chronological order for repeated sequences

Use Cases:

  • Longitudinal studies requiring precise timing
  • Time-series functional imaging
  • Studies where acquisition time is more relevant than description
  • Distinguishing repeated sequences of same protocol

Custom Filename Formatting

Construct filenames from multiple DICOM fields:

Format Pattern Examples:

1
2
3
{SeriesNumber}-{SeriesInstanceUID}-{SeriesDescription}
{StudyDate}-{SeriesNumber}-{SeriesDescription}
{PatientID}-{StudyDate}-{SeriesNumber}

Result Examples:

  • 003-1.2.840.113619.2.55.3-T1_MPRAGE
  • 20241024-003-T1_MPRAGE
  • SUB001-20241024-003

Use Cases:

  • Unique file identification across studies
  • Include study metadata in filenames
  • Support downstream processing requirements
  • Maintain traceability to source data

Custom Routing Pattern Examples

Advanced routing patterns for complex organizational requirements.

Partial Routing with Defaults

Pattern:

1
fw://{group._id}/{project.label}[/{subject.label}][/{session.label}]

Behavior:

Routing String Input Extracted Values Fallback Behavior
fw://neuro/parkinson/sub01/ses01 All specified None needed
fw://neuro/parkinson/sub01 Group, project, subject Session from StudyDescription
fw://neuro/parkinson Group, project Subject from PatientID, session from StudyDescription

Space-Separated Identifiers in StudyDescription

Pattern:

1
{group._id} {project.label}

Use Case:

Some institutions encode group and project identifiers in the StudyDescription field using space separation.

Example StudyDescription: neuro parkinsons-longitudinal

Extraction Results:

  • Group: neuro
  • Project: parkinsons-longitudinal
  • Subject and Session: Derived from other DICOM fields (e.g., PatientID, StudyDate)

Site-Specific Routing with Defaults

Pattern with Defaults:

Default organization and project when routing string is missing or incomplete.

Behavior:

  • Missing routing string → Unknown group
  • Incomplete routing → Unsorted project
  • Default subject: Derived from PatientID
  • Default session: Derived from StudyDescription

Timestamp Handling Options

Control how the Connector interprets and uses DICOM timestamp fields.

Timezone Configuration

Default Behavior: All timestamps use UTC timezone

Configurable Options:

  • Specify scanner local timezone
  • Use facility timezone
  • Force UTC for all timestamps

Impact:

  • Affects session.timestamp values
  • Affects acquisition.timestamp values
  • Critical for multi-site studies across timezones

Example:

Scanner in US Eastern timezone captures at 14:30 local time:

  • UTC timezone: 2024-10-24T19:30:00Z
  • Local timezone: 2024-10-24T14:30:00-05:00

Alternative Timestamp Sources

Session Timestamp Sources:

  • Primary: StudyDate + StudyTime
  • Alternative: Can be configured to use other date/time combinations

Acquisition Timestamp Sources:

  • Default: AcquisitionDate + AcquisitionTime
  • Siemens scanners: SeriesDate + SeriesTime
  • Fallback: session.timestamp if acquisition timestamp unavailable

Timestamp-Based Session Labeling

Option: Use timestamp as session label instead of StudyDescription

Behavior:

  • Uses the original DICOM timestamp format from StudyDate + StudyTime
  • Exact format depends on how DICOM fields are formatted in source data

Use Cases:

  • Time-series longitudinal studies
  • Multiple sessions per day
  • When study descriptions are not unique

Extended SeriesInstanceUID Manipulation

Expand on the existing UID processing rules with additional context.

UID Suffix for Multi-Acquisition Series

Rule: Non-Siemens manufacturers with AcquisitionNumber > 1

Processing:

Original SeriesInstanceUID: 1.2.840.113619.2.55.3

With AcquisitionNumber = 2: 1.2.840.113619.2.55.3_2

Purpose:

  • Separate multi-part acquisitions into distinct Flywheel acquisitions
  • Maintain relationship through base UID
  • Support modalities that use acquisition numbers for segmentation

Derived Series UID Decrementing

Rule: ImageType contains DERIVED\SECONDARY\SCREEN SAVE or DERIVED\SECONDARY\VXTL STATE

Processing:

Original SeriesInstanceUID: 1.2.3.4.5.6

Processed: 1.2.3.4.5.5 (last component decremented)

Purpose:

  • Group derived series with their source series
  • Maintain distinct UIDs while indicating relationship
  • Support post-processing workflows

UID Preservation for Source Tracking

Behavior:

  • Original SeriesInstanceUID always preserved in DICOM metadata
  • Manipulated UID used only for Flywheel organization
  • Enables tracing back to source DICOM system

Benefits:

  • Maintains DICOM compliance
  • Supports data provenance
  • Enables cross-platform tracking

Preventing Duplicate Acquisitions

UID-Based Deduplication:

  • Connector tracks uploaded series by SeriesInstanceUID
  • Re-uploads only occur if series content changes
  • Grace period applies to vanished series

Series Completion Detection:

  • Monitors NumberOfSeriesRelatedInstances header
  • Waits for stability before upload
  • Configurable delay for conservative completion

Metadata Formatting Examples

Practical examples of metadata formatting patterns.

Acquisition Label Patterns

Pattern 1: Series Number and Description

1
{SeriesNumber} - {SeriesDescription}

Result: 003 - T1_MPRAGE

Pattern 2: Number, Modality, and Description

1
{SeriesNumber} - {Modality} - {SeriesDescription}

Result: 003 - MR - T1_MPRAGE

Pattern 3: Timestamp Prefix

1
{SeriesTime} - {SeriesDescription}

Result: 143015 - T1_MPRAGE

Session Label Patterns

Pattern 1: Study Description with Date

1
{StudyDescription} - {StudyDate}

Result: Brain Protocol - 20241024

Pattern 2: Protocol and Time

1
{ProtocolName} - {StudyTime}

Result: NeuroProtocol - 143000

Subject Label Patterns

Pattern 1: Patient ID with Site Code

1
{PatientID}

Result: SITE01-SUB123

Pattern 2: Formatted Patient Name

1
{PatientID} - {PatientName}

Result: SUB123 - LastName^FirstName

Filename Patterns

Pattern 1: Complete Traceability

1
{StudyDate}_{SeriesNumber}_{SeriesInstanceUID}

Result: 20241024_003_1.2.840.113619.2.55.3

Pattern 2: Human-Readable

1
{SeriesNumber}_{SeriesDescription}_{StudyDate}

Result: 003_T1_MPRAGE_20241024

Pattern 3: Minimal Unique

1
{SeriesNumber}_{AcquisitionTime}

Result: 003_143015

Configuration Coordination

All advanced options are configured by Flywheel during deployment in collaboration with customer requirements.

Configuration Process

  1. Requirements Gathering: Customer describes naming and organizational needs
  2. Pattern Design: Flywheel designs metadata extraction and formatting patterns
  3. Sample Testing: Patterns tested against customer DICOM samples when available
  4. Validation: Customer validates results match expectations
  5. Deployment: Flywheel deploys validated configuration
  6. Refinement: Adjustments made based on production observations

When to Use Advanced Options

Consider Advanced Options When:

  • Default naming does not support workflow requirements
  • Multiple studies require different organizational strategies
  • Downstream processing depends on specific naming patterns
  • Time-based sorting is critical
  • Cross-site studies require timezone consistency
  • Multi-acquisition series need separation

Discuss with Flywheel:

  • Specific DICOM field values from your scanners
  • Desired organizational structure
  • Downstream system requirements
  • Any existing naming conventions to maintain