aisp 0.1.34__py3-none-any.whl → 0.1.35__py3-none-any.whl

aisp/utils/__init__.py

@@ -1,5 +1,6 @@
+"""Utility functions and helpers for development."""
 from ._multiclass import slice_index_list_by_class
 
 __author__ = "João Paulo da Silva Barros"
 __all__ = ["slice_index_list_by_class"]
-__version__ = "0.1.33"
+__version__ = "0.1.35"

aisp/utils/_multiclass.py

@@ -1,3 +1,4 @@
+"""Utility functions for handling classes with multiple categories."""
 from typing import Union
 import numpy as np
 import numpy.typing as npt
@@ -5,37 +6,21 @@ import numpy.typing as npt
 
 def slice_index_list_by_class(classes: Union[npt.NDArray, list], y: npt.NDArray) -> dict:
     """
-    The function ``__slice_index_list_by_class(...)``, separates the indices of the lines \
-    according to the output class, to loop through the sample array, only in positions where \
-    the output is the class being trained.
-
-    Parameters:
-    ---
-        * classes (``list or npt.NDArray``): list with unique classes.
-        * y (npt.NDArray): Receives a ``y``[``N sample``] array with the output classes of the \
-            ``X`` sample array.
-
-    returns:
-    ---
-        * dict: A dictionary with the list of array positions(``y``), with the classes as key.
-
-    ---
-
-    A função ``__slice_index_list_by_class(...)``, separa os índices das linhas conforme a \
-    classe de saída, para percorrer o array de amostra, apenas nas posições que a saída for \
-    a classe que está sendo treinada.
-
-    Parameters:
-    ---
-        * classes (``list or npt.NDArray``): lista com classes únicas.
-        * y (npt.NDArray): Recebe um array ``y``[``N amostra``] com as classes de saída do \
-            array de amostra ``X``.
-
-    Returns:
-    ---
-        * dict: Um dicionário com a lista de posições do array(``y``), com as classes como chave.
+    The function ``slice_index_list_by_class(...)``, separates the indices of the lines according
+    to the output class, to loop through the sample array, only in positions where the output is the
+    class being trained.
+
+    Parameters
+    ----------
+    * classes (``list or npt.NDArray``): list with unique classes.
+    * y (``npt.NDArray``): Receives a ``y``[``N sample``] array with the output classes of the 
+        ``X`` sample array.
+
+    returns
+    ----------
+    * dict: A dictionary with the list of array positions(``y``), with the classes as key.
     """
-    position_samples = dict()
+    position_samples = {}
     for _class_ in classes:
         # Gets the sample positions by class from y.
         position_samples[_class_] = list(np.nonzero(y == _class_)[0])

aisp/utils/metrics.py

@@ -1,4 +1,6 @@
+"""Utility functions for measuring accuracy and performance."""
 from typing import Union
+
 import numpy as np
 import numpy.typing as npt
 
@@ -8,54 +10,31 @@ def accuracy_score(
         y_pred: Union[npt.NDArray, list]
 ) -> float:
     """
-    Function to calculate precision accuracy based on lists of true labels and
-    predicted labels.
-
-    Parameters:
-    ---
-
-        * y_true (``Union[npt.NDArray, list]``): Ground truth (correct) labels. \
-            Expected to be of the same length as `y_pred`.
-        * y_pred (``Union[npt.NDArray, list]``): Predicted labels. Expected to \
-            be of the same length as `y_true`.
-
-    Returns:
-    ---
-        * Accuracy (``float``): The ratio of correct predictions to the total \
-        number of predictions.
-
-    Raises:
-    ---
-        * ValueError: If `y_true` or `y_pred` are empty or if they do not have the same length.
-
-    ---
-
-    Função para calcular a acurácia de precisão com base em listas de rótulos
-    verdadeiros e nos rótulos previstos.
-
-    Parâmetros:
-    ---
-        * y_true (``Union[npt.NDArray, list]``): Rótulos verdadeiros (corretos)..
-        * y_pred (``Union[npt.NDArray, list]``): Rótulos previstos.
-
-    Retornos:
-    ---
-        * Precisão (``float``): A proporção de previsões corretas em relação
-        ao número total de previsões.
-
-    Lança:
-    ---
-        * ValueError: Se `y_true` ou `y_pred` estiverem vazios ou se não
-        tiverem o mesmo tamanho.
+    Function to calculate the accuracy score based on true and predicted labels.
+
+    Parameters
+    ----------
+    * y_true ()``Union[npt.NDArray, list]``):
+        Ground truth (correct) labels. Expected to be of the same length as `y_pred`.
+    * y_pred (``Union[npt.NDArray, list]``):
+        Predicted labels. Expected to be of the same length as `y_true`.
+
+    Returns
+    ----------
+    * float: The ratio of correct predictions to the total number of predictions.
+
+    Raises
+    ----------
+    * ValueError: If `y_true` or `y_pred` are empty or if they do not have the same length.
     """
     n = len(y_true)
     if n == 0:
         raise ValueError(
             "Division by zero: y_true cannot be an empty list or array."
         )
