API#

snakebids#

class snakebids.BidsComponent(*, name, path, zip_lists)#

Representation of a bids data component

A component is a set of data entries all corresponding to the same type of object. Entries vary over a set of entities. For example, a component may represent all the unprocessed, T1-weighted anatomical images aqcuired from a group of 100 subjects, across 2 sessions, with three runs per session. Here, the subject, session, and run are the entities over which the component varies. Each entry in the component has a single value assigned for each of the three entities (e.g subject 002, session 01, run 1).

Each entry can be defined solely by its wildcard values. The complete collection of entries can thus be stored as a table, where each row represents an entity and each column represents an entry.

BidsComponent stores and indexes this table. It uses ‘row-first’ indexing, meaning first an entity is selected, then an entry. It also has a number of properties and methods making it easier to incorporate the data in a snakemake workflow.

In addition, BidsComponent stores a template ~BidsComponent.path derived from the source dataset. This path is used by the expand() method to recreate the original filesystem paths.

The real power of the BidsComponent, however, is in creating derived paths based on the original dataset. Using the :meth`~BidsComponent.expand` method, you can pass new paths with {wildcard} placeholders wrapped in braces and named according to the entities in the component. These placeholders will be substituted with the entity values saved in the table, giving you a list of paths the same length as the number of entries in the component.

BidsComponents are immutable: their values cannot be altered.

Parameters:

name (str) –
path (str) –

name: str#: Name of the component

path: str#: Wildcard-filled path that matches the files for this component.

expand(paths=None, /, allow_missing=False, **wildcards)#

Safely expand over given paths with component wildcards

Uses the entity-value combinations found in the dataset to expand over the given paths. If no path is provided, expands over the component path (thus returning the original files used to create the component). Extra wildcards can be specified as keyword arguments.

By default, expansion over paths with extra wildcards not accounted for by the component causes an error. This prevents accidental partial expansion. To allow the passage of extra wildcards without expansion,set allow_missing to True.

Uses the snakemake expand under the hood.

Parameters:

paths (Iterable[Path | str] | Path | str | None) – Path or list of paths to expand over. If not provided, the component’s own path will be expanded over.
allow_missing (bool | str | Iterable[str]) – If True, allow {wildcards} in the provided paths that are not present either in the component or in the extra provided **wildcards. These wildcards will be preserved in the returned paths.
wildcards (str | Iterable[str]) – Each keyword should be the name of an wildcard in the provided paths. Keywords not found in the path will be ignored. Keywords take values or lists of values to be expanded over the provided paths.

Return type:

list[str]

property entities: MultiSelectDict[str, list[str]]#

Component entities and their associated values

Dictionary where each key is an entity and each value is a list of the unique values found for that entity. These lists might not be the same length.

filter(*, regex_search=False, **filters)#

Filter component based on provided entity filters

This method allows you to expand over a subset of your wildcards. This could be useful for extracting subjects from a specific patient group, running different rules on different aquisitions, and any other reason you may need to filter your data after the workflow has already started.

Takes entities as keyword arguments assigned to values or list of values to select from the component. Only columns containing the provided entity-values are kept. If no matches are found, a component with the all the original entities but with no values will be returned.

Returns a brand new BidsComponent. The original component is not modified.

Parameters:

regex_search (bool | str | Iterable[str]) – Treat filters as regex patterns when matching with entity-values.
filters (str | Iterable[str]) – Each keyword should be the name of an entity in the component. Entities not found in the component will be ignored. Keywords take values or a list of values to be matched with the component zip_lists

Return type:

Self

property wildcards: MultiSelectDict[str, str]#

Wildcards in brace-wrapped syntax

Dictionary where each key is the name of a wildcard entity, and each value is the Snakemake wildcard used for that entity.

property zip_lists#

Table of unique wildcard groupings for each member in the component.

Dictionary where each key is a wildcard entity and each value is a list of the values found for that entity. Each of these lists has length equal to the number of images matched for this modality, so they can be zipped together to get a list of the wildcard values for each file.

class snakebids.BidsPartialComponent(*, zip_lists)#

