Analytica Docs - User contributions [en]

Read data from URL on internet

2026-07-02T22:15:18Z

Lchrisman: /* See Also */

[[Category:Analytica User Guide]]
<breadcrumbs>Analytica User Guide > Integration with data and applications > {{PAGENAME}}</breadcrumbs><br />

The [[ReadFromUrl]] function, on the Database menu, reads text from URL sources, such as HTTP web pages or FTP sites.

''This feature is available in {{Analytica Developer}} and [[Optimizer]].''

==ReadFromUrl(url, ''method, formValues, formFields, formIndex'')==

[[ReadFromUrl]] reads text or images from a URL (Universal Resource Locator) location on the web. In most cases, ypu can call it with a single parameter -- the URL. When reading from a web page, the «url» should begin with <nowiki>'http://....'</nowiki>. When reading a text file from an FTP site, it should begin with <nowiki>'ftp://...'</nowiki>. It returns the entire text as a text value. In most cases, you will need to write Analytica expressions to parse the data. When the URL is an http request that points to an image (*.jpg, *.png, *.gif, etc), it returns a picture object, which you can assign to the Pict attribute of objects, or into an array. With the exception of http requests to known image types, the source data must be textual, and if not, the resulting data will be garbled.

Some web pages and most FTP sites require user and password authentication to access. To authenticate, embed the user name and password in the URL, like this:

:<code>ReadFromUrl(<nowiki>'http://user:password@www.site.com/dir/page.htm'</nowiki>)</code>
:<code>ReadFromUrl(<nowiki>'ftp://user:password@site.com/directory/file.txt'</nowiki>)</code>

The optional second through fourth parameters are used to submit data to web forms. There are two methods used to submit data to HTTP web forms: <code>method: 'POST'</code>or <code>method: 'GET'</code>. The field names and the values submitted for those fields are specified in «formValues» and «formFields», which must share a common index, and if that common index is anything other than «formFields», it should be specified in the «formIndex» parameter.

== See Also ==
* [[ReadFromUrl]]
* [[OAuth2Authorize]]
* [[OpenURL]]
* [[Links or URL in model attributes]]
* [[Retrieving Content From the Web]]
* [[Excel spreadsheets read and write]]
* [[Read and write text files]]

<footer>Excel spreadsheets read and write / {{PAGENAME}} / Import and Export data</footer>

What's new in Analytica 7.1?

2026-06-29T22:39:15Z

Lchrisman: /* Assista */

Analytica release 7.1 is currently in early [[Beta Tester Page|Beta Testing]]. If have have a paid desktop Analytica subscription, we encourage you to try it out from the [[Beta Tester Page]].

== Highlights of Analytica 7.1 ==
[[File:Assista What kinds of things can you do.png|alt=Assista dialog screen answering "What kinds of things can you do?"|thumb|441x441px]]
'''[[#Assista|Assista]]:''' By far the most important visible improvement is in [[#Assista|Assista]], Analytica's A.I. assistant. When first released in Analytica 6.5, Assista was already quite useful for explaining Analytica features, describing and documenting models, and building models, but it was a bit unreliable in Analytica syntax and arranging influence diagrams. We think you will find that the latest Assista is so much improved, including writing Analytica Definitions and drawing influence diagrams. You may start to use chatting with Assista as the primary way you interact with Analytica.

Other improvements include faster response time, better look and feel, a trace of its thinking, the ability to save and use conversations from previous sessions, ingesting files to provide information, including txt, pdf, csv, xlsx; understanding images and diagrams; a set of skills that you can extend and customize, and more.

'''[[#Engine|Performance]]:''' Large models start up much faster using multiple processes to parse the definitions. Arrays now use a ''tensor'' representation, similar to AI frameworks like PyTorch and TensorFlow, but with Index labels that support "Intelligent Arrays". This internal improvement isn't noticeable to users -- but enables major future performance improvements.

'''[[#Spreadsheets|CSV and spreadsheet files]] :''' You can now import [[#CSV files|CSV files]] simply by dragging them into an diagram or in a command line when you start Analytica. You can create a new [[#spreadsheets |spreadsheet]] with and add or remove sheets from it.

'''[[#Spanish|Spanish]]:''' The user interface now supports Spanish -- with other languages in the future. Assista already supports most languages, and explains features (translating docs) in your language.

== Assista ==
[[Assista]] is Analytica's A.I. assistant. She is greatly improved in this release.
* Her UI is now a top-level window that resides at the same level as Analytica's main application window.
** You can move her chat window to a non-overlapping location or even a different monitor (to maximize screen real estate used by your Analytica window).
** Selected objects remain visually selected in the main window when you type into Assista.
* Her chat has a different look-and-feel.
* Her chat window is faster and more responsive
* You can drag-highlight any text in her chat and copy to paste elsewhere.
* The UI has improved formatting capabilities for displaying Assista's response.
* Her "thoughts" display as she is processing your prompt, making it clear she is working and even giving you a peek into how she is solving it.
* She has a new processing pipeline on the backend, enabling her to respond faster but also work longer on harder tasks.
* She has an extended set of competencies (skills).
* Your sessions are automatically saved, keyed to your model, and you can resume a previous session for that model from a session selector dropdown in the UI.
* You can create and expose [[Assista_-_Analytica_AI_Assistant/Custom_user_skills_for_Assista|your own custom skills]] to expand her capabilities, or ask her to do it for you.
* You can add or drag-and-drop a document (<code>*.txt, *.pdf, *.md, *.docx, *.xlsx, *.xlsm</code>) or URLs into the chat which Assista can "ingest" during your conversation. Have her extract data from the doc, adding tables to your model. Or even to implement a model described by the paper or translate a spreadsheet into an Analytica model.
* You can add, drag-and-drop or paste an image into the chat, which she can see while processing your question. For example, she can extract data from the image.
* Assista can "see" images in your model -- pictures in nodes, images in table cells, and diagram or graph screenshots.
* She is language-aware. If you are using Analytica is Spanish, she'll provide UI instructions that refer to the Spanish-language UI elements.
* She is aware of her reasoning in previous conversation turns and the actions she took, enabling her to explain her reasoning or build on ideas she thought about but might not have included in the final response.
* She has an improved ability to navigate and find objects within your (large) models.
* You can personalize her tone, style, level of verbosity and provide her custom instructions. To do this, click on the icon in the top-left corner of the Assista window and select Personization...
* You can have Assista generate a report as a downloadable PDF or Word document, which can contain graphs or other images from your model and formatted equations.

== Multi-linguality: Spanish UI ==
Analytica now comes with a Spanish-language UI, in which its menus, dialogs, error messages and built-in function descriptions are all in Spanish. Also its installer runs with a Spanish-language UI when you are in a Spanish-language region. Spanish is the default when you are in a Spanish-language region.

You can override the default language by launching Analytica as:
* <code>Analytica.exe /lang:es</code>
*: or
* <code>Analytica.exe /lang:en</code>

You can also set the <code>Language</code> registry setting in the <code>"HKCU/Software/Lumina Decision Systems/Analytica"</code> hive to REG_SZ <code>"en"</code> on <code>"es"</code> for your default if different from your windows region setting.

Some of you may ask "what about my language?". Stay tuned (and let us know there is a demand for your language). Once our AI translation pipeline is solid, it shouldn't be too hard for us to add more.

== Window appearance ==
The appearance of the chrome around child MDI windows (aka the "non-client area") has been changed to more closely match the Windows 11 style of windows -- i.e., thin (1 pixel) borders, rounded corners at the top, white title bar, very plain (text-like) button images in the toolbar.

== CSV files ==
There are now a few additional ways to open CSV files in Analytica:
* On the command line: <code>Analytica.exe MyData.csv</code>
* Drag and drop a *.csv file onto the diagram (which behaves the same as using <code>File / Import...</code> on the *.csv file).

== Spreadsheets ==
* <code>[[SpreadsheetOpen]]("new")</code> now creates a blank spreadsheet in memory. Works with both the Excel and LibXl backends.
* Prefacing a sheet name with + in the call to [[SpreadsheetSetCell]] or [[SpreadsheetSetRange]] will add a new sheet by that name to the workbook (as it applies the specified change to that new worksheet). Works with either backend.
* You can also now remove a sheet from a workbook using: <code>[[SpreadsheetSetCell]](wb, "-OldSheet", col, row, Null)</code>. The «col» and «row» parameters are required but ignored in this case.

== Misc. User Interface ==
* The Node Icon editor (on the Diagram menu) is far more flexible. You can use it to edit arbitrary node images, with support for color and transparency.
* Added keyboard shortcuts for '''Set Node Style...''' and '''Set Diagram Style...'''
* There is a new option, '''Use as default arrow style''', on the right-mouse context menu for an influence diagram arrow. This sets the global arrow style default to match the selected arrow.

== Built-in functions ==
* New options for [[GetProcessInfo]]: <code>"Number of monitors"</code>, <code>"Current monitor rect"</code>, <code>"Current monitor work rect"</code>, <code>"Monitor «N» Rect"</code>, and <code>"Monitor «N» work rect"</code>.
* New optional parameter, «throwParsingErrors», to [[Evaluate]].
* [[ReadFromURL]] is a bit smarter about returning binary content (like <code>*.zip</code> files) as a [[In-memory binary data terms|Binary Data Term]].
* [[MakeJSON]] will automatically encode an image in base64 JSON, and [[ParseJSON]] will automatically decode a base64 representation into an image. Also there is a new «maxCells» parameter that can be used to prevent giagantic arrays from being encoded (resulting in immensely long text).
* <code>[[GetProcessInfo]]("UI Language")</code> returns the UI language, either <code>"en"</code> (for English) or <code>"es"</code> for Spanish.
* <code>[[QualifiedName]]( obj, nsContext )</code>: Returns the qualified identifier (as text) that uniquely identifies «obj» from the context of «nsContext».
* <code>[[Namespace]] of X</code>: A new virtual attribute that returns the namespace of «X».
* [[Evaluate]] has a second return value that captures output to the typescript window (including stuff written by [[ConsolePrint]]) during the evaluation. It also has a new optional «ignoreAtFirstWarning» parameter that can be used in conjunction, capturing the first warning text in that second return value, not showing the return value to the user, and ignoring additional warnings during the duration of the Evaluate call (enables Assista to see the warnings).
* Added a syntax construct for [[Namespaces#Scoped_namespace_inclusion:_Using|Scoped namespace inclusion]] to bring a namespace into scope for only a localized expression or lexical block.
* File functions ([[ReadTextFile]], [[WriteTextFile]], [[ReadBinaryFile]], [[WriteBinaryFile]], [[ReadImageFile]] and [[WriteImageFile]]) have a new optional parameter, «extensionFilter», where you can specify which extension filters show up on a file selector dialog.

== System variables ==
* SysVar [[Graph_ColorSequence]]: Replaces [[Graph_ColorSeq]] which is now deprecated. The new sysvar contains a list of color interer with one integer (of the form <code>0x00rrggbb</code>) per color (the deprecated version used triples of numbers per color).

== Engine ==
* After loading a large model, it parses expressions in parallel, using multiple threads/cores to parse different variables. On some computers on some models, this can dramatically speed up model load time.
* Color attributes use color integers for consistently (rather than the legacy number triples for R,G,B).
* You can use a localized namespace import (for a single expression or single lexical block) with the syntax
*:<code>[[Using..Do|Using]] NS;</code>

== Model loading ==
When opening a model file, the "checking" stage (when attributes are parsed) parses different expressions on different threads, resulting in substantially faster model load times for very large models.

Note: In the event that this creates a problem with your specific model (maybe due to an as-yet-undiscovered multithreading bug), you can disable it for your model as follows:
# Temporarily turn off multithreading (Skip this step if you are able to load your model)
## New model
## <b>Definition menu / System variables / Settings / Maximum evaluation threads</b>
## Set to 1 (and remember the previous value)
# Open your model
# <b>Definition menu / System variables / Settings / Disable Multithreaded Evaluations</b>
# Press the <code>Edit Table</code> button.
# Check the checkbox for <code>Parsing</code>
# Save your model
# <b>Definition menu / System variables / Settings / Maximum evaluation threads</b>
#: Restore the original value from Step 1

== MCP server ==
* Added an ability to install multiple ADE-based Mcp servers that run different ADE releases. For example, you can install two MCP servers into Claude Code:
* ade-server: Runs ADE 7.1
* ade-server-70: Runs ADE 7.0
The information in the <code>«ADE install folder»\Examples\Mcp_server\README.txt</code> file explain how (with enough info for Claude code to configure this for you).

With both installed, Claude Code (or other MCP-enabled AI agents) can compare results for the same model across different releases, etc.

Side note: The Mcp server was added to ADE 7.0.

== Internals ==
This release has undergone massive internal restructuring and refactorization. Ideally (i.e., in the absence of bugs) these changes won't change functionality, but may alter some aspects of behavior, hopefully for the better.
* Internal data structures use for multi-dimensional arrays has been changed. Possible impacts:
** Likely to remove the sensitivity to the "canonical order" of indexes on evaluation speed.
** May change relative evaluation speeds of various functions and operations.
* Added system modules/namespaces: <code>SysLib_Internal</code> and <code>SysLib_Experimental</code>. Intended for Analytica-internal use.
*[[:Category:Cell format functions|Cell formatting functions]] (like [[CellSpan]], [[CellFill]], etc.) are now [[Struct]]s rather than functions. Does not impact usage, other that making it easier for code to traverse resulting data structures.

== Discontinued... ==
* Plug-in functions. (An old hook that allows you to extend Analytica with compiled functions and UI elements written it C++. We are almost certain no one is using these hooks any more.)
* The sysvar [[Graph_ColorSeq]] is now deprecated (but works for both reading and setting to preserve backward compatibility). It has been replaced by the system variable [[Graph_ColorSequence]].
* The built-in (but undocumented, unsupported) <code>ifpos</code> and <code>if0</code> functions were removed.
* The legacy (deprecated) syntax <code>Using temp:=... Do</code> for declaring locals is no longer supported. Legacy models will have such definitions automatically rewritten to use [[Local..Do]] when you load them. [[Using..Do]] now has a different meaning, which is to provide a temporary namespace import.

What's new in Analytica 7.1?

2026-06-29T22:35:47Z

Lchrisman: /* Built-in functions */

Analytica release 7.1 is currently in early [[Beta Tester Page|Beta Testing]]. If have have a paid desktop Analytica subscription, we encourage you to try it out from the [[Beta Tester Page]].

== Highlights of Analytica 7.1 ==
[[File:Assista What kinds of things can you do.png|alt=Assista dialog screen answering "What kinds of things can you do?"|thumb|441x441px]]
'''[[#Assista|Assista]]:''' By far the most important visible improvement is in [[#Assista|Assista]], Analytica's A.I. assistant. When first released in Analytica 6.5, Assista was already quite useful for explaining Analytica features, describing and documenting models, and building models, but it was a bit unreliable in Analytica syntax and arranging influence diagrams. We think you will find that the latest Assista is so much improved, including writing Analytica Definitions and drawing influence diagrams. You may start to use chatting with Assista as the primary way you interact with Analytica.

Other improvements include faster response time, better look and feel, a trace of its thinking, the ability to save and use conversations from previous sessions, ingesting files to provide information, including txt, pdf, csv, xlsx; understanding images and diagrams; a set of skills that you can extend and customize, and more.

'''[[#Engine|Performance]]:''' Large models start up much faster using multiple processes to parse the definitions. Arrays now use a ''tensor'' representation, similar to AI frameworks like PyTorch and TensorFlow, but with Index labels that support "Intelligent Arrays". This internal improvement isn't noticeable to users -- but enables major future performance improvements.

'''[[#Spreadsheets|CSV and spreadsheet files]] :''' You can now import [[#CSV files|CSV files]] simply by dragging them into an diagram or in a command line when you start Analytica. You can create a new [[#spreadsheets |spreadsheet]] with and add or remove sheets from it.

'''[[#Spanish|Spanish]]:''' The user interface now supports Spanish -- with other languages in the future. Assista already supports most languages, and explains features (translating docs) in your language.

== Assista ==
[[Assista]] is Analytica's A.I. assistant. She is greatly improved in this release.
* Her UI is now a top-level window that resides at the same level as Analytica's main application window.
** You can move her chat window to a non-overlapping location or even a different monitor (to maximize screen real estate used by your Analytica window).
** Selected objects remain visually selected in the main window when you type into Assista.
* Her chat has a different look-and-feel.
* Her chat window is faster and more responsive
* You can drag-highlight any text in her chat and copy to paste elsewhere.
* The UI has improved formatting capabilities for displaying Assista's response.
* Her "thoughts" display as she is processing your prompt, making it clear she is working and even giving you a peek into how she is solving it.
* She has a new processing pipeline on the backend, enabling her to respond faster but also work longer on harder tasks.
* She has an extended set of competencies (skills).
* Your sessions are automatically saved, keyed to your model, and you can resume a previous session for that model from a session selector dropdown in the UI.
* You can create and expose [[Assista_-_Analytica_AI_Assistant/Custom_user_skills_for_Assista|your own custom skills]] to expand her capabilities, or ask her to do it for you.
* You can add or drag-and-drop a document (<code>*.txt, *.pdf, *.md, *.docx, *.xlsx, *.xlsm</code>) or URLs into the chat which Assista can "ingest" during your conversation. Have her extract data from the doc, adding tables to your model. Or even to implement a model described by the paper or translate a spreadsheet into an Analytica model.
* Assista can "see" images in your model -- pictures in nodes, images in table cells, and diagram or graph screenshots.
* She is language-aware. If you are using Analytica is Spanish, she'll provide UI instructions that refer to the Spanish-language UI elements.
* She is aware of her reasoning in previous conversation turns and the actions she took, enabling her to explain her reasoning or build on ideas she thought about but might not have included in the final response.
* She has an improved ability to navigate and find objects within your (large) models.
* You can personalize her tone, style, level of verbosity and provide her custom instructions. To do this, click on the icon in the top-left corner of the Assista window and select Personization...

== Multi-linguality: Spanish UI ==
Analytica now comes with a Spanish-language UI, in which its menus, dialogs, error messages and built-in function descriptions are all in Spanish. Also its installer runs with a Spanish-language UI when you are in a Spanish-language region. Spanish is the default when you are in a Spanish-language region.

You can override the default language by launching Analytica as:
* <code>Analytica.exe /lang:es</code>
*: or
* <code>Analytica.exe /lang:en</code>

You can also set the <code>Language</code> registry setting in the <code>"HKCU/Software/Lumina Decision Systems/Analytica"</code> hive to REG_SZ <code>"en"</code> on <code>"es"</code> for your default if different from your windows region setting.

Some of you may ask "what about my language?". Stay tuned (and let us know there is a demand for your language). Once our AI translation pipeline is solid, it shouldn't be too hard for us to add more.

== Window appearance ==
The appearance of the chrome around child MDI windows (aka the "non-client area") has been changed to more closely match the Windows 11 style of windows -- i.e., thin (1 pixel) borders, rounded corners at the top, white title bar, very plain (text-like) button images in the toolbar.

== CSV files ==
There are now a few additional ways to open CSV files in Analytica:
* On the command line: <code>Analytica.exe MyData.csv</code>
* Drag and drop a *.csv file onto the diagram (which behaves the same as using <code>File / Import...</code> on the *.csv file).

== Spreadsheets ==
* <code>[[SpreadsheetOpen]]("new")</code> now creates a blank spreadsheet in memory. Works with both the Excel and LibXl backends.
* Prefacing a sheet name with + in the call to [[SpreadsheetSetCell]] or [[SpreadsheetSetRange]] will add a new sheet by that name to the workbook (as it applies the specified change to that new worksheet). Works with either backend.
* You can also now remove a sheet from a workbook using: <code>[[SpreadsheetSetCell]](wb, "-OldSheet", col, row, Null)</code>. The «col» and «row» parameters are required but ignored in this case.

== Misc. User Interface ==
* The Node Icon editor (on the Diagram menu) is far more flexible. You can use it to edit arbitrary node images, with support for color and transparency.
* Added keyboard shortcuts for '''Set Node Style...''' and '''Set Diagram Style...'''
* There is a new option, '''Use as default arrow style''', on the right-mouse context menu for an influence diagram arrow. This sets the global arrow style default to match the selected arrow.

== Built-in functions ==
* New options for [[GetProcessInfo]]: <code>"Number of monitors"</code>, <code>"Current monitor rect"</code>, <code>"Current monitor work rect"</code>, <code>"Monitor «N» Rect"</code>, and <code>"Monitor «N» work rect"</code>.
* New optional parameter, «throwParsingErrors», to [[Evaluate]].
* [[ReadFromURL]] is a bit smarter about returning binary content (like <code>*.zip</code> files) as a [[In-memory binary data terms|Binary Data Term]].
* [[MakeJSON]] will automatically encode an image in base64 JSON, and [[ParseJSON]] will automatically decode a base64 representation into an image. Also there is a new «maxCells» parameter that can be used to prevent giagantic arrays from being encoded (resulting in immensely long text).
* <code>[[GetProcessInfo]]("UI Language")</code> returns the UI language, either <code>"en"</code> (for English) or <code>"es"</code> for Spanish.
* <code>[[QualifiedName]]( obj, nsContext )</code>: Returns the qualified identifier (as text) that uniquely identifies «obj» from the context of «nsContext».
* <code>[[Namespace]] of X</code>: A new virtual attribute that returns the namespace of «X».
* [[Evaluate]] has a second return value that captures output to the typescript window (including stuff written by [[ConsolePrint]]) during the evaluation. It also has a new optional «ignoreAtFirstWarning» parameter that can be used in conjunction, capturing the first warning text in that second return value, not showing the return value to the user, and ignoring additional warnings during the duration of the Evaluate call (enables Assista to see the warnings).
* Added a syntax construct for [[Namespaces#Scoped_namespace_inclusion:_Using|Scoped namespace inclusion]] to bring a namespace into scope for only a localized expression or lexical block.
* File functions ([[ReadTextFile]], [[WriteTextFile]], [[ReadBinaryFile]], [[WriteBinaryFile]], [[ReadImageFile]] and [[WriteImageFile]]) have a new optional parameter, «extensionFilter», where you can specify which extension filters show up on a file selector dialog.

== System variables ==
* SysVar [[Graph_ColorSequence]]: Replaces [[Graph_ColorSeq]] which is now deprecated. The new sysvar contains a list of color interer with one integer (of the form <code>0x00rrggbb</code>) per color (the deprecated version used triples of numbers per color).

== Engine ==
* After loading a large model, it parses expressions in parallel, using multiple threads/cores to parse different variables. On some computers on some models, this can dramatically speed up model load time.
* Color attributes use color integers for consistently (rather than the legacy number triples for R,G,B).
* You can use a localized namespace import (for a single expression or single lexical block) with the syntax
*:<code>[[Using..Do|Using]] NS;</code>

== Model loading ==
When opening a model file, the "checking" stage (when attributes are parsed) parses different expressions on different threads, resulting in substantially faster model load times for very large models.

Note: In the event that this creates a problem with your specific model (maybe due to an as-yet-undiscovered multithreading bug), you can disable it for your model as follows:
# Temporarily turn off multithreading (Skip this step if you are able to load your model)
## New model
## <b>Definition menu / System variables / Settings / Maximum evaluation threads</b>
## Set to 1 (and remember the previous value)
# Open your model
# <b>Definition menu / System variables / Settings / Disable Multithreaded Evaluations</b>
# Press the <code>Edit Table</code> button.
# Check the checkbox for <code>Parsing</code>
# Save your model
# <b>Definition menu / System variables / Settings / Maximum evaluation threads</b>
#: Restore the original value from Step 1

== MCP server ==
* Added an ability to install multiple ADE-based Mcp servers that run different ADE releases. For example, you can install two MCP servers into Claude Code:
* ade-server: Runs ADE 7.1
* ade-server-70: Runs ADE 7.0
The information in the <code>«ADE install folder»\Examples\Mcp_server\README.txt</code> file explain how (with enough info for Claude code to configure this for you).

With both installed, Claude Code (or other MCP-enabled AI agents) can compare results for the same model across different releases, etc.

Side note: The Mcp server was added to ADE 7.0.

== Internals ==
This release has undergone massive internal restructuring and refactorization. Ideally (i.e., in the absence of bugs) these changes won't change functionality, but may alter some aspects of behavior, hopefully for the better.
* Internal data structures use for multi-dimensional arrays has been changed. Possible impacts:
** Likely to remove the sensitivity to the "canonical order" of indexes on evaluation speed.
** May change relative evaluation speeds of various functions and operations.
* Added system modules/namespaces: <code>SysLib_Internal</code> and <code>SysLib_Experimental</code>. Intended for Analytica-internal use.
*[[:Category:Cell format functions|Cell formatting functions]] (like [[CellSpan]], [[CellFill]], etc.) are now [[Struct]]s rather than functions. Does not impact usage, other that making it easier for code to traverse resulting data structures.

== Discontinued... ==
* Plug-in functions. (An old hook that allows you to extend Analytica with compiled functions and UI elements written it C++. We are almost certain no one is using these hooks any more.)
* The sysvar [[Graph_ColorSeq]] is now deprecated (but works for both reading and setting to preserve backward compatibility). It has been replaced by the system variable [[Graph_ColorSequence]].
* The built-in (but undocumented, unsupported) <code>ifpos</code> and <code>if0</code> functions were removed.
* The legacy (deprecated) syntax <code>Using temp:=... Do</code> for declaring locals is no longer supported. Legacy models will have such definitions automatically rewritten to use [[Local..Do]] when you load them. [[Using..Do]] now has a different meaning, which is to provide a temporary namespace import.

WriteImageFile

2026-06-29T20:02:37Z

Lchrisman: Document extensionFilter parameter (new in 7.1, ER 20237)

[[Category:Image and canvas functions]]
[[Category:Database Functions]]
[[category:File system functions]]

{{ReleaseBar}}

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

''Requires {{Analytica Developer}} edition or better.''

== WriteImageFile( filename, image'', showDialog, warn, mimeType, title{{Release|6.0||, download}}{{Release|7.1||, extensionFilter}}'' ) ==

Writes an in-memory image to a file.

* «filename»: When a full (absolute) filename is not supplied, the file name is relative to the [[CurrentDataFolder]]. {{Release|6.4||
*:When «filename» is <code>"<>"</code>, the image is written to an in-memory binary data term.}}
* «image»: An image, obtained from the <code>(Pict Of «obj»)</code> attribute, or from a function that returns an image such as [[ReadImageFile]], [[ReadFromUrl]], or [[CanvasImage]].
* «showDialog»: (Optional) When <code>True</code>, the file finder dialog is always presented to the user. When <code>False</code>, the dialog is never presented to the user. When omitted, the dialog is shown only if the file cannot be written to «filename», or if the file already exists and you haven't specified <code>warn:False</code>.
* «warn»: (Optional) When <code>True</code>, a warning is issued if <code>showDialog:False</code> and the file exists. This warning will only be shown when [[Preferences#Show result warnings|Show Result Warnings]] is enabled.
* «mimeType»: (Optional) Specifies the preferred file type, such as <code>'PNG'</code>, <code>'JPG'</code>, etc., for the image.
* «title»: (Optional) A custom caption shown in the file selector when the file selector is displayed.{{Release|6.0||
* «download»: (Option) When <code>True</code> and running in [[ACP]], the image downloaded to the end user's computer as an image file with the name «filename».}}
{{Release|1=7.1|2=|3=
* «extensionFilter»: (Optional) Overrides the file types offered in the file-selector dialog. Specify the filter(s) as a text in any of these forms: a ''display-format'' text such as <code>"Image Files (*.png, *.jpg, *.tif); All Files (*.*)"</code>; a list of <code>"Description{{!}}patterns"</code> filters such as <code>["Images{{!}}*.png;*.jpg;*.tif", "All files{{!}}*.*"]</code>; or just patterns such as <code>"*.png;*.jpg;*.gif;*.tif"</code>. An <code>"All files (*.*)"</code> entry is appended automatically unless your list already includes one; when omitted, the default file types are shown.}}

== See Also ==
* [[ReadImageFile]]
* [[ReadFromURL]]
* [[CanvasImage]]
* [[ImageInfo]]{{Release|6.4||
* If you write to an in-memory binary data term, see: [[ReadBinaryFile]], [[GetFromBinaryData]], [[BinaryDataSize]]}}

ReadImageFile

2026-06-29T19:59:19Z

Lchrisman: Note extensionFilter parameter added in 7.1 (ER 20237)

[[category:System Functions]]
[[category:Database Functions]]
[[Category:Image and canvas functions]]
[[category:File system functions]]

''Requires {{Analytica Developer}} or Power Player''

== ReadImageFile(filename'', showDialog{{Release|7.1||, extensionFilter}}'') ==

Reads an image file with «filename» into memory and returns a value that acts as a [[handle]] to the image and can be assigned to the [[Pict]] attribute of an object on a diagram.

The optional parameter, «showDialog» controls whether the file dialog appears. If not specified, then the dialog appears only if the file does not exist. To prevent this from showing (displaying an error instead) specify «showDialog» as <code>False</code>. To force the dialog to display, even if the file exists (i.e., as a way to give the user a chance to change the filename, while still providing a default name), specify «showDialog» as true.

{{Release|1=7.1|2=|3=
«extensionFilter»: (Optional) Overrides the file types offered in the file-selector dialog. Specify the filter(s) as a text in any of these forms:
* ''Display form'' — one or more filters separated by semicolons, each a description with its patterns in parentheses, e.g. <code>"Image Files (*.png, *.jpg, *.tif); All Files (*.*)"</code>.
* ''A list of'' <code>"Description{{!}}patterns"</code> ''filters'' (description first, patterns separated by <code>;</code>), e.g. <code>["Images{{!}}*.png;*.jpg;*.tif", "All files{{!}}*.*"]</code>.
* ''Just patterns'', e.g. <code>"*.png;*.jpg;*.gif;*.tif"</code> (a description is generated automatically).
An <code>"All files (*.*)"</code> entry is appended automatically unless your list already includes one. When omitted, the default file types are shown.
}}

From [[ADE]], the dialog is never displayed.

== Uses ==
We foresee possible cases where certain applications may need to integrate with an external application that generates an image, and then may want to embed the image in a diagram. Analytica might launch the external command using [[RunConsoleProcess]], sending it commands and data either through stdIn or via a data file, and waiting for it to complete. The external program would produce an image (e.g., a JPEG) and store it in a file. Analytica would then use [[ReadImageFile]] to read in the resulting, dynamically created, image and assign it to the Pict attribute of a picture node on the diagram. To update the [[dynamic]] image, it would repeat the process.

External processes that might be used in the fashion might include GIS systems, drawing programs, or external graphing engines.

This reads the image only from a file on disk. To read an image from a web URL, use [[ReadFromURL]]. There is also no facility currently for extracting "blobs" from database queries and converting them to functional image objects.

Image handles currently display in result tables in a textual form. This is also tentative and subject to change, with the possibility that future releases will display the graphical image directly in the result table.

== Supported file formats ==
* JPG, JPEG
* PNG
* GIF
* TIFF
* EXIF
* WMF
* BMP (in [[Analytica 5.1]] or later)

== From ADE ==
When evaluated in [[ADE|the Analytica Decision Engine (ADE)]] and a dialog needs to be shown to the end-user, it calls [[IAdeUICallbacks::GetFilename]](...). From within that callback, the parent application can interact with the end-user to resolve the file path, and a web applications can instruct the end-user to upload a file. Once complete, the callback returns the full path to the file which is then read. To receive this callback, the parent application must have previously registered the callback with ADE using [[CAEngine::SetCallbackObject]]( ). If it has not registered a callback and the file doesn't exist, returns an empty text.

== History ==
Introduced in [[Analytica 4.2]] as an experimental feature.

ADE callback added in [[Analytica 4.6|ADE 4.6]]

Promoted to supported function in [[Analytica 5.0]].

«extensionFilter» parameter added in [[Analytica 7.1]].

== See Also ==
* [[ReadFromUrl]]
* [[ReadTextFile]]
* [[RunConsoleProcess]]
* [[Handle]]
* [[ImageFromHex]]

ReadImageFile

2026-06-29T19:58:04Z

Lchrisman: Document extensionFilter parameter (new in 7.1, ER 20237)

[[category:System Functions]]
[[category:Database Functions]]
[[Category:Image and canvas functions]]
[[category:File system functions]]

''Requires {{Analytica Developer}} or Power Player''

== ReadImageFile(filename'', showDialog{{Release|7.1||, extensionFilter}}'') ==

Reads an image file with «filename» into memory and returns a value that acts as a [[handle]] to the image and can be assigned to the [[Pict]] attribute of an object on a diagram.

The optional parameter, «showDialog» controls whether the file dialog appears. If not specified, then the dialog appears only if the file does not exist. To prevent this from showing (displaying an error instead) specify «showDialog» as <code>False</code>. To force the dialog to display, even if the file exists (i.e., as a way to give the user a chance to change the filename, while still providing a default name), specify «showDialog» as true.

{{Release|1=7.1|2=|3=
«extensionFilter»: (Optional) Overrides the file types offered in the file-selector dialog. Specify the filter(s) as a text in any of these forms:
* ''Display form'' — one or more filters separated by semicolons, each a description with its patterns in parentheses, e.g. <code>"Image Files (*.png, *.jpg, *.tif); All Files (*.*)"</code>.
* ''A list of'' <code>"Description{{!}}patterns"</code> ''filters'' (description first, patterns separated by <code>;</code>), e.g. <code>["Images{{!}}*.png;*.jpg;*.tif", "All files{{!}}*.*"]</code>.
* ''Just patterns'', e.g. <code>"*.png;*.jpg;*.gif;*.tif"</code> (a description is generated automatically).
An <code>"All files (*.*)"</code> entry is appended automatically unless your list already includes one. When omitted, the default file types are shown.
}}

From [[ADE]], the dialog is never displayed.

== Uses ==
We foresee possible cases where certain applications may need to integrate with an external application that generates an image, and then may want to embed the image in a diagram. Analytica might launch the external command using [[RunConsoleProcess]], sending it commands and data either through stdIn or via a data file, and waiting for it to complete. The external program would produce an image (e.g., a JPEG) and store it in a file. Analytica would then use [[ReadImageFile]] to read in the resulting, dynamically created, image and assign it to the Pict attribute of a picture node on the diagram. To update the [[dynamic]] image, it would repeat the process.

External processes that might be used in the fashion might include GIS systems, drawing programs, or external graphing engines.

This reads the image only from a file on disk. To read an image from a web URL, use [[ReadFromURL]]. There is also no facility currently for extracting "blobs" from database queries and converting them to functional image objects.

Image handles currently display in result tables in a textual form. This is also tentative and subject to change, with the possibility that future releases will display the graphical image directly in the result table.

== Supported file formats ==
* JPG, JPEG
* PNG
* GIF
* TIFF
* EXIF
* WMF
* BMP (in [[Analytica 5.1]] or later)

== From ADE ==
When evaluated in [[ADE|the Analytica Decision Engine (ADE)]] and a dialog needs to be shown to the end-user, it calls [[IAdeUICallbacks::GetFilename]](...). From within that callback, the parent application can interact with the end-user to resolve the file path, and a web applications can instruct the end-user to upload a file. Once complete, the callback returns the full path to the file which is then read. To receive this callback, the parent application must have previously registered the callback with ADE using [[CAEngine::SetCallbackObject]]( ). If it has not registered a callback and the file doesn't exist, returns an empty text.

== History ==
Introduced in [[Analytica 4.2]] as an experimental feature.

ADE callback added in [[Analytica 4.6|ADE 4.6]]

Promoted to supported function in [[Analytica 5.0]].

== See Also ==
* [[ReadFromUrl]]
* [[ReadTextFile]]
* [[RunConsoleProcess]]
* [[Handle]]
* [[ImageFromHex]]

WriteBinaryFile

2026-06-29T19:55:12Z

Lchrisman: Document extensionFilter parameter (new in 7.1, ER 20237)

[[category:Database Functions]]
[[category:System Functions]]
[[category:File system functions]]

{{ReleaseBar}}

''Requires [[Analytica 5.0]] {{Developer}} edition or better.''

ReadBinaryFile() and WriteBinaryFile() read and write binary files, in contrast to [[ReadTextFile]] and [[WriteTextFile]], which read and write text files (surprise!). Binary files store data in a format similar to how the data are represented in computer memory used by Analytica (or any application). So they are usually more compact and much faster to read or write than text files. Text files, such as [[ParseCSV|CSV files]] or Analytica [[Model file formats]], represent each number as a sequence of digit characters, which have to be parsed and converted to the internal binary form, which takes time.

Of course, binary files, unlike text files, are not readable by humans. The layout and metadata, such as the size of each cell and row, and the number of rows, is not part of a binary file. This is unlike CSV files, for example, with separators for each cell and row (usually comma and new line), and column headers in the first row. For binary files, you must need to specify this information as parameters to ReadBinaryFile() and WriteBinaryFile(), including array indexes, and the data type or number of bytes per cell. It's usually worth using binary formats only when you have really large amounts of data so that the file size and read/write speed are significant issues. Occasionally, you may want to read binary files from other sources or generate binary files for use by other applications.

== WriteBinaryFile(filename, data'', I..., bytesPer, typeFlags, append, warn, showDialog, title{{Release|6.0||, download}}{{Release|7.1||, extensionFilter}}'') ==

Writes data to a binary file. If you wish to write data to a human-readable file, you should probably be using [[WriteTextFile]]. Use [[WriteBinaryFile]] when providing data for or integrated with another application that has a specific binary data format. Or when you have large amounts of data -- e.g. large arrays -- to save and read into Analytica, you can save substantial computation time, reduce file size, and retain full precision by using [[WriteBinaryFile]] and [[ReadBinaryFile]] relative to using text files or a database.

== Parameters ==
=== filename ===
Name of file to create, replace or append to.

File name paths can be either relative or absolute. An absolute path specifies the full path of the file from a root drive, such as
:<code>"C:\Users\Drice\Documents\Projects\FatigueAnalysis\Results.bin"</code>

A relative filename incompletely specifies a file path, and is interpreted relative to the [[CurrentDataDirectory]].

{{Release|6.2||If you set the «filename» to <code>"<>"</code>, [[WriteBinaryFile]] writes to an in-memory binary data term rather than to a file. }}

=== data ===
The data to write, usually an array. If «data» is an array of integers from 0 to 255, by default each integer is written into one byte of the file. If the number is a real (floating point) number, it will round it to an integer, and ignore digits above 255 (the maximum integer that fits into one byte). To write larger integers or to preserve floating point numbers or text values, you can specify more bytes and other types with the optional «bytesPer» and «typeFlags» described below.

=== I... ===
The indexes of the array passed to «data». When «data» has more than one dimension, the order in which you list the indexes controls the order in which cells are written to the file. The first index you list is varied the slowest, and the last index you list varies fastest. For example, suppose index <code>I := 1..3</code> and index <code>J := 1..2</code>, then

:<code>WriteBinaryFile(filename, data, I, J)</code>

writes the cells in the order:
:<code>data[I = 1, J = 1]</code>
:<code>data[I = 1, J = 2]</code>
:<code>data[I = 2, J = 1]</code>
:<code>data[I = 2, J = 2]</code>
:<code>data[I = 3, J = 1]</code>
:<code>data[I = 3, J = 2]</code>

whereas
:<code>WriteBinaryFile(filename, data, J, I)</code>

writes the cells in the order
:<code>data[I = 1, J = 1]</code>
:<code>data[I = 2, J = 1]</code>
:<code>data[I = 3, J = 1]</code>
:<code>data[I = 1, J = 2]</code>
:<code>data[I = 2, J = 2]</code>
:<code>data[I = 3, J = 2]</code>

=== bytesPer ===

The number of bytes in the file per cell of «data».

When writing integer values (the default when «typeFlags» is omitted), this specifies the number of bytes per integer word, and can be 1 (for single bytes, integers 0 to 2^8-1=255), 2 (for integers up to 2^16-1 = 65,535), 4 (for 32-bit integers up to 2^32-1 = 4,294,967,295) or 8 (for 64-bit integers up to 2^64-1).

For floating point real numbers, you can specify 4 (for 32-bit IEEE 754 reals, often called '''''float'''''s), or 8 (for 64-bit IEEE 754 reals, often called '''''double'''''s). When «typeFlags» = 2 (floating point), the «bytesPer» defaults to 8 if not specified.

For the «typeFlags» option of <code>3</code>, it uses 9 bytes per item, so you can either omit «bytesPer» or set it to 9. Any other value gives an error.

For the «typeFlags» option of <code>4</code>, the number of bytes per item may vary (depending on the length of text values), and you must omit «bytesPer» to avoid an error.

=== typeFlags ===

The data type format written:
:<code>1</code> = Integer (default)
:<code>2</code> = IEEE 754 Floating point real
:<code>3</code> = Value (numbers, dates and null). 9 bytes per item.
:<code>4</code> = Value (including text{{Release|6.2|| and binary}}). Variable bytes per text item.{{Release|1=6.2|2=|3=
:<code>7</code> = Raw binary data. «data» must be in-memory binary data.}}
:<code>32</code> = Big endian flag.
:<code>64</code> = Flag to issue error when cell cannot be coerced to type. By default, it will not give error messages when it cannot coerce a cell to fit in the specified data type.

A standard Intel convention writes numbers (integers or floating point values) with the least significant bytes written first, least significant bytes last, which is termed "little-endian format". [[WriteBinaryFile]] uses this default unless the <code>typeFlags = 32</code> flag is specified. "Big endian" means that the most significant byte is written first.

You can add <code>32, 64</code> or <code>32 + 64</code> options to the data type selection. So, for example, a value of <code>2 + 32 + 64</code> would specify a floating point format (<code>2</code>) with the byte order reversed (<code>32</code>), and with an error issued when a non-numeric cell is encountered (<code>64</code>).

Integer formats write the «bytesPer» least-significant bits to the file. For example, when «bytesPer» is 2, the integers written will be between 0 and 65535 (or between -32768 and 32767). If «data» contains a number outside this range, such as 66,000, then <code>Mod(66K, 2^16, true)</code>, which equals 464 would actually be written. It isn't necessary to differentiate between whether the integers are positive or negative at the time they are being written, but you do need to make this distinction when reading (see [[ReadBinaryFile]]).

The Value type is a variant data type, in which a byte is written to encode the internal data type of the value, and followed by an 8-byte value. The «typeFlags» option of <code>3</code> only writes Analytica data types that can be fully encoded in with 8 bytes, which includes integers, fixed-point reals, floating point reals, date and date-time numbers, and the special value [[Null]]. When using this type, [[Null]] values ARE written to the file. The «typeFlags» option of <code>3</code> cannot be used to write text values, since these vary in length. The cells will each use 9 bytes, and will be spaced every 9 bytes in the file.

The «typeFlags» option of <code>4</code> extends option <code>3</code> by allowing text values and binary data ("blobs"). When a text value occurs, the first byte indicates that the value is text, the next four bytes encode the length, <code>n</code>, and the next <code>n</code> bytes encodes the characters in UTF-8. {{Release|6.2||When a binary "blob" occurs, the first byte indicates that it is binary data, the next 8 bytes encode the number of bytes, and the next <code>n</code>bytes are the binary data.}} When this format is used, the «bytesPer» parameter must be omitted. The location of items in the file are not spaced at any predictable interval, since text items vary in length.

{{Release|6.2||When «typeFlags» is <code>7</code>, then «data» must be in memory binary data or Null (if Null, the data is ignored). This writes the binary data directly with no extra surrounding information to indicate its type or size. Thus, if this option is applied to an array of binary data, the binary data gets directly appended.}}

=== append ===
When you pass <code>True</code> to the «append» parameter, it appends the data to the end of the file if it already exists. When you omit «append» or set it to false, it overwrites any existing file with the new contents.

=== warn ===
Use this Boolean parameter to force or suppress a warning when the file already exists. When omitted, a warning occurs unless you are appending.

=== showDialog ===
This is a flag to force or suppress the file selector dialog. When not specified, the dialog only displays if needed, for example, if the file name is blank or to a directory that is not writable or does not exist. Setting «showDialog» to false suppresses the dialog from appearing. Setting «showDialog» to true forces the dialog to display, using «filename» as the initial default.

=== title ===
The text to use as caption of file selector dialog.

=== download ===
''New to [[Analytica 6.0]]''

When set to <code>True</code> and the model is running in [[ACP]], the data is downloaded to the end user's computer as a file with the name given by «filename».

{{Release|1=7.1|2=|3=
=== extensionFilter ===
(''New in [[Analytica 7.1]]'') Overrides the file types offered in the file-selector dialog. Specify the filter(s) as a text in any of these forms:
* ''Display form'' — one or more filters separated by semicolons, each a description with its patterns in parentheses, e.g. <code>"Data Files (*.dat, *.bin); All Files (*.*)"</code>.
* ''A list of'' <code>"Description{{!}}patterns"</code> ''filters'' (description first, patterns separated by <code>;</code>), e.g. <code>["Data files{{!}}*.dat;*.bin", "All files{{!}}*.*"]</code>.
* ''Just patterns'', e.g. <code>"*.dat;*.bin"</code> (a description is generated automatically).
An <code>"All files (*.*)"</code> entry is appended automatically unless your list already includes one. When omitted, the default file types are shown.
}}

== See Also ==
* [[In-memory binary data terms]]
* [[Binary and hexadecimal integer formats]]
* [[ReadBinaryFile]]
* [[GetFromBinaryData]]
* [[BinaryDataSize]]
* [[Base64-encoded binary term literals]]
* [[WriteTextFile]]
* [[Dec2Bin]]
* [[Hex2Dec]]
* [[Hex2Bin]]
* [[Bin2Dec]]
* [[Bin2Hex]]

WriteBinaryFile

2026-06-29T19:53:03Z

Lchrisman: Add extensionFilter to signature (new in 7.1, ER 20237)

[[category:Database Functions]]
[[category:System Functions]]
[[category:File system functions]]

{{ReleaseBar}}

''Requires [[Analytica 5.0]] {{Developer}} edition or better.''

ReadBinaryFile() and WriteBinaryFile() read and write binary files, in contrast to [[ReadTextFile]] and [[WriteTextFile]], which read and write text files (surprise!). Binary files store data in a format similar to how the data are represented in computer memory used by Analytica (or any application). So they are usually more compact and much faster to read or write than text files. Text files, such as [[ParseCSV|CSV files]] or Analytica [[Model file formats]], represent each number as a sequence of digit characters, which have to be parsed and converted to the internal binary form, which takes time.

Of course, binary files, unlike text files, are not readable by humans. The layout and metadata, such as the size of each cell and row, and the number of rows, is not part of a binary file. This is unlike CSV files, for example, with separators for each cell and row (usually comma and new line), and column headers in the first row. For binary files, you must need to specify this information as parameters to ReadBinaryFile() and WriteBinaryFile(), including array indexes, and the data type or number of bytes per cell. It's usually worth using binary formats only when you have really large amounts of data so that the file size and read/write speed are significant issues. Occasionally, you may want to read binary files from other sources or generate binary files for use by other applications.

== WriteBinaryFile(filename, data'', I..., bytesPer, typeFlags, append, warn, showDialog, title{{Release|6.0||, download}}{{Release|7.1||, extensionFilter}}'') ==

Writes data to a binary file. If you wish to write data to a human-readable file, you should probably be using [[WriteTextFile]]. Use [[WriteBinaryFile]] when providing data for or integrated with another application that has a specific binary data format. Or when you have large amounts of data -- e.g. large arrays -- to save and read into Analytica, you can save substantial computation time, reduce file size, and retain full precision by using [[WriteBinaryFile]] and [[ReadBinaryFile]] relative to using text files or a database.

== Parameters ==
=== filename ===
Name of file to create, replace or append to.

File name paths can be either relative or absolute. An absolute path specifies the full path of the file from a root drive, such as
:<code>"C:\Users\Drice\Documents\Projects\FatigueAnalysis\Results.bin"</code>

A relative filename incompletely specifies a file path, and is interpreted relative to the [[CurrentDataDirectory]].

{{Release|6.2||If you set the «filename» to <code>"<>"</code>, [[WriteBinaryFile]] writes to an in-memory binary data term rather than to a file. }}

=== data ===
The data to write, usually an array. If «data» is an array of integers from 0 to 255, by default each integer is written into one byte of the file. If the number is a real (floating point) number, it will round it to an integer, and ignore digits above 255 (the maximum integer that fits into one byte). To write larger integers or to preserve floating point numbers or text values, you can specify more bytes and other types with the optional «bytesPer» and «typeFlags» described below.

=== I... ===
The indexes of the array passed to «data». When «data» has more than one dimension, the order in which you list the indexes controls the order in which cells are written to the file. The first index you list is varied the slowest, and the last index you list varies fastest. For example, suppose index <code>I := 1..3</code> and index <code>J := 1..2</code>, then

:<code>WriteBinaryFile(filename, data, I, J)</code>

writes the cells in the order:
:<code>data[I = 1, J = 1]</code>
:<code>data[I = 1, J = 2]</code>
:<code>data[I = 2, J = 1]</code>
:<code>data[I = 2, J = 2]</code>
:<code>data[I = 3, J = 1]</code>
:<code>data[I = 3, J = 2]</code>

whereas
:<code>WriteBinaryFile(filename, data, J, I)</code>

writes the cells in the order
:<code>data[I = 1, J = 1]</code>
:<code>data[I = 2, J = 1]</code>
:<code>data[I = 3, J = 1]</code>
:<code>data[I = 1, J = 2]</code>
:<code>data[I = 2, J = 2]</code>
:<code>data[I = 3, J = 2]</code>

=== bytesPer ===

The number of bytes in the file per cell of «data».

When writing integer values (the default when «typeFlags» is omitted), this specifies the number of bytes per integer word, and can be 1 (for single bytes, integers 0 to 2^8-1=255), 2 (for integers up to 2^16-1 = 65,535), 4 (for 32-bit integers up to 2^32-1 = 4,294,967,295) or 8 (for 64-bit integers up to 2^64-1).

For floating point real numbers, you can specify 4 (for 32-bit IEEE 754 reals, often called '''''float'''''s), or 8 (for 64-bit IEEE 754 reals, often called '''''double'''''s). When «typeFlags» = 2 (floating point), the «bytesPer» defaults to 8 if not specified.

For the «typeFlags» option of <code>3</code>, it uses 9 bytes per item, so you can either omit «bytesPer» or set it to 9. Any other value gives an error.

For the «typeFlags» option of <code>4</code>, the number of bytes per item may vary (depending on the length of text values), and you must omit «bytesPer» to avoid an error.

=== typeFlags ===

The data type format written:
:<code>1</code> = Integer (default)
:<code>2</code> = IEEE 754 Floating point real
:<code>3</code> = Value (numbers, dates and null). 9 bytes per item.
:<code>4</code> = Value (including text{{Release|6.2|| and binary}}). Variable bytes per text item.{{Release|1=6.2|2=|3=
:<code>7</code> = Raw binary data. «data» must be in-memory binary data.}}
:<code>32</code> = Big endian flag.
:<code>64</code> = Flag to issue error when cell cannot be coerced to type. By default, it will not give error messages when it cannot coerce a cell to fit in the specified data type.

A standard Intel convention writes numbers (integers or floating point values) with the least significant bytes written first, least significant bytes last, which is termed "little-endian format". [[WriteBinaryFile]] uses this default unless the <code>typeFlags = 32</code> flag is specified. "Big endian" means that the most significant byte is written first.

You can add <code>32, 64</code> or <code>32 + 64</code> options to the data type selection. So, for example, a value of <code>2 + 32 + 64</code> would specify a floating point format (<code>2</code>) with the byte order reversed (<code>32</code>), and with an error issued when a non-numeric cell is encountered (<code>64</code>).

Integer formats write the «bytesPer» least-significant bits to the file. For example, when «bytesPer» is 2, the integers written will be between 0 and 65535 (or between -32768 and 32767). If «data» contains a number outside this range, such as 66,000, then <code>Mod(66K, 2^16, true)</code>, which equals 464 would actually be written. It isn't necessary to differentiate between whether the integers are positive or negative at the time they are being written, but you do need to make this distinction when reading (see [[ReadBinaryFile]]).

The Value type is a variant data type, in which a byte is written to encode the internal data type of the value, and followed by an 8-byte value. The «typeFlags» option of <code>3</code> only writes Analytica data types that can be fully encoded in with 8 bytes, which includes integers, fixed-point reals, floating point reals, date and date-time numbers, and the special value [[Null]]. When using this type, [[Null]] values ARE written to the file. The «typeFlags» option of <code>3</code> cannot be used to write text values, since these vary in length. The cells will each use 9 bytes, and will be spaced every 9 bytes in the file.

The «typeFlags» option of <code>4</code> extends option <code>3</code> by allowing text values and binary data ("blobs"). When a text value occurs, the first byte indicates that the value is text, the next four bytes encode the length, <code>n</code>, and the next <code>n</code> bytes encodes the characters in UTF-8. {{Release|6.2||When a binary "blob" occurs, the first byte indicates that it is binary data, the next 8 bytes encode the number of bytes, and the next <code>n</code>bytes are the binary data.}} When this format is used, the «bytesPer» parameter must be omitted. The location of items in the file are not spaced at any predictable interval, since text items vary in length.

{{Release|6.2||When «typeFlags» is <code>7</code>, then «data» must be in memory binary data or Null (if Null, the data is ignored). This writes the binary data directly with no extra surrounding information to indicate its type or size. Thus, if this option is applied to an array of binary data, the binary data gets directly appended.}}

=== append ===
When you pass <code>True</code> to the «append» parameter, it appends the data to the end of the file if it already exists. When you omit «append» or set it to false, it overwrites any existing file with the new contents.

=== warn ===
Use this Boolean parameter to force or suppress a warning when the file already exists. When omitted, a warning occurs unless you are appending.

=== showDialog ===
This is a flag to force or suppress the file selector dialog. When not specified, the dialog only displays if needed, for example, if the file name is blank or to a directory that is not writable or does not exist. Setting «showDialog» to false suppresses the dialog from appearing. Setting «showDialog» to true forces the dialog to display, using «filename» as the initial default.

=== title ===
The text to use as caption of file selector dialog.

=== download ===
''New to [[Analytica 6.0]]''

When set to <code>True</code> and the model is running in [[ACP]], the data is downloaded to the end user's computer as a file with the name given by «filename».

== See Also ==
* [[In-memory binary data terms]]
* [[Binary and hexadecimal integer formats]]
* [[ReadBinaryFile]]
* [[GetFromBinaryData]]
* [[BinaryDataSize]]
* [[Base64-encoded binary term literals]]
* [[WriteTextFile]]
* [[Dec2Bin]]
* [[Hex2Dec]]
* [[Hex2Bin]]
* [[Bin2Dec]]
* [[Bin2Hex]]

ReadBinaryFile

2026-06-29T19:50:19Z

Lchrisman: Document extensionFilter parameter (new in 7.1, ER 20237)

[[category:Database Functions]]
[[category:System Functions]]
[[category:File system functions]]
{{ReleaseBar}}

''Requires [[Analytica 5.0]] {{Developer}} or higher''

== ReadBinaryFile(filename'', bytesPer, typeFlags, offset, resultIndex..., showDialog, title{{Release|7.1||, extensionFilter}}'') ==

Reads data directly from a binary (i.e., non-text) file.

Flat data files are usually read using [[ReadTextFile]]. When you read text files, end-of-line characters are interpreted in various ways for you, conversions from character sets such as UTF-8 or Unicode may occur, and certain special byte values such as the zero byte or end-of-file cannot occur in the file. In contrast, reading from a binary file gives you access to the bytes of the file exactly as they appear.

[[ReadBinaryFile]] is most commonly used when you have a data file in a binary data format from another application, and need to access the internal bytes at particular locations. It can also be used in conjunction with [[WriteBinaryFile]] as a fast and convenient method to dump an Analytica array to a file and load it back in later.

The function [[GetFromBinaryData]] operates identically to [[ReadBinaryFile]], except that it reads from an in-memory binary data term rather than from a file. If you plan to run your model runs in ACP over the web, it is important to read the file into memory with one call, and then use [[GetFromBinaryData]] to read each item so that the user is asked to upload the file only once.

== Result Value(s) ==
These values are returned:
# The contents read.
# The full file path
# The offset where it left off reading. Useful if you want to read a different data structure that starts afterwards. (new to [[Analytica 6.4]]).

The main result returned is the contents it reads. This will either be an array indexed by the index(es) you specify in the «resultIndex» parameter, or a list of items if you omit the «resultIndex» parameter.

To capture one or both of the other result values, use:

:<code>[[Local]] ( content, path, nextOffset ) := [[ReadBinaryFile]](....)</code>

== Reading bytes ==
The usage
:<code>ReadBinaryFile(filename)</code>

returns the contents of the file as bytes, a list of integer values between 0 and 255.

== Reading N values ==
To limit the number of items read, pass an index to the «resultIndex» parameter having a length equal to the maximum number of items to read. The actual number read will be less if the end-of-file is reached. For example,

:<code>ReadBinaryFile(filename, resultIndex: I)</code>

== Parameters ==
==== filename ====
Name of file to read from.

File name paths can be either relative or absolute. An absolute path specifies the full path of the file from a root drive, such as
:<code>"C:\Users\Drice\Documents\Projects\FatigueAnalysis\Results.bin"</code>

A relative filename incompletely specifies a file path, and is interpreted relative to the [[CurrentDataDirectory]].

==== I... ====

The index(es) that you want as index(es) of the result. If you provide no index, it returns an unindexed list, so the variable calling ReadBinaryFile will appear as the index. If you provide multiple indexes, the last index listed vary fastest and first varies slowest as items are read.

The number of bytes to read depends on the product of the sizes of the indexes and the number of bytes per cell, which could vary if Bytesper parameter varies by one or more of the Indexes. If the total is less than the number of bytes in the file, it will read only the amount of data needed. If the total is more than the file size, it will pad out the excess cells with NULL.

If the indexes are in a different order in the file from the canonical order within Analytica, it reforms (transposes) the array to the internal form needed. If the amount of data is very large file (e.g. file has hundreds of MB), this reform process can be quite time-consuming.

==== bytesPer ====
Specifies the number of bytes per item read. For example, when you specify <code>bytesPer: 4</code>, then each 4 bytes becomes one cell of the result. When this is 1, then each byte is read and returned as a separate cell. Using 8 for «bytesPer» will result in the most memory-efficient encoding of contents when it is read into memory, since there is 8 times as much information per cell as would be the case for single bytes (and the bytes required per cell in memory would be the same in both cases).

When reading integer values (as is the default when «typeFlags» is omitted), this specifies the number of bytes per integer word, and can be 1 (for single bytes), 2 (for 16-bit words), 4 (for 32-bit integers) or 8 (for 64-bit integers).

When reading floating point real numbers, «bytesPer» can be 4 (for 32-bit IEEE 754 reals, often called '''''float'''''s), or 8 (for 64-bit IEEE 754 reals, often called '''''double'''''s). When «typeFlags» has <code>2</code> (floating point), the default for «bytesPer» is 8 if not specified.

For the «typeFlags» option of <code>3</code>, nine bytes per item are used, so you can either omit «bytesPer» or set it to 9. Any other value throws an error.

For the «typeFlags» option of <code>4</code>, the number of bytes per item may vary (depending on the length of text values), and so «bytesPer» must be omitted or an error will be issued.

==== typeFlags ====
Controls how each item read gets converted into a value.
:<code>0</code> = Unsigned integer (positive only)
:<code>1</code> = Signed integer (positive and negative numbers)
:<code>2</code> = IEEE 754 Floating point real
:<code>3</code> = Value (numbers, dates and null). 9 bytes per item.
:<code>4</code> = Value (including text{{Release|6.2|| or binary data}}). Variable bytes per text item.{{Release|6.2||
:<code>7</code> {{=}} Raw binary data.
:<code>8</code> {{=}} image}}
:<code>32</code> = Big endian flag.

You can say the one-byte integer with hex value 0xc1 is equal to 193, or you can say that it equals -133. The distinction here is whether you interpret the raw binary data as representing an unsigned integer (193) or a signed integer (-133). Signed integers use two's-complement so that both negative and positive values are within the possible range. Use <code>typeFlags: 0</code> when you want integers to be interpreted as unsigned, or <code>1</code> to include negative values. When «bytesPer» is 8, integers are read in as signed regardless.

A standard Intel convention writes numbers (integers or floating point values) with the least significant bytes written first, least significant bytes last, which is termed "little-endian format". This is the default assumed by [[WriteBinaryFile]] unless the <code>typeFlags = 32</code> flag is specified. "Big endian" means that the most significant byte is written first.

You can add the <code>32</code> "big endian" option to the data type selection. So, for example, a value of <code>2 + 32</code> would specify a floating point format (<code>2</code>) with the byte order reversed (<code>32</code>).

The Value type is a variant data type, in which a leading byte encodes the internal data type of the value, and followed by an 8-byte value. The «typeFlags» option of <code>3</code> only writes Analytica data types that can be fully encoded in with 8 bytes, which includes integers, fixed-point reals, floating point reals, date and date-time numbers, and the special value [[Null]]. When using this type, [[Null]] values ARE written to the file. The «typeFlags» option of <code>3</code> cannot be used to write text values, since these vary in length. The cells will each use 9 bytes, and will be spaced every 9 bytes in the file.

The «typeFlags» option of <code>4</code> extends option <code>3</code> by allowing text values{{Release|6.2|| or binary data}}. When a text value occurs, the first byte indicates that the value is text, the next four bytes encode the length, <code>n</code>, and the next <code>n</code> bytes encodes the characters in UTF-8. {{Release|6.2||When a binary data "blob" occurs, the first byte indicates the value in binary, the next 8 bytes specify the number of bytes, and then the next <code>n</code> bytes are the data.}} When this format is used, the «bytesPer» parameter must be omitted. The location of items in the file are not spaced at any predictable interval, since text items vary in length.

{{Release|6.2||The «typeFlags» option of 7 reads the next «bytesPer» bytes of the file into memory as a binary data term. When «bytesPer» is INF or omitted, the entire file is read. When «bytesPer» is specified and you haven't specified an index, it'll read a list of binary data terms of the given size. If you have specified and index, it'll read up to the index length binary data chunks. You can use this to read a binary file into memory, and then use [[GetFromBinaryData]] to perform multiple reads at different locations. This avoids extra overhead of opening and closing the file during each read. [[GetFromBinaryData]] has the same parameters as ReadBinaryFile, but reads from an in-memory binary term rather than from a binary file on disk.}}

==== offset ====
Specifies the file position to start reading from. Negative value specifies the distance (in bytes) from the end of the file, and a positive or zero value specifies the distance in bytes from the start of the file. You can use «offset» parameter to read data from a particular location inside the file.

When «offset» varies with the result index(es), you can use [[Null]] values in the «offset» array to indicate that the item resides directly after the previously read item. Hence, set to non-null integer values only for those items that start at a new offset.

It is likely you'll want to limit the number if items read to a maximum number. To do this, specify a result index. The length of the result index will be used as the maximum number of items read.

==== showDialog ====
This is a flag to force or suppress the file selector dialog. When not specified, the dialog only displays if needed, for example, if the file name is blank or the file doesn't exist. Setting «showDialog» to false suppresses the dialog from appearing. Setting «showDialog» to true forces the dialog to display, using «filename» as the initial default.

==== title ====
The text to use as caption of file selector dialog.

{{Release|1=7.1|2=|3=
==== extensionFilter ====
(''New in [[Analytica 7.1]]'') Overrides the file types offered in the file-selector dialog. Specify the filter(s) as a text in any of these forms:
* ''Display form'' — one or more filters separated by semicolons, each a description with its patterns in parentheses, e.g. <code>"Data Files (*.dat, *.bin); All Files (*.*)"</code>.
* ''A list of'' <code>"Description{{!}}patterns"</code> ''filters'' (description first, patterns separated by <code>;</code>), e.g. <code>["Data files{{!}}*.dat;*.bin", "All files{{!}}*.*"]</code>.
* ''Just patterns'', e.g. <code>"*.dat;*.bin"</code> (a description is generated automatically).
An <code>"All files (*.*)"</code> entry is appended automatically unless your list already includes one. When omitted, the default file types are shown.
}}

== Examples ==

=== Fast Writing and reading of Analytica arrays ===

[[WriteBinaryFile]]() and [[ReadBinaryFile]]() are the fastest ways to write data from a model to a file or read from a file, because the numeric data does not need to be converted to text when writing or parsed when reading.

Assume: <code>a</code> is an array indexed by indexes <code>I, J, K</code>, and <code>l</code>. Assume also that it contains only numbers, dates and null values -- no text, [[handles]], [[references]], etc.

Write the array to the file:
: <code>[[WriteBinaryFile]]("a.dat", a, I,J,K,L, bytesPer:12, typeFlags:3 )</code>

Read the array back in:
:<code>[[ReadBinaryFile]]("a.dat", bytesPer:12, typeFlags:3, resultIndex: I, J, K, L )</code>

=== Reading a complex binary structure ===

Binary Shape files (*.shp) and Shape index files (*.shx) have the following header layout for their first 100 bytes:
::[[image:SHP_file_header_layout.png]]

To read this, create an index for the items of the header:
:Index Header_item := <code>['File Code','Unused','Unused','Unused','Unused','Unused','File length','Version','Shape type','Xmin','Ymin','Xmax','Ymax','Zmin','Zmax','Mmin','Mmax']</code>

The bytes per item varies:
:Variable BytesPerItem := <code>Table(Header_item)(4,4,4,4,4,4,4,4,4,8,8,8,8,8,8,8,8)</code>

A big-endian (positive) integer is «typeFlag» 32, a little-endian integer is 0, and a little-endian double is 2. So the item types are:
:Variable ItemType := <code>Table(Header_item)(32,32,32,32,32,32,32,0,0,2,2,2,2,2,2,2,2)</code>

The full header is then read using:
:<code>[[ReadBinaryFile]]("filename.shx", bytesPer: BytesPerItem, typeFlags:itemType, resultIndex: Header_item )</code>

The following model embellishes this with a user-interface for selecting the items in a general binary data record and using this to read the structure. For complex binary structures, this may simplify the coding.
::[[image:shx_read_binary_UI.png]]
* '''Model file: ''' [[media:Reading binary data file.ana|Reading binary data file.ana]]
* '''Try the model with this binary data file: ''' [[file:NHDWaterbody.shx|NHDWaterbody.shx]]

{{Release|6.2||
== From ACP ==
By specifying a blank filename, or a filename that you know does not exist on the server, ACP will display a file selector dialog on the user's browser, asking her to select a file for upload.

This can be utilized to upload an arbitrary file type to disk, since you can use this to upload the file into memory (by setting «typeFlags» to 7), and then using WriteBinaryFile to save it to the server's disk (again, setting «typeFlags» to 7). This trick can be utilized to upload a spreadsheet when using [[LibXL]] for reading spreadsheet data where Excel is not installed on the server, as is the case on Lumina's public ACP server. For security reasons, Excel is not installed on Lumina's public ACP server.}}

== From ADE ==
When evaluated in the [[ADE|Analytica Decision Engine (ADE)]] and a dialog needs to be shown to the end-user, it calls [[IAdeUICallbacks::GetFilename]](...). From within that callback, the parent application can interact with the end-user to resolve the file path, and a web applications can instruct the end-user to upload a file. Once complete, the callback returns the full path to the file which is then read. To receive this callback, the parent application must have previously registered the callback with ADE using [[CAEngine::SetCallbackObject]]( ).

Once the file read completes, it calls [[IAdeUICallbacks::FileOpenCompleted]]().

== See Also ==
<div style="column-count:2;-moz-column-count:2;-webkit-column-count:2">
* [[In-memory binary data terms]]
* [[Binary and hexadecimal integer formats]]
* [[ReadTextFile]]
* [[WriteBinaryFile]]
* [[GetFromBinaryData]]
* [[Dec2Bin]]
* [[Hex2Bin]]
* [[Bin2Dec]]
* [[Bin2Hex]]
* [[BitAnd]]
* [[BitOr]]
* [[BitXOr]]
* [[BitNot]]
* [[BitShift]] -- these can be useful when you need to manipulate the bytes of multi-byte integers that you read.
</div>

ReadBinaryFile

2026-06-29T19:48:27Z

Lchrisman: Add extensionFilter to signature (new in 7.1, ER 20237)

[[category:Database Functions]]
[[category:System Functions]]
[[category:File system functions]]
{{ReleaseBar}}

''Requires [[Analytica 5.0]] {{Developer}} or higher''

== ReadBinaryFile(filename'', bytesPer, typeFlags, offset, resultIndex..., showDialog, title{{Release|7.1||, extensionFilter}}'') ==

Reads data directly from a binary (i.e., non-text) file.

Flat data files are usually read using [[ReadTextFile]]. When you read text files, end-of-line characters are interpreted in various ways for you, conversions from character sets such as UTF-8 or Unicode may occur, and certain special byte values such as the zero byte or end-of-file cannot occur in the file. In contrast, reading from a binary file gives you access to the bytes of the file exactly as they appear.

[[ReadBinaryFile]] is most commonly used when you have a data file in a binary data format from another application, and need to access the internal bytes at particular locations. It can also be used in conjunction with [[WriteBinaryFile]] as a fast and convenient method to dump an Analytica array to a file and load it back in later.

The function [[GetFromBinaryData]] operates identically to [[ReadBinaryFile]], except that it reads from an in-memory binary data term rather than from a file. If you plan to run your model runs in ACP over the web, it is important to read the file into memory with one call, and then use [[GetFromBinaryData]] to read each item so that the user is asked to upload the file only once.

== Result Value(s) ==
These values are returned:
# The contents read.
# The full file path
# The offset where it left off reading. Useful if you want to read a different data structure that starts afterwards. (new to [[Analytica 6.4]]).

The main result returned is the contents it reads. This will either be an array indexed by the index(es) you specify in the «resultIndex» parameter, or a list of items if you omit the «resultIndex» parameter.

To capture one or both of the other result values, use:

:<code>[[Local]] ( content, path, nextOffset ) := [[ReadBinaryFile]](....)</code>

== Reading bytes ==
The usage
:<code>ReadBinaryFile(filename)</code>

returns the contents of the file as bytes, a list of integer values between 0 and 255.

== Reading N values ==
To limit the number of items read, pass an index to the «resultIndex» parameter having a length equal to the maximum number of items to read. The actual number read will be less if the end-of-file is reached. For example,

:<code>ReadBinaryFile(filename, resultIndex: I)</code>

== Parameters ==
==== filename ====
Name of file to read from.

File name paths can be either relative or absolute. An absolute path specifies the full path of the file from a root drive, such as
:<code>"C:\Users\Drice\Documents\Projects\FatigueAnalysis\Results.bin"</code>

A relative filename incompletely specifies a file path, and is interpreted relative to the [[CurrentDataDirectory]].

==== I... ====

The index(es) that you want as index(es) of the result. If you provide no index, it returns an unindexed list, so the variable calling ReadBinaryFile will appear as the index. If you provide multiple indexes, the last index listed vary fastest and first varies slowest as items are read.

The number of bytes to read depends on the product of the sizes of the indexes and the number of bytes per cell, which could vary if Bytesper parameter varies by one or more of the Indexes. If the total is less than the number of bytes in the file, it will read only the amount of data needed. If the total is more than the file size, it will pad out the excess cells with NULL.

If the indexes are in a different order in the file from the canonical order within Analytica, it reforms (transposes) the array to the internal form needed. If the amount of data is very large file (e.g. file has hundreds of MB), this reform process can be quite time-consuming.

==== bytesPer ====
Specifies the number of bytes per item read. For example, when you specify <code>bytesPer: 4</code>, then each 4 bytes becomes one cell of the result. When this is 1, then each byte is read and returned as a separate cell. Using 8 for «bytesPer» will result in the most memory-efficient encoding of contents when it is read into memory, since there is 8 times as much information per cell as would be the case for single bytes (and the bytes required per cell in memory would be the same in both cases).

When reading integer values (as is the default when «typeFlags» is omitted), this specifies the number of bytes per integer word, and can be 1 (for single bytes), 2 (for 16-bit words), 4 (for 32-bit integers) or 8 (for 64-bit integers).

When reading floating point real numbers, «bytesPer» can be 4 (for 32-bit IEEE 754 reals, often called '''''float'''''s), or 8 (for 64-bit IEEE 754 reals, often called '''''double'''''s). When «typeFlags» has <code>2</code> (floating point), the default for «bytesPer» is 8 if not specified.

For the «typeFlags» option of <code>3</code>, nine bytes per item are used, so you can either omit «bytesPer» or set it to 9. Any other value throws an error.

For the «typeFlags» option of <code>4</code>, the number of bytes per item may vary (depending on the length of text values), and so «bytesPer» must be omitted or an error will be issued.

==== typeFlags ====
Controls how each item read gets converted into a value.
:<code>0</code> = Unsigned integer (positive only)
:<code>1</code> = Signed integer (positive and negative numbers)
:<code>2</code> = IEEE 754 Floating point real
:<code>3</code> = Value (numbers, dates and null). 9 bytes per item.
:<code>4</code> = Value (including text{{Release|6.2|| or binary data}}). Variable bytes per text item.{{Release|6.2||
:<code>7</code> {{=}} Raw binary data.
:<code>8</code> {{=}} image}}
:<code>32</code> = Big endian flag.

You can say the one-byte integer with hex value 0xc1 is equal to 193, or you can say that it equals -133. The distinction here is whether you interpret the raw binary data as representing an unsigned integer (193) or a signed integer (-133). Signed integers use two's-complement so that both negative and positive values are within the possible range. Use <code>typeFlags: 0</code> when you want integers to be interpreted as unsigned, or <code>1</code> to include negative values. When «bytesPer» is 8, integers are read in as signed regardless.

A standard Intel convention writes numbers (integers or floating point values) with the least significant bytes written first, least significant bytes last, which is termed "little-endian format". This is the default assumed by [[WriteBinaryFile]] unless the <code>typeFlags = 32</code> flag is specified. "Big endian" means that the most significant byte is written first.

You can add the <code>32</code> "big endian" option to the data type selection. So, for example, a value of <code>2 + 32</code> would specify a floating point format (<code>2</code>) with the byte order reversed (<code>32</code>).

The Value type is a variant data type, in which a leading byte encodes the internal data type of the value, and followed by an 8-byte value. The «typeFlags» option of <code>3</code> only writes Analytica data types that can be fully encoded in with 8 bytes, which includes integers, fixed-point reals, floating point reals, date and date-time numbers, and the special value [[Null]]. When using this type, [[Null]] values ARE written to the file. The «typeFlags» option of <code>3</code> cannot be used to write text values, since these vary in length. The cells will each use 9 bytes, and will be spaced every 9 bytes in the file.

The «typeFlags» option of <code>4</code> extends option <code>3</code> by allowing text values{{Release|6.2|| or binary data}}. When a text value occurs, the first byte indicates that the value is text, the next four bytes encode the length, <code>n</code>, and the next <code>n</code> bytes encodes the characters in UTF-8. {{Release|6.2||When a binary data "blob" occurs, the first byte indicates the value in binary, the next 8 bytes specify the number of bytes, and then the next <code>n</code> bytes are the data.}} When this format is used, the «bytesPer» parameter must be omitted. The location of items in the file are not spaced at any predictable interval, since text items vary in length.

{{Release|6.2||The «typeFlags» option of 7 reads the next «bytesPer» bytes of the file into memory as a binary data term. When «bytesPer» is INF or omitted, the entire file is read. When «bytesPer» is specified and you haven't specified an index, it'll read a list of binary data terms of the given size. If you have specified and index, it'll read up to the index length binary data chunks. You can use this to read a binary file into memory, and then use [[GetFromBinaryData]] to perform multiple reads at different locations. This avoids extra overhead of opening and closing the file during each read. [[GetFromBinaryData]] has the same parameters as ReadBinaryFile, but reads from an in-memory binary term rather than from a binary file on disk.}}

==== offset ====
Specifies the file position to start reading from. Negative value specifies the distance (in bytes) from the end of the file, and a positive or zero value specifies the distance in bytes from the start of the file. You can use «offset» parameter to read data from a particular location inside the file.

When «offset» varies with the result index(es), you can use [[Null]] values in the «offset» array to indicate that the item resides directly after the previously read item. Hence, set to non-null integer values only for those items that start at a new offset.

It is likely you'll want to limit the number if items read to a maximum number. To do this, specify a result index. The length of the result index will be used as the maximum number of items read.

==== showDialog ====
This is a flag to force or suppress the file selector dialog. When not specified, the dialog only displays if needed, for example, if the file name is blank or the file doesn't exist. Setting «showDialog» to false suppresses the dialog from appearing. Setting «showDialog» to true forces the dialog to display, using «filename» as the initial default.

==== title ====
The text to use as caption of file selector dialog.

== Examples ==

=== Fast Writing and reading of Analytica arrays ===

[[WriteBinaryFile]]() and [[ReadBinaryFile]]() are the fastest ways to write data from a model to a file or read from a file, because the numeric data does not need to be converted to text when writing or parsed when reading.

Assume: <code>a</code> is an array indexed by indexes <code>I, J, K</code>, and <code>l</code>. Assume also that it contains only numbers, dates and null values -- no text, [[handles]], [[references]], etc.

Write the array to the file:
: <code>[[WriteBinaryFile]]("a.dat", a, I,J,K,L, bytesPer:12, typeFlags:3 )</code>

Read the array back in:
:<code>[[ReadBinaryFile]]("a.dat", bytesPer:12, typeFlags:3, resultIndex: I, J, K, L )</code>

=== Reading a complex binary structure ===

Binary Shape files (*.shp) and Shape index files (*.shx) have the following header layout for their first 100 bytes:
::[[image:SHP_file_header_layout.png]]

To read this, create an index for the items of the header:
:Index Header_item := <code>['File Code','Unused','Unused','Unused','Unused','Unused','File length','Version','Shape type','Xmin','Ymin','Xmax','Ymax','Zmin','Zmax','Mmin','Mmax']</code>

The bytes per item varies:
:Variable BytesPerItem := <code>Table(Header_item)(4,4,4,4,4,4,4,4,4,8,8,8,8,8,8,8,8)</code>

A big-endian (positive) integer is «typeFlag» 32, a little-endian integer is 0, and a little-endian double is 2. So the item types are:
:Variable ItemType := <code>Table(Header_item)(32,32,32,32,32,32,32,0,0,2,2,2,2,2,2,2,2)</code>

The full header is then read using:
:<code>[[ReadBinaryFile]]("filename.shx", bytesPer: BytesPerItem, typeFlags:itemType, resultIndex: Header_item )</code>

The following model embellishes this with a user-interface for selecting the items in a general binary data record and using this to read the structure. For complex binary structures, this may simplify the coding.
::[[image:shx_read_binary_UI.png]]
* '''Model file: ''' [[media:Reading binary data file.ana|Reading binary data file.ana]]
* '''Try the model with this binary data file: ''' [[file:NHDWaterbody.shx|NHDWaterbody.shx]]

{{Release|6.2||
== From ACP ==
By specifying a blank filename, or a filename that you know does not exist on the server, ACP will display a file selector dialog on the user's browser, asking her to select a file for upload.

This can be utilized to upload an arbitrary file type to disk, since you can use this to upload the file into memory (by setting «typeFlags» to 7), and then using WriteBinaryFile to save it to the server's disk (again, setting «typeFlags» to 7). This trick can be utilized to upload a spreadsheet when using [[LibXL]] for reading spreadsheet data where Excel is not installed on the server, as is the case on Lumina's public ACP server. For security reasons, Excel is not installed on Lumina's public ACP server.}}

== From ADE ==
When evaluated in the [[ADE|Analytica Decision Engine (ADE)]] and a dialog needs to be shown to the end-user, it calls [[IAdeUICallbacks::GetFilename]](...). From within that callback, the parent application can interact with the end-user to resolve the file path, and a web applications can instruct the end-user to upload a file. Once complete, the callback returns the full path to the file which is then read. To receive this callback, the parent application must have previously registered the callback with ADE using [[CAEngine::SetCallbackObject]]( ).

Once the file read completes, it calls [[IAdeUICallbacks::FileOpenCompleted]]().

== See Also ==
<div style="column-count:2;-moz-column-count:2;-webkit-column-count:2">
* [[In-memory binary data terms]]
* [[Binary and hexadecimal integer formats]]
* [[ReadTextFile]]
* [[WriteBinaryFile]]
* [[GetFromBinaryData]]
* [[Dec2Bin]]
* [[Hex2Bin]]
* [[Bin2Dec]]
* [[Bin2Hex]]
* [[BitAnd]]
* [[BitOr]]
* [[BitXOr]]
* [[BitNot]]
* [[BitShift]] -- these can be useful when you need to manipulate the bytes of multi-byte integers that you read.
</div>

ReadTextFile

2026-06-29T19:44:37Z

Lchrisman: Document extensionFilter parameter (new in 7.1, ER 20237)

[[category:System Functions]]
[[category:Database Functions]]
[[category:File system functions]]

{{ReleaseBar}}

''(Requires Analytica {{Developer}}, Optimizer, or Power Player)''

== ReadTextFile(filename, ''showDialog, title{{Release|7.1||, extensionFilter}}'') ==

Returns the contents a text file «filename» as a text value. «filename» may be the name of a file in the [[CurrentDataDirectory|Current Data Directory]] (initially, the directory containing the model), or a path relative to the [[CurrentDataDirectory|Current Data Directory]] , or an absolute pathname.

If it can't find a file with that name, by default, it opens a file browser dialog to let the user select another file. Set optional parameter, «showDialog» to <code>True</code> (1) to show the file browser dialog, using «filename» as default, even if the file exists. Set «showDialog» to <code>False</code> (0) to never show it. If it can't find the file, it shows an error message.

You can specify the caption for the title bar of the file browser dialog titlebar in the optional «title» parameter.

{{Release|1=7.1|2=|3=
«extensionFilter»: (Optional) Overrides the file types offered in the file-selector dialog. Specify the filter(s) as a text in any of these forms:
* ''Display form'' — one or more filters separated by semicolons, each a description with its patterns in parentheses, e.g. <code>"Text Files (*.txt); CSV Files (*.csv); All Files (*.*)"</code>.
* ''A list of'' <code>"Description{{!}}patterns"</code> ''filters'' (description first, patterns separated by <code>;</code>), e.g. <code>["Text files{{!}}*.txt;*.csv", "All files{{!}}*.*"]</code>.
* ''Just patterns'', e.g. <code>"*.txt;*.csv"</code> (a description is generated automatically).
An <code>"All files (*.*)"</code> entry is appended automatically unless your list already includes one. When omitted, the default file types are shown.
}}

[[ADE]] never shows the file browser dialog, no matter what the parameter values.

== Treating End-of-line ==
There are three common standards in text-files to identify newlines:
* Windows files usually use the two-character sequence CRLF -- [[Chr]](10) [[Chr]](13)
* Unix files use a single LF character -- [[Chr]](10)
* Macintosh OS files use a single CR character -- [[Chr]](13)

Occasional Windows-based programs use one of the other standards.

ReadTextFile insulates you from worrying about which standard is used by converting each to the Unix standard, a single LF -- [[Chr]](10).

If a file contains inconsistent line breaks -- e.g. including more than one examples of LF, CRLF, and CR -- it converts LF and CRLF to a single LF, and leaves CR -- Chr(13) -- as is.

== Getting the file name actually opened ==
Your code may want to know the file path for which file was actually opened. This may differ from «filename» when the specified file is not found, or when «showDialog» forces a dialog, allowing the user to select a different file. [[ReadTextFile]] returns the file path as a second return value, which you can optionally capture using, e.g.,

:<code>[[Local]] (contents, filepath) := [[ReadTextFile]]( ... );</code>

A common pattern is that you may want to save the filename in a variable such that when the evaluation is repeated in the future, it can supply the file selected by the user to the «filename» parameter. This can be coded by supplying first a global variable to hold the filename defined using [[ComputedBy]] with the default filename as follows:

:Variable TheFilename ::=
::<code>[[ComputedBy]]( TheFileContetns, "defaultFilename" ) </code>

:Variable TheFileContents ::=
::<code>( , TheFilename ) := [[ReadTextFile]]( TheFilename )</code>

The assignment to <code>( , TheFilename )</code> passes through the first parameter as the result of the assignment expression, but assigns the second return value the <code>TheFilename</code>. The assignment to <code>TheFilename</code> is a [[side-effect]] that is allowed only because <code>TheFilename</code> is defined as a [[ComputedBy]]. The assignment changes the value, but also rewrites the second parameter of the call to [[ComputedBy]], thus permanently preserving the filename selected. The one line definition of <code>TheFileContents</code> is locally equivalent to:

:<code>[[Local]] (contents, filename ) := [[ReadTextFile]]( TheFilename );</code>
:<code>TheFilename := filename;</code>
:<code>contents</code>

{{Release|1=6.6|2=|3=
== Getting the file encoding ==
(''New in [[Analytica 6.6]]'')
A text file may include a Byte Mark Encoding (BOM) as the first few characters of the file. This can be captured as the fourth return value and will have one the the values:
* [[Null]] : No BOM. Presumed to be ASCII.
* <code>'UTF-8'</code>: Each character uses a variable number of bytes, from 1-6 depending on the character.
* <code>'UTF-16be'</code>: 2 bytes per character, big-endian.
* <code>'UTF-16le'</code>: 2 bytes per character, little-endian

Example of capturing the encoding:
:<code>[[Local]] ( contents, filepath, isUploaded, encoding ) := [[ReadTextFile]]( filename );</code>
}}
== From ADE ==
When evaluated in [[ADE|the Analytica Decision Engine (ADE)]] and a dialog needs to be shown to the end-user, it calls [[IAdeUICallbacks::GetFilename]](...). From within that callback, the parent application can interact with the end-user to resolve the file path, and a web applications can instruct the end-user to upload a file. Once complete, the callback returns the full path to the file which is then read. To receive this callback, the parent application must have previously registered the callback with ADE using [[CAEngine::SetCallbackObject]]( ). If it has not registered a callback and the file doesn't exist, returns an empty text.

Once the file read completes, it calls [[IAdeUICallbacks::FileOpenCompleted]]().

== History ==
* The «title» parameter was introduced in [[Analytica 4.6]].

* The callback in ADE was introduced in [[Analytica 4.6|ADE 4.6]].

* The «extensionFilter» parameter was introduced in [[Analytica 7.1]].

== See Also ==
* [[WriteTextFile]]
* [[Read and write text files]]
* [[Text functions]]
* [[ParseCSV]]
* [[ParseJSON]]
* [[ReadFromUrl]]
* [[ReadImageFile]]
* [[ReadExportFile]]
* [[ReadBinaryFile]]
* [[Model File Character Encoding]]
* [[Chr]]
* [[CurrentDataFolder]]
* [[NumberToText]]
* [[Files and Editing]]
* [[Returning multiple values]]

WriteTextFile

2026-06-29T19:35:52Z

Lchrisman: Document extensionFilter parameter (new in 7.1, ER 20237)

[[category:System Functions]]
[[category:Database Functions]]
[[category:File system functions]]
[[Category:Doc Status D]] 

{{ReleaseBar}}

== WriteTextFile(filename, text'', append, warn, sep, showDialog, encoding{{Release|6.0||, download}}{{Release|7.1||, extensionFilter}}'') ==

Write «text» value to a file with name «filename».

=== Optional parameters ===

«append»: Default <code>False</code>. If the file exists and «append» is <code>True</code>, it appends the text to the end of the file. If it doesn't exist and «warn» is <code>True</code> , it asks whether to create the file.

«warn»: Default <code>True</code>. If «warn» is <code>False</code>, it suppresses the warning that the file already exists when «append» is false or that it does not exist when «append» is True.

«showDialog»: Default <code>Undefined</code> -- i.e. it shows a file browser dialog only if the indicated filename is a folder, a read-only file, or if it exists and «warn» is <code>True</code>, or if it does not exist and «append» is <code>True</code>. When «showDialog» is <code>True</code>, it always opens a dialog before with file name as the default to let the user change file name or folder. When <code>False</code>, it never shows a dialog but may generate an error when trying to overwrite an existing file with «append» False.

«sep»: (Default is a new line.) Character to use as a separator between elements when «text» is an array.

«encoding» (Default <code>"ANSI"</code>.) Specifies how to encode characters in the file:
* <code>"ANSI"</code> : One byte per character, [http://en.wikipedia.org/wiki/8859 ISO-8859-1]. Extended characters (above ascii 255) are written as ?.
* <code>"UTF-8"</code> : [http://en.wikipedia.org/wiki/UTF-8 UTF-8 encoding] with a [http://en.wikipedia.org/wiki/Byte_order_mark byte order mark] ([http://en.wikipedia.org/wiki/Byte_order_mark BOM]). The UTF-8 encoding uses one byte for comman characters, and 2-3 bytes for characters with ascii values above 127.
*<code> "-UTF-8"</code> : [http://en.wikipedia.org/wiki/UTF-8 UTF-8 encoding] without a BOM.
* <code>"UTF-16"</code> : Two bytes per character, big endian, with BOM.
* <code>"UTF-16le"</code> : Two bytes per character, little endian, with BOM.

{{Release|6.0||
«download»: This is only used when running the model in [[ACP]]. When set to <code>True</code>, the «text» is downloaded onto the end-user's computer as a text file with the given «filename». }}

{{Release|1=7.1|2=|3=
«extensionFilter»: (Optional) Overrides the file types offered in the file-selector dialog. Specify the filter(s) as a text in any of these forms:
* ''Display form'' — one or more filters separated by semicolons, each a description with its patterns in parentheses, e.g. <code>"Text Files (*.txt); CSV Files (*.csv); All Files (*.*)"</code>.
* ''A list of'' <code>"Description{{!}}patterns"</code> ''filters'' (description first, patterns separated by <code>;</code>), e.g. <code>["Text files{{!}}*.txt;*.csv", "All files{{!}}*.*"]</code>.
* ''Just patterns'', e.g. <code>"*.txt;*.csv"</code> (a description is generated automatically).
An <code>"All files (*.*)"</code> entry is appended automatically unless your list already includes one. When omitted, the default file types are shown.
}}

==History==
Introduced in [[What's new in Analytica 4.0?|Analytica 4.0]].

«encoding» parameter introduced in [[Analytica 4.5]].

«download» parameter introduced in [[Analytica 6.0]].

«extensionFilter» parameter introduced in [[Analytica 7.1]].

== See also ==
* [[ReadTextFile]]
* [[Read and write text files]]
* [[MakeCSV]]
* [[MakeJSON]]
* [[Text functions]]
* [[WriteBinaryFile]]
* [[CurrentDataFolder]]
* [[Model File Character Encoding]]
* [[Files and Editing]]

MakeJSON

2026-06-25T14:20:01Z

Lchrisman: Correct flag 512 polarity to opt-out (base64 is the default; setting 512 keeps the legacy «Picture» placeholder), matching the code

[[category:Text Functions]]
[[category:Analytica 5.0]]
{{ReleaseBar}}
''New to [[Analytica 5.0]]''

{{Release|1=|2=6.5|3=''This function requires the {{Analytica Developer}} edition or higher (i.e., higher editions are [[Analytica Optimizer Guide|Analytica Optimizer]], [[Analytica Decision Engine|ADE]] or [http://Cubeplan.com CubePlan]]).''}}

== MakeJSON( x'', indexOrder, objects, flags{{Release|7.1||, maxCells}}'' ) ==

Returns text in [http://json.org JavaScript Object Notation (JSON)]] format representing the data in «x». When there are multidimensional arrays, you can control the nesting order in the JSON text by specifying the indexes in the «indexOrder» parameter. When some indexes encode the member names of a JavaScript object, you should list those indexes in «objects». The optional «flags» parameter accepts an integer that encodes a bit-field of options, with these options.
* 1 = Don't infer that 1-D arrays with textual indexes are objects.
* 2 = reserved. Must be 0. 
* 4 = reserved. Should be 0. 
* 8 = Top-level element in the result can be a non-object.
* 16 = Allow ragged arrays.{{Release|6.4||
* 32 {{=}} Don't include fields that have a [[Null]] value.}}{{Release|6.5||
* 64 {{=}} Prepend a dot to local index identifier text values.}}{{Release|7.0||
* 128 {{=}} Allow preformatted JSON. Reference to text gets inserted verbatim.}}{{Release|7.1||
* 256 {{=}} Escape CR as \r. Without the flag, it escapes as \n as generally required in JavaScript.}}{{Release|1=7.1|2=|3=
* 512 = Don't encode picture or binary-image data as base64 -- keep the legacy <code>"«Picture (PNG)»"</code> placeholder instead. Without this flag (the default), such data is emitted in a base64 form such as <code>{"width":16, "height":16, "mime":"image/png", "base64":"iVBOR...."}</code>.
* 1024 = Don't encode binary (non-image) data as base64. Without this flag (the default), binary data is emitted as <code>{"binary":true, "base64":"..."}</code> JSON objects.}}

{{Release|7.1||The optional «maxCells» parameter limits how large an array may be before its contents are written out. When the total number of cells in an array -- the product of the lengths of all its indexes, across every dimension -- exceeds «maxCells», that array's elements are not serialized; instead a JSON object naming the array's true shape is emitted in its place:
:<code>{"$truncated":true, "cells":''N'', "maxCells":''M'', "dimensions":[{"index":"''I''", "size":''n''}, ...]}</code>
A positional or implicit index appears as <code>"index":null</code>. This guards against accidentally serializing an unintentionally enormous array (for example, millions of cells produced by a mistaken expression) into a huge JSON string. When «maxCells» is omitted, there is no limit.}}

=== JSON Objects vs. Arrays ===

Consider the following array in Variable <code>Biblio1984</code>
:[[image:MakeJSON_Biblio1984.png]]

One way to encode this is JSON is an a JSON object.
:<code>[[MakeJSON]]( Biblio1984, objects: Biblio )</code> →
:::<code>'{"title": "1984", "author": "George Orwell", "year": 1949, "pages": 336, "paperback": 1}'</code>

A second way to encode the same array data is an a JSON array.
:<code>[[MakeJSON]]( Biblio1984, indexOrder:Biblio, flags:9 )</code> →
:::<code>'["1984", "George Orwell", 1949, 336, 1]'</code>
Because the top-most item in JSON text is supposed to a JSON object, this second example isn't strictly valid (the «flags»=8 option was required for this reason). But for information anywhere other than the outermost dimension of «x», the fact remains that the data in an Analytica array can be placed in either form -- JSON-object or JSON-array.

For any index in your data, you can make it explicit by listing the index in the «objects» parameter if you want it to produce a JSON object, or in the «indexOrder» parameter if you want it to produce a JSON-array for that index. When you don't set the «flags»=8 bit, one index will be selected as an object index, even if they are all listed in «indexOrder», just because JSON text is supposed to have the root be an object.

When «x» contains an index that you have not explicitly listed, it will infer that it should be an object when the «flags»=1 is not set, the array is 1-D, and the index has textual member names. Otherwise it will output it as an array without the index labels.

=== Index order ===

When an Analytica array has more that one-dimension, you should list the indexes in «indexOrder», with the index that should vary most slowly listed first. For example:

Index I := <code>1..4</code>
Index J := <code>1..3</code>
Index K := <code>['k1', 'k2']</code>
Variable z1 := <code>10 * J + @K</code>
Variable z2 := <code>100*I + @K</code>
Index Struct := <code>['z1', 'z2']</code>
Variable data1 := [[Table]](Struct)( \z1, \z2 )

You should think of <code>data1</code> as being like an instantiation of a class named <code>Struct</code>, which has two members <code>z1</code> and <code>z2</code>. The <code>z1</code> member of <code>data1</code> has a 2-D array indexed by <code>J, K</code>, and <code>z2</code> has a 2-D array indexed by <code>I, K</code>.

If you don't specify the index order, you can't reliably predict which nesting you will get.
[[MakeJSON]]( data1 ) →
{ "z1": [[11, 12], [21, 22], [31, 32]],
"z2": [[101, 201, 301, 401], [102, 202, 302, 402]]
}
Note: [[MakeJSON]] does not insert newlines or indents. The result was formatted above manually.

It may be that the application code receiving this expects the data to be in <code>K</code>-major order. In the above, <code>z2</code> was as desired, but <code>z1</code> was transposed. To ensure this, you need to specify the «indexOrder».
[[MakeJSON]]( data1, indexOrder: K, J, I ) →
{ "z1": [[11, 21, 31], [12, 22, 32]],
"z2": [[101, 201, 301, 401], [102, 202, 302, 402]]
}

When you list multiple indexes in the «objects» parameter, this also constrains the order, where the first index listed becomes the outer object. For example, given the following Analytica array
:[[image:MakeJSON_cat_dog.png]]
listing <code>Animal</code> before <code>Sex</code> in «objects» creates nested objects as follows
:<code>[[MakeJSON]](Counts, objects:Animal,Sex)→{"cat": {"Male": 12, "Female": 8}, "dog": {"Male": 4, "Female": 5}}</code>
but listing them in the opposite order reverses the object nesting
:<code>[[MakeJSON]](Counts, objects:Sex,Animal)→{"Male": {"cat": 12, "dog": 4}, "Female": {"cat": 8, "dog": 5}}</code>

=== Mixed objects and arrays ===
(These rules apply to [[Analytica 5.2]]. Before that, it isn't legit to have object & array dimensions mixed for single arrays -- instead, you should use references to structure your object structures).

When a multi-dimensional array is transcribed into JSON at any level (each time there is a reference, you have a new multi-dimensional array to consider), each index of that array will be transcribed either as a JSON array or as a JSON object (i.e., either using brackets [ ] or using braces { } ). By using the «indexOrder» and «objects» parameters, you have control over which way each index is treated, as well as the nesting order. You could, for example, end up with an array of JSON objects, or a JSON object containing arrays for each member.

The rules for selecting whether an index is treated as an JSON object or JSON array is as follows:
* An index listed in «objects» will be transcribed as an object.
* When the array is 1-D and <code>flags:1</code> is not set and the index labels are textual, an index not listed in «indexOrder_» is treated as an object.
* When <code>flags:8</code> is not set, the very first index of the entire JSON is an object.
* Otherwise, it is transcribed as an array.

The rules for determining nesting order are as follows:
* If index I appears before index J in the «indexOrder» parameter, then J will be nested inside I.
* If index I appears before index J in the «objects» parameter, then J will be nested inside I.
* When two indexes aren't explicitly ordered in one of the two parameters, objects are nested inside array dimensions (i.e., objects moved inward, array dimensions moved outward), so you'll end up with arrays of objects.
* Finally, Analytica's internal canonical ordering is used. Since this is internal to Analytica, this is essentially an arbitrary ordering.

When you need to specify the nesting order between a JSON-array and a JSON-object dimension, list both corresponding indexes in the «indexOrder» parameter and list the index for the object in the «objects» parameter.

== See Also ==
* [[ParseJSON]]
* [[MakeCSV]]
* [[WriteTextFile]]
* [[JoinText]], [[NumberToText]]

MakeJSON

2026-06-25T00:24:28Z

Lchrisman: Document flag 1024 (opt out of base64 encoding for binary data; keeps the legacy placeholder)

[[category:Text Functions]]
[[category:Analytica 5.0]]
{{ReleaseBar}}
''New to [[Analytica 5.0]]''

{{Release|1=|2=6.5|3=''This function requires the {{Analytica Developer}} edition or higher (i.e., higher editions are [[Analytica Optimizer Guide|Analytica Optimizer]], [[Analytica Decision Engine|ADE]] or [http://Cubeplan.com CubePlan]]).''}}

== MakeJSON( x'', indexOrder, objects, flags{{Release|7.1||, maxCells}}'' ) ==

Returns text in [http://json.org JavaScript Object Notation (JSON)]] format representing the data in «x». When there are multidimensional arrays, you can control the nesting order in the JSON text by specifying the indexes in the «indexOrder» parameter. When some indexes encode the member names of a JavaScript object, you should list those indexes in «objects». The optional «flags» parameter accepts an integer that encodes a bit-field of options, with these options.
* 1 = Don't infer that 1-D arrays with textual indexes are objects.
* 2 = reserved. Must be 0. 
* 4 = reserved. Should be 0. 
* 8 = Top-level element in the result can be a non-object.
* 16 = Allow ragged arrays.{{Release|6.4||
* 32 {{=}} Don't include fields that have a [[Null]] value.}}{{Release|6.5||
* 64 {{=}} Prepend a dot to local index identifier text values.}}{{Release|7.0||
* 128 {{=}} Allow preformatted JSON. Reference to text gets inserted verbatim.}}{{Release|7.1||
* 256 {{=}} Escape CR as \r. Without the flag, it escapes as \n as generally required in JavaScript.}}{{Release|1=7.1|2=|3=
* 512 = Encode images in a base64 form such as <code>{"width":16, "height":16, "mime":"image/png", "base64":"iVBOR...."}</code>. Without this they appear as <code>"«Picture (PNG)»"</code>.
* 1024 = Don't encode binary (non-image) data as base64. Without this flag (the default), binary data is emitted as <code>{"binary":true, "base64":"..."}</code> JSON objects.}}

{{Release|7.1||The optional «maxCells» parameter limits how large an array may be before its contents are written out. When the total number of cells in an array -- the product of the lengths of all its indexes, across every dimension -- exceeds «maxCells», that array's elements are not serialized; instead a JSON object naming the array's true shape is emitted in its place:
:<code>{"$truncated":true, "cells":''N'', "maxCells":''M'', "dimensions":[{"index":"''I''", "size":''n''}, ...]}</code>
A positional or implicit index appears as <code>"index":null</code>. This guards against accidentally serializing an unintentionally enormous array (for example, millions of cells produced by a mistaken expression) into a huge JSON string. When «maxCells» is omitted, there is no limit.}}

=== JSON Objects vs. Arrays ===

Consider the following array in Variable <code>Biblio1984</code>
:[[image:MakeJSON_Biblio1984.png]]

One way to encode this is JSON is an a JSON object.
:<code>[[MakeJSON]]( Biblio1984, objects: Biblio )</code> →
:::<code>'{"title": "1984", "author": "George Orwell", "year": 1949, "pages": 336, "paperback": 1}'</code>

A second way to encode the same array data is an a JSON array.
:<code>[[MakeJSON]]( Biblio1984, indexOrder:Biblio, flags:9 )</code> →
:::<code>'["1984", "George Orwell", 1949, 336, 1]'</code>
Because the top-most item in JSON text is supposed to a JSON object, this second example isn't strictly valid (the «flags»=8 option was required for this reason). But for information anywhere other than the outermost dimension of «x», the fact remains that the data in an Analytica array can be placed in either form -- JSON-object or JSON-array.

For any index in your data, you can make it explicit by listing the index in the «objects» parameter if you want it to produce a JSON object, or in the «indexOrder» parameter if you want it to produce a JSON-array for that index. When you don't set the «flags»=8 bit, one index will be selected as an object index, even if they are all listed in «indexOrder», just because JSON text is supposed to have the root be an object.

When «x» contains an index that you have not explicitly listed, it will infer that it should be an object when the «flags»=1 is not set, the array is 1-D, and the index has textual member names. Otherwise it will output it as an array without the index labels.

=== Index order ===

When an Analytica array has more that one-dimension, you should list the indexes in «indexOrder», with the index that should vary most slowly listed first. For example:

Index I := <code>1..4</code>
Index J := <code>1..3</code>
Index K := <code>['k1', 'k2']</code>
Variable z1 := <code>10 * J + @K</code>
Variable z2 := <code>100*I + @K</code>
Index Struct := <code>['z1', 'z2']</code>
Variable data1 := [[Table]](Struct)( \z1, \z2 )

You should think of <code>data1</code> as being like an instantiation of a class named <code>Struct</code>, which has two members <code>z1</code> and <code>z2</code>. The <code>z1</code> member of <code>data1</code> has a 2-D array indexed by <code>J, K</code>, and <code>z2</code> has a 2-D array indexed by <code>I, K</code>.

If you don't specify the index order, you can't reliably predict which nesting you will get.
[[MakeJSON]]( data1 ) →
{ "z1": [[11, 12], [21, 22], [31, 32]],
"z2": [[101, 201, 301, 401], [102, 202, 302, 402]]
}
Note: [[MakeJSON]] does not insert newlines or indents. The result was formatted above manually.

It may be that the application code receiving this expects the data to be in <code>K</code>-major order. In the above, <code>z2</code> was as desired, but <code>z1</code> was transposed. To ensure this, you need to specify the «indexOrder».
[[MakeJSON]]( data1, indexOrder: K, J, I ) →
{ "z1": [[11, 21, 31], [12, 22, 32]],
"z2": [[101, 201, 301, 401], [102, 202, 302, 402]]
}

When you list multiple indexes in the «objects» parameter, this also constrains the order, where the first index listed becomes the outer object. For example, given the following Analytica array
:[[image:MakeJSON_cat_dog.png]]
listing <code>Animal</code> before <code>Sex</code> in «objects» creates nested objects as follows
:<code>[[MakeJSON]](Counts, objects:Animal,Sex)→{"cat": {"Male": 12, "Female": 8}, "dog": {"Male": 4, "Female": 5}}</code>
but listing them in the opposite order reverses the object nesting
:<code>[[MakeJSON]](Counts, objects:Sex,Animal)→{"Male": {"cat": 12, "dog": 4}, "Female": {"cat": 8, "dog": 5}}</code>

=== Mixed objects and arrays ===
(These rules apply to [[Analytica 5.2]]. Before that, it isn't legit to have object & array dimensions mixed for single arrays -- instead, you should use references to structure your object structures).

When a multi-dimensional array is transcribed into JSON at any level (each time there is a reference, you have a new multi-dimensional array to consider), each index of that array will be transcribed either as a JSON array or as a JSON object (i.e., either using brackets [ ] or using braces { } ). By using the «indexOrder» and «objects» parameters, you have control over which way each index is treated, as well as the nesting order. You could, for example, end up with an array of JSON objects, or a JSON object containing arrays for each member.

The rules for selecting whether an index is treated as an JSON object or JSON array is as follows:
* An index listed in «objects» will be transcribed as an object.
* When the array is 1-D and <code>flags:1</code> is not set and the index labels are textual, an index not listed in «indexOrder_» is treated as an object.
* When <code>flags:8</code> is not set, the very first index of the entire JSON is an object.
* Otherwise, it is transcribed as an array.

The rules for determining nesting order are as follows:
* If index I appears before index J in the «indexOrder» parameter, then J will be nested inside I.
* If index I appears before index J in the «objects» parameter, then J will be nested inside I.
* When two indexes aren't explicitly ordered in one of the two parameters, objects are nested inside array dimensions (i.e., objects moved inward, array dimensions moved outward), so you'll end up with arrays of objects.
* Finally, Analytica's internal canonical ordering is used. Since this is internal to Analytica, this is essentially an arbitrary ordering.

When you need to specify the nesting order between a JSON-array and a JSON-object dimension, list both corresponding indexes in the «indexOrder» parameter and list the index for the object in the «objects» parameter.

== See Also ==
* [[ParseJSON]]
* [[MakeCSV]]
* [[WriteTextFile]]
* [[JoinText]], [[NumberToText]]

What's new in Analytica 7.1?

2026-06-25T00:18:43Z

Lchrisman: /* Built-in functions */

This page lists new features in release 7.1, which is currently in early [[Beta Tester Page|Beta Testing]]. If have have an active subscription license, we encourage you to try it out from the [[Beta Tester Page]].

== Window appearance ==
The appearance of the chrome around child MDI windows (aka the "non-client area") has been changed to more closely match the Windows 11 style of windows -- i.e., thin (1 pixel) borders, rounded corners at the top, white title bar, very plain (text-like) button images in the toolbar.

== Assista ==
[[Assista]] is Analytica's A.I. assistant. She is greatly improved in this release.
* Her UI is now a top-level window that resides at the same level as Analytica's main application window.
** You can move her chat window to a non-overlapping location or even a different monitor (to maximize screen real estate used by your Analytica window).
** Selected objects remain visually selected in the main window when you type into Assista.
* Her chat has a different look-and-feel.
* Her chat window is faster and more responsive
* You can drag-highlight any text in her chat and copy to paste elsewhere.
* The UI has improved formatting capabilities for displaying Assista's response.
* Her "thoughts" display as she is processing your prompt, making it clear she is working and even giving you a peek into how she is solving it.
* She has a new processing pipeline on the backend, enabling her to respond faster but also work longer on harder tasks.
* She has an extended set of competencies (skills).
* Your sessions are automatically saved, keyed to your model, and you can resume a previous session for that model from a session selector dropdown in the UI.
* You can create and expose [[Assista_-_Analytica_AI_Assistant/Custom_user_skills_for_Assista|your own custom skills]] to expand her capabilities, or ask her to do it for you.
* You can add or drag-and-drop a document (<code>*.txt, *.pdf, *.md, *.docx, *.xlsx, *.xlsm</code>) or URLs into the chat which Assista can "ingest" during your conversation. Have her extract data from the doc, adding tables to your model. Or even to implement a model described by the paper or translate a spreadsheet into an Analytica model.
* Assista can "see" images in your model -- pictures in nodes, images in table cells, and diagram or graph screenshots.
* She is language-aware. If you are using Analytica is Spanish, she'll provide UI instructions that refer to the Spanish-language UI elements.
* She is aware of her reasoning in previous conversation turns and the actions she took, enabling her to explain her reasoning or build on ideas she thought about but might not have included in the final response.
* She has an improved ability to navigate and find objects within your (large) models.
* You can personalize her tone, style, level of verbosity and provide her custom instructions. To do this, click on the icon in the top-left corner of the Assista window and select Personization...

== Multi-linguality: Spanish UI ==
Analytica now comes with a Spanish-language UI, in which its menus, dialogs, error messages and built-in function descriptions are all in Spanish. Also its installer runs with a Spanish-language UI when you are in a Spanish-language region. Spanish is the default when you are in a Spanish-language region.

You can override the default language by launching Analytica as:
* <code>Analytica.exe /lang:es</code>
*: or
* <code>Analytica.exe /lang:en</code>

You can also set the <code>Language</code> registry setting in the <code>"HKCU/Software/Lumina Decision Systems/Analytica"</code> hive to REG_SZ <code>"en"</code> on <code>"es"</code> for your default if different from your windows region setting.

Some of you may ask "what about my language?". Stay tuned (and let us know there is a demand for your language). Once our AI translation pipeline is solid, it shouldn't be too hard for us to add more.

== CSV files ==
There are now a few additional ways to open CSV files in Analytica:
* On the command line: <code>Analytica.exe MyData.csv</code>
* Drag and drop a *.csv file onto the diagram (which behaves the same as using <code>File / Import...</code> on the *.csv file).

== Spreadsheets ==
* <code>[[SpreadsheetOpen]]("new")</code> now creates a blank spreadsheet in memory. Works with both the Excel and LibXl backends.
* Prefacing a sheet name with + in the call to [[SpreadsheetSetCell]] or [[SpreadsheetSetRange]] will add a new sheet by that name to the workbook (as it applies the specified change to that new worksheet). Works with either backend.
* You can also now remove a sheet from a workbook using: <code>[[SpreadsheetSetCell]](wb, "-OldSheet", col, row, Null)</code>. The «col» and «row» parameters are required but ignored in this case.

== Misc. User Interface ==
* The Node Icon editor (on the Diagram menu) is more featureful and can be used to edit arbitrary node images, with support for color and transparency.
* Added keyboard shortcuts for '''Set Node Style...''' and '''Set Diagram Style...'''
* There is a new option, '''Use as default arrow style''', on the right-mouse context menu for an influence diagram arrow. This sets the global arrow style default to match the selected arrow.

== Built-in functions ==
* New options for [[GetProcessInfo]]: <code>"Number of monitors"</code>, <code>"Current monitor rect"</code>, <code>"Current monitor work rect"</code>, <code>"Monitor «N» Rect"</code>, and <code>"Monitor «N» work rect"</code>.
* New optional parameter, «throwParsingErrors», to [[Evaluate]].
* [[ReadFromURL]] is a bit smarter about returning binary content (like <code>*.zip</code> files) as a [[In-memory binary data terms|Binary Data Term]].
* [[MakeJSON]] will automatically encode an image in base64 JSON, and [[ParseJSON]] will automatically decode a base64 representation into an image. Also there is a new «maxCells» parameter that can be used to prevent giagantic arrays from being encoded (resulting in immensely long text).
* <code>[[GetProcessInfo]]("UI Language")</code> returns the UI language, either <code>"en"</code> (for English) or <code>"es"</code> for Spanish.
* <code>[[QualifiedName]]( obj, nsContext )</code>: Returns the qualified identifier (as text) that uniquely identifies «obj» from the context of «nsContext».
* <code>[[Namespace]] of X</code>: A new virtual attribute that returns the namespace of «X».
* [[Evaluate]] has a second return value that captures output to the typescript window (including stuff written by [[ConsolePrint]]) during the evaluation. It also has a new optional «ignoreAtFirstWarning» parameter that can be used in conjunction, capturing the first warning text in that second return value, not showing the return value to the user, and ignoring additional warnings during the duration of the Evaluate call (enables Assista to see the warnings).
* Added a syntax construct for [[Namespaces#Scoped_namespace_inclusion:_Using|Scoped namespace inclusion]] to bring a namespace into scope for only a localized expression or lexical block.

== System variables ==
* SysVar [[Graph_ColorSequence]]: Replaces [[Graph_ColorSeq]] which is now deprecated. The new sysvar contains a list of color interer with one integer (of the form <code>0x00rrggbb</code>) per color (whereas the deprecated used triples of numbers per color).

== Engine ==
* After loading a large model, it parses expressions in parallel, using multiple threads/cores to parse different variables. On some computers on some models, this can dramatically speed up model load time.
* Color attributes use color integers for consistently (rather than the legacy number triples for R,G,B).
* You can use a localized namespace import (for a single expression or single lexical block) with the syntax
*:<code>[[Using..Do|Using]] NS;</code>

== Model loading ==
When opening a model file, the "checking" stage (when attributes are parsed) parses different expressions on different threads, resulting in substantially faster model load times for very large models.

Note: In the event that this creates a problem with your specific model (maybe due to an as-yet-undiscovered multithreading bug), you can disable it for your model as follows:
# Temporarily turn off multithreading (Skip this step if you are able to load your model)
## New model
## <b>Definition menu / System variables / Settings / Maximum evaluation threads</b>
## Set to 1 (and remember the previous value)
# Open your model
# <b>Definition menu / System variables / Settings / Disable Multithreaded Evaluations</b>
# Press the <code>Edit Table</code> button.
# Check the checkbox for <code>Parsing</code>
# Save your model
# <b>Definition menu / System variables / Settings / Maximum evaluation threads</b>
#: Restore the original value from Step 1

== MCP server ==
* Added an ability to install multiple ADE-based Mcp servers that run different ADE releases. For example, you can install two MCP servers into Claude Code:
* ade-server: Runs ADE 7.1
* ade-server-70: Runs ADE 7.0
The information in the <code>«ADE install folder»\Examples\Mcp_server\README.txt</code> file explain how (with enough info for Claude code to configure this for you).

With both installed, Claude Code (or other MCP-enabled AI agents) can compare results for the same model across different releases, etc.

Side note: The Mcp server was added to ADE 7.0.

== Internals ==
This release has undergone massive internal restructuring and refactorization. Ideally (i.e., in the absence of bugs) these changes won't change functionality, but may alter some aspects of behavior, hopefully for the better.
* Internal data structures use for multi-dimensional arrays has been changed. Possible impacts:
** Likely to remove the sensitivity to the "canonical order" of indexes on evaluation speed.
** May change relative evaluation speeds of various functions and operations.
* Added system modules/namespaces: <code>SysLib_Internal</code> and <code>SysLib_Experimental</code>. Intended for Analytica-internal use.
*[[:Category:Cell format functions|Cell formatting functions]] (like [[CellSpan]], [[CellFill]], etc.) are now [[Struct]]s rather than functions. Does not impact usage, other that making it easier for code to traverse resulting data structures.

== Discontinued... ==
* Plug-in functions. (An old hook that allows you to extend Analytica with compiled functions and UI elements written it C++. We are almost certain no one is using these hooks any more.)
* The sysvar [[Graph_ColorSeq]] is now deprecated (but works for both reading and setting to preserve backward compatibility). It has been replaced by the system variable [[Graph_ColorSequence]].
* The built-in (but undocumented, unsupported) <code>ifpos</code> and <code>if0</code> functions were removed.
* The legacy (deprecated) syntax <code>Using temp:=... Do</code> for declaring locals is no longer supported. Legacy models will have such definitions automatically rewritten to use [[Local..Do]] when you load them. [[Using..Do]] now has a different meaning, which is to provide a temporary namespace import.

MakeJSON

2026-06-25T00:17:10Z

Lchrisman:

[[category:Text Functions]]
[[category:Analytica 5.0]]
{{ReleaseBar}}
''New to [[Analytica 5.0]]''

{{Release|1=|2=6.5|3=''This function requires the {{Analytica Developer}} edition or higher (i.e., higher editions are [[Analytica Optimizer Guide|Analytica Optimizer]], [[Analytica Decision Engine|ADE]] or [http://Cubeplan.com CubePlan]]).''}}

== MakeJSON( x'', indexOrder, objects, flags{{Release|7.1||, maxCells}}'' ) ==

Returns text in [http://json.org JavaScript Object Notation (JSON)]] format representing the data in «x». When there are multidimensional arrays, you can control the nesting order in the JSON text by specifying the indexes in the «indexOrder» parameter. When some indexes encode the member names of a JavaScript object, you should list those indexes in «objects». The optional «flags» parameter accepts an integer that encodes a bit-field of options, with these options.
* 1 = Don't infer that 1-D arrays with textual indexes are objects.
* 2 = reserved. Must be 0. 
* 4 = reserved. Should be 0. 
* 8 = Top-level element in the result can be a non-object.
* 16 = Allow ragged arrays.{{Release|6.4||
* 32 {{=}} Don't include fields that have a [[Null]] value.}}{{Release|6.5||
* 64 {{=}} Prepend a dot to local index identifier text values.}}{{Release|7.0||
* 128 {{=}} Allow preformatted JSON. Reference to text gets inserted verbatim.}}{{Release|7.1||
* 256 {{=}} Escape CR as \r. Without the flag, it escapes as \n as generally required in JavaScript.}}{{Release|1=7.1|2=|3=
* 512 = Encode images in a base64 form such as <code>{"width":16, "height":16, "mime":"image/png", "base64":"iVBOR...."}</code>. Without this they appear as <code>"«Picture (PNG)»"</code>.}}

{{Release|7.1||The optional «maxCells» parameter limits how large an array may be before its contents are written out. When the total number of cells in an array -- the product of the lengths of all its indexes, across every dimension -- exceeds «maxCells», that array's elements are not serialized; instead a JSON object naming the array's true shape is emitted in its place:
:<code>{"$truncated":true, "cells":''N'', "maxCells":''M'', "dimensions":[{"index":"''I''", "size":''n''}, ...]}</code>
A positional or implicit index appears as <code>"index":null</code>. This guards against accidentally serializing an unintentionally enormous array (for example, millions of cells produced by a mistaken expression) into a huge JSON string. When «maxCells» is omitted, there is no limit.}}

=== JSON Objects vs. Arrays ===

Consider the following array in Variable <code>Biblio1984</code>
:[[image:MakeJSON_Biblio1984.png]]

One way to encode this is JSON is an a JSON object.
:<code>[[MakeJSON]]( Biblio1984, objects: Biblio )</code> →
:::<code>'{"title": "1984", "author": "George Orwell", "year": 1949, "pages": 336, "paperback": 1}'</code>

A second way to encode the same array data is an a JSON array.
:<code>[[MakeJSON]]( Biblio1984, indexOrder:Biblio, flags:9 )</code> →
:::<code>'["1984", "George Orwell", 1949, 336, 1]'</code>
Because the top-most item in JSON text is supposed to a JSON object, this second example isn't strictly valid (the «flags»=8 option was required for this reason). But for information anywhere other than the outermost dimension of «x», the fact remains that the data in an Analytica array can be placed in either form -- JSON-object or JSON-array.

For any index in your data, you can make it explicit by listing the index in the «objects» parameter if you want it to produce a JSON object, or in the «indexOrder» parameter if you want it to produce a JSON-array for that index. When you don't set the «flags»=8 bit, one index will be selected as an object index, even if they are all listed in «indexOrder», just because JSON text is supposed to have the root be an object.

When «x» contains an index that you have not explicitly listed, it will infer that it should be an object when the «flags»=1 is not set, the array is 1-D, and the index has textual member names. Otherwise it will output it as an array without the index labels.

=== Index order ===

When an Analytica array has more that one-dimension, you should list the indexes in «indexOrder», with the index that should vary most slowly listed first. For example:

Index I := <code>1..4</code>
Index J := <code>1..3</code>
Index K := <code>['k1', 'k2']</code>
Variable z1 := <code>10 * J + @K</code>
Variable z2 := <code>100*I + @K</code>
Index Struct := <code>['z1', 'z2']</code>
Variable data1 := [[Table]](Struct)( \z1, \z2 )

You should think of <code>data1</code> as being like an instantiation of a class named <code>Struct</code>, which has two members <code>z1</code> and <code>z2</code>. The <code>z1</code> member of <code>data1</code> has a 2-D array indexed by <code>J, K</code>, and <code>z2</code> has a 2-D array indexed by <code>I, K</code>.

If you don't specify the index order, you can't reliably predict which nesting you will get.
[[MakeJSON]]( data1 ) →
{ "z1": [[11, 12], [21, 22], [31, 32]],
"z2": [[101, 201, 301, 401], [102, 202, 302, 402]]
}
Note: [[MakeJSON]] does not insert newlines or indents. The result was formatted above manually.

It may be that the application code receiving this expects the data to be in <code>K</code>-major order. In the above, <code>z2</code> was as desired, but <code>z1</code> was transposed. To ensure this, you need to specify the «indexOrder».
[[MakeJSON]]( data1, indexOrder: K, J, I ) →
{ "z1": [[11, 21, 31], [12, 22, 32]],
"z2": [[101, 201, 301, 401], [102, 202, 302, 402]]
}

When you list multiple indexes in the «objects» parameter, this also constrains the order, where the first index listed becomes the outer object. For example, given the following Analytica array
:[[image:MakeJSON_cat_dog.png]]
listing <code>Animal</code> before <code>Sex</code> in «objects» creates nested objects as follows
:<code>[[MakeJSON]](Counts, objects:Animal,Sex)→{"cat": {"Male": 12, "Female": 8}, "dog": {"Male": 4, "Female": 5}}</code>
but listing them in the opposite order reverses the object nesting
:<code>[[MakeJSON]](Counts, objects:Sex,Animal)→{"Male": {"cat": 12, "dog": 4}, "Female": {"cat": 8, "dog": 5}}</code>

=== Mixed objects and arrays ===
(These rules apply to [[Analytica 5.2]]. Before that, it isn't legit to have object & array dimensions mixed for single arrays -- instead, you should use references to structure your object structures).

When a multi-dimensional array is transcribed into JSON at any level (each time there is a reference, you have a new multi-dimensional array to consider), each index of that array will be transcribed either as a JSON array or as a JSON object (i.e., either using brackets [ ] or using braces { } ). By using the «indexOrder» and «objects» parameters, you have control over which way each index is treated, as well as the nesting order. You could, for example, end up with an array of JSON objects, or a JSON object containing arrays for each member.

The rules for selecting whether an index is treated as an JSON object or JSON array is as follows:
* An index listed in «objects» will be transcribed as an object.
* When the array is 1-D and <code>flags:1</code> is not set and the index labels are textual, an index not listed in «indexOrder_» is treated as an object.
* When <code>flags:8</code> is not set, the very first index of the entire JSON is an object.
* Otherwise, it is transcribed as an array.

The rules for determining nesting order are as follows:
* If index I appears before index J in the «indexOrder» parameter, then J will be nested inside I.
* If index I appears before index J in the «objects» parameter, then J will be nested inside I.
* When two indexes aren't explicitly ordered in one of the two parameters, objects are nested inside array dimensions (i.e., objects moved inward, array dimensions moved outward), so you'll end up with arrays of objects.
* Finally, Analytica's internal canonical ordering is used. Since this is internal to Analytica, this is essentially an arbitrary ordering.

When you need to specify the nesting order between a JSON-array and a JSON-object dimension, list both corresponding indexes in the «indexOrder» parameter and list the index for the object in the «objects» parameter.

== See Also ==
* [[ParseJSON]]
* [[MakeCSV]]
* [[WriteTextFile]]
* [[JoinText]], [[NumberToText]]

MakeJSON

2026-06-25T00:15:33Z

Lchrisman: Document the new maxCells parameter (caps array serialization; oversized arrays become a {"$truncated":...} descriptor)

[[category:Text Functions]]
[[category:Analytica 5.0]]
{{ReleaseBar}}
''New to [[Analytica 5.0]]''

{{Release|1=|2=6.5|3=''This function requires the {{Analytica Developer}} edition or higher (i.e., higher editions are [[Analytica Optimizer Guide|Analytica Optimizer]], [[Analytica Decision Engine|ADE]] or [http://Cubeplan.com CubePlan]]).''}}

== MakeJSON( x'', indexOrder, objects, flags, maxCells'' ) ==

Returns text in [http://json.org JavaScript Object Notation (JSON)]] format representing the data in «x». When there are multidimensional arrays, you can control the nesting order in the JSON text by specifying the indexes in the «indexOrder» parameter. When some indexes encode the member names of a JavaScript object, you should list those indexes in «objects». The optional «flags» parameter accepts an integer that encodes a bit-field of options, with these options.
* 1 = Don't infer that 1-D arrays with textual indexes are objects.
* 2 = reserved. Must be 0. 
* 4 = reserved. Should be 0. 
* 8 = Top-level element in the result can be a non-object.
* 16 = Allow ragged arrays.{{Release|6.4||
* 32 {{=}} Don't include fields that have a [[Null]] value.}}{{Release|6.5||
* 64 {{=}} Prepend a dot to local index identifier text values.}}{{Release|7.0||
* 128 {{=}} Allow preformatted JSON. Reference to text gets inserted verbatim.}}{{Release|7.1||
* 256 {{=}} Escape CR as \r. Without the flag, it escapes as \n as generally required in JavaScript.}}{{Release|1=7.1|2=|3=
* 512 = Encode images in a base64 form such as <code>{"width":16, "height":16, "mime":"image/png", "base64":"iVBOR...."}</code>. Without this they appear as <code>"«Picture (PNG)»"</code>.}}

{{Release|7.1||The optional «maxCells» parameter limits how large an array may be before its contents are written out. When the total number of cells in an array -- the product of the lengths of all its indexes, across every dimension -- exceeds «maxCells», that array's elements are not serialized; instead a JSON object naming the array's true shape is emitted in its place:
:<code>{"$truncated":true, "cells":''N'', "maxCells":''M'', "dimensions":[{"index":"''I''", "size":''n''}, ...]}</code>
A positional or implicit index appears as <code>"index":null</code>. This guards against accidentally serializing an unintentionally enormous array (for example, millions of cells produced by a mistaken expression) into a huge JSON string. When «maxCells» is omitted, there is no limit.}}

=== JSON Objects vs. Arrays ===

Consider the following array in Variable <code>Biblio1984</code>
:[[image:MakeJSON_Biblio1984.png]]

One way to encode this is JSON is an a JSON object.
:<code>[[MakeJSON]]( Biblio1984, objects: Biblio )</code> →
:::<code>'{"title": "1984", "author": "George Orwell", "year": 1949, "pages": 336, "paperback": 1}'</code>

A second way to encode the same array data is an a JSON array.
:<code>[[MakeJSON]]( Biblio1984, indexOrder:Biblio, flags:9 )</code> →
:::<code>'["1984", "George Orwell", 1949, 336, 1]'</code>
Because the top-most item in JSON text is supposed to a JSON object, this second example isn't strictly valid (the «flags»=8 option was required for this reason). But for information anywhere other than the outermost dimension of «x», the fact remains that the data in an Analytica array can be placed in either form -- JSON-object or JSON-array.

For any index in your data, you can make it explicit by listing the index in the «objects» parameter if you want it to produce a JSON object, or in the «indexOrder» parameter if you want it to produce a JSON-array for that index. When you don't set the «flags»=8 bit, one index will be selected as an object index, even if they are all listed in «indexOrder», just because JSON text is supposed to have the root be an object.

When «x» contains an index that you have not explicitly listed, it will infer that it should be an object when the «flags»=1 is not set, the array is 1-D, and the index has textual member names. Otherwise it will output it as an array without the index labels.

=== Index order ===

When an Analytica array has more that one-dimension, you should list the indexes in «indexOrder», with the index that should vary most slowly listed first. For example:

Index I := <code>1..4</code>
Index J := <code>1..3</code>
Index K := <code>['k1', 'k2']</code>
Variable z1 := <code>10 * J + @K</code>
Variable z2 := <code>100*I + @K</code>
Index Struct := <code>['z1', 'z2']</code>
Variable data1 := [[Table]](Struct)( \z1, \z2 )

You should think of <code>data1</code> as being like an instantiation of a class named <code>Struct</code>, which has two members <code>z1</code> and <code>z2</code>. The <code>z1</code> member of <code>data1</code> has a 2-D array indexed by <code>J, K</code>, and <code>z2</code> has a 2-D array indexed by <code>I, K</code>.

If you don't specify the index order, you can't reliably predict which nesting you will get.
[[MakeJSON]]( data1 ) →
{ "z1": [[11, 12], [21, 22], [31, 32]],
"z2": [[101, 201, 301, 401], [102, 202, 302, 402]]
}
Note: [[MakeJSON]] does not insert newlines or indents. The result was formatted above manually.

It may be that the application code receiving this expects the data to be in <code>K</code>-major order. In the above, <code>z2</code> was as desired, but <code>z1</code> was transposed. To ensure this, you need to specify the «indexOrder».
[[MakeJSON]]( data1, indexOrder: K, J, I ) →
{ "z1": [[11, 21, 31], [12, 22, 32]],
"z2": [[101, 201, 301, 401], [102, 202, 302, 402]]
}

When you list multiple indexes in the «objects» parameter, this also constrains the order, where the first index listed becomes the outer object. For example, given the following Analytica array
:[[image:MakeJSON_cat_dog.png]]
listing <code>Animal</code> before <code>Sex</code> in «objects» creates nested objects as follows
:<code>[[MakeJSON]](Counts, objects:Animal,Sex)→{"cat": {"Male": 12, "Female": 8}, "dog": {"Male": 4, "Female": 5}}</code>
but listing them in the opposite order reverses the object nesting
:<code>[[MakeJSON]](Counts, objects:Sex,Animal)→{"Male": {"cat": 12, "dog": 4}, "Female": {"cat": 8, "dog": 5}}</code>

=== Mixed objects and arrays ===
(These rules apply to [[Analytica 5.2]]. Before that, it isn't legit to have object & array dimensions mixed for single arrays -- instead, you should use references to structure your object structures).

When a multi-dimensional array is transcribed into JSON at any level (each time there is a reference, you have a new multi-dimensional array to consider), each index of that array will be transcribed either as a JSON array or as a JSON object (i.e., either using brackets [ ] or using braces { } ). By using the «indexOrder» and «objects» parameters, you have control over which way each index is treated, as well as the nesting order. You could, for example, end up with an array of JSON objects, or a JSON object containing arrays for each member.

The rules for selecting whether an index is treated as an JSON object or JSON array is as follows:
* An index listed in «objects» will be transcribed as an object.
* When the array is 1-D and <code>flags:1</code> is not set and the index labels are textual, an index not listed in «indexOrder_» is treated as an object.
* When <code>flags:8</code> is not set, the very first index of the entire JSON is an object.
* Otherwise, it is transcribed as an array.

The rules for determining nesting order are as follows:
* If index I appears before index J in the «indexOrder» parameter, then J will be nested inside I.
* If index I appears before index J in the «objects» parameter, then J will be nested inside I.
* When two indexes aren't explicitly ordered in one of the two parameters, objects are nested inside array dimensions (i.e., objects moved inward, array dimensions moved outward), so you'll end up with arrays of objects.
* Finally, Analytica's internal canonical ordering is used. Since this is internal to Analytica, this is essentially an arbitrary ordering.

When you need to specify the nesting order between a JSON-array and a JSON-object dimension, list both corresponding indexes in the «indexOrder» parameter and list the index for the object in the «objects» parameter.

== See Also ==
* [[ParseJSON]]
* [[MakeCSV]]
* [[WriteTextFile]]
* [[JoinText]], [[NumberToText]]

QFlex distribution

2026-06-23T23:38:00Z

Lchrisman: Add download links for library and demo model

[[category:Continuous distributions]]
[[category:Unbounded distributions]]
[[category:Bounded distributions]]
[[category:Semi-bounded distributions]]
[[category:Univariate distributions]]
[[category:Custom distributions]]
{{ReleaseBar}}
''Provided by a downloadable add-in library (not a built-in distribution). Fitting requires the [[Analytica Optimizer]] edition.''

== QFlex( a, ''K, gamma, lb, ub'' ) ==

The ''QFlex distribution'' ("Quantile Flexibility") is a flexible, quantile-parameterized distribution capable of fitting a wide variety of continuous shapes directly to a set of assessed quantiles — for example a 10-50-90 judgment, or a larger set of assessed percentiles. Use it when standard parametric distributions such as the [[Normal distribution|Normal]], [[Log-normal distribution|LogNormal]], or [[Beta distribution|Beta]] are too restrictive to match what you have assessed, and you want a single smooth distribution that passes through (or near) your elicited quantiles while remaining a valid probability distribution.

You obtain the coefficient vector «a» by fitting it to your assessed quantiles with <code>QFlexFit</code> (see [[#How to use the library|How to use the library]] below). <code>QFlex</code> then draws a sampled, uncertain value from the fitted distribution, much as you would use a built-in distribution like <code>Normal</code> or <code>LogNormal</code>. Define a Chance variable as <code>QFlex(...)</code>.

;Reference
:Bickel, J. Eric, Connor Colombe, and Benjamin D. Leibowicz. ''The QFlex Distribution.'' The University of Texas at Austin. '''(Under review for publication, June 2026.)'''
:''The QFlex distribution and the methods implemented in this library are described in this paper. Because the paper is currently in review, the citation details may change.''

'''QFlex is not a built-in Analytica distribution.''' It is provided as a downloadable [[Libraries|library]] (see [[#Download and installation|Download and installation]]). Because the coefficient fit is solved as a quadratic program (QP), the [[Analytica Optimizer]] edition is required to fit a QFlex distribution to your data.

=== Parameters ===
* «a»: The QFlex coefficient vector, indexed by «K». You normally obtain this from <code>QFlexFit</code>.
* «K»: The coefficient [[Index]]. Its length is the maximum number of terms. Use, e.g., <code>K := 1..10</code>. (A 1-term QFlex is not a valid distribution, so use at least 2; more terms give a more flexible fit.)
* «gamma»: (Optional, default 0.5): The centering parameter. Use the same «gamma» that you used when fitting «a». See <code>QFlexEstimateGamma</code>.
* «lb», «ub»: (Optional): The support bounds. Omit both for an '''unbounded''' distribution; supply «lb» only for a '''lower-bounded''' [«lb», ∞) distribution; supply both for a '''bounded''' [«lb», «ub»] distribution.

== About the QFlex distribution ==

Internally, QFlex builds the distribution's quantile function (the inverse CDF) as a weighted sum of simple, individually valid building blocks: powers of a right-tail exponential, a left-tail (reflected) exponential, and a centered-uniform term. Because every building block is itself a valid, strictly increasing quantile function, a QFlex fit can be kept '''monotone — a genuine probability distribution — by construction''', through simple conditions on its coefficients. This is its main practical advantage over some other flexible quantile-parameterized families such as the [[Keelin (MetaLog) distribution|Keelin (MetaLog)]] distribution, which can require more complex constraints to ensure monotonicity. (Note that the Keelin distribution in Analytica automatically enforces these).

Consider QFlex when:
* You have '''more assessed (or empirical) quantiles than a standard 2-3 parameter distribution can honor''', and you want the distribution to match them rather than only approximate their mean and spread.
* You want a '''smooth, valid continuous distribution''' (with an analytic CDF and PDF) rather than a discrete or purely empirical one.
* You need '''control over skewness and tail behavior''', or want to shape the left tail, right tail, and center somewhat independently.
* Your quantity is '''unbounded, lower-bounded, or bounded''' — QFlex supports all three.

The number of terms (the length of «K») controls flexibility: more terms can match more assessed quantiles and more complex shapes. With «K» terms you can interpolate up to «K» probability-quantile pairs; with more assessed pairs than terms, the fit is a constrained least-squares fit. You do '''not''' need to work through the paper's mathematics to use the library — the functions encapsulate the fitting and the analytic details for practical model building.

Since the [[Keelin (MetaLog) distribution]] and QFlex are both highly flexible with largely the same underpinning motivations, the question of when to use one or the other arises. In general, the MetaLog distribution exhibits a greater degree of flexibility, and is more apt to capture distributional variation (and a comparable number of terms), whereas QFlex tends towards a strong unimodal bias and is less likely to display wiggle that may (or may not) actually be present. Both distributions exhibit strong matching to classic Pearson distributions, with QFlex showing a somewhat stronger bias to shapes within the Pearson space. In Analytica, for now, QFlex requires the Optimizer edition whereas MetaLog is available in all editions. For those who have to implement their own code in a different platform, QFlex is easier to implement than MetaLog 2.0.

== Download and installation ==

QFlex is distributed as an Analytica library plus a demonstration model, both plain <code>.ana</code> files:
* '''Library:''' <code>QFlex distribution library.ana</code> — [https://downloads.analytica.com/AdditionalLibraries/QFlex%20distribution%20library.ana Download]
* '''Demo model:''' <code>Demo of QFlex distribution.ana</code> — [https://downloads.analytica.com/AdditionalLibraries/Demo%20of%20QFlex%20distribution.ana Download]

To use the library in your own model, open your model and choose '''File → Add Library...''', select <code>QFlex distribution library.ana</code>, and link it. The library's functions then become available in your model. The demo model already includes the library and shows the full workflow.

=== Requirements ===
* '''[[Analytica Optimizer]] edition.''' The fitting function <code>QFlexFit</code> solves a quadratic program, which requires Optimizer. (Once you have a fitted coefficient vector, the remaining functions — <code>QFlex</code>, <code>CumQFlex</code>, <code>CumQFlexInv</code>, and <code>DensQFlex</code> — are ordinary evaluations and do not themselves require Optimizer; but in normal use you fit with <code>QFlexFit</code>, so Optimizer is required.)
* Analytica 7.x or later is recommended.

== How to use the library ==

The workflow has three steps:

# '''Compute the centering parameter «gamma».''' Use <code>QFlexEstimateGamma( p, q, I )</code> on your assessed probability-quantile pairs, or specify a «gamma» yourself if you have a preferred value. Keep that «gamma» and pass the '''same''' value to the later functions.
# '''Fit the coefficient vector «a».''' Use <code>QFlexFit( p, q, I, K, gamma, numTerms )</code> with your probabilities «p», quantiles «q», the assessment index «I», and the coefficient index «K». ''(This step requires the Optimizer edition.)''
# '''Use the fitted distribution.''' Call <code>QFlex( a, K, gamma, lb, ub )</code> to construct the uncertain quantity, or use <code>CumQFlexInv</code>, <code>CumQFlex</code>, and <code>DensQFlex</code> for the inverse CDF, CDF, and density at specific points. Use the '''same «gamma» and «K»''' that you used when fitting.

Because «gamma» is an explicit parameter to the QFlex functions, it is best to compute or choose «gamma» once and then pass that same value consistently to the fitting and evaluation functions.

== Examples ==

=== Fit to assessed quantiles ===

Suppose you have assessed ten quantiles of an uncertain quantity. Define an index of the assessed probabilities, the assessed quantile values, and a coefficient index:

:Index Quantile_probability := <code>[0.01, 0.05, 0.1, 0.25, 0.5, 0.75, 0.9, 0.95, 0.99, 0.999]</code>
:Variable Assessed_quantiles := <code>Table( Quantile_probability )( ... )</code>   ''(your ten assessed quantile values)''
:Index K_terms := <code>1..10</code>

Then carry out the three steps:

:Variable Gamma_to_use := <code>QFlexEstimateGamma( Quantile_probability, Assessed_quantiles, Quantile_probability )</code>
:Variable QFlex_coefficients := <code>QFlexFit( Quantile_probability, Assessed_quantiles, Quantile_probability, K_terms, Gamma_to_use )</code>
:Chance Fitted_distribution := <code>QFlex( QFlex_coefficients, K_terms, Gamma_to_use )</code>

Now <code>Fitted_distribution</code> is an uncertain quantity you can use anywhere in your model. You can also read the fitted distribution analytically at specific points:

:<code>CumQFlexInv( 0.9, QFlex_coefficients, K_terms, Gamma_to_use )</code>   ''the fitted 90th percentile''
:<code>CumQFlex( x, QFlex_coefficients, K_terms, Gamma_to_use )</code>   ''the CDF, P(X ≤ x)''
:<code>DensQFlex( x, QFlex_coefficients, K_terms, Gamma_to_use )</code>   ''the density (PDF) at x''

=== Bounded and semi-bounded fits ===

To fit a distribution known to be non-negative (for example, a cost or a physical quantity), pass a lower bound to the construction and evaluation functions:

:<code>QFlex( QFlex_coefficients, K_terms, Gamma_to_use, lb: 0 )</code>   ''lower-bounded at 0''
:<code>QFlex( QFlex_coefficients, K_terms, Gamma_to_use, lb: 0, ub: 100 )</code>   ''bounded on [0, 100]''

Use the same «lb» and «ub» consistently across <code>QFlex</code>, <code>CumQFlex</code>, <code>CumQFlexInv</code>, and <code>DensQFlex</code> so they all describe the same distribution.

== Fitting the distribution to your data ==

These two functions are used '''before''' constructing the distribution, to estimate the centering parameter and fit the coefficients.

=== QFlexEstimateGamma( p, q, I ) ===

Estimates the QFlex centering parameter «gamma» from assessed probability-quantile pairs («p», «q») indexed by «I». It estimates Q(0.1), Q(0.5), and Q(0.9) from your assessed quantiles by interpolation, computes the Kelly skewness index ''SI'', and returns gamma = 0.5 × (1 − ''SI''), clipped to the open interval (0, 1).

* «p»: The assessed probabilities, each in (0, 1), indexed by «I».
* «q»: The corresponding assessed quantile values, indexed by «I».
* «I»: The [[Index]] over the assessments.

Returns gamma = 0.5 for a symmetric assessment with no skew (0.45 in the exactly symmetric case, matching the paper's convention), a value greater than 0.5 for right-skewed assessments, and less than 0.5 for left-skewed ones. If fewer than three points are supplied, it returns 0.5.

''Why «gamma» matters:'' it centers the centered-uniform basis terms. Choosing «gamma» from the assessed skewness (rather than always 0.5) keeps the fit well-conditioned — important especially when your assessed probabilities are symmetric about 0.5.

=== QFlexFit( p, q, I, K, ''gamma, numTerms'' ) ===

Fits the QFlex coefficient vector «a» (indexed by «K») to your assessed pairs («p», «q») by constrained least squares: it minimizes squared quantile error subject to the monotonicity constraints (tail-coefficient nonnegativity and the tail-center magnitude bound) from the paper, so the fitted distribution is '''valid by construction'''. '''Requires the [[Analytica Optimizer]] edition''' (the fit is a QP).

* «p», «q»: The assessed probabilities and quantiles, indexed by «I».
* «I»: The [[Index]] over the assessments.
* «K»: The coefficient [[Index]]; its length sets the maximum number of terms.
* «gamma»: (Optional): The centering parameter. If omitted, <code>QFlexFit</code> estimates it internally via <code>QFlexEstimateGamma</code>. '''Best practice:''' compute «gamma» once with <code>QFlexEstimateGamma</code> and pass it explicitly, so the same value is used for both fitting and evaluation.
* «numTerms»: (Optional): How many terms (≤ <code>IndexLength(K)</code>) to actually fit. If omitted, all of «K» is used. If «numTerms» is less than the length of «K», the result is still indexed by «K» and is <code>Null</code> in the positions beyond «numTerms».

'''Returns''' the coefficient vector «a» indexed by «K» (with <code>Null</code> in any unused positions). Pass this vector, with the same «K» and «gamma», to <code>QFlex</code>, <code>CumQFlex</code>, <code>CumQFlexInv</code>, or <code>DensQFlex</code>.

== Analytic distribution functions ==

These functions evaluate the fitted distribution analytically at a point (or an array of points), without sampling. They all take the fitted coefficient vector «a» indexed by «K», the centering parameter «gamma», and the same optional bounds «lb»/«ub» described under [[#QFlex( a, K, gamma, lb, ub )|QFlex]].

=== CumQFlexInv( p, a, K, ''gamma, lb, ub'' ) ===

The analytic '''inverse cumulative (quantile) function''': returns the value «x» such that P(X ≤ «x») = «p». Evaluate it at a probability «p» (or an array of probabilities) to read quantiles off the fitted distribution. This is the closed-form construction; <code>QFlex</code> simply calls it with a uniform random «p».

* «p»: A probability in [0, 1] (or an array of them).
* «a», «K», «gamma», «lb», «ub»: As for <code>QFlex</code>.

'''Example:''' <code>CumQFlexInv( 0.9, QFlex_coefficients, K_terms, Gamma_to_use )</code> returns the fitted 90th percentile.

=== CumQFlex( x, a, K, ''gamma, lb, ub'' ) ===

The analytic '''cumulative distribution function''': returns P(X ≤ «x») for a value «x». It is computed by numerically inverting the quantile function (bisection), giving the analytic CDF at a point, independent of sampling.

* «x»: The value (or array of values) at which to evaluate the CDF.
* «a», «K», «gamma», «lb», «ub»: As for <code>QFlex</code>.

'''Example:''' <code>CumQFlex( 0, QFlex_coefficients, K_terms, Gamma_to_use )</code>

=== DensQFlex( x, a, K, ''gamma, lb, ub'' ) ===

The analytic '''probability density function''' f(«x»): returns the density at a value «x», using the quantile-density relationship (no sampling required). This is convenient for plotting a smooth PDF curve over a grid of «x» values.

* «x»: The value (or array of values) at which to evaluate the density.
* «a», «K», «gamma», «lb», «ub»: As for <code>QFlex</code>.

'''Example:''' <code>DensQFlex( Plot_x, QFlex_coefficients, K_terms, Gamma_to_use )</code>

'''Note on bounds:''' An upper bound must be supplied together with a lower bound. Specifying «ub» without «lb» is not supported, and the analytic CDF/PDF return <code>Null</code> in that case. For an upper-bounded quantity, use the bounded [«lb», «ub»] form.

== The demo model ==

The demo model <code>Demo of QFlex distribution.ana</code> provides an interactive playground:
* Editable assessed quantiles for several example data sets (a symmetric logistic, a right-skewed lognormal, a heavy-tailed Student-''t'', and two bimodal shapes), selectable individually.
* A number-of-terms control to explore how flexibility changes the fit.
* Live graphs of the fitted inverse CDF, CDF, and PDF, built from <code>CumQFlexInv</code>, <code>CumQFlex</code>, and <code>DensQFlex</code>.
* A QA-tests module with analytically tractable checks (for example, the coefficient vector «a» = [0, 1, 1] reproduces the standard logistic quantile), useful as worked sanity checks.

== See Also ==

* [[Keelin (MetaLog) distribution]] — a related quantile-parameterized distribution.
* [[UncertainLMH]] — simpler option when you have only a low-medium-high (e.g. 10-50-90) assessment.
* [[Analytica Optimizer]] — the edition required for fitting.
* [[Distribution Densities Library]]
* [[Probability Distributions]]

QFlex distribution

2026-06-23T23:30:03Z

Lchrisman: /* About the QFlex distribution */

[[category:Continuous distributions]]
[[category:Unbounded distributions]]
[[category:Bounded distributions]]
[[category:Semi-bounded distributions]]
[[category:Univariate distributions]]
[[category:Custom distributions]]
{{ReleaseBar}}
''Provided by a downloadable add-in library (not a built-in distribution). Fitting requires the [[Analytica Optimizer]] edition.''

== QFlex( a, ''K, gamma, lb, ub'' ) ==

The ''QFlex distribution'' ("Quantile Flexibility") is a flexible, quantile-parameterized distribution capable of fitting a wide variety of continuous shapes directly to a set of assessed quantiles — for example a 10-50-90 judgment, or a larger set of assessed percentiles. Use it when standard parametric distributions such as the [[Normal distribution|Normal]], [[Log-normal distribution|LogNormal]], or [[Beta distribution|Beta]] are too restrictive to match what you have assessed, and you want a single smooth distribution that passes through (or near) your elicited quantiles while remaining a valid probability distribution.

You obtain the coefficient vector «a» by fitting it to your assessed quantiles with <code>QFlexFit</code> (see [[#How to use the library|How to use the library]] below). <code>QFlex</code> then draws a sampled, uncertain value from the fitted distribution, much as you would use a built-in distribution like <code>Normal</code> or <code>LogNormal</code>. Define a Chance variable as <code>QFlex(...)</code>.

;Reference
:Bickel, J. Eric, Connor Colombe, and Benjamin D. Leibowicz. ''The QFlex Distribution.'' The University of Texas at Austin. '''(Under review for publication, June 2026.)'''
:''The QFlex distribution and the methods implemented in this library are described in this paper. Because the paper is currently in review, the citation details may change.''

'''QFlex is not a built-in Analytica distribution.''' It is provided as a downloadable [[Libraries|library]] (see [[#Download and installation|Download and installation]]). Because the coefficient fit is solved as a quadratic program (QP), the [[Analytica Optimizer]] edition is required to fit a QFlex distribution to your data.

=== Parameters ===
* «a»: The QFlex coefficient vector, indexed by «K». You normally obtain this from <code>QFlexFit</code>.
* «K»: The coefficient [[Index]]. Its length is the maximum number of terms. Use, e.g., <code>K := 1..10</code>. (A 1-term QFlex is not a valid distribution, so use at least 2; more terms give a more flexible fit.)
* «gamma»: (Optional, default 0.5): The centering parameter. Use the same «gamma» that you used when fitting «a». See <code>QFlexEstimateGamma</code>.
* «lb», «ub»: (Optional): The support bounds. Omit both for an '''unbounded''' distribution; supply «lb» only for a '''lower-bounded''' [«lb», ∞) distribution; supply both for a '''bounded''' [«lb», «ub»] distribution.

== About the QFlex distribution ==

Internally, QFlex builds the distribution's quantile function (the inverse CDF) as a weighted sum of simple, individually valid building blocks: powers of a right-tail exponential, a left-tail (reflected) exponential, and a centered-uniform term. Because every building block is itself a valid, strictly increasing quantile function, a QFlex fit can be kept '''monotone — a genuine probability distribution — by construction''', through simple conditions on its coefficients. This is its main practical advantage over some other flexible quantile-parameterized families such as the [[Keelin (MetaLog) distribution|Keelin (MetaLog)]] distribution, which can require more complex constraints to ensure monotonicity. (Note that the Keelin distribution in Analytica automatically enforces these).

Consider QFlex when:
* You have '''more assessed (or empirical) quantiles than a standard 2-3 parameter distribution can honor''', and you want the distribution to match them rather than only approximate their mean and spread.
* You want a '''smooth, valid continuous distribution''' (with an analytic CDF and PDF) rather than a discrete or purely empirical one.
* You need '''control over skewness and tail behavior''', or want to shape the left tail, right tail, and center somewhat independently.
* Your quantity is '''unbounded, lower-bounded, or bounded''' — QFlex supports all three.

The number of terms (the length of «K») controls flexibility: more terms can match more assessed quantiles and more complex shapes. With «K» terms you can interpolate up to «K» probability-quantile pairs; with more assessed pairs than terms, the fit is a constrained least-squares fit. You do '''not''' need to work through the paper's mathematics to use the library — the functions encapsulate the fitting and the analytic details for practical model building.

Since the [[Keelin (MetaLog) distribution]] and QFlex are both highly flexible with largely the same underpinning motivations, the question of when to use one or the other arises. In general, the MetaLog distribution exhibits a greater degree of flexibility, and is more apt to capture distributional variation (and a comparable number of terms), whereas QFlex tends towards a strong unimodal bias and is less likely to display wiggle that may (or may not) actually be present. Both distributions exhibit strong matching to classic Pearson distributions, with QFlex showing a somewhat stronger bias to shapes within the Pearson space. In Analytica, for now, QFlex requires the Optimizer edition whereas MetaLog is available in all editions. For those who have to implement their own code in a different platform, QFlex is easier to implement than MetaLog 2.0.

== Download and installation ==

QFlex is distributed as an Analytica library plus a demonstration model, both plain <code>.ana</code> files:
* '''Library:''' <code>QFlex distribution library.ana</code> — '''[download link to be added]'''
* '''Demo model:''' <code>Demo of QFlex distribution.ana</code> — '''[download link to be added]'''

To use the library in your own model, open your model and choose '''File → Add Library...''', select <code>QFlex distribution library.ana</code>, and link it. The library's functions then become available in your model. The demo model already includes the library and shows the full workflow.

=== Requirements ===
* '''[[Analytica Optimizer]] edition.''' The fitting function <code>QFlexFit</code> solves a quadratic program, which requires Optimizer. (Once you have a fitted coefficient vector, the remaining functions — <code>QFlex</code>, <code>CumQFlex</code>, <code>CumQFlexInv</code>, and <code>DensQFlex</code> — are ordinary evaluations and do not themselves require Optimizer; but in normal use you fit with <code>QFlexFit</code>, so Optimizer is required.)
* Analytica 7.x or later is recommended.

== How to use the library ==

The workflow has three steps:

# '''Compute the centering parameter «gamma».''' Use <code>QFlexEstimateGamma( p, q, I )</code> on your assessed probability-quantile pairs, or specify a «gamma» yourself if you have a preferred value. Keep that «gamma» and pass the '''same''' value to the later functions.
# '''Fit the coefficient vector «a».''' Use <code>QFlexFit( p, q, I, K, gamma, numTerms )</code> with your probabilities «p», quantiles «q», the assessment index «I», and the coefficient index «K». ''(This step requires the Optimizer edition.)''
# '''Use the fitted distribution.''' Call <code>QFlex( a, K, gamma, lb, ub )</code> to construct the uncertain quantity, or use <code>CumQFlexInv</code>, <code>CumQFlex</code>, and <code>DensQFlex</code> for the inverse CDF, CDF, and density at specific points. Use the '''same «gamma» and «K»''' that you used when fitting.

Because «gamma» is an explicit parameter to the QFlex functions, it is best to compute or choose «gamma» once and then pass that same value consistently to the fitting and evaluation functions.

== Examples ==

=== Fit to assessed quantiles ===

Suppose you have assessed ten quantiles of an uncertain quantity. Define an index of the assessed probabilities, the assessed quantile values, and a coefficient index:

:Index Quantile_probability := <code>[0.01, 0.05, 0.1, 0.25, 0.5, 0.75, 0.9, 0.95, 0.99, 0.999]</code>
:Variable Assessed_quantiles := <code>Table( Quantile_probability )( ... )</code>   ''(your ten assessed quantile values)''
:Index K_terms := <code>1..10</code>

Then carry out the three steps:

:Variable Gamma_to_use := <code>QFlexEstimateGamma( Quantile_probability, Assessed_quantiles, Quantile_probability )</code>
:Variable QFlex_coefficients := <code>QFlexFit( Quantile_probability, Assessed_quantiles, Quantile_probability, K_terms, Gamma_to_use )</code>
:Chance Fitted_distribution := <code>QFlex( QFlex_coefficients, K_terms, Gamma_to_use )</code>

Now <code>Fitted_distribution</code> is an uncertain quantity you can use anywhere in your model. You can also read the fitted distribution analytically at specific points:

:<code>CumQFlexInv( 0.9, QFlex_coefficients, K_terms, Gamma_to_use )</code>   ''the fitted 90th percentile''
:<code>CumQFlex( x, QFlex_coefficients, K_terms, Gamma_to_use )</code>   ''the CDF, P(X ≤ x)''
:<code>DensQFlex( x, QFlex_coefficients, K_terms, Gamma_to_use )</code>   ''the density (PDF) at x''

=== Bounded and semi-bounded fits ===

To fit a distribution known to be non-negative (for example, a cost or a physical quantity), pass a lower bound to the construction and evaluation functions:

:<code>QFlex( QFlex_coefficients, K_terms, Gamma_to_use, lb: 0 )</code>   ''lower-bounded at 0''
:<code>QFlex( QFlex_coefficients, K_terms, Gamma_to_use, lb: 0, ub: 100 )</code>   ''bounded on [0, 100]''

Use the same «lb» and «ub» consistently across <code>QFlex</code>, <code>CumQFlex</code>, <code>CumQFlexInv</code>, and <code>DensQFlex</code> so they all describe the same distribution.

== Fitting the distribution to your data ==

These two functions are used '''before''' constructing the distribution, to estimate the centering parameter and fit the coefficients.

=== QFlexEstimateGamma( p, q, I ) ===

Estimates the QFlex centering parameter «gamma» from assessed probability-quantile pairs («p», «q») indexed by «I». It estimates Q(0.1), Q(0.5), and Q(0.9) from your assessed quantiles by interpolation, computes the Kelly skewness index ''SI'', and returns gamma = 0.5 × (1 − ''SI''), clipped to the open interval (0, 1).

* «p»: The assessed probabilities, each in (0, 1), indexed by «I».
* «q»: The corresponding assessed quantile values, indexed by «I».
* «I»: The [[Index]] over the assessments.

Returns gamma = 0.5 for a symmetric assessment with no skew (0.45 in the exactly symmetric case, matching the paper's convention), a value greater than 0.5 for right-skewed assessments, and less than 0.5 for left-skewed ones. If fewer than three points are supplied, it returns 0.5.

''Why «gamma» matters:'' it centers the centered-uniform basis terms. Choosing «gamma» from the assessed skewness (rather than always 0.5) keeps the fit well-conditioned — important especially when your assessed probabilities are symmetric about 0.5.

=== QFlexFit( p, q, I, K, ''gamma, numTerms'' ) ===

Fits the QFlex coefficient vector «a» (indexed by «K») to your assessed pairs («p», «q») by constrained least squares: it minimizes squared quantile error subject to the monotonicity constraints (tail-coefficient nonnegativity and the tail-center magnitude bound) from the paper, so the fitted distribution is '''valid by construction'''. '''Requires the [[Analytica Optimizer]] edition''' (the fit is a QP).

* «p», «q»: The assessed probabilities and quantiles, indexed by «I».
* «I»: The [[Index]] over the assessments.
* «K»: The coefficient [[Index]]; its length sets the maximum number of terms.
* «gamma»: (Optional): The centering parameter. If omitted, <code>QFlexFit</code> estimates it internally via <code>QFlexEstimateGamma</code>. '''Best practice:''' compute «gamma» once with <code>QFlexEstimateGamma</code> and pass it explicitly, so the same value is used for both fitting and evaluation.
* «numTerms»: (Optional): How many terms (≤ <code>IndexLength(K)</code>) to actually fit. If omitted, all of «K» is used. If «numTerms» is less than the length of «K», the result is still indexed by «K» and is <code>Null</code> in the positions beyond «numTerms».

'''Returns''' the coefficient vector «a» indexed by «K» (with <code>Null</code> in any unused positions). Pass this vector, with the same «K» and «gamma», to <code>QFlex</code>, <code>CumQFlex</code>, <code>CumQFlexInv</code>, or <code>DensQFlex</code>.

== Analytic distribution functions ==

These functions evaluate the fitted distribution analytically at a point (or an array of points), without sampling. They all take the fitted coefficient vector «a» indexed by «K», the centering parameter «gamma», and the same optional bounds «lb»/«ub» described under [[#QFlex( a, K, gamma, lb, ub )|QFlex]].

=== CumQFlexInv( p, a, K, ''gamma, lb, ub'' ) ===

The analytic '''inverse cumulative (quantile) function''': returns the value «x» such that P(X ≤ «x») = «p». Evaluate it at a probability «p» (or an array of probabilities) to read quantiles off the fitted distribution. This is the closed-form construction; <code>QFlex</code> simply calls it with a uniform random «p».

* «p»: A probability in [0, 1] (or an array of them).
* «a», «K», «gamma», «lb», «ub»: As for <code>QFlex</code>.

'''Example:''' <code>CumQFlexInv( 0.9, QFlex_coefficients, K_terms, Gamma_to_use )</code> returns the fitted 90th percentile.

=== CumQFlex( x, a, K, ''gamma, lb, ub'' ) ===

The analytic '''cumulative distribution function''': returns P(X ≤ «x») for a value «x». It is computed by numerically inverting the quantile function (bisection), giving the analytic CDF at a point, independent of sampling.

* «x»: The value (or array of values) at which to evaluate the CDF.
* «a», «K», «gamma», «lb», «ub»: As for <code>QFlex</code>.

'''Example:''' <code>CumQFlex( 0, QFlex_coefficients, K_terms, Gamma_to_use )</code>

=== DensQFlex( x, a, K, ''gamma, lb, ub'' ) ===

The analytic '''probability density function''' f(«x»): returns the density at a value «x», using the quantile-density relationship (no sampling required). This is convenient for plotting a smooth PDF curve over a grid of «x» values.

* «x»: The value (or array of values) at which to evaluate the density.
* «a», «K», «gamma», «lb», «ub»: As for <code>QFlex</code>.

'''Example:''' <code>DensQFlex( Plot_x, QFlex_coefficients, K_terms, Gamma_to_use )</code>

'''Note on bounds:''' An upper bound must be supplied together with a lower bound. Specifying «ub» without «lb» is not supported, and the analytic CDF/PDF return <code>Null</code> in that case. For an upper-bounded quantity, use the bounded [«lb», «ub»] form.

== The demo model ==

The demo model <code>Demo of QFlex distribution.ana</code> provides an interactive playground:
* Editable assessed quantiles for several example data sets (a symmetric logistic, a right-skewed lognormal, a heavy-tailed Student-''t'', and two bimodal shapes), selectable individually.
* A number-of-terms control to explore how flexibility changes the fit.
* Live graphs of the fitted inverse CDF, CDF, and PDF, built from <code>CumQFlexInv</code>, <code>CumQFlex</code>, and <code>DensQFlex</code>.
* A QA-tests module with analytically tractable checks (for example, the coefficient vector «a» = [0, 1, 1] reproduces the standard logistic quantile), useful as worked sanity checks.

== See Also ==

* [[Keelin (MetaLog) distribution]] — a related quantile-parameterized distribution.
* [[UncertainLMH]] — simpler option when you have only a low-medium-high (e.g. 10-50-90) assessment.
* [[Analytica Optimizer]] — the edition required for fitting.
* [[Distribution Densities Library]]
* [[Probability Distributions]]

QFlex distribution

2026-06-23T23:27:37Z

Lchrisman: /* About the QFlex distribution */

[[category:Continuous distributions]]
[[category:Unbounded distributions]]
[[category:Bounded distributions]]
[[category:Semi-bounded distributions]]
[[category:Univariate distributions]]
[[category:Custom distributions]]
{{ReleaseBar}}
''Provided by a downloadable add-in library (not a built-in distribution). Fitting requires the [[Analytica Optimizer]] edition.''

== QFlex( a, ''K, gamma, lb, ub'' ) ==

The ''QFlex distribution'' ("Quantile Flexibility") is a flexible, quantile-parameterized distribution capable of fitting a wide variety of continuous shapes directly to a set of assessed quantiles — for example a 10-50-90 judgment, or a larger set of assessed percentiles. Use it when standard parametric distributions such as the [[Normal distribution|Normal]], [[Log-normal distribution|LogNormal]], or [[Beta distribution|Beta]] are too restrictive to match what you have assessed, and you want a single smooth distribution that passes through (or near) your elicited quantiles while remaining a valid probability distribution.

You obtain the coefficient vector «a» by fitting it to your assessed quantiles with <code>QFlexFit</code> (see [[#How to use the library|How to use the library]] below). <code>QFlex</code> then draws a sampled, uncertain value from the fitted distribution, much as you would use a built-in distribution like <code>Normal</code> or <code>LogNormal</code>. Define a Chance variable as <code>QFlex(...)</code>.

;Reference
:Bickel, J. Eric, Connor Colombe, and Benjamin D. Leibowicz. ''The QFlex Distribution.'' The University of Texas at Austin. '''(Under review for publication, June 2026.)'''
:''The QFlex distribution and the methods implemented in this library are described in this paper. Because the paper is currently in review, the citation details may change.''

'''QFlex is not a built-in Analytica distribution.''' It is provided as a downloadable [[Libraries|library]] (see [[#Download and installation|Download and installation]]). Because the coefficient fit is solved as a quadratic program (QP), the [[Analytica Optimizer]] edition is required to fit a QFlex distribution to your data.

=== Parameters ===
* «a»: The QFlex coefficient vector, indexed by «K». You normally obtain this from <code>QFlexFit</code>.
* «K»: The coefficient [[Index]]. Its length is the maximum number of terms. Use, e.g., <code>K := 1..10</code>. (A 1-term QFlex is not a valid distribution, so use at least 2; more terms give a more flexible fit.)
* «gamma»: (Optional, default 0.5): The centering parameter. Use the same «gamma» that you used when fitting «a». See <code>QFlexEstimateGamma</code>.
* «lb», «ub»: (Optional): The support bounds. Omit both for an '''unbounded''' distribution; supply «lb» only for a '''lower-bounded''' [«lb», ∞) distribution; supply both for a '''bounded''' [«lb», «ub»] distribution.

== About the QFlex distribution ==

Internally, QFlex builds the distribution's quantile function (the inverse CDF) as a weighted sum of simple, individually valid building blocks: powers of a right-tail exponential, a left-tail (reflected) exponential, and a centered-uniform term. Because every building block is itself a valid, strictly increasing quantile function, a QFlex fit can be kept '''monotone — a genuine probability distribution — by construction''', through simple conditions on its coefficients. This is its main practical advantage over some other flexible quantile-parameterized families such as the [[Keelin (MetaLog) distribution|Keelin (MetaLog)]] distribution, which can require more complex constraints to ensure monotonicity. (Note that the Keelin distribution in Analytica automatically enforces these).

Consider QFlex when:
* You have '''more assessed (or empirical) quantiles than a standard 2-3 parameter distribution can honor''', and you want the distribution to match them rather than only approximate their mean and spread.
* You want a '''smooth, valid continuous distribution''' (with an analytic CDF and PDF) rather than a discrete or purely empirical one.
* You need '''control over skewness and tail behavior''', or want to shape the left tail, right tail, and center somewhat independently.
* Your quantity is '''unbounded, lower-bounded, or bounded''' — QFlex supports all three.

The number of terms (the length of «K») controls flexibility: more terms can match more assessed quantiles and more complex shapes. With «K» terms you can interpolate up to «K» probability-quantile pairs; with more assessed pairs than terms, the fit is a constrained least-squares fit. You do '''not''' need to work through the paper's mathematics to use the library — the functions encapsulate the fitting and the analytic details for practical model building.

Since the [[Keelin (MetaLog) distribution]] and QFlex are both highly flexible with largely the same underpinning motivations, the question of when to use one or the other arises. In general, the MetaLog distribution exhibits a greater degree of flexibility, and is more apt to capture distributional variation (and a comparable number of terms), whereas QFlex tends towards a strong unimodal bias and is less likely to display wiggle that may (or may not) actually be present. Both distributions exhibit strong matching to classic Pearson distributions, with QFlex showing a somewhat stronger bias to shapes within the Pearson space.

== Download and installation ==

QFlex is distributed as an Analytica library plus a demonstration model, both plain <code>.ana</code> files:
* '''Library:''' <code>QFlex distribution library.ana</code> — '''[download link to be added]'''
* '''Demo model:''' <code>Demo of QFlex distribution.ana</code> — '''[download link to be added]'''

To use the library in your own model, open your model and choose '''File → Add Library...''', select <code>QFlex distribution library.ana</code>, and link it. The library's functions then become available in your model. The demo model already includes the library and shows the full workflow.

=== Requirements ===
* '''[[Analytica Optimizer]] edition.''' The fitting function <code>QFlexFit</code> solves a quadratic program, which requires Optimizer. (Once you have a fitted coefficient vector, the remaining functions — <code>QFlex</code>, <code>CumQFlex</code>, <code>CumQFlexInv</code>, and <code>DensQFlex</code> — are ordinary evaluations and do not themselves require Optimizer; but in normal use you fit with <code>QFlexFit</code>, so Optimizer is required.)
* Analytica 7.x or later is recommended.

== How to use the library ==

The workflow has three steps:

# '''Compute the centering parameter «gamma».''' Use <code>QFlexEstimateGamma( p, q, I )</code> on your assessed probability-quantile pairs, or specify a «gamma» yourself if you have a preferred value. Keep that «gamma» and pass the '''same''' value to the later functions.
# '''Fit the coefficient vector «a».''' Use <code>QFlexFit( p, q, I, K, gamma, numTerms )</code> with your probabilities «p», quantiles «q», the assessment index «I», and the coefficient index «K». ''(This step requires the Optimizer edition.)''
# '''Use the fitted distribution.''' Call <code>QFlex( a, K, gamma, lb, ub )</code> to construct the uncertain quantity, or use <code>CumQFlexInv</code>, <code>CumQFlex</code>, and <code>DensQFlex</code> for the inverse CDF, CDF, and density at specific points. Use the '''same «gamma» and «K»''' that you used when fitting.

Because «gamma» is an explicit parameter to the QFlex functions, it is best to compute or choose «gamma» once and then pass that same value consistently to the fitting and evaluation functions.

== Examples ==

=== Fit to assessed quantiles ===

Suppose you have assessed ten quantiles of an uncertain quantity. Define an index of the assessed probabilities, the assessed quantile values, and a coefficient index:

:Index Quantile_probability := <code>[0.01, 0.05, 0.1, 0.25, 0.5, 0.75, 0.9, 0.95, 0.99, 0.999]</code>
:Variable Assessed_quantiles := <code>Table( Quantile_probability )( ... )</code>   ''(your ten assessed quantile values)''
:Index K_terms := <code>1..10</code>

Then carry out the three steps:

:Variable Gamma_to_use := <code>QFlexEstimateGamma( Quantile_probability, Assessed_quantiles, Quantile_probability )</code>
:Variable QFlex_coefficients := <code>QFlexFit( Quantile_probability, Assessed_quantiles, Quantile_probability, K_terms, Gamma_to_use )</code>
:Chance Fitted_distribution := <code>QFlex( QFlex_coefficients, K_terms, Gamma_to_use )</code>

Now <code>Fitted_distribution</code> is an uncertain quantity you can use anywhere in your model. You can also read the fitted distribution analytically at specific points:

:<code>CumQFlexInv( 0.9, QFlex_coefficients, K_terms, Gamma_to_use )</code>   ''the fitted 90th percentile''
:<code>CumQFlex( x, QFlex_coefficients, K_terms, Gamma_to_use )</code>   ''the CDF, P(X ≤ x)''
:<code>DensQFlex( x, QFlex_coefficients, K_terms, Gamma_to_use )</code>   ''the density (PDF) at x''

=== Bounded and semi-bounded fits ===

To fit a distribution known to be non-negative (for example, a cost or a physical quantity), pass a lower bound to the construction and evaluation functions:

:<code>QFlex( QFlex_coefficients, K_terms, Gamma_to_use, lb: 0 )</code>   ''lower-bounded at 0''
:<code>QFlex( QFlex_coefficients, K_terms, Gamma_to_use, lb: 0, ub: 100 )</code>   ''bounded on [0, 100]''

Use the same «lb» and «ub» consistently across <code>QFlex</code>, <code>CumQFlex</code>, <code>CumQFlexInv</code>, and <code>DensQFlex</code> so they all describe the same distribution.

== Fitting the distribution to your data ==

These two functions are used '''before''' constructing the distribution, to estimate the centering parameter and fit the coefficients.

=== QFlexEstimateGamma( p, q, I ) ===

Estimates the QFlex centering parameter «gamma» from assessed probability-quantile pairs («p», «q») indexed by «I». It estimates Q(0.1), Q(0.5), and Q(0.9) from your assessed quantiles by interpolation, computes the Kelly skewness index ''SI'', and returns gamma = 0.5 × (1 − ''SI''), clipped to the open interval (0, 1).

* «p»: The assessed probabilities, each in (0, 1), indexed by «I».
* «q»: The corresponding assessed quantile values, indexed by «I».
* «I»: The [[Index]] over the assessments.

Returns gamma = 0.5 for a symmetric assessment with no skew (0.45 in the exactly symmetric case, matching the paper's convention), a value greater than 0.5 for right-skewed assessments, and less than 0.5 for left-skewed ones. If fewer than three points are supplied, it returns 0.5.

''Why «gamma» matters:'' it centers the centered-uniform basis terms. Choosing «gamma» from the assessed skewness (rather than always 0.5) keeps the fit well-conditioned — important especially when your assessed probabilities are symmetric about 0.5.

=== QFlexFit( p, q, I, K, ''gamma, numTerms'' ) ===

Fits the QFlex coefficient vector «a» (indexed by «K») to your assessed pairs («p», «q») by constrained least squares: it minimizes squared quantile error subject to the monotonicity constraints (tail-coefficient nonnegativity and the tail-center magnitude bound) from the paper, so the fitted distribution is '''valid by construction'''. '''Requires the [[Analytica Optimizer]] edition''' (the fit is a QP).

* «p», «q»: The assessed probabilities and quantiles, indexed by «I».
* «I»: The [[Index]] over the assessments.
* «K»: The coefficient [[Index]]; its length sets the maximum number of terms.
* «gamma»: (Optional): The centering parameter. If omitted, <code>QFlexFit</code> estimates it internally via <code>QFlexEstimateGamma</code>. '''Best practice:''' compute «gamma» once with <code>QFlexEstimateGamma</code> and pass it explicitly, so the same value is used for both fitting and evaluation.
* «numTerms»: (Optional): How many terms (≤ <code>IndexLength(K)</code>) to actually fit. If omitted, all of «K» is used. If «numTerms» is less than the length of «K», the result is still indexed by «K» and is <code>Null</code> in the positions beyond «numTerms».

'''Returns''' the coefficient vector «a» indexed by «K» (with <code>Null</code> in any unused positions). Pass this vector, with the same «K» and «gamma», to <code>QFlex</code>, <code>CumQFlex</code>, <code>CumQFlexInv</code>, or <code>DensQFlex</code>.

== Analytic distribution functions ==

These functions evaluate the fitted distribution analytically at a point (or an array of points), without sampling. They all take the fitted coefficient vector «a» indexed by «K», the centering parameter «gamma», and the same optional bounds «lb»/«ub» described under [[#QFlex( a, K, gamma, lb, ub )|QFlex]].

=== CumQFlexInv( p, a, K, ''gamma, lb, ub'' ) ===

The analytic '''inverse cumulative (quantile) function''': returns the value «x» such that P(X ≤ «x») = «p». Evaluate it at a probability «p» (or an array of probabilities) to read quantiles off the fitted distribution. This is the closed-form construction; <code>QFlex</code> simply calls it with a uniform random «p».

* «p»: A probability in [0, 1] (or an array of them).
* «a», «K», «gamma», «lb», «ub»: As for <code>QFlex</code>.

'''Example:''' <code>CumQFlexInv( 0.9, QFlex_coefficients, K_terms, Gamma_to_use )</code> returns the fitted 90th percentile.

=== CumQFlex( x, a, K, ''gamma, lb, ub'' ) ===

The analytic '''cumulative distribution function''': returns P(X ≤ «x») for a value «x». It is computed by numerically inverting the quantile function (bisection), giving the analytic CDF at a point, independent of sampling.

* «x»: The value (or array of values) at which to evaluate the CDF.
* «a», «K», «gamma», «lb», «ub»: As for <code>QFlex</code>.

'''Example:''' <code>CumQFlex( 0, QFlex_coefficients, K_terms, Gamma_to_use )</code>

=== DensQFlex( x, a, K, ''gamma, lb, ub'' ) ===

The analytic '''probability density function''' f(«x»): returns the density at a value «x», using the quantile-density relationship (no sampling required). This is convenient for plotting a smooth PDF curve over a grid of «x» values.

* «x»: The value (or array of values) at which to evaluate the density.
* «a», «K», «gamma», «lb», «ub»: As for <code>QFlex</code>.

'''Example:''' <code>DensQFlex( Plot_x, QFlex_coefficients, K_terms, Gamma_to_use )</code>

'''Note on bounds:''' An upper bound must be supplied together with a lower bound. Specifying «ub» without «lb» is not supported, and the analytic CDF/PDF return <code>Null</code> in that case. For an upper-bounded quantity, use the bounded [«lb», «ub»] form.

== The demo model ==

The demo model <code>Demo of QFlex distribution.ana</code> provides an interactive playground:
* Editable assessed quantiles for several example data sets (a symmetric logistic, a right-skewed lognormal, a heavy-tailed Student-''t'', and two bimodal shapes), selectable individually.
* A number-of-terms control to explore how flexibility changes the fit.
* Live graphs of the fitted inverse CDF, CDF, and PDF, built from <code>CumQFlexInv</code>, <code>CumQFlex</code>, and <code>DensQFlex</code>.
* A QA-tests module with analytically tractable checks (for example, the coefficient vector «a» = [0, 1, 1] reproduces the standard logistic quantile), useful as worked sanity checks.

== See Also ==

* [[Keelin (MetaLog) distribution]] — a related quantile-parameterized distribution.
* [[UncertainLMH]] — simpler option when you have only a low-medium-high (e.g. 10-50-90) assessment.
* [[Analytica Optimizer]] — the edition required for fitting.
* [[Distribution Densities Library]]
* [[Probability Distributions]]

QFlex distribution

2026-06-23T23:18:57Z

Lchrisman: Create QFlex distribution page (downloadable library; requires Optimizer). Draft — placeholder download links pending.

[[category:Continuous distributions]]
[[category:Unbounded distributions]]
[[category:Bounded distributions]]
[[category:Semi-bounded distributions]]
[[category:Univariate distributions]]
[[category:Custom distributions]]
{{ReleaseBar}}
''Provided by a downloadable add-in library (not a built-in distribution). Fitting requires the [[Analytica Optimizer]] edition.''

== QFlex( a, ''K, gamma, lb, ub'' ) ==

The ''QFlex distribution'' ("Quantile Flexibility") is a flexible, quantile-parameterized distribution capable of fitting a wide variety of continuous shapes directly to a set of assessed quantiles — for example a 10-50-90 judgment, or a larger set of assessed percentiles. Use it when standard parametric distributions such as the [[Normal distribution|Normal]], [[Log-normal distribution|LogNormal]], or [[Beta distribution|Beta]] are too restrictive to match what you have assessed, and you want a single smooth distribution that passes through (or near) your elicited quantiles while remaining a valid probability distribution.

You obtain the coefficient vector «a» by fitting it to your assessed quantiles with <code>QFlexFit</code> (see [[#How to use the library|How to use the library]] below). <code>QFlex</code> then draws a sampled, uncertain value from the fitted distribution, much as you would use a built-in distribution like <code>Normal</code> or <code>LogNormal</code>. Define a Chance variable as <code>QFlex(...)</code>.

;Reference
:Bickel, J. Eric, Connor Colombe, and Benjamin D. Leibowicz. ''The QFlex Distribution.'' The University of Texas at Austin. '''(Under review for publication, June 2026.)'''
:''The QFlex distribution and the methods implemented in this library are described in this paper. Because the paper is currently in review, the citation details may change.''

'''QFlex is not a built-in Analytica distribution.''' It is provided as a downloadable [[Libraries|library]] (see [[#Download and installation|Download and installation]]). Because the coefficient fit is solved as a quadratic program (QP), the [[Analytica Optimizer]] edition is required to fit a QFlex distribution to your data.

=== Parameters ===
* «a»: The QFlex coefficient vector, indexed by «K». You normally obtain this from <code>QFlexFit</code>.
* «K»: The coefficient [[Index]]. Its length is the maximum number of terms. Use, e.g., <code>K := 1..10</code>. (A 1-term QFlex is not a valid distribution, so use at least 2; more terms give a more flexible fit.)
* «gamma»: (Optional, default 0.5): The centering parameter. Use the same «gamma» that you used when fitting «a». See <code>QFlexEstimateGamma</code>.
* «lb», «ub»: (Optional): The support bounds. Omit both for an '''unbounded''' distribution; supply «lb» only for a '''lower-bounded''' [«lb», ∞) distribution; supply both for a '''bounded''' [«lb», «ub»] distribution.

== About the QFlex distribution ==

Internally, QFlex builds the distribution's quantile function (the inverse CDF) as a weighted sum of simple, individually valid building blocks: powers of a right-tail exponential, a left-tail (reflected) exponential, and a centered-uniform term. Because every building block is itself a valid, strictly increasing quantile function, a QFlex fit can be kept '''monotone — a genuine probability distribution — by construction''', through simple conditions on its coefficients. This is its main practical advantage over some other flexible quantile-parameterized families such as the [[Keelin (MetaLog) distribution|Keelin (MetaLog)]] distribution, which can require after-the-fact numerical "repair" to restore monotonicity.

Consider QFlex when:
* You have '''more assessed (or empirical) quantiles than a standard 2-3 parameter distribution can honor''', and you want the distribution to match them rather than only approximate their mean and spread.
* You want a '''smooth, valid continuous distribution''' (with an analytic CDF and PDF) rather than a discrete or purely empirical one.
* You need '''control over skewness and tail behavior''', or want to shape the left tail, right tail, and center somewhat independently.
* Your quantity is '''unbounded, lower-bounded, or bounded''' — QFlex supports all three.

The number of terms (the length of «K») controls flexibility: more terms can match more assessed quantiles and more complex shapes. With «K» terms you can interpolate up to «K» probability-quantile pairs; with more assessed pairs than terms, the fit is a constrained least-squares fit. You do '''not''' need to work through the paper's mathematics to use the library — the functions encapsulate the fitting and the analytic details for practical model building.

== Download and installation ==

QFlex is distributed as an Analytica library plus a demonstration model, both plain <code>.ana</code> files:
* '''Library:''' <code>QFlex distribution library.ana</code> — '''[download link to be added]'''
* '''Demo model:''' <code>Demo of QFlex distribution.ana</code> — '''[download link to be added]'''

To use the library in your own model, open your model and choose '''File → Add Library...''', select <code>QFlex distribution library.ana</code>, and link it. The library's functions then become available in your model. The demo model already includes the library and shows the full workflow.

=== Requirements ===
* '''[[Analytica Optimizer]] edition.''' The fitting function <code>QFlexFit</code> solves a quadratic program, which requires Optimizer. (Once you have a fitted coefficient vector, the remaining functions — <code>QFlex</code>, <code>CumQFlex</code>, <code>CumQFlexInv</code>, and <code>DensQFlex</code> — are ordinary evaluations and do not themselves require Optimizer; but in normal use you fit with <code>QFlexFit</code>, so Optimizer is required.)
* Analytica 7.x or later is recommended.

== How to use the library ==

The workflow has three steps:

# '''Compute the centering parameter «gamma».''' Use <code>QFlexEstimateGamma( p, q, I )</code> on your assessed probability-quantile pairs, or specify a «gamma» yourself if you have a preferred value. Keep that «gamma» and pass the '''same''' value to the later functions.
# '''Fit the coefficient vector «a».''' Use <code>QFlexFit( p, q, I, K, gamma, numTerms )</code> with your probabilities «p», quantiles «q», the assessment index «I», and the coefficient index «K». ''(This step requires the Optimizer edition.)''
# '''Use the fitted distribution.''' Call <code>QFlex( a, K, gamma, lb, ub )</code> to construct the uncertain quantity, or use <code>CumQFlexInv</code>, <code>CumQFlex</code>, and <code>DensQFlex</code> for the inverse CDF, CDF, and density at specific points. Use the '''same «gamma» and «K»''' that you used when fitting.

Because «gamma» is an explicit parameter to the QFlex functions, it is best to compute or choose «gamma» once and then pass that same value consistently to the fitting and evaluation functions.

== Examples ==

=== Fit to assessed quantiles ===

Suppose you have assessed ten quantiles of an uncertain quantity. Define an index of the assessed probabilities, the assessed quantile values, and a coefficient index:

:Index Quantile_probability := <code>[0.01, 0.05, 0.1, 0.25, 0.5, 0.75, 0.9, 0.95, 0.99, 0.999]</code>
:Variable Assessed_quantiles := <code>Table( Quantile_probability )( ... )</code>   ''(your ten assessed quantile values)''
:Index K_terms := <code>1..10</code>

Then carry out the three steps:

:Variable Gamma_to_use := <code>QFlexEstimateGamma( Quantile_probability, Assessed_quantiles, Quantile_probability )</code>
:Variable QFlex_coefficients := <code>QFlexFit( Quantile_probability, Assessed_quantiles, Quantile_probability, K_terms, Gamma_to_use )</code>
:Chance Fitted_distribution := <code>QFlex( QFlex_coefficients, K_terms, Gamma_to_use )</code>

Now <code>Fitted_distribution</code> is an uncertain quantity you can use anywhere in your model. You can also read the fitted distribution analytically at specific points:

:<code>CumQFlexInv( 0.9, QFlex_coefficients, K_terms, Gamma_to_use )</code>   ''the fitted 90th percentile''
:<code>CumQFlex( x, QFlex_coefficients, K_terms, Gamma_to_use )</code>   ''the CDF, P(X ≤ x)''
:<code>DensQFlex( x, QFlex_coefficients, K_terms, Gamma_to_use )</code>   ''the density (PDF) at x''

=== Bounded and semi-bounded fits ===

To fit a distribution known to be non-negative (for example, a cost or a physical quantity), pass a lower bound to the construction and evaluation functions:

:<code>QFlex( QFlex_coefficients, K_terms, Gamma_to_use, lb: 0 )</code>   ''lower-bounded at 0''
:<code>QFlex( QFlex_coefficients, K_terms, Gamma_to_use, lb: 0, ub: 100 )</code>   ''bounded on [0, 100]''

Use the same «lb» and «ub» consistently across <code>QFlex</code>, <code>CumQFlex</code>, <code>CumQFlexInv</code>, and <code>DensQFlex</code> so they all describe the same distribution.

== Fitting the distribution to your data ==

These two functions are used '''before''' constructing the distribution, to estimate the centering parameter and fit the coefficients.

=== QFlexEstimateGamma( p, q, I ) ===

Estimates the QFlex centering parameter «gamma» from assessed probability-quantile pairs («p», «q») indexed by «I». It estimates Q(0.1), Q(0.5), and Q(0.9) from your assessed quantiles by interpolation, computes the Kelly skewness index ''SI'', and returns gamma = 0.5 × (1 − ''SI''), clipped to the open interval (0, 1).

* «p»: The assessed probabilities, each in (0, 1), indexed by «I».
* «q»: The corresponding assessed quantile values, indexed by «I».
* «I»: The [[Index]] over the assessments.

Returns gamma = 0.5 for a symmetric assessment with no skew (0.45 in the exactly symmetric case, matching the paper's convention), a value greater than 0.5 for right-skewed assessments, and less than 0.5 for left-skewed ones. If fewer than three points are supplied, it returns 0.5.

''Why «gamma» matters:'' it centers the centered-uniform basis terms. Choosing «gamma» from the assessed skewness (rather than always 0.5) keeps the fit well-conditioned — important especially when your assessed probabilities are symmetric about 0.5.

=== QFlexFit( p, q, I, K, ''gamma, numTerms'' ) ===

Fits the QFlex coefficient vector «a» (indexed by «K») to your assessed pairs («p», «q») by constrained least squares: it minimizes squared quantile error subject to the monotonicity constraints (tail-coefficient nonnegativity and the tail-center magnitude bound) from the paper, so the fitted distribution is '''valid by construction'''. '''Requires the [[Analytica Optimizer]] edition''' (the fit is a QP).

* «p», «q»: The assessed probabilities and quantiles, indexed by «I».
* «I»: The [[Index]] over the assessments.
* «K»: The coefficient [[Index]]; its length sets the maximum number of terms.
* «gamma»: (Optional): The centering parameter. If omitted, <code>QFlexFit</code> estimates it internally via <code>QFlexEstimateGamma</code>. '''Best practice:''' compute «gamma» once with <code>QFlexEstimateGamma</code> and pass it explicitly, so the same value is used for both fitting and evaluation.
* «numTerms»: (Optional): How many terms (≤ <code>IndexLength(K)</code>) to actually fit. If omitted, all of «K» is used. If «numTerms» is less than the length of «K», the result is still indexed by «K» and is <code>Null</code> in the positions beyond «numTerms».

'''Returns''' the coefficient vector «a» indexed by «K» (with <code>Null</code> in any unused positions). Pass this vector, with the same «K» and «gamma», to <code>QFlex</code>, <code>CumQFlex</code>, <code>CumQFlexInv</code>, or <code>DensQFlex</code>.

== Analytic distribution functions ==

These functions evaluate the fitted distribution analytically at a point (or an array of points), without sampling. They all take the fitted coefficient vector «a» indexed by «K», the centering parameter «gamma», and the same optional bounds «lb»/«ub» described under [[#QFlex( a, K, gamma, lb, ub )|QFlex]].

=== CumQFlexInv( p, a, K, ''gamma, lb, ub'' ) ===

The analytic '''inverse cumulative (quantile) function''': returns the value «x» such that P(X ≤ «x») = «p». Evaluate it at a probability «p» (or an array of probabilities) to read quantiles off the fitted distribution. This is the closed-form construction; <code>QFlex</code> simply calls it with a uniform random «p».

* «p»: A probability in [0, 1] (or an array of them).
* «a», «K», «gamma», «lb», «ub»: As for <code>QFlex</code>.

'''Example:''' <code>CumQFlexInv( 0.9, QFlex_coefficients, K_terms, Gamma_to_use )</code> returns the fitted 90th percentile.

=== CumQFlex( x, a, K, ''gamma, lb, ub'' ) ===

The analytic '''cumulative distribution function''': returns P(X ≤ «x») for a value «x». It is computed by numerically inverting the quantile function (bisection), giving the analytic CDF at a point, independent of sampling.

* «x»: The value (or array of values) at which to evaluate the CDF.
* «a», «K», «gamma», «lb», «ub»: As for <code>QFlex</code>.

'''Example:''' <code>CumQFlex( 0, QFlex_coefficients, K_terms, Gamma_to_use )</code>

=== DensQFlex( x, a, K, ''gamma, lb, ub'' ) ===

The analytic '''probability density function''' f(«x»): returns the density at a value «x», using the quantile-density relationship (no sampling required). This is convenient for plotting a smooth PDF curve over a grid of «x» values.

* «x»: The value (or array of values) at which to evaluate the density.
* «a», «K», «gamma», «lb», «ub»: As for <code>QFlex</code>.

'''Example:''' <code>DensQFlex( Plot_x, QFlex_coefficients, K_terms, Gamma_to_use )</code>

'''Note on bounds:''' An upper bound must be supplied together with a lower bound. Specifying «ub» without «lb» is not supported, and the analytic CDF/PDF return <code>Null</code> in that case. For an upper-bounded quantity, use the bounded [«lb», «ub»] form.

== The demo model ==

The demo model <code>Demo of QFlex distribution.ana</code> provides an interactive playground:
* Editable assessed quantiles for several example data sets (a symmetric logistic, a right-skewed lognormal, a heavy-tailed Student-''t'', and two bimodal shapes), selectable individually.
* A number-of-terms control to explore how flexibility changes the fit.
* Live graphs of the fitted inverse CDF, CDF, and PDF, built from <code>CumQFlexInv</code>, <code>CumQFlex</code>, and <code>DensQFlex</code>.
* A QA-tests module with analytically tractable checks (for example, the coefficient vector «a» = [0, 1, 1] reproduces the standard logistic quantile), useful as worked sanity checks.

== See Also ==

* [[Keelin (MetaLog) distribution]] — a related quantile-parameterized distribution.
* [[UncertainLMH]] — simpler option when you have only a low-medium-high (e.g. 10-50-90) assessment.
* [[Analytica Optimizer]] — the edition required for fitting.
* [[Distribution Densities Library]]
* [[Probability Distributions]]

What's new in Analytica 7.1?

2026-06-22T18:23:02Z

Lchrisman: /* Misc. User Interface */

This page lists new features in release 7.1, which is currently in early [[Beta Tester Page|Beta Testing]]. If have have an active subscription license, we encourage you to try it out from the [[Beta Tester Page]].

== Window appearance ==
The appearance of the chrome around child MDI windows (aka the "non-client area") has been changed to more closely match the Windows 11 style of windows -- i.e., thin (1 pixel) borders, rounded corners at the top, white title bar, very plain (text-like) button images in the toolbar.

== Assista ==
[[Assista]] is Analytica's A.I. assistant. She is greatly improved in this release.
* Her UI is now a top-level window that resides at the same level as Analytica's main application window.
** You can move her chat window to a non-overlapping location or even a different monitor (to maximize screen real estate used by your Analytica window).
** Selected objects remain visually selected in the main window when you type into Assista.
* Her chat has a different look-and-feel.
* Her chat window is faster and more responsive
* You can drag-highlight any text in her chat and copy to paste elsewhere.
* The UI has improved formatting capabilities for displaying Assista's response.
* Her "thoughts" display as she is processing your prompt, making it clear she is working and even giving you a peek into how she is solving it.
* She has a new processing pipeline on the backend, enabling her to respond faster but also work longer on harder tasks.
* She has an extended set of competencies (skills).
* Your sessions are automatically saved, keyed to your model, and you can resume a previous session for that model from a session selector dropdown in the UI.
* You can create and expose [[Assista_-_Analytica_AI_Assistant/Custom_user_skills_for_Assista|your own custom skills]] to expand her capabilities, or ask her to do it for you.
* You can add or drag-and-drop a document (<code>*.txt, *.pdf, *.md, *.docx, *.xlsx, *.xlsm</code>) or URLs into the chat which Assista can "ingest" during your conversation. Have her extract data from the doc, adding tables to your model. Or even to implement a model described by the paper or translate a spreadsheet into an Analytica model.
* Assista can "see" images in your model -- pictures in nodes, images in table cells, and diagram or graph screenshots.
* She is language-aware. If you are using Analytica is Spanish, she'll provide UI instructions that refer to the Spanish-language UI elements.
* She is aware of her reasoning in previous conversation turns and the actions she took, enabling her to explain her reasoning or build on ideas she thought about but might not have included in the final response.
* She has an improved ability to navigate and find objects within your (large) models.
* You can personalize her tone, style, level of verbosity and provide her custom instructions. To do this, click on the icon in the top-left corner of the Assista window and select Personization...

== Multi-linguality: Spanish UI ==
Analytica now comes with a Spanish-language UI, in which its menus, dialogs, error messages and built-in function descriptions are all in Spanish. Also its installer runs with a Spanish-language UI when you are in a Spanish-language region. Spanish is the default when you are in a Spanish-language region.

You can override the default language by launching Analytica as:
* <code>Analytica.exe /lang:es</code>
*: or
* <code>Analytica.exe /lang:en</code>

You can also set the <code>Language</code> registry setting in the <code>"HKCU/Software/Lumina Decision Systems/Analytica"</code> hive to REG_SZ <code>"en"</code> on <code>"es"</code> for your default if different from your windows region setting.

Some of you may ask "what about my language?". Stay tuned (and let us know there is a demand for your language). Once our AI translation pipeline is solid, it shouldn't be too hard for us to add more.

== CSV files ==
There are now a few additional ways to open CSV files in Analytica:
* On the command line: <code>Analytica.exe MyData.csv</code>
* Drag and drop a *.csv file onto the diagram (which behaves the same as using <code>File / Import...</code> on the *.csv file).

== Spreadsheets ==
* <code>[[SpreadsheetOpen]]("new")</code> now creates a blank spreadsheet in memory. Works with both the Excel and LibXl backends.
* Prefacing a sheet name with + in the call to [[SpreadsheetSetCell]] or [[SpreadsheetSetRange]] will add a new sheet by that name to the workbook (as it applies the specified change to that new worksheet). Works with either backend.
* You can also now remove a sheet from a workbook using: <code>[[SpreadsheetSetCell]](wb, "-OldSheet", col, row, Null)</code>. The «col» and «row» parameters are required but ignored in this case.

== Misc. User Interface ==
* The Node Icon editor (on the Diagram menu) is more featureful and can be used to edit arbitrary node images, with support for color and transparency.
* Added keyboard shortcuts for '''Set Node Style...''' and '''Set Diagram Style...'''
* There is a new option, '''Use as default arrow style''', on the right-mouse context menu for an influence diagram arrow. This sets the global arrow style default to match the selected arrow.

== Built-in functions ==
* New options for [[GetProcessInfo]]: <code>"Number of monitors"</code>, <code>"Current monitor rect"</code>, <code>"Current monitor work rect"</code>, <code>"Monitor «N» Rect"</code>, and <code>"Monitor «N» work rect"</code>.
* New optional parameter, «throwParsingErrors», to [[Evaluate]].
* [[ReadFromURL]] is a bit smarter about returning binary content (like <code>*.zip</code> files) as a [[In-memory binary data terms|Binary Data Term]].
* [[MakeJSON]] will automatically encode an image in base64 JSON, and [[ParseJSON]] will automatically decode a base64 representation into an image.
* <code>[[GetProcessInfo]]("UI Language")</code> returns the UI language, either <code>"en"</code> (for English) or <code>"es"</code> for Spanish.
* <code>[[QualifiedName]]( obj, nsContext )</code>: Returns the qualified identifier (as text) that uniquely identifies «obj» from the context of «nsContext».
* <code>[[Namespace]] of X</code>: A new virtual attribute that returns the namespace of «X».
* [[Evaluate]] has a second return value that captures output to the typescript window (including stuff written by [[ConsolePrint]]) during the evaluation. It also has a new optional «ignoreAtFirstWarning» parameter that can be used in conjunction, capturing the first warning text in that second return value, not showing the return value to the user, and ignoring additional warnings during the duration of the Evaluate call (enables Assista to see the warnings).
* Added a syntax construct for [[Namespaces#Scoped_namespace_inclusion:_Using|Scoped namespace inclusion]] to bring a namespace into scope for only a localized expression or lexical block.

== System variables ==
* SysVar [[Graph_ColorSequence]]: Replaces [[Graph_ColorSeq]] which is now deprecated. The new sysvar contains a list of color interer with one integer (of the form <code>0x00rrggbb</code>) per color (whereas the deprecated used triples of numbers per color).

== Engine ==
* After loading a large model, it parses expressions in parallel, using multiple threads/cores to parse different variables. On some computers on some models, this can dramatically speed up model load time.
* Color attributes use color integers for consistently (rather than the legacy number triples for R,G,B).
* You can use a localized namespace import (for a single expression or single lexical block) with the syntax
*:<code>[[Using..Do|Using]] NS;</code>

== Model loading ==
When opening a model file, the "checking" stage (when attributes are parsed) parses different expressions on different threads, resulting in substantially faster model load times for very large models.

Note: In the event that this creates a problem with your specific model (maybe due to an as-yet-undiscovered multithreading bug), you can disable it for your model as follows:
# Temporarily turn off multithreading (Skip this step if you are able to load your model)
## New model
## <b>Definition menu / System variables / Settings / Maximum evaluation threads</b>
## Set to 1 (and remember the previous value)
# Open your model
# <b>Definition menu / System variables / Settings / Disable Multithreaded Evaluations</b>
# Press the <code>Edit Table</code> button.
# Check the checkbox for <code>Parsing</code>
# Save your model
# <b>Definition menu / System variables / Settings / Maximum evaluation threads</b>
#: Restore the original value from Step 1

== MCP server ==
* Added an ability to install multiple ADE-based Mcp servers that run different ADE releases. For example, you can install two MCP servers into Claude Code:
* ade-server: Runs ADE 7.1
* ade-server-70: Runs ADE 7.0
The information in the <code>«ADE install folder»\Examples\Mcp_server\README.txt</code> file explain how (with enough info for Claude code to configure this for you).

With both installed, Claude Code (or other MCP-enabled AI agents) can compare results for the same model across different releases, etc.

Side note: The Mcp server was added to ADE 7.0.

== Internals ==
This release has undergone massive internal restructuring and refactorization. Ideally (i.e., in the absence of bugs) these changes won't change functionality, but may alter some aspects of behavior, hopefully for the better.
* Internal data structures use for multi-dimensional arrays has been changed. Possible impacts:
** Likely to remove the sensitivity to the "canonical order" of indexes on evaluation speed.
** May change relative evaluation speeds of various functions and operations.
* Added system modules/namespaces: <code>SysLib_Internal</code> and <code>SysLib_Experimental</code>. Intended for Analytica-internal use.
*[[:Category:Cell format functions|Cell formatting functions]] (like [[CellSpan]], [[CellFill]], etc.) are now [[Struct]]s rather than functions. Does not impact usage, other that making it easier for code to traverse resulting data structures.

== Discontinued... ==
* Plug-in functions. (An old hook that allows you to extend Analytica with compiled functions and UI elements written it C++. We are almost certain no one is using these hooks any more.)
* The sysvar [[Graph_ColorSeq]] is now deprecated (but works for both reading and setting to preserve backward compatibility). It has been replaced by the system variable [[Graph_ColorSequence]].
* The built-in (but undocumented, unsupported) <code>ifpos</code> and <code>if0</code> functions were removed.
* The legacy (deprecated) syntax <code>Using temp:=... Do</code> for declaring locals is no longer supported. Legacy models will have such definitions automatically rewritten to use [[Local..Do]] when you load them. [[Using..Do]] now has a different meaning, which is to provide a temporary namespace import.

Arrow bends, curves, and styles

2026-06-22T18:21:39Z

Lchrisman: /* Arrow menu */

New to [[What's new in Analytica 6.0?|Analytica 6.0]]

{{ReleaseBar}}

You can modify Influence Arrows to have multiple line segments or curves -- very handy when you want to avoid arrows crossing other arrows or nodes. You can also set an arrow's thickness, linestyle, colors, and more.

== Bends and Curves ==

Here's how to add segments or spline curves to an influence arrow in Edit mode:
* Click a straight arrow to select it. It will show a square and round handles in the middle of the arrow.
* To bend the arrow into two straight line segments, drag the square handle.
* To add a curve to the arrow, drag the round handle.

<center>[[image:Example with curved colored styles arrows.png|400px]]</center>

To modify a segmented or curved arrow, click the arrow to select it and then:
* To move the waypoints (the dark circles or squares), just drag them.
* To add another lines or curve, drag a new midpoint (open circle or square).
* You can also move the start point or end point of an arrow where it meets a node border. Simply drag the point along the border.

== Arrow menu ==

Use the arrow menu to further modify the arrow styles.
* Click an arrow to select it.
* Shift-click on additional arrow(s) if you want to select several.
* Right-click a selected arrow to show the arrow context menu:

<center>[[image:Arrow menu.png|500px]]</center>
* Then select:
** '''Curved''' to toggle between curved and straight segments.
** '''Remove way point''' to remove a segment.
** '''Remove all way points''' to restore a simple straight arrow.
** '''Dash style''' and then select solid, dashes, dots, dash-dot, or Dash-dot-dot.
** '''Double line''' to show the arrow as two lines.
** '''Thickness''' and then select a number to make the arrow thicker or thinner.
** '''Show color palette''' to show the [[Color palette]]. Click a color from the palette to color the selected arrow(s).{{Release|1=7.1|2=|3=
** '''Use as default arrow style''' (''new in [[Analytica 7.1]]'') to set the global default arrow styles to match the style for the selected arrow.}}


=== Show or hide arrows ===

You can use the [[Diagram Style dialog]] for each Diagram (Module) to control whether to show arrows to and from indexes and functions (off by default) or modules (on by default). You can use the [[Node Style dialog]] for one or more selected nodes to control whether to show arrows from all its inputs or to all its outputs. You can use the Arrow menu above to show or hide individual arrows:

To hide an arrow,
* Click the arrow to select it
* Right-click to show the Arrow menu.
* Select '''Hide arrow'''

To show a hidden arrow,
* You'll need to click around where you think it might be until you manage to select it.
* Right click to show the Arrow menu
* Select '''Show arrow''' to show the hidden arrow



== Examples==
<center>[[image:System dynamics diagram with curved arrows.png|600px]]</center>

<center> An influence diagram using Systems Dynamics notation for a software business. All nodes have their borders hidden, except for the stock nodes (rectangles using Decisions). The flows to and between stocks use the double arrow style. The cloud (source or sink for stock flows in Systems Dynamics is an image pasted into a node. So is the "valve" image that controls stock flows.</center>

<center>[[image:Influence diagram with curved arrows for supply chain model.png|400px]]

An influence diagram for a supply chain model for a beer brewery.
Curved arrows show influences that go in both directions between modules.</center>

== See also ==
* [[Draw arrows]]
* [[Draw arrows between modules]]

Arrow bends, curves, and styles

2026-06-22T18:21:17Z

Lchrisman: /* Arrow menu */

New to [[What's new in Analytica 6.0?|Analytica 6.0]]

{{ReleaseBar}}

You can modify Influence Arrows to have multiple line segments or curves -- very handy when you want to avoid arrows crossing other arrows or nodes. You can also set an arrow's thickness, linestyle, colors, and more.

== Bends and Curves ==

Here's how to add segments or spline curves to an influence arrow in Edit mode:
* Click a straight arrow to select it. It will show a square and round handles in the middle of the arrow.
* To bend the arrow into two straight line segments, drag the square handle.
* To add a curve to the arrow, drag the round handle.

<center>[[image:Example with curved colored styles arrows.png|400px]]</center>

To modify a segmented or curved arrow, click the arrow to select it and then:
* To move the waypoints (the dark circles or squares), just drag them.
* To add another lines or curve, drag a new midpoint (open circle or square).
* You can also move the start point or end point of an arrow where it meets a node border. Simply drag the point along the border.

== Arrow menu ==

Use the arrow menu to further modify the arrow styles.
* Click an arrow to select it.
* Shift-click on additional arrow(s) if you want to select several.
* Right-click a selected arrow to show the arrow context menu:

<center>[[image:Arrow menu.png|500px]]</center>
* Then select:
** '''Curved''' to toggle between curved and straight segments.
** '''Remove way point''' to remove a segment.
** '''Remove all way points''' to restore a simple straight arrow.
** '''Dash style''' and then select solid, dashes, dots, dash-dot, or Dash-dot-dot.
** '''Double line''' to show the arrow as two lines.
** '''Thickness''' and then select a number to make the arrow thicker or thinner.
** '''Show color palette''' (''new in [[Analytica 7.1]]'') to show the [[Color palette]]. Click a color from the palette to color the selected arrow(s).{{Release|1=7.1|2=|3=
** '''Use as default arrow style''' to set the global default arrow styles to match the style for the selected arrow.}}


=== Show or hide arrows ===

You can use the [[Diagram Style dialog]] for each Diagram (Module) to control whether to show arrows to and from indexes and functions (off by default) or modules (on by default). You can use the [[Node Style dialog]] for one or more selected nodes to control whether to show arrows from all its inputs or to all its outputs. You can use the Arrow menu above to show or hide individual arrows:

To hide an arrow,
* Click the arrow to select it
* Right-click to show the Arrow menu.
* Select '''Hide arrow'''

To show a hidden arrow,
* You'll need to click around where you think it might be until you manage to select it.
* Right click to show the Arrow menu
* Select '''Show arrow''' to show the hidden arrow



== Examples==
<center>[[image:System dynamics diagram with curved arrows.png|600px]]</center>

<center> An influence diagram using Systems Dynamics notation for a software business. All nodes have their borders hidden, except for the stock nodes (rectangles using Decisions). The flows to and between stocks use the double arrow style. The cloud (source or sink for stock flows in Systems Dynamics is an image pasted into a node. So is the "valve" image that controls stock flows.</center>

<center>[[image:Influence diagram with curved arrows for supply chain model.png|400px]]

An influence diagram for a supply chain model for a beer brewery.
Curved arrows show influences that go in both directions between modules.</center>

== See also ==
* [[Draw arrows]]
* [[Draw arrows between modules]]

Arrow bends, curves, and styles

2026-06-22T18:20:32Z

Lchrisman: /* Arrow menu */ ER 22257 -- New "Use as default arrow style" option on context menu

New to [[What's new in Analytica 6.0?|Analytica 6.0]]

{{ReleaseBar}}

You can modify Influence Arrows to have multiple line segments or curves -- very handy when you want to avoid arrows crossing other arrows or nodes. You can also set an arrow's thickness, linestyle, colors, and more.

== Bends and Curves ==

Here's how to add segments or spline curves to an influence arrow in Edit mode:
* Click a straight arrow to select it. It will show a square and round handles in the middle of the arrow.
* To bend the arrow into two straight line segments, drag the square handle.
* To add a curve to the arrow, drag the round handle.

<center>[[image:Example with curved colored styles arrows.png|400px]]</center>

To modify a segmented or curved arrow, click the arrow to select it and then:
* To move the waypoints (the dark circles or squares), just drag them.
* To add another lines or curve, drag a new midpoint (open circle or square).
* You can also move the start point or end point of an arrow where it meets a node border. Simply drag the point along the border.

== Arrow menu ==

Use the arrow menu to further modify the arrow styles.
* Click an arrow to select it.
* Shift-click on additional arrow(s) if you want to select several.
* Right-click a selected arrow to show the arrow context menu:

<center>[[image:Arrow menu.png|500px]]</center>
* Then select:
** '''Curved''' to toggle between curved and straight segments.
** '''Remove way point''' to remove a segment.
** '''Remove all way points''' to restore a simple straight arrow.
** '''Dash style''' and then select solid, dashes, dots, dash-dot, or Dash-dot-dot.
** '''Double line''' to show the arrow as two lines.
** '''Thickness''' and then select a number to make the arrow thicker or thinner.
** '''Show color palette''' to show the [[Color palette]]. Click a color from the palette to color the selected arrow(s).
{{Release|1=7.1|2=|3=
** '''Use as default arrow style''' to set the global default arrow styles to match the style for the selected arrow.}}

=== Show or hide arrows ===

You can use the [[Diagram Style dialog]] for each Diagram (Module) to control whether to show arrows to and from indexes and functions (off by default) or modules (on by default). You can use the [[Node Style dialog]] for one or more selected nodes to control whether to show arrows from all its inputs or to all its outputs. You can use the Arrow menu above to show or hide individual arrows:

To hide an arrow,
* Click the arrow to select it
* Right-click to show the Arrow menu.
* Select '''Hide arrow'''

To show a hidden arrow,
* You'll need to click around where you think it might be until you manage to select it.
* Right click to show the Arrow menu
* Select '''Show arrow''' to show the hidden arrow



== Examples==
<center>[[image:System dynamics diagram with curved arrows.png|600px]]</center>

<center> An influence diagram using Systems Dynamics notation for a software business. All nodes have their borders hidden, except for the stock nodes (rectangles using Decisions). The flows to and between stocks use the double arrow style. The cloud (source or sink for stock flows in Systems Dynamics is an image pasted into a node. So is the "valve" image that controls stock flows.</center>

<center>[[image:Influence diagram with curved arrows for supply chain model.png|400px]]

An influence diagram for a supply chain model for a beer brewery.
Curved arrows show influences that go in both directions between modules.</center>

== See also ==
* [[Draw arrows]]
* [[Draw arrows between modules]]

Arrow bends, curves, and styles

2026-06-22T18:17:17Z

Lchrisman:

New to [[What's new in Analytica 6.0?|Analytica 6.0]]

{{ReleaseBar}}

You can modify Influence Arrows to have multiple line segments or curves -- very handy when you want to avoid arrows crossing other arrows or nodes. You can also set an arrow's thickness, linestyle, colors, and more.

== Bends and Curves ==

Here's how to add segments or spline curves to an influence arrow in Edit mode:
* Click a straight arrow to select it. It will show a square and round handles in the middle of the arrow.
* To bend the arrow into two straight line segments, drag the square handle.
* To add a curve to the arrow, drag the round handle.

<center>[[image:Example with curved colored styles arrows.png|400px]]</center>

To modify a segmented or curved arrow, click the arrow to select it and then:
* To move the waypoints (the dark circles or squares), just drag them.
* To add another lines or curve, drag a new midpoint (open circle or square).
* You can also move the start point or end point of an arrow where it meets a node border. Simply drag the point along the border.

== Arrow menu ==

Use the arrow menu to further modify the arrow styles.
* Click an arrow to select it.
* Shift-click on additional arrow(s) if you want to select several.
* Right-click a selected arrow to show the arrow context menu:

<center>[[image:Arrow menu.png|500px]]</center>
* Then select:
** '''Curved''' to toggle between curved and straight segments.
** '''Remove way point''' to remove a segment.
** '''Remove all way points''' to restore a simple straight arrow.
** '''Dash style''' and then select solid, dashes, dots, dash-dot, or Dash-dot-dot.
** '''Double line''' to show the arrow as two lines.
** '''Thickness''' and then select a number to make the arrow thicker or thinner.
** '''Show color palette''' to show the [[Color palette]]. Click a color from the palette to color the selected arrow(s).


=== Show or hide arrows ===

You can use the [[Diagram Style dialog]] for each Diagram (Module) to control whether to show arrows to and from indexes and functions (off by default) or modules (on by default). You can use the [[Node Style dialog]] for one or more selected nodes to control whether to show arrows from all its inputs or to all its outputs. You can use the Arrow menu above to show or hide individual arrows:

To hide an arrow,
* Click the arrow to select it
* Right-click to show the Arrow menu.
* Select '''Hide arrow'''

To show a hidden arrow,
* You'll need to click around where you think it might be until you manage to select it.
* Right click to show the Arrow menu
* Select '''Show arrow''' to show the hidden arrow


== Examples==
<center>[[image:System dynamics diagram with curved arrows.png|600px]]</center>

<center> An influence diagram using Systems Dynamics notation for a software business. All nodes have their borders hidden, except for the stock nodes (rectangles using Decisions). The flows to and between stocks use the double arrow style. The cloud (source or sink for stock flows in Systems Dynamics is an image pasted into a node. So is the "valve" image that controls stock flows.</center>

<center>[[image:Influence diagram with curved arrows for supply chain model.png|400px]]

An influence diagram for a supply chain model for a beer brewery.
Curved arrows show influences that go in both directions between modules.</center>

== See also ==
* [[Draw arrows]]
* [[Draw arrows between modules]]

CumDist - Custom continuous distribution using cumulative probabilities

2026-06-19T21:11:08Z

Lchrisman: It accepts r_i when it is non-descending but not scrictly increasing.

[[category:Continuous distributions]]
[[category:Bounded distributions]]
[[category:Custom distributions]]
[[category:Univariate distributions]]
[[Category:Doc Status C]] 
{{ReleaseBar}}

The <code>CumDist</code> functions are used to specify an arbitrarily shaped distribution by specifying points (pi,ri) on the cumulative probability curve.

== Functions ==

For each function below, the shape is described by two arrays, «p_i» and «r_i», each indexed by index «<code>I</code>». These are points on the cumulative density (CDF) curve. «p_i» and «r_i» must be non-decreasing along «<code>I</code>». The index «<code>I</code>» may be omitted when either «p_i» or «r_i» is itself an index.

In addition, an optional boolean «smooth» parameter (defaults to true) causes the CDF to be smooth and the PDF to be continuous. When set to False, the CDF is piecewise linear, which implies the PDF is piecewise constant and discontinuous.

; Naming convention note:
There is a convention that the Analytic functions use the names <code>Dens«Dist»()</code>, <code>Cum«Dist»()</code> and <code>Cum«Dist»Inv()</code>, where «Dist» is the distribution function name. That convention is used with this function, but results in the repeated "CumCum" for two of the functions. Also, this convention is applied to the [[ProbDist]] distribution function also, so be careful not to confuse [[CumProbDist]] with [[CumDist]], etc.

=== CumDist(p_i, r_i'', I, over, smooth'') ===

The distribution function. Use this function to describe a quantity having the custom distribution described by («p_i», «r_i»). To specify independent by identically distributed quantities along additional indexes, list those other indexes in the «over» parameter.

=== <div id="DensCumDist">DensCumDist(x, p_i, r_i'', I, smooth'')</div> ===
''New to [[Analytica 5.2]]''

Returns the probability density at each point in «x».

=== <div id="CumCumDist">CumCumDist(x, p_i, r_i'', I, smooth'')</div> ===
''New to [[Analytica 5.2]]''

Returns the cumulative probability at «x» -- the probability that the quantity is less than or equal to «x».

=== <div id="CumCumDistInv">CumCumDistInv(p, p_i, r_i'', I, smooth'')</div> ===
''New to [[Analytica 5.2]]''

The inverse cumulative probability. Returns the «p»<sup>th</sup> fractile/quantile/percentile.

== History ==
* The analytic functions are new to [[Analytica 5.2]].

== See Also ==
* [[ProbDist]]
* [[Fractiles]]
* [[Cdf and Pdf Functions]]
* [[Custom continuous distributions]]
* [[Distribution Densities Library]]

What's new in Analytica 7.1?

2026-06-17T14:27:30Z

Lchrisman:

This page lists new features in release 7.1, which is currently in early [[Beta Tester Page|Beta Testing]]. If have have an active subscription license, we encourage you to try it out from the [[Beta Tester Page]].

== Window appearance ==
The appearance of the chrome around child MDI windows (aka the "non-client area") has been changed to more closely match the Windows 11 style of windows -- i.e., thin (1 pixel) borders, rounded corners at the top, white title bar, very plain (text-like) button images in the toolbar.

== Assista ==
[[Assista]] is Analytica's A.I. assistant. She is greatly improved in this release.
* Her UI is now a top-level window that resides at the same level as Analytica's main application window.
** You can move her chat window to a non-overlapping location or even a different monitor (to maximize screen real estate used by your Analytica window).
** Selected objects remain visually selected in the main window when you type into Assista.
* Her chat has a different look-and-feel.
* Her chat window is faster and more responsive
* You can drag-highlight any text in her chat and copy to paste elsewhere.
* The UI has improved formatting capabilities for displaying Assista's response.
* Her "thoughts" display as she is processing your prompt, making it clear she is working and even giving you a peek into how she is solving it.
* She has a new processing pipeline on the backend, enabling her to respond faster but also work longer on harder tasks.
* She has an extended set of competencies (skills).
* Your sessions are automatically saved, keyed to your model, and you can resume a previous session for that model from a session selector dropdown in the UI.
* You can create and expose [[Assista_-_Analytica_AI_Assistant/Custom_user_skills_for_Assista|your own custom skills]] to expand her capabilities, or ask her to do it for you.
* You can add or drag-and-drop a document (<code>*.txt, *.pdf, *.md, *.docx, *.xlsx, *.xlsm</code>) or URLs into the chat which Assista can "ingest" during your conversation. Have her extract data from the doc, adding tables to your model. Or even to implement a model described by the paper or translate a spreadsheet into an Analytica model.
* Assista can "see" images in your model -- pictures in nodes, images in table cells, and diagram or graph screenshots.
* She is language-aware. If you are using Analytica is Spanish, she'll provide UI instructions that refer to the Spanish-language UI elements.
* She is aware of her reasoning in previous conversation turns and the actions she took, enabling her to explain her reasoning or build on ideas she thought about but might not have included in the final response.
* She has an improved ability to navigate and find objects within your (large) models.
* You can personalize her tone, style, level of verbosity and provide her custom instructions. To do this, click on the icon in the top-left corner of the Assista window and select Personization...

== Multi-linguality: Spanish UI ==
Analytica now comes with a Spanish-language UI, in which its menus, dialogs, error messages and built-in function descriptions are all in Spanish. Also its installer runs with a Spanish-language UI when you are in a Spanish-language region. Spanish is the default when you are in a Spanish-language region.

You can override the default language by launching Analytica as:
* <code>Analytica.exe /lang:es</code>
*: or
* <code>Analytica.exe /lang:en</code>

You can also set the <code>Language</code> registry setting in the <code>"HKCU/Software/Lumina Decision Systems/Analytica"</code> hive to REG_SZ <code>"en"</code> on <code>"es"</code> for your default if different from your windows region setting.

Some of you may ask "what about my language?". Stay tuned (and let us know there is a demand for your language). Once our AI translation pipeline is solid, it shouldn't be too hard for us to add more.

== CSV files ==
There are now a few additional ways to open CSV files in Analytica:
* On the command line: <code>Analytica.exe MyData.csv</code>
* Drag and drop a *.csv file onto the diagram (which behaves the same as using <code>File / Import...</code> on the *.csv file).

== Spreadsheets ==
* <code>[[SpreadsheetOpen]]("new")</code> now creates a blank spreadsheet in memory. Works with both the Excel and LibXl backends.
* Prefacing a sheet name with + in the call to [[SpreadsheetSetCell]] or [[SpreadsheetSetRange]] will add a new sheet by that name to the workbook (as it applies the specified change to that new worksheet). Works with either backend.
* You can also now remove a sheet from a workbook using: <code>[[SpreadsheetSetCell]](wb, "-OldSheet", col, row, Null)</code>. The «col» and «row» parameters are required but ignored in this case.

== Misc. User Interface ==
* The Node Icon editor (on the Diagram menu) is more featureful and can be used to edit arbitrary node images, with support for color and transparency.
* Added keyboard shortcuts for '''Set Node Style...''' and '''Set Diagram Style...'''

== Built-in functions ==
* New options for [[GetProcessInfo]]: <code>"Number of monitors"</code>, <code>"Current monitor rect"</code>, <code>"Current monitor work rect"</code>, <code>"Monitor «N» Rect"</code>, and <code>"Monitor «N» work rect"</code>.
* New optional parameter, «throwParsingErrors», to [[Evaluate]].
* [[ReadFromURL]] is a bit smarter about returning binary content (like <code>*.zip</code> files) as a [[In-memory binary data terms|Binary Data Term]].
* [[MakeJSON]] will automatically encode an image in base64 JSON, and [[ParseJSON]] will automatically decode a base64 representation into an image.
* <code>[[GetProcessInfo]]("UI Language")</code> returns the UI language, either <code>"en"</code> (for English) or <code>"es"</code> for Spanish.
* <code>[[QualifiedName]]( obj, nsContext )</code>: Returns the qualified identifier (as text) that uniquely identifies «obj» from the context of «nsContext».
* <code>[[Namespace]] of X</code>: A new virtual attribute that returns the namespace of «X».
* [[Evaluate]] has a second return value that captures output to the typescript window (including stuff written by [[ConsolePrint]]) during the evaluation. It also has a new optional «ignoreAtFirstWarning» parameter that can be used in conjunction, capturing the first warning text in that second return value, not showing the return value to the user, and ignoring additional warnings during the duration of the Evaluate call (enables Assista to see the warnings).
* Added a syntax construct for [[Namespaces#Scoped_namespace_inclusion:_Using|Scoped namespace inclusion]] to bring a namespace into scope for only a localized expression or lexical block.

== System variables ==
* SysVar [[Graph_ColorSequence]]: Replaces [[Graph_ColorSeq]] which is now deprecated. The new sysvar contains a list of color interer with one integer (of the form <code>0x00rrggbb</code>) per color (whereas the deprecated used triples of numbers per color).

== Engine ==
* After loading a large model, it parses expressions in parallel, using multiple threads/cores to parse different variables. On some computers on some models, this can dramatically speed up model load time.
* Color attributes use color integers for consistently (rather than the legacy number triples for R,G,B).
* You can use a localized namespace import (for a single expression or single lexical block) with the syntax
*:<code>[[Using..Do|Using]] NS;</code>

== Model loading ==
When opening a model file, the "checking" stage (when attributes are parsed) parses different expressions on different threads, resulting in substantially faster model load times for very large models.

Note: In the event that this creates a problem with your specific model (maybe due to an as-yet-undiscovered multithreading bug), you can disable it for your model as follows:
# Temporarily turn off multithreading (Skip this step if you are able to load your model)
## New model
## <b>Definition menu / System variables / Settings / Maximum evaluation threads</b>
## Set to 1 (and remember the previous value)
# Open your model
# <b>Definition menu / System variables / Settings / Disable Multithreaded Evaluations</b>
# Press the <code>Edit Table</code> button.
# Check the checkbox for <code>Parsing</code>
# Save your model
# <b>Definition menu / System variables / Settings / Maximum evaluation threads</b>
#: Restore the original value from Step 1

== MCP server ==
* Added an ability to install multiple ADE-based Mcp servers that run different ADE releases. For example, you can install two MCP servers into Claude Code:
* ade-server: Runs ADE 7.1
* ade-server-70: Runs ADE 7.0
The information in the <code>«ADE install folder»\Examples\Mcp_server\README.txt</code> file explain how (with enough info for Claude code to configure this for you).

With both installed, Claude Code (or other MCP-enabled AI agents) can compare results for the same model across different releases, etc.

Side note: The Mcp server was added to ADE 7.0.

== Internals ==
This release has undergone massive internal restructuring and refactorization. Ideally (i.e., in the absence of bugs) these changes won't change functionality, but may alter some aspects of behavior, hopefully for the better.
* Internal data structures use for multi-dimensional arrays has been changed. Possible impacts:
** Likely to remove the sensitivity to the "canonical order" of indexes on evaluation speed.
** May change relative evaluation speeds of various functions and operations.
* Added system modules/namespaces: <code>SysLib_Internal</code> and <code>SysLib_Experimental</code>. Intended for Analytica-internal use.
*[[:Category:Cell format functions|Cell formatting functions]] (like [[CellSpan]], [[CellFill]], etc.) are now [[Struct]]s rather than functions. Does not impact usage, other that making it easier for code to traverse resulting data structures.

== Discontinued... ==
* Plug-in functions. (An old hook that allows you to extend Analytica with compiled functions and UI elements written it C++. We are almost certain no one is using these hooks any more.)
* The sysvar [[Graph_ColorSeq]] is now deprecated (but works for both reading and setting to preserve backward compatibility). It has been replaced by the system variable [[Graph_ColorSequence]].
* The built-in (but undocumented, unsupported) <code>ifpos</code> and <code>if0</code> functions were removed.
* The legacy (deprecated) syntax <code>Using temp:=... Do</code> for declaring locals is no longer supported. Legacy models will have such definitions automatically rewritten to use [[Local..Do]] when you load them. [[Using..Do]] now has a different meaning, which is to provide a temporary namespace import.

Analytica 7.1 beta Release Notes

2026-06-17T14:21:44Z

Lchrisman: Created page with "Category: Release notes << Beta Tester Page For a list of 7.1 enhancements since the release of Analytica 7.0, see What's new in Analytica 7.1..."

[[Category: Release notes]]

[[Beta Tester Page|<< Beta Tester Page]]

For a list of 7.1 enhancements since the release of [[Analytica 7.0]], see [[What's new in Analytica 7.1?]].

Substantial changes or fixes that have occurred since the previous beta build are listed on the individual pages below.

== Notes for individual builds ==

* Build 7.1.4.313: First public ''beta'' release. See [[What's new in Analytica 7.1?]].

Beta Tester Page

2026-06-17T14:20:32Z

Lchrisman:

[[Category: Beta testing]]
{{#svarset:betarelease|7.1}}
{{#svarset:prevrelease|7.1}}

We invite you to be a beta tester of [[Analytica {{#svarget:betarelease}}]] if you have Analytica {{#svarget:prevrelease}} installed on your computer with an active subscription. (Sorry, not [[Analytica Free Edition]] and not a legacy permanent license). A floating license subscription works.



== Why become a beta tester? ==
* Test drive the upcoming release {{#svarget:betarelease}} and start using its [[Analytica {{#svarget:betarelease}}|new features]] immediately.
* Participate in webinars on tips and guides on new features.
* Help improve the final release.
* Check that your models work in the new release. Find any issues while they can still be fixed, ensuring a seamless transition for you and your model users when this release becomes official.
== As a beta tester, we request that you ==
* Read [[What's new in Analytica {{#svarget:betarelease}}?]] for an overview of the new features.
* Sign up as a beta tester by filling in the form when you run the installer.
* Try out the new Analytica enhancements of interest to you.
* [[Beta_Tester_Page/Submitting_a_Bug_Report|Submit a bug report]] if you find an issue
* Keep up-to-date with the latest beta build. Analytica will show you an alert whenever there is a new build ready to install, about every 2 weeks. We may also send you email reminders. See [[Analytica {{#svarget:betarelease}} beta Release Notes| release notes]] for changes and bug fixes in each beta release.
* We encourage you to retain Analytica {{#svarget:prevrelease}} when you install Analytica {{#svarget:betarelease}} beta. That lets you compare their behavior if you suspect a new bug.

== How to start beta-testing ==
Download the installer for the latest beta build, release number 7.1.4.313, from:
* [https://downloads.analytica.com/ANA7.1/AnaSetup7_1_4_313.exe Analytica {{#svarget:betarelease}} installer]
* [https://downloads.analytica.com/ANA7.1/AnaSetup7_1_4_313.exe ADE {{#svarget:betarelease}} installer]
These beta builds use your existing {{#svarget:prevrelease}} subscription license that is already on your computer. A separate beta license is not required.

The installers for the current non-beta release can be downloaded directly from the [https://analytica.com/support-2/analytica-downloads/ Analytica Downloads] page.

== Improve Analytica docs ==

During the alpha and beta testing period, we are still updating these Analytica Docs to reflect new features. [[What's new in Analytica {{#svarget:betarelease}}?]] is the most complete listing of new features, and is also a work in progress. As we approach final release date, this information will be more complete.

As an Analytica user, you are invited to contribute to the docs! Since it's on a wiki (using Mediawiki software, just like Wikipedia), you can add or edit any content. If you find something unclear, incomplete, or just wrong, feel free to fix it yourself. Or add comments, asking someone else to. And you are welcome to add tips or interesting examples.

== Known issues ==

If you find an issue, please let us know about it at <code>support@lumina.com</code>. Please see [[/Submitting a Bug Report|Submitting a bug report]] for instructions on reporting bugs.

'''Note:''' We list only the most important issues here (ones that might impact your ability to use it, or which are likely to be found and reported multiple times). We maintain a comprehensive bug base in-house, which is not accessible outside of Lumina.

== FAQs: Frequently Asked Questions ==

See [[Analytica User FAQs]] for frequently asked questions not specific to {{#svarget:betarelease}} or to beta testing.

What's new in Analytica 7.1?

2026-06-17T14:17:20Z

Lchrisman: Start Beta Testing

This page lists new features in release 7.1, which is currently in [[Beta Tester Page|Beta Testing]] prior to final release. If have have an active subscription license, we encourage you to try it out from the [[Beta Tester Page]].

== Window appearance ==
The appearance of the chrome around child MDI windows (aka the "non-client area") has been changed to more closely match the Windows 11 style of windows -- i.e., thin (1 pixel) borders, rounded corners at the top, white title bar, very plain (text-like) button images in the toolbar.

== Assista ==
[[Assista]] is Analytica's A.I. assistant. She is greatly improved in this release.
* Her UI is now a top-level window that resides at the same level as Analytica's main application window.
** You can move her chat window to a non-overlapping location or even a different monitor (to maximize screen real estate used by your Analytica window).
** Selected objects remain visually selected in the main window when you type into Assista.
* Her chat has a different look-and-feel.
* Her chat window is faster and more responsive
* You can drag-highlight any text in her chat and copy to paste elsewhere.
* The UI has improved formatting capabilities for displaying Assista's response.
* Her "thoughts" display as she is processing your prompt, making it clear she is working and even giving you a peek into how she is solving it.
* She has a new processing pipeline on the backend, enabling her to respond faster but also work longer on harder tasks.
* She has an extended set of competencies (skills).
* Your sessions are automatically saved, keyed to your model, and you can resume a previous session for that model from a session selector dropdown in the UI.
* You can create and expose [[Assista_-_Analytica_AI_Assistant/Custom_user_skills_for_Assista|your own custom skills]] to expand her capabilities, or ask her to do it for you.
* You can add or drag-and-drop a document (<code>*.txt, *.pdf, *.md, *.docx, *.xlsx, *.xlsm</code>) or URLs into the chat which Assista can "ingest" during your conversation. Have her extract data from the doc, adding tables to your model. Or even to implement a model described by the paper or translate a spreadsheet into an Analytica model.
* Assista can "see" images in your model -- pictures in nodes, images in table cells, and diagram or graph screenshots.
* She is language-aware. If you are using Analytica is Spanish, she'll provide UI instructions that refer to the Spanish-language UI elements.
* She is aware of her reasoning in previous conversation turns and the actions she took, enabling her to explain her reasoning or build on ideas she thought about but might not have included in the final response.
* She has an improved ability to navigate and find objects within your (large) models.
* You can personalize her tone, style, level of verbosity and provide her custom instructions. To do this, click on the icon in the top-left corner of the Assista window and select Personization...

== Multi-linguality: Spanish UI ==
Analytica now comes with a Spanish-language UI, in which its menus, dialogs, error messages and built-in function descriptions are all in Spanish. Also its installer runs with a Spanish-language UI when you are in a Spanish-language region. Spanish is the default when you are in a Spanish-language region.

You can override the default language by launching Analytica as:
* <code>Analytica.exe /lang:es</code>
*: or
* <code>Analytica.exe /lang:en</code>

You can also set the <code>Language</code> registry setting in the <code>"HKCU/Software/Lumina Decision Systems/Analytica"</code> hive to REG_SZ <code>"en"</code> on <code>"es"</code> for your default if different from your windows region setting.

Some of you may ask "what about my language?". Stay tuned (and let us know there is a demand for your language). Once our AI translation pipeline is solid, it shouldn't be too hard for us to add more.

== CSV files ==
There are now a few additional ways to open CSV files in Analytica:
* On the command line: <code>Analytica.exe MyData.csv</code>
* Drag and drop a *.csv file onto the diagram (which behaves the same as using <code>File / Import...</code> on the *.csv file).

== Spreadsheets ==
* <code>[[SpreadsheetOpen]]("new")</code> now creates a blank spreadsheet in memory. Works with both the Excel and LibXl backends.
* Prefacing a sheet name with + in the call to [[SpreadsheetSetCell]] or [[SpreadsheetSetRange]] will add a new sheet by that name to the workbook (as it applies the specified change to that new worksheet). Works with either backend.
* You can also now remove a sheet from a workbook using: <code>[[SpreadsheetSetCell]](wb, "-OldSheet", col, row, Null)</code>. The «col» and «row» parameters are required but ignored in this case.

== Misc. User Interface ==
* The Node Icon editor (on the Diagram menu) is more featureful and can be used to edit arbitrary node images, with support for color and transparency.
* Added keyboard shortcuts for '''Set Node Style...''' and '''Set Diagram Style...'''

== Built-in functions ==
* New options for [[GetProcessInfo]]: <code>"Number of monitors"</code>, <code>"Current monitor rect"</code>, <code>"Current monitor work rect"</code>, <code>"Monitor «N» Rect"</code>, and <code>"Monitor «N» work rect"</code>.
* New optional parameter, «throwParsingErrors», to [[Evaluate]].
* [[ReadFromURL]] is a bit smarter about returning binary content (like <code>*.zip</code> files) as a [[In-memory binary data terms|Binary Data Term]].
* [[MakeJSON]] will automatically encode an image in base64 JSON, and [[ParseJSON]] will automatically decode a base64 representation into an image.
* <code>[[GetProcessInfo]]("UI Language")</code> returns the UI language, either <code>"en"</code> (for English) or <code>"es"</code> for Spanish.
* <code>[[QualifiedName]]( obj, nsContext )</code>: Returns the qualified identifier (as text) that uniquely identifies «obj» from the context of «nsContext».
* <code>[[Namespace]] of X</code>: A new virtual attribute that returns the namespace of «X».
* [[Evaluate]] has a second return value that captures output to the typescript window (including stuff written by [[ConsolePrint]]) during the evaluation. It also has a new optional «ignoreAtFirstWarning» parameter that can be used in conjunction, capturing the first warning text in that second return value, not showing the return value to the user, and ignoring additional warnings during the duration of the Evaluate call (enables Assista to see the warnings).
* Added a syntax construct for [[Namespaces#Scoped_namespace_inclusion:_Using|Scoped namespace inclusion]] to bring a namespace into scope for only a localized expression or lexical block.

== System variables ==
* SysVar [[Graph_ColorSequence]]: Replaces [[Graph_ColorSeq]] which is now deprecated. The new sysvar contains a list of color interer with one integer (of the form <code>0x00rrggbb</code>) per color (whereas the deprecated used triples of numbers per color).

== Engine ==
* After loading a large model, it parses expressions in parallel, using multiple threads/cores to parse different variables. On some computers on some models, this can dramatically speed up model load time.
* Color attributes use color integers for consistently (rather than the legacy number triples for R,G,B).
* You can use a localized namespace import (for a single expression or single lexical block) with the syntax
*:<code>[[Using..Do|Using]] NS;</code>

== Model loading ==
When opening a model file, the "checking" stage (when attributes are parsed) parses different expressions on different threads, resulting in substantially faster model load times for very large models.

Note: In the event that this creates a problem with your specific model (maybe due to an as-yet-undiscovered multithreading bug), you can disable it for your model as follows:
# Temporarily turn off multithreading (Skip this step if you are able to load your model)
## New model
## <b>Definition menu / System variables / Settings / Maximum evaluation threads</b>
## Set to 1 (and remember the previous value)
# Open your model
# <b>Definition menu / System variables / Settings / Disable Multithreaded Evaluations</b>
# Press the <code>Edit Table</code> button.
# Check the checkbox for <code>Parsing</code>
# Save your model
# <b>Definition menu / System variables / Settings / Maximum evaluation threads</b>
#: Restore the original value from Step 1

== MCP server ==
* Added an ability to install multiple ADE-based Mcp servers that run different ADE releases. For example, you can install two MCP servers into Claude Code:
* ade-server: Runs ADE 7.1
* ade-server-70: Runs ADE 7.0
The information in the <code>«ADE install folder»\Examples\Mcp_server\README.txt</code> file explain how (with enough info for Claude code to configure this for you).

With both installed, Claude Code (or other MCP-enabled AI agents) can compare results for the same model across different releases, etc.

Side note: The Mcp server was added to ADE 7.0.

== Internals ==
This release has undergone massive internal restructuring and refactorization. Ideally (i.e., in the absence of bugs) these changes won't change functionality, but may alter some aspects of behavior, hopefully for the better.
* Internal data structures use for multi-dimensional arrays has been changed. Possible impacts:
** Likely to remove the sensitivity to the "canonical order" of indexes on evaluation speed.
** May change relative evaluation speeds of various functions and operations.
* Added system modules/namespaces: <code>SysLib_Internal</code> and <code>SysLib_Experimental</code>. Intended for Analytica-internal use.
*[[:Category:Cell format functions|Cell formatting functions]] (like [[CellSpan]], [[CellFill]], etc.) are now [[Struct]]s rather than functions. Does not impact usage, other that making it easier for code to traverse resulting data structures.

== Discontinued... ==
* Plug-in functions. (An old hook that allows you to extend Analytica with compiled functions and UI elements written it C++. We are almost certain no one is using these hooks any more.)
* The sysvar [[Graph_ColorSeq]] is now deprecated (but works for both reading and setting to preserve backward compatibility). It has been replaced by the system variable [[Graph_ColorSequence]].
* The built-in (but undocumented, unsupported) <code>ifpos</code> and <code>if0</code> functions were removed.
* The legacy (deprecated) syntax <code>Using temp:=... Do</code> for declaring locals is no longer supported. Legacy models will have such definitions automatically rewritten to use [[Local..Do]] when you load them. [[Using..Do]] now has a different meaning, which is to provide a temporary namespace import.

What's new in Analytica 7.1?

2026-06-11T23:56:13Z

Lchrisman: /* Built-in functions */

Analytica 7.1 is currently under development, and will be the next future release of Analytica. The current official release is [[Analytica 7.0]]. This page is under construction, and will list enhancements that are new to Analytica or ADE 7.1.

== Window appearance ==
The appearance of the chrome around child MDI windows (aka the "non-client area") has been changed to more closely match the Windows 11 style of windows -- i.e., thin (1 pixel) borders, rounded corners at the top, white title bar, very plain (text-like) button images in the toolbar.

== Assista ==
[[Assista]] is Analytica's A.I. assistant. She is greatly improved in this release.
* Her UI is now a top-level window that resides at the same level as Analytica's main application window.
** You can move her chat window to a non-overlapping location or even a different monitor (to maximize screen real estate used by your Analytica window).
** Selected objects remain visually selected in the main window when you type into Assista.
* Her chat has a different look-and-feel.
* Her chat window is faster and more responsive
* You can drag-highlight any text in her chat and copy to paste elsewhere.
* The UI has improved formatting capabilities for displaying Assista's response.
* Her "thoughts" display as she is processing your prompt, making it clear she is working and even giving you a peek into how she is solving it.
* She has a new processing pipeline on the backend, enabling her to respond faster but also work longer on harder tasks.
* She has an extended set of competencies (skills).
* Your sessions are automatically saved, keyed to your model, and you can resume a previous session for that model from a session selector dropdown in the UI.
* You can create and expose [[Assista_-_Analytica_AI_Assistant/Custom_user_skills_for_Assista|your own custom skills]] to expand her capabilities, or ask her to do it for you.
* You can add or drag-and-drop a document (<code>*.txt, *.pdf, *.md, *.docx, *.xlsx, *.xlsm</code>) or URLs into the chat which Assista can "ingest" during your conversation. Have her extract data from the doc, adding tables to your model. Or even to implement a model described by the paper or translate a spreadsheet into an Analytica model.
* Assista can "see" images in your model -- pictures in nodes, images in table cells, and diagram or graph screenshots.
* She is language-aware. If you are using Analytica is Spanish, she'll provide UI instructions that refer to the Spanish-language UI elements.
* She is aware of her reasoning in previous conversation turns and the actions she took, enabling her to explain her reasoning or build on ideas she thought about but might not have included in the final response.
* She has an improved ability to navigate and find objects within your (large) models.
* You can personalize her tone, style, level of verbosity and provide her custom instructions. To do this, click on the icon in the top-left corner of the Assista window and select Personization...

== Multi-linguality: Spanish UI ==
Analytica now comes with a Spanish-language UI, in which its menus, dialogs, error messages and built-in function descriptions are all in Spanish. Also its installer runs with a Spanish-language UI when you are in a Spanish-language region. Spanish is the default when you are in a Spanish-language region.

You can override the default language by launching Analytica as:
* <code>Analytica.exe /lang:es</code>
*: or
* <code>Analytica.exe /lang:en</code>

You can also set the <code>Language</code> registry setting in the <code>"HKCU/Software/Lumina Decision Systems/Analytica"</code> hive to REG_SZ <code>"en"</code> on <code>"es"</code> for your default if different from your windows region setting.

Some of you may ask "what about my language?". Stay tuned (and let us know there is a demand for your language). Once our AI translation pipeline is solid, it shouldn't be too hard for us to add more.

== CSV files ==
There are now a few additional ways to open CSV files in Analytica:
* On the command line: <code>Analytica.exe MyData.csv</code>
* Drag and drop a *.csv file onto the diagram (which behaves the same as using <code>File / Import...</code> on the *.csv file).

== Spreadsheets ==
* <code>[[SpreadsheetOpen]]("new")</code> now creates a blank spreadsheet in memory. Works with both the Excel and LibXl backends.
* Prefacing a sheet name with + in the call to [[SpreadsheetSetCell]] or [[SpreadsheetSetRange]] will add a new sheet by that name to the workbook (as it applies the specified change to that new worksheet). Works with either backend.
* You can also now remove a sheet from a workbook using: <code>[[SpreadsheetSetCell]](wb, "-OldSheet", col, row, Null)</code>. The «col» and «row» parameters are required but ignored in this case.

== Misc. User Interface ==
* The Node Icon editor (on the Diagram menu) is more featureful and can be used to edit arbitrary node images, with support for color and transparency.
* Added keyboard shortcuts for '''Set Node Style...''' and '''Set Diagram Style...'''

== Built-in functions ==
* New options for [[GetProcessInfo]]: <code>"Number of monitors"</code>, <code>"Current monitor rect"</code>, <code>"Current monitor work rect"</code>, <code>"Monitor «N» Rect"</code>, and <code>"Monitor «N» work rect"</code>.
* New optional parameter, «throwParsingErrors», to [[Evaluate]].
* [[ReadFromURL]] is a bit smarter about returning binary content (like <code>*.zip</code> files) as a [[In-memory binary data terms|Binary Data Term]].
* [[MakeJSON]] will automatically encode an image in base64 JSON, and [[ParseJSON]] will automatically decode a base64 representation into an image.
* <code>[[GetProcessInfo]]("UI Language")</code> returns the UI language, either <code>"en"</code> (for English) or <code>"es"</code> for Spanish.
* <code>[[QualifiedName]]( obj, nsContext )</code>: Returns the qualified identifier (as text) that uniquely identifies «obj» from the context of «nsContext».
* <code>[[Namespace]] of X</code>: A new virtual attribute that returns the namespace of «X».
* [[Evaluate]] has a second return value that captures output to the typescript window (including stuff written by [[ConsolePrint]]) during the evaluation. It also has a new optional «ignoreAtFirstWarning» parameter that can be used in conjunction, capturing the first warning text in that second return value, not showing the return value to the user, and ignoring additional warnings during the duration of the Evaluate call (enables Assista to see the warnings).
* Added a syntax construct for [[Namespaces#Scoped_namespace_inclusion:_Using|Scoped namespace inclusion]] to bring a namespace into scope for only a localized expression or lexical block.

== System variables ==
* SysVar [[Graph_ColorSequence]]: Replaces [[Graph_ColorSeq]] which is now deprecated. The new sysvar contains a list of color interer with one integer (of the form <code>0x00rrggbb</code>) per color (whereas the deprecated used triples of numbers per color).

== Engine ==
* After loading a large model, it parses expressions in parallel, using multiple threads/cores to parse different variables. On some computers on some models, this can dramatically speed up model load time.
* Color attributes use color integers for consistently (rather than the legacy number triples for R,G,B).
* You can use a localized namespace import (for a single expression or single lexical block) with the syntax
*:<code>[[Using..Do|Using]] NS;</code>

== Model loading ==
When opening a model file, the "checking" stage (when attributes are parsed) parses different expressions on different threads, resulting in substantially faster model load times for very large models.

Note: In the event that this creates a problem with your specific model (maybe due to an as-yet-undiscovered multithreading bug), you can disable it for your model as follows:
# Temporarily turn off multithreading (Skip this step if you are able to load your model)
## New model
## <b>Definition menu / System variables / Settings / Maximum evaluation threads</b>
## Set to 1 (and remember the previous value)
# Open your model
# <b>Definition menu / System variables / Settings / Disable Multithreaded Evaluations</b>
# Press the <code>Edit Table</code> button.
# Check the checkbox for <code>Parsing</code>
# Save your model
# <b>Definition menu / System variables / Settings / Maximum evaluation threads</b>
#: Restore the original value from Step 1

== MCP server ==
* Added an ability to install multiple ADE-based Mcp servers that run different ADE releases. For example, you can install two MCP servers into Claude Code:
* ade-server: Runs ADE 7.1
* ade-server-70: Runs ADE 7.0
The information in the <code>«ADE install folder»\Examples\Mcp_server\README.txt</code> file explain how (with enough info for Claude code to configure this for you).

With both installed, Claude Code (or other MCP-enabled AI agents) can compare results for the same model across different releases, etc.

Side note: The Mcp server was added to ADE 7.0.

== Internals ==
This release has undergone massive internal restructuring and refactorization. Ideally (i.e., in the absence of bugs) these changes won't change functionality, but may alter some aspects of behavior, hopefully for the better.
* Internal data structures use for multi-dimensional arrays has been changed. Possible impacts:
** Likely to remove the sensitivity to the "canonical order" of indexes on evaluation speed.
** May change relative evaluation speeds of various functions and operations.
* Added system modules/namespaces: <code>SysLib_Internal</code> and <code>SysLib_Experimental</code>. Intended for Analytica-internal use.
*[[:Category:Cell format functions|Cell formatting functions]] (like [[CellSpan]], [[CellFill]], etc.) are now [[Struct]]s rather than functions. Does not impact usage, other that making it easier for code to traverse resulting data structures.

== Discontinued... ==
* Plug-in functions. (An old hook that allows you to extend Analytica with compiled functions and UI elements written it C++. We are almost certain no one is using these hooks any more.)
* The sysvar [[Graph_ColorSeq]] is now deprecated (but works for both reading and setting to preserve backward compatibility). It has been replaced by the system variable [[Graph_ColorSequence]].
* The built-in (but undocumented, unsupported) <code>ifpos</code> and <code>if0</code> functions were removed.
* The legacy (deprecated) syntax <code>Using temp:=... Do</code> for declaring locals is no longer supported. Legacy models will have such definitions automatically rewritten to use [[Local..Do]] when you load them. [[Using..Do]] now has a different meaning, which is to provide a temporary namespace import.

What's new in Analytica 7.1?

2026-06-11T23:51:56Z

Lchrisman: /* Assista */

Analytica 7.1 is currently under development, and will be the next future release of Analytica. The current official release is [[Analytica 7.0]]. This page is under construction, and will list enhancements that are new to Analytica or ADE 7.1.

== Window appearance ==
The appearance of the chrome around child MDI windows (aka the "non-client area") has been changed to more closely match the Windows 11 style of windows -- i.e., thin (1 pixel) borders, rounded corners at the top, white title bar, very plain (text-like) button images in the toolbar.

== Assista ==
[[Assista]] is Analytica's A.I. assistant. She is greatly improved in this release.
* Her UI is now a top-level window that resides at the same level as Analytica's main application window.
** You can move her chat window to a non-overlapping location or even a different monitor (to maximize screen real estate used by your Analytica window).
** Selected objects remain visually selected in the main window when you type into Assista.
* Her chat has a different look-and-feel.
* Her chat window is faster and more responsive
* You can drag-highlight any text in her chat and copy to paste elsewhere.
* The UI has improved formatting capabilities for displaying Assista's response.
* Her "thoughts" display as she is processing your prompt, making it clear she is working and even giving you a peek into how she is solving it.
* She has a new processing pipeline on the backend, enabling her to respond faster but also work longer on harder tasks.
* She has an extended set of competencies (skills).
* Your sessions are automatically saved, keyed to your model, and you can resume a previous session for that model from a session selector dropdown in the UI.
* You can create and expose [[Assista_-_Analytica_AI_Assistant/Custom_user_skills_for_Assista|your own custom skills]] to expand her capabilities, or ask her to do it for you.
* You can add or drag-and-drop a document (<code>*.txt, *.pdf, *.md, *.docx, *.xlsx, *.xlsm</code>) or URLs into the chat which Assista can "ingest" during your conversation. Have her extract data from the doc, adding tables to your model. Or even to implement a model described by the paper or translate a spreadsheet into an Analytica model.
* Assista can "see" images in your model -- pictures in nodes, images in table cells, and diagram or graph screenshots.
* She is language-aware. If you are using Analytica is Spanish, she'll provide UI instructions that refer to the Spanish-language UI elements.
* She is aware of her reasoning in previous conversation turns and the actions she took, enabling her to explain her reasoning or build on ideas she thought about but might not have included in the final response.
* She has an improved ability to navigate and find objects within your (large) models.
* You can personalize her tone, style, level of verbosity and provide her custom instructions. To do this, click on the icon in the top-left corner of the Assista window and select Personization...

== Multi-linguality: Spanish UI ==
Analytica now comes with a Spanish-language UI, in which its menus, dialogs, error messages and built-in function descriptions are all in Spanish. Also its installer runs with a Spanish-language UI when you are in a Spanish-language region. Spanish is the default when you are in a Spanish-language region.

You can override the default language by launching Analytica as:
* <code>Analytica.exe /lang:es</code>
*: or
* <code>Analytica.exe /lang:en</code>

You can also set the <code>Language</code> registry setting in the <code>"HKCU/Software/Lumina Decision Systems/Analytica"</code> hive to REG_SZ <code>"en"</code> on <code>"es"</code> for your default if different from your windows region setting.

Some of you may ask "what about my language?". Stay tuned (and let us know there is a demand for your language). Once our AI translation pipeline is solid, it shouldn't be too hard for us to add more.

== CSV files ==
There are now a few additional ways to open CSV files in Analytica:
* On the command line: <code>Analytica.exe MyData.csv</code>
* Drag and drop a *.csv file onto the diagram (which behaves the same as using <code>File / Import...</code> on the *.csv file).

== Spreadsheets ==
* <code>[[SpreadsheetOpen]]("new")</code> now creates a blank spreadsheet in memory. Works with both the Excel and LibXl backends.
* Prefacing a sheet name with + in the call to [[SpreadsheetSetCell]] or [[SpreadsheetSetRange]] will add a new sheet by that name to the workbook (as it applies the specified change to that new worksheet). Works with either backend.
* You can also now remove a sheet from a workbook using: <code>[[SpreadsheetSetCell]](wb, "-OldSheet", col, row, Null)</code>. The «col» and «row» parameters are required but ignored in this case.

== Misc. User Interface ==
* The Node Icon editor (on the Diagram menu) is more featureful and can be used to edit arbitrary node images, with support for color and transparency.
* Added keyboard shortcuts for '''Set Node Style...''' and '''Set Diagram Style...'''

== Built-in functions ==
* New options for [[GetProcessInfo]]: <code>"Number of monitors"</code>, <code>"Current monitor rect"</code>, <code>"Current monitor work rect"</code>, <code>"Monitor «N» Rect"</code>, and <code>"Monitor «N» work rect"</code>.
* New optional parameter, «throwParsingErrors», to [[Evaluate]].
* [[ReadFromURL]] is a bit smarter about returning binary content (like <code>*.zip</code> files) as a [[In-memory binary data terms|Binary Data Term]].
* [[MakeJSON]] will automatically encode an image in base64 JSON, and [[ParseJSON]] will automatically decode a base64 representation into an image.
* <code>[[GetProcessInfo]]("UI Language")</code> returns the UI language, either <code>"en"</code> (for English) or <code>"es"</code> for Spanish.
* <code>[[QualifiedName]]( obj, nsContext )</code>: Returns the qualified identifier (as text) that uniquely identifies «obj» from the context of «nsContext».
* <code>[[Namespace]] of X</code>: A new virtual attribute that returns the namespace of «X».
* [[Evaluate]] has a second return value that captures output to the typescript window (including stuff written by [[ConsolePrint]]) during the evaluation. It also has a new optional «ignoreAtFirstWarning» parameter that can be used in conjunction, capturing the first warning text in that second return value, not showing the return value to the user, and ignoring additional warnings during the duration of the Evaluate call (enables Assista to see the warnings).

== System variables ==
* SysVar [[Graph_ColorSequence]]: Replaces [[Graph_ColorSeq]] which is now deprecated. The new sysvar contains a list of color interer with one integer (of the form <code>0x00rrggbb</code>) per color (whereas the deprecated used triples of numbers per color).

== Engine ==
* After loading a large model, it parses expressions in parallel, using multiple threads/cores to parse different variables. On some computers on some models, this can dramatically speed up model load time.
* Color attributes use color integers for consistently (rather than the legacy number triples for R,G,B).
* You can use a localized namespace import (for a single expression or single lexical block) with the syntax
*:<code>[[Using..Do|Using]] NS;</code>

== Model loading ==
When opening a model file, the "checking" stage (when attributes are parsed) parses different expressions on different threads, resulting in substantially faster model load times for very large models.

Note: In the event that this creates a problem with your specific model (maybe due to an as-yet-undiscovered multithreading bug), you can disable it for your model as follows:
# Temporarily turn off multithreading (Skip this step if you are able to load your model)
## New model
## <b>Definition menu / System variables / Settings / Maximum evaluation threads</b>
## Set to 1 (and remember the previous value)
# Open your model
# <b>Definition menu / System variables / Settings / Disable Multithreaded Evaluations</b>
# Press the <code>Edit Table</code> button.
# Check the checkbox for <code>Parsing</code>
# Save your model
# <b>Definition menu / System variables / Settings / Maximum evaluation threads</b>
#: Restore the original value from Step 1

== MCP server ==
* Added an ability to install multiple ADE-based Mcp servers that run different ADE releases. For example, you can install two MCP servers into Claude Code:
* ade-server: Runs ADE 7.1
* ade-server-70: Runs ADE 7.0
The information in the <code>«ADE install folder»\Examples\Mcp_server\README.txt</code> file explain how (with enough info for Claude code to configure this for you).

With both installed, Claude Code (or other MCP-enabled AI agents) can compare results for the same model across different releases, etc.

Side note: The Mcp server was added to ADE 7.0.

== Internals ==
This release has undergone massive internal restructuring and refactorization. Ideally (i.e., in the absence of bugs) these changes won't change functionality, but may alter some aspects of behavior, hopefully for the better.
* Internal data structures use for multi-dimensional arrays has been changed. Possible impacts:
** Likely to remove the sensitivity to the "canonical order" of indexes on evaluation speed.
** May change relative evaluation speeds of various functions and operations.
* Added system modules/namespaces: <code>SysLib_Internal</code> and <code>SysLib_Experimental</code>. Intended for Analytica-internal use.
*[[:Category:Cell format functions|Cell formatting functions]] (like [[CellSpan]], [[CellFill]], etc.) are now [[Struct]]s rather than functions. Does not impact usage, other that making it easier for code to traverse resulting data structures.

== Discontinued... ==
* Plug-in functions. (An old hook that allows you to extend Analytica with compiled functions and UI elements written it C++. We are almost certain no one is using these hooks any more.)
* The sysvar [[Graph_ColorSeq]] is now deprecated (but works for both reading and setting to preserve backward compatibility). It has been replaced by the system variable [[Graph_ColorSequence]].
* The built-in (but undocumented, unsupported) <code>ifpos</code> and <code>if0</code> functions were removed.
* The legacy (deprecated) syntax <code>Using temp:=... Do</code> for declaring locals is no longer supported. Legacy models will have such definitions automatically rewritten to use [[Local..Do]] when you load them. [[Using..Do]] now has a different meaning, which is to provide a temporary namespace import.

What's new in Analytica 7.1?

2026-06-11T23:49:16Z

Lchrisman: /* Assista */

Analytica 7.1 is currently under development, and will be the next future release of Analytica. The current official release is [[Analytica 7.0]]. This page is under construction, and will list enhancements that are new to Analytica or ADE 7.1.

== Window appearance ==
The appearance of the chrome around child MDI windows (aka the "non-client area") has been changed to more closely match the Windows 11 style of windows -- i.e., thin (1 pixel) borders, rounded corners at the top, white title bar, very plain (text-like) button images in the toolbar.

== Assista ==
[[Assista]] is Analytica's A.I. assistant. She is greatly improved in this release.
* Her UI is now a top-level window that resides at the same level as Analytica's main application window.
** You can move her chat window to a non-overlapping location or even a different monitor (to maximize screen real estate used by your Analytica window).
** Selected objects remain visually selected in the main window when you type into Assista.
* Her chat has a different look-and-feel.
* Her chat window is faster and more responsive
* You can drag-highlight any text in her chat and copy to paste elsewhere.
* The UI has improved formatting capabilities for displaying Assista's response.
* Her "thoughts" display as she is processing your prompt, making it clear she is working and even giving you a peek into how she is solving it.
* She has a new processing pipeline on the backend, enabling her to respond faster but also work longer on harder tasks.
* She has an extended set of competencies (skills).
* Your sessions are automatically saved, keyed to your model, and you can resume a previous session for that model from a session selector dropdown in the UI.
* You can create and expose [[Assista_-_Analytica_AI_Assistant/Custom_user_skills_for_Assista|your own custom skills]] to expand her capabilities, or ask her to do it for you.
* You can add or drag-and-drop a document (<code>*.txt, *.pdf, *.md, *.docx, *.xlsx, *.xlsm</code>) or URLs into the chat which Assista can "ingest" during your conversation. Have her extract data from the doc, adding tables to your model. Or even to implement a model described by the paper.
* Assista can "see" images in your model -- pictures in nodes, images in table cells, and diagram or graph screenshots.
* She is language-aware. If you are using Analytica is Spanish, she'll provide UI instructions that refer to the Spanish-language UI elements.
* She is aware of her reasoning in previous conversation turns and the actions she took, enabling her to explain her reasoning or build on ideas she thought about but might not have included in the final response.
* She has an improved ability to navigate and find objects within your (large) models.
* You can personalize her tone, style, level of verbosity and provide her custom instructions. To do this, click on the icon in the top-left corner of the Assista window and select Personization...

== Multi-linguality: Spanish UI ==
Analytica now comes with a Spanish-language UI, in which its menus, dialogs, error messages and built-in function descriptions are all in Spanish. Also its installer runs with a Spanish-language UI when you are in a Spanish-language region. Spanish is the default when you are in a Spanish-language region.

You can override the default language by launching Analytica as:
* <code>Analytica.exe /lang:es</code>
*: or
* <code>Analytica.exe /lang:en</code>

You can also set the <code>Language</code> registry setting in the <code>"HKCU/Software/Lumina Decision Systems/Analytica"</code> hive to REG_SZ <code>"en"</code> on <code>"es"</code> for your default if different from your windows region setting.

Some of you may ask "what about my language?". Stay tuned (and let us know there is a demand for your language). Once our AI translation pipeline is solid, it shouldn't be too hard for us to add more.

== CSV files ==
There are now a few additional ways to open CSV files in Analytica:
* On the command line: <code>Analytica.exe MyData.csv</code>
* Drag and drop a *.csv file onto the diagram (which behaves the same as using <code>File / Import...</code> on the *.csv file).

== Spreadsheets ==
* <code>[[SpreadsheetOpen]]("new")</code> now creates a blank spreadsheet in memory. Works with both the Excel and LibXl backends.
* Prefacing a sheet name with + in the call to [[SpreadsheetSetCell]] or [[SpreadsheetSetRange]] will add a new sheet by that name to the workbook (as it applies the specified change to that new worksheet). Works with either backend.
* You can also now remove a sheet from a workbook using: <code>[[SpreadsheetSetCell]](wb, "-OldSheet", col, row, Null)</code>. The «col» and «row» parameters are required but ignored in this case.

== Misc. User Interface ==
* The Node Icon editor (on the Diagram menu) is more featureful and can be used to edit arbitrary node images, with support for color and transparency.
* Added keyboard shortcuts for '''Set Node Style...''' and '''Set Diagram Style...'''

== Built-in functions ==
* New options for [[GetProcessInfo]]: <code>"Number of monitors"</code>, <code>"Current monitor rect"</code>, <code>"Current monitor work rect"</code>, <code>"Monitor «N» Rect"</code>, and <code>"Monitor «N» work rect"</code>.
* New optional parameter, «throwParsingErrors», to [[Evaluate]].
* [[ReadFromURL]] is a bit smarter about returning binary content (like <code>*.zip</code> files) as a [[In-memory binary data terms|Binary Data Term]].
* [[MakeJSON]] will automatically encode an image in base64 JSON, and [[ParseJSON]] will automatically decode a base64 representation into an image.
* <code>[[GetProcessInfo]]("UI Language")</code> returns the UI language, either <code>"en"</code> (for English) or <code>"es"</code> for Spanish.
* <code>[[QualifiedName]]( obj, nsContext )</code>: Returns the qualified identifier (as text) that uniquely identifies «obj» from the context of «nsContext».
* <code>[[Namespace]] of X</code>: A new virtual attribute that returns the namespace of «X».
* [[Evaluate]] has a second return value that captures output to the typescript window (including stuff written by [[ConsolePrint]]) during the evaluation. It also has a new optional «ignoreAtFirstWarning» parameter that can be used in conjunction, capturing the first warning text in that second return value, not showing the return value to the user, and ignoring additional warnings during the duration of the Evaluate call (enables Assista to see the warnings).

== System variables ==
* SysVar [[Graph_ColorSequence]]: Replaces [[Graph_ColorSeq]] which is now deprecated. The new sysvar contains a list of color interer with one integer (of the form <code>0x00rrggbb</code>) per color (whereas the deprecated used triples of numbers per color).

== Engine ==
* After loading a large model, it parses expressions in parallel, using multiple threads/cores to parse different variables. On some computers on some models, this can dramatically speed up model load time.
* Color attributes use color integers for consistently (rather than the legacy number triples for R,G,B).
* You can use a localized namespace import (for a single expression or single lexical block) with the syntax
*:<code>[[Using..Do|Using]] NS;</code>

== Model loading ==
When opening a model file, the "checking" stage (when attributes are parsed) parses different expressions on different threads, resulting in substantially faster model load times for very large models.

Note: In the event that this creates a problem with your specific model (maybe due to an as-yet-undiscovered multithreading bug), you can disable it for your model as follows:
# Temporarily turn off multithreading (Skip this step if you are able to load your model)
## New model
## <b>Definition menu / System variables / Settings / Maximum evaluation threads</b>
## Set to 1 (and remember the previous value)
# Open your model
# <b>Definition menu / System variables / Settings / Disable Multithreaded Evaluations</b>
# Press the <code>Edit Table</code> button.
# Check the checkbox for <code>Parsing</code>
# Save your model
# <b>Definition menu / System variables / Settings / Maximum evaluation threads</b>
#: Restore the original value from Step 1

== MCP server ==
* Added an ability to install multiple ADE-based Mcp servers that run different ADE releases. For example, you can install two MCP servers into Claude Code:
* ade-server: Runs ADE 7.1
* ade-server-70: Runs ADE 7.0
The information in the <code>«ADE install folder»\Examples\Mcp_server\README.txt</code> file explain how (with enough info for Claude code to configure this for you).

With both installed, Claude Code (or other MCP-enabled AI agents) can compare results for the same model across different releases, etc.

Side note: The Mcp server was added to ADE 7.0.

== Internals ==
This release has undergone massive internal restructuring and refactorization. Ideally (i.e., in the absence of bugs) these changes won't change functionality, but may alter some aspects of behavior, hopefully for the better.
* Internal data structures use for multi-dimensional arrays has been changed. Possible impacts:
** Likely to remove the sensitivity to the "canonical order" of indexes on evaluation speed.
** May change relative evaluation speeds of various functions and operations.
* Added system modules/namespaces: <code>SysLib_Internal</code> and <code>SysLib_Experimental</code>. Intended for Analytica-internal use.
*[[:Category:Cell format functions|Cell formatting functions]] (like [[CellSpan]], [[CellFill]], etc.) are now [[Struct]]s rather than functions. Does not impact usage, other that making it easier for code to traverse resulting data structures.

== Discontinued... ==
* Plug-in functions. (An old hook that allows you to extend Analytica with compiled functions and UI elements written it C++. We are almost certain no one is using these hooks any more.)
* The sysvar [[Graph_ColorSeq]] is now deprecated (but works for both reading and setting to preserve backward compatibility). It has been replaced by the system variable [[Graph_ColorSequence]].
* The built-in (but undocumented, unsupported) <code>ifpos</code> and <code>if0</code> functions were removed.
* The legacy (deprecated) syntax <code>Using temp:=... Do</code> for declaring locals is no longer supported. Legacy models will have such definitions automatically rewritten to use [[Local..Do]] when you load them. [[Using..Do]] now has a different meaning, which is to provide a temporary namespace import.

What's new in Analytica 7.1?

2026-06-11T13:40:48Z

Lchrisman: /* Assista */

Analytica 7.1 is currently under development, and will be the next future release of Analytica. The current official release is [[Analytica 7.0]]. This page is under construction, and will list enhancements that are new to Analytica or ADE 7.1.

== Window appearance ==
The appearance of the chrome around child MDI windows (aka the "non-client area") has been changed to more closely match the Windows 11 style of windows -- i.e., thin (1 pixel) borders, rounded corners at the top, white title bar, very plain (text-like) button images in the toolbar.

== Assista ==
[[Assista]] is Analytica's A.I. assistant. She is greatly improved in this release.
* Her UI is now a top-level window that resides at the same level as Analytica's main application window.
** You can move her chat window to a non-overlapping location or even a different monitor (to maximize screen real estate used by your Analytica window).
** Selected objects remain visually selected in the main window when you type into Assista.
* Her chat has a different look-and-feel.
* Her chat window is faster and more responsive
* You can drag-highlight any text in her chat and copy to paste elsewhere.
* The UI has improved formatting capabilities for displaying Assista's response.
* Her "thoughts" display as she is processing your prompt, making it clear she is working and even giving you a peek into how she is solving it.
* She has a new processing pipeline on the backend, enabling her to respond faster but also work longer on harder tasks.
* She has an extended set of competencies (skills).
* Your sessions are automatically saved, keyed to your model, and you can resume a previous session for that model from a session selector dropdown in the UI.
* You can create and expose [[Assista_-_Analytica_AI_Assistant/Custom_user_skills_for_Assista|your own custom skills]] to expand her capabilities, or ask her to do it for you.
* You can add or drag-and-drop a document (<code>*.txt, *.pdf, *.md, *.docx, *.xlsx, *.xlsm</code>) or URLs into the chat which Assista can "ingest" during your conversation. Have her extract data from the doc, adding tables to your model. Or even to implement a model described by the paper.
* Assista can "see" images in your model -- pictures in nodes, images in table cells, and diagram or graph screenshots.
* She is language-aware. If you are using Analytica is Spanish, she'll provide UI instructions that refer to the Spanish-language UI elements.
* She is aware of her reasoning in previous conversation turns and the actions she took, enabling her to explain her reasoning or build on ideas she thought about but might not have included in the final response.
* She has an improved ability to navigate and find objects within your (large) models.

== Multi-linguality: Spanish UI ==
Analytica now comes with a Spanish-language UI, in which its menus, dialogs, error messages and built-in function descriptions are all in Spanish. Also its installer runs with a Spanish-language UI when you are in a Spanish-language region. Spanish is the default when you are in a Spanish-language region.

You can override the default language by launching Analytica as:
* <code>Analytica.exe /lang:es</code>
*: or
* <code>Analytica.exe /lang:en</code>

You can also set the <code>Language</code> registry setting in the <code>"HKCU/Software/Lumina Decision Systems/Analytica"</code> hive to REG_SZ <code>"en"</code> on <code>"es"</code> for your default if different from your windows region setting.

Some of you may ask "what about my language?". Stay tuned (and let us know there is a demand for your language). Once our AI translation pipeline is solid, it shouldn't be too hard for us to add more.

== CSV files ==
There are now a few additional ways to open CSV files in Analytica:
* On the command line: <code>Analytica.exe MyData.csv</code>
* Drag and drop a *.csv file onto the diagram (which behaves the same as using <code>File / Import...</code> on the *.csv file).

== Spreadsheets ==
* <code>[[SpreadsheetOpen]]("new")</code> now creates a blank spreadsheet in memory. Works with both the Excel and LibXl backends.
* Prefacing a sheet name with + in the call to [[SpreadsheetSetCell]] or [[SpreadsheetSetRange]] will add a new sheet by that name to the workbook (as it applies the specified change to that new worksheet). Works with either backend.
* You can also now remove a sheet from a workbook using: <code>[[SpreadsheetSetCell]](wb, "-OldSheet", col, row, Null)</code>. The «col» and «row» parameters are required but ignored in this case.

== Misc. User Interface ==
* The Node Icon editor (on the Diagram menu) is more featureful and can be used to edit arbitrary node images, with support for color and transparency.
* Added keyboard shortcuts for '''Set Node Style...''' and '''Set Diagram Style...'''

== Built-in functions ==
* New options for [[GetProcessInfo]]: <code>"Number of monitors"</code>, <code>"Current monitor rect"</code>, <code>"Current monitor work rect"</code>, <code>"Monitor «N» Rect"</code>, and <code>"Monitor «N» work rect"</code>.
* New optional parameter, «throwParsingErrors», to [[Evaluate]].
* [[ReadFromURL]] is a bit smarter about returning binary content (like <code>*.zip</code> files) as a [[In-memory binary data terms|Binary Data Term]].
* [[MakeJSON]] will automatically encode an image in base64 JSON, and [[ParseJSON]] will automatically decode a base64 representation into an image.
* <code>[[GetProcessInfo]]("UI Language")</code> returns the UI language, either <code>"en"</code> (for English) or <code>"es"</code> for Spanish.
* <code>[[QualifiedName]]( obj, nsContext )</code>: Returns the qualified identifier (as text) that uniquely identifies «obj» from the context of «nsContext».
* <code>[[Namespace]] of X</code>: A new virtual attribute that returns the namespace of «X».
* [[Evaluate]] has a second return value that captures output to the typescript window (including stuff written by [[ConsolePrint]]) during the evaluation. It also has a new optional «ignoreAtFirstWarning» parameter that can be used in conjunction, capturing the first warning text in that second return value, not showing the return value to the user, and ignoring additional warnings during the duration of the Evaluate call (enables Assista to see the warnings).

== System variables ==
* SysVar [[Graph_ColorSequence]]: Replaces [[Graph_ColorSeq]] which is now deprecated. The new sysvar contains a list of color interer with one integer (of the form <code>0x00rrggbb</code>) per color (whereas the deprecated used triples of numbers per color).

== Engine ==
* After loading a large model, it parses expressions in parallel, using multiple threads/cores to parse different variables. On some computers on some models, this can dramatically speed up model load time.
* Color attributes use color integers for consistently (rather than the legacy number triples for R,G,B).
* You can use a localized namespace import (for a single expression or single lexical block) with the syntax
*:<code>[[Using..Do|Using]] NS;</code>

== Model loading ==
When opening a model file, the "checking" stage (when attributes are parsed) parses different expressions on different threads, resulting in substantially faster model load times for very large models.

Note: In the event that this creates a problem with your specific model (maybe due to an as-yet-undiscovered multithreading bug), you can disable it for your model as follows:
# Temporarily turn off multithreading (Skip this step if you are able to load your model)
## New model
## <b>Definition menu / System variables / Settings / Maximum evaluation threads</b>
## Set to 1 (and remember the previous value)
# Open your model
# <b>Definition menu / System variables / Settings / Disable Multithreaded Evaluations</b>
# Press the <code>Edit Table</code> button.
# Check the checkbox for <code>Parsing</code>
# Save your model
# <b>Definition menu / System variables / Settings / Maximum evaluation threads</b>
#: Restore the original value from Step 1

== MCP server ==
* Added an ability to install multiple ADE-based Mcp servers that run different ADE releases. For example, you can install two MCP servers into Claude Code:
* ade-server: Runs ADE 7.1
* ade-server-70: Runs ADE 7.0
The information in the <code>«ADE install folder»\Examples\Mcp_server\README.txt</code> file explain how (with enough info for Claude code to configure this for you).

With both installed, Claude Code (or other MCP-enabled AI agents) can compare results for the same model across different releases, etc.

Side note: The Mcp server was added to ADE 7.0.

== Internals ==
This release has undergone massive internal restructuring and refactorization. Ideally (i.e., in the absence of bugs) these changes won't change functionality, but may alter some aspects of behavior, hopefully for the better.
* Internal data structures use for multi-dimensional arrays has been changed. Possible impacts:
** Likely to remove the sensitivity to the "canonical order" of indexes on evaluation speed.
** May change relative evaluation speeds of various functions and operations.
* Added system modules/namespaces: <code>SysLib_Internal</code> and <code>SysLib_Experimental</code>. Intended for Analytica-internal use.
*[[:Category:Cell format functions|Cell formatting functions]] (like [[CellSpan]], [[CellFill]], etc.) are now [[Struct]]s rather than functions. Does not impact usage, other that making it easier for code to traverse resulting data structures.

== Discontinued... ==
* Plug-in functions. (An old hook that allows you to extend Analytica with compiled functions and UI elements written it C++. We are almost certain no one is using these hooks any more.)
* The sysvar [[Graph_ColorSeq]] is now deprecated (but works for both reading and setting to preserve backward compatibility). It has been replaced by the system variable [[Graph_ColorSequence]].
* The built-in (but undocumented, unsupported) <code>ifpos</code> and <code>if0</code> functions were removed.
* The legacy (deprecated) syntax <code>Using temp:=... Do</code> for declaring locals is no longer supported. Legacy models will have such definitions automatically rewritten to use [[Local..Do]] when you load them. [[Using..Do]] now has a different meaning, which is to provide a temporary namespace import.

What's new in Analytica 7.1?

2026-06-11T13:38:57Z

Lchrisman:

Analytica 7.1 is currently under development, and will be the next future release of Analytica. The current official release is [[Analytica 7.0]]. This page is under construction, and will list enhancements that are new to Analytica or ADE 7.1.

== Window appearance ==
The appearance of the chrome around child MDI windows (aka the "non-client area") has been changed to more closely match the Windows 11 style of windows -- i.e., thin (1 pixel) borders, rounded corners at the top, white title bar, very plain (text-like) button images in the toolbar.

== Assista ==
[[Assista]] is Analytica's A.I. assistant. She is greatly improved in this release.
* Her UI is now a top-level window that resides at the same level as Analytica's main application window.
** You can move her chat window to a non-overlapping location or even a different monitor (to maximize screen real estate used by your Analytica window).
** Selected objects remain visually selected in the main window when you type into Assista.
* Her chat has a different look-and-feel.
* Her chat window is faster and more responsive
* You can drag-highlight any text in her chat and copy to paste elsewhere.
* The UI has improved formatting capabilities for displaying Assista's response.
* Her "thoughts" display as she is processing your prompt, making it clear she is working and even giving you a peek into how she is solving it.
* She has a new processing pipeline on the backend, enabling her to respond faster but also work longer on harder tasks.
* She has an extended set of competencies (skills).
* You can create and expose [[Assista_-_Analytica_AI_Assistant/Custom_user_skills_for_Assista|your own custom skills]] to expand her capabilities, or ask her to do it for you.
* You can add or drag-and-drop a document (<code>*.txt, *.pdf, *.md, *.docx, *.xlsx, *.xlsm</code>) or URLs into the chat which Assista can "ingest" during your conversation. Have her extract data from the doc, adding tables to your model. Or even to implement a model described by the paper.
* Assista can "see" images in your model -- pictures in nodes, images in table cells, and diagram or graph screenshots.
* She is language-aware. If you are using Analytica is Spanish, she'll provide UI instructions that refer to the Spanish-language UI elements.
* She is aware of her reasoning in previous conversation turns and the actions she took, enabling her to explain her reasoning or build on ideas she thought about but might not have included in the final response.
* She has an improved ability to navigate and find objects within your (large) models.

== Multi-linguality: Spanish UI ==
Analytica now comes with a Spanish-language UI, in which its menus, dialogs, error messages and built-in function descriptions are all in Spanish. Also its installer runs with a Spanish-language UI when you are in a Spanish-language region. Spanish is the default when you are in a Spanish-language region.

You can override the default language by launching Analytica as:
* <code>Analytica.exe /lang:es</code>
*: or
* <code>Analytica.exe /lang:en</code>

You can also set the <code>Language</code> registry setting in the <code>"HKCU/Software/Lumina Decision Systems/Analytica"</code> hive to REG_SZ <code>"en"</code> on <code>"es"</code> for your default if different from your windows region setting.

Some of you may ask "what about my language?". Stay tuned (and let us know there is a demand for your language). Once our AI translation pipeline is solid, it shouldn't be too hard for us to add more.

== CSV files ==
There are now a few additional ways to open CSV files in Analytica:
* On the command line: <code>Analytica.exe MyData.csv</code>
* Drag and drop a *.csv file onto the diagram (which behaves the same as using <code>File / Import...</code> on the *.csv file).

== Spreadsheets ==
* <code>[[SpreadsheetOpen]]("new")</code> now creates a blank spreadsheet in memory. Works with both the Excel and LibXl backends.
* Prefacing a sheet name with + in the call to [[SpreadsheetSetCell]] or [[SpreadsheetSetRange]] will add a new sheet by that name to the workbook (as it applies the specified change to that new worksheet). Works with either backend.
* You can also now remove a sheet from a workbook using: <code>[[SpreadsheetSetCell]](wb, "-OldSheet", col, row, Null)</code>. The «col» and «row» parameters are required but ignored in this case.

== Misc. User Interface ==
* The Node Icon editor (on the Diagram menu) is more featureful and can be used to edit arbitrary node images, with support for color and transparency.
* Added keyboard shortcuts for '''Set Node Style...''' and '''Set Diagram Style...'''

== Built-in functions ==
* New options for [[GetProcessInfo]]: <code>"Number of monitors"</code>, <code>"Current monitor rect"</code>, <code>"Current monitor work rect"</code>, <code>"Monitor «N» Rect"</code>, and <code>"Monitor «N» work rect"</code>.
* New optional parameter, «throwParsingErrors», to [[Evaluate]].
* [[ReadFromURL]] is a bit smarter about returning binary content (like <code>*.zip</code> files) as a [[In-memory binary data terms|Binary Data Term]].
* [[MakeJSON]] will automatically encode an image in base64 JSON, and [[ParseJSON]] will automatically decode a base64 representation into an image.
* <code>[[GetProcessInfo]]("UI Language")</code> returns the UI language, either <code>"en"</code> (for English) or <code>"es"</code> for Spanish.
* <code>[[QualifiedName]]( obj, nsContext )</code>: Returns the qualified identifier (as text) that uniquely identifies «obj» from the context of «nsContext».
* <code>[[Namespace]] of X</code>: A new virtual attribute that returns the namespace of «X».
* [[Evaluate]] has a second return value that captures output to the typescript window (including stuff written by [[ConsolePrint]]) during the evaluation. It also has a new optional «ignoreAtFirstWarning» parameter that can be used in conjunction, capturing the first warning text in that second return value, not showing the return value to the user, and ignoring additional warnings during the duration of the Evaluate call (enables Assista to see the warnings).

== System variables ==
* SysVar [[Graph_ColorSequence]]: Replaces [[Graph_ColorSeq]] which is now deprecated. The new sysvar contains a list of color interer with one integer (of the form <code>0x00rrggbb</code>) per color (whereas the deprecated used triples of numbers per color).

== Engine ==
* After loading a large model, it parses expressions in parallel, using multiple threads/cores to parse different variables. On some computers on some models, this can dramatically speed up model load time.
* Color attributes use color integers for consistently (rather than the legacy number triples for R,G,B).
* You can use a localized namespace import (for a single expression or single lexical block) with the syntax
*:<code>[[Using..Do|Using]] NS;</code>

== Model loading ==
When opening a model file, the "checking" stage (when attributes are parsed) parses different expressions on different threads, resulting in substantially faster model load times for very large models.

Note: In the event that this creates a problem with your specific model (maybe due to an as-yet-undiscovered multithreading bug), you can disable it for your model as follows:
# Temporarily turn off multithreading (Skip this step if you are able to load your model)
## New model
## <b>Definition menu / System variables / Settings / Maximum evaluation threads</b>
## Set to 1 (and remember the previous value)
# Open your model
# <b>Definition menu / System variables / Settings / Disable Multithreaded Evaluations</b>
# Press the <code>Edit Table</code> button.
# Check the checkbox for <code>Parsing</code>
# Save your model
# <b>Definition menu / System variables / Settings / Maximum evaluation threads</b>
#: Restore the original value from Step 1

== MCP server ==
* Added an ability to install multiple ADE-based Mcp servers that run different ADE releases. For example, you can install two MCP servers into Claude Code:
* ade-server: Runs ADE 7.1
* ade-server-70: Runs ADE 7.0
The information in the <code>«ADE install folder»\Examples\Mcp_server\README.txt</code> file explain how (with enough info for Claude code to configure this for you).

With both installed, Claude Code (or other MCP-enabled AI agents) can compare results for the same model across different releases, etc.

Side note: The Mcp server was added to ADE 7.0.

== Internals ==
This release has undergone massive internal restructuring and refactorization. Ideally (i.e., in the absence of bugs) these changes won't change functionality, but may alter some aspects of behavior, hopefully for the better.
* Internal data structures use for multi-dimensional arrays has been changed. Possible impacts:
** Likely to remove the sensitivity to the "canonical order" of indexes on evaluation speed.
** May change relative evaluation speeds of various functions and operations.
* Added system modules/namespaces: <code>SysLib_Internal</code> and <code>SysLib_Experimental</code>. Intended for Analytica-internal use.
*[[:Category:Cell format functions|Cell formatting functions]] (like [[CellSpan]], [[CellFill]], etc.) are now [[Struct]]s rather than functions. Does not impact usage, other that making it easier for code to traverse resulting data structures.

== Discontinued... ==
* Plug-in functions. (An old hook that allows you to extend Analytica with compiled functions and UI elements written it C++. We are almost certain no one is using these hooks any more.)
* The sysvar [[Graph_ColorSeq]] is now deprecated (but works for both reading and setting to preserve backward compatibility). It has been replaced by the system variable [[Graph_ColorSequence]].
* The built-in (but undocumented, unsupported) <code>ifpos</code> and <code>if0</code> functions were removed.
* The legacy (deprecated) syntax <code>Using temp:=... Do</code> for declaring locals is no longer supported. Legacy models will have such definitions automatically rewritten to use [[Local..Do]] when you load them. [[Using..Do]] now has a different meaning, which is to provide a temporary namespace import.

Evaluate

2026-06-11T13:37:03Z

Lchrisman: ER 22271: document the new ignoreAtFirstWarning parameter (7.1)

[[category:Evaluation Functions]]
{{ReleaseBar}}

Evaluate(t) is a powerful, but rarely needed function. If t is text, it parses it as an Analytica expression and evaluates it. If t is a handle to a variable, it evaluates and returns its value.
== Evaluate(t) ==

If parameter «t» is a [[Text values|text value]], [[Evaluate]](«t») tries to parse «t» as an Analytica [[expression]] (as in the [[definition]] of a Variable), evaluates it, and returns the resulting [[value]]. For example:

:<code>Evaluate('10 * 10') → 100</code>

If parameter «t» is a [[Handle]] to a variable, [[Evaluate]](«t») evaluates the variable and returns its value:
:<code>Variable A := 100</code>
:<code>[[Evaluate]]([[Handle]](A)) → 100</code>

You can also use it to evaluate a function passed as an object or handle:
:<code>Function Add(a, b) := a+b</code>
:<code>[[Evaluate]]([[Handle]](Add), 2, 10) → 12</code>
This can be useful when you want to define a function that takes a function as a parameter and applies the function in its body.
See [[#Using Evaluate on a Function]] below.

== Handling errors ==
As of [[Analytica 6.6]], when an error occurs during the parsing or evaluation of «t» ''and'' the call to [[Evaluate]] appears within a [[Try]], evaluation transfers to the «catch» expression of the [[Try]] without presenting any error message dialog to the user. But this isn't true when the only surrounding (possibly nested) [[Try]]s have «errorNum» filters that do not match the occurring error.

If error is not caught by a [[Try]], then a parsing error silently returns [[Null]] and an evaluation error appears to the user like any other evaluation error, typically terminating the computation.

In [[Analytica 6.5]] and earlier, parsing errors are not caught by a surrounding [[Try]] -- they return Null as if there were no surrounding [[Try]].

{{Release|1=7.1|2=|3=
== Capturing console output ==
''New to [[Analytica 7.1]].''

[[Evaluate]] can optionally return a second value containing the text of everything printed to the console while «t» is evaluated, such as the output of any [[ConsolePrint]]() calls. To request it, capture two return values:

:<code>[[Local]] (result, consoleText) {{eq}} [[Evaluate]]('ConsolePrint(2 + 2)') Do consoleText</code>

Here <code>result</code> is the value of the evaluated expression (here <code>4</code>), and <code>consoleText</code> is the captured console output (here the text <code>"4"</code> followed by a newline). Capturing the output does not prevent it from also appearing in the typescript window as it normally does.

The second value captures only output produced ''during'' this evaluation. If «t» refers to a variable whose value is already cached, the variable is not recomputed, so it produces no console output and the captured text is empty.
}}

{{Release|1=7.1|2=|3=
== Limiting evaluation time ==
''New to [[Analytica 7.1]].''

The optional «maxSeconds» parameter sets an approximate limit, in seconds, on how long the evaluation of «t» may run. «maxSeconds» may be fractional, so <code>maxSeconds: 0.1</code> limits evaluation to roughly 100 milliseconds. The default of <code>0</code> means no time limit.

If the evaluation does not complete within «maxSeconds», it is aborted and [[Evaluate]] throws an error reading ''"Evaluate reached the maximum time limit of N seconds without completing."'' Because this is an ordinary evaluation error, you can catch it with a surrounding [[Try]]:

:<code>[[Try]]( [[Evaluate]]('Sum(Sqrt(1..100M))', maxSeconds: 0.5), catch: 'Timed out' )</code>

The timing is approximate -- evaluation stops the next time it checks for interruption -- so the limit adds no measurable overhead to normal evaluation. This makes «maxSeconds» well suited to probing how far a long-running evaluation gets within a time budget, rather than to enforcing a precise deadline.
}}

{{Release|1=7.1|2=|3=
== Controlling warnings ==
''New to [[Analytica 7.1]].''

Normally, a warning that occurs while «t» is being evaluated is shown to the user, just as it would be during any other evaluation. The optional «ignoreAtFirstWarning» parameter, when <code>true</code>, silently does what pressing the ''Ignore warnings'' button would do when the first warning occurs: no warning dialog is shown, evaluation continues, and any further warnings during the same call are ignored entirely (so that, for example, a warning that occurs in every cell of a million-cell array does not repeat a million times).

The text of the first warning still goes to the console output, so by also capturing the second return value (see [[#Capturing console output|Capturing console output]] above) the calling code receives the warning text as feedback:

:<code>[[Local]] (result, consoleText) {{eq}} [[Evaluate]]('Sqrt(-1)', ignoreAtFirstWarning: true) Do consoleText</code>

Here <code>result</code> is <code>NaN</code> and <code>consoleText</code> contains the text ''"Warning: Square root of a negative number."'' No dialog interrupts the user.

The suppression applies only for the duration of the [[Evaluate]] call -- the previous warning setting is restored when [[Evaluate]] returns, so the user still sees warnings from later evaluations unless they had already silenced them. This parameter is particularly useful when code (such as an AI agent) calls [[Evaluate]] and wants feedback about warnings without showing dialogs to the user.
}}

== Limitations of Evaluate(t) ==

There are some subtleties and limitations to Evaluate(«t») when «t» is a text value.

{{Release|1=|2=6.5|3=If text «t» contains a [[syntax]] error, [[Evaluate]](«t») gives no error message, and returns [[Null]].}}

The context inside the Evaluate parameter is global, not local. So:
:<code>Variable A := 100</code>
:<code>Variable B := ([[Local]] A := 0; [[Evaluate]]('A + 1'))</code>
:<code>B → 101</code>

The Variable <code>A</code> inside <code>Evaluate('A + 1')</code> refers to the global <code>A</code>, not the local <code>A</code> defined in <code>B</code>. More generally:

* [[Evaluate]](t) creates its own context for [[Parsed Expressions|parsing]] «t» (at evaluation time), which is not the context of the expression in which the [[Evaluate]](t) appears -- e.g., the definition of <code>B</code> above.
* So, text «t» cannot refer to [[Local Values|local value]]s, [[index]]es, or [[function parameters]] defined in the context in which the [[Evaluate]](t) function appears.
* Text «t» may itself define local values and indexes, and refer to them, but these will not be available outside «t».
* If the text value of «t» refers to a global variable —e.g., <code>A</code> in the definition of <code>B</code> above—these do not appear as Inputs of <code>B</code>.
* More generally, Analytica cannot track the dependency of any variable name that appears inside the text. So, for example, any change to <code>A</code> will not cause automatic re-evaluation of <code>B</code>:
:<code>A := 3</code>
:<code>B := A + 1</code>
:<code>C := Evaluate('A + 1')</code>
:<code>A := 5</code>

When <code>A</code> changes, Analytica will automatically ensure that <code>B</code> is updated, but it has no way of knowing <code>C</code> should also be recomputed.

The parameter «t» may itself be an expression that creates a text value to be evaluated by [[Evaluate]]. This text expression appears in the definition of <code>V</code> and is not subject to the above limitations, so, for example:

:<code>Variable V :=([[Local]] x:= ’10’; [[Evaluate]](x & x))</code>
:<code>V → 1010</code>

== When to Use ==

The cases in which you should use [[Evaluate]] are rare. You should be reluctant to use it due to the caveats listed in the previous section. Typical cases when it is useful include:
* Parsing simple expressions.
* (advanced) Use in [[Meta-Inference]] algorithms where you are manipulating handles to objects in your model.
* (rare) Cases where you really do wish to by-pass dependency maintenance. You want it to compute something the first time the result is requested after the model is first loaded, but not update when parent values are changes.

== Non-text Parameters ==

A non-text value can also be passed to [[Evaluate]], which can be of use in some [[Meta-Inference]] applications. You need to keep in mind that the parameter to evaluate is evaluated BEFORE the function itself gets it, so evaluating a non-text value is only meaningful when the evaluated parameter is itself something that can still be evaluated. One instance of this that is often useful is the case of a [[handle]] an object.

For example, suppose
:<code>Variable A := 2 + 3</code>
:<code>Variable TheVar := [[Handle]](A)</code>

In the more general case, you might have a [[Meta-Inference]] algorithm that identifies a single variable object through some computation. Having identified the object, <code>TheVar</code> now holds a handle to the object. You then may want to access values or properties of the object pointed to by <code>TheVar</code>, rather than just values or properties of <code>TheVar</code> itself. Evaluate serves this purpose:

:<code>TheVar → A { A -- i.e., a handle to the object A }</code>
:<code>[[Evaluate]](TheVar) → 5 { evaluates A }</code>

It is worth nothing that an alternative method also exists for evaluating a [[handle]]. You can declare a [[LocalAlias]] set to the handle, and then use its identifier as if it were the identifier of the object.

:<code>[[LocalAlias]] x := TheVar Do x → 5 { x is an alias for A, so "x" in the body is the value of A }</code>

When accessing attributes of an object in a [[Meta-Inference]] algorithm, where your algorithm has a handle to an object (again, say it is in <code>TheVar</code>), you can access the attribute using e.g.,

:<code>Description Of Evaluate(TheVar) → "Description of A"</code>
:<code>Description Of TheVar → "Description of TheVar"</code>

(the result of using <code>TheVar</code> alone is shown for comparison).

== Using Evaluate on a Function ==

Given a [[handle]] to a function object, you can use [[Evaluate]] to call the function. If the function expects ''N'' parameters, you would provide ''N+1'' parameters to [[Evaluate]] -- the first parameter being the handle to the function, and the remaining parameters being the values passed to the function. Example:

:<code>[[Local]] fn := [[If]] opt = 1 [[Then]] [[Handle]]([[Max]]) [[Else]] [[If]] opt = 2 [[Then]] [[Handle]]([[Min]]) [[Else]] [[Handle]]([[Sum]]);</code>
:<code>[[Evaluate]](fn, A, I)</code>

Parameters to the function being called are always passed by position, i.e., you cannot use a named-parameter calling syntax as you might if you were calling the function directly.

If the function being called contains repeated (or variable number of) parameters, and you need to include a parameter that follows the [[repeated parameter]], then you must place brackets around the repeated parameters. For example,

:<code> Function Fu1(x; y: repeated; z: optional) := ...</code>
:<code> </code>
:<code>[[Evaluate]](fn, 1, 2, 3, 4) →</code>
::''Equivalent to <code>Fu1(1, 2, 3, 4)</code>, where <code>[2, 3, 4]</code> are values for <code>y</code> and <code>z</code> is omitted''
:<code>[[Evaluate]](fn, 1, [2, 3], 4) →</code>
::''Equivalent to <code>Fu1(1, 2, 3, y: 4)</code>, where <code>[2, 3]</code> are values for <code>y</code>, and <code>z</code> is 4''.

However, there is a limitation that the first supplied parameter (i.e., the second parameter to [[Evaluate]]) cannot be placed inside brackets. Likewise, you cannot pass an literal list by specifying the first parameter as a bracketed list. This is because the repeated-parameter syntax applies equally to [[Evaluate]]. If you specify the first parameter to [[Evaluate]] in brackets, those become the parameters to the function, i.e.,:

:<code>[[Evaluate]]([[Handle]](F), [1, 2, 3, 4]) →</code>
::''Equivalent to <code>F(1, 2, 3, 4)''</code>

Several common built-in functions, including [[Sum]], [[Max]], and [[Min]], allow a variable number of indexes, so that you can use <code>[[Sum]](A, I, J, K)</code> to sum over 3 dimensions in a single call. These functions also have [[optional parameter]]s, such as «ignoreNonNumbers», so that if you need to specify these optional parameters, you will need to place brackets around the index(es), even if only one (or zero) index is specified. For example, the following examples show how to to specify «ignoreNonNumbers» as true to [[Sum]], when summing over a single index, and when summing over the [[implicit dimension]]:

:<code>[[Evaluate]]([[Handle]]([[Sum]]), A, [I], true)</code>
:<code>[[Local]] x := [3, 2, 'a', 'b', 6] do [[Evaluate]]([[Handle]]([[Sum]]), x, [], true)</code>

Notice that if you don't need to specify the optional «ignoreNonNumbers» parameter (or any parameters that follow the repeated index parameters), then it is more natural to omit the brackets:

:<code>[[Evaluate]]([[Handle]]([[Sum]]), A, I)</code>
:<code>[[Local]] x := [3, 2, 5, 3, 6] do [[Evaluate]]([[Handle]]([[Sum]]), x)</code>

{{Release|6.5||
== Evaluating in a different namespace context ==
''New to [[Analytica 6.5]]''

Suppose there are two variables that both have the identifier X, but which live in different [[Namespaces]]. Then
:<code>[[Evaluate]]( "X+1" )</code>
would differ depending on where it appears. By default it resolves the identifier <code>X</code> from the namespace of the object containing the expression. In some esoteric situations, you may need to interpret the expression from a different namespace context. You can do this by first obtaining a handle to the other namespace module, or to any object inside that namespace, and passing that handle to the «nsContext» parameter.
:<code>[[Evaluate]]( "X+1", nsContext: [[Handle]]("NS2") )</code>
}}

== See Also ==
<div style="column-count:2;-moz-column-count:2;-webkit-column-count:2">
* [[EvaluateScript]]
* [[Proactive Evaluation]]
* [[Evaluation Modes]]
* [[Handle]]
* [[Expression Syntax]]
* [[Expression Assist]]
* [[Parsed Expressions]]
* [[Function calls and parameters]]
* [[Summary of Programming Constructs]]
* [[Procedural Programming]]
* [[Meta-Inference]]{{Release|6.5||
* [[Namespaces]]}}
</div>

Error Messages/49963

2026-06-10T22:20:02Z

Lchrisman: Rewrap message lines so the pre block doesn't need a horizontal scrollbar

[[Category: Error messages]]

== Error message ==

<pre style="background:white; border:white; margin-left: 1em; font-style:italic">
The first word of «cmdLine» (--version) does not appear to name the
«program» being launched (C:\Python313\python.exe). The new process
receives «cmdLine» as its complete command line and treats the first
word as its own program name (argv[0]), not as an argument. Either
repeat the program name at the start of «cmdLine», e.g.
cmdLine: 'python --version', or omit «program» and pass the entire
command line in «cmdLine».
</pre>

== Description ==

This warning (it is a warning, not an error — the process is still launched exactly as you specified) appears when you call [[RunConsoleProcess]] with both the «program» and «cmdLine» parameters, and the first word of «cmdLine» does not appear to name the executable given in «program». The example message above results from:

:<code>RunConsoleProcess('C:\Python313\python.exe', '--version')</code>

This call looks reasonable, but it does not run <code>python --version</code>. By Windows convention, a newly launched process receives a single command-line string, and the first word of that string is the program's own name (<code>argv[0]</code> in C parlance); the real arguments begin at the second word. [[RunConsoleProcess]] passes «cmdLine» to the new process as its complete command line, so in this example python sees <code>--version</code> as its own program name and concludes that it was given no arguments at all. Rather than printing its version, python behaves as if launched bare: it reads a script from standard input (the «stdIn» parameter — empty here), runs it, and exits. The net effect is that the call returns empty text, with no other indication of what went wrong.

To fix the call, do either of the following:

* Repeat the program name as the first word of «cmdLine». It does not have to be the full path — the bare name is enough:
*:<code>RunConsoleProcess('C:\Python313\python.exe', 'python --version')</code>
* Or pass the entire command line as a single parameter, and let Analytica locate the executable (quote the path if it contains spaces):
*:<code>RunConsoleProcess('"C:\Python313\python.exe" --version')</code>

The check that triggers this warning is forgiving about form: the first word of «cmdLine» may be a bare name or a full path, quoted or unquoted, with or without the <code>.exe</code> extension, in any letter case. The warning is issued only when, after reducing both sides to a bare program name, they still differ.

In the rare case where the mismatch is deliberate — a few programs intentionally inspect <code>argv[0]</code> and vary their behavior based on the name they were invoked under — you can simply ignore the warning, or suppress it like any other warning. The process is launched with exactly the «program» and «cmdLine» you gave.

This warning was added in Analytica 7.1.

== See Also ==
* [[RunConsoleProcess]]
* [[Error Messages/40335]] — ''RunConsoleProcess could not launch the indicated process''

Error Messages/49963

2026-06-10T22:19:14Z

Lchrisman: New page for warning 49963 (ER 22270): RunConsoleProcess cmdLine first word should repeat the program name (argv[0])

[[Category: Error messages]]

== Error message ==

<pre style="background:white; border:white; margin-left: 1em; font-style:italic">
The first word of «cmdLine» (--version) does not appear to name the «program» being
launched (C:\Python313\python.exe). The new process receives «cmdLine» as its complete
command line and treats the first word as its own program name (argv[0]), not as an
argument. Either repeat the program name at the start of «cmdLine», e.g.
cmdLine: 'python --version', or omit «program» and pass the entire command line in «cmdLine».
</pre>

== Description ==

This warning (it is a warning, not an error — the process is still launched exactly as you specified) appears when you call [[RunConsoleProcess]] with both the «program» and «cmdLine» parameters, and the first word of «cmdLine» does not appear to name the executable given in «program». The example message above results from:

:<code>RunConsoleProcess('C:\Python313\python.exe', '--version')</code>

This call looks reasonable, but it does not run <code>python --version</code>. By Windows convention, a newly launched process receives a single command-line string, and the first word of that string is the program's own name (<code>argv[0]</code> in C parlance); the real arguments begin at the second word. [[RunConsoleProcess]] passes «cmdLine» to the new process as its complete command line, so in this example python sees <code>--version</code> as its own program name and concludes that it was given no arguments at all. Rather than printing its version, python behaves as if launched bare: it reads a script from standard input (the «stdIn» parameter — empty here), runs it, and exits. The net effect is that the call returns empty text, with no other indication of what went wrong.

To fix the call, do either of the following:

* Repeat the program name as the first word of «cmdLine». It does not have to be the full path — the bare name is enough:
*:<code>RunConsoleProcess('C:\Python313\python.exe', 'python --version')</code>
* Or pass the entire command line as a single parameter, and let Analytica locate the executable (quote the path if it contains spaces):
*:<code>RunConsoleProcess('"C:\Python313\python.exe" --version')</code>

The check that triggers this warning is forgiving about form: the first word of «cmdLine» may be a bare name or a full path, quoted or unquoted, with or without the <code>.exe</code> extension, in any letter case. The warning is issued only when, after reducing both sides to a bare program name, they still differ.

In the rare case where the mismatch is deliberate — a few programs intentionally inspect <code>argv[0]</code> and vary their behavior based on the name they were invoked under — you can simply ignore the warning, or suppress it like any other warning. The process is launched with exactly the «program» and «cmdLine» you gave.

This warning was added in Analytica 7.1.

== See Also ==
* [[RunConsoleProcess]]
* [[Error Messages/40335]] — ''RunConsoleProcess could not launch the indicated process''

GetProcessInfo

2026-06-10T21:01:49Z

Lchrisman: /* Types of information */

[[Category:System Functions]]
[[Category: Memory management]]
{{ReleaseBar}}

[[GetProcessInfo]] can give you information about the current Analytica or [[ADE]] process, such as user name, computer, name, memory in use, number of processors available, number of objects in the model, and a whole lot more. from the Windows operating system,

== Types of information ==

[[GetProcessInfo]] returns information about the current Analytica or [[ADE]] process from the Windows operating system, according to which of these texts you pass as the «item» parameter:
:<code>"Process ID"</code> -- returns the Process ID, or Pid, for the current process.
:<code>"Thread ID"</code> -- returns the Id of the Analytica/ADE thread.
:<code>"Priority"</code> -- returns the priority of the Analytica/ADE thread. The following values are possible (defined by the Windows operating system):
::*<code>-15</code> : Idle only
::*<code>-2</code> : lowest priority
::*<code>-1</code> : below normal
::*<code>0</code> : normal priority
::*<code>1</code> : Above normal
::*<code>2</code> : Highest priority
::*<code>15</code>: Critical priority
::*<code>31</code>: Real-time priority
:<code>"Computer Name"</code>
:<code>"User Name"</code>: Windows login name
:<code>"User Identity"</code>: User name in ACP, or Windows login name in DTA.
:<code>"Windows Version"</code>
:<code>"Windows SP"</code>
:<code>"Windows Build"</code>
:<code>"Abort Event Object"</code> { ADE only }. Name of global Event object for ADE project that can be used to send ADE a break signal to abort the current computation.
: <code>"ENV:''«name»''"</code>: Retrieves the value for the environment variable «name»
: <code>"Environment Variables"</code>: List of all Environment variables
: <code>"Command Line"</code>
: <code>"Analytica Path"</code>: Full file path to the ''Analytica.exe, Ade.exe'', or ''Ade.dll'' file being run.
: <code>"Working Set Size"</code>
: <code>"Working Set Max"</code>
: <code>"Working Set Min"</code>
: <code>"Working Set Flags"</code>
:<code> "Working Set Peak"</code>
: <code>"Private Bytes"</code>
: <code>"Total RAM"</code>
: <code>"Free RAM"</code>
: <code>"Total Virtual"</code>
: <code>"Max Address Space"</code>
: <code>"Memory Load"</code>
: <code>"Total Free Memory"</code>
: <code>"Page Fault Count"</code>
: <code>"Avail Virtual"</code>
: <code>"Processor #"</code>: On a multi-core computer, the processor currently running the current evaluation. This changes with time.
: <code>"Affinity Mask"</code>: A list of which processors the operating system will allow Analytica's evaluation to run on.
: <code>"Num Processors"</code>: The number of processors the Analytica process is allowed to run on.
: <code>"Num Sys Processors"</code>: The total number of processors on this computer in the current processor group. Always <=64.{{Release|6.0||
: <code>"Num cores"</code>: The total number of processors on this computer in all [https://docs.microsoft.com/en-us/windows/win32/procthread/processor-groups processor groups]. (Typically the same as <code>"Num Sys Processors"</code> on computers with 64 cores or less, but can be greater than 64 on very high-end servers).}}
: <code>"User Objects"</code>: Number of objects in use (variable nodes, local indexes, etc) by a model
: <code>"Total Objects"</code>: Number of objects in use including both user objects and built-in system objects.
: <code>"Free Objects"</code>: Number of free "slots" still available for additional objects.{{Release|1=7.1|2=|3=
: <code>'UI Language'</code>: Returns the language used for the Analytica user interface, "en"=English, "es"=Spanish, etc. }}{{Release|6.5||
:<code>"Application Rect"</code>: Returns width, height, top, left, as 4 return values, describing the screen coordinates of the desktop Analytica application window. Returns Null in ADE.
:<code>"Desk Rect"</code>: Returns width, height, x,y, as 4 return values, describing the rectangle within the desktop application where MDI windows can be. This rectangle starts below the toolbar, and does not include application boundaries.}}{{Release|1=7.0|2=|3=
:<code>"Python Environments"</code>: returns a list of all discovered Python/conda environment paths
:<code>"Python Installations"</code>: returns just the base Python installations
:<code>"Screenshot"</code>: Returns an image of the Analytica desktop application window (at the time the function call is evaluated).}}{{Release|1=7.1|2=|3=
:<code>"Current Monitor Rect"</code>: Returns width, height, x, y, as 4 return values, describing the screen coordinates of the monitor that the Analytica application window is currently on. Returns Null in ADE.
:<code>"Current Monitor Work Rect"</code>: Returns width, height, x, y, as 4 return values, describing the work area (excluding taskbar) of the monitor that the Analytica application window is currently on. Returns Null in ADE.
:<code>"Number of Monitors"</code>: The number of monitors connected to the system.
:<code>"Monitor ''N'' Rect"</code>: Returns width, height, x, y, as 4 return values, describing the screen coordinates of the ''N''th monitor (1-based). Replace ''N'' with any integer from 1 to the value of <code>"Number of Monitors"</code>. For example, <code>GetProcessInfo("Monitor 2 Rect")</code> returns the rectangle of the 2nd monitor.
:<code>"Monitor ''N'' Work Rect"</code>: Like <code>"Monitor ''N'' Rect"</code> but returns the work area (excluding taskbar) of the ''N''th monitor. For example, <code>GetProcessInfo("Monitor 1 Work Rect")</code>.}}

== Examples ==
=== Process ID ===
Knowing the Process ID makes it possible to differentiate between multiple instances of Analytica or [[ADE]] in the Windows Task Manager.
:<code>GetProcessInfo("Process ID") → 4117</code>

=== Reading the command line ===
:<code>GetProcessInfo("Command Line") → '"C:\Program Files\Lumina\Analytica.exe" "C:\My Models\Costs.ana"'</code>

See [[Analytica Command Line]] for a list of valid command line parameters recognized by Analytica.

=== Reading Environment Variables ===
Obtain a list of all environment variables:
:<code>Index EnvVarName := GetProcessInfo("Environment Variables");</code>
:<code>GetProcessInfo("Env:"&EnvVarName)</code>

=== Getting PID from ADE (C#) ===
:<code>CAEngine ade = new CAEngine();</code>
:<code>CAObject V = ade.CreateObject("V", "variable");</code>
:<code>V.SetAttribute("definition", "GetProcessInfo(\"Process ID\")");</code>
:<code>string pInfoResult = V.Result().ToString();</code>

=== Aborting an in-progress evaluation in ADE ===
To abort a computation in [[ADE]], your program must obtain a HANDLE to the ''abort event object''. In order to obtain this, you need to obtain the name of this object from ADE. You get this by calling <code>GetProcessInfo("Abort Event Object")</code>. You then use the Windows Platform SDK routine OpenEvent to get the handle to this object. When you want to abort an in-process computation, you set this event. Generally your application that uses ADE will need to be multi-threaded, so that one thread calls ADE, the other thread detects the signal to abort the computation (the signal might be a user pressing ''Ctrl+Break'', for example).

<pre style="background:white; border:white; margin-left: 1em;">
C++ example:

/* From first application thread, which uses ADE: */
#include <windows.h>
#import "ADE.exe"
using namespace ADE4;
...
GLOBAL HEVENT hAbort;
...
void main()
{
...
CAEngine* pAde = new CAEngine();
pAde->SendCommand("GetProcessInfo('Abort Event Object')");
_bstr_t abortObjName = pAde->get_OutputBuffer();
hAbort = OpenEvent(EVENT_MODIFY_STATE,/*bInherit*/FALSE,abortObjName);
...
CreateThread(..., MonitorForBreak,... );
CTable* pResult = pAde->Get("X")->ResultTable(); /* Initiate a very long computation */
if (pAde->get_ErrorCode() == 78) {
/* The computation was aborted before completion */
...
}
...
}

DWORD WINAPI MonitorForBreak( LPVOID )
{
/* This routine detects a signal to break the computation. Maybe it is a user-keypress,
* or other UI interaction. */
if (DetectUserWantsToAbort()) {
SetEvent(hAbort); /* Causes the abort */
}
}
</pre>

=== Memory Information ===
The Analytica process that evaluates your model may end up using a lot of memory. The operating system keeps some of that memory in RAM, and swaps some of it out to virtual memory. Accessing RAM is fast, while accessing virtual memory is much slower. Windows makes various tradeoffs with what other programs are running on your computer to decide how much of the Analytica process to keep in RAM. The amount of RAM to devote to Analytica is called its ''working set''. When the working set is much smaller that the available RAM, other applications on your computer will respond well (since they can use that RAM), but Analytica may run slowly. If the working set is close to the amount of available RAM, then Analytica gets to make more use of fast RAM, but other applications, and the Windows UI, may get very slow, since they will then need to switch in and out of memory.

<code>GetProcessInfo("Working Set Max")</code> and <code>GetProcessInfo("Working set Min")</code> return the minimum and maximum working set size, in bytes, currently imposed by Windows on the Analytica process. <code>GetProcessInfo("Working Set Flags")</code> returns an integer containing flags, indicating whether Windows is allowed to alter these limits as the process uses more or less memory. The flags are the following numbers added together:
* <code>1</code> = Analytica is guaranteed at least the minimum working set.
* <code>2</code> = Windows may reduce Analytica's working set below the minimum value when memory demands are high
* <code>4</code> = Windows will not allocate more than the indicated working set max.
* <code>8</code> = Windows may give Analytica more than the <code>Working Set Max</code> when memory demands from other applications is low.

The <code>"Avail Virtual"</code> option returns the number that Windows reports as the theoretical maximum amount of memory available to all processes running on the operating system, including both RAM and page file space. However, the number isn't very meaningful or reliable, as Windows often reports a number that far exceeds the amount of available hard disk space (for example, in Windows x64, a number of 8.8 TeraBytes is reported), and in 32-bit processes on Windows x64, the huge number seems to be wrap at 4GB, resulting in a nonesense (and often very small) number.

{{Release|1=6.5|2=|3=
== Application window coordinates ==
''new in [[Analytica 6.5]]''
:<code>[[Local]] (width, height, left, top) := [[GetProcessInfo]]( 'Application Rect');</code>

This gets the rectangle, in screen coordinates, of the desktop application. From ADE, or ACP when there is no dual desktop UI running, returns Null.

:<code>[[Local]](width, height) := [[GetProcessInfo]]('Desk Rect');</code>

This gets the size of the desk, the rectangle within the application where diagram windows, object window, result windows, the outliner, Assista window, etc. reside. This desk rectangle starts below the toolbar. You can also get the location:

:<code>[[Local]](width, height, x, y) := [[GetProcessInfo]]('Desk Rect');</code>

The x,y location coordinate is relative to the application window.
}}
==History==
This function was introduced in [[What's new in Analytica 4.0?|Analytica 4.0]].

==See Also==
* [[Working Set Size]]
* [[Memory usage and management]]

Evaluate

2026-06-03T20:55:08Z

Lchrisman: Document new maxSeconds parameter (ER 22222), gated to 7.1

[[category:Evaluation Functions]]
{{ReleaseBar}}

Evaluate(t) is a powerful, but rarely needed function. If t is text, it parses it as an Analytica expression and evaluates it. If t is a handle to a variable, it evaluates and returns its value.
== Evaluate(t) ==

If parameter «t» is a [[Text values|text value]], [[Evaluate]](«t») tries to parse «t» as an Analytica [[expression]] (as in the [[definition]] of a Variable), evaluates it, and returns the resulting [[value]]. For example:

:<code>Evaluate('10 * 10') → 100</code>

If parameter «t» is a [[Handle]] to a variable, [[Evaluate]](«t») evaluates the variable and returns its value:
:<code>Variable A := 100</code>
:<code>[[Evaluate]]([[Handle]](A)) → 100</code>

You can also use it to evaluate a function passed as an object or handle:
:<code>Function Add(a, b) := a+b</code>
:<code>[[Evaluate]]([[Handle]](Add), 2, 10) → 12</code>
This can be useful when you want to define a function that takes a function as a parameter and applies the function in its body.
See [[#Using Evaluate on a Function]] below.

== Handling errors ==
As of [[Analytica 6.6]], when an error occurs during the parsing or evaluation of «t» ''and'' the call to [[Evaluate]] appears within a [[Try]], evaluation transfers to the «catch» expression of the [[Try]] without presenting any error message dialog to the user. But this isn't true when the only surrounding (possibly nested) [[Try]]s have «errorNum» filters that do not match the occurring error.

If error is not caught by a [[Try]], then a parsing error silently returns [[Null]] and an evaluation error appears to the user like any other evaluation error, typically terminating the computation.

In [[Analytica 6.5]] and earlier, parsing errors are not caught by a surrounding [[Try]] -- they return Null as if there were no surrounding [[Try]].

{{Release|1=7.1|2=|3=
== Capturing console output ==
''New to [[Analytica 7.1]].''

[[Evaluate]] can optionally return a second value containing the text of everything printed to the console while «t» is evaluated, such as the output of any [[ConsolePrint]]() calls. To request it, capture two return values:

:<code>[[Local]] (result, consoleText) {{eq}} [[Evaluate]]('ConsolePrint(2 + 2)') Do consoleText</code>

Here <code>result</code> is the value of the evaluated expression (here <code>4</code>), and <code>consoleText</code> is the captured console output (here the text <code>"4"</code> followed by a newline). Capturing the output does not prevent it from also appearing in the typescript window as it normally does.

The second value captures only output produced ''during'' this evaluation. If «t» refers to a variable whose value is already cached, the variable is not recomputed, so it produces no console output and the captured text is empty.
}}

{{Release|1=7.1|2=|3=
== Limiting evaluation time ==
''New to [[Analytica 7.1]].''

The optional «maxSeconds» parameter sets an approximate limit, in seconds, on how long the evaluation of «t» may run. «maxSeconds» may be fractional, so <code>maxSeconds: 0.1</code> limits evaluation to roughly 100 milliseconds. The default of <code>0</code> means no time limit.

If the evaluation does not complete within «maxSeconds», it is aborted and [[Evaluate]] throws an error reading ''"Evaluate reached the maximum time limit of N seconds without completing."'' Because this is an ordinary evaluation error, you can catch it with a surrounding [[Try]]:

:<code>[[Try]]( [[Evaluate]]('Sum(Sqrt(1..100M))', maxSeconds: 0.5), catch: 'Timed out' )</code>

The timing is approximate -- evaluation stops the next time it checks for interruption -- so the limit adds no measurable overhead to normal evaluation. This makes «maxSeconds» well suited to probing how far a long-running evaluation gets within a time budget, rather than to enforcing a precise deadline.
}}

== Limitations of Evaluate(t) ==

There are some subtleties and limitations to Evaluate(«t») when «t» is a text value.

{{Release|1=|2=6.5|3=If text «t» contains a [[syntax]] error, [[Evaluate]](«t») gives no error message, and returns [[Null]].}}

The context inside the Evaluate parameter is global, not local. So:
:<code>Variable A := 100</code>
:<code>Variable B := ([[Local]] A := 0; [[Evaluate]]('A + 1'))</code>
:<code>B → 101</code>

The Variable <code>A</code> inside <code>Evaluate('A + 1')</code> refers to the global <code>A</code>, not the local <code>A</code> defined in <code>B</code>. More generally:

* [[Evaluate]](t) creates its own context for [[Parsed Expressions|parsing]] «t» (at evaluation time), which is not the context of the expression in which the [[Evaluate]](t) appears -- e.g., the definition of <code>B</code> above.
* So, text «t» cannot refer to [[Local Values|local value]]s, [[index]]es, or [[function parameters]] defined in the context in which the [[Evaluate]](t) function appears.
* Text «t» may itself define local values and indexes, and refer to them, but these will not be available outside «t».
* If the text value of «t» refers to a global variable —e.g., <code>A</code> in the definition of <code>B</code> above—these do not appear as Inputs of <code>B</code>.
* More generally, Analytica cannot track the dependency of any variable name that appears inside the text. So, for example, any change to <code>A</code> will not cause automatic re-evaluation of <code>B</code>:
:<code>A := 3</code>
:<code>B := A + 1</code>
:<code>C := Evaluate('A + 1')</code>
:<code>A := 5</code>

When <code>A</code> changes, Analytica will automatically ensure that <code>B</code> is updated, but it has no way of knowing <code>C</code> should also be recomputed.

The parameter «t» may itself be an expression that creates a text value to be evaluated by [[Evaluate]]. This text expression appears in the definition of <code>V</code> and is not subject to the above limitations, so, for example:

:<code>Variable V :=([[Local]] x:= ’10’; [[Evaluate]](x & x))</code>
:<code>V → 1010</code>

== When to Use ==

The cases in which you should use [[Evaluate]] are rare. You should be reluctant to use it due to the caveats listed in the previous section. Typical cases when it is useful include:
* Parsing simple expressions.
* (advanced) Use in [[Meta-Inference]] algorithms where you are manipulating handles to objects in your model.
* (rare) Cases where you really do wish to by-pass dependency maintenance. You want it to compute something the first time the result is requested after the model is first loaded, but not update when parent values are changes.

== Non-text Parameters ==

A non-text value can also be passed to [[Evaluate]], which can be of use in some [[Meta-Inference]] applications. You need to keep in mind that the parameter to evaluate is evaluated BEFORE the function itself gets it, so evaluating a non-text value is only meaningful when the evaluated parameter is itself something that can still be evaluated. One instance of this that is often useful is the case of a [[handle]] an object.

For example, suppose
:<code>Variable A := 2 + 3</code>
:<code>Variable TheVar := [[Handle]](A)</code>

In the more general case, you might have a [[Meta-Inference]] algorithm that identifies a single variable object through some computation. Having identified the object, <code>TheVar</code> now holds a handle to the object. You then may want to access values or properties of the object pointed to by <code>TheVar</code>, rather than just values or properties of <code>TheVar</code> itself. Evaluate serves this purpose:

:<code>TheVar → A { A -- i.e., a handle to the object A }</code>
:<code>[[Evaluate]](TheVar) → 5 { evaluates A }</code>

It is worth nothing that an alternative method also exists for evaluating a [[handle]]. You can declare a [[LocalAlias]] set to the handle, and then use its identifier as if it were the identifier of the object.

:<code>[[LocalAlias]] x := TheVar Do x → 5 { x is an alias for A, so "x" in the body is the value of A }</code>

When accessing attributes of an object in a [[Meta-Inference]] algorithm, where your algorithm has a handle to an object (again, say it is in <code>TheVar</code>), you can access the attribute using e.g.,

:<code>Description Of Evaluate(TheVar) → "Description of A"</code>
:<code>Description Of TheVar → "Description of TheVar"</code>

(the result of using <code>TheVar</code> alone is shown for comparison).

== Using Evaluate on a Function ==

Given a [[handle]] to a function object, you can use [[Evaluate]] to call the function. If the function expects ''N'' parameters, you would provide ''N+1'' parameters to [[Evaluate]] -- the first parameter being the handle to the function, and the remaining parameters being the values passed to the function. Example:

:<code>[[Local]] fn := [[If]] opt = 1 [[Then]] [[Handle]]([[Max]]) [[Else]] [[If]] opt = 2 [[Then]] [[Handle]]([[Min]]) [[Else]] [[Handle]]([[Sum]]);</code>
:<code>[[Evaluate]](fn, A, I)</code>

Parameters to the function being called are always passed by position, i.e., you cannot use a named-parameter calling syntax as you might if you were calling the function directly.

If the function being called contains repeated (or variable number of) parameters, and you need to include a parameter that follows the [[repeated parameter]], then you must place brackets around the repeated parameters. For example,

:<code> Function Fu1(x; y: repeated; z: optional) := ...</code>
:<code> </code>
:<code>[[Evaluate]](fn, 1, 2, 3, 4) →</code>
::''Equivalent to <code>Fu1(1, 2, 3, 4)</code>, where <code>[2, 3, 4]</code> are values for <code>y</code> and <code>z</code> is omitted''
:<code>[[Evaluate]](fn, 1, [2, 3], 4) →</code>
::''Equivalent to <code>Fu1(1, 2, 3, y: 4)</code>, where <code>[2, 3]</code> are values for <code>y</code>, and <code>z</code> is 4''.

However, there is a limitation that the first supplied parameter (i.e., the second parameter to [[Evaluate]]) cannot be placed inside brackets. Likewise, you cannot pass an literal list by specifying the first parameter as a bracketed list. This is because the repeated-parameter syntax applies equally to [[Evaluate]]. If you specify the first parameter to [[Evaluate]] in brackets, those become the parameters to the function, i.e.,:

:<code>[[Evaluate]]([[Handle]](F), [1, 2, 3, 4]) →</code>
::''Equivalent to <code>F(1, 2, 3, 4)''</code>

Several common built-in functions, including [[Sum]], [[Max]], and [[Min]], allow a variable number of indexes, so that you can use <code>[[Sum]](A, I, J, K)</code> to sum over 3 dimensions in a single call. These functions also have [[optional parameter]]s, such as «ignoreNonNumbers», so that if you need to specify these optional parameters, you will need to place brackets around the index(es), even if only one (or zero) index is specified. For example, the following examples show how to to specify «ignoreNonNumbers» as true to [[Sum]], when summing over a single index, and when summing over the [[implicit dimension]]:

:<code>[[Evaluate]]([[Handle]]([[Sum]]), A, [I], true)</code>
:<code>[[Local]] x := [3, 2, 'a', 'b', 6] do [[Evaluate]]([[Handle]]([[Sum]]), x, [], true)</code>

Notice that if you don't need to specify the optional «ignoreNonNumbers» parameter (or any parameters that follow the repeated index parameters), then it is more natural to omit the brackets:

:<code>[[Evaluate]]([[Handle]]([[Sum]]), A, I)</code>
:<code>[[Local]] x := [3, 2, 5, 3, 6] do [[Evaluate]]([[Handle]]([[Sum]]), x)</code>

{{Release|6.5||
== Evaluating in a different namespace context ==
''New to [[Analytica 6.5]]''

Suppose there are two variables that both have the identifier X, but which live in different [[Namespaces]]. Then
:<code>[[Evaluate]]( "X+1" )</code>
would differ depending on where it appears. By default it resolves the identifier <code>X</code> from the namespace of the object containing the expression. In some esoteric situations, you may need to interpret the expression from a different namespace context. You can do this by first obtaining a handle to the other namespace module, or to any object inside that namespace, and passing that handle to the «nsContext» parameter.
:<code>[[Evaluate]]( "X+1", nsContext: [[Handle]]("NS2") )</code>
}}

== See Also ==
<div style="column-count:2;-moz-column-count:2;-webkit-column-count:2">
* [[EvaluateScript]]
* [[Proactive Evaluation]]
* [[Evaluation Modes]]
* [[Handle]]
* [[Expression Syntax]]
* [[Expression Assist]]
* [[Parsed Expressions]]
* [[Function calls and parameters]]
* [[Summary of Programming Constructs]]
* [[Procedural Programming]]
* [[Meta-Inference]]{{Release|6.5||
* [[Namespaces]]}}
</div>

Error Messages/49962

2026-06-03T20:41:34Z

Lchrisman:

== Error message ==
:[[Evaluate]] reached the maximum time limit of 3 seconds.

== Description ==
You called <code>[[Evaluate]]( expr, maxSeconds: 3 )</code>, and the amount of time spent evaluating «expr» exceeded the specified maximum elapsed time.

In most usage cases, a call to [[Evaluate]] that uses the «maxSeconds» parameter will be inside a [[Try]], such as:
[[Try]] (
[[Evaluate]]( expr, maxSeconds:3 )
, errorNum: 49962, { time out }
, catch:
Null
)

Error Messages/49962

2026-06-03T20:41:00Z

Lchrisman: Created page with "== Error message == :Evaluate reached the maximum time limit of 3 seconds. == Description == You called <code>Evaluate( expr, maxSeconds: 3 )</code>, and the amount o..."

What's new in Analytica 7.1?

2026-06-01T21:28:06Z

Lchrisman: /* Built-in functions */

Analytica 7.1 is currently under development, and will be the next future release of Analytica. The current official release is [[Analytica 7.0]]. This page is under construction, and will list enhancements that are new to Analytica or ADE 7.1.

== Window appearance ==
The appearance of the chrome around child MDI windows (aka the "non-client area") has been changed to more closely match the Windows 11 style of windows -- i.e., thin (1 pixel) borders, rounded corners at the top, white title bar, very plain (text-like) button images in the toolbar.

== Assista ==
[[Assista]] is Analytica's A.I. assistant. She is greatly improved in this release.
* Her UI is now a top-level window that resides at the same level as Analytica's main application window.
** You can move her chat window to a non-overlapping location or even a different monitor (to maximize screen real estate used by your Analytica window).
** Selected objects remain visually selected in the main window when you type into Assista.
* Her chat has a different look-and-feel.
* Her chat window is faster and more responsive
* You can drag-highlight any text in her chat and copy to paste elsewhere.
* The UI has improved formatting capabilities for displaying Assista's response.
* Her "thoughts" display as she is processing your prompt, making it clear she is working and even giving you a peek into how she is solving it.
* She has a new processing pipeline on the backend, enabling her to respond faster but also work longer on harder tasks.
* She has an extended set of competencies (skills).
* You can create and expose [[Assista_-_Analytica_AI_Assistant/Custom_user_skills_for_Assista|your own custom skills]] to expand her capabilities, or ask her to do it for you.
* You can drag-and-drop a document (<code>*.txt, *.pdf, *.md, *.docx</code>) or URLs into the chat which Assista can "ingest" during your conversation. Have her extract data from the doc, adding tables to your model. Or even to implement a model described by the paper.
* Assista can "see" images in your model -- pictures in nodes, images in table cells, and diagram or graph screenshots.
* She is language-aware. If you are using Analytica is Spanish, she'll provide UI instructions that refer to the Spanish-language UI elements.
* She is aware of her reasoning in previous conversation turns and the actions she took, enabling her to explain her reasoning or build on ideas she thought about but might not have included in the final response.
* She has an improved ability to navigate and find objects within your (large) models.

== Multi-linguality: Spanish UI ==
Analytica now comes with a Spanish-language UI, in which its menus, dialogs, error messages and built-in function descriptions are all in Spanish. Also its installer runs with a Spanish-language UI when you are in a Spanish-language region. Spanish is the default when you are in a Spanish-language region.

You can override the default language by launching Analytica as:
* <code>Analytica.exe /lang:es</code>
*: or
* <code>Analytica.exe /lang:en</code>

You can also set the <code>Language</code> registry setting in the <code>"HKCU/Software/Lumina Decision Systems/Analytica"</code> hive to REG_SZ <code>"en"</code> on <code>"es"</code> for your default if different from your windows region setting.

Some of you may ask "what about my language?". Stay tuned (and let us know there is a demand for your language). Once our AI translation pipeline is solid, it shouldn't be too hard for us to add more.

== CSV files ==
There are now a few additional ways to open CSV files in Analytica:
* On the command line: <code>Analytica.exe MyData.csv</code>
* Drag and drop a *.csv file onto the diagram (which behaves the same as using <code>File / Import...</code> on the *.csv file).

== Spreadsheets ==
* <code>[[SpreadsheetOpen]]("new")</code> now creates a blank spreadsheet in memory. Works with both the Excel and LibXl backends.
* Prefacing a sheet name with + in the call to [[SpreadsheetSetCell]] or [[SpreadsheetSetRange]] will add a new sheet by that name to the workbook (as it applies the specified change to that new worksheet). Works with either backend.
* You can also now remove a sheet from a workbook using: <code>[[SpreadsheetSetCell]](wb, "-OldSheet", col, row, Null)</code>. The «col» and «row» parameters are required but ignored in this case.

== Misc. User Interface ==
* The Node Icon editor (on the Diagram menu) is more featureful and can be used to edit arbitrary node images, with support for color and transparency.
* Added keyboard shortcuts for '''Set Node Style...''' and '''Set Diagram Style...'''

== Built-in functions ==
* New options for [[GetProcessInfo]]: <code>"Number of monitors"</code>, <code>"Current monitor rect"</code>, <code>"Current monitor work rect"</code>, <code>"Monitor «N» Rect"</code>, and <code>"Monitor «N» work rect"</code>.
* New optional parameter, «throwParsingErrors», to [[Evaluate]].
* [[ReadFromURL]] is a bit smarter about returning binary content (like <code>*.zip</code> files) as a [[In-memory binary data terms|Binary Data Term]].
* [[MakeJSON]] will automatically encode an image in base64 JSON, and [[ParseJSON]] will automatically decode a base64 representation into an image.
* <code>[[GetProcessInfo]]("UI Language")</code> returns the UI language, either <code>"en"</code> (for English) or <code>"es"</code> for Spanish.
* <code>[[QualifiedName]]( obj, nsContext )</code>: Returns the qualified identifier (as text) that uniquely identifies «obj» from the context of «nsContext».
* <code>[[Namespace]] of X</code>: A new virtual attribute that returns the namespace of «X».
* [[Evaluate]] has a second return value that captures output to the typescript window (including stuff written by [[ConsolePrint]]) during the evaluation.

== System variables ==
* SysVar [[Graph_ColorSequence]]: Replaces [[Graph_ColorSeq]] which is now deprecated. The new sysvar contains a list of color interer with one integer (of the form <code>0x00rrggbb</code>) per color (whereas the deprecated used triples of numbers per color).

== Engine ==
* After loading a large model, it parses expressions in parallel, using multiple threads/cores to parse different variables. On some computers on some models, this can dramatically speed up model load time.
* Color attributes use color integers for consistently (rather than the legacy number triples for R,G,B).
* You can use a localized namespace import (for a single expression or single lexical block) with the syntax
*:<code>[[Using..Do|Using]] NS;</code>

== Model loading ==
When opening a model file, the "checking" stage (when attributes are parsed) parses different expressions on different threads, resulting in substantially faster model load times for very large models.

Note: In the event that this creates a problem with your specific model (maybe due to an as-yet-undiscovered multithreading bug), you can disable it for your model as follows:
# Temporarily turn off multithreading (Skip this step if you are able to load your model)
## New model
## <b>Definition menu / System variables / Settings / Maximum evaluation threads</b>
## Set to 1 (and remember the previous value)
# Open your model
# <b>Definition menu / System variables / Settings / Disable Multithreaded Evaluations</b>
# Press the <code>Edit Table</code> button.
# Check the checkbox for <code>Parsing</code>
# Save your model
# <b>Definition menu / System variables / Settings / Maximum evaluation threads</b>
#: Restore the original value from Step 1

== MCP server ==
* Added an ability to install multiple ADE-based Mcp servers that run different ADE releases. For example, you can install two MCP servers into Claude Code:
* ade-server: Runs ADE 7.1
* ade-server-70: Runs ADE 7.0
The information in the <code>«ADE install folder»\Examples\Mcp_server\README.txt</code> file explain how (with enough info for Claude code to configure this for you).

With both installed, Claude Code (or other MCP-enabled AI agents) can compare results for the same model across different releases, etc.

Side note: The Mcp server was added to ADE 7.0.

== Internals ==
This release has undergone massive internal restructuring and refactorization. Ideally (i.e., in the absence of bugs) these changes won't change functionality, but may alter some aspects of behavior, hopefully for the better.
* Internal data structures use for multi-dimensional arrays has been changed. Possible impacts:
** Likely to remove the sensitivity to the "canonical order" of indexes on evaluation speed.
** May change relative evaluation speeds of various functions and operations.
* Added system modules/namespaces: <code>SysLib_Internal</code> and <code>SysLib_Experimental</code>. Intended for Analytica-internal use.
*[[:Category:Cell format functions|Cell formatting functions]] (like [[CellSpan]], [[CellFill]], etc.) are now [[Struct]]s rather than functions. Does not impact usage, other that making it easier for code to traverse resulting data structures.

== Discontinued... ==
* Plug-in functions. (An old hook that allows you to extend Analytica with compiled functions and UI elements written it C++. We are almost certain no one is using these hooks any more.)
* The sysvar [[Graph_ColorSeq]] is now deprecated (but works for both reading and setting to preserve backward compatibility). It has been replaced by the system variable [[Graph_ColorSequence]].
* The built-in (but undocumented, unsupported) <code>ifpos</code> and <code>if0</code> functions were removed.
* The legacy (deprecated) syntax <code>Using temp:=... Do</code> for declaring locals is no longer supported. Legacy models will have such definitions automatically rewritten to use [[Local..Do]] when you load them. [[Using..Do]] now has a different meaning, which is to provide a temporary namespace import.

Evaluate

2026-06-01T21:22:25Z

Lchrisman: Document Evaluate's optional second return value that captures console output (Release 7.1+)

[[category:Evaluation Functions]]
{{ReleaseBar}}

Evaluate(t) is a powerful, but rarely needed function. If t is text, it parses it as an Analytica expression and evaluates it. If t is a handle to a variable, it evaluates and returns its value.
== Evaluate(t) ==

If parameter «t» is a [[Text values|text value]], [[Evaluate]](«t») tries to parse «t» as an Analytica [[expression]] (as in the [[definition]] of a Variable), evaluates it, and returns the resulting [[value]]. For example:

:<code>Evaluate('10 * 10') → 100</code>

If parameter «t» is a [[Handle]] to a variable, [[Evaluate]](«t») evaluates the variable and returns its value:
:<code>Variable A := 100</code>
:<code>[[Evaluate]]([[Handle]](A)) → 100</code>

You can also use it to evaluate a function passed as an object or handle:
:<code>Function Add(a, b) := a+b</code>
:<code>[[Evaluate]]([[Handle]](Add), 2, 10) → 12</code>
This can be useful when you want to define a function that takes a function as a parameter and applies the function in its body.
See [[#Using Evaluate on a Function]] below.

== Handling errors ==
As of [[Analytica 6.6]], when an error occurs during the parsing or evaluation of «t» ''and'' the call to [[Evaluate]] appears within a [[Try]], evaluation transfers to the «catch» expression of the [[Try]] without presenting any error message dialog to the user. But this isn't true when the only surrounding (possibly nested) [[Try]]s have «errorNum» filters that do not match the occurring error.

If error is not caught by a [[Try]], then a parsing error silently returns [[Null]] and an evaluation error appears to the user like any other evaluation error, typically terminating the computation.

In [[Analytica 6.5]] and earlier, parsing errors are not caught by a surrounding [[Try]] -- they return Null as if there were no surrounding [[Try]].

{{Release|1=7.1|2=|3=
== Capturing console output ==
''New to [[Analytica 7.1]].''

[[Evaluate]] can optionally return a second value containing the text of everything printed to the console while «t» is evaluated, such as the output of any [[ConsolePrint]]() calls. To request it, capture two return values:

:<code>[[Local]] (result, consoleText) {{eq}} [[Evaluate]]('ConsolePrint(2 + 2)') Do consoleText</code>

Here <code>result</code> is the value of the evaluated expression (here <code>4</code>), and <code>consoleText</code> is the captured console output (here the text <code>"4"</code> followed by a newline). Capturing the output does not prevent it from also appearing in the typescript window as it normally does.

The second value captures only output produced ''during'' this evaluation. If «t» refers to a variable whose value is already cached, the variable is not recomputed, so it produces no console output and the captured text is empty.
}}

== Limitations of Evaluate(t) ==

There are some subtleties and limitations to Evaluate(«t») when «t» is a text value.

{{Release|1=|2=6.5|3=If text «t» contains a [[syntax]] error, [[Evaluate]](«t») gives no error message, and returns [[Null]].}}

The context inside the Evaluate parameter is global, not local. So:
:<code>Variable A := 100</code>
:<code>Variable B := ([[Local]] A := 0; [[Evaluate]]('A + 1'))</code>
:<code>B → 101</code>

The Variable <code>A</code> inside <code>Evaluate('A + 1')</code> refers to the global <code>A</code>, not the local <code>A</code> defined in <code>B</code>. More generally:

* [[Evaluate]](t) creates its own context for [[Parsed Expressions|parsing]] «t» (at evaluation time), which is not the context of the expression in which the [[Evaluate]](t) appears -- e.g., the definition of <code>B</code> above.
* So, text «t» cannot refer to [[Local Values|local value]]s, [[index]]es, or [[function parameters]] defined in the context in which the [[Evaluate]](t) function appears.
* Text «t» may itself define local values and indexes, and refer to them, but these will not be available outside «t».
* If the text value of «t» refers to a global variable —e.g., <code>A</code> in the definition of <code>B</code> above—these do not appear as Inputs of <code>B</code>.
* More generally, Analytica cannot track the dependency of any variable name that appears inside the text. So, for example, any change to <code>A</code> will not cause automatic re-evaluation of <code>B</code>:
:<code>A := 3</code>
:<code>B := A + 1</code>
:<code>C := Evaluate('A + 1')</code>
:<code>A := 5</code>

When <code>A</code> changes, Analytica will automatically ensure that <code>B</code> is updated, but it has no way of knowing <code>C</code> should also be recomputed.

The parameter «t» may itself be an expression that creates a text value to be evaluated by [[Evaluate]]. This text expression appears in the definition of <code>V</code> and is not subject to the above limitations, so, for example:

:<code>Variable V :=([[Local]] x:= ’10’; [[Evaluate]](x & x))</code>
:<code>V → 1010</code>

== When to Use ==

The cases in which you should use [[Evaluate]] are rare. You should be reluctant to use it due to the caveats listed in the previous section. Typical cases when it is useful include:
* Parsing simple expressions.
* (advanced) Use in [[Meta-Inference]] algorithms where you are manipulating handles to objects in your model.
* (rare) Cases where you really do wish to by-pass dependency maintenance. You want it to compute something the first time the result is requested after the model is first loaded, but not update when parent values are changes.

== Non-text Parameters ==

A non-text value can also be passed to [[Evaluate]], which can be of use in some [[Meta-Inference]] applications. You need to keep in mind that the parameter to evaluate is evaluated BEFORE the function itself gets it, so evaluating a non-text value is only meaningful when the evaluated parameter is itself something that can still be evaluated. One instance of this that is often useful is the case of a [[handle]] an object.

For example, suppose
:<code>Variable A := 2 + 3</code>
:<code>Variable TheVar := [[Handle]](A)</code>

In the more general case, you might have a [[Meta-Inference]] algorithm that identifies a single variable object through some computation. Having identified the object, <code>TheVar</code> now holds a handle to the object. You then may want to access values or properties of the object pointed to by <code>TheVar</code>, rather than just values or properties of <code>TheVar</code> itself. Evaluate serves this purpose:

:<code>TheVar → A { A -- i.e., a handle to the object A }</code>
:<code>[[Evaluate]](TheVar) → 5 { evaluates A }</code>

It is worth nothing that an alternative method also exists for evaluating a [[handle]]. You can declare a [[LocalAlias]] set to the handle, and then use its identifier as if it were the identifier of the object.

:<code>[[LocalAlias]] x := TheVar Do x → 5 { x is an alias for A, so "x" in the body is the value of A }</code>

When accessing attributes of an object in a [[Meta-Inference]] algorithm, where your algorithm has a handle to an object (again, say it is in <code>TheVar</code>), you can access the attribute using e.g.,

:<code>Description Of Evaluate(TheVar) → "Description of A"</code>
:<code>Description Of TheVar → "Description of TheVar"</code>

(the result of using <code>TheVar</code> alone is shown for comparison).

== Using Evaluate on a Function ==

Given a [[handle]] to a function object, you can use [[Evaluate]] to call the function. If the function expects ''N'' parameters, you would provide ''N+1'' parameters to [[Evaluate]] -- the first parameter being the handle to the function, and the remaining parameters being the values passed to the function. Example:

:<code>[[Local]] fn := [[If]] opt = 1 [[Then]] [[Handle]]([[Max]]) [[Else]] [[If]] opt = 2 [[Then]] [[Handle]]([[Min]]) [[Else]] [[Handle]]([[Sum]]);</code>
:<code>[[Evaluate]](fn, A, I)</code>

Parameters to the function being called are always passed by position, i.e., you cannot use a named-parameter calling syntax as you might if you were calling the function directly.

If the function being called contains repeated (or variable number of) parameters, and you need to include a parameter that follows the [[repeated parameter]], then you must place brackets around the repeated parameters. For example,

:<code> Function Fu1(x; y: repeated; z: optional) := ...</code>
:<code> </code>
:<code>[[Evaluate]](fn, 1, 2, 3, 4) →</code>
::''Equivalent to <code>Fu1(1, 2, 3, 4)</code>, where <code>[2, 3, 4]</code> are values for <code>y</code> and <code>z</code> is omitted''
:<code>[[Evaluate]](fn, 1, [2, 3], 4) →</code>
::''Equivalent to <code>Fu1(1, 2, 3, y: 4)</code>, where <code>[2, 3]</code> are values for <code>y</code>, and <code>z</code> is 4''.

However, there is a limitation that the first supplied parameter (i.e., the second parameter to [[Evaluate]]) cannot be placed inside brackets. Likewise, you cannot pass an literal list by specifying the first parameter as a bracketed list. This is because the repeated-parameter syntax applies equally to [[Evaluate]]. If you specify the first parameter to [[Evaluate]] in brackets, those become the parameters to the function, i.e.,:

:<code>[[Evaluate]]([[Handle]](F), [1, 2, 3, 4]) →</code>
::''Equivalent to <code>F(1, 2, 3, 4)''</code>

Several common built-in functions, including [[Sum]], [[Max]], and [[Min]], allow a variable number of indexes, so that you can use <code>[[Sum]](A, I, J, K)</code> to sum over 3 dimensions in a single call. These functions also have [[optional parameter]]s, such as «ignoreNonNumbers», so that if you need to specify these optional parameters, you will need to place brackets around the index(es), even if only one (or zero) index is specified. For example, the following examples show how to to specify «ignoreNonNumbers» as true to [[Sum]], when summing over a single index, and when summing over the [[implicit dimension]]:

:<code>[[Evaluate]]([[Handle]]([[Sum]]), A, [I], true)</code>
:<code>[[Local]] x := [3, 2, 'a', 'b', 6] do [[Evaluate]]([[Handle]]([[Sum]]), x, [], true)</code>

Notice that if you don't need to specify the optional «ignoreNonNumbers» parameter (or any parameters that follow the repeated index parameters), then it is more natural to omit the brackets:

:<code>[[Evaluate]]([[Handle]]([[Sum]]), A, I)</code>
:<code>[[Local]] x := [3, 2, 5, 3, 6] do [[Evaluate]]([[Handle]]([[Sum]]), x)</code>

{{Release|6.5||
== Evaluating in a different namespace context ==
''New to [[Analytica 6.5]]''

Suppose there are two variables that both have the identifier X, but which live in different [[Namespaces]]. Then
:<code>[[Evaluate]]( "X+1" )</code>
would differ depending on where it appears. By default it resolves the identifier <code>X</code> from the namespace of the object containing the expression. In some esoteric situations, you may need to interpret the expression from a different namespace context. You can do this by first obtaining a handle to the other namespace module, or to any object inside that namespace, and passing that handle to the «nsContext» parameter.
:<code>[[Evaluate]]( "X+1", nsContext: [[Handle]]("NS2") )</code>
}}

== See Also ==
<div style="column-count:2;-moz-column-count:2;-webkit-column-count:2">
* [[EvaluateScript]]
* [[Proactive Evaluation]]
* [[Evaluation Modes]]
* [[Handle]]
* [[Expression Syntax]]
* [[Expression Assist]]
* [[Parsed Expressions]]
* [[Function calls and parameters]]
* [[Summary of Programming Constructs]]
* [[Procedural Programming]]
* [[Meta-Inference]]{{Release|6.5||
* [[Namespaces]]}}
</div>