Check attribute

Analytica User GuideDefinitionsCheck attribute

It's a good idea to include in your model checks to make sure that all user inputs (or internal computed values) are of the expected type and range. It helps avoid or detect common mistakes. There are three ways to do this in Analytica:

If a user input must be one of a short list of text or numerical values, it is best to set it up as with a Choice function (or a Checkbox, if it is a Boolean whose values must be True (1) or False (0).
The Domain attribute of a variable lets you specify its type and valid range of values by selecting from lists. It even generates a clear message if you enter an invalid value into an Edit table.
The Check attribute of a variable lets you specify an expression to test if its value is valid.

The Domain attribute is a bit easier to set up. But, the Check attribute lets you define more complex validity check and a custom error message if the Check fails.

Domain Range Checks

The Domain attribute lets you define for each variable whether it

Computed values are compared against the space of possible values specified in the domain attribute (see The domain of possible values). This validation occurs as long as the Check value bounds ... against domain bounds preference is turned on (it is on by default). Thus, validity testing requires only that you take the time to specify the appropriate domain attribute and bounds, something that is a recommended good practice anyway.

Domain range checks are also applied to input controls when a literal value is entered:

Validation of edit table cell entry: Domain bounds are also applied to edit table cells. Cells that are not consistent with the domain bounds display with a pink background, and when values are entered, a tool tip describes the problem:

Check Attribute

The Check attribute provides an even more flexible mechanism for validating model results. In its simple usage, it can be utilized for range checking in the same fashion as the domain attribute, for example, to check that the value of Percent_damage is between 0 and 100, set its check attribute:

Check := Percent_damage >= 0 AND Percent_damage <= 100

If the check attribute evaluates to False, whenever the variable is evaluated, it shows a warning dialog and the opportunity to edit the definition. Use of the check attribute has one further advantage that the domain attribute does not have -- you can customize the error message that displays when the criteria is violated.

Unlike the domain, the Check attribute can also be used to check consistency across multiple cells in results, or even across multiple result variables. For example, in some cases you might know that a certain invariant is required to hold, so that a violation of that invariant would signal a problem with the model. Such an invariant can apply array operations and multiple variables, e.g.:

Check := C <= Max(A, I) + Sum(B, I)

While the check attribute has some flexibility not available from the domain attribute, when validating against simple bounds, the domain attribute tends to be more convenient.

You can always view and edit the check attribute in the Attribute panel, if you open it below a diagram. If you want to view or edit it in Object windows, you must first cause it to be shown:

Displaying the check attribute:

Select Attributes from the Object menu to open the Attributes dialog (see Managing attributes).
Scroll down the attribute list and find Check.
Click Check once to select it, and a second time to add a checkmark next to it. The checkmark indicates that the attribute is displayed in the Object window.
Click OK.

Now the check attribute appears in Object windows for all variables. You can also set it to appear for functions by repeating the steps above but selecting Functions from the Class menu in the Attributes dialog.

Defining the check: Either open the Object window for the variable, or open the Attribute panel below the diagram and select Check from the Attribute menu. Enter a Boolean (logical) expression in the Check field that returns true (1) if the value is acceptable, or false (0) if not. The expression should refer to the variable by its identifier or as Self. For example, to check that the value for the Lifetime of a car is more than 0 and less than 12 years, define the check to match one of the following samples.

If the Check expression refers to another variable, it makes a dependency from the variable being checked to the variable mentioned. It usually shows an arrow from that variable.

Triggering a check: If a variable X depends on no other variables, or if it is defined as an edit table and does not operate over the indexes of the table, it performs the check whenever you change its input value or a cell of the edit table. Otherwise, it performs the check each time it evaluates the checked variable X — that is, when you first view a result for X or a variable on which X depends. If you view or compute a probabilistic value for X, it warns if any sample value of X fails the check. More generally, if the value of the Check expression is an array, it fails if any atom in the array is false (0). If you compute first its mid value of X and then its prob value, it causes two evaluations, one check on the mid value and a second on the prob value.

If you change the definition of X or any variable on which it depends, including any variable mentioned in its Check expression, it performs the check again next time you view X or a variable that depends on it.

Cell-by-cell validation in edit tables: When you define a check attribute for a variable defined as an edit table, Analytica will test and flag each cell individually as long as the check attribute does not operate over any of the table indexes and the values in the edit table cells do not have the potential of triggering a lengthy evaluation. Cells that fail the validation are displayed with a red background when viewing the edit table, a message balloon appears with a tail pointing to the bad cell when an out-of-range entry is first entered. If the check expression operates over a table index, this feature is disabled and the check is performed only after the final entries are stored.

If any cell in the table contains a general expression that references other variables, then the cell-by-cell checking is disabled. This is to prevent the possibility of a delay for the user if a large part of the model must be evaluated; therefore, the cell-by-cell checking is only appropriate for tables where expressions would not be entered. If the check expression operates over any table index, such as Sum(Self, Projects) < 5, then this would indicate that the check is a validation on the table as a whole, rather than on individual cells, and in this case the cell-by-cell checking is again disabled. When disabled, checks are validated at evaluation time as would occur with non-edit table variables.

If a check fails: If a check fails — evaluates to False — the warning dialog offers the option of editing the variable’s definition, cancelling, or continuing. If you continue, it does not perform the check again unless you change the definition of the variable or a variable it depends on.

Custom error messagesThe default warning when a check fails shows the Check expression. This is OK for modelers, but might be obscure for end users. If you call the Error() function in the check, it displays the message you pass to Error() instead of the default warning. Using this, you can craft a more helpful message. The warning gives the same options.

To disable checking: You can disable all value checking by unchecking Check value bounds in the Preferences dialog from the Edit menu. If you want to disable only Check attribute validation, but leave domain validation in tact, then uncheck the Check value bounds..against Check attribute preference. Validation preferences are on (checked) by default.

Check attribute

Domain Range Checks

Check Attribute

See Also