Using the Code operator

• Preface
• Creating a Code operator
• Setting up and executing a Code operator
• Inputting operands into the Code operator
• Processing pings with the Code operator
• Selecting the matched ping
• Using the window of measurements
• Processing ping data or metadata
• Ping sample data in the Code operator
• Multibeam support
• Wideband support
• Applying calibration with the Code operator
• Returning ping data to Echoview
• The data type of the Code operator
• The Echoview Python package
• Importing Python packages
• Installing a package
• Using other packages and Echoview
• Reloading an imported package or library
• Error handling
• No data handling
• Performance considerations
• Example Python source files
• See also

Preface

This page contains detailed information on the Code operator's features.

If you are unfamiliar with the Code operator we recommend you first complete the Introduction to the Code operator tutorial or watch the Introduction to the Code operator: A Python interface for Echoview video.

Creating a Code operator

1. On the Dataflow window, click on an existing raw or virtual acoustic variable to preselect it.
2. Select Code operator from the Dataflow Toolbox or the New Virtual Variable dialog box.

This creates a new Code operator virtual variable with the variable that you preselected as Operand 1.

Setting up and executing a Code operator

1. First create a Code operator variable.
2. Click on the Code operator and open its Variable Properties dialog box (press F8)
3. On the Operands page specify the input operands
4. On the Code page, specify the
   • Echoview Python source file containing your Python program for the operator.
   • Window size (pings) setting, indicating the number of input pings into the Code operator with each iteration.
5. Configure any other settings on the Variable Properties dialog box.

To execute the Code operator, double-click on the Code operator dataflow object. This executes the commands in the Echoview Python source file for the Code operator and opens an echogram displaying the result.

While you have the echogram for the Code operator open, Echoview re-executes the Code operator whenever you save changes to the Code operator's Echoview Python source file.

Refer to error handling if you see a uniformly black echogram.

Inputting operands into the Code operator

You can input multiple operands into the Code operator by specifying them on the Code page of the Code operator's Variable Properties dialog box. However, all input operands must have the same ping geometry (refer to the Using multiple operands page).

Each of the operands on the Code page is an OperandInput object, which Echoview passes to the eval method in a Python list. For example, in this extract

        def eval(self, inputs: List[ev.OperandInput]):
            first_input = inputs[0]
            second_input = inputs[1]
            third_input = inputs[2]
                  ...
                  ...

Operand 1 is inputs[0], Operand 2 is inputs[1] and Operand 3 is inputs[2] in the Echoview Python source file.

Processing pings with the Code operator

The Code operator iterates through the pings of the input operands. Each ping in the Code operator is an object of the Measurement class. The current ping into the Code operator is called the matched ping, and corresponds to the current output ping.

(Note that for optimization reasons, the Code operator may not process the pings in an echogram in sequence.)

Selecting the matched ping

Use the measurement attribute of the OperandInput class to select the matched ping in the Echoview Python source file. For example,

        def eval(self, inputs: List[ev.OperandInput]):
            first_input = inputs[0]
            matched_ping = first_input.measurement
                 ...
                 ...

Note that the measurement attribute in the above snippet provides a shorthand syntax to identify the matched ping in the window of measurements. An equivalent way to select the match ping uses the window_measurements and window_index attributes of the OperandInput,

        def eval(self, inputs: List[ev.OperandInput]):
            first_input = inputs[0]
            matched_ping = first_input.window_measurements[first_input.window_index]
                 ...
                 ...

The window_index attribute is especially useful to ensure you identify the sample data for the matched ping to return to Echoview (refer to the returning ping data to Echoview section below). Refer to the multibeam fish detection filter example for an illustration.

Using the window of measurements

The Window size (pings) setting allows you to read pings adjacent to the matched ping into the Code operator. Then use the window_measurements attribute of the OperandInput class to access all the pings in the window. For example,

        def eval(self, inputs: List[ev.OperandInput]):
            first_input = inputs[0]
            first_input_window = first_input.window_measurements
                 ...
                 ...

Note that first_input_window in the above snippet is the window of measurements. It is a Python list.

