:py:mod:`kwcoco.util`
=====================

.. py:module:: kwcoco.util

.. autoapi-nested-parse::

   mkinit ~/code/kwcoco/kwcoco/util/__init__.py -w



Submodules
----------
.. toctree::
   :titlesonly:
   :maxdepth: 1

   dict_like/index.rst
   jsonschema_elements/index.rst
   util_delayed_poc/index.rst
   util_futures/index.rst
   util_json/index.rst
   util_monkey/index.rst
   util_sklearn/index.rst


Package Contents
----------------

Classes
~~~~~~~

.. autoapisummary::

   kwcoco.util.Executor
   kwcoco.util.SerialExecutor
   kwcoco.util.StratifiedGroupKFold




.. py:class:: Executor(mode='thread', max_workers=0)

   Bases: :py:obj:`object`

   Wrapper around a specific executor.

   Abstracts Serial, Thread, and Process Executor via arguments.

   :Parameters: * **mode** (*str, default='thread'*) -- either thread, serial, or process
                * **max_workers** (*int, default=0*) -- number of workers. If 0, serial is forced.

   .. py:method:: __enter__(self)


   .. py:method:: __exit__(self, ex_type, ex_value, tb)


   .. py:method:: submit(self, func, *args, **kw)


   .. py:method:: shutdown(self)



.. py:class:: SerialExecutor

   Bases: :py:obj:`object`

   Implements the concurrent.futures API around a single-threaded backend

   .. rubric:: Example

   >>> with SerialExecutor() as executor:
   >>>     futures = []
   >>>     for i in range(100):
   >>>         f = executor.submit(lambda x: x + 1, i)
   >>>         futures.append(f)
   >>>     for f in concurrent.futures.as_completed(futures):
   >>>         assert f.result() > 0
   >>>     for i, f in enumerate(futures):
   >>>         assert i + 1 == f.result()

   .. py:method:: __enter__(self)


   .. py:method:: __exit__(self, ex_type, ex_value, tb)


   .. py:method:: submit(self, func, *args, **kw)


   .. py:method:: shutdown(self)



.. py:class:: StratifiedGroupKFold(n_splits=3, shuffle=False, random_state=None)

   Bases: :py:obj:`sklearn.model_selection._split._BaseKFold`

   Stratified K-Folds cross-validator with Grouping

   Provides train/test indices to split data in train/test sets.

   This cross-validation object is a variation of GroupKFold that returns
   stratified folds. The folds are made by preserving the percentage of
   samples for each class.

   Read more in the :ref:`User Guide <cross_validation>`.

   :Parameters: **n_splits** (*int, default=3*) -- Number of folds. Must be at least 2.

   .. py:method:: _make_test_folds(self, X, y=None, groups=None)

      :Parameters: * **X** (*ndarray*) -- data
                   * **y** (*ndarray*) -- labels
                   * **groups** (*ndarray*) -- groupids for items. Items with the same groupid
                     must be placed in the same group.

      :returns: test_folds
      :rtype: list

      .. rubric:: Example

      >>> import kwarray
      >>> rng = kwarray.ensure_rng(0)
      >>> groups = [1, 1, 3, 4, 2, 2, 7, 8, 8]
      >>> y      = [1, 1, 1, 1, 2, 2, 2, 3, 3]
      >>> X = np.empty((len(y), 0))
      >>> self = StratifiedGroupKFold(random_state=rng, shuffle=True)
      >>> skf_list = list(self.split(X=X, y=y, groups=groups))
      ...
      >>> import ubelt as ub
      >>> print(ub.repr2(skf_list, nl=1, with_dtype=False))
      [
          (np.array([2, 3, 4, 5, 6]), np.array([0, 1, 7, 8])),
          (np.array([0, 1, 2, 7, 8]), np.array([3, 4, 5, 6])),
          (np.array([0, 1, 3, 4, 5, 6, 7, 8]), np.array([2])),
      ]


   .. py:method:: _iter_test_masks(self, X, y=None, groups=None)

      Generates boolean masks corresponding to test sets.

      By default, delegates to _iter_test_indices(X, y, groups)


   .. py:method:: split(self, X, y, groups=None)

      Generate indices to split data into training and test set.