aisp 0.2.0__py3-none-any.whl → 0.3.0__py3-none-any.whl

aisp/__init__.py

@@ -1,4 +1,4 @@
 """Artificial Immune Systems Package."""
 
 __author__ = "João Paulo da Silva Barros"
-__version__ = "0.1.42"
+__version__ = "0.3.0"

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

@@ -5,21 +5,21 @@ 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: Optional[Union[npt.NDArray, list]] = None
+    classes: Union[npt.NDArray, list] = []
 
     @abstractmethod
-    def fit(self, X: npt.NDArray, y: npt.NDArray, verbose: bool = True):
+    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.
 
@@ -83,6 +83,10 @@ class BaseClassifier(ABC):
         if len(y) == 0:
             return 0
         y_pred = self.predict(X)
+
+        if y_pred is None:
+            return 0
+
         return accuracy_score(y, y_pred)
 
     def _slice_index_list_by_class(self, y: npt.NDArray) -> dict:
@@ -102,15 +106,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,76 @@
+"""Base class for clustering algorithms."""
+
+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/base/mutation.py

@@ -84,3 +84,47 @@ def clone_and_mutate_binary(
         clone_set[i] = clone
 
     return clone_set
+
+
+@njit([(types.float64[:], types.int64, types.float64[:, :])], cache=True)
+def clone_and_mutate_ranged(
+    vector: npt.NDArray[np.float64],
+    n: int,
+    bounds: npt.NDArray[np.float64]
+) -> npt.NDArray[np.float64]:
+    """
+    Generate a set of mutated clones from a cell represented by custom ranges per dimension.
+
+    This function creates `n` clones of the input vector and applies random mutations to each of
+    them, simulating the process of clonal expansion in artificial immune systems. Each clone
+    will have a random number of mutations applied in distinct positions of the original vector.
+
+    Parameters
+    ----------
+    vector : npt.NDArray[np.bool_]
+        The original immune cell with binary values to be cloned and mutated.
+    n : int
+        The number of mutated clones to be generated.
+    bounds : np.ndarray
+        Array (n_features, 2) with min and max per dimension.
+
+    Returns
+    -------
+    clone_set : npt.NDArray
+        An Array(n, len(vector)) containing the `n` mutated clones of the original vector.
+    """
+    n_features = vector.shape[0]
+    clone_set = np.empty((n, n_features), dtype=np.float64)
+
+    for i in range(n):
+        n_mutations = np.random.randint(1, n_features)
+        clone = vector.copy()
+        position_mutations = np.random.permutation(n_features)[:n_mutations]
+        for j in range(n_mutations):
+            idx = position_mutations[j]
+            min_limit = bounds[idx, 0]
+            max_limit = bounds[idx, 1]
+            clone[idx] = np.random.uniform(min_limit, max_limit)
+        clone_set[i] = clone
+
+    return clone_set

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}

@@ -4,16 +4,19 @@ import random
 from collections import Counter
 from heapq import nlargest
 from operator import attrgetter
-from typing import List, Literal, Optional, Dict
+from typing import List, Optional, Dict
 
 import numpy as np
 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
+from ..utils.types import FeatureType, MetricType
+from ..utils.validation import detect_vector_data_type
 from ._base import BaseAIRS
 
 
@@ -114,20 +117,12 @@ class AIRS(BaseAIRS):
         * ``'manhattan'`` ➜ The calculation of the distance is given by the expression:
             ( |x₁ – x₂| + |y₁ – y₂| + ... + |yn – yn|).
 
-    algorithm : Literal["continuous-features", "binary-features"], default="continuous-features"
-        Specifies the type of algorithm to use based on the nature of the input features:
-
-        * ``continuous-features``: selects an algorithm designed for continuous data, which should
-            be normalized within the range [0, 1].
-
-        * ``binary-features``: selects an algorithm specialized for handling binary variables.
-
     seed : int
         Seed for the random generation of detector values. Defaults to None.
 
     **kwargs
         p : float
