aisp 0.2.1__py3-none-any.whl → 0.3.1__py3-none-any.whl

aisp/__init__.py

@@ -1,4 +1,26 @@
-"""Artificial Immune Systems Package."""
+"""AISP - Artificial Immune Systems Package.
 
-__author__ = "João Paulo da Silva Barros"
-__version__ = "0.1.42"
+AISP is a Python package of immunoinspired techniques that apply metaphors from the vertebrate
+immune system to pattern recognition and optimization tasks.
+
+The package is organized into specialized modules, each dedicated to a family of Artificial
+Immune Systems algorithms:
+- csa: Clonal Selection Algorithms
+- nsa: Negative Selection Algorithms
+- ina: Immune Network Algorithms
+
+For detailed documentation and examples, visit:
+https://ais-package.github.io/docs/intro
+"""
+
+from . import csa
+from . import nsa
+from . import ina
+
+__author__ = "AISP Development Team"
+__version__ = "0.3.1"
+__all__ = [
+    'csa',
+    'nsa',
+    'ina'
+]

aisp/base/__init__.py

@@ -1,5 +1,7 @@
 """Base class modules."""
 
 from ._classifier import BaseClassifier
+from ._clusterer import BaseClusterer
+from ._base import set_seed_numba
 
-__all__ = ['BaseClassifier']
+__all__ = ['BaseClassifier', 'BaseClusterer', 'set_seed_numba']

aisp/base/_base.py

@@ -0,0 +1,65 @@
+"""Base class for parameter introspection compatible with the scikit-learn API."""
+import random
+
+import numpy as np
+from numba import njit
+
+
+class Base:
+    """
+    Generic base class for models with a common interface.
+
+    Provides the ``get_params`` and ``set_params`` method for compatibility with
+    the scikit-learn API, allowing access to the model's public parameters.
+    """
+
+    def set_params(self, **params):
+        """
+        Set the parameters of the instance.
+
+        This method is required to ensure compatibility with scikit-learn functions
+
+        Parameters
+        ----------
+        **params
+            set as attributes on the instance.
+
+        Returns
+        -------
+        self
+        """
+        for key, value in params.items():
+            if not key.startswith("_") and hasattr(self, key):
+                setattr(self, key, value)
+        return self
+
+    def get_params(self, deep: bool = True) -> dict:  # pylint: disable=W0613
+        """
+        Return a dictionary with the object's main parameters.
+
+        This method is required to ensure compatibility with scikit-learn functions.
+
+        Returns
+        -------
+        dict
+            Dictionary containing the object's attributes that do not start with "_".
+        """
+        return {
+            key: value
+            for key, value in self.__dict__.items()
+            if not key.startswith("_")
+        }
+
+
+@njit(cache=True)
+def set_seed_numba(seed: int):
+    """
+    Set the seed for random numbers used by functions compiled with Numba.
+
+    Parameters
+    ----------
+    seed : int
+        Integer value used to initialize Numba's random number generator.
+    """
+    np.random.seed(seed)
+    random.seed(seed)

aisp/base/_classifier.py

@@ -1,25 +1,26 @@
 """Base class for classification algorithm."""
 
+from __future__ import annotations
 from abc import ABC, abstractmethod
 from typing import Optional, Union
 
 import numpy.typing as npt
 
+from ._base import Base
 from ..utils import slice_index_list_by_class
 from ..utils.metrics import accuracy_score
 
 
-class BaseClassifier(ABC):
+class BaseClassifier(ABC, Base):
     """Base class for classification algorithms.
 
-    Defines the abstract methods ``fit`` and ``predict``, and implements the ``score``,
-    ``get_params`` method.
+    Defines the abstract methods ``fit`` and ``predict``, and implements the ``score`` method.
     """
 
     classes: Union[npt.NDArray, list] = []
 
     @abstractmethod
-    def fit(self, X: npt.NDArray, y: npt.NDArray, verbose: bool = True) -> "BaseClassifier":
+    def fit(self, X: npt.NDArray, y: npt.NDArray, verbose: bool = True) -> BaseClassifier:
         """
         Train the model using the input data X and corresponding labels y.
 
@@ -106,15 +107,3 @@ class BaseClassifier(ABC):
             A dictionary with the list of array positions(``y``), with the classes as key.
         """
         return slice_index_list_by_class(self.classes, y)
