Skip to main content

Simulation Results

Retrieve Simulation Query data​

Description​

Envizage Query Language is they query language designed for retrieving the requested data from the simulation of a household. The syntax of the language is an array of query expressions. Each query expression is an array composed of 3 comma-separated expressions. The expressions are JSON objects:

  1. The dataset expression: Properties on the dataset used, when the data extraction will take place, etc.
  2. The filter expression: Properties on which our dataset will be filtered.
  3. The projection expression: Properties of the dataset or calculated values based on the defined reduce operators to be shown in the final results after the data extraction has been performed

Specification​

Dataset Expression JSON Object​

It has the following fields:

FieldTypeDescriptionPossible valuesConstraints
datasetStringSpecify which dataset to query. There are 2 options, the simulation (data) or goal (goal) dataset.data, goalMust not be null
nameStringLabel the output result object with a name field
gatherStringSpecifies whether the data will be captured before or after the simulated timestep is finished. This field is optional and the default value is before. For the goal dataset it always defaults to after whether the property is set or notbefore, afterApplicable only to the data dataset.
aggregateStringSpecify by which property data will be grouped by. This property is optional, if specified we need to specify exactly one reduce operators on the projection expression (see 3rd object). Such reduce operators are $min, $max, $count, $pct. Aggregation type "goalId" is only acceptable with dataset "goal".timestepId, lifeId, goalId
runStringSpecify from which diagnostic run we will query the data. This only applies on a diagnostic run. Default value is BASE. More values can be found in the Appendix.Check the Appendix.
bandsObjectSpecifies whether Goal Achievability should also be reported in specific bands. Bands are defined as the area of probabilities enclosed between the array of percentiles passed as parameters. For example the following expression "bands": { "cell": "BS@NET_WORTH@TOTAL", "percentiles": [5, 50, 95 ]} defines 2 bands. One band that encloses the lives whose total net worth lies between the 5% and 50% percentile of total net worths across all lives and a second band with percentiles ranging from 50% to 95%Applicable only to the goal dataset.

Examples​

{ "dataset": "data", "name": "data" }
{ "dataset": "data", "name": "50th percentile" }
{ "dataset": "data", "name": "50th percentile", "gather": "after" }
{ "dataset": "data", "name": "data", "aggregate": "timestepId" }
{ "dataset": "goal", "name": "Goal Achievability", "gather": "after" }

Filter Expression JSON Object​

It has exactly the same semantics as the MongoDB query language filtering expression. If the JSON is empty, then no filtering is applied. The available comparison operators are the following:

OperatorDescriptionConstraints
$gtSelects the data where the value of the field is greater than (i.e. >) the specified value.Accepts only numeric values.
$gteSelects the data where the value of the field is greater than or equal to (i.e. >=) the specified value.Accepts only numeric values.
$inSelects the data where the value of the field equals any of the value in the specified array.Accepts both numeric and string values.
$ltSelects the data where the value of the field is less than (i.e. <) the specified value.Accepts only numeric values.
$lteSelects the data where the value of the field is less than or equal to (i.e. <=) the specified value.Accepts only numeric values.

All the available queryable timestep data properties can be found in the Appendix in the Query Language section.

Examples​

{ }
{ "lifeId": 5 }
{ "lifeId": 5, "timestepId": 10 }
{ "timestepId": { "$lt": 5 } }
{ "BS@NET_WORTH@TOTAL": { "$gte": 50000 } }
{ "timestepId": { "$in": [ 1, 2 ]} }

Projection Expression JSON Object​

It has similar semantics as the MongoDB query language projection expression:

  • One or more fields with value “1” will be included only from the available data in the final result.
  • One or more fields with value “0” will be excluded from the available data in the final result.
  • A statement cannot have both inclusion and exclusion statements.

Few noticeable differences:

  1. It will allow only one reduce operator (any of $min, $max, $count, $pct) and only if in the dataset expression the aggregate property has been specified.
  2. $pct operation is the percentile operator that does not exist in MongoDB. It accepts an array of properties with the first being the data field and the second which percentile we want (e.g. 50 being the 50th percentile). Check the 3rd example below for the syntax.
  3. The rest of the remaining projected fields, will be taken from the life or timestep selected by the reduce operator. In case of the $count operator, it will take the last matched aggregated field.

