File based Parameter Values - openmpp/openmpp.github.io GitHub Wiki

Home > Common Topics > File-based Parameter Values

This topic describes how parameter values can be be represented in files in OpenM++. File-based parameter values are used by several OpenM++ components including build, run, UI, scripting, import, export.

• Modgen-specific: CsvToDat utility: Command-line utility to convert CSV parameters to DAT format

• Introduction
• How to use CSV or TSV files for input parameters values
  • CSV or TSV file with dimension(s) and parameter value(s)
  • CSV or TSV file with dimension(s) and multiple parameter sub-values
  • CSV or TSV files with IDs as dimension(s) items
  • CSV or TSV file with parameter values only

In several contexts, the value(s) of a parameter can be in a file whose name is the name of the parameter followed by a suffix which indicates content and format.

For example, if a file named AgeBaselinePreg1.csv is present in the folder `RiskPaths/parameters/Default', it will be used by the OpenM++ compiler to provide values for that parameter when publishing the Default scenario when the model is built.

The suffix of the file indicates how the contents of the file are interpreted, as follows:

The header line contains the column names of indices as specified in the parameter declaration in model code. The header line can optionally start with an initial column named sub_id. If so, the first value in each line is the 0-based index of the replicate (aka sub, subsample, member).

[back to topic contents]

You can use CSV or TSV files to supply input parameter values for your model. For example, if the RiskPaths model has the SeparationDurationBaselineparameter:

partition DISSOLUTION_DURATION	//EN Duration since union dissolution
{
  2, 6, 10, 15
};
..........
// Separation Duration Baseline of 2nd Formation
double	SeparationDurationBaseline[DISSOLUTION_DURATION] = {
  0.1995702, 0.1353028, 0.1099149, 0.0261186, 0.0456905
};

then you can supply parameter values from RiskPaths/parameters/RiskPths.dat or from RiskPaths/parameters/SeparationDurationBaseline.csv:

dim0,      param_value
"(-∞,2)",  0.1995702
"[2,6)",   0.1353028
"[6,10)",  0.1099149
"[10,15)", 0.0261186
"[15,∞)",  0.0456905

If parameter values are coming from CSV or TSV file then you can use Markdown file(s) to provide parameter value notes. For example, RiskPaths/parameters/SeparationDurationBaseline.EN.md:

This is a parameter values for Separation Duration Baseline of 2nd Formation.

It is a test sample model and data may not be accurate.

and RiskPaths/parameters/SeparationDurationBaseline.FR.md:

**Translation below created by Google, please provide a proper French translation before publishing the model**

Il s'agit d'une valeur de paramètre pour la ligne de base de la durée de séparation de la 2e formation.

Il s'agit d'un modèle d'échantillon de test et les données peuvent ne pas être exactes.

The following rules are applied to parameter CSV or TSV files:

• file name must be the same as parameter name, which is SeparationDurationBaseline in example above
• it can be parameter.csv with comma-separated values or parameter.tsv with tab-separated values
• if dimension item name or parameter value contains comma then it must be "quoted"
• header line of the file must contain dimension names and "param_value", for example: dim0,otherDim,dim3,param_value
• (optional) if parameter has multiple sub-values then header line must start with "sub_id" (see example below)
• if the scenario directory contains a .dat file with values for ParameterName and also a file named ParameterName.csv the CSV values will override the .dat values.

The following formats of CSV or TSV files are supported:

• CSV or TSV file with dimension(s) and parameter value(s)
• CSV or TSV file with dimension(s) and multiple parameter sub-values
• CSV or TSV files with IDs as dimension(s) items
• CSV or TSV file with parameter values only, without dimensions (omc only)

Subsequent sub-topics describe each in turn, with examples.

[back to topic contents]

Dimension items must be supplied as item "names", similar to partition DISSOLUTION_DURATION above. Or take a look into another example of two-dimensional parameter:

classification SEX //EN Sex
{
  FEMALE,
  MALE
};
range YEAR //EN Year
{
  2019,
  2021
};
............
double GenderByYearRatio[SEX][YEAR] = {
  0.1, (2)0.2, 0.5, 0.6, 0.7
};

GenderByYearRatio.csv file:

dim0,   dim1, param_value
FEMALE, 2019, 0.1
FEMALE, 2020, 0.2
FEMALE, 2021, 0.2
MALE,   2019, 0.5
MALE,   2020, 0.6
MALE,   2021, 0.7

• Line order in the file is not important and openM++ will sort it automatically.
• If there some line(s) are missing then parameter value will be a default for that parameter type, for example: 0.0.

[back to topic contents]

It can be used for uncertainty probabilistic analysis, file example:

sub_id, dim0,   dim1, param_value
 0,     FEMALE, 2019, 0.1
 0,     FEMALE, 2020, 0.2
 0,     FEMALE, 2021, 0.2
 0,     MALE,   2019, 0.5
 0,     MALE,   2020, 0.6
 0,     MALE,   2021, 0.7
 1,     FEMALE, 2019, 1.1
 1,     FEMALE, 2020, 1.2
 1,     FEMALE, 2021, 1.2
 1,     MALE,   2019, 1.5
 1,     MALE,   2020, 1.6
 1,     MALE,   2021, 1.7
...........

• Header line must start with "sub_id" in order to indicate presnse of sub values in parameter.csv file.
• Sub value id's can be any integer values, for example: -1, 0, 4, 8, 12, 42. It must be integer but does not need to be positive or sequential.
• The first sub value id in a CSV file is considered to be the "default" sub value for that parameter.

[back to topic contents]

You can use dimension item ID instead of item names, for example SeparationDurationBaseline.id.csv:

dim0, param_value
0,    0.1995702
1,    0.1353028
2,    0.1099149
3,    0.0261186
4,    0.0456905

GenderByYearRatio.id.csv:

dim0, dim1, param_value
0,    0,    0.1
0,    1,    0.2
0,    2,    0.2
1,    0,    0.5
1,    1,    0.6
1,    2,    0.7

Please notice file naming convention: ParameterName.id.csv or ParameterName.id.tsv

[back to topic contents]

This format is only supported for parameters read at build time by the OpenM++ compiler (omc).

In this format the file contains only parameter value(s) without dimensions, for example SeparationDurationBaseline.value.csv:

  0.1995702, 0.1353028, 0.1099149, 0.0261186, 0.0456905

GenderByYearRatio.value.csv:

  0.1, 0.2, 0.2,
  0.5,
  0.6, 0.7

• Please note the file naming convention: ParameterName.value.csv or ParameterName.value.tsv
• Values in the file must be ordered according to the dimension order in the parameter declaration, ie the same order as in a .dat file.
• Any number of values may be given on each line.
• Each pair of values must be separated by a comma, including the last value on a line and the first value on the subsequent line.

[back to topic contents]