-
-    def get_params(self, deep: bool = True) -> dict:  # pylint: disable=W0613
-        """
-        Return a dictionary with the object's main parameters.
-
-        This method is required to ensure compatibility with scikit-learn functions.
-        """
-        return {
-            key: value
-            for key, value in self.__dict__.items()
-            if not key.startswith("_")
-        }

aisp/base/_clusterer.py

@@ -0,0 +1,77 @@
+"""Base class for clustering algorithms."""
+
+from __future__ import annotations
+from abc import ABC, abstractmethod
+from typing import Optional
+
+import numpy.typing as npt
+
+from ._base import Base
+
+
+class BaseClusterer(ABC, Base):
+    """Abstract base class for clustering algorithms.
+
+    This class defines the core interface for clustering models. It enforces
+    the implementation of the `fit` and `predict` methods in all derived classes,
+    and provides a default implementation for `fit_predict` and `get_params`.
+    """
+
+    @abstractmethod
+    def fit(self, X: npt.NDArray, verbose: bool = True) -> BaseClusterer:
+        """
+        Train the model using the input data X.
+
+        This abstract method is implemented by the class that inherits it.
+
+        Parameters
+        ----------
+        X : npt.NDArray
+            Input data used for training the model.
+        verbose : bool, default=True
+            Flag to enable or disable detailed output during training.
+
+        Returns
+        -------
+        self : BaseClusterer
+            Returns the instance of the class that implements this method.
+        """
+
+    @abstractmethod
+    def predict(self, X: npt.NDArray) -> Optional[npt.NDArray]:
+        """
+        Generate predictions based on the input data X.
+
+        This abstract method is implemented by the class that inherits it.
+
+        Parameters
+        ----------
+        X : npt.NDArray
+            Input data for which predictions will be generated.
+
+        Returns
+        -------
+        predictions : Optional[npt.NDArray]
+            Predicted cluster labels for each input sample, or None if prediction is not possible.
+        """
+
+    def fit_predict(self, X, verbose: bool = True):
+        """Fit the clustering model to the data and return cluster labels.
+
+        This is a convenience method that combines `fit` and `predict`
+        into a single call.
+
+        Parameters
+        ----------
+        X : npt.NDArray
+            Input data for which predictions will be generated.
+        verbose : bool, default=True
+            Flag to enable or disable detailed output during training.
+
+        Returns
+        -------
+        predictions : Optional[npt.NDArray]
+            Predicted cluster labels for each input sample, or None if prediction is not possible.
+        """
+        self.fit(X, verbose)
+        return self.predict(X)

aisp/csa/__init__.py

@@ -3,7 +3,7 @@
 CSAs are inspired by the process of antibody proliferation upon detecting an antigen, during which
 the generated antibodies undergo mutations in an attempt to enhance pathogen recognition.
 """
-from ._ai_immune_recognition_sys import AIRS
+from ._ai_recognition_sys import AIRS
 
 __author__ = 'João Paulo da Silva Barros'
 __all__ = ['AIRS']

aisp/csa/{_ai_immune_recognition_sys.py → _ai_recognition_sys.py}

@@ -1,5 +1,6 @@
 """Artificial Immune Recognition System (AIRS)."""
 
+from __future__ import annotations
 import random
 from collections import Counter
 from heapq import nlargest
@@ -11,7 +12,7 @@ import numpy.typing as npt
 from scipy.spatial.distance import pdist
 from tqdm import tqdm
 
-
+from ..base import set_seed_numba
 from ._cell import Cell
 from ..utils.sanitizers import sanitize_param, sanitize_seed, sanitize_choice
 from ..utils.distance import hamming, compute_metric_distance, get_metric_code
@@ -178,6 +179,7 @@ class AIRS(BaseAIRS):
         self.seed: Optional[int] = sanitize_seed(seed)
         if self.seed is not None:
             np.random.seed(self.seed)
+            set_seed_numba(self.seed)
 
         self._feature_type: FeatureType = "continuous-features"
 
@@ -188,6 +190,7 @@ class AIRS(BaseAIRS):
         self.p: np.float64 = np.float64(kwargs.get("p", 2.0))
 
         self._cells_memory = None
+        self._all_class_cell_vectors = None
         self.affinity_threshold = 0.0
         self.classes = []
         self._bounds: Optional[npt.NDArray[np.float64]] = None
@@ -197,7 +200,7 @@ class AIRS(BaseAIRS):
         """Returns the trained cells memory, organized by class."""
         return self._cells_memory
 
-    def fit(self, X: npt.NDArray, y: npt.NDArray, verbose: bool = True) -> "AIRS":
+    def fit(self, X: npt.NDArray, y: npt.NDArray, verbose: bool = True) -> AIRS:
         """
         Fit the model to the training data using the AIRS.
 
