About the Formula editor window

The Formula editor window offers a way to create a mathematical formula or logical expression that operates on the data in one or more input operand variables.

To display the Formula editor window.

  1. Create a new variable using the Formula operator

  2. On the Variable Properties dialog box for the new variable, click the Operands tab and select your input operands.

  3. On the Variable Properties dialog box for the new variable, click the Formula tab.

  4. Click Edit Formula

Edit Formula is only available when data is available, and when pings from multiple operands have the same time and geometry. The pings from the selected operands must have the same start range, stop range and number of samples in order to generate a result. For multibeam pings, all the operands must have the same beam count and spread. The Match pings times and Match geometry operators can help you satisfy the ping-multiple-operand requirement.

Note: The formula operator does not account for data type when it evaluates operations on data values. As a consequence, you need to be aware of your data types and design your formulae with respect to linear domain and dB domain calculations accordingly. Refer to Input operands, pings, samples and data values for more information.

Example window

The example below shows the Formula editor window with a formula (in the Editor area).

Using the Formula editor window

See Creating a formula for guidelines on formula creation. This section describes the tools available on the Formula editor window:

Selecting formula elements

The placeholder and insertion marker

Elements toolbar

Evaluation

The Structure panel

The Input panel

The menus

Selecting formula elements

Use the Elements toolbar to choose formula elements to insert into the formula f(p,s). Click to select an element to use in the formula editor. The mouse cursor mirrors the chosen element. To clear the selected element from the mouse, click ESC or Select. Available insertion points are highlighted as you navigate in the editor window with the mouse. Click in the formula to insert the element. To clear the selected element from the mouse, click ESC or Select.

You can use the Selection tool on the Elements toolbar to highlight a selection within the formula. Such areas are also highlighted in the Structure panel, where you can see additional relationships and evaluation information. The selection is marked as illustrated in the figure above.

Use PAGE UP and PAGE DOWN to navigate up and down levels within the formula structure. Use the LEFT ARROW, RIGHT ARROW, UP ARROW and DOWN ARROW to navigate within formula elements.

Placeholders and insertion marker

A formula element can be:

  • placed in a placeholder (visible as a shaded green square, as illustrated in the figure above)

  • - OR -

  • inserted at an insertion marker (visible as a highlighted area with a position indicator, as illustrated in the figure above)

The insertion marker can completely surround an element if the element you are inserting only has a single place holder (e.g. brackets). Only elements which can contain other elements can be inserted using the insertion marker. See Formula elements.

Press CTRL to ignore placeholders (only the insertion marker is used). This can be useful if you need to insert something before or after a placeholder.

The CUT, COPY, PASTE and Manipulate functions on the Edit menu or the Shortcut menu are also useful in editing a formula. Especially when selecting the insertion position (Top side, Bottom side, Left side and Right side).

Elements toolbar

The Elements toolbar offers formula elements, a (text) search filter and a selection tool selection tool that changes to reflect the element you want to insert.

Six distinct categories of formula elements are available:

Constants elements for user specified constants and fixed constants
Basic elements for basic algebraic, conversion and trigonometric functions
Echogram elements which access echogram data and input operands
Exponents elements for exponentiation and logarithms
Grid and Statistics elements for creating matrices and vectors
Boolean elements for creating logical expressions

Note: The Elements toolbar can be docked at the top or bottom of the Formula Editor area.

Input operands, ping, samples and data values

In order to operate on echograms or the data in an echogram, Echoview identifies a data value in an echogram by its unique input operand, ping number, beam number and sample number. When you use the Formula operator:

  • The input operand is represented by the symbol Vn where n takes on the numeral assigned to a listed input operand.

  • The ping number is represented by the symbol p and can take a value from 0 upwards (the first ping in an echogram is ping 0).

  • The beam number is represented by the symbol b and can take a value from 0 upwards (the first beam in an echogram is beam 0).

  • The sample number is represented by the symbol s and can take a value from 0 upwards (the first sample in a ping is sample 0).

  • The data value of the sample s on ping p for input operand 1 is returned by the function value 1 (p, s).

  • The data value of the sample s on ping p for beam b for input operand 1 is returned by the function value 1 (p, b, s).

