aisp 0.3.21__py3-none-any.whl → 0.4.1__py3-none-any.whl

aisp/__init__.py

@@ -5,9 +5,22 @@ 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
+
+Modules
+-------
+csa : Clonal Selection Algorithms.
+    Inspired by the processes of antibody proliferation and mutation.
+    - AIRS: Artificial Immune Recognition System for classification.
+    - Clonalg: Clonal Selection Algorithm for optimization.
+
+nsa : Negative Selection Algorithms
+    Simulates T cell maturation and is capable of detecting non-self cells.
+    - RNSA: Real-value Negative Selection Algorithm for classification.
+    - BNSA: Binary Negative Selection Algorithm for classification.
+
+ina : Immune Network Algorithms
+    Based on immune network theory.
+    - AiNet: Artificial Immune Network for clustering.
 
 For detailed documentation and examples, visit:
 https://ais-package.github.io/docs/intro
@@ -18,7 +31,7 @@ from . import ina
 from . import nsa
 
 __author__ = "AISP Development Team"
-__version__ = "0.3.2"
+__version__ = "0.4.0"
 __all__ = [
     'csa',
     'nsa',

aisp/base/__init__.py

@@ -1,7 +1,26 @@
-"""Base class modules."""
+"""Base Classes and Core Utilities.
+
+This module provides the fundamental classes and utilities that serve as the basis for all
+Artificial Immune Systems algorithms implemented in the AISP package.
+
+Classes
+-------
+BaseClassifier
+    Abstract Base Class for Classification Algorithms.
+BaseClusterer
+    Abstract Base Class for Clustering Algorithms.
+BaseOptimizer
+    Abstract Base Class for optimization algorithms.
+
+Functions
+---------
+set_seed_numba
+    Set Random Seed for Numba JIT Compilation.
+"""
 
 from ._base import set_seed_numba
 from ._classifier import BaseClassifier
 from ._clusterer import BaseClusterer
+from ._optimizer import BaseOptimizer
 
-__all__ = ['BaseClassifier', 'BaseClusterer', 'set_seed_numba']
+__all__ = ['BaseClassifier', 'BaseClusterer', 'BaseOptimizer', 'set_seed_numba']

aisp/base/_classifier.py

@@ -13,9 +13,11 @@ from ..utils.metrics import accuracy_score
 
 
 class BaseClassifier(ABC, Base):
-    """Base class for classification algorithms.
+    """Abstract base class for classification algorithms.
 
-    Defines the abstract methods ``fit`` and ``predict``, and implements the ``score`` method.
+    This class defines the core interface for classification models. It enforces the
+    implementation of the ``fit`` and ``predict`` methods in all derived classes,
+    and provides a default implementation of ``score`` and utility functions.
     """
 
     classes: Union[npt.NDArray, list] = []

aisp/base/_optimizer.py

@@ -0,0 +1,188 @@
+"""Base class for optimization algorithms."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import Optional, List, Any, Callable
+
+from ..utils.display import TableFormatter
+
+
+class BaseOptimizer(ABC):
+    """Abstract base class for optimization algorithms.
+
+    This class defines the core interface for optimization strategies. It keeps track of cost
+    history, evaluated solutions, and the best solution found during the optimization process.
+    Subclasses must implement ``optimize`` and ``affinity_function``.
+    """
+
+    def __init__(self) -> None:
+        self._cost_history: List[float] = []
+        self._solution_history: list = []
+        self._best_solution: Optional[Any] = None
+        self._best_cost: Optional[float] = None
+        self._protected_aliases = [
+            "__init__",
+            "optimize",
+            "register",
+            "get_report"
+        ]
+        self.mode = "min"
+
+    @property
+    def cost_history(self) -> List[float]:
+        """Return the history of costs during optimization."""
+        return self._cost_history
+
+    @property
+    def solution_history(self) -> List:
+        """Returns the history of evaluated solutions."""
+        return self._solution_history
+
+    @property
+    def best_solution(self) -> Optional[Any]:
+        """Return the best solution found so far, or ``None`` if unavailable."""
+        return self._best_solution
+
+    @property
+    def best_cost(self) -> Optional[float]:
+        """Return the cost of the best solution found so far, or ``None`` if unavailable."""
+        return self._best_cost
+
+    def _record_best(self, cost: float, best_solution: Any) -> None:
+        """Record a new cost value and update the best solution if improved.
+
+        Parameters
+        ----------
+        cost : float
+            Cost value to be added to the history.
+        """
+        self._solution_history.append(best_solution)
+        self._cost_history.append(cost)
+        is_better = (
+            self._best_cost is None or
+            (self.mode == "min" and cost < self._best_cost) or
+            (self.mode == "max" and cost > self._best_cost)
+        )
+        if is_better:
+            self._best_solution = best_solution
+            self._best_cost = cost
+
+    def get_report(self) -> str:
+        """Generate a formatted summary report of the optimization process.
+
+        The report includes the best solution, its associated cost, and the evolution of cost
+        values per iteration.
+
+        Returns
+        -------
+        report : str
+            A formatted string containing the optimization summary.
+        """
+        if not self._cost_history:
+            return "Optimization has not been run. The report is empty."
+
+        header = "\n" + "=" * 45 + "\n"
+        report_parts = [
+            header,
+            f"{'Optimization Summary':^45}",
+            header,
+            f"Best cost      : {self.best_cost}\n",
+            f"Best solution  : {self.best_solution}\n",
+            "Cost History per Iteration:\n"
+        ]
+        table_formatter = TableFormatter(
+            {
+                'Iteration': 12,
+                'Cost': 28
+            }
+        )
+
+        report_parts.extend([table_formatter.get_header()])
+
+        for i, cost in enumerate(self._cost_history, start=1):
+            report_parts.append(
+                '\n' + table_formatter.get_row(
+                    {
+                        'Iteration': f"{i:>11} ",
+                        'Cost': f"{cost:>27.6f} "
+                    }
+                )
+            )
+
+        report_parts.append(table_formatter.get_bottom(True))
+        return "".join(report_parts)
+
+    @abstractmethod
+    def optimize(self, max_iters: int = 50, n_iter_no_change=10, verbose: bool = True) -> Any:
+        """Execute the optimization process.
+
+        This abstract method must be implemented by the subclass, defining
+        how the optimization strategy explores the search space.
+
+        Parameters
+        ----------
+        max_iters : int
+            Maximum number of interactions
+        n_iter_no_change: int, default=10
+            the maximum number of iterations without updating the best
+        verbose : bool, default=True
+            Flag to enable or disable detailed output during optimization.
+
+        Returns
+        -------
+        best_solution : Any
+            The best solution found by the optimization algorithm.
+        """
+
+    @abstractmethod
+    def affinity_function(self, solution: Any) -> float:
+        """Evaluate the affinity of a candidate solution.
+
+        This abstract method must be implemented by the subclass to define the problem-specific.
+
+        Parameters
+        ----------
+        solution : Any
+            Candidate solution to be evaluated.
+
+        Returns
+        -------
+        cost : float
+            Cost value associated with the given solution.
+        """
+
+    def register(self, alias: str, function: Callable[..., Any]) -> None:
+        """Register a function dynamically in the optimizer instance.
+
+        Parameters
+        ----------
+        alias : str
+            Name used to access the function as an attribute.
+        function : Callable[..., Any]
+            Callable to be registered.
+
+        Raises
+        ------
+        TypeError
+            If `function` is not callable.
+        AttributeError
+            If `alias` is protected and cannot be modified. Or if `alias` does not exist in the
+            optimizer class.
+        """
+        if not callable(function):
+            raise TypeError(f"Expected a function for '{alias}', got {type(function).__name__}")
+        if alias in self._protected_aliases or alias.startswith("_"):
+            raise AttributeError(f"The alias '{alias}' is protected and cannot be modified.")
+        if not hasattr(self, alias):
+            raise AttributeError(
+                f"Alias '{alias}' is not a valid method of {self.__class__.__name__}"
+            )
+        setattr(self, alias, function)
+
+    def reset(self):
+        """Reset the object's internal state, clearing history and resetting values."""
+        self._cost_history: List[float] = []
+        self._solution_history: list = []
+        self._best_solution: Optional[Any] = None
+        self._best_cost: Optional[float] = None

aisp/base/mutation.py

@@ -10,10 +10,11 @@ import numpy.typing as npt
 from numba import njit, types
 
 
-@njit([(types.float64[:], types.int64)], cache=True)
+@njit([(types.float64[:], types.int64, types.float64)], cache=True)
 def clone_and_mutate_continuous(
     vector: npt.NDArray[np.float64],
-    n: int
+    n: int,
+    mutation_rate: float
 ) -> npt.NDArray[np.float64]:
     """
     Generate a set of mutated clones from a cell represented by a continuous vector.
@@ -28,6 +29,10 @@ def clone_and_mutate_continuous(
         The original immune cell with continuous values to be cloned and mutated.
     n : int
         The number of mutated clones to be generated.
+    mutation_rate : float, default=1
+        If 0 <= mutation_rate < 1: probability of mutating each component.
+        If mutation_rate >= 1 or mutation_rate <= 0: the mutation randomizes
+        a number of components between 1 and len(vector).
 
     Returns
     -------
@@ -37,12 +42,22 @@ def clone_and_mutate_continuous(
     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]
-            clone[idx] = np.float64(np.random.random())
+        if 0 <= mutation_rate < 1:
+            any_mutation = False
+            for j in range(n_features):
+                if np.random.random() < mutation_rate:
+                    clone[j] = np.random.random()
+                    any_mutation = True
+            if not any_mutation:
+                idx = np.random.randint(0, n_features)
+                clone[idx] = np.random.random()
+        else:
+            n_mutations = np.random.randint(1, n_features)
+            position_mutations = np.random.permutation(n_features)[:n_mutations]
+            for j in range(n_mutations):
+                idx = position_mutations[j]
+                clone[idx] = np.float64(np.random.random())
         clone_set[i] = clone
 
     return clone_set
@@ -75,8 +90,8 @@ def clone_and_mutate_binary(
     n_features = vector.shape[0]
     clone_set = np.empty((n, n_features), dtype=np.bool_)
     for i in range(n):
-        n_mutations = np.random.randint(1, n_features)
         clone = vector.copy()
+        n_mutations = np.random.randint(1, n_features)
         position_mutations = np.random.permutation(n_features)[:n_mutations]
         for j in range(n_mutations):
             idx = position_mutations[j]
@@ -86,11 +101,12 @@ def clone_and_mutate_binary(
     return clone_set
 
 
-@njit([(types.float64[:], types.int64, types.float64[:, :])], cache=True)
+@njit([(types.float64[:], types.int64, types.float64[:, :], types.float64)], cache=True)
 def clone_and_mutate_ranged(
     vector: npt.NDArray[np.float64],
     n: int,
-    bounds: npt.NDArray[np.float64]
+    bounds: npt.NDArray[np.float64],
+    mutation_rate: float
 ) -> npt.NDArray[np.float64]:
     """
     Generate a set of mutated clones from a cell represented by custom ranges per dimension.
@@ -107,6 +123,10 @@ def clone_and_mutate_ranged(
         The number of mutated clones to be generated.
     bounds : np.ndarray
         Array (n_features, 2) with min and max per dimension.
+    mutation_rate : float, default=1
+        If 0 <= mutation_rate < 1: probability of mutating each component.
+        If mutation_rate >= 1 or mutation_rate <= 0: the mutation randomizes
+        a number of components between 1 and len(vector).
 
     Returns
     -------
@@ -117,14 +137,62 @@ def clone_and_mutate_ranged(
     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[0][idx]
-            max_limit = bounds[1][idx]
-            clone[idx] = np.random.uniform(min_limit, max_limit)
+        if 0 <= mutation_rate < 1:
+            any_mutation = False
+            for j in range(n_features):
+                if np.random.random() < mutation_rate:
+                    clone[j] = np.random.uniform(low=bounds[0][j], high=bounds[1][j])
+                    any_mutation = True
+            if not any_mutation:
+                idx = np.random.randint(0, n_features)
+                clone[idx] = np.random.uniform(low=bounds[0][idx], high=bounds[1][idx])
+        else:
+            n_mutations = np.random.randint(1, n_features)
+            position_mutations = np.random.permutation(n_features)[:n_mutations]
+            for j in range(n_mutations):
+                idx = position_mutations[j]
+                min_limit = bounds[0][idx]
+                max_limit = bounds[1][idx]
+                clone[idx] = np.random.uniform(low=min_limit, high=max_limit)
+        clone_set[i] = clone
+
+    return clone_set
+
+
+@njit([(types.int64[:], types.int64, types.float64)], cache=True)
+def clone_and_mutate_permutation(
+    vector: npt.NDArray[np.int64],
+    n: int,
+    mutation_rate: float
+) -> npt.NDArray[np.int64]:
+    """Generate a set of mutated clones by random permutation.
+
+    Parameters
+    ----------
+    vector : npt.NDArray[np.int64]
+        The original immune cell with permutation values to be cloned and mutated.
+    n : int
+        The number of mutated clones to be generated.
+    mutation_rate : float
+        Probability of mutating each component 0 <= mutation_rate < 1.
+
+    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.int64)
+
+    for i in range(n):
+        clone = vector.copy()
+        for j in range(n_features):
+            if np.random.random() < mutation_rate:
+                idx = np.random.randint(0, n_features)
+                tmp = clone[j]
+                clone[j] = clone[idx]
+                clone[idx] = tmp
         clone_set[i] = clone
 
     return clone_set

aisp/base/populations.py

@@ -0,0 +1,49 @@
+"""Provide utility functions for generating antibody populations in immunological algorithms."""
+
+from typing import Optional
+
+import numpy as np
+import numpy.typing as npt
+
+from ..utils.types import FeatureTypeAll
+
+
+def generate_random_antibodies(
+    n_samples: int,
+    n_features: int,
+    feature_type: FeatureTypeAll = "continuous-features",
+    bounds: Optional[npt.NDArray[np.float64]] = None
+) -> npt.NDArray:
+    """
+    Generate a random antibody population.
+
+    Parameters
+    ----------
+    n_samples : int
+        Number of antibodies (samples) to generate.
+    n_features : int
+        Number of features (dimensions) for each antibody.
+    feature_type : FeatureType, default="continuous-features"
+        Specifies the type of features: "continuous-features", "binary-features",
+        "ranged-features", or "permutation-features".
+    bounds : np.ndarray
+        Array (n_features, 2) with min and max per dimension.
+
+    Returns
+    -------
+    npt.NDArray
+        Array of shape (n_samples, n_features) containing the generated antibodies.
+    """
+    if n_features <= 0:
+        raise ValueError("Number of features must be greater than zero.")
+
+    if feature_type == "binary-features":
+        return np.random.randint(0, 2, size=(n_samples, n_features)).astype(np.bool_)
+    if feature_type == "ranged-features" and bounds is not None:
+        return np.random.uniform(low=bounds[0], high=bounds[1], size=(n_samples, n_features))
+    if feature_type == "permutation-features":
+        return np.array(
+            [np.random.permutation(n_features) for _ in range(n_samples)]
+        ).astype(dtype=np.int64)
+
+    return np.random.random_sample(size=(n_samples, n_features))

aisp/csa/__init__.py

@@ -2,8 +2,19 @@
 
 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.
+
+Classes
+-------
+AIRS : Artificial Immune Recognition System.
+    A supervised learning algorithm for classification tasks based on the clonal
+    selection principle.
+Clonalg : Clonal Selection Algorithm.
+    Implementation of the clonal selection algorithm for optimization, adapted
+    for both minimization and maximization of cost functions in binary,
+    continuous, and permutation problems.
 """
 from ._ai_recognition_sys import AIRS
+from ._clonalg import Clonalg
 
 __author__ = 'João Paulo da Silva Barros'
-__all__ = ['AIRS']
+__all__ = ['AIRS', 'Clonalg']

aisp/csa/_cell.py

@@ -53,8 +53,8 @@ class Cell:
         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)
+            clone_and_mutate_ranged(self.vector, n, bounds, np.float64(1.0))
+        return clone_and_mutate_continuous(self.vector, n, np.float64(1.0))
 
     def __eq__(self, other):
         """Check if two cells are equal."""