opentau.datasets.standard_data_format_mapping

Standard data format mapping for dataset feature names and loss types.

This module provides mappings between standard feature names used internally by OpenTau and dataset-specific feature names used in various robot learning and vision-language datasets. It also maps datasets to their appropriate loss types for training.

The standard format uses canonical names like “camera0”, “camera1”, “state”, “actions”, “prompt”, and “response”, while different datasets may use various naming conventions (e.g., “observation.images.image”, “observation.state”, “action”, “task”, etc.). These mappings enable the codebase to work with multiple datasets without requiring dataset-specific code paths.

Key Features:

  • Feature name standardization: Maps dataset-specific feature names to standard format names for consistent processing across datasets.

  • Multi-camera support: Handles datasets with varying numbers of camera views, mapping them to standard camera0, camera1, etc. names.

  • Loss type specification: Maps datasets to appropriate loss functions (MSE for continuous actions, CE for discrete classification tasks).

Constants:

DATA_FEATURES_NAME_MAPPING

Dictionary mapping dataset repository IDs to feature name dictionaries. Each inner dictionary maps standard feature names (keys) to dataset-specific feature names (values). Standard feature names include:

  • “camera0”, “camera1”, …: Camera/image observations

  • “state”: Robot state observations

  • “actions”: Action outputs

  • “prompt”: Task descriptions or prompts

  • “response”: Expected responses or labels

  • “mistake”: Mistake-polarity signal (True/1 = something went wrong); must name a per-frame column (episode-level outcomes belong on “success”); defaults to the literal “mistake” column written by annotate_mistakes.py / attach_metadata.py

  • “success”: Success-polarity signal (True = episode succeeded), e.g. DROID’s “is_episode_successful”. Resolved from the frame column or the per-episode metadata (including the per-episode “mean” aggregate in episodes_stats, v2.1+) and inverted into “mistake” when no mistake column exists; also drives the value-function return bins

Example

Access feature name mapping for a dataset:
>>> mapping = DATA_FEATURES_NAME_MAPPING["lerobot/aloha_mobile_cabinet"]
>>> mapping["camera0"]  # Returns "observation.images.cam_right_wrist"
>>> mapping["actions"]  # Returns "action"

Functions

feature_mapping_key(repo_id, control_mode)

Return the DATA_FEATURES_NAME_MAPPING key for a dataset entry.

resolve_feature_mapping(repo_id[, control_mode])

Look up a dataset's feature-name mapping, control-mode-aware.
opentau.datasets.standard_data_format_mapping.feature_mapping_key(repo_id: str, control_mode: str | None) → str[source]

Return the DATA_FEATURES_NAME_MAPPING key for a dataset entry.

Two mixture entries can share a repo_id while declaring different data_features_name_mapping values — e.g. the same robot exposed as control_mode="joint" (actions -> action_joint) and control_mode="ee" (actions -> action_ee). Keying the global mapping by repo_id alone makes the second registration clobber the first, so the “joint” entry would silently read the end-effector column. Disambiguating by control_mode lets both coexist.

Returns "<repo_id>::<control_mode>" when control_mode is a real, non-empty label, and the plain repo_id otherwise (missing / whitespace / "unknown") — so built-in defaults and single-mode datasets keep their existing repo_id keys.

opentau.datasets.standard_data_format_mapping.resolve_feature_mapping(repo_id: str, control_mode: str | None = None) → dict[str, str][source]

Look up a dataset’s feature-name mapping, control-mode-aware.

Prefers the precise "<repo_id>::<control_mode>" entry and falls back to the plain repo_id entry (built-in defaults / single-mode datasets / back-compat). Raises KeyError if neither is registered.