Analytica Docs - User contributions [en]

Objects and Their Attributes - Part 2 of 3

2014-03-05T23:13:36Z

Esherwin: /* Computed Attributes */

[[Objects and Their Attributes - Part 1 of 3|<<prev]] | [[Objects and Their Attributes - Part 3 of 3|next>>]]

==User-Specified Attributes==

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

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

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

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

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

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

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

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

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

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

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

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

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

==Computed Attributes==

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

'''Savedate''' The last time the model was saved.

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

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

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

'''Value''' The deterministic value of a variable.

'''Probvalue''' The probabilistic value of a variable.

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

'''Isin''' The model to which an object belongs.

==User Interface Attributes==

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

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

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

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

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

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

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

'''Nodeinfo''' ''version, showinputs, showoutputs, showlabel, showborder, fill, usenodefont, formwidth, showbevel, showformicon, embed'' 
Controls display options for a node, including arrows, node border, label and so on.

*''version'' indicates the version of this attribute's format; 1 in the current version of Analytica
*''showinputs, showoutputs, showlabel, showborder, fill, usenodefont, showbevel'' and ''showformicon'' have values of 0 (for off) or 1 (for on). ''Showformicon'' only applies to output nodes.
*''formwidth'' specifies the width of an input node’s or output node’s field (0 is the default, which means the actual width will be computed based on the font size).
*''embed'': Not currently implemented (in 4.1). For an input node with an underlying table, a value 0 indicates that a button should appear to bring the edit table up in a separate window. A value 1 indicates that the edit table should be embedded in the diagram. For an output variable with an array result, 0 indicates that a ''Calc'' or ''Result'' button should appear that opens the result in a separate window, 1 indicates that the result should be embedded. If you embed a table or graph, you need to size your control to be large enough to accommodate it. If this is unset, Analytica and AWP will assume the intention is to embed when the control is taller than 5 lines of text, or about 60 pixels.

'''DiagramColor''' 
red, green, blue

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

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

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

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

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

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

'''Reformdef [''' ''col, row'' ''']''' 
'''Reformval [''' ''col, row'' ''']''' These are row/column reform state attributes for Edit Table and Result windows, respectively. col and row, inside brackets specify the index variable for the column and row, respectively.

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

*version is the current format version (1.0)
*formatcode has the following values:

code name example
D Suffix 1.235K
E Expoential 1.235e+4
F Fixed point 12345.68
I Integer 12346
% Percent 1234567.80%
DD Date Tue, Oct 19, 1937
DB Boolean True

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

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

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

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

==Inspecting Objects==

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

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

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

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

Example>'''title mpy'''
miles per year
Example>

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

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

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

Example>value mpy
12K
Example>

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

[[Objects and Their Attributes - Part 1 of 3|<<prev]] | [[Objects and Their Attributes - Part 3 of 3|next>>]]

Objects and Their Attributes - Part 2 of 3

2014-03-05T23:13:07Z

Esherwin:

[[Objects and Their Attributes - Part 1 of 3|<<prev]] | [[Objects and Their Attributes - Part 3 of 3|next>>]]

==User-Specified Attributes==

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

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

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

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

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

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

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

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

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

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

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

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

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

==Computed Attributes==

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

'''Savedate''' The last time the model was saved.

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

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

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

'''Value''' The deterministic value of a variable.

'''Probvalue''' The probabilistic value of a variable.

'''Contains''' The list of variables and other objects created within a model.
'''Isin''' The model to which an object belongs.

==User Interface Attributes==

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

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

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

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

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

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

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

'''Nodeinfo''' ''version, showinputs, showoutputs, showlabel, showborder, fill, usenodefont, formwidth, showbevel, showformicon, embed'' 
Controls display options for a node, including arrows, node border, label and so on.

*''version'' indicates the version of this attribute's format; 1 in the current version of Analytica
*''showinputs, showoutputs, showlabel, showborder, fill, usenodefont, showbevel'' and ''showformicon'' have values of 0 (for off) or 1 (for on). ''Showformicon'' only applies to output nodes.
*''formwidth'' specifies the width of an input node’s or output node’s field (0 is the default, which means the actual width will be computed based on the font size).
*''embed'': Not currently implemented (in 4.1). For an input node with an underlying table, a value 0 indicates that a button should appear to bring the edit table up in a separate window. A value 1 indicates that the edit table should be embedded in the diagram. For an output variable with an array result, 0 indicates that a ''Calc'' or ''Result'' button should appear that opens the result in a separate window, 1 indicates that the result should be embedded. If you embed a table or graph, you need to size your control to be large enough to accommodate it. If this is unset, Analytica and AWP will assume the intention is to embed when the control is taller than 5 lines of text, or about 60 pixels.

'''DiagramColor''' 
red, green, blue

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

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

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

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

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

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

'''Reformdef [''' ''col, row'' ''']''' 
'''Reformval [''' ''col, row'' ''']''' These are row/column reform state attributes for Edit Table and Result windows, respectively. col and row, inside brackets specify the index variable for the column and row, respectively.

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

*version is the current format version (1.0)
*formatcode has the following values:

code name example
D Suffix 1.235K
E Expoential 1.235e+4
F Fixed point 12345.68
I Integer 12346
% Percent 1234567.80%
DD Date Tue, Oct 19, 1937
DB Boolean True

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

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

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

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

==Inspecting Objects==

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

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

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

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

Example>'''title mpy'''
miles per year
Example>

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

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

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

Example>value mpy
12K
Example>

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

[[Objects and Their Attributes - Part 1 of 3|<<prev]] | [[Objects and Their Attributes - Part 3 of 3|next>>]]

What's New in Analytica 4.5?

2013-12-20T01:48:40Z

Esherwin:

This page describes enhancements introduced in Analytica 4.5 since [[Analytica 4.4]].
Analytica 4.5 also includes bug fixes and improvements to robustness too numerous to list here.

= Free 101 Edition =

* As its name implies, the Analytica Free 101 costs nothing.

* It lets you use the full features of Analytica Professional to build models with up to 101 user-created objects.

* If you use it to open a model with more than 101 objects, or expand a model up to 101 objects, it reverts to the features of the Analytica Player: You can still open and review the model, change inputs, and generate results as tables and graphs. But, it is locked in Browse mode, so it won't let you edit the model or add more objects. However, you can save the model with changed inputs.

* The Analytica Free 101 edition replaces the previous Analytica Trial and Analytica Player editions.

* Analytica Free 101 offers all features for Analytica Professional but not features of Analytica Enterprise or Optimizer: So, it doesn't offer spreadsheet and database access.

* Analytica Free 101 does let you use and distribute models for free use by others using the Analytica Cloud Player (ACP) or Power Player.

* Watermarks appear on diagrams, graphs, copied images, and printouts indicating that they were generated with the Analytica Free 101 edition.

