Oms API Read Run Parameter value - openmpp/openmpp.github.io GitHub Wiki
Read a "page" of parameter values from model run.
Page is part of parameter values defined by zero-based "start" row number and row count. If row count <= 0 then all rows below start row number returned.
Dimension(s) and enum-based parameters returned as enum codes. Dimension type or parameter type is simple (integer or boolean) then string value used (ex.: "true", "1234").
Method verb must be POST and Content-Type header "application/json". JSON body POSTed to specify parameter name, page size, row count, filters and row order. It is expected to be JSON representation of db.ReadLayout structure from Go library.
Method:
POST /api/model/:model/run/:run/parameter/value
For example:
curl -v -X POST -H "Content-Type: application/json" http://localhost:4040/api/model/modelOne/run/Default/parameter/value -d @test.json
curl -v -X POST -H "Content-Type: application/json" http://localhost:4040/api/model/modelOne/run/2016_08_17_21_07_55_123/parameter/value -d @test.json
Arguments:
:model - (required) model digest or model name
Model can be identified by digest or by model name. It is recommended to use digest because it is uniquely identifies model. It is possible to use model name, which is more human readable than digest, but if there are multiple models with same name in database than result is undefined.
:run - (required) model run digest, run stamp or run name
Model run can be identified by run digest, run stamp or run name. It is recommended to use digest because it is uniquely identifies model run. Run stamp, if not explicitly specified as model run option, automatically generated as timestamp string, ex.: 2016_08_17_21_07_55_123. It is also possible to use name, which is more human readable than digest, but if there are multiple runs with same name in database than result is undefined.
JSON body arguments:
For example:
{
"Name": "ageSex",
"Offset": 0,
"Size": 100,
"IsFullPage": true,
"IsSubId": true,
"SubId": 2,
"Filter": [{
"Name": "AgeGroup",
"Op": "IN",
"Values": ["20-30", "30-40", "40+"]
}, {
"Name": "Sex",
"Op": "=",
"Values": ["F"]
}
],
"OrderBy": [{
"IndexOne": 2,
"IsDesc": true
}, {
"IndexOne": 3,
"IsDesc": true
}
]
}
Name - (required) parameter name
Offset - (optional) zero-based start row to select parameter values
Size - (optional) max row count to select parameter values.
IsFullPage - (optional) if true then always return non-empty last page of data.
IsSubId - (optional) if true then select only single sub-value, default: all sub-values
SubId - (optional) sub-value id to select if IsSubId is true
Filter - (optional) conditions to filter dimension enum code(s)
OrderBy - (optional) list of columns indexes (one based) to order by
By default oms service selects 100 rows (it can be configured). If Size <= 0 specified then all rows selected.
Filter conditions joined by AND and can have following operations:
= - enum equal to: AgeGroup = "20-30"
!= - enum not equal to: AgeGroup <> "20-30"
> - enum greater than: AgeGroup > "20-30"
>= - enum greater or equal: AgeGroup >= "20-30"
< - enum less than: AgeGroup < "20-30"
<= - enum less or equal: AgeGroup <= "20-30"
IN - enum is in the list of: AgeGroup IN ("20-30", "30-40", "40+")
BETWEEN - between min and max: AgeGroup BETWEEN "30-40" AND "all"
IN_AUTO - automatically choose most suitable: = or != or IN or BETWEEN
Keep in mind: dimension enums are always ordered by id's, not by code and result of filter Sex < "M" may not be Sex = "F".
Order by specified by one-based column(s) index(es) in result. In case of parameters columns are:
SELECT sub_id, dim0, dim1, ..., param_value FROM parameterTable ORDER BY 1, 2,...
Columns always contain enum id's, not enum codes and therefore result ordered by id's
JSON response:
{
Layout: {
Offset: actual first row number of the page data (zero-base),
Size: actual data page row count,
IsLastPage: true if this is last page of data
},
Page: [....page of data...]
}
Example 1:
JSON body:
{
"Name": "ageSex",
"Filter": [],
"OrderBy": []
}
Result:
< HTTP/1.1 200 OK
< Content-Type: application/json
< Date: Fri, 14 Dec 2018 01:53:21 GMT
< Content-Length: 544
<
{"Layout":{"Offset":0,"Size":8,"IsFullPage":false,"IsLastPage":true}
,"Page":[{"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}
]}
Example 2:
JSON body:
{
"Name": "ageSex",
"Offset": 6,
"Size": 4,
"IsFullPage": true,
"Filter": [],
"OrderBy": []
}
Result:
{"Layout":{"Offset":6,"Size":2,"IsFullPage":true,"IsLastPage":true}
,"Page":[{"Dims":["40+","M"],"IsNull":false,"Value":0.7,"SubId":0}
,{"Dims":["40+","F"],"IsNull":false,"Value":0.8,"SubId":0}
]}
Example 3:
JSON body:
{
"Name": "ageSex",
"Offset": 2,
"OrderBy": [{
"IndexOne": 2,
"IsDesc": true
}, {
"IndexOne": 3,
"IsDesc": true
}
]
}
Result:
{"Layout":{"Offset":2,"Size":6,"IsFullPage":false,"IsLastPage":true}
,"Page":[{"Dims":["30-40","F"],"IsNull":false,"Value":0.6,"SubId":0}
,{"Dims":["30-40","M"],"IsNull":false,"Value":0.5,"SubId":0}
,{"Dims":["20-30","F"],"IsNull":false,"Value":0.4,"SubId":0}
,{"Dims":["20-30","M"],"IsNull":false,"Value":0.3,"SubId":0}
,{"Dims":["10-20","F"],"IsNull":false,"Value":0.2,"SubId":0}
,{"Dims":["10-20","M"],"IsNull":false,"Value":0.1,"SubId":0}
]}
Example 4:
There are 3 filters applied to ageSex parameter:
- age group dimension:
dim0 IN ["20-30", "40+"] - AND sex dimension:
dim1 = "F" - AND parameter values:
param_value < 0.5
JSON body:
{
"Name": "ageSex",
"Offset": 0,
"Size": 100,
"Filter": [{
"Name": "dim0",
"Op": "IN",
"Values": ["20-30", "40+"]
}, {
"Name": "dim1",
"Op": "=",
"Values": ["F"]
}, {
"Name": "param_value",
"Op": "<",
"Values": ["0.5"]
}
]
}
Result:
{
"Page":[
{"Dims":["20-30","F"],"IsNull":false,"Value":0.4,"SubId":0}
],
"Layout":{"Offset":0,"Size":1,"IsLastPage":true,"IsFullPage":false}
}