Using Dataset Tools

This guide covers the dataset tools utilities available in LeRobot for modifying and editing existing datasets.

Overview

LeRobot provides several utilities for manipulating datasets:

1. Delete Episodes - Remove specific episodes from a dataset
2. Split Dataset - Divide a dataset into multiple smaller datasets
3. Merge Datasets - Combine multiple datasets into one. The datasets must have identical features, and episodes are concatenated in the order specified in repo_ids
4. Add Features - Add new features to a dataset
5. Remove Features - Remove features from a dataset
6. Convert to Video - Convert image-based datasets to video format for efficient storage

The core implementation is in lerobot.datasets.dataset_tools. An example script detailing how to use the tools API is available in examples/dataset/use_dataset_tools.py.

Command-Line Tool: lerobot-edit-dataset

lerobot-edit-dataset is a command-line script for editing datasets. It can be used to delete episodes, split datasets, merge datasets, add features, remove features, and convert image datasets to video format.

Run lerobot-edit-dataset --help for more information on the configuration of each operation.

Usage Examples

Delete Episodes

Remove specific episodes from a dataset. This is useful for filtering out undesired data.

# Delete episodes 0, 2, and 5 (modifies original dataset)
lerobot-edit-dataset \
    --repo_id lerobot/pusht \
    --operation.type delete_episodes \
    --operation.episode_indices "[0, 2, 5]"

# Delete episodes and save to a new dataset (preserves original dataset)
lerobot-edit-dataset \
    --repo_id lerobot/pusht \
    --new_repo_id lerobot/pusht_after_deletion \
    --operation.type delete_episodes \
    --operation.episode_indices "[0, 2, 5]"

Split Dataset

Divide a dataset into multiple subsets.

# Split by fractions (e.g. 80% train, 20% test, 20% val)
lerobot-edit-dataset \
    --repo_id lerobot/pusht \
    --operation.type split \
    --operation.splits '{"train": 0.8, "test": 0.2, "val": 0.2}'

# Split by specific episode indices
lerobot-edit-dataset \
    --repo_id lerobot/pusht \
    --operation.type split \
    --operation.splits '{"task1": [0, 1, 2, 3], "task2": [4, 5]}'

There are no constraints on the split names, they can be determined by the user. Resulting datasets are saved under the repo id with the split name appended, e.g. lerobot/pusht_train, lerobot/pusht_task1, lerobot/pusht_task2.

Merge Datasets

Combine multiple datasets into a single dataset.

# Merge train and validation splits back into one dataset
lerobot-edit-dataset \
    --repo_id lerobot/pusht_merged \
    --operation.type merge \
    --operation.repo_ids "['lerobot/pusht_train', 'lerobot/pusht_val']"

Remove Features

Remove features from a dataset.

# Remove a camera feature
lerobot-edit-dataset \
    --repo_id lerobot/pusht \
    --operation.type remove_feature \
    --operation.feature_names "['observation.images.top']"

Convert to Video

Convert an image-based dataset to video format, creating a new LeRobotDataset where images are stored as videos. This is useful for reducing storage requirements and improving data loading performance. The new dataset will have the exact same structure as the original, but with images encoded as MP4 videos in the proper LeRobot format.

# Local-only: Save to a custom output directory (no hub push)
lerobot-edit-dataset \
    --repo_id lerobot/pusht_image \
    --operation.type convert_to_video \
    --operation.output_dir /path/to/output/pusht_video

# Save with new repo_id (local storage)
lerobot-edit-dataset \
    --repo_id lerobot/pusht_image \
    --new_repo_id lerobot/pusht_video \
    --operation.type convert_to_video

# Convert and push to Hugging Face Hub
lerobot-edit-dataset \
    --repo_id lerobot/pusht_image \
    --new_repo_id lerobot/pusht_video \
    --operation.type convert_to_video \
    --push_to_hub true

# Convert with custom video codec and quality settings
lerobot-edit-dataset \
    --repo_id lerobot/pusht_image \
    --operation.type convert_to_video \
    --operation.output_dir outputs/pusht_video \
    --operation.vcodec libsvtav1 \
    --operation.pix_fmt yuv420p \
    --operation.g 2 \
    --operation.crf 30

# Convert only specific episodes
lerobot-edit-dataset \
    --repo_id lerobot/pusht_image \
    --operation.type convert_to_video \
    --operation.output_dir outputs/pusht_video \
    --operation.episode_indices "[0, 1, 2, 5, 10]"

# Convert with multiple workers for parallel processing
lerobot-edit-dataset \
    --repo_id lerobot/pusht_image \
    --operation.type convert_to_video \
    --operation.output_dir outputs/pusht_video \
    --operation.num_workers 8

Parameters:

• output_dir: Custom output directory (optional - by default uses new_repo_id or {repo_id}_video)
• vcodec: Video codec to use - options: h264, hevc, libsvtav1 (default: libsvtav1)
• pix_fmt: Pixel format - options: yuv420p, yuv444p (default: yuv420p)
• g: Group of pictures (GOP) size - lower values give better quality but larger files (default: 2)
• crf: Constant rate factor - lower values give better quality but larger files, 0 is lossless (default: 30)
• fast_decode: Fast decode tuning option (default: 0)
• episode_indices: List of specific episodes to convert (default: all episodes)
• num_workers: Number of parallel workers for processing (default: 4)

Note: The resulting dataset will be a proper LeRobotDataset with all cameras encoded as videos in the videos/ directory, with parquet files containing only metadata (no raw image data). All episodes, stats, and tasks are preserved.

Push to Hub

Add the --push_to_hub true flag to any command to automatically upload the resulting dataset to the Hugging Face Hub:

lerobot-edit-dataset \
    --repo_id lerobot/pusht \
    --new_repo_id lerobot/pusht_after_deletion \
    --operation.type delete_episodes \
    --operation.episode_indices "[0, 2, 5]" \
    --push_to_hub true

There is also a tool for adding features to a dataset that is not yet covered in lerobot-edit-dataset.