Track API

The Track API provides efficient time-series data tracking for robotics, reinforcement learning, and any sequential experiments.

Overview

Tracks are perfect for:

Robotics: Robot positions, joint angles, sensor readings
Reinforcement Learning: Agent trajectories, rewards, states
Simulations: Physics parameters over time
Sequential Data: Any data that changes over time

Basic Usage

python

from ml_dash import Experiment

with Experiment("robotics/training").run as experiment:
    for step in range(1000):
        # Append data to a track
        experiment.tracks("robot/position").append(
            step=step,
            x=position[0],
            y=position[1],
            z=position[2]
        )

Timestamp-Based Tracking

Tracks support three timestamp modes:

1. Auto-Generated Timestamps (Recommended)

When _ts is not provided, timestamps are automatically generated:

python

with Experiment("my-project/exp").run as experiment:
    for i in range(100):
        # Auto-generate unique timestamps
        experiment.tracks("sensors/temperature").append(value=temperature)
        experiment.tracks("sensors/pressure").append(value=pressure)

2. Explicit Timestamps

Provide explicit timestamps when you need precise control:

python

import time

with Experiment("my-project/exp").run as experiment:
    for i in range(100):
        timestamp = time.time()

        # Track with explicit timestamp
        experiment.tracks("sensors/temperature").append(value=temperature, _ts=timestamp)

        # Track with same timestamp (entries are merged)
        experiment.tracks("sensors/pressure").append(value=pressure, _ts=timestamp)

3. Timestamp Inheritance with `_ts=-1`

Use _ts=-1 to inherit the last timestamp from the previous tracks.append() or metrics.log() call in the same thread. This is perfect for synchronizing multi-modal data:

python

with Experiment("robotics/multi-modal").run as experiment:
    for step in range(1000):
        # First append - auto-generates timestamp
        experiment.tracks("robot/pose").append(position=[1.0, 2.0, 3.0])

        # Following appends - inherit the same timestamp
        experiment.tracks("camera/left").append(width=640, height=480, _ts=-1)
        experiment.tracks("camera/right").append(width=640, height=480, _ts=-1)
        experiment.tracks("robot/velocity").append(linear=[0.1, 0.0, 0.0], _ts=-1)
        experiment.tracks("sensors/lidar").append(ranges=[1.5, 2.0, 2.5], _ts=-1)

        # All 5 tracks now share the exact same timestamp!

_ts=-1 also inherits across metrics and tracks — they share the same last timestamp per thread:

python

# Set timestamp via track, inherit in metric
experiment.tracks("robot/pose").append(position=[1.0, 2.0, 3.0], _ts=100.0)
experiment.metrics("train").log(loss=0.5, _ts=-1)   # inherits 100.0

# Set timestamp via metric, inherit in track
experiment.metrics("train").log(loss=0.5)            # auto _ts, sets _last_timestamp
experiment.tracks("robot/pose").append(x=1.0, _ts=-1)  # inherits it

Benefits of _ts=-1:

Cleaner code - no need to manually pass timestamps around
Less error-prone - can't accidentally use wrong timestamp
Perfect for robotics/ML multi-modal data (poses, images, sensors at same instant)
Works across ALL tracks and metrics globally (per thread)

Multiple Tracks

Track different aspects of your experiment:

python

with Experiment("robotics/walker").run as experiment:
    for step in range(1000):
        # Robot position
        experiment.tracks("robot/position").append(
            step=step,
            x=pos[0],
            y=pos[1],
            z=pos[2]
        )

        # Joint angles
        experiment.tracks("robot/joints").append(
            step=step,
            joint1=angles[0],
            joint2=angles[1],
            joint3=angles[2]
        )

        # Control signals
        experiment.tracks("robot/control").append(
            step=step,
            motor1=ctrl[0],
            motor2=ctrl[1]
        )

        # Sensor readings
        experiment.tracks("robot/sensors").append(
            step=step,
            imu_x=imu[0],
            imu_y=imu[1],
            imu_z=imu[2],
            force=force_sensor
        )

Numpy Array Serialization

