MoMo R5.1: Model

1. Contents
2. Setup
3. Preferences
4. Sessions
5. Command line
6. Models: 6.1What is a model?
6.2Model class
6.3Model interface
6.4Model script - MI50B interface
6.5MI50C interface
6.6Measurement class of trials
6.7Order of model evaluations
6.8Output of models
6.9Creating/modifying models
6.10Show model details
6.11User function
7. Visualize C3D
8. Administration
9. Changes

6.1 What is a model?

The model evaluates all data belonging to a session. This includes the trajectories and time-distance-parameters of the trial-files and the scalar values from the ENF-files, e.g. the body-weight. In addition the model controls which trials are used and how the output should look like. Therefore the term model exceeds the physical rigid body model.
The models are implemented as Matlab functions called model script. They have a main routine, which forwards the calls from MoMo to a certain set of subroutines. In the currently existing model scripts, the subroutines are parts of the same file, but it is possible to call external functions also, e.g. to share some parts with other models.

6.2 Model class

Each model belongs to a model class, which is a classification concerning different studies or measurement objects, e.g. Gait and Foot. For each session a "best" matching model class must exist, although a session can be processed with a "foreign" class also. During processing a session, MoMo writes the model class to a status file in the session folder. On subsequent processing of this sessions, the function moModelManager determines the actual model script. By this technique a new version of a model script need to be inserted in moModelManager only, but the session folders are not concerned.
MoMo uses the model class '$auto' to start an automatic detection of the best matching model class for a specific session. For this job, the function moModelManager contains the correlation between marker-sets, BodyBuilder scripts and subject names and corresponding model classes.
The extra-ordinary class "Research" is not connected with specific model scripts, because it allows to apply experimental models, e.g. during their development. Instead of moModelManager, the function moResearchModel manages the actually used model script. In the MoMoG dialog, the research model script can be chosen with a right-click on the popup-menu for model classes after selecting the 'Research' class.

6.3 Model interface

From time to time the interface between MoMo and the model scripts need an extension, e.g. if new model scripts demand for a new kind of measurement data. Nevertheless, existing and well tested model scripts should not need any changes, because editing functions implies the danger of inserting bugs ever. Therefore MoMo is compatible with different versions of the model interface. The MoMo issue 5.0.10 handles the interfaces 'MI50A' and 'MI50B'. The later includes EMG data and can export text messages (needed for filter parameters of EMG evaluations) from the model script to trials exported to the database. Future versions of MoMo R5 will remain backward-compatible with all 'MI5xy' interfaces.
While MoMo 5.0.10 can work with MI50A and MI50B model scripts, the older MoMo 5.0.0 understands MI50A only. Such limitations are considered in the function moModelManager. As a drawback, this function is rather complicated, but fortunately it must be modified only to define new standard model scripts or if a new model interface becomes active. For the future a simpler method using tables in text format is under construction.
For each known model interface, a template model script exists, e.g. MI50B_ModelTemplate_. A copy of this file can be used as template to create new model scripts. The file contains the exact definition of the interface and a list of changes to earlier interfaces. The template file is the best reference for the specifications of the model interface. It is in general newer than this documentation.

6.4 Model script - MI50B interface

