API reference

API components that most users will interact with.

In echopype versions prior to 0.5.0, the API in this page focused on the convert and process subpackages. See the 0.4.1 API page if you’re using a previous release. That workflow is now removed.

Content

EchoData class

EchoData is an object that handles interfacing raw converted data. It is used for calibration and other processing.

Classes

EchoData([converted_raw_path, ...])

Echo data model class for handling raw converted data, including multiple files associated with the same data set.

Open raw and converted files

echopype.open_rawraw_file: '100MB'EchoData

Create an EchoData object containing parsed data from a single raw data file.

The EchoData object can be used for adding metadata and ancillary data as well as to serialize the parsed data to zarr or netcdf.

ParametersReturnsRaises
Notes

In case of a large memory footprint, the program will determine if using a temporary swap space is needed. If so, it will use that space during conversion to prevent out of memory errors.

Users can override this behaviour by either passing use_swap=True or use_swap=False. If a keyword “auto” is used for the use_swap parameter, echopype will determine the usage of swap space automatically.

This feature is only available for the following echosounders: EK60, ES70, EK80, ES80, EA640.

echopype.open_convertedconverted_raw_path] None**kwargs

Create an EchoData object from a single converted netcdf or zarr file.

ParametersReturns

Combine EchoData objects

echopype.combine_echodataechodata_list] NoneEchoData

Combines multiple EchoData objects into a single EchoData object.

ParametersReturnsRaises
NotesExamples

Combine lazy loaded EchoData objects:

>>> ed1 = echopype.open_converted("file1.zarr")
>>> ed2 = echopype.open_converted("file2.zarr")
>>> combined = echopype.combine_echodata(echodata_list=[ed1, ed2])

Combine in-memory EchoData objects:

>>> ed1 = echopype.open_raw(raw_file="EK60_file1.raw", sonar_model="EK60")
>>> ed2 = echopype.open_raw(raw_file="EK60_file2.raw", sonar_model="EK60")
>>> combined = echopype.combine_echodata(echodata_list=[ed1, ed2])

Data processing subpackages

calibrate

Functions

compute_Sv(echodata, **kwargs)

Compute volume backscattering strength (Sv) from raw data.

compute_TS(echodata, **kwargs)

Compute target strength (TS) from raw data.

clean

Functions

estimate_noise(ds_Sv, ping_num, range_sample_num)

Estimate background noise by computing mean calibrated power of a collection of pings.

remove_noise(ds_Sv, ping_num, range_sample_num)

Remove noise by using estimates of background noise from mean calibrated power of a collection of pings.

commongrid

Functions

compute_MVBS(ds_Sv[, range_var, range_bin, ...])

Compute Mean Volume Backscattering Strength (MVBS) based on intervals of range (echo_range) or depth (depth) and ping_time specified in physical units.

compute_NASC(ds_Sv[, range_bin, dist_bin, ...])

Compute Nautical Areal Scattering Coefficient (NASC) from an Sv dataset.

compute_MVBS_index_binning(ds_Sv[, ...])

Compute Mean Volume Backscattering Strength (MVBS) based on intervals of range_sample and ping number (ping_num) specified in index number.

consolidate

Functions

swap_dims_channel_frequency(ds)

Use frequency_nominal in place of channel to be dataset dimension and coorindate.

add_depth(ds[, depth_offset, tilt, downward])

Create a depth data variable based on data in Sv dataset.

add_location(ds, echodata[, nmea_sentence])

Add geographical location (latitude/longitude) to the Sv dataset.

add_splitbeam_angle(source_Sv, echodata, ...)

Add split-beam (alongship/athwartship) angles into the Sv dataset.

qc

Functions

coerce_increasing_time(ds[, time_name, win_len])

Coerce a time coordinate so that it always flows forward.

exist_reversed_time(ds, time_name)

Test for occurrence of time reversal in specified datetime coordinate variable.

mask

Functions

frequency_differencing(source_Sv[, ...])

Create a mask based on the differences of Sv values using a pair of frequencies.

apply_mask(source_ds, mask[, var_name, ...])

Applies the provided mask(s) to the Sv variable var_name in the provided Dataset source_ds.

metrics

Functions to compute summary statistics from echo data.

Functions

abundance(ds[, range_label])

Calculates the area-backscattering strength (Sa) [unit: dB re 1 m^2 m^-2].

aggregation(ds[, range_label])

Calculated the index of aggregation (IA) [unit: m^-1].

center_of_mass(ds[, range_label])

Calculates the mean backscatter location [unit: m].

dispersion(ds[, range_label])

Calculates the inertia (I) [unit: m^-2].

evenness(ds[, range_label])

Calculates the equivalent area (EA) [unit: m].

Utilities

Utilities for calculating seawater acoustic properties.

Functions

calc_absorption(frequency[, temperature, ...])

Calculate sea water absorption in units [dB/m].

calc_sound_speed([temperature, salinity, ...])

Calculate sound speed in [m/s].

Visualization subpackage

Visualization module to quickly plot raw, Sv, and MVBS dataset.

NOTE: To use this subpackage. `Matplotlib` and `cmocean` package must be installed.

echopype.visualize.create_echogramdata]

Create an Echogram from an EchoData object or Sv and MVBS Dataset.

Parameters
  • data : EchoData or xr.Dataset

    Echodata or Xarray Dataset to be plotted

  • channel : str or list of str, optional

    The channel to be plotted. Otherwise all channels will be plotted.

  • frequency : int, float, or list of float or ints, optional

    The frequency to be plotted. If not specified, all frequency will be plotted.

  • get_range : bool, optional

    Flag as to whether range (echo_range) should be computed or not, by default it will just plot range_sample` as the yaxis.

    Note that for data that is “Sv” xarray dataset, get_range defaults to True.

  • range_kwargs : dict

    Keyword arguments dictionary for computing range (echo_range). Keys are env_params, waveform_mode, and encode_mode.

  • vertical_offset : int, float, xr.DataArray, or bool, optional

    Water level data array for platform water level correction. Note that auto addition of water level can be performed when data is an EchoData object by setting this argument to True. Currently because the water level information is not available as part of the Sv dataset, a warning is issued when vertical_offset=True in this case and no correction is performed. This behavior will change in the future when the default content of Sv dataset is updated to include this information.

  • **kwargs: optional

    Additional keyword arguments for xarray plot pcolormesh.

Notes

The EK80 echosounder can be configured to transmit either broadband (waveform_mode="BB") or narrowband (waveform_mode="CW") signals. When transmitting in broadband mode, the returned echoes are encoded as complex samples (encode_mode="complex"). When transmitting in narrowband mode, the returned echoes can be encoded either as complex samples (encode_mode="complex") or as power/angle combinations (encode_mode="power") in a format similar to those recorded by EK60 echosounders.