pcntoolkit.util.data_utils
==========================

.. py:module:: pcntoolkit.util.data_utils

.. autoapi-nested-parse::

   Utilities for data operations.

   This module is the shared home for programming operations (e.g., from NumPy,
   pandas, xarray, itertools packages). The goal is to keep the main codebase
   focused on Bayesian statistics while moving reusable programming operations
   to a shared utility module.



Functions
---------

.. autoapisummary::

   pcntoolkit.util.data_utils.iter_batch_combinations


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

.. py:function:: iter_batch_combinations(batch_values: numpy.ndarray, unique_batch_effects: dict[str, list[str | int]], batch_dims: list[str]) -> Generator[tuple[dict[str, str | int], numpy.ndarray]]

   Yield batch-effect combinations together with observation masks.

   :param batch_values: Observed batch-effect values with shape
                        ``(n_observations, n_batch_dims)``.
   :type batch_values: :py:class:`np.ndarray`
   :param unique_batch_effects: Allowed values for each batch-effect dimension.
   :type unique_batch_effects: :py:class:`dict[str`, :py:class:`list[str | int]]`
   :param batch_dims: Ordered batch-effect dimensions used to interpret both
                      ``batch_values`` and ``unique_batch_effects``.
   :type batch_dims: :py:class:`list[str]`

   :Yields: :py:class:`tuple[dict[str`, :py:class:`str | int]`, :py:class:`np.ndarray]` -- A dictionary describing one batch-effect combination and a
            boolean mask that selects observations in that combination.

   :raises KeyError: If ``unique_batch_effects`` is missing a requested batch
       dimension.