Skip to content

Model

Introduction

A Model node allows the seamless integration of models defined in the UI in a process. The process does not need to be updated when a model is changed. Like other VOR Stream nodes, a Model node takes input streams of data and produces streams of data. Features of a Model node include:

  1. Specify a model by name or by model type.

  2. Integration with scenarios and risk factor transformations.

  3. Support for segmented models through framework filters.

  4. Support for parallelism without the requirement that the models are threadsafe.

  5. Support for merged input queues like computational nodes.

Creating Model Nodes

The method of creating nodes is through Stream Files. The Model node sections are detailed in the Process - Model statments section.

An example of using a Model node in a stream file is:

name model

in input.csv -> input
in scen.csv -> scen

// This is a Model Node
model (input)(output)
    name=nodeName
    label="short description"
    descr="Long description"
    Type="Model_Type"
    scenario=true
    getdyn = fact1, fact2

model (input, scen)(output)
    ModelName="Model Name"
    getdyn = fact1, fact2
    exceptq=exceptions

out output -> ans.csv
out exceptions -> except.csv

where

  • name - Specifies the name of the node. This is used as the default label for the node and the name of the generated code. This is optional.

  • descr - Optional long form description of the node's purpose or value. This is put in the generated documentation.

  • label - Specifies a short form description of the node's purpose or value. Used in displaying the process in the documentation and UI. This is optional and defaults to the name of the node.

  • type - Specifies the type of the model to use. This is a quoted string, so substitution functionality can be used. Either Modelname or Type, or unitTest= must be specified. Type is case insensitive.

  • Modelname - Specifies the name of the model to use. This is a quoted string, so substitution functionality can be used. Either Modelname or Type, or unitTest= must be specified.

  • UnitTest - A Boolean that instructs the Model node to use the model selected for unit testing. Either Modelname or Type, or unitTest= must be specified.

  • getdyn - Optional list of dynamic facts the model node needs. The node will wait for the facts to be available before running. The facts will be passed to the model and assigned to fields that match in the output queues.

  • scenario - Optional boolean that specifies that scenarios requested in the run are applied to each observation from the first input queue. scenario set in. The scenario data set will have scenario, Either Scenario=true may be set or a second queue is specified, but not both. Neither is required.

  • ExceptQ= - Specfies the queue to write exceptions; for observations where a model fails. The error returned by the model call is placed in the output field "Error". If the except queue isn't specified, the error message will be placed in the log. In both cases, the observation with the error will not be sent to the other output queues.

Using Model TYPES

Models defined in the UI have a type associated with them. Model types are defined by a VOR administrator and have a short name and a long name. The Model node is expected the short name for the type. This can be found in the UI by hovering over the model name in the model list.

Multiple models may share the same type, so the specific models used at runtime are determined by the Framework specified in the Study. In the Framework, one or more models are selected and assigned filters. These filters define which model should be used in a particular situation. For example, filters may be used to implement segmented models or conditional overrides.

Threading a Model Node

A Model node can be executed using multiple threads. The models that are used do not need to be thread-safe. Specify the number of threads to use in the jobsoptions.json file. The default is one thread.

Scenarios in a Model Node

Scenarios are optional for a Model node. If a single input queue is specified and scenario=false is set (the default), the selected model will be run once for each observation in the input queue. The output queues will contain the same number of observations as the input queue.

If scenarios are requested by specifying an additional input queue — then for each input observation, the selected model will be run once for each observation in the scenario data. The number of observations in the output queues will be:

(# input observations) × (# scenario observations).

Fields from the scenario whose names match fields in the output queues are copied into the output.

When scenario=true, the Model node uses the scenario data similarly, but uses the as-of-date specified in the study to determine which observations in the scenario to use. So, if the as-of-date is before or equal to the dates in the scenario, all the scenario data will be used. For scenario=true, The following variables are automatically available:

  • Scenario
  • Horizon
  • Date
  • Weight

Dynamic facts in a Model Node

One or more dynamic facts can be passed to a Model node. The facts can be used to change the model type or model name at run time using substition functionality. A Model node will wait until all the requested dynamic facts are available before executing the models. The dynamic facts will be passed to the model(s) using the Tile form of the fact name. This means that the dynamic fact can override a field of the same name in the input queue or the scenario. Note, the type of the fact is preserved - if a fact is an integer array that is what is passed to the model.