MinT Simulation Analysis Tool

A Python-based tool for analyzing and visualizing biomechanical simulation data in MusclesInTime dataset with focus on knee loading, muscle activations, and ground reaction forces.

Core Files

• test_script.py: Entry point, handles data loading and analysis pipeline
• utils.py: Core functions for data concatenation, error calculation, analysis
• plot.py: Visualization functions for knee metrics, GRF, time continuity

Optional Analysis Modules

• muscles.py:

  • Provides muscle name mappings (short -> full names)
  • Defines anatomical regions (hip, thigh, lower leg)
  • Not currently used but useful for muscle group analysis

• cluster.py:

  • Optional muscle synergy analysis through clustering
  • Methods:
    • K-means clustering of activation patterns
    • Time series specific clustering
    • Dimensionality reduction
    • Visualization of muscle groups
  • Can be integrated for deeper muscle coordination analysis

Output Structure

output_path/
├── script_run.log                    # Main execution log
└── subject_id/                       # Per-subject results
    └── activity_name/                # Per-activity results
        ├── analysis.log             # Analysis details
        ├── figures.pdf             # Generated plots
        └── results_dict.pkl        # Results dictionary
        

Features

• Kinematics tracking error analysis
• Ground reaction force (GRF) analysis
• Muscle activation analysis
• Knee loading metrics (KAM, MCF) visualization
• Time series continuity validation
• Automated quality checks
• PDF report generation

Key Components

Analysis Results Dictionary

The analyze_simulation() function returns a dictionary containing:

results_dict = {
    "tracking_error_df": pd.DataFrame,          # DataFrame with columns: coordinate, rmse, max, mean, std, is_translational
    "checks_passed": list[bool],                # List of quality check results
    "muscles_with_high_peak_activation": array,  # Muscle names with peak activation > 0.6
    "muscles_with_high_mean_activation": array,  # Muscle names with mean activation > 0.2
    "plot_values_knee": {                       # Knee metrics plotting data
        "plot_time": array,                     # Time points for plotting
        "plot_kam": array,                      # Knee adduction moment values
        "plot_mcf": array                       # Medial contact force values
    },
    "plot_values_grf": {                        # Ground reaction force plotting data
        "plot_time": array,                     # Time points for plotting
        "plot_grf": array                       # GRF values
    },
    "grf_labels": list[str],                    # Labels for GRF components
    "kam_labels": list[str],                    # Labels for KAM measurements
    "mcf_labels": list[str],                    # Labels for MCF measurements
    "subject": str,                             # Subject identifier
    "activity": str,                            # Activity name/segment
    "babel_sid": int,                           # Babel database identifier
    "babel_url": str                            # URL to animation video (if available)
}

Quality Checks

The checks_passed key contains a list of boolean values corresponding to the following checks (in order):

1. Rotational tracking accuracy (True if all rotational RMSE < 5.0°)
2. Translational tracking accuracy (True if all translational RMSE < 0.02m)
3. Ground reaction force magnitude (True if peak GRF < 2.0 BW)
4. Muscle activation levels (True if max activation < 0.9)
5. Knee adduction moment (True if max KAM < 0.08 BW*ht)

Example:

checks_passed = [True, True, False, True, True]  # Indicates high GRF values

The tool performs automated quality checks with biomechanically-informed thresholds:

• 1. Rotational tracking (threshold: 5.0°)

  • Based on typical joint angle measurement accuracy in motion capture
  • Errors >5° might indicate significant marker placement or model scaling issues
  • Critical for accurate joint moment calculations

• 2. Translational tracking (threshold: 2cm)

  • Reflects typical marker position tracking accuracy in optical motion capture
  • Values >2cm suggest marker displacement or soft tissue artifacts
  • Important for center of mass and ground reaction force analysis

• 3. Peak ground reaction forces (threshold: 2.0 BW)

  • Normal walking produces peaks of 1.0-1.2 body weights (BW) Keller et al., 1996, Clin Biomech
  • Running/jumping can reach 1.5-2.0 BW
  • Values >2.0 BW indicate potential measurement errors or extreme activities McNitt-Gray, 1993, J Biomech

• 4. Muscle activation peaks (threshold: 0.9)

  • Values >0.9 might suggest potentially unrealistic muscle recruitment patterns
  • May indicate issues with muscle-tendon parameter scaling

• 5. Knee adduction moment magnitude (threshold: 0.08 BW*ht)

  • Typical walking KAM peaks: 0.02-0.04 BW*ht Kutzner, Ines et al. “Knee adduction moment and medial contact force--facts about their correlation during gait.” PloS one vol. 8,12 e81036. 2 Dec. 2013, doi:10.1371/journal.pone.0081036
  • Values >0.08 BW*ht associated with increased medial knee loading
  • Important clinical indicator for osteoarthritis progression

This analysis framework primarily follows the OpenSim evaluation guidelines and incorporates quality metrics from biomechanical literature where available. While some thresholds (e.g., KAM and GRF values) are directly supported by scientific studies, others represent empirically determined values based on experimental observations and computational considerations. The default thresholds can be adjusted through configuration parameters to accommodate specific research requirements or clinical standards.

Generated Files

For each analysis, the tool generates:

1. Analysis log file (.log)
2. PDF report with plots (_figures.pdf)
3. Pickled results dictionary (results_dict.pkl)

Setup

1. Create conda environment from yml file:

conda env create -f environment.yml

2. Activate the environment:

conda activate opensim_scripting

Usage

Once the environment is activated:

python test_script.py --dataset-root <path_to_data> --output-path <output_directory>

Required Arguments

• --dataset-root: Path to root directory containing MusclesInTime.csv
• --output-path: Path where logs and results will be saved

Dependencies

See environment.yml for the complete list of dependencies:

• Python 3.11
• NumPy
• Pandas
• Matplotlib
• scikit-learn
• tqdm