When an acquisition file is added or modified, all files in the acquisition will be compared to the project's Gear Rules to determine if any new gears should be run on the acquisition.
This article gives an overview of Gear Rule logic and how to create your own Gear Rule.
Note
Prefer to watch a video?
We have a collection of videos showing you how to get the most out of Flywheel. See these for more directions:
See all Flywheel webinars or our Youtube channel for more videos.
A Project Admin can select from the following criteria to create the Gear Rule logic:
If the data matches ANY of the following criteria: A file must match at least one of the criteria under this section to trigger the Gear
If the data matches ALL of the following criteria: A file must match all criteria listed below
Regex: If the Regex checkbox is selected, the text string entered will be interpreted with Regular Expression rules, or if it's not selected than an exact match of the string will be used in the criteria.
Logic Criteria |
Notes |
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 or see the list of default file classifications for MR data 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 |
Acquisition File Type |
An acquisition must have files that match the specified type for this rule to apply. Common file types are: dicom, nifti, bvec, bval, parrec, pfile, and ismrmrd. This specification is useful for Gears that accept multiple input file types (e.g., bvec, bval, nifti). |
Acquisition File Classification |
An acquisition must have files that match the specified classification for this rule to apply. Learn more about how data gets classified in Flywheel or see the list of default file classifications for MR data in Flywheel. You can also create custom classifications for your data. |
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.
Let's walk through a common Gear Rule: Running the MRIQC Gear.
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 highlighted file you can see the results of the MRIQC Gear.
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.
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.