mdapy-v2 2.0.0__py3-none-any.whl

mdapy/__init__.py

@@ -0,0 +1,5 @@
+"""Maximum dissimilarity sampling."""
+
+from .mda import DataColumn, max_diss_alg
+
+__all__ = ["DataColumn", "max_diss_alg"]

mdapy/legacy.py

@@ -0,0 +1,141 @@
+"""Tuple-based API retained for existing users and historical comparison."""
+
+from functools import cache
+
+import numpy as np
+from numpy.typing import ArrayLike, NDArray
+from scipy.stats import circstd
+
+
+def distance(
+    point1: NDArray,
+    point2: NDArray,
+    dir_indices: list[int] | None,
+    std_list: list[float],
+) -> float:
+    vector = np.zeros_like(point1)
+    for ind, (p1_ind, p2_ind) in enumerate(zip(point1, point2)):
+        if dir_indices is not None and ind in dir_indices:
+            dist = ((p1_ind - p2_ind) + 180) % 360 - 180
+        else:
+            dist = p1_ind - p2_ind
+        vector[ind] = dist / (np.sqrt(2) * std_list[ind])
+    return float(np.linalg.norm(vector))
+
+
+def preprocess(data_tuple: tuple[ArrayLike, ...]) -> NDArray:
+    return np.array(data_tuple, dtype=np.float32).T
+
+
+def std_list(
+    data_tuple: tuple[ArrayLike, ...],
+    dir_indices: list[int] | None,
+) -> list[float]:
+    return_list = []
+    for ind, array in enumerate(data_tuple):
+        array = np.asarray(array)
+        if dir_indices is not None and ind in dir_indices:
+            computed_std = circstd(array, high=360, low=0)
+        else:
+            computed_std = np.std(array)
+        return_list.append(computed_std)
+    return return_list
+
+
+class DataMatrix:
+    def __init__(
+        self,
+        data_tuple: tuple[ArrayLike, ...],
+        dir_indices: list[int] | None,
+    ) -> None:
+        # Check if any of the arrays in the tuple has NaN values
+        for array in data_tuple:
+            if np.isnan(array).any():
+                raise ValueError("The data contains NaN values")
+        self.data = preprocess(data_tuple)
+        self.std_list = std_list(data_tuple, dir_indices)
+        self.dir_indices = dir_indices
+
+    def __getitem__(self, index: list[int] | int) -> NDArray:
+        return self.data[index]
+
+    @property
+    def num_points(self) -> int:
+        return len(self.data)
+
+    # Preserve the historical cache for comparisons; revisit with the algorithm.
+    @cache  # noqa: B019
+    def distance_between(self, index1: int, index2: int) -> float:
+        point1, point2 = self.data[[index1, index2]]
+        return distance(point1, point2, self.dir_indices, self.std_list)
+
+
+def distance_to_subset(
+    data_matrix: DataMatrix,
+    point_index: int,
+    subset_indices: list[int],
+) -> float:
+    distance_list = [
+        data_matrix.distance_between(point_index, i_point) for i_point in subset_indices
+    ]
+    return min(distance_list)
+
+
+def max_diss_alg(
+    data_tuple: tuple[ArrayLike, ...],
+    n_clusters: int,
+    seed_index: int = 0,
+    dir_indices: list[int] | None = None,
+    *,
+    show_progress: bool = True,
+) -> tuple[NDArray, list[int]]:
+    """
+    This function implements the Maximum Dissimilarity Algorithm (MDA) to cluster a data.
+
+    Parameters
+    ----------
+    data_tuple : tuple[NDArray, ...]
+        A tuple of arrays with the data to cluster.
+    n_clusters : int
+        The number of clusters to generate.
+    seed_index : int, optional
+        The index of the seed point, by default 0
+    dir_indices : list[int], optional
+        The indices of directional arrays in the tuple, by default None
+    show_progress : bool, optional
+        Print progress while selecting points, by default True
+
+    Returns
+    -------
+    tuple[NDArray, list[int]]
+        A tuple with the clustered data points and their indices in the original data.
+    """
+
+    # Create the data matrix
+    data_matrix = DataMatrix(data_tuple, dir_indices)
+
+    # Initialize the centroids with the seed
+    subset_indices: list[int] = [seed_index]
+
+    while len(subset_indices) < n_clusters:
+        max_dist = next_point_index = -1
+        # Find the point with the maximum distance to the subset
+        for i_point in range(data_matrix.num_points):
+            if i_point in subset_indices:
+                continue
+            # Get the distance to the closest point in the subset
+            distance = distance_to_subset(data_matrix, i_point, subset_indices)
+            if distance > max_dist:
+                max_dist = distance
+                next_point_index = i_point
+            if show_progress:
+                progress = (i_point + 1) / data_matrix.num_points * 100
+                print(
+                    f"Finding cluster nº{len(subset_indices) + 1} --> {progress:.2f}%",
+                    end="\r",
+                )
+        # Add the point with the maximum distance to the subset
+        if next_point_index > -1:
+            subset_indices.append(next_point_index)
+
+    return data_matrix[subset_indices], subset_indices

