aisp 0.1.34__tar.gz → 0.1.40__tar.gz

{aisp-0.1.34 → aisp-0.1.40}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: aisp
-Version: 0.1.34
+Version: 0.1.40
 Summary: Package with techniques of artificial immune systems.
 Author-email: João Paulo da Silva Barros <jpsilvabarr@gmail.com>
 Maintainer-email: Alison Zille Lopes <alisonzille@gmail.com>
@@ -9,18 +9,21 @@ Project-URL: Homepage, https://ais-package.github.io/
 Project-URL: Documentation, https://ais-package.github.io/docs/intro
 Project-URL: Source Code, https://github.com/AIS-Package/aisp
 Project-URL: Tracker, https://github.com/AIS-Package/aisp/issues
-Keywords: Artificial Immune Systems,classification,Natural computing,machine learning,artificial intelligence
+Keywords: Artificial Immune Systems,classification,Natural computing,machine learning,artificial intelligence,AIS
 Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python
 Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.8
-Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
-Requires-Python: >=3.8.10
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: numpy>=1.22.4
+Requires-Dist: numba>=0.59.0
 Requires-Dist: scipy>=1.8.1
 Requires-Dist: tqdm>=4.64.1
 Dynamic: license-file
@@ -39,7 +42,7 @@ Dynamic: license-file
 <div class='language-options'>
 
 * [English.](#english)
-* [Português.](#português)
+* [Português.](https://ais-package.github.io/pt-br/docs/intro)
 
 </div>
 
@@ -52,11 +55,6 @@ Dynamic: license-file
 ---
 
 <section id='english'>
-<div align = center> 
-
-## English
-
-</div>
 
 #### Summary:
 
@@ -91,7 +89,7 @@ Artificial Immune Systems (AIS) are inspired by the vertebrate immune system, cr
 
 #### **Installation**
 
-The module requires installation of [python 3.8.10](https://www.python.org/downloads/) or higher.
+The module requires installation of [python 3.10](https://www.python.org/downloads/) or higher.
 
 <section id='dependencies'>
 
@@ -104,6 +102,7 @@ The module requires installation of [python 3.8.10](https://www.python.org/downl
 |    numpy      |    ≥ 1.22.4   |
 |    scipy      |    ≥ 1.8.1    |
 |    tqdm       |    ≥ 4.64.1   |
+|    numba      |    ≥ 0.59.0   |
 
 </div>
 
@@ -144,104 +143,5 @@ Below are some examples that use a database for classification with the [Jupyter
 
 ---
 
-
-</section>
-</section>
-
----
-
-<section id='português'>
-<div align = center> 
-
-## Português
-
-</div>
-
-#### Sumário:
-
-> 1. [Introdução.](#introdução)
-> 2. [Instalação.](#instalação)
->    1. [Dependências](#dependências)
->    2. [Instalação do usuário](#instalação-do-usuário)
-> 3. [Exemplos.](#exemplos)
-
----
-<section id='introdução'>
-
-#### Introdução
-
-O **AISP** é um pacote python que implementa as técnicas dos sistemas imunológicos artificiais, distribuído sob a licença GNU Lesser General Public License v3.0 (LGPLv3).
-
-O pacote teve início no ano de **2022** como um pacote de pesquisa no instituto federal do norte de minas gerais - campus salinas (**IFNMG - Salinas**).
-
-Os sistemas imunológicos artificiais (SIA) inspiram-se no sistema imunológico dos vertebrados, criando metáforas que aplicam a capacidade de reconhecer e catalogar os patógenos, entre outras características desse sistema.
-
-##### Algoritmos implementados:
-
-> - [x] [**Seleção Negativa.**](https://ais-package.github.io/docs/aisp-techniques/Negative%20Selection/)
-> - [ ] *Algoritmos de Seleção Clonal.*
-> - [ ] *Células Dendríticas.*
-> - [ ] *Teoria da Rede Imune.*
-
-</section>
-
-<section id='introdução'>
-
-#### **Instalação**
-
-
-O módulo requer a instalação do [python 3.8.10](https://www.python.org/downloads/) ou superior.
-
-<section id='dependências'>
-
-##### **Dependências:**
-<div align = center> 
-
-|    Pacotes    |     Versão    |
-|:-------------:|:-------------:|
-|    numpy      |    ≥ 1.22.4   |
-|    scipy      |    ≥ 1.8.1    |
-|    tqdm       |    ≥ 4.64.1   |
-
-</div>
-</section>
-
-<section id='instalação-do-usuário'>
-
-##### **Instalação do usuário**
-
-A maneira mais simples de instalação do AISP é utilizando o ``pip``:
-
-```Bash
-pip install aisp
-```
-
-</section>
-
-</section>
-<section id='exemplos'>
-
-#### Exemplos:
-
----
-
-##### Exemplo utilizando a técnica de seleção negativa (**nsa**):
-
-No exemplo presente nesse [notebook](https://github.com/AIS-Package/aisp/blob/main/examples/RNSA/example_with_randomly_generated_dataset-pt.ipynb), gerando **500** amostras aleatórias dispostas em dois grupos um para cada classe.
-
-A seguir alguns exemplos que utiliza-se de base de dados para classificação com a ferramenta [Jupyter notebook](https://jupyter.org/).
-
-#### **Seleção Negativa:**
-
-+ **RNSA** Aplicação das tecnica de seleção negativa para classificação utilizando a base de dados de flores da família Iris e Old Faithful Geyser:
-    + [iris_dataBase_example](https://github.com/AIS-Package/aisp/blob/main/examples/RNSA/iris_dataBase_example_pt-br.ipynb)
-    + [geyser_dataBase_example](https://github.com/AIS-Package/aisp/blob/main/examples/RNSA/geyser_dataBase_example_pt-br.ipynb)
-
-+ **BNSA** 
-    + [mushrooms_dataBase_example](https://github.com/AIS-Package/aisp/blob/main/examples/BNSA/mushrooms_dataBase_example_en.ipynb)
-
-
----
-
 </section>
 </section>

aisp-0.1.40/README.md

@@ -0,0 +1,117 @@
+<div align = center> 
+
+|    <img src='https://ais-package.github.io/assets/images/logo-7b415c6841a3ed8a760eff38ecd996b8.svg'/>   |     <h1 class='text-title' align=center>**Artificial Immune Systems Package.**</h1>  |
+|:-------------:|:-------------:|
+
+</div>
+
+---
+
+#### Select the language / Selecione o Idioma:
+
+<div class='language-options'>
+
+* [English.](#english)
+* [Português.](https://ais-package.github.io/pt-br/docs/intro)
+
+</div>
+
+#### Package documentation / Documentação do pacote:
+
+* [Docs.](https://ais-package.github.io/docs/intro)
+
+* [Wiki Github.](https://github.com/AIS-Package/aisp/wiki)
+
+---
+
+<section id='english'>
+
+#### Summary:
+
+> 1. [Introduction.](#introduction)
+> 2. [Installation.](#installation)
+>    1. [Dependencies](#dependencies)
+>    2. [User installation](#user-installation)
+> 3. [Examples.](#examples)
+
+---
+<section id='introduction'>
+
+#### Introduction
+
+The **AISP** is a python package that implements artificial immune systems techniques, distributed under the GNU Lesser General Public License v3.0 (LGPLv3).
+
+The package started in **2022** as a research package at the Federal Institute of Northern Minas Gerais - Salinas campus (**IFNMG - Salinas**).
+
+
+Artificial Immune Systems (AIS) are inspired by the vertebrate immune system, creating metaphors that apply the ability to detect and catalog pathogens, among other features of this system.
+
+##### Algorithms implemented:
+
+> - [x] [**Negative Selection.**](https://ais-package.github.io/docs/aisp-techniques/Negative%20Selection/)
+> - [ ] *Clonal Selection Algorithms.*
+> - [ ] *Dendritic Cells.*
+> - [ ] *Immune Network Theory.*
+
+</section>
+
+<section id='installation'>
+
+#### **Installation**
+
+The module requires installation of [python 3.10](https://www.python.org/downloads/) or higher.
+
+<section id='dependencies'>
+
+##### **Dependencies:**
+<div align = center> 
+
+
+|    Packages   |     Version   |
+|:-------------:|:-------------:|
+|    numpy      |    ≥ 1.22.4   |
+|    scipy      |    ≥ 1.8.1    |
+|    tqdm       |    ≥ 4.64.1   |
+|    numba      |    ≥ 0.59.0   |
+
+</div>
+
+</section>
+<section id='user-installation'>
+
+##### **User installation**
+
+The simplest way to install AISP is using ``pip``:
+
+```Bash
+pip install aisp
+```
+
+</section>
+
+</section>
+<section id='examples'>
+
+#### Examples:
+
+---
+
+##### Example using the negative selection technique (**nsa**):
+
+In the example present in this [notebook](https://github.com/AIS-Package/aisp/blob/main/examples/RNSA/example_with_randomly_generated_dataset-en.ipynb), **500** random samples were generated, arranged in two groups, one for each class.
+
+Below are some examples that use a database for classification with the [Jupyter notebook](https://jupyter.org/) tool.
+
+
+##### **Negative Selection:**
+
++ **RNSA** Application of negative selection techniques for classification using the Iris family flower database and Old Faithful Geyser:
+    + [iris_dataBase_example](https://github.com/AIS-Package/aisp/blob/main/examples/RNSA/iris_dataBase_example_en.ipynb)
+    + [geyser_dataBase_example](https://github.com/AIS-Package/aisp/blob/main/examples/RNSA/geyser_dataBase_example_en.ipynb)
++ **BNSA** 
+    + [mushrooms_dataBase_example](https://github.com/AIS-Package/aisp/blob/main/examples/BNSA/mushrooms_dataBase_example_en.ipynb)
+
+---
+
+</section>
+</section>

aisp-0.1.40/aisp/__init__.py

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

aisp-0.1.40/aisp/base/__init__.py

@@ -0,0 +1,4 @@
+"""Base class modules."""
+from ._classifier import BaseClassifier
+
+__all__ = ['BaseClassifier']

aisp-0.1.40/aisp/base/_classifier.py

@@ -0,0 +1,90 @@
+"""Base class for classification algorithm."""
+
+from abc import ABC, abstractmethod
+from typing import Optional
+
+import numpy.typing as npt
+
+from ..utils.metrics import accuracy_score
+
+
+class BaseClassifier(ABC):
+    """
+    Base class for classification algorithms, defining the abstract methods ``fit`` and ``predict``,
+    and implementing the ``get_params`` method.
+    """
+
+    @abstractmethod
+    def fit(self, X: npt.NDArray, y: npt.NDArray, verbose: bool = True):
+        """
+        Function to train the model using the input data ``X`` and corresponding labels ``y``.
+
+        This abstract method is implemented by the class that inherits it.
+
+        Parameters
+        ----------
+        * X (``npt.NDArray``): Input data used for training the model, previously normalized to the
+            range [0, 1].
+        * y (``npt.NDArray``): Corresponding labels or target values for the input data.
+        * verbose (``bool``, optional): Flag to enable or disable detailed output during training.
+            Default is ``True``.
+
+        Returns
+        ----------
+        * self: Returns the instance of the class that implements this method.
+        """
+
+    @abstractmethod
+    def predict(self, X) -> Optional[npt.NDArray]:
+        """
+        Function to 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 values for each input sample, or
+            ``None`` if the prediction fails.
+        """
+
+    def score(self, X: npt.NDArray, y: list) -> float:
+        """
+        Score function calculates forecast accuracy.
+
+        Details
+        ----------
+        This function performs the prediction of X and checks how many elements are equal
+        between vector y and y_predicted. This function was added for compatibility with some
+        scikit-learn functions.
+
+        Parameters
+        ----------
+        * X (``np.ndarray``):
+            Feature set with shape (n_samples, n_features).
+        * y (``np.ndarray``):
+            True values with shape (n_samples,).
+
+        Returns
+        ----------
+        * accuracy (``float``): The accuracy of the model.
+        """
+        if len(y) == 0:
+            return 0
+        y_pred = self.predict(X)
+        return accuracy_score(y, y_pred)
+
+    def get_params(self, deep: bool = True) -> dict:  # pylint: disable=W0613
+        """
+        The get_params function Returns a dictionary with the object's main parameters.
+
+        This function is required to ensure compatibility with scikit-learn functions.
+        """
+        return {
+            key: value
+            for key, value in self.__dict__.items()
+            if not key.startswith("_")
+        }

aisp-0.1.40/aisp/exceptions.py

@@ -0,0 +1,42 @@
+"""Custom warnings and errors"""
+
+
+class MaxDiscardsReachedError(Exception):
+    """Exception thrown when the maximum number of detector discards is reached."""
+
+    def __init__(self, _class_, message=None):
+        if message is None:
+            message = (
+                "An error has been identified:\n"
+                f"the maximum number of discards of detectors for the {_class_} class "
+                "has been reached.\nIt is recommended to check the defined radius and "
+                "consider reducing its value."
+            )
+
+        super().__init__(message)
+
+
+class FeatureDimensionMismatch(Exception):
+    """ 
+    Exception raised when the number of input features does not match the expected number 
+    required by the model for prediction
+    """
+
+    def __init__(
+            self,
+            expected: int,
+            received: int,
+            variable_name: str = None
+    ):
+        parts = []
+        if variable_name:
+            parts.append(f"In variable '{variable_name}'")
+
+        parts.append("feature dimension mismatch")
+
+        message = (
+            f"{' '.join(parts)}: expected {expected} features, but received {received}. "
+            "Please ensure the input data has the correct number of features "
+            "and matches the expected shape for the model."
+        )
+        super().__init__(message)

aisp-0.1.40/aisp/nsa/__init__.py

@@ -0,0 +1,11 @@
+"""nsa: Module (NSA) Negative Selection Algorithm
+
+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.
+"""
+from ._negative_selection import BNSA, RNSA
+
+__author__ = "João Paulo da Silva Barros"
+__all__ = ["RNSA", "BNSA"]
+__version__ = "0.1.40"

aisp-0.1.40/aisp/nsa/_base.py

@@ -0,0 +1,118 @@
+"""Base Class for Negative Selection Algorithm."""
+
+from abc import ABC
+from dataclasses import dataclass
+from typing import Literal, Optional
+
+import numpy as np
+import numpy.typing as npt
+
+from ..base import BaseClassifier
+from ..exceptions import FeatureDimensionMismatch
+
+
+class BaseNSA(BaseClassifier, ABC):
+    """
+    The base class contains functions that are used by more than one class in the package, and
+    therefore are considered essential for the overall functioning of the system.
+    """
+
+    @staticmethod
+    def _check_and_raise_exceptions_fit(
+        X: npt.NDArray = None,
+        y: npt.NDArray = None,
+        _class_: Literal["RNSA", "BNSA"] = "RNSA",
+    ) -> None:
+        """
+        Function responsible for verifying fit function parameters and throwing exceptions if the
+        verification is not successful.
+
+        Parameters
+        ----------
+        * X (``npt.NDArray``) Training array, containing the samples and their
+            characteristics, [``N samples`` (rows)][``N features`` (columns)].
+        * y (``npt.NDArray``) Array of target classes of ``X`` with [``N samples`` (lines)].
+        * _class_ (``Literal[RNSA, BNSA], optional``) Current class. Defaults to 'RNSA'.
+
+        Raises
+        ----------
+        * TypeError: If X or y are not ndarrays or have incompatible shapes.
+        * ValueError: If _class_ is BNSA and X contains values that are not composed only of
+            0 and 1.
+        """
+        if isinstance(X, list):
+            X = np.array(X)
+        if isinstance(y, list):
+            y = np.array(y)
+
+        if not isinstance(X, np.ndarray):
+            raise TypeError("X is not an ndarray or list.")
+        if not isinstance(y, np.ndarray):
+            raise TypeError("y is not an ndarray or list.")
+
+        if X.shape[0] != y.shape[0]:
+            raise TypeError(
+                "X does not have the same amount of sample for the output classes in y."
+            )
+
+        if _class_ == "BNSA" 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,
+        expected: int = 0,
+        _class_: Literal["RNSA", "BNSA"] = "RNSA",
+    ) -> None:
+        """
+        Function responsible for verifying predict function parameters and throwing exceptions if
+        the verification is not successful.
+
+        Parameters
+        ----------
+        * X (``npt.NDArray``)
+            Input array for prediction, containing the samples and their characteristics,
+            [``N samples`` (rows)][``N features`` (columns)].
+        * expected (``int``)
+            Expected number of features per sample (columns in X).
+        * _class_ (``Literal[RNSA, BNSA], optional``)
+            Current class. Defaults to 'RNSA'.
+
+        Raises
+        ----------
+        * TypeError: If X is not an ndarray or list.
+        * FeatureDimensionMismatch: If the number of features in X does not match the expected
+            number.
+        * ValueError: If _class_ is BNSA and X contains values that are not composed only of 0
+        and 1.
+        """
+        if not isinstance(X, (np.ndarray, list)):
+            raise TypeError("X is not an ndarray or list")
+        if expected != len(X[0]):
+            raise FeatureDimensionMismatch(expected, len(X[0]), "X")
+
+        if _class_ != "BNSA":
+            return
+
+        # Checks if matrix X contains only binary samples. Otherwise, raises an exception.
+        if not np.isin(X, [0, 1]).all():
+            raise ValueError(
+                "The array X contains values that are not composed only of 0 and 1."
+            )
+
+
+@dataclass(slots=True)
+class Detector:
+    """
+    Represents a non-self detector of the RNSA class.
+
+    Attributes
+    ----------
+    * position (``npt.NDArray[np.float64]``): Detector feature vector.
+    * radius (``float, optional``): Detector radius, used in the V-detector algorithm.
+    """
+
+    position: npt.NDArray[np.float64]
+    radius: Optional[float] = None