Gear Building Tutorial Part 3: The Flywheel Environment

Introduction

This document provides information on the Flywheel environment.

Instruction Steps

• The Flywheel Environment
• The Flywheel Directory Structure
• Inputs
• Output
• Config Settings
• Environment

The Flywheel Environment

Before we start building our test gear, we are going to take a brief detour in this part to discuss how Flywheel handles inputs and outputs, as well as any intermediary files created by our gear algorithm. When a gear is run in Flywheel, the environment is set up in a very specific way that is the same for each gear.  This allows us to make generalizations in our code that will always be true.  Since these settings are expected, deviating from them can result in our gear failing.  We'll discuss the main Flywheel environment components that we'll need to know to develop your gear.

The Flywheel Directory Structure

Flywheel handles all of its processing in a specific directory inside the Docker image.  This directory is ALWAYS:

1

/flywheel/v0

The Flywheel directory will contain the following files and folders, along with any additional files we may have copied in when creating our Docker image:

1
2
3
4

/flywheel/v0/  
     ├── work/  
     ├── input/  
     ├── output/  

The work directory is where our gear should do its processing; any intermediate files and processing results should initially go here.  We can create any structure of subdirectories in here that we wish.  After the processing is complete, we can move any files that we want to save as outputs from the work directory to the output directory.  Upon completion of gear execution, ONLY the files in the output directory will get saved back to Flywheel.  More on that below.

The input and output are directories where files are stored as inputs or outputs to the gear.

Inputs

The input directory contains subfolders for every input we specify for the gear. (The names of these subfolders are specified in the manifest, which we'll cover in Part 5).  For example, if we have three inputs: a NIfTI image, a text file, and a json file, we would specify to Flywheel what we wanted to name each input. The "name" of the input is just what Flywheel refers to the input file as.  For example, we could name the NIfTI image "nifti_in", the text file "slice_timing", and the json file "subject_info". Flywheel will then create subdirectories in the "input" folder, one for each input, with the name we assigned.  In this case, Flywheel will generate three subdirectories:

1
2
3
4
5
6
7
8

/flywheel/v0/  
     └── input/  
       ├── nifti-in/  
       │   └── whatever_file_you_give.nii  
       ├── slice_timing/  
       │   └── whatever_file_you_give.txt  
       └── subject_info/  
           └── whatever_file_you_give.json  

This way, we always know exactly where to find our input files, as long as we know what we name them.

Output

When a Docker container finishes running, it terminates itself, and in doing so, deletes all information and files inside.  That doesn't sound very desirable for us, since we'll want the output from our code!  Fortunately, Flywheel has a way around this.  Flywheel also creates an output directory in the flywheel/v0 directory.

Any file that is saved in the output directory is then available in our Flywheel instance, either listed as a file with the acquisitions if it's a utility gear, or in a separate "analysis" container if it's an analysis gear, which you can find in the "Analyses" tab in your Flywheel UI.  There is no limit to the number of files we can place in the output directory.

Config Settings

Sometimes, we need to set values that aren't technically an input file.  For example, maybe we're performing spatial smoothing, and we want to specify the kernel size.  This is called a "config" setting, and we can also specify them in the manifest.  They appear in the user interface as text or check boxes that the user can fill out when they run the gear.  These options are accessible through a python "config" dictionary.  We name each config setting (e.g. "kernel size"), and then in our code, we access the input value through that key in the dictionary.  (config["kernel size"] would have the value our example input).  This is discussed in more detail in later sections.

Environment

Unfortunately, environment variables set in the Dockerfile won't carry over to the gear environment when run on Flywheel.  For most basic gears, this isn't a problem, but for more advanced gears (for example, if we call FSL), these environment variables are important.  We'll briefly learn about how to re-initialize our environmental variables in the manifest file in Part 5.

Wrapping Up

In this part we have walked through the Flywheel environment in anticipation of building our first gear. Understanding how Flywheel expects inputs and outputs to be handled will be useful as we consider how to build our run script and then our gear manifest file. Continue on to Part 4 where we will start creating the script for our test gear to run.

Navigation

Previous: Part 2 Creating Your First Gear

Next: Part 4 The Run Script