Difference between revisions of "Creating or editing a definition"
m (converted pseudo subsections to actual MediaWiki subsections.)
 
(16 intermediate revisions by 3 users not shown)
Line 1: Line 1:
−
[[Category:Analytica User Guide]]
+
[[Category: Analytica User Guide]]
−
<breadcrumbs>Analytica User Guide > Creating and Editing Definitions > {{PAGENAME}}</breadcrumbs>
+
[[Category: Definitions]]
 +
<breadcrumbs>Analytica User Guide > Definitions > {{PAGENAME}}</breadcrumbs>
 +
{{ReleaseBar}}
  
 
==How to create or edit a definition==
 
==How to create or edit a definition==
−
To create or edit the definition of a variable, first be sure that the edit tool [[File:Chapter8_1.png]] is selected. Select the variable of interest and do any of the following:
+
To create or edit the [[definition]] of a variable (or function), first be sure that the edit tool {{Release||4.6|[[Image:Chapter8_1.png]]}}{{Release|5.0||[[Image:ToolbarEditModeButton.png]]}} is selected. Select the variable of interest by clicking its node in its parent Diagram. Then do one of these actions:
  
−
* Click [[File:Chapter8_2.png]] in the toolbar, or press ''Control+e''.
+
* Click {{Release||4.6|[[Image:Chapter8_2.png]]}}{{Release|5.0||[[Image:ToolbarExprButton.png]]}} in the [[toolbar]]
−
* Select '''Edit Definition '''from the '''Definition '''menu.
+
* Press ''Control+e''.  
−
* Double-click the variable to open its '''Object '''window. Then click in the definition field.
+
* From the [[Definition menu]], select '''Edit Definition '''.
−
* Click the key icon [[File:Chapter8_3.png]] to open the '''Attribute '''panel of the diagram. Select '''Definition '''from the '''Attribute '''popup menu. Then click in the definition field.
+
Each of these three actions either
 +
* Opens the  [[Attribute panel]] below the Diagram and selects the Definition attribute for the variable
 +
* Or,  shows the Object view  and selects its Definition, if the Object view for the variable is already open or if, in the [[Preferences]] dialog, you selected '''opens: Object window''': {{Release||4.6|[[Image:Preferences expr opens Object window.png|200px]]}}{{Release|5.0||[[Image:PreferenceExprOpens.png|200px]]}}
 +
* Or,  it opens the Edit table view, if the definition of the Variable is an [[Edit table]],.
 +
If you want to make sure to edit the Definition in the  [[Attribute panel]]:
 +
