gwkokab.analysis.utils.jenks
============================

.. py:module:: gwkokab.analysis.utils.jenks

.. autoapi-nested-parse::

   Bucketing and padding utilities using Jenks' Natural Breaks algorithm.

   This module provides functionality to partition sequences of arrays into buckets based
   on their sizes using Jenks' Natural Breaks algorithm, then pad and stack these arrays
   within each bucket for uniform shape. This is useful for managing memory usage when
   processing large datasets.



Functions
---------

.. autoapisummary::

   gwkokab.analysis.utils.jenks.pad_and_stack


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

.. py:function:: pad_and_stack(*arrays: collections.abc.Sequence[Union[jaxtyping.Array, numpy.ndarray]], n_buckets: Optional[int] = None, threshold: float = 3.0) -> Tuple[collections.abc.Sequence[jaxtyping.Array], Ellipsis]

   Pad and stack multiple arrays into buckets.

   :param \*arrays: Variable number of array sequences to be bucketed. All sequences must
                    have the same length.
   :type \*arrays: Sequence[Union[Array, np.ndarray]]
   :param n_buckets: The number of buckets to create from the data. If None, the function will
                     partition the data into buckets based on the sizes of the arrays.
   :type n_buckets: Optional[int]
   :param threshold: if :code:`n_buckets` is None, this value is used to determine the maximum size of
                     the buckets.
   :type threshold: float

   :returns: A sequence of lists of padded arrays, where each list corresponds to an original
             array sequence, and the elements of the inner list are the stacked buckets.
             The last element of the returned tuple is the list of mask arrays (one mask array
             per bucket).
   :rtype: Tuple[Sequence[Array], ...]