Keeping text literals consistent with index labels

New to Analytica 7.0

Analytica includes many advanced features for automatically updating expressions as you rename identifiers, change index values used by tables (see Table Splicing) or other expressions, or change inputs used by previously computed calculations. These features help you to focus on your model logic and avoid mistakes.

Automatic expression updates

One change that can impact logic in other expressions throughout your model is a name change to an index label. This occurs when you have defined an index to be a List of Text, and then you have used the text values in the definitions (or other expressions) in other variables. For example:

Index Power_type ::= [ 'coal', 'gas', 'hydro', 'nuclear', 'solar', 'wind' ]

Variable Nems2_offset ::= If Power_type = 'solar' Then ...

This partial example illustrates a case where a label from the Power_type index, 'solar', appears in the definition of a different variable. At some point you might change one or more label names in Power_type which would cause the definition in Nems2_offset to become incorrect (and not necessarily in a way that throws an error).

You can make use of the Domain attribute to also help Analytica spot cases where text literals should be associated with an index value. For example, suppose in another variable you have an edit table like:

Variable Power_plant_type ::= Table( Power_plant )( 'gas', 'hydro', 'gas', 'solar' ....)

Each cell of the table contains a text entry. By itself there is no intrinsic association of these cell values to the index values of Power_type. The overlap may just be coincidence; hence, if you change a label in the Power_type index, Analytica won't rewrite these table cells. If they were indeed meant to refer to the labels of Power_type, that change could introduce a logical error into your model. You may also be faced with a time-consuming task of updating all the cells of the table.

In an example like this, you can use the Domain attribute to establish the association so that Analytica knows that the text values in this table are supposed to be the same text used in Power_type's index labels. You should set the domain type to be "Copy from index", and select Power_type as the index. With that configuration, if you now rename a label in Power_type, it will automatically rewrite the corresponding cells of the table.

Index-label syntax

In the above examples, Analytica automatically figures out to rewrite certain definitions that use text literals that correspond to an index label. It looks for equality or inequality comparison, use of the text literal in calls to Subscript (X[Power_type='solar']), PositionInIndex (including @[ Power_type = 'solar']), and SubIndex. It notices comparisons to a Choice variable that uses the index to a text literal. It finds literal definitions or cells when the domain is connected to the index.

Although it automatically finds and updates the most common and most obvious cases, it cannot recognize all cases where it can be far less obvious that text literal is associated with an index. This would include the following examples.

Variable Incentive_discount ::=
     Local desired_type := If abs(latitude)<35 Then "solar" Else "nuclear";
     If Power_type == desired_type Then Solar_discount Else Nuclear_discount

To ensure that Analytica catches the association of these text literals with the index labels, you can use the index-label syntax instead:

Variable Incentive_discount ::=
     Local desired_type := If abs(latitude)<35 Then Power_type . "solar" Else Power_type . "nuclear";
     If Power_type == desired_type Then Solar_discount Else Nuclear_discount

The index-label notation provides two benefits:

When the label in the index (Power_type) changes, it knows to rewrite the expression with the new label.
When Power_type . "solar" is evaluated, it double checks that the index contains the label and issues a warning if not, helping you to find mistakes. The result of the evaluation is the text value "solar".