Internals#

Note

These types are mostly used internally. The API most users will need is documented in the main API page, but these are listed here for reference (and some of the main API items link here).

utils#

class snakebids.utils.utils.BidsTag#
snakebids.utils.utils.DEPRECATION_FLAG = '<!DEPRECATED!>'#

Sentinel string to mark deprecated config features

snakebids.utils.utils.read_bids_tags(bids_json=None)#

Read the bids tags we are aware of from a JSON file.

This is used specifically for compatibility with pybids, since some tag keys are different from how they appear in the file name, e.g. subject for sub, and acquisition for acq.

Parameters:

bids_json (Path | None) – Path to JSON file to use, if not specified will use bids_tags.json in the snakebids module.

Returns:

Dictionary of bids tags

Return type:

dict

class snakebids.utils.utils.BidsEntity(entity)#

Bids entities with tag and wildcard representations

Parameters:

entity (str) –

property tag: str#

Get the bids tag version of the entity

For entities in the bids spec, the tag is the short version of the entity name. Otherwise, the tag is equal to the entity.

property match: str#

Get regex of acceptable value matches

If no pattern is associated with the entity, the default pattern is a word with letters and numbers

property before: str#

regex str to search before value in paths

property after: str#

regex str to search after value in paths

property regex: Pattern[str]#

Complete pattern to match when searching in paths

Contains three capture groups, the first corresponding to “before”, the second to “value”, and the third to “after”

property wildcard: str#

Get the snakebids {wildcard}

The wildcard is generally equal to the tag, i.e. the short version of the entity name, except for subject and session, which use the full name name. This is to ensure compatibility with the bids function

classmethod from_tag(tag)#

Return the entity associated with the given tag, if found

If not associated entity is found, the tag itself is used as the entity name

Parameters:

tag (str) – tag to search

Return type:

BidsEntity

classmethod normalize(item, /)#

Return the entity associated with the given item, if found

Supports both strings and BidsEntities as input. Unlike the constructor, if a tag name is given, the associated entity will be returned. If no associated entity is found, the tag itself is used as the entity name

Parameters:
Return type:

BidsEntity

exception snakebids.utils.utils.BidsParseError(path, entity)#

Exception raised for errors encountered in the parsing of Bids paths

Parameters:
Return type:

None

snakebids.utils.utils.property_alias(prop, label=None, ref=None, copy_extended_docstring=False)#

Set property as an alias for another property

Copies the docstring from the aliased property to the alias

Parameters:

  • prop (property) – Property to alias

  • label (str | None) – Text to use in link to aliased property

  • ref (str | None) – Name of the property to alias

  • copy_extended_docstring (bool) – If True, copies over the entire docstring, in addition to the summary line

Return type:

property

snakebids.utils.utils.surround(s, object_, /)#

Surround a string or each string in an iterable with characters

Parameters:
Return type:

Iterable[str]

class snakebids.utils.utils.MultiSelectDict#

Dict supporting selection of multiple keys using tuples

If a single key is given, the item associated with that key is returned just as in a regular dict. If multiple, comma-seperated keys are given, (e.g. a tuple), a new MultiSelectDict will be returned containing the keys given and their values:

>>> mydict = MultiSelectDict({
...     "foo": "bar",
...     "hello": "world",
...     "fee": "fie",
... })
>>> mydict["foo"]
'bar'
>>> mydict["foo", "hello"]
{'foo': 'bar', 'hello': 'world'}

The new MultiSelectDict is a “view” of the original data. Any mutations made to the values will be reflected in the original object:

>>> mydict = MultiSelectDict({
...     "foo": [1, 2, 3, 4],
...     "hello": "world",
...     "fee": "fie",
... })
>>> view = mydict["foo", "hello"]
>>> view["foo"].append(5)
>>> mydict
{'foo': [1, 2, 3, 4, 5], 'hello': 'world', 'fee': 'fie'}

The keys of the new MultiSelectDict will be inserted in the order provided in the selector

>>> mydict = MultiSelectDict({
...     "foo": "bar",
...     "hello": "world",
...     "fee": "fie",
... })
>>> mydict["hello", "foo"]
{'hello': 'world', 'foo': 'bar'}

Tuples of length 1 will still return a MultiSelectDict:

