Home
Practical notes for people using micromotion: things that are useful to know but that change independently of a release, and things too specific or too opinionated for the reference documentation.
The reference documentation, which covers installation, the API, and an explanation of every method with its citation, lives at fourms.github.io/micromotion. Start there when new. Come here when something has gone wrong, or to find out why a default is what it is.
| Page | What is on it | Read it when |
|---|---|---|
| Traps | mistakes made in real analyses, grouped by cause, with the measurements from each case | a number looks plausible and something feels wrong |
| Recipes | worked examples for questions that come up repeatedly | there is a task to do and a starting point would help |
| Design decisions | where a default came from, what is still unsettled, and where this package deliberately disagrees with another | a figure is about to be published, or numbers are being compared against someone else's |
| This page | the map, the one-paragraph summary, and how to contribute | first visit |
Traps and Design decisions cover some of the same ground from opposite directions. Traps says what goes wrong and how to avoid it; Design decisions says which choice the package made and why. Where both touch a subject, Traps carries the measurements and Design decisions links to them.
Quantity of motion is the average speed of a body part, band-limited to 0.2–5 Hz (mm.BAND),
in millimetres per second. Jerk and other high derivatives use mm.WIDEBAND, 0.2–10 Hz,
wherever the sampling rate can deliver it. Compute it with mm.qom(data, fs, kind=..., unit=...).
Read files with mm.read(path), which dispatches on content rather than on the file extension.
Validate before trusting anything: mm.validate.validate_series(...). Compare across datasets
only after mm.to_rate(x, fs, mm.HARMONISED_RATE), and only within a matching body placement
and a matching task instruction, since those two constrain comparability far more than any
filter choice does. That last point surprises most new users, and the last section of
Traps gives the measured spread across instructions and placements, which is larger
than people expect.
That figure is why this is one package rather than three: one synthetic body motion read as optical position, as worn acceleration, and at half the sampling rate gives medians within 2.6 per cent of each other.
It is also why the paragraph above ends the way it does. Those three series come from ONE trajectory, so nothing differs except the pipeline — which makes the figure a poor guide to whether two REAL recordings can be compared. Placement and instruction move a real number far more than any of this does.
pip install micromotion. The current version is the one on
PyPI and in the repository's pyproject.toml. It is
deliberately not named on this page, which cannot be kept in step with a release. Print
mm.__version__ and mm.BAND before trusting a batch of results, since the environment is part
of the result.
Issues and pull requests at fourMs/micromotion. A case where a default here gives a misleading answer is the most useful kind of issue to file, since most of the defaults exist because someone hit exactly that.
Separate packages with separate release cycles, built to be used together and sharing several implementations, so the same measure computed in two of them agrees.
This package owns circular statistics for the family. From ambiscape 0.40.0,
ambiscape.circstats.circ_corr is a re-export of micromotion.circular.circ_corr
rather than a second copy: the two had carried the same Jammalamadaka–SenGupta
formula under one name and returned different types, a float against a dict, so a
caller who swapped the import got an object where a number belonged. ambiscape
imports it lazily and declares it as its circular extra, so ambiscape still
installs without micromotion --- only entrain.directional_correlation needs it.
| Toolbox | What it is for | Docs |
|---|---|---|
Musical Gestures Toolbox (musicalgestures) |
video and audio: motiongrams, videograms, motion analysis from ordinary video | wiki |
| ambiscape | soundscapes: the sonic ambience of a place | wiki |
| musiscape | music collections: comparing many tracks and albums | wiki |
The package is archived on Zenodo. Cite the CONCEPT DOI, which always resolves to the newest version: 10.5281/zenodo.21948988.
Where the exact behaviour matters, name the version you ran as well — version 1.12.1 is
10.5281/zenodo.21948989. CITATION.cff in the
repository carries the same information in machine-readable form.