Primitive representation of a bids data component

See BidsComponent for an extended definition of a data component.

BidsPartialComponents are typically derived from a BidsComponent. They do not store path information, and do not represent real data files. They just have a table of entity-values, typically a subset of those present in their source BidsComponent.

Despite this, BidsPartialComponents still allow you to expand the data table over new paths, allowing you to derive paths from your source dataset.

The members of BidsPartialComponent are identical to BidsComponent with the following exceptions:

No name or path
expand() must be given a path or list of paths as the first argument

BidsPartialComponents are immutable: their values cannot be altered.

class snakebids.BidsComponentRow(iterable, /, entity)#

A single row from a BidsComponent

This class is derived by indexing a single entity from a BidsComponent or BidsPartialComponent. It should not be constructed manually.

The class is a subclass of ImmutableList and can thus be treated as a tuple. Indexing it via row[<int>] gives the entity-value of the selected entry.

The entities and wildcards directly return the list of unique entity-values or the {brace-wrapped-entity} name corresponding to the row, rather than a dict.

The expand() and filter() methods behave as they would in a BidsComponent with a single entity.

Parameters:

iterable (Iterable[str]) –
entity (str) –

property entities: tuple[str, ...]#: The unique values associated with the component

property wildcards: str#: The entity name wrapped in wildcard braces

expand(paths, /, allow_missing=False, **wildcards)#

Safely expand over given paths with component wildcards

Uses the entity-values represented by this row to expand over the given paths. Extra wildcards can be specified as keyword arguments.

Uses the snakemake expand under the hood.

Parameters:

paths (Iterable[Path | str] | Path | str) – Path or list of paths to expand over
allow_missing (bool | str | Iterable[str]) – If True, allow {wildcards} in the provided paths that are not present either in the component or in the extra provided **wildcards. These wildcards will be preserved in the returned paths.
wildcards (str | Iterable[str]) – Each keyword should be the name of an wildcard in the provided paths. Keywords not found in the path will be ignored. Keywords take values or lists of values to be expanded over the provided paths.

Return type:

list[str]

filter(spec=None, /, *, regex_search=False, **filters)#

Filter component based on provided entity filters

Extracts a subset of the entity-values present in the row.

Returns a brand new BidsComponentRow. The original component is not modified.

Parameters:

spec (str | Iterable[str] | None) – Value or iterable of values assocatiated with the ComponentRow’s entity. Equivalent to specifying .filter(entity=value)
regex_search (bool | str | Iterable[str]) – Treat filters as regex patterns when matching with entity-values.
filters (str | Iterable[str]) – Keyword-value(s) filters as in filter(). Here, the only valid filter is the entity of the BidsComponentRow; all others will be ignored.

Return type:

Self

class snakebids.BidsDataset(data, layout=None)#

A bids dataset parsed by pybids, organized into BidsComponents.

BidsDatasets are typically generated using generate_inputs(), which reads the pybids_inputs field in your snakemake config file and, for each entry, creates a BidsComponent using the provided name, wildcards, and filters.

Individual components can be accessed using bracket-syntax: (e.g. inputs["t1w"]).

Provides access to summarizing information, for instance, the set of all subjects or sessions found in the dataset.

Parameters:

data (Any) –
layout (BIDSLayout | None) –

layout: BIDSLayout | None#: Underlying layout generated from pybids. Note that this will be set to None if custom paths are used to generate every component

property path: dict[str, str]#: Dict mapping BidsComponents names to their paths.

Warning

Deprecated since version 0.8.0: The behaviour of path will change in an upcoming release, where it will refer instead to the root path of the dataset. Please access component paths using Dataset[<component_name>].path

property zip_lists: dict[str, snakebids.types.ZipList]#: Dict mapping BidsComponents names to their zip_lists

Warning

Deprecated since version 0.8.0: The behaviour of zip_lists will change in an upcoming release, where it will refer instead to the consensus of entity groups across all components in the dataset. Please access component zip_lists using Dataset[<component_name>].zip_lists

property entities: dict[str, MultiSelectDict[str, list[str]]]#: Dict mapping BidsComponents names to to their entities

