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

Interface for BidsTag configuration.

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

property type: str | None

Get the type of the entity.

Returns None if type unspecified.

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:

item (str | BidsEntity) – tag to search

Return type:

BidsEntity

snakebids.utils.utils.matches_any(item, match_list, match_func, *args)

Test if item matches any of the items in match_list.

Parameters:

  • item (_T) – Item to test

  • match_list (Iterable[_T]) – Items to compare with

  • match_func (BinaryOperator[_T, object]) – Function to test equality. Defaults to basic equality (==) check

  • args (Any) –

Return type:

bool

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]

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

snakebids.utils.utils.to_resolved_path(path)

Convert provided object into resolved path.

Parameters:

path (str | PathLike[str]) –

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]

snakebids.utils.utils.entity_to_wildcard(entities, /)

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

Parameters:

entities (str | Iterable[str]) –

snakebids.utils.utils.text_fold(text)

Fold a block of text into a single line as in yaml folded multiline string.

Parameters:

text (str) –

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

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

Exception raised when a Snakebids plugin encounters a problem.

types

class snakebids.types.FilterSpec

Optional filter specification allowing regex matching.

class snakebids.types.InputConfig

Configuration for a single bids component.

filters: Mapping[str, str | bool | Sequence[str | bool] | FilterSpec]

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)

Callables that act on two objects of identical type.

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)

Mappings supporting selection with multiple keys.

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

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’

alias of Dict[str, InputConfig]

snakebids.types.ZipList

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.

alias of MultiSelectDict[str, List[str]]

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