View source for Self-Indexed Arrays

[[category:Arrays]]
[[Category:Doc Status C]] <!-- For Lumina use, do not change -->
 
__TOC__


Each dimension of an array is identified by an Index. Usually, each index is defined as an index object, which appears in a Diagram like this:

:[[image:IndexNode.jpg]]

But, it's also possible for a standard variable to contain an index value in addition to its actual value.  This index value is called a "Self index" because the actual array value of the variable is indexed by the variable's own index value. An array value of another variable may also use the self index of this variable. Self-indexes can arise and be useful in several situations.

== Create a self-indexed variable ==

Here's one way yo create a self-indexed variable:  

First, drag a variable node to the diagram and name it <code>X</code>.  Press the [[image:Expr.jpg]] button on the toolbar to edit the definition and select "Table" from the definition type dropdown:

:[[image:CreateTable.JPG]]

In the index chooser dialog, select the "X (Self)" index and press OK.

:[[image:SelectSelfIndex.jpg]]

You have now just created an edit table with a self index.

:[[image:SelfIndexedTable.jpg]]

Notice that the row-index is <code>X</code>, and the edit table itself is for <code>X</code>.  Here the row headings are the index values for <code>X</code>, the table body cells hold the main value for <code>X</code>.  Next, fill in both the self-index value and the body cells with values, as follows.

:[[image:SelfIndexedTable2.jpg]]

As we see here, the variable's self-index value is usually different from its actual value.

== Expression Context ==

When a variable has both a main value and an index value, what happens when its identifier is used in an expression?  (Side note: In general, a variable may have a [[Mid]] value and a probabilistic, or sample, value.  See [[Evaluation Modes]] for more detail.  Here we refer to either of these as the main value.)

As it turns out, Analytica can determine whether to use the main value or the index value based on the context in which the identifier appears.  A simple example is this:

:<code>Sum(X, X)</code>

This expressions sums the value of «X» along the «X» index.  So, when «X» is a self-indexed variable, the main value is used for the first parameter, and its self-index value is used for the second parameter.

In general, the parameters of a function (whether built-in or user-defined) are declared using various [[Function Parameter Qualifiers]].  When a parameter is declared using the [[Function Parameter Qualifiers#IndexType|IndexType]] qualifier, then identifiers passed for that parameter are interpreted as indexes.  Parameters that are declare otherwise are interpreted as values.  (Note: There are further subtleties involved when a parameter is declared as a [[Function Parameter Qualifiers#VariableType|VariableType]], which are beyond the scope of this introduction).  

== The IndexType qualifier ==

When you define your own user-defined function (UDF), you might declare a parameter to be an index.  This creates a local variable that is an alias for the index that is passed in.  If this local variable is used in a value context, the index value (and not the main value) is used.  So, for example, consider the following function:

:[[image:JoinIndex.jpg]]

Suppose, using the self-indexed array defined earlier, we call this function using [[JoinIndex]]():

:<code>JoinIndex(X)</code> 

The result obtained is:  
:<code>"one, two, three, four"</code>

Compare this to what we would get by evaluating [[Join]]() in </code>Join( X, X,' ,')</code>, which results in "15,12,13,8".

Three [[:category:Special Functions|special functions]] exist to explicit control which value to use from within an expression.  These are applicable to expressions being evaluated in a value context.  These are: [[Mid]], [[Sample]] and [[IndexValue]].  The [[Mid]] and [[Sample]] functions provide access to the main values of the variable (see [[Evaluation Modes]] for the distinction), while the [[IndexValue]] function returns the index value.  Using the [[IndexValue]] function, we could for example join the index value of <code>X</code> using
:<code>Join(IndexValue(X), X, ",")</code>
yielding 
:<code>''"one, two, three, four"''</code>

== Copy Index ==
Using the <code>X</code> variable defined above, suppose we wish to define an index, <code>J</code>, having the same values that <code>X</code> has.  We now have two choices - should this new index be composed of <code>X</code>'s index values, i.e., <code>['one', 'two', 'three', 'four']</code>, or of <code>X</code>'s result values, i.e., <code>[15,12,13, 8]</code>?  Either is possible:

:<code>CopyIndex(X)             &rarr;  [15, 12, 13, 8]</code>
:<code>CopyIndex( IndexValue(X) ) &rarr; ['one', 'two', 'three', 'four']</code>

Note: There are several alternative ways of copying the index value.  The [[IndexValue]] function is new to Analytica 4.0, but for earlier versions one could use
:<code>Subset(Array(X,1))       &rarr;  ['one', 'two', 'three', 'four']</code>

== List Definitions ==

A second way that index values often arise in Analytica is by defining a variable as a list of identifiers, or as a list of expressions.  This is often very convenient when creating a report, bringing several results together in a single table view.

:[[image:Cash_flow_stmt_definition.jpg]]

The variable shown in the preceding screenshot is defined as a list of identifiers.  When this variable is evaluated, it has both a self-index (the list of identifiers) and a value, obtained by evaluating each of the variables appearing in the table and joining them into a single array.

In this model, most of the variables appearing in the list evaluate to a result that is indexed by [[Time]].  Therefore, the value obtained is two-dimensional, indexed by itself (<code>Cash_flow_statement</code>) and by [[Time]].

:[[image:Cash_flow_stmt_result.jpg]]

Side note: When Analytica displays a self-indexed result, and the self-index is composed of object identifiers, then Analytica uses separate number formats for each row (or column if pivoted), taking the number format for the corresponding row from the identifier that appears in the self-index.  This provides a capability to format each row of a table differently.

The value of <code>IndexValue(Cash_flow_statement)</code> in this example is composed of a list of [[varTerm]]s, essentially handles to Analytica objects.  In advanced Analytica modeling, these varTerms can be utilized for meta-level inference and button scripting (performing inference about the model itself).  Meta-level inference is beyond the scope of the current article, but we point this out for readers who may already be at this level of expertise.  

== Self-Indexes from the Domain ==
When the domain attribute contains an explicit list, either a list of expressions, list of labels, or index-domain, Analytica treats the domain value as the variable's self-index.  This is often used when defining a [[Choice]] definition, [[DetermTable]] or [[ProbTable]] definition.  For example, in a ProbTable, the main value (usually the [[Sample]]) is the randomly-sampled set of values, but the [[IndexValue]] for the variable is the set of all possible values.

The domain values can also be accessed using:
:<code>domain of X</code>

It should be noticed that the treatment of the domain value as a self-index value is a functionality that [http://lumina.com Lumina] plans to eventually eliminate.  If you wish to refer to the domain value of a variable, it is preferable to use "domain of X" rather than [[IndexValue]](X) to ensure forward compatibility with future releases of Analytica.

The use of the domain in a [[Choice]] definition, or to index a [[DetermTable]] or [[ProbTable]] will continue to be valid in future releases.  However, when the changes we envision are eventually enacted, we could allow for the possibility of a multi-select [[Choice]] control, for example.  In such a case, the main and index values could be a subset of the domain value.

Note: Few models utilize the domain of a variable as a self-index outside their use of [[Choice]](Self, n), [[DetermTable]] or [[ProbTable]], so this change only impacts models that do fairly unusual things.

==See also==
* [[Self]]
* [[Index]]
* [[Array]]
* [[IndexValue]]
* [[Domain Indexes]]