Datasets Beta
Datasets are how you assemble training and evaluation sets from your robotics data. Curate moments that matter, such as successful grasps or night-drive failures, into a versioned collection you can load into a training pipeline.
A dataset is a named, versioned collection of episodes. An episode is a time range over one or more recordings. Dataset versions are immutable, maintaining a record of the exact data used for training.
Datasets belong to a Project and live on the Datasets page. You can also create and manage datasets, their versions, and episodes via the API.
On the Datasets page, a search box on the left of the filter bar matches part of a dataset name, ignoring case. Press Cmd+F (Ctrl+F on Linux and Windows) to focus the search box. In a web browser, press it again while the box has focus to use the browser's find in page.
Episodes
An episode represents a complete set of actions for a task, commonly used for ML training.
Foxglove episodes reference a time span on recordings with optional metadata to track labels and custom info without duplicating the underlying data.
Episodes exist independently of any dataset. The Episodes page lists every episode in the Project. While visualizing recordings, the Episodes tab in the right sidebar lists the episodes on those recordings.
Search matches episodes by ID or by metadata key, so one query can pull a training set out of thousands of episodes. To find every towel-folding episode a labeler marked successful:
@episode.metadata.task == fold_towel and @episode.metadata.outcome == success
Select the matching episodes and use Add to dataset. See Search for the full query syntax.
To download a single episode, open it from the Episodes page and click Download. The download is one MCAP or ROS 1 bag file that merges the episode's recordings over its time range. In the dialog you can narrow the range or choose which topics to include. Recordings whose data has been deleted are left out, and Download is disabled when none of the episode's recordings have data left.
An episode stores a reference to its recordings and time range, not a copy of the data. If that data is deleted, the episode remains and keeps its reference to it, though the reference no longer resolves to anything you can visualize or download.
Episodes tab
The Episodes tab in the visualization right sidebar lists the episodes on the data that you view, sorted by start time. An episode is listed when its recordings are exactly the recordings in the view and its time span overlaps the loaded time range, so an episode that also covers other recordings is not listed. The tab is available when you view recordings, a session, an episode, a device, or an event stored in Foxglove. A view of more than 50 recordings lists no episodes. In compare mode, the tab lists the episodes of each compared source, labeled with that source's letter.
Click an episode to seek to its start, or to the start of the loaded time range when the episode begins before it. Filter the list by episode ID, metadata key, or metadata value.
Creating a dataset
To make a new dataset, click Create dataset on the Datasets page and give it a name, plus an optional description. Names are case-insensitive and must be unique within a Project. Typing a new name in the Add to dataset dialog also creates a dataset.
Adding episodes
Add to dataset appears anywhere you can select data:
- The Search, Recordings, Sessions, Events, and Episodes pages, and their detail pages
- The data source menu and the event details panel in visualization
Each selected item becomes an episode. Items with no recordings or a zero-length time range are skipped.
Adding from visualization covers the current playback range, not the whole recording. Set the range to the span you want the episode to cover before you add it.
Adjusting an episode's time range
Edit episode on the dataset page opens the same range editor for the draft. Save new version saves a new version of the episode and switches the draft to it. Save as new episode creates an episode with the new range and replaces the original in the draft, so Review changes shows one addition and one removal. Either way, other datasets containing the episode remain unchanged. When the draft uses an older version of the episode, only Save as new episode is available.
Edit episode on the Episodes page or on an episode’s page opens a range editor. Save new version saves a new version of the same episode. Datasets keep using their existing episode versions. To create a separate episode without changing the original or its dataset memberships, open the menu next to the save button and select Save as new episode. Both editors remember your choice the next time you edit an episode. Version edits start from the latest episode version. When an episode page shows an older version, select Go to latest version before you edit.
If Edit episode is not available, Create episode from range on the Episodes page creates a separate episode without removing anything.
To change which episode version a dataset draft uses, select Change episode version from the episode’s actions menu.
Versions
Every dataset has exactly one draft version, created with the dataset and again after every commit. Adding episodes, removing episodes, and changing episode versions stage changes in the draft.
Open Review changes to see what the draft has staged. Commit saves it as a numbered version and records who committed it and when. Discard all changes resets the draft to the last committed version. A draft with no changes can't be committed.
A dataset version records the episodes it contains and which version of each episode it uses.
To view an earlier dataset version, select it from the version dropdown. Select Restore this version to make the draft use that version’s episodes and episode versions. This discards any pending draft changes. Commit the draft to save the restored contents as a dataset version.
Compare versions shows episodes added, removed, or updated between two dataset versions. An episode appears as Version updated when both contain the same episode ID but use different episode versions. For example, switching an episode from version 2 to version 3 appears as a version update.
Removing and deleting
Removing an episode from a dataset doesn't delete the episode. Deleting a dataset doesn't delete the episodes it held.
An episode can be deleted only when no existing dataset holds it in any version.
Exporting a dataset for training
Download in the dataset actions menu packages a committed version as a zip archive.
Drafts can't be downloaded. Commit the draft first.
In the dialog, choose the version to download and, optionally, the topics to include. With no topics selected, the download includes every topic.
The archive holds one MCAP file per episode plus a manifest:
night-drive-failures-v3/
episode_0000_ep_7Ht2kQmN4pWx.mcap
episode_0001_ep_9Kp4mRtY2wQz.mcap
manifest.json
manifest.json records the dataset, the version and its commit time, the topic selection, and one entry per episode with its time range, metadata, byte size, and a status of downloaded, skipped, or failed. Episodes whose recordings are gone are skipped. An episode that fails to stream is recorded with the reason, and the rest of the download continues.