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.
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.
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.
The model script contains the following routine/subroutines:
- The main routine, which forwards the different commands to different
subroutines.
- 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.
- 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.
- 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.
- DefVariables: Definition
of input and output values with diagram titles, units, internal names of
variables, plane, used force plates and so on.
- DefMClass: define the
measurement classes, which involve the side ("right" and
"left") and measurement conditions (e.g. "barefeet"/
"shoe", "ramp"/"stairs"/"level").
- 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.
- Session: A kind of calibration concerning the whole
session, e.g. reading the persons weight from the session-ENF.
- 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.
- Joint: Determination of joint axes.
- ClassCalib: Calibration value for a specific
measurement class. This can include the values from static and joint trials.
- AllCalib: Calibration values based on the measurements
of all classes.
- 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.
- 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.
- 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.
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)
- 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.
- (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.
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.
MoMo processes the section of the model in this order (in
moEvalModel):
- General session data: Session
- For each class (group & side) all static trials are processed:
Static
- For each class (group & side) all joint trials are processed:
Joint
- Combine calibration values of steps 1 to 3:
AllCalib
- For each class (group & side) all dynamic trials are processed:
Dynamic
- Post-processing (will be implemented if anybody needs it):
PostProc
- 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.
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:
- Info: The message is displayed in the command window
with a short header, which contains the trial name and the currently processed
group and side. This is helpful for debugging and explanations of unexpected
results.
- Warn: As in the first case, the message is written to
the command window, but the (currently processed group and side of this) trial
is excluded from processing! Trials, which cannot be handled without a warning,
cannot be a base of reliable results for clinical decision making. While other
warnings of MoMo can be ignored if the user is really sure, warnings from the
model are treated as serious problem and the trial should be disabled.
More help: help moModelOut.
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:
- 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).
- 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!
- 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.
- Dynamic: Insert the actual calculations here.
After creating or modifying a model script, several tests are recommended:
CheckSyntax verifies a stricter Matlab syntax. Unfortunately
this works in Matlab 6.5 only and for Matlab 7 this tool has less power.
momoTestModel <model_script> checks the compatibility
with the specified model interface.momoFixModel updates the strings for file name and path. This
calls the first two tests momoTestModel and
CheckSyntax implicitely.- Run MoMo at least once with info level
4 to activate deeper integrity checks.
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):
- Flags with default values:
momoShowVars Foot19 flag
- All variables:
momoShowVars Foot19 all
- All with debug info for the newest Gait model:
momoShowVars >Gait detail
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.