Skip to main content

Choosing parameters

What n_neighbors, min_dist, metric and the other parameters do, with examples.

polars-umap uses the same parameter names and defaults as umap-learn, so its guidance applies here too. The defaults are a good start; two parameters are worth exploring.

n_neighbors: local versus global

n_neighbors (default 15) is the size of the neighborhood UMAP considers for each point. Small values focus on fine local detail, at the cost of the big picture. Large values preserve more global structure, at the cost of detail.

With 5 neighbors, the digits break up into many small fragments. With 200, digits that look alike move together. Typical values are 5 to 50. polars-umap reduces n_neighbors to the number of rows minus one when needed.

min_dist: tight or spread out

min_dist (default 0.1) is the minimum distance between points in the embedding. Small values give tight, dense clusters, which helps for clustering. Large values spread the points out, which shows more of the structure within a cluster.

min_dist must lie between 0 and spread (default 1.0), which sets the overall scale.

metric

The distance metric of the input space. Use "cosine" for text and image embeddings, whose length usually carries no meaning, and "euclidean" (the default) for most other numeric data. Also available: "manhattan", "chebyshev", "minkowski", "correlation" and "hamming".

n_components

The number of output dimensions. Use 2 for plots. For clustering or as input to another model, values like 5 or 10 often preserve more structure.

The rest

Parameter When to change it
n_epochs Fewer is faster but less converged
init Pass an array to start from an earlier layout
layout "0.5" to match older umap-learn; see Reproducibility
learning_rate Fine-tuning the optimization; rarely needed
negative_sample_rate Fine-tuning the optimization; rarely needed
repulsion_strength Fine-tuning the optimization; rarely needed
local_connectivity How the neighbor graph is built; rarely needed
set_op_mix_ratio How the neighbor graph is built; rarely needed
a, b Override the curve from min_dist and spread
disconnection_distance Cut edges longer than this in the neighbor graph

See the reference for every parameter.