sbcluster 0.1.0__tar.gz

sbcluster-0.1.0/.gitlab-ci.yml

@@ -0,0 +1,39 @@
+stages:
+  - lint
+  - deploy
+  - publish
+
+lint:
+  image: python:latest
+  stage: lint
+  script:
+    - pip install ruff
+    - ruff format sbcluster
+    - ruff check sbcluster
+  rules:
+    - if: $CI_COMMIT_BRANCH
+
+pages:
+  image: python:latest
+  stage: deploy
+  script:
+    - apt-get update && apt-get install -y git
+    - pip install sphinx furo
+    - pip install . --extra-index-url https://download.pytorch.org/whl/cpu
+    - sphinx-build -b html docs/source public
+  artifacts:
+    paths:
+      - public
+  rules:
+    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
+
+publish-to-pypi:
+  image: python:latest
+  stage: publish
+  script:
+    - python -m pip install --upgrade pip build twine setuptools-scm
+    - python -m build
+    - TWINE_PASSWORD=${PYPI_TOKEN} TWINE_USERNAME=__token__ python -m twine upload --verbose dist/*
+  rules: 
+    - if: '$CI_COMMIT_TAG =~ /^v.*$/'
+

sbcluster-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Felix Laplante <felixlaplante0@proton.me>
+
+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.

sbcluster-0.1.0/PKG-INFO

@@ -0,0 +1,12 @@
+Metadata-Version: 2.4
+Name: sbcluster
+Version: 0.1.0
+Summary: Spectral Bridges clustering algorithm
+Author-email: Félix Laplante <felixlaplante0@proton.me>
+Requires-Python: >=3.10
+License-File: LICENSE
+Requires-Dist: numpy
+Requires-Dist: scipy
+Requires-Dist: pydantic
+Requires-Dist: faiss-cpu
+Dynamic: license-file

sbcluster-0.1.0/README.md

@@ -0,0 +1,78 @@
+# 📊 Spectral Bridges
+
+**sbcluster** is a Python package that implements a novel clustering algorithm combining k-means and spectral clustering techniques, called **Spectral Bridges**. It leverages efficient affinity matrix computation and merges clusters based on a connectivity measure inspired by SVM's margin concept. This package is designed to provide robust clustering solutions, particularly suited for large datasets.
+
+---
+
+## ✨ Features
+
+- **Spectral Bridges Algorithm**: Integrates k-means and spectral clustering with efficient affinity matrix calculation for improved clustering results.
+- **Scalability**: Designed to handle large datasets by optimizing cluster formation through advanced affinity matrix computations.
+- **Customizable**: Parameters such as number of clusters, iterations, and random state allow flexibility in clustering configurations.
+- **Model selection**: Automatic model selection for number of nodes (m) according to a normalized eigengap metric.
+
+---
+
+## ⚡ Speed
+
+Spectral Bridges not only utilizes FAISS's efficient k-means implementation but also uses a scikit-learn method clone for centroid initialization, which is much faster than using scikit-learn's implementation (over 2x improvement).
+
+---
+
+## 🚀 Installation
+
+```bash
+pip install sbcluster
+```
+
+## 🔧 Usage
+
+### Example
+
+```python
+import numpy as np
+
+from sbcluster import SpectralBridges
+
+# Generate sample data
+np.random.seed(0)
+X = np.random.rand(100, 10)  # Replace with your dataset
+
+# Initialize and fit Spectral Bridges (with a specified number of nodes if needed) and random seed
+model = SpectralBridges(n_clusters=5, random_state=42)
+
+# Define range of nodes to evaluate, should be an iterable of integers, or None if n_nodes is already set.
+n_nodes_range = [10, 15, 20]
+
+# Find the optimal number of nodes for a given value of clusters
+# Modifies the instance attributes, returns a dict
+# If n_nodes_range is None, then the model selects using self.n_nodes if not None
+mean_ngaps = model.fit_select(X, n_nodes_range) 
+
+print("Optimal number of nodes:", model.n_nodes)
+print("Dict of mean normalized eigengaps:", mean_ngaps)
+
+# Predict clusters for new data points
+new_data = np.random.rand(20, 10)  # Replace with new data
+predicted_clusters = model.predict(new_data)
+
+print("Predicted clusters:", predicted_clusters)
+
+# With a custom number of nodes
+custom_model = SpectralBridges(n_clusters=5, n_nodes=12, p=1) # And a p-bridge affinity
+
+# Fit the model
+custom_model.fit(X)
+
+# Predict the same way...
+custom_predicted_clusters = custom_model.predict(new_data)
+
+print("Predicted clusters:", custom_predicted_clusters)
+```
+
+---
+
+## 📖 Learn More
+
+For tutorials, API reference, visit the official site:  
+👉 [sbcluster Documentation](https://felixlaplante0.gitlab.io/sbcluster)

sbcluster-0.1.0/docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = source
+BUILDDIR      = build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

sbcluster-0.1.0/docs/make.bat

@@ -0,0 +1,35 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=source
+set BUILDDIR=build
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.https://www.sphinx-doc.org/
+	exit /b 1
+)
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd

sbcluster-0.1.0/docs/source/_templates/autosummary/class.rst

@@ -0,0 +1,8 @@
+{{ fullname | escape | underline}}
+
+.. currentmodule:: {{ module }}
+
+.. autoclass:: {{ objname }}
+   :members:
+
+   .. automethod:: __init__

sbcluster-0.1.0/docs/source/conf.py

@@ -0,0 +1,46 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# For the full list of built-in configuration values, see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+
+
+import os
+
+release = os.getenv("CI_COMMIT_TAG", "v0.0.0")
+version = release.lstrip("v")
+
+
+project = "sbcluster"
+copyright = "2025, Félix Laplante"
+author = "Félix Laplante"
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+extensions = [
+    "sphinx.ext.autodoc",
+    "sphinx.ext.napoleon",
+    "sphinx.ext.viewcode",
+    "sphinx.ext.autosummary",
+]
+
+templates_path = ["_templates"]
+exclude_patterns = []
+
+autodoc_member_order = "bysource"
+autodoc_typehints = "description"
+autodoc_typehints_format = "short"
+autodoc_inherit_docstrings = True
+autosummary_generate = True
+add_module_names = False
+napoleon_use_ivar = True
+napoleon_attr_annotations = True
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+html_theme = "furo"
+html_static_path = ["_static"]

sbcluster-0.1.0/docs/source/index.rst

@@ -0,0 +1,71 @@
+Spectral Bridges
+================
+
+**sbcluster** is a Python package that implements a novel clustering algorithm combining k-means and spectral clustering techniques, called **Spectral Bridges**. It leverages efficient affinity matrix computation and merges clusters based on a connectivity measure inspired by SVM's margin concept. This package is designed to provide robust clustering solutions, particularly suited for large datasets.
+
+Features
+--------
+
+- **Spectral Bridges Algorithm**: Integrates k-means and spectral clustering with efficient affinity matrix calculation for improved clustering results.
+- **Scalability**: Designed to handle large datasets by optimizing cluster formation through advanced affinity matrix computations.
+- **Customizable**: Parameters such as number of clusters, iterations, and random state allow flexibility in clustering configurations.
+- **Model selection**: Automatic model selection for number of nodes (m) according to a normalized eigengap metric.
+
+Speed
+-----
+
+Spectral Bridges not only utilizes FAISS's efficient k-means implementation but also uses a scikit-learn method clone for centroid initialization which is much faster than using scikit-learn's implementation (over 2x improvement).
+
+Installation
+------------
+
+You can install the package via pip:
+
+.. code-block:: bash
+
+   pip install sbcluster
+
+Usage
+-----
+
+Example:
+
+.. code-block:: python
+
+   import numpy as np
+
+   from sbcluster import SpectralBridges
+
+   # Generate sample data
+   np.random.seed(0)
+   X = np.random.rand(100, 10)  # Replace with your dataset
+
+   # Initialize and fit Spectral Bridges (with a specified number of nodes if needed) and random seed
+   model = SpectralBridges(n_clusters=5, random_state=42)
+
+   # Define range of nodes to evaluate, should be an iterable of integers, or None if n_nodes is already set.
+   n_nodes_range = [10, 15, 20]
+
+   # Find the optimal number of nodes for a given value of clusters
+   mean_ngaps = model.fit_select(X, n_nodes_range) 
+   print("Optimal number of nodes:", model.n_nodes)
+   print("Dict of mean normalized eigengaps:", mean_ngaps)
+
+   # Predict clusters for new data points
+   new_data = np.random.rand(20, 10)  # Replace with new data
+   predicted_clusters = model.predict(new_data)
+   print("Predicted clusters:", predicted_clusters)
+
+   # With a custom number of nodes
+   custom_model = SpectralBridges(n_clusters=5, n_nodes=12, p=1) # And a p-bridge affinity
+   custom_model.fit(X)
+   custom_predicted_clusters = custom_model.predict(new_data)
+   print("Predicted clusters:", custom_predicted_clusters)
+
+API Reference
+-------------
+
+.. autoclass:: sbcluster._bridges.SpectralBridges
+   :members:
+   :undoc-members:
+   :show-inheritance:

sbcluster-0.1.0/pyproject.toml

@@ -0,0 +1,41 @@
+[project]
+name = "sbcluster"
+description = "Spectral Bridges clustering algorithm"
+authors = [{ name = "Félix Laplante", email = "felixlaplante0@proton.me" }]
+requires-python = ">=3.10"
+dependencies = ["numpy", "scipy", "pydantic", "faiss-cpu"]
+dynamic = ["version"]
+
+[build-system]
+requires = ["setuptools>=42", "setuptools-scm[toml]>=6.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools_scm]
+version_scheme = "post-release"
+local_scheme = "no-local-version"
+
+[tool.ruff]
+lint.select = [
+    "D",   # pydocstyle (docstring conventions)
+    "E",   # pycodestyle errors
+    "W",   # pycodestyle warnings
+    "F",   # Pyflakes
+    "I",   # isort
+    "UP",  # pyupgrade
+    "B",   # flake8-bugbear
+    "C4",  # flake8-comprehensions
+    "S",   # flake8-bandit (security)
+    "T20", # flake8-print
+    "PT",  # flake8-pytest-style
+    "Q",   # flake8-quotes
+    "RET", # flake8-return
+    "SIM", # flake8-simplify
+    "ARG", # flake8-unused-arguments
+    "ERA", # eradicate (commented code)
+    "PL",  # Pylint
+    "RUF", # Ruff-specific rules
+]
+lint.ignore = ["D417", "PLR0913"]
+
+[tool.ruff.lint.pydocstyle]
+convention = "google"

sbcluster-0.1.0/sbcluster/__init__.py

@@ -0,0 +1,4 @@
+from ._bridges import SpectralBridges  # noqa: D104
+from ._defs import ExpQuantileTransform
+
+__all__ = ["ExpQuantileTransform", "SpectralBridges"]

sbcluster-0.1.0/sbcluster/_bridges.py

@@ -0,0 +1,269 @@
+from collections.abc import Iterable
+from typing import Final, cast
+
+import faiss  # type: ignore
+import numpy as np
+from numpy.typing import NDArray
+from pydantic import ConfigDict, validate_call
+from scipy.linalg.blas import sgemm  # type: ignore
+
+from ._defs import (
+    AffinityTransform,
+    ExpQuantileTransform,
+    FloatGtZeroLtHalf,
+    IntStrictlyPositive,
+    NumStrictlyPositive,
+)
+from ._kmeans import KMeans
+from ._spectral import SpectralClustering
+
+# Constants
+DEFAULT_AFFINITY_TRANSFORM: Final = ExpQuantileTransform(0.1, 1e4)
+
+
+class SpectralBridges:
+    """Spectral Bridges clustering algorithm.
+
+    Attributes:
+        random_state (int | None): Determines random number generation for centroid
+            initialization.
+        n_clusters (int): The number of clusters to form.
+        n_nodes (int): Number of nodes or initial clusters.
+        p (float): Power of the alpha_i.
+        n_iter (int): Number of iterations to run the k-means algorithm.
+        n_local_trials (int or None): Number of seeding trials for centroids
+            initialization.
+        random_state (int | None): Determines random number generation for centroid
+            initialization.
+        affinity_transform (AffinityTransform): Affinity transform to apply to the
+            affinity matrix.
+        cluster_centers_ (list[NDArray[np.float32]] | None): Coordinates of cluster
+            centers.
+        eigvals_ (NDArray[np.float32 | np.float64] | None): The eigenvalues of the
+            (normalized) laplacian matrix.
+        ngap_ (float): The normalized eigengap.
+    """
+
+    n_clusters: int
+    n_nodes: int | None
+    p: float
+    n_iter: int
+    n_local_trials: IntStrictlyPositive | None
+    random_state: int | None
+    cluster_centers_: list[NDArray[np.float32]] | None
+    eigvals_: NDArray[np.float32 | np.float64] | None
+    ngap_: float | None
+    affinity_transform: AffinityTransform
+
+    @validate_call(config=ConfigDict(arbitrary_types_allowed=True))
+    def __init__(
+        self,
+        n_clusters: IntStrictlyPositive,
+        n_nodes: IntStrictlyPositive | None = None,
+        *,
+        p: NumStrictlyPositive = 2,
+        alpha: FloatGtZeroLtHalf = 0.1,
+        n_iter: IntStrictlyPositive = 20,
+        n_local_trials: IntStrictlyPositive | None = None,
+        random_state: int | None = None,
+        affinity_transform: AffinityTransform = DEFAULT_AFFINITY_TRANSFORM,
+    ):
+        """Initialize the Spectral Bridges model.
+
+        Args:
+            n_clusters  (IntStrictlyPositive): The number of clusters to form.
+            n_nodes  (IntStrictlyPositive | None): Number of nodes or initial clusters.
+            p (NumStrictlyPositive, optional): Power of the alpha_i. Defaults to 2.
+            alpha (FloatGtZeroLtHalf, optional): Quantile for affinity matrix
+                computation. Defaults to 0.1.
+            n_iter (int, optional): Number of iterations to run the k-means algorithm.
+                Defaults to 20.
+            n_local_trials (int or None, optional): Number of seeding trials for
+                centroids initialization.
+            random_state (int or None, optional): Determines random number generation
+                for centroid initialization.
+            affinity_transform (AffinityTransform, optional): Affinity transform
+                to apply to the affinity matrix. Defaults to DEFAULT_AFFINITY_TRANSFORM.
+        """
+        self.n_clusters = n_clusters
+        self.n_nodes = n_nodes
+        self.p = p
+        self.alpha = alpha
+        self.n_iter = n_iter
+        self.n_local_trials = n_local_trials
+        self.random_state = random_state
+        self.affinity_transform = affinity_transform
+        self.cluster_centers_ = None
+        self.eigvals_ = None
+        self.ngap_ = None
+
+        if self.n_nodes is not None and self.n_nodes <= self.n_clusters:
+            raise ValueError(
+                f"n_nodes must be greater than n_clusters, got {self.n_nodes} <= "
+                "{self.n_clusters}"
+            )
+
+    @validate_call(config=ConfigDict(arbitrary_types_allowed=True))
+    def fit(self, X: np.ndarray):
+        """Fit the Spectral Bridges model on the input data X.
+
+        Args:
+            X : numpy.ndarray
+                Input data to cluster.
+        """
+        if self.n_nodes is None:
+            raise ValueError("n_nodes must be provided")
+
+        kmeans = KMeans(
+            self.n_nodes,
+            self.n_iter,
+            self.n_local_trials,
+            self.random_state,
+        )
+        kmeans.fit(X)
+        centers = cast(NDArray[np.float32], kmeans.cluster_centers_)
+
+        affinity: NDArray[np.float64] = np.empty((self.n_nodes, self.n_nodes))
+
+        X_centered = [
+            np.array(
+                X[kmeans.labels_ == i]
+                - cast(NDArray[np.float32], kmeans.cluster_centers_)[i],
+                dtype=np.float32,
+                order="F",
+            )
+            for i in range(self.n_nodes)
+        ]
+
+        counts = np.array([X_centered[i].shape[0] for i in range(self.n_nodes)])
+        counts = counts[None, :] + counts[:, None]
+
+        for i in range(self.n_nodes):
+            segments = np.asfortranarray(centers - centers[i])
+            dists = np.einsum("ij,ij->i", segments, segments)
+            dists[i] = 1
+
+            projs = sgemm(1.0, X_centered[i], segments, trans_b=True)
+            np.clip(projs / dists, 0, None, out=projs)
+            projs = np.power(projs, self.p)
+
+            affinity[i] = projs.sum(axis=0)
+
+        affinity = np.power((affinity + affinity.T) / counts, 1 / self.p)
+
+        affinity = cast(NDArray[np.float64], self.affinity_transform(affinity))
+
+        spectralclustering = SpectralClustering(
+            self.n_clusters, self.n_iter, self.n_local_trials, self.random_state
+        )
+        spectralclustering.fit(affinity)
+
+        self.eigvals_ = spectralclustering.eigvals_
+        self.ngap_ = spectralclustering.ngap_
+        self.cluster_centers_ = [
+            centers[spectralclustering.labels_ == i] for i in range(self.n_clusters)
+        ]
+
+    @validate_call(config=ConfigDict(arbitrary_types_allowed=True))
+    def fit_select(
+        self,
+        X: np.ndarray,
+        n_nodes_range: Iterable[int] | None = None,
+        n_redo: IntStrictlyPositive = 10,
+    ) -> dict[int, float]:
+        """Selects and fits the best model from a range of possible node counts.
+
+        It evaluates the mean normalized eigengap (ngap) for each candidate.
+
+        For each `n_nodes` in `n_nodes_range`, multiple models are fit to the data,
+        and the one with the highest mean normalized eigengap over `n_redo` runs
+        is selected. The method then updates the current instance to use the
+        attributes of the best candidate model.
+
+        Args:
+            X (np.ndarray): The input data.
+            n_nodes_range (Iterable[int] | None): The range of possible node counts.
+            n_redo (int): The number of times to run the model.
+
+        Returns:
+            dict[int, float]: The mean normalized eigengap for each node count.
+        """
+        if n_nodes_range is None:
+            if self.n_nodes is None:
+                raise ValueError("n_nodes_range or self.n_nodes must be provided")
+            n_nodes_range = [self.n_nodes]
+
+        rng = np.random.default_rng(self.random_state)
+        max_int = np.iinfo(np.int32).max
+
+        best_candidate = None
+        best_mean_ngap = -1
+        mean_ngaps: dict[int, float] = {}
+
+        for n_nodes in n_nodes_range:
+            candidate = None
+            cum_ngap = 0
+
+            for _ in range(n_redo):
+                model = SpectralBridges(
+                    n_clusters=self.n_clusters,
+                    n_nodes=n_nodes,
+                    p=self.p,
+                    n_iter=self.n_iter,
+                    n_local_trials=self.n_local_trials,
+                    random_state=self.random_state,
+                    affinity_transform=self.affinity_transform,
+                )
+                model.fit(X)
+
+                cum_ngap += cast(float, model.ngap_)
+
+                if candidate is None or cast(float, model.ngap_) > cast(
+                    float, candidate.ngap_
+                ):
+                    candidate = model
+
+                self.random_state = int(rng.integers(max_int + 1))
+
+            mean_ngap = cum_ngap / n_redo
+            mean_ngaps[n_nodes] = mean_ngap
+
+            if mean_ngap > best_mean_ngap:
+                best_candidate = candidate
+                best_mean_ngap = mean_ngap
+
+        self.__dict__.update(best_candidate.__dict__)
+
+        return mean_ngaps
+
+    @validate_call(config=ConfigDict(arbitrary_types_allowed=True))
+    def predict(self, x: np.ndarray) -> np.ndarray:
+        """Predict the nearest cluster index for each input data point x.
+
+        Args:
+            x (np.ndarray): The input data.
+
+        Raises:
+            ValueError: If `x` contains inf or NaN values.
+
+        Returns:
+            NDArray[np.int32]: The predicted cluster indices.
+        """
+        if np.isinf(x).any():
+            raise ValueError("x must not contain inf values")
+        if np.isnan(x).any():
+            raise ValueError("x must not contain NaN values")
+
+        centers = cast(list[NDArray[np.float32]], self.cluster_centers_)
+
+        cluster_centers = np.vstack(centers)
+        cluster_cutoffs = np.cumsum([cluster.shape[0] for cluster in centers])
+
+        index = faiss.IndexFlatL2(x.shape[1])
+        index.add(cluster_centers.astype(np.float32))  # type: ignore
+        winners = index.search(x.astype(np.float32), 1)[1].ravel()  # type: ignore
+
+        return cast(
+            NDArray[np.int32],
+            np.searchsorted(cluster_cutoffs, winners, side="right"),  # type: ignore
+        )

sbcluster-0.1.0/sbcluster/_defs.py

@@ -0,0 +1,95 @@
+from typing import Annotated, Protocol, TypeAlias, runtime_checkable
+
+import numpy as np
+from numpy.typing import NDArray
+from pydantic import AfterValidator, ConfigDict, validate_call
+
+
+# Validators
+def is_strict_pos(x: int | float) -> int | float:
+    """Checks if the argument is strictly positive.
+
+    Args:
+        x (int | float): The input number.
+
+    Raises:
+        ValueError: If the number is not strictly positive.
+
+    Returns:
+        int | float | torch.Tensor: The output number or tensor.
+    """
+    if x <= 0:
+        raise ValueError(f"Expected strictly positive number, got {x}")
+    return x
+
+
+def is_gt_zero_lt_half(x: float) -> float:
+    """Checks if the argument is between 0 and 1/2.
+
+    Args:
+        x (float): The input number.
+
+    Raises:
+        ValueError: If the number is not between 0 and 1/2.
+
+    Returns:
+        float: The output number.
+    """
+    if x <= 0 or x >= 0.5:  # noqa: PLR2004
+        raise ValueError(f"Expected number > 0 and < 1/2, got {x}")
+    return x
+
+
+Num: TypeAlias = int | float
+IntStrictlyPositive = Annotated[int, AfterValidator(is_strict_pos)]
+NumStrictlyPositive = Annotated[Num, AfterValidator(is_strict_pos)]
+FloatGtZeroLtHalf = Annotated[float, AfterValidator(is_gt_zero_lt_half)]
+
+
+# Protocols
+@runtime_checkable
+class AffinityTransform(Protocol):
+    """Protocol for affinity transforms.
+
+    Use this protocol to define custom affinity transforms.
+    """
+
+    def __call__(
+        self, x: NDArray[np.float32 | np.float64]
+    ) -> NDArray[np.float32 | np.float64]: ...
+
+
+# Transformations
+
+
+class ExpQuantileTransform(AffinityTransform):
+    """Exponential quantile transform.
+
+    Attributes:
+        alpha (float): Quantile for affinity matrix computation.
+        mult_factor (int | float): Scaling parameter for affinity matrix computation.
+    """
+
+    alpha: float
+    mult_factor: int | float
+
+    @validate_call(config=ConfigDict(arbitrary_types_allowed=True))
+    def __init__(
+        self, alpha: FloatGtZeroLtHalf = 0.1, mult_factor: NumStrictlyPositive = 1e4
+    ):
+        """Initialize the Exponential quantile transform.
+
+        Args:
+            alpha (FloatGtZeroLtHalf): Quantile for affinity matrix computation.
+            mult_factor (NumStrictlyPositive): Scaling parameter for affinity matrix
+                computation.
+        """
+        self.alpha = alpha
+        self.mult_factor = mult_factor
+
+    def __call__(
+        self, x: NDArray[np.float32 | np.float64]
+    ) -> NDArray[np.float32 | np.float64]:
+        q1, q2 = np.quantile(x, [self.alpha, 1 - self.alpha])
+        gamma = np.log(self.mult_factor) / (q2 - q1)
+        return np.exp(gamma * (x - x.max()))

sbcluster-0.1.0/sbcluster/_kmeans.py

@@ -0,0 +1,159 @@
+from typing import cast
+
+import faiss  # type: ignore
+import numpy as np
+from numpy.typing import NDArray
+from pydantic import ConfigDict, validate_call
+from scipy.linalg.blas import sgemm  # type: ignore
+
+
+class KMeans:
+    """K-means clustering using FAISS.
+
+    Attributes:
+        cluster_centers_  (NDArray[np.float32] | None): Coordinates of cluster centers.
+        labels_ (NDArray[np.int32] | None): Labels of each point (index) in X.
+
+    Methods:
+    --------
+    fit(X):
+        Run k-means clustering on the input data X.
+    """
+
+    cluster_centers_: NDArray[np.float32] | None
+    labels_: NDArray[np.int32] | None
+
+    def __init__(
+        self,
+        n_clusters: int,
+        n_iter: int,
+        n_local_trials: int | None,
+        random_state: int | None,
+    ):
+        """Initializes the KMeans class.
+
+        Args:
+            n_clusters (int): The number of clusters to form.
+            n_iter (int): The number of iterations to run the k-means
+                algorithm.
+            n_local_trials  (int | None): The number of seeding trials for
+                centroids initialization.
+            random_state (int | None) Determines random number generation for
+                centroid initialization.
+        """
+        self.n_clusters = n_clusters
+        self.n_iter = n_iter
+        self.n_local_trials = n_local_trials
+        self.random_state = random_state
+        self.cluster_centers_ = None
+        self.labels_ = None
+
+    @staticmethod
+    def _dists(
+        X: NDArray[np.float32], y: NDArray[np.float32], XX: NDArray[np.float32]
+    ) -> NDArray[np.float32]:
+        """Computes the pairwise distances between a fixed data matrix and some points.
+
+        Args:
+            X (NDArray[np.float32]): The fixed data matrix.
+            y (NDArray[np.float32]): The non fixed points.
+            XX (NDArray[np.float32]): The fixed matrix squared norm.
+
+        Returns:
+            NDArray[np.float32]: The computed pairwise distances.
+        """
+        yy = np.einsum("ij,ij->i", y, y)
+        dists = XX - sgemm(2.0, X, y, trans_b=True) + yy
+        np.clip(dists, 0, None, out=dists)
+        return dists
+
+    def _init_centroids(self, X: NDArray[np.float32]) -> NDArray[np.float32]:
+        """Initializes the centroids in a K-means++ fashion.
+
+        Args:
+            X (NDArray[np.float32]): The fixed data matrix.
+
+        Returns:
+            NDArray[np.float32]: The initialized centroids.
+        """
+        rng = np.random.default_rng(self.random_state)
+
+        centroids = np.empty((self.n_clusters, X.shape[1]), dtype=X.dtype)
+        centroids[0] = X[rng.integers(X.shape[0])]
+
+        XX = np.einsum("ij,ij->i", X, X)[:, None]
+
+        dists = self._dists(X, centroids[0:1], XX).ravel()
+        inertia = dists.sum()
+
+        if self.n_local_trials is None:
+            self.n_local_trials = 2 + int(np.log(self.n_clusters))
+
+        for i in range(1, self.n_clusters):
+            candidate_ids = rng.choice(
+                X.shape[0], size=self.n_local_trials, p=dists / inertia
+            )
+            candidates = np.asfortranarray(X[candidate_ids])
+
+            current_candidates_dists = self._dists(X, candidates, XX)
+            candidates_dists = np.minimum(current_candidates_dists, dists[:, None])
+
+            inertias = candidates_dists.sum(axis=0)
+            best_inertia = inertias.argmin()
+            best_candidate = candidate_ids[best_inertia]
+            dists = candidates_dists[:, best_inertia]
+            inertia = inertias[best_inertia]
+
+            centroids[i] = X[best_candidate]
+
+        return centroids
+
+    @staticmethod
+    def _validate_X(X: NDArray[np.float32 | np.float64]) -> NDArray[np.float32]:
+        """Validates and converts the data matrix.
+
+        Args:
+            X (NDArray[np.float32  |  np.float64]): The fixed data matrix.
+
+        Raises:
+            ValueError: If `X``contains inf values.
+            ValueError: If `X``contains NaN values.
+
+        Returns:
+            NDArray[np.float32]: The validated and converted data matrix.
+        """
+        if np.isinf(X).any():
+            raise ValueError("X must not contain inf values")
+        if np.isnan(X).any():
+            raise ValueError("X must not contain NaN values")
+
+        return np.array(X, dtype=np.float32, order="F")
+
+    @validate_call(config=ConfigDict(arbitrary_types_allowed=True))
+    def fit(self, X: np.ndarray):
+        """Run k-means clustering on the input data X.
+
+        Args:
+            X (np.ndarray): Input data matrix to cluster.
+        """
+        X_f32 = self._validate_X(X)
+
+        index = faiss.IndexFlatL2(X.shape[1])
+        kmeans = faiss.Clustering(X.shape[1], self.n_clusters)
+
+        init_centroids = self._init_centroids(X_f32)
+
+        kmeans.centroids.resize(init_centroids.size)
+        faiss.copy_array_to_vector(init_centroids.ravel(), kmeans.centroids)  # type: ignore
+        kmeans.niter = self.n_iter
+        kmeans.min_points_per_centroid = 0
+        kmeans.max_points_per_centroid = -1
+        kmeans.train(X_f32, index)  # type: ignore
+
+        self.cluster_centers_ = cast(
+            NDArray[np.float32],
+            faiss.vector_to_array(kmeans.centroids).reshape(  # type: ignore
+                self.n_clusters, X.shape[1]
+            ),
+        )
+        self.labels_ = cast(NDArray[np.int32], index.search(X_f32, 1)[1].ravel())  # type: ignore

sbcluster-0.1.0/sbcluster/_spectral.py

@@ -0,0 +1,84 @@
+from typing import cast
+
+import numpy as np
+from numpy.typing import NDArray
+from scipy.sparse.csgraph import laplacian  # type: ignore
+
+from ._kmeans import KMeans
+
+
+class SpectralClustering:
+    """Spectral clustering based on Laplacian matrix.
+
+    Attributes:
+        n_local_trials  (int | None): The number of seeding trials for
+            centroids initialization.
+        random_state (int | None) Determines random number generation for
+            centroid initialization.
+        labels_ (NDArray[np.int32] | None): Labels of each point (index) in the affinity
+            matrix.
+        eigvals_ (NDArray[np.float32 | np.float64] | None): The eigenvalues of the
+            (normalized) laplacian matrix.
+        ngap_ (float): The normalized eigengap.
+    """
+
+    n_iter: int
+    n_local_trials: int | None
+    random_state: int | None
+    labels_: NDArray[np.int32] | None
+    eigvals_: NDArray[np.float32 | np.float64] | None
+    ngap_: float | None
+
+    def __init__(
+        self,
+        n_clusters: int,
+        n_iter: int,
+        n_local_trials: int | None,
+        random_state: int | None,
+    ):
+        """Initializes the class.
+
+        Args:
+            n_clusters (int): The number of clusters to form.
+            n_iter (int): The number of iterations to run the k-means
+                algorithm.
+            n_local_trials  (int | None): The number of seeding trials for
+                centroids initialization.
+            random_state (int | None) Determines random number generation for
+                centroid initialization.
+            random_state (int | None): Determines random number generation for centroid
+                initialization.
+        """
+        self.n_clusters = n_clusters
+        self.random_state = random_state
+        self.n_iter = n_iter
+        self.n_local_trials = n_local_trials
+        self.labels_ = None
+        self.eigvals_ = None
+        self.ngap_ = None
+
+    def fit(self, affinity: NDArray[np.float32 | np.float64]):
+        """Fit the spectral clustering model on the affinity matrix.
+
+        Parameters:
+        -----------
+        affinity (NDArray[np.float32]): Affinity matrix representing pairwise similarity
+            between points.
+        """
+        L = cast(NDArray[np.float32 | np.float64], laplacian(affinity, normed=True))
+
+        self.eigvals_, eigvecs = cast(
+            tuple[NDArray[np.float32 | np.float64], ...],
+            np.linalg.eigh(L),  # type: ignore
+        )
+        eigvecs = eigvecs[:, : self.n_clusters]
+        eigvecs /= np.linalg.norm(eigvecs, axis=1)[:, None]
+        kmeans = KMeans(
+            self.n_clusters, self.n_iter, self.n_local_trials, self.random_state
+        )
+        kmeans.fit(eigvecs)
+
+        self.ngap_ = (
+            self.eigvals_[self.n_clusters] - self.eigvals_[self.n_clusters - 1]
+        ) / self.eigvals_[self.n_clusters - 1]
+        self.labels_ = kmeans.labels_

sbcluster-0.1.0/sbcluster.egg-info/PKG-INFO

@@ -0,0 +1,12 @@
+Metadata-Version: 2.4
+Name: sbcluster
+Version: 0.1.0
+Summary: Spectral Bridges clustering algorithm
+Author-email: Félix Laplante <felixlaplante0@proton.me>
+Requires-Python: >=3.10
+License-File: LICENSE
+Requires-Dist: numpy
+Requires-Dist: scipy
+Requires-Dist: pydantic
+Requires-Dist: faiss-cpu
+Dynamic: license-file

sbcluster-0.1.0/sbcluster.egg-info/SOURCES.txt

@@ -0,0 +1,20 @@
+.gitlab-ci.yml
+LICENSE
+README.md
+pyproject.toml
+docs/Makefile
+docs/make.bat
+docs/source/conf.py
+docs/source/index.rst
+docs/source/_static/.gitkeep
+docs/source/_templates/autosummary/class.rst
+sbcluster/__init__.py
+sbcluster/_bridges.py
+sbcluster/_defs.py
+sbcluster/_kmeans.py
+sbcluster/_spectral.py
+sbcluster.egg-info/PKG-INFO
+sbcluster.egg-info/SOURCES.txt
+sbcluster.egg-info/dependency_links.txt
+sbcluster.egg-info/requires.txt
+sbcluster.egg-info/top_level.txt

sbcluster-0.1.0/sbcluster.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

sbcluster-0.1.0/sbcluster.egg-info/requires.txt

@@ -0,0 +1,4 @@
+numpy
+scipy
+pydantic
+faiss-cpu

sbcluster-0.1.0/sbcluster.egg-info/top_level.txt

@@ -0,0 +1 @@
+sbcluster

sbcluster-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+