Skip to main content

How To Use MTP

Check that you have all the necessary inputs​

Scaled OpenSim Model
You will need to have a scaled OpenSim model. Preferably one that has already been run through JMP to have accurate joint geometries. This OpenSim file should also have

NMSM Pipeline Model (Optional)
If you ran GCP or another MTP run before an MTP run, you can include that output .osimx file as an input to MTP. MTP does not directly use any of the information in the input .osimx file, but will concatenate MTP results to the end of the .osimx file if given.

Processed Data
You need a data folder with all your preprocessed data. It is recommended to do this through the data preprocessing tool. Specifically, you need inverse dynamics joint moments, processed EMG data, and muscle analysis data, including muscle-tendon velocities as calculated by the data preprocessing tool.

Create your XML settings file and modify necessary parameters​

You can create an MTP settings file using the NMSM Pipeline GUI plugin in OpenSim. Alternatively, you may use the MTPReference to build a settings file from scratch. This file contains an exhaustive list of all MTP settings file elements.

If creating an MTP settings file in the GUI, one MTP task will be automatically created that personalizes all all muscle-tendon parameters simultaneously. We recommend running this initial settings file, and iterating your max allowable errors and error centers to get the best solution.

If using MTLI or SynX, those settings will be built into the XML file that you are using for MTP.

Create your MATLAB file to run MTP​

You may now create a MATLAB script to run MTP. This file should call the function MuscleTendonPersonalizationTool("settingsFileName.xml") MTP is thread-safe, so you can use a "threads" parallel process.

Make sure the nmsm-core project is running in MATLAB​

If it is not already running, double click on ‘Project.prj’ in the root of the nmsm-core folder to open it up.

Press run in MATLAB​

Analyze your results​

The key output to an MTP optimization is the .osimx file. This file contains all of the information about your Hill-type muscle models that will be used later by NCP and Treatment Optimization. If given an input .osimx file, MTP will concatenate new elements to that .osimx file.

MTP generates many files to analyze your results. The two key files that will be used by subsequent tools are:

  • modelMoments: Joint moments generated by the calibrated muscle forces. These will be different from your input inverse dynamics joint moments, depending on your tracking quality.
  • muscleActivations: Muscle activations calculated using the calibrated activation dynamics parameters. These should be used later as inputs to NCP and Treatment Optimization.

In addition to the files that will be used later in the NMSM Pipeline, MTP also generates many files that can be used to analyze your results. You can plot these files using the function plotMtpResultsFromSettingsFile("settingsFileName.xml"). This function generates plots for:

  • Joint moment matching
  • Muscle excitations and activations
  • Normalized muscle fiber lengths
  • Passive joint moment matching (only if MTLI was used)
  • Muscle forces
  • Hill-type muscle model parameters.

All of the files used in these plots are inside of the Analysis folder, and are described below. These files are used by the MTP plotting function and do not need to be directly interacted with.

  • muscleModelParameters: Hill-type muscle model parameters for all muscles.
  • activeMuscleForces: Muscle forces generated by the active component of the Hill-type muscles
  • passiveMuscleForces: Muscle forces generated by the passive component of the Hill-type muscles
  • totalMuscleForces: The sum of active and passive muscle forces
  • tendonForces: totalMuscleForces multiplied by cos(pennationAngle). These forces are used to calculate joint moments.
  • inverseDynamicsJointMoments - Experimental inverse dynamics joint moments
  • modelJointMoments - Modeled joint moments calculated without using SynX. If you did not use SynX, this file will be the same as modelMoments above.
  • modelJointMomentsSynx - Modeled joint moments calculated with SynX. If this file is generated, it will be the same as modelMoments above.
  • muscleActivations: Muscle activations calculated without using SynX. If you did not use SynX, this file will be the same as muscleActivations above.
  • muscleActivationsSynx: Muscle activations calculated calculated using SynX. If this file is generated, it will be the same as muscleActivations above.
  • muscleExcitations: Muscle excitations calculated without using SynX.
  • muscleExcitationsSynx: Muscle excitations calculated using SynX.
  • normalizedFiberLengths: Time varying normalized fiber lengths for all muscles.
  • passiveJointMomentsExperimental: Experimental passive joint moments that were tracked in MTLI.
  • passiveJointMomentsModeled: Modeled passive joint moments after running MTLI.

For more detail, visit the hands-on MTP Tutorial.