Tracks automatically serialize numpy arrays:

python

import numpy as np

with Experiment("rl/training").run as experiment:
    for episode in range(100):
        state = env.reset()  # numpy array

        # Numpy arrays are automatically converted to lists
        experiment.tracks("agent/states").append(
            episode=episode,
            state=state,  # numpy array - auto-serialized!
            reward=0.0
        )

MuJoCo Example

Perfect for tracking robot simulations:

python

import mujoco
import numpy as np

with Experiment("robotics/mujoco-sim").run as experiment:
    model = mujoco.MjModel.from_xml_string(xml_content)
    data = mujoco.MjData(model)
    renderer = mujoco.Renderer(model, height=480, width=640)

    for i in range(1000):
        # Apply control
        data.ctrl[0] = 4.0 * np.sin(i * 0.03)
        data.ctrl[1] = 2.5 * np.sin(i * 0.05)

        # Step simulation
        mujoco.mj_step(model, data)

        if i % 4 == 0:
            # Get end effector position
            ee_pos = data.site_xpos[model.site('end_effector').id].copy()

            # Track position
            experiment.tracks("robot/position").append(
                step=i,
                x=ee_pos[0],
                y=ee_pos[1],
                z=ee_pos[2]
            )

            # Track control
            experiment.tracks("robot/control").append(
                step=i,
                ctrl_1=float(data.ctrl[0]),
                ctrl_2=float(data.ctrl[1])
            )

            # Save frame aligned with track
            renderer.update_scene(data)
            pixels = renderer.render()
            experiment.files("frames").save_image(
                pixels,
                to=f"frame_{i:05d}.jpg"
            )

Aligning Frames with Tracks

Use consistent step indices to align frames with track data:

python

with Experiment("vision/tracking").run as experiment:
    for step in range(1000):
        # Track data
        experiment.tracks("agent/position").append(
            step=step,
            x=x,
            y=y
        )

        # Save frame with same step index
        experiment.files("frames").save_image(
            frame,
            to=f"frame_{step:05d}.jpg"
        )

        # Now frames and tracks are aligned by step index!

Reinforcement Learning Example

python

import gymnasium as gym

with Experiment("rl/cartpole").run as experiment:
    env = gym.make("CartPole-v1")

    for episode in range(100):
        state, info = env.reset()
        done = False
        total_reward = 0
        step = 0

        while not done:
            action = agent.act(state)
            next_state, reward, terminated, truncated, info = env.step(action)
            done = terminated or truncated

            # Track episode trajectory
            experiment.tracks("agent/trajectory").append(
                episode=episode,
                step=step,
                state=state.tolist(),  # numpy to list
                action=int(action),
                reward=float(reward),
                next_state=next_state.tolist()
            )

            state = next_state
            total_reward += reward
            step += 1

        # Track episode summary
        experiment.tracks("agent/episodes").append(
            episode=episode,
            total_reward=total_reward,
            steps=step
        )

Buffering and Performance

Tracks use the background buffering system:

python

with Experiment("high-freq/tracking").run as experiment:
    # All track appends are non-blocking
    for i in range(100000):
        experiment.tracks("sensor/data").append(
            step=i,
            value=sensor.read()
        )
        # Returns immediately! No blocking I/O

    # Automatically batched and uploaded in background

Configure track buffering:

bash

export ML_DASH_TRACK_BATCH_SIZE=100  # Batch 100 track entries
export ML_DASH_FLUSH_INTERVAL=5.0    # Flush every 5 seconds

Timestamp Merging

Entries with the same timestamp are automatically merged:

python

# Using explicit timestamps
experiment.tracks("multi-sensor").append(temperature=25.0, _ts=12345.67)
experiment.tracks("multi-sensor").append(pressure=1013.0, _ts=12345.67)

# Result: Single entry with both fields
# {"timestamp": 12345.67, "temperature": 25.0, "pressure": 1013.0}

You can also use _ts=-1 for merging:

python

# First append sets the timestamp
experiment.tracks("multi-sensor").append(temperature=25.0, _ts=12345.67)

