artlib.elementary.ART1
======================

.. py:module:: artlib.elementary.ART1

.. autoapi-nested-parse::

   ART1 :cite:`carpenter1987massively`.



Classes
-------

.. autoapisummary::

   artlib.elementary.ART1.ART1


Functions
---------

.. autoapisummary::

   artlib.elementary.ART1.match_criterion_numba
   artlib.elementary.ART1.category_choice_numba
   artlib.elementary.ART1.update_numba


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

.. py:function:: match_criterion_numba(i, w_td, dim_)

   Compute the match criterion for ART1 clustering.

   This function calculates the proportion of active features in the input `i`
   that match the corresponding features in the top-down weight vector `w_td`.

   :param i: Binary or integer input vector representing the data sample.
   :type i: np.ndarray (int32 or uint8)
   :param w_td: Binary top-down weight vector of the cluster.
   :type w_td: np.ndarray (uint8)
   :param dim_: The number of features (dimensions) in the input vector.
   :type dim_: int

   :returns: The match criterion value, computed as the ratio of matching features
             to the total number of features.
   :rtype: float


.. py:function:: category_choice_numba(i, w_bu)

   Compute the category choice activation for ART1.

   This function calculates the category choice value, which represents the
   strength of association between an input `i` and a bottom-up weight vector `w_bu`.

   :param i: Binary or integer input vector representing the data sample.
   :type i: np.ndarray (int32 or uint8)
   :param w_bu: Bottom-up weight vector of the cluster.
   :type w_bu: np.ndarray (float32)

   :returns: The activation value, computed as the sum of element-wise multiplications.
   :rtype: float


.. py:function:: update_numba(i, w, L, dim_)

   Optimized update function for ART1 using Numba.

   This function updates the cluster weight vector based on the input `i`,
   using ART1 learning rules.

   :param i: Binary or integer input vector.
   :type i: np.ndarray (int32 or uint8)
   :param w: Cluster weight vector, containing both bottom-up and top-down weights.
   :type w: np.ndarray (float32)
   :param L: Uncommitted node bias parameter.
   :type L: float
   :param dim_: Feature dimension.
   :type dim_: int

   :returns: Updated cluster weight vector.
   :rtype: np.ndarray


.. py:class:: ART1(rho: float, L: float)

   Bases: :py:obj:`artlib.common.BaseART.BaseART`


   ART1 for Binary Clustering.

   This module implements ART1 as first published in: :cite:`carpenter1987massively`.


   .. # Carpenter, G. A., & Grossberg, S. (1987a).
   .. # A massively parallel architecture for a self-organizing neural pattern
   .. # recognition machine.
   .. # Computer Vision, Graphics, and Image
   .. # Processing, 37, 54 – 115. doi:10. 1016/S0734-189X(87)80014-2.

   ART1 is exclusively for clustering binary data.



   .. py:method:: prepare_data(X: numpy.ndarray) -> numpy.ndarray

      Prepare data for clustering.

      :param X: Dataset.
      :type X: np.ndarray

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



   .. py:method:: restore_data(X: numpy.ndarray) -> numpy.ndarray

      Restore data to its state prior to preparation.

      :param X: Dataset.
      :type X: np.ndarray

      :returns: Restored data.
      :rtype: np.ndarray



   .. py:method:: validate_params(params: dict)
      :staticmethod:


      Validate clustering parameters.

      :param params: Dictionary containing parameters for the algorithm.
      :type params: dict



   .. py:method:: validate_data(X: numpy.ndarray)

      Validate the data prior to clustering.

      :param X: The dataset.
      :type X: np.ndarray



   .. py:method:: category_choice(i: numpy.ndarray, w: numpy.ndarray, params: dict) -> tuple[float, Optional[dict]]

      Get the activation of the cluster.

      :param i: Data sample.
      :type i: np.ndarray
      :param w: Cluster weight or information.
      :type w: np.ndarray
      :param params: Dictionary containing parameters for the algorithm.
      :type params: dict

      :returns: * *float* -- Cluster activation.
                * *dict, optional* -- Cache used for later processing.



   .. py:method:: match_criterion(i: numpy.ndarray, w: numpy.ndarray, params: dict, cache: Optional[dict] = None) -> Tuple[float, Optional[Dict]]

      Get the match criterion of the cluster.

      :param i: Data sample.
      :type i: np.ndarray
      :param w: Cluster weight or information.
      :type w: np.ndarray
      :param params: Dictionary containing parameters for the algorithm.
      :type params: dict
      :param cache: Cache containing values from previous calculations.
      :type cache: dict, optional

      :returns: * *float* -- Cluster match criterion.
                * *dict* -- Cache used for later processing.



   .. py:method:: update(i: numpy.ndarray, w: numpy.ndarray, params: dict, cache: Optional[dict] = None) -> numpy.ndarray

      Get the updated cluster weight.

      :param i: Data sample.
      :type i: np.ndarray
      :param w: Cluster weight or information.
      :type w: np.ndarray
      :param params: Dictionary containing parameters for the algorithm.
      :type params: dict
      :param cache: Cache containing values from previous calculations.
      :type cache: dict, optional

      :returns: Updated cluster weight.
      :rtype: np.ndarray



   .. py:method:: new_weight(i: numpy.ndarray, params: dict) -> numpy.ndarray

      Generate a new cluster weight.

      :param i: Data sample.
      :type i: np.ndarray
      :param params: Dictionary containing parameters for the algorithm.
      :type params: dict

      :returns: Updated cluster weight.
      :rtype: np.ndarray



   .. py:method:: get_cluster_centers() -> List[numpy.ndarray]

      Get the centers of each cluster, used for regression.

      :returns: Cluster centroids.
      :rtype: list of np.ndarray