Docs specviz (#2727)

* Initial edits to specviz display docs * Add more API calls * Updates to plugin docs and screenshots * Add API calls for model fitting and updated screenshots * More API examples * More API examples * Update path to plugin image for imviz * Delete old imviz plugin image * Update docs/specviz/plugins.rst Fix typo Co-authored-by: Ricky O'Steen <[email protected]> * Update docs/specviz/plugins.rst Take suggestion from review Co-authored-by: Ricky O'Steen <[email protected]> --------- Co-authored-by: Camilla Pacifici <[email protected]> Co-authored-by: Ricky O'Steen <[email protected]>
spacetelescope · Feb 29, 2024 · 0e0a3b7 · 0e0a3b7
1 parent c8d6353
commit 0e0a3b7
Show file tree

Hide file tree

Showing 10 changed files with 119 additions and 26 deletions.
diff --git a/docs/img/line_lists.png b/docs/img/line_lists.png
diff --git a/docs/img/model_fitting_components.png b/docs/img/model_fitting_components.png
diff --git a/docs/img/plugins.jpg b/docs/img/plugins.jpg
diff --git a/docs/imviz/img/plugins.jpg b/docs/imviz/img/plugins.jpg
diff --git a/docs/imviz/plugins.rst b/docs/imviz/plugins.rst
@@ -8,7 +8,7 @@ The Imviz data analysis plugins are meant to aid quick-look analysis
 of 2D image data. All plugins are accessed via the :guilabel:`plugin`
 icon in the upper right corner of the Imviz application.
 
-.. image:: ../img/plugins.jpg
+.. image:: ./img/plugins.jpg
     :alt: Imviz Plugins
     :width: 200px
 
@@ -95,9 +95,16 @@ In Imviz, the table also exposed columns labeled "pixel:unreliable", "world:unre
 the bounds of the reference image's WCS (noted in the mouseover display by the information showing
 as grayed).
 
-To export the table into the notebook via the API, call
-:meth:`~jdaviz.core.template_mixin.TableMixin.export_table`
-(see :ref:`plugin-apis`).
+From the API
+------------
+
+To export the table into the notebook via the API:
+
+.. code-block:: python
+
+    markersplugin = imviz.plugins['Markers']
+    markersplugin.export_table()
+
 
 .. _imviz-orientation:
 
@@ -378,7 +385,7 @@ Canvas Rotation
     This plugin is deprecated in favor of rotation via :ref:`imviz-orientation` and will be removed
     in a future release.
 
-The canvas rotation plugin allows rotating and horizontally flipping the image to any arbitrary 
+The canvas rotation plugin allows rotating and horizontally flipping the image to any arbitrary
 value by rotating the canvas axes themselves.  Note that this does not affect the underlying data, and
 exporting data to the notebook via the API will therefore not exhibit the same rotation.
 

diff --git a/docs/specviz/displaying.rst b/docs/specviz/displaying.rst
@@ -29,8 +29,8 @@ for each button.
 Selecting/Showing Data Sets
 ===========================
 
-Data can be selected and de-selected in each viewer's data menu, opened by clicking the 
-|icon-viewer-data-select| button in the top left of the viewer. Here, you can click a 
+Data can be selected and de-selected in each viewer's data menu, opened by clicking the
+|icon-viewer-data-select| button in the top left of the viewer. Here, you can click a
 checkbox next to the listed data to make the data visible (checked) or invisible (unchecked).
 
 .. image:: img/data_tab.png
@@ -62,6 +62,10 @@ Home
 
 This button will reset your zoom and panning to display the entire image.
 
+Previous zoom is also available by right-clicking on the home icon and selecting
+the previous zoom icon.  This will revert to the last saved zoom state.  Zoom states
+are saved when beginning a zoom selection or when activating a pan/zoom tool.
+
 .. _box-zoom:
 
 Box Zoom
@@ -90,16 +94,6 @@ Interactive Pan/Zoom (Desktop or Notebook Interface)
 You can find the following Pan/Zoom tools available in the viewer toolbar
 on the top right of the viewer.
 
