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