Add simple plotting functionality

[lsetiawan]

Overview

This PR adds an initial simple plotting functionality by calling ep.visualize.create_echogram.

NOTE: This is still a draft, suggestions are highly welcomed and encouraged.

Example

Actions

• If user passes in EchoData, plot the backscatter_r in beam group.
• If user passes MVBS / Sv, then plot those directly.
• Ability to plot EK80
• Ability to plot EK60
• Ability to plot AZFP
• Ability to plot ADCP (Currently not supported at this moment).
• Add docstring to function
• Add actual plot comparison test? (Maybe future improvements, not sure how to do this at this moment).
• Add a custom EK500 colormap along with the cmocean colormaps.

Notes

There are still some quirks and improvements to add, and some questions to be discussed such as:

1. How to plot the EK80 quadrant dims?
2. Backscatter_r is not available in ADCP, at least the one on the test data. In this case, what to do?
3. How do I utilize the water_level to calibrate the range?
4. How to improve the ease of the function call?

[codecov-commenter]

Codecov Report

Merging #436 (fdc31e4) into dev (d996e28) will decrease coverage by 57.18%.
The diff coverage is 100.00%.

@@             Coverage Diff             @@
##              dev     #436       +/-   ##
===========================================
- Coverage   77.13%   19.94%   -57.19%     
===========================================
  Files          39       40        +1     
  Lines        3415     3420        +5     
===========================================
- Hits         2634      682     -1952     
- Misses        781     2738     +1957     

Flag	Coverage Δ
unittests	19.94% <100.00%> (-57.19%)	⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.

Impacted Files	Coverage Δ
echopype/__init__.py	100.00% <100.00%> (ø)
echopype/metrics/summary_statistics.py	0.00% <0.00%> (-96.43%)	⬇️
echopype/convert/set_groups_ek80.py	12.05% <0.00%> (-83.66%)	⬇️
echopype/convert/set_groups_ad2cp.py	16.66% <0.00%> (-82.23%)	⬇️
echopype/calibrate/calibrate_ek.py	12.19% <0.00%> (-80.14%)	⬇️
echopype/convert/set_groups_azfp.py	19.64% <0.00%> (-78.54%)	⬇️
echopype/convert/parse_azfp.py	14.46% <0.00%> (-76.73%)	⬇️
echopype/convert/set_groups_ek60.py	16.50% <0.00%> (-74.68%)	⬇️
echopype/preprocess/noise_est.py	22.85% <0.00%> (-71.43%)	⬇️
echopype/utils/io.py	13.23% <0.00%> (-71.33%)	⬇️
... and 21 more

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update d996e28...fdc31e4. Read the comment docs.

[lsetiawan]

@leewujung Do you know if there's a better file for me to develop the visualization with that's pretty? 😃

[emiliom]

TODO: Investigate what platform or sonar/beam metadata attribute exists or should be added that clearly specifies the "direction" the echosounder is oriented (eg, downward vs upward looking). This need came about in the context of the OOI EK60/80 sensor @lsetiawan is using in his plotting tests, which is upward looking. This functionality would allow the echogram plots of raw data to be automatically oriented correctly with a depth y axis.

Looking through the SONAR-netCDF4 convention, the Sonar/Beam beam_mode attribute is helpful, but not fully what's needed; its values can be "vertical", "horizontal" and "inspection". Platform variables involving orientation and coordinate system may be usable, too, but currently the convention uses a ship-based frame of reference.

[gavinmacaulay]

The upcoming version of SONAR-netCDF4 has a more complete orientation and coordinate system that allows for specifying absolute beam pointing directions - details here. It was designed for multi-beam bathymetric sonars and might be a bit complicated for just upward-looking echosounders, but was intended to be general enough for all purposes and does not assume a ship-based frame of reference (keep in mind that the platform is not necessary a vessel).

The beam_mode in version 1 of SONAR-netCDF4 is a label for the different groups of beams that fisheries omni-directional sonars have (e.g., a set of horizontal beams, a set of vertical beams, and spot beams - the word inspection comes from the usage in such sonars - a narrow beam for inspecting parts of a fish school)

[leewujung]

Great! please add EK500 colormap as one of the options. :)

[emiliom]

@gavinmacaulay thanks so much for chiming in to elaborate on the new coordinate system framework and the context of the beam_mode attribute! I'll look into the coordinate system description more closely.

[lsetiawan]

EK500 Example

Notes

With this improvement, when a user import echopype the ek500 colormap is available at ep.ek500 or ep.ek500_r.

[leewujung]

For quick visualization of EK80 complex data, we can plot the magnitude

np.abs(ed.beam.backscatter_r + 1j * ed.beam.backscatter_i)

of each quadrant separately.

Can have an option doing a coherent sum over all quadrants

(ed.beam.backscatter_r + 1j * ed.beam.backscatter_i).sum(dim="quadrant")

and then do the magnitude.

[leewujung]

@lsetiawan : thanks for the changes, they look great! I put in a couple small comments that should pretty easy to address.

Do you think you could add a test for the water_level options? With all the possibilities it seems a good idea to have a test to catch any potential hiccups.

[leewujung]

Hey @lsetiawan : Thanks for the changes. I found a couple bugs in the water_level tests and added a couple suggestions. Once they are fixed this should be good to go!

[leewujung]

@lsetiawan : thanks, the changes look great! I'll merge this after adding in some small notes to the create_echogram docstring due to the range vs depth stuff below.

One thing I noticed which we'll need to do something about (also requested in #259 ) is to include the addition of water_level in the Sv dataset (since right now even if users put in water_level=True if the input is an Sv dataset no water_level offset is added. A more accurate way to think about it is probably that we are actually plotting "depth" in the case when we have range_meters + water_level.

The more general description is that people are plotting the range offset from some platform. Let's discuss how that coordinate should be named... Hence I am wondering if water_level should be range_offset instead, so that it is more general.

Pinging @emiliom here since this is related to the whole convention and attribute conversation.

[leewujung]

To check how the EK500 colormap looks like (as in this previous comment), use matplotlib.colormaps["ep.ek500"].

From a recent deprecation warning:

The get_cmap function was deprecated in Matplotlib 3.7 and will be removed two minor releases later. Use matplotlib.colormaps[name] or matplotlib.colormaps.get_cmap(obj) instead.