Use Oms to prepare model input

Overview

OpenM++ provides multiple different ways to supply input parameters and run the models as described at:

• Model Run Cycle: How model finds input parameters
• Model Run: How to Run the Model

You don't have to do any programming or database operations in order to provide model input parameters, you can:

• provide parameter value as command line argument
• run model with default workset (default "scenario")
• use workset name ("scenario" name) to run the model
• use ini-file to provide model parameters
• supply parameter values as csv-file(s)

Also following API available for advanced parameter manipulation and output results processing:

• JSON web-service to use with any modern framework (.NET, JavaScript, Python, etc.)
• Go library and tools
• OpenMpp R package and R usage examples

Current page describe an usage of openM++ JSON web-service (oms) in order to prepare, examine and modify model input parameters. There are two terms are used in text below: "workset" and "base run". Please see Model Run Cycle: How model finds input parameters page for details.

Workset: set of model input parameters (a.k.a. "scenario")

Workset is a set of model input parameters in database which we can use to run the model. Each workset has unique name. Each model must have "default workset", which is a first set of model input parameters. Model user can create, modify and delete worksets.

Base run

Each model run started from creating full copy of model input parameters in database, which are used for that particular model run. Because usually only small portion of model parameters are changing between model runs it is convenient to create new workset (new "scenario") based on input parameters of previous model run, which is called "base run". In that case we only need to supply few modified parameter values and the rest is coming from "base run" parameters.

Start Oms: OpenM++ JSON web-service

Below we are using oms web-service to prepare model input. Most examples are created with browser output and curl to avoid any unnecessary programing languages details.

You can start oms web-service on Windows:

C:
cd \SomeDir\openmpp_win_20190508\
bin\oms.exe -oms.ApiOnly

Or Linux:

cd openmpp_debian_20190508/
bin/oms -oms.ApiOnly

If your models are not in models/bin sub-folder then use:

bin/oms -oms.ApiOnly -oms.ModelDir ../my_model_dir

Please see Oms web-service page for more details.

Get list of published models

We need to know model name at least, or better model digest to find or modify model input parameters. Open your favorite browser and type:

http://localhost:4040/api/model-list

Result can look like:

[
  {
    "ModelId": 1,
    "Name": "modelOne",
    "Digest": "_201208171604590148_",
    "Type": 0,
    "Version": "1.0",
    "CreateDateTime": "2012-08-17 16:04:59.0148",
    "DefaultLangCode": "EN"
  },
  {
    "ModelId": 101,
    "Name": "RiskPaths",
    "Digest": "db6e5168c74a73a4f5b194cb2a793444",
    "Type": 0,
    "Version": "3.0.0.0",
    "CreateDateTime": "2018-12-14 18:36:05.0272",
    "DefaultLangCode": "EN"
  }
]

Get list of model worksets (set of input parameters, a.k.a. "scenarios")

Go to:

http://localhost:4040/api/model/modelOne/workset-list

[
  {
    "ModelName": "modelOne",
    "ModelDigest": "_201208171604590148_",
    "Name": "Default",
    "BaseRunDigest": "",
    "IsReadonly": true,
    "UpdateDateTime": "2013-05-29 23:55:07.1234",
    "Txt": [],
    "Param": []
  },
........
]

Model default set of input parameters

First workset is a default set of model input parameters. You can explore more it at

http://localhost:4040/api/model/modelOne/workset/Default/text

and look at each parameter values, for example:

http://localhost:4040/api/model/modelOne/workset/Default/parameter/StartingSeed/value

[
  {
    "Dims": [],
    "IsNull": false,
    "Value": 8191,
    "SubId": 0
  }
]

Or

http://localhost:4040/api/model/modelOne/workset/Default/parameter/ageSex/value

[
{"Dims":["10-20","M"],"IsNull":false,"Value":0.1,"SubId":0}
,{"Dims":["10-20","F"],"IsNull":false,"Value":0.2,"SubId":0}
,{"Dims":["20-30","M"],"IsNull":false,"Value":0.3,"SubId":0}
,{"Dims":["20-30","F"],"IsNull":false,"Value":0.4,"SubId":0}
,{"Dims":["30-40","M"],"IsNull":false,"Value":0.5,"SubId":0}
,{"Dims":["30-40","F"],"IsNull":false,"Value":0.6,"SubId":0}
,{"Dims":["40+","M"],"IsNull":false,"Value":0.7,"SubId":0}
,{"Dims":["40+","F"],"IsNull":false,"Value":0.8,"SubId":0}
]

Model run results and run input parameters

To see the history of model runs:

