# HDBSCAN

### *class* cuml.cluster.hdbscan.HDBSCAN(, min_cluster_size=5, min_samples=None, cluster_selection_epsilon=0.0, max_cluster_size=0, metric='euclidean', alpha=1.0, p=None, cluster_selection_method='eom', allow_single_cluster=False, gen_min_span_tree=False, verbose=False, output_type=None, prediction_data=False, build_algo='brute_force', build_kwds=None, device_ids=None)

HDBSCAN Clustering

Recursively merges the pair of clusters that minimally increases a
given linkage distance.

Note that while the algorithm is generally deterministic and should provide
similar results with the Scikit-learn Contrib version, the construction of
the k-nearest neighbors graph and minimum spanning tree can introduce
differences between the two algorithms, especially when several nearest
neighbors around a point might have the same distance. While the
differences in the minimum spanning trees alone might be subtle, they can
(and often will) lead to some points being assigned different cluster
labels between the two implementations.

* **Parameters:**
  **alpha**
  : A distance scaling parameter as used in robust single linkage.

  **verbose**
  : Sets logging level. It must be one of `cuml.common.logger.level_*`.
    See [Verbosity Levels](../../cuml/index.html.md#verbosity-levels) for more info.

  **min_cluster_size**
  : The minimum number of samples in a group for that group to be
    considered a cluster; groupings smaller than this size will be left
    as noise. Must be greater than one.

  **min_samples**
  : The number of nearest neighbors, excluding the point itself, used to
    determine a point’s core distance. This follows the effective
    convention implemented by `hdbscan.HDBSCAN` from
    scikit-learn-contrib. It differs from
    `sklearn.cluster.HDBSCAN`, where `min_samples` includes the point
    itself. For `k >= 2`, to match
    `sklearn.cluster.HDBSCAN(min_samples=k)`, use
    `cuml.cluster.HDBSCAN(min_samples=k - 1)`. The `k = 1` case is not
    supported by cuML. If ‘None’, it defaults to the min_cluster_size.

  **cluster_selection_epsilon**
  : A distance threshold. Clusters below this value will be merged.
    Note that this should not be used
    if we want to predict the cluster labels for new points in future
    (e.g. using approximate_predict), as the approximate_predict function
    is not aware of this argument.

  **max_cluster_size**
  : A limit to the size of clusters returned by the eom algorithm.
    Has no effect when using leaf clustering (where clusters are
    usually small regardless) and can also be overridden in rare
    cases by a high value for cluster_selection_epsilon. Note that
    this should not be used if we want to predict the cluster labels
    for new points in future (e.g. using approximate_predict), as
    the approximate_predict function is not aware of this argument.

  **metric**
  : The metric to use when calculating distance between instances in a
    feature array. Allowed values: ‘euclidean’.

  **p**
  : p value to use if using the minkowski metric.

  **cluster_selection_method**
  : The method used to select clusters from the condensed tree. The
    standard approach for HDBSCAN\* is to use an Excess of Mass algorithm
    to find the most persistent clusters. Alternatively you can instead
    select the clusters at the leaves of the tree – this provides the
    most fine grained and homogeneous clusters. Options are:
    > * `eom`
    > * `leaf`

  **allow_single_cluster**
  : By default HDBSCAN\* will not produce a single cluster, setting this
    to True will override this and allow single cluster results in
    the case that you feel this is a valid result for your dataset.

  **gen_min_span_tree**
  : Whether to populate the [`minimum_spanning_tree_`](#cuml.cluster.hdbscan.HDBSCAN.minimum_spanning_tree_) member for
    utilizing plotting tools. This requires the `hdbscan` CPU Python
    package to be installed.

  **output_type**
  : Return results and set estimator attributes to the indicated output
    type. If None, the output type set at the module level
    (`cuml.global_settings.output_type`) will be used. See
    [Output Data Type Configuration](../../cuml/index.html.md#output-data-type-configuration) for more info.

  **prediction_data**
  : Whether to generate extra cached data for predicting labels or
    membership vectors few new unseen points later. If you wish to
    persist the clustering object for later re-use you probably want
    to set this to True.

  **build_algo: string (default=’brute_force’)**
  : How to build the knn graph. Supported build algorithms are [‘brute_force’,
    ‘nn_descent’]. The ‘nn_descent’ algorithm is typically faster,
    but may result in a slight accuracy drop compared to ‘brute_force’.

  **build_kwds: dict (optional, default=None)**
  : Dictionary of parameters to configure the build algorithm. Default values:
    - `knn_n_clusters` (int, default=1): Number of clusters for data partitioning.
      Higher values reduce memory usage at the cost of accuracy. When `knn_n_clusters > 1`,
      HDBSCAN can process data larger than device memory.
    - `knn_overlap_factor` (int, default=2): Number of clusters each data point belongs to.
      Valid only when `knn_n_clusters > 1`. Must be < ‘knn_n_clusters’.
    - `nnd_graph_degree` (int, default=64): Graph degree used for NN Descent when
      `build_algo=nn_descent`. Must be ≥ `min_samples+1`.
    - `nnd_intermediate_graph_degree` (int, default=128): Intermediate graph degree for
      NN Descent. Must be > `nnd_graph_degree`.
    - `nnd_max_iterations` (int, default=20): Max NN Descent iterations when
      `build_algo=nn_descent`.
    - `nnd_termination_threshold` (float, default=0.0001): Stricter threshold leads to
      better convergence but longer runtime.
    <br/>
    Hints:
    - Increasing `nnd_graph_degree` and `nnd_max_iterations` may improve accuracy
      when `build_algo=nn_descent`.
    - The ratio `knn_overlap_factor / knn_n_clusters` impacts memory usage.
      Approximately `(knn_overlap_factor / knn_n_clusters) * num_rows_in_entire_data`
      rows will be loaded onto device memory at once.  E.g., 2/20 uses less device
      memory than 2/10.
    - Larger `knn_overlap_factor` results in better accuracy of the final knn graph.
      E.g. While using similar amount of device memory,
      `(knn_overlap_factor / knn_n_clusters)` = 4/20 will have better accuracy
      than 2/10 at the cost of performance.
    - Start with `knn_overlap_factor = 2` and gradually increase (2->3->4 …)
      for better accuracy.
    - Start with `knn_n_clusters = 4` and increase (4 → 8 → 16…) for less GPU
      memory usage. This is independent from knn_overlap_factor as long as
      ‘knn_overlap_factor’ < ‘knn_n_clusters’.

  **device_ids**
  : The device IDs to use during fitting (only used when
    `build_algo=nn_descent` and `nnd_n_clusters > 1`). May be a list of
    ids, `"all"` (to use all available devices), or `None` (to fit
    using a single GPU only). Default is None.
* **Attributes:**
  **labels_**
  : Cluster labels for each point in the dataset given to fit().
    Noisy samples are given the label -1.

  **probabilities_**
  : The strength with which each sample is a member of its assigned
    cluster. Noise points have probability zero; points in clusters
    have values assigned proportional to the degree that they
    persist as part of the cluster.

  **cluster_persistence_**
  : A score of how persistent each cluster is. A score of 1.0 represents
    a perfectly stable cluster that persists over all distance scales,
    while a score of 0.0 represents a perfectly ephemeral cluster. These
    scores can be used to gauge the relative coherence of the
    clusters output by the algorithm.

  [`condensed_tree_`](#cuml.cluster.hdbscan.HDBSCAN.condensed_tree_)
  : HDBSCAN.condensed_tree_(self)

  [`single_linkage_tree_`](#cuml.cluster.hdbscan.HDBSCAN.single_linkage_tree_)
  : HDBSCAN.single_linkage_tree_(self)

  [`minimum_spanning_tree_`](#cuml.cluster.hdbscan.HDBSCAN.minimum_spanning_tree_)
  : HDBSCAN.minimum_spanning_tree_(self)

### Methods

| [`fit`](#cuml.cluster.hdbscan.HDBSCAN.fit)(self, X[, y])              | Fit HDBSCAN model from features.                                                                 |
|---------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------|
| [`fit_predict`](#cuml.cluster.hdbscan.HDBSCAN.fit_predict)(self, X[, y])      | Fit the HDBSCAN model from features and return cluster labels.                                   |
| [`generate_prediction_data`](#cuml.cluster.hdbscan.HDBSCAN.generate_prediction_data)(self) | Create data that caches intermediate results used for predicting the label of new/unseen points. |
<!-- !! processed by numpydoc !! -->

#### as_sklearn()[[source]](https://github.com/NVIDIA/cuml/blob/93418baf5/python/cuml/cuml/internals/interop.py#L206)

Convert this estimator into an equivalent scikit-learn (or scikit-learn
extension) estimator.

* **Returns:**
  sklearn.base.BaseEstimator
  : A scikit-learn compatible estimator instance that mirrors the trained
    state of the current estimator.

<!-- !! processed by numpydoc !! -->

#### *property* condensed_tree_

<!-- !! processed by numpydoc !! -->

#### fit(self, X, y=None) → 'HDBSCAN'[[source]](https://github.com/NVIDIA/cuml/blob/93418baf5/python/cuml/cuml/cluster/hdbscan/hdbscan.pyx#L925)

Fit HDBSCAN model from features.

* **Parameters:**
  **X**
  : Dense matrix with dtype float32 or float64.
    Acceptable formats: CUDA array interface compliant objects like
    CuPy, cuDF DataFrame/Series, NumPy ndarray and Pandas
    DataFrame/Series.

  **y**
  : Dense matrix with dtype float32 or float64.
    Acceptable formats: CUDA array interface compliant objects like
    CuPy, cuDF DataFrame/Series, NumPy ndarray and Pandas
    DataFrame/Series.

<!-- !! processed by numpydoc !! -->

#### fit_predict(self, X, y=None)[[source]](https://github.com/NVIDIA/cuml/blob/93418baf5/python/cuml/cuml/cluster/hdbscan/hdbscan.pyx#L1083)

Fit the HDBSCAN model from features and return
cluster labels.

* **Parameters:**
  **X**
  : Dense matrix with dtype float32 or float64.
    Acceptable formats: CUDA array interface compliant objects like
    CuPy, cuDF DataFrame/Series, NumPy ndarray and Pandas
    DataFrame/Series.

  **y**
  : Dense matrix with dtype float32 or float64.
    Acceptable formats: CUDA array interface compliant objects like
    CuPy, cuDF DataFrame/Series, NumPy ndarray and Pandas
    DataFrame/Series.
* **Returns:**
  **preds**
  : Cluster indexes
    <br/>
    For more information on how to configure cuML’s output type,
    refer to: [Output Data Type Configuration](../../cuml/index.html.md#output-data-type-configuration).

<!-- !! processed by numpydoc !! -->

#### *classmethod* from_sklearn(model)[[source]](https://github.com/NVIDIA/cuml/blob/93418baf5/python/cuml/cuml/internals/interop.py#L222)

Create a cuml estimator from a scikit-learn estimator.

* **Parameters:**
  **model**
  : A compatible scikit-learn (or scikit-learn extension) estimator.
* **Returns:**
  cls
  : A new instance of this cuml estimator class that mirrors the
    state of the input estimator.

### Notes

`output_type` of the estimator is set to “numpy” by default, as these
cannot be inferred from training arguments. If something different is
required, then please use cuml’s output_type configuration utilities.

<!-- !! processed by numpydoc !! -->

#### generate_prediction_data(self)[[source]](https://github.com/NVIDIA/cuml/blob/93418baf5/python/cuml/cuml/cluster/hdbscan/hdbscan.pyx#L911)

Create data that caches intermediate results used for predicting
the label of new/unseen points. This data is only useful if you
are intending to use functions from hdbscan.prediction.

<!-- !! processed by numpydoc !! -->

#### get_params(deep=True)[[source]](https://github.com/NVIDIA/cuml/blob/93418baf5/python/cuml/cuml/internals/base.py#L191)

Returns a dict of all params owned by this class. If the child class
has appropriately overridden the `_get_param_names` method and does not
need anything other than what is there in this method, then it doesn’t
have to override this method

<!-- !! processed by numpydoc !! -->

#### *property* minimum_spanning_tree_

<!-- !! processed by numpydoc !! -->

#### *property* prediction_data_

<!-- !! processed by numpydoc !! -->

#### set_params(\*\*params)[[source]](https://github.com/NVIDIA/cuml/blob/93418baf5/python/cuml/cuml/internals/base.py#L200)

Accepts a dict of params and updates the corresponding ones owned by
this class. If the child class has appropriately overridden the
`_get_param_names` method and does not need anything other than what is,
there in this method, then it doesn’t have to override this method

<!-- !! processed by numpydoc !! -->

#### *property* single_linkage_tree_

<!-- !! processed by numpydoc !! -->