Choosing parameters
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.