The model script contains the following routine/subroutines:
  1. The main routine, which forwards the different commands to different subroutines.
  2. IdentModel: Define name and version of the class belonging to this model script. The version number may help to distinguish different outputs, e.g. if a variable has been redefined. The model class is saved to status file in the processed session folder and allows MoMo to find the best matching script even in future versions.
  3. TrialMatch: Create a filter for trial-ENFs and define a list of accepted marker-sets and BodyBuilder scripts. This allows to ignore trials to save the time for importing.
  4. ModelJob: Modification of MoMo's control struct Job: E.g. a model can specify the need of static trials, accepting of cycles with missing trajectories or the number of rows and columns for the output sheets.
  5. DefVariables: Definition of input and output values with diagram titles, units, internal names of variables, plane, used force plates and so on.
  6. DefMClass: define the measurement classes, which involve the side ("right" and "left") and measurement conditions (e.g. "barefeet"/ "shoe", "ramp"/"stairs"/"level").
  7. TrialMClass: Identify the measurement class(es) of each trial - you can use every kind of information in the C3D or trial-, (sub)session-ENF files to obtain this information.
  8. Session: A kind of calibration concerning the whole session, e.g. reading the persons weight from the session-ENF.
  9. Static: Evaluation a static trial: finding zero attitudes of joints or distances; these information is stored for each measurement class, so that the dynamic model can access these data of the specific class.
  10. Joint: Determination of joint axes.
  11. ClassCalib: Calibration value for a specific measurement class. This can include the values from static and joint trials.
  12. AllCalib: Calibration values based on the measurements of all classes.
  13. Dynamic model. It uses, like the static and the joint model, the marker trajectories to compute arbitrary values like angles etc. In addition the force plates and EMG channels can be evaluated. 3D objects created for modeling can be visualized by forwarding them to ShowC4D.
  14. Post Proc: some post processing. To allow as much flexibility as possible, this section is implemented as state machine, so the input arguments are not specified yet.
  15. Report: Individual report methods. As for Post Process the input is not specified yet. Please ask me for instructions on demand.
The parts can be included as local subroutines in the model script or as external Matlab functions (with a unique function name or in a private subfolder).
MoMo calls the command IdentModel after the model class and script have been determined. To specify model parameters like groups, norm data, output style and filters of accepting trials, the commands DefMClass, ModelJob, TrialMatch and DefVariables are called in this order. After reading the trials (using the information from the TrialMatch command), the command IdentGroup is called for each trial to find the list of groups each trial belongs to. Then actual physical model is applied at first to session related data (as body weight) by the Session command, then Static and Joint commands are called for the corresponding trials. The replies are collected by the ClassCalib command for each group and for all groups afterwards with AllCalib. The Dynamic section is called for each dynamic trial and each group separately. Finally the PostProc section allows additional combinations of the calculations and Report is called after the creation of sheets for an individual output.

6.5 MI50C interface

The model interface needed some additions to allow for a simpler processing of EMG trials (new: 16-Nov-2009):
(The list number are related to the description of MI50B interface above)
  1. TrialMClass: The struct MClass.UserData can be created to control computations in the Dynamic section. E.g. the EMG field of the trial-ENF is parsed in TrialMClass to determine, if the EMG has been applied to the right, left or both feet. The UserData can carry this information to the other parts of the model.
  2. (and 10. and 14.) The sections Static, Joint and Dynamic can export string messages to the files, which are exported for the database, e.g. the name of the EMG filter. See: help moDBExportMsg.
Existing models need not be modified and work under MoMo 5.0.19. Models using the new features do not run under MoMo < 5.0.12, but it is easy to create a model which works under MI50B and MI50C - feel free to ask me.

6.6 Measurement class of trials

The model can define different classes to sort the trials in. Usually there are different measurement conditions, e.g. different shoes, inclined ramps, walking speeds, etc., and the two sides right and left (in the same or different trials). The side is determined in the model script using the trial-ENF, (sub)session-ENF or the trajectories. The measurement conditions are called "group" and can be identified by the model using the trial type, values of the trial-ENF or (sub)session-ENF, the field STUDY_GROUP in the trial-ENF or the name of the subsession folder.
While the measurement classes are defined in the DefMClass section of the model script, the classes are assigned to the trials in the TrialMClass section. A trial can belong to multiple classes, e.g. the gait trials contain data for both sides ever and therefore they belong to 2 classes.
For the processing of groups of sessions, as the creation of norm data, the measurement classes can be combined: For the assessment of a shoe, both sides can be included in one "box". See Session-sets and norm data.

6.7 Order of model evaluations

MoMo processes the section of the model in this order (in moEvalModel):
  1. General session data: Session
  2. For each class (group & side) all static trials are processed: Static
  3. For each class (group & side) all joint trials are processed: Joint
  4. Combine calibration values of steps 1 to 3: AllCalib
  5. For each class (group & side) all dynamic trials are processed: Dynamic
  6. Post-processing (will be implemented if anybody needs it): PostProc
  7. After the sheets are created, the model can add a Report (will be implemented if anybody needs it): Report
