API

class ancpbids.DatasetOptions(infer_artifact_datatype: bool = False, ignore: bool | List[str] = False)

All options that can be set to influence handling of reading/writing a dataset from/to file system.

ignore: bool | List[str] = False

If a .bidsignore file is available at the root, all resources (files/folders) matching the filters in that file will not be added to the in-memory graph. Alternatively, a list of fnmatch patterns can be provided.

By default, this option is set to False as it may have a negative performance impact.

infer_artifact_datatype: bool = False

If True, will determine the datatype an Artifact is contained in, either directly or within a sub-directory. For example, given the path “sub-02/func/sub-02_task-mixedgamblestask_run-01_bold.nii.gz”, the datatype will be “func”.

By default, this option is set to False as it may have a negative performance impact.

ancpbids.load_dataset(base_dir: str, options: DatasetOptions | None = None)

Loads a dataset given its directory path on the file system.

from ancpbids import load_dataset, validate_dataset
dataset_path = 'path/to/your/dataset'
dataset = load_dataset(dataset_path, DatasetOptions(ignore=False, infer_artifact_datatype=True))
Parameters:
  • base_dir – the dataset path to load from

  • options – the options to use, see DatasetOptions class for available options

Returns:

a Dataset object depending on the used schema which represents the dataset as an in-memory graph

Return type:

str

ancpbids.load_schema(base_dir)

Loads a BIDS schema object which represents the static/formal definition of the BIDS specification.

As per BIDS spec, a BIDS compliant dataset must have a BIDSVersion field in the dataset_description.json file at the top level. This field is used to determine which BIDS schema to load.

In case the BIDSVersion field is missing or not supported, the earliest supported schema will be returned.

Parameters:

base_dir – The dataset directory path where a dataset_description.json must be located.

Returns:

A BIDS schema object which represents the static/formal definition of the BIDS specification.

Return type:

object

ancpbids.save_dataset(ds: object, target_dir: str, context_folder=None)

Copies the dataset graph into the provided target directory.

EXPERIMENTAL/UNSTABLE

Parameters:
  • ds – the dataset graph to save

  • target_dir – the target directory to save to

  • context_folder – a folder node within the dataset graph to limit to

ancpbids.validate_dataset(dataset) ValidationReport

Validates a dataset and returns a report object containing any detected validation errors.

Example:

report = validate_dataset(dataset)
for message in report.messages:
    print(message)
if report.has_errors():
    raise "The dataset contains validation errors, cannot continue".
Parameters:

dataset – the dataset to validate

Returns:

a report object containing any detected validation errors or warning

Return type:

ValidationPlugin.ValidationReport

ancpbids.write_derivative(ds, derivative)

Writes the provided derivative folder to the dataset. Note that a ‘derivatives’ folder will be created if not present.

Parameters:
  • ds – the dataset object to extend

  • derivative – the derivative folder to write

ancpbids.utils.deepupdate(target, src)

Deep update target dict with src For each k,v in src: if k doesn’t exist in target, it is deep copied from src to target. Otherwise, if v is a list, target[k] is extended with src[k]. If v is a set, target[k] is updated with v, If v is a dict, recursively deep-update it.

Examples: >>> t = {‘name’: ‘Ferry’, ‘hobbies’: [‘programming’, ‘sci-fi’]} >>> deepupdate(t, {‘hobbies’: [‘gaming’]}) >>> print t {‘name’: ‘Ferry’, ‘hobbies’: [‘programming’, ‘sci-fi’, ‘gaming’]}

Copyright Ferry Boender, released under the MIT license.

ancpbids.utils.fetch_dataset(dataset_id: str, output_dir='~/.ancp-bids/datasets')

Downloads and extracts an ancpBIDS test dataset from Github.

Parameters:
  • dataset_id – The dataset ID of the ancp-bids-datasets github repository. See https://github.com/ANCPLabOldenburg/ancp-bids-dataset for more details.

  • output_dir – The output directory to download and extract the dataset to. Default is to write to user’s home directory at ~/.ancp-bids/datasets

Returns:

Return type:

The path of the extracted dataset.