-    elif n != len(y_pred):
+    if n != len(y_pred):
         raise ValueError(
             f"Error: The arrays must have the same size. Size of y_true: "
             f"{len(y_true)}, Size of y_pred: {len(y_pred)}"
         )
-    return np.sum(np.sum(np.array(y_true) == np.array(y_pred))) / n
+    return np.sum(np.array(y_true) == np.array(y_pred)) / n

aisp/utils/sanitizers.py

@@ -0,0 +1,54 @@
+"""Utility functions for validation and treatment of parameters."""
+from typing import TypeVar, Iterable, Callable, Any, Optional
+
+T = TypeVar('T')
+
+def sanitize_choice(value: T, valid_choices: Iterable[T], default: T) -> T:
+    """
+    Returns the value if it is present in the set of valid choices; otherwise, 
+    returns the default value.
+
+    Parameters
+    ----------
+    * value: The value to be checked.
+    * valid_choices (iterable): A collection of valid choices.
+    * default: The default value to be returned if 'value' is not in 'valid_choices'.
+
+    Returns
+    ----------
+    * The original value if valid, or the default value if not.
+    """
+    return value if value in valid_choices else default
+
+
+def sanitize_param(value: T, default: T, condition: Callable[[T], bool]) -> T:
+    """
+    Returns the value if it satisfies the specified condition; otherwise, returns the default value.
+
+    Parameters
+    ----------
+    * value: The value to be checked.
+    * default (``T``): The default value to be returned if the condition is not satisfied.
+    * condition (``Callable[[T], bool]``): A function that takes a value and returns a boolean, 
+        determining if the value is valid.
+
+    Returns
+    ----------
+    * T: The original value if the condition is satisfied, or the default value if not.
+    """
+    return value if condition(value) else default
+
+
+def sanitize_seed(seed: Any) -> Optional[int]:
+    """
+    Returns the seed if it is a non-negative integer; otherwise, returns None.
+
+    Parameters
+    ----------
+    * seed (``Any``): The seed value to be validated.
+
+    Returns
+    ----------
+    * Optional[int]: The original seed if it is a non-negative integer, or None if it is invalid.
+    """
+    return seed if isinstance(seed, int) and seed >= 0 else None