Note: It is essential to note that the value function takes no account of the underlying data type of the echogram. Irrespective of the data type the value is the number which is stored for sample s on ping p. For example, on an Sv echogram, the value of -30dB is stored as -30 and the value function will return -30. It does not return the linear value of 0.001 which -30dB represents. The consequence of this is that you need to be aware of your data types and design your formulae with respect to linear domain and dB domain calculations accordingly. You can use the dB and lin elements to manage your dB and linear data types.

Evaluation

Use the Evaluate button to evaluate the Formula elements with respect to the selection on the Structure panel. Note, the process of evaluation can be lengthy. The Formula elements are evaluated according to the following priorities (1 represents the first priority):

Precedence

Toolbar
Symbol

Name

1
5.0
Number
pi
Pi
e
e
abs
Absolute Value
dB
Linear to dB
lin
dB to Linear
sin()
Sine
cos()
Cosine
tan()
Tangent
asin()
Arcsine
acos()
Arccosine
atan()
Arctangent
atan2()
Arctangent(y/x)
Rad
Degrees to Radians
Deg
Radians to Degrees
Round
Wrap
Clamp
Range
Centered Range
Var
Variance
Standard Deviation
Min
Max
Median
( )
Brackets
vps
Data Value
vpbs
Data Value
p
Ping Number
b
Beam Number
s
Sample Number
T/F
Constant Boolean
Grid
logb x
Logarithm
Mean
Sample range
angular position Angular Position
minor-axis Minor-axis angle
major-axis Major-axis angle
2
xy
Power
3
x
Multiply
Divide
4
+
Plus
-
Minus
5
<
Less Than
Less Than or Equal To
>
Greater Than
Greater Than or Equal To
=
Equal To
Not Equal To
6
not
Not
7
and
And
8
or
Or
xor
Exclusive Or

Notes:

The following conditions will return a no data value:

  • An illegal or erroneous operation e.g. division by zero or the square root of a negative number.

  • A sample beyond the limits of the operand echogram is referenced.

  • When b (the beam number) is not specified in vpbs.

  • A no data value in the operand. Alternative behavior occurs for formula elements that compare values.

  • When input values that are not angles are used with Angular Position, Minor-axis angle or Major-axis angle elements.

  • If a boolean element expects boolean values in an operand and the operand is not boolean (the boolean element is not evaluated).

Thresholded values are assigned a special value of -999 dB. Calculations in the linear domain handle the special value as zero. Other arithmetic calculations handle the special value such that the result is consistent with the thresholded nature of the value, as opposed to a pure numerical evaluation. For example -999 dB divided by a number returns -999 dB. Elements that support -999 dB are: Plus, Minus, Multiply, Divide, Absolute value, Round, Degrees to Radians, Radians to Degrees, Wrap, Clamp, Modulo, Logarithm, Power, Linear to dB, dB to Linear, Sine, Cosine, Tangent, Arcsine, Arccosine, Arctangent, Arctangent (y/x), Equal To, Less Than, Less than or Equal To, Greater than, Greater Than or and Equal To.

The Structure panel

The Structure panel displays an interactive structural view of the formula and evaluation information for formula elements. Zoom tools are also available.

One formula element can contain other elements, generally referred to as child elements or children. For example the element Plus (+) contains two elements which are added, and the element Minus (-) contains two elements which are subtracted. Each of those elements may in turn contain other elements.

The result is a structure which is illustrated in the structure panel. Each element has both a symbol and a name. The symbol is illustrated in the formula and the name is displayed in the structure panel.

To select an element, click on its name in the structure panel. The properties of the selected element are displayed at the bottom of the panel:

Type is the name of the element.

Evaluation Type is either Number (indicating a single value) or Set (indicating a group of values)

Evaluates to displays the value of that element if it is a Number, and if it can be calculated uniquely in the editor (that is, does not make reference to echogram data values).

The Input panel

The Input panel lists the (numbered) input operands that were selected on the Operands page of the Variable Properties dialog box. The numbered operand 1 corresponds to a Formula element V1. The settings Ping and Sample enable you to do a test evaluation of an expression in the Formula editor.

The menus

You can perform certain tasks on the Formula editor window by using the following commands on the:

Formula menu

Menu item

Description

Close Editor

Save formula and close the Formula editor window.

Edit menu

Some of these items have keyboard shortcuts. Refer to Formula editor keyboard shortcuts for more information.

Menu item

Description

Undo

Undo last action. Can undo multiple actions.

Redo

Redo last action. Can redo multiple actions.

Cut

Removes the selected element while keeping a copy of it in the Windows clipboard.

Copy

Copies the selected element into the Windows clipboard.

Paste

Removes the selected element replacing it with the contents of the Windows clipboard.

Paste Into Side

With an element that contains multiple place holders selected the Paste into menu item is accessible. The further commands of Top side, Bottom side, Left side and Right side are displayed based on the positions of the available placeholders.

Delete

Deletes the selected element.

Options

Displays the Options dialog box where you can set the following appearance options:

Option

Description

Normal font

Displays the font used for display. Click Change to change the font, its style or size.

Size (as a fraction of parent font size)

Displays the size of the Subscript font as a percentage of the parent font size. Enter a value or select a value from the list.

Subscript font

Displays previews for 3 levels of Subscript font.

Manipulate menu

Manipulate menu items can facilitate the editing of complex formulas. These items are also available on the Shortcut menu.

Menu item

Description

Swap Children

Swap the order of the children within the selected element.

For example:

  • A × B is changed to B × A
  • (A + B) × (C + D) is changed to (C + D) × (A + B)

Rotate Children Right

For the selected element that has more than two children, rotate child elements to the right.

For example:

  • A × (B + C) becomes A × (C + B)

Rotate Children Left

For the selected element that has more than two children, rotate child elements to the left.

Swap Order

For the selected element with children that contains nested elements, swap the order of main and nested elements.

For example:

  • A × (B + C) becomes (A × B) + C.

Remove

For the partially completed selected element that contains children, remove the selected element and leave the child. This is useful when you want to retain parts of a formula while editing.

Change To

Allows you to change the selected element and retain the children. Elements for substitution are grouped into:

Same Layout

Lists the elements that can be substituted without changing the general structure of the formula.

For example:

  • A (B + C) can be changed to A (B - C).

Different Layout

Lists the elements that will create different layouts, but contain the same number of child elements.

More Child Elements

Lists the elements that contain a greater number of children than the selected element.

Less Child Elements

Lists the elements that contain fewer children than the selected element.

View menu

Menu item

Description

Structure

Displays or hides the Structure panel.

Input Variables

Displays or hides the Input panel.

Zoom In

Zoom in within the Formula Editor area.

Zoom Out

Zoom out within the Formula Editor area.

Reset Zoom

Reset the zoom level.

Shortcut menu

The following commands may be available on the Shortcut (right-click) menu for a selected formula element:

Menu item

Shortcut key

Description

Cut

CTRL+X

Removes the selected element while keeping a copy of it in the Windows clipboard.

Copy

CTRL+C

Copies the selected element into the Windows clipboard.

Paste

CTRL+V

Removes the selected element replacing it with the contents of the Windows clipboard.

Paste Into

 

Move the mouse above an element with one placeholder and the Paste Into shortcut menu item is accessible.

Paste Into Side

 

Move the mouse above an element that contains multiple placeholders and the Paste Into Side shortcut menu item is accessible. The further commands of Top side, Bottom side, Left side and Right side are displayed based on the positions of the available placeholders.

Delete

DEL

Deletes the selected element.

Manipulate

  Accesses the Manipulate Menu

Properties

 

When available, allows you to view and change the properties of the selected formula term.

Available only for the Constant Number, Grid and Bracket elements.

Note: Elements are copied to the Windows clipboard encoded in a plain text format. You can paste this text into any other Windows application, save it in a text file, share it with other people, and this same text can be pasted into the Formula editor window again later. We do not recommend changing this text however — the encoding format is not currently documented and we cannot provide support for its interpretation.

See also

About the Formula operator
The Formula elements
Creating a formula
Formula operator