Plugins are a feature in Snakebids that enables you to add custom functionality to your Snakebids application after parsing CLI arguments but before invoking Snakemake. For example, you can use a plugin to perform BIDS validation of your Snakebids app’s input, which ensures your app is only executed if the input dataset is valid. You can either use those that are distributed with Snakebids (see Using plugins) or create your own plugins (see Creating plugins).
For a full list of plugins distributed with Snakebids, see the Plugins reference page.
To add one or more plugins to your
SnakeBidsApp, pass them to the
SnakeBidsApp constructor via the
plugins parameter. Your plugin will have access to CLI parameters (after they’ve been parsed) via their names in
SnakeBidsApp.config. Any modifications to that config dictionary made by the plugin will be carried forward into the workflow.
As an example, the distributed
BidsValidator plugin can be used to run the BIDS Validator on the input directory like so:
import subprocess from snakebids.app import SnakeBidsApp from snakebids.plugins.validator import BidsValidator SnakeBidsApp( "path/to/snakebids/app", plugins=[BidsValidator] ).run_snakemake()
A plugin is a function or callable class that accepts a
SnakeBidsApp as input and returns a modified
As an example, a simplified version of the bids-validator plugin that runs the BIDS Validator could be defined as follows:
import subprocess from snakebids.app import SnakeBidsApp from snakebids.exceptions import SnakeBidsPluginError class BidsValidator: """Perform BIDS validation of dataset Parameters ----------- app Snakebids application to be run """ def __call__(self, app: SnakeBidsApp) -> None: # Skip bids validation if app.config["plugins.validator.skip"]: return try: subprocess.run(["bids-validator", app.config["bids_dir"]], check=True) except subprocess.CalledProcessError as err: raise InvalidBidsError from err class InvalidBidsError(SnakebidsPluginError): """Error raised if input BIDS dataset is invalid, inheriting from SnakebidsPluginError. """
When adding plugin-specific parameters to the config dictionary, it is recommended to use namespaced keys (e.g.
plugins.validator.skip). This will help ensure plugin-specific parameters do not conflict with other parameters already defined in the dictionary or by other plugins.
A plugin can be used to implement any logic that can be handled by a Python function. In the above example, you may also want to add some logic to check if the BIDS Validator is installed and pass along a custom error message if it is not. Created plugins can then be used within a Snakebids workflow, similar to the example provided in Using plugins section. Prospective plugin developers can take a look at the source of the
snakebids.plugins module for examples.
When creating a custom error for your Snakebids plugin, it is recommended to inherit from
SnakebidsPluginError such that errors will be recognized as a plugin error.