>>> mydict = MultiSelectDict({
...     "foo": [1, 2, 3, 4],
...     "hello": "world",
...     "fee": "fie",
... })
>>> mydict["foo",]
{'foo': [1, 2, 3, 4]}

If a key is given multiple times, the extra instances of the key will be ignored:

>>> mydict = MultiSelectDict({
...     "foo": [1, 2, 3, 4],
...     "hello": "world",
...     "fee": "fie",
... })
>>> mydict["foo", "foo", "foo"]
{'foo': [1, 2, 3, 4]}
snakebids.utils.utils.zip_list_eq(first, second, /)#

Compare two zip lists, allowing the order of columns to be irrelevant

Parameters:
snakebids.utils.utils.get_first_dir(path)#

Return the top level directory in a path

If absolute, return the root. This function is necessary to handle paths with ./, as pathlib.Path filters this out.

Parameters:

path (str) –

Return type:

str

class snakebids.utils.utils.ImmutableList(iterable=(), /)#

Subclassable tuple equivalent

Mimics a tuple in every way, but readily supports subclassing. Data is stored on a private attribute _data. Subclasses must not override this attribute. To avoid accidental modification, subclasses should avoid interacting with _data, using the relevant super() calls to access internal data instead (e.g. use super().__getitem__(index) rather than self._data[index]).

Unlike tuples, only a single type parameter is supported. In other words, ImmutableList cannot be specified via type hints as a fixed length sequence containing heterogenous items. A tuple specified as tuple[str, int, str] would be specified as ImmutableList[str | int]

Parameters:

iterable (Iterable[_T_co]) –

count(value) → integer -- return number of occurrences of value#
Parameters:

value (Any) –

Return type:

int

index(value[, start[, stop]]) → integer -- return first index of value.#

Raises ValueError if the value is not present.

Supporting start and stop arguments is optional, but recommended.

Parameters:
Return type:

int

snakebids.utils.utils.get_wildcard_dict(entities, /)#

Turn entity strings into wildcard dicts as {“entity”: “{entity}”}

Parameters:

entities (str | Iterable[str]) –

Return type:

dict[str, str]

class snakebids.utils.utils.RegexContainer(template)#

Container that tests if a string matches a regex using the in operator

Constructed with a regex expression. Supports inclusion tests for strings using in. Strings matching the regex (using re.match) will return True

Parameters:

template (AnyStr | re.Pattern[AnyStr]) –

class snakebids.utils.utils.ContainerBag(*entries)#

Container to hold other containers

Useful because list(Container) isn’t guaranteed to work, so this lets us merge Containers in a type safe way.

Parameters:

entries (Container[_T]) –

snakemake_io#

File globbing functions based on snakemake.io library

snakebids.utils.snakemake_io.regex(filepattern)#

Build Snakebids regex based on the given file pattern.

Parameters:

filepattern (str) –

Return type:

str

snakebids.utils.snakemake_io.glob_wildcards(pattern, files=None, followlinks=False)#

Glob the values of wildcards by matching a pattern to the filesystem.

Returns a zip_list of field names with matched wildcard values.

Parameters:

  • pattern (str | Path) – Path including wildcards to glob on the filesystem.

  • files (Sequence[str | Path] | None) – Files from which to glob wildcards. If None (default), the directory corresponding to the first wildcard in the pattern is walked, and wildcards are globbed from all files.

  • followlinks (bool) – Whether to follow links when globbing wildcards.

Return type:

snakebids.types.ZipList

snakebids.utils.snakemake_io.update_wildcard_constraints(pattern, wildcard_constraints, global_wildcard_constraints)#

Update wildcard constraints.

Parameters:

  • pattern (str) – Pattern on which to update constraints.

  • wildcard_constraints (dict) – Dictionary of wildcard:constraint key-value pairs.

  • global_wildcard_constraints (dict) – Dictionary of wildcard:constraint key-value pairs.

Return type:

str

cli#

class snakebids.cli.FilterParse(option_strings, dest, nargs=None, const=None, default=None, type=None, choices=None, required=False, help=None, metavar=None)#

Class for parsing CLI filters in argparse

class snakebids.cli.SnakemakeHelpAction(option_strings, dest, nargs=None, const=None, default=None, type=None, choices=None, required=False, help=None, metavar=None)#

Class for printing snakemake usage in argparse

class snakebids.cli.SnakebidsArgs(force, outputdir, snakemake_args, args_dict, pybidsdb_dir=None, pybidsdb_reset=False)#

