Transformations

Transformations modify vectors to create derived layers.

Creating Transformations

  1. Select a layer in the Graph Editor

  2. In the Config Panel, find “Add Transformation”

  3. Enter an optional name

  4. Select the transformation type

  5. Click “Add Transformation”

This creates:

  • A new transformation node

  • A new derived layer with transformed vectors

Scaling

Multiplies vectors by per-axis scale factors.

Formula: v'[i] = scale_factors[i] * v[i]

Parameters:

  • Scale Factors - Per-dimension multipliers (can be linked or independent)

  • Link Axes - When enabled, all axes use the same scale factor

Use cases:

  • Normalizing magnitude across dimensions

  • Emphasizing or de-emphasizing certain features

  • Exploring how scale affects clustering patterns

Rotation

Rotates vectors in a 2D plane within the n-dimensional space.

Formula: Rotation matrix applied to two selected dimensions.

Parameters:

  • Angle - Rotation angle in degrees (-180° to 180°)

  • Rotation Plane - Which two dimensions to rotate (e.g., “dim_0 ↔ dim_1”)

Use cases:

  • Exploring rotational invariance of embeddings

  • Manually aligning projections for comparison

  • Understanding how rotation affects clustering structure

PCA Transformation

Applies Principal Component Analysis to transform vectors into the principal component coordinate system. This is useful for reducing dimensionality while preserving variance, or for decorrelating features.

Formula: v' = PCA(v) where each output axis is a principal component

Parameters:

  • Components - Number of principal components to keep (default: all)

  • Center - Whether to center the data (subtract mean) before PCA (default: true)

  • Whiten - Whether to normalize variance of each component (default: false)

Stored Information:

After applying the PCA transformation, the following information is computed and stored:

  • Explained Variance Ratio - How much variance each component captures

  • Components Matrix - The principal component directions (loadings)

  • Mean - The mean vector used for centering

Use cases:

  • Dimensionality reduction before visualization

  • Decorrelating features (whitening)

  • Understanding which original dimensions contribute to each component

  • Preprocessing data for downstream transformations

Custom Affine Transformation

Transforms vectors using a user-defined change of basis where the first two or three axes are custom directions (typically defined by barycenters), and the remaining axes are preserved from the standard basis.

Formula: v' = B_target^{-1} @ (v - center)

where B_target = [v1 | v2 | e_2 | e_3 | ... | e_{N-1}] (2D)

or B_target = [v1 | v2 | v3 | e_3 | e_4 | ... | e_{N-1}] (3D)

Parameters:

  • Axis 1 - First custom axis direction (from a named custom axis)

  • Axis 2 - Second custom axis direction (from a named custom axis)

  • Axis 3 - Third custom axis direction (optional, for 3D output)

  • Projection Mode - How to compute coordinates:

    • Oblique (default): Oblique coordinate projection onto the subspace spanned by the axes

    • Affine: Full change of basis transformation

  • Flip Axis 1/2/3 - Negate the direction of each axis

  • Center - Use mean (default) or a virtual point as origin

Projection Modes Explained:

The two projection modes give different results:

  1. Oblique Mode: Finds coefficients (α, β, [γ]) such that α*v1 + β*v2 [+ γ*v3] is the closest point to x in the subspace spanned by the custom axes. The remaining dimensions are copied unchanged from the input.

    Formula: [α, β, γ] = (V^T V)^{-1} V^T x where V = [v1 | v2 | v3]

  2. Affine Mode: Full change of basis where x = c1*v1 + c2*v2 + c3*v3 + c4*e_3 + ... The coefficients c1, c2, c3 are the exact decomposition, not a projection. The remaining dimensions are modified by the change of basis.

Why they differ - Example:

Consider a 3D example with: - v1 = [1, 0, 1] (45° between e_0 and e_2) - v2 = [0, 1, 0] = e_1

For a point x = [1, 0, 0]:

  • Oblique projection gives: [0.5, 0] (closest point in the v1-v2 plane)

  • Change of basis gives: [1, 0] (because x = 1*v1 + 0*v2 - 1*e_2)

The affine mode finds the exact coefficients needed to reconstruct x from the basis vectors, while oblique mode finds the best approximation in the 2D subspace.

Choosing a Mode:

  • Use Oblique when you want the Custom Axes view to match the transformation output

  • Use Affine when you need the mathematically exact change of basis

Use cases:

  • Aligning embeddings to semantically meaningful directions (e.g., “male→female”, “young→old”)

  • Interpreting embeddings in terms of user-defined concepts

  • Creating consistent coordinate systems across layers

3D Custom Affine:

To use three custom axes for a 3D change of basis:

  1. Create three custom axes (e.g., from class barycenters)

  2. Select the Custom Affine transformation

  3. Choose axes for Axis 1, Axis 2, and Axis 3

  4. Click Apply

When a third axis is specified, the transformation replaces the first three standard basis vectors with your custom axes, creating a 3D coordinate system aligned to your semantic directions.

Example - Iris with 3D Custom Affine:

  1. Create barycenters for setosa, versicolor, and virginica classes

  2. Define axes: setosa→versicolor, setosa→virginica, versicolor→virginica

  3. Apply Custom Affine with all three axes

  4. The derived layer’s first three dimensions now represent distances along these semantic directions

Configuring Transformations

After creating a transformation:

  1. Click the transformation node in the Graph Editor

  2. Adjust parameters using sliders or inputs

  3. Changes apply immediately to derived layers and projections

Chaining Transformations

To apply multiple transformations:

  1. Create the first transformation (Source → T1 → Derived1)

  2. Select the derived layer (Derived1)

  3. Add another transformation (Derived1 → T2 → Derived2)

Example chain:

Iris → Scaling (0.5) → Scaled → Rotation (45°) → Rotated
  ↓                       ↓                          ↓
PCA View              PCA View                   PCA View

Transformation Properties

Invertibility

All built-in transformations are invertible (can be reversed):

  • Scaling: divide by scale factor

  • Rotation: rotate by negative angle

  • PCA: apply inverse transformation (multiply by components matrix transpose)

Point Identity

Point IDs are preserved across transformations. This means:

  • You can track the same point through the pipeline

  • Selection works across transformed and source layers

  • Labels and metadata are preserved

Real-time Updates

When you modify transformation parameters:

  1. Derived layer vectors are recomputed

  2. All dependent projections are recomputed

  3. Views update immediately

Tips

  • Start simple: Use scaling to understand magnitude effects

  • Small rotations: Start with small angles to see gradual effects

  • Compare views: Create projections before and after transformation

  • Chain carefully: Each transformation adds to the pipeline