fast-hdbscan 0.1.0__tar.gz

fast_hdbscan-0.1.0/LICENSE

@@ -0,0 +1,24 @@
+BSD 2-Clause License
+
+Copyright (c) 2023, Tutte Institute for Mathematics and Computing
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

fast_hdbscan-0.1.0/PKG-INFO

@@ -0,0 +1,121 @@
+Metadata-Version: 1.2
+Name: fast_hdbscan
+Version: 0.1.0
+Summary: A fast multicore version of hdbscan for low dimensional euclidean spaces
+Home-page: https://github.com/TutteInstitute/fast_hdbscan
+Author: Leland McInnes
+Author-email: leland.mcinnes@gmail.com
+Maintainer: Leland McInnes
+Maintainer-email: leland.mcinnes@gmail.com
+License: BSD 2-Clause License
+Description: .. -*- mode: rst -*-
+        
+        .. image:: doc/hdbscan_logo.png
+          :width: 600
+          :alt: HDBSCAN logo
+          :align: center
+        
+        ======================
+        Fast Multicore HDBSCAN
+        ======================
+        
+        Ahe ``fast_hdbscan`` library provides a simple implementation of the HDBSCAN clustering algorithm designed specifically
+        for high performance on multicore machine with low dimensional data. The algorithm runs in parallel and can make
+        effective use of as many cores as you wish to throw at a problem. It is thus ideal for large SMP systems, and even
+        modern multicore laptops.
+        
+        This library provides a
+        re-implementation of a subset of the HDBSCAN algorithm that is compatible with the
+        `hdbscan <https://github.com/scikit-learn-contrib/hdbscan>`_ library for data that is Euclidean and
+        low dimensional. The primary advantages of this library over the standard ``hdbscan`` library are:
+        
+        
+         * this library can easily use all available cores to speed up computation;
+         * this library has much faster implementations of tree condensing and cluster extraction;
+         * this library is much simpler and more approachable for extending or using components from;
+         * this library is built on numba and has less issues with binaries and compilation.
+        
+        This library does not support all the features and input formats available in the hdbscan library.
+        
+        -----------
+        Basic Usage
+        -----------
+        
+        The ``fast_hdbscan`` library follows the ``hdbscan`` library in using the sklearn API. You can use the ``fast_hdbscan``
+        class ``HDBSCAN`` exactly as you wuld that of the ``hdbscan`` library with the caveat that ``fast_hdbscan`` only
+        supports a subset of the parameters and options of ``hdbscan``. Nonetheless, if you have low-dimensional
+        Euclidean data (e.g. the output of UMAP), you can use this library as a straightforward drop in replacement for
+        ``hdbscan``:
+        
+        .. code:: python
+        
+            import fast_hdbscan
+            from sklearn.datasets import make_blobs
+        
+            data, _ = make_blobs(1000)
+        
+            clusterer = fast_hdbscan.HDBSCAN(min_cluster_size=10)
+            cluster_labels = clusterer.fit_predict(data)
+        
+        ------------
+        Installation
+        ------------
+        fast_hdbscan requires:
+        
+         * numba
+         * numpy
+         * scikit-learn
+        
+        fast_hdbscan can be installed via pip:
+        
+        .. code:: bash
+        
+            pip install fast-hdbscan
+        
+        To manually install this package:
+        
+        .. code:: bash
+        
+            wget https://github.com/TutteInstitute/fast_hdbscan/archive/main.zip
+            unzip main.zip
+            rm main.zip
+            cd fast_hdbscan-main
+            python setup.py install
+        
+        ----------
+        References
+        ----------
+        
+        The algorithm used here is an adaptation of the algorithms described in the papers:
+        
+            McInnes L, Healy J. *Accelerated Hierarchical Density Based Clustering*
+            In: 2017 IEEE International Conference on Data Mining Workshops (ICDMW), IEEE, pp 33-42.
+            2017 `[pdf] <http://ieeexplore.ieee.org/stamp/stamp.jsp?tp=&arnumber=8215642>`_
+        
+            R. Campello, D. Moulavi, and J. Sander, *Density-Based Clustering Based on
+            Hierarchical Density Estimates*
+            In: Advances in Knowledge Discovery and Data Mining, Springer, pp 160-172.
+            2013
+        
+        -------
+        License
+        -------
+        
+        fast_hdbscan is BSD (2-clause) licensed. See the LICENSE file for details.
+        
+        ------------
+        Contributing
+        ------------
+        
+        Contributions are more than welcome! If you have ideas for features of projects please get in touch. Everything from
+        code to notebooks to examples and documentation are all *equally valuable* so please don't feel you can't contribute.
+        To contribute please `fork the project <https://github.com/TutteInstitute/fast_hdbscan/issues#fork-destination-box>`_ make your
+        changes and submit a pull request. We will do our best to work through any issues with you and get your code merged in.
+Keywords: cluster,clustering,hdbscan,dbscan
+Platform: UNKNOWN
+Classifier: License :: OSI Approved :: BSD License
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Development Status :: 4 - Beta
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.9

