benjamin_repeated_jump

In this experiment, we collect motion, force and emg data of participants while they perform a rebound-jumping exercise. This repository compiles all necessary files to read in the data, complete the analysis, and create the necessary figures.

Setting up

Set up the conda environment

For this project, it is suggested to use the Kinetics Toolkit. That toolkit has it's own evnironment (named ktk) associated with it, so we will take that as the basis for our project as well. Additionally, they suggest using Spyder as an IDE as it has good visualisation tools. If you want to use VS Code (or another IDE), feel free to do so.

To create the ktk environment, open a conda terminal (note that's not the same thing as the git terminal) and use the following prompt. It might take a few minutes to set up the full environment:

conda create -n ktk -c conda-forge kineticstoolkit spyder-kernels

Then follow the steps from the Kinetic Toolkit website to install and configure Spyder.

If your console shows Spyder is not connecting to the kernel after following the steps, you might have to update the pyzmq python package (this is the solution that worked for me). In this case, open a conda terminal for the update:

conda activate ktk
conda update pyzmq

Now, clone the benjamin_repeated_jump repo locally. This will allow us to share the code related to this project.

Open a new Git terminal and navigate in the directory you will be keeping your code:

cd 
cd coding # you can change this to anything you want, but make sure you use the same dir in the following steps

Clone this repo. The link can be found on the repo webpage under Clone or download. There are two options here: using HTTPS or using SSH. SSH is our preferred option (but it requires that you have set up an SSH key as described above).

git clone git@github.com:s-dupan/benjamin_repeated_jump.git

Now open a conda terminal (note that's not the same thing as the git terminal), and activate the ktk repository: On Windows:

conda activate rs_jump

Install the project

Now, within the conda terminal, you will install the project. Make sure your environment is activated first!

cd coding/RS_jump
python setup.py install

Once all of this in done, you can focus your work in Spyder (or any other IDE), and make less use of the conda terminal.

Folder structure

To work well with all the code, it is best to all have the same folder structure. As not all the folders are tracked by git (e.g. data is not uploaded), you might have to add some folders. I use the following structure, which is based on a suggestion by Patrick Mineault:

• \data
• \docs
• \results
• \scripts
• \src
• \tests
• .gitignore
• environment.yml
• README.md

Some extra folders will be generated by using this as a project and git, but you can ignore those.

Associated packages

As all these packages are included in the environment, you should be ok, but if you get errors that certain packages are missing, you might still have to install them.

The main basis for the environment and our code is the kineticstoolkit. Python toolkit for time series, rigid body geometry, and visualisation of c3d data. Detailed information on the toolkit itself, and python for biomechanics more generally can be found in their associated free book.

The standard data format for this environment is c3d. Extra information on the c3d format can be found here. It also uses ezc3d, a c3d reader/writer that is becoming standard in the field (e.g. it is used for OpenSim)

Other packages that might be interesting but are not integrated yet:

• codamotion: the python package associated with the acquisition software we use. You will be invited to a closed webpage from the company where you can download both the software itself and the python package.
• pyomeca with documentation here

Small note: installing pyomeca through pip install did not work for me, so you might have to clone the repository if you want to use it.

Processed-metrics outputs

Each trial produces a per-jump Excel file (<trial>_cmj_metrics.xlsx) with one row per jump and a shared column schema across the male and female pipelines. A complete data dictionary describing every column (definitions, units, processing conventions, QC flags) is in results/DATA_DICTIONARY.xlsx. To regenerate it after any schema change, run python scripts/build_data_dictionary.py.

Running the full pipeline

A top-level orchestrator chains every stage from raw C3D → per-jump Excel → statistical workbook → thesis figures:

python run_all.py                 # run everything
python run_all.py --skip-pipelines # reuse existing per-jump Excel; re-run stats + figures only
python run_all.py --only stats figures_coupling   # run a named subset
python run_all.py --list          # show available stages in order

Stages (in dependency order):

1. pipeline_male — scripts/MAIN_2025_RJT_LegacyHip_GSJCS.py
2. pipeline_female — scripts/MAIN_2026_RJT_PelvisHip_GSJCS.py
3. stats — scripts/MAIN_statistical_analysis.py
4. figures_methods — scripts/generate_thesis_figures.py
5. figures_waveform — scripts/generate_valgus_ensemble_figures.py (valgus ensembles)
6. figures_coupling — scripts/generate_slope_coupling_figures.py (kinetic-kinematic coupling)
7. figures_responder — scripts/generate_responder_tertile_figures.py (responder tertiles)
8. figures_ta_corr — scripts/generate_ta_valgus_correlation_figures.py (per-subject TA × valgus correlations, Pearson r with Fisher-z 95% CIs; tests the supervisor-driven hypothesis that 3D GSJCS valgus is partially a kinematic shadow of tibialis-anterior activity, whereas 2D pelvis-relative valgus is rotation-invariant)
9. figures_ta_overlay — scripts/generate_ta_valgus_waveform_overlay.py (dual-axis stance-phase overlays: TA EMG, 3D valgus, and 2D valgus on a shared 0–100% stance axis. Pooled M+F, sex-split, and Early/Late variants — the visual companion to stage 8.)

Reproducibility

• Pinned package versions are in requirements.txt. Install into a clean env with python -m pip install -r requirements.txt (Python 3.14, conda-forge ktk environment).
• Every stochastic routine in the statistical script (BCa bootstrap CIs, permutation sensitivity tests, slope-slope correlations) is seeded from RANDOM_SEED at the top of scripts/MAIN_statistical_analysis.py. Re-running the pipeline produces byte-identical p-values and effect-size CIs — verified by hashing the Permutation_Sensitivity, PostHoc and Fatigue_Slopes sheets across back-to-back runs.