kwneuro.util
============

.. py:module:: kwneuro.util

.. autoapi-nested-parse::

   Common utility functions



Attributes
----------

.. autoapisummary::

   kwneuro.util.PathLike


Functions
---------

.. autoapisummary::

   kwneuro.util.normalize_path
   kwneuro.util.ensure_output_dir
   kwneuro.util.create_estimate_volume_resource
   kwneuro.util.update_volume_metadata
   kwneuro.util.subsample_volume
   kwneuro.util.deep_equal_allclose


Module Contents
---------------

.. py:data:: PathLike

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


.. py:function:: ensure_output_dir(path: PathLike) -> pathlib.Path

   Normalize *path*, assert it is a directory (not a file), create it, and return it.


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


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


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

   :param volume: The volume to subsample.
   :param 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.


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