## umap()


Embed rows into a low-dimensional space with UMAP.


Usage

``` python
umap(
    *features,
    n_components=2,
    n_neighbors=15,
    min_dist=0.1,
    spread=1.0,
    metric="euclidean",
    n_epochs=None,
    learning_rate=1.0,
    init="auto",
    negative_sample_rate=5,
    repulsion_strength=1.0,
    local_connectivity=1.0,
    set_op_mix_ratio=1.0,
    a=None,
    b=None,
    random_state=None,
    optimizer=None,
    layout="0.6",
    disconnection_distance=None,
    null_policy="error",
    n_threads=None,
    gpu=False,
    verbose=False
)
```


UMAP (Uniform Manifold Approximation and Projection) is fitted on all rows the expression sees and returns their embedding, so the output has as many rows as the input. Use `.over(...)` to fit one UMAP per group.


## Parameters


`*features: IntoExpr | list[IntoExpr]`  
The input. Either a single `Array` or `List` column holding one vector per row (e.g. text embeddings), or one or more numeric columns, which are stacked into a feature matrix. Column names, expressions and selectors are accepted. Values are converted to `Float32`.

`n_components: int = ``2`  
Dimensionality of the embedding.

`n_neighbors: int = ``15`  
Size of the local neighborhood. Larger values preserve more global structure. Clamped to the number of rows minus one.

`min_dist: float = ``0.1`  
Minimum distance between embedded points. Smaller values give tighter clusters. Must be in `[0, spread]`.

`spread: float = ``1.0`  
Scale of the embedded points. Together with `min_dist` this determines how clustered the embedding is.

`metric: Metric = ``"euclidean"`  
Distance metric of the input space.

`n_epochs: int | None = None`  
Number of optimization epochs. `None` picks a default based on the size of the data (more epochs for smaller data).

`learning_rate: float = ``1.0`  
Initial learning rate of the layout optimization.

`init: InitLike = ``"auto"`  
How to initialize the embedding: `"auto"` (`"recursive"` for the 0.6 layout, `"spectral"` for 0.5), `"spectral"`, `"tswspectral"`, `"random"`, `"recursive"` or `"pca"`. You can also pass an expression, Series or 2D array with one `n_components`-dimensional starting point per row.

`negative_sample_rate: int = ``5`  
Number of negative samples per positive sample during optimization.

`repulsion_strength: float = ``1.0`  
Weight of the negative samples.

`local_connectivity: float = ``1.0`  
Number of nearest neighbors assumed to be connected locally.

`set_op_mix_ratio: float = ``1.0`  
Interpolation between fuzzy union (1.0) and fuzzy intersection (0.0) when symmetrizing the neighbor graph.

`a: float | None = None`  
Parameters of the low-dimensional similarity curve. Derived from `min_dist` and `spread` when not given.

`b: float | None = None`  
Parameters of the low-dimensional similarity curve. Derived from `min_dist` and `spread` when not given.

`random_state: int | None = None`  
Seed for the random number generators. With the default 0.6 layout, the same seed gives the same embedding.

`optimizer: Optimizer | None = None`  
`"adam"`, `"momentum"` or `"sgd"`. Defaults to `"adam"` for the 0.6 layout and `"sgd"` for the 0.5 layout.

`layout: Layout = ``"0.6"`  
`"0.6"` (default) reproduces the umap-learn 0.6 pipeline: recursive initialization and a deterministic Adam optimizer. `"0.5"` reproduces the classic umap-learn 0.5 pipeline: spectral initialization and Hogwild SGD, which is not bit-for-bit reproducible when multithreaded.

`disconnection_distance: float | None = None`  
Input distances at or above this value disconnect points in the neighbor graph. Defaults to 2 for cosine and correlation and infinity otherwise.

`null_policy: NullPolicy = ``"error"`  
`"error"` raises when a row is null or contains null, NaN or infinite values. `"ignore"` fits UMAP on the remaining rows and returns null for the invalid ones.

`n_threads: int | None = None`  
Number of threads. `None` uses a shared pool sized by `RAYON_NUM_THREADS`, `POLARS_MAX_THREADS` or the number of CPUs.

`gpu: bool = ``False`  
Use WebGPU (Metal, Vulkan or DirectX 12) for the nearest neighbor search and layout optimization. Falls back to the CPU when no GPU is available.

`verbose: bool = ``False`  
Print progress to standard error.


## Returns


`pl.Expr`  
An `Array(Float32, n_components)` expression. It is named after the first feature column.


## Examples

``` python
>>> import polars as pl
>>> import polars_umap as pu
>>> df = pl.DataFrame({"x": range(100), "y": [i % 7 for i in range(100)]})
>>> out = df.select(pu.umap("x", "y", random_state=0).alias("xy"))
>>> out.schema["xy"] == pl.Array(pl.Float32, 2)
```

True