mdapy/mda.py

@@ -0,0 +1,85 @@
+"""Public API for selecting maximally dissimilar observations."""
+
+from functools import cached_property
+from numbers import Integral
+
+import numpy as np
+from numpy.typing import ArrayLike, NDArray
+from scipy.stats import circstd
+
+from . import legacy
+
+
+class DataColumn:
+    """One scalar variable, optionally interpreted as angles in degrees."""
+
+    def __init__(self, array: ArrayLike, *, directional: bool = False) -> None:
+        if not isinstance(directional, bool):
+            raise TypeError("directional must be a bool")
+        values = np.asarray(array, dtype=np.float32)
+        if values.ndim != 1:
+            raise ValueError("Each data column must be one-dimensional")
+        if not np.isfinite(values).all():
+            raise ValueError("Data columns must contain only finite values")
+        self.np_array: NDArray[np.float32] = values
+        self.directional = directional
+
+    def __len__(self) -> int:
+        return len(self.np_array)
+
+    @cached_property
+    def standard_deviation(self) -> float:
+        if self.directional:
+            return float(circstd(self.np_array, high=360, low=0))
+        return float(np.std(self.np_array))
+
+
+_LEGACY_HINT = (
+    "The tuple-based API is available from mdapy.legacy: "
+    "from mdapy.legacy import max_diss_alg"
+)
+
+
+def max_diss_alg(
+    *columns: DataColumn,
+    n_clusters: int | None = None,
+    seed_index: int = 0,
+    **kwargs: object,
+) -> tuple[NDArray[np.float32], list[int]]:
+    """Select observations using columns and the maximum dissimilarity algorithm.
+
+    ``n_clusters`` is required. Directional columns use degrees with a period
+    of 360. Returns selected rows in selection order and their input indices.
+    """
+    if "data_tuple" in kwargs or "dir_indices" in kwargs:
+        raise TypeError(_LEGACY_HINT)
+    if kwargs:
+        unexpected = next(iter(kwargs))
+        raise TypeError(f"Unexpected keyword argument: {unexpected}")
+    if columns and not all(isinstance(col, DataColumn) for col in columns):
+        raise TypeError(f"Expected DataColumn arguments. {_LEGACY_HINT}")
+    if not columns:
+        raise ValueError("At least one DataColumn is required")
+    if n_clusters is None:
+        raise TypeError("n_clusters is required")
+    if isinstance(n_clusters, bool) or not isinstance(n_clusters, Integral):
+        raise TypeError("n_clusters must be an integer")
+    if isinstance(seed_index, bool) or not isinstance(seed_index, Integral):
+        raise TypeError("seed_index must be an integer")
+
+    n_points = len(columns[0])
+    if any(len(col) != n_points for col in columns):
+        raise ValueError("All data columns must have the same length")
+    if not 1 <= n_clusters <= n_points:
+        raise ValueError("n_clusters must be between 1 and the number of rows")
+    if not 0 <= seed_index < n_points:
+        raise ValueError("seed_index is out of bounds")
+    for index, col in enumerate(columns):
+        if not np.isfinite(col.standard_deviation) or col.standard_deviation <= 0:
+            raise ValueError(f"Column {index} has zero or undefined deviation")
+
+    arrays = tuple(col.np_array for col in columns)
+    dir_indices = [i for i, col in enumerate(columns) if col.directional]
+    return legacy.max_diss_alg(
+        arrays, int(n_clusters), int(seed_index), dir_indices, show_progress=False
+    )

mdapy_v2-2.0.0.dist-info/METADATA

