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

aisp/csa/_clonalg.py

@@ -0,0 +1,369 @@
+"""Clonal Selection Algorithm (CLONALG)."""
+
+from __future__ import annotations
+
+import heapq
+from typing import Optional, Callable, Dict, Literal
+
+import numpy as np
+import numpy.typing as npt
+
+from ..utils.display import ProgressTable
+from ..base import BaseOptimizer, set_seed_numba
+from ..base.mutation import clone_and_mutate_binary, clone_and_mutate_ranged, \
+    clone_and_mutate_continuous, clone_and_mutate_permutation
+from ..base.populations import generate_random_antibodies
+from ..utils.sanitizers import sanitize_seed, sanitize_param, sanitize_bounds
+from ..utils.types import FeatureTypeAll
+
+
+class Clonalg(BaseOptimizer):
+    """Clonal Selection Algorithm (CLONALG).
+
+    The Clonal Selection Algorithm (CSA) is an optimization algorithm inspired by the biological
+    process of clonal selection and expansion of antibodies in the immune system [1]_. This
+    implementation of CLONALG has been adapted for the minimization or maximization of cost
+    functions in binary, continuous, ranged-value, and permutation problems.
+
+
+    Parameters
+    ----------
+    problem_size : int
+        Dimension of the problem to be minimized.
+    N : int, default=50
+        Number of memory cells (antibodies) in the population.
+    rate_clonal : float, default=10
+        Maximum number of possible clones of a cell. This value is multiplied by
+        cell_affinity to determine the number of clones.
+    rate_hypermutation : float, default=0.75
+        Rate of mutated clones, used as a scalar factor.
+    n_diversity_injection : int, default=5
+        Number of new random memory cells injected to maintain diversity.
+    selection_size : int, default=5
+        Number of the best antibodies selected for cloning.
+    affinity_function : Optional[Callable[..., npt.NDArray]], default=None
+        Objective function to evaluate candidate solutions in minimizing the problem.
+    feature_type : FeatureTypeAll, default='ranged-features'
+        Type of problem samples: binary, continuous, or based on value ranges.
+        Specifies the type of features: "continuous-features", "binary-features",
+        "ranged-features", or "permutation-features".
+    bounds : Optional[Dict], default=None
+        Definition of search limits when ``feature_type='ranged-features'``.
+        Can be provided in two ways:
+
+        * Fixed values: ``{'low': float, 'high': float}``
+            Values are replicated across all dimensions, generating equal limits for each
+            dimension.
+        * Arrays: ``{'low': list, 'high': list}``
+            Each dimension has specific limits. Both arrays must be
+            ``problem_size``.
+
+    mode : Literal["min", "max"], default="min"
+        Defines whether the algorithm minimizes or maximizes the cost function.
+    seed : Optional[int], default=None
+        Seed for random generation of detector values. If None, the value is random.
+
+    Notes
+    -----
+    This CLONALG implementation contains some changes based on the AISP context, for general
+    application to various problems, which may produce results different from the standard or
+    specific implementation. This adaptation aims to generalize CLONALG to minimization and
+    maximization tasks, in addition to supporting continuous, discrete, and permutation problems.
+
+    References
+    ----------
+    .. [1] BROWNLEE, Jason. Clonal Selection Algorithm. Clever Algorithms: Nature-inspired
+    Programming Recipes., 2011. Available at:
+    https://cleveralgorithms.com/nature-inspired/immune/clonal_selection_algorithm.html
+    """
+
+    def __init__(
+        self,
+        problem_size: int,
+        N: int = 50,
+        rate_clonal: int = 10,
+        rate_hypermutation: float = 0.75,
+        n_diversity_injection: int = 5,
+        selection_size: int = 5,
+        affinity_function: Optional[Callable[..., npt.NDArray]] = None,
+        feature_type: FeatureTypeAll = 'ranged-features',
+        bounds: Optional[Dict] = None,
+        mode: Literal["min", "max"] = "min",
+        seed: Optional[int] = None
+    ):
+        super().__init__()
+        self.problem_size = sanitize_param(problem_size, 1, lambda x: x > 0)
+        self.N: int = sanitize_param(N, 50, lambda x: x > 0)
+        self.rate_clonal: int = sanitize_param(rate_clonal, 10, lambda x: x > 0)
+        self.rate_hypermutation: np.float64 = np.float64(
+            sanitize_param(
+                rate_hypermutation, 0.75, lambda x: x > 0
+            )
+        )
+        self.n_diversity_injection: int = sanitize_param(
+            n_diversity_injection, 5, lambda x: x > 0
+        )
+        self.selection_size: int = sanitize_param(
+            selection_size, 5, lambda x: x > 0
+        )
+        self._affinity_function = affinity_function
+        self.feature_type: FeatureTypeAll = feature_type
+
+        self._bounds = None
+        self._bounds_extend_cache = None
+        self.bounds = bounds
+
+        self.mode: Literal["min", "max"] = sanitize_param(
+            mode,
+            "min",
+            lambda x: x == "max"
+        )
+
+        self.seed: Optional[int] = sanitize_seed(seed)
+        if self.seed is not None:
+            np.random.seed(self.seed)
+            set_seed_numba(self.seed)
+
+        self.population = None
+
+    @property
+    def bounds(self) -> Optional[Dict]:
+        """Getter for the bounds attribute."""
+        return self._bounds
+
+    @bounds.setter
+    def bounds(self, value: Optional[Dict]):
+        """Setter for the bounds attribute."""
+        if self.feature_type == 'ranged-features':
+            self._bounds = sanitize_bounds(value, self.problem_size)
+            low_bounds = np.array(self._bounds['low'])
+            high_bounds = np.array(self._bounds['high'])
+            self._bounds_extend_cache = np.array([low_bounds, high_bounds])
+        else:
+            self._bounds = None
+            self._bounds_extend_cache = None
+
+    def optimize(
+        self,
+        max_iters: int = 50,
+        n_iter_no_change=10,
+        verbose: bool = True
+    ) -> npt.NDArray:
+        """Execute the optimization process and return the population.
+
+        Parameters
+        ----------
+        max_iters : int, default=50
+            Maximum number of interactions when searching for the best solution using clonalg.
+        n_iter_no_change: int, default=10
+            the maximum number of iterations without updating the best cell
+        verbose : bool, default=True
+            Feedback on interactions, indicating the best antibody.
+
+        Returns
+        -------
+        population : npt.NDArray
+            Antibody population after clonal expansion.
+        """
+        self.reset()
+        self.population = self._init_population_antibodies()
+
+        t = 1
+        antibodies = [(antibody, self.affinity_function(antibody)) for antibody in self.population]
+        best_cost = None
+        stop = 0
+        progress = ProgressTable(
+            {
+                "Iteration": 11,
+                f"Best Affinity ({self.mode})": 25,
+                "Worse Affinity": 20,
+                "Stagnation": 17},
+            verbose
+        )
+
+        while t <= max_iters:
+            p_select = self._select_top_antibodies(self.selection_size, antibodies)
+            self._record_best(p_select[0][1], p_select[0][0])
+
+            clones = self._clone_and_hypermutation(p_select)
+
+            p_rand = [
+                (antibody, self.affinity_function(antibody))
+                for antibody in self._diversity_introduction()
+            ]
+            antibodies = p_select
+            antibodies.extend(clones)
+            antibodies = self._select_top_antibodies(
+                self.N - self.n_diversity_injection, antibodies
+            )
+            antibodies.extend(p_rand)
+            if len(antibodies) > self.N:
+                antibodies = self._select_top_antibodies(self.N, antibodies)
+            if best_cost == self.best_cost:
+                stop += 1
+            else:
+                stop = 0
+                best_cost = self.best_cost
+            progress.update(
+                {
+                    "Iteration": t,
+                    f"Best Affinity ({self.mode})": f"{self.best_cost:>25.6f}",
+                    "Worse Affinity": f"{antibodies[-1][1]:>20.6f}",
+                    "Stagnation": stop
+                }
+            )
+            if stop == n_iter_no_change:
+                break
+
+            t += 1
+        progress.finish()
+        self.population = np.array([antibody for antibody, _ in antibodies]).astype(dtype=float)
+        return self.population
+
+    def _select_top_antibodies(self, n: int, antibodies: list[tuple]) -> list[tuple]:
+        """Select the antibodies with the highest or lowest values, depending on the mode.
+
+        Parameters
+        ----------
+        n : int
+            Number of antibodies to select.
+        antibodies : list[tuple]
+            Representing the antibodies and their associated score.
+
+        Returns
+        -------
+            List containing the `n` antibodies selected according to the defined min or max
+            criterion.
+        """
+        if self.mode == "max":
+            return heapq.nlargest(n, antibodies, key=lambda x: x[1])
+
+        return heapq.nsmallest(n, antibodies, key=lambda x: x[1])
+
+    def affinity_function(self, solution: npt.NDArray) -> np.float64:
+        """
+        Evaluate the affinity of a candidate cell.
+
+        Parameters
+        ----------
+        solution : npt.NDArray
+            Candidate solution to evaluate.
+
+        Returns
+        -------
+        affinity : float
+            Affinity value associated with the given cell.
+
+        Raises
+        ------
+        NotImplementedError
+            If no affinity function has been provided.
+        """
+        if not callable(self._affinity_function):
+            raise NotImplementedError(
+                "No affinity function to evaluate the candidate cell was provided."
+            )
+        return np.float64(self._affinity_function(solution))
+
+    def _init_population_antibodies(self) -> npt.NDArray:
+        """Initialize the antibody set of the population randomly.
+
+        Returns
+        -------
+        npt.NDArray
+            List of initialized antibodies.
+        """
+        return generate_random_antibodies(
+            self.N,
+            self.problem_size,
+            self.feature_type,
+            self._bounds_extend_cache
+        )
+
+    def _diversity_introduction(self):
+        """Introduce diversity into the antibody population.
+
+        Returns
+        -------
+        npt.NDArray
+            Array of new random antibodies for diversity introduction.
+        """
+        return generate_random_antibodies(
+            self.n_diversity_injection,
+            self.problem_size,
+            self.feature_type,
+            self._bounds_extend_cache
+        )
+
+    def _clone_and_mutate(
+        self,
+        antibody: npt.NDArray,
+        n_clone: int,
+        rate_hypermutation: float
+    ) -> npt.NDArray:
+        """
+        Generate mutated clones from an antibody, based on the feature type.
+
+        Parameters
+        ----------
+        antibody : npt.NDArray
+            Original antibody vector to be cloned and mutated.
+        n_clone : int
+            Number of clones to generate.
+
+        Returns
+        -------
+        npt.NDArray
+            Array of shape (n_clone, len(antibody)) containing mutated clones
+        """
+        if self.feature_type == "binary-features":
+            return clone_and_mutate_binary(antibody, n_clone)
+        if self.feature_type == "ranged-features" and self._bounds_extend_cache is not None:
+            return clone_and_mutate_ranged(
+                antibody, n_clone, self._bounds_extend_cache, rate_hypermutation
+            )
+        if self.feature_type == "permutation-features":
+            return clone_and_mutate_permutation(antibody, n_clone, rate_hypermutation)
+        return clone_and_mutate_continuous(antibody, n_clone, rate_hypermutation)
+
+    def _clone_and_hypermutation(
+        self,
+        population: list[tuple]
+    ) -> list:
+        """Clone and hypermutate the population's antibodies.
+
+        The clone list is returned with the clones and their affinities with respect to the cost
+        function.
+
+        Parameters
+        ----------
+        population: list
+            The list of antibodies (solutions) to be evaluated and cloned.
+
+        Returns
+        -------
+        list[npt.NDArray]
+            List of mutated clones.
+        """
+        clonal_m = []
+        min_affinity = min(item[1] for item in population)
+        max_affinity = max(item[1] for item in population)
+        affinity_range = max_affinity - min_affinity
+
+        for antibody, affinity in population:
+            if affinity_range == 0:
+                normalized_affinity = 1
+            else:
+                normalized_affinity = (affinity - min_affinity) / affinity_range
+                if self.mode == "min":
+                    normalized_affinity = max(0.0, 1.0 - normalized_affinity)
+
+            num_clones = max(0, int(self.rate_clonal * normalized_affinity))
+            clones = self._clone_and_mutate(
+                antibody,
+                num_clones,
+                1 - np.exp(-self.rate_hypermutation * normalized_affinity)
+            )
+            clonal_m.extend(clones)
+
+        return [(clone, self.affinity_function(clone)) for clone in clonal_m]