-
-Home
-^^^^
-
-This button will reset your zoom and panning to display the spectrum.
-
-Previous zoom is also available by right-clicking on the home icon and selecting
-the previous zoom icon.  This will revert to the last saved zoom state.  Zoom states
-are saved when beginning a zoom selection or when activating a pan/zoom tool.
-
 .. _image-pan-zoom:
 
 2D Bidirectional Pan/Zoom
@@ -113,11 +107,22 @@ Horizontal/Vertical Zoom
 ^^^^^^^^^^^^^^^^^^^^^^^^
 The |icon-zoom-pan-horiz| (horizontal) and |icon-zoom-pan-vert| (vertical) Zoom tools allow you to zoom along each axis, while locking the other.  You can also zoom by scrolling.
 
+Setting Viewer Bounds
+^^^^^^^^^^^^^^^^^^^^^
+The limits of the x and y axes can be set in the Plot Option plugin using the
+expandable menu "Viewer bounds".
+
+.. image:: img/specviz_plotopt_viewerbounds.png
+    :alt: Imviz Plot Options viewer bounds
+    :width: 200px
+
 From the API
 ------------
 
 The Specviz helper contains a set of convenience methods to programmatically define the view of the spectrum viewer. You may instantiate a Specviz Helper via::
 
+.. code-block:: python
+
     from jdaviz import Specviz
     # Instantiate an instance of Specviz
     specviz = Specviz()
@@ -173,7 +178,21 @@ and the spectral trace in color, coded to subset number and listed under the sub
 
 Clicking on that selector, you can add more regions by selecting the "create new" entry.
 
-From the API, you can use the :py:meth:`~jdaviz.configs.specviz.helper.Specviz.get_spectral_regions` method:
+From the API
+------------
+You can define a spectral region programmatically, by using the Glue XRangeROI method
+and specifying the bounds of the spectral region (xmin, xmax).
+
+.. code-block:: python
+
+    from glue.core.roi import XRangeROI
+    sv = specviz.app.get_viewer('spectrum-viewer')
+    sv.toolbar_active_subset.selected = []
+    sv.apply_roi(XRangeROI(xmin, xmax))
+
+
+To extract the properties of the defined spectral regions, you can use
+the :py:meth:`~jdaviz.configs.specviz.helper.Specviz.get_spectral_regions` method:
 
 .. image:: img/spectral_region_5.png
 
@@ -183,7 +202,7 @@ Line Selection
 ==============
 
 This button will allow you to click and select a vertical line when multiple
-lines from a line list are over-plotted. Futher analysis can be performed on this
+lines from a line list are over-plotted. Further analysis can be performed on this
 line of interest.
 
 .. seealso::
@@ -230,9 +249,13 @@ Plot uncertainties
 Toggle on to view uncertainties attached to the spectrum, if any.
 
 From the API
-^^^^^^^^^^^^
+------------
+
+Here is an example on how to set the plot options from the API.
 
 .. code-block:: python
 
     plot_options = specviz.plugins['Plot Options']
+    plotopt.line_color = 'blue'
+    plotopt.line_width = 3
     plot_options.uncertainty_visible = True
diff --git a/docs/specviz/img/line_analysis_plugin.png b/docs/specviz/img/line_analysis_plugin.png
diff --git a/docs/specviz/img/specviz_plotopt_viewerbounds.png b/docs/specviz/img/specviz_plotopt_viewerbounds.png
diff --git a/docs/specviz/img/specvizplugins.jpg b/docs/specviz/img/specvizplugins.jpg
diff --git a/docs/specviz/plugins.rst b/docs/specviz/plugins.rst
@@ -48,7 +48,9 @@ Subset Tools
 .. seealso::
 
     :ref:`Subset Tools <imviz-subset-plugin>`
-        Imviz documentation describing the concept of subsets in Jdaviz.
+        Imviz documentation describing the concept of subsets in Jdaviz. Subsets
+        in Specviz are strictly spectral subsets and do not support rotation or
+        recentering.
 
 Markers
 =======
@@ -79,6 +81,7 @@ Model Fitting
 =============
 
 .. image:: ../img/model_fitting_components.png
