View source for MetaIndex..Do

[[category:Evaluation Functions]]
[[category:Meta-Inference Functions]]

(new to 4.0 -- available starting 4.0.0.35)

= MetaIndex I := expr Do body =

This declaration creates a local index object that does not evaluate its index elements when performing associative lookup, such as with [[Subscript]] or @[I=x].  

A MetaIndex..Do declaration is identical to a [[Index..Do]] declaration except that the local index object created as the [[MetaOnly]] attribute set to 1.

Local indexes declared using MetaIndex are used in [[Meta-Inference]], and are a topic for advanced Analytica expert modelers.  For most modeling tasks, use [[Index..Do]].

= When to use =

During [[Meta-Inference|meta-inference]], you might collect a list of objects and keep these as the elements of an index.  Your algorithm may then use this index used in associative lookup operations such as [[Subscript]].  Using a normal index in this case will cause the variables and expressions specified as index elements to be evaluated, causing errors or warnings to be issued if those variables have evaluation problems.  If your algorithm is reasoning about the model structure, you probably don't care about evaluating the underlying objects, and thus, a meta index would be used.

[[Meta-Inference]] is an advanced Analytica topic, but there are many potential meta-inference algorithm that could be useful, and could extend the capabilities of your Analyica application in important ways.  Example include:
* Creating custom reports about your model, for example, a table containing all the object descriptions and definitions, or reports printed to flat files with this information.
* Button script algorithms to alter your model, such as changing node colors to reflect some particular property.
* Collecting information about the objects in your model, as the Profiler.ana library does.
* Finding all ancestors with a certain property, as Make Importance does.
* Searching the model for object with certain properties.

= Controlling the Index Name =

It is possible to control the index name, which may be different from the local variable name referenced in the body.  The index name can even be computed dynamically.  The syntax for doing this is:

  MetaIndex J / nameExpr := seqExpr do bodyExpr

Here nameExpr is evaluated and must result in a text string that contains a valid identifier.  The nameExpr is then used in the [[A.I]] notation.  The local name, J here, can be referenced within bodyExpr.  

One instance where this control over the name is required is when you write a user-defined function that creates an N-dimensional array, where the dimensionality, N, is not known in advance.  Here you must loop over 1..N, creating a new local index during each iteration, but with a separate name each time.

= Examples =

== Sorting Objects ==

The following creates a list of objects in module Report_A, sorted by identifier:

 MetaIndex objs := contains of Report_A;
 var v := objs;
 Index Items := ['Identifier','Title','Description','Definition'];
 var a := Items;
 var info := a of v;
 MetaIndex sortedObjects := sortIndex( info[Items='Identifier'] );
 info[ objs = sortedObjects ]

The first line is the salient one in this example.  Had this used the [[Index..Do]] declaration, rather than the [[MetaIndex..Do]] declaration, the variables in Report_A would have been evaluated when info[objs=sortedObject] was encountered (they would be evaluated only the first time an associative lookup on that index occurs).  Here the evaluation is avoided.

== Avoiding An Ambiguity ==

With non-meta associative lookup, an ambiguity may arise when a variable in a non-meta index evaluates to an atom, and when that atomic literal also occurs in the index.  Demonstrated here:

 Variable A := 5
 Variable B := 2
 Variable C := VarTerm(A)
 Index I := [C,A,B,2]
 MetaIndex J := [A,B,2,C]

 @[I=2] &rarr; 3           { Ambiguous, could be 3 or 4, first is returned }
 @[J=2] &rarr; 4           { not ambiguous }

 @[I=VarTerm(A)] &rarr; 1  { Ambiguous, could be 1 or 2 }
 @[J=VarTerm(A)] &rarr; 2  { not ambiguous }
 
= See Also =

* [[Index..Do]]
* [[MetaOnly]] attribute
* [[Meta-Index]]
* [[Subscript/Slice Operator]]
* [[MetaVar..Do]], [[LocalAlias..Do]]