Analytica Docs - User contributions [en]

Links or URL in model attributes

2025-12-07T20:45:58Z

Max: /* HTML markup in Text Attributes */

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

A '''''description''''', or other text attribute of a variable or other object, can contain a hyperlink to any web page{{Release|6.0||, or even to an Analytica expression to run when it is clicked}}. This is useful for linking to detailed explanations, data, references, or to related downloadable Analytica models. In [[browse mode]], hyperlinks are underlined in blue. When you click a hyperlink, your computer shows the indicated web page in your default web browser.

To add or edit a hyperlink (in edit mode), type the text that you want the user to see, select it, and press ctrl+k to open a dialog where you can edit the text and the link:
:[[image:Edit Hyperlink dialog.png]]
Select either <code>http://</code> or <code>https://</code>, enter the target URL and press OK. The text displays as a hyperlink. When you switch to browse mode, the HTML code displays as a hyperlink.

Or you can enter the link with standard HTML syntax of the form
<code><nowiki><a href="http://www.analytica.com/">Click here</a></nowiki></code>}}{{Release|5.3||type the text you want the user to see.

'''In edit mode''':

:[[File:Chapter9 21.png]]

'''In browse mode''':}}

:[[File:Chapter9 22.png]]

When you click on the link in browse mode, it opens the web page. When you click on the link in edit mode, you are given options to go to the page, change the link or remove the link.
:[[image:Hyperlink options.png]]
The '''Change''' option re-opens the ''Edit Hyperlink'' dialog shown above.

You can also view the HTML-like "markup" text in edit mode by right-clicking within the attribute text and selecting '''Toggle show markup'''.
:[[File:Chapter9 21.png]]

== Eval links ==
You can create a link that evaluates an Analytica expression when you click on it. To do so, select "eval:" in the dropdown.

:[[image:Hyperlink eval.png]]

Eval opens up numerous creative options, including:
* Calling [[ShowPdfFile]] to open a PDF file.
* Calling [[ShowWindow]] to show a particular object view (such as a result table, graph, and edit table, or to an object on a diagram, etc.).
* Display a [[MsgBox]] with some computed information (as in the example shown).

== HTML markup in Text Attributes ==

You can use appearance-related HTML tags in the Description of a text node and other objects (and other text-based attributes including user-defined attributes.) You use standard HTML syntax, like <code><html>...</html></code>. [[ACP]] renders these when the text node displays in a diagram You can include CSS styles inside styles attributes. Desktop Analytica renders only a subset of these HTML tags.

As of [[Analytica 7.0]], these HTML tags that have an effect in desktop Analytica (but in text nodes only when they display on a diagram) when the attribute is surrounded by <code><html>...</html></code> (they can be nested):
* Hyperlink: <code><a href="...">label</a></code>
* '''Bold''': <code>text</code>: bold
* ''Italic'': <code>text</code> or <code>text</code> (emphasis)
* Underline: <code>text</code>
* Strike-out: <code><s>text</s></code> or <code><strike>text</strike></code> or <code><del>text</del></code>
* In-line block: <code> ... </code>
* Non-inline block: <code><div>text</div></code>:
* Paragraph block: <code>text</code>:
* Line break: <code> </code>
* Ordered list: <code><ol> ... </ol></code> containing items tagged as <code><li>item</li></code>
* Unordered list: <code><ul> ... </ul></code> containing items tagged as <code><li>item</li> </code>.

If you use a non-supported HTML tag, it treats it as in-line blocks (same as <code> ... </code>)

You can specify <code>style="..."</code> attribute on any tag, such as
<nowiki><div style="color:red">some red text</div></nowiki>
but only a few CSS styles have any affect in desktop Analytica. Recognized tags (as of [[Analytica 6.6]]) are:
* <code>color</code>: Text color
* <code>background-color</code>: But with some rendering limitations

== History ==
The Edit Hyperlink dialog (a GUI for editing the hyperlinks) was added in [[Analytica 5.3]]. Prior to that, markup displayed in edit mode, hyperlinks in edit mode.

The ability to evaluate an arbitrary expression when the hyperlink is clicked was added in [[Analytica 6.0]].

The bold and italics tags were added in [[Analytica 6.5]].

The extended tags using <code><html></code> were added in [[Analytica 6.6]].

==See Also==
* [[OpenURL]]
* [[ReadFromUrl]]
* [[Read data from URL on internet]]
* [[Retrieving Content From the Web]]

<footer>Graphics, frames, and text in a diagram / {{PAGENAME}} / Analytica Free Edition</footer>

Formatted Text Literals

2025-11-17T19:38:41Z

Max: /* Array abstraction */

{{ReleaseBar}}

''New to [[Analytica 6.0]]''

A [[Formatted Text Literals|formatted text literal]] (''F-string'' for short) is a concise way to define text containing expressions, such as the values of variables.

==Introduction==

A [[Formatted Text Literals|formatted text literal]] (''F-string'' for short) starts with F or f preceding a text literal enclosed in double-quotes. It can include replacement expressions delineated by curly braces, which get replaced by the result of evaluating the expressions -- for example, if x=1 and y=2:
:<code>F"The value of x is {x}, y is {y} and their sum is {x+y}" → 'The value of x is 1, y is 2 and their sum is 3'</code>

You could get the same result using [[Text_Concatenation_Operator%3A_%26|text-concatenation]] as
:<code>"The value of x is " & x & ", y is " & y & " and their sum is " & (x+y)</code>
but the F-string version is more concise and easier to read.

The names [[Formatted Text Literals]] and [[F-Strings]] are borrowed from [https://docs.python.org/3/reference/lexical_analysis.html?highlight=formatting#formatted-string-literals Python]. [[Formatted Text Literals]] aren't really literals like normal single- or double-quoted text values. Strictly, they are expressions whose value is determined at evaluation time. But, we use that term because they have the syntactic appearance of literals.

== Syntax ==

A [[Formatted Text Literals|formatted text literal]] starts with either <code>F"</code> or <code>f"</code>, and ends with <code>"</code>. In other words, it is a double-quoted text value prefixed with an upper or lower case F. There can be no space between the F and the opening quote. You can insert expressions within the text using curly braces, <code>{expr}</code>. When it evaluates an F-String, it also evaluates any expressions in curly braces and substitutes in their results.

There is currently no single-quoted version of F-strings in Analytica, so you cannot write <code>f'Something'</code>. It must use double quotes is in <code>f"Something"</code>.

To embed a double quote (<code>"</code>), or curly brace (<code>{</code> or <code>}</code>) in the text part of an F-string, you must double the character. For example,
<pre>
F"An F-string has the form F""some text {{ an expression : format spec }} some more text""."
</pre>
which has the content: ''An F-string has the form F"some text { an expression : format spec } some more text".''

When the curly braces are not doubled, the content between them is parsed as an expression. Optionally, the expression can be followed by a colon (<code>:</code>) and a [[#Format Specifiers|format specifier]]. For example:
:<code>F"1/3 = {1/3 : %6}"</code> → "1/3 = 33.333333%"

When you omit a format specifier, the [[Number formats|number format]] for the current expression context is used, i.e., for the current variable or [[User-Defined Function]], which you set using the [[Number formats|number format dialog]].

== Array abstraction ==
F-strings array abstract in the usual way. When a curly-bracket expression evaluates to an array, it creates a text value for each cell. When you have more than one expression, the indexes of your final result will be the union of the indexes for all the expressions. For example:<code>
:[[LocalIndex]] X := 1..9;
:[[LocalIndex]] Y := 1..9;
:F"{X} * {Y} = {X*Y}"
</code>
returns a 2-D array having 81 cells:
<center>[[image:FstringExampleXxY.png]]</center>

A format specifier is static. It isn't computed and cannot vary along any index, so the same format specifier (if any) applies to every cell of the result.

== Format Specifiers ==
Format specifiers are optional, but when you want to specify the format, follow your expression with a colon and then with the format specifiers. F-String format specifiers are terse by design, so as to minimize the distraction from the content and keep your formatted text literal looking as much as possible like the final result. But being terse, they are also cryptic. Except for numeric parts, each element of the format is denoted by a single character. Analytica's format specifiers are similar to Python's, but not quite the same.

You don't need a format specifier when you've set the [[Number formats|Number Format]] of your variable or [[UDF]] to be as you'd like. Also, you have the option of using [[NumberToText]] around your expression for a more descriptive way to specify the format.

A format specifier can specify the following information:
* The number format for numeric values
* Minimum width (in characters) and alignment within that space
* The date template for date-time values
All three are optional, or you may specify more than one.

Parts that aren't explicitly specified are inherited from the current variable or [[UDF]]'s number format.

=== Number formats ===
A number format type can be one of the following characters:
* <code>S</code> or <code>s</code>: Suffix
* <code>E</code> or <code>e</code>: Exponential
* <code>G</code> or <code>g</code>: General
* <code>F</code> or <code>f</code>: Fixed point
* <code>I</code> or <code>i</code>: Integer
* <code>P</code>, <code>p</code> or <code>%</code>: Percent
* <code>B</code>: Boolean (Prints as True or False)
* <code>H</code>, <code>h</code>, <code>X</code> or <code>x</code>: Hexadecimal
* <code>b</code>: binary

The type can be followed by the number of digits or decimals, such as <code>G12</code> for General type with 12 digits. For suffix, exponential, general, hex and binary types, the number is the number of digits total, for fixed point and percent types it is the number of decimal places. See [[Number formats]].

The following characters specify additional components of the number format:
* <code>'!'</code>: Display full precision
* <code>0</code> or <code>z</code>: Show trailing zeros. If you use 0, it needs be separated in some way from the number of digits, such as by a space of '.'. E.g., F10 is Fixed point with 10 decimals, whereas F1.0 is fixed point with 1 decimal and trailing zeros.
* <code>,</code>: Show thousands separators
* ''space'' or <code>.</code>: Ignored characters.{{Release|6.3||
* <code>'j'</code> or <code>'J'</code> controls whether a [[Complex Numbers|complex number]] with zero imaginary part displays "+0j" or not. <code>'j'</code> displays it, <code>'J'</code> does not. (New to [[Analytica 6.3]])}}

A few options not available (if you need these, use [[NumberToText]]) are: Currency symbols, use of parentheses for negative numbers, control of the ordering of currency, sign and digits.

Examples:
:<code>F"π={Pi:!}"</code> → "π=3.141592653589793"
:<code>F"The 25th power of 3 is {3^25:I,}"</code> → "The 25th power of 3 is 847,288,609,443"
:<code>F"${profit:F2,0}"</code> → "$17,343,300.00"

=== Width and Alignment ===
When you specify a (minimum) width and alignment, the expression uses at least that number of characters, using spaces to pad unused space. The alignment character comes first, followed by the width, and both are required. The possible alignment characters are:
* <code>L</code> or <code><</code>: Left align
* <code>R</code> or <code>></code>: Right align
* <code>C</code> or <code>^</code>: Center align

Examples:
:<code>F"π≈{pi:R10G4}, π/2≈{pi:L10G4}, |π^2≈{pi:C10G4}|"</code> → "π≈     3.142, π/2≈1.571      , |π^2≈   9.87   |"
:<code>F"Cost=${Cost:I,R15}"</code>→[[image:FStringCurrencyLeft.png]]
:<code>F"Cost={F"${Cost:I,}":R15}"</code> →[[image:FStringCurrencyWithNumber.png]]

The last example shows how you can use a nested F-string to produce a fixed-width cost column while keeping the $ attached to the number.

=== Date template ===
The date template renders date-time values. This can be specified along with a number format, so that when an expression returns an array of values with some dates and some numbers, the number format is used for numbers and the date format for dates.

The date template is preceded by the letter <code>D</code>, and then continues to the closing curly brace. The date format therefore must be last and come after any alignment and width or number format. Any spaces that appear after the D and before curly brace become part of the final text. The date template specified in an F-string cannot contain curly braces. Otherwise, it uses the same conventions as the date template in the number format dialog.

Example:
* <code>F"The current time is {Today(true):Dhh:mm:ss tt}"</code> → "The current time is 03:31:38 PM"
* <code>F"In the US it is {Today():DMM/dd/yyyy}, but in Europe it is {Today():Ddd/MM/yyyy}."</code> →
*:::"In the US it is 03/24/2021, but in Europe it is 24/03/2021."

== See Also ==

* [[Text_Concatenation_Operator%3A_%26|The text-concatenation operator, &]]
* [[NumberToText]]
* [[Number formats]]
* [[Text values]]
* [[JoinText]]

Other Procedural Functions

2025-10-09T16:55:37Z

Max: /* EvaluateScript(t) */

[[Category: Analytica User Guide]]
[[Category: Functions]]
<breadcrumbs> Analytica User Guide > Procedural Programming > {{PAGENAME}}</breadcrumbs> 

==CurrentDataFolder(''folderPath'')==

Sets the current data folder to «folderPath». The '''''current data folder''''' is the folder used by functions that read data files such as [[ReadTextFile]](), [[WriteTextFile]](), and [[SpreadsheetOpen]]() when their filename parameter contains no other path. When starting a model, it is the current model folder that contains the model. Specifying a path as a parameter to the function changes the current data folder to that path. If «folderPath» is omitted, it returns the path to the current data folder. See [[CurrentDataFolder]]().

==CurrentModelFolder(folderPath)==

Sets the current model folder to «folderPath». The '''''current model folder''''' is the folder into which the model (and submodules) are saved, by default. When starting a model, it is the folder containing the model. You can change it by selecting a different folder directly using the folder browser from '''Save as''', or by using this function. If «folderPath» is omitted, it returns the path to the current model folder. See [[CurrentModelFolder]]().

==Evaluate(e)==

If «e» is a text value, [[Evaluate]](e) tries to parse «e» as an Analytica expression, evaluates it, and returns its value. For example:
:<code>Evaluate('10M /10') → 1M</code>

One use for [[Evaluate]](e) is to convert a number formatted as text into a number it can compute with, for example:
:<code>Evaluate('1.23456e+10') → 12.3456G</code>

If «e» is an expression that generates a text value, it evaluates the expression, and then parses and evaluates the resulting text value. For example:
:<code>(VAR x := 10; Evaluate(x & "+" & x)) → 20</code>

If «e» is a number or expression that is not a text value, it just returns its value:
:<code>Evaluate(10M /10) → 1M</code>

If «e» is a text value that is not a valid expression — for example, if it has a syntax error — it returns [[Null]].

Like other functions, it evaluates the parameter as mid (deterministic) or prob (probabilistic), according to the context in which it is called.

[[Evaluate]](e) parses and evaluates text «e» in a global context. Thus, «e» cannot refer to local variables, local indexes, or function parameters defined in the definition that uses [[Evaluate]](e). For example, this would give an evaluation error:
:<code>Variable A := (VAR r := 99; Evaluate('r^2'))</code>

If <code>e</code> evaluates to a handle before it is passed to the function, then that object is evaluated and its (mid or sample) value is returned.

===Evaluate and dependencies===

Analytica’s dependency mechanism does not work with variables or functions whose identifiers appear inside the text parameter of [[Evaluate]](). For example, consider:
:<code>Variable B := Evaluate("F(A)")</code>
:<code>Variable C := F(A)</code>

Initially <code>B</code> and <code>C</code> compute the same value. If you then change the definition of function <code>F</code> or variable <code>A</code>, Analytica’s dependency maintenance ensures that <code>C</code> is recomputed when needed using the new definition of <code>F</code> and <code>A</code>. But, <code>B</code> does not know it depends on <code>F</code> and <code>A</code>, so is not recomputed, and can become inconsistent with the new values for <code>F</code> and <code>A</code>. In rare cases, you might intentionally want to break the dependency, in which case [[Evaluate]]() is appropriate; otherwise, use it only with care.

== InvalidateResult(x) ==
''(Requires [[Analytica 5.0]] or higher)''

Use [[InvalidateResult]] from an [[OnClick]] or [[OnChange]] event to invalidate a previously computed and cached result for variable «x». This is useful when «x» depends on something random or something that may have changed. For example, if «x» generates some random testing data, you could use this to refresh with a new random sample. If «x» reads data from an external data source, use this to force it to refresh the data.

You never have to worry about explicitly invalidating results in your model when inputs within the model change. Analytica tracks dependencies and automatically invalidates caches results with an input within the model that it depended on changes.

==EvaluateScript(t)==

This function evaluates a text value <code>t</code> as if it was [[Typescript]]. This lets you use Typescript [[Commands]] that aren’t available in expressions.

<Tip Title="Tip ">Avoid using [[EvaluateScript]](t) except from event attributes (<code>OnClick</code>, <code>OnChange</code> or <code>Script</code>), or functions called from event attributes. This minimizes the danger of undermining the no-side effects rule.</Tip>

==GetProcessInfo(item)==

Returns information about the current Analytica process from the Windows operating system. There are a large number of recognized values for «item», and for a complete list see [[GetProcessInfo]](). Some of the possible values for «item» are: <code>"Process ID", "Thread ID", "Computer Name", "User Name", "Windows Version", "Command Line", "Total RAM", "Total Virtual", "Free RAM", "Private Bytes".</code>
:<code>GetProcessInfo("User Name") → "Drice"</code>

You can also access the value of an environment variable as <code>item: name</code>.
:<code>GetProcessInfo("HOMEPATH”) → "\Users\Drice"</code>

A few options provide information about Analytica’s state: <code>"User Objects", "Total Objects".</code>
:<code>GetProcessInfo("User Objects") → 76</code>

==GetRegistryValue(root, subfolder, name)==

Reads a value from the Windows system registry. This can be quite useful if you install your Analytica model as part of a larger application, and if your model needs to find certain data files on the user’s computer (for example, for use with [[ShowPdfFile]](), [[ReadTextFile]](), or [[RunConsoleProcess]]()). The locations of those files could be stored in the registry by your installer, so that your model knows where to look. See [[GetRegistryValue]]().

'''Example:'''
:<code>GetRegistryValue("HKEY_CURRENT_USER", "Software/MyCompany/MyProduct", "FileLocation")</code>

==IgnoreWarnings(expr)==

Evaluates its parameter «expr», and returns its value, while suppressing most [[warnings]] that might otherwise be displayed during the evaluation. It is useful when you want to evaluate an expression that generates warnings, such as divide by zero, that you know are not important in that context, but you do not want to uncheck the option ''Show Result Warnings'' in the [[Preferences dialog]], because you do want to see warnings that might appear in other parts of the model. See [[IgnoreWarnings]]().

==IsResultComputed(x)==

Returns <code>1</code> if the value of «x» is computed when the function is evaluated. To test whether the sample value of «x» has been computed, use <code>Sample(IsResultComputed(x))</code>, or to test the mid value use <code>Mid(IsResultComputed(x))</code>. See [[IsResultComputed]]().

==OpenURL(url)==

Opens «url» in a browser window, using your default browser. See [[OpenURL]]().

==ShowPdfFile(filename)==

Opens «filename» using Adobe Reader or Acrobat if one is installed on this computer and the file is a PDF document. [[ShowPdfFile]]() is most useful when called from a button script, for example, as a way to provide the user of your model with a way to open a user guide for your model.

==Try(expr, catch, ''errorNum'')==

Attempts to evaluate and return the result for «expr». If an evaluation error occurs directly in «expr», or in a [[User-Defined Function]] (UDF) called from «expr», then «catch» is evaluated without reporting the error. See [[Try]]().

'''Example:'''
:<code>Try(COMCreateObject("MSXML"), catch: Null )</code>

Inside the «catch» expression, you can refer to local variables named <code>ErrorText</code>, <code>ErrorNumber</code> and <code>ErrorLocation</code>, containing information about the error. <code>ErrorLocation</code> contains a handle to the object where the error occurred. You can re-issue the error from within the catch expression by calling [[ReThrow]](). In some cases, you might want to change the error text to your own by calling [[Error]]().

You may optionally specify specific error numbers to catch using the «errorNum» parameter:
:<code>Try(COMCreateObject("MSXML"),</code>
:<code>errorNum: 42770, 43033, 43034,</code>
:<code>catch: Error("You don’t have MSXML installed")</code>
:<code>)</code>

To find the error number for the «errorNum» parameter, set your catch expression to [[MsgBox]](ErrorNumber) and cause the error to occur. Once you have the number or numbers, reset your «catch» expression as you would like it.

[[Try]]() does not suppress or catch warnings. For that, use [[IgnoreWarnings]]().

== See Also ==
<div style="column-count:2;-moz-column-count:2;-webkit-column-count:2">
* [[CurrentDataFolder]]()
* [[CurrentModelFolder]]()
* [[Evaluate]]()
* [[EvaluateScript]]()
* [[GetProcessInfo]]()
* [[GetRegistryValue]]()
* [[IgnoreWarnings]]()
* [[IsResultComputed]]()
* [[OpenURL]]()
* [[ShowPdfFile]]()
* [[Try]]()
* [[ReThrow]]()
* [[System Functions]]
</div>

<footer>Dialog Functions / {{PAGENAME}} / Reference sections</footer>

CopyToClipboard

2025-09-12T21:39:44Z

Max: /* CopyToClipboard( content, format, empty ) */

[[Category:User-interface functions]]

''New to [[Analytica 6.5]]''

== CopyToClipboard( content'', format, empty'' ) ==

Puts «content» onto the system clipboard so that you can paste it elsewhere into Analytica or another application. It replaces anything previously on the clipboard.

=== Parameters ===

; content : The data to be placed on the clipboard--usually text, an image, or an [[In-memory binary data terms|in-memory binary data term]].
; format : (Optional) The name of a format to be posted, such as "text", "bitmap", or a custom format name such as "PNG", "HTML Format", etc. It is generally not needed when posting text or an image since it figures out the usual formats automatically, but it is need it when posting binary data.
; empty : (Optional) When omitted or True, it empties the previous content of the clipboard before posting. When False, it adds the format to the content already there. You can use <code>empty:False</code> to post multiple formats.

== Example usage ==

=== Copying text to the clipboard ===

[[CopyToClipboard]]( "hello world" )

=== Copying an image to the clipboard ===

[[Local]] img := [[ReadImageFile]]( "", true );
[[CopyToClipboard]]( img )

If you were to select a PNG file, this would post both a "bitmap" format as well as a "PNG" format. On the other hand, if you post:

[[CopyToClipboard]]( img, "PNG" )

it would post only the "PNG" format without the "bitmap" format. Beware that it does not check that your image really is a PNG! "PNG" is not a standard format, but it is commonly used as a custom format, such that many applications recognize it.

=== Copying HTML format to clipboard ===

A HTML format can be useful when you want to include formatting. However, this is not a standard format. Gmail uses a custom format named "HTML Format", but it requires more that just HTML content. A header is required before the HTML as illustrated here:

<pre>
Version:0.9
StartHTML:0000000100
EndHTML:0000000105
StartFragment:0000000099
EndFragment:0000000198
<!DOCTYPE html>
<html>
<body>
<h1>Example</h1>
This illustrates the <code>"HTML Format"</code> clipboard type used by gmail.
</body>
</html>
</pre>

The StartHTML, EndHTML, StartFragment, and EndFragment offsets indicate the positions of the HTML content and the fragment within the clipboard data. The positions are represented by zero-padded 10-digit numbers. The StartFragment and EndFragment comments are also necessary.

== Posting multiple formats ==

You can post data in multiple formats. It doesn't even have to be the same content. For example:

[[Local]] url := "https://analytica.com/wp-content/uploads/2023/07/logo.png";
[[Local]] logo := [[ReadFromURL]]( url );
[[CopyToClipboard]]( logo );
[[CopyToClipboard]]( url, format: "source_url", empty:False );
[[CopyToClipboard]]( "logo.png", format: "text", empty:False )

Slider

2025-08-31T17:14:56Z

Max: /* Slider( val..., domain, styles, ..., resultIndex, returnRef ) */

''New to [[Analytica 6.3]]''

[[Category:Top level functions]]
[[Category:User-interface functions]]

Use this function to create a slider control in a user input node or in an edit table cell.

A slider control has a horizontal track with one or more movable thumbs (a standard UI term) that are used to select a value, an interval, or multiple values. A slider can be continuous or discrete -- a discrete slider limits the thumb to a finite set of positions. Its Domain specifies the space of selectable values and thus determines whether it is continuous or discrete. A slider can also optionally include labels with tick marks.

== Slider( val...'', domain, styles, ..., resultIndex, returnRef'' )==

A slider can have one or more thumbs:
:{| border="0"
! Expression !! !! Control's appearance !! !! Result after evaluation
|-
| <code>Slider(0.5)</code> || → || [[image:slider(0.5).png]] || → || <code>0.5</code>
|-
|<code>Slider(0.5, 0.75)</code> || → || [[image:slider(0.5,0.75).png]] || → || <code>[0.5, 0.75]</code>
|-
|<code>Slider(0.1, 0.5, 0.75)</code> || → || [[image:slider(0.1,0.5,0.75).png]] || → || <code>[0.1, 0.5, 0.75]</code>
|}

All the parameters after «vals» are optional. If specified, you must use [[Call a function|named-parameter calling syntax]]. See below for details.

The number of value parameters determines the number of thumbs. It defaults to a <code>[[Continuous]](0,1)</code> scale, unless you specify a «domain» parameter or Domain attribute.

== To create a slider user input ==

# Enter [[Edit mode]]
# [[Tutorial%3A_Create_a_model#Creating_variable_nodes|Drag a new Variable or Decision node to the diagram]]
# Enter a Title, say: <code>Probability of Rain</code>
# Press [[image:ToolbarExprButton.png]] to edit its Definition
# Enter its Definition: <code>Slider(0.5)</code> [[image:GreenCheck.png]]
# From the the [[Object menu]] (or [[Right mouse button menus|Right-click menu]]) select '''Make User Input Node''' (or press ''Ctrl+m'').
# [[Tutorial%3A_Create_a_model#Moving_nodes|Drag the user input node]] to your desired location.

The user input node looks like this:
<center>[[image:Probability of rain slider.png]]</center>

Or if you enter the Definition as <code>Slider(0.5, styles:'LabelsBelow')</code>, it looks like this:
<center>[[image:Probability of rain slider with labels below.png]]</center>

== The value(s) ==

The first parameter, «val», is the current value. For example, here the value 0.5 is selected:
:<code>Slider(0.5)</code> → [[image:slider(0.5).png]]
As the user moves the thumb, it changes the value in this first parameter. For example, after dragging the slider, the Definition is now
:<code>Slider(0.660000026226)</code> → [[image:Slider(0.66).png]]
It stores continuous values at full precision, so you may see the value saved with many significant digits like this.

The number of values listed determines the number of thumbs in the slider. You create an interval slider by listing two values.
:<code>Slider(0.5, 0.75)</code> → [[image:slider(0.5,0.75).png]]
Here, 0.5 and 0.75 are the current values, which it updates when the user moves a thumb.

== Domain ==
The domain is the set of values that can you can select with the slider. You can specify the domain either with the Variable's [[Domain attribute]] or by specifying the «domain» parameter to the Slider function. When no domain is specified, the slider defaults to <code>[[Continuous]](0, 1)</code>, which allows any value between 0 and 1 to be selected.

=== Using the [[Domain attribute]] ===

Often it's betterto specify the [[Domain attribute]] rather than providing a «domain» parameter since it is easier to see once your UI is displaying the control. You can specify it with the [[Attribute panel]] by selecting '''Domain''' from the [[Attribute panel|Attribute menu]]. [[image:Domain on Attribute Choice.png|top]].

The Domain-type pulldown has these options: [[image:DomainPulldown5.png|top]].

Select [[Continuous]] if you want a continuous slider and specify the lower and upper bounds.

A discrete slider restricts the thumb(s) to a finite set of positions. You can select either [[Integer]], '''Explicit Values''', or '''Copy from Index'''. You can also compute the domain using '''Expression'''. This example uses '''Explicit Values''':
:[[image:Explicit Values for Domain.png]]

:<code>Slider('Bad', styles:'LabelsBelow')</code> → [[image:Slider from explicit values.png]]

=== Using the «domain» parameter ===

As an alternative to using the [[Domain attribute]], your can specify the domain directly as a parameter to the Slider functon. If both are specified, the parameter overrides the attribute. When you pass the domain as a parameter, you ''must'' use a [[Function calls and parameters|name-parameter calling convention]]. These examples show ways to specify the «domain» parameter:

*<code>Slider( 'Good', domain: [[Discrete]]('Horrible', 'Bad', 'Neutral', 'Good', 'Excellent') )</code>
*<code>Slider( 'Good', domain: ['Horrible', 'Bad', 'Neutral', 'Good', 'Excellent'] )</code>
*<code>Slider( 'D', domain: 'A' .. 'G' )</code>
*<code>Slider( 23, 54, domain: [[Continuous]](0, 100) )</code>
*<code>Slider( 4, domain: [[Integer]](1, 5) )</code>
*<code>Slider( 'Medium', domain: LMH)</code> { where LMH is an index name }

== Return value ==

A slider with one thumb returns its first parameter.
:<code>Slider(0.7)</code> → 0.7
:<code>Slider('C', domain:'A'..'Z')</code> → <code>'C'</code>

A slider with two or more thumbs returns a list of the values
:<code>Slider(0.3, 0.7)</code> → <code>[0.3, 0.7]</code>

When you provide a «resultIndex», the result is a 1-D array on that index.
:Index Quantile := <code>[10%, 50%, 90%]</code>

:<code>Slider(10,30,80, domain:[[Continuous]](0,200), resultIndex: Quantile)</code> → [[image:Slider resultIndex result.png|top]]

If you pass <code>True</code> to the «returnRef» parameter, a [[reference]] to the result is returned.

If you have a table of multi-thumb sliders (like interval sliders), then you should return references or use a «resultIndex» for all multi-thumb sliders in the table. Otherwise, each list returned by each multi-thumb slider becomes a separate implicit index, and multiple implicit indexes cannot be combined in the same array. The use of «returnRef» or «resultIndex» addresses that problem.

== Ordering ==

When a slider has 2 or more thumbs, the default is to constrain the ordering of the thumbs so that the left thumb cannot move past the right thumb. You can change this by using <code>styles:'Unordered'</code> as illustrated here.
:<code>Slider( 0.1, 0.2, 0.4, styles: 'Unordered' )</code>

== Appearance ==

There are many options (various styles, colors and track height) that alter the appearance sliders. In most cases, you'll want to adopt a consistent color and style scheme for all sliders in your model. To maintain consistency, you should configure the model-wide defaults and avoid explicitly specifying appearance parameters in the [[Slider]] function calls. Use the parameters to adjust parameters when you want a particular slider to deviate from the model-wide defaults.

=== Model-wide defaults ===
To control these model-wide defaults, make sure no node is selected, then use the menus to navigate to

::'''[[Definition menu|Definition]] / System variables / Settings / Slider style defaults / Edit table'''

:[[image:Slider style defaults table.png]]

=== Appearance parameters ===

The «styles» parameter accepts a comma-separated list of text options, as described in the next subsection. The subsection after that lists the numerous color parameters that you can specify. And finally, «trackHeight» accepts a single positive number, which is the height of the track (in pixels).

==== «Styles» parameter ====
The «styles» parameter accepts these options:
; <code>'Needle'</code>, <code>'Circle'</code>, <code>'Rectangle'</code>, <code>'Diamond'</code>, <code>'Block'</code>, <code>'Line'</code>, <code>'NoThumb'</code>: The thumb shape.
; <code>'RoundedEnds'</code>, <code>'FlatEnds'</code>: The track shape.
; <code>'LabelsNone'</code>,<code>'LabelsBelow'</code>,<code>'LabelsAtEnds'</code>: Whether and where labels appear.
; <code>'ShowSelect'</code>,<code>'HideSelect'</code>: Whether the area to the left of a single thumb, or between 2 thumbs, uses «selectColor».
; <code>'Ordered'</code>, <code>'Unordered'</code>: Whether multiple thumbs can cross over each other.

The options in each group above are mutually exclusive. If you do specify more than one, the one that appears last takes precedence. Multiple styles, one from each each group, can be specified in any order separated by commas, e.g.,
:<code>Slider( 0.2, styles: 'Circle','FlatEnds','LabelsAtEnds','ShowSelect')</code> → [[image:Slider Circle Flat AtEnds LeftSelect.png]]

==== Color parameters ====
The [[Color parameters|color parameter]] names are
* <code>trackColor</code>
* <code>trackOutlineColor</code>
* <code>selectColor</code>
* <code>thumbColor</code>
* <code>thumbOutlineColor</code>
Their meaning is illustrated here.
:[[image:sliderColors.png]]
(Depicted is <code>Slider( 0.2, 0.7, styles:'ShowSelect', trackColor:0x1000ff00, selectColor:0x200000ff, thumbColor:0x80ff80,0x8080ff, thumbOutlineColor:'red', trackOutlineColor:'Blue')</code>)

Each color parameter value can be specified using a color integer or a color name as described at [[Color parameters]].

Each of the color parameters (<code>trackColor</code>, <code>trackOutlineColor</code>, <code>selectColor</code>, and <code>thumbOutlineColor</code>), other than <code>thumbColor</code>, accepts a single color only. You can pass one or more colors to the <code>thumbColor</code> parameter, making it possible to have thumbs with different colors.

:<code>Slider(0.1,0.3,0.6, thumbColor:'red','white','blue')</code> → [[image:slider with red white blue thumbs.png]].

=== Thumb shapes ===
; <code>'Needle'</code>
:[[image:slider needle.png]]
; <code>'Circle'</code>
:[[image:slider circle.png]]
; <code>'Rectangle'</code>
:[[image:slider rectangle.png]]
; <code>'Diamond'</code>
:[[image:slider diamond.png]]
; <code>'Block'</code>
:[[image:slider block.png]]
:[[image:slider block trackheight20.png]]
:A block thumb looks better when used with a larger track height (shown are trackheight:8 and trackheight:20), and with <code>style:'FlatEnds'</code>.
; <code>'Line'</code>
:[[image:slider line.png]]
; <code>'NoThumb'</code>
:[[image:slider nothumb.png]]
:[[image:slider nothumb trackheight20.png]]
:The NoThumb style needs to show the selection (the <code>'ShowSelect'</code> style), which it turns on automatically unless you explicitly specify <code>styles:'HideSelect'</code>. We think it also work best with a larger track height (shown are trackheight:8 and trackheight:20), and with <code>style:'FlatEnds'</code>.

=== Labels ===
A slider control can appear with no labels (<code>styles:'LabelsNone'</code>), with the min and max label at each end (<code>styles:'LabelsAtEnds'</code>), or with labels below (<code>styles:'LabelsBelow'</code>) . These examples illustrate a slider with <code>'LabelsAtEnds'</code> and two sliders with <code>'LabelsBelow'</code>.

:[[image:slider label styles.png]]

The bottom user input node has its [[Node Style dialog|node style]] set to have the control on the left.

When using <code>'LabelsBelow'</code> the scale is chosen automatically. If some labels don't appear, it is probably because they would overlap if all the labels were shown. Making the slider wider may help. There are no options to manually scale, to control which labels are omitted to prevent overlap, or to control how many continuous tic marks or the increment between them. Also, the auto-scaling has some limitations currently including: (a) When deciding which labels to omit, discrete numeric scales, including Integer ranges, are not interpreted numerically, so it doesn't attempt to select round integers - it simply tries to include as many labels as possible without overlap, (b) It is not date or time aware, so may not display labels on "even" dates.

=== Track end styles ===

Use a <code>'RoundedEnds'</code> or <code>'FlatEnds'</code> style to control the track shape.

:<code>Slider( 0.3, styles:'RoundedEnds' )</code> → [[image:Slider rounded ends.png]]

:<code>Slider( 0.3, styles:'FlatEnds' )</code> → [[image:Slider flat ends.png]]

Rounded ends are the out-of-the-box default (although you can change the model-wide default in the ''Slider style defaults'' system variable). We think flat ends work better with the <code>'Block'</code> and <code>'NoThumb'</code> thumb styles, e.g.,

:<code>Slider( 0.3, styles:'Block','FlatEnds','ShowLeftSelect', trackHeight:15, selectColor:'Lime',thumbColor:'LightGreen' )</code>
→ [[image:Slider block green.png]]

=== Track Height ===
The track height can change the feel of the slider control substantially. The following compares track heights of 8, 1 and 20.
:[[image:slider track heights 8 1 20.png]]

Note that when the track height is set to 1, you can't see the trackColor or selectColor, unless you set <code>trackOutlineColor:'Transparent'</code>. In the second slider above, we see the track outline color.

=== ShowLeftSelect ===
In the model-wide defaults, the '''ShowLeftSelect''' checkbox controls whether the select color appears to the left of the thumb in the case where the slider has one thumb. The select color shows up between thumbs for interval sliders even when this is off. Here we see a slider with this unchecked and then with it checked.
:[[image:slider HideLeftSelect.png]]
:[[image:slider ShowLeftSelect.png]]

For an interval slider, the model-wide default does not turn off the selection color between the thumbs. This interval slider displays the same regardless of whether ShowLeftSelect is on in the model-wide defaults.
:[[image:slider interval.png]]

The styles parameter options <code>'ShowSelect'</code> and <code>'HideSelect'</code> override the '''ShowLeftSelect''' model-wide setting for one-thumb and interval-sliders alike.
:<code>Slider(25,64, styles:'HideSelect')</code> → [[image:slider interval hide select.png]]

== See Also ==
* [[User Input nodes]]: <Add Slider into this page, and also Multichoice>
* [[Choice]] <Add multichoice into this page>
* [[Checkbox]]

Slider

2025-08-31T17:11:45Z

Max: /* The value(s) */

''New to [[Analytica 6.3]]''

[[Category:Top level functions]]
[[Category:User-interface functions]]

Use this function to create a slider control in a user input node or in an edit table cell.

A slider control has a horizontal track with one or more movable thumbs (a standard UI term) that are used to select a value, an interval, or multiple values. A slider can be continuous or discrete -- a discrete slider limits the thumb to a finite set of positions. Its Domain specifies the space of selectable values and thus determines whether it is continuous or discrete. A slider can also optionally include labels with tick marks.

== Slider( val...'', domain, styles, ..., resultIndex, returnRef'' )==

A slider can have one or more thumbs:
:{| border="0"
! Expression !! !! Control's appearance !! !! Result after evaluation
|-
| <code>Slider(0.5)</code> || → || [[image:slider(0.5).png]] || → || <code>0.5</code>
|-
|<code>Slider(0.5, 0.75)</code> || → || [[image:slider(0.5,0.75).png]] || → || <code>[0.5, 0.75]</code>
|-
|<code>Slider(0.1, 0.5, 0.75)</code> || → || [[image:slider(0.1,0.5,0.75).png]] || → || <code>[0.1, 0.5, 0.75]</code>
|}

All parameters after «vals» are optional, but if specified, must be specified with [[Call a function|named-parameter calling syntax]]. The parameters are described in the sections below.

The number of values specified determines the number of thumbs. Notice that it defaults to a <code>[[Continuous]](0,1)</code> scale.

== To create a slider user input ==

# Enter [[Edit mode]]
# [[Tutorial%3A_Create_a_model#Creating_variable_nodes|Drag a new Variable or Decision node to the diagram]]
# Enter a Title, say: <code>Probability of Rain</code>
# Press [[image:ToolbarExprButton.png]] to edit its Definition
# Enter its Definition: <code>Slider(0.5)</code> [[image:GreenCheck.png]]
# From the the [[Object menu]] (or [[Right mouse button menus|Right-click menu]]) select '''Make User Input Node''' (or press ''Ctrl+m'').
# [[Tutorial%3A_Create_a_model#Moving_nodes|Drag the user input node]] to your desired location.

The user input node looks like this:
<center>[[image:Probability of rain slider.png]]</center>

Or if you enter the Definition as <code>Slider(0.5, styles:'LabelsBelow')</code>, it looks like this:
<center>[[image:Probability of rain slider with labels below.png]]</center>

== The value(s) ==

The first parameter, «val», is the current value. For example, here the value 0.5 is selected:
:<code>Slider(0.5)</code> → [[image:slider(0.5).png]]
As the user moves the thumb, it changes the value in this first parameter. For example, after dragging the slider, the Definition is now
:<code>Slider(0.660000026226)</code> → [[image:Slider(0.66).png]]
It stores continuous values at full precision, so you may see the value saved with many significant digits like this.

The number of values listed determines the number of thumbs in the slider. You create an interval slider by listing two values.
:<code>Slider(0.5, 0.75)</code> → [[image:slider(0.5,0.75).png]]
Here, 0.5 and 0.75 are the current values, which it updates when the user moves a thumb.

== Domain ==
The domain is the set of values that can you can select with the slider. You can specify the domain either with the Variable's [[Domain attribute]] or by specifying the «domain» parameter to the Slider function. When no domain is specified, the slider defaults to <code>[[Continuous]](0, 1)</code>, which allows any value between 0 and 1 to be selected.

=== Using the [[Domain attribute]] ===

Often it's betterto specify the [[Domain attribute]] rather than providing a «domain» parameter since it is easier to see once your UI is displaying the control. You can specify it with the [[Attribute panel]] by selecting '''Domain''' from the [[Attribute panel|Attribute menu]]. [[image:Domain on Attribute Choice.png|top]].

The Domain-type pulldown has these options: [[image:DomainPulldown5.png|top]].

Select [[Continuous]] if you want a continuous slider and specify the lower and upper bounds.

A discrete slider restricts the thumb(s) to a finite set of positions. You can select either [[Integer]], '''Explicit Values''', or '''Copy from Index'''. You can also compute the domain using '''Expression'''. This example uses '''Explicit Values''':
:[[image:Explicit Values for Domain.png]]

:<code>Slider('Bad', styles:'LabelsBelow')</code> → [[image:Slider from explicit values.png]]

=== Using the «domain» parameter ===

As an alternative to using the [[Domain attribute]], your can specify the domain directly as a parameter to the Slider functon. If both are specified, the parameter overrides the attribute. When you pass the domain as a parameter, you ''must'' use a [[Function calls and parameters|name-parameter calling convention]]. These examples show ways to specify the «domain» parameter:

*<code>Slider( 'Good', domain: [[Discrete]]('Horrible', 'Bad', 'Neutral', 'Good', 'Excellent') )</code>
*<code>Slider( 'Good', domain: ['Horrible', 'Bad', 'Neutral', 'Good', 'Excellent'] )</code>
*<code>Slider( 'D', domain: 'A' .. 'G' )</code>
*<code>Slider( 23, 54, domain: [[Continuous]](0, 100) )</code>
*<code>Slider( 4, domain: [[Integer]](1, 5) )</code>
*<code>Slider( 'Medium', domain: LMH)</code> { where LMH is an index name }

== Return value ==

A slider with one thumb returns its first parameter.
:<code>Slider(0.7)</code> → 0.7
:<code>Slider('C', domain:'A'..'Z')</code> → <code>'C'</code>

A slider with two or more thumbs returns a list of the values
:<code>Slider(0.3, 0.7)</code> → <code>[0.3, 0.7]</code>

When you provide a «resultIndex», the result is a 1-D array on that index.
:Index Quantile := <code>[10%, 50%, 90%]</code>

:<code>Slider(10,30,80, domain:[[Continuous]](0,200), resultIndex: Quantile)</code> → [[image:Slider resultIndex result.png|top]]

If you pass <code>True</code> to the «returnRef» parameter, a [[reference]] to the result is returned.

If you have a table of multi-thumb sliders (like interval sliders), then you should return references or use a «resultIndex» for all multi-thumb sliders in the table. Otherwise, each list returned by each multi-thumb slider becomes a separate implicit index, and multiple implicit indexes cannot be combined in the same array. The use of «returnRef» or «resultIndex» addresses that problem.

== Ordering ==

When a slider has 2 or more thumbs, the default is to constrain the ordering of the thumbs so that the left thumb cannot move past the right thumb. You can change this by using <code>styles:'Unordered'</code> as illustrated here.
:<code>Slider( 0.1, 0.2, 0.4, styles: 'Unordered' )</code>

== Appearance ==

There are many options (various styles, colors and track height) that alter the appearance sliders. In most cases, you'll want to adopt a consistent color and style scheme for all sliders in your model. To maintain consistency, you should configure the model-wide defaults and avoid explicitly specifying appearance parameters in the [[Slider]] function calls. Use the parameters to adjust parameters when you want a particular slider to deviate from the model-wide defaults.

=== Model-wide defaults ===
To control these model-wide defaults, make sure no node is selected, then use the menus to navigate to

::'''[[Definition menu|Definition]] / System variables / Settings / Slider style defaults / Edit table'''

:[[image:Slider style defaults table.png]]

=== Appearance parameters ===

The «styles» parameter accepts a comma-separated list of text options, as described in the next subsection. The subsection after that lists the numerous color parameters that you can specify. And finally, «trackHeight» accepts a single positive number, which is the height of the track (in pixels).

==== «Styles» parameter ====
The «styles» parameter accepts these options:
; <code>'Needle'</code>, <code>'Circle'</code>, <code>'Rectangle'</code>, <code>'Diamond'</code>, <code>'Block'</code>, <code>'Line'</code>, <code>'NoThumb'</code>: The thumb shape.
; <code>'RoundedEnds'</code>, <code>'FlatEnds'</code>: The track shape.
; <code>'LabelsNone'</code>,<code>'LabelsBelow'</code>,<code>'LabelsAtEnds'</code>: Whether and where labels appear.
; <code>'ShowSelect'</code>,<code>'HideSelect'</code>: Whether the area to the left of a single thumb, or between 2 thumbs, uses «selectColor».
; <code>'Ordered'</code>, <code>'Unordered'</code>: Whether multiple thumbs can cross over each other.

The options in each group above are mutually exclusive. If you do specify more than one, the one that appears last takes precedence. Multiple styles, one from each each group, can be specified in any order separated by commas, e.g.,
:<code>Slider( 0.2, styles: 'Circle','FlatEnds','LabelsAtEnds','ShowSelect')</code> → [[image:Slider Circle Flat AtEnds LeftSelect.png]]

==== Color parameters ====
The [[Color parameters|color parameter]] names are
* <code>trackColor</code>
* <code>trackOutlineColor</code>
* <code>selectColor</code>
* <code>thumbColor</code>
* <code>thumbOutlineColor</code>
Their meaning is illustrated here.
:[[image:sliderColors.png]]
(Depicted is <code>Slider( 0.2, 0.7, styles:'ShowSelect', trackColor:0x1000ff00, selectColor:0x200000ff, thumbColor:0x80ff80,0x8080ff, thumbOutlineColor:'red', trackOutlineColor:'Blue')</code>)

Each color parameter value can be specified using a color integer or a color name as described at [[Color parameters]].

Each of the color parameters (<code>trackColor</code>, <code>trackOutlineColor</code>, <code>selectColor</code>, and <code>thumbOutlineColor</code>), other than <code>thumbColor</code>, accepts a single color only. You can pass one or more colors to the <code>thumbColor</code> parameter, making it possible to have thumbs with different colors.

:<code>Slider(0.1,0.3,0.6, thumbColor:'red','white','blue')</code> → [[image:slider with red white blue thumbs.png]].

=== Thumb shapes ===
; <code>'Needle'</code>
:[[image:slider needle.png]]
; <code>'Circle'</code>
:[[image:slider circle.png]]
; <code>'Rectangle'</code>
:[[image:slider rectangle.png]]
; <code>'Diamond'</code>
:[[image:slider diamond.png]]
; <code>'Block'</code>
:[[image:slider block.png]]
:[[image:slider block trackheight20.png]]
:A block thumb looks better when used with a larger track height (shown are trackheight:8 and trackheight:20), and with <code>style:'FlatEnds'</code>.
; <code>'Line'</code>
:[[image:slider line.png]]
; <code>'NoThumb'</code>
:[[image:slider nothumb.png]]
:[[image:slider nothumb trackheight20.png]]
:The NoThumb style needs to show the selection (the <code>'ShowSelect'</code> style), which it turns on automatically unless you explicitly specify <code>styles:'HideSelect'</code>. We think it also work best with a larger track height (shown are trackheight:8 and trackheight:20), and with <code>style:'FlatEnds'</code>.

=== Labels ===
A slider control can appear with no labels (<code>styles:'LabelsNone'</code>), with the min and max label at each end (<code>styles:'LabelsAtEnds'</code>), or with labels below (<code>styles:'LabelsBelow'</code>) . These examples illustrate a slider with <code>'LabelsAtEnds'</code> and two sliders with <code>'LabelsBelow'</code>.

:[[image:slider label styles.png]]

The bottom user input node has its [[Node Style dialog|node style]] set to have the control on the left.

When using <code>'LabelsBelow'</code> the scale is chosen automatically. If some labels don't appear, it is probably because they would overlap if all the labels were shown. Making the slider wider may help. There are no options to manually scale, to control which labels are omitted to prevent overlap, or to control how many continuous tic marks or the increment between them. Also, the auto-scaling has some limitations currently including: (a) When deciding which labels to omit, discrete numeric scales, including Integer ranges, are not interpreted numerically, so it doesn't attempt to select round integers - it simply tries to include as many labels as possible without overlap, (b) It is not date or time aware, so may not display labels on "even" dates.

=== Track end styles ===

Use a <code>'RoundedEnds'</code> or <code>'FlatEnds'</code> style to control the track shape.

:<code>Slider( 0.3, styles:'RoundedEnds' )</code> → [[image:Slider rounded ends.png]]

:<code>Slider( 0.3, styles:'FlatEnds' )</code> → [[image:Slider flat ends.png]]

Rounded ends are the out-of-the-box default (although you can change the model-wide default in the ''Slider style defaults'' system variable). We think flat ends work better with the <code>'Block'</code> and <code>'NoThumb'</code> thumb styles, e.g.,

:<code>Slider( 0.3, styles:'Block','FlatEnds','ShowLeftSelect', trackHeight:15, selectColor:'Lime',thumbColor:'LightGreen' )</code>
→ [[image:Slider block green.png]]

=== Track Height ===
The track height can change the feel of the slider control substantially. The following compares track heights of 8, 1 and 20.
:[[image:slider track heights 8 1 20.png]]

Note that when the track height is set to 1, you can't see the trackColor or selectColor, unless you set <code>trackOutlineColor:'Transparent'</code>. In the second slider above, we see the track outline color.

=== ShowLeftSelect ===
In the model-wide defaults, the '''ShowLeftSelect''' checkbox controls whether the select color appears to the left of the thumb in the case where the slider has one thumb. The select color shows up between thumbs for interval sliders even when this is off. Here we see a slider with this unchecked and then with it checked.
:[[image:slider HideLeftSelect.png]]
:[[image:slider ShowLeftSelect.png]]

For an interval slider, the model-wide default does not turn off the selection color between the thumbs. This interval slider displays the same regardless of whether ShowLeftSelect is on in the model-wide defaults.
:[[image:slider interval.png]]

The styles parameter options <code>'ShowSelect'</code> and <code>'HideSelect'</code> override the '''ShowLeftSelect''' model-wide setting for one-thumb and interval-sliders alike.
:<code>Slider(25,64, styles:'HideSelect')</code> → [[image:slider interval hide select.png]]

== See Also ==
* [[User Input nodes]]: <Add Slider into this page, and also Multichoice>
* [[Choice]] <Add multichoice into this page>
* [[Checkbox]]

MultiTable

2025-08-21T17:56:45Z

Max: /* Dimensionality */

[[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 Platform]] or [[Free Edition]]) 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)--i.e. normal Analytica array abstraction.

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.

== MultiTable vs. SubTable ==

A [[SubTable]] and [[MultiTable]] are very closely related. Each presents a table view of data that is located in one or more different sources. In each case, the table view can contain a mixture of editable and computed cells. They can even be nested in any combination -- i.e., each source a [[MultiTable]] can be another [[MultiTable]] or another [[SubTable]] (in which cases, the real location of the data is two (or more) steps away). There are cases where you can obtain the same table view using either a [[SubTable]] or a [[MultiTable]]. There are also cases where only one of the two will get you to your desired view (in these cases, it is usually theoretically possible to do it with either, but the wrong choice is excessively complex and inflexible). This brings up the question -- how do you figure out which one you need to use?

<code>[[SubTable]]( expr )</code> accepts a single expression. The ''expr'' has precisely the same form as one cell expression in a [[MultiTable]]. Thus, one question to ask is: Are you adding a new index (or indexes) to your view that will index the sources? If yes, then you probably want a [[MultiTable]]. If no, then you probably want a [[SubTable]].

The following example illustrates this idea ([[media:MultiTable or SubTable.ana|download this example model]]). You have two source tables, each indexed by <code>Move_num</code>:
:<code>Index Move_num := [1, 2, 3, 4, 5]</code>
:<code>Variable Whites_move := Table(Move_num)</code>
:<code>Variable Blacks_move := Table(Move_num)</code>

The source edit tables contain initially:
:[[image:whites_moves.png]][[image:blacks_moves.png]]

In the first variation, you want to combine these into an editable move table as follows:
:[[image:move_table.png]]
In this variation, the index <code>Side</code> indexes the source tables, so therefore, [[MultiTable]] is the correct option.

In the second variation, you want to combine these into a linear move sequence as follows:
:[[image:linear_move_sequence.png]]
This maps the sources to a new index
:<code>Index Turn := ['1W', '1B', '2W', '2B', '3W', '3B', '4W', '4B', '5W', '5B' ]</code>

In this case, the index, <code>Turn</code> indirectly indexes the source, but it doesn't directly index the sources. While it is possible to use a [[MultiTable]] with the index <code>Turn</code>, you would need to insert a separate expression in all 10 cells. If, in the future, you change the maximum number of moves, if take some work to get the new cells to automatically start with the correct cell default. So for this variation, a [[SubTable]] is a much better option than a [[MultiTable]]. One way to define the [[SubTable]] is as
:<code>[[SubTable]]( [[If]] [[Mod]](@Turn,2)=1 [[Then]] Whites_move[Move_num=Move_num_of_turn] [[Else]] Blacks_move[Move_num=Move_num_of_turn] )</code>

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

Tornado charts

2025-05-20T21:27:13Z

Max: /* Implementing a tornado analysis */

[[Category:Analytica User Guide]]
<breadcrumbs>Analytica User Guide > Statistics, Sensitivity, and Uncertainty Analysis > {{PAGENAME}}</breadcrumbs>
{{ReleaseBar}}

A tornado diagram is a common tool used to depict the sensitivity of a result to changes in
selected variables. It shows the effect on the output of varying each input variable at a time, keeping all the other input variables at their initial (nominal) values. Typically, you choose a “low” and a “high” value for each input. The result is then displayed as a special type of bar graph, with bars for each input variable displaying the variation from the nominal value. It is standard practice to plot the bars horizontally, sorted so that the widest bar is placed at the top. When drawn in this fashion, the diagram takes on the appearance of a tornado, hence its name. The figure below shows a typical tornado diagram.

:[[File:Chapter16_5.png]]

'''Create a tornado analysis:''' To perform a tornado analysis, you must:
# Select the result or output variable to perform the analysis on.
# Select the input variables that might affect the output.
# Decide what the low and high values are to be for each input variable.

'''''Note:''' The input variables do not need to be chance variables. In fact, tornado analysis is often applied to models with no chance variables.''

There are several options for selecting low and high values, including:
* Selecting the same absolute low and high levels for every input. This usually only makes sense if inputs are very homogeneous with identical nominal values.
* Selecting absolute low and high values separately for each input variable.
* Varying all inputs by the same relative amount, e.g., low = 90% of nominal, high = 110% of nominal.
* Varying all inputs between two given fractiles (aka percentiles, quartiles). This only makes sense if your inputs are uncertain variables. '''Example:''' Low = 10% fractile, High = 90% fractile, nominal = 50% fractile.

==Implementing a tornado analysis==

''For this example, assume we vary all inputs by the same percentage.''

# Create an index variable containing a list of input variable identifiers. Suppose this is called <code>Vars</code>.
# Create a variable, <code>Level</code>, and define it as a self-indexed table. (To do this, select '''Table''' from the [[expr]] menu, and select self as an index.) From the edit table, set the self-index labels to read low and high. Set the value corresponding to low to 90%, and set the value corresponding to high to 110%.
#:
#: [[File:Chapter16_6.png]]
#:
#Create a node, <code>Tornado_Analysis</code>. Assume that the output variable is <code>Net_value</code>. Define <code>Tornado_Analysis</code> as:
#: <code>WhatIfAll(Net_value, Vars, Level*Vars)</code>{{Release||4.6|

You can use array abstraction to produce a set of tornado diagrams, with each tornado itself indexed by additional dimensions. Additional dimensions are already included if your output variable is itself an array result, in which case you have a tornado diagram for each element in the output value’s array value.

The [[WhatIfAll]] function is typically the easiest way to implement tornado analysis in Analytica. Note that the third parameter to [[WhatIfAll]] controls the method by which inputs are varied for the analysis. For example:

* For the case where you select the same absolute low and high levels for every input, <code>Level</code> would be set to the absolute low and high values, and the third parameter to [[WhatIfAll]] would be simply <code>Level</code>.
* For the case where you select absolute low and high values separately for each input variable, you would index <code>Level</code> by <code>Vars</code>, fill in <code>Level</code>’s table appropriately, then set the third parameter to be just <code>Level</code>.
* And for the case where you vary all inputs between two given fractiles, you would set <code>Level</code> to the desired fractiles, and use the expression <code>[[GetFract]](Net_value, Level)</code> as the third parameter.

=== Graphing a tornado ===
It’s customary to graph a tornado with the names of the input variables are listed down the vertical axis, and the bars displaying the effect on the output horizontally:

# Select '''Show Result''' for the <code>Tornado_Analysis</code> {{Release||4.6|or <code>Sorted_Tornado</code>}} variable. Press the '''Graph''' button if necessary.
# Pivot the index order (if necessary) so that <code>Vars</code> is on the X-axis and <code>L</code> is the <code>Key</code>.
# Select '''Graph Setup''' and the '''Chart Type''' tab.
# Set the ''Line Style'' to the filled bar setting and check the ''Variable origin'' checkbox. This will also set ''Bar Overlap'' = 100% and ''Swap horizontal and vertical'' for you. {{Release|5.0||
# Set the '''Sort by data spread''' checkbox. }}
# Click '''Apply'''.
# Next, we want to compare to the baseline value of <code>Net_Value</code>. Click the '''XY''' button to open the '''XY Comparison Sources''' dialog, check ''Use another variable'', press '''Add...''', and in the '''Object Finder''' select the variable <code>Net_Value</code>. Press '''OK''' twice.
# In the Bar Origin pulldown, select <code>Net_value</code>.

==See Also==
* [[GetFract]]
* [[Tornado Plots]]
* [[XY Comparison]]
* [[Graph setup dialog]]
* [[WhatIfAll]], [[WhatIf]]

<footer>Sensitivity analysis functions / {{PAGENAME}} / X-Y plots</footer>

Attrib of Obj

2025-05-20T20:41:03Z

Max: /* No auto propagation of changes to attributes other than Definition and Identifier */

[[Category:Meta-Inference Functions]]
[[Category:Operators]]
[[Category: Attributes]]
{{ReleaseBar}}

== ''Attrib'' Of ''Obj'' ==

Returns the value of attribute «Attrib» of object «Obj». «Attrib» and «Obj» may each be an identifier, a text value containing identifiers, or a handle to the attribute or object. For example:

:<code>Units OF Time → 'Years'</code>
:<code>'Units' OF 'Time' → 'Years'</code>
:<code>'Units' OF [[HandleFromIdentifier]]('Time') → 'Years'</code>

If the requested attribute is not set for that object, it returns [[Null]].
This works if «Attrib» or «Obj» are arrays of attribute or object names or handles.

=== Computing «obj» ===

Sometimes you may want to use an expression for «obj» rather than just a literal identifier , especially when doing [[Meta-Inference]]. For example:
:<code>Decision A := 'Yes'</code>
:<code>Variable B := Handle(A)</code>
:<code>Class OF B → Variable</code>
You might have expected that the second expression would return <code>Decision</code>, the class of variable <code>'A'</code> whose handle is the value of <code>B</code>. But the parser naturally assumes you want the attribute of the object <code>B</code>, not its value. If you want to get the value of the variable or expression in «Obj», you need use an expression that is not just the name of a variable. You can simply put parentheses around the identifier:
:<code>Class OF (B) → Decision</code>

This can be particularly useful if you want to get an attribute of a list of objects:
:<code>INDEX Vars := ListOfHandles(X, Y, Z)</code>
:<code>Class OF (Vars) → Array(Vars, [Decision, Variable, Index])</code>

=== Specifying «attrib» ===

If «attrib» is not simply the identifier of an attribute, it tries to evaluates ot as an expression. «attrib» could be a variable or expression whose value is a text identifier of an Attribute, a handle to an attribute, or a text value with the identifier of an attribute, or an array of such text identifiers or handles. For example:
:<code>Variable Attribs := ['Class', 'Identifier', 'Value']</code>
:<code>Attribs OF A→ Array(Attribs, ['Decision', 'A', 'Yes'])</code>

=== Syntax of "OF" ===

You can use '''OF''' to get attributes of a function:
:<code>Description OF Evaluate</code>
returns the description of the evaluate function, while
:<code>Description OF Evaluate('Va1')</code>
returns the description of <code>Va1</code>.

The '''OF''' operator parses in a right-associative fashion, so that:
<code>Class OF Value OF B→ Decision</code>
parses as:
:<code>Class OF (Value OF B)→ Decision</code>

'''OF''' binds more tightly than [[operators|arithmetic operators]], but less tightly than the [[Subscript/Slice Operator]]. So, for example, to access an attribute of a local index of an object, parens are not necessary:

:<code>Index I := 1..2;</code>
:<code>Description OF I := "A simple index";</code>
:<code>Var A := I^2;</code>
:<code>Description OF A.I & "=" & A</code>

The last line parses as
:<code>((Description OF (A.I)) & "=") & A</code>

== To assign a value to an Attribute ==

You can set the value of attributes using the syntax:
:<code>''attrib'' OF ''obj'' := expr</code>
As with the standard [[Assignment Operator :=]], you can use this only in the [[OnClick]] attribute of a Button, [[OnChange]] of a Variable, [[Script]] attribute (obsolete), or a Function called from one of these. You may also assign to an attribute of a [[Local variable]] within a Definition.

You may not assign to read-only attributes, like [[Inputs]], and [[Outputs]]. You can assign a handle to a module [[IsIn]], which has the effect of moving the object into that module. You can assign to the Value of a variable, but that is dangerous because it may be inconsistent with its Definition.

As with the simple construct, «attrib» OF «obj» described above, «attrib» and «obj» may each be a simple identifier, a text value containing an identifier, or a handle to the attribute or object. And if «obj» is a variable <code>X</code> containing a handle or text value referring to the object of interest, you must put parentheses around it <code>Title OF (X)</code> if you want the Title of what <code>X</code> refers to instead of <code>X</code> itself.

However, for attribute assignment, «attrib» and «obj» must be atoms, not arrays. It does NOT array abstract.

For most attributes, «expr» should to evaluate to text, even in this case where it appears the attribute contains numbers:
:<code>NodeColor OF Va1 := '16000,8000,65535'</code>

You may only assign a text value to the definition attribute, e.g.:
:<code>Definition OF Va1 := "A + B"</code>

When you assign directly to a variable:
:<code>Va1 := "A + B"</code>
it sets the definition to the text value <code>'A+B'</code> (with quotes), rather than the expression <code>A+B</code> (without quotes) that depends on the values of A and B.

You may assign to attributes of a local index(declared using [[Index..Do]]).

To remove an attribute value, assign [[Null]] to it:
:<code>Units of Va1 := Null</code>

''Note: Internally, Analytica distinguishes between an attribute set to the special value [[Null]], and an attribute that has no value. However, it is not possible to set an attribute value to [[Null]] from an Analytica expression (although you can set value to lists or arrays containing [[Null]] elements).''

== Changes to attributes other than Definition and Identifier don't auto propagate ==

Analytica maintains dependencies between variables specified in their Definitions, as reflected in the influence arrows. So, when you change the Definition of variable, <code>A</code>, it invalidates the value of any variable <code>B</code> influenced by <code>A</code>, and recomputes <code>B</code> when needed. It also automatically propagates any change to an identifier to update any definitions that use that identifier. This also works for CheckAttribute, OnClick, and OnChange attributes.

But not other attributes! So if you (or some Analytica code) change, say, the Units of <code>A</code>, it will not invalidate or recompute <code>B</code> if it depends on the Units of <code>A</code>:

:<code>A := 20</code>
:<code>Units OF A := 'KW'</code>
:<code>B := IF Units OF A = 'KW' THEN 1000*A ELSE IF Units of A = 'MW' THEN 1M*A ELSE A</code>
:<code>B → 20000</code> { Because Units of A are KW }
:<code>Units OF A := 'MW'</code>
:<code>B → 20000</code> { Changing Units of A did not cause B to be recomputed }

{{Release|6.1||
==Subattributes or Fields ==

Some attributes contain multiple fields separated by commas, including: [[NodeInfo]], [[NodeLocation]], [[NodeSize]], [[DefaultSize]], [[FontStyle]], [[NodeFont]], [[DiagState]], [[WindState]], [[ValueState]], [[OutlinerState]], [[DefnState]], [[NumberFormat]], [[ProbabilityNumberFmt]], [[DensityNumberFormat]], and [[FileInfo]]. We refer to these fields as ''sub-attributes''. For example, the [[NodeLocation]] attribute has three sub-attributes: x, y and z, encoding the x, y location (in pixels) of the center of a node on a diagram, along with its z-index (which determines which nodes appear above of other nodes when they overlap).

You can access each sub-attribute using a special syntax ''«attribute»::«fieldNum»'' or ''«attribute»::«fieldName»''.
For example, to obtain the y value of the [[NodeLocation]] of <code>Va1</code>, use either
* <code>NodeLocation::y of Va1</code>
* <code>NodeLocation::2 of Va1</code>
The result is either numeric or Null in this case (no need to use [[ParseNumber]]). Similarly, you can set a sub-attribute within the attribute assignment with either syntax, e.g.,
* <code>NodeLocation::2 of Va1 :{{=}} 200 </code>
* <code>NodeLocation::y of Va1 :{{=}} 200</code>
}}

== See Also ==
* [[Attributes]]
* [[Objects and Values]]
* [[Assignment Operator :=]]
* [[Handle]] function
* [[Meta-Inference]]

Attributes

2025-05-20T20:39:24Z

Max:

[[Category:Attributes]]
(Up to [[Analytica Reference]])

Each Analytica Object consists of a set of Attributes, termed "properties" or "fields" in other computer languages. Every Object has a Class, Identifier, and Title. Variables also have a Definition and Domain.

You can easily view and edit some attributes in an [[Object window]] or the [[Attribute panel]] below a Diagram. Other attributes you can see, but not edit directly -- such as, the Value, Inputs and Outputs of a Variable, which Analytica computes from the Definition.

Some attributes apply only to a particular object [[Class]] -- for example, Author and Creation date apply only to a Model or Module; Parameters and Recursive apply only to a Function. There are also many internal attributes that you don't usually see but may affect how the node looks -- such as, Nodeinfo, NodeSize, and Nodefont.

This page first describes common editable Attributes, then non-modifiable Attributes, and finally the many obscure internal Attributes that users rarely need to know about.

== Common attributes ==

These attributes apply to all classes of user-defined objects. You can edit them directly in [[Edit mode]] in the [[Object window]] and [[Attribute panel]]:

===Editable Attributes of all Objects===

;Class: The [[Classes of variables and other objects|class]] of the object, such as Variable, Index, Function, or Module. You may change the Class of an object only to a compatible class: You can change the class of a Variable among these subclasses Chance, Constant, Determ, Decision, Index, Objective, Variable. You may change a [[Modules and Libraries|Module]] among these subclasses Library, FiledLibrary, Model, Module, FiledModule, or Form. You can change a [[Text nodes|Text]] node to a [[Frame node|Frame]] node or back. You can't change the class of a Function, Button, or system object. In the [[Object window]] or [[Attribute panel]], in Edit mode, the Class appears as a pulldown menu that lets you change it to another compatible Class.

;Identifier: The unique name of the object. An identifier must start with a letter, and contain only letters, digits, or underscore, up to 40 characters. Identifiers are insensitive to case -- but Analytica retains and shows the case originally provided (or adapted from the Object's title). So you can use CamelCase to clarify words in the identifier.

;Title: A word or brief phrase identifying the the object. It usually appears in the diagram node, and in many other places in the user interface. It's best to limit a Title to about 50 characters. By default, it creates an identifier from the first 20 characters of the title, substituting "_" for blank or any character that isn't a letter or digit.

;Description: Text that describes or documents the object. For a variable, it should describe what the quantity represents. For a function, it should describe what value it returns and what parameters it expects. If the definition is not obvious, it should also explain briefly what definition is doing. It should also mention any exceptions, such as what it does if an input or parameter is outside the expected domain.

===Editable attributes of Variables and Functions===

;Units: The units of measurement of a variable, or value returned by a function -- such as "$/year" or "km/hr". It's best to use abbreviations to keep units within about 10 characters.

;Definition: The expression used to compute the value of a variable or function.

;[[Check Attribute|Check]]: An expression used to test that the computed result value is valid. If it returns false, it gives a warning. This is helpful to detect errors in user input or complex calculations. See [[Check Attribute]].

===Non-editable attributes of variables and functions===

These attributes are of variables and functions are visible, but not editable, in the Object window and Attribute panel:

;Inputs: A list of variables and functions used in the definition, after definition has been parsed. Before parsing, it may contain variables and functions from which arrows were drawn.

;Outputs: A list of variables and functions that use this object in their definitions.

;Value: The computed value of the variable (not available for functions). You may displayed the Value in an Object window, but it is not displayed by default.

;EvaluationTime: The number of CPU seconds that have been spent evaluating or obtaining the value of the variable, or computing the result of the [[User Defined Functions|function]], since the object was created or loaded, or since the [[ResetEvalTimes]] command was last executed. This timing does not include the time spent evaluating parent values.

;EvaluationTimeAll: The number of CPU seconds spent in evaluation of the object, including time spent evaluating or obtaining the values of other variables that it depends on. This is the cumulative time since the object was first created or loaded, or since the [[ResetEvalTimes]] command was last executed.

===Editable attributes of Functions===

;Parameters: A list of the function [[parameters]], enclosed in parentheses. It may include [[parameter qualifiers|qualifiers]] that specify what data type or dimension are expected for each parameter, or whether a parameter is optional or may be repeated. It is good practice to also list the main (non-optional) parameters (without qualifiers) in the title, so users can easily see what parameters it expects from seeing the function node in a diagram.

;Recursive: A boolean, with value 0 (default) or 1, specifies whether the function is recursive -- i.e., it may call itself in its definition, or call another function that calls it (mutually recursive). By default, it is not displayed. You need to set it to be displayed in the [[Attributes dialog]].

===Editable Attributes of Modules===

;Author: The name(s) of the person or people who created this module. When you start a new model, it may automatically fill this in with the name of the owner of the computer, if registered with Windows.

;[[TemplateInput]]: Identifies a single variable within the module that functions at the module's primary input. Drawing an arrow into this module node inserts the origin of the arrow as the definition of this variable.

;[[TemplateOutput]]: Identifies a single variable within the module that serves as the module's primary output. Drawing an arrow from this module node treats this variable as the origin of the arrow -- for example, for use as an input to another object.

===Non-editable attributes of modules===

The Module [[class]] includes subclasses Model, Module, Filed Module, Library, Filed Library, and Form. These are attributes of modules that you can see but not edit in the [[Object window]] and [[Attribute panel]]:

;Date (Created): The time and date on which the module was first created.

;Savedate (Last Saved): The time and date on which this model or separately filed module or library was last saved.

;Fileinfo (File info): The directory path and name of the file from which this model was read from or to which it was last saved.

==Hidden attributes==

There are quite a few hidden attributes that you can't usually see in the standard user interface, and almost never need to think about. If needed you can see them in the [[Typescript]] Window. Type "Profile <identifier>" into the Typescript to see all the attributes of an object.

=== Hidden attributes of Variables and Functions===

;[[NumberFormat]]: The number format parameters specified in the [[Number Format Dialog]] for numbers generated in a variable or function. If absent, it uses the default Number Format.
:<code>v, format, proxy, zeroes, separators, currency, digits, trailingZeros, currencysymbol, currencyPlacement, datetemplate, fullPrecision, fullDateTemplate, relReqForFullDateTemplate, datesAsNumbers, numbersAsDates, digitsForGeneralFmt</code>

;[[ProbabilityNumberFmt]]: In a Probability Bands result view, a Cumulative Probability result view, or a Probability mass view for a discrete-valued quantity, probabilities display in addition to values for the underlying variable. For the columns or axes containing probabilities, this attribute holds the number format, which is often different from the underlying variable's number format.
:<code>v, format, proxy, zeroes, separators, currency, digits, trailingZeros, currencysymbol, currencyPlacement, datetemplate, fullPrecision, fullDateTemplate, relReqForFullDateTemplate, datesAsNumbers, numbersAsDates, digitsForGeneralFmt</code>

;[[DensityNumberFormat]]: In a Probability Density Result view for a continuous variable, probability density values appear in addition to values for the underlying variable's quantity. This attribute stores the number format used for columns or axes that display probability densities.
:<code>v, format, proxy, zeroes, separators, currency, digits, trailingZeros, currencysymbol, currencyPlacement, datetemplate, fullPrecision, fullDateTemplate, relReqForFullDateTemplate, datesAsNumbers, numbersAsDates, digitsForGeneralFmt</code>

;FixedDef: The parse-tree (DCODE) from the Definition. It displays as the code, usually with extra parens.

;DisplayInputs: A list of objects among inputs from which arrows are to be displayed. It does not display arrows from Inputs that are not in Displayinputs.

;IsIn: A handle to the module that contains this object. (Null for the top model.)

;[[Aliases]]: A list of handles to any user inputs or user outputs ([FormNode]]) or [[Alias nodes]] for this object. Any object type can have aliases, including Variables, Functions, Modules, and Buttons.

;[[Original]]: The original node of a user input or user output ([[FormNode]]) or [[Alias nodes|Alias node]]. [[Aliases]] attribute contains all the nodes listing it as its Original.

===Hidden attributes of Modules===

;Contains:The list of objects contained in this module.

;Defaultsize:The default node size for new nodes in this module. It uses the same format as Nodesize. If empty, it inherits the default size from its parent module. For a Model, it uses the default size from the Analytica initialization.

==Node attributes==

These attributes apply to the visual node that represents an object in its parent influence diagram. They control the location, size, and appearance of each node. You can modify some in the [[Diagram window|Diagram view]] (NodeLocation, NodeSize), some in the [[Node Style dialog]] (NodeFont, NodeInfo), or using the [[Color palette|Color palette dialog]], (NodeColor and NodeFontColor). :

;Nodelocation: The location of the node center in its parent diagram, as x,y,z, where x and y are number of pixels rightwards and downwards from the top-left corner of the diagram. You can, of course, modify node location by dragging nodes in their diagram. Nodes are displayed in order of z value, which therefore controls which nodes are displayed in front of other nodes. You can send a node back or to the front by selecting the node and using the [[Right mouse button menus|Right mouse button menus.]]

;Nodesize: The size of the node, as x,y, where x and y are the half width and half height in pixels, i.e. the distance from the node center to each edge. You can change the size of each node in its Diagram dragging the corner boxes around a selected node. You can define the default node sizes in the [[Diagram Style dialog]].

;Nodecolor: The color for this node, as r,g,b, where each color is in the range 0 to 65535. If empty, it uses the default color for this object class. You can modify colors bydirectly by selecting the node in the diagram, and using the [[Color palette]].

;NodeFontColor: Controls the font color of a node in a diagram. You can modify it from the [[Color palette#Change the text color of nodes|Color palette]]. The attribute is in RGB format, r,g,b, where each color is in the range 0 to 65535.

You can see the effects of Nodefont and Nodeinfo in the parent diagram. You can modify them for each node with the [[Node Style dialog]] or set defaults for a model or module with the [[Diagram Style dialog]].

;Nodeinfo: This affects how the node appears. It has quite a number of fields, all Boolean -- 0 or 1 -- except ''widthOfCtrl''.
:1
:: ''inputArrows'': set to 1 to show all input influence arrows or 0 to suppress them
:: ''outputArrows'': set to 1 to show all output influence arrows or 0 to suppress them
:: ''label'': set to 1 to show the title (or identifier) in the node, or 0 not to.
:: ''border'': set to 1 to show the thin border around the node, or 0 not to.
:: ''fill'': set to 1 to fill the node with selected color, or 0 not to.
:: ''label'': set to 1 to show the title (or identifier) in the node, or 0 not to.
:: ''useCustomFont'': set to 1 to use the custom font set in NodeFont, or 0 not to.
:: ''widthOfCtrl'': For a user input or output node, this specifies the width of the field (for a text or choice menu) or the button for other types.
:: ''bevel'': set to 1 to show a bevel to make the node appear outdented -- default for button nodes -- or 0 not to.
:: ''ShowFormIcon'': controls whether the little result mode icon (e.g., "Mid") displays to the right of the result button or not.
:: ''Embedded'': is reserved for a future release, where it will specify that the edit table, result view, or module is shown directly on the diagram within the node's rectangular area.

::''Hidden'': is also for a future release, to make the node invisible in its Diagram.

;Nodefont: The node font family and size in points, e.g. Bodoni, 16. If empty, it inherits the default font family and size from the parent diagram module.

;Att_hyperlinkPref: When an index or result table contains a [[handle]] to an object, it shows title of the object as a blue clickable link. When you click a handle link, it shows the object. The number assigned to this attribute controls how it shows the object when you click :
# Open its Object window
# Open its parent diagram with the node selected
# If it's a Module, open its Diagram with nothing selected. Otherwise, Open parent Diagram with the node selected.
The attribute is inherited: If you set this attribute for a Model, it sets the default for all results. If you set it on a module, it sets the default for results inside that module. If you set it for a particular variable, it applies only to that variable.

;Pict: An image shown in the node. You can paste an image into a node, or assign an image in standard formats (.png, jpeg, tiff) to the Pict attribute of a node.

==Window status attributes==

These attributes store the location and size of windows, including the Diagram, Object, and Result window, as applicable to each class of object.

;DiagState: The location and size of the diagram window, where ''x'', ''y'' are location of top left corner, ''w'' and ''h'' are width and height in pixels. ''b'' is a bit field that stores the diagram style options. ''t'' is the style for tabs when a tabbed diagram style is selected.

:<code>v, x, y, w, h, b, tabs, buttonStyle, customIcon, titleOnly, crumbs</code>

:''v'' is a version number. Should be 2.

:''x'', ''y'' in the coordinate of the top-left corner of the window frame when the window is not maximized, relative to the top-left corner of the ''desk area'' (the gray background area that starts under the toolbar).

:''w, h'' are the width and height of the client area of the window when the window is not maximized. This client are is the area of the window not including the edges around the window, the window title bar, or the attribute panel, but it does include the diagram scroll bars (which have a width and height of 16). In [[Analytica 4.6]] and earlier, the height is from the bottom edge of the title bar to the bottom of the diagram's horizontal scroll bar, and hence, includes the height of the module hierarchy stripe within the total height. In [[Analytica 5.0]], the height starts at the lower edge of the hierarchy stripe -- so it does not include the hierarchy stripe.

:''b'' is a bit field, which is the sum of the following values:
:* 1 = Show arrows to/from modules
:* 2 = Show arrows to/from indexes
:* 4 = Show arrows to/from functions
:* 8 = Turn off background (i.e., the diagram background will appear white)
:* 16 = Show dynamic dependency arrows
:* 32 = Show arrows for dependencies in the Check attribute

:''tabs'' is reserved for a future enhancement (not currently exposed) It encodes whether the diagram is a tabbed diagram, which side the tabs display on, and which style of tabs are used. Possible values are:
:* 0 = (default) Not tabbed
:* 1 = Tabs on top
:* 2 = Tabs on bottom
:* 3 = Tabs on left (vertical text)
:* 4 = Tabs on right (vertical text)
:* 5 = Wide tabs on left (horizontal text)
:* 6 = Wide tabs on right (horizontal text)
:* 7 = Tabs hidden (e.g. overlays, controlled via button scripts)

:''buttonStyle'' controls how the buttons in input and output nodes display (such as ''Calc'', ''Edit Table'', etc).
:* 0 = Normal text (default in [[Analytica 5.0]])
:* 1 = Bolded text (pre-5.0 standard)
:* 2 = Blank (no label or icon in button)
:* 3 = Icon
:* 4 = Bare Icon
::''buttonStyle'' was introduced in [[Analytica 5.0]]

:''customIcon'' If set to 1, uses the pict of the module or model as the icon for the titlebar.

:''titleOnly'' If set to 1, uses the diagram object's title as the titlebar's title without the prefix "Diagram - ".

:''crumbs'' If 0, hides the hierarchy bar from this diagram window only (child diagrams unaffected),

::''customIcon'', ''titleOnly'', and ''crumbs'' were introduced in [[Analytica 6.4]].

;WindState: The location and size of the object window, where X, Y are location of top left corner, W and H are width and height in pixels. v is version number, usually 1. (Applies to all user-defined objects.)
:<code>v, X, Y, W, H</code>

;ValueState: <code>v, X, Y, W, H, Graph, U</code>
The type, location and size of the result window for a variable, where X, Y are location of top left corner of the window, W and H are width and height in pixels of the area exclusing the title bar and edges (the actual window size is X+15, Y+38), Graph is 1 if a graph view, 0 if a table view, and U is text defining the uncertainty view. v is version number, usually 1. (Applies only to variables.)

;DefnState: The location and size of an edit table window.
:<code>v, x, y, w, h</code>

;OutlinerState: The location and size of the outliner window. This is stored as an attribute of the keyword object named <code>All</code> and is not saved with the model.
:<code>v, x, y, w, h</code>

;Reformval: Lists the indexes for a multidimensional variable, in sequence defining which index is for rows (x axis), which for columns (key), and the remaining as slicers, from bottom to top.

;Att_usebyprevindex: ???

== Internal Engine Attributes==

=== Att_versionRange ===
=== Att_canBeIn ===

=== Att_dirties ===
=== Att_showable ===
=== Att_saveAlways ===
=== Att_recordSysFunDependencies ===
=== Att_Saveable ===
=== Att_attributeType ===
=== Att_readOnly ===
=== Att_domainKids, Att_domainParents ===

== User Interface State Attributes ==

'''Att_resultSlicerState''':

'''Att_editSlicerState'''

== Graphing Attributes ==

=== xyExpr ===

Contains one external/exogenous value expression. Recognized by Analytica 3.1 and earlier, where the expression for the X value in an XY graph was stored.

=== Att_exogenousValue ===

Holds a list of external values for a result window, which can then be used as graphing dimensions. Analytica 4.0 allows more than one external value to be brought in for plotting against the primary result of a variable. This attribute holds a list of expressions -- most commonly, each expression consists of a single variable identifier.

The xyExpr may also contain one addition external expression. (The reason it is split across two attributes is for greater 3.1 interoperability).

=== Att_indexRange ===

:ver, cat,auto, includezero, log, reverse, incs, min, max, includeSubset, excludeSubset, hideLabels
where:
:version : Must be 1 (version)
:categorical : Categorical flag (1=force categorical interp), opt.
:auto : Full autoscale flag
:includezero : force 0 to be in range flag
:log : log scaling flag
:reverse : reverse order flag
:incs : Number of increments
:min : minimum value for manually scaled axis
:max : maximum value for manually scaled axis
:includeSubset : [2,7,8,12] -- include these items (by position) when using manual scaling. Brackets included
:excludeSubset : [3,6,13,17] -- exclude these items when using manual scaling.
:hideLabels: 1=hide labels for this axis

=== Att_valueRange ===

This attribute is usually contained within the [[GraphSetup]] attribute (except when '''Set Default''' was pressed after configuring the range).

The range for each value is encoded as

:ver, cat,auto, includezero, log, reverse, incs, min, max, includeSubset, excludeSubset, hideLabels
where:
:version : Must be 1 (version)
:categorical : Categorical flag (1=force categorical interp), opt.
:auto : Full autoscale flag
:includezero : force 0 to be in range flag
:log : log scaling flag
:reverse : reverse order flag
:incs : Number of increments
:min : minimum value for manually scaled axis
:max : maximum value for manually scaled axis
:includeSubset : [2,7,8,12] -- include these items (by position) when using manual scaling. Brackets included
:excludeSubset : [3,6,13,17] -- exclude these items when using manual scaling.
:hideLabels: 1=hide labels for this axis

For a given variable identifier, there can be a different range for each slice along a comparison index. These are encoded by joining the different range settings using a pipe separator (<code>|</code>) and prefixing each slice range with the slice number and colon. For example:

:<code>1,,1,,0,,20|1:1,,0,,1,,,0.01,0.56,0</code>

The first range (<code>1,,1,,0,,20</code> is for the variable's main value, the second one is prefixed by "1:" and applies to the first comparison slice. In a continuous CDF, PDF or Exceedance plot, this would be the 'X' value (e.g., the probability or density axis), but the 'Y' value is encoded instead on the <code>Graph_*_Valdim</code> system variable.

For common statistical axis, the attribute is set on special system variables with names having the form <code>Graph_*_Valdim</code>, such as <code>Graph_Pdf_Valdim</code>. This encodes the range setting for the PDF's density axis.

=== Att_continuousLineStyle ===
=== Att_categoricaLineStyle ===
=== Att_stackedBar ===
=== Att_stackedLine ===
=== Att_barOverlap ===

=== Graphing Role Attributes ===

These attributes are: '''Att_xRole''', '''Att_yRole''', '''Att_colorRole''', '''Att_symbolRole''', '''Att_symbolSizeRole''', '''Att_originRole'''.

They define the graphing pivot in coordination with the '''reformVal''' attribute. The settings in these attributes are combined with the current chart type, dimensions present in the current value (or values), etc., and Analytica may adjust the pivot actually shown to create a consistent set of roles. Since the dimensionality of results can change in Analytica (as upstream dimensions or added or removed, the view type can be changed, or the number of elements in a dimension may change), the exact pivot used the previous time the graph was displayed may no longer be sensible. However, when possible, the roles defined in these attributes do become the roles used in the graph.

Each of these role attributes can hold values in several possible forms:
* '''Self''': The keyword Self indicates that the main result fills the role.
* '''barOrigin''': The attribute name barOrigin indicates that the expression found in the legacy barOrigin attribute fills the role.
* '''xyExpr''': The attribute name indicates that the expression found in the xyExpr attribute fills the role.
* ''identifier'' : The identifier indicates that the index having this identifier fills the role.
* '''Sys_LocalIndex("''name''")''': Syntax indicating that the local index having the indicated name is used.
* '''Sys_CoordIndex(''value'')''' : The slice of the main result corresponding to ''[CoordIndex=value]'' is used, where ''value'' is an element of the coordinate index.
* 0 : The numeric value zero indicates that the main result is used (same as Self).
* n > 0: A positive integer value indicates that an external value is used. Several exogenous values may be attached to the result view (see '''Att_exogenousValues''' and '''xyExpr''' attributes). These are numbered, with the xyExpr always being n=1 if present, and then the remaining continuing in order through those listed in Att_exogenousValues, and finally the legacy barOrigin attribute expression coming last.
* n < 0: A negative integer value identifies a coordinate index slice by position. The role uses the slice of the main result corresponding to ''[@CoordIndex=abs(n)]''.

Also '''barOrigin'''.

== Table attributes ==

* [[TableCellDefault]]: The default value (or Checkbox or Choice expression) used in a new cell of an Edit table when you add or extend an index of that table.

* [[CorrespondenceMethod]]

==Other attributes==
; Att_BrowseOnly
; Att__cloakDefn
; Att_Dirty
; Att_Obfuscated
; Att_recordSet : See [[DbQuery]] for examples of use
; Att_ResultSliceState
; Att_rlm_license
; Att_rlm_licenseobj
; Att_Showable
; Att_whenDisallowed
; [[Att_PreLoadScript]]

==See Also==
<div style="column-count:2;-moz-column-count:2;-webkit-column-count:2">
* [[Manage attributes]]
* [[Attrib of Obj]]
* [[Objects and Values]]
* [[Objects_and_Their_Attributes_-_Part_1_of_3|Objects and Their Attributes]]
* [[Objects_and_Their_Attributes_-_Part_2_of_3#User-Specified_Attributes|User-Defined Attributes]]
* [[To edit an attribute]]
* [[Attribute panel]]
* [[:Category: Attributes]]
* [[Domain attribute]]
* [[Class]]
* [[Identifier]]
* [[Optimizer Attributes]]
* [[Attributes of a function]]
* [[Check attribute]]
* [[Classes of variables and other objects]]
* [[Definitions]]
</div>

Attrib of Obj

2025-05-20T20:13:48Z

Max: /* Assigning Values to Attributes */

[[Category:Meta-Inference Functions]]
[[Category:Operators]]
[[Category: Attributes]]
{{ReleaseBar}}

== ''Attrib'' Of ''Obj'' ==

Returns the value of attribute «Attrib» of object «Obj». «Attrib» and «Obj» may each be an identifier, a text value containing identifiers, or a handle to the attribute or object. For example:

:<code>Units OF Time → 'Years'</code>
:<code>'Units' OF 'Time' → 'Years'</code>
:<code>'Units' OF [[HandleFromIdentifier]]('Time') → 'Years'</code>

If the requested attribute is not set for that object, it returns [[Null]].
This works if «Attrib» or «Obj» are arrays of attribute or object names or handles.

=== Computing «obj» ===

Sometimes you may want to use an expression for «obj» rather than just a literal identifier , especially when doing [[Meta-Inference]]. For example:
:<code>Decision A := 'Yes'</code>
:<code>Variable B := Handle(A)</code>
:<code>Class OF B → Variable</code>
You might have expected that the second expression would return <code>Decision</code>, the class of variable <code>'A'</code> whose handle is the value of <code>B</code>. But the parser naturally assumes you want the attribute of the object <code>B</code>, not its value. If you want to get the value of the variable or expression in «Obj», you need use an expression that is not just the name of a variable. You can simply put parentheses around the identifier:
:<code>Class OF (B) → Decision</code>

This can be particularly useful if you want to get an attribute of a list of objects:
:<code>INDEX Vars := ListOfHandles(X, Y, Z)</code>
:<code>Class OF (Vars) → Array(Vars, [Decision, Variable, Index])</code>

=== Specifying «attrib» ===

If «attrib» is not simply the identifier of an attribute, it tries to evaluates ot as an expression. «attrib» could be a variable or expression whose value is a text identifier of an Attribute, a handle to an attribute, or a text value with the identifier of an attribute, or an array of such text identifiers or handles. For example:
:<code>Variable Attribs := ['Class', 'Identifier', 'Value']</code>
:<code>Attribs OF A→ Array(Attribs, ['Decision', 'A', 'Yes'])</code>

=== Syntax of "OF" ===

You can use '''OF''' to get attributes of a function:
:<code>Description OF Evaluate</code>
returns the description of the evaluate function, while
:<code>Description OF Evaluate('Va1')</code>
returns the description of <code>Va1</code>.

The '''OF''' operator parses in a right-associative fashion, so that:
<code>Class OF Value OF B→ Decision</code>
parses as:
:<code>Class OF (Value OF B)→ Decision</code>

'''OF''' binds more tightly than [[operators|arithmetic operators]], but less tightly than the [[Subscript/Slice Operator]]. So, for example, to access an attribute of a local index of an object, parens are not necessary:

:<code>Index I := 1..2;</code>
:<code>Description OF I := "A simple index";</code>
:<code>Var A := I^2;</code>
:<code>Description OF A.I & "=" & A</code>

The last line parses as
:<code>((Description OF (A.I)) & "=") & A</code>

== To assign a value to an Attribute ==

You can set the value of attributes using the syntax:
:<code>''attrib'' OF ''obj'' := expr</code>
As with the standard [[Assignment Operator :=]], you can use this only in the [[OnClick]] attribute of a Button, [[OnChange]] of a Variable, [[Script]] attribute (obsolete), or a Function called from one of these. You may also assign to an attribute of a [[Local variable]] within a Definition.

You may not assign to read-only attributes, like [[Inputs]], and [[Outputs]]. You can assign a handle to a module [[IsIn]], which has the effect of moving the object into that module. You can assign to the Value of a variable, but that is dangerous because it may be inconsistent with its Definition.

As with the simple construct, «attrib» OF «obj» described above, «attrib» and «obj» may each be a simple identifier, a text value containing an identifier, or a handle to the attribute or object. And if «obj» is a variable <code>X</code> containing a handle or text value referring to the object of interest, you must put parentheses around it <code>Title OF (X)</code> if you want the Title of what <code>X</code> refers to instead of <code>X</code> itself.

However, for attribute assignment, «attrib» and «obj» must be atoms, not arrays. It does NOT array abstract.

For most attributes, «expr» should to evaluate to text, even in this case where it appears the attribute contains numbers:
:<code>NodeColor OF Va1 := '16000,8000,65535'</code>

You may only assign a text value to the definition attribute, e.g.:
:<code>Definition OF Va1 := "A + B"</code>

When you assign directly to a variable:
:<code>Va1 := "A + B"</code>
it sets the definition to the text value <code>'A+B'</code> (with quotes), rather than the expression <code>A+B</code> (without quotes) that depends on the values of A and B.

You may assign to attributes of a local index(declared using [[Index..Do]]).

To remove an attribute value, assign [[Null]] to it:
:<code>Units of Va1 := Null</code>

''Note: Internally, Analytica distinguishes between an attribute set to the special value [[Null]], and an attribute that has no value. However, it is not possible to set an attribute value to [[Null]] from an Analytica expression (although you can set value to lists or arrays containing [[Null]] elements).''

== No auto propagation of changes to attributes other than Definition and Identifier ==

Analytica maintains dependencies between variables specified in their Definitions, as reflected in the influence arrows. So, if you change the definition of variable, <code>A</code>, it invalidates the value of any variable <code>B</code> that depends on <code>A</code>, and recomputes <code>B</code> when needed. It also automatically propagates any change to an identifier to update any definitions that use that identifier. This works for CheckAttribute, OnClick, and OnChange attributes.
But not other attributes! So if you (or some Analytica code) change, say, the Units of <code>A</code>, it will not invalidate or recompute <code>B</code> if it depends on the Units of <code>A</code>:

:<code>A := 20</code>
:<code>Units OF A := 'KW'</code>
:<code>B := IF Units OF A = 'KW' THEN 1000*A ELSE IF Units of A = 'MW' THEN 1M*A ELSE A</code>
:<code>B → 20000</code> { Because Units of A are KW }
:<code>Units OF A := 'MW'</code>
:<code>B → 20000</code> { Changing Units of A did not cause B to be recomputed }

{{Release|6.1||
==Sub-Attributes ==
There are several attributes in Analytica that store multiple fields separated by commas, namely these attributes: [[NodeInfo]], [[NodeLocation]], [[NodeSize]], [[DefaultSize]], [[FontStyle]], [[NodeFont]], [[DiagState]], [[WindState]], [[ValueState]], [[OutlinerState]], [[DefnState]], [[NumberFormat]], [[ProbabilityNumberFmt]], [[DensityNumberFormat]], and [[FileInfo]]. We refer to these fields as ''sub-attributes''. For example, the [[NodeLocation]] attribute has three sub-attributes: x, y and z, encoding the x, y location (in pixels) of the center of a node on a diagram, along with its z-index (which determines which nodes appear above of other nodes when they overlap).

When you need to access a sub-attribute, you can do so using a special syntax ''«attribute»::«fieldNum»'' or ''«attribute»::«fieldName»''.
For example, to obtain the y value of the [[NodeLocation]] of <code>Va1</code>, use either
* <code>NodeLocation::2 of Va1</code>
* <code>NodeLocation::y of Va1</code>
The result is either numeric or Null in this case (no need to use [[ParseNumber]]). Similarly, to set a sub-attribute, use either syntax within the attribute assignment, e.g.,
* <code>NodeLocation::2 of Va1 :{{=}} 200 </code>
* <code>NodeLocation::y of Va1 :{{=}} 200</code>
}}

== See Also ==
* [[Attributes]]
* [[Objects and Values]]
* [[Assignment Operator :=]]
* [[Handle]] function
* [[Meta-Inference]]

Attrib of Obj

2025-05-20T20:11:58Z

Max: /* Computing «obj» */

[[Category:Meta-Inference Functions]]
[[Category:Operators]]
[[Category: Attributes]]
{{ReleaseBar}}

== ''Attrib'' Of ''Obj'' ==

Returns the value of attribute «Attrib» of object «Obj». «Attrib» and «Obj» may each be an identifier, a text value containing identifiers, or a handle to the attribute or object. For example:

:<code>Units OF Time → 'Years'</code>
:<code>'Units' OF 'Time' → 'Years'</code>
:<code>'Units' OF [[HandleFromIdentifier]]('Time') → 'Years'</code>

If the requested attribute is not set for that object, it returns [[Null]].
This works if «Attrib» or «Obj» are arrays of attribute or object names or handles.

=== Computing «obj» ===

Sometimes you may want to use an expression for «obj» rather than just a literal identifier , especially when doing [[Meta-Inference]]. For example:
:<code>Decision A := 'Yes'</code>
:<code>Variable B := Handle(A)</code>
:<code>Class OF B → Variable</code>
You might have expected that the second expression would return <code>Decision</code>, the class of variable <code>'A'</code> whose handle is the value of <code>B</code>. But the parser naturally assumes you want the attribute of the object <code>B</code>, not its value. If you want to get the value of the variable or expression in «Obj», you need use an expression that is not just the name of a variable. You can simply put parentheses around the identifier:
:<code>Class OF (B) → Decision</code>

This can be particularly useful if you want to get an attribute of a list of objects:
:<code>INDEX Vars := ListOfHandles(X, Y, Z)</code>
:<code>Class OF (Vars) → Array(Vars, [Decision, Variable, Index])</code>

=== Specifying «attrib» ===

If «attrib» is not simply the identifier of an attribute, it tries to evaluates ot as an expression. «attrib» could be a variable or expression whose value is a text identifier of an Attribute, a handle to an attribute, or a text value with the identifier of an attribute, or an array of such text identifiers or handles. For example:
:<code>Variable Attribs := ['Class', 'Identifier', 'Value']</code>
:<code>Attribs OF A→ Array(Attribs, ['Decision', 'A', 'Yes'])</code>

=== Syntax of "OF" ===

You can use '''OF''' to get attributes of a function:
:<code>Description OF Evaluate</code>
returns the description of the evaluate function, while
:<code>Description OF Evaluate('Va1')</code>
returns the description of <code>Va1</code>.

The '''OF''' operator parses in a right-associative fashion, so that:
<code>Class OF Value OF B→ Decision</code>
parses as:
:<code>Class OF (Value OF B)→ Decision</code>

'''OF''' binds more tightly than [[operators|arithmetic operators]], but less tightly than the [[Subscript/Slice Operator]]. So, for example, to access an attribute of a local index of an object, parens are not necessary:

:<code>Index I := 1..2;</code>
:<code>Description OF I := "A simple index";</code>
:<code>Var A := I^2;</code>
:<code>Description OF A.I & "=" & A</code>

The last line parses as
:<code>((Description OF (A.I)) & "=") & A</code>

== Assigning Values to Attributes ==

You can set the value of attributes using the syntax:
:<code>''attrib'' OF ''obj'' := expr</code>
As with the standard [[Assignment Operator :=]], you can use this only in the [[OnClick]] attribute of a Button, [[OnChange]] of a Variable, [[Script]] attribute (obsolete), or a Function called from one of these. You may also assign to an attribute of a [[Local variable]] within a Definition.

You may not assign to read-only attributes, like [[Inputs]], and [[Outputs]]. You can assign a handle to a module [[IsIn]], which has the effect of moving the object into that module. You can assign to the Value of a variable, but that is dangerous because it may be inconsistent with its Definition.

As with the simple construct, «attrib» OF «obj» described above, «attrib» and «obj» may each be a simple identifier, a text value containing an identifier, or a handle to the attribute or object. And if «obj» is a variable <code>X</code> containing a handle or text value referring to the object of interest, you must put parentheses around it <code>Title OF (X)</code> if you want the Title of what <code>X</code> refers to instead of <code>X</code> itself.

However, for attribute assignment, «attrib» and «obj» must be atoms, not arrays. It does NOT array abstract.

For most attributes, «expr» should to evaluate to text, even in this case where it appears the attribute contains numbers:
:<code>NodeColor OF Va1 := '16000,8000,65535'</code>

You may only assign a text value to the definition attribute, e.g.:
:<code>Definition OF Va1 := "A + B"</code>

When you assign directly to a variable:
:<code>Va1 := "A + B"</code>
it sets the definition to the text value <code>'A+B'</code> (with quotes), rather than the expression <code>A+B</code> (without quotes) that depends on the values of A and B.

You may assign to attributes of a local index(declared using [[Index..Do]]).

To remove an attribute value, assign [[Null]] to it:
:<code>Units of Va1 := Null</code>

''Note: Internally, Analytica distinguishes between an attribute set to the special value [[Null]], and an attribute that has no value. However, it is not possible to set an attribute value to [[Null]] from an Analytica expression (although you can set value to lists or arrays containing [[Null]] elements).''

== No auto propagation of changes to attributes other than Definition and Identifier ==

Analytica maintains dependencies between variables specified in their Definitions, as reflected in the influence arrows. So, if you change the definition of variable, <code>A</code>, it invalidates the value of any variable <code>B</code> that depends on <code>A</code>, and recomputes <code>B</code> when needed. It also automatically propagates any change to an identifier to update any definitions that use that identifier. This works for CheckAttribute, OnClick, and OnChange attributes.
But not other attributes! So if you (or some Analytica code) change, say, the Units of <code>A</code>, it will not invalidate or recompute <code>B</code> if it depends on the Units of <code>A</code>:

:<code>A := 20</code>
:<code>Units OF A := 'KW'</code>
:<code>B := IF Units OF A = 'KW' THEN 1000*A ELSE IF Units of A = 'MW' THEN 1M*A ELSE A</code>
:<code>B → 20000</code> { Because Units of A are KW }
:<code>Units OF A := 'MW'</code>
:<code>B → 20000</code> { Changing Units of A did not cause B to be recomputed }

{{Release|6.1||
==Sub-Attributes ==
There are several attributes in Analytica that store multiple fields separated by commas, namely these attributes: [[NodeInfo]], [[NodeLocation]], [[NodeSize]], [[DefaultSize]], [[FontStyle]], [[NodeFont]], [[DiagState]], [[WindState]], [[ValueState]], [[OutlinerState]], [[DefnState]], [[NumberFormat]], [[ProbabilityNumberFmt]], [[DensityNumberFormat]], and [[FileInfo]]. We refer to these fields as ''sub-attributes''. For example, the [[NodeLocation]] attribute has three sub-attributes: x, y and z, encoding the x, y location (in pixels) of the center of a node on a diagram, along with its z-index (which determines which nodes appear above of other nodes when they overlap).

When you need to access a sub-attribute, you can do so using a special syntax ''«attribute»::«fieldNum»'' or ''«attribute»::«fieldName»''.
For example, to obtain the y value of the [[NodeLocation]] of <code>Va1</code>, use either
* <code>NodeLocation::2 of Va1</code>
* <code>NodeLocation::y of Va1</code>
The result is either numeric or Null in this case (no need to use [[ParseNumber]]). Similarly, to set a sub-attribute, use either syntax within the attribute assignment, e.g.,
* <code>NodeLocation::2 of Va1 :{{=}} 200 </code>
* <code>NodeLocation::y of Va1 :{{=}} 200</code>
}}

== See Also ==
* [[Attributes]]
* [[Objects and Values]]
* [[Assignment Operator :=]]
* [[Handle]] function
* [[Meta-Inference]]

MultiResult

2025-02-05T21:49:15Z

Max: /* Examples */

Multiresult lets a [[User-Defined Function]] or expression return more than one distinct value. It is also convenient in some loops when you want to set multiple local variables at the same time.

== MultiResult( expr ... ) ==
== _( expr ... ) ==

These two equivalent functions accept repeated expressions separated by commas. It evaluates the only the ones that are captured by the caller or parent expression, and returns the results as multiple distinct return values. The dimensions of each return value are kept distinct -- they are not combined in any way as they would in other functions. <code>MultiResult(a,b,c)</code> and <code>_(a,b,c)</code> are identical in functionality. Stylistically, the <code>MultiResult(...)</code> syntax is generally nicer when used for a UDF return value, and the <code>_(...)</code> notation lends itself to looping constructs.

=== Examples ===

This function returns the R, G, B and Alpha components as separate results given a color integer c.

<code>
:Function ColorComponents(c: Color ) :=
::[[MultiResult]](
:::[[BitAnd]]( [ [[BitShift]]( c, 16), 0xFF] ),
:::[[BitAnd]]( [ [[BitShift]]( c, 8), 0xFF] ),
:::[[BitAnd]]( [ c, 0xFF] ),
:::[[BitAnd]]( [ [[BitShift]]( c, 24), 0xFF] ) )
</code>You can then capture the separate return values in local values using, e.g.,
:<code>[[Local]] (r,g,b,a) := ColorComponents( 'Turquoise' );</code>
When you don't need the alpha value,
:<code>[[Local]] (r,g,b) := ColorComponents( 'Turquoise' );</code>
In this case, the final expression <code>[[BitAnd]]( [ [[BitShift]]( c, 24), 0xFF] )</code> in the UDF does not get evaluated.

The next example illustrates its use in a looping construct. Here <code>v</code> is indexed by <code>Time</code> and <code>In1</code>, but the «bodyExpr» does something where it requires <code>v</code> to be indexed only by <code>Time</code>. At the same time, it also needs to know the corresponding index value from <code>In1</code> for that slice of <code>v</code>.

:<code>[[Local]] ( vi[Time], i[ ] ) := _( v, In1);</code>
:''«bodyExpr»''

== History ==

Added in release 5.2.

== See Also ==
* [[Local]]
* [[User-Defined Functions]]

MultiResult

2025-02-05T21:44:54Z

Max:

Multiresult lets a [[User-Defined Function]] or expression return more than one distinct value. It is also convenient in some loops when you want to set multiple local variables at the same time.

== MultiResult( expr ... ) ==
== _( expr ... ) ==

These two equivalent functions accept repeated expressions separated by commas. It evaluates the only the ones that are captured by the caller or parent expression, and returns the results as multiple distinct return values. The dimensions of each return value are kept distinct -- they are not combined in any way as they would in other functions. <code>MultiResult(a,b,c)</code> and <code>_(a,b,c)</code> are identical in functionality. Stylistically, the <code>MultiResult(...)</code> syntax is generally nicer when used for a UDF return value, and the <code>_(...)</code> notation lends itself to looping constructs.

=== Examples ===

This function returns the R, G, B and Alpha components as separate results given a color integer c.

:Function ColorComponents(c: Color ) := <code>
::[[MultiResult]](
:::[[BitAnd]]( [ [[BitShift]]( c, 16), 0xFF] ),
:::[[BitAnd]]( [ [[BitShift]]( c, 8), 0xFF] ),
:::[[BitAnd]]( [ c, 0xFF] ),
:::[[BitAnd]]( [ [[BitShift]]( c, 24), 0xFF] ) )
</code>You can then capture the separate return values in local values using, e.g.,
:<code>[[Local]] (r,g,b,a) := ColorComponents( 'Turquoise' );</code>
When you don't need the alpha value,
:<code>[[Local]] (r,g,b) := ColorComponents( 'Turquoise' );</code>
In this case, the final expression <code>[[BitAnd]]( [ [[BitShift]]( c, 24), 0xFF] )</code> in the UDF does not get evaluated.

The next example illustrates its use in a looping construct. Here <code>v</code> is indexed by <code>Time</code> and <code>In1</code>, but the «bodyExpr» does something where it requires <code>v</code> to be indexed only by <code>Time</code>. At the same time, it also needs to know the corresponding index value from <code>In1</code> for that slice of <code>v</code>.

:<code>[[Local]] ( vi[Time], i[ ] ) := _( v, In1);</code>
:''«bodyExpr»''

== History ==

Added in release 5.2.

== See Also ==
* [[Local]]
* [[User-Defined Functions]]

MultiChoice

2025-02-05T21:41:29Z

Max: /* Filtering long MultiChoice lists (ACP) */

[[Category:Functions that select part of an array]]
[[Category:Top level functions]]
[[Category: Menus]]
[[Category:User-interface functions]]
[[Category:Analytica 5.0]]
{{ReleaseBar}}

''New to [[Analytica 5.0]]''

== MultiChoice( <code>I</code>'', n..., allowNone, separator, returnList, returnSet{{Release|6.4||, labels, selectionLabels, nestUnder}}'' ) ==

[[image:MultiChoice popup.png|frame|A user-input control showing the [[MultiChoice]] popup with separators and multiple items selected.]]

[[MultiChoice]] creates a user-input control that lets you select one, none, some, or All from a list of options, unlike the similar [[Choice]] control that lets you select only one or All. It returns the list of selected options. [[MultiChoice]] must appear as the top-level of a [[Definition]] or in a [[Table]]. In a [[Table]], it returns a [[Sets - collections of unique elements|Set]] -- a [[reference]] to a list of the selected values,

It doesn't work as a user input when the legacy [[Preferences|Preference setting]] '''Domain acts as self index''' is on.

=== Parameters ===

* «<code>I</code>»: Either an index identifier, or the keyword [[Self]]. When it is an index identifier, the index elements are the possible options. When the keyword [[Self]] is used, the possible options are obtained from the [[Domain]].
* «n»: The currently selected options, listed by position. For example, <code>MultiChoice( I, 2, 3, 7 )</code> records that the 2nd, 3rd, and 7th items are selected.
* «allowNone»: (Optional) A Boolean that specifies whether the empty selection is allowed. By default, the empty selection is disallowed. To allow the empty selection, use named-parameter syntax, e.g., <code>MultiChoice(Self, allowNone:True)</code>. When the empty selection is disallowed and «n» contains no valid options, the first item is returned.
* «separator»: (Optional) When an element in the list of options matches the value specified here, it displays as a non-selectable separator (a horizontal line between items).
* «returnList»: (Optional) When true, returns a list even when a single item is selected. It that case, the result is a one-element list. This is useful when you define an index with the Multichoice. When «returnList» is false or omitted, «returnSet» is not true, and only a single item is selected, then the single item is returned.
* «returnSet»: (Optional) When true, returns a reference to a list (i.e., a [[Set Functions|set]]). When [[MultiChoice]] appears in a table cell, this is the default, since it avoids the combination of dimensions from every cell with a multichoice selector.{{Release|6.4||
* «labels»: (Optional) The values that appears on the popup menu (or as the selected value on the control if «selectionLabels» isn't also specified). Use this parameter if you want these to be different from the index values (the result). This should be indexed by «<code>I</code>», or can be a list when using a Self-choice. These can be (thumbnail) images.
* «selectionLabels»: (Optional) The values that you want to appear in the control as the selected value. This should be indexed by «<code>I</code>», or can be a list when using a Self-choice. Specify this when you want this to be different from «labels». These can be (thumbnail) images.
* «nestUnder»: (Optional) A 1-D array indexed by «<code>I</code>» of submenu names (or Null). When specified, the options are organized hierarchically as submenus. Multiple submenu levels can be separated by the '>' character, for example <code>"California > Santa Clara Co."</code> would place the corresponding item two levels deep.}}

== Examples ==

In these examples, the index <code>Option</code> contains the possible choices.
:<code>Index Option := ['Apple', 'Pear', 'Orange']</code>

A Multichoice with one option selected returns the value of that option:
:<code>MultiChoice(Option, 3) → 'Orange'</code>

A Multichoice with multiple options selected returns the values of those options as a list, indexed by the variable containing the Multichoice:
:<code>MultiChoice(Option, 1, 3) → ['Apple', 'Orange']</code>

A Multichoice with no options selected returns the first item by default:
:<code>MultiChoice(Option) → </code>

Unless you specify optional parameter «allowNone» as True, in which case it lets the user choose no option, and returns an empty list indexed by the variable containing the Multichoice:
:<code>MultiChoice(Option, allowNone: True) → []</code>

In this case, the options come from the variable or index's own [[Domain]]. Two items are selected.
:<code>MultiChoice(Self, 7,12)</code>

This example uses separators, specified as '--', to group the options. Currently <code>'cherry'</code>, <code>'egg plant'</code> and <code>'peanut'</code> are selected.
:Index Produce_item := <code>['apple', 'banana', 'cherry', '--', 'egg plant', 'lettuce', 'squash', '--', 'almond', 'peanut', 'walnut']</code>
:Domain of Produce := {Copy from index} <code>Produce_item</code>
:Index Produce := <code>[[MultiChoice]]( Self, 3, 5, 10, separator:'--' )</code>

:::[[image:MultiChoice popup.png]]

== Using the MultiChoice control ==

Usually, if you define a variable or index to be a [[MultiChoice]], you will create an input node for that variable. The input node then displays the control on your diagram. The control looks pretty much the same as a [[Choice]] control. When a single item is selected, the selected item appears in the control. When multiple items are selected, the control displays '''«Multiple»''' or '''«All»''', and if no items are selected, it displays '''«None»'''.

When you click on the control, the list of options pops up. Keyboard actions include:
* [ESC] key: Cancels the current input and closes the popup, restoring the original selection.
* [Enter] key: Closes the popup, accepting the current selections.
* [Up] and [Down] arrows: Moves the highlighted selection (no impact on which items are selected).
* [Space] key: Toggles the highlighted selection. Leaves popup open.
* [Ctrl+A]: Selects all, or if all options are already selected, deselects all (but leaves one selected if «allowNone» is not on).
Mouse actions include:
* Click on item: Toggles item. Leaves popup open.
* Click outside the control: Accepts selections and closes popup.
* Click - drag - release: Select or deselect several items. The item where the mouse down occurs determines whether the drag selects or deselects.

When «allowNone» is not on, the actions that toggle the selection state will not deselect the last selected item.

== Details ==

==== Handles ====
When the options are [[handles]] to variables (or other objects), it shows the [[Title]] or [[Identifier]] of each object in the menu (as with [[Choice]]) and returns the [[handle]], not the value of the variable.

==== Pictures in MultiChoice ====
You can use pictures as MultiChoice options by using an Index with pictures in it. For more information on how to do this, see [https://docs.analytica.com/index.php/Choice#Pictures_in_Choice_nodes Pictures in Choice nodes].

==== Filtering long MultiChoice lists (ACP) ====
In ACP, when you open a MultiChoice menu that has more than 10 options, it adds a filter box at the top of the menu. As you type into the box, it shortens the menu showing only options that match what you have typed, like so:

[[image:choicefilter.png|link=Special:FilePath/Choicefilter.png|alt=|frameless|314x314px]]

Note that this feature is only available in ACP, not (yet) in Desktop Analytica.

== See Also ==
* [[Choice]]
* [[Choice menu user input]]
* [[Choice menus and Checkboxes in an edit table]]
* [http://lumina.com/blog/analytica-5-video-shorts-multichoice-controls Analytica 5 Video Short: MultiChoice controls] on blog (or watch on [https://youtu.be/g9xpsW0cH4o YouTube])
* [[Checkbox]]
* [[Preferences]]

Choice

2025-02-05T21:41:00Z

Max: /* Filtering long Choice lists (ACP) */

[[Category:Functions that select part of an array]]
[[Category:Top level functions]]
[[Category: Menus]]
[[Category:User-interface functions]]
{{ReleaseBar}}

== Choice(i, n) ==
[[Choice]] is a user-interface function that displays a drop-down menu in the normal view of the Definition (or in a [[User Input nodes|User input]] for the variable) to allow an end user to select from a list of options. The index «i» is the list of options -- an index containing the values appearing on the popup. When <code>I: Self</code>, the values listed in the variable's domain are used. «N» is the position of the currently selected option in that list, or 0 for ''All''. This should always be an explicit integer, not an expression.

[[Choice]] lets the user to select only one option at a time (or, optionally, All options.) If you want to be able to select any subset of options, use [[MultiChoice]]. A [[Slider]] is another UI control for selecting a single value at a time.

When the user selects a different option, it changes the value of parameter «n» in the Definition to match that option (or 0 to mean ''All'' options.) You can use Choice to show a menu as the definition of a variable or in a cell of an Edit table (or [[ProbTable]] or [[DetermTable]]). [[Choice]] must be the top level of the definition or the cell, and may not be nested within an expression. You must create an Input node for the variable before it will display choices as menus.

The full declaration of Choice() is:
:[[Choice]](I: Index; n: atomic nonNegative; inclAll: optional boolean = True; Eval: optional boolean = True; Result: optional Array[I], separator: optional text)

==Optional parameters==
===InclAll===
«inclAll» (default <code>True</code>) specifies whether the "All" option is displayed.

By default, the menu shows ''All'' as the first option. If you choose ''All'', the result will be computed for every value of index «i». This makes it easy to do a parametric analysis to see how the choices affect the results. When you choose ''All'', it sets parameter «n» to 0.

If you select ''All'' for multiple Choice menus, each variable influenced by the Choice variables is computed for all combinations of values from those menus, adding an index dimension to each result. So if there are more than two or three, the number of dimensions may make the result hard to understand, and long to compute. In rare cases, the model may not be able to compute correctly with ''All''. In such cases, you can turn off ''All'' as an option by setting an optional third parameter, «inclAll» to <code>False</code> (0). It usually advisable to set «inclAll» to <code>False</code> whenever you use [[Choice]] in an Edit table.

===Eval===
The «Eval» parameter specifies whether [[handle]] or expression terms are evaluated for the return value when index i contains handles to variable or expression. It has no effect when the «Result» parameter is specified, or when «I» contains only constants, such as numbers and text strings. Setting «Eval» to false is recommended in most cases when «I» contains [[handle]]s (variable identifiers). The «Eval» parameter has no effect when «I» is Self (it is always treated as false).

===Result===
Normally, Choice(I, n) returns the «n»th value of index «I».. You can use the optional parameter, «Result», to specify a different value to return. The «Result» parameter should be indexed by «I». It will return «Result»[@I = «n»].

This example returns the index position (instead of the label) of the selected value:

:<code>Choice(I, 1, Result: @I)</code>

Suppose you have a table <code>A</code> indexed by <code>I</code>, and you want your user to select a row of <code>I</code>, and then select out only the selected row. A standard formulation of this is:
:<code>Variable A := Table(I)(...)</code>
:<code>Decision selectedRow := Choice(I, 1)</code>
:<code>Variable selectedA := A[I = selectedRow]</code>

You can do this more concisely using the «Result» parameter:
:<code>Variable A := Table(I)(...)</code>
:<code>Decision selectedA := Choice(I, 1, Result: A)</code>

When the «Result» parameter is specified, the «Eval» parameter does nothing.

=== Separator===
You can specify that certain items in <code>I</code> are to display as separators -- nonselectable items used to group selectable items in the menu. Use the «separator» parameter to specify what value in «I» should display as a separator, for example:

:<code>Choice(I, 1, separator:'---')</code>

:<code>Index Country_S := ['Canada', 'Mexico', 'USA', '---',</code>
::<code>'England', 'France', 'Germany', 'Russia', '---',</code>
::<code>'China', 'India', 'Japan','Philippines', '---',</code>
::<code>'Australia', 'New Zealand', '---',</code>
::<code>'Argentina', 'Brazil', 'Chile']</code>

:<code>Variable Select_country := Choice(Country_S, 1, separator:'---')</code>

:[[image:choice_with_separators.png]]

=== labels and selectionLabels ===
'''New to [[Analytica 6.4]]''

These optional parameters enable you to display values in the popup menu or in the control that are different from the index values in «<code>I</code>». Without these, the index values appear. When used, these should be indexed by <code>I</code>. In the case of a Self-choice, you may need to supply a list of values, which has the disadvantage that it cannot adapt to changes in length or re-orderings of the domain value. You can also supply images for either -- if you do so, keep them small. They are not resized from the original size.

«labels» contains the values that appear on the popup menu. When «selectionLabels» isn't also specified, these are also used for the selected value in the control itself.

«selectionLabels» contains the values that appear as the selected value in the control itself.

'''Example 1: City selection'''

This example of selecting a city from a hierarchical menu provides an example where it is convenient to have different values for the index value (the result), the «labels» and the «selectionLabels». A given city name often appears in multiple states, for example Salem, Oregon and Salem, New York. To keep index elements unique, the values in the index have the full name in the form <code>"Oregon, Salem"</code>, etc.

:<code>Index City := ["Alabama, Auburn", "Alabama, Florence", "Alabama, Marion", ...]</code>

:<code>Variable State_name := [[FindInText]]("^(.+),",City,subpattern:1,return:'S')</code>
:<code>Variable City_name := [[FindInText]](",\s*(.+)\s*$",City,subpattern:1,return:'S')</code>

<code>State_name</code> and <code>City_name</code> are indexed by <code>City</code>.

Our city selection can now present only the city name on the menus, but the full name in the selection (and result):
:<code>Variable Choose_city := [[Choice]]( City, 8, inclAll:False, labels:City_name, selectionLabels:City, nestUnder: State_name )</code>
:→
:[[image:city select hierarchy.png]]

'''Example 2: Color picker'''
A second example where it is useful for the labels to be different from the index values is a color picker. The <code>Color</code> index can contain the color names or RGB integers, whereas the choice contains color swatches (images).

:<code>Index Color := ['red','white','blue','orange','green']</code>
:<code>Variable Color_swatch := [[CanvasImage]]( [[Canvas]]( 10, 25, Color ]] )</code>

:<code>Variable Choose_color := [[Choice]]( Color, 1, labels:Color_swatch)</code> →
::[[image:Color_picker_choice.png]]

The result of <code>Choose_color</code> is <code>"Green"</code>.

=== nestUnder for hierarchical menus ===
''New to [[Analytica 6.4]]''

This optional parameter lets you organize the options into hierarchical submenus. The parameter should be a 1-D array indexed by «<code>I</code>». The entries must all be text or Null. Text entries contain the name of the submenu. Multiple levels of submenus are separated by '>'. For example, consider a <code>City</code> index with this «nestUnder» array:

::Variable City_submenus → [[image:City_submenus.png]]

Then <code>[[Choice]]( City, 1, nestUnder: City_submenus )</code> produces this multilevel pulldown:

::[[Image:nestUnderEx.png]]

In this example, Arizona and Nevada are only one level deep, each with a single element, while San Jose is two levels deep, with counties, and cities within each county.

==Examples==
Suppose multiple variables use [[Choice]](I, n) with the same index <code>I</code>, and you choose ''All'' for each of them, e.g.
:<code>Index I := ['Low', 'Mid', 'High']</code>
:<code>Variable A := Choice(I, 0)</code>
:<code>Variable B := Choice(I, 0)</code>
:<code>Variable Result := IF A = 'Low' AND B = 'Low' THEN 0 ELSE 100 →</code>
::<code>Array(I, [0, 100, 100])</code>

<code>Result</code> is indexed by I only once, and A and B are treated as if they have the same values. If you wanted to vary them independently, they should use different indexes, e.g.
:<code>Index I := ['Low', 'Mid', 'High']</code>
:<code>Variable A := Choice(I, 0)</code>
:<code>Index J := CopyIndex(I)</code>
:<code>Variable B := Choice(J, 0)</code>
:<code>Variable Result := IF A = 'Low' AND B = 'Low' THEN 0 ELSE 100 →</code>
::<code>Array(I, J, [0, 100, 100], [100, 100, 100], [100, 100, 100])</code>

The function [[CopyIndex]](I) makes returns a new index with the same values as <code>I</code>.

==Details and more examples==
=== Self-Indexed Choices ===
When a variable is defined with the first parameter set to [[Self]], as in the definition:
:<code>Choice(Self, 0)</code>

then the set of values appearing in the choice are located in the variable's own domain attribute. In this case, the domain must be either a list, list-of-labels or index type.

The easiest way to create a Self-Choice is to select "Choice..." from the definition type popup. Analytica will then fill in a default one-element list-of-labels selection.

When a domain is a list, the elements are usually numbers, but may also be variable identifiers or expressions. (See "Identifier and Expression items" below).

If you use an Index domain, then the values for domain of [[Self]] come from another index variable. In this case, <code>Choice(Self,1)</code> when <code>domain = I</code> is very similar to <code>Choice(I,1)</code> with no domain set. There are, however, several differences.

First, if you use an index domain, then your variable will have both an index value and mid/prob values, while if you use <code>Choice(I, 1)</code> your variable will not have an index semantics.

Second, if "All" is selected in the pulldown, the result of <ode>Choice(I, 0) is indexed by <code>I</code>, while <code>Choice(Self, 0)</code> is indexed by [[Self]].

Third, in an index domain using Index I, the values in the domain are the evaluated values of <code>I</code>. If <code>I</code> contains only numbers and text strings, then these are the same as the values of <code>I</code>, but if <code>I</code> contains identifiers or expressions, then there is a difference. <code>Choice(I, 1)</code> would show the identifiers or expressions, while <code>Choice(Self, 1)</code> with <code>domain = I</code> would show the values of those variables in the pulldown.

=== Input Nodes ===
Selecting "Make Input" from the Object menu creates a pull-down control that you can position on your diagram as part of a user-interface form.

=== Pull-downs in edit tables ===
You can put a [[Choice]] pulldown menu in a cell of an edit table. Just type the expression, such as <code>Choice(option, 1, 0)</code>. where <code>option</code> is an index containing the possible options. You usually set the third parameter, «inclAll», to 0, so to remove the ''All'' option. Otherwise, if the user selects "All" in a table, array abstraction causes the index <code>option</code> to become an index of the entire value of the table result. Similarly, you can specify [[Choice]] and [[Checkbox]] in the cells of any [[DetermTable]], [[ProbTable]], [[IntraTable]], or [[SubTable]].

When you enter a valid [[Choice]] or [[Checkbox]] expression into a table cell, the cell immediately shows the menu or checkbox. But, you will also see an expression/choice selector near the right top of the window:

:[[image:expr-choice-selector.png]]

If you select the ''expr'' option, you will see all cells as text expressions, so you can review and edit them directly.

In browse mode, these cells with controls always appear as controls. The controls appear as disabled (so you can't change them) in browse mode, unless or until you create an input node for the table.

==== In Analytica 4.0 thru Analytica 4.4 ====

In these earlier versions, there is now expression/choice select, and you can only see the expression in Edit mode, allowing you to edit the definition.

=== Using Choice with DetermTable ===
A useful arrangement is to use [[Choice]] variables for key parameters, especially parameters where you may want to perform a parametric analysis (by selecting "All"), and then organizing tabular data in [[DetermTable]]s (rather than standard Edit Tables). This arrangement looks like the following:

:<code>Decision Scenario := Choice(Self, 0)</code>
:<code>Domain of Scenario : [1, 2, 3, 4]</code>
:<code>Variable A := DetermTable(Scenario)(...)</code>

In this arrangement, the definition of <code>A</code> appears as an edit table, indexed by all domain values of <code>Scenario</code>. However, when evaluated, only the selected row is returned.

With this arrangement, you can compute downstream results for a single <code>Scenario</code> (or other dimension), or for every scenario when "All" is selected. When available memory limits your ability to perform a full parameter analysis across many dimensions (since the number of combinations increases multiplicatively), this setup makes it easy to limit the parametric analysis to only selected dimensions.

A second variation on this is:
:<code>Index AllScenarios := [1, 2, 3, 4]</code>
:<code>Decision Scenario := Choice(Self, 0)</code>
:<code>Domain of Scenario : Index AllScenarios</code>
:<code>Variable A := DetermTable(Scenario)(...)</code>

=== Identifier and Expression Items ===
When an option in «I» is a [[handle]] to a variable, then the pulldown will display either the title of the object or its identifier, depending on whether "Show By Identifier" is selected. The "Show By Identifier" setting is found on the '''Object''' menu and can also be toggled by pressing ''Ctrl+Y'' .

When you want to set up an explicit list of identifiers to select between, the best way to do this is to create an index node and turn on its [[MetaOnly]] attribute. Then set the definition to be a list and enter the identifiers in each cell. You can also compute a list of identifiers.

When the selected item is a [[handle]] to a variable, the result of evaluating the [[Choice]] function will be either the handle or the result of evaluating the handle, as follows. If the «eval» parameter is specified and set to false, or if the «I» option is [[Self]], then the result is the handle. If the «eval» parameter is specified and true, and the «I» parameter is an index (i.e., not [[Self]]), then the result is the result of evaluating the selected variable. When «eval» is not specified, then a handle is returned if «I» is index node with the [[MetaOnly]] attribute set or if «I» species the domain of another variable, or otherwise the result of evaluating the variable is returned.

If you are dealing with Choices involving variable identifiers, using <code>Eval: False</code> is generally preferred. Operations such as comparing the selected value to the original index, or use of a [[DetermTable]] based on the choice variable, function more consistently and less ambiguously. As a comparison, if you return values (e.g., <code>Eval: True</code>), and two variables in the choice happen to have the same value, then an ambiguity over which variable was selected exists, but with <code>Eval: False</code> no such ambiguity exists.

=== Pictures in Choice nodes ===
You can make Choice nodes with pictures as options by creating an Index with pictures in it and using that as the Index in the Choice function:
[[image:choiceimages.png|alt=|frameless|369x369px]]

''' Instructions for creating an Index with pictures'''
# Add each picture into Analytica. For help with this step, see [https://docs.analytica.com/index.php/Graphics,_frames,_and_text_in_a_diagram#Adding_graphics Adding Graphics].
# Get the identifier of each picture. You can find the identifier of a picture by clicking on the picture node and either looking at the identifier in the Attribute panel or by opening object mode. It will generally start with “Pi” and end with numbers, e.g., Pi123456789.
# Create a list of handles called ImageHandles using these picture identifiers. Both [[MetaOnly]] index or [https://docs.analytica.com/index.php/Handle_Functions#ListOfHandles.28x1.2C_x2.2C...2Cxn.29 ListofHandles] will work.
# <code>Pict of (ImageHandles)</code> will give you an array with the pictures as the values.
# Use CopyIndex to turn the array indexed by the ListofHandles into an Index

''' Example code '''

The following code is an example of an Index with pictures when you have a list of identifiers PictureIdentifier1, PictureIdentifier2, etc:

<code>CopyIndex(Pict of ListofHandles(PictureIdentifier1, PictureIdentifier2, PictureIdentifier3))</code>

The following code is an example of an Index with all of the pictures in MyModuleWithPics:

<code>CopyIndex(Pict of #FindObjects(class:Picture, within:Handle(MyModuleWithPics))</code>

You can combine picture and text in the same index when they are different slices of the array, e.g., [Picture, Text, Picture, Text], but you cannot combine pictures and text in the same slice of the Index, e.g., [Picture & Text, Picture & Text].

Once you have your list of images, you can use it in a Choice node to get a Choice with images, e.g.:

<code>Choice(IndexwithPictures, 1)</code>

=== Filtering long Choice lists (ACP) ===
In ACP, when you select a Choice menu that has more than 10 options, it shows a filter box at the top of the menu. As you type into the box, it shortens the menu showing only options that match what you have typed, like so:

[[image:choicefilter.png|link=Special:FilePath/Choicefilter.png|alt=|frameless|314x314px]]

Note that this feature is only available in ACP, not (yet) in Desktop Analytica.

== History ==
Releases prior to Analytica 4.4.2 do not support extremely long option lists on the [[Choice]] popup. In those releases, the choice pulldown displays only the first 254 items, plus the selected item. This limitation is fixed in patch release 4.4.2, where no such limitation exists. If you have many options and for some reason cannot upgrade to 4.4.2 or later, consider creating a 2-stage hierarchical menu, where the first pulldown offers subgroups, and the second shows a the items in that subgroup.

Pulldowns in [[Analytica 4.5]] and later are described [[#In Analytica 4.5 or later|above]].

[[Analytica 6.4]] added an option to add a hierarchical organization to the items by specifying an optional «nestUnder» parameter.

== See Also ==
* [[Choice menu user input]]
* [[Choice menus and Checkboxes in an edit table]]
* [[MultiChoice]]
* [[Checkbox]]
* [[Slider]]
* [[AskMsgChoice]]
* [[MetaOnly]]
* Webinar on [[Analytica_User_Group/Past_Topics#Creating_Control_Panels|Creating Control Panels]]

Array-reducing functions

2024-11-23T19:52:38Z

Max: /* Text values */

[[Category:Analytica User Guide]]
[[Category: Array-reducing functions]]
<breadcrumbs>Analytica User Guide > Array functions > {{PAGENAME}}</breadcrumbs>

An '''array-reducing function''' aggregates across an Index (dimension) of an array and returns a result without that Index. So it reduces the number of dimensions of that array by one (or more). Examples include, [[Sum]](x, i), [[Product]](x, i), [[Max]](x, i), [[Min]](x, i), and others described below. The [[Subscript and slice of a subarray |subscript]] construct [[Subscript-Slice_Operator|x[i = v]]] and related slice functions also reduce arrays by a dimension.

The function [[Sum]](x, i) illustrates some properties of reducing functions.

'''Examples'''

:<code>Sum(Car_prices, Car_type) →</code>
:{| class="wikitable" border="1"
! colspan="5" | Years ▶
|-
! style="width:75px;" |'''2005 '''
! style="width:75px;" |'''2006 '''
! style="width:75px;" |'''2007 '''
! style="width:75px;" |'''2008 '''
! style="width:75px;" |'''2009 '''
|-
| 59K
| 62K
| 66K
| 71K
| 76K
|}

:<code>Sum(Car_prices, Years) →</code>
:{| class="wikitable" border="1"
! colspan="3" | Car_type ▶
|-
! style="width:75px;" |'''VW '''
! style="width:75px;" |'''Honda '''
! style="width:75px;" |'''BMW '''
|-
| 99K
| 103K
| 141K
|}

:<code>Sum(Sum(Car_prices, Years), Car_type) → 334K</code>

Or more simply:
:<code>Sum(Car_prices, Years, Car_type) → 334K</code>

''See [[Array Function Example Variables]] for example array variables used here and below.''

<tip title="Tip">The second parameter, «i», specifying the dimension over which to sum, is optional. But if the array, «x», has more than one dimension, Analytica might not sum over the dimension you expect. For this reason, it is safer always to specify the dimension index explicitly in [[Sum]]() or any other array-reducing function.</Tip>

== Key features==

===Reduce over multiple indexes===
Most array-reducing functions, including [[Sum]], [[Product]], [[Average]], [[Min]], [[Max]], [[ArgMin]], and [[ArgMax]], let you specify more than one index. This is a convenient way to operate over multiple indexes in a single call, for example:

:Sum(x, i, j, k)

This is equivalent to:
:Sum(Sum(Sum(x, i), j), k)

===Reduce over all indexes===
You can sum over ''all'' the indexes of an array without having to list them explicitly:
:Sum(x, ... IndexesOf(x))
This necessarily returns a scalar -- i.e. value with no index. See [[Repeated Parameter Forwarding]] for details.

Below we describe the most common array-reducing functions.

===Reducing over an unused index===

If the index, «i», is not a dimension of «x», [[Sum]](x, i) returns «x» unreduced (i.e., with the same number of indexes), but multiplied by the size (number of elements) of «i». The reason is that if «x» is not indexed by «i», it means that it has the same value for all values of «i». This is true even if «x» is an atom with no dimensions:

:<code>Variable x := 5</code>
:<code>Sum(x, Car_type) → 15</code>

This is because <code>Car_type</code> has three elements (3 x 5 = 15).

In this way, if we later decide to change the value for <code>x</code> for each value of <code>Car_type</code>, we can redefine «x» as an edit table indexed by <code>Car_type</code>. Any expression containing a [[Sum]]() or other reducing function on «x» works correctly whether it is indexed by <code>Car_type</code> or not.

===Ignoring Null===

These array-reducing functions ignore elements of an array that contain [[Null]]. For example, the [[Average]](x, i) function sums all the non-null elements of «x» and divides by the number of non-null elements. This feature is very convenient when working with missing data.

===Treatment of NAN===

When the array contains a '''NaN''' value (an indeterminate number), the result of a function on the array is usually '''NaN''' as well. '''NaN''' values result from indeterminate operations such as <code>0/0</code>. NaNs propagate in this fashion to ensure that you will not accidentally compute an indeterminate result without realizing it. However, if you wish to ignore '''NaN''' values, the functions [[Sum]], [[Product]], [[Average]], [[Min]], and [[Max]] all accept an optional parameter, «ignoreNaN» that can be set to True. «IgnoreNan» requires a named-parameter syntax, for example:

:<code>Max(x, i, ignoreNaN: True)</code>

===Text values===

When the parameter contains both text and numbers, [[Sum]], [[Min]] and [[Max]] normally return NaN. But you can instruct them to ignore non-numeric values (except NaN) using the optional «ignoreNonNumbers» parameter, for example:

:<code>Max(x, i, ignoreNonNumbers: True)</code>

Functions [[Min]], [[Max]], [[ArgMin]], [[ArgMax]], [[CondMin]] and [[CondMax]] work on text values using alphabetical ordering. Min refers to the first item and Max the last item alphabetically.

==Sum(x, ''i'')==
Returns the sum of array «x» over the dimension indexed by «i».

'''Library:''' Array

'''Examples:'''

:<code>Sum(Car_prices, Years) →</code>

:{| class="wikitable" border="1"
! colspan="3" | Car_type ▶
|-
! style="width:75px;" |'''VW '''
! style="width:75px;" |'''Honda '''
! style="width:75px;" |'''BMW '''
|-
| 99K
| 103K
| 141K
|}

''See [[Array Function Example Variables]] for example array variables used here and below.''

==Product(x,''i'')==
Returns the product of all of the elements of «x», along the dimension indexed by «i». See also [[Product]]().

'''Library:''' Array

'''Examples:'''

:<code>Product(Car_prices, Car_type) →</code>
:{| class="wikitable" border="1"
! colspan="5" | Years ▶
|-
! style="width:75px;" |'''2005 '''
! style="width:75px;" |'''2006 '''
! style="width:75px;" |'''2007 '''
! style="width:75px;" |'''2008 '''
! style="width:75px;" |'''2009 '''
|-
| 7.2T
| 8.398T
| 10.08Y
| 12.54T
| 15.36T
|}

==Average(x, ''i'')==
Returns the mean value of all of the elements of array «x», averaged over index «i». See also [[Average]]().

'''Library:''' Array

'''Examples:'''

:<code>Average(Miles, Years)→</code>
:{| class="wikitable" border="1"
! colspan="3" | Car_type ▶
|-
! style="width:75px;" |'''VW '''
! style="width:75px;" |'''Honda '''
! style="width:75px;" |'''BMW '''
|-
| 8000
| 12K
| 7600
|}

==Max(x, i)==
Returns the highest valued element of «x» along index «i». See also [[Max]]().

'''Library:''' Array

'''Examples:'''

:<code>Max(Miles, Years) →</code>
:{| class="wikitable" border="1"
! colspan="3" | Car_type ▶
|-
! style="width:75px;" |'''VW '''
! style="width:75px;" |'''Honda '''
! style="width:75px;" |'''BMW '''
|-
| 10K
| 12K
| 10K
|}

To obtain the maximum of two numbers, first turn them into an array:

:<code>Max([10, 5]) → 10</code>

''See [[Array Function Example Variables]] for example array variables used here and below.''

==Min(x, ''i'')==
Returns the lowest valued element of «x» along index «i». See also [[Min]]().

'''Library:''' Array

'''Examples:'''

:<code>Min(Miles, Years) →</code>
:{| class="wikitable" border="1"
! colspan="3" | Car_type ▶
|-
! style="width:75px;" |'''VW '''
! style="width:75px;" |'''Honda '''
! style="width:75px;" |'''BMW '''
|-
| 6000
| 10K
| 5000
|}

To obtain the minimum of two numbers, first turn them into an array:

:<code>Min([10, 5]) → 5</code>

==ArgMax(a, i) and ArgMin(a, i)==
ArgMax(a, i) an item of index «i» for which array «a» is the maximum. Similarly, ArgMin(a, i) returns a value of «i» for which «a» is minimum.

'''Position''': If you specify optional parameter <code>First: True</code>, these functions return the position (integer number) isntead of the value of «i» of the maximum (or minimum) value in «a».

'''First''': If «a» has more than one maximum (minimum) value, it normally returns the last one. Or you can specify optional parameter <code>First: False</code> if you prefer to return the first one.

'''Library:''' Array

'''Example:'''
:<code>ArgMax(Miles, Car_type) →</code>
:{| class="wikitable" border="1"
! colspan="5" | Years ▶
|-
! style="width:75px;" |'''2005 '''
! style="width:75px;" |'''2006 '''
! style="width:75px;" |'''2007 '''
! style="width:75px;" |'''2008 '''
! style="width:75px;" |'''2009 '''
|-
| Honda
| Honda
| Honda
| Honda
| Honda
|}

:<code>ArgMin(Car_prices, Car_type) →</code>
:{| class="wikitable" border="1"
! colspan="5" style="text-align: left;" | Years ▶
|-
! style="width:75px;" |'''2005 '''
! style="width:75px;" |'''2006 '''
! style="width:75px;" |'''2007 '''
! style="width:75px;" |'''2008 '''
! style="width:75px;" |'''2009 '''
|-
| BMW
| VW
| BMW
| VW
| VW
|}

==CondMin(x, cond, i) and CondMax(x, cond, i)==

[[CondMin]]() "conditional min" returns the smallest value along a given index, «i», that satisfies condition «cond».
Similarly, [[CondMax]]() returns the largest When «cond» is never satisfied, [[CondMin]]() returns [[INF]] and [[CondMax]]() returns <code>-INF</code>.

'''Library:''' none

'''Examples:'''
:<code>CondMin(Cost_of_ownership, Time >= 2, Time) →</code>
:{| class="wikitable" border="1"
! colspan="3" | Car_type ▶
|-
! style="width:75px;" |'''VW '''
! style="width:75px;" |'''Honda '''
! style="width:75px;" |'''BMW '''
|-
| 3098
| 3897
| 3409
|}

==SubIndex(a, u, i)==

Does a lookup (similar to VLookup and Hlookup in Excel) returning the value of index «i» of array «a» for which «a» equals «u» -- in other words, it returns the value <code>vi</code> of index «i» for which array «a»[«i» = <code>vi] =</code> «u». If «a» contains multiple values equal to «u», it returns the last value of «i» that matches. If no value of «a» equals «u», it returns [[Null]]. If «a» has index(es) in addition to «i», or if «u» is an array with other indexes, those indexes also appear in the result. See also [[SubIndex]]().

'''Library:''' Array

'''Examples:'''
:<code>SubIndex(Car_prices, 18K, Car_type) →</code>
:{| class="wikitable" border="1"
! colspan="5"| Years ▶
|-
! style="width:75px;" |'''2005 '''
! style="width:75px;" |'''2006 '''
! style="width:75px;" |'''2007 '''
! style="width:75px;" |'''2008 '''
! style="width:75px;" |'''2009 '''
|-
| Honda
| «null»
| Honda
| «null»
| «null»
|}

:<code>SubIndex(Car_prices, 18K, Years) →</code>
:{| class="wikitable" border="1"
! colspan="3" | Car_type ▶
|-
! style="width:75px;" |'''VW '''
! style="width:75px;" |'''Honda '''
! style="width:75px;" |'''BMW '''
|-
| 2007
| 2005
| «null»
|}

If «u» is an array of values, it returns an array with the same indexes.

:<code>SubIndex(Car_prices, [18K, 19K] Car_type) →</code>
:{| class="wikitable"
!
! colspan="5" |Years ▶
|-
!Subindex ▼
!2005
!2006
!2007
!2008
!2009
|-
|'''18K'''
|Honda
|«null»
|VW
|«null»
|«null»
|-
|'''19K'''
|«null»
|Honda
|«null»
|VW
|«null»
|}

==PositionInIndex(a, x, i)==
Returns the position <code>n</code> in index «i» for which x[@i = <code>n</code>] = x — that is, a number from 1 to the size of index «i» — of the last element of array «a» equal to «x». If no element of «a» matches «x», it returns 0. See also [[PositionInIndex]]().

'''Example:'''

:<code>Index I := ['A', 'B', 'C']</code>
:<code>Variable A := Array(I, [1, 2, 2])</code>
:<code>PositionInIndex(A, 1, I) → 1</code>
:<code>PositionInIndex(A, 2, I) → 3</code>
:<code>PositionInIndex(A, 5, I) → 0</code>

<tip title="Tip">[[PositionInIndex]]() is the positional equivalent of [[Subindex]](). It is useful when «i» contains duplicate values, in which case [[Subindex]]() would return an ambiguous result.</Tip>

<tip title="Tip">Parameter a is optional. When omitted, it returns the position of x in the index i, or 0 if not found. The syntax <code>@[i = x]</code> (see [[Subscript and slice of a subarray#@: Index Position Operator|@: Index Position Operator]]) returns the same result as <code>PositionInIndex(, x, i)</code>:

:<code>PositionInIndex(, 'B', I) → 2</code>
:<code>@[I = 'B'] → 2</code>
:<code>PositionInIndex(, 'D', I) → 0</code>
:<code>@[I = 'D'] → 0</code>
</Tip>

When the array is multidimensional:
Taking the same example from above:

:<code>PositionInIndex(Car_prices, 18K, Car_type) →</code>
:{| class="wikitable" border="1"
! colspan="5"| Years ▶
|-
! style="width:75px;" |'''2005 '''
! style="width:75px;" |'''2006 '''
! style="width:75px;" |'''2007 '''
! style="width:75px;" |'''2008 '''
! style="width:75px;" |'''2009 '''
|-
| 2
| 0
| 1
| 0
| 0
|}

==Area(y, x, ''x1, x2, i'')==
Returns the area (sum of trapezoids) under the piecewise-linear curve denoted by the points
(«xi», «yi»), landing in the region «x1» ≤ «x» ≤ «x2». The arrays «x» and «y» must share the common index «i», or when either «x» or «y» is itself an index, «i» can be safely omitted. «x» and «x2» are optional; if they are not specified, the area is calculated across all values of «x».

If «x1» or «x2» fall outside the range of values in «i», the first value (for «x1») or last value (for «x1») are used. [[Area]]() computes the total integral across «x», returning a value with one less dimension than «y». Compare [[Area]]() to [[Transforming functions#Integrate()|Integrate()]].

'''Library:''' Array

'''Example'''
:<code>Area(Cost_of_ownership, Time, 0, 2) →</code>
:{| class="wikitable" border="1"
! colspan="3" | Car_type ▶
|-
! style="width:75px;" |'''VW '''
! style="width:75px;" |'''Honda '''
! style="width:75px;" |'''BMW '''
|-
| 5905
| 7563
| 6591
|}

==See Also==
<div style="column-count:2;-moz-column-count:2;-webkit-column-count:2">
* [[Tutorial: Arrays#Array_Reducing_Functions|Tutorial: Array Reducing Functions]]
* [[:Category:Array-reducing functions]]
* [[Tutorial: Arrays#Reducing_an_array_using_subscripts|Tutorial: Reducing an array using subscripts]]
* [[Sum]]()
* [[Product]]()
* [[Average]]()
* [[Functions Min and Max]]
* [[Max]]()
* [[Min]]()
* [[ArgMax]]()
* [[ArgMin]]()
* [[CondMin]]()
* [[CondMax]]()
* [[SubIndex]]()
* [[PositionInIndex]]()
* [[Area]]()
* [[Function calls and parameters]]
* [[Multidimensional array]]
* [[Relational tables and multiD arrays]]
* [[Repeated Parameter Forwarding|Reducing over all indexes]]
</div>

<footer>Functions that create arrays / {{PAGENAME}} / Transforming functions</footer>

Array-reducing functions

2024-11-23T19:45:22Z

Max: /* Text values */

[[Category:Analytica User Guide]]
[[Category: Array-reducing functions]]
<breadcrumbs>Analytica User Guide > Array functions > {{PAGENAME}}</breadcrumbs>

An '''array-reducing function''' aggregates across an Index (dimension) of an array and returns a result without that Index. So it reduces the number of dimensions of that array by one (or more). Examples include, [[Sum]](x, i), [[Product]](x, i), [[Max]](x, i), [[Min]](x, i), and others described below. The [[Subscript and slice of a subarray |subscript]] construct [[Subscript-Slice_Operator|x[i = v]]] and related slice functions also reduce arrays by a dimension.

The function [[Sum]](x, i) illustrates some properties of reducing functions.

'''Examples'''

:<code>Sum(Car_prices, Car_type) →</code>
:{| class="wikitable" border="1"
! colspan="5" | Years ▶
|-
! style="width:75px;" |'''2005 '''
! style="width:75px;" |'''2006 '''
! style="width:75px;" |'''2007 '''
! style="width:75px;" |'''2008 '''
! style="width:75px;" |'''2009 '''
|-
| 59K
| 62K
| 66K
| 71K
| 76K
|}

:<code>Sum(Car_prices, Years) →</code>
:{| class="wikitable" border="1"
! colspan="3" | Car_type ▶
|-
! style="width:75px;" |'''VW '''
! style="width:75px;" |'''Honda '''
! style="width:75px;" |'''BMW '''
|-
| 99K
| 103K
| 141K
|}

:<code>Sum(Sum(Car_prices, Years), Car_type) → 334K</code>

Or more simply:
:<code>Sum(Car_prices, Years, Car_type) → 334K</code>

''See [[Array Function Example Variables]] for example array variables used here and below.''

<tip title="Tip">The second parameter, «i», specifying the dimension over which to sum, is optional. But if the array, «x», has more than one dimension, Analytica might not sum over the dimension you expect. For this reason, it is safer always to specify the dimension index explicitly in [[Sum]]() or any other array-reducing function.</Tip>

== Key features==

===Reduce over multiple indexes===
Most array-reducing functions, including [[Sum]], [[Product]], [[Average]], [[Min]], [[Max]], [[ArgMin]], and [[ArgMax]], let you specify more than one index. This is a convenient way to operate over multiple indexes in a single call, for example:

:Sum(x, i, j, k)

This is equivalent to:
:Sum(Sum(Sum(x, i), j), k)

===Reduce over all indexes===
You can sum over ''all'' the indexes of an array without having to list them explicitly:
:Sum(x, ... IndexesOf(x))
This necessarily returns a scalar -- i.e. value with no index. See [[Repeated Parameter Forwarding]] for details.

Below we describe the most common array-reducing functions.

===Reducing over an unused index===

If the index, «i», is not a dimension of «x», [[Sum]](x, i) returns «x» unreduced (i.e., with the same number of indexes), but multiplied by the size (number of elements) of «i». The reason is that if «x» is not indexed by «i», it means that it has the same value for all values of «i». This is true even if «x» is an atom with no dimensions:

:<code>Variable x := 5</code>
:<code>Sum(x, Car_type) → 15</code>

This is because <code>Car_type</code> has three elements (3 x 5 = 15).

In this way, if we later decide to change the value for <code>x</code> for each value of <code>Car_type</code>, we can redefine «x» as an edit table indexed by <code>Car_type</code>. Any expression containing a [[Sum]]() or other reducing function on «x» works correctly whether it is indexed by <code>Car_type</code> or not.

===Ignoring Null===

These array-reducing functions ignore elements of an array that contain [[Null]]. For example, the [[Average]](x, i) function sums all the non-null elements of «x» and divides by the number of non-null elements. This feature is very convenient when working with missing data.

===Treatment of NAN===

When the array contains a '''NaN''' value (an indeterminate number), the result of a function on the array is usually '''NaN''' as well. '''NaN''' values result from indeterminate operations such as <code>0/0</code>. NaNs propagate in this fashion to ensure that you will not accidentally compute an indeterminate result without realizing it. However, if you wish to ignore '''NaN''' values, the functions [[Sum]], [[Product]], [[Average]], [[Min]], and [[Max]] all accept an optional parameter, «ignoreNaN» that can be set to True. «IgnoreNan» requires a named-parameter syntax, for example:

:<code>Max(x, i, ignoreNaN: True)</code>

===Text values===

When the parameter contains both text and numbers, these functions normally return NaN. But you can instruct [[Sum]], [[Min]] and [[Max]] to ignore non-numeric values (except NaN) using the optional «ignoreNonNumbers» parameter, for example:

:<code>Max(x, i, ignoreNonNumbers: True)</code>

==Sum(x, ''i'')==
Returns the sum of array «x» over the dimension indexed by «i».

'''Library:''' Array

'''Examples:'''

:<code>Sum(Car_prices, Years) →</code>

:{| class="wikitable" border="1"
! colspan="3" | Car_type ▶
|-
! style="width:75px;" |'''VW '''
! style="width:75px;" |'''Honda '''
! style="width:75px;" |'''BMW '''
|-
| 99K
| 103K
| 141K
|}

''See [[Array Function Example Variables]] for example array variables used here and below.''

==Product(x,''i'')==
Returns the product of all of the elements of «x», along the dimension indexed by «i». See also [[Product]]().

'''Library:''' Array

'''Examples:'''

:<code>Product(Car_prices, Car_type) →</code>
:{| class="wikitable" border="1"
! colspan="5" | Years ▶
|-
! style="width:75px;" |'''2005 '''
! style="width:75px;" |'''2006 '''
! style="width:75px;" |'''2007 '''
! style="width:75px;" |'''2008 '''
! style="width:75px;" |'''2009 '''
|-
| 7.2T
| 8.398T
| 10.08Y
| 12.54T
| 15.36T
|}

==Average(x, ''i'')==
Returns the mean value of all of the elements of array «x», averaged over index «i». See also [[Average]]().

'''Library:''' Array

'''Examples:'''

:<code>Average(Miles, Years)→</code>
:{| class="wikitable" border="1"
! colspan="3" | Car_type ▶
|-
! style="width:75px;" |'''VW '''
! style="width:75px;" |'''Honda '''
! style="width:75px;" |'''BMW '''
|-
| 8000
| 12K
| 7600
|}

==Max(x, i)==
Returns the highest valued element of «x» along index «i». See also [[Max]]().

'''Library:''' Array

'''Examples:'''

:<code>Max(Miles, Years) →</code>
:{| class="wikitable" border="1"
! colspan="3" | Car_type ▶
|-
! style="width:75px;" |'''VW '''
! style="width:75px;" |'''Honda '''
! style="width:75px;" |'''BMW '''
|-
| 10K
| 12K
| 10K
|}

To obtain the maximum of two numbers, first turn them into an array:

:<code>Max([10, 5]) → 10</code>

''See [[Array Function Example Variables]] for example array variables used here and below.''

==Min(x, ''i'')==
Returns the lowest valued element of «x» along index «i». See also [[Min]]().

'''Library:''' Array

'''Examples:'''

:<code>Min(Miles, Years) →</code>
:{| class="wikitable" border="1"
! colspan="3" | Car_type ▶
|-
! style="width:75px;" |'''VW '''
! style="width:75px;" |'''Honda '''
! style="width:75px;" |'''BMW '''
|-
| 6000
| 10K
| 5000
|}

To obtain the minimum of two numbers, first turn them into an array:

:<code>Min([10, 5]) → 5</code>

==ArgMax(a, i) and ArgMin(a, i)==
ArgMax(a, i) an item of index «i» for which array «a» is the maximum. Similarly, ArgMin(a, i) returns a value of «i» for which «a» is minimum.

'''Position''': If you specify optional parameter <code>First: True</code>, these functions return the position (integer number) isntead of the value of «i» of the maximum (or minimum) value in «a».

'''First''': If «a» has more than one maximum (minimum) value, it normally returns the last one. Or you can specify optional parameter <code>First: False</code> if you prefer to return the first one.

'''Library:''' Array

'''Example:'''
:<code>ArgMax(Miles, Car_type) →</code>
:{| class="wikitable" border="1"
! colspan="5" | Years ▶
|-
! style="width:75px;" |'''2005 '''
! style="width:75px;" |'''2006 '''
! style="width:75px;" |'''2007 '''
! style="width:75px;" |'''2008 '''
! style="width:75px;" |'''2009 '''
|-
| Honda
| Honda
| Honda
| Honda
| Honda
|}

:<code>ArgMin(Car_prices, Car_type) →</code>
:{| class="wikitable" border="1"
! colspan="5" style="text-align: left;" | Years ▶
|-
! style="width:75px;" |'''2005 '''
! style="width:75px;" |'''2006 '''
! style="width:75px;" |'''2007 '''
! style="width:75px;" |'''2008 '''
! style="width:75px;" |'''2009 '''
|-
| BMW
| VW
| BMW
| VW
| VW
|}

==CondMin(x, cond, i) and CondMax(x, cond, i)==

[[CondMin]]() "conditional min" returns the smallest value along a given index, «i», that satisfies condition «cond».
Similarly, [[CondMax]]() returns the largest When «cond» is never satisfied, [[CondMin]]() returns [[INF]] and [[CondMax]]() returns <code>-INF</code>.

'''Library:''' none

'''Examples:'''
:<code>CondMin(Cost_of_ownership, Time >= 2, Time) →</code>
:{| class="wikitable" border="1"
! colspan="3" | Car_type ▶
|-
! style="width:75px;" |'''VW '''
! style="width:75px;" |'''Honda '''
! style="width:75px;" |'''BMW '''
|-
| 3098
| 3897
| 3409
|}

==SubIndex(a, u, i)==

Does a lookup (similar to VLookup and Hlookup in Excel) returning the value of index «i» of array «a» for which «a» equals «u» -- in other words, it returns the value <code>vi</code> of index «i» for which array «a»[«i» = <code>vi] =</code> «u». If «a» contains multiple values equal to «u», it returns the last value of «i» that matches. If no value of «a» equals «u», it returns [[Null]]. If «a» has index(es) in addition to «i», or if «u» is an array with other indexes, those indexes also appear in the result. See also [[SubIndex]]().

'''Library:''' Array

'''Examples:'''
:<code>SubIndex(Car_prices, 18K, Car_type) →</code>
:{| class="wikitable" border="1"
! colspan="5"| Years ▶
|-
! style="width:75px;" |'''2005 '''
! style="width:75px;" |'''2006 '''
! style="width:75px;" |'''2007 '''
! style="width:75px;" |'''2008 '''
! style="width:75px;" |'''2009 '''
|-
| Honda
| «null»
| Honda
| «null»
| «null»
|}

:<code>SubIndex(Car_prices, 18K, Years) →</code>
:{| class="wikitable" border="1"
! colspan="3" | Car_type ▶
|-
! style="width:75px;" |'''VW '''
! style="width:75px;" |'''Honda '''
! style="width:75px;" |'''BMW '''
|-
| 2007
| 2005
| «null»
|}

If «u» is an array of values, it returns an array with the same indexes.

:<code>SubIndex(Car_prices, [18K, 19K] Car_type) →</code>
:{| class="wikitable"
!
! colspan="5" |Years ▶
|-
!Subindex ▼
!2005
!2006
!2007
!2008
!2009
|-
|'''18K'''
|Honda
|«null»
|VW
|«null»
|«null»
|-
|'''19K'''
|«null»
|Honda
|«null»
|VW
|«null»
|}

==PositionInIndex(a, x, i)==
Returns the position <code>n</code> in index «i» for which x[@i = <code>n</code>] = x — that is, a number from 1 to the size of index «i» — of the last element of array «a» equal to «x». If no element of «a» matches «x», it returns 0. See also [[PositionInIndex]]().

'''Example:'''

:<code>Index I := ['A', 'B', 'C']</code>
:<code>Variable A := Array(I, [1, 2, 2])</code>
:<code>PositionInIndex(A, 1, I) → 1</code>
:<code>PositionInIndex(A, 2, I) → 3</code>
:<code>PositionInIndex(A, 5, I) → 0</code>

<tip title="Tip">[[PositionInIndex]]() is the positional equivalent of [[Subindex]](). It is useful when «i» contains duplicate values, in which case [[Subindex]]() would return an ambiguous result.</Tip>

<tip title="Tip">Parameter a is optional. When omitted, it returns the position of x in the index i, or 0 if not found. The syntax <code>@[i = x]</code> (see [[Subscript and slice of a subarray#@: Index Position Operator|@: Index Position Operator]]) returns the same result as <code>PositionInIndex(, x, i)</code>:

:<code>PositionInIndex(, 'B', I) → 2</code>
:<code>@[I = 'B'] → 2</code>
:<code>PositionInIndex(, 'D', I) → 0</code>
:<code>@[I = 'D'] → 0</code>
</Tip>

When the array is multidimensional:
Taking the same example from above:

:<code>PositionInIndex(Car_prices, 18K, Car_type) →</code>
:{| class="wikitable" border="1"
! colspan="5"| Years ▶
|-
! style="width:75px;" |'''2005 '''
! style="width:75px;" |'''2006 '''
! style="width:75px;" |'''2007 '''
! style="width:75px;" |'''2008 '''
! style="width:75px;" |'''2009 '''
|-
| 2
| 0
| 1
| 0
| 0
|}

==Area(y, x, ''x1, x2, i'')==
Returns the area (sum of trapezoids) under the piecewise-linear curve denoted by the points
(«xi», «yi»), landing in the region «x1» ≤ «x» ≤ «x2». The arrays «x» and «y» must share the common index «i», or when either «x» or «y» is itself an index, «i» can be safely omitted. «x» and «x2» are optional; if they are not specified, the area is calculated across all values of «x».

If «x1» or «x2» fall outside the range of values in «i», the first value (for «x1») or last value (for «x1») are used. [[Area]]() computes the total integral across «x», returning a value with one less dimension than «y». Compare [[Area]]() to [[Transforming functions#Integrate()|Integrate()]].

'''Library:''' Array

'''Example'''
:<code>Area(Cost_of_ownership, Time, 0, 2) →</code>
:{| class="wikitable" border="1"
! colspan="3" | Car_type ▶
|-
! style="width:75px;" |'''VW '''
! style="width:75px;" |'''Honda '''
! style="width:75px;" |'''BMW '''
|-
| 5905
| 7563
| 6591
|}

==See Also==
<div style="column-count:2;-moz-column-count:2;-webkit-column-count:2">
* [[Tutorial: Arrays#Array_Reducing_Functions|Tutorial: Array Reducing Functions]]
* [[:Category:Array-reducing functions]]
* [[Tutorial: Arrays#Reducing_an_array_using_subscripts|Tutorial: Reducing an array using subscripts]]
* [[Sum]]()
* [[Product]]()
* [[Average]]()
* [[Functions Min and Max]]
* [[Max]]()
* [[Min]]()
* [[ArgMax]]()
* [[ArgMin]]()
* [[CondMin]]()
* [[CondMax]]()
* [[SubIndex]]()
* [[PositionInIndex]]()
* [[Area]]()
* [[Function calls and parameters]]
* [[Multidimensional array]]
* [[Relational tables and multiD arrays]]
* [[Repeated Parameter Forwarding|Reducing over all indexes]]
</div>

<footer>Functions that create arrays / {{PAGENAME}} / Transforming functions</footer>

Array-reducing functions

2024-11-23T19:42:06Z

Max:

[[Category:Analytica User Guide]]
[[Category: Array-reducing functions]]
<breadcrumbs>Analytica User Guide > Array functions > {{PAGENAME}}</breadcrumbs>

An '''array-reducing function''' aggregates across an Index (dimension) of an array and returns a result without that Index. So it reduces the number of dimensions of that array by one (or more). Examples include, [[Sum]](x, i), [[Product]](x, i), [[Max]](x, i), [[Min]](x, i), and others described below. The [[Subscript and slice of a subarray |subscript]] construct [[Subscript-Slice_Operator|x[i = v]]] and related slice functions also reduce arrays by a dimension.

The function [[Sum]](x, i) illustrates some properties of reducing functions.

'''Examples'''

:<code>Sum(Car_prices, Car_type) →</code>
:{| class="wikitable" border="1"
! colspan="5" | Years ▶
|-
! style="width:75px;" |'''2005 '''
! style="width:75px;" |'''2006 '''
! style="width:75px;" |'''2007 '''
! style="width:75px;" |'''2008 '''
! style="width:75px;" |'''2009 '''
|-
| 59K
| 62K
| 66K
| 71K
| 76K
|}

:<code>Sum(Car_prices, Years) →</code>
:{| class="wikitable" border="1"
! colspan="3" | Car_type ▶
|-
! style="width:75px;" |'''VW '''
! style="width:75px;" |'''Honda '''
! style="width:75px;" |'''BMW '''
|-
| 99K
| 103K
| 141K
|}

:<code>Sum(Sum(Car_prices, Years), Car_type) → 334K</code>

Or more simply:
:<code>Sum(Car_prices, Years, Car_type) → 334K</code>

''See [[Array Function Example Variables]] for example array variables used here and below.''

<tip title="Tip">The second parameter, «i», specifying the dimension over which to sum, is optional. But if the array, «x», has more than one dimension, Analytica might not sum over the dimension you expect. For this reason, it is safer always to specify the dimension index explicitly in [[Sum]]() or any other array-reducing function.</Tip>

== Key features==

===Reduce over multiple indexes===
Most array-reducing functions, including [[Sum]], [[Product]], [[Average]], [[Min]], [[Max]], [[ArgMin]], and [[ArgMax]], let you specify more than one index. This is a convenient way to operate over multiple indexes in a single call, for example:

:Sum(x, i, j, k)

This is equivalent to:
:Sum(Sum(Sum(x, i), j), k)

===Reduce over all indexes===
You can sum over ''all'' the indexes of an array without having to list them explicitly:
:Sum(x, ... IndexesOf(x))
This necessarily returns a scalar -- i.e. value with no index. See [[Repeated Parameter Forwarding]] for details.

Below we describe the most common array-reducing functions.

===Reducing over an unused index===

If the index, «i», is not a dimension of «x», [[Sum]](x, i) returns «x» unreduced (i.e., with the same number of indexes), but multiplied by the size (number of elements) of «i». The reason is that if «x» is not indexed by «i», it means that it has the same value for all values of «i». This is true even if «x» is an atom with no dimensions:

:<code>Variable x := 5</code>
:<code>Sum(x, Car_type) → 15</code>

This is because <code>Car_type</code> has three elements (3 x 5 = 15).

In this way, if we later decide to change the value for <code>x</code> for each value of <code>Car_type</code>, we can redefine «x» as an edit table indexed by <code>Car_type</code>. Any expression containing a [[Sum]]() or other reducing function on «x» works correctly whether it is indexed by <code>Car_type</code> or not.

===Ignoring Null===

These array-reducing functions ignore elements of an array that contain [[Null]]. For example, the [[Average]](x, i) function sums all the non-null elements of «x» and divides by the number of non-null elements. This feature is very convenient when working with missing data.

===Treatment of NAN===

When the array contains a '''NaN''' value (an indeterminate number), the result of a function on the array is usually '''NaN''' as well. '''NaN''' values result from indeterminate operations such as <code>0/0</code>. NaNs propagate in this fashion to ensure that you will not accidentally compute an indeterminate result without realizing it. However, if you wish to ignore '''NaN''' values, the functions [[Sum]], [[Product]], [[Average]], [[Min]], and [[Max]] all accept an optional parameter, «ignoreNaN» that can be set to True. «IgnoreNan» requires a named-parameter syntax, for example:

:<code>Max(x, i, ignoreNaN: True)</code>

===Text values===

When the parameter contains both text and numbers, you can instruct [[Sum]], [[Min]] and [[Max]] to ignore the non-numeric values using the optional «ignoreNonNumbers» parameter, for example:

:<code>Max(x, i, ignoreNonNumbers: True)</code>

==Sum(x, ''i'')==
Returns the sum of array «x» over the dimension indexed by «i».

'''Library:''' Array

'''Examples:'''

:<code>Sum(Car_prices, Years) →</code>

:{| class="wikitable" border="1"
! colspan="3" | Car_type ▶
|-
! style="width:75px;" |'''VW '''
! style="width:75px;" |'''Honda '''
! style="width:75px;" |'''BMW '''
|-
| 99K
| 103K
| 141K
|}

''See [[Array Function Example Variables]] for example array variables used here and below.''

==Product(x,''i'')==
Returns the product of all of the elements of «x», along the dimension indexed by «i». See also [[Product]]().

'''Library:''' Array

'''Examples:'''

:<code>Product(Car_prices, Car_type) →</code>
:{| class="wikitable" border="1"
! colspan="5" | Years ▶
|-
! style="width:75px;" |'''2005 '''
! style="width:75px;" |'''2006 '''
! style="width:75px;" |'''2007 '''
! style="width:75px;" |'''2008 '''
! style="width:75px;" |'''2009 '''
|-
| 7.2T
| 8.398T
| 10.08Y
| 12.54T
| 15.36T
|}

==Average(x, ''i'')==
Returns the mean value of all of the elements of array «x», averaged over index «i». See also [[Average]]().

'''Library:''' Array

'''Examples:'''

:<code>Average(Miles, Years)→</code>
:{| class="wikitable" border="1"
! colspan="3" | Car_type ▶
|-
! style="width:75px;" |'''VW '''
! style="width:75px;" |'''Honda '''
! style="width:75px;" |'''BMW '''
|-
| 8000
| 12K
| 7600
|}

==Max(x, i)==
Returns the highest valued element of «x» along index «i». See also [[Max]]().

'''Library:''' Array

'''Examples:'''

:<code>Max(Miles, Years) →</code>
:{| class="wikitable" border="1"
! colspan="3" | Car_type ▶
|-
! style="width:75px;" |'''VW '''
! style="width:75px;" |'''Honda '''
! style="width:75px;" |'''BMW '''
|-
| 10K
| 12K
| 10K
|}

To obtain the maximum of two numbers, first turn them into an array:

:<code>Max([10, 5]) → 10</code>

''See [[Array Function Example Variables]] for example array variables used here and below.''

==Min(x, ''i'')==
Returns the lowest valued element of «x» along index «i». See also [[Min]]().

'''Library:''' Array

'''Examples:'''

:<code>Min(Miles, Years) →</code>
:{| class="wikitable" border="1"
! colspan="3" | Car_type ▶
|-
! style="width:75px;" |'''VW '''
! style="width:75px;" |'''Honda '''
! style="width:75px;" |'''BMW '''
|-
| 6000
| 10K
| 5000
|}

To obtain the minimum of two numbers, first turn them into an array:

:<code>Min([10, 5]) → 5</code>

==ArgMax(a, i) and ArgMin(a, i)==
ArgMax(a, i) an item of index «i» for which array «a» is the maximum. Similarly, ArgMin(a, i) returns a value of «i» for which «a» is minimum.

'''Position''': If you specify optional parameter <code>First: True</code>, these functions return the position (integer number) isntead of the value of «i» of the maximum (or minimum) value in «a».

'''First''': If «a» has more than one maximum (minimum) value, it normally returns the last one. Or you can specify optional parameter <code>First: False</code> if you prefer to return the first one.

'''Library:''' Array

'''Example:'''
:<code>ArgMax(Miles, Car_type) →</code>
:{| class="wikitable" border="1"
! colspan="5" | Years ▶
|-
! style="width:75px;" |'''2005 '''
! style="width:75px;" |'''2006 '''
! style="width:75px;" |'''2007 '''
! style="width:75px;" |'''2008 '''
! style="width:75px;" |'''2009 '''
|-
| Honda
| Honda
| Honda
| Honda
| Honda
|}

:<code>ArgMin(Car_prices, Car_type) →</code>
:{| class="wikitable" border="1"
! colspan="5" style="text-align: left;" | Years ▶
|-
! style="width:75px;" |'''2005 '''
! style="width:75px;" |'''2006 '''
! style="width:75px;" |'''2007 '''
! style="width:75px;" |'''2008 '''
! style="width:75px;" |'''2009 '''
|-
| BMW
| VW
| BMW
| VW
| VW
|}

==CondMin(x, cond, i) and CondMax(x, cond, i)==

[[CondMin]]() "conditional min" returns the smallest value along a given index, «i», that satisfies condition «cond».
Similarly, [[CondMax]]() returns the largest When «cond» is never satisfied, [[CondMin]]() returns [[INF]] and [[CondMax]]() returns <code>-INF</code>.

'''Library:''' none

'''Examples:'''
:<code>CondMin(Cost_of_ownership, Time >= 2, Time) →</code>
:{| class="wikitable" border="1"
! colspan="3" | Car_type ▶
|-
! style="width:75px;" |'''VW '''
! style="width:75px;" |'''Honda '''
! style="width:75px;" |'''BMW '''
|-
| 3098
| 3897
| 3409
|}

==SubIndex(a, u, i)==

Does a lookup (similar to VLookup and Hlookup in Excel) returning the value of index «i» of array «a» for which «a» equals «u» -- in other words, it returns the value <code>vi</code> of index «i» for which array «a»[«i» = <code>vi] =</code> «u». If «a» contains multiple values equal to «u», it returns the last value of «i» that matches. If no value of «a» equals «u», it returns [[Null]]. If «a» has index(es) in addition to «i», or if «u» is an array with other indexes, those indexes also appear in the result. See also [[SubIndex]]().

'''Library:''' Array

'''Examples:'''
:<code>SubIndex(Car_prices, 18K, Car_type) →</code>
:{| class="wikitable" border="1"
! colspan="5"| Years ▶
|-
! style="width:75px;" |'''2005 '''
! style="width:75px;" |'''2006 '''
! style="width:75px;" |'''2007 '''
! style="width:75px;" |'''2008 '''
! style="width:75px;" |'''2009 '''
|-
| Honda
| «null»
| Honda
| «null»
| «null»
|}

:<code>SubIndex(Car_prices, 18K, Years) →</code>
:{| class="wikitable" border="1"
! colspan="3" | Car_type ▶
|-
! style="width:75px;" |'''VW '''
! style="width:75px;" |'''Honda '''
! style="width:75px;" |'''BMW '''
|-
| 2007
| 2005
| «null»
|}

If «u» is an array of values, it returns an array with the same indexes.

:<code>SubIndex(Car_prices, [18K, 19K] Car_type) →</code>
:{| class="wikitable"
!
! colspan="5" |Years ▶
|-
!Subindex ▼
!2005
!2006
!2007
!2008
!2009
|-
|'''18K'''
|Honda
|«null»
|VW
|«null»
|«null»
|-
|'''19K'''
|«null»
|Honda
|«null»
|VW
|«null»
|}

==PositionInIndex(a, x, i)==
Returns the position <code>n</code> in index «i» for which x[@i = <code>n</code>] = x — that is, a number from 1 to the size of index «i» — of the last element of array «a» equal to «x». If no element of «a» matches «x», it returns 0. See also [[PositionInIndex]]().

'''Example:'''

:<code>Index I := ['A', 'B', 'C']</code>
:<code>Variable A := Array(I, [1, 2, 2])</code>
:<code>PositionInIndex(A, 1, I) → 1</code>
:<code>PositionInIndex(A, 2, I) → 3</code>
:<code>PositionInIndex(A, 5, I) → 0</code>

<tip title="Tip">[[PositionInIndex]]() is the positional equivalent of [[Subindex]](). It is useful when «i» contains duplicate values, in which case [[Subindex]]() would return an ambiguous result.</Tip>

<tip title="Tip">Parameter a is optional. When omitted, it returns the position of x in the index i, or 0 if not found. The syntax <code>@[i = x]</code> (see [[Subscript and slice of a subarray#@: Index Position Operator|@: Index Position Operator]]) returns the same result as <code>PositionInIndex(, x, i)</code>:

:<code>PositionInIndex(, 'B', I) → 2</code>
:<code>@[I = 'B'] → 2</code>
:<code>PositionInIndex(, 'D', I) → 0</code>
:<code>@[I = 'D'] → 0</code>
</Tip>

When the array is multidimensional:
Taking the same example from above:

:<code>PositionInIndex(Car_prices, 18K, Car_type) →</code>
:{| class="wikitable" border="1"
! colspan="5"| Years ▶
|-
! style="width:75px;" |'''2005 '''
! style="width:75px;" |'''2006 '''
! style="width:75px;" |'''2007 '''
! style="width:75px;" |'''2008 '''
! style="width:75px;" |'''2009 '''
|-
| 2
| 0
| 1
| 0
| 0
|}

==Area(y, x, ''x1, x2, i'')==
Returns the area (sum of trapezoids) under the piecewise-linear curve denoted by the points
(«xi», «yi»), landing in the region «x1» ≤ «x» ≤ «x2». The arrays «x» and «y» must share the common index «i», or when either «x» or «y» is itself an index, «i» can be safely omitted. «x» and «x2» are optional; if they are not specified, the area is calculated across all values of «x».

If «x1» or «x2» fall outside the range of values in «i», the first value (for «x1») or last value (for «x1») are used. [[Area]]() computes the total integral across «x», returning a value with one less dimension than «y». Compare [[Area]]() to [[Transforming functions#Integrate()|Integrate()]].

'''Library:''' Array

'''Example'''
:<code>Area(Cost_of_ownership, Time, 0, 2) →</code>
:{| class="wikitable" border="1"
! colspan="3" | Car_type ▶
|-
! style="width:75px;" |'''VW '''
! style="width:75px;" |'''Honda '''
! style="width:75px;" |'''BMW '''
|-
| 5905
| 7563
| 6591
|}

==See Also==
<div style="column-count:2;-moz-column-count:2;-webkit-column-count:2">
* [[Tutorial: Arrays#Array_Reducing_Functions|Tutorial: Array Reducing Functions]]
* [[:Category:Array-reducing functions]]
* [[Tutorial: Arrays#Reducing_an_array_using_subscripts|Tutorial: Reducing an array using subscripts]]
* [[Sum]]()
* [[Product]]()
* [[Average]]()
* [[Functions Min and Max]]
* [[Max]]()
* [[Min]]()
* [[ArgMax]]()
* [[ArgMin]]()
* [[CondMin]]()
* [[CondMax]]()
* [[SubIndex]]()
* [[PositionInIndex]]()
* [[Area]]()
* [[Function calls and parameters]]
* [[Multidimensional array]]
* [[Relational tables and multiD arrays]]
* [[Repeated Parameter Forwarding|Reducing over all indexes]]
</div>

<footer>Functions that create arrays / {{PAGENAME}} / Transforming functions</footer>

Array-reducing functions

2024-11-23T19:20:50Z

Max:

[[Category:Analytica User Guide]]
[[Category: Array-reducing functions]]
<breadcrumbs>Analytica User Guide > Array functions > {{PAGENAME}}</breadcrumbs>

An '''array-reducing function''' aggregates across an Index (dimension) of an array and returns a result without that Index. So reduces the number of dimensions of that array by one (or more). Examples include, [[Sum]](x, i), [[Product]](x, i), [[Max]](x, i), [[Min]](x, i), and others described below. The [[Subscript and slice of a subarray |subscript]] construct [[Subscript-Slice_Operator|x[i = v]]] and related slice functions also reduce arrays by a dimension.

The function [[Sum]](x, i) illustrates some properties of reducing functions.

'''Examples'''

:<code>Sum(Car_prices, Car_type) →</code>
:{| class="wikitable" border="1"
! colspan="5" | Years ▶
|-
! style="width:75px;" |'''2005 '''
! style="width:75px;" |'''2006 '''
! style="width:75px;" |'''2007 '''
! style="width:75px;" |'''2008 '''
! style="width:75px;" |'''2009 '''
|-
| 59K
| 62K
| 66K
| 71K
| 76K
|}

:<code>Sum(Car_prices, Years) →</code>
:{| class="wikitable" border="1"
! colspan="3" | Car_type ▶
|-
! style="width:75px;" |'''VW '''
! style="width:75px;" |'''Honda '''
! style="width:75px;" |'''BMW '''
|-
| 99K
| 103K
| 141K
|}

:<code>Sum(Sum(Car_prices, Years), Car_type) → 334K</code>

''See [[Array Function Example Variables]] for example array variables used here and below.''

<tip title="Tip">The second parameter, «i», specifying the dimension over which to sum, is optional. But if the array, «x», has more than one dimension, Analytica might not sum over the dimension you expect. For this reason, it is safer always to specify the dimension index explicitly in [[Sum]]() or any other array-reducing function.</Tip>

'''Reducing over an unused index:''' If the index, «i», is not a dimension of «x», [[Sum]](x, i) returns «x» unreduced (i.e., with the same number of indexes), but multiplied by the size (number of elements) of «i». The reason is that if «x» is not indexed by «i», it means that it has the same value for all values of «i». This is true even if «x» is an atom with no dimensions:

:<code>Variable x := 5</code>
:<code>Sum(x, Car_type) → 15</code>

This is because <code>Car_type</code> has three elements (3 x 5 = 15).

In this way, if we later decide to change the value for <code>x</code> for each value of <code>Car_type</code>, we can redefine «x» as an edit table indexed by <code>Car_type</code>. Any expression containing a [[Sum]]() or other reducing function on «x» works correctly whether it is indexed by <code>Car_type</code> or not.

'''Elements that are ignored:''' These array-reducing functions ignore elements of an array that contain [[Null]]. For example, the [[Average]](x, i) function sums all the non-null elements of «x» and divides by the number of non-null elements.

'''IgnoreNaN''': When a '''NaN''' value (an indeterminate number) appears as an element of an array, the result of a function that operates on the array is usually '''NaN''' as well. '''NaN''' values result from indeterminate operations such as <code>0/0</code>. They propagate forward in this fashion to ensure that you will not accidentally compute an indeterminate result without realizing it. However, in some cases you might wish to ignore '''NaN''' values in an array-reducing operation. The functions [[Sum]], [[Product]], [[Average]], [[Min]], and [[Max]] all accept an optional parameter, «ignoreNaN» that can be set to True. «IgnoreNan» requires a named-parameter syntax, for example:

:<code>Max(x, i, ignoreNaN: True)</code>

'''ignoreNonNumbers''': When the parameter contains both text and numbers, you can instruct [[Sum]], [[Min]] and [[Max]] to ignore the non-numeric values using the optional «ignoreNonNumbers» parameter, for example:

:<code>Max(x, i, ignoreNonNumbers: True)</code>

'''Reduce over multiple indexes:''' Most array-reducing functions, including [[Sum]], [[Product]], [[Average]], [[Min]], [[Max]], [[ArgMin]], and [[ArgMax]], let you specify more than one index. This is a convenient way to reduce over multiple indexes in a single call, for example:

:Sum(x, i, j, k)

This is equivalent to:
:Sum(Sum(Sum(x, i), j), k)

'''Reduce over all indexes''': You can sum over ''all'' the indexes of an array without having to list them explicitly:
:Sum(x, ... IndexesOf(x))
This necessarily returns a scalar -- i.e. value with no index. See [[Repeated Parameter Forwarding]] for details.

Below we describe the most common array-reducing functions.

==Sum(x, ''i'')==
Returns the sum of array «x» over the dimension indexed by «i».

'''Library:''' Array

'''Examples:'''

:<code>Sum(Car_prices, Years) →</code>

:{| class="wikitable" border="1"
! colspan="3" | Car_type ▶
|-
! style="width:75px;" |'''VW '''
! style="width:75px;" |'''Honda '''
! style="width:75px;" |'''BMW '''
|-
| 99K
| 103K
| 141K
|}

''See [[Array Function Example Variables]] for example array variables used here and below.''

==Product(x,''i'')==
Returns the product of all of the elements of «x», along the dimension indexed by «i». See also [[Product]]().

'''Library:''' Array

'''Examples:'''

:<code>Product(Car_prices, Car_type) →</code>
:{| class="wikitable" border="1"
! colspan="5" | Years ▶
|-
! style="width:75px;" |'''2005 '''
! style="width:75px;" |'''2006 '''
! style="width:75px;" |'''2007 '''
! style="width:75px;" |'''2008 '''
! style="width:75px;" |'''2009 '''
|-
| 7.2T
| 8.398T
| 10.08Y
| 12.54T
| 15.36T
|}

==Average(x, ''i'')==
Returns the mean value of all of the elements of array «x», averaged over index «i». See also [[Average]]().

'''Library:''' Array

'''Examples:'''

:<code>Average(Miles, Years)→</code>
:{| class="wikitable" border="1"
! colspan="3" | Car_type ▶
|-
! style="width:75px;" |'''VW '''
! style="width:75px;" |'''Honda '''
! style="width:75px;" |'''BMW '''
|-
| 8000
| 12K
| 7600
|}

==Max(x, i)==
Returns the highest valued element of «x» along index «i». See also [[Max]]().

'''Library:''' Array

'''Examples:'''

:<code>Max(Miles, Years) →</code>
:{| class="wikitable" border="1"
! colspan="3" | Car_type ▶
|-
! style="width:75px;" |'''VW '''
! style="width:75px;" |'''Honda '''
! style="width:75px;" |'''BMW '''
|-
| 10K
| 12K
| 10K
|}

To obtain the maximum of two numbers, first turn them into an array:

:<code>Max([10, 5]) → 10</code>

''See [[Array Function Example Variables]] for example array variables used here and below.''

==Min(x, ''i'')==
Returns the lowest valued element of «x» along index «i». See also [[Min]]().

'''Library:''' Array

'''Examples:'''

:<code>Min(Miles, Years) →</code>
:{| class="wikitable" border="1"
! colspan="3" | Car_type ▶
|-
! style="width:75px;" |'''VW '''
! style="width:75px;" |'''Honda '''
! style="width:75px;" |'''BMW '''
|-
| 6000
| 10K
| 5000
|}

To obtain the minimum of two numbers, first turn them into an array:

:<code>Min([10, 5]) → 5</code>

==ArgMax(a, i)==
Returns the item of index «i» for which array «a» is the maximum. If «a» has more than one value equal to the maximum, it returns the index of the last one. See also [[ArgMax]]().

'''Library:''' Array

'''Example:'''
:<code>ArgMax(Miles, Car_type) →</code>
:{| class="wikitable" border="1"
! colspan="5" | Years ▶
|-
! style="width:75px;" |'''2005 '''
! style="width:75px;" |'''2006 '''
! style="width:75px;" |'''2007 '''
! style="width:75px;" |'''2008 '''
! style="width:75px;" |'''2009 '''
|-
| Honda
| Honda
| Honda
| Honda
| Honda
|}

==ArgMin(a, i)==
Returns the corresponding value in index «i» for which array «a» is the minimum. If more than one value equals the minimum, returns the index of the last occurrence. See also [[ArgMin]]().

'''Library:''' Array

'''Example:'''
:<code>ArgMin(Car_prices, Car_type) →</code>
:{| class="wikitable" border="1"
! colspan="5" style="text-align: left;" | Years ▶
|-
! style="width:75px;" |'''2005 '''
! style="width:75px;" |'''2006 '''
! style="width:75px;" |'''2007 '''
! style="width:75px;" |'''2008 '''
! style="width:75px;" |'''2009 '''
|-
| BMW
| VW
| BMW
| VW
| VW
|}

==CondMin(x, cond, i) and CondMax(x, cond, i)==
[[CondMin]]() "conditional min" returns the smallest value along a given index, «i», that satisfies condition «cond».
Similarly, [[CondMax]]() returns the largest When «cond» is never satisfied, [[CondMin]]() returns [[INF]] and [[CondMax]]() returns <code>-INF</code>.

'''Library:''' none

'''Examples:'''
:<code>CondMin(Cost_of_ownership, Time >= 2, Time) →</code>
:{| class="wikitable" border="1"
! colspan="3" | Car_type ▶
|-
! style="width:75px;" |'''VW '''
! style="width:75px;" |'''Honda '''
! style="width:75px;" |'''BMW '''
|-
| 3098
| 3897
| 3409
|}

==SubIndex(a, u, i)==
Does a lookup (similar to VLookup and Hlookup in Excel) returning the value of index «i» of array «a» for which «a» equals «u» -- in other words, it returns the value <code>vi</code> of index «i» for which array «a»[«i» = <code>vi] =</code> «u». If «a» contains multiple values equal to «u», it returns the last value of «i» that matches. If no value of «a» equals «u», it returns [[Null]]. If «a» has index(es) in addition to «i», or if «u» is an array with other indexes, those indexes also appear in the result. See also [[SubIndex]]().

'''Library:''' Array

'''Examples:'''
:<code>SubIndex(Car_prices, 18K, Car_type) →</code>
:{| class="wikitable" border="1"
! colspan="5"| Years ▶
|-
! style="width:75px;" |'''2005 '''
! style="width:75px;" |'''2006 '''
! style="width:75px;" |'''2007 '''
! style="width:75px;" |'''2008 '''
! style="width:75px;" |'''2009 '''
|-
| Honda
| «null»
| Honda
| «null»
| «null»
|}

:<code>SubIndex(Car_prices, 18K, Years) →</code>
:{| class="wikitable" border="1"
! colspan="3" | Car_type ▶
|-
! style="width:75px;" |'''VW '''
! style="width:75px;" |'''Honda '''
! style="width:75px;" |'''BMW '''
|-
| 2007
| 2005
| «null»
|}

If «u» is an array of values, an array of index values is returned.

:<code>SubIndex(Car_prices, [18K, 19K] Car_type) →</code>
:{| class="wikitable"
!
! colspan="5" |Years ▶
|-
!Subindex ▼
!2005
!2006
!2007
!2008
!2009
|-
|'''18K'''
|Honda
|«null»
|VW
|«null»
|«null»
|-
|'''19K'''
|«null»
|Honda
|«null»
|VW
|«null»
|}

==PositionInIndex(a, x, i)==
Returns the position <code>n</code> in index «i» for which x[@i = <code>n</code>] = x — that is, a number from 1 to the size of index «i» — of the last element of array «a» equal to «x». If no element of «a» matches «x», it returns 0. See also [[PositionInIndex]]().

'''Example:'''

:<code>Index I := ['A', 'B', 'C']</code>
:<code>Variable A := Array(I, [1, 2, 2])</code>
:<code>PositionInIndex(A, 1, I) → 1</code>
:<code>PositionInIndex(A, 2, I) → 3</code>
:<code>PositionInIndex(A, 5, I) → 0</code>

<tip title="Tip">[[PositionInIndex]]() is the positional equivalent of [[Subindex]](). It is useful when «i» contains duplicate values, in which case [[Subindex]]() would return an ambiguous result.</Tip>

<tip title="Tip">Parameter a is optional. When omitted, it returns the position of x in the index i, or 0 if not found. The syntax <code>@[i = x]</code> (see [[Subscript and slice of a subarray#@: Index Position Operator|@: Index Position Operator]]) returns the same result as <code>PositionInIndex(, x, i)</code>:

:<code>PositionInIndex(, 'B', I) → 2</code>
:<code>@[I = 'B'] → 2</code>
:<code>PositionInIndex(, 'D', I) → 0</code>
:<code>@[I = 'D'] → 0</code>
</Tip>

When the array is multidimensional:
Taking the same example from above:

:<code>PositionInIndex(Car_prices, 18K, Car_type) →</code>
:{| class="wikitable" border="1"
! colspan="5"| Years ▶
|-
! style="width:75px;" |'''2005 '''
! style="width:75px;" |'''2006 '''
! style="width:75px;" |'''2007 '''
! style="width:75px;" |'''2008 '''
! style="width:75px;" |'''2009 '''
|-
| 2
| 0
| 1
| 0
| 0
|}

==Area(y, x, ''x1, x2, i'')==
Returns the area (sum of trapezoids) under the piecewise-linear curve denoted by the points
(«xi», «yi»), landing in the region «x1» ≤ «x» ≤ «x2». The arrays «x» and «y» must share the common index «i», or when either «x» or «y» is itself an index, «i» can be safely omitted. «x» and «x2» are optional; if they are not specified, the area is calculated across all values of «x».

If «x1» or «x2» fall outside the range of values in «i», the first value (for «x1») or last value (for «x1») are used. [[Area]]() computes the total integral across «x», returning a value with one less dimension than «y». Compare [[Area]]() to [[Transforming functions#Integrate()|Integrate()]].

'''Library:''' Array

'''Example'''
:<code>Area(Cost_of_ownership, Time, 0, 2) →</code>
:{| class="wikitable" border="1"
! colspan="3" | Car_type ▶
|-
! style="width:75px;" |'''VW '''
! style="width:75px;" |'''Honda '''
! style="width:75px;" |'''BMW '''
|-
| 5905
| 7563
| 6591
|}

==See Also==
<div style="column-count:2;-moz-column-count:2;-webkit-column-count:2">
* [[Tutorial: Arrays#Array_Reducing_Functions|Tutorial: Array Reducing Functions]]
* [[:Category:Array-reducing functions]]
* [[Tutorial: Arrays#Reducing_an_array_using_subscripts|Tutorial: Reducing an array using subscripts]]
* [[Sum]]()
* [[Product]]()
* [[Average]]()
* [[Functions Min and Max]]
* [[Max]]()
* [[Min]]()
* [[ArgMax]]()
* [[ArgMin]]()
* [[CondMin]]()
* [[CondMax]]()
* [[SubIndex]]()
* [[PositionInIndex]]()
* [[Area]]()
* [[Function calls and parameters]]
* [[Multidimensional array]]
* [[Relational tables and multiD arrays]]
* [[Repeated Parameter Forwarding|Reducing over all indexes]]
</div>

<footer>Functions that create arrays / {{PAGENAME}} / Transforming functions</footer>

Array-reducing functions

2024-11-23T19:19:05Z

Max:

[[Category:Analytica User Guide]]
[[Category: Array-reducing functions]]
<breadcrumbs>Analytica User Guide > Array functions > {{PAGENAME}}</breadcrumbs>

__TOC__

An '''array-reducing function''' aggregates across an Index (dimension) of an array and returns a result without that Index. So reduces the number of dimensions of that array by one (or more). Examples include, [[Sum]](x, i), [[Product]](x, i), [[Max]](x, i), [[Min]](x, i), and others described below. The [[Subscript and slice of a subarray |subscript]] construct [[Subscript-Slice_Operator|x[i = v]]] and related slice functions also reduce arrays by a dimension.

The function [[Sum]](x, i) illustrates some properties of reducing functions.

'''Examples'''

:<code>Sum(Car_prices, Car_type) →</code>
:{| class="wikitable" border="1"
! colspan="5" | Years ▶
|-
! style="width:75px;" |'''2005 '''
! style="width:75px;" |'''2006 '''
! style="width:75px;" |'''2007 '''
! style="width:75px;" |'''2008 '''
! style="width:75px;" |'''2009 '''
|-
| 59K
| 62K
| 66K
| 71K
| 76K
|}

:<code>Sum(Car_prices, Years) →</code>
:{| class="wikitable" border="1"
! colspan="3" | Car_type ▶
|-
! style="width:75px;" |'''VW '''
! style="width:75px;" |'''Honda '''
! style="width:75px;" |'''BMW '''
|-
| 99K
| 103K
| 141K
|}

:<code>Sum(Sum(Car_prices, Years), Car_type) → 334K</code>

''See [[Array Function Example Variables]] for example array variables used here and below.''

<tip title="Tip">The second parameter, «i», specifying the dimension over which to sum, is optional. But if the array, «x», has more than one dimension, Analytica might not sum over the dimension you expect. For this reason, it is safer always to specify the dimension index explicitly in [[Sum]]() or any other array-reducing function.</Tip>

'''Reducing over an unused index:''' If the index, «i», is not a dimension of «x», [[Sum]](x, i) returns «x» unreduced (i.e., with the same number of indexes), but multiplied by the size (number of elements) of «i». The reason is that if «x» is not indexed by «i», it means that it has the same value for all values of «i». This is true even if «x» is an atom with no dimensions:

:<code>Variable x := 5</code>
:<code>Sum(x, Car_type) → 15</code>

This is because <code>Car_type</code> has three elements (3 x 5 = 15).

In this way, if we later decide to change the value for <code>x</code> for each value of <code>Car_type</code>, we can redefine «x» as an edit table indexed by <code>Car_type</code>. Any expression containing a [[Sum]]() or other reducing function on «x» works correctly whether it is indexed by <code>Car_type</code> or not.

'''Elements that are ignored:''' These array-reducing functions ignore elements of an array that contain [[Null]]. For example, the [[Average]](x, i) function sums all the non-null elements of «x» and divides by the number of non-null elements.

'''IgnoreNaN''': When a '''NaN''' value (an indeterminate number) appears as an element of an array, the result of a function that operates on the array is usually '''NaN''' as well. '''NaN''' values result from indeterminate operations such as <code>0/0</code>. They propagate forward in this fashion to ensure that you will not accidentally compute an indeterminate result without realizing it. However, in some cases you might wish to ignore '''NaN''' values in an array-reducing operation. The functions [[Sum]], [[Product]], [[Average]], [[Min]], and [[Max]] all accept an optional parameter, «ignoreNaN» that can be set to True. «IgnoreNan» requires a named-parameter syntax, for example:

:<code>Max(x, i, ignoreNaN: True)</code>

'''ignoreNonNumbers''': When the parameter contains both text and numbers, you can instruct [[Sum]], [[Min]] and [[Max]] to ignore the non-numeric values using the optional «ignoreNonNumbers» parameter, for example:

:<code>Max(x, i, ignoreNonNumbers: True)</code>

'''Reduce over multiple indexes:''' Most array-reducing functions, including [[Sum]], [[Product]], [[Average]], [[Min]], [[Max]], [[ArgMin]], and [[ArgMax]], let you specify more than one index. This is a convenient way to reduce over multiple indexes in a single call, for example:

:Sum(x, i, j, k)

This is equivalent to:
:Sum(Sum(Sum(x, i), j), k)

'''Reduce over all indexes''': You can sum over ''all'' the indexes of an array without having to list them explicitly:
:Sum(x, ... IndexesOf(x))
This necessarily returns a scalar -- i.e. value with no index. See [[Repeated Parameter Forwarding]] for details.

Below we describe the most common array-reducing functions.

==Sum(x, ''i'')==
Returns the sum of array «x» over the dimension indexed by «i».

'''Library:''' Array

'''Examples:'''

:<code>Sum(Car_prices, Years) →</code>

:{| class="wikitable" border="1"
! colspan="3" | Car_type ▶
|-
! style="width:75px;" |'''VW '''
! style="width:75px;" |'''Honda '''
! style="width:75px;" |'''BMW '''
|-
| 99K
| 103K
| 141K
|}

''See [[Array Function Example Variables]] for example array variables used here and below.''

==Product(x,''i'')==
Returns the product of all of the elements of «x», along the dimension indexed by «i». See also [[Product]]().

'''Library:''' Array

'''Examples:'''

:<code>Product(Car_prices, Car_type) →</code>
:{| class="wikitable" border="1"
! colspan="5" | Years ▶
|-
! style="width:75px;" |'''2005 '''
! style="width:75px;" |'''2006 '''
! style="width:75px;" |'''2007 '''
! style="width:75px;" |'''2008 '''
! style="width:75px;" |'''2009 '''
|-
| 7.2T
| 8.398T
| 10.08Y
| 12.54T
| 15.36T
|}

==Average(x, ''i'')==
Returns the mean value of all of the elements of array «x», averaged over index «i». See also [[Average]]().

'''Library:''' Array

'''Examples:'''

:<code>Average(Miles, Years)→</code>
:{| class="wikitable" border="1"
! colspan="3" | Car_type ▶
|-
! style="width:75px;" |'''VW '''
! style="width:75px;" |'''Honda '''
! style="width:75px;" |'''BMW '''
|-
| 8000
| 12K
| 7600
|}

==Max(x, i)==
Returns the highest valued element of «x» along index «i». See also [[Max]]().

'''Library:''' Array

'''Examples:'''

:<code>Max(Miles, Years) →</code>
:{| class="wikitable" border="1"
! colspan="3" | Car_type ▶
|-
! style="width:75px;" |'''VW '''
! style="width:75px;" |'''Honda '''
! style="width:75px;" |'''BMW '''
|-
| 10K
| 12K
| 10K
|}

To obtain the maximum of two numbers, first turn them into an array:

:<code>Max([10, 5]) → 10</code>

''See [[Array Function Example Variables]] for example array variables used here and below.''

==Min(x, ''i'')==
Returns the lowest valued element of «x» along index «i». See also [[Min]]().

'''Library:''' Array

'''Examples:'''

:<code>Min(Miles, Years) →</code>
:{| class="wikitable" border="1"
! colspan="3" | Car_type ▶
|-
! style="width:75px;" |'''VW '''
! style="width:75px;" |'''Honda '''
! style="width:75px;" |'''BMW '''
|-
| 6000
| 10K
| 5000
|}

To obtain the minimum of two numbers, first turn them into an array:

:<code>Min([10, 5]) → 5</code>

==ArgMax(a, i)==
Returns the item of index «i» for which array «a» is the maximum. If «a» has more than one value equal to the maximum, it returns the index of the last one. See also [[ArgMax]]().

'''Library:''' Array

'''Example:'''
:<code>ArgMax(Miles, Car_type) →</code>
:{| class="wikitable" border="1"
! colspan="5" | Years ▶
|-
! style="width:75px;" |'''2005 '''
! style="width:75px;" |'''2006 '''
! style="width:75px;" |'''2007 '''
! style="width:75px;" |'''2008 '''
! style="width:75px;" |'''2009 '''
|-
| Honda
| Honda
| Honda
| Honda
| Honda
|}

==ArgMin(a, i)==
Returns the corresponding value in index «i» for which array «a» is the minimum. If more than one value equals the minimum, returns the index of the last occurrence. See also [[ArgMin]]().

'''Library:''' Array

'''Example:'''
:<code>ArgMin(Car_prices, Car_type) →</code>
:{| class="wikitable" border="1"
! colspan="5" style="text-align: left;" | Years ▶
|-
! style="width:75px;" |'''2005 '''
! style="width:75px;" |'''2006 '''
! style="width:75px;" |'''2007 '''
! style="width:75px;" |'''2008 '''
! style="width:75px;" |'''2009 '''
|-
| BMW
| VW
| BMW
| VW
| VW
|}

==CondMin(x, cond, i) and CondMax(x, cond, i)==
[[CondMin]]() "conditional min" returns the smallest value along a given index, «i», that satisfies condition «cond».
Similarly, [[CondMax]]() returns the largest When «cond» is never satisfied, [[CondMin]]() returns [[INF]] and [[CondMax]]() returns <code>-INF</code>.

'''Library:''' none

'''Examples:'''
:<code>CondMin(Cost_of_ownership, Time >= 2, Time) →</code>
:{| class="wikitable" border="1"
! colspan="3" | Car_type ▶
|-
! style="width:75px;" |'''VW '''
! style="width:75px;" |'''Honda '''
! style="width:75px;" |'''BMW '''
|-
| 3098
| 3897
| 3409
|}

==SubIndex(a, u, i)==
Does a lookup (similar to VLookup and Hlookup in Excel) returning the value of index «i» of array «a» for which «a» equals «u» -- in other words, it returns the value <code>vi</code> of index «i» for which array «a»[«i» = <code>vi] =</code> «u». If «a» contains multiple values equal to «u», it returns the last value of «i» that matches. If no value of «a» equals «u», it returns [[Null]]. If «a» has index(es) in addition to «i», or if «u» is an array with other indexes, those indexes also appear in the result. See also [[SubIndex]]().

'''Library:''' Array

'''Examples:'''
:<code>SubIndex(Car_prices, 18K, Car_type) →</code>
:{| class="wikitable" border="1"
! colspan="5"| Years ▶
|-
! style="width:75px;" |'''2005 '''
! style="width:75px;" |'''2006 '''
! style="width:75px;" |'''2007 '''
! style="width:75px;" |'''2008 '''
! style="width:75px;" |'''2009 '''
|-
| Honda
| «null»
| Honda
| «null»
| «null»
|}

:<code>SubIndex(Car_prices, 18K, Years) →</code>
:{| class="wikitable" border="1"
! colspan="3" | Car_type ▶
|-
! style="width:75px;" |'''VW '''
! style="width:75px;" |'''Honda '''
! style="width:75px;" |'''BMW '''
|-
| 2007
| 2005
| «null»
|}

If «u» is an array of values, an array of index values is returned.

:<code>SubIndex(Car_prices, [18K, 19K] Car_type) →</code>
:{| class="wikitable"
!
! colspan="5" |Years ▶
|-
!Subindex ▼
!2005
!2006
!2007
!2008
!2009
|-
|'''18K'''
|Honda
|«null»
|VW
|«null»
|«null»
|-
|'''19K'''
|«null»
|Honda
|«null»
|VW
|«null»
|}

==PositionInIndex(a, x, i)==
Returns the position <code>n</code> in index «i» for which x[@i = <code>n</code>] = x — that is, a number from 1 to the size of index «i» — of the last element of array «a» equal to «x». If no element of «a» matches «x», it returns 0. See also [[PositionInIndex]]().

'''Example:'''

:<code>Index I := ['A', 'B', 'C']</code>
:<code>Variable A := Array(I, [1, 2, 2])</code>
:<code>PositionInIndex(A, 1, I) → 1</code>
:<code>PositionInIndex(A, 2, I) → 3</code>
:<code>PositionInIndex(A, 5, I) → 0</code>

<tip title="Tip">[[PositionInIndex]]() is the positional equivalent of [[Subindex]](). It is useful when «i» contains duplicate values, in which case [[Subindex]]() would return an ambiguous result.</Tip>

<tip title="Tip">Parameter a is optional. When omitted, it returns the position of x in the index i, or 0 if not found. The syntax <code>@[i = x]</code> (see [[Subscript and slice of a subarray#@: Index Position Operator|@: Index Position Operator]]) returns the same result as <code>PositionInIndex(, x, i)</code>:

:<code>PositionInIndex(, 'B', I) → 2</code>
:<code>@[I = 'B'] → 2</code>
:<code>PositionInIndex(, 'D', I) → 0</code>
:<code>@[I = 'D'] → 0</code>
</Tip>

When the array is multidimensional:
Taking the same example from above:

:<code>PositionInIndex(Car_prices, 18K, Car_type) →</code>
:{| class="wikitable" border="1"
! colspan="5"| Years ▶
|-
! style="width:75px;" |'''2005 '''
! style="width:75px;" |'''2006 '''
! style="width:75px;" |'''2007 '''
! style="width:75px;" |'''2008 '''
! style="width:75px;" |'''2009 '''
|-
| 2
| 0
| 1
| 0
| 0
|}

==Area(y, x, ''x1, x2, i'')==
Returns the area (sum of trapezoids) under the piecewise-linear curve denoted by the points
(«xi», «yi»), landing in the region «x1» ≤ «x» ≤ «x2». The arrays «x» and «y» must share the common index «i», or when either «x» or «y» is itself an index, «i» can be safely omitted. «x» and «x2» are optional; if they are not specified, the area is calculated across all values of «x».

If «x1» or «x2» fall outside the range of values in «i», the first value (for «x1») or last value (for «x1») are used. [[Area]]() computes the total integral across «x», returning a value with one less dimension than «y». Compare [[Area]]() to [[Transforming functions#Integrate()|Integrate()]].

'''Library:''' Array

'''Example'''
:<code>Area(Cost_of_ownership, Time, 0, 2) →</code>
:{| class="wikitable" border="1"
! colspan="3" | Car_type ▶
|-
! style="width:75px;" |'''VW '''
! style="width:75px;" |'''Honda '''
! style="width:75px;" |'''BMW '''
|-
| 5905
| 7563
| 6591
|}

==See Also==
<div style="column-count:2;-moz-column-count:2;-webkit-column-count:2">
* [[Tutorial: Arrays#Array_Reducing_Functions|Tutorial: Array Reducing Functions]]
* [[:Category:Array-reducing functions]]
* [[Tutorial: Arrays#Reducing_an_array_using_subscripts|Tutorial: Reducing an array using subscripts]]
* [[Sum]]()
* [[Product]]()
* [[Average]]()
* [[Functions Min and Max]]
* [[Max]]()
* [[Min]]()
* [[ArgMax]]()
* [[ArgMin]]()
* [[CondMin]]()
* [[CondMax]]()
* [[SubIndex]]()
* [[PositionInIndex]]()
* [[Area]]()
* [[Function calls and parameters]]
* [[Multidimensional array]]
* [[Relational tables and multiD arrays]]
* [[Repeated Parameter Forwarding|Reducing over all indexes]]
</div>

<footer>Functions that create arrays / {{PAGENAME}} / Transforming functions</footer>

Managing windows

2024-11-22T23:45:52Z

Max:

[[Category:Analytica User Guide]]
[[Category: Windows and dialogs]]

<breadcrumbs>Analytica User Guide > Working with Large Models > {{PAGENAME}}</breadcrumbs>

You could theoretically open hundreds of [[Diagram window|Diagram]], [[Object window|Object]], and [[Result window|Result]] windows in a model. To avoid cluttering your screen, Analytica limits the number of windows that can be open at once. The default limit is 4 windows of any type. (Dialogs do not count as windows.) If you open a new window when you already have 4 open, it automatically closes the window that has been inactive the longest.

You can change this limit in the [[Preferences dialog]], which you can open from the from the [[Edit menu]] . Select a different number from the "Max open windows'' menu:
:[[File:Chapter19_19.png]]

== See Also ==
* [[Diagram window]]
* [[Object window]]
* [[Result window]]
* [[Preferences]]

<footer>Making a browse-only model and hiding definitions / {{PAGENAME}} / Memory usage and management</footer>

What's new in Analytica 5.2?

2024-11-22T03:12:16Z

Max: /* Emergent iteration constructs */

[[category:What's new pages]]


== Highlights ==

For most users, the most valuable new features are about graphing:

* '''Zoom into graphs''': Press your mouse button within a graph and drag the cursor to show a rectangle to get a close up view of that part of the graph. You can do this horizontally to zoom into part of the X axis, vertically to zoom the Y axis, or both together.

* '''Hide elements on a graph:''' Further enhances on a popular feature introduced in [[Analytica 5.1]] that gives you the option to hide some lines on a graph. Click an element in the key to toggle whether to hide or show the corresponding line. If there are many key items, and you want to show just one or a few, you can now select '''Turn off all key items''' from the right-click menu in the Key. Then you can click just those few key items you want to show.

* '''Combine symbols and lines:''' You can show some data sets as symbols and others as a continuous line in the same graph -- for example, to show a regression line fitted to data points. In '''Graph setup''' / '''Chart type''', select the second '''Line style''' which shows lines ''and'' symbols. In the Graph, you can now click each element in the Key to display line only, symbol only, both line and symbol, or neither (to hide that data) by successive clicks. To save these options for future views of the graph, select '''Save key item visibility''' from the '''right-click menu'''.
:::[[File:Graph setup dialog with Line style lines and symbols.png|200px]]

* '''Show and fill regions on a map:''' Given a series of points with longitude and latitude, you can show them as regions. You should select the longitude and latitude values as X and Y values using [[XY Comparison|XY]] plot. The '''Graph setup''' / '''Chart type''' then shows a new '''Fill type''' option, which lets you fill in each polygon with a color.

* '''OnGraphDraw attribute:''' Lets you draw points, lines, areas, and text on a graph to annotate it, for example to point out a maximum, minimum value, add labels to points, or even show points on a Google map.

* '''Multiple results from a function:''' A function can now return multiple results of different dimensions. You can assign multiple results to multiple local variables, for example:
:<code>Local (txt, filename) := ReadTextFile('Import file.txt', Dialog: True);</code>
[[ReadTextFile]] now returns the file name as its second result in addition to the actual text contents of the file as its first result. This is useful if the user may select a different file from the default on specified as first parameter. Several other built-in functions that access files also now return the file name as a second result. You can also define user defined functions to return multiple results, using this construct, usually as the last expression in its definition:
:::<code>[[MultiResult]]( v1, v2, v3)</code>

* '''Extended syntax for locals and assignment:''' As shown above, you can declare multiple local variables at once. You can also assign to multiple local variables outside a declaration:
:::<code>(txt, filename) := ReadTextFile('Import file.txt', Dialog: True);</code>
You can declare multiple locals together as:
:::<code>Local x := 1, y := 2, z := 3;</code>

See below for more on these and other new features.

___TOC___

== Graphing ==

=== Interactive zooming ===

When you first show a result as a graph, it automatically set the ranges for the vertical and horizontal axes so that all data points are visible (ignoring values containing [[INF, NAN, and NULL - Exception values|INF, NAN, or Null]]). Now, you can zoom in to show just part of the graph by dragging the cursor. Drag the cursor horizontally from a low to high value to zoom in along the horizontal axis. Drag it vertically to zoom along the vertical axis. Drag it diagonally to create a rectangle to zoom in on both axes. It records the zoomed min and max values in the Axis ranges tab of Graph setup as if you had set them manually.

* Drag the mouse horizontally to zoom to a manually-scaled x-axis interval:
::[[image:graph_zoom_horiz.png]] → [[image:graph_zoom_horiz_after.png]]
::Transparent blue selection rectangle appears while dragging. After drag, Y is still autoscaled, but now to the data in the selected range.
* Drag the mouse diagonally to zoom to manually-scaled intervals on both axes:
::[[image:graph_zoom_diag.png]] → [[image:graph_zoom_diag_after.png]]
* When you move the mouse over a zoomed graph, autoscale hover icon buttons appear. Click on one to auto-scale that axis.
::[[image:graph_zoom_autoscale.png]] → [[image:graph_zoom_autoscaley_after.png]]
::Clicked on the vertical axis autoscale hover icon. Horizontal axis is still manually scaled.
* Drag vertically to zoom to a manually-scaled y-axis interval.
::[[image:graph_zoom_vert.png]] → [[image:graph_zoom_vert_after.png]]
* Zooming has the same effect as changing the manual scale range in Graph Setup. In fact, it records your selected end points there.
::[[image:graph_zoom_graphsetup_after.png]]

=== Key item visibility states ===

Analytica 5.2 further enhances the popular feature (introduced in [[Analytica 5.1]]) that lets you click on each item in Graph Key to show or hide the corresponding line or bar. See [[Toggling Key Item Visibility]].

==== Turn on all, Turn off all ====

Right-click on a graph Key to see menu options '''Turn on all key items''' and '''Turn off all key items'''. Use these when you want to show or hide almost all of them. They save you many clicks when there are a lot of key items.

==== Show lines and symbols ====

You can now show a graph with some data as symbols only, some as lines without symbols, and some lines and symbols. This is very useful when you want to show data points and a line fitted to those points on the same graph.
::[[image:Line and point graph.png]]

To achieve this, select the Line+Symbol plot style:
:[[image:How to line and point graph.png]]
Initially, every data series (key item) has lines and symbols (as before). Click on each Key item to toggle it from line+symbol to line-only to symbol-only, and back to line+symbol. So with just a few clicks, you can select how to display each each series.

What if your graph has multiple keys, line and symbol or symbol size each depicting different information? You can then toggle each element on each key separately through three states: On to Off to Partial, and back to On. In the Off state, it hides both lines and symbols. In the Partial state on the Line key, it hides the line but shows the symbols. Or in the Symbol Key, when an item is Partial, it shows the line but not the symbol.

::[[image:graph_key_symbol_partial.png]]

In the above graph, the 2 points corresponding to '''Least''' would appear at x=2 in the fully-on graph, but fit_err=Least is been clicked once, putting it into the off state. As a result, there is a gap in the lines at x=2. In the symbol size key (x cat), the x_cat=8 item is in the partial state. The points corresponding to x_cat=8 appear at x=8. In this case the lines pass through the points, but the symbols are hidden.

When fit_graph=y in the line key is off, all the red "ink" on the graph disappears. But when it is in the partial state, the line disappears but the symbols continue to show, as illustrated here:
::[[image:graph_key_line_partial.png]]

==== Save visibility states ====
Changes to key item visibility reset by default when you close and re-open a graph anew. If you want your current visibility state to be saved as the starting point next time the graph is opened, select '''Save key item visibilities''' from the right-mouse menu.

=== Polygon fill plots ===
When you plot a curve in an X-Y plot, there is now a polygon fill option that fills the interior of the polygon(s). For example, starting with this data, already plotted as Latitude vs Longitude
::[[image:California_unfilled_plot.png]]
you can use the new Polygon fill type (the Fill type option is new).
::[[image:Graph_setup_polygon_filltype.png]]
The difference between alternate and solid arises when a curve crosses itself. In this example with a state outline, that doesn't happen so they are equivalent. Polygon fill closes each curve segment (null data starts a new segment) and fills the interior.
::[[image:California_filled_plot.png]]
and viola!
::[[image:Red state blue state.png]]

=== OnGraphDraw ===
You can use the [[OnGraphDraw]] attribute to adorn or customize your graphs in various ways. You can enter an expression that gets evaluated at any of 4 phases during the graph rendering. A [[Canvas]] is provided that you can draw on using the [[Drawing images|canvas drawing functions]].

==== Examples ====
Using [[OnGraphDraw]], by drawing on the canvas ''after'' the graph has been rendered, you you can annotate points on a plot such as the maximum or minimum, label a threshold level, draw error bars or labels for individual points.
<center>[[image:OnGraphDraw min and max.png]]
[[image:OnGraphDraw threshold.png|400px]]
[[image:OnGraphDraw_ErrorBars.png|400px]]
</center>

By drawing ''after'' the axes have been scaled, but before the data has been plotted, you can draw under the data, or replace the rendering of the data entirely, such as by replacing probability bands with Tukey bars that your code renders.
<center>[[image:OnGraphDraw_TukeyBands.png|400px]]</center>

You can also draw a Google map under the data (Analytica Enterprise is required to support the functions necessary for downloading a Google map).
<center>[[image:OnGraphDraw map.png]]</center>
The Google map also requires running the [[OnGraphDraw]] after the graph is laid out, but before the axes are drawn, at which opportunity it can register the actual latitute/longitude axis scale to match the downloaded map.

Finally, you can draw ''before'' anything has been drawn to completely replace the graph with a totally customized data depiction, such as a pie chart, dendritic tree, etc.

==== Using OnGraphDraw ====
* To use OnGraphDraw, go to the [[Attributes dialog]] and enable it for Variables. It appears there now.
* On the [[Object window]] for the variable on interest, the [[OnGraphDraw]] attribute appears, along with a series of check box where you can select which phases of drawing you want your code called.
* Several local variables are provided to [[OnGraphDraw]]: <code>canv</code>, <code>info</code>, <code>roles</code>, <code>phase</code>, <code>continue</code>, and <code>roleChanges</code>. These supply the canvas, information about the graph itself and its layout, the pivot (roles) of the graph, and which phase of rendering is being processed. You can set <code>continue</code> to tell it not to draw further, or set <code>roleChanges</code> to make actual changes (like when registering actual latitude bounds of a Google map).
* The new [[GraphToCanvasCoord]] function makes it easy to find the pixel location for a data point, based on the data's own units.

See [[OnGraphDraw]] for instructions on how to use this.

Specific adornments or novel plot types can be encapsulated as [[User-Defined Functions]] and bundled in libraries, so that with these you need only add a function call in [[OnGraphDraw]] and check the appropriate phase check boxes. We have not released any such library yet, but may post libraries like this on the Analytica Wiki and Analytica blog in the future, so stay tuned.

=== Other graphing ===

* Bug fix impacting marginal abatement graphs
* Changing symbol size role less likely to swap other roles, less confusing

== Expression language & Engine ==

=== Declaring local identifiers ===

==== Omission of initial value====

When declaring a local, you can now omit its initial value, so that
:<code>[[Local]] x;</code>
is equivalent to
:<code>[[Local]] x := Null</code>;

==== Multiple locals in one declaration ====

You can declare multiple local identifiers in the same Local declaration. For example,
:<code>Local a, b := 5, c[ J ], d[ ] := Va1;</code>
This is then equivalent to four separate declarations as follows
<code>
:[[Local]] a:=[[Null]];
:[[Local]] b:=5;
:[[Local]] c[ J ] := [[Null]];
:[[Local]] d[ ] := Va1;
</code>

==== Capture of multiple return values ====

Functions can now return multiple values, each with different dimensionality. This is covered below in [[#Multiple return values]]. These values can be captured by [[Local]] (or the other declaration constructs like [[For]], etc.) by placing the declared identifiers inside parentheses, as illustrated here:

:<code>[[Local]] (u,w,v) := [[SingularValueDecomp]]( a, I, J, J2 );</code>

where the function, [[SingularValueDecomp]] returns three matrices, each with a different dimensionality. With dimensional restrictions, this could also be declared as

:<code>[[Local]] (u[I,J], w[J,J2], v[J,J2]) := [[SingularValueDecomp]]( a, I, J, J2 );</code>

Note that [[SingularValueDecomp]] is called a single time, and returns three separate values. This function, as well as [[EigenDecomp]], behave differently when multiple return values are captured compared to when only the main value is used, which is done for backward compatibility with their legacy behavior. Previously, the returned a data structure with 3 [[references]] to the 3 matricies, which required some work to unpack. They illustrate that the capability to return multiple values isn't entirely new, but is far more convenient. These two functions are the only functions that change their behavior. For all other functions, when only the main value is used, the secondary return values are simply dropped (and are usually not computed in the first place). For example, in addition to reading the contents of a file, you can also capture the file name selected by the user using

:<code>[[Local]] ( txt, filename ) := [[ReadTextFile]]("");</code>

but you don't need to capture filename if you don't need it, and can simple use

:<code>[[Local]] txt := [[ReadTextFile]]("");</code>

==== Reduced keyword ====

As with previous releases, you can declare the indexes that the value named by a local identifier is allowed to have using brackets, such as
:<code>[[Local]] x[I, J, K] := Z;</code>
When declared in this fashion, and expressions you include in the body (i.e., the lexical scope of these local identifiers) can be treated as if it does not contain any indexes not listed. The new keyword "<code>reduced</code>" also restricts the dimensionality of a local variable, but in a somewhat different way. The same qualifier exists for [[Function parameter qualifiers|function parameter declarations]] and in fact works in exactly the same way here.

:<code>[[Local]] ( a[ ], b reduced ) := _( X, Y );</code>

Since <code>a</code> might need to be iterated over the indexes of <code>X</code>, <code>b</code> will have the indexes of <code>Y</code> that are not also indexes of <code>X</code>. In addition, the slice of X or Y named by a or b is coordinated. When a names <code>X[J=3]</code>, then <code>b</code> also names <code>Y[J=3]</code>. This leads to some convenient new iteration constructs. For example, you may have seen expressions such as this one:

<code>
:[[For]] n := @I Do (
::[[Local]] ii := I[@I=n]
::[[Local]] x_i := X[@I=n];
::…
</code>

the ensuing looped body code makes use of the index position (n), the index label (ii), and the array slice (x_i), and so it has to extract two of the items from the loop variable. This can now be condensed to a single looping structure,

<code>
:[[For]] (n[], ii[], x_i reduced) := _(@I, I, X) Do ( …
</code>
Note: In many cases, the word [[Local]] can be used in place of [[For]] here. Note that <code>n</code> names each position of <code>I</code>, <code>ii</code> names each label of <code>I</code>, and <code>x_i</code> names the slice of <code>X</code> corresponding to <code>[@I=n]</code>. This is similar to calling a function with <code>F(@I, I, X)</code> with has Parameters declared as
:Function F(n,i : [] ; x_i : reduced)

==== Iterating over repeated parameters (Local xi := repeated x Do) ====

When a [[User-Defined Function]] has a repeated parameter, for example when its [[Parameters]] are:
:<code>( x : ... )</code>
or equivalently
:<code>(x : repeated)</code>

the "correct" way to iterate over the supplied parameters in the Definition of the UDF is now
:<code>[[Local]] xi := repeated x;</code>

The <code>repeated</code> keyword at this position is recognized. So for example, if someone calls this function as
:<code>F(a,b,c)</code>
where <code>a</code>, <code>b</code> and <code>c</code> each have different dimensions, <code>xi</code> will alias each of these values in turn. A couple syntactic variations are to use [[For]] in place of [[Local]], or to include parens around the name, e.g.,
:<code>[[For]] xi := repeated(x) Do ...</code>

As before, you can also access these using, e.g., Slice(x,2) for the second repeated. It is best, however, not to treat the repeated "dimension" as you would the implicit dimension, otherwise you may end up with the union of the incoming dimensions.

==== Preservation of local name instead of local1, local2 ====

Prior to this release, the parse tree (an internal data structure) for an Analytica expression did not remember the local identifier. Instead, it numbered the locals, and so every once in a while you might encounter a situation where the identify of the local is extracted from the parse tree and appears as <code>local1</code>, <code>local2</code>, etc. Analytica 5.2 now annotates the parse tree with the local identifier, so that depictions of the parse use the original names. For example, suppose <code>Va1</code> is defined as

[[Local]] x := [[Sin]](angle);
[[Local]] y := [[Cos]](angle);
[x,y]

You can see the difference here:
{|border="0"
|[[Image:LocalIdentsIn5.1.png]] || [[Image:LocalIdentsIn5.2.png]]
|-
! <center>In Analytica 5.1</center> !! <center>In Analytica 5.2</center>
|}

=== Multiple return values ===

Functions can now return multiple values, each with potentially different indexes, not just a single value or array, as previously. An expression calling the function may use only the first returned value, or it can use some or all of the values. Several built-in functions return extra information in the second and third return values.

==== Built-in functions that return multiple values ====

These built-in functions read information from a file and return its contents in one way or other in the main value. Each has now been enhanced to return the file name that was opened as a second parameter. Since in each case, a user might potentially select a file from a file selector dialog, you would otherwise not knowing which file was actually read. The primary return value is the same as in previous releases, the second return value is new.

* [[ReadTextFile]]: Returns ( file_contents, filename )
* [[SpreadsheetOpen]]: Returns ( workbook, filename )
* [[ReadExportFile]]: Returns ( array, filename )
* [[ReadBinaryFile]]: Returns (date, filename)
* [[ReadImageFile]]: Returns (image, filename)

Note: the Write functions don't yet return filenames in this fashion.

* [[CanvasDrawText]] returns the coordinates of the bounding box of the text.
* [[Regression]] will return the bias coefficient as a second return value without having it included in the basis.
* [[MantissaAndExponent]] returns the mantissa and exponents as separate return values.
* [[MsgBox]] returns the check box state as a second return value.

The function [[SingularValueDecomp]] computes three matrices, each with a different dimensionality. Formerly, these were returned as a vector of 3 [[reference]]s. You would then usually unpack this, extracting the three items. With the ability for it to return three return values, the call is more convenient, namely:

:<code>(u, w, v) := [[SingularValueDecomp]]( a, I, J, J2)</code>

eliminating the ugly unpacking code. To ensure backward compatibility with code that used the 3-reference data structure, it is able to detect when you are capturing multiple return values and return the 3-reference structure when you are not.

A similar enhancement applies to the [[EigenDecomp]] function, which returns a vector of eigen values and 2-D matrix of eigen vectors. Formerly, these were bundled using a reference for the eigen vectors, but with multiple return values it is convenient to immediately separate these, e.g.,

:<code>(eigenVals, eigenVecs) := [[EigenDecomp]](a, I, J)</code>

[[EigenDecomp]] also retains its legacy behavior when you are not capturing multiple return values.

The [[Regression]] function automatically adds a bias term to the basis and return the bias coefficient as the second return value when you capture the second return value. This means you can now find <code>m</code> and <code>b</code> for simple y=m*x+b regression for scalar x using just
:<code>[[Local]] (m,b) := [[Regression]](y, x, I);</code>

You can include a checkbox on a message box displayed by [[MsgBox]](). When you do so, the state of the checkbox is returned as a second return value.

==== Capturing multiple return values ====
When a function returns multiple return values, you have to capture these values. There are two ways of doing this: In a local declaration, or via the assignment operator (:=).

:<code>[[Local]]( x, y, z ) := FuncWithMultiple( );</code>
or
:<code>(a, b, c) := FuncWithMultiple( );</code>

When assignment is used, each destination (a, b and c) can be anything that could appear on the left-hand side of an normal assignment operator. This includes local identifiers, global variables (in contexts where a side-effect is legal), a slice of a local variable, an attribute of an object, etc.

Although I'm showing the local declaration example using [[Local..Do]], you can also use other local declaration constructs in the same way, including [[For]] and [[LocalAlias]], or the legacy [[Var..Do]], [[Using..Do]], [[MetaVar..Do]], etc.

When you capture a return value that isn't actually returned by the function, it is equivalent to capturing null. For example:
:<code>( x,y ) := [[Sqrt]](5)</code>
sets <code>x</code> to 5 and <code>y</code> to null.

==== Returning multiple values from a UDF ====
To return multiple values from your own UDFs, simple return
:<code>[[MultiResult]]( v1, v2, v3, v4 )</code>
where <code>v1, v2, …</code> are the expressions whose result is to be returned. Be aware that for any of these values that are not captured by the caller, the corresponding expression will not be evaluated. You can use that to your advantage by placing any time-consuming code not shared by v1 in the expression for v2, so that when the caller uses only v1, no wasted computation ensues.

There is a synonymous syntax, <code>_( v1, v2, v3, v4 )</code> that can be used. When returning values from a UDF, we feel that it clearer to call [[MultiResult]]. However, the underscore function is convenient when using a multiple assignment directly, such as

:<code>[[Local]] (key[], val[]) := _( dict.Key, dict );</code>

This example combines <code>_( ) </code> with [[Repeated parameter forwarding]] to accomplish something that would have taken four lines of code otherwise.
:<code>[[Local]] (x,y,z) := _( ...[[ParseNumber]]( [[SplitText]]( "10, 20, 3", "," ) ) );</code>

==== Emergent iteration constructs ====

Some new convenient forms of iteration constructs emerge from the introduction of multiple return values. For example, when iterating over an index, you can simultaneously grab the index position and the index labels in the loop declaration.
<code>
:[[For]] ( pos, label ) := _( @J, J ) Do …
</code>
A 1-D array with an index containing labels is called as associative array in other programming languages. The index values are the keys and the array values are the values. Your iteration can conveniently name both the current key and the current value.
<code>
:[[For]] ( key[], val reduced ) := _( I, a ) Do …
</code>

=== Assignment ===
* (Definition of X := array) -- setting cell expressions
* new ParseExpression() function
* Capturing multiple values
=== Multithreading ===
Added finer-grained control over which multi-threaded algorithms are enabled or disabled. This is so that if you encounter a multi-threading-related problem with one particular algorithm, you can disable it without having to sacrifice all multi-threading.

* [[DisableMultithreaded]]: New system variable that contains the flags.
* [[SetEvaluationFlag]]('multithreaded'): Function for turning on or off only within one expression.

=== Experimental ===
You should not rely on experimental features while they are still experimental. They are subject to change or even cancellation in future releases, and are less thoroughly tested.

==== Sparse arrays ====
Analytica has long had support for a certain form of sparsity, which we call constant sparsity (or just const sparsity for short). When the values along a slice of an array don't vary (are constant), Analytica is often able to store the single value only, and also avoid an iteration during computations. However, many sparse arrays can't take advantage of const sparseness. We've been experimenting with fully sparse multi-dimensional arrays. With these, it is possible to have multidimensional cubes with large numbers of dimensions and immense numbers of distinct coordinates as long as the number of cell with actual data is relatively small. Such sparsity is often seen in [[MdTable]] relational-to-array transformations.

You can use the same Analytica operators and functions on sparse arrays as you would on any other Analytica arrays, but when possible, Analytica will attempt to use sparse algorithms to process the only values that are present and produce a sparse array, maintaining fast and low-memory computation. With this we have been able to demonstrate some real-life computations on sparse BI hypercubes that were not previously possible (and which are not realistically possible with a relational table representation).

Some operations produce non-sparse results, even when applied to sparse arrays. [[Cumulate]] applied to an array with a non-zero default value is one obvious example. This is a serious "gotcha", because if you are manipulating arrays with quadrillions of cells, one application of a function like that and you've just created a multi-petabyte array.

At present, only a subset of operations and functions that could have sparse-array-aware algorithms actually do; however, many of the ones that are present are the most common operations. But this incompleteness is one reason this is classified as an experimental feature.

In addition, the sparse algorithms are at this point quite new and not battle tested, so it not unlikely that bugs may be lurking, including bugs that might produce incorrect results. One of the reasons we are including it as an experimental feature is to promote testing of the algorithms.

===== Using sparse arrays =====
The use of sparse arrays is enabled by setting the system variable [[EnableSparse]] to 1. Or, you can enable the production of a sparse array from a specific expression by using <code>[[SetEvaluationFlag]]('sparse', true', «expr»)</code>.

[[MdTable]] is able to return a sparse array from a relational table, provided [[EnableSparse]] is set, or the sparse evaluation flag is on, or you set the optional «sparse» parameter to true. From there, the sparseness will propagate as you slice, add, and so on.

Expressions like <code>a = b</code> are often sparse, but will only return a sparse result when the evaluation context allows it. When these produce dense arrays, and those dense arrays are combined with sparse arrays, a lot of sparsity is often lost.

== Built-in functions ==
=== with Multiple return values ===
The following built-in functions now return multiple results: [[ReadTextFile]], [[ReadImageFile]], [[ReadBinaryFile]], [[SpreadsheetOpen]], [[ReadExportFile]], [[SingularValueDecomp]], [[EigenDecomp]], [[MsgBox]], [[MantissaAndExponent]], [[CanvasDrawText]] and [[Regression]].

See [[#Multiple return values]] above.

=== New optional parameters to existing functions ===
* Added an optional parameter named «initially» parameter to [[ComputedBy]]. This provides an initial value for the parent variable, and retains the value assigned by the called in the definition. (But only when the value is a simple atom). For example, if you want to remember what file a user selected, you could use:<code>
Variable filename := [[ComputedBy]](wb,"")

Variable wb :=
Local tmp;
(tmp,filename) := [[SpreadsheetOpen]](filename);
tmp</code>

* Added an optional Boolean parameter, «w1D» parameter to [[SingularValueDecomp]]. When false or omitted, it the resulting W is a square diagonal matrix. When set to true, the returned W is a vector (the diagonal).

* Added an optional «except» parameter to [[IndexesOf]], which accepts any number of index identifiers. For example, the following sums over every index of array A except for <code>I</code> and <code>J</code>.
:::<code>[[Sum]]( A, …[[IndexesOf]](A, except:I,J) )</code>

* Added a «first» parameter to [[ArgMin]], [[Argmax]], [[SubIndex]], and [[PositionInIndex]]. When omitted or false, in the event of a tie these return the ''last'' occurrence. When set to true, they return the position of the first occurrence of the tie.

::In addition, it was previously less obvious which tie was identified by [[ArgMin]] or [[Argmax]] in the multi-dimensional case. Now it is the first or last occurrence in the natural ordering of the supplied index parameters.

* The basis index, <code>K</code>, is now optional for the [[Regression]] function. This is for convenience when performing a 1-D regression over a scalar x.

* Added an optional «measureOnly» boolean parameter to [[CanvasDrawText]].

==== For sparse arrays ====
* Added an optional boolean parameter «sparse» to [[MdTable]]. Experimental. See [[#Sparse arrays]].
* The optional Boolean «sparseCount» parameter to [[Size]]. When true, counts the actual number of values (including default values) in the sparse array.

=== Analytic distribution functions ===
The analytic probability functions for all built-in distributions are now also built-in functions. For example, corresponding to the [[Triangular]] distribution function there are also the [[DensTriangular]], [[CumTriangular]] and [[CumTriangularInv]] functions. Previously, to use these functions you have to add the [[Distribution Densities Library]] to your model.

The general naming pattern for these functions is (where «dist» is the name of the distribution):
* <code>Dens«dist»</code>: The ''probability density function'' for a continuous distribution. Returns the density at «x».
* <code>Prob«dist»</code>: The ''discrete probability function'' for a discrete distribution. Returns the probability of «x».
* <code>Cum«dist»</code>: The cumulative probability function, also known as the ''probability function'' and ''cumulative density function''. Returns the probability of being less than or equal to «x».
*<code>Cum«dist»Inv</code>: The inverse cumulative probability function, also called the ''quantile function''. Returns the «p»th fractile/percentile/quartile.

A few of these analytic functions were already built in previously, but all of the following were added:
* [[DensBeta]], [[DensChiSquared]], [[DensCumDist]], [[DensExponential]], [[DensFDist]], [[DensGamma]], [[DensLogistic]], [[DensProbDist]], [[DensStudentT]], [[DensTriangular]], [[DensWeibull]].
* [[ProbBernoulli]], [[ProbBinomial]], [[ProbGeometric]], [[ProbHyperGeometric]], [[ProbNegativeBinomial]], [[ProbPoisson]], [[ProbUniform]]
* [[CumBernoulli]], [[CumBeta]], [[CumChiSquared]], [[CumCumDist]], [[CumExponential]], [[CumFDist]], [[CumGamma]], [[CumGeometric]], [[CumHyperGeometric]], [[CumLogistic]], [[CumNegativeBinomial]], [[CumProbDist]], [[CumStudentT]], [[CumTriangular]], [[CumUniform]], [[CumWeibull]].
* [[CumBernoulliInv]], [[CumBetaInv]], [[CumChiSquaredInv]], [[CumCumDistInv]], [[CumExponentialInv]], [[CumFDistInv]], [[CumGammaInv]], [[CumGeometricInv]], [[CumHyperGeometricInv]], [[CumLogisticInv]], [[CumNegativeBinomInv]], [[CumProbDistInv]], [[CumStudentTInv]], [[CumTriangularInv]], [[CumUniformInv]], [[CumWeibullInv]].

=== New built-in functions ===
* The preceding section covered the many newly built-in analytic distribution functions.

* The [[F-distribution]] was added as a built-in function (functions [[FDist]], [[DensFDist]], [[CumFDist]] and [[CumFDistInv]]).

* [[ParseExpression]]: Returns a parse tree for an Analytica expression. When this is assigned to a global variable, the edit table cells are Analytica expressions.

* [[MultiResult]](..) and [[MultiResult|_]](…) return multiple values. See [[#Returning multiple values from a UDF]].

* [[ChangeArraySparsity]]: (experimental) converts between a sparse and standard multi-dimensional array representation.

* [[GraphToCanvasCoord]]: For use in the [[OnGraphDraw]] expression, it maps from a data value to a pixel coordinate. See [[#OnGraphDraw]] on this page.

* [[MantissaAndExponent]](x): Returns the mantissa and base-2 exponent of a floating point number.

=== Enhancements to existing functions ===
* [[MakeJSON]] handles the encoding of multidimensional arrays better, with better control over nesting orders and ability to map some indexes to JSON objects and others to JSON arrays.
* Added the «except» parameter to the [[IndexesOf]] function.
* Added the «first» parameter to [[SubIndex]], [[ArgMin]], [[ArgMax]], [[SubIndex]] and [[PositionInIndex]]
* [[CellOnClick]] allows local variables in expression and supplies several new local variables to the expression. See below.
* When the probabilities in a [[ProbTable]] don't add to 1, the [[Mid]]-value is now determined from the normalized version, and hence may differ from the mid-value in pre-5.2 releases. The [[Sample]]-value is unaffected, since it was already determined from the normalized probabilities.
* Optional parameters added to [[MsgBox]] allow you to include one or two URL links and a checkbox input on the dialog.
* An optional parameter «getFrom» was added to [[NumberToText]]. Specify a handle to use the stored number format from an indicated object.

=== New System Variables ===
The following system variables are new:
* [[DisableMultithreaded]]
* [[EnableSparse]]
* [[UserGoogleAPIKey]]

== Libraries and Example Models ==
* New library (for [[Analytica Enterprise]] users): "Google Maps from OnGraphDraw". Makes it easy to plot data over a Google Map via the new [[OnGraphDraw]] attribute.
* New example model (for [[Analytica Enterprise]] users): "CSV read and Google Maps plot.ana", in the Data Analysis folder. Shows how to use the Google Maps plotting, how to download CSV data from a web source with fail-over to a second URL source if the first fails, and how to parse the CSV file.

== File saving and loading ==
* The save author and save date are no longer written as part of the model file. These were inconvenient when tracking a model in a source control system (like git or svn) because they changed every time, and collided every time when merges were required. When a model file is read that does not have the save date, the SaveDate attribute is now set to the file system's last-modified time stamp.

== Cell Formats ==
=== CellOnClick ===
* The «expr» inside a [[CellOnClick]] now has access to the coordinates of the cell that was clicked. From «expr», evaluating any of the index identifiers in a value context returns the coordinate of that index at the clicked cell.
* All the special local variables available in the [[Cell Format Expression]] attribute in general are now available inside «expr» when it is run, plus two more locals can be used:
** <code>TotalIndexes</code>: A list of handles containing all indexes that are being summed over for the clicked cell.
** <code>comparisonColumn</code>: When a cell is in a comparison variable column of a result table, this is the exogenous comparison variable or expression (i.e., it is either a [[handle]] or a parsed expression). If the click was not in a comparison column (the more normal case), this is null.
* Assignment can now occur directly from inside the «expr» of [[CellOnClick]]. Previously, you had to do it from a [[UDF]].
* When a cell contains a [[handle]] or [[reference]], the default behavior is to hyperlink when the user double clicks. But a [[CellOnClick]] handler overrides that. Now if the [[CellOnClick]] returns false (0), the default behavior will (also) execute.

== Clipboard ==
* Paste XML Spreadsheet format
** Copy/paste from Excel to Analytica or from Analytica to Excel is as faithful as possible to data types and what you see is what you get
** Copy/paste from one instance of Analytica to another instance is similarly faithful
** Paste special offers XML Spreadsheet format as the default option
** Paste special unlinked supports user choice of clipboard format used
** XML Spreadsheet format offers special support for row headers and column headers on copy/paste from Analytica to Analytica
* The Paste menu option is enabled in browse mode when the focus could be pasted to if only you changed to edit mode. When you attempt a paste or Ctrl+V, it then asks you if you want to change to edit mode. Address a confusing "why isn't paste working?" case, where you forgot you are in browse mode.

== General GUI ==
* Several enhancements to the [[Indexes dialog]] make it easier to select indexes when the list is very long.
** The dialog is larger, so indexes more are visible in the panes.
** You can now view index identifiers by pressing Ctrl+Y
** You can type the first few characters to quickly jump to the index that starts with those characters.
** The Up, Down, Page Up, and Page Down keyboard can be used to scroll the index pane.
** The Left or Right keys can be used to move the selected index or indexes from one pane to the other (same as pressing the >> or << button).
** Use the mouse wheel to scroll the Indexes pane.
* More recent files recorded by default (was 6. Now 11).
* Added the '''Remove quotes''' option for lists
* Added the '''Remove quotes''' and '''Add quotes''' dropdown menu options for description and definition fields in object windows
** These operations support undo and redo
** These operations are performed in the selected area in these input windows only
** '''Add quotes''' is useful for the definition field when a paste operation puts data there that is meant to be a string but does not initially have quotes, escaping internal quotes as part of the operation
* '''Comparison Tolerance''' appears on the Definition menu.
* Undo for
** Uncertainty options... changes
* The preferred declaration constructs (e.g., Local..Do) appear on Definition menu, and not deprecated ones (e.g., Var..Do).
* When you exceed the number of characters allowed in the identifier or units field, it now displays the error in a bubble instead of a primitive model alert dialog.
::[[image:too_many_characters_bubble.png]]

== Optimizer ==
* The add-on OptQuest engine is now available from Analytica 64-bit. Previously this engine was only available in 32-bits.

== Wiki ==
* Some pages of the wiki have a release bar at the top and display different content depending on which release number is selected. The release bar looks like this:
*::{{ReleaseBar}}
*:Links from Analytica into the wiki now include the release number in the URL, so that the Wiki can automatically select the same release number that you are using. Since this is new to 5.2, release 4.6, 5.0 or 5.1 won't auto-select the release, but it will enable future releases to show the correct version-specific pages.

== ADE ==
* Changed the [[CATable::GraphWithStoredPivot]] property to default to true.
* Method for installation of ADE without running installer. Used to create a docker container image.
* The binary for AdeTest is now compiled for .NET 4.6. The project file is saved for Visual Studio 2018.

== Retired 32-bit ==
Analytica 5.2 is being released only in 64-bit. The 32-bit edition has been retired.

== Licensing ==
* Fixed a bug where RLM Server name didn't stick in licensing dialog. This caused problems for users of floating licenses and required them to manually set a registry setting to get around it.
* Changed beta-build licensing. Formerly a separate beta testing license was required. Now any active subscription license (i.e., expiring 5.x license) is sufficient. Thus, we eliminated lots of complex code for automatically acquiring and updating beta test licenses during the beta testing period.

== Typescript ==
* The Up and Down arrow keys recall history, like Ctrl+Up and Ctrl+Down already do.

What's new in Analytica 5.2?

2024-11-22T02:28:21Z

Max: /* Multiple return values */

[[category:What's new pages]]


== Highlights ==

For most users, the most valuable new features are about graphing:

* '''Zoom into graphs''': Press your mouse button within a graph and drag the cursor to show a rectangle to get a close up view of that part of the graph. You can do this horizontally to zoom into part of the X axis, vertically to zoom the Y axis, or both together.

* '''Hide elements on a graph:''' Further enhances on a popular feature introduced in [[Analytica 5.1]] that gives you the option to hide some lines on a graph. Click an element in the key to toggle whether to hide or show the corresponding line. If there are many key items, and you want to show just one or a few, you can now select '''Turn off all key items''' from the right-click menu in the Key. Then you can click just those few key items you want to show.

* '''Combine symbols and lines:''' You can show some data sets as symbols and others as a continuous line in the same graph -- for example, to show a regression line fitted to data points. In '''Graph setup''' / '''Chart type''', select the second '''Line style''' which shows lines ''and'' symbols. In the Graph, you can now click each element in the Key to display line only, symbol only, both line and symbol, or neither (to hide that data) by successive clicks. To save these options for future views of the graph, select '''Save key item visibility''' from the '''right-click menu'''.
:::[[File:Graph setup dialog with Line style lines and symbols.png|200px]]

* '''Show and fill regions on a map:''' Given a series of points with longitude and latitude, you can show them as regions. You should select the longitude and latitude values as X and Y values using [[XY Comparison|XY]] plot. The '''Graph setup''' / '''Chart type''' then shows a new '''Fill type''' option, which lets you fill in each polygon with a color.

* '''OnGraphDraw attribute:''' Lets you draw points, lines, areas, and text on a graph to annotate it, for example to point out a maximum, minimum value, add labels to points, or even show points on a Google map.

* '''Multiple results from a function:''' A function can now return multiple results of different dimensions. You can assign multiple results to multiple local variables, for example:
:<code>Local (txt, filename) := ReadTextFile('Import file.txt', Dialog: True);</code>
[[ReadTextFile]] now returns the file name as its second result in addition to the actual text contents of the file as its first result. This is useful if the user may select a different file from the default on specified as first parameter. Several other built-in functions that access files also now return the file name as a second result. You can also define user defined functions to return multiple results, using this construct, usually as the last expression in its definition:
:::<code>[[MultiResult]]( v1, v2, v3)</code>

* '''Extended syntax for locals and assignment:''' As shown above, you can declare multiple local variables at once. You can also assign to multiple local variables outside a declaration:
:::<code>(txt, filename) := ReadTextFile('Import file.txt', Dialog: True);</code>
You can declare multiple locals together as:
:::<code>Local x := 1, y := 2, z := 3;</code>

See below for more on these and other new features.

___TOC___

== Graphing ==

=== Interactive zooming ===

When you first show a result as a graph, it automatically set the ranges for the vertical and horizontal axes so that all data points are visible (ignoring values containing [[INF, NAN, and NULL - Exception values|INF, NAN, or Null]]). Now, you can zoom in to show just part of the graph by dragging the cursor. Drag the cursor horizontally from a low to high value to zoom in along the horizontal axis. Drag it vertically to zoom along the vertical axis. Drag it diagonally to create a rectangle to zoom in on both axes. It records the zoomed min and max values in the Axis ranges tab of Graph setup as if you had set them manually.

* Drag the mouse horizontally to zoom to a manually-scaled x-axis interval:
::[[image:graph_zoom_horiz.png]] → [[image:graph_zoom_horiz_after.png]]
::Transparent blue selection rectangle appears while dragging. After drag, Y is still autoscaled, but now to the data in the selected range.
* Drag the mouse diagonally to zoom to manually-scaled intervals on both axes:
::[[image:graph_zoom_diag.png]] → [[image:graph_zoom_diag_after.png]]
* When you move the mouse over a zoomed graph, autoscale hover icon buttons appear. Click on one to auto-scale that axis.
::[[image:graph_zoom_autoscale.png]] → [[image:graph_zoom_autoscaley_after.png]]
::Clicked on the vertical axis autoscale hover icon. Horizontal axis is still manually scaled.
* Drag vertically to zoom to a manually-scaled y-axis interval.
::[[image:graph_zoom_vert.png]] → [[image:graph_zoom_vert_after.png]]
* Zooming has the same effect as changing the manual scale range in Graph Setup. In fact, it records your selected end points there.
::[[image:graph_zoom_graphsetup_after.png]]

=== Key item visibility states ===

Analytica 5.2 further enhances the popular feature (introduced in [[Analytica 5.1]]) that lets you click on each item in Graph Key to show or hide the corresponding line or bar. See [[Toggling Key Item Visibility]].

==== Turn on all, Turn off all ====

Right-click on a graph Key to see menu options '''Turn on all key items''' and '''Turn off all key items'''. Use these when you want to show or hide almost all of them. They save you many clicks when there are a lot of key items.

==== Show lines and symbols ====

You can now show a graph with some data as symbols only, some as lines without symbols, and some lines and symbols. This is very useful when you want to show data points and a line fitted to those points on the same graph.
::[[image:Line and point graph.png]]

To achieve this, select the Line+Symbol plot style:
:[[image:How to line and point graph.png]]
Initially, every data series (key item) has lines and symbols (as before). Click on each Key item to toggle it from line+symbol to line-only to symbol-only, and back to line+symbol. So with just a few clicks, you can select how to display each each series.

What if your graph has multiple keys, line and symbol or symbol size each depicting different information? You can then toggle each element on each key separately through three states: On to Off to Partial, and back to On. In the Off state, it hides both lines and symbols. In the Partial state on the Line key, it hides the line but shows the symbols. Or in the Symbol Key, when an item is Partial, it shows the line but not the symbol.

::[[image:graph_key_symbol_partial.png]]

In the above graph, the 2 points corresponding to '''Least''' would appear at x=2 in the fully-on graph, but fit_err=Least is been clicked once, putting it into the off state. As a result, there is a gap in the lines at x=2. In the symbol size key (x cat), the x_cat=8 item is in the partial state. The points corresponding to x_cat=8 appear at x=8. In this case the lines pass through the points, but the symbols are hidden.

When fit_graph=y in the line key is off, all the red "ink" on the graph disappears. But when it is in the partial state, the line disappears but the symbols continue to show, as illustrated here:
::[[image:graph_key_line_partial.png]]

==== Save visibility states ====
Changes to key item visibility reset by default when you close and re-open a graph anew. If you want your current visibility state to be saved as the starting point next time the graph is opened, select '''Save key item visibilities''' from the right-mouse menu.

=== Polygon fill plots ===
When you plot a curve in an X-Y plot, there is now a polygon fill option that fills the interior of the polygon(s). For example, starting with this data, already plotted as Latitude vs Longitude
::[[image:California_unfilled_plot.png]]
you can use the new Polygon fill type (the Fill type option is new).
::[[image:Graph_setup_polygon_filltype.png]]
The difference between alternate and solid arises when a curve crosses itself. In this example with a state outline, that doesn't happen so they are equivalent. Polygon fill closes each curve segment (null data starts a new segment) and fills the interior.
::[[image:California_filled_plot.png]]
and viola!
::[[image:Red state blue state.png]]

=== OnGraphDraw ===
You can use the [[OnGraphDraw]] attribute to adorn or customize your graphs in various ways. You can enter an expression that gets evaluated at any of 4 phases during the graph rendering. A [[Canvas]] is provided that you can draw on using the [[Drawing images|canvas drawing functions]].

==== Examples ====
Using [[OnGraphDraw]], by drawing on the canvas ''after'' the graph has been rendered, you you can annotate points on a plot such as the maximum or minimum, label a threshold level, draw error bars or labels for individual points.
<center>[[image:OnGraphDraw min and max.png]]
[[image:OnGraphDraw threshold.png|400px]]
[[image:OnGraphDraw_ErrorBars.png|400px]]
</center>

By drawing ''after'' the axes have been scaled, but before the data has been plotted, you can draw under the data, or replace the rendering of the data entirely, such as by replacing probability bands with Tukey bars that your code renders.
<center>[[image:OnGraphDraw_TukeyBands.png|400px]]</center>

You can also draw a Google map under the data (Analytica Enterprise is required to support the functions necessary for downloading a Google map).
<center>[[image:OnGraphDraw map.png]]</center>
The Google map also requires running the [[OnGraphDraw]] after the graph is laid out, but before the axes are drawn, at which opportunity it can register the actual latitute/longitude axis scale to match the downloaded map.

Finally, you can draw ''before'' anything has been drawn to completely replace the graph with a totally customized data depiction, such as a pie chart, dendritic tree, etc.

==== Using OnGraphDraw ====
* To use OnGraphDraw, go to the [[Attributes dialog]] and enable it for Variables. It appears there now.
* On the [[Object window]] for the variable on interest, the [[OnGraphDraw]] attribute appears, along with a series of check box where you can select which phases of drawing you want your code called.
* Several local variables are provided to [[OnGraphDraw]]: <code>canv</code>, <code>info</code>, <code>roles</code>, <code>phase</code>, <code>continue</code>, and <code>roleChanges</code>. These supply the canvas, information about the graph itself and its layout, the pivot (roles) of the graph, and which phase of rendering is being processed. You can set <code>continue</code> to tell it not to draw further, or set <code>roleChanges</code> to make actual changes (like when registering actual latitude bounds of a Google map).
* The new [[GraphToCanvasCoord]] function makes it easy to find the pixel location for a data point, based on the data's own units.

See [[OnGraphDraw]] for instructions on how to use this.

Specific adornments or novel plot types can be encapsulated as [[User-Defined Functions]] and bundled in libraries, so that with these you need only add a function call in [[OnGraphDraw]] and check the appropriate phase check boxes. We have not released any such library yet, but may post libraries like this on the Analytica Wiki and Analytica blog in the future, so stay tuned.

=== Other graphing ===

* Bug fix impacting marginal abatement graphs
* Changing symbol size role less likely to swap other roles, less confusing

== Expression language & Engine ==

=== Declaring local identifiers ===

==== Omission of initial value====

When declaring a local, you can now omit its initial value, so that
:<code>[[Local]] x;</code>
is equivalent to
:<code>[[Local]] x := Null</code>;

==== Multiple locals in one declaration ====

You can declare multiple local identifiers in the same Local declaration. For example,
:<code>Local a, b := 5, c[ J ], d[ ] := Va1;</code>
This is then equivalent to four separate declarations as follows
<code>
:[[Local]] a:=[[Null]];
:[[Local]] b:=5;
:[[Local]] c[ J ] := [[Null]];
:[[Local]] d[ ] := Va1;
</code>

==== Capture of multiple return values ====

Functions can now return multiple values, each with different dimensionality. This is covered below in [[#Multiple return values]]. These values can be captured by [[Local]] (or the other declaration constructs like [[For]], etc.) by placing the declared identifiers inside parentheses, as illustrated here:

:<code>[[Local]] (u,w,v) := [[SingularValueDecomp]]( a, I, J, J2 );</code>

where the function, [[SingularValueDecomp]] returns three matrices, each with a different dimensionality. With dimensional restrictions, this could also be declared as

:<code>[[Local]] (u[I,J], w[J,J2], v[J,J2]) := [[SingularValueDecomp]]( a, I, J, J2 );</code>

Note that [[SingularValueDecomp]] is called a single time, and returns three separate values. This function, as well as [[EigenDecomp]], behave differently when multiple return values are captured compared to when only the main value is used, which is done for backward compatibility with their legacy behavior. Previously, the returned a data structure with 3 [[references]] to the 3 matricies, which required some work to unpack. They illustrate that the capability to return multiple values isn't entirely new, but is far more convenient. These two functions are the only functions that change their behavior. For all other functions, when only the main value is used, the secondary return values are simply dropped (and are usually not computed in the first place). For example, in addition to reading the contents of a file, you can also capture the file name selected by the user using

:<code>[[Local]] ( txt, filename ) := [[ReadTextFile]]("");</code>

but you don't need to capture filename if you don't need it, and can simple use

:<code>[[Local]] txt := [[ReadTextFile]]("");</code>

==== Reduced keyword ====

As with previous releases, you can declare the indexes that the value named by a local identifier is allowed to have using brackets, such as
:<code>[[Local]] x[I, J, K] := Z;</code>
When declared in this fashion, and expressions you include in the body (i.e., the lexical scope of these local identifiers) can be treated as if it does not contain any indexes not listed. The new keyword "<code>reduced</code>" also restricts the dimensionality of a local variable, but in a somewhat different way. The same qualifier exists for [[Function parameter qualifiers|function parameter declarations]] and in fact works in exactly the same way here.

:<code>[[Local]] ( a[ ], b reduced ) := _( X, Y );</code>

Since <code>a</code> might need to be iterated over the indexes of <code>X</code>, <code>b</code> will have the indexes of <code>Y</code> that are not also indexes of <code>X</code>. In addition, the slice of X or Y named by a or b is coordinated. When a names <code>X[J=3]</code>, then <code>b</code> also names <code>Y[J=3]</code>. This leads to some convenient new iteration constructs. For example, you may have seen expressions such as this one:

<code>
:[[For]] n := @I Do (
::[[Local]] ii := I[@I=n]
::[[Local]] x_i := X[@I=n];
::…
</code>

the ensuing looped body code makes use of the index position (n), the index label (ii), and the array slice (x_i), and so it has to extract two of the items from the loop variable. This can now be condensed to a single looping structure,

<code>
:[[For]] (n[], ii[], x_i reduced) := _(@I, I, X) Do ( …
</code>
Note: In many cases, the word [[Local]] can be used in place of [[For]] here. Note that <code>n</code> names each position of <code>I</code>, <code>ii</code> names each label of <code>I</code>, and <code>x_i</code> names the slice of <code>X</code> corresponding to <code>[@I=n]</code>. This is similar to calling a function with <code>F(@I, I, X)</code> with has Parameters declared as
:Function F(n,i : [] ; x_i : reduced)

==== Iterating over repeated parameters (Local xi := repeated x Do) ====

When a [[User-Defined Function]] has a repeated parameter, for example when its [[Parameters]] are:
:<code>( x : ... )</code>
or equivalently
:<code>(x : repeated)</code>

the "correct" way to iterate over the supplied parameters in the Definition of the UDF is now
:<code>[[Local]] xi := repeated x;</code>

The <code>repeated</code> keyword at this position is recognized. So for example, if someone calls this function as
:<code>F(a,b,c)</code>
where <code>a</code>, <code>b</code> and <code>c</code> each have different dimensions, <code>xi</code> will alias each of these values in turn. A couple syntactic variations are to use [[For]] in place of [[Local]], or to include parens around the name, e.g.,
:<code>[[For]] xi := repeated(x) Do ...</code>

As before, you can also access these using, e.g., Slice(x,2) for the second repeated. It is best, however, not to treat the repeated "dimension" as you would the implicit dimension, otherwise you may end up with the union of the incoming dimensions.

==== Preservation of local name instead of local1, local2 ====

Prior to this release, the parse tree (an internal data structure) for an Analytica expression did not remember the local identifier. Instead, it numbered the locals, and so every once in a while you might encounter a situation where the identify of the local is extracted from the parse tree and appears as <code>local1</code>, <code>local2</code>, etc. Analytica 5.2 now annotates the parse tree with the local identifier, so that depictions of the parse use the original names. For example, suppose <code>Va1</code> is defined as

[[Local]] x := [[Sin]](angle);
[[Local]] y := [[Cos]](angle);
[x,y]

You can see the difference here:
{|border="0"
|[[Image:LocalIdentsIn5.1.png]] || [[Image:LocalIdentsIn5.2.png]]
|-
! <center>In Analytica 5.1</center> !! <center>In Analytica 5.2</center>
|}

=== Multiple return values ===

Functions can now return multiple values, each with potentially different indexes, not just a single value or array, as previously. An expression calling the function may use only the first returned value, or it can use some or all of the values. Several built-in functions return extra information in the second and third return values.

==== Built-in functions that return multiple values ====

These built-in functions read information from a file and return its contents in one way or other in the main value. Each has now been enhanced to return the file name that was opened as a second parameter. Since in each case, a user might potentially select a file from a file selector dialog, you would otherwise not knowing which file was actually read. The primary return value is the same as in previous releases, the second return value is new.

* [[ReadTextFile]]: Returns ( file_contents, filename )
* [[SpreadsheetOpen]]: Returns ( workbook, filename )
* [[ReadExportFile]]: Returns ( array, filename )
* [[ReadBinaryFile]]: Returns (date, filename)
* [[ReadImageFile]]: Returns (image, filename)

Note: the Write functions don't yet return filenames in this fashion.

* [[CanvasDrawText]] returns the coordinates of the bounding box of the text.
* [[Regression]] will return the bias coefficient as a second return value without having it included in the basis.
* [[MantissaAndExponent]] returns the mantissa and exponents as separate return values.
* [[MsgBox]] returns the check box state as a second return value.

The function [[SingularValueDecomp]] computes three matrices, each with a different dimensionality. Formerly, these were returned as a vector of 3 [[reference]]s. You would then usually unpack this, extracting the three items. With the ability for it to return three return values, the call is more convenient, namely:

:<code>(u, w, v) := [[SingularValueDecomp]]( a, I, J, J2)</code>

eliminating the ugly unpacking code. To ensure backward compatibility with code that used the 3-reference data structure, it is able to detect when you are capturing multiple return values and return the 3-reference structure when you are not.

A similar enhancement applies to the [[EigenDecomp]] function, which returns a vector of eigen values and 2-D matrix of eigen vectors. Formerly, these were bundled using a reference for the eigen vectors, but with multiple return values it is convenient to immediately separate these, e.g.,

:<code>(eigenVals, eigenVecs) := [[EigenDecomp]](a, I, J)</code>

[[EigenDecomp]] also retains its legacy behavior when you are not capturing multiple return values.

The [[Regression]] function automatically adds a bias term to the basis and return the bias coefficient as the second return value when you capture the second return value. This means you can now find <code>m</code> and <code>b</code> for simple y=m*x+b regression for scalar x using just
:<code>[[Local]] (m,b) := [[Regression]](y, x, I);</code>

You can include a checkbox on a message box displayed by [[MsgBox]](). When you do so, the state of the checkbox is returned as a second return value.

==== Capturing multiple return values ====
When a function returns multiple return values, you have to capture these values. There are two ways of doing this: In a local declaration, or via the assignment operator (:=).

:<code>[[Local]]( x, y, z ) := FuncWithMultiple( );</code>
or
:<code>(a, b, c) := FuncWithMultiple( );</code>

When assignment is used, each destination (a, b and c) can be anything that could appear on the left-hand side of an normal assignment operator. This includes local identifiers, global variables (in contexts where a side-effect is legal), a slice of a local variable, an attribute of an object, etc.

Although I'm showing the local declaration example using [[Local..Do]], you can also use other local declaration constructs in the same way, including [[For]] and [[LocalAlias]], or the legacy [[Var..Do]], [[Using..Do]], [[MetaVar..Do]], etc.

When you capture a return value that isn't actually returned by the function, it is equivalent to capturing null. For example:
:<code>( x,y ) := [[Sqrt]](5)</code>
sets <code>x</code> to 5 and <code>y</code> to null.

==== Returning multiple values from a UDF ====
To return multiple values from your own UDFs, simple return
:<code>[[MultiResult]]( v1, v2, v3, v4 )</code>
where <code>v1, v2, …</code> are the expressions whose result is to be returned. Be aware that for any of these values that are not captured by the caller, the corresponding expression will not be evaluated. You can use that to your advantage by placing any time-consuming code not shared by v1 in the expression for v2, so that when the caller uses only v1, no wasted computation ensues.

There is a synonymous syntax, <code>_( v1, v2, v3, v4 )</code> that can be used. When returning values from a UDF, we feel that it clearer to call [[MultiResult]]. However, the underscore function is convenient when using a multiple assignment directly, such as

:<code>[[Local]] (key[], val[]) := _( dict.Key, dict );</code>

This example combines <code>_( ) </code> with [[Repeated parameter forwarding]] to accomplish something that would have taken four lines of code otherwise.
:<code>[[Local]] (x,y,z) := _( ...[[ParseNumber]]( [[SplitText]]( "10, 20, 3", "," ) ) );</code>

==== Emergent iteration constructs ====

Some new convenient forms of iteration constructs emerge from the introduction of multiple return values. For example, when iterating over an index, you can simultaneously grab the index position and the index labels in the loop declaration.
<code>
:[[For]] ( pos, label ) := _( @J, J ) Do …
</code>

A 1-D array with an index containing labels is called as associative array in other programming languages. The index values are the keys and the array values are the values. Your iteration can conveniently name both the current key and the current value.
<code>
:[[For]] ( key[], val reduced ) := _( I, a ) Do …
</code>

=== Assignment ===
* (Definition of X := array) -- setting cell expressions
* new ParseExpression() function
* Capturing multiple values
=== Multithreading ===
Added finer-grained control over which multi-threaded algorithms are enabled or disabled. This is so that if you encounter a multi-threading-related problem with one particular algorithm, you can disable it without having to sacrifice all multi-threading.

* [[DisableMultithreaded]]: New system variable that contains the flags.
* [[SetEvaluationFlag]]('multithreaded'): Function for turning on or off only within one expression.

=== Experimental ===
You should not rely on experimental features while they are still experimental. They are subject to change or even cancellation in future releases, and are less thoroughly tested.

==== Sparse arrays ====
Analytica has long had support for a certain form of sparsity, which we call constant sparsity (or just const sparsity for short). When the values along a slice of an array don't vary (are constant), Analytica is often able to store the single value only, and also avoid an iteration during computations. However, many sparse arrays can't take advantage of const sparseness. We've been experimenting with fully sparse multi-dimensional arrays. With these, it is possible to have multidimensional cubes with large numbers of dimensions and immense numbers of distinct coordinates as long as the number of cell with actual data is relatively small. Such sparsity is often seen in [[MdTable]] relational-to-array transformations.

You can use the same Analytica operators and functions on sparse arrays as you would on any other Analytica arrays, but when possible, Analytica will attempt to use sparse algorithms to process the only values that are present and produce a sparse array, maintaining fast and low-memory computation. With this we have been able to demonstrate some real-life computations on sparse BI hypercubes that were not previously possible (and which are not realistically possible with a relational table representation).

Some operations produce non-sparse results, even when applied to sparse arrays. [[Cumulate]] applied to an array with a non-zero default value is one obvious example. This is a serious "gotcha", because if you are manipulating arrays with quadrillions of cells, one application of a function like that and you've just created a multi-petabyte array.

At present, only a subset of operations and functions that could have sparse-array-aware algorithms actually do; however, many of the ones that are present are the most common operations. But this incompleteness is one reason this is classified as an experimental feature.

In addition, the sparse algorithms are at this point quite new and not battle tested, so it not unlikely that bugs may be lurking, including bugs that might produce incorrect results. One of the reasons we are including it as an experimental feature is to promote testing of the algorithms.

===== Using sparse arrays =====
The use of sparse arrays is enabled by setting the system variable [[EnableSparse]] to 1. Or, you can enable the production of a sparse array from a specific expression by using <code>[[SetEvaluationFlag]]('sparse', true', «expr»)</code>.

[[MdTable]] is able to return a sparse array from a relational table, provided [[EnableSparse]] is set, or the sparse evaluation flag is on, or you set the optional «sparse» parameter to true. From there, the sparseness will propagate as you slice, add, and so on.

Expressions like <code>a = b</code> are often sparse, but will only return a sparse result when the evaluation context allows it. When these produce dense arrays, and those dense arrays are combined with sparse arrays, a lot of sparsity is often lost.

== Built-in functions ==
=== with Multiple return values ===
The following built-in functions now return multiple results: [[ReadTextFile]], [[ReadImageFile]], [[ReadBinaryFile]], [[SpreadsheetOpen]], [[ReadExportFile]], [[SingularValueDecomp]], [[EigenDecomp]], [[MsgBox]], [[MantissaAndExponent]], [[CanvasDrawText]] and [[Regression]].

See [[#Multiple return values]] above.

=== New optional parameters to existing functions ===
* Added an optional parameter named «initially» parameter to [[ComputedBy]]. This provides an initial value for the parent variable, and retains the value assigned by the called in the definition. (But only when the value is a simple atom). For example, if you want to remember what file a user selected, you could use:<code>
Variable filename := [[ComputedBy]](wb,"")

Variable wb :=
Local tmp;
(tmp,filename) := [[SpreadsheetOpen]](filename);
tmp</code>

* Added an optional Boolean parameter, «w1D» parameter to [[SingularValueDecomp]]. When false or omitted, it the resulting W is a square diagonal matrix. When set to true, the returned W is a vector (the diagonal).

* Added an optional «except» parameter to [[IndexesOf]], which accepts any number of index identifiers. For example, the following sums over every index of array A except for <code>I</code> and <code>J</code>.
:::<code>[[Sum]]( A, …[[IndexesOf]](A, except:I,J) )</code>

* Added a «first» parameter to [[ArgMin]], [[Argmax]], [[SubIndex]], and [[PositionInIndex]]. When omitted or false, in the event of a tie these return the ''last'' occurrence. When set to true, they return the position of the first occurrence of the tie.

::In addition, it was previously less obvious which tie was identified by [[ArgMin]] or [[Argmax]] in the multi-dimensional case. Now it is the first or last occurrence in the natural ordering of the supplied index parameters.

* The basis index, <code>K</code>, is now optional for the [[Regression]] function. This is for convenience when performing a 1-D regression over a scalar x.

* Added an optional «measureOnly» boolean parameter to [[CanvasDrawText]].

==== For sparse arrays ====
* Added an optional boolean parameter «sparse» to [[MdTable]]. Experimental. See [[#Sparse arrays]].
* The optional Boolean «sparseCount» parameter to [[Size]]. When true, counts the actual number of values (including default values) in the sparse array.

=== Analytic distribution functions ===
The analytic probability functions for all built-in distributions are now also built-in functions. For example, corresponding to the [[Triangular]] distribution function there are also the [[DensTriangular]], [[CumTriangular]] and [[CumTriangularInv]] functions. Previously, to use these functions you have to add the [[Distribution Densities Library]] to your model.

The general naming pattern for these functions is (where «dist» is the name of the distribution):
* <code>Dens«dist»</code>: The ''probability density function'' for a continuous distribution. Returns the density at «x».
* <code>Prob«dist»</code>: The ''discrete probability function'' for a discrete distribution. Returns the probability of «x».
* <code>Cum«dist»</code>: The cumulative probability function, also known as the ''probability function'' and ''cumulative density function''. Returns the probability of being less than or equal to «x».
*<code>Cum«dist»Inv</code>: The inverse cumulative probability function, also called the ''quantile function''. Returns the «p»th fractile/percentile/quartile.

A few of these analytic functions were already built in previously, but all of the following were added:
* [[DensBeta]], [[DensChiSquared]], [[DensCumDist]], [[DensExponential]], [[DensFDist]], [[DensGamma]], [[DensLogistic]], [[DensProbDist]], [[DensStudentT]], [[DensTriangular]], [[DensWeibull]].
* [[ProbBernoulli]], [[ProbBinomial]], [[ProbGeometric]], [[ProbHyperGeometric]], [[ProbNegativeBinomial]], [[ProbPoisson]], [[ProbUniform]]
* [[CumBernoulli]], [[CumBeta]], [[CumChiSquared]], [[CumCumDist]], [[CumExponential]], [[CumFDist]], [[CumGamma]], [[CumGeometric]], [[CumHyperGeometric]], [[CumLogistic]], [[CumNegativeBinomial]], [[CumProbDist]], [[CumStudentT]], [[CumTriangular]], [[CumUniform]], [[CumWeibull]].
* [[CumBernoulliInv]], [[CumBetaInv]], [[CumChiSquaredInv]], [[CumCumDistInv]], [[CumExponentialInv]], [[CumFDistInv]], [[CumGammaInv]], [[CumGeometricInv]], [[CumHyperGeometricInv]], [[CumLogisticInv]], [[CumNegativeBinomInv]], [[CumProbDistInv]], [[CumStudentTInv]], [[CumTriangularInv]], [[CumUniformInv]], [[CumWeibullInv]].

=== New built-in functions ===
* The preceding section covered the many newly built-in analytic distribution functions.

* The [[F-distribution]] was added as a built-in function (functions [[FDist]], [[DensFDist]], [[CumFDist]] and [[CumFDistInv]]).

* [[ParseExpression]]: Returns a parse tree for an Analytica expression. When this is assigned to a global variable, the edit table cells are Analytica expressions.

* [[MultiResult]](..) and [[MultiResult|_]](…) return multiple values. See [[#Returning multiple values from a UDF]].

* [[ChangeArraySparsity]]: (experimental) converts between a sparse and standard multi-dimensional array representation.

* [[GraphToCanvasCoord]]: For use in the [[OnGraphDraw]] expression, it maps from a data value to a pixel coordinate. See [[#OnGraphDraw]] on this page.

* [[MantissaAndExponent]](x): Returns the mantissa and base-2 exponent of a floating point number.

=== Enhancements to existing functions ===
* [[MakeJSON]] handles the encoding of multidimensional arrays better, with better control over nesting orders and ability to map some indexes to JSON objects and others to JSON arrays.
* Added the «except» parameter to the [[IndexesOf]] function.
* Added the «first» parameter to [[SubIndex]], [[ArgMin]], [[ArgMax]], [[SubIndex]] and [[PositionInIndex]]
* [[CellOnClick]] allows local variables in expression and supplies several new local variables to the expression. See below.
* When the probabilities in a [[ProbTable]] don't add to 1, the [[Mid]]-value is now determined from the normalized version, and hence may differ from the mid-value in pre-5.2 releases. The [[Sample]]-value is unaffected, since it was already determined from the normalized probabilities.
* Optional parameters added to [[MsgBox]] allow you to include one or two URL links and a checkbox input on the dialog.
* An optional parameter «getFrom» was added to [[NumberToText]]. Specify a handle to use the stored number format from an indicated object.

=== New System Variables ===
The following system variables are new:
* [[DisableMultithreaded]]
* [[EnableSparse]]
* [[UserGoogleAPIKey]]

== Libraries and Example Models ==
* New library (for [[Analytica Enterprise]] users): "Google Maps from OnGraphDraw". Makes it easy to plot data over a Google Map via the new [[OnGraphDraw]] attribute.
* New example model (for [[Analytica Enterprise]] users): "CSV read and Google Maps plot.ana", in the Data Analysis folder. Shows how to use the Google Maps plotting, how to download CSV data from a web source with fail-over to a second URL source if the first fails, and how to parse the CSV file.

== File saving and loading ==
* The save author and save date are no longer written as part of the model file. These were inconvenient when tracking a model in a source control system (like git or svn) because they changed every time, and collided every time when merges were required. When a model file is read that does not have the save date, the SaveDate attribute is now set to the file system's last-modified time stamp.

== Cell Formats ==
=== CellOnClick ===
* The «expr» inside a [[CellOnClick]] now has access to the coordinates of the cell that was clicked. From «expr», evaluating any of the index identifiers in a value context returns the coordinate of that index at the clicked cell.
* All the special local variables available in the [[Cell Format Expression]] attribute in general are now available inside «expr» when it is run, plus two more locals can be used:
** <code>TotalIndexes</code>: A list of handles containing all indexes that are being summed over for the clicked cell.
** <code>comparisonColumn</code>: When a cell is in a comparison variable column of a result table, this is the exogenous comparison variable or expression (i.e., it is either a [[handle]] or a parsed expression). If the click was not in a comparison column (the more normal case), this is null.
* Assignment can now occur directly from inside the «expr» of [[CellOnClick]]. Previously, you had to do it from a [[UDF]].
* When a cell contains a [[handle]] or [[reference]], the default behavior is to hyperlink when the user double clicks. But a [[CellOnClick]] handler overrides that. Now if the [[CellOnClick]] returns false (0), the default behavior will (also) execute.

== Clipboard ==
* Paste XML Spreadsheet format
** Copy/paste from Excel to Analytica or from Analytica to Excel is as faithful as possible to data types and what you see is what you get
** Copy/paste from one instance of Analytica to another instance is similarly faithful
** Paste special offers XML Spreadsheet format as the default option
** Paste special unlinked supports user choice of clipboard format used
** XML Spreadsheet format offers special support for row headers and column headers on copy/paste from Analytica to Analytica
* The Paste menu option is enabled in browse mode when the focus could be pasted to if only you changed to edit mode. When you attempt a paste or Ctrl+V, it then asks you if you want to change to edit mode. Address a confusing "why isn't paste working?" case, where you forgot you are in browse mode.

== General GUI ==
* Several enhancements to the [[Indexes dialog]] make it easier to select indexes when the list is very long.
** The dialog is larger, so indexes more are visible in the panes.
** You can now view index identifiers by pressing Ctrl+Y
** You can type the first few characters to quickly jump to the index that starts with those characters.
** The Up, Down, Page Up, and Page Down keyboard can be used to scroll the index pane.
** The Left or Right keys can be used to move the selected index or indexes from one pane to the other (same as pressing the >> or << button).
** Use the mouse wheel to scroll the Indexes pane.
* More recent files recorded by default (was 6. Now 11).
* Added the '''Remove quotes''' option for lists
* Added the '''Remove quotes''' and '''Add quotes''' dropdown menu options for description and definition fields in object windows
** These operations support undo and redo
** These operations are performed in the selected area in these input windows only
** '''Add quotes''' is useful for the definition field when a paste operation puts data there that is meant to be a string but does not initially have quotes, escaping internal quotes as part of the operation
* '''Comparison Tolerance''' appears on the Definition menu.
* Undo for
** Uncertainty options... changes
* The preferred declaration constructs (e.g., Local..Do) appear on Definition menu, and not deprecated ones (e.g., Var..Do).
* When you exceed the number of characters allowed in the identifier or units field, it now displays the error in a bubble instead of a primitive model alert dialog.
::[[image:too_many_characters_bubble.png]]

== Optimizer ==
* The add-on OptQuest engine is now available from Analytica 64-bit. Previously this engine was only available in 32-bits.

== Wiki ==
* Some pages of the wiki have a release bar at the top and display different content depending on which release number is selected. The release bar looks like this:
*::{{ReleaseBar}}
*:Links from Analytica into the wiki now include the release number in the URL, so that the Wiki can automatically select the same release number that you are using. Since this is new to 5.2, release 4.6, 5.0 or 5.1 won't auto-select the release, but it will enable future releases to show the correct version-specific pages.

== ADE ==
* Changed the [[CATable::GraphWithStoredPivot]] property to default to true.
* Method for installation of ADE without running installer. Used to create a docker container image.
* The binary for AdeTest is now compiled for .NET 4.6. The project file is saved for Visual Studio 2018.

== Retired 32-bit ==
Analytica 5.2 is being released only in 64-bit. The 32-bit edition has been retired.

== Licensing ==
* Fixed a bug where RLM Server name didn't stick in licensing dialog. This caused problems for users of floating licenses and required them to manually set a registry setting to get around it.
* Changed beta-build licensing. Formerly a separate beta testing license was required. Now any active subscription license (i.e., expiring 5.x license) is sufficient. Thus, we eliminated lots of complex code for automatically acquiring and updating beta test licenses during the beta testing period.

== Typescript ==
* The Up and Down arrow keys recall history, like Ctrl+Up and Ctrl+Down already do.

Embed an ACP model in a Web Page

2024-11-19T01:01:41Z

Max: /* ACP in an Iframe on a wiki */

[[Category: Analytica Cloud Platform]]
[[Category: Models]]

[[Analytica_Cloud_Platform|<<back]]

==Overview==
People normally view [[Analytica Cloud Platform]] (ACP) models on an acp server such as [https://ACP.Analytica.com https://ACP.Analytica.com]. However, you can also embed an ACP model in any web page, for example on your own web site, to make it more easily accessible to end users. When you do this, your users see the ACP model as a region in an iFrame within your HTML content, although the model is actually being run on the ACP server.

This page explains how to configure your own web page to display an ACP model.

'''Prerequisite:''' You must already have an ACP account, which you do if you have a subscription to any desktop Edition of Analytica.

The model will appear and use an ACP session credit whenever a user visits the web page. You can avoid this (and the time delay while the ACP model loads) by hiding the model behind a screenshot of the ACP mode. You can add code to start the model and use a session credit only when a user clicks the screenshot.

==Showing your model in an inline Frame (Iframe)==
An inline frame is just an HTML document embedded inside another HTML document on a website.

=== Step 1: Create a Web page. ===
To keep it simple, let’s say you just want to display an ACP model in an otherwise empty web page, in an Iframe. We’ll show you an example of how to do this, and hopefully that’s enough for you to get started on playing your own model within a web page on your web site.

In this example, there are two servers.
*Your Server, the server where your web site resides. This is the server you are able to upload and edit pages on.
*And there’s ACP’s server, https://acp.analytica.com, which hosts ACP and will contain the web page that plays your model. ''Since this page is an HTML frame, it will appear the model is being played on your web site.''

#First, create a web page - you can use a text editor. Here is one that just contains a title, 'Look at My Analytica Model'. Save this as an html file ACPIframe.html.

<div style="margin-left: 2em;">
<code><nowiki><html></nowiki></code> 
<code><nowiki><head></nowiki></code> 
  <code><nowiki><title>Look at My Analytica Model</title></nowiki></code> 
<code><nowiki></head></nowiki></code> 
<code><nowiki><body></nowiki></code> 
  <code><nowiki><h1>Look at My Analytica Model</h1></nowiki></code> 
<code><nowiki></body></nowiki></code> 
<code><nowiki></html></nowiki></code>
</div>

When opened in the Chrome browser this is what this web page initially displays :

:[[File:ACPIFrame01.png]]

=== Step 2 - Creating the Link to Play Your Model ===
Use ACP’s Email Invite functionality to create the link which will play your model.

#[https://acp.analytica.com/ Sign into your ACP account]
#If your model doesn't already use [[ACP_Auto_zoom|Auto Zoom]] style that will make the ACP zoom to fit the Iframe, you should make it do so. Click the model to open it in ACP, select ACP Style lib, and set it to Auto Zoom. Then save the model.
#Click a radio button to select your model -- in this example. the Project portfolio planner.ana.
#:[[File:ACPFrame01.png|720px|thumb|left]]
#Click the '''Email Invite''' button to show the email invitation dialog:
#Copy the link from this email invite. 
#:[[File:ACPFrame02.png|720px|thumb|left]] 
#Press '''Cancel''' button, since we aren’t sending the invite to anyone.

''Note: Ensure a model you insert in a web page stays in the same ACP Model Project and folder.'' If you delete it, the web page will show an error message saying "the model can't be found".

===Step 3: Insert the code for an Iframe. ===

1. Now in the web page source Insert the code for an Iframe with the link to your model in it. 
2. Set the Iframe to be a size that looks good for your model diagram, and that fits with auto zoom. It will probably need to be tweaked later, but you can do this by playing the model in ACP, and by using developer's tools or by taking a screenshot of the model and checking the dimensions. In this case the model looks good at width: 900px; height: 446px. 
3. Add Iframe html tags and paste the link for your model into the "src" attribute, and the code for ACPIframe.html will look like this: 

<div style="margin-left: 2em;">
<code><nowiki><html></nowiki></code> 
<code><nowiki><head></nowiki></code> 
  <code><nowiki><title>Look at My Analytica Model</title></nowiki></code> 
<code><nowiki></head></nowiki></code> 
<code><nowiki><body></nowiki></code> 
  <code><nowiki><h1>Look at My Analytica Model</h1></nowiki></code> 
  <code><nowiki><iframe width="900" height="446" src="https://acp.analytica.com/view?invite=4771&code=2359748081441958275"></iframe></nowiki></code> 
<code><nowiki></body></nowiki></code> 
<code><nowiki></html></nowiki></code>
</div>

4. Now you can save the web page and load it in a browser. Or you can see it on the Analytica docs server here: [https://docs.analytica.com/custom_pages/ACPIframe.html https://docs.analytica.com/custom_pages/ACPIframe.html]
It will display the model in the iframe like this:
:[[File:ACPIFrame02.png|720px|thumb|left]]
Download the example html [[File:ACPIframe.zip]].


==Put an ACP model behind an image==
To avoid the ACP model loading each time the page is visited, you can hide the model behind an image, and add code to start the model when the image is clicked like a button.

'''Tip:''' To save time and get the screen shots to paste into an editor at close to the same size as what you are seeing in the browser, you may want to adjust your display settings to 100%.

1. Make a display image to put over the iframe when ACP is not running the model. Here is one way to do this:
a. Enter the source url from the html into the address bar for Chrome. Then with the browser unmaximized, adjust the window size until it looks good and the zoom fits the diagram. Using developer's tools elements tab I can see the model diagram looks pretty good at 900px wide; 447px height;.[[File:ACPIFrame05.png|720px|thumb|left]]
b. Take a screenshot, crop it to remove all but the model and the top bar and save the image.
[[File:ACPIFrame06.png|720px|thumb|left]]
2. Save the image where it is accessible to the javascript - for instance, in the same folder or in an uploads directory. 
3. Add a div in the html source containing the container with the display image. And the script following.
<div style="margin-left: 2em;">
<code><nowiki><html></nowiki></code> 
<code><nowiki><head></nowiki></code> 
  <code><nowiki><title>Look at My Analytica Model</title></nowiki></code> 
<code><nowiki></head></nowiki></code> 
<code><nowiki><body></nowiki></code> 
  <code><nowiki><h1>Look at My Analytica Model</h1></nowiki></code> 
  <code><nowiki><div id="container" style="cursor: pointer; border: 1px solid #ccc; padding: 10px; margin: 10px; width: 900px; height: 447px;"></nowiki></code> 
    <code><nowiki><img id="runImage" src="ACPIframe02.png" style="width: 100%; height: 100%;"></nowiki></code> 
  <code><nowiki></div></nowiki></code> 
  <code><nowiki><script></nowiki></code> 
    <code><nowiki>document.addEventListener('DOMContentLoaded', function () {</nowiki></code> 
      <code><nowiki>function showIframe() {</nowiki></code> 
        <code><nowiki>// Hide the image</nowiki></code> 
        <code><nowiki>document.getElementById('runImage').style.display = 'none';</nowiki></code> 
        <code><nowiki>// Create and configure the iframe</nowiki></code> 
        <code><nowiki>const iframe = document.createElement('iframe');</nowiki></code> 
        <code><nowiki>iframe.src = 'https://acp.analytica.com/view?invite=4714&code=4200729999208732852';</nowiki></code> 
        <code><nowiki>iframe.style.width = '900px';</nowiki></code> 
        <code><nowiki>iframe.style.height = '446px';</nowiki></code> 
        <code><nowiki>iframe.style.border = 'none';</nowiki></code> 

        <code><nowiki>// Append the iframe to the container</nowiki></code> 
        <code><nowiki>document.getElementById('container').appendChild(iframe);</nowiki></code> 
      <code><nowiki>}</nowiki></code> 

      <code><nowiki>// Add click event listener to the image container</nowiki></code> 
      <code><nowiki>document.getElementById('container').addEventListener('click', showIframe);</nowiki></code> 
    <code><nowiki>});</nowiki></code> 
  <code><nowiki></script></nowiki></code> 
<code><nowiki></body></nowiki></code> 
<code><nowiki></html></nowiki></code>
</div>

Download the example html file and image [[File:ACPIModelBehindImage.zip]]

You can see what this page looks like here: [https://docs.analytica.com/custom_pages/ACPModelBehindIframe.html https://docs.analytica.com/custom_pages/ACPModelBehindIframe.html]

== Buttons to expand to full screen and minimize==

It's convenient for users to be able to expand an embedded ACP window to the full browser window -- and to minimize it again. Here's a live example: [[https://docs.analytica.com/custom_pages/ACPIframeInteract.html https://docs.analytica.com/custom_pages/ACPIframeInteract.html]
Here is how to add
* a maximize button [[File:Arrows-maximize.png|24px]] to show the Iframe fullscreen - visible in the Iframe when the model is running at normal size.
* a minimize button [[File:Arrows-minimize.png|24px]] to exitfull screen visible when the Iframe is full screen.
* a button on the Iframe labeled "click to interact with the model in Analytica Cloud Platform" to clarify that you need to click it to start the model in ACP.
* Some styling with a 1 pixel wide outline and a drop shadow. You can set these in a css file too.
* The fullscreen and minimize icons from the docs.analytica.com wiki - just use links to them for now.

Here is an example html file with the code to add these extra features, using the same overlay image as before: [[File:ACPIframeInteract.zip]]

Here is some updated html and script.
<div style="margin-left: 2em;">
<code><nowiki><!DOCTYPE html></nowiki></code> 
<code><nowiki><html></nowiki></code> 
<code><nowiki><head></nowiki></code> 
  <code><nowiki><title>Interactive Analytica Model</title></nowiki></code> 
  <code><nowiki><style></nowiki></code> 
    <code><nowiki>#container {</nowiki></code> 
      <code><nowiki>position: relative;</nowiki></code> 
      <code><nowiki>cursor: pointer;</nowiki></code> 
      <code><nowiki>width: 900px;</nowiki></code> 
      <code><nowiki>height: 447px;</nowiki></code> 
      <code><nowiki>margin: 0 auto;</nowiki></code> 
      <code><nowiki>border: 1px solid #ccc;</nowiki></code> 
      <code><nowiki>box-shadow: 0 4px 8px rgba(0, 0, 0, 0.2);</nowiki></code> 
    <code><nowiki>}</nowiki></code> 
    <code><nowiki>#runImage {</nowiki></code> 
      <code><nowiki>width: 100%;</nowiki></code> 
      <code><nowiki>height: 100%;</nowiki></code> 
      <code><nowiki>display: block;</nowiki></code> 
    <code><nowiki>}</nowiki></code> 
    <code><nowiki>.control-button {</nowiki></code> 
      <code><nowiki>position: absolute;</nowiki></code> 
      <code><nowiki>width: 30px;</nowiki></code> 
      <code><nowiki>height: 30px;</nowiki></code> 
      <code><nowiki>background-size: contain;</nowiki></code> 
      <code><nowiki>background-repeat: no-repeat;</nowiki></code> 
      <code><nowiki>background-color: transparent;</nowiki></code> 
      <code><nowiki>border: none;</nowiki></code> 
      <code><nowiki>cursor: pointer;</nowiki></code> 
    <code><nowiki>}</nowiki></code> 
    <code><nowiki>#maximizeButton {</nowiki></code> 
      <code><nowiki>bottom: 10px;</nowiki></code> 
      <code><nowiki>right: 120px;</nowiki></code> 
      <code><nowiki>background-image: url("https://docs.analytica.com/images/9/9c/Arrows-maximize.png");</nowiki></code> 
      <code><nowiki>display: none;</nowiki></code> 
    <code><nowiki>}</nowiki></code> 
    <code><nowiki>#minimizeButton {</nowiki></code> 
      <code><nowiki>bottom: 10px;</nowiki></code> 
      <code><nowiki>right: 120px;</nowiki></code> 
      <code><nowiki>background-image: url("https://docs.analytica.com/images/8/82/Arrows-minimize.png");</nowiki></code> 
      <code><nowiki>display: none;</nowiki></code> 
    <code><nowiki>}</nowiki></code> 
    <code><nowiki>#interactButton {</nowiki></code> 
      <code><nowiki>position: absolute;</nowiki></code> 
      <code><nowiki>bottom: 10px;</nowiki></code> 
      <code><nowiki>right: 120px;</nowiki></code> 
      <code><nowiki>padding: 5px 10px;</nowiki></code> 
      <code><nowiki>font-size: 16px;</nowiki></code> 
      <code><nowiki>font-weight: bold;</nowiki></code> 
      <code><nowiki>background-color: #e4e4e4;</nowiki></code> 
      <code><nowiki>color: black;</nowiki></code> 
      <code><nowiki>border: none;</nowiki></code> 
      <code><nowiki>border-radius: 5px;</nowiki></code> 
      <code><nowiki>cursor: pointer;</nowiki></code> 
      <code><nowiki>opacity: 0.9;</nowiki></code> 
      <code><nowiki>display: inline-block;</nowiki></code> 
    <code><nowiki>}</nowiki></code> 
  <code><nowiki></style></nowiki></code> 
<code><nowiki></head></nowiki></code> 
<code><nowiki><body></nowiki></code> 
  <code><nowiki><div id="container"></nowiki></code> 
    <code><nowiki><img id="runImage" src="ACPIframe02.png"></nowiki></code> 
    <code><nowiki><button id="maximizeButton" class="control-button" title="Click to use full screen"></button></nowiki></code> 
    <code><nowiki><button id="minimizeButton" class="control-button" title="Exit full screen"></button></nowiki></code> 
    <code><nowiki><button id="interactButton">Click to interact with the model in Analytica Cloud Platform</button></nowiki></code> 
  <code><nowiki></div></nowiki></code> 
</div>
<div style="margin-left: 2em;">
<code><nowiki><script></nowiki></code> 
  <code><nowiki>document.addEventListener('DOMContentLoaded', function () {</nowiki></code> 
    <code><nowiki>let iframeAdded = false;</nowiki></code> 
    <code><nowiki>const container = document.getElementById('container');</nowiki></code> 
    <code><nowiki>const runImage = document.getElementById('runImage');</nowiki></code> 
    <code><nowiki>const maximizeButton = document.getElementById('maximizeButton');</nowiki></code> 
    <code><nowiki>const minimizeButton = document.getElementById('minimizeButton');</nowiki></code> 
    <code><nowiki>const interactButton = document.getElementById('interactButton');</nowiki></code> 
    <code><nowiki>function showIframe() {</nowiki></code> 
      <code><nowiki>runImage.style.display = 'none';</nowiki></code> 
      <code><nowiki>interactButton.style.display = 'none';</nowiki></code> 
      <code><nowiki>if (!iframeAdded) {</nowiki></code> 
        <code><nowiki>const iframe = document.createElement('iframe');</nowiki></code> 
        <code><nowiki>iframe.src = 'https://acp.analytica.com/view?invite=4771&code=2359748081441958275';</nowiki></code> 
        <code><nowiki>iframe.style.width = '100%';</nowiki></code> 
        <code><nowiki>iframe.style.height = '100%';</nowiki></code> 
        <code><nowiki>iframe.style.border = 'none';</nowiki></code> 
        <code><nowiki>container.appendChild(iframe);</nowiki></code> 
        <code><nowiki>iframeAdded = true;</nowiki></code> 
        <code><nowiki>maximizeButton.style.display = 'inline-block';</nowiki></code> 
      <code><nowiki>}</nowiki></code> 
    <code><nowiki>}</nowiki></code> 
    <code><nowiki>function maximizeIframe() {</nowiki></code> 
      <code><nowiki>if (container.requestFullscreen) {</nowiki></code> 
        <code><nowiki>container.requestFullscreen();</nowiki></code> 
      <code><nowiki>} else if (container.webkitRequestFullscreen) {</nowiki></code> 
        <code><nowiki>container.webkitRequestFullscreen();</nowiki></code> 
      <code><nowiki>} else if (container.msRequestFullscreen) {</nowiki></code> 
        <code><nowiki>container.msRequestFullscreen();</nowiki></code> 
      <code><nowiki>}</nowiki></code> 
      <code><nowiki>maximizeButton.style.display = 'none';</nowiki></code> 
      <code><nowiki>minimizeButton.style.display = 'inline-block';</nowiki></code> 
    <code><nowiki>}</nowiki></code> 
    <code><nowiki>function minimizeIframe() {</nowiki></code> 
      <code><nowiki>if (document.exitFullscreen) {</nowiki></code> 
        <code><nowiki>document.exitFullscreen();</nowiki></code> 
      <code><nowiki>} else if (document.webkitExitFullscreen) {</nowiki></code> 
        <code><nowiki>document.webkitExitFullscreen();</nowiki></code> 
      <code><nowiki>} else if (document.msExitFullscreen) {</nowiki></code> 
        <code><nowiki>document.msExitFullscreen();</nowiki></code> 
      <code><nowiki>}</nowiki></code> 
      <code><nowiki>maximizeButton.style.display = 'inline-block';</nowiki></code> 
      <code><nowiki>minimizeButton.style.display = 'none';</nowiki></code> 
    <code><nowiki>}</nowiki></code> 
    <code><nowiki>interactButton.addEventListener('click', function (event) {</nowiki></code> 
      <code><nowiki>event.stopPropagation();</nowiki></code> 
      <code><nowiki>showIframe();</nowiki></code> 
    <code><nowiki>});</nowiki></code> 
    <code><nowiki>maximizeButton.addEventListener('click', function (event) {</nowiki></code> 
      <code><nowiki>event.stopPropagation();</nowiki></code> 
      <code><nowiki>maximizeIframe();</nowiki></code> 
    <code><nowiki>});</nowiki></code> 
    <code><nowiki>minimizeButton.addEventListener('click', function (event) {</nowiki></code> 
      <code><nowiki>event.stopPropagation();</nowiki></code> 
      <code><nowiki>minimizeIframe();</nowiki></code> 
    <code><nowiki>});</nowiki></code> 
    <code><nowiki>container.addEventListener('click', showIframe);</nowiki></code> 
  <code><nowiki>});</nowiki></code> 
<code><nowiki></script></nowiki></code> 
<code><nowiki></body></nowiki></code> 
<code><nowiki></html></nowiki></code>
</div>

==ACP in an Iframe on a wiki==
You cannot usually add html or javascript into a mediawiki page. Instead, you can run the code in a widget. To do this you need to install the widget extension, then save the code as a widget page and put the widget into your mediawiki page.
*Here's an example page in Analytica docs which uses a widget file to run the same model. [https://docs.analytica.com/index.php/Testiframe https://docs.analytica.com/index.php/Testiframe].
*You can inspect this code by navigating to the page and selecting <code>This page > show source</code>.
*You can also navigate to the widget page and view the source: [https://docs.analytica.com/index.php/Widget:Ppplanner05 https://docs.analytica.com/index.php/Widget:Ppplanner05].

==ACP in an Iframe on a wordpress site==
Running live on this page: [https://analytica.com/acpiframeminmax/ https://analytica.com/acpiframeminmax/]
To add an iframe running an ACP model on an Elementor page:
*Upload images needed to your wordpress site and note the location and urls.
*Click edit with Elementor.
*Add a new section then drag an HTML widget onto the section.
* In the code block for the HTML widget enter the code for your overlay image and for your iframe.
**Here is the code for this Iframe: you would need to edit the images and styles.

<div style="margin-left: 2em;">
<code><nowiki><script></nowiki></code> 
  <code><nowiki>function showIframe() {</nowiki></code> 
    <code><nowiki>document.getElementById('runImage').style.display = 'none';</nowiki></code> 
    <code><nowiki>const container = document.getElementById('container');</nowiki></code> 
    <code><nowiki>const interactButton = document.getElementById('interactButton');</nowiki></code> 

    <code><nowiki>// Hide the "Interact" button if present</nowiki></code> 
    <code><nowiki>if (interactButton) {</nowiki></code> 
      <code><nowiki>interactButton.style.display = 'none';</nowiki></code> 
    <code><nowiki>}</nowiki></code> 

    <code><nowiki>// Check if iframe is already present</nowiki></code> 
    <code><nowiki>let iframe = document.getElementById('embeddedIframe');</nowiki></code> 
    <code><nowiki>if (!iframe) {</nowiki></code> 
      <code><nowiki>iframe = document.createElement('iframe');</nowiki></code> 
      <code><nowiki>iframe.id = 'embeddedIframe';</nowiki></code> 
      <code><nowiki>iframe.src = 'https://acp.analytica.com/view0?invite=4314&code=2462049136540573676';</nowiki></code> 
      <code><nowiki>iframe.style.width = '1210px';</nowiki></code> 
      <code><nowiki>iframe.style.height = '600px';</nowiki></code> 
      <code><nowiki>iframe.style.border = 'none';</nowiki></code> 
      <code><nowiki>container.appendChild(iframe);</nowiki></code> 
    <code><nowiki>}</nowiki></code> 
    <code><nowiki>iframe.style.display = 'block';</nowiki></code> 

    <code><nowiki>// Ensure maximize button is displayed</nowiki></code> 
    <code><nowiki>let maximizeButton = document.getElementById('maximizeButton');</nowiki></code> 
    <code><nowiki>if (!maximizeButton) {</nowiki></code> 
      <code><nowiki>maximizeButton = document.createElement('button');</nowiki></code> 
      <code><nowiki>maximizeButton.id = 'maximizeButton';</nowiki></code> 
      <code><nowiki>maximizeButton.title = 'Click to use full screen';</nowiki></code> 
      <code><nowiki>maximizeButton.style.position = 'absolute';</nowiki></code> 
      <code><nowiki>maximizeButton.style.bottom = '10px';</nowiki></code> 
      <code><nowiki>maximizeButton.style.right = '110px';</nowiki></code> 
      <code><nowiki>maximizeButton.style.background = 'transparent';</nowiki></code> 
      <code><nowiki>maximizeButton.style.border = 'none';</nowiki></code> 
      <code><nowiki>maximizeButton.style.cursor = 'pointer';</nowiki></code> 
      <code><nowiki>maximizeButton.style.width = '30px';</nowiki></code> 
      <code><nowiki>maximizeButton.style.height = '30px';</nowiki></code> 
      <code><nowiki>maximizeButton.style.backgroundImage = 'url("https://analytica.com/wp-content/uploads/2024/11/arrows-maximize.png")';</nowiki></code> 
      <code><nowiki>maximizeButton.style.backgroundSize = 'contain';</nowiki></code> 
      <code><nowiki>maximizeButton.style.backgroundRepeat = 'no-repeat';</nowiki></code> 
      <code><nowiki>maximizeButton.onclick = function() {</nowiki></code> 
        <code><nowiki>container.requestFullscreen();</nowiki></code> 
        <code><nowiki>iframe.style.width = "100%";</nowiki></code> 
        <code><nowiki>iframe.style.height = "100%";</nowiki></code> 
        <code><nowiki>maximizeButton.style.display = 'none';</nowiki></code> 
        <code><nowiki>minimizeButton.style.display = 'block';</nowiki></code> 
      <code><nowiki>};</nowiki></code> 
      <code><nowiki>container.appendChild(maximizeButton);</nowiki></code> 
    <code><nowiki>}</nowiki></code> 
    <code><nowiki>// Ensure minimize button is created</nowiki></code> 
    <code><nowiki>let minimizeButton = document.getElementById('minimizeButton');</nowiki></code> 
    <code><nowiki>if (!minimizeButton) {</nowiki></code> 
      <code><nowiki>minimizeButton = document.createElement('button');</nowiki></code> 
      <code><nowiki>minimizeButton.id = 'minimizeButton';</nowiki></code> 
      <code><nowiki>minimizeButton.title = 'Exit full screen';</nowiki></code> 
      <code><nowiki>minimizeButton.style.position = 'fixed';</nowiki></code> 
      <code><nowiki>minimizeButton.style.bottom = '10px';</nowiki></code> 
      <code><nowiki>minimizeButton.style.right = '110px';</nowiki></code> 
      <code><nowiki>minimizeButton.style.background = 'transparent';</nowiki></code> 
      <code><nowiki>minimizeButton.style.border = 'none';</nowiki></code> 
      <code><nowiki>minimizeButton.style.cursor = 'pointer';</nowiki></code> 
      <code><nowiki>minimizeButton.style.width = '30px';</nowiki></code> 
      <code><nowiki>minimizeButton.style.height = '30px';</nowiki></code> 
      <code><nowiki>minimizeButton.style.backgroundImage = 'url("https://analytica.com/wp-content/uploads/2024/11/arrows-minimize.png")';</nowiki></code> 
      <code><nowiki>minimizeButton.style.backgroundSize = 'contain';</nowiki></code> 
      <code><nowiki>minimizeButton.style.backgroundRepeat = 'no-repeat';</nowiki></code> 
      <code><nowiki>minimizeButton.style.display = 'none'; // Hidden initially</nowiki></code> 
      <code><nowiki>minimizeButton.onclick = function() {</nowiki></code> 
        <code><nowiki>document.exitFullscreen();</nowiki></code> 
        <code><nowiki>iframe.style.width = '1210px';</nowiki></code> 
        <code><nowiki>iframe.style.height = '600px';</nowiki></code> 
      <code><nowiki>};</nowiki></code> 
      <code><nowiki>container.appendChild(minimizeButton);</nowiki></code> 
    <code><nowiki>}</nowiki></code> 
  <code><nowiki>}</nowiki></code> 

  <code><nowiki>// Event listener to handle fullscreen changes</nowiki></code> 
  <code><nowiki>document.addEventListener('fullscreenchange', function() {</nowiki></code> 
    <code><nowiki>const maximizeButton = document.getElementById('maximizeButton');</nowiki></code> 
    <code><nowiki>const minimizeButton = document.getElementById('minimizeButton');</nowiki></code> 
    <code><nowiki>const iframe = document.getElementById('embeddedIframe');</nowiki></code> 

    <code><nowiki>// Check if in fullscreen mode</nowiki></code> 
    <code><nowiki>if (document.fullscreenElement) {</nowiki></code> 
      <code><nowiki>if (maximizeButton) maximizeButton.style.display = 'none';</nowiki></code> 
      <code><nowiki>if (minimizeButton) minimizeButton.style.display = 'block';</nowiki></code> 
    <code><nowiki>} else {</nowiki></code> 
      <code><nowiki>if (maximizeButton) maximizeButton.style.display = 'block';</nowiki></code> 
      <code><nowiki>if (minimizeButton) minimizeButton.style.display = 'none';</nowiki></code> 
      <code><nowiki>// Restore iframe size when exiting fullscreen</nowiki></code> 
      <code><nowiki>iframe.style.width = '1210px';</nowiki></code> 
      <code><nowiki>iframe.style.height = '600px';</nowiki></code> 
    <code><nowiki>}</nowiki></code> 
  <code><nowiki>});</nowiki></code> 

  <code><nowiki>// Create the "Click to interact" button</nowiki></code> 
  <code><nowiki>document.addEventListener('DOMContentLoaded', function() {</nowiki></code> 
    <code><nowiki>const container = document.getElementById('container');</nowiki></code> 
    <code><nowiki>const interactButton = document.createElement('button');</nowiki></code> 
    <code><nowiki>interactButton.id = 'interactButton';</nowiki></code> 
    <code><nowiki>interactButton.textContent = "Click to interact with the model in Analytica Cloud Platform";</nowiki></code> 
    <code><nowiki>interactButton.style.position = 'absolute';</nowiki></code> 
    <code><nowiki>interactButton.style.bottom = '13px';</nowiki></code> 
    <code><nowiki>interactButton.style.right = '140px';</nowiki></code> 
    <code><nowiki>interactButton.style.padding = '5px 10px';</nowiki></code> 
    <code><nowiki>interactButton.style.fontSize = '16px';</nowiki></code> 
    <code><nowiki>interactButton.style.fontWeight = 'bold';</nowiki></code> 
    <code><nowiki>interactButton.style.backgroundColor = '#d3d3d3';</nowiki></code> 
    <code><nowiki>interactButton.style.color = 'black';</nowiki></code> 
    <code><nowiki>interactButton.style.border = 'none';</nowiki></code> 
    <code><nowiki>interactButton.style.borderRadius = '5px';</nowiki></code> 
    <code><nowiki>interactButton.style.cursor = 'pointer';</nowiki></code> 
    <code><nowiki>interactButton.style.opacity = '0.9';</nowiki></code> 

    <code><nowiki>interactButton.onclick = function(event) {</nowiki></code> 
      <code><nowiki>event.stopPropagation();</nowiki></code> 
      <code><nowiki>showIframe();</nowiki></code> 
    <code><nowiki>};</nowiki></code> 
    <code><nowiki>container.appendChild(interactButton);</nowiki></code> 
  <code><nowiki>});</nowiki></code> 
<code><nowiki></script></nowiki></code> 
 
<code><nowiki><div id="container" class="screenshot-border" style="position: relative; width: 100%; height: auto;"></nowiki></code> 
  <code><nowiki><img id="runImage" src="https://analytica.com/wp-content/uploads/2023/07/ev-vs-ice-1.webp" width="1210px" height="648px" onclick="showIframe()" style="cursor: pointer;"></nowiki></code> 
<code><nowiki></div></nowiki></code>
</div>



==See Also==
* [[Analytica Cloud Player]]
* [[Example Models]]
* [[Tutorial: Sharing a model with ACP]]
* [[Model Licensing]]

Embed an ACP model in a Web Page

2024-11-19T00:59:25Z

Max: /* Add a Full screen button and minimize button to the Iframe */

[[Category: Analytica Cloud Platform]]
[[Category: Models]]

[[Analytica_Cloud_Platform|<<back]]

==Overview==
People normally view [[Analytica Cloud Platform]] (ACP) models on an acp server such as [https://ACP.Analytica.com https://ACP.Analytica.com]. However, you can also embed an ACP model in any web page, for example on your own web site, to make it more easily accessible to end users. When you do this, your users see the ACP model as a region in an iFrame within your HTML content, although the model is actually being run on the ACP server.

This page explains how to configure your own web page to display an ACP model.

'''Prerequisite:''' You must already have an ACP account, which you do if you have a subscription to any desktop Edition of Analytica.

The model will appear and use an ACP session credit whenever a user visits the web page. You can avoid this (and the time delay while the ACP model loads) by hiding the model behind a screenshot of the ACP mode. You can add code to start the model and use a session credit only when a user clicks the screenshot.

==Showing your model in an inline Frame (Iframe)==
An inline frame is just an HTML document embedded inside another HTML document on a website.

=== Step 1: Create a Web page. ===
To keep it simple, let’s say you just want to display an ACP model in an otherwise empty web page, in an Iframe. We’ll show you an example of how to do this, and hopefully that’s enough for you to get started on playing your own model within a web page on your web site.

In this example, there are two servers.
*Your Server, the server where your web site resides. This is the server you are able to upload and edit pages on.
*And there’s ACP’s server, https://acp.analytica.com, which hosts ACP and will contain the web page that plays your model. ''Since this page is an HTML frame, it will appear the model is being played on your web site.''

#First, create a web page - you can use a text editor. Here is one that just contains a title, 'Look at My Analytica Model'. Save this as an html file ACPIframe.html.

<div style="margin-left: 2em;">
<code><nowiki><html></nowiki></code> 
<code><nowiki><head></nowiki></code> 
  <code><nowiki><title>Look at My Analytica Model</title></nowiki></code> 
<code><nowiki></head></nowiki></code> 
<code><nowiki><body></nowiki></code> 
  <code><nowiki><h1>Look at My Analytica Model</h1></nowiki></code> 
<code><nowiki></body></nowiki></code> 
<code><nowiki></html></nowiki></code>
</div>

When opened in the Chrome browser this is what this web page initially displays :

:[[File:ACPIFrame01.png]]

=== Step 2 - Creating the Link to Play Your Model ===
Use ACP’s Email Invite functionality to create the link which will play your model.

#[https://acp.analytica.com/ Sign into your ACP account]
#If your model doesn't already use [[ACP_Auto_zoom|Auto Zoom]] style that will make the ACP zoom to fit the Iframe, you should make it do so. Click the model to open it in ACP, select ACP Style lib, and set it to Auto Zoom. Then save the model.
#Click a radio button to select your model -- in this example. the Project portfolio planner.ana.
#:[[File:ACPFrame01.png|720px|thumb|left]]
#Click the '''Email Invite''' button to show the email invitation dialog:
#Copy the link from this email invite. 
#:[[File:ACPFrame02.png|720px|thumb|left]] 
#Press '''Cancel''' button, since we aren’t sending the invite to anyone.

''Note: Ensure a model you insert in a web page stays in the same ACP Model Project and folder.'' If you delete it, the web page will show an error message saying "the model can't be found".

===Step 3: Insert the code for an Iframe. ===

1. Now in the web page source Insert the code for an Iframe with the link to your model in it. 
2. Set the Iframe to be a size that looks good for your model diagram, and that fits with auto zoom. It will probably need to be tweaked later, but you can do this by playing the model in ACP, and by using developer's tools or by taking a screenshot of the model and checking the dimensions. In this case the model looks good at width: 900px; height: 446px. 
3. Add Iframe html tags and paste the link for your model into the "src" attribute, and the code for ACPIframe.html will look like this: 

<div style="margin-left: 2em;">
<code><nowiki><html></nowiki></code> 
<code><nowiki><head></nowiki></code> 
  <code><nowiki><title>Look at My Analytica Model</title></nowiki></code> 
<code><nowiki></head></nowiki></code> 
<code><nowiki><body></nowiki></code> 
  <code><nowiki><h1>Look at My Analytica Model</h1></nowiki></code> 
  <code><nowiki><iframe width="900" height="446" src="https://acp.analytica.com/view?invite=4771&code=2359748081441958275"></iframe></nowiki></code> 
<code><nowiki></body></nowiki></code> 
<code><nowiki></html></nowiki></code>
</div>

4. Now you can save the web page and load it in a browser. Or you can see it on the Analytica docs server here: [https://docs.analytica.com/custom_pages/ACPIframe.html https://docs.analytica.com/custom_pages/ACPIframe.html]
It will display the model in the iframe like this:
:[[File:ACPIFrame02.png|720px|thumb|left]]
Download the example html [[File:ACPIframe.zip]].


==Put an ACP model behind an image==
To avoid the ACP model loading each time the page is visited, you can hide the model behind an image, and add code to start the model when the image is clicked like a button.

'''Tip:''' To save time and get the screen shots to paste into an editor at close to the same size as what you are seeing in the browser, you may want to adjust your display settings to 100%.

1. Make a display image to put over the iframe when ACP is not running the model. Here is one way to do this:
a. Enter the source url from the html into the address bar for Chrome. Then with the browser unmaximized, adjust the window size until it looks good and the zoom fits the diagram. Using developer's tools elements tab I can see the model diagram looks pretty good at 900px wide; 447px height;.[[File:ACPIFrame05.png|720px|thumb|left]]
b. Take a screenshot, crop it to remove all but the model and the top bar and save the image.
[[File:ACPIFrame06.png|720px|thumb|left]]
2. Save the image where it is accessible to the javascript - for instance, in the same folder or in an uploads directory. 
3. Add a div in the html source containing the container with the display image. And the script following.
<div style="margin-left: 2em;">
<code><nowiki><html></nowiki></code> 
<code><nowiki><head></nowiki></code> 
  <code><nowiki><title>Look at My Analytica Model</title></nowiki></code> 
<code><nowiki></head></nowiki></code> 
<code><nowiki><body></nowiki></code> 
  <code><nowiki><h1>Look at My Analytica Model</h1></nowiki></code> 
  <code><nowiki><div id="container" style="cursor: pointer; border: 1px solid #ccc; padding: 10px; margin: 10px; width: 900px; height: 447px;"></nowiki></code> 
    <code><nowiki><img id="runImage" src="ACPIframe02.png" style="width: 100%; height: 100%;"></nowiki></code> 
  <code><nowiki></div></nowiki></code> 
  <code><nowiki><script></nowiki></code> 
    <code><nowiki>document.addEventListener('DOMContentLoaded', function () {</nowiki></code> 
      <code><nowiki>function showIframe() {</nowiki></code> 
        <code><nowiki>// Hide the image</nowiki></code> 
        <code><nowiki>document.getElementById('runImage').style.display = 'none';</nowiki></code> 
        <code><nowiki>// Create and configure the iframe</nowiki></code> 
        <code><nowiki>const iframe = document.createElement('iframe');</nowiki></code> 
        <code><nowiki>iframe.src = 'https://acp.analytica.com/view?invite=4714&code=4200729999208732852';</nowiki></code> 
        <code><nowiki>iframe.style.width = '900px';</nowiki></code> 
        <code><nowiki>iframe.style.height = '446px';</nowiki></code> 
        <code><nowiki>iframe.style.border = 'none';</nowiki></code> 

        <code><nowiki>// Append the iframe to the container</nowiki></code> 
        <code><nowiki>document.getElementById('container').appendChild(iframe);</nowiki></code> 
      <code><nowiki>}</nowiki></code> 

      <code><nowiki>// Add click event listener to the image container</nowiki></code> 
      <code><nowiki>document.getElementById('container').addEventListener('click', showIframe);</nowiki></code> 
    <code><nowiki>});</nowiki></code> 
  <code><nowiki></script></nowiki></code> 
<code><nowiki></body></nowiki></code> 
<code><nowiki></html></nowiki></code>
</div>

Download the example html file and image [[File:ACPIModelBehindImage.zip]]

You can see what this page looks like here: [https://docs.analytica.com/custom_pages/ACPModelBehindIframe.html https://docs.analytica.com/custom_pages/ACPModelBehindIframe.html]

== Buttons to expand to full screen and minimize==

It's convenient for users to be able to expand an embedded ACP window to the full browser window -- and to minimize it again. Here's a live example: [[https://docs.analytica.com/custom_pages/ACPIframeInteract.html https://docs.analytica.com/custom_pages/ACPIframeInteract.html]
Here is how to add
* a maximize button [[File:Arrows-maximize.png|24px]] to show the Iframe fullscreen - visible in the Iframe when the model is running at normal size.
* a minimize button [[File:Arrows-minimize.png|24px]] to exitfull screen visible when the Iframe is full screen.
* a button on the Iframe labeled "click to interact with the model in Analytica Cloud Platform" to clarify that you need to click it to start the model in ACP.
* Some styling with a 1 pixel wide outline and a drop shadow. You can set these in a css file too.
* The fullscreen and minimize icons from the docs.analytica.com wiki - just use links to them for now.

Here is an example html file with the code to add these extra features, using the same overlay image as before: [[File:ACPIframeInteract.zip]]

Here is some updated html and script.
<div style="margin-left: 2em;">
<code><nowiki><!DOCTYPE html></nowiki></code> 
<code><nowiki><html></nowiki></code> 
<code><nowiki><head></nowiki></code> 
  <code><nowiki><title>Interactive Analytica Model</title></nowiki></code> 
  <code><nowiki><style></nowiki></code> 
    <code><nowiki>#container {</nowiki></code> 
      <code><nowiki>position: relative;</nowiki></code> 
      <code><nowiki>cursor: pointer;</nowiki></code> 
      <code><nowiki>width: 900px;</nowiki></code> 
      <code><nowiki>height: 447px;</nowiki></code> 
      <code><nowiki>margin: 0 auto;</nowiki></code> 
      <code><nowiki>border: 1px solid #ccc;</nowiki></code> 
      <code><nowiki>box-shadow: 0 4px 8px rgba(0, 0, 0, 0.2);</nowiki></code> 
    <code><nowiki>}</nowiki></code> 
    <code><nowiki>#runImage {</nowiki></code> 
      <code><nowiki>width: 100%;</nowiki></code> 
      <code><nowiki>height: 100%;</nowiki></code> 
      <code><nowiki>display: block;</nowiki></code> 
    <code><nowiki>}</nowiki></code> 
    <code><nowiki>.control-button {</nowiki></code> 
      <code><nowiki>position: absolute;</nowiki></code> 
      <code><nowiki>width: 30px;</nowiki></code> 
      <code><nowiki>height: 30px;</nowiki></code> 
      <code><nowiki>background-size: contain;</nowiki></code> 
      <code><nowiki>background-repeat: no-repeat;</nowiki></code> 
      <code><nowiki>background-color: transparent;</nowiki></code> 
      <code><nowiki>border: none;</nowiki></code> 
      <code><nowiki>cursor: pointer;</nowiki></code> 
    <code><nowiki>}</nowiki></code> 
    <code><nowiki>#maximizeButton {</nowiki></code> 
      <code><nowiki>bottom: 10px;</nowiki></code> 
      <code><nowiki>right: 120px;</nowiki></code> 
      <code><nowiki>background-image: url("https://docs.analytica.com/images/9/9c/Arrows-maximize.png");</nowiki></code> 
      <code><nowiki>display: none;</nowiki></code> 
    <code><nowiki>}</nowiki></code> 
    <code><nowiki>#minimizeButton {</nowiki></code> 
      <code><nowiki>bottom: 10px;</nowiki></code> 
      <code><nowiki>right: 120px;</nowiki></code> 
      <code><nowiki>background-image: url("https://docs.analytica.com/images/8/82/Arrows-minimize.png");</nowiki></code> 
      <code><nowiki>display: none;</nowiki></code> 
    <code><nowiki>}</nowiki></code> 
    <code><nowiki>#interactButton {</nowiki></code> 
      <code><nowiki>position: absolute;</nowiki></code> 
      <code><nowiki>bottom: 10px;</nowiki></code> 
      <code><nowiki>right: 120px;</nowiki></code> 
      <code><nowiki>padding: 5px 10px;</nowiki></code> 
      <code><nowiki>font-size: 16px;</nowiki></code> 
      <code><nowiki>font-weight: bold;</nowiki></code> 
      <code><nowiki>background-color: #e4e4e4;</nowiki></code> 
      <code><nowiki>color: black;</nowiki></code> 
      <code><nowiki>border: none;</nowiki></code> 
      <code><nowiki>border-radius: 5px;</nowiki></code> 
      <code><nowiki>cursor: pointer;</nowiki></code> 
      <code><nowiki>opacity: 0.9;</nowiki></code> 
      <code><nowiki>display: inline-block;</nowiki></code> 
    <code><nowiki>}</nowiki></code> 
  <code><nowiki></style></nowiki></code> 
<code><nowiki></head></nowiki></code> 
<code><nowiki><body></nowiki></code> 
  <code><nowiki><div id="container"></nowiki></code> 
    <code><nowiki><img id="runImage" src="ACPIframe02.png"></nowiki></code> 
    <code><nowiki><button id="maximizeButton" class="control-button" title="Click to use full screen"></button></nowiki></code> 
    <code><nowiki><button id="minimizeButton" class="control-button" title="Exit full screen"></button></nowiki></code> 
    <code><nowiki><button id="interactButton">Click to interact with the model in Analytica Cloud Platform</button></nowiki></code> 
  <code><nowiki></div></nowiki></code> 
</div>
<div style="margin-left: 2em;">
<code><nowiki><script></nowiki></code> 
  <code><nowiki>document.addEventListener('DOMContentLoaded', function () {</nowiki></code> 
    <code><nowiki>let iframeAdded = false;</nowiki></code> 
    <code><nowiki>const container = document.getElementById('container');</nowiki></code> 
    <code><nowiki>const runImage = document.getElementById('runImage');</nowiki></code> 
    <code><nowiki>const maximizeButton = document.getElementById('maximizeButton');</nowiki></code> 
    <code><nowiki>const minimizeButton = document.getElementById('minimizeButton');</nowiki></code> 
    <code><nowiki>const interactButton = document.getElementById('interactButton');</nowiki></code> 
    <code><nowiki>function showIframe() {</nowiki></code> 
      <code><nowiki>runImage.style.display = 'none';</nowiki></code> 
      <code><nowiki>interactButton.style.display = 'none';</nowiki></code> 
      <code><nowiki>if (!iframeAdded) {</nowiki></code> 
        <code><nowiki>const iframe = document.createElement('iframe');</nowiki></code> 
        <code><nowiki>iframe.src = 'https://acp.analytica.com/view?invite=4771&code=2359748081441958275';</nowiki></code> 
        <code><nowiki>iframe.style.width = '100%';</nowiki></code> 
        <code><nowiki>iframe.style.height = '100%';</nowiki></code> 
        <code><nowiki>iframe.style.border = 'none';</nowiki></code> 
        <code><nowiki>container.appendChild(iframe);</nowiki></code> 
        <code><nowiki>iframeAdded = true;</nowiki></code> 
        <code><nowiki>maximizeButton.style.display = 'inline-block';</nowiki></code> 
      <code><nowiki>}</nowiki></code> 
    <code><nowiki>}</nowiki></code> 
    <code><nowiki>function maximizeIframe() {</nowiki></code> 
      <code><nowiki>if (container.requestFullscreen) {</nowiki></code> 
        <code><nowiki>container.requestFullscreen();</nowiki></code> 
      <code><nowiki>} else if (container.webkitRequestFullscreen) {</nowiki></code> 
        <code><nowiki>container.webkitRequestFullscreen();</nowiki></code> 
      <code><nowiki>} else if (container.msRequestFullscreen) {</nowiki></code> 
        <code><nowiki>container.msRequestFullscreen();</nowiki></code> 
      <code><nowiki>}</nowiki></code> 
      <code><nowiki>maximizeButton.style.display = 'none';</nowiki></code> 
      <code><nowiki>minimizeButton.style.display = 'inline-block';</nowiki></code> 
    <code><nowiki>}</nowiki></code> 
    <code><nowiki>function minimizeIframe() {</nowiki></code> 
      <code><nowiki>if (document.exitFullscreen) {</nowiki></code> 
        <code><nowiki>document.exitFullscreen();</nowiki></code> 
      <code><nowiki>} else if (document.webkitExitFullscreen) {</nowiki></code> 
        <code><nowiki>document.webkitExitFullscreen();</nowiki></code> 
      <code><nowiki>} else if (document.msExitFullscreen) {</nowiki></code> 
        <code><nowiki>document.msExitFullscreen();</nowiki></code> 
      <code><nowiki>}</nowiki></code> 
      <code><nowiki>maximizeButton.style.display = 'inline-block';</nowiki></code> 
      <code><nowiki>minimizeButton.style.display = 'none';</nowiki></code> 
    <code><nowiki>}</nowiki></code> 
    <code><nowiki>interactButton.addEventListener('click', function (event) {</nowiki></code> 
      <code><nowiki>event.stopPropagation();</nowiki></code> 
      <code><nowiki>showIframe();</nowiki></code> 
    <code><nowiki>});</nowiki></code> 
    <code><nowiki>maximizeButton.addEventListener('click', function (event) {</nowiki></code> 
      <code><nowiki>event.stopPropagation();</nowiki></code> 
      <code><nowiki>maximizeIframe();</nowiki></code> 
    <code><nowiki>});</nowiki></code> 
    <code><nowiki>minimizeButton.addEventListener('click', function (event) {</nowiki></code> 
      <code><nowiki>event.stopPropagation();</nowiki></code> 
      <code><nowiki>minimizeIframe();</nowiki></code> 
    <code><nowiki>});</nowiki></code> 
    <code><nowiki>container.addEventListener('click', showIframe);</nowiki></code> 
  <code><nowiki>});</nowiki></code> 
<code><nowiki></script></nowiki></code> 
<code><nowiki></body></nowiki></code> 
<code><nowiki></html></nowiki></code>
</div>

==ACP in an Iframe on a wiki==
*Putting html or javascript into a mediawiki page is generally not supported directly.
*You can run the code in a widget. To do this you need to install the widget extension, then save the code as a widget page and put the widget into your mediawiki page..
*Here is an example page on the Analytica docs which uses a widget file to run the same model. [https://docs.analytica.com/index.php/Testiframe https://docs.analytica.com/index.php/Testiframe].
*You can inspect this code by navigating to the page and selecting <code>This page > show source</code>.
*You can also navigate to the widget page and view the source: [https://docs.analytica.com/index.php/Widget:Ppplanner05 https://docs.analytica.com/index.php/Widget:Ppplanner05].

==ACP in an Iframe on a wordpress site==
Running live on this page: [https://analytica.com/acpiframeminmax/ https://analytica.com/acpiframeminmax/]
To add an iframe running an ACP model on an Elementor page:
*Upload images needed to your wordpress site and note the location and urls.
*Click edit with Elementor.
*Add a new section then drag an HTML widget onto the section.
* In the code block for the HTML widget enter the code for your overlay image and for your iframe.
**Here is the code for this Iframe: you would need to edit the images and styles.

<div style="margin-left: 2em;">
<code><nowiki><script></nowiki></code> 
  <code><nowiki>function showIframe() {</nowiki></code> 
    <code><nowiki>document.getElementById('runImage').style.display = 'none';</nowiki></code> 
    <code><nowiki>const container = document.getElementById('container');</nowiki></code> 
    <code><nowiki>const interactButton = document.getElementById('interactButton');</nowiki></code> 

    <code><nowiki>// Hide the "Interact" button if present</nowiki></code> 
    <code><nowiki>if (interactButton) {</nowiki></code> 
      <code><nowiki>interactButton.style.display = 'none';</nowiki></code> 
    <code><nowiki>}</nowiki></code> 

    <code><nowiki>// Check if iframe is already present</nowiki></code> 
    <code><nowiki>let iframe = document.getElementById('embeddedIframe');</nowiki></code> 
    <code><nowiki>if (!iframe) {</nowiki></code> 
      <code><nowiki>iframe = document.createElement('iframe');</nowiki></code> 
      <code><nowiki>iframe.id = 'embeddedIframe';</nowiki></code> 
      <code><nowiki>iframe.src = 'https://acp.analytica.com/view0?invite=4314&code=2462049136540573676';</nowiki></code> 
      <code><nowiki>iframe.style.width = '1210px';</nowiki></code> 
      <code><nowiki>iframe.style.height = '600px';</nowiki></code> 
      <code><nowiki>iframe.style.border = 'none';</nowiki></code> 
      <code><nowiki>container.appendChild(iframe);</nowiki></code> 
    <code><nowiki>}</nowiki></code> 
    <code><nowiki>iframe.style.display = 'block';</nowiki></code> 

    <code><nowiki>// Ensure maximize button is displayed</nowiki></code> 
    <code><nowiki>let maximizeButton = document.getElementById('maximizeButton');</nowiki></code> 
    <code><nowiki>if (!maximizeButton) {</nowiki></code> 
      <code><nowiki>maximizeButton = document.createElement('button');</nowiki></code> 
      <code><nowiki>maximizeButton.id = 'maximizeButton';</nowiki></code> 
      <code><nowiki>maximizeButton.title = 'Click to use full screen';</nowiki></code> 
      <code><nowiki>maximizeButton.style.position = 'absolute';</nowiki></code> 
      <code><nowiki>maximizeButton.style.bottom = '10px';</nowiki></code> 
      <code><nowiki>maximizeButton.style.right = '110px';</nowiki></code> 
      <code><nowiki>maximizeButton.style.background = 'transparent';</nowiki></code> 
      <code><nowiki>maximizeButton.style.border = 'none';</nowiki></code> 
      <code><nowiki>maximizeButton.style.cursor = 'pointer';</nowiki></code> 
      <code><nowiki>maximizeButton.style.width = '30px';</nowiki></code> 
      <code><nowiki>maximizeButton.style.height = '30px';</nowiki></code> 
      <code><nowiki>maximizeButton.style.backgroundImage = 'url("https://analytica.com/wp-content/uploads/2024/11/arrows-maximize.png")';</nowiki></code> 
      <code><nowiki>maximizeButton.style.backgroundSize = 'contain';</nowiki></code> 
      <code><nowiki>maximizeButton.style.backgroundRepeat = 'no-repeat';</nowiki></code> 
      <code><nowiki>maximizeButton.onclick = function() {</nowiki></code> 
        <code><nowiki>container.requestFullscreen();</nowiki></code> 
        <code><nowiki>iframe.style.width = "100%";</nowiki></code> 
        <code><nowiki>iframe.style.height = "100%";</nowiki></code> 
        <code><nowiki>maximizeButton.style.display = 'none';</nowiki></code> 
        <code><nowiki>minimizeButton.style.display = 'block';</nowiki></code> 
      <code><nowiki>};</nowiki></code> 
      <code><nowiki>container.appendChild(maximizeButton);</nowiki></code> 
    <code><nowiki>}</nowiki></code> 
    <code><nowiki>// Ensure minimize button is created</nowiki></code> 
    <code><nowiki>let minimizeButton = document.getElementById('minimizeButton');</nowiki></code> 
    <code><nowiki>if (!minimizeButton) {</nowiki></code> 
      <code><nowiki>minimizeButton = document.createElement('button');</nowiki></code> 
      <code><nowiki>minimizeButton.id = 'minimizeButton';</nowiki></code> 
      <code><nowiki>minimizeButton.title = 'Exit full screen';</nowiki></code> 
      <code><nowiki>minimizeButton.style.position = 'fixed';</nowiki></code> 
      <code><nowiki>minimizeButton.style.bottom = '10px';</nowiki></code> 
      <code><nowiki>minimizeButton.style.right = '110px';</nowiki></code> 
      <code><nowiki>minimizeButton.style.background = 'transparent';</nowiki></code> 
      <code><nowiki>minimizeButton.style.border = 'none';</nowiki></code> 
      <code><nowiki>minimizeButton.style.cursor = 'pointer';</nowiki></code> 
      <code><nowiki>minimizeButton.style.width = '30px';</nowiki></code> 
      <code><nowiki>minimizeButton.style.height = '30px';</nowiki></code> 
      <code><nowiki>minimizeButton.style.backgroundImage = 'url("https://analytica.com/wp-content/uploads/2024/11/arrows-minimize.png")';</nowiki></code> 
      <code><nowiki>minimizeButton.style.backgroundSize = 'contain';</nowiki></code> 
      <code><nowiki>minimizeButton.style.backgroundRepeat = 'no-repeat';</nowiki></code> 
      <code><nowiki>minimizeButton.style.display = 'none'; // Hidden initially</nowiki></code> 
      <code><nowiki>minimizeButton.onclick = function() {</nowiki></code> 
        <code><nowiki>document.exitFullscreen();</nowiki></code> 
        <code><nowiki>iframe.style.width = '1210px';</nowiki></code> 
        <code><nowiki>iframe.style.height = '600px';</nowiki></code> 
      <code><nowiki>};</nowiki></code> 
      <code><nowiki>container.appendChild(minimizeButton);</nowiki></code> 
    <code><nowiki>}</nowiki></code> 
  <code><nowiki>}</nowiki></code> 

  <code><nowiki>// Event listener to handle fullscreen changes</nowiki></code> 
  <code><nowiki>document.addEventListener('fullscreenchange', function() {</nowiki></code> 
    <code><nowiki>const maximizeButton = document.getElementById('maximizeButton');</nowiki></code> 
    <code><nowiki>const minimizeButton = document.getElementById('minimizeButton');</nowiki></code> 
    <code><nowiki>const iframe = document.getElementById('embeddedIframe');</nowiki></code> 

    <code><nowiki>// Check if in fullscreen mode</nowiki></code> 
    <code><nowiki>if (document.fullscreenElement) {</nowiki></code> 
      <code><nowiki>if (maximizeButton) maximizeButton.style.display = 'none';</nowiki></code> 
      <code><nowiki>if (minimizeButton) minimizeButton.style.display = 'block';</nowiki></code> 
    <code><nowiki>} else {</nowiki></code> 
      <code><nowiki>if (maximizeButton) maximizeButton.style.display = 'block';</nowiki></code> 
      <code><nowiki>if (minimizeButton) minimizeButton.style.display = 'none';</nowiki></code> 
      <code><nowiki>// Restore iframe size when exiting fullscreen</nowiki></code> 
      <code><nowiki>iframe.style.width = '1210px';</nowiki></code> 
      <code><nowiki>iframe.style.height = '600px';</nowiki></code> 
    <code><nowiki>}</nowiki></code> 
  <code><nowiki>});</nowiki></code> 

  <code><nowiki>// Create the "Click to interact" button</nowiki></code> 
  <code><nowiki>document.addEventListener('DOMContentLoaded', function() {</nowiki></code> 
    <code><nowiki>const container = document.getElementById('container');</nowiki></code> 
    <code><nowiki>const interactButton = document.createElement('button');</nowiki></code> 
    <code><nowiki>interactButton.id = 'interactButton';</nowiki></code> 
    <code><nowiki>interactButton.textContent = "Click to interact with the model in Analytica Cloud Platform";</nowiki></code> 
    <code><nowiki>interactButton.style.position = 'absolute';</nowiki></code> 
    <code><nowiki>interactButton.style.bottom = '13px';</nowiki></code> 
    <code><nowiki>interactButton.style.right = '140px';</nowiki></code> 
    <code><nowiki>interactButton.style.padding = '5px 10px';</nowiki></code> 
    <code><nowiki>interactButton.style.fontSize = '16px';</nowiki></code> 
    <code><nowiki>interactButton.style.fontWeight = 'bold';</nowiki></code> 
    <code><nowiki>interactButton.style.backgroundColor = '#d3d3d3';</nowiki></code> 
    <code><nowiki>interactButton.style.color = 'black';</nowiki></code> 
    <code><nowiki>interactButton.style.border = 'none';</nowiki></code> 
    <code><nowiki>interactButton.style.borderRadius = '5px';</nowiki></code> 
    <code><nowiki>interactButton.style.cursor = 'pointer';</nowiki></code> 
    <code><nowiki>interactButton.style.opacity = '0.9';</nowiki></code> 

    <code><nowiki>interactButton.onclick = function(event) {</nowiki></code> 
      <code><nowiki>event.stopPropagation();</nowiki></code> 
      <code><nowiki>showIframe();</nowiki></code> 
    <code><nowiki>};</nowiki></code> 
    <code><nowiki>container.appendChild(interactButton);</nowiki></code> 
  <code><nowiki>});</nowiki></code> 
<code><nowiki></script></nowiki></code> 
 
<code><nowiki><div id="container" class="screenshot-border" style="position: relative; width: 100%; height: auto;"></nowiki></code> 
  <code><nowiki><img id="runImage" src="https://analytica.com/wp-content/uploads/2023/07/ev-vs-ice-1.webp" width="1210px" height="648px" onclick="showIframe()" style="cursor: pointer;"></nowiki></code> 
<code><nowiki></div></nowiki></code>
</div>



==See Also==
* [[Analytica Cloud Player]]
* [[Example Models]]
* [[Tutorial: Sharing a model with ACP]]
* [[Model Licensing]]

Embed an ACP model in a Web Page

2024-11-19T00:47:57Z

Max: /* Overview */

[[Category: Analytica Cloud Platform]]
[[Category: Models]]

[[Analytica_Cloud_Platform|<<back]]

==Overview==
People normally view [[Analytica Cloud Platform]] (ACP) models on an acp server such as [https://ACP.Analytica.com https://ACP.Analytica.com]. However, you can also embed an ACP model in any web page, for example on your own web site, to make it more easily accessible to end users. When you do this, your users see the ACP model as a region in an iFrame within your HTML content, although the model is actually being run on the ACP server.

This page explains how to configure your own web page to display an ACP model.

'''Prerequisite:''' You must already have an ACP account, which you do if you have a subscription to any desktop Edition of Analytica.

The model will appear and use an ACP session credit whenever a user visits the web page. You can avoid this (and the time delay while the ACP model loads) by hiding the model behind a screenshot of the ACP mode. You can add code to start the model and use a session credit only when a user clicks the screenshot.

==Showing your model in an inline Frame (Iframe)==
An inline frame is just an HTML document embedded inside another HTML document on a website.

=== Step 1: Create a Web page. ===
To keep it simple, let’s say you just want to display an ACP model in an otherwise empty web page, in an Iframe. We’ll show you an example of how to do this, and hopefully that’s enough for you to get started on playing your own model within a web page on your web site.

In this example, there are two servers.
*Your Server, the server where your web site resides. This is the server you are able to upload and edit pages on.
*And there’s ACP’s server, https://acp.analytica.com, which hosts ACP and will contain the web page that plays your model. ''Since this page is an HTML frame, it will appear the model is being played on your web site.''

#First, create a web page - you can use a text editor. Here is one that just contains a title, 'Look at My Analytica Model'. Save this as an html file ACPIframe.html.

<div style="margin-left: 2em;">
<code><nowiki><html></nowiki></code> 
<code><nowiki><head></nowiki></code> 
  <code><nowiki><title>Look at My Analytica Model</title></nowiki></code> 
<code><nowiki></head></nowiki></code> 
<code><nowiki><body></nowiki></code> 
  <code><nowiki><h1>Look at My Analytica Model</h1></nowiki></code> 
<code><nowiki></body></nowiki></code> 
<code><nowiki></html></nowiki></code>
</div>

When opened in the Chrome browser this is what this web page initially displays :

:[[File:ACPIFrame01.png]]

=== Step 2 - Creating the Link to Play Your Model ===
Use ACP’s Email Invite functionality to create the link which will play your model.

#[https://acp.analytica.com/ Sign into your ACP account]
#If your model doesn't already use [[ACP_Auto_zoom|Auto Zoom]] style that will make the ACP zoom to fit the Iframe, you should make it do so. Click the model to open it in ACP, select ACP Style lib, and set it to Auto Zoom. Then save the model.
#Click a radio button to select your model -- in this example. the Project portfolio planner.ana.
#:[[File:ACPFrame01.png|720px|thumb|left]]
#Click the '''Email Invite''' button to show the email invitation dialog:
#Copy the link from this email invite. 
#:[[File:ACPFrame02.png|720px|thumb|left]] 
#Press '''Cancel''' button, since we aren’t sending the invite to anyone.

''Note: Ensure a model you insert in a web page stays in the same ACP Model Project and folder.'' If you delete it, the web page will show an error message saying "the model can't be found".

===Step 3: Insert the code for an Iframe. ===

1. Now in the web page source Insert the code for an Iframe with the link to your model in it. 
2. Set the Iframe to be a size that looks good for your model diagram, and that fits with auto zoom. It will probably need to be tweaked later, but you can do this by playing the model in ACP, and by using developer's tools or by taking a screenshot of the model and checking the dimensions. In this case the model looks good at width: 900px; height: 446px. 
3. Add Iframe html tags and paste the link for your model into the "src" attribute, and the code for ACPIframe.html will look like this: 

<div style="margin-left: 2em;">
<code><nowiki><html></nowiki></code> 
<code><nowiki><head></nowiki></code> 
  <code><nowiki><title>Look at My Analytica Model</title></nowiki></code> 
<code><nowiki></head></nowiki></code> 
<code><nowiki><body></nowiki></code> 
  <code><nowiki><h1>Look at My Analytica Model</h1></nowiki></code> 
  <code><nowiki><iframe width="900" height="446" src="https://acp.analytica.com/view?invite=4771&code=2359748081441958275"></iframe></nowiki></code> 
<code><nowiki></body></nowiki></code> 
<code><nowiki></html></nowiki></code>
</div>

4. Now you can save the web page and load it in a browser. Or you can see it on the Analytica docs server here: [https://docs.analytica.com/custom_pages/ACPIframe.html https://docs.analytica.com/custom_pages/ACPIframe.html]
It will display the model in the iframe like this:
:[[File:ACPIFrame02.png|720px|thumb|left]]
Download the example html [[File:ACPIframe.zip]].


==Put an ACP model behind an image==
To avoid the ACP model loading each time the page is visited, you can hide the model behind an image, and add code to start the model when the image is clicked like a button.

'''Tip:''' To save time and get the screen shots to paste into an editor at close to the same size as what you are seeing in the browser, you may want to adjust your display settings to 100%.

1. Make a display image to put over the iframe when ACP is not running the model. Here is one way to do this:
a. Enter the source url from the html into the address bar for Chrome. Then with the browser unmaximized, adjust the window size until it looks good and the zoom fits the diagram. Using developer's tools elements tab I can see the model diagram looks pretty good at 900px wide; 447px height;.[[File:ACPIFrame05.png|720px|thumb|left]]
b. Take a screenshot, crop it to remove all but the model and the top bar and save the image.
[[File:ACPIFrame06.png|720px|thumb|left]]
2. Save the image where it is accessible to the javascript - for instance, in the same folder or in an uploads directory. 
3. Add a div in the html source containing the container with the display image. And the script following.
<div style="margin-left: 2em;">
<code><nowiki><html></nowiki></code> 
<code><nowiki><head></nowiki></code> 
  <code><nowiki><title>Look at My Analytica Model</title></nowiki></code> 
<code><nowiki></head></nowiki></code> 
<code><nowiki><body></nowiki></code> 
  <code><nowiki><h1>Look at My Analytica Model</h1></nowiki></code> 
  <code><nowiki><div id="container" style="cursor: pointer; border: 1px solid #ccc; padding: 10px; margin: 10px; width: 900px; height: 447px;"></nowiki></code> 
    <code><nowiki><img id="runImage" src="ACPIframe02.png" style="width: 100%; height: 100%;"></nowiki></code> 
  <code><nowiki></div></nowiki></code> 
  <code><nowiki><script></nowiki></code> 
    <code><nowiki>document.addEventListener('DOMContentLoaded', function () {</nowiki></code> 
      <code><nowiki>function showIframe() {</nowiki></code> 
        <code><nowiki>// Hide the image</nowiki></code> 
        <code><nowiki>document.getElementById('runImage').style.display = 'none';</nowiki></code> 
        <code><nowiki>// Create and configure the iframe</nowiki></code> 
        <code><nowiki>const iframe = document.createElement('iframe');</nowiki></code> 
        <code><nowiki>iframe.src = 'https://acp.analytica.com/view?invite=4714&code=4200729999208732852';</nowiki></code> 
        <code><nowiki>iframe.style.width = '900px';</nowiki></code> 
        <code><nowiki>iframe.style.height = '446px';</nowiki></code> 
        <code><nowiki>iframe.style.border = 'none';</nowiki></code> 

        <code><nowiki>// Append the iframe to the container</nowiki></code> 
        <code><nowiki>document.getElementById('container').appendChild(iframe);</nowiki></code> 
      <code><nowiki>}</nowiki></code> 

      <code><nowiki>// Add click event listener to the image container</nowiki></code> 
      <code><nowiki>document.getElementById('container').addEventListener('click', showIframe);</nowiki></code> 
    <code><nowiki>});</nowiki></code> 
  <code><nowiki></script></nowiki></code> 
<code><nowiki></body></nowiki></code> 
<code><nowiki></html></nowiki></code>
</div>

Download the example html file and image [[File:ACPIModelBehindImage.zip]]

You can see what this page looks like here: [https://docs.analytica.com/custom_pages/ACPModelBehindIframe.html https://docs.analytica.com/custom_pages/ACPModelBehindIframe.html]

==Add a Full screen button and minimize button to the Iframe==
* You can see this page live here [[https://docs.analytica.com/custom_pages/ACPIframeInteract.html https://docs.analytica.com/custom_pages/ACPIframeInteract.html]
* Here we add a button Maximize button [[File:Arrows-maximize.png|24px]] to show the Iframe fullscreen - only visible when the Iframe is showing and the model is running at normal lsize.
* Also a minimize button [[File:Arrows-minimize.png|24px]] to get out of full screen which only shows when the Iframe is full screen.
* Also add a button attached to the Iframe which shows the text "click to interact with the model in Analytica Cloud Platform" to clarify thatyou actually need to click the image (or the button) to play the model in ACP.
* Add some styling with a 1 pixel wide outline and a drop shadow. You can set these in a css file too.
* And add the fullscreen and minimize icons from the docs.analytica.com wiki - just use links to them for now.

*Here is an example html file with the code to add these extra features, using the same overlay image as before: [[File:ACPIframeInteract.zip]]

* Here is some updated html and script.
<div style="margin-left: 2em;">
<code><nowiki><!DOCTYPE html></nowiki></code> 
<code><nowiki><html></nowiki></code> 
<code><nowiki><head></nowiki></code> 
  <code><nowiki><title>Interactive Analytica Model</title></nowiki></code> 
  <code><nowiki><style></nowiki></code> 
    <code><nowiki>#container {</nowiki></code> 
      <code><nowiki>position: relative;</nowiki></code> 
      <code><nowiki>cursor: pointer;</nowiki></code> 
      <code><nowiki>width: 900px;</nowiki></code> 
      <code><nowiki>height: 447px;</nowiki></code> 
      <code><nowiki>margin: 0 auto;</nowiki></code> 
      <code><nowiki>border: 1px solid #ccc;</nowiki></code> 
      <code><nowiki>box-shadow: 0 4px 8px rgba(0, 0, 0, 0.2);</nowiki></code> 
    <code><nowiki>}</nowiki></code> 
    <code><nowiki>#runImage {</nowiki></code> 
      <code><nowiki>width: 100%;</nowiki></code> 
      <code><nowiki>height: 100%;</nowiki></code> 
      <code><nowiki>display: block;</nowiki></code> 
    <code><nowiki>}</nowiki></code> 
    <code><nowiki>.control-button {</nowiki></code> 
      <code><nowiki>position: absolute;</nowiki></code> 
      <code><nowiki>width: 30px;</nowiki></code> 
      <code><nowiki>height: 30px;</nowiki></code> 
      <code><nowiki>background-size: contain;</nowiki></code> 
      <code><nowiki>background-repeat: no-repeat;</nowiki></code> 
      <code><nowiki>background-color: transparent;</nowiki></code> 
      <code><nowiki>border: none;</nowiki></code> 
      <code><nowiki>cursor: pointer;</nowiki></code> 
    <code><nowiki>}</nowiki></code> 
    <code><nowiki>#maximizeButton {</nowiki></code> 
      <code><nowiki>bottom: 10px;</nowiki></code> 
      <code><nowiki>right: 120px;</nowiki></code> 
      <code><nowiki>background-image: url("https://docs.analytica.com/images/9/9c/Arrows-maximize.png");</nowiki></code> 
      <code><nowiki>display: none;</nowiki></code> 
    <code><nowiki>}</nowiki></code> 
    <code><nowiki>#minimizeButton {</nowiki></code> 
      <code><nowiki>bottom: 10px;</nowiki></code> 
      <code><nowiki>right: 120px;</nowiki></code> 
      <code><nowiki>background-image: url("https://docs.analytica.com/images/8/82/Arrows-minimize.png");</nowiki></code> 
      <code><nowiki>display: none;</nowiki></code> 
    <code><nowiki>}</nowiki></code> 
    <code><nowiki>#interactButton {</nowiki></code> 
      <code><nowiki>position: absolute;</nowiki></code> 
      <code><nowiki>bottom: 10px;</nowiki></code> 
      <code><nowiki>right: 120px;</nowiki></code> 
      <code><nowiki>padding: 5px 10px;</nowiki></code> 
      <code><nowiki>font-size: 16px;</nowiki></code> 
      <code><nowiki>font-weight: bold;</nowiki></code> 
      <code><nowiki>background-color: #e4e4e4;</nowiki></code> 
      <code><nowiki>color: black;</nowiki></code> 
      <code><nowiki>border: none;</nowiki></code> 
      <code><nowiki>border-radius: 5px;</nowiki></code> 
      <code><nowiki>cursor: pointer;</nowiki></code> 
      <code><nowiki>opacity: 0.9;</nowiki></code> 
      <code><nowiki>display: inline-block;</nowiki></code> 
    <code><nowiki>}</nowiki></code> 
  <code><nowiki></style></nowiki></code> 
<code><nowiki></head></nowiki></code> 
<code><nowiki><body></nowiki></code> 
  <code><nowiki><div id="container"></nowiki></code> 
    <code><nowiki><img id="runImage" src="ACPIframe02.png"></nowiki></code> 
    <code><nowiki><button id="maximizeButton" class="control-button" title="Click to use full screen"></button></nowiki></code> 
    <code><nowiki><button id="minimizeButton" class="control-button" title="Exit full screen"></button></nowiki></code> 
    <code><nowiki><button id="interactButton">Click to interact with the model in Analytica Cloud Platform</button></nowiki></code> 
  <code><nowiki></div></nowiki></code> 
</div>
<div style="margin-left: 2em;">
<code><nowiki><script></nowiki></code> 
  <code><nowiki>document.addEventListener('DOMContentLoaded', function () {</nowiki></code> 
    <code><nowiki>let iframeAdded = false;</nowiki></code> 
    <code><nowiki>const container = document.getElementById('container');</nowiki></code> 
    <code><nowiki>const runImage = document.getElementById('runImage');</nowiki></code> 
    <code><nowiki>const maximizeButton = document.getElementById('maximizeButton');</nowiki></code> 
    <code><nowiki>const minimizeButton = document.getElementById('minimizeButton');</nowiki></code> 
    <code><nowiki>const interactButton = document.getElementById('interactButton');</nowiki></code> 
    <code><nowiki>function showIframe() {</nowiki></code> 
      <code><nowiki>runImage.style.display = 'none';</nowiki></code> 
      <code><nowiki>interactButton.style.display = 'none';</nowiki></code> 
      <code><nowiki>if (!iframeAdded) {</nowiki></code> 
        <code><nowiki>const iframe = document.createElement('iframe');</nowiki></code> 
        <code><nowiki>iframe.src = 'https://acp.analytica.com/view?invite=4771&code=2359748081441958275';</nowiki></code> 
        <code><nowiki>iframe.style.width = '100%';</nowiki></code> 
        <code><nowiki>iframe.style.height = '100%';</nowiki></code> 
        <code><nowiki>iframe.style.border = 'none';</nowiki></code> 
        <code><nowiki>container.appendChild(iframe);</nowiki></code> 
        <code><nowiki>iframeAdded = true;</nowiki></code> 
        <code><nowiki>maximizeButton.style.display = 'inline-block';</nowiki></code> 
      <code><nowiki>}</nowiki></code> 
    <code><nowiki>}</nowiki></code> 
    <code><nowiki>function maximizeIframe() {</nowiki></code> 
      <code><nowiki>if (container.requestFullscreen) {</nowiki></code> 
        <code><nowiki>container.requestFullscreen();</nowiki></code> 
      <code><nowiki>} else if (container.webkitRequestFullscreen) {</nowiki></code> 
        <code><nowiki>container.webkitRequestFullscreen();</nowiki></code> 
      <code><nowiki>} else if (container.msRequestFullscreen) {</nowiki></code> 
        <code><nowiki>container.msRequestFullscreen();</nowiki></code> 
      <code><nowiki>}</nowiki></code> 
      <code><nowiki>maximizeButton.style.display = 'none';</nowiki></code> 
      <code><nowiki>minimizeButton.style.display = 'inline-block';</nowiki></code> 
    <code><nowiki>}</nowiki></code> 
    <code><nowiki>function minimizeIframe() {</nowiki></code> 
      <code><nowiki>if (document.exitFullscreen) {</nowiki></code> 
        <code><nowiki>document.exitFullscreen();</nowiki></code> 
      <code><nowiki>} else if (document.webkitExitFullscreen) {</nowiki></code> 
        <code><nowiki>document.webkitExitFullscreen();</nowiki></code> 
      <code><nowiki>} else if (document.msExitFullscreen) {</nowiki></code> 
        <code><nowiki>document.msExitFullscreen();</nowiki></code> 
      <code><nowiki>}</nowiki></code> 
      <code><nowiki>maximizeButton.style.display = 'inline-block';</nowiki></code> 
      <code><nowiki>minimizeButton.style.display = 'none';</nowiki></code> 
    <code><nowiki>}</nowiki></code> 
    <code><nowiki>interactButton.addEventListener('click', function (event) {</nowiki></code> 
      <code><nowiki>event.stopPropagation();</nowiki></code> 
      <code><nowiki>showIframe();</nowiki></code> 
    <code><nowiki>});</nowiki></code> 
    <code><nowiki>maximizeButton.addEventListener('click', function (event) {</nowiki></code> 
      <code><nowiki>event.stopPropagation();</nowiki></code> 
      <code><nowiki>maximizeIframe();</nowiki></code> 
    <code><nowiki>});</nowiki></code> 
    <code><nowiki>minimizeButton.addEventListener('click', function (event) {</nowiki></code> 
      <code><nowiki>event.stopPropagation();</nowiki></code> 
      <code><nowiki>minimizeIframe();</nowiki></code> 
    <code><nowiki>});</nowiki></code> 
    <code><nowiki>container.addEventListener('click', showIframe);</nowiki></code> 
  <code><nowiki>});</nowiki></code> 
<code><nowiki></script></nowiki></code> 
<code><nowiki></body></nowiki></code> 
<code><nowiki></html></nowiki></code>
</div>

==ACP in an Iframe on a wiki==
*Putting html or javascript into a mediawiki page is generally not supported directly.
*You can run the code in a widget. To do this you need to install the widget extension, then save the code as a widget page and put the widget into your mediawiki page..
*Here is an example page on the Analytica docs which uses a widget file to run the same model. [https://docs.analytica.com/index.php/Testiframe https://docs.analytica.com/index.php/Testiframe].
*You can inspect this code by navigating to the page and selecting <code>This page > show source</code>.
*You can also navigate to the widget page and view the source: [https://docs.analytica.com/index.php/Widget:Ppplanner05 https://docs.analytica.com/index.php/Widget:Ppplanner05].

==ACP in an Iframe on a wordpress site==
Running live on this page: [https://analytica.com/acpiframeminmax/ https://analytica.com/acpiframeminmax/]
To add an iframe running an ACP model on an Elementor page:
*Upload images needed to your wordpress site and note the location and urls.
*Click edit with Elementor.
*Add a new section then drag an HTML widget onto the section.
* In the code block for the HTML widget enter the code for your overlay image and for your iframe.
**Here is the code for this Iframe: you would need to edit the images and styles.

<div style="margin-left: 2em;">
<code><nowiki><script></nowiki></code> 
  <code><nowiki>function showIframe() {</nowiki></code> 
    <code><nowiki>document.getElementById('runImage').style.display = 'none';</nowiki></code> 
    <code><nowiki>const container = document.getElementById('container');</nowiki></code> 
    <code><nowiki>const interactButton = document.getElementById('interactButton');</nowiki></code> 

    <code><nowiki>// Hide the "Interact" button if present</nowiki></code> 
    <code><nowiki>if (interactButton) {</nowiki></code> 
      <code><nowiki>interactButton.style.display = 'none';</nowiki></code> 
    <code><nowiki>}</nowiki></code> 

    <code><nowiki>// Check if iframe is already present</nowiki></code> 
    <code><nowiki>let iframe = document.getElementById('embeddedIframe');</nowiki></code> 
    <code><nowiki>if (!iframe) {</nowiki></code> 
      <code><nowiki>iframe = document.createElement('iframe');</nowiki></code> 
      <code><nowiki>iframe.id = 'embeddedIframe';</nowiki></code> 
      <code><nowiki>iframe.src = 'https://acp.analytica.com/view0?invite=4314&code=2462049136540573676';</nowiki></code> 
      <code><nowiki>iframe.style.width = '1210px';</nowiki></code> 
      <code><nowiki>iframe.style.height = '600px';</nowiki></code> 
      <code><nowiki>iframe.style.border = 'none';</nowiki></code> 
      <code><nowiki>container.appendChild(iframe);</nowiki></code> 
    <code><nowiki>}</nowiki></code> 
    <code><nowiki>iframe.style.display = 'block';</nowiki></code> 

    <code><nowiki>// Ensure maximize button is displayed</nowiki></code> 
    <code><nowiki>let maximizeButton = document.getElementById('maximizeButton');</nowiki></code> 
    <code><nowiki>if (!maximizeButton) {</nowiki></code> 
      <code><nowiki>maximizeButton = document.createElement('button');</nowiki></code> 
      <code><nowiki>maximizeButton.id = 'maximizeButton';</nowiki></code> 
      <code><nowiki>maximizeButton.title = 'Click to use full screen';</nowiki></code> 
      <code><nowiki>maximizeButton.style.position = 'absolute';</nowiki></code> 
      <code><nowiki>maximizeButton.style.bottom = '10px';</nowiki></code> 
      <code><nowiki>maximizeButton.style.right = '110px';</nowiki></code> 
      <code><nowiki>maximizeButton.style.background = 'transparent';</nowiki></code> 
      <code><nowiki>maximizeButton.style.border = 'none';</nowiki></code> 
      <code><nowiki>maximizeButton.style.cursor = 'pointer';</nowiki></code> 
      <code><nowiki>maximizeButton.style.width = '30px';</nowiki></code> 
      <code><nowiki>maximizeButton.style.height = '30px';</nowiki></code> 
      <code><nowiki>maximizeButton.style.backgroundImage = 'url("https://analytica.com/wp-content/uploads/2024/11/arrows-maximize.png")';</nowiki></code> 
      <code><nowiki>maximizeButton.style.backgroundSize = 'contain';</nowiki></code> 
      <code><nowiki>maximizeButton.style.backgroundRepeat = 'no-repeat';</nowiki></code> 
      <code><nowiki>maximizeButton.onclick = function() {</nowiki></code> 
        <code><nowiki>container.requestFullscreen();</nowiki></code> 
        <code><nowiki>iframe.style.width = "100%";</nowiki></code> 
        <code><nowiki>iframe.style.height = "100%";</nowiki></code> 
        <code><nowiki>maximizeButton.style.display = 'none';</nowiki></code> 
        <code><nowiki>minimizeButton.style.display = 'block';</nowiki></code> 
      <code><nowiki>};</nowiki></code> 
      <code><nowiki>container.appendChild(maximizeButton);</nowiki></code> 
    <code><nowiki>}</nowiki></code> 
    <code><nowiki>// Ensure minimize button is created</nowiki></code> 
    <code><nowiki>let minimizeButton = document.getElementById('minimizeButton');</nowiki></code> 
    <code><nowiki>if (!minimizeButton) {</nowiki></code> 
      <code><nowiki>minimizeButton = document.createElement('button');</nowiki></code> 
      <code><nowiki>minimizeButton.id = 'minimizeButton';</nowiki></code> 
      <code><nowiki>minimizeButton.title = 'Exit full screen';</nowiki></code> 
      <code><nowiki>minimizeButton.style.position = 'fixed';</nowiki></code> 
      <code><nowiki>minimizeButton.style.bottom = '10px';</nowiki></code> 
      <code><nowiki>minimizeButton.style.right = '110px';</nowiki></code> 
      <code><nowiki>minimizeButton.style.background = 'transparent';</nowiki></code> 
      <code><nowiki>minimizeButton.style.border = 'none';</nowiki></code> 
      <code><nowiki>minimizeButton.style.cursor = 'pointer';</nowiki></code> 
      <code><nowiki>minimizeButton.style.width = '30px';</nowiki></code> 
      <code><nowiki>minimizeButton.style.height = '30px';</nowiki></code> 
      <code><nowiki>minimizeButton.style.backgroundImage = 'url("https://analytica.com/wp-content/uploads/2024/11/arrows-minimize.png")';</nowiki></code> 
      <code><nowiki>minimizeButton.style.backgroundSize = 'contain';</nowiki></code> 
      <code><nowiki>minimizeButton.style.backgroundRepeat = 'no-repeat';</nowiki></code> 
      <code><nowiki>minimizeButton.style.display = 'none'; // Hidden initially</nowiki></code> 
      <code><nowiki>minimizeButton.onclick = function() {</nowiki></code> 
        <code><nowiki>document.exitFullscreen();</nowiki></code> 
        <code><nowiki>iframe.style.width = '1210px';</nowiki></code> 
        <code><nowiki>iframe.style.height = '600px';</nowiki></code> 
      <code><nowiki>};</nowiki></code> 
      <code><nowiki>container.appendChild(minimizeButton);</nowiki></code> 
    <code><nowiki>}</nowiki></code> 
  <code><nowiki>}</nowiki></code> 

  <code><nowiki>// Event listener to handle fullscreen changes</nowiki></code> 
  <code><nowiki>document.addEventListener('fullscreenchange', function() {</nowiki></code> 
    <code><nowiki>const maximizeButton = document.getElementById('maximizeButton');</nowiki></code> 
    <code><nowiki>const minimizeButton = document.getElementById('minimizeButton');</nowiki></code> 
    <code><nowiki>const iframe = document.getElementById('embeddedIframe');</nowiki></code> 

    <code><nowiki>// Check if in fullscreen mode</nowiki></code> 
    <code><nowiki>if (document.fullscreenElement) {</nowiki></code> 
      <code><nowiki>if (maximizeButton) maximizeButton.style.display = 'none';</nowiki></code> 
      <code><nowiki>if (minimizeButton) minimizeButton.style.display = 'block';</nowiki></code> 
    <code><nowiki>} else {</nowiki></code> 
      <code><nowiki>if (maximizeButton) maximizeButton.style.display = 'block';</nowiki></code> 
      <code><nowiki>if (minimizeButton) minimizeButton.style.display = 'none';</nowiki></code> 
      <code><nowiki>// Restore iframe size when exiting fullscreen</nowiki></code> 
      <code><nowiki>iframe.style.width = '1210px';</nowiki></code> 
      <code><nowiki>iframe.style.height = '600px';</nowiki></code> 
    <code><nowiki>}</nowiki></code> 
  <code><nowiki>});</nowiki></code> 

  <code><nowiki>// Create the "Click to interact" button</nowiki></code> 
  <code><nowiki>document.addEventListener('DOMContentLoaded', function() {</nowiki></code> 
    <code><nowiki>const container = document.getElementById('container');</nowiki></code> 
    <code><nowiki>const interactButton = document.createElement('button');</nowiki></code> 
    <code><nowiki>interactButton.id = 'interactButton';</nowiki></code> 
    <code><nowiki>interactButton.textContent = "Click to interact with the model in Analytica Cloud Platform";</nowiki></code> 
    <code><nowiki>interactButton.style.position = 'absolute';</nowiki></code> 
    <code><nowiki>interactButton.style.bottom = '13px';</nowiki></code> 
    <code><nowiki>interactButton.style.right = '140px';</nowiki></code> 
    <code><nowiki>interactButton.style.padding = '5px 10px';</nowiki></code> 
    <code><nowiki>interactButton.style.fontSize = '16px';</nowiki></code> 
    <code><nowiki>interactButton.style.fontWeight = 'bold';</nowiki></code> 
    <code><nowiki>interactButton.style.backgroundColor = '#d3d3d3';</nowiki></code> 
    <code><nowiki>interactButton.style.color = 'black';</nowiki></code> 
    <code><nowiki>interactButton.style.border = 'none';</nowiki></code> 
    <code><nowiki>interactButton.style.borderRadius = '5px';</nowiki></code> 
    <code><nowiki>interactButton.style.cursor = 'pointer';</nowiki></code> 
    <code><nowiki>interactButton.style.opacity = '0.9';</nowiki></code> 

    <code><nowiki>interactButton.onclick = function(event) {</nowiki></code> 
      <code><nowiki>event.stopPropagation();</nowiki></code> 
      <code><nowiki>showIframe();</nowiki></code> 
    <code><nowiki>};</nowiki></code> 
    <code><nowiki>container.appendChild(interactButton);</nowiki></code> 
  <code><nowiki>});</nowiki></code> 
<code><nowiki></script></nowiki></code> 
 
<code><nowiki><div id="container" class="screenshot-border" style="position: relative; width: 100%; height: auto;"></nowiki></code> 
  <code><nowiki><img id="runImage" src="https://analytica.com/wp-content/uploads/2023/07/ev-vs-ice-1.webp" width="1210px" height="648px" onclick="showIframe()" style="cursor: pointer;"></nowiki></code> 
<code><nowiki></div></nowiki></code>
</div>



==See Also==
* [[Analytica Cloud Player]]
* [[Example Models]]
* [[Tutorial: Sharing a model with ACP]]
* [[Model Licensing]]

IndexesOf

2024-11-19T00:06:36Z

Max: /* IndexesOf(a, except...) */

[[Category:Functions that create lists]]
[[Category:Functions returning information about arrays]]
[[Category:Meta-Inference Functions]]

== IndexesOf(a'', except...'') ==
Returns a list of [[handle]]s to the indexes of array «a». It is different from [[IndexNames]](a), which returns the identifiers of the indexes as text values instead of handles.

If «X» has an [[implicit index]] (an index without a name), the first element of the output list is [[null]], rather than a handle.

If the array has more than one [[Local Indexes|local index]] with the same identifier, you can use [[IndexesOf]](a) to identify each index safely because each handle unambiguously refers to the corresponding index, where [[IndexNames]](a) would return the identifiers as identical and therefore ambiguous text values.

The optional «except» parameter excludes any of the indexes that are listed.

[[Syntax]]:
:[[IndexesOf]](a: Array)

== Example ==
:<code>IndexesOf(Car_prices) → [Car_types, Year]</code>

:<code>IndexesOf(Car_prices, except: Car_types) → [Year]</code>

Find the maximum in <code>A</code> over all indexes:
:<code>[[Max]]( A, ...[[IndexesOf]](A) )</code>

Sum over all indexes of <code>x</code> except <code>J</code> and <code>K</code>:
:<code>[[Sum]]( x, ...[[IndexesOf]](x, except: J,K) )</code>

== History ==
* The «except» parameter was introduced in [[Analytica 5.2]].

== See Also ==
* [[Handle]]
* [[Handle Functions]]
* [[IndexNames]]
* [[Repeated parameter forwarding]]

AcpStyles

2024-08-02T22:30:37Z

Max: /* Hide the Save options */

[[Category: Analytica Cloud Platform]]
[[Category: Attributes]]
[[Analytica_Cloud_Player#See_also|Analytica Cloud Platform >]]

::{{ReleaseBar}}

ACP offers a wide variety of styles and options to control the look and functioning of the user interface. Many of these go beyond what is (currently) available in Desktop Analytica (DTA).

The easiest way to set most of these styles and options is to use the [[ACP Style Library]]. This library lets you interactively select most ACP styles and options for Navigation, Frames and results using menus and checkboxes and menus. As you change styles in ACP, you can see their effects immediately.

If you use [[ACP Style Library]] you don't need to learn about the ACP Styles described below. This page is only needed if you want to do something esoteric with AcpStyles, or use those few AcpStyles not (yet) accessible in the [[ACP_Style_Library]].

You set general styles and options that apply to the whole model by adding flags to the AcpStyles attribute for the main model. You set styles specific to a particular module or node by adding flags to the AcpStyles attribute for that object.

The easiest way to view and edit the AcpStyles attribute in Desktop Analytica is to use the [[Attribute panel]]. Select AcpStyles from the list of Attributes at the top of that panel. By default, AcpStyles is not shown in the [[Object window]], so you first need to set it to be shown either with the [[Object_Window|right click menu]] in the Object window, or in the [[Manage attributes|Attributes dialog]].

The AcpStyles and their flags are not case sensitive.

When you put multiple flags in a AcpStyles attribute, put each flag on a separate line.

== Model level styles ==

These styles apply to the entire model. You set them in the AcpStyles attribute for the Main Model. (They have no effect when set for a submodule.)

=== Navigation style ===

These Navigation_style options control how a user can view and access the module hierarchy:
* '''<code>Navigation_style: Outline</code>''' -- Show an expandable tree of modules on the left of the ACP window, similar to the outline view in desktop Analytica (showing only modules not other objects). This is the default style when you upload a model with no ACP styles set or no Acp styles library embedded, or if you have not yet set the Navigation style in the Acp styles library. A navigation flag is not needed for this style, but if you want to explicitly set this style you can add '''<code>Navigation_style: Outline</code>''' to the top diagram's AcpStyles attribute.

*'''<code>Navigation_style: Top diagram only</code>''' -- Show only the top diagram, with no Outline and no tabs. This lets you make a simple web application with a single UI page.
 

For the next two 'Tabbed application' styles, each module in the main model becomes a tab. The order of the tabs follows the sequence of the module nodes in the main diagram, from left to right then top to bottom.

* '''<code>Navigation_style: Top_tabs</code>''' -- The main modules in the top model appear as a row of tabs across the top of the window. Click a tab to show the diagram for that module.

*'''<code>Navigation_style: Side_tabs</code>''' -- The main modules in the top model appear as a column of tabs on the left of the window. Click a tab to show the diagram for that module.


We describe each in more detail below.

===Outline Tree===

By default, when using the Outline Navigation style, ACP shows an expandable outline tree of modules on the left hand side of the window, similar to the Outline view in Analytica on the desktop. This makes it easy to navigate a model with an extensive hierarchy of modules.

*'''<code>Show_outline: yes</code>''' -- The default, and unecessary for Outline Navigation style. It is generally redundant with other Navigation styles since the tabs or hierarchy show the same information, and the Outline takes up screen space. But you can add it to the top diagram's AcpStyles attribute if you want to show the Outline tree with other Navigation styles.

{{CalloutAnnotationBlock|[[File:Outline tree 6.0 01.png]]|{{CalloutAnnotation|Market model with Outline Tree|v=80|pt=10,106}}}}
*'''<code>show_outline: no</code>''' -- When using the Acp Style library this is set by default for Navigation styles other than Outline. For small models, and most web apps, you may want to suppress the Outline view even when using the Outline Navigation style. Do this by inserting this text into the top diagram's AcpStyles attribute (See image below). (If a model has only one diagram, i.e. with no modules, it never shows the outline tree.) 
{{CalloutAnnotationBlock|[[File:Outline tree 6.0 02.png]]|{{CalloutAnnotation|Market model with '''<code>show_outline: no</code>'''|v=80}}}}

===Top Diagram Only===

Set by adding '''<code>navigation_style: top_diagram_only</code>''' to the AcpStyles attribute of the top diagram.  The Styles library will set the flag  '''<code>show_outline:no</code>''' .

===Tabbed Module Navigation===

As an alternative to the Outline view, you can set the '''<code>Navigation_style</code>''' to use use a tabbed interface which is often more convenient and familiar for web applications. By default, the main model appears as the first tab. You can change this with the style [[AcpStyles_Attribute_Values#Exclude_the_top_level_diagram_from_tabs|show_as_tab:no]] described below.


There are two tabbed styles, Top_tabs, with a row of tabs across the top; and Side_tabs with a column of tabs down the side. Top_tabs works well if you have up to 5 to 8 modules in the main diagram (tabs), depending on the length of their titles and the width of the ACP window. If you have a lot of modules, or they have long titles, it may be better to use Side_tabs.

'Top tabs or side tabs.' The first tab displays the top level diagram, and the remaining tabs display the modules present on the top level diagram of the model. (The modules will not display on the diagram, so you need to tweak your diagram for playing in ACP so that it looks right without these present).

* '''<code>navigation_style: top_tabs</code>''' -- This setting instructs ACP to use the 'Tabs across top' navigation style.

[[File:Top tabs 6.0 01.png]]

* '''<code>navigation_style: side_tabs</code>''' -- This setting instructs ACP to use the 'Side tabs' navigation style. Side tabs work better than top tabs when there are more module nodes present.

[[File:Side tabs 6.0 01.png]]

=== Toolbar Tabs ===
*'''<code>show_tabs: no</code>''' -- By default, with the Outline Navigation style. ACP shows navigation tabs for "Diagram", "Object", "Table", "Graph" along the top. Use this flag to hide those tabs. If you display the model inputs and outputs on the diagram -- using embedded tables and graphs on the diagram -- your users may not need those tabs. (You can also use '''<code>show_tabs: yes</code>''' to explicitly show the tabs in Outline and Top diagram only Navigation styles.)
{{CalloutAnnotationBlock|[[File:Show tabs no 6.0 0.1.png]]|{{CalloutAnnotation|Market model with '''<code>show_tabs: no</code>'''|v=80|pt=232,37|path=t!-}}}}
 

===Module hierarchy bar ===
Using tabbed navigation, ACP shows the model hierarchy in a bar at the top of the diagram by default. The model hierarchy header shows you where you are in a large model by listing the titles of the ancestor modules in which the current diagram is nested. You can click any ancestor to click up levels in the hierarchy. The Hierarchy Bar takes up much less screen real estate than the Outline Tree. ACP doesn't show the hierarchy bar when you are viewing a top level module, or if the module title is already in the selected tab. 

Note that this setting is not based on a AcpStyles attribute, but rather on the ''Show module hierarchy'' check box in the model [[Preferences]] in Analytica. If you want to set this preference manually, with the model opened in Analytica, on the [[Edit menu]], select '''Preference...''', and check (or uncheck) the ''Show module hierarchy'' checkbox.

If you are using the ACP styles library, the Styles library will set this to the default setting automatically once you select a Navigation style. But you have the option of changing it if, for instance you want to show the Outline and the Hierarchy bar.


===Auto zoom ===
*'''<code>auto_zoom_diagrams: yes</code>''' -- ACP automatically zooms the UI to fit the browser window -- the most constraining of width or height so it retains the aspect ratio of the diagram. Works with zoom in and zoom out. This Acp style has no effect if '''<code>Use_top_diagram_size:Yes </code>''' is present, you can use only one or the other. You can also set '''<code>auto_zoom_diagrams: no</code>''' which is the default.

===Use top diagram size for all ACP windows===
*'''<code>Use_top_diagram_size:Yes </code>''' -- Sets the size of all diagrams based on the size of the diagram window of the top level when the model was last viewed in Desktop Analytica (in non-maximized mode). '''<code>Use_top_diagram_size:No </code>''' is the same as if the flag is not set, and is the default - the ACP diagram will use the entire browser window.


===Show or hide the Dashboard Title and Model title===
*'''<code>show_model_title: no</code>''' -- Hide the title of the model, which appears by default in the top Teal bar.

*'''<code>show_diagram_title: yes</code>''' -- Use to show the dashboard title at the top of the diagram. Or <code>show_diagram_title: no</code> to suppress the diagram title, but not really necessary because ACP does not show the diagram title by default.


===Exclude diagram(s) from tabs===

When using tabbed navigation, you can select those modules (from the top model diagram) that you want to appear as a tab in ACP. The default is for all to appear as tabs. You should use the ''Show modules as tabs'' choice menu in the '''<code>ACP Navigation styles</code>''' section of the [[ACP Style Library]] if you want to set this flag,, and if you also want to hide the modules corresponding to these tabs [[ChangeNodeVisibility|hidden]], so that the model viewer cannot see them.

*Optionally, Enter the text '''<code>Show_as_tab: no</code>''' in the AcpStyles attribute of the modules you don't wish to show as a tab. The modules themselves will not be hidden with this setting, only the tabs.

===Tab color===

When using Tabbed Navigation, you can use these flags to control how the color of the tabs display on your model in ACP. To use, add one of them to the AcpStyles attribute of the top level diagram of your model. They have no effect if added to a module other than the top diagram.

*'''<code>Tab_color: Default </code>''' The default. Non-selected tabs are bluish white. The selected tab uses the background color for that diagram.
*'''<code>Tab_color: Background </code>''' All tabs use their diagram background color, whether selected or not
*'''<code>Tab_color: Node </code>''' The selected Tab uses its diagram background color; The other tabs use the color of their Module node (not their diagram background color). You can use this to change the color of the tabs by modifying their node color in an Analytica functions.

== Model level styles for diagram nodes. ==

These model-level styles affect how all nodes are displayed in diagrams.

=== Node shadows and bevels ===

By default ACP displays nodes without shadows or bevels (for now) , so they look like this:
:[[Image:Nodes no shadow or bevel.png]]

Set this flag to show a drop shadow behind each node, giving a kind of 3D effect:

*'''<code>node_drop_shadow: yes</code>'''

:[[Image:Nodes drop shadow.png]]

Set this flag to display a bevel border for each node, giving another kind of 3-D effect:
*'''<code>bevel_node_border: yes</code>'''

:[[Image:Nodes beveled border.png]]

===Node hover highlighting===

By default, ACP displays a highlight -- a contrasting light rectangle behind a node -- when you move the cursor over the node:

[[File:acp hover hl.png]]

You can switch it off by setting:
*'''<code>show_hover_highlight: No</code>'''

=== Balloon Help ===

When you move the cursor over a node, ACP usually shows a "balloon" popup next to the node with the description of the node (if it has one) to help end users understand what its for, or what to enter for a user input. If the node has no description, the [[help balloons|balloon help]] will not appear.

*'''<code>show_id_in_balloon: yes</code>''' Use this flag to show each node's identifier below its title in the balloon -- unless the identifier and title are identical (except for spaces which are replaced by underscores). This flag goes in the AcpStyles of the model and apply to all nodes in the model.





*'''<code>show_hover_balloon: no</code>'''
::Insert this flag in the AcpStyles for a node, to suppress display of its balloon.


==ACP styles inheritance==
This is the order of inheritance for Acpstyles below that apply to tables and graphs. Styles at a higher level take precedence over the lower precedence styles. (Inheritance doesn't apply to the ACPstyles described above that apply only at the Model level.)
# '''Variable''' (includes Tall nodes): Acpstyles applied to an individual variable will take precedence over all other styles. A variable with a style of <code>show_title:no</code> will not show the title, even if the model level style is <code>show_title:yes</code>, and if that node shows it's result in a frame node the variable style will override the frame node style.
# '''Frame''' : An Acpstyle set for a frame node will affect any variable shown in that frame that doesn't have its own settings. These will also override any styles at the model level.
# '''Model ACP style defaults''': Acpstyles that you can enter into the Acptyles attribute of the top diagram of your model. These will override the ACP defaults, and will be inherited by frame nodes and variables in the model that don't have their own Acpstyle.
# '''ACP style defaults for ACP''': The default style ACP uses if you have no specific setting for that style. Eg for show_index_menus the default is fly-in and that is what will show if you don't enter a different show_index_menus: Acpstyle flag in the Acpstyle for the top diagram (model level) or for frame nodes or variables.

==ACP Styles for tables and graphs==

These styles affect how result graphs and tables are displayed in ACP, including in [[Embed_table_or_graph_with_ACP#Frame_nodes|Tall nodes]] and [[Embed_table_or_graph_with_ACP#Tall_nodes|˞Frame nodes]]. They provide options not (yet) available in Desktop Analytica. ACP has default settings for these. You can override these settings for the entire model. You can also set them for [[Embed_table_or_graph_with_ACP#Frame_nodes|˞Frame nodes]], which will apply to all results shown in the Frame and override the ACP and model level settings. And you can set these styles for individual variables, which will override any settings in the Model or Frame. As always, it's easiest to set the using the [[ACP_Style_library]].

None of these styles apply to tab result views using the default Navigation_style: Outline.

===Show or hide the Description===

*'''<code>Show_description: nn</code>'''' Where <code>nn</code> is a number between 0 and 100, where it uses up to nn% of the vertical space available to show the description. If that isn't enough to show the entire description, it shows a vertical scroll bar. Set <code>nn = 0</code>, if you don't want to show the description at all. Default if not mentioned, is one third, i.e. <code>Show_description: 33</code>. This style can be used at the model level, for frame nodes or for individual nodes, but controls whether or not the Description shows in tall nodes or Frame nodes.

===Show or hide the Object view icon===
*'''<code>Object_in_Frame:yes/no</code>''': With this style set, it shows an object view hover icon at the top right of a frame node or tall node when showing a graph or table view. Click this icon to show the object window view. The object view shows the Table and Graph hover icon to go back to the table or graph view. You can set '''<code>Object_in_frame</code>''' style at either the top level of the model or in an individual frame node, which overrides the top level setting. When working with tall nodes, you can set '''<code>Object_in_frame</code>''' style at the top level or in the original variable's ACP style setting, which overrides the top level setting.

===Show or hide the title===

*'''<code>Show_title</code>''': Set <code>Show_title: yes</code> to show or <code>Show_title: no</code> to stop showing the Title and units of a selected variable. This style can be used at the model level, for frame nodes or for individual nodes, but controls whether or not the Title and units show in Frame nodes or tall nodes.

===Show or hide the Graph-Table icon===

*'''<code>Show_graph_table_icon:no</code>''' Hides the icon in the top right of a Result that lets you toggle between Graph and Table view. This applies to [[Embed_table_or_graph_with_ACP|Frame nodes and tall nodes]]. This style can be used for the entire model, for frame nodes or for individual nodes . You set them in the AcpStyles attribute. Conversely, you can set '''<code>Show_graph_table_icon:yes</code>'''. This is the default so not usually necessary at the model level, but can be used in a frame node or variable to override the model default or override a frame node setting.

===Show or hide the Uncertainty view menu===
By default, in ACP, as in desktop Analytica, the [[Uncertainty views]] menu appears above each result graph or table to let you select [[Mid]] to display its deterministic value, or Mean, Probability distribution, and other ways to display a probabilistic value.

You can override this default behavior with this ACP style for the entire model, [[Embed_table_or_graph_with_ACP#Frame_nodes|Frame nodes]], or for individual variables. The Uncertainty view menu is always present in tab result views.
*'''<code>Show_uncertainty_view: No</code>''' Never show the uncertainty menu in frame nodes or tall result nodes. Suitable for models with no probabilistic values, or if you want to fix a particular probabilistic view for each frame node or variable so that ACP users can't change it.
*'''<code>Show_uncertainty_view: Yes</code>''' Always show the uncertainty menu even for variables that are not probabilistic, as in Desktop Analytica. This is the default and not normally necessary at the model level, but can be used to customize which frame nodes or variables to show the uncertainty view menu when the model level style is set to '''<code>Show_uncertainty_view: No</code>'''

===Show or hide the Index menus and Pivoters/slicers===
*'''<code>Show_index_menus: Fly-in</code>''' By default (the same as if there is no show_index_menu: setting) the index menus are not shown in [[https://wiki.analytica.com/index.php?title=Embed_table_or_graph_with_ACP|frame nodes or tall nodes]] (but slicers are), since often the modeler has already chosen the pivot they want to use. And because these menus take up valuable screen space. But if you hover over the frame node (or tall node) there is a fly-in pivoter control. If you click this it toggles - on or off - the visibility of the pivoters; allowing you to pivot the result table or graph and then close the pivoters to give you more space.
*'''<code>Show_index_menus: Yes</code>''' If you do want to allow users to be able to pivot or change the slice of the table or graph, without using the fly-in, then use use show_index_menus:yes. Always present in tab result views.
*'''<code>Show_index_menus: No</code>''' If show_index_menus:no is set then the indexes and pivoters will not show and there is no fly-in, but the slicers will still be present.
*'''<code>Show_index_menus: Not_even_slicers</code>''' If you don't want to show any pivoters or slicers, you can set show_index_menus:Not_even_slicers.

===Autocalc===

In the [[ACP Style Library]], Autocalc looks like a style you can set for a model, module or variable. It controls whether ACP evaluates each variable and shows its results automatically when you view a Diagram or tab showing the -- instead of the default Analytica behavior where the end user has to click on a Calc button to compute a result. With Autocalc on, a result in view also recomputes automatically when you change an input that influences it.

Autocalc is not actually an ACPStyle in ACP3. (It was in ACP1.) Autocalc is implemented using the Desktop Analytica functionality for [[Proactive_Evaluation]].

== Node Level Settings ==

These style flags and options apply to individual nodes (variables), rather than the model as a whole. So, you set these flags on the AcpStyles for selected objects (nodes).

=== Other node level flags ===
=== Prevent nodes from showing on the diagram ===

*'''<code>Show_Object: no</code>'''
You can prevent nodes or modules from showing on the diagram of your model, by adding this flag to the AcpStyles attribute of the object you wish to hide. Once the model is shown in ACP the objects aren't visible.

== Modifying ACP menus==

Normally, ACP offers menus that appear when you press one of the three icons on the right of the top teal bar. These ACP styles let you modify these menus.

===Hide the Save options===

*'''<code>Hide_save_button: yes </code>''' Set this model ACP style option to exclude the 'Save this model' and 'Save model as...' from the ACP Close menu. It prevents users from saving over your models or saving other versions.

===Remove Help menu items===

These styles add menu items to or remove items from the help (?) menu if added to the AcpStyles of the top diagram of your model. For [[ACP_Server_License|ACP installations]] on an intranet, these standard links may not be accessible. On the other hand you may want to offer a special help page for a particular model.

*'''<code>Remove_help_menu_options: Text</code>
This style allows you to list one or more of the standard options to remove from the help (?) menu. Replace <code>Text</code> with one or more of the following: <code>ACP_Online_docs, Analytica_Q_A_forum, Tech_support</code>.

(Note: The help menu item <code>Connection status</code> cannot currently be removed).

===Add Help menu item===
*'''<code>Add_help_menu_option: Text|URL</code>'''
Adds another menu item, for example: <code>Add_help_menu_option: How to use this model...|https://www.lumina.com</code> adds a menu item to the help (?) menu with the text "How to use this model..." and opens the link when clicked.

===Add download this model to the Close menu===
*'''<code>save_menu_download: yes</code>'''
This AcpStyle is controlled by a setting in the [[Customizing_an_ACP_server#The_acpConfig.json_file|AcpConfig.json]] file. On Lumina's acp.analytica.com server it is turned on.
With this AcpStyle in the model, ''<code>"download this model"</code>'' is added to the close menu at the top right of the ACP GUI.
When set, this will allow anyone to download the model - even a reviewer, and even from an email invite.
*'''<code>save_menu_download: no</code>''' (default if not set)
*'''<code>save_menu_download:Prompt_to_download_free</code>'''. This adds a popup dialog with a download link and prompt to download the Analytica free installer.

==See Also==
* [[ACP Style Library]]
* [[media:ACP style library.ana]]
* [[Analytica Cloud Platform]]
* [[ACP Rendering tables and graphs on the diagram]]
* [[Putting ACP in a Web Page]]
* [[Help balloons]]
* [[Attributes]]
* [[Manage attributes]]

Keyboard Shortcuts

2024-07-16T00:20:34Z

Max: remove long obsolete arrow mode

[[Category:Ana: Status M]] 

Like most applications, Analytica offers keys or key combinations as shortcuts to access common features. Some, like ''ctrl+v'' to paste, or ''ctrl+s'' to '''s'''ave a model file, are common to most Windows applications. Learning some of these can greatly speed up your interactions.

You can see the keyboard shortcuts for Toolbar icon buttons in the tooltip that appears when you move the mouse cursor over each icon, for menu options inside each menu at the top of the application, and for context-dependent menu that appears when you right-click.

==Most valuable shortcuts==

These are the most useful shortcuts to learn initially (beyond the standard shortcuts common to most Windows applications):
* ''CTRL+F'': Open the [[Find dialog]]
* ''CTRL+H'': Select a variable or function identifier in a definition, and press ''ctrl+H'' to open its Object view
* ''CTRL+R'': Select a node and see its result view
* ''CTR+B'': Open the [[Number Format Dialog]]
* ''CTR+U'': Open the [[Uncertainty Setup Dialog]]
* ''F8'': Change to Edit mode
* ''ctrl+click'': When the edit cursor is the a Definition in the Attribute panel at the bottom of a diagram, ''ctrl+click'' on another node to insert its identifier into the definition.
* Select several nodes in a Diagram and press:
** ''=='' resize the nodes to be the same as the last node you selected (the one with black boxes in the corners)
**''ctrl+='' align the nodes one above the other with same width

== Shortcuts for Toolbar buttons ==

* F2: [[image:ParentTool.jpg]]: Open Diagram window containing the selected node.
* F3: [[image:OutlineTool.jpg]]: Open the Outliner window
* F4: [[image:ObjectWindowToolbarButton.jpg]]: Open the Object window for selected node.
* F5: [[image:ResultToolbarButton.jpg]]: Open the Result window for the selected variable. (same as CTRL+R)
* F6: [[image:Expr.jpg]]: Edit the definition (script for Button) of selected Variable or Function (same as CTRL+E) in Attribute Panel or Object window, depending on setting in Preferences... dialog.
* F7: [[image:browseTool.jpg]]: Enter browse mode
* F8: [[image:Edit_Mode_Toolbar_Button.jpg]]: Enter Edit mode

== Shortcuts to add a nodes to a diagram ==

* CTRL+1: New Decision node
* CTRL+2: New Variable node
* CTRL+3: New Chance node
* CTRL+4: New Objective node
* CTRL+5: New Module node
* CTRL+6: New Index node
* CTRL+7: New Constant node
* CTRL+8: New Function node
* CTRL+9: New Text node
* CTRL+0: New Button node

== Tab as a shortcut ==

Use the ''tab'' key to select the next element in a windowt:
* In a Diagram window, ''tab'' selects the next node from left to right, then up to down
* In an Object window, ''tab'' selects the next Attribute field
* In a table, ''tab'' selects the next cell.

Use ''shift+tab'' to go backwards, to select the previous node, Attribute, or cell.

=== Shortcuts for menus ===

* F10: Select the main menu bar.
** Use left or right arrow or a letter to select a menu.
** Use up or down arrow or a letter to select an option in that menu.

* F12, or CTRL+': Open/close typescript window

=== Shortcuts to edit a Definition or other attribute ===

* Double-click an identifier to select it
* ''CTRL+f:'' Open [[find dialog]] for this identifier. A quick way to find the node for a variable, or open wiki page for a system function or variable.
* '''CTRL+click''' on a node: When you are editing the Definition (or other attribute) in an Attribute panel, CTRL-click on another node in the same diagram inserts its identifier into the Definition. This shortcut is very handy when writing a complex expression.
* '''CTRL+alt''' on a node: Same as CTRL+click. Useful when running Analytica in VMWare Fusion on a Macintosh, which treats CTRL+click as something else.
* Return
* CTRL+Return
* CTRL+right-arrow: Move right one token (identifier or operator)
* CTRL+left-arrow: Move left one token (identifier or operator)
* CTRL+ALT+left-arrow: Find left paren that matches the right paren currently at the left of the caret.
* CTRL+ALT+right-arrow: Find right parent that matches the left parent currently to the right of the cursor.
* SHIFT+(any of the above): Select the characters between.

=== Shortcuts to edit a diagram ===

* Arrow: Move selected node(s) in direction of the arrow by a grid increment, if snap to grid is set -- otherwise, by one pixel.
* SHIFT+arrow: Move selected node(s) in direction of the arrow, by one pixel if snap to grid is set -- otherwise, by one grid increment.
* CTRL+left-arrow: Align left edges
* CTRL+F9: Align horiz center
* SHIFT+F9: Align vert centers of selected nodes
* CTRL+right-arrow: Align right edges
* CTRL+=: Align left and right edges of selected nodes
* CTRL+up-arrow: Align tops of selected nodes
* CTRL+down-arrow: Align bottoms of selected nodes

These shortcuts use two keystrokes in sequence -- not pressed together:
* =,right-arrow: Make selected nodes the same width as the first selected node
* =,down-arrow: Make selected nodes the same height as the first selected node
* =,=: Make selected nodes the same width and height as the first selected node

=== Shortcuts for Table Navigation ===

Analytica supports almost all the standard shortcuts for tables offered by Microsoft Excel. See [[Shortcuts for Table Navigation]] for details.

=== Alphabetic list of CTRL shortcuts by letter ===

* CTRL+A: Select All nodes in a diagram, text in a definition, or cells in a table.
* CTRL+B: Open [[Number Format Dialog]]
* CTRL+C: Copy selected node(s), text, cell or region of a table.
* CTRL+D: Duplicate selected node(s)
* CTRL+E: Edit definition of selected node in Attribute pane
* CTRL+F: Open [[Find Dialog]] to find an object by identifier or title. In a table, Find will search table.
* CTRL+G: Find next matching item from [[Find Dialog]].
* CTRL+H: Find object with identifier matching the text you have selected -- e.g. in a definition.
* CTRL+I: Insert a new row or column after the row or column you have selected in an Edit table.
* CTRL+J: In a Diagram, align selected node(s) to grid
* CTRL+K: Kill (delete) the row or column you have selected in an Edit table.
* CTRL+L: Open dialog to Add Module...
* CTRL+M: Make an alias from the selected node(s).
* CTRL+N: Start a New Model
* CTRL+O: Open a model file
* CTRL+P: Print the current Diagram, Graph
* CTRL+Q: Exit (Quit) the model.
* CTRL+R: Show result for selected variable(s)
* CTRL+S: Save the model
* CTRL+T: Adjust selected node(s) to their default size
* CTRL+U: Open Uncertainty Options... dialog
* CTRL+V: Paste text, cell or region of a table, or selected nodes.
* CTRL+W: Close the model
* CTRL+X: Cut selected text or node(s).
* CTRL+Y: Toggle between viewing titles and identifiers
* CTRL+Z: Undo last action (typing text or moving or resizing node(s)
* CTRL+. (CTRL+dot): Stop the computation in progress.
* CTRL+Break: Stop the computation in progress.
* CTRL+' (CTRL+apostrophe): Open/close Typescript window. On some non-English keyboards, this combination is not available. In those cases, use F12.

== See also ==

[[Shortcuts for Table Navigation]]

Keyboard Shortcuts

2024-07-16T00:20:03Z

Max:

[[Category:Ana: Status M]] 

Like most applications, Analytica offers keys or key combinations as shortcuts to access common features. Some, like ''ctrl+v'' to paste, or ''ctrl+s'' to '''s'''ave a model file, are common to most Windows applications. Learning some of these can greatly speed up your interactions.

You can see the keyboard shortcuts for Toolbar icon buttons in the tooltip that appears when you move the mouse cursor over each icon, for menu options inside each menu at the top of the application, and for context-dependent menu that appears when you right-click.

==Most valuable shortcuts==

These are the most useful shortcuts to learn initially (beyond the standard shortcuts common to most Windows applications):
* ''CTRL+F'': Open the [[Find dialog]]
* ''CTRL+H'': Select a variable or function identifier in a definition, and press ''ctrl+H'' to open its Object view
* ''CTRL+R'': Select a node and see its result view
* ''CTR+B'': Open the [[Number Format Dialog]]
* ''CTR+U'': Open the [[Uncertainty Setup Dialog]]
* ''F8'': Change to Edit mode
* ''ctrl+click'': When the edit cursor is the a Definition in the Attribute panel at the bottom of a diagram, ''ctrl+click'' on another node to insert its identifier into the definition.
* Select several nodes in a Diagram and press:
** ''=='' resize the nodes to be the same as the last node you selected (the one with black boxes in the corners)
**''ctrl+='' align the nodes one above the other with same width

== Shortcuts for Toolbar buttons ==

* F2: [[image:ParentTool.jpg]]: Open Diagram window containing the selected node.
* F3: [[image:OutlineTool.jpg]]: Open the Outliner window
* F4: [[image:ObjectWindowToolbarButton.jpg]]: Open the Object window for selected node.
* F5: [[image:ResultToolbarButton.jpg]]: Open the Result window for the selected variable. (same as CTRL+R)
* F6: [[image:Expr.jpg]]: Edit the definition (script for Button) of selected Variable or Function (same as CTRL+E) in Attribute Panel or Object window, depending on setting in Preferences... dialog.
* F7: [[image:browseTool.jpg]]: Enter browse mode
* F8: [[image:Edit_Mode_Toolbar_Button.jpg]]: Enter Edit mode
* F9: [[image:arrowTool.jpg]]: Enter Arrow mode.
* F11: Toggle between Edit/Arrow editing modes ([[image:Edit_Mode_Toolbar_Button.jpg]] ←→ [[image:arrowTool.jpg]] ).

== Shortcuts to add a nodes to a diagram ==

* CTRL+1: New Decision node
* CTRL+2: New Variable node
* CTRL+3: New Chance node
* CTRL+4: New Objective node
* CTRL+5: New Module node
* CTRL+6: New Index node
* CTRL+7: New Constant node
* CTRL+8: New Function node
* CTRL+9: New Text node
* CTRL+0: New Button node

== Tab as a shortcut ==

Use the ''tab'' key to select the next element in a windowt:
* In a Diagram window, ''tab'' selects the next node from left to right, then up to down
* In an Object window, ''tab'' selects the next Attribute field
* In a table, ''tab'' selects the next cell.

Use ''shift+tab'' to go backwards, to select the previous node, Attribute, or cell.

=== Shortcuts for menus ===

* F10: Select the main menu bar.
** Use left or right arrow or a letter to select a menu.
** Use up or down arrow or a letter to select an option in that menu.

* F12, or CTRL+': Open/close typescript window

=== Shortcuts to edit a Definition or other attribute ===

* Double-click an identifier to select it
* ''CTRL+f:'' Open [[find dialog]] for this identifier. A quick way to find the node for a variable, or open wiki page for a system function or variable.
* '''CTRL+click''' on a node: When you are editing the Definition (or other attribute) in an Attribute panel, CTRL-click on another node in the same diagram inserts its identifier into the Definition. This shortcut is very handy when writing a complex expression.
* '''CTRL+alt''' on a node: Same as CTRL+click. Useful when running Analytica in VMWare Fusion on a Macintosh, which treats CTRL+click as something else.
* Return
* CTRL+Return
* CTRL+right-arrow: Move right one token (identifier or operator)
* CTRL+left-arrow: Move left one token (identifier or operator)
* CTRL+ALT+left-arrow: Find left paren that matches the right paren currently at the left of the caret.
* CTRL+ALT+right-arrow: Find right parent that matches the left parent currently to the right of the cursor.
* SHIFT+(any of the above): Select the characters between.

=== Shortcuts to edit a diagram ===

* Arrow: Move selected node(s) in direction of the arrow by a grid increment, if snap to grid is set -- otherwise, by one pixel.
* SHIFT+arrow: Move selected node(s) in direction of the arrow, by one pixel if snap to grid is set -- otherwise, by one grid increment.
* CTRL+left-arrow: Align left edges
* CTRL+F9: Align horiz center
* SHIFT+F9: Align vert centers of selected nodes
* CTRL+right-arrow: Align right edges
* CTRL+=: Align left and right edges of selected nodes
* CTRL+up-arrow: Align tops of selected nodes
* CTRL+down-arrow: Align bottoms of selected nodes

These shortcuts use two keystrokes in sequence -- not pressed together:
* =,right-arrow: Make selected nodes the same width as the first selected node
* =,down-arrow: Make selected nodes the same height as the first selected node
* =,=: Make selected nodes the same width and height as the first selected node

=== Shortcuts for Table Navigation ===

Analytica supports almost all the standard shortcuts for tables offered by Microsoft Excel. See [[Shortcuts for Table Navigation]] for details.

=== Alphabetic list of CTRL shortcuts by letter ===

* CTRL+A: Select All nodes in a diagram, text in a definition, or cells in a table.
* CTRL+B: Open [[Number Format Dialog]]
* CTRL+C: Copy selected node(s), text, cell or region of a table.
* CTRL+D: Duplicate selected node(s)
* CTRL+E: Edit definition of selected node in Attribute pane
* CTRL+F: Open [[Find Dialog]] to find an object by identifier or title. In a table, Find will search table.
* CTRL+G: Find next matching item from [[Find Dialog]].
* CTRL+H: Find object with identifier matching the text you have selected -- e.g. in a definition.
* CTRL+I: Insert a new row or column after the row or column you have selected in an Edit table.
* CTRL+J: In a Diagram, align selected node(s) to grid
* CTRL+K: Kill (delete) the row or column you have selected in an Edit table.
* CTRL+L: Open dialog to Add Module...
* CTRL+M: Make an alias from the selected node(s).
* CTRL+N: Start a New Model
* CTRL+O: Open a model file
* CTRL+P: Print the current Diagram, Graph
* CTRL+Q: Exit (Quit) the model.
* CTRL+R: Show result for selected variable(s)
* CTRL+S: Save the model
* CTRL+T: Adjust selected node(s) to their default size
* CTRL+U: Open Uncertainty Options... dialog
* CTRL+V: Paste text, cell or region of a table, or selected nodes.
* CTRL+W: Close the model
* CTRL+X: Cut selected text or node(s).
* CTRL+Y: Toggle between viewing titles and identifiers
* CTRL+Z: Undo last action (typing text or moving or resizing node(s)
* CTRL+. (CTRL+dot): Stop the computation in progress.
* CTRL+Break: Stop the computation in progress.
* CTRL+' (CTRL+apostrophe): Open/close Typescript window. On some non-English keyboards, this combination is not available. In those cases, use F12.

== See also ==

[[Shortcuts for Table Navigation]]

Choice

2024-07-15T17:17:05Z

Max: /* Separator */

[[Category:Functions that select part of an array]]
[[Category:Top level functions]]
[[Category: Menus]]
[[Category:User-interface functions]]
{{ReleaseBar}}

== Choice(i, n) ==
[[Choice]] displays a drop-down menu to allow an end user to select from a list of options. The index «i» is the list of options -- an index containing the values appearing on the popup. When <code>I: Self</code>, the values listed in the variable's domain are used. «N» is the position of the currently selected option in that list, or 0 for ''All''. This should always be an explicit integer, not an expression.

When the user selects a different option, it changes the value of «n». You can use Choice to provide a menu as the definition of a variable or in a cell of an Edit table (or [[ProbTable]] or [[DetermTable]]). [[Choice]] must be the top level of the definition or the cell, and may not be nested within an expression. You must create an Input node for the variable before it will display choices as menus.

When a user changes the selection using the dropdown, the second parameter in the definition is replaced with the new choice.

Use [[Choice]] when you was the user to select only a single option at a time, or (optionally) every option. If you would like the user to be able to select any subset of options, use [[MultiChoice]]. A [[Slider]] is also another possible UI control for selecting a single value at a time.

The full declaration of Choice() is:
:[[Choice]](I: Index; n: atomic nonNegative; inclAll: optional boolean = True; Eval: optional boolean = True; Result: optional Array[I], separator: optional text)

==Optional parameters==
===InclAll===
«inclAll» (default <code>True</code>) specifies whether the "All" option is displayed.

By default, the menu will include ''All'' as the first option. If you choose ''All'', the result will be computed for each value of index «i». This makes it easy to do a parametric analysis to see how the choices affect the results. When you choose ''All'', it sets parameter «n» to 0.

If you select ''All'' for multiple Choice menus, results will be computed for all combinations of values from those menus. Each selection of All may add an index dimension to the results. So if there are more than two or three, the number of dimensions may make the result hard to understand, and long to compute. In a few cases, the model may not be able to compute correctly with ''All''. In such cases, you can turn off ''All'' as an option by setting an optional third parameter, «inclAll» to <code>False</code> (0). It usually advisable to set «inclAll» to <code>False</code> whenever you use [[Choice]] in an Edit table.

===Eval===
The «Eval» parameter specifies whether [[handle]] or expression terms are evaluated for the return value.

The «Eval» parameter has no effect when the Result parameter is specified, or when «I» contains only constants, such as numbers and text strings. Setting «Eval» to false is recommended in most cases when «I» contains [[handle]]s (variable identifiers). The «Eval» parameter has no effect when «I» is Self (it is always treated as false).

===Result===
The [[Choice]] function has an optional parameter, «Result», that can be used to specify the value returned when Choice is evaluated in a completely general manner: «Result» specifies a return value for each choice different from the value in «I». Using the «Result» parameter, the result of evaluating Choice can be totally separate from the value appearing on the pull-down itself.

Choice normally returns the selected index label. The following syntax returns the index position (rather than label) of the selected value:

:<code>Choice(I, 1, Result: @I)</code>

Suppose you have a table <code>A</code> indexed by <code>I</code>, and you want your user to select a row of <code>I</code>, and then select out only the selected row. A standard formulation of this is:
:<code>Variable A := Table(I)(...)</code>
:<code>Decision selectedRow := Choice(I, 1)</code>
:<code>Variable selectedA := A[I = selectedRow]</code>

Using the «Result» parameter, a variable can be eliminated:
:<code>Variable A := Table(I)(...)</code>
:<code>Decision selectedA := Choice(I, 1, Result: A)</code>

When the «Result» parameter is specified, the «Eval» parameter does nothing.

=== Separator===
You can specify that certain items in <code>I</code> are to display as separators. Separators are horizontal lines on the popup that are nonselectable. To include separators, use the «separator» parameter to specify what value in «I» should display as a separator. You can include that value in <code>I</code> multiple times for multiple separators:

:<code>Choice(I, 1, separator:'---')</code>

:<code>Index Country_S := ['Canada', 'Mexico', 'USA', '---',</code>
::<code>'England', 'France', 'Germany', 'Russia', '---',</code>
::<code>'China', 'India', 'Japan','Philippines', '---',</code>
::<code>'Australia', 'New Zealand', '---',</code>
::<code>'Argentina', 'Brazil', 'Chile']</code>

:<code>Variable Select_country := Choice(Country_S, 1, separator:'---')</code>

:[[image:choice_with_separators.png]]

=== labels and selectionLabels ===
'''New to [[Analytica 6.4]]''

These optional parameters enable you to display values in the popup menu or in the control that are different from the index values in «<code>I</code>». Without these, the index values appear. When used, these should be indexed by <code>I</code>. In the case of a Self-choice, you may need to supply a list of values, which has the disadvantage that it cannot adapt to changes in length or re-orderings of the domain value. You can also supply images for either -- if you do so, keep them small. They are not resized from the original size.

«labels» contains the values that appear on the popup menu. When «selectionLabels» isn't also specified, these are also used for the selected value in the control itself.

«selectionLabels» contains the values that appear as the selected value in the control itself.

'''Example 1: City selection'''

This example of selecting a city from a hierarchical menu provides an example where it is convenient to have different values for the index value (the result), the «labels» and the «selectionLabels». A given city name often appears in multiple states, for example Salem, Oregon and Salem, New York. To keep index elements unique, the values in the index have the full name in the form <code>"Oregon, Salem"</code>, etc.

:<code>Index City := ["Alabama, Auburn", "Alabama, Florence", "Alabama, Marion", ...]</code>

:<code>Variable State_name := [[FindInText]]("^(.+),",City,subpattern:1,return:'S')</code>
:<code>Variable City_name := [[FindInText]](",\s*(.+)\s*$",City,subpattern:1,return:'S')</code>

<code>State_name</code> and <code>City_name</code> are indexed by <code>City</code>.

Our city selection can now present only the city name on the menus, but the full name in the selection (and result):
:<code>Variable Choose_city := [[Choice]]( City, 8, inclAll:False, labels:City_name, selectionLabels:City, nestUnder: State_name )</code>
:→
:[[image:city select hierarchy.png]]

'''Example 2: Color picker'''
A second example where it is useful for the labels to be different from the index values is a color picker. The <code>Color</code> index can contain the color names or RGB integers, whereas the choice contains color swatches (images).

:<code>Index Color := ['red','white','blue','orange','green']</code>
:<code>Variable Color_swatch := [[CanvasImage]]( [[Canvas]]( 10, 25, Color ]] )</code>

:<code>Variable Choose_color := [[Choice]]( Color, 1, labels:Color_swatch)</code> →
::[[image:Color_picker_choice.png]]

The result of <code>Choose_color</code> is <code>"Green"</code>.

=== nestUnder for hierarchical menus ===
''New to [[Analytica 6.4]]''

This optional parameter lets you organize the options into hierarchical submenus. The parameter should be a 1-D array indexed by «<code>I</code>». The entries must all be text or Null. Text entries contain the name of the submenu. Multiple levels of submenus are separated by '>'. For example, consider a <code>City</code> index with this «nestUnder» array:

::Variable City_submenus → [[image:City_submenus.png]]

Then <code>[[Choice]]( City, 1, nestUnder: City_submenus )</code> produces this multilevel pulldown:

::[[Image:nestUnderEx.png]]

In this example, Arizona and Nevada are only one level deep, each with a single element, while San Jose is two levels deep, with counties, and cities within each county.

==Examples==
Suppose multiple variables use [[Choice]](I, n) with the same index <code>I</code>, and you choose ''All'' for each of them, e.g.
:<code>Index I := ['Low', 'Mid', 'High']</code>
:<code>Variable A := Choice(I, 0)</code>
:<code>Variable B := Choice(I, 0)</code>
:<code>Variable Result := IF A = 'Low' AND B = 'Low' THEN 0 ELSE 100 →</code>
::<code>Array(I, [0, 100, 100])</code>

<code>Result</code> is indexed by I only once, and A and B are treated as if they have the same values. If you wanted to vary them independently, they should use different indexes, e.g.
:<code>Index I := ['Low', 'Mid', 'High']</code>
:<code>Variable A := Choice(I, 0)</code>
:<code>Index J := CopyIndex(I)</code>
:<code>Variable B := Choice(J, 0)</code>
:<code>Variable Result := IF A = 'Low' AND B = 'Low' THEN 0 ELSE 100 →</code>
::<code>Array(I, J, [0, 100, 100], [100, 100, 100], [100, 100, 100])</code>

The function [[CopyIndex]](I) makes returns a new index with the same values as <code>I</code>.

==Details and more examples==
=== Self-Indexed Choices ===
When a variable is defined with the first parameter set to [[Self]], as in the definition:
:<code>Choice(Self, 0)</code>

then the set of values appearing in the choice are located in the variable's own domain attribute. In this case, the domain must be either a list, list-of-labels or index type.

The easiest way to create a Self-Choice is to select "Choice..." from the definition type popup. Analytica will then fill in a default one-element list-of-labels selection.

When a domain is a list, the elements are usually numbers, but may also be variable identifiers or expressions. (See "Identifier and Expression items" below).

If you use an Index domain, then the values for domain of [[Self]] come from another index variable. In this case, <code>Choice(Self,1)</code> when <code>domain = I</code> is very similar to <code>Choice(I,1)</code> with no domain set. There are, however, several differences.

First, if you use an index domain, then your variable will have both an index value and mid/prob values, while if you use <code>Choice(I, 1)</code> your variable will not have an index semantics.

Second, if "All" is selected in the pulldown, the result of <ode>Choice(I, 0)</code> is indexed by <code>I</code>, while <code>Choice(Self, 0)</code> is indexed by [[Self]].

Third, in an index domain using Index I, the values in the domain are the evaluated values of <code>I</code>. If <code>I</code> contains only numbers and text strings, then these are the same as the values of <code>I</code>, but if <code>I</code> contains identifiers or expressions, then there is a difference. <code>Choice(I, 1)</code> would show the identifiers or expressions, while <code>Choice(Self, 1)</code> with <code>domain = I</code> would show the values of those variables in the pulldown.

=== Input Nodes ===
Selecting "Make Input" from the Object menu creates a pull-down control that you can position on your diagram as part of a user-interface form.

=== Pull-downs in edit tables ===
You can put a [[Choice]] pulldown menu in a cell of an edit table. Just type the expression, such as <code>Choice(option, 1, 0)</code>. where <code>option</code> is an index containing the possible options. You usually set the third parameter, «inclAll», to 0, so to remove the ''All'' option. Otherwise, if the user selects "All" in a table, array abstraction causes the index <code>option</code> to become an index of the entire value of the table result. Similarly, you can specify [[Choice]] and [[Checkbox]] in the cells of any [[DetermTable]], [[ProbTable]], [[IntraTable]], or [[SubTable]].

When you enter a valid [[Choice]] or [[Checkbox]] expression into a table cell, the cell immediately shows the menu or checkbox. But, you will also see an expression/choice selector near the right top of the window:

:[[image:expr-choice-selector.png]]

If you select the ''expr'' option, you will see all cells as text expressions, so you can review and edit them directly.

In browse mode, these cells with controls always appear as controls. The controls appear as disabled (so you can't change them) in browse mode, unless or until you create an input node for the table.

==== In Analytica 4.0 thru Analytica 4.4 ====

In these earlier versions, there is now expression/choice select, and you can only see the expression in Edit mode, allowing you to edit the definition.

=== Using Choice with DetermTable ===
A useful arrangement is to use [[Choice]] variables for key parameters, especially parameters where you may want to perform a parametric analysis (by selecting "All"), and then organizing tabular data in [[DetermTable]]s (rather than standard Edit Tables). This arrangement looks like the following:

:<code>Decision Scenario := Choice(Self, 0)</code>
:<code>Domain of Scenario : [1, 2, 3, 4]</code>
:<code>Variable A := DetermTable(Scenario)(...)</code>

In this arrangement, the definition of <code>A</code> appears as an edit table, indexed by all domain values of <code>Scenario</code>. However, when evaluated, only the selected row is returned.

With this arrangement, you can compute downstream results for a single <code>Scenario</code> (or other dimension), or for every scenario when "All" is selected. When available memory limits your ability to perform a full parameter analysis across many dimensions (since the number of combinations increases multiplicatively), this setup makes it easy to limit the parametric analysis to only selected dimensions.

A second variation on this is:
:<code>Index AllScenarios := [1, 2, 3, 4]</code>
:<code>Decision Scenario := Choice(Self, 0)</code>
:<code>Domain of Scenario : Index AllScenarios</code>
:<code>Variable A := DetermTable(Scenario)(...)</code>

=== Identifier and Expression Items ===
When an option in «I» is a [[handle]] to a variable, then the pulldown will display either the title of the object or its identifier, depending on whether "Show By Identifier" is selected. The "Show By Identifier" setting is found on the '''Object''' menu and can also be toggled by pressing ''Ctrl+Y'' .

When you want to set up an explicit list of identifiers to select between, the best way to do this is to create an index node and turn on its [[MetaOnly]] attribute. Then set the definition to be a list and enter the identifiers in each cell. You can also compute a list of identifiers.

When the selected item is a [[handle]] to a variable, the result of evaluating the [[Choice]] function will be either the handle or the result of evaluating the handle, as follows. If the «eval» parameter is specified and set to false, or if the «I» option is [[Self]], then the result is the handle. If the «eval» parameter is specified and true, and the «I» parameter is an index (i.e., not [[Self]]), then the result is the result of evaluating the selected variable. When «eval» is not specified, then a handle is returned if «I» is index node with the [[MetaOnly]] attribute set or if «I» species the domain of another variable, or otherwise the result of evaluating the variable is returned.

If you are dealing with Choices involving variable identifiers, using <code>Eval: False</code> is generally preferred. Operations such as comparing the selected value to the original index, or use of a [[DetermTable]] based on the choice variable, function more consistently and less ambiguously. As a comparison, if you return values (e.g., <code>Eval: True</code>), and two variables in the choice happen to have the same value, then an ambiguity over which variable was selected exists, but with <code>Eval: False</code> no such ambiguity exists.

== History ==
Releases prior to Analytica 4.4.2 do not support extremely long option lists on the [[Choice]] popup. In those releases, the choice pulldown displays only the first 254 items, plus the selected item. This limitation is fixed in patch release 4.4.2, where no such limitation exists. If you have many options and for some reason cannot upgrade to 4.4.2 or later, consider creating a 2-stage hierarchical menu, where the first pulldown offers subgroups, and the second shows a the items in that subgroup.

Pulldowns in [[Analytica 4.5]] and later are described [[#In Analytica 4.5 or later|above]].

[[Analytica 6.4]] added an option to add a hierarchical organization to the items by specifying an optional «nestUnder» parameter.

== See Also ==
* [[Choice menu user input]]
* [[Choice menus and Checkboxes in an edit table]]
* [[MultiChoice]]
* [[Checkbox]]
* [[Slider]]
* [[AskMsgChoice]]
* [[MetaOnly]]
* Webinar on [[Analytica_User_Group/Past_Topics#Creating_Control_Panels|Creating Control Panels]]

Assista - Analytica AI Assistant

2024-07-12T16:31:02Z

Max: /* Privacy (or lack of) */

''New in [[Analytica 6.5]]''

The Analytica A.I. assistant, named ''Assista'', is a co-pilot that uses Artificial Intelligence to help you use Analytica and build models.

'''Note: In the early 6.5 alpha builds, it requires Analytica Enterprise or Optimizer to use.'''

Ask Assista for help or support using plain English, or even in other non-English languages. It knows what you are/were currently looking at just prior to switching over to the chat window, and it can access much of your model to provide you answers. It can also carry out many tasks for you in the Analytica UI.

== Inaccuracies ==
It is important to understand that, like other AI systems, it is not always accurate. It makes mistakes and sometimes provides incorrect information. But if it leads you astray today, don't give up on it! We are improving it, and your questions will help it to improve in the future. With time, it will be more and more capable of helping you with all stages of model building and interpreting results.

== Privacy (or lack of) ==

When you use Assista, your questions and some model information are sent to Lumina's servers as well as to OpenAI's servers. We use this information in a variety of ways to improve Assista in the future. We at Lumina take privacy seriouslyl, and will make our best effort to protect this information from uses other than to operate and improve Assista.

If you do not use the A.I. assistant at all, no information is sent, so you need not worry about this when simply using Analytica.

== Scope ==
What types of things can Assista help you with? This section identifies some areas, but these do not fully cover its full scope.

Please ask it for whatever help you need, even if it doesn't match stuff shown here! It may surprise you, but even if it fails, your questions may inform Assista's engineers about what types of capabilities would be useful to focus on.

Assista relies heavily on the documentation attributes (Title, Description, Units) in your model, and on the arrows that you have drawn between variables (even if they aren't yet defined). Keep those populated both for your own benefit, but also to increase the quality of the assistance. You can even ask it to write those descriptions for you.

=== Using Analytica's UI ===

::''How do you ... in Analytica?''

Ask it for the steps required to do something using the Analytica's UI.

Inaccuracies in its steps sometimes occur. But improving this accuracy is our first area of focus.

=== Navigating the Docs ===

As you likely know, the Analytica Docs are extensive. Assista often provides "see also" links it is response to relevant Docs pages.

Ask it for a list of functions of a specified type, for example, Or where you can find more information on something.

This general area is our second focus priority.

=== Performing actions for you ===

In addition to providing steps you need to take to accomplish something from the Analytica GUI, Assista can sometimes do it for you!
* Open the graph of X { or edit table, result table, object window, etc.)
* Change the color of X to blue
* Write this description
* Write this definition.
* ... and more

=== Explaining Analytica concepts ===

Ask it to teach you more about Analytica concepts.

=== Creative formulation ===

Mapping your complex, messy, real world problem to an influence diagram that captures the essential elements is a challenging task for human model builders. This is also one of the most exciting use cases for this new technology, especially in a collaborative analyst-assistant partnership.

Extreme competence at this is a long term future goal for Assista, but there is reason to believe that it could become quite good eventually.

=== Interpreting results ===

How do you interpret results, and how should you act based on the insights you gain from the model?

Today, Assista is unlikely to help much at this. For one, it doesn't yet look directly at the raw numbers or graph images in your results (or in your edit tables), even thought it is aware of your graphing dimensions (axes, keys) and table pivots.

=== Other ===
This list of ideas is by no means complete. If you could use some help while using Analytica, ask it even if it doesn't fall into any of these categories. There is a chance it might, and you might inspire us to extend its capabilities in new directions.

== See also ==
* See some use case examples in [https://downloads.analytica.com/Videos/AI_Series/AAIA_alpha_demo.mp4| a short unpolished demo].

Assista - Analytica AI Assistant

2024-07-12T16:27:58Z

Max: /* Inaccuracies */

''New in [[Analytica 6.5]]''

The Analytica A.I. assistant, named ''Assista'', is a co-pilot that uses Artificial Intelligence to help you use Analytica and build models.

'''Note: In the early 6.5 alpha builds, it requires Analytica Enterprise or Optimizer to use.'''

Ask Assista for help or support using plain English, or even in other non-English languages. It knows what you are/were currently looking at just prior to switching over to the chat window, and it can access much of your model to provide you answers. It can also carry out many tasks for you in the Analytica UI.

== Inaccuracies ==
It is important to understand that, like other AI systems, it is not always accurate. It makes mistakes and sometimes provides incorrect information. But if it leads you astray today, don't give up on it! We are improving it, and your questions will help it to improve in the future. With time, it will be more and more capable of helping you with all stages of model building and interpreting results.

== Privacy (or lack of) ==
It is important to keep in mind that when you use Assista, your questions AND information inside your model will be sent to Lumina's servers as well as to OpenAI's servers, and may be used in a variety of ways to improve Assista in the future. We at Lumina are very privacy conscious in general, and will make our best effort to protect the information from uses other than for Assista improvement.

If you do not use the A.I. assistant at all, no information is sent, so you need not worry about this when simply using Analytica.

== Scope ==
What types of things can Assista help you with? This section identifies some areas, but these do not fully cover its full scope.

Please ask it for whatever help you need, even if it doesn't match stuff shown here! It may surprise you, but even if it fails, your questions may inform Assista's engineers about what types of capabilities would be useful to focus on.

Assista relies heavily on the documentation attributes (Title, Description, Units) in your model, and on the arrows that you have drawn between variables (even if they aren't yet defined). Keep those populated both for your own benefit, but also to increase the quality of the assistance. You can even ask it to write those descriptions for you.

=== Using Analytica's UI ===

::''How do you ... in Analytica?''

Ask it for the steps required to do something using the Analytica's UI.

Inaccuracies in its steps sometimes occur. But improving this accuracy is our first area of focus.

=== Navigating the Docs ===

As you likely know, the Analytica Docs are extensive. Assista often provides "see also" links it is response to relevant Docs pages.

Ask it for a list of functions of a specified type, for example, Or where you can find more information on something.

This general area is our second focus priority.

=== Performing actions for you ===

In addition to providing steps you need to take to accomplish something from the Analytica GUI, Assista can sometimes do it for you!
* Open the graph of X { or edit table, result table, object window, etc.)
* Change the color of X to blue
* Write this description
* Write this definition.
* ... and more

=== Explaining Analytica concepts ===

Ask it to teach you more about Analytica concepts.

=== Creative formulation ===

Mapping your complex, messy, real world problem to an influence diagram that captures the essential elements is a challenging task for human model builders. This is also one of the most exciting use cases for this new technology, especially in a collaborative analyst-assistant partnership.

Extreme competence at this is a long term future goal for Assista, but there is reason to believe that it could become quite good eventually.

=== Interpreting results ===

How do you interpret results, and how should you act based on the insights you gain from the model?

Today, Assista is unlikely to help much at this. For one, it doesn't yet look directly at the raw numbers or graph images in your results (or in your edit tables), even thought it is aware of your graphing dimensions (axes, keys) and table pivots.

=== Other ===
This list of ideas is by no means complete. If you could use some help while using Analytica, ask it even if it doesn't fall into any of these categories. There is a chance it might, and you might inspire us to extend its capabilities in new directions.

== See also ==
* See some use case examples in [https://downloads.analytica.com/Videos/AI_Series/AAIA_alpha_demo.mp4| a short unpolished demo].

What's new in Analytica 6.5?

2024-07-12T16:25:40Z

Max: /* Namespaces */

[[category:What's new pages]]
The current release is [[Analytica 6.4]]. This page is describes new features in the next Analytica release.

The Analytica 6.5 release introduces the '''[[Analytica A.I. Assistant]]'''.

Analytica 6.5 is currently in '''''alpha testing'''''. The alpha stage comes before the beta testing stage, which is when we usually make a preview release available to our users. The pre-beta build(s) very likely contain serious instabilities. We discourage you from using or relying on the alpha build for your "real work". We provide this early release in order to give early access to the A.I. assistant. If you want to be an alpha tester, get started at the [[Beta Tester Page]].

== Assista, the Analytica A.I. Assistant ==

An exciting natural language assistant that can help with things like:
* How do you do X in Analytica?
* Can you do it for me?
* Where can I find more info on «Analytica topic»
* Write this description for me
* Show me «description of something or some result in the model»

and much more, with increasing capabilities expected in the future. Here is [https://downloads.analytica.com/Videos/AI_Series/AAIA_alpha_demo.mp4 a 7 minute unpolished demo video] with some examples.

As of this build, an Analytica Enterprise or Optimizer license is required to use Assista. We intend to fix this shortly and make it available to Professional and Free users in a future build.

== Web service integration ==
The [[ReadFromURL]] function, used to call external web services APIs, has been significantly extended to support:
* Asynchronous HTTP communications
* Ctrl+Break to interrupt it and Windows redraw events while waiting for a slow server response.
* Websocket connections.
* Streaming responses (Server-Sent Events, SSE).

== Built-in functions ==
* New «warningNumber» parameter to [[IgnoreWarnings]]
* New system variable [[Sys_TopLevelModule]]
* A new «silent» flag to [[ConsolePrint]].
* Flag to [[MakeJSON]] to render a local index name with a dot.

== Namespaces ==

It is possible to define a new Namespace for each module and library to prevent clashes when they contain identifiers that are the same as those in another module. Namespaces also let the modeler specify which object identifiers are public -- i.e. may be accessed from outside the module -- or private. '''This is an incomplete feature, and so not an official part of the 6.5 release.''' But it is used by the A.I. assistant client to keep its identifiers separate from your model's. See [[Namespaces]].

== Customizing DTA's UI ==
Advanced library authors can take advantage of some new customization features.
* Allows browse-only modules that aren't filed modules.
* Allows a library to add a menu item or a toolbar button.
* [[RegisterSelectionChangeHandler]] - a mechanism to track changes to what is selected in the UI.

== Misc ==
* Less flashing during diagram redraws.
* The [[NameSize]] default changed from 20 to 40. This is the [[Preferences]] setting that controls the maximum number of characters in an identifier that is auto-generated from a title.

What's new in Analytica 6.5?

2024-07-12T16:23:26Z

Max: /* Namespaces */

[[category:What's new pages]]
The current release is [[Analytica 6.4]]. This page is describes new features in the next Analytica release.

The Analytica 6.5 release introduces the '''[[Analytica A.I. Assistant]]'''.

Analytica 6.5 is currently in '''''alpha testing'''''. The alpha stage comes before the beta testing stage, which is when we usually make a preview release available to our users. The pre-beta build(s) very likely contain serious instabilities. We discourage you from using or relying on the alpha build for your "real work". We provide this early release in order to give early access to the A.I. assistant. If you want to be an alpha tester, get started at the [[Beta Tester Page]].

== Assista, the Analytica A.I. Assistant ==

An exciting natural language assistant that can help with things like:
* How do you do X in Analytica?
* Can you do it for me?
* Where can I find more info on «Analytica topic»
* Write this description for me
* Show me «description of something or some result in the model»

and much more, with increasing capabilities expected in the future. Here is [https://downloads.analytica.com/Videos/AI_Series/AAIA_alpha_demo.mp4 a 7 minute unpolished demo video] with some examples.

As of this build, an Analytica Enterprise or Optimizer license is required to use Assista. We intend to fix this shortly and make it available to Professional and Free users in a future build.

== Web service integration ==
The [[ReadFromURL]] function, used to call external web services APIs, has been significantly extended to support:
* Asynchronous HTTP communications
* Ctrl+Break to interrupt it and Windows redraw events while waiting for a slow server response.
* Websocket connections.
* Streaming responses (Server-Sent Events, SSE).

== Built-in functions ==
* New «warningNumber» parameter to [[IgnoreWarnings]]
* New system variable [[Sys_TopLevelModule]]
* A new «silent» flag to [[ConsolePrint]].
* Flag to [[MakeJSON]] to render a local index name with a dot.

== Namespaces ==

It is possible to define a new Namespace for each module and library to prevent clashes when they contain identifiers that are the same as those in another module. Namespaces also let the modeler specify which object identifiers are public -- i.e. may be accessed from outside the module -- or private. '''This is an incomplete feature,''' and so not an official part of the 6.5 release. But it is used by the A.I. assistant client to keep its identifiers separate from your model's. See [[Namespaces]].

== Customizing DTA's UI ==
Advanced library authors can take advantage of some new customization features.
* Allows browse-only modules that aren't filed modules.
* Allows a library to add a menu item or a toolbar button.
* [[RegisterSelectionChangeHandler]] - a mechanism to track changes to what is selected in the UI.

== Misc ==
* Less flashing during diagram redraws.
* The [[NameSize]] default changed from 20 to 40. This is the [[Preferences]] setting that controls the maximum number of characters in an identifier that is auto-generated from a title.

What's new in Analytica 6.5?

2024-07-12T16:19:06Z

Max: /* Web service integrations */

[[category:What's new pages]]
The current release is [[Analytica 6.4]]. This page is describes new features in the next Analytica release.

The Analytica 6.5 release introduces the '''[[Analytica A.I. Assistant]]'''.

Analytica 6.5 is currently in '''''alpha testing'''''. The alpha stage comes before the beta testing stage, which is when we usually make a preview release available to our users. The pre-beta build(s) very likely contain serious instabilities. We discourage you from using or relying on the alpha build for your "real work". We provide this early release in order to give early access to the A.I. assistant. If you want to be an alpha tester, get started at the [[Beta Tester Page]].

== Assista, the Analytica A.I. Assistant ==

An exciting natural language assistant that can help with things like:
* How do you do X in Analytica?
* Can you do it for me?
* Where can I find more info on «Analytica topic»
* Write this description for me
* Show me «description of something or some result in the model»

and much more, with increasing capabilities expected in the future. Here is [https://downloads.analytica.com/Videos/AI_Series/AAIA_alpha_demo.mp4 a 7 minute unpolished demo video] with some examples.

As of this build, an Analytica Enterprise or Optimizer license is required to use Assista. We intend to fix this shortly and make it available to Professional and Free users in a future build.

== Web service integration ==
The [[ReadFromURL]] function, used to call external web services APIs, has been significantly extended to support:
* Asynchronous HTTP communications
* Ctrl+Break to interrupt it and Windows redraw events while waiting for a slow server response.
* Websocket connections.
* Streaming responses (Server-Sent Events, SSE).

== Built-in functions ==
* New «warningNumber» parameter to [[IgnoreWarnings]]
* New system variable [[Sys_TopLevelModule]]
* A new «silent» flag to [[ConsolePrint]].
* Flag to [[MakeJSON]] to render a local index name with a dot.

== Namespaces ==
Incomplete feature, and thus not an official part of the 6.5 release. But it is used by the A.I. assistant client to keep its identifiers separate from your model's. See [[Namespaces]].

== Customizing DTA's UI ==
Advanced library authors can take advantage of some new customization features.
* Allows browse-only modules that aren't filed modules.
* Allows a library to add a menu item or a toolbar button.
* [[RegisterSelectionChangeHandler]] - a mechanism to track changes to what is selected in the UI.

== Misc ==
* Less flashing during diagram redraws.
* The [[NameSize]] default changed from 20 to 40. This is the [[Preferences]] setting that controls the maximum number of characters in an identifier that is auto-generated from a title.

Beta Tester Page

2024-07-12T16:14:24Z

Max: change wiki to docs

[[Category: Beta testing]]

{{#svarset:betarelease|6.5}}
{{#svarset:prevrelease|6.4}}

If you have an Analytica Enterprise or Optimizer license, then we invite you to try out the new [[Analytica A.I. Assistant]] and other new [[Analytica {{#svarget:betarelease}}]] enhancements with this early '''''alpha''''' build of [[Analytica 6.5]]. Just please beware that this is alpha, and is not at the beta-quality stability level yet. We are making this build available earlier than usual so that you can try out the A.I. assistant. Also keep in mind that the A.I. assistant is going to get better rapidly.

If you have an Analytica Professional license, you won't be able to use the [[Analytica A.I. Assistant|A.I. Assistant]] yet, but check back. We intend to get it working in Professional too, we just have some remaining technical challenges to get that working.









== Why become a beta tester? ==

* Test drive the upcoming release {{#svarget:betarelease}} and start using its [[Analytica {{#svarget:betarelease}}|new features]] immediately.
* Participate in webinars on tips and guides on new features.
* Help improve the final release.
* Check that your models work in the new release. Find any issues while they can still be fixed, ensuring a seamless transition for you and your model users when this release becomes official.

== As a beta tester, we request that you ==

* Read [[What's new in Analytica {{#svarget:betarelease}}?]] for an overview of the new features.
* Sign up as a beta tester by filling in the form when you run the installer.
* Try out the new Analytica enhancements of interest to you.
* [[Beta_Tester_Page/Submitting_a_Bug_Report|Submit a bug report]] if you find an issue
* Keep up-to-date with the latest beta build. Analytica will show you an alert whenever there is a new build ready to install, about every 2 weeks. We may also send you email reminders. See [[Analytica {{#svarget:betarelease}} beta Release Notes| release notes]] for changes and bug fixes in each beta release.
* We encourage you to retain Analytica {{#svarget:prevrelease}} when you install Analytica {{#svarget:betarelease}} beta. That lets you compare their behavior if you suspect a new bug.

== How to start beta-testing ==

Download the installer for the latest beta build, release number 6.5.2.250, from:
* [https://downloads.Analytica.com/ANA6.5/AnaSetup6_5_2_250.exe Analytica {{#svarget:betarelease}} installer]

These beta builds use your existing {{#svarget:prevrelease}} subscription license that is already on your computer. A separate beta license is not required.



== Improve Analytica docs ==

During the alpha and beta testing period, we are still updating these Analytica Docs to reflect new features. [[What's new in Analytica {{#svarget:betarelease}}?]] is the most complete listing of new features, and is also a work in progress. As we approach final release date, this information will be more complete.

As an Analytica user, you are invited to contribute to the docs! Since it's on a wiki (using Mediawiki software, just like Wikipedia), you can add or edit any content. If you find something unclear, incomplete, or just wrong, feel free to fix it yourself. Or add comments, asking someone else to. And you are welcome to add tips or interesting examples.

== Known issues ==

If you find an issue, please let us know about it at <code>support@lumina.com</code>. Please see [[/Submitting a Bug Report|Submitting a bug report]] for instructions on reporting bugs.

'''Note:''' We list only the most important issues here (ones that might impact your ability to use it, or which are likely to be found and reported multiple times). We maintain a comprehensive bug base in-house, which is not accessible outside of Lumina.

== FAQs: Frequently Asked Questions ==

See [[Analytica User FAQs]] for frequently asked questions not specific to {{#svarget:betarelease}} or to beta testing.

Filed modules and libraries

2024-06-27T20:25:16Z

Max:

[[Category:Analytica User Guide]]
[[Category: Concepts]]
<breadcrumbs>Analytica User Guide > Working with Large Models > {{PAGENAME}}</breadcrumbs>

A Model may contain several Modules (including Libraries, which are a subclass of Modules). Usually, Modules and Libraries are embedded in the file of their parent Model, but it is also possible to include them in separate files, known as '''Filed (or linked) Modules and Libraries. This page describes these different classes of Module, and how to create, save, import, and remove them.

__TOC__

=== Module Classes ===

Technically, Module is a [[Class]] of Object. Model and Library are subclasses of the Module class. Each Module (including a Model or Library) is simply a collection of variables and other objects. It has a Diagram view, displaying the objects arranged as nodes with arrows indicating dependencies. It may contain submodules, defining a nested hierarchy of Modules. The Module hierarchy provides a convenient way to organize a complex model, perhaps with hundreds or thousands of variables and other objects.

There are six types of ''module'':
* '''Model''': A top level Module, always saved in a separate file.
* '''Module''': A plain Module that is embedded in its parent Model or other Module.
* '''Filed Module''': A Module used in a parent Model or other Module, but saved in its own file.
* '''Library''': A Module that contains Functions and/or other objects designed for use in multiple Models.
* '''Filed Library''': A library saved in its own file. Analytica is distributed with a set of [[standard libraries]] of this kind. You can also create your own [[User-defined Functions and Libraries|Libraries]] for use by yourself and others.
* '''Form''': A special class of Module that makes it easy to add [[User Input nodes]], and [[User Output nodes]], simply by drawing arrows from a variable to the Form Node, or from the Form Node to a variable, respectively.

The only difference between a Filed Module or Library and a Module or Library embedded in its parent Model is that it is saved as a separate file. When you add a filed Module or Library into a Model, it gives you the choice of keeping it in a separate file or embedding it in the Model file. It's usually best to embed it so that you don't have to remember to include the separate files when you move the Model or share it with other people.

If you leave a module as a separate file, any changes you make to it will also affect any other Models that also link to this filed Module or Library. Sometimes this is useful, for example when several people are working on a Model in parallel, and you want them all to benefit from your improvements. For the same reason, it is dangerous because any change that anyone makes to the filed Module will affect all Models that use it.

=== Add a Module or Library to a Model ===

To add a filed Module or Library to the active Model, use the [[Import a module or library|Add Module dialog]] from the [[File menu]]. It prompts you for the directory and file. If instead, you select '''Add Library''' from the [[File menu]], the file dialog defaults to the directory containing the [[Standard libraries]] distributed with Analytica.

Either way, it gives you the choice to embed the Module or Library into the parent Model or to link to the file.

=== Remove a filed Module or Library from a Model ===

To remove a Module or Library from a Model, first select it. Then, select '''Cut''' or '''Clear''' from the [[Edit menu]], or press the ''delete'' key. If it was embedded, it deletes it. If it was filed, it deletes only the node and link from the parent Module, but not the separate file.

=== To create a library or filed module or library ===

The [[toolbar|Node toolbar]] offers only a standard embedded Module. To make a separately filed Module, Library, or Form, you first create a standard Module and then change its class to what you want.

# Create a module by dragging the module icon from the node palette onto the diagram, and give it a title.
# Create variables, functions and any other objects in the new module, or, if they already exist, drag them into the module.
# [[To_change_the_class_of_an_object|Change the class]] of the module
# If you change the class to a separately filed '''Module''' [[File:Chapter19_14.png]] or '''Library''' [[File:Chapter19_15.png]], a file browser dialog prompts you for a directory and file name.
# If you want the parent Model to load the new filed Module or Library the next time it is opened, use the '''Save''' command from the [[File menu]] to make sure it saves the link to the new file.

===Changing Module Class===

You can change the Class of a Module to another Module Class, including from embedded to filed or vice versa, in the same way that you change the Class of a Variable. (You can't change a Module into a Variable or other non-Module class, or vice versa.) Show its Class in its [[Object Window]], or [[Attribute pane]]. In Edit mode, press on the Class menu and select another Class.

If you change from an embedded to Filed Class, e.g. from Library to Filed Library, it a File browser prompts you to select the file name and directory.

=== Saving changes ===

After you have linked to a filed module or library, the '''Save''' option from the [[File menu]] saves every filed module and library that has changed, as well as the model containing them, in their corresponding files. The '''Save As''' and '''Save A Copy''' options save only the active (topmost window’s) model, filed module or filed library, but not any submodules it may contain.

===Using a Module to Copy stuff from one Model to Another===

Analytica doesn't let you copy and paste objects directly from one Model to another. Here's how to copy variables, functions, modules, or any objects from a model M1 into another model M2:
#Open Model M1.
#Create a new Module by dragging from the Toolbar, and give it a title, say "From M1".
#Drag all the objects you want to copy into that Module.
#Open the [[Attribute panel]] (if needed) by clicking on the key icon at the bottom left corner of the window.
#Select the node for module "From M1"
#Change the [[Attribute panel]] to the ''Class'' view, to show its current class "Module"
#Open the ''Class'' menu and select Filed Module (with page icon inside the module icon) [[File:SelectClass.jpg]]
#When it prompts to save the Module, select the file name (or use the default).
#Now open Model M1
#In Edit mode, select '''Add module...''' from the [[File menu]], and select module "From M1.ana".
#In the '''Add module or library''' dialog, select '''Embed a model''', but leave '''Merge contents''' unchecked.
This reads "From M1.ana" to become a new module into M2. With "Merge contents" unchecked, if any imported object has the same identifier as an existing object in M2, it adds a digit at the end of its identifier, to make no existing object gets overwritten.

=== Managing multiple versions of a model ===

There are several reasons you might need to manage multiple versions of a model:
# While you are developing a model, you want to explore alternative ways to structure it. In this case, it's a good idea to make sure the parts for which you want to try different versions are all in the same module, and the parts that won't change are outside it. That way, once you've explored the variations, you can more easily remember what's changed and what's haven't.
# Similarly, when two or more modelers work on a model in parallel, it's best to agree on who can make changes to which module(s) before you fork the model (start multiple versions). Then you can change those modules to be separately filed. Usually one person takes responsibility for the parent model. Analytica doesn't have a built-in way to prevent "unauthorized" changes to a module, except by saving it as "Browse-only". But you can lock a module using the Windows explorer (see below.) When you recombine the modules (merge them) you can simply copy the changed modules into the same folder as the parent model. When you restart the parent model it will automatically read in the new module versions. At that point you can decide if you want to change them back from separately filed to integrated modules.
# A great way to support multiple modelers and multiple model versions is to use '''Github''', the widely used software source code management tool. Analytica works well with Github. That allows multiple modelers to work simultaneously on the same modules. It tracks who made what changes and makes it easy to compare versions. When you want to merge changes, you can see each change and decide which version of each change you want to use.
# Sometimes you want to create several versions of a model for different applications . One approach is to put all the variables, functions, and so on that are common to all the applications into a separately filed module, and keep the things that change from one version to another in the parent model.

=== Module Attributes ===

Each Module has standard attributes common to any Object, including Identifier, Title, and Description, plus Author(s). If it is a separately filed Module or Library, it also contains Created date, Last Saved date, and File info, containing its file path and name, like a Model object. You can see these in its [[Object Window]].

=== Locking a filed module or library ===

You can use the Windows explorer to lock a filed module or library to prevent users from modifying it, even which they can modify things in a parent model that uses it:
# Close the filed module or library, or close Analytica.
# In Windows Explorer, select the filed module or library.
# Select '''Properties''' from the [[File menu]].
#:[[File:Chapter19_16.png]]
# Check the ''Read-only'' checkbox.
# Close the '''Properties''' window

== See Also ==
* [[Modules and Libraries]]
* [[Standard libraries]]
* [[Additional libraries]]
* [[User Libraries]]
* [[User-defined Functions and Libraries]]
* [[Analytica Libraries and Templates]]
* [[Example Models and Libraries]]
* [[Obfuscated and Browse-Only Models]]

<footer>Invalid variables / {{PAGENAME}} / Import a module or library</footer>

Filed modules and libraries

2024-06-27T19:48:19Z

Max: /* Managing multiple versions of a model */

[[Category:Analytica User Guide]]
[[Category: Concepts]]
<breadcrumbs>Analytica User Guide > Working with Large Models > {{PAGENAME}}</breadcrumbs>

A Model may contain Modules and Libraries. A Library contains functions and other objects for use in other models. Usually, Modules and Libraries are embedded in the file of their parent Model, but it is also possible to include them in separate files, known as filed (or linked) Modules and Libraries. This page describes these different classes of Module, and how to create, save, import, and remove them.

__TOC__

=== Module Classes ===

Technically, Module is a [[Class]] of Object. Model and Library are subclasses of the Module class. Each Module (including a Model or Library) is simply a collection of variables and other objects. It has a Diagram view, displaying the objects arranged as nodes with arrows indicating dependencies. It may contain submodules, defining a nested hierarchy of Modules. The Module hierarchy provides a convenient way to organize a complex model, perhaps with hundreds or thousands of variables and other objects.

There are six types of ''module''a:
* '''Model''': A top level Module, always saved in a separate file.
* '''Module''': A plain Module that is embedded in its parent Model or other Module.
* '''Filed Module''': A Module used in a parent Model or other Module, but saved in its own file.
* '''Library''': A Module that contains Functions and/or other objects designed for use in multiple Models.
* '''Filed Library''': A library saved in its own file. Analytica is distributed with a set of [[standard libraries]] of this kind. You can also create your own [[User-defined Functions and Libraries|Libraries]] for use by yourself and others.
* '''Form''': A special class of Module that makes it easy to add [[User Input nodes]], and [[User Output nodes]], simply by drawing arrows from a variable to the Form Node, or from the Form Node to a variable, respectively.

The only difference between a Filed Module or Library and a Module or Library embedded in its parent Model is that it is saved as a separate file. When you add a filed Module or Library into a Model, it gives you the choice of keeping it in a separate file or embedding it in the Model file. It's usually best to embed it so that you don't have to remember to include the separate files when you move the Model or share it with other people.

If you leave it a separate file, any changes you make to it will also affect any other Models that also link to this filed Module or Library. Sometimes this is useful, for example when several people are working on a Model in parallel, and you want them all to benefit from your improvements. For the same reason, it is dangerous because any change that you or anyone makes to the same copy of filed Module will affect all Models that use it.

=== Add a Module or Library to a Model ===

To add a filed Module or Library to the active Model, use the [[Import a module or library|Add Module dialog]] from the [[File menu]]. It prompts you for the directory and file. If instead, you select '''Add Library''' from the [[File menu]], the file dialog defaults to the directory containing the [[Standard libraries]] distributed with Analytica.

Either way, it gives you the choice to embed the Module or Library into the parent Model or to link to the file.

=== Remove a filed Module or Library from a Model ===

To remove a Module or Library from a Model, first select it. Then, select '''Cut''' or '''Clear''' from the [[Edit menu]], or press the ''delete'' key. If it was embedded, it deletes it. If it was filed, it deletes only the node and link from the parent Module, but not the separate file.

=== To create a library or filed module or library ===

The [[toolbar|Node toolbar]] offers only a standard embedded Module. To make a separately filed Module, Library, or Form, you first create a standard Module and then change its class to what you want.

# Create a module by dragging the module icon from the node palette onto the diagram, and give it a title.
# Create variables, functions and any other objects in the new module, or, if they already exist, drag them into the module.
# [[To_change_the_class_of_an_object|Change the class]] of the module
# If you change the class to a separately filed '''Module''' [[File:Chapter19_14.png]] or '''Library''' [[File:Chapter19_15.png]], a file browser dialog prompts you for a directory and file name.
# If you want the parent Model to load the new filed Module or Library the next time it is opened, use the '''Save''' command from the [[File menu]] to make sure it saves the link to the new file.

===Changing Module Class===

You can change the Class of a Module to another Module Class, including from embedded to filed or vice versa, in the same way that you change the Class of a Variable. (You can't change a Module into a Variable or other non-Module class, or vice versa.) Show its Class in its [[Object Window]], or [[Attribute pane]]. In Edit mode, press on the Class menu and select another Class.

If you change from an embedded to Filed Class, e.g. from Library to Filed Library, it a File browser prompts you to select the file name and directory.

=== Saving changes ===

After you have linked to a filed module or library, the '''Save''' command saves every filed module and library that has changed, as well as the model containing them, in their corresponding files. The '''Save As''' and '''Save A Copy''' In commands save only the active (topmost window’s) model, filed module or filed library.

===Using a Module to Copy stuff from one Model to Another===

Analytica doesn't let you copy and paste objects directly from one Model to another. Here is a way to copy variables, functions, modules, or any objects from a model M1 into another model M2:
#Open Model M1.
#Create a new Module by dragging from the Toolbar, and give it a title, say "From M1".
#Drag all the objects you want to copy into that Module.
#Open the [[Attribute panel]] (if needed) by clicking on the key icon at the bottom left corner of the window.
#Select the node for module "From M1"
#Change the [[Attribute panel]] to the ''Class'' view, to show its current class "Module"
#Open the ''Class'' menu and select Filed Module (with page icon inside the module icon) [[File:SelectClass.jpg]]
#When it prompts to save the Module, select the file name (or use the default).
#Now open Model M1
#In Edit mode, select '''Add module...''' from the [[File menu]], and select module "From M1.ana".
#In the '''Add module or library''' dialog, select '''Embed a model''', but leave '''Merge contents''' unchecked.
This reads "From M1.ana" to become a new module into M2. With "Merge contents" unchecked, if any imported object has the same identifier as an existing object in M2, it adds a digit at the end of its identifier, to make no existing object gets overwritten.

=== Managing multiple versions of a model ===

There are several reasons you might need to manage multiple versions of a model:
# While you are developing a model, you want to explore alternative ways to structure it. In this case, it's a good idea to make sure the parts for which you want to try different versions are all in the same module, and the parts that won't change are outside it. That way, once you've explored the variations, you can more easily remember what's changed and what's haven't.
# Similarly, when two or more modelers work on a model in parallel, it's best to agree on who can make changes to which module(s) before you fork the model (start multiple versions). Then you can change those modules to be separately filed. Usually one person takes responsibility for the parent model. Analytica doesn't have a built-in way to prevent "unauthorized" changes to a module, except by saving it as "Browse-only". But you can lock a module using the Windows explorer (see below.) When you recombine the modules (merge them) you can simply copy the changed modules into the same folder as the parent model. When you restart the parent model it will automatically read in the new module versions. At that point you can decide if you want to change them back from separately filed to integrated modules.
# A great way to support multiple modelers and multiple model versions is to use '''Github''', the widely used software source code management tool. Analytica works well with Github. That allows multiple modelers to work simultaneously on the same modules. It tracks who made what changes and makes it easy to compare versions. When you want to merge changes, you can see each change and decide which version of each change you want to use.
# Sometimes you want to create several versions of a model for different applications . One approach is to put all the variables, functions, and so on that are common to all the applications into a separately filed module, and keep the things that change from one version to another in the parent model.

=== Module Attributes ===

Each Module has standard attributes common to any Object, including Identifier, Title, and Description, plus Author(s). If it is a separately filed Module or Library, it also contains Created date, Last Saved date, and File info, containing its file path and name, like a Model object. You can see these in its [[Object Window]].

=== Locking a filed module or library ===

You can use the Windows explorer to lock a filed module or library to prevent users from modifying it, even which they can modify things in a parent model that uses it:
# Close the filed module or library, or close Analytica.
# In Windows Explorer, select the filed module or library.
# Select '''Properties''' from the [[File menu]].
#:[[File:Chapter19_16.png]]
# Check the ''Read-only'' checkbox.
# Close the '''Properties''' window

== See Also ==
* [[Modules and Libraries]]
* [[Standard libraries]]
* [[Additional libraries]]
* [[User Libraries]]
* [[User-defined Functions and Libraries]]
* [[Analytica Libraries and Templates]]
* [[Example Models and Libraries]]
* [[Obfuscated and Browse-Only Models]]

<footer>Invalid variables / {{PAGENAME}} / Import a module or library</footer>

Color Themes Library

2024-06-25T19:00:43Z

Max: /* Apple example node styles as default style */

Use the '''Color Themes Library''' to quickly update your diagram and graph styles with some new and updated preset themes! Simply add the '''Color Themes Library''' into your model to update your model’s theme.

When you open the '''Color Themes Library''', you’ll see the following screen:

[[File:Colorthemeslibrary.jpg|alt=|frameless|600x600px]]

The '''Color Themes Library''' shows examples of each node class, including text, picture, form, and slider defaults as well as an Example Diagram to show how the selected theme looks. To the right of the example nodes there is a button '''Apply example node styles as default style'''. Under these examples there is a '''Select Diagram Theme''' menu which allows you to select theme and other options, and to the right of that menu there is an '''Additional Settings''' module and two buttons, '''Set all nodes to default color and border styles''' and '''Export Anastyle'''. At the bottom of the window is the '''Graph Examples''' menu which allows you to select graph themes and see examples of the selected settings on various graph types.

== Download ==
You can download the Color Themes Library here: [[Media:Color Themes Library.ana|Color Themes Library.ana]]. To use it, simply add the library into your model.

== Notes ==

* Nodes and graphs that already have non-default options selected will not update when defaults are changed. If you have nodes with explicit color and style settings that you would like to revert to model defaults, use the '''Set all nodes to default color and border styles''' button at the bottom right of the library.
* Arrow border colors will only change in Analytica versions 6.3.0 or newer
* [[Slider|Slider bars]] (and styles) will only display in Analytica versions 6.3.0 or newer
* Bar graph outlines will only change in Analytica versions 5.0.7 or newer

== Make a new style ==

[[File:Colorthemeslibrary examplenodes.png|892x892px]]

In Edit Mode you can change the colors and other styles of these example nodes at the top of the library diagram. Use the [[Color palette]] and [[Node Style dialog]]. Once you've set the styles you want, click the '''Apply example node styles as default style''' button to set these styles as the model default style. They will apply to all nodes in the model (except any that have their own nondefault styles). You can then export these styles as an Anastyle using the '''Export Anastyle''' button at the bottom of the library window, so you can easily apply them to other models.

Note that the font styles of these nodes will '''not''' be applied to the default style. The default model font is set in the [[Diagram Style dialog]].

Any changes made to these nodes and the default style will be reset if you select different Diagram colors in the '''Select Diagram Theme''' menu below.

== Select Diagram Theme Menu ==
[[File:Selectdiagramtheme.png|alt=|frameless]]

Use the '''Select Diagram Theme''' menu to update your model’s default theme options. This menu includes the following options:

* Diagram colors
* Node borders
* Font size
* Font

==== Diagram colors ====
The '''Diagram colors''' drop-down select menu allows you to select one of our preset themes. Changing this menu automatically updates model defaults to the selected theme.

The available themes are shown in the table below:
{| class="wikitable"
|+Diagram Color Themes available in Color Themes Library
!2023
[[File:2023theme.png|frameless]]
!2023 Dark
[[File:2023darktheme.png|alt=2023 Dark Colors Theme|frameless]]
|-
!Classic
[[File:Classictheme.png|frameless]]
!Monochrome
[[File:Monochrometheme.png|frameless]]
|-
!Viridis
[[File:Viridistheme.png|frameless]]
!Plasma
[[File:Plasmatheme.png|frameless]]
|}
See the [https://lumina.com/behind-the-scenes-5-3-color-themes/ Lumina Blog] for insight on how the Viridis and Plasma themes were designed.

==== Node borders ====
Use the '''Node borders''' option to select node border style.

Select ''None'' to turn off node borders. Selecting this option will also toggle borders on and off in graphs. ''Monochrome'' sets a single border color for all nodes and ''Color'' sets custom border colors depending on each nodes’ color. See the table below for examples of the options:
{| class="wikitable"
|+Examples of nodes with different Node borders options
!None
!Monochrome
!Color
|-
|[[File:Examplediagramnoborders.png|frameless]]
|[[File:Examplediagramwithstandardborders.png|frameless]]
|[[File:Examplediagramwithnodecolorborders.png|frameless]]
|}
Some themes will automatically update the Include borders option to the selected theme’s default when you change themes, but this option can still be changed according to your tastes.

==== Font Size ====
The '''Font size''' menu allows you to change the font size of your model. This will affect the text and tables in diagrams, graphs, Object View, and Result View.

==== Font ====
The '''Font''' menu allows you to change the font of your model. This will affect the text in diagrams and graphs.

== Graph Examples Menu ==
[[File:Graphexamplesmenu.png|frameless|512x512px]]

The '''Graph Examples''' menu allows you to change your graph theme and view various example graphs. By default, the S'''ame diagram and graph themes''' option is selected and graphs will match the selected '''Diagram colors'''.

If you uncheck the '''Same diagram and graph themes''' option, several menus will appear on the right hand side of the menu. The '''Graph theme''' drop-down menu provides a list of graph theme options for you to choose from. The '''Graph font size''' drop-down menu will change the font size in graphs. And the '''Include graph borders''' checkbox allows you to toggle borders on and off in graphs. Changing these selections will update the graph settings accordingly.

Click the Result icon ([[File:VirtButtonBareIcon6.0.png]]) for each graph type to see an example.

Examples of the available themes are shown in the table below:
{| class="wikitable"
|+Graph Themes available in Color Themes Library
!2023
[[File:Graphin2023theme.png|frameless]]
!2023 Dark
[[File:Graphin2023darktheme.png|frameless]]
|-
!2023 Rainbow
[[File:Graphin2023rainbowtheme.png|frameless]]
!2023 Dark Rainbow
[[File:Graphin2023darkrainbowgraphtheme.png|frameless]]
|-
!Classic
[[File:Graphinclassictheme.png|frameless]]
!Monochrome
[[File:Graphinmonochrometheme.png|frameless]]
|-
!Viridis
[[File:Graphinviridistheme.png|frameless]]
!Plasma
[[File:Graphinplasmatheme.png|frameless]]
|}

== Set all nodes to default color and border styles ==
At the bottom right of the '''Color Themes Library''' is a '''Set all nodes to default color and border styles''' button. Nodes with explicit colors and styles will not update when model defaults are changed. This button reset all nodes with explicit colors and styles so they will use the defaults, ''i.e.'', the colors from the selected theme, again.

== Export Anastyle ==
At the bottom right of the '''Color Themes Library''' is an '''Export Anastyle''' button. Clicking on this button will save the current model's default diagram and graph theme options into an [[Anastyles|Anastyle]] file that can be imported into other models. This way you can easily import your selected options into other models without having to import the '''Color Themes Library''' and select your options again. You can import an Anastyle file to a model the same way you would add a Library into a model.

See [[Anastyles]] for more information.

== Additional Settings ==
[[File:Colorthemeslibrary additionalsettings.png|617x617px]]

The '''Additional Settings''' module is located on the right hand side of the library under the example nodes. Open this module to access Arrow Settings and Corner Settings.

=== Arrow Settings ===
The Arrow settings menu allows you to change the default size and color of arrows.

Use the '''Arrow size''' drop-down select menu to change the arrow size.

Change the arrow color by changing the color of the '''Arrow color''' node, then pressing the '''Apply color''' button beneath it. Your selected color will not be applied as the default color until you press the '''Apply color''' button. Note that you must be in Edit mode to change the Arrow color node. If you are in Edit mode, you can open the Color Palette by right-clicking on the Arrow color node and selecting Show/Hide Color Palette.

=== Corner Settings ===
The Corner Settings menu allows you to change the default corner radius of certain objects.

Use the '''Set corner radius to''' drop-down select menu to select a corner radius. The Null option selects the system default corner radius.

Use the '''For object types''' multi-choice select menu to select which objects the corner radius settings should apply to. Options include Text nodes, Frame nodes, User inputs and outputs, and Buttons.

== Reverting to the Classic Theme ==
If you’re using the '''Color Themes Library''' and would like to go back to the Classic Analytica theme, you can simply select the Classic diagram colors and graph theme options.

Analytica also comes with the default Classic theme saved as an [[Anastyles|Anastyle]] file. You can use this file to revert any model to the Classic Theme without importing the '''Color Themes Library''' using the following steps:

# Go to '''File''' > '''Add Library…'''
# This should open the '''Select Library File''' window. By default this should be open in the '''Libraries''' folder. If not, this '''Libraries''' folder is usually accessible by going to C:/Program Files/Lumina/Analytica/Libraries.
# Open the '''Node Styles''' folder.
# Select the '''Defaults.anastyle''' file and press '''Open'''.

== Release Notes ==
The latest Color Themes Library was released July 6, 2023. Updates include:

* Fixed Export Anastyle bug when Classic theme is selected
* Ability to change example node styles and apply them as default styles
* Arrow Settings and Corner Settings added in Additional Settings module
* Export Anastyle button now exports the current default settings to accommodate any customization made
* Library variable identifiers have now been prefixed to avoid name conflicts when importing into models

Color Themes Library

2024-06-25T18:47:15Z

Max: Enlarged initial diagram

Use the '''Color Themes Library''' to quickly update your diagram and graph styles with some new and updated preset themes! Simply add the '''Color Themes Library''' into your model to update your model’s theme.

When you open the '''Color Themes Library''', you’ll see the following screen:

[[File:Colorthemeslibrary.jpg|alt=|frameless|600x600px]]

The '''Color Themes Library''' shows examples of each node class, including text, picture, form, and slider defaults as well as an Example Diagram to show how the selected theme looks. To the right of the example nodes there is a button '''Apply example node styles as default style'''. Under these examples there is a '''Select Diagram Theme''' menu which allows you to select theme and other options, and to the right of that menu there is an '''Additional Settings''' module and two buttons, '''Set all nodes to default color and border styles''' and '''Export Anastyle'''. At the bottom of the window is the '''Graph Examples''' menu which allows you to select graph themes and see examples of the selected settings on various graph types.

== Download ==
You can download the Color Themes Library here: [[Media:Color Themes Library.ana|Color Themes Library.ana]]. To use it, simply add the library into your model.

== Notes ==

* Nodes and graphs that already have non-default options selected will not update when defaults are changed. If you have nodes with explicit color and style settings that you would like to revert to model defaults, use the '''Set all nodes to default color and border styles''' button at the bottom right of the library.
* Arrow border colors will only change in Analytica versions 6.3.0 or newer
* [[Slider|Slider bars]] (and styles) will only display in Analytica versions 6.3.0 or newer
* Bar graph outlines will only change in Analytica versions 5.0.7 or newer

== Apple example node styles as default style ==
[[File:Colorthemeslibrary examplenodes.png|892x892px]]

At the top of the library are example nodes. While in Edit Mode you can change the styles of these nodes directly using the Node Style menu and Color Palette. The '''Apply example node styles as default style''' button will set the styles of these example nodes as the model default style. This will apply these styles to all nodes in the model using the default model style and allow you to export these styles as an Anastyle using the '''Export Anastyle''' button at the bottom of the library window.

Note that the font styles of these nodes will '''not''' be applied to the default style.

Any changes made to these nodes and the default style will be reset when Diagram colors are changed in the '''Select Diagram Theme''' menu below.

== Select Diagram Theme Menu ==
[[File:Selectdiagramtheme.png|alt=|frameless]]

Use the '''Select Diagram Theme''' menu to update your model’s default theme options. This menu includes the following options:

* Diagram colors
* Node borders
* Font size
* Font

==== Diagram colors ====
The '''Diagram colors''' drop-down select menu allows you to select one of our preset themes. Changing this menu automatically updates model defaults to the selected theme.

The available themes are shown in the table below:
{| class="wikitable"
|+Diagram Color Themes available in Color Themes Library
!2023
[[File:2023theme.png|frameless]]
!2023 Dark
[[File:2023darktheme.png|alt=2023 Dark Colors Theme|frameless]]
|-
!Classic
[[File:Classictheme.png|frameless]]
!Monochrome
[[File:Monochrometheme.png|frameless]]
|-
!Viridis
[[File:Viridistheme.png|frameless]]
!Plasma
[[File:Plasmatheme.png|frameless]]
|}
See the [https://lumina.com/behind-the-scenes-5-3-color-themes/ Lumina Blog] for insight on how the Viridis and Plasma themes were designed.

==== Node borders ====
Use the '''Node borders''' option to select node border style.

Select ''None'' to turn off node borders. Selecting this option will also toggle borders on and off in graphs. ''Monochrome'' sets a single border color for all nodes and ''Color'' sets custom border colors depending on each nodes’ color. See the table below for examples of the options:
{| class="wikitable"
|+Examples of nodes with different Node borders options
!None
!Monochrome
!Color
|-
|[[File:Examplediagramnoborders.png|frameless]]
|[[File:Examplediagramwithstandardborders.png|frameless]]
|[[File:Examplediagramwithnodecolorborders.png|frameless]]
|}
Some themes will automatically update the Include borders option to the selected theme’s default when you change themes, but this option can still be changed according to your tastes.

==== Font Size ====
The '''Font size''' menu allows you to change the font size of your model. This will affect the text and tables in diagrams, graphs, Object View, and Result View.

==== Font ====
The '''Font''' menu allows you to change the font of your model. This will affect the text in diagrams and graphs.

== Graph Examples Menu ==
[[File:Graphexamplesmenu.png|frameless|512x512px]]

The '''Graph Examples''' menu allows you to change your graph theme and view various example graphs. By default, the S'''ame diagram and graph themes''' option is selected and graphs will match the selected '''Diagram colors'''.

If you uncheck the '''Same diagram and graph themes''' option, several menus will appear on the right hand side of the menu. The '''Graph theme''' drop-down menu provides a list of graph theme options for you to choose from. The '''Graph font size''' drop-down menu will change the font size in graphs. And the '''Include graph borders''' checkbox allows you to toggle borders on and off in graphs. Changing these selections will update the graph settings accordingly.

Click the Result icon ([[File:VirtButtonBareIcon6.0.png]]) for each graph type to see an example.

Examples of the available themes are shown in the table below:
{| class="wikitable"
|+Graph Themes available in Color Themes Library
!2023
[[File:Graphin2023theme.png|frameless]]
!2023 Dark
[[File:Graphin2023darktheme.png|frameless]]
|-
!2023 Rainbow
[[File:Graphin2023rainbowtheme.png|frameless]]
!2023 Dark Rainbow
[[File:Graphin2023darkrainbowgraphtheme.png|frameless]]
|-
!Classic
[[File:Graphinclassictheme.png|frameless]]
!Monochrome
[[File:Graphinmonochrometheme.png|frameless]]
|-
!Viridis
[[File:Graphinviridistheme.png|frameless]]
!Plasma
[[File:Graphinplasmatheme.png|frameless]]
|}

== Set all nodes to default color and border styles ==
At the bottom right of the '''Color Themes Library''' is a '''Set all nodes to default color and border styles''' button. Nodes with explicit colors and styles will not update when model defaults are changed. This button reset all nodes with explicit colors and styles so they will use the defaults, ''i.e.'', the colors from the selected theme, again.

== Export Anastyle ==
At the bottom right of the '''Color Themes Library''' is an '''Export Anastyle''' button. Clicking on this button will save the current model's default diagram and graph theme options into an [[Anastyles|Anastyle]] file that can be imported into other models. This way you can easily import your selected options into other models without having to import the '''Color Themes Library''' and select your options again. You can import an Anastyle file to a model the same way you would add a Library into a model.

See [[Anastyles]] for more information.

== Additional Settings ==
[[File:Colorthemeslibrary additionalsettings.png|617x617px]]

The '''Additional Settings''' module is located on the right hand side of the library under the example nodes. Open this module to access Arrow Settings and Corner Settings.

=== Arrow Settings ===
The Arrow settings menu allows you to change the default size and color of arrows.

Use the '''Arrow size''' drop-down select menu to change the arrow size.

Change the arrow color by changing the color of the '''Arrow color''' node, then pressing the '''Apply color''' button beneath it. Your selected color will not be applied as the default color until you press the '''Apply color''' button. Note that you must be in Edit mode to change the Arrow color node. If you are in Edit mode, you can open the Color Palette by right-clicking on the Arrow color node and selecting Show/Hide Color Palette.

=== Corner Settings ===
The Corner Settings menu allows you to change the default corner radius of certain objects.

Use the '''Set corner radius to''' drop-down select menu to select a corner radius. The Null option selects the system default corner radius.

Use the '''For object types''' multi-choice select menu to select which objects the corner radius settings should apply to. Options include Text nodes, Frame nodes, User inputs and outputs, and Buttons.

== Reverting to the Classic Theme ==
If you’re using the '''Color Themes Library''' and would like to go back to the Classic Analytica theme, you can simply select the Classic diagram colors and graph theme options.

Analytica also comes with the default Classic theme saved as an [[Anastyles|Anastyle]] file. You can use this file to revert any model to the Classic Theme without importing the '''Color Themes Library''' using the following steps:

# Go to '''File''' > '''Add Library…'''
# This should open the '''Select Library File''' window. By default this should be open in the '''Libraries''' folder. If not, this '''Libraries''' folder is usually accessible by going to C:/Program Files/Lumina/Analytica/Libraries.
# Open the '''Node Styles''' folder.
# Select the '''Defaults.anastyle''' file and press '''Open'''.

== Release Notes ==
The latest Color Themes Library was released July 6, 2023. Updates include:

* Fixed Export Anastyle bug when Classic theme is selected
* Ability to change example node styles and apply them as default styles
* Arrow Settings and Corner Settings added in Additional Settings module
* Export Anastyle button now exports the current default settings to accommodate any customization made
* Library variable identifiers have now been prefixed to avoid name conflicts when importing into models

Color Themes Library

2024-06-25T18:46:53Z

Max:

Use the '''Color Themes Library''' to quickly update your diagram and graph styles with some new and updated preset themes! Simply add the '''Color Themes Library''' into your model to update your model’s theme.

When you open the '''Color Themes Library''', you’ll see the following screen:

[[File:Colorthemeslibrary.jpg|alt=|frameless|500x500px]]

The '''Color Themes Library''' shows examples of each node class, including text, picture, form, and slider defaults as well as an Example Diagram to show how the selected theme looks. To the right of the example nodes there is a button '''Apply example node styles as default style'''. Under these examples there is a '''Select Diagram Theme''' menu which allows you to select theme and other options, and to the right of that menu there is an '''Additional Settings''' module and two buttons, '''Set all nodes to default color and border styles''' and '''Export Anastyle'''. At the bottom of the window is the '''Graph Examples''' menu which allows you to select graph themes and see examples of the selected settings on various graph types.

== Download ==
You can download the Color Themes Library here: [[Media:Color Themes Library.ana|Color Themes Library.ana]]. To use it, simply add the library into your model.

== Notes ==

* Nodes and graphs that already have non-default options selected will not update when defaults are changed. If you have nodes with explicit color and style settings that you would like to revert to model defaults, use the '''Set all nodes to default color and border styles''' button at the bottom right of the library.
* Arrow border colors will only change in Analytica versions 6.3.0 or newer
* [[Slider|Slider bars]] (and styles) will only display in Analytica versions 6.3.0 or newer
* Bar graph outlines will only change in Analytica versions 5.0.7 or newer

== Apple example node styles as default style ==
[[File:Colorthemeslibrary examplenodes.png|892x892px]]

At the top of the library are example nodes. While in Edit Mode you can change the styles of these nodes directly using the Node Style menu and Color Palette. The '''Apply example node styles as default style''' button will set the styles of these example nodes as the model default style. This will apply these styles to all nodes in the model using the default model style and allow you to export these styles as an Anastyle using the '''Export Anastyle''' button at the bottom of the library window.

Note that the font styles of these nodes will '''not''' be applied to the default style.

Any changes made to these nodes and the default style will be reset when Diagram colors are changed in the '''Select Diagram Theme''' menu below.

== Select Diagram Theme Menu ==
[[File:Selectdiagramtheme.png|alt=|frameless]]

Use the '''Select Diagram Theme''' menu to update your model’s default theme options. This menu includes the following options:

* Diagram colors
* Node borders
* Font size
* Font

==== Diagram colors ====
The '''Diagram colors''' drop-down select menu allows you to select one of our preset themes. Changing this menu automatically updates model defaults to the selected theme.

The available themes are shown in the table below:
{| class="wikitable"
|+Diagram Color Themes available in Color Themes Library
!2023
[[File:2023theme.png|frameless]]
!2023 Dark
[[File:2023darktheme.png|alt=2023 Dark Colors Theme|frameless]]
|-
!Classic
[[File:Classictheme.png|frameless]]
!Monochrome
[[File:Monochrometheme.png|frameless]]
|-
!Viridis
[[File:Viridistheme.png|frameless]]
!Plasma
[[File:Plasmatheme.png|frameless]]
|}
See the [https://lumina.com/behind-the-scenes-5-3-color-themes/ Lumina Blog] for insight on how the Viridis and Plasma themes were designed.

==== Node borders ====
Use the '''Node borders''' option to select node border style.

Select ''None'' to turn off node borders. Selecting this option will also toggle borders on and off in graphs. ''Monochrome'' sets a single border color for all nodes and ''Color'' sets custom border colors depending on each nodes’ color. See the table below for examples of the options:
{| class="wikitable"
|+Examples of nodes with different Node borders options
!None
!Monochrome
!Color
|-
|[[File:Examplediagramnoborders.png|frameless]]
|[[File:Examplediagramwithstandardborders.png|frameless]]
|[[File:Examplediagramwithnodecolorborders.png|frameless]]
|}
Some themes will automatically update the Include borders option to the selected theme’s default when you change themes, but this option can still be changed according to your tastes.

==== Font Size ====
The '''Font size''' menu allows you to change the font size of your model. This will affect the text and tables in diagrams, graphs, Object View, and Result View.

==== Font ====
The '''Font''' menu allows you to change the font of your model. This will affect the text in diagrams and graphs.

== Graph Examples Menu ==
[[File:Graphexamplesmenu.png|frameless|512x512px]]

The '''Graph Examples''' menu allows you to change your graph theme and view various example graphs. By default, the S'''ame diagram and graph themes''' option is selected and graphs will match the selected '''Diagram colors'''.

If you uncheck the '''Same diagram and graph themes''' option, several menus will appear on the right hand side of the menu. The '''Graph theme''' drop-down menu provides a list of graph theme options for you to choose from. The '''Graph font size''' drop-down menu will change the font size in graphs. And the '''Include graph borders''' checkbox allows you to toggle borders on and off in graphs. Changing these selections will update the graph settings accordingly.

Click the Result icon ([[File:VirtButtonBareIcon6.0.png]]) for each graph type to see an example.

Examples of the available themes are shown in the table below:
{| class="wikitable"
|+Graph Themes available in Color Themes Library
!2023
[[File:Graphin2023theme.png|frameless]]
!2023 Dark
[[File:Graphin2023darktheme.png|frameless]]
|-
!2023 Rainbow
[[File:Graphin2023rainbowtheme.png|frameless]]
!2023 Dark Rainbow
[[File:Graphin2023darkrainbowgraphtheme.png|frameless]]
|-
!Classic
[[File:Graphinclassictheme.png|frameless]]
!Monochrome
[[File:Graphinmonochrometheme.png|frameless]]
|-
!Viridis
[[File:Graphinviridistheme.png|frameless]]
!Plasma
[[File:Graphinplasmatheme.png|frameless]]
|}

== Set all nodes to default color and border styles ==
At the bottom right of the '''Color Themes Library''' is a '''Set all nodes to default color and border styles''' button. Nodes with explicit colors and styles will not update when model defaults are changed. This button reset all nodes with explicit colors and styles so they will use the defaults, ''i.e.'', the colors from the selected theme, again.

== Export Anastyle ==
At the bottom right of the '''Color Themes Library''' is an '''Export Anastyle''' button. Clicking on this button will save the current model's default diagram and graph theme options into an [[Anastyles|Anastyle]] file that can be imported into other models. This way you can easily import your selected options into other models without having to import the '''Color Themes Library''' and select your options again. You can import an Anastyle file to a model the same way you would add a Library into a model.

See [[Anastyles]] for more information.

== Additional Settings ==
[[File:Colorthemeslibrary additionalsettings.png|617x617px]]

The '''Additional Settings''' module is located on the right hand side of the library under the example nodes. Open this module to access Arrow Settings and Corner Settings.

=== Arrow Settings ===
The Arrow settings menu allows you to change the default size and color of arrows.

Use the '''Arrow size''' drop-down select menu to change the arrow size.

Change the arrow color by changing the color of the '''Arrow color''' node, then pressing the '''Apply color''' button beneath it. Your selected color will not be applied as the default color until you press the '''Apply color''' button. Note that you must be in Edit mode to change the Arrow color node. If you are in Edit mode, you can open the Color Palette by right-clicking on the Arrow color node and selecting Show/Hide Color Palette.

=== Corner Settings ===
The Corner Settings menu allows you to change the default corner radius of certain objects.

Use the '''Set corner radius to''' drop-down select menu to select a corner radius. The Null option selects the system default corner radius.

Use the '''For object types''' multi-choice select menu to select which objects the corner radius settings should apply to. Options include Text nodes, Frame nodes, User inputs and outputs, and Buttons.

== Reverting to the Classic Theme ==
If you’re using the '''Color Themes Library''' and would like to go back to the Classic Analytica theme, you can simply select the Classic diagram colors and graph theme options.

Analytica also comes with the default Classic theme saved as an [[Anastyles|Anastyle]] file. You can use this file to revert any model to the Classic Theme without importing the '''Color Themes Library''' using the following steps:

# Go to '''File''' > '''Add Library…'''
# This should open the '''Select Library File''' window. By default this should be open in the '''Libraries''' folder. If not, this '''Libraries''' folder is usually accessible by going to C:/Program Files/Lumina/Analytica/Libraries.
# Open the '''Node Styles''' folder.
# Select the '''Defaults.anastyle''' file and press '''Open'''.

== Release Notes ==
The latest Color Themes Library was released July 6, 2023. Updates include:

* Fixed Export Anastyle bug when Classic theme is selected
* Ability to change example node styles and apply them as default styles
* Arrow Settings and Corner Settings added in Additional Settings module
* Export Anastyle button now exports the current default settings to accommodate any customization made
* Library variable identifiers have now been prefixed to avoid name conflicts when importing into models

Items within Budget function

2024-06-20T00:52:18Z

Max: /* Example model */

[[Category: Examples]]
=== Example model ===

'''Description:''' Given a set of items, each with a cost and priority, the function Items_within_budget
returns a vector with 1 or 0 to identify the items selected, with the highest priority items whose cumulative cost is within the specified budget.

'''Keywords:'''

'''Author:''' Max Henrion

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

Weibull estimation library

2024-05-29T02:35:54Z

Max:

[[Weibull distribution]]s are widely used for modeling lifetimes of automobiles, engines, and other equipment. Also for the lifetimes of people. This library includes functions for estimating Weibull distributions for lifespan or time to failure from data, and to obtain mean, median, and variance, and percentiles of a Weibull from its shape (k) and scale (lamda) parameters (and vice versa).

[[File:Weibull estimation lib.png|600px]]

'''Weibull_Estimate(age, i)''' estimates the Weibull parameters from lifespan (age at death) when all population has failed (died).

'''Weibull_est_RC(age, died, i)''' estimates Weibull parameters from lifespan (age at death) or age using "right-censored" (RC) data -- i.e. when some individuals have survived. This function requires the Analytica Optimizer. The other functions will work fine with lesser editions of Analytica

'''Download: ''' [[media:Weibull estimation lib.ana]]

== See Also ==
* [[Weibull distribution]]
* [[Weibull_10_50_90]]
* [[Probability distributions]]

Weibull estimation library

2024-05-29T02:33:37Z

Max:

Weibull distributions are widely used for modeling lifetimes of automobiles, engines, and other equipment. Also for the lifetimes of people. This library includes functions for estimating Weibull distributions for lifespan or time to failure from data, and to obtain mean, median, and variance, and percentiles of a Weibull from its shape (k) and scale (lamda) parameters (and vice versa).

[[File:Weibull estimation lib.png|600px]]

'''Weibull_Estimate(age, i)''' estimates the Weibull parameters from lifespan (age at death) when all population has failed (died).

'''Weibull_est_RC(age, died, i)''' estimates Weibull parameters from lifespan (age at death) or age using "right-censored" (RC) data -- i.e. when some individuals have survived. This function requires the Analytica Optimizer. The other functions will work fine with lesser editions of Analytica

'''Download: ''' [[media:Weibull estimation lib.ana]]

== See Also ==
* [[Weibull estimation library]]
* [[Rayleigh]]
* [[Weibull_10_50_90]]

Weibull estimation library

2024-05-29T02:33:16Z

Max:

Weibull distributions are widely used for modeling lifetimes of automobiles, engines, and other equipment. Also for the lifetimes of people. This library includes functions for estimating Weibull distributions for lifespan or time to failure from data, and to obtain mean, median, and variance, and percentiles of a Weibull from its shape (k) and scale (lamda) parameters (and vice versa).

'''Download:''' [[File:Weibull estimation lib.png|600px]]

'''Weibull_Estimate(age, i)''' estimates the Weibull parameters from lifespan (age at death) when all population has failed (died).

'''Weibull_est_RC(age, died, i)''' estimates Weibull parameters from lifespan (age at death) or age using "right-censored" (RC) data -- i.e. when some individuals have survived. This function requires the Analytica Optimizer. The other functions will work fine with lesser editions of Analytica

'''Download: ''' [[media:Weibull estimation lib.ana]]

== See Also ==
* [[Weibull estimation library]]
* [[Rayleigh]]
* [[Weibull_10_50_90]]

Weibull estimation library

2024-05-29T02:30:35Z

Max:

Weibull distributions are widely used for modeling lifetimes of automobiles, engines, and other equipment. Also for the lifetimes of people. This library includes functions for estimating Weibull distributions for lifespan or time to failure from data, and to obtain mean, median, and variance, and percentiles of a Weibull from its shape (k) and scale (lamda) parameters (and vice versa).

'''Download:''' [[File:Weibull estimation library.png|600px]]

''Weibull_Estimate(age, i)'' estimates the Weibull parameters from lifespan (age at death) when all population has failed (died).

''Weibull_est_RC(age, died, i)'' estimates Weibull parameters from lifespan (age at death) or age using "right-censored" (RC) data -- i.e. when some individuals have survived. This function requires the Analytica Optimizer. The other functions will work fine with lesser editions of Analytica

'''Download: ''' [[media:Weibull estimation lib.ana]]

== See Also ==
* [[Weibull estimation library]]
* [[Rayleigh]]
* [[Weibull_10_50_90]]

File:Weibull estimation lib.ana

2024-05-29T02:27:26Z

Max: Analytica library for estimating Weibull distributions

== Summary ==
Analytica library for estimating Weibull distributions

Weibull estimation library

2024-05-29T02:25:46Z

Max:

Weibull distributions are widely used for modeling lifetimes of automobiles, engines, and other equipment. Also for the lifetimes of people. This library includes functions for estimating Weibull distributions for lifespan or time to failure from data, and to obtain mean, median, and variance, and percentiles of a Weibull from its shape (k) and scale (lamda) parameters (and vice versa).

[[File:Weibull estimation library.png|600px]]

''Weibull_Estimate(age, i)'' estimates the Weibull parameters from lifespan (age at death) when all population has failed (died).

''Weibull_est_RC(age, died, i)'' estimates Weibull parameters from lifespan (age at death) or age using "right-censored" (RC) data -- i.e. when some individuals have survived. This function requires the Analytica Optimizer. The other functions will work fine with lesser editions of Analytica

'''Download: ''' [[media: Weibull estimation lib.ANA]]

== See Also ==
* [[Weibull estimation library]]
* [[Rayleigh]]
* [[Weibull_10_50_90]]