It is not strictly defined if the group or side is altered at first in the list of classes.

6.8 Output of models

The function moModelOut creates the output of the most sections of models: TrialMClass, Session, Joint, ClassCalib, AllCalib, Static, Dynamic. This helps to avoid the creation of malformed output from the model scripts and MoMo can save a lot of time for validity checks.
Besides the different evaluated data, the sections can reply two classes of messages:
More help: help moModelOut.

6.9 Creating/modifying models

A new model script can be created either by modifying an existing one, or by starting with the template of the current model interface, e.g. "MI50B_ModelTemplate_.m". Looking into existing models is the best help for the implementation e.g. of the TrialMClass section and the interpretation of forces in the Dynamic section.
If you want to add just a few variables to an existing model, this can by done dynamically without cloning the original model script: The new script calls the existing one at first and append new variables afterwards. The function moMergeModelReply help to join the parameters of the DefVariables section for this case. This method has the tremendous advantage, that changes of the original function are included in all inherited experimental models automatically. For example, if you decide to insert ground reaction forces to the standard model, they are available in the depending models immediately. The same holds true for improved titles or fixed bugs. Be aware that the synchronization of different model scripts is a critical task and the confusion of editors and examinators reading the created sheets can be a dangerous source of wrong assessments!
Ask the author for an example file, if you want to work with this method.
To insert a new variable, usually just a few lines of code are needed in the model script in the different sections:
  1. DefVariables: Insert a new line in the corresponding table with key, title, unit, titles for low and high values, a character for the plane and the diagram type (which is 'XT' or 'hide:XT' ever in MoMo R5.0).
  2. Version: If you add a new variable or change an existing definition, advance the version number! It cannot be stressed enough, that this is very important if anyone is interested in the created data later, if ASCII or PDF files are exported. A value of a variable looses its meaning, if the calculation cannot be reproduced exactly!
  3. Static: Add calculations here, if a neutral position need to be considered. Usually the Static section calls the Dynamic section implicitly for the complicated calculation of spatial parameters. By this way the algorithms do not appear twice in the Static and the Dynamic section and the risk of different definitions is avoided.
  4. Dynamic: Insert the actual calculations here.
After creating or modifying a model script, several tests are recommended:

6.10 Show model details

A double click on a diagram on the sheets opens a new figure with the selected diagram and a explanation drawing – if the author of a model added such drawings. MoMo can create sheets with the diagrams replaced with these drawings: momo desc.
The function momoShowVars displays the variables defined in the $DefVaribales section in the command window of Matlab. This is usually faster than searching in the source code of the model. Examples for a foot model (assumed than Foot19 is existing):

6.11 User function

The user can define a set of functions, which is applied to the processing data of MoMo at different phases of the calculations. This allows for a kind of post-processing independent from the model script. Currently (MoMo R5.0.12, 27-Jun-2009) only one type of callbacks is implemented:
The evaluated data for dynamics, analog and EMG variables can be modified by a user-defined function before the normalization.
Further callbacks will be included on demand - feel free to ask me! Ideas: Remove offsets, change signs of certain variables, smoothing, export, etc. Do not fake results in publications.
The user-defined functions are controlled by the input argument UserFcn. Further explanations can be found at help moUserFcn and the example function UserFcn_Template_. The function User_Derive calculates the temporal derivatives for all variables (This removes the horizontal offset caused by variation of marker placement and segment size). To apply this function start MoMo with: momo UserFcn User_Derive.
This feature replaces the former argument "derive" by a more flexible method (new: 27-Jun-2009, MoMo R5.0.12). Because the special calculations are triggered dynamically by input arguments and exported data cannot be reproduced without further informations, the user-defined functions will keep the status [EXPERIMENTAL] in the future. A message on sheets points out the application of a user-defined functions.
Author: © Jan Simon, Imprint / Impressum   File: Help/momo_5.1/model.html    24-Nov-2018   MoMo: 5.1.34