---
title: Codebook
emoji: 📚
colorFrom: pink
colorTo: indigo
sdk: static
pinned: false
---

Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference

# Human-Robot Collaboration Failure Codebook

- browse all failure categories
- open a category detail page with its definition and representative example
- inspect every coded segment attached to that category
- search all coded segments across the dataset

## Project Structure

```text
.
|-- index.html                  # Homepage with failure category cards
|-- category.html               # Detail page for one failure category
|-- all_videos.html             # Searchable table of all coded segments
|-- assets/
|   |-- css/                    # Shared and page-specific styles
|   `-- js/
|       |-- failures.js         # Failure definitions and metadata
|       |-- homepage.js         # Homepage search + category stats
|       |-- category.js         # Category page rendering
|       |-- all_videos.js       # All-videos table rendering
|       `-- video_segment.js    # Video loop/playback behavior
|-- raw_data.csv                # Original Label Studio export
|-- cleaned_data.csv            # Flattened CSV used by the web app
|-- clean.py                    # Converts raw_data.csv -> cleaned_data.csv
`-- videos/                     # Source MP4 files referenced by the app
```


## Data Files

### `raw_data.csv`

This is the original annotation export. It contains:

- `id`
- `participant`
- `condition`
- `run`
- `filename`
- `videoLabels`

The `videoLabels` column stores Label Studio timeline annotations as JSON.

### `cleaned_data.csv`

This is the flattened file the app actually uses. It contains one row per coded label occurrence:

- `filename`
- `video_id`
- `video_path`
- `label`
- `start`
- `end`


## Video Playback Rules

Segment playback behavior is implemented in `assets/js/video_segment.js`.

Each embedded video:

- lazy-loads when it gets near the viewport
- starts from a computed frame-based window
- loops only within the relevant segment
- respects manual pause and scrubbing

Some labels have custom playback behavior. For example:

- `Success` and `Failure` play the full video
- `Safety Avoidance` and `Redundant Retrieval` play from the annotated start to the end of the video
- `Missed Grab` and `Slippage` expand the playback window around the annotation

Default FPS is set to `30`.

## Typical Update Workflow

1. Replace or update `raw_data.csv`.
2. Run `python3 clean.py`.
3. Confirm `cleaned_data.csv` was regenerated correctly.
4. Add or update files in `videos/` if needed.
5. Start a local server and verify `index.html`, `category.html`, and `all_videos.html`.

## Current Dataset Snapshot

At the time of this README update, the repository contains:

- `288` data rows in `raw_data.csv` excluding the header
- `657` data rows in `cleaned_data.csv` excluding the header