View source for The domain of possible values

[[Category:Analytica User Guide]]
[[Category: Attributes]]
<breadcrumbs>Analytica User Guide > Creating and Editing Definitions > {{PAGENAME}}</breadcrumbs>

== Domain Values==
In addition to specifying a variable’s [[definition]], it is also a good practice, and often advantageous, to also specify the space of possible values allowed for the variable’s result. The '''''Domain attribute '''''is used for this purpose. In fact, it is a good practice to define the space of possible values before you start to specify the definition, since this can help to encourage clear thinking and ensure that you are defining a variable that is clearly and unambiguously defined.

The domain attribute specifies the values allowed for each cell in a variable’s result. When the variable evaluates to an array result, the domain specification applies individually to each cell of the result. The domain does nothing to constrain the permissible dimensionality.

In addition to promoting lucid thinking during the model building process, once specified the domain provides Analytica and its user interface with numerous clues about how variables should be treated, and can be instrumental in detecting modeling errors.

'''Making the Domain visible''': By default, the domain attribute is not shown in the Object Window (except that in Analytica Optimizer, it is always visible for Decision variables). To make it visible for greater convenience, you can turn it on by placing a check next to '''Domain '''in the '''Attributes... '''dialog, found on the '''Object '''menu. You must be in edit mode to make this change.

:[[File:Chapter8_29.png]]

== Domain Types ==
On the domain attribute pulldown, several categories of domain types are presented:

:[[File:Chapter8_30.png]]

These are divided into three groups. Those in the top group are used to specify an implicit set of values, such as all integers above zero. The second group specifying an explicitly enumerated set of discrete values. And the final type, '''Expression''', allows the domain to be specified as a computed expression, which provides complete generality for the most advanced users. Each type has additional subfields for information such as bounds.

'''Automatic''': Automatic signifies that you have not specified the domain explicitly. When the domain is needed, Analytica will use heuristics to automatically infer the likely domain based on the information at hand. For example, when displaying probability distributions, it makes a difference whether a variable is continuous or discrete, since in the former a probability density graph should be displayed, while in the latter a probability distribution should be depicted.

'''Continuous''': Indicates that the variable is real-valued. When Continuous is selected, you may optionally specify the lower and upper bounds:

:[[File:Chapter8 31.png]]

If you elect to specify bounds, you should treat these as hard bounds, meaning the final value should never fall outside the indicated range. If, for example, you have an uncertain variable with a right tail, you would leave the upper bound blank. The bounds are inclusive.

'''Integer''': Indicates that the variable is integer-valued, with optional lower and upper bounds.

'''Grouped Integer''': This option shows up only for decision variables, and only in Analytica Optimizer. Each grouped integer variable belongs to a named group. The optimal value for cells falling within a given group must have a value between 1 and ''N'', where ''N'' is the total number of cells belonging to the same group, and such that all cells belonging to the same group have a different value. This category is used solely for formulating certain types of optimization problems. See the ''Optimizer User Guide''.

'''Boolean''': Indicates that the variable is 0, 1 valued (false, true).

'''Discrete''': Indicates that the variable is discrete (as opposed to continuous), but not captured by the above Integer or Boolean categories, and where the set of discrete values cannot be enumerated explicitly. The discrete type pulldown allows you to designate the values further as being textual, numeric, or more Any (unrestricted).

:[[File:Chapter8 32.png]]

When an input control is set to '''Discrete Text''', quotation characters do not display around the current value, and whatever a user types is taken directly as text. No attempt is made to parse the entry as a number, variable name or expression.

Some uncertain quantities result in discrete numeric (but non-integer) outcomes. When '''Discrete Numbers '''is selected, probability distribution graphs will be displayed, not probability density graphs.

'''Explicit Values''': This option allows you to list the set of possible (allowed) values explicitly. As with discrete, you can indicate whether the values are all numeric or all textual.

'''Copy From Index''': Indicates that the set of allowed values are the set of values found in another index variable. When you select this option, you are asked to select the index. To change the source index, click on the index name.