# Following appends inherit and merge
experiment.tracks("multi-sensor").append(pressure=1013.0, _ts=-1)
experiment.tracks("multi-sensor").append(humidity=60.0, _ts=-1)

# Result: Single entry with all three fields at timestamp 12345.67

Best Practices

1. Use Consistent Indexing

python

# Good: Use step index consistently
for step in range(1000):
    experiment.tracks("data").append(step=step, value=v
    )
    experiment.files("frames").save_image(frame, to=f"frame_{step:05d}.jpg")

# Bad: Inconsistent indexing makes alignment hard
for i in range(1000):
    experiment.tracks("data").append(index=i * 2, value=v
    )
    experiment.files("frames").save_image(frame, to=f"frame_{i}.jpg")

2. Include Step/Episode in Data

python

# Good: Always include step/episode for easy querying
experiment.tracks("agent/rewards").append(
    episode=episode,
    step=step,
    reward=reward
)

# Less useful: Missing context
experiment.tracks("agent/rewards").append(
    reward=reward
)

3. Organize by Topic

python

# Good: Clear topic hierarchy
experiment.tracks("robot/joints/arm").append(**data)
experiment.tracks("robot/joints/leg").append(**data)
experiment.tracks("robot/sensors/imu").append(**data)

# Less clear: Flat structure
experiment.tracks("arm_data").append(**data)
experiment.tracks("leg_data").append(**data)

4. Zero-Pad Filenames for Alignment

python

# Good: Files sort correctly
experiment.files("frames").save_image(frame, to=f"frame_{i:05d}.jpg")
# frame_00000.jpg, frame_00001.jpg, frame_00002.jpg

# Bad: Sorting breaks
experiment.files("frames").save_image(frame, to=f"frame_{i}.jpg")
# frame_1.jpg, frame_10.jpg, frame_2.jpg  (wrong order!)

5. Store Frame References in Tracks

python

for step in range(1000):
    frame_filename = f"frame_{step:05d}.jpg"

    # Save frame
    experiment.files("frames").save_image(frame, to=frame_filename)

    # Reference frame in track
    experiment.tracks("robot/position").append(
        step=step,
        frame=frame_filename,  # Link to frame
        x=x,
        y=y,
        z=z
    )

Track Slicing and Iteration

The slice() method returns an iterable view of track data with timestamp-based indexing using floor matching.

Basic Iteration

python

with Experiment("robotics/analysis").run as experiment:
    # ... append data to tracks ...
    experiment.tracks.flush()

    # Create slice
    track_slice = experiment.tracks("robot/pose").slice()

    # Iterate through all entries
    for entry in track_slice:
        timestamp = entry["timestamp"]
        position = entry["position"]
        print(f"t={timestamp}: pos={position}")

Timestamp Range Filtering

python

# Slice specific time range
track_slice = experiment.tracks("robot/pose").slice(
    start_timestamp=10.0,
    end_timestamp=20.0
)

# Iterate through entries in range [10.0, 20.0]
for entry in track_slice:
    process(entry)

Floor-Match Timestamp Queries

The slice object supports findByTime() with floor matching: returns the entry with the largest timestamp ≤ queried timestamp.

python

# Create slice
track_slice = experiment.tracks("robot/pose").slice()

# If timestamps are [1.0, 3.0, 5.0, 7.0, 9.0]:

# Single timestamp queries
entry = track_slice.findByTime(5.5)  # Returns entry at timestamp 5.0 (floor match)
entry = track_slice.findByTime(5.0)  # Returns entry at timestamp 5.0 (exact match)
entry = track_slice.findByTime(6.9)  # Returns entry at timestamp 5.0 (floor match)
entry = track_slice.findByTime(7.0)  # Returns entry at timestamp 7.0 (exact match)

# Batch queries with list of timestamps
entries = track_slice.findByTime([1.0, 3.5, 7.0])  # Returns list of 3 entries
# entries[0] -> timestamp 1.0
# entries[1] -> timestamp 3.0 (floor match for 3.5)
# entries[2] -> timestamp 7.0

