Jump Test Analysis

Force-plate analysis toolkit for vertical jump testing, built around an engineer-friendly pipeline for detecting events, segmenting movement phases, computing biomechanics metrics, and exporting explainable results for APIs and visualization tools.

At a high level, this repository takes raw vertical ground reaction force (vGRF) data from force plates and turns it into structured outputs for three common jump-test families:

• Countermovement Jump (CMJ)
• Drop Jump (DJ)
• Squat Jump (SJ)

Background: What These Jump Tests Measure

For readers who want the sports-science context first:

• Vertical jump overview (Wikipedia)
• Countermovement jump overview and monitoring use case (PubMed meta-analysis)
• Drop jump / Reactive Strength Index context (PubMed)
• Drop jump performance validity against force plate measures (PubMed)

In practice:

• CMJ is used to assess jump performance, neuromuscular status, and force-time strategy during a countermovement.
• SJ isolates concentric intent more cleanly by removing the preparatory dip.
• DJ is commonly used for reactive strength and stretch-shortening-cycle assessment, especially through contact-time and RSI-style metrics.

Why This Project Exists

This project sits at the intersection of biomechanics and software engineering. The goal is not just to "calculate jump height," but to build a reusable analysis system that:

• accepts raw force-plate exports or in-memory payloads,
• detects meaningful biomechanical events robustly from noisy real-world data,
• computes physics-based metrics from those detections,
• packages results into a consistent JSON contract for downstream apps,
• supports debugging and interpretation through visualization and explainable outputs.

That design makes the repo useful both as an analysis engine and as a portfolio example of applied engineering in signal processing, numerical computing, API-oriented backend design, and domain-specific algorithm development.

Engineering Highlights

• Modular analysis architecture: data loading, detection, kinematics, metrics, export, and visualization are separated into focused modules under src/.
• Single API-style entry point: src/run_analysis.py dispatches by test_type and returns a unified payload shape across CMJ, DJ, and SJ.
• Typed domain models: dataclasses in src/data/types.py give the pipeline explicit structures for trials, events, and validity state.
• Robust detection logic: event detection uses sustained-threshold rules, morphology-aware peak/valley logic, and phase-aware validation rather than naive single-sample thresholding.
• Physics-based computation: metrics are derived from force, impulse, velocity, displacement, RFD, and bodyweight-normalized quantities instead of relying only on simple summary statistics.
• Explainable output contract: the exported payload includes both raw values and human-readable explanations via src/analysis_response.py.
• Tooling around the core pipeline: this repo includes CLI workflows, JSON export, a browser viewer, batch processing scripts, and synced video rendering for analysis/debugging.
• Research-to-code translation: the codebase captures domain rules such as contact timing, take-off/landing thresholds, structural peak logic, and classification heuristics in configurable, inspectable Python modules.

How The System Works

The core pipeline is:

1. Load raw trial data from JSON or an in-memory dict.
2. Estimate baseline bodyweight and sample rate.
3. Detect biomechanical events from the force-time signal.
4. Derive phase boundaries from those events.
5. Compute kinematics and performance metrics.
6. Build a normalized visualization/API payload with phases, key points, metrics, validity flags, and explanations.

That flow is implemented most directly in src/run_analysis.py.

Test-specific logic

• CMJ: detects movement onset, minimum force, eccentric end, velocity-zero transition, take-off, and landing; computes jump height, power, RFD, impulses, displacement, and asymmetry metrics.
• DJ: detects contact episodes, drop landing, peak impact, contact through point, start of concentric, peak drive-off, take-off, second landing, and landing peak; computes contact-time, RSI, braking/propulsive metrics, and reactive classification.
• SJ: detects quiet standing, contraction onset, optional countermovement contamination, peak force, take-off, landing, and landing peak; computes concentric-force metrics and classifies execution quality.

Repository Map

Core analysis code

• src/data/load.py: tolerant loaders for raw JSON and in-memory request payloads.
• src/data/types.py: typed dataclasses for trials, events, phases, and validity.
• src/detect/: event detection, baseline estimation, validity checks, and test-specific logic.
• src/physics/: kinematics, metrics, and left/right asymmetry calculations.
• src/export_viz.py: builds the JSON payload used by the viewer and by API consumers.
• src/analysis_response.py: attaches explanations and display ordering to outputs.
• src/config.py: configurable thresholds and detection settings.

Scripts and tooling

