# 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

- 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: '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_file : str

  path to raw data file

- sonar_model : str

  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_path : str

  path to XML config file used by AZFP

- convert_params : dict

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

- storage_options : dict, 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_mb : int

  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] None**kwargs

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

Parameters

- converted_raw_path : str

  path to converted data file

- storage_options : dict

  options for cloud storage

- kwargs : dict

  optional keyword arguments to be passed into xr.open_dataset

Returns

- EchoData object

## Combine EchoData objects

echopype. combine_echodata echodata_list] None EchoData

Combines multiple `EchoData` objects into a single `EchoData` object.

Parameters

- echodata_list : list 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_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_echogram data]

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.