+    :alt: Model Fitting plugin
 
 Astropy models can be fit to a spectrum via the Model Fitting plugin.
 Model components are selected via the :guilabel:`Model Component` pulldown menu.
@@ -101,10 +104,37 @@ or to change to subtraction, for example.
 After fitting, the expandable menu for each component model will update to
 show the fitted value of each parameter rather than the initial value, and
 will additionally show the standard deviation uncertainty of the fitted
-parameter value if the parameter was not set to be fixed to the initial value.
+parameter value if the parameter was not set to be fixed to the initial value
+and if the spectrum uncertainty was loaded.
 
-Parameter values for each fitting run are stored in the plugin table.  
-To export the table into the notebook via the API, call
+From the API
+------------
+
+The model fitting plugin can be run from the API:
+
+.. code-block:: python
+
+    # Open model fitting plugin
+    plugin_mf = specviz.plugins['Model Fitting']
+    plugin_mf.open_in_tray()
+    # Input the appropriate dataset and subset
+    plugin_mf.dataset = 'my spectrum'
+    plugin_mf.spectral_subset = 'Subset 1'
+    # Input the model components
+    plugin_mf.create_model_component(model_component='Linear1D',
+                                     model_component_label='L')
+    plugin_mf.create_model_component(model_component='Gaussian1D',
+                                     model_component_label='G')
+    # Set the initial guess of some model parameters
+    plugin_mf.set_model_component('G', 'stddev', 0.002)
+    plugin_mf.set_model_component('G', 'mean', 2.2729)
+    # Model equation gets populated automatically, but can be overwritten
+    plugin_mf.equation = 'L+G'
+    # Calculate fit
+    plugin_mf.calculate_fit()
+
+Parameter values for each fitting run are stored in the plugin table.
+To export the table into the notebook, call
 :meth:`~jdaviz.core.template_mixin.TableMixin.export_table`
 (see :ref:`plugin-apis`).
 
@@ -131,6 +161,16 @@ Select the flux density unit in the :guilabel:`New Flux Unit` pulldown
 Note that this affects the default units in all viewers and plugins, where applicable,
 but does not affect the underlying data.
 
+From the API
+------------
+
+The Unit Conversion plugin can be called from the API:
+
+.. code-block:: python
+
+    unitconv_pl = specviz.plugins['Unit Conversion']
+    unitconv_pl.spectral_unit = 'Angstrom'
+
 .. _line-lists:
 
 Line Lists
@@ -224,6 +264,9 @@ will return the data as originally loaded, with the redshift unchanged.
 Line Analysis
 =============
 
+.. image:: ./img/line_analysis_plugin.png
+    :alt: Line Analysis plugin
+
 The Line Analysis plugin returns
 `specutils analysis <https://specutils.readthedocs.io/en/stable/analysis.html>`_
 for a single spectral line.
@@ -239,11 +282,31 @@ in the spectrum plot while the plugin is open.  The thick line shows the linear
 is then interpolated into the line region as shown by a thin line.  Alternatively, a custom
 secondary region can be created and selected as the region to fit the linear continuum.
 
-The statistics returned include the line centroid, gaussian sigma width, gaussian FWHM,
-total flux, and equivalent width.
+The properties returned include the line centroid, gaussian sigma width, gaussian FWHM,
+total flux, and equivalent width. Uncertainties on the derived properties are also
+returned. For more information on the algorithms used, refer to the `specutils documentation
+<https://specutils.readthedocs.io/en/stable/analysis.html>`_.
 
 The line flux results are automatically converted to Watts/meter^2, when appropriate.
 
+From the API
+------------
+
+The Line Analysis plugin can be run from the API:
+
+.. code-block:: python
+
+    # Open line analysis plugin
+    plugin_la = specviz.plugins['Line Analysis']
+    plugin_la.open_in_tray()
+    # Input the appropriate spectrum and region
+    plugin_la.dataset = 'my spectrum'
+    plugin_la.spectral_subset = 'Subset 2'
+    # Input the values for the continuum
+    plugin_la.continuum = 'Subset 3'
+    # Return line analysis results
+    plugin_la.get_results()
+
 Redshift from Centroid
 ----------------------