add_splitbeam_angle

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 the EchoData 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" and encode_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 when source_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. If to_disk=True, either the input dataset source_Sv or a lazy-loaded Dataset (from the path source_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 a channel dimension

ValueError

If source_Sv does not have appropriate dimension lengths in comparison to echodata data

ValueError

If the provided waveform_mode, encode_mode, and pulse_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 in source_Sv will be added.

Contents