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

aisp/nsa/_ns_core.py

@@ -1,8 +1,9 @@
-"""ns: Negative Selection
+"""nsa - Negative Selection.
 
 The functions perform detector checks and utilize Numba decorators for Just-In-Time compilation
 """
 
+import numpy as np
 import numpy.typing as npt
 from numba import njit, types
 
@@ -18,25 +19,29 @@ from ..utils.distance import compute_metric_distance, hamming
     cache=True
 )
 def check_detector_bnsa_validity(
-    x_class: npt.NDArray,
-    vector_x: npt.NDArray,
+    x_class: npt.NDArray[np.bool_],
+    vector_x: npt.NDArray[np.bool_],
     aff_thresh: float
 ) -> bool:
     """
-    Checks the validity of a candidate detector (vector_x) against samples from a class (x_class)
-    using the Hamming distance. A detector is considered INVALID if its distance to any sample
-    in ``x_class`` is less than or equal to ``aff_thresh``.
+    Check the validity of a candidate detector using the Hamming distance.
+    
+    A detector is considered INVALID if its distance to any sample in ``x_class`` is less than or
+    equal to ``aff_thresh``.
 
     Parameters
     ----------
-    * x_class (``npt.NDArray``): Array containing the class samples. Expected shape: 
-        (n_samples, n_features).
-    * vector_x (``npt.NDArray``): Array representing the detector. Expected shape: (n_features,).
-    * aff_thresh (``float``): Affinity threshold.
+    x_class : npt.NDArray[np.bool_]
+        Array containing the class samples. Expected shape:  (n_samples, n_features).
+    vector_x : npt.NDArray[np.bool_]
+        Array representing the detector. Expected shape: (n_features,).
+    aff_thresh : float
+        Affinity threshold.
 
     Returns
-    ----------
-    * True if the detector is valid, False otherwise.
+    -------
+    valid : bool
+        True if the detector is valid, False otherwise.
     """
     n = x_class.shape[1]
     if n != vector_x.shape[0]:
@@ -58,24 +63,25 @@ def check_detector_bnsa_validity(
     cache=True
 )
 def bnsa_class_prediction(
-    features: npt.NDArray,
-    class_detectors: npt.NDArray,
+    features: npt.NDArray[np.bool_],
+    class_detectors: npt.NDArray[np.bool_],
     aff_thresh: float
 ) -> int:
-    """
-    Defines the class of a sample from the non-self detectors.
+    """Define the class of a sample from the non-self detectors.
 
     Parameters
     ----------
-    * features (``npt.NDArray``): binary sample to be classified (shape: [n_features]).
-    * class_detectors (``npt.NDArray``): Array containing the detectors of all classes
-    (shape: [n_classes, n_detectors, n_features]).
-    * aff_thresh (``float``): Affinity threshold that determines whether a detector recognizes the
-    sample as non-self.
+    features : npt.NDArray[np.bool_]
+        binary sample to be classified (shape: [n_features]).
+    class_detectors : npt.NDArray[np.bool_]
+        Array containing the detectors of all classes (shape: [n_classes, n_detectors, n_features]).
+    aff_thresh : float
+        Affinity threshold that determines whether a detector recognizes the sample as non-self.
 
     Returns
-    ----------
-    * int: Index of the predicted class. Returns -1 if it is non-self for all classes.
+    -------
+    best_class_index : int
+        Index of the predicted class. Returns -1 if it is non-self for all classes.
     """
     n_classes, n_detectors, _ = class_detectors.shape
     best_class_idx = -1
@@ -116,31 +122,35 @@ def bnsa_class_prediction(
     cache=True
 )
 def check_detector_rnsa_validity(
-    x_class: npt.NDArray,
-    vector_x: npt.NDArray,
+    x_class: npt.NDArray[np.float64],
+    vector_x: npt.NDArray[np.float64],
     threshold: float,
     metric: int,
     p: float
 ) -> bool:
-    """
-    Checks the validity of a candidate detector (vector_x) against samples from a class (x_class)
-    using the Hamming distance. A detector is considered INVALID if its distance to any sample
-    in ``x_class`` is less than or equal to ``aff_thresh``.
+    """Check the validity of a candidate detector using the Hamming distance.
+
+    A detector is considered INVALID if its distance to any sample  in ``x_class`` is less than
+    or equal to ``aff_thresh``.
 
     Parameters
     ----------
-    * x_class (``npt.NDArray``): Array containing the class samples. Expected shape: 
-        (n_samples, n_features).
-    * vector_x (``npt.NDArray``): Array representing the detector. Expected shape: (n_features,).
-    * threshold (``float``): threshold.
-    * metric (``int``): Distance metric to be used. Available options: 
-        [0 (Euclidean), 1 (Manhattan), 2 (Minkowski)].
-    * p (``float``): Parameter for the Minkowski distance (used only if `metric` 
-    is "minkowski").
+    x_class : npt.NDArray[np.float64]
+        Array containing the class samples. Expected shape: (n_samples, n_features).
+    vector_x : npt.NDArray[np.float64]
+        Array representing the detector. Expected shape: (n_features,).
+    threshold : float
+        threshold.
+    metric : int
+        Distance metric to be used. Available options: [0 (Euclidean), 1 (Manhattan),
+        2 (Minkowski)].
+    p : float
+        Parameter for the Minkowski distance (used only if `metric` is "minkowski").
 
     Returns
-    ----------
-    * True if the detector is valid, False otherwise.
+    -------
+    valid : bool
+        True if the detector is valid, False otherwise.
     """
     n = x_class.shape[1]
     if n != vector_x.shape[0]:

aisp/utils/__init__.py

@@ -1,6 +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.35"

aisp/utils/_multiclass.py

@@ -6,24 +6,30 @@ 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.
+    """Separate indices of samples by class for targeted iteration.
 
     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.
+    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.
+    Returns
+    -------
+    position_samples : dict
+        A dictionary with the list of array positions(``y``), with the classes as key.
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> labels = ['a', 'b', 'c']
+    >>> y = np.array(['a', 'c', 'b', 'a', 'c', 'b'])
+    >>> slice_index_list_by_class(labels, y)
+    {'a': [0, 3], 1: [2, 5], 2: [1, 4]}
     """
     position_samples = {}
     for _class_ in classes:
         # Gets the sample positions by class from y.
-        position_samples[_class_] = list(np.nonzero(y == _class_)[0])
-
+        position_samples[_class_] = np.flatnonzero(y == _class_).tolist()
     return position_samples

aisp/utils/distance.py

@@ -3,6 +3,7 @@
 import numpy as np
 import numpy.typing as npt
 from numba import njit, types
+from numpy import float64
 
 EUCLIDEAN = 0
 MANHATTAN = 1
@@ -11,95 +12,105 @@ HAMMING = 3
 
 
 @njit([(types.boolean[:], types.boolean[:])], cache=True)
-def hamming(u: npt.NDArray[np.bool_], v: npt.NDArray[np.bool_]) -> np.float64:
-    """
-    Function to calculate the normalized Hamming distance between two points.
+def hamming(u: npt.NDArray[np.bool_], v: npt.NDArray[np.bool_]) -> float64:
+    """Calculate the normalized Hamming distance between two points.
     
     ((x₁ ≠ x₂) + (y₁ ≠ y₂) + ... + (yn ≠ yn)) / n
 
     Parameters
     ----------
-    * u (``npt.NDArray``): Coordinates of the first point.
-    * v (``npt.NDArray``): Coordinates of the second point.
+    u : npt.NDArray[np.bool_]
+        Coordinates of the first point.
+    v : npt.NDArray[np.bool_]
+        Coordinates of the second point.
 
-    returns
-    ----------
-    * Distance (``float``) between the two points.
+    Returns
+    -------
+    Distance : np.float64
+        Distance : float``) between the two points.
     """
     n = len(u)
     if n == 0:
-        return 0.0
+        return float64(0.0)
 
-    return np.sum(u != v) / n
+    return np.float64(np.sum(u != v) / n)
 
 
 @njit()
-def euclidean(u: npt.NDArray[np.float64], v: npt.NDArray[np.float64]) -> np.float64:
-    """
-    Function to calculate the normalized Euclidean distance between two points.
+def euclidean(u: npt.NDArray[np.float64], v: npt.NDArray[np.float64]) -> float64:
+    """Calculate the normalized Euclidean distance between two points.
     
     √( (x₁ – x₂)² + (y₁ – y₂)² + ... + (yn – yn)²)
 
     Parameters
     ----------
-    * u (``npt.NDArray``): Coordinates of the first point.
-    * v (``npt.NDArray``): Coordinates of the second point.
+    u : npt.NDArray[float64]
+        Coordinates of the first point.
+    v : npt.NDArray[float64]
+        Coordinates of the second point.
 
-    returns
-    ----------
-    * Distance (``float``) between the two points.
+    Returns
+    -------
+    distance : float64
+        Distance : float``) between the two points.
     """
-    return np.linalg.norm(u - v)
+    return float64(np.linalg.norm(u - v))
 
 
 @njit()
-def cityblock(u: npt.NDArray[np.float64], v: npt.NDArray[np.float64]) -> np.float64:
-    """
-    Function to calculate the normalized Manhattan distance between two points.
+def cityblock(u: npt.NDArray[float64], v: npt.NDArray[float64]) -> float64:
+    """Calculate the normalized Manhattan distance between two points.
     
     (|x₁ – x₂| + |y₁ – y₂| + ... + |yn – yn|) / n
 
     Parameters
     ----------
-    * u (``npt.NDArray``): Coordinates of the first point.
-    * v (``npt.NDArray``): Coordinates of the second point.
+    u : npt.NDArray[float64]
+        Coordinates of the first point.
+    v : npt.NDArray[float64]
+        Coordinates of the second point.
 
-    returns
-    ----------
-    * Distance (``float``) between the two points.
+    Returns
+    -------
+    distance : float64
+        Distance (``float``) between the two points.
     """
     n = len(u)
     if n == 0:
-        return -1.0
+        return float64(-1.0)
 
-    return np.sum(np.abs(u - v)) / n
+    return float64(np.sum(np.abs(u - v)) / n)
 
 
 @njit()
-def minkowski(u: npt.NDArray[np.float64], v: npt.NDArray[np.float64], p: float = 2.0):
-    """
-    Function to calculate the normalized Minkowski distance between two points.
+def minkowski(u: npt.NDArray[float64], v: npt.NDArray[float64], p: float = 2.0) -> float64:
+    """Calculate the normalized Minkowski distance between two points.
     
     (( |X₁ – Y₁|p + |X₂ – Y₂|p + ... + |Xn – Yn|p) ¹/ₚ.) / n
 
     Parameters
     ----------
-    * u (``npt.NDArray``): Coordinates of the first point.
-    * v (``npt.NDArray``): Coordinates of the second point.
-    * p float: The p parameter defines the type of distance to be calculated:
+    u : npt.NDArray[float64]
+        Coordinates of the first point.
+    v : npt.NDArray[float64]
+        Coordinates of the second point.
+    p : float
+        The p parameter defines the type of distance to be calculated:
+
         - p = 1: **Manhattan** distance — sum of absolute differences.
         - p = 2: **Euclidean** distance — sum of squared differences (square root).
         - p > 2: **Minkowski** distance with an increasing penalty as p increases.
 
