# Choosing parameters

polars-umap uses the same parameter names and defaults as [umap-learn](https://umap-learn.readthedocs.io/en/latest/parameters.html), 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.


<style>
  #altair-viz-a7071f6cf2fd44f789599c50650f9064.vega-embed {
    width: 100%;
    display: flex;
  }

  #altair-viz-a7071f6cf2fd44f789599c50650f9064.vega-embed details,
  #altair-viz-a7071f6cf2fd44f789599c50650f9064.vega-embed details summary {
    position: relative;
  }
</style>


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.


<style>
  #altair-viz-c718943928044434bb8b7723bae5ee92.vega-embed {
    width: 100%;
    display: flex;
  }

  #altair-viz-c718943928044434bb8b7723bae5ee92.vega-embed details,
  #altair-viz-c718943928044434bb8b7723bae5ee92.vega-embed details summary {
    position: relative;
  }
</style>


`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](reproducibility.md) |
| `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](../reference/umap.md) for every parameter.