-            This parameter stores the value of ``p`` used in the Minkowsks distance. The default
+            This parameter stores the value of ``p`` used in the Minkowski distance. The default
             is ``2``, which represents normalized Euclidean distance.\
             Different values of p lead to different variants of the Minkowski Distance.
 
@@ -160,11 +155,8 @@ class AIRS(BaseAIRS):
         k: int = 3,
         max_iters: int = 100,
         resource_amplified: float = 1.0,
-        metric: Literal["manhattan", "minkowski", "euclidean"] = "euclidean",
-        algorithm: Literal[
-            "continuous-features", "binary-features"
-        ] = "continuous-features",
-        seed: int = None,
+        metric: MetricType = "euclidean",
+        seed: Optional[int] = None,
         **kwargs,
     ) -> None:
         self.n_resources: float = sanitize_param(n_resources, 10, lambda x: x >= 1)
@@ -183,35 +175,30 @@ class AIRS(BaseAIRS):
         )
         self.k: int = sanitize_param(k, 3, lambda x: x > 3)
         self.max_iters: int = sanitize_param(max_iters, 100, lambda x: x > 0)
-        self.seed: int = sanitize_seed(seed)
+        self.seed: Optional[int] = sanitize_seed(seed)
         if self.seed is not None:
             np.random.seed(self.seed)
+            set_seed_numba(self.seed)
 
-        self.algorithm: Literal["continuous-features", "binary-features"] = (
-            sanitize_param(
-                algorithm, "continuous-features", lambda x: x == "binary-features"
-            )
-        )
+        self._feature_type: FeatureType = "continuous-features"
 
-        if algorithm == "binary-features":
-            self.metric: str = "hamming"
-        else:
-            self.metric: str = sanitize_choice(
-                metric, ["manhattan", "minkowski"], "euclidean"
-            )
+        self.metric = sanitize_choice(
+            metric, ["manhattan", "minkowski"], "euclidean"
+        )
 
         self.p: np.float64 = np.float64(kwargs.get("p", 2.0))
 
         self._cells_memory = None
         self.affinity_threshold = 0.0
-        self.classes = None
+        self.classes = []
+        self._bounds: Optional[npt.NDArray[np.float64]] = None
 
     @property
-    def cells_memory(self) -> Dict[str, list[Cell]]:
+    def cells_memory(self) -> Optional[Dict[str, list[Cell]]]:
         """Returns the trained cells memory, organized by class."""
         return self._cells_memory
 
-    def fit(self, X: npt.NDArray, y: npt.NDArray, verbose: bool = True):
+    def fit(self, X: npt.NDArray, y: npt.NDArray, verbose: bool = True) -> "AIRS":
         """
         Fit the model to the training data using the AIRS.
 
@@ -233,27 +220,30 @@ 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, self.algorithm)
+        super()._check_and_raise_exceptions_fit(X, y)
 
-        if self.algorithm == "binary-features":
-            X = X.astype(np.bool_)
+        match self._feature_type:
+            case "binary-features":
+                X = X.astype(np.bool_)
+                self.metric = "hamming"
+            case "ranged-features":
+                self._bounds = np.vstack([np.min(X, axis=0), np.max(X, axis=0)])
 
         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:
-                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
@@ -267,7 +257,7 @@ class AIRS(BaseAIRS):
             for ai in x_class:
                 # Calculating the stimulation of memory cells with aᵢ and selecting the largest
                 # stimulation from the memory set.
-                c_match = None
+                c_match = pool_c[0]
                 match_stimulation = -1
                 for cell in pool_c:
                     stimulation = self._affinity(cell.vector, ai)
@@ -284,7 +274,7 @@ class AIRS(BaseAIRS):
 
                 set_clones: npt.NDArray = c_match.hyper_clonal_mutate(
                     int(self.rate_hypermutation * self.rate_clonal * match_stimulation),
-                    self.algorithm
+                    self._feature_type
                 )
 
                 for clone in set_clones:
@@ -302,15 +292,14 @@ class AIRS(BaseAIRS):
                     if self._affinity(c_candidate.vector, c_match.vector) < sufficiently_similar:
                         pool_c.remove(c_match)
 
-                if verbose:
-                    progress.update(1)
+                progress.update(1)
             pool_cells_classes[_class_] = pool_c
 
-        if verbose:
-            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
         return self
 
@@ -337,7 +326,7 @@ class AIRS(BaseAIRS):
             return None
 
         super()._check_and_raise_exceptions_predict(
-            X, len(self._cells_memory[self.classes[0]][0].vector), self.algorithm
+            X, len(self._cells_memory[self.classes[0]][0].vector), self._feature_type
         )
 
         c: list = []
@@ -417,7 +406,7 @@ class AIRS(BaseAIRS):
             random_index = random.randint(0, len(arb_list) - 1)
             clone_arb = arb_list[random_index].hyper_clonal_mutate(
                 int(self.rate_clonal * c_match_stimulation),
-                self.algorithm
+                self._feature_type
             )
 
             arb_list = [
@@ -446,12 +435,12 @@ class AIRS(BaseAIRS):
         antigens_list : npt.NDArray
             List of training antigens.
         """
