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.
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.
Any additional parameters for the storage backend, corresponding to the
path provided for source_Sv
The frequency differencing criteria.
Only one of freqAB and chanAB should be provided, and not both.
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.
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.
If neither freqABEq or chanABEq are given
If both freqABEq and chanABEq are given
If any input is not of the correct type
If either freqABEq or chanABEq are provided and the extracted
freqAB or chanAB does not contain 2 distinct elements
If freqABEq contains values that are not contained in frequency_nominal
If chanABEq contains values that not contained in channel
If operator is not one of the following: ">", "<", "<=", ">=", "=="
If the path provided for source_Sv is not a valid path
If freqABEq or chanABEq is provided and the Dataset produced by source_Sv
does not contain the coordinate channel and variable frequency_nominal
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.
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=mock_Sv_ds, storage_options={},
... freqABEq=None, chanABEq = '"chan1" - "chan2">=10.0')
<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