Contribute code from GitHub
Metrics, modules and coded dashboards: source in GitHub, pinned versions in your organization library.
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.
| Concern | Where |
|---|---|
| Source and review | GitHub, in any repository: yours or the MotionCommons repository |
| Published version | An immutable version in your organization library, pinned by pipelines and dashboards |
| Provenance | The GitHub repository, commit and path, recorded with every published version |
| Runs | Your organization’s machines execute the pinned copy, never a later push |
| Data and results | Stay 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.
@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.
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