Syntax for plotting different types of echograms and linkage to associated widgets

[leewujung]

Note 2023-07-26 See the 2nd comment text for update; this initial comment is preserved here just as a reference

---

Right now to plot a multi-frequency echogram from a dataset (ds_MVBS), one can use ds_MVBS.eshader.echogram_multiple_frequency, with the layout argument being "single_frequency", "multiple_frequency", or "composite". But then there is another method echogram_single_frequency that plots a single frequency echogram, and only this one is linked to the Sv slider and colormap selector.

Based on our discussion notes, I think we can consolidate these to use a single call:

ds_MVBS.eshader.echogram(layout, channel)

• when layout is multiple_frequency, the current 3x1 in a column type of echograms from all channels are shown (this is the same as the current behavior)
• when layout is single_frequency, a single echogram is shown, along with tabs of all channels on the top (this part is the same as the current behavior); the change would be:
  • if channel is given, then the echogram corresponding to the specified channel is shown (i.e., the channel argument specifies the starting channel)
  • if channel is not given, then the echogram of the first channel is shown (as in the current behavior)
  • Note that the above would eliminate the need for a channel selector, since that functionality is already provided by the tabs.
• when layout is composite, a tricolor echogram is shown (current behavior)

Another set of changes would be to link the associated widgets Sv_range_slider, cmap_selector (note the names) with all types of echograms

• for layout=single_frequency, have the Sv_range_slider and cmap_selector linked to all of the echogram tabs
• for layout=multiple_frequency
  • if the Sv range slider is initiated with slider_widget = echogram.Sv_range_slider(channel="SOME_CHANNEL"), then the generated Sv slider controls the Sv range of the channel SOME_CHANNEL only. This allows users to generate different Sv range sliders for different channels so that they can control them individually
  • if the Sv range slider is initiated without a channel argument (slider_widget = echogram.Sv_range_slider()), then the generated Sv range slider will control the Sv range of all channels

Let me know if the above makes sense. Thanks!

[leewujung]

Update on 2023-07-26:

• We will NOT be using tabs for layout="single_frequency" for now due to issues with the selection box across multiple tabs
• Simplify the Sv range slider we get from multiple frequency echogram (see below examples)
• Simplify syntax to just control what we plot using a list of channels

Regular echogram + slider

Tricolor (composite) echogram

[valentina-s]

@leewujung Based on a follow-up discussion with @ldr426, turned out the proposed approach would not work to dynamically update the widgets after that, one need to proceed as follows if they want to both to set parameters and dynamically link widgets after that:

# we do not assign this to an object 
# this sets the channel in the Echoshader object
ds.eshader.echogram(channel=["38kHz"])
ds.eshader.Sv_range_slider(["38kHz"])
# pass the functions to panel: this allows for dynamic updates
panel.row(ds.eshader.echogram, ds.eshader.Sv_range_slider)

If we just run as discussed

echogram_widget = ds.eshader.echogram(channel=["38kHz"])
Sv_range_slider_widget = ds.eshader.Sv_range_slider(["38kHz"])
# pass the functions to panel: this allows for dynamic updates
panel.row(echogram_widget, Sv_range_slider_widget)

one would not be able to update the plots dynamically, as the widgets are static objects.

With the first scenario, we worry that even if we write in the documentation that they should pass the function, they will set the function call to an object and will pass it to panel and will be puzzled why it is not updating.

An alternative to mitigate this problem is to actually make echogram return a function instead of the holoviews object. To the user that might be a bit invisible.

# echogram_widget is a function
echogram_widget = ds.eshader.echogram(channel=["38kHz"])

# the function then can be passed to panel
panel.row(echogram_widget)

panel will accept the function and the echogram will plot.

The function can be created by some pseudo code like that

def echogram(MVBS_ds, ch, cmap):
    return(hv.Image(MVBS_ds, ch, map))

channel_select = panel.select()
cmap_input = panel.Input()

echogram_bind  = panel.bind(echogram, ch=channel_select, cmap=cmap_select)

def eg(MVBS_Sv, ch, cmap, echogram_bind):
    ch_sel.value = ch
    cmap_sel.value = cmap
    return (echogram_bind)

Of course, if the user just runs echogram_widget in a cell it will show that this is a function. To display the plot, one needs to run echogram_widget().

Yet another alternative is that they always create a changing widget if they want to change a value of the parameters, but this will result in too many widgets that we may not want to update.

@ldr426 can you verify that the above is correct.

[ldr426]

@valentina-s Thanks for illustration. yes, that is the situation is

[leewujung]

Would something like the following work?

from echogram import plot_echogram
from widgets import create_range_slider

@xarray.register_dataset_accessor("eshader")
class Echoshader:
   def __init__():   
      # self.ds_MVBS points the accessed xr dataset

      # initiate Sv range slider for all channels so we always have them for potential linkage
      self.Sv_range_slider = create_range_slider(...)
      return self.Sv_range_slider  # probably needs to be a list with elements being each channel

   def Sv_range_slider(CHANNEL_SPECIFICTION, ...):
      # something to select channel from self.Sv_range_slider
      # return channel slider with correct channel selection

   @pn.depends(Sv_range=self.Sv_range_slider)
   def echogram(CHANNEL_SPECIFICTION, ...):
      # something to select vmin and vmax of the slider of the correct channel
      return plot_echogram(..., vmin=..., vmax=...)

The plot_echogram function content could be very similar to what you have in https://github.com/OSOceanAcoustics/echoshader/blob/3f075a115ed20e74201d4d27023a776d627cf4a3/echoshader/new_version/echogram.py#L213C11-L213C11

This is not completely thought out (for example I did not completely specify the mechanism to make sure the returned slider and echogram works on the same channel) but I just took a quick look at this page to see if how things could be linked, so this is my pattern matching result.

[ldr426]

@leewujung Hey wu-jung, Thanks for the suggestion. This is what I used similarly in my latest commit. But this is not the issue @valentina-s trying to explain. I mentioned it in the thread previously.

[ldr426]

New designing pattern has been built in https://github.com/OSOceanAcoustics/echoshader/pull/131