ao_compensation_model

A GRU-based compensation model that improves the performance of adaptive oscillators (AOs) during stop-go and go-stop gait transitions. The model learns the phase error between the AO output and the ground-truth gait phase, and applies a real-time correction on edge devices via TFLite.

Data Acquisition

The training data was collected using three walking protocols:

1. Steady-state treadmill walking at 3, 4, and 5 km/h, with each speed recorded for 5 minutes.
2. Dynamic treadmill transitions at 4 km/h, using 30-second walking bursts separated by rest periods of 10, 5, and 3 seconds. The full sequence was repeated twice to capture rapid stop-go changes.
3. Overground stop-go walking, consisting of exactly 10 steps on level ground followed by standing breaks of 10, 5, and 3 seconds. This sequence was repeated four times.

After acquisition, run prep to convert the raw recordings into training-ready CSV files. Before training, quickly review the processed output to make sure the auto-generated targets and phase traces remain smooth and do not contain sudden jumps.

Pipeline

Step	Command	Description
1	prep	Bandpass-filters raw IMU hip angles, aligns AO phase, and computes target_cos and target_sin training targets.
2	train	Trains a GRU network on sliding windows of AO features and exports an optimized TFLite model.
3	validate	Runs frame-by-frame TFLite inference on test data and visualises predicted phase and its sin/cos outputs alongside raw kinematics.
4	txt2csv	Converts raw sensor text files (tab / comma / semicolon delimited) in a folder to semicolon-delimited CSVs.

Install

From PyPI:

pip install ao-compensation-model

From source:

git clone https://github.com/lhharry/ao_compensation_model.git
cd ao_compensation_model
uv sync

Usage

CLI

All commands follow the pattern:

uv run python -m ao_compensation_model <command> [options]

Data Preparation

# Prepare ground-truth targets from all raw CSVs
uv run python -m ao_compensation_model prep

# Prepare a single file
uv run python -m ao_compensation_model prep --file 20260304_17_13_22_stopgo.csv

# Prepare with a manual stationary threshold (default: auto)
uv run python -m ao_compensation_model prep --file recording.csv --threshold 0.1

Training

uv run python -m ao_compensation_model train

Validation

# Validate all test files
uv run python -m ao_compensation_model validate

# Validate a specific test file
uv run python -m ao_compensation_model validate --file 20260304_14_26_34_4km_stopgo.csv

File Conversion

# Opens a folder picker GUI
uv run python -m ao_compensation_model txt2csv

# Convert a specific folder
uv run python -m ao_compensation_model txt2csv --file /path/to/folder

CLI Flags

Flag	Applies to	Description
--file	prep, validate, txt2csv	prep: single CSV to process. validate: single test CSV. txt2csv: folder path.
--threshold	prep	Amplitude threshold for stationary detection. Omit or pass auto for automatic (default: auto).
--log-level	all	Log level (TRACE, DEBUG, INFO, SUCCESS, WARNING, ERROR, CRITICAL).
--stderr-level	all	Stderr log level.

As a Library

from ao_compensation_model.training import build_gru_model
from ao_compensation_model.utils import bandpass_filter, align_ao_phase
from ao_compensation_model.validation import validate_prediction

Development

0. Install uv from Astral.
1. git clone git@github.com:lhharry/ao_compensation_model.git
2. make init — create virtual environment and install dependencies
3. make format — format code and run type checks
4. make test — run the test suite with coverage
5. make clean — delete temporary files and directories

Publishing

Pushing a version tag triggers automatic publishing to PyPI via GitHub Actions (Trusted Publishing):

# Update version in pyproject.toml, then:
git tag v0.x.x
git push origin --tags

Structure

├── src
│   └── ao_compensation_model
│       ├── __init__.py
│       ├── __main__.py
│       ├── app.py
│       ├── definitions.py
│       ├── gt_dataprep.py
│       ├── training.py
│       ├── txt2csv.py
│       ├── utils.py
│       ├── validation.py
│       ├── dataset/
│       └── model/
├── tests
│   ├── __init__.py
│   ├── conftest.py
│   ├── app_test.py
│   ├── gt_dataprep_test.py
│   ├── training_test.py
│   └── utils_test.py
├── .github/workflows/
├── CONTRIBUTING.md
├── Dockerfile
├── LICENSE
├── Makefile
├── README.md
└── pyproject.toml