Parameter Processing

Home page Models Systems Tools IT staff References

Regular Parameter Processing LHS Parameter Processing Parameter Processing Code

Regular Parameter Processing

The various models all use parameters specified in an XML file. When a model is run the parameter file to use is typically specified via a command line option. The parameter files are processsed using Tiny XML. For some models the GUI version will prompt for a parameter file, using a file browser dialog, if none is specified on the command line.

Here is an example parameter file for the 3D lung model. Each parameter is specified as an attribute of an XML tag. For example the initN4 = "100000" is an attribute of the GR XML tag. The levels of tags are for parameters for different parts of the model. In this example parameter file the GR tag (the top or root tag) is for general model parameters. The parameters in the Mac tag are parameters for macrophages, which are agents in that model. The Tcell tag has parameters for Tcells in general, and sub-tags within Tcell have parameters for specific types of Tcells. Mtb tag specifies parameters about the TB bacteria. The INIT tag specifies the initial conditions for the model, in this case to place an infected macrophage at a specific grid location.

Different models will use different XML tags and different parameters. Also, there are some differences among the models with respect to the code changes needed when adding or deleting parameters. See the description for a particular model, at Models, for details on how that model handles parameters differently than described here.

LHS Parameter Processing

It is common in simulation modeling to perform parameter sweeps over some subset of the parameter space for a model. We use Latin Hypercube Sampling (LHS) to define a set of parameter files to run with a model. See this article for a reference on the LHS algorithm.

The parameter processing code for each model also includes a separate program, in a C++ source file called lhs.cpp, (which also has header file lhs.h). This will be in the same directory as the simulation model code (this directory is often called "simulation"). This program is built using make lhs. The lhs program takes 2 command line arguments, "-i" to specify an LHS parameter file (described shortly) and -n for the number of samples - the number of regular parameter files to create. The created regular parameter files are numbered from 1 to N, where N is the sample size, ex. 1.xml, 2.xml, etc.

An LHS parameter file is the same as a regular parameter parameter file, except that one or more parameters have a range of values instead of a single value. A parameter value range is specified as a min and max value within square brackets and separated by a comma, ex. "nrSources = "[50,100]".

Note that older versions of the lhs program required that all parameters have a range, even if not all parameters were being varied (so most parameters would have the same value as the min and max for the range). This is no longer the case, but you may see LHS parameter files like this from prior runs.

These are needed to post process run results. Typically this is performed on the model run server, but you might want to do it on another system. These need to be installed on whatever system is used to perform the run result post processing.

An LHS is performed as follows:

Build the lhs program for the model. In a terminal window, cd to the directory with the lhs.cpp program for the model (typically the "simulation" directory) and do make lhs.
Create a directory to serve as the main directory for the LHS.
Create an LHS parameter file in the directory for the LHS, with ranges for those parameters to be varied.
Run the lhs program: lhs -i lhs-parameter-file.xml -n sample-size, ex. lhs -i containment-lhs.xml -n 500. This will create parameter files 1.xml, 2.xml, etc. Each regular parameter file is the same as the LHS parameter file, except that in place of each parameter range is a single value chosen at random from the range (using a stratification strategy as described in the LHS article).
Run the model on each parameter file, specifying the number of replications for each parameter file (how many runs to perform with each parameter file with random seeds), either on a cluster or on one or more desktops. Be sure to edit whatever run script you use to make sure the correct command line arguments are used and be sure to specify saving statistics to a file and saving simulation states to files so the graphics can be generated during post-processing (since we typically run the non-gui version of the model when doing an LHS).
- On a cluster, use the non-gui version of a model (since clusters typically don't have graphics cards for doing graphics - they may have graphics cards for parallel computation). See the directions for running on a particular cluster on the Systems page, for example running on the Axiom cluster.
- On one or more desktops, such as helico or macrophage, use the runAbm.pl script. You can use either the gui or non-gui version, but it is probably faster to use the non-gui version.
However the runs are performed, the run result files will be in a directory structure like the following (in this example the LHS has a sample size of 2 and was run with 3 replications).
```
main-lhs-directory
	lhs-parameter-file.xml
	1.xml
	2.xml
	exp1
		exp1-1
		exp1-2
		exp1-3
	exp2
		exp2-1
		exp2-2
		exp2-3
```
Copy the run results (the LHS main directory and all the files and sub-directories it contains) to the model run server, or whatever system will be used for post processing. Ulitmately all model run results should be copied to the model run server, regardless of where the post preocessing is performed. If run on two or more desktops this will require consolidating the separate run result directories from the different desktops into a single unified directory structure.
Run the makeLhsPRCC.pl script to create an LHS matrix for further analysis, often PRCC (Partial Rank Correlation Coefficient) analysis using Matlab.
Run the snapshot script to generate graphics from saved model states.
Create an LHS report:
- Run the makereportNew.pl script. Run it without any command line arguments to see what the arguments are.
- Run pdflatex on the latex file produced by makereportNew.pl. It must be run twice for the report to have a table of contents. See the description of pdflatex if the report is too large or if pdflatex detects Latex errors.

Parameter Processing Code

There is a class called ParamsBase that contains the bulk of the parameter handling code. It has 2 sub-classes, Params, in source file params.h and params.cpp and Lhs, in source files lhs.h and lhs.cpp.

To add a new parameter to the parameter file processing you need to do the following. If the parameter is to be an attribute of a new XML node then the you need to add an item to the XmlElement enum in paramsbase.h. Make sure the NODE_COUNT enum item remains the last one. A corresponding entry then needs to be made to the NodeDescription array in paramsbase.cpp. If the new enum item is the nth item in the enum then the new entry in the NodeDescription array must also be the nth item in the array, since the enum items are used as indices into the array.

Each array element in the NodeDescription array is a structure of type NodeDescription, which has 3 members. In the new entry for the array, the first member should be the new XmlElement enum item, the 2nd member should be a string that will be used as the XML node name in a parameter file (character case counts, "Tcell" is not the same as "TCELL") and the 3rd member is a text description (mostly for documentation purpose).

Once an XML node has been defined for the new parameter in the XmlElement enum and the NodeDescription array, add an enum item for it either in the ParamDoubleType enum or the ParamIntType enum, in paramsbase.h, depending on whether the parameter's values will be integer or floating point. Then add an item to the ParamDescription array in parambase.cpp. The first part of the ParamDescription array is for floating point parameters, the remaining part is for integer parameters. The ParameterDescription item for the new parameter must go in the proper place. If its enum is the nth item in the ParamDoubleType enum then it must be the nth item in the ParamDescription array. If its enum is the nth item in the ParamIntType enum then it must be the nth item after the last floating point item in the ParamDescription array. This is because the enums are used as indices into the ParamDescription array.

Each array element in the ParamDescription array is a structure of type NodeDescription, which has 8 members:

name: A string that is the parameter name as it will appear in the parameter file.
xmlElement: The XML node it will be an attribute of in the parameter file - this is an XmlElement enum item.
probPos: A boolean which specifies whether or not this parameter is a probability (should have values between 0 and 1), if the parameter is a floating point parameter, or specifies whether this parameter should have values >= 0 if the parameter is an integer parameter. If this member is true then when this parameter is read from a parameter file and if it violates the constraint an error message is produced and the model does not run (but the remaining parameters in the parameter file are processed).
useDefault: A boolean which specifies whether or not a default value will be used. If false then this parameter must appear in the parameter file. If true then it does not have to appear in the parameter file - a default value will be used.
doubleDefault and intDefault: Floating point and integer default values. Ignored if useDefault is false. If use default is true the one for the type of the parameter is used - doubleDefault for a floating point parameter and intDefault for an integer parameter. Even though only one can be used, by convention both are set to the same value, which is 0 if useDefault is false.
unit: A string for the unit for this parameter. It can be an empty string if the parameter is unitless. It is only used for display purposes, for example when showing the parameters in a window in the gui version of a model. It is not used to perform unit conversion.
description: A string description of the parameter, used for display purposes, for example when showing the parameters in a window in the gui version of a model.

No other coding changes are needed. When deleting a parameter, simply delete the items that were added when adding it.