Using the Code operator

The Code operator is an Echoview virtual variable that is a Python application programming interface (API). The operator is specifically devised to transform echogram ping sample data. For example, according to a filter or algorithm of your design. The operator accepts other Echoview variables as input, performs computations on the associated ping samples in Python, and returns the output to Echoview.

The Code operator is only available under a licensed Advanced Operators module.

Security

Python programs may be written by anyone, and could contain malicious code or other security risks. Echoview recommends you review any files before executing them and only obtain them from trustworthy sources.

When opening an EV file that contains a Code operator or creating a Code virtual variable in a new EV file, a Security Warning window seeks permission to enable Python code for that EV file. Selecting No allows the display of and edits to the Code Variable properties dialog box. The Python source file may be edited, but is not executed.

A permission is valid while the EV file is open. To change the permission, close the EV file and reopen it.

The Security warning can be turned off under the Messages section of the Interface page of the Echoview Configuration dialog box.

Create a Code variable

  1. Right-click on the Dataflow window and on the Shortcut menu select New, Variable.
  2. On the Operator list select Code.
  3. Enter a name for the New virtual variable and click OK. This will open the Variable properties dialog box for the Code operator.
  4. On the Operands page use the Operand list to select the input operand(s). Use Add New Operand to add operands.
  5. On the Code page, under Python source file, specify an existing Python source file (see Security).

    - OR -

    Click New to generate a new Python source file.
  6. On the Code page, specify the Window size (pings) to access the adjacent pings to the matched ping (see Code operator mechanics and Ping index). This is an odd integer.
  7. Click OK to execute the Python source file. This will close the Variable properties dialog box and create the Code variable on the Dataflow window.
  8. Double-click the Code variable to display an echogram.

The Python source file

The Code operator allows you to generate a new Python source file. The default Echoview Python source file includes:

Notes:

Code operator mechanics

The echoview package

The echoview Python package comes installed with Echoview. The following classes in this package grant access to the pings from the input operands.

Classes in the echoview package

Wideband support

Echoview 12 onward allows processing the complex numbers from frequency modulated (FM) wideband data (see About transmitted pulses).

The complex values are available via Measurement.data_complex and Measurement.matched_filter. Define Operator.result_type within the Operator class to determine the correct echoview.MeasurementType:

    def result_type(self, input_types):
        return input_types[0]

Without this, the input operand ping data will be converted from FM to continuous wave. See also Wideband data types.

Complex value precision

Echoview uses complex numbers of type numpy.complex128, composed of two 64-bit precision floating-point numbers. However, you may use eval to return complex numbers of either type numpy.complex128 or numpy.complex64, depending on the precision required. For example

    return Measurement.data_complex.astype(np.complex64)

- OR -

    return Measurement.data_complex.astype(np.complex128)

Ping index

You can determine the matched ping's number from OperandInput.measurement.index (OperandInput.measurement is an object of the Measurement class).

Within the OperandInput window, this ping has index OperandInput.window_index.

For example, when using the default Python source file:

a) Ping 23 from Operand 1 in Echoview, using Window size (pings) 3.

inputs[0].measurement.index takes the value of the ping number, i.e., 23.

inputs[0].window_index takes the value 1. This is the middle item of the window comprising [Ping 22, Ping 23, Ping 24].

b) Ping 0 from Operand 1 in Echoview, using Window size (pings) 3.

inputs[0].measurement.index takes the value of the ping number, i.e., 0.

inputs[0].window_index takes the value 0. This is the first item of the window comprising [Ping 0, Ping 1].

Input/Output data types

The output acoustic variable data type from the Code operator is generally the same as the input acoustic variable data type of Operand 1.

You can change this by using Operator.result_type for example to that of operand 3

    def result_type(self, input_types):
        return input_types[2]

or some other data type using the attributes of the Measurement class.

    def result_type(self, input_types):
        return echoview.Measurement.SINGLE_BEAM_BOOLEAN

Important: Only the data type is changed, the data itself is not converted.

Wideband data types

The following wideband data types are output as corresponding single beam Sv, TS and power data types:

Input single beam operands with multibeam result output are not supported.

Input multibeam operands with single beam output is allowed. The output is similar to a Beam select operator. Note that the beam geometry is absent in the output data.

Importing packages and libraries

The Python NumPy and SciPy libraries are provided with Echoview. You can also import other Python libraries and packages. Visit The Python Standard Library - Site-specific configuration hook for more information.

Adding a site package

  1. Browse to C:\Users\username\AppData\Local\Echoview Software\Echoview64\EchoviewVersionNumber
    1. For Echoview 11.0, EchoviewVersionNumber is 11.0
  2. Create a folder called Python37.
  3. Within the Python37 folder create a folder called site-packages.
  4. Copy folder(s) containing the required package(s) into
    1. C:\Users\username\AppData\Local\Echoview Software\Echoview64\11.0\Python37\site-packages
  5. In your Python script, specify import NameOfSitePackage to use the added package(s).

Notes:

Reloading an imported package or library

If you update a package or library, you may need to

for the change to take effect for the Code operator.

Error handling

The Code operator's echogram is displayed as black when:

In these instances, an error message either from Echoview or the Python, is sent to the Messages dialog box.

No data handling

The Code operator supports Echoview no data values in the following ways:

See also:

Performance considerations

Follow these guidelines to improve the speed of your Code operator programs:

Example Python source files

The following example Python source files serve to demonstrate some uses of the Code operator. Take note of the UTF-8 coding system when using copy/paste, as this preserves the Python code indentation.

You may need to configure the color scheme, grid, analysis and display settings and thresholds when viewing the Code variable echogram.

Example script

Difficulty

Suitable data

Details

Dusk and dawn bitmap Easy Single beam or multibeam

Generates a bitmap where all samples in pings from Operand 1 around dawn and dusk (±1 hour) are True.

Multifrequency categorization Easy Single beam

This is a multifrequency categorization technique (see Jech and Michaels, 2006) for echosounder data analysis. It implements an algorithm that classifies the Sv responses that register above a threshold, from each frequency.

Biomass density estimator More difficult Single beam

Generates a mask, as a bitmap, that indicates if the biomass density is low enough to obtain reliable in situ TS values. This is accomplished by calculating the number of fish in the acoustic sampling volume (Nv, Sawada et al., 1993; see also Gauthier and Rose, 2001) and ratio of multiple echoes when measuring a single target (M) and then testing the resulting values against their respective threshold values (nv_threshold and m_threshold respectively).

Z score Multifrequency backscatter classification More difficult Single beam

Calculates the normal deviate (Z-score) for walleye pollock (Theragra chalcogramma) as detailed in De Robertis et al. 2010 from three Sv inputs with the frequencies 38kHz, 120kHz, and 200kHz respectively.

Diagnosis More difficult

 

Demonstrates methods of diagnosing issues in your custom Code operator.

Multibeam cross filter Most difficult Multibeam data

Generates a bitmap representing the fish detected using a cross filter on DIDSON data as detailed in Balk et al. 2009.

Smoothing multibeam data using a convolution window More difficult Multibeam data

Uses the Window Size property of the Code operator to smooth multibeam data in three-dimensions. The smoothing is performed as a mean in the linear domain, using the Window size to define the number of samples in each dimension to include in the calculation.

See also

Code operator
About the Code operator