View source for Assignment Operator :=

[[category:Operators]]

{{ReleaseBar}}


__TOC__


An assignment with syntax
:<code>''v'' := ''expr''</code>
sets the value of variable «v» to the value obtained from expression «expr».

== Avoid assignment to improve transparency ==

Analytica doesn't allow assignment to global variables, except in a few special cases. This comes as a shock to many experienced programmers because assignment is perhaps the most common operation in conventional computer languages.  But there is a good reason to avoid assignment. In conventional languages, any function or module may have the "side effect" of assigning a new value to a global variable. A global variable may be assigned a new value almost anywhere in the code. So it's hard to be sure just where it got its current value -- a major reason that software is so hard to write, understand, and debug. Computer scientists term these side effects "non-locality" or "referential opacity".  Analytica avoids this problem by requiring that each global variable gets its value from a single definition, which is part of the Variable object.  So you know exactly where to look if you want to understand or debug the calculation for each variable. Experienced programmers often find this ban on global assignments takes a bit of getting used to. But, they soon discover the huge advantage of improved transparency.

== When Analytica allows assignment ==

Analytica does allow assignment in special cases that do not damage transparency unduly. You may assign to:

* A local variable «v» that is declared in the same definition using [[Var..Do|Local]], or LocalAlias, or where «v» is a parameter of the function. Since the local variable is defined and assigned in the same definition, you don't have to look far to understand its effect. 
* A Global variable in an [[OnClick]] attribute of a Button or [[OnChange]] attribute of an input variable (or in the obsolete  [[Script]] attribute). The user must actively click the Button or change the Input Variable. It actually changes the definition of the variable, so the result is clear.
* A Global variable in a user-defined Function that is called from an [[OnClick]] or [[OnChange]] attribute (or in a Function called from such a Function, and so on.)
* An Attribute of a Global variable in the same contexts that you may assign to the value of the variable.
* A Global Variable '''''A''''' in the [[Definition]] of a Global Variable '''''B''''' if '''''A''''' is defined as [[ComputedBy]](''B''). This is useful if the definition of '''''A''''' has an algorithm that computes two (or more) results that you want to retain -- as the value of '''''A''''' and '''''B'''''. It does not damage transparency since you can immediately see in the Definition of '''''A '''''that it is computed in the definition of '''''B'''''.
* The [[RandomSeed]] system variable.

See below for details on each of these cases.

== Assignment to a Local Variable ==

This example shows the use of a local variable in an expression:

:<code>{{Local}} count := 0;</code>
:<code>[[For]] j := I Do(</code>
:::<code>count := count + (A[I = j] <> Null)</code>
:<code>);</code>
:<code>count</code>

This expression counts the number of elements of <code>A</code> over <code>I</code> that are not equal to <code>[[Null]]</code>. It assigns to count. The <code>[[For]]</code> loop also assigns consecutive values of <code>I</code> to <code>j</code>.  Note that if <code>A</code> has dimensions other than <code>I</code>, this expression works fine, and count will contain these other indexes.

== Assignment to a global variable in OnClick or OnChange ==

You may assign to a Global variable in an [[OnClick]] attribute of a Button or [[OnChange]] attribute of an input variable. You may also assign to a Global Variable in a function called from an [[OnClick]]  or [[OnChange]] attribute, or a function called from such  function, and so on. The rationale is that by clicking the Button or changing the input variable, the user is deliberately making a change, which may reasonably change the value and definition of a Global Variable.

Here is how to assign to a Global variable <code>X</code> in an [[OnClick]] or [[OnChange]] Attribute (or in a Function called from such an attribute):
:<code>X := expr</code>

The value of <code>X</code> becomes the result of calculating <code>expr</code>. To be more precise, the definition of <code>X</code> becomes the value of <code>expr</code>.

== Assignment to an Attribute ==
You can assign directly to any user-modifiable attribute of a global object in an expression in an [[OnClick]] or [[OnChange]] Attribute (or a function called by such an action), for example
:<code>Units OF X := "KWh"</code>

User-modifiable attributes include Class, Identifier, Title,  Units, Description, and Definition. For a Module, you can also set Authors and Filename. All these Attributes expect  a text value, so the «expr» should be, or evaluate to, an atomic text value.
The general syntax is:
:<code>''attrib'' OF ''obj'' := ''expr''</code>