fast_hdbscan-0.1.0/README.rst

@@ -0,0 +1,103 @@
+.. -*- mode: rst -*-
+
+.. image:: doc/hdbscan_logo.png
+  :width: 600
+  :alt: HDBSCAN logo
+  :align: center
+
+======================
+Fast Multicore HDBSCAN
+======================
+
+Ahe ``fast_hdbscan`` library provides a simple implementation of the HDBSCAN clustering algorithm designed specifically
+for high performance on multicore machine with low dimensional data. The algorithm runs in parallel and can make
+effective use of as many cores as you wish to throw at a problem. It is thus ideal for large SMP systems, and even
+modern multicore laptops.
+
+This library provides a
+re-implementation of a subset of the HDBSCAN algorithm that is compatible with the
+`hdbscan <https://github.com/scikit-learn-contrib/hdbscan>`_ library for data that is Euclidean and
+low dimensional. The primary advantages of this library over the standard ``hdbscan`` library are:
+
+
+ * this library can easily use all available cores to speed up computation;
+ * this library has much faster implementations of tree condensing and cluster extraction;
+ * this library is much simpler and more approachable for extending or using components from;
+ * this library is built on numba and has less issues with binaries and compilation.
+
+This library does not support all the features and input formats available in the hdbscan library.
+
+-----------
+Basic Usage
+-----------
+
+The ``fast_hdbscan`` library follows the ``hdbscan`` library in using the sklearn API. You can use the ``fast_hdbscan``
+class ``HDBSCAN`` exactly as you wuld that of the ``hdbscan`` library with the caveat that ``fast_hdbscan`` only
+supports a subset of the parameters and options of ``hdbscan``. Nonetheless, if you have low-dimensional
+Euclidean data (e.g. the output of UMAP), you can use this library as a straightforward drop in replacement for
+``hdbscan``:
+
+.. code:: python
+
+    import fast_hdbscan
+    from sklearn.datasets import make_blobs
+
+    data, _ = make_blobs(1000)
+
+    clusterer = fast_hdbscan.HDBSCAN(min_cluster_size=10)
+    cluster_labels = clusterer.fit_predict(data)
+
+------------
+Installation
+------------
+fast_hdbscan requires:
+
+ * numba
+ * numpy
+ * scikit-learn
+
+fast_hdbscan can be installed via pip:
+
+.. code:: bash
+
+    pip install fast-hdbscan
+
+To manually install this package:
+
+.. code:: bash
+
+    wget https://github.com/TutteInstitute/fast_hdbscan/archive/main.zip
+    unzip main.zip
+    rm main.zip
+    cd fast_hdbscan-main
+    python setup.py install
+
+----------
+References
+----------
+
+The algorithm used here is an adaptation of the algorithms described in the papers:
+
+    McInnes L, Healy J. *Accelerated Hierarchical Density Based Clustering*
+    In: 2017 IEEE International Conference on Data Mining Workshops (ICDMW), IEEE, pp 33-42.
+    2017 `[pdf] <http://ieeexplore.ieee.org/stamp/stamp.jsp?tp=&arnumber=8215642>`_
+
+    R. Campello, D. Moulavi, and J. Sander, *Density-Based Clustering Based on
+    Hierarchical Density Estimates*
+    In: Advances in Knowledge Discovery and Data Mining, Springer, pp 160-172.
+    2013
+
+-------
+License
+-------
+
+fast_hdbscan is BSD (2-clause) licensed. See the LICENSE file for details.
+
+------------
+Contributing
+------------
+
+Contributions are more than welcome! If you have ideas for features of projects please get in touch. Everything from
+code to notebooks to examples and documentation are all *equally valuable* so please don't feel you can't contribute.
+To contribute please `fork the project <https://github.com/TutteInstitute/fast_hdbscan/issues#fork-destination-box>`_ make your
+changes and submit a pull request. We will do our best to work through any issues with you and get your code merged in.

