Skip to content

Pattern Quick Reference

Quick reference for commonly used filtering and mapping patterns in Flywheel Bulk Import and Export operations.

Learn More

For detailed pattern syntax and metadata field documentation, see:

Common Operators

Operator Description Example
= Exact match name=patient01
!= Not equal name!=temp
=~ Pattern match path=~*.dcm
!~ Pattern doesn't match path!~*temp*
> Greater than size>10MB
< Less than depth<5

Wildcard Characters

Pattern Matches Example
* Any chars (no /) *.dcm → file.dcm
**/ Any chars (with /) **/*.dcm → dir/sub/file.dcm
[opt] Optional section file[_01].txt → file.txt or file_01.txt
\uid DICOM UID \uid → 1.3.6.1.4.1.14519.5

Common Filter Patterns

File Types

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
# DICOM files
--include 'path=~*.dcm'
--include 'ext=dcm'

# NIfTI files
--include 'path=~*.nii'
--include 'path=~*.nii.gz'

# Multiple types
--include 'path=~*.dcm' --include 'path=~*.nii'

File Sizes

1
2
3
4
5
6
7
8
# Large files
--include 'size>100MB'

# Size range
--include 'size>=1MB' --exclude 'size>1GB'

# Exclude empty
--exclude 'size=0'

Directory Patterns

1
2
3
4
5
6
7
# Specific depth
--include 'depth=4'

# Directory name patterns
--include 'path=~patient*/*'
--exclude 'path=~*test*'
--exclude 'path=~*backup*'

DICOM Filtering (Export Only)

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
# By modality (requires DICOM metadata extraction)
--include 'file.info.header.dicom.Modality=MR'
--exclude 'file.info.header.dicom.Modality=PR'

# By series (requires DICOM metadata extraction)
--include 'file.info.header.dicom.SeriesDescription=~*T1*'
--exclude 'file.info.header.dicom.SeriesDescription=~*localizer*'

# By patient (requires DICOM metadata extraction)
--include 'file.info.header.dicom.PatientID=~RESEARCH*'

Warning

DICOM metadata filtering is only available for export operations. Import filters can only use file system fields (path, name, size, etc.).

System Files

1
2
3
4
5
6
# Exclude common unwanted files
--exclude 'name=~.*'          # Hidden files
--exclude 'name=~*~'          # Backup files
--exclude 'name=~*.tmp'       # Temp files
--exclude 'name=~Thumbs.db'   # Windows thumbnails
--exclude 'name=~.DS_Store'   # macOS metadata

Common Mapping Patterns

Standard Hierarchy

1
2
3
4
5
6
7
8
# Patient/Study/Series structure
--mapping 'path={sub}/{ses}/{acq}/*'

# Skip root directory
--mapping 'path=data/{sub}/{ses}/{acq}/*'

# Include study in path
--mapping 'path=study_{study}/{sub}/{ses}/{acq}/*'

Date-Based Organization (Import)

1
2
3
4
# Use DICOM date fields for organization
--mapping 'subject.label={PatientID}'
--mapping 'session.label={StudyDate}'
--mapping 'acquisition.label={SeriesDescription}'

Container Label Derivation (Import)

1
2
3
4
5
6
7
# Derive labels from DICOM metadata
--mapping 'subject.label={PatientID}'
--mapping 'session.label={StudyDescription}_{StudyDate}'
--mapping 'acquisition.label={Modality}_{SeriesNumber}'

# Derive labels from file path structure
--mapping 'path={sub}/{ses}/{acq}/*'

DICOM File Naming (Import)

1
2
3
4
5
# Set ZIP archive name when grouping DICOM files (requires --type dicom)
--dicom-instance-name '{SeriesDescription}_{SeriesNumber}.dicom.zip'

# Rename individual files during import
--mapping 'file.name={PatientID}_{SeriesNumber}_{file.name}'