You can remove an attribute by assigning [[Null]] to it:
:<code>attrib of X := Null</code>

=== Assigning a Definition === 

Assigning an expression to a Global variable sets its [[Definition]] to the value of the expression. For example
:<code>X := 10^2</code>

evaluates 10^2 to obtain 100, and sets the <code>Definition</code> of  <code>X</code> to 100.

You can change the Definition to an expression, without evaluating it, by assigning the expression as a text value to the [[Definition]]:
:<code>Definition OF X := "Y^2"</code>

In this case, the value of <code>X</code> will change if <code>Y</code> changes.

So, these expressions are ''not'' equivalent:
:<code>X := B</code>     Sets the Definition of X to the value of B
:<code>X := "B"</code>   Sets the Definition of X to the text "B"
:<code>Definition OF X := "B"</code>   Sets the Definition of X to the expression B.

In the last case, if <code>B</code> isn't a defined Variable, it gives a syntax error.

This table highlights the subtle differences between assigning an evaluated value to a Variable (as its new definition) and assigning a [[Definition]] directly:

:{| class="wikitable"
|-
! scope="col"| Assignment
! scope="col"| Definition of X
! scope="col"| Value of X
|-
| X := 1 + 2
| 3
| 3
|-
| X := "1 + 2"
| "1 + 2"
| "1 + 2"
|-
| Definition OF X := 1 + 2
| 3
| 3
|-
| Definition OF X := "1 + 2"
| 1+2
| 3
|}

=== Assigning to a Value or ProbValue ===

Although the Value (and [[ProbValue]]) attribute is not usually user-modifiable, you can assign a number, text, or [[Null]] directly to it, e.g.:
:<code>Value OF X := 100</code>

This may set a [[Value]] for X that is inconsistent with its [[Definition]]. So we strongly discourage assigning to the [[Value]] attribute except in unusual circumstances.

