Analytica Docs - User contributions [en]

Multithreaded evaluation

2016-08-24T14:44:03Z

Bbecane:

[[category:Concepts]]
''new to [[Analytica 5.0]]''

''Requires [[Analytica Professional]]''

Some computations can take advantage of multiple cores on your computer to speed up to net computation time. These computations partition the task across multiple threads, where each thread can be assigned to a different core. For example, when adding two large arrays, <code>A+B</code>, where each array has 100,000 elements, the computation might be parallelized across four threads, with each thread handling roughly 25,000 additions each. As a result, the elapsed time to complete the full array addition might be as much as four times faster than it would have been when evaluated in single threaded mode. Because there is additional overhead required to partition a task and coordinate multiple threads, the actual speedup will end up being something less that the total number of threads.

Multithreaded evaluation uses fine-grained parallelism, meaning that certain low-level computations are parallelized. The computation is decomposed at a high-level. So when concurrent evaluation is occurring, all threads are working on the same task.

Not all operations are decomposed into parallel computation. In general, arithmetic operations are performed concurrently, but only when the arrays are large enough to justify the extra overhead of multithreading. As a rough idea, operators involving arrays with fewer than 100 elements will be evaluated on a single thread, operations involving more than 1,000 cells are likely to be performed on multiple threads (if threads are available), and between there the threshold depends on the internal array structure, specific operation, etc. Several built-in functions operate in parallel, as well as some internal bookkeeping, but again, these use multiple threads only when the arrays involved are large enough to justify the overhead. With new releases of Analytica, additional functions or operations may be enhanced to leverage multithreaded evaluation.

== Requirements ==

Multithreaded evaluation requires [[Analytica Professional]] or better. It is not available in [[Analytica Free 101]].

By default, multithreaded evaluation is disabled in 32-bit Analytica, and it is recommended that you use single threaded evaluation in 32-bit Analytica, since the extra threads consume memory, and is 32-bit Analytica the extra memory space saved by using single-threaded evaluation is usually more important than the speed-ups from multithreaded evaluation.

== Configuration ==

The configuration of multithreaded evaluation is controlled by two system variables. To change these, navigate the menus to [[Definition menu|Definition]] > System variables > Settings'''.

=== Max Evaluation Threads ===

Set this to 1 to force single threaded evaluation, or to a number greater than 1, up to the number of available cores on your computer, to allow multithreaded evaluation. Evaluation will limit the number of threads actually used to this number.

This setting is specific to your computer, and not associated with any model. It persists when you quit and restart Analytica.

If you want to prevent computations from periodically usurping all available cycles, you may opt to set this to a number less than the total number of cores on your computer. If you are running multiple instances of Analytica or ADE, each may use up to this number of threads. Also, since each thread used does require extra memory, you might want to limit the maximum number of threads when you have a small amount of RAM on your computer.

=== Max Model Threads ===

Set this to 1 to force single threaded evaluation for the current model, or to 0 to eliminate any maximum number of threads. You can set it to a number greater than 1 to enforce a maximum number of threads that will be used for evaluation by the current model. The number of threads actually used for evaluation will never exceed this number.

This setting is stored with the current model, and so will be set when you share your model with other people, but it won't impact other models.

Use this setting when you need to limit the number of threads used only for the current model. When Max Model Threads is set, the actual maximum number of threads used will be the smaller of Max Model Threads and Max Evaluation Threads.

One reason to force a model to be single threaded would be a bug were to be discovered that impacts your model with multithreaded evaluation. Another would be if you were to discover that multithreaded evaluation was resulting in a net slowdown for your model, or if you were to find that your model is fastest at some particular number of threads.

== Net speed-up gains from multi-threaded evaluation ==

The net speed-up obtained from multi-threaded evaluation depends strongly on the particular model and computations performed. In general, models that manipulate larger arrays are more likely to derive more benefit.

Suppose that 60% of the operations in your model (as measure as a percentage of time in single-threaded evaluation) are able to take advantage of multithreaded evaluation, and these operations experience a 3-fold speedup as a result (as might be realistic with 4 cores after overhead). Then <code>60% * 2/3 = 40%</code> of the total evaluation time will be saved, which results in a 66% speed-up. So even with four cores, and fairly favorable conditions, the net speed-up is less than a factor of 2.

== History ==

[[Analytica 5.0]] was the first release to include multithreaded evaluation.

== See Also ==

* [[What's new in Analytica 5.0?]]
* [[Evaluate]]
* [[GetProcessInfo]]
* [[Memory usage and management]]

Multithreaded evaluation

2016-08-24T14:38:35Z

Bbecane: /* See Also */

Multithreaded evaluation

2016-08-24T14:33:25Z

Bbecane:

Multithreaded evaluation

2016-08-24T14:31:49Z

Bbecane: /* Configuration */

[[category:Concepts]]
''new to [[Analytica 5.0]]''

''Requires [[Analytica Professional]]''

Some computations can take advantage of multiple cores on your computer to speed up to net computation time. These computations partition the task across multiple threads, where each thread can be assigned to a different core. For example, when adding two large arrays, <code>A+B</code>, where each array has 100,000 elements, the computation might be parallelized across four threads, with each thread handling roughly 25,000 additions each. As a result, the elapsed time to complete the full array addition might be as much as four times faster than it would have been when evaluated in single threaded mode. Because there is additional overhead required to partition a task and coordinate multiple threads, the actual speedup will end up being something less that the total number of threads.

Multithreaded evaluation uses fine-grained parallelism, meaning that certain low-level computations are parallelized. The computation is decomposed at a high-level. So when concurrent evaluation is occurring, all threads are working on the same task.

Not all operations are decomposed into parallel computation. In general, arithmetic operations are performed concurrently, but only when the arrays are large enough to justify the extra overhead of multithreading. As a rough idea, operators involving arrays with fewer than 100 elements will be evaluated on a single thread, operations involving more than 1,000 cells are likely to be performed on multiple threads (if threads are available), and between there the threshold depends on the internal array structure, specific operation, etc. Several built-in functions operate in parallel, as well as some internal bookkeeping, but again, these use multiple threads only when the arrays involved are large enough to justify the overhead. With new releases of Analytica, additional functions or operations may be enhanced to leverage multithreaded evaluation.

== Requirements ==

Multithreaded evaluation requires [[Analytica Professional]] or better. It is not available in [[Analytica Free 101]].

By default, multithreaded evaluation is disabled in 32-bit Analytica, and it is recommended that you use single threaded evaluation in 32-bit Analytica, since the extra threads consume memory, and is 32-bit Analytica the extra memory space saved by using single-threaded evaluation is usually more important than the speed-ups from multithreaded evaluation.

== Configuration ==

The configuration of multithreaded evaluation is controlled by two system variables. To change these, navigate the menus to [[Defiinition menu|Definition]] > System variables > Settings'''.

=== Max Evaluation Threads ===

Set this to 1 to force single threaded evaluation, or to a number greater than 1, up to the number of available cores on your computer, to allow multithreaded evaluation. Evaluation will limit the number of threads actually used to this number.

This setting is specific to your computer, and not associated with any model. It persists when you quit and restart Analytica.

If you want to prevent computations from periodically usurping all available cycles, you may opt to set this to a number less than the total number of cores on your computer. If you are running multiple instances of Analytica or ADE, each may use up to this number of threads. Also, since each thread used does require extra memory, you might want to limit the maximum number of threads when you have a small amount of RAM on your computer.

=== Max Model Threads ===

Set this to 1 to force single threaded evaluation for the current model, or to 0 to eliminate any maximum number of threads. You can set it to a number greater than 1 to enforce a maximum number of threads that will be used for evaluation by the current model. The number of threads actually used for evaluation will never exceed this number.

This setting is stored with the current model, and so will be set when you share your model with other people, but it won't impact other models.

Use this setting when you need to limit the number of threads used only for the current model. When Max Model Threads is set, the actual maximum number of threads used will be the smaller of Max Model Threads and Max Evaluation Threads.

One reason to force a model to be single threaded would be a bug were to be discovered that impacts your model with multithreaded evaluation. Another would be if you were to discover that multithreaded evaluation was resulting in a net slowdown for your model, or if you were to find that your model is fastest at some particular number of threads.

== Net speed-up gains from multi-threaded evaluation ==

The net speed-up obtained from multi-threaded evaluation depends strongly on the particular model and computations performed. In general, models that manipulate larger arrays are more likely to derive more benefit.

Suppose that 60% of the operations in your model (as measure as a percentage of time in single-threaded evaluation) are able to take advantage of multithreaded evaluation, and these operations experience a 3-fold speedup as a result (as might be realistic with 4 cores after overhead). Then <code>60% * 2/3 = 40%</code> of the total evaluation time will be saved, which results in a 66% speed-up. So even with four cores, and fairly favorable conditions, the net speed-up is less than a factor of 2.

== History ==

[[Analytica 5.0]] was the first release to include multithreaded evaluation.

== See Also ==

