Skip to content

Commit 11fe098

Browse files
DennisMoschinaDennisMoschina
committed
docs: update changelog and add documentation for getting started, data model, and API reference
1 parent d822511 commit 11fe098

6 files changed

Lines changed: 318 additions & 84 deletions

File tree

‎CHANGELOG.md‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,10 @@
11
## 0.0.2
22

33
* added access to raw microphone dataframes
4+
* added a dedicated `docs/` documentation set (getting started, data model, API reference)
5+
* updated `README.md` as a concise entry point and linked full docs
46

57
## 0.0.1
68

79
* Initial release of the Open Earable Python SDK.
8-
* parse Open Earable data files
10+
* parse Open Earable data files

‎README.md‎

Lines changed: 17 additions & 83 deletions
Original file line numberDiff line numberDiff line change
@@ -1,23 +1,14 @@
11
# Open Earable Python
22

3-
A Python toolkit for parsing and analyzing multi-sensor recordings from an OpenEarable device. The library provides pandas-friendly accessors for IMU, barometer, PPG, bone accelerometer, optical temperature, and microphone data, along with audio utilities.
4-
5-
## Features
6-
- Load `.oe` recordings into a single time-aligned pandas DataFrame.
7-
- Convenient attribute and key-based accessors for grouped sensors and individual channels.
8-
- Play or export microphone audio directly from notebooks.
9-
- Export combined sensor data to CSV for downstream analysis.
3+
Python toolkit for parsing and analyzing multi-sensor OpenEarable recordings.
104

115
## Installation
12-
The package targets Python 3.9+.
13-
14-
Once published to PyPI:
156

167
```bash
178
pip install open-earable-python
189
```
1910

20-
From source (for development):
11+
For local development:
2112

2213
```bash
2314
git clone https://github.com/OpenEarable/open-earable-python.git
@@ -27,86 +18,29 @@ source .venv/bin/activate
2718
pip install -e .
2819
```
2920

30-
## Quickstart
31-
Load a recording and explore the combined DataFrame:
21+
## Quick Example
3222

3323
```python
3424
from open_earable_python import SensorDataset
3525

36-
# Load a single .oe file
37-
recording = SensorDataset("my_recording.oe")
26+
dataset = SensorDataset("recording.oe")
3827

39-
# Time-indexed dataframe containing all available sensors
40-
full_df = recording.get_dataframe()
41-
print(full_df.head())
28+
# Combined time-indexed DataFrame of all parsed sensors
29+
df = dataset.get_dataframe()
4230

43-
# Export to CSV
44-
recording.save_csv("my_recording.csv")
31+
# Per-sensor views
32+
imu_df = dataset.imu.df
33+
ppg_red = dataset.ppg["ppg.red"]
34+
audio_df = dataset.get_audio_dataframe()
4535
```
4636

47-
### Sensor access patterns
48-
Each sensor has an accessor exposing both grouped views and individual channels using attribute or key syntax. For IMU data:
49-
50-
```python
51-
imu = recording.imu
52-
53-
# Full IMU dataframe (original column names retained)
54-
imu.df # or imu.to_dataframe()
55-
imu["acc.x"] # Column-style access
56-
57-
# Accelerometer
58-
imu.acc # Accelerometer dataframe
59-
imu.acc["x"] # Accelerometer X channel
60-
imu.acc["y"]
61-
imu.acc["z"]
37+
## Documentation
6238

63-
# Gyroscope
64-
imu.gyro # Gyroscope dataframe
65-
imu.gyro["x"]
66-
imu.gyro["y"]
67-
imu.gyro["z"]
39+
- [Documentation index](docs/README.md)
40+
- [Getting started](docs/getting-started.md)
41+
- [Data model and sensor channels](docs/data-model.md)
42+
- [API reference](docs/api-reference.md)
6843

69-
# Magnetometer
70-
imu.mag # Magnetometer dataframe
71-
imu.mag["x"]
72-
imu.mag["y"]
73-
imu.mag["z"]
74-
```
75-
76-
PPG channels follow the same pattern:
77-
78-
```python
79-
ppg = recording.ppg
80-
ppg.df # Full PPG dataframe
81-
ppg["ppg.red"] # Column-style access
82-
ppg["red"] # Channel shortcut
83-
ppg.ir
84-
ppg.green
85-
ppg.ambient
86-
```
44+
## License
8745