http://localhost:4040/api/model/modelOne/run-list

[
  {
    "ModelName": "modelOne",
    "ModelDigest": "_201208171604590148_",
    "Name": "Default",
    "SubCount": 1,
    "SubStarted": 1,
    "SubCompleted": 1,
    "CreateDateTime": "2019-01-10 18:36:13.0655",
    "Status": "s",
    "UpdateDateTime": "2019-01-10 18:36:13.0669",
    "Digest": "6fbad822cb9ae42deea1ede626890711",
    "Txt": [],
    "Opts": {},
    "Param": [],
    "Progress": []
  },
........
  {
    "ModelName": "modelOne",
    "ModelDigest": "_201208171604590148_",
    "Name": "Parameter sub-values 2 from csv",
    "SubCount": 2,
    "SubStarted": 2,
    "SubCompleted": 2,
    "CreateDateTime": "2019-01-10 18:36:13.0745",
    "Status": "s",
    "UpdateDateTime": "2019-01-10 18:36:13.0762",
    "Digest": "ac72e96b549638d31acaf6ee965b23c2",
    "Txt": [],
    "Opts": {},
    "Param": [],
    "Progress": []
  },
........
]

Model run can be uniquely identified by run digest, for example above:

• digest: "ac72e96b549638d31acaf6ee965b23c2", run name: "Parameter sub-values 2 from csv"
• digest: "6fbad822cb9ae42deea1ede626890711", run name: "Default"

Run name may not be unique, but in examples below we going to use name just to improve readability.

To see the parameter value from particular model run:

http://localhost:4040/api/model/modelOne/run/Default/parameter/StartingSeed/value

[
  {
    "Dims": [],
    "IsNull": false,
    "Value": 1023,
    "SubId": 0
  }
]

Or

http://localhost:4040/api/model/modelOne/run/Default/parameter/baseSalary/value

[
  {
    "Dims": [],
    "IsNull": false,
    "Value": "Full",
    "SubId": 0
  }
]

Use model profile to supply parameter values

Profile is a set of key-value options, similar to ini-file, which can be used to run the model. Each profile can be identified by profile name. It may be more convenient to use profiles instead of ini-files because profiles are stored in database and you don't need to deal with multiple files in order to publish and run the model in cloud.

To create profile named seed-1-base-full with values of StartingSeed and baseSalary parameters :

curl -v -X PATCH -H "Content-Type: application/json" \
  "http://localhost:4040/api/model/modelOne/profile" \
  -d \
  '{ "Name": "seed-1-base-full", 
     "Opts": {
       "OpenM.StartingSeed": "1023",
       "OpenM.baseSalary": "Full"
     } 
  }'

Above curl command line is Linux specific, on Windows you must use ^ instead of \ for multi-line input and also double "quotes" and " instead of single 'quotes'.

To view model profile:

http://localhost:4040/api/model/modelOne/profile/seed-1-base-full

{
  "Name": "seed-1-base-full",
  "Opts": {
    "OpenM.StartingSeed": "1023",
    "OpenM.baseSalary": "Full"
  }
}

To modify profile value:

curl -v -X POST http://localhost:4040/api/model/modelOne/profile/seed-1-base-full/key/Parameter.StartingSeed/value/4095

You can create multiple profiles similar to above in order to run the model with different StartingSeed and baseSalary parameter values:

modelOne -OpenM.Profile seed-1-base-full
modelOne -OpenM.Profile seed-1-base-part
modelOne -OpenM.Profile seed-2-base-full
modelOne -OpenM.Profile seed-2-base-part

It is the same as supply parameter values on command line:

modelOne -Parameter.StartingSeed 1023 -Parameter.baseSalary Full
modelOne -Parameter.StartingSeed 1023 -Parameter.baseSalary Part
modelOne -Parameter.StartingSeed 2047 -Parameter.baseSalary Full
modelOne -Parameter.StartingSeed 2047 -Parameter.baseSalary Part

Above model runs are using profile or command line values of StartingSeed and baseSalary and all other parameters are coming from "default" workset (default set of input parameters, a.k.a. default "scenario").

Simple way to create new workset (input set of parameters)

If you already run the model then database contains run results in output tables and copy of input parameters of that model run. We can use previous run parameters as "base" for our new workset, modify only some of it and run our model again.

1. To create New-Set of model parameters based on model run named "Default" with digest "6fbad822cb9ae42deea1ede626890711":

