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

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:

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. 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.
6. Under If the data matches ALL of the following criteria, Select file type from the list.
7. Enter dicom for the file type.
8. Click Select Gear.
9. Choose Utility Gear.
10. Choose SciTran: MR Classifier.
11. Select a version of the Gear to run. In most cases you should use the latest version.
12. 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.

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

1. 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

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:

  + 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 files.

Also gears are only triggered when a rule changes from False to True as a result of a file or data change.

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 Execution

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

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.

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.

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.

One 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.

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.