88-
### Working with multiple recordings
89-
Load several files at once and iterate over them:
90-
91-
```python
92-
from open_earable_python.dataset import load_recordings
93-
94-
paths = ["session1.oe", "session2.oe"]
95-
recordings = load_recordings(paths)
96-
97-
# Access a specific recording
98-
first = recordings[0]
99-
print(first.list_sensors())
100-
```
101-
102-
### Audio utilities
103-
- `play_audio(sampling_rate=48000)`: play stereo microphone data in a Jupyter environment.
104-
- `save_audio(path, sampling_rate=48000)`: export microphone audio to WAV.
105-
- `get_audio_dataframe(sampling_rate=48000)`: return microphone PCM as a timestamp-indexed DataFrame (`mic.inner`, `mic.outer`).
106-
107-
Example:
108-
109-
```python
110-
audio_df = recording.get_audio_dataframe()
111-
print(audio_df.head())
112-
```
46+
MIT. See `LICENSE`.

‎docs/README.md‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
# Open Earable Python Documentation
2+
3+
`open-earable-python` parses `.oe` recordings into pandas DataFrames and exposes convenient accessors for OpenEarable sensor streams.
4+
5+
## Contents
6+
7+
- [Getting started](getting-started.md)
8+
- [Data model and sensor channels](data-model.md)
9+
- [API reference](api-reference.md)
10+
11+
## Package Scope
12+
13+
- Parse binary OpenEarable streams into structured sensor samples.
14+
- Build per-sensor and combined time-indexed DataFrames.
15+
- Decode microphone PCM samples and export/play audio.
16+
- Load one or multiple recordings with the same API.

‎docs/api-reference.md‎

Lines changed: 125 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,125 @@
1+
# API Reference
2+
3+
## Package Exports
4+
5+
```python
6+
from open_earable_python import SensorDataset, load_recordings
7+
```
8+
9+
## `SensorDataset`
10+
11+
High-level API for loading and analyzing a single `.oe` recording.
12+
13+
### Constructor
14+
15+
```python
16+
SensorDataset(filename: str, verbose: bool = False)
17+
```
18+
19+
- `filename`: path to `.oe` file.
20+
- `verbose`: enables parser diagnostic output.
21+
22+
Parsing happens during initialization.
23+
24+
### Attributes
25+
26+
- `filename: str` source file path.
27+
- `verbose: bool` parser verbosity flag.
28+
- `parse_result: parser.ParseResult` raw parse output.
29+
- `sensor_dfs: Dict[int, pandas.DataFrame]` per-SID DataFrames.
30+
- `df: pandas.DataFrame` lazily built combined DataFrame.
31+
- `audio_stereo: Optional[numpy.ndarray]` stereo audio frames (`int16`, shape `(N, 2)`).
32+
- `audio_df: pandas.DataFrame` cached audio DataFrame.
33+
34+
Sensor accessor attributes:
35+
36+
- `dataset.imu`
37+
- `dataset.barometer`
38+
- `dataset.microphone`
39+
- `dataset.ppg`
40+
- `dataset.optical_temp`
41+
- `dataset.bone_acc`
42+
43+
Each accessor supports grouped and channel-level access (see data model docs).
44+
45+
### Methods
46+
47+
#### `parse() -> None`
48+
49+
Re-parses the recording file and updates `parse_result`.
50+
51+
#### `list_sensors() -> List[str]`
52+
53+
Returns sensor names with non-empty DataFrames.
54+
55+
#### `get_sensor_dataframe(name: str) -> pandas.DataFrame`
56+
57+
Returns one sensor DataFrame by name.
58+
59+
- Valid names: `imu`, `barometer`, `microphone`, `ppg`, `optical_temp`, `bone_acc`
60+
- Raises `KeyError` for unknown names.
61+
62+
#### `get_dataframe() -> pandas.DataFrame`
63+
64+
Builds and caches a merged DataFrame across all non-empty sensor streams.
65+
66+
#### `get_audio_dataframe(sampling_rate: int = 48000) -> pandas.DataFrame`
67+
68+
Returns timestamp-indexed audio DataFrame with columns:
69+
70+
- `mic.inner`
71+
- `mic.outer`
72+
73+
Behavior:
74+
75+
- Raises `ValueError` if `sampling_rate <= 0`.
76+
- Returns empty DataFrame with expected columns if no mic packets exist.
77+
- Caches by sampling rate.
78+
79+
#### `export_csv() -> None`
80+
81+
Writes combined DataFrame to `<recording_basename>.csv` by delegating to `save_csv()`.
82+
83+
#### `save_csv(path: str) -> None`
84+
85+
Saves the combined DataFrame to CSV if `self.df` is non-empty.
86+
87+
Call `get_dataframe()` first to ensure `self.df` is populated.
88+
89+
#### `play_audio(sampling_rate: int = 48000) -> None`
90+
91+
Plays audio in IPython/Jupyter via `IPython.display.Audio`.
92+
93+
#### `save_audio(path: str, sampling_rate: int = 48000) -> None`
94+
95+
Writes WAV audio with `scipy.io.wavfile.write`.
96+
97+
## `load_recordings`
98+
99+
```python
100+
load_recordings(file_paths: Sequence[str]) -> List[SensorDataset]
101+
```
102+
103+
Creates `SensorDataset` objects for existing files only.
104+
105+
## Parser Module (`open_earable_python.parser`)
106+
107+
Core classes and helpers for decoding binary packets:
108+
109+
- `Parser`: stream parser over packetized binary data.
110+
- `PayloadParser`: base parser interface.
111+
- `SchemePayloadParser`: parser built from `SensorScheme`.
112+
- `MicPayloadParser`: parser for microphone payloads.
113+
- `ParseResult`: parse container with per-SID DataFrames and microphone artifacts.
114+
- `interleaved_mic_to_stereo(samples)`: converts interleaved samples to stereo.
115+
- `mic_packet_to_stereo_frames(packet, sampling_rate)`: timestamp + stereo frame conversion.
116+
117+
## Scheme Module (`open_earable_python.scheme`)
118+
119+
Defines sensor schema primitives:
120+
121+
- `ParseType` enum
122+
- `SensorComponentScheme`
123+
- `SensorComponentGroupScheme`
124+
- `SensorScheme`
125+
- `build_default_sensor_schemes(sensor_sid)`

‎docs/data-model.md‎

Lines changed: 61 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,61 @@
1+
# Data Model and Sensor Channels
2+
3+
## Time Index
4+
5+
All sensor DataFrames are indexed by `timestamp` in seconds (`float`), derived from packet timestamps in microseconds.
6+
7+
## Sensor Streams
8+
9+
`SensorDataset` defines these sensor streams:
10+
11+
- `imu` (SID 0)
12+
- `barometer` (SID 1)
13+
- `microphone` (SID 2)
14+
- `ppg` (SID 4)
15+
- `optical_temp` (SID 6)
16+
- `bone_acc` (SID 7)
17+
18+
## Default Columns by Sensor
19+
20+
- `imu`: `acc.x`, `acc.y`, `acc.z`, `gyro.x`, `gyro.y`, `gyro.z`, `mag.x`, `mag.y`, `mag.z`
21+
- `barometer`: `barometer.temperature`, `barometer.pressure`
22+
- `ppg`: `ppg.red`, `ppg.ir`, `ppg.green`, `ppg.ambient`
23+
- `bone_acc`: `bone_acc.x`, `bone_acc.y`, `bone_acc.z`
24+
- `optical_temp`: `optical_temp`
25+
- `microphone`: `mic.inner`, `mic.outer`
26+
27+
## Accessor Semantics
28+
29+
Each sensor is exposed as a `_SensorAccessor` object:
30+
31+
- `sensor.df` or `sensor.to_dataframe()` returns the full sensor DataFrame with original column names.
32+
- Group columns are available as sub-DataFrames:
33+
- `dataset.imu.acc` -> columns `x`, `y`, `z`
34+
- `dataset.imu.gyro` -> columns `x`, `y`, `z`
35+
- `dataset.imu.mag` -> columns `x`, `y`, `z`
36+
- `dataset.ppg.ppg` -> columns `red`, `ir`, `green`, `ambient`
37+
- Original columns remain directly accessible:
38+
- `dataset.imu["acc.x"]`
39+
- `dataset.ppg["ppg.red"]`
40+
41+
## Combined DataFrame
42+
43+
`get_dataframe()` merges all non-empty per-sensor DataFrames:
44+
45+
- Creates a union of all sensor timestamps.
46+
- Reindexes each sensor DataFrame onto that common index.
47+
- Concatenates columns into one DataFrame.
48+
49+
This preserves each stream while aligning them on time.
50+
51+
## Microphone Data Details
52+
53+
Microphone payloads are parsed as interleaved `int16` samples and converted to stereo frames:
54+
55+
- Input interleaving: `[outer, inner, outer, inner, ...]`
56+
- Output stereo columns/order: `[inner, outer]`
57+
58+
The audio DataFrame generated by `get_audio_dataframe()` uses:
59+
60+
- index: `timestamp` in seconds
61+
- columns: `mic.inner`, `mic.outer`

0 commit comments

Comments
 (0)