Arguments for Snakebids App

Organizes the various options available for a generic Snakebids App, and store project specific arguments in a dict. Snakemake args are to be put in a list

Parameters:
force#

Force output in a directory that already has contents

Type:

bool

outputdir#

Directory to place outputs

Type:

Path

pybidsdb_dir#

Directory to place pybids database

Type:

Path

snakemake_args#

Arguments to pass on to Snakemake

Type:

list of strings

args_dict#

Contains all the snakebids specific args. Meant to contain custom user args defined in config, as well as dynamic –filter-xx and –wildcard-xx args. These will eventually be printed in the new config.

Type:

dict[str, Any]

snakebids.cli.create_parser(include_snakemake=False)#

Generate basic Snakebids Parser

Includes the standard Snakebids arguments.

Parameters:

include_snakemake (bool) –

Return type:

ArgumentParser

exceptions#

exception snakebids.exceptions.ConfigError(msg)#

Exception raised for errors with the Snakebids config.

Parameters:

msg (str) –

Return type:

None

exception snakebids.exceptions.RunError(msg, *args)#

Exception raised for errors in generating and running the snakemake workflow.

Parameters:
Return type:

None

exception snakebids.exceptions.PybidsError#

Exception raised when pybids encounters a problem.

exception snakebids.exceptions.DuplicateComponentError(duplicated_names)#

Raised when a dataset is constructed from components with the same name.

Parameters:

duplicated_names (Iterable[str]) –

exception snakebids.exceptions.MisspecifiedCliFilterError(misspecified_filter)#

Raised when a magic CLI filter cannot be parsed.

Parameters:

misspecified_filter (str) –

exception snakebids.exceptions.SnakebidsPluginError#

Exception raised when a Snakebids plugin encounters a problem

types#

class snakebids.types.InputConfig#

Configuration for a single bids component

filters: dict[str, str | bool | list[str | bool]]#

Filters to pass on to BIDSLayout.get()

Each key refers to the name of an entity. Values may take the following forms:

  • string: Restricts the entity to the exact string given

  • bool: True requires the entity to be present (with any value). False requires the entity to be absent.

  • list [str]: List of allowable values the entity may take.

In addition, a few special filters may be added which carry different meanings:

  • use_regex: True: If present, all strings will be interpreted as regex

  • scope: Restricts the scope of the component. It may take the following values:

    • "all": search everything (default behaviour)

    • "raw": only search the top-level raw dataset

    • "derivatives": only search derivative datasets

    • <PipelineName>: only search derivative datasets with a matching pipeline

      name

wildcards: list[str]#

Wildcards to allow in the component.

Each value in the list refers to the name of an entity. If the entity is present, the generated BidsComponent will have values of this entity substituted for wildcards in the path, and the entity will be included in the zip_lists.

If the entity is not found, it will be ignored.

class snakebids.types.BinaryOperator(*args, **kwargs)#
class snakebids.types.Expandable(*args, **kwargs)#

Protocol represents objects that hold an entity table and can expand over a path

Includes BidsComponent, BidsPartialComponent, and BidsComponentRow

class snakebids.types.MultiSelectable(*args, **kwargs)#
class snakebids.types.UserDictPy38#
class snakebids.types.OptionalFilterType(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)#

Sentinel value for CLI OPTIONAL filtering.

This is necessary because None means no CLI filter was added.

snakebids.types.InputsConfig: TypeAlias = 'dict[str, InputConfig]'

Configuration for all bids components to be parsed in the app

Should be defined in the config.yaml file, by convention in a key called ‘pybids_inputs’

snakebids.types.ZipList: TypeAlias = 'utils.MultiSelectDict[str, list[str]]'

Multiselectable dict mapping entity names to possible values.

All lists must be the same length. Entries in each list with the same index correspond to the same path. Thus, the ZipList can be read like a table, where each row corresponds to an entity, and each “column” corresponds to a path.

snakebids.types.ZipListLike

Generic form of a ZipList

Useful for typing functions that won’t mutate the ZipList or use MultiSelectDict capabilities. Like ZipList, each Sequence must be the same length, and values in each with the same index must correspond to the same path.

alias of Mapping[str, Sequence[str]]

class snakebids.types.ZipList#
class snakebids.types.InputsConfig#
class snakebids.types.ZipListLike#