* [[What's new in Analytica 5.0?]]

Multithreaded evaluation

2016-08-24T14:27:07Z

Bbecane: /* See Also */

[[category:Concepts]]
''new to [[Analytica 5.0]]''

''Requires [[Analytica Professional]]''

Some computations can take advantage of multiple cores on your computer to speed up to net computation time. These computations partition the task across multiple threads, where each thread can be assigned to a different core. For example, when adding two large arrays, <code>A+B</code>, where each array has 100,000 elements, the computation might be parallelized across four threads, with each thread handling roughly 25,000 additions each. As a result, the elapsed time to complete the full array addition might be as much as four times faster than it would have been when evaluated in single threaded mode. Because there is additional overhead required to partition a task and coordinate multiple threads, the actual speedup will end up being something less that the total number of threads.

Multithreaded evaluation uses fine-grained parallelism, meaning that certain low-level computations are parallelized. The computation is decomposed at a high-level. So when concurrent evaluation is occurring, all threads are working on the same task.

Not all operations are decomposed into parallel computation. In general, arithmetic operations are performed concurrently, but only when the arrays are large enough to justify the extra overhead of multithreading. As a rough idea, operators involving arrays with fewer than 100 elements will be evaluated on a single thread, operations involving more than 1,000 cells are likely to be performed on multiple threads (if threads are available), and between there the threshold depends on the internal array structure, specific operation, etc. Several built-in functions operate in parallel, as well as some internal bookkeeping, but again, these use multiple threads only when the arrays involved are large enough to justify the overhead. With new releases of Analytica, additional functions or operations may be enhanced to leverage multithreaded evaluation.

== Requirements ==

Multithreaded evaluation requires [[Analytica Professional]] or better. It is not available in [[Analytica Free 101]].

By default, multithreaded evaluation is disabled in 32-bit Analytica, and it is recommended that you use single threaded evaluation in 32-bit Analytica, since the extra threads consume memory, and is 32-bit Analytica the extra memory space saved by using single-threaded evaluation is usually more important than the speed-ups from multithreaded evaluation.

== Configuration ==

The configuration of multithreaded evaluation is controlled by two system variables. To change these, navigate the menus to '''Definition / System variables / Settings'''.

=== Max Evaluation Threads ===

Set this to 1 to force single threaded evaluation, or to a number greater than 1, up to the number of available cores on your computer, to allow multithreaded evaluation. Evaluation will limit the number of threads actually used to this number.

This setting is specific to your computer, and not associated with any model. It persists when you quit and restart Analytica.

If you want to prevent computations from periodically usurping all available cycles, you may opt to set this to a number less than the total number of cores on your computer. If you are running multiple instances of Analytica or ADE, each may use up to this number of threads. Also, since each thread used does require extra memory, you might want to limit the maximum number of threads when you have a small amount of RAM on your computer.

=== Max Model Threads ===

Set this to 1 to force single threaded evaluation for the current model, or to 0 to eliminate any maximum number of threads. You can set it to a number greater than 1 to enforce a maximum number of threads that will be used for evaluation by the current model. The number of threads actually used for evaluation will never exceed this number.

This setting is stored with the current model, and so will be set when you share your model with other people, but it won't impact other models.

Use this setting when you need to limit the number of threads used only for the current model. When Max Model Threads is set, the actual maximum number of threads used will be the smaller of Max Model Threads and Max Evaluation Threads.

One reason to force a model to be single threaded would be a bug were to be discovered that impacts your model with multithreaded evaluation. Another would be if you were to discover that multithreaded evaluation was resulting in a net slowdown for your model, or if you were to find that your model is fastest at some particular number of threads.

== Net speed-up gains from multi-threaded evaluation ==

The net speed-up obtained from multi-threaded evaluation depends strongly on the particular model and computations performed. In general, models that manipulate larger arrays are more likely to derive more benefit.

Suppose that 60% of the operations in your model (as measure as a percentage of time in single-threaded evaluation) are able to take advantage of multithreaded evaluation, and these operations experience a 3-fold speedup as a result (as might be realistic with 4 cores after overhead). Then <code>60% * 2/3 = 40%</code> of the total evaluation time will be saved, which results in a 66% speed-up. So even with four cores, and fairly favorable conditions, the net speed-up is less than a factor of 2.

== History ==

[[Analytica 5.0]] was the first release to include multithreaded evaluation.

== See Also ==

* [[What's new in Analytica 5.0?]]

Weighted average

2016-08-23T17:35:37Z

Bbecane: Redirected page to Mean

#REDIRECT [[Mean]]

Remove duplicates in an array

2016-08-23T15:35:22Z

Bbecane: Redirected page to Unique

#REDIRECT [[Unique]]

Atom

2016-08-23T15:23:59Z

Bbecane: Created page with "Category: Objects An atom or an '''atomic value''' denotes a single element -- a number, text string, a handle, a reference, or the value Null, i...."

[[Category: Objects]]

An [[atom]] or an '''atomic value''' denotes a single element -- a [[number]], [[text]] string, a [[handle]], a [[reference]], or the value [[Null]], i.e. not an [[array]] (table).

Atomic values form the cells of arrays but they may also stand by themselves as values, e.g. the result of evaluating ''1+2'' is the atomic value ''3'', which is not an array. The Title [[attribute]] of any object is an atomic text value.

Because an [[atom]] can be seen as a zero-dimensional array, atoms are functionally equivalent to arrays with zero indexes, enabling the conversion of atoms to arrays in some cases. Nevertheless, in standard usage the term '''atom''' or '''atomic value''' is used to distinguish simple values from "complex" ones like arrays or lists (one-dimensional arrays).

Because [[atom]]s are not indexed, [[Array Abstraction|array abstraction]] is not always possible on atomic values without a special treatment, see [[Ensuring_Array_Abstraction#Atom_parameters_and_array_abstraction|Atom parameters and array abstraction]] for details.

==See Also==
* [[Objects and Values]]
* [[Atomic..Do]]
* [[Function_parameter_qualifiers#Atom|Atomic function parameters]]
* [[Ensuring_Array_Abstraction#Atom_parameters_and_array_abstraction|Atom parameters and array abstraction]]

Objects and Values

2016-08-23T15:22:09Z

Bbecane: /* See Also */

[[Category:Objects]]

__TOC__

There are two primary types of entities that comprise and are manipulated by Analytica models: ''Objects'' and ''Values''. Understanding this simple distinction can help you understand several of the other language features and concepts in Analytica.

An Analytica ''value'' is essentially data. A value can be an ''intelligent array'' or an ''atomic value''. An [[Intelligent Arrays|intelligent array]] is a collection of [[atomic]] values. The result of any calculation is a value. Anything passed as a parameter to a function or an operator is a value. Values can be stored in various ways, and are the entities manipulated through calculation.

An Analytica ''object'' is an entity that has a class, a name, and set of attribute values. Each attribute value associates a value with a particular attribute, so that an object typically contains several values. For example, a (global) variable, which you often see as a rounded rectangle on an influence diagram, is an object that usually has values associated with the attributes [[Title]], [[Description]], [[Units]], [[Definition]], (mid-)[[Value]], [[ProbValue]] (aka. [[Sample]] value), [[Domain]] and [[Check]] among others. In addition, [[Class]] and [[Identifier]] are also attributes.

The word ''entity'' is not a term we use when referring to Analytica concepts. I use it here to help with the description. The terms ''value'' and ''object'' are specific terms we use within Analytica, and each have each have a precise meaning as described in this article. Both of these words are used in other ways in English and in computer science, so take note that we are using these here to refer to ''Analytica values'' and ''Analytica objects'', as opposed to other common meanings of each of those words.

== Values ==
Value can take subdivided into these subtypes (among others)
* [[Atomic]] values
** Numbers
** Text
** The [[Null]] value
** [[Handle]]s
** [[Reference]]s
* [[Array]]s
** Lists

Atomic values form the cells of arrays, but they may also stand by themselves as values. For example, the result of ''1+2'' is the atomic value 3, which is not an array. The Title attribute of any object is an atomic text value. We use the term "atomic value", or just "atom", to distinguish from an array.

A array is a rectangular (or hyper-rectangular) collection of "cells", where each cell contains an atomic value. Arrays can have between 1 and 24 dimensions (or between 1 and 15 dimensions in 32-bit Analytica). Each dimension is associated with an index, with each dimension associated with a different ''index''. An index, by the way is an object. There is one exception -- during computation, one dimension of an array can contain an [[Self-Indexed_Arrays|implicit index]]. A list is a 1-D array where the only dimensions is an implicit dimension. Lists are used to define indexes. See also [[Function_parameter_qualifiers#Atom|Atomic function parameters]] and [[Atomic..Do]].

== Objects ==
An Analytica object is an entity that has a [[Class]], an [[Identifier]] (or name), and several other attribute values. The class and identifier are in fact attributes themselves. Most objects are in the global namespace, and each object in the global namespace must have a unique identifier. Some objects, most notably [[Local Indexes|local indexes]], are not in the global namespace, and don't need to have a unique [[identifier]].

Objects can be sub-divided into the following subtypes (among others)
* Global variables
** Decision variables
** General variables
** [[Chance]] variables
** [[Objective]] variables
** [[DefineOptimization#Constraints|Constraint]] variables
** (Global) indexes
** Constants
** [[System variables]]
* Functions
** Built-in functions
** [[User-Defined Functions]]
* [[Modules_and_Libraries|Modules]]
** Model objects
** [[Libraries]]
* [[Buttons]]
* Pictures
* Text nodes
* [[User input nodes and user output nodes|FormNodes]] (user input and output nodes)
* [[Alias nodes]]
* [[Graph Style Templates|Graph style templates]]
* [[Local Indexes]]
* [[Domain Indexes]]
* [[Attributes]]

The [[Object Window]] is used to view an object, and from that window you can directly see the various attribute values contained within the object. The [[Object Window]] shows you a subset of these values. From the [[Typescript Window]], you can use the [[Profile]] command so see all the attribute values in an object.

== What about COM Objects? ==
Are [[COM Integration|COM objects]] actually objects, as the name implies? The answer is that they are not ''Analytica objects'', as identified above, although they do have similar characteristics in many ways. For example, whereas Analytica objects have attribute values, COM objects have properties. As mentioned earlier, the word ''object'' is used in many ways in computer science, and the term ''COM objects'' was created outside the context of Analytica. When you call [[COMCreateObject]], a thing called a ''COM object'' is instantiated somewhere in your computer's memory (it can even be in the memory of a remote computer), but the result from [[COMCreateObject]] is a "''moniker''" or "''pointer''" to that object, which is a type of atomic value that is used to reference that thing. This pointer is an Analytica value.

Suppose you define a variable, <code>A</code>, to be a call to [[COMCreateObject]]. Its result is a pointer to that COM object. If you then define variable <code>B</code> to be <code>A</code>, the pointer is copied, but there is still only a single COM object. Now both <code>A</code> and <code>B</code> point to the same COM object.

== Indirect Referents ==
A [[Handle]] is an indirect referent to an Analytica object, and a [[Reference]] is an indirect referent to an Analytica value. These are the two fundamental forms of indirection referents. You can think of an ''indirect referent'' as a ''pointer''. For example, an object exists somewhere in memory. There is only one copy of this object. But you might want to refer to this object -- that is the role of a [[handle]]. Similarly, a value exists somewhere in memory. You may want to refer to that value without making a copy of it -- a [[Reference]] allows you to do this. When you create multiple copies of a [[handle]], the object itself is not copies -- they all point to the same object -- you end up with several handles to the same object.

Because Analytica is a functional language with [http://en.wikipedia.org/wiki/Referential_transparency_(computer_science) referential transparency], a reference does not allow you to change the contents of a value. Any time you make a change to a value, a new copy must be made. However, the useful thing about a [[reference]] is that it is itself an atomic value. So even though it might "point" to an array, it acts as an atom for [[Array Abstraction]].

== Locals ==
Locals are identifies in expressions that act as names for either values or objects. There are a couple different types of locals:

* [[Local Indexes]]
* [[LocalAlias]]
* [[MetaVar]]s and standard local variables

Local indexes create an index object, which can then serve as the dimension on an array. The identifier of the local index is therefore a name that can be used to refer to the index object. Local indexes to not live in the global namespace, so they do not need to have a unique identifier. When you declare a local index, you can specify the object name explicitly, and it does not have to be the same as the local name. This is done using this syntax

:<code>Index I / "''Name''" := expr;</code>

Within the lexical scope of <code>I</code>, you can refer to this index object by <code>I</code>, but the name of the object is actually <code>Name</code>.

A [[LocalAlias]] declares a name for an object, that can be used within a local lexical expression scope. Hence, in the following declarations, <code>I</code>, <code>J</code>, and <code>K</code> can be used as names for other pre-existing objects.

:<code>LocalAlias I := Data.Row;</code>
:<code>LocalAlias J := Handle(Va1);</code>
:<code>LocalAlias K := Contains of ModelDetailsModule;</code>

In the last example, <code>[[Contains]] of ModelDetailsModule</code> is a list of [[handle]]s, but within the lexical scope of <code>K</code>, <code>K</code> will name only one of these objects at a time. The ''body expression'' -- that expression in the lexical scope of <code>K</code>, will be evaluated once for each object in <code>[[Contains]] of ModelDetailsModule</code>.

Most other local variables, declared using [[MetaVar..Do]], [[Var..Do]], or [[For..Do]], are alias to values. It is important to note that ''local variables are not Analytica objects'', whereas global variables (those that show on influence diagrams) are Analytica objects. Again -- ''local variables declare a name for a value''. There is only one value -- there is not a separate [[Value|Mid-Value]] or [[ProbValue|Sample-Value]]. The value is computed and set when the variable is declared (or assigned to), and after that, the [[Evaluation Modes|evaluation mode]] has no relevance.

==See Also==
<div style="column-count:2;-moz-column-count:2;-webkit-column-count:2">
* [[The domain of possible values]]
* [[Values in Object Window]]
* [[Evaluation Modes]]
* [[Objects_and_Their_Attributes_-_Part_1_of_3|Objects and Their Attributes]]
* [[Attrib of Obj]]
* [[Classes of variables and other objects]]
* [[Change class of an object]]
* [[Atom]]
* [[Array]]
* [[Class]]
* [[COM Integration|COM objects]]
* [[Object window]]
* [[Object menu]]
* [[Object Manipulation Typescript Commands]]
* [[LocalAlias]]
* [[Contains]]
* [[Identifier]]
* [[Numbers]]
* [[Handles to Objects]]
</div>

Atomic..Do

2016-08-23T15:21:17Z

Bbecane:

[[Category:Evaluation Functions]]

== Atomic x := expr Do body ==
Declares a local variable, «x», that can be referred to only from within the expression «body», and assigns it the initial value obtained by evaluating «expr». When used from within «body», Analytica guarantees that the value of «x» is [[Objects_and_Values#Values|atomic]] -- i.e., non-[[array]]-valued. Analytica achieves this guarantee by iterating (horizontally [[Array Abstraction|array abstracting]]) across the result of «expr» when it is array-valued.

'''Atomic''' «x» := «expr» '''Do''' «body» is exactly equivalent to:
:[[MetaVar]] «x»[ ] := «expr» Do «body»

In most common scenarios, it is also equivalent to these, although there are some subtle distinctions as special cases.
:[[For]] «x» := «expr» Do «body»
:[[For]] «x»[ ] := «expr» Do «body»
:[[Var]] «x»[ ] := «expr» Do «body»

==History==
This construct was introduced in Analytica 4.2.

== See Also ==
* [[Atom]]
* [[Objects_and_Values#Values|Atomic values]]
* [[Function_parameter_qualifiers#Atom|Atomic function parameters]]
* [[Var..Do]]
* [[MetaVar..Do]]
* [[For..Do]]
* [[For versus Var]]

Text

2016-08-23T15:17:01Z

Bbecane: Redirected page to Text values

#REDIRECT [[Text values]]

Number

2016-08-23T15:16:27Z

Bbecane: Redirected page to Numbers

#REDIRECT [[Numbers]]

Array Abstraction

2016-08-23T15:01:19Z

Bbecane: /* See Also */

[[Category:Arrays]]
[[Category:Doc Status D]] 

(in-progress)

__TOC__

'''Array abstraction''' is one of the most powerful features in Analytica. Although conceptually simple, Analytica modelers find that their mastery of [[array]] abstraction continues to improve over the course of years. Array abstraction provides many benefits:
* Flexibility: Easy to alter an [[index]], e.g., adding or deleting elements.
* Hyper-flexibility: Easy to adjust the dimensionality of a model, even late in the modeling process.
* Direct [[what-if analysis]] and [[parametric analysis]].
* Simplifies expressions, which increases transparency
* Reduces the cognitive load of the modeler, with dramatic productivity gains during model creation.
* Speed - Analytica is an array-based semi-interpreted language, but array operations, the bulk of the computation, occur in "native code".
* Representational Power: Any simple scalar function becomes a powerful array function when abstracted.
* Synergy with probabilistic inference: [[Monte Carlo]] and [[Latin Hypercube]] simulation are accomplished in Analytica through array abstraction. The [[Run]] index (i.e., the simulation index), is just another dimension, and the [[propagation of uncertainties]] through the model is an instance of array abstraction at work.

== Array abstraction of a scalar function ==
=== One parameter function ===
The function [[Sqrt]](x) computes the square root of «x». When you supply an array as a parameter, array abstraction iterates the function over all elements of the array and returns an array with the same dimensionality as the original.

:<code>A := </code>

:[[image:ArrayAbstract_A.png]]

:<code>Sqrt(A) :=</code>

:[[image:ArrayAbstract_B.png]]

[[Sqrt]] is an example of a scalar function with one parameter. We say that it treats its parameter as ''atomic'', or it treats its parameter as an ''atom''.

=== Parameters have same indexes ===
The plus operator treats both its parameters as atoms. If both values supplied to the parameters have the same dimensionality, then array abstraction iterates over each index combination, producing an array result with the same dimensionality as the parameters.

:<code>Variable B := Sqrt(A)</code>
:<code>A + B →</code>

:[[image:ArrayAbstract_A+B.png]]

=== An array parameter with a scalar parameter ===
The [[Mod]](x, y) function returns the remainder of dividing «x» by «y». It treats both parameters as atoms. When one parameter is an array and the other is scalar, array abstraction iterates over each cell of the array and applies the function using the same scalar value.

:<code>Mod(A, 5) → </code>

:[[image:ArrayAbstract_Mod_A_B.png]]

=== Equivalence of a scalar and a non-varying array ===
When you combine an array with a scalar, you get the same result as you would get if you combined the array with another array having the same indexes, but where every cell contains the scalar value.

:[[image:ArrayAbstract_A.png]] <code>+ 5 →</code>
:[[image:ArrayAbstract_A+5.png]]

:[[image:ArrayAbstract_A.png]] <code>+</code> [[image:ArrayAbstract_5.png]] <code>→</code>
:[[image:ArrayAbstract_A+5.png]]

We say that an array that does not vary is equivalent to scalar with respect to array abstraction. It is a general principle that exchanging a value with an equivalent value in a computation produces an equivalent result. The indexes of the new result might be different, but if so, the result will be constant along any index that does not appear in its equivalent result.

This principle of equivalence gives rise to a general principle in Analytica modeling: You only need to include an index if the data you are representing varies over that index.

An inverse perspective is that you can conceptualize any value has if it has every index, but does not vary along those indexes that aren't shown.

=== Combining arrays with different indexes ===
When the two (or more) parameters to a scalar function or operator are arrays with different indexes, the result has the union of the indexes from the parameters. For example, if the first parameter has indexes <code>I</code> and <code>J</code>, and the second parameter has indexes <code>J</code> and <code>K</code>, the result has indexes <code>I, J</code>, and <code>K</code>.

From the previous subsection, we saw that an array index by <code>I</code> and <code>J</code> is equivalent to an array indexed by <code>I, J</code>, and <code>K</code> which does not vary along <code>K</code>. Similarly, an array indexed by <code>J</code> and <code>K</code> is equivalent to and array indexed by <code>I, J</code>, and <code>K</code> that does not vary along <code>I</code>. You can substitute these equivalent arrays for the originals to obtain two arrays with identical dimensionality, which is a case covered above.

Another way to think about it is that for each cell in the result, find the cell in each parameter that matches on the coordinates for the indexes that the result and parameter has in common. Apply the scalar function to those cells to obtain the result.

Consider this example:

:[[image:ArrayAbstract_C.png]] <code>+</code> [[image:ArrayAbstract_D.png]] <code>→ </code>

:[[image:ArrayAbstract_C+D.png]]

First, observe that the result has all indexes from the parameters. Then, notice that the result cell for <code>[I = 3, J = 2]</code> is <code>C[I = 3] + D[J = 2]</code>. You should study the example to understand where each result cell comes from. You should also study the next example.

:[[image:ArrayAbstract_C.png]] <code>+</code> [[image:ArrayAbstract_D2.png]] <code>→</code>

:[[image:ArrayAbstract_C+D2.png]]

=== Test yourself ===
The two indexes named <code>Tens</code> and <code>Ones</code> are defined as <code>0..9</code>, and <code>Pos</code> has these indexes as shown.

:[[image:ArrayAbstract_Pos.png]]

* Write a short expression for the Definition of <code>Pos</code> that produces this result. Hint: It requires only two arithmetic operations.

The array <code>N_sqr</code> has index <code>N</code>, <code>N := 0..99</code>, and each cell is equal to the square of <code>N</code>.

:[[image:ArrayAbstract_N_sqr.png]]

The [[Subscript]] expression, <code>N_sqr[N = Pos]</code>, can be viewed as a scalar function of <code>Pos</code>. In function syntax, this can be equivalently written as <code>Subscript(N_sqr, N, Pos)</code>. Note: The first parameter of [[Subscript]] is not a scalar -- it expects an array, but here you can visualize that as being fixed, so that we are essentially considering the function

:<code>Function F(x) := N_sqrt[N = x]</code>

which is a scalar function of <code>x</code>.

* Use the principles of array abstraction on scalar functions to find the result of <code>N_sqrt[N = Pos]</code>. Note: An array, <code>Pos</code> is being passed to a parameter that is treated as an atom.

== Array abstraction of a function with an array parameter ==
The above section considered the case where a function treats a parameter as atomic. Let's now consider the case where a function operates over an array.

=== Functions with one array parameter ===
The function <code>Sum(x, I)</code> expects an array for the first parameter. It also expects an index as a second parameter, which tells the function which index to operate over. It is generally the case for a functions that array-abstracts that an array parameter is accompanied by an index (or indexes) specified which indexes are operated over. You can say that [[Sum]] expects the first parameter to be an array indexed by «I». In other words, it expects the first parameter to be a one-dimensional array.

Although <code>Sum(x, I)</code> expects «x» to be one-dimensional, there is no problem with passing a 2-D, or even 10-D, value to the first parameter. Once again, array abstraction kicks in and iterates over all combinations the indexes of «x» excluding index «I». For each combination, it takes the slice that remains and applies the function.

:<code>A := </code>

:[[image:ArrayAbstract_A.png]]

:<code>Sum(A, I) := </code>

:[[image:ArrayAbstract_Sum_A_I.png]]

In the example here, <code>A</code> contains and extra index, <code>J</code>. So <code>Sum(A, I)</code> iterates over <code>J</code>. It calculates the sum over <code>I</code> for the slice <code>A[J = 1]</code>, and then again for the slice <code>A[J = 2]</code>.

* Test yourself: Notice that <code>Sum(A, I)[J = 2]</code> is the same as <code>Sum(A[J = 2], I)</code>. Is there a general principle here?

== The general principle of array abstraction ==
== Composition and array abstraction ==

== See Also ==
* [[Intelligent Arrays]]
* [[Ensuring Array Abstraction]]
* [[Writing Array-Abstractable Definitions]]
* [https://www.youtube.com/watch?v=_8ZaXnEwhoE Intelligent Array Abstraction] (an explanatory video on YouTube)
* [[Expressions that don't array-abstract]]
* [[Array Manipulation Examples and Challenge Problems]]

Unique

2016-08-23T14:57:09Z

Bbecane: /* Unique(a, I) */

[[Category:Functions that create lists]]
[[Category:Array Library]]
[[Category:Doc Status C]] 

==Unique(a'', <code>I</code>'')==

Without the index parameter <code>«I»</code>, returns a list containing all the unique [[atom]]s in «a». The resulting list has any duplicates removed. «a» can be a multidimensional array, and the result contains the unique atoms (cells) across all dimensions.

When an index <code>«I»</code> is specified, it returns a maximal subset of index <code>«I»</code> such that each indicated [[slice]] of array «a» along <code>«I»</code> is unique. This usage can be used to remove duplicate slices from an array, or to identify a single member of each equivalence class.

== Example ==
Let:

:<code>Variable DataSet :=</code>
:{| class="wikitable"
!
!colspan="3" | Field ▶
|-
!PersonNum ▼'''
!LastName
!FirstName
!Company
|-
! scope="row" |1
|Smith
|Bob
|Acme
|-
! scope="row" |2
|Jones
|John
|Acme
|-
! scope="row" |3
|Johnson
|Bob
|Floorworks
|-
! scope="row" |4
|Smith
|Bob
|Acme
|}

Then:

:<code>Unique(DataSet) → ['Smith', 'Jones', 'Johnson', 'Bob', 'John', 'Acme', 'Floorworks' ]</code>
:<code>Unique(DataSet, PersonNum) → [1, 2, 3]</code>
:<code>Unique(DataSet[Field = 'Company'], PersonNum) → [1, 3]</code>

== Optional parameters ==
=== Position ===
By default, [[Unique]] returns the elements of the index. Setting the optional parameter «position» equal <code>true</code> (<code>position: true</code>) will return the positions of the elements in <code>«I»</code> , rather than the elements themselves (see [[Associative vs. Positional Indexing]]).

This parameter is not used when the <code>«I»</code> index parameter is omitted.

===CaseInsensitive===
When applying [[Unique]] to text values, values are considered by default in a case-sensitive fashion, for example, "Apple" and "apple" are considered distinct elements.

Specifying <code>caseInsensitive: true</code> ignores differences in upper and lower case in text values when determining if values are unique.

=== ResultIndex ===

When an index is provided for this parameter, the result is indexed by the given [[index]] instead of being an unindexed list. If the index supplied is shorter than the number of unique items, then only the first ''n'' items are returned, where ''n'' is the size of the index. When the result index is too long, the result is [[null]]-padded.

«ResultIndex» can be useful when you want to [[Array Abstraction|array abstract]]. For example, in a 2-D array <code>a</code>, you may want to identify the unique items along <code>I</code> separately for each item in index <code>J</code>, as follows.

:<code>For jj := J Do Unique(a[J = jj], I, resultIndex: I)</code>

Without the «resultIndex» parameter, each iteration would return a list, and the [[For]] loop would then need to combine multiple list (i.e., implicit dimensions), which would be disallowed and result in an error. By ensuring that each result has an explicit index -- <code>I</code> in this example -- the results can be successfully combined.

It is also worth noting that the [[For]] loop example just given is not equivalent to
:<code>Unique(a, I, resultIndex: I)</code>

The reason is that <code>Unique(a, I)</code> compares entire [[slice]]s -- it isn't operating over each slice of the exogenous dimensions separately as most other array functions do.

== Notes ==
The [[Set Functions]] such as [[SetDifference]] or [[SetUnion]] ensure that no duplicates exist in the final result, and hence can also be used to find the unique elements. For example, when <code>L</code> is a 1-D array or list

:<code>#SetDifference(\L)</code>
and
:<code>Unique(L)</code>

do the same thing. Since no set is being differences, [[SetDifference]] returns the set <code>\L</code> after duplicates are removed. In some instances, [[SetDifference]] has advantages over [[Unique]]. For example, if you also want to ignore certain values, including [[Null]] or others, you could compute the unique elements and then follow that with a call to [[SetDifference]] to remove the other values, but when so doing, you might as well skip the call to [[Unique]] entirely since [[SetDifference]] already does that for you.

The ordering of elements in the result follows the ordering of the elements in «a», which often feels arbitrary. Hence, it is common to wrap the call to [[Unique]] is a call to [[SortIndex]] such as

:<code>SortIndex(Unique(a))</code>

== History ==

The «I» parameter was first made optional in [[Analytica 5.0]]. Prior to that, the <code>Unique(a)</code> usage was not available. Without to omitted index, use <code>a[I = Unique(a, I)]</code> or <code>#SetDifference(\a)</code> to define an index.

The «resultIndex» parameter is present in [[Analytica 4.3]] and later, but hidden (doesn't show up in [[Expression Assist]], etc.) until [[Analytica 5.0]]. You can still use it in those earlier releases even though it is hidden.

== See also ==
* [[SortIndex]]
* [[Subset]]
* [[Set Functions]] -- These also remove duplicates from their results.

Count

2016-08-23T14:30:52Z

Bbecane: Redirected page to Sum

#REDIRECT [[Sum]]

Count atom

2016-08-23T14:30:17Z

Bbecane: Redirected page to Sum

#REDIRECT [[Sum]]

Numbers

2016-08-23T00:03:39Z

Bbecane:

[[Category: Analytica User Guide]]
[[Category: Number formats]]

<breadcrumbs>Analytica User Guide > Expressions > {{PAGENAME}}</breadcrumbs>

You can enter a number into an expression using any available number formats in (see [[Number formats]]), including:
:<code>2008, 12.345, 0.00123, 5.3E20, 5.3E-20, $100,000</code>

Suffix format uses a letter or symbol suffix to denote a power of ten, such as:
:<code>25K, 200M, 123p, 20%</code>

Suffix format provides a simple, familiar way to specify large or small numbers. See [[Number formats|Suffix characters]] for details.

You can usually enter numbers using most number format types directly into an expression no matter what number format was specified for the variable defined by the expression. The exceptions are:

# You may use commas to separate groups of three digits, such as <code>123,456.00</code>, only if the expression consists of that single number. If the number is part of an expression with other elements, such as <code>12*123,456</code>, you may ''not ''use comma separators because the syntax would be ambiguous. You should use simply <code>12*123456</code>.
# Dates, date-times, or times-of-day must be typed in a very specific format when the number format is not set to date, or when they appear within an expression with other elements. See [[Date and Time Values]].

'''Integers, Fixed Point and Floating Point''': Integer values that you enter between <code>-9,223,372,036,854,775,807</code> and <code>9,223,372,036,854,775,807</code> are represented internally as integers, and numbers that you enter between <code>-9,223,372,036,854.775807</code> and <code>9,223,372,036,854.775807</code> with 6 or fewer decimals are represented internally with full precision as fixed-point numbers. Numbers with more than 6 decimal digits of precision or outside these ranges are represented using 64-bit binary floating point numbers.

'''Precision''': Integer and fixed-point numbers are exact representations of the numeric value, and hence, Analytica prefers these representations when possible. Floating point values are, in general, approximate values, accurate to about 15 significant digits. Many base-10 floating point numbers cannot be represented exactly in binary, and hence may have some rounding error in the 16th digit.

'''Round-off error''': Some calculations, especially those that involve small differences between large numbers or large numbers of additions, might result in less precision than this maximum, or may magnify existing [[round]]-off error.

When calculations are performed with integer or fixed-point numbers, the result is represented internally as an integer or fixed-point number if Analytica is able to do so, which it usually is able to do with addition, subtraction, and multiplication. These results have zero round-off error. With many other operations, such as division or functions like [[Sqrt]](), this is not possible, so the result is floating point number. Operations involving floating-point numbers result in floating-point numbers even if the result appears to be an integer, since the result is no longer guaranteed exact, and always subject to the possibility that round-off error could accumulate.

'''Largest and smallest numbers''': Analytica can represent positive numbers between about 10<sup>-320</sup> and 1.797x10<sup>308</sup>. If a calculation would result in a number smaller than about 10<sup>-320</sup>, it rounds it down zero:
:<code>1/10^1000 → 0</code>

If the result would be larger than 1.797x10<sup>308</sup> it returns <code>INF</code> (infinity):
:<code>10^1000 → INF</code>

For more, see [[Exception values INF, NAN, and NULL]].

'''Complex Numbers''': To enter the imaginary part of a [[Complex Numbers|complex number]], append a lowercase ''j ''or ''i ''to the number, as in these examples
:<code>1j, -1-1j, -2M+23Kj, 4-7e-8j</code>

In the <code>4-7e-8j</code> example, the imaginary part is <code>-7e-8</code> (i.e., <code>-70n</code>). There cannot be a space between the digit and the ''j'', and if you want just the imaginary number, you must write <code>1i</code> or <code>1j</code>, since without the preceding 1, you would be referring to a variable named <code>i</code> or <code>j</code>.

The real and imaginary components are both represented internally as 32-bit floating point numbers, each spanning the range from <code>3.4e+38</code> to <code>3.4e-38</code> with about 7 digits of precision. A complex number consumes the same amount of memory as a real number, but sacrifices range and precision to do so. As a result, you will experience greater round-off error in calculations that use complex numbers.

==See Also==
<div style="column-count:2;-moz-column-count:2;-webkit-column-count:2">
* [[Number formats]]
* [[Number Format Dialog]]
* [[NumberFormat]] attribute
* [[Data_Type_Functions#Function_IsNumber|IsNumber]]
* [[NaN|Not a Number]]
* [[INF, NAN, and Null]]
* [[INF, NAN, and NULL - Exception values]]
* [[IsNaN]]
* [[IsNull]]
* [[Complex Numbers]]
* [[EnableComplexNumbers]]
* [[Complex number functions]]
* [[Binary and hexadecimal integer formats]]
* [[ReadBinaryFile]]
* [[WriteBinaryFile]]
* [[BitAnd]]
* [[Numbers and text]]
* [[Converting Numbers to Text]]
* [[NumberToText]]
* [[ParseNumber]]
* [[Round]]
* [[Numeric Tolerance and Precision]]
* [[Function_parameter_qualifiers#Number| Number type function parameters]]
* [[The_Analytica_Domain_Attribute#Discrete_Numeric|Numeric variables]]
* [[Domain_Expressions#Integer.28.29|Integer() variable specification function]]
* [[Math functions]]
* [[Objects and Values]]
* [[Multiple formats in one table]]
</div>

<footer>Expressions / {{PAGENAME}} / Date and Time Values</footer>

Text values

2016-08-23T00:02:53Z

Bbecane:

[[Category:Analytica User Guide]]
<breadcrumbs>Analytica User Guide > Expressions > {{PAGENAME}}</breadcrumbs>

You specify a text value by enclosing text between single quotes, or between double quotes, for example:
:<code>'A', "A25", 'A longish text - with punctuation.'</code>

A text value can contain any character, including any digit, comma, space, and new line. To include a single quote(<code>'</code>) or apostrophe, type two single quotes in sequence, such as:
:<code><nowiki>'Isn''t this easy?'</nowiki></code>

The resulting text contains only one apostrophe. Or you can enclose the text value in double quotes:
:<code>"Don't do that!"</code>

Similarly, if you want to include double quotes, enclose the text in single quotes:
:<code>'Did you say "Yes"?'</code>

You can enter a text value directly as the value of a variable, or in an expression, including as an element of a list (see [[Creating an index]]) or edit table (see [[Defining a variable as an edit table]]). Analytica displays text values in results without the enclosing quotes. Also see [[Numbers and text|Converting number to text]].

For comparison and sort order for text, see [[Operators|Alphabetic ordering of text values]]. For functions that work with text values, see [[Text functions]].

For converting between numbers and text, see [[Numbers and text]].

==See Also==
* [[Operators#Alphabetic ordering of text values|Alphabetic ordering of text values]]
* [[Text functions]]
* [[IsText]]
* [[Text Concatenation Operator: &]]
* [[Converting Numbers to Text]]
* [[Numbers and text]]
* [[Read and write text files]]
* [[Graphics, frames, and text in a diagram]]
* [[Objects and values]]
* [[Choice]]
* [[Multiple formats in one table]]

<footer>Boolean or truth values / {{PAGENAME}} / Operators</footer>

Converting Numbers to Text

2016-08-23T00:02:44Z

Bbecane:

[[Category:Styles and options]]

To convert a number to a text value, you can use [[Text Concatenation Operator: &|string concatenation]], e.g., <code>"" & x</code>.

==Examples==

:<code>"" & (2^10) → '1024'</code>
:<code>"" & Pi → '3.142'</code>
:<code>"" & Exp(10) → '22.03K'</code>

The coercion uses the number format for the object that contains the expression being evaluated. So, to use a different number format for the coercion, you must set the number format for that object.

To avoid confusion between the format for displaying results and the format used for number-to-text conversion, a better way to perform the conversion is to define a [[User-Defined Function]] for the specific number format you are interested in. For example:

:<code>Function NumberToYYYY_MMM_DD(x) := "" & x</code>
::<code>{ Set its number format to Date → Custom → YYYY-MMM-DD }</code>

:<code>Function NumberToDollars(x) := "" & x</code>
::<code>{ Set its number format to Fixed Point, currency, two digits, show trailing zeroes }</code>

With these, you can now accomplish the desired coercions using these functions. The number format for the function determines the conversion, rather than the number format for your variable.

== See Also ==

* [[Function_Parameter_Qualifiers#Coerce_.3Ctype.3E|Coerce function parameter qualifier]]
* [[Numbers]]
* [[Numbers and text]]
* [[NumberToText]]
* [[ParseNumber]]
* [[ParseDate]]
* [[Number Format Dialog]]
* [[User-Defined Functions]]
* [[Math functions]]
* [[Text functions]]
* [[Multiple formats in one table]]

Text functions

2016-08-23T00:02:18Z

Bbecane: /* See Also */

[[Category:Analytica User Guide]]
[[Category: Text Functions]]
<breadcrumbs>Analytica User Guide > Text, Date, Math, and Financial Functions > {{PAGENAME}}</breadcrumbs>

__TOC__

These functions work with [[text values]] (sometimes known as strings), available in the built-in Text library.

==Asc(t)==
Returns the ASCII code (a number between 0 and 255) of the first character in text value «t». This is occasionally useful, for example to understand the alphabetic ordering of text values.

See also [[Asc]](t).

==Chr(n)==
Returns the character corresponding to the numeric ASCII code «n» (a number between 0 and 255). [[Chr]]() and [[Asc]]() are inverses of each other, for example:

:<code>Chr(65) → 'A', Asc(Chr(65)) → 65</code>
:<code>Asc('A') → 65, Chr(Asc('A')) → 'A'</code>

[[Chr]]() is useful for creating characters that cannot easily be typed, such as ''Tab'', which is <code>Chr(9)</code> and ''carriage return (CR)'', which is <code>Chr(13)</code>. For example, if you read in a text file, <code>x</code>, you can use
<code>SplitText(x, Chr(13))</code> to generate an array of lines from a multiline text file.

==TextLength(t)==
Returns the number of characters in text «t».

See also [[TextLength]]().

:<code>TextLength('supercalifragilisticexpialidocious') → 34</code>

==SelectText(t, m, n)==
Returns text containing the «m»'th through the «n»'th character of text «t» (where the first character is «m»=1). If «n» is omitted it returns characters from the «m»'th through the end of «t».

See also [[SelectText]]().

:<code>SelectText('One or two', 1, 3) → 'One'</code>
:<code>SelectText('One or two', 8) → 'two'</code>

===FindInText(substr, text, ''start, caseInsensitive, re, return, subpattern, repeat, repeatSubpattern, repeatIndex'')===
Returns the position of the first occurrence of «substr» within «text», as the number of characters to the first character of text. If it can't find «substr» in text, it returns 0.

:<code>Variable People := 'Amy, Betty, Carla'</code>
:<code>FindInText('Amy', People) → 1</code>
:<code>FindInText('Betty', People) → 6</code>
:<code>FindInText('Fred', People) → 0</code>

=== Optional parameters ===

==== CaseInsensitive ====
[[FindInText]]() is case-sensitive unless the optional parameter «caseInsensitive» is true:
:<code>FindInText('amy', People) → 0</code>
:<code>FindInText('amy', People, caseInsensitive: true) → 1</code>

==== Start ====
The optional third parameter, «start», specifies the position to start searching at, for example, if you want to find a second occurrence of «substr» after you have found the first one.

:<code>FindInText('i','Supercalifragilisticexpialidocious') → 9</code>
:<code>FindInText('i','Supercalifragilisticexpialidocious', 10) → 14</code>

==== Repeat, RepeatIndex ====
Normally [[FindInText]]() returns information on the first match, but by using any of the three optional repeat parameters can be used to find all matches in text. When it finds multiple matches, the result is an array. If you specify<code>repeat: true</code>, the resulthas a local index named <code>.Repeat</code> with elements <code>1..n</code>.

Alternatively, you can specify a preexisting index as «repeatIndex» parameter. If that index has ''n'' elements, it returns only the first ''n'' matches.

This example parses XML text, returning an array of ages with a local index named «.Name», where the labels of the local index are the names of each person:

:<code>FindInText('<person.*?name = "(?<name>(.*?))".*?>.*?' & '<age>(?<age>.*?)</age>.*?' & '</person>', xmlText, re: true, return: 'S', repeatSubpattern: 'name', subpattern: 'age')</code>

==== Re (Regular expression), Return, and Subpattern ====

If you set optional parameter, «re», to <code>True,</code>it interprets «substr» as a ''regular expression''. The regular expression language is widely used (not just in Analytica) to specify match criteria for text. It offers "wild cards" that match any letter, digit, or other character, identify separate words, and a lot more. See [[Regular expression]]s for details.

Parentheses within a regular expression denote subpatterns, numbered in a depth first fashion. Subpatterns can also be named using the regular expression format “<code>(?<name>...)</code>”. You can the match information for any subpattern by specifying the subpattern number or subpattern name in the optional «subpattern» parameter.

:<code>FindInText('d.*T', 'FindInText', re:1) → 4</code>
:<code>FindInText('d.*T', 'FindInText', re: 1, return:['L', 'S']) → [4, 'dInT']</code>
:<code>FindInText('(\d\d\d)-(\d\d\d\d)', '650-212-1212', re:1, return:’S’, subpattern:[0, 1, 2]) → ['212-1212', ’212’, ’1212’]</code>
:<code>FindInText('a*(?<bcd>b+(c+)(d*))','zyabdaabbcccfd', re:1, subpattern:['bcd', 0, 1, 2, 3]) → [8, 6, 8, 10, 13]</code>

The «return» parameter alters what is returned, according to what letter you provide as the parameter:

* ‘P’ (or ‘Position’): The position of the matching text or subpattern (default)
* ‘L’ (or ‘Length’): The length of the matching text or subpattern.
* 'S’ (or ‘Subpattern’): The text matched the regular expression or subpattern.
* ‘#’ (or ‘#Subpatterns’): The number of subpatterns in the regular expression.

==TextTrim(t, ''leftOnly, rightOnly, trimChars'')==
Removes leading and trailing spaces from the text «t».
:<code>TextTrim(' Hello World ') → 'Hello World'</code>

Set optional parameter «leftOnly» to True to remove only preceding spaces, or set «rightOnly» to True to remove only followingspaces:
:<code>TextTrim(' Hello World ', leftOnly: True) → 'Hello World'</code>
:<code>TextTrim(' Hello World ', rightOnly: True) → ' Hello World'</code>

To remove characters other than spaces, specify those characters in a text for the optional «trimChars» parameter:
:<code>TextTrim(' [One, Two, Three] ', trimChars: ' []') → 'One, Two, Three'</code>

==TextReplace(text, pattern, substr, ''all, caseInsensitive, re'')==
Returns text with the first occurrence of «pattern» replaced by «substr».

<code>TextReplace('StringReplace, StringLength', 'String', 'Text') → 'TextReplace, StringLength'</code>

If «all» is <code>True</code>, it returns «text» with ''all'' occurrences of text «pattern» replaced by «subst».
:<code>TextReplace('StringReplace, StringLength', 'String', 'Text', All: True) → 'TextReplace, TextLength'</code>
Matches are case-sensitive unless «caseInsensitive» is <code>True</code>.

==== Re (Regular expression) ====
When the optional «re» parameter is <code>True</code>, it treats «pattern» as a [[regular expression]]. In this mode, it replaces the character sequence <code>\0</code> in «subst» by the matching text, and it replaces <code>\1, \2, ..., \9</code> by the subtext matched by the corresponding numbered subpattern in the regular expression. The character sequence <code>''<name>''</code> in «subst» is replaced by the subtext matched to the indicated named subpattern.

:<code>TextReplace('Hello world', '\w+', '«\0»', all:True, re: True) → '«Hello» «world»'</code>
:<code>TextReplace('Hello world', '(.{1, 7}).*', '\1…', re: True) → 'Hello w…'</code>
:<code>TextReplace(text: 'swap first and last', pattern: '(?<first>\w+)(?<mid>.*)(?<last>\b\w+)', subst:'<last><mid><first>', re: True) → 'last first and swap’</code>
:<code>TextReplace('swap first and last', '(\w)(\w*)(\w)', '\3\2\1', re: 1, all: 1 ) → 'pwas tirsf dna tasl'</code>

==Joining Text: a & b==
The [[Text_Concatenation_Operator%3A_%26|&]] operator joins (concatenates) two text values to form a single text value, for example:

:<code>'What is the' & ' number' & '?' → 'What is the number?'</code>

If one or both operands are numbers, it converts them to text using the number format of the variable whose definition contains this function call (or the default suffix format if none is set), for example:

:<code>'The number is ' & 10^8 → 'The number is 100M'</code>

This is also useful for converting (or “coercing”) numbers to text.

==JoinText(a, i, ''separator, finalSeparator, default, textForNull'')==
Returns the elements of array «a» joined together into a single text value over index «i». If elements of «a» are numeric, [[JoinText]]() first converts them to text using the number format settings for the variable whose definition contains this function call. For example:

:<code>I := ['A', 'B', 'C']</code>
:<code>JoinText(I, I) → 'ABC'</code>
:<code>A := Array(I, ['VW', 'Honda', 'BMW'])</code>
:<code>B := Array(I, ['VW', Null, 'BMW'])</code>
:<code>JoinText(A, I) → 'VWHondaBMW'</code>

If the optional parameter «separator» is specified, it is inserted as a separator between successive elements, for example:

:<code>JoinText(A, I, ', ') → 'VW, Honda, BMW'</code>

The optional parameter «finalSeparator», if present, specifies a different separator between the second-to-last and last elements of «a».

:<code>JoinText(A, I, '; ', '; and') → 'VW; Honda; and BMW'</code>

Null values in «a» are ignored unless the optional parameter «textForNull» is specified.

:<code>JoinText(B, I, ', ') → 'one, two'</code>
:<code>JoinText(B, I, ', ', textForNull: '') → 'one, , two'</code>
:<code>JoinText(B, I, ', ' , textForNull: 'NULL') → 'one, NULL, two'</code>

The optional «default» parameter is returned when all values are ignored, or «a» has a zero length.

:<code>JoinText([Null, Null, Null], default: Null) → «null»</code>

==SplitText(text, separator, ''caseInsensitive, re'')==
Returns a list of text values formed by splitting the elements of text value text at each occurrence of separator «separator». For example:

:<code>SplitText('VW, Honda, BMW', ', ') → ['VW', 'Honda', 'BMW']</code>

[[SplitText]]() is the inverse of [[JoinText]](), if you use the same separators. For example:

:<code>Var x := SplitText('Humpty Dumpty sat on a wall.', ' ') → ['Humpty', 'Dumpty', 'sat', 'on', 'a', 'wall.']</code>
:<code>JoinText(x, , ' ') → 'Humpty Dumpty sat on a wall.'</code>

When «separator» contains letters, setting «caseInsensitive» to <code>True</code> matches in a lower/uppercase-insensitive manner. When the «re» parameter is <code>True</code>, separator is interpreted as a Perl-compatible [[regular expression]].

:<code>Variable s := 'Yes, Virginia. There is a Santa Claus!'</code>
:<code>SplitText(s, '[\s, \.!]+', re: 1) → ['Yes', 'Virginia', 'There', 'is', 'a', 'Santa', 'Claus', '']</code>
:<code>SplitText(TextTrim(s, trimChars: ' , .!'), '[\s, \.!]+', re:1) → ['Yes', 'Virginia', 'There', 'is', 'a', 'Santa', 'Claus']</code>

<tip title="Tip> With [[SplitText]](), «text» must be a single text value, not an array. Otherwise, it might generate an array of arrays of different length. See [[Ensuring Array Abstraction|Functions expecting atomic parameters]] on what to do if you want apply it to an array.
</Tip>

==TextLowerCase(t)==
[[TextLowerCase]]() returns the text «t» with all letters as lowercase. For example:

:<code>TextLowerCase('What does XML mean?') → 'what does xml mean?'</code>

==TextUpperCase(t)==
[[TextUpperCase]]() returns the text «t» with all letters as uppercase. For example:

:<code>TextUpperCase('What does XML mean?') → 'WHAT DOES XML MEAN?'</code>

==TextSentenceCase(Text, ''preserveUC'')==
[[TextSentenceCase]]() returns the text «t» with the first character (if a letter) as uppercase, and any other letters as lowercase. For example:

:<code>TextSentenceCase('mary ann FRED Maylene') → 'Mary ann fred maylene'</code>
:<code>TextSentenceCase(SplitText('mary ann FRED Maylene', ' ')) → ['Mary', 'Ann', 'Fred', 'Maylene']</code>
:<code>TextSentenceCase('they are Fred and Maylene', true) → 'They are Fred and Maylene'</code>

==NumberToText(x, format)==

NumberToText() converts number «x» to text using the specified «format». It provides all the settings and options available in the [[Number formats]] dialog for displaying a number (including a date number).

Possible values for «format» are: <code>'Suffix', 'Exponential', 'Fixed Point', 'Integer', 'Percent', 'Date', 'Boolean'</code>, or <code>'Hexadecimal'</code>. You can just use the first letter of a format to keep it brief:

:<code>NumberToText(3.45M, ['S', 'E', 'F', 'I', 'H']) → ['3.45M', '3.45.e+006', '3450000', '3450000', '0x34a490']</code>
:<code>NumberToText(0.0012, ['S', 'E', 'F', 'P']) → ['1.2m', '1.2e-003', '0', 0.12%']</code>

NumberToText() offers these optional parameters:

*«digits» specifies the precision for Suffix and Exponential formats, and the digits to the right of the decimal for Fixed Point and Percent formats, for example:

:<code>NumberToText(Pi, 'Suffix', digits: 5) → '3.1416'</code>
:<code>NumberToText(Pi, 'Fixed Point', digits: 5) → '3.14159'</code>
:<code>NumberToText(Pi, 'Percent', digits: 5) → '314.15927%'</code>

* «showZeros» forces the inclusion of trailing zeros:

:<code>NumberToText(1/4, 'Percent', digits: 2, showZeros: True) → '25.00%'</code>

Set «thousandsSeparators» to <code>True</code> to separate digits into groups of three:

:<code>NumberToText(7^12,'I', thousandsSeparators: True) → '13,841, 287, 201'</code>

* «currency» specifies a template with the currency symbol and its placement relative to the number and the minus sign.

:<code>NumberToText(-372, 'F', currency: ['-£#', 'US$-#', '#£-', '($#)']) → ['-£372', 'US$-372', '372£-', '($372)']</code>

* «dateFormat» provides a date format template for converting [[date numbers]] to text:

:<code>NumberToText(Today(), dateFormat: 'yyyy MMMM dd (wwww)') → '2013 July 01 (Monday)'</code>

* «fullPrecision»: Set this to true, to include all digits to ensure that the full precision of the number.

:<code>NumberToText(Pi, fullPrecision: True) → '3.141592653589793'</code>

== ParseNumber(text, ''badVal'') ==

Parses a text value into a number. (For dates, use [[ParseDate]]()). The result is independent of the number format setting. Values that are already numeric are returned. If the number is unparseable, it returns <code>Null</code>, unless you specify a different value to the optional parameter «badVal».

:<code>ParseNumber('12.43K') → 12.43K</code>
:<code>ParseNumber('hello') → «null»</code>
:<code>ParseNumber(14.3) → 14.3</code>

If you use <code>ParseNumber(x, x)</code> it will simply return any unparseable text values in «x» as the original text value:

:<code>VAR x := ['3, 214', 14, 'foo'] DO ParseNumber(x, x) → [ 3214, 14, 'foo']</code>

==See Also==
<div style="column-count:2;-moz-column-count:2;-webkit-column-count:2">
* [[Regular Expressions]]
* [[Asc]]()
* [[Chr]]()
* [[TextLength]]()
* [[SelectText]]()
* [[ FindInText]]()
* [[TextTrim]]()
* [[TextReplace]]()
* [[Text Concatenation Operator: &]]
* [[JoinText]]()
* [[SplitText]]()
* [[TextLowerCase]]()
* [[TextUpperCase]]()
* [[TextSentenceCase]]()
* [[NumberToText]]()
* [[Numbers and text]]
* [[Converting Numbers to Text]]
* [[ParseNumber]]()
* [[Model File Character Encoding]]
* [[Read and write text files]]
* [[Files and Editing]]
* [[Multiple formats in one table]]

</div>

<footer>Text, Date, Math, and Financial Functions / {{PAGENAME}} / Date functions</footer>

Number formats

2016-08-23T00:01:04Z

Bbecane:

[[Category: Analytica User Guide]]
[[Category: Windows and dialogs]]
[[Category:Number formats]]
<breadcrumbs>Analytica User Guide > Number and table formats > {{PAGENAME}}</breadcrumbs>

==Setting the number format==
The '''Number format '''dialog lets you set the format of numbers and dates displayed in tables, graphs, and input or output fields. You can select options like the number of decimal digits, currency signs, and commas to separate thousands. The default number format is '''''suffix''''', which uses a letter after the number to denote order of magnitude -- for example, 10K means 10,000, where ''K ''means Kilo or thousands.

Number format sets the format of a variable wherever it appears — in an [[Table|edit table]], [[Table view of a result|result table]], [[Graph view of a result|graph]], or field of a [[User input nodes and user output nodes|user input, or output]]. The number format of an [[Arrays and Indexes|index]] applies wherever that index is used, including row or column headers of a table, or graph axis that uses that index.

You can enter a number into an [[Expression Assist|expression]] or table in any format, no matter what output format it uses.

To set the number format for a variable:

# Select a variable to format by showing its edit table, result table, or graph, or by selecting its node in a diagram. You can apply the same format to several variables if you select their nodes together in a diagram.
# Select '''Number format '''from the [[Result menu]], or press ''Control+b'', to show this dialog:<br>
:[[File:Chapter7_1.png]]
<ol start="3">
<li> Select the format type you want from the list on the left.
<li> Select options you want, such as '''''Decimal digits''''', '''''Show trailing zeroes''''', '''''Thousands separators''''', or '''''Show currency symbol''''', from the menus and checkboxes. The options available depend on which format you selected.
<li> View the example at the top of the dialog to see if the format is what you want.
<li> If so, click the '''Apply '''button.
</ol>

You can change the default number format by pressing '''Set Default'''. The default format applies to all variables in your model whose number format has not been explicitly set.

'''Format types''': Choose one of these number formats:
:{| class="wikitable"
!Format
!Description
!Example
|-
! Suffix
|A letter after the number specifies power of ten
|12.35K
|-
! Exponential
|Scientific notation, where the number after 'e' gives
the powers of ten
|1.2345e04
|-
! Fixed Point
|Number with a fixed number of digits after the decimal point
|12345.68
|-
! Integer
|A whole number with no decimals shown
|12346
|-
! Date
|Show number (days since 1 Jan 1900) as a date and/or time
(see below for format options)
|12 Jan 2007
|-
! Boolean
|Display 0 as '''<code>False</code>''', and any other number as '''<code>True</code>'''
|True, False
|}

==== Suffix number format ====
Suffix is Analytica’s default number format. It uses a conventional letter after each number to specify powers of 10: 12K means 12,000 ('''''K''' ''for kilo or thousands), 2.5M means 2,500,000 ('''''M''' ''for Mega or millions), 5n means 0.000,000,005 ('''''n''' ''means nano or billionths). Here are the suffix characters:
:{| class="wikitable"
!Power of 10
!Suffix
!Prefix
| rowspan="7" |
!Power of 10
!Suffix
!Prefix
|-
|
|
|
!10<sup>-2</sup>
|%
|percent
|-
!10<sup>3</sup>
|K
|Kilo
!10<sup>-3</sup>
|m
|milli
|-
!10<sup>6</sup>
|M
|Mega or Million
!10<sup>-6</sup>
|μ or u
|micro (mu)
|-
!10<sup>9</sup>
|G or B
|Giga or Billion
!10<sup>-9</sup>
|n
|nano
|-
!10<sup>12</sup>
|T
|Tera or Trillion
!10<sup>-12</sup>
|p
|pico
|-
!10<sup>15</sup>
|Q
|Quadrillion
!10<sup>-15</sup>
|f
|femto
|}

<tip title="Tip">Note the difference between “M” for Mega or Million and “m” for milli (1/1000). This is the only situation in which Analytica cares about the difference between uppercase and lowercase. Otherwise, it is insensitive to case (except when matching text values).</tip>

<tip title="Tip">In suffix format, it displays four-digit numbers without the “K” suffix — e.g., 2010, not 2.010K — which works better for years. For suffix, integer, or fixed point formats, it uses exponent format for numbers too large or small — e.g., numbers larger than 109 in integer or fixed point format, or larger than 1018 in suffix format.</tip>

'''Maximum precision''': The maximum number of digits including decimal digits is 15 (14 for fixed point and percent). The maximum precision is 15 digits (9 for integers).

==Number format options ==
'''Decimal digits''': The number of digits to show after the decimal point.

'''Show trailing zeroes''': Check to show trailing zeroes in decimals, e.g., 2.100 instead of 2.1, when decimal digits are set to 3.

'''Thousands separators''': Check to show commas between every third digit of the integer part, e.g., 12,345.678, instead of 12345.678.

'''Show currency symbol''': Check to show a currency symbol. Select the symbol and placement from these menus.

[[File:Chapter7_4.png]]

Placement controls the relative location of the currency symbol, e.g., '''$200 '''or '''200DM''', and whether to use a minus sign '''-$200 '''or parentheses '''($200) '''to indicate a negative number.

'''Regional settings''': If you select the last entry, '''regional''', from the '''Symbol '''or '''Placement '''menu, it uses, respectively, the regional currency or placement settings set for your computer. You can modify these settings in the '''Regional and Language '''options available from the Windows Control Panel.

==See Also==
<div style="column-count:2;-moz-column-count:2;-webkit-column-count:2">
* [[Number Format Dialog]]
* [[NumberFormat]] attribute
* [[Numbers]]
* [[Data_Type_Functions#Function_IsNumber|IsNumber]]
* [[NaN|Not a Number]]
* [[Complex Numbers]]
* [[Binary and hexadecimal integer formats]]
* [[ReadBinaryFile]]
* [[WriteBinaryFile]]
* [[BitAnd]]
* [[NumberToText]]
* [[Numbers and text]]
* [[ParseNumber]]
* [[Result menu]]
</div>

<footer>Number and table formats / {{PAGENAME}} / Date formats</footer>

Multiple formats in one table

2016-08-23T00:00:01Z

Bbecane:

[[Category:Analytica User Guide]]
<breadcrumbs>Analytica User Guide > Number and table formats> {{PAGENAME}}</breadcrumbs>

Usually, the same [[Number formats|number format]] applies to all numbers in a table (except its index values in column or row headers, which use the format set for the index variable). Sometimes, you might want to use different formats for different rows (more generally, [[slice]]s) of a table. You can do this if you define the table as a list of variables, for example:

:<code>Index Years := 2007..2012</code>
:<code>Variable DollarX := Table(Years)(...) { Formatted as dollars }</code>
:<code>Variable PercentX := DollarX/40K { Formatted as percent }</code>
:<code>Variable MultiformatX := [DollarX, PercentX]</code>
:<code>MultiformatX →</code>

:[[File:Chapter7_8.png]]

This table uses the number format set for each variable responsible for a row here — as long as you don’t override their settings by setting a format for <code>MultiformatX</code>.

==See Also==
* [[Number formats]]
* [[Creating Arrays (Tables)]]
* [[Tutorial: Arrays]]
* [[Table]]
* [[Slice]]
* [[Numbers and text]]
* [[Datatype functions]]

<footer>Display of constraint results / {{PAGENAME}} / Graphs</footer>

Numbers and text

2016-08-22T23:58:14Z

Bbecane:

[[Category:Analytica User Guide]]
<breadcrumbs>Analytica User Guide > Expressions > {{PAGENAME}}</breadcrumbs>

'''Converting number to text''': If you apply the [[Text_Concatenation_Operator%3A_%26|&]] operator or [[JoinText]]() to numbers, they convert the numbers to text values, using the number format specified for the variable or function in whose definition they appear. You can use this effect to convert (“coerce”) numbers into text values, for example:
:<code>123456789 & '' → '123.5M'</code>
:<code>123456789 & '' → '$123,456,789.00'</code>
:<code>'The date is: ' & 38345 → The date is: Thursday, December 25, 2008'</code>

<tip title="Tip">The actual result depends on ''Number Format ''setting for the variable or function in whose definition the expression appears. The first example assumes the default ''Suffix ''format. The second assumes ''Fixed Point ''format, with currency and thousands separators checked, and two decimal digits. The third assumes the ''Long Date ''format. Use the [[Number format]] dialog on the [[Result menu]] to set the formats.</tip>

You can also control the format used when converting numbers to text with the [[Text functions|NumberToText]] function.

'''Converting text to number''': You can use the [[Evaluate]] function to convert a text representation of a number into an actual number, for example:
:<code>Evaluate('12350') → 12.35K</code>

Evaluate() can convert any number format that Analytica can handle in an expression— and no others. Thus, it can handle decimals, exponent format, dates, <code>True</code> or <code>False</code>, a <code>$</code> at the start of a number (which it ignores), and letter suffixes, like <code>K</code> and <code>M</code>.

An alternative method, for converting text to a number is to use the <code>Coerce Number</code> qualifier on a user-defined function. For example, you could define a user-defined function such as:
:<code>ParseNum(X: Coerce Number) := X</code>

==See Also==
* [[Converting Numbers to Text]]
* [[NumberToText]]
* [[Numbers]]
* [[IsNumber]]
* [[IsText]]
* [[Math functions]]
* [[Text functions]]
* [[Read and write text files]]
* [[Multiple formats in one table]]

<footer>Math functions / {{PAGENAME}} / INF, NAN, and NULL - Exception values</footer>

Datatype functions

2016-08-22T23:55:48Z

Bbecane:

[[Category:Analytica User Guide]]
[[Category: Data Type Functions]]
<breadcrumbs>Analytica User Guide > Expressions > {{PAGENAME}}</breadcrumbs>

A value can be a number, text, [[Null]], or a reference. Integers, reals, Boolean, and date values, are all represented as numbers. You can use these functions from the [[Special_Functions_library|Special]] library of [[Definition menu]] to determine the type.

'''IsNumber(x)''': Returns <code>True</code> if «x» is a number, including a boolean, date, [[INF]], [[NaN]], or complex. See also [[IsNumber]]().
:<code>IsNumber(0) → True </code>
:<code>IsNumber(False) → True </code>
:<code>IsNumber(INF) → True </code>
:<code>IsNumber('hi') → False </code>
:<code>IsNumber(5) → True </code>
:<code>IsNumber('5') → False </code>
:<code>IsNumber(NAN) → True</code>

'''IsText(x)''': Returns <code>True</code> if «x» is a text value. See also [[IsText]]().
:<code>IsText('hello') → True </code>
:<code>IsText(7) → False</code>
:<code>IsText('7') → True</code>

'''IsNaN(x)''': Returns <code>True</code> if «x» is “not a number,” i.e., [[NaN]]. [[INF]] or regular numbers do not qualify, nor does a text or [[Null]]. See also [[IsNaN]]().
:<code>0/0 → NAN</code>
:<code>IsNaN(0/0) → True </code>
:<code>IsNaN(5) → False </code>
:<code>IsNaN(INF) → False </code>
:<code>IsNaN('Hello') → False</code>

'''IsNull(x)''': To test if «x» is exactly [[Null]]. Returns false if «x» is an array. See also [[IsNull]]().

'''x <nowiki>=</nowiki> NULL''': To test if an atomic «x» is [[Null]]. When «x» is an array, returns <code>True</code> or <code>False</code> for each element of the array.

'''IsUndef(x)''': Returns <code>True</code> if atomic «x» is [[Null]] or the internal value [[Undefined]] (usually indicating uncomputed). When «x» is an array, returns <code>True</code> or <code>False</code> for each element of the array. See also [[IsUndef]]().

'''IsRealNumber(x)''': Returns <code>True</code> when «x» is a real number, including a boolean, date or [[INF]]. Returns <code>False</code> when «x» is a complex number or [[NaN]]. See also [[IsRealNumber]]().

'''IsReference(x)''': Returns <code>True</code> if «x» is a reference to a value. See also [[IsReference]]().

'''IsHandle(x)''': Returns <code>True</code> if «x» is a handle to an Analytica object. See also [[IsHandle]](x).

'''TypeOf(x)''': Returns the type of expression «x» as a text value, usually one of <code>Number, Text, Reference</code>, or [[Null]]. [[INF]] and [[NaN]] are both of type <code>"Number"</code>. See also [[TypeOf]]().
:<code>TypeOf(2008) → "Number" </code>
:<code>TypeOf('2008') → "Text" </code>
:<code>TypeOf(INF) → "Number" </code>
:<code>TypeOf(0/0) → "Number"</code>

==See Also==
<div style="column-count:2;-moz-column-count:2;-webkit-column-count:2">
* [[Data Type Functions]]
* [[TypeOf]]
* [[IsNumber]]
* [[IsRealNumber]]
* [[IsNaN]]
* [[IsText]]
* [[IsReference]]
* [[IsHandle]]
* [[IsNull]]
* [[IsUndef]]
* [[Special Functions library]]
* [[Function_parameter_qualifiers#Data_type_qualifiers| Data types of function parameters]]
* [[Multiple formats in one table]]
</div>

<footer>Warnings / {{PAGENAME}} / Text, Date, Math, and Financial Functions</footer>

Multiple formats in one table

2016-08-22T23:55:10Z

Bbecane:

[[Category:Analytica User Guide]]
<breadcrumbs>Analytica User Guide > Number and table formats> {{PAGENAME}}</breadcrumbs>

Usually, the same [[Number formats|number format]] applies to all numbers in a table (except its index values in column or row headers, which use the format set for the index variable). Sometimes, you might want to use different formats for different rows (more generally, [[slice]]s) of a table. You can do this if you define the table as a list of variables, for example:

:<code>Index Years := 2007..2012</code>
:<code>Variable DollarX := Table(Years)(...) { Formatted as dollars }</code>
:<code>Variable PercentX := DollarX/40K { Formatted as percent }</code>
:<code>Variable MultiformatX := [DollarX, PercentX]</code>
:<code>MultiformatX →</code>

:[[File:Chapter7_8.png]]

This table uses the number format set for each variable responsible for a row here — as long as you don’t override their settings by setting a format for <code>MultiformatX</code>.

==See Also==
* [[Number formats]]
* [[Creating Arrays (Tables)]]
* [[Tutorial: Arrays]]
* [[Table]]
* [[Slice]]
* [[Datatype functions]]

<footer>Display of constraint results / {{PAGENAME}} / Graphs</footer>

Multiple formats in one table

2016-08-22T23:55:00Z

Bbecane: /* See Also */

[[Category:Analytica User Guide]]
<breadcrumbs>Analytica User Guide > Number and table formats> {{PAGENAME}}</breadcrumbs>

Usually, the same [[Number formats|number format]] applies to all numbers in a table (except its index values in column or row headers, which use the format set for the index variable). Sometimes, you might want to use different formats for different rows (more generally, [[slice]]s) of a table. You can do this if you define the table as a list of variables, for example:

:<code>Index Years := 2007..2012</code>
:<code>Variable DollarX := Table(Years)(...) { Formatted as dollars }</code>
:<code>Variable PercentX := DollarX/40K { Formatted as percent }</code>
:<code>Variable MultiformatX := [DollarX, PercentX]</code>
:<code>MultiformatX →</code>

:[[File:Chapter7_8.png]]

This table uses the number format set for each variable responsible for a row here — as long as you don’t override their settings by setting a format for <code>MultiformatX</code>.

==See Also==
* [[Number formats]]
* [[Creating Arrays (Tables)]]
* [[Tutorial: Arrays]]
* [[Table]]
* [[Slice]]
* [[Datatype functions]]

<footer>Display of constraint results / {{PAGENAME}} / Graphs</footer>

Data definitions

2016-08-22T23:54:34Z

Bbecane: Redirected page to Multiple formats in one table

#REDIRECT [[Multiple formats in one table]]

Selecting the Sample Size

2016-08-22T23:43:03Z

Bbecane:

[[Category: Analytica User Guide]]
<breadcrumbs> Analytica User Guide > Expressing Uncertainty > {{PAGENAME}}</breadcrumbs><br />

Each probabilistic value is simulated by computing a random sample of values from the actual probability distribution.

You can control the sampling method (system variable [[SampleType]]) and sample size (system variable [[SampleSize]]) by using [[Uncertainty Setup dialog]]. The sections below discuss how to select a sample size.

==Choosing an Appropriate Sample Size==

There is a clear trade-off for using a larger sample size in calculating an uncertainty variable. When you set the sample size to a large value, the result is less noisy, but it takes a longer time to compute the distribution. For an initial probabilistic calculation, a sample size of 20 to 50 is usually adequate.

How should you choose the sample size «m»? It depends both on the cost of each model run, and what you want the results for. An advantage of the [[Monte Carlo]] method is that you can apply many standard statistical techniques to estimate the precision of estimates of the output distribution. This is because the generated sample of values for each output variable is a random sample from the true probability distribution for that variable.

==Uncertainty about the Mean==

First, suppose you are primarily interested in the precision of the [[mean]] of your output variable «y». Assume you have a random sample of «m» output values generated by [[Monte Carlo]] simulation:

:<math>(y_1, y_2, y_3, …y_m) </math><div class="floatright">(1)</div>

You can estimate the mean and standard deviation of «y» using the following equations:

:<math>\vec y=\sum_{i=1}^m \frac { y_i }m</math><div class="floatright">(2)</div>

:<math>s^2=\sum_{i=1}^m \frac { (y_i - \vec y)^2} {m - 1}</math><div class="floatright">(3)</div>

This leads to the following confidence interval with confidence «α», where «c» is the deviation for the unit normally enclosing probability «α»:

:<math>\left (\vec y-c\frac {s} {\sqrt m}, \vec y + c\frac {s} {\sqrt m}\right ) </math><div class="floatright">(4)</div>

Suppose you wish to obtain an estimate of the mean of «y» with an «α» confidence interval smaller than «w» units wide. What sample size do you need? You need to make sure that:

:<math>w>2c \frac {s}{\sqrt m}</math><div class="floatright">(5)</div>

Or, rearranging the inequality:

:<math>m> \left ( \frac {2cs}{w}\right ) ^2</math><div class="floatright">(6)</div>

To use this, first make a small Monte Carlo run with, say, 10 values to get an initial estimate of the variance of «y» — that is, «s2». You can then use equation (6) to estimate how many samples reduce the confidence interval to the requisite width «w».

For example, suppose you wish to obtain a 95% confidence interval for the mean that is less than 20 units wide. Suppose your initial sample of 10 gives ''s = 40''. The deviation «c» enclosing a probability of 95% for a unit normal is about 2. Substituting these numbers into equation (6), you get:

:<math>m> \left ( \frac {2 \times 2 \times 40}{20} \right )^2 = 8^2 = 64</math><div class="floatright">(7)</div><br />

So, to get the required precision for the mean, you should set the sample size to about 64.

== Estimating Confidence Intervals for Fractiles ==

Another criterion for selecting sample size is the precision of the estimate of the median and other fractiles, or more generally, the precision of the estimated cumulative distribution. Assume that the sample «m» values of «y» are relabeled so that they are in increasing order:

:<math> y_1 \le, y_2 \le, ...y_m</math>

«c» is the deviation enclosing probability «α» of the unit normal. Then the following pair of sample values constitutes the confidence interval:

:<math>(y_i, y_k)</math>

where:

:<math>i = \left \lfloor mp - c \sqrt {mp (1-p)} \right \rfloor</math><div class="floatright">(8)</div><br />

:<math>i = \left \lceil mp - c \sqrt {mp (1-p)} \right \rceil</math><div class="floatright">(9)</div>

<Tip Title="Note"> The brackets in equations (8) and (9) above mean round up [[File:lceil.png]] and round down[[File:rfloor.png]], since they are computing numbers that need to be integers.</Tip>

Suppose you want to achieve sufficient precision such that the «a» confidence interval for the pth fractile «Y<sub>p</sub>» is given by (y<sub>1</sub>, y<sub>2</sub>), where «y<sub>i</sub>» is an estimate of '''<math>{Y_p-{_\Delta}{_p}}</math>''', and «y<sub>k</sub>» is an estimate of '''<math>{Y_p+{_\Delta}{_p}}</math>'''. In other words, you want «<math>\alpha</math>» confidence of «Y<sub>p</sub>» being between the sample values used as estimates of the (<math>p-{_\Delta}{_p})</math>) and (<math>p+{_\Delta}{_p})</math>) fractiles. What sample size do you need? Ignoring the rounding, you have approximately:

:<math>i = m(p-{\Delta}p), k = m(p+{\Delta} p)</math><div class="floatright">(10)</div><br />

Thus:

:<math>k - i = 2m{\Delta}p</math><div class="floatright">(11)</div><br />

From equations (8) and (9) above, you have:

:<math>k - i = 2c\sqrt {mp(1-p)}</math><div class="floatright">(12)</div><br />

Equating the two expressions for ''k - 1'' , you obtain:

:<math>2mp\Delta p = 2c \sqrt {mp(1-p)}</math><div class="floatright">(13)</div><br />

:<math>m=p(1- p) \left (\frac {c}{\Delta p} \right )^2</math><div class="floatright">(14)</div><br />

For example, suppose you want to be 95% confident that the estimated fractile Y<sub>.90</sub> is between the estimated fractiles Y<sub>.85</sub> and Y<sub>.95</sub>. So you have <math>\Delta p</math> = 0.05, and ''c ≈ 2''. Substituting the numbers into equation (14), you get:

:<math>m = 0.90 \times (1 - 0.90) \times \left (\frac {2}{0.05} \right )^2 = 144</math><div class="floatright">(15)</div><br />
On the other hand, suppose you want the credible interval for the least precise estimated percentile (the 50th percentile) to have a 95% confidence interval of plus or minus one estimated percentile. Then:

:<math>m = 0.5 \times (1 - 0.5) \times \left (\frac {2}{0.01} \right )^2 = 10,000</math><div class="floatright">(16)</div><br />

These results are completely independent of the shape of the distribution. If you find this an appropriate way to state your requirements for the precision of the estimated distribution, you can determine the sample size before doing ''any'' runs to see what sort of distribution it might be.

==See Also==
* [[SampleSize]]
* [[SampleType]]
* [[Sample]]
* [[Monte_Carlo_and_probabilistic_simulation#Monte_Carlo_sampling|Monte Carlo sampling]]
* [[Evaluation Modes]]
* [[Uncertainty Setup dialog]]
* [[Distribution Densities Library]]

<footer>Uncertainty views / {{PAGENAME}} / Choosing an appropriate distribution</footer>

SampleSize

2016-08-22T23:41:20Z

Bbecane: /* See Also */

[[Category:System Variables]]

== SysVar SampleSize ==

This system variable contains the current sample size used in [[Monte Carlo]] simulations. You can use this value in expressions. You can equivalently obtain the sample size using <code>Size(Run)</code>.

The sample size is changed using the [[Uncertainty Setup dialog]], which you can get to on the menu from [[Result menu|Result]] → '''Uncertainty Options...'' or by pressing ''Ctrl+U''. Then select '''Analysis option: Uncertainty Sample'''.

== Selecting a Sample Size ==

How do you select the appropriate sample size for your problem?

There is a basic tradeoff when selecting sample size. Larger sample sizes require longer evaluation times and more memory, while smaller sample sizes result in greater sampling error. While perfecting your model's logic, you may want to use a very small sample size, even though the sampling error would be unacceptable, but then when you're ready to compute your final results, up the sample size accordingly.

Most people substantially over-estimate the sample sizes they really need for good results for their specific problem. This is partly because the appearance of [[PDF]] graphs are among the most sensitive to sampling error, and irregular appearance of [[PDF]] graphs often leads people to think they need very large sample sizes. But even with choppy-looking [[PDF]]s, it may be the case that the sampling error for specific [[GetFract|fractile levels]], [[Mean|mean]] and [[SDeviation|standard deviations]] is quite small.

However, if you are require extreme fractile levels, accurate higher-order moments (e.g., [[Skewness]], [[Kurtosis]]), or highly reliable sensitivity/importance estimates, it really may require very large sample sizes to achieve low sampling error.

The best way to figure out the appropriate tradeoffs for your application is by experimentation designed to empirically measure and estimate your sampling error at particular sample sizes. Select a fixed sample size, and then evaluate your key results. Reset (e.g., but changing the sample size to something else, then resetting it back again) and repeat. Do this several times to see how much your results vary from run to run. By observing that variation, you are directly observing the sample error.

The experiment can automated (for each fixed sample size) by introducing an index and allowing array abstraction to repeat the experiment for you. Your uncertain results will all be indexed by this new index, and you can directly view the variation across your results. Doing this, however, requires that you add an «over» parameter to all your calls to distribution functions. For example, if you have:

:<code>Variable X := Normal(a, b)</code>

you'll need to change it to:

:<code>Variable X := Normal(a, b, over: meta_run)</code>

and define your index:

:<code>Index Meta_run := 1..10</code>

Having done this, then you can examine your results of interest and see how these vary over the <code>Meta_run</code> index. This measures the observed sampling error in the fractile levels of interest:

:<code>Variable Est_samp_err := SDeviation(ProbBands(My_result), Meta_run)</code>

If you surgically introduce <code>Meta_run</code> into your model in this fashion, it turns out to be better to define <code>Meta_run</code> as a variable object, rather than as an index. If you do that, then you can easily change its definition to a scalar, e.g.:

:<code>Variable Meta_run := 0</code>

when you aren't performing this meta-analysis of sampling error.

== Theoretical determination of Sample Size ==

In many cases, you can also compute the "theoretical" sample size required with a little algebra. This is detailed in the [[Selecting the Sample Size]] in the [[Analytica User Guide]].

==See Also==
* [[Run]]
* [[Sample]]
* [[SampleType]]
* [[Selecting the Sample Size]]
* [[ProbBands]]
* [[Uncertainty Setup dialog]]
* [[Monte Carlo and probabilistic simulation]]

SampleSize

2016-08-22T23:40:08Z

Bbecane: /* SysVar SampleSize */

[[Category:System Variables]]

== SysVar SampleSize ==

This system variable contains the current sample size used in [[Monte Carlo]] simulations. You can use this value in expressions. You can equivalently obtain the sample size using <code>Size(Run)</code>.

The sample size is changed using the [[Uncertainty Setup dialog]], which you can get to on the menu from [[Result menu|Result]] → '''Uncertainty Options...'' or by pressing ''Ctrl+U''. Then select '''Analysis option: Uncertainty Sample'''.

== Selecting a Sample Size ==

How do you select the appropriate sample size for your problem?

There is a basic tradeoff when selecting sample size. Larger sample sizes require longer evaluation times and more memory, while smaller sample sizes result in greater sampling error. While perfecting your model's logic, you may want to use a very small sample size, even though the sampling error would be unacceptable, but then when you're ready to compute your final results, up the sample size accordingly.

Most people substantially over-estimate the sample sizes they really need for good results for their specific problem. This is partly because the appearance of [[PDF]] graphs are among the most sensitive to sampling error, and irregular appearance of [[PDF]] graphs often leads people to think they need very large sample sizes. But even with choppy-looking [[PDF]]s, it may be the case that the sampling error for specific [[GetFract|fractile levels]], [[Mean|mean]] and [[SDeviation|standard deviations]] is quite small.

However, if you are require extreme fractile levels, accurate higher-order moments (e.g., [[Skewness]], [[Kurtosis]]), or highly reliable sensitivity/importance estimates, it really may require very large sample sizes to achieve low sampling error.

The best way to figure out the appropriate tradeoffs for your application is by experimentation designed to empirically measure and estimate your sampling error at particular sample sizes. Select a fixed sample size, and then evaluate your key results. Reset (e.g., but changing the sample size to something else, then resetting it back again) and repeat. Do this several times to see how much your results vary from run to run. By observing that variation, you are directly observing the sample error.

The experiment can automated (for each fixed sample size) by introducing an index and allowing array abstraction to repeat the experiment for you. Your uncertain results will all be indexed by this new index, and you can directly view the variation across your results. Doing this, however, requires that you add an «over» parameter to all your calls to distribution functions. For example, if you have:

:<code>Variable X := Normal(a, b)</code>

you'll need to change it to:

:<code>Variable X := Normal(a, b, over: meta_run)</code>

and define your index:

:<code>Index Meta_run := 1..10</code>

Having done this, then you can examine your results of interest and see how these vary over the <code>Meta_run</code> index. This measures the observed sampling error in the fractile levels of interest:

:<code>Variable Est_samp_err := SDeviation(ProbBands(My_result), Meta_run)</code>

If you surgically introduce <code>Meta_run</code> into your model in this fashion, it turns out to be better to define <code>Meta_run</code> as a variable object, rather than as an index. If you do that, then you can easily change its definition to a scalar, e.g.:

:<code>Variable Meta_run := 0</code>

when you aren't performing this meta-analysis of sampling error.

== Theoretical determination of Sample Size ==

In many cases, you can also compute the "theoretical" sample size required with a little algebra. This is detailed in the [[Selecting the Sample Size]] in the [[Analytica User Guide]].

==See Also==
* [[Run]]
* [[Sample]]
* [[Selecting the Sample Size]]
* [[ProbBands]]
* [[Uncertainty Setup dialog]]

SampleType

2016-08-22T23:37:53Z

Bbecane: /* See Also */

[[category:System Variables]]

== SysVar SampleType ==

Determines the sampling method used to generate samples from probability distributions. Possible values are:
:<code>0</code>: Median Latin Hypercube
:<code>1</code>: Random Latin Hypercube
:<code>2</code>: Simple Monte Carlo
:<code>3</code>: biased Median Latin Hypercube (legacy)
:<code>4</code>: biased Random latin Hypercube (legacy)
:<code>5</code>: Sobol, limiting polynomial order as appropriate for sample size ([[Analytica 4.6]] or higher)
:<code>6</code>: Sobol, allow use of high order polynomials ([[Analytica 4.6]] or higher)

== Setting the sample type ==

In Analytica, you usually set the [[SampleType]] from the [[Uncertainty Settings]] dialog, by selecting '''More options''' on the '''Uncertainty Sample''' tab.

:[[image:SampleType on UncertaintySetup.png]]

The dialog gives you access to options <code>0</code>, <code>1</code> and <code>2</code> only. To select options <code>3</code> thru <code>6</code>, you need to set the system variable from the [[Typescript Window]].

== Latin Hypercube ==

''Latin hypercube methods'' generate a sample of size ''N'' for a scalar uncertainty by selecting one sample from each <code>[(i - 1)/N, i/N]</code>-fractile interval, ''i = 1..N''.
For example, with a sample size of 5, Latin Hypercube would ensure that one point is in the 0 to 20th percentile range, another point between the 20th to 40th percentiles, one between the 40th to 60th percentiles, one between the 60th to 80th percentiles and in the 80th to 100th percentile range. This helps to ensure that the full range of values gets coverage an avoid random clumping that can occur with pure Monte Carlo. The points within the sample are randomly shuffled for each scalar uncertainty.

''Median Latin Hypercube'' (MLH) selects the median percentile from each percentile range. This ensures maximal spreading of the sample points, but it also means that the set of samples is deterministic -- you'll always get the same points in the sample. The order of the points along the [[Run]] index is random, since the points are shuffled, so the sample itself (taking ordering into account) does indeed have a random component.

''Random Latin Hypercube'' (RLH) selects the point in each percentile range at random.

Latin Hypercube methods ensure spreading of the sample points within each individual scalar dimension, but there is no coordination between separate scalar uncertainties. Hence, in a 2-D sample space, clumping and areas with minimal coverage are still possible. Latin Hypercube methods converge quadratically faster than pure Month Carlo for smooth (analytic) problems involving a single uncertainty. No theoretical guarantees exist when multiple scalar uncertainties are involved, but measurably better convergence is often observed in real-life models with as many as 40 scalar uncertainties (see [http://blog.lumina.com/2014/latin-hypercube-vs-monte-carlo-sampling/ Latin Hypercube vs. Monte Carlo sampling]). With a large number of scalar uncertainties, convergence rates are not substantially better than Monte Carlo.

In non-smooth models, Latin Hypercube methods can on rare occasions produce artifacts that slow convergence to be worse that Monte Carlo. These situations are rare.

== Monte Carlo ==

Pure Monte Carlo samples every point independently. It is a classical method in statistics, for which much is known. It lends itself to proof of many theoretical properties. Sampling error decreases as <math>1/\sqrt{N}</math>, so that to halve the sampling error, you need to quadruple the sample size.

== Biased Latin Hypercube ==

Options <code>3</code> and <code>4</code> exist only to reproduce the same samples returned in Analytica 4.2 and earlier, but should not be used otherwise.

In these earlier versions of Analytica, there was a very small bias in the shuffling algorithm.

== Sobol sequences ==

[[SobolSequence|Sobol sequences]] are a ''quasi-Monte Carlo'' method that attempt to distribute points evenly in the multi-dimensional sample space of multiple scalar uncertainties. These can be seen as a generalization of Latin Hypercube methods, but where Latin Hypercube methods treat each scalar uncertainty separately, Sobol sequences ensure that the points are (eventually) spread evenly within the multidimensional sample space.

Sobol sequences also come with theoretical guarantees that hold even in (analytic) models involving multiple scalar uncertainties. Sampling error converges as

:<math>O( (\log N)^d / N )</math>

where d is the number of scalar uncertainties and «N» is the sample size. As «N» gets immensely large, the denominator dominates the numerator, bringing this close to the holy grail of <math>O(1/N)</math> -- which would be quadratically faster than Monte Carlo. However, when «d» is large, as it usually is, the numerator in this theoretical result is huge, and indeed the improved performance is often not evident until sample sizes approach astronomical sizes.

Many publications claim to have created superior algorithms (to previous sampling methods) by employing Sobol sampling. My own experiments have not shown it to be substantially better than Latin Hypercube, and sometimes notably worse as realistic sample sizes (i.e., sample sizes under 1 million).

There are two Sobol methods provided. Option <code>5</code> is the better of the two. It limits the highest order Sobol polynomial based on sample size. This also limits the number of scalar uncertainties that are "coordinated" before it starts over again with low-order polynomials. Option <code>6</code> does not limit the polynomial order, allowing up to 21,000 scalar Sobol dimensions simultaneously before starting over again with the low-order polynomials. With option <code>6</code> many artifacts occur in which points do not get even spread through the high-dimensional space, and obvious sections of the space go unexplored. These artifacts would disappear with enough sample points -- method <code>5</code> excludes the high-order Sobol polynomials that don't have a sample size large enough to support them, making it work much better.

==See Also==
* [[Monte Carlo and probabilistic simulation]]
* [[Monte_Carlo_and_probabilistic_simulation#Monte_Carlo_sampling|Monte Carlo sampling]]
* [[SampleSize]]
* [[Sample]]
* [[Run]]
* [[System variables]]
* [[SobolSequence]]
* [[Distribution Densities Library]]

SampleType

2016-08-22T23:37:00Z

Bbecane: /* See Also */

[[category:System Variables]]

== SysVar SampleType ==

Determines the sampling method used to generate samples from probability distributions. Possible values are:
:<code>0</code>: Median Latin Hypercube
:<code>1</code>: Random Latin Hypercube
:<code>2</code>: Simple Monte Carlo
:<code>3</code>: biased Median Latin Hypercube (legacy)
:<code>4</code>: biased Random latin Hypercube (legacy)
:<code>5</code>: Sobol, limiting polynomial order as appropriate for sample size ([[Analytica 4.6]] or higher)
:<code>6</code>: Sobol, allow use of high order polynomials ([[Analytica 4.6]] or higher)

== Setting the sample type ==

In Analytica, you usually set the [[SampleType]] from the [[Uncertainty Settings]] dialog, by selecting '''More options''' on the '''Uncertainty Sample''' tab.

:[[image:SampleType on UncertaintySetup.png]]

The dialog gives you access to options <code>0</code>, <code>1</code> and <code>2</code> only. To select options <code>3</code> thru <code>6</code>, you need to set the system variable from the [[Typescript Window]].

== Latin Hypercube ==

''Latin hypercube methods'' generate a sample of size ''N'' for a scalar uncertainty by selecting one sample from each <code>[(i - 1)/N, i/N]</code>-fractile interval, ''i = 1..N''.
For example, with a sample size of 5, Latin Hypercube would ensure that one point is in the 0 to 20th percentile range, another point between the 20th to 40th percentiles, one between the 40th to 60th percentiles, one between the 60th to 80th percentiles and in the 80th to 100th percentile range. This helps to ensure that the full range of values gets coverage an avoid random clumping that can occur with pure Monte Carlo. The points within the sample are randomly shuffled for each scalar uncertainty.

''Median Latin Hypercube'' (MLH) selects the median percentile from each percentile range. This ensures maximal spreading of the sample points, but it also means that the set of samples is deterministic -- you'll always get the same points in the sample. The order of the points along the [[Run]] index is random, since the points are shuffled, so the sample itself (taking ordering into account) does indeed have a random component.

''Random Latin Hypercube'' (RLH) selects the point in each percentile range at random.

Latin Hypercube methods ensure spreading of the sample points within each individual scalar dimension, but there is no coordination between separate scalar uncertainties. Hence, in a 2-D sample space, clumping and areas with minimal coverage are still possible. Latin Hypercube methods converge quadratically faster than pure Month Carlo for smooth (analytic) problems involving a single uncertainty. No theoretical guarantees exist when multiple scalar uncertainties are involved, but measurably better convergence is often observed in real-life models with as many as 40 scalar uncertainties (see [http://blog.lumina.com/2014/latin-hypercube-vs-monte-carlo-sampling/ Latin Hypercube vs. Monte Carlo sampling]). With a large number of scalar uncertainties, convergence rates are not substantially better than Monte Carlo.

In non-smooth models, Latin Hypercube methods can on rare occasions produce artifacts that slow convergence to be worse that Monte Carlo. These situations are rare.

== Monte Carlo ==

Pure Monte Carlo samples every point independently. It is a classical method in statistics, for which much is known. It lends itself to proof of many theoretical properties. Sampling error decreases as <math>1/\sqrt{N}</math>, so that to halve the sampling error, you need to quadruple the sample size.

== Biased Latin Hypercube ==

Options <code>3</code> and <code>4</code> exist only to reproduce the same samples returned in Analytica 4.2 and earlier, but should not be used otherwise.

In these earlier versions of Analytica, there was a very small bias in the shuffling algorithm.

== Sobol sequences ==

[[SobolSequence|Sobol sequences]] are a ''quasi-Monte Carlo'' method that attempt to distribute points evenly in the multi-dimensional sample space of multiple scalar uncertainties. These can be seen as a generalization of Latin Hypercube methods, but where Latin Hypercube methods treat each scalar uncertainty separately, Sobol sequences ensure that the points are (eventually) spread evenly within the multidimensional sample space.

Sobol sequences also come with theoretical guarantees that hold even in (analytic) models involving multiple scalar uncertainties. Sampling error converges as

:<math>O( (\log N)^d / N )</math>

where d is the number of scalar uncertainties and «N» is the sample size. As «N» gets immensely large, the denominator dominates the numerator, bringing this close to the holy grail of <math>O(1/N)</math> -- which would be quadratically faster than Monte Carlo. However, when «d» is large, as it usually is, the numerator in this theoretical result is huge, and indeed the improved performance is often not evident until sample sizes approach astronomical sizes.

Many publications claim to have created superior algorithms (to previous sampling methods) by employing Sobol sampling. My own experiments have not shown it to be substantially better than Latin Hypercube, and sometimes notably worse as realistic sample sizes (i.e., sample sizes under 1 million).

There are two Sobol methods provided. Option <code>5</code> is the better of the two. It limits the highest order Sobol polynomial based on sample size. This also limits the number of scalar uncertainties that are "coordinated" before it starts over again with low-order polynomials. Option <code>6</code> does not limit the polynomial order, allowing up to 21,000 scalar Sobol dimensions simultaneously before starting over again with the low-order polynomials. With option <code>6</code> many artifacts occur in which points do not get even spread through the high-dimensional space, and obvious sections of the space go unexplored. These artifacts would disappear with enough sample points -- method <code>5</code> excludes the high-order Sobol polynomials that don't have a sample size large enough to support them, making it work much better.

==See Also==
* [[Monte_Carlo_and_probabilistic_simulation#Monte_Carlo_sampling|Monte Carlo sampling]]
* [[SampleSize]]
* [[Sample]]
* [[Run]]
* [[System variables]]
* [[SobolSequence]]
* [[Distribution Densities Library]]

Selecting the Sample Size

2016-08-22T23:36:01Z

Bbecane:

[[Category: Analytica User Guide]]
<breadcrumbs> Analytica User Guide > Expressing Uncertainty > {{PAGENAME}}</breadcrumbs><br />

Each probabilistic value is simulated by computing a random sample of values from the actual probability distribution.

You can control the sampling method and sample size by using [[Uncertainty Setup dialog|Uncertainty Setup]]. The sections below discuss how to select a sample size.

==Choosing an Appropriate Sample Size==

There is a clear trade-off for using a larger sample size in calculating an uncertainty variable. When you set the sample size to a large value, the result is less noisy, but it takes a longer time to compute the distribution. For an initial probabilistic calculation, a sample size of 20 to 50 is usually adequate.

How should you choose the sample size «m»? It depends both on the cost of each model run, and what you want the results for. An advantage of the [[Monte Carlo]] method is that you can apply many standard statistical techniques to estimate the precision of estimates of the output distribution. This is because the generated sample of values for each output variable is a random sample from the true probability distribution for that variable.

==Uncertainty about the Mean==

First, suppose you are primarily interested in the precision of the [[mean]] of your output variable «y». Assume you have a random sample of «m» output values generated by [[Monte Carlo]] simulation:

:<math>(y_1, y_2, y_3, …y_m) </math><div class="floatright">(1)</div>

You can estimate the mean and standard deviation of «y» using the following equations:

:<math>\vec y=\sum_{i=1}^m \frac { y_i }m</math><div class="floatright">(2)</div>

:<math>s^2=\sum_{i=1}^m \frac { (y_i - \vec y)^2} {m - 1}</math><div class="floatright">(3)</div>

This leads to the following confidence interval with confidence «α», where «c» is the deviation for the unit normally enclosing probability «α»:

:<math>\left (\vec y-c\frac {s} {\sqrt m}, \vec y + c\frac {s} {\sqrt m}\right ) </math><div class="floatright">(4)</div>

Suppose you wish to obtain an estimate of the mean of «y» with an «α» confidence interval smaller than «w» units wide. What sample size do you need? You need to make sure that:

:<math>w>2c \frac {s}{\sqrt m}</math><div class="floatright">(5)</div>

Or, rearranging the inequality:

:<math>m> \left ( \frac {2cs}{w}\right ) ^2</math><div class="floatright">(6)</div>

To use this, first make a small Monte Carlo run with, say, 10 values to get an initial estimate of the variance of «y» — that is, «s2». You can then use equation (6) to estimate how many samples reduce the confidence interval to the requisite width «w».

For example, suppose you wish to obtain a 95% confidence interval for the mean that is less than 20 units wide. Suppose your initial sample of 10 gives ''s = 40''. The deviation «c» enclosing a probability of 95% for a unit normal is about 2. Substituting these numbers into equation (6), you get:

:<math>m> \left ( \frac {2 \times 2 \times 40}{20} \right )^2 = 8^2 = 64</math><div class="floatright">(7)</div><br />

So, to get the required precision for the mean, you should set the sample size to about 64.

== Estimating Confidence Intervals for Fractiles ==

Another criterion for selecting sample size is the precision of the estimate of the median and other fractiles, or more generally, the precision of the estimated cumulative distribution. Assume that the sample «m» values of «y» are relabeled so that they are in increasing order:

:<math> y_1 \le, y_2 \le, ...y_m</math>

«c» is the deviation enclosing probability «α» of the unit normal. Then the following pair of sample values constitutes the confidence interval:

:<math>(y_i, y_k)</math>

where:

:<math>i = \left \lfloor mp - c \sqrt {mp (1-p)} \right \rfloor</math><div class="floatright">(8)</div><br />

:<math>i = \left \lceil mp - c \sqrt {mp (1-p)} \right \rceil</math><div class="floatright">(9)</div>

<Tip Title="Note"> The brackets in equations (8) and (9) above mean round up [[File:lceil.png]] and round down[[File:rfloor.png]], since they are computing numbers that need to be integers.</Tip>

Suppose you want to achieve sufficient precision such that the «a» confidence interval for the pth fractile «Y<sub>p</sub>» is given by (y<sub>1</sub>, y<sub>2</sub>), where «y<sub>i</sub>» is an estimate of '''<math>{Y_p-{_\Delta}{_p}}</math>''', and «y<sub>k</sub>» is an estimate of '''<math>{Y_p+{_\Delta}{_p}}</math>'''. In other words, you want «<math>\alpha</math>» confidence of «Y<sub>p</sub>» being between the sample values used as estimates of the (<math>p-{_\Delta}{_p})</math>) and (<math>p+{_\Delta}{_p})</math>) fractiles. What sample size do you need? Ignoring the rounding, you have approximately:

:<math>i = m(p-{\Delta}p), k = m(p+{\Delta} p)</math><div class="floatright">(10)</div><br />

Thus:

:<math>k - i = 2m{\Delta}p</math><div class="floatright">(11)</div><br />

From equations (8) and (9) above, you have:

:<math>k - i = 2c\sqrt {mp(1-p)}</math><div class="floatright">(12)</div><br />

Equating the two expressions for ''k - 1'' , you obtain:

:<math>2mp\Delta p = 2c \sqrt {mp(1-p)}</math><div class="floatright">(13)</div><br />

:<math>m=p(1- p) \left (\frac {c}{\Delta p} \right )^2</math><div class="floatright">(14)</div><br />

For example, suppose you want to be 95% confident that the estimated fractile Y<sub>.90</sub> is between the estimated fractiles Y<sub>.85</sub> and Y<sub>.95</sub>. So you have <math>\Delta p</math> = 0.05, and ''c ≈ 2''. Substituting the numbers into equation (14), you get:

:<math>m = 0.90 \times (1 - 0.90) \times \left (\frac {2}{0.05} \right )^2 = 144</math><div class="floatright">(15)</div><br />
On the other hand, suppose you want the credible interval for the least precise estimated percentile (the 50th percentile) to have a 95% confidence interval of plus or minus one estimated percentile. Then:

:<math>m = 0.5 \times (1 - 0.5) \times \left (\frac {2}{0.01} \right )^2 = 10,000</math><div class="floatright">(16)</div><br />

These results are completely independent of the shape of the distribution. If you find this an appropriate way to state your requirements for the precision of the estimated distribution, you can determine the sample size before doing ''any'' runs to see what sort of distribution it might be.

==See Also==
* [[SampleSize]]
* [[SampleType]]
* [[Sample]]
* [[Monte_Carlo_and_probabilistic_simulation#Monte_Carlo_sampling|Monte Carlo sampling]]
* [[Evaluation Modes]]
* [[Uncertainty Setup dialog]]
* [[Distribution Densities Library]]

<footer>Uncertainty views / {{PAGENAME}} / Choosing an appropriate distribution</footer>

Uncertainty Setup dialog

2016-08-22T23:33:16Z

Bbecane:

[[Category:Analytica User Guide]]
[[Category: Windows and dialogs]]
<breadcrumbs>Analytica User Guide > Expressing Uncertainty > {{PAGENAME}}</breadcrumbs>

___TOC___
Use the '''Uncertainty Setup''' dialog to inspect and change options to compute and display uncertain quantities. It contains five tabs/menu options: '''Uncertainty sample''' including sampling method, '''Statistics''', '''Probability bands''', '''Cumulative probability''' and '''Probability density''' views. Each is described below. The Uncertainty sample methods apply to the entire model. You can apply the rest to a single variable or as the default for the entire model. It saves all settings with your model.

To open the '''Uncertainty Setup''' dialog, select '''Uncertainty Options''' from the [[Result menu]] or ''Control+u''. To set values for a specific variable, select the variable before opening the dialog.

You can select each of the five options in the '''Uncertainty Setup''' dialog from the '''Analysis option''' menu.
:[[File:Analysis option.png]]

== Uncertainty sample==

''For pre-[[Analytica 5.0]] releases, please see [[Uncertainty_Setup_dialog/Uncertainty sample/4.6]].''

:[[File:Uncertainty setup.png]]

'''Sample size''': This number specifies how many runs or iterations Analytica performs to estimate probability distributions. Larger sample sizes take more time and memory to compute, and produce smoother distributions and more precise statistics. See [[Selecting the Sample Size]] for guidelines on selecting a sample size. In the [[Analytica Free 101|Free 101]] and [[Editions of Analytica|Professional editions]], the sample size must be between 2 and 32,000. You can access this number in expressions in your models as the system variable ''[[SampleSize]]''.

=== Sampling method ===

The sampling method is used to determine how to generate a random sample of the specified sample size, '''m''', for each uncertain quantity. Analytica offers four options: '''Median Latin hypercube''' (the default), '''Random Latin hypercube''', '''Monte Carlo''', and '''Sobol''' sampling methods. See [[Monte Carlo and probabilistic simulation]] for details.

=== Random seed ===

This value must be a number between 0 and 100,000,000 (10<sup>8</sup>). The series of random numbers starts from this seed value when:

* A model is opened.
* The value in this field is changed.
* You check the Reset once box, and close the Uncertainty Setup dialog by clicking '''Accept''' or '''Set Default'''.

=== Reset once ===

Check the ''Reset once'' box to produce the exact same series of random numbers.

== Statistics option ==

To change the statistics reported when you select '''Statistics''' as the [[uncertainty view of a result]], select the '''Statistics''' option from the '''Analysis option''' popup menu.

:[[File:Statistic option.png]]

==Probability Bands option ==
To change the probability bands displayed when you select '''Probability Bands''' as the uncertainty view for a result, select the '''Probability Bands''' option from the '''Analysis option''' popup menu.

:[[File:Probability band.png]]

== Probability density option ==

To change how probability density is estimated and drawn, select '''Probability Density''' from the '''Analysis option''' popup menu.

:[[File:Probability density.png]]

Analytica estimates the probability density function, like other uncertainty views, from the underlying array of sample values for each uncertain quantity. The probability density is highly susceptible to random sampling variation and noise. Both histogramming and kernel density smoothing techniques are available for estimating the probability density from the sample, but to ultimately reduce noise and variability it may be necessary to increase sample size (for details on selecting the sample size, see [[Selecting the Sample Size]]). The following example graphs compare the two methods on the same uncertain result:

:[[File:Histogram.png]]

'''Histogram''': The histogram estimation methods partition the space of possible continuous values into bins, and then tally how many samples land in each bin. The probability density is then equal to the fraction of the Monte Carlo sample landing in a given bin divided by the bin’s width. The average number of points landing in each bin determines both the smoothness of the resulting function and the resolution of the resulting plot. With more bins, a finer resolution is obtained, but since fewer points land in each bin, the amount of random fluctuation increases resulting in a noisier plot. '''The Samples per PDF step interval''' setting sizes the bin width to match the average number of points per bin.
With larger sample sizes, you can increase the '''Samples per PDF step interval''' to achieve smoother plots, since more samples will land in each bin. A number approximately equal to the square root of sample size tends to work fairly well.

You can also control how the partitioning of the space of values is performed. When '''Equal X axis steps''' is used, the range of values from the smallest to largest sample point is partitioned into equal sized bins. With this method, all bins have the same width, but the number of points falling in each bin varies. When '''Equal weighted probability steps''' is used, the bins are sized so that each bin contains approximately the same fraction of the total probability. With this method, the fraction of the sample in each bin is nearly constant, but the width of each bin varies. When '''Equal sample probability steps''' is used, the bins are partitioned so that the number of sample points in each bin is constant, with the width of each bin again varying. '''Equal weighted probability steps''' and '''Equal sample probability steps''' are exactly equivalent when standard equally-weighted Monte Carlo or Latin Hypercube sampling is being used. They differ when the Sample Weighting system variable assigns different weights to each sample along the Run index, as is sometimes employed with importance sampling, logic sampling for posterior analysis, and rare-event modeling. See [[Importance weights|Importance weighting]].

Probability density plots using the histogram method default to the '''Step''' chart type, which emphasizes the histogram and reveals the bin placements. When desired, this can be changed to the standard line style from the '''Graph Setup''', see [[Graph setup dialog|Chart Type tab]].

'''Smoothing''': The smoothing method estimates probability density using a technique known as Kernel Density Estimation (KDE) or [[Kernel Density Smoothing]]. This technique replaces each Monte Carlo sample with a [[Gaussian]] curve, called a Kernel, and then sums the curve to obtain the final continuous curve. Unlike a histogram, the degree of smoothness and the resolution of the plot are independent. The '''Smoothing factor''' controls the smoothness or amount of detail in the estimated PDF. The more info button next to the '''Smoothing''' radio control jumps to a page on the Analytica Wiki that elaborates in more detail on how kernel density smoothing works.

Due to the randomness of Monte Carlo sampling, estimations of probability density are often quite noisy. The '''Smoothing''' method can often provide smoother and more intuitively appealing plots than '''Histogram''' methods, but the averaging effects inherent in '''smoothing''' can also introduce some minor artifacts. In particular, Smoothing tends to increase the apparent variance in your result slightly, with a greater increase when the '''Smoothing''' factor is greater. This increase in variance is also seen as a decrease in the height of peaks. Sharp cutoffs (such as is the case with a [[Uniform]] distribution, for example) become rounded with a decaying tail past the cutoff point. And when positive-only distributions begin with a very sharp rise, the density estimate may get smoothed into a plot with a tail extending into the negative value territory.

== Cumulative probability option ==
To change how the cumulative probability values are drawn or to change their resolution, select the respective option from the '''Analysis option''' popup menu.

:[[File:Cumulative probability.png]]

Analytica estimates the cumulative distribution function, like other uncertainty views, from the underlying array of sample values for each uncertain quantity. As with any simulation-based method, each estimated distribution has some noise and variability from one evaluation to the next. Cumulative probability estimates are less susceptible to noise than, for example, probability density estimates.

The '''Samples per CDF plot''' '''point''' setting controls the average number of sample values used to estimate each point on the cumulative distribution function ([[CDF]]) curve, which ultimately controls the number of points plotted on your result.

The '''Equal X axis steps, Equal weighted probability steps''' and '''Equal sample probability steps''' control which points are used in plot of the cumulative probability. '''Equal X axis steps''' spaces points equally along the X axis. '''Equal weighted probability steps''' uses the sample to estimate a set of <code>m+!</code> fractiles (quantiles), <code>Xp</code>, at equal probability intervals, where <code>p=0, q, 2q, ... 1, </code>and<code> q = 1/m</code>. The cumulative probability is plotted at each of the points <code>Xp</code>, increasing in equal steps along the vertical axis. Points are plotted closer together along the horizontal axis in the regions where the density is the greatest. '''Equal sample probability steps''' plots one point each at each nth sample point, where n is the sample per CDF plot point, ignoring the weight on each sample point when they are weighted differently. The cumulative probability up to the nth point is estimated and plotted. Equal weighted probability steps and '''Equal sample probability steps''' are exactly equivalent unless unequal sample weighting is employed (see [[Importance weights]]).

== History ==

The '''Uncertainty Sample''' pane was reworked in [[Analytica 5.0]]. Prior to 5.0, an option for changing the pseudo-random generator method was shown. This was removed (if you really want to use a different random generator algorithm, you can still change this by changing the [[RandomType]] system variable).

The [[Kernel Density Smoothing]] option for probability density estimation was introduced in [[Analytica 4.4]].

== See Also ==
* [[Expressing Uncertainty]]
* [[Tutorial: Open a model to browse#Displaying_alternative_uncertain_views|Tutorial: Displaying alternative uncertain views]]
* [[CDF]]
* [[Gaussian]]
* [[Probability distributions]]
* [[Distribution Densities Library]]
* [[Kernel Density Smoothing]]
* [[Importance weights]]
* [[Selecting the Sample Size]]
* [[SampleSize]]
* [[SampleType]]

<footer>Expressing Uncertainty / {{PAGENAME}} / Uncertainty views</footer>

Uncertainty Setup dialog

2016-08-22T23:30:34Z

Bbecane:

[[Category:Analytica User Guide]]
[[Category: Windows and dialogs]]
<breadcrumbs>Analytica User Guide > Expressing Uncertainty > {{PAGENAME}}</breadcrumbs>

___TOC___
Use the '''Uncertainty Setup''' dialog to inspect and change options to compute and display uncertain quantities. It contains five tabs/menu options: '''Uncertainty sample''' including sampling method, '''Statistics''', '''Probability bands''', '''Cumulative probability''' and '''Probability density''' views. Each is described below. The Uncertainty sample methods apply to the entire model. You can apply the rest to a single variable or as the default for the entire model. It saves all settings with your model.

To open the '''Uncertainty Setup''' dialog, select '''Uncertainty Options''' from the [[Result menu]] or ''Control+u''. To set values for a specific variable, select the variable before opening the dialog.

You can select each of the five options in the '''Uncertainty Setup''' dialog from the '''Analysis option''' menu.
:[[File:Analysis option.png]]

== Uncertainty sample==

''For pre-[[Analytica 5.0]] releases, please see [[Uncertainty_Setup_dialog/Uncertainty sample/4.6]].''

:[[File:Uncertainty setup.png]]

'''Sample size''': This number specifies how many runs or iterations Analytica performs to estimate probability distributions. Larger sample sizes take more time and memory to compute, and produce smoother distributions and more precise statistics. See [[Selecting the Sample Size]] for guidelines on selecting a sample size. In the [[Analytica Free 101|Free 101]] and [[Editions of Analytica|Professional editions]], the sample size must be between 2 and 32,000. You can access this number in expressions in your models as the system variable ''[[SampleSize]]''.

=== Sampling method ===

The sampling method is used to determine how to generate a random sample of the specified sample size, '''m''', for each uncertain quantity. Analytica offers four options: '''Median Latin hypercube''' (the default), '''Random Latin hypercube''', '''Monte Carlo''', and '''Sobol''' sampling methods. See [[Monte Carlo and probabilistic simulation]] for details.

=== Random seed ===

This value must be a number between 0 and 100,000,000 (10<sup>8</sup>). The series of random numbers starts from this seed value when:

* A model is opened.
* The value in this field is changed.
* You check the Reset once box, and close the Uncertainty Setup dialog by clicking '''Accept''' or '''Set Default'''.

=== Reset once ===

Check the ''Reset once'' box to produce the exact same series of random numbers.

== Statistics option ==

To change the statistics reported when you select '''Statistics''' as the [[uncertainty view of a result]], select the '''Statistics''' option from the '''Analysis option''' popup menu.

:[[File:Statistic option.png]]

==Probability Bands option ==
To change the probability bands displayed when you select '''Probability Bands''' as the uncertainty view for a result, select the '''Probability Bands''' option from the '''Analysis option''' popup menu.

:[[File:Probability band.png]]

== Probability density option ==

To change how probability density is estimated and drawn, select '''Probability Density''' from the '''Analysis option''' popup menu.

:[[File:Probability density.png]]

Analytica estimates the probability density function, like other uncertainty views, from the underlying array of sample values for each uncertain quantity. The probability density is highly susceptible to random sampling variation and noise. Both histogramming and kernel density smoothing techniques are available for estimating the probability density from the sample, but to ultimately reduce noise and variability it may be necessary to increase sample size (for details on selecting the sample size, see [[Selecting the Sample Size]]). The following example graphs compare the two methods on the same uncertain result:

:[[File:Histogram.png]]

'''Histogram''': The histogram estimation methods partition the space of possible continuous values into bins, and then tally how many samples land in each bin. The probability density is then equal to the fraction of the Monte Carlo sample landing in a given bin divided by the bin’s width. The average number of points landing in each bin determines both the smoothness of the resulting function and the resolution of the resulting plot. With more bins, a finer resolution is obtained, but since fewer points land in each bin, the amount of random fluctuation increases resulting in a noisier plot. '''The Samples per PDF step interval''' setting sizes the bin width to match the average number of points per bin.
With larger sample sizes, you can increase the '''Samples per PDF step interval''' to achieve smoother plots, since more samples will land in each bin. A number approximately equal to the square root of sample size tends to work fairly well.

You can also control how the partitioning of the space of values is performed. When '''Equal X axis steps''' is used, the range of values from the smallest to largest sample point is partitioned into equal sized bins. With this method, all bins have the same width, but the number of points falling in each bin varies. When '''Equal weighted probability steps''' is used, the bins are sized so that each bin contains approximately the same fraction of the total probability. With this method, the fraction of the sample in each bin is nearly constant, but the width of each bin varies. When '''Equal sample probability steps''' is used, the bins are partitioned so that the number of sample points in each bin is constant, with the width of each bin again varying. '''Equal weighted probability steps''' and '''Equal sample probability steps''' are exactly equivalent when standard equally-weighted Monte Carlo or Latin Hypercube sampling is being used. They differ when the Sample Weighting system variable assigns different weights to each sample along the Run index, as is sometimes employed with importance sampling, logic sampling for posterior analysis, and rare-event modeling. See [[Importance weights|Importance weighting]].

Probability density plots using the histogram method default to the '''Step''' chart type, which emphasizes the histogram and reveals the bin placements. When desired, this can be changed to the standard line style from the '''Graph Setup''', see [[Graph setup dialog|Chart Type tab]].

'''Smoothing''': The smoothing method estimates probability density using a technique known as Kernel Density Estimation (KDE) or [[Kernel Density Smoothing]]. This technique replaces each Monte Carlo sample with a [[Gaussian]] curve, called a Kernel, and then sums the curve to obtain the final continuous curve. Unlike a histogram, the degree of smoothness and the resolution of the plot are independent. The '''Smoothing factor''' controls the smoothness or amount of detail in the estimated PDF. The more info button next to the '''Smoothing''' radio control jumps to a page on the Analytica Wiki that elaborates in more detail on how kernel density smoothing works.

Due to the randomness of Monte Carlo sampling, estimations of probability density are often quite noisy. The '''Smoothing''' method can often provide smoother and more intuitively appealing plots than '''Histogram''' methods, but the averaging effects inherent in '''smoothing''' can also introduce some minor artifacts. In particular, Smoothing tends to increase the apparent variance in your result slightly, with a greater increase when the '''Smoothing''' factor is greater. This increase in variance is also seen as a decrease in the height of peaks. Sharp cutoffs (such as is the case with a [[Uniform]] distribution, for example) become rounded with a decaying tail past the cutoff point. And when positive-only distributions begin with a very sharp rise, the density estimate may get smoothed into a plot with a tail extending into the negative value territory.

== Cumulative probability option ==
To change how the cumulative probability values are drawn or to change their resolution, select the respective option from the '''Analysis option''' popup menu.

:[[File:Cumulative probability.png]]

Analytica estimates the cumulative distribution function, like other uncertainty views, from the underlying array of sample values for each uncertain quantity. As with any simulation-based method, each estimated distribution has some noise and variability from one evaluation to the next. Cumulative probability estimates are less susceptible to noise than, for example, probability density estimates.

The '''Samples per CDF plot''' '''point''' setting controls the average number of sample values used to estimate each point on the cumulative distribution function ([[CDF]]) curve, which ultimately controls the number of points plotted on your result.

The '''Equal X axis steps, Equal weighted probability steps''' and '''Equal sample probability steps''' control which points are used in plot of the cumulative probability. '''Equal X axis steps''' spaces points equally along the X axis. '''Equal weighted probability steps''' uses the sample to estimate a set of <code>m+!</code> fractiles (quantiles), <code>Xp</code>, at equal probability intervals, where <code>p=0, q, 2q, ... 1, </code>and<code> q = 1/m</code>. The cumulative probability is plotted at each of the points <code>Xp</code>, increasing in equal steps along the vertical axis. Points are plotted closer together along the horizontal axis in the regions where the density is the greatest. '''Equal sample probability steps''' plots one point each at each nth sample point, where n is the sample per CDF plot point, ignoring the weight on each sample point when they are weighted differently. The cumulative probability up to the nth point is estimated and plotted. Equal weighted probability steps and '''Equal sample probability steps''' are exactly equivalent unless unequal sample weighting is employed (see [[Importance weights]]).

== History ==

The '''Uncertainty Sample''' pane was reworked in [[Analytica 5.0]]. Prior to 5.0, an option for changing the pseudo-random generator method was shown. This was removed (if you really want to use a different random generator algorithm, you can still change this by changing the [[RandomType]] system variable).

The [[Kernel Density Smoothing]] option for probability density estimation was introduced in [[Analytica 4.4]].

== See Also ==
* [[Expressing Uncertainty]]
* [[Tutorial: Open a model to browse#Displaying_alternative_uncertain_views|Tutorial: Displaying alternative uncertain views]]
* [[CDF]]
* [[Gaussian]]
* [[Probability distributions]]
* [[Distribution Densities Library]]
* [[Kernel Density Smoothing]]
* [[Importance weights]]
* [[Selecting the Sample Size]]
* [[SampleSize]]

<footer>Expressing Uncertainty / {{PAGENAME}} / Uncertainty views</footer>

Dynamic function

2016-08-22T23:25:56Z

Bbecane:

[[Category:Analytica User Guide]]
<breadcrumbs>Analytica User Guide > Dynamic Simulation > {{PAGENAME}}</breadcrumbs>

__TOC__

==Dynamic(initial1, ''initial2..., initialn'', expr)==
Performs dynamic simulation, calculating the value of its defined variable at each element of [[Time]]. The result of [[Dynamic]]() is an array, indexed by [[Time]].

«Initial1», ...«initialn» are the values of the variable for the first ''n'' time periods. «expr» is an expression giving the value of the variable for each subsequent time period. «expr» can refer to the variable in earlier time periods, that is, contain its own identifier in its definition. If variable <code>Var</code> is defined using [[Dynamic]], «expr» can be a function of <code>Var[Time - k]</code> or <code>Self[Time - k]</code>, where ''k'' is an expression that evaluates to an integer between ''1'' and ''t'', and ''t'' is the time step at which «expr» is being evaluated.

<tip title="Tip">
Square brackets ([ ]) are necessary around <code>Time - t</code>.
</Tip>

The [[Dynamic]] function must appear at the topmost level of a definition. It cannot be used inside another expression.

When a dynamic variable refers to itself, it appears in its own list of inputs and outputs, with a symbol for cyclic dependency: [[File:Chapter17_1.5.png]].

'''Library:''' Special

'''When to use:''' Use [[Dynamic]]() for defining variables that are cyclically dependent. There are only two functions in Analytica that allow a cycle to be formed, in which a variable can refer to its own value or to other variables that depend on it. Those two functions are [[Dynamic]]() and [[Iterate]](). Only dynamic variables can compute their value based on the values at at earlier time periods.

'''Example:''' [[Dynamic]]() can be used to calculate the effect of inflation on the price of gasoline in the years 1990 to 1994.

If the initial value is $1.20 per gallon and the rate of inflation is 5% per year, then <code>Gasprice</code> can be defined as: <code>Dynamic(1.2, Gasprice[Time - 1]*1.05)</code> or <code>Dynamic(1.2, Self[Time - 1]*1.05)</code>.

:[[File:Chapter17_2.png]]

Clicking the '''Result''' button and viewing the mid value as a table displays the following results.

:[[File:Chapter17_3.png]]

For 1990, Analytica uses the initial value of <code>Gasprice (1.2)</code>. For each subsequent year, Analytica multiplies the value of <code>Gasprice</code> at <code>[Time - 1]</code> by 1.05 (the 5 percent inflation rate).

==x[Time - k]==
Given a variable <code>x</code> and brackets enclosing [[Time]] minus an integer «k», returns the value for «x», «k» time periods back from the current time period. This function is only valid for variables defined using the [[Dynamic]] function.

'''Library:''' Special

==See Also==
* [[Tutorial: Dynamic system model]]
* [[Dynamic]]
* [[Time]]
* [[Time index]]
* [[Iterate]]

<footer>Time index / {{PAGENAME}} / Time index details</footer>

Time index

2016-08-22T23:24:27Z

Bbecane: /* See Also */

[[Category:Analytica User Guide]]
<breadcrumbs>Analytica User Guide > Dynamic Simulation > {{PAGENAME}}</breadcrumbs>

Dynamic simulation time periods are specified in the system variable [[Time]]. To perform dynamic simulation, you must provide a [[definition]] for '''Time'''.

To edit the definition of [[Time]], select '''Edit Time''' from the [[Definition menu]] to open the [[Object window]] for '''Time'''.

[[Time]] is defined by default as a list of three numbers 0, 1, and 2. You might want to define '''Time''' as a list of years, as in the following example.

:[[File:Chapter17_1.png]]

[[Time]] becomes the index for the array that results from the [[Dynamic]] function.

<tip tilte="Tip"> A model can have only one definition '''Time''' — that is, one set of time periods for Dynamic functions. Any number of variables in the model can be defined using [[Dynamic]]().
</Tip>

<tip title= "Tip">A variation, [[Dynamic]][T](), can be used to represent recurrences over indexes other than '''Time''', but placing the index name in square brackets. This provides a way to express secondary recurrences if you’ve already used your [[Time]] index for sometime else. The dynamic concepts are introduced thoroughly in this chapter using '''Time''', but if you have a loop using a different index, just substitute your other index for [[Time]] in what follows.
</Tip>

==See Also==
* [[Arrays and indexes]]
* [[Time]]
* [[Dynamic]]
* [[Tutorial: Dynamic system model]]
* [[Date and time values]]

<footer>Dynamic Simulation / {{PAGENAME}} / Dynamic function</footer>

Dynamic Simulation

2016-08-22T23:23:56Z

Bbecane:

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

This chapter shows you how to model changes over time. This can be done in Analytica by means of dynamic variables. A dynamic variable is a quantity that changes over time — for example, the effect of inflation on car prices over a ten-year period — with a recurrence or dependence on previous time periods. The term dynamic is used in this chapter to refer to [[Dynamic]] function, an Analytica system function that together with the system variable [[Time]] enables to perform dynamic simulations. We recommend that you read the [[Arrays and Indexes]] chapter, before using these features.

==Sections==
* [[Time index]]
* [[Dynamic function]]
* [[Time index details]]
* [[Dynamic initial values]]
* [[Dynamic using arrays]]
* [[Dynamic dependencies]]
* [[Dynamic and uncertainty]]
* [[Dynamic on non-Time Indexes]]
* [[Reverse Dynamic]]

==See Also==
* [[Tutorial: Dynamic system model]]

<footer>Statistics, Sensitivity, and Uncertainty Analysis / {{PAGENAME}} / Integration with data and applications</footer>

Time

2016-08-22T23:23:25Z

Bbecane: /* See Also */

[[Category:System Variables]]

== SysVar Time ==

[[Time]] is a built-in index available in Analytica. You can get to this variable from the [[Definition menu]] (option '''Show Time''' from browse mode or '''Edit Time''' from [[toolbar|edit mode]]).

The [[Time]] index behaves like any other Analytica index. It can be used as a dimension for arrays and tables, referred to by identifier in expressions, and operated over in array functions. In addition, [[Time]] provides an extra functionality not available to other indexes -- its use with [[Dynamic]].

[[Dynamic|Dynamic models]] compute the value of a variable from the values of itself or other variables at earlier points in [[Time]]. Dynamic loops between variables, creating cycles on the influence diagram, are then possible. This ability to recur over the [[Time]] index is a very powerful feature of Analytica, and is something that is only possible over this special system index, [[Time]].

== See Also ==
* [[Time index]]
* [[Time index details]]
* [[Module 5: Time as an Extrinsic index|Time as an Extrinsic index]]
* [[Defining the Time variable]]
* [[Tutorial: Dynamic system model]]
* [[Dynamic]]
* [[Dynamic Simulation]]
* [[:Category: System Variables]]
* [[IdentPred]]

Dynamic

2016-08-22T23:22:51Z

Bbecane:

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

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

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

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

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

:<code>ident[Time - k]</code>

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

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

You can also make use of [[Subscript]] operations to earlier time points with [[Dynamic]], such as in
:<code> X[Time = Ceil(Time/2)]</code>

or equivalently, <code>Subscript(X, Time, Time/2)</code>. You should beware of the difference between identifying a time point by position and identifying a time point by label (associationally). If the elements of your [[Time]] index are in increments other than ''1'', then <code>X[Time - 1]</code> and <code>X[@Time = @Time - 1]</code> refer to the previous time point, while <code>X[Time = Time - 1]</code> may refer to a time point that doesn't even exist, or to a point other than the immediately previous time point.

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

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

:<code>Dynamic(X, Self[Time - 1] + X)</code>

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

== The Big Dynamic Gotcha ==

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

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

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

Another trick is to place your [[Time]]-operations in a separate variable outside the dynamic loop. For example:

:<code>Variable max_time := Max(Time)</code>

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

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

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

== User-Defined Functions inside Dynamic Loops ==

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

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

When a global variable identifier is evaluated from within a [[User-Defined Functions]], the current dynamic context is dropped if the variable does not belong to the same dynamic loop as the [[UDF]]. In contrast, the dynamic context passed through to the evaluation of the variable if the variable belongs to the same dynamic loop as the [[UDF]]. The following example illustrates.

:<code>Time = 1..10</code>
:<code>Variable V := 100*1.06^(@Time - 1)</code>
:<code>Variable X := Dynamic(1, F(V))</code>
:<code>Variable Y := Dynamic(0, X[Time - 1])</code>
:<code>Function F(z) := Sum(Z + V + Y,Time)</code>

Here <code>V</code> is not part of any dynamic loop, and <code>X → Y → F() → X</code> forms a dynamic loop.

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

== Reverse Dynamic ==

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

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

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

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

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

== Recurrences over non-Time indexes ==

By default, [[Dynamic]] works over the built-in Index, [[Time]]. You can use another index by giving its name in square brackets after [[Dynamic]], e.g.:

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

[[Dynamic]] is optimized for the [[Time]] index, and may run substantially slower over other Indexes. Therefore, it is advisable to use it for indexes (other than time) with to short dimensions, and to use [[Time]] for your primary index for [[Dynamic]].

You can have two (or more) dynamic loops using different indexes that intersect -- i.e. one or more variables is in both loops. The example model [[media:Dynamic on multiple indexes.ana|Dynamic on multiple indexes.ana]] demonstrates using an example in which [[Dynamic]][Item] is used to allocate functions among items, then [[Dynamic]][Time] is used to carry-over unspent funds to the next time period where the allocation re-occurs.

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

== See Also ==
* [[Tutorial: Dynamic system model]]
* [[Dynamic function]]
* [[Dynamic Simulation]]
* [[Dynamic dependencies]]
* [[Iterate]]
* [[WhatIf]]
* [[While]]
* [[Slice Assignment]]
* [[IdentPred]]

User defined functions

2016-08-22T23:18:30Z

Bbecane: Redirected page to User-Defined Functions

#REDIRECT [[User-Defined Functions]]

Standard deviation

2016-08-22T23:11:20Z

Bbecane: Redirected page to SDeviation

#REDIRECT [[SDeviation]]

SDeviation

2016-08-22T23:10:54Z

Bbecane: /* See Also */

[[category:Statistical Functions]]
[[Category:Doc Status C]] 

== SDeviation(X, ''I, w'') ==
Computes the weighted sample standard deviation -- the square root of the [[Variance|variance]].

If ''X'' is an uncertain quantity, dependent on Analytica distribution functions, the variance is obtained using [[SDeviation]](X).

«X» is evaluated in [[Sample]] mode, and the variance along the [[Run]] index computed.

Regardless of the variation used, the standard deviation, or weighted standard deviation, is defined as

:<math>\sqrt(Variance(X,I,w))</math>

See [[Variance]] for additional technical details.

==Optional parameters==
===I===
The optional «I» parameter can be used to calculate standard deviation along Index «I».

Given a data set indexed by «I», the sample variance along «I» is computed using:

:<code>SDeviation(X, I)</code>

When the running index, «I», is the system index [[Run]] (or not specified), the value of «X» is evaluated in [[Sample]] mode and the average value among numeric values computed. If the running index is anything other than [[Run]], then «X» is evaluated in context.

=== W ===

The weighted standard deviation computing by assigning a different "weight" to each point. The weight vector, <code>wt</code>, should be indexed by «I» (or by [[Run]] if «I» is not specified), and the weighted variance is computed using one of these forms

:<code>SDeviation(X, w: wt)</code>
:<code>SDeviation(X, I, w: wt)</code>

When the «w» parameter is not specified, and the running index «I» is either the [[Run]] index or is not specified, then the weighting defaults to the value in the system variable [[SampleWeighting]].

== See Also ==
* [[Statistical_functions#Sdeviation.28x.29|Statistical functions: SDeviation]]
* [[Statistical Functions and Importance Weighting]]
* [[Variance]]
* [[Mean]]
* [[Skewness]]
* [[Kurtosis]]
* [[Statistics]]
* [[media:Data Statistics Library.ana|Data Statistics Library.ana]]
* [[Analytica_Libraries_and_Templates#Data_Statistics|Data Statistics library]]

SDeviation

2016-08-22T23:10:30Z

Bbecane: /* See Also */

[[category:Statistical Functions]]
[[Category:Doc Status C]] 

== SDeviation(X, ''I, w'') ==
Computes the weighted sample standard deviation -- the square root of the [[Variance|variance]].

If ''X'' is an uncertain quantity, dependent on Analytica distribution functions, the variance is obtained using [[SDeviation]](X).

«X» is evaluated in [[Sample]] mode, and the variance along the [[Run]] index computed.

Regardless of the variation used, the standard deviation, or weighted standard deviation, is defined as

:<math>\sqrt(Variance(X,I,w))</math>

See [[Variance]] for additional technical details.

==Optional parameters==
===I===
The optional «I» parameter can be used to calculate standard deviation along Index «I».

Given a data set indexed by «I», the sample variance along «I» is computed using:

:<code>SDeviation(X, I)</code>

When the running index, «I», is the system index [[Run]] (or not specified), the value of «X» is evaluated in [[Sample]] mode and the average value among numeric values computed. If the running index is anything other than [[Run]], then «X» is evaluated in context.

=== W ===

The weighted standard deviation computing by assigning a different "weight" to each point. The weight vector, <code>wt</code>, should be indexed by «I» (or by [[Run]] if «I» is not specified), and the weighted variance is computed using one of these forms

:<code>SDeviation(X, w: wt)</code>
:<code>SDeviation(X, I, w: wt)</code>

When the «w» parameter is not specified, and the running index «I» is either the [[Run]] index or is not specified, then the weighting defaults to the value in the system variable [[SampleWeighting]].

== See Also ==
* [[Variance]]
* [[Statistical_functions#Sdeviation.28x.29|Statistical functions: SDeviation]]
* [[Statistical Functions and Importance Weighting]]
* [[Mean]]
* [[Skewness]]
* [[Kurtosis]]
* [[Statistics]]
* [[media:Data Statistics Library.ana|Data Statistics Library.ana]]
* [[Analytica_Libraries_and_Templates#Data_Statistics|Data Statistics library]]

Data Type Functions

2016-08-22T23:05:59Z

Bbecane: /* See Also */

[[Category:Data Type Functions]]
[[Category:Doc Status C]] 

__TOC__

Analytica provides several functions for checking the data type of atoms (i.e., the items in an array). These are found in the [[Special_Functions_library|Special library]].

== Function IsHandle ==

:'''IsHandle'''(X : Atom)
:'''IsHandle'''(X'', local: true'')

Tests whether the value in «X» is a [[handle]]. When «X» is array-valued, it tests whether each cell of the array contains a handle. The second form with <code>local: true</code> tests whether a local variable «X» contains a [[handle]]. For details, see [[IsHandle]].

== Function IsNaN ==

:'''IsNaN'''(X: Atom)

[[NaN]] is a special value arising from indeterminate arithmetic operations indicating "Not A Number". [[NaN]] can arise from operations such as:
:<code>0/0</code>
:<code>0*INF</code>
:<code>INF - INF</code>
:<code>IgnoreWarnings(Ln(-1))</code>
:<code>IgnoreWarnings(Sqrt(-1))</code>

The last two cases result in [[NaN]] since Analytica does not have internal support for [[Complex Numbers|complex numbers]] (see [[Ln]], [[Sqrt]] and [[IgnoreWarnings]]). The other cases result because the result is indeterminate.

'''IsNaN'''(X) returns 1 (i.e., True) when «X» is the special value [[NaN]], 0 (false) otherwise.

== Function IsNumber ==

:'''IsNumber'''(X: Atom)

Returns True when «X» is a number, or any of the special values [[INF]], -[[INF]], or [[NaN]]. It is also true when «X» is a complex number or a date-time number, since a date-time number is encoded as the number of days elapsed since the time origin. It returns false (zero) for text, even if the characters in the text could be parsed as a number.

== Function IsRealNumber ==

:'''IsRealNumber'''(X: Atom)

Returns True when «X» is a real number or the special values [[INF]] or -[[INF]]. It also returns true when «X» is a date-time number, since a date-time number is considered to be a numeric value -- the number of days elapsed since the date origin. It differs from [[IsNumber]] in that it returns false (zero) for a complex or imaginary number or for the special value [[NaN]].

== Function IsDateTime ==

:'''IsDateTime'''(X: Atom)

Returns True when «X» is a date-time. A date-time is a special time of number in Analytica that encodes the number of days elapsed since the date origin, which is normally ''1-Jan-1904'', or ''30-Dec-1899'' if the "Use Excel Date Origin" preference is set. The fractional part of a date-time number represents a time. When printed, date-time numbers use the Date number format.

'''IsDateTime'''(X) is false for numbers other than those recognized as date-time numbers. It is also false for text values, even if the text itself appears to be a date or time.

== Function IsReference ==

:'''IsReference'''(X)

Returns 1 (True) when «X» is a reference, 0 otherwise. When «X» is a reference, you can use the [[#X operator]].

== Function IsText ==

:'''IsText'''(X: Atom)

Returns 1 (True) when «X» is a textual string, 0 otherwise.

== Comparison to Null ==

The expressions <code>X = Null</code> or <code>X <> Null</code> can be used to test whether «X» is the special system constant [[Null]]. [[Null]] results from certain operations where the value is not found, such as <code>A[I = X]</code> when <code>X</code> is not an element of <code>I</code> (and warnings are ignored).

[[Null]] can also be detected using '''IsUndef'''(X).

== Function IsUndef ==

:'''IsUndef'''(X: Atom)

Returns True if «X» is either of the two special system constants [[Undefined]] or [[Null]]. [[Undefined]] is a special system constant indicating that an attribute does not yet have a value, and also used to indicate that a value is not yet computed (e.g., that the ([[Mid]]) value or [[probValue]] attribute do not yet have a value), or that an optional parameter to a function was not specified. [[Null]] is a value returned by function evaluations indicating that a requested value is out-of-range or does not exist.

The special value [[Null]] was introduced into Analytica 3.0. Prior to that, many functions returned [[Undefined]] when values did not exist, but were changed to return [[Null]]. To handle backward compatibility where the '''IsUndef''' function was being used to test for these values, '''IsUndef''' returns True in both cases.

== Function IsNull ==

:'''IsNull'''(X)

Returns True if «X» is exactly [[Null]]. Returns False when «X» is another than [[Null]]. Does not [[Array Abstraction|array abstract]], so if «X» is an array, even an array containing [[Null]] cells, it still returns atomic False. If you want to compare the cells of an array individually to [[Null]], use <code>x = Null</code>. If you want to test whether an attribute is set, use
:'''IsNull'''(attrib Of obj)

which will return False (0) if the attribute happens to contain an array with [[Null]].

Note that '''IsNull''' is different from the other '''''IsXXXX''''' functions in that it does not [[Array Abstraction|array abstract]].

== Function IsNotSpecified ==
:'''IsNotSpecified'''(X: Atom)

Used within a user-defined function to determine whether an optional parameter has a value. If the optional parameter is not specified in the function call, and if the parameter has no default value, then '''IsNotSpecified''' returns true.

For example:
:<code>Function Fu1(A: Numeric; B: optional numeric)</code>
:<code>Definition:</code>
::<code>if IsNotSpecified(B) Then B := sqrt(A);</code>
::<code>Normal(A*Time, B*sqrt(T))</code>

== Function TypeOf ==

:'''TypeOf'''(X: Atom; Shallow: optional boolean)

Returns the name of the atomic data type of «X» as a textual string. When '''TypeOf''' is applied to an array, the result is an array, where each cell contains the data type of the corresponding item in the original array. When «shallow» is true, a less detailed type description is given. In many cases, '''TypeOf''' exposes details of the internal representation being used; hence, it is preferable to make use of the '''''IsXXX'''''() functions when possible.

{|class="wikitable"
! When <code>X</code> is:
! <code>TypeOf(X)</code> returns:
! <code>TypeOf(X, shallow: true)</code> returns:
|-
| A real number stored internally in IEEE 754 double binary float format || "Number" || "Number"
|-
| An integer value stored internally as a 64-bit signed integer || "Integer" || "Number"
|-
| A real-value stored internally in a fixed-point real number format || "FixedPoint" || "Number"
|-
| A date/time numeric value || "DateTime" || "DateTime"
|-
| A complex (imaginary) number || "ComplexNumber" || "ComplexNumber"
|-
| A textual value || "Text" || "Text"
|-
| [[Null]] || "Null" || "Null"
|-
| A Linear optimization Program (returned by [[DefineOptimization]]) || "LP" || "Custom"
|-
| A Quadratic optimization Program with linear constraints (returned by [[DefineOptimization]]) || "QP" || "Custom"
|-
| A Quadratically Constrained optimization Program (returned by [[DefineOptimization]]) || "QCP" || "Custom"
|-
| A Non-Linear optimization Program (returned by [[DefineOptimization]]) || "NLP" || "Custom"
|-
| An ODBC Record Set object || "RecordSet" || "Custom"
|-
| A parsed expression where the outermost operation is an operator || "Expression" || "Expression"
|-
| A parsed expression where the outermost operation is a function call || "FunctionCall" || "FunctionCall"
|-
| A binary blob of data, e.g., from a Pict attribute || "Data" || "Data"
|-
| A [[Handle]] to an object with the class «className» || "''«className»''", one of:
"Decision"<br>
"Variable"<br>
"Chance"<br>
"Objective"<br>
"Constraint"<br>
"Constant"<br>
"Index"<br>
"Function"<br>
"Determ"<br>
"Module"<br>
"Module"<br>
"Library"<br>
"Form"<br>
"Linkmodule"<br>
"Linklibrary"<br>
"Text"<br>
"Button"<br>
"Picture"<br>
"Formnode"<br>
"Alias"<br>
"Attribute"<br>
"Command"<br>
"Graphstyletemplate"<br>
"Sysfunction"<br>
"Keyword"<br>
| "Object"
|-
| A [[Reference]] || "Reference" || "Reference"
|-
| The data from an input or output attribute || "ObjectSet" || "ObjectSet"
|}

The parameter to '''TypeOf''' is evaluated. So, if you apply this to a function parameter or local variable, the type of the value is returned, even if the parameter is declared as an index or variable type. For example:
:<code>Function F1(A: Variable) := TypeOf(A)</code>

When you call <code>F1(Ch1)</code>, the type of each atom in the value of <code>Ch1</code> is returned -- not the class of <code>Ch1</code>. If you wanted the class of the object, it would be easiest to use:
:<code>Function F2(A: Variable) := class of A</code>

which would return "Chance" when call <code>F2(Ch1)</code>.

==See Also==
* [[IsHandle]]
* [[Undefined]]
* [[Special Functions library]]
* [[Datatype functions]]
* [[Function_parameter_qualifiers#Data_type_qualifiers|Data types of function parameters]]
* [[:Category: Data Type Functions]]
* [[:Category:Domain Access Functions]]

Data Type Functions

2016-08-22T23:04:46Z

Bbecane:

Error Messages/40318

2016-08-22T23:03:43Z

Bbecane: /* See Also */

[[Category: Error messages]]

== Error message examples ==

<pre style="background:white; border:white; margin-left: 1em; font-style:italic">
Error encountered in the parameter declaration for Function CovertToText while checking:
(X: coerce)
In the declaration for parameter X, you must specify a datatype when you use COERCE.
</pre>

== Cause ==

'''Coerce''' <t> is a parameter qualifier in the Parameters attribute of a Function.
It specifies that the function, when called, should try to convert the actual parameter to the specified type <t>.
You omitted any type <t>. The type may be Text, Number, or Reference

{| class="wikitable"
|-
| '''From<br>'''
| '''To'''<br>
| '''Result'''<br>
|-
| Null<br>
| Text<br>
| "Null"<br>
|-
| Number<br>
| Text<br>
| Number as text, using the number format of the variable or function calling the function.<br>
|-
| Text<br>
| Number or Positive<br>
| If possible, interprets it as a date or number, using the number format.<br>
|-
| Null<br>
| Reference<br>
| \Null<br>
|-
| Number<br>
| Reference<br>
| \X<br>
|-
| Text<br>
| Reference<br>
| \Text<br>
|}

See more at [[Function_Parameter_Qualifiers#Parameter_qualifiers|function parameter qualifiers.]]

== Remedies ==

Add the type you want the parameter to be coerced to.

==See Also==
* [[User-Defined Functions]]
* [[Function calls and parameters]]
* [[Function_parameter_qualifiers#Data_type_qualifiers|Data types of function parameters]]
* [[Function Parameter Qualifiers]]
* [[NumberToText]]
* [[Datatype functions]]

Datatype functions

2016-08-22T23:01:42Z

Bbecane:

[[Category:Analytica User Guide]]
[[Category: Data Type Functions]]
<breadcrumbs>Analytica User Guide > Expressions > {{PAGENAME}}</breadcrumbs>

A value can be a number, text, [[Null]], or a reference. Integers, reals, Boolean, and date values, are all represented as numbers. You can use these functions from the [[Special_Functions_library|Special]] library of [[Definition menu]] to determine the type.

'''IsNumber(x)''': Returns <code>True</code> if «x» is a number, including a boolean, date, [[INF]], [[NaN]], or complex. See also [[IsNumber]]().
:<code>IsNumber(0) → True </code>
:<code>IsNumber(False) → True </code>
:<code>IsNumber(INF) → True </code>
:<code>IsNumber('hi') → False </code>
:<code>IsNumber(5) → True </code>
:<code>IsNumber('5') → False </code>
:<code>IsNumber(NAN) → True</code>

'''IsText(x)''': Returns <code>True</code> if «x» is a text value. See also [[IsText]]().
:<code>IsText('hello') → True </code>
:<code>IsText(7) → False</code>
:<code>IsText('7') → True</code>

'''IsNaN(x)''': Returns <code>True</code> if «x» is “not a number,” i.e., [[NaN]]. [[INF]] or regular numbers do not qualify, nor does a text or [[Null]]. See also [[IsNaN]]().
:<code>0/0 → NAN</code>
:<code>IsNaN(0/0) → True </code>
:<code>IsNaN(5) → False </code>
:<code>IsNaN(INF) → False </code>
:<code>IsNaN('Hello') → False</code>

'''IsNull(x)''': To test if «x» is exactly [[Null]]. Returns false if «x» is an array. See also [[IsNull]]().

'''x <nowiki>=</nowiki> NULL''': To test if an atomic «x» is [[Null]]. When «x» is an array, returns <code>True</code> or <code>False</code> for each element of the array.

'''IsUndef(x)''': Returns <code>True</code> if atomic «x» is [[Null]] or the internal value [[Undefined]] (usually indicating uncomputed). When «x» is an array, returns <code>True</code> or <code>False</code> for each element of the array. See also [[IsUndef]]().

'''IsRealNumber(x)''': Returns <code>True</code> when «x» is a real number, including a boolean, date or [[INF]]. Returns <code>False</code> when «x» is a complex number or [[NaN]]. See also [[IsRealNumber]]().

'''IsReference(x)''': Returns <code>True</code> if «x» is a reference to a value. See also [[IsReference]]().

'''IsHandle(x)''': Returns <code>True</code> if «x» is a handle to an Analytica object. See also [[IsHandle]](x).

'''TypeOf(x)''': Returns the type of expression «x» as a text value, usually one of <code>Number, Text, Reference</code>, or [[Null]]. [[INF]] and [[NaN]] are both of type <code>"Number"</code>. See also [[TypeOf]]().
:<code>TypeOf(2008) → "Number" </code>
:<code>TypeOf('2008') → "Text" </code>
:<code>TypeOf(INF) → "Number" </code>
:<code>TypeOf(0/0) → "Number"</code>

==See Also==
* [[Data Type Functions]]
* [[TypeOf]]
* [[IsNumber]]
* [[IsRealNumber]]
* [[IsNaN]]
* [[IsText]]
* [[IsReference]]
* [[IsHandle]]
* [[IsNull]]
* [[IsUndef]]
* [[Special Functions library]]
* [[Function_parameter_qualifiers#Data_type_qualifiers| Data types of function parameters]]

<footer>Warnings / {{PAGENAME}} / Text, Date, Math, and Financial Functions</footer>

Data type

2016-08-22T22:59:22Z

Bbecane: Redirected page to Datatype functions

#REDIRECT [[Datatype functions]]

Compound expression

2016-08-22T22:54:28Z

Bbecane: Redirected page to Begin-End for Grouping Expressions

#REDIRECT [[Begin-End for Grouping Expressions]]