curl -v -X PUT \
  -F 'workset={
       "ModelName": "modelOne",
       "Name": "New-Set",
       "BaseRunDigest": "6fbad822cb9ae42deea1ede626890711",
       "Txt": [
         { "LangCode": "EN", "Descr": "My new set of input parameters" }
       ],
       "Param": [
         {
           "Name": "StartingSeed",
           "SubCount": 1,
           "Txt": [
             { "LangCode": "EN", "Note": "Starting seed new value" }
           ],
           "Value": [
             {"Dims": [], "IsNull": false, "Value": 8191, "SubId": 0}
           ]
         },
         {
           "Name": "ageSex",
           "SubCount": 1,
           "Txt": [],
           "Value": [
             {"Dims": ["10-20","M"], "IsNull": false, "Value": 0.1, "SubId": 0},
             {"Dims": ["10-20","F"], "IsNull": false, "Value": 0.2, "SubId": 0},
             {"Dims": ["20-30","M"], "IsNull": false, "Value": 0.3, "SubId": 0},
             {"Dims": ["20-30","F"], "IsNull": false, "Value": 0.4, "SubId": 0},
             {"Dims": ["30-40","M"], "IsNull": false, "Value": 0.5, "SubId": 0},
             {"Dims": ["30-40","F"], "IsNull": false, "Value": 0.6, "SubId": 0},
             {"Dims": ["40+","M"],   "IsNull": false, "Value": 0.7, "SubId": 0},
             {"Dims": ["40+","F"],   "IsNull": false, "Value": 0.8, "SubId": 0}
           ]
         }
       ]
     }' \
  http://localhost:4040/api/workset-create

That New-Set conatins new values for StartingSeed and ageSex parameters. All other input values are identical to previous "Default" model run input.

Each input set of model parameters (each workset) must have unique name. Different models can have worksets with same name, i.e. each model can have workset with name "Default". If workset with the same name New-Set already exist then this method return an error.

You don't have to create workset based on previous model run, you can omit BaseRunDigest and include all parameter values in the new workset. However it may be difficult for complex model with hundreds input parameters.

Advanced way to create new workset (input set of parameters) based on previous model run

If you already run the model then database contains run results in output tables and copy of input parameters of that model run. We can use previous run parameters as "base" for our new workset, modify only some of it and run our model again.

1. To create new MyFirstSet of model parameters based on model run named "Default" with digest "6fbad822cb9ae42deea1ede626890711":

curl -v -X PUT \
  -F 'workset={
      "ModelName": "modelOne",
      "Name": "MyFirstSet",
      "BaseRunDigest": "6fbad822cb9ae42deea1ede626890711",
      "Txt": [
        { "LangCode": "EN", "Descr": "My first set of input parameters" }
      ]
     }' \
  http://localhost:4040/api/workset-replace

That workset does not yet include any new parameter values, all input is identical to previous "Default" model run input. In order to modify parameter values we first need to copy into our new workset from any model run, any other workset or upload as csv-file.

2. Copy parameter StartingSeed value into MyFirstSet workset from Default-4 model run:

curl -v -X PUT http://localhost:4040/api/model/modelOne/workset/MyFirstSet/copy/parameter/StartingSeed/from-run/Default-4

3. Copy parameter baseSalary value into MyFirstSet workset from modelOne_other workset:

curl -v -X PUT http://localhost:4040/api/model/modelOne/workset/MyFirstSet/copy/parameter/baseSalary/from-workset/modelOne_other

4. Upload parameter ageSex values into MyFirstSet workset from my_age_sex.csv csv file:

curl -v -X PATCH \
  -F 'workset={
      "ModelName": "modelOne",
      "Name": "MyFirstSet",
      "Param": [ 
        { "Name": "ageSex", "SubCount": 1 }
      ] 
     }' \
  -F 'parameter-csv=@my_age_sex.csv;filename=ageSex.csv' \
  http://localhost:4040/api/workset-merge

where content of my_age_sex.csv is:

sub_id,dim0,dim1,param_value
0,10-20,M,11
0,10-20,F,12
0,20-30,M,13
0,20-30,F,14
0,30-40,M,15
0,30-40,F,16
0,40+,M,17
0,40+,F,18

It is also possible to modify some part of parameter values. For example, ageSex parameter above is 4*3 matrix and if want to modify values:

 [30-40, M] = 0.15
 [30-40, F] = 0.16

then:

curl -v -X PATCH -H "Content-Type: application/json" \
  http://localhost:4040/api/model/modelOne/workset/MyFirstSet/parameter/ageSex/new/value \
  -d '[
      {"Dims": ["30-40", "M"], "IsNull": false, "SubId":0, "Value": 0.15},
      {"Dims": ["30-40", "F"], "IsNull": false, "SubId":0, "Value": 0.16}
    ]'

