Skip to content

CLI Reference Guide: Import DICOM

Introduction

The import DICOM option reads through directories of DICOM files and uses the DICOM header information to group them into the correct Acquisitions and Sessions in Flywheel. This article explains the optional arguments for the import dicom command. See this article for directions on how to run the import dicom command.

Instruction Steps

Warning

Unsupported upload method for site, group, or project de-id profiles

Use one of these supported methods if you use site, group, or project de-id profiles.

Usage

fw ingest dicom [optional arguments] folder group_id project_label

Required Arguments

Required Arguments Description
folder The path to the folder to import
group_id Enter an existing group id or enter a new group_id to create the group when you import data. The group id can include lowercase letters, numbers, dashes, and underscores as long as it’s unique. It can’t be changed later.
project_label Enter an existing project label or enter a new project label to create the group when you import data.
The project label can include lowercase letters, numbers, dashes, underscores or spaces as long as its unique. Project labels with spaces require quotes (for example "A Project Name"). The project label can be changed later.

Optional Arguments

Optional Arguments Description
-h Show this help message and exit
--config-file FILE LOCATION Specify configuration options via config file. See our article on how to create and use the config file to set optional arguments.
--no-config Do NOT load the default configuration file
-y Assume the answer is yes to all prompts
--ca-certs CA_CERTS The file to use for SSL Certificate Validation
--debug Turns on debug logging level
--quiet Stop logging to the console
--max-retries MAX_RETRIES Sets the maximum number of retry attempts, if assume yes. The default is 3 retry attempts.
--jobs JOBS Allocates resources for jobs. Jobs perform tasks on your data to process and prepare it for upload to Flywheel. For example, the compression-level is a job run before the data is uploaded to Flywheel.
--concurrent-uploads CONCURRENT_UPLOADS Allocates resources for uploading data to your Flywheel instance. The amount of concurrent uploads your computer can successfully upload depends on the amount of CPU available.
--compression-level The compression level to use for packfiles. -1 for default, 0 for store. A higher compression level number means more compression (and more processing time to compress the data)
--symlinks Follow symbolic links that resolve to directories
--include-dirs INCLUDE_DIRS Patterns of directories to include. You can use wildcard matches (?, *) to include directories and their subdirectories.
Flywheel CLI can only import directories that are under the initial indicated directory
--exclude-dirs EXCLUDE_DIRS Patterns of directories to exclude. You can use wildcard matches (?,*) to include directories. This does not include sub-directories.
--include FILTER Enter specific filenames or use wildcard matches (?,*) to include patterns of filenames. You can only include files that are within the path designated in the command. Learn more about file types in Flywheel.
--exclude EXCLUDE Enter specific filenames or use wildcard matches (?,*) to exclude patterns of filenames. Learn more about file types in Flywheel.
--output-folder OUTPUT_FOLDER Output to the given folder instead of uploading to flywheel.
--no-uids Ignore UIDs when grouping sessions and acquisitions. This is useful when you want to group sessions and acquisitions by labels instead of UID.
--unique-uids Warn before creating a Flywheel container (Group, Project, Subject, Session, or Acquisition) with duplicate UIDs
--max-tempfile MAX_TEMPFILE The max in-memory tempfile size, in MB, or 0 to always use disk
--skip-existing Skip import of existing files.
--no-audit-log Don't generate an audit log
--audit-log-path AUDIT_LOG_PATH Sets the location for where the audit log should be placed.
--private-dicom-tags PRIVATE_DICOM_TAGS Include the path to the file that defines your private DICOM tags (tags that are not standard for DICOMs and are unique to your institution).
You can then use the defined tags to de-identify the tags before uploading your data to Flywheel. See our article to learn how define and de-identify private DICOM tags.
--ignore-unknown-tags The Flywheel CLI gives an error if there is an unknown DICOM tag. Use this flag to suppress the error and ignore unknown DICOM tags.
--encodings ENCODINGS Set character encoding aliases. E.g. win_1251=cp1251
--related-acquisitions Store related DICOMs in the same acquisition.
--de-identify De-identify DICOM files, e-files and p-files prior to upload.
This flag removes the DICOM tags PatientID, PatientName, and PatientBirthDate.
--profile PROFILE Use the de-identification profile to de-id more fields. See our article to learn more about creating this file.
--subject subject_label Override value for the subject label
--session session_label Override value for the session label

DICOM Tags mapping

The Flywheel CLI uses DICOM tags to populate the Flywheel container fields by default. The specific mapping between DICOM tags and Flywheel fields is:

  • subject.label - PatientID
  • subject.sex - PatientSex
  • session.uid - StudyInstanceUID
  • session.timestamp - AcquisitionDate & AcquisitionTime (SeriesDate and SeriesTime for Siemens)
  • session.label - StudyDescription
    fallback to session.timestamp
    fallback to StudyInstanceUID
  • acquisition.uid - SeriesInstanceUID
  • acquisition.label - SeriesNumber - SeriesDescription
    fallback to acquisition.timestamp (formatted as %Y-%m-%dT%H:%M:%S)
    fallback to SeriesInstanceUID
    only prefixed if SeriesNumber is set
  • acquisition.timestamp - AcquisitionDate & AcquisitionTime (SeriesDate and SeriesTime for Siemens)