# DBSCAN

### *class* cuml.cluster.DBSCAN(, eps=0.5, min_samples=5, metric='euclidean', algorithm='brute', verbose=False, max_mbytes_per_batch=None, output_type=None, calc_core_sample_indices=True)

DBSCAN is a very powerful yet fast clustering technique that finds clusters
where data is concentrated. This allows DBSCAN to generalize to many
problems if the datapoints tend to congregate in larger groups.

cuML’s DBSCAN expects an array-like object or cuDF DataFrame, and
constructs an adjacency graph to compute the distances between close
neighbours.

* **Parameters:**
  **eps**
  : The maximum distance between 2 points such they reside in the same
    neighborhood.

  **min_samples**
  : The number of samples in a neighborhood such that this group can be
    considered as an important core point (including the point itself).

  **metric: {‘euclidean’, ‘cosine’, ‘precomputed’}, default = ‘euclidean’**
  : The metric to use when calculating distances between points.
    If metric is ‘precomputed’, X is assumed to be a distance matrix
    and must be square.
    The input will be modified temporarily when cosine distance is used
    and the restored input matrix might not match completely
    due to numerical rounding.

  **algorithm: {‘brute’, ‘rbc’}, default = ‘brute’**
  : The algorithm to be used by for nearest neighbor computations.

  **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.

  **max_mbytes_per_batch**
  : Calculate batch size using no more than this number of megabytes for
    the pairwise distance computation. This enables the trade-off between
    runtime and memory usage for making the N^2 pairwise distance
    computations more tractable for large numbers of samples.
    If you are experiencing out of memory errors when running DBSCAN, you
    can set this value based on the memory size of your device.
    Note: this option does not set the maximum total memory used in the
    DBSCAN computation and so this value will not be able to be set to
    the total memory available on the device.

  **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.

  **calc_core_sample_indices**
  : Indicates whether the indices of the core samples should be calculated.
    If True (the default), `core_sample_indices_` and `components_` will
    be computed and stored as fitted attributes. Set to False to avoid
    computing these attributes, removing a small amount of overhead.
* **Attributes:**
  **labels_**
  : Which cluster each datapoint belongs to. Noisy samples are labeled as
    -1. Format depends on cuml global output type and estimator
    output_type.

  **core_sample_indices_**
  : The indices of the core samples. Only calculated if
    `calc_core_sample_indices=True`.

  **components_**
  : Copy of each core sample found by training. Only calculated if
    `calc_core_sample_indices=True`.

### Methods

| [`fit`](#cuml.cluster.DBSCAN.fit)(self, X[, y, sample_weight, out_dtype])   | Perform DBSCAN clustering from features.             |
|------------------------------------------------------------------------------------------------|------------------------------------------------------|
| [`fit_predict`](#cuml.cluster.DBSCAN.fit_predict)(self, X[, y, sample_weight, ...]) | Performs clustering on X and returns cluster labels. |

### Notes

DBSCAN is very sensitive to the distance metric it is used with, and a
large assumption is that datapoints need to be concentrated in groups for
clusters to be constructed.

**Applications of DBSCAN**

> DBSCAN’s main benefit is that the number of clusters is not a
> hyperparameter, and that it can find non-linearly shaped clusters.
> This also allows DBSCAN to be robust to noise.
> DBSCAN has been applied to analyzing particle collisions in the
> Large Hadron Collider, customer segmentation in marketing analyses,
> and much more.

For additional docs, see [scikitlearn’s DBSCAN](http://scikit-learn.org/stable/modules/generated/sklearn.cluster.DBSCAN.html).

### Examples

```python
>>> # Both import methods supported
>>> from cuml import DBSCAN
>>> from cuml.cluster import DBSCAN
>>>
>>> import cudf
>>> import numpy as np
>>>
>>> gdf_float = cudf.DataFrame()
>>> gdf_float['0'] = np.asarray([1.0,2.0,5.0], dtype = np.float32)
>>> gdf_float['1'] = np.asarray([4.0,2.0,1.0], dtype = np.float32)
>>> gdf_float['2'] = np.asarray([4.0,2.0,1.0], dtype = np.float32)
>>>
>>> dbscan_float = DBSCAN(eps = 1.0, min_samples = 1)
>>> dbscan_float.fit(gdf_float)
DBSCAN(eps=1.0, min_samples=1)
>>> dbscan_float.labels_
0    0
1    1
2    2
dtype: int32
```

<!-- !! 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 !! -->

#### fit(self, X, y=None, sample_weight=None, , out_dtype='int32') → 'DBSCAN'[[source]](https://github.com/NVIDIA/cuml/blob/93418baf5/python/cuml/cuml/cluster/dbscan.pyx#L299)

Perform DBSCAN clustering 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.

  **sample_weight**
  : The weights for each observation in X. If None, all observations
    are assigned equal weight.
    Acceptable formats: CUDA array interface compliant objects like
    CuPy, cuDF DataFrame/Series, NumPy ndarray and Pandas
    DataFrame/Series.

  **e: dtype**
  : Determines the precision of the output labels array. Options
    are int32 or int64, defaults to int32.

  **sample_weight: array-like of shape (n_samples,), default=None**
  : Weight of each sample, such that a sample with a weight of at
    least min_samples is by itself a core sample; a sample with a
    negative weight may inhibit its eps-neighbor from being core.
    default: None (which is equivalent to weight 1 for all samples).

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

#### fit_predict(self, X, y=None, sample_weight=None, , out_dtype='int32')[[source]](https://github.com/NVIDIA/cuml/blob/93418baf5/python/cuml/cuml/cluster/dbscan.pyx#L470)

Performs clustering on X and returns 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.

  **sample_weight**
  : The weights for each observation in X. If None, all observations
    are assigned equal weight.
    Acceptable formats: CUDA array interface compliant objects like
    CuPy, cuDF DataFrame/Series, NumPy ndarray and Pandas
    DataFrame/Series.

  **e: dtype**
  : Determines the precision of the output labels array. Options
    are int32 or int64, defaults to int32.

  **sample_weight: array-like of shape (n_samples,), default=None**
  : Weight of each sample, such that a sample with a weight of at
    least min_samples is by itself a core sample; a sample with a
    negative weight may inhibit its eps-neighbor from being core.
    default: None (which is equivalent to weight 1 for all samples).

  **Returns**

  **——-**

  **preds**
  : Cluster labels
    <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 !! -->

#### 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 !! -->

#### 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 !! -->