Skip to main content

umap()

Embed rows into a low-dimensional space with UMAP.

Usage

Source

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

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