changed parameter name from epsilon to cluster_selection_epsilon and set default value from None to 0.0

Author: cmalzer

hdbscan/_hdbscan_tree.pyx

@@ -609,29 +609,29 @@ cpdef list get_cluster_tree_leaves(np.ndarray cluster_tree):
     root = cluster_tree['parent'].min()
     return recurse_leaf_dfs(cluster_tree, root)
 
-cpdef np.intp_t traverse_upwards(np.ndarray cluster_tree, np.double_t cut_value, np.intp_t leaf):
+cpdef np.intp_t traverse_upwards(np.ndarray cluster_tree, np.double_t cluster_selection_epsilon, np.intp_t leaf):
 
     root = cluster_tree['parent'].min()
     parent = cluster_tree[cluster_tree['child'] == leaf]['parent']
     if parent == root:
         return leaf #return node closest to root
 
     parent_eps = 1/cluster_tree[cluster_tree['child'] == parent]['lambda_val']
-    if parent_eps > cut_value:
+    if parent_eps > cluster_selection_epsilon:
         return parent
     else:
-        return traverse_upwards(cluster_tree, cut_value, parent)
+        return traverse_upwards(cluster_tree, cluster_selection_epsilon, parent)
 
-cpdef set epsilon_search(set leaves, np.ndarray cluster_tree, np.double_t cut_value):
+cpdef set epsilon_search(set leaves, np.ndarray cluster_tree, np.double_t cluster_selection_epsilon):
 
     selected_clusters = list()
     processed = list()
 
     for leaf in leaves:
         eps = 1/cluster_tree['lambda_val'][cluster_tree['child'] == leaf][0]
-        if eps < cut_value:
+        if eps < cluster_selection_epsilon:
                 if leaf not in processed:
-                    epsilon_child = traverse_upwards(cluster_tree, cut_value, leaf)
+                    epsilon_child = traverse_upwards(cluster_tree, cluster_selection_epsilon, leaf)
                     selected_clusters.append(epsilon_child)
 
                     for sub_node in bfs_from_cluster_tree(cluster_tree, epsilon_child):
@@ -646,7 +646,7 @@ cpdef tuple get_clusters(np.ndarray tree, dict stability,
                          cluster_selection_method='eom',
                          allow_single_cluster=False,
                          match_reference_implementation=False,
-                         cut_value=None):
+                         cluster_selection_epsilon=0.0):
     """Given a tree and stability dict, produce the cluster labels
     (and probabilities) for a flat clustering based on the chosen
     cluster selection method.
@@ -672,8 +672,8 @@ cpdef tuple get_clusters(np.ndarray tree, dict stability,
         Whether to match the reference implementation in how to handle
         certain edge cases.
 
-    cut_value: float, optional (default None)
-        A threshold for cluster splits
+    cluster_selection_epsilon: float, optional (default 0.0)
+        A distance threshold for cluster splits.
 
     Returns
     -------
@@ -727,10 +727,10 @@ cpdef tuple get_clusters(np.ndarray tree, dict stability,
                     if sub_node != node:
                         is_cluster[sub_node] = False
 
-        if cut_value is not None and cut_value != 0.0:
+        if cluster_selection_epsilon != 0.0:
 
             eom_clusters = set([c for c in is_cluster if is_cluster[c]])
-            selected_clusters = epsilon_search(eom_clusters, cluster_tree, cut_value)
+            selected_clusters = epsilon_search(eom_clusters, cluster_tree, cluster_selection_epsilon)
             for c in is_cluster:
                 if c in selected_clusters:
                     is_cluster[c] = True
@@ -745,8 +745,8 @@ cpdef tuple get_clusters(np.ndarray tree, dict stability,
                 is_cluster[c] = False
             is_cluster[tree['parent'].min()] = True
 
-        if cut_value is not None and cut_value != 0.0:
-            selected_clusters = epsilon_search(leaves, cluster_tree, cut_value)
+        if cluster_selection_epsilon != 0.0:
+            selected_clusters = epsilon_search(leaves, cluster_tree, cluster_selection_epsilon)
         else:
             selected_clusters = leaves
 

hdbscan/hdbscan_.py

@@ -49,7 +49,7 @@ def _tree_to_labels(X, single_linkage_tree, min_cluster_size=10,
                     cluster_selection_method='eom',
                     allow_single_cluster=False,
                     match_reference_implementation=False,
-					epsilon=None):
+					cluster_selection_epsilon=0.0):
     """Converts a pretrained tree and cluster size into a
     set of labels and probabilities.
     """
@@ -61,7 +61,7 @@ def _tree_to_labels(X, single_linkage_tree, min_cluster_size=10,
                                                       cluster_selection_method,
                                                       allow_single_cluster,
                                                       match_reference_implementation,
-													  epsilon)
+													  cluster_selection_epsilon)
 
     return (labels, probabilities, stabilities, condensed_tree,
             single_linkage_tree)
@@ -329,7 +329,7 @@ def check_precomputed_distance_matrix(X):
     check_array(tmp)
 
 
-def hdbscan(X, min_cluster_size=5, min_samples=None, alpha=1.0, epsilon=None,
+def hdbscan(X, min_cluster_size=5, min_samples=None, alpha=1.0, cluster_selection_epsilon=0.0,
             metric='minkowski', p=2, leaf_size=40,
             algorithm='best', memory=Memory(cachedir=None, verbose=0),
             approx_min_span_tree=True, gen_min_span_tree=False,
@@ -355,8 +355,9 @@ def hdbscan(X, min_cluster_size=5, min_samples=None, alpha=1.0, epsilon=None,
         to be considered as a core point. This includes the point itself.
         defaults to the min_cluster_size.
 
-	epsilon: float, optional (default=None)
-		A threshold for cluster splits.
+	cluster_selection_epsilon: float, optional (default=0.0)
+		A distance threshold. Clusters below this value will be merged.
+        See [3]_ for more information.
 
     alpha : float, optional (default=1.0)
         A distance scaling parameter as used in robust single linkage.
@@ -476,6 +477,8 @@ def hdbscan(X, min_cluster_size=5, min_samples=None, alpha=1.0, epsilon=None,
        cluster tree. In Advances in Neural Information Processing Systems
        (pp. 343-351).
 
+    .. [3] Malzer, C., & Baum, M. (2019). HDBSCAN(ε^): An Alternative Cluster
+       Extraction Method for HDBSCAN. arxiv preprint 1911.02282.
     """
     if min_samples is None:
         min_samples = min_cluster_size
