micromotion 0.6.0__tar.gz

micromotion-0.6.0/.github/workflows/docs.yml

@@ -0,0 +1,30 @@
+name: docs
+on:
+  push: { branches: [main] }
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+concurrency:
+  group: pages
+  cancel-in-progress: false
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with: { python-version: "3.12" }
+      - run: pip install -e . mkdocs-material mkdocstrings[python]
+      - run: mkdocs build --strict
+      - uses: actions/upload-pages-artifact@v3
+        with: { path: site }
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - id: deployment
+        uses: actions/deploy-pages@v4

micromotion-0.6.0/.github/workflows/publish.yml

@@ -0,0 +1,54 @@
+name: publish
+
+# Publishes to PyPI when a GitHub release is published. Authentication is by PyPI Trusted
+# Publishing (OIDC), so there is no API token to store or rotate: PyPI is configured to trust
+# this repository, this workflow file and the `pypi` environment, and nothing else.
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with: { python-version: "${{ matrix.python-version }}" }
+      - run: pip install -e ".[test]"
+      - run: pytest -q
+
+  build:
+    needs: test
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with: { python-version: "3.12" }
+      - run: pip install build
+      - run: python -m build
+      # Fail here rather than at upload if the version and the tag disagree.
+      - name: Check the built version matches the release tag
+        run: |
+          version=$(ls dist/*.tar.gz | sed -E 's/.*micromotion-(.*)\.tar\.gz/\1/')
+          tag="${GITHUB_REF_NAME#v}"
+          test "$version" = "$tag" || {
+            echo "pyproject version $version does not match release tag $tag"; exit 1; }
+      - uses: actions/upload-artifact@v4
+        with: { name: dist, path: dist/ }
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/micromotion
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with: { name: dist, path: dist/ }
+      - uses: pypa/gh-action-pypi-publish@release/v1

micromotion-0.6.0/.github/workflows/tests.yml

@@ -0,0 +1,16 @@
+name: tests
+on:
+  push: { branches: [main] }
+  pull_request:
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with: { python-version: "${{ matrix.python-version }}" }
+      - run: pip install -e ".[test]"
+      - run: pytest -q

micromotion-0.6.0/.gitignore

@@ -0,0 +1,11 @@
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.ruff_cache/
+*.egg-info/
+build/
+dist/
+.venv/
+.DS_Store
+
+site/

micromotion-0.6.0/CHANGELOG.md

@@ -0,0 +1,113 @@
+# Changelog
+
+## 0.6.0
+
+First release published to PyPI.
+
+**The lower band edge moved from 0.3 Hz to 0.2 Hz, and every number this package produces changes
+with it.** 0.3 was inherited rather than chosen. Swept across seven optical datasets and 665
+recordings, the between-dataset spread is 3.2 per cent at 0.15 Hz, 2.1 at 0.20, 2.7 at 0.25, 6.2
+at 0.30 and 10.1 at 0.40. 0.2 is a clear optimum and is where the 20 Hz origin dataset stops being
+an outlier in either direction. Checked against the failure this edge exists to prevent: on
+accelerometer data the mean-to-median speed ratio, which rises when integration drift leaks in, is
+2.07 at 0.2 Hz against 2.00 at 0.3 — flat, so integration is safe. Absolute values rise about 73
+per cent because more low-frequency content is kept.
+
+One real cost, now under test: the filter transient runs 40 s at each end rather than 27, so a
+recording under about two minutes has no clean interior at all.
+
+- `bandpass` warns when the sampling rate exceeds the upper band edge by more than 40:1. Porting
+  the analysis scripts turned up a filter that is wrong in published work rather than merely
+  different: a 0.1–0.5 Hz third-order band-pass at 250 Hz, written the usual way as
+  `butter(3, [lo/ny, hi/ny])` with `filtfilt`, has a largest pole radius of 0.9979 and a measured
+  passband gain of 0.84 at 0.15 Hz where it should be 0.99. Nothing raises and nothing looks
+  wrong; every amplitude downstream is sixteen per cent low. This package uses second-order
+  sections and was never affected, but it accepted such a band silently, and a caller designing
+  their own filter deserves to be told. The warning names the fix, which is to decimate first.
+- `bandpass` and `lowpass` take a `margin` argument. The upper edge was pinned at 0.99 of Nyquist
+  with no way to change it, and the Still Standing corpus uses 0.999 throughout, so no script
+  written against that convention could be ported.
+- `detect_breaths_adaptive`, added with its benchmark and an explicit note not to default to it.
+  The expectation was that rejecting chest rises which never cross an adaptive baseline would beat
+  plain peak detection. Measured, it does not: on twelve belt recordings the two agree, and on
+  eight chest accelerometers — the case the rejection was meant to help — it over-counts badly,
+  10.3 breaths/min against 3.6 for the peak-based detector.
+- The balance readers are described by content rather than by a `.tsv` extension they no longer
+  have.
+
+164 tests.
+
+## 0.5.0
+
+The integration rule used to turn acceleration into speed is now selectable, and it was hiding a
+systematic 0.26 per cent. This package integrated with a rectangle sum; the StillStanding365 and
+fNIRS pipelines use the trapezoid rule, and on real phone data the two differ consistently because
+the rectangle sum lags the signal by half a sample.
+
+Both are available. The default stays rectangle, and not because it is the better rule — it is
+not. It is what the harmonised cross-collection table and every figure derived from it were
+computed with, and it reproduces the deposited Taqasim value, 93.140 against 93.091 mm/s, where
+trapezoid gives 93.405. Changing the default would silently invalidate numbers already published.
+Which rule the project standardises on is left open.
+
+## 0.4.0
+
+Added `group`, for the question everything else here could not ask. The rest of the package
+describes one recording or relates a pair; this answers whether a room full of people moved at the
+same moments.
+
+- `event_train` — continuous signal to point process, thresholded relative to each person's own
+  variability, so a quiet participant and a loud one both register events.
+- `coincidence_test` — surrogates shift each person by an independent bounded random offset, so
+  every individual keeps their own event rate and local structure and only the between-person
+  alignment is destroyed.
+- `participation_ratio` — the fraction of people whose motion fell after an event. Sign-based, so
+  sensors differing by an order of magnitude do not shift it.
+
+## 0.3.0
+
+Absorbed the quantity-of-motion modules from `musicalgestures`, whose unreleased main branch
+carried `band_limited_qom`, `accel_to_speed`, `read_qtm_tsv`, `cop_sway_metrics` and
+`respiration_rate`, all credited in their docstrings to the same source study as this package.
+Rather than ship a competing fifth implementation of the project's central measure, they move here
+and MGT depends on micromotion.
+
+MGT's behaviour is preserved exactly rather than silently reconciled. `band_limited_qom` still
+defaults to a 0.3–15 Hz band, differentiates with a two-point difference and does not band-limit
+again afterwards; on a 200 Hz optical recording it still returns 5.675 mm/s against 5.455 for this
+package's `qom()`. They are different measures and are documented as such.
+
+## 0.2.0
+
+Added the function families an audit against the source study's 159 analysis scripts found
+missing.
+
+- `align` — offset recovery between recordings sharing no clock, by cross-correlation or
+  direct search, plus instantaneous rate tracking and transient detection. Reproduces the
+  fNIRS session's 126.0 s offset, which the deposited sync clap independently confirms.
+- `circular` — mean direction, Rayleigh and its axial form, V test, circular and
+  circular-linear correlation, axial dispersion.
+- `posture` — sway anisotropy and principal axis, 95 per cent confidence ellipse, path
+  length, dispersion radius.
+- `spectral` — peak with signal-to-noise ratio, band RMS, band power fractions, mean
+  frequency, breath detection.
+- `dynamics` — approximate entropy, detrended cross-correlation.
+- `resample` — short-gap interpolation with a stated ceiling, and gap reporting.
+- `qom` — tilt decomposition made public, with `tilt_fraction`.
+
+`xcorr_lag` now differences its inputs by default. Correlating two drifting series and taking
+the best lag is the spurious-regression trap: over 200 independent random-walk pairs the
+best-lag correlation had a median of 0.47, exceeded 0.5 forty per cent of the time and
+reached 0.98 at worst. Differenced, the same pairs never passed 0.16.
+
+89 tests.
+
+## 0.1.0
+
+First release. Filters, quantity of motion, resampling, spectral peaks, dynamics, seven
+readers and a common record type, extracted from 159 analysis scripts in which 58 defined
+their own band-pass filter and 37 computed quantity of motion.
+
+Restores two validations that had been lost: the time-reversal test returns z = +0.85 on an
+AR(1) process and z = -41 on a logistic map. A report stated both; no script implementing
+them had survived.

micromotion-0.6.0/CITATION.cff

@@ -0,0 +1,25 @@
+cff-version: 1.2.0
+title: "micromotion: analysis of human micromotion in motion time series"
+message: "If you use this software, please cite it."
+type: software
+authors:
+  - family-names: Jensenius
+    given-names: Alexander Refsum
+    orcid: "https://orcid.org/0000-0003-4703-9411"
+    affiliation: "RITMO Centre for Interdisciplinary Studies in Rhythm, Time and Motion, University of Oslo"
+repository-code: "https://github.com/fourMs/micromotion"
+abstract: >-
+  One implementation of quantity of motion — the average speed of a body part,
+  band-limited to 0.2-10 Hz, in millimetres per second — for optical marker data,
+  body-worn accelerometers and force-plate centre of pressure, together with the
+  readers, resampling rules, scaling measures and alignment methods that surround it.
+keywords:
+  - micromotion
+  - standstill
+  - quantity of motion
+  - motion capture
+  - accelerometer
+  - postural sway
+license: GPL-3.0-or-later
+version: 0.6.0
+date-released: "2026-07-30"