DocumentationMotionCommons · Developer preview

Contribute code from GitHub

Implemented locally

Metrics, modules and coded dashboards: source in GitHub, pinned versions in your organization library.

Docs/Build extensions
Ask Claude

Contribute code from GitHub

Page Markdown

The complete guide, ready to copy or save as a Markdown file.

Download .md ↓

Where your code lives

Publishing refuses files with uncommitted changes, unpushed commits and repositories whose origin is not on GitHub. The library keeps a frozen copy of that commit, so a deleted repository, a force-push or a GitHub outage never changes a past or future run.

ConcernWhere
Source and reviewGitHub, in any repository: yours or the MotionCommons repository
Published versionAn immutable version in your organization library, pinned by pipelines and dashboards
ProvenanceThe GitHub repository, commit and path, recorded with every published version
RunsYour organization’s machines execute the pinned copy, never a later push
Data and resultsStay under the existing access rules; publishing code shares no data

Add a trial metric

One decorated function per metric, with at least one synthetic example whose answer you can check by hand. Inputs keep their original units: degrees for rotations and metres for translations or marker positions. Raise NotApplicable with a short reason when a trial does not fit; never return a substitute value.

Create a file with uv run --frozen hb metric new my-lab/peak-hip-flexion and check it with uv run --frozen hb metric check my_metric.py. Each check runs the examples through the same runner that machines use.

python
@metric(
    "my-lab/peak-hip-flexion",
    version="1.0.0",
    label="Peak hip flexion (right)",
    unit="deg",
    description="Maximum hip_flexion_r over the trial, unfiltered. Not clinically validated.",
    source="kinematics",
    examples=[Example(Kinematics([0, 1], {"hip_flexion_r": [3.0, 41.0]}), expected=41.0)],
)
def peak_hip_flexion(data: Kinematics) -> float:
    return max(data.coordinate("hip_flexion_r"))

Publish to your organization

A metric becomes a module with a trial input and a metric output, plus a "Compute …" pipeline that runs it on a machine. Add --dry-run to package and check without publishing.

Published versions start Organization-only. Their owners can switch them to Public; that shares the code, never patient data.

Reviewed core metrics built into MotionCommons also appear in the OpenCap trial metrics table. Published metrics run as pipelines and are not yet added to that table automatically.

sh
uv run --frozen hb agent login
uv run --frozen hb metric publish my_metric.py --organization ORG --study PROJECT
uv run --frozen hb block publish module.json --code module.py --organization ORG --study PROJECT
uv run --frozen hb dashboard publish path/to/folder --organization ORG

Accessibility

Make every MotionCommons page comfortable for you. Settings apply on this browser.

Text size

Your training, at your pace.

Reading & movement
Audio support

Spoken audio is unavailable in this browser. All instructions remain available as text.

Read this page speaks up to 1,800 characters of visible page text. Embedded dashboards have their own Read dashboard button.