View source for 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  [[The_Expression_popup_menu|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 <code>Power_type</code> index, <code>'solar'</code>, appears in the definition of a different variable. At some point you might change one or more label names in <code>Power_type</code> which would cause the definition in <code>Nems2_offset</code> 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 <code>Power_type</code>. The overlap may just be coincidence; hence, if you change a label in the <code>Power_type</code> index, Analytica won't rewrite these table cells. If they were indeed meant to refer to the  labels of <code>Power_type</code>, 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 <code>Power_type</code>'s index labels. You should set the domain type to be "Copy from index", and select <code>Power_type</code> as the index. With that configuration, if you now rename a label in <code>Power_type</code>, 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]] (<code>X[Power_type='solar']</code>), [[PositionInIndex]] (including <code>@[ Power_type = 'solar']</code>), 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 (<code>Power_type</code>) changes, it knows to rewrite the expression with the new label.
# When <code>Power_type . "solar"</code> 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 <code>"solar"</code>.