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: https://github.com/OSOceanAcoustics/echopype/blob/d08f1f6e460732497fa689d49b4da4d946137cd3/echopype/echodata/echodata.py#L265-L272

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:

• 740 (see also the sample notebook I refer to, which I created)

• 1003

• 1062

• 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.

• 259 (and follow ups, #578 and #579)

• 516

• 592

• 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.