Skip to content

Bulk Import - Customizing Import Rules

Overview

While Flywheel provides automatic import behavior that works well for many scenarios, you may need to customize how files are organized during import.

The new (BETA) CLI provides extensive options for customizing:

  • Filtering - Control which files are imported
  • Mapping - Define how files are organized into Flywheel's hierarchy
  • Grouping - Control how DICOM files are packaged into ZIP archives
  • File Naming - Customize ZIP archive and individual file names

All customization options are available when using the fw-beta import run command.

Pattern Syntax Documentation

For comprehensive pattern syntax documentation and practical examples, see:

Filtering Files

Filters control which files are included or excluded from import based on file properties like name, size, path, or depth.

Include Filters

Include filters specify which files should be processed. At least one include filter must match for a file to be imported.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
# Include only DICOM files
fw-beta import run -s <storage> -p <project> \
    --include 'ext=dcm'

# Include multiple file types
fw-beta import run -s <storage> -p <project> \
    --include 'ext=dcm' \
    --include 'ext=nii'

# Include files at specific depth
fw-beta import run -s <storage> -p <project> \
    --include 'depth=4'

Exclude Filters

Exclude filters specify which files should be skipped. If any exclude filter matches, the file is not imported.

1
2
3
4
5
6
7
8
# Exclude temporary files
fw-beta import run -s <storage> -p <project> \
    --exclude 'name=~*temp*' \
    --exclude 'name=~*backup*'

# Exclude by size
fw-beta import run -s <storage> -p <project> \
    --exclude 'size<1MB'

Combining Include and Exclude

1
2
3
4
5
# Import DICOM files but exclude localizers
fw-beta import run -s <storage> -p <project> \
    --include 'ext=dcm' \
    --exclude 'name=~*localizer*' \
    --exclude 'name=~*scout*'

For more filtering examples and available fields, see the Filtering and Mapping Guide.

Mapping Files to Flywheel Hierarchy

Mapping patterns define how source file paths are transformed into Flywheel's hierarchy structure (Subject, Session, Acquisition) and how container labels are derived.

Path-Based Mapping

Extract container labels from file path structure:

1
2
3
4
5
6
7
# Map directory structure to Flywheel hierarchy
fw-beta import run -s <storage> -p <project> \
    --mapping 'path={sub}/{ses}/{acq}/*'

# Skip root directory levels
fw-beta import run -s <storage> -p <project> \
    --mapping 'path=data/{sub}/{ses}/{acq}/*'

DICOM Metadata Mapping

For DICOM files, derive container labels from DICOM headers:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
# Use DICOM tags for container labels
fw-beta import run -s <storage> -p <project> \
    --type dicom \
    --mapping 'subject.label={PatientID}' \
    --mapping 'session.label={StudyDescription}' \
    --mapping 'acquisition.label={SeriesDescription}'

# Combine multiple DICOM tags
fw-beta import run -s <storage> -p <project> \
    --type dicom \
    --mapping 'session.label={StudyDescription}_{StudyDate}' \
    --mapping 'acquisition.label={Modality}_{SeriesNumber}'

Default Values

Set default values when mappings don't extract a value:

1
2
3
fw-beta import run -s <storage> -p <project> \
    --mapping 'subject.label={PatientID}' \
    --default 'session.label=baseline'

Override Values

Force specific values regardless of extracted data:

1
2
3
fw-beta import run -s <storage> -p <project> \
    --mapping 'subject.label={PatientID}' \
    --override 'project.label=MyStudy'

For more mapping examples and available DICOM fields, see the Filtering and Mapping Guide.

DICOM-Specific Customizations

Custom Grouping Logic

Control how DICOM files are grouped into ZIP archives using the --dicom-group-by option:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
# Group by study and series (default behavior)
fw-beta import run -s <storage> -p <project> \
    --type dicom \
    --dicom-group-by StudyInstanceUID \
    --dicom-group-by SeriesInstanceUID

# Custom grouping by date and series number
fw-beta import run -s <storage> -p <project> \
    --type dicom \
    --dicom-group-by StudyDate \
    --dicom-group-by StudyTime \
    --dicom-group-by SeriesNumber

Disable Zipping Single Files

By default, even single DICOM files are zipped. Use --no-zip-single to disable this:

1
2
3
fw-beta import run -s <storage> -p <project> \
    --type dicom \
    --no-zip-single

Configuring File Names

Control the naming of files during import using the file.name mapping field. This applies to both ZIP archives created from DICOM files and non-DICOM files:

1
2
3
4
5
6
7
8
# Custom ZIP archive naming for DICOM
fw-beta import run -s <storage> -p <project> \
    --type dicom \
    --mapping 'file.name={Modality}_{SeriesNumber}_{SeriesDescription}.dicom.zip'

# Rename non-DICOM files during import
fw-beta import run -s <storage> -p <project> \
    --mapping 'file.name={PatientID}_{file.name}'

Configuring Individual DICOM File Names

Control how individual DICOM files are named within ZIP archives using --dicom-instance-name:

1
2
3
4
# Custom naming for individual DICOM files in archives
fw-beta import run -s <storage> -p <project> \
    --type dicom \
    --dicom-instance-name '{SeriesDescription}_{InstanceNumber}.{Modality}.dcm'

Note

The --dicom-instance-name option only affects DICOM files packaged into ZIP archives. To customize the names of loose DICOM files when --no-zip-single is used, use the file.name mapping field instead (see Configuring File Names).

Using Rule Files

For complex import scenarios with multiple sets of rules, you can define all your customizations in a reusable YAML rule file:

1
2
3
# Use a rule file for import
fw-beta import run -s <storage> -p <project> \
    --rules-file /path/to/import-rules.yaml

Rule files support:

  • Multiple rules with first-match-wins logic
  • All filtering and mapping options
  • DICOM-specific configurations
  • Reusable configurations across imports

See Rule Files for complete documentation on the YAML format and examples.

Complete Example

Here's a comprehensive example combining multiple customization options:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
fw-beta import run \
    --project "fw://group/MyProject" \
    --storage my-storage-id \
    --type dicom \
    --include 'ext=dcm' \
    --include 'size>1MB' \
    --exclude 'name=~*localizer*' \
    --exclude 'name=~*scout*' \
    --mapping 'subject.label={PatientID}' \
    --mapping 'session.label={StudyDescription}_{StudyDate}' \
    --mapping 'acquisition.label={SeriesNumber}_{Modality}_{SeriesDescription}' \
    --dicom-group-by StudyInstanceUID \
    --dicom-group-by SeriesInstanceUID \
    --dicom-instance-name '{SeriesNumber}_{InstanceNumber}.{Modality}.dcm'

This command:

  • Imports DICOM files larger than 1MB
  • Excludes localizer and scout images
  • Derives container labels from DICOM headers
  • Groups files by study and series
  • Customizes individual DICOM file naming within archives

Testing Your Configuration

Before running a full import, test your configuration using:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
# Test on a single file
fw-beta import test /path/to/sample.dcm \
    --type dicom \
    --include 'ext=dcm' \
    --mapping 'subject.label={PatientID}'

# Dry-run mode (processes small subset without actual import)
fw-beta import run \
    --project "fw://group/MyProject" \
    --storage my-storage-id \
    --dry-run

See Also