merge with user guide example

CHANGES.rst

@@ -899,7 +899,7 @@ Enhancements
   See :ref:`model.multidimensional-label`.
 * The :py:func:`~.api.plot.plot_spectra`  function now listens to
   events to update the figure automatically.
-  See :ref:`this example <plot_profiles_interactive-label>`.
+  See :ref:`this example <sphx_glr_auto_examples_region_of_interest_ExtractLineProfile.py>`.
 * Improve thread-based parallelism. Add ``max_workers`` argument to the
   :py:meth:`~.api.signals.BaseSignal.map` method, such that the user can directly
   control how many threads they launch.

doc/user_guide/visualisation.rst

@@ -1021,38 +1021,6 @@ and "overlap" styles:
   Plotting on existing matplotlib axes.
 
 
-.. _plot_profiles_interactive-label:
-
-Plotting profiles interactively
--------------------------------
-
-Spectra or line profile can be plotted interactively on the same figure using
-the :func:`~.api.plot.plot_spectra` function. For example, profiles
-obtained from different Signal2D using the :class:`~.roi.Line2DROI` ROI can
-be plotted interactively:
-
-.. code-block:: python
-
-    >>> import holospy as  # doctest: +SKIP
-    >>> im0 = holo.data.Fe_needle_reference_hologram() # doctest: +SKIP
-    >>> im1 = holo.data.Fe_needle_hologram() # doctest: +SKIP
-    >>> im0.plot() # doctest: +SKIP
-    >>> im1.plot() # doctest: +SKIP
-    >>> # Create the ROI
-    >>> line_profile = hs.roi.Line2DROI(400, 250, 220, 600) # doctest: +SKIP
-    >>> # Obtain the signals to plot by "slicing" the signals with the ROI
-    >>> line0 = line_profile.interactive(im0) # doctest: +SKIP
-    >>> line1 = line_profile.interactive(im1) # doctest: +SKIP
-    >>> # Plotting the profile on the same figure
-    >>> hs.plot.plot_spectra([line0, line1]) # doctest: +SKIP
-
-.. figure::  images/interactive_profiles.gif
-  :align:   center
-  :width:   1024
-
-  Plotting profiles from different images interactively.
-
-
 .. _plot.signals:
 
 Plotting several signals

examples/region_of_interest/ExtractLineProfile.py

@@ -1,55 +1,61 @@
+
 """
-Extract line profile from image
-===============================
+Extract line profile from image interactively
+=============================================
 
-Use a ``Line2DROI`` to interactively extract a line profile with a certain width
-from an image.
+Use a :py:class:`~.api.roi.Line2DROI` to interactively extract a line profile with
+a certain width from an image. Use :func:`~.api.plot.plot_spectra` to plot several
+line profiles on the same figure. Save a profile data as ``msa`` file.
 
 """
 
 #%%
-# Initialize image data as HyperSpy signal:
-import hyperspy.api as hs
-import scipy
-img = hs.signals.Signal2D(scipy.datasets.ascent())
+#.. figure::  interactive_profiles.gif
+#    :align:   center
+#    :width:   1024
+#
+#    Extracting line profiles and interactive plotting.
 
 #%%
-# Intialize Line-ROI from pixel (90,90) to pixel (200,250) of width 5.
-# You can also use calibrated axes units by providing floats instead of integers.
-line_roi = hs.roi.Line2DROI(90, 90, 200, 250, 5)
+# Initialize image data as HyperSpy signal:
+import hyperspy.api as hs
+import holospy as holo
+im0 = holo.data.Fe_needle_reference_hologram()
+im1 = holo.data.Fe_needle_hologram()
 
 #%%
-# Plot the image and display the ROI (creates new signal object):
-img.plot(cmap='viridis')
-roi1D = line_roi.interactive(img, color='yellow')
+# Intialize Line-ROI from position (400,250) to position (220,600) of width 5
+# in calibrated axes units (in the current example equal to the image pixels):
+line_roi = hs.roi.Line2DROI(400, 250, 220, 600, 5)
 
 #%%
-# You can drag and drop the ends of the ROI to adjust.
-# Print the (updated) parameters of the ROI:
-print('%.3f, %.3f, %.3f, %.3f, %.2f' % (line_roi.x1, line_roi.y1, line_roi.x2, line_roi.y2, line_roi.linewidth))
+# Plot the image and display the ROI (creates a new signal object). You can also
+# display the same ROI on a second image to make sure that a profile is well
+# placed on both images:
+im0.plot()
+roi1D = line_roi.interactive(im0, color='green')
+im1.plot()
+roi1D = line_roi.interactive(im1, color='green')
 
 #%%
-# You can also display the same ROI on a second image
-# (e.g. to make sure that a profile is well placed on both images).
-# In this example, we create a second image by differentiating the original image:
-img2 = img.diff(axis=-1)
-img2.plot()
-roi1D = line_roi.interactive(img2, color='green')
+# You can then drag and drop the ends of the ROI to adjust the placement.
+#
+# If you want to later update the ROI initialization with the modified parameters
+# you can print these:
+print(tuple(line_roi))
 
 #%%
-# Extract data along ROI as new signal:
+# Extract data along the ROI as new signal by "slicing" the signal and plot the
+# profile:
 profile = line_roi(img)
-profile
-
-#%%
-# Plot the profile:
 profile.plot()
 
 #%%
-# Extract data along the same ROI from the second image and plot both profiles:
+# Extract data along the same ROI from the second image and plot both profiles in
+# a single plot:
 profile2 = line_roi(img2)
 hs.plot.plot_spectra([profile, profile2])
-# Choose the third figure as gallery thumbnail:
+# Choose the fourth figure as gallery thumbnail:
 # sphinx_gallery_thumbnail_number = 4
 
 #%%