Finally our "MyFirstSet" input set contains new values for 3 parameters: StartingSeed, baseSalary, ageSex, which different from previous "base run" parameters. And now we can run our model with that new workset:

modelOne -OpenM.SetName MyFirstSet

It is also possible to delete parameter from workset, delete entire workset in order to cleanup database and perform some other operations. Please see Oms: openM++ web-service API for details.

Create or modify modeling task

Modeling task consists of multiple sets of input data and can be run in batch mode. There is an example of modeling task at Run RiskPaths model from R page where we creating 800 sets of input data to study Childlessness by varying

• Age baseline for first union formation
• Relative risks of union status on first pregnancy After preparing such modeling task we can submit RiskPath model to high performance cluster (HPC) grid or in cloud where model will read 800 input sets and produce 800 model run outputs.

It is also possible to create or modify or delete modeling task without R, using Oms JSON web-service from programming language of your choice.

In order to do this we need first to prepare our input worksets as described above and after that we can create modeling task. For example, if we have two worksets: MyFirstSet, MySecondSet then we can create task:

curl -v -X PUT -H "Content-Type: application/json" \
  http://localhost:4040/api/task-new \
  -d '{
    "ModelName": "modelOne",
    "Name": "MyTask",
    "Txt": [{
        "LangCode": "EN",
        "Descr": "Task to vary 3 parameters",
        "Note": "Study effect of 3 parameters on output results"
      }
    ],
    "Set": [
      "MyFirstSet",
      "MySecondSet"
    ]
  }'

You can see the list of modeling tasks:

http://localhost:4040/api/model/modelOne/task-list

examine task metadata, input sets or task run history:

http://localhost:4040/api/model/modelOne/task/MyTask/text
http://localhost:4040/api/model/modelOne/task/MyTask/sets
http://localhost:4040/api/model/modelOne/task/MyTask/runs

It is also possible to delete or modify task. For example, if you want to add MyThirdSet set of parameters to the task above:

curl -v -X PATCH -H "Content-Type: application/json" \
  http://localhost:4040/api/task \
  -d '{
    "ModelName": "modelOne",
    "Name": "MyTask",
    "Set": [
      "MyThirdSet"
    ]
  }'

After that task will contain 3 input worksets:

http://localhost:4040/api/model/modelOne/task/MyTask/sets

{
  "ModelName": "modelOne",
  "ModelDigest": "_201208171604590148_",
  "Name": "MyTask",
  "Txt": [],
  "Set": [
    "MyFirstSet",
    "MySecondSet",
    "MyThirdSet"
  ],
  "TaskRun": []
}

Now you can run the model with that task:

modelOne -OpenM.SubValues 16 -OpenM.TaskName MyTask -OpenM.TaskRunName MyTask-sub16

and examine history of modeling task run:

http://localhost:4040/api/model/modelOne/task/MyTask/runs

{
  "ModelName": "modelOne",
  "ModelDigest": "_201208171604590148_",
  "Name": "MyTask",
  "Txt": [],
  "Set": [],
  "TaskRun": [
    {
      "Name": "MyTask-sub16",
      "SubCount": 16,
      "CreateDateTime": "2019-01-16 04:38:53.0298",
      "Status": "s",
      "UpdateDateTime": "2019-01-16 04:38:53.0461",
      "TaskRunSet": [
        {
          "Run": {
            "Name": "MyTask_sub16_MyFirstSet_2019_01_16_04_38_53_0304_111",
            "SubCompleted": 16,
            "CreateDateTime": "2019-01-16 04:38:53.0304",
            "Status": "s",
            "Digest": "1cece5a11d522b6225d7f9cb5afda39a"
          },
          "SetName": "MyFirstSet"
        },
        {
          "Run": {
            "Name": "MyTask_sub16_MySecondSet_2019_01_16_04_38_53_0357_112",
            "SubCompleted": 16,
            "CreateDateTime": "2019-01-16 04:38:53.0357",
            "Status": "s",
            "Digest": "4a55cd6614f8f7be439c0776b2a473ab"
          },
          "SetName": "MySecondSet"
        },
        {
          "Run": {
            "Name": "MyTask_sub16_MyThirdSet_2019_01_16_04_38_53_0410_113",
            "SubCompleted": 16,
            "CreateDateTime": "2019-01-16 04:38:53.0410",
            "Status": "s",
            "Digest": "d112237f501317422943880eca54d07b"
          },
          "SetName": "MyThirdSet"
        }
      ]
    }
  ]