Examples​

{ "lifeId": 1 }
{ "timestepId": 1, "BS@NET_WORTH@TOTAL": 1 , "maximum": { "$max": "BS@NET_WORTH@SAVINGS_AND_INVESTMENTS" } }
{ "timestepId": 1, "BS@NET_WORTH@TOTAL": 1 , "percentile": { "$pct": [ "BS@NET_WORTH@SAVINGS_AND_INVESTMENTS", 50 ] } }
{ "timestepId": 1, "BS@NET_WORTH@TOTAL": 1 , "total": { "$count": 1 } }

Putting it all Together​

So, one query expression could look like the following:

[
  [
    { "dataset": "data" },
    { "BS@NET_WORTH@TOTAL": { "$gte": 50000 } },
    { "timestepId": 1, "BS@NET_WORTH@TOTAL": 1 }
  ],
  [
    { "dataset": "data", "name": "50th percentile", "aggregate": "timestepId" },
    {},
    {
      "timestepId": 1,
      "BS@NET_WORTH@TOTAL": 1,
      "pct": { "$pct": ["BS@NET_WORTH@SAVINGS_AND_INVESTMENTS", 50] }
    }
  ]
]

Results Format​

The results will be an array of results, mapped 1 to 1 as the array of queries. Named queries (name field on dataset object) will yield a named result entry on the results array.

[
  { "results": [ {...}, {...}, {...} ] },
  { "name": "50th percentile", "results": [ {...}, {...}, {...} ] },
]

Trigger Simulation Query Data​

POST {api-url}/scenarios/{scenarioId}/execute

Description​

In order to extract the results of the simulations, we need to execute the scenario simulation as shown in the example below.

Example Request​

curl 'https://api.envizage.me/scenarios/{scenarioId}/execute' -i -X POST \
            -H 'Content-Type: application/json;charset=UTF-8' \
            -H 'Authorization: Bearer {YOUR_ACCESS_TOKEN}' \
            -d '"[[{\"dataset\":\"goal\",\"aggregate\":\"goalId\",\"name\":\"Total Achieved\",\"gather\":\"after\"},{\"achieved\":1},{\"totalAchieved\":{\"$count\":1}}],[{\"dataset\":\"goal\",\"aggregate\":\"goalId\",\"name\":\"Total Alive\",\"gather\":\"after\"},{\"GP@primaryAlive\":1},{\"totalAlive\":{\"$count\":1}}]]"'

Example HTTP Response​

HTTP/1.1 200 OK

Retrieve Simulation Query Data Results​

GET /results/{scenarioId}/query/results

Description​

This call retrieves the scenario simulation execution results.

Example Request​

curl 'https://api.envizage.me/results/1/query/results' -i -X GET \
            -H 'Authorization: Bearer {YOUR_ACCESS_TOKEN}'

Example HTTP Response​

HTTP/1.1 200 OK
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Type: application/json
Content-Length: 732

{
  "id" : "2c991e2c79414de5017a8ba041955d75",
  "scenarioId" : "1",
  "simulationId" : "5220b7a4-34b6-469d-b5b6-8c20fde6ffde",
  "clientId" : "test",
  "username" : "test",
  "results" : [ {
    "name" : "Total Achieved",
    "results" : [ {
      "goalId" : "609907ca34b4543f0502dc83",
      "data" : {
        "totalAchieved" : 498
      }
    }, {
      "goalId" : "6093e72d2c23d27143f1d071",
      "data" : {
        "totalAchieved" : 93
      }
    } ]
  }, {
    "name" : "Total Alive",
    "results" : [ {
      "goalId" : "609907ca34b4543f0502dc83",
      "data" : {
        "totalAlive" : 500
      }
    }, {
      "goalId" : "6093e72d2c23d27143f1d071",
      "data" : {
        "totalAlive" : 451
      }
    } ]
  } ]
}