This page takes you from a DataFrame of high-dimensional vectors to a 2D map of them. We’ll use the handwritten digits that ship with scikit-learn: 1,797 images of 8×8 pixels, so 64 numbers per image.
Load the data
import polars as pl
import polars_umap as pu # registers the `umap` namespace
from sklearn.datasets import load_digits
X, y = load_digits(return_X_y=True)
digits = pl.DataFrame({"pixels": X, "digit": y})
digits.head()
shape: (5, 2)| pixels | digit |
|---|
| array[f64, 64] | i64 |
| [0.0, 0.0, … 0.0] | 0 |
| [0.0, 0.0, … 0.0] | 1 |
| [0.0, 0.0, … 0.0] | 2 |
| [0.0, 0.0, … 0.0] | 3 |
| [0.0, 0.0, … 0.0] | 4 |
The 2D NumPy array becomes an Array(Float64, 64) column: one fixed-length vector per row. This is how embeddings usually live in Polars.
Run UMAP
Call .umap.fit_transform() on the column:
digits = digits.with_columns(
xy=pl.col("pixels").umap.fit_transform(random_state=42),
)
digits.head()
shape: (5, 3)| pixels | digit | xy |
|---|
| array[f64, 64] | i64 | array[f32, 2] |
| [0.0, 0.0, … 0.0] | 0 | [0.364655, 8.250998] |
| [0.0, 0.0, … 0.0] | 1 | [-4.066062, -4.919734] |
| [0.0, 0.0, … 0.0] | 2 | [0.743235, -1.350548] |
| [0.0, 0.0, … 0.0] | 3 | [6.934849, 1.243669] |
| [0.0, 0.0, … 0.0] | 4 | [-8.66126, -0.087729] |
The result is an Array(Float32, 2) column with one 2D point per row. random_state makes the result reproducible: run it again and you get exactly the same numbers.
If you’d rather have one column per dimension, use the DataFrame helper:
digits = digits.umap.fit_transform("pixels", random_state=42)
digits.select("digit", "umap_0", "umap_1").head()
shape: (5, 3)| digit | umap_0 | umap_1 |
|---|
| i64 | f32 | f32 |
| 0 | 0.364655 | 8.250998 |
| 1 | -4.066062 | -4.919734 |
| 2 | 0.743235 | -1.350548 |
| 3 | 6.934849 | 1.243669 |
| 4 | -8.66126 | -0.087729 |
Plot it
Show the plotting code
import altair as alt
centers = digits.group_by("digit").agg(pl.col("umap_0", "umap_1").median())
points = (
alt.Chart(digits.select("digit", "umap_0", "umap_1"))
.mark_circle(size=12, opacity=0.5, color="#8d8b86")
.encode(
x=alt.X("umap_0", axis=None),
y=alt.Y("umap_1", axis=None),
tooltip=[alt.Tooltip("digit:N", title="Digit")],
)
)
labels = (
alt.Chart(centers)
.mark_text(fontSize=16, fontWeight="bold", color="#5f5d58")
.encode(x="umap_0", y="umap_1", text="digit:N")
)
(points + labels).properties(width="container", height=440).configure_view(stroke=None)
UMAP has never seen the labels, yet each digit forms its own cluster. Digits that are easy to confuse, such as 1 and 7, or 3, 5 and 8, end up closer together.