API

class ancpbids.BIDSLayout(ds_dir: str, **kwargs)

A convenience class to provide access to an in-memory representation of a BIDS dataset.

dataset_path = 'path/to/your/dataset'
layout = BIDSLayout(dataset_path)
Parameters

ds_dir – the (absolute) path to the dataset to load

get_<entity>()

It is possible to get a unique set of values for each of the available BIDS entities.

Examples:

all_task_labels = layout.get_tasks()
all_subject_labels = layout.get_subjects(task='lang')
all_bold_session_labels = layout.get_sessions(suffix='bold')

See EntityEnum for supported entities.

get(return_type: str = 'object', target: Optional[str] = None, scope: Optional[str] = None, extension: Optional[Union[str, List[str]]] = None, suffix: Optional[Union[str, List[str]]] = None, **entities) Union[List[str], List[object]]

Depending on the return_type value returns either paths to files that matched the filtering criteria or Artifact objects for further processing by the caller.

Note that all provided filter criteria are AND combined, i.e. subj=’02’,task=’lang’ will match files containing ‘02’ as a subject AND ‘lang’ as a task. If you provide a list of values for a criteria, they will be OR combined.

file_paths = layout.get(subj='02', task='lang', suffix='bold', return_type='files')

file_paths = layout.get(subj=['02', '03'], task='lang', return_type='files')
Parameters
  • return_type – Either ‘files’ to return paths of matched files or ‘object’ to return Artifact object, defaults to ‘object’

  • target – Either suffixes, extensions or one of any valid BIDS entities key (see EntityEnum, defaults to None

  • scope – a hint where to search for files If passed, only nodes/directories that match the specified scope will be searched. Possible values include: ‘all’ (default): search all available directories. ‘derivatives’: search all derivatives directories. ‘raw’: search only BIDS-Raw directories. ‘self’: search only the directly called BIDSLayout. <PipelineName>: the name of a BIDS-Derivatives pipeline.

  • extension – criterion to match any files containing the provided extension only

  • suffix – criterion to match any files containing the provided suffix only

  • entities – a list of key-values to match the entities of interest, example: subj=’02’,task=’lang’

Returns

  • depending on the return_type value either paths to files that matched the filtering criteria

  • or Artifact objects for further processing by the caller

get_dataset() object
Returns

Return type

the in-memory representation of this layout/dataset

get_dataset_description(scope='self', all_=False) Union[List[Dict], Dict]

Return contents of dataset_description.json.

Parameters
  • scope (str) – The scope of the search space. Only descriptions of BIDSLayouts that match the specified scope will be returned. See bids.layout.BIDSLayout.get docstring for valid values. Defaults to ‘self’ –i.e., returns the dataset_description.json file for only the directly-called BIDSLayout.

  • all (bool) – If True, returns a list containing descriptions for all matching layouts. If False (default), returns for only the first matching layout.

Returns

a dictionary or list of dictionaries (depending on all_).

Return type

dict or list of dict

get_entities(scope: Optional[str] = None, sort: bool = False) dict

Returns a unique set of entities found within the dataset as a dict. Each key of the resulting dict contains a list of values (with at least one element).

Example dict: .. code-block:

{
    'sub': ['01', '02', '03'],
    'task': ['gamblestask']
}
Parameters
  • scope – see BIDSLayout.get()

  • sort (default is False) – whether to sort the keys by name

Returns

a unique set of entities found within the dataset as a dict

Return type

dict

get_file(filename, scope='all')

Return the BIDSFile object with the specified path.

Parameters
  • filename (str) – The path of the file to retrieve. Must be either an absolute path, or relative to the root of this BIDSLayout.

  • scope (str or list, optional) – Scope of the search space. If passed, only BIDSLayouts that match the specified scope will be searched. See BIDSLayout.get docstring for valid values. Default is ‘all’.

Returns

File found, or None if no match was found.

Return type

bids.layout.BIDSFile or None

get_files(scope='all')

Get BIDSFiles for all layouts in the specified scope.

Parameters

scope (str) – The scope of the search space. Indicates which BIDSLayouts’ entities to extract. See bids.layout.BIDSLayout.get docstring for valid values.

Returns

A dict, where keys are file paths and values are bids.layout.BIDSFile instances.

get_metadata(path, include_entities=False, scope='all')

Return metadata found in JSON sidecars for the specified file.

Parameters
  • path (str) – Path to the file to get metadata for.

  • include_entities (bool, optional) – If True, all available entities extracted from the filename (rather than JSON sidecars) are included in the returned metadata dictionary.

  • scope (str or list, optional) – The scope of the search space. Each element must be one of ‘all’, ‘raw’, ‘self’, ‘derivatives’, or a BIDS-Derivatives pipeline name. Defaults to searching all available datasets.

Returns

A dictionary of key/value pairs extracted from all of the target file’s associated JSON sidecars.

Return type

dict

Notes

A dictionary containing metadata extracted from all matching .json files is returned. In cases where the same key is found in multiple files, the values in files closer to the input filename will take precedence, per the inheritance rules in the BIDS specification.

validate() ValidationReport

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

Example

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

Return type

a report object containing any detected validation errors or warning

write_derivative(derivative)

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

Parameters

derivative – the derivative folder to write

ancpbids.load_dataset(base_dir: str)

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)
Parameters

base_dir – the dataset path to load from

Returns

an object instance of type ancpbids.model.Dataset 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: Optional[str] = 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.