Utilities

Helper functions used across OncoPrep.

Logging

get_logger

BIDS helpers

Utilities to handle BIDS inputs.

oncoprep.utils.bids.collect_derivatives(derivatives_dir: str, subject_id: str, std_spaces: List[str], spec: Dict[str, Any] | None = None, patterns: Dict[str, Any] | None = None, session_id: str | None = None) → Dict[str, Any]

Gather existing derivatives and compose a cache.

Parameters:

• derivatives_dir (str) – Path to the derivatives directory

• subject_id (str) – Subject identifier

• std_spaces (list of str) – Standard space names to query

• spec (dict, optional) – Derivative specification. If None, defaults to nipreps spec

• patterns (dict, optional) – BIDS filename patterns. If None, defaults to nipreps patterns

• session_id (str, optional) – Session identifier

Returns:

derivs_cache – Dictionary of collected derivatives

Return type:

dict

oncoprep.utils.bids.write_bidsignore(deriv_dir: str) → None

Write a .bidsignore file to the derivatives directory.

Parameters:

deriv_dir (str) – Path to derivatives directory

oncoprep.utils.bids.write_derivative_description(bids_dir: str, deriv_dir: str) → None

Write a dataset_description.json for the derivatives folder.

Parameters:

• bids_dir (str) – Path to the input BIDS dataset

• deriv_dir (str) – Path to the derivatives directory

Examples

>>> from pathlib import Path
>>> from tempfile import TemporaryDirectory
>>> tmpdir = TemporaryDirectory()
>>> deriv_desc = Path(tmpdir.name) / 'dataset_description.json'
>>> write_derivative_description('.', deriv_desc.parent)
>>> deriv_desc.is_file()
True

Labels

oncoprep.utils.labels.split_seg_labels(seg_file)

Split multi-label segmentation into per-label binary masks.

BraTS old labels: 1=NCR, 2=ED, 3=ET, 4=RC. Returns one binary NIfTI per label in a fixed order so that the colour mapping in TumorROIsPlot stays consistent.

Miscellaneous

Self-contained utilities to be used within Function nodes.

oncoprep.utils.misc.apply_lut(in_dseg, lut, newpath=None)

Map the input discrete segmentation to a new label set (lookup table, LUT).

oncoprep.utils.misc.fs_isRunning(subjects_dir, subject_id, mtime_tol=86400, logger=None)

Checks FreeSurfer subjects dir for presence of recon-all blocking IsRunning files, and optionally removes any based on the modification time.

Parameters:

• subjects_dir (os.PathLike or None) – Existing FreeSurfer subjects directory

• subject_id (str) – Subject label

• mtime_tol (int) – Tolerance time (in seconds) between current time and last modification of recon-all.log

Returns:

subjects_dir

Return type:

os.PathLike or None

oncoprep.utils.misc.stringify_sessions(lst, max_length=10, digest_size=2)

Convert a list of session into a string identifier.

If the list has only one element, it returns that element. If the list has more than one element, it concatenates them with ‘-‘. If the concatenated string exceeds max_length, it returns a string starting with ‘multi-’ followed by a BLAKE2b hash of the concatenated string.

Example

>>> stringify_sessions(['a'])
'a'
>>> stringify_sessions(['a', 'b', 'c'])
'a-b-c'
>>> stringify_sessions(['a', 'b', 'toolong'])
'multi-32b3'
>>> stringify_sessions(['a', 'b', 'toolong'], max_length=12)
'a-b-toolong'
>>> stringify_sessions(['a', 'b', 'toolong'], digest_size=4)
'multi-f1edd4fd'