# Query before first timestamp raises ml_dash.StorageError
# track_slice.findByTime(0.5)  # StorageError: No entry found with timestamp <= 0.5

# Query after last timestamp returns last entry
entry = track_slice.findByTime(100.0)  # Returns entry at timestamp 9.0

Practical Example: Robot Trajectory Analysis

python

with Experiment("robotics/analysis").run as experiment:
    # ... data already logged ...

    # Analyze trajectory in specific time window
    trajectory = experiment.tracks("robot/pose").slice(0.0, 30.0)

    # Iterate through trajectory
    positions = []
    for entry in trajectory:
        positions.append(entry["position"])

    # Get robot state at specific times (single queries)
    state_at_5s = trajectory.findByTime(5.0)
    state_at_10s = trajectory.findByTime(10.0)
    state_at_15_5s = trajectory.findByTime(15.5)  # Floor match to closest ≤ 15.5

    # Or batch query multiple times at once
    states = trajectory.findByTime([5.0, 10.0, 15.5, 20.0, 25.0])
    for state in states:
        print(f"t={state['timestamp']}: pos={state['position']}")

    # Calculate metrics
    total_distance = calculate_distance(positions)
    print(f"Total distance: {total_distance:.2f}m")
    print(f"Number of waypoints: {len(trajectory)}")

Combine slicing with timestamp inheritance for synchronized queries:

python

with Experiment("robotics/sync").run as experiment:
    # Read multiple synchronized tracks
    pose_slice = experiment.tracks("robot/pose").slice(0.0, 10.0)
    camera_slice = experiment.tracks("camera/left").slice(0.0, 10.0)
    lidar_slice = experiment.tracks("sensors/lidar").slice(0.0, 10.0)

    # Query all tracks at same timestamp (floor match ensures sync)
    for pose_entry in pose_slice:
        t = pose_entry["timestamp"]
        camera_entry = camera_slice.findByTime(t)
        lidar_entry = lidar_slice.findByTime(t)

        # All entries at same timestamp (or floor-matched)
        process_multimodal(pose_entry, camera_entry, lidar_entry)

Slice Features

Iterator Protocol:

for entry in slice: ... - Iterate through entries
iter(slice) - Get iterator
Can iterate multiple times (data is cached)

Timestamp Queries:

slice.findByTime(timestamp) - Get entry by timestamp (floor match)
Optimized for sequential queries using internal index
Raises StorageError (from ml_dash) if query timestamp is before first entry

Length:

len(slice) - Get number of entries in slice

Representation:

repr(slice) - Shows topic, start, and end timestamps

API Reference

`experiment.tracks(topic: str) -> TrackBuilder`

Returns a TrackBuilder for the specified topic.

Parameters:

topic (str): Topic name (e.g., "robot/position")

Returns:

TrackBuilder instance

`TrackBuilder.append(**fields, _ts=None) -> TrackBuilder`

Append a data entry to the track. Keyword-only: each keyword becomes a field.

Parameters:

**fields: Data fields to track
_ts (float, optional): Timestamp. Omitted: generated from the current time. -1: reuse the previous timestamp. A number: use it as given.

Examples:

python

# With automatic timestamp
experiment.tracks("sensor/temp").append(value=25.0)

# With explicit timestamp
experiment.tracks("sensor/temp").append(value=25.0, _ts=time.time())

# Multiple fields
experiment.tracks("sensor/temp").append(
    step=100,
    value=25.0
)

# From a dict
experiment.tracks("sensor/temp").append(**{"value": 25.0})

`TrackBuilder.slice(start_timestamp: float = None, end_timestamp: float = None) -> TrackSlice`

Create an iterable slice of track data with timestamp-based indexing.

Parameters:

start_timestamp (float, optional): Start timestamp (inclusive)
end_timestamp (float, optional): End timestamp (inclusive)

Returns:

TrackSlice object supporting iteration and timestamp indexing

Examples:

python

# Full track slice
track_slice = experiment.tracks("robot/pose").slice()

# Time range slice
track_slice = experiment.tracks("robot/pose").slice(
    start_timestamp=0.0,
    end_timestamp=10.0
)