'''Expression''': (''Advanced'') This view allows you to enter the domain as an Analytica expression, or to view the expression for the currently selected domain option. This provides a high degree of flexibility for advanced scenarios, allowing the domains themselves to be computed, array-valued, and conditional. Expression mode is also required to access certain less common parameters of the above domain types.

There are five special domain functions which are used to specify each of the above domain types in expression view, [[Continuous]](), [[Integer]](), [[GroupedInteger]](), [[Boolean]](), and [[Discrete]](). The simplest domain expressions consist of a single call to one of these functions, e.g.:
:<code>Continuous(lb: 0, ub: 1000)</code>

These functions can be combined in arbitrary ways using Analytica expression syntax to create computed domains. For example:
:<code>If Col = "Id" then Integer(lb: 1) Else Continuous(lb: low, ub: low + range)</code>

An expression can compute a set of discrete values as an unindexed list, or it can wrap them in a call to the [[Discrete]]() function, e.g.:
:<code>Discrete("Accounting", "Engineering", "HR", "Marketing", "Sales")</code>

Each standard domain type considers null values to be acceptable. You can override this and indicate that null is not acceptable by specifying an optional «nullOk» parameter as <code>false</code> in expression view, e.g.:
:<code>Continuous(nullOk: false)</code>

Each of the five functions are described in Domain Functions below.

As a stylistic guideline, domain computations should be designed to be computationally simple. For example, although possible, it is generally not a good idea to employ a complex and time consuming algorithm that produces a highly informed and nearly tight lower bound. Instead, utilize a “hard” bound that is relatively easy to obtain and save the complex algorithms for variable definitions.

== Uses of Domain ==
When the domain is specified, Analytica makes use of the information in numerous ways.

'''Bounds checking''': When the value of a variable is computed, it is compared with the domain, and if the result is not consistent with the domain, an out-of-range warning is displayed. Bounds violation are often effective in detecting modeling mistakes. The '''Check value bounds...against domain bounds '''preference setting disables this feature (see [[Preferences dialog]]).

'''Detecting Logical Errors''': The domain enables Analytica to detect and warn of various inconsistencies in your model that may indicate an error in your modeling logic. Sometimes inconsistencies arise when one part of a model is changed, but you forget to change another part of your model to be consistent. Analytica will display warning messages when these situations are encountered, which can help to cut down on undetected modeling errors. An example is the following. Suppose an expression contains the following sub-expression
:<code>If X = "Yes" Then...</code>

where the <code>domain of X</code> is <code>Boolean</code>, meaning that a value of <code>X</code> will be ''0'' or ''1'', not “Yes” or “No”. Analytica issues a warning (at evaluation time) that reveals this error in logic, which is made possible as a result of specifying the domain.

'''Interpretation of uncertainty''': The computation of probability distributions or cumulative probability distributions requires the underlying sample to be interpreted as being either continuous or discrete. Although Analytica can usually correctly infer this from heuristics that make use of various other clues, an explicit domain provides this information directly.

'''Label ordering in graphs''': In parametric graphs (e.g., XY graphs, histograms of discrete quantities, etc), the ordering for labels on the graph axes is not always obvious. In the absence of guidance from the domain, Analytica will usually use a lexical sort order; however, if you want to control the ordering of possible values, you can do so by using an explicit values domain. The order that possible values are listed is then used as the label ordering on graphs.

'''Search Space in Optimization''': In Analytica Optimizer, the domain of decision variables defines the search space for constrained optimization problems. See the ''Optimizer User Guide''.

'''List of Options for a self-Choice''': A node with a definition of <code>Choice(Self,...)</code> uses the set of possible values listed in the domain as the options that appear on the Choice pulldown.

'''Indexes for a DetermTable or ProbTable''': A [[DetermTable]] specifies a result for every possible value across a set of parent variables. The result of a determTable selects out the values that match the computed value. The domain is used to specify what the set of possible values are for each of these parent selector variables. A [[ProbTable]] behaves like a determtable, with its own domain included as a table index.

