Skip to content

Creating a Configuration File for the Flywheel CLI

When you upload data using the Flywheel CLI, there are many settings that you can configure. To simplify how you configure these settings, you can create a configuration file.

The configuration file keeps all of the upload settings in one place. It also allows you to reuse the settings or share them with other Flywheel users in your environment. This standardizes how data is uploaded.

This article explains how to create a config file for the fw ingest command.

Example config file

To begin let's take a look at an example config file for uploading DICOM files. We will go over how to customize this file in the steps below.

#####
# Template and Group/Project Settings
#####

template:
  - pattern: "{project}"
  - pattern: "{subject}"
  - pattern: "{session}"
  - pattern: "{acquisition}"
      scan: dicom

#####
# Includes/excludes directories or file types
#####

# Patterns of directories to include
include-dirs:  
  - "*-DCM"

# Patterns of filenames to exclude
exclude:  
  - "*.txt"
  - "*.xml"

  #####
# De-identification Settings
#####

deid-profile: custom

deid-profiles:
- name: custom

  dicom:

    # What date offset to use, in number of days
    date-increment: -17

    # Remove all private tags
    remove-private-tags: true

    # Set patient age from date of birth
    patient-age-from-birthdate: true

    # Set patient age units as Years
    patient-age-units: Y

    fields:
      # Remove a dicom field (e.g.remove PatientID)
      - name: PatientID
        remove: true
      # Increment a date field by -17 days
      - name: StudyDate
        increment-date: true
      # One-Way hash a dicom field to a unique string
      - name: AccessionNumber
        hash: true

Customize the Config File for Data

  1. Copy and paste the example config file into a text editor.

  2. Update the config file to fit your data, as well as the command you are using. For more information on the sections within this config, see the following articles:

  3. Template

  4. De-id profile
  5. See the reference guide articles below for the settings you can configure in your yaml file:
  6. Ingest DICOM reference guide
  7. Ingest template reference guide

  8. Ingest folder reference guide

  9. Save with the .yaml extension.

Tip

Use an online YAML validator (such as YAMLlint ) to make sure the format is correct.

How to Use the Config File

To use the config file in your ingest command:

  1. Instead of setting the optional flags in the command, you can combine all of the settings in to the config file option. To call this config file in your command:
fw ingest template ~/Documents/DataToImport TemplateExample --config-file ~/Documents/ExampleConfig.yaml
  1. You'll see the following output when the Flywheel CLI is using the config file:
fw ingest template ~/Documents/DataToImport TemplateExample --config-file ~/Documents/ExampleConfig.yaml

Reading config options from: Users/AvaFranklin/Documents/ExampleConfig.yaml

Warning

CLI arguments override anything set in the config file.

For example, if you add the flag --group Psychology , but the config file includes the line group: PsychLab, then Flywheel will use Psychology as the group name.

Customization FAQs

Can I change the order of the settings in the config file?

The example config above uses sections to organize the settings. These sections can be removed or reordered. However, there are special considerations for the options under the Template and Group/Project Settings section (see the template article for more information).

If I have created a template or de-id profile already, can I reuse that in the ingest config file?

Yes. If you created a template, de-id profile, or config file to use with the import command, those files can be integrated in the ingest config. This means if those files were valid with the import command, they are also valid for the ingest command.

Are there more settings I can add to the config file?

Yes. The valid settings for the config file depend on which fw ingest command you use. The optional flags in the reference articles are the same settings you can add to the config file. See the following articles for more information:

Resources

  1. Online YAML validator: YAML lint