-        if self.algorithm == "binary-features":
+        if self._feature_type == "binary-features":
             distances = pdist(antigens_list, metric="hamming")
-        elif self.metric == "minkowski":
-            distances = pdist(antigens_list, metric="minkowski", p=self.p)
         else:
-            distances = pdist(antigens_list, metric=self.metric)
+            metric_kwargs = {'p': self.p} if self.metric == 'minkowski' else {}
+            distances = pdist(antigens_list, metric=self.metric, **metric_kwargs)
+
         n = antigens_list.shape[0]
         sum_affinity = np.sum(1.0 - (distances / (1.0 + distances)))
         self.affinity_threshold = 1.0 - (sum_affinity / ((n * (n - 1)) / 2))
@@ -473,7 +462,7 @@ class AIRS(BaseAIRS):
             The stimulus rate between the vectors.
         """
         distance: float
-        if self.algorithm == "binary-features":
+        if self._feature_type == "binary-features":
             distance = hamming(u, v)
         else:
             distance = compute_metric_distance(

aisp/csa/_base.py

@@ -1,12 +1,12 @@
 """Base Class for Clonal Selection Algorithm."""
 
 from abc import ABC
-from typing import Literal
 
 import numpy as np
 import numpy.typing as npt
 
-from aisp.exceptions import FeatureDimensionMismatch
+from ..exceptions import FeatureDimensionMismatch
+from ..utils.types import FeatureType
 from ..base import BaseClassifier
 
 
@@ -20,11 +20,8 @@ class BaseAIRS(BaseClassifier, ABC):
 
     @staticmethod
     def _check_and_raise_exceptions_fit(
-        X: npt.NDArray = None,
-        y: npt.NDArray = None,
-        algorithm: Literal[
-            "continuous-features", "binary-features"
-        ] = "continuous-features"
+        X: npt.NDArray,
+        y: npt.NDArray
     ):
         """
         Verify the fit parameters and throw exceptions if the verification is not successful.
@@ -36,17 +33,11 @@ class BaseAIRS(BaseClassifier, ABC):
             [``N samples`` (rows)][``N features`` (columns)].
         y : npt.NDArray
             Array of target classes of ``X`` with [``N samples`` (lines)].
-        algorithm : Literal["continuous-features", "binary-features"], default="continuous-features"
-            Specifies the type of algorithm to use, depending on whether the input data has
-            continuous or binary features.
 
         Raises
         ------
         TypeError:
             If X or y are not ndarrays or have incompatible shapes.
