tribble-clustering 0.1.0__tar.gz

tribble_clustering-0.1.0/.github/workflows/publish.yaml

@@ -0,0 +1,39 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - 'v*'
+
+jobs:
+  build-n-publish:
+    name: Build and publish Python distribution to PyPI
+    runs-on: ubuntu-latest
+    permissions:
+      # This permission is required for trusted publishing (OIDC)
+      id-token: write
+      contents: read
+
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Set up Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: "3.10"
+
+    - name: Install build dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install build
+
+    - name: Build binary wheel and source tarball
+      run: python -m build
+
+    - name: Publish package distributions to PyPI
+      uses: pypa/gh-action-pypi-publish@release/v1
+      # Note: For this to work with Trusted Publishing, the user must configure
+      # the repository on PyPI to trust this GitHub workflow.
+      # If using an API token, uncomment the following line and set up secrets.
+      # with:
+      #   password: ${{ secrets.PYPI_API_TOKEN }}

tribble_clustering-0.1.0/.github/workflows/test.yml

@@ -0,0 +1,32 @@
+name: Test
+
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.8", "3.9", "3.10", "3.11", "3.12","3.13","3.14"]
+
+    steps:
+    - uses: actions/checkout@v4
+    
+    - name: Set up Python ${{ matrix.python-version }}
+      uses: actions/setup-python@v5
+      with:
+        python-version: ${{ matrix.python-version }}
+        
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install pytest
+        pip install .
+        
+    - name: Run tests
+      run: |
+        pytest tests

tribble_clustering-0.1.0/.gitignore

@@ -0,0 +1,148 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so may as well local ignore them.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or app, you might want to share your Python version
+.python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or even
+#   fail to install them. In that case, the lock file should be added to .gitignore.
+#Pipfile.lock
+
+# poetry
+#   Similar to Pipenv, see https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+
+# pdm
+#   Similar to Pipenv, see https://pdm.fming.dev/#usage/commit-your-pdmlock-file-to-version-control
+#pdm.lock
+
+# PEP 582; used by e.g. github.com/fannheyward/coc-pyright
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+.idea/

tribble_clustering-0.1.0/.junie/memory/language.json

@@ -0,0 +1 @@
+[]

tribble_clustering-0.1.0/.junie/memory/memory.version

@@ -0,0 +1 @@
+3.0

tribble_clustering-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Scott Phillips
+
+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.

tribble_clustering-0.1.0/PKG-INFO

@@ -0,0 +1,41 @@
+Metadata-Version: 2.4
+Name: tribble-clustering
+Version: 0.1.0
+Summary: An optimized Visualization Assessment Tendency (VAT/IVAT) and fuzzy clustering (FCM) package
+Project-URL: Homepage, https://github.com/fundthmcalculus/clustering
+Project-URL: Bug Tracker, https://github.com/fundthmcalculus/clustering/issues
+Author-email: Scott Phillips <polygonguru@gmail.com>
+License-File: LICENSE
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.8
+Requires-Dist: numba-progress==1.2.0
+Requires-Dist: numba==0.65.1
+Requires-Dist: numpy==2.4.6
+Requires-Dist: scipy==1.17.1
+Provides-Extra: dev
+Requires-Dist: matplotlib; extra == 'dev'
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: ucimlrepo; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Clustering Package
+
+A simple Python package for clustering tasks.
+
+## Installation
+
+```bash
+pip install clustering-pkg
+```
+
+## Usage
+
+```python
+from clustering import simple_cluster
+
+data = [1, 2, 10, 11]
+result = simple_cluster(data, threshold=5)
+print(result) # [[1, 2], [10, 11]]
+```

tribble_clustering-0.1.0/README.md

@@ -0,0 +1,19 @@
+# Clustering Package
+
+A simple Python package for clustering tasks.
+
+## Installation
+
+```bash
+pip install clustering-pkg
+```
+
+## Usage
+
+```python
+from clustering import simple_cluster
+
+data = [1, 2, 10, 11]
+result = simple_cluster(data, threshold=5)
+print(result) # [[1, 2], [10, 11]]
+```

tribble_clustering-0.1.0/pyproject.toml

@@ -0,0 +1,39 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "tribble-clustering"
+version = "0.1.0"
+authors = [
+  { name="Scott Phillips", email="polygonguru@gmail.com" },
+]
+description = "An optimized Visualization Assessment Tendency (VAT/IVAT) and fuzzy clustering (FCM) package"
+readme = "README.md"
+requires-python = ">=3.8"
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+]
+dependencies = [
+    "numba==0.65.1",
+    "numpy==2.4.6",
+    "scipy==1.17.1",
+    "numba-progress==1.2.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "ucimlrepo",
+    "matplotlib",
+    "pytest"
+]
+
+[project.urls]
+"Homepage" = "https://github.com/fundthmcalculus/clustering"
+"Bug Tracker" = "https://github.com/fundthmcalculus/clustering/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/clustering"]
+

tribble_clustering-0.1.0/src/clustering/__init__.py

@@ -0,0 +1,6 @@
+from .pvat import (
+    compute_ordered_dis_njit_merge,
+    vat_prim_mst,
+    vat_prim_mst_seq,
+    compute_ivat,
+)

tribble_clustering-0.1.0/src/clustering/fcm.py

