# UMAP

### *class* cuml.manifold.UMAP(, n_neighbors=15, n_components=2, metric='euclidean', metric_kwds=None, n_epochs=None, learning_rate=1.0, min_dist=0.1, spread=1.0, set_op_mix_ratio=1.0, local_connectivity=1.0, repulsion_strength=1.0, negative_sample_rate=5, transform_queue_size=4.0, init='spectral', a=None, b=None, target_n_neighbors=-1, target_weight=0.5, target_metric='categorical', hash_input=False, random_state=None, force_serial_epochs=None, precomputed_knn=None, callback=None, build_algo='auto', build_kwds=None, device_ids=None, verbose=False, output_type=None)

Uniform Manifold Approximation and Projection

Finds a low dimensional embedding of the data that approximates
an underlying manifold.

Adapted from [https://github.com/lmcinnes/umap/blob/master/umap/](https://github.com/lmcinnes/umap/blob/master/umap/)[umap]().py

The UMAP algorithm is outlined in [1]. This implementation follows the
GPU-accelerated version as described in [2].

* **Parameters:**
  **n_neighbors: float (optional, default 15)**
  : The size of local neighborhood (in terms of number of neighboring
    sample points) used for manifold approximation. Larger values
    result in more global views of the manifold, while smaller
    values result in more local data being preserved. In general
    values should be in the range 2 to 100.

  **n_components: int (optional, default 2)**
  : The dimension of the space to embed into. This defaults to 2 to
    provide easy visualization, but can reasonably be set to any

  **metric: string (default=’euclidean’).**
  : Distance metric to use. Supported distances are [‘l1, ‘cityblock’,
    ‘taxicab’, ‘manhattan’, ‘euclidean’, ‘l2’, ‘sqeuclidean’, ‘canberra’,
    ‘minkowski’, ‘chebyshev’, ‘linf’, ‘cosine’, ‘correlation’, ‘hellinger’,
    ‘hamming’, ‘jaccard’]
    Metrics that take arguments (such as minkowski) can have arguments
    passed via the metric_kwds dictionary.
    Note: The ‘jaccard’ distance metric is only supported for sparse
    inputs.
    Note: If build_algo=\`brute_force_knn\` and `knn_n_clusters > 1`, the metric
    must be one of [‘l2’, ‘sqeuclidean’, ‘euclidean’, ‘cosine’, ‘inner_product’].

  **metric_kwds: dict (optional, default=None)**
  : Metric argument

  **n_epochs: int (optional, default None)**
  : The number of training epochs to be used in optimizing the
    low dimensional embedding. Larger values result in more accurate
    embeddings. If None is specified a value will be selected based on
    the size of the input dataset (200 for large datasets, 500 for small).

  **learning_rate: float (optional, default 1.0)**
  : The initial learning rate for the embedding optimization.

  **init: string (optional, default ‘spectral’)**
  : How to initialize the low dimensional embedding. Options are:
    * ‘spectral’: use a spectral embedding of the fuzzy 1-skeleton
    * ‘random’: assign initial embedding positions at random.
    * An array-like with initial embedding positions.
    <br/>
    Note: When `init='spectral'` and `n_components <= 512`,
    `force_serial_epochs` defaults to `True` because spectral
    initialization is more susceptible to outlier artifacts. Pass
    `force_serial_epochs=False` explicitly to disable and use the
    faster parallel batch kernel.

  **min_dist: float (optional, default 0.1)**
  : The effective minimum distance between embedded points. Smaller values
    will result in a more clustered/clumped embedding where nearby points
    on the manifold are drawn closer together, while larger values will
    result on a more even dispersal of points. The value should be set
    relative to the `spread` value, which determines the scale at which
    embedded points will be spread out.

  **spread: float (optional, default 1.0)**
  : The effective scale of embedded points. In combination with
    `min_dist` this determines how clustered/clumped the embedded
    points are.

  **set_op_mix_ratio: float (optional, default 1.0)**
  : Interpolate between (fuzzy) union and intersection as the set operation
    used to combine local fuzzy simplicial sets to obtain a global fuzzy
    simplicial sets. Both fuzzy set operations use the product t-norm.
    The value of this parameter should be between 0.0 and 1.0; a value of
    1.0 will use a pure fuzzy union, while 0.0 will use a pure fuzzy
    intersection.

  **local_connectivity: int (optional, default 1)**
  : The local connectivity required – i.e. the number of nearest
    neighbors that should be assumed to be connected at a local level.
    The higher this value the more connected the manifold becomes
    locally. In practice this should be not more than the local intrinsic
    dimension of the manifold.

  **repulsion_strength: float (optional, default 1.0)**
  : Weighting applied to negative samples in low dimensional embedding
    optimization. Values higher than one will result in greater weight
    being given to negative samples.

  **negative_sample_rate: int (optional, default 5)**
  : The number of negative samples to select per positive sample
    in the optimization process. Increasing this value will result
    in greater repulsive force being applied, greater optimization
    cost, but slightly more accuracy.

  **transform_queue_size: float (optional, default 4.0)**
  : For transform operations (embedding new points using a trained model
    this will control how aggressively to search for nearest neighbors.
    Larger values will result in slower performance but more accurate
    nearest neighbor evaluation.

  **a: float (optional, default None)**
  : More specific parameters controlling the embedding. If None these
    values are set automatically as determined by `min_dist` and
    `spread`.

  **b: float (optional, default None)**
  : More specific parameters controlling the embedding. If None these
    values are set automatically as determined by `min_dist` and
    `spread`.

  **target_n_neighbors: int (optional, default=-1)**
  : The number of nearest neighbors to use to construct the target
    simplicial set. If set to -1 use the `n_neighbors` value.

  **target_metric: string (optional, default=’categorical’)**
  : The metric used to measure distance for a target array when using
    supervised dimension reduction. By default this is ‘categorical’
    which will measure distance in terms of whether categories match
    or are different. Furthermore, if semi-supervised is required
    target values of -1 will be treated as unlabelled under the
    ‘categorical’ metric. If the target array takes continuous values
    (e.g. for a regression problem) then metric of ‘euclidean’ or ‘l2’
    is probably more appropriate.

  **target_weight: float (optional, default=0.5)**
  : Weighting factor between data topology and target topology. A
    value of 0.0 weights predominantly on data, a value of 1.0 places
    a strong emphasis on target. The default of 0.5 balances the
    weighting equally between data and target.

  **hash_input: bool, optional (default = False)**
  : UMAP can hash the training input so that exact embeddings
    are returned when transform is called on the same data upon
    which the model was trained. This enables consistent
    behavior between calling `model.fit_transform(X)` and
    calling `model.fit(X).transform(X)`. Note that the CPU-based
    UMAP reference implementation does this by default. This
    feature is made optional in the GPU version due to the
    significant overhead in copying memory to the host for
    computing the hash.

  **precomputed_knn**
  : This feature allows the precomputation of the KNN outside of UMAP.
    Options are:
    - A tuple (indices, distances) of dense arrays of shape (n_samples,
      n_neighbors), where n_neighbors is >= the `n_neighbors` parameter.
      Self references should be included (i.e. the first column of
      `indices` should be [0, 1, …], denotating that the nearest neighbor
      to each row is itself). This is the most efficient representation.
      Note that providing on CPU may result in lower peak GPU memory usage.
    - A sparse matrix KNN graph, as may be output by
      `cuml.neighbors.kneighbors_graph` with `mode="distance"` and
      `include_self=True`. The `n_neighbors` used to calculate the
      graph must be >= the `n_neighbors` parameter.
    - A pairwise distances dense array of shape (n_samples, n_samples).
    <br/>
    In all cases the KNN should be computed using the same `metric` as
    provided to `UMAP`.

  **random_state**
  : Seed used by the random number generator for embedding initialization
    and optimizer sampling. Setting a random_state enables reproducible
    embeddings, but at the cost of slower training and increased memory
    usage. This is because high parallelism during optimization involves
    non-deterministic floating-point addition ordering.
    <br/>
    Note: Explicitly setting `build_algo='nn_descent'` will break
    reproducibility, as NN Descent produces non-deterministic KNN graphs.

  **force_serial_epochs: bool or None, optional (default=None)**
  : Controls whether optimization epochs use the sequential (reduced
    GPU parallelism) kernel. When `None` (the default), serial epochs
    are enabled automatically for `init='spectral'` with
    `n_components <= 512` because spectral initialization is more
    susceptible to outlier artifacts; for `n_components > 512` the
    auto-default falls back to `False` since the serial kernel does
    not support that range. Pass `True` to force serial epochs
    regardless of init (only supported for `n_components <= 512`;
    otherwise a `ValueError` is raised), or `False` to disable them.

  **callback: An instance of GraphBasedDimRedCallback class**
  : Used to intercept the internal state of embeddings while they are being
    trained. Example of callback usage:
    ```python
    from cuml.internals import GraphBasedDimRedCallback
    <br/>
    class CustomCallback(GraphBasedDimRedCallback):
        def on_preprocess_end(self, embeddings):
            print(embeddings)
    <br/>
        def on_epoch_end(self, embeddings):
            print(embeddings)
    <br/>
        def on_train_end(self, embeddings):
            print(embeddings)
    ```

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

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

  **build_algo: string (default=’auto’)**
  : How to build the knn graph. Supported build algorithms are [‘auto’, ‘brute_force_knn’,
    ‘nn_descent’]. ‘auto’ chooses to run with brute force knn if number of data rows is
    smaller than or equal to 50K. Otherwise, runs with nn descent.

  **build_kwds: dict (optional, default=None)**
  : Dictionary of parameters to configure the build algorithm. Default values:
    - `nnd_graph_degree` (int, default=64): Graph degree used for NN Descent.
      Must be ≥ `n_neighbors`.
    - `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.
    - `nnd_termination_threshold` (float, default=0.0001): Stricter threshold leads to
      better convergence but longer runtime.
    - `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`,
      UMAP 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’.
    <br/>
    Hints:
    - Increasing `nnd_graph_degree` and `nnd_max_iterations` may improve accuracy.
    - 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 `knn_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:**
  **embedding_**

### Methods

| [`fit`](#cuml.manifold.UMAP.fit)(self, X[, y, knn_graph])           | Fit X into an embedded space.                                                                                 |
|-----------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------|
| [`fit_transform`](#cuml.manifold.UMAP.fit_transform)(self, X[, y, knn_graph]) | Fit X into an embedded space and return that transformed output.                                              |
| [`inverse_transform`](#cuml.manifold.UMAP.inverse_transform)(self, X)             | Transform X in the existing embedded space back into the input data space and return that transformed output. |
| [`transform`](#cuml.manifold.UMAP.transform)(self, X)                     | Transform X into the existing embedded space and return that transformed output.                              |

### Notes

This module is heavily based on Leland McInnes’ reference UMAP package.
However, there are a number of differences and features that are not yet
implemented in `cuml.umap`:

* Using a pre-computed pairwise distance matrix (under consideration
  for future releases)
* Manual initialization of initial embedding positions

In addition to these missing features, you should expect to see
the final embeddings differing between cuml.umap and the reference
UMAP.

### References

<!-- !! 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, , knn_graph=None) → 'UMAP'[[source]](https://github.com/NVIDIA/cuml/blob/93418baf5/python/cuml/cuml/manifold/umap/umap.pyx#L1213)

Fit X into an embedded space.

* **Parameters:**
  **X**
  : Dense or sparse matrix with dtype float32 or float64.
    Acceptable dense 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.

  **h: tuple[array, array], sparse-matrix, array, optional**
  : This feature allows the precomputation of the KNN outside of UMAP.
    <br/>
    This may take any of the valid forms accepted by the
    `precomputed_knn` parameter to `UMAP`, and takes precedence
    over it. See the `UMAP` docstring on `precomputed_knn` for more
    information.

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

#### fit_transform(self, X, y=None, , knn_graph=None)[[source]](https://github.com/NVIDIA/cuml/blob/93418baf5/python/cuml/cuml/manifold/umap/umap.pyx#L1429)

Fit X into an embedded space and return that transformed
output.

There is a subtle difference between calling fit_transform(X)
and calling fit().transform(). Calling fit_transform(X) will
train the embeddings on X and return the embeddings. Calling
fit(X).transform(X) will train the embeddings on X and then
run a second optimization.

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

  **h**
  : This feature allows the precomputation of the KNN outside of UMAP.
    <br/>
    This may take any of the valid forms accepted by the
    `precomputed_knn` parameter to `UMAP`, and takes precedence
    over it. See the `UMAP` docstring on `precomputed_knn` for more
    information.

  **Returns**

  **——-**

  **X_new**
  : Embedding of the data in low-dimensional space.
    <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_feature_names_out(input_features=None)

Get output feature names for transformation.

The feature names out will prefixed by the lowercased class name. For
example, if the transformer outputs 3 features, then the feature names
out are: `["class_name0", "class_name1", "class_name2"]`.

* **Parameters:**
  **input_features**
  : Only used to validate feature names with the names seen in [`fit`](#cuml.manifold.UMAP.fit).
* **Returns:**
  **feature_names_out**
  : Transformed feature names.

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

#### inverse_transform(self, X)[[source]](https://github.com/NVIDIA/cuml/blob/93418baf5/python/cuml/cuml/manifold/umap/umap.pyx#L1587)

Transform X in the existing embedded space back into the input
data space and return that transformed output.

* **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.
* **Returns:**
  **X_new**
  : Generated data points in data space.
    <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 !! -->

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

#### transform(self, X)[[source]](https://github.com/NVIDIA/cuml/blob/93418baf5/python/cuml/cuml/manifold/umap/umap.pyx#L1463)

Transform X into the existing embedded space and return that
transformed output.

Please refer to the reference UMAP implementation for information
on the differences between fit_transform() and running fit()
transform().

Specifically, the transform() function is stochastic:
[https://github.com/lmcinnes/umap/issues/158](https://github.com/lmcinnes/umap/issues/158)

* **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.
* **Returns:**
  **X_new**
  : Embedding of the data in low-dimensional space.
    <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 !! -->