Flywheel Gears

Introduction

Do you spend a lot of time preparing your data for use? Flywheel Gears reduce data-management overhead by automating many routine, time-consuming tasks.

Gears are applications that run in Flywheel. They come in two flavors depending on their functionality: Utility or Analysis. For example, to convert all files from DICOM to NIfTI format or produce a report on QA metrics like displacement and signal spikes, you can use a Utility Gear. Or use an Analysis Gear to run popular tools such as Freesurfer.

Learn more about how Gears can reduce your data-management overhead and allow you to focus on the research.

Instruction Steps

View gears available on a site

To view the available Gears in your environment, click Installed Gears in the left navigation menu.

Add a Gear to a site

Site Admins can add more gears in two ways:

• The Gear Exchange: The Gear Exchange is a curated collection of Gears maintained by Flywheel. These Gears are made available through the contributions of Flywheel employees, customers, and members of the broader research community. Browse the the Gear Exchange for more information, and contact Flywheel Support to add these Gears to your site (only Site Admins can install Gear Exchange gears).
• Develop your own Gear: You can also create your own custom gear to, with adequate permissions, upload to your site. See our Gear Developer tutorial for more information on how to build your first gear.
  

Run a Gear

1. Navigate to a project/subject/session/search results from which you want to launch the gear.
2. Select container.
3. Click Run Gear or, from the Analyses tab, Run Analysis Gear in the top right corner, then (if needed) select type of gear Utility or Analysis, and select gear from the drop-down menu. Note that different versions of gears may be available; the default selection will be the latest version uploaded to this Flywheel site.

1. Once a selection has been made, you will be brought to a modal with 3 tabs--inputs, configuration, and information:
2. Inputs
   • The inputs tab is where the user selects the input they wish to run their gear on. Flywheel's input selector allows you to move up and down the Flywheel hierarchy. Click the right arrow at the end of a container in to dive in or use the links at the top of the modal to move up the hierarchy. A Gear manifest may optionally have a suggested File type for Files needed as input. If the type is specified, when you are asked to select Files to run the Gear, Flywheel will present those Files to the user at the top of the drop-down under the heading Suggested Files. All other Files will be presented under the heading Other Files.
     
   • You can also tags to the Gear job. Tagging Gear jobs is helpful for tracking.
     
   • If it's an analysis gear, this tab is where you may specify the label of the analysis container to be created.
     
3. Configuration
   • Different configuration options are available for each gear and can be found in the Configuration tab.
     
4. Information
   • The Information tab provides more context around the gear implementation and the underlying algorithm. Links and contact information are listed if the gear maintainer provided them. The maintainer of the gear is the creator of the Flywheel gear itself. The Author field denotes who is responsible for the underlying science algorithm. Questions about the Flywheel implementation of the gear would go to the Maintainer. Questions about the underlying algorithm would be best answered by the Author and a link to their website is often provided.
     
5. Once you've specified your input Files and made any desired modifications to the configuration of the Gear, click Run Gear.
   
6. There are two easy places to check on a Gear run's progress:
7. Select the Provenance tab in the Session Detail. The Provenance tab provides a list of the Gears that have been run, their inputs, outputs, and allows you to view and download the log. Click the Refresh button to reload the page.
   
8. Navigate to the Jobs Log tab on the left to access similar information.
9. Once the job is complete you can view detailed logs, including the input and output files for the Gear run. If you ran an Analysis Gear, you can view the output in the Analyses tab.

Tips

• Cancel Running Gears: To cancel a running gear, navigate to the Provenance tab or Jobs Log. If the gear is still running a Cancel button will appear next to the View Log button. Click the cancel button to cancel the running of the gear. Once the run is canceled, any created output will be disposed of.
  
• It may take several minutes for a job to process; corresponding pages may need to be refreshed to display results.
• To view Gear information, hover over the Gear origins icon. A display will pop up that tells you the date and time the Gear run was initiated, the file name and the file size.
  
• Managing Analyses: Once an analysis has been created, users can view or download the outputs in the Analysis tab. Each listed analysis should also contain information about who created it, when, and (if applicable) the name of the gear that ran and an associated job status. Users can also create notes about the analysis. Multiple analyses can exist on a single project/subject/session/acquisition. Users have the ability to modify a Gear and re-analyze data. To delete an analysis, click the accordion menu in the top right corner of the Session Detail, then select Delete.
  
• Batch run Gears: To run a Gear against multiple sessions or acquisitions at the same time, use batch processing
• Use Gear Rules to automate gear runs, described below.

Automate Gears Using Gear Rules

Manually running a gear each time you have new data can be time-consuming. Gear Rules allow you to automate a project's data processing. Whenever the conditions of the gear rule are met, the rule triggers a specific gear to run.

Create a simple project gear rule to automatically classify DICOM files:

1. Click Projects in the left navigation menu.
2. Select the options menu , and choose Gear Rules.
3. Click Add New Rule.
4. Enter a name for the rule
5. Under If the data matches ALL of the following criteria, Select file type from the list.
6. Enter dicom for the file type.
7. Click Select Gear.
8. Choose SciTran: MR Classifier.
9. Select a version of the Gear to run. In most cases you should use the latest version.
10. Disable Always use the latest gear version.

When this is enabled, Flywheel automatically updates the gear when a newer version is published. However, updating the gear version may have unintended consequences for provenance and may change how the gear works.

1. Modify the Gear configuration if necessary.
2. Click Save Changes.
   
3. Click Save on the Gear rule.

Now, each time a DICOM file is added to the project, Flywheel will automatically run the DICOM MR Classifier. Correctly classifying data and extracting metadata greatly increases the value of raw data and allows you to do more with it inside Flywheel. For example, now that your data is properly classified, you can create more gears rules to automate converting DICOM files to NIfTI using the dcm2niix: DICOM to NIfTI conversion Gear.

Next Steps

Learn how to search for data.