View source for Parameter qualifiers

[[Category:Analytica User Guide]]
[[Category: Functions]]

<breadcrumbs>Analytica User Guide > Building Functions and Libraries > {{PAGENAME}}</breadcrumbs><br />

__TOC__

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:

:<code>(a: Number Array[i, j]; i, j: Index; c; d: Atom Text Optional = “NA”)</code>

It defines five parameters. <code>a</code> should be an array of numbers, indexed by parameters <code>i</code> and <code>j</code>, and optionally other indexes. <code>i</code> and <code>j</code> must be index variables. <code>c</code> has no qualifiers, and so can be of any type or dimensions. (The semicolon “;” between <code>c</code> and <code>d</code> means that the qualifiers following <code>d</code> do  not apply to <code>c</code>. <code>d</code> 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 “<code>NA</code>”. 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.

:<code>Function Last(x; I: Index)</code>
:<code>Definition: Slice(x, I, Size(I))</code>

Because <code>x</code> and <code>I</code> are separated by a semicolon, the Index qualifier applies only to <code>I</code>. 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:

:<code>Function Fn1(x)</code>
:<code>Parameters: (x: Context)</code>
:<code>Mean(Fn1(x))</code>

[[Mean]]() is a statistical function that always evaluates its parameter probabilistically. Hence, the evaluation context for <code>x</code> is probabilistic, and so <code>Fn1</code> evaluates <code>x</code> probabilistically. 

<code>Context</code> is the default evaluation mode used when no evaluation mode qualifier is mentioned. So, strictly, <code>Context</code> 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:

:<code>Mean(x: ContextSample[i]; i: Index = Run)</code>

Thus, <code>Mean(x, Run)</code> evaluates <code>x</code> in prob mode. So does <code>Mean](x)</code>, because the index <code>i</code> defaults to [[Run]]. But, <code>Mean(x, j)</code> evaluates <code>x</code> in [[mid]] mode, because <code>j</code> 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:

:<code>(A: Prob [In1, Run])</code>

===Sample===

Evaluates the parameter probabilistically, i.e., in prob mode, if it can. If you declare the dimension of the parameter, include the dimension <code>Run</code> 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:

:<code>(A: Sample[In1, Run])</code>

===Index===

The parameter must be an index variable, or a dot-operator expression, such as <code>a.i</code>. 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 <code>Sum(x, i)</code> 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 <code>Scalar</code>.

===Atom===

<code>Atom</code> 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 <code>Atom</code> 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 <code>Atom</code> to qualify parameters of every function, just in case it’s needed. We strongly advise you not to do that: Functions with <code>Atom</code> 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 <code>Number Atom</code>.

===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 <code>a</code> is indexed only by the specified index(es). For example, if <code>Fu1</code> has the parameter declaration:

:<code>Function Fu1(a: Array[Time])</code>

and if <code>a</code>, when evaluated, contains index(es) other than <code>Time</code>, it iterates over the other index(es) calling <code>Fu1</code>, for each one, and thus ensuring that each time it calls <code>Fu1</code>, parameter a has no index other than <code>Time</code>. See [[Array]]()

An array declaration can specified zero or more indexes between the square brackets. With zero indexes, it is equivalent to the qualifier <code>Atom</code>, 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 <code>Array</code> is optional, so you could write simply:

:<code>Function F(a: Number [I])</code>

instead of

:<code>Function F(a: Number Array [I])</code>

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 <code>Parameters</code> attribute:

:<code>(A: [Time, j]; j: Index)</code>

specifies that parameter a must be an array indexed by <code>Time</code> (a built-in index variable) and by the index variable passed to parameter <code>j</code>.

In the absence of an array qualifier, Analytica accepts an array-valued parameter for the function, and passes it into the function <code>Definition</code> 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:

:<code>x: All [i, j]</code>

Here the <code>All</code> qualifier forces the value of <code>x</code> to be an array indexed by the specified index variables, <code>i</code> and <code>j</code>. If <code>x</code> is a single number, not an array, <code>All</code> converts it into an array with indexes, <code>i</code> and <code>j</code>, repeating the value of <code>x</code> in each element. Without <code>All</code>, Analytica would simply pass the atomic value <code>x</code> 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:

:{| class="wikitable"
! Name
! Description
|-
|Number
|A number, including <code>+INF, -INF, or NaN</code>
|-
|Positive
| A number greater than zero, including <code>INF</code>
|-
|Nonnegative
|Zero, or a number greater than zero including <code>INF</code>
|-
|Text
|A text value
|-
|Reference
|A reference to a value, created with the \ operator
|-
|Handle
|A handle to an Analytica object, obtained from the <code>Handle</code> or <code>HandleFromIdentifier</code> functions. It also accepts an array of handles.
|-
|OrNull
|Used in conjunction with one of the above type qualifiers, allows <code>Null</code> values in addition to the given type. For example: <br />
<code>x: Number OrNull</code><br />
Some array functions ignore <code>Null</code> 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 <code>Coerce</code> qualifier, it tries to convert, or coerce, the value of the parameter to the specified type. For example:<br />
<code>a: Coerce Text [I]</code><br />
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.
|}

<code>Coerce</code> supports these conversions:

:{| class="wikitable"
! From
! To
! Result
|-
|<code>Null</code> 
|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.
|-
|<code>Null</code>
|Reference
|<code>\Null</code>
|-
|Number
|Reference
|<code>\X</code>
|-
|Text
|Reference
|\Text
|}

Other combinations, including [[Null]] to<code> Number</code>, give an error message that the coercion is not possible.

==Ordering qualifiers: Ascending and Descending==

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

Ordering is not strict; that is, it allows successive elements to be the same. For example, <code>[1, 2, 3, 3, 4]</code> and <code>['Anne', 'Bob', 'Bob', 'Carmen']</code> 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:

:<code>A: Ascending [I]</code>

==Optional parameters==

You can specify a parameter as optional using the qualifier <code>Optional</code>, for example:

:<code>Function F(a: Number; b: Optional Number)</code>

In this case, you can call the function without mentioning <code>b</code>, as:

:<code>F(100)</code>

Or you can specify <code>b</code>:

:<code>F(100, 200)</code>

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

:<code>Function F(a: Number; b: Number Optional = 0)</code>

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

:<code>Function F(a: Number; b: Number = 0)</code>

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

:<code>Function G(A: Optional; B; C: Optional; D; E: Optional)</code>

You can call <code>G</code> in any of these ways:

:<code>G(1, 2, 3, 4, 5)</code>
:<code>G(1, 2, , 4)</code>
:<code>G( , 2, , 4)</code>
:<code>G( , 2, 3, 4, 5)</code>

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:

:<code>G(B: 2, D: 4)</code>

===IsNotSpecified](v)===

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

:<code>If IsNotSpecified(a) then a := 0;</code>

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

:<code>Function H(x;, a : = 0)</code>

==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:

:<code>Function ValMax(x: ... Number) := Max(x)</code>
:<code>ValMax(3, 6, -2, 4) &rarr; 6</code>

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

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

:<code>[3, 6, -2, 4]</code>

<code>ValMax()</code> also take array parameters, for example:

:<code>Variable Z := [0.2, 0.5, 1, 2, 4]</code>
:<code>ValMax(Sqrt(Z), Z^2, 0)</code>

By itself, the qualifier “...” means that the qualified parameter expects one or more parameters. If you combine “...” with <code>Optional</code>, 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:

:<code>Function F2(a; b: ...)</code>
:<code>F2(1, 2, 3, 4)</code>

Within the function, <code>F2</code>, the value of <code>a</code> is <code>1</code>, and the value of <code>b</code> 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:

:<code>Function Fxy(X: ... scalar; Y: ... Optional Scalar)</code>

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

:<code>Fxy(x: 10, 20, 40, y: 2, 3, 4)</code>

Or use position for the first repeated parameter group and name only the second parameter <code>y</code>:

:<code>Fxy(10, 20, 40, y: 2, 3, 4)</code>

Or enclose each set of repeated parameters in square brackets:

:<code>Fxy([10, 20, 40], [2, 3, 4])</code>

==Deprecated synonyms for parameter qualifiers==

Most parameter qualifiers have several synonyms. For example, <code>Atomic</code>, <code>AtomType</code>, and <code>AtomicType</code> are synonyms for <code>Atom</code>. We recommend that you use only the words listed above. If you encounter other synonyms in older models, see [[Function_Parameter_Qualifiers#Deprecated_Synonyms_for_Parameter_Qualifiers|Deprecated Synonyms for Parameter Qualifiers]].

== See Also ==
* [[User-Defined Functions]]
* [[Function calls and parameters]]
* [[Function Parameter Qualifiers]]
* [[ParameterEnumeration]]


<footer>Attributes of a function / {{PAGENAME}} / User Libraries</footer>