Part II: Computing Joint Moments with AddBiomechanics

In the previous section, we scaled and made model and kinematic adjustments sequentially. Modern computational methods have enabled new algorithms to adjust the model and kinematic data together. This could save time by reducing the number of inputs from a user and reduce residuals further than an expert iteratively changing settings on each step.

AddBiomechanics is a tool that can use OpenSim models and data and perform all of these steps automatically. We will use the web interface to process the same data, and then analyze the changes it made to improve the simulation results.

1. Preparing the inputs to AddBiomechanics

• Prepare the model by adding additional markers. When previously scaling the model using OpenSim, additional markers, specific to the laboratory marker setup, were added from another file. Since AddBiomechanics does not currently support this feature, follow the steps below to add these markers to a new, modified model file.
• Copy the original model file (Rajagopal2015.osim) to a new file (e.g., Rajagopal2015_CustomMarkerSet.osim) before making any changes.
• The model file is an XML file. Open both the new model file and the additional marker set file (Scale/markerset_walk_preScale.xml) in a text editor. More info about the model format and suggestions for text editors can be found in the OpenSim Models File Format documentation.
• Add the additional markers to the new model file. For both files, all of the Markers can be found under the section <MarkerSet>, under a subsection called <objects>. Copy all of the Markers from the additional marker set file to the new model file (appending them to the list of markers, not replacing them), and save the new model file.
• Open the new model in OpenSim and check if additional markers have been added to the model. If the model does not load, check if the new model file has the required XML opening and closing tag (e.g., <Marker> and a corresponding </Marker>).
• Prepare the marker and ground reaction force data files.
• Copy the original marker (ExpData/motion_capture_walk.trc) and ground reaction force (grf_walk.mot) data files to new files (e.g., motion_capture_walk_trimmed.trc and grf_walk_trimmed.mot) before making any changes.
• In the new files, trim the beginning and end of the trial so that the time range remaining only contains times that are valid for use with Inverse Dynamics (as you did previously for RRA). It could be helpful to use an advanced text editor (e.g., Notepad++), Excel, or MATLAB to perform this step.

2. Accessing the AddBiomechanics web app

• Go to https://addbiomechanics.org/ 
• Click Go to App at the top right of the page.
• Either create a new account or log into your account.

3. Setting up a new folder for the example

• Click Process, Share and Analyze Data
• Create a new folder for the lab (e.g., named ExampleWalking)
• Click to enter the new folder and create a new subject (e.g., named Subject1)

4. Upload data and run the AddBiomechanics tool

• To ensure that the marker names between the model and data match, for “OpenSim Model and Markerset”, choose Custom OpenSim Model, Custom Markerset in the dropdown menu.
• A new box should appear to the right of the dropdown menu. Upload your new model file that is the generic model file with all experimental markers added to the model.
• Provide the height (1.829 m) and weight (85.0668 kg) for the subject.
• Under “Subject Tags”, select Healthy Subject.
• Load the trimmed marker data: Drag and drop the experimental motion capture data (e.g., ExpData/motion_capture_walk_trimmed.trc)
• Load the trimmed GRF data: For the new trial (named “motion_capture_walk”), click the block and select the GRF data (e.g., ExpData/grf_walk_trimmed.mot).
• Under “Trial Tags”, select Walking.
• By default, AddBiomechanics will only perform the Scale and Inverse Kinematics step. Inverse Dynamics is an optional step.
• To compute Inverse Dynamics moments, scroll to the bottom of the page and expand “Show Advanced Options”.
• Check the box Experimental - Attempt to Fit Dynamics.
• There will now be a new box towards the top of the page named “Foot Body Names in Custom OpenSim Model”. Select the same bodies as those chosen in the Inverse Dynamics setup before (calcn_r and calcn_l).
• At the top of the page, select to Process and Share the data. The app will ask if you want to share the data. Select OK.
• Processing could take a few minutes or longer. Once the result are processed, the webpage for the subject will note that the Status is Processed. You will also receive an email when the results are processed.
• Download the results by clicking Download OpenSim Results.

Questions

