Overview

The Output Reporter is an Analysis tool (available in OpenSim version 4.0 and later) that allows users to tailor their analysis workflow to their exact needs. In particular the output reporter allows you to output quantities of interest (e.g., moment arms, kinematics of the COM, muscle fiber lengths, and more) from a simulation. In this example, we'll use a results from a previously generated jumping simulation to explore the Output Reporter.

TODO: Add a link to the relevant webinar(s). OpenSim 4.0 webinar and potentially ESB webinar, as well.

Model and Simulation Background

In this tutorial, you will be using a simplified musculoskeletal model with muscle-driven lower extremities and torque-driven upper extremities. It is modified from the lower-extremity model of Delp et al. [1] to combine major muscles in the lower extremity and to include a torso and arms [2]. The anthropometry of the model has already been scaled to match the dimensions of the subject we will be analyzing.

The simulation was created following an Inverse Problem approach. Specifically, Inverse Kinematics was used to find the joint angles that best reproduce the experimental marker positions of the subject performing a maximum-height jump. The Residual Reduction Algorithm tool was used to adjust the model's torso mass parameters so that the motion from Inverse Kinematics with the model is more dynamically consistent with ground reaction data. Finally, Computed Muscle Control was used to estimate muscle excitation and other muscle and tendon states during the jump.

The files provided are the model, results from Computed Muscle Control, and an example setup file for the Output Reporter.

What are outputs?

Each component type (e.g., Muscle, Frame) has different outputs available for users. Each output is a quantity of interest that a user can query directly from a component for during a simulation. In the first part of the example, we will show you how to explore the outputs available for each component in your model.

Exploring outputs of different components

First, we'll find the output for the whole model's center of mass position.

  1. Load the model file jumper_model_updated.osim.
  2. In the Navigator pane, select the model by clicking on the model name "jumper". This should bring up the properties of the model in the Properties pane.
  3. In the Properties pane, click on "Outputs". This Properties pane will now be populated with the outputs that can be extracted from the model. The name of each output appears in the left column, and the data type in the right column. TODO: What is a vec3? What is a double?
  4. To use the Output Reporter, the full path to each output is needed. We'll find the output for the center of mass position of the whole model. Select "com_position" in the Outputs list. In the bottom left, there are now two strings. The top string is the name of the output (i.e., "com_position"), and the line below contains the full path (i.e., "/|com_position"). See below for how your Navigator and Properties panes could appear at this point.

Next, we'll find the output for the right hand's position.

  1. In the Navigator pane, expand the "jumper" level, then the "Bodies" list.
  2. Click on the body "hand_r".
  3. In the Properties pane, select Outputs.
  4. Click the "position" Output.
  5. Find the full path for the "position" output (i.e., "/bodyset/hand_r|position").

Finally, we'll find some interesting muscle outputs. In particular, we're find the active force length multipliers for the right calf muscles, "soleus_r" and "gastroc_r".

  1. Find the two muscles, "soleus_r" and "gastroc_r" by expanding "Forces", then "Muscles".
  2. For each muscle, go to the Outputs tab and find the "active_force_length_multiplier" output.
  3. Write down the full path of the "active_force_length_multiplier" output for each muscle.

We'll use all of the paths to the outputs in the next section. If there are other outputs of interest, you can continue to explore each of the components in your model.

Exploring the Output Reporter analysis tool

The Output Reporter analysis allows us to get the values for all of the outputs above easily for a given simulation. The example files contain a setup file that sets up the analysis for our jumping simulation.

Running the tool

  1. On the top toolbar, go to "Tools" → "Analyze...".
  2. Load the setup file "outputreporter_setup.xml".
  3. Explore the input files from CMC.
    1. In the Main Settings tab, the states from CMC output are used (i.e., "cmc_states.sto").
    2. In the "Actuators and External Loads tab"
      1. The same Actuators file from CMC is used ("reserve_actuators.xml").
      2. The same External Loads file from CMC is used ("jump_forces.xml").
  4. Explore the Output Reporter analysis.
    1. Go to the "Analyses" tab. The OutputReporter analysis has already been added.
    2. Click on the "OutputReporter" analysis and then click "Edit".
    3. Expand the "output_paths" list. The full paths to different outputs are added here.
    4. Check if the four full paths from the previous section are the same ones added here.
    5. If you'd like to add another output, click the "+" icon in the second column of the pane.
  5. Run the Output Reporter analysis by going back to the main Analysis window and clicking the "Run" button.

Examining the output files

The setup file defaults to printing the output files to "Results_PlantarflexorOutputs". To examine the output, we'll use the Plotter tool.

  1. Open the Plotter tool by going to Tools → Plot.
  2. Plot the model's center of mass vertical position and right hand vertical position over time.
    1. Click Y-Quantity... → Load file...
    2. Open jumper_OutputsVec3.sto. Note that this where any outputs of data type "Vec3" type will be printed.
    3. Select "/|com_position_y" and "/bodyset/hand_r|position_y" and click OK
    4. Click X-Quanity..., select "time", and click OK
    5. Click "Add" in the bottom right pane.
  3. Plot the active force length multiplier for the right calf muscles over time.
    1. Click Y-Quantity... → Load file...
    2. Open jumper_Outputs.sto. Note that this is where any outputs of data type "double" will be printed.
    3. Following steps c-e from Step 2 above, choose the two outputs and plot them over time.

References

  1. Delp, S.L., Loan, J.P., Hoy, M.G., Zajac, F.E., Topp E.L., Rosen, J.M. An interactive graphics-based model of the lower extremity to study orthopaedic surgical procedures. IEEE Transactions on Biomedical Engineering, vol. 37, pp. 757-767, 1990.
  2. Hamner, S.R., Seth, A., Steele, K.M., Delp, S.L.A rolling constraint reproduces ground reaction forces and moments in dynamic simulations of walking, running, and crouch gait. Journal of biomechanics, vol. 46, pp. 1772-1776, 2013.