Note: The --dicom-instance-name option (available in version 20.5+) controls the naming of ZIP archives created when grouping DICOM files during import.

Size Units

Unit Description Example
B Bytes size=1024B
KB Kilobytes size>500KB
MB Megabytes size>=10MB
GB Gigabytes size<2GB
TB Terabytes size<=1TB

Field Names

File System

  • path - Full file path
  • name - File name only
  • ext - File extension (e.g., png, dcm)
  • dir - Parent directory name
  • depth - Directory depth level
  • size - File size in bytes
  • ctime - File created timestamp
  • mtime - File modified timestamp

DICOM Fields

For Import Mappings (read directly from DICOM files):

  • PatientID - Patient ID
  • PatientName - Patient Name
  • StudyInstanceUID - Study UID
  • SeriesInstanceUID - Series UID
  • Modality - Imaging modality
  • SeriesDescription - Series description
  • StudyDescription - Study description
  • AcquisitionDate - Scan date
  • ImageComments - Image comments

Note: This is a subset of commonly-used fields. Any standard DICOM tag can be used in import mappings.

For Export Filters (requires extraction by File Metadata Importer gear):

  • file.info.header.dicom.PatientID - Patient ID
  • file.info.header.dicom.PatientName - Patient Name
  • file.info.header.dicom.StudyInstanceUID - Study UID
  • file.info.header.dicom.SeriesInstanceUID - Series UID
  • file.info.header.dicom.Modality - Imaging modality
  • file.info.header.dicom.SeriesDescription - Series description
  • file.info.header.dicom.StudyDescription - Study description
  • file.info.header.dicom.AcquisitionDate - Scan date
  • file.info.header.dicom.ImageComments - Image comments

Note: This is a subset of commonly-used fields. Any DICOM tag extracted by the File Metadata Importer gear can be used.

Flywheel Hierarchy (Export Only)

  • project.label - Project name
  • subject.label - Subject ID
  • session.label - Session ID
  • acquisition.label - Acquisition name

Note: This is a subset of commonly-used fields. Many more Flywheel metadata fields are available for export filters. See Pattern Syntax Reference for complete field listings.

Regular Expression Mode

For complex patterns, append !r for regex mode:

1
2
3
4
5
# Full regex pattern
--include 'path=~^/data/[0-9]{4}/.*\.dcm$!r'

# Case insensitive regex
--include 'name=~^patient.*!ri'

Testing Patterns

Before running full operations:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
# Test import patterns
fw-beta import test /path/to/file.dcm \
    --type dicom \
    --include 'path=~*.dcm' \
    --mapping 'subject.label={PatientID}'

# Shows:
# - Whether file matches filters
# - Extracted metadata
# - Target organization

Common Command Templates

Basic DICOM Import

1
2
3
4
5
6
fw-beta import run \
    --project "fw://group/project" \
    --storage storage-id \
    --type dicom \
    --include 'path=~*.dcm' \
    --exclude 'name=~*localizer*'

Research Data Export

1
2
3
4
5
6
fw-beta export run \
    --project "fw://group/project" \
    --storage /export/path \
    --include 'file.info.header.dicom.Modality=MR' \
    --include 'file.info.header.dicom.SeriesDescription=~*T1*' \
    --path '{sub}/{ses}/{acq}/{file}'

Quality Control Import

1
2
3
4
5
6
7
8
9
fw-beta import run \
    --project "fw://group/project" \
    --storage storage-id \
    --type dicom \
    --include 'path=~*.dcm' \
    --include 'size>1MB' \
    --exclude 'name=~*localizer*' \
    --exclude 'name=~*scout*' \
    --exclude 'name=~*SECONDARY*'

Troubleshooting Tips

  • Pattern not matching? → Use fw-beta import test to debug
  • Too many files? → Add more specific exclude filters
  • Performance slow? → Use depth filtering and specific patterns
  • Mapping errors? → Verify source structure matches pattern
  • Complex patterns? → Break into multiple simpler filters