Parameter and Table Display and Content - openmpp/openmpp.github.io GitHub Wiki

Home > Model Development Topics > Parameter and Table Display and Content

This topic describes how to control the display and presence of parameters and tables using statements in model code.

• OpenM++ User Interface
• Model Code

• Parameter groups Organizing parameters into a hierarchy
• Table groups Organizing tables into a hierarchy
• Dual UI Specifying a user interface with switchable simplified and detailed views
• Model trim down Creating a trimmed-down model by removing parameters and tables
• Derived parameters as tables Output derived parameters as tables

A parameter group is a named, ordered list of parameters and other parameter groups. Parameter groups can be used to organize the parameters of a model into a hierarchical structure for display and navigation in the model UI. A parameter or parameter group can be a component of zero, one, or more than one parameter groups.

In the hierarchical display of input parameters in the model UI, parameters and parameter groups which are not part of any other parameter group are displayed at the root level in lexicographical order by name.

Parameter groups can also be used to identify groups of parameters in other model code statements such as hide, parameters_retain, or (for derived parameters) parameters_to_tables.

The following example declares a parameter group named PG12_SchoolOneFate which consists of the model input parameter Educ1Model followed by three other parameter groups.

parameter_group PG12_SchoolOneFate  //EN Primary School 
{
    Educ1Model,
    PG10_SchoolOneFateBase,
    PG11_SchoolOneFateRefined,
    PG10_ShoolOneTracking
};

Derived parameters in a parameter_group are absent from the hierarchical display of parameters in the model UI. Derived parameters can be displayed in the UI as described below.

Modgen-specific: The Modgen-specific statement model_generated_parameter_group is treated as a synonym of parameter_group by OpenM++.

[back to topic contents]

Table groups are very similar to Parameter groups. They are used to display a model's tables in a hierarchy in the model UI. A table or table group can be a component of zero, one, or more than one table groups.

In the hierarchical display of tables in the model UI, tables and table groups which are not part of any other table group are displayed at the root level in lexicographical order by name.

Table groups are also used to identify groups of tables in other model code statements such as hide or tables_retain.

Table groups can be used for run-time table selection using model options Tables.Retain or Tables.Suppress.

The following example declares a table group named TG04_Education which consists of three other table groups.

table_group TG04_Education //EN Education
{
    TG04_Preschool,
    TG04_Primary,
    TG04_Secondary
};

[back to topic contents]

The OpenM++ UI can present either a simplified or a detailed model interface to the user, and the user can switch between the two dynamically in the UI by tapping a button. The simplified interface can contain fewer parameters and tables than the detailed interface. Which parameters and tables are displayed in each interface is specified in model source code using one or more hide or show statements. A model can contain either hide statements or show statements, but not both. If a model contains no hide or show statements, it has a single interface and the button to choose the simplified or detailed interface is absent from the UI. If a model has both interfaces, the simplified interface is displayed by default.

The hide statement syntax is like:

hide P02_Fertility, TG01_Life_Tables;

The arguments to hide can be the names of tables, parameters, or groups.

The show statement has the same syntax. The show statement hides all parameters, tables, and groups except those listed as arguments to show statements.

hide and show do not change which parameters or tables are present in the model. They should not be confused with suppress or retain statements in model code which burn in parameters or remove tables from the model itself when it is built: parameters_retain, parameters_suppress, tables_retain, tables_suppress.

hide and show should also not be confused with the run-time model options Tables.Suppress and Tables.Retain which specify which tables are output in a model run.

Modgen-specific: The Modgen hide syntax which surrounds arguments in parentheses is also recognized, and treated as described in the description of hide above. Modgen hide functionality is similar but not equivalent to ompp hide functionality. Modgen hide of a table suppresses it from the model, and is similar to the ompp tables_suppress statement. Modgen hide of a parameter does not remove it, but instructs the UI to not display it.

[back to topic contents]

A family of four model code statements can be used to trim down a model at build time by selectively suppressing parameters using parameters_suppress or tables using tables_suppress. Suppression of parameters or tables does not affect the simulation. The complementary statements parameters_retain and tables_retain specify that the model is only to contain specified parameters or tables, suppressing all others. Suppress and retain are mutually exclusive: The OpenM++ compiler will raise an error if model code contains both parameters_suppress and parameters_retain statements, or both tables_suppress and tables_retain statements.

Suppressed parameters are burned into the executable using values published when the model is built. Suppressed parameters are absent from the user interface and the model database, and from metadata in the database. Large models can benefit both in build time and start-up time by suppressing parameters, because there is no need to read suppressed parameters from the database when launching the model. Suppressing parameters can also simplify the UI of a deployed model.

Suppressed tables are completely removed from the model. Large models can benefit both in build time and run time by suppressing tables.

Table dependencies specified using the dependency statement are nevertheless respected if a suppressed table is required by a non-suppressed table. Suppressed tables which are required by other tables are computed internally but are otherwise invisible.

Branches of the parameter or table hierarchy which become empty because of parameter or table suppression are suppressed from the model metadata and the user interface.

