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 being deprecated.

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_raw(raw_file: Optional[PathHint] = None, sonar_model: Optional[SonarModelsHint] = None, xml_path: Optional[PathHint] = None, convert_params: Optional[Dict[str, str]] = None, storage_options: Optional[Dict[str, str]] = None, offload_to_zarr: bool = False, max_zarr_mb: int = 100) → Optional[echopype.echodata.echodata.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

  • AD2CP: Nortek Signature series ADCP (tested with Signature 500 and Signature 1000)

xml_pathstr

path to XML config file used by AZFP

convert_paramsdict

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

storage_optionsdict

options for cloud storage

offload_to_zarr: bool

If True, variables with a large memory footprint will be written to a temporary zarr store.

max_zarr_mbint

maximum MB that each zarr chunk should hold, when offloading variables with a large memory footprint to a temporary zarr store

Returns
EchoData object

Notes

offload_to_zarr=True is only available for the following echosounders: EK60, ES70, EK80, ES80, EA640. Additionally, this feature is currently in beta.

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(echodatas: List[echopype.echodata.echodata.EchoData], combine_attrs='override') → echopype.echodata.echodata.EchoData#

Combines multiple EchoData objects into a single EchoData object.

Parameters
echodatas: List[EchoData]

The list of EchoData objects to be combined.

combine_attrs: { “override”, “drop”, “identical”, “no_conflicts”, “overwrite_conflicts” }

String indicating how to combine attrs of the EchoData objects being merged. This parameter matches the identically named xarray parameter (see https://xarray.pydata.org/en/latest/generated/xarray.combine_nested.html) with the exception of the “overwrite_conflicts” value.

  • “override”: Default. skip comparing and copy attrs from the first EchoData object to the result.

  • “drop”: empty attrs on returned EchoData object.

  • “identical”: all attrs must be the same on every object.

  • “no_conflicts”: attrs from all objects are combined, any that have the same name must also have the same value.

  • “overwrite_conflicts”: attrs from all EchoData objects are combined, attrs with conflicting keys will be overwritten by later EchoData objects.

Returns
EchoData

An EchoData object with all of the data from the input EchoData objects combined.

Raises
ValueError

If echodatas contains EchoData objects with different or None sonar_model values (i.e., all EchoData objects must have the same non-None sonar_model value).

ValueError

If EchoData objects have conflicting source file names.

Warns
UserWarning

If the sonar_model of the input EchoData objects is “EK60” and any EchoData objects have non-monotonically increasing ping_time, time1 or time2 values, the corresponding values in the output EchoData object will be increased starting at the timestamp where the reversal occurs such that all values in the output are monotonically increasing. Additionally, the original ping_time, time1 or time2 values will be stored in the Provenance group, although this behavior may change in future versions.

Warning

Changes in parameters between EchoData objects are not currently checked; however, they may raise an error in future versions.

Notes

  • EchoData objects are combined by combining their groups individually.

  • Attributes from all groups before the combination will be stored in the provenance group, although this behavior may change in future versions.

  • The source_file and converted_raw_path attributes will be copied from the first EchoData object in the given list, but this may change in future versions.

Examples

>>> ed1 = echopype.open_converted("file1.nc")
>>> ed2 = echopype.open_converted("file2.zarr")
>>> combined = echopype.combine_echodata([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.

preprocess#

Functions#

compute_MVBS(ds_Sv[, range_meter_bin, ...])

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

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.

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.

qc#

Functions#

coerce_increasing_time(ds[, time_name, ...])

Coerce a time coordinate to always flow forward.

exist_reversed_time(ds, time_name)

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

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_echogram(data: Union[echopype.echodata.echodata.EchoData, xarray.core.dataset.Dataset], channel: Optional[Union[str, List[str]]] = None, frequency: Optional[Union[str, List[str]]] = None, get_range: Optional[bool] = None, range_kwargs: dict = {}, water_level: Optional[Union[int, float, xarray.core.dataarray.DataArray, bool]] = None, **kwargs) → List[Union[xarray.plot.facetgrid.FacetGrid, matplotlib.collections.QuadMesh]]#

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

Parameters
dataEchoData or xr.Dataset

Echodata or Xarray Dataset to be plotted

channelstr or list of str, optional

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

frequencyint, float, or list of float or ints, optional

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

get_rangebool, 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_kwargsdict

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

water_levelint, 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 water_level=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.