cdc-cluster 0.1.1__tar.gz → 0.2.1__tar.gz

cdc_cluster-0.2.1/LICENSE

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

{cdc_cluster-0.1.1 → cdc_cluster-0.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: cdc-cluster
-Version: 0.1.1
+Version: 0.2.1
 Summary: A novel Clustering algorithm by measuring Direction Centrality (CDC) locally. It adopts a density-independent metric based on the distribution of K-nearest neighbors (KNNs) to distinguish between internal and boundary points. The boundary points generate enclosed cages to bind the connections of internal points.
 Author-email: pdh <pengdh@whu.edu.cn>
 Project-URL: Homepage, https://github.com/ZPGuiGroupWhu/CDC-pkg
@@ -20,6 +20,7 @@ Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Requires-Python: >=3.8
 Description-Content-Type: text/markdown
+License-File: LICENSE
 Requires-Dist: scikit-learn>=1.3.2
 
 # Clustering by measuring local direction centrality for data with heterogeneous density and weak connectivity (CDC)
@@ -46,71 +47,49 @@ cd CDC-pkg
 pip install -e .
 ```
 
-# How To Run
-The CDC algorithm package provides the `cdc_cluster` function for clustering.
+# Usage
+The CDC algorithm is refactored to be a scikit-learn compatible estimator. It provides both a class-based interface `CDC` and a function-based interface `cdc_cluster`.
 
-The description of the hyperparameters for user configuration are presented as follows 
+### Class-based Usage
 ```python
-def cdc_cluster(X: np.ndarray, k_num: int, ratio: float) -> np.ndarray:
-    """Clustering by measuring local Direction Centrality (CDC) algorithm.
-
-    This function implements the CDC clustering algorithm, which is a connectivity-based
-    clustering method that identifies boundary points using a directional centrality
-    metric (DCM) and connects internal points to generate cluster labels. DCM is defined
-    as angle variance in 2D space and simplex volume variance in higher dimensions.
-
-    The algorithm works in several steps:
-    1. For each point, find k-nearest neighbors
-    2. For each point, calculate its DCM
-    3. Identify boundary and internal points based on the DCM threshold
-    4. Calculate reachable distances of the internal points
-    5. Form clusters by connecting nearby internal points
-    6. Assign boundary points to nearest clusters
-
-    Args:
-        X (np.ndarray): Input data matrix of shape (n_samples, n_features).
-            Each row represents a data point and each column represents a feature.
-        k_num (int): Number of nearest neighbors to consider. Must be greater than 0.
-            This parameter controls the local neighborhood size.
-        ratio (float): Ratio for determining the DCM threshold. Must be between 0 and 1.
-            Lower values result in fewer internal points and more boundary points.
-
-    Returns:
-        np.ndarray: Cluster labels for each data point. Shape (n_samples,).
-            Labels are integers starting from 1, where points with the same label
-            belong to the same cluster.
-
-    Raises:
-        AssertionError: If k_num <= 0 or ratio is not in (0, 1).
-        ValueError: If X is not a 2D array or has insufficient data points.
-
-    Note:
-        - For 2D data, the algorithm uses angle variance between k-nearest neighbors
-        - For higher dimensional data, it uses convex hull simplex volume variance
-        - The algorithm automatically handles edge cases and numerical instabilities
-    """
-```
-After installing the CDC library, you can use this function as follows:
-```python
-from cdc import cdc_cluster
+from cdc_cluster import CDC
 import numpy as np
-import pandas as pd
 import matplotlib.pyplot as plt
-import time
-# DS1.txt link: https://github.com/ZPGuiGroupWhu/ClusteringDirectionCentrality/blob/master/Toolkit/Python/DS1.txt
-raw_data = pd.read_table('DS1.txt', header=None)
-X = np.array(raw_data)
-[n, d] = X.shape
-data = X[:, :d-1]
-ref = X[:, d-1]
-time_start = time.time()
-res = cdc_cluster(X=data, k_num=30, ratio=0.72)
-time_end = time.time()
-print(time_end-time_start)
-
-plt.scatter(data[:, 0], data[:, 1], c=res, s=10, cmap='hsv', marker='o')
+from sklearn.datasets import make_moons
+
+# Generate sample data
+X, _ = make_moons(n_samples=200, noise=0.05, random_state=42)
+
+# Initialize and fit CDC
+# n_neighbors: Number of nearest neighbors to consider (k_num)
+# ratio: Ratio for determining the DCM threshold
+cdc = CDC(n_neighbors=20, ratio=0.9)
+cdc.fit(X)
+
+# Get cluster labels
+# Labels start from 0. Noisy samples are labeled as -1.
+labels = cdc.labels_
+
+# Plot result
+plt.scatter(X[:, 0], X[:, 1], c=labels, cmap='viridis')
+plt.title("CDC Clustering Result")
 plt.show()
 ```
+
+### Function-based Usage
+```python
+from cdc_cluster import cdc_cluster
+from sklearn.datasets import make_blobs
+
+X, _ = make_blobs(n_samples=200, centers=3, random_state=42)
+
+# Compute clustering directly
+# Returns an array of cluster labels
+labels = cdc_cluster(X, n_neighbors=20, ratio=0.9)
+
+print(f"Number of clusters: {len(set(labels)) - (1 if -1 in labels else 0)}")
+```
+
 # Citation Request:
 Peng, D., Gui, Z.*, Wang, D. et al. Clustering by measuring local direction centrality for data with heterogeneous density and weak connectivity. Nat. Commun. 13, 5455 (2022).
 https://www.nature.com/articles/s41467-022-33136-9

cdc_cluster-0.2.1/README.md

@@ -0,0 +1,74 @@
+# Clustering by measuring local direction centrality for data with heterogeneous density and weak connectivity (CDC)
+
+
+We propose a novel Clustering algorithm by measuring Direction Centrality (CDC) locally. It adopts a density-independent metric based on the distribution of K-nearest neighbors (KNNs) to distinguish between internal and boundary points. The boundary points generate enclosed cages to bind the connections of internal points, thereby preventing cross-cluster connections and separating weakly-connected clusters. We present an interactive ***Demo*** and a brief introduction to the algorithm at ***https://zpguigroupwhu.github.io/CDC-Introduction-Website/***, and develop a CDC toolkit at ***https://github.com/ZPGuiGroupWhu/ClusteringDirectionCentrality*** This paper has been published in ***Nature Communications***, and more details can be seen https://www.nature.com/articles/s41467-022-33136-9. 
+
+![image](https://raw.githubusercontent.com/ZPGuiGroupWhu/CDC-pkg/refs/heads/main/image/cdc_algorithm.png)
+
+# Installation
+Supported `python` versions are `3.8` and above.
+
+This project has been uploaded to [PyPI](https://pypi.org/project/cdc-cluster/), supporting direct download and installation from pypi
+
+```
+pip install cdc-cluster
+```
+
+## Manual Installation
+
+```
+git clone https://github.com/ZPGuiGroupWhu/CDC-pkg.git
+cd CDC-pkg
+pip install -e .
+```
+
+# Usage
+The CDC algorithm is refactored to be a scikit-learn compatible estimator. It provides both a class-based interface `CDC` and a function-based interface `cdc_cluster`.
+
+### Class-based Usage
+```python
+from cdc_cluster import CDC
+import numpy as np
+import matplotlib.pyplot as plt
+from sklearn.datasets import make_moons
+
+# Generate sample data
+X, _ = make_moons(n_samples=200, noise=0.05, random_state=42)
+
+# Initialize and fit CDC
+# n_neighbors: Number of nearest neighbors to consider (k_num)
+# ratio: Ratio for determining the DCM threshold
+cdc = CDC(n_neighbors=20, ratio=0.9)
+cdc.fit(X)
+
+# Get cluster labels
+# Labels start from 0. Noisy samples are labeled as -1.
+labels = cdc.labels_
+
+# Plot result
+plt.scatter(X[:, 0], X[:, 1], c=labels, cmap='viridis')
+plt.title("CDC Clustering Result")
+plt.show()
+```
+
+### Function-based Usage
+```python
+from cdc_cluster import cdc_cluster
+from sklearn.datasets import make_blobs
+
+X, _ = make_blobs(n_samples=200, centers=3, random_state=42)
+
+# Compute clustering directly
+# Returns an array of cluster labels
+labels = cdc_cluster(X, n_neighbors=20, ratio=0.9)
+
+print(f"Number of clusters: {len(set(labels)) - (1 if -1 in labels else 0)}")
+```
+
+# Citation Request:
+Peng, D., Gui, Z.*, Wang, D. et al. Clustering by measuring local direction centrality for data with heterogeneous density and weak connectivity. Nat. Commun. 13, 5455 (2022).
+https://www.nature.com/articles/s41467-022-33136-9
+
+# License
+
+This project is covered under the MIT License.

cdc_cluster-0.2.1/cdc_cluster/__init__.py

@@ -0,0 +1,3 @@
+from ._cdc import CDC, cdc_cluster
+
+__all__ = ['CDC', 'cdc_cluster']

cdc_cluster-0.2.1/cdc_cluster/_cdc.py

@@ -0,0 +1,262 @@
+"""
+Clustering by measuring local Direction Centrality (CDC).
+"""
+import math
+import numpy as np
+from scipy.special import gamma
+from scipy.spatial import ConvexHull
+from sklearn.base import BaseEstimator, ClusterMixin
+from sklearn.neighbors import NearestNeighbors
+from sklearn.utils.validation import check_array
+
+def cdc_cluster(X, n_neighbors=20, ratio=0.9):
+    """
+    Perform CDC clustering from vector array or distance matrix.
+    
+    Parameters
+    ----------
+    X : {array-like, sparse matrix} of shape (n_samples, n_features)
+        Training instances.
+        
+    n_neighbors : int, default=20
+        Number of nearest neighbors to consider.
+        
+    ratio : float, default=0.9
+        Ratio for determining the DCM threshold. Must be between 0 and 1.
+        
+    Returns
+    -------
+    labels : ndarray of shape (n_samples,)
+        Cluster labels for each point. Noisy samples are given the label -1.
+    """
+    X = check_array(X)
+    
+    if n_neighbors <= 0:
+        raise ValueError("n_neighbors must be greater than 0")
+    if not (0 < ratio < 1):
+        raise ValueError("ratio must be between 0 and 1")
+
+    k_num = n_neighbors
+    num, d = X.shape
+
+    # Nearest Neighbors
+    # Note: We need k_num + 1 because the point itself is included
+    nbrs = NearestNeighbors(n_neighbors=k_num+1, algorithm='ball_tree').fit(X)
+    indices = nbrs.kneighbors(X, return_distance=False)
+    # Exclude the point itself (first column)
+    get_knn = indices[:, 1:k_num+1]
+
+    angle_var = np.zeros(num)
+    
+    # Calculate DCM (Direction Centrality Metric)
+    if d == 2:
+        angle = np.zeros((num, k_num))
+        for i in range(num):
+            for j in range(k_num):
+                delta_x = X[get_knn[i, j], 0] - X[i, 0]
+                delta_y = X[get_knn[i, j], 1] - X[i, 1]
+                if delta_x == 0:
+                    if delta_y == 0:
+                        angle[i, j] = 0
+                    elif delta_y > 0:
+                        angle[i, j] = math.pi / 2
+                    else:
+                        angle[i, j] = 3 * math.pi / 2
+                elif delta_x > 0:
+                    if math.atan(delta_y / delta_x) >= 0:
+                        angle[i, j] = math.atan(delta_y / delta_x)
+                    else:
+                        angle[i, j] = 2 * math.pi + math.atan(delta_y / delta_x)
+                else:
+                    angle[i, j] = math.pi + math.atan(delta_y / delta_x)
+
+        for i in range(num):
+            angle_order = sorted(angle[i, :])
+
+            for j in range(k_num - 1):
+                point_angle = angle_order[j + 1] - angle_order[j]
+                angle_var[i] = angle_var[i] + pow(point_angle - 2 * math.pi / k_num, 2)
+
+            point_angle = angle_order[0] - angle_order[k_num - 1] + 2 * math.pi
+            angle_var[i] = angle_var[i] + pow(point_angle - 2 * math.pi / k_num, 2)
+            angle_var[i] = angle_var[i] / k_num
+
+        angle_var = angle_var / ((k_num - 1) * 4 * pow(math.pi, 2) / pow(k_num, 2))
+    else:
+        for i in range(num):
+            try:
+                dif_x = X[get_knn[i], :] - X[i, :]
+                cov = np.dot(dif_x, dif_x.T)
+                if np.all(cov == 0):
+                    map_x = dif_x
+                else:
+                    map_x = np.linalg.inv(np.diag(np.sqrt(np.diag(cov)))) @ dif_x
+                
+                hull = ConvexHull(map_x)
+                simplex_num = len(hull.simplices)
+                simplex_vol = np.zeros(simplex_num)
+
+                for j in range(simplex_num):
+                    simplex_coord = map_x[hull.simplices[j], :]
+                    simplex_vol[j] = np.sqrt(max(0, np.linalg.det(np.dot(simplex_coord, simplex_coord.T)))) / gamma(d-1)
+
+                angle_var[i] = np.var(simplex_vol)
+
+            except Exception:
+                angle_var[i] = 1
+
+    # Determine threshold
+    sort_dcm = sorted(angle_var)
+    idx = math.ceil(num * ratio)
+    if idx >= num:
+        idx = num - 1
+    T_DCM = sort_dcm[idx]
+    
+    ind = np.zeros(num)
+    for i in range(num):
+        if angle_var[i] < T_DCM:
+            ind[i] = 1 # Internal point
+
+    near_dis = np.zeros(num)
+    for i in range(num):
+        knn_ind = ind[get_knn[i, :]]
+        if ind[i] == 1: # Internal
+            if 0 in knn_ind: # Has boundary neighbor
+                bdpts_ind = np.where(knn_ind == 0)[0]
+                bd_id = get_knn[i, bdpts_ind[0]]
+                near_dis[i] = math.sqrt(np.sum((X[i, :] - X[bd_id, :])**2))
+            else:
+                near_dis[i] = float("inf")
+                for j in range(num):
+                    if ind[j] == 0:
+                        temp_dis = math.sqrt(np.sum((X[i, :] - X[j, :])**2))
+                        if temp_dis < near_dis[i]:
+                            near_dis[i] = temp_dis
+        else: # Boundary
+            if 1 in knn_ind: # Has internal neighbor
+                bdpts_ind = np.where(knn_ind == 1)[0]
+                bd_id = get_knn[i, bdpts_ind[0]]
+                near_dis[i] = bd_id # Storing ID of nearest internal point
+            else:
+                mark_dis = float("inf")
+                for j in range(num):
+                    if ind[j] == 1:
+                        temp_dis = math.sqrt(np.sum((X[i, :] - X[j, :])**2))
+                        if temp_dis < mark_dis:
+                            mark_dis = temp_dis
+                            near_dis[i] = j
+
+    # Clustering
+    cluster = np.zeros(num)
+    mark = 1
+    for i in range(num):
+        if ind[i] == 1 and cluster[i] == 0:
+            cluster[i] = mark
+            for j in range(num):
+                # Connectivity check
+                if ind[j] == 1:
+                    dist = math.sqrt(np.sum((X[i, :] - X[j, :])**2))
+                    if dist <= near_dis[i] + near_dis[j]:
+                        if cluster[j] == 0:
+                            cluster[j] = cluster[i]
+                        else:
+                            # Merge clusters
+                            temp_cluster = cluster[j]
+                            temp_ind = np.where(cluster == temp_cluster)
+                            cluster[temp_ind] = cluster[i]
+            mark = mark + 1
+
+    # Assign boundary points
+    for i in range(num):
+        if ind[i] == 0:
+            cluster[i] = cluster[int(near_dis[i])]
+
+    # Remap labels: start from 0, use -1 for unassigned (noise)
+    # Original logic: 0 is unassigned, valid clusters >= 1
+    
+    unique_labels = np.unique(cluster)
+    mapped_labels = np.full(num, -1, dtype=int)
+    
+    current_label = 0
+    # Sort labels to ensure deterministic mapping (ignore 0)
+    sorted_labels = sorted([l for l in unique_labels if l != 0])
+    
+    for old_label in sorted_labels:
+        mapped_labels[cluster == old_label] = current_label
+        current_label += 1
+        
+    return mapped_labels
+
+class CDC(BaseEstimator, ClusterMixin):
+    """
+    Clustering by measuring local Direction Centrality (CDC).
+
+    Parameters
+    ----------
+    n_neighbors : int, default=20
+        Number of nearest neighbors to consider.
+    
+    ratio : float, default=0.9
+        Ratio for determining the DCM threshold. Must be between 0 and 1.
+
+    Attributes
+    ----------
+    labels_ : ndarray of shape (n_samples,)
+        Cluster labels for each point. Noisy samples are given the label -1.
+    
+    n_features_in_ : int
+        Number of features seen during :term:`fit`.
+        
+    feature_names_in_ : ndarray of shape (n_features_in_,)
+        Names of features seen during :term:`fit`. Defined only when `X`
+        has feature names that are all strings.
+
+    References
+    ----------
+    Peng, D., Gui, Z.*, Wang, D. et al. Clustering by measuring local 
+    direction centrality for data with heterogeneous density and weak connectivity. 
+    Nat. Commun. 13, 5455 (2022). https://www.nature.com/articles/s41467-022-33136-9
+    """
+    def __init__(self, n_neighbors=20, ratio=0.9):
+        self.n_neighbors = n_neighbors
+        self.ratio = ratio
+
+    def fit(self, X, y=None):
+        """Compute CDC clustering.
+
+        Parameters
+        ----------
+        X : array-like of shape (n_samples, n_features)
+            Training instances.
+
+        y : Ignored
+            Not used, present here for API consistency by convention.
+
+        Returns
+        -------
+        self : object
+            Fitted estimator.
+        """
+        X = check_array(X)
+        self.n_features_in_ = X.shape[1]
+        self.labels_ = cdc_cluster(X, n_neighbors=self.n_neighbors, ratio=self.ratio)
+        return self
+
+    def fit_predict(self, X, y=None):
+        """Compute clusters and return cluster labels.
+
+        Parameters
+        ----------
+        X : array-like of shape (n_samples, n_features)
+            Training instances.
+
+        y : Ignored
+            Not used, present here for API consistency by convention.
+
+        Returns
+        -------
+        labels : ndarray of shape (n_samples,)
+            Cluster labels.
+        """
+        self.fit(X)
+        return self.labels_

{cdc_cluster-0.1.1 → cdc_cluster-0.2.1}/cdc_cluster.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: cdc-cluster
-Version: 0.1.1
+Version: 0.2.1
 Summary: A novel Clustering algorithm by measuring Direction Centrality (CDC) locally. It adopts a density-independent metric based on the distribution of K-nearest neighbors (KNNs) to distinguish between internal and boundary points. The boundary points generate enclosed cages to bind the connections of internal points.
 Author-email: pdh <pengdh@whu.edu.cn>
 Project-URL: Homepage, https://github.com/ZPGuiGroupWhu/CDC-pkg
@@ -20,6 +20,7 @@ Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Requires-Python: >=3.8
 Description-Content-Type: text/markdown
+License-File: LICENSE
 Requires-Dist: scikit-learn>=1.3.2
 
 # Clustering by measuring local direction centrality for data with heterogeneous density and weak connectivity (CDC)
@@ -46,71 +47,49 @@ cd CDC-pkg
 pip install -e .
 ```
 
-# How To Run
-The CDC algorithm package provides the `cdc_cluster` function for clustering.
+# Usage
+The CDC algorithm is refactored to be a scikit-learn compatible estimator. It provides both a class-based interface `CDC` and a function-based interface `cdc_cluster`.
 
-The description of the hyperparameters for user configuration are presented as follows 
+### Class-based Usage
 ```python
-def cdc_cluster(X: np.ndarray, k_num: int, ratio: float) -> np.ndarray:
-    """Clustering by measuring local Direction Centrality (CDC) algorithm.
-
-    This function implements the CDC clustering algorithm, which is a connectivity-based
-    clustering method that identifies boundary points using a directional centrality
-    metric (DCM) and connects internal points to generate cluster labels. DCM is defined
-    as angle variance in 2D space and simplex volume variance in higher dimensions.
-
-    The algorithm works in several steps:
-    1. For each point, find k-nearest neighbors
-    2. For each point, calculate its DCM
-    3. Identify boundary and internal points based on the DCM threshold
-    4. Calculate reachable distances of the internal points
-    5. Form clusters by connecting nearby internal points
-    6. Assign boundary points to nearest clusters
-
-    Args:
-        X (np.ndarray): Input data matrix of shape (n_samples, n_features).
-            Each row represents a data point and each column represents a feature.
-        k_num (int): Number of nearest neighbors to consider. Must be greater than 0.
-            This parameter controls the local neighborhood size.
-        ratio (float): Ratio for determining the DCM threshold. Must be between 0 and 1.
-            Lower values result in fewer internal points and more boundary points.
-
-    Returns:
-        np.ndarray: Cluster labels for each data point. Shape (n_samples,).
-            Labels are integers starting from 1, where points with the same label
-            belong to the same cluster.
-
-    Raises:
-        AssertionError: If k_num <= 0 or ratio is not in (0, 1).
-        ValueError: If X is not a 2D array or has insufficient data points.
-
-    Note:
-        - For 2D data, the algorithm uses angle variance between k-nearest neighbors
-        - For higher dimensional data, it uses convex hull simplex volume variance
-        - The algorithm automatically handles edge cases and numerical instabilities
-    """
-```
-After installing the CDC library, you can use this function as follows:
-```python
-from cdc import cdc_cluster
+from cdc_cluster import CDC
 import numpy as np
-import pandas as pd
 import matplotlib.pyplot as plt
-import time
-# DS1.txt link: https://github.com/ZPGuiGroupWhu/ClusteringDirectionCentrality/blob/master/Toolkit/Python/DS1.txt
-raw_data = pd.read_table('DS1.txt', header=None)
-X = np.array(raw_data)
-[n, d] = X.shape
-data = X[:, :d-1]
-ref = X[:, d-1]
-time_start = time.time()
-res = cdc_cluster(X=data, k_num=30, ratio=0.72)
-time_end = time.time()
-print(time_end-time_start)
-
-plt.scatter(data[:, 0], data[:, 1], c=res, s=10, cmap='hsv', marker='o')
+from sklearn.datasets import make_moons
+
+# Generate sample data
+X, _ = make_moons(n_samples=200, noise=0.05, random_state=42)
+
+# Initialize and fit CDC
+# n_neighbors: Number of nearest neighbors to consider (k_num)
+# ratio: Ratio for determining the DCM threshold
+cdc = CDC(n_neighbors=20, ratio=0.9)
+cdc.fit(X)
+
+# Get cluster labels
+# Labels start from 0. Noisy samples are labeled as -1.
+labels = cdc.labels_
+
+# Plot result
+plt.scatter(X[:, 0], X[:, 1], c=labels, cmap='viridis')
+plt.title("CDC Clustering Result")
 plt.show()
 ```
+
+### Function-based Usage
+```python
+from cdc_cluster import cdc_cluster
+from sklearn.datasets import make_blobs
+
+X, _ = make_blobs(n_samples=200, centers=3, random_state=42)
+
+# Compute clustering directly
+# Returns an array of cluster labels
+labels = cdc_cluster(X, n_neighbors=20, ratio=0.9)
+
+print(f"Number of clusters: {len(set(labels)) - (1 if -1 in labels else 0)}")
+```
+
 # Citation Request:
 Peng, D., Gui, Z.*, Wang, D. et al. Clustering by measuring local direction centrality for data with heterogeneous density and weak connectivity. Nat. Commun. 13, 5455 (2022).
 https://www.nature.com/articles/s41467-022-33136-9

{cdc_cluster-0.1.1 → cdc_cluster-0.2.1}/cdc_cluster.egg-info/SOURCES.txt

@@ -1,9 +1,11 @@
+LICENSE
 README.md
 pyproject.toml
-cdc/__init__.py
+cdc_cluster/__init__.py
+cdc_cluster/_cdc.py
 cdc_cluster.egg-info/PKG-INFO
 cdc_cluster.egg-info/SOURCES.txt
 cdc_cluster.egg-info/dependency_links.txt
 cdc_cluster.egg-info/requires.txt
 cdc_cluster.egg-info/top_level.txt
-test/test1.py
+tests/test_cdc.py

cdc_cluster-0.2.1/cdc_cluster.egg-info/top_level.txt

@@ -0,0 +1 @@
+cdc_cluster

{cdc_cluster-0.1.1 → cdc_cluster-0.2.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "cdc-cluster"
-version = "0.1.1"
+version = "0.2.1"
 description = "A novel Clustering algorithm by measuring Direction Centrality (CDC) locally. It adopts a density-independent metric based on the distribution of K-nearest neighbors (KNNs) to distinguish between internal and boundary points. The boundary points generate enclosed cages to bind the connections of internal points."
 authors = [
     {name = "pdh", email = "pengdh@whu.edu.cn"}
@@ -35,8 +35,16 @@ Repository = "https://github.com/ZPGuiGroupWhu/CDC-pkg.git"
 "Bug Tracker" = "https://github.com/ZPGuiGroupWhu/CDC-pkg/issues"
 
 [build-system]
-requires = ["setuptools>=61.0", "wheel"]
+requires = ["setuptools>=68.0", "wheel"]
 build-backend = "setuptools.build_meta"
 
 [tool.setuptools]
-packages = ["cdc"]
+packages = ["cdc_cluster"]
+
+[dependency-groups]
+dev = [
+    "build>=1.2.2.post1",
+    "matplotlib>=3.7.5",
+    "pytest>=8.3.5",
+    "twine>=6.1.0",
+]

cdc_cluster-0.2.1/tests/test_cdc.py

@@ -0,0 +1,50 @@
+import numpy as np
+import pytest
+from sklearn.datasets import make_blobs
+from cdc_cluster import CDC, cdc_cluster
+
+def test_cdc_class():
+    X, y = make_blobs(n_samples=100, centers=3, random_state=42)
+    cdc = CDC(n_neighbors=10, ratio=0.9)
+    cdc.fit(X)
+    assert hasattr(cdc, 'labels_')
+    
+    # Check labels start from 0
+    unique_labels = np.unique(cdc.labels_)
+    # Filter out noise if any (-1)
+    valid_labels = unique_labels[unique_labels >= 0]
+    if len(valid_labels) > 0:
+        assert np.min(valid_labels) == 0
+        # Check consecutive integers (optional, but good practice if expected)
+        # CDC might produce gaps if not careful, but our remapping ensures consecutive 0..K-1
+        assert np.all(np.diff(sorted(valid_labels)) == 1)
+        
+    # Check predictions match fit
+    labels = cdc.fit_predict(X)
+    assert np.array_equal(labels, cdc.labels_)
+
+def test_cdc_function():
+    X, y = make_blobs(n_samples=100, centers=3, random_state=42)
+    labels = cdc_cluster(X, n_neighbors=10, ratio=0.9)
+    
+    assert len(labels) == 100
+    unique_labels = np.unique(labels)
+    valid_labels = unique_labels[unique_labels >= 0]
+    
+    if len(valid_labels) > 0:
+        assert np.min(valid_labels) == 0
+
+def test_consistency():
+    X, y = make_blobs(n_samples=100, centers=3, random_state=42)
+    cdc = CDC(n_neighbors=10, ratio=0.9)
+    labels_class = cdc.fit_predict(X)
+    labels_func = cdc_cluster(X, n_neighbors=10, ratio=0.9)
+    
+    assert np.array_equal(labels_class, labels_func)
+
+def test_input_validation():
+    with pytest.raises(ValueError):
+        cdc_cluster(np.random.rand(10, 2), n_neighbors=-1)
+        
+    with pytest.raises(ValueError):
+        cdc_cluster(np.random.rand(10, 2), ratio=1.5)

cdc_cluster-0.1.1/README.md

@@ -1,96 +0,0 @@
-# Clustering by measuring local direction centrality for data with heterogeneous density and weak connectivity (CDC)
-
-
-We propose a novel Clustering algorithm by measuring Direction Centrality (CDC) locally. It adopts a density-independent metric based on the distribution of K-nearest neighbors (KNNs) to distinguish between internal and boundary points. The boundary points generate enclosed cages to bind the connections of internal points, thereby preventing cross-cluster connections and separating weakly-connected clusters. We present an interactive ***Demo*** and a brief introduction to the algorithm at ***https://zpguigroupwhu.github.io/CDC-Introduction-Website/***, and develop a CDC toolkit at ***https://github.com/ZPGuiGroupWhu/ClusteringDirectionCentrality*** This paper has been published in ***Nature Communications***, and more details can be seen https://www.nature.com/articles/s41467-022-33136-9. 
-
-![image](https://raw.githubusercontent.com/ZPGuiGroupWhu/CDC-pkg/refs/heads/main/image/cdc_algorithm.png)
-
-# Installation
-Supported `python` versions are `3.8` and above.
-
-This project has been uploaded to [PyPI](https://pypi.org/project/cdc-cluster/), supporting direct download and installation from pypi
-
-```
-pip install cdc-cluster
-```
-
-## Manual Installation
-
-```
-git clone https://github.com/ZPGuiGroupWhu/CDC-pkg.git
-cd CDC-pkg
-pip install -e .
-```
-
-# How To Run
-The CDC algorithm package provides the `cdc_cluster` function for clustering.
-
-The description of the hyperparameters for user configuration are presented as follows 
-```python
-def cdc_cluster(X: np.ndarray, k_num: int, ratio: float) -> np.ndarray:
-    """Clustering by measuring local Direction Centrality (CDC) algorithm.
-
-    This function implements the CDC clustering algorithm, which is a connectivity-based
-    clustering method that identifies boundary points using a directional centrality
-    metric (DCM) and connects internal points to generate cluster labels. DCM is defined
-    as angle variance in 2D space and simplex volume variance in higher dimensions.
-
-    The algorithm works in several steps:
-    1. For each point, find k-nearest neighbors
-    2. For each point, calculate its DCM
-    3. Identify boundary and internal points based on the DCM threshold
-    4. Calculate reachable distances of the internal points
-    5. Form clusters by connecting nearby internal points
-    6. Assign boundary points to nearest clusters
-
-    Args:
-        X (np.ndarray): Input data matrix of shape (n_samples, n_features).
-            Each row represents a data point and each column represents a feature.
-        k_num (int): Number of nearest neighbors to consider. Must be greater than 0.
-            This parameter controls the local neighborhood size.
-        ratio (float): Ratio for determining the DCM threshold. Must be between 0 and 1.
-            Lower values result in fewer internal points and more boundary points.
-
-    Returns:
-        np.ndarray: Cluster labels for each data point. Shape (n_samples,).
-            Labels are integers starting from 1, where points with the same label
-            belong to the same cluster.
-
-    Raises:
-        AssertionError: If k_num <= 0 or ratio is not in (0, 1).
-        ValueError: If X is not a 2D array or has insufficient data points.
-
-    Note:
-        - For 2D data, the algorithm uses angle variance between k-nearest neighbors
-        - For higher dimensional data, it uses convex hull simplex volume variance
-        - The algorithm automatically handles edge cases and numerical instabilities
-    """
-```
-After installing the CDC library, you can use this function as follows:
-```python
-from cdc import cdc_cluster
-import numpy as np
-import pandas as pd
-import matplotlib.pyplot as plt
-import time
-# DS1.txt link: https://github.com/ZPGuiGroupWhu/ClusteringDirectionCentrality/blob/master/Toolkit/Python/DS1.txt
-raw_data = pd.read_table('DS1.txt', header=None)
-X = np.array(raw_data)
-[n, d] = X.shape
-data = X[:, :d-1]
-ref = X[:, d-1]
-time_start = time.time()
-res = cdc_cluster(X=data, k_num=30, ratio=0.72)
-time_end = time.time()
-print(time_end-time_start)
-
-plt.scatter(data[:, 0], data[:, 1], c=res, s=10, cmap='hsv', marker='o')
-plt.show()
-```
-# Citation Request:
-Peng, D., Gui, Z.*, Wang, D. et al. Clustering by measuring local direction centrality for data with heterogeneous density and weak connectivity. Nat. Commun. 13, 5455 (2022).
-https://www.nature.com/articles/s41467-022-33136-9
-
-# License
-
-This project is covered under the MIT License.

cdc_cluster-0.1.1/cdc/__init__.py

@@ -1,193 +0,0 @@
-import math
-import numpy as np
-from sklearn.neighbors import NearestNeighbors
-from scipy.special import gamma
-from scipy.spatial import ConvexHull
-
-__all__ = ['cdc_cluster']
-
-def cdc_cluster(X: np.ndarray, k_num: int, ratio: float) -> np.ndarray:
-    """Clustering by measuring local Direction Centrality (CDC) algorithm.
-    
-    This function implements the CDC clustering algorithm, which is a connectivity-based
-    clustering method that identifies boundary points using a directional centrality
-    metric (DCM) and connects internal points to generate cluster labels. DCM is defined
-    as angle variance in 2D space and simplex volume variance in higher dimensions.
-    
-    paper reference: Peng, D., Gui, Z.*, Wang, D. et al. Clustering by measuring local 
-    direction centrality for data with heterogeneous density and weak connectivity. 
-    Nat. Commun. 13, 5455 (2022). https://www.nature.com/articles/s41467-022-33136-9
-    
-    The algorithm works in several steps:
-    1. For each point, find k-nearest neighbors
-    2. For each point, calculate its DCM
-    3. Identify boundary and internal points based on the DCM threshold
-    4. Calculate reachable distances of the internal points
-    5. Form clusters by connecting nearby internal points
-    6. Assign boundary points to nearest clusters
-    
-    Args:
-        X (np.ndarray): Input data matrix of shape (n_samples, n_features).
-            Each row represents a data point and each column represents a feature.
-        k_num (int): Number of nearest neighbors to consider. Must be greater than 0.
-            This parameter controls the local neighborhood size.
-        ratio (float): Ratio for determining the DCM threshold. Must be between 0 and 1.
-            Lower values result in fewer internal points and more boundary points.
-
-    
-    Returns:
-        np.ndarray: Cluster labels for each data point. Shape (n_samples,).
-            Labels are integers starting from 1, where points with the same label
-            belong to the same cluster.
-    
-    Raises:
-        AssertionError: If k_num <= 0 or ratio is not in (0, 1).
-        ValueError: If X is not a 2D array or has insufficient data points.
-    
-    Example:
-        >>> import numpy as np
-        >>> from CDC import cdc_cluster
-        >>> 
-        >>> # Generate sample 2D data
-        >>> X = np.random.rand(100, 2)
-        >>> 
-        >>> # Apply CDC clustering
-        >>> labels = cdc_cluster(X=X, k_num=20, ratio=0.9)
-        >>> 
-        >>> # Get number of clusters
-        >>> n_clusters = len(np.unique(labels))
-        >>> print(f"Number of clusters: {n_clusters}")
-    
-    Note:
-        - For 2D data, the algorithm uses angle variance between k-nearest neighbors
-        - For higher dimensional data, it uses convex hull simplex volume variance
-        - The algorithm automatically handles edge cases and numerical instabilities
-    """
-    assert k_num > 0, "k_num must be greater than 0"
-    assert 0 < ratio < 1, "ratio must be between 0 and 1"
-    
-    [num, d] = X.shape
-    nbrs = NearestNeighbors(n_neighbors=k_num+1, algorithm='ball_tree').fit(X)
-    indices = nbrs.kneighbors(X, return_distance=False)
-    get_knn = indices[:, 1:k_num+1]
-
-    angle_var = np.zeros(num)
-    if (d == 2):
-        angle = np.zeros((num, k_num))
-        for i in range(num):
-            for j in range(k_num):
-                delta_x = X[get_knn[i, j], 0] - X[i, 0]
-                delta_y = X[get_knn[i, j], 1] - X[i, 1]
-                if delta_x == 0:
-                    if delta_y == 0:
-                        angle[i, j] = 0
-                    elif delta_y > 0:
-                        angle[i, j] = math.pi / 2
-                    else:
-                        angle[i, j] = 3 * math.pi / 2
-                elif delta_x > 0:
-                    if math.atan(delta_y / delta_x) >= 0:
-                        angle[i, j] = math.atan(delta_y / delta_x)
-                    else:
-                        angle[i, j] = 2 * math.pi + math.atan(delta_y / delta_x)
-                else:
-                    angle[i, j] = math.pi + math.atan(delta_y / delta_x)
-
-        for i in range(num):
-            angle_order = sorted(angle[i, :])
-
-            for j in range(k_num - 1):
-                point_angle = angle_order[j + 1] - angle_order[j]
-                angle_var[i] = angle_var[i] + pow(point_angle - 2 * math.pi / k_num, 2)
-
-            point_angle = angle_order[0] - angle_order[k_num - 1] + 2 * math.pi
-            angle_var[i] = angle_var[i] + pow(point_angle - 2 * math.pi / k_num, 2)
-            angle_var[i] = angle_var[i] / k_num
-
-        angle_var = angle_var / ((k_num - 1) * 4 * pow(math.pi, 2) / pow(k_num, 2))
-    else:
-        for i in range(num):
-            try:
-                dif_x = X[get_knn[i], :] - X[i, :]
-                map_x = np.linalg.inv(np.diag(np.sqrt(np.diag(np.dot(dif_x, dif_x.T))))) @ dif_x
-                hull = ConvexHull(map_x)
-                simplex_num = len(hull.simplices)
-                simplex_vol = np.zeros(simplex_num)
-
-                for j in range(simplex_num):
-                    simplex_coord = map_x[hull.simplices[j], :]
-                    simplex_vol[j] = np.sqrt(max(0, np.linalg.det(np.dot(simplex_coord, simplex_coord.T)))) / gamma(d-1)
-
-                angle_var[i] = np.var(simplex_vol)
-
-            except Exception as e:
-                angle_var[i] = 1
-
-    sort_dcm = sorted(angle_var)
-    T_DCM = sort_dcm[math.ceil(num*ratio)]
-    ind = np.zeros(num)
-    for i in range(num):
-        if angle_var[i] < T_DCM:
-            ind[i] = 1
-
-    near_dis = np.zeros(num)
-    for i in range(num):
-        knn_ind = ind[get_knn[i, :]]
-        if ind[i] == 1:
-            if 0 in knn_ind:
-                bdpts_ind = np.where(knn_ind == 0)
-                bd_id = get_knn[i, bdpts_ind[0][0]]
-                near_dis[i] = math.sqrt(sum(pow((X[i, :] - X[bd_id, :]), 2)))
-            else:
-                near_dis[i] = float("inf")
-                for j in range(num):
-                    if ind[j] == 0:
-                        temp_dis = math.sqrt(sum(pow((X[i, :] - X[j, :]), 2)))
-                        if temp_dis < near_dis[i]:
-                            near_dis[i] = temp_dis
-        else:
-            if 1 in knn_ind:
-                bdpts_ind = np.where(knn_ind == 1)
-                bd_id = get_knn[i, bdpts_ind[0][0]]
-                near_dis[i] = bd_id
-            else:
-                mark_dis = float("inf")
-                for j in range(num):
-                    if ind[j] == 1:
-                        temp_dis = math.sqrt(sum(pow((X[i, :] - X[j, :]), 2)))
-                        if temp_dis < mark_dis:
-                            mark_dis = temp_dis
-                            near_dis[i] = j
-
-    cluster = np.zeros(num)
-    mark = 1
-    for i in range(num):
-        if ind[i] == 1 and cluster[i] == 0:
-            cluster[i] = mark
-            for j in range(num):
-                if ind[j] == 1 and math.sqrt(sum(pow((X[i, :] - X[j, :]), 2))) <= near_dis[i] + near_dis[j]:
-                    if cluster[j] == 0:
-                        cluster[j] = cluster[i]
-                    else:
-                        temp_cluster = cluster[j]
-                        temp_ind = np.where(cluster == temp_cluster)
-                        cluster[temp_ind] = cluster[i]
-
-            mark = mark + 1
-
-    for i in range(num):
-        if ind[i] == 0:
-            cluster[i] = cluster[int(near_dis[i])]
-
-    mark = 1
-    storage = np.zeros(num)
-    for i in range(num):
-        if cluster[i] in storage:
-            temp_ind = np.where(storage == cluster[i])
-            cluster[i] = cluster[temp_ind[0][0]]
-        else:
-            storage[i] = cluster[i]
-            cluster[i] = mark
-            mark = mark + 1
-
-    return cluster

cdc_cluster-0.1.1/cdc_cluster.egg-info/top_level.txt

@@ -1 +0,0 @@
-cdc

cdc_cluster-0.1.1/test/test1.py

@@ -1,6 +0,0 @@
-from cdc import cdc_cluster
-import numpy as np
-X = np.random.rand(100, 2)
-labels = cdc_cluster(k_num=5, ratio=0.1, X=X)
-n_clusters = len(np.unique(labels))
-print(f"Number of clusters: {n_clusters}")