* Below the Diagram, click the key icon [[File:Chapter8_3.png]] to open the [[Attribute panel] and select '''Definition '''from the [[Attribute dropdown menu]].  
 +
If you want to make sure to edit the Definition in the Object window:
 +
* Double-click the node to open its [[Object window]].
  
−
[[File:Chapter8_4.png]]
+
:[[File:Chapter8_4.png]]
  
 
If you have drawn arrows into this variable from other variables (<code>Down_payment</code> and <code>Buying_price</code> in this example), they appear in the [[File:Chapter8_5.png]] menu. Select an input to paste its identifier into the definition. (The menu doesn’t appear if the variable has no inputs.)
 
If you have drawn arrows into this variable from other variables (<code>Down_payment</code> and <code>Buying_price</code> in this example), they appear in the [[File:Chapter8_5.png]] menu. Select an input to paste its identifier into the definition. (The menu doesn’t appear if the variable has no inputs.)
  
−
<tip title="Tip">If you are editing in the '''Attribute '''panel, a handy way to insert the identifier of a node into the definition is to click the node while pressing the ''Alt ''key. This only works for nodes in the same diagram.</tip>
+
<tip title="Tip">If you are editing a Definition in the [[Attribute panel]], you can insert the [[identifier]] of a node into the definition at the cursor simply by clicking that node while pressing the ''Control'' or ''Alt ''key. This only works for nodes in the same diagram.</tip>
  
−
To edit a definition that is a simple number, text, or other expression:
+
To edit a [[definition]] that is a simple number, text, or other expression:
  
 
# Select the definition.
 
# Select the definition.
 
# Edit it by typing, by deleting, or by using the standard text editing operators — that is, '''Copy''' (''Control+c''), '''Cut '''(''Control+x''), and '''Paste '''(''Control+v'').
 
# Edit it by typing, by deleting, or by using the standard text editing operators — that is, '''Copy''' (''Control+c''), '''Cut '''(''Control+x''), and '''Paste '''(''Control+v'').
  
−
See [[Using Expressions]] for the syntax of numbers, operators, simple expressions, and mathematical functions.
+
See [[Expressions]] for the syntax of numbers, operators, simple expressions, and mathematical functions.
  
−
You can change the definition to one of several commonly used expressions with the Expression popup menu.  
+
You can change the definition to one of several common expressions by selecting an option from the [[Expression popup menu]].  
  
−
'''Expression Assist''': As you type an expression into the definition, the Expression Assist pops up with each keystroke to show possible identifier completions, function parameters, function descriptions, or index values. Expression Assist may be turned on or off from the Preferences dialog. Even when it is turned off, you can press ''Ctrl+Space ''to display it temporarily.  
+
===Expression Assist===
 +
As you type an expression into the definition, the [[Expression Assist]] pops up with each keystroke to show possible identifier completions, function parameters, function descriptions, or index values. Expression Assist may be turned on or off from the Preferences dialog. Even when it is turned off, you can press ''Ctrl+Space ''to display it temporarily.  
  
−
'''Special editing key combinations''': These special mouse and key combinations are useful when editing a definitions:
+
''Shortcuts for editing''': These special mouse and key combinations are useful when editing a definitions:
 
:{| class="wikitable"
 
:{| class="wikitable"
 
!Key or key combination
 
!Key or key combination
Line 33: Line 43:
 
|-
 
|-
 
|''double-click''
 
|''double-click''
−
|Selects the entire identifier containing the cursor.
+
|Select the identifier of variable, function or other text that contains the cursor
 
|-
 
|-
−
|''Alt+click'' a node,
+
|''Ctrl+f
 +
|Open [[Find Dialog]] with selected identifier or other text (if any)
 +
|-
 +
|''Alt+click'' a node<br />
 
''Ctrl+click'' a node
 
''Ctrl+click'' a node
−
|Inserts identifier of the node at the cursor position. Works when nodes are in the same diagram window as the definition being edited.
+
|Insert identifier of the node at the cursor position. Works when nodes are in the same diagram window as the definition being edited.
 
|-
 
|-
−
|''left-arrow ←, right-arrow ''→
+
|''left-arrow &larr;<br />right-arrow &rarr;''
−
|Moves cursor one character left or right.
+
|Move cursor one character left or right.
 
|-
 
|-
−
|''up-arrow, down-arrow''
+
|''up-arrow or &uarr; <br />down-arrow &darr;''
−
|When Expression Assist is displaying possible identifier completions, moves the selection. Otherwise, moves the caret one line up or down.
+
|When Expression Assist is displaying possible identifier completions, move the selection. <br />Otherwise, move the caret cursor one line up or down.
 
|-
 
|-
−
|''Control+left-arrow, Control+right-arrow''
+
|''Ctrl+&larr;<br />Ctrl+&rarr;''
−
|Moves to the beginning or end of the next word or identifier.
+
|Move to the beginning or end of the next word or identifier.
 
|-
 
|-
−
|''Alt+Control+left-arrow, Alt+Control+right-arrow''
+
|''Alt+Ctrl+&larr;<br />Alt+Ctrl+&rarr;''
 
|Moves the cursor from the adjacent parenthesis to the next matching parenthesis, left or right.
 
|Moves the cursor from the adjacent parenthesis to the next matching parenthesis, left or right.
 
|-
 
|-
 
|''Esc''
 
|''Esc''
−
|Temporarily removes expression assist popup.
+
|Temporarily remove [[Expression Assist]] popup.
 
|-
 
|-
 
|''Ctrl+space''
 
|''Ctrl+space''
Line 58: Line 71:
 
|-
 
|-
 
|''Ctrl+?''
 
|''Ctrl+?''
−
|Toggles Expression Assist on or off for the field being edited. Note: On most keyboards, ? requires the Shift key, so this is really Ctrl+Shift+?.
+
|Toggle Expression Assist on or off for the field being edited. Note: On most keyboards, ? requires the Shift key, so this is really Ctrl+Shift+?.
 
|-
 
|-
 
|''Tab''
 
|''Tab''
−
|When Expression Assist displays possible completions, inserts the first (or selected) one.
+
|When Expression Assist displays possible completions, insert the first (or selected) one.
 
|}
 
|}
  
−
If you also press ''Shift ''with any arrow movements, it selects the text between old and new cursor positions for copy/paste operations, etc.
+
If you press ''Shift ''with any arrow movements, it selects the text between old and new cursor positions for copy/paste operations, etc.
  
−
'''Parenthesis matching''': Analytica expressions sometimes contain several levels of nested parentheses. To help keep parentheses clear, when you place the cursor just to the right of a parenthesis, it makes it and its matching parenthesis bold. This works for left or right parentheses, square brackets, or curly brackets (used for comments). It helps you see whether you have the right number and types of parentheses in complex expressions, without resorting to counting.
+
===Parenthesis matching===
 +
Analytica expressions sometimes contain several levels of nested parentheses. To help keep parentheses clear, when you place the cursor just to the right of a parenthesis, it makes it and its matching parenthesis bold. This works for left or right parentheses, square brackets, or curly brackets (used for comments). It helps you see whether you have the right number and types of parentheses in complex expressions, without resorting to counting.
  
 
The ''Alt+Control+arrow ''keys also help. For example, pressing ''Alt+Control+right-arrow ''when the cursor is at '''''A '''''moves the cursor to '''''B'''''. Then pressing ''Alt+Control+left-arrow ''moves it back again:
 
The ''Alt+Control+arrow ''keys also help. For example, pressing ''Alt+Control+right-arrow ''when the cursor is at '''''A '''''moves the cursor to '''''B'''''. Then pressing ''Alt+Control+left-arrow ''moves it back again:
  
−
[[File:Chapter8 7.png]]
+
:[[File:Chapter8 7.png]]
  
−
'''Comments in definitions''': It is wise to document your models generously. Usually, it’s best to document what a variable or function represents in its '''Description '''attribute, and also explain its algorithm if it’s not obvious. For complex, multiline definitions, it’s also useful to insert comments within the definition. Comments can also be used to disable portions of expressions while debugging.
+
===Comments in definitions===
 +
It is wise to document your models generously. Usually, it’s best to document what a variable or function represents in its '''Description '''attribute, and also explain its algorithm if it’s not obvious. For complex, multiline definitions, it’s also useful to insert comments within the definition. Comments can also be used to disable portions of expressions while debugging.
  
 
Enclose comments in curly brackets:
 
Enclose comments in curly brackets:
 
:<code>Variable X := -b*Sqrt(B^2 - 4*A*C)/A { Positive quadratic root }</code>
 
:<code>Variable X := -b*Sqrt(B^2 - 4*A*C)/A { Positive quadratic root }</code>
  
−
You can insert a comment at any point in an expression where whitespace is allowed. Analytica ignores anything inside a comment when parsing or evaluating an expression. If you start a comment with “{” , then your comment cannot contain the “}” character within the comment.
+
You can insert a comment at any point in an expression where whitespace is allowed. Analytica ignores anything inside a comment when parsing or evaluating an expression. If you start a comment with <code>{</code> , then your comment cannot contain the <code>}</code> character within the comment.
  
 
<tip title="Tip">Analytica does not preserve comments in the cells of an edit table — so it’s not worth entering comments there.</tip>
 
<tip title="Tip">Analytica does not preserve comments in the cells of an edit table — so it’s not worth entering comments there.</tip>
  
−
'''Identifiers''': To refer to the value of another variable, use its identifier. To place a variable’s identifier at the insertion point in the definition, do any of the following:
+
===Identifiers===
 +
To refer to the value of another variable, use its [[identifier]]. To place a variable’s identifier at the insertion point in the definition, do any of the following:
  
 
* If the variable is an input, select it from the '''Inputs '''popup menu.
 
* If the variable is an input, select it from the '''Inputs '''popup menu.
 
* Type in the variable’s identifier. To see all nodes in the active diagram labeled by their identifiers (instead of their titles), select '''Show By Identifier '''from the '''Object '''menu (''Control+y''). (Note that entering ''Control+y ''a second time switches the diagram back to displaying the nodes by their titles.)
 
* Type in the variable’s identifier. To see all nodes in the active diagram labeled by their identifiers (instead of their titles), select '''Show By Identifier '''from the '''Object '''menu (''Control+y''). (Note that entering ''Control+y ''a second time switches the diagram back to displaying the nodes by their titles.)
−
* Select '''Paste Identifier '''from the '''Definition '''menu and use the '''Find '''button or identifier menu items in the Object Finder dialog.
+
* Select '''Paste Identifier '''from the [[Definition menu]] and use the '''Find '''button or identifier menu items in the [[Object Finder dialog]].
−
* If the definition is being edited from the '''Attribute '''panel, you can insert the identifier of a variable in the same module window by holding down the ''Alt ''key and clicking the node. The identifier of the clicked node is inserted at the caret position. This shortcut isn’t available from the '''Object '''window or for nodes is different modules.
+
* If the definition is being edited from the [[Attribute panel]], you can insert the identifier of a variable in the same module window by holding down the ''Alt ''key and clicking the node. The identifier of the clicked node is inserted at the caret position. This shortcut isn’t available from the [[Object window]] or for nodes is different modules.
  
−
'''Functions''': You can paste functions at the insertion point by doing either of the following:
+
===Functions===
−
* Select '''Paste Identifier '''from the '''Definition '''menu to open the Object Finder dialog.
+
You can paste functions at the insertion point by doing either of the following:
 +
* Select '''Paste Identifier '''from the [[Definition menu]] to open the [[Object Finder dialog]].
 
* Select the function from its library in the Definition menu.
 
* Select the function from its library in the Definition menu.
  
−
'''Syntax check''': After entering or editing a definition, press ''Alt-Enter ''or click the accept button [[File:Chapter8 8.png]] to perform a syntax check of the revised definition and accept the changes.
+
===Syntax check===
 +
After entering or editing a definition, press ''Alt-Enter ''or click the accept button [[File:Chapter8 8.png]] to perform a syntax check of the revised definition and accept the changes.
  
 
Click the cancel button [[File:Chapter8 9.png]] to cancel your changes.
 
Click the cancel button [[File:Chapter8 9.png]] to cancel your changes.
Line 98: Line 116:
 
The definition warning icon [[File:Chapter8 10.png]] appears next to the definition if it is not syntactically correct. Click the icon to see a message about what might be wrong.
 
The definition warning icon [[File:Chapter8 10.png]] appears next to the definition if it is not syntactically correct. Click the icon to see a message about what might be wrong.
  
−
[[File:Chapter8 11.png]]
+
:[[File:Chapter8 11.png]]
  
 
A definition’s syntax check can reveal syntax errors. For example, if a definition contains text that is not an identifier, the following dialog appears.
 
A definition’s syntax check can reveal syntax errors. For example, if a definition contains text that is not an identifier, the following dialog appears.
  
−
[[File:Chapter8 12.png]]
+
:[[File:Chapter8 12.png]]
  
 
==Automatically updating the diagram==
 
==Automatically updating the diagram==
 
After you give a variable a valid definition, the influence diagram containing that variable might change.
 
After you give a variable a valid definition, the influence diagram containing that variable might change.
  
−
'''Cross-hatching disappears''': Normally, any node whose definition is missing or invalid displays with a cross-hatch pattern.
+
===Cross-hatching disappears===
 +
Normally, any node whose definition is missing or invalid displays with a cross-hatch pattern.
  
−
[[File:Chapter8 13.png]]
+
:[[File:Chapter8 13.png]]
  
 
After you enter a valid definition, the cross-hatching disappears and the node becomes clear.
 
After you enter a valid definition, the cross-hatching disappears and the node becomes clear.
  
−
[[File:Chapter8 14.png]]
+
:[[File:Chapter8 14.png]]
  
−
You can remove cross-hatching even from invalid variables by unchecking '''Show Undefined '''in the '''Preferences '''dialog from the '''Edit '''menu.
+
You can remove cross-hatching even from invalid variables by unchecking '''Show Undefined '''in the [[Preferences dialog]] from the [[Edit menu]].
  
−
'''Arrow updating''': After you enter or edit a definition, it ensures that the arrows going into the node to properly reflect its inputs. It adds an arrow from any extra variable you mentioned, and removes an arrow from any variable you didn’t use in the definition.
+
===Arrow updating===
 +
After you enter or edit a definition, it ensures that the arrows going into the node to properly reflect its inputs. It adds an arrow from any extra variable you mentioned, and removes an arrow from any variable you didn’t use in the definition.
  
 
==See Also==
 
==See Also==
−
<footer>Creating and Editing Definitions / {{PAGENAME}} / The Expression popup menu</footer>
+
* [[Definition]]
 +
* [[Definition menu]]
 +
* [[Definition menu (more)]]
 +
* [[Writing Array-Abstractable Definitions]]
 +
* [[Expressions]]
 +
* [[Expression Assist]]
 +
* [[Expression Syntax]]
 +
 
 +
 
 +
<footer>Definitions / {{PAGENAME}} / The Expression popup menu</footer>

Latest revision as of 20:04, 5 July 2024

Analytica User GuideDefinitionsCreating or editing a definition
Release:

…  • 4.6 •  5.0 •  5.1 •  5.2 •  5.3 •  5.4 •   •  6.0 •  6.1 •  6.2 •  6.3 •  6.4 •  6.5 •  6.6

How to create or edit a definition

To create or edit the definition of a variable (or function), first be sure that the edit tool ToolbarEditModeButton.png is selected. Select the variable of interest by clicking its node in its parent Diagram. Then do one of these actions:

Each of these three actions either

  • Opens the Attribute panel below the Diagram and selects the Definition attribute for the variable
  • Or, shows the Object view and selects its Definition, if the Object view for the variable is already open or if, in the Preferences dialog, you selected opens: Object window: PreferenceExprOpens.png
  • Or, it opens the Edit table view, if the definition of the Variable is an Edit table,.

If you want to make sure to edit the Definition in the Attribute panel:

  • Below the Diagram, click the key icon Chapter8 3.png to open the [[Attribute panel] and select Definition from the Attribute dropdown menu.

If you want to make sure to edit the Definition in the Object window:

Chapter8 4.png

If you have drawn arrows into this variable from other variables (Down_payment and Buying_price in this example), they appear in the Chapter8 5.png menu. Select an input to paste its identifier into the definition. (The menu doesn’t appear if the variable has no inputs.)

Tip
If you are editing a Definition in the Attribute panel, you can insert the identifier of a node into the definition at the cursor simply by clicking that node while pressing the Control or Alt key. This only works for nodes in the same diagram.

To edit a definition that is a simple number, text, or other expression:

  1. Select the definition.
  2. Edit it by typing, by deleting, or by using the standard text editing operators — that is, Copy (Control+c), Cut (Control+x), and Paste (Control+v).

See Expressions for the syntax of numbers, operators, simple expressions, and mathematical functions.

You can change the definition to one of several common expressions by selecting an option from the Expression popup menu.

Expression Assist

As you type an expression into the definition, the Expression Assist pops up with each keystroke to show possible identifier completions, function parameters, function descriptions, or index values. Expression Assist may be turned on or off from the Preferences dialog. Even when it is turned off, you can press Ctrl+Space to display it temporarily.

Shortcuts for editing': These special mouse and key combinations are useful when editing a definitions:

Key or key combination Action
double-click Select the identifier of variable, function or other text that contains the cursor
Ctrl+f Open Find Dialog with selected identifier or other text (if any)
Alt+click a node

Ctrl+click a node

Insert identifier of the node at the cursor position. Works when nodes are in the same diagram window as the definition being edited.
left-arrow ←
right-arrow → 		Move cursor one character left or right.
up-arrow or ↑
down-arrow ↓ 		When Expression Assist is displaying possible identifier completions, move the selection.
Otherwise, move the caret cursor one line up or down.
Ctrl+←
Ctrl+→ 		Move to the beginning or end of the next word or identifier.
Alt+Ctrl+←
Alt+Ctrl+→ 		Moves the cursor from the adjacent parenthesis to the next matching parenthesis, left or right.
Esc Temporarily remove Expression Assist popup.
Ctrl+space Temporarily show expression assist.
Ctrl+? Toggle Expression Assist on or off for the field being edited. Note: On most keyboards, ? requires the Shift key, so this is really Ctrl+Shift+?.
Tab When Expression Assist displays possible completions, insert the first (or selected) one.

If you press Shift with any arrow movements, it selects the text between old and new cursor positions for copy/paste operations, etc.

Parenthesis matching

Analytica expressions sometimes contain several levels of nested parentheses. To help keep parentheses clear, when you place the cursor just to the right of a parenthesis, it makes it and its matching parenthesis bold. This works for left or right parentheses, square brackets, or curly brackets (used for comments). It helps you see whether you have the right number and types of parentheses in complex expressions, without resorting to counting.

The Alt+Control+arrow keys also help. For example, pressing Alt+Control+right-arrow when the cursor is at A moves the cursor to B. Then pressing Alt+Control+left-arrow moves it back again:

Chapter8 7.png

Comments in definitions

It is wise to document your models generously. Usually, it’s best to document what a variable or function represents in its Description attribute, and also explain its algorithm if it’s not obvious. For complex, multiline definitions, it’s also useful to insert comments within the definition. Comments can also be used to disable portions of expressions while debugging.

Enclose comments in curly brackets:

Variable X := -b*Sqrt(B^2 - 4*A*C)/A { Positive quadratic root }

You can insert a comment at any point in an expression where whitespace is allowed. Analytica ignores anything inside a comment when parsing or evaluating an expression. If you start a comment with { , then your comment cannot contain the } character within the comment.

Tip
Analytica does not preserve comments in the cells of an edit table — so it’s not worth entering comments there.

Identifiers

To refer to the value of another variable, use its identifier. To place a variable’s identifier at the insertion point in the definition, do any of the following:

  • If the variable is an input, select it from the Inputs popup menu.
  • Type in the variable’s identifier. To see all nodes in the active diagram labeled by their identifiers (instead of their titles), select Show By Identifier from the Object menu (Control+y). (Note that entering Control+y a second time switches the diagram back to displaying the nodes by their titles.)
  • Select Paste Identifier from the Definition menu and use the Find button or identifier menu items in the Object Finder dialog.
  • If the definition is being edited from the Attribute panel, you can insert the identifier of a variable in the same module window by holding down the Alt key and clicking the node. The identifier of the clicked node is inserted at the caret position. This shortcut isn’t available from the Object window or for nodes is different modules.

Functions

You can paste functions at the insertion point by doing either of the following:

Syntax check

After entering or editing a definition, press Alt-Enter or click the accept button Chapter8 8.png to perform a syntax check of the revised definition and accept the changes.

Click the cancel button Chapter8 9.png to cancel your changes.

The definition warning icon Chapter8 10.png appears next to the definition if it is not syntactically correct. Click the icon to see a message about what might be wrong.

Chapter8 11.png

A definition’s syntax check can reveal syntax errors. For example, if a definition contains text that is not an identifier, the following dialog appears.

Chapter8 12.png

Automatically updating the diagram

After you give a variable a valid definition, the influence diagram containing that variable might change.

Cross-hatching disappears

Normally, any node whose definition is missing or invalid displays with a cross-hatch pattern.

Chapter8 13.png

After you enter a valid definition, the cross-hatching disappears and the node becomes clear.

Chapter8 14.png

You can remove cross-hatching even from invalid variables by unchecking Show Undefined in the Preferences dialog from the Edit menu.

Arrow updating

After you enter or edit a definition, it ensures that the arrows going into the node to properly reflect its inputs. It adds an arrow from any extra variable you mentioned, and removes an arrow from any variable you didn’t use in the definition.

See Also


DefinitionsCreating or editing a definitionThe Expression popup menu
Comments


You are not allowed to post comments.