-    returns
-    ----------
-    * Distance (``float``) between the two points.
+    Returns
+    -------
+    float64
+        Distance (``float``) between the two points.
     """
     n = len(u)
     if n == 0:
-        return -1.0
+        return float64(-1.0)
 
-    return (np.sum(np.abs(u - v) ** p) ** (1 / p)) / n
+    return float64((np.sum(np.abs(u - v) ** p) ** (1 / p)) / n)
 
 
 @njit(
@@ -110,26 +121,29 @@ def minkowski(u: npt.NDArray[np.float64], v: npt.NDArray[np.float64], p: float =
     cache=True
 )
 def compute_metric_distance(
-    u: npt.NDArray[np.float64],
-    v: npt.NDArray[np.float64],
+    u: npt.NDArray[float64],
+    v: npt.NDArray[float64],
     metric: int,
-    p: np.float64 = 2.0
-) -> np.float64:
-    """
-    Function to calculate the distance between two points by the chosen ``metric``.
+    p: float64 = 2.0
+) -> float64:
+    """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.
-    * metric (``int``): Distance metric to be used. Available options: 
-    [0 (Euclidean), 1 (Manhattan), 2 (Minkowski)]
-    * p (``float``): Parameter for the Minkowski distance (used only if `metric` 
-    is "minkowski").
-
-    returns
-    ----------
-    * Distance (``double``) between the two points with the selected metric.
+    u : npt.NDArray[float64]
+        Coordinates of the first point.
+    v : npt.NDArray[float64]
+        Coordinates of the second point.
+    metric : int
+        Distance metric to be used. Available options:  [0 (Euclidean), 1 (Manhattan), 
+        2 (Minkowski)]
+    p : float, default=2.0
+        Parameter for the Minkowski distance (used only if `metric` is "minkowski").
+
+    Returns
+    -------
+    float64
+        Distance (``float``) between the two points with the selected metric.
     """
     if metric == MANHATTAN:
         return cityblock(u, v)
@@ -147,29 +161,31 @@ def compute_metric_distance(
     cache=True
 )
 def min_distance_to_class_vectors(
-    x_class: npt.NDArray[np.float64],
-    vector_x: npt.NDArray[np.float64],
+    x_class: npt.NDArray[float64],
+    vector_x: npt.NDArray[float64],
     metric: int,
     p: float = 2.0
 ) -> float:
-    """
-    Calculates the minimum distance between an input vector and the vectors of a class.
+    """Calculate the minimum distance between an input vector and the vectors of a class.
 
     Parameters
     ----------
-    * x_class (``npt.NDArray``): Array containing the class vectors to be compared 
-    with the input vector. Expected shape: (n_samples, n_features).
-    * vector_x (``npt.NDArray``): Vector to be compared with the class vectors.
-    Expected shape: (n_features,).
-    * metric (``str``): Distance metric to be used. Available options: 
-    ["hamming", "cityblock", "minkowski", "euclidean"]
-    * p (``float``): Parameter for the Minkowski distance (used only if `metric` 
-    is "minkowski").
+    x_class : npt.NDArray[float64]
+        Array containing the class vectors to be compared with the input vector. Expected shape:
+        (n_samples, n_features).
+    vector_x : npt.NDArray[float64]
+        Vector to be compared with the class vectors. Expected shape: (n_features,).
+    metric : int
+        Distance metric to be used. Available options: ["hamming", "cityblock", "minkowski",
+        "euclidean"]
+    p : float, default=2.0
+        Parameter for the Minkowski distance (used only if `metric` is "minkowski").
 
     Returns