{{Release|6.1||
=== Assignment to a sub-attribute ===
Several built-in attributes hold multiple fields (''sub-attributes'') separated by commas.  You can assign to a single field using the [[Attrib of Obj#Sub-Attributes|sub-attribute syntax]]. For example, to turn on the bevel for node <code>Va1</code>, you can use 
* <code>NodeInfo::bevel of Va1 :{{=}} 1</code>
Since «bevel» is the ninth field in [[NodeInfo]], you can alternatively use
* <code>NodeInfo::9 of Va1 :{{=}} 1</code>
The sub-attribute syntax works with these built-in attributes: [[NodeInfo]], [[NodeLocation]], [[NodeSize]], [[DefaultSize]], [[FontStyle]], [[NodeFont]], [[DiagState]], [[WindState]], [[ValueState]], [[OutlinerState]], [[DefnState]], [[NumberFormat]], [[ProbabilityNumberFmt]], [[DensityNumberFormat]], and [[FileInfo]].
}}

== Assignment to RandomSeed ==

When Analytica uses pseudo-random numbers, such as when sampling from a distribution, the actual sample generated is based on the current [[RandomSeed]], used by the internal random number generators.  If you evaluate an uncertain variable at different times, or chance variables in different orders, you are likely to get different samples.  

To reproduce the same sample each time, one method that can be used is to reset the random seed to a known value prior to calling the distribution function.  For example,

:<code>RandomSeed := 999;  Normal(0, 1)</code>

This would generate the same sample for the normal distribution same every time it is evaluated.  Analytica allows an assignment to the [[RandomSeed]] system variable from any expression, and doing so from a variable or function definition does not cause previously computed samples or results to be invalidated.  However, this is the only global object that can be assigned to while a variable is being evaluated.

=== Assigning in a Script Attribute ===
You may also assign in a [[Script]] attribute, but that is an obsolete feature, replaced by  [[OnClick]]  or [[OnChange]] attribute. One reason the Script attribute was replaced is that it uses a slightly different syntax, known as Typescript. For example, to assign to a variable in a Script, you shoud surround the the assignment operation in parentheses, such as:
:<code>(Va1 := expr)</code>

Without parentheses, a script will interpret the expression as typescript rather than as an expression. It will not evaluate the right-hand side but rather set the definition of <code>Va1</code> to the literal character-for-character expression written on the right-hand side.  The parentheses cause typescript to interpret the line as an expression. To avoid this subtlety, we recommend you use only the [[OnClick]]  or [[OnChange]] attributes. We retain the Script attribute only for compatibility with legacy models. 

To avoid this subtlety, we often recommend creating any complex button-script logic in a user-defined function, where the logic resides in a definition using the syntax most Analytica users are already well-accustomed to.   Your button script can then consist of a simple single call to your user-defined function.

== Gotchas with assignment ==
=== Interactions of Assignment with Array Abstraction ===

Analytica performs array-based operations.  When an operation has side-effects, as the assignment operator does, this can have unexpected results.  These three expressions may seem the same to someone accustomed to a procedural programming language, but only (C) produces the expected result. We assume they are each evaluated in Prob mode, so generate a random sample of values for result:

:<code>(A)</code>
:<code>{{Local}} result := [[Uniform]](0, 1);</code>
:<code>[[If]] result < 0.5 [[Then]] result := 0.5;</code>
:<code>result</code>

:<code>(B)</code>
:<code>{{Local}} result := Uniform(0, 1);</code>
:<code>[[If]] result < 0.5 [[Then]] result  := 0.5 [[Else]] result := result</code>

:<code>(C)</code>
:<code>{{Local}} result := Uniform(0,1);</code>
:<code>result := [[If]] result < 0.5 [[Then]] 0.5 [[Else]] result</code>

To understand this foible, you must realize that Analytica evaluates the [[If-Then-Else]] in an array fashion, evaluating the entire IF part, then evaluating the THEN part in an array-operation only once, and evaluating the ELSE part in an array fashion only once.  It is not iterating over each atomic element of result.  (We sometimes refer to this distinction has "vertical" vs. "horizontal" abstraction).  

In case (A), when <code>result < 0.5</code> is evaluated (assuming [[Evaluation Modes|Sample mode]]), at least one element of result is likely to satisfy <code>result < 0.5</code>, so the THEN clause will be evaluated.  When this happens, the local variable is set to the scalar value of 0.5 -- it is no longer indexed by [[Run]].  Probably not what the author expected.

In case (B), <code>result < 0.5</code> will have some true and some false instances, so both the THEN and ELSE clauses will be evaluated.  When THEN is evaluated, the entire value becomes 0.5 as the assignment side-effect, and the <code>result := result</code> part has no real impact.  Again, not what the author expected.

Case (C) does work as expected.  Here the IF-THEN -else is evaluated as an array operation, returning the correct truncating, and the assignment of the entire array occurs once.

To avoid this foible, don't use assignment within a conditional THEN or ELSE clause.  There are situations where you can legitimately do so, but when doing so, you should ensure that your antecedent (the [[IF]] condition) is guaranteed to be a scalar at all times.

=== Don't change a global index used by a transient array ===

You should never write a function that changes a global index (assign a new value) that might be used by a transient array. A transient array exists only temporarily during a computation, such as an array value of a local variables, a function parameter, or an intermediate result during evaluation of an expression. ''If you modify a Global Index with an assignment, any transient arrays using that index may be corrupted, with unpredictable consequences, including incorrect results, or a crash.'' Analytica does not detect this situation (which would be computationally expensive).  Such are the perils of side-effects! For example, suppose <code>J</code> is a global index, and this is in a function called by a Script:

:<code>{{Local}} x := [[Array]](J, [1, 2, 3]);</code>
:<code>J := [[Concat]](J, ['D']);</code>
:<code>F(x)</code>

The assignment changing <code>J</code> makes <code>x</code> inconsistent. Global tables that use <code>J</code> use [[Table Splicing|spliced]] to keep them consistent, but there is no direct link from <code>J</code> to the transient array in local variable <code>x</code>, so it cannot be made consistent. 

Bottom line: Never change a global index while it is in-use by a value in a local variable.

Note: It is okay to assign a new value to a local index. When you do to, it essentially creates a new local index, treated as separate from the one held by local variables.

Here is an example of a transient value that doesn't involve a local variable or parameter:

:<code>{{LocalIndex}} I := 1..10</code>
:<code>Function F()</code>
:<code>Definition: (I + 1)/(I := 10..100)</code>

<code>(I + 1)</code> is a transient array indexed by <code>I</code>, which is held in memory as the denominator is computed. The computation of the denominator changes <code>I</code> -- including its length. The result is inconsistent.

== Slice/Subscript Assignment ==

When «v» is a local variable, you may assign to a single slice of a value, leaving all other current values of the local variable unchanged.  The syntax for this is:

:<code>v[I = x]  := y</code>
:<code>v[@I = n] := x</code>

This is only permitted when «v» is a local variable. 

If you wish to change a single slice of a global variable, «X», from a button script, and if you can guarantee that every cell of the global variable contains a literal value, you can accomplish this using:
:<code>{{Local}} v := Va1;</code>
:<code>v[I = x] := y;</code>
:<code>Va1 := v</code>

You could also accomplish this equivalently using:
:<code>Va1 := [[If]] I = x [[Then]] y [[Else]] Va1</code>

For a single slice, the latter is equally efficient; however, if you have a complex algorithm that will manipulate many slices and perform many slice assignments in the process, direct assignment to slices prior to writing the value back to the global value is substantially more efficient.

Additional information on [[Slice Assignment]] is available at [[Subscript/Slice Operator]].

=== Assigning an Array ===

If you assign an array value to a global variable (from an [[OnClick]] or [[OnChange]] attribute), e.g.
:<code>X := [[Array]](I, [10, 20, 30])</code>

it sets the Definition of X to a Table, with specified index and values, so it looks like this:
:<code>Definition OF X &rarr;  Table(I)(10, 20, 30)</code>

If X was previously defined as a [[Table]], [[DetermTable]], [[ProbTable]] or [[IntraTable]], it retains that form of '''Edit''' table, but using the Index(es) and values from the assigned Array.

If you want to change the form of a [[Table]], for example from [[DetermTable]] to [[Table]], you should first set it to [[Null]]:
:<code>X := NULL</code>
:<code>[[Definition]] OF X &rarr;  [[Table]](I)(10, 20, 30)</code>

If you want to change an existing [[Table]] to another form, such as [[DetermTable]], [[ProbTable]] or [[IntraTable]], it is best to use the [[MakeChangesInTable]] typescript command.

== Assignment to variables with Checkbox. Choice, MultiChoice or Slider ==

If you assign a Boolean (0 or 1) to a variable defined as [[Checkbox]](0) control, it stays as a checkbox, with the new value selected. For example:
:<code>Variable X := Checkbox(0)</code>

Assignment from the Onclick of a Button
:<code>X := 1</code>

changes the definition of <code>X</code> to
:<code>[[Checkbox]](1)</code>

Similarly, you can assign a valid value «v» to a variable defined as a [[Choice]](i, v) control:
:<code>Index Pet := ["Cat", "Dog", "Rat"]</code>
:<code> Variable Select_Pet := Choice(Pet, 1)</code>

After the assignment
:<code>X := "Rat"</code>
the variable retains its definition as a  [[Choice]] menu, but with the new value:
<code>Select_Petm : [[Choice]](Animal, 3)</code>. 

This also works for a variable defined with [[MultiChoice]](), 
:<code>Variable X := Multichoice(Animal, 1)</code>
:<code>X := 'Dog'</code>
after which 
:<code>Variable X :=Multichoice(Animal, 2)</code>

You can assign multiple values to a MultiChoice variable as a vector of values:
:<code>X := ['Cat', 'Dog']</code>

You can also assign 'All' to a [[Choice]] or [[MultiChoice]] variable to select all its possible values.
:<code>X := 'All'</code>

You can set a Multichoice variable to None (assuming you have set None as an option) by assigning an empty vector:
:<code>X := []</code>

This kind of assignment only works if you assign a valid value, 1 or 0 (True or False) to a [[Checkbox]], or a value from the index to a [[Choice]] control -- e.g. <code>"Rat"</code> from <code>Pet</code>. If you assign an invalid value that becomes the the new value of <code>X</code> and it loses its [[Checkbox]] or [[Choice]] control, e.g.:
:<code>X := "Moose"</code>

The new value of <code>X</code> is <code>"Moose"</code> with no [[Choice]]() control.

This also works when assigning a new value to the cell of a Table that contains a Checkbox(), Choice(), or MultiChoice():

:<code>Variable Pet_detail := <code>Table(Pet_field)(Choice(Animal, 2), Checkbox(0))</code>

The assignment
:<code>Pet_detail := Array(Pet_field, ["Rat", 1])</code>

preserves the Choice or Checkbox controls, resulting in the new edit table
:<code>Variable Pet_detail := Table(Pet_field)(Choice(Animal, 3), Checkbox(1) )</code>

Assigning to a [[Slider]] control preserves the control as well.

== Assignment to Local Variables with [[Handle]]s ==

There are several different constructs for declaring local variables, resulting in several nuances in behavior with regard to assignment.  For most users of Analytica, these nuances are unimportant -- their primary relevance is for [[meta-inference]], where the distinctions with respect to how [[handle]]s are processed becomes important.  With respect to assignment, the key distinctions are what happens when you assign a value to a local variable that is current holding a [[handle]], and whether the local variable is declared as an index or not.

In general, local variables are declared either with a declaration construct (e.g., {{Local}}..Do), or through a [[Function Parameter Qualifiers|parameter declaration]] in a [[User-Defined Function]].  

When assignment is made to a local variable that currently contains a [[handle]] to another object, there are three distinct things that may happen, depending on which type of local variable is being used:
;Meta-variable treatment: The local variable is changed, no longer pointing to the object, leaving the object unchanged, and causing the local variable to now contain the new value.
;Alias treatment: The assignment applies to the object, changing its definition.  This behavior may require the evaluation to be launched from a button script or require the object to be defined via the [[ComputedBy]] function, since it involves a global side effect.
;Index treatment: The assignment creates a new local index object with the new value.

This table shows how local variables are treated by assignment based on how they are declared:
:{| class="wikitable"
! How declared !! Treatment type by Assignment (''x'' := ...) !! Notes
|-
! colspan=3 | Local Declaration Constructs
|-
! [[Local..Do]] 
| meta-variable || ''requires [[Analytica 5.0|5.0]]''
(recommended)
|-
! [[Var..Do]] 
| meta-variable || {{Release|5.0||''deprecated''}}
|-
! [[Using..Do]] 
| meta-variable || ''deprecated. 
Identical to [[Var..Do]]
|-
! [[MetaVar..Do]] 
| meta-variable || ''requires 4.2. 
Identical to [[Local..Do]]''
{{Release|5.0||(deprecated)}}
|-
! [[LocalAlias..Do]] 
| Alias || (recommended)
|-
! [[Alias..Do]] 
| Alias || Same as [[LocalAlias..Do]]
|-
! [[LocalIndex..Do]] 
| Index
| (recommended)
|-
! [[Index..Do]] 
| Index
| &nbsp;
|-
! [[MetaIndex..Do]] 
| Index 
| Identical to [[LocalIndex..Do]]
|-
! colspan=3 | Function Parameter Declarations
|-
! x : [[Function_Parameter_Qualifiers#Context|Context]] (or none) 
| Alias ||
|-
! x :[[Function_Parameter_Qualifiers#Sample|Sample]]<br>x:[[Function_Parameter_Qualifiers#Prob|Prob]]<br>x:[[Function_Parameter_Qualifiers#Mid|Mid]]<br>etc. 
| Alias ||
|-
! x : [[Function_Parameter_Qualifiers#Variable|Variable]] 
| Alias
||
|-
! x : [[Function_Parameter_Qualifiers#Object|Object]]
| Alias
| &nbsp;
|-
! x : [[Function_Parameter_Qualifiers#Index|Index]]
| Index 
| &nbsp;
|-
! x : [[Function_Parameter_Qualifiers#Handle|Handle]] 
| Meta-variable
| &nbsp;
|}

When you are performing [[meta-inference]], it is recommended that you limit yourself to the {{MetaVar}} and [[LocalAlias]] declarations local variables.  The [[Var..Do]] construct has been around in Analytica for a long time, long before it was widely used for [[meta-inference]] and manipulation of [[handle]]s.  As a result of its legacy, and the need to continue supporting backward compatibility, its treatment of [[handle]]s is a  less consistent, which can be a source of confusion.  The [[LocalAlias..Do]] and [[MetaVar..Do]] variations were introduced for the purpose of providing two highly self-consistent, making their behavior easier to fully understand, and [[MetaVar..Do]] is now [[Local..Do]] as of [[Analytica 5.0]] and is the recommended method for declaring local identifiers for values.  Again, the distinctions only have a bearing when you are manipulating [[handle]]s to other objects.

=== Examples ===

{| class="wikitable"
| {{Local}} x := [[Handle]](Va1);
x := 6
| '''''Meta-variable treatment'''''
local <code>x</code> becomes 6.
<code>Va1</code> unchanged
|-
| [[MetaVar]] x:= [[Handle]](Va1);
x := 6
| '''''Meta-variable treatment'''''
local <code>x</code> becomes 6.
<code>Va1</code> unchanged
|-
| {{MetaVar}} x:= [[Handle]](Va1);
x := [[Handle]](Va2);
| '''''Meta-variable treatment'''''
local <code>x</code> is now holding a handle to <code>Va2</code>.
<code>Va1</code> unchanged
|-
| [[LocalAlias]] x := [[Handle]](Va1);
x := 6
| '''''Alias treatment'''''
local <code>x</code> unchanged -- still points to <code>Va1</code>.
<code>Va1</code>'s definition changed to 6
|-
| {{LocalIndex}} I := 1..5;
{{Local}} A := I^2;

I := 10..15
| '''''Index-treatment'''''
:A new local index <code>I</code> is created with an [[IndexValue]] of <code>[10, 11,12,13, 14, 15]</code>.
:The local <code>I</code> now refers to the new index.
:Array <code>A</code> is indexed by the original index, <code>A.I</code>.
|}

Suppose you have a meta-variable that points to <code>Va1</code>:
:<code>{{MetaVar}} x := Handle(Va1);</code>

and now you want to use assignment to change the definition of <code>Va1</code>. Assigning to <code>x</code> doesn't do it, since this simply changes the value of <code>x</code>. To make the assignment, you need to force the alias treatment, which is done via [[LocalAlias]] as follows
:<code>[[LocalAlias]] x1 := x Do x1:=6</code>

Consider the converse, where you have a [[LocalAlias]] to <code>Va1</code>:
:<code>[[LocalAlias]] x:= [[Handle]](Va1);</code>

and you want to change <code>x</code> to now be an alias for <code>Va2</code> instead. This cannot be done, because <code>x</code> is in all ways an alias for <code>Va1</code>, so any attempt to change it will be enacting a change to <code>Va1</code>. What this should tell you is that if you have logic that is going to have to change what a local points to, you need to use a meta-variable ({{MetaVar}} not [[LocalAlias]], or for function parameter qualifiers, [[Handle]] not [[Function_Parameter_Qualifiers#Variable|Variable]] or [[Function_Parameter_Qualifiers#Object|Object]]).

Suppose you have a list of handles, and you want to set every variable in the list to 0. This can be done with a single [[LocalAlias]] statement,
:<code>[[LocalAlias]] x := [[ListOfHandles]](Va1, Va2, Va3) Do x := 0</code>

This works because of array abstraction. [[LocalAlias]] is psuedo-atomic in that it points to only one item (I say "pseudo-atomic" here because the object it is an alias for may have an array, so it doesn't limit the dimensionality of the value).  So since <code>x</code> is being set to three handles, the body of [[LocalAlias]] is repeated three times, each time <code>x</code> is an alias of a different object.

=== Attribute Assignment with Handles ===

There is no functional difference between the following two examples

:<code>{{MetaVar}} x := [[Handle]](Te1);</code>
:<code>Description Of x := "New text";</code>

:<code>[[LocalAlias]] x := [[Handle]](Te1);</code>
:<code>Description Of x := "New text";</code>

In both cases, the description of <code>Te1</code> is set. The second case should seem straightforward, but the first case with {{MetaVar}} appears to be setting the description attribute of <code>x</code> rather than the description attribute of <code>Te1</code>. However, it doesn't work this way because local variables are not objects -- they have no attributes themselves. Since the intent is unambiguous, the [[Of]] operator resolves a meta-variable (as well as a local alias) to the object pointed to. Thus, if you need to read or set an attribute value of the object held in your meta-variable, you don't have to obtain a local alias first.

== See Also ==
* [[Definition]]
* [[Subscript/Slice Operator]]
* {{Local}}..Do
* [[RandomSeed]]
* [[Scripting]]
* [[Attrib of Obj]]