spectralbrain.utils.helpers#

Miscellaneous utilities: timing, reproducibility, I/O helpers.

Small tools used across SpectralBrain that don’t belong in any specific subpackage.

Functions

`collect_subjects`(bids_dir[, pattern])	List subject IDs in a BIDS directory.
`ensure_dir`(path)	Create directory if it doesn't exist.
`file_hash`(path[, algorithm])	Compute hash of a file.
`find_files`(directory[, pattern, recursive])	Glob for files in a directory.
`format_array_summary`(arr[, name])	One-line summary of an array.
`get_reproducibility_info`()	Collect version info for reproducibility metadata.
`parse_bids_filename`(filename)	Extract BIDS entities from a filename.
`print_dict`(d, *[, title, indent])	Pretty-print a dict with Rich (fallback to plain).
`seed_everything`([seed])	Set random seeds for NumPy, Python, and optional frameworks.
`timer`([label])	Context manager that logs elapsed time.

Classes

Timer()

Reusable timer with lap support.

class spectralbrain.utils.helpers.Timer[source]#

Bases: object

Reusable timer with lap support.

Examples

>>> t = Timer()
>>> t.start()
>>> process_a()
>>> t.lap("step A")
>>> process_b()
>>> t.lap("step B")
>>> t.report()

lap(label='')[source]#

Record a lap. Returns seconds since start.

Parameters:: label (str)
Return type:: float

report()[source]#

Return and log all laps.

Return type:: dict[str, float]

start()[source]#

Start the timer and return self.

Return type:: Timer

spectralbrain.utils.helpers.collect_subjects(bids_dir, pattern='sub-*')[source]#

List subject IDs in a BIDS directory.

Parameters:

bids_dir (PathLike)
pattern (str)

Returns:

list of str – Subject IDs (e.g. ["sub-01", "sub-02", ...]).

Return type:

list[str]

spectralbrain.utils.helpers.ensure_dir(path)[source]#

Create directory if it doesn’t exist. Returns the Path.

Parameters:: path (str | PathLike)
Return type:: Path

spectralbrain.utils.helpers.file_hash(path, algorithm='sha256')[source]#

Compute hash of a file.

Parameters:

path (PathLike)
algorithm (str) – "sha256", "md5", etc.

Returns:

str – Hex digest.

Return type:

str

spectralbrain.utils.helpers.find_files(directory, pattern='*', recursive=True)[source]#

Glob for files in a directory.

Parameters:

directory (PathLike)
pattern (str) – Glob pattern (e.g. "*.nii.gz").
recursive (bool)

Returns:

list of Path

Return type:

list[Path]

spectralbrain.utils.helpers.format_array_summary(arr, name='array')[source]#

One-line summary of an array.

Parameters:

arr (ndarray)
name (str)

Return type:

str

spectralbrain.utils.helpers.get_reproducibility_info()[source]#

Collect version info for reproducibility metadata.

Returns:: dict – Keys: python, numpy, scipy, spectralbrain, platform, date.
Return type:: dict[str, str]

spectralbrain.utils.helpers.parse_bids_filename(filename)[source]#

Extract BIDS entities from a filename.

Parameters:: filename (str) – E.g. "sub-01_ses-pre_T1w.nii.gz".
Returns:: dict – E.g. {"sub": "01", "ses": "pre", "suffix": "T1w"}.
Return type:: dict[str, str]

spectralbrain.utils.helpers.print_dict(d, *, title=None, indent=2)[source]#

Pretty-print a dict with Rich (fallback to plain).

Parameters:

d (dict[str, Any])
title (str | None)
indent (int)

Return type:

None

spectralbrain.utils.helpers.seed_everything(seed=42)[source]#

Set random seeds for NumPy, Python, and optional frameworks.

Parameters:: seed (int)
Return type:: None

spectralbrain.utils.helpers.timer(label='Operation')[source]#

Context manager that logs elapsed time.

Parameters:: label (str) – Description for the log message.
Return type:: Generator[None, None, None]

Examples

>>> with timer("Eigendecomposition"):
...     decomp = mesh.decompose(k=100)
# [HH:MM:SS] INFO  Eigendecomposition: 12.34s