umap()
Embed rows into a low-dimensional space with UMAP.
Usage
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
ArrayorListcolumn 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 toFloat32. 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_distthis determines how clustered the embedding is. metric: Metric = "euclidean"-
Distance metric of the input space.
n_epochs: int | None = None-
Number of optimization epochs.
Nonepicks 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 onen_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_distandspreadwhen not given. b: float | None = None-
Parameters of the low-dimensional similarity curve. Derived from
min_distandspreadwhen 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.
Noneuses a shared pool sized byRAYON_NUM_THREADS,POLARS_MAX_THREADSor 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
>>> 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