@@ -490,13 +493,10 @@ def hdbscan(X, min_cluster_size=5, min_samples=None, alpha=1.0, epsilon=None,
     if min_cluster_size == 1:
         raise ValueError('Min cluster size must be greater than one')
 
-    if epsilon is None:
-        epsilon = 0.0
-
-    if type(epsilon) is int:
-        epsilon = float(epsilon)
+    if type(cluster_selection_epsilon) is int:
+        cluster_selection_epsilon = float(cluster_selection_epsilon)
 
-    if type(epsilon) is not float or epsilon < 0.0:
+    if type(cluster_selection_epsilon) is not float or cluster_selection_epsilon < 0.0:
         raise ValueError('Epsilon must be a float value greater than or equal to 0!')
 
     if not isinstance(alpha, float) or alpha <= 0.0:
@@ -631,7 +631,7 @@ def hdbscan(X, min_cluster_size=5, min_samples=None, alpha=1.0, epsilon=None,
                            cluster_selection_method,
                            allow_single_cluster,
                            match_reference_implementation,
-						   epsilon) + \
+						   cluster_selection_epsilon) + \
             (result_min_span_tree,)
 
 
@@ -671,6 +671,10 @@ class HDBSCAN(BaseEstimator, ClusterMixin):
         A distance scaling parameter as used in robust single linkage.
         See [3]_ for more information.
 
+    cluster_selection_epsilon: float, optional (default=0.0)
+		A distance threshold. Clusters below this value will be merged.
+        See [5]_ for more information.
+
     algorithm : string, optional (default='best')
         Exactly which algorithm to use; hdbscan has variants specialised
         for different characteristics of the data. By default this is set
@@ -828,9 +832,12 @@ class HDBSCAN(BaseEstimator, ClusterMixin):
        Sander, J., 2014. Density-Based Clustering Validation. In SDM
        (pp. 839-847).
 
+    .. [5] Malzer, C., & Baum, M. (2019). HDBSCAN(ε^): An Alternative Cluster
+       Extraction Method for HDBSCAN. arxiv preprint 1911.02282.
+
     """
 
-    def __init__(self, min_cluster_size=5, min_samples=None, epsilon=None,
+    def __init__(self, min_cluster_size=5, min_samples=None, cluster_selection_epsilon=0.0,
                  metric='euclidean', alpha=1.0, p=None,
                  algorithm='best', leaf_size=40,
                  memory=Memory(cachedir=None, verbose=0),
@@ -844,7 +851,7 @@ def __init__(self, min_cluster_size=5, min_samples=None, epsilon=None,
         self.min_cluster_size = min_cluster_size
         self.min_samples = min_samples
         self.alpha = alpha
-        self.epsilon = epsilon
+        self.cluster_selection_epsilon = cluster_selection_epsilon
         self.metric = metric
         self.p = p
         self.algorithm = algorithm