The formula elements

The formula elements are grouped according type:

Constants
Basic

Echogram

Exponents

Grid and Statistics
Boolean

Notes:

  • 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.
  • Handling for -999 dB special value.
Constants

Constant elements are evaluated according to their precedence.

Toolbar
Symbol

Math Symbol

Name

Contains this many elements

Properties

Description

5.0
a number
Number 0 The value itself

Contains a single real number which is set as a property.

T/F
T/F
Boolean 1 boolean value

Specifies a boolean value of True or False.

pi
ϖ
Pi 0 The value itself

Contains a single real number for Pi.

e
e
e 0 The value itself

Contains a single real number for e.

Basic

Basic elements are evaluated according to their precedence.

Note: An illegal or erroneous operation, e.g. division by zero, or the square root of a negative number, will return a no data value.

Toolbar
Symbol

Math Symbol

Name

Contains this many elements

Properties

Description

+
+
Plus 2 none

The elements are added.

-
-
Minus 2 none

The second element is subtracted from the first.

Divide 2 none

The first element is divided by the second.

x
x
Multiply 2 none

The elements are multiplied.

( )
as specified by properties.
Brackets 1 The style of bracket - (), {}, [], <> or custom.

Groups elements together into an expression which evaluates to a single value.

abs
abs()
Absolute Value Selection none

The absolute value of the selection within the brackets.

dB
dB()
Linear to dB Selection none

The linear to dB value of the selection within the brackets.

lin
lin()
dB to Linear Selection none

The dB to linear value of the selection within the brackets.

sin
sin()
Sine Selection none

The sine of the selection within the brackets. The selection is in degrees.

cos
cos()
Cosine Selection none

The cosine of the selection within the brackets. The selection is in degrees.

tan
tan()
Tangent Selection none

The tangent of the selection within the brackets. The selection is in degrees.

asin
Arcsine()
Arcsine Selection none

The arcsine of the selection within the brackets. Returns the arcsine in degrees.

acos
Arccosine()
Arccosine Selection none

The arccosine of the selection within the brackets. Returns the arccosine in degrees.

atan
Arctangent()
Arctangent Selection none

The arctangent of the selection within the brackets.

Returns the arctangent in the range -90 to 90 degrees, and returns an error for input outside that range.

atan2
Arctangent(y/x)
Arctangent(y/x) 2

The value for y.

The value for x.

The arctangent of the selection (y/x) within the brackets. Returns the arctangent(y/x) in the range -180 to 180 degrees, and returns an error for input outside that range.

rad
radian()
Degrees to Radians Selection none

The radian value of the selection (in degrees) within the brackets.

Example of use:

radian(180) = 3.141593

deg
degree()
Radians to Degrees Selection none

The degree value of the selection (in radians) within the brackets.

Example of use:

degree(π) = 180.00000

Round
round()
Round Selection none Rounds the selection to the nearest integer.
wrap(a,b)
Wrap 2 none

Finds the corresponding wrap-value for a in the wrap-range specified by b. b specifies the inclusive upper and lower integer values of the wrap-range and is a Range or Centered range (set) element.

The wrap-value equivalent to a is given by a mapping to the wrap-range. Where the wrap-range represents a ring of integers such that the upper and lower values of b wrap to each other.

Examples of use:

wrap(300,[-180,180]) = -60

wrap(5,[1,4]) = 2

wrap(-5,[0,3]) = 1

Clamp
clamp(a,b)
Clamp 2 none

Finds the corresponding clamp-value for a in clamp-range specified by b. b specifies the inclusive upper and lower integer values of the clamp-range and is a Range or Centered range (set) element.

The clamp-value for a is given by the mapping of a to the clamp-range. Values outside the clamp-range are mapped to the closest clamp range value.

Examples of use:

clamp(-5,[0,10]) = 0

clamp(5,[0,10]) = 5

mod
(a) mod (b)
Modulo 2 none

a mod b is a modular arithmetic operation. b defines the divisor and the set of integers {0...b}.

If ab then a mod b = a.

If a = n b where n is a positive integer, then a mod b = 0.

Otherwise, a mod b is the remainder of a division of a by b.

Examples of use:

10 mod 2 = 0

11 mod 2 = 1

2 mod 10 = 2

Echogram

Echogram elements are evaluated according to their precedence.

Notes: The following conditions will return a no data value:

  • 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.

Toolbar
Symbol

Math Symbol

Name

Contains this many elements

Properties

Description

V1
Vn
Input operand n 1 Input operand number (n).

Specifies the value of a ping (p) and sample (s) in the input operand (n) from the Input panel. Example of use:

variable use

vps
valuen(p,s)
Data Value 2 Input operand number (n).

The two components to this single beam formula element are ping number and sample number. Returns the value of the data point in the operand for the sample thus specified. This element is useful if you want to specify p and /or s in a more complex way.

The simple expression V1(p,s) is equivalent to V1.

Example of use:

single beam index

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 the specified sample. 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.

vpbs
valuen(p,b,s)
Data Value 3 Input operand number (n).

The four components to this multibeam formula element are input operand, ping number, beam number and sample number. Returns the value of the data point in the operand for the sample thus specified. This element is useful if you want to specify a multibeam variable in a specific way.

The simple expression V1(p,b,s) is equivalent to V1.

Example of use:

multibeam index

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 the specified sample. 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.

p
p
Ping Number 0 none

The current ping number that is being evaluated.

b
b
Beam Number 0 none

