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 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 Using Gears article.

Example Gear Rules

To start we'll go through creating and understanding common Gear Rules. To create a Gear Rule, you will need the Manage Gear Rules permission.

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.

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.

Tip

Selecting the Triggering Input for gears with multiple inputs

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.

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.

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.

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.

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

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. Regular expressions are interpreted differently in different settings. Here, JavaScript syntax is used (as opposed to Python, Golang, etc.).

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

Gear Rule Logic Execution

For more detail on how the triggering logic works, please see Gear Rule Processing Details.

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 select to run either Utility or Analysis Gears in either gear rules or site templates.

{[{category.name}]}