Parameter qualifiers
Parameter qualifiers are keywords you can use in the list of parameters to specify how, or whether, each parameter should be evaluated when the function is used (called), and whether to require a particular type of value, such as number or text value. Other qualifiers specify whether a parameter should be an array, and if so, which indexes it expects. You can also specify whether a parameter is optional, or can be repeated. By using qualifiers properly, you can help make functions easier to use, more flexible, and more reliable.
For example, consider this parameters attribute:
(a: Number Array[i, j]; i, j: Index; c; d: Atom Text Optional =“NA”)
It defines five parameters. a should be an array of numbers, indexed by parameters i and j, and optionally other indexes. i and j must be index variables. c has no qualifiers, and so can be of any type or dimensions. (The semicolon “;” between c and d means that the qualifiers following d do not apply to c. d is an Atom Text, meaning that it is reduced to a single text value each time the function is called, and is optional. If omitted it defaults to “NA”. See below for details.
What you must know
If you learn about no other qualifiers, the one qualifier you need to know about is Index. You should think about it this way: some parameters are values, and some parameters are indexes. The value parameters can exist with no qualifiers, but an index parameter must have the Index qualifier. If you create a function that operates over an index, you’ll want an index qualifier.
As an example, consider a function to return the last slice of an array along a given index.
Function Last( x ; I : Index ) Definition: Slice( x, I, Size(I) )
Because x and I are separated by a semicolon, the Index qualifier applies only to I. When you call this function, you must supply an index for the second parameter.
Evaluation mode qualifiers
Evaluation modes control how, or whether, Analytica evaluates each parameter when a function is used (called). The evaluation mode qualifiers are:
Context
Evaluates the parameter deterministically or probabilistically according to the current context. For example:
Function Fn1(x) Parameters: (x: Context) Mean(Fn1(x))
Mean() is a statistical function that always evaluates its parameter probabilistically. Hence, the evaluation context for x is probabilistic, and so Fn1 evaluates x probabilistically.
Context is the default evaluation mode used when no evaluation mode qualifier is mentioned. So, strictly, Context is redundant, and you can omit it. But, it is sometimes useful to specify it explicitly to make clear that the function should be able to handle the parameter whether it is deterministic or probabilistic.
ContextSample
Causes the qualified parameter to be evaluated in prob mode if any of the other parameters to the function are Run. If not, it evaluates in context mode — i.e., prob or mid following the context in which the function is called.
This qualifier is used for the main parameter of most built-in statistical functions. For example, Mean has these parameters:
Mean(x: ContextSample[i]; i: Index = Run)
Thus, Mean(x, Run) evaluates x in prob mode. So does Mean(x), because the index i defaults to Run. But, Mean(x, j) evaluates x in mid mode, because j is not Run.
When the parameter declaration contains more than one dimension, prob mode is used if any of the indexes is Run.
Mid
Evaluates the parameter determinstically, or in mid mode, using the mid (usually median) of any explicit probability distribution.
Prob
Evaluates the parameter probabilistically, i.e., in prob mode, if it can. If you declare the dimension of the parameter, include the dimension Run in the declaration if you want the variable to hold the full sample, or omit Run from the list if you want the variable to hold individual samples. For example:
(A: Prob [ In1, Run ])
Sample
Evaluates the parameter probabilistically, i.e., in prob mode, if it can. If you declare the dimension of the parameter, include the dimension Run in the declaration if you want the variable to hold the full sample, or omit Run from the list if you want the variable to hold individual samples. For example:
(A: Sample[ In1, Run ])
Index
The parameter must be an index variable, or a dot-operator expression, such as a.i. You can then use the parameter as a local index within the function definition. This is useful if you want to use the index in a function that requires an index, for example Sum(x, i) within the function.
Var
The parameter must be a variable, or the identifier of some other object. You can then treat the parameter name as equivalent to the variable, or other object name, within the function definition. This is useful if you want to use the variable in one of the few expressions or built-in functions that require a variable as a parameter, for example, WhatIf, DyDx, and Elasticity.
Array qualifiers
An array qualifier can specify that a parameter is an array with specified index(es) or no indexes, in the case of Scalar.
Atom
Atom specifies that the parameter must be an atom — a single number, text, or other value not an array — when the function is evaluated; but the actual parameter can be an array when you call the function. If it is an array when you call the function, Analytica disassembles it into atoms, and evaluates the function separately on each atomic element of the array. After these evaluates, it reassembles the results into an array with the same indexes as the original parameter, and returns is returned as the overall result.
You need to use Atom only when the function uses one of Analytica’s few constructs that require an atomic parameter or operand — i.e., that does not fully support array abstraction. See Ensuring array abstraction.
You might be tempted to use Atom to qualify parameters of every function, just in case it’s needed. We strongly advise you not to do that: Functions with Atom parameters can take much longer to execute with array parameters, because they have to disassemble the array-valued parameters, execute the function for each atom value, and reassemble them into an array. So, avoid using it except when really necessary.
Scalar
The parameter expects a single number, not an array. Means the same as Number Atom.
Array [i1, i2...]
Specifies that the parameter should be an array with the designated index(es) when it the function is evaluated. Similar to Atom above, you can still call the function with the parameter as an array with indexes in addition to those listed. If you do, it disassembles the array into subarrays, each with only the listed indexes. It calls the function for each subarray, so that a is indexed only by the specified index(es). For example, if Fu1 has the parameter declaration:
Function Fu1(a: Array[Time])
and if a, when evaluated, contains index(es) other than Time, it iterates over the other index(es) calling Fu1, for each one, and thus ensuring that each time it calls Fu1, parameter a has no index other than Time.
An array declaration can specified zero or more indexes between the square brackets. With zero indexes, it is equivalent to the qualifier Atom, specifying that the parameter must be a single value or atom each time the function is called.
The square brackets are sufficient and the qualifier word Array is optional, so you could write simply:
Function F(a: Number [I])
instead of
Function F(a: Number Array [I])
Each index identifier listed inside the brackets can be either a global index variable or another parameter explicitly qualified as an Index. For example the Parameters attribute:
(A: [Time, j]; j: Index)
specifies that parameter a must be an array indexed by Time (a built-in index variable) and by the index variable passed to parameter j.
In the absence of an array qualifier, Analytica accepts an array-valued parameter for the function, and passes it into the function Definition for evaluation with all its indexes. This kind of vertical array abstraction is usually more efficient for those functions that can handle array-valued parameters.
All
Forces the parameter to have, or be expanded to have, all the Indexes listed. For example:
x: All [i, j]
Here the All qualifier forces the value of x to be an array indexed by the specified index variables, i and j. If x is a single number, not an array, All converts it into an array with indexes, i and j, repeating the value of x in each element. Without All Analytica would simply pass the atomic value x into the function definition.
Type checking qualifiers
Type checking qualifiers make Analytica check whether the value of a parameter (each element of an array-valued parameter) has the expected type — such as, numerical, text, or reference. If any values do not have the expected type, Analytica gives an evaluation error at the time it tries to use (call) the function. The type checking qualifiers are:
Number A number, including +INF, -INF, or NaN. Positive A number greater than zero, including INF.
Name Description Number A number, including +INF, -INF, or NaN. 2 D, E, F 3 G, H, I
Enable comment auto-refresher