micromotion

A Python package for measuring human micromotion: the small movement of a body that is standing, sitting or otherwise trying to stay still. It reads optical marker data, body-worn accelerometers, respiration belts and force plates, and reduces all of them to one measure.

That measure is quantity of motion: the average speed of a body part, band-limited to 0.2–5 Hz, in millimetres per second.

It can be computed from every sensor family, because the shared abstraction is the frequency band rather than the device. One synthetic body motion, read three ways — as optical position at 100 Hz, as the acceleration a worn sensor would report, and as position sampled at 50 Hz — gives medians of 2.29, 2.35 and 2.29 mm/s, a spread of 2.6 per cent.

Both figures are real output, regenerated by docs/img/make_figures.py on synthetic signals whose answer is known.

Install

pip install micromotion

Python 3.10 or newer, with numpy, scipy and pandas. There is no computer-vision or audio stack to install.

Quickstart

import micromotion as mm

rec = mm.read("mocap_data/A0001.tsv")      # dispatches on content, not on the extension
head = rec.marker("P01")                   # (n_samples, 3), gaps already NaN
result = mm.qom(head, rec.fs, kind="position", unit=rec.unit)

print(result.median_mm_s, result.mean_mm_s)

Report the median, and say that it is the median. The mean and the median can rank the same recordings differently, so both are returned and neither is chosen for the caller.

Do not name a local variable mm. The conventional alias collides with a mean and with a value in millimetres, and rebinding it replaces the package for the rest of the file.

Documentation

Read Getting started first, then The three bands, which is the one convention that cannot be skipped. Reading files covers what each reader handles, which axis is vertical in which system, and the traps that produce plausible numbers rather than errors.

What is in it

Readers: Qualisys and Qualisys-style TSV in all three header shapes, Sverm, Axivity AX3, Physics Toolbox phone logs, Equivital, Wii balance board, and Artinis fNIRS. read dispatches on content rather than on extension, because in this field the extension is frequently wrong.

Licence and credit

GPL-3.0-or-later. Built at the fourMs lab, RITMO Centre for Interdisciplinary Studies in Rhythm, Time and Motion, University of Oslo. If you use the package, please cite it—see CITATION.cff—and cite the underlying methods too, since the Methods page gives a reference for each.

Issues and pull requests are welcome at fourMs/micromotion. A case where a default here gives a misleading answer is the most useful kind of issue to file.

The four toolboxes

Four packages from the fourMs lab, each released separately on PyPI. Which one you want is decided by what you have in hand rather than by what you want to know:

Where a measure appears in more than one package it has a single owner and a single implementation, so the answer does not depend on which package you called. This package is the owner for filtering, lag estimation and circular statistics, and it is the root of the family: it depends on none of the others, needing only numpy, scipy and pandas. musicalgestures and musiscape both require it. ambiscape does not, keeping its own copy of six short circular-statistics primitives so that it installs alone, held equal to this package's by a test on its side.

Being the owner is a responsibility rather than a rank. align.xcorr_lag returned the opposite of the sign it documented until 1.13.0, and what caught it was comparing against musicalgestures.xcorr_lag, which had been right all along.

Citing

Cite the CONCEPT DOI, which always resolves to the newest version:

Jensenius, A. R., Upham, F., Zelechowska, A., Gonzalez-Sanchez, V. E., Swarbrick, D., & Riaz, M. (2026). micromotion: analysis of human micromotion in motion time series (Version 1.12.2) [Computer software]. Zenodo. https://doi.org/10.5281/zenodo.21953120

Where the exact behaviour matters, cite the version you ran instead. This package HAS changed behaviour at releases — read_phone at 0.15.0, group_qom at 1.0.0, to_rate at 1.2.2 — so which version produced a number is part of the method. Version 1.12.2 is https://doi.org/10.5281/zenodo.21953121.

An older concept DOI, https://doi.org/10.5281/zenodo.21948988, is frozen at 1.12.1. It was created by a hand deposit made before the Zenodo GitHub integration was archiving this repository, and Zenodo cannot merge two concepts; that record says so itself and points here. Cite the DOI above.

CITATION.cff in this repository carries the same information in machine-readable form.