@@ -0,0 +1,122 @@
+Metadata-Version: 2.4
+Name: mdapy-v2
+Version: 2.0.0
+Summary: Maximum Dissimilarity Algorithm in Python
+Author: Pablo Garcia
+Author-email: Pablo Garcia <pablofueros@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Requires-Dist: numpy>=1.26
+Requires-Dist: scipy>=1.11.2
+Requires-Python: >=3.10
+Project-URL: Repository, https://github.com/pablofueros/mdapy-v2
+Project-URL: Issues, https://github.com/pablofueros/mdapy-v2/issues
+Project-URL: Original project, https://github.com/IHCantabria/mdapy
+Description-Content-Type: text/markdown
+
+# mdapy-v2
+
+`mdapy-v2` is a maintained fork of
+[`IHCantabria/mdapy`](https://github.com/IHCantabria/mdapy), developed by the
+original author. Version 2.0 introduces the `DataColumn` API while preserving
+the `mdapy` Python import and the original maximum dissimilarity algorithm.
+
+The distributions `mdapy-v2`, `ihc-mdapy`, and the unrelated `mdapy` project
+all provide a package named `mdapy`. Treat them as alternatives: do not install
+them together in the same Python environment.
+
+## Installation
+
+Install the maintained distribution from PyPI:
+
+```bash
+pip install mdapy-v2
+```
+
+The import remains unchanged:
+
+```python
+from mdapy import DataColumn, max_diss_alg
+```
+
+The original `ihc-mdapy==0.1.0` distribution uses the tuple-based API shown in
+the legacy section below. Version 2.0 also contains the NaN validation from the
+historical `v0.1.1` tag, which was not published to PyPI.
+
+---
+
+## 📋 The Maximum Dissimilarity Algorithm
+The Maximum Dissimilarity Algorithm is a technique used to select a specified number of data points from a larger dataset in such a way that the selected points are maximally dissimilar to each other. The algorithm is particularly useful in scenarios where you need to create diverse subsets of data for analysis or for initializing cluster centroids in clustering algorithms.
+
+In this case, directional variables can also be considered, in which case, the distance between two angles is calculated as the shortest distance between the two angles in a circle. For example, the distance between 350° and 10° is 20°, not 340°. This is the approach used in this implementation of the algorithm (see [Guanche et al. (2013)](#1) for more details).
+
+### Algorithm steps
+
+1. Start with the observation at `seed_index` (default `0`).
+2. For each unselected observation, find its distance to the nearest selected observation.
+3. Select the observation with the greatest nearest distance. Repeat until `n_clusters` observations have been selected.
+
+Distances are Euclidean after dividing each column's difference by its
+standard deviation and `sqrt(2)`. Directional differences use the shortest
+arc in degrees, and their standard deviation is circular. If two candidates
+have exactly the same distance, the one appearing first in the input is
+selected.
+
+---
+
+## Usage
+
+Pass one `DataColumn` per variable. Each column must be one-dimensional, have
+the same number of observations, and contain only finite values. Columns with
+zero or undefined standard deviation are rejected. Directional columns are
+angles in degrees. `n_clusters` is required and must be between 1 and the
+number of observations; `seed_index` must be a valid input position.
+
+```python
+from mdapy import DataColumn, max_diss_alg
+
+tp = [14.93, 10.42, 7.46, 7.63, 12.20, 12.05, 14.49, 8.62]
+hs = [1.82, 1.45, 0.26, 0.90, 1.30, 5.71, 1.40, 2.18]
+direction = [268, 272, 289, 293, 276, 273, 276, 292]
+
+points, indices = max_diss_alg(
+    DataColumn(tp),
+    DataColumn(hs),
+    DataColumn(direction, directional=True),
+    n_clusters=3,
+)
+```
+
+Input values are converted to `float32`. `points` is a `float32` NumPy array
+of shape `(n_clusters, n_columns)` in selection order.
+`indices` is a list of positions in the original input. The first position is
+`seed_index` (default `0`).
+
+### Legacy tuple API
+
+Existing tuple-based calls can use an explicit import:
+
+```python
+from mdapy.legacy import max_diss_alg
+
+points, indices = max_diss_alg((tp, hs, direction), 3, seed_index=0, dir_indices=[2])
+```
+
+Passing a tuple to `mdapy.max_diss_alg` raises an error explaining this import.
+
+---
+
+## ©️ Credits
+
+Originally developed by 👨‍💻 [Pablo Garcia](https://github.com/pablofueros)
+at 🏢 [IHCantabria](https://github.com/IHCantabria), and now maintained as
+the personal `mdapy-v2` fork. The historical `v0.1.1` fix was contributed by
+Álvaro Rodríguez. The original IHCantabria copyright notice and MIT terms are
+preserved in [`LICENSE`](LICENSE).
+
+---
+
+## 📚 References
+<a id="1">[1]</a> Guanche, Y., Guanche, R., Camus, P., Mendez, F. J., & Medina, R. (2013). A multivariate approach to estimate design loads for offshore wind turbines. *Wind Energy*, 16(7), 1091-1106.
+
+---

mdapy_v2-2.0.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+mdapy/__init__.py,sha256=L4K8sO64fv2UNzuGn66NgjXZ-oLH-oVT7OInwCmrixQ,123
+mdapy/legacy.py,sha256=N46a_plmigXAgEXO2NPIyl2-q9mAkZiTdf8ae7_4FuE,4605
+mdapy/mda.py,sha256=b-uKJwaZGRFUmPfwkLa9I09i2AoN0lSl-E0p32zQqTU,3334
+mdapy_v2-2.0.0.dist-info/licenses/LICENSE,sha256=H8yzPXcyB1OyvYT09336d2NE5aaSuguDV5-lr2a5DcQ,1067
+mdapy_v2-2.0.0.dist-info/WHEEL,sha256=xTCBFIZIIyRSxyowOv5Wqg_jFU6KsdIffuulBB09Ph8,80
+mdapy_v2-2.0.0.dist-info/METADATA,sha256=9LvNXjN5s9Ap20tEe6tdvBmTaZ4I_rjalC3Ot-rZl38,4727
+mdapy_v2-2.0.0.dist-info/RECORD,,

mdapy_v2-2.0.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: uv 0.13.0
+Root-Is-Purelib: true
+Tag: py3-none-any

mdapy_v2-2.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 IHCantabria
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.