kwneuro.util¶

Common utility functions

Attributes¶

PathLike

Functions¶

`normalize_path`(→ pathlib.Path)	Accepts a path as a string or Path object, expands the tilde (~),
`ensure_output_dir`(→ pathlib.Path)	Normalize path, assert it is a directory (not a file), create it, and return it.
`create_estimate_volume_resource`(...)	Creates an InMemoryVolumeResource from a numpy array of scalar estimates,
`update_volume_metadata`(, intent_name, Any])	Use the convenience of nibabel's header class to update volume metadata.
`subsample_volume`(→ kwneuro.resource.InMemoryVolumeResource)	Spatially subsample a volume by taking every Nth voxel along each spatial axis.
`deep_equal_allclose`(→ bool)	Recursively compares two objects, including nested lists, tuples,

Module Contents¶

kwneuro.util.PathLike¶

kwneuro.util.normalize_path(path_input: PathLike) → pathlib.Path¶: Accepts a path as a string or Path object, expands the tilde (~), and returns a resolved, absolute Path object.

kwneuro.util.ensure_output_dir(path: PathLike) → pathlib.Path¶: Normalize path, assert it is a directory (not a file), create it, and return it.

kwneuro.util.create_estimate_volume_resource(array: numpy.typing.NDArray[Any], reference_volume: kwneuro.resource.VolumeResource, intent_name: str) → kwneuro.resource.VolumeResource¶: Creates an InMemoryVolumeResource from a numpy array of scalar estimates, using the affine and metadata of a reference volume.

kwneuro.util.update_volume_metadata(metadata: dict[str, Any], volume_data_array: numpy.ndarray, intent_code: int | str | None = None, intent_params: Any = (), intent_name: str = '') → dict[str, Any]¶

Use the convenience of nibabel’s header class to update volume metadata. If intent_code is not provided then we don’t modify the intent parameters.

Keys in metadata that are valid NIfTI-1 header fields flow through a Nifti1Header (so they get the standard normalisation). Keys that aren’t NIfTI fields are preserved verbatim in the returned dict. This lets VolumeResource implementations carry custom metadata alongside the canonical NIfTI fields.

Note: custom (non-NIfTI) keys don’t survive a NIfTI save via NiftiVolumeResource.save — nibabel only writes actual header fields.

kwneuro.util.subsample_volume(volume: kwneuro.resource.VolumeResource, factor: int = 2) → kwneuro.resource.InMemoryVolumeResource¶

Spatially subsample a volume by taking every Nth voxel along each spatial axis.

This is stride-based subsampling (not interpolated resampling). It is mainly useful for quickly reducing resolution in demo notebooks so that expensive downstream steps run faster.

Parameters:

volume – The volume to subsample.
factor – Take every factor-th voxel along each of the first three (spatial) dimensions. Extra dimensions are left untouched.

Returns:

A new InMemoryVolumeResource with the subsampled data and an updated affine that reflects the coarser voxel grid.

kwneuro.util.deep_equal_allclose(obj1: Any, obj2: Any) → bool¶: Recursively compares two objects, including nested lists, tuples, and dicts. Uses np.allclose for numpy arrays. NaN’s are considered equal.