frequency_differencing

echopype.mask.frequency_differencing(source_Sv: Dataset | str | Path, storage_options: dict | None = {}, freqABEq: str | None = None, chanABEq: str | None = None) → DataArray

Create a mask based on the differences of Sv values using a pair of frequencies. This method is often referred to as the “frequency-differencing” or “dB-differencing” method.

Parameters:

source_Sv: xr.Dataset or str or pathlib.Path

If a Dataset this value contains the Sv data to create a mask for, else it specifies the path to a zarr or netcdf file containing a Dataset. This input must correspond to a Dataset that has the coordinate channel and variables frequency_nominal and Sv.

storage_options: dict, optional

Any additional parameters for the storage backend, corresponding to the path provided for source_Sv

freqABEq: string, optional

The frequency differencing criteria. Only one of freqAB and chanAB should be provided, and not both.

chanAB: string, optional

The frequency differencing criteria in terms of channel names where channel names in the criteria are enclosed in double quotes. Only one of freqAB and chanAB should be provided, and not both.

Returns:

xr.DataArray

A DataArray containing the mask for the Sv data. Regions satisfying the thresholding criteria are filled with True, else the regions are filled with False.

Raises:

ValueError

If neither freqABEq or chanABEq are given

ValueError

If both freqABEq and chanABEq are given

TypeError

If any input is not of the correct type

ValueError

If either freqABEq or chanABEq are provided and the extracted freqAB or chanAB does not contain 2 distinct elements

ValueError

If freqABEq contains values that are not contained in frequency_nominal

ValueError

If chanABEq contains values that not contained in channel

ValueError

If operator is not one of the following: ">", "<", "<=", ">=", "=="

ValueError

If the path provided for source_Sv is not a valid path

ValueError

If freqABEq or chanABEq is provided and the Dataset produced by source_Sv does not contain the coordinate channel and variable frequency_nominal

Notes

This function computes the frequency differencing as follows: Sv_freqA - Sv_freqB operator diff. Thus, if operator = "<" and diff = "5" the following would be calculated: Sv_freqA - Sv_freqB < 5.

Examples

Compute frequency-differencing mask using a mock Dataset and channel selection:

>>> n = 5 # set the number of ping times and range samples
...
>>> # create mock Sv data
>>> Sv_da = xr.DataArray(data=np.stack([np.arange(n**2).reshape(n,n), np.identity(n)]),
...                      coords={"channel": ['chan1', 'chan2'],
...                              "ping_time": np.arange(n), "range_sample":np.arange(n)})
...
>>> # obtain mock frequency_nominal data
>>> freq_nom = xr.DataArray(data=np.array([1.0, 2.0]),
...                         coords={"channel": ['chan1', 'chan2']})
...
>>> # construct mock Sv Dataset
>>> Sv_ds = xr.Dataset(data_vars={"Sv": Sv_da, "frequency_nominal": freq_nom})
...
>>> # compute frequency-differencing mask using channel names
>>> echopype.mask.frequency_differencing(source_Sv=Sv_ds, storage_options={},
...                                      freqABEq=None, chanABEq = '"chan1" - "chan2">=10.0dB')
<xarray.DataArray 'mask' (ping_time: 5, range_sample: 5)>
array([[False, False, False, False, False],
       [False, False, False, False, False],
       [ True,  True,  True,  True,  True],
       [ True,  True,  True,  True,  True],
       [ True,  True,  True,  True,  True]])
Coordinates:
  * ping_time     (ping_time) int64 0 1 2 3 4
  * range_sample  (range_sample) int64 0 1 2 3 4