[DRAFT] Document data sequences, capture on demand, and sequence datasets

[Eliza Farley (elizafarley)]

Summary

Documents data sequences end to end: capturing on demand, recording and reviewing sequences, building sequence datasets, and exporting them for custom training.

New pages

• data/capture-sync/capture-on-demand.md: start and stop capture on demand with the capture-control module (default path), with writing your own capture control sensor as an advanced option.
• data/sequences.md: what sequences are, and how to record, view, and manage them.
• data/sequences-tutorial.md: end-to-end tutorial from recording to export, with Viam app and CLI/SDK tabs for each step.
• train/sequence-dataset-format.md: the Parquet export format for sequence datasets and how to train on it.
• Glossary term: sequence.

Reworked pages

• train/create-a-dataset.md: organized around the two dataset types (image and sequence). One shared create step, then adding data, image training prep, and export split by type, plus a comparison table of what each type supports. Incoming links that pointed at removed section anchors now point at the page itself.
• Data, train, CLI, and API reference pages updated where sequences or sequence datasets affect them: custom training scripts, train a model, export data, the CLI dataset commands, the ML training client, and others.

Generated SDK docs

• Added sdk_protos_map.csv rows and proto description overrides for the sequence and sequence-dataset-export RPCs.

Checks

• prettier 3.2.5, markdownlint, vale, and make build-prod pass on the changed pages.

🤖 Generated with Claude Code

[netlify]

✅ Deploy Preview for viam-docs ready!

Name	Link
🔨 Latest commit	75bb2aa
🔍 Latest deploy log	https://app.netlify.com/projects/viam-docs/deploys/6ac595640570e40008cbd050
😎 Deploy Preview	https://deploy-preview-5374--viam-docs.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.
Lighthouse	1 paths audited Performance: 36 (🔴 down 7 from production) Accessibility: 100 (no change from production) Best Practices: 100 (no change from production) SEO: 92 (no change from production) PWA: 60 (no change from production) View the detailed breakdown and full score reports

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[Jeremy Rose (jeremyrose-viam)]

FYI, the Go DataClient sequences rows here also cover the sequences methods that #5190 tracks as undocumented, so that issue can close when this merges. The Go scraper already attributes by proto name, so no generator change was needed.

[Vignesh P (vpandiarajan20)]

We query ADF to get tabular data and we bill for ADF, I think at the end of the month.

[Jeremy Rose (jeremyrose-viam)]

Reviewed from a documentation-user perspective, and I ran the tutorial's CLI path end to end on a fresh machine. Steps 1 to 7 work as written, and the exported Parquet schema matches the format page. Confirmed by running: the CLI can't add the module (step 2), and --api is required for the data manager (step 3). Comments are inline. The ones I'd prioritize: the stale capture_disabled row, the version prerequisites, the unresolved billing wording, and the missing sequence training example.

Not in the diff: the contradiction with cli/configure-machines.md on --api (see the comment on tutorial line 189).

[Jeremy Rose (jeremyrose-viam)]

Thanks for the quick turnaround on the review. The tutorial now reads cleanly from start to finish. I'm approving, and I wanted to make a case for one thing that I'd really like to see, either in this PR or as a fast follow-up.

A short sequence-dataset example in custom-training-scripts.md. Everything in this PR leads to "train a model on a sequence dataset," and the tutorial ends with the reader holding three Parquet files. The binary path on that page has a skeleton script to copy. The sequence path has an argument table and a pointer to the column docs, so the reader has to work out the same three things from scratch:

• path is relative in an export and absolute in a cloud job.
• payload is a JSON string with a readings wrapper.
• Images and readings run at different rates, so they have to be matched by nearest timestamp. A row-by-row join gives wrong pairs without any error.

I don't mean a training loop, which depends on the task. About 15 lines that load and pair the data would do it. I ran this sketch against an export from the tutorial (87 images, 87 readings, all image paths resolved), so you're welcome to adapt it:

import json
import os

import pandas as pd

export_dir = "demos"  # in a training job, `path` is already absolute
images = pd.read_parquet(f"{export_dir}/parquet/binary_data.parquet")
readings = pd.read_parquet(f"{export_dir}/parquet/tabular_data.parquet")
sequences = pd.read_parquet(f"{export_dir}/parquet/sequences.parquet")

# Resolve image paths. They're relative in an export, absolute in a training job.
images["path"] = images["path"].map(
    lambda p: p if os.path.isabs(p) else os.path.join(export_dir, p)
)

# Unpack the JSON payload, for example {"readings": {"a": 1.0}}.
readings = pd.concat(
    [readings, pd.json_normalize(readings["payload"].map(json.loads))], axis=1
)

# Each resource has its own sample rate, so pair each image with the
# nearest reading in the same sequence.
pairs = pd.merge_asof(
    images.sort_values("timestamp"),
    readings.sort_values("timestamp"),
    on="timestamp",
    by="sequence_id",
    direction="nearest",
    suffixes=("_image", "_reading"),
).merge(sequences[["sequence_id", "tags"]], on="sequence_id")

Two things to confirm before using it. A training job reads --binary_data_file and the other arguments instead of hardcoding paths, and pd.merge_asof assumes pandas is available in the training container.

If you'd rather keep this PR small, a follow-up is fine. I'd just like it to land soon, because this is the first thing a reader will try after the tutorial.

[viam-overwatch]

Hey Eliza Farley (@elizafarley) — this PR has been approved and CI has been green for 3+ business days. Ready to merge?

Auto-comment from overwatch. Will not re-nudge for 7 days.