Note

This page is a reference documentation. It only explains the class signature, and not how to use it. Please refer to the user guide for the big picture.

brainprep.decorators.BidsHook

class brainprep.decorators.BidsHook(process=None, bids_file=None, container=None, add_subjects=False, longitudinal=False)

Bases: Hook

BIDS specification.

This hook performs three main tasks:

1. Compute a BIDS-compliant output directory path based on the input BIDS file(s) and inject it into the function inputs.

2. Ensure BIDS-compliant metadata is written to the output directory.

3. Inject the entities parameter into the function when a bids_file argument is provided.

Parameters:

processstr | None

Name of the processing pipeline (e.g., ‘fmriprep’, ‘custom’). Default None.

bids_filestr | None

Name of the argument in the function that contains the BIDS file path. or iterable of file path. Default None.

containerstr | None

The name of the container (e.g., Docker image) used to run the pipeline. Default None.

add_subjectsbool

If True, add a ‘subjects’ upper level directory in the output directory, for instance to regroup subject level data. Default False.

longitudinalbool

If True, add a ‘longitudinal’ upper level directory in the output directory. Default False.

Examples

>>> from typing import Any
>>> from brainprep.decorators import step, BidsHook, CoerceparamsHook
>>> from brainprep.typing import File, Directory
>>> from brainprep.utils import Bunch

>>> @step(
...     hooks=[
...         CoerceparamsHook(),
...         BidsHook(
...             process="test",
...             bids_file="t1_file",
...             add_subjects=True,
...         ),
...     ]
... )
... def myfunc(t1_file: File, output_dir: Directory, **kwargs: Any):
...     '''BIDS specification.'''
...     entities = kwargs.get("entities", {})
...     return Bunch(
...         t1_file=t1_file,
...         output_dir=output_dir,
...         entities=entities,
...     )

>>> result = myfunc(
...     "/tmp/rawdata/sub-00/anat/sub-00_run-00_T1w.nii.gz",
...     "/tmp/derivatives",
... )
>>> print(result)
Bunch(
  t1_file: PosixPath('/tmp/rawdata/sub-00/anat/sub-00_run-00_T1w.nii.gz')
  output_dir: PosixPath('...derivatives/test/subjects/sub-00/ses-01')
  entities: {'sub': '00', 'run': '00', ...}
)

__init__(process=None, bids_file=None, container=None, add_subjects=False, longitudinal=False)

before_call(func, inputs)

Transform and inspect inputs before the function call.

Parameters:

funcCallable

The function to be decorated.

inputsdict[str, Any]

Positional and keyword arguments passed to func.

Returns:

inputsdict[str, Any]

Positional and keyword arguments passed to func with adjusted ‘output_dir’ injected.

Raises:

ValueError

If the decorated function has no bids_file or output_dir arguments. If kwargs argument is not a dict.