1. Assess the IK results by looking at the marker errors.
1. In the IK folder, open the file that ends in “summary.txt”. What was the average marker RMSE and the average marker max error?
2. Open the file containing the marker errors between the IK solution and the experimental data (in the IK folder, find the file that ends in “marker_errors.pdf”). Markers that are on both limbs are plotted together. For both legs, which Marker has the highest RMSE?
2. Look at the Marker with the highest error by visualizing the results in the OpenSim GUI. Load the model (final.osim) and the IK results (in the IK folder, find the .mot file). Find the Marker of interest on the model. How did the tool move the Marker?
3. Overlay the experimental data with the IK solution. To do this, under the model, expand the “Motions” section, right-click “Coordinates” and click Associate Motion Data…. Go to the MarkerData subfolder and choose the .trc file. Does the Marker with the highest error track closely to the experimental data (blue marker)?

5. Adjusting settings for marker tracking

Markers in OpenSim models have a boolean property tag called <fixed>. Broadly, setting this tag to true for a Marker indicates to the tool that this Marker’s location should not move as much as a Marker with the tag set to false. (Note that OpenSim’s Scale Tool uses a similar but different interpretation of this tag. See the Scale Tool documentation for more information). In this section, we will adjust this setting for the Markers that could be causing issues and re-run the tool.

• Set the <fixed> tag to true for Markers that could be causing issues in the generic model with added markers (e.g., Rajagopal2015_CustomMakerSet.osim). There are two ways to do this:
  • Load the model in the GUI and navigate to the Markers to be updated.
    • Click on an individual marker, then in the Properties pane (bottom left), check the box next to “fixed”.
    • Repeat this for all Markers that need to be updated.
    • Save the model.
  • Load the model file in a text editor.
    • Navigate to a Marker to be updated and change the XML tag <fixed> to be true.
    • Repeat this for all Markers that need to be updated.
    • Save the model file.
• Update the AddBiomechanics setup page and re-run the tool.
  • Navigate back to the original Subject page that you set up before.
  • Update the model by clicking on the box on the right hand side of the OpenSim Model and Markerset and choosing your updated generic model file.
  • Click Reprocess.
• Download the results.

Questions

1. Assess the new IK results. Were results improved by the change by “fixing” the Marker? Support your answer with quantitative data from any plots and other output, and with visualizing the model and results.
2. Plot the coordinates that are located closest to the updated Marker for both the results in the previous section and this section. How did the IK results change for this coordinate? Coordinates can be plotted in a couple ways: 1) in the GUI, or 2) in the file ending in “ik.pdf” provided in the IK results folder.
3. Overlay the experimental data on the new IK motion as done in the previous section.
   1. Does the Marker with the highest error track closely to the experimental data (blue marker)?
   2. Recall that the Scale and IK steps were completed at the same time when using AddBiomechanics. 
      1. How can this explain any issues with the placement of this Marker? 
      2. What is a downside to performing these steps at the same time?
4. Why might it have been necessary to set this Marker as “fixed” for AddBiomechanics when it was not “fixed” when using the OpenSim Scale Tool (i.e., scaling a model during a static trial)?
5. Looking at all of the marker errors, suggest other Markers that you may consider “fixing” in future iterations.

6. Assessing Inverse Dynamics Results

The Inverse Dynamics step was also completed, with the results printed to the ID folder.

Questions

1. Assess the quality of the Inverse Dynamics results. In the ID results folder, open the file ending in “summary.txt”.
   1. What are the average residual force and torque?
   2. How do these values compare to the residuals after RRA?
   3. Look at all 6 residual values over the trial by opening the file ending in “id.pdf” provided in the ID results folder. How do these values compare with the residuals after RRA?
2. Investigate some of the changes that were made by the tool to reduce residuals. Similar to RRA, the inertial parameters of bodies and kinematics can be changed to reduce residuals.
   1. In the top folder of the downloaded results, open README.txt. How does the total mass of the model compare to the mass of the subject that was used as an input to the tool?
   2. Which bodies had some of the largest changes, both as percentage changes and absolute changes. Are these changes changes reasonable? Why or why not?
3. Assess the quality of your ID results by comparing your ID results from those obtained in the original paper (Rajagopal et al., 2016). Plot your results for the three sagittal plane coordinates (hip_flexion, knee_angle, and ankle_angle) through either: 1) plotting in the GUI, or 2) opening the file ending in “id.pdf” provided in the ID results folder.
   1. How well do your results match with the original work? Some aspects to consider include the timing of peaks, the relative magnitude of the different joint moments, and the absolute magnitude of the different joint moments.
   2. Are these differences surprising given that the processing steps were performed differently?