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
    get_dyn = fact1, fact2

model (input, scen)(output)
    model_name="Model Name"
    get_dyn = fact1, fact2
    exception_queue=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 model_name or type, or unit_test must be specified. type is case insensitive.

• model_name - Specifies the name of the model to use. This is a quoted string, so substitution functionality can be used. Either model_name or type, or unit_test must be specified.

• unit_test - A Boolean that instructs the Model node to use the model selected for unit testing. Either model_name or type, or unit_test must be specified.

• get_dyn - 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.

• exception_queue - Specifies the queue to route observations to when a model evaluation fails. The error returned by the model call is placed in the output field "Error". The exception queue definition must include a variable called Error of type char to receive the error message. When running with scenarios, the variables Scenario (char) and Date (date) can also be included on the exception queue to capture which scenario and date triggered the error. If the exception queue is specified, the observation will be routed to it and will not be sent to the other output queues. If the exception queue isn't specified, the error message will be placed in the log and the observation will still be sent to the output queues with NaN for computed fields.

Error handling in custom models

When a model's Model() function returns an error, the behavior depends on whether an exception queue is configured:

• With exception_queue: The observation is routed to the exception queue regardless of whether the results map is nil or non-nil. The run continues.
• Without exception_queue: The behavior depends on the results map:
  • If the model returns a non-nil map along with the error (e.g., with NaN values for computed fields), the observation is sent to the output queues with those values. Structured models do this automatically.
  • If the model returns nil with the error, the run is terminated. Custom models that want observations to propagate on error should return a non-nil map with math.NaN() for any fields that could not be computed.

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. Only scenario dates strictly after the as-of-date are evaluated and output; the as-of-date itself and any earlier dates are excluded entirely (not evaluated, not output). 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.