Gear Rules
Introduction
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 using the triggering file as an input.
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 Flywheel Gears article.
Instruction Steps
To start we'll go through some examples creating and understanding common Gear Rules. To create a Gear Rule, you will need the Manage Gear Rules permission.
Example: 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 Utility Gear.
- Choose SciTran: MR Classifier.
- Select a version of the Gear to run. In most cases you should use the latest version.
-
Keep Always use the latest gear version disabled for now (the default)
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 a gear run including failures if the new gear version has material changes.
For example, if a new version of a gear requires additional inputs when the prior did not, the gear will fail.
If a permission is now are now needed in the gear version the system will default to read-only permission and this may also cause the gear to fail of a different permission is needed by the new gear version.
-
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.
Example: 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:
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 \
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:
1 2 3 4 5 6 |
|
- 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. Regular expressions are interpreted differently in different settings. Here, JavaScript syntax is used (as opposed to Python, Golang, etc.).
Types of Rule Triggering Criteria
The table below shows the different types of criteria and how they trigger the gear rule.
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. One 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 |
Selecting the Triggering Input for Gear Rules
The gears used in the example above have only one required input. In general there are gears with more than one required input, zero or more optional inputs, and also gears with no inputs. Each of these can be used in a gear rule. Since there is only one triggering file, which varies because it is identified using the rule conditions, the other required inputs must have a 'fixed' file name associated with them.
One Required Input
For a gear with one required input, like the examples above, the file that triggers the gear rule will be fed to that input of the gear during processing.
No Inputs
If the particular gear has no inputs, the gear rule still triggers due to a file meeting all the conditions for triggering. The gear executes in the specified container. There is no input specification required.
More Than One Required Input
When the gear has more than one required input, you need to pick which of the required inputs should be given the trigger file by Selecting the Trigger input from Available Inputs. Also, you will need to provide input files for all the remaining required inputs so that the gear has all inputs necessary to run.
Optional Inputs
If the gear has optional inputs, you have the option of providing an input file for these inputs. Optional inputs can never be a trigger input.
Project Gear Rules Populated from Site Gear Rule Templates
When a new project or a Smart Copy is created, gear rules are populated from the site wide templates. In situations where additional information is required for the rule to function (for example specific project files for fixed inputs) you will see an icon on the rule header. This is a reminder that more info is needed before the rule can be enabled on the project. The specific fields that need information will be indicated when you open the rule.
Gear Rule Logic Execution
For more detail on how the triggering logic works, please see Gear Rule Processing Details.
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 files.
- Also gears are only triggered when a rule changes from False to True as a result of a file or data change.
Managing Gear Rules
Disabling 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 grayed out. In the image below, the "Create Nifti" rule is disabled.
Tip
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.
Deleting a Gear Rule
To delete a gear rule, click the delete button on the gear rule. Deleting a gear rule will remove it from the project.
FAQs
How do I set a Gear Rule Configuration Setting From the Gear Rule Page?
One should be able to change the gear configuration from the gear rule when they choose the option to Change the Gear Version. This will also pull up the gear's current configuration and allow changes.
What Kinds of Gears can be Used in a Gear Rule?
- You can select either Utility or Analysis Gears in either gear rules or site templates.
- Gears that use the Flywheel SDK are also available for gear rules or site templates.
How do I re-trigger a gear rule for a particular file?
Re-triggering a gear rule requires the file to be put back into the pre-triggered state. This is because gears rules are triggered based on a change in state and only trigger once per file. You can't just change another criteria used by the gear rule. For example, if the file triggered the gear rule a tag change, the tag for the file needs to be changed back, and then changed to the triggering value to trigger the gear rule again.