The current beam number that is being evaluated.

s
s
Sample Number 0 none

The current sample number that is being evaluated.

rangen(p,s) Sample range 3 none

The three elements are input operand, ping number and sample number. Returns the range of the data point in the operand for the sample thus specified.

When s is not an integer, the sample range is interpolated.

angular position angle(a,b) Angular Position 2

The value for a.

The value for b.

Angular Position is specified by a the minor-axis angle and b the major-axis angle. The angles are in degrees.

Notes:

  • The valid range for angles is -180 to +180 degrees. Input values for angles outside the valid range are translated into the equivalent valid angle.
  • angle(minor(V1), major(V1)) is equal to V1, given that V1 is an angular position variable.
minor axis angle minor() Minor-axis angle Selection none

The minor-axis angle in degrees.

Note: The valid range for angles is -180 to +180 degrees. Input values for angles outside the valid range are translated into the equivalent valid angle.

major axis angle major() Major-axis angle Selection none

The major-axis angle in degrees.

Note: The valid range for angles is -180 to +180 degrees. Input values for angles outside the valid range are translated into the equivalent valid angle.

Exponents

Exponent elements are evaluated according to their precedence.

Toolbar
Symbol

Math Symbol

Name

Contains this many elements

Properties

Description

logb x
logb x
Logarithm 2 none

Returns the logarithm of the second element to the base of the first element. For example, if the first element is 10 then the base 10 logarithm of the second element is returned.

xy
xy
Power 2 none

Returns the first element raised to the power of the second element.

Note: Echoview defines the power evaluation in these cases as: 0y = 0 and 00 = 1.

Grid and Statistics

Grid and Statistics elements are evaluated according to their precedence.

Toolbar
Symbol

Math Symbol

Name

Contains this many elements

Properties

Description

elements arranged in a grid
Grid rows × columns The size of the grid (in rows and columns)

Groups elements together into a set which evaluates to multiple values.

mean(s)
Mean 1 none

Contains one Grid element. Returns the sample mean of the elements in the grid. No_data values are not used in the calculation of the mean.

Where
n = number of elements in the grid
xj = the jth element in the grid
[a,b]
[a,b]
Range 2 none

Specifies the set integers from a to b inclusive. The range element can be used in the wrap and clamp elements.

Example of use:

[1,4] = {1,2,3,4}

[a ± b ]
Centered Range 2 none

Specifies the set of integers where the center integer is a and the lowest and highest integers are a ± b. The centered range element can be used in the wrap and clamp elements.

Example of use:

[p ± 2] = {p-2, p-1, p, p+1, p+2}

var
variance()
Variance Grid none

Returns the sample variance1 of the grid.


Where

n = number of elements in the grid
xj = the jth element in the grid

Note: The sample mean of the grid is used in this calculation.

stddev()
Standard Deviation Grid none

Returns the standard deviation1 of the grid.

Note: The sample mean of the grid is used in this calculation.

min()
Minimum Grid none Returns the minimum value of the grid.
max()
Maximum Grid none Returns the maximum value of the grid.
median()
Median Grid none

Returns the median value of the grid.

The median is the number in the middle of the ordered set derived from the grid. Half the grid elements have values that are greater than the median, and half the grid elements have values that are less.

Example of use:

For the set {1,2,3} the median is 2.

For the set {1,2,3,4} the median is 2.5.

1Note: The calculations for variance and standard deviation follow Donald Knuth's Art of Computer Programming, Vol 2, page 232, 3rd edition. This method provides the highest level of precision.

Boolean

Boolean elements are evaluated according to their boolean precedence or comparison precedence.

Note: If a boolean element expects boolean values in an operand, and the operand is not boolean (the boolean element is not evaluated), a no data value will be returned.

Toolbar
Symbol

Math Symbol

Name

Contains this many elements

Properties

Description

and
and
And 2 none

Logical And (x and y) that results in a value of True if both x and y are True, otherwise a value of False.

or
or
Or 2 none

Logical Or (x or y) that results in a value of True whenever x or y are True, otherwise a value of False.

xor
xor
Exclusive Or 2 none

Logical Exclusive Or (x xor y) that results in a value of True if only one of x or y is True, otherwise a value of False.

not
not
Not 1 none

Logical Not (not x) that results in a value that is the opposite of x.

When x is False, the value is True. When x is True, the value is False.

<
<
Less Than 2 none

Logical (x < y) that results in a value of True when the value of x is less than the value of y, otherwise a value of False.

No data returns a value of False.

Less Than or Equal To 2 none

Logical (xy) that results in a value of True when the value of x is less than or equal to the value of y, otherwise a value of False.

No data returns a value of False.

>
>
Greater Than 2 none

Logical (x > y) that results in a value of True when the value of x is greater than the value of y, otherwise a value of False.

No data returns a value of False.

Greater Than or Equal To 2 none

Logical (xy) that results in a value of True when the value of x is greater than or equal to the value of y, otherwise a value of False.

No data returns a value of False.

=
=
Equal To 2 none

Logical Equality (x = y) that results in a value of True when the value of x is equal to the value of y, otherwise a value of False.

No data returns a value of False.

Note: Angles and angular position can be used with the Equal to element.

Not Equal To 2 none

Logical Inequality (xy) that results in a value of True when the value of x is not equal to the value of y, otherwise a value of False.

No data returns a value of False.

Note: Angles and angular position can be used with the Not Equal to element.

See also

About the Formula operator
Creating a formula

Formula operator