Warning

Deprecated since version 0.8.0: The behaviour of entities will change in the 1.0 release, where it will refer instead to the union of all entity-values across all components in the dataset. Please access component entity lists using Dataset[<component_name>].entities

property wildcards: dict[str, MultiSelectDict[str, str]]#: Dict mapping BidsComponents names to their wildcards

Warning

Deprecated since version 0.8.0: The behaviour of wildcards will change in an upcoming release, where it will refer instead to the union of all entity-wildcard mappings across all components in the dataset. Please access component wildcards using Dataset[<component_name>].wildcards

property subjects: list[str]#: A list of the subjects in the dataset.

property sessions: list[str]#: A list of the sessions in the dataset.

property subj_wildcards: dict[str, str]#

The subject and session wildcards applicable to this dataset.

{"subject":"{subject}"} if there is only one session, {"subject": "{subject}", "session": "{session}"} if there are multiple sessions.

property as_dict: BidsDatasetDict#

Get the layout as a legacy dict

Included primarily for backward compatability with older versions of snakebids, where generate_inputs() returned a dict rather than the BidsDataset class

Return type:: BidsDatasetDict

classmethod from_iterable(iterable, layout=None)#

Construct Dataset from iterable of BidsComponents

Parameters:

iterable (Iterable[BidsComponent]) –
layout (BIDSLayout | None) –

Return type:

BidsDataset

class snakebids.BidsDatasetDict#: Dict equivalent of BidsInputs, for backwards-compatibility

snakebids.bids(root=None, datatype=None, prefix=None, suffix=None, extension=None, **entities)#

Helper function for generating bids paths for snakemake workflows.

File path is of the form:

