add_splitbeam_angle#
- echopype.consolidate.add_splitbeam_angle(source_Sv: Union[Dataset, str, Path], echodata: Union[EchoData, str, Path], waveform_mode: str, encode_mode: str, pulse_compression: bool = False, storage_options: dict = {}, to_disk: bool = True) Dataset #
Add split-beam (alongship/athwartship) angles into the Sv dataset. This function calculates the alongship/athwartship angle using data stored in the Sonar/Beam_groupX groups of an EchoData object.
In cases when angle data does not already exist or cannot be computed from the data, an error is issued and no angle variables are added to the dataset.
- Parameters
- source_Sv: xr.Dataset or str or pathlib.Path
The Sv Dataset or path to a file containing the Sv Dataset, to which the split-beam angles will be added
- echodata: EchoData or str or pathlib.Path
An
EchoData
object or path to a file containing theEchoData
object holding the raw data- waveform_mode{“CW”, “BB”}
Type of transmit waveform
"CW"
for narrowband transmission, returned echoes recorded either as complex or power/angle samples"BB"
for broadband transmission, returned echoes recorded as complex samples
- encode_mode{“complex”, “power”}
Type of encoded return echo data
"complex"
for complex samples"power"
for power/angle samples, only allowed when the echosounder is configured for narrowband transmission
- pulse_compression: bool, False
Whether pulse compression should be used (only valid for
waveform_mode="BB"
andencode_mode="complex"
)- storage_options: dict, default={}
Any additional parameters for the storage backend, corresponding to the path provided for
source_Sv
- to_disk: bool, default=True
If
False
,to_disk
with split-beam angles added will be returned.to_disk=True
is useful whensource_Sv
is a path and users only want to write the split-beam angle data to this path.
- Returns
- xr.Dataset or None
If
to_disk=False
, nothing will be returned. Ifto_disk=True
, either the input datasetsource_Sv
or a lazy-loaded Dataset (from the pathsource_Sv
) with split-beam angles added will be returned.
- Raises
- ValueError
If
echodata
has a sonar model that is not analogous to either EK60 or EK80- ValueError
If the input
source_Sv
does not have achannel
dimension- ValueError
If
source_Sv
does not have appropriate dimension lengths in comparison toechodata
data- ValueError
If the provided
waveform_mode
,encode_mode
, andpulse_compression
are not valid- NotImplementedError
If an unknown
beam_type
is encountered during the split-beam calculation
Notes
Split-beam angle data potentially exist for the Simrad EK60 or EK80 echosounders with split-beam transducers and configured to store angle data (along with power samples) or store raw complex samples.
In most cases where the type of samples collected by the echosounder (power/angle samples or complex samples) and the transmit waveform (broadband or narrowband) are identical across all channels, the channels existing in
source_Sv
and ` echodata` will be identical. If this is not the case, only angle data corresponding to channels existing insource_Sv
will be added.