View source for User-Defined Functions

[[Category: Functions]]
[[Category: Definitions]]
[[Category:Doc Status D]] <!-- For Lumina use, do not change -->


__TOC__


You can create your own functions to perform calculations you use frequently. A function has one or more parameters; its definition is an expression that uses these parameters. You can specify that the function check the type or dimensions of its parameters, and control their evaluation by using various [[Function Parameter Qualifiers|parameter qualifiers]].

A ''Library'' is a a collection of functions grouped in a library file to extend Analytica’s built-in functions for use for particular types of applications. Analytica is distributed with an initial set of libraries, accessed from the [[File menu]] with the '''Add Library...''' option. If you add a Library to a model, it will appear with its functions in the Definition menu, and these functions will appear almost the same as the built-in functions.

You may want to look at these libraries to see if they provide functions useful for your applications. You may also look at library functions as a starting point or inspiration for writing your own functions.

Analytica experts may create their own function libraries for particular domains. Other Analytica users can benefit from these libraries.

One of the nice things about defining functions in Analytica is that the function definition uses the same expression syntax used to define variables, so that defining a new function is just like defining a variable, along with an additional ''parameters'' attribute.

== Example function ==

The following function, [[Capm]](), computes the expected return for a stock under the capital asset pricing model.

:<code>Parameters: (Rf, Rm, Beta: Numeric)</code>
:<code>Definition: Rf + Beta * (Rm - Rf)</code>

'''Sample usage:''' You use the [[Capm]]() function in a definition in the same way you would use Analytica’s built-in functions. For example, if the risk free rate is 5%, the expected market return is 8%, and ''StockBeta'' is defined as the beta value for a given stock, we can find the expected return according to the capital asset pricing model as: 
:<code>Stock_return: Capm(5%, 8%, StockBeta)</code>

This definition functions equally well when <code>StockBeta</code> is an array of beta values. In this case, the result will be an array of expected returns.

== Creating a function ==

To define a function:

# Make sure the [[toolbar|Edit tool]] ([[image:Edit Mode Toolbar Button.jpg]]) is selected and you can see the node palette.
# Drag the Function node icon from the node palette into the Diagram area.
# Title the node, and double-click on it to open its [[Object window]].
# Fill in the new function's attributes.  

== Attributes of a function ==

Like other objects, a Function is defined by a set of attributes.  Many of these attributes are the same as the attributes of Variables, including identifier, title, units, description, and definition, inputs, and outputs. It possesses one unique Attribute, Parameters, which specifies the parameters available to the function.

;'''Identifier''' :If you are creating a library of functions, make a descriptive identifier. This identifier appears in the function list for the library under the Definition menu, and is used to call the function. Analytica makes all characters except the first one lower case.

;'''Title''' :The title appears in the Function node.  It is usually good to have the title match the identifier, although for clarity you can also include a brief parameter description as part of the title.  For example, we might title our [[Capm]] function as <code>Capm(Rf, Rm, Beta)</code>.

;'''Units''' :If desired, use the units field to document the units of the function’s result. The units are not used in any calculation.

;'''Parameters''' :The parameters to be passed to the function must be enclosed in parentheses, separated by commas. For example: <code>(x, y, z)</code> 
:The parameters may have type qualifiers (see the next section).

:If you are creating a library of functions, use descriptive abbreviations for the parameters and give them a logical sequence. The parameters will appear in the [[Object Finder dialog]] box and they will be pasted when the function is pasted from its library in the [[Definition menu]].

:'''''Note:''' Earlier releases of Analytica (pre-4.0) limited the number of total parameters and local variables to 32.  No such limit exists any more -- you can have as many parameters as you desire.''

;'''Description''' :The '''Description''' should first document what the function returns, and explain each of its parameters. If the [[Definition]] is not immediately obvious, the second part of the '''Description''' should explain how it works. The '''Description''' text for a function in a Library will also appears in a scrolling box in the bottom half of the [[Object Finder dialog]].

;'''Definition''' :The [[definition]] of a function is an expression or compound list of expressions. It should usually use all of its parameters. When you select the [[definition]] field of a function in [[toolbar|Edit mode]], it shows the Inputs pull-down menu that lists the [[Function calls and parameters|parameters]] as well as any other Variables or functions that have been specified as inputs to the function. You can specify the inputs to a function in the same way as for a Variable—by drawing arrows from each input node into the function node.

; '''Recursive''' :If your function needs to call itself, or needs to call another function that will ultimately call your function again, then it is a recursive function.  By default, Analytica will issue an error message indicating that you have a dependency cycle if you attempt a recursive definition without setting this attribute to ''1'' (true).  Since recursive functions are fairly rare, this helps to catch mistakes.

If you really intend a recursive function, then you should set this parameter to true.  You can do this from the attribute pane (below the diagram), or you can configure Analytica to show the recursive attribute in the object window.  To keep things simple, the attribute is hidden by default. To configure it to show, select '''Attributes...''' from the [[Object menu]].  Select Function in the pulldown, and set a checkmark next to Recursive in the attribute list.  Then to indicate that your function should allow recursion, set the attribute to ''1''.

== Parameter qualifiers ==
[[Function Parameter Qualifiers | Parameter qualifiers]] are keywords you may use in [[Function calls and parameters|parameters]] to specify for each parameter how, or whether, it should be evaluated when the function is used (called), and whether it should have a particular type of value, such as number, text value, or other. 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. 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: Optional Atom Text)</code>

It defines five parameters, <code>A, I, J, C</code>, and <code>D</code>.<code>A</code> should be an array of numbers, indexed by parameters <code>I</code> and <code>J</code>. <code>I</code> and <code>J</code>, being separated
by commas "," rather than semicolons ";" are subject to the same qualifier, <code>IndexType</code>. <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> has three qualifiers, specifying that it is <code>Optional, Atomic</code>, and a text value.

The page [[Function Parameter Qualifiers]] defines all parameter qualifiers in detail.

[[Function Parameter Qualifiers]] provide very rich control over [[Evaluation Modes]] and [[Array Abstraction]], which can contribute a tremendous amount of programming power alone.

== Libraries ==

To do:
* Library icons, node shapes
* Creating a library
* Adding a filed (linked) library to a model
* Using a library
* screen shots.

==See Also==
* [[Define a function]]
* [[User-defined Functions and Libraries]]
* [[Function Parameter Qualifiers]]
* [[Conventions for parameters and operands]]