[root]/[sub-{subject}]/[ses-{session]/
[prefix]_[sub-{subject}]_[ses-{session}]_[{key}-{val}_ ... ]_[suffix]

Parameters:

root (str or Path, default=None) – root folder to include in the path (e.g. ‘results’)
datatype (str, default=None) – folder to include after sub-/ses- (e.g. anat, dwi )
prefix (str, default=None) – string to prepend to the file name (typically not defined, unless you want tpl-{tpl}, or a datatype)
suffix (str, default=None) – bids suffix including extension (e.g. ‘T1w.nii.gz’)
subject (str, default=None) – subject to use, for folder and filename
session (str, default=None) – session to use, for folder and filename
include_subject_dir (bool, default=True) – whether to include the sub-{subject} folder if subject defined (default: True)
include_session_dir (bool, default=True) – whether to include the ses-{session} folder if session defined (default: True)
**entities (str | bool) – dictionary of bids entities (e.g. space=T1w for space-T1w)
extension (str | None) –
**entities –

Returns:

bids-like file path

Return type:

str

Examples

Below is a rule using bids naming for input and output:

rule proc_img:
    input: 'sub-{subject}_T1w.nii.gz'
    output: 'sub-{subject}_space-snsx32_desc-preproc_T1w.nii.gz'

With bids() you can instead use:

rule proc_img:
   input: bids(subject='{subject}',suffix='T1w.nii.gz')
   output: bids(
       subject='{subject}',
       space='snsx32',
       desc='preproc',
       suffix='T1w.nii.gz'
   )

Note that here we are not actually using “functions as inputs” in snakemake, which would require a function definition with wildcards as the argument, and restrict to input/params, but bids() is being used simply to return a string.

Also note that space, desc and suffix are NOT wildcards here, only {subject} is. This makes it easy to combine wildcards and non-wildcards with bids-like naming.

However, you can still use bids() in a lambda function. This is especially useful if your wildcards are named the same as bids entities (e.g. {subject}, {session}, {task} etc..):

rule proc_img:
    input: lambda wildcards: bids(**wildcards,suffix='T1w.nii.gz')
    output: bids(
        subject='{subject}',
        space='snsx32',
        desc='preproc',
        suffix='T1w.nii.gz'
    )

Or another example where you may have many bids-like wildcards used in your workflow:

rule denoise_func:
    input: lambda wildcards: bids(**wildcards, suffix='bold.nii.gz')
    output: bids(
        subject='{subject}',
        session='{session}',
        task='{task}',
        acq='{acq}',
        desc='denoise',
        suffix='bold.nii.gz'
    )

In this example, all the wildcards will be determined from the output and passed on to bids() for inputs. The output filename will have a ‘desc-denoise’ flag added to it.

Also note that even if you supply entities in a different order, the entities will be ordered based on the OrderedDict defined here. If entities not known are provided, they will be just be placed at the end (before the suffix), in the order you provide them in.

Notes

For maximum flexibility all arguments are optional (if none are specified, will return empty string). Note that datatype and prefix may not be used in isolation, but must be given with another entity.
Some code adapted from mne-bids, specifically https://mne.tools/mne-bids/stable/_modules/mne_bids/utils.html

snakebids.filter_list(zip_list, filters, return_indices_only=False, regex_search=False)#

This function is used when you are expanding over some subset of the wildcards i.e. if your output file doesn’t contain all the wildcards in BidsComponent.wildcards

Parameters:

zip_list (ZipListLike) – generated zip lists dict from config file to filter
filters (Mapping[str, Iterable[str] | str]) – wildcard values to filter the zip lists
return_indices_only (bool) – return the indices of the matching wildcards
regex_search (bool) – Use regex matching to filter instead of the default equality check.

Return type:

ZipList | list[int]

Examples

>>> import snakebids

Filtering to get all subject='01' scans:

>>> snakebids.filter_list(
...     {
...         'dir': ['AP','PA','AP','PA', 'AP','PA','AP','PA'],
...         'acq': ['98','98','98','98','99','99','99','99'],
...         'subject': ['01','01','02','02','01','01','02','02' ]
...     },
...     {'subject': '01'}
... ) == {
...     'dir': ['AP', 'PA', 'AP', 'PA'],
...     'acq': ['98', '98', '99', '99'],
...     'subject': ['01', '01', '01', '01']
... }
True

Filtering to get all acq='98' scans:

>>> snakebids.filter_list(
...     {
...         'dir': ['AP','PA','AP','PA', 'AP','PA','AP','PA'],
...         'acq': ['98','98','98','98','99','99','99','99'],
...         'subject': ['01','01','02','02','01','01','02','02' ]
...     },
...     {'acq': '98'}
... ) == {
...     'dir': ['AP', 'PA', 'AP', 'PA'],
...     'acq': ['98', '98', '98', '98'],
...     'subject': ['01', '01', '02', '02']
... }
True

Filtering to get all dir=='AP' scans:

>>> snakebids.filter_list(
...     {
...         'dir': ['AP','PA','AP','PA', 'AP','PA','AP','PA'],
...         'acq': ['98','98','98','98','99','99','99','99'],
...         'subject': ['01','01','02','02','01','01','02','02' ]
...     },
...     {'dir': 'AP'}
... ) == {
...     'dir': ['AP', 'AP', 'AP', 'AP'],
...     'acq': ['98', '98', '99', '99'],
...     'subject': ['01', '02', '01', '02']
... }
True

Filtering to get all subject='03' scans (i.e. no matches):

>>> snakebids.filter_list(
...     {
...         'dir': ['AP','PA','AP','PA', 'AP','PA','AP','PA'],
...         'acq': ['98','98','98','98','99','99','99','99'],
...         'subject': ['01','01','02','02','01','01','02','02' ]
...     },
...     {'subject': '03'}
... ) == {
...     'dir': [],
...     'acq': [],
...     'subject': []
... }
True

snakebids.generate_inputs(bids_dir, pybids_inputs, pybidsdb_dir=None, pybidsdb_reset=None, derivatives=False, pybids_config=None, limit_to=None, participant_label=None, exclude_participant_label=None, use_bids_inputs=None, validate=False, pybids_database_dir=None, pybids_reset_database=None)#

Dynamically generate snakemake inputs using pybids_inputs

Pybids is used to parse the bids_dir. Custom paths can also be parsed by including the custom_paths entry under the pybids_inputs descriptor.

Parameters:

bids_dir (Path | str) – Path to bids directory
pybids_inputs (snakebids.types.InputsConfig) –
Configuration for bids inputs, with keys as the names (str)

Nested dicts with the following required keys (for complete info, see InputConfig):
- "filters": Dictionary of entity: “values” (dict of str -> str or list of str). The entity keywords should the bids tags on which to filter. The values should be an acceptable str value for that entity, or a list of acceptable str values.
- "wildcards": List of (str) bids tags to include as wildcards in snakemake. At minimum this should usually include ['subject','session'], plus any other wildcards that you may want to make use of in your snakemake workflow, or want to retain in the output paths. Any wildcards in this list that are not in the filename will just be ignored.
- "custom_path": Custom path to be parsed with wildcards wrapped in braces, as in /path/to/sub-{subject}/{wildcard_1}-{wildcard_2}. This path will be parsed without pybids, allowing the use of non-bids-compliant paths.
pybidsdb_dir (Path | str | None) – Path to database directory. If None is provided, database is not used
pybidsdb_reset (bool | None) – A boolean that determines whether to reset / overwrite existing database.
derivatives (bool | Path | str) – Indicates whether pybids should look for derivative datasets under bids_dir. These datasets must be properly formatted according to bids specs to be recognized. Defaults to False.
limit_to (Iterable[str] | None) – If provided, indicates which input descriptors from pybids_inputs should be parsed. For example, if pybids_inputs describes "bold" and "dwi" inputs, and limit_to = ["bold"], only the “bold” inputs will be parsed. “dwi” will be ignored
participant_label (str | Iterable[str] | None) – Indicate one or more participants to be included from input parsing. This may cause errors if subject filters are also specified in pybids_inputs. It may not be specified if exclude_participant_label is specified
exclude_participant_label (str | Iterable[str] | None) – Indicate one or more participants to be excluded from input parsing. This may cause errors if subject filters are also specified in pybids_inputs. It may not be specified if participant_label is specified
use_bids_inputs (bool | None) – If False, returns the classic BidsDatasetDict instead of :class`BidsDataset`. Setting to True is deprecated as of v0.8, as this is now the default behaviour
validate (bool) – If True performs validation of BIDS directory using pybids, otherwise skips validation.
pybids_config (str | None) –
pybids_database_dir (Path | str | None) –
pybids_reset_database (bool | None) –

Returns:

Object containing organized information about the bids inputs for consumption in snakemake. See the documentation of BidsDataset for details and examples.

Return type:

BidsDataset | BidsDatasetDict

Example

As an example, consider the following BIDS dataset:

example
├── README.md
├── dataset_description.json
├── participant.tsv
├── sub-001
│   ├── ses-01
│   │   ├── anat
│   │   │   ├── sub-001_ses-01_run-01_T1w.json
│   │   │   ├── sub-001_ses-01_run-01_T1w.nii.gz
│   │   │   ├── sub-001_ses-01_run-02_T1w.json
│   │   │   └── sub-001_ses-01_run-02_T1w.nii.gz
│   │   └── func
│   │       ├── sub-001_ses-01_task-nback_bold.json
│   │       ├── sub-001_ses-01_task-nback_bold.nii.gz
│   │       ├── sub-001_ses-01_task-rest_bold.json
│   │       └── sub-001_ses-01_task-rest_bold.nii.gz
│   └── ses-02
│       ├── anat
│       │   ├── sub-001_ses-02_run-01_T1w.json
│       │   └── sub-001_ses-02_run-01_T1w.nii.gz
│       └── func
│           ├── sub-001_ses-02_task-nback_bold.json
│           ├── sub-001_ses-02_task-nback_bold.nii.gz
│           ├── sub-001_ses-02_task-rest_bold.json
│           └── sub-001_ses-02_task-rest_bold.nii.gz
└── sub-002
    ├── ses-01
    │   ├── anat
    │   │   ├── sub-002_ses-01_run-01_T1w.json
    │   │   ├── sub-002_ses-01_run-01_T1w.nii.gz
    │   │   ├── sub-002_ses-01_run-02_T1w.json
    │   │   └── sub-002_ses-01_run-02_T1w.nii.gz
    │   └── func
    │       ├── sub-002_ses-01_task-nback_bold.json
    │       ├── sub-002_ses-01_task-nback_bold.nii.gz
    │       ├── sub-002_ses-01_task-rest_bold.json
    │       └── sub-002_ses-01_task-rest_bold.nii.gz
    └── ses-02
        └── anat
            ├── sub-002_ses-02_run-01_T1w.json
            ├── sub-002_ses-02_run-01_T1w.nii.gz
            ├── sub-002_ses-02_run-02_T1w.json
            └── sub-002_ses-02_run-02_T1w.nii.gz

With the following pybids_inputs defined in the config file:

pybids_inputs:
  bold:
    filters:
      suffix: 'bold'
      extension: '.nii.gz'
      datatype: 'func'
    wildcards:
      - subject
      - session
      - acquisition
      - task
      - run

Then generate_inputs(bids_dir, pybids_input) would return the following values:

BidsDataset({
    "bold": BidsComponent(
        name="bold",
        path="bids/sub-{subject}/ses-{session}/func/sub-{subject}_ses-{session}_task-{task}_bold.nii.gz",
        zip_lists={
            "subject": ["001",   "001",  "001",   "001",  "002",   "002" ],
            "session": ["01",    "01",   "02",    "02",   "01",    "01"  ],
            "task":    ["nback", "rest", "nback", "rest", "nback", "rest"],
        },
    ),
    "t1w": BidsComponent(
        name="t1w",
        path="example/sub-{subject}/ses-{session}/anat/sub-{subject}_ses-{session}_run-{run}_T1w.nii.gz",
        zip_lists={
            "subject": ["001", "001", "001", "002", "002", "002", "002"],
            "session": ["01",  "01",  "02",  "01",  "01",  "02",  "02" ],
            "run":     ["01",  "02",  "01",  "01",  "02",  "01",  "02" ],
        },
    ),
})

snakebids.get_filtered_ziplist_index(zip_list, wildcards, subj_wildcards)#

Use this function when you have wildcards for a single scan instance, and want to know the index of that scan, amongst that subject’s scan instances.

Parameters:

zip_list (dict) – lists for scans in a dataset, zipped to get each instance
wildcards (dict) – wildcards for the single instance for querying it’s index
subj_wildcards (dict) – keys of this dictionary are used to pick out the subject/(session) from the wildcards

Return type:

int | list[int]

Examples

>>> import snakebids

In this example, we have a dataset where with scans from two subjects, where each subject has dir-AP and dir-PA scans, along with acq-98 and acq-99:

sub-01_acq-98_dir-AP_dwi.nii.gz
sub-01_acq-98_dir-PA_dwi.nii.gz
sub-01_acq-99_dir-AP_dwi.nii.gz
sub-01_acq-99_dir-PA_dwi.nii.gz
sub-02_acq-98_dir-AP_dwi.nii.gz
sub-02_acq-98_dir-PA_dwi.nii.gz
sub-02_acq-99_dir-AP_dwi.nii.gz
sub-02_acq-99_dir-PA_dwi.nii.gz

The zip_list produced by generate_inputs() is the set of entities that when zipped together, e.g. with expand(path, zip, **zip_list), produces the entity combinations that refer to each scan:

{
    'dir': ['AP','PA','AP','PA', 'AP','PA','AP','PA'],
    'acq': ['98','98','98','98','99','99','99','99'],
    'subject': ['01','01','02','02','01','01','02','02']
}

The filter_list() function produces a subset of the entity combinations as a filtered zip list. This is used e.g. to get all the scans for a single subject.

This get_filtered_ziplist_index() function performs filter_list() twice:

Using the subj_wildcards (e.g.: 'subject': '{subject}') to get a subject/session-specific zip_list.
To return the indices from that list of the matching wildcards.

In this example, if the wildcards parameter was:

{'dir': 'PA', 'acq': '99', 'subject': '01'}

Then the first (subject/session-specific) filtered list provides this zip list:

{
    'dir': ['AP','PA','AP','PA'],
    'acq': ['98','98','99','99'],
    'subject': ['01','01','01','01']
}

which has 4 combinations, and thus are indexed from 0 to 3.

The returned value would then be the index (or indices) that matches the wildcards. In this case, since the wildcards were {'dir': 'PA', 'acq': '99', 'subject':'01'}, the return index is 3.

>>> snakebids.get_filtered_ziplist_index(
...     {
...         'dir': ['AP','PA','AP','PA', 'AP','PA','AP','PA'],
...         'acq': ['98','98','98','98','99','99','99','99'],
...         'subject': ['01','01','02','02','01','01','02','02' ]
...     },
...     {'dir': 'PA', 'acq': '99', 'subject': '01'},
...     {'subject': '{subject}' }
... )
3

snakebids.get_wildcard_constraints(image_types)#

Return a wildcard_constraints dict for snakemake to use, containing all the wildcards that are in the dynamically grabbed inputs

Parameters:

image_types (dict) –

Returns:

Dict containing wildcard constraints for all wildcards in the
inputs, with typical bids naming constraints, ie letters and numbers
[a-zA-Z0-9]+.

Return type:

dict[str, str]

snakebids.write_derivative_json(snakemake, **kwargs)#

Snakemake function to read a json file, and write to a new one, adding BIDS derivatives fields for Sources and Parameters.

Parameters:

snakemake (struct Snakemake) – structure passed to snakemake python scripts, containing input, output, params, config … This function requires input.json and output.json to be defined, as it will read and write json files
kwargs (dict[str, Any]) –

Return type:

None

app#

Tools to generate a Snakemake-based BIDS app.

class snakebids.app.SnakeBidsApp(snakemake_dir, plugins=_Nothing.NOTHING, skip_parse_args=False, parser=_Nothing.NOTHING, configfile_path=_Nothing.NOTHING, snakefile_path=_Nothing.NOTHING, config=_Nothing.NOTHING, version=_Nothing.NOTHING, args=None)#

Snakebids app with config and arguments.

Parameters:

snakemake_dir (str | Path) – Root directory of the snakebids app, containing the config file and workflow files.
parser (argparse.ArgumentParser) – Parser including only the arguments specific to this Snakebids app, as specified in the config file. By default, it will use create_parser() from cli.py
configfile_path (pathlib.Path) – Relative path to config file (relative to snakemake_dir). By default, autocalculates based on snamake_dir
snakefile_path (pathlib.Path) –
Absolute path to the input Snakefile. By default, autocalculates based on snakemake_dir:
```
join(snakemake_dir, snakefile_path)
```
config (dict[str, Any]) – Contains all the configuration variables parsed from the config file and generated during the initialization of the SnakeBidsApp.
args (snakebids.cli.SnakebidsArgs | None) – Arguments to use when running the app. By default, generated using the parser attribute, autopopulated with args from config.py
plugins (list[Callable[[snakebids.app.SnakeBidsApp], None | snakebids.app.SnakeBidsApp]]) –
List of methods to be called after CLI parsing.

Each callable in plugins should take, as a single argument, a reference to the SnakeBidsApp. Plugins may perform any arbitrary side effects, including updates to the config dictionary, validation of inputs, optimization, or other enhancements to the snakebids app.

CLI parameters may be read from SnakeBidsApp.config. Plugins are responsible for documenting what properties they expect to find in the config.

Every plugin should return either:
- Nothing, in which case any changes to the SnakeBidsApp will persist in the workflow.
- A SnakeBidsApp, which will replace the existing instance, so this option should be used with care.
skip_parse_args (bool) –
version (str | None) –

run_snakemake()#

Run snakemake with the given config, after applying plugins

Return type:: None

create_descriptor(out_file)#

Generate a boutiques descriptor for this Snakebids app.

Parameters:: out_file (PathLike[str] | str) –
Return type:: None

snakebids.app.update_config(config, snakebids_args)#

Add snakebids arguments to config in-place.

Parameters:

config (dict[str, Any]) –
snakebids_args (SnakebidsArgs) –

Return type:

None