Model Data Get and Set Quick Start - openmpp/openmpp.github.io GitHub Wiki

Overview

There multiple examples how to set input parameters, run the model and get results:

Also openM++ support following APIs:

Quick examples below do not cover all possible options, please check links above and Model Run: How model finds input parameters for more details.

Sub-values: sub-samples, members, replicas

Following terms: "simulation member", "replica", "sub-sample" are often used in micro-simulation conversations interchangeably, depending on context. To avoid terminology discussion openM++ uses "sub-value" as equivalent of all above and some older pages of that wiki may contain "sub-sample" in that case.

Model output tables: sub-values, accumulators and expressions

There are two kind of model output tables:

  • accumulators table: output sub-values (similar to Modgen sub-samples)
  • expressions table: model output value calculated as accumulators aggregated across sub-values (e.g. mean or CV or SE)

All output accumulator tables always contain same number of sub-values, for example model run:

model.exe -OpenM.SubValues 16

will create 16 sub-values for each accumulator in each output accumulator table.

Model parameters: sub-values (optional)

OpenM++ parameters can also contain sub-values. Parameters sub-values are not required, it is a user choice to run the model and supply sub-values for some parameters.

For example, if user wants to describe statistical uncertanty of parameter SalaryByYearByProvince then csv file with 16 sub-values can be supplied to run the model:

model.exe -OpenM.SubValues 16 -SubFrom.SalaryByYearByProvince csv -OpenM.ParamDir C:\MyCsv\

Parameters: Re-use same parameters values as in previous model run

Most of the model parameters are not changing between simulations and only few are varying. It is convenient to select all unchanged parameters from previous model run (from "base" run):

model.exe -Parameter.Ratio 0.7 -OpenM.BaseRunId 1234
model.exe -Parameter.Ratio 0.7 -OpenM.BaseRunDigest 5dc848891ea57db19d8dc08ec7a30804
model.exe -Parameter.Ratio 0.7 -OpenM.BaseRunName "My base run of the Model"

Above command do run the model with parameter Ratio = 0.7 and the rest of parameters values are the same as it was in previous run with id = 1234.

It is also possible to use run diegst or run name to identify "base" model run:

model.exe -Parameter.Ratio 0.7 -OpenM.BaseRunDigest 5dc848891ea57db19d8dc08ec7a30804
model.exe -Parameter.Ratio 0.7 -OpenM.BaseRunName "My base run of the Model"

Please keep in mind, model run may not be unique and if database contains multiple model runs with the same name then first run will be selected.

Parameter: Value as command line argument

It is possible to specify value of any scalar parameter as command line argument, for example:

model.exe -Parameter.Ratio 0.7

There is an example of such technique at Run model from R: simple loop over model parameter page, where we using NewCaseBased model to study effect of Mortality Hazard input parameter on Duration of Life output:

for (mortalityValue from 0.014 to 0.109 by step 0.005)
{
  # run the model
  NewCaseBased.exe -Parameter.MortalityHazard mortalityValue
}

If parameter is enum-based (e.g. classification) then you can specify code or enum id:

modelOne.exe -Parameter.baseSalary Full
modelOne.exe -Parameter.baseSalary 22 -OpenM.IdParameterValue true

Parameter: Sub-values [0, N-1] as command line argument

If we want to run the model with multiple sub-values (a.k.a. sub-samples) and want "Grade" parameter sub-values to be created as [0, N-1] then:

model.exe -OpenM.SubValues 16 -SubFrom.Grade iota

as result sub-values parameter Grade would be: [0, ..., 15]

Parameter: Value inside of ini.file

Also any scalar parameter can be defined in model ini-file, i.e.:

model.exe -ini my.ini

; inside of my.ini file:
;
[Parameter]
Z_Parameter = XYZ      ; string parameter
SomeInt     = 1234     ; integer parameter
OrLogical   = true     ; boolean parameter
Anumber     = 9.876e5  ; float parameter

Parameters: Csv files

It is also possible to supply some (or even all) model parameters as csv-file(s). For example:

model.exe -OpenM.ParamDir C:\my_csv

