Plugins¶

Note

This page consists of plugins distributed with Snakebids. Externally developed and distributed plugins may be missing from this page.

Core¶

These plugins provide essential bids app features and will be needed by most apps.

class snakebids.plugins.BidsArgs(argument_group='', bids_dir=True, output_dir=True, analysis_level=True, analysis_level_choices=None, analysis_level_choices_config=None, participant_label=True, exclude_participant_label=True, derivatives=True)¶

Add basic BIDSApp arguments.

Parameters:

argument_group (str) – Specify title of the group to which arguments should be added
bids_dir (bool) – Indicate if bids_dir (first bids argument) should be defined
output_dir (bool) – Indicate if output_dir (second bids argument) should be defined
analysis_level (bool) – Indicate if output_dir (third bids argument) should be defined
analysis_level_choices (list[str] | None) – List of valid analysis levels
analysis_level_choices_config (str | None) – Configuration key containing analysis level choices
participant_label (bool) – Indicate if participant_label should be defined. Used to filter specific subjects for processesing
exclude_participant_label (bool) – Indicate if exclude_participant_label should be defined. Used to excluded specific subjects from processesing
derivatives (bool) – Indicate if derivatives should be defined. Used to allow automatic derivative indexing or specify paths to derivatives.

CLI Arguments¶

All arguments are added by default, but can be disabled using their respective parameters. Additionally, arguments can be directly overridden by adding arguments to the parser before the plugin runs, using the following dests:

bids_dir: The input bids directory
output_dir: The output bids directory
analysis_level: The level of analysis to perform (usually participant or group)
participant_label: Collection of subject labels to include in analysis
exclude_participant_label: Collection of subject labels to exclude from analysis
derivatives: Collection of derivative folder paths to include in bids indexing.

Note that only the dest field matters when overriding arguments, all other feature, including positional versus optional, are incidental. Other than adding arguments for the above dests, BidsArgs makes no assumptions about these arguments. Other plugins, however, may expect to find data in the parser namespace or config corresponding to the dest names.

Warning

Overriding just one or two of the positional arguments may alter the order, preventing the app from being called correctly. Thus, if any of the positional args are being overridden, they all should be.

Analysis levels¶

Valid analysis levels can be set using the analysis_level_choices key or the analysis_level_choices_config key. If both are set, an error will be raised. If neither are set, the config will first be searched for the analysis_levels key. If this is not found, analysis levels will be set to ["participant", "group"].

add_cli_arguments(parser, argument_groups, config)¶

Add arguments from config.

Parameters:

parser (argparse.ArgumentParser) –
argument_groups (ArgumentGroups) –
config (dict[str, Any]) –

class snakebids.plugins.ComponentEdit(components_key='pybids_inputs')¶

Use CLI arguments to edit the filters, wildcards, and paths of components.

Arguments are added based on the components specified in config. For each component, a --filter-<comp_name>, --wildcards-<comp_name>, and a --path-<comp_name> argument will be added to the CLI. After parsing, these arguments are read and used to update the original component specification within config.

Filters are specified on the CLI using ENTITY[:METHOD][=VALUE], as follows:

ENTITY=VALUE selects paths based on an exact value match.
ENTITY:match=REGEX and ENTITY:search=REGEX selects paths using regex with re.match() and re.search() respectively. This syntax can be used to select multiple values (e.g. 'session:match=01|02').
ENTITY:required selects all paths with the entity, regardless of value.
ENTITY:none selects all paths without the entity.
ENTITY:any removes filters for the entity.

CLI arguments created by this plugin cannot be overridden.

Parameters:: components_key (str) – Key of component specification within the config dictionary.

add_cli_arguments(parser, config)¶

Add filter, wildcard, and path override arguments for each component.

Parameters:

parser (ArgumentParser) –
config (dict[str, Any]) –

update_cli_namespace(namespace, config)¶

Apply provided overrides to the component configuration.

Parameters:

namespace (dict[str, Any]) –
config (dict[str, Any]) –

class snakebids.plugins.CliConfig(cli_key='parse_args')¶

Configure CLI arguments directly in config.

Arguments are provided in config in a dictionary stored under cli_key. Each entry maps the name of the argument to a set of valid arguments for add_argument().

This plugin will attempt to be the first to add arguments, and thus can be used to override arguments from other compatible plugins, such as BidsArgs

Parameters:: cli_key (str) – Key of dict containing arguments

Example