@@ -0,0 +1,84 @@
+from typing import Optional, Literal
+
+import numpy as np
+from numpy import ndarray
+from scipy.optimize import minimize
+
+
+def _j_w_c(x: np.ndarray, c: np.ndarray, m: float) -> float:
+    """Compute the weighted sum of squared distances"""
+    w_ij = _get_weights(c, m, x)
+    j_wc = np.sum(
+        w_ij**m * np.sum((x[:, np.newaxis, :] - c[np.newaxis, :, :]) ** 2.0, axis=2),
+        axis=None,
+    )
+
+    return j_wc
+
+
+def _get_weights(c: ndarray, m: float, x: ndarray) -> ndarray:
+    distances = np.linalg.norm(x[:, np.newaxis, :] - c[np.newaxis, :, :], axis=2)
+    distances_to_jj = distances[:, :, np.newaxis]
+    distances_to_all = distances[:, np.newaxis, :]
+    w_ij = 1.0 / np.sum((distances_to_jj / distances_to_all) ** (2.0 / (m - 1)), axis=2)
+    w_ij = np.where(np.isnan(w_ij) | np.isinf(w_ij), 0.0, w_ij)
+    return w_ij
+
+
+def _get_v_ij(w_ij: ndarray, m: float, x: ndarray) -> ndarray:
+    v_ij = np.sum(w_ij[:, :, np.newaxis]**m * (x[:, np.newaxis, :]), axis=0) / np.sum(w_ij ** m, axis=0)[:, np.newaxis]
+    return v_ij
+
+
+def fuzzy_c_means(
+    x: np.ndarray,
+    n: int,
+    m: float = 2.0,
+    *,
+    method: Literal["gd","iter"] = "iter",
+    indices: Optional[np.ndarray | list[int]] = None,
+    initial_guess: Optional[np.ndarray] = None
+) -> tuple[np.ndarray, np.ndarray]:
+    """Compute the fuzzy c-means"""
+    if initial_guess is not None and indices is not None:
+        raise ValueError("initial_guess and indices cannot both be provided")
+    # 1. Create the candidate centers
+    if indices is not None:
+        c = x[indices, :]
+    elif initial_guess is not None:
+        if initial_guess.shape != (n, x.shape[1]):
+            raise ValueError(
+                f"initial_guess must have shape ({n}, {x.shape[1]}), "
+                f"got {initial_guess.shape}"
+            )
+        c = initial_guess
+    else:
+        indices = np.random.choice(x.shape[0], size=n * 2, replace=False)
+        c = x[indices, :]
+        # Combine every two rows into one so no cluster center exactly matches a data-point
+        c = c.reshape(n, 2, x.shape[1]).mean(axis=1)
+
+    # 2. Iteratively refine with a gradient descent method
+    def optim_j_w_c(c_opt: np.ndarray) -> float:
+        c_reshaped = c_opt.reshape(n, x.shape[1])
+        return _j_w_c(x, c_reshaped, m)
+
+    if method == "gd":
+        result = minimize(optim_j_w_c, c.flatten(), method="BFGS")
+        c = result.x.reshape(n, x.shape[1])
+    elif method == "iter":
+        # Max of 100 iterations
+        for _ in range(100):
+            w_ij = _get_weights(c, m, x)
+            c_new = _get_v_ij(w_ij, m, x)
+            if np.allclose(c_new, c, rtol=1e-5, atol=1e-8):
+                break
+            c = c_new
+    else:
+        raise ValueError(f"Invalid method: {method}. Choose 'gd' or 'iter'.")
+
+    # Calculate membership matrix
+    w_ij = _get_weights(c, m, x)
+
+    # 3. Return the center-points
+    return c, w_ij

tribble_clustering-0.1.0/src/clustering/pvat.py