If directory C:\my_csv\ exist and contains parameterName.csv files then model will use it parameter values.

It is important to describe your parameter values to make sure model users clearly understand scenario data. In order to do that you can supply parameterName.LANG-CODE.md file(s).

For example, C:\my_csv\Sex.csv values of "Sex" parameter:

sub_id,dim0,param_value
0,     F,   true
0,     M,   false

And parameter value notes C:\my_csv\Sex.EN.md:

Sex parameter values in this scenario contain indicators of increased gender-specific hazards.

Note: As it is today Markdown content of parameter value notes may not always display correctly in openM++ UI.

Parameters: Csv files with multiple sub-values

If user want to supply up to 32 sub-values of "Sex" parameter:

sub_id,dim0,param_value
0,     F,   true
0,     M,   false
1,     F,   true
1,     M,   true
.................
31,    F,   false
31,    M,   true

Important: Presence of multiple sub-values in csv file (or in database) does not mean model will use all parameter sub-values. Only explicitly specified parameter(s) receiving sub-values.

For example, if user run the model 3 times:

model.exe -OpenM.SubValues 16
model.exe -OpenM.SubValues 16 -OpenM.ParamDir C:\my_csv
model.exe -OpenM.SubValues 16 -OpenM.ParamDir C:\my_csv -SubFrom.Sex csv
  • "Sex" parameter expected to be in database and no sub-values used
  • "Sex" parameter value is sub-value 0 from C:\my_csv\Sex.csv
  • "Sex" parameter using sub-values [0, 15] from C:\my_csv\Sex.csv

Output Tables: Suppress output tables

By default model calculate all output tables and write it into database as model run results. Sometime it may be convenient to save only some output tables to reduce a time of each model run. This can be done by either suppressing model output table(s) or table group(s):

model.exe -Tables.Suppress ageSexIncome
model.exe -Tables.Suppress ageSexIncome,fullAgeSalary,A_TablesGroup

Or by suppressing output for all tables except of some:

model.exe -Tables.Retain ageSexIncome
model.exe -Tables.Retain ageSexIncome,fullAgeSalary,A_TablesGroup

Suppress and Retain options are mutually exclusive and cannot be mixed. For example, this model run would fail:

model.exe -Tables.Suppress ageSexIncome -Tables.Retain fullAgeSalary

Use dbcopy: Export entire model into text files

dbcopy -m modelOne
dbcopy -m modelOne -dbcopy.Zip
dbcopy -m modelOne -dbcopy.NoAccumulatorsCsv
dbcopy -m modelOne -dbcopy.NoMicrodata

It will create modelOne directory and modelOne.Zip file with:

  • all model metadata (e.g. parameters, description, notes,...) in .json files
  • csv files with sets of model input parameters
  • csv files with model run results, input parameters and microdata

You can create .tsv output files instead of .tsv:

dbcopy -m modelOne -dbcopy.IntoTsv
dbcopy -m modelOne -dbcopy.IntoTsv -dbcopy.Zip

Model run microdata can be huge and if you are not intersted in it then use -dbcopy.NoMicrodata to suppress it:

dbcopy -m modelOne -dbcopy.NoMicrodata

For each model run output table openM++ store expression values (e.g. average, CV, SE) and also accumulators. Accumulators are sub-samples (a.k.a. sub-values or members or replicas, etc.) which used to produces output table aggregated expression value(s). By default dbcopy do output both: output table expressions and accumulators. If you are interestred only expression values then use -dbcopy.NoAccumulatorsCsv to suppress accumulators and get your results faster:

dbcopy -m modelOne -dbcopy.NoAccumulatorsCsv

Use dbcopy: Export entire model into csv files

dbcopy -m modelOne -dbcopy.To csv
dbcopy -m modelOne -dbcopy.To csv -dbcopy.Zip
dbcopy -m modelOne -dbcopy.To csv -dbcopy.NoAccumulatorsCsv