parse_args:
    --tunable-parameter:
        help: |
            A parameter important to the analysis that you can be set from the
            commandline. If not set, a sensible default will be used
        default: 5
        type: float
    --alternate-mode:
        help: |
            A flag activating a secondary feature of the workflow
        action: store_true
    --derivatives:
        help: |
            An alternate help message for --derivatives, which will override
            the help message from argument given by ``BidsArgs``. Note that we
            must again specify the ``nargs`` and ``type`` for the param
        type: Path
        nargs: "*"

add_cli_arguments(parser, config)¶

Add arguments from config.

Parameters:

parser (ArgumentParser) –
config (dict[str, Any]) –

class snakebids.plugins.Pybidsdb(argument_group=None)¶

Add CLI parameters to specify and reset a pybids database.

Parameters:: argument_group (str | None) – Specify title of the group to which arguments should be added

CLI Arguments¶

Two arguments are added to the CLI. These can be overridden by adding arguments with corresponding dests before this plugin is run:

plugins.pybidsdb.dir: (Path) Path of the database
plugins.pybidsdb.reset: (bool) Boolean indicating the database should be reset.

After parsing, the above dests will be moved into config under the following names:

plugins.pybidsdb.dir → pybidsdb_dir
plugins.pybidsdb.reset → pybidsdb_reset

This plugin only handles the CLI arguments, it does not do any actions with the database. The above config entries can be consumed by downstream processes.

add_cli_arguments(parser, argument_groups)¶

Add database parameters.

Parameters:

parser (argparse.ArgumentParser) –
argument_groups (ArgumentGroups) –

update_cli_namespace(namespace, config)¶

Assign database parameters to config.

Parameters:

namespace (dict[str, Any]) –
config (dict[str, Any]) –

Utility¶

These plugins add additional features that may be helpful to most bids apps.

class snakebids.plugins.BidsValidator(raise_invalid_bids=True)¶

Perform validation of a BIDS dataset using the bids-validator.

If the dataset is not valid according to the BIDS specifications, an InvalidBidsError is raised.

An argument –skip-bids-validation is added to the CLI. This argument can be overridden by adding an argument with dest plugins.validator.skip before this plugin runs.

Two entries are added to config: - "plugins.validator.skip": Indicates if validation was skipped - "plugins.validator.success": Indicates if validation succeeded

Parameters:: raise_invalid_bids (bool) – Flag to indicate whether InvalidBidsError should be raised if BIDS validation fails. Default to True.

add_cli_arguments(parser)¶

Add option to skip validation.

Parameters:: parser (ArgumentParser) –

finalize_config(config)¶

Perform BIDS validation of dataset.

Raises:: InvalidBidsError – Raised when the input BIDS directory does not pass validation with the bids-validator
Parameters:: config (dict[str, Any]) –
Return type:: None

Workflow Integrations¶

These plugins enable integrations with specific workflow managers.

class snakebids.plugins.SnakemakeBidsApp(snakemake_dir, *, configfile_path=_Nothing.NOTHING, configfile_outpath=None, snakefile_path=_Nothing.NOTHING)¶

Snakebids app with config and arguments.

Loads the BidsArgs, CliConfig, Pybidsdb, and ComponentEdit plugins as dependencies.

Parameters:

snakemake_dir (str | Pathlike[str]) – Root directory of the snakebids app, containing the config file and workflow files.
configfile_path (pathlib.Path | None) – Path of config file. By default, looks for config.yaml, config.json, snakebids.yaml, or snakebids.json either within the snakemake_dir or within snakemake_dir/config
configfile_outpath (pathlib.Path | None) – Path of output configfile that will be consumed by the snakemake workflow. This is only necessary if the input configfile is not within the snakemake directory. If given, it should be the same as the path specified under configfile: ...` within the ``Snakefile
snakefile_path (pathlib.Path) – Absolute path to the input Snakefile. By default, looks for Snakefile within the snakemake_dir or snakemake_dir/workflow

cwd: Path¶

The current working directory for running snakemake.

This is where the .snakemake metadata folder will be placed.

force_output: bool¶

Allow specifying outputs in unrecognized, non-empty directories.

After the first run, a .snakebids file will be created in the directory to mark the directory as safe for future runs.

classmethod create_empty()¶: Create empty instance of plugin.

initialize_config(config)¶

Read config file and load into config dict.

Parameters:: config (dict[str, Any]) –

add_cli_arguments(parser)¶

Add snakemake help and force_output arguments.

Parameters:: parser (ArgumentParser) –

handle_unknown_args(args, config)¶

Add snakemake args to config.

Parameters:

args (list[str]) –
config (dict[str, Any]) –

update_cli_namespace(namespace, config)¶

Resolve Paths within the namespace and set target.

Parameters:

namespace (dict[str, Any]) –
config (dict[str, Any]) –

finalize_config(config)¶

Perform final steps for snakemake workflows.

Expects to find output_dir in config as a fully resolved Path

Modify output_dir to output/results if output is set to the app dir
Set self.cwd
Write config file into output dir
Add snakemake specific parameters to config

Parameters:: config (dict[str, Any]) –

run(config)¶

Run snakemake with the given config, after applying plugins.

Parameters:: config (dict[str, Any]) –

Plugin Development¶

snakebids.bidsapp.hookimpl()¶

Marker to be imported and used in plugins (and for own implementations).

See pluggy.HookimplMarker() for more information. Its parameters are represented here fore reference.

Parameters:

optionalhook – If True, a missing matching hook specification will not result in an error (by default it is an error if no matching spec is found). See Optional validation.
tryfirst – If True, this hook implementation will run as early as possible in the chain of N hook implementations for a specification. See Call time order.
trylast – If True, this hook implementation will run as late as possible in the chain of N hook implementations for a specification. See Call time order.
wrapper – If True (“new-style hook wrapper”), the hook implementation needs to execute exactly one yield. The code before the yield is run early before any non-hook-wrapper function is run. The code after the yield is run after all non-hook-wrapper functions have run. The yield receives the result value of the inner calls, or raises the exception of inner calls (including earlier hook wrapper calls). The return value of the function becomes the return value of the hook, and a raised exception becomes the exception of the hook. See Wrappers.
hookwrapper – If True (“old-style hook wrapper”), the hook implementation needs to execute exactly one yield. The code before the yield is run early before any non-hook-wrapper function is run. The code after the yield is run after all non-hook-wrapper function have run The yield receives a pluggy.Result object representing the exception or result outcome of the inner calls (including earlier hook wrapper calls). This option is mutually exclusive with wrapper. See Old-style wrappers.
specname – If provided, the given name will be used instead of the function name when matching this hook implementation to a hook specification during registration. See Hookspec name matching.

Specs¶

The spec contains the hooks recognized by snakebids. Each spec has a specific function name and a set of available arguments, and will be called at a specific time during app initialization.

snakebids.bidsapp.hookspecs.initialize_config(config)¶

Modify config dict before creation of CLI parser.

Config should be modified in place.

Parameters:: config (dict[str, Any]) – Possibly empty dictionary of configuration values

snakebids.bidsapp.hookspecs.add_cli_arguments(parser, config, argument_groups)¶

Add any number of arguments to the argument parser.

If special intervention is not made in the update_cli_namespace() hook, argument data will be automatically merged into config following argument parsing under the argument dest. To avoid naming conflicts, plugins should explicitly set the dest of each argument they add to plugins.<plugin_name>.<argument_name>.

Parameters:

parser (argparse.ArgumentParser) – BIDS app CLI parser
config (dict[str, Any]) – Configuration dictionary preloaded with values from initialize_config()
argument_groups (ArgumentGroups) –

snakebids.bidsapp.hookspecs.get_argv(argv, config)¶

Set or modify the CLI parameters that will be parsed by the parser.

Parameters:

argv (list[str]) –
config (dict[str, Any]) –

Return type:

list[str] | None

snakebids.bidsapp.hookspecs.handle_unknown_args(args, config)¶

If parse_known_args enabled, handle unknown arguments.

Parameters:

args (list[str]) – List of unknown arguments parsed by the argparse parser
config (dict[str, Any]) – Configuration dictionary

snakebids.bidsapp.hookspecs.update_cli_namespace(namespace, config)¶

Interact with argument parsing results before they are merged into config.

The namespace contains the results from parse_args() (equivalent to vars(Namespace)). Any modifications made to this dict will be carried forward in app initialization. For instance, if an entry is deleted from namespace, it will not be available to downstream plugins or be copied into config.

Parameters:

namespace (dict[str, Any]) – the dictionary of values derived from the argparse namespace
config (dict[str, Any]) – Configuration dictionary

snakebids.bidsapp.hookspecs.finalize_config(config)¶

Perform modifications to the config following merging of parsed arguments.

Parameters:: config (dict[str, Any]) – Configuration dictionary

snakebids.bidsapp.hookspecs.run(config)¶

Consume configuration and perform actions.

This hook runs directly after finalize_config(). The config should not be modified.

Parameters:: config (dict[str, Any]) – The finalized configuration dictionary