'''Validation of user input:''' When a user of a model enters values that are in disallowed by the domain, Analytica can provide the user with immediate feedback that his entry is out of the allowed range. This can be utilized in input controls or edit table cells.

'''Display and parsing of textual values''': The domain influences how values are shown in input fields or cells. Should quotes be displayed around textual values? They will be if the domain indicates that both numeric and textual values are acceptable, but not if the variable is restricted to textual values. What if the user enters text that matches an existing variable name, or text that could be interpreted as a number? Should it be treated as a purely textual entry, or should it be parsed? Again, this is determined by the domain. When the domain is restricted to purely textual values, the entry is treated purely as text.

== Domain Functions ==
(''Advanced'') The functions in this section are used in the Expression view of the Domain attribute to specify the space of possible values for a variable.

It would be highly unconventional to use any of these domain functions from outside of the domain attribute; nevertheless, it is possible to do so. When a domain function is evaluated, the return value is in the form of a parsed expression, consisting of a function call to the indicated function, but with each parameter evaluated and replaced by the literal values. Treating this result as an atomic value, expressions can assemble heterogeneous arrays of domain types that vary across multiple indexes.

'''Continuous(''lb, ub, orZero, nullOk'')''':  Used to specify a continuous domain. The optional «lb» and «ub» parameters specify lower and upper bounds respectively, and the expressions specified for «lb» and «ub» may evaluate to an array when the bounds vary along an index. The «orZero» parameter may be set to true to specify a semi-continuous domain, in which zero is acceptable along with any value consistent with «lb» and «ub». By default, null values are considered acceptable, but when «nullOk» is specified as <code>false</code>, then [[Null]] value will trigger out-of-bounds warnings. See also [[Continuous]]().

'''Integer(''lb, ub, nullOk'')''': Used to specify an integer domain. The optional «lb» and «ub» parameters specify lower and upper bounds respectively. Values equal to the bounds are considered to be within the acceptable range. The «nullOk» parameter can be set to <code>false</code> to reject null values as out-of-range. When not specified, «nullOk» defaults to true. See also [[Integer]]().

'''GroupedInteger(''groupName, .., nullOk'')''': Used to specify a grouped integer domain, in which all cells belonging to the same group are required to have a unique value in the final solution found by optimizer. This option is generally only used from Analytica Optimizer, and only in the context of an integer programming problems. See also [[GroupedInteger]]().

'''Boolean(''nullOk'')''': Indicates a 0-1 valued domain. Any value other than 0, 1 or [[Null]] will trigger an out-of-bounds warning. When the optional «nullOk» parameter is specified as <code>false</code>, then Null will also trigger an out-of-bounds warning. See also [[Boolean]]().

'''Discrete(''x1, x2, x3,..., type, nullOk'')''': This function is used to encode both a '''Discrete Domain '''with unknown values, and the '''Explicit Values '''domain where the values are explicitly listed. For an Explicit Values domain, the values are listed as the parameters to the function, e.g.:
:<code>Discrete(2, 3, 5, 7, 9, 11, 13, 17)</code>

For an implicit discrete domain, no allowed values are listed. Either usage may include the «type» parameter, which must be specifying using the named parameter convention and may be specified as any of the following values, or a list of any of the following values: <code>"Any", "Number", "Text"</code> or <code>"Handle"</code>, e.g.:
:<code>Discrete(Type: "Text")</code>

See also [[Discrete]]().

The type setting is used by the user interface components when labels are being entered to determine whether the values should be parsed. Expressions are allowed in GUI list cells when the type is <code>"Any"</code>.

[[Null]] values are also accepted without generating an out-of-bounds warning unless <code>nullOk: False</code> is specified.

==See Also==
* [[Objects and Values]]
* [[The Analytica Domain Attribute]]
* [[Attributes]]
* [[Continuous]]()
* [[Integer]]()
* [[GroupedInteger]]()
* [[Boolean]]()
* [[Discrete]]()
* [[Domain Indexes]]
* [[ProbTable]]
* [[DetermTable]]


<footer>Definition menu / {{PAGENAME}} / Check attribute</footer>