artlib.common.utils
===================

.. py:module:: artlib.common.utils

.. autoapi-nested-parse::

   General utilities used throughout ARTLib.



Attributes
----------

.. autoapisummary::

   artlib.common.utils.IndexableOrKeyable


Functions
---------

.. autoapisummary::

   artlib.common.utils.normalize
   artlib.common.utils.de_normalize
   artlib.common.utils.complement_code
   artlib.common.utils.de_complement_code
   artlib.common.utils.l1norm
   artlib.common.utils.l2norm2
   artlib.common.utils.fuzzy_and
   artlib.common.utils.fracsort
   artlib.common.utils.fracargmax
   artlib.common.utils.binarize_features_thermometer


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

.. py:data:: IndexableOrKeyable

.. py:function:: normalize(data: numpy.ndarray, d_max: Optional[numpy.ndarray] = None, d_min: Optional[numpy.ndarray] = None) -> Tuple[numpy.ndarray, numpy.ndarray, numpy.ndarray]

   Normalize data column-wise between 0 and 1.

   :param data: 2D array of dataset (rows = samples, columns = features).
   :type data: np.ndarray
   :param d_max: Maximum values for each column.
   :type d_max: np.ndarray, optional
   :param d_min: Minimum values for each column.
   :type d_min: np.ndarray, optional

   :returns: * *np.ndarray* -- Normalized data.
             * *np.ndarray* -- Maximum values for each column.
             * *np.ndarray* -- Minimum values for each column.


.. py:function:: de_normalize(data: numpy.ndarray, d_max: numpy.ndarray, d_min: numpy.ndarray) -> numpy.ndarray

   Restore column-wise normalized data to original scale.

   :param data: Normalized data.
   :type data: np.ndarray
   :param d_max: Maximum values for each column.
   :type d_max: np.ndarray
   :param d_min: Minimum values for each column.
   :type d_min: np.ndarray

   :returns: De-normalized data.
   :rtype: np.ndarray


.. py:function:: complement_code(data: numpy.ndarray) -> numpy.ndarray

   Complement code the data.

   :param data: Dataset.
   :type data: np.ndarray

   :returns: complement coded data.
   :rtype: np.ndarray


.. py:function:: de_complement_code(data: numpy.ndarray) -> numpy.ndarray

   Find the centroid of complement coded data.

   :param data: Dataset.
   :type data: np.ndarray

   :returns: De-complement coded data.
   :rtype: np.ndarray


.. py:function:: l1norm(x: numpy.ndarray) -> float

   Get the L1 norm of a vector using Numba.

   :param x: Input vector.
   :type x: np.ndarray

   :returns: L1 norm.
   :rtype: float


.. py:function:: l2norm2(data: numpy.ndarray) -> float

   Get the squared L2 norm of a vector.

   :param data: Input vector.
   :type data: np.ndarray

   :returns: Squared L2 norm.
   :rtype: float


.. py:function:: fuzzy_and(x: numpy.ndarray, y: numpy.ndarray) -> numpy.ndarray

   Get the fuzzy AND operation between two vectors.

   :param x: First input vector.
   :type x: np.ndarray
   :param y: Second input vector.
   :type y: np.ndarray

   :returns: Fuzzy AND result.
   :rtype: np.ndarray


.. py:function:: fracsort(num: numpy.typing.ArrayLike, den: numpy.typing.ArrayLike) -> numpy.typing.NDArray[numpy.intp]

   Get argsort indices for elementwise fractions ``num[i] / den[i]`` without
   division.

   This function returns an index array that sorts the rational values exactly using
   cross-multiplication in a compiled C++ backend (no division is performed). Ties
   are broken by the lowest original index.

   :param num: 1D array-like of nonnegative numerators. Must be convertible to a contiguous
               NumPy array with dtype ``np.uint32`` or ``np.uint64``.
   :type num: ArrayLike
   :param den: 1D array-like of denominators with ``den[i] >= 1``. Must be convertible to a
               contiguous NumPy array with dtype ``np.uint32`` or ``np.uint64`` and have the
               same shape and dtype as ``num``.
   :type den: ArrayLike

   :returns: Indices that sort ``num[i] / den[i]`` in ascending order, with ties broken by
             the lowest index.
   :rtype: NDArray[np.intp]


.. py:function:: fracargmax(num: numpy.typing.ArrayLike, den: numpy.typing.ArrayLike) -> numpy.intp

   Get the index that maximizes the elementwise fractions ``num[i] / den[i]``
   without division.

   This function returns the index of the maximum rational value exactly using
   cross-multiplication in a compiled C++ backend (no division is performed). Ties
   are broken first by the larger denominator, then by the lowest original index.

   :param num: 1D array-like of nonnegative numerators. Must be convertible to a contiguous
               NumPy array with dtype ``np.uint32`` or ``np.uint64``.
   :type num: ArrayLike
   :param den: 1D array-like of denominators with ``den[i] >= 1``. Must be convertible to a
               contiguous NumPy array with dtype ``np.uint32`` or ``np.uint64`` and have the
               same shape and dtype as ``num``.
   :type den: ArrayLike

   :returns: Index ``i`` that maximizes ``num[i] / den[i]`` (descending). Ties are broken
             by larger denominator first, then the lowest index.
   :rtype: np.intp


.. py:function:: binarize_features_thermometer(data: numpy.ndarray, n_bits: int) -> numpy.ndarray

   Binarizes each feature in the data using thermometer encoding.

   :param data: Input array of shape (n, m), where n is the number of
                samples and m is the number of features.
   :type data: np.ndarray
   :param n_bits: Number of bits to use for thermometer encoding.
   :type n_bits: int

   :returns:

             A thermometer-coded representation of the input data with
                 shape (n, m * n_bits).
   :rtype: np.ndarray