-        ValueError
-            If algorithm is binary-features and X contains values that are not composed only
-            of 0 and 1.
         """
         if not isinstance(X, np.ndarray):
             if isinstance(X, list):
@@ -63,18 +54,12 @@ class BaseAIRS(BaseClassifier, ABC):
                 "X does not have the same amount of sample for the output classes in y."
             )
 
-        if algorithm == "binary-features" and not np.isin(X, [0, 1]).all():
-            raise ValueError(
-                "The array X contains values that are not composed only of 0 and 1."
-            )
 
     @staticmethod
     def _check_and_raise_exceptions_predict(
-        X: npt.NDArray = None,
+        X: npt.NDArray,
         expected: int = 0,
-        algorithm: Literal[
-            "continuous-features", "binary-features"
-        ] = "continuous-features"
+        feature_type: FeatureType = "continuous-features"
     ) -> None:
         """
         Verify the predict parameters and throw exceptions if the verification is not successful.
@@ -86,8 +71,8 @@ class BaseAIRS(BaseClassifier, ABC):
             [``N samples`` (rows)][``N features`` (columns)].
         expected : int, default=0
             Expected number of features per sample (columns in X).
-        algorithm : Literal["continuous-features", "binary-features"], default="continuous-features"
-            Specifies the type of algorithm to use, depending on whether the input data has
+        feature_type : FeatureType, default="continuous-features"
+            Specifies the type of feature_type to use, depending on whether the input data has
             continuous or binary features.
 
         Raises
@@ -97,7 +82,7 @@ class BaseAIRS(BaseClassifier, ABC):
         FeatureDimensionMismatch
             If the number of features in X does not match the expected number.
         ValueError
-            If algorithm is binary-features and X contains values that are not composed only
+            If feature_type is binary-features and X contains values that are not composed only
             of 0 and 1.
         """
         if not isinstance(X, (np.ndarray, list)):
@@ -109,7 +94,7 @@ class BaseAIRS(BaseClassifier, ABC):
                 "X"
             )
 
-        if algorithm != "binary-features":
+        if feature_type != "binary-features":
             return
 
         # Checks if matrix X contains only binary samples. Otherwise, raises an exception.

aisp/csa/_cell.py

@@ -1,12 +1,17 @@
 """Represents a memory B-cell."""
 
 from dataclasses import dataclass
-from typing import Literal
+from typing import Optional
 
 import numpy as np
 import numpy.typing as npt
 
-from ..base.mutation import clone_and_mutate_continuous, clone_and_mutate_binary
+from ..base.mutation import (
+    clone_and_mutate_continuous,
+    clone_and_mutate_binary,
+    clone_and_mutate_ranged
+)
+from ..utils.types import FeatureType
 
 
 @dataclass(slots=True)
@@ -25,7 +30,8 @@ class Cell:
     def hyper_clonal_mutate(
         self,
         n: int,
-        algorithm: Literal["continuous-features", "binary-features"] = "continuous-features"
+        feature_type: FeatureType = "continuous-features",
+        bounds: Optional[npt.NDArray[np.float64]] = None
     ) -> npt.NDArray:
         """
         Clones N features from a cell's features, generating a set of mutated vectors.
@@ -34,14 +40,22 @@ class Cell:
         ----------
         n : int
             Number of clones to be generated from mutations of the original cell.
-        algorithm : Literal["continuous-features", "binary-features"], default="continuous-features"
-            Specifies the type of algorithm to use based on the nature of the input features
+        feature_type : Literal["binary-features", "continuous-features", "ranged-features"]
+            Specifies the type of feature_type to use based on the nature of the input features
+        bounds : np.ndarray
+            Array (n_features, 2) with min and max per dimension.
 
         Returns
         -------
         npt.NDArray
             An array containing N mutated vectors from the original cell.
         """
-        if algorithm == "binary-features":
+        if feature_type == "binary-features":
             return clone_and_mutate_binary(self.vector, n)
+        if feature_type == "ranged-features" and bounds is not None:
+            clone_and_mutate_ranged(self.vector, n, bounds)
         return clone_and_mutate_continuous(self.vector, n)
+
+    def __eq__(self, other):
+        """Check if two cells are equal."""
+        return np.array_equal(self.vector, other.vector)