It will create modelOne directory and modelOne.Zip file with:

  • all model metadata (e.g. parameters, description, notes,...) in .csv files
  • csv files with sets of model input parameters
  • csv files with model run results and input parameters Each model run result and each input parameters set will be in separate sub-directory. Use -dbcopy.NoAccumulatorsCsv option to get your results faster by suppressing accumulators (a.k.a sub-sanples) output to CSV files.

You can create .tsv output files instead of .tsv:

dbcopy -m modelOne -dbcopy.To csv -dbcopy.IntoTsv
dbcopy -m modelOne -dbcopy.To csv -dbcopy.IntoTsv -dbcopy.Zip

Other variation of csv output is:

dbcopy -m modelOne -dbcopy.To csv-all
dbcopy -m modelOne -dbcopy.To csv-all -dbcopy.IntoTsv

In that case all model runs will be in "all_model_runs" sub-directory and all input sets are in "all_input_sets".

You can suppress zero values and / or NULL (missing) values in output tables and microdata CSV files:

dbcopy -m modelOne -dbcopy.To csv -dbcopy.NoZeroCsv
dbcopy -m modelOne -dbcopy.To csv -dbcopy.NoNullCsv
dbcopy -m modelOne -dbcopy.To csv -dbcopy.NoNullCsv -dbcopy.NoZeroCsv

Use dbcopy: Export set of input parameters into text files

dbcopy -m modelOne -s modelOne_other -dbcopy.ParamDir pDir

It will create pDir directory with:

  • input parameters set metadata (name, description, notes,...) in .json file
  • csv files with sets of model input parameters

Use dbcopy: Export model run results into text files

dbcopy -m modelOne -dbcopy.LastRun
dbcopy -m modelOne -dbcopy.RunId 101
dbcopy -m modelOne -dbcopy.RunName modelOne_2016_11_22_11_38_49_0945_101
dbcopy -m modelOne -dbcopy.LastRun -dbcopy.NoAccumulatorsCsv

It will create a directory with:

  • model run metadata (name, description, notes,...) in .json file
  • csv files with input parameters used to run the model
  • csv files with model output tables values Use -dbcopy.NoAccumulatorsCsv option to get your results faster by suppressing accumulators (a.k.a sub-sanples) output to CSV files.

Use dbcopy: Import parameters from csv files into database

dbcopy -m myModel -s MyInput -dbcopy.ParamDir P -dbcopy.ToSqlite myModel.sqlite

If any parameterName.csv file(s) exist in directory P then it will be loaded into MyInput set of input parameters.

It is recommended to run dbcopy -m modelOne -s modelOne_other -dbcopy.ParamDir P to get familiar how csv files look like.

Use dbcopy: Import parameters, description and notes from text files into database

dbcopy -m myModel -s MyInput -dbcopy.ToSqlite myModel.sqlite

It will insert or update MyInput set of input parameters in database with:

  • if json metadata file exist then input set description, notes and parameter value note updated
  • if any parameterName.csv files exist then it will be loaded into database

It is recommended to run dbcopy -m modelOne -s modelOne_other -dbcopy.ParamDir P to get familiar how json and csv files look like.

Example of json metadata file for "ageSexData" input set of parameters with description, notes and ageSex parameter value notes:

{
  "ModelName" : "modelOne",
  "Name" : "ageSexData",
  "Txt" : [{
      "LangCode" : "EN",
      "Descr" : "Model One set of parameters"
    }
  ],
  "Param" : [{
      "Name" : "ageSex",
      "SubCount" : 1,
      "Txt" : [{
          "LangCode" : "EN",
          "Note" : "Age by Sex values"
        }
      ]
    }
  ]
}

It is also must exist csv file with parameter values: ageSex.csv

Example of json metadata file for "emptyData" input set of parameters with description and notes in English and French:

{
  "ModelName" : "modelOne",
  "Name" : "emptyData",
  "Txt" : [{
      "LangCode" : "EN",
      "Descr" : "Model One set of parameters",
      "Note" : "Notes for model One set of parameters"
    }, {
      "LangCode" : "FR",
      "Descr" : "Je suis désolé je ne parle pas français"
    }
  ]
}
⚠️ **GitHub.com Fallback** ⚠️