Parameter qualifiers

Analytica User GuideBuilding Functions and LibrariesParameter 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

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

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

Mid evaluates the parameter determinstically, or in mid mode, using the mid (usually median) of any explicit probability distribution.

Prob

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

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

Index indicates that 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

Variable or Var indicates that 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 or dimensionality 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

Scalar indicates that the parameter expects a single number, not an array. Means the same as Number Atom.

Array[i1, i2...]

Array 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. See Array()

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:

Name	Description
Number	A number, including +INF, -INF, or NaN
Positive	A number greater than zero, including INF
Nonnegative	Zero, or a number greater than zero including INF
Text	A text value
Reference	A reference to a value, created with the \ operator
Handle	A handle to an Analytica object, obtained from the Handle or HandleFromIdentifier functions. It also accepts an array of handles.
OrNull	Used in conjunction with one of the above type qualifiers, allows Null values in addition to the given type. For example: x: Number OrNull Some array functions ignore Null values, but require this qualifier for the null values to be accepted without flagging an error.
Coerce	If you accompany a Type checking qualifier by the Coerce qualifier, it tries to convert, or coerce, the value of the parameter to the specified type. For example: a: Coerce Text [I] tries to convert the value of a to an array of text values. It gives an error message if any of the coercions are unsuccessful.

Coerce supports these conversions:

From	To	Result
Null	Text	"Null"
Number	Text	Number as text, using the number format of the variable or function calling the function.
Text	Number or Positive	If possible, interprets it as a date or number, using the number format.
Null	Reference	\Null
Number	Reference	\X
Text	Reference	\Text

Other combinations, including Null to Number, give an error message that the coercion is not possible.

Ordering qualifiers: Ascending and Descending

The ordering qualifiers, Ascending or Descending, check that the parameter value is an array of numbers or text values in the specified order. For text values, Ascending means alphabetical order, and Descending means the reverse.

Ordering is not strict; that is, it allows successive elements to be the same. For example, [1, 2, 3, 3, 4] and ['Anne', 'Bob', 'Bob', 'Carmen'] are both considered ascending.

If the value of the parameter does not have the specified ordering, or it is an atom (not array) value, it gives an evaluation error.

If the parameter has more than one dimension (other than Run), you should specify the index of the dimension over which to check the order, for example:

A: Ascending [I]

Optional parameters

You can specify a parameter as optional using the qualifier Optional, for example:

Function F(a: Number; b: Optional Number)

In this case, you can call the function without mentioning b, as:

F(100)

Or you can specify b:

F(100, 200)

You can specify a default value for an optional parameter after an = sign, for example:

Function F(a: Number; b: Number Optional = 0)

It uses the default value if the actual parameter is omitted. Given an equal sign and default value, the Optional qualifier is itself optional (!):

Function F(a: Number; b: Number = 0)

Optional parameters can appear anywhere within the declaration — they are not limited to the final parameters. For example, if you declare the parameters for G as:

Function G(A: Optional; B; C: Optional; D; E: Optional)

You can call G in any of these ways:

G(1, 2, 3, 4, 5)

G(1, 2, , 4)

G( , 2, , 4)

G( , 2, 3, 4, 5)

Generally, you must include the commas to indicate an omitted optional parameter, before any specified parameter, but not after the last specified parameter.

Or you can use named-based calling syntax, which is usually clearer and simpler:

G(B: 2, D: 4)

IsNotSpecified](v)

If you omit a parameter that is not given a default value, you can test this inside the function definition using function IsNotSpecified(v). For example, the first line of the body of the function might read:

If IsNotSpecified(a) then a := 0;

But it is usually simpler to specify the default value in the parameter list as:

Function H(x;, a : = 0)

Repeated parameters (...)

Three dots, “...” qualifies a parameter as repeatable, meaning that the function accepts one or more actual parameters for the formal parameter. For example:

Function ValMax(x: ... Number) := Max(x)

ValMax(3, 6, -2, 4) → 6

ValMax() returns the maximum value of the actual parameters given for its repeated parameter, «x». Unlike the built-in Max() function, it doesn’t need square brackets around its parameters.

During evaluation of ValMax(), the value of the repeated parameter, «x», is a list of the values of the actual parameters, with implicit (Null) index:

[3, 6, -2, 4]

ValMax() also take array parameters, for example:

Variable Z := [0.2, 0.5, 1, 2, 4]

ValMax(Sqrt(Z), Z^2, 0)

By itself, the qualifier “...” means that the qualified parameter expects one or more parameters. If you combine “...” with Optional, it accepts zero or more parameters.

Calling a function that has only its last parameter repeated is easy. You just add as many parameters as you want in the call. The extra ones are treated as repeated:

Function F2(a; b: ...)

F2(1, 2, 3, 4)

Within the function, F2, the value of a is 1, and the value of b is a list [2, 3, 4].

If the repeated parameter is not the last parameter, or if a function has more than one repeated parameter, for example:

Function Fxy(X: ... scalar; Y: ... Optional Scalar)

You have several options for syntax to call the function. Use name-based calling:

Fxy(x: 10, 20, 40, y: 2, 3, 4)

Or use position for the first repeated parameter group and name only the second parameter y:

Fxy(10, 20, 40, y: 2, 3, 4)

Or enclose each set of repeated parameters in square brackets:

Fxy([10, 20, 40], [2, 3, 4])

Deprecated synonyms for parameter qualifiers

Most parameter qualifiers have several synonyms. For example, Atomic, AtomType, and AtomicType are synonyms for Atom. We recommend that you use only the words listed above. If you encounter other synonyms in older models, see Deprecated Synonyms for Parameter Qualifiers.

See Also

• User-Defined Functions
• Function calls and parameters
• Function Parameter Qualifiers
• ParameterEnumeration

Attributes of a functionParameter qualifiersUser Libraries