Skip to main content

Inputs and outputs

Which columns polars-umap accepts, and how to work with the embedding it returns.

Input

polars-umap accepts two kinds of input.

One vector per row

A single Array or List column, where each row holds one vector. This is the natural shape for embeddings from a language or image model.

import polars_umap as pu

df = pl.DataFrame({"embedding": vectors})  # Array(Float32, 8)
df.select(pl.col("embedding").umap.fit_transform(random_state=0)).head(3)
shape: (3, 1)
embedding
array[f32, 2]
[-3.434997, -0.106764]
[3.194072, 2.138245]
[1.460992, -1.859551]

A List column works too, as long as every row has the same length:

as_list = df.with_columns(pl.col("embedding").arr.to_list())
as_list.select(pl.col("embedding").umap.fit_transform(random_state=0)).head(3)
shape: (3, 1)
embedding
array[f32, 2]
[-3.434997, -0.106764]
[3.194072, 2.138245]
[1.460992, -1.859551]

Lists of different lengths raise an error, because UMAP needs every vector to have the same dimensionality.

Several numeric columns

Pass several numeric columns to pu.umap() and they’re stacked into a feature matrix, like X in scikit-learn:

wide = pl.DataFrame(vectors, schema=[f"feature_{i}" for i in range(8)])
wide.select(pu.umap("feature_0", "feature_1", "feature_2", random_state=0)).head(3)
shape: (3, 1)
feature_0
array[f32, 2]
[3.229914, -2.633859]
[-2.465854, -2.471153]
[2.340761, -2.858644]

Selectors and regular expressions work too:

import polars.selectors as cs

wide.select(
    pu.umap(cs.starts_with("feature_"), random_state=0).alias("from_selector"),
    pu.umap(pl.col("^feature_.*$"), random_state=0).alias("from_regex"),
).head(3)
shape: (3, 2)
from_selectorfrom_regex
array[f32, 2]array[f32, 2]
[-3.434997, -0.106764][-3.434997, -0.106764]
[3.194072, 2.138245][3.194072, 2.138245]
[1.460992, -1.859551][1.460992, -1.859551]

Data types

Integer, float and boolean values are all converted to Float32, which is what the UMAP implementation uses internally. Float64 input gives the same result as Float32 input.

Output

Expressions return an Array(Float32, n_components) column with one point per input row, in the same order. The column is named after the first input column; use .alias() to rename it.

out = df.select(xyz=pl.col("embedding").umap.fit_transform(n_components=3, random_state=0))
out.schema
Schema([('xyz', Array(Float32, shape=(3,)))])

To get one column per component, use .arr.get(), .arr.to_struct() or the DataFrame helper:

out.select(
    pl.col("xyz").arr.get(0).alias("x"),
    pl.col("xyz").arr.get(1).alias("y"),
    pl.col("xyz").arr.get(2).alias("z"),
).head(3)
shape: (3, 3)
xyz
f32f32f32
-1.826774-0.3721372.518197
2.3343750.8314720.814163
0.087367-2.1654991.413459
df.umap.fit_transform("embedding", n_components=3, random_state=0).head(3)
shape: (3, 4)
embeddingumap_0umap_1umap_2
array[f32, 8]f32f32f32
[0.12573, -0.132105, … 0.947081]-1.826774-0.3721372.518197
[-0.703735, -1.265422, … -0.732267]2.3343750.8314720.814163
[-0.544259, -0.3163, … 0.35151]0.087367-2.1654991.413459

The helper takes output="array" to add a single Array column instead, name= to name that column, and prefix= to change the umap_ prefix of the component columns.

Small inputs

UMAP needs a few points to do anything meaningful. polars-umap handles tiny inputs gracefully, which matters when you run it per group:

  • 0 rows give an empty result;
  • 1 row is placed at the origin;
  • 2 rows are placed one unit apart;
  • otherwise, n_neighbors is reduced to the number of rows minus one when needed, as umap-learn does.