# The formula elements

The formula elements are grouped according type:

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 0 The value itself Contains a single real number for Pi. 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 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(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 a ∈ b 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: 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: 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: 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. 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() 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() 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 x 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 (x ≤ y) 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 (x ≥ y) 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 (x ≠ y) 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.