data-model.md

Data Model and Sensor Channels

Time Index

All sensor DataFrames are indexed by timestamp in seconds (float), derived from packet timestamps in microseconds.

Sensor Streams

SensorDataset defines these sensor streams:

• imu (SID 0)
• barometer (SID 1)
• microphone (SID 2)
• ppg (SID 4)
• optical_temp (SID 6)
• bone_acc (SID 7)

Default Columns by Sensor

• imu: acc.x, acc.y, acc.z, gyro.x, gyro.y, gyro.z, mag.x, mag.y, mag.z
• barometer: barometer.temperature, barometer.pressure
• ppg: ppg.red, ppg.ir, ppg.green, ppg.ambient
• bone_acc: bone_acc.x, bone_acc.y, bone_acc.z
• optical_temp: optical_temp
• microphone: mic.inner, mic.outer

Accessor Semantics

Each sensor is exposed as a _SensorAccessor object:

• sensor.df or sensor.to_dataframe() returns the full sensor DataFrame with original column names.
• Group columns are available as sub-DataFrames:
  • dataset.imu.acc -> columns x, y, z
  • dataset.imu.gyro -> columns x, y, z
  • dataset.imu.mag -> columns x, y, z
  • dataset.ppg.ppg -> columns red, ir, green, ambient
• Original columns remain directly accessible:
  • dataset.imu["acc.x"]
  • dataset.ppg["ppg.red"]

Combined DataFrame

get_dataframe() merges all non-empty per-sensor DataFrames:

• Creates a union of all sensor timestamps.
• Reindexes each sensor DataFrame onto that common index.
• Concatenates columns into one DataFrame.

This preserves each stream while aligning them on time.

Microphone Data Details

Microphone payloads are parsed as interleaved int16 samples and converted to stereo frames:

• Input interleaving: [outer, inner, outer, inner, ...]
• Output stereo columns/order: [inner, outer]

The audio DataFrame generated by get_audio_dataframe() uses:

• index: timestamp in seconds
• columns: mic.inner, mic.outer