ancpbids.utils.load_contents(file_path, return_type: str | None = None)

Loads the contents of the provided file path.

Parameters:
  • file_path – the file path to load contents from

  • return_type – A hint to consider when deciding how to load the contents of the provided file. For example, to load a TSV file as a pandas DataFrame the return_type should be ‘dataframe’, to load a numpy ndarray, the return_type should be ‘ndarray’. It is up to the registered file handlers to correctly interpret the return_type.

Returns:

  • The result depends on the extension of the file name.

  • For example, a .json file may be returned as an ordinary Python dict or a .txt as a str value.

ancpbids.utils.parse_bids_name(name: str)

Parses a given string (file name) according to the BIDS naming scheme.

Parameters:

name – The file name to parse. If a full path (with path separaters), the path segments will be ignored.

Returns:

A dictionary describing the BIDS naming components.

Return type:

dict

Examples

>>> bids_obj = parse_bids_name("sub-11_task-mixedgamblestask_run-02_bold.nii.gz")
{'entities': {'sub': '11', 'task': 'mixedgamblestask', 'run': '02'}, 'suffix': 'bold', 'extension': '.nii.gz'}
ancpbids.utils.write_contents(file_path: str, contents)

Writes the provided contents to the target file path using a registered file writer.

A valid file writer may be inferred by the file’s extension and/or the given contents object. If no file writer is found for the given file, a ValueError is raised.

Parameters:
  • file_path – The file path to write to.

  • contents – The contents to write to the target file.

class ancpbids.plugin.DatasetPlugin(**props)

A dataset plugin may enhance an in-memory graph of a dataset.

class ancpbids.plugin.FileHandlerPlugin(**props)

A file handler plugin may register a reader or writer function to allow handling unknown file extensions.

class ancpbids.plugin.Plugin(**props)

Base class of all plugins.

class ancpbids.plugin.SchemaPlugin(**props)

A schema plugin may extend/modify a BIDS schema representation module. For example, to monkey-patch generated classes.

class ancpbids.plugin.ValidationPlugin(**props)

A validation plugin may extend the rules to validate a dataset against.

class ValidationReport

Contains validation messages (errors/warnings) after a dataset has been validated.

error(message, offender=None)

Adds a new error message to the report.

Parameters:

message – the error message to add to the report

has_errors()
Returns:

whether this report contains errors

Return type:

bool

warn(message, offender=None)

Adds a new warning message to the report.

Parameters:

message – the warning message to add to the report

class ancpbids.plugin.WritingPlugin(**props)

A writing plugin may write additional files/folders when a dataset is stored back to file system. This may be most interesting to write derivatives to a dataset.

ancpbids.plugin.get_plugins(plugin_class, **props) List[Plugin]

Returns a list of plugin instances matching the provided plugin class and properties.

Parameters:
  • plugin_class – the plugin class to filter by

  • props – additional filters found in any attached plugin properties

Returns:

Return type:

a list of plugin instances matching the provided plugin class and properties

ancpbids.plugin.is_valid_plugin(plugin_class)
Parameters:

plugin_class – the class to check if known to be a valid plugin class

Returns:

whether the class is considered a valid plugin class

Return type:

bool

ancpbids.plugin.load_plugins_by_package(ns_pkg, ranking: int = 1000, **props)

Loads all valid plugin classes by the provided package.

Parameters:
  • ns_pkg – the package to scan for plugin classes

  • ranking – the ranking to use for any detected plugin class

  • props – the properties to assign to the detected plugin classes

Returns:

a list of plugin classes or empty if no valid plugin classes found

Return type:

list

ancpbids.plugin.register_plugin(plugin_class, ranking: int = 1000, **props)

Registers the provided plugin class. If the class is not considered a valid plugin class a ValueError is raised.

Parameters:
  • plugin_class – The plugin class to register.

  • ranking – The rank to use for the plugin to help prioritize plugins of same type. Note that the lower the ranking the higher its prioritization in the processing. System level plugins are registered with ranking = 0, i.e. if you need your plugin to be prioritized over system plugins, use a ranking below 0.

  • props – Additional (static) properties to attach to the provided plugin class.