Gears
Overview
In Flywheel, a “Gear” is another name for an analysis or computations run on your data. Flywheel Gears are “containers” that package or “bundle” important metadata with the analysis results. Additional information stored within gears includes all of the information about who ran the analysis, when, with what inputs, the analysis software name, version, maintainer, and of course all of the analysis outputs. Gears keep this critical metadata in one place making analyses trackable and easier to review. Gears will already be installed into Flywheel by INC staff, if you wish to add more, see Looking For Other Gears? You can view all gears installed on the UCB Flywheel Instance in the “Installed Gears” View in the Gears section of the sidebar menu. Interested in learning more about gears? Check out Flywheel’s documentation on gears here.
Running Gears
It is important to note, you can start a gear from multiple levels of the Flywheel hierarchy. This provides the flexibility to run a range of software tools that may need any number of inputs, such as only a single acquisition (acquisition level), all acquisitions in a session (session level), all sessions for a single subject (subject level), multiple or all subjects in a given project (project level). Being diligent about the Flywheel hierarchy level you use to run your gear is critical. For example, some gears will only execute if ran at a “session” level.
Running Gears at the Project Level
Running gears at a project level is most commonly used for running group analyses. In order to run a gear on an entire project, follow the steps below.
Select “Projects” on the sidebar menu.
Select your active project.
Navigate to the “Analyses” panel in that project.
Click the “Run Analysis Gear” button in the upper right corner.
Select the gear and version
Click “Run Gear”
Running Gears at the Subject Level
Running gears at a subject level is most commonly used for analyses that require multiple or all sessions from a single subject to be accepted as inputs at the same time. Many BIDS formatted analyses may be run at a subject or session level. In order to run a gear on an entire subject, follow the steps below.
From your project, select “Sessions” panel
Toggle the View to “Subject View”
Select a single subject for your analysis
Select the “Analyses” panel inside the Sessions Menu
Click the “Run Analysis Gear” button in the upper right corner
Running Gears at the Session Level
Running gears at a session level is the most common method for running analysis gears. Most gears including curation, re-naming, and preprocessing gears can be run on a single session. In order to run a gear on a single session, follow the steps below.
From your project, select “Sessions” panel
Make sure the view is toggled to “List View”
Select a single session for your analysis
Select the “Analyses” panel inside the Sessions Menu
Click the “Run Analysis Gear” button in the upper right corner
Running Gears at the Acquisition Level
Running gears on a single acquisition is generally reserved for light weight “Utility” Gears and “Gear Rules”, which will be discussed later. In order to run a gear on a single acquisition, follow the steps below.
From your project, select “Sessions” panel
Make sure the view is toggled to “List View”
Select a single session for your analysis
Select the “Acquisitions” tab
Click the “Run Gear” button in the upper right corner
Select either “Utility Gear” or “Analysis Gear” (gear methods discussed below)
Important
Running an “Analysis Gear” will default to running at a Session Level even from this menu!
Gear Versions
Flywheel Gears are version controlled, meaning both the underlying software version and the version of Flywheel’s container are recorded and stored in the analysis. In addition, INC often makes custom changes to the gears on this instance and is identified with INC versioning.
Example Gear Version:
1.2.5_20.0.6_inc1.0
The meaning of the versioning broken down piece by piece
1.2.5 --> Flywheel Gear Version
20.0.6 --> Underlying Pipeline / Software Version
inc1.0 --> INC Customized Version
If you find that a gear version is missing the inc version tag, that simply means that INC did not modify the gear from what Flywheel originally produced.
Note
When starting a new analysis, it is best practice to select the most updated version of the gear. Once a version is selected for a project, we recommend to use the same version for the duration of your project.
Gear Methods
Running Utility Gears
Utility Gears are lightweight analyses usually used only for converting file types or performing quality assurance checks. The outputs of these gears are saved directly with the input data.
Navigate to the desired project
Select the “Sessions” panel
Select the desired session from the list of sessions
From the “Acquisitions” tab, Click “Run Gear” in the upper right corner
Select Utility Gear
Select a gear and version
Choose a file for the input
- Under the configuration tab, select the necessary options for your job
For more information about each configuration setting, hover the mouse over the info icon next to the configuration
The information tab tells you all the data and metadata that will be stored about the job
Click “Run Gear”
Running Analysis Gears
Analysis Gears are used for larger analyses and are organized as unique containers (or “folders”) in Flywheel. These containers are conveniently called Analyses in your Session view. Analysis Gears package additional information including the gear inputs, configuration, version, logs, and outputs.
To run an Analysis Gear, follow the steps below:
Navigate to the desired project
Select the “Sessions” tab
Select the desired session from Session’s List
From the “Acquisitions” panel, Click “Run Gear” in the upper right corner
Select Analysis Gear
Select the gear and version of the gear you want to run
Select all the necessary input files
- Change any options under the configuration tab that are needed
For more information about each configuration setting, hover the mouse over the info icon next to the configuration
The information tab tells you all the data and metadata that will be stored about the job
Select “Run Gear”
Running High Performance Compute (HPC) Analysis Gears
In order to run Gears on the HPC environment (instead of the CUmulus virtual machines), add a job tag “hpc” when setting up the analysis. This job tag is case sensitive. Additional settings including SLURM resources configurations may be available in the gear’s configuration settings.
View Gear Status
To view the progress of your gear, navigate to the desired session, and then select the “Provenance” tab. Provenance shows a list of all gears for a specific session. To view the results of your Analysis Gears, navigate to the “Analyses” tab.
What To Do If Your Gear Failed?
If your gear fails, first check the job log. If there is an obvious error message such as missing or incorrect input, make that change and run the gear again. If a problem persists or you cannot determine why the gear failed, reach out to the INC staff for assistance.
What To Do If Your Gear Succeeded?
After your analysis gear completes successfully you can inspect the results in the “Analyses” tab. Select the analysis container of interest. You should see a “Results” tab with all data created during the analysis. From this container, you may also review the records of all inputs, configurations, gear information, and logs.
Looking For Other Gears?
The Flywheel Gear Exchange is a place where you can see other gears created for Flywheel (usually by Flywheel staff). If you wish to add another gear to our Flywheel instance, look on the Gear Exchange and contact a member of the INC staff to request the gear be added to UCB Flywheel instance. If the gear is not in the Gear Exchange, contact INC staff as well for a consultation. INC staff can work with Flywheel to develop the gear, or train/direct you on how to develop your own Flywheel gears.