Analytica Docs - User contributions [en]

DbQuery/Step-by-Step querying Microsoft Access

2019-10-18T19:36:24Z

KMullins: Added a link to the Northwinds database, since it doesn't seem to come with Office 365

[[Category: Database Functions]]

__TOC__

This mini-tutorial takes you through a step-by-step process of connecting to and querying data from a Microsoft Access database using [[DbQuery]].

== Find the Database ==

Microsoft Access 2000 and later includes a sample database called ''Northwind'' that we will use for this exercise. First, locate this database on your computer and view it in Access:

* Start Microsoft Access
* Select File → Open..., and find the <code>Northwind.mdb</code> file, usually at:
:<code>C:\Program Files\Microsoft Office\Office11\Samples\Northwind.mdb</code>
* If you don't have a local copy, the database can be downloaded from Microsoft Templates at [https://omextemplates.content.office.net/support/templates/en-us/tf01228997.accdt this link]
* After opening in Access, it may display an introduce dialog. Click through this and examine the list of Tables. Open the <code>Customers</code> table. We'll query this table from Analytica.

== Set up a Data Source ==

Here you will set up a DSN for the Northwind database, which will allow you to connect to it by name from [[DbQuery]]. To do this, follow these steps:
* ''Start → Control Panel → Administrative Tools → Data Sources (ODBC)''
* Click the ''System DSN'' tab.
* Press Add..., select ''Microsoft Access Driver (<code>*.mdb</code>)''
* Enter:
:<code>Data Source Name: Northwind</code>
:<code>Description: Sample database from Microsoft Access</code>
* Press the '''Select...''' button, and navigate to the <code>Northwind.mdb</code> database file identified earlier. Select it.
* Press '''OK''' to complete the Data Sources dialog.

Now we have a data source named <code>Northwind</code> that we can connect to using [[DbQuery]]. With this datasource, we can query any of the tables in the Northwind database.

== Set up the Analytica model ==

Now you will create the query in an Analytica model.
* Start Analytica
* Drag an index node to the diagram, title it <code>Customer Number</code>
* Set its definition to:
:<code>DbQuery("DSN=Northwind", sql: "select * from Customers")</code>
* Evaluate it.

At this point, if you've done things correctly, you'll see an index from 1 to 91 (or however many records are present in your own Customers table).

* Drag another index node to the diagram, name it <code>Customer Field</code>, define it as:
:<code>DbLabels(Customer_Number)</code>
* Drag a variable node to the diagram, name it <code>Customer Table</code>, and define it as:
:<code>DbTable(Customer_Number, Customer_Field)</code>
* Evaluate <code>Customer_Table</code>

The data is now imported (as shown below).

:[[Image:ODBC_Customer_Table.JPG]]

== Reindexing the Table ==

For convenience, we may want to use the <code>CustomerID</code> column of the table as the row index. To do this, we'll re-index the data.

* Create a new index node, name it <code>CustomerID</code>, defined as:
*:<code>CopyIndex(DbTable(Customer_Number,"CustomerID"))</code>

This will now serve as our row index.
* Change the definition of <code>Customer_Field</code> to:
*:<code>index tmp := DbLabels(Customer_Number) do subset(tmp <> "CustomerID")</code>
* Change the definition of <code>Customer_Table</code> to
*:<code>DbTable(Customer_Number, Customer_Field) [@Customer_Number = @CustomerID]</code>
* Re-evaluate <code>Customer_Table</code>. You should see a two-D table having indexes: <code>CustomerID</code> and <code>Customer_Fields</code>
*:[[Image:ODBC_Customer_Table_re-indexed.JPG]]

==See Also==
* [[DbQuery]]
* [[Querying Access database from Analytica 64]]
* [[Database functions]]

Iterate

2019-08-13T21:47:44Z

KMullins:

[[category:Evaluation Functions]]
[[category:Top level functions]]
[[Category:Doc Status D]] 

== Iterate(initial, expr, until'', maxIter, warn'') ==
Repeats the computation «expr» until the termination condition «until» becomes true (nonzero), or the number of iterations reaches «maxIter». The parameters «expr» and «until» may, and usually do, depend on variable(s) that depends on the variable defined with Iterate. This creates a recurrence, [[Draw arrows#Influence cycle or loop|cycle or loop]] in the influence diagram, something that is not otherwise allowed except in [[Dynamic]] loops. Analytica iterates the evaluation around the cycle until it reaches the termination condition «until», usually a convergence or equilibrium.

You may use [[Iterate]] only as the main function defining a variable (as with [[Dynamic]]). You may not nest it inside an expression.

'''Parameters:'''
* «initial»: the starting value for the iteration
* «expr»: how the subsequent values are computed from the previous value. «expr» may, and usually does, depend directly or indirectly upon the variable defined by Iterate, forming a recurrence or cycle in the influence diagram.
* «until»: The termination condition. Iterate continues evaluating «expr» until «until» is true (non-zero) -- if «until» is an array, until all its elements are true (nonzero) -- or until the number of iterations reaches «maxIter», if specif.
* ''«maxIter»'': (optional) The maximum number of iterations. If omitted, it will keep iterating until the «until» becomes true. Unless you are absolutely certain the iteration will converge, it is a good idea to specify a value for «maxinter».
* ''«warn»'': (optional) If true (nonzero), it will give a warning if it terminates due to reaching the maximum number of iterations «maxinter», rather than the termination condition «until».

[[Iterate]] is useful when you want adjust a variable and repeat a calculation over several variables in the model to meet a constraint. If you can perform the iteration within the definition of a single variable or [[User-Defined Functions]], it is usually simpler and clearer to use the [[While..Do]] construct.

For more complex cases, especially when you want to adjust multiple variables to solve constraints and/or find a maximum or minimum, it is simpler and faster to use the [[Analytica Optimizer Guide|Analytica Optimizer]].

== Example ==
:[[Image:Market Equilibrary Diagram.jpg]]

This examples models how a market price reaches equilibrium to correct an imbalance between supply and demand. It forecasts a the supply and demand given an initial price, and modifies the <code>Price</code> iteratively until the supply exactly matches the demand reaching a market equilibrium. <code>Price</code> is defined as:

:<code>Price := Iterate(Price_Guess, Next_price, Abs(Next_price-price) < 0.01, 50)</code>

It iterates until the change in price between successive iterations is less than 0.01, or reaches 50 iterations.

== Iterating Multiple Variables ==
You may want to update several variables in each iteration: For example, both <code>Price</code> and <code>Market_size</code>. You should define only one variable using [[Iterate]]. (If you define both <code>Price</code> and <code>Market_size</code> using [[Iterate]], it will create two nested iterations, which would not do what you want.) Instead, you can define a new single variable that groups all the variables into a single state, listing them along an index.

:[[Image:Market Equilib Diagram2.jpg]]

In the above diagram, <code>State_index</code> is defined as a list of labels:
:{| class="wikitable"
! State_index ▼
|-
| "Price"
|-
| "Market Size"
|}

You define the initial state and next state each as a table indexed by <code>State_index</code>:

:<code>Variable Initial_state := Table(State_index)(Price_Guess, Market_size_guess)</code>
:<code>Variable Next_State := Table(State_Index)(Price_Guess, Market_size_guess)</code>

and define <code>State</code> using Iterate:
:<code>Variable State := Iterate(Initial_state, Next_State, abs(state-next_state) < 0.01, 50)</code>

For convenience in the rest of the model, it is useful to define <code>Price</code> and <code>Market_Size</code> as the elements of <code>State</code>:
:<code>Variable Price := State[State_Index = 'Price']</code>
:<code>Variable Market_Size := State[State_Index = 'Market Size']</code>

So far, we assume that <code>State</code> and <code>Market_size</code> have the same dimensions -- both are scalars, or both are arrays with the same indexes. If you want them to have different dimensions, you can include their values using [[Using References|references]]:

:<code>Variable Initial_state := </code>
::<code>Table(State_index)(\Price_guess, \Market_size_guess)</code>
:<code>Variable Next_state := </code>
::<code>Table(State_Index)(\Price_Guess, \Market_size_guess)</code>
:<code>Variable Price := </code>
::<code>#State[State_index = 'Price']</code>
:<code>Variable Market_size :=</code>
::<code>#State[State_index = 'Market Size']</code>
:<code>Variable State :=</code>
::<code>Iterate(Initial_state, Next_State, </code>
:::<code>Abs(Price-next_price) < 0.01 AND Abs(Market_size - Next_market_size) < 1, </code>
:::<code>50)</code>

Note that '[[Using References|\]]' and '[[#]]' are the reference and de-reference operators. Gathering references to values into an array is a flexible method that generalizes to any number of variables.

== Iterate with Dynamic ==
Iterate can be used in conjunction with [[Dynamic]]. Depending on the model structure, this can either result in an iteration within a dynamic loop, where the iteration to convergence occurs at each point in time, or it can result in a dynamic loop within an iteration, in which case the entire dynamic loop is computed to completion within each iteration.

Suppose <code>X</code> is a variable defined with Iterate, and <code>Y</code> is a variable defined with [[Dynamic]]. Then <code>X</code> might depend directly or indirectly on <code>Y</code>, and <code>Y</code> might depend directly or indirectly on <code>X</code>. This creates four distinct dependency structures. When neither <code>X</code> nor <code>Y</code> depends on the other, then there is no interaction. Similarly, when <code>Y</code> depends on <code>X</code>, but <code>X</code> is not downstream of <code>Y</code>, then <code>X</code> is not within <code>Y</code>'s dynamic loop, so again there is no interaction. In this case, <code>X</code> is iterated to completion once, independent of the dynamic loop, then the dynamic loop performs its looping using this value.

When <code>X</code> depends on <code>Y</code>, but <code>Y</code> does not depend on <code>X</code>, then the dynamic loop is completely inside the Iteration for <code>X</code>, so that the dynamic loop is computed to completion within each iteration.

The most difficult case is when <code>X</code> and <code>Y</code> both depend on the other. When this happens, the iterate expression could, in principle, be interpreted as being inside the dynamic or around the dynamic. Analytica resolves this ambiguity by assuming that the iterate is inside the dynamic, so that as the dynamic loop is evaluated at each time period, the iteration in <code>X</code> is run to completion for that time period. Variables inside <code>X</code>'s definition are implicitly assumed to be sliced by the current dynamic time (as occurs with any variable appearing inside a dynamic loop).

You may encounter situations where you want to compute one or more variables using Iterate, which in turn are utilized within a dynamic loop, but where you desire the iteration to occur around the dynamic loop. For example, you may have completed an entire [[Dynamic]] model, and now you want to wrap [[Iterate]] around the full model to adjust an input parameter. In the future, we may introduce a new variation on the iterate function that would make it possible to specify that [[Iterate]] is wrapped around a given dynamic loop. Until then, one way to cause Iterate to wrap around a dynamic loop is by using a [[WhatIf]] to compute the value of the input parameter. To demonstrate, suppose you have an input parameter, <code>K</code>, used by a dynamic model having some output <code>Y</code>. We want to define <code>K</code> using [[Iterate]] where the update expression and termination expressions depend on <code>Y</code>. To do this, we introduce two variables:
:<code>Variable Y2 := WhatIf(Y, K, K2)</code>
:<code>Variable K2 := Iterate(K, f(K2, Y2), g(K2, Y2))</code>

Here <code>f()</code> is the update expression and <code>g()</code> is the termination expression. When <code>K2</code> is evaluated, the iteration re-evaluates the full model repeatedly, with <code>K2</code> eventually being set to the "converged" value for the parameter <code>K</code>. As a final step, we may want to set <code>K</code> to be this computed value for <code>K2</code>. For this last step, we would need to use a button:
:<code>Button Update_K := (K := K2)</code>

Pressing the button causes the entire evaluation to take place.

(To do: provide some examples)

== Interacting Iterate Functions ==
If you have two (or more) variables defined using the [[Iterate]] function, they should not be mutually dependent on each other. This case creates an ambiguity (for example, the result would depend on which was evaluated first), and results in an error message.

It is okay for one to be nested within the other, in which case the inner iteration runs to convergence during each iteration of the outer iterate. However, the need for nested iterations like this are rare. You should make sure that you don't intend to have a single iteration with multiple variables updated in the same iteration (see the earlier section on this page).

If you have two interacting Iterate loops that are not clearly nested, you will see this error message:

:''A disallowed cyclic dependency involving the Iterate function in ''ident'' detected. You may have two nodes defined with Iterate functions, with each depending on the other. If you use two Iterate functions, one needs to be clearly nested inside the other. If you intend to have a single iteration involving two or more nodes, the Iterate function should appear only once.''

=== Iterate with Change in Evaluation Mode ===
Suppose <code>X</code> is defined using [[Iterate]], and the update expression depends on [[Sample]](X) -- for example, it may use a statistical function like [[Mean]](X). If <code>X</code> is evaluated in [[Mid]] mode, it appears as if there are two interacting Iterate loops, and the above error message, ''A disallowed cyclic dependency involving Iterate....'' occurs.

== Iterate vs. While..Do ==
[[Iterate]] and [[While..Do]] are closely related, and both are often used for implementing convergence algorithms. When implementing an iterative algorithm in a [[User-Defined Functions|User-Defined Function]], you would normally use [[While..Do]]. However, in some situations you may develop a fairly sizable influence diagram model, where you wish to iterate over the entire model. In that case, Iterate is very convenient, and may require only small modifications.

The [[While..Do]] construct requires its parameter, which determines when the loop terminates, to be atomic, while [[Iterate]] allows array-valued termination conditions, but continues until all cells are true.

There are a few other approaches to implementing iterations within Analytica. [[NlpDefine]] performs a full optimization search. The [[Solve]] and [[GoalSeek]] functions are similar, although scaled down somewhat in their sophistication. [[User-Defined Functions]] can be recursive, although the [[recursion]] depth is usually limited to 255, which can be a limiting factor. And to iterate over an existing model structure, [[While..Do]] can be used with [[WhatIf]], or from a button script, [[While..Do]] can be used with assignment (often a useful way to iterate in very large scale sampling applications that exceed memory required for built-in Monte Carlo sampling). And of course, there is [[Dynamic]].

== See Also ==
* [[Analytica_User_Group/Past_Topics#The_Iterate_Function|Webinar on the Iterate Function]]
* [[Dynamic]]
* [[ComputedBy]]
* [[While..Do]]
* [[Using References]]
* [[DefineOptimization]]
* [[WhatIf]]
* [[Recursion]]
* <code>Newton Raphson Method.ana</code> example model in the <code>Example Models/Decision Analysis folder</code> installed with Analytica

User Input nodes

2019-08-12T21:23:25Z

KMullins: Update to match User Output updates

[[Category:Analytica User Guide]]
[[Category:Nodes]]
<breadcrumbs>Analytica User Guide > User Interfaces for End Users > {{PAGENAME}}</breadcrumbs>
{{ReleaseBar}}

An '''''input node '''''lets you, or your end user, see and easily change the value of a variable directly in the diagram, without opening an ''Attribute ''view or [[Object window]] (see [[Browsing with input and output nodes]]). In browse mode you can change only the values and definitions of input nodes.

An input node is an alias of a variable that you want to treat as an input to the model (see [[Alias nodes]]).

The type of definition of the original variable determines the appearance of the input node. If you want your users to be able to change the type of definition, instruct them on how to open an ''Attribute ''view or [[Object window]] and use the [[The Expression popup menu|expr menu]].

'''Input field'''

[[Image:Chapter9 2.png]] A single number or text value (scalar) displays as an input field. You can have Analytica check if the input value is acceptable by using the [[Checking for valid values|Check attribute]]; the check is performed on input of a new value. {{Release|5.0||After creating the input field, you should select '''Number only''', '''Text only''' or '''Number or text only''' from the Definition type pulldown in the [[Attribute panel]] or [[Object Window]] if you want to disallow the entry of general expressions.}}

'''Checkbox'''

[[Image:Checkbox.png]] A true/false or yes/no selection.

<div id="Input_popup_menu">'''Input popup menu'''</div>

[[Image:Chapter9 3.png]] A choice displays as an input popup menu. To create an input menu for an input node, see [[Creating a choice menu]].

'''List'''

[[File:Chapter9 4.png]] A list or list of labels displays as a '''List '''button. See [[Creating an index]].

'''Edit table'''

[[File:Chapter9 5.png]] An edit table displays as an '''Edit Table '''button. See [[Defining a variable as an edit table]].

'''Probability distribution'''

[[File:Chapter9 6.png]] A probability distribution displays a button with the name of the distribution. See [[Defining a variable as a distribution]].

'''Creating an input node''': To create an input node from a variable:

# Make sure you are in [[edit mode]].
# Select the variable.
# There are three options once you have selected the node:
#* Select '''Make Input Node '''from the [[Object menu]]
#* Right click the node and select '''Make User Input Node'''
#* Use the keyboard shortcut ''Ctrl+Alt+I''
# Move the input node to the location you want.
# Adjust the size of the node.

<tip title="Tip">To make several input nodes at once, select the nodes and then choose '''Make Input Node'''.</tip>

==See Also==
* [[User input nodes and user output nodes]]
* [[User output nodes]]

<footer>User interfaces / {{PAGENAME}} / Choice menu user input</footer>

User output nodes

2019-08-12T21:07:43Z

KMullins: Added three options to create User Output Node

[[Category:Analytica User Guide]]
[[Category:Nodes]]
<breadcrumbs>Analytica User Guide > User Interfaces for End Users > {{PAGENAME}}</breadcrumbs>
{{ReleaseBar}}

An '''''output node '''''gives you, or your end user, rapid access to a selected result in the model. You can use output nodes to focus attention on particular outputs of interest.

An output node displays a result value in the view style — i.e., whether table or graph, the indexes displayed, and the uncertainty view — last selected for display and saved with the model. {{Release||4.6|It also shows}}{{Release|5.0||Optionally, you can also show}} the uncertainty view icon (see [[Uncertainty views]]){{Release|5.0|| by turning on the '''Show result mode icons''' [[Preferences|preference setting]]}}.

:[[Image:Chapter9 9.png]] If the result is a single value (mid value or mean), it displays directly in the output field. {{Release|5.0||The <code>mid</code> seen here is the optional uncertainty view icon.}}

:{{Release||4.6|[[Image:Chapter9 10.png]]}}{{Release|5.0||[[Image:ResultButton.png]]}} If the result is a table, the output node displays a '''Result '''button. Click the button to display the table or graph. After you display the table or graph, you can use the result toolbar to change the view.

:{{Release||4.6|[[Image:Chapter9 11.png]]}}{{Release|5.0||[[Image:CalcButton.png]]}} If the value of an output has not yet been computed, the '''Calc '''button appears in the node. Click the '''Calc '''button to compute and display the value.

'''Creating an output node''': To create an output node from a variable:
# Make sure you are in [[edit mode]].
# In a [[Diagram window]], select the node of the variable for which you wish to create an output node.
# There are three options once you have selected the node:
#* Select '''Make Output Node '''from the [[Object menu]]
#* Right click the node and select Make User Output Node
#* Use the keyboard shortcut Ctrl+Alt+O
# Move the output node, which appears in the diagram next to the selected node, to the location you want.
# Adjust the size of the node.

The view style of the output result (table or graph) is the format you last set for it (see [[Number and table formats]] and [[Graphs]]).

'''Resizing controls''':

{{Release||4.6|
:[[image:Chapter9 12.png]]}}
{{Release|5.0||
:{{CalloutAnnotationBlock|<br/><br/><br/>
[[image:Output node with resizing handles.png]]|
{{CalloutAnnotation|Drag left edge of control to resize|Type=Bare|v=0|pt=165,20|path=rmD10|style=width:300px}}
{{CalloutAnnotation|Drag handles to resize node|Type=Bare|v=120|pt=235,32|path=r(235,8)mr(22,8)mr(22,32)mr|style=width:200px}}
}} }}

You can resize input and output nodes by dragging their corner handles, just like other nodes. But for these, its usually most convenient to deselect '''Resize centered '''from the [[Diagram menu]] so you can align them either along their right edges, or both edges.

You can also drag the left edge of the control field, button, or menu left or right to change its width. This is especially useful for choice menus when you want to expand the width to be large enough for the widest menu option.

When using a pull-down menu containing long text values, you might want to adjust the pull-down control as necessary to accommodate your longest text value. Input and output nodes contain text and graphics, in addition to the control itself. The node resizing handles that appear as small black squares at the corners of the node adjust the size of the bounding rectangle that holds all these items, but does not change the width of the control itself. To change the width of a control (a pull-down menu, textedit box, or button), position the mouse over the left edge of the control, depress the mouse button and drag the cursor to the left or right.

==See Also==
* [[User input nodes and user output nodes]]
* [[User Input nodes]]

<footer>Checkbox user input / {{PAGENAME}} / User inputs and outputs as aliases</footer>

Objects and Their Attributes - Part 2 of 3

2019-08-07T17:31:50Z

KMullins:

[[Category: Analytica Scripting Guide]]
[[Category: Objects]]
[[Category: Attributes]]

<breadcrumbs>Analytica Scripting Guide > {{PAGENAME}}</breadcrumbs>

==User-Specified Attributes==

Objects may be described by various attributes. Some of these attributes may be specified by the user. These are known as user-specified attributes. For example, when you create a variable, you usually supply four attributes for it: Title, Units, Description, and Definition. The user-specified attributes are summarized below:

'''Author'''<br>The author(s) of a model or another object. By default, this is the computer’s registered user name (on Macintosh, specified in the Sharing Setup control panel).

'''Title'''<br>
Brief text used to identify a variable. Titles can be up to 255 characters; however Analytica often truncates them to fit.

'''Description'''<br>
One or more lines about what an object represents. Descriptions will help you, and other people who access the model, understand it.

'''Definition'''<br>
An expression that Analytica uses to compute the value of an object. A definition may be a simple number, an array, a probability distribution or a mathematical Expression that includes other variables. Definitions may be several lines long.

'''Units'''<br>
The units of measurement of a variable, e.g., $/yr. You can leave the Units field blank if the variable is a number or a dimensionless ratio.

'''Parameters'''<br>
When you create a new mathematical Function, you may specify a list of parameters for each Function. See [[UDF|User-defined functions]] and [[Function Parameter Qualifiers]].

'''Check'''<br>
A test that Analytica conducts on the validity of the value of a variable. A [[Check attribute]] is an Expression that contains the variable to be tested. If checking evaluates to False (or 0), Analytica warns you that the value of the variable is questionable. [[Check attribute]]s are described later in this manual.

'''Usecheck'''<br>
An attribute that controls whether a variable will (or won't) be checked for legality according to its Check attribute whenever it is evaluated. Usecheck overrides the system variable Checking for the particular variable to which it is attached.

'''Script'''<br>
An attribute that contains a sequence of commands each separated by carriage returns that are executed when the user clicks on the button containing the script.

'''Balloonhelp'''<br>
An attribute that contains help that appears when the mouse is over the object's node in a Diagram window. By default, Analytica uses the Description attribute for an object in Balloon Help. This attribute is available only on the Macintosh.

'''Indexvals'''<br>
An attribute that may be defined as a list or list of labels, and function as a Self index for a variable table definition. This attribute is normally set by Analytica, but can be user-specified.

'''Domain'''<br>
An attribute that may be defined as a list or list of labels, and function as a Self domain for a variable probtable definition. This attribute is normally set by Analytica, but can be user-specified.

==Computed Attributes==

In addition to user-specified attributes, there are computed attributes that Analytica adds to objects. Analytica generates the values of computed attributes. Other computed attributes used internally by Analytica are listed in the Appendix.

'''Date''' (displays as '''Created''')<br>
The date and time the model was first created.

'''Savedate'''<br>The last time the model was saved.

'''Saveauthor'''<br>The user who last modified a model, if different from the owner of the computer on which the model is created.

'''Inputs'''<br>A list of variables and functions that appear in the definition of the specified variable or function.

'''Outputs'''<br>A list of variables and functions that refer to this object in their Definitions.

'''Value'''<br>The deterministic value of a variable.

'''Probvalue'''<br>The probabilistic value of a variable.

'''Contains'''<br>The list of variables and other objects created within a model.

'''Isin'''<br>The model to which an object belongs.

==User Interface Attributes==

Many computed attributes are set by the graphical user interface in Analytica, and are called User Interface attributes. User Interface attributes are only represented visually and are usually not examined or modified directly by the user. These attributes range from window state information, to node location, color and font.

An object's node location and node size can be specified using the following attributes:

'''Nodelocation''' ''h, v'' <br>Horizontal and vertical coordinates (in Diagram space) of the node representing this object.

'''Nodesize''' ''w, h''<br>Half-width and half-height (in Diagram space) of the node representing this object.

An object’s information can be viewed in a number of windows; hence there are several different attributes used to store window state information, depending on the window type needed. The format of these window state attributes is as follows:

'''attribute''' ''version, left, top, width, height [, attribs]'' <br>
*''version'' indicates the version of this attribute's format; 1 in the current version of Analytica
*''left'' and ''top'' are the top-left screen coordinates of the window
*''width'' and ''height'' are the window’s width and height

Additional information regarding node style, diagram style, and result state may follow these values, depending on the attribute.

'''[[NodeInfo]]''': Controls display options for a node, including arrows, node border, label and so on. See [[NodeInfo]]

'''DiagramColor'''<br>
red, green, blue

'''Nodecolor''' ''red, green, blue''<br>
These are Diagram and Node background color attributes, respectively; light gray by default for diagrams, white by default for nodes. Color information is stored as RGB (Red, Green, Blue) components. Each RGB component is an integer value from 0 to 65,535. RGB color is additive, which means that as the value of a component is increased, the amount of that component in the total color decreases. An RGB color is black if all three components are set to 0; white if each component is set to 65,535. A negative value (-32767 to -1) is internally transformed by adding 65536.

'''Fontstyle''' ''fontname, fontsize''

'''Nodefont''' ''fontname, fontsize''<br>
These are Diagram and Node font attributes, respectively, containing font name and font size. , fontsize is in pixels, not points. These are the same on a 1/72 dots per inch screen. VGA screens are usually 1/96 dots per inch, so an n pixel font size is 72/96 * n points.

(Note, the NodeFont attribute is only used when the NodeInfo attribute setting for UseNodeFont is set to 1.)

'''Defaultsize''' ''width, height''<br>
This is the default half-height and half-width for a node, used when creating new nodes in a diagram.

'''Icon''' ''hexdata'' <br>
Node icon information is stored as hexadecimal ASCII text. Analytica automatically "compiles" this information into the icon format when an icon is represented on the screen.

'''Graphsetup''' ''commands''<br>
Graphsetup contains a sequence of graph system variable assignments separated by carriage returns (and using the "~" continuation character), to be used when creating a graph result of the variable to which it is assigned.

'''ReformDef [''' ''col, row'' ''']'''<br>
'''[[ReformVal]] [''' ''col, row'' ''']'''<br>These are row/column reform state attributes for [[Edit Table]] and [[Result window]]s, respectively. col and row, inside brackets specify the index variable for the column and row, respectively.

'''Numberformat''' ''version, formatcode, digits, zeroes, separators, currency''
Numberformat specifies how a number (result or output node) should be displayed.

*version is the current format version (1.0)
*formatcode has the following values:
:{|class="wikitable"
! code||name||example
|-
|D||Suffix||1.235K
|-
|E||Expoential||1.235e+4
|-
|F||Fixed point||12345.68
|-
|I||Integer||12346
|-
|%||Percent||1234567.80%
|-
|DD ||Date||Tue, Oct 19, 1937
|-
|DB ||Boolean||True
|}

* ''digits'' specifies the number of digits for suffix and exponent formats.

* ''zeroes'' specifies the number of digits after the decimal point for fixed point, integer and percent formats.

* ''separators'' and ''currency'' only apply to fixed point formats; values are 0 (don’t show) or 1 (show).

'''Xyexpr''' ''expr''<br>
Specifies an expression to graph against, as an x-y scatter graph. This is used by the Analytica interface.

==Inspecting Objects==

To see all of the user-specified attributes of an object, you use the Show Command, as illustrated in the transcript below:

:<code>Example>show mpy</code>
:<code>variable Mpy</code>
:<code>Title: miles per year</code>
:<code>Units: Miles/year</code>
:<code>Description: Annual mileage driven</code>
:<code>Definition: 12K</code>
:<code>Nodelocation: 208,48</code>
:<code>Nodesize: 52,24</code>

To see the entire contents of a model (i.e., all of the user-defined objects in the model), you use the '''Allshow''' Command. Note that the output from Allshow may be as large as the model file itself.

To see a particular attribute of an object, you type the attribute and the object's identifier, as illustrated below:

:<code>Example>title mpy</code>
:<code>miles per year</code>
:<code>Example></code>

To see a summary of a variable, including its title, units, and value, you type its identifier. For example, to see a summary of variable Mpy (the entire variable is shown in the preceding example),

:<code>Example>mpy</code>
:<code>mpy Miles per year (miles/year) = 12K</code>
:<code>Example></code>

To display the value of a variable, you ask for the Value attribute, as illustrated below:

:<code>Example>value mpy</code>
:<code>12K</code>
:<code>Example></code>

A discussion of possible values for variables is given elsewhere in this manual.

==See Also==
* [[Tutorial: Decision trees#Defining_Party_Location_as_a_list_of_labels|Tutorial: Defining Party Location as a list of labels]]

<footer>Objects and Their Attributes - Part 1 of 3 / {{PAGENAME}} / Objects and Their Attributes - Part 3 of 3</footer>

GraphToCanvasCoord

2019-07-26T22:05:13Z

KMullins:

(''New to [[Analytica 5.2]]'')

This function is only used from within the [[OnGraphDraw]] attribute expression, or from [[User-Defined Functions]] that are called from [[OnGraphDraw]]. Use this function when you need to figure out the pixel coordinates of a data point on the graph when annotating a graph using the [[Drawing images|Canvas Drawing Functions]].

== GraphToCanvasCoord( info, roles, x,y'', cluster, flags'' ) ==

Returns the pixel coordinates, xPx and yPx in a graph with specified info and roles, given the data coordinates, «x» and «y».
«x» is in units of the variable or index used for the independent axis -- i.e. the horizontal axis unless you have checked '''Swap horizontal and vertical''' in [[Graph Setup]]. «y» is in units of the dependent axis, usually the vertical axis. For example, when viewing a graph of ''Revenue'' vs. ''Time'', this code in the [[OnGraphDraw]] attribute) draws a circle on the graph at Time=2020, Revenue=1M

::[[Local]] (x,y) := [[GraphToCanvasCoord]](info, roles, 2020, 1M );
::[[CanvasDrawEllipse]](canv, x-5, y-5, 11, 11)

The function returns pixel x and pixel y as separate return values, so you have to capture multiple return values to access y. Hence, in the above example, you must include the parentheses around <code>(x,y)</code> in the [[Local]] declaration.

Do not use this function when <code>phase=1</code> -- before layout -- because <code>info</code> and <code>roles</code> have not yet been established at that point.

When you have a bar chart with a color index and a cluster index, you can use this to map from (x, y, cluster) to pixel x, pixel y. In this case, both «x» and «y» are categorical values, often text. When supplying «cluster», named parameter calling syntax is required (at least for «cluster». At present, the function does not handle clustered bar charts that use a value for the Color role (as opposed to an index for the Color role).

Graphs can be pivoted by the end-user, so your code in ''OnGraphDraw'' may need to be cognizant about which value is assigned to which axis.

The function automatically adjusts for linear vs. log axis scaling, continuous vs. categorical axes, Swap horizontal and vertical, and reverse axis order, and manual axis scaling (e.g., zoom) in the current view. As a result, it greatly simplifies the creating of graph annotations.

An end-user can also manually scale an axis, for example to zoom into a part of the graph. In this case, the data point you map to pixels may land outside of the visible plot area. You may want to take this into account in your annotation code. In some cases, you might want to not draw anything for these out-of-range points, for example when annotating points with labels -- otherwise, the label would be dawn outside the plot area. In other cases, you might want to clip the drawing to the plot area (using [[CanvasContext]], for example when drawing lines between points. The 3rd return value is a boolean (or array of booleans when transforming an array of points) that indicates whether the point is within the plot area visible range. Or you can set «flag» to 1 to return null for out-of-range pixel x or pixel y, which will often cause your drawing code to ignore these points automatically without any additional code or your part.

=== Parameters ===
* «info», «roles»: These are the values for the local variables <code>info</code> and <code>roles</code> that are available to [[OnGraphDraw]]. You need to just forward those as-if to this function. These are not available in the 'before layout' phase, i.e., when <code>phase=1</code>; hence, the function cannot be used in that phase.
* «x»: A value along the dependent-axis -- i.e., along the horizontal axis when '''Swap horizontal and vertical''' is off, or along the vertical axis when it is on.
* «y»: A value along the independent-axis -- i.e., along the vertical axis when '''Swap horizontal and vertical''' is off, or along the horizontal axis when it is on.
* «cluster»: (Optional) A value in the cluster index in a clustered bar chart. Only use this for a clustered bar chart with an index for Color. (At present, the function does not support the case where a value is used for color). This parameter must be specified using a named-parameter syntax, e.g., <code>cluster:someVal</code>.
* «flags»: (Optional). A sum of zero or more of the following values:
** 1 = Return [[Null]] for pixel x or pixel y when the respective «x» or «y» value is not within the current plot area. When a graph is manually scaled (zoomed), some points may land outside of the plot area. Without this flag, it will return pixel coordinates that may land outside that plot area frame.
** 2 = Return the "far" end of a categorical interval along the y-axis. This would be the "top" of a bar, for example, in a horizontal bar chart with a non-reversed axis. Without this (or flag=4), the center of the category interval is returned. This flag is ignored for non-bar-charts unless the flag=8 bit is set.
** 4 = Return the "near" end of a categorical interval along the y-axis. Ignored for non-bar-charts except with the flag=8 bit is set.
** 8 = Apply the flag=2 or flag=4 bit to non-bar charts. Without this, flag=2 or flag=4 apply only to bar charts.

=== Return values ===
It returns three values:
# The horizontal coordinate of the point in pixel coordinates.
# The vertical coordinate of the point in pixel coordinates.
# True when the point is within the plot area (given the current axis scaling), False if it falls outside the current plot area.

To access the 2nd and 3rd return values, you must use the multiple-return-value capture syntax, which consists of placing parentheses around the local identifiers as follows:

:<code>[[Local]] (pixel_x, pixel_y, isVisible) := [[GraphToCanvasCoord]](...)</code>

== See Also ==
* [[OnGraphDraw]]
* [[Drawing images]]

OnGraphDraw

2019-07-26T22:01:53Z

KMullins:

[[category:Attributes]]
{{ReleaseBar}}

This attribute lets you annotate a graph with text, lines, areas, and other graphics -- for example, to add labels to points, or point out interesting aspects of a graph. It even lets you show a map or other image under a graph, and display points over it. The annotations may depend on the values being graphed and so reposition themselves as the data changes. It also provides a hook where you can enhance graphing functionality (or make use of existing functions that do so) when there is something you want that the built-in graphing engine support.

Two libraries are included with [[Analytica 5.2]] that provide functions for use in the [[OnGraphDraw]] with pre-implemented effects:
* The [[:Category:OnGraphDraw annotations library functions|OnGraphDraw annotations library]] provides functions for plotting [[Plot_error_bars|error bars]], [[Plot_Tukey_bars|Tukey bars]], [[Plot_point_labels|labels on data points]], [[Plot_solid_band|a filled range behind data]] and [[Plot_solid_prob_bands|filled probability bands]].
* The [[:Category:Google Maps from OnGraphDraw library functions|Google Maps from OnGraphDraw library]] provides functions for [[OnDraw_Google_map|drawing a Google map]] behind your data (or said differently, for plotting data over a Google map). This library requires [[Analytica Enterprise]] or better.

Additional libraries of functions that perform various types of annotations or graphs may become available over time, and may be contributed by other Analytica users.

{{Release|5.1|5.1|''This feature is '''experimental''' until [[Analytica 5.2]] and may be subject to future non-backward-compatible changes.''}}
{{Release||5.0|''Requires [[Analytica 5.2]] or later.''}}
{{Release|5.2||''New to [[Analytica 5.2]]}}

== Attribute OnGraphDraw ==

You can specify an expression in the [[OnGraphDraw]] attribute, which is evaluated while a graph is being drawn. The expression uses [[Drawing images|drawing commands on a Canvas]], which lies under or over the standard graph plot.

You can write code in [[OnGraphDraw]] to draw nearly anything you can dream up, but unless you are a power user, you are more likely to make use of libraries of pre-existing [[User-Defined Functions]] that implement specific plots, embellishments or effects.

[[OnGraphDraw/Label Minimum and maximum|Here is an example]] that finds and labels the minimum and maximum points in a data series:

[[image:onGraphDraw_min_and_max.png]]

The graphing engine scaled and drew the axes and plotted the points. The code in the [[OnGraphDraw]] attribute found the min and max points and drew the annotations. ([[OnGraphDraw/Label Minimum and maximum|See how this was done]]).

In this example, [[OnGraphDraw]] gets a map from Google maps and draws it behind the plotted data. Here the X-Y graph has three data points connected by two lines:

[[Image:onGraphDraw_map.png]]

The [[OnGraphDraw]] expression obtains the map from Google maps using [[ReadFromURL]] -- the map is not served by the graphing engine itself. The library function [[OnDraw_Google_map]] makes it easy to include graph on a map ([[Analytica Enterprise]] required) -- see [[OnDraw_Google_map]] for instructions.

=== Locals ===

These local variables are accessible within an [[OnGraphDraw]] expression, and give information about the graph and the current graphing roles:
* '''''canv''''': The canvas. This is what you draw to using the [[Drawing images|canvas drawing functions]].
* '''''info''''': A vector of information about the graph, such as the dimensions of the graph and location of the plot area. The vector is indexed by the system index [[OnGraphDrawItem]] index.
* '''''phase''''': The drawing phase. This enables you to detect at what stage of the graph rendering the attribute is being evaluated. Possible values are: 1=Before graphing has started, 2=After the graph layout has been calculated, but before anything is drawn, 4=After the background and axes have been drawn, but before the data is plotted, 8=After the graph has been fully rendered (except for your own embellishments).
* '''''roles''''': Information about the graphing dimensions that fill each graphing role. This is indexed by [[GraphingRole]] and [[GraphFillerInfo]].
* '''''continue''''': A boolean that you can set to false if you don't want the graph to be drawn any further beyond this point. This can be used to substitute your own custom drawing code in place of the built-in graphing engine, which might include totally different graphical depictions.
* '''''roleChanges''''': It is possible to alter axis scaling by changing items in this local. For example, you may need to adjust the axis range in order to register a map image so that data plotted on top appear at the correct latitude and longitude.

=== When OnGraphDraw is evaluated ===

By default, it evaluates the expression in [[OnGraphDraw]] after rendering the graph data. That's useful when you want to draw the annotations on the graph over the data. You can also set it to evaluate at three earlier phases of drawing. To set this preference, check the appropriate box in the [[OnGraphDraw]] attribute in the [[Object Window]] of the graphed variable:
<center>[[image:OnGraphDraw-checkboxes.png]]</center>

{{Release|5.1|5.1|''Note: These checkboxes are not present in [[Analytica 5.1]], so you need to the system variable [[OnGraphDrawFlags]] to a number equal to the sum of the phase values listed next.''}}

''Note: These check boxes appear in the [[Object window]], but not in the [[Attribute pane]].''

It evaluates [[OnGraphDraw]] during each phase of the graph rendering that you check:
* 1: '''Evaluate before layout''': Call before graphing has started, including before determining the layout info, such as the plot area. To replace a graph entirely with a custom graphical depiction of your own, enable this, and set <code>continue:=0</code> in your [[OnGraphDraw]] code.
* 2: '''Evaluate before drawing''': Call after determining the layout, but before drawing anything, so annotations will appear behind any background and axes.
* 4: '''Evaluate after axes, before data''': Draw annotations after the background and axes, but behind data points, lines or bars.
* 8 '''Evaluate after fully drawn''' (default) Call after the standard graphing has completed to annotate the graph or data with images in front of the data.
The check boxes in the object window are stored in the '''OnGraphDrawFlags''' attribute of the graphed object, using a value equal to the sum of the values show for phase.

The local variable <code>phase</code> contains one of these values and can be used inside an [[OnGraphDraw]] expression to detect which phase it is. When you select more than one of these options, you should usually include an [[If|If-Then]] branch on the local <code>phase</code>.

=== To access OnGraphDraw ===
{{Release||5.1|The [[OnGraphDraw]] Attribute is currently an experimental feature. To make it visible, press F12 to open the [[Typescript Window]], and then type: <code>AskAttribute OnGraphDraw, Variable, yes</code>}}
{{Release|5.2||By default, the [[OnGraphDraw]] attribute does not appear in the [[Attribute pane]] or [[Object window]]. To see it, go to the [[Attributes dialog]] on the [[Object menu]] and enable it for ''Variables''.}}

It will now appear in the [[Attribute panel]] and [[Object window]], where you can give it an Analytica expression.

=== Basics of drawing ===
To draw on the graph surface, use the [[Drawing images|Canvas drawing functions]] to draw to <code>canv</code> where <code>canv</code> is the name of a local variable available to you in the [[OnGraphDraw]] attribute. For example:

:'''OnGraphDraw:''' <code>[[CanvasDrawRectangle]]( canv, x:100, y:130, width:80, height:50, fillColor:0x440000ff )</code>

[[image:onGraphDraw_rect1.png]]

This rectangle always appears at the same location, and doesn't adapt when the graph window is resized; therefore, its location does not necessarily coincide with any particular data, unless by chance. The difficult part is writing code that figures out where to draw. The plot area in canvas pixel coordinates is provided in the local variable named <code>info</code> as illustrated here:

<code>
::{|border="0"
|'''OnGraphDraw:''' || [[CanvasDrawEllipse]](canv, || x:info[OnGraphDrawItem='PlotAreaLeft'],
|-
|   ||   || y:info[OnGraphDrawItem='PlotAreaTop'],
|-
|   ||   || width: info[OnGraphDrawItem='PlotAreaWidth'],
|-
|   ||   || height: info[OnGraphDrawItem='PlotAreaHeight'],
|-
|   ||   || fillColor:0x440000ff )
|}
</code>

[[image:onGraphDraw_plotArea.png]]

The y-axis scale goes from <code>roles[GraphingRole='Y axis', GraphFillerInfo='Min']</code> to <code>roles[GraphingRole='Y axis', GraphFillerInfo='Max']</code>. So to annotate a threshold at y=1000, you could use this [[OnGraphDraw]] expression

[[image:OnGraphDraw_afterFullyDrawn.png]]
[[Local]] yThresh := 1000;
[[Local]] (ignore,y) := [[GraphToCanvasCoord]](info,roles,0,yThresh);
[[Local]] x1 := info[OnGraphDrawItem='PlotAreaLeft'];
[[Local]] x2 := info[OnGraphDrawItem='PlotAreaWidth'] + x1;
[[CanvasDrawLine]]( canv, x1,y, x2, y, color:'Green', width:3);
[[CanvasDrawText]](canv, "Threshold", x1, y, color:'Green', vAlign:'Bottom')

[[image:onGraphDraw_threshold.png]]

=== Replacing the plot entirely, but using the same axes ===
A probability bands graph plot is normally draw with lines, such as:
:[[image:OnGraphDraw_OriginalBandsPlot.png|533px]]

By using [[OnGraphDraw]], we can retain the axes and axes scaling, but replace the plot itself with custom-drawn Tukey bars:
:[[image:OnGraphDraw TukeyBands.png|533px]]

In this case, the [[OnGraphDraw]] will be set as follows
:[[image:OnGraphDraw_TukeyBandsCall.png]]
Two key things are happening here. First, it is evaluated after the axes are drawn but before the data is drawn, and second, it sets the local <code>continue</code> to false if it draws the Tukey bars. The pre-existing [[UDF]] <code>Tukey_bars</code> returns true when it draws the bars, false otherwise. The function has a line that checks whether you are viewing the Bands view, so that other uncertainty views continue to render in their default fashion.
<code>
::[[If]] info[OnGraphDrawItem='ViewMode']<>'Bands' [[Then]] ...
</code>
The key is also turned off in graph setup, since the colors shown in the key no longer apply.

=== Clipping to the plot area ===

When you draw to <code>canv</code>, you can draw on any part of the graph. So if you aren't careful, annotations that you expect to draw on the data may extend outside of the plot area (the area bounded by the axes). In some cases this may be what you want, but in other cases you may want to clip to the plot area.

In this example, error bars are draw around the mean value points without any clipping. It does not look natural for these bars to extend outside of the plot area.

'''OnGraphDraw:''' { simplistic version }
[[Local]] spread := SDeviation(Self);
[[Local]] xPt := #roles[GraphingRole='X axis', GraphFillerInfo='Value'];
[[Local]] yPt := #roles[GraphingRole='Y axis', GraphFillerInfo='Value'];
[[Local]] (xUp,yUp) := [[GraphToCanvasCoord]](info,roles,xPt,yPt+spread);
[[Local]] (xDn,yDn) := [[GraphToCanvasCoord]](info,roles,xPt,yPt-spread);
[[CanvasDrawLine]](canv,xUp,yUp,xDn,yDn);
[[CanvasDrawLine]](canv,xUp-4,yUp,xUp+4,yUp);
[[CanvasDrawLine]](canv,xDn-4,yDn,xDn+4,yDn)

:[[image:OnGraphDraw_ErrorBarsNoClip.png]]

To fix this, you can draw to a [[CanvasContext|canvas context]] that has been clipped to the plot area, rather than drawing directly to <code>canv</code>. The above code is modified as follows, where <code>clip</code> is a clipped canvas context:

'''OnGraphDraw:''' { still simplistic, but with clipping }
[[Local]] spread := SDeviation(Self);
[[Local]] xPt := #roles[ [[GraphingRole]]='X axis', [[GraphFillerInfo]]='Value'];
[[Local]] yPt := #roles[ [[GraphingRole]]='Y axis', [[GraphFillerInfo]]='Value'];
[[Local]] (xUp,yUp) := [[GraphToCanvasCoord]](info,roles,xPt,yPt+spread);
[[Local]] (xDn,yDn) := [[GraphToCanvasCoord]](info,roles,xPt,yPt-spread);
<span style="background:yellow">[[Local]] clip := Clip_to_PlotArea(canv, info);</span>
[[CanvasDrawLine]](<span style="background:yellow">clip</span>,xUp,yUp,xDn,yDn);
[[CanvasDrawLine]](<span style="background:yellow">clip</span>,xUp-4,yUp,xUp+4,yUp);
[[CanvasDrawLine]](<span style="background:yellow">clip</span>,xDn-4,yDn,xDn+4,yDn)

:[[image:OnGraphDraw_ErrorBarsWithClip.png]]

where the Clip_to_plotArea is a [[User-Defined Function]] that returns a canvas context clipped to the plot area. It is implemented as follows:

Function <code>Clip_to_plotArea(canv,info) :=
:[[Local]] (x,y,w,h) := _(...info[ [[OnGraphDrawItem]]='PlotArea'&['Left','Top','Width','Height'] ]);
:[[CanvasContext]](canv, clip:x,y,w,h)
</code>

=== Modifying the axis scale ===

The graphing engine selects the axis scale based on the data, and it does not know about stuff that you draw. In same cases you may need to adjust the axis scales so that the range includes your annotations. This section will illustrate one example where this comes up -- when drawing error bars around a point, the range of the error bars around mean-value points extend outside of the range of the plotted mean points. At least when the axis is auto-scaled, you need to extend the min and max data points. Another example occurs when rendering a Google map behind the data. You need to adjust the actual min and max latitude and longitude to the map actually returned by the Google server, even when your axes are manually scaled.

Changes to the scale must occur in the "before drawing" phase, so you need to enable evaluation of [[OnGraphDraw]] before drawing (as well as in the phase when you will actually render your annotations). During the before drawing phase, phase=2, your code needs to make modifications to the local variable <code>roleChanges</code>, which the rendering engine will then use while drawing the axes in the next phase.

The relevant addition for rescaling is highlighted. This part occurs during phase=2, whereas the remaining previous code is not in the else (not phase 2). The key point is that in phase=2, it modifies the min and max to include the extrema of the error bars.

[[image:OnGraphDraw_PhaseBeforeAxes_and_after.png]]
[[Local]] spread := [[SDeviation]](Self);
[[Local]] yRole := roles[ [[GraphingRole]]='Y axis' ];
[[Local]] yPt := #yRole[ [[GraphFillerInfo]]='Value' ];
<span style="background:lightyellow">[[If]] phase = 2 and yRole[ [[GraphFillerInfo]]='Autoscale'] [[Then]] (</span>
<span style="background:lightyellow">roleChanges[ [[GraphingRole]]='Y axis', [[GraphFillerInfo]]='Max' ] := MaxAll(yPt+spread);</span>
<span style="background:lightyellow">roleChanges[ [[GraphingRole]]='Y axis', [[GraphFillerInfo]]='Min' ] := MinAll(yPt-spread);</span>
<span style="background:lightyellow">)</span> Else (
[[Local[[ xPt := #roles[ [[GraphingRole]]='X axis', [[GraphFillerInfo]]='Value' ];
[[Local]] (xUp,yUp) := [[GraphToCanvasCoord]](info,roles,xPt,yPt+spread);
[[Local]] (xDn,yDn) := [[GraphToCanvasCoord]](info,roles,xPt,yPt-spread);
[[Local]] clip := Clip_to_plotArea(canv,info);
[[CanvasDrawLine]](clip,xUp,yUp,xDn,yDn);
[[CanvasDrawLine]](clip,xUp-4,yUp,xUp+4,yUp);
[[CanvasDrawLine]](clip,xDn-4,yDn,xDn+4,yDn)
)
:[[image:OnGraphDraw_ErrorBarsWithAdjustedYScale.png]]

=== Adapting to Swap XY ===

The error bar example so far has a problem when you Swap XY. Can you spot it:
:[[image:OnGraphDraw_ErrorBarsSwapXY_bad.png]]
The problem has to do with the way we draw the caps at the end of each error bar. They are still being drawn horizontally, but now need to be drawn vertically. Here the code that draws one of those ticks:
:<code>[[CanvasDrawLine]](clip,xDn-4,yDn,xDn+4,yDn)</code>
It draws a line from 4 pixels left of the bar end to 4 pixels right of the bar end. When we've swapped XY, we effectively want instead
:<code>[[CanvasDrawLine]](clip,xDn,yDn-4,xDn,yDn+4)</code>

The following addition accomplishes this (unchanged lines not shown):
<code>
:[[Local]] ticW:=4, ticH:=0;
:[[If]] info[ [[OnGraphDrawItem]]='SwapXY'] [[Then]] ( ticW:=0; ticH:=4 );
:...
:[[CanvasDrawLine]](clip,xUp-ticW,yUp-ticH,xUp+ticW,yUp+ticH);
:[[CanvasDrawLine]](clip,xDn-ticW,yDn-ticH,xDn+ticW,yDn+ticH);
</code>
:[[image:OnGraphDraw_ErrorBarsSwapXY.png]]

=== Encapsulating drawing code ===
You may want to show error bars for a different variable. You don't want to repeat all this code every time, and of course, if you later make a bug fix or improvement, you'll want all your plots to inherit that fix. Hence, you should encapsulate this code as a [[User-Defined Function]]. Once you do this, when new variables want error bars, you'll just need to call your UDF from [[OnGraphDraw]] AND you'll need make sure to check the correct check boxes to specify when it is evaluated.

Encapsulating tends to be easy. You're function parameters are whichever of the special local variables (including possibly Self) that your code used. You have some choices about how you want to encapsulate it. For example, do you want your error bar function to only operate from Mean result view? Or do you want to let your caller decide? Do you want to always depict one standard deviation, or do you want your caller to specify the spread?

When your logic changes the <code>continue</code> or the <code>roleChanges</code> variable, then your function will need to return the new value, and the caller needs to set it. In the error bar example, it makes modifications to <code>roleChanges</code>, so this needs to be returned. So the call in [[OnGraphDraw]] will be:

:<code>roleChanges := Plot_error_bars( canv, info, roles, phase, [[SDeviation]](Self) )</code>

When you make changes to both, your function will need to return two return values, and your caller will use:
:<code>(continue, roleChanges) := My_annotation_function(....)</code>

Wrapping it all up, the Plot_error_bars function becomes:
Function Plot_error_bars( canv, info, roles, phase, spread ) :=
[[Local]] yRole := roles[ [[GraphingRole]]='Y axis'];
[[Local]] yPt := #yRole[ [[GraphFillerInfo]]='Value'];
[[Local]] roleChanges := null;
 
[[If]] phase = 2 and yRole[ [[GraphFillerInfo]]='Autoscale' ] [[Then]] (
roleChanges[ [[GraphingRole]]='Y axis', [[GraphFillerInfo]]='Max'] := MaxAll(yPt+spread);
roleChanges[ [[GraphingRole]]='Y axis', [[GraphFillerInfo]]='Min'] := MinAll(yPt-spread);
) else if phase=8 then (
[[Local]] ticW:=4, ticH:=0;
[[If]] info[ [[OnGraphDrawItem]]='SwapXY'] [[Then]] ( ticW:=0; ticH:=4 );
[[Local]] xPt := #roles[ [[GraphingRole]]='X axis', [[GraphFillerInfo]]='Value'];
[[Local]] (xUp,yUp) := [[GraphToCanvasCoord]](info,roles,xPt,yPt+spread);
[[Local]] (xDn,yDn) := [[GraphToCanvasCoord]](info,roles,xPt,yPt-spread);
[[Local]] clip := Clip_to_plotArea(canv,info);
[[CanvasDrawLine]](clip,xUp,yUp,xDn,yDn);
[[CanvasDrawLine]](clip,xUp-ticW,yUp-ticH,xUp+ticW,yUp+ticH);
[[CanvasDrawLine]](clip,xDn-ticW,yDn-ticH,xDn+ticW,yDn+ticH);
);
roleChanges

== See Also ==
* [[Drawing images]]
* [[:Category:OnGraphDraw annotations library functions|OnGraphDraw annotations library]]
** [[Plot_error_bars]]
** [[Plot_point_labels]]
** [[Plot_Tukey_bars]]
** [[Plot_solid_prob_bands]]
** [[Plot_solid_band]]
* [[:Category:Google Maps from OnGraphDraw library functions|Google Maps from OnGraphDraw library]]
** [[OnDraw_Google_map]]
* [[OnGraphDraw/Label Minimum and maximum]] example
* Index of «info»: [[OnGraphDrawItem]]
* Indexes of «roles»: [[GraphingRole]] and [[GraphFillerInfo]]

OnGraphDraw

2019-07-26T21:54:50Z

KMullins: /* See Also */

[[category:Attributes]]
{{ReleaseBar}}

This attribute lets you annotate a graph with text, lines, areas, and other graphics -- for example, to add labels to points, or point out interesting aspects of a graph. It even lets you show a map or other image under a graph, and display points over it. The annotations may depend on the values being graphed and so reposition themselves as the data changes. It also provides a hook where you can enhance graphing functionality (or make use of existing functions that do so) when there is something you want that the built-in graphing engine support.

Two libraries are included with [[Analytica 5.2]] that provide functions for use in the [[OnGraphDraw]] with pre-implemented effects:
* The [[:Category:OnGraphDraw annotations library functions|OnGraphDraw annotations library]] provides functions for plotting [[Plot_error_bars|error bars]], [[Plot_Tukey_bars|Tukey bars]], [[Plot_point_labels|labels on data points]], [[Plot_solid_band|a filled range behind data]] and [[Plot_solid_prob_bands|filled probability bands]].
* The [[:Category:Google Maps from OnGraphDraw library functions|Google Maps from OnGraphDraw library]] provides functions for [[OnDraw_Google_map|drawing a Google map]] behind your data (or said differently, for plotting data over a Google map). This library requires [[Analytica Enterprise]] or better.

Additional libraries of functions that perform various types of annotations or graphs may become available over time, and may be contributed by other Analytica users.

{{Release|5.1|5.1|''This feature is '''experimental''' until [[Analytica 5.2]] and may be subject to future non-backward-compatible changes.''}}
{{Release||5.0|''Requires [[Analytica 5.2]] or later.''}}
{{Release|5.2||''New to [[Analytica 5.2]]}}

== Attribute OnGraphDraw ==

You can specify an expression in the [[OnGraphDraw]] attribute, which is evaluated while a graph is being drawn. The expression uses [[Drawing images|drawing commands on a Canvas]], which lies under or over the standard graph plot.

You can write code in [[OnGraphDraw]] to draw nearly anything you can dream up, but unless you are a power user, you are more likely to make use of libraries of pre-existing [[User-Defined Functions]] that implement specific plots, embellishments or effects.

[[OnGraphDraw/Label Minimum and maximum|Here is an example]] that finds and labels the minimum and maximum points in a data series:

[[image:onGraphDraw_min_and_max.png]]

The graphing engine scaled and drew the axes and plotted the points. The code in the [[OnGraphDraw]] attribute found the min and max points and drew the annotations. ([[OnGraphDraw/Label Minimum and maximum|See how this was done]]).

In this example, [[OnGraphDraw]] gets a map from Google maps and draws it behind the plotted data. Here the X-Y graph has three data points connected by two lines:

[[Image:onGraphDraw_map.png]]

The [[OnGraphDraw]] expression obtains the map from Google maps using [[ReadFromURL]] -- the map is not served by the graphing engine itself. The library function [[OnDraw_Google_map]] makes it easy to include graph on a map ([[Analytica Enterprise]] required) -- see [[OnDraw_Google_map]] for instructions.

=== Locals ===

These local variables are accessible within an [[OnGraphDraw]] expression, and give information about the graph and the current graphing roles:
* '''''canv''''': The canvas. This is what you draw to using the [[Drawing images|canvas drawing functions]].
* '''''info''''': A vector of information about the graph, such as the dimensions of the graph and location of the plot area. The vector is indexed by the system index [[OnGraphDrawItem]] index.
* '''''phase''''': The drawing phase. This enables you to detect at what stage of the graph rendering the attribute is being evaluated. Possible values are: 1=Before graphing has started, 2=After the graph layout has been calculated, but before anything is drawn, 4=After the background and axes have been drawn, but before the data is plotted, 8=After the graph has been fully rendered (except for your own embellishments).
* '''''roles''''': Information about the graphing dimensions that fill each graphing role. This is indexed by [[GraphingRole]] and [[GraphFillerInfo]].
* '''''continue''''': A boolean that you can set to false if you don't want the graph to be drawn any further beyond this point. This can be used to substitute your own custom drawing code in place of the built-in graphing engine, which might include totally different graphical depictions.
* '''''roleChanges''''': It is possible to alter axis scaling by changing items in this local. For example, you may need to adjust the axis range in order to register a map image so that data plotted on top appear at the correct latitude and longitude.

=== When OnGraphDraw is evaluated ===

By default, it evaluates the expression in [[OnGraphDraw]] after rendering the graph data. That's useful when you want to draw the annotations on the graph over the data. You can also set it to evaluate at three earlier phases of drawing. To set this preference, check the appropriate box in the [[OnGraphDraw]] attribute in the [[Object Window]] of the graphed variable:
<center>[[image:OnGraphDraw-checkboxes.png]]</center>

{{Release|5.1|5.1|''Note: These checkboxes are not present in [[Analytica 5.1]], so you need to the system variable [[OnGraphDrawFlags]] to a number equal to the sum of the phase values listed next.''}}

''Note: These check boxes appear in the [[Object window]], but not in the [[Attribute pane]].''

It evaluates [[OnGraphDraw]] during each phase of the graph rendering that you check:
* 1: '''Evaluate before layout''': Call before graphing has started, including before determining the layout info, such as the plot area. To replace a graph entirely with a custom graphical depiction of your own, enable this, and set <code>continue:=0</code> in your [[OnGraphDraw]] code.
* 2: '''Evaluate before drawing''': Call after determining the layout, but before drawing anything, so annotations will appear behind any background and axes.
* 4: '''Evaluate after axes, before data''': Draw annotations after the background and axes, but behind data points, lines or bars.
* 8 '''Evaluate after fully drawn''' (default) Call after the standard graphing has completed to annotate the graph or data with images in front of the data.
The check boxes in the object window are stored in the '''OnGraphDrawFlags''' attribute of the graphed object, using a value equal to the sum of the values show for phase.

The local variable <code>phase</code> contains one of these values and can be used inside an [[OnGraphDraw]] expression to detect which phase it is. When you select more than one of these options, you should usually include an [[If|If-Then]] branch on the local <code>phase</code>.

=== To access OnGraphDraw ===
{{Release||5.1|The [[OnGraphDraw]] Attribute is currently an experimental feature. To make it visible, press F12 to open the [[Typescript Window]], and then type: <code>AskAttribute OnGraphDraw, Variable, yes</code>}}
{{Release|5.2||By default, the [[OnGraphDraw]] attribute does not appear in the [[Attribute pane]] or [[Object window]]. To see it, go to the [[Attributes dialog]] on the [[Object menu]] and enable it for ''Variables''.}}

It will now appear in the [[Attribute panel]] and [[Object window]], where you can give it an Analytica expression.

=== Basics of drawing ===
To draw on the graph surface, use the [[Drawing images|Canvas drawing functions]] to draw to <code>canv</code> where <code>canv</code> is the name of a local variable available to you in the [[OnGraphDraw]] attribute. For example:

:'''OnGraphDraw:''' <code>[[CanvasDrawRectangle]]( canv, x:100, y:130, width:80, height:50, fillColor:0x440000ff )</code>

[[image:onGraphDraw_rect1.png]]

This rectangle always appears at the same location, and doesn't adapt when the graph window is resized; therefore, its location does not necessarily coincide with any particular data, unless by chance. The difficult part is writing code that figures out where to draw. The plot area in canvas pixel coordinates is provided in the local variable named <code>info</code> as illustrated here:

<code>
::{|border="0"
|'''OnGraphDraw:''' || [[CanvasDrawEllipse]](canv, || x:info[OnGraphDrawItem='PlotAreaLeft'],
|-
|   ||   || y:info[OnGraphDrawItem='PlotAreaTop'],
|-
|   ||   || width: info[OnGraphDrawItem='PlotAreaWidth'],
|-
|   ||   || height: info[OnGraphDrawItem='PlotAreaHeight'],
|-
|   ||   || fillColor:0x440000ff )
|}
</code>

[[image:onGraphDraw_plotArea.png]]

The y-axis scale goes from <code>roles[GraphingRole='Y axis', GraphFillerInfo='Min']</code> to <code>roles[GraphingRole='Y axis', GraphFillerInfo='Max']</code>. So to annotate a threshold at y=1000, you could use this [[OnGraphDraw]] expression

[[image:OnGraphDraw_afterFullyDrawn.png]]
[[Local]] yThresh := 1000;
[[Local]] (ignore,y) := [[GraphToCanvasCoord]](info,roles,0,yThresh);
[[Local]] x1 := info[OnGraphDrawItem='PlotAreaLeft'];
[[Local]] x2 := info[OnGraphDrawItem='PlotAreaWidth'] + x1;
[[CanvasDrawLine]]( canv, x1,y, x2, y, color:'Green', width:3);
[[CanvasDrawText]](canv, "Threshold", x1, y, color:'Green', vAlign:'Bottom')

[[image:onGraphDraw_threshold.png]]

=== Replacing the plot entirely, but using the same axes ===
A probability bands graph plot is normally draw with lines, such as:
:[[image:OnGraphDraw_OriginalBandsPlot.png|533px]]

By using [[OnGraphDraw]], we can retain the axes and axes scaling, but replace the plot itself with custom-drawn Tukey bars:
:[[image:OnGraphDraw TukeyBands.png|533px]]

In this case, the [[OnGraphDraw]] will be set as follows
:[[image:OnGraphDraw_TukeyBandsCall.png]]
Two key things are happening here. First, it is evaluated after the axes are drawn but before the data is drawn, and second, it sets the local <code>continue</code> to false if it draws the Tukey bars. The pre-existing [[UDF]] <code>Tukey_bars</code> returns true when it draws the bars, false otherwise. The function has a line that checks whether you are viewing the Bands view, so that other uncertainty views continue to render in their default fashion.
<code>
::[[If]] info[OnGraphDrawItem='ViewMode']<>'Bands' [[Then]] ...
</code>
The key is also turned off in graph setup, since the colors shown in the key no longer apply.

=== Clipping to the plot area ===

When you draw to <code>canv</code>, you can draw on any part of the graph. So if you aren't careful, annotations that you expect to draw on the data may extend outside of the plot area (the area bounded by the axes). In some cases this may be what you want, but in other cases you may want to clip to the plot area.

In this example, error bars are draw around the mean value points without any clipping. It does not look natural for these bars to extend outside of the plot area.

'''OnGraphDraw:''' { simplistic version }
[[Local]] spread := SDeviation(Self);
[[Local]] xPt := #roles[GraphingRole='X axis', GraphFillerInfo='Value'];
[[Local]] yPt := #roles[GraphingRole='Y axis', GraphFillerInfo='Value'];
[[Local]] (xUp,yUp) := [[GraphToCanvasCoord]](info,roles,xPt,yPt+spread);
[[Local]] (xDn,yDn) := [[GraphToCanvasCoord]](info,roles,xPt,yPt-spread);
[[CanvasDrawLine]](canv,xUp,yUp,xDn,yDn);
[[CanvasDrawLine]](canv,xUp-4,yUp,xUp+4,yUp);
[[CanvasDrawLine]](canv,xDn-4,yDn,xDn+4,yDn)

:[[image:OnGraphDraw_ErrorBarsNoClip.png]]

To fix this, you can draw to a [[CanvasContext|canvas context]] that has been clipped to the plot area, rather than drawing directly to <code>canv</code>. The above code is modified as follows, where <code>clip</code> is a clipped canvas context:

'''OnGraphDraw:''' { still simplistic, but with clipping }
[[Local]] spread := SDeviation(Self);
[[Local]] xPt := #roles[ [[GraphingRole]]='X axis', [[GraphFillerInfo]]='Value'];
[[Local]] yPt := #roles[ [[GraphingRole]]='Y axis', [[GraphFillerInfo]]='Value'];
[[Local]] (xUp,yUp) := [[GraphToCanvasCoord]](info,roles,xPt,yPt+spread);
[[Local]] (xDn,yDn) := [[GraphToCanvasCoord]](info,roles,xPt,yPt-spread);
<span style="background:yellow">[[Local]] clip := Clip_to_PlotArea(canv, info);</span>
[[CanvasDrawLine]](<span style="background:yellow">clip</span>,xUp,yUp,xDn,yDn);
[[CanvasDrawLine]](<span style="background:yellow">clip</span>,xUp-4,yUp,xUp+4,yUp);
[[CanvasDrawLine]](<span style="background:yellow">clip</span>,xDn-4,yDn,xDn+4,yDn)

:[[image:OnGraphDraw_ErrorBarsWithClip.png]]

where the Clip_to_plotArea is a [[User-Defined Function]] that returns a canvas context clipped to the plot area. It is implemented as follows:

Function <code>Clip_to_plotArea(canv,info) :=
:[[Local]] (x,y,w,h) := _(...info[ [[OnGraphDrawItem]]='PlotArea'&['Left','Top','Width','Height'] ]);
:[[CanvasContext]](canv, clip:x,y,w,h)
</code>

=== Modifying the axis scale ===

The graphing engine selects the axis scale based on the data, and it does not know about stuff that you draw. In same cases you may need to adjust the axis scales so that the range includes your annotations. This section will illustrate one example where this comes up -- when drawing error bars around a point, the range of the error bars around mean-value points extend outside of the range of the plotted mean points. At least when the axis is auto-scaled, you need to extend the min and max data points. Another example occurs when rendering a Google map behind the data. You need to adjust the actual min and max latitude and longitude to the map actually returned by the Google server, even when your axes are manually scaled.

Changes to the scale must occur in the "before drawing" phase, so you need to enable evaluation of [[OnGraphDraw]] before drawing (as well as in the phase when you will actually render your annotations). During the before drawing phase, phase=2, your code needs to make modifications to the local variable <code>roleChanges</code>, which the rendering engine will then use while drawing the axes in the next phase.

The relevant addition for rescaling is highlighted. This part occurs during phase=2, whereas the remaining previous code is not in the else (not phase 2). The key point is that in phase=2, it modifies the min and max to include the extrema of the error bars.

[[image:OnGraphDraw_PhaseBeforeAxes_and_after.png]]
[[Local]] spread := [[SDeviation]](Self);
[[Local]] yRole := roles[ [[GraphingRole]]='Y axis' ];
[[Local]] yPt := #yRole[ [[GraphFillerInfo]]='Value' ];
<span style="background:lightyellow">[[If]] phase = 2 and yRole[ [[GraphFillerInfo]]='Autoscale'] [[Then]] (</span>
<span style="background:lightyellow">roleChanges[ [[GraphingRole]]='Y axis', [[GraphFillerInfo]]='Max' ] := MaxAll(yPt+spread);</span>
<span style="background:lightyellow">roleChanges[ [[GraphingRole]]='Y axis', [[GraphFillerInfo]]='Min' ] := MinAll(yPt-spread);</span>
<span style="background:lightyellow">)</span> Else (
[[Local[[ xPt := #roles[ [[GraphingRole]]='X axis', [[GraphFillerInfo]]='Value' ];
[[Local]] (xUp,yUp) := [[GraphToCanvasCoord]](info,roles,xPt,yPt+spread);
[[Local]] (xDn,yDn) := [[GraphToCanvasCoord]](info,roles,xPt,yPt-spread);
[[Local]] clip := Clip_to_plotArea(canv,info);
[[CanvasDrawLine]](clip,xUp,yUp,xDn,yDn);
[[CanvasDrawLine]](clip,xUp-4,yUp,xUp+4,yUp);
[[CanvasDrawLine]](clip,xDn-4,yDn,xDn+4,yDn)
)
:[[image:OnGraphDraw_ErrorBarsWithAdjustedYScale.png]]

=== Adapting to Swap XY ===

The error bar example so far has a problem when you Swap XY. Can you spot it:
:[[image:OnGraphDraw_ErrorBarsSwapXY_bad.png]]
The problem has to do with the way we draw the caps at the end of each error bar. They are still being drawn horizontally, but now need to be drawn vertically. Here the code that draws one of those ticks:
:<code>[[CanvasDrawLine]](clip,xDn-4,yDn,xDn+4,yDn)</code>
It draws a line from 4 pixels left of the bar end to 4 pixels right of the bar end. When we've swapped XY, we effectively want instead
:<code>[[CanvasDrawLine]](clip,xDn,yDn-4,xDn,yDn+4)</code>

The following addition accomplishes this (unchanged lines not shown):
<code>
:[[Local]] ticW:=4, ticH:=0;
:[[If]] info[ [[OnGraphDrawItem]]='SwapXY'] [[Then]] ( ticW:=0; ticH:=4 );
:...
:[[CanvasDrawLine]](clip,xUp-ticW,yUp-ticH,xUp+ticW,yUp+ticH);
:[[CanvasDrawLine]](clip,xDn-ticW,yDn-ticH,xDn+ticW,yDn+ticH);
</code>
:[[image:OnGraphDraw_ErrorBarsSwapXY.png]]

=== Encapsulating drawing code ===
You may want to show error bars for a different variable. You don't want to repeat all this code every time, and of course, if you later make a bug fix or improvement, you'll want all your plots to inherit that fix. Hence, you should encapsulate this code as a [[User-Defined Function]]. Once you do this, when new variables want error bars, you'll just need to call your UDF from [[OnGraphDraw]] AND you'll need make sure to check the correct check boxes to specify when it is evaluated.

Encapsulating tends to be easy. You're function parameters are whichever of the special local variables (including possibly Self) that your code used. You have some choices about how you want to encapsulate it. For example, do you want your error bar function to only operate from Mean result view? Or do you want to let your caller decide? Do you want to always depict one standard deviation, or do you want your caller to specify the spread?

When your logic changes the <code>continue</code> or the <code>roleChanges</code> variable, then your function will need to return the new value, and the caller needs to set it. In the error bar example, it makes modifications to <code>roleChanges</code>, so this needs to be returned. So the call in [[OnGraphDraw]] will be:

:<code>roleChanges := Plot_error_bars( canv, info, roles, phase, [[SDeviation]](Self) )</code>

When you make changes to both, your function will need to return two return values, and your caller will use:
:<code>(continue, roleChanges) := My_annotation_function(....)</code>

Wrapping it all up, the Plot_error_bars function becomes:
Function Plot_error_bars( canv, info, roles, phase, spread ) :=
[[Local]] yRole := roles[ [[GraphingRole]]='Y axis'];
[[Local]] yPt := #yRole[ [[GraphFillerInfo]]='Value'];
[[Local]] roleChanges := null;
 
[[If]] phase = 2 and yRole[ [[GraphFillerInfo]]='Autoscale' ] [[Then]] (
roleChanges[ [[GraphingRole]]='Y axis', [[GraphFillerInfo]]='Max'] := MaxAll(yPt+spread);
roleChanges[ [[GraphingRole]]='Y axis', [[GraphFillerInfo]]='Min'] := MinAll(yPt-spread);
) else if phase=8 then (
[[Local]] ticW:=4, ticH:=0;
[[If]] info[ [[OnGraphDrawItem]]='SwapXY'] [[Then]] ( ticW:=0; ticH:=4 );
[[Local]] xPt := #roles[ [[GraphingRole]]='X axis', [[GraphFillerInfo]]='Value'];
[[Local]] (xUp,yUp) := [[GraphToCanvasCoord]](info,roles,xPt,yPt+spread);
[[Local]] (xDn,yDn) := [[GraphToCanvasCoord]](info,roles,xPt,yPt-spread);
[[Local]] clip := Clip_to_plotArea(canv,info);
[[CanvasDrawLine]](clip,xUp,yUp,xDn,yDn);
[[CanvasDrawLine]](clip,xUp-ticW,yUp-ticH,xUp+ticW,yUp+ticH);
[[CanvasDrawLine]](clip,xDn-ticW,yDn-ticH,xDn+ticW,yDn+ticH);
);
roleChanges

== See Also ==
* [[Drawing images]]
* [[:Category:OnGraphDraw annotations library functions|OnGraphDraw annotations library]]
** [[Plot_error_bars]]
** <nowiki>[[Plot_point_labels]]</nowiki>
** [[Plot_Tukey_bars]]
** [[Plot_solid_prob_bands]]
** [[Plot_solid_band]]
* [[:Category:Google Maps from OnGraphDraw library functions|Google Maps from OnGraphDraw library]]
** [[OnDraw_Google_map]]
* [[OnGraphDraw/Label Minimum and maximum]] example
* Index of «info»: [[OnGraphDrawItem]]
* Indexes of «roles»: [[GraphingRole]] and [[GraphFillerInfo]]

Tutorial: Open a model to browse

2019-07-26T17:40:53Z

KMullins:

[[Category:Analytica Tutorial]]
[[Category: Rent vs. Buy model]]
<breadcrumbs>Analytica Tutorial > {{PAGENAME}}</breadcrumbs>
{{ReleaseBar}}

This Tutorial page shows you how to open and explore an example Analytica model: The '''Rent vs. Buy model''' compares the total cost of renting a house to the cost of buying one.

You can start by viewing this video, or jump straight into starting up the model in Analytica.

<br>
<center>
<iframe width="640" height="360" src="https://www.youtube.com/embed/GQV0dnDN0Q0" frameborder="0" allowfullscreen></iframe>

'''Video:''' [https://youtu.be/GQV0dnDN0Q0 Tutorial: Open a model to browse] (7 minutes)
</center>
<br>

<div style="column-count:2;-moz-column-count:2;-webkit-column-count:2">
__TOC__
</div>

==Open the Rent vs. Buy model==
To begin, follow these steps.
# You start Analytica like any Windows application: For example, click the '''Start''' button on the Windows taskbar. Click '''All Programs''' → '''Analytica {{#svarget:anarelease|4.6}}''' → '''Analytica {{#svarget:anarelease|4.6}}'''. <br>{{Release||4.6|[[File:Chapter 1.1.png|300px]]}}{{Release|5.0||[[File:Launch Ana5.0 from Start Menu.png|300px]]}}
# After Analytica starts, {{Release||4.6|
select '''File''' → '''Open''' from the menu.
# <br> [[File:Chapter 1.2a.png]]
# Open the Rent vs. Buy model. <br> [[File:Chapter 1.2b.png]] <br> Analytica reads in the Rent vs. Buy model.
}}{{Release|5.0||
select the ''Rent vs. Buy Example'' on the [[Intro screen]].<br />
[[File:Open Buy vs Rent Example.png]]
}}

==The Diagram window==
When you open a model, Analytica first displays a top-level [[Diagram window]]. The ''Rent vs. Buy'' model diagram shows several input variables that affect the trade-offs between renting and buying, '''Normal''' buttons, a '''Calc''' button, and a node labeled Model.

{{CalloutAnnotationBlock|[[image:Chapter 1.3.png]]|
{{CalloutAnnotation|
Normal buttons|Type=Bare|v=130|pt=215,129|path=r-}}
{{CalloutAnnotation|
User input buttons |Type=Bare|v=170|pt=518,175|path=r-}}
{{CalloutAnnotation|
Model node|Type=Bare|v=200|pt=246,210|path=r-}}
{{CalloutAnnotation|
Calc button to see results|Type=Bare|v=268|pt=412,262|path=r-}}
}}

This top-level diagram is an end-user interface to the model itself, which is contained in the Model node. In this chapter, you use only the interface in this top level diagram; in the following chapters you will explore the model in more depth.

Across the top of the screen is a [[toolbar|horizontal palette of buttons]]. This is called the '''''tools palette'''''.

:{{Release||4.6|[[File:Chapter 1.4.png]]}}
{{Release|5.0||
{{CalloutAnnotationBlock|[[image:BrowseToolOnToolbar5.0.png]]|
{{CalloutAnnotation|The browse tool|Type=Bare|v=10|pt=267,33|path=bD20-}}}}
}}

When you first open the ''Rent vs. Buy'' model, the '''browse tool''' is highlighted on the palette. With the browse tool selected, the cursor looks like a hand [[File:Chapter 1.5.png]] when it is over the diagram. The browse tool allows you to calculate the model, change input values, and examine — but not change — the structure of the model. In this chapter, you only use the browse tool.

==Access Help Resources==

At any time, you can press the ''F1'' key on the keyboard or use the '''Help''' menu to access Analytica’s help resources online. This menu includes links to this [[Analytica Tutorial|Tutorial], the [[Analytica User Guide|User Guide]] and much more tips and reference material on this [[Analytica Wiki]].

==Compute output values==

In the ''Rent vs. Buy'' model, the output value of interest is at the bottom, ''Present value of buying and renting''.

{{CalloutAnnotationBlock|[[image:Chapter 1.3.png]]|
{{CalloutAnnotation|
Click the '''Calc''' button to compare the present value of buying and renting.|v=200|pt=413,265|path=bD20-|n=1}}
}}

The output value displays in a [[Result window]]. This '''Result''' window shows a graph of two '''''probability density''''' curves, one for buying and one for renting. In a probability density graph, the units of the vertical scale are chosen so that the total area under each curve is 1 (100%). 25μ corresponds to 25 x 10-6 or 0.000025.

<tip>Numerical suffixes like μ and K are used extensively throughout Analytica. A quick reference for these suffixes is given in [[Number formats]] .</tip>

:[[File:Chapter 1.7.png]]

Since the graph is of probability densities, both buying and renting have probabilistic, or uncertain, inputs. The probability density graph for each appear to be bell-shaped curves ([[normal]] distribution), although they appear a bit “noisy.”

The graphs show that the cost of renting, given the model’s inputs, are between about $105,000 and $155,000 (the negative numbers mean cost — cash flowing out), while the cost of buying is between $115,000 and a gain of $75,000.

{{CalloutAnnotationBlock|[[image:Chapter 1.8.png]]|
{{CalloutAnnotation|
Click the '''Diagram''' window to bring it to the front.|v=20|pt=60,220|path=b!|n=+}}
}}

'''''Note''': Your results can vary slightly, since the model is generating random inputs based on a normal distribution for the uncertainty of the rate of inflation and for the appreciation rate.''

Click the model [[Diagram window]] to bring it to the front. Notice that the button next to ''Costs of buying and renting'' has changed to '''Result'''. The '''Result''' button indicates that the value has been computed; clicking the '''Result''' button re-displays the computed values.

{{CalloutAnnotationBlock|[[image:Chapter 1.9.png]]|
{{CalloutAnnotation|
The '''Calc''' button has changed to '''Result'''.|Type=Bare|v=220|pt=413,265|path=bD20-}}
}}

==Change input values and recompute results==

Now you will change some input values to the model and recompute the rent vs. buy comparison. You will change the values of ''Time horizon'', ''Monthly rent'', and ''Buying price''.

{{CalloutAnnotationBlock|[[image:Chapter 1.9.png]]|
{{CalloutAnnotation|
Click the box next to ''Time horizon''. Change the value to '''''7''''' and press ''Alt+Enter''.|v=50|pt=220,64|path=tU20-|n=1}}
}}

<tip>The main Enter key and the numeric keypad Enter key are not interchangeable. They have different functions in Analytica. Alt+Enter is equivalent to the numeric keypad Enter key.</tip>

As soon as you change an input, the '''Result''' button changes to a '''Calc''' button, indicating that ''Present value of buying and renting'' needs to be recomputed.

{{CalloutAnnotationBlock|[[image:Chapter 1.10.png]]|
{{CalloutAnnotation|
Click the box next to ''Monthly rent''. Change the value to '''''1400''''' and press ''Alt+Enter''.|v=170|pt=220,171|path=r-|n=+}}
}}

{{CalloutAnnotationBlock|[[image:Chapter 1.11.png]]|
{{CalloutAnnotation|
Click the box next to ''Buying price''. Change the value to '''''180K''''' (or 180000) and press ''Alt+Enter''.|v=130|pt=510,65|path=tU100-|n=+}}
}}

Now you are ready to recompute to see the new results.

{{CalloutAnnotationBlock|[[image:Chapter 1.12.png]]|
{{CalloutAnnotation|
Click the '''Calc''' button to compute the comparison of the costs of buying to renting.|v=140|pt=413,265|path=bD20-|n=+}}
}}

The graphs show that the cost of renting, given these changed inputs, is between $90,000 and $120,000, while the cost of buying is between $135,000 and a gain of $70,000.

{{CalloutAnnotationBlock|[[image:Chapter 1.13.png]]|
{{CalloutAnnotation|
Click the '''Diagram''' window to bring it to the front.|v=140|pt=127,386|path=b!|n=+}}
}}

==Examine and change an uncertain input==
When an input is defined as a probability distribution, a button with the name of the distribution appears next to the input’s name. Clicking this button opens the [[Object Finder dialog|Object Finder]] window, in which you can see details and change the distribution’s parameters or type of distribution.

''Rate of inflation''’s button says '''Normal''', indicating that it is defined as a normal distribution.

{{CalloutAnnotationBlock|[[image:Chapter 1.12.png]]|
{{CalloutAnnotation|
Click the '''Normal''' button next to the ''Rate of inflation''.|v=90|pt=218,134|path=bD20-|n=1}}
}}

The [[Object Finder dialog|Object Finder]] window appears. It shows that ''Rate of inflation'' is defined as a normal distribution with a '''''mean''''' of 3.5 and a '''''standard deviation''''' of 1.3.

You will now modify the probability distribution that defines ''Rate of inflation''. Rather than using the normal distribution, you will use the uniform distribution, and assume that inflation has an equal probability of being anywhere between 3% and 4% per year.

{{CalloutAnnotationBlock|[[image:Chapter 1.15.png]]|
{{CalloutAnnotation|
Scroll down the list of distributions and select '''Uniform'''|v=80|pt=0,200|path=b!|n=+}}
}}

{{CalloutAnnotationBlock|[[image:Chapter 1.16.png]]|
{{CalloutAnnotation|
Change the minimum to '''''3'''''.|v=205|pt=222,248|path=r-|n=+}}
{{CalloutAnnotation|
Change the maximum to '''''4'''''.|v=290|pt=330,268|path=tU10/|n=+}}
{{CalloutAnnotation|
Click '''OK''' to accept the change.|v=480|pt=537,481|path=r-|n=+}}
}}

{{CalloutAnnotationBlock|[[image:Chapter 1.17.png]]|
{{CalloutAnnotation|
Click the '''Calc''' button to compute the new comparison of the present value of buying to renting.|v=140|pt=413,265|path=bD20-|n=+}}
}}

:[[File:Chapter 1.18.png]]

The graphs show that the uncertainty in the cost of renting has narrowed to between about $105,000 and $109,000, while the uncertainty in the cost of buying has flattened to between about $125,000 and a gain of $10,000.

==Display alternative uncertainty views==

Analytica offers a variety of views to display uncertain values, including selected statistics, [[Statistical_Functions_and_Importance_Weighting#ProbBands|probability bands]], the [[Uncertainty_Setup_dialog#Probability_density_option|probability density]] function, the [[Uncertainty_Setup_dialog#Cumulative_probability_option|cumulative probability]] distribution function, measures of central tendency, and the table of random numbers from which the uncertain distribution is estimated.

You will now examine several of these views.

In the upper-left corner of the [[Result window]] is the [[Uncertainty view of a result|Uncertainty View]] popup menu.

:[[File:Chapter 1.19.png]]

The miniature probability distribution [[File:Chapter 1.20.png]] indicates that '''''Probability Density''''' is selected.

:[[File:Chapter 1.21.png]]

The [[Result window]] now shows two cumulative probability curves. Along the vertical axis, these curves give the probability that each cost is less than a given value along the horizontal axis.

:[[File:Chapter 1.22.png]]

There appears to be about a 50% probability that the cost to buy is below $70,000, while the cost to rent has a 50% probability of being below about $110,000.

Sometimes you might want to see an uncertain value expressed as a single number — a measure of central tendency. Analytica computes the [[mid]] value (sometimes called the '''''deterministic value''''') by fixing all input probability distributions at their [[median]] (50% probability) values. The mid value is the only uncertainty view available for nonprobabilistic results.

:[[File:Chapter 1.23.png]]

The [[Result window]] now displays bar graphs for the two mid values.

Under the [[Uncertainty view of a result|Uncertainty View]] popup menu are two buttons, [[File:Chapter 1.23.2.png]] and [[File:Chapter 1.23.3.png]]. The [[File:Chapter 1.23.3.png]] is highlighted, indicating that the '''Result''' window is displaying a [[Graph view of a result|graph view]]. The '''Result''' window can also display numeric values in a spreadsheet-like table view.

:[[File:Chapter 1.24.png]]

Analytica also provides the [[mean]] (or average) value.

:[[File:Chapter 1.25.png]]

:[[File:Chapter 1.25.2.png]]

You can also view a set of [[statistics]], including both the [[median]] and [[mean]], the ranges ([[Functions Min and Max|minimum and maximum]]), and the [[Sdeviation|standard deviation]].

:[[File:Chapter 1.26.png]]

The [[Result window]] now displays the minimum, median<ref>Note that the median value is slightly different from the mid value. The mid value is composed of non- probabilistic results generated by using the median value for each input. The median value is calculated using probabilistic inputs and taking the median of the resulting distribution.</ref>, mean, maximum, and standard deviation for ''Costs of buying and renting''.

:[[File:Chapter 1.27.png]]

The statistics might not be exact, because they are estimated from a sample of values from the distribution.

Finally, you see the [[sample]] values.

:[[File:Chapter 1.28.png]]

The table above lists the 100 sample values that Analytica randomly generated from the probability distribution to estimate the [[statistics]].

A [[SampleSize|sample size]] of 100 is adequate for most applications; however, if you need more precise estimates, you can increase the [[SampleSize|sample size]]. See [[Uncertainty Setup dialog]] in the [[Analytica User Guide]].

:[[File:Chapter 1.29.png]]

==Save your model==
If you want to save changes to your model, you can do so at this point. (For instructions on quitting without saving, see the next section.

:[[File:Chapter 1.30.png]]

If you wish to save your model as a different file, so that you do not change the original model, select '''Save As''' from the [[File menu]].

==Quit Analytica==
When you have finished using a model, you might want to quit Analytica.

:[[File:Chapter 1.33.png]]

== Summary ==

You have now opened an Analytica model, calculated and viewed the results, changes input values and probability distributions, and displayed the uncertain results in several ways. These are the basic techniques for using any quantitative model.

After you create your own models, you might want to give them a top-level input and output diagram like the one used in this chapter. For information about customizing a model for end users, see [[Creating Interfaces for End Users]] in the [[Analytica User Guide]].

The next Tutorial page, shows how to navigate the details of the Rent vs. Buy model, exploring its structure and contents.

==Notes==
<references/>

==See Also==
<div style="column-count:2;-moz-column-count:2;-webkit-column-count:2">
* [https://www.analyticacloud.com/acp/Client/AcpClient.aspx?inviteId=3&inviteCode=221703&subName=acp%20demos Play the Rent vs. Buy model in Analytica Cloud Player]
* [https://www.youtube.com/watch?v=GQV0dnDN0Q0 Using the Rent vs. Buy Model] (an explanatory video on YouTube)
* [[Tutorial videos]]
* [[To open or exit a model]]
* [[Create and save a model]]
* [[Tutorial: Create a model]]
* [[Example Models]]
* [[Example Models and Libraries]]
* [[Diagram window]]
* [[Help menu and documentation]]
* [[User input nodes and user output nodes]]
* [[Expressing Uncertainty]]
* [[Uncertainty Setup dialog]]
* [[Uncertainty view of a result]]
</div>

<footer>About Analytica/ {{PAGENAME}} / Tutorial: Reviewing a model</footer>

MultiTable

2019-07-25T23:59:38Z

KMullins: Add link to MultiTable and SubTable tutorial video on YouTube

[[category:User-interface functions]]
[[category:Top level functions]]
[[category:Table functions]]

== MultiTable(i1,i2,...)(src1, src2, ...) ==

A [[MultiTable]] lets you mix editable and computed values in a single table. Editable cells are based on other variables, each defined as a [[Table]] or [[SubTable]]. Computed values are based on calculated variables or expressions. When you change an editable cell, you are actually changing the original cell in the source table, not a copy.

It is best practice in Analytica to keep different editable user inputs and computed results in different variables. But, it is often convenient to define part of a user interface that combines editable and computed values, which the [[MultiTable]] lets you do.

For example, suppose <code>Startup_cost</code> and <code>Prob_success</code> are both edit tables, indexed by <code>Project</code>. Then the a variable defined as:
:<code>Variable Project_inputs := MultiTable(Item)(Startup_cost, Prob_success)</code>

lets you view and edit both Startup_cost and Prob_Success in the same edit table. The [[MultiTable]] is indexed by <code>Project</code>, the index common to both Startup_cost and Prob_success, and by <code>Item</code>, which is an additional index that needs to be created.

[[MultiTable]] is the inverse of [[SubTable]] in that it combines multiple sources into one view, where [[SubTable]] selects a particular slice or subset of data to edit.

== Creating a MultiTable ==

Before you create a [[MultiTable]], you need to create or identify one or more indexes that your data sources will vary over. For example, if you want a different data source to appear in each column of your table, then you'll need a column index, and you'll need to fill in the labels for each column as you define the index.

Next, create a variable to hold your [[MultiTable]] and press ''Ctrl+E'' to place your cursor in the definition field.

:[[image:MT_create1.png]]

In the '''Object Finder''', select the '''Array''' library and scroll down to find and select [[MultiTable]]. Then, press the '''Indexes''' button.

:[[image:MT_create2.png]]

Select the indexes that your [[MultiTable]] data sources will vary along. These are not the indexes of your data sources themselves.

:[[image:MT_create3.png]]

The table initially displays the "Meta expressions" view so that you can specify the data sources for the table. The ''meta-expression selector'' controls which view you are in.

== Specifying Data Sources ==

Whenever you need to specify or change which data source should appear in a [[MultiTable]], use the ''meta-expressions selector'' to change to '''meta-expressions view'''.

Here is an example of meta-expressions.

:[[image:MT_create4.png]]

In the above meta-expressions view, <code>Option_type</code>, <code>Stock_symbol</code>, <code>Strike_price</code> and <code>Expiration_date</code> are identifiers of other edit tables. These will be editable columns. <code>Stock_price_lookup(Stock_Symbol)</code> is a call to a [[User-Defined Function]], and its computed value will appear in this column. The last cell contains <code>Mid(Contract_valuation)</code>, so that the computed mid-value of <code>Contract_valuation</code> will be displayed. When you want the computed value of a variable, you must surround its identifier with [[Mid]] in this fashion, otherwise its definition will appear in the cell and will be editable.

=== Editable sources ===

An editable source reflects the contents of another edit table in your model, a [[slice]] of an edit table, or the [[definition]] of another variable. When a user edits these cells in the multitable, they are actually changing the data in the specified source definition or table. In meta-expression view, an editable source is specified in one of the following ways.
* <code>X</code> : An identifier. The definition of <code>X</code>, or the [[Table|edit table]] (or [[SubTable]] or [[MultiTable]] of <code>X</code>) is depicted.
* <code>X[I=v]</code> : A [[Slice]] or [[Subscript]] of another table. That slice is depicted in an editable form.

The source can be a scalar variable, an [[Table|edit table]], a [[SubTable]] or another [[MultiTable]]. Rather arbitrary transformations that be accomplished by nesting SubTables and MultiTables.

=== Computed sources ===

The following are computed expressions, which are evaluated and the resulting value displayed in a non-editable form with a gray background.
* <code>31.4</code>, <code>"Text"</code>: Literal values (numbers, quoted text)
* <code>Mid(X)</code>: Displays the computed mid-value of the variable <code>X</code>
* <code>F(...)</code>: Any function call other than [[Slice]] or [[Subscript]], including calls to [[User-Defined Function]]s, are evaluated.
* <code>x + y</code> : An expression, such as one involving arithmetic operations, is evaluated.

Here are a few additional examples:

* <code>Mid(X)</code> : ''computes and displays the [[mid]]-value of <code>X</code>''
* <code>Abs(X)</code> : ''displays the [[Abs|absolute value]] of the (mid-value) of <code>X</code>''
* <code>Mean(X)</code> : ''computes and displays the [[mean]] of <code>X</code>''
* <code>1.2</code> : ''displays the number, 1.2, in a non-editable cell''
* <code>"Some text"</code> : ''displays the text, without quotes, in a non-editable cell

A computed expression or computed variable CAN depend on the values of other data sources that appear in the same [[MultiTable]]. When you do this, the computed value will change when the user changes the input cells and presses the green check button.

== Viewing the Data ==

After you have specified the data sources in meta-expression view, change the '''meta-expression selector''' to '''Show Cells''' to see the actual data.

:[[image:MT_create5.png]]

=== When cells can be edited ===

You can never edit computed values in a [[MultiTable]]

In [[Browse mode]], you can edit data in a variable only if the variable has a [[user input node]]. This means that if your [[MultiTable]] variable has a user input node, users in [[Browse mode]] (including [[Analytica Cloud Player]] or [[Free Edition|Analytica Free 101]]) can edit all table sources. Otherwise, if one source has a user input node and another does not, users in [[Browse mode]] can edit only those cells from the source(s) with the user in.

== Examples ==

Here is an example of an editable value and computed value in the same table:

<pre style="background:white; border:white; margin-left: 1em;">
Index Base := ["Decimal", "Hex"]
Variable x := 123
Variable HexConverter := MultiTable(Base)(x, NumberToText(x, "Hexadecimal"))
</pre>

The edit table displays like this:

:[[image:HexConverter.png]]

The first cell can be edited, and when you change it and press the green check, the [[Binary and hexadecimal integer formats|hexadecimal]] value is computed and displayed.

== Dimensionality ==

The dimensions of the [[MultiTable]] content are the union of the indexes from all sources and of the [[MultiTable]] index(es).

A [[MultiTable]] works best when your sources all have the same dimensionality. When one source does not have an index present in another source, a single cell in the source will map to multiple cells in the [[MultiTable]]; hence, you'll see the same value multiple places, and when you change it, multiple cells will change. The source retains its original dimensionality, so if the value doesn't vary along an index in the source, it won't vary along that index is the [[MultiTable]]. You may temporarily see a difference in these cells after you first enter a value, but they will become consistent as soon as you press the Green check.

== Number Formats ==

When number formats are set for the source tables, those formats are used in the corresponding column of the MultiTable.

When a meta-expression is of the form <code>Mid(X)</code>, then <code>X</code>'s number format is used. For arbitrary expressions, the number format of the [[MultiTable]]'s own variable is used.

==History==
Introduced in [[Analytica 4.6]]. Present in experimental form in [[Analytica 4.5]].

== See Also ==
* MultiTable and SubTable [https://www.youtube.com/watch?v=q2zqbgsPPBk video tutorial]
* [[Tutorial: Arrays]]
* [[Arrays and Indexes]]
* [[SubTable]]
* [[Table]]
* [[Mid]], [[Mean]], [[Sample]] -- used for specifying computed results.
* [[Subscript]], [[Slice]], [[Subscript/Slice Operator]]
* [[Objects and Values]]

EvaluateScript

2019-06-22T00:27:48Z

KMullins: typo

[[category:Evaluation Functions]]
[[Category: Typescript Commands]]
[[Category:Doc Status C]] 

== EvaluateScript(typescript) ==

Evaluates a [[typescript]] command. Returns the typescript output as a string.

<tip title="Warning"> There are some dangerous aspects to this function. It is not a function most users will want to make use of. However, because it provides access to typescript from expressions, it does open up some doors, making something things possible that would not otherwise be. But, if you use [[EvaluateScript]], Analytica does not prevent you from "shooting yourself in the foot".
</tip>

Despite the warning, there are many legitimate uses.

== Example ==

The following creates a list of all keywords in Analytica:
:<code>Index kw:= Split(EvaluateScript("Command List|list]] keyword")," ");</code>
:<code>subset(kw<>"")</code>

== Error Handling ==

When an error occurs while processing the typescript, the error message is returned in the text of the result. In Analytica 4.2 and later, the optional «showErr» parameter can be specified as true to halt execution and display the error:

:<code>EvaluateScript("show nothing") → "Syntax error at line 1: Undefined name."</code>
:<code>EvaluateScript("show nothing", showError: true) → { Evaluation stops, error dialog appears }</code>

When «showError» is true, the error can also be caught using the [[Try]](..) function. ([[Analytica 4.6]] or later).

== Dangers ==

[[EvaluateScript]] makes it possible to go around Analytica's referential transparency rule that prohibits side-effects while a variable is being evaluated. If you choose to do so, you do so at your own risk. In particular, unpredictable things may occur, including the potential for a crash, or for incorrect computations, if you alter something that a pending computation depends on. For example, if <code>X</code> is in the process of being computed, and <code>A</code> is upstream from <code>X</code>. If you use [[EvaluateScript]] to change <code>A</code>, which you might do from some variable far removed from <code>X</code>, the computation of <code>X</code> may experience serious problems. Since it is in the process of being evaluated, it may have already computed intermediate results that are no longer valid given the change in <code>A</code>. It won't know this, and will plow ahead with the remainder of the computation, possibly producing a nonsense answer, and possibly even crashing.

One situation that is particularly nefarious is the case where a [[Dynamic]] evaluation is in progress. A dynamic evaluation bases its computation of the model's global loop structure. Previously computed information on the model's loop structure is invalidated when a definition in the model changes. Hence, you should never use [[EvaluateScript]] to alter a variable's definition if there is a possibility that a variable in a dynamic loop is in the process of being evaluated. This case if extremely hard to debug to figure out what is happening, and the symptom may simply be that numeric results aren't correct.

Another mistake to avoid is assigning to [[RandomSeed]] while a variable evaluation is in-progress, since this causes all uncertain quantities to be invalidated. You can assign to [[RandomSeed]] using the [[Assignment Operator :=]], even when a computation is in progress, so if you want a "deterministic pseudo-random sample" use assignment, not [[EvaluateScript]], e.g., from an expression, <code>[[RandomSeed]]:=5; [[Uniform]](0,1)</code>.

With [[EvaluateScript]], you are given the ability to shoot yourself in the foot, but in rare cases, the fact that it is not limited can make it possible to work around core limitations.

In general, side-effects created by [[EvaluateScript]] are not particularly dangerous from [[UDF]]s called from button scripts, [[OnClick]] or [[OnChange]] handlers.

== See Also ==

* [[:Category:Typescript Commands|Typescript Commands]]
* [[Command List]]
* [[Evaluate]]
* [[Attrib of Obj]]
* [[Try]]
* [[OnClick]]
* [[OnChange]]

Plot solid prob band

2019-04-08T22:02:30Z

KMullins: Added example image

''New to [[Analytica 5.2]]''

Use this function from [[OnGraphDraw]] to plot a filled color band between symmetric percentiles in a probability bands result view.

== Plot_solid_prob_band( canv, info, roles ) ==
Fills in a solid band behind a probability bands view. To be used from the OnGraphDraw attribute. Usage:

# Set "Evaluate before drawing" AND "Evaluate after axes, before data" in [[OnGraphDraw]]
# Set the [[OnGraphDraw]] expression to: <code> [[Plot_solid_prob_band]]( canv, info, roles ) </code>
# Select the bands view for your result.
# Make sure you have Key=.Probability for the pivot.

Below is an example of how this function can be used. One additional step is to [[Customization of Graph Colors|change the colors]] for the Probability index so that the 5th and 95th percentile values and the 25th and 75th values are the same.

:[[File:Plot_solid_prob_band_example.png]]

== See Also ==
* [[OnGraphDraw]]
* [[Plot_solid_band]]
* [[Plot_Tukey_bars]]
* [[Plot_error_bars]]

File:Plot solid prob band example.png

2019-04-08T21:56:09Z

KMullins: Example of function use, using the car cost demo model

Example of function use, using the car cost demo model

Plot solid prob band

2019-04-08T21:17:59Z

KMullins: Changed to ordered list so people see usage notes as a list of steps (so they're less likely to just look at the definition, which I just did...)

''New to [[Analytica 5.2]]''

Use this function from [[OnGraphDraw]] to plot a filled color band between symmetric percentiles in a probability bands result view.

== Plot_solid_prob_band( canv, info, roles ) ==
Fills in a solid band behind a probability bands view. To be used from the OnGraphDraw attribute. Usage:

# Set "Evaluate before drawing" AND "Evaluate after axes, before data" in [[OnGraphDraw]]
# Set the [[OnGraphDraw]] expression to: <code> [[Plot_solid_prob_band]]( canv, info, roles ) </code>
# Select the bands view for your result.
# Make sure you have Color=.Probability for the pivot.

== See Also ==
* [[OnGraphDraw]]
* [[Plot_solid_band]]
* [[Plot_Tukey_bars]]
* [[Plot_error_bars]]

File:Time-series-reindexing.ana

2019-03-28T17:43:37Z

KMullins: KMullins uploaded a new version of File:Time-series-reindexing.ana

An example model demonstrating some simple stuff.

File:Weekly data graph ex.png

2019-03-28T17:41:37Z

KMullins: KMullins uploaded a new version of File:Weekly data graph ex.png

Graph from an example model

Data Sets

2019-03-14T17:46:55Z

KMullins:

You may find these sample data set modules useful as you explore what Analytica can do, and as inspiration or a starting point for your own models. They can be added to a model in [[Editions of Analytica|any edition]] of Analytica, and cover a wide variety of topic areas. For instructions on how to add a data module to your model, see [[Import a module or library]].

You can are also invited to contribute your own well organized and complete data sets as sources for the Analytica community to use. For how to do that, see [[Uploading Example Models]].

__TOC__

== Time Series ==

=== Oil Price ===

Monthly oil price data from 1987 to 2018. Includes Brent and WTI prices.

'''Download:''' [[media:Oil prices module.ana|Oil price module]]

=== PM2.5 Concentration in Beijing ===

Hourly PM2.5 from the US Embassy in Beijing, China with relvant hourly meteorological data. The data cover 2010 through 2014. Available at: [http://archive.ics.uci.edu/ml/datasets/Beijing+PM2.5+Data UCI Machine Learning Repository].

Citation: Liang, X., Zou, T., Guo, B., Li, S., Zhang, H., Zhang, S., Huang, H. and Chen, S. X. (2015). Assessing Beijing's PM2.5 pollution: severity, weather impact, APEC and winter heating. ''Proceedings of the Royal Society A'', 471, 20150257.

'''Download:''' [[media:Beijing air quality data.ana|Beijing air quality module]]

== Econometric ==

=== Wages ===

Cross-sectional data set surrounding wages from 1976 for 526 workers. Variables cover demographics, industry, and geography. Taken from "Introductory Econometrics: A Modern Approach, 6e" by Jeffrey M. Wooldridge, via https://rdrr.io/cran/wooldridge/f/

'''Download:''' [[media:WAGE1.ana|Wage data module]]

Data Sets

2019-03-14T17:46:00Z

KMullins:

You may find these sample data set modules useful as you explore what Analytica can do, and as inspiration or a starting point for your own models. They can be added to a model in [[Editions of Analytica|any edition]] of Analytica, and cover a wide variety of topic areas. For instructions on how to add a data module to your model, see [[Import a module or library]].

You can are also invited to contribute your own well organized and complete data sets as sources for the Analytica community to use. For how to do that, see [[Uploading Example Models]].

__TOC__

== Time Series ==

=== Oil Price ===

Monthly oil price data from 1987 to 2018. Includes Brent and WTI prices.

'''Download:''' [[media:Oil prices module.ana|Oil price module]]

=== PM2.5 Concentration in Beijing ===

Hourly PM2.5 from the US Embassy in Beijing, China with relvant hourly meteorological data. The data cover 2010 through 2014.

Citation: Liang, X., Zou, T., Guo, B., Li, S., Zhang, H., Zhang, S., Huang, H. and Chen, S. X. (2015). Assessing Beijing's PM2.5 pollution: severity, weather impact, APEC and winter heating. ''Proceedings of the Royal Society A'', 471, 20150257.

Available at: [http://archive.ics.uci.edu/ml/datasets/Beijing+PM2.5+Data UCI Machine Learning Repository].

'''Download:''' [[media:Beijing air quality data.ana|Beijing air quality module]]

== Econometric ==

=== Wages ===

Cross-sectional data set surrounding wages from 1976 for 526 workers. Variables cover demographics, industry, and geography. Taken from "Introductory Econometrics: A Modern Approach, 6e" by Jeffrey M. Wooldridge, via https://rdrr.io/cran/wooldridge/f/

'''Download:''' [[media:WAGE1.ana|Wage data module]]

Data Sets

2019-03-14T16:43:07Z

KMullins:

You may find these sample data set modules useful as you explore what Analytica can do, and as inspiration or a starting point for your own models. They can be added to a model in [[Editions of Analytica|any edition]] of Analytica, and cover a wide variety of topic areas. For instructions on how to add a data module to your model, see [[Import a module or library]].

You can are also invited to contribute your own well organized and complete data sets as sources for the Analytica community to use. For how to do that, see [[Uploading Example Models]].

__TOC__

== Time Series ==

=== Oil Price ===

Monthly oil price data from 1987 to 2018. Includes Brent and WTI prices.

'''Download:''' [[media:Oil prices module.ana|Oil price module]]

=== PM 2.5 Concentration in Beijing ===

Hourly PM2.5 from the US Embassy in Beijing, China with relvant hourly meteorological data. The data cover 2010 through 2014.

Citation: Liang, X., Zou, T., Guo, B., Li, S., Zhang, H., Zhang, S., Huang, H. and Chen, S. X. (2015). Assessing Beijing's PM2.5 pollution: severity, weather impact, APEC and winter heating. ''Proceedings of the Royal Society A'', 471, 20150257.

Available at: [http://archive.ics.uci.edu/ml/datasets/Beijing+PM2.5+Data UCI Machine Learning Repository].

'''Download:''' [[media:Beijing air quality data.ana|Beijing air quality module]]

== Econometric ==

=== Wages ===

Cross-sectional data set surrounding wages from 1976 for 526 workers. Variables cover demographics, industry, and geography. Taken from "Introductory Econometrics: A Modern Approach, 6e" by Jeffrey M. Wooldridge, via https://rdrr.io/cran/wooldridge/f/

'''Download:''' [[media:WAGE1.ana|Wage data module]]

Data Sets

2019-03-14T16:42:18Z

KMullins: Added data module

You may find these sample data set modules useful as you explore what Analytica can do, and as inspiration or a starting point for your own models. They can be added to a model in [[Editions of Analytica|any edition]] of Analytica, and cover a wide variety of topic areas. For instructions on how to add a data module to your model, see [[Import a module or library]].

You can are also invited to contribute your own well organized and complete data sets as sources for the Analytica community to use. For how to do that, see [[Uploading Example Models]].

__TOC__

== Time Series ==

=== Oil Price ===

Monthly oil price data from 1987 to 2018. Includes Brent and WTI prices.

'''Download:''' [[media:Oil prices module.ana|Oil price module]]

=== PM 2.5 Concentration in Beijing ===

Hourly PM2.5 from the US Embassy in Beijing, China with relvant hourly meteorological data. The data cover 2010 through 2014.

Citation: Liang, X., Zou, T., Guo, B., Li, S., Zhang, H., Zhang, S., Huang, H. and Chen, S. X. (2015). Assessing Beijing's PM2.5 pollution: severity, weather impact, APEC and winter heating. Proceedings of the Royal Society A, 471, 20150257.

Available at: [http://archive.ics.uci.edu/ml/datasets/Beijing+PM2.5+Data UCI Machine Learning Repository].

'''Download:''' [[media:Beijing air quality data.ana|Beijing air quality module]]

== Econometric ==

=== Wages ===

Cross-sectional data set surrounding wages from 1976 for 526 workers. Variables cover demographics, industry, and geography. Taken from "Introductory Econometrics: A Modern Approach, 6e" by Jeffrey M. Wooldridge, via https://rdrr.io/cran/wooldridge/f/

'''Download:''' [[media:WAGE1.ana|Wage data module]]

File:Beijing air quality data.ana

2019-03-14T16:40:32Z

KMullins: Hourly PM2.5 from the US Embassy in Beijing, China with relvant hourly meteorological data. The data cover 2010 through 2014. Citation: Liang, X., Zou, T., Guo, B., Li, S., Zhang, H., Zhang, S., Huang, H. and Chen, S. X. (2015). Assessing Beijing's PM...

Hourly PM2.5 from the US Embassy in Beijing, China with relvant hourly meteorological data. The data cover 2010 through 2014.

Citation: Liang, X., Zou, T., Guo, B., Li, S., Zhang, H., Zhang, S., Huang, H. and Chen, S. X. (2015). Assessing Beijing's PM2.5 pollution: severity, weather impact, APEC and winter heating. Proceedings of the Royal Society A, 471, 20150257.

Available at: http://archive.ics.uci.edu/ml/datasets/Beijing+PM2.5+Data

Data Sets

2019-03-14T00:49:20Z

KMullins:

You may find these sample data set modules useful as you explore what Analytica can do, and as inspiration or a starting point for your own models. They can be added to a model in [[Editions of Analytica|any edition]] of Analytica, and cover a wide variety of topic areas. For instructions on how to add a data module to your model, see [[Import a module or library]].

You can are also invited to contribute your own well organized and complete data sets as sources for the Analytica community to use. For how to do that, see [[Uploading Example Models]].

__TOC__

== Time Series ==

=== Oil Price ===

Monthly oil price data from 1987 to 2018. Includes Brent and WTI prices.

'''Download:''' [[media:Oil prices module.ana|Oil price module]]

=== PM 2.5 Concentration in Beijing ===

Multivariate air quality data from Beijing (PM 2.5) from 2010 to 2014. Data provided by [http://archive.ics.uci.edu/ml/datasets/Beijing+PM2.5+Data UCI Machine Learning Repository].

== Econometric ==

=== Wages ===

Cross-sectional data set surrounding wages from 1976 for 526 workers. Variables cover demographics, industry, and geography. Taken from "Introductory Econometrics: A Modern Approach, 6e" by Jeffrey M. Wooldridge, via https://rdrr.io/cran/wooldridge/f/

'''Download:''' [[media:WAGE1.ana|Wage data module]]

File:WAGE1.ana

2019-03-14T00:35:25Z

KMullins: KMullins uploaded a new version of File:WAGE1.ana

Cross-sectional data set from 1976 for 526 workers. Taken from "Introductory Econometrics: A Modern Approach, 6e" by Jeffrey M. Wooldridge, via https://rdrr.io/cran/wooldridge/f/

Data Sets

2019-03-13T17:46:43Z

KMullins: Added oil price data

File:Oil prices module.ana

2019-03-13T17:45:11Z

KMullins: Monthly oil price data from 1987 to 2018. Includes Brent and WTI prices.

Monthly oil price data from 1987 to 2018. Includes Brent and WTI prices.

Data Sets

2019-03-08T00:13:15Z

KMullins:

File:WAGE1.ana

2019-03-08T00:06:59Z

KMullins: Cross-sectional data set from 1976 for 526 workers. Taken from "Introductory Econometrics: A Modern Approach, 6e" by Jeffrey M. Wooldridge, via https://rdrr.io/cran/wooldridge/f/

Cross-sectional data set from 1976 for 526 workers. Taken from "Introductory Econometrics: A Modern Approach, 6e" by Jeffrey M. Wooldridge, via https://rdrr.io/cran/wooldridge/f/

Data Sets

2019-03-07T23:37:23Z

KMullins: Created page with "You may find these sample data set modules useful as you explore what Analytica can do, and as inspiration or a starting point for your own models. They can be added to a mode..."

Example Models

2019-03-07T23:32:14Z

KMullins:

[[Category: Models]]
[[Category: Examples]]
[[category:Doc Status D]]

You may find these example Analytica models useful to see what Analytica can do, and as inspiration or a starting point for your own models. They cover a wide variety of topics and techniques.

These examples supplement the example models that are [[Example Models and Libraries |installed with Analytica]] into the Examples folder.

You can are also invited to contribute your own models as examples. For how to do that, see [[Uploading Example Models]].

__TOC__

==Business Examples==

=== Marginal Abatement Graph ===

:[[image:Marginal abatement heating energy.png]]

This model, along with [http://blog.lumina.com/2015/marginal-abatement/ the accompanying blog article], show how to set up a Marginal Abatement graph in Analytica.

'''Keywords''': Graph methods, carbon price, energy efficiency, climate policy, optimal allocation, budget constraint.

'''Author:''' Lonnie Chrisman

'''Download:''' [[media:Marginal abatement home heating.ana|Marginal abatement home heating.ana]]

=== Solar Panel Analysis ===

:[[image:Solar Panel Analysis.png]]

'''Description:''' Would it be cost effective to install solar panels on the roof of my house? This model explores this question for my situation in San Jose, California. [https://www.youtube.com/watch?v=vhSor_fPIsI An accompanying video] documents the building of this model, and is a good example of the process one goes through when building any decision model.

The model explores how many panels I should install, and what the payoff is in terms of [[NPV|net present value]], [[IRR|Internal rate of return]] and time to recoup cost. It also looks at whether I should postpone the start of the installation to take advantage of rapidly falling PV prices, or cash in on tax credits.

'''Keywords''': Renewable energy, photovoltaics, net present value, internal rate of return, tax credits, agile modeling.

'''Author:''' Lonnie Chrisman

'''Download:''' [[media:Solar Panel Analysis.ana|Solar Panel Analysis.ana]]

=== Items within Budget function ===

'''Description:''' Given a set of items, with a priority and a cost for each, the function Items_within_budget function selects out the highest priority items that fit within the fixed budget.

'''Keywords:'''

'''Author:''' Max Henrion

'''Download''': [[Media:Items_within_budget.ana|Items within budget.ana]]

=== Grant Exclusion Model ===

'''Description:''' This model tests a hypothesis about the distribution of an attribute of the marginal rejectee of a grant program, given the relevance of that attribute to award of the grant. It could be used by an organization to make decisions as to whether to fiscally-sponsor another organization that will use that fiscal sponsorship to apply for grants, by looking at the effect on the pool of grant recipients overall.

'''Keywords:''' Business analysis

'''Download''': [[Media:Grant_exclusion.ANA|Grant exclusion.ana]]

=== Project Planner ===

:[[Image: Project planner model.png |500px]]

'''Description:''' This is a demo model that shows how to:
* Evaluate a set of R&D projects, including uncertain R&D costs, and uncertain revenues if it leads to release of a commercial product.
* Use multiattribute analysis to compare projects, including a hard attribute -- expected net present value -- and soft attributes -- strategic fit, staff development, and public good will.
* Compare cost, [[NPV]], and multiattribute value for a selected portfolio of projects.
* Generate the best portfolio (ratio of NPV or multiattribute merit to cost) given a R&D budget.

The model linked here is only a test, and to an older version: [[File:Project_priorities_2007_4.0.ANA]]

'''Keywords:''' Business models, cost analysis, net present value (NPV), uncertainty analysis

'''Download:''' [[Media:Project Priorities 5 0.ana|Project Priorities 5 0.ana]]

=== Steel and Aluminum import tariff impact on US trade deficit ===

<center>[[Image:Steel and aluminum tariff model diagram.png|400px]]</center>

'''Description:''' On 2-March-2018, President Trump proposed new import tariffs on steel and aluminum. It seems as if the projected net impacts of these tariffs on the total US trade deficit and US economy depends largely on which news outlets you get your news from. We thought it would be helpful to put together a simple and easy to understand model to estimate of the net impact of these tariffs on the US trade deficit, assuming that no other factors change (e.g., no retaliatory tariffs are enacted by other countries). We wanted something that allows you to understand how its estimates are being derived, with assumptions that can be easily replaced with your own, so that the model itself would be impartial to any particular viewpoint. We want the uncertainties that are inherent in such a simple model to be explicit, so you can see the range of possibilities and not just a single guess. Finally, we wanted the model to be easy to understand fully for non-economists (a group to which we belong, too).

This model accompanied a current event blog post on the Lumina blog: [http://lumina.com/blog/impact-of-trumps-proposed-steel-aluminum-tariffs-on-us-trade-deficit Impact of Trump’s proposed Steel & Aluminum tariffs on US trade deficit]

'''Authors:''' Kimberley Mullins and Lonnie Chrisman, Lumina Decision Systems

'''Download:''' [[Media:Steel and aluminum tariff model.ana|Steel and aluminum tariff model.ana]]

=== Tax bracket interpolation ===

<center>[[Image:Tax bracket interpolation.png]]</center>

'''Description:''' Computes amount of tax due from taxable income for a 2017 US Federal tax return. To match the IRS's numbers exactly, it is necessary to process tax brackets correctly as well as implementation a complex mix of rounding rules that reproduce the 12 pages of table lookups from the Form 1040 instructions. This model is showcased in a blog article, [http://Lumina.com/blog/how-to-simplify-the-irs-tax-tables How to simplify the IRS Tax Tables].

'''Author:''' Lonnie Chrisman, Lumina Decision Systems

'''Download:''' [[Media: Tax bracket interpolation.ana|Tax bracket interpolation.ana]]

==Data Analysis==

=== Sampling from only feasible points ===

'''Description:''' You have a bunch of chance variables, each with a probability distribution. Their joint sample, however, contains some combinations of points that are (for one reason or another) physically impossible. We'll call those infeasible points. You'd like to eliminate those points from the sample and keep only the feasible points.

This module implements a button that will sample a collection of chance variables, then reset the sample size and keep only those sample points that are "feasible".

Obviously, this approach will work best when most of your samples are feasible. If you can handle the "infeasible" points in your model directly, by conditioning certain chance variables on others, that is far preferable. But there are some cases where this solution (although a bit of a kludge) is more convenient.

The instructions for how to use this are in the module description field.

'''Keywords''': Statistics, sampling, Importance sampling, feasibility, Monte Carlo simulation

'''Author:''' Lonnie Chrisman

'''Download''': [[Media:Feasible_Sampler.ana|Feasible Sampler.ana]]

=== Cross-Validation / Fitting Kernel Functions to Data ===

:[[image:Cross-validated data fit.jpg]]

'''Description:''' When fitting a function to data, if you have too many free parameters relative to the number of points in your data set, you may "overfit" the data. When this happens, the fit to your training data may be very good, but the fit to new data points (beyond those used for training) may be very poor.

Cross-validation is a common technique to deal with this problem: We set aside a fraction of the available data as a cross-validation set. Then we begin by fitting very simple functions to the data (with few free parameters), successively increasing the number of free parameters, and seeing how the predictive performance changes on the cross-validation set. It is typical to see improvement on the cross-validation set for a while, followed by a deterioration of predictive performance on the cross-validation set once overfitting starts occurring.

This example model successively fits a non-linear kernel function to the residual error, and uses cross-validation to determine how many kernel functions should be used.

Requires Analytica Optimizer: The kernel fitting function (Kern_Fit) uses [[NlpDefine]].

'''Keywords:''' Cross-validation, overfitting, non-linear kernel functions

'''Author:''' Lonnie Chrisman

'''Download:''' [[media:Cross-validation example.ana|Cross-validation example.ana]]

=== Statistical Bootstrapping ===

'''Description:''' Bootstrapping is a technique from statistics for estimating the sampling error present in a statistical estimator. The simplest version estimates sampling error by resampling the original data. This model demonstrates how to do this in Analytica.

'''Keywords:''' Bootstrapping, sampling error, re-sampling

'''Download:''' [[media:Bootstrapping.ana|Bootstrapping.ana]]

=== Smooth PDF plots using Kernel Density Estimation ===

:{| border="0"
| [[image:Dens_Est_builtin_pdf.png|frame|Analytica's built-in PDF plot with default settings]]
|
[[image:Dens_Est_Kernel_pdf.png|frame|PDF computed from Kernel Density estimation]]
|}

'''Description:''' This example demonstrates a very simple fixed-width kernel density estimator to estimate a "smooth" probability density. The built-in PDF function in Analytica often has a choppy appearance due to the nature of histogramming -- it sets up a set of bins and counts how many points land in each bin. A kernel density estimator smooths this out, producing a less choppy PDF plot.

This smoothing is built into [[Analytica 4.4]]. You can select [[Kernel Density Smoothing|smoothing]] from the [[Uncertainty Setup dialog]].

'''Keywords:''' Kernel density estimation, kernel density smoothing

'''Author:''' D. Rice, Lumina Decision Systems

'''Download:''' [[media:Kernel_Density_Estimation.ana|Kernel Density Estimation.ana]]

=== Output and Input Columns in Same Table ===

:[[image:Output and input columns.png]]

'''Description:''' Presents an input table to a user, where one column is populated with computed output data, the other column with checkboxes for the user to select. Although the '''Output Data''' column isn't read only, as would be desired, a [[Check Attribute]] has been configured to complain if he does try to change values in that column. The model that uses these inputs would ignore any changes he makes to data in the '''Output Data''' column.

Populating the '''Output Data''' column requires the user to press a button, which runs a button script to populate that column. This button is presented on the top-level panel. If you change the input value, the output data will change, and then the button needs to be pressed to refresh the output data column.

'''Keywords:''' Data analysis

'''Author:''' D. Rice, Lumina Decision Systems

'''Download:''' [[media:Output and input columns.ana|Output and input columns.ana]]

==Decision Analysis==

=== From Controversy to Consensus: California's offshore oil platforms ===

<center>[[image:oilplatform_1.jpg|300px]]</center>

'''Description:''' Too many environmental issues cause bitter public controversy. The question of how to decommission California's 27 offshore oil platforms started out as a typical example. But remarkably, after careful analysis a single option, "[http://lumina.com/case-studies/energy-and-power/a-win-win-solution-for-californias-offshore-oil-rigs rigs to reefs]", obtained the support of almost all stakeholders, including oil companies and environmentalists. A law to enable this option was passed by the California State house almost unanimously, and signed by Governor Arnold Schwarzenegger.

'''Keywords:''' decision analysis, multi-attribute, offshore platforms, oil and gas, stakeholders, rigs to reefs, decision support, sensitivity analysis

'''Author:''' Max Henrion, Lumina Decision Systems

'''Download:''' [[media:Platform 2018b.ana|Platform2018b.ana]].

=== Retirement plan type comparison ===

<center>[[image:Comparing retirement account types.png|500px]]</center>

'''Description:''' Will you end up with a bigger nest egg at retirement with a 401(k), traditional IRA, Roth IRA or a normal non-tax-advantaged brokerage account? For example, comparing a Roth IRA to a normal brokerage, intermediate capital gains compound in the Roth, but eventually you pay taxes on those gains at your income tax rate at retirement, whereas in the brokerage you pay capital gains taxes on the gains, which is likely a lower tax rate. So does the compounding outweigh the tax rate difference? What effect do the higher account maintenance fees in a 401(k) account have? How sensitive are these conclusions to the various input estimates? The answers to all these questions depend on your own situation, and may different for someone else. Explore these questions with this model.

'''Keywords:''' 401(k), IRA, retirement account, decision analysis, uncertainty, sensitivity analysis, [[MultiTable]]s.

'''Author:''' Lonnie Chrisman, Lumina Decision Systems

'''Download:''' [[media:Comparing retirement account types.ana|Comparing retirement account types.ana]].
::For a version without the sensitivity analysis part, which has fewer than 100 objects and can thus be modified using [http://lumina.com/products/free101/ Analytica Free 101], you can use this one: [[media:Comparing retirement account types without sensitivity.ana|Comparing retirement account types without sensitivity.ana]].

=== Plane Catching Decision with Expected Value of Including Uncertainty ===

'''Description:''' A simple model to assess what time I should leave my home to catch a plane, with uncertain driving time, walking from parking to gate (including security), and how long I need to be at the gate ahead of scheduled departure time. It uses a loss model based on minutes, assuming I value each extra minute snoozing in bed and set the loss if I miss the plane to 400 of those minutes.

It illustrates the EVIU (expected value of including uncertainty) i.e. the difference in expected value if I make a decision to minimize expected loss instead of decision to minimize time ignoring uncertainty (assuming each distribution is fixed at its mid value). For more details see "The Value of Knowing How Little You Know", Max Henrion, PhD Dissertation, Carnegie Mellon University, 1982.

'''Keywords''': Decision theory, decision analysis, uncertainty, Monte Carlo simulation, value of information, EVPI, EVIU.

'''Author:''' Max Henrion

'''Download:''' [[media:Plane catching decision with EVIU.ana|Plane catching decision with EVIU.ana]]

=== Marginal Analysis for Control of SO<sub>2</sub> emissions ===

'''Description:''' Acid rain in eastern US and Canada caused by sulfur dioxide is emitted primarily by coal-burning electric-generating plants in the Midwestern U.S. This model demonstrates a marginal analysis a.k.a. benefit/cost analysis to determine the policy alternative that leads us to the most economically efficient level of cleanup.

'''Keywords:''' Environmental engineering, cost-benefit analysis, marginal analysis

'''Author:''' Surya Swamy

'''Download:''' [[media:Marginal Analysis for Control of SO2 Emissions.ana|Marginal Analysis for Control of SO2 Emissions.ana]]

==Dynamic Models==

=== Donor/Presenter Dashboard ===

'''Description:''' This model implements a continuous-time Markov chain in Analytica's discrete-time dynamic simulation environment. It supports immigration to, and emigration from, every node.

It can be used by an arts organization to probabilistically forecast future audience evolution, in both the short and the long (steady state) term. It also allows for uncertainty in the input parameters.

'''Keywords:''' Dynamic models, Markov processes

'''Download:''' [[Media:Donor_Presenter_Dashboard_II.ANA|Donor-Presenter Dashboard.ana]]

=== Regulation of Photosynthesis ===

:[[image:Photosynthesis fluorescence.jpg]]

A model of how photosynthesis is regulated inside a cyanobacteria. As light exposure varies over time (and you can experiment with various light intensity waveforms), it simulates the concentration levels of key transport molecules along the chain, through the PSII complex, plasto-quinone pool, PSI complex, down to metabolic oxidation. The dynamic response to light levels, or changes in light levels, over time becomes evident, and the impact of changes to metabolic demand can also be observed. In the graph of fluorescence above, we can see an indicator of how much energy is being absorbed, in three different cases (different light intensities). In the two higher intensity cases, photoinhibition is observed -- a protective mechanism of the cell that engages when more energy is coming in than can be utilized by the cell. Excess incoming energy, in the absence of photoinhibition, causes damage, particularly to the PSII complex.

This model uses node shapes for a different purpose than is normally seen in decision analysis models. In this model, ovals, instead of depicting chance variables, depict chemical reactions, where the value depicts the reaction rate, and rounded rectangles depict chemical concentrations.

Two models are attached. The first is a bit cleaner, and focused on the core transport chain, as described above. The second is less developed, but is focused more on genetic regulation processes.

'''Keywords:''' Photosynthesis, dynamic models

'''Author:''' Lonnie Chrisman

'''Download:'''
* [[media:Photosynthesis regulation.ANA|Photosynthesis Regulation.ana]] - main regulation pathways
* [[media:Photosystem.ana | Photosystem.ana]] - rough sketch of genetic regulation.

=== Time-series re-indexing ===

:[[image:Weekly_data_graph_ex.png]]

'''Description:''' This model contains some examples of time-series re-indexing. It is intended to demonstrate some of these basic techniques.

In this example, actual measurements were collected at non-uniform time increments. Before analyzing these, we map these to a uniformly spaced time index (<code>Week</code>), occurring on Monday of each week. The mapping is done using an interpolation. The evenly-spaced data is then used to forecast future behavior. We first forecast over an index containing only future time points (<code>Future_weeks</code>), using a log-normal process model based on the historical weekly change. We then combine the historical data with the forecast on a common index (<code>Week</code>). A prob-bands graph of the weekly_data result shows the range of uncertainty projected by the process model (you'll notice the uncertainty exists only for future forecasted values, not historical ones).

'''Keywords:''' Dynamic models, forecasting, time-series re-indexing

'''Author:''' Lonnie Chrisman

'''Download:''' [[media:Time-series-reindexing.ana|Time-series-reindexing.ana]]

==Engineering Examples==

=== Timber Post Compression Load Capacity ===

'''Description:''' Here is a calculator for computing the maximum load that can be handled by a Douglas Fir - Larch post of a given size, grade, and composition in a construction setting.

'''Keywords:'''

'''Author:''' Lonnie Chrisman

'''Download:''' [[Media:PostCompression.ana|Post Compression Model]]

=== Compression Post Load Calculator ===

'''Description:''' Computes the load that a Douglas-Fir Larch post can support in compression. Works for different timber types and grades and post sizes.

'''Keywords:''' Compression analysis

'''Author:''' Lonnie Chrisman

'''Download:''' [[media:Compression_Post_Load_Capacity.ana|Compression Post Load Capacity.ana]]

=== Daylighting Options in Building Design ===

:[[File:Chapter_9.7-updated.png]]

'''Description:''' A demonstration showing how to analyze lifecycle costs and savings from daylighting options in building design.

Analysis based on Nomograph Cost/Benefit Tool for Daylighting. adapted from S.E. Selkowitz and M. Gabel. 1984. "LBL Daylighting Nomographs," LBL-13534, Lawrence Berkeley Laboratory, Berkeley CA, 94704. (510) 486-6845.

'''Keywords:''' Engineering, cost-benefits analysis

'''Author:''' Max Henrion

'''Download:''' [[media:Daylighting analyzer.ana|Daylighting analyzer.ana]]

=== California Power Plants ===

'''Description:''' An example showing how to use Choice menus and Checkbox inside an Edit table. It also shows how to use the Cell default attribute to specify default values (including Choice menu and Checkbox with default selections) specified in "Default Plant Data" to be used when user creates a new row in the Edit table. This model shows how to demonstrates the use of [[Choice|choice pulldowns]] in edit tables. The model is created during a mini-tutorial on [[Inserting Choice Controls in Edit Table Cells]] elsewhere on this Wiki.

'''Keywords:''' Edit table, Choice menu, pulldown menu, checkbox, Power plants.

'''Download:''' [[Media:California_Power_Plants.ANA|California Power Plants.ana ]]

=== Electrical Generation and Transmission ===

'''Description:''' This model of an electrical network minimizes total cost of generation and transmission. Each node in the network has power generators and consumers (demand). Nodes are connected by transmission links. Each link has a maximum capacity in Watts and an admittance (the real part of impedance is assumed to be zero). Each generator has a min and max power and a marginal cost in $/KWh. The model uses a linear program to determine how much power each generator should produce so as to minimize total cost of generation and transmission, while satisfying demand and remaining within link constraints.

''Requires Analytica Optimizer''

'''Keywords:''' Electrical engineering, power generation and transmission

'''Author:''' Lonnie Chrisman

'''Download:''' [[media:Electrical Transmission.ana|Electrical Transmission.ana]]

==Fun and Games==

=== Color Map ===

:[[File:Color_map.gif]]

'''Description:''' A model which highlights [[Cell Format Expression|Cell Formatting]] and [[Computed cell formats|Computed Cell Formats]]. Model result is a 'color map' wherein the cell fill color is computed based on three input variables (R, G, and B), the computed color is displayed in hexadecimal, and the font color of the hexadecimal color is determined by the cell fill color.

'''Keywords:''' Computed cell formatting

'''Author:''' Kimberley Mullins, Lumina Decision Systems

'''Download:''' [[media:color_map.ana|Color map.ana]]

=== 2018 World Cup Soccer final ===

'''Download:''' [[Media:World cup.ana|World cup.ana]]

'''Description:''' On July 15, 2018, France beat Croatia 4-2 in the final game of the World Cup to become world champions. But how much of that is can be attributed to France being the better team versus to the random chance? This model accompanies my blog article, [http://lumina.com/blog/world-cup-soccer.-how-much-does-randomness-determine-the-winner World Cup Soccer. How much does randomness determine the winner?], where I explore this question and use the example to demonstrate the [[Poisson|Poisson distribution]].

'''Author:''' Lonnie Chrisman, Lumina Decision Systems

=== Image recognition ===

'''Download: ''' [http://AnalyticaOnline.com/Lonnie/resnet18.zip resnet18.zip]

'''Description:''' Show it an image, and it tries to recognize what it is an image of, classifying it among 1000 possible categories. It uses an 18-layer residual network. This model is described and demonstrated in a video in the blog article [http://lumina.com/blog/an-analytica-model-that-recognizes-images An Analytica model that recognizes images].

'''Author:''' Lonnie Chrisman, Lumina Decision Systems. (Analytica implementation). Residual network developed by
* Kaiming He, Xiangyu Zhang, Shaoqing Ren, Jian Sun, "Deep Residual Learning for Image Recognition", https://arxiv.org/abs/1512.03385 rXiv:1512.03385]

==Function Examples==

=== Transforming Dimensions by transform matrix, month to quarter ===

'''Description:''' The model shows how to transform an array from a finer-grain index (e.g., Month) onto a coarser index (e.g., Quarter). We generally refer to this as [[Aggregate|aggregation]]. The model illustrates the direct use of [[Aggregate]], as well as a method to do this used before Aggregate was added to Analytica in release 4.2.

'''Webinar:''' [[Analytica_User_Group/Past_Topics#The_Aggregate_Function|the Aggregate function]].

'''Keywords''': Aggregation, level of detail, days, weeks, months, quarters, years.

'''Author:''' Lonnie Chrisman

'''Download:''' [[Media:Month to quarter.ana|Month to quarter.ana]]

=== Convolution ===

'''Description:''' Convolution is used mostly for signal and systems analysis. It is a way to combine two time series. This model contains function Convolve(Y, Z, T, I), that computes the convolution of two time series. The model contains several examples of convolved functions.

A time series is a set of points, <code>(Y, T)</code>, where <code>T</code> is the ascending X-axis, and the set of points is indexed by <code>I</code>. The values of <code>T</code> do not have to be equally spaced. The function treats <code>Y</code> and <code>Z</code> as being equal to 0 outside the range of <code>T</code>. The two time series here are the set of points <code>(Y, T)</code> and the set of points <code>(Z, T)</code>, where both sets of points are indexed by <code>I</code>.

The mathematical definition of the convolution of two time series is the function given by:

:<math>h(t) = \int y(u) z(t-u) dt</math>

'''Keywords:''' Signal analysis, systems analysis

'''Author:''' Lonnie Chrisman

'''Download''': [[Media:Convolution.ana|Convolution.ana]]

=== Dependency Tracker Module ===

:[[image:Dependency tracker.jpg]]

'''Description:''' This module tracks dependencies through your model, updating the visual appearance of nodes so that you can quickly visualize the paths by which one variable influences another. You can also use it to provide a visual indication of which nodes are downstream (or upstream) from an indicated variable.

The module contains button scripts that change the bevel appearance of nodes in your model. To see how Variable <code>X</code> influences Variable <code>Y</code>, the script will bevel the nodes for all variables that are influenced by <code>X</code> and influence <code>Y</code>. Alternatively, you can bevel all nodes that are influenced by <code>X</code>, or you can bevel all nodes that influence <code>Y</code>.

In the image above, the path from <code>dp_ex_2</code> through <code>dp_ex_4</code> has been highlighted using the bevel style of the nodes. (The result of pressing the "Bevel all from Ancestor to Descendant" button)

'''Keywords:''' Dependency analysis

'''Download:''' [[media:Dependency_Tracker.ANA | Dependency Tracker.ana]]

=== Multi-lingual Influence Diagram ===

:{| border="0"
| [[Image:English-view.png]]
| [[Image:French-view.png]]
|}

'''Description:''' Maintains a single influence diagram with Title and Description attributes in both English and French. With the change of a pull-down, the influence diagram and all object descriptions are instantly reflected in the language of choice.

If you change a title or description while viewing English, and then change to French, the change you made will become the English-language version of the description. Similarly if you make a change while viewing French.

'''Keywords:''' Multi-lingual models

'''Author:''' D. Rice, Lumina Decision Systems

'''Download:''' [[media:French-English.ana|French-English.ana]]

=== Extracting Data from an XML file ===

'''Description:''' Suppose you receive data in an XML format that you want to read into your model. This example demonstrates two methods for extracting data: Using a full XML DOM parser, or using regular expressions. The first method fully parses the XML structure, the second simply finds the data of interest by matching patterns, which can be easier for very simple data structures (as is often the case).

'''Keywords:''' Data extraction, xml, DOM parsing

'''Author:''' D. Rice, Lumina Decision Systems

'''Download:''' [[media:Parsing XML example.ana|Parsing XML example.ana]]

=== Vector Math ===

'''Description:'''
Functions used for computing geospatial coordinates and distances. Includes:
* A cross product of vectors function
* Functions to conversion between spherical and Cartesian coordinates in 3-D
* Functions to compute bearings from one latitude-longitude point to another
* Functions for finding distance between two latitude-longitude points along the great circle.
* Functions for finding the intersection of two great circles

'''Keywords:''' Geospatial analysis, GIS, vector analysis

'''Author:''' Robert D. Brown III, Incite Decision Technologies, LLC

'''Download:''' [[media:Vector Math.ana|Vector Math.ana]]

==Optimizer Examples==

=== Total Allowable Harvest ===

'''Description:''' The problem applies to any population of fish or animal whose dynamics are poorly known but can be summarized in a simple model:

:<code>N_t + 1 = N_t*Lambda - landed catch*(1 + loss rate)</code>

where «N_t» is the population size (number of individuals) at time ''t'', «N_t+1» is the population size at time ''t + 1'', «Lambda» is the intrinsic rate of increase and the «loss rate» is the percentage of fish or animals killed but not retrieved relative to the «landed catch», or catch secured.

The question here is to determine how many fish or animals can be caught (landed) annually so that the probability of the population declining X% in Y years (decline threshold) is less than Z% (risk tolerance).

Two models are available for download. One uses the Optimizer ([[NlpDefine]]) to find the maximum landed catch at the risk tolerance level for the given decline threshold. The other (for those using a version of Analytica without Optimizer) uses [[StepInterp]] in an iterative way to get that maximum landed catch.

'''Keywords:''' Population analysis, dynamic models, optimization analysis

'''Author:''' Models contributed by Pierre Richard

'''Download:'''
* [[media:Total Allowable Removal model with Optimizer.ana | Total Allowable w Optimizer.ana]]
* [[media:Total Allowable Removal model w StepInterp.ana|Total Allowable w StepInterp.ana]]

=== Linearizing a discrete NSP ===

'''Description:''' A cereal formulation model

A discrete mixed integer model that chooses product formulations to minimize total ingredient costs. This could be an NSP but it uses two methods to linearize:
1) Decision variable is constructed as a constrained Boolean array
2) Prices are defined as piecewise linear curves

'''Keywords:''' product formulation, cereal formulation

'''Author:''' P. Sanford, Lumina Decision Systems

'''Download:''' [[media:Cereal Formulation1.ana|Cereal Formulation1.ana]]

=== Neural Network ===

'''Description:''' A feed-forward neural network can be trained (fit to training data) using the Analytica Optimizer. This is essentially an example of non-linear regression. This model contains four sample data sets, and is set up to train a 2-layer feedforward sigmoid network to "learn" the concept represented by the data set(s), and then test how well it does across examples not appearing in the training set.

Developed during the Analytica User Group Webinar of 21-Apr-2011 -- see the [[Analytica_User_Group/Past_Topics#Neural_Networks|webinar recording]].

'''Keywords:''' Feed-forward neural networks, optimization analysis

'''Author:''' Lonnie Chrisman, Lumina Decision Systems

'''Download:''' [[media:Neural-Network.ana|Neural Network.ana]]

==Risk Analysis==

=== Earthquake Expenses ===

'''Description:''' An example of risk analysis with time-dependence and costs shifted over time.

Certain organizations (insurance companies, large companies, governments) incur expenses following earthquakes. This simplified demo model can be used to answer questions such as:
* What is the probability of more than one quake in a specific 10 year period.
* What is the probability that in my time window my costs exceed $X?

Assumptions in this model:
* Earthquakes are Poisson events with mean rate of once every 10 years.
* Damage caused by such quake is lognormally distributed, with mean $10M adn stddev of $6M.
* Cost of damage gets incurred over the period of a year from the date of the quake as equipment is replaced and buildings are repaired over time: 20% in 1st quarter after quake, 50% in 2nd quarter, 20% in 3rd quarter, 10% in 4th quarter.

'''Keywords:''' Risk analysis, cost analysis

'''Download''': [[media:Earthquake expenses.ana|Earthquake expenses.ana]]

=== Loan Policy Selection ===

'''Description:''' A lender has a large pool of money to loan, but needs to decide what credit rating threshold to require and what interest rate (above prime) to charge. The optimal value is determined by market forces (competing lenders) and by the probability that the borrower defaults on the loan, which is a function of the economy and borrower's credit rating. The model can be used without the Analytica optimizer, in which case you can explore the decision space manually or use a parametric analysis to find the near optimal solution. Those with Analytica Optimizer can find the optimal solution (more quickly) using an [[NlpDefine|NLP]] search.

'''Best used with Analytica Optimizer'''

'''Keywords:''' Creditworthiness, credit rating, default risk, risk analysis

'''Author:''' Lonnie Chrisman

'''Download:''' [[media:Loan policy selection.ANA|Loan policy selection.ana]]

=== Inherent and Residual Risk Simulation ===

:[[File:Prob of Exceeding Loss.png]]

'''Description:''' The model simulates loss exceedance curves for a set of cybersecurity events, the likelihood and probabilistic monetary impact of which have been characterized by system experts. The goal of the model is assess the impact of mitigation measures, by comparing the residual risk curve to the inherent risk curve (defined as risk without any mitigation measures) and to the risk tolerance curve. This is a translation of a model built by Douglas Hubbard and Richard Seiersen which they describe in their book [https://www.howtomeasureanything.com/cybersecurity/about-the-book/ How to Measure Anything in Cybersecurity Risk], and which they make available [https://www.howtomeasureanything.com/cybersecurity/ here].

'''Keywords:''' Cybersecurity risk, loss exceedance curve, simulation

'''Author:''' Kim Mullins

'''Download:''' [[media:Hubbard and Seiersen cyberrisk.ana|Hubbard_and_Seiersen_cyberrisk.ana]]

== Graphing examples ==
=== Red or blue state ===
[[image:Red_or_blue_state.png|600px]]

'''Download:''' [[media:Red State Blue State plot.ana]]

'''Description:''' This example contains the shape outlines for each of the 50 US states, along with a graph that uses color to depict something that varies by state (historical political party leaning). You may find the shape data useful for your own plots. In addition, it demonstrates the polygon fill feature that is new in [[Analytica 5.2]].

'''Author:''' Lonnie Chrisman, Lumina Decision Systems

==See Also==
* [[New examples]]
* [[Additional libraries]]
* [[Uploading Example Models]]
* [[Example Models and Libraries]]
* [[Using Add Module... to import a Model file]]
* [[Import a module or library]]
* [[Tutorial: Sharing a model with ACP]]
* [[Obfuscated and Browse-Only Models]]
* [[Filed modules and libraries]]
* [[Working with Models, Modules, and Files in ADE]]
* [[Combining models into an integrated model]]
* [[Model file formats]]
* [[Model Licensing]]

Function parameter qualifiers

2019-02-15T22:18:06Z

KMullins: Corrected formatting issue

[[Category: Functions]]
[[Category:Doc Status C]] 
Parameter qualifiers are keywords used in the Parameters attribute of a function to specify what kind of value or object the function expects:
*'''Class Qualifiers''', such as '''Index''' and '''Variable''', specify what class of Object is expected.
*'''Evaluation mode qualifiers''', such as '''Mid''' and '''Prob''', control whether to evaluate a parameter as deterministic or probabilistic.
*'''Data type qualifiers''', such as '''Number''', '''Text''', '''Reference''', and '''Handle''', specify the expected data type.
*'''Dimension qualifiers''', such as '''Atom''', '''List''', '''Array''', and '''[i]''', specify the expected dimensions and indexes to support array abstraction.
* '''Optional''' (or '''=''' with default) and '''Repeated''' (or ...) specify whether a parameter is optional or may be repeated.

<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
__TOC__
</div>

== Why use qualifiers? ==

Parameter qualifiers help make sure that each parameter gets the kind of value or object that the function expects. A Class qualifier specifies the expected class (Index, Variable, or other object class). An Evaluation mode qualifier specifies whether to evaluate the parameters as deterministic (Mid) or probabilistic (Prob). A Data type qualifier specifies whether the parameter should be a number, text, Boolean, or other data type. A Dimension qualifier specifies whether a parameter should be a single value, e.g. a scalar number, or an array, and how many indexes it should have.

When the actual parameter does not match what the qualifier(s) specify, Analytica will try to convert it to the expected form. For example. it can reduce a high-dimensional array down to arrays with fewer dimensions or a scalar with no dimensions if that's what the function expects the parameter to be. If a value contains a number, but parameter expects a text, it may be able to coerce (convert) the number to a text. When it can't convert it, it flags an error. In this way, qualifiers are very helpful in avoiding errors in function calls, or at least in detecting and reporting them.

Built-in functions use qualifiers extensively to avoid or detect mismatches between formal and actual parameters. See the [[Syntax]] segment, to see what the function expects from its parameters. When you write your own [[User-Defined Functions]], It's a good idea to use qualifiers for any parameter that the function requires to be of a particular class, data type, or dimensions.

By convention, formal parameters (e.g. «a», «i», «o») start with a lowercase letter, global variables and functions (e.g. <code>F, Y, J</code>) start with an uppercase letter, and qualifiers also start with an uppercase. Analytica doesn't enforce this convention, but it helps clarity in reading functions and models.

== Example ==
For example, consider a Function F with Parameters specified as:
:<code>Function F</code><code>Parameters: (a: Array Number; i: Index; o: Optional Boolean = False)</code>

We may call the function in an expression as:
:<code>F(Y^2, J, True)</code>

The parameters, «a», «i», and «o», in the Parameters attribute are termed the ''formal parameters''. The parameters, <code>Y^2</code>, <code>J</code>, and <code>1</code> in the call to Function F are termed the ''actual parameters. ''

The qualifiers, '''Array''' '''Number''', after formal parameter «a», require that the actual parameter <code>Y^2</code> should evaluate to an array of numbers. Parameter <code>J</code> should be an Index variable. And «o» should evaluate to a Boolean (or a number that will be treated as a Boolean, i.e., 0 is False and all other numbers are <code>True</code>.) Parameter «o» is optional and defaults to <code>True</code>, if the call to the function has no actual parameter.

== Object Class Qualifiers ==
These Qualifiers, including Index, Variable, and Object, specify that the parameter to be the identifier of an object of that [[class]]. Within the function, the parameter contains a [[Handle]] to the object. It does not evaluate the parameter during the call. The function can operate on the object, including getting an attribute (or assigning to an attribute if the function is called from a script.)

==== Index ====
Requires the parameter to be the identifier of an Index. It may be a global or [[Local Indexes|local Index]]. The function does not evaluate the Index when it is called, and can use the parameter as an index in internal expressions, for example:

:<code>Function NormalizeWeights</code>
:<code>Parameters: (x: Number; i: Index)</code>
:<code>Definition: x/Sum(x, i)</code>

A parameter with Index Qualifier must be the identifier of a Variable, but its [[class]] doesn't have to be Index. It also works for other classes of variables if their [[Domain]] is an Index, Discrete, or defined as a List. It also works for a local Index declared as an Index within the Definition calling the function. And it can accept the syntax <code>A.I</code> where <code>A</code> is an array with a local index <code>I</code>.

=== Variable ===

As you might expect, a parameter qualified as Variable, should be the identifier of a Variable.

'''Typical usage:'''
:<code>Fu1(Z: Variable)</code>

[MH: Should we call this Object, since it can refer to any class of Analytica object, not just a Variable? Or would it be better to offer a several such qualifiers, to specify what Class of Object is acceptable? E.g. Module (any module type, including Model, Module, Library), Variable (any Variable type, including Index, Constant, Chance, Decision, and Variable), or Object, that allows an Object of any class.
Alternatively, we could add Object <Class>, where <class> can be any Analytica class. Should or could you be able to pass an Attribute, or User-defined Function, or System Function to an Object parameter?]

[MH: Please review changes below]

The actual parameter passed to a Variable parameter must be one of:
* An identifier of an object in the global namespace.
* An <code>X.I</code> expression, where <code>X</code> holds an array and <code>I</code> is the identifier of an index of that array.
* A local variable identifier that is an alias for an object. A local variable is an alias of an object when:
** It was declared as a Variable or Index parameter.
** It was assigned a [[Handle]], such as: <code>Var X := HandleFromIdentifier("Va1");</code>

Variable parameter won't accept a literal text, or a general expression, even if that expression returns a [[Handle]]. This is because the parameter is not actually evaluated as an expression would normally be as an actual parameter not qualified as an Index, Variable, or Object. For example, in <code>Fu2(X), X</code> is the identifier of an object, it is not an expression that evaluates to an object. If the expression were evaluated, then <code>X</code> would have to hold a [[varTerm]]. If you need to use an expression that evaluates to a varTerm, then you would define a local variable to contain the result of that expression and specify the local variable identifier when you call the function.

Within the Definition of the function, the parameter name <code>X</code> serves as an alias for the original object, and can be passed to other functions that expect objects (i.e., Variable parameters), such as <code>WhatIf(y, X, x0)</code>, or <code><attrib> Of X</code>, or <code>X Of o</code> if X is the name of an Attribute.

A Function called from a [[Script]] (not called from a Variable) can assign to the parameter, <code>X := <expr></code>, hence assigning a new definition to the variable <code>X</code> refers to. In other contexts, if <code>X</code> is in an expression or a parameter to another function that evaluates its parameters, Analytica evaluates <code>X</code> to return its value.

If the object passed in as the parameter is a valid index, then <code>X</code> can be used within the function in an index context, e.g., <code>Sum(expr, X)</code>. The Index and Variable qualifiers differ in their behavior when the local variable is used in a value-context and a self-indexed table is passed in. In a value context, a Variable parameter will evaluate to the value, while an Index parameter evaluates to its index value.

The Variable qualifier is similar to pass-by-reference in other computer languages. When called from a script (with no caching variables involved), the underlying variable's Value, [[ProbValue]], or other attributes, can be assigned to. (However, because of a prohibition on side-effects with dependency maintenance, you can't assign to the object when a function is called from a variable evaluation).

If the Variable Qualifier is followed by a Datatype qualifier, such as:
:<code>Fu3(X: Variable Number)</code>

Analytica will evaluate <code>X</code> when calling <code>Fu3</code> to check that its value has the specified Datatype. But, in the Definition of <code>Fu3</code>, it will treat <code>X</code> as an unevaluated Variable, as just above. The Coerce qualifier has no effect on a Variable parameter.

=== LVarType ===
This qualifier is for internal use by built-in functions. It is a variation on the Variable qualifier.

=== Object ===
A parameter with qualified as Object expects the identifier of any user-defined. This may be a Variable, Function, Module, or other class of Object. It is useful for meta-inference about Objects, for example to find the contents of a module. The Object is not evaluated -- which it could not be anyway if it was not a Variable.

'''Typical declaration''':
:<code>Fu1(obj: Object)</code>

'''Typical usage''':
:<code>Fu1(MyIdentifier)</code>

The qualifier Handle is closely related to '''Object'''. The distinction is that Handle is a data type qualifier, while Object is an evaluation mode qualifier. If you have an expression that returns a handle when evaluated, and you want to pass the resulting handle to a function, then you would use the Handle qualifier. You would use the Object qualifier only if you want your function to accept an identifier directly without having to surround it within a call to the [[Handle]] function. Compare:
:<code>Fu1(obj: Object)</code> --- call using: <code>Fu1(X)</code>
:<code>Fu2(obj: Handle)</code> --- call using: <code>Fu2(Handle(X))</code>

=== Module ===
''new in [[Analytica 5.0]]''
Specifies that a module is expected. The calling expression can be a module identifier, text containing the module identifier, or an expression that evaluates to a module identifier or to a textual module name. Can be used with or without the [[#Atom|atom]] qualifier or other dimensional qualifiers.

:<code>Fu1(m : Module)</code>
:<code>Fu1(m : Module atom)</code>
Call using any of these:
* Fu1(Mo1)
* Fu1('Mo1')
* Fu1([[Handle]](Mo1))

=== Class ===
''new in [[Analytica 5.0]]''
Specifies that an object Class is expected. This can be the identifier of a class, the textual name of a class, or a handle to the class object. To see a complete list of classes in Analytica, evaluate <code>#[[FindObjects]](class:Object)</code>. Can be used with or without the [[#Atom|atom]] qualifier or other dimensional qualifiers.
:<code>Fu1(c:Class)</code>
:<code>Fu1(c:Class atom)</code>
Call using any of these:
* Fu1(Button)
* Fu1('Button')
* Fu1([[Handle]](Button))

=== VarList ===
Specifies that a function expects a list of variables -- i.e., a list of pointers to Analytica objects. An example is the second parameter of built-in function [[WhatIfAll]].

'''Related:''' List of Index

If you really want to pass a variable number of Variables as parameters to a function, it is better to use the ellipsis qualifier:
:<code>(vars: ... Variable)</code>

In this case, it passes a list of handles to each variable to parameter vars, without evaluating them. Inside the function, vars contains a list of Handles.

When the VarList parameter is used, as with the declarations:
:<code>(vars: VarList)</code>
:<code>(vars: VarList[ ])</code>
:<code>(vars: VarList[I])</code>
:<code>(vars: List[I] of Variable)</code>

or with the related declaration:
:<code>(vars: List[] of IndexType)</code>
:etc.

Then the argument IS evaluated. The elements of the evaluated result must then be Handles. If not, an error results. In normal Analytica usage, it is pretty unusual for a result to evaluate to [[varTerm]]s. If you use an identifier within an expression, it will evaluate to the underlying value, so it doesn't work to pass a list of identifiers. For example:

:<code>Function Fu1(vars: VarList)</code>
:<code>Function Fu2(vars: ... Variable)</code>
:<code>Fu1([Va1, Va2, Va3])</code> -- won't work because the list expression [...] will evaluate the variables inside it.
:<code>Fu1(GetVariableByName(["Va1", "Va2"]))</code> -- Good
:<code>Fu2([Va1, Va2, Va3])</code> -- good
:<code>Fu2(Va1, Va2, Va3)</code> -- good, equiv to previous
:<code>Fu2(GetVariableByName(["Va1","Va2"]))</code> -- won't work

== Evaluation Mode Qualifiers ==
=== Mid===

Forces the parameter to be evaluated in [[Mid]] (deterministic) mode, irrespective of the context evaluation mode.

=== Prob ===
Forces the parameter to be evaluated in Prob (probabilistic) mode, independent of the context evaluation mode.

If your user-defined function applies [[:category:Statistical Functions|statistical functions]] to a parameter, that parameter usually should be declared as Prob or Sample, otherwise your function may yield non-intuitive results. To illustrate, consider the following [[User-Defined Functions|UDF]] that uses the statistical function [[Mean]], shown two ways, with and without the Prob qualifier.
:<code>Function MeanMax1(X: Prob; J: Index) := Mean(Max(X, J))</code>
:<code>Function MeanMax2(X: Array; J: Index) := Mean(Max(X, J))</code>

Consider the results of applying these function in the following example:
:<code>Index Case := 1..3</code>
:<code>Chance Damage := Table(Case)(LogNormal(10, 2), LogNormal(7, 3), LogNormal(12, 1.2))</code>
:<code>Variable E_worst1 := Meanmax1(Damage, Case)</code>
:<code>Variable E_worst2 := MeanMax2(Damage, Case)</code>

The variables <code>E_worst</code> and <code>E_worst2</code> may be evaluated in either [[Mid]] or [[Sample]] mode. Let's compare:
:{| class=wikitable
! rowspan="2" | Expression
! colspan="2" | Evaluation Context
|-
! Mid !! Sample
|-
! Mean(Max(Damage,"Case))
| 20.53 || 20.53
|-
! MeanMax1(Damage, Case)
| 20.53 || 20.53
|-
! MeanMax2(Damage, Case)
| 12 || 20.53
|}

From this table you can see that without the Prob qualifier, the result of <code>MeanMax2</code> in [[Evaluation Modes|mid mode]] is not the same as <code>Mean(Max(Damage, Case)</code>. The potentially counter-intuitive result for <code>Mid(MeanMax2(Damage, Case))</code> occurs because the first parameter value is obtained by evaluating <code>Damage</code> in [[Evaluation Modes|mid mode]], yielding the one-dimensional array <code>[10, 7, 12]</code> indexed by <code>Case</code>, rather than an array with the full distribution samples.

=== Sample ===
Like [[Prob]], it forces the parameter to be evaluated in Prob mode, irrespective of the context mode. The only difference is that it gives an error message if the resulting value is not uncertain -- i.e. it does not contain the [[Run]] index.

=== Context ===
Evaluates the parameter in [[Mid]] or Prob mode, according to the evaluation mode used to evaluate the function being called. Context is the default evaluation mode, if no qualifier ([[Mid]], Prob, or [[Sample]]) is specified, so there is strictly no reason to use it.

=== Unevaluated ===
Accepts any expression and does not evaluate it. It leaves it up to the function to evaluate it if needed. It is rarely used within user-defined functions, but is used in various built-in functions, for example:
:<code>Whatif(e: Unevaluated; v: Variable; x)</code>

=== 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]].

== Dimension qualifiers ==

Dimension qualifiers specify the dimensions -- that is, the indexes -- that the function expects for that parameter. The qualifier ''Atom'' specifies that the parameter value passed to the function must be a single value, with no indexes. <code>(x : Array[Time, I, J])</code> qualifies parameter x as having the three indexes listed. The main reason to use a Dimension qualifier is when the function will not work with parameters with different, usually more dimensions -- usually because it uses one of the [[Expressions that don't array-abstract]]. It is also of occasional use to conserve memory in a Function that may use a lot of memory temporarily during calculation. If it specifies few or no dimensions for its parameters, it is less likely to run out of memory during computation.

The key point to understand about dimension qualifiers is that they d ''not'' 'require that the actual value passed to the function has exactly those indexes and number of dimensions. Rather, they specify that the Function expects to work on a parameter with those indexes or number of dimensions. Analytica automatically resolves any mismatch between the dimensions of the actual value and the dimensional qualifier:

* If the actual value has more indexes than specified by the qualifier, it decomposes the value over the extra indexes into slices each with the expected indexes, and calls the function on each slice. It then reassembles the results from each function call into an array with those extra indexes. This reassembled result may also have additional indexes from the individual result of each function call, if that passes through indexes that it uses, or generates new indexes itself.

* If the actual value of a parameter is missing any expected index(es) specified in the dimensionality qualifier, the function also works fine. Any operation on a value <code>v</code> over an index <code>i</code> when <code>v</code> is not indexed by <code>i</code> treats <code>v</code> as constant over <code>i</code>. For example, the atomic (scalar) number 4 is not indexed by <code>Time</code>. Suppose time has 10 steps, so:
:<code>Size(Time) → 10</code>.
Then
:<code>Sum(4, Time) → 40</code>

When multiple parameters have dimension qualifiers, Analytica coordinates the iteration over each parameter so that indexes impacting multiple parameters are iterated together.

=== Array ===
'''Typical Usage:'''
:<code>(x : Array[Time, I, J]; I: Index; J: Optional Index)</code>

The Array qualifier defines what indexes the parameter should have when passed to the Function. It consists of the word ''Array'', followed by a list of one or more indexes in square brackets. Actually, the ''Array'' is optional, since the list of indexes in square brackets is sufficient. So, these two declarations are the same:
:<code>(x: Numeric Array[Time])</code>
:<code>(x: Numeric[Time])</code>

The Array qualifier specifies that the parameter is a multi-dimensional array (of zero or more dimensions), and is most importantly used to declare what those dimensions are. Inside the body of the function, parameter variable is guaranteed to contain no dimensions other than those declared. Analytica iterates over the function, calling it repeatedly on successive slices when an argument contains extra dimensions, so that this guarantee is satisifed within the function body -- this is the basis for Array Abstraction.

Suppose <code>A</code> is indexed by [[Time]], <code>K1, K2</code>, and <code>K3</code> and that a function having the above Typical Usage declaration is called as <code>F(A, K1)</code>. Analytica will iterate over all combinations of <code>K2</code> and <code>K3</code>, slicing <code>A</code> for each combination and calling <code>F</code> each time with parameter <code>X</code> indexed only by [[Time]] and <code>I</code> (where parameter <code>I</code> is an alias for <code>K1</code> inside the function Definition).

An array declaration does not add in dimensions, so for example, if in the earlier example, if the function were called using: <code>F(5, In1)</code>, inside the function body <code>X</code> will be the scalar 5 -- the dimensions [[Time]] and <code>In1</code> are not automatically added to the parameter. However, since for all [[Array Abstraction|array-abstractable]] functions, 5 is equivalent to an array containing 5 for every element, computations will usually remain equivalent (and sometimes more efficient) even if the argument does not contain the dimension. The [[All]] keyword (described elsewhere on this page), used in conjunction with a dimensionality declaration.

When you define a function using [[Procedural Programming|procedural programming]] constructs, like [[While]] or or a local index with [[Sequence]]() that require their parameters to be Atoms, it is a good idea to qualify the dimensions of each function parameter that might affect them. The function will then array-abstract properly, and continue work if you add dimensions to the model later.

=== Atom ===
'''Typical Usage:'''
:<code>(X: Atom)</code>

Specifies that the parameter is atomic -- a single element. If an array is passed to this parameter, Analytica will iterate over its dimensions so that at each call the parameter value is guaranteed to consist of a single element, typically a number, text string, a reference, or the value [[Null]].

In esoteric cases, some internal data types can also be passed, which could theoretically include an parsed expression structure, a varset, a data blob (such as an image), a [[Optimization_Characteristics#Parts_of_a_Linear_Program_.28LP.29|LP]], [[Optimization_Characteristics#Parts_of_a_Quadratic_Program_.28QP.29|QP]] or [[Optimization_Characteristics#Parts_of_a_Non-Linear_Program_.28NLP.29|NLP]] problem-specification object.

Because an atom is considered to be a zero-dimensional array, the atomic qualifier is functionally equivalent to the Array qualifier with zero indexes, i.e.:
:<code>(X : Array[ ])</code>

See also [[Objects_and_Values#Values|Atomic values]] and [[Atomic..Do]].

=== Scalar ===
'''Typical usage:'''
:<code>(X: Scalar)</code>

The Scalar qualifier is an alias for "Number Atom".

=== Vector ===
'''Typical Usage:'''
:<code>(X: Vector[I]; I: Optional IndexType)</code>

The vector qualifier specifies that the argument passed must contain at least one dimension, even if that dimension is not explicitly specified. When there is an explicit index provided, the behavior is the same as the Array qualifier. The distinguishing behavior occurs when no index is specified, such as when an optional index is omitted in the typical preceding typical usage. In such a case, array abstraction is applied to a vector parameter until a single dimension remains, while in the case of Array it would be applied until the parameter is scalar. When the parameter contains multiple dimensions, the default single remaining dimension will be the canonically first dimension. If no index can be identified, an error results.

Examples:
:<code>Fu1 (X: Vector[I, J]; I, J: optional IndexType)</code>
:<code>Fu2 (X: Array [I, J]; I, J: optional IndexType)</code>
:<code>Fu3 (X : Vector)</code>
:<code>Variable A := (indexed by In1 and In2)</code>

Dimensionality of <code>X</code> within function body:
:<code>Fu1(A)</code> ==> <code>X</code> is dimensioned by <code>In1</code>. Iterates over <code>In2</code>.
:<code>Fu2(A)</code> ==> <code>X</code> is atomic. Iterates over <code>In1</code> and <code>In2</code>.
:<code>Fu1(A, In2)</code> => <code>X</code> is dimensioned by <code>In2</code>. Iterates over <code>In1</code>.
:<code>Fu1(A, In1, In2)</code> => <code>X</code> is dimensioned by <code>In1</code> and <code>In2</code>.
:<code>Fu3(A)</code> ==> <code>X</code> is dimensioned by <code>In1</code>. Iterates over <code>In2</code>.
:<code>Fu1([A, A^2])</code> ==> <code>X</code> is a null-indexed list of atoms. Iterates over <code>In1</code> and <code>In2</code>.
:<code>Fu2([A, A^2])</code> ==> <code>X</code> is atomic. Iterates over null-list, <code>In1</code> and <code>In2</code>.

<small>[[Media:Array vs Vector.ANA|Download example model]]</small>

Note that the example illustrate the difference between Vector and Array qualifiers.

Many built-in Analytica functions that operate on 1-D parameters act as if they are declared in this fashion (internally not all built-in functions use the newer parameter scheme documented here). These include [[Sum]], [[Min]], [[Max]], [[Product]], [[Cumulate]], [[Uncumulate]], [[CumProduct]], etc.

=== List ===
'''Typical Usages:'''
:<code>(L: List[ ])</code>
:<code>(L: List All [ ])</code>
:<code>(L: List[I]; I: IndexType)</code>

The List parameter qualifier is a variation of the Array qualifier that is used when a null-indexed dimension is expected, and the function does not want array abstraction it iterate over and remove that dimension before evaluating the function.

The array qualifier has no syntactic variation that allows you to the [[Null]]-dimension within the list of dimensions. The so-called Null-dimension does not really correspond to an actual Analytica object, but rather is a term that refers to a list. But, essentially, a declaration <code>List[I, J]</code> would be the conceptual equivalent of <code>Array[NullDim, I, J]</code>. It declares that the parameter may be indexed by the null-dimension, <code>I</code>, and <code>J</code>. Without the All qualifier, none of these dimensions are required, but they are the only ones allowed.

As is the case with the [[Array]] qualifier, a [[List]] declaration with no brackets is allowed but not particularly useful, since it doesn't restrict the dimensionality of the parameter.

The declaration <code>(L : List[ ])</code> specifies that only the null-dimension is allowed. If the argument is not a list, then L will be atomic at each function invocation. If the argument has a null-dimension, then all other dimensions are iterated, with only the null-dimension passed to the function.

When the [[All]] qualifier is included, as in <code>(L: List All[I])</code> or <code>(L : List All[ ])</code>, then both the specified index(es) and the null-index are required. When a null-index is added, Analytica has no reference index object to determine its length, so a null-list of length one is added.

When the list qualifier is used in conjunction with the Variable or Index qualifiers, a somewhat different treatment results. For these cases, see the [[VarList]] qualifier. "Variable List" or "List of Variable" is synonymous with VarList.

=== All ===
'''Typical Usage:'''
:<code>(A: Array All[I, J])</code>

The All qualifier is used with Array, Vector, or List to specify that the function requires all listed indexes to be present. Without All, it allows, but does not require that the parameter has these dimensions. With All , the function body is guaranteed that the parameter has all and exactly the listed dimensions.

If an argument to an array parameter has extra indexes not listed, they are iterated, whether or not the [[All]] qualifier is present. If any named index(es) is (are) not an index of the actual parameter, it adds the index(es) as a dimension, repeating the value of the parameter across the added dimension(s). Internally, it represents them as ''sparse dimensions'', so that there is little memory or time penalty involved in passing the extra dimensions; however, if the function operates over that dimension, intermediate or final results may require more memory, because for example, intermediate values may no longer be constant over those dimensions.

=== Reduced ===
'''Typical Usage:'''
:<code>(A, B: Array[I]; C:Array[J]; D: Reduced)</code>

When a parameter is declared with the Reduced keyword, it is sliced along any dimensions that are iterated as a result of dimensionality declarations on other parameters. For example, with the preceding declaration, suppose that the function is called with <code>A[I, J], B[I, K], C[J, K]</code> and <code>D[I, J, K]</code>. Then Analytica will iterate over <code>J</code> (for parameter <code>A</code>) and over <code>K</code> (for parameters <code>B</code> and <code>C</code>). <code>D</code> will thus be reduced by dimensions <code>J</code> and <code>K</code>, so that within the function body, <code>D</code> will be remain dimensioned only by <code>I</code>.

When a parameter is declared as Reduced, no index dimensions can be declared. In other words, <code>D : Reduced[I]</code> would result in an error.

An example situation where the Reduced qualifier is useful is the following. Suppose a function can compute multiple related results. A parameter, computation, indicates which result is desired, e.g.:
:<code>Function Process(A: Numeric[I]; I: Index; computation: Reduced)</code>

Within the function, Process can examine the computation parameter to determine exactly which computations need to be done. If the same computation is requested several times (for the same iteration along A), work does not need to be repeated, and if two computations share 90% of a computation, the function can leverage this fact, which it would not be able to do if these were done on separate iterations.

== Data type qualifiers ==
A Data Type, such as Number, Positive Negative, Text, or Reference, is a qualifier to specify the expected type of value of a parameter. If the parameter doesn't have the specified type when the function is called, it gives an evaluation error. If the parameter is an array, it checks that every cell of the array is of the expected type. You can combine a Data type qualifier with an Array type qualifier, such as Vector, Array, or [I], or with object qualifier, such as Index. The qualifier Coerce requests that, if the parameter has a different type, Analytica should try to convert it to the desired type if possible -- e.g. convert a number to a text. The data type is optional. A small performance penalty is incurred at the time of a function call when the data type is specified.

=== Number ===
:<code>(x: Number)</code>

Expects an expression that evaluates to a number (which includes [[INF]], -[[INF]], or [[NaN]]), or an array of numbers.

=== Text ===
:<code>(s: Text)</code>

Expects an expression that evaluates to a text value (which includes empty text ''), or an array of text values.

=== Reference ===
:<code>(r: Reference)</code>

Expects an expression that evaluates to a Reference, or an array of references. <code>R</code> must be a reference, or an array of references. Each reference may refer to any type of value or object without restriction.

=== Positive ===
:<code>(x: Positive)</code>

A positive number, which could include [[INF]], but not [[NaN]].

=== NonNegative ===
Zero or a positive number, which could include [[INF]], but not [[NaN]].

=== Handle ===
:<code>(v: Handle)</code>

Expects a handle to an object or an array of handles. These functions [[Handle]], [[HandleFromIdentifier]], [[IndexesOf]] return handles. You can also get a handle from the [[Contains]] or [[IsIn]] Attributes of an object, or an Array of Handles from the Inputs, Outputs, or Contains Attributes of an Object. Handles are used in [[Meta-Inference]]. The [[Handle]] qualifier is a different from the Variable, Index or Object qualifiers in that its parameter is typically evaluated. The Handle qualifier specifies the expected the data type, not the evaluation mode.

=== Color ===
(''new to ''[[Analytica 5.0]]'')

A color can be either a color integer or a textual color name. A color integer is most conveniently written in hex notation as 0xaarrggbb or 0xrrggbb, where ''aa'' is the alpha value, rr the red value, ''gg'' the green value, and ''bb'' the blue value. For example, <code>0x80c0257d</code> has an alpha of 0x80, a red of 0xc0, a green of 0x25 and a blue of 0x7d. A color name is a color name in English, such as 'Red', 'Yellow', 'Green', or 'Brown'. See [[Color parameters]] for a full list of color names.

=== Coerce <type> ===
If possible, it converts the value of the parameter into the desired type, Text or Number, as specified.

'''Typical Usages:'''
:<code>(t : Coerce Text; x: Coerce Number)</code>

When coercing a number to Text, it uses the number format of the Variable or Function that calls the function which coerces its parameter(s)-- not the number format of the called function.
:<code>Function Result_text(x: Coerce Text) := 'The result is ' & x</code>
:<code>Variable Y := Result_text(12345.678)</code>

If <code>Y</code> uses Analytica's default Number Format, which is suffix format with 4 significant digits, it gives
:<code>Y -> 'The result is 12.35K'</code>

But if the Number format of Y was set to Fixed point with 2 decimal digits and commas, it gives
:<code>Y → 'The result is 12,345.68'</code>

When coercing from Text to Number, it tries to parse text containing numbers using the number format.

Coercion to a reference returns a reference to an atomic value (text or number) that is not already a reference.
Coercing an array to a reference returns an array of references to the elements of the array.

In all cases, if a coercion is not possible (including when a text does not contain a valid number), it flags an evaluation error.

== Ordering Qualifiers ==

=== Ascending ===
'''Typical Usages:'''
:<code>(A : Ascending[I])</code>
:<code>(L : Ascending List[ ])</code>
:<code>(I : Ascending IndexType)</code>

The ascending qualifier specifies that the values of a list, vector, array, or index must be in non-strictly ascending order. Use of this qualifier requires that the declaration specifies a one-dimensional parameter. Without one dimension, the index over which it must be ascending is ambiguous, and hence an error is issued.

The test triggers an error if any element is less than the value that precedes it. The test is non-strict, so that a constant array, or an element equal to its predecessor, does not trigger an error. There is no parameter qualifier variation that tests for strict ascending order.

=== Descending ===
The descending qualifier specifies that the values of a list, vector, array, or index must be in non-strictly descending order. It is the exact dual of the Ascending parameter qualifier -- see the description above for Ascending for details.

== Optional and repeated parameters ==
=== Optional qualifier ===
'''Typical uses:'''
:<code>Function F1(x: optional)</code>
:<code>Function F2(a: Array[I]; i: optional IndexType)</code>
:<code>Function F3(a: Optional = 0; b := 99)</code>

The ''Optional'' qualifier specifies that a parameter is optional. If the function is called with no value, the parameter has the value Undefined inside the function. You can test if the value is undefined with functions [[Data_Type_Functions#IsNotSpecified|IsNotSpecified]](...) or IsUndef(...).

You can provide a different default using an equal sign, as in the example, <code>a: = 0</code> for <code>F3</code> above. In that case, the parameter gets the specified default if none is provided when you call it.

The function, you can pass a parameter declared as optional as a argument to another function having an optional parameter. If the parameter is not specified to the first function, it will appear to the second function as if it is not specified as well. Within the body, should the parameter variable itself be used, it contains the special system value Undefined.

Optional can be applied to values or indexes. Using the optional qualifier on index parameters causes array parameters using that index to be of variable dimensionality.

Note: Use of the ellipsis qualifier, or the inclusion of a default value, are alternative means to specify optional or variable-length parameter lists.

=== Default values ===
'''Syntax:''' <code>ident: qualifiers = defaultValue</code>

'''Typical Usages''':
:<code>(X: Optional Number = 0)</code>
:<code>(X: Number = 0)</code>
:<code>(A: ContextSample[R]; R: Index = Run)</code>

You can specify a default value to be used for an optional parameter when the parameter is omitted when calling the function. In the parameters, you simply include <code> = <defaultVal></code> in the qualifier. If you specify a default in this way, you don't need to include the "Optional" qualifier since it is implied. For a value parameter, the optional value should usually be a literal, a number or text. You may use an expression, but we don't recommend it. For an Index or Variable parameter, the optional value must identify an index or variable. For one of these Unevaluated parameter types, the default could be another parameter of that type declared earlier in the parameters list.

For an index parameter you may specify the default as code>Common</code>, meaning that the default the index common to all array parameters using that index. For example:
:<code>(P, R: Array[I]; I: Index = Common)</code>

In this case, the parameters passed for <code>P</code> and <code>R</code> must share exactly one index if <code>I</code> is not specified.

=== Repeated parameters (...) ===
'''Typical Usages''':
:<code>(X: ... Scalar)</code>
:<code>(A: Array[I] ; I : ... IndexType)</code>

Three dots "..." qualifies a parameter as repeated: The function accepts one or more actual parameters of the given type. If you combine "..." with Optional, it accepts ''zero'' or more parameters -- instead of requiring at least one parameter. Within the function, an repeated parameter is a list (with [[Null]] index) containing the actual parameters given. For example,
:<code>Function ValMax(x: ... Number) := Max(X)</code>
:<code>ValMax(3, 6,-2, 4) → 6</code>

<code>ValMax()</code> returns the maximum value of its repeated parameter. Unlike the built-in [[Max]] function, it doesn't need square brackets around its parameters. During evaluation of <code>ValMax</code>, <code>X</code> is the null-indexed list <code>[3, 6,- 2, 4]</code>. <code>ValMax</code> could also be applied to array arguments, such as
:<code>ValMax(Sqrt(X), X^2, 0)</code>

This function
:<code>Function Total(a: Array[I]; i: ... IndexType)</code>

sums its parameter, a, over one or more dimensions -- a generalization of Sum(A,I). For example:
:<code>Total(A, I, J, K)</code>

is equivalent to:
:<code>Sum(Sum(Sum(A, I), J), K)</code>

(Actually, the built-in Function [[Sum]], and other [[array-reducing functions]], including [[Product]], [[Min]], [[Max]], [[Average]], already allow you to provide a list of indexes to work over.)

Inside the body of <code>Total</code>, <code>A</code> would be an array containing the [[Null]]-index, along with all dimensions listed in the <code>I</code> parameter.

You can specify an array parameter with a variable number of explicit indexes, by using the ellipsis on an index parameter, e.g:
:<code>(A: Array[I]; I: ... Optional IndexType)</code>

A parameter passed to an repeated parameter may NOT be indexed by [[Null]]. (However, an explicit bracket syntax can be used to group a variable number of arguments in the call, see examples below).

Several syntaxes may be used when calling a function containing an repeated parameter. When the parameter is named in the call, then all arguments that follow are considered to be instances of that parameter up until another parameter name is indicated. For example, in the declaration
You may use several methods to specify the actual parameters to a function with repeated parameters. For this function:

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

you may give the repeated parameter by name:
:<code>Fxy(X: 1, 2, 3, 4, Y: 5, 6, 7)</code>

Use position and naming only the second parameter Y:

:<code>Fxy(1, 2, 3, 4, Y: 5, 6, 7)</code>

In this case, the first four are treated as parameters to X. You needed to specify parameter Y by name, to make clear that the second four are elements of Y.

You may also use square brackets with pure positional syntax:

:<code>Fxy([1, 2, 3, 4], [5, 6, 7])</code>

The brackets prevent any ambiguity.

Repeated parameters for indexes are useful to enable a variable number of dimensions for an array parameter. However, you cannot (currently) use the individual indexes explicitly from within the user-defined function. You could implement the <code>Total</code> function above as:

:<code>Sum(Sum(Sum(Sum(Sum(Sum(Sum(Sum(Sum(Sum(Sum(Sum(Sum(Sum(Sum(A)))))))))))))))</code>

which would work up to 15 dimensions (the maximum # of dimensions allowed in Analytica anyway), but note that the indexes are not specified explicitly. It would be difficult currently to use the I parameter in the function itself.

Note that Repeated indexes can be mixed with non-Repeated indexes in array declarations, e.g.
:<code>(A: Array[I, J]; I: IndexType; J: ... IndexType)</code>

This function requires two or more indexes: <code>I</code> and one or more instances of <code>J</code>.

=== '''Using Index with Optional and Repeated Qualifiers''' ===

:<code>I: Index</code> -- The function requires an index parameter
:<code>I: Optional Index</code> -- the function can accept an Index parameter, but it is optional.
:<code>I: Index = J</code> -- the function can accept an Index parameter. If omitted it defaults to <code>J</code>. Using <code>=</code> to specify a default value implies the parameter is optional, even if the keyword <code>Optional</code> is omitted.
:<code>I: Index = Run</code> -- the function can accept an Index parameter. If omitted it defaults to [[Run]]].
:<code>I: Repeat Index</code> -- the function expects a list of one or more Index parameters.
:<code>I: ... Optional Index</code> -- the function expects a list of zero or more Index parameters. Ellipsis "..." is a synonym for<code>Repeat</code>

You can also use a local variable that refers to an Index:
:<code>VAR v := GetVariableByName("In1") DO Fu1(v)</code>

which is equivalent to
:<code>Fu1(In1)</code>

You cannot specify a general expression where an Index is required, so you could not compose the above to:
:<code>Fu1(GetVariableByName("In1"))</code>

== Other Qualifiers ==
=== Hidden ===
When marked as hidden, a parameter does not appear in the object finder dialog, or when pasting the definition via the definition menu. The parameter, however, is there and can be specified in a function call.

Internally Analytica makes use of hidden parameters in the following construct:
:<code>(A; exprA: hidden unevaluated = A)</code>

This allows the underlying implementation access to the expression for <code>A</code>, while still receiving the evaluated parameter <code>A</code> (suitably iterated and typechecked if other qualifiers are attached to <code>A</code>).

=== Of ===
The [[Of]] qualifier is ignored by the parameter qualifier parser, but can be included within qualifier list for stylistic preference, such as:
:<code>(X : Ascending Array[I, J] of Number)</code>
:<code>(L : List of Number)</code>

as equivalent alternatives to
:<code>(X : Ascending Number Array[I,J])</code>
:<code>(X : Number List)</code>

and so on. Note that qualifiers can appear in any order, and contain various aliases (such as Numeric or Numbers) to make either stylistic variation sensible, depending on user preference.

=== Deprecated Synonyms for Parameter Qualifiers ===

We originally defined synonyms for some parameter qualifiers, thinking it would let you specify parameter lists more flexibly. In practice, users found it harder to recognize and remember so many terms, so we have chosen one preferred term for each qualifier and deprecate the others -- i.e. we advise you not to use them. Please use the preferred terms, since the deprecated ones may not be supported in future releases.

For the benefit of those looking at old Analytica code, here are the synonyms, after the recommended term for each qualifier:
:{| class="wikitable"
!Recommended term
!Synonyms
|-
|<code>Array</code>
|ArrayType, Arr
|-
|<code>Index</code>
|IndexType
|-
|<code>Prob</code>
|Probabilistic, ProbType, Uncertain
|-
|<code>Sample</code>
|Samp, SampType, SampleType
|-
|<code>Mid</code>
|Determ, DetermType, DetermMode, MidMode
|-
|<code>Context</code>
|Expr, ContextType
|-
|<code>Unevaluated</code>
|Expression
|-
|<code>ContextSample</code>
|ContextSamp, MaybeSamp, MaybeSample
|-
|<code>Variable</code>
|VariableType, Var, VarType
|-
|<code>VariableList</code>
|VarList, Variable List, List of Variable
|-
|<code>Atom</code>
|Atomic, AtomicType, AtomType
|-
|<code>Scalar</code>
|ScalarType, Scalars
|-
|<code>Vector</code>
|VectorType
|-
|<code>List</code>
|ListType
|-
|<code>Number</code>
|Numeric, Numbers, NumberType, NumericType, Num, Real, Boolean
|-
|<code>Text</code>
|Textual, TexType, TextType
|-
|<code>Reference</code>
|Ref, RefType, ReferenceType
|-
|<code>NonNegative</code>
|PositiveOrZero, NotNegative
|-
|<code>Coerce</code>
|Coerced
|-
|<code>Optional</code>
|opt
|}
:

==See Also==
* [[Parameter qualifiers]]
* [[ParameterEnumeration]]
* [[Function calls and parameters]]
* [[Repeated Parameter Forwarding]]
* [[User-Defined Functions]]
* [[User-defined Functions and Libraries]]
* [[Class]]

File:Valentine's Date.ana

2019-02-14T01:11:46Z

KMullins: Optimal stopping theory applied to a Valentine's Date problem, simulating expected results and time spent. Corresponds to Feb 14, 2019 blog post.

Optimal stopping theory applied to a Valentine's Date problem, simulating expected results and time spent. Corresponds to Feb 14, 2019 blog post.

Repeated Parameter Forwarding

2019-02-13T18:48:29Z

KMullins: Corrected typo.

[[Category:Functions]]

__TOC__

Repeated parameter forwarding lets you pass a list of items to a repeated function parameter. A repeated function parameter, with qualifier "..." accepts one or more parameters of the specified type. If you don't know about [[Repeated parameters|repeated parameters]], you may want to first read [[Function_Parameter_Qualifiers#Repeated_parameters_.28....29|Repeated parameters]] section of [[Function Parameter Qualifiers]].

== Basic idea ==
Consider this [[User-Defined Function]]:

:<code>Function TreeNode(x; children:...)</code>
:<code>Definition: Array(TreeNodeIdx, [x, \children])</code>
where
:<code>Index TreeNodeIdx := ['value', 'children']</code>

Then <code>TreeNode(1, 2, 3, 4)</code> creates this data structure:

:[[image:SmallTree.png]]

The repeated parameter, «children», allows you to list as many children as you'd like, without having to make use of square brackets in the syntax. Hence, we could built a multi-level tree using:

:<code>TreeNode(1, TreeNode(2, 5, 6), TreeNode(3, 7, 8, 9, TreeNode(10, 11, 12, 13)), 4)</code>

:[[image:MultiLayerTree.png]]

Now suppose you have some expression -- say, <code>F()</code> -- that computes and returns a list of "nodes", and you want to create a tree node having this set of nodes as the children, with 7 as the root. Your expression doesn't know what <code>F()</code> will return, or even how many children it will return, but for illustration let's pretend it returns <code>[1, 2, 3]</code>. Your first attempt might be
:<code>TreeNode(a, F())</code>

This produces an error, because you cannot pass a list value to a repeated parameter; however, logically what you are actually doing here is producing the wrong tree, which would actually be

:[[image:OneChildTree.png]]

The call is providing one instance of the repeated parameter, hence one child node. The value of that child node is the list of values. What we really want is to be able to pass three instances of the «children» parameter to the function, basically
:<code>TreeNode(7, Slice(F(),1), Slice(F(),2), Slice(F(),3))</code>

This would work if we knew that <code>F()</code> would return 3 values -- but [[Repeated_Parameter_Forwarding|Repeated parameter forwarding]] lets us handle this when we don't know how many items <code>F()</code> will to return. To ''forward'' the result of <code>F()</code> to the repeated parameter, we preface it with three dots
:<code>TreeNode(7, ...F())</code>

The three dots (or ellipsis, which matches the three dots used when declaring a repeated parameter) indicate that we want each item in the computed result to be passed as one instance of the repeated parameter. When you use this syntax, the expression following the three dots must produce a list or a 1-D array.

Be aware that <code>...</code> is part of the expression -- not that we've omitted something!

== Uses ==
=== Operating over all indexes of an array ===

Several built-in functions accept a repeated index parameter, so that you can apply them over multiple dimensions, such as:
:<code>Sum(X, I, j, K)</code>
Other such functions, besides [[Sum]], include [[Max]], [[Min]], [[ArgMax]], [[ArgMin]], [[CondMax]], [[CondMin]], [[Average]], [[Product]], and [[Array]].

Sometimes you'd like to apply these functions over every index of an array. Parameter forwarding makes it easy, e.g.
:<code>Sum(A,...IndexesOf(A))</code>

Note that this sometimes violates the [[Expressions_that_don%27t_array-abstract#Principle_of_Array_Abstraction|principle of array abstraction]], which could limit the flexibility of your model. So you should be careful with this.

=== Creating a constant array over computed dimensions ===

Sometimes it is useful to create a constant array over a set of indexes. You can do this using, e.g, <code>Array(I, J, 0)</code>, to create an array on indexes I and J having the value 0 everywhere. But what if the set of indexes is computed? Here is an example
:<code>Array( ...#SetDifference(\IndexesOf(A), \IndexesOf(B)), 0)</code>

This creates an array containing all the indexes of <code>A</code> that are not also indexes of <code>B</code>, with all values 0.

=== Forwarding a repeated parameter in a user-defined function===

Sometimes it's useful to wrap an existing function with a [[User-Defined Function]] that you create. For example, if an existing function does most of what you want, but doesn't treat [[Null]] values the way you like, has a bug you need to work around, or for some other reason you might create your own variation. The original function might have a bunch of parameters that you just simply want to forward to the original function. When the parameter being forwarded is a repeated parameter, you need to use the repeated parameter forwarding syntax.

The [[User-Defined Function]] <code>AbsMax</code> here accepts the same parameters as [[Max]], but returns the maximum of the absolute value. It is essentially a wrapper of the [[Max]] function -- we copy the parameter declaration for Max:

<pre style="background:white; border:white; margin-left: 1em;">
Function AbsMax(X; I: ... recommended Index WarnDynamic; IgnoreNonNumbers, IgnoreNaN: optional named atomic boolean; caseInsensitive: optional atomic boolean)
Definition: Max(Abs(X),...I, IgnoreNonNumbers, IgnoreNaN, caseInsensitive)
</pre>

To forward the repeated parameter, we need the ... in front of I, otherwise it would look like one parameter instance.

=== Computing a set of decisions or constraints for DefineOptimization ===

The [[DefineOptimization]] function accepts a list of decision and constraint nodes as repeated parameters. If you decide to get fancy, you might decide to create an interface, or some logic, that computes which constraints or decisions should be active. [[Repeated Parameter Forwarding|Repeated parameter forwarding]] allows you to provide a computed list of decisions or [[DefineOptimization#Constraints|constraints]] to the optimization declaration, e.g.
<code>[[DefineOptimization]](decisions: ...ActiveDecisions, constraints: ...ActiveConstraints, maximize: myObjective )</code>

Note that although the two parameters normally look for object identifiers, here the identifier <code>ActiveDecisions</code> is actually the variable that computes which decisions to use (as a 1-D array or list), and not one of the decision nodes. Similarly for <code>ActiveConstraints</code>.

==History==
Introduced in [[Analytica 4.5]].

== See Also ==
* [[Function calls and parameters]]
* [[Function_Parameter_Qualifiers#Repeated_parameters_.28....29|Repeated parameters]]
* [[Function Parameter Qualifiers]]
* [[Parametric Analysis]]
* [[IndexesOf]]
* [[DefineOptimization#Constraints|Constraints]]
* [[DefineOptimization]]

Function parameter qualifiers

2019-02-13T18:46:48Z

KMullins: /* Repeated parameters (...) */

[[Category: Functions]]
[[Category:Doc Status C]] 
Parameter qualifiers are keywords used in the Parameters attribute of a function to specify what kind of value or object the function expects:
*'''Class Qualifiers''', such as '''Index''' and '''Variable''', specify what class of Object is expected.
*'''Evaluation mode qualifiers''', such as '''Mid''' and '''Prob''', control whether to evaluate a parameter as deterministic or probabilistic.
*'''Data type qualifiers''', such as '''Number''', '''Text''', '''Reference''', and '''Handle''', specify the expected data type.
*'''Dimension qualifiers''', such as '''Atom''', '''List''', '''Array''', and '''[i]''', specify the expected dimensions and indexes to support array abstraction.
* '''Optional''' (or '''=''' with default) and '''Repeated''' (or ...) specify whether a parameter is optional or may be repeated.

<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
__TOC__
</div>

== Why use qualifiers? ==

Parameter qualifiers help make sure that each parameter gets the kind of value or object that the function expects. A Class qualifier specifies the expected class (Index, Variable, or other object class). An Evaluation mode qualifier specifies whether to evaluate the parameters as deterministic (Mid) or probabilistic (Prob). A Data type qualifier specifies whether the parameter should be a number, text, Boolean, or other data type. A Dimension qualifier specifies whether a parameter should be a single value, e.g. a scalar number, or an array, and how many indexes it should have.

When the actual parameter does not match what the qualifier(s) specify, Analytica will try to convert it to the expected form. For example. it can reduce a high-dimensional array down to arrays with fewer dimensions or a scalar with no dimensions if that's what the function expects the parameter to be. If a value contains a number, but parameter expects a text, it may be able to coerce (convert) the number to a text. When it can't convert it, it flags an error. In this way, qualifiers are very helpful in avoiding errors in function calls, or at least in detecting and reporting them.

Built-in functions use qualifiers extensively to avoid or detect mismatches between formal and actual parameters. See the [[Syntax]] segment, to see what the function expects from its parameters. When you write your own [[User-Defined Functions]], It's a good idea to use qualifiers for any parameter that the function requires to be of a particular class, data type, or dimensions.

By convention, formal parameters (e.g. «a», «i», «o») start with a lowercase letter, global variables and functions (e.g. <code>F, Y, J</code>) start with an uppercase letter, and qualifiers also start with an uppercase. Analytica doesn't enforce this convention, but it helps clarity in reading functions and models.

== Example ==
For example, consider a Function F with Parameters specified as:
:<code>Function F</code><code>Parameters: (a: Array Number; i: Index; o: Optional Boolean = False)</code>

We may call the function in an expression as:
:<code>F(Y^2, J, True)</code>

The parameters, «a», «i», and «o», in the Parameters attribute are termed the ''formal parameters''. The parameters, <code>Y^2</code>, <code>J</code>, and <code>1</code> in the call to Function F are termed the ''actual parameters. ''

The qualifiers, '''Array''' '''Number''', after formal parameter «a», require that the actual parameter <code>Y^2</code> should evaluate to an array of numbers. Parameter <code>J</code> should be an Index variable. And «o» should evaluate to a Boolean (or a number that will be treated as a Boolean, i.e., 0 is False and all other numbers are <code>True</code>.) Parameter «o» is optional and defaults to <code>True</code>, if the call to the function has no actual parameter.

== Object Class Qualifiers ==
These Qualifiers, including Index, Variable, and Object, specify that the parameter to be the identifier of an object of that [[class]]. Within the function, the parameter contains a [[Handle]] to the object. It does not evaluate the parameter during the call. The function can operate on the object, including getting an attribute (or assigning to an attribute if the function is called from a script.)

==== Index ====
Requires the parameter to be the identifier of an Index. It may be a global or [[Local Indexes|local Index]]. The function does not evaluate the Index when it is called, and can use the parameter as an index in internal expressions, for example:

:<code>Function NormalizeWeights</code>
:<code>Parameters: (x: Number; i: Index)</code>
:<code>Definition: x/Sum(x, i)</code>

A parameter with Index Qualifier must be the identifier of a Variable, but its [[class]] doesn't have to be Index. It also works for other classes of variables if their [[Domain]] is an Index, Discrete, or defined as a List. It also works for a local Index declared as an Index within the Definition calling the function. And it can accept the syntax <code>A.I</code> where <code>A</code> is an array with a local index <code>I</code>.

=== Variable ===

As you might expect, a parameter qualified as Variable, should be the identifier of a Variable.

'''Typical usage:'''
:<code>Fu1(Z: Variable)</code>

[MH: Should we call this Object, since it can refer to any class of Analytica object, not just a Variable? Or would it be better to offer a several such qualifiers, to specify what Class of Object is acceptable? E.g. Module (any module type, including Model, Module, Library), Variable (any Variable type, including Index, Constant, Chance, Decision, and Variable), or Object, that allows an Object of any class.
Alternatively, we could add Object <Class>, where <class> can be any Analytica class. Should or could you be able to pass an Attribute, or User-defined Function, or System Function to an Object parameter?]

[MH: Please review changes below]

The actual parameter passed to a Variable parameter must be one of:
* An identifier of an object in the global namespace.
* An <code>X.I</code> expression, where <code>X</code> holds an array and <code>I</code> is the identifier of an index of that array.
* A local variable identifier that is an alias for an object. A local variable is an alias of an object when:
** It was declared as a Variable or Index parameter.
** It was assigned a [[Handle]], such as: <code>Var X := HandleFromIdentifier("Va1");</code>

Variable parameter won't accept a literal text, or a general expression, even if that expression returns a [[Handle]]. This is because the parameter is not actually evaluated as an expression would normally be as an actual parameter not qualified as an Index, Variable, or Object. For example, in <code>Fu2(X), X</code> is the identifier of an object, it is not an expression that evaluates to an object. If the expression were evaluated, then <code>X</code> would have to hold a [[varTerm]]. If you need to use an expression that evaluates to a varTerm, then you would define a local variable to contain the result of that expression and specify the local variable identifier when you call the function.

Within the Definition of the function, the parameter name <code>X</code> serves as an alias for the original object, and can be passed to other functions that expect objects (i.e., Variable parameters), such as <code>WhatIf(y, X, x0)</code>, or <code><attrib> Of X</code>, or <code>X Of o</code> if X is the name of an Attribute.

A Function called from a [[Script]] (not called from a Variable) can assign to the parameter, <code>X := <expr></code>, hence assigning a new definition to the variable <code>X</code> refers to. In other contexts, if <code>X</code> is in an expression or a parameter to another function that evaluates its parameters, Analytica evaluates <code>X</code> to return its value.

If the object passed in as the parameter is a valid index, then <code>X</code> can be used within the function in an index context, e.g., <code>Sum(expr, X)</code>. The Index and Variable qualifiers differ in their behavior when the local variable is used in a value-context and a self-indexed table is passed in. In a value context, a Variable parameter will evaluate to the value, while an Index parameter evaluates to its index value.

The Variable qualifier is similar to pass-by-reference in other computer languages. When called from a script (with no caching variables involved), the underlying variable's Value, [[ProbValue]], or other attributes, can be assigned to. (However, because of a prohibition on side-effects with dependency maintenance, you can't assign to the object when a function is called from a variable evaluation).

If the Variable Qualifier is followed by a Datatype qualifier, such as:
:<code>Fu3(X: Variable Number)</code>

Analytica will evaluate <code>X</code> when calling <code>Fu3</code> to check that its value has the specified Datatype. But, in the Definition of <code>Fu3</code>, it will treat <code>X</code> as an unevaluated Variable, as just above. The Coerce qualifier has no effect on a Variable parameter.

=== LVarType ===
This qualifier is for internal use by built-in functions. It is a variation on the Variable qualifier.

=== Object ===
A parameter with qualified as Object expects the identifier of any user-defined. This may be a Variable, Function, Module, or other class of Object. It is useful for meta-inference about Objects, for example to find the contents of a module. The Object is not evaluated -- which it could not be anyway if it was not a Variable.

'''Typical declaration''':
:<code>Fu1(obj: Object)</code>

'''Typical usage''':
:<code>Fu1(MyIdentifier)</code>

The qualifier Handle is closely related to '''Object'''. The distinction is that Handle is a data type qualifier, while Object is an evaluation mode qualifier. If you have an expression that returns a handle when evaluated, and you want to pass the resulting handle to a function, then you would use the Handle qualifier. You would use the Object qualifier only if you want your function to accept an identifier directly without having to surround it within a call to the [[Handle]] function. Compare:
:<code>Fu1(obj: Object)</code> --- call using: <code>Fu1(X)</code>
:<code>Fu2(obj: Handle)</code> --- call using: <code>Fu2(Handle(X))</code>

=== Module ===
''new in [[Analytica 5.0]]''
Specifies that a module is expected. The calling expression can be a module identifier, text containing the module identifier, or an expression that evaluates to a module identifier or to a textual module name. Can be used with or without the [[#Atom|atom]] qualifier or other dimensional qualifiers.

:<code>Fu1(m : Module)</code>
:<code>Fu1(m : Module atom)</code>
Call using any of these:
* Fu1(Mo1)
* Fu1('Mo1')
* Fu1([[Handle]](Mo1))

=== Class ===
''new in [[Analytica 5.0]]''
Specifies that an object Class is expected. This can be the identifier of a class, the textual name of a class, or a handle to the class object. To see a complete list of classes in Analytica, evaluate <code>#[[FindObjects]](class:Object)</code>. Can be used with or without the [[#Atom|atom]] qualifier or other dimensional qualifiers.
:<code>Fu1(c:Class)</code>
:<code>Fu1(c:Class atom)</code>
Call using any of these:
* Fu1(Button)
* Fu1('Button')
* Fu1([[Handle]](Button))

=== VarList ===
Specifies that a function expects a list of variables -- i.e., a list of pointers to Analytica objects. An example is the second parameter of built-in function [[WhatIfAll]].

'''Related:''' List of Index

If you really want to pass a variable number of Variables as parameters to a function, it is better to use the ellipsis qualifier:
:<code>(vars: ... Variable)</code>

In this case, it passes a list of handles to each variable to parameter vars, without evaluating them. Inside the function, vars contains a list of Handles.

When the VarList parameter is used, as with the declarations:
:<code>(vars: VarList)</code>
:<code>(vars: VarList[ ])</code>
:<code>(vars: VarList[I])</code>
:<code>(vars: List[I] of Variable)</code>

or with the related declaration:
:<code>(vars: List[] of IndexType)</code>
:etc.

Then the argument IS evaluated. The elements of the evaluated result must then be Handles. If not, an error results. In normal Analytica usage, it is pretty unusual for a result to evaluate to [[varTerm]]s. If you use an identifier within an expression, it will evaluate to the underlying value, so it doesn't work to pass a list of identifiers. For example:

:<code>Function Fu1(vars: VarList)</code>
:<code>Function Fu2(vars: ... Variable)</code>
:<code>Fu1([Va1, Va2, Va3])</code> -- won't work because the list expression [...] will evaluate the variables inside it.
:<code>Fu1(GetVariableByName(["Va1", "Va2"]))</code> -- Good
:<code>Fu2([Va1, Va2, Va3])</code> -- good
:<code>Fu2(Va1, Va2, Va3)</code> -- good, equiv to previous
:<code>Fu2(GetVariableByName(["Va1","Va2"]))</code> -- won't work

== Evaluation Mode Qualifiers ==
=== Mid===

Forces the parameter to be evaluated in [[Mid]] (deterministic) mode, irrespective of the context evaluation mode.

=== Prob ===
Forces the parameter to be evaluated in Prob (probabilistic) mode, independent of the context evaluation mode.

If your user-defined function applies [[:category:Statistical Functions|statistical functions]] to a parameter, that parameter usually should be declared as Prob or Sample, otherwise your function may yield non-intuitive results. To illustrate, consider the following [[User-Defined Functions|UDF]] that uses the statistical function [[Mean]], shown two ways, with and without the Prob qualifier.
:<code>Function MeanMax1(X: Prob; J: Index) := Mean(Max(X, J))</code>
:<code>Function MeanMax2(X: Array; J: Index) := Mean(Max(X, J))</code>

Consider the results of applying these function in the following example:
:<code>Index Case := 1..3</code>
:<code>Chance Damage := Table(Case)(LogNormal(10, 2), LogNormal(7, 3), LogNormal(12, 1.2))</code>
:<code>Variable E_worst1 := Meanmax1(Damage, Case)</code>
:<code>Variable E_worst2 := MeanMax2(Damage, Case)</code>

The variables <code>E_worst</code> and <code>E_worst2</code> may be evaluated in either [[Mid]] or [[Sample]] mode. Let's compare:
:{| class=wikitable
! rowspan="2" | Expression
! colspan="2" | Evaluation Context
|-
! Mid !! Sample
|-
! Mean(Max(Damage,"Case))
| 20.53 || 20.53
|-
! MeanMax1(Damage, Case)
| 20.53 || 20.53
|-
! MeanMax2(Damage, Case)
| 12 || 20.53
|}

From this table you can see that without the Prob qualifier, the result of <code>MeanMax2</code> in [[Evaluation Modes|mid mode]] is not the same as <code>Mean(Max(Damage, Case)</code>. The potentially counter-intuitive result for <code>Mid(MeanMax2(Damage, Case))</code> occurs because the first parameter value is obtained by evaluating <code>Damage</code> in [[Evaluation Modes|mid mode]], yielding the one-dimensional array <code>[10, 7, 12]</code> indexed by <code>Case</code>, rather than an array with the full distribution samples.

=== Sample ===
Like [[Prob]], it forces the parameter to be evaluated in Prob mode, irrespective of the context mode. The only difference is that it gives an error message if the resulting value is not uncertain -- i.e. it does not contain the [[Run]] index.

=== Context ===
Evaluates the parameter in [[Mid]] or Prob mode, according to the evaluation mode used to evaluate the function being called. Context is the default evaluation mode, if no qualifier ([[Mid]], Prob, or [[Sample]]) is specified, so there is strictly no reason to use it.

=== Unevaluated ===
Accepts any expression and does not evaluate it. It leaves it up to the function to evaluate it if needed. It is rarely used within user-defined functions, but is used in various built-in functions, for example:
:<code>Whatif(e: Unevaluated; v: Variable; x)</code>

=== 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]].

== Dimension qualifiers ==

Dimension qualifiers specify the dimensions -- that is, the indexes -- that the function expects for that parameter. The qualifier ''Atom'' specifies that the parameter value passed to the function must be a single value, with no indexes. <code>(x : Array[Time, I, J])</code> qualifies parameter x as having the three indexes listed. The main reason to use a Dimension qualifier is when the function will not work with parameters with different, usually more dimensions -- usually because it uses one of the [[Expressions that don't array-abstract]]. It is also of occasional use to conserve memory in a Function that may use a lot of memory temporarily during calculation. If it specifies few or no dimensions for its parameters, it is less likely to run out of memory during computation.

The key point to understand about dimension qualifiers is that they d ''not'' 'require that the actual value passed to the function has exactly those indexes and number of dimensions. Rather, they specify that the Function expects to work on a parameter with those indexes or number of dimensions. Analytica automatically resolves any mismatch between the dimensions of the actual value and the dimensional qualifier:

* If the actual value has more indexes than specified by the qualifier, it decomposes the value over the extra indexes into slices each with the expected indexes, and calls the function on each slice. It then reassembles the results from each function call into an array with those extra indexes. This reassembled result may also have additional indexes from the individual result of each function call, if that passes through indexes that it uses, or generates new indexes itself.

* If the actual value of a parameter is missing any expected index(es) specified in the dimensionality qualifier, the function also works fine. Any operation on a value <code>v</code> over an index <code>i</code> when <code>v</code> is not indexed by <code>i</code> treats <code>v</code> as constant over <code>i</code>. For example, the atomic (scalar) number 4 is not indexed by <code>Time</code>. Suppose time has 10 steps, so:
:<code>Size(Time) → 10</code>.
Then
:<code>Sum(4, Time) → 40</code>

When multiple parameters have dimension qualifiers, Analytica coordinates the iteration over each parameter so that indexes impacting multiple parameters are iterated together.

=== Array ===
'''Typical Usage:'''
:<code>(x : Array[Time, I, J]; I: Index; J: Optional Index)</code>

The Array qualifier defines what indexes the parameter should have when passed to the Function. It consists of the word ''Array'', followed by a list of one or more indexes in square brackets. Actually, the ''Array'' is optional, since the list of indexes in square brackets is sufficient. So, these two declarations are the same:
:<code>(x: Numeric Array[Time])</code>
:<code>(x: Numeric[Time])</code>

The Array qualifier specifies that the parameter is a multi-dimensional array (of zero or more dimensions), and is most importantly used to declare what those dimensions are. Inside the body of the function, parameter variable is guaranteed to contain no dimensions other than those declared. Analytica iterates over the function, calling it repeatedly on successive slices when an argument contains extra dimensions, so that this guarantee is satisifed within the function body -- this is the basis for Array Abstraction.

Suppose <code>A</code> is indexed by [[Time]], <code>K1, K2</code>, and <code>K3</code> and that a function having the above Typical Usage declaration is called as <code>F(A, K1)</code>. Analytica will iterate over all combinations of <code>K2</code> and <code>K3</code>, slicing <code>A</code> for each combination and calling <code>F</code> each time with parameter <code>X</code> indexed only by [[Time]] and <code>I</code> (where parameter <code>I</code> is an alias for <code>K1</code> inside the function Definition).

An array declaration does not add in dimensions, so for example, if in the earlier example, if the function were called using: <code>F(5, In1)</code>, inside the function body <code>X</code> will be the scalar 5 -- the dimensions [[Time]] and <code>In1</code> are not automatically added to the parameter. However, since for all [[Array Abstraction|array-abstractable]] functions, 5 is equivalent to an array containing 5 for every element, computations will usually remain equivalent (and sometimes more efficient) even if the argument does not contain the dimension. The [[All]] keyword (described elsewhere on this page), used in conjunction with a dimensionality declaration.

When you define a function using [[Procedural Programming|procedural programming]] constructs, like [[While]] or or a local index with [[Sequence]]() that require their parameters to be Atoms, it is a good idea to qualify the dimensions of each function parameter that might affect them. The function will then array-abstract properly, and continue work if you add dimensions to the model later.

=== Atom ===
'''Typical Usage:'''
:<code>(X: Atom)</code>

Specifies that the parameter is atomic -- a single element. If an array is passed to this parameter, Analytica will iterate over its dimensions so that at each call the parameter value is guaranteed to consist of a single element, typically a number, text string, a reference, or the value [[Null]].

In esoteric cases, some internal data types can also be passed, which could theoretically include an parsed expression structure, a varset, a data blob (such as an image), a [[Optimization_Characteristics#Parts_of_a_Linear_Program_.28LP.29|LP]], [[Optimization_Characteristics#Parts_of_a_Quadratic_Program_.28QP.29|QP]] or [[Optimization_Characteristics#Parts_of_a_Non-Linear_Program_.28NLP.29|NLP]] problem-specification object.

Because an atom is considered to be a zero-dimensional array, the atomic qualifier is functionally equivalent to the Array qualifier with zero indexes, i.e.:
:<code>(X : Array[ ])</code>

See also [[Objects_and_Values#Values|Atomic values]] and [[Atomic..Do]].

=== Scalar ===
'''Typical usage:'''
:<code>(X: Scalar)</code>

The Scalar qualifier is an alias for "Number Atom".

=== Vector ===
'''Typical Usage:'''
:<code>(X: Vector[I]; I: Optional IndexType)</code>

The vector qualifier specifies that the argument passed must contain at least one dimension, even if that dimension is not explicitly specified. When there is an explicit index provided, the behavior is the same as the Array qualifier. The distinguishing behavior occurs when no index is specified, such as when an optional index is omitted in the typical preceding typical usage. In such a case, array abstraction is applied to a vector parameter until a single dimension remains, while in the case of Array it would be applied until the parameter is scalar. When the parameter contains multiple dimensions, the default single remaining dimension will be the canonically first dimension. If no index can be identified, an error results.

Examples:
:<code>Fu1 (X: Vector[I, J]; I, J: optional IndexType)</code>
:<code>Fu2 (X: Array [I, J]; I, J: optional IndexType)</code>
:<code>Fu3 (X : Vector)</code>
:<code>Variable A := (indexed by In1 and In2)</code>

Dimensionality of <code>X</code> within function body:
:<code>Fu1(A)</code> ==> <code>X</code> is dimensioned by <code>In1</code>. Iterates over <code>In2</code>.
:<code>Fu2(A)</code> ==> <code>X</code> is atomic. Iterates over <code>In1</code> and <code>In2</code>.
:<code>Fu1(A, In2)</code> => <code>X</code> is dimensioned by <code>In2</code>. Iterates over <code>In1</code>.
:<code>Fu1(A, In1, In2)</code> => <code>X</code> is dimensioned by <code>In1</code> and <code>In2</code>.
:<code>Fu3(A)</code> ==> <code>X</code> is dimensioned by <code>In1</code>. Iterates over <code>In2</code>.
:<code>Fu1([A, A^2])</code> ==> <code>X</code> is a null-indexed list of atoms. Iterates over <code>In1</code> and <code>In2</code>.
:<code>Fu2([A, A^2])</code> ==> <code>X</code> is atomic. Iterates over null-list, <code>In1</code> and <code>In2</code>.

<small>[[Media:Array vs Vector.ANA|Download example model]]</small>

Note that the example illustrate the difference between Vector and Array qualifiers.

Many built-in Analytica functions that operate on 1-D parameters act as if they are declared in this fashion (internally not all built-in functions use the newer parameter scheme documented here). These include [[Sum]], [[Min]], [[Max]], [[Product]], [[Cumulate]], [[Uncumulate]], [[CumProduct]], etc.

=== List ===
'''Typical Usages:'''
:<code>(L: List[ ])</code>
:<code>(L: List All [ ])</code>
:<code>(L: List[I]; I: IndexType)</code>

The List parameter qualifier is a variation of the Array qualifier that is used when a null-indexed dimension is expected, and the function does not want array abstraction it iterate over and remove that dimension before evaluating the function.

The array qualifier has no syntactic variation that allows you to the [[Null]]-dimension within the list of dimensions. The so-called Null-dimension does not really correspond to an actual Analytica object, but rather is a term that refers to a list. But, essentially, a declaration <code>List[I, J]</code> would be the conceptual equivalent of <code>Array[NullDim, I, J]</code>. It declares that the parameter may be indexed by the null-dimension, <code>I</code>, and <code>J</code>. Without the All qualifier, none of these dimensions are required, but they are the only ones allowed.

As is the case with the [[Array]] qualifier, a [[List]] declaration with no brackets is allowed but not particularly useful, since it doesn't restrict the dimensionality of the parameter.

The declaration <code>(L : List[ ])</code> specifies that only the null-dimension is allowed. If the argument is not a list, then L will be atomic at each function invocation. If the argument has a null-dimension, then all other dimensions are iterated, with only the null-dimension passed to the function.

When the [[All]] qualifier is included, as in <code>(L: List All[I])</code> or <code>(L : List All[ ])</code>, then both the specified index(es) and the null-index are required. When a null-index is added, Analytica has no reference index object to determine its length, so a null-list of length one is added.

When the list qualifier is used in conjunction with the Variable or Index qualifiers, a somewhat different treatment results. For these cases, see the [[VarList]] qualifier. "Variable List" or "List of Variable" is synonymous with VarList.

=== All ===
'''Typical Usage:'''
:<code>(A: Array All[I, J])</code>

The All qualifier is used with Array, Vector, or List to specify that the function requires all listed indexes to be present. Without All, it allows, but does not require that the parameter has these dimensions. With All , the function body is guaranteed that the parameter has all and exactly the listed dimensions.

If an argument to an array parameter has extra indexes not listed, they are iterated, whether or not the [[All]] qualifier is present. If any named index(es) is (are) not an index of the actual parameter, it adds the index(es) as a dimension, repeating the value of the parameter across the added dimension(s). Internally, it represents them as ''sparse dimensions'', so that there is little memory or time penalty involved in passing the extra dimensions; however, if the function operates over that dimension, intermediate or final results may require more memory, because for example, intermediate values may no longer be constant over those dimensions.

=== Reduced ===
'''Typical Usage:'''
:<code>(A, B: Array[I]; C:Array[J]; D: Reduced)</code>

When a parameter is declared with the Reduced keyword, it is sliced along any dimensions that are iterated as a result of dimensionality declarations on other parameters. For example, with the preceding declaration, suppose that the function is called with <code>A[I, J], B[I, K], C[J, K]</code> and <code>D[I, J, K]</code>. Then Analytica will iterate over <code>J</code> (for parameter <code>A</code>) and over <code>K</code> (for parameters <code>B</code> and <code>C</code>). <code>D</code> will thus be reduced by dimensions <code>J</code> and <code>K</code>, so that within the function body, <code>D</code> will be remain dimensioned only by <code>I</code>.

When a parameter is declared as Reduced, no index dimensions can be declared. In other words, <code>D : Reduced[I]</code> would result in an error.

An example situation where the Reduced qualifier is useful is the following. Suppose a function can compute multiple related results. A parameter, computation, indicates which result is desired, e.g.:
:<code>Function Process(A: Numeric[I]; I: Index; computation: Reduced)</code>

Within the function, Process can examine the computation parameter to determine exactly which computations need to be done. If the same computation is requested several times (for the same iteration along A), work does not need to be repeated, and if two computations share 90% of a computation, the function can leverage this fact, which it would not be able to do if these were done on separate iterations.

== Data type qualifiers ==
A Data Type, such as Number, Positive Negative, Text, or Reference, is a qualifier to specify the expected type of value of a parameter. If the parameter doesn't have the specified type when the function is called, it gives an evaluation error. If the parameter is an array, it checks that every cell of the array is of the expected type. You can combine a Data type qualifier with an Array type qualifier, such as Vector, Array, or [I], or with object qualifier, such as Index. The qualifier Coerce requests that, if the parameter has a different type, Analytica should try to convert it to the desired type if possible -- e.g. convert a number to a text. The data type is optional. A small performance penalty is incurred at the time of a function call when the data type is specified.

=== Number ===
:<code>(x: Number)</code>

Expects an expression that evaluates to a number (which includes [[INF]], -[[INF]], or [[NaN]]), or an array of numbers.

=== Text ===
:<code>(s: Text)</code>

Expects an expression that evaluates to a text value (which includes empty text ''), or an array of text values.

=== Reference ===
:<code>(r: Reference)</code>

Expects an expression that evaluates to a Reference, or an array of references. <code>R</code> must be a reference, or an array of references. Each reference may refer to any type of value or object without restriction.

=== Positive ===
:<code>(x: Positive)</code>

A positive number, which could include [[INF]], but not [[NaN]].

=== NonNegative ===
Zero or a positive number, which could include [[INF]], but not [[NaN]].

=== Handle ===
:<code>(v: Handle)</code>

Expects a handle to an object or an array of handles. These functions [[Handle]], [[HandleFromIdentifier]], [[IndexesOf]] return handles. You can also get a handle from the [[Contains]] or [[IsIn]] Attributes of an object, or an Array of Handles from the Inputs, Outputs, or Contains Attributes of an Object. Handles are used in [[Meta-Inference]]. The [[Handle]] qualifier is a different from the Variable, Index or Object qualifiers in that its parameter is typically evaluated. The Handle qualifier specifies the expected the data type, not the evaluation mode.

=== Color ===
(''new to ''Analytica 5.0]]'')

A color can be either a color integer or a textual color name. A color integer is most conveniently written in hex notation as 0xaarrggbb or 0xrrggbb, where ''aa'' is the alpha value, rr the red value, ''gg'' the green value, and ''bb'' the blue value. For example, <code>0x80c0257d</code> has an alpha of 0x80, a red of 0xc0, a green of 0x25 and a blue of 0x7d. A color name is a color name in English, such as 'Red', 'Yellow', 'Green', or 'Brown'. See [[Color parameters]] for a full list of color names.

=== Coerce <type> ===
If possible, it converts the value of the parameter into the desired type, Text or Number, as specified.

'''Typical Usages:'''
:<code>(t : Coerce Text; x: Coerce Number)</code>

When coercing a number to Text, it uses the number format of the Variable or Function that calls the function which coerces its parameter(s)-- not the number format of the called function.
:<code>Function Result_text(x: Coerce Text) := 'The result is ' & x</code>
:<code>Variable Y := Result_text(12345.678)</code>

If <code>Y</code> uses Analytica's default Number Format, which is suffix format with 4 significant digits, it gives
:<code>Y -> 'The result is 12.35K'</code>

But if the Number format of Y was set to Fixed point with 2 decimal digits and commas, it gives
:<code>Y → 'The result is 12,345.68'</code>

When coercing from Text to Number, it tries to parse text containing numbers using the number format.

Coercion to a reference returns a reference to an atomic value (text or number) that is not already a reference.
Coercing an array to a reference returns an array of references to the elements of the array.

In all cases, if a coercion is not possible (including when a text does not contain a valid number), it flags an evaluation error.

== Ordering Qualifiers ==

=== Ascending ===
'''Typical Usages:'''
:<code>(A : Ascending[I])</code>
:<code>(L : Ascending List[ ])</code>
:<code>(I : Ascending IndexType)</code>

The ascending qualifier specifies that the values of a list, vector, array, or index must be in non-strictly ascending order. Use of this qualifier requires that the declaration specifies a one-dimensional parameter. Without one dimension, the index over which it must be ascending is ambiguous, and hence an error is issued.

The test triggers an error if any element is less than the value that precedes it. The test is non-strict, so that a constant array, or an element equal to its predecessor, does not trigger an error. There is no parameter qualifier variation that tests for strict ascending order.

=== Descending ===
The descending qualifier specifies that the values of a list, vector, array, or index must be in non-strictly descending order. It is the exact dual of the Ascending parameter qualifier -- see the description above for Ascending for details.

== Optional and repeated parameters ==
=== Optional qualifier ===
'''Typical uses:'''
:<code>Function F1(x: optional)</code>
:<code>Function F2(a: Array[I]; i: optional IndexType)</code>
:<code>Function F3(a: Optional = 0; b := 99)</code>

The ''Optional'' qualifier specifies that a parameter is optional. If the function is called with no value, the parameter has the value Undefined inside the function. You can test if the value is undefined with functions [[Data_Type_Functions#IsNotSpecified|IsNotSpecified]](...) or IsUndef(...).

You can provide a different default using an equal sign, as in the example, <code>a: = 0</code> for <code>F3</code> above. In that case, the parameter gets the specified default if none is provided when you call it.

The function, you can pass a parameter declared as optional as a argument to another function having an optional parameter. If the parameter is not specified to the first function, it will appear to the second function as if it is not specified as well. Within the body, should the parameter variable itself be used, it contains the special system value Undefined.

Optional can be applied to values or indexes. Using the optional qualifier on index parameters causes array parameters using that index to be of variable dimensionality.

Note: Use of the ellipsis qualifier, or the inclusion of a default value, are alternative means to specify optional or variable-length parameter lists.

=== Default values ===
'''Syntax:''' <code>ident: qualifiers = defaultValue</code>

'''Typical Usages''':
:<code>(X: Optional Number = 0)</code>
:<code>(X: Number = 0)</code>
:<code>(A: ContextSample[R]; R: Index = Run)</code>

You can specify a default value to be used for an optional parameter when the parameter is omitted when calling the function. In the parameters, you simply include <code> = <defaultVal></code> in the qualifier. If you specify a default in this way, you don't need to include the "Optional" qualifier since it is implied. For a value parameter, the optional value should usually be a literal, a number or text. You may use an expression, but we don't recommend it. For an Index or Variable parameter, the optional value must identify an index or variable. For one of these Unevaluated parameter types, the default could be another parameter of that type declared earlier in the parameters list.

For an index parameter you may specify the default as code>Common</code>, meaning that the default the index common to all array parameters using that index. For example:
:<code>(P, R: Array[I]; I: Index = Common)</code>

In this case, the parameters passed for <code>P</code> and <code>R</code> must share exactly one index if <code>I</code> is not specified.

=== Repeated parameters (...) ===
'''Typical Usages''':
:<code>(X: ... Scalar)</code>
:<code>(A: Array[I] ; I : ... IndexType)</code>

Three dots "..." qualifies a parameter as repeated: The function accepts one or more actual parameters of the given type. If you combine "..." with Optional, it accepts ''zero'' or more parameters -- instead of requiring at least one parameter. Within the function, an repeated parameter is a list (with [[Null]] index) containing the actual parameters given. For example,
:<code>Function ValMax(x: ... Number) := Max(X)</code>
:<code>ValMax(3, 6,-2, 4) → 6</code>

<code>ValMax()</code> returns the maximum value of its repeated parameter. Unlike the built-in [[Max]] function, it doesn't need square brackets around its parameters. During evaluation of <code>ValMax</code>, <code>X</code> is the null-indexed list <code>[3, 6,- 2, 4]</code>. <code>ValMax</code> could also be applied to array arguments, such as
:<code>ValMax(Sqrt(X), X^2, 0)</code>

This function
:<code>Function Total(a: Array[I]; i: ... IndexType)</code>

sums its parameter, a, over one or more dimensions -- a generalization of Sum(A,I). For example:
:<code>Total(A, I, J, K)</code>

is equivalent to:
:<code>Sum(Sum(Sum(A, I), J), K)</code>

(Actually, the built-in Function [[Sum]], and other [[array-reducing functions]], including [[Product]], [[Min]], [[Max]], [[Average]], already allow you to provide a list of indexes to work over.)

Inside the body of <code>Total</code>, <code>A</code> would be an array containing the [[Null]]-index, along with all dimensions listed in the <code>I</code> parameter.

You can specify an array parameter with a variable number of explicit indexes, by using the ellipsis on an index parameter, e.g:
:<code>(A: Array[I]; I: ... Optional IndexType)</code>

A parameter passed to an repeated parameter may NOT be indexed by [[Null]]. (However, an explicit bracket syntax can be used to group a variable number of arguments in the call, see examples below).

Several syntaxes may be used when calling a function containing an repeated parameter. When the parameter is named in the call, then all arguments that follow are considered to be instances of that parameter up until another parameter name is indicated. For example, in the declaration
You may use several methods to specify the actual parameters to a function with repeated parameters. For this function:

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

you may give the repeated parameter by name:
:<code>Fxy(X: 1, 2, 3, 4, Y: 5, 6, 7)</code>

Use position and naming only the second parameter Y:

:<code>Fxy(1, 2, 3, 4, Y: 5, 6, 7)</code>

In this case, the first four are treated as parameters to X. You needed to specify parameter Y by name, to make clear that the second four are elements of Y.

You may also use square brackets with pure positional syntax:

:<code>Fxy([1, 2, 3, 4], [5, 6, 7])</code>

The brackets prevent any ambiguity.

Repeated parameters for indexes are useful to enable a variable number of dimensions for an array parameter. However, you cannot (currently) use the individual indexes explicitly from within the user-defined function. You could implement the <code>Total</code> function above as:

:<code>Sum(Sum(Sum(Sum(Sum(Sum(Sum(Sum(Sum(Sum(Sum(Sum(Sum(Sum(Sum(A)))))))))))))))</code>

which would work up to 15 dimensions (the maximum # of dimensions allowed in Analytica anyway), but note that the indexes are not specified explicitly. It would be difficult currently to use the I parameter in the function itself.

Note that Repeated indexes can be mixed with non-Repeated indexes in array declarations, e.g.
:<code>(A: Array[I, J]; I: IndexType; J: ... IndexType)</code>

This function requires two or more indexes: <code>I</code> and one or more instances of <code>J</code>.

=== '''Using Index with Optional and Repeated Qualifiers''' ===

:<code>I: Index</code> -- The function requires an index parameter
:<code>I: Optional Index</code> -- the function can accept an Index parameter, but it is optional.
:<code>I: Index = J</code> -- the function can accept an Index parameter. If omitted it defaults to <code>J</code>. Using <code>=</code> to specify a default value implies the parameter is optional, even if the keyword <code>Optional</code> is omitted.
:<code>I: Index = Run</code> -- the function can accept an Index parameter. If omitted it defaults to [[Run]]].
:<code>I: Repeat Index</code> -- the function expects a list of one or more Index parameters.
:<code>I: ... Optional Index</code> -- the function expects a list of zero or more Index parameters. Ellipsis "..." is a synonym for<code>Repeat</code>

You can also use a local variable that refers to an Index:
:<code>VAR v := GetVariableByName("In1") DO Fu1(v)</code>

which is equivalent to
:<code>Fu1(In1)</code>

You cannot specify a general expression where an Index is required, so you could not compose the above to:
:<code>Fu1(GetVariableByName("In1"))</code>

== Other Qualifiers ==
=== Hidden ===
When marked as hidden, a parameter does not appear in the object finder dialog, or when pasting the definition via the definition menu. The parameter, however, is there and can be specified in a function call.

Internally Analytica makes use of hidden parameters in the following construct:
:<code>(A; exprA: hidden unevaluated = A)</code>

This allows the underlying implementation access to the expression for <code>A</code>, while still receiving the evaluated parameter <code>A</code> (suitably iterated and typechecked if other qualifiers are attached to <code>A</code>).

=== Of ===
The [[Of]] qualifier is ignored by the parameter qualifier parser, but can be included within qualifier list for stylistic preference, such as:
:<code>(X : Ascending Array[I, J] of Number)</code>
:<code>(L : List of Number)</code>

as equivalent alternatives to
:<code>(X : Ascending Number Array[I,J])</code>
:<code>(X : Number List)</code>

and so on. Note that qualifiers can appear in any order, and contain various aliases (such as Numeric or Numbers) to make either stylistic variation sensible, depending on user preference.

=== Deprecated Synonyms for Parameter Qualifiers ===

We originally defined synonyms for some parameter qualifiers, thinking it would let you specify parameter lists more flexibly. In practice, users found it harder to recognize and remember so many terms, so we have chosen one preferred term for each qualifier and deprecate the others -- i.e. we advise you not to use them. Please use the preferred terms, since the deprecated ones may not be supported in future releases.

For the benefit of those looking at old Analytica code, here are the synonyms, after the recommended term for each qualifier:
:{| class="wikitable"
!Recommended term
!Synonyms
|-
|<code>Array</code>
|ArrayType, Arr
|-
|<code>Index</code>
|IndexType
|-
|<code>Prob</code>
|Probabilistic, ProbType, Uncertain
|-
|<code>Sample</code>
|Samp, SampType, SampleType
|-
|<code>Mid</code>
|Determ, DetermType, DetermMode, MidMode
|-
|<code>Context</code>
|Expr, ContextType
|-
|<code>Unevaluated</code>
|Expression
|-
|<code>ContextSample</code>
|ContextSamp, MaybeSamp, MaybeSample
|-
|<code>Variable</code>
|VariableType, Var, VarType
|-
|<code>VariableList</code>
|VarList, Variable List, List of Variable
|-
|<code>Atom</code>
|Atomic, AtomicType, AtomType
|-
|<code>Scalar</code>
|ScalarType, Scalars
|-
|<code>Vector</code>
|VectorType
|-
|<code>List</code>
|ListType
|-
|<code>Number</code>
|Numeric, Numbers, NumberType, NumericType, Num, Real, Boolean
|-
|<code>Text</code>
|Textual, TexType, TextType
|-
|<code>Reference</code>
|Ref, RefType, ReferenceType
|-
|<code>NonNegative</code>
|PositiveOrZero, NotNegative
|-
|<code>Coerce</code>
|Coerced
|-
|<code>Optional</code>
|opt
|}
:

==See Also==
* [[Parameter qualifiers]]
* [[ParameterEnumeration]]
* [[Function calls and parameters]]
* [[Repeated Parameter Forwarding]]
* [[User-Defined Functions]]
* [[User-defined Functions and Libraries]]
* [[Class]]

Box Plots

2019-02-01T19:57:07Z

KMullins:

[[Category: Graphs]]

__TOC__

Using [[What's new in Analytica 5.2?|Analytica 5.2]] or later versions, users can create box-whisker plots using the [[OnGraphDraw]] attribute and the set of [[Drawing images|relevant drawing functions]]. The following is an example of a box-whisker plot created using the new functionality:

<center>[[image:OnGraphDraw_TukeyBands.png|400px]]</center>

Users of previous versions may use probability bands, as described below, to communicate similar information.

A classical box-whisker plot is one that looks like this:

:[[image:Classic-box-wisker.png]]

The whisker-ends usually represent either the min and max range of data, or the 10% and 90% fractiles. The top and bottom of the box denotes the 25% and 75% quartiles, with the middle line being the median.

Analytica's probability bands graph is used to depict the same type information, but in a different format:

:[[image:ProbBands-plot.png]]

As a substitute for a box-whisker plot, you can consider a "box-box-box plot":

:[[image:box-box-box-plot.png]]

Or, in the other direction, a whisker-whisker-whisker plot:

:[[image:whisker-whisker-whisker-plot.png]]

While the topmost box-whisker plot is not currently available in Analytica 4.4, all three of the other variations are possible using Analytica's graphing engine. All three plots depict the same information.

The examples in this article are contained in the [[media:Box-like-plots.ana|Box-like-plots.ana]] model, which you can download and play with.

== Probability Bands Plot ==

The probability bands plot is immediate in the result view when viewing an uncertain quantity that has at least one other dimension (usually a time dimension). Just select the ProbBands view in the top-left corner of the result view.

:[[image:ProbBands-select.png]]

== Box-Box-Box plots ==

To obtain a box-box-box plot, select a [[ProbBands]] result view, then double click to change the chart type settings. Select a bar chart, check the "Variable origin", and uncheck "Swap horizontal and vertical".

:[[image:Box-box-box-graphSetup.png]]

Next, press ''Ctrl+U'' ([[Uncertainty Setup dialog]]) and select the probability levels of interest:

:[[image:Box-box-box-probability-levels.png]]

Finally, ensure your horizontal axis is your time index, Key is Probability, and then for [[Bar Origin]] select ''Probability = 0'' (or your lowest selected fractile):

:[[image:Box-box-box-plot.png]]

== Whisker-Whisker-Whisker plots ==

The Whisker-whisker-whisker plot is sometimes a little tricky to get right. Once again, display the [[ProbBands]] view. You must add your Time in as a comparison index, even though it already appears as a pivoter index. This enables the use of an XY graph with more flexible control over which series of points are connected by lines (the running index).

:[[image:Whisker-XY-setting.png]]

You need to use a line-symbol chart type, and select '''Use Separate color / symbol keys''':

:[[image:Whisker-ChartType-setting.png]]

With this, you can now pivot as shown in the next final image to obtain the final graph:

:[[image:Whisker-whisker-whisker-plot.png]]

==See Also==
* [[media:Box-like-plots.ana|Box-like-plots.ana]]
* [[Graph settings]]
* [[Tornado Plots]]
* [[Bar Origin]]
* [[Statistical_Functions_and_Importance_Weighting#ProbBands|ProbBands]]

Box Plots

2019-02-01T19:50:58Z

KMullins: Added a link to the new 5.2 OnGraphDraw attribute and drawing functions. This should be expanded to include code on how to produce the example plot.

[[Category: Graphs]]

__TOC__

Using [[What's new in Analytica 5.2?|Analytica 5.2]] or later versions, users can create box-whisker plots using the [[OnGraphDraw]] attribute and the set of [[Drawing images|relevant drawing functions]]. The following is an example of a box-whisker plot created using the new functionality:

:[[image:OnGraphDraw_TukeyBands.png]]

Users of previous versions may use probability bands, as described below, to communicate similar information.

A classical box-whisker plot is one that looks like this:

:[[image:Classic-box-wisker.png]]

The whisker-ends usually represent either the min and max range of data, or the 10% and 90% fractiles. The top and bottom of the box denotes the 25% and 75% quartiles, with the middle line being the median.

Analytica's probability bands graph is used to depict the same type information, but in a different format:

:[[image:ProbBands-plot.png]]

As a substitute for a box-whisker plot, you can consider a "box-box-box plot":

:[[image:box-box-box-plot.png]]

Or, in the other direction, a whisker-whisker-whisker plot:

:[[image:whisker-whisker-whisker-plot.png]]

While the topmost box-whisker plot is not currently available in Analytica 4.4, all three of the other variations are possible using Analytica's graphing engine. All three plots depict the same information.

The examples in this article are contained in the [[media:Box-like-plots.ana|Box-like-plots.ana]] model, which you can download and play with.

== Probability Bands Plot ==

The probability bands plot is immediate in the result view when viewing an uncertain quantity that has at least one other dimension (usually a time dimension). Just select the ProbBands view in the top-left corner of the result view.

:[[image:ProbBands-select.png]]

== Box-Box-Box plots ==

To obtain a box-box-box plot, select a [[ProbBands]] result view, then double click to change the chart type settings. Select a bar chart, check the "Variable origin", and uncheck "Swap horizontal and vertical".

:[[image:Box-box-box-graphSetup.png]]

Next, press ''Ctrl+U'' ([[Uncertainty Setup dialog]]) and select the probability levels of interest:

:[[image:Box-box-box-probability-levels.png]]

Finally, ensure your horizontal axis is your time index, Key is Probability, and then for [[Bar Origin]] select ''Probability = 0'' (or your lowest selected fractile):

:[[image:Box-box-box-plot.png]]

== Whisker-Whisker-Whisker plots ==

The Whisker-whisker-whisker plot is sometimes a little tricky to get right. Once again, display the [[ProbBands]] view. You must add your Time in as a comparison index, even though it already appears as a pivoter index. This enables the use of an XY graph with more flexible control over which series of points are connected by lines (the running index).

:[[image:Whisker-XY-setting.png]]

You need to use a line-symbol chart type, and select '''Use Separate color / symbol keys''':

:[[image:Whisker-ChartType-setting.png]]

With this, you can now pivot as shown in the next final image to obtain the final graph:

:[[image:Whisker-whisker-whisker-plot.png]]

==See Also==
* [[media:Box-like-plots.ana|Box-like-plots.ana]]
* [[Graph settings]]
* [[Tornado Plots]]
* [[Bar Origin]]
* [[Statistical_Functions_and_Importance_Weighting#ProbBands|ProbBands]]

Archived webinars

2018-11-08T18:57:56Z

KMullins: Added link to the good tutorial videos page, since this is the first search return for me when I search 'webinars'

[[Category: Videos]]

Old webinars and videos that are out of date or recordings of poor quality. Visit the [[Tutorial videos]] page for the complete list of past webinars.

=== New Features in [[Analytica 4.4]] ===

'''Date and Time:''' 19 Jan 2012 10:00am Pacific Standard Time

'''Presenter''': Lonnie Chrisman, Lumina Decision Systems

'''Abstract'''

I will give a rapid overview of enhancements and changes in [[Analytica 4.4]] and what these mean for people upgrading from Analytica 4.3.
I'll give quick demonstrations of Expression Assist, Publish to [[ACP|Cloud]], Kernel density smoothing, adjusting legacy models for Clear Type font, Help balloons, and dozens of small improvements that you'll find listed at [[What's new in Analytica 4.4?]]. I'll include a few hidden gems. In following weeks,
we will follow up with more in-depth webinars on specific items.

Watch a recording of this webinar from [http://AnalyticaOnline.com/WebinarArchive/2012-01-19-New-In-Analytica-4.4.wmv New In Analytica 4.4.wmv]

=== Analytica Web Player ===

'''Date and Time:''' Thursday, August 7, 2008, 10:00am Pacific Daylight Time

'''Presenter:''' Max Henrion, Lumina Decision Systems

The Analytica Web Player (AWP) is scheduled to launch on July 31, 2008. AWP is a subscription service hosted on Lumina's servers. As a subscriber, you can upload your models to the server and send your colleagues a URL so that they can view your model. To view your models, they need only a Flash-enabled web browser. They can browser your model, change inputs, and evaluate results, all from within their web browser.

In this talk we'll cover the available subscription plans, pricing, limitations, and how you sign up. We'll also demonstrate the process of uploading models and sharing these with colleagues.

You can watch a recording of this webinar at [http://AnalyticaOnline.com/WebinarArchive/2008-08-07-AWP.wmv AWP.wmv].

=== Manipulating Indexes and Arrays in Analytica Expressions ===

Demonstrates common operations applied to indexes and arrays from within Analytica expressions, including the powerful [[Subscript]] and [[Slice]] operations, [[Associative_vs._Positional_Indexing|duality of associational and positional indexing]], including @I, A[@I=n], and @[I=n] operations. Explains the distinction between index and value contexts in expressions, along with the distinction between a variable's index value, mid value and sample value, [[Self-Indexed Arrays]]. Explains slice assignment -- the ability to assign values to individual slices of an array within an algorithm.

Audience: Moderate to advanced Analytica users.

Watch [[media:Indexes and Arrays UG2.ANA | "Indexes and Arrays UG2.ANA"]]. (This wouldn't be very interesting for someone who didn't attend, but it contains the examples we tried).

'''Missing the link to video file.'''

<b>Presented by:</b> Lonnie Chrisman, CTO, Lumina Decision Systems on Aug 9, 2007.

Example Models

2018-10-30T20:20:42Z

KMullins: Changed PV video link to YouTube rather than Camtasia embedded video player. Thought: driving traffic to our YouTube page is desirable.

[[Category: Models]]
[[category:Doc Status D]]

You may find these example Analytica models useful to see what Analytica can do, and as inspiration or a starting point for your own models. They cover a wide variety of topics and techniques.

These examples supplement the example models that are [[Example Models and Libraries |installed with Analytica]] into the Examples folder.

You can are also invited to contribute your own models as examples. For how to do that, see [[Uploading Example Models]].

__TOC__

==Business Examples==

=== Marginal Abatement Graph ===

:[[image:Marginal abatement heating energy.png]]

This model, along with [http://blog.lumina.com/2015/marginal-abatement/ the accompanying blog article], show how to set up a Marginal Abatement graph in Analytica.

'''Keywords''': Graph methods, carbon price, energy efficiency, climate policy, optimal allocation, budget constraint.

'''Author:''' Lonnie Chrisman

'''Download:''' [[media:Marginal abatement home heating.ana|Marginal abatement home heating.ana]]

=== Solar Panel Analysis ===

:[[image:Solar Panel Analysis.png]]

'''Description:''' Would it be cost effective to install solar panels on the roof of my house? This model explores this question for my situation in San Jose, California. [https://www.youtube.com/watch?v=vhSor_fPIsI An accompanying video] documents the building of this model, and is a good example of the process one goes through when building any decision model.

The model explores how many panels I should install, and what the payoff is in terms of [[NPV|net present value]], [[IRR|Internal rate of return]] and time to recoup cost. It also looks at whether I should postpone the start of the installation to take advantage of rapidly falling PV prices, or cash in on tax credits.

'''Keywords''': Renewable energy, photovoltaics, net present value, internal rate of return, tax credits, agile modeling.

'''Author:''' Lonnie Chrisman

'''Download:''' [[media:Solar Panel Analysis.ana|Solar Panel Analysis.ana]]

=== Items within Budget function ===

'''Description:''' Given a set of items, with a priority and a cost for each, the function Items_within_budget function selects out the highest priority items that fit within the fixed budget.

'''Keywords:'''

'''Author:''' Max Henrion

'''Download''': [[Media:Items_within_budget.ana|Items within budget.ana]]

=== Grant Exclusion Model ===

'''Description:''' This model tests a hypothesis about the distribution of an attribute of the marginal rejectee of a grant program, given the relevance of that attribute to award of the grant. It could be used by an organization to make decisions as to whether to fiscally-sponsor another organization that will use that fiscal sponsorship to apply for grants, by looking at the effect on the pool of grant recipients overall.

'''Keywords:''' Business analysis

'''Download''': [[Media:Grant_exclusion.ANA|Grant exclusion.ana]]

=== Project Planner ===

:[[Image: Project planner model.png |500px]]

'''Description:''' This is a demo model that shows how to:
* Evaluate a set of R&D projects, including uncertain R&D costs, and uncertain revenues if it leads to release of a commercial product.
* Use multiattribute analysis to compare projects, including a hard attribute -- expected net present value -- and soft attributes -- strategic fit, staff development, and public good will.
* Compare cost, [[NPV]], and multiattribute value for a selected portfolio of projects.
* Generate the best portfolio (ratio of NPV or multiattribute merit to cost) given a R&D budget.

The model linked here is only a test, and to an older version: [[File:Project_priorities_2007_4.0.ANA]]

'''Keywords:''' Business models, cost analysis, net present value (NPV), uncertainty analysis

'''Download:''' [[Media:Project Priorities 5 0.ana|Project Priorities 5 0.ana]]

=== Steel and Aluminum import tariff impact on US trade deficit ===

<center>[[Image:Steel and aluminum tariff model diagram.png|400px]]</center>

'''Description:''' On 2-March-2018, President Trump proposed new import tariffs on steel and aluminum. It seems as if the projected net impacts of these tariffs on the total US trade deficit and US economy depends largely on which news outlets you get your news from. We thought it would be helpful to put together a simple and easy to understand model to estimate of the net impact of these tariffs on the US trade deficit, assuming that no other factors change (e.g., no retaliatory tariffs are enacted by other countries). We wanted something that allows you to understand how its estimates are being derived, with assumptions that can be easily replaced with your own, so that the model itself would be impartial to any particular viewpoint. We want the uncertainties that are inherent in such a simple model to be explicit, so you can see the range of possibilities and not just a single guess. Finally, we wanted the model to be easy to understand fully for non-economists (a group to which we belong, too).

This model accompanied a current event blog post on the Lumina blog: [http://lumina.com/blog/impact-of-trumps-proposed-steel-aluminum-tariffs-on-us-trade-deficit Impact of Trump’s proposed Steel & Aluminum tariffs on US trade deficit]

'''Authors:''' Kimberley Mullins and Lonnie Chrisman, Lumina Decision Systems

'''Download:''' [[Media:Steel and aluminum tariff model.ana|Steel and aluminum tariff model.ana]]

=== Tax bracket interpolation ===

<center>[[Image:Tax bracket interpolation.png]]</center>

'''Description:''' Computes amount of tax due from taxable income for a 2017 US Federal tax return. To match the IRS's numbers exactly, it is necessary to process tax brackets correctly as well as implementation a complex mix of rounding rules that reproduce the 12 pages of table lookups from the Form 1040 instructions. This model is showcased in a blog article, [http://Lumina.com/blog/how-to-simplify-the-irs-tax-tables How to simplify the IRS Tax Tables].

'''Author:''' Lonnie Chrisman, Lumina Decision Systems

'''Download:''' [[Media: Tax bracket interpolation.ana|Tax bracket interpolation.ana]]

==Data Analysis==

=== Sampling from only feasible points ===

'''Description:''' You have a bunch of chance variables, each with a probability distribution. Their joint sample, however, contains some combinations of points that are (for one reason or another) physically impossible. We'll call those infeasible points. You'd like to eliminate those points from the sample and keep only the feasible points.

This module implements a button that will sample a collection of chance variables, then reset the sample size and keep only those sample points that are "feasible".

Obviously, this approach will work best when most of your samples are feasible. If you can handle the "infeasible" points in your model directly, by conditioning certain chance variables on others, that is far preferable. But there are some cases where this solution (although a bit of a kludge) is more convenient.

The instructions for how to use this are in the module description field.

'''Keywords''': Statistics, sampling, Importance sampling, feasibility, Monte Carlo simulation

'''Author:''' Lonnie Chrisman

'''Download''': [[Media:Feasible_Sampler.ana|Feasible Sampler.ana]]

=== Cross-Validation / Fitting Kernel Functions to Data ===

:[[image:Cross-validated data fit.jpg]]

'''Description:''' When fitting a function to data, if you have too many free parameters relative to the number of points in your data set, you may "overfit" the data. When this happens, the fit to your training data may be very good, but the fit to new data points (beyond those used for training) may be very poor.

Cross-validation is a common technique to deal with this problem: We set aside a fraction of the available data as a cross-validation set. Then we begin by fitting very simple functions to the data (with few free parameters), successively increasing the number of free parameters, and seeing how the predictive performance changes on the cross-validation set. It is typical to see improvement on the cross-validation set for a while, followed by a deterioration of predictive performance on the cross-validation set once overfitting starts occurring.

This example model successively fits a non-linear kernel function to the residual error, and uses cross-validation to determine how many kernel functions should be used.

Requires Analytica Optimizer: The kernel fitting function (Kern_Fit) uses [[NlpDefine]].

'''Keywords:''' Cross-validation, overfitting, non-linear kernel functions

'''Author:''' Lonnie Chrisman

'''Download:''' [[media:Cross-validation example.ana|Cross-validation example.ana]]

=== Statistical Bootstrapping ===

'''Description:''' Bootstrapping is a technique from statistics for estimating the sampling error present in a statistical estimator. The simplest version estimates sampling error by resampling the original data. This model demonstrates how to do this in Analytica.

'''Keywords:''' Bootstrapping, sampling error, re-sampling

'''Download:''' [[media:Bootstrapping.ana|Bootstrapping.ana]]

=== Smooth PDF plots using Kernel Density Estimation ===

:{| border="0"
| [[image:Dens_Est_builtin_pdf.png|frame|Analytica's built-in PDF plot with default settings]]
|
[[image:Dens_Est_Kernel_pdf.png|frame|PDF computed from Kernel Density estimation]]
|}

'''Description:''' This example demonstrates a very simple fixed-width kernel density estimator to estimate a "smooth" probability density. The built-in PDF function in Analytica often has a choppy appearance due to the nature of histogramming -- it sets up a set of bins and counts how many points land in each bin. A kernel density estimator smooths this out, producing a less choppy PDF plot.

This smoothing is built into [[Analytica 4.4]]. You can select [[Kernel Density Smoothing|smoothing]] from the [[Uncertainty Setup dialog]].

'''Keywords:''' Kernel density estimation, kernel density smoothing

'''Author:''' D. Rice, Lumina Decision Systems

'''Download:''' [[media:Kernel_Density_Estimation.ana|Kernel Density Estimation.ana]]

=== Output and Input Columns in Same Table ===

:[[image:Output and input columns.png]]

'''Description:''' Presents an input table to a user, where one column is populated with computed output data, the other column with checkboxes for the user to select. Although the '''Output Data''' column isn't read only, as would be desired, a [[Check Attribute]] has been configured to complain if he does try to change values in that column. The model that uses these inputs would ignore any changes he makes to data in the '''Output Data''' column.

Populating the '''Output Data''' column requires the user to press a button, which runs a button script to populate that column. This button is presented on the top-level panel. If you change the input value, the output data will change, and then the button needs to be pressed to refresh the output data column.

'''Keywords:''' Data analysis

'''Author:''' D. Rice, Lumina Decision Systems

'''Download:''' [[media:Output and input columns.ana|Output and input columns.ana]]

==Decision Analysis==

=== Retirement plan type comparison ===

<center>[[image:Comparing retirement account types.png|500px]]</center>

'''Description:''' Will you end up with a bigger nest egg at retirement with a 401(k), traditional IRA, Roth IRA or a normal non-tax-advantaged brokerage account? For example, comparing a Roth IRA to a normal brokerage, intermediate capital gains compound in the Roth, but eventually you pay taxes on those gains at your income tax rate at retirement, whereas in the brokerage you pay capital gains taxes on the gains, which is likely a lower tax rate. So does the compounding outweigh the tax rate difference? What effect do the higher account maintenance fees in a 401(k) account have? How sensitive are these conclusions to the various input estimates? The answers to all these questions depend on your own situation, and may different for someone else. Explore these questions with this model.

'''Keywords:''' 401(k), IRA, retirement account, decision analysis, uncertainty, sensitivity analysis, [[MultiTable]]s.

'''Author:''' Lonnie Chrisman, Lumina Decision Systems

'''Download:''' [[media:Comparing retirement account types.ana|Comparing retirement account types.ana]].
::For a version without the sensitivity analysis part, which has fewer than 100 object and can thus be modified using [http://lumina.com/products/free101/ Analytica Free 101], you can use this one: [[media:Comparing retirement account types without sensitivity.ana|Comparing retirement account types without sensitivity.ana]].

=== Plane Catching Decision with Expected Value of Including Uncertainty ===

'''Description:''' A simple model to assess what time I should leave my home to catch a plane, with uncertain driving time, walking from parking to gate (including security), and how long I need to be at the gate ahead of scheduled departure time. It uses a loss model based on minutes, assuming I value each extra minute snoozing in bed and set the loss if I miss the plane to 400 of those minutes.

It illustrates the EVIU (expected value of including uncertainty) i.e. the difference in expected value if I make a decision to minimize expected loss instead of decision to minimize time ignoring uncertainty (assuming each distribution is fixed at its mid value). For more details see "The Value of Knowing How Little You Know", Max Henrion, PhD Dissertation, Carnegie Mellon University, 1982.

'''Keywords''': Decision theory, decision analysis, uncertainty, Monte Carlo simulation, value of information, EVPI, EVIU.

'''Author:''' Max Henrion

'''Download:''' [[media:Plane catching decision with EVIU.ana|Plane catching decision with EVIU.ana]]

=== Marginal Analysis for Control of SO<sub>2</sub> emissions ===

'''Description:''' Acid rain in eastern US and Canada caused by sulfur dioxide is emitted primarily by coal-burning electric-generating plants in the Midwestern U.S. This model demonstrates a marginal analysis a.k.a. benefit/cost analysis to determine the policy alternative that leads us to the most economically efficient level of cleanup.

'''Keywords:''' Environmental engineering, cost-benefit analysis, marginal analysis

'''Author:''' Surya Swamy

'''Download:''' [[media:Marginal Analysis for Control of SO2 Emissions.ana|Marginal Analysis for Control of SO2 Emissions.ana]]

==Dynamic Models==

=== Donor/Presenter Dashboard ===

'''Description:''' This model implements a continuous-time Markov chain in Analytica's discrete-time dynamic simulation environment. It supports immigration to, and emigration from, every node.

It can be used by an arts organization to probabilistically forecast future audience evolution, in both the short and the long (steady state) term. It also allows for uncertainty in the input parameters.

'''Keywords:''' Dynamic models, Markov processes

'''Download:''' [[Media:Donor_Presenter_Dashboard_II.ANA|Donor-Presenter Dashboard.ana]]

=== Regulation of Photosynthesis ===

:[[image:Photosynthesis fluorescence.jpg]]

A model of how photosynthesis is regulated inside a cyanobacteria. As light exposure varies over time (and you can experiment with various light intensity waveforms), it simulates the concentration levels of key transport molecules along the chain, through the PSII complex, plasto-quinone pool, PSI complex, down to metabolic oxidation. The dynamic response to light levels, or changes in light levels, over time becomes evident, and the impact of changes to metabolic demand can also be observed. In the graph of fluorescence above, we can see an indicator of how much energy is being absorbed, in three different cases (different light intensities). In the two higher intensity cases, photoinhibition is observed -- a protective mechanism of the cell that engages when more energy is coming in than can be utilized by the cell. Excess incoming energy, in the absence of photoinhibition, causes damage, particularly to the PSII complex.

This model uses node shapes for a different purpose than is normally seen in decision analysis models. In this model, ovals, instead of depicting chance variables, depict chemical reactions, where the value depicts the reaction rate, and rounded rectangles depict chemical concentrations.

Two models are attached. The first is a bit cleaner, and focused on the core transport chain, as described above. The second is less developed, but is focused more on genetic regulation processes.

'''Keywords:''' Photosynthesis, dynamic models

'''Author:''' Lonnie Chrisman

'''Download:'''
* [[media:Photosynthesis regulation.ANA|Photosynthesis Regulation.ana]] - main regulation pathways
* [[media:Photosystem.ana | Photosystem.ana]] - rough sketch of genetic regulation.

=== Time-series re-indexing ===

:[[image:Weekly_data_graph_ex.png]]

'''Description:''' This model contains some examples of time-series re-indexing. It is intended to demonstrate some of these basic techniques.

In this example, actual measurements were collected at non-uniform time increments. Before analyzing these, we map these to a uniformly spaced time index (<code>Week</code>), occurring on Monday of each week. The mapping is done using an interpolation. The evenly-spaced data is then used to forecast future behavior. We first forecast over an index containing only future time points (<code>Future_weeks</code>), using a log-normal process model based on the historical weekly change. We then combine the historical data with the forecast on a common index (<code>Week</code>). A prob-bands graph of the weekly_data result shows the range of uncertainty projected by the process model (you'll notice the uncertainty exists only for future forecasted values, not historical ones).

'''Keywords:''' Dynamic models, forecasting, time-series re-indexing

'''Author:''' Lonnie Chrisman

'''Download:''' [[media:Time-series-reindexing.ana|Time-series-reindexing.ana]]

==Engineering Examples==

=== Timber Post Compression Load Capacity ===

'''Description:''' Here is a calculator for computing the maximum load that can be handled by a Douglas Fir - Larch post of a given size, grade, and composition in a construction setting.

'''Keywords:'''

'''Author:''' Lonnie Chrisman

'''Download:''' [[Media:PostCompression.ana|Post Compression Model]]

=== Compression Post Load Calculator ===

'''Description:''' Computes the load that a Douglas-Fir Larch post can support in compression. Works for different timber types and grades and post sizes.

'''Keywords:''' Compression analysis

'''Author:''' Lonnie Chrisman

'''Download:''' [[media:Compression_Post_Load_Capacity.ana|Compression Post Load Capacity.ana]]

=== Daylighting Options in Building Design ===

:[[File:Chapter_9.7-updated.png]]

'''Description:''' A demonstration showing how to analyze lifecycle costs and savings from daylighting options in building design.

Analysis based on Nomograph Cost/Benefit Tool for Daylighting. adapted from S.E. Selkowitz and M. Gabel. 1984. "LBL Daylighting Nomographs," LBL-13534, Lawrence Berkeley Laboratory, Berkeley CA, 94704. (510) 486-6845.

'''Keywords:''' Engineering, cost-benefits analysis

'''Author:''' Max Henrion

'''Download:''' [[media:Daylighting analyzer.ana|Daylighting analyzer.ana]]

=== California Power Plants ===

'''Description:''' An example showing how to use Choice menus and Checkbox inside an Edit table. It also shows how to use the Cell default attribute to specify default values (including Choice menu and Checkbox with default selections) specified in "Default Plant Data" to be used when user creates a new row in the Edit table. This model shows how to demonstrates the use of [[Choice|choice pulldowns]] in edit tables. The model is created during a mini-tutorial on [[Inserting Choice Controls in Edit Table Cells]] elsewhere on this Wiki.

'''Keywords:''' Edit table, Choice menu, pulldown menu, checkbox, Power plants.

'''Download:''' [[Media:California_Power_Plants.ANA|California Power Plants.ana ]]

=== Electrical Generation and Transmission ===

'''Description:''' This model of an electrical network minimizes total cost of generation and transmission. Each node in the network has power generators and consumers (demand). Nodes are connected by transmission links. Each link has a maximum capacity in Watts and an admittance (the real part of impedance is assumed to be zero). Each generator has a min and max power and a marginal cost in $/KWh. The model uses a linear program to determine how much power each generator should produce so as to minimize total cost of generation and transmission, while satisfying demand and remaining within link constraints.

''Requires Analytica Optimizer''

'''Keywords:''' Electrical engineering, power generation and transmission

'''Author:''' Lonnie Chrisman

'''Download:''' [[media:Electrical Transmission.ana|Electrical Transmission.ana]]

==Fun and Games==

=== Color Map ===

:[[File:Color_map.gif]]

'''Description:''' A model which highlights [[Cell Format Expression|Cell Formatting]] and [[Computed cell formats|Computed Cell Formats]]. Model result is a 'color map' wherein the cell fill color is computed based on three input variables (R, G, and B), the computed color is displayed in hexadecimal, and the font color of the hexadecimal color is determined by the cell fill color.

'''Keywords:''' Computed cell formatting

'''Author:''' Kimberley Mullins, Lumina Decision Systems

'''Download:''' [[media:color_map.ana|Color map.ana]]

=== 2018 World Cup Soccer final ===

'''Download:''' [[Media:World cup.ana|World cup.ana]]

'''Description:''' On July 15, 2018, France beat Croatia 4-2 in the final game of the World Cup to become world champions. But how much of that is can be attributed to France being the better team versus to the random chance? This model accompanies my blog article, [http://lumina.com/blog/world-cup-soccer.-how-much-does-randomness-determine-the-winner World Cup Soccer. How much does randomness determine the winner?], where I explore this question and use the example to demonstrate the [[Poisson|Poisson distribution]].

'''Author:''' Lonnie Chrisman, Lumina Decision Systems

=== Image recognition ===

'''Download: ''' [http://AnalyticaOnline.com/Lonnie/resnet18.zip resnet18.zip]

'''Description:''' Show it an image, and it tries to recognize what it is an image of, classifying it among 1000 possible categories. It uses an 18-layer residual network. This model is described and demonstrated in a video in the blog article [http://lumina.com/blog/an-analytica-model-that-recognizes-images An Analytica model that recognizes images].

'''Author:''' Lonnie Chrisman, Lumina Decision Systems. (Analytica implementation). Residual network developed by
* Kaiming He, Xiangyu Zhang, Shaoqing Ren, Jian Sun, "Deep Residual Learning for Image Recognition", https://arxiv.org/abs/1512.03385 rXiv:1512.03385]

==Function Examples==

=== Transforming Dimensions by transform matrix, month to quarter ===

'''Description:''' The model shows how to transform an array from a finer-grain index (e.g., Month) onto a coarser index (e.g., Quarter). We generally refer to this as [[Aggregate|aggregation]]. The model illustrates the direct use of [[Aggregate]], as well as a method to do this used before Aggregate was added to Analytica in release 4.2.

'''Webinar:''' [[Analytica_User_Group/Past_Topics#The_Aggregate_Function|the Aggregate function]].

'''Keywords''': Aggregation, level of detail, days, weeks, months, quarters, years.

'''Author:''' Lonnie Chrisman

'''Download:''' [[Media:Month to quarter.ana|Month to quarter.ana]]

=== Convolution ===

'''Description:''' Convolution is used mostly for signal and systems analysis. It is a way to combine two time series. This model contains function Convolve(Y, Z, T, I), that computes the convolution of two time series. The model contains several examples of convolved functions.

A time series is a set of points, <code>(Y, T)</code>, where <code>T</code> is the ascending X-axis, and the set of points is indexed by <code>I</code>. The values of <code>T</code> do not have to be equally spaced. The function treats <code>Y</code> and <code>Z</code> as being equal to 0 outside the range of <code>T</code>. The two time series here are the set of points <code>(Y, T)</code> and the set of points <code>(Z, T)</code>, where both sets of points are indexed by <code>I</code>.

The mathematical definition of the convolution of two time series is the function given by:

:<math>h(t) = \int y(u) z(t-u) dt</math>

'''Keywords:''' Signal analysis, systems analysis

'''Author:''' Lonnie Chrisman

'''Download''': [[Media:Convolution.ana|Convolution.ana]]

=== Dependency Tracker Module ===

:[[image:Dependency tracker.jpg]]

'''Description:''' This module tracks dependencies through your model, updating the visual appearance of nodes so that you can quickly visualize the paths by which one variable influences another. You can also use it to provide a visual indication of which nodes are downstream (or upstream) from an indicated variable.

The module contains button scripts that change the bevel appearance of nodes in your model. To see how Variable <code>X</code> influences Variable <code>Y</code>, the script will bevel the nodes for all variables that are influenced by <code>X</code> and influence <code>Y</code>. Alternatively, you can bevel all nodes that are influenced by <code>X</code>, or you can bevel all nodes that influence <code>Y</code>.

In the image above, the path from <code>dp_ex_2</code> through <code>dp_ex_4</code> has been highlighted using the bevel style of the nodes. (The result of pressing the "Bevel all from Ancestor to Descendant" button)

'''Keywords:''' Dependency analysis

'''Download:''' [[media:Dependency_Tracker.ANA | Dependency Tracker.ana]]

=== Multi-lingual Influence Diagram ===

:{| border="0"
| [[Image:English-view.png]]
| [[Image:French-view.png]]
|}

'''Description:''' Maintains a single influence diagram with Title and Description attributes in both English and French. With the change of a pull-down, the influence diagram and all object descriptions are instantly reflected in the language of choice.

If you change a title or description while viewing English, and then change to French, the change you made will become the English-language version of the description. Similarly if you make a change while viewing French.

'''Keywords:''' Multi-lingual models

'''Author:''' D. Rice, Lumina Decision Systems

'''Download:''' [[media:French-English.ana|French-English.ana]]

=== Extracting Data from an XML file ===

'''Description:''' Suppose you receive data in an XML format that you want to read into your model. This example demonstrates two methods for extracting data: Using a full XML DOM parser, or using regular expressions. The first method fully parses the XML structure, the second simply finds the data of interest by matching patterns, which can be easier for very simple data structures (as is often the case).

'''Keywords:''' Data extraction, xml, DOM parsing

'''Author:''' D. Rice, Lumina Decision Systems

'''Download:''' [[media:Parsing XML example.ana|Parsing XML example.ana]]

=== Vector Math ===

'''Description:'''
Functions used for computing geospatial coordinates and distances. Includes:
* A cross product of vectors function
* Functions to conversion between spherical and Cartesian coordinates in 3-D
* Functions to compute bearings from one latitude-longitude point to another
* Functions for finding distance between two latitude-longitude points along the great circle.
* Functions for finding the intersection of two great circles

'''Keywords:''' Geospatial analysis, GIS, vector analysis

'''Author:''' Robert D. Brown III, Incite Decision Technologies, LLC

'''Download:''' [[media:Vector Math.ana|Vector Math.ana]]

==Optimizer Examples==

=== Total Allowable Harvest ===

'''Description:''' The problem applies to any population of fish or animal whose dynamics are poorly known but can be summarized in a simple model:

:<code>N_t + 1 = N_t*Lambda - landed catch*(1 + loss rate)</code>

where «N_t» is the population size (number of individuals) at time ''t'', «N_t+1» is the population size at time ''t + 1'', «Lambda» is the intrinsic rate of increase and the «loss rate» is the percentage of fish or animals killed but not retrieved relative to the «landed catch», or catch secured.

The question here is to determine how many fish or animals can be caught (landed) annually so that the probability of the population declining X% in Y years (decline threshold) is less than Z% (risk tolerance).

Two models are available for download. One uses the Optimizer ([[NlpDefine]]) to find the maximum landed catch at the risk tolerance level for the given decline threshold. The other (for those using a version of Analytica without Optimizer) uses [[StepInterp]] in an iterative way to get that maximum landed catch.

'''Keywords:''' Population analysis, dynamic models, optimization analysis

'''Author:''' Models contributed by Pierre Richard

'''Download:'''
* [[media:Total Allowable Removal model with Optimizer.ana | Total Allowable w Optimizer.ana]]
* [[media:Total Allowable Removal model w StepInterp.ana|Total Allowable w StepInterp.ana]]

=== Linearizing a discrete NSP ===

'''Description:''' A cereal formulation model

A discrete mixed integer model that chooses product formulations to minimize total ingredient costs. This could be an NSP but it uses two methods to linearize:
1) Decision variable is constructed as a constrained Boolean array
2) Prices are defined as piecewise linear curves

'''Keywords:''' product formulation, cereal formulation

'''Author:''' P. Sanford, Lumina Decision Systems

'''Download:''' [[media:Cereal Formulation1.ana|Cereal Formulation1.ana]]

=== Neural Network ===

'''Description:''' A feed-forward neural network can be trained (fit to training data) using the Analytica Optimizer. This is essentially an example of non-linear regression. This model contains four sample data sets, and is set up to train a 2-layer feedforward sigmoid network to "learn" the concept represented by the data set(s), and then test how well it does across examples not appearing in the training set.

Developed during the Analytica User Group Webinar of 21-Apr-2011 -- see the [[Analytica_User_Group/Past_Topics#Neural_Networks|webinar recording]].

'''Keywords:''' Feed-forward neural networks, optimization analysis

'''Author:''' Lonnie Chrisman, Lumina Decision Systems

'''Download:''' [[media:Neural-Network.ana|Neural Network.ana]]

==Risk Analysis==

=== Earthquake Expenses ===

'''Description:''' An example of risk analysis with time-dependence and costs shifted over time.

Certain organizations (insurance companies, large companies, governments) incur expenses following earthquakes. This simplified demo model can be used to answer questions such as:
* What is the probability of more than one quake in a specific 10 year period.
* What is the probability that in my time window my costs exceed $X?

Assumptions in this model:
* Earthquakes are Poisson events with mean rate of once every 10 years.
* Damage caused by such quake is lognormally distributed, with mean $10M adn stddev of $6M.
* Cost of damage gets incurred over the period of a year from the date of the quake as equipment is replaced and buildings are repaired over time: 20% in 1st quarter after quake, 50% in 2nd quarter, 20% in 3rd quarter, 10% in 4th quarter.

'''Keywords:''' Risk analysis, cost analysis

'''Download''': [[media:Earthquake expenses.ana|Earthquake expenses.ana]]

=== Loan Policy Selection ===

'''Description:''' A lender has a large pool of money to loan, but needs to decide what credit rating threshold to require and what interest rate (above prime) to charge. The optimal value is determined by market forces (competing lenders) and by the probability that the borrower defaults on the loan, which is a function of the economy and borrower's credit rating. The model can be used without the Analytica optimizer, in which case you can explore the decision space manually or use a parametric analysis to find the near optimal solution. Those with Analytica Optimizer can find the optimal solution (more quickly) using an [[NlpDefine|NLP]] search.

'''Best used with Analytica Optimizer'''

'''Keywords:''' Creditworthiness, credit rating, default risk, risk analysis

'''Author:''' Lonnie Chrisman

'''Download:''' [[media:Loan policy selection.ANA|Loan policy selection.ana]]

=== Inherent and Residual Risk Simulation ===

:[[File:Prob of Exceeding Loss.png]]

'''Description:''' The model simulates loss exceedance curves for a set of cybersecurity events, the likelihood and probabilistic monetary impact of which have been characterized by system experts. The goal of the model is assess the impact of mitigation measures, by comparing the residual risk curve to the inherent risk curve (defined as risk without any mitigation measures) and to the risk tolerance curve. This is a translation of a model built by Douglas Hubbard and Richard Seiersen which they describe in their book [https://www.howtomeasureanything.com/cybersecurity/about-the-book/ How to Measure Anything in Cybersecurity Risk], and which they make available [https://www.howtomeasureanything.com/cybersecurity/ here].

'''Keywords:''' Cybersecurity risk, loss exceedance curve, simulation

'''Author:''' Kim Mullins

'''Download:''' [[media:Hubbard and Seiersen cyberrisk.ana|Hubbard_and_Seiersen_cyberrisk.ana]]

== Graphing examples ==
=== Red or blue state ===
[[image:Red_or_blue_state.png|600px]]

'''Download:''' [[media:Red State Blue State plot.ana]]

'''Description:''' This example contains the shape outlines for each of the 50 US states, along with a graph that uses color to depict something that varies by state (historical political party leaning). You may find the shape data useful for your own plots. In addition, it demonstrates the polygon fill feature that is new in [[Analytica 5.2]].

'''Author:''' Lonnie Chrisman, Lumina Decision Systems

==See Also==
* [[New examples]]
* [[Additional libraries]]
* [[Uploading Example Models]]
* [[Example Models and Libraries]]
* [[Using Add Module... to import a Model file]]
* [[Import a module or library]]
* [[Tutorial: Sharing a model with ACP]]
* [[Obfuscated and Browse-Only Models]]
* [[Filed modules and libraries]]
* [[Working with Models, Modules, and Files in ADE]]
* [[Combining models into an integrated model]]
* [[Model file formats]]
* [[Model Licensing]]

Using References

2018-09-10T21:35:49Z

KMullins:

[[category:Concepts]]
[[Category:Doc Status C]] 

== Reference Operator: \A ==

The reference operator returns a reference to the value of «A». «A» is an expression which is evaluated in the current context. «A» reference acts as an [[atomic]] element for [[Array Abstraction|array abstraction]], and can be thought of as a pointer to a value (the value is often array-valued). with the simple syntax, <code>\A</code>, all dimensions of «A» are placed under the reference.

A reference displays in a result table as «ref». You can view the value pointed to by the reference by double-clicking on the cell containing «ref».

== \[I, J]A ==

A list of zero or more indexes can be specified with taking the reference of a value. When indexes are specified, only those dimensions are swallowed by the reference. If there are other dimensions, the result returned will be an array of references. An empty list of references, <code>\[]A</code>, creates pointers to atomic values.

== Dereference Operator: #R ==

When you have a reference (e.g., a pointer to a value), the dereference operator, <code>#R</code>, returns the value pointed to.

The operator has a lower precedence than subscript, so that <code>#R[I = x]</code> is equivalent to <code>#(R[I = x])</code>. In other words, when you have an array of references indexed by <code>I</code>, this is how you get to the thing pointed to by one of those references. If you need to slice the de-referenced value, then use <code>(#R)[I = x]</code>.

When «R» is an array of references, <code>#R</code> will contain the union of all indexes from the de-referenced cells. There are many cases where you want to avoid this, either because the resulting number of dimensions would be huge, or because two or more of the dereferenced values contain an implicit dimension (e.g., list), which would cause an error. Because references are often used to separate items with distinct dimensionality, or to store separate lists, these situations are common for cases where references are used. Thus, you will often need to explicitly loop with [[For..Do]] or other looping constructs, rather than letting array abstraction take care of it for you.

== Comparisons ==

Less-than and greater-than comparisons are not defined for references and always return [[Null]].

Testing equality of references gets a bit tricky, and in general it is a bad practice to rely on equality of references. References are equal only if they point to the exact same data in memory. The value pointed to by two references can be identical while the references are not considered equal. For example:
:<code>\"Hello" = \"Hello" → 0 { they point to two different instances of "Hello" in memory }</code>
:<code>Var..Do|Var s := "Hello" Do (\s = \s) → 1 { Now they point to the same instance in memory }</code>

References to equal numbers, null, or undef do test for equality.
:<code>\1 = \1 → 1</code>
:<code>\Null = \Null → 1</code>

[[Subscript]]ing on a reference does not work in Analytica 4.1 and earlier, even if the references are considered equal by the equality operator. For example, <code>A[J = Slice(J, 1)]</code> will not get the first slice in <code>A</code> when the first element of <code>J</code> is a reference. This is remedied in Analytica 4.2.

== Examples ==

== See also ==
* [[Operators]]
* [[Set Functions]]
* [[References and Data Structures]]

Using References

2018-09-10T21:34:44Z

KMullins: Temporary change to create a new page

[[category:Concepts]]
[[Category:Doc Status C]] 

== Reference Operator: \A ==

The reference operator returns a reference to the value of «A». «A» is an expression which is evaluated in the current context. «A» reference acts as an [[atomic]] element for [[Array Abstraction|array abstraction]], and can be thought of as a pointer to a value (the value is often array-valued). with the simple syntax, <code>\A</code>, all dimensions of «A» are placed under the reference.

A reference displays in a result table as «ref». You can view the value pointed to by the reference by double-clicking on the cell containing «ref».

== \[I, J]A ==

A list of zero or more indexes can be specified with taking the reference of a value. When indexes are specified, only those dimensions are swallowed by the reference. If there are other dimensions, the result returned will be an array of references. An empty list of references, <code>\[]A</code>, creates pointers to atomic values.

== Dereference Operator: #R ==

When you have a reference (e.g., a pointer to a value), the dereference operator, <code>#R</code>, returns the value pointed to.

The operator has a lower precedence than subscript, so that <code>#R[I = x]</code> is equivalent to <code>#(R[I = x])</code>. In other words, when you have an array of references indexed by <code>I</code>, this is how you get to the thing pointed to by one of those references. If you need to slice the de-referenced value, then use <code>(#R)[I = x]</code>.

When «R» is an array of references, <code>#R</code> will contain the union of all indexes from the de-referenced cells. There are many cases where you want to avoid this, either because the resulting number of dimensions would be huge, or because two or more of the dereferenced values contain an implicit dimension (e.g., list), which would cause an error. Because references are often used to separate items with distinct dimensionality, or to store separate lists, these situations are common for cases where references are used. Thus, you will often need to explicitly loop with [[For..Do]] or other looping constructs, rather than letting array abstraction take care of it for you.

== Comparisons ==

Less-than and greater-than comparisons are not defined for references and always return [[Null]].

Testing equality of references gets a bit tricky, and in general it is a bad practice to rely on equality of references. References are equal only if they point to the exact same data in memory. The value pointed to by two references can be identical while the references are not considered equal. For example:
:<code>\"Hello" = \"Hello" → 0 { they point to two different instances of "Hello" in memory }</code>
:<code>Var..Do|Var s := "Hello" Do (\s = \s) → 1 { Now they point to the same instance in memory }</code>

References to equal numbers, null, or undef do test for equality.
:<code>\1 = \1 → 1</code>
:<code>\Null = \Null → 1</code>

[[Subscript]]ing on a reference does not work in Analytica 4.1 and earlier, even if the references are considered equal by the equality operator. For example, <code>A[J = Slice(J, 1)]</code> will not get the first slice in <code>A</code> when the first element of <code>J</code> is a reference. This is remedied in Analytica 4.2.

== Examples ==

[[Change node color example]]

== See also ==
* [[Operators]]
* [[Set Functions]]
* [[References and Data Structures]]

Additional libraries

2018-09-06T18:27:58Z

KMullins:

[[Category:Function libraries]]

__TOC__

This page describes a set of useful Analytica function libraries. These are ''additional'' to the [[Standard libraries]] that are automatically installed when you install Analytica. If you want to use any of these additional libraries, click on its link and it will download onto your computer. Depending on your download settings, it may automatically open it in Analytica. Either way, you should save it into a directory so that you can add it into your models. It's usually most convenient to save it with your [[Standard libraries]] in directory
:<code>c: Lumina/Analytica 4.6/Libraries</code>

You can then easily add it into your models using the standard menu option '''Add Library...''' from the [[File menu]].

See [[User-defined Functions and Libraries]] to build your own functions and libraries.

__TOC__

=== Large Sample Library ===
'''Download:''' [[media:Large_Sample_Library_v10.ana|Large sample library v10.ana]]

:[[image:Large sample library.png]]

The [[Large Sample Library: User Guide|Large Sample Library]] is an Analytica library that lets you run a Monte Carlo simulation for large models or a large sample size that might otherwise exhaust computer memory, including virtual memory. It breaks up a large sample into a series of batch samples, each small enough to run in memory. For selected variables, known as the Large Sample Variables or LSVs, it accumulates the batches into a large sample. You can then view the probability distributions for each LSV using the standard methods — confidence bands, [[PDF]], [[CDF]], etc. — with the full precision of the large sample.

See [[Large Sample Library: User Guide]].

===The Sensitivity Analysis Library===
[[The Sensitivity Analysis Library]] provides functions for analyzing the sensitivity of an output to each cell of each array-valued chance input, and locating those individual scalar inputs that have the greatest impact on the result. See [[The Sensitivity Analysis Library]] for documentation on using this library.

The library itself can be downloaded from [[media:Sensitivity Analysis Library.ana|Sensitivity Analysis Library.ana]], and an example model to demonstrate its usage is at [[media:Sensitivity Functions Examples.ana|Sensitivity Functions Examples.ana]].

=== Model Documentation Library ===
'''Download: ''' [[media:Model Documentation Library.ana|Model Documentation Library.ana]]

'''Prerequisites:''' [[Analytica 5.0]] or later. The [[Preferences_dialog|Domain acts as self index]] legacy preference must be OFF. You must be using [[Diagram_Style_dialog|ClearType text]] (not the very old non-clearType legacy setting).

Some people like to create a concise report on paper that contains all objects in their model along with descriptions or other selected attributes. The "Print Report" feature in Analytica can be used for this purpose, but is not at all concise and ends up placing each object window on a separate page. The ''Model Documentation Library'' allows you to select a module from your model and produce a result table containing every object within that module with its selected attributes such as title, description, units, definition, or user-defined attributes. This table can then be exported to Excel where you can format it nicely and print it. Thus, you can end up with a very concise report on paper.

To use this library, load your model and then select '''File → Add Module...'''. Add the [[media:Model Documentation Library.ana|Model Documentation Library.ana]] module file using Embed. In that module, using the pulldown, select the top-level module for the report. Follow the instructions shown on the diagram. If you make changes to your model later, press the ''Update Model Documentation'' button to adjust the pulldown content.

=== Units Conversion Library ===
'''Download: ''' [[media:Units conversion library.ana|Units conversion library.ana]]

The functions in this library provide conversions between different units -- for example, from feet to kilometers, or from Btu (British thermal units) to gigajoules of energy. Using this library relieves you from having to look up conversion factors. It also makes the model more transparent by making it clear where you are converting from one units to another -- instead of just embedding conversion constants in the formulas.

Use '''Conversion_Factor'''(oldUnits, newUnits) to give a conversion factor between two units.

If you omit «newUnits», it will assume the standard units for that type (dimensions).

When specifying units , you must use a symbol (abbreviation) from the Units table.

If the units are of different dimensions, e.g. energy and power, or if it doesn't recognize the units, it will give an error.

Use '''Nom_to_real_dollars'''(yr, baseYr) to convert from nominal dollars for year «yr» to "real dollars" for specified «baseYr». If you omit «baseYr», it defaults to the Standard base year.

=== Greatest Common Divisor functions ===
'''Download: ''' [[media:GCD function library.ana|GCD function library.ana]]

This library contains two [[User-Defined Functions]] for computing the greatest common divisor.

=== DB Conversion Library ===
'''Download: ''' [[media:Db conversion lib.ana|DB conversion lib.ana]]

Lets you embed data obtained from a database into the Analytica model. This breaks the need to use it with an external database, so -- for example -- you can send to someone (e.g. Lumina tech support) who does not have access to the database or has an edition of Analytica (e.g. Professional) that doesn't support database access.

Press a button in this library to transform all the variables defined using [[DbQuery]], [[DbLabels]] and [[DbTable]] to literal data. Variables and indexes defined using [[DbQuery]] or [[DbLabels]] are transformed to list definitions, and those defined using [[DbTable]] are transformed into edit tables. This breaks the connection to the external database. So, of course, the model will no longer be able to get new or extended data from the database.

The library is limited in its scope. It only works when all calls to [[DbQuery]], [[DbLabels]] and [[DbTable]] occur at the top level of variable definitions. Do not try to use it if the calls to these functions are embedded within larger expressions or in [[User-Defined Functions]].

'''''Use with extreme caution!!''''': Make a copy of your original model ''before'' adding and executing this module. After running the transformation, be sure to use '''File → Save As...''' to save the transformed model under a different filename, so you don't clobber your original model.

=== Spreadsheet Helper Library ===
'''Download: ''' [[media:Spreadsheet Helper lib.ana|Spreadsheet Helper lib.ana]]

Includes functions that return the list of worksheet names and the Excel filename of the workbook. It also contains a SpreadsheetOpenEx function that can be used in place of [[SpreadsheetOpen]], but which remembers the filename selected by the user so the next time they don't have to select the file again.

=== Data Standardization Library ===
'''Download: ''' [[media:Data Standardization Library.ana|Data Standardization Library.ana]]

Imported data is often inconsistent. This library allows you to choose what the "standard" values should be in a column of data. You can then map any non-standard value to one of the standard values. The result is a column of consistent data.

== Individual functions with examples ==

'''Download: ''' [[media:Recumulate example.ana|Recumulate example.ana]] : Like [[Cumulate]], but resets to zero at selected points.

'''Download:''' [[media:Apportion.ana|Apportion.ana]]: Aggregates or disaggregates an array of values from one index to another index, where the second index may be larger or smaller. Does not require the indexes to be index multiples of each other. For example, if you map from a 47-element index to a 13-element index, each 3.62 elements of the original map to an element in the destination, so for example, the first 3 items map to the first item, then the fourth item is shared, with 0.62 apportioned to the first element and 0.38 apportioned to the second element. Supports aggregation types <code>'SUM'</code>, <code>'AVERAGE'</code>, <code>'MIN'</code> and <code>'MAX'</code>. Contributed by Paul Sanford of EPRI.

==See Also==
* [[Standard libraries]]: Installed with Analytica
* [[User Libraries]]: How to create your own Libraries
* [[Example Models]]
* [[Large Sample Library: User Guide]]
* [[Modules and Libraries]]
* [[Filed modules and libraries]]
* [[User-defined Functions and Libraries]]
* [[Example Models and Libraries]]
* [[Financial library functions]]
* [[The Sensitivity Analysis Library]]
* [[Distribution Densities Library]]
* [[Linked list library]]
* [[Base Conversion Function Library]]
* [[Performance Profiler library]]
* [[List of libraries]]

BitShift

2018-08-30T17:26:41Z

KMullins: Added hexadecimal to RGB triplet example.

[[category:Bit functions]]

== BitShift(x, shift'', left, I, rotate, bit'' ) ==

Shifts the bits in an integer value «x» bit «shift» positions to the right, or by «shift» positions to the left when «left» is specified as true. Alternatively, «shift» can be negative to invert the shift direction.

When an array is provided and the index «I» is specified, the bits are shifted to the adjacent cell. Each integer in each cell is considered to have 64 bits.

When «rotate» is true, the bits are rotated, so that a bit that shifts off the right edge is used for the value of the bit shifted in on the left.

When «rotate» is not specified, you can specify the value for new bits in the «bit» parameter, which must be either 0 or 1.

When neither «rotate» nor «bit» are specified, then 0 bits are shifted into the result when shifting left, but when shifting right, the most significant bit (the 64th bit) is used, which has the effect of preserving the sign of the integer. This default is equivalent to integer division by powers of 2 when shifting right, and multiplication by powers of 2 when shifting left.

== Examples ==
To make the effect of the function obvious, integers are written here in [[Binary and hexadecimal integer formats|binary notation]].

:<code>BitShift(0b110101011100, 5) →</code>
::<code>0b1101010</code>
:<code>BitShift(3420, 5) →</code>
::<code>106</code>

:<code>BitShift(0b110101011100, 5, left: true) →</code>
::<code>0b110101011100000</code>
:<code>BitShift(3420, 5, left: true) →</code>
::<code>109440</code>

Negative numbers have leading 1 bits, and are 64 bits in length. Shifting right shifts 1s into the left side.
:<code>BitShift(-170, 5) →</code>
::<code>0b1111111111111111111111111111111111111111111111111111111111111010 = -6</code>

Or you can shift in zero bits:
:<code>BitShift(-170, 5) →</code>
::<code>0b0000011111111111111111111111111111111111111111111111111111111010 = 576460752303423482</code>

:<code>BitShift(0b1101010111, 3, rotate: true) →</code>
::<code>0b1110000000000000000000000000000000000000000000000000000001101010</code>

Next, shifting across cells of an array:
:<code>x :=</code>
:[[image:BitShift_x.png]]

:<code>BitShift(x, 4, I: J) → </code>

:[[image:BitShift_right.png]]

:<code>BitShift(x, 4, I: J, rotate: true) → </code>

:[[image:BitShift_right_rot.png]]

=== Convert Hexadecimal to RGB numeric values ===

Colors are commonly defined with three channels for information: Red, Green, and Blue. The BitShift function offers a straightforward way to convert colors defined by a hexadecimal string to numerical RGB triplet.

:<code>[[Local Values|Local]] hex_val := 0x0079BF</code>
:<code>[[Local Values|Local]] R := BitShift( hex_val, 16 ) → 00</code>
:<code>[[Local Values|Local]] G := BitShift( hex_val, 8 ) - BitShift( R, 8, left: True ) → 79</code>
:<code>[[Local Values|Local]] B := hex_val - BitShift( R, 16, True ) - BitShift( G, 8, True ) → BF</code>

Displayed as integers, these values are <code>[R, G, B] = [0, 121, 191]</code>

==History==
Introduced in [[Analytica 5.0]].

== See Also ==
* [[BitAnd]]
* [[BitOr]]
* [[BitNot]]
* [[BitXOr]]
* [[BitCount]]

FAQs on Software Licensing and Activation

2018-06-22T20:26:10Z

KMullins:

This is a collection of frequently asked questions about activating your Analytica software products. If you have questions that aren't answered here, please let us know at [mailto:sales@lumina.com sales@lumina.com].

__TOC__

==License Server==
===Where do I find my software key?===

:Colon to indent.

Three apostrophes to '''bold''' text.

''italics''

===Second question===

FAQs on Software Licensing and Activation

2018-06-22T19:45:49Z

KMullins: Created page with "This is a collection of frequently asked questions about activating your Analytica software products. If you have questions that aren't answered here, please let us know at sa..."

This is a collection of frequently asked questions about activating your Analytica software products. If you have questions that aren't answered here, please let us know at sales@lumina.com.

__TOC__

===Where do I find my software key?===
Email.

MultiTable

2018-06-21T23:20:12Z

KMullins: Minor update to clarify the purpose of 'item' in the initial example.

[[category:User-interface functions]]
[[category:Top level functions]]
[[category:Table functions]]

== MultiTable(i1,i2,...)(src1, src2, ...) ==

A [[MultiTable]] lets you mix editable and computed values in a single table. Editable cells are based on other variables, each defined as a [[Table]] or [[SubTable]]. Computed values are based on calculated variables or expressions. When you change an editable cell, you are actually changing the original cell in the source table, not a copy.

It is best practice in Analytica to keep different editable user inputs and computed results in different variables. But, it is often convenient to define part of a user interface that combines editable and computed values, which the [[MultiTable]] lets you do.

For example, suppose <code>Startup_cost</code> and <code>Prob_success</code> are both edit tables, indexed by <code>Project</code>. Then the a variable defined as:
:<code>Variable Project_inputs := MultiTable(Item)(Startup_cost, Prob_success)</code>

lets you view and edit both Startup_cost and Prob_Success in the same edit table. The [[MultiTable]] is indexed by <code>Project</code>, the index common to both Startup_cost and Prob_success, and by <code>Item</code>, which is an additional index that needs to be created.

[[MultiTable]] is the inverse of [[SubTable]] in that it combines multiple sources into one view, where [[SubTable]] selects a particular slice or subset of data to edit.

== Creating a MultiTable ==

Before you create a [[MultiTable]], you need to create or identify one or more indexes that your data sources will vary over. For example, if you want a different data source to appear in each column of your table, then you'll need a column index, and you'll need to fill in the labels for each column as you define the index.

Next, create a variable to hold your [[MultiTable]] and press ''Ctrl+E'' to place your cursor in the definition field.

:[[image:MT_create1.png]]

In the '''Object Finder''', select the '''Array''' library and scroll down to find and select [[MultiTable]]. Then, press the '''Indexes''' button.

:[[image:MT_create2.png]]

Select the indexes that your [[MultiTable]] data sources will vary along. These are not the indexes of your data sources themselves.

:[[image:MT_create3.png]]

The table initially displays the "Meta expressions" view so that you can specify the data sources for the table. The ''meta-expression selector'' controls which view you are in.

== Specifying Data Sources ==

Whenever you need to specify or change which data source should appear in a [[MultiTable]], use the ''meta-expressions selector'' to change to '''meta-expressions view'''.

Here is an example of meta-expressions.

:[[image:MT_create4.png]]

In the above meta-expressions view, <code>Option_type</code>, <code>Stock_symbol</code>, <code>Strike_price</code> and <code>Expiration_date</code> are identifiers of other edit tables. These will be editable columns. <code>Stock_price_lookup(Stock_Symbol)</code> is a call to a [[User-Defined Function]], and its computed value will appear in this column. The last cell contains <code>Mid(Contract_valuation)</code>, so that the computed mid-value of <code>Contract_valuation</code> will be displayed. When you want the computed value of a variable, you must surround its identifier with [[Mid]] in this fashion, otherwise its definition will appear in the cell and will be editable.

=== Editable sources ===

An editable source reflects the contents of another edit table in your model, a [[slice]] of an edit table, or the [[definition]] of another variable. When a user edits these cells in the multitable, they are actually changing the data in the specified source definition or table. In meta-expression view, an editable source is specified in one of the following ways.
* <code>X</code> : An identifier. The definition of <code>X</code>, or the [[Table|edit table]] (or [[SubTable]] or [[MultiTable]] of <code>X</code>) is depicted.
* <code>X[I=v]</code> : A [[Slice]] or [[Subscript]] of another table. That slice is depicted in an editable form.

The source can be a scalar variable, an [[Table|edit table]], a [[SubTable]] or another [[MultiTable]]. Rather arbitrary transformations that be accomplished by nesting SubTables and MultiTables.

=== Computed sources ===

The following are computed expressions, which are evaluated and the resulting value displayed in a non-editable form with a gray background.
* <code>31.4</code>, <code>"Text"</code>: Literal values (numbers, quoted text)
* <code>Mid(X)</code>: Displays the computed mid-value of the variable <code>X</code>
* <code>F(...)</code>: Any function call other than [[Slice]] or [[Subscript]], including calls to [[User-Defined Function]]s, are evaluated.
* <code>x + y</code> : An expression, such as one involving arithmetic operations, is evaluated.

Here are a few additional examples:

* <code>Mid(X)</code> : ''computes and displays the [[mid]]-value of <code>X</code>''
* <code>Abs(X)</code> : ''displays the [[Abs|absolute value]] of the (mid-value) of <code>X</code>''
* <code>Mean(X)</code> : ''computes and displays the [[mean]] of <code>X</code>''
* <code>1.2</code> : ''displays the number, 1.2, in a non-editable cell''
* <code>"Some text"</code> : ''displays the text, without quotes, in a non-editable cell

A computed expression or computed variable CAN depend on the values of other data sources that appear in the same [[MultiTable]]. When you do this, the computed value will change when the user changes the input cells and presses the green check button.

== Viewing the Data ==

After you have specified the data sources in meta-expression view, change the '''meta-expression selector''' to '''Show Cells''' to see the actual data.

:[[image:MT_create5.png]]

=== When cells can be edited ===

You can never edit computed values in a [[MultiTable]]

In [[Browse mode]], you can edit data in a variable only if the variable has a [[user input node]]. This means that if your [[MultiTable]] variable has a user input node, users in [[Browse mode]] (including [[Analytica Cloud Player]] or [[Free Edition|Analytica Free 101]]) can edit all table sources. Otherwise, if one source has a user input node and another does not, users in [[Browse mode]] can edit only those cells from the source(s) with the user in.

== Examples ==

Here is an example of an editable value and computed value in the same table:

<pre style="background:white; border:white; margin-left: 1em;">
Index Base := ["Decimal", "Hex"]
Variable x := 123
Variable HexConverter := MultiTable(Base)(x, NumberToText(x, "Hexadecimal"))
</pre>

The edit table displays like this:

:[[image:HexConverter.png]]

The first cell can be edited, and when you change it and press the green check, the [[Binary and hexadecimal integer formats|hexadecimal]] value is computed and displayed.

== Dimensionality ==

The dimensions of the [[MultiTable]] content are the union of the indexes from all sources and of the [[MultiTable]] index(es).

A [[MultiTable]] works best when your sources all have the same dimensionality. When one source does not have an index present in another source, a single cell in the source will map to multiple cells in the [[MultiTable]]; hence, you'll see the same value multiple places, and when you change it, multiple cells will change. The source retains its original dimensionality, so if the value doesn't vary along an index in the source, it won't vary along that index is the [[MultiTable]]. You may temporarily see a difference in these cells after you first enter a value, but they will become consistent as soon as you press the Green check.

== Number Formats ==

When number formats are set for the source tables, those formats are used in the corresponding column of the MultiTable.

When a meta-expression is of the form <code>Mid(X)</code>, then <code>X</code>'s number format is used. For arbitrary expressions, the number format of the [[MultiTable]]'s own variable is used.

==History==
Introduced in [[Analytica 4.6]]. Present in experimental form in [[Analytica 4.5]].

== See Also ==
* [[Tutorial: Arrays]]
* [[Arrays and Indexes]]
* [[SubTable]]
* [[Table]]
* [[Mid]], [[Mean]], [[Sample]] -- used for specifying computed results.
* [[Subscript]], [[Slice]], [[Subscript/Slice Operator]]
* [[Objects and Values]]

File:Foxes and hares dynamic.ana

2018-06-14T19:35:33Z

KMullins: Tutorial model from the system dynamics section.

Tutorial model from the system dynamics section.

Tutorial: Open a model to browse

2018-06-01T17:42:41Z

KMullins:

[[Category:Analytica Tutorial]]
[[Category: Rent vs. Buy model]]
<breadcrumbs>Analytica Tutorial > {{PAGENAME}}</breadcrumbs>
{{ReleaseBar}}

This Tutorial page shows you how to open an example Analytica model: The '''Rent vs. Buy model''' lets you compare the cost of renting a house to the cost of buying one. You will learn how to:
* open an existing model,
* use it to calculate results, and
* change input values to calculate different results
* save your changes and quit

<br>
<center>
<iframe width="640" height="360" src="https://www.youtube.com/embed/GQV0dnDN0Q0" frameborder="0" allowfullscreen></iframe>

'''Video:''' [https://youtu.be/GQV0dnDN0Q0 Tutorial: Open a model to browse] (7 minutes)
</center>
<br>

<div style="column-count:2;-moz-column-count:2;-webkit-column-count:2">
__TOC__
</div>

==Open the Rent vs. Buy model==
To begin, follow these steps.
# Launch Analytica: Click the '''Start''' button on the Windows taskbar. Click '''All Programs''' → '''Analytica {{#svarget:anarelease|4.6}}''' → '''Analytica {{#svarget:anarelease|4.6}}'''. <br>{{Release||4.6|[[File:Chapter 1.1.png|300px]]}}{{Release|5.0||[[File:Launch Ana5.0 from Start Menu.png|300px]]}}
# After Analytica starts, {{Release||4.6|
select '''File''' → '''Open''' from the menu.
# <br> [[File:Chapter 1.2a.png]]
# Open the Rent vs. Buy model. <br> [[File:Chapter 1.2b.png]] <br> Analytica reads in the Rent vs. Buy model.
}}{{Release|5.0||
select the ''Rent vs. Buy Example'' on the [[Intro screen]].<br />
[[File:Open Buy vs Rent Example.png]]
}}

==The Diagram window==
When you open a model, Analytica first displays a top-level [[Diagram window]]. The ''Rent vs. Buy'' model diagram shows several input variables that affect the trade-offs between renting and buying, '''Normal''' buttons, a '''Calc''' button, and a node labeled Model.

{{CalloutAnnotationBlock|[[image:Chapter 1.3.png]]|
{{CalloutAnnotation|
Normal buttons|Type=Bare|v=130|pt=215,129|path=r-}}
{{CalloutAnnotation|
Normal buttons |Type=Bare|v=130|pt=518,155|path=r-}}
{{CalloutAnnotation|
Model node|Type=Bare|v=200|pt=246,210|path=r-}}
{{CalloutAnnotation|
Calc button|Type=Bare|v=268|pt=412,262|path=r-}}
}}

This top-level diagram is an end-user interface to the model itself, which is contained in the Model node. In this chapter, you use only the interface in this top level diagram; in the following chapters you will explore the model in more depth.

Across the top of the screen is a [[toolbar|horizontal palette of buttons]]. This is called the '''''tools palette'''''.

:{{Release||4.6|[[File:Chapter 1.4.png]]}}
{{Release|5.0||
{{CalloutAnnotationBlock|[[image:BrowseToolOnToolbar5.0.png]]|
{{CalloutAnnotation|The browse tool|Type=Bare|v=10|pt=267,33|path=bD20-}}}}
}}

When you first open the ''Rent vs. Buy'' model, the '''browse tool''' is highlighted on the palette. With the browse tool selected, the cursor looks like a hand [[File:Chapter 1.5.png]] when it is over the diagram. The browse tool allows you to calculate the model, change input values, and examine — but not change — the structure of the model. In this chapter, you only use the browse tool.

==Access Help Resources==

At any time, you can press the ''F1'' key on the keyboard or use the '''Help''' menu to access Analytica’s help resources online. This menu includes links to this [[Analytica Tutorial|Tutorial], the [[Analytica User Guide|User Guide]] and much more tips and reference material on this [[Analytica Wiki]].

==Compute output values==

In the ''Rent vs. Buy'' model, the output value of interest is at the bottom, ''Present value of buying and renting''.

{{CalloutAnnotationBlock|[[image:Chapter 1.3.png]]|
{{CalloutAnnotation|
Click the '''Calc''' button to compare the present value of buying and renting.|v=200|pt=413,265|path=bD20-|n=1}}
}}

The output value displays in a [[Result window]]. This '''Result''' window shows a graph of two '''''probability density''''' curves, one for buying and one for renting. In a probability density graph, the units of the vertical scale are chosen so that the total area under each curve is 1 (100%). 25μ corresponds to 25 x 10-6 or 0.000025.

<tip>Numerical suffixes like μ and K are used extensively throughout Analytica. A quick reference for these suffixes is given in [[Number formats]] .</tip>

:[[File:Chapter 1.7.png]]

Since the graph is of probability densities, both buying and renting have probabilistic, or uncertain, inputs. The probability density graph for each appear to be bell-shaped curves ([[normal]] distribution), although they appear a bit “noisy.”

The graphs show that the cost of renting, given the model’s inputs, are between about $105,000 and $155,000 (the negative numbers mean cost — cash flowing out), while the cost of buying is between $115,000 and a gain of $75,000.

{{CalloutAnnotationBlock|[[image:Chapter 1.8.png]]|
{{CalloutAnnotation|
Click the '''Diagram''' window to bring it to the front.|v=20|pt=60,220|path=b!|n=+}}
}}

'''''Note''': Your results can vary slightly, since the model is generating random inputs based on a normal distribution for the uncertainty of the rate of inflation and for the appreciation rate.''

Click the model [[Diagram window]] to bring it to the front. Notice that the button next to ''Costs of buying and renting'' has changed to '''Result'''. The '''Result''' button indicates that the value has been computed; clicking the '''Result''' button re-displays the computed values.

{{CalloutAnnotationBlock|[[image:Chapter 1.9.png]]|
{{CalloutAnnotation|
The '''Calc''' button has changed to '''Result'''.|Type=Bare|v=220|pt=413,265|path=bD20-}}
}}

==Change input values and recompute results==

Now you will change some input values to the model and recompute the rent vs. buy comparison. You will change the values of ''Time horizon'', ''Monthly rent'', and ''Buying price''.

{{CalloutAnnotationBlock|[[image:Chapter 1.9.png]]|
{{CalloutAnnotation|
Click the box next to ''Time horizon''. Change the value to '''''7''''' and press ''Alt+Enter''.|v=50|pt=220,64|path=tU20-|n=1}}
}}

<tip>The main Enter key and the numeric keypad Enter key are not interchangeable. They have different functions in Analytica. Alt+Enter is equivalent to the numeric keypad Enter key.</tip>

As soon as you change an input, the '''Result''' button changes to a '''Calc''' button, indicating that ''Present value of buying and renting'' needs to be recomputed.

{{CalloutAnnotationBlock|[[image:Chapter 1.10.png]]|
{{CalloutAnnotation|
Click the box next to ''Monthly rent''. Change the value to '''''1400''''' and press ''Alt+Enter''.|v=170|pt=220,171|path=r-|n=+}}
}}

{{CalloutAnnotationBlock|[[image:Chapter 1.11.png]]|
{{CalloutAnnotation|
Click the box next to ''Buying price''. Change the value to '''''180K''''' (or 180000) and press ''Alt+Enter''.|v=130|pt=510,65|path=tU100-|n=+}}
}}

Now you are ready to recompute to see the new results.

{{CalloutAnnotationBlock|[[image:Chapter 1.12.png]]|
{{CalloutAnnotation|
Click the '''Calc''' button to compute the comparison of the costs of buying to renting.|v=140|pt=413,265|path=bD20-|n=+}}
}}

The graphs show that the cost of renting, given these changed inputs, is between $90,000 and $120,000, while the cost of buying is between $135,000 and a gain of $70,000.

{{CalloutAnnotationBlock|[[image:Chapter 1.13.png]]|
{{CalloutAnnotation|
Click the '''Diagram''' window to bring it to the front.|v=140|pt=127,386|path=b!|n=+}}
}}

==Examine and change an uncertain input==
When an input is defined as a probability distribution, a button with the name of the distribution appears next to the input’s name. Clicking this button opens the [[Object Finder dialog|Object Finder]] window, in which you can see details and change the distribution’s parameters or type of distribution.

''Rate of inflation''’s button says '''Normal''', indicating that it is defined as a normal distribution.

{{CalloutAnnotationBlock|[[image:Chapter 1.12.png]]|
{{CalloutAnnotation|
Click the '''Normal''' button next to the ''Rate of inflation''.|v=90|pt=218,134|path=bD20-|n=1}}
}}

The [[Object Finder dialog|Object Finder]] window appears. It shows that ''Rate of inflation'' is defined as a normal distribution with a '''''mean''''' of 3.5 and a '''''standard deviation''''' of 1.3.

You will now modify the probability distribution that defines ''Rate of inflation''. Rather than using the normal distribution, you will use the uniform distribution, and assume that inflation has an equal probability of being anywhere between 3% and 4% per year.

{{CalloutAnnotationBlock|[[image:Chapter 1.15.png]]|
{{CalloutAnnotation|
Scroll down the list of distributions and select '''Uniform'''|v=80|pt=0,200|path=b!|n=+}}
}}

{{CalloutAnnotationBlock|[[image:Chapter 1.16.png]]|
{{CalloutAnnotation|
Change the minimum to '''''3'''''.|v=205|pt=222,248|path=r-|n=+}}
{{CalloutAnnotation|
Change the maximum to '''''4'''''.|v=290|pt=330,268|path=tU10/|n=+}}
{{CalloutAnnotation|
Click '''OK''' to accept the change.|v=480|pt=537,481|path=r-|n=+}}
}}

{{CalloutAnnotationBlock|[[image:Chapter 1.17.png]]|
{{CalloutAnnotation|
Click the '''Calc''' button to compute the new comparison of the present value of buying to renting.|v=140|pt=413,265|path=bD20-|n=+}}
}}

:[[File:Chapter 1.18.png]]

The graphs show that the uncertainty in the cost of renting has narrowed to between about $105,000 and $109,000, while the uncertainty in the cost of buying has flattened to between about $125,000 and a gain of $10,000.

==Display alternative uncertainty views==

Analytica offers a variety of views to display uncertain values, including selected statistics, [[Statistical_Functions_and_Importance_Weighting#ProbBands|probability bands]], the [[Uncertainty_Setup_dialog#Probability_density_option|probability density]] function, the [[Uncertainty_Setup_dialog#Cumulative_probability_option|cumulative probability]] distribution function, measures of central tendency, and the table of random numbers from which the uncertain distribution is estimated.

You will now examine several of these views.

In the upper-left corner of the [[Result window]] is the [[Uncertainty view of a result|Uncertainty View]] popup menu.

:[[File:Chapter 1.19.png]]

The miniature probability distribution [[File:Chapter 1.20.png]] indicates that '''''Probability Density''''' is selected.

:[[File:Chapter 1.21.png]]

The [[Result window]] now shows two cumulative probability curves. Along the vertical axis, these curves give the probability that each cost is less than a given value along the horizontal axis.

:[[File:Chapter 1.22.png]]

There appears to be about a 50% probability that the cost to buy is below $70,000, while the cost to rent has a 50% probability of being below about $110,000.

Sometimes you might want to see an uncertain value expressed as a single number — a measure of central tendency. Analytica computes the [[mid]] value (sometimes called the '''''deterministic value''''') by fixing all input probability distributions at their [[median]] (50% probability) values. The mid value is the only uncertainty view available for nonprobabilistic results.

:[[File:Chapter 1.23.png]]

The [[Result window]] now displays bar graphs for the two mid values.

Under the [[Uncertainty view of a result|Uncertainty View]] popup menu are two buttons, [[File:Chapter 1.23.2.png]] and [[File:Chapter 1.23.3.png]]. The [[File:Chapter 1.23.3.png]] is highlighted, indicating that the '''Result''' window is displaying a [[Graph view of a result|graph view]]. The '''Result''' window can also display numeric values in a spreadsheet-like table view.

:[[File:Chapter 1.24.png]]

Analytica also provides the [[mean]] (or average) value.

:[[File:Chapter 1.25.png]]

:[[File:Chapter 1.25.2.png]]

You can also view a set of [[statistics]], including both the [[median]] and [[mean]], the ranges ([[Functions Min and Max|minimum and maximum]]), and the [[Sdeviation|standard deviation]].

:[[File:Chapter 1.26.png]]

The [[Result window]] now displays the minimum, median<ref>Note that the median value is slightly different from the mid value. The mid value is composed of non- probabilistic results generated by using the mean value for each input. The median value is calculated using probabilistic inputs and taking the median of the resulting distribution.</ref>, mean, maximum, and standard deviation for ''Costs of buying and renting''.

:[[File:Chapter 1.27.png]]

The statistics might not be exact, because they are estimated from a sample of values from the distribution.

Finally, you see the [[sample]] values.

:[[File:Chapter 1.28.png]]

The table above lists the 100 sample values that Analytica randomly generated from the probability distribution to estimate the [[statistics]].

A [[SampleSize|sample size]] of 100 is adequate for most applications; however, if you need more precise estimates, you can increase the [[SampleSize|sample size]]. See [[Uncertainty Setup dialog]] in the [[Analytica User Guide]].

:[[File:Chapter 1.29.png]]

==Save your model==
If you want to save changes to your model, you can do so at this point. (For instructions on quitting without saving, see the next section.

:[[File:Chapter 1.30.png]]

If you wish to save your model as a different file, so that you do not change the original model, select '''Save As''' from the [[File menu]].

==Quit Analytica==
When you have finished using a model, you might want to quit Analytica.

:[[File:Chapter 1.33.png]]

== Summary ==

You have now opened an Analytica model, calculated and viewed the results, changes input values and probability distributions, and displayed the uncertain results in several ways. These are the basic techniques for using any quantitative model.

After you create your own models, you might want to give them a top-level input and output diagram like the one used in this chapter. For information about customizing a model for end users, see [[Creating Interfaces for End Users]] in the [[Analytica User Guide]].

The next Tutorial page, shows how to navigate the details of the Rent vs. Buy model, exploring its structure and contents.

==Notes==
<references/>

==See Also==
<div style="column-count:2;-moz-column-count:2;-webkit-column-count:2">
* [https://www.analyticacloud.com/acp/Client/AcpClient.aspx?inviteId=3&inviteCode=221703&subName=acp%20demos Play the Rent vs. Buy model in Analytica Cloud Player]
* [https://www.youtube.com/watch?v=GQV0dnDN0Q0 Using the Rent vs. Buy Model] (an explanatory video on YouTube)
* [[Tutorial videos]]
* [[To open or exit a model]]
* [[Create and save a model]]
* [[Tutorial: Create a model]]
* [[Example Models]]
* [[Example Models and Libraries]]
* [[Diagram window]]
* [[Help menu and documentation]]
* [[User input nodes and user output nodes]]
* [[Expressing Uncertainty]]
* [[Uncertainty Setup dialog]]
* [[Uncertainty view of a result]]
</div>

<footer>About Analytica/ {{PAGENAME}} / Tutorial: Reviewing a model</footer>

Tutorial: Reviewing a model

2018-06-01T17:41:52Z

KMullins:

[[Category:Analytica Tutorial]]
[[Category: Rent vs. Buy model]]
<breadcrumbs>Analytica Tutorial > {{PAGENAME}}</breadcrumbs>
{{ReleaseBar}}

This Tutorial page shows you how to explore a model by examining the ''Rent vs. Buy'' model's:
* Influence diagrams
* Variables
* Attributes
* Definitions
* Results

This assumes you have started Analytica and have opened the ''Rent vs. Buy'' model. If this is not the case, see [[Tutorial: Open a model to browse#Opening_the_Rent_vs._Buy_model|Opening the Rent vs. Buy model]]. If you are using the model as modified from [[Tutorial: Open a model to browse|Chapter 1]], change the value of ''Time horizon ''back to '''10''', the value of ''Monthly rent ''back to '''1200''', and the value of ''Buying price ''back to '''140K'''. Also change the ''Rate of inflation ''back to a normal distribution with a mean of '''3.5 '''and a standard deviation of '''1.3'''.

<br>

<center>
<iframe width="640" height="360" src="https://www.youtube.com/embed/mpF4xcmKaao" frameborder="0" allowfullscreen></iframe>

'''Tutorial Video:''' [https://youtu.be/mpF4xcmKaao Review/explore a model] (8 minutes)
</center>

<br>

<div style="column-count:2;-moz-column-count:2;-webkit-column-count:2">
__TOC__
</div>

==Recognize influence diagrams==
In this chapter, you will delve into some of the details of the ''Rent vs. Buy'' model. You will not use the top diagram that you used in [[Tutorial: Open a model to browse|Chapter 1]].

:[[File:Chapter 2.1.png]]

The details of an Analytica model display in an [[Diagram window|influence diagram window]]. An influence diagram (shown below) is a graphical representation of a model, showing how different variables in the model interact with each other. A typical influence diagram consists of a number of '''''nodes''''' connected by '''''arrows'''''.

:{{Release||4.6|[[File:Chapter 2.2.png]]}}{{Release|5.0||[[File:Chapter_2_2b.png]]}}

'''''Nodes''''' represent variables and appear as boxes, ovals, hexagons, and other shapes. Different node shapes represent different types of variables. Analytica uses the term '''''variable''''' broadly to include anything that has a value or can be evaluated. Note that many of the variables have the same names as the inputs and output at the top diagram that you used in [[Tutorial: Open a model to browse|Chapter 1]]. The top diagram provides an easy way to see and change these nodes’ values.

'''''Arrows''''' connecting different variables indicate a relation between the variables. The arrow connecting ''Rate of inflation ''to ''Appreciation rate ''indicates that the value of the ''Appreciation rate ''variable depends on the value of the ''Rate of inflation ''variable. In the ''Rent vs. Buy ''model influence diagram, ''Cost to Buy ''depends on the ''Buying price'', ''Rate of inflation'', ''Appreciation rate'', ''Discount rate'', and ''Time horizon ''variables.

The following figure illustrates different types of nodes.

:[[File:Chapter 2.3.png]]

==Open Object windows==
Every object in Analytica has an associated [[Object window]] containing detailed information about it. You can display the '''Object''' window of any variable by double-clicking its node in the [[Diagram window|influence diagram]].

:[[File:Chapter 2.4.png]]

Information about a variable is provided in a list of attributes. [[Attributes]] include the variable’s class (for example, decision, chance, or constant), identifier, units, title, description, definition, inputs, and outputs. See the illustration below.

:[[File:Chapter 2.5.png]]

<tip>You can enter numbers with a suffix abbreviation, so Buying Price can be defined as either 140K or 140000. A quick reference for these suffixes is given on [[Number formats]] page.</tip>

==Move between Object windows==
You have opened the [[Object window]] of a variable (''Buying price'') by double-clicking its node in the [[Diagram window|influence diagram]].

The '''Object '''window contains a list of the variable’s '''''inputs '''''and '''''outputs''''', if there are any.

You can open the [[Object window]] for any input or output variable by double-clicking the one you wish to view.

:[[File:Chapter 2.6.png]]

Analytica opens the '''Object''' window for ''Mortgage loan amount''.

:[[File:Chapter 2.7.png]]

Note in the figure above that the '''''Title '''''of ''Mortgage loan amount ''is different from the variable’s [[identifier]], ''Mortgage''. The title is what the model user normally sees; the identifier is used as a mathematical symbol in the definitions of other variables that depend on this variable.

The [[definition]] of the ''Mortgage loan amount ''is an [[Expressions|expression]], the sum of ''Buying price ''and ''Down payment ''(which is a negative amount). The definition refers to these variables by their identifiers.

'''''Inputs '''''lists the identifiers and titles of the variables in the definition. ''Buying price'', the variable you just examined, is one of the inputs. The other input of ''Mortgage loan amount ''is ''Down payment''.

:[[File:Chapter 2.8.png]]

The [[Object window]] now displays the [[attributes]] of ''Down payment''.

:[[File:Chapter 2.9.png]]

==Use the Attribute panel==
As an alternative to viewing a variable’s attributes in a separate window, you can inspect them in the [[Attribute panel]], which is an auxiliary window pane that you can open below the influence diagram.

The [[Attribute panel]] allows you to rapidly examine one [[attributes|attribute]] at a time of any variable in the model. You select the variable you wish to view and select the attribute to examine from a popup menu.

The variable ''Buying price ''should be highlighted with a title in white, indicating that it is selected; if it is not, select it by clicking it once.

:[[File:Chapter 2.10.png]]

By default, Analytica displays the '''''description '''''of the selected node (e.g., ''Buying price'') in the [[Attribute panel]].

:[[File:Chapter 2.11.png]]

==Inspect definitions in the Attribute panel==
The [[Attribute panel]] allows you to inspect any attribute of a variable.

In this section, you will see the [[definition]] of two variables that you viewed in the top-level diagram in [[Tutorial: Open a model to browse|Chapter 1]].

:[[File:Chapter 2.12.png]]

:[[File:Chapter 2.13.png]]

:[[File:Chapter 2.14.png]]

When a variable is defined as an '''''uncertainty distribution''''', a button appears in the '''Definition''' field.

:[[File:Chapter 2.15.png]]

In [[Tutorial: Open a model to browse|Chapter 1]] you saw that ''Rate of inflation'' is defined as a [[normal]] distribution with a [[mean]] of 3.5 and a [[Sdeviation|standard deviation]] of 1.3.

==Open modules==
Analytica models generally contain '''''modules'''''. Each [[Modules and Libraries|module]] contains the details of a part of the model, also represented as an [[influence diagram]]. In the ''Rent vs. Buy'' model, ''Cost to Buy'' and ''Cost to Rent'' are both modules.

Modules can also contain other modules. In this manner, a large model with hundreds of variables can be organized into a hierarchy of modules, each small enough to be easily understood.

:[[File:Chapter 2.16.png]]

Analytica displays the influence diagram of the ''Cost to Buy'' [[Modules and Libraries|module]]. This module contains three additional modules: ''Out-of-pocket costs to own, Future sales proceeds,'' and ''Opportunity cost''.

:[[File:Chapter 2.17.png]]

The '''''input arrowhead''''' (without a trailing line) shows that the node to the right of the arrow has one or more inputs from outside this module.

The '''''output arrowhead''''' shows that the node to the left of the arrow has one or more outputs outside this module.

:[[File:Chapter 2.18.png]]

:[[File:Chapter 2.19.png]]

Analytica limits the number of open windows at each level of the model hierarchy to minimize clutter on your screen. See [[Managing windows]] in the [[Analytica User Guide]] for information on how to open more than one module [[Diagram window]] at a time.

:[[File:Chapter 2.20.png]]

The combined arrowhead, shown above, indicates that the node has one or more inputs from outside this module, plus the input variable in this module.

You can also navigate the model by tracking a variable’s [[User input nodes and user output nodes|inputs or outputs]].

:[[File:Chapter 2.22.png]]

The Out-of-pocket costs to own module diagram is brought to the front, with the Insurance node selected.

==Learn about nodes using Help balloons==
[[Help balloons]] pop up when you hover over a node for about a second, and display the title, units, and description for a variable. These allow you to browse information very rapidly without having to open the object window. Balloons do not appear when objects do not have the Help or Description attribute filled in.

:[[File:Chapter 2.24.png]]

:[[File:Chapter 2.23.png]]

==Inspect values in the Attribute panel==
The [[Attribute panel]] allows you to view certain attributes, such as a variable’s '''''value''''', that are not (initially) displayed in an [[Object window]].

:[[File:Chapter 2.25.png]]

:[[File:Chapter 2.26.png]]

If '''''Value '''''was not previously computed, Analytica computes the variable’s value '''''deterministically''''', assuming that all of the input probability distributions are fixed at their median values. [[Mid]] value is an abbreviation for this deterministically computed value.

You can use the [[Attribute panel]] in this manner to examine the mid value of any variable in the model.

It is faster to compute a mid (deterministic) value than an uncertain (probabilistic) value, so it is useful for conducting initial checks of a model before performing any uncertainty analysis.

==Display results==
When you are viewing a model’s [[Diagram window|influence diagram]], you can evaluate any variable and display its value in a [[Result window]].

:[[File:Chapter 2.27.png]]

A [[Result window]] displays the [[Probability density and mass graphs|probability density function graph]] for this variable. Analytica displays the [[Uncertainty view of a result|uncertainty view]] that was most recently selected from the [[Uncertainty views|Uncertainty View]] popup menu, or that was saved with the model.

:[[File:Chapter 2.29-updated.png]]

<tip>The ''Rent vs. Buy ''model uses financial flow conventions: funds flowing in (received) have positive values; funds flowing out (expended) have negative values.</tip>

As an alternative to clicking the '''Result''' button [[File:Chapter 2.29.1.png]] and then selecting an uncertainty view, you can use the [[Result menu]] to evaluate a variable and select the [[Uncertainty view of a result|uncertainty view of the result]].

:[[File:Chapter 2.30.png]]

The [[Result window]] appears displaying the variable’s [[Distribution_Densities_Library#Cumulative_Probability_Functions|cumulative probability distribution]].

:[[File:Chapter 2.31.png]]

:[[File:Chapter 2.33.png]]

A single [[mid]] value appears in table view.

:[[File:Chapter 2.34.png]]

The [[mid]] value in [[Table view of a result|table view]] is the only result view available for a nonprobabilistic variable with a single value.

:[[File:Chapter 2.35.png]]

Analytica tells you that this is a nonprobabilistic value.

:[[File:Chapter 2.36.png]]

==Summary==
You now have browsed the ''Rent vs. Buy'' model by examining its influence diagrams, variables, attributes, definitions, and results. These are the basic techniques for exploring any Analytica model.

The next chapter shows you how to analyze the Rent vs. Buy model.

You can quit Analytica at this point.

==See Also==
<div style="column-count:2;-moz-column-count:2;-webkit-column-count:2">
* [https://www.analyticacloud.com/acp/Client/AcpClient.aspx?inviteId=3&inviteCode=221703&subName=acp%20demos Play the Rent vs. Buy model in Analytica Cloud Player]
* [https://www.youtube.com/watch?v=mpF4xcmKaao Exploring a model] (an explanatory video on YouTube)
* [[Tutorial videos]]
* [[Examining a Model]]
* [[Diagram window]]
* [[Creating Lucid Influence Diagrams]]
* [[Object Window]]
* [[Classes of variables and other objects]]
* [[Attributes]]
* [[Attribute panel]]
* [[Entering Attributes using the Attribute panel]]
* [[Definitions]]
* [[Import a module or library]]
* [[User input nodes and user output nodes]]
* [[Help balloons]]
* [[Result Tables and Graphs]]
* [[Result window]]
* [[Managing windows]]
</div>

<footer>Tutorial: Open a model to browse/ {{PAGENAME}} / Tutorial: Analyzing a model</footer>

Tutorial: Reviewing a model

2018-06-01T17:40:39Z

KMullins:

[[Category:Analytica Tutorial]]
[[Category: Rent vs. Buy model]]
<breadcrumbs>Analytica Tutorial > {{PAGENAME}}</breadcrumbs>
{{ReleaseBar}}

This Tutorial page shows you how to explore a model by examining the ''Rent vs. Buy'' model's:
* Influence diagrams
* Variables
* Attributes
* Definitions
* Results

This assumes you have started Analytica and have opened the ''Rent vs. Buy'' model. If this is not the case, see [[Tutorial: Open a model to browse#Opening_the_Rent_vs._Buy_model|Opening the Rent vs. Buy model]]. If you are using the model as modified from [[Tutorial: Open a model to browse|Chapter 1]], change the value of ''Time horizon ''back to '''10''', the value of ''Monthly rent ''back to '''1200''', and the value of ''Buying price ''back to '''140K'''. Also change the ''Rate of inflation ''back to a normal distribution with a mean of '''3.5 '''and a standard deviation of '''1.3'''.

<br>

<center>
<iframe width="640" height="360" src="https://www.youtube.com/embed/mpF4xcmKaao" frameborder="0" allowfullscreen></iframe>

'''Tutorial Video:''' [https://youtu.be/mpF4xcmKaao Review/explore a model] (8 minutes)
</center>

<br>

<div style="column-count:2;-moz-column-count:2;-webkit-column-count:2">
__TOC__
</div>

==Recognize influence diagrams==
In this chapter, you will delve into some of the details of the ''Rent vs. Buy'' model. You will not use the top diagram that you used in [[Tutorial: Open a model to browse|Chapter 1]].

:[[File:Chapter 2.1.png]]

The details of an Analytica model display in an [[Diagram window|influence diagram window]]. An influence diagram (shown below) is a graphical representation of a model, showing how different variables in the model interact with each other. A typical influence diagram consists of a number of '''''nodes''''' connected by '''''arrows'''''.

:{{Release||4.6|[[File:Chapter 2.2.png]]}}{{Release|5.0||[[File:Chapter_2_2b.png]]}}

'''''Nodes''''' represent variables and appear as boxes, ovals, hexagons, and other shapes. Different node shapes represent different types of variables. Analytica uses the term '''''variable''''' broadly to include anything that has a value or can be evaluated. Note that many of the variables have the same names as the inputs and output at the top diagram that you used in [[Tutorial: Open a model to browse|Chapter 1]]. The top diagram provides an easy way to see and change these nodes’ values.

'''''Arrows''''' connecting different variables indicate a relation between the variables. The arrow connecting ''Rate of inflation ''to ''Appreciation rate ''indicates that the value of the ''Appreciation rate ''variable depends on the value of the ''Rate of inflation ''variable. In the ''Rent vs. Buy ''model influence diagram, ''Cost to Buy ''depends on the ''Buying price'', ''Rate of inflation'', ''Appreciation rate'', ''Discount rate'', and ''Time horizon ''variables.

The following figure illustrates different types of nodes.

:[[File:Chapter 2.3.png]]

==Open Object windows==
Every object in Analytica has an associated [[Object window]] containing detailed information about it. You can display the '''Object''' window of any variable by double-clicking its node in the [[Diagram window|influence diagram]].

:[[File:Chapter 2.4.png]]

Information about a variable is provided in a list of attributes. [[Attributes]] include the variable’s class (for example, decision, chance, or constant), identifier, units, title, description, definition, inputs, and outputs. See the illustration below.

:[[File:Chapter 2.5.png]]

<tip>You can enter numbers with a suffix abbreviation, so Buying Price can be defined as either 140K or 140000. A quick reference for these suffixes is given on [[Number formats]] page.</tip>

==Move between Object windows==
You have opened the [[Object window]] of a variable (''Buying price'') by double-clicking its node in the [[Diagram window|influence diagram]].

The '''Object '''window contains a list of the variable’s '''''inputs '''''and '''''outputs''''', if there are any.

You can open the [[Object window]] for any input or output variable by double-clicking the one you wish to view.

:[[File:Chapter 2.6.png]]

Analytica opens the '''Object''' window for ''Mortgage loan amount''.

:[[File:Chapter 2.7.png]]

Note in the figure above that the '''''Title '''''of ''Mortgage loan amount ''is different from the variable’s [[identifier]], ''Mortgage''. The title is what the model user normally sees; the identifier is used as a mathematical symbol in the definitions of other variables that depend on this variable.

The [[definition]] of the ''Mortgage loan amount ''is an [[Expressions|expression]], the sum of ''Buying price ''and ''Down payment ''(which is a negative amount). The definition refers to these variables by their identifiers.

'''''Inputs '''''lists the identifiers and titles of the variables in the definition. ''Buying price'', the variable you just examined, is one of the inputs. The other input of ''Mortgage loan amount ''is ''Down payment''.

:[[File:Chapter 2.8.png]]

The [[Object window]] now displays the [[attributes]] of ''Down payment''.

:[[File:Chapter 2.9.png]]

==Use the Attribute panel==
As an alternative to viewing a variable’s attributes in a separate window, you can inspect them in the [[Attribute panel]], which is an auxiliary window pane that you can open below the influence diagram.

The [[Attribute panel]] allows you to rapidly examine one [[attributes|attribute]] at a time of any variable in the model. You select the variable you wish to view and select the attribute to examine from a popup menu.

The variable ''Buying price ''should be highlighted with a title in white, indicating that it is selected; if it is not, select it by clicking it once.

:[[File:Chapter 2.10.png]]

By default, Analytica displays the '''''description '''''of the selected node (e.g., ''Buying price'') in the [[Attribute panel]].

:[[File:Chapter 2.11.png]]

==Inspect definitions in the Attribute panel==
The [[Attribute panel]] allows you to inspect any attribute of a variable.

In this section, you will see the [[definition]] of two variables that you viewed in the top-level diagram in [[Tutorial: Open a model to browse|Chapter 1]].

:[[File:Chapter 2.12.png]]

:[[File:Chapter 2.13.png]]

:[[File:Chapter 2.14.png]]

When a variable is defined as an '''''uncertainty distribution''''', a button appears in the '''Definition''' field.

:[[File:Chapter 2.15.png]]

In [[Tutorial: Open a model to browse|Chapter 1]] you saw that ''Rate of inflation'' is defined as a [[normal]] distribution with a [[mean]] of 3.5 and a [[Sdeviation|standard deviation]] of 1.3.

==Open modules==
Analytica models generally contain '''''modules'''''. Each [[Modules and Libraries|module]] contains the details of a part of the model, also represented as an [[influence diagram]]. In the ''Rent vs. Buy'' model, ''Cost to Buy'' and ''Cost to Rent'' are both modules.

Modules can also contain other modules. In this manner, a large model with hundreds of variables can be organized into a hierarchy of modules, each small enough to be easily understood.

:[[File:Chapter 2.16.png]]

Analytica displays the influence diagram of the ''Cost to Buy'' [[Modules and Libraries|module]]. This module contains three additional modules: ''Out-of-pocket costs to own, Future sales proceeds,'' and ''Opportunity cost''.

:[[File:Chapter 2.17.png]]

The '''''input arrowhead''''' (without a trailing line) shows that the node to the right of the arrow has one or more inputs from outside this module.

The '''''output arrowhead''''' shows that the node to the left of the arrow has one or more outputs outside this module.

:[[File:Chapter 2.18.png]]

:[[File:Chapter 2.19.png]]

Analytica limits the number of open windows at each level of the model hierarchy to minimize clutter on your screen. See [[Managing windows]] in the [[Analytica User Guide]] for information on how to open more than one module [[Diagram window]] at a time.

:[[File:Chapter 2.20.png]]

The combined arrowhead, shown above, indicates that the node has one or more inputs from outside this module, plus the input variable in this module.

You can also navigate the model by tracking a variable’s [[User input nodes and user output nodes|inputs or outputs]].

:[[File:Chapter 2.22.png]]

The Out-of-pocket costs to own module diagram is brought to the front, with the Insurance node selected.

==Help balloons==
[[Help balloons]] pop up when you hover over a node for about a second, and display the title, units, and description for a variable. These allow you to browse information very rapidly without having to open the object window. Balloons do not appear when objects do not have the Help or Description attribute filled in.

:[[File:Chapter 2.24.png]]

:[[File:Chapter 2.23.png]]

==Inspect values in the Attribute panel==
The [[Attribute panel]] allows you to view certain attributes, such as a variable’s '''''value''''', that are not (initially) displayed in an [[Object window]].

:[[File:Chapter 2.25.png]]

:[[File:Chapter 2.26.png]]

If '''''Value '''''was not previously computed, Analytica computes the variable’s value '''''deterministically''''', assuming that all of the input probability distributions are fixed at their median values. [[Mid]] value is an abbreviation for this deterministically computed value.

You can use the [[Attribute panel]] in this manner to examine the mid value of any variable in the model.

It is faster to compute a mid (deterministic) value than an uncertain (probabilistic) value, so it is useful for conducting initial checks of a model before performing any uncertainty analysis.

==Display results==
When you are viewing a model’s [[Diagram window|influence diagram]], you can evaluate any variable and display its value in a [[Result window]].

:[[File:Chapter 2.27.png]]

A [[Result window]] displays the [[Probability density and mass graphs|probability density function graph]] for this variable. Analytica displays the [[Uncertainty view of a result|uncertainty view]] that was most recently selected from the [[Uncertainty views|Uncertainty View]] popup menu, or that was saved with the model.

:[[File:Chapter 2.29-updated.png]]

<tip>The ''Rent vs. Buy ''model uses financial flow conventions: funds flowing in (received) have positive values; funds flowing out (expended) have negative values.</tip>

As an alternative to clicking the '''Result''' button [[File:Chapter 2.29.1.png]] and then selecting an uncertainty view, you can use the [[Result menu]] to evaluate a variable and select the [[Uncertainty view of a result|uncertainty view of the result]].

:[[File:Chapter 2.30.png]]

The [[Result window]] appears displaying the variable’s [[Distribution_Densities_Library#Cumulative_Probability_Functions|cumulative probability distribution]].

:[[File:Chapter 2.31.png]]

:[[File:Chapter 2.33.png]]

A single [[mid]] value appears in table view.

:[[File:Chapter 2.34.png]]

The [[mid]] value in [[Table view of a result|table view]] is the only result view available for a nonprobabilistic variable with a single value.

:[[File:Chapter 2.35.png]]

Analytica tells you that this is a nonprobabilistic value.

:[[File:Chapter 2.36.png]]

==Summary==
You now have browsed the ''Rent vs. Buy'' model by examining its influence diagrams, variables, attributes, definitions, and results. These are the basic techniques for exploring any Analytica model.

The next chapter shows you how to analyze the Rent vs. Buy model.

You can quit Analytica at this point.

==See Also==
<div style="column-count:2;-moz-column-count:2;-webkit-column-count:2">
* [https://www.analyticacloud.com/acp/Client/AcpClient.aspx?inviteId=3&inviteCode=221703&subName=acp%20demos Play the Rent vs. Buy model in Analytica Cloud Player]
* [https://www.youtube.com/watch?v=mpF4xcmKaao Exploring a model] (an explanatory video on YouTube)
* [[Tutorial videos]]
* [[Examining a Model]]
* [[Diagram window]]
* [[Creating Lucid Influence Diagrams]]
* [[Object Window]]
* [[Classes of variables and other objects]]
* [[Attributes]]
* [[Attribute panel]]
* [[Entering Attributes using the Attribute panel]]
* [[Definitions]]
* [[Import a module or library]]
* [[User input nodes and user output nodes]]
* [[Help balloons]]
* [[Result Tables and Graphs]]
* [[Result window]]
* [[Managing windows]]
</div>

<footer>Tutorial: Open a model to browse/ {{PAGENAME}} / Tutorial: Analyzing a model</footer>

Tutorial: Analyzing a model

2018-06-01T17:39:11Z

KMullins:

[[Category:Analytica Tutorial]]
[[Category: Rent vs. Buy model]]
<breadcrumbs>Analytica Tutorial > {{PAGENAME}}</breadcrumbs>

This Tutorial page shows you how to:
* Perform importance analysis
* Perform parametric analysis
* Set up and compare alternative decisions

In this Tutorial you will analyze the ''Rent vs. Buy Analysis ''model, a modified version of the model that you used in [[Tutorial: Open a model to browse]] and [[Tutorial: Reviewing a model]]. You will identify its key sources of uncertainty through '''''importance analysis, perform parametric analysis''''', and '''''compare alternative '''''decisions.

For instructions on how to open a model, see “Opening the Rent vs. Buy model”. In this case, however, open the ''Rent vs. Buy Analysis ''model by double-clicking the file labeled '''Rent vs. Buy Analysis.ana'''.

<br>
<center>
<iframe width="640" height="360" src="https://www.youtube.com/embed/scVOq29NMG4" frameborder="0" allowfullscreen></iframe>

'''Tutorial Video:''' [https://youtu.be/scVOq29NMG4 Analyze a model] (6 minutes)
</center>
<br>

__TOC__

==Examine the difference between renting and buying==
The ''Rent vs. Buy Analysis ''model is the module called ''Model ''that you explored in [[Tutorial: Reviewing a model]] with the addition of nodes to help you understand the importance of the uncertain inputs to the uncertainty in the output.

In [[Tutorial: Open a model to browse]] you saw that evaluating ''Costs of buying and renting ''produces a graph of two uncertain values. To understand whether it would be financially advantageous to rent or buy, the ''Rent vs. Buy Analysis ''model includes the objective node, ''Difference between buying and renting''.

:[[File:Chapter 3.1.png]]

The difference between the two uncertain values is also uncertain. The difference is positive if buying costs less over the time period, and negative if renting costs less over the time period.

:[[File:Chapter 3.3.png]]

==Importance analysis==
In the ''Rent vs. Buy Analysis ''model, as in most complex models, several of the input variables are uncertain.

It is often useful to understand how much each uncertain input contributes to the uncertainty in the output. Typically, a few key uncertain inputs are responsible for the lion’s share of the uncertainty in the output, while the rest of the inputs have little impact.

Analytica’s [[importance analysis]] features can help you understand which uncertain inputs contribute most to the uncertainty in the output. You can then concentrate on getting more precise estimates or building a more detailed model for the one or two most “important” inputs.

:[[File:Chapter 3.6.png]]

Analytica defines '''''importance''''' as the [[rank]] order [[correlation]] between the output value and each uncertain input. Each variable’s importance is calculated on a relative scale from 0 to 1. An importance value of 0 indicates that the uncertain input variable has no effect on the uncertainty in the output. A value of 1 implies total correlation, where all of the uncertainty in the output is due to the uncertainty of a single input.

:[[File:Chapter 3.6b.png]]

It is clear in the figure above that the input ''Appreciation Rate'' is contributing most of the uncertainty in the ''Difference between buying and renting''.

:[[File:Chapter 3.8.png]]

For more information about [[importance analysis]] and the steps to create an importance variable in your own model, see [[Scatter plots]] in the [[Statistics, Sensitivity, and Uncertainty Analysis]] chapter of the [[Analytica User Guide]].

==Perform parametric (sensitivity) analysis==
'''''Parametric analysis '''''(also called '''''sensitivity analysis''''') involves varying the value of an input variable to examine its effect on a selected output. Performing sensitivity analysis often provides useful insights into how small changes in input variable values affect the desired outcome.

Because the [[importance analysis]] in the section “Importance analysis” revealed that ''Appreciation rate ''caused most of the uncertainty in ''Difference between buying and renting, ''you will start the [[parametric analysis]] with that input variable. You will change ''Appreciation rate''’s definition from a probability distribution to a list of alternative values, and analyze the effect on the ''Difference between buying and renting ''output.

Before proceeding, click the edit button [[File:Chapter 3.10a.png]] in the toolbar to switch into edit mode. In edit mode you can modify the model: adding and removing nodes, and modifying existing nodes. Then click the key icon [[File:Chapter 3.10b.png]] to open the [[Attribute panel]], then select the ''Appreciation rate ''node, and then select '''Definition '''from the [[Attribute dropdown menu]] to view its definition.

:{{Release||4.6|[[File:Chapter 3.10.png]]}}{{Release|5.0||[[File:Chapter 3.10_v5.0.png]]}}

When the Definition [[attributes|attribute]] is displayed, the [[Expression popup menu]] [[File:Chapter 3.10c.png]] appears.

Before proceeding, click the [[toolbar|edit tool]] [[File:Chapter 3.10a.png]] to switch to edit mode.

The [[Expression popup menu]] allows you to change the [[definition]] of a variable to one of several different types of expressions.

Expression types include:
* Expression, or mathematical formula [[File:Chapter 3.10d.png]]
* List [[File:Chapter 3.10e.png]]
* List of Labels [[File:Chapter 3.10f.png]]
* Table [[File:Chapter 3.10g.png]]
* Probability table [[File:Chapter 3.10g.png]]
* Distribution [[File:Chapter 3.10c.png]]
* Choice [[File:Chapter 3.10h.png]]

You will now use [[the Expression popup menu]] to change the definition of ''Appreciation rate'' from a probability distribution to a list. You will redefine ''Appreciation rate'' as a list of alternative values from -10% to 10%.

:[[File:Chapter 3.11.png]]

:[[File:Chapter 3.12.png]]

Note that the icon on the [[Expression popup menu]] changes to indicate that '''List''' [[File:Chapter 3.10e.png]] is selected.

When a definition is first changed to a list, a cell (indicated by a box around it) appears in the definition. The first cell in the list initially contains the expression that was previously in the definition. In this case, you see the expression for a [[normal]] distribution (Normal(Inflation,3)).

You will replace the entry with a number and add cells to perform [[parametric analysis]].

:[[File:Chapter 3.13.png]]

<tip>In Analytica, you add cells to a list by pressing the main Enter key, not the numeric keypad Enter key.</tip>

A new cell appears with the value -9. Change its value to -5. After you have entered two values, as you press ''Enter'' to add a new cell, Analytica automatically fills in the new cell with a value based on the difference between the last two values. You can override the automatic value by typing the desired value.

:[[File:Chapter 3.14.png]]

:[[File:Chapter 3.15.png]]

:[[File:Chapter 3.16.png]]

Pivot the graph as follows:

:[[File:Chapter 3.17.png]]

The resulting graph shows the [[mid]] value of buying and renting as a function of ''Appreciation rate'', which varies from -10% to 10%, as you just entered.

''Appreciation rate'' is informally called an '''''index''''' because it characterizes a dimension of another variable’s value, in this case, ''Costs of buying and renting''.

The graph shows that at an ''Appreciation rate'' of about -5% per year, renting and buying costs the same. If it is less than -5%, it would be better to rent; if it is greater than -5%, it would be better to buy.

:[[File:Chapter 3.18-updated.png]]

The table shows the values computed for each parameterized value of ''Appreciation rate''.

:[[File:Chapter 3.19-updated.png]]

==Evaluate alternative decisions==
Analytica allows you to perform sensitivity analysis on several variables simultaneously.

In this section, you will change ''Buying price'' to compare results based on alternative decisions. In doing so, you will perform [[parametric analysis]] on both ''Buying price'' and ''Appreciation rate'' at the same time.

:[[File:Chapter 3.20-updated.png]]

:[[File:Chapter 3.21-updated.png]]

The first cell in this list contains the expression for the previous definition, 140K. You will change this value, and add additional cells, as you did in previous steps.

:[[File:Chapter 3.22-updated.png]]

:[[File:Chapter 3.23-updated.png]]

The [[Result window]] appears displaying the variable’s mid value. The ''Difference between buying and renting variable'' is three curves, one for each ''Buying price''. Below the graph is a key to identify each curve.

When you examine the mid value results, you can see that only a $160K home, coupled with an appreciation rate of -2%/year or less, or a $140K home, coupled with an appreciation rate of -6%/year or less, results in renting being cheaper than buying. So, what is the best buy, a 120K home or a 160K home? That depends on what you anticipate the appreciation rate will be. For appreciation rates less than 9% per year, the less expensive home is the better investment. For higher appreciation rates above 9%, the more expensive home provides a larger return.

:[[File:Chapter 3.24-updated.png]]

Remember that the cost of renting has been held constant. To further investigate the effect of this, you will examine the Costs of renting and buying node.

:[[File:Chapter 3.25-updated.png]]

:[[File:Chapter 3.26-updated.png]]

:[[File:Chapter 3.27-updated.png]]

The result has three dimensions, ''Buying price, Buy or rent,'' and ''Appreciation rate'', shown in the figure above.

Because only two dimensions can be shown in the graph, Analytica chooses one value of the third dimension to display, in this case, ''Buying price'' equals '''$120K'''.

Use the navigating arrows to display different values of the ''Buying price'' index.

:[[File:Chapter 3.28-updated.png]]

:[[File:Chapter 3.29-updated.png]]

The graph changes to show the [[mid]] value of ''Costs of buying and renting'' given that the ''Buying price'' equals '''$160K'''.

:[[File:Chapter 3.30-updated.png]]

:[[File:Chapter 3.31-updated.png]]

:[[File:Chapter 3.32-updated.png]]

This table shows the [[mid]] value cost of buying for the parameterized values of ''Buying Price'' and ''Appreciation Rate''.

:[[File:Chapter 3.33-updated.png]]

This table shows that ''Cost to Rent'' does not vary with ''Buying Price'' or ''Appreciation rate''.

:[[File:Chapter 3.34-updated.png]]

==Summary==
In this chapter, you have:
* Performed importance analysis.
* Performed parametric analysis.
* Set up and compared alternative decisions.
The next chapter introduces you to creating a new Analytica model.

You can quit Analytica at this point.

==See Also==
* [https://www.analyticacloud.com/acp/Client/AcpClient.aspx?inviteId=3&inviteCode=221703&subName=acp%20demos Play the Rent vs. Buy model in Analytica Cloud Player]
* [https://www.youtube.com/watch?v=scVOq29NMG4 Analyzing a model] (en explanatory video on YouTube)
* [[Example Models]]
* [[Example Models and Libraries]]
* [[Comparing results]]
* [[Importance analysis]]
* [[Parametric analysis]]
* [[Statistics, Sensitivity, and Uncertainty Analysis]]
* [[Sensitivity analysis functions]]
* [[The Sensitivity Analysis Library]]
* [[Tornado Plots]]
* [[Tutorial videos]]

<footer>Tutorial: Reviewing a model/ {{PAGENAME}} / Tutorial: Create a model</footer>

Tutorial: Reviewing a model

2018-06-01T17:34:29Z

KMullins:

[[Category:Analytica Tutorial]]
[[Category: Rent vs. Buy model]]
<breadcrumbs>Analytica Tutorial > {{PAGENAME}}</breadcrumbs>
{{ReleaseBar}}

This Tutorial page shows you how to explore a model by examining the ''Rent vs. Buy'' model's:
* Influence diagrams
* Variables
* Attributes
* Definitions
* Results

This assumes you have started Analytica and have opened the ''Rent vs. Buy'' model. If this is not the case, see [[Tutorial: Open a model to browse#Opening_the_Rent_vs._Buy_model|Opening the Rent vs. Buy model]]. If you are using the model as modified from [[Tutorial: Open a model to browse|Chapter 1]], change the value of ''Time horizon ''back to '''10''', the value of ''Monthly rent ''back to '''1200''', and the value of ''Buying price ''back to '''140K'''. Also change the ''Rate of inflation ''back to a normal distribution with a mean of '''3.5 '''and a standard deviation of '''1.3'''.

<br>

<center>
<iframe width="640" height="360" src="https://www.youtube.com/embed/mpF4xcmKaao" frameborder="0" allowfullscreen></iframe>

'''Tutorial Video:''' [https://youtu.be/mpF4xcmKaao Review/explore a model] (8 minutes)
</center>

<br>

<div style="column-count:2;-moz-column-count:2;-webkit-column-count:2">
__TOC__
</div>

==Recognizing influence diagrams==
In this chapter, you will delve into some of the details of the ''Rent vs. Buy'' model. You will not use the top diagram that you used in [[Tutorial: Open a model to browse|Chapter 1]].

:[[File:Chapter 2.1.png]]

The details of an Analytica model display in an [[Diagram window|influence diagram window]]. An influence diagram (shown below) is a graphical representation of a model, showing how different variables in the model interact with each other. A typical influence diagram consists of a number of '''''nodes''''' connected by '''''arrows'''''.

:{{Release||4.6|[[File:Chapter 2.2.png]]}}{{Release|5.0||[[File:Chapter_2_2b.png]]}}

'''''Nodes''''' represent variables and appear as boxes, ovals, hexagons, and other shapes. Different node shapes represent different types of variables. Analytica uses the term '''''variable''''' broadly to include anything that has a value or can be evaluated. Note that many of the variables have the same names as the inputs and output at the top diagram that you used in [[Tutorial: Open a model to browse|Chapter 1]]. The top diagram provides an easy way to see and change these nodes’ values.

'''''Arrows''''' connecting different variables indicate a relation between the variables. The arrow connecting ''Rate of inflation ''to ''Appreciation rate ''indicates that the value of the ''Appreciation rate ''variable depends on the value of the ''Rate of inflation ''variable. In the ''Rent vs. Buy ''model influence diagram, ''Cost to Buy ''depends on the ''Buying price'', ''Rate of inflation'', ''Appreciation rate'', ''Discount rate'', and ''Time horizon ''variables.

The following figure illustrates different types of nodes.

:[[File:Chapter 2.3.png]]

==Opening Object windows==
Every object in Analytica has an associated [[Object window]] containing detailed information about it. You can display the '''Object''' window of any variable by double-clicking its node in the [[Diagram window|influence diagram]].

:[[File:Chapter 2.4.png]]

Information about a variable is provided in a list of attributes. [[Attributes]] include the variable’s class (for example, decision, chance, or constant), identifier, units, title, description, definition, inputs, and outputs. See the illustration below.

:[[File:Chapter 2.5.png]]

<tip>You can enter numbers with a suffix abbreviation, so Buying Price can be defined as either 140K or 140000. A quick reference for these suffixes is given on [[Number formats]] page.</tip>

==Moving between Object windows==
You have opened the [[Object window]] of a variable (''Buying price'') by double-clicking its node in the [[Diagram window|influence diagram]].

The '''Object '''window contains a list of the variable’s '''''inputs '''''and '''''outputs''''', if there are any.

You can open the [[Object window]] for any input or output variable by double-clicking the one you wish to view.

:[[File:Chapter 2.6.png]]

Analytica opens the '''Object''' window for ''Mortgage loan amount''.

:[[File:Chapter 2.7.png]]

Note in the figure above that the '''''Title '''''of ''Mortgage loan amount ''is different from the variable’s [[identifier]], ''Mortgage''. The title is what the model user normally sees; the identifier is used as a mathematical symbol in the definitions of other variables that depend on this variable.

The [[definition]] of the ''Mortgage loan amount ''is an [[Expressions|expression]], the sum of ''Buying price ''and ''Down payment ''(which is a negative amount). The definition refers to these variables by their identifiers.

'''''Inputs '''''lists the identifiers and titles of the variables in the definition. ''Buying price'', the variable you just examined, is one of the inputs. The other input of ''Mortgage loan amount ''is ''Down payment''.

:[[File:Chapter 2.8.png]]

The [[Object window]] now displays the [[attributes]] of ''Down payment''.

:[[File:Chapter 2.9.png]]

==Using the Attribute panel==
As an alternative to viewing a variable’s attributes in a separate window, you can inspect them in the [[Attribute panel]], which is an auxiliary window pane that you can open below the influence diagram.

The [[Attribute panel]] allows you to rapidly examine one [[attributes|attribute]] at a time of any variable in the model. You select the variable you wish to view and select the attribute to examine from a popup menu.

The variable ''Buying price ''should be highlighted with a title in white, indicating that it is selected; if it is not, select it by clicking it once.

:[[File:Chapter 2.10.png]]

By default, Analytica displays the '''''description '''''of the selected node (e.g., ''Buying price'') in the [[Attribute panel]].

:[[File:Chapter 2.11.png]]

==Inspecting definitions in the Attribute panel==
The [[Attribute panel]] allows you to inspect any attribute of a variable.

In this section, you will see the [[definition]] of two variables that you viewed in the top-level diagram in [[Tutorial: Open a model to browse|Chapter 1]].

:[[File:Chapter 2.12.png]]

:[[File:Chapter 2.13.png]]

:[[File:Chapter 2.14.png]]

When a variable is defined as an '''''uncertainty distribution''''', a button appears in the '''Definition''' field.

:[[File:Chapter 2.15.png]]

In [[Tutorial: Open a model to browse|Chapter 1]] you saw that ''Rate of inflation'' is defined as a [[normal]] distribution with a [[mean]] of 3.5 and a [[Sdeviation|standard deviation]] of 1.3.

==Opening modules==
Analytica models generally contain '''''modules'''''. Each [[Modules and Libraries|module]] contains the details of a part of the model, also represented as an [[influence diagram]]. In the ''Rent vs. Buy'' model, ''Cost to Buy'' and ''Cost to Rent'' are both modules.

Modules can also contain other modules. In this manner, a large model with hundreds of variables can be organized into a hierarchy of modules, each small enough to be easily understood.

:[[File:Chapter 2.16.png]]

Analytica displays the influence diagram of the ''Cost to Buy'' [[Modules and Libraries|module]]. This module contains three additional modules: ''Out-of-pocket costs to own, Future sales proceeds,'' and ''Opportunity cost''.

:[[File:Chapter 2.17.png]]

The '''''input arrowhead''''' (without a trailing line) shows that the node to the right of the arrow has one or more inputs from outside this module.

The '''''output arrowhead''''' shows that the node to the left of the arrow has one or more outputs outside this module.

:[[File:Chapter 2.18.png]]

:[[File:Chapter 2.19.png]]

Analytica limits the number of open windows at each level of the model hierarchy to minimize clutter on your screen. See [[Managing windows]] in the [[Analytica User Guide]] for information on how to open more than one module [[Diagram window]] at a time.

:[[File:Chapter 2.20.png]]

The combined arrowhead, shown above, indicates that the node has one or more inputs from outside this module, plus the input variable in this module.

You can also navigate the model by tracking a variable’s [[User input nodes and user output nodes|inputs or outputs]].

:[[File:Chapter 2.22.png]]

The Out-of-pocket costs to own module diagram is brought to the front, with the Insurance node selected.

==Help balloons==
[[Help balloons]] pop up when you hover over a node for about a second, and display the title, units, and description for a variable. These allow you to browse information very rapidly without having to open the object window. Balloons do not appear when objects do not have the Help or Description attribute filled in.

:[[File:Chapter 2.24.png]]

:[[File:Chapter 2.23.png]]

==Inspecting values in the Attribute panel==
The [[Attribute panel]] allows you to view certain attributes, such as a variable’s '''''value''''', that are not (initially) displayed in an [[Object window]].

:[[File:Chapter 2.25.png]]

:[[File:Chapter 2.26.png]]

If '''''Value '''''was not previously computed, Analytica computes the variable’s value '''''deterministically''''', assuming that all of the input probability distributions are fixed at their median values. [[Mid]] value is an abbreviation for this deterministically computed value.

You can use the [[Attribute panel]] in this manner to examine the mid value of any variable in the model.

It is faster to compute a mid (deterministic) value than an uncertain (probabilistic) value, so it is useful for conducting initial checks of a model before performing any uncertainty analysis.

==Displaying results==
When you are viewing a model’s [[Diagram window|influence diagram]], you can evaluate any variable and display its value in a [[Result window]].

:[[File:Chapter 2.27.png]]

A [[Result window]] displays the [[Probability density and mass graphs|probability density function graph]] for this variable. Analytica displays the [[Uncertainty view of a result|uncertainty view]] that was most recently selected from the [[Uncertainty views|Uncertainty View]] popup menu, or that was saved with the model.

:[[File:Chapter 2.29-updated.png]]

<tip>The ''Rent vs. Buy ''model uses financial flow conventions: funds flowing in (received) have positive values; funds flowing out (expended) have negative values.</tip>

As an alternative to clicking the '''Result''' button [[File:Chapter 2.29.1.png]] and then selecting an uncertainty view, you can use the [[Result menu]] to evaluate a variable and select the [[Uncertainty view of a result|uncertainty view of the result]].

:[[File:Chapter 2.30.png]]

The [[Result window]] appears displaying the variable’s [[Distribution_Densities_Library#Cumulative_Probability_Functions|cumulative probability distribution]].

:[[File:Chapter 2.31.png]]

:[[File:Chapter 2.33.png]]

A single [[mid]] value appears in table view.

:[[File:Chapter 2.34.png]]

The [[mid]] value in [[Table view of a result|table view]] is the only result view available for a nonprobabilistic variable with a single value.

:[[File:Chapter 2.35.png]]

Analytica tells you that this is a nonprobabilistic value.

:[[File:Chapter 2.36.png]]

==Summary==
You now have browsed the ''Rent vs. Buy'' model by examining its influence diagrams, variables, attributes, definitions, and results. These are the basic techniques for exploring any Analytica model.

The next chapter shows you how to analyze the Rent vs. Buy model.

You can quit Analytica at this point.

==See Also==
<div style="column-count:2;-moz-column-count:2;-webkit-column-count:2">
* [https://www.analyticacloud.com/acp/Client/AcpClient.aspx?inviteId=3&inviteCode=221703&subName=acp%20demos Play the Rent vs. Buy model in Analytica Cloud Player]
* [https://www.youtube.com/watch?v=mpF4xcmKaao Exploring a model] (an explanatory video on YouTube)
* [[Tutorial videos]]
* [[Examining a Model]]
* [[Diagram window]]
* [[Creating Lucid Influence Diagrams]]
* [[Object Window]]
* [[Classes of variables and other objects]]
* [[Attributes]]
* [[Attribute panel]]
* [[Entering Attributes using the Attribute panel]]
* [[Definitions]]
* [[Import a module or library]]
* [[User input nodes and user output nodes]]
* [[Help balloons]]
* [[Result Tables and Graphs]]
* [[Result window]]
* [[Managing windows]]
</div>

<footer>Tutorial: Open a model to browse/ {{PAGENAME}} / Tutorial: Analyzing a model</footer>