"They asked me why I confused sleep apnea with a loose wristband. I would have told them, but nobody wrote down which wristband, which firmware, or which wrist."
An Under-Documented AI Agent
Prerequisites
This section builds on the leakage-safe dataset construction of Chapter 5 and the sampling, timing, and synchronization vocabulary of Chapter 3: we assume you can already say what a sample rate, a session, and a subject-disjoint split are. Here we do not re-derive those; we ask how to write them down so that a dataset survives contact with auditors, regulators, and the engineer who inherits it in three years. The biometric-consent constraints referenced below are developed fully in Section 70.2.
The Big Picture
A sensor dataset is not a folder of arrays; it is a claim about the physical world, made under specific instruments, bodies, and conditions. Dataset governance is the practice of attaching enough structured metadata to that claim that a stranger can judge whether it is fit for a purpose, and can be held accountable when it is misused. Two artifacts dominate the field: the datasheet for datasets (a long-form questionnaire covering motivation, composition, collection, preprocessing, distribution, and maintenance) and the dataset card (a shorter, structured, machine-readable companion that ships with the data). For sensor AI these documents carry weight that vision or text datasets rarely feel: the sensor make and firmware, the mounting geometry, the clock discipline, and the consent basis are all load-bearing, and omitting any one of them silently invalidates downstream models. This section teaches what to record, why each field prevents a specific failure, and how to make the record a build artifact rather than an afterthought.
Why sensor datasets need heavier governance than they usually get
The datasheet-for-datasets idea (Gebru and colleagues, 2018, revised 2021) and the model-card and dataset-card conventions (Mitchell and colleagues, 2019; the Hugging Face dataset-card schema) were forged largely on image and language corpora. Sensor data inherits every concern they raise (consent, representativeness, licensing) and adds a physical layer that has no analogue in a folder of JPEGs. A photograph does not change identity when you swap the camera firmware; a photoplethysmography (PPG) waveform does. The green-LED sampling rate, the analog front-end gain, the skin-tone-dependent optical coupling, and the wristband tightness all reshape the signal before any model sees it. If the dataset does not record them, a model trained on it cannot be reproduced, cannot be safely transferred to a new device, and cannot be audited when it fails on a demographic the collection under-sampled.
The governance payload for a sensor dataset therefore has three tiers. The first is the generic datasheet content: who made it, why, under what license, with what consent, and how it will be maintained. The second is the instrument tier: sensor model and revision, firmware version, sample rate and its jitter, dynamic range, calibration procedure, units, and clock-synchronization method across modalities. The third is the context tier: subject demographics, body placement and orientation, environment (temperature, motion regime, surface), and the session structure that determines what a leakage-safe split even means. Skip the instrument tier and your dataset is irreproducible; skip the context tier and your fairness and generalization claims are unfounded.
Key Insight
For sensor data, provenance is a feature. The identity of the device, its firmware, and its mounting are confounders that a model will happily exploit as shortcuts. A dataset card that omits them does not merely lose reproducibility; it hides the very variables you must hold disjoint across train and test to get an honest number. Governance metadata and leakage-safe evaluation (Chapter 65) are the same discipline viewed from two ends: you cannot split on a variable you never recorded.
What goes on a sensor dataset card
A dataset card is a structured document, ideally machine-readable, that travels inside the dataset repository. Treat it as a schema with mandatory fields, not free prose. The generic backbone follows the datasheet sections, and to it you append sensor-specific blocks. The minimum viable set of fields for a sensor corpus is: identity (name, version, DOI, license, maintainer, contact); motivation (the task it was built for, and explicit non-uses); instruments (per-modality sensor model, firmware, sample rate, units, calibration, sync method); composition (subject count, sessions per subject, class balance, and the split keys); collection (protocol, IRB or ethics approval identifier, consent language, dates, geography); known limitations (demographic gaps, environmental coverage, sensor failure modes present); and maintenance (versioning policy, deprecation, how errata are published).
Two fields do disproportionate work and are the two most often missing. The first is the split key: the column that identifies the unit you must keep disjoint (subject, device, site, session). Recording it turns the leakage-safe split from tribal knowledge into a checkable invariant. The second is the consent scope: what the subjects agreed their data could be used for, because a corpus collected for clinical validation of an arrhythmia detector cannot be silently repurposed to train an emotion classifier without violating the basis it was gathered under, a distinction the regulation section (Section 70.6) makes legally sharp.
Step-Through: a wrist-PPG sleep study that could not be reused
A digital-health team assembles 400 nights of wrist PPG and accelerometry to build a sleep-staging model, and the retrospective numbers are excellent. Two years later a second team wants to reuse the corpus for atrial-fibrillation screening (the modeling side of which lives in Chapter 30). Three governance gaps stop them cold. First, the card never recorded the wristband firmware; midway through collection an over-the-air update changed the PPG sampling from 25 Hz to 50 Hz, so half the corpus has a different spectral content and no field flags which half. Second, the split key was "file name", and several subjects wore the device across multiple nights under different file names, so the original sleep model had leaked subjects across folds and its accuracy was inflated. Third, the consent form authorized "sleep research" only; AF screening is a new medical purpose outside the scope, and the ethics board blocks reuse. None of these are modeling failures. A dataset card with an instrument.firmware field, a declared subject_id split key, and a consent_scope enum would have surfaced all three before a single model was trained, and the firmware field alone would have let the second team stratify rather than discard.
Make the card a build artifact, not a memory
Governance decays the moment it depends on someone remembering to update a document. The durable pattern is to generate the dataset card from the data and the collection log programmatically, so that the recorded sample rate is measured from the timestamps rather than typed from a spec sheet, and the class balance and subject count are counted rather than recalled. When the card is a function of the data, it cannot drift from the data. Code 70.5.1 sketches this: it ingests a manifest of sessions, verifies that mandatory instrument and consent fields are present, measures the effective sample rate from timestamps, and refuses to emit a card if a required field is missing. Wiring this check into the same pipeline that publishes the dataset (the MLOps machinery of Chapter 69) makes an undocumented dataset a build failure rather than a code-review comment.
import numpy as np
REQUIRED = ["sensor_model", "firmware", "units", "consent_scope", "split_key"]
def build_dataset_card(sessions, declared):
"""Emit a dataset card only if governance fields are present and
the declared sample rate matches what the timestamps actually show."""
missing = [f for f in REQUIRED if f not in declared]
if missing:
raise ValueError(f"Refusing to publish: missing fields {missing}")
# Measure the effective sample rate from timestamps, do not trust the spec.
rates = [1.0 / np.median(np.diff(s["t"])) for s in sessions if len(s["t"]) > 1]
fs_measured = float(np.median(rates))
fs_spread = float(np.max(rates) - np.min(rates)) # firmware/clock drift signal
subjects = {s["subject_id"] for s in sessions}
split_vals = {s[declared["split_key"]] for s in sessions}
return {
"identity": declared["name"], "license": declared["license"],
"instruments": {"sensor_model": declared["sensor_model"],
"firmware": declared["firmware"],
"units": declared["units"],
"fs_declared_hz": declared.get("fs_hz"),
"fs_measured_hz": round(fs_measured, 3),
"fs_spread_hz": round(fs_spread, 3)},
"composition": {"n_sessions": len(sessions),
"n_subjects": len(subjects),
"split_key": declared["split_key"],
"n_split_groups": len(split_vals)},
"consent_scope": declared["consent_scope"],
}
sessions = [{"subject_id": f"S{i%7}", "device": f"D{i%3}",
"t": np.cumsum(np.random.default_rng(i).exponential(0.04, 500))}
for i in range(21)]
declared = dict(name="wrist-ppg-sleep", license="CC-BY-NC-4.0",
sensor_model="MAX86141", firmware="1.4.0", units="ADC_counts",
fs_hz=25.0, consent_scope="sleep_research", split_key="subject_id")
card = build_dataset_card(sessions, declared)
print(card["instruments"], "\n", card["composition"])
fs_spread_hz. The declared split_key is materialized into a counted group so reviewers can confirm a subject-disjoint evaluation is even possible.Notice what Code 70.5.1 buys you: the gap between fs_declared_hz and fs_measured_hz, and any nonzero fs_spread_hz, are exactly the signals that catch a firmware or clock-discipline change before it silently poisons a model. The card is now a test, and an undocumented instrument change turns red.
Right Tool: let the dataset-hub tooling carry the card
Writing a validated, machine-readable card schema, a Markdown renderer, and a versioned publication flow by hand is a few hundred lines of boilerplate. The Hugging Face datasets library plus huggingface_hub give you a typed DatasetCard and DatasetCardData object, a YAML front-matter schema, and push_to_hub versioning in roughly 5 lines: build the card dict (as in Code 70.5.1), wrap it with DatasetCard.from_template(...), and push. That is about a 200-line reduction, and the schema validation, template rendering, and immutable version snapshots come for free. Keep your governance logic (the field checks and the measured-vs-declared sample-rate audit) as the wrapper; let the hub own storage and rendering.
From documents to accountability
Governance artifacts only matter if they change decisions, so bind each field to a downstream gate. The consent-scope field should be read by the training pipeline, which refuses to load a corpus for a task outside its declared scope. The split-key field should be consumed by the evaluation harness, which asserts that no split group appears in two folds before it reports a metric. The demographic-composition block should feed the subgroup-fairness slicing of Section 70.3, so that a known under-representation becomes a reported confidence caveat rather than a surprise in production. When a dataset is versioned, deprecated, or found to contain a labeling error, the maintenance section is where the erratum lives, and the version DOI is what lets a deployed model state exactly which snapshot it trusted. This closes the loop that the documentation-and-accountability section (Section 70.7) generalizes to the whole system: a claim you cannot trace to a governed dataset is a claim you cannot defend.
Exercise
Take an inertial human-activity corpus you have used (or the structure of one from Chapter 26). (a) Draft the instrument tier of its dataset card: list every field whose change would alter the accelerometer signal, and mark which ones you could recover today versus which are lost. (b) Extend Code 70.5.1 so the card also fails if any single subject supplies more than 40% of the samples of any one activity class, and explain which downstream claim that guard protects. (c) Write two sentences of known_limitations that an honest maintainer would include, and name the deployment decision each caveat should block.
Self-Check
- Name three sensor-specific fields that a text-dataset card never needs but a PPG or IMU card must carry, and give the concrete failure each one prevents.
- Why is generating the dataset card from the data (measuring the sample rate from timestamps) strictly safer than transcribing it from the sensor's spec sheet?
- A team wants to reuse a clinically-collected corpus for a new task. Which two card fields most directly determine whether they are allowed to, and what does each one encode?
What's Next
In Section 70.6, we move from the documents you author voluntarily to the ones the law compels. The consent-scope and provenance fields introduced here become legally operative under the EU AI Act's treatment of biometric and emotion inference as high-risk, under GDPR's purpose-limitation and data-subject rights, and under the FDA's expectations for datasets backing a medical device, and we will see how a well-built dataset card is already most of a compliance dossier.