Gear Rules – Flywheel.io

Gear Rules allow you to automate your project's data processing. Whenever the conditions of the gear rule are met, the rule triggers a specific gear to run. This article gives an overview of Gear Rule logic and how to create your own Gear Rule. To learn more about how to use individual Gears, see our Using Gears article.

Example Gear Rules

To start we'll go through creating and understanding common Gear Rules.

Automatically classify DICOM files

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

Click Projects in the left navigation menu.
Select the options menu , and choose Gear Rules.
Click Add New Rule.
Enter a name for the rule.
Choose a container from the list. This is where the Gear Rule will watch for matching files to trigger the Gear. You can choose Any Container to watch all files.
Under If the data matches ALL of the following criteria, Select file type from the list.
Enter dicom for the file type.
Click Select Gear.
Choose SciTran: MR Classifier.
Select a version of the Gear to run. In most cases you should use the latest version.
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.
Modify the Gear configuration if necessary.
Click Save Changes.
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.

Using regex with the MRIQC Gear rule

To start, let's go through a common Gear Rule: Running the MRIQC Gear to extract image quality metrics from structural and functional MRI data.

To begin we'll take a look at the If the data matches ALL of the following criteria section.

File Type is nifti. Learn more about file types in Flywheel.
File Classification is ^(Structural|Functional)$. This is a regular expression which is looking for either Structural or Functional. It is case sensitive. Learn more about file classifications in Flywheel.
File Classification is ^(T1|T2|T2\*)$. This is a regular expression looking for T1, T2, or T2* classifications. It is also case sensitive. However, in the next section we can see that files with the Classification In-Plane are excluded from the Gear.

So combined with the criteria before, the Classification must be a combination of Structural/Functional and T1/T2/T2*. However, in the next section there is an exception: if the File Classification In-Plane, the Gear will not run against the file.

Below is an example of a file that meets the Gear Rule criteria and as a result would trigger MRIQC to run:

Tip

Below the circled file you can see the results of the MRIQC Gear.

Gear Rule logic

A user with the Manage Gear Rules permission can select from the following criteria to create the Gear Rule logic:

If the data from <container> matches the following criteria: Files at in the container you choose are evaluated against the criteria. In other words this is where the Gear will be run. Options are:
- Projects
- Subjects
- Sessions
- Acquisitions
- Analysis Outputs
- Any container (watches all of the containers in the list)
If the data matches ANY of the following criteria: A file from the container chosen above must match at least one of the criteria under this section to trigger the Gear. See the table below for more information on the options.
If the data matches ALL of the following criteria: A file from the container chosen above must match all criteria listed below to trigger the Gear. See the table below for more information on the options

Regex: If the Regex checkbox is selected, the text string entered will be interpreted with Regular Expression rules. If it's not enabled then an exact match of the string will be used in the criteria.

Note

Adding or modifying a rule will only run gears on new files/modifications made to acquisitions after the rule changes are saved. It will not trigger jobs for existing data. Files can

Criteria option	Description
File Type	File Type refers to the specified type in the Flywheel Core. Common file types are: dicom, nifti, bvec, bval, parrec, pfile, and ismrmrd. A given file's type must match for this rule to apply.
File Name	A given file with the name specified will match this rule. Wildcards are accepted (e.g., myfile*.nii.gz).
File Classification	File classification must match the specified type for the rule to apply. Learn more about how data gets classified in Flywheel You can also create custom classifications for your data.
File Tags	Files with matching tags will be the input for the Gear. Use file tags to create a pipeline of Gears. This means once one Gear is complete, it will add a tag to the output files. You can then configure a Gear Rule to trigger the next Gear based on that tag. For example: Gear A processes a `myfile.dcm`. On completion, the gear adds tag “alpha” to `myfile.dcm`. A subsequent gear rule looking for a file tagged with “alpha” is triggered and so forth.
Container has file type	A container must have files that match the specified type for this rule to apply. Common file types are: diced, nifty, bvec, oval, parcel, pfile, and ismrmrd. This specification is useful for Gears that accept multiple input file types (e.g., bvec, oval, nifty.)
Container has file classification	A container must have files that match the specified classification for this rule to apply

FAQ

How do I disable a Gear Rule?

To disable a gear rule, open the Gear Rules window from the panel on the left of the Dashboard. You will see a toggle button to the right of each rule. Moving the button to the left disables the rule so that it will not be automatically triggered.

You will be able to see that the rule is disabled in the main 'Gear Rules' window from the button position and because the text is gray'd out. In the image below, the "Create Nifti" rule is disabled.

The ability to disable a rule can come in handy if you have a new version of a gear that you would like to run on your data, but do not want to delete your old gear rule for the older version.

Can I choose an analysis Gear in a Gear Rule?

You can choose to run either Utility or Analysis Gears in Project Gear Rules, but there is a restriction. Gears that use the Flywheel SDK are not available to be selected unless they have the `read-only` key added to them.

The reason for this restriction is that Gear Rules run via a System API key instead of the typical user's API key when a user starts a gear. Since the System API key doesn't have permission to write data outside of its container, it could fail due to permissions. By designating `read-only`, the gear is able to be used to read data but not potentially edit or overwrite any data without it being associated with a particular Flywheel user.

{[{category.name}]}