# Iterate
for entry in track_slice:
    print(entry["timestamp"], entry["position"])

# Floor-match timestamp query
entry = track_slice.findByTime(5.5)  # Returns entry with largest timestamp <= 5.5

# Get length
count = len(track_slice)

Comparison with Metrics

Feature	Tracks	Metrics
Use Case	Time-series data, trajectories	Training metrics, losses
Structure	Flexible dict per entry	Flat key-value pairs
Timestamp	`_ts` field, explicit or auto	`_ts` field, explicit or auto
`_ts=-1` inheritance	Yes, shared with metrics	Yes, shared with tracks
Merging	Timestamp-based merging	No merging
Best For	Robotics, RL, sensors	Training loss, accuracy

Example: Complete Robot Tracking

python

import mujoco
import numpy as np
from ml_dash import Experiment

with Experiment(
    prefix="robotics/complete-tracking",
    tags=["mujoco", "tracking"],
    dash_url="http://localhost:3000"
).run as experiment:
    experiment.log("Starting robot tracking experiment")

    # Initialize MuJoCo
    model = mujoco.MjModel.from_xml_string(xml_content)
    data = mujoco.MjData(model)
    renderer = mujoco.Renderer(model, height=480, width=640)

    steps = 1000
    record_interval = 4

    for i in range(steps):
        # Control
        ctrl_1 = 4.0 * np.sin(i * 0.03)
        ctrl_2 = 2.5 * np.sin(i * 0.05)
        data.ctrl[0] = ctrl_1
        data.ctrl[1] = ctrl_2

        # Simulate
        mujoco.mj_step(model, data)

        # Record
        if i % record_interval == 0:
            # Render
            renderer.update_scene(data)
            pixels = renderer.render()

            # Get state
            ee_pos = data.site_xpos[model.site('end_effector').id].copy()

            # Save frame
            experiment.files("robot/frames").save_image(
                pixels,
                to=f"frame_{i:05d}.jpg",
                quality=85
            )

            # Track position
            experiment.tracks("robot/position").append(
                step=i,
                x=float(ee_pos[0]),
                y=float(ee_pos[1]),
                z=float(ee_pos[2])
            )

            # Track control
            experiment.tracks("robot/control").append(
                step=i,
                ctrl_1=float(ctrl_1),
                ctrl_2=float(ctrl_2)
            )

            experiment.log(
                f"Step {i:3d}: pos=({ee_pos[0]:.4f}, "
                f"{ee_pos[1]:.4f}, {ee_pos[2]:.4f})"
            )

    experiment.log("Tracking complete!")

This creates a complete tracking dataset with aligned frames, positions, and control signals!

Track API

Overview

Basic Usage

Timestamp-Based Tracking

1. Auto-Generated Timestamps (Recommended)

2. Explicit Timestamps

3. Timestamp Inheritance with _ts=-1

Multiple Tracks

Numpy Array Serialization

MuJoCo Example

Aligning Frames with Tracks

Reinforcement Learning Example

Buffering and Performance

Timestamp Merging

Best Practices

1. Use Consistent Indexing

2. Include Step/Episode in Data

3. Organize by Topic

4. Zero-Pad Filenames for Alignment

5. Store Frame References in Tracks

Track Slicing and Iteration

Basic Iteration

Timestamp Range Filtering

Floor-Match Timestamp Queries

Practical Example: Robot Trajectory Analysis

Synchronizing Multi-Modal Data

Slice Features

API Reference

experiment.tracks(topic: str) -> TrackBuilder

TrackBuilder.append(**fields, _ts=None) -> TrackBuilder

TrackBuilder.slice(start_timestamp: float = None, end_timestamp: float = None) -> TrackSlice

Comparison with Metrics

Example: Complete Robot Tracking

3. Timestamp Inheritance with `_ts=-1`

`experiment.tracks(topic: str) -> TrackBuilder`

`TrackBuilder.append(**fields, _ts=None) -> TrackBuilder`

`TrackBuilder.slice(start_timestamp: float = None, end_timestamp: float = None) -> TrackSlice`