MoonBit Gait Lab: A gait analysis and metrics library for running, postoperative rehabilitation, and elderly screening.

gait

biomechanics

analysis

sports

rehabilitation

moon add hgetty/gaitlab@0.1.1

Download zip

Author

hgetty

Version

0.1.1

License

Apache-2.0

Repository

github.com/hgetty/moonbit-gaitlab

Last updated

1 hour ago

Downloads

README

#MoonBit GaitLab

MoonBit GaitLab is a dependency-light toolkit for turning joint trajectories into reproducible gait-analysis results. It provides validated data ingestion, signal conditioning, gait-cycle metrics, bilateral symmetry analysis, quality diagnostics, screening rules, and machine-readable reports.

The library is intended for rehabilitation studies, sports-science experiments, and repeatable local data pipelines. Its screening output is an analysis aid, not a medical diagnosis.

#Why GaitLab

Gait data is useful only when the pipeline makes invalid samples visible and produces the same result for the same input. GaitLab keeps input validation, numerical processing, biomechanical metrics, quality gates, and reporting as separate layers so an application can adopt the pieces it needs.

#Highlights

Layer	What it provides
Data	RFC-style CSV parsing, typed tables, schemas, JSON accessors, validation, transformation, and stable exports
Numerics	Statistics, geometry, interpolation, matrices, robust estimators, time-series utilities, and vector operations
Signals	Smoothing, robust filters, derivatives, event detection, correlation, frequency features, segmentation, and windows
Trajectories	Time-axis checks, resampling, unit conversion, alignment, coordinate transforms, features, and quality rules
Gait	Cycle segmentation, temporal/spatial metrics, symmetry, variability, reference ranges, balance, and explainable screening
Pipeline	Strict or lenient analysis, batch processing, diagnostics, caching keys, readiness gates, invariants, and structured results
Reports	Markdown, JSON, CSV, text, TSV, dashboard, and accessibility-oriented summaries

#Quick start

Install the current stable MoonBit toolchain, then run the portable local checks:

moon update
moon fmt --check
moon check --deny-warn --target all
moon test --deny-warn --target wasm-gc
moon test --deny-warn --target js
moon run main -- --demo

The demo is deterministic and uses an in-memory trajectory; no external dataset is required. On Unix hosts, the native backend can also be checked with:

moon test --deny-warn --target all

#CLI

The executable accepts a demo trajectory or raw CSV/JSON data:

moon run main -- --help
moon run main -- --demo
moon run main -- --demo --format json
moon run main -- --demo --format csv
moon run main -- --demo --strict --sampling-rate 100

markdown is the default report format. json and csv produce machine-readable output suitable for scripts and downstream pipelines.

#CSV input

The CLI accepts a header followed by rows using this stable mapping:

time,hip_x,hip_y,hip_z,knee_x,knee_y,knee_z,ankle_x,ankle_y,ankle_z,foot_x,foot_y,foot_z

Example:

$csv = @'
time,hip_x,hip_y,hip_z,knee_x,knee_y,knee_z,ankle_x,ankle_y,ankle_z,foot_x,foot_y,foot_z
0,0,0.9,0,0,0.5,0,0,0.1,0,0,0,0
0.01,0.01,0.9,0,0.01,0.5,0,0.01,0.1,0,0.01,0,0
'@
moon run main -- --csv-data $csv --format json

#JSON input

JSON input expects a top-level frames array. Each frame contains a numeric time and a left_foot point:

{
  "frames": [
    {"time": 0.00, "left_foot": {"x": 0.00, "y": 0.00, "z": 0.00}},
    {"time": 0.01, "left_foot": {"x": 0.01, "y": 0.00, "z": 0.00}}
  ]
}

moon run main -- --json-data '{"frames":[{"time":0,"left_foot":{"x":0,"y":0,"z":0}},{"time":0.01,"left_foot":{"x":0.01,"y":0,"z":0}}]}' --format json

Both input paths are converted into JointFrame values and passed through the same validation, analysis, and report pipeline as the built-in demo.

#API

The reusable packages can be imported independently of the CLI. A compact API example is available in README.mbt.md. The central pipeline call is:

let result = @pipeline.analyze_frames(
  left_frames,
  right_frames,
  @pipeline.default_config(),
)

Use @pipeline.has_fatal_diagnostics(result) before consuming a report in strict applications. The report layer then supports stable format selection through @report.render_report(result.report, "json") or another supported format.

#Architecture

CSV / JSON / API values
          │
          ▼
trajectory validation → units → alignment → resampling
          │
          ▼
signal conditioning → events → gait cycles
          │
          ▼
temporal/spatial metrics → symmetry → quality and screening
          │
          ▼
pipeline diagnostics and readiness gates
          │
          ▼
Markdown / JSON / CSV / text reports

Package	Responsibility
lib/math	Numeric primitives, geometry, matrices, robust statistics, and time series
lib/csv	CSV parser, tables, typed columns, validation, grouping, and exports
lib/json	JSON AST, accessors, formatting, validation, transforms, and visitors
lib/signal	Filtering, derivatives, events, correlation, frequency, and windows
lib/trajectory	Time axes, trajectory quality, units, alignment, transforms, and features
lib/gait	Cycles, gait metrics, variability, balance, reference rules, and explainability
lib/pipeline	Configuration, orchestration, diagnostics, batch analysis, readiness, and invariants
lib/report	Human- and machine-readable report renderers
main	CLI parsing and deterministic demo

#Benchmarks

The benchmark runner builds a deterministic signal-and-gait workload in release mode, runs it as repeated processes, and records wall-clock time plus workload checksums:

pwsh -File scripts/run_benchmark.ps1 -Target wasm-gc -Runs 3 -Iterations 5

For native measurements on a working Unix C toolchain:

pwsh -File scripts/run_benchmark.ps1 -Target native -Runs 5 -Iterations 20

The checked-in benchmark report records a wasm-gc release run with three process measurements: 94.001 ms, 88.020 ms, and 89.737 ms. The signal and gait checksums were identical across runs. These are reproducibility observations, not hardware-independent performance guarantees.

#Tests and source audit

The test suite covers malformed and empty input, timestamp ordering, invalid dimensions, zero and oversized windows, constant signals, boundary padding, event confidence, strict pipeline behavior, report formats, deterministic workloads, and CLI format boundaries.

moon test --deny-warn --target wasm-gc
moon test --deny-warn --target js

The source audit counts non-empty, non-comment production .mbt lines. Tests, benchmarks, generated metadata, and build directories are excluded:

pwsh -File scripts/audit_source_scale.ps1 -MinimumProductionLines 8000

#Continuous integration

GitHub Actions runs on Ubuntu, macOS, and Windows. Every job installs the current stable MoonBit toolchain, updates dependencies, checks formatting, checks all targets with warnings denied, verifies package metadata, exercises the CLI, and runs the production source audit.

Unix jobs run all-target and native tests.
Windows runs the wasm-gc and JavaScript backends so hosted C-toolchain differences do not mask portable project verification.

See .github/workflows/check.yml.

#Project layout

lib/                    reusable MoonBit packages
main/                   CLI executable
benchmarks/             deterministic workloads and measurements
scripts/                local audit and benchmark automation
data/                   sample input data
.github/workflows/      continuous integration

#License

MoonBit GaitLab is licensed under the Apache License, Version 2.0.

Site source Report issue Packages Build queue Skills Statistics