* Click [http://www.lumina.com/products/free101/ here] to download Analytica Free 101.

= Promotional Quickstart Pricing =

To celebrate the release of 4.5, [http://www.lumina.com/services/analytica-quick-start/ Quickstart packages] are now only $495 for a limited time (normally $800)!

A Quickstart package gives you '''4 hours of one-on-one guidance''' via email, phone or web-based meeting, from an experienced Analytica professional.

= 64-bit Editions =

There is no longer a price difference between 32-bit and 64-bit editions. As long as you are running 64-bit Windows, you can install either.

If your are upgrading from an earlier release and your support is active, the Analytica 4.5 64-bit installer will automatically upgrade you to a 64-bit license.

= Unicode and International Alphabets =

Analytica supports unicode (instead of Ascii) for models. This means that you can use almost any alphabet for object identifiers, titles, units, descriptions, and any other attribute that accepts text, including file names. Alphabets includes Chinese, Greek, Japanese, Russian, Greek, or just about any language with letters or characters from extended Unicode characters ([[Chr]](1) to [[Chr]](65535)). (Arabic and Hebrew are available, but it doesn't display text right-to-left.) You can also include accents, mathematical symbols and numerous icons. Here's part of the Bond Model in Chinese: [[image:ChineseBondModel.png|right|420px]]

The user interface is not internationalized: Text in menus, dialogs, help, software documentation, and so on are still in English.
(The PDF guides (Tutorial, User Guide, Optimizer Guide) are also available in Chinese.)

== [[Collation Order]] ==

Analytica's comparison operators (e.g., < and >) and sorting functions (e.g., [[SortIndex]], [[Rank]], [[Sort]]) now compare text using language-specific collation order. Formerly, they compared text using the ascii values of each character. For non-English text, ascii order (also known as ansi order) does't always correspond to the natural ordering of text. For example, an accented é does not come between the letters d and f in ansi order.

A new system variable, <code>[[TextLocale]]</code>, specifies the collation order. The value usually indicates a language, or language and region (e.g., "English", "English_US", "Spanish"). You can still use the old-style ansi-order, by setting it to "Ansi". See [[Collation Order]].

== Accent awareness ==

Analytica treats accented characters more logically. For example, functions [[TextUpperCase]] and [[TextLowerCase]], and the automatic generation of an identifier from a title that you type, behave appropriately when accents are present.

== Model file format ==

To accommodate Unicode text fields, Analytica stores model files using the [http://en.wikipedia.org/wiki/UTF-8 UTF-8 character encoding] instead of ANSI encoding.

The [http://en.wikipedia.org/wiki/UTF-8 UTF-8 encoding] is the same as ANSI for basic characters -- i.e., those with ascii values below 128, including English alphabet letters, numbers and standard punctuation. So, there is no change for models that only use these basic characters. This ensures forward compatibility of existing model files. Extended characters -- the most common being letters with accents and some non-US currency symbols -- each use two bytes in the model file.

== Remapped characters ==

The ascii value of some extended characters is now different. If these appear in your legacy model, they'll be converted and you'll never know it. But if you use the [[Chr]] or [[Asc]] functions, you might notice this difference.

The characters with ascii values from 128 thru 160 are not the same in ANSI (aka ISO-8859-1) and Unicode. So these characters are remapped. The characters ≠, ≤ and ≥, previously with ascii values of 173, 178 and 179, now have the standard unicode values of 8800, 8804 and 8805.

== Month and weekday names ==

Month and weekday names in date formats display those in the regional language even when they include characters outside of the ascii range. Previously names with non-ascii characters would revert to their English equivalent.

= Editing expressions =

== Enumerated parameter assist ==

When typing a definition and at a parameter with an enumerated set of possible values, Expression Assist now shows you the list of possible values and what they mean:

[[image:Enumerated Parameter Assist.png]]

== Indentation and Tabs ==

While editing a definition (or other text attribute), the TAB key will indent the line (inserting a Tab character) to make it easier to write indented text. When writing nested multiline expressions, indenting lets you make them much easier to read.

Here's how it works when you are editing a Definition or other attribute in the Attribute pane or Object window:
* If Expression Assist is suggesting an identifier or word completion, TAB inserts the selected item.
* If you have selected text in one or more lines in edit mode, press TAB to indent the line(s).
* Or press Shift+TAB to remove one level of indent for the selected line(s).
* If you are typing in an attribute field, Tab inserts a tab character, which lines up the next character at a fixed pixel position, spaced approximately 4 typical characters widths apart.
* In the Object Window, pressing TAB selects the next attribute in the window -- except if you are editing the attribute (if you have clicked in it or move the cursor in it) it indents the selected line(s), as described above.

= Exporting and importing data =

== Refinements to the [[Export-Import data format]] specification ==

The [[Export-Import data format]] is used by the '''File→Export''' and '''File→Import''' menu commands, and by '''Copy Table''', as a representation for exchanging multidimensional arrays. It is described in the last section of Chapter 19 of the Analyica User Guide.

* There were ambiguities in the original specification, largely relating to differentiating between text that wasn't quoted and expressions or identifiers. The original specification also did not address how multiline cell values should be represented, or values containing the tab character. A more precise specification of the format has been created. The user guide description has been updated, the [[Export-Import data format|Wiki specification]] has the more formal and precise specification.

* Multidimensional tables and arrays containing distribution functions, multiline cell values, identifiers, expressions, and tab characters can now be successfully exported and imported. (these cases did not work previously due to ambiguities).

* A new built-in function, [[ReadExportFile]], has been added which can be used to read in a file in the [[Export-Import data format]]. (we are aware of the obvious omission of WriteExportFile that isn't yet available).

* The old typescript commands [[Export]] and [[Import]] work with the updated format. (prior to 4.5, [[Import]] was not there but didn't work).

== Index Correspondence ==

* When you import a saved or copied multidimensional array into an edit table, the indexes of the saved array need to be matched (or ''corresponded'') with the indexes of the table. That correspondence can be quite confusing since the tables may be pivoted differently, or may be based on different indexes having either the same length or same elements. The logic for making this correspondence has been greatly enhanced, so that it is now much smarter about recognizing intended correspondences across a variety of cases. The details are described in [[Export-Import_data_format#Index_Correspondence|Index Correspondence]]. What this means for you:
** When copying a table to another that uses the same indexes, it'll work even if you don't get the pivot the same.
** When source and destination tables have different indexes, but of the same lengths, you can remove any ambiguities by making the pivot the same.

= Engine and language enhancements =

== Complex Numbers ==

[[Complex Numbers|Complex numbers]] are now built-in and exposed, relevant built-in functions are complex-number aware, and several new built-in functions are now present for manipulating complex numbers, including: [[RealPart]], [[ImPart]], [[ComplexRadians]], [[ComplexDegrees]] (use [[Abs]] for magnitude), [[FFT]] and [[FFTInv]].

To type a complex number, use an i or j suffix, for example: -2j or 4+3i. Complex numbers display in 3-4j format in result table cells. Graphs display [[RealPart]](x).

If you try to evaluate <code>[[Sqrt]](-4)</code>, the result depends on whether you have enabled complex numbers. If you have not, you'll be warned that you are taking the square root of a negative number and, if you ignore warnings, the result will be [[NaN]]. If you enable complex numbers, the result will be <code>2j</code>. To enable complex numbers, select '''Definition → System Variables → EnableComplexNumbers''' from the menus (with no object selected).

See [[Complex Numbers]] for more details.

== Fixed real precision arithmetic ==

Analytica now uses fixed-precision (also known as fixed-point) to represent numbers when it can, instead of floating point. Fixed-precision is an exact representation, so this avoids occasional issues of round-off error that occur with floating point.

For example, the number 0.07 has no exact binary floating point representation. The closest floating-point value is roughly 0.07000000000000001. This tiny error can become magnified by certain arithmetic operations, such as
: <code>(0.07 * 10 - .7) * 1e+16</code>
With floating point arithmetic, this gives a result slightly greater than 1, even though the result should be zero. In Analytica 4.5, the use of fixed point arithmetic produces the exact result of 0.

Fixed precision uses an exact representation for numbers with up 6 decimal digits with absolute value less than 9 trillion -- more precisely, for x where Abs(x) <= 9,223,372,036,854.775807. Fixed-precision arithmetic preserves fixed-precision for results when possible. Operations that cannot guarantee a fixed-point result fall back to floating point precision.

== Repeated parameter forwarding ==

Have you ever needed to [[Sum]] over all the indexes of an array, without necessarily knowing what indexes are present in advance? A new language extension called [[Repeated Parameter Forwarding]] allows you to do this using
:<code>[[Sum]](A,...indexesOf(A))</code>

In general, this extension allows you to compute a list of values and pass them to a repeated function parameter. For more details, see [[Repeated Parameter Forwarding]].

== Subscript warning ==

When you use [[Slice]] or [[Subscript]] to re-index to a larger index, a warning is no longer issued about elements that are not found in the source index. For example, suppose
:Index I := 1..10
:Index J := 1..100
Then <code>A[I=J]</code> will not issue a warning that 11 is not an element of <code>I</code>. In the result, the elements corresponding to J = 11..100 will be [[Null]]. This saves you from having to write <code>A[I=J,default:Null]</code> as was previous necessary to avoid the warning in this case. We have found this case of re-indexing to a larger index to be common enough that we felt it better without the warning.

= Assignment to controls and tables =

When you use the [[Assignment Operator:: ::=|assignment operator, :=]] to set the value of a variable that is currently defined as a [[Choice]], if the value you are assigning is a possible value on the list of choices, the choice control is now retained and the value that you are assigning is selected. The same applied when the definition is a [[Checkbox]] and you assign 0 or 1 to the variable.

This same treatment of controls applied when you use the [[Assignment Operator:: ::=|assignment operator, :=]] to change the definition of a table. If a cell in the new value happens to be a possible value for a [[Choice]] control in the same cell, the cell remains a control and the new value is selected in the choice control.

If you assign an array value to a variable that is currently defined as a [[DetermTable]], the definition now remains a [[DetermTable]] rather that being changed to a [[Table]]. The same applies to other table types: [[Table]], [[IntraTable]], and [[ProbTable]].

= Built-in functions =

== Logistic regression ==

[[LogisticRegression]], [[ProbitRegression]] and [[PoissonRegression]] are now built-in and available from all editions of Analytica. These functions include a Bayesian prior, which tends to work much better than maximum likelihood approaches in practice.

This class of functions is used to predict the probability of an outcome from known input variables (as compared to straight [[Regression]] which is usually thought of as predicting an outcome, rather than a distribution, from known input variables). You use training data that known input values paired with the outcome that actually occurred.

== Fast Fourier Transform ==

The [[FFT|Fast Fourier Transform]] has many uses, including the identification of seasonality or oscillations in time series, efficient convolution and de-convolution of data series, and the characteristic function representation of probability distributions in Bayesian inference. The [[FFT]] and [[FFTInv]] functions provide efficient transformations between a time or spatial domain and the frequency domain. These functions make use of [[Complex Numbers]].

== User interface functions ==

The new [[AskMsgChoice]] function displays a pop-up (in desktop Analytica) where you can ask the user to make a selection from a list of values. The selection can take the form of a choice pulldown (a fixed set of values) or a combo box, where a pulldown provides suggested values but where the user can type a value other than those suggested.

== Spreadsheet functions ==

''requires Analytica Enterprise''

New functions, [[SpreadsheetInfo]] and [[SpreadsheetSetInfo]], allow you to query or set various properties of the workbook object. You can use these to find out the file name and path, toggle automatic or manual computation modes, and obtain a list of names ranges, among other things.

== Reading or writing data files ==

* The [[ReadExportFile]] is now available for reading in a file in Analytica's multi-dimensional export format.

* The [[ReadTextFile]] function can now be used to read in data from files in ANSI, UTF-8 or UTF-16 formats, including file containing extended Unicode characters.

== Array Functions ==

* The index parameters to [[MdArrayToTable]] are now optional. A single parameter call, <code>[[MdArrayToTable]](A)</code>, converts multidimensional array A to a relational table.

== Probability Distributions ==

Two new distributions are now included as built-in functions.

* The [[NegativeBinomial|negative binomial distribution]] models the number of successes that occur in a Bernoulli processes before the first failure occurs, and is exposed as the built-in function [[NegativeBinomial]]. The Analytic probability, [[Prob_NegativeBinomia]], cumulative probability, [[CumNegativeBinomial]] and inverse cumulative, [[CumNegativeBinomInv]] are provided in the [[Distribution Densities Library]].

* The [[Wilcoxon|Wilcoxon distribution]] is primarily used for non-parametric hypothesis testing. The distribution function [[Wilcoxon]] and the analytic functions [[ProbWilcoxon]], [[CumWilcoxon]] and [[CumWilcoxonInv]] are all built-in functions and can all be used without adding any library, but the analytic functions only appear on the Definition menu if you add the [[Distribution Densities Library]].

= Graphs =

There have been several small fixes to result graphs (plots), some of which are notable.

* On an axis containing date-time values, labels on tick mark other than whole day boundaries did not show up, but now will.

* When a graph window is does not have sufficient height or width, some axis labels sometimes need to be dropped to avoid overlapping text. An enhanced layout algorithm now selects which labels to drop to maximize the regularity in spacing between the labels that are shown. The more even spacing usually looks more natural than before.

= Tables =

* When you view a table with controls ([[Choice]] pulldowns or [[Checkbox]]es), these now display as active controls in edit mode. A control appears in the bottom right corner of the header area which allows you to view and edit the textual expressions instead, which is visible in the following screenshot. With this feature, it is no longer necessary to switch back and forth between browse and edit mode to use controls in tables.

:[[image:ControlsInEditMode.png]]

* This release contains an experimental feature called a [[MultiTable]], which makes it possible to display multiple tables within a single edit table, including both editable and non-editable sources, and computed results. This is not officially part of the 4.5 release, and hence is not overtly exposed and may be subject to change before it becomes a supported feature.

= Graphical User Interface =

* You can easily compare the results from two or more nodes by selecting multiple nodes and pressing the ''Result'' button. Previously, this would add a new node to your model to hold the comparison. Now you can do this without adding a node to your model -- the result window opens with the comparison. In edit mode, you are asked whether you would like to add a node to your model to hold the comparison.

* A new menu option, '''Close All But Active''', has been added to the '''Windows''' menu. After you've been browsing a model and have dozens of windows open, this closes them all, except for the frontmost one.

* When you abort a computation, e.g., by pressing Ctrl+Break or clicking on the stop sign on the tool bar, there are times when it takes a while for Analytica to back out of the computation. Now, when it first responds to the break, as it starts to back out of the computation, the cursor changes to [[image:breakCursor.png]], giving immediate feedback that it has noticed your abort request and is handling it. While it is backing out of a computation is usually cannot respond to other windows events.

* Double clicking on a [[Checkbox]] input node no longer brings up the [[Object Window]], even if you are double clicking on the node label. This behaves a little different to other input/output node, where double clicking on the label jumps you to the [[Object Window]]. The change is made to match people's natural intuition for a checkbox.

* Alias nodes, input/output form nodes, text and picture objects no longer have squatters rights to their own identifier. If you rename another object to an identifier currently claimed by one of these, the existing non-squatter will silently be issued a new identifier and will not prevent you from using that identifier. In addition, the identifiers automatically created for these objects are highly unique so that a future name collision should never occur.

* The [[TableCellDefault|Cell Default]] attribute is now shown in the Attribute Panel or [[Object Window]] when the definition is blank or unparsed, whereas previously it was hidden. This allows you to easily configure the default before creating the table, so that the default applies to the initial cells when they are created.

= Libraries =

* The Libraries folder now has a subfolder named Old. Libraries that are now considered obsolete as a result of functions that have been build into Analytica over time are now located in the subfolder.

= Example Models =

* New example model, <code>Mean Reversion Trading.ana</code>, located in the <code>Dynamic Models</code> folder, illustrates the encoding of a Markov Decision Process.

* New example models, <code>Logistic regression prior selection.ana</code> and <code>Poisson regression ad exposures.ana</code>, in the <code>Data Analysis</code> folder illustrate the use of new logistic regression functions.

= Backward Compatibility =

We strive to make each release of Analytica backward compatible, so that models created in Analytica 4.4 will load and evaluate just fine in Analytica 4.5. Nevertheless, whenever any change occurs, there is always a remote chance it will impact an existing model. For example, if your model takes advantage of a bug, and that bug is fixed, then something may change. Here we list areas we know of that have potential to impact the backward compatibility of existing models. These are all pretty rare situations, but we list them for completeness.

* The sort order for text has changed, so as to be more sensible with letters with accents, etc. Prior to Analytica 4.5, sort order was determined purely by the ascii value of each character, whereas now it is based on the regional language collation order. For example, an accented é will now sort to be between the letters d and f, even thought the ascii value of é is not between d and f. If your model relies on the old ascii sort order, you can change a system variable to use the old order. The new system variable, [[TextLocale]], controls which collation order is used. To use the ascii order, press F12 to open the typescript window and type: <code>TextLocale:ansi</code>. You should then save and re-open your model, since results already computed won't automatically invalidate.

* Some errors in your definitions with index parameters are now detected at parse time, whereas previously they would not be detected until your expression was evaluated. These nodes will now appear cross-hatched when the model is loaded. When the bad expression is in an IF-THEN clause, and the IF part was false, your node might evaluate in 4.4 but give an error now. An example is this expression
::<code>[[If]] false [[Then]] [[Sum]](A,[[Sum]](B,J)) [[Else]] 0</code>
:Here the second parameter to [[Sum]] is not an index, so this is an error. This error would not be detected in 4.4, even at evaluation, because the [[If|IF]] is always false. If you find one of these cases when you run your model in Analytica 4.5, you should fix your expression -- it is an error regardless of which release you are running in.

* Ascii value of certain extended characters. Because of the conversion from ANSI ISO-9952-1 to the Unicode character set, the precise ascii value of a few extended characters has changed. This is only an issue if your model relies on the precise ascii value for these characters, which would be very rare. If you've simply used these characters in descriptions, definitions, or other attributes, this is not a problem since these will be automatically converted when you load your model. The characters impacted are [[Chr]](128)..[[Chr]](160), [[Chr]](173), [[Chr]](178) and [[Chr]](179), which appear as these: "€‚ƒ„…†‡ˆ‰Š‹ŒŽ‘’“”•–—˜™š›œžŸ≠≤≥".

* If your model files contain any Unicode charcters, the model file will be stored in UTF-8 format. Analytica 4.4 and earlier don't know about UTF-8, and always stored models using an ASCII character set. Hence, if you load a 4.5 model with unicode characters into Analytica 4.4, each of these extended characters will get converted into two or there garbage characters. See [[Model File Character Encoding]] for more information on this and on how to change encoding.

* When you use the [[Assignment Operator:: ::=|assignment operator]] from a button script to assign an array to a global variable, the existing type of the table is now preserved, whereas formerly such as assignment would change a [[DetermTable]] into a [[Table]]. This would only impact a model in the unlikely event that such as assignment is being used to convert a [[DetermTable]] to a [[Table]].

* When you use the [[Assignment Operator:: ::=|assignment operator]] to change a definition or edit table cell that contains a control ([[Choice]] or [[Checkbox]]), the control is now preserved and the new value is selected, whereas previously the control was replaced by the literal value. This change will have no effect on computed results, but could change the appearance of an edit table in the unlikely event that the assignment operator from a button script is being used to remove controls from a table.

What's New in Analytica 4.5?

2013-12-17T02:28:08Z

Esherwin: /* Free 101 Edition */

This page describes enhancements introduced in Analytica 4.5 since [[Analytica 4.4]].
Analytica 4.5 also includes bug fixes and improvements to robustness too numerous to list here.

= Free 101 Edition =

* As it's name implies, the Analytica Free 101 costs nothing.

* It lets you use the full features of Analytica Professional to build models with up to 101 user-created objects.

* If you use it to open a model with more than 101 objects, or expand a model up to 101 objects, it reverts to the features of the Analytica Player: You can still open and review the model, change inputs, and generate results as tables and graphs. But, it is locked in Browse mode, so it won't let you edit the model or add more objects. And you can't save the model with changed inputs.

* The Analytica Free 101 edition replaces the previous Analytica Trial and Analytica Player editions.

* Analytica Free 101 offers all features for Analytica Professional but not features of Analytica Enterprise or Optimizer: So, it doesn't offer spreadsheet and database access.

* Analytica Free 101 does let you use and distribute models for free use by others using the Analytica Cloud Player (ACP) or Power Player.

* Watermarks appear on diagrams, graphs, copied images, and printouts indicating that they were generated with the Analytica Free 101 edition.

* Click [http://www.lumina.com/products/free101/ here] to download Analytica Free 101.

= 64-bit Editions =

There is no longer a price difference between 32-bit and 64-bit editions. As long as you are running 64-bit Windows, you can install either.

If your are upgrading from an earlier release and your support is active, the Analytica 4.5 64-bit installer will automatically upgrade you to a 64-bit license.

= Unicode and International Alphabets =

Analytica supports unicode (instead of Ascii) for models. This means that you can use almost any alphabet for object identifiers, titles, units, descriptions, and any other attribute that accepts text, including file names. Alphabets includes Chinese, Greek, Japanese, Russian, Greek, or just about any language with letters or characters from extended Unicode characters ([[Chr]](1) to [[Chr]](65535)). (Arabic and Hebrew are available, but it doesn't display text right-to-left.) You can also include accents, mathematical symbols and numerous icons. Here's part of the Bond Model in Chinese: [[image:ChineseBondModel.png|right|420px]]

The user interface is not internationalized: Text in menus, dialogs, help, software documentation, and so on are still in English.
(The PDF guides (Tutorial, User Guide, Optimizer Guide) are also available in Chinese.)

== [[Collation Order]] ==

Analytica's comparison operators (e.g., < and >) and sorting functions (e.g., [[SortIndex]], [[Rank]], [[Sort]]) now compare text using language-specific collation order. Formerly, they compared text using the ascii values of each character. For non-English text, ascii order (also known as ansi order) does't always correspond to the natural ordering of text. For example, an accented é does not come between the letters d and f in ansi order.

A new system variable, <code>[[TextLocale]]</code>, specifies the collation order. The value usually indicates a language, or language and region (e.g., "English", "English_US", "Spanish"). You can still use the old-style ansi-order, by setting it to "Ansi". See [[Collation Order]].

== Accent awareness ==

Analytica treats accented characters more logically. For example, functions [[TextUpperCase]] and [[TextLowerCase]], and the automatic generation of an identifier from a title that you type, behave appropriately when accents are present.

== Model file format ==

To accommodate Unicode text fields, Analytica stores model files using the [http://en.wikipedia.org/wiki/UTF-8 UTF-8 character encoding] instead of ANSI encoding.

The [http://en.wikipedia.org/wiki/UTF-8 UTF-8 encoding] is the same as ANSI for basic characters -- i.e., those with ascii values below 128, including English alphabet letters, numbers and standard punctuation. So, there is no change for models that only use these basic characters. This ensures forward compatibility of existing model files. Extended characters -- the most common being letters with accents and some non-US currency symbols -- each use two bytes in the model file.

== Remapped characters ==

The ascii value of some extended characters is now different. If these appear in your legacy model, they'll be converted and you'll never know it. But if you use the [[Chr]] or [[Asc]] functions, you might notice this difference.

The characters with ascii values from 128 thru 160 are not the same in ANSI (aka ISO-8859-1) and Unicode. So these characters are remapped. The characters ≠, ≤ and ≥, previously with ascii values of 173, 178 and 179, now have the standard unicode values of 8800, 8804 and 8805.

== Month and weekday names ==

Month and weekday names in date formats display those in the regional language even when they include characters outside of the ascii range. Previously names with non-ascii characters would revert to their English equivalent.

= Editing expressions =

== Enumerated parameter assist ==

When typing a definition and at a parameter with an enumerated set of possible values, Expression Assist now shows you the list of possible values and what they mean:

[[image:Enumerated Parameter Assist.png]]

== Indentation and Tabs ==

While editing a definition (or other text attribute), the TAB key will indent the line (inserting a Tab character) to make it easier to write indented text. When writing nested multiline expressions, indenting lets you make them much easier to read.

Here's how it works when you are editing a Definition or other attribute in the Attribute pane or Object window:
* If Expression Assist is suggesting an identifier or word completion, TAB inserts the selected item.
* If you have selected text in one more more lines in edit mode, press TAB to indent the line(s).
* Or press Shift+TAB to remove one level of indent for the selected line(s).
* If you are typing in an attribute field, Tab inserts a tab character, which lines up the next character at a fixed pixel position, spaced approximately 4 typical characters widths apart.
* In the Object Window, pressing TAB selects the next attribute in the window -- except if you are editing the attribute (if you have clicked in it or move the cursor in it) it indents the selected line(s), as described above.

= Exporting and importing data =

== Refinements to the [[Export-Import data format]] specification ==

The [[Export-Import data format]] is used by the '''File→Export''' and '''File→Import''' menu commands, and by '''Copy Table''', as a representation for exchanging multidimensional arrays. It is described in the last section of Chapter 19 of the Analyica User Guide.

* There were ambiguities in the original specification, largely relating to differentiating between text that wasn't quoted and expressions or identifiers. The original specification also did not address how multiline cell values should be represented, or values containing the tab character. A more precise specification of the format has been created. The user guide description has been updated, the [[Export-Import data format|Wiki specification]] has the more formal and precise specification.

* Multidimensional tables and arrays containing distribution functions, multiline cell values, identifiers, expressions, and tab characters can now be successfully exported and imported. (these cases did not work previously due to ambiguities).

* A new built-in function, [[ReadExportFile]], has been added which can be used to read in a file in the [[Export-Import data format]]. (we are aware of the obvious omission of WriteExportFile that isn't yet available).

* The old typescript commands [[Export]] and [[Import]] work with the updated format. (prior to 4.5, [[Import]] was not there but didn't work).

== Index Correspondence ==

* When you import a saved or copied multidimensional array into an edit table, the indexes of the saved array need to be matched (or ''corresponded'') with the indexes of the table. That correspondence can be quite confusing since the tables may be pivoted differently, or may be based on different indexes having either the same length or same elements. The logic for making this correspondence has been greatly enhanced, so that it is now much smarter about recognizing intended correspondences across a variety of cases. The details are described in [[Export-Import_data_format#Index_Correspondence|Index Correspondence]]. What this means for you:
** When copying a table to another that uses the same indexes, it'll work even if you don't get the pivot the same.
** When source and destination tables have different indexes, but of the same lengths, you can remove any ambiguities by making the pivot the same.

= Engine and language enhancements =

== Complex Numbers ==

[[Complex Numbers|Complex numbers]] are now built-in and exposed, relevant built-in functions are complex-number aware, and several new built-in functions are now present for manipulating complex numbers, including: [[RealPart]], [[ImPart]], [[ComplexRadians]], [[ComplexDegrees]] (use [[Abs]] for magnitude), [[FFT]] and [[FFTInv]].

To type a complex number, use an i or j suffix, for example: -2j or 4+3i. Complex numbers display in 3-4j format in result table cells. Graphs display [[RealPart]](x).

If you try to evaluate <code>[[Sqrt]](-4)</code>, the result depends on whether you have enabled complex numbers. If you have not, you'll be warned that you are taking the square root of a negative number and, if you ignore warnings, the result will be [[NaN]]. If you enable complex numbers, the result will be <code>2j</code>. To enable complex numbers, select '''Definition → System Variables → EnableComplexNumbers''' from the menus (with no object selected).

See [[Complex Numbers]] for more details.

== Fixed real precision arithmetic ==

Analytica now uses fixed-precision (also known as fixed-point) to represent numbers when it can, instead of floating point. Fixed-precision is an exact representation, so this avoids occasional issues of round-off error that occur with floating point.

For example, the number 0.07 has no exact binary floating point representation. The closest floating-point value is roughly 0.07000000000000001. This tiny error can become magnified by certain arithmetic operations, such as
: <code>(0.07 * 10 - .7) * 1e+16</code>
With floating point arithmetic, this gives a result slightly greater than 1, even though the result should be zero. In Analytica 4.5, the use of fixed point arithmetic produces the exact result of 0.

Fixed precision uses an exact representation for numbers with up 6 decimal digits with absolute value less than 9 trillion -- more precisely, for x where Abs(x) <= 9,223,372,036,854.775807. Fixed-precision arithmetic preserves fixed-precision for results when possible. Operations that cannot guarantee a fixed-point result fall back to floating point precision.

== Repeated parameter forwarding ==

Have you ever needed to [[Sum]] over all the indexes of an array, without necessarily knowing what indexes are present in advance? A new language extension called [[Repeated Parameter Forwarding]] allows you to do this using
:<code>[[Sum]](A,...indexesOf(A))</code>

In general, this extension allows you to compute a list of values and pass them to a repeated function parameter. For more details, see [[Repeated Parameter Forwarding]].

== Subscript warning ==

When you use [[Slice]] or [[Subscript]] to re-index to a larger index, a warning is no longer issued about elements that are not found in the source index. For example, suppose
:Index I := 1..10
:Index J := 1..100
Then <code>A[I=J]</code> will not issue a warning that 11 is not an element of <code>I</code>. In the result, the elements corresponding to J = 11..100 will be [[Null]]. This saves you from having to write <code>A[I=J,default:Null]</code> as was previous necessary to avoid the warning in this case. We have found this case of re-indexing to a larger index to be common enough that we felt it better without the warning.

= Assignment to controls and tables =

When you use the [[Assignment Operator:: ::=|assignment operator, :=]] to set the value of a variable that is currently defined as a [[Choice]], if the value you are assigning is a possible value on the list of choices, the choice control is now retained and the value that you are assigning is selected. The same applied when the definition is a [[Checkbox]] and you assign 0 or 1 to the variable.

This same treatment of controls applied when you use the [[Assignment Operator:: ::=|assignment operator, :=]] to change the definition of a table. If a cell in the new value happens to be a possible value for a [[Choice]] control in the same cell, the cell remains a control and the new value is selected in the choice control.

If you assign an array value to a variable that is currently defined as a [[DetermTable]], the definition now remains a [[DetermTable]] rather that being changed to a [[Table]]. The same applies to other table types: [[Table]], [[IntraTable]], and [[ProbTable]].

= Built-in functions =

== Logistic regression ==

[[LogisticRegression]], [[ProbitRegression]] and [[PoissonRegression]] are now built-in and available from all editions of Analytica. These functions include a Bayesian prior, which tends to work much better than maximum likelihood approaches in practice.

This class of functions is used to predict the probability of an outcome from known input variables (as compared to straight [[Regression]] which is usually thought of as predicting an outcome, rather than a distribution, from known input variables). You use training data that known input values paired with the outcome that actually occurred.

== Fast Fourier Transform ==

The [[FFT|Fast Fourier Transform]] has many uses, including the identification of seasonality or oscillations in time series, efficient convolution and de-convolution of data series, and the characteristic function representation of probability distributions in Bayesian inference. The [[FFT]] and [[FFTInv]] functions provide efficient transformations between a time or spatial domain and the frequency domain. These functions make use of [[Complex Numbers]].

== User interface functions ==

The new [[AskMsgChoice]] function displays a pop-up (in desktop Analytica) where you can ask the user to make a selection from a list of values. The selection can take the form of a choice pulldown (a fixed set of values) or a combo box, where a pulldown provides suggested values but where the user can type a value other than those suggested.

== Spreadsheet functions ==

''requires Analytica Enterprise''

New functions, [[SpreadsheetInfo]] and [[SpreadsheetSetInfo]], allow you to query or set various properties of the workbook object. You can use these to find out the file name and path, toggle automatic or manual computation modes, and obtain a list of names ranges, among other things.

== Reading or writing data files ==

* The [[ReadExportFile]] is now available for reading in a file in Analytica's multi-dimensional export format.

* The [[ReadTextFile]] function can now be used to read in data from files in ANSI, UTF-8 or UTF-16 formats, including file containing extended Unicode characters.

== Array Functions ==

* The index parameters to [[MdArrayToTable]] are now optional. A single parameter call, <code>[[MdArrayToTable]](A)</code>, converts multidimensional array A to a relational table.

== Probability Distributions ==

Two new distributions are now included as built-in functions.

* The [[NegativeBinomial|negative binomial distribution]] models the number of successes that occur in a Bernoulli processes before the first failure occurs, and is exposed as the built-in function [[NegativeBinomial]]. The Analytic probability, [[Prob_NegativeBinomia]], cumulative probability, [[CumNegativeBinomial]] and inverse cumulative, [[CumNegativeBinomInv]] are provided in the [[Distribution Densities Library]].

* The [[Wilcoxon|Wilcoxon distribution]] is primarily used for non-parametric hypothesis testing. The distribution function [[Wilcoxon]] and the analytic functions [[ProbWilcoxon]], [[CumWilcoxon]] and [[CumWilcoxonInv]] are all built-in functions and can all be used without adding any library, but the analytic functions only appear on the Definition menu if you add the [[Distribution Densities Library]].

= Graphs =

There have been several small fixes to result graphs (plots), some of which are notable.

* On an axis containing date-time values, labels on tick mark other than whole day boundaries did not show up, but now will.

* When a graph window is does not have sufficient height or width, some axis labels sometimes need to be dropped to avoid overlapping text. An enhanced layout algorithm now selects which labels to drop to maximize the regularity in spacing between the labels that are shown. The more even spacing usually looks more natural than before.

= Tables =

* When you view a table with controls ([[Choice]] pulldowns or [[Checkbox]]es), these now display as active controls in edit mode. A control appears in the bottom right corner of the header area which allows you to view and edit the textual expressions instead, which is visible in the following screenshot. With this feature, it is no longer necessary to switch back and forth between browse and edit mode to use controls in tables.

:[[image:ControlsInEditMode.png]]

* This release contains an experimental feature called a [[MultiTable]], which makes it possible to display multiple tables within a single edit table, including both editable and non-editable sources, and computed results. This is not officially part of the 4.5 release, and hence is not overtly exposed and may be subject to change before it becomes a supported feature.

= Graphical User Interface =

* You can easily compare the results from two or more nodes by selecting multiple nodes and pressing the ''Result'' button. Previously, this would add a new node to your model to hold the comparison. Now you can do this without adding a node to your model -- the result window opens with the comparison. In edit mode, you are asked whether you would like to add a node to your model to hold the comparison.

* A new menu option, '''Close All But Active''', has been added to the '''Windows''' menu. After you've been browsing a model and have dozens of windows open, this closes them all, except for the frontmost one.

* When you abort a computation, e.g., by pressing Ctrl+Break or clicking on the stop sign on the tool bar, there are times when it takes a while for Analytica to back out of the computation. Now, when it first responds to the break, as it starts to back out of the computation, the cursor changes to [[image:breakCursor.png]], giving immediate feedback that it has noticed your abort request and is handling it. While it is backing out of a computation is usually cannot respond to other windows events.

* Double clicking on a [[Checkbox]] input node no longer brings up the [[Object Window]], even if you are double clicking on the node label. This behaves a little different to other input/output node, where double clicking on the label jumps you to the [[Object Window]]. The change is made to match people's natural intuition for a checkbox.

* Alias nodes, input/output form nodes, text and picture objects no longer have squatters rights to their own identifier. If you rename another object to an identifier currently claimed by one of these, the existing non-squatter will silently be issued a new identifier and will not prevent you from using that identifier. In addition, the identifiers automatically created for these objects are highly unique so that a future name collision should never occur.

* The [[TableCellDefault|Cell Default]] attribute is now shown in the Attribute Panel or [[Object Window]] when the definition is blank or unparsed, whereas previously it was hidden. This allows you to easily configure the default before creating the table, so that the default applies to the initial cells when they are created.

= Libraries =

* The Libraries folder now has a subfolder named Old. Libraries that are now considered obsolete as a result of functions that have been build into Analytica over time are now located in the subfolder.

= Example Models =

* New example model, <code>Mean Reversion Trading.ana</code>, located in the <code>Dynamic Models</code> folder, illustrates the encoding of a Markov Decision Process.

* New example models, <code>Logistic regression prior selection.ana</code> and <code>Poisson regression ad exposures.ana</code>, in the <code>Data Analysis</code> folder illustrate the use of new logistic regression functions.

= Backward Compatibility =

We strive to make each release of Analytica backward compatible, so that models created in Analytica 4.4 will load and evaluate just fine in Analytica 4.5. Nevertheless, whenever any change occurs, there is always a remote chance it will impact an existing model. For example, if your model takes advantage of a bug, and that bug is fixed, then something may change. Here we list areas we know of that have potential to impact the backward compatibility of existing models. These are all pretty rare situations, but we list them for completeness.

* The sort order for text has changed, so as to be more sensible with letters with accents, etc. Prior to Analytica 4.5, sort order was determined purely by the ascii value of each character, whereas now it is based on the regional language collation order. For example, an accented é will now sort to be between the letters d and f, even thought the ascii value of é is not between d and f. If your model relies on the old ascii sort order, you can change a system variable to use the old order. The new system variable, [[TextLocale]], controls which collation order is used. To use the ascii order, press F12 to open the typescript window and type: <code>TextLocale:ansi</code>. You should then save and re-open your model, since results already computed won't automatically invalidate.

* Some errors in your definitions with index parameters are now detected at parse time, whereas previously they would not be detected until your expression was evaluated. These nodes will now appear cross-hatched when the model is loaded. When the bad expression is in an IF-THEN clause, and the IF part was false, your node might evaluate in 4.4 but give an error now. An example is this expression
::<code>[[If]] false [[Then]] [[Sum]](A,[[Sum]](B,J)) [[Else]] 0</code>
:Here the second parameter to [[Sum]] is not an index, so this is an error. This error would not be detected in 4.4, even at evaluation, because the [[If|IF]] is always false. If you find one of these cases when you run your model in Analytica 4.5, you should fix your expression -- it is an error regardless of which release you are running in.

* Ascii value of certain extended characters. Because of the conversion from ANSI ISO-9952-1 to the Unicode character set, the precise ascii value of a few extended characters has changed. This is only an issue if your model relies on the precise ascii value for these characters, which would be very rare. If you've simply used these characters in descriptions, definitions, or other attributes, this is not a problem since these will be automatically converted when you load your model. The characters impacted are [[Chr]](128)..[[Chr]](160), [[Chr]](173), [[Chr]](178) and [[Chr]](179), which appear as these: "€‚ƒ„…†‡ˆ‰Š‹ŒŽ‘’“”•–—˜™š›œžŸ≠≤≥".

* If your model files contain any Unicode charcters, the model file will be stored in UTF-8 format. Analytica 4.4 and earlier don't know about UTF-8, and always stored models using an ASCII character set. Hence, if you load a 4.5 model with unicode characters into Analytica 4.4, each of these extended characters will get converted into two or there garbage characters. See [[Model File Character Encoding]] for more information on this and on how to change encoding.

* When you use the [[Assignment Operator:: ::=|assignment operator]] from a button script to assign an array to a global variable, the existing type of the table is now preserved, whereas formerly such as assignment would change a [[DetermTable]] into a [[Table]]. This would only impact a model in the unlikely event that such as assignment is being used to convert a [[DetermTable]] to a [[Table]].

* When you use the [[Assignment Operator:: ::=|assignment operator]] to change a definition or edit table cell that contains a control ([[Choice]] or [[Checkbox]]), the control is now preserved and the new value is selected, whereas previously the control was replaced by the literal value. This change will have no effect on computed results, but could change the appearance of an edit table in the unlikely event that the assignment operator from a button script is being used to remove controls from a table.

What's New in Analytica 4.5?

2013-12-17T02:26:41Z

Esherwin: /* Free 101 Edition */

This page describes enhancements introduced in Analytica 4.5 since [[Analytica 4.4]].
Analytica 4.5 also includes bug fixes and improvements to robustness too numerous to list here.

= Free 101 Edition =

* As it's name implies, the Analytica Free 101 costs nothing.

* It lets you use the full features of Analytica Professional to build models with up to 101 user-created objects.

* If you use it to open a model with more than 101 objects, or expand a model up to 101 objects, it reverts to the features of the Analytica Player: You can still open and review the model, change inputs, and generate results as tables and graphs. But, it is locked in Browse mode, so it won't let you edit the model or add more objects. And you can't save the model with changed inputs.

* The Analytica Free 101 edition replaces the previous Analytica Trial and Analytica Player editions.

* Analytica Free 101 offers all features for Analytica Professional but not features of Analytica Enterprise or Optimizer: So, it doesn't offer spreadsheet and database access.

* Analytica Free 101 does let you use and distribute models for free use by others using the Analytica Cloud Player (ACP) or Power Player.

* Watermarks appear on diagrams, graphs, copied images, and printouts indicating that they were generated with the Analytica Free 101 edition.

* Click [here][http://www.lumina.com/products/free101/] to download Analytica Free 101.

= 64-bit Editions =

There is no longer a price difference between 32-bit and 64-bit editions. As long as you are running 64-bit Windows, you can install either.

If your are upgrading from an earlier release and your support is active, the Analytica 4.5 64-bit installer will automatically upgrade you to a 64-bit license.

= Unicode and International Alphabets =

Analytica supports unicode (instead of Ascii) for models. This means that you can use almost any alphabet for object identifiers, titles, units, descriptions, and any other attribute that accepts text, including file names. Alphabets includes Chinese, Greek, Japanese, Russian, Greek, or just about any language with letters or characters from extended Unicode characters ([[Chr]](1) to [[Chr]](65535)). (Arabic and Hebrew are available, but it doesn't display text right-to-left.) You can also include accents, mathematical symbols and numerous icons. Here's part of the Bond Model in Chinese: [[image:ChineseBondModel.png|right|420px]]

The user interface is not internationalized: Text in menus, dialogs, help, software documentation, and so on are still in English.
(The PDF guides (Tutorial, User Guide, Optimizer Guide) are also available in Chinese.)

== [[Collation Order]] ==

Analytica's comparison operators (e.g., < and >) and sorting functions (e.g., [[SortIndex]], [[Rank]], [[Sort]]) now compare text using language-specific collation order. Formerly, they compared text using the ascii values of each character. For non-English text, ascii order (also known as ansi order) does't always correspond to the natural ordering of text. For example, an accented é does not come between the letters d and f in ansi order.

A new system variable, <code>[[TextLocale]]</code>, specifies the collation order. The value usually indicates a language, or language and region (e.g., "English", "English_US", "Spanish"). You can still use the old-style ansi-order, by setting it to "Ansi". See [[Collation Order]].

== Accent awareness ==

Analytica treats accented characters more logically. For example, functions [[TextUpperCase]] and [[TextLowerCase]], and the automatic generation of an identifier from a title that you type, behave appropriately when accents are present.

== Model file format ==

To accommodate Unicode text fields, Analytica stores model files using the [http://en.wikipedia.org/wiki/UTF-8 UTF-8 character encoding] instead of ANSI encoding.

The [http://en.wikipedia.org/wiki/UTF-8 UTF-8 encoding] is the same as ANSI for basic characters -- i.e., those with ascii values below 128, including English alphabet letters, numbers and standard punctuation. So, there is no change for models that only use these basic characters. This ensures forward compatibility of existing model files. Extended characters -- the most common being letters with accents and some non-US currency symbols -- each use two bytes in the model file.

== Remapped characters ==

The ascii value of some extended characters is now different. If these appear in your legacy model, they'll be converted and you'll never know it. But if you use the [[Chr]] or [[Asc]] functions, you might notice this difference.

The characters with ascii values from 128 thru 160 are not the same in ANSI (aka ISO-8859-1) and Unicode. So these characters are remapped. The characters ≠, ≤ and ≥, previously with ascii values of 173, 178 and 179, now have the standard unicode values of 8800, 8804 and 8805.

== Month and weekday names ==

Month and weekday names in date formats display those in the regional language even when they include characters outside of the ascii range. Previously names with non-ascii characters would revert to their English equivalent.

= Editing expressions =

== Enumerated parameter assist ==

When typing a definition and at a parameter with an enumerated set of possible values, Expression Assist now shows you the list of possible values and what they mean:

[[image:Enumerated Parameter Assist.png]]

== Indentation and Tabs ==

While editing a definition (or other text attribute), the TAB key will indent the line (inserting a Tab character) to make it easier to write indented text. When writing nested multiline expressions, indenting lets you make them much easier to read.

Here's how it works when you are editing a Definition or other attribute in the Attribute pane or Object window:
* If Expression Assist is suggesting an identifier or word completion, TAB inserts the selected item.
* If you have selected text in one more more lines in edit mode, press TAB to indent the line(s).
* Or press Shift+TAB to remove one level of indent for the selected line(s).
* If you are typing in an attribute field, Tab inserts a tab character, which lines up the next character at a fixed pixel position, spaced approximately 4 typical characters widths apart.
* In the Object Window, pressing TAB selects the next attribute in the window -- except if you are editing the attribute (if you have clicked in it or move the cursor in it) it indents the selected line(s), as described above.

= Exporting and importing data =

== Refinements to the [[Export-Import data format]] specification ==

The [[Export-Import data format]] is used by the '''File→Export''' and '''File→Import''' menu commands, and by '''Copy Table''', as a representation for exchanging multidimensional arrays. It is described in the last section of Chapter 19 of the Analyica User Guide.

* There were ambiguities in the original specification, largely relating to differentiating between text that wasn't quoted and expressions or identifiers. The original specification also did not address how multiline cell values should be represented, or values containing the tab character. A more precise specification of the format has been created. The user guide description has been updated, the [[Export-Import data format|Wiki specification]] has the more formal and precise specification.

* Multidimensional tables and arrays containing distribution functions, multiline cell values, identifiers, expressions, and tab characters can now be successfully exported and imported. (these cases did not work previously due to ambiguities).

* A new built-in function, [[ReadExportFile]], has been added which can be used to read in a file in the [[Export-Import data format]]. (we are aware of the obvious omission of WriteExportFile that isn't yet available).

* The old typescript commands [[Export]] and [[Import]] work with the updated format. (prior to 4.5, [[Import]] was not there but didn't work).

== Index Correspondence ==

* When you import a saved or copied multidimensional array into an edit table, the indexes of the saved array need to be matched (or ''corresponded'') with the indexes of the table. That correspondence can be quite confusing since the tables may be pivoted differently, or may be based on different indexes having either the same length or same elements. The logic for making this correspondence has been greatly enhanced, so that it is now much smarter about recognizing intended correspondences across a variety of cases. The details are described in [[Export-Import_data_format#Index_Correspondence|Index Correspondence]]. What this means for you:
** When copying a table to another that uses the same indexes, it'll work even if you don't get the pivot the same.
** When source and destination tables have different indexes, but of the same lengths, you can remove any ambiguities by making the pivot the same.

= Engine and language enhancements =

== Complex Numbers ==

[[Complex Numbers|Complex numbers]] are now built-in and exposed, relevant built-in functions are complex-number aware, and several new built-in functions are now present for manipulating complex numbers, including: [[RealPart]], [[ImPart]], [[ComplexRadians]], [[ComplexDegrees]] (use [[Abs]] for magnitude), [[FFT]] and [[FFTInv]].

To type a complex number, use an i or j suffix, for example: -2j or 4+3i. Complex numbers display in 3-4j format in result table cells. Graphs display [[RealPart]](x).

If you try to evaluate <code>[[Sqrt]](-4)</code>, the result depends on whether you have enabled complex numbers. If you have not, you'll be warned that you are taking the square root of a negative number and, if you ignore warnings, the result will be [[NaN]]. If you enable complex numbers, the result will be <code>2j</code>. To enable complex numbers, select '''Definition → System Variables → EnableComplexNumbers''' from the menus (with no object selected).

See [[Complex Numbers]] for more details.

== Fixed real precision arithmetic ==

Analytica now uses fixed-precision (also known as fixed-point) to represent numbers when it can, instead of floating point. Fixed-precision is an exact representation, so this avoids occasional issues of round-off error that occur with floating point.

For example, the number 0.07 has no exact binary floating point representation. The closest floating-point value is roughly 0.07000000000000001. This tiny error can become magnified by certain arithmetic operations, such as
: <code>(0.07 * 10 - .7) * 1e+16</code>
With floating point arithmetic, this gives a result slightly greater than 1, even though the result should be zero. In Analytica 4.5, the use of fixed point arithmetic produces the exact result of 0.

Fixed precision uses an exact representation for numbers with up 6 decimal digits with absolute value less than 9 trillion -- more precisely, for x where Abs(x) <= 9,223,372,036,854.775807. Fixed-precision arithmetic preserves fixed-precision for results when possible. Operations that cannot guarantee a fixed-point result fall back to floating point precision.

== Repeated parameter forwarding ==

Have you ever needed to [[Sum]] over all the indexes of an array, without necessarily knowing what indexes are present in advance? A new language extension called [[Repeated Parameter Forwarding]] allows you to do this using
:<code>[[Sum]](A,...indexesOf(A))</code>

In general, this extension allows you to compute a list of values and pass them to a repeated function parameter. For more details, see [[Repeated Parameter Forwarding]].

== Subscript warning ==

When you use [[Slice]] or [[Subscript]] to re-index to a larger index, a warning is no longer issued about elements that are not found in the source index. For example, suppose
:Index I := 1..10
:Index J := 1..100
Then <code>A[I=J]</code> will not issue a warning that 11 is not an element of <code>I</code>. In the result, the elements corresponding to J = 11..100 will be [[Null]]. This saves you from having to write <code>A[I=J,default:Null]</code> as was previous necessary to avoid the warning in this case. We have found this case of re-indexing to a larger index to be common enough that we felt it better without the warning.

= Assignment to controls and tables =

When you use the [[Assignment Operator:: ::=|assignment operator, :=]] to set the value of a variable that is currently defined as a [[Choice]], if the value you are assigning is a possible value on the list of choices, the choice control is now retained and the value that you are assigning is selected. The same applied when the definition is a [[Checkbox]] and you assign 0 or 1 to the variable.

This same treatment of controls applied when you use the [[Assignment Operator:: ::=|assignment operator, :=]] to change the definition of a table. If a cell in the new value happens to be a possible value for a [[Choice]] control in the same cell, the cell remains a control and the new value is selected in the choice control.

If you assign an array value to a variable that is currently defined as a [[DetermTable]], the definition now remains a [[DetermTable]] rather that being changed to a [[Table]]. The same applies to other table types: [[Table]], [[IntraTable]], and [[ProbTable]].

= Built-in functions =

== Logistic regression ==

[[LogisticRegression]], [[ProbitRegression]] and [[PoissonRegression]] are now built-in and available from all editions of Analytica. These functions include a Bayesian prior, which tends to work much better than maximum likelihood approaches in practice.

This class of functions is used to predict the probability of an outcome from known input variables (as compared to straight [[Regression]] which is usually thought of as predicting an outcome, rather than a distribution, from known input variables). You use training data that known input values paired with the outcome that actually occurred.

== Fast Fourier Transform ==

The [[FFT|Fast Fourier Transform]] has many uses, including the identification of seasonality or oscillations in time series, efficient convolution and de-convolution of data series, and the characteristic function representation of probability distributions in Bayesian inference. The [[FFT]] and [[FFTInv]] functions provide efficient transformations between a time or spatial domain and the frequency domain. These functions make use of [[Complex Numbers]].

== User interface functions ==

The new [[AskMsgChoice]] function displays a pop-up (in desktop Analytica) where you can ask the user to make a selection from a list of values. The selection can take the form of a choice pulldown (a fixed set of values) or a combo box, where a pulldown provides suggested values but where the user can type a value other than those suggested.

== Spreadsheet functions ==

''requires Analytica Enterprise''

New functions, [[SpreadsheetInfo]] and [[SpreadsheetSetInfo]], allow you to query or set various properties of the workbook object. You can use these to find out the file name and path, toggle automatic or manual computation modes, and obtain a list of names ranges, among other things.

== Reading or writing data files ==

* The [[ReadExportFile]] is now available for reading in a file in Analytica's multi-dimensional export format.

* The [[ReadTextFile]] function can now be used to read in data from files in ANSI, UTF-8 or UTF-16 formats, including file containing extended Unicode characters.

== Array Functions ==

* The index parameters to [[MdArrayToTable]] are now optional. A single parameter call, <code>[[MdArrayToTable]](A)</code>, converts multidimensional array A to a relational table.

== Probability Distributions ==

Two new distributions are now included as built-in functions.

* The [[NegativeBinomial|negative binomial distribution]] models the number of successes that occur in a Bernoulli processes before the first failure occurs, and is exposed as the built-in function [[NegativeBinomial]]. The Analytic probability, [[Prob_NegativeBinomia]], cumulative probability, [[CumNegativeBinomial]] and inverse cumulative, [[CumNegativeBinomInv]] are provided in the [[Distribution Densities Library]].

* The [[Wilcoxon|Wilcoxon distribution]] is primarily used for non-parametric hypothesis testing. The distribution function [[Wilcoxon]] and the analytic functions [[ProbWilcoxon]], [[CumWilcoxon]] and [[CumWilcoxonInv]] are all built-in functions and can all be used without adding any library, but the analytic functions only appear on the Definition menu if you add the [[Distribution Densities Library]].

= Graphs =

There have been several small fixes to result graphs (plots), some of which are notable.

* On an axis containing date-time values, labels on tick mark other than whole day boundaries did not show up, but now will.

* When a graph window is does not have sufficient height or width, some axis labels sometimes need to be dropped to avoid overlapping text. An enhanced layout algorithm now selects which labels to drop to maximize the regularity in spacing between the labels that are shown. The more even spacing usually looks more natural than before.

= Tables =

* When you view a table with controls ([[Choice]] pulldowns or [[Checkbox]]es), these now display as active controls in edit mode. A control appears in the bottom right corner of the header area which allows you to view and edit the textual expressions instead, which is visible in the following screenshot. With this feature, it is no longer necessary to switch back and forth between browse and edit mode to use controls in tables.

:[[image:ControlsInEditMode.png]]

* This release contains an experimental feature called a [[MultiTable]], which makes it possible to display multiple tables within a single edit table, including both editable and non-editable sources, and computed results. This is not officially part of the 4.5 release, and hence is not overtly exposed and may be subject to change before it becomes a supported feature.

= Graphical User Interface =

* You can easily compare the results from two or more nodes by selecting multiple nodes and pressing the ''Result'' button. Previously, this would add a new node to your model to hold the comparison. Now you can do this without adding a node to your model -- the result window opens with the comparison. In edit mode, you are asked whether you would like to add a node to your model to hold the comparison.

* A new menu option, '''Close All But Active''', has been added to the '''Windows''' menu. After you've been browsing a model and have dozens of windows open, this closes them all, except for the frontmost one.

* When you abort a computation, e.g., by pressing Ctrl+Break or clicking on the stop sign on the tool bar, there are times when it takes a while for Analytica to back out of the computation. Now, when it first responds to the break, as it starts to back out of the computation, the cursor changes to [[image:breakCursor.png]], giving immediate feedback that it has noticed your abort request and is handling it. While it is backing out of a computation is usually cannot respond to other windows events.

* Double clicking on a [[Checkbox]] input node no longer brings up the [[Object Window]], even if you are double clicking on the node label. This behaves a little different to other input/output node, where double clicking on the label jumps you to the [[Object Window]]. The change is made to match people's natural intuition for a checkbox.

* Alias nodes, input/output form nodes, text and picture objects no longer have squatters rights to their own identifier. If you rename another object to an identifier currently claimed by one of these, the existing non-squatter will silently be issued a new identifier and will not prevent you from using that identifier. In addition, the identifiers automatically created for these objects are highly unique so that a future name collision should never occur.

* The [[TableCellDefault|Cell Default]] attribute is now shown in the Attribute Panel or [[Object Window]] when the definition is blank or unparsed, whereas previously it was hidden. This allows you to easily configure the default before creating the table, so that the default applies to the initial cells when they are created.

= Libraries =

* The Libraries folder now has a subfolder named Old. Libraries that are now considered obsolete as a result of functions that have been build into Analytica over time are now located in the subfolder.

= Example Models =

* New example model, <code>Mean Reversion Trading.ana</code>, located in the <code>Dynamic Models</code> folder, illustrates the encoding of a Markov Decision Process.

* New example models, <code>Logistic regression prior selection.ana</code> and <code>Poisson regression ad exposures.ana</code>, in the <code>Data Analysis</code> folder illustrate the use of new logistic regression functions.

= Backward Compatibility =

We strive to make each release of Analytica backward compatible, so that models created in Analytica 4.4 will load and evaluate just fine in Analytica 4.5. Nevertheless, whenever any change occurs, there is always a remote chance it will impact an existing model. For example, if your model takes advantage of a bug, and that bug is fixed, then something may change. Here we list areas we know of that have potential to impact the backward compatibility of existing models. These are all pretty rare situations, but we list them for completeness.

* The sort order for text has changed, so as to be more sensible with letters with accents, etc. Prior to Analytica 4.5, sort order was determined purely by the ascii value of each character, whereas now it is based on the regional language collation order. For example, an accented é will now sort to be between the letters d and f, even thought the ascii value of é is not between d and f. If your model relies on the old ascii sort order, you can change a system variable to use the old order. The new system variable, [[TextLocale]], controls which collation order is used. To use the ascii order, press F12 to open the typescript window and type: <code>TextLocale:ansi</code>. You should then save and re-open your model, since results already computed won't automatically invalidate.

* Some errors in your definitions with index parameters are now detected at parse time, whereas previously they would not be detected until your expression was evaluated. These nodes will now appear cross-hatched when the model is loaded. When the bad expression is in an IF-THEN clause, and the IF part was false, your node might evaluate in 4.4 but give an error now. An example is this expression
::<code>[[If]] false [[Then]] [[Sum]](A,[[Sum]](B,J)) [[Else]] 0</code>
:Here the second parameter to [[Sum]] is not an index, so this is an error. This error would not be detected in 4.4, even at evaluation, because the [[If|IF]] is always false. If you find one of these cases when you run your model in Analytica 4.5, you should fix your expression -- it is an error regardless of which release you are running in.

* Ascii value of certain extended characters. Because of the conversion from ANSI ISO-9952-1 to the Unicode character set, the precise ascii value of a few extended characters has changed. This is only an issue if your model relies on the precise ascii value for these characters, which would be very rare. If you've simply used these characters in descriptions, definitions, or other attributes, this is not a problem since these will be automatically converted when you load your model. The characters impacted are [[Chr]](128)..[[Chr]](160), [[Chr]](173), [[Chr]](178) and [[Chr]](179), which appear as these: "€‚ƒ„…†‡ˆ‰Š‹ŒŽ‘’“”•–—˜™š›œžŸ≠≤≥".

* If your model files contain any Unicode charcters, the model file will be stored in UTF-8 format. Analytica 4.4 and earlier don't know about UTF-8, and always stored models using an ASCII character set. Hence, if you load a 4.5 model with unicode characters into Analytica 4.4, each of these extended characters will get converted into two or there garbage characters. See [[Model File Character Encoding]] for more information on this and on how to change encoding.

* When you use the [[Assignment Operator:: ::=|assignment operator]] from a button script to assign an array to a global variable, the existing type of the table is now preserved, whereas formerly such as assignment would change a [[DetermTable]] into a [[Table]]. This would only impact a model in the unlikely event that such as assignment is being used to convert a [[DetermTable]] to a [[Table]].

* When you use the [[Assignment Operator:: ::=|assignment operator]] to change a definition or edit table cell that contains a control ([[Choice]] or [[Checkbox]]), the control is now preserved and the new value is selected, whereas previously the control was replaced by the literal value. This change will have no effect on computed results, but could change the appearance of an edit table in the unlikely event that the assignment operator from a button script is being used to remove controls from a table.

Error Messages/40087

2013-12-16T19:30:52Z

Esherwin: /* Error Message Examples */

= Error Message Examples =

The function Readfromurl is not available in Analytica Free 101.
The function LpDefine is not available in Analytica Professional.

= Cause =

Some Analytica functions are only available in higher editions of Analytica.
For example, Database functions, such as [[DbLabels]], [[DbQuery]], and [[DbTable]], are available only in Analytica Enterprise or higher editions.
And Optimizer functions, such as [[LpDefine]], [[NlpDefine]], and [[SolverInfo]], are only available in Analytica Optimizer.

= Remedy =

To use functions not available in your current Edition of Analytica, you will need to upgrade it to a higher edition.

Note that the Analytica Power Player lets you use models with database access functions and other functions available with Enterprise and higher, but not to create models. Similarly, Power Player with Optimizer lets you use models containing Optimizer functions, created with the Optimizer Edition.

<comments />

Cumulate

2013-10-11T16:26:18Z

Esherwin:

[[Category:Transforming functions]]
[[Category:Doc Status C]] 

= Cumulate(X,I) =

Returns an array with each element being the sum of all of the elements of X along dimension I up to, and including, the corresponding element of X.

= Declaration =

Cumulate(X:Array[I] ; I : Index)

= Library =

Array Functions

= Examples =

{| border="1"
! I →
| 1 || 2 || 3 || 4 || 5 || 6
|-
! X →
| 8 || 2 || 0 || 5 || -3 || 7
|-
! [[Cumulate]](X,I) →
| 8 || 10 || 10 || 15 || 12 || 19

|}

= Library =

Array Functions

= Optional Parameters =

== PassNull ==

Cumulate(X,I,passNull:true)

When the optional «passNull» is omitted or false, [[Cumulate]] ignores [[Null]] values. In that case they have essentially the same effect as a zero, unless they happen to be the first value in «X», in which case they are passed since no numeric values are yet obtained.

When «passNull» is explicitly set to true, then [[Null]] values are passed through as [[Null]] in the result.

:{| border="1"
! X →
| [[«null»]] || [[«null»]] || 4 || 1 || [[«null»]] || [[«null»]] || 1 || 9 || 3 || 2 || [[«null»]]
|-
! [[Cumulate]](X,I) →
| [[«null»]] || [[«null»]] || 4 || 5 || 5 || 5 || 6 || 15||18 || 20|| 20
|-
! [[Cumulate]](X,I,passNull:false) →
| [[«null»]] || [[«null»]] || 4 || 5 || 5 || 5 || 6 || 15||18 || 20|| 20
|-
! [[Cumulate]](X,I,passNull:true) →
| [[«null»]] || [[«null»]] || 4 || 5 || [[«null»]] || [[«null»]] || 6 || 15||18 || 20|| [[«null»]]
|}

== Reset ==

[[Cumulate]](X,I,reset:R)

''New to Analytica 4.3''

The optional «reset» parameter accepts an array of boolean values indexed by «I». At the positions where «reset» is true, [[Cumulate]] starts over. This sets the sum of all previous values to zero, so that the value at that position will be the same as the value in «X».

{| border="1"
! I →
| 1 || 2 || 3 || 4 || 5 || 6 || 7
|-
! X →
| 8 || 2 || 0 || 5 || -3 || 7 || 5
|-
! R →
| 0 || 0 || 1 || 0 || 0 || 1 || 0
|-
! [[Cumulate]](X,I,reset:R) →
| 8 || 10 || 0 || 5 || 2 || 7 || 12
|}

«Reset» can be used to restart the cumulation each time some state change occurs. In such a scenario, the «reset» parameter is set to ''True'' at the first instant (along «I») that the system is in the new state.

Suppose ''State'' is a state designator, indexed by ''I''. The following would compute how long the system has been in the same state for:

[[Cumulate]](1,I,reset:State[@I=@I-1]<>State)

= Notes =

== Recumulate ==

In Analytica 4.2 and earlier, the functionality of the «reset» parameter can be obtained using the ''Recumulate'' library function, which resets the total to zero at selected points. This usage is:
Recumulate(x,b,I)
where b is an array of booleans indexed by I, having 1 at each point where the cumulation is to be reset to zero. Recumulate is implemented as a [[User-Defined Function]] in the example [[media:Recumulate example.ana|Recumulate example.ana]]. A clever usage of this function computes the number of time steps that the system has been in the same state (see the example).

== Use in Dynamic Functions ==

If objects X and Y belong to the same dynamic loop, then the definition of Y should never perform an operation over the Time index on the value of X. When you write such an expression, you presumably intend to operate over the entire Time-indexed array for X, which would thus implicitly refer to future points in time that have not yet been computed, and would therefore be disallowed. However, in reality, the use of X in Y's definition refers to the value of X at the current time point, so that an expression such as Cumulate(X,Time) would actually be cumulating a constant value over time. While that is not disallowed, it is probably not what is intended, and Analytica will issue a warning in this case. You can usually expression operations over Time directly using Dynamic, for example, instead of Cumulate(X,Time) you would define CumX as

Dynamic(X,Self[Time-1] + X)

For more information on dynamic functions, see:
http://wiki.lumina.com/index.php/Dynamic

= See Also =

* [[Uncumulate]]
* [[Sum]]
* [[CumProduct]]
* [[media:Recumulate example.ana|Recumulate example.ana]]

Keyboard Shortcuts

2013-08-24T01:55:59Z

Esherwin: /* Tab as a shortcut */

[[Category:Ana: Status M]] 

[[What's new in Analytica 4.0?]] >
[Most of these shortcuts are new for Analytica 4.0]

=== [[Shortcuts for Table Navigation]] ===

Analytica now supports almost all the standard shortcuts for tables offered by Microsoft Excel. See [[Shortcuts for Table Navigation]] for details.

=== Tab as a shortcut ===

* tab:
** In a Diagram window, select the next node, from left to right, then up to down
** In an Object window, select the next Attribute field
** In a table, select the next cell
* shift+tab: Like tab, but in reverse sequence.

=== Shortcuts for Toolbar buttons ===
* F1: User Guide
* 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.

=== 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.
* F11: Toggle between Edit/Arrow editing modes ([[image:Edit_Mode_Toolbar_Button.jpg]] ←→ [[image:arrowTool.jpg]] ). In Analytica 3.1, this was F2.
* F12, or CTRL+F12: Open/close typescript window

=== Shortcuts using control by letter ===

* CTRL+A: Select all
* CTRL+B: Number Format...
* CTRL+C: Copy selected text, cell or region of a table, or nodes.
* CTRL+D: Duplicate nodes
* CTRL+E: Edit definition
* 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.

=== Shortcuts for adding 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

=== Shortcuts when editing a definition or other attribute ===

* ALT+click on a node: When you are editing the definition (or other attribute) in an Attribute panel, ALT-click on another node in the same diagram. This shortcut is very handy when writing a complex expression.
* Enter
* Return
* CTRL+Return

* CTRL+right-arrow: Move right one token
* CTRL+left-arrow: Move left one token
* 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.
(More to be listed)

=== Shortcuts when editing 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

Dynamic

2013-03-02T02:19:41Z

Esherwin: /* Dynamic( initial1, initial2, ..., initialN, expr ) */

[[category:Evaluation Functions]]
[[Category:Doc Status D]] 

''This page needs work. A better introductory reference for now is the Analytica User Guide chapter 17 on Dynamic Simulation.''

= Dynamic( initial1, initial2, ..., initialN, expr ) =

The dynamic function performs dynamic simulation, calculating its value at each element of Time. Time is a special system index that is built into Analytica, and is the only index that Dynamic can operate over in this fashion. The result of Dynamic is an array indexed by the system index Time.

When the [[Dynamic]] function is used, it must appear as the topmost function in the definition. It can contain one or more initial value parameters, containing the values at @Time=1, @Time=2, ... @Time=N, and then an expression that is used to compute all subsequent values. The expression can get the values of variables at previous time points by using the syntax:

:ident[Time-k]

When the value for @Time=t is being computed, ''X[Time-1]'' refers to the value of X at the previous time period, i.e., at @Time=t-1. What is especially useful is that the value of ''X[Time-1]'' is allowed to depend (directly or indirectly) on the variable that is defined by the Dynamic function. This makes it possible to have cyclic loops within your model, where a variable depends on itself, as long as there is an offset to a previous time point somewhere within the dynamic loop.

The syntax ''X[Time-k]'' is equivalent to ''X[@Time=@Time-k]'' and ''[[Slice]](X,Time,@Time-k)''. The offset ''k'' can be a constant, or it can be computed; however, it is not allowed to refer to a position before the beginning of Time -- e.g., in which ''@Time-k < 1''. There must be at least one non-zero offset before the loop returns to the original Dynamic variable, so that no cycle occurs.

You can also make use of Subscript operations to earlier time points with Dynamic, such as in
: ''X[Time=[[Ceil]](Time/2)]''
or equivalently, [[Subscript]](X,Time,Time/2). You should beware of the difference between identifying a time point by position and identifying a time point by label (associationally). If the elements of your Time index are in increments other than 1, then ''X[Time-1]'' and ''X[@Time=@Time-1]'' refer to the previous time point, while ''X[Time=Time-1]'' may refer to a time point that doesn't even exist, or to a point other than the immediately previous time point.

When the identifier of a variable X is used in the definition for Y, and both X and Y belong to the same dynamic loop, then the identifier X in Y's definition implicitly refers to the value of X at the current time period. Although the final value of X may be indexed by time, the value as seen during the evaluation of Y does not have that dimension. Because of this, you can can refer to the current time point being evaluated by simply using the identifier Time, and you can refer to the position along the time index as @Time. Any identifier (except those appearing in a slice or subscript operation) used in an expression is equivalent to ''X[Time-0]'' or ''[[Slice]](X,Time,@Time)''.

If X and Y belong to the same dynamic loop, then the definition of Y should never perform an operation over the Time index on the value of X. When you write such an expression, you presumably intend to operate over the entire Time-indexed array for X, which would thus implicitly refer to future points in time that have not yet been computed, and would therefore be disallowed. However, in reality, the use of X in Y's definition refers to the value of X at the current time point, so that an expression such as ''[[Cumulate]](X,Time)'' would actually be cumulating a constant value over time. While that is not disallowed, it is probably not what is intended, and Analytica will issue a warning in this case. You can usually expression operations over Time directly using Dynamic, for example, instead of ''[[Cumulate]](X,Time)'' you would define ''CumX'' as
[[Dynamic]](X,Self[Time-1] + X)

As this example shows, the keyword ''Self'' can be used to refer to the current variable that is defined by Dynamic.

= The Big Dynamic Gotcha =

When you refer to an identifier <code>X</code> from within a dynamic loop -- and in fact, from any variable in a dynamic loop, even if the variable is not defined as [[Dynamic]](...) -- you are implicitly refering to <code>X[Time=Time]</code>. In other words, <code>X</code> refers to the value of <code>X</code> ''at the current time period''. The one exception to this is if you use X directly in a slice or subscript operation over the Time index, e.g., <code>X[@Time=@Time-1]</code>.

It is easy to forget this and make stupid mistakes. Many of these mistakes involve attempts to operate over the Time index (as mentioned previously). Some of these can be quite innocent and hard to notice, such as an attempt to get the largest time value using <code>[[Max]](Time)</code>. Because <code>Time</code> is only the current time point, this obtains the current time value.

You are safe in using Time in an index context -- where an index is expected. Thus, if you want the full Time array, use <code>[[IndexValue]](Time)</code>. If you want the length of the time index, use [[Sum]](1,Time).

Another trick is to place your Time-operations in a separate variable outside the dynamic loop. For example:
Variable max_time := [[Max]](Time)

Then you can use max_time from within your dynamic loop expressions without worrying about this mistake.

We also want to urge you to avoid a certain reliance on this implicit Time-slicing in certain cases, since the treatement of these cases are likely to be changed in a future Analytica release. The proposed changes are intended to eliminate the sources for the above common mistakes. If you can avoid these cases, then you will minimize the risk of your existing models "breaking" when these enhancements appear.

The cases to avoid are fairly esoteric, so we hope they won't impact too many people. However, it is good to understand where they are. Suppose Y is a variable inside a dynamic loop, and U is a variable that outside of Y's dynamic loop. U might be outside of any dynamic loop, or it may belong to a different dynamic loop -- whatever the case, Y is not a descendant of U. The case in question then occurs when Y uses U in its definition, and U appears inside an array parameter of a function call. For example, <code>[[Max]](U)</code>. The distinguishing characteristic here is that when you look at the syntax alone, it is conceivable that the function might operate over the Time index. So, if the function obviously operates over the Time index, as in <code>[[Max]](U,Time)</code>, or might operate over the Time index, as in <code>[[Max]](U)</code>, then you should not rely on the fact that U is implicitly sliced over time.

= [[User-Defined Functions]] inside Dynamic Loops =

''new to [[What's new in Analytica 4.2?|Analytica 4.2]]''

In the rare event that a User-Defined Function is part of a dynamic loop, then how the value for variable named in the definition is obtained depends on a number of factors. These rules are designed to allow a UDF to implement array operations across the dynamic index, while co-existing within a recurrence. The ability to embed a UDF within a dynamic loop is new to Analytica 4.2.

When a global variable identifier is evaluated from within a [[User-Defined Functions]], the current dynamic context is dropped if the variable does not belong to the same dynamic loop as the UDF. In contrast, the dynamic context passed through to the evaluation of the variable if the variable belongs to the same dynamic loop as the UDF. The following example illustrates.
Time=1..10
Variable V := 100 * 1.06^(@Time-1)
Variable X := [[Dynamic]](1,F(V))
Variable Y := [[Dynamic]](0,X[Time-1])
Function F(z) := [[Sum]](Z+V+Y,Time)
Here V is not part of any dynamic loop, and X→Y→F()→X forms a dynamic loop.

Consider the evaluation of ''V'' in X's definition when Time=2. Since a variable always preserved dynamic context, V[Time=2] is obtained (= 106). So ''F(106)'' is called. Inside F, when ''Z+V+Y'' is evaluated, these are obtained as Z=106, V (indexed by Time) and Y[Time=2] =1. The full time-indexed value for V is used since it does not belong to the dynamic loop. So at Time=2, F computes (106+V,Time).

= Reverse Dynamic =

''new to [[What's new in Analytica 4.2?|Analytica 4.2]]''

In many dynamic programming applications, one starts with a known ''final value'', then computes the value at each time point as a function of future values. This ''dynamic-in-reverse'' can be accomplished using [[Dynamic]] by specifying the recurrence as the first parameter to dynamic, followed by the final value(s), and then specifying ''reverse:true''.

The example model [[media:Optimal Path Dynamic Programming.ana|Optimal Path Dynamic Programming.ana]] computes the optimal path over a finite horizon. There is a final payout in the last time period, as a function of your final state, and an action cost (a function of action and state) at each intermediate step. Dynamic programming is used to find the optimal policy and the utility at each State x Action x Time point:

Decision Best_Action := [[ArgMax]](Sxa_utility,Action)
Objective Sxa_utility :=
[[Dynamic]]( Sxa_utility[Time+1][Action=Best_action[Time+1]][State=Transition] - Action_cost,
Final_payout,
reverse : true )

Notice the use of [Time+1] rather than the [Time-1] that is commonly used in forward [[Dynamic]] usages.

= Recurrences over non-Time indexes =

''new to [[What's new in Analytica 4.2?|Analytica 4.2]]''

To specify a recurrence over an index other than time using [[Dynamic]], specify the dynamic index in brackets following the word [[Dynamic]], e.g.:

Variable Remaining_Budget := Dynamic[Project]( Budget, Budget[Project-1] - Project_allocation[Project-1] )
Variable Project_Allocation :=(Project_Cost <= Budget) * Project_Cost

The efficiency of [[Dynamic]] computation in Analytica is optimized for the Time index, so use on non-Time indexes may result in substantially slower computation. Therefore, it is advisable to limit the use of Dynamic on non-Time indexes to relatively short dimensions, and to utilize the system Time index for your primary Time index.

When dynamic loops over distinct indexes intersect, a multi-D dynamic computation results. The example model [[media:Dynamic on multiple indexes.ana|Dynamic on multiple indexes.ana]] demonstrates using an example in which [[Dynamic]][Item]] is used to allocate functions among items, then [[Dynamic]][Time] is used to carry-over unspent funds to the next time period where the allocation re-occurs.

When intersecting loops exist, the result for any variable in any of the intersecting dynamic loop may contain all dynamic indexes. The result for some variables, however, might not vary with one of the dynamic indexes. For a given variable, the indexes on which there is no variation may appear in some case and not in others, depending on what order variables are evaluated. The principle of array abstraction generally treats two arrays with differing dimensionality as equivalent if each array is constant on the dimensions that don't appear in the other. Thus, this variation in displayed functionality does not alter the actual value as far as array abstraction is concerned. However, if you are utilizing intersecting dynamic loops on different dynamic indexes, you should be prepared for this seemingly unusual phenomena.

= See Also =

* [[Iterate]]
* [[WhatIf]]
* [[While]]
* [[Slice Assignment]]

Handle Functions

2012-07-11T19:17:18Z

Esherwin: /* About Handles (varTerms) */

[[Category:Meta-Inference Functions]]
[[Category:Doc Status C]] 

[[What's new in Analytica 4.0?]] >

= About Handles (varTerms) =

A '''handle''' (formerly known as '''varTerm''') is a reference or pointer to a variable, index, function, module, or other Analytica object. Using a handle lets you write variables or functions that work with the object itself rather than the value of the object. Usually, if you refer to variable X in an expression, say as:
Variable X := 100
Variable A := X
The value of A will be equal to the value of X, namely 100. But if you write:
Variable B := Handle(X)

B now refers to variable X, and you can now access the Title, Description, Inputs or Outputs of X. You can also create and use lists of handles to objects. For example, the list of indexes of an array, or the inputs or outputs of a variable.

If you define a variable as a list of variables:
Variable A := [X, Y, Z]
the value of A will be the result of evaluating X, Y, and Z. The index of A is a list of handles to X, Y, and Z. It usually shows the titles of X, Y, and Z. If you double-click the title (or identifier) of an object in the index in a Table window, it opens the Object view for that object. If "Show By Identifier" is on (from the Object menu, or if you toggle it with control-Y), the index shows identifiers rather than titles. Either way, you can double click to open the object view.

Some attributes consist of lists of handles, notably Inputs, Outputs, and Contains (the objects in a module). You can use these to write functions to find the ancestors, descendants, or contents of an object.

= Handle(v) =

Returns a handle (pointer or reference) to object v.

Function Handle( X : Variable ; AsIndex : optional boolean atomic )

If you want to create a user-defined function that returns a Handle, in most cases the return value needs to involve a call to the Handle function. If you simply place the identifier of a local variable (even if it declared as Variable) as the return value, it will be evaluated. For example, consider these two functions:

Function Fu1( X : Variable ) := X
Function Fu2( X : Variable ) := Handle(X)
Variable Va1 := 5

Suppose you evaluate Fu1(Va1) and Fu2(Va1). Fu1 returns the value of Va1, that is 5. Fu2 returns a handle to the Va1 object. Hence, to return a Handle, a call to Function Handle was necessary.

You can declare a local variable to be a Handle using, for example,
var a := Handle(Va1) do ...
where Va1 is the identifier of an object. In the scope of this var declaration, a then becomes an alias for Va1. In other words, anywhere you might use the identifier Va1 in an expression, you could equivalently use a.

To create an alias to an index, use
var I := Handle( In1, AsIndex:True ) do ...
The local variable I will then serve as an alias to the original index In1 inside the scope of this var statement. The AsIndex parameter causes I's index values to be used when I appears in a value context (this is relevant when the original object is a self-indexed array, having both a value and an index value).

When an index has handles as elements, and you wish to subscript across that index, the recommended syntax is:
A[ I = Handle(x) ]
In this example, x would be the identifier appearing as one of the elements of I.

= Function ListOfHandles =

ListOfHandles( identifiers : repeated Object )

''new to Analytica 4.3''

Returns a list of handles to several objects specified by their identifiers. For example:
ListOfHandles( X,Y,Z )

returns a list with three elements, the first item being a handle to X, etc. The end result is similar to the result of evaluating:
[Handle(X),Handle(Y),Handle(Z)]

but of course is more convenient. However, there is another distinction. When you define a variable using the explicit list syntax, [Handle(X),...], the variable ends up being a 1-D self-indexed array, where the index elements are each an expression, such as Handle(X), the value is the handle itself. In some scenarios that is nice, in that is shows you where the result came from when viewing a result table, but when defining an index you often want the index values to be the handles themselves. Using ListOfHandles(..) directly accomplishes this.

= Function HandleFromIdentifier =

HandleFromIdentifier( varName : atomic text )

(formerly GetVariableByName).

Finds an object in the global namespace having the indicated name and returns a handle to that object. If no such object exists, returns Null (use IsUndef to test for null if you worry about backward compatibility).

One danger with using this function is that Analytica has no dependency influence information. For example, the following expression
var x := HandleFromIdentifier("Va1") do x
evaluates Va1 and returns that value; however, if Va1 were to change, Analytica would have no way of knowing that this result needs to be invalidated. Obviously, in this example, it would better to use just the identifier Va1 in the expression, but as a basis of comparison, note that Analytica would be aware of the dependency influence if this variation were used:
var x:= Handle(Va1) do x
If the value of Va1 changes, it would know that this value needs to be re-computed.

== Handle to Caller of a [[User-Defined Functions|UDF]] ==

(note: This does not need to be mentioned in the user-guide)

A special case, HandleFromIdentifier("_Caller"), can be used in a user-defined function to obtain a handle to the variable, function, or button that invoked the function. From a nested function, the variable or button that invoked the parent function is returned. The tag "_Caller" will not conflict with an identifier since identifiers may not begin with an underscore.

Using this, it is possible to create a function that bases its behavior based on a property of the variable that invokes it. Your function might, for example, use the value of a [[User-Defined Attribute]] (UDA) of the calling variable.

= Function [[IndexesOf]] =

IndexesOf( A : Array )

Returns a list of handles, each one serving as a handle to an index of array A.

This is similar to IndexNames(A), except that IndexesOf returns the handles of the indexes, while IndexNames returns the identifier of each index as a text value.

It is possible for an array to have more than one local index having the same identifier. Obviously, we don't recommend, but in the unusual case where this occurs, the handles returned by IndexesOf are unambiguous, where the results of IndexNames are ambiguous.

= Local Variables and Handles =

The value of a local variable, like a global variable, may be a number, text, or handle or an array or scalar. When a local variable is set to a single handle (not an array), there are two behaviors that are possible, depending on the ''type'' of local variable.

Starting with Analytica 4.2, there are essentially two (pure) types of local variables: [[MetaVar]]s and [[LocalAlias]]es. These behave quite differently when you assign them to be a single handle.

A [[MetaVar]] local contains whatever you assign it. Whenever you use its identifier in a value context, its identifier acts as the value assigned to it. So if you use a [[MetaVar]] identifier in a value context, its value is a handle to an object (not the value of the object pointed to). When you [[Assignment|assign]] to a [[MetaVar]], you are just changing its value -- the object previously pointed to is not impacted.

A [[LocalAlias]] local acts as an alias of another object when it is set to be a handle. Any use of a [[LocalAlias]]'s identifier in an expression is equivalent to using the identifier of the object pointed to (at least for objects that exist in the global namespace). If you [[Assignment|assign]] a new value to a [[LocalAlias]]-type local, you change the object pointed to, and the local remains an alias to that same variable (note: you are only allowed to change the value of another object when the assignment is evaluated from a button script).

When writing [[meta-inference]] algorithms, where your algorithm will be manipulating handles to objects, we recommend that you declare all your local variables using only [[MetaVar..Do]] or [[LocalAlias..Do]] depending on your intention, and avoid the use of [[Var..Do]], or even [[For..Do]]. The recommendation is only for your own conceptual simplicity, since MetaVar and LocalAlias have such clean semantics, it is var less confusing. Note however that [[MetaVar..Do]] and [[LocalAlias..Do]] are [[What's new in Analytica 4.2?|new to Analytica 4.2]].

When a local variable that is declared using [[Var..Do]] is assigned a handle, it acts as a hybrid of the [[MetaVar]] and [[LocalAlias]] semantics. In a value context, its identifier acts as an alias. However, when you assign to it, the local is changed to the new value without changing the object originally pointed to.

You may find yourself iterating over a list or array of handles, where you intend to operate on each handle in the list. Rather than use:
[[For]] v:=ListOfHandle Do «body»
it is better to use one of:
[[LocalAlias]] y := ListOfHandle Do «body»
[[MetaVar]] z[] := ListOfHandle Do «body»
In each iteration of «body», y will be an alias of the object pointed to in the first form, and z will contain a handle to the object in the second form.

= Function [[IsHandle]](x) =

The function [[IsHandle]](X) tests whether the value contained in «X» is a handle. If the value of «X» is an array, then it tests whether each cell of the array contains a handle, and returns an array of 0s and 1s.

The call [[IsHandle]](X,local:true), where «X» is a local variable, tests whether the local variable contains a handle. Note that if you don't include the ''local:true'' parameter, you are testing the value contained within the local, rather than the local itself (except in the case of a [[MetaVar |meta-local]], in which case the test is valid even without the optional ''local:true''). See [[IsHandle]] for details.

= Display of Handles in Result Tables =

When a handle object is displayed in a result table cell, the ''title'' or ''identifier'' of the object pointed to will be displayed, depending on whether the "''Show by identifier''" preference is on. Pressing CTRL-Y toggles this preference, and thus toggles the display between title and identifier.

Double clicking on a cell displaying a handle opens the parent diagram of the object, with the object highlighted. You can change this default behavior to open its Object window instead by setting the preference attribute [[Att_hyperlinkPref]]. The attribute is inherited, so if you set it for a single variable, the setting controls the behavior only from that variable's result table. If you set it for a module, that defines the default behavior within that module, or if you set it for your top-level model object, it defines the default behavior model-wide. The attribute has three possible values:
* 1 = Jump to object's object window (behavior in Analytica 4.1 and earlier)
* 2 = Jump to parent diagram containing object, with object selected (default in 4.2 and later)
* 3 = For handles to modules, open the module's diagram with nothing selected. For non-modules, jump to diagram containing object with object selected.

If-Then-Else

2012-05-19T00:46:48Z

Esherwin:

[[Category:Doc Status D]] 

= If a Then b Else c =

This conditional expression evaluates and returns «b» if «a» is true, or «c» if «a» is false.

Variable X := 1M
Variable Y := 1
 
If X > Y Then X Else Y → 1M

== Omitting Else ==

It is possible to omit the Else clause:
If X < Y Then [[MsgBox]]("Unexpected: X was found to be less than Y");
X-Y

When the Else clause is omitted and «a» is false, a warning will be issued if the result value is actually used (in the above example, it isn't used, so no warning results). If you ignore the warning, the result is [[Null]].

Usually, you should omit the ''Else «c»'' part only in a compound expression, where ''Then «b»'' is followed by a semi-colon, followed by other expressions. In such case, the result of If-Then is not actually used. See also [[#Perils of Side-Effects]] below.

== Array Parameters ==

Conditional expressions get more interesting when they work on arrays, in which case array-abstraction generalizes to multi-dimensional cases. When «a» is an array with a mixture of true and false values, the result is an array with the same indexes as «a», which individual cells containing «b» or «c» as appropriate.

{|
|
Variable x := -2..2
 
If x>0 Then 'Positive'
Else If x<0 Then 'Negative'
Else 'Zero'
| →
| [[Image:If then else1.jpg]]
|}

If «b» or «c» are arrays with the same indexes as «a», the corresponding values from «b» or «c» are returned according to whether «a» is true or false.

{|
|
If x>=0 Then [[Sqrt]](x) Else 'Imaginary'
| →
| [[Image:If then else2.jpg]]
|}

== When «b» and «c» are evaluated ==

If-Then-Else processes all its parameters using array operations. The full arrays for «b» is computed whenever «a» contains at least one true value. So in the earlier example:
If X>=0 Then [[Sqrt]](x) Else 'Imaginary'
the square root of ''x'' is computed even for the negative values of ''X'', even though they are replaced with 'Imagingary'' in the final result. Similarly, if «a» contains at least one false value, then «c» is computed entirely, even for values where «a» is true.

The apparently wasted computation is usually more than offset by the faster computation obtained from Analytica's ability to process the expressions using array processing. However, this not always true, and in some cases a case failing the antecedent condition can lead to an error when «b» (or «c») is evaluated.

== To avoid evaluating «b» or «c» ==

The entire evaluation of «b» is skipped (i.e., the expression for «b» is not evaluated at all) when «a» is scalar false, or is an array containing only false values. Likewise, «c» is not evaluated when «a» is scalar true or when «a» is an array containing only true values.

To avoid computations for sub-arrays of «b» (or of «c»), you must employ explicit iteration (via [[User-Defined Functions]] using [[Function_Parameter_Qualifiers#Dimensionality_Qualifiers|Parameter Dimensionality Qualifiers]]. Usually the iteration is writen in such a way to ensure that «a» is a scalar each time the conditional is processed.

[[Var]] xi[] := x Do
If xi>=0 Then [[Sqrt]](xi) Else 'Imaginary'

The overhead of explicit iteration may slow down computation substantially. As long as you aren't experiencing errors, in the vast majority of cases it is better to simply let «b» and «c» be evaluated in full.

== Embedded Warnings ==

When [[Sqrt]](x) is evaluated on a negative number, an embedded warning is issued. When that warning occurs from within an expression embedded in «b» or «c», it might have no effect on the final result if «a» doesn't select it. When the embedded warning occurs, Analytica figures out whether the warning could potentially impact the final result, or whether it will end up being ignored. When Analytica concludes that the case generating the warning does not impact the final result, then the warning is not shown to the the user, even if ''Show Result Warnings'' is on. This logic makes it possible for you to write very intuitive expressions to avoid problematic cases, as was done with the [[Sqrt]] example above; however, the logic to determine whether the warning will impact the final result does consume computational cycles. If you determine a particular computation involving If-then-else, where embedded warnings are probably occurring within «b» or «c», a speed-up can be obtained by surrounding the expression with a call to [[IgnoreWarnings]]():

[[IgnoreWarnings]]( If x>=0 Then [[Sqrt]](x) else 'Imaginary' )

In this example, no change to behavior occurs, but speed-up occurs because the extra process to determine whether the case generating the warning is eventually ignored is skipped.

= Perils of Side-Effects =

Extreme care should be exercised when using [[Assignment Operator]]s within conditionals. When dealing with array cases, [[Assignment Operator|assignment]] occuring within «b» or «c» is likely to produce counter-intuitive results.

The following example illustrates the point:

[[Var]] a := [[Min]]([x,y]);
If a<0 Then a:=0;
[[Sqrt]](a)

When ''x'' and ''y'' are scalar values, the above expressions produces the intuitive result. However, consider what happens when ''x'' and ''y'' are arrays:

{| border="1"
! i → !! 1 !! 2 !! 3 !! 4
|-
! x → || 3 || -4 || 2 || 1
|-
! y → || 2 || 5 || 7 || -1
|}

After the initial assignment, ''a'' becomes:
{| border="1"
! i → !! 1 !! 2 !! 3 !! 4
|-
! a → || 2 || -4 || 2 || -1
|-
! a<0 → || 0 || 1 || 0 || 1

|}

But now, when the conditional is evaluated, ''a<0'' is an array containing at least one true value, so the ''Then'' clause is evaluated. The assignment ''a:=0'' sets the local variable ''a'' to scalar 0. So the final result if evaluating the expression is scalar 0 -- not an array indexed by ''i''.

A good rule of thumb is that if you cannot guarantee that the ''If'' condition, «a», is scalar, do not embed [[Assignment Operator|assignment operations]] inside the ''Then'' or ''Else'' parts.

To guarantee that ''a'' is scalar, the expression could be re-expressed as:
[[Atomic..Do|Atomic]] a := [[Min]]([x,y]);
If a<0 Then a:=0;
[[Sqrt]](a)

This expression causes looping when x or y is array-valued. To continue leveraging the efficiency of array processing, it may be better to avoid looping. In most cases, you can avoid placing assignment inside «b» or «c» in a manner such as:
[[Var]] a := [[Min]]([x,y]);
a := If a<0 Then 0 Else a;
[[Sqrt]](a)

= Dimensionality of the Result =

When <code>If «a» Then «b» Else «c»</code> is evaluated, the result will have the union of the dimensions of the parameters that get evaluated. So, the result will also include any dimensions of «a», along with any dimensions of «b» if «a» was true anywhere, along with any dimensions of «c» if «a» was false anywhere.

Because of this conditional nature, it is not possible to predict the dimensionality of the result in advance before you know the result of «a». Dimensions may or may not be included depending on whether «b» or «c» are actually evaluated.

=== Ifall-Then-Else ===

When you want to ensure that the final dimensionality is always the same, regardless if the final values for «a», you can employ the <code>Ifall «a» Then «b» Else «c»</code> variation. '''Ifall''' always evaluates all parameters, «a», «b» and «c», and includes the union of all their dimensions in the final result. Thus, the final dimensionality is independent of whether the individual elements of «a» are true or false.

When you use <code>Ifall-Then-Else</code>, you incur two hits to efficiency. First, since «b» and «c» are always evaluated in every case, evaluations occur that would be skipped by <code>If-Then-Else</code> when «a» is constant. Second, because the result may have more dimensions, downstream computations may have to compute using larger arrays.

=== Ifonly-Then-Else ===

In contrast to the <code>Ifall-Then-Else<code> construct, <code>Ifonly-Then-Else</code> may actually return a result with fewer dimensions than <code>If-Then-Else</code>. Smaller arrays can reduce the total number of computations performed by downstream operations, and thus improve efficiency.

The distinction between '''If''' and '''Ifonly''' occurs when «a» is contains all true. In this case, as with '''If''', «b» will be evaluated and «c» will not be evaluated. The difference is that '''If''' includes the dimensions of «a» in the result while '''Ifonly''' does not. When «a» is a constant array, we can think of this as being ''equivalent'' to a scalar in the eyes of array abstraction, so ''Ifonly'' reduces the antecedant to a scalar prior to evaluating the remainder of <code>Ifonly-Then-Else</code>.

== Dimensionality Summary Table ==

{| border="1"
! rowspan=2 | Case
! colspan=3 | Dimensionality of result for
|-
! <code>If «a» Then «b» Else «c»</code>
! <code>Ifonly «a» Then «b» Else «c»</code>
! <code>Ifall «a» Then «b» Else «c»</code>
|-
! «a» is everywhere true || Da U Db || Db || Da U Db U Dc
|-
! «a» is everywhere false || Da U Dc || Dc || Da U Db U Dc
|-
! «a» contains both true and false || Da U Db U Dc || Da U Db U Dc || Da U Db U Dc
|}

= See Also =

* [[Expression Syntax]]

If-Then-Else

2012-05-19T00:46:23Z

Esherwin:

[[Category:Doc Status D]] 

= If a Then b Else c =

This conditional expression evaluates and returns «b» if «a» is true, or «c» if «a» is false.

Variable X := 1M
Variable Y := 1
 
If X > Y Then X Else Y → 1M

== Omitting Else ==

It is possible to omit the Else clause:
If X < Y Then [[MsgBox]]("Unexpected: X was found to be less than Y");
X-Y

When the Else clause is omitted and «a» is false, a warning will be issued if the result value is actually used (in the above example, it isn't used, so no warning results). If you ignore the warning, the result is [[Null]].

Usally, you should omit the ''Else «c»'' part only in a compound expression, where ''Then «b»'' is followed by a semi-colon, followed by other expressions. In such case, the result of If-Then is not actually used. See also [[#Perils of Side-Effects]] below.

== Array Parameters ==

Conditional expressions get more interesting when they work on arrays, in which case array-abstraction generalizes to multi-dimensional cases. When «a» is an array with a mixture of true and false values, the result is an array with the same indexes as «a», which individual cells containing «b» or «c» as appropriate.

{|
|
Variable x := -2..2
 
If x>0 Then 'Positive'
Else If x<0 Then 'Negative'
Else 'Zero'
| →
| [[Image:If then else1.jpg]]
|}

If «b» or «c» are arrays with the same indexes as «a», the corresponding values from «b» or «c» are returned according to whether «a» is true or false.

{|
|
If x>=0 Then [[Sqrt]](x) Else 'Imaginary'
| →
| [[Image:If then else2.jpg]]
|}

== When «b» and «c» are evaluated ==

If-Then-Else processes all its parameters using array operations. The full arrays for «b» is computed whenever «a» contains at least one true value. So in the earlier example:
If X>=0 Then [[Sqrt]](x) Else 'Imaginary'
the square root of ''x'' is computed even for the negative values of ''X'', even though they are replaced with 'Imagingary'' in the final result. Similarly, if «a» contains at least one false value, then «c» is computed entirely, even for values where «a» is true.

The apparently wasted computation is usually more than offset by the faster computation obtained from Analytica's ability to process the expressions using array processing. However, this not always true, and in some cases a case failing the antecedent condition can lead to an error when «b» (or «c») is evaluated.

== To avoid evaluating «b» or «c» ==

The entire evaluation of «b» is skipped (i.e., the expression for «b» is not evaluated at all) when «a» is scalar false, or is an array containing only false values. Likewise, «c» is not evaluated when «a» is scalar true or when «a» is an array containing only true values.

To avoid computations for sub-arrays of «b» (or of «c»), you must employ explicit iteration (via [[User-Defined Functions]] using [[Function_Parameter_Qualifiers#Dimensionality_Qualifiers|Parameter Dimensionality Qualifiers]]. Usually the iteration is writen in such a way to ensure that «a» is a scalar each time the conditional is processed.

[[Var]] xi[] := x Do
If xi>=0 Then [[Sqrt]](xi) Else 'Imaginary'

The overhead of explicit iteration may slow down computation substantially. As long as you aren't experiencing errors, in the vast majority of cases it is better to simply let «b» and «c» be evaluated in full.

== Embedded Warnings ==

When [[Sqrt]](x) is evaluated on a negative number, an embedded warning is issued. When that warning occurs from within an expression embedded in «b» or «c», it might have no effect on the final result if «a» doesn't select it. When the embedded warning occurs, Analytica figures out whether the warning could potentially impact the final result, or whether it will end up being ignored. When Analytica concludes that the case generating the warning does not impact the final result, then the warning is not shown to the the user, even if ''Show Result Warnings'' is on. This logic makes it possible for you to write very intuitive expressions to avoid problematic cases, as was done with the [[Sqrt]] example above; however, the logic to determine whether the warning will impact the final result does consume computational cycles. If you determine a particular computation involving If-then-else, where embedded warnings are probably occurring within «b» or «c», a speed-up can be obtained by surrounding the expression with a call to [[IgnoreWarnings]]():

[[IgnoreWarnings]]( If x>=0 Then [[Sqrt]](x) else 'Imaginary' )

In this example, no change to behavior occurs, but speed-up occurs because the extra process to determine whether the case generating the warning is eventually ignored is skipped.

= Perils of Side-Effects =

Extreme care should be exercised when using [[Assignment Operator]]s within conditionals. When dealing with array cases, [[Assignment Operator|assignment]] occuring within «b» or «c» is likely to produce counter-intuitive results.

The following example illustrates the point:

[[Var]] a := [[Min]]([x,y]);
If a<0 Then a:=0;
[[Sqrt]](a)

When ''x'' and ''y'' are scalar values, the above expressions produces the intuitive result. However, consider what happens when ''x'' and ''y'' are arrays:

{| border="1"
! i → !! 1 !! 2 !! 3 !! 4
|-
! x → || 3 || -4 || 2 || 1
|-
! y → || 2 || 5 || 7 || -1
|}

After the initial assignment, ''a'' becomes:
{| border="1"
! i → !! 1 !! 2 !! 3 !! 4
|-
! a → || 2 || -4 || 2 || -1
|-
! a<0 → || 0 || 1 || 0 || 1

|}

But now, when the conditional is evaluated, ''a<0'' is an array containing at least one true value, so the ''Then'' clause is evaluated. The assignment ''a:=0'' sets the local variable ''a'' to scalar 0. So the final result if evaluating the expression is scalar 0 -- not an array indexed by ''i''.

A good rule of thumb is that if you cannot guarantee that the ''If'' condition, «a», is scalar, do not embed [[Assignment Operator|assignment operations]] inside the ''Then'' or ''Else'' parts.

To guarantee that ''a'' is scalar, the expression could be re-expressed as:
[[Atomic..Do|Atomic]] a := [[Min]]([x,y]);
If a<0 Then a:=0;
[[Sqrt]](a)

This expression causes looping when x or y is array-valued. To continue leveraging the efficiency of array processing, it may be better to avoid looping. In most cases, you can avoid placing assignment inside «b» or «c» in a manner such as:
[[Var]] a := [[Min]]([x,y]);
a := If a<0 Then 0 Else a;
[[Sqrt]](a)

= Dimensionality of the Result =

When <code>If «a» Then «b» Else «c»</code> is evaluated, the result will have the union of the dimensions of the parameters that get evaluated. So, the result will also include any dimensions of «a», along with any dimensions of «b» if «a» was true anywhere, along with any dimensions of «c» if «a» was false anywhere.

Because of this conditional nature, it is not possible to predict the dimensionality of the result in advance before you know the result of «a». Dimensions may or may not be included depending on whether «b» or «c» are actually evaluated.

=== Ifall-Then-Else ===

When you want to ensure that the final dimensionality is always the same, regardless if the final values for «a», you can employ the <code>Ifall «a» Then «b» Else «c»</code> variation. '''Ifall''' always evaluates all parameters, «a», «b» and «c», and includes the union of all their dimensions in the final result. Thus, the final dimensionality is independent of whether the individual elements of «a» are true or false.

When you use <code>Ifall-Then-Else</code>, you incur two hits to efficiency. First, since «b» and «c» are always evaluated in every case, evaluations occur that would be skipped by <code>If-Then-Else</code> when «a» is constant. Second, because the result may have more dimensions, downstream computations may have to compute using larger arrays.

=== Ifonly-Then-Else ===

In contrast to the <code>Ifall-Then-Else<code> construct, <code>Ifonly-Then-Else</code> may actually return a result with fewer dimensions than <code>If-Then-Else</code>. Smaller arrays can reduce the total number of computations performed by downstream operations, and thus improve efficiency.

The distinction between '''If''' and '''Ifonly''' occurs when «a» is contains all true. In this case, as with '''If''', «b» will be evaluated and «c» will not be evaluated. The difference is that '''If''' includes the dimensions of «a» in the result while '''Ifonly''' does not. When «a» is a constant array, we can think of this as being ''equivalent'' to a scalar in the eyes of array abstraction, so ''Ifonly'' reduces the antecedant to a scalar prior to evaluating the remainder of <code>Ifonly-Then-Else</code>.

== Dimensionality Summary Table ==

{| border="1"
! rowspan=2 | Case
! colspan=3 | Dimensionality of result for
|-
! <code>If «a» Then «b» Else «c»</code>
! <code>Ifonly «a» Then «b» Else «c»</code>
! <code>Ifall «a» Then «b» Else «c»</code>
|-
! «a» is everywhere true || Da U Db || Db || Da U Db U Dc
|-
! «a» is everywhere false || Da U Dc || Dc || Da U Db U Dc
|-
! «a» contains both true and false || Da U Db U Dc || Da U Db U Dc || Da U Db U Dc
|}

= See Also =

* [[Expression Syntax]]