rename and deprecate Spectral Extraction plugins in specviz2d and cubeviz (#3691)

* rename and deprecate Spectral Extraction plugins in specviz2d and cubeviz to Spectral Extraction 2D and Cube Spectral Extraction

* review comments

Author: cshanahan1

CHANGES.rst

@@ -33,13 +33,16 @@ New Features
 
 - Allow custom resolutions when exporting viewers to png or mp4. [#3478]
 
+
 Cubeviz
 ^^^^^^^
 
 - Ability to ingest and export ``SkyRegion`` objects. [#3502]
 
 - Add sonified layer for each cube created by the Sonify Data plugin. [#3430, #3660]
 
+- Renamed ``Spectral Extraction`` plugin to ``3D Spectral Extraction``. [#3691]
+
 Imviz
 ^^^^^
 
@@ -76,6 +79,8 @@ Specviz2d
 
 - New plugin to vizualize the cross-dispersion profile [#3552]
 
+- Renamed ``Spectral Extraction`` plugin to ``2D Spectral Extraction``. [#3691]
+
 API Changes
 -----------
 

docs/cubeviz/export_data.rst

@@ -33,7 +33,7 @@ To extract all the subsets created in the viewers, call the Subset Tools plugin:
         Documentation on how to export data from the ``spectrum-viewer``.
 
 The following line of code can be used to extract 1D spectra.
-To use a ``function`` other than sum, use the :ref:`Spectral Extraction <spectral-extraction>` plugin
+To use a ``function`` other than sum, use the :ref:`3D Spectral Extraction <spectral-extraction>` plugin
 first to create a 1D spectrum and then refer to it by label in ``get_data``.
 
 .. code-block:: python

docs/cubeviz/plugins.rst

@@ -287,13 +287,13 @@ spectral region of interest.
 
 .. _spectral-extraction:
 
-Spectral Extraction
-===================
+3D Spectral Extraction
+======================
 
 .. image:: ../img/cubeviz_spectral_extraction.png
 
 
-The Spectral Extraction plugin produces a 1D spectrum from a spectral
+The 3D Spectral Extraction plugin produces a 1D spectrum from a spectral
 cube. The 1D spectrum can be computed via the sum, mean, minimum, or
 maximum of the spatial dimensions in the spectral cube. Select an
 extraction operation from the :guilabel:`Function` dropdown, and
@@ -305,6 +305,12 @@ By default, if a mask was loaded with the cube, it will be applied to the
 cube when extracting in addition to any subsets chosen as an aperture. This
 is not currently done for Data Quality arrays, e.g. the DQ extension in JWST files.
 
+To interact with the plugin via the API in a notebook, access the plugin object via:
+
+.. code-block:: python
+
+  sp_ext = cubeviz.plugins['3D Spectral Extraction']
+
 If using a simple subset (currently only works for a circular subset applied to data
 with spatial axis units in wavelength) for the spatial aperture, an option to
 make the aperture wavelength dependent will appear. If checked, this will

docs/specviz2d/plugins.rst

@@ -48,17 +48,17 @@ Markers
 
 .. _specviz2d-spectral-extraction:
 
-Spectral Extraction
-===================
+2D Spectral Extraction
+======================
 
-The Spectral Extraction plugin exposes `specreduce <https://specreduce.readthedocs.io>`_
+The 2D Spectral Extraction plugin exposes `specreduce <https://specreduce.readthedocs.io>`_
 methods for tracing, background subtraction, and spectral extraction from 2D spectra.
 
 To interact with the plugin via the API in a notebook, access the plugin object via:
 
 .. code-block:: python
 
-  sp_ext = specviz2d.plugins['Spectral Extraction']
+  sp_ext = specviz2d.plugins['2D Spectral Extraction']
 
 
 Trace
@@ -100,7 +100,7 @@ Trace parameters can be set from the notebook by accessing the plugin.
     sp_ext.trace_peak_method = 'Gaussian'
 
 To export and access the :py:class:`specreduce.tracing.Trace` object defined in the plugin,
-call :py:meth:`~jdaviz.configs.specviz2d.plugins.spectral_extraction.spectral_extraction.SpectralExtraction.export_trace`:
+call :py:meth:`~jdaviz.configs.specviz2d.plugins.spectral_extraction.spectral_extraction.SpectralExtraction2D.export_trace`:
 
 .. code-block:: python
 
@@ -115,7 +115,7 @@ via ``load``:
     specviz2d.load(my_trace, data_label="my trace")
 
 or directly into the plugin
-via :py:meth:`~jdaviz.configs.specviz2d.plugins.spectral_extraction.spectral_extraction.SpectralExtraction.import_trace`
+via :py:meth:`~jdaviz.configs.specviz2d.plugins.spectral_extraction.spectral_extraction.SpectralExtraction2D.import_trace`
 
 .. code-block:: python
 
@@ -154,21 +154,21 @@ Background parameters can be set from the notebook by accessing the plugin.
     sp_ext.bg_width = 6
 
 To export and access the :py:class:`specreduce.background.Background` object defined in the plugin,
-call :py:meth:`~jdaviz.configs.specviz2d.plugins.spectral_extraction.spectral_extraction.SpectralExtraction.export_bg`:
+call :py:meth:`~jdaviz.configs.specviz2d.plugins.spectral_extraction.spectral_extraction.SpectralExtraction2D.export_bg`:
 
 .. code-block:: python
 
   bg = sp_ext.export_bg()
 
 To access the background image, background spectrum, or background-subtracted image as a
 :class:`~specutils.Spectrum` object,
-call :py:meth:`~jdaviz.configs.specviz2d.plugins.spectral_extraction.spectral_extraction.SpectralExtraction.export_bg_img`,
-:py:meth:`~jdaviz.configs.specviz2d.plugins.spectral_extraction.spectral_extraction.SpectralExtraction.export_bg_spectrum`,
-or :py:meth:`~jdaviz.configs.specviz2d.plugins.spectral_extraction.spectral_extraction.SpectralExtraction.export_bg_sub`, respectively.
+call :py:meth:`~jdaviz.configs.specviz2d.plugins.spectral_extraction.spectral_extraction.SpectralExtraction2D.export_bg_img`,
+:py:meth:`~jdaviz.configs.specviz2d.plugins.spectral_extraction.spectral_extraction.SpectralExtraction2D.export_bg_spectrum`,
+or :py:meth:`~jdaviz.configs.specviz2d.plugins.spectral_extraction.spectral_extraction.SpectralExtraction2D.export_bg_sub`, respectively.
 
 To import the parameters from a :py:class:`specreduce.background.Background` object into the plugin,
 whether it's new or was exported and modified in the notebook,
-call :py:meth:`~jdaviz.configs.specviz2d.plugins.spectral_extraction.spectral_extraction.SpectralExtraction.import_bg`:
+call :py:meth:`~jdaviz.configs.specviz2d.plugins.spectral_extraction.spectral_extraction.SpectralExtraction2D.import_bg`:
 
 .. code-block:: python
 
@@ -205,21 +205,21 @@ Extraction parameters can be set from the notebook by accessing the plugin.
     sp_ext.ext_width = 8
 
 To export and access
-the :py:class:`~jdaviz.configs.specviz2d.plugins.spectral_extraction.spectral_extraction.SpectralExtraction` object defined
+the :py:class:`~jdaviz.configs.specviz2d.plugins.spectral_extraction.spectral_extraction.SpectralExtraction2D` object defined
 in the plugin,
-call :py:meth:`~jdaviz.configs.specviz2d.plugins.spectral_extraction.spectral_extraction.SpectralExtraction.export_extract`:
+call :py:meth:`~jdaviz.configs.specviz2d.plugins.spectral_extraction.spectral_extraction.SpectralExtraction2D.export_extract`:
 
 .. code-block:: python
 
   ext = sp_ext.export_extract()
 
 To access the extracted spectrum as a :class:`~specutils.Spectrum` object,
-call :py:meth:`~jdaviz.configs.specviz2d.plugins.spectral_extraction.spectral_extraction.SpectralExtraction.export_extract_spectrum`.
+call :py:meth:`~jdaviz.configs.specviz2d.plugins.spectral_extraction.spectral_extraction.SpectralExtraction2D.export_extract_spectrum`.
 
 To import the parameters from
-a :py:class:`~jdaviz.configs.specviz2d.plugins.spectral_extraction.spectral_extraction.SpectralExtraction` object
+a :py:class:`~jdaviz.configs.specviz2d.plugins.spectral_extraction.spectral_extraction.SpectralExtraction2D` object
 (either a new object, or an exported one modified in the notebook) into the plugin,
-call :py:meth:`~jdaviz.configs.specviz2d.plugins.spectral_extraction.spectral_extraction.SpectralExtraction.import_extract`:
+call :py:meth:`~jdaviz.configs.specviz2d.plugins.spectral_extraction.spectral_extraction.SpectralExtraction2D.import_extract`:
 
 .. code-block:: python
 

jdaviz/app.py

@@ -824,7 +824,7 @@ def _link_new_data(self, reference_data=None, data_to_be_linked=None):
             dc.add_link(LinkSame(ref_wavelength_component, linked_wavelength_component))
             return
 
-        elif (linked_data.meta.get('Plugin', None) == 'Spectral Extraction' or
+        elif (linked_data.meta.get('Plugin', None) == '3D Spectral Extraction' or
                 (linked_data.meta.get('Plugin', None) == ('Gaussian Smooth') and
                  linked_data.ndim < 3 and  # Cube linking requires special logic. See below
                  ref_data.ndim < 3)

jdaviz/configs/cubeviz/cubeviz.yaml

@@ -25,7 +25,7 @@ tray:
   - g-markers
   - cube-slice
   - g-unit-conversion
-  - cubeviz-spectral-extraction
+  - spectral-extraction-3d
   - g-gaussian-smooth
   - g-collapse
   - g-model-fitting

jdaviz/configs/cubeviz/helper.py

@@ -88,23 +88,23 @@ def load_data(self, data, data_label=None, override_cube_limit=False, **kwargs):
 
         super().load_data(data, parser_reference="cubeviz-data-parser", **kwargs)
 
-        if 'Spectral Extraction' not in self.plugins:  # pragma: no cover
+        if '3D Spectral Extraction' not in self.plugins:  # pragma: no cover
             msg = SnackbarMessage(
-                "Automatic spectral extraction requires the Spectral Extraction plugin to be enabled",  # noqa
+                "Automatic spectral extraction requires the 3D Spectral Extraction plugin to be enabled",  # noqa
                 color='error', sender=self, timeout=10000)
             self.app.hub.broadcast(msg)
         else:
             try:
-                self.plugins['Spectral Extraction']._obj._extract_in_new_instance(auto_update=False, add_data=True)  # noqa
+                self.plugins['3D Spectral Extraction']._obj._extract_in_new_instance(auto_update=False, add_data=True)  # noqa
             except Exception:
                 msg = SnackbarMessage(
                     "Automatic spectrum extraction for the entire cube failed."
-                    " See the spectral extraction plugin to perform a custom extraction",
+                    " See the 3D Spectral Extraction plugin to perform a custom extraction",
                     color='error', sender=self, timeout=10000)
             else:
                 msg = SnackbarMessage(
                     "The extracted 1D spectrum was generated automatically for the entire cube."
-                    " See the spectral extraction plugin for details or to"
+                    " See the 3D Spectral Extraction plugin for details or to"
                     " perform a custom extraction.",
                     color='warning', sender=self, timeout=10000)
             self.app.hub.broadcast(msg)
@@ -137,22 +137,24 @@ def specviz(self):
     def get_data(self, data_label=None, spatial_subset=None, spectral_subset=None,
                  cls=None, use_display_units=False):
         """
-        Returns data with name equal to ``data_label`` of type ``cls`` with subsets applied from
-        ``spectral_subset``, if applicable.
+        Returns data with name equal to ``data_label`` of type ``cls`` with
+        subsets applied from ``spectral_subset``, if applicable.
 
         Parameters
         ----------
         data_label : str, optional
             Provide a label to retrieve a specific data set from data_collection.
         spatial_subset : str, optional
-            Spatial subset applied to data.  Only applicable if ``data_label`` points to a cube or
-            image.  To extract a spectrum from a cube, use the spectral extraction plugin instead.
+            Spatial subset applied to data.  Only applicable if ``data_label``
+            points to a cube or image.  To extract a spectrum from a cube, use
+            the 3D Spectral Extraction plugin instead.
         spectral_subset : str, optional
             Spectral subset applied to data.
         cls : `~specutils.Spectrum`, `~astropy.nddata.CCDData`, optional
             The type that data will be returned as.
         use_display_units : bool, optional
-            Specify whether the returned data is in native units or the current display units.
+            Specify whether the returned data is in native units or the current
+            display units.
 
         Returns
         -------

jdaviz/configs/cubeviz/plugins/spectral_extraction/spectral_extraction.py

@@ -28,16 +28,17 @@
 from jdaviz.configs.cubeviz.plugins.viewers import WithSliceIndicator
 
 
-__all__ = ['SpectralExtraction']
+__all__ = ['SpectralExtraction3D']
 
 
 @tray_registry(
-    'cubeviz-spectral-extraction', label="Spectral Extraction"
+    'spectral-extraction-3d', label="3D Spectral Extraction"
 )
-class SpectralExtraction(PluginTemplateMixin, ApertureSubsetSelectMixin,
-                         DatasetSelectMixin, AddResultsMixin):
+class SpectralExtraction3D(PluginTemplateMixin, ApertureSubsetSelectMixin,
+                           DatasetSelectMixin, AddResultsMixin):
     """
-    See the :ref:`Spectral Extraction Plugin Documentation <spectral-extraction>` for more details.
+    See the :ref:`3D Spectral Extraction Plugin Documentation <spectral-extraction>`
+    for more details.
 
     Only the following attributes and methods are available through the
     :ref:`public plugin API <plugin-apis>`:
@@ -279,8 +280,8 @@ def _aperture_items_changed(self, msg):
 
     def _extract_in_new_instance(self, dataset=None, function='Sum', subset_lbl=None,
                                  auto_update=False, add_data=False):
-        # create a new instance of the Spectral Extraction plugin (to not affect the instance in
-        # the tray) and extract the entire cube with defaults.
+        # create a new instance of the 3D Spectral Extraction plugin (to not
+        # affect the instance in the tray) and extract the entire cube with defaults.
         plg = self.new()
         plg.dataset.selected = self.dataset.selected if dataset is None else dataset
         if subset_lbl is not None:

jdaviz/configs/cubeviz/plugins/spectral_extraction/spectral_extraction.vue

@@ -1,7 +1,7 @@
 <template>
   <j-tray-plugin
     :config="config"
-    :plugin_key="plugin_key || 'Spectral Extraction'"
+    :plugin_key="plugin_key || '3D Spectral Extraction'"
     :api_hints_enabled.sync="api_hints_enabled"
     :description="docs_description"
     :link="docs_link || 'https://jdaviz.readthedocs.io/en/'+vdocs+'/'+config+'/plugins.html#spectral-extraction'"