• script/main.py: main CMJ CLI workflow.
• script/export_dj_viz.py: batch export for DJ trials.
• script/export_sj_viz.py: batch export for SJ trials.
• script/serve_viewer.py: local HTTP server for browsing generated viewer JSON.
• script/render_sync_video.py: renders synchronized video + force-chart output.

Supporting assets

• web/viewer.html: standalone visualization UI for exported trials.
• docs/DETECTION_AND_METRICS.md: detailed CMJ detection and metric definitions.
• docs/DROP_JUMP_ANALYSIS.md: overview of the DJ pipeline and outputs.
• docs/DROP_JUMP_DETECTION_ALGORITHM.md: deeper algorithm notes for DJ.
• docs/SQUAT_JUMP_METRICS_AND_STATISTICS.md: squat-jump metrics and interpretation.

Input Data Contract

The pipeline expects JSON exports containing:

• athlete_id or name
• test_type
• test_duration
• force or total_force
• left_force
• right_force
• optional sample_count

The loader is intentionally tolerant:

• force and total_force are both accepted.
• sample_count is inferred if missing.
• arrays are trimmed to a consistent minimum length when needed.

This behavior is implemented in src/data/load.py, which reflects a backend-focused design: the code is written to absorb imperfect payloads without making integration fragile.

Output Contract

Each analysis returns a structured payload containing:

• time_s, force_N, left_force_N, right_force_N
• phases
• key_points
• events
• metrics
• validity
• analysis

The analysis block is especially useful for frontend or product integration because it maps phases, key points, and metrics to { value, explanation }, which makes the output easier to display, annotate, and debug.

Setup

python3 -m venv .venv
.venv/bin/pip install -r requirements.txt

Run The Project

1. Run the main CMJ CLI

PYTHONPATH=. .venv/bin/python script/main.py path/to/trial.json --export output/cmj_viz.json

Useful options:

• --no-plot
• --save chart.png
• --filter 50
• --take-off-threshold <N>
• --landing-threshold <N>
• --onset-below-bw <fraction>

2. Export all drop-jump trials

PYTHONPATH=. .venv/bin/python script/export_dj_viz.py saved_raw_data/dj-data

3. Export all squat-jump trials

PYTHONPATH=. .venv/bin/python script/export_sj_viz.py saved_raw_data/sj-data

4. Open the viewer locally

PYTHONPATH=. .venv/bin/python script/serve_viewer.py --port 8000

Then open http://localhost:8000.

Using It As A Backend / API Component

The cleanest integration point is src/run_analysis.py:

from src.run_analysis import run_analysis

payload = run_analysis({
    "athlete_id": "example-athlete",
    "test_type": "DJ",
    "test_duration": 2.5,
    "total_force": [...],
    "left_force": [...],
    "right_force": [...],
})

This returns a ready-to-serve JSON-like dict and avoids file I/O, which is exactly the kind of interface you want when connecting force-plate hardware or analysis services to a web or mobile application.

Visualization and Debugging

One of the strongest engineering aspects of this repo is that the analysis does not stop at metric computation. It also provides tooling for inspection:

• JSON exports for browser-based review
• phase shading and key-point overlays in the viewer
• comparison-friendly payloads
• synced video rendering for force-data verification

That is valuable in real engineering settings because signal-processing systems are hard to trust if they cannot be visualized and debugged against the underlying waveform.

Software Engineering Skills Demonstrated

This project showcases practical engineering skills in:

• numerical computing with NumPy and SciPy
• signal-processing-oriented algorithm design
• thresholding and morphology-based event detection
• clean pipeline decomposition and separation of concerns
• API-first backend design
• typed Python data modeling with dataclasses
• explainable analytics output design
• domain-driven module organization
• CLI and visualization tooling for developer workflows
• translating biomechanics concepts into reproducible software logic

Suggested Reading Order For Engineers

If you are reviewing the repo as an engineer, this order gives the fastest understanding:

1. src/run_analysis.py
2. src/data/load.py
3. src/detect/
4. src/physics/metrics.py
5. src/export_viz.py
6. web/viewer.html
7. docs/DETECTION_AND_METRICS.md

Notes

• The repo currently contains sample raw data and generated output under saved_raw_data/ and output/.
• The main CLI path is centered on CMJ, while DJ and SJ are exported through dedicated scripts and all three are supported through the in-memory API entry point.
• The existing documentation in docs/ goes deeper into the biomechanics details; this README is intended to make the repository easy to understand quickly for engineering reviewers, recruiters, collaborators, or portfolio visitors.