Add/handle vertical (z) variables in Platform group, on echodata.update_platform

[emiliom]

Ensure that variables related to the vertical (z) coordinate are properly handled and populated in the EchoData update_platform method:

echopype/echopype/echodata/echodata.py

Lines 265 to 272 in d08f1f6

	def update_platform(
	self,
	extra_platform_data: xr.Dataset,
	time_dim="time",
	extra_platform_data_file_name=None,
	):
	"""
	Updates the `EchoData["Platform"]` group with additional external platform data.

This may involve adding an optional argument for the depth relative to the water level, or related variables. Reworking this function will also entail addressing the time dimension name problems mentioned in #740 and #1003.

The two depth-related variables in the Platform group, from the convention, are vertical_offset and water_level.

Related open issues that we will act on now are:

• Enhance update_platform to support more use cases and produce more consistent results #740 (see also the sample notebook I refer to, which I created)
• echodata.update_platform adds a water_level with incorrectly assigned time1 dimension #1003
• Add descriptions and a diagram to docs documenting vertical offsets (water level, etc) #1062
• Add option in consolidate.add_depth to use variables already in EchoData #790

Here are some relevant background discussions (issues) we've had previously. See also the associated PR's. These discussions include specific references to the SONAR-netCDF4 convention.

• Support for depth coordinates #259 (and follow ups, Add mechanism to convert echo_range to depth in calibrated datasets #578 and Change water_level name to range_offset and include it in the returned Dataset from compute_SV #579)
• Include water_level or range_offset in Sv dataset #516
• Add missing required variables in Platform groups #592
• Sonar orientation and coordinate system convention, implementation #517

[emiliom]

For completeness, there are three other position related Platform variables that have a z component: position_offset_z, MRU_offset_z and transducer_offset_z. They are all z offsets relative to the "Platform Coordinate System" (PCS) origin, which itself is arbitrary.

For a platform with a pressure sensor like a glider or a mooring, the depth (pressure) is actually equivalent to water_level + vertical_offset. The strategy here should probably be to set water_level vertical_offset to the pressure-sensor based depth and set vertical_offset water_level to 0 (or retain as nan?).

[emiliom]

The preview to the draft, glider-based echopype examples notebook provides a concrete example of depth and pressure data from a glider external file.

[emiliom]

(TODO) Another set of relevant variables is beam_direction_x/y/z, from Beam_groupX. They are mandatory (M), but AZFP has not been creating them. Their addition to AZFP is discussed in #1100 and will be in PR #1102.

beam_direction_x/y/z together define a unit vector "in the beam direction for each beam and ping, as per the sonar beam coordinate system."

The convention defines beam_direction_x/y/z as having dimensions (ping_time, beam). But in the use cases that echopype handles, we don't expect these variables to be time-varying. So, we have standardized to assigning only one dimension, channel.

(TODO) In the current examples we've seen for EK60 and EK80, they're being populated with values of zero. While this is read directly from a datagram, 0 for all 3 variables does not add up to a unit vector! We suspect that those 0 values may in reality represent no-data. But we don't know how to distinguish "0 as nan" from valid 0 values, except to check if all three values are 0; in that case, we should set the variables to nan.

[emiliom]

(TODO) Another set of relevant variables is beam_direction_x/y/z, from Beam_groupX. They are mandatory (M), but AZFP has not been creating them. Their addition to AZFP is discussed in #1100 and will be in PR #1102.

Completed in #1102

(TODO) In the current examples we've seen for EK60 and EK80, they're being populated with values of zero. While this is read directly from a datagram, 0 for all 3 variables does not add up to a unit vector! We suspect that those 0 values may in reality represent no-data. But we don't know how to distinguish "0 as nan" from valid 0 values, except to check if all three values are 0; in that case, we should set the variables to nan.

Completed in #1114

[emiliom]

This issue was an umbrella for related topics. It wasn't quite a tracking issue.

Most of the topics raised here have been addressed. Remaining ones are best tracked in the specific, narrower issues that are currently open. I'll close this issue now.