aisp/ina/__init__.py

@@ -4,8 +4,8 @@ This module implements algorithms based on Network Theory Algorithms proposed by
 
 Classes
 -------
-AiNet
-    Artificial Immune Network implementation for clustering.
+AiNet : Artificial Immune Network.
+    An unsupervised learning algorithm for clustering, based on the theory of immune networks.
 """
 
 from ._ai_network import AiNet

aisp/ina/_ai_network.py

@@ -16,6 +16,7 @@ from ._base import BaseAiNet
 from ..base import set_seed_numba
 from ..base.mutation import clone_and_mutate_binary, clone_and_mutate_continuous, \
     clone_and_mutate_ranged
+from ..base.populations import generate_random_antibodies
 from ..utils.distance import hamming, compute_metric_distance, get_metric_code
 from ..utils.sanitizers import sanitize_choice, sanitize_param, sanitize_seed
 from ..utils.types import FeatureType, MetricType
@@ -293,7 +294,7 @@ class AiNet(BaseAiNet):
         npt.NDArray
             List of initialized memories.
         """
-        return self._generate_random_antibodies(
+        return generate_random_antibodies(
             self.N,
             self._n_features,
             self._feature_type,
@@ -402,7 +403,7 @@ class AiNet(BaseAiNet):
         npt.NDArray
             Array of new random antibodies for diversity introduction.
         """
-        return self._generate_random_antibodies(
+        return generate_random_antibodies(
             self.n_diversity_injection,
             self._n_features,
             self._feature_type,
@@ -478,8 +479,8 @@ class AiNet(BaseAiNet):
         if self._feature_type == "binary-features":
             return clone_and_mutate_binary(antibody, n_clone)
         if self._feature_type == "ranged-features" and self._bounds is not None:
-            return clone_and_mutate_ranged(antibody, n_clone, self._bounds)
-        return clone_and_mutate_continuous(antibody, n_clone)
+            return clone_and_mutate_ranged(antibody, n_clone, self._bounds, np.float64(1.0))
+        return clone_and_mutate_continuous(antibody, n_clone, np.float64(1.0))
 
     def _build_mst(self):
         """Construct the Minimum Spanning Tree (MST) for the antibody population.

aisp/ina/_base.py

@@ -1,7 +1,6 @@
 """Base Class for Network Theory Algorithms."""
 
 from abc import ABC
-from typing import Optional
 
 import numpy as np
 from numpy import typing as npt
@@ -82,42 +81,3 @@ class BaseAiNet(BaseClusterer, ABC):
             raise ValueError(
                 "The array X contains values that are not composed only of 0 and 1."
             )
-
-    @staticmethod
-    def _generate_random_antibodies(
-        n_samples: int,
-        n_features: int,
-        feature_type: FeatureType = "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",
-            or "ranged-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.
-            Data type depends on the feature_type type (float for continuous/ranged, bool for
-            binary).
-        """
-        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))
-
-        return np.random.random_sample(size=(n_samples, n_features))

aisp/nsa/__init__.py

@@ -3,6 +3,13 @@
 NSAs simulate the maturation process of T-cells in the immune system, where these cells learn to 
 distinguish between self and non-self. Only T-cells capable of recognizing non-self elements are 
 preserved.
+
+Classes
+-------
+RNSA : Real-valued Negative Selection Algorithm.
+    A supervised learning algorithm for classification that uses real-valued detectors.
+BNSA : Binary Negative Selection Algorithm.
+    A supervised learning algorithm for classification that uses binary detectors.
 """
 
 from ._binary_negative_selection import BNSA

aisp/utils/display.py

@@ -0,0 +1,185 @@
+"""Utility functions for displaying algorithm information."""
+
+from __future__ import annotations
+
+import locale
+import sys
+import time
+from typing import Mapping, Union
+
+
+def _supports_box_drawing() -> bool:
+    """
+    Check if the terminal supports boxed characters.
+
+    Returns
+    -------
+    bool
+        True if the terminal likely supports boxed characters, False otherwise.
+    """
+    enc = (sys.stdout.encoding or locale.getpreferredencoding(False)).lower()
+    if not enc.startswith("utf"):
+        return False
+    try:
+        "┌".encode(enc)
+    except UnicodeEncodeError:
+        return False
+    return True
+
+
+class TableFormatter:
+    """
+    Format tabular data into strings for display in the console.
+
+    Parameters
+    ----------
+    headers : Mapping[str, int]
+        Mapping of column names to their respective widths, in the format
+        {column_name: column_width}.
+    """
+
+    def __init__(self, headers: Mapping[str, int]) -> None:
+        if not headers or not isinstance(headers, Mapping):
+            raise ValueError("'headers' must be a non-empty dictionary.")
+        self.headers: Mapping[str, int] = headers
+        self._ascii_only = not _supports_box_drawing()
+
+    def _border(self, left: str, middle: str, right: str, line: str, new_line: bool = True) -> str:
+        """
+        Create a horizontal border for the table.
+
+        Parameters
+        ----------
+        left: str
+            Character on the left side of the border.
+        middle: str
+            Character separator between columns.
+        right: str
+            Character on the right side of the border.
+        line: str
+            Character used to fill the border.
+        new_line: bool, optional
+            If True, adds a line break before the border (default is True).
+
+        Returns
+        -------
+        str
+            String representing the horizontal border.
+        """
+        nl = '\n' if new_line else ''
+        return f"{nl}{left}{middle.join(line * w for w in self.headers.values())}{right}"
+
+    def get_header(self):
+        """
+        Generate the table header, including the top border, column headings, and separator line.
+
+        Returns
+        -------
+        str
+            Formatted string of the table header.
+        """
+        if self._ascii_only:
+            top = self._border("+", "+", "+", "-")
+            sep = self._border("+", "+", "+", "-")
+            cell_border = "|"
+        else:
+            top = self._border("┌", "┬", "┐", "─")
+            sep = self._border("├", "┼", "┤", "─")
+            cell_border = "│"
+
+        titles = '\n' + cell_border + cell_border.join(
+            f"{h:^{self.headers[h]}}" for h in self.headers
+        ) + cell_border
+
+        return top + titles + sep
+
+    def get_row(self, values: Mapping[str, Union[str, int, float]]):
+        """
+        Generate a formatted row for the table data.
+
+        Parameters
+        ----------
+        values : Mapping[str, Union[str, int, float]]
+            Dictionary with values for each column, in the format
+            {column_name: value}.
+
+        Returns
+        -------
+        str
+        Formatted string of the table row.
+        """
+        border = "|" if self._ascii_only else "│"
+        row = border + border.join(
+            f"{values.get(h, ''):^{self.headers[h]}}" for h in self.headers
+        ) + border
+
+        return row
+
+    def get_bottom(self, new_line: bool = False):
+        """
+        Generate the table's bottom border.
+
+        Parameters
+        ----------
+        new_line : bool, Optional
+            If True, adds a line break before the border (default is False).
+
+        Returns
+        -------
+        str
+            Formatted string for the bottom border.
+        """
+        if self._ascii_only:
+            bottom = self._border("+", "+", "+", "-", new_line)
+        else:
+            bottom = self._border("└", "┴", "┘", "─", new_line)
+        return bottom
+
+
+class ProgressTable(TableFormatter):
+    """
+    Display a formatted table in the console to track the algorithm's progress.
+
+    Parameters
+    ----------
+    headers : Mapping[str, int]
+        Mapping {column_name: column_width}.
+    verbose : bool, default=True
+        If False, prints nothing to the terminal.
+    """
+
+    def __init__(self, headers: Mapping[str, int], verbose: bool = True) -> None:
+        super().__init__(headers)
+        if not headers or not isinstance(headers, Mapping):
+            raise ValueError("'headers' must be a non-empty dictionary.")
+        self.verbose: bool = verbose
+        self.headers: Mapping[str, int] = headers
+        self._ascii_only = not _supports_box_drawing()
+        if self.verbose:
+            self._print_header()
+            self._start = time.perf_counter()
+
+    def _print_header(self) -> None:
+        """Print the table header."""
+        print(self.get_header())
+
+    def update(self, values: Mapping[str, Union[str, int, float]]) -> None:
+        """
+        Add a new row of values to the table.
+
+        Parameters
+        ----------
+        values: Mapping[str, Union[str, int, float]]
+            Keys must match the columns defined in headers.
+        """
+        if not self.verbose:
+            return
+        print(self.get_row(values))
+
+    def finish(self) -> None:
+        """End the table display, printing the bottom border and total time."""
+        if not self.verbose:
+            return
+
+        print(self.get_bottom())
+        print(f"Total time: {time.perf_counter() - self._start:.6f} seconds")