clinicaio.directory

Path functions and classes.

Attributes

LOGGER

Classes

_BIDSDirectoryMetaclass	Metaclass for BIDSDirectory that automatically defines methods in subclasses
BIDSDirectory	A directory in a BIDS dataset.

Module Contents

clinicaio.directory.LOGGER

class clinicaio.directory._BIDSDirectoryMetaclass

Bases: type

Metaclass for BIDSDirectory that automatically defines methods in subclasses based on configured subdirectory types for different entities.

class clinicaio.directory.BIDSDirectory

Bases: clinicaio.path.BIDSPath

A directory in a BIDS dataset.

Attributes:

SUBDIRECTORY_TYPES_BY_ENTITY:

An optional dict mapping entity types to subclasses of BIDSPath or BIDSDirectory. This can be used conveniently convert child nodes of a directory to custom subclasses by entity. For example, the BIDSDataset class can automatically convert its child subjects to instances of the class BIDSSubject.

SUBCLASSES_BY_SUFFIX:

Similar to SUBCLASSES_BY_ENTITY, this is an optional dict mapping suffixes to subclasses of BIDSPath or BIDSDirectory. Currently SUBCLASSES_BY_ENTITY will take precedence but this behavior may be configured by overriding the maybe_convert_child method.

SUBCLASSES_BY_ENTITY

SUBCLASSES_BY_SUFFIX

maybe_convert_child(bids_path: clinicaio.path.BIDSPath)

Optionally convert a child BIDSPath instance to a different BIDSPath type. This function is invoked by the __div__ operator and can be overridden in subclasses to customize child paths by e.g. entity.

When cnoverting types, it is recommended to invoke the from_bids_path() method of the target class with the given bids_path argument.

Args:

bids_path:

The child BIDSPath instance.

Returns:

A child BIDSPath instance.

get_child_paths(include_files: bool = True, include_dirs: bool = True)

Get an iterator over file paths in this directory.

Args:

include_files:

Include file (i.e. non-directory) paths.

include_dirs:

Include directory paths.

Returns:

The iterator over Path instances of the selected paths.

get_child_bids_paths(**kwargs)

An iterable of BIDSPath instances of paths in this directory.

Args:

**kwargs:

Keyword arguments passed through to get_paths.

Returns:

An iterator over BIDSPath instances.

property child_entities

The set of entities found in this directory’s child node filepaths.

get_children_by_entity(entity: clinicaio.entities.EntityArg, value: clinicaio.entities.EntityValue = None, include: bool = True, **kwargs)

Get an iterator over BIDS paths in this directory that match the target entity.

Args:

entity:

The target entity.

value:

An optional entity value to match. If none, all paths with the given entity are matched.

include:

If True, return paths that match, else return paths that don’t match.

**kwargs:

Keyword arguments passed through to get_bids_paths.

Returns:

A generator over instances of BIDSPath for each matching path.

TODO:

Maybe generalize this function to support multiple entities.

get_child_mapping_by_entity(entity: clinicaio.entities.EntityArg, *args, **kwargs)

Get a dict mapping entity values to children of this directory containing that entity as instances of BIDSPath or a subclass thereof.

Args:

entity:

The target entity.

*args:

Additional ositional arguments passed through to get_children_by_entity.

**kwargs:

Keyword arguments passed through to get_children_by_entity.

Returns:

A dict mapping entity values to instances of the class passed through to get_children_by_entity.

recurse_directory(filter_func: Callable[[clinicaio.path.BIDSPath | BIDSDirectory], bool] | None = None)

Recurse paths within this directory.

Args:

filter_func:

A optional function that accepts a BIDSPath argument and returns a boolean to indicate if the path should be included in the results (True) or not (False).

Returns:

A generator over all directories and files in this directory, as instances of BIDSDirectory and BIDSPath, respectively, or subclasses thereof.

check()

Check for errors in this path. Override this in subclasses to add specific logic for that subclass, such as checking entity values in names or that required files exist in a directory. The method should raise BIDSPathError or a subclass thereof if the check fails.

classmethod add_custom_subclass_methods()

Add custom caching accessors for the entity subdirectories specified in SUBDIRECTORY_TYPES_BY_ENTITY.