---

name: aligned-composition description: "Covers AlignedUMAP for related slices and fitted UMAP model composition with intersection, union, or contrast operators." disable-model-invocation: true metadata: disco-role: operating license: BSD 3-Clause

Aligned UMAP and Model Composition

Use this sub-skill when embeddings must stay comparable across related slices, time periods, batches, or feature views, or when a task asks to combine fitted UMAP models with *, +, or -.

Route Here For

• umap.AlignedUMAP on a list of related datasets.
• Relation dictionaries that map sample indices from one slice to the next.
• Online updates with a new slice and relation map.
• Per-slice parameter lists for n_neighbors or other AlignedUMAP parameters.
• Choosing alignment_regularisation or alignment_window_size.
• Combining two fitted UMAP models over the same samples using intersection (*), union (+), or contrast (-).

Route Elsewhere

• Single-dataset fit/transform/sparse/precomputed workflows: read core-embedding.
• Supervised labels or densMAP: read supervised-density.
• Plotting aligned embeddings: read plotting-diagnostics.
• Parametric neural embeddings are out of scope for this sub-skill.

Quick AlignedUMAP Pattern

import umap

# X_slices is a list such as [X_t0, X_t1, X_t2].
# relations[t] must map row indices in X_slices[t] to row indices in
# X_slices[t + 1]. Keep those row positions stable after filtering/sorting.
relations = [
    {0: 0, 1: 2, 2: 3},
    {0: 1, 2: 2, 3: 4},
]
model = umap.AlignedUMAP(
    n_neighbors=15,
    alignment_regularisation=0.01,
    alignment_window_size=3,
    random_state=42,
).fit(X_slices, relations=relations)
embeddings = model.embeddings_

Run scripts/aligned_composition_smoke.py for a tiny no-network aligned/composition check:

python scripts/aligned_composition_smoke.py --composition --json

For online updates, remember that update uses the same adjacent-slice row index convention as fit: map rows in the previously fitted slice to rows in the new slice you are adding.

Quick Composition Pattern

left_mapper = umap.UMAP(random_state=42).fit(left_view)
right_mapper = umap.UMAP(random_state=42).fit(right_view)
intersection = left_mapper * right_mapper
union = left_mapper + right_mapper
contrast = left_mapper - right_mapper

Only compose models trained on the same sample order and one-to-one sample correspondence. Do not use these operators to combine unrelated datasets.

Decision Points

1. Slices versus views: use AlignedUMAP for ordered related slices; use composition operators for different views of the same rows.
2. Relations: relation dictionaries map adjacent slices. Missing keys can represent absent correspondence, but accidental missing keys cause drift.
3. Alignment strength: stronger regularisation makes slices more comparable but can suppress real temporal or batch-specific change.
4. Window size: larger windows propagate alignment across more neighbouring slices; validate if distant slices should influence each other.
5. Contrast is directional: A - B is not the same as B - A.
6. Update direction: update uses the same forward slice-to-slice relation convention as fit; build the map from the existing last slice to the new slice.

References

• Read workflows for aligned slices, updates, per-slice parameters, and model composition recipes.
• Read API reference for signatures, relation schema, and operator semantics.
• Read troubleshooting for relation and row-correspondence failures.