fast_hdbscan-0.1.0/fast_hdbscan/__init__.py

@@ -0,0 +1,10 @@
+from .hdbscan import HDBSCAN, fast_hdbscan
+
+# Force JIT compilation on import
+import numpy as np
+random_state = np.random.RandomState(42)
+random_data = random_state.random(size=(100, 3))
+HDBSCAN(allow_single_cluster=True).fit(random_data)
+HDBSCAN(cluster_selection_method="leaf").fit(random_data)
+
+__all__ = ["HDBSCAN", "fast_hdbscan"]

fast_hdbscan-0.1.0/fast_hdbscan/boruvka.py

@@ -0,0 +1,277 @@
+import numba
+import numpy as np
+
+from .disjoint_set import ds_rank_create, ds_find, ds_union_by_rank
+from .numba_kdtree import parallel_tree_query, rdist, point_to_node_lower_bound_rdist
+
+@numba.njit()
+def merge_components(disjoint_set, candidate_neighbors, candidate_neighbor_distances, point_components):
+    component_edges = {0: (0, np.int32(1), np.float32(0.0)) for i in range(0)}
+
+    # Find the best edges from each component
+    for i in range(candidate_neighbors.shape[0]):
+        from_component = point_components[i]
+        if from_component in component_edges:
+            if candidate_neighbor_distances[i] < component_edges[from_component][2]:
+                component_edges[from_component] = (i, candidate_neighbors[i], candidate_neighbor_distances[i])
+        else:
+            component_edges[from_component] = (i, candidate_neighbors[i], candidate_neighbor_distances[i])
+
+    result = np.empty((len(component_edges), 3), dtype=np.float64)
+    result_idx = 0
+
+    # Add the best edges to the edge set and merge the relevant components
+    for edge in component_edges.values():
+        from_component = ds_find(disjoint_set, np.int32(edge[0]))
+        to_component = ds_find(disjoint_set, np.int32(edge[1]))
+        if from_component != to_component:
+            result[result_idx] = (np.float64(edge[0]), np.float64(edge[1]), np.float64(edge[2]))
+            result_idx += 1
+
+            ds_union_by_rank(disjoint_set, from_component, to_component)
+
+    return result[:result_idx]
+
+
+@numba.njit(parallel=True)
+def update_component_vectors(tree, disjoint_set, node_components, point_components):
+    for i in numba.prange(point_components.shape[0]):
+        point_components[i] = ds_find(disjoint_set, np.int32(i))
+
+    for i in range(tree.node_data.shape[0] - 1, -1, -1):
+        node_info = tree.node_data[i]
+
+        # Case 1:
+        #    If the node is a leaf we need to check that every point
+        #    in the node is of the same component
+        if node_info.is_leaf:
+            candidate_component = point_components[tree.idx_array[node_info.idx_start]]
+            for j in range(node_info.idx_start + 1, node_info.idx_end):
+                idx = tree.idx_array[j]
+                if point_components[idx] != candidate_component:
+                    break
+            else:
+                node_components[i] = candidate_component
+
+        # Case 2:
+        #    If the node is not a leaf we only need to check
+        #    that both child nodes are in the same component
+        else:
+            left = 2 * i + 1
+            right = left + 1
+
+            if node_components[left] == node_components[right]:
+                node_components[i] = node_components[left]
+
+
+@numba.njit()
+def component_aware_query_recursion(
+        tree,
+        node,
+        point,
+        heap_p,
+        heap_i,
+        current_core_distance,
+        core_distances,
+        current_component,
+        node_components,
+        point_components,
+        dist_lower_bound,
+        component_nearest_neighbor_dist,
+):
+    node_info = tree.node_data[node]
+
+    # ------------------------------------------------------------
+    # Case 1a: query point is outside node radius:
+    #         trim it from the query
+    if dist_lower_bound > heap_p[0]:
+        return
+
+    # ------------------------------------------------------------
+    # Case 1b: we can't improve on the best distance for this component
+    #         trim it from the query
+    elif dist_lower_bound > component_nearest_neighbor_dist[0] or current_core_distance > \
+            component_nearest_neighbor_dist[0]:
+        return
+
+    # ------------------------------------------------------------
+    # Case 1c: node contains only points in same component as query
+    #         trim it from the query
+    elif node_components[node] == current_component:
+        return
+
+    # ------------------------------------------------------------
+    # Case 2: this is a leaf node.  Update set of nearby points
+    elif node_info.is_leaf:
+        for i in range(node_info.idx_start, node_info.idx_end):
+            idx = tree.idx_array[i]
+            if point_components[idx] != current_component and core_distances[idx] < component_nearest_neighbor_dist[0]:
+                d = max(rdist(point, tree.data[idx]), current_core_distance, core_distances[idx])
+                if d < heap_p[0]:
+                    heap_p[0] = d
+                    heap_i[0] = idx
+                    if d < component_nearest_neighbor_dist[0]:
+                        component_nearest_neighbor_dist[0] = d
+
+    # ------------------------------------------------------------
+    # Case 3: Node is not a leaf.  Recursively query subnodes
+    #         starting with the closest
+    else:
+        left = 2 * node + 1
+        right = left + 1
+        dist_lower_bound_left = point_to_node_lower_bound_rdist(tree.node_bounds[0, left], tree.node_bounds[1, left],
+                                                                point)
+        dist_lower_bound_right = point_to_node_lower_bound_rdist(tree.node_bounds[0, right], tree.node_bounds[1, right],
+                                                                 point)
+
+        # recursively query subnodes
+        if dist_lower_bound_left <= dist_lower_bound_right:
+            component_aware_query_recursion(
+                tree,
+                left,
+                point,
+                heap_p,
+                heap_i,
+                current_core_distance,
+                core_distances,
+                current_component,
+                node_components,
+                point_components,
+                dist_lower_bound_left,
+                component_nearest_neighbor_dist
+            )
+            component_aware_query_recursion(
+                tree,
+                right,
+                point,
+                heap_p,
+                heap_i,
+                current_core_distance,
+                core_distances,
+                current_component,
+                node_components,
+                point_components,
+                dist_lower_bound_right,
+                component_nearest_neighbor_dist
+            )
+        else:
+            component_aware_query_recursion(
+                tree,
+                right,
+                point,
+                heap_p,
+                heap_i,
+                current_core_distance,
+                core_distances,
+                current_component,
+                node_components,
+                point_components,
+                dist_lower_bound_right,
+                component_nearest_neighbor_dist
+            )
+            component_aware_query_recursion(
+                tree,
+                left,
+                point,
+                heap_p,
+                heap_i,
+                current_core_distance,
+                core_distances,
+                current_component,
+                node_components,
+                point_components,
+                dist_lower_bound_left,
+                component_nearest_neighbor_dist
+            )
+
+    return
+
+
+@numba.njit(parallel=True)
+def boruvka_tree_query(tree, node_components, point_components, core_distances):
+    candidate_distances = np.full(tree.data.shape[0], np.inf, dtype=np.float32)
+    candidate_indices = np.full(tree.data.shape[0], -1, dtype=np.int32)
+    component_nearest_neighbor_dist = np.full(tree.data.shape[0], np.inf, dtype=np.float32)
+
+    data = np.asarray(tree.data.astype(np.float32))
+
+    for i in numba.prange(tree.data.shape[0]):
+        distance_lower_bound = point_to_node_lower_bound_rdist(tree.node_bounds[0, 0], tree.node_bounds[1, 0],
+                                                               tree.data[i])
+        heap_p, heap_i = candidate_distances[i:i + 1], candidate_indices[i:i + 1]
+        component_aware_query_recursion(
+            tree,
+            0,
+            data[i],
+            heap_p,
+            heap_i,
+            core_distances[i],
+            core_distances,
+            point_components[i],
+            node_components,
+            point_components,
+            distance_lower_bound,
+            component_nearest_neighbor_dist[point_components[i]:point_components[i] + 1]
+        )
+
+    return candidate_distances, candidate_indices
+
+
+@numba.njit(parallel=True)
+def initialize_boruvka_from_knn(knn_indices, knn_distances, core_distances, disjoint_set):
+    # component_edges = {0:(np.int32(0), np.int32(1), np.float32(0.0)) for i in range(0)}
+    component_edges = np.full((knn_indices.shape[0], 3), -1, dtype=np.float64)
+
+    for i in numba.prange(knn_indices.shape[0]):
+        for j in range(1, knn_indices.shape[1]):
+            k = np.int32(knn_indices[i, j])
+            if core_distances[i] >= core_distances[k]:
+                component_edges[i] = (np.float64(i), np.float64(k), np.float64(core_distances[i]))
+                break
+
+    result = np.empty((len(component_edges), 3), dtype=np.float64)
+    result_idx = 0
+
+    # Add the best edges to the edge set and merge the relevant components
+    for edge in component_edges:
+        if edge[0] < 0:
+            continue
+        from_component = ds_find(disjoint_set, np.int32(edge[0]))
+        to_component = ds_find(disjoint_set, np.int32(edge[1]))
+        if from_component != to_component:
+            result[result_idx] = (np.float64(edge[0]), np.float64(edge[1]), np.float64(edge[2]))
+            result_idx += 1
+
+            ds_union_by_rank(disjoint_set, from_component, to_component)
+
+    return result[:result_idx]
+
+
+def parallel_boruvka(tree, min_samples=10):
+    components_disjoint_set = ds_rank_create(tree.data.shape[0])
+    point_components = np.arange(tree.data.shape[0])
+    node_components = np.full(tree.node_data.shape[0], -1)
+    n_components = point_components.shape[0]
+
+    if min_samples > 1:
+        distances, neighbors = parallel_tree_query(tree, tree.data, k=min_samples + 1, output_rdist=True)
+        core_distances = distances.T[-1]
+        edges = initialize_boruvka_from_knn(neighbors, distances, core_distances, components_disjoint_set)
+        update_component_vectors(tree, components_disjoint_set, node_components, point_components)
+    else:
+        core_distances = np.zeros(tree.data.shape[0], dtype=np.float32)
+        distances, neighbors = parallel_tree_query(tree, tree.data, k=2)
+        edges = initialize_boruvka_from_knn(neighbors, distances, core_distances, components_disjoint_set)
+        update_component_vectors(tree, components_disjoint_set, node_components, point_components)
+
+    while n_components > 1:
+        candidate_distances, candidate_indices = boruvka_tree_query(tree, node_components, point_components,
+                                                                    core_distances)
+        new_edges = merge_components(components_disjoint_set, candidate_indices, candidate_distances, point_components)
+        update_component_vectors(tree, components_disjoint_set, node_components, point_components)
+
+        edges = np.vstack((edges, new_edges))
+        n_components = np.unique(point_components).shape[0]
+
+    edges[:, 2] = np.sqrt(edges.T[2])
+    return edges