Importing a Structured Folder of Imaging Data with the CLI

Introduction

The folder command should be used if you are importing data that you previously downloaded from Flywheel, or if you are importing data that was shared from another Flywheel site.

This article explains how to use the ingest folder and import folder (DEPRECATED) commands.

The folder command requires your directory of data to exactly match the the Flywheel hierarchy. Below is the basic Flywheel hierarchy:

Warning: Strict Folder Structure

If the directory you are importing does not exactly match the directory shown in the image above, consider using another method to import your images. For example, if all of your images are DICOMs, consider using our dicom importer to automatically determine containers in Flywheel for your data. This option also groups images by subjects and sessions. Learn about the other ways to import data.

Before You Begin

• Follow these instructions to download and install the Flywheel CLI. If you cannot download the Flywheel CLI to your computer, you can upload smaller batches of files using your web browser.

Warning: Unsupported File Types

The import/ingest folder command does not support uploading site, group, or project de-id profiles.

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

Instruction Steps

Steps for Ingest Folder

Use the ingest folder command unless you have been instructed by Flywheel support or your Site Admin to use the legacy import folder command.

1. Open Terminal.
2. Note the location of the parent folder for your data.
3. If your DICOM images are in a .zip file, unzip them.
4. Enter the ingest folder command:

fw ingest folder <optional flags> --group <groupid> --project <projectlabel> --dicom <folder with images> <SRC> 

For example: fw ingest folder --group psychology --project MyProject --dicom dcm001 ~/Desktop/MultiCenterStudy

• The --group and --project flags designate where in Flywheel the data should be imported. This overwrites whatever the name of the folder is in the directory you are uploading.

• The --dicom flag takes subfolders with DICOM images, analyzes them, zips them, and adds them as acquisitions. The --dicom flag is required if you have enabled project, group, or site de-id profiles for de-identification.

• Review the hierarchy and scan summary to make sure it matches what you expect.

• Enter yes to begin importing.
  The Flywheel CLI displays its import progress

• Sign in to Flywheel to view your data.

Steps for Import Folder (DEPRECATED)

Follow these steps to import your structured directory to Flywheel:

1. Open Terminal or Windows Command Prompt.
2. Note the location of the parent folder for your data.
3. Enter the import folder command:

fw import folder <Folder you are importing> <optional flags>

For example: fw import folder ~/Desktop/MultiCenterStudy --group psychology --dicom dicomsubfolder1

The --group flag designates a group in Flywheel where the data should be imported. This overwrites whatever the name of the folder is in the directory you are uploading. The --dicom flag takes subfolders with DICOM images, analyzes them, zips them, and adds them as acquisitions. Learn more about the optional flags for the import folder command.

1. Review the hierarchy and scan summary to make sure it matches what you expect.
   

2. Enter yes to begin importing.
   The Flywheel CLI displays its import progress

3. Sign in to Flywheel to view your data.

Troubleshooting

Each level in the Flywheel hierarchy must be specified during import. This means you must either: - Have a folder for each container (Group, Project, Subject, Session, Acquisitions, and images)

OR

• Manually configure the container using an optional flag. For example: --group <groupID> or --project <project label>. For more information about the optional flags, see our reference guide.