The following example is an extract from a model code module SuppressRetain.ompp which was added to the large OncoSim model to create a trimmed-down test version of the model which contained only parameters and tables related to breast cancer.

parameters_retain
    SimulationSeed,
    SimulationCases,
    Breast_Cancer_Parameters
;

tables_retain
    TG01_Breast_Cancer_Tables
;

OpenM++ also includes the ability to selectively suppress tables at run-time using the model run options Tables.Suppress and Tables.Retain. These options allow a model user to economize processing time and storage by restricting output to specific tables of interest from the available tables in the model.

Unlike the model run options Tables.Suppress and Tables.Retain, the model code statements tables_suppress and tables_retain remove tables completely from a model. That can improve model build time, run time, and run storage, but tables suppressed at build time are not available to users at run time.

A model with suppressed parameters builds faster because its metadata and Default values are not published to the model database. The model also launches faster because there is no need for it to read the suppressed parameters from the database when the model starts. A suppressed parameter can be made visible and editable in the model UI by changing the suppress/retain statement and rebuilding the model. This can be simpler than using the Fixed parameter mechanism which requires moving the file containing the parameter values between two folders.

Models can contain diagnostic tables used for testing and development, but which are only needed occasionally subsequently. Instead of commenting out or removing such tables, they can be kept, but added to a table group and then suppressed using tables_suppress. Doing so ensures that the diagnostic tables continue to be parsed and verified when the model is built, without imposing additional complexity or costs to the published model.

During model development, a model is often modified, built, and run repeatedly when working on a specific component. That iterative development process can be accelerated by using parameters_retain and tables_retain temporarily to focus only on the parameters and tables associated with the current development activity. That optimizes the model to the current development activity without changing the simulation logic. After the development activity is complete, the temporary parameters_retain and tables_retain statements can be removed.

[back to topic contents]

A derived parameter is normally invisible in model inputs and outputs but can be made visible by exporting it as a derived table using the parameters_to_tables statement.

The argument of parameters_to_tables is a comma separated list of derived parameters or groups of derived parameters. Model code can contain multiple occurrences of parameters_to_tables.

The corresponding derived table

• has the same name as the derived parameter
• has the same metadata as the derived parameter including parameter label, note, dimension labels, and dimension names
• converts parameter values to double, with classifications, ranges, and partitions converted to {0,1,2,...} and bool converted to {0,1}, where 0 is false and 1 is true.
• has an implicit dimension for sub/member/replicate for runs with multiple subs
• computes, for overall run results, the average across subs (like other derived tables)

A derived table created by parameters_to_tables acts like other derived tables and can be

• displayed in the UI as a multi-dimensional table
• organized in the hierarchical display of tables in the model UI using table_group
• suppressed or retained in model outputs using tables_suppress or tables_retain
• exported in csv format for downstream analysis either from the UI or by using dbcopy
• used in model output comparisons with test_models

A derived parameter (aka model-generated parameter) is declared using the derived keyword. It is computed by model code before the simulation starts using values of other parameters.

Modgen-specific: In Modgen, derived parameters are declared using the keyword model_generated. OpenM++ treats model_generated as a synonym of derived. In Modgen, derived tables are declared using the keyword user_table. OpenM++ treats user_table as a synonym of derived_table.

For example, here's the declaration of the derived parameter ImmigrantDonors in the OzProj model:

parameters
{
  ...
  //EN Number of immigrant donors in initial population
  model_generated int ImmigrantDonors;
  ...
};

OzProj computes the value of ImmigrantDonors in the function PersonCore_PreSimulation by counting microdata input records which satisfy particular conditions. The computation depends on the input parameter MicroDataInputFile which gives the name of the file containing input microdata.

Derived parameters are not editable and are not present in the hierarchical display of parameters in the model UI. However, parameters_to_tables makes selected derived parameters visible in the UI by converting them to derived tables.

The following statement in OzProj makes the 7 derived parameters in OzProj visible as identically-named derived tables in the model UI.

parameters_to_tables
    EmigrationHazard,
    FertilityHazard,
    MortalityHazard,
    ImmigrantDonors,
    EmigrationHazard,
    FertilityHazard,
    MortalityHazard
;

Every parameter specifies the type of its value(s), e.g. double, int, bool, REGION, AGE_GROUP. Because the value of a table cell is always double, parameters_to_tables may need to convert the parameter value type to double in the derived table. The conversion follows normal C++ type conversion rules. This includes converting parameter values of type Range, Classification or Partition to {0,1,2,...}, and parameter values of type bool to {0,1}, where 0 is false and 1 is true.

Derived parameters transformed to derived tables can be members of a table group, e.g.

table_group DerivedParameters //EN Derived Parameters
{
    EmigrationHazard,
    FertilityHazard,
    MortalityHazard,
    ImmigrantDonors,
    EmigrationHazard,
    FertilityHazard,
    MortalityHazard
};

This allows them to be organized hierarchically in the UI, or suppressed/retained as a group using tables_suppress or tables_retain.

[back to topic contents]