Export templates

  • Updated

When you download a project from Flywheel, by default the data is downloaded to the destination in the Flywheel hierarchy. With export templates you can customize how Flywheel organizes and labels your data on export.

This article explains how to create an export template to format your downloaded data.

Step 1: Create the export template

  1. The export template is a YAML file, so to begin, open a plain text editor (for example, Sublime, TextEdit, or Notepad), and save as a yaml file. 

  2. Copy and paste the default export template:

    ---
file: 
  acquisition: "{group.id}/{project.label}/{subject.label}/{session.label}/{acquisition.label}"

    This template exports data in the same structure found within Flywheel. For example:

    {group.id}/ 
    {project.label}/
	{subject.label}/
	    {session.label}/
		{acquisition.label}/
		    file.png
		{acquisition.label}/
		    file.png
		{acquisition.label}/
		    file.dcm.zip

  3. You can add or remove the metadata fields to change the structure of the downloaded data as well as the folder names.

    In this example, we will add some additional folders that are labeled with the following metadata

    • file type

    • file modality

    • file classification measurement

    We also no longer need the group or project structure, so we'll remove those fields.

  4. Based on the above changes, the new export template would like:

    file:
  acquisition: "{subject.label}/{session.label}/{file.type}/{file.modality}/{file.classification.measurement}"

    Note

    Use / to create subfolders

    Based on the template above, data is downloaded in the following format:

    TEMPLATE FORMAT                                  EXAMPLE
    {subject.label}                           →      001/     
  {session.label}                         →        ses-1/
    {file.type}                           →          dicom/
      {file.modality}                     →            MR/
        {file.classification.measurement} →              T1/
                                                               1211-file.dcm
                                                                                                                        
      {file.modality}                     →            MR/
        {file.classification.measurement} →              T1/                                                                    
                                                           1221-file.dcm                                                           
      {file.modality}                     →            MR/
        {file.classification.measurement} →              T1/
                                                           1231-file.dcm

Step 2: Sync a project to your computer

Now that you have a template, use it in the CLI command to sync a project to your computer (the sync command also allows for syncing to an S3 bucket)

  1. If you have not already, upgrade your Flywheel CLI to version 15.1 or later.

    check the version using the command: fw version

  2. Open the Terminal or Windows Command Prompt app, and enter the following command:

    fw sync fw://group/project ~/localFolder --export-templates-file export.yaml

    For example:

    fw sync fw://Lab612/Psychology ~/Documents/StudyData --export-templates-file ~/Documents/export.yaml

    Tip

    Use the --dry-run flag to create an audit log attached to the project that shows a preview of how data would be downloaded. This allows you to review the labels and structure before actually downloading all of the data. See our article on fw sync for more information.

  3. The project data is downloaded in the format specified and the sync log is attached to the project in Flywheel.

Additional considerations

  • If Flywheel field name is incorrect or there is no value, the export template uses "unknown" instead.

  • Export templates can also be used when syncing to an S3 bucket