While the matched ping is typically the item in the center of the window_measurements list, this rule does not apply at the ends of the input operand's echogram. Here, the window truncates as required to accommodate the deficiency in pings into the Code operator—meaning the matched ping is no longer in the center.

To obtain the value of the Window size (pings) setting use self.window_size.

Processing ping data or metadata

Each ping in the window of measurements is an object of the Measurement class. The attributes of this class correspond to various aspects of a ping, such as the recorded

• ping sample data,
• start/stop range,
• heading, and more.

Refer to the list of attributes of the Measurement class for a full list.

The (Python) data type of each attribute depends on the attribute itself. For example, the ping sample data are in a NumPy array, whereas the ping timestamp is a Python datetime object.

Ping sample data in the Code operator

This section presents some details on the data attribute of the Measurement class, i.e., the sample data for the pings in the window of measurements.

The Code operator grants you access to modify and compute the ping samples of an echogram according to an algorithm of your design. To access the ping's samples, use the data attribute. For example, to obtain the ping samples for the matched ping

        def eval(self, inputs: List[ev.OperandInput]):
            first_input = inputs[0]
            matched_ping = first_input.measurement
            matched_ping_data = matched_ping.data
                 ...
                 ...

The ping sample data—or matched_ping_data in the above example—is stored in a Python NumPy array, and corresponds to the sample value as a function of range.

While you can manipulate the array and its contents, you must return a NumPy array of the same shape as the input. For example,

            return matched_ping_data[0]

will cause an error (assuming the ping has more than 1 sample), as the return statement is only communicating the first ping sample to Echoview.

Multibeam support

For multibeam data the data attribute is a 2D NumPy array.

The first axis corresponds to the sample value as a function of range, and the second axis is the sample value as a function of beam.

Single beam data derived from multibeam data points in the direction of the transducer.

Wideband support

The data_complex (refer to the Measurement class) attribute exposes the underlying complex number ping samples for these wideband data types

• Complex power dB
• Complex Sv
• Complex TS
• Complex angular position

The complex values are underlying data from the wideband raw variables, prior to any processing (e.g., calculation of Sv and TS). However, note that the complex values have been pulse compressed for these wideband variables

• Pulse compressed power dB
• Pulse compressed complex Sv
• Pulse compressed complex TS
• Pulse compressed complex angular position

When returning complex values in eval, you must specify the result_type method (refer to OperatorBase) in your Echoview Python source file. Echoview converts the Code operator to the corresponding data type (as applicable). For more information, refer to the the data type of the Code operator section below.

Applying calibration with the Code operator

Use the cal method of the Measurement class to obtain the value of the calibration setting to use in your computations.

Refer to the biomass density estimator example for an illustration.

Returning ping data to Echoview

Use the return statement of the eval method to communicate the results from Python to Echoview via the Code operator. Refer to understanding the default Echoview Python source file for an example.

The results must be in a NumPy array of the same shape as the matched ping.

The data type of the Code operator

By default the Code operator adopts the data type of Operand 1.

The data types of the input operands are objects of the MeasurementType class. Refer to the attributes and methods of this class (for the syntax to use in the Echoview Python source file) to query the data types of the operands into the Code operator, or to set the data type of the Code operator.

Use the result_type method in the Echoview Python source file to set the data type of the Code operator.

For example, to choose the data type of Operand 3, return the data type of the third element (index 2) in the input_types list.

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

Or change the data type to single beam boolean, if you are returning an array of truth values

        def result_type(self, input_types):
            return ev.MeasurementType.SINGLE_BEAM_BOOLEAN

Note that result_type does not perform any computations to convert the data values from one to another. For example you cannot convert wideband complex values to pulse compressed by simply specifying a pulse compressed MeasurementType.

The Echoview Python package

The Echoview Python package comes installed with Echoview. You need to import the Echoview Python package in your Echoview Python source file for the Code operator.

Follow the links for detailed documentation for each of the following classes in the Echoview Python package.

