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