Open questions

Open questions

Unresolved decisions that affect numbers people report. Each is recorded here rather than settled silently.

1. Which band the project states

Two conventions, differing by 15.5 per cent on identical optical data:

• 0.3–10 Hz band-pass — usable on every sensor; across seven independent optical datasets the median head speed converges to 4.42 mm/s with a 3.5 per cent spread.
• 10 Hz low-pass, no lower edge — the convention behind most published figures; the same datasets spread 5.9 per cent.

The band-pass gives the tighter invariant and is the only one an accelerometer can confirm. The low-pass is what is in print. This is an editorial decision about published work, not a technical one.

2. Overlap with MGT — RESOLVED 2026-07-29

Decided: the modules move here and MGT depends on this package. Done in fourMs/MGT-python#362, which is open for review. MGT's 53 tests are vendored under tests/mgt/ and pass unmodified, so the guarantee that its numbers did not change keeps holding.

One piece is deliberately unresolved. axial_rayleigh as absorbed from MGT returns R = 0.9985 where circular.rayleigh_axial returns 0.9222 for the same bimodal input. Only the latter matches the textbook resultant length of the doubled angles, so MGT's looks wrong — but it is the one under test, and changing it would change published numbers. Needs its own fix.

The original analysis follows.

Background

MGT's unreleased main branch already contains band_limited_qom, accel_to_speed, read_qtm_tsv, cop_sway_metrics and respiration_rate, credited in their docstrings to the same source study as this package. They are absent from the released 1.6.9.

The implementations disagree. On one 200 Hz optical recording:

	mean speed
MGT band_limited_qom, 0.3–15 Hz default	5.675 mm/s
MGT band_limited_qom, forced to 0.3–10 Hz	5.594 mm/s
micromotion.qom, 0.3–10 Hz	5.455 mm/s

MGT's default band reaches to 15 Hz rather than 10, it differentiates with a two-point difference, and it does not band-limit again after differentiating. Three possible resolutions:

1. Publish MGT's pending release and have micromotion depend on it. Costs a 282 MB dependency including opencv for anyone analysing accelerometer data.
2. Extract those modules out of MGT into micromotion and have MGT depend on this package instead. Matches the existing MGT → ambiscape arrow, where the heavy package depends on the light one and never the reverse.
3. Scope micromotion to what MGT genuinely lacks — the readers, the resampling rules, the alignment module, circular statistics.

Option 2 fits the stated architecture. Until it is decided, state which package produced any number you report.

3. PyPI, and what depends on it

Not published. This is load-bearing rather than administrative: deposited research datasets have to run standalone for someone who downloads only that record, so they cannot import a package that is not installable. Their own copies of these functions therefore stay, verified numerically against this package rather than replaced by it.