What's new in Analytica 5.4?

2020-06-15T20:53:21Z

Ldavidson: /* Syntax coloring and fonts in expressions */

Analytica 5.4 will be the next future release of Analytica. It is currently under development. The current release is [[Analytica 5.3]]. This page is under construction, but will list the enhancements that are new to Analytica 5.4 since [[Analytica 5.3]]. If you have an Analytica subscription, you will be able to test drive a preliminary version when [[Analytica 5.4]] goes beta -- check the [[Beta Tester Page]] for status.

<center>[[image:Analytica-5.4.jpg]]</center>

== Syntax coloring and fonts in expressions ==

The big improvement in Release 5.4 is the way it shows expressions in a Definition attribute (also Check, OnClick, OnChange and other attributes showing expressions). Here's an example:

[[File:Analytica_definition.jpg]]

# it colors the text to distinguish identifiers of variables or functions, keywords (like IF, FOR, AND...), comments, text literals, and more.
# it uses a mono space font (each character has the same width as in typewriters), which is more common for code editors
# it underlines any syntax error with red wavy lines.

If you don't think these are improvements, you can revert each back to its original look using a system variable accessible from the '''Definition''' menu:
# Set the syntax colors using system variable "Syntax colors" from ''Definition / System variables / Settings / Syntax colors'' (see [[Sys_SyntaxColors]])
# You can turn syntax coloring on and off using system variable "Enable syntax coloring" from ''Definition / System variables / Settings / Enable syntax coloring'' (see [[Sys_EnableSyntaxColo]])
# Go back to variable width font using system variable '''Enable fixed font''' back from 1 to 0 from ''Definition / System variables / Settings / Enable fixed font'' (see [[Sys_EnableFixedFont]])
# Disable error underlining with [[Sys EnableErrorUnder]], accessible from ''Definition / System variables / Settings / Enable error underlining'' (see [[Sys_EnableErrorUnder]])

===Module color inheritance===

Module nodes now inherit their color from the Node style default rather than their containing module. See [[Sys UseLegacyColors]] if you want to revert back to the legacy behavior that inherited color from the containing module.

=== Multichoice option ===

The ''expr'' pulldown menu for an index node now includes [[MultiChoice]] -- very useful when you want to be able to select one, several, or all options. This was available before but not on the menu.

== Graphing ==
=== Custom graph axis/key titles===

You can now modify or hide the title for each graph axis and the Key instead of showing the title of the variable (or Index). On the graph (in edit mode), right click on the title or axis you want to change, and select '''Change axis title''' or '''Change key title'''. The dialog lets you edit the title -- or enter blank to hide it. For example, it's kind of redundant to show title Years (e.g. 2010, 2020, 2030) as "Years".

The dialog has a checkbox to let you to set the revised title (or hidden title) for every graph that uses that index or variable as an axis or key.

==== '''Axis/Key Title''' attribute====

You can also see and set nondefault text used for axes and key titles for a variable or index with the '''Axis/Key Title''' attribute in the [[Object window]] or [[Attribute panel]]. You first need to set this attribute to show from the [[Attribute panel]]. This will apply to all graphs using the variable. But, it's usually easier to use the right-click menu on the title described above.

====How the default axis/key title is determined====

There are rules about how the default title is determined. If you have changed the axis/key title for all graphs using the index or variable, then the default is what you changed this to. If you have not changed the axis/key title then the default is the title of the index or variable, or, if that title is blank, the default is the identifier of the index or variable.

However, if you have checked the checkbox referred to above then blanked out the title, this resets any change you made for all graphs and the default is the title of the index or variable or, if that title is blank, the default is the identifier of the index or variable.

The popup "Use default axis title?" (or key title) will tell you what the default will be. You will see words in one of these three variations:

"Do you want to use the default axis title for Revenue, which is Annual revenue (global axis title override)?" - This indicates that the default is the axis title "Annual revenue" that has been designated to be used in all graphs using the index or variable Revenue.

"Do you want to use the default axis title for Revenue, which is Revenue (Title attribute)?" - This indicates that the default is the title "Revenue" of the index or variable Revenue.

"Do you want to use the default axis title for Revenue, which is Revenue (identifier)?" - This indicates that Revenue has no title and the default is the identifier of the index or variable Revenue.

=== Exceedance probability ===

There is a new '''Exceedance probability''' option in the [[Uncertainty views]] for each result. It shows the probability that the value of an uncertain variable is greater than each value. It's the complement (1 - p) of the Cumulative probability (CDF). In some fields, like cybersecurity risk, many people prefer exceedance probability distributions to CDFs.

[[File:Exceedance probability in Uncertainty view.png|400px]]

== Tables ==
* Shift+Space now extends the selected cells to include the entire row(s).
* Ctrl+Space now extends the selected cells to include the entire column(s).

== Built-in Functions ==
=== Changes to existing functions ===
* The [[UncertainLMH]] distribution has been changed to use the Hadlock-Bickel-Johnson Quantile Parameterized Distribution by default, rather than the Keelin SPT distribution. The HBJ-QPD is preferred since it is maximally feasible. This impacts [[UncertainLMH]], [[DensUncertainLMH]], [[CumUncertainLMH]] and [[CumUncertainLMHInv]] functions.
** A new system variable has been added: [[UncertainLMH_Method]], which selects the default algorithm used by these functions. If you need backward compatibility with 5.3 with this distribution, your can set this to 2. But note: Due to a small improvement, [[DensUncertainLMH]] with keelin algorithm is slightly more accurate, so numbers may differ out around the 9th decimal point compared to previously.
** A new optional parameter, «method», was added to each of these functions, which you can use to select the algorithm (HBJ-QPD or K-SPT) for the specific call.
* [[AskMsgText]] and [[AskMsgNumber]]: Added an option to include a checkbox on the dialog.
* [[Cdf]] Added an option to return the exceedance curve.
* Eliminated a spurious "dynamic-loop cyclic dependency" error message that appeared in a 2-D [[Dynamic]] loop. This is a case where there wasn't really a cyclic dependency, so the error message was a false positive. A 2-D dynamic loop is where two dynamic loops on different dynamic indexes intersect, so that the nodes in that loop have to iterate over two dynamic indexes (fairly rare).
* A «condition» parameter was added to [[Flatten]]. Makes it easy to include only the items that satisfy the «condition» in the flattened result.

=== New functions ===
* [[COMEnumerate]] -- enumerates the elements of an enumerable COM object.

=== Evaluation engine ===
* When the outermost function of a variable's Definition is [[Mid]]() or [[Sample]](), the evaluation occurs slightly differently than before, which ensures that the mid-value and sample-value are the same when the Definition contains a random component. When the engine sees [[Mid]]() at the outer level, it tells it that this variable should only be evaluated in mid-mode. The sample value will share the same mid value. This results in a difference from previous releases when the Definition contains a random component, such as:
*::<code>[[Mid]](Random())</code>
Previously, children that used its sample-value would see a different value than children who used its mid-value, and there wasn't any convenient way to tell it to use the same value for both mid- and sample-values.
** The same idea applies to expressions inside a call to [[Dynamic]], for example <code>[[Dynamic]](0, Mid(Random()+Self[Time-1]))</code>.
** If you want the legacy behavior (because you want identical random sequences if you find this changes them), press F12 to open the typescript window and type: <code>[[RandomLegacyRelease]]:50300</code>.
** The above descriptions apply symmetrically when the definition has [[Sample]]() as the outer function.

== Other Misc ==
* It now omits the currency symbol for non-finite values -- e.g. it shows <code>INF</code> instead of <code>$INF</code> and <code>NAN</code> instead of <code>$NAN</code> -- when you have selected currency in [[Number format]].
* A new attribute, [[NodeBorderColor]], can be set to get a non-black node border color. You can set this on a class object to change the default border color. There is no GUI for this yet, it has to be changed via typescript.

What's new in Analytica 5.4?

2020-06-15T20:16:14Z

Ldavidson: /* Syntax coloring and fonts in expressions */

Analytica 5.4 will be the next future release of Analytica. It is currently under development. The current release is [[Analytica 5.3]]. This page is under construction, but will list the enhancements that are new to Analytica 5.4 since [[Analytica 5.3]]. If you have an Analytica subscription, you will be able to test drive a preliminary version when [[Analytica 5.4]] goes beta -- check the [[Beta Tester Page]] for status.

<center>[[image:Analytica-5.4.jpg]]</center>

== Syntax coloring and fonts in expressions ==

The big improvement in Release 5.4 is the way it shows expressions in a Definition attribute (also Check, OnClick, OnChange and other attributes showing expressions). Here's an example:

[[File:Analytica_definition.jpg]]

# it colors the text to distinguish identifiers of variables or functions, keywords (like IF, FOR, AND...), comments, text literals, and more.
# it uses a mono space font (each character has the same width as in typewriters), which is more common for code editors
# it underlines any syntax error with red wavy lines.

If you don't think these are improvements, you can revert each back to its original look using a system variable accessible from the '''Definition''' menu:
# Set the syntax colors using system variable "Syntax colors" from ''Definition / System variables / Settings / Syntax colors'' (see [[Sys_SyntaxColors]])'
# You can turn syntax coloring on and off using system variable "Enable syntax coloring" from ''Definition / System variables / Settings / Enable syntax coloring'' (see [[Sys_EnableSyntaxColo]])'
# Go back to variable width font using system variable '''Enable fixed font''' back from 1 to 0 from ''Definition / System variables / Settings / Enable fixed font'' (see [[Sys_EnableFixedFont]])'
# Disable error underlining with [[Sys EnableErrorUnder]], accessible from ''Definition / System variables / Settings / Enable error underlining'' (see [[Sys_EnableErrorUnder]])'.

===Module color inheritance===

Module nodes now inherit their color from the Node style default rather than their containing module. See [[Sys UseLegacyColors]] if you want to revert back to the legacy behavior that inherited color from the containing module.

=== Multichoice option ===

The ''expr'' pulldown menu for an index node now includes [[MultiChoice]] -- very useful when you want to be able to select one, several, or all options. This was available before but not on the menu.

== Graphing ==
=== Custom graph axis/key titles===

You can now modify or hide the title for each graph axis and the Key instead of showing the title of the variable (or Index). On the graph (in edit mode), right click on the title or axis you want to change, and select '''Change axis title''' or '''Change key title'''. The dialog lets you edit the title -- or enter blank to hide it. For example, it's kind of redundant to show title Years (e.g. 2010, 2020, 2030) as "Years".

The dialog has a checkbox to let you to set the revised title (or hidden title) for every graph that uses that index or variable as an axis or key.

==== '''Axis/Key Title''' attribute====

You can also see and set nondefault text used for axes and key titles for a variable or index with the '''Axis/Key Title''' attribute in the [[Object window]] or [[Attribute panel]]. You first need to set this attribute to show from the [[Attribute panel]]. This will apply to all graphs using the variable. But, it's usually easier to use the right-click menu on the title described above.

====How the default axis/key title is determined====

There are rules about how the default title is determined. If you have changed the axis/key title for all graphs using the index or variable, then the default is what you changed this to. If you have not changed the axis/key title then the default is the title of the index or variable, or, if that title is blank, the default is the identifier of the index or variable.

However, if you have checked the checkbox referred to above then blanked out the title, this resets any change you made for all graphs and the default is the title of the index or variable or, if that title is blank, the default is the identifier of the index or variable.

The popup "Use default axis title?" (or key title) will tell you what the default will be. You will see words in one of these three variations:

"Do you want to use the default axis title for Revenue, which is Annual revenue (global axis title override)?" - This indicates that the default is the axis title "Annual revenue" that has been designated to be used in all graphs using the index or variable Revenue.

"Do you want to use the default axis title for Revenue, which is Revenue (Title attribute)?" - This indicates that the default is the title "Revenue" of the index or variable Revenue.

"Do you want to use the default axis title for Revenue, which is Revenue (identifier)?" - This indicates that Revenue has no title and the default is the identifier of the index or variable Revenue.

=== Exceedance probability ===

There is a new '''Exceedance probability''' option in the [[Uncertainty views]] for each result. It shows the probability that the value of an uncertain variable is greater than each value. It's the complement (1 - p) of the Cumulative probability (CDF). In some fields, like cybersecurity risk, many people prefer exceedance probability distributions to CDFs.

[[File:Exceedance probability in Uncertainty view.png|400px]]

== Tables ==
* Shift+Space now extends the selected cells to include the entire row(s).
* Ctrl+Space now extends the selected cells to include the entire column(s).

== Built-in Functions ==
=== Changes to existing functions ===
* The [[UncertainLMH]] distribution has been changed to use the Hadlock-Bickel-Johnson Quantile Parameterized Distribution by default, rather than the Keelin SPT distribution. The HBJ-QPD is preferred since it is maximally feasible. This impacts [[UncertainLMH]], [[DensUncertainLMH]], [[CumUncertainLMH]] and [[CumUncertainLMHInv]] functions.
** A new system variable has been added: [[UncertainLMH_Method]], which selects the default algorithm used by these functions. If you need backward compatibility with 5.3 with this distribution, your can set this to 2. But note: Due to a small improvement, [[DensUncertainLMH]] with keelin algorithm is slightly more accurate, so numbers may differ out around the 9th decimal point compared to previously.
** A new optional parameter, «method», was added to each of these functions, which you can use to select the algorithm (HBJ-QPD or K-SPT) for the specific call.
* [[AskMsgText]] and [[AskMsgNumber]]: Added an option to include a checkbox on the dialog.
* [[Cdf]] Added an option to return the exceedance curve.
* Eliminated a spurious "dynamic-loop cyclic dependency" error message that appeared in a 2-D [[Dynamic]] loop. This is a case where there wasn't really a cyclic dependency, so the error message was a false positive. A 2-D dynamic loop is where two dynamic loops on different dynamic indexes intersect, so that the nodes in that loop have to iterate over two dynamic indexes (fairly rare).
* A «condition» parameter was added to [[Flatten]]. Makes it easy to include only the items that satisfy the «condition» in the flattened result.

=== New functions ===
* [[COMEnumerate]] -- enumerates the elements of an enumerable COM object.

=== Evaluation engine ===
* When the outermost function of a variable's Definition is [[Mid]]() or [[Sample]](), the evaluation occurs slightly differently than before, which ensures that the mid-value and sample-value are the same when the Definition contains a random component. When the engine sees [[Mid]]() at the outer level, it tells it that this variable should only be evaluated in mid-mode. The sample value will share the same mid value. This results in a difference from previous releases when the Definition contains a random component, such as:
*::<code>[[Mid]](Random())</code>
Previously, children that used its sample-value would see a different value than children who used its mid-value, and there wasn't any convenient way to tell it to use the same value for both mid- and sample-values.
** The same idea applies to expressions inside a call to [[Dynamic]], for example <code>[[Dynamic]](0, Mid(Random()+Self[Time-1]))</code>.
** If you want the legacy behavior (because you want identical random sequences if you find this changes them), press F12 to open the typescript window and type: <code>[[RandomLegacyRelease]]:50300</code>.
** The above descriptions apply symmetrically when the definition has [[Sample]]() as the outer function.

== Other Misc ==
* It now omits the currency symbol for non-finite values -- e.g. it shows <code>INF</code> instead of <code>$INF</code> and <code>NAN</code> instead of <code>$NAN</code> -- when you have selected currency in [[Number format]].
* A new attribute, [[NodeBorderColor]], can be set to get a non-black node border color. You can set this on a class object to change the default border color. There is no GUI for this yet, it has to be changed via typescript.

What's new in Analytica 5.4?

2020-06-15T20:14:21Z

Ldavidson: /* Syntax coloring and fonts in expressions */

Analytica 5.4 will be the next future release of Analytica. It is currently under development. The current release is [[Analytica 5.3]]. This page is under construction, but will list the enhancements that are new to Analytica 5.4 since [[Analytica 5.3]]. If you have an Analytica subscription, you will be able to test drive a preliminary version when [[Analytica 5.4]] goes beta -- check the [[Beta Tester Page]] for status.

<center>[[image:Analytica-5.4.jpg]]</center>

== Syntax coloring and fonts in expressions ==

The big improvement in Release 5.4 is the way it shows expressions in a Definition attribute (also Check, OnClick, OnChange and other attributes showing expressions). Here's an example:

[[File:Analytica_definition.jpg]]

# it colors the text to distinguish identifiers of variables or functions, keywords (like IF, FOR, AND...), comments, text literals, and more.
# it uses a mono space font (each character has the same width as in typewriters), which is more common for code editors
# it underlines any syntax error with red wavy lines.

If you don't think these are improvements, you can revert each back to its original look using a system variable accessible from the '''Definition''' menu:
# Set the syntax colors using system variable "Syntax colors" from ''Definition / System variables / Settings / Syntax colors'' (see [[Sys_SyntaxColors]])'
# You can turn syntax coloring on and off using system variable "Enable syntax coloring" from ''Definition / System variables / Settings / Enable syntax coloring'' (see [[Sys_EnableSyntaxColo]])'
# Go back to variable width font using system variable '''Enable fixed font''' back from 1 to 0 from ''Definition / System variables / Settings / Enable fixed font'' (see [[Sys_EnableFixedFont]])'
# Disable error underlining with [[Sys EnableErrorUnder]], accessible from ''Definition / System variables / Settings / Enable error underlining'' (see [[Sys_EnableErrorUnder]])'.

===Module color inheritance===

Module nodes now inherit their color from the Node style default rather than their containing module. See [[Sys UseLegacyColors]] if you want to revert back to the legacy behavior that inherited color from the containing module.

=== Multichoice option ===

The ''expr'' pulldown menu for an index node now includes [[MultiChoice]] -- very useful when you want to be able to select one, several, or all options. This was available before but not on the menu.

== Graphing ==
=== Custom graph axis/key titles===

You can now modify or hide the title for each graph axis and the Key instead of showing the title of the variable (or Index). On the graph (in edit mode), right click on the title or axis you want to change, and select '''Change axis title''' or '''Change key title'''. The dialog lets you edit the title -- or enter blank to hide it. For example, it's kind of redundant to show title Years (e.g. 2010, 2020, 2030) as "Years".

The dialog has a checkbox to let you to set the revised title (or hidden title) for every graph that uses that index or variable as an axis or key.

==== '''Axis/Key Title''' attribute====

You can also see and set nondefault text used for axes and key titles for a variable or index with the '''Axis/Key Title''' attribute in the [[Object window]] or [[Attribute panel]]. You first need to set this attribute to show from the [[Attribute panel]]. This will apply to all graphs using the variable. But, it's usually easier to use the right-click menu on the title described above.

====How the default axis/key title is determined====

There are rules about how the default title is determined. If you have changed the axis/key title for all graphs using the index or variable, then the default is what you changed this to. If you have not changed the axis/key title then the default is the title of the index or variable, or, if that title is blank, the default is the identifier of the index or variable.

However, if you have checked the checkbox referred to above then blanked out the title, this resets any change you made for all graphs and the default is the title of the index or variable or, if that title is blank, the default is the identifier of the index or variable.

The popup "Use default axis title?" (or key title) will tell you what the default will be. You will see words in one of these three variations:

"Do you want to use the default axis title for Revenue, which is Annual revenue (global axis title override)?" - This indicates that the default is the axis title "Annual revenue" that has been designated to be used in all graphs using the index or variable Revenue.

"Do you want to use the default axis title for Revenue, which is Revenue (Title attribute)?" - This indicates that the default is the title "Revenue" of the index or variable Revenue.

"Do you want to use the default axis title for Revenue, which is Revenue (identifier)?" - This indicates that Revenue has no title and the default is the identifier of the index or variable Revenue.

=== Exceedance probability ===

There is a new '''Exceedance probability''' option in the [[Uncertainty views]] for each result. It shows the probability that the value of an uncertain variable is greater than each value. It's the complement (1 - p) of the Cumulative probability (CDF). In some fields, like cybersecurity risk, many people prefer exceedance probability distributions to CDFs.

[[File:Exceedance probability in Uncertainty view.png|400px]]

== Tables ==
* Shift+Space now extends the selected cells to include the entire row(s).
* Ctrl+Space now extends the selected cells to include the entire column(s).

== Built-in Functions ==
=== Changes to existing functions ===
* The [[UncertainLMH]] distribution has been changed to use the Hadlock-Bickel-Johnson Quantile Parameterized Distribution by default, rather than the Keelin SPT distribution. The HBJ-QPD is preferred since it is maximally feasible. This impacts [[UncertainLMH]], [[DensUncertainLMH]], [[CumUncertainLMH]] and [[CumUncertainLMHInv]] functions.
** A new system variable has been added: [[UncertainLMH_Method]], which selects the default algorithm used by these functions. If you need backward compatibility with 5.3 with this distribution, your can set this to 2. But note: Due to a small improvement, [[DensUncertainLMH]] with keelin algorithm is slightly more accurate, so numbers may differ out around the 9th decimal point compared to previously.
** A new optional parameter, «method», was added to each of these functions, which you can use to select the algorithm (HBJ-QPD or K-SPT) for the specific call.
* [[AskMsgText]] and [[AskMsgNumber]]: Added an option to include a checkbox on the dialog.
* [[Cdf]] Added an option to return the exceedance curve.
* Eliminated a spurious "dynamic-loop cyclic dependency" error message that appeared in a 2-D [[Dynamic]] loop. This is a case where there wasn't really a cyclic dependency, so the error message was a false positive. A 2-D dynamic loop is where two dynamic loops on different dynamic indexes intersect, so that the nodes in that loop have to iterate over two dynamic indexes (fairly rare).
* A «condition» parameter was added to [[Flatten]]. Makes it easy to include only the items that satisfy the «condition» in the flattened result.

=== New functions ===
* [[COMEnumerate]] -- enumerates the elements of an enumerable COM object.

=== Evaluation engine ===
* When the outermost function of a variable's Definition is [[Mid]]() or [[Sample]](), the evaluation occurs slightly differently than before, which ensures that the mid-value and sample-value are the same when the Definition contains a random component. When the engine sees [[Mid]]() at the outer level, it tells it that this variable should only be evaluated in mid-mode. The sample value will share the same mid value. This results in a difference from previous releases when the Definition contains a random component, such as:
*::<code>[[Mid]](Random())</code>
Previously, children that used its sample-value would see a different value than children who used its mid-value, and there wasn't any convenient way to tell it to use the same value for both mid- and sample-values.
** The same idea applies to expressions inside a call to [[Dynamic]], for example <code>[[Dynamic]](0, Mid(Random()+Self[Time-1]))</code>.
** If you want the legacy behavior (because you want identical random sequences if you find this changes them), press F12 to open the typescript window and type: <code>[[RandomLegacyRelease]]:50300</code>.
** The above descriptions apply symmetrically when the definition has [[Sample]]() as the outer function.

== Other Misc ==
* It now omits the currency symbol for non-finite values -- e.g. it shows <code>INF</code> instead of <code>$INF</code> and <code>NAN</code> instead of <code>$NAN</code> -- when you have selected currency in [[Number format]].
* A new attribute, [[NodeBorderColor]], can be set to get a non-black node border color. You can set this on a class object to change the default border color. There is no GUI for this yet, it has to be changed via typescript.

What's new in Analytica 5.4?

2020-06-15T20:10:30Z

Ldavidson: /* Syntax coloring and fonts in expressions */

Analytica 5.4 will be the next future release of Analytica. It is currently under development. The current release is [[Analytica 5.3]]. This page is under construction, but will list the enhancements that are new to Analytica 5.4 since [[Analytica 5.3]]. If you have an Analytica subscription, you will be able to test drive a preliminary version when [[Analytica 5.4]] goes beta -- check the [[Beta Tester Page]] for status.

<center>[[image:Analytica-5.4.jpg]]</center>

== Syntax coloring and fonts in expressions ==

The big improvement in Release 5.4 is the way it shows expressions in a Definition attribute (also Check, OnClick, OnChange and other attributes showing expressions). Here's an example:

[[File:Analytica_definition.jpg]]

# it colors the text to distinguish identifiers of variables or functions, keywords (like IF, FOR, AND...), comments, text literals, and more.
# it uses a mono space font (each character has the same width as in typewriters), which is more common for code editors
# it underlines any syntax error with red wavy lines.

If you don't think these are improvements, you can revert each back to its original look using a system variable accessible from the '''Definition''' menu:
# Set the syntax colors using system variable "Syntax colors" from ''Definition / System variables / Settings / Syntax colors'' (see [[Sys_SyntaxColors]])'
# You can turn syntax coloring on and off using system variable "Enable syntax coloring" from ''Definition / System variables / Settings / Enable syntax coloring'' (see [[Sys_EnableSyntaxColo]])
# Go back to variable width font using system variable '''Enable fixed font''' back from 1 to 0 from ''Definition / System variables / Settings / Enable fixed font'' (see [[Sys_EnableFixedFont]])'
# Disable error underlining with [[Sys EnableErrorUnder]], accessible from ''Definition / System variables / Settings / Enable error underlining'' (see [[Sys_EnableErrorUnder]])'.

===Module color inheritance===

Module nodes now inherit their color from the Node style default rather than their containing module. See [[Sys UseLegacyColors]] if you want to revert back to the legacy behavior that inherited color from the containing module.

=== Multichoice option ===

The ''expr'' pulldown menu for an index node now includes [[MultiChoice]] -- very useful when you want to be able to select one, several, or all options. This was available before but not on the menu.

== Graphing ==
=== Custom graph axis/key titles===

You can now modify or hide the title for each graph axis and the Key instead of showing the title of the variable (or Index). On the graph (in edit mode), right click on the title or axis you want to change, and select '''Change axis title''' or '''Change key title'''. The dialog lets you edit the title -- or enter blank to hide it. For example, it's kind of redundant to show title Years (e.g. 2010, 2020, 2030) as "Years".

The dialog has a checkbox to let you to set the revised title (or hidden title) for every graph that uses that index or variable as an axis or key.

==== '''Axis/Key Title''' attribute====

You can also see and set nondefault text used for axes and key titles for a variable or index with the '''Axis/Key Title''' attribute in the [[Object window]] or [[Attribute panel]]. You first need to set this attribute to show from the [[Attribute panel]]. This will apply to all graphs using the variable. But, it's usually easier to use the right-click menu on the title described above.

====How the default axis/key title is determined====

There are rules about how the default title is determined. If you have changed the axis/key title for all graphs using the index or variable, then the default is what you changed this to. If you have not changed the axis/key title then the default is the title of the index or variable, or, if that title is blank, the default is the identifier of the index or variable.

However, if you have checked the checkbox referred to above then blanked out the title, this resets any change you made for all graphs and the default is the title of the index or variable or, if that title is blank, the default is the identifier of the index or variable.

The popup "Use default axis title?" (or key title) will tell you what the default will be. You will see words in one of these three variations:

"Do you want to use the default axis title for Revenue, which is Annual revenue (global axis title override)?" - This indicates that the default is the axis title "Annual revenue" that has been designated to be used in all graphs using the index or variable Revenue.

"Do you want to use the default axis title for Revenue, which is Revenue (Title attribute)?" - This indicates that the default is the title "Revenue" of the index or variable Revenue.

"Do you want to use the default axis title for Revenue, which is Revenue (identifier)?" - This indicates that Revenue has no title and the default is the identifier of the index or variable Revenue.

=== Exceedance probability ===

There is a new '''Exceedance probability''' option in the [[Uncertainty views]] for each result. It shows the probability that the value of an uncertain variable is greater than each value. It's the complement (1 - p) of the Cumulative probability (CDF). In some fields, like cybersecurity risk, many people prefer exceedance probability distributions to CDFs.

[[File:Exceedance probability in Uncertainty view.png|400px]]

== Tables ==
* Shift+Space now extends the selected cells to include the entire row(s).
* Ctrl+Space now extends the selected cells to include the entire column(s).

== Built-in Functions ==
=== Changes to existing functions ===
* The [[UncertainLMH]] distribution has been changed to use the Hadlock-Bickel-Johnson Quantile Parameterized Distribution by default, rather than the Keelin SPT distribution. The HBJ-QPD is preferred since it is maximally feasible. This impacts [[UncertainLMH]], [[DensUncertainLMH]], [[CumUncertainLMH]] and [[CumUncertainLMHInv]] functions.
** A new system variable has been added: [[UncertainLMH_Method]], which selects the default algorithm used by these functions. If you need backward compatibility with 5.3 with this distribution, your can set this to 2. But note: Due to a small improvement, [[DensUncertainLMH]] with keelin algorithm is slightly more accurate, so numbers may differ out around the 9th decimal point compared to previously.
** A new optional parameter, «method», was added to each of these functions, which you can use to select the algorithm (HBJ-QPD or K-SPT) for the specific call.
* [[AskMsgText]] and [[AskMsgNumber]]: Added an option to include a checkbox on the dialog.
* [[Cdf]] Added an option to return the exceedance curve.
* Eliminated a spurious "dynamic-loop cyclic dependency" error message that appeared in a 2-D [[Dynamic]] loop. This is a case where there wasn't really a cyclic dependency, so the error message was a false positive. A 2-D dynamic loop is where two dynamic loops on different dynamic indexes intersect, so that the nodes in that loop have to iterate over two dynamic indexes (fairly rare).
* A «condition» parameter was added to [[Flatten]]. Makes it easy to include only the items that satisfy the «condition» in the flattened result.

=== New functions ===
* [[COMEnumerate]] -- enumerates the elements of an enumerable COM object.

=== Evaluation engine ===
* When the outermost function of a variable's Definition is [[Mid]]() or [[Sample]](), the evaluation occurs slightly differently than before, which ensures that the mid-value and sample-value are the same when the Definition contains a random component. When the engine sees [[Mid]]() at the outer level, it tells it that this variable should only be evaluated in mid-mode. The sample value will share the same mid value. This results in a difference from previous releases when the Definition contains a random component, such as:
*::<code>[[Mid]](Random())</code>
Previously, children that used its sample-value would see a different value than children who used its mid-value, and there wasn't any convenient way to tell it to use the same value for both mid- and sample-values.
** The same idea applies to expressions inside a call to [[Dynamic]], for example <code>[[Dynamic]](0, Mid(Random()+Self[Time-1]))</code>.
** If you want the legacy behavior (because you want identical random sequences if you find this changes them), press F12 to open the typescript window and type: <code>[[RandomLegacyRelease]]:50300</code>.
** The above descriptions apply symmetrically when the definition has [[Sample]]() as the outer function.

== Other Misc ==
* It now omits the currency symbol for non-finite values -- e.g. it shows <code>INF</code> instead of <code>$INF</code> and <code>NAN</code> instead of <code>$NAN</code> -- when you have selected currency in [[Number format]].
* A new attribute, [[NodeBorderColor]], can be set to get a non-black node border color. You can set this on a class object to change the default border color. There is no GUI for this yet, it has to be changed via typescript.

Sys EnableSyntaxColo

2020-06-15T20:09:09Z

Ldavidson: Created page with "Set this system variable to 1 if you want the parser to color fields of different syntactic types it finds in definitions and other attribute fields that take parseable expres..."

2020-03-03T19:18:35Z

Ldavidson: Ldavidson uploaded a new version of File:Syntax colors.png

What's new in Analytica 5.4?

2020-02-20T17:38:51Z

Ldavidson: /* Custom axis/key titles */

Analytica 5.4 will be the next future release of Analytica. It is currently under development. The current release is [[Analytica 5.3]]. This page is under construction, but will list the enhancements that are new to Analytica 5.4 since [[Analytica 5.3]]. If you have an Analytica subscription, you will be able to test drive a preliminary version when [[Analytica 5.4]] goes beta -- check the [[Beta Tester Page]] for status.

== Editing expressions ==

===Fixed-spaced font===
Attributes that hold expressions such as Definition, Check, OnClick, etc., are now shown in a fixed-width font.

There is a user-preference setting to turn this off: Definition / System variables / Settings / Enable fixed font
===Syntax coloration===
Coloration is now used within an expression to differentiate identifiers, keywords, comments, text literals, etc.

Customize the actual colors used at '''Definition / System variables / Settings / Syntax colors'''. Changes here apply to your computer only, and are not saved with the model.

===Error underlining===
Syntax errors within an expression are underlined in red while editing.

You can turn this on and off using [[Sys EnableErrorUnder]]. Access the system variable using Definition / System variables / Settings / Enable error underlining.

===Module color inheritance===
There is a change in 5.4 in how module nodes inherit their colors. Now instead of using a containing module, modules use Node style default. This doesn't have to affect module colors in pre-5,4 legacy models. See [[Sys UseLegacyColors]] for details.

=== Multichoice option ===
On the definition-type pulldown for an index node, the options now include [[MultiChoice]]. This is very useful for "selected scenario" indexes.

== Graphing ==
=== Custom axis/key titles===
By default, Analytica uses a variable's title and units to form the axis or key title as it appears on the graph. But you can now override this, and use different text for your axis title or key title on the graph. Just right-click (in edit mode) on the key title or axis title and select '''Change axis title''' or '''Change key title'''.

When you type the new title, there is a checkbox that allows you to set your new text as the title for every graph that uses the given index or variable as an axis or key. Or, you can clear the title text entire to either hide the title, or reset to the default title.

You can also set the text used for axes and key titles for a specific object, in all graphs where that variable is used, from the [[Object window]] or [[Attribute panel]] by setting the '''Axis/Key Title''' attribute. You need to show this attribute first from the [[Attribute panel]]. However, you can also change this as described in the previous paragraph.

====How the default axis/key title is determined====
There are rules about how the default title is determined. If you have changed the axis/key title for all graphs using the index or variable, then the default is what you changed this to. If you have not changed the axis/key title then the default is the title of the index or variable, or, if that title is blank, the default is the identifier of the index or variable.

However, if you have checked the checkbox referred to above then blanked out the title, this resets any change you made for all graphs and the default is the title of the index or variable or, if that title is blank, the default is the identifier of the index or variable.

The popup "Use default axis title?" (or key title) will tell you what the default will be. You will see words in one of these three variations:

"Do you want to use the default axis title for Revenue, which is Annual revenue (global axis title override)?" - This indicates that the default is the axis title "Annual revenue" that has been designated to be used in all graphs using the index or variable Revenue.

"Do you want to use the default axis title for Revenue, which is Revenue (Title attribute)?" - This indicates that the default is the title "Revenue" of the index or variable Revenue.

"Do you want to use the default axis title for Revenue, which is Revenue (identifier)?" - This indicates that Revenue has no title and the default is the identifier of the index or variable Revenue.

=== Exceedance probability ===
The '''Exceedance probability''' (at <code>x</code>) of an uncertain quantity is the probability the outcome is greater than or equal to <code>x</code>. This is a dual to the cumulative probability, which is the probability that the outcome is less than or equal to <code>x</code>. Some fields prefer the use of Exceedance probability to CDFs.

Exceedance probability has been added to the available uncertainty views.

== Built-in Functions ==
=== Changes to existing functions ===
* The [[UncertainLMH]] distribution has been changed to use the Hadlock-Bickel-Johnson Quantile Parameterized Distribution by default, rather than the Keelin SPT distribution. The HBJ-QPD is preferred since it is maximally feasible. This impacts [[UncertainLMH]], [[DensUncertainLMH]], [[CumUncertainLMH]] and [[CumUncertainLMHInv]] functions.
** A new system variable has been added: [[UncertainLMH_Method]], which selects the default algorithm used by these functions. If you need backward compatibility with 5.3 with this distribution, your can set this to 2. But note: Due to a small improvement, [[DensUncertainLMH]] with keelin algorithm is slightly more accurate, so numbers may differ out around the 9th decimal point compared to previously.
** A new optional parameter, «method», was added to each of these functions, which you can use to select the algorithm (HBJ-QPD or K-SPT) for the specific call.
* [[AskMsgText]] and [[AskMsgNumber]]: Added an option to include a checkbox on the dialog.
* [[Cdf]] Added an option to return the exceedance curve.
* Eliminated a spurious "dynamic-loop cyclic dependency" error message that appeared in a 2-D [[Dynamic]] loop. This is a case where there wasn't really a cyclic dependency, so the error message was a false positive. A 2-D dynamic loop is where two dynamic loops on different dynamic indexes intersect, so that the nodes in that loop have to iterate over two dynamic indexes (fairly rare).
* A «condition» parameter was added to [[Flatten]]. Makes it easy to include only the items that satisfy the «condition» in the flattened result.

=== New functions ===
* [[COMEnumerate]] -- enumerates the elements of an enumerable COM object.

== Other Misc ==
* When you have currency turned on in the number format, it now omits the currency symbol for non-finite values, i.e., it prints <code>INF</code> instead of <code>$INF</code> and <code>NAN</code> instead of <code>$NAN</code>.

What's new in Analytica 5.4?

2020-02-12T21:26:17Z

Ldavidson: Edited the Error underlining section and added the Module color inheritance section.

What's new in Analytica 5.4?

2020-02-12T21:22:36Z

Ldavidson: /* Error underlining */

What's new in Analytica 5.4?

2020-02-12T21:20:13Z

Ldavidson: /* Error underlining */

Sys UseLegacyColors

2020-02-12T20:54:07Z

Ldavidson:

This system variables has the values 0 (false) and 1 (true). In 5.4 we have changed our scheme for how a module node inherits its color.

The old inheritance scheme: pre-5.4 a module would inherit its color from a containing module.

The new inheritance scheme: in 5.4 and after a module inherits its color from the color of the module class as set in Node style defaults, which make module color inheritance consistent with non-module node color inheritance.

However, there are legacy pre-5.4 models still usable in 5.4 and, in case bringing them up in 5.4 is expected to have them use the same colors as before, we provide this system variable to control which scheme is used. If this is set to true, we use the new scheme. If this is set to false, we use the old scheme.

If we bring up a model that indicates it was last saved before 5.4, we set this variable to true and if this model is saved in 5.4, we save the value of this variable as true with the model, so we have a permanent indication that it is a legacy model.

If we bring up a model that was saved in 5.4, the last value of this variable has been saved in the model file, so this handles both cases, of models created in 5.3 or before and saved in 5.4 or created and saved in 5.4.

You can of course change this back to false to get the new inheritance scheme. But you can then change it back to true to get the old.

To make this user friendly, if your model is recognized as being created in 5.3 or earlier, but you use Node style defaults to set the color of any module type, we automatically set this variable to false so that your setting in Node style default takes over. You can always set the variable to true again to back this out.

Sys UseLegacyColors

2020-02-12T20:53:37Z

Ldavidson: Created page with "This system variables has the values 0 (false) and 1 (true). In 5.4 we have changed our scheme for how a module node inherits its color. The old inheritance scheme: pre-5.4 a..."

This system variables has the values 0 (false) and 1 (true). In 5.4 we have changed our scheme for how a module node inherits its color.

The old inheritance scheme: pre-5.4 a module would inherit its color from a containing module.

The new inheritance scheme: in 5.4 and after a module inherits its color from the color of the module class as set in Node style defaults, which make module color inheritance consistent with non-module node color inheritance.

However, there are legacy pre-5.4 models still usable in 5.4 and, in case bringing them up in 5.4 is expected to have them use the same colors as before, we provide this system variable to control which scheme is used. If this is set to true, we use the new scheme. If this is set to false, we use the old scheme.

If we bring up a model that indicates it was last saved before 5.4, we set this variable to true and if this model is saved in 5.4, we save the value of this variable as true with the model, so we have a permanent indication that it is a legacy model.

If we bring up a model that was saved in 5.4, the last value of this variable has been saved in the model file, so this handles both cases, of models created in 5.3 or before and saved in 5.4 or created and saved in 5.4.

You can of course change this back to false to get the new inheritance scheme. But you can then change it back to true to get the old.

To make this user friendly, if your model is recognized as being created in 5.3 or earlier, but you use Node style defaults to set the color of any module type, we automatically set this variable to false to that your setting in Node style default takes over. You can always set the variable to true again to back this out.

Sys TokenType

2020-02-12T20:42:27Z

Ldavidson:

This system variable is one index for the system variable SyntaxColors (see [[Sys SyntaxColors]]). This indexes the token types values of colors in the rows of the SyntaxColors table. This cannot be changed. The members of this index are comments, text literals, keywords, variables, identifiers. Here is what these mean:

comments - Analytica comments, of the forms /* comment text */ or { comment text }

text literals - strings enclosed in quotes, of the forms '[text ' or " text "

keywords - reserved words in Analytica such as if, then, else, do, local, etc.

variables - these are words that are not keywords and not declared variables and not identifiers of any Analytica nodes or functions; by default, these are lighter colored than identifiers and help you spot typos from failing to type resolved names correctly or else spot intended names that you typed before having actually defined them

identifiers - these are declared variables or else resolved identifiers of Analytica nodes or functions

Sys SyntaxColors

2020-02-12T20:40:03Z

Ldavidson:

This system variable is a two dimensional table that you can edit to control syntax coloring in expression fields such as definitions in object windows and in the attribute pane. This is indexed by [[Sys TokenType]] and [[Sys RedGreenBlue]]. The table is stored in the registry and read from there at startup. Any editing changes you make will update the registry, if these changes are valid.

Here is the table with initial default values:

[[image:syntax colors.png]]

The row and column headers are not editable, and you cannot add any rows or columns. Only the data cells can be changed, and these cells only allow integer values between 0 and 255, inclusive. Any other values will cause an error and you will get an error popup explaining these rules and suggesting that you correct your error. If you say yes, go back to editing, the edit table will revert back to was it was before.

The rows give the RGB components of the colors used in expression fields for various syntactic categories. Here are the categories:

comments - Analytica comments, of the forms /* comment text */ or { comment text }

text literals - strings enclosed in quotes, of the forms '[text ' or " text "

keywords - reserved words in Analytica such as if, then, else, do, local, etc.

variables - these are words that are not keywords and not declared variables and not identifiers of any Analytica nodes or functions; by default, these are lighter colored than identifiers and help you spot typos from failing to type resolved names correctly or else spot intended names that you typed before having actually defined them

identifiers - these are declared variables or else resolved identifiers of Analytica nodes or functions

Note that syntax coloring is continuously updated as you type into expression fields.

File:Syntax colors.png

2020-02-12T20:28:12Z

Ldavidson:

Sys SyntaxColors

2020-02-12T20:18:54Z

Ldavidson: Created page with "This system variable is a two dimensional table that you can edit to control syntax coloring in expression fields such as definitions in object windows and in the attribute pa..."

Sys EnableFixedFont

2020-02-12T20:04:03Z

Ldavidson: Created page with "This system variable has the values 0 (false) or 1 (true). When it is true, Analytica will display expressions in expressions fields such as definitions in object windows or t..."

Sys EnableErrorUnder

2020-02-12T19:56:50Z

Ldavidson: Created page with "The system variable identifier is Sys_EnableErrorUnder, and the more readable name is Enable error underlining. This has possible values 0 (false) and 1 (true). When true, thi..."

2018-12-21T18:28:32Z

Ldavidson: Added description of new Remove quotes and Add quotes options for editing description and definition fields

The current release is [[Analytica 5.1]]. Analytica 5.2 is currently under development -- and so is this page.

These are improvements in Analytica and ADE release 5.2. (As usual, we don't list bug fixes except the most notable cases.)

== Graphing ==
Graphs have some new interactive manual scaling and a new polygon fill feature, as described below.

=== Interactive zooming ===
* Drag the mouse horizontally to zoom to a manually-scaled x-axis interval:
::[[image:graph_zoom_horiz.png]] → [[image:graph_zoom_horiz_after.png]]
::Transparent blue selection rectangle appears while dragging. After drag, Y is still autoscaled, but now to the data in the selected range.
* Drag the mouse diagonally to zoom to manually-scaled intervals on both axes:
::[[image:graph_zoom_diag.png]] → [[image:graph_zoom_diag_after.png]]
* When you move the mouse over a zoomed graph, autoscale hover icon buttons appear. Click on one to auto-scale that axis.
::[[image:graph_zoom_autoscale.png]] → [[image:graph_zoom_autoscaley_after.png]]
::Clicked on the vertical axis autoscale hover icon. Horizontal axis is still manually scaled.
* Drag vertically to zoom to a manually-scaled y-axis interval.
::[[image:graph_zoom_vert.png]] → [[image:graph_zoom_vert_after.png]]
* Zooming has the same effect as changing the manual scale range in Graph Setup. In fact, it records your selected end points there.
::[[image:graph_zoom_graphsetup_after.png]]

=== Key item visibility states ===
[[Analytica 5.1]] introduced a feature to toggle the visibility of individual curves on a graph by clicking on its corresponding key item. Analytica 5.2 includes some further enhancement to this popular feature.

==== Turn on all, Turn off all ====
Right-click on a graph key and you'll see the options '''Turn on all key items''' and '''Turn off all key items'''. These can save you many clicks when there are a lot of key items and you want to turn almost all of them off.

==== Toggle line, symbol visibility ====

::[[image:Line and point graph.png]]
In the preceding graph, the points in a data set appear as symbols without any lines connecting them, and a best-fit line appears appears on the same graph without symbols. This is done by starting with a Line+Symbol plot style, like this:
:[[image:How to line and point graph.png]]
Notice that in the starting line+symbol plot, each key item has a line and a symbol. When you click on one of them multiple times in a row, the key item toggles from line+symbol → off → line-only → symbol-only → line+symbol. So with just a few clicks on the key items, you get to the line only and symbols only series on the same plot.

When you have multiple keys, with the line, symbol or symbol size each depicting different information, each key toggles through three states: On → Off → Partial → On. In the full off state, the data is fully hidden -- so if you hide a line, the symbols for that curve are also hidden, or if you hide a symbol, the line segments to and from that symbol hide. When a item in a line key is partial, the curve's line isn't shown, but its symbols continue to show. When an item in a symbol key is partial, the line to that datum remains, but the symbol does not appear.

::[[image:graph_key_symbol_partial.png]]

In the above graph, the 2 points corresponding to '''Least''' would appear at x=2 in the fully-on graph, but fit_err=Least is been clicked once, putting it into the off state. As a result, there is a gap in the lines at x=2. In the symbol size key (x cat), the x_cat=8 item is in the partial state. The points corresponding to x_cat=8 appear at x=8. In this case the lines pass through the points, but the symbols are hidden.

When fit_graph=y in the line key is off, all the red "ink" on the graph disappears. But when it is in the partial state, the line disappears but the symbols continue to show, as illustrated here:
::[[image:graph_key_line_partial.png]]

==== Save visibility states ====
Changes to key item visibility reset by default when you close and re-open a graph anew. If you want your current visibility state to be saved as the starting point next time the graph is opened, select '''Save key item visibilities''' from the right-mouse menu.

=== Polygon fill plots ===
When you plot a curve in an X-Y plot, there is now a polygon fill option that fills the interior of the polygon(s). For example, starting with this data, already plotted as Latitude vs Longitude
::[[image:California_unfilled_plot.png]]
you can use the new Polygon fill type (the Fill type option is new).
::[[image:Graph_setup_polygon_filltype.png]]
The difference between alternate and solid arises when a curve crosses itself. In this example with a state outline, that doesn't happen so they are equivalent. Polygon fill closes each curve segment (null data starts a new segment) and fills the interior.
::[[image:California_filled_plot.png]]
and viola!
::[[image:Red state blue state.png]]

=== Other graphing ===

* Bug fix impacting marginal abatement graphs
* Changing symbol size role less likely to swap other roles, less confusing

== Expression language & Engine ==

=== Declaring local identifiers ===

==== Omission of initial value====

When declaring a local, you can now omit its initial value, so that
:<code>[[Local]] x;</code>
is equivalent to
:<code>[[Local]] x := Null</code>;

==== Multiple locals in one declaration ====

You can declare multiple local identifiers in the same Local declaration. For example,
:<code>Local a, b := 5, c[ J ], d[ ] := Va1;</code>
This is then equivalent to four separate declarations as follows
<code>
:[[Local]] a:=[[Null]];
:[[Local]] b:=5;
:[[Local]] c[ J ] := [[Null]];
:[[Local]] d[ ] := Va1;
</code>

==== Capture of multiple return values ====

Functions can now return multiple values, each with different dimensionality. This is covered below in [[#Multiple return values]]. These values can be captured by [[Local]] (or the other declaration constructs like [[For]], etc.) by placing the declared identifiers inside parentheses, as illustrated here:

:<code>[[Local]] (u,w,v) := [[SingularValueDecomp]]( a, I, J, J2 );</code>

where the function, [[SingularValueDecomp]] returns three matrices, each with a different dimensionality. With dimensional restrictions, this could also be declared as

:<code>[[Local]] (u[I,J], w[J,J2], v[J,J2]) := [[SingularValueDecomp]]( a, I, J, J2 );</code>

Note that [[SingularValueDecomp]] is called a single time, and returns three separate values. This function, as well as [[EigenDecomp]], behave differently when multiple return values are captured compared to when only the main value is used, which is done for backward compatibility with their legacy behavior. Previously, the returned a data structure with 3 [[references]] to the 3 matricies, which required some work to unpack. They illustrate that the capability to return multiple values isn't entirely new, but is far more convenient. These two functions are the only functions that change their behavior. For all other functions, when only the main value is used, the secondary return values are simply dropped (and are usually not computed in the first place). For example, in addition to reading the contents of a file, you can also capture the file name selected by the user using

:<code>[[Local]] ( txt, filename ) := [[ReadTextFile]]("");</code>

but you don't need to capture filename if you don't need it, and can simple use

:<code>[[Local]] txt := [[ReadTextFile]]("");</code>

==== Reduced keyword ====

As with previous releases, you can declare the indexes that the value named by a local identifier is allowed to have using brackets, such as
:<code>[[Local]] x[I, J, K] := Z;</code>
When declared in this fashion, and expressions you include in the body (i.e., the lexical scope of these local identifiers) can be treated as if it does not contain any indexes not listed. The new keyword "<code>reduced</code>" also restricts the dimensionality of a local variable, but in a somewhat different way. The same qualifier exists for [[Function parameter qualifiers|function parameter declarations]] and in fact works in exactly the same way here.

:<code>[[Local]] ( a[ ], b reduced ) := _( X, Y );</code>

Since <code>a</code> might need to be iterated over the indexes of <code>X</code>, <code>b</code> will have the indexes of <code>Y</code> that are not also indexes of <code>X</code>. In addition, the slice of X or Y named by a or b is coordinated. When a names <code>X[J=3]</code>, then <code>b</code> also names <code>Y[J=3]</code>. This leads to some convenient new iteration constructs. For example, you may have seen expressions such as this one:

<code>
:[[For]] n := @I Do (
::[[Local]] ii := I[@I=n]
::[[Local]] x_i := X[@I=n];
::…
</code>

the ensuing looped body code makes use of the index position (n), the index label (ii), and the array slice (x_i), and so it has to extract two of the items from the loop variable. This can now be condensed to a single looping structure,

<code>
:[[For]] (n[], ii[], x_i reduced) := _(@I, I, X) Do ( …
</code>
Note: In many cases, the word [[Local]] can be used in place of [[For]] here. Note that <code>n</code> names each position of <code>I</code>, <code>ii</code> names each label of <code>I</code>, and <code>x_i</code> names the slice of <code>X</code> corresponding to <code>[@I=n]</code>. This is similar to calling a function with <code>F(@I, I, X)</code> with has Parameters declared as
:Function F(n,i : [] ; x_i : reduced)

==== Iterating over repeated parameters (Local xi := repeated x Do) ====

==== Preservation of local name instead of local1, local2 ====

=== Multiple return values ===

Functions can now return multiple values, each with potentially different indexes, not just a single value or array, as previously. An expression calling the function can use only the first returned value, or it can use some or all of the vales. Several built-in functions have been enhanced to return additional information in the second and third return values.

==== Built-in functions that return multiple values ====

These built-in functions read information from a file and return its contents in one way or other in the main value. Each has now been enhanced to return the file name that was opened as a second parameter. Since in each case, a user might potentially select a file from a file selector dialog, you would otherwise not knowing which file was actually read. The primary return value is the same as in previous releases, the second return value is new.

* [[ReadTextFile]]: Returns ( file_contents, filename )
* [[SpreadsheetOpen]]: Returns ( workbook, filename )
* [[ReadExportFile]]: Returns ( array, filename )
* [[ReadBinaryFile]]: Returns (date, filename)
* [[ReadImageFile]]: Returns (image, filename)

TO DO: Look up -- do the Write functions return filenames?

The function [[SingularValueDecomp]] computes three matrices, each with a different dimensionality. Formerly, there were returned as a vector of 3 [[reference]]s. You would then usually unpack this, extracting the three items. With the ability for it to return three return values, the call is more convenient, namely:

:<code>(u, w, v) := [[SingularValueDecomp]]( a, I, J, J2)</code>

eliminating the ugly unpacking code. To ensure backward compatibility with code that used the 3-reference data structure, it is able to detect when you are capturing multiple return values and return the 3-reference structure when you are not.

A similar enhancement applies to the [[EigenDecomp]] function, which returns a vector of eigen values and 2-D matrix of eigen vectors. Formerly, these were bundled using a reference for the eigen vectors, but with multiple return values it is convenient to immediately separate these, e.g.,

:<code>(eigenVals, eigenVecs) := [[EigenDecomp]](a, I, J)</code>

[[EigenDecomp]] also retains its legacy behavior when you are not capturing multiple return values.

==== Capturing multiple return values ====
When a function returns multiple return values, you have to capture these values. There are two ways of doing this: In a local declaration, or via the assignment operator (:=).

:<code>[[Local]]( x, y, z ) := FuncWithMultiple( );</code>
or
:<code>(a, b, c) := FuncWithMultiple( );</code>

When assignment is used, each destination (a, b and c) can be anything that could appear on the left-hand side of an normal assignment operator. This includes local identifiers, global variables (in contexts where a side-effect is legal), a slice of a local variable, an attribute of an object, etc.

Although I'm showing the local declaration example using [[Local..Do]], you can also use other local declaration constructs in the same way, including [[For]] and [[LocalAlias]], or the legacy [[Var..Do]], [[Using..Do]], [[MetaVar..Do]], etc.

When you capture a return value that isn't actually returned by the function, it is equivalent to capturing null. For example:
:<code>( x,y ) := [[Sqrt]](5)</code>
sets <code>x</code> to 5 and <code>y</code> to null.

==== Returning multiple values from a UDF ====
To return multiple values from your own UDFs, simple return
:<code>[[MultiResult]]( v1, v2, v3, v4 )</code>
where <code>v1, v2, …</code> are the expressions whose result is to be returned. Be aware that any of these values that are not captured by the caller, the corresponding expression will not be evaluated. You can use that to your advantage by placing any time-consuming code not shared by v1 in the expression for v2, so that when the caller uses only v1, no wasted computation ensues.

There is a synonymous syntax, <code>_( v1, v2, v3, v4 )</code> that can be used. When returning values from a UDF, we feel that it clearer to call [[MultiResult]]. However, the underscore function is convenient when using a multiple assignment directly, such as

:<code>[[Local]] (key[], val[]) := _( dict.Key, dict );</code>

This example combines <code>_( ) </code> is combined with [[Repeated parameter forwarding]] to accomplish something that would have taken four lines of code otherwise.
:<code>[[Local]] (x,y,z) := _( ...[[ParseNumber]]( [[SplitText]]( "10, 20, 3", "," ) ) );</code>

==== Emergent iteration constructs ====

Some new convenient forms of iteration constructs emerge from the introduction of multiple return values. For example, when iterating over an index, you can simultaneously grab the index position and the index labels in the loop declaration.
<code>
:[[For]] ( pos, label ) := _( @J, J ) Do …
</code>

A 1-D array with an index containing labels is called as associative array in other programming languages. The index values are the keys and the array values are the values. Your iteration can conveniently name both the current key and the current value.
<code>
:[[For]] ( key[], val reduced ) := _( I, a ) Do …
</code>

=== Assignment ===
* (Definition of X := array) -- setting cell expressions
* new ParseExpression() function
* Capturing multiple values
=== Multithreading ===
Added finer-grained control over which multi-threaded algorithms are enabled or disabled. This is so that if you encounter a multi-threading-related problem with one particular algorithm, you can disable it without having to sacrifice all multi-threading.

* [[DisableMultithreaded]]: New system variable that contains the flags.
* [[SetEvaluationFlag]]('multithreaded'): Function for turning on or off only within one expression.

=== Experimental ===
You should not rely on experimental features while they are still experimental. They are subject to change or even cancellation in future releases, and are less thoroughly tested.

==== Sparse arrays ====
Analytica has long had support for a certain form of sparsity, which we call constant sparsity (or just const sparsity for short). When the values along a slice of an array don't vary (are constant), Analytica is often able to store the single value only, and also avoid an iteration during computations. However, many sparse arrays can't take advantage of const sparseness. We've been experimenting with fully sparse multi-dimensional arrays. With these, it is possible to have multidimensional cubes with large numbers of dimensions and immense numbers of distinct coordinates as long as the number of cell with actual data is relatively small. Such sparsity is often seen in [[MdTable]] relational-to-array transformations.

You can use the same Analytica operators and functions on sparse arrays as you would on any other Analytica arrays, but when possible, Analytica will attempt to use sparse algorithms to process the only values that are present and produce a sparse array, maintaining fast and low-memory computation. With this we have been able to demonstrate some real-life computations on sparse BI hypercubes that were not previously possible (and which are not realistically possible with a relational table representation).

Some operations produce non-sparse results, even when applied to sparse arrays. [[Cumulate]] applied to an array with a non-zero default value is one obvious example. This is a serious "gotcha", because if you are manipulating arrays with quadrillions of cells, one application of a function like that and you've just created a multi-petabyte array.

At present, only a subset of operations and functions that could have sparse-array-aware algorithms actually do; however, many of the ones that are present are the most common operations. But this incompleteness is one reason this is classified as an experimental feature.

In addition, the sparse algorithms are at this point quite new and not battle tested, so it not unlikely that bugs may be lurking, including bugs that might produce incorrect results. One of the reasons we are including it as an experimental feature is to promote testing of the algorithms.

===== Using sparse arrays =====
The use of sparse arrays is enabled by setting the system variable [[EnableSparse]] to 1. Or, you can enable the production of a sparse array from a specific expression by using <code>[[SetEvaluationFlag]]('sparse', true', «expr»)</code>.

[[MdTable]] is able to return a sparse array from a relational table, provided [[EnableSparse]] is set, or the sparse evaluation flag is on, or you set the optional «sparse» parameter to true. From there, the sparseness will propagate as you slice, add, and so on.

Expressions like <code>a = b</code> are often sparse, but will only return a sparse result when the evaluation context allows it. When these produce dense arrays, and those dense arrays are combined with sparse arrays, a lot of sparsity is often lost.

== Built-in functions ==
=== with Multiple return values ===
The following built-in functions now return multiple results: [[ReadTextFile]], [[ReadImageFile]], [[ReadBinaryFile]], [[SpreadsheetOpen]], [[ReadExportFile]], [[SingularValueDecomp]], [[EigenDecomp]].

See [[#Multiple return values]] above.

=== New optional parameters to existing functions ===
* Added an optional parameter named «initially» parameter to [[ComputedBy]]. This provides an initial value for the parent variable, and retains the value assigned by the called in the definition. (But only when the value is a simple atom). For example, if you want to remember what file a user selected, you could use:<code>
Variable filename := [[ComputedBy]](wb,"")

Variable wb :=
Local tmp;
(tmp,filename) := [[SpreadsheetOpen]](filename);
tmp</code>

* Added an optional Boolean parameter, «w1D» parameter to [[SingularValueDecomp]]. When false or omitted, it the resulting W is a square diagonal matrix. When set to true, the returned W is a vector (the diagonal).

* Added an optional «except» parameter to [[IndexesOf]], which accepts any number of index identifiers. For example, the following sums over every index of array A except for <code>I</code> and <code>J</code>.
:::<code>[[Sum]]( A, …[[IndexesOf]](A, except:I,J) )</code>

* Added a «first» parameter to [[ArgMin]], [[Argmax]], [[SubIndex]], and [[PositionInIndex]]. When omitted or false, in the event of a tie these return the ''last'' occurrence. When set to true, they return the position of the first occurrence of the tie.

::In addition, it was previously less obvious which tie was identified by [[ArgMin]] or [[Argmax]] in the multi-dimensional case. Now it is the first or last occurrence in the natural ordering of the supplied index parameters.

==== For sparse arrays ====
* Added an optional boolean parameter «sparse» to [[MdTable]]. Experimental. See [[#Sparse arrays]].
* The optional Boolean «sparseCount» parameter to [[Size]]. When true, counts the actual number of values (including default values) in the sparse array.

=== Analytic distribution functions ===
The analytic probability functions for all built-in distributions are now also built-in functions. For example, corresponding to the [[Triangular]] distribution function there are also the [[DensTriangular]], [[CumTriangular]] and [[CumTriangularInv]] functions. Previously, to use these functions you have to add the [[Distribution Densities Library]] to your model.

The general naming pattern for these functions is (where «dist» is the name of the distribution):
* <code>Dens«dist»</code>: The ''probability density function'' for a continuous distribution. Returns the density at «x».
* <code>Prob«dist»</code>: The ''discrete probability function'' for a discrete distribution. Returns the probability of «x».
* <code>Cum«dist»</code>: The cumulative probability function, also known as the ''probability function'' and ''cumulative density function''. Returns the probability of being less than or equal to «x».
*<code>Cum«dist»Inv</code>: The inverse cumulative probability function, also called the ''quantile function''. Returns the «p»th fractile/percentile/quartile.

A few of these analytic functions were already built in previously, but all of the following were added:
* [[DensBeta]], [[DensChiSquared]], [[DensCumDist]], [[DensExponential]], [[DensFDist]], [[DensGamma]], [[DensLogistic]], [[DensProbDist]], [[DensStudentT]], [[DensTriangular]], [[DensWeibull]].
* [[ProbBernoulli]], [[ProbBinomial]], [[ProbGeometric]], [[ProbHyperGeometric]], [[ProbNegativeBinomial]], [[ProbPoisson]], [[ProbUniform]]
* [[CumBernoulli]], [[CumBeta]], [[CumChiSquared]], [[CumCumDist]], [[CumExponential]], [[CumFDist]], [[CumGamma]], [[CumGeometric]], [[CumHyperGeometric]], [[CumLogistic]], [[CumNegativeBinomial]], [[CumProbDist]], [[CumStudentT]], [[CumTriangular]], [[CumUniform]], [[CumWeibull]].
* [[CumBernoulliInv]], [[CumBetaInv]], [[CumChiSquaredInv]], [[CumCumDistInv]], [[CumExponentialInv]], [[CumFDistInv]], [[CumGammaInv]], [[CumGeometricInv]], [[CumHyperGeometricInv]], [[CumLogisticInv]], [[CumNegativeBinomInv]], [[CumProbDistInv]], [[CumStudentTInv]], [[CumTriangularInv]], [[CumUniformInv]], [[CumWeibullInv]].

=== New built-in functions ===
* The preceding section covered the many newly built-in analytic distribution functions.

* The [[F-distribution]] was added as a built-in function (functions [[FDist]], [[DensFDist]], [[CumFDist]] and [[CumFDistInv]]).

* [[ParseExpression]]: Returns a parse tree for an Analytica expression. When this is assigned to a global variable, the edit table cells are Analytica expressions.

* [[MultiResult]](..) and [[MultiResult|_]](…) return multiple values. See [[#Returning multiple values from a UDF]].

* [[ChangeArraySparsity]]: (experimental) converts between a sparse and standard multi-dimensional array representation.

=== Enhancements to existing functions ===
* [[MakeJSON]] handles the encoding of multidimensional arrays better, with better control over nesting orders and ability to map some indexes to JSON objects and others to JSON arrays.
* Added the «expect» parameter to the [[IndexesOf]] function.
* Added the «first» parameter to [[SubIndex]], [[ArgMin]], [[ArgMax]], [[SubIndex]] and [[PositionInIndex]]
* [[CellOnClick]] allows local variables in expression and supplies several new local variables to the expression. See below.

== File saving and loading ==
* The save author and save date are no longer written as part of the model file. These were inconvenient when tracking a model in a source control system (like git or svn) because they changed every time, and collided every time when merges were required. When a model file is read that does not have the save date, the SaveDate attribute is now set to the file system's last-modified time stamp.

== Cell Formats ==
=== CellOnClick ===
* The «expr» inside a [[CellOnClick]] now has access to the coordinates of the cell that was clicked. From «expr», evaluating any of the index identifiers in a value context returns the coordinate of that index at the clicked cell.
* All the special local variables available in the [[Cell Format Expression]] attribute in general are now available inside «expr» when it is run, plus two more locals can be used:
** <code>TotalIndexes</code>: A list of handles containing all indexes that are being summed over for the clicked cell.
** <code>comparisonColumn</code>: When a cell is in a comparison variable column of a result table, this is the exogenous comparison variable or expression (i.e., it is either a [[handle]] or a parsed expression). If the click was not in a comparison column (the more normal case), this is null.
* Assignment can now occur directly from inside the «expr» of [[CellOnClick]]. Previously, you had to do it from a [[UDF]].
* When a cell contains a [[handle]] or [[reference]], the default behavior is to hyperlink when the user double clicks. But a [[CellOnClick]] handler overrides that. Now if the [[CellOnClick]] returns false (0), the default behavior will (also) execute.

== Clipboard ==
* Paste XML Spreadsheet format
** Copy/paste from Excel to Analytica or from Analytica to Excel is as faithful as possible to data types and what you see is what you get
** Copy/paste from one instance of Analytica to another instance is similarly faithful
** Paste special offers XML Spreadsheet format as the default option
** Paste special unlinked supports user choice of clipboard format used
** XML Spreadsheet format offers special support for row headers and column headers on copy/paste from Analytica to Analytica

== General GUI ==
* Several enhancements to the [[Indexes dialog]] make it easier to select indexes when the list is very long.
** The dialog is larger, so indexes more are visible in the panes.
** You can now view index identifiers by pressing Ctrl+Y
** You can type the first few characters to quickly jump to the index that starts with those characters.
** The Up, Down, Page Up, and Page Down keyboard can be used to scroll the index pane.
** The Left or Right keys can be used to move the selected index or indexes from one pane to the other (same as pressing the >> or << button).
** Use the mouse wheel to scroll the Indexes pane.
* More recent files recorded by default (was 6. Now 11).
* Added the '''Remove quotes''' option for lists
* Added the '''Remove quotes''' and '''Add quotes''' dropdown menu options for description and definition fields in object windows
** These operations support undo and redo
** These operations are performed in the selected area in these input windows only
** '''Add quotes''' is useful for the definition field when a paste operation puts data there that is meant to be a string but does not initially have quotes, escaping internal quotes as part of the operation
* '''Comparison Tolerance''' appears on the Definition menu.
* Undo for
** Uncertainty options... changes
* The preferred declaration constructs (e.g., Local..Do) appear on Definition menu, and not deprecated ones (e.g., Var..Do).
* When you exceed the number of characters allowed in the identifier or units field, it now displays the error in a bubble instead of a primitive model alert dialog.
::[[image:too_many_characters_bubble.png]]

== Optimizer ==
* The add-on OptQuest engine is now available from Analytica 64-bit. Previously this engine was only available in 32-bits.

== Wiki ==
* Some pages of the wiki have a release bar at the top and display different content depending on which release number is selected. The release bar looks like this:
*::{{ReleaseBar}}
*:Links from Analytica into the wiki now include the release number in the URL, so that the Wiki can automatically select the same release number that you are using. Since this is new to 5.2, release 4.6, 5.0 or 5.1 won't auto-select the release, but it will enable future releases to show the correct version-specific pages.

== ADE ==
* Changed the [[CATable::GraphWithStoredPivot]] property to default to true.
* Method for installation of ADE without running installer. Used to create a docker container image.

== Licensing ==
* Fixed a bug where RLM Server name didn't stick in licensing dialog. This caused problems for users of floating licenses and required them to manually set a registry setting to get around it.
* Changed beta-build licensing. Formerly a separate beta testing license was required. Now any active subscription license (i.e., expiring 5.x license) is sufficient. Thus, we eliminated lots of complex code for automatically acquiring and updating beta test licenses during the beta testing period.

== Typescript ==
* The Up and Down arrow keys recall history, like Ctrl+Up and Ctrl+Down already do.

What's new in Analytica 5.2?

2018-12-21T18:17:00Z

Ldavidson: Added sub-bullets about XML Spreadsheet clipboard format

The current release is [[Analytica 5.1]]. Analytica 5.2 is currently under development -- and so is this page.

These are improvements in Analytica and ADE release 5.2. (As usual, we don't list bug fixes except the most notable cases.)

== Graphing ==
Graphs have some new interactive manual scaling and a new polygon fill feature, as described below.

=== Interactive zooming ===
* Drag the mouse horizontally to zoom to a manually-scaled x-axis interval:
::[[image:graph_zoom_horiz.png]] → [[image:graph_zoom_horiz_after.png]]
::Transparent blue selection rectangle appears while dragging. After drag, Y is still autoscaled, but now to the data in the selected range.
* Drag the mouse diagonally to zoom to manually-scaled intervals on both axes:
::[[image:graph_zoom_diag.png]] → [[image:graph_zoom_diag_after.png]]
* When you move the mouse over a zoomed graph, autoscale hover icon buttons appear. Click on one to auto-scale that axis.
::[[image:graph_zoom_autoscale.png]] → [[image:graph_zoom_autoscaley_after.png]]
::Clicked on the vertical axis autoscale hover icon. Horizontal axis is still manually scaled.
* Drag vertically to zoom to a manually-scaled y-axis interval.
::[[image:graph_zoom_vert.png]] → [[image:graph_zoom_vert_after.png]]
* Zooming has the same effect as changing the manual scale range in Graph Setup. In fact, it records your selected end points there.
::[[image:graph_zoom_graphsetup_after.png]]

=== Key item visibility states ===
[[Analytica 5.1]] introduced a feature to toggle the visibility of individual curves on a graph by clicking on its corresponding key item. Analytica 5.2 includes some further enhancement to this popular feature.

==== Turn on all, Turn off all ====
Right-click on a graph key and you'll see the options '''Turn on all key items''' and '''Turn off all key items'''. These can save you many clicks when there are a lot of key items and you want to turn almost all of them off.

==== Toggle line, symbol visibility ====

::[[image:Line and point graph.png]]
In the preceding graph, the points in a data set appear as symbols without any lines connecting them, and a best-fit line appears appears on the same graph without symbols. This is done by starting with a Line+Symbol plot style, like this:
:[[image:How to line and point graph.png]]
Notice that in the starting line+symbol plot, each key item has a line and a symbol. When you click on one of them multiple times in a row, the key item toggles from line+symbol → off → line-only → symbol-only → line+symbol. So with just a few clicks on the key items, you get to the line only and symbols only series on the same plot.

When you have multiple keys, with the line, symbol or symbol size each depicting different information, each key toggles through three states: On → Off → Partial → On. In the full off state, the data is fully hidden -- so if you hide a line, the symbols for that curve are also hidden, or if you hide a symbol, the line segments to and from that symbol hide. When a item in a line key is partial, the curve's line isn't shown, but its symbols continue to show. When an item in a symbol key is partial, the line to that datum remains, but the symbol does not appear.

::[[image:graph_key_symbol_partial.png]]

In the above graph, the 2 points corresponding to '''Least''' would appear at x=2 in the fully-on graph, but fit_err=Least is been clicked once, putting it into the off state. As a result, there is a gap in the lines at x=2. In the symbol size key (x cat), the x_cat=8 item is in the partial state. The points corresponding to x_cat=8 appear at x=8. In this case the lines pass through the points, but the symbols are hidden.

When fit_graph=y in the line key is off, all the red "ink" on the graph disappears. But when it is in the partial state, the line disappears but the symbols continue to show, as illustrated here:
::[[image:graph_key_line_partial.png]]

==== Save visibility states ====
Changes to key item visibility reset by default when you close and re-open a graph anew. If you want your current visibility state to be saved as the starting point next time the graph is opened, select '''Save key item visibilities''' from the right-mouse menu.

=== Polygon fill plots ===
When you plot a curve in an X-Y plot, there is now a polygon fill option that fills the interior of the polygon(s). For example, starting with this data, already plotted as Latitude vs Longitude
::[[image:California_unfilled_plot.png]]
you can use the new Polygon fill type (the Fill type option is new).
::[[image:Graph_setup_polygon_filltype.png]]
The difference between alternate and solid arises when a curve crosses itself. In this example with a state outline, that doesn't happen so they are equivalent. Polygon fill closes each curve segment (null data starts a new segment) and fills the interior.
::[[image:California_filled_plot.png]]
and viola!
::[[image:Red state blue state.png]]

=== Other graphing ===

* Bug fix impacting marginal abatement graphs
* Changing symbol size role less likely to swap other roles, less confusing

== Expression language & Engine ==

=== Declaring local identifiers ===

==== Omission of initial value====

When declaring a local, you can now omit its initial value, so that
:<code>[[Local]] x;</code>
is equivalent to
:<code>[[Local]] x := Null</code>;

==== Multiple locals in one declaration ====

You can declare multiple local identifiers in the same Local declaration. For example,
:<code>Local a, b := 5, c[ J ], d[ ] := Va1;</code>
This is then equivalent to four separate declarations as follows
<code>
:[[Local]] a:=[[Null]];
:[[Local]] b:=5;
:[[Local]] c[ J ] := [[Null]];
:[[Local]] d[ ] := Va1;
</code>

==== Capture of multiple return values ====

Functions can now return multiple values, each with different dimensionality. This is covered below in [[#Multiple return values]]. These values can be captured by [[Local]] (or the other declaration constructs like [[For]], etc.) by placing the declared identifiers inside parentheses, as illustrated here:

:<code>[[Local]] (u,w,v) := [[SingularValueDecomp]]( a, I, J, J2 );</code>

where the function, [[SingularValueDecomp]] returns three matrices, each with a different dimensionality. With dimensional restrictions, this could also be declared as

:<code>[[Local]] (u[I,J], w[J,J2], v[J,J2]) := [[SingularValueDecomp]]( a, I, J, J2 );</code>

Note that [[SingularValueDecomp]] is called a single time, and returns three separate values. This function, as well as [[EigenDecomp]], behave differently when multiple return values are captured compared to when only the main value is used, which is done for backward compatibility with their legacy behavior. Previously, the returned a data structure with 3 [[references]] to the 3 matricies, which required some work to unpack. They illustrate that the capability to return multiple values isn't entirely new, but is far more convenient. These two functions are the only functions that change their behavior. For all other functions, when only the main value is used, the secondary return values are simply dropped (and are usually not computed in the first place). For example, in addition to reading the contents of a file, you can also capture the file name selected by the user using

:<code>[[Local]] ( txt, filename ) := [[ReadTextFile]]("");</code>

but you don't need to capture filename if you don't need it, and can simple use

:<code>[[Local]] txt := [[ReadTextFile]]("");</code>

==== Reduced keyword ====

As with previous releases, you can declare the indexes that the value named by a local identifier is allowed to have using brackets, such as
:<code>[[Local]] x[I, J, K] := Z;</code>
When declared in this fashion, and expressions you include in the body (i.e., the lexical scope of these local identifiers) can be treated as if it does not contain any indexes not listed. The new keyword "<code>reduced</code>" also restricts the dimensionality of a local variable, but in a somewhat different way. The same qualifier exists for [[Function parameter qualifiers|function parameter declarations]] and in fact works in exactly the same way here.

:<code>[[Local]] ( a[ ], b reduced ) := _( X, Y );</code>

Since <code>a</code> might need to be iterated over the indexes of <code>X</code>, <code>b</code> will have the indexes of <code>Y</code> that are not also indexes of <code>X</code>. In addition, the slice of X or Y named by a or b is coordinated. When a names <code>X[J=3]</code>, then <code>b</code> also names <code>Y[J=3]</code>. This leads to some convenient new iteration constructs. For example, you may have seen expressions such as this one:

<code>
:[[For]] n := @I Do (
::[[Local]] ii := I[@I=n]
::[[Local]] x_i := X[@I=n];
::…
</code>

the ensuing looped body code makes use of the index position (n), the index label (ii), and the array slice (x_i), and so it has to extract two of the items from the loop variable. This can now be condensed to a single looping structure,

<code>
:[[For]] (n[], ii[], x_i reduced) := _(@I, I, X) Do ( …
</code>
Note: In many cases, the word [[Local]] can be used in place of [[For]] here. Note that <code>n</code> names each position of <code>I</code>, <code>ii</code> names each label of <code>I</code>, and <code>x_i</code> names the slice of <code>X</code> corresponding to <code>[@I=n]</code>. This is similar to calling a function with <code>F(@I, I, X)</code> with has Parameters declared as
:Function F(n,i : [] ; x_i : reduced)

==== Iterating over repeated parameters (Local xi := repeated x Do) ====

==== Preservation of local name instead of local1, local2 ====

=== Multiple return values ===

Functions can now return multiple values, each with potentially different indexes, not just a single value or array, as previously. An expression calling the function can use only the first returned value, or it can use some or all of the vales. Several built-in functions have been enhanced to return additional information in the second and third return values.

==== Built-in functions that return multiple values ====

These built-in functions read information from a file and return its contents in one way or other in the main value. Each has now been enhanced to return the file name that was opened as a second parameter. Since in each case, a user might potentially select a file from a file selector dialog, you would otherwise not knowing which file was actually read. The primary return value is the same as in previous releases, the second return value is new.

* [[ReadTextFile]]: Returns ( file_contents, filename )
* [[SpreadsheetOpen]]: Returns ( workbook, filename )
* [[ReadExportFile]]: Returns ( array, filename )
* [[ReadBinaryFile]]: Returns (date, filename)
* [[ReadImageFile]]: Returns (image, filename)

TO DO: Look up -- do the Write functions return filenames?

The function [[SingularValueDecomp]] computes three matrices, each with a different dimensionality. Formerly, there were returned as a vector of 3 [[reference]]s. You would then usually unpack this, extracting the three items. With the ability for it to return three return values, the call is more convenient, namely:

:<code>(u, w, v) := [[SingularValueDecomp]]( a, I, J, J2)</code>

eliminating the ugly unpacking code. To ensure backward compatibility with code that used the 3-reference data structure, it is able to detect when you are capturing multiple return values and return the 3-reference structure when you are not.

A similar enhancement applies to the [[EigenDecomp]] function, which returns a vector of eigen values and 2-D matrix of eigen vectors. Formerly, these were bundled using a reference for the eigen vectors, but with multiple return values it is convenient to immediately separate these, e.g.,

:<code>(eigenVals, eigenVecs) := [[EigenDecomp]](a, I, J)</code>

[[EigenDecomp]] also retains its legacy behavior when you are not capturing multiple return values.

==== Capturing multiple return values ====
When a function returns multiple return values, you have to capture these values. There are two ways of doing this: In a local declaration, or via the assignment operator (:=).

:<code>[[Local]]( x, y, z ) := FuncWithMultiple( );</code>
or
:<code>(a, b, c) := FuncWithMultiple( );</code>

When assignment is used, each destination (a, b and c) can be anything that could appear on the left-hand side of an normal assignment operator. This includes local identifiers, global variables (in contexts where a side-effect is legal), a slice of a local variable, an attribute of an object, etc.

Although I'm showing the local declaration example using [[Local..Do]], you can also use other local declaration constructs in the same way, including [[For]] and [[LocalAlias]], or the legacy [[Var..Do]], [[Using..Do]], [[MetaVar..Do]], etc.

When you capture a return value that isn't actually returned by the function, it is equivalent to capturing null. For example:
:<code>( x,y ) := [[Sqrt]](5)</code>
sets <code>x</code> to 5 and <code>y</code> to null.

==== Returning multiple values from a UDF ====
To return multiple values from your own UDFs, simple return
:<code>[[MultiResult]]( v1, v2, v3, v4 )</code>
where <code>v1, v2, …</code> are the expressions whose result is to be returned. Be aware that any of these values that are not captured by the caller, the corresponding expression will not be evaluated. You can use that to your advantage by placing any time-consuming code not shared by v1 in the expression for v2, so that when the caller uses only v1, no wasted computation ensues.

There is a synonymous syntax, <code>_( v1, v2, v3, v4 )</code> that can be used. When returning values from a UDF, we feel that it clearer to call [[MultiResult]]. However, the underscore function is convenient when using a multiple assignment directly, such as

:<code>[[Local]] (key[], val[]) := _( dict.Key, dict );</code>

This example combines <code>_( ) </code> is combined with [[Repeated parameter forwarding]] to accomplish something that would have taken four lines of code otherwise.
:<code>[[Local]] (x,y,z) := _( ...[[ParseNumber]]( [[SplitText]]( "10, 20, 3", "," ) ) );</code>

==== Emergent iteration constructs ====

Some new convenient forms of iteration constructs emerge from the introduction of multiple return values. For example, when iterating over an index, you can simultaneously grab the index position and the index labels in the loop declaration.
<code>
:[[For]] ( pos, label ) := _( @J, J ) Do …
</code>

A 1-D array with an index containing labels is called as associative array in other programming languages. The index values are the keys and the array values are the values. Your iteration can conveniently name both the current key and the current value.
<code>
:[[For]] ( key[], val reduced ) := _( I, a ) Do …
</code>

=== Assignment ===
* (Definition of X := array) -- setting cell expressions
* new ParseExpression() function
* Capturing multiple values
=== Multithreading ===
Added finer-grained control over which multi-threaded algorithms are enabled or disabled. This is so that if you encounter a multi-threading-related problem with one particular algorithm, you can disable it without having to sacrifice all multi-threading.

* [[DisableMultithreaded]]: New system variable that contains the flags.
* [[SetEvaluationFlag]]('multithreaded'): Function for turning on or off only within one expression.

=== Experimental ===
You should not rely on experimental features while they are still experimental. They are subject to change or even cancellation in future releases, and are less thoroughly tested.

==== Sparse arrays ====
Analytica has long had support for a certain form of sparsity, which we call constant sparsity (or just const sparsity for short). When the values along a slice of an array don't vary (are constant), Analytica is often able to store the single value only, and also avoid an iteration during computations. However, many sparse arrays can't take advantage of const sparseness. We've been experimenting with fully sparse multi-dimensional arrays. With these, it is possible to have multidimensional cubes with large numbers of dimensions and immense numbers of distinct coordinates as long as the number of cell with actual data is relatively small. Such sparsity is often seen in [[MdTable]] relational-to-array transformations.

You can use the same Analytica operators and functions on sparse arrays as you would on any other Analytica arrays, but when possible, Analytica will attempt to use sparse algorithms to process the only values that are present and produce a sparse array, maintaining fast and low-memory computation. With this we have been able to demonstrate some real-life computations on sparse BI hypercubes that were not previously possible (and which are not realistically possible with a relational table representation).

Some operations produce non-sparse results, even when applied to sparse arrays. [[Cumulate]] applied to an array with a non-zero default value is one obvious example. This is a serious "gotcha", because if you are manipulating arrays with quadrillions of cells, one application of a function like that and you've just created a multi-petabyte array.

At present, only a subset of operations and functions that could have sparse-array-aware algorithms actually do; however, many of the ones that are present are the most common operations. But this incompleteness is one reason this is classified as an experimental feature.

In addition, the sparse algorithms are at this point quite new and not battle tested, so it not unlikely that bugs may be lurking, including bugs that might produce incorrect results. One of the reasons we are including it as an experimental feature is to promote testing of the algorithms.

===== Using sparse arrays =====
The use of sparse arrays is enabled by setting the system variable [[EnableSparse]] to 1. Or, you can enable the production of a sparse array from a specific expression by using <code>[[SetEvaluationFlag]]('sparse', true', «expr»)</code>.

[[MdTable]] is able to return a sparse array from a relational table, provided [[EnableSparse]] is set, or the sparse evaluation flag is on, or you set the optional «sparse» parameter to true. From there, the sparseness will propagate as you slice, add, and so on.

Expressions like <code>a = b</code> are often sparse, but will only return a sparse result when the evaluation context allows it. When these produce dense arrays, and those dense arrays are combined with sparse arrays, a lot of sparsity is often lost.

== Built-in functions ==
=== with Multiple return values ===
The following built-in functions now return multiple results: [[ReadTextFile]], [[ReadImageFile]], [[ReadBinaryFile]], [[SpreadsheetOpen]], [[ReadExportFile]], [[SingularValueDecomp]], [[EigenDecomp]].

See [[#Multiple return values]] above.

=== New optional parameters to existing functions ===
* Added an optional parameter named «initially» parameter to [[ComputedBy]]. This provides an initial value for the parent variable, and retains the value assigned by the called in the definition. (But only when the value is a simple atom). For example, if you want to remember what file a user selected, you could use:<code>
Variable filename := [[ComputedBy]](wb,"")

Variable wb :=
Local tmp;
(tmp,filename) := [[SpreadsheetOpen]](filename);
tmp</code>

* Added an optional Boolean parameter, «w1D» parameter to [[SingularValueDecomp]]. When false or omitted, it the resulting W is a square diagonal matrix. When set to true, the returned W is a vector (the diagonal).

* Added an optional «except» parameter to [[IndexesOf]], which accepts any number of index identifiers. For example, the following sums over every index of array A except for <code>I</code> and <code>J</code>.
:::<code>[[Sum]]( A, …[[IndexesOf]](A, except:I,J) )</code>

* Added a «first» parameter to [[ArgMin]], [[Argmax]], [[SubIndex]], and [[PositionInIndex]]. When omitted or false, in the event of a tie these return the ''last'' occurrence. When set to true, they return the position of the first occurrence of the tie.

::In addition, it was previously less obvious which tie was identified by [[ArgMin]] or [[Argmax]] in the multi-dimensional case. Now it is the first or last occurrence in the natural ordering of the supplied index parameters.

==== For sparse arrays ====
* Added an optional boolean parameter «sparse» to [[MdTable]]. Experimental. See [[#Sparse arrays]].
* The optional Boolean «sparseCount» parameter to [[Size]]. When true, counts the actual number of values (including default values) in the sparse array.

=== Analytic distribution functions ===
The analytic probability functions for all built-in distributions are now also built-in functions. For example, corresponding to the [[Triangular]] distribution function there are also the [[DensTriangular]], [[CumTriangular]] and [[CumTriangularInv]] functions. Previously, to use these functions you have to add the [[Distribution Densities Library]] to your model.

The general naming pattern for these functions is (where «dist» is the name of the distribution):
* <code>Dens«dist»</code>: The ''probability density function'' for a continuous distribution. Returns the density at «x».
* <code>Prob«dist»</code>: The ''discrete probability function'' for a discrete distribution. Returns the probability of «x».
* <code>Cum«dist»</code>: The cumulative probability function, also known as the ''probability function'' and ''cumulative density function''. Returns the probability of being less than or equal to «x».
*<code>Cum«dist»Inv</code>: The inverse cumulative probability function, also called the ''quantile function''. Returns the «p»th fractile/percentile/quartile.

A few of these analytic functions were already built in previously, but all of the following were added:
* [[DensBeta]], [[DensChiSquared]], [[DensCumDist]], [[DensExponential]], [[DensFDist]], [[DensGamma]], [[DensLogistic]], [[DensProbDist]], [[DensStudentT]], [[DensTriangular]], [[DensWeibull]].
* [[ProbBernoulli]], [[ProbBinomial]], [[ProbGeometric]], [[ProbHyperGeometric]], [[ProbNegativeBinomial]], [[ProbPoisson]], [[ProbUniform]]
* [[CumBernoulli]], [[CumBeta]], [[CumChiSquared]], [[CumCumDist]], [[CumExponential]], [[CumFDist]], [[CumGamma]], [[CumGeometric]], [[CumHyperGeometric]], [[CumLogistic]], [[CumNegativeBinomial]], [[CumProbDist]], [[CumStudentT]], [[CumTriangular]], [[CumUniform]], [[CumWeibull]].
* [[CumBernoulliInv]], [[CumBetaInv]], [[CumChiSquaredInv]], [[CumCumDistInv]], [[CumExponentialInv]], [[CumFDistInv]], [[CumGammaInv]], [[CumGeometricInv]], [[CumHyperGeometricInv]], [[CumLogisticInv]], [[CumNegativeBinomInv]], [[CumProbDistInv]], [[CumStudentTInv]], [[CumTriangularInv]], [[CumUniformInv]], [[CumWeibullInv]].

=== New built-in functions ===
* The preceding section covered the many newly built-in analytic distribution functions.

* The [[F-distribution]] was added as a built-in function (functions [[FDist]], [[DensFDist]], [[CumFDist]] and [[CumFDistInv]]).

* [[ParseExpression]]: Returns a parse tree for an Analytica expression. When this is assigned to a global variable, the edit table cells are Analytica expressions.

* [[MultiResult]](..) and [[MultiResult|_]](…) return multiple values. See [[#Returning multiple values from a UDF]].

* [[ChangeArraySparsity]]: (experimental) converts between a sparse and standard multi-dimensional array representation.

=== Enhancements to existing functions ===
* [[MakeJSON]] handles the encoding of multidimensional arrays better, with better control over nesting orders and ability to map some indexes to JSON objects and others to JSON arrays.
* Added the «expect» parameter to the [[IndexesOf]] function.
* Added the «first» parameter to [[SubIndex]], [[ArgMin]], [[ArgMax]], [[SubIndex]] and [[PositionInIndex]]
* [[CellOnClick]] allows local variables in expression and supplies several new local variables to the expression. See below.

== File saving and loading ==
* The save author and save date are no longer written as part of the model file. These were inconvenient when tracking a model in a source control system (like git or svn) because they changed every time, and collided every time when merges were required. When a model file is read that does not have the save date, the SaveDate attribute is now set to the file system's last-modified time stamp.

== Cell Formats ==
=== CellOnClick ===
* The «expr» inside a [[CellOnClick]] now has access to the coordinates of the cell that was clicked. From «expr», evaluating any of the index identifiers in a value context returns the coordinate of that index at the clicked cell.
* All the special local variables available in the [[Cell Format Expression]] attribute in general are now available inside «expr» when it is run, plus two more locals can be used:
** <code>TotalIndexes</code>: A list of handles containing all indexes that are being summed over for the clicked cell.
** <code>comparisonColumn</code>: When a cell is in a comparison variable column of a result table, this is the exogenous comparison variable or expression (i.e., it is either a [[handle]] or a parsed expression). If the click was not in a comparison column (the more normal case), this is null.
* Assignment can now occur directly from inside the «expr» of [[CellOnClick]]. Previously, you had to do it from a [[UDF]].
* When a cell contains a [[handle]] or [[reference]], the default behavior is to hyperlink when the user double clicks. But a [[CellOnClick]] handler overrides that. Now if the [[CellOnClick]] returns false (0), the default behavior will (also) execute.

== Clipboard ==
* Paste XML Spreadsheet format
** Copy/paste from Excel to Analytica or from Analytica to Excel is as faithful as possible to data types and what you see is what you get
** Copy/paste from one instance of Analytica to another instance is similarly faithful
** Paste special offers XML Spreadsheet format as the default option
** Paste special unlinked supports user choice of clipboard format used
** XML Spreadsheet format offers special support for row headers and column headers on copy/paste from Analytica to Analytica

== General GUI ==
* Several enhancements to the [[Indexes dialog]] make it easier to select indexes when the list is very long.
** The dialog is larger, so indexes more are visible in the panes.
** You can now view index identifiers by pressing Ctrl+Y
** You can type the first few characters to quickly jump to the index that starts with those characters.
** The Up, Down, Page Up, and Page Down keyboard can be used to scroll the index pane.
** The Left or Right keys can be used to move the selected index or indexes from one pane to the other (same as pressing the >> or << button).
** Use the mouse wheel to scroll the Indexes pane.
* More recent files recorded by default (was 6. Now 11).
* Added the '''Remove quotes''' option for lists
* '''Comparison Tolerance''' appears on the Definition menu.
* Undo for
** Uncertainty options... changes
* The preferred declaration constructs (e.g., Local..Do) appear on Definition menu, and not deprecated ones (e.g., Var..Do).
* When you exceed the number of characters allowed in the identifier or units field, it now displays the error in a bubble instead of a primitive model alert dialog.
::[[image:too_many_characters_bubble.png]]

== Optimizer ==
* The add-on OptQuest engine is now available from Analytica 64-bit. Previously this engine was only available in 32-bits.

== Wiki ==
* Some pages of the wiki have a release bar at the top and display different content depending on which release number is selected. The release bar looks like this:
*::{{ReleaseBar}}
*:Links from Analytica into the wiki now include the release number in the URL, so that the Wiki can automatically select the same release number that you are using. Since this is new to 5.2, release 4.6, 5.0 or 5.1 won't auto-select the release, but it will enable future releases to show the correct version-specific pages.

== ADE ==
* Changed the [[CATable::GraphWithStoredPivot]] property to default to true.
* Method for installation of ADE without running installer. Used to create a docker container image.

== Licensing ==
* Fixed a bug where RLM Server name didn't stick in licensing dialog. This caused problems for users of floating licenses and required them to manually set a registry setting to get around it.
* Changed beta-build licensing. Formerly a separate beta testing license was required. Now any active subscription license (i.e., expiring 5.x license) is sufficient. Thus, we eliminated lots of complex code for automatically acquiring and updating beta test licenses during the beta testing period.

== Typescript ==
* The Up and Down arrow keys recall history, like Ctrl+Up and Ctrl+Down already do.