Training Movies¶

Watch your embedding space evolve during training. Featrix captures 3D projections at each epoch, letting you visualize how the model learns to organize your data.

What Training Movies Show¶

During training, the model learns to position similar records close together in embedding space. Training movies let you:

Watch clusters form as the model discovers structure in your data
Track individual records as they move through the space
See categories separate as the model learns distinctions
Identify training issues like collapse (everything bunching together) or instability

Viewing in Jupyter Notebooks¶

The easiest way to view training movies is in a Jupyter notebook:

from featrixsphere.api import FeatrixSphere

featrix = FeatrixSphere()
notebook = featrix.notebook()

# Train a model
fm = featrix.create_foundational_model(
    name="customer_model",
    data_file="customers.csv"
)
fm.wait_for_training()

# View the training movie
movie = notebook.training_movie(fm, notebook_mode=True)
# Widget displays automatically in Jupyter

3D Embedding Space Visualization¶

View the final embedding space interactively:

fig = notebook.embedding_space_3d(fm, interactive=True)
fig.show()

API Access¶

For custom visualizations or integration into your own tools, access the raw projection data via the API.

Get Epoch Projections¶

Retrieve 3D coordinates for each training epoch:

# Get all epochs
projections = featrix.get_json(f"/session/{fm.id}/epoch_projections")

# Get just the last epoch (efficient for thumbnails)
last_epoch = featrix.get_json(f"/session/{fm.id}/epoch_projections?epoch=last")

# Get a specific epoch
epoch_10 = featrix.get_json(f"/session/{fm.id}/epoch_projections?epoch=10")

# Paginate through epochs
first_five = featrix.get_json(f"/session/{fm.id}/epoch_projections?start_epoch=1&limit=5")

# Get metadata only (epoch count, etc.)
metadata = featrix.get_json(f"/session/{fm.id}/epoch_projections?metadata_only=true")

Projection Data Structure¶

Each epoch's projection contains:

{
    "coords": [
        {
            "x": -0.123,
            "y": 0.456,
            "z": 0.789,
            "__featrix_row_id": 0,
            "set_columns": {"category": "electronics"},
            "scalar_columns": {"price": 299.99},
            "string_columns": {"description": "wireless headphones"}
        },
        # ... more records
    ],
    "epoch": 5,
    "timestamp": "2025-01-03T18:30:45.123456",
    "sample_size": 500,
    "total_records": 50000
}

Point Tracking Across Epochs¶

The same 500 sample points are tracked across all epochs. This means you can:

Draw paths showing how each point moved during training
Color points by category and watch clusters form
Measure convergence by tracking movement between epochs

# Build point trajectories
projections = featrix.get_json(f"/session/{fm.id}/epoch_projections")

point_paths = {}
for epoch_data in projections["epochs"]:
    for point in epoch_data["coords"]:
        row_id = point["__featrix_row_id"]
        if row_id not in point_paths:
            point_paths[row_id] = []
        point_paths[row_id].append({
            "epoch": epoch_data["epoch"],
            "x": point["x"],
            "y": point["y"],
            "z": point["z"]
        })

# Now point_paths[row_id] contains the full trajectory for each tracked point

What to Look For¶

Healthy Training¶

Points spread out initially, then gradually organize into clusters
Similar items (same category, similar values) move toward each other
Movement decreases in later epochs as the model converges

Warning Signs¶

Pattern	What It Means
All points collapse to center	Embedding collapse—model isn't learning distinctions
Points oscillate wildly	Training instability—learning rate may be too high
No movement at all	Dead network—gradients aren't flowing
Clusters form then dissolve	Overfitting—model memorizing then forgetting

Performance Notes¶

Projections use only 500 sampled points for speed
Each epoch's projection takes 2-5 seconds to generate
Full projections with clustering are generated after training completes
Use epoch=last parameter when you only need the final state