{aisp-0.1.34.dist-info → aisp-0.1.35.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: aisp
-Version: 0.1.34
+Version: 0.1.35
 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>
@@ -39,7 +39,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 +52,6 @@ Dynamic: license-file
 ---
 
 <section id='english'>
-<div align = center> 
-
-## English
-
-</div>
 
 #### Summary:
 
@@ -144,104 +139,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.35.dist-info/RECORD

@@ -0,0 +1,14 @@
+aisp/__init__.py,sha256=6is9Nwltdm6JZAsdLPXY56WXC7qnd0kNUEJoizOxWHg,111
+aisp/exceptions.py,sha256=ONiKCZrBhfUaMO1vYHnOr1_eL9PtVJ7b_HRroMbORpc,1405
+aisp/nsa/__init__.py,sha256=wgoFb-0WovzFovQG6UFkAb-IbZWK2wlytuJ03wmV4Q0,411
+aisp/nsa/_base.py,sha256=OpBC3loiWk8NEb4ulogulIOKeh6hTnxcpImF6BNy8iI,8086
+aisp/nsa/_negative_selection.py,sha256=iYtd39eR4O2y1bOVAAEqfMmgzIzQ_oexLCN3sRO8Mxg,32089
+aisp/utils/__init__.py,sha256=-r--qdfTq4dVJU-VoJ7dvXTNS5_I1q1aGAQ02zNBOGw,217
+aisp/utils/_multiclass.py,sha256=KJ2Le62KsSPRQB3UDMv7HT13xQLvwwZQM3QekTATDiY,1049
+aisp/utils/metrics.py,sha256=RmqR5FRxQUZkF9GZhAUXNplaeRldhXv592DeeYPdyV8,1300
+aisp/utils/sanitizers.py,sha256=QKpIu8YyNLIZT472O49QybLZB5P-NQqGaNI5xylyJ8k,1856
+aisp-0.1.35.dist-info/licenses/LICENSE,sha256=fTqV5eBpeAZO0_jit8j4Ref9ikBSlHJ8xwj5TLg7gFk,7817
+aisp-0.1.35.dist-info/METADATA,sha256=aHoORgNbmyDlN7Pd2MXCaNgGD7T30g_jtM_XIH20pZs,4603
+aisp-0.1.35.dist-info/WHEEL,sha256=CmyFI0kx5cdEMTLiONQRbGQwjIoR1aIYB7eCAQ4KPJ0,91
+aisp-0.1.35.dist-info/top_level.txt,sha256=Q5aJi_rAVT5UNS1As0ZafoyS5dwNibnoyOYV7RWUB9s,5
+aisp-0.1.35.dist-info/RECORD,,

aisp/NSA/__init__.py

@@ -1,18 +0,0 @@
-"""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.
-
-----
-
-Os NSAs simulam o processo de maturação das células-T no sistema imunológico, onde \
-essas células aprendem a distinguir entre o próprio e não-próprio.
-Apenas as células-T capazes de reconhecer elementos não-próprios são preservadas.
-
-"""
-from ._negative_selection import BNSA, RNSA
-
-__author__ = "João Paulo da Silva Barros"
-__all__ = ["RNSA", "BNSA"]
-__version__ = "0.1.34"

aisp/NSA/_base.py

@@ -1,281 +0,0 @@
-from abc import abstractmethod
-
-import numpy as np
-import numpy.typing as npt
-from typing import Literal, Optional
-from scipy.spatial.distance import euclidean, cityblock, minkowski
-
-from ..utils.metrics import accuracy_score
-
-
-class Base:
-    """
-    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.
-
-    ---
-
-    A classe base contém funções que são utilizadas por mais de uma classe do pacote, e por isso \
-    são consideradas essenciais para o funcionamento geral do sistema.
-    """
-
-    def __init__(self, metric: str = "euclidean", p: float = 2):
-        """
-        Parameters:
-        ---
-        * metric (``str``): Way to calculate the distance between the detector and the sample:
-
-                * ``'Euclidean'`` ➜ The calculation of the distance is given by the expression: \
-                    √( (x₁ – x₂)² + (y₁ – y₂)² + ... + (yn – yn)²).
-                * ``'minkowski'`` ➜ The calculation of the distance is given by the expression: \
-                    ( |X₁ – Y₁|p + |X₂ – Y₂|p + ... + |Xn – Yn|p) ¹/ₚ.
-                * ``'manhattan'`` ➜ The calculation of the distance is given by the expression: \
-                    ( |x₁ – x₂| + |y₁ – y₂| + ... + |yn – yn|) .
-
-
-        * p (``float``): 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 \
-            [learn more](https://docs.scipy.org/doc/scipy/reference/generated/scipy.spatial.distance.minkowski.html).
-
-        ---
-
-        Parameters:
-        ---
-        * metric (``str``): Forma para se calcular a distância entre o detector e a amostra: 
-
-                * ``'euclidiana'`` ➜ O cálculo da distância dá-se pela expressão: \
-                    √( (x₁ – x₂)² + (y₁ – y₂)² + ... + (yn – yn)²).
-                * ``'minkowski'``  ➜ O cálculo da distância dá-se pela expressão: \
-                    ( |X₁ – Y₁|p + |X₂ – Y₂|p + ... + |Xn – Yn|p).
-                * ``'manhattan'``  ➜ O cálculo da distância dá-se pela expressão: \
-                    ( |x₁ – x₂| + |y₁ – y₂| + ... + |yn – yn|).
-
-            Defaults to ``'euclidean'``.
-
-        * p (``float``): Este parâmetro armazena o valor de ``p`` utilizada na distância de Minkowski. \
-            O padrão é ``2``, o que significa distância euclidiana normalizada. Diferentes valores \
-            de p levam a diferentes variantes da distância de Minkowski \
-            [saiba mais](https://docs.scipy.org/doc/scipy/reference/generated/scipy.spatial.distance.minkowski.html).
-        """
-        if metric == "manhattan" or metric == "minkowski":
-            self.metric: str = metric
-        else:
-            self.metric: str = "euclidean"
-        self.p: float = p
-
-    def _distance(self, u: npt.NDArray, v: npt.NDArray):
-        """
-        Function to calculate the distance between two points by the chosen ``metric``.
-
-        Parameters:
-        ---
-            * u (``npt.NDArray``): Coordinates of the first point.
-            * v (``npt.NDArray``): Coordinates of the second point.
-
-        returns:
-        ---
-            * Distance (``double``) between the two points.
-
-        ---
-
-        Função para calcular a distância entre dois pontos pela ``metric`` escolhida.
-
-        Parameters:
-        ---
-            * u (``npt.NDArray``): Coordenadas do primeiro ponto.
-            * v (``npt.NDArray``): Coordenadas do segundo ponto.
-
-        Returns:
-        ---
-            * Distância (``double``) entre os dois pontos.
-        """
-        if self.metric == "manhattan":
-            return cityblock(u, v)
-        elif self.metric == "minkowski":
-            return minkowski(u, v, self.p)
-        else:
-            return euclidean(u, v)
-
-    @staticmethod
-    def _check_and_raise_exceptions_fit(
-            X: npt.NDArray = None,
-            y: npt.NDArray = None,
-            _class_: Literal["RNSA", "BNSA"] = "RNSA",
-    ):
-        """
-        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.
-
-        ---
-
-        Função responsável por verificar os parâmetros da função fit e lançar exceções se a \
-        verificação não for bem-sucedida.
-
-        Parâmetros:
-        ---
-            * X (``npt.NDArray``): Array de treinamento, contendo as amostras e suas características, \
-                [``N samples`` (linhas)][``N features`` (colunas)].
-            * y (``npt.NDArray``): Array de classes alvo de ``X`` com [``N samples`` (linhas)].
-            * _class_ (Literal[RNSA, BNSA], opcional): Classe atual. O padrão é 'RNSA'.
-
-        Lança:
-        ---
-            * TypeError: Se X ou y não forem ndarrays ou tiverem formas incompatíveis.
-            * ValueError: Se _class_ for BNSA e X contiver valores que não sejam compostos apenas por 0 e 1.
-        """
-        if not isinstance(X, np.ndarray):
-            if isinstance(X, list):
-                X = np.array(X)
-            else:
-                raise TypeError("X is not an ndarray or list.")
-        elif not isinstance(y, np.ndarray):
-            if isinstance(y, list):
-                y = np.array(y)
-            else:
-                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."
-            )
-
-    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.
-
-        ---
-
-        Função score calcular a acurácia da previsão.
-
-        Details:
-        ---
-        Esta função realiza a previsão de X e verifica quantos elementos são iguais entre o vetor \
-        y e y_previsto. Essa função foi adicionada para oferecer compatibilidade com algumas funções \
-        do scikit-learn.
-
-        Parameters:
-        ---
-
-        * X : np.ndarray
-            Conjunto de características com shape (n_samples, n_features).
-        * y : np.ndarray
-            Valores verdadeiros com shape (n_samples,).
-
-        returns:
-        ---
-
-        accuracy : float
-            A acurácia do modelo.
-        """
-        if len(y) == 0:
-            return 0
-        y_pred = self.predict(X)
-        return accuracy_score(y, y_pred)
-
-    @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.
-
-        ---
-
-        Função para treinar o modelo usando os dados de entrada ``X`` e os classes correspondentes ``y``.
-
-        Este método abstrato é implementado pela classe que o herdar.
-
-        Parâmetros:
-        ---
-            * X (``npt.NDArray``): Dados de entrada utilizados para o treinamento do modelo, previamente \
-                normalizados no intervalo [0, 1].
-            * y (``npt.NDArray``): Rótulos ou valores-alvo correspondentes aos dados de entrada.
-            * verbose (``bool``, opcional): Flag para ativar ou desativar a saída detalhada durante o \
-                treinamento. O padrão é ``True``.
-
-        Retornos:
-        ---
-            * self: Retorna a instância da classe que implementa este método.
-        """
-        pass
-
-    @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.
-
-        ---
-
-        Função para gerar previsões com base nos dados de entrada ``X``.
-
-        Este método abstrato é implementado pela classe que o herdar.
-
-        Parâmetros:
-        ---
-            * X (``npt.NDArray``): Dados de entrada para os quais as previsões serão geradas.
-
-        Retornos:
-        ---
-            * Previsões (``Optional[npt.NDArray]``): Valores previstos para cada amostra de entrada,
-                ou ``None`` se a previsão falhar.
-        """
-        pass