-    ----------
-    * float: The minimum distance calculated between the input vector and the class vectors.
-    * Returns -1.0 if the input dimensions are incompatible.
+    -------
+    min_distance : float:
+        The minimum distance calculated between the input vector and the class vectors. 
+        Returns -1.0 if the input dimensions are incompatible.
     """
     n = x_class.shape[1]
     if n != vector_x.shape[0]:
@@ -184,20 +200,22 @@ def min_distance_to_class_vectors(
 
 
 def get_metric_code(metric: str) -> int:
-    """
-    Returns the numeric code associated with a distance metric.
+    """Get the numeric code associated with a distance metric.
 
     Parameters
     ----------
-    * metric (str): Name of the metric. Can be "euclidean", "manhattan", "minkowski" or "hamming".
+    metric : str
+        Name of the metric. Can be "euclidean", "manhattan", "minkowski" or "hamming".
 
     Raises
-    ----------
-    * ValueError: If the metric provided is not supported.
+    ------
+    ValueError
+        If the metric provided is not supported.
 
     Returns
-    ----------
-    * int: Numeric code corresponding to the metric.
+    -------
+    int
+        Numeric code corresponding to the metric.
     """
     metric_map = {
         "euclidean": EUCLIDEAN,

aisp/utils/metrics.py

@@ -1,4 +1,5 @@
 """Utility functions for measuring accuracy and performance."""
+
 from typing import Union
 
 import numpy as np
@@ -9,23 +10,24 @@ def accuracy_score(
     y_true: Union[npt.NDArray, list],
     y_pred: Union[npt.NDArray, list]
 ) -> float:
-    """
-    Function to calculate the accuracy score based on true and predicted labels.
+    """Calculate the accuracy score based on true and predicted labels.
 
     Parameters
     ----------
-    * y_true ()``Union[npt.NDArray, list]``):
+    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]``):
+    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.
+    -------
+    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.
+    ------
+    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:

aisp/utils/sanitizers.py

@@ -1,4 +1,5 @@
 """Utility functions for validation and treatment of parameters."""
+
 from typing import TypeVar, Iterable, Callable, Any, Optional
 
 T = TypeVar('T')
@@ -6,50 +7,58 @@ 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.
+    Value if present in the set of valid choices; otherwise, the default value.
 
     Parameters
     ----------
-    * value (``T``): The value to be checked.
-    * valid_choices (``Iterable[T]``): A collection of valid choices.
-    * default: The default value to be returned if 'value' is not in 'valid_choices'.
+    value : T
+        The value to be checked.
+    valid_choices : Iterable[T]
+        A collection of valid choices.
+    default : T
+        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.
+    -------
+    value : T
+        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.
+    Value if it satisfies the specified condition; otherwise, 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.
+    value : T
+        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.
+    -------
+    value : 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.
+    Seed if it is a non-negative integer; otherwise, None.
 
     Parameters
     ----------
-    * seed (``Any``): The seed value to be validated.
+    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.
+    -------
+    seed : 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.41.dist-info → aisp-0.2.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: aisp
-Version: 0.1.41
+Version: 0.2.0
 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>
@@ -79,7 +79,8 @@ Artificial Immune Systems (AIS) are inspired by the vertebrate immune system, cr
 ##### Algorithms implemented:
 
 > - [x] [**Negative Selection.**](https://ais-package.github.io/docs/aisp-techniques/Negative%20Selection/)
-> - [ ] *Clonal Selection Algorithms.*
+> - [x] **Clonal Selection Algorithms.**
+>     * [AIRS - Artificial Immune Recognition System](https://ais-package.github.io/docs/aisp-techniques/Clonal%20Selection%20Algorithms/)
 > - [ ] *Dendritic Cells.*
 > - [ ] *Immune Network Theory.*
 
@@ -126,22 +127,14 @@ pip install aisp
 
 ---
 
-##### Example using the negative selection technique (**nsa**):
+Explore the example notebooks available in the [AIS-Package/aisp repository](https://github.com/AIS-Package/aisp/tree/main/examples).
+These notebooks demonstrate how to utilize the package's functionalities in various scenarios, including applications of the RNSA,
+BNSA and AIRS algorithms on datasets such as Iris, Geyser, and Mushrooms.
 
-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.
+You can run the notebooks directly in your browser without any local installation using Binder:
 
-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)
-
----
+[![Launch on Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/AIS-Package/aisp/HEAD?labpath=%2Fexamples)
 
+> 💡 **Tip**: Binder may take a few minutes to load the environment, especially on the first launch.
 </section>
 </section>