API reference

API reference#

API components that most users will interact with.

Attention

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
Open raw and converted files
Combine EchoData objects
Data processing subpackages
Utilities
Visualization subpackage

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_raw(raw_file: PathHint, sonar_model: SonarModelsHint, xml_path: PathHint | None = None, include_bot: bool = False, include_idx: bool = False, convert_params: Dict[str, str] | None = None, storage_options: Dict[str, str] | None = None, use_swap: bool | Literal['auto'] = False, max_chunk_size: str = '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.

Parameters:

raw_filestr

path to raw data file

sonar_modelstr

model of the sonar instrument

EK60: Kongsberg Simrad EK60 echosounder
ES70: Kongsberg Simrad ES70 echosounder
EK80: Kongsberg Simrad EK80 echosounder
EA640: Kongsberg EA640 echosounder
AZFP: ASL Environmental Sciences AZFP echosounder
AZFP6: ASL Environmental Sciences AZFP echosounder (ULS6)
AD2CP: Nortek Signature series ADCP (tested with Signature 500 and Signature 1000)

xml_pathstr

path to XML config file used by AZFP

include_botbool, default False

Include bottom depth file in parsing. Only used by EK60/EK80.

include_indexbool, default False

Include index file in parsing. Only used by EK60/EK80.

convert_paramsdict

parameters (metadata) that may not exist in the raw file and need to be added to the converted file

storage_optionsdict, optional

options for cloud storage

use_swap: bool or “auto”, default False

Flag to use disk swap in case of a large memory footprint. When set to True (or when set to “auto” and large memory footprint is needed, this function will create a temporary zarr store at the operating system’s temporary directory.

max_mbint

The maximum data chunk size in Megabytes (MB), when offloading variables with a large memory footprint to a temporary zarr store

Returns:

EchoData object

Raises:

ValueError: If sonar_model is None or sonar_model given is unsupported.
FileNotFoundError: If raw_file is None.
TypeError: If raw_file input is neither str or pathlib.Path type.

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_converted(converted_raw_path: PathHint, storage_options: Dict[str, str] = None, **kwargs)#

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

Parameters:

converted_raw_pathstr: path to converted data file
storage_optionsdict: options for cloud storage
kwargsdict: optional keyword arguments to be passed into xr.open_dataset

Returns:

EchoData object

Combine EchoData objects#

echopype.combine_echodata(echodata_list: List[EchoData] = None, channel_selection: List | Dict[str, list] | None = None) → EchoData#

Combines multiple EchoData objects into a single EchoData object.

Parameters:

echodata_listlist of EchoData object

The list of EchoData objects to be combined

channel_selection: list of str or dict, optional

Specifies what channels should be selected for an EchoData group with a channel dimension (before combination).

if a list is provided, then each EchoData group with a channel dimension

will only contain the channels in the provided list - if a dictionary is provided, the dictionary should have keys specifying only beam groups (e.g. “Sonar/Beam_group1”) and values as a list of channel names to select within that beam group. The rest of the EchoData groups with a channel dimension will have their selected channels chosen automatically.

Returns:

EchoData: A lazy loaded EchoData object, with all data from the input EchoData objects combined.

Raises:

ValueError

If the provided zarr path does not point to a zarr file

TypeError

If a list of EchoData objects are not provided

ValueError

If any EchoData object’s sonar_model is None

ValueError

If any EchoData object does not have a file path

ValueError

If the provided EchoData objects have the same filenames

RuntimeError

If the first time value of each EchoData group is not less than the first time value of the subsequent corresponding EchoData group, with respect to the order in echodata_list

RuntimeError

If the same EchoData groups in echodata_list do not have the same number of channels and the same name for each of these channels.

RuntimeError

If any of the following attribute checks are not met amongst the combined EchoData groups:

the keys are not the same
the values are not identical
the keys date_created or conversion_time do not have the same types

RuntimeError

If any EchoData group has a channel dimension value with a duplicate value.

RuntimeError

If channel_selection=None and the channel dimensions are not the same across the same group under each object in echodata_list.

NotImplementedError

If channel_selection is a list and the listed channels are not contained in the EchoData group across all objects in echodata_list.

Notes

EchoData objects are combined by appending their groups individually.
All attributes (besides attributes whose values are arrays) from all groups before the combination will be stored in the Provenance group.

Examples

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_background_noise`(ds_Sv, ping_num, ...)	Estimate background noise by computing mean calibrated power of a collection of pings.
`mask_attenuated_signal`(ds_Sv[, ...])	Locate attenuated signals and create an attenuated signal mask.
`mask_impulse_noise`(ds_Sv[, depth_bin, ...])	Locate and create a mask for impulse noise using a ping-wise two-sided comparison.
`mask_transient_noise`(ds_Sv[, func, ...])	Locate and create a mask for transient noise using a pooling comparison.
`remove_background_noise`(ds_Sv, ping_num, ...)	Remove noise by using estimates of background noise from mean calibrated power of a collection of pings.
`detect_transient`(ds, method, params)	Dispatch transient-noise detection to a chosen method and return a boolean mask.

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[, echodata, depth_offset, ...])	Create a depth data variable based on data in Sv dataset, Echodata object, and/or user input depth offset and tilt data.
`add_location`(ds, echodata[, datagram_type, ...])	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`.
`detect_seafloor`(ds, method, params)	Dispatch seafloor detection to a chosen method and return a 1-D bottom line.
`detect_shoal`(ds, method, params)	Detect shoals using the selected method and return a 2D boolean mask.
`regrid_mask`(mask_da, range_da[, range_bin, ...])	Regrid mask through downsampling via a logical AND operation.

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

API reference

Contents

API reference#

EchoData class#

Classes#

Open raw and converted files#

Combine EchoData objects#

Data processing subpackages#

calibrate#

Functions#

clean#

Functions#

commongrid#

Functions#

consolidate#

Functions#

qc#

Functions#

mask#

Functions#

metrics#

Functions#

Utilities#

Functions#

Visualization subpackage#