Residual Gait Gap in Parkinson's Disease

Code supporting the analysis and figure-generation workflow for the study of residual gait impairment beyond clinical-treatment expectation in Parkinson's disease.

The analytical framework compares:

• Observed wearable gait impairment, derived from multidomain lumbar wearable features;
• Expected wearable gait impairment, estimated from conventional clinical-treatment descriptors;
• their difference, defined as the Residual Gait Gap.

A positive residual indicates gait impairment that is greater than expected from the clinical-treatment profile alone.

Repository contents

.
├── analysis/
│   ├── 01_data_audit_and_cohort_definition.py
│   ├── 02_feature_domains_and_observed_impairment.py
│   ├── 03_expected_impairment_and_residual_gait_gap.py
│   ├── 04_high_gap_feature_characterization.py
│   ├── 05_retrospective_fall_anchor.py
│   ├── 06_patient_level_sensitivity.py
│   ├── 07_residual_gait_gap_robustness.py
│   ├── 08_methodological_validation.py
│   ├── 09_pca_stability.py
│   └── 10_outcome_construction_robustness.py
├── figures/
│   ├── figure1.R
│   ├── figure2.R
│   ├── figure3.R
│   ├── figure4.R
│   └── supplementary_figureS1.R
├── assets/
│   └── BannerGaitGapGithub.png
├── .gitignore
├── requirements.txt
└── README.md

Analysis workflow

The core pipeline is:

Source data
   │
   ▼
01  Cohort definition and data audit
   │
   ▼
02  Multidomain wearable impairment construction
   │
   ▼
03  Expected impairment and Residual Gait Gap
   │
   ├──► 04  High-gap biomechanical characterization
   ├──► 05  Retrospective fall anchoring
   ├──► 06  Patient-level sensitivity
   ├──► 07  Residual-gap robustness
   ├──► 08  Methodological validation
   └──► 10  Outcome-construction robustness

02 ───► 09  PCA stability

01 — Cohort definition

Defines the complete-case assessment-level analytical cohort, standardizes identifiers and coding, and retains the variables required by the downstream pipeline.

02 — Observed wearable impairment

Organizes 22 wearable gait features into five prespecified biomechanical domains:

• locomotor performance;
• rhythmicity;
• dynamic regularity;
• neuromotor complexity;
• trunk-centered kinematics.

Within each domain, the first principal component is extracted and sign-aligned so that higher values indicate greater impairment. The standardized domain scores are then averaged to obtain the Observed Wearable Gait Impairment score.

03 — Residual Gait Gap

Uses patient-grouped out-of-fold Ridge regression to estimate expected wearable impairment from:

• age;
• disease duration;
• LEDD;
• UPDRS-III;
• Hoehn & Yahr stage;
• sex;
• center.

The primary quantity is:

Residual Gait Gap =
Observed Wearable Gait Impairment
− Expected Wearable Gait Impairment

The primary high-gap phenotype is defined as the upper quartile of the residual distribution.

04–10 — Characterization and robustness

The remaining scripts evaluate:

• stable biomechanical features characterizing the high-gap phenotype;
• exploratory retrospective fall anchoring;
• patient-level robustness;
• sensitivity to alternative high-gap thresholds;
• expected-model calibration, bootstrap uncertainty and permutation testing;
• stability of the domain-specific PCA representations;
• robustness of the observed-impairment construction to alternative PCA sign-orientation references.

Running the analysis

The source dataset is not distributed with this repository.

Users with an authorized local copy of the compatible source dataset can begin with:

python analysis/01_data_audit_and_cohort_definition.py \
  --input /path/to/source_dataset.xlsx

Then run the core pipeline:

python analysis/02_feature_domains_and_observed_impairment.py
python analysis/03_expected_impairment_and_residual_gait_gap.py

The remaining analysis scripts can then be run independently:

python analysis/04_high_gap_feature_characterization.py
python analysis/05_retrospective_fall_anchor.py
python analysis/06_patient_level_sensitivity.py
python analysis/07_residual_gait_gap_robustness.py
python analysis/08_methodological_validation.py
python analysis/09_pca_stability.py
python analysis/10_outcome_construction_robustness.py

Generated datasets, derived tables, figures, and other outputs are intentionally excluded from version control.

Figure generation

The figures/ directory contains the R scripts used to generate the manuscript figures and supplementary robustness dashboard.

Generated figure files are not tracked in the repository.

Data availability

The source dataset is not included in this repository.

This repository contains the analysis and figure-generation code required to document and reproduce the computational workflow when used with an appropriately structured and authorized local copy of the study data.

Software

The Python workflow uses:

• Python 3;
• NumPy;
• pandas;
• SciPy;
• scikit-learn;
• openpyxl.

The figure-generation workflow uses R with ggplot2, patchwork, and grid.

Exact Python dependencies are listed in requirements.txt.

Reproducibility notes

• Repeated assessments from the same participant are kept within the same cross-validation fold.
• Primary expected impairment is based on out-of-fold predictions.
• The Residual Gait Gap is defined only after the observed and expected quantities have been constructed.
• High-gap classifiers are used for phenotype characterization, not for defining the residual gap or its threshold.
• Retrospective fall status is used only as an exploratory external clinical anchor.
• Intermediate data and analysis outputs are excluded from the public repository.

Citation

If you use this code, please cite the associated manuscript.

Software release archived on Zenodo:

DOI: 10.5281/zenodo.21837917

License

License information will be added before public release.