Model Variable Calculator

The Model Variable Calculator allows a user to create a model variable using data or an existing variable that has been applied with a statistical query or passed through a calculator. The resulting model variable can then be referenced in other rules.

Model Variable Calculator tab

The Model Variable Calculator tab allows you to define a model variable. This model variable stores the resulting values from having statistical queries applied or from having been passed through a calculator (Figure).

Figure.  The Model Variable Calculator interface.

Name of Variable: this field displays the name of a selected model variable created in the Model Variable Calculator tab. Expanding the dropdown for this field displays all the available model variables in the study.

Add Variable: this button accesses the New Model Variable dialog where the name of a new model variable is configured.

Rename Variable: this button accesses the Rename Model Variable dialog which allows the editing of the selected model variable’s name. The edited model variable name is displayed in the Name of Variable field.

Copy Variable: this button creates a copy of the selected model variable in the Model Variable Calculator tab. When clicked, the Duplicate Model Variable dialog is loaded which allows assigning a unique model variable name for the duplicate of the model variable. The duplicated model variable’s name is displayed in the Name of Variable field.

Delete Variable: this button deletes the selected model variable from the study. After being removed, the model variable name is no longer displayed in the Name of Variable field’s dropdown.

Statistical Queries: this radio button option uses statistical queries to process an existing data or variable for the model variable.

Calculator: this radio button option uses an equation to define how the model variable is computed. More information on working with the Calculator for a model variable is detailed in Calculator.

Apply: clicking this button saves the configuration of the model variable.

When working with a model variable, Statistical Queries or the Calculator may be selected. Only one of these options may be selected for generating the model variable values.

Selecting Data or Existing Variables

Using either Statistical Queries or the Calculator to generate the values for a model variable uses a reference data or existing variable in the study. The data or existing variable is selected via the Variable Picker.

When working with Statistical Queries, a single data or existing variable must be selected. The Variable Picker is accessed by clicking on the ellipses button in the Name of data or existing variable field.

When working with the Calculator, multiple data or existing variables may be selected. The Variable Picker is accessed by clicking on the VAR button to the right-hand side of the Calculator area.

Handling Undefined Values

The value of -9999 is assigned to undefined values for data. The value of 1.40E-45 is assigned to undefined values for existing variables.

When an undefined value is present in a reference data or existing variable when computing for the model variable at a time step, these undefined values are ignored for Statistical Queries. For the Calculator, the result is undefined if an undefined value is part of the equation.

Statistical Queries

When using Statistical Queries, data or an existing variable is selected via the Variable Picker accessed from the ellipses button of the Name of data or existing variable field.

After selecting data or existing variable to work with, statistical queries can be applied over a duration of several time steps. Statistical queries can also be applied to the rate of change of the referenced data or existing variable over a duration of several time steps. Both these options may be applied at the same time for statistical queries.

Handling Time Steps

For Statistical Queries, the number of time steps must be defined. The model variable value for the current time step is computed depending on whether the statistical query is applied to data or an existing variable.

When the statistical query works with data, the time steps considered include the current time step along with previous time steps. For example, the current date is February 10 and 4 daily time steps are considered. For the 4 time steps, 5 data points are used. The values from February 6-7, 7-8, 8-9, and 9-10 are used to compute the model variable value for February 10.

When the statistical query works with an existing variable, the time steps exclude the current time step but include the previous time steps. Using the details from the previous example, the model variable value for the current time step on February 10 considers the data points from February 5-6, 6-7, 7-8, and 8-9.

Statistical Queries Applied Directly for a Duration of Time Steps

To apply the statistical query to the selected data or existing variable over a duration of time steps, the checkbox must be checked next to the Duration of time steps. When this option is selected, the number of time steps must be defined. The value must be 0 or greater.

Only one statistical query may be selected for application over a duration of a number of time steps. The available options are listed below.

Mean: this returns the average value of the set of data for the specified number of time steps.

Median: this returns the middle value of the set of data for the specified number of time steps

Minimum: this returns the minimum value in the set of data for the specified number of time steps.

Maximum: this returns the maximum value in the set of data for the specified number of time steps.

Sum: this returns the sum of values in the set of data for the specified number of time steps.

Mode: this returns the most common value in the set of data for the specified number of time steps.

Statistical Queries Applied to the Rate of Change

When the checkbox is checked next to the Rate of change per time steps, the change in values per time step is first computed for the reference data or existing variable. The selected statistical query is then applied to the rate of change over the duration of time steps. When this option is selected, the number of time steps must be defined. The value must be 0 or greater.

Only one statistical query may be selected for application to the rate of change over a number of time steps. The available options are listed below.

Average over interval: this returns the average value of the rate of change values for the specified number of time steps.

Instantaneous (current compared to start of interval): this returns the result of the following formula using the values from the referenced data or existing variable. The set of data includes the current time step and previous time steps according to the number defined for time steps. There must be at least 2 values that are defined in the set of data or existing variables.

Where: 

Maximum over interval: this returns the maximum value of the rate of change values for the specified number of time steps.

Minimum over interval: this returns the minimum value of the rate of change values for the specified number of time steps.

Absolute value of maximum change over interval: this returns the absolute value of the maximum change in the set of data for the specified number of time steps.

Statistical Queries Applied Directly to the Rate of Change for a Duration of Time Steps

Statistical queries can be applied both directly to the referenced data or existing variable and to the rate of change of the referenced data or existing variable for a duration of time steps. This is configured by checking both checkboxes for Duration of time steps and Rate of change per time steps. Each option still applies their separate values for time steps.

When the statistical queries are applied both directly and to the rate of change of the reference data or existing variable, the statistical query selected under the Duration of time steps are first applied directly to the data or existing variable for the specified number of time steps. The rate of change is then computed from the results. Finally, the statistical query selected under the Rate of change per time steps is applied to the rate of change results for the specified number of time steps.

Calculator

The Calculator option allows the configuration of a formula that computes selected data and existing variables to generate the model variable value.

The Calculator includes a set of buttons similar to a calculator to build the formula in the calculator field. The VAR button accesses the Variable Picker to select data and existing variables to the calculator field. The formula may also be typed into the field (Figure).

Figure.  Click the Apply button to save the Model Variable Calculator configuration.

Nested Model Variables

When creating a model variable, existing model variables may be used as reference in the new model variable. The existing model variables are selected in the Variable Picker by selecting the Category of “Model Variable Calculator”. The Member dropdown lists all the available existing model variables.   

Circular Dependencies with Model Variables

When selecting a model variable from the Variable Picker, the currently selected model variable is also available. This results in a circular reference of the current model variable.

Computing a simulation with a model variable with a circular reference does not abort the simulation. The results table for a model variable with a circular reference is generated with undefined values.

Because the “most recent value” for a circular reference on the starting time step is always null (1.4E-45), this value is perpetuated through the rest of the model variable time series.

Simulation Output

Each model variable created in the Model Variable Calculator generates a table of results in the Simulation HDF file. The model variable results are organized under the ModelVariableCalculator folder.