@@ -219,8 +222,6 @@ class AIRS(BaseAIRS):
         AIRS
             Returns the instance itself.
         """
-        progress = None
-
         self._feature_type = detect_vector_data_type(X)
 
         super()._check_and_raise_exceptions_fit(X, y)
@@ -234,18 +235,17 @@ class AIRS(BaseAIRS):
 
         self.classes = np.unique(y)
         sample_index = self._slice_index_list_by_class(y)
-        if verbose:
-            progress = tqdm(
-                total=len(y),
-                postfix="\n",
-                bar_format="{desc} ┇{bar}┇ {n}/{total} memory cells for each aᵢ",
-            )
+        progress = tqdm(
+            total=len(y),
+            postfix="\n",
+            disable=not verbose,
+            bar_format="{desc} ┇{bar}┇ {n}/{total} memory cells for each aᵢ",
+        )
         pool_cells_classes = {}
         for _class_ in self.classes:
-            if verbose and progress is not None:
-                progress.set_description_str(
-                    f"Generating the memory cells for the {_class_} class:"
-                )
+            progress.set_description_str(
+                f"Generating the memory cells for the {_class_} class:"
+            )
 
             x_class = X[sample_index[_class_]]
             # Calculating the similarity threshold between antigens
@@ -294,16 +294,20 @@ class AIRS(BaseAIRS):
                     if self._affinity(c_candidate.vector, c_match.vector) < sufficiently_similar:
                         pool_c.remove(c_match)
 
-                if verbose and progress is not None:
-                    progress.update(1)
+                progress.update(1)
             pool_cells_classes[_class_] = pool_c
 
-        if verbose and progress is not None:
-            progress.set_description(
-                f"\033[92m✔ Set of memory cells for classes ({', '.join(map(str, self.classes))}) "
-                f"successfully generated\033[0m"
-            )
+        progress.set_description(
+            f"\033[92m✔ Set of memory cells for classes ({', '.join(map(str, self.classes))}) "
+            f"successfully generated\033[0m"
+        )
+        progress.close()
         self._cells_memory = pool_cells_classes
+        self._all_class_cell_vectors = [
+            (class_name, cell.vector)
+            for class_name in self.classes
+            for cell in self._cells_memory[class_name]
+        ]
         return self
 
     def predict(self, X: npt.NDArray) -> Optional[npt.NDArray]:
@@ -325,7 +329,7 @@ class AIRS(BaseAIRS):
             An ndarray of the form ``C`` [``N samples``], containing the predicted classes for
             ``X``. or ``None``: If there are no detectors for the prediction.
         """
-        if self._cells_memory is None:
+        if self._all_class_cell_vectors is None:
             return None
 
         super()._check_and_raise_exceptions_predict(
@@ -334,16 +338,10 @@ class AIRS(BaseAIRS):
 
         c: list = []
 
-        all_cells_memory = [
-            (class_name, cell.vector)
-            for class_name in self.classes
-            for cell in self._cells_memory[class_name]
-        ]
-
         for line in X:
             label_stim_list = [
                 (class_name, self._affinity(memory, line))
-                for class_name, memory in all_cells_memory
+                for class_name, memory in self._all_class_cell_vectors
             ]
             # Create the list with the k nearest neighbors and select the class with the most votes
             k_nearest = nlargest(self.k, label_stim_list, key=lambda x: x[1])

aisp/csa/_base.py

@@ -54,7 +54,6 @@ class BaseAIRS(BaseClassifier, ABC):
                 "X does not have the same amount of sample for the output classes in y."
             )
 
-
     @staticmethod
     def _check_and_raise_exceptions_predict(
         X: npt.NDArray,

aisp/ina/__init__.py

@@ -0,0 +1,14 @@
+"""Module (ina) Immune Network Algorithm.
+
+This module implements algorithms based on Network Theory Algorithms proposed by Jerne.
+
+Classes
+-------
+AiNet
+    Artificial Immune Network implementation for clustering.
+"""
+
+from ._ai_network import AiNet
+
+__author__ = 'João Paulo da Silva Barros'
+__all__ = ['AiNet']