@@ -0,0 +1,278 @@
+import heapq
+
+from numba import njit, prange
+import numpy as np
+from numba_progress import ProgressBar
+from numpy import ndarray
+
+
+def compute_ivat(
+    matrix_of_pairwise_distance: np.ndarray, inplace: bool = False
+) -> tuple[np.ndarray, np.ndarray, np.ndarray, np.ndarray]:
+    """
+    Computes the improved VAT (IVAT) for the provided dissimilarity (distance) matrix
+    :param matrix_of_pairwise_distance: dissimilarity matrix, typically an L2-norm matrix, it must be symmetric and positive semi-definite
+    :param inplace: whether to perform the computation in-place on the input matrix
+    :return: tuple of the IVAT matrix, the VAT matrix, the sequence of IVAT indices, and the sequence of permutation (VAT) indices
+    """
+    d_star, p_seq, as_seq = compute_ordered_dis_njit_merge(
+        matrix_of_pairwise_distance, inplace=inplace
+    )
+    N = d_star.shape[0]
+    if not inplace:
+        d_p_star = np.zeros(d_star.shape, dtype=d_star.dtype)
+    else:
+        d_p_star = d_star
+    argmin_seq = []
+    for r in range(1, N):
+        jj = np.argmin(d_star[r, :r])
+        # TODO - Get from the prim-mst sequence?
+        # jj = as_seq[r-1]
+        argmin_seq.append(jj)
+
+        # TODO - Handle doing just upper-triangular matrix for memory savings?
+        d_p_star[r, jj] = d_star[r, jj]
+        d_p_star[jj, r] = d_star[r, jj]
+        for c in range(r):
+            if c != jj:
+                d_p_star[c, r] = d_p_star[r, c] = max(d_star[r, jj], d_p_star[jj, c])
+
+    return d_p_star, d_star, argmin_seq, p_seq
+
+
+def compute_vat(matrix_of_pairwise_distance: np.ndarray, inplace: bool = False) -> tuple[np.ndarray, np.ndarray]:
+    """
+    Computes the visualization assessment of cluster tendency (VAT) for the provided dissimilarity (distance) matrix
+    :param matrix_of_pairwise_distance: dissimilarity matrix, typically an L2-norm matrix, it must be symmetric and positive semi-definite
+    :param inplace: whether to perform the computation in-place on the input matrix
+    :return: tuple of the permuted distance (VAT) matrix and the permutation (VAT) sequence
+    """
+    d_star, p_seq, as_seq = compute_ordered_dis_njit_merge(
+        matrix_of_pairwise_distance, inplace=inplace
+    )
+    return d_star, p_seq
+
+
+@njit(cache=True, parallel=True, nogil=True)
+def compute_ordered_dis_njit_merge(
+    matrix_of_pairwise_distance: np.ndarray,
+    inplace: bool = False,
+    progress_bar: ProgressBar | None = None,
+) -> tuple[np.ndarray, list[int], list[int]]:
+    n = matrix_of_pairwise_distance.shape[0]
+    if inplace:
+        ordered_matrix = matrix_of_pairwise_distance
+    else:
+        ordered_matrix: np.ndarray = np.zeros(
+            matrix_of_pairwise_distance.shape, dtype=matrix_of_pairwise_distance.dtype
+        )
+    p, q = vat_prim_mst(matrix_of_pairwise_distance, progress_bar=progress_bar)
+    # Step 3 - since this is symmetric, we only have to do half
+    n_bit_mask = int(np.ceil(n / 8))
+    # Boolean is stored as a byte, so this is smaller
+    visited = np.zeros((n, n_bit_mask), dtype=np.uint8)
+
+    if progress_bar is not None:
+        progress_bar.set(0)
+
+    if inplace:
+        # Due to loop-walking, we cannot use the parallel operations since we cannot know a-priori which loops are different.
+        for ij in range(n):
+            shuffle_ordered_column(n, ij, ordered_matrix, p, visited)
+            if progress_bar is not None:
+                progress_bar.update(1)
+    else:
+        for ij in prange(n):
+            for jk in range(ij, n):
+                ordered_matrix[ij, jk] = ordered_matrix[jk, ij] = (
+                    matrix_of_pairwise_distance[p[ij], p[jk]]
+                )
+                if progress_bar is not None:
+                    progress_bar.update(1)
+
+    # Step 4 - since this is symmetric, we only have to do half
+    return ordered_matrix, p, q
+
+
+@njit(cache=True)
+def shuffle_ordered_column(
+    n: int, ij: int, ordered_matrix: ndarray, p: ndarray, visited: ndarray
+):
+    for jk in range(ij, n):
+        if _get_bit(visited, ij, jk):
+            continue
+        # Walk this loop, and store which visited
+        r0, c0 = ij, jk
+        r1, c1 = -1, -1
+        p0 = ordered_matrix[r0, c0]
+        while r1 != ij or c1 != jk:
+            r1, c1 = p[r0], p[c0]
+            _set_bit(visited, r0, c0)
+            _set_bit(visited, c0, r0)
+            ordered_matrix[r0, c0] = ordered_matrix[c0, r0] = ordered_matrix[r1, c1]
+            # Next step!
+            r0, c0 = r1, c1
+        # Close the final block
+        ordered_matrix[r0, c0] = ordered_matrix[c0, r0] = p0
+        _set_bit(visited, r0, c0)
+        _set_bit(visited, c0, r0)
+
+
+@njit(cache=True)
+def _set_bit(bitmask: np.ndarray, row: int, col: int) -> None:
+    bitmask[row, col // 8] |= 1 << (col % 8)
+
+
+@njit(cache=True)
+def _get_bit(bitmask: np.ndarray, row: int, col: int) -> int:
+    return (bitmask[row, col // 8] >> (col % 8)) & 1
+
+
+@njit(cache=True)
+def vat_prim_mst(
+    adj: np.ndarray, progress_bar: ProgressBar | None = None
+) -> tuple[np.ndarray, np.ndarray]:
+    n: int = len(adj)
+
+    # Find the column of the maximum value.
+    max_adj: np.signedinteger = np.argmax(adj)
+    src_i: np.signedinteger = max_adj // n
+    src_j: np.signedinteger = max_adj % n
+    src_key = adj[src_i, src_j]
+
+    # Create a list for keys and initialize all keys as infinite (INF)
+    key: np.ndarray = np.full(n, np.inf, dtype=adj.dtype)
+
+    # To store the parent array which, in turn, stores MST
+    parent: np.ndarray = np.full(n, -1, dtype=np.int32)
+
+    # To keep track of vertices included in MST
+    in_mst: np.ndarray = np.full(n, False, dtype=np.bool_)
+
+    # Insert the source itself into the priority queue and initialize its key as 0
+    pq: list[tuple[float, np.signedinteger, np.signedinteger]] = [
+        (src_key, src_i, src_j)
+    ]  # Priority queue to store vertices that are being processed
+    key[src_i] = src_key
+
+    # The final sequence of vertices in MST
+    heap_seq: np.ndarray = np.zeros(n, dtype=np.int32)
+    heap_seq_idx: int = 0
+
+    # Parent sequences of vertices in MST (for iVAT)
+    parent_seq: np.ndarray = np.zeros(n, dtype=np.int32)
+    parent_seq_idx: int = 0
+
+    # Preallocated
+    vertices: np.ndarray = np.arange(n)
+
+    # Loop until the priority queue becomes empty
+    while pq:
+        # The first vertex in the pair is the minimum key vertex
+        # Extract it from the priority queue
+        # The vertex label is stored in the second of the pair
+        w, u, v0 = heapq.heappop(pq)
+
+        # Different key values for the same vertex may exist in the priority queue.
+        # The one with the least key value is always processed first.
+        # Therefore, ignore the rest.
+        if in_mst[u]:
+            continue
+
+        in_mst[u] = True  # Include the vertex in MST
+        heap_seq[heap_seq_idx] = u
+        heap_seq_idx += 1
+
+        parent_seq[parent_seq_idx] = v0
+        parent_seq_idx += 1
+
+        if progress_bar is not None:
+            progress_bar.update(1)
+
+        # Iterate through all adjacent vertices of a vertex
+        # Parallel processing of adjacent vertices
+        mask = (vertices != u) & ~in_mst & (key[vertices] >= adj[u, vertices])
+        key[mask] = adj[u, mask]
+        for v in vertices[mask]:
+            heapq.heappush(pq, (key[v], v, heap_seq_idx))
+            parent[v] = u
+
+    return heap_seq, parent_seq
+
+
+@njit(cache=True)
+def vat_prim_mst_seq(samples: np.ndarray) -> np.ndarray:
+    n = len(samples)
+
+    # Find the column of the maximum value.
+    max_adj = -np.inf
+    max_idx = (-1, -1)
+    for ij in range(n):
+        for jk in range(ij, n):
+            cur_dist = _get_dist(samples, ij, jk)
+            if cur_dist > max_adj:
+                max_adj = cur_dist
+                max_idx = (ij, jk)
+
+    src = max_idx[0]
+    src_key = max_adj
+
+    # Create a list for keys and initialize all keys as infinite (INF)
+    key: np.ndarray = np.full(n, float("inf"))
+
+    # To store the parent array which, in turn, stores MST
+    parent: np.ndarray = np.full(n, -1)
+
+    # To keep track of vertices included in MST
+    in_mst = np.full(n, False)
+
+    # Insert the source itself into the priority queue and initialize its key as 0
+    pq: list[tuple[float, int]] = [
+        (src_key, src)
+    ]  # Priority queue to store vertices that are being processed
+    key[src] = src_key
+
+    # The final sequence of vertices in MST
+    heap_seq: np.ndarray = np.zeros(n, dtype=np.int32)
+    heap_seq_idx = 0
+
+    # Preallocated
+    vertices = np.arange(n)
+
+    # Loop until the priority queue becomes empty
+    while pq:
+        # The first vertex in the pair is the minimum key vertex
+        # Extract it from the priority queue
+        # The vertex label is stored in the second of the pair
+        u = heapq.heappop(pq)[1]
+
+        # Different key values for the same vertex may exist in the priority queue.
+        # The one with the least key value is always processed first.
+        # Therefore, ignore the rest.
+        if in_mst[u]:
+            continue
+
+        in_mst[u] = True  # Include the vertex in MST
+        heap_seq[heap_seq_idx] = u
+        heap_seq_idx += 1
+
+        # Iterate through all adjacent vertices of a vertex
+        # Parallel processing of adjacent vertices
+
+        mask = (
+            (vertices != u)
+            & ~in_mst
+            & (key[vertices] > _get_dist(samples, u, vertices))
+        )
+        key[mask] = _get_dist(samples, u, vertices[mask])
+        for v in vertices[mask]:
+            heapq.heappush(pq, (key[v], v))
+            parent[v] = u
+
+    return heap_seq
+
+
+@njit(cache=True)
+def _get_dist(samples: np.ndarray, idx1: int, idx2: int) -> float:
+    diff = samples[idx1, :] - samples[idx2, :]
+    return np.sqrt(np.sum(np.square(diff)))

tribble_clustering-0.1.0/src/clustering/util.py

@@ -0,0 +1,17 @@
+import numpy as np
+from numba import prange, njit
+
+
+@njit(cache=True, parallel=True, nogil=True)
+def pairwise_distances(data: np.ndarray) -> np.ndarray:
+    is_1d: bool = data.shape[1] == 1
+    if is_1d:
+        # Vectorized computation for 1D case
+        return np.abs(data.T - data)
+    else:
+        dist_arr = np.zeros((data.shape[0], data.shape[0]), dtype=data.dtype)
+        for i in prange(len(data)):
+            for j in range(i + 1, len(data)):
+                dist_arr[i, j] = np.linalg.norm(data[i, :] - data[j, :])
+                dist_arr[j, i] = dist_arr[i, j]
+        return dist_arr

tribble_clustering-0.1.0/tests/test_cluster.py

@@ -0,0 +1,552 @@
+import time
+from typing import Any
+
+import numpy as np
+from matplotlib import pyplot as plt
+from numpy import ndarray
+from scipy.spatial import Voronoi, voronoi_plot_2d
+
+from clustering.util import pairwise_distances
+from src.clustering import vat_prim_mst_seq, compute_ivat, fcm
+
+
+def _random_cities(
+    center_x, center_y, n_cities: int = 10, cluster_diameter: float = 3.0
+) -> np.ndarray:
+    if n_cities == 1:
+        return np.array([[center_x, center_y]])
+    # Randomly distribute cities in a uniform circle?
+    theta = np.linspace(0, 2 * np.pi, n_cities + 1, dtype=np.float32)
+    theta = theta[:-1]
+    # Add slight random scramble to locations
+    scramble = np.random.uniform(
+        -cluster_diameter * 0.05, cluster_diameter * 0.05, size=(n_cities, 2)
+    )
+    city_x = np.cos(theta) * cluster_diameter / 2.0 + center_x + scramble[:, 0]
+    city_y = np.sin(theta) * cluster_diameter / 2.0 + center_y + scramble[:, 1]
+    return np.c_[city_x, city_y]
+
+
+def _circle_random_clusters(
+    n_clusters: int = 10,
+    n_cities: int = 10,
+    cluster_diameter: float = 2.0,
+    cluster_spacing: float = 10.0,
+) -> np.ndarray:
+    city_locations = np.zeros(shape=(0, 2), dtype=np.float32)
+    for theta in np.linspace(0, 2 * np.pi, n_clusters):
+        theta *= n_clusters / (n_clusters + 1)
+        cx = cluster_spacing * np.cos(theta)
+        cy = cluster_spacing * np.sin(theta)
+        city_locations = np.concatenate(
+            (
+                city_locations,
+                _random_cities(
+                    cx, cy, n_cities=n_cities, cluster_diameter=cluster_diameter
+                ),
+            ),
+            axis=0,
+        )
+    return city_locations
+
+
+def _hierarchical_circle_clusters(
+        clusters_per_level: list[int],
+        diameters_per_level: list[float],
+) -> np.ndarray:
+    """
+    Create hierarchical clusters arranged in circles around circles recursively.
+
+    Args:
+        clusters_per_level: Number of clusters at each hierarchical level (e.g., [3, 4, 5] means 3 top-level clusters, 
+                           each containing 4 mid-level clusters, each containing 5 leaf clusters)
+        diameters_per_level: Diameter for clusters at each level
+
+    Returns:
+        Array of point coordinates (N, 2)
+
+    Raises:
+        ValueError: If configuration would create more than 16000 points
+    """
+    if len(clusters_per_level) != len(diameters_per_level):
+        raise ValueError("clusters_per_level and diameters_per_level must have the same length")
+
+    # Calculate total number of points
+    total_points = np.prod(clusters_per_level)
+
+    if total_points > 16000:
+        raise ValueError(
+            f"Configuration would create {total_points} points, which exceeds the limit of 16000. "
+            f"Reduce clusters_per_level, diameters_per_level, or points_per_leaf."
+        )
+
+    def _create_level(
+            center_x: float,
+            center_y: float,
+            level_idx: int,
+    ) -> np.ndarray:
+        """Recursively create clusters at the current level"""
+        n_clusters = clusters_per_level[level_idx]
+        diameter = diameters_per_level[level_idx]
+        # Last level gets a bit of noise
+        if level_idx == len(clusters_per_level)-1:
+            # Base case: create leaf points
+            return _random_cities(
+                center_x, center_y,
+                n_cities=n_clusters,
+                cluster_diameter=diameter
+            )
+
+        all_points = np.zeros(shape=(0, 2), dtype=np.float32)
+
+        for theta in np.linspace(0, 2 * np.pi, n_clusters, endpoint=False):
+            # Calculate position of sub-cluster center
+            sub_cx = center_x + diameter * np.cos(theta)
+            sub_cy = center_y + diameter * np.sin(theta)
+
+            # Recursively create points for this sub-cluster
+            sub_points = _create_level(sub_cx, sub_cy,level_idx + 1)
+
+            all_points = np.concatenate((all_points, sub_points), axis=0)
+
+        return all_points
+
+    # Start recursion from the origin
+    return _create_level(0.0, 0.0, 0)
+
+
+def _test_cluster_sequencing():
+    from ucimlrepo import fetch_ucirepo
+
+    # fetch dataset
+    # 59 is letter recognition
+    # 827 is sepsis survival (allocates 80+ GB RAM)
+    # 148 is shuttle stat log (allocates 50 GB RAM)
+    letter_recognition = fetch_ucirepo(id=59)
+
+    # data (as pandas dataframes)
+    X = np.array(letter_recognition.data.features)
+
+    # metadata
+    print(f"Metadata: {letter_recognition.metadata}")
+
+    # variable information
+    print(f"Variable Information: {letter_recognition.variables}")
+
+    # Compute the pairwise distances
+    t0 = time.time()
+    ordered_matrix = vat_prim_mst_seq(X)
+    t1 = time.time()
+
+    print(f"Elapsed time for {len(X)} data points: {t1-t0:.02f}")
+
+
+def test_merge_ivat():
+    all_cities = _circle_random_clusters(
+        n_clusters=10, n_cities=5, cluster_spacing=5.0, cluster_diameter=1
+    )
+    # Scramble the order of the cities
+    scramble_order = np.random.permutation(len(all_cities))
+    all_cities = all_cities[scramble_order]
+    matrix_of_pairwise_distance = pairwise_distances(all_cities)
+
+    ivat_mst, vat_mst, ivat_order, vat_order = compute_ivat(matrix_of_pairwise_distance)
+    plot_vat_ivat(ivat_mst, vat_mst)
+
+
+def plot_vat_ivat(ivat_mst: np.ndarray, vat_mst: np.ndarray):
+    fig, (ax1, ax2) = plt.subplots(1, 2)
+
+    im1 = ax1.imshow(vat_mst, cmap="viridis")
+    ax1.set_title("VAT Matrix")
+    plt.colorbar(im1, ax=ax1)
+
+    im2 = ax2.imshow(ivat_mst, cmap="viridis")
+    ax2.set_title("iVAT Matrix")
+    plt.colorbar(im2, ax=ax2)
+    plt.tight_layout()
+    plt.show()
+
+
+def test_fcm_with_center_on_datapoint():
+    """Test FCM behavior when a cluster center coincides with a data point"""
+    # Create 5 points on a line: (1,0), (3,0), (5,0), (7,0), (9,0)
+    data_points = np.array([[1.0, 0.0], [3.0, 0.0], [5.0, 0.0], [7.0, 0.0], [9.0, 0.0]])
+
+    # Run FCM with 2 clusters
+    n_clusters = 2
+    for idx0 in range(len(data_points)):
+        for idx1 in range(idx0, len(data_points)):
+            cluster_centers, membership_weights = fcm.fuzzy_c_means(
+                data_points, n_clusters, m=2.0, indices=[idx0, idx1]
+            )
+
+            # Verify that we got 2 cluster centers
+            assert cluster_centers.shape == (
+                n_clusters,
+                2,
+            ), f"Expected shape {(n_clusters, 2)}, got {cluster_centers.shape}"
+
+            # Verify that membership weights sum to 1 for each data point
+            membership_sums = np.sum(membership_weights, axis=1)
+            # Verify that membership weights sum to 1 for each data point
+            # (or 0 for duplicate points where cluster center coincides with data point)
+            membership_sums = np.sum(membership_weights, axis=1)
+            expected_values = np.where(
+                membership_sums > 0.5, 1.0, 0.0
+            )  # Expect 1.0 or 0.0
+            np.testing.assert_array_almost_equal(
+                membership_sums,
+                expected_values,
+                err_msg=f"Membership weights should sum to 1 for each data point (or 0 for duplicates): {idx0, idx1}",
+            )
+
+            # Verify all membership weights are between 0 and 1
+            assert np.all(membership_weights >= 0) and np.all(
+                membership_weights <= 1
+            ), "All membership weights should be between 0 and 1"
+
+
+def test_heirarchy_ivat_means():
+    """Test hierarchical circle clusters with iVAT and FCM"""
+    # Example: 3 top-level clusters, each with 4 mid-level, each with 5 leaf clusters (3*4*5*10 = 600 points)
+    all_cities = _hierarchical_circle_clusters(
+        clusters_per_level=[3, 4, 5],
+        diameters_per_level=[15.0, 5.0, 1.0]
+    )
+
+    # Scramble the order of the cities
+    scramble_order = np.random.permutation(len(all_cities))
+    all_cities = all_cities[scramble_order]
+
+    print(f"Created {len(all_cities)} hierarchical points")
+
+    # Compute pairwise distances and iVAT
+    matrix_of_pairwise_distance = pairwise_distances(all_cities)
+    ivat_mst, vat_mst, ivat_order, vat_order = compute_ivat(matrix_of_pairwise_distance)
+
+    # Get cluster information from iVAT
+    abrupt_change_indices, cluster_city_ids, diagonal_values, initial_centroids, max_diff_indices, peaks_threshold, sorted_diagonal = _get_ivat_means(
+        all_cities, ivat_mst, vat_order)
+    # Run FCM with iVAT-derived initial guess
+    n_clusters = len(initial_centroids)
+    meth_c, w_c = fcm.fuzzy_c_means(all_cities, n_clusters, 2, initial_guess=initial_centroids[0])
+
+    print(f"Detected {n_clusters} clusters using iVAT")
+
+    # Visualize results
+    plot_vat_ivat(ivat_mst, vat_mst)
+    for idx in range(len(initial_centroids)):
+        # plot_membership(all_cities, cluster_city_ids[idx], meth_c, w_c)
+        plot_diagonal(
+            diagonal_values,
+            [max_diff_indices[idx]],
+            peaks_threshold[idx],
+            sorted_diagonal,
+            abrupt_change_indices[idx],
+        )
+        plot_voronoi(all_cities, initial_centroids[idx])
+    plt.show()
+
+
+def plot_voronoi(all_cities, centroids):
+    v = Voronoi(centroids)
+    fig = voronoi_plot_2d(v)
+    fig.axes[0].set_title("Voronoi plot")
+    fig.axes[0].scatter(all_cities[:, 0], all_cities[:, 1])
+    fig.show()
+
+
+def test_multi_dim_pairwise_dist_perf():
+    results = []
+    # Do 1 pairwise distances to reduce nogil/numba randomness
+    pairwise_distances(np.zeros((100, 3)))
+
+    dims = [1, 2]
+    sizes = [1000, 2000, 3000, 5000, 8000, 10000, 20000]
+    # sizes = [1000, 2000]
+    for dim in dims:
+        for size in sizes:
+            data = np.random.rand(size, dim)
+            start = time.time()
+            pairwise_distances(data)
+            end = time.time()
+            elapsed = end - start
+            results.append((dim, size, elapsed))
+
+    # Plot results
+    fig, ax = plt.subplots(figsize=(10, 6))
+
+    # Group results by dimension
+    colors = plt.cm.viridis(np.linspace(0, 1, len(dims)))
+
+    for dim, color in zip(dims, colors):
+        dim_results = [(size, time) for d, size, time in results if d == dim]
+        sizes, times = zip(*dim_results)
+        ax.plot(sizes, times, marker='o', label=f'Dim={dim}', color=color, linewidth=2)
+
+    ax.set_xlabel('Data Size', fontsize=12)
+    ax.set_ylabel('Time (seconds)', fontsize=12)
+    ax.set_title('Pairwise Distance Computation Performance', fontsize=14)
+    ax.legend()
+    ax.grid(True, alpha=0.3)
+    plt.tight_layout()
+    plt.show()
+
+
+def test_fuzzy_c_means():
+    n_total: int = 256
+    n_clusters: int = 16
+    n_cities: int = n_total // n_clusters
+    all_cities = _circle_random_clusters(
+        n_clusters=n_clusters, n_cities=n_cities, cluster_spacing=5, cluster_diameter=0.5
+    )
+    # Scramble the order of the cities
+    scramble_order = np.random.permutation(len(all_cities))
+    all_cities = all_cities[scramble_order]
+
+    # Time the elbow method (multiple FCM calls with varying cluster counts)
+    start_elbow = time.time()
+    elbow_results = []
+    cluster_range = range(2, n_clusters + 1)
+    for k in cluster_range:
+        centers, weights = fcm.fuzzy_c_means(all_cities, k, 2)
+        elbow_results.append((k, centers, weights))
+    end_elbow = time.time()
+    elbow_time = end_elbow - start_elbow
+
+    start_ivat = time.time()
+    matrix_of_pairwise_distance = pairwise_distances(all_cities)
+    # Compute the IVAT
+    ivat_mst, vat_mst, ivat_order, vat_order = compute_ivat(matrix_of_pairwise_distance)
+    abrupt_change_indices, cluster_city_ids, diagonal_values, initial_centroids, max_diff_indices, peaks_threshold, sorted_diagonal = _get_ivat_means(
+        all_cities, ivat_mst, vat_order)
+
+    # Time the single FCM call
+    start_single = time.time()
+    meth_c, w_c = fcm.fuzzy_c_means(all_cities, n_clusters, 2, initial_guess=initial_centroids)
+    mid_single = time.time()
+    _, _ = fcm.fuzzy_c_means(all_cities, n_clusters, 2)
+    end_single = time.time()
+    _, _ = fcm.fuzzy_c_means(all_cities, n_clusters, 2, method='gd')
+    end_gd = time.time()
+    smart_fcm_time = mid_single - start_single
+    single_fcm_time = end_single - mid_single
+    iter_fcm_time = end_gd - end_single
+    single_ivat_time = start_single - start_ivat
+
+    # Print performance comparison
+    print(f"\n{'=' * 60}")
+    print(f"Performance Comparison:")
+    print(f"{'=' * 60}")
+    print(f"Elbow Method (n=2 to {n_clusters}): {elbow_time:.4f} seconds")
+    print(f"Single iter-FCM (n={n_clusters}):     {single_fcm_time:.4f} seconds")
+    print(f"Single GD-FCM (n={n_clusters}):     {iter_fcm_time:.4f} seconds")
+    print(f"Smart FCM (n={n_clusters}):     {smart_fcm_time:.4f} seconds")
+    print(f"IVAT (n={n_clusters}):           {single_ivat_time:.4f} seconds")
+    print(f"Time difference:          {elbow_time - single_ivat_time:.4f} seconds")
+    print(f"Elbow method is {elbow_time/single_ivat_time:.2f}x slower")
+    print(f"{'='*60}\n")
+
+    # Assert that every city has been allocated to a cluster
+    all_allocated_cities = np.sort(np.concatenate(cluster_city_ids))
+    # print(f"All cities:\n{np.r_[0:len(all_cities)]}")
+    # print(f"Allocated Cities:\n{all_allocated_cities}")
+    assert len(all_allocated_cities) == len(
+        all_cities
+    ), f"Not all cities allocated: {len(all_allocated_cities)} allocated out of {len(all_cities)} total"
+    assert len(np.unique(all_allocated_cities)) == len(
+        all_cities
+    ), f"Duplicate city allocations detected"
+
+    plot_vat_ivat(ivat_mst, vat_mst)
+
+    plot_diagonal(
+        diagonal_values,
+        max_diff_indices,
+        peaks_threshold,
+        sorted_diagonal,
+        abrupt_change_indices,
+    )
+
+    plot_membership(all_cities, cluster_city_ids, meth_c, w_c)
+    plt.show()
+
+
+def _get_ivat_means(all_cities: ndarray, ivat_mst: ndarray,
+                   vat_order: ndarray) -> tuple[ndarray, list[Any], ndarray, ndarray, list[int], ndarray, ndarray]:
+    # Look down the off-by-1 diagonal and count the number of substantial changes.
+    diagonal_values = np.diag(ivat_mst, k=1)
+    # Augment back to original size, just prepend the initial value to avoid throwing off the diff fcn
+    # Expand this to the original size for convenience.
+    diagonal_values = np.concatenate(
+        [np.array([diagonal_values[0]]), diagonal_values], axis=0
+    )
+    # Sort the diagonal values
+    sorted_diagonal = np.sort(diagonal_values)
+    # Find the maximum difference and the index thereof
+    diagonal_diffs = np.diff(sorted_diagonal)
+    max_diff_indices = _arg_max(diagonal_diffs, 3)
+    peaks_threshold = sorted_diagonal[max_diff_indices + 1]
+    abrupt_change_indices = []
+    cluster_groups = []
+    cluster_city_ids = []
+    initial_centroids = []
+    for index, peak_th in enumerate(peaks_threshold):
+        abrupt_change_idx = np.where(diagonal_values >= peak_th)[0]
+        abrupt_change_indices.append(abrupt_change_idx)
+
+        # Use each section as a cluster endpoint, inclusive.
+        cluster_group = np.concatenate([np.array([0]), abrupt_change_idx, np.array([len(all_cities)])])
+        cluster_groups.append(cluster_group)
+        cluster_city_indexs = []
+        for idx in range(0, len(cluster_group) - 1):
+            cg_start = cluster_group[idx]
+            cg_end = cluster_group[idx + 1]
+            # Use the VAT order to pick out the cities in each cluster
+            cluster_city_indexs.append(vat_order[cg_start:cg_end])
+
+        # Compute the initial guess as the centroid of each city cluster
+        initial_centroids.append(np.array([
+            np.mean(all_cities[cluster_ids], axis=0)
+            for cluster_ids in cluster_city_indexs
+        ]))
+        cluster_city_ids.append(cluster_city_indexs)
+
+    return abrupt_change_indices, cluster_city_ids, diagonal_values, initial_centroids, max_diff_indices, peaks_threshold, sorted_diagonal
+
+
+def get_ivat_means(all_cities: ndarray, ivat_mst: ndarray, vat_order: ndarray) -> tuple[ndarray, list[Any], ndarray]:
+    abrupt_change_indices, cluster_city_ids, diagonal_values, initial_centroids, max_diff_indices, peaks_threshold, sorted_diagonal = _get_ivat_means(all_cities, ivat_mst, vat_order)
+    return initial_centroids, cluster_city_ids, peaks_threshold
+
+
+def _arg_max(a: ndarray, n: int = 1) -> ndarray:
+    """Get the indexes of the n-largest values in the array. You can assume it's a 1D array"""
+    if n >= len(a):
+        return np.argsort(a)[::-1]
+    # Use argpartition to find the n largest elements efficiently
+    partitioned_indices = np.argpartition(a, -n)[-n:]
+    # Sort these indices by their corresponding values in descending order
+    sorted_indices = partitioned_indices[np.argsort(a[partitioned_indices])[::-1]]
+    return sorted_indices
+
+
+def plot_membership(all_cities: ndarray, cluster_city_ids: list[Any],
+                    meth_c: ndarray, w_c: ndarray):
+    # Create a color map for clusters
+    colors = plt.cm.rainbow(np.linspace(0, 1, meth_c.shape[0]))
+
+    # Create plot
+    fig, ax = plt.subplots()
+
+    # Plot each point with blended color based on membership weights
+    for i in range(all_cities.shape[0]):
+        # Blend colors based on membership weights
+        blended_color = np.zeros(4)  # RGBA
+        for j in range(meth_c.shape[0]):
+            blended_color += w_c[i, j] * colors[j]
+
+        blended_color /= blended_color.max()
+
+        ax.scatter(
+            all_cities[i, 0],
+            all_cities[i, 1],
+            c=[blended_color],
+            s=50,
+            alpha=0.7,
+            edgecolors="black",
+            linewidth=0.5,
+        )
+
+    # Plot cluster city IDs with "*" markers
+    ivat_centers = []
+    for idx, cluster_ids in enumerate(cluster_city_ids):
+        cluster_points = all_cities[cluster_ids]
+        cluster_color = colors[idx % len(colors)]
+        ax.scatter(
+            cluster_points[:, 0],
+            cluster_points[:, 1],
+            marker="*",
+            edgecolors=cluster_color,
+            facecolors="none",
+            label=f"Cluster {idx}",
+        )
+        center = np.mean(cluster_points, axis=0)
+        ivat_centers.append(center)
+    ivat_centers = np.array(ivat_centers)
+
+    # Plot ivat cluster centers
+    ax.scatter(
+        ivat_centers[:, 0],
+        ivat_centers[:, 1],
+        c="red",
+        s=150,
+        marker="D",
+        edgecolors="white",
+        label="iVAT Cluster Centers",
+    )
+
+    # Plot cluster centers
+    ax.scatter(
+        meth_c[:, 0],
+        meth_c[:, 1],
+        c="black",
+        s=150,
+        marker="X",
+        edgecolors="white",
+        label="FCM Cluster Centers",
+    )
+
+    ax.set_title("Fuzzy C-Means Clustering with Membership-based Colors")
+    ax.set_xlabel("X Coordinate")
+    ax.set_ylabel("Y Coordinate")
+    # ax.legend(bbox_to_anchor=(1.05, 1), loc="upper left")
+    ax.legend()
+    plt.tight_layout()
+
+
+def plot_diagonal(
+    diagonal_values: ndarray,
+    max_diff_indices: list[int],
+    peaks_threshold,
+    sorted_diagonal: ndarray,
+    abrupt_change_indices: ndarray,
+) -> ndarray:
+    fig, (ax1, ax2) = plt.subplots(2, 1, figsize=(5, 8))
+    ax1.plot(diagonal_values, marker="o")
+    ax1.set_title("Off-by-One Diagonal of iVAT Matrix")
+    ax1.set_xlabel("Index")
+    ax1.set_ylabel("Distance Value")
+    ax1.grid(True)
+
+    ax2.plot(sorted_diagonal, marker="o")
+    for idx in max_diff_indices:
+        ax2.axvline(
+            x=idx,
+            color="r",
+            linestyle="--",
+            label=f"Max diff at index {idx}",
+        )
+    ax2.legend()
+    ax2.set_title("Sorted Off-by-One Diagonal of iVAT Matrix")
+    ax2.set_xlabel("Index")
+    ax2.set_ylabel("Distance Value")
+    ax2.grid(True)
+    plt.tight_layout()
+
+    # Count abrupt size changes using a basic stats test
+    ax1.axhline(
+        y=peaks_threshold,
+        color="r",
+        linestyle="--",
+        label=f"Threshold: {peaks_threshold:.2f}",
+    )
+    ax2.text(
+        0.02,
+        0.98,
+        f"Abrupt changes: {len(abrupt_change_indices)}, threshold: {peaks_threshold:.2f}",
+        transform=ax2.transAxes,
+        verticalalignment="top",
+        bbox=dict(boxstyle="round", facecolor="wheat", alpha=0.5),
+    )