Implement plot span map

doc/reference/api.plot/index.rst

@@ -5,6 +5,7 @@
    hyperspy.api.plot.markers
    hyperspy.api.plot.plot_histograms
    hyperspy.api.plot.plot_images
+   hyperspy.api.plot.plot_roi_map
    hyperspy.api.plot.plot_signals
    hyperspy.api.plot.plot_spectra
 

doc/user_guide/region_of_interest.rst

@@ -223,3 +223,41 @@ Handily, we can pass a :py:class:`~.roi.RectangularROI` ROI instead.
     >>> tuple(roi)
     (2.0, 10.0, 0.0, 5.0)
     >>> im.align2D(roi=roi)
+
+
+Interactively Slicing Signal Dimensions
+---------------------------------------
+
+:func:`~.api.plot.plot_roi_map` is a function that allows you to
+interactively see the spatial variation of intensity in a Signal
+within a ROI of its signal axes.
+
+To allow selection of the signal ROIs, a plot of the mean signal over all
+spatial positions is generated. Interactive ROIs can then be adjusted to the
+desired regions within this plot.
+
+For each ROI, a plot reflecting how the intensity of signal within this ROI
+varies over the spatial dimensions of the Signal object is also plotted.
+
+For Signal objects with 1 signal dimension :py:class:`~.roi.SpanROI`\ s are used
+and for 2 signal dimensions, :py:class:`~.roi.RectangularROI`\ s are used.
+
+For example, below, for a hyperspectral map with 2 navigation dimensions and
+1 signal dimension i.e. a spectrum at each position in a 2D map,
+:py:class:`~.roi.SpanROI`\ s are used to select spectral regions of interest.
+For each spectral region of interest a plot is generated displaying the
+intensity within this region at each position in the map.
+
+.. code-block:: python
+
+    >>> import hyperpsy.api as hs
+    >>> from hyperspy.utils.plot import plot_roi_map
+    >>> sig = hs.load('mydata.sur')
+    >>> sig
+    <Signal1D, dimensions: (128, 128|1024)>
+    >>> plot_roi_map(sig, rois=2)
+
+
+.. image:: images/plot_roi_map_demo.gif
+  :width: 100%
+  :alt: Demo of plot_roi_map functionality.

hyperspy/drawing/_widgets/range.py

@@ -142,6 +142,12 @@
 
     def _set_span_extents(self, left, right):
         self.span.extents = (left, right)
+        try:
+            # For https://github.com/matplotlib/matplotlib/pull/27409
+            self.span._selection_completed = True
+        except AttributeError:
+            # Remove when minimum matplotlib is > 3.8.2
+            pass
         # update internal state range widget
         self._span_changed()
 

hyperspy/drawing/utils.py

@@ -35,6 +35,8 @@
 import matplotlib.pyplot as plt
 from rsciio.utils import rgb_tools
 
+
+import hyperspy.api as hs
 from hyperspy.defaults_parser import preferences
 from hyperspy.misc.utils import to_numpy
 
@@ -1698,3 +1700,196 @@ def picker_kwargs(value, kwargs=None):
         kwargs['picker'] = value
 
     return kwargs
+
+
+def _create_span_roi_group(sig_ax, N):
+    """
+    Creates a set of `N` of :py:class:`~.roi.SpanROI`\\ s that sit along axis at sensible positions.
+
+    Arguments
+    ---------
+    sig_ax: DataAxis
+        The axis over which the ROI will be placed
+    N: int
+        The number of ROIs
+    """
+    axis = sig_ax.axis
+    ax_range = axis[-1] - axis[0]
+    span_width = ax_range / (2 * N)
+
+    spans = []
+
+    for i in range(N):
+        # create a span that has a unique range
+        span = hs.roi.SpanROI(
+            i * span_width + axis[0], (i + 1) * span_width + axis[0]
+        )
+
+        spans.append(span)
+
+    return spans
+
+
+def _create_rect_roi_group(sig_wax, sig_hax, N):
+    """
+    Creates a set of `N` :py:class:`~roi.RectangularROI`\\ s that sit along `waxis` and `haxis` at sensible positions.
+
+    Arguments
+    ---------
+    sig_wax: DataAxis
+        The width axis over which the ROI will be placed
+    sig_hax: DataAxis
+        The height axis over which the ROI will be placed
+    N: int
+        The number of ROIs
+    """
+    waxis = sig_wax.axis
+    haxis = sig_hax.axis
+
+    w_range = waxis[-1] - waxis[0]
+    h_range = haxis[-1] - haxis[0]
+
+    span_w_width = w_range / (2 * N)
+    span_h_width = h_range / (2 * N)
+
+    rects = []
+
+    for i in range(N):
+        # create a span that has a unique range
+        rect = hs.roi.RectangularROI(
+            left=i * span_w_width + waxis[0],
+            top=i * span_h_width + haxis[0],
+            right=(i + 1) * span_w_width + waxis[0],
+            bottom=(i + 1) * span_h_width + haxis[0]
+        )
+
+        rects.append(rect)
+
+    return rects
+
+
+def plot_roi_map(signal, rois=1):
+    """
+    Plot a ROI map of ``signal``.
+
+    Uses ROIs to select a regions of ``signal``'s signal axes.
+
+    For each ROI, a plot is generated of the sum within this signal ROI
+    at each point in ``signal``'s navigator.
+
+    The ROI can be moved interactively and the corresponding plots will
+    update automatically.
+
+    Arguments
+    ---------
+    signal: :class:`~.api.signals.BaseSignal`
+        The signal to inspect.
+    rois: int, list of :class:`~.api.roi.SpanROI` or :class:`~.api.roi.RectangularROI`
+        ROIs that represent colour channels in map. Can either pass a list of
+        ROI objects, or an ``int``, ``N``, in which case ``N`` ROIs will
+        be created. Currently limited to a maximum of 3 ROIs.
+
+    Returns
+    -------
+    all_sum : :class:`~.api.signals.BaseSignal`
+        Sum over all positions of the signal, the 'navigator'on which the ROIs
+        are added.
+    rois : list of :class:`~.api.roi.SpanROI` or :class:`~.api.roi.RectangularROI`
+        The ROIs that slice signal
+    roi_signals : :class:`~.api.signals.BaseSignal`
+        Slices of ``signal`` according to each roi
+    roi_sums : :class:`~.api.signals.BaseSignal`
+        The summed ``roi_signals``
+
+    Examples
+    --------
+    3D hyperspectral data:
+
+    For 3D hyperspectral data, the rois used will be instances of
+    :class:`~.api.roi.SpanROI`. Therefore these ROIs can be used to select
+    particular spectral ranges, e.g. a particular peak.
+
+    The map generated for a given ROI is therefore the sum of this spectral
+    region at each point in the hyperspectral map. Therefore regions of the
+    sample where this peak is bright will be bright in this map.
+
+    4D STEM:
+
+    For 4D STEM data, the ROIs used will be instances of
+    :class:`~.api.roi.RectangularROI`. These ROIs can be used to select particular
+    regions in reciprocal space, e.g. a particular diffraction spot.
+
+    The map generated for a given ROI is therefore the intensity of this
+    region at each point in the scan. Therefore regions of the
+    scan where a particular spot is intense will appear bright.
+    """
+    sig_dims = len(signal.axes_manager.signal_axes)
+    nav_dims = len(signal.axes_manager.navigation_axes)
+
+    if sig_dims not in [1, 2] or nav_dims not in [1, 2]:
+        warnings.warn(("This function is only tested for signals with 1 or 2 "
+                       "signal and navigation dimensions, not"
+                       f" {sig_dims} signal and {nav_dims} navigation."))
+
+    if isinstance(rois, int):
+        if sig_dims == 1:
+            rois = _create_span_roi_group(
+                signal.axes_manager.signal_axes[0], rois
+            )
+        elif sig_dims == 2:
+            rois = _create_rect_roi_group(
+                *signal.axes_manager.signal_axes, rois
+            )
+        else:
+            raise ValueError(("Can only generate default ROIs for signals "
+                              f"with 1 or 2 signal dimensions, not {sig_dims}"
+                              ", try providing an explicit `rois` argument"))
+
+    if len(rois) > 3:
+        raise ValueError("Maximum number of spans is 3")
+
+    colors = ["red", "green", "blue"]
+    roi_signals = []
+    roi_sums = []
+
+    all_sum = signal.nansum()
+    all_sum.plot()
+
+    for i, roi in enumerate(rois):
+        color = colors[i]
+
+        # add it to the sum over all positions
+        roi.add_widget(all_sum, color=colors[i])
+
+        # create a signal that is the spectral slice of sig
+        roi_signal = hs.interactive(
+            roi,
+            signal=signal,
+            event=roi.events.changed,
+            axes=signal.axes_manager.signal_axes,
+        )
+        roi_signals.append(roi_signal)
+
+        # add up the roi sliced signals to one point per nav position
+        roi_sum = roi_signal.nansum(roi_signal.axes_manager.signal_axes)
+
+        # transpose shape to swap these points per nav into signal points
+        roi_sum = roi_sum.transpose(
+            signal_axes=roi_sum.axes_manager.navigation_dimension
+        )
+
+        roi_sums.append(roi_sum)
+
+        roi_sum.plot(cmap=f"{color.capitalize()}s")
+
+        # connect the span signal changing range to the value of span_sum
+        hs.interactive(
+            roi_signal.nansum,
+            event=roi_signal.axes_manager.events.any_axis_changed,
+            axis=roi_signal.axes_manager.signal_axes,
+            out=roi_sum,
+            recompute_out_event=None,
+        )
+
+    # return all ya bits for future messing around.
+    return all_sum, rois, roi_signals, roi_sums

hyperspy/external/matplotlib/widgets.py

@@ -510,7 +510,7 @@ def _press(self, event):
             # visibility to False and extents to (v, v)
             # update will be called when setting the extents
             self.visible = False
-            self.extents = v, v
+            self._set_extents((v, v))
             # We need to set the visibility back, so the span selector will be
             # drawn when necessary (span width > 0)
             self.visible = True
@@ -609,7 +609,7 @@ def _onmove(self, event):
             if vmin > vmax:
                 vmin, vmax = vmax, vmin
 
-        self.extents = vmin, vmax
+        self._set_extents((vmin, vmax))
 
         if self.onmove_callback is not None:
             self.onmove_callback(vmin, vmax)
@@ -679,6 +679,10 @@ def extents(self):
 
     @extents.setter
     def extents(self, extents):
+        self._set_extents(extents)
+        self._selection_completed = True
+
+    def _set_extents(self, extents):
         # Update displayed shape
         if self.snap_values is not None:
             extents = tuple(self._snap(extents, self.snap_values))

hyperspy/tests/test_import.py

@@ -195,8 +195,9 @@ def test_dir_utils_plot():
         'markers',
         'plot_histograms',
         'plot_images',
+        'plot_roi_map',
         'plot_signals',
-        'plot_spectra',
+        'plot_spectra'
         ]