Metadata-Version: 2.4
Name: imuops
Version: 0.3.1
Summary: IMU data QA, reliability scoring, and reproducibility tooling
Author: Boz Liu
License: MIT
License-File: LICENSE
Keywords: benchmark,data-quality,har,imu,pdr,qa,sensor-fusion,wearable
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Requires-Python: >=3.11
Requires-Dist: ahrs>=0.3.1
Requires-Dist: h5py>=3.11.0
Requires-Dist: jinja2>=3.1.4
Requires-Dist: numpy>=1.26.0
Requires-Dist: openpyxl>=3.1.0
Requires-Dist: pandas>=2.2.0
Requires-Dist: plotly>=5.24.1
Requires-Dist: pyarrow>=15.0.0
Requires-Dist: pydantic>=2.8.2
Requires-Dist: pyyaml>=6.0.2
Requires-Dist: requests>=2.32.0
Requires-Dist: scikit-learn>=1.5.2
Requires-Dist: typer>=0.12.0
Provides-Extra: dev
Requires-Dist: pytest-cov>=5.0.0; extra == 'dev'
Requires-Dist: pytest>=8.2.0; extra == 'dev'
Description-Content-Type: text/markdown

# imuops

`imuops` is a public alpha for **IMU data QA, reliability scoring, and reproducibility**.

It is built around one core question:

> Is this IMU data trustworthy, why is it failing, and how does that affect baseline algorithms?

The product is intentionally **tabular-first**. The main path is customer-shaped `csv`, `tsv`, or `parquet` data plus a small YAML mapping file. Benchmark adapters stay in the repo for reproducibility demos, but they are secondary to the tabular workflow.

## Status

- alpha / preview release
- main product path: `tabular`
- benchmark/demo adapters: `ronin`, `oxiod`, `wisdm`
- local-only contrib adapter: `legacy_arduino`

Benchmark adapters are validated on fixtures and demo flows. They are not guaranteed across every upstream packaging or layout variant.

## Install

Requires Python 3.11+.

Primary public path:

```bash
python3.12 -m venv .venv
source .venv/bin/activate
pip install .
```

Use any Python 3.11+ interpreter available on your machine.

Optional `uv` path:

```bash
uv venv
source .venv/bin/activate
uv pip install .
```

`imuops` is prepared for PyPI publication, but this alpha does not claim a live PyPI package yet.

## Quickstart

After install, the offline first-run path is exactly three commands:

```bash
imuops ingest tabular examples/sample_tabular_imu.csv --config examples/sample_tabular_config.yaml --out output/sample_tabular_demo
imuops audit output/sample_tabular_demo --summary-format markdown
imuops report output/sample_tabular_demo --out output/sample_tabular_demo/report.html
```

You can also use the bundled demo wrapper:

```bash
bash examples/run_tabular_demo.sh
```

## What It Does

- normalizes messy IMU tables into one canonical session format
- audits timing, clipping, dropout, magnetic disturbance, bias drift, and related issues
- computes a versioned `trust_score` with explicit penalties, weights, and thresholds
- replays conservative baseline algorithms for orientation and PDR reproducibility
- benchmarks task-aware baselines where labels or trajectories exist
- compares clean vs corrupted or before vs after sessions
- batches QA over many sessions and writes machine-readable summaries for CI use

## Core Commands

```bash
imuops ingest tabular /path/to/session.csv --config /path/to/mapping.yaml --out output/session_a
imuops audit output/session_a --fail-below 0.80 --summary-format markdown
imuops export output/session_a --profile qa_filtered --format parquet --out output/session_a_clean
imuops compare output/session_a output/session_b --out output/compare.html
imuops batch audit output --out output/batch_artifacts
```

## Included Adapters

### Market-facing default

- `tabular`: customer-shaped `csv`, `tsv`, and `parquet` sources with YAML mapping and unit conversion

### Benchmark/demo adapters

- `ronin`: clean inertial odometry benchmark sessions
- `oxiod`: clean handheld / phone inertial odometry benchmark sessions
- `wisdm`: lightweight HAR benchmark sessions

### Contrib/local regression

- `legacy_arduino`: historical Arduino/MPU9255 adapter kept only for local regression and examples

## Trust Score

`imuops` publishes the trust-score contract directly into artifacts and reports:

- per-window formula
- session aggregation formula
- penalty totals
- weight profile
- thresholds

That is documented in [docs/trustscore.md](docs/trustscore.md), and the current validation tranche is in [docs/trustscore_validation.md](docs/trustscore_validation.md).

## Docs

- [Architecture](docs/architecture.md)
- [Datasets](docs/datasets.md)
- [Trust Score](docs/trustscore.md)
- [Trust-Score Validation](docs/trustscore_validation.md)
- [Schema Compatibility](docs/schema_compatibility.md)
- [Release Checklist](docs/release.md)
- [Contributing](CONTRIBUTING.md)

## Public Alpha Notes

- This repo is a **truthful alpha**, not a commercial deployment claim.
- Reports support `--redact-source-path` and `--redact-subject-id` for safer sharing.
- Output quality is strongest for tabular customer data and fixture/demo benchmark layouts.

## License

[MIT](LICENSE)