Class	Description
Measurement	Represents the ping object and incorporates all supported ping data and meta data for the Code operator.
MeasurementType	Code operator supported data types.
OperandInput	Handle for the operands into the Code operator, including support for the Window size (pings) setting.
OperatorBase	Base class for the Operator class (refer to Understanding the default Echoview Python source file).
PingMode	Support for multibeam ping mode.

Importing Python packages

Echoview comes installed with the Echoview, NumPy and SciPy Python packages. It is mandatory to import the Echoview Python package in your Echoview Python source file.

        import echoview as ev

Similarly, you can also immediately import the NumPy and Scipy packages,

        import numpy as np
        import scipy

or any of the other packages from the Python Standard Library (https://docs.python.org/3/library/site.html). You can immediately import these in your Echoview Python source file.

If you wish to use other Python packages, you need to install them first.

Installing a package

Follow this procedure to install Python packages that are available from the Python Package Index (PyPI) using pip—the Python package installer.

1. Installing pip for Echoview (needed only once for your version of Echoview M.m)

   The following steps require Administrator privileges.

   1. Download and save https://bootstrap.pypa.io/get-pip.py into C:\Program Files\Echoview Software\Echoview M.m\Echoview\
   2. Open the Windows Command prompt as the administrator, and
      1. navigate to the Echoview Python interpreter location

         cd C:\Program Files\Echoview Software\Echoview M.m\Echoview\

      2. install pip for the Echoview Python interpreter

         python get-pip.py

         You may receive a WARNING from the installer that the scripts pip*.exe are not on PATH. Ignore this, as the packages you install will be for Echoview only and not any external Python environment.
2. Installing a Python package from PyPI

   With the Windows Command prompt

   1. navigate to the Echoview Python interpreter location

      cd C:\Program Files\Echoview Software\Echoview M.m\Echoview\

   2. indicate the destination to install the package

      SET PYTHONUSERBASE=%LOCALAPPDATA%\Echoview Software\Echoview64\M.m\

   3. install PACKAGE with the Echoview Python interpreter via pip

      python -m pip install --user PACKAGE

Using other packages with Echoview

Each time you want to use Echoview and other Python packages (other than those installed with Echoview), you need to specify a Windows Environment variable and then start Echoview.

Under the Windows Command prompt use:

cd C:\Program Files\Echoview Software\Echoview M.m\Echoview\
SET PYTHONUSERBASE=%LOCALAPPDATA%\Echoview Software\Echoview64\M.m\
Echoview.exe

 

Reloading an imported package or library

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

• close and reopen the EV file,
• close and restart Echoview, or
• use reload

for the change to take effect for the Code operator.

Error handling

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

• Echoview encounters an error with the Code operator
• there is an error in the Python source file
• the Echoview Python source file is not specified or cannot be found

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:

• a bitmap to indicate which values should be included. This is the approach taken by NumPy masked arrays.
• Not a Number (numpy.nan) values to indicate no data. (Some NumPy functions like numpy.nanmean will ignore NaN values.)

Performance considerations

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

• Set Window size (pings) to the minimum that you need. This conserves the amount of data that will be loaded into memory.
• NumPy and SciPy (see Importing Python packages) contain highly optimized routines that can replace loops, conditional statements and mathematical operations.

Example Echoview Python source files

The following example Python source files serve to demonstrate some uses of the Code operator. These source files use the UTF-8 character encoding format.

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

Echoview Python source file	Description
Dusk and dawn bitmap	Generates a bitmap where all samples in pings from Operand 1 around (±1 hour) dawn and dusk are True. For use with single or multibeam data.
Multifrequency categorization	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. For use with single beam data.
Biomass density estimator	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	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. For use with single beam data.
Diagnosis	Demonstrates methods of diagnosing issues in your custom Code operator. For use with single beam data.
Multibeam fish detection filter	Generates a bitmap that assists fish identification in multibeam echosounders (e.g., DIDSON or ARIS sonars). For use with multibeam data.
Smoothing multibeam data using a convolution window	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. For use with multibeam data.

See also

About the Code operator
About the Echoview Python source file
Code operator