Merge pull request USNavalResearchLaboratory#96 from MJWeberg/main

Added eis_explore_raster GUI tool

MANIFEST.in

@@ -9,3 +9,4 @@ include eispac/templates/eis_template_dir/*.jpg
 include eispac/data/test/*.h5
 include eispac/data/templates/*.h5
 include eispac/data/templates/*.jpg
+include eispac/data/ref/*.txt

docs/code_reference/eispac_data.rst

@@ -0,0 +1,8 @@
+eispac data
+=============
+
+This subpackage contains all of the fitting templates used by EISPAC as well
+as a few helper functions.
+
+.. automodapi:: eispac.data
+  :no-heading:

docs/code_reference/index.rst

@@ -7,6 +7,7 @@ API Reference
    :maxdepth: 1
 
    eispac_core
+   eispac_data
    eispac_download
    eispac_extern
    eispac_instr

docs/guide/02-scripts.rst

@@ -21,6 +21,10 @@ There are currently five command line scripts available,
    downloading the HDF5 files your computer. Can also generate a text list of
    files to download.
 
+-  ``eis_explore_raster`` - **New in 2024-July-11** GUI tool for viewing and
+   exploring the contents of one or more EIS rasters. Can be used on both 
+   level-1 HDF5 files and fit results produced by EISPAC.
+
 -  ``eis_browse_templates`` - GUI tool for browsing the fit templates
    corresponding to each spectral window in a given EIS observation and
    copying the template files from EISPAC to your current working directory
@@ -102,7 +106,9 @@ D. **Search** **Results**: List of all EIS observations matching your search
    additional information about that observation in the "Details" panel.
 
 E. **Details**: General use panel for displaying help information,
-   observation details, and status updates.
+   observation details, and status updates. Newer versions of the GUI have
+   addtional tabs here for viewing context images from SDO / AIA 
+   (or SOHO / EIT before 2010-May) as well as general help information.
 
 F. **Download** **Controls**: Select output directory, download selected
    file, download all files in the list (use with care!), or make a text
@@ -111,6 +117,44 @@ F. **Download** **Controls**: Select output directory, download selected
    better in a future update). If the "Use Date Tree" box is checked, files
    will be downloaded into subdirectories organized by month and day.
 
+.. _sec-explore:
+
+eis_explore_raster
+------------------
+
+**New in 2024-July-11** The ``eis_explore_raster`` GUI tool can be used to 
+view and explore the contents of one or more EIS rasters. The interface 
+works with both a level-1 HDF5 files and fit results produced by EISPAC 
+(as saved using the `~eispac.core.save_fit` function). More information 
+about fitting is given in the :ref:`sec-fitting` chapter.
+
+.. figure:: figures/eis_explore_raster_example.png
+   :align: center
+   :width: 600px
+
+   The main window of the `eis_explore_raster` GUI tool. The left image is
+   showing level-1 data in the Fe XII 195.119 window while the right image
+   is plotting the fit results for the Fe XI 188.299 lines. 
+
+Assorted program controls (including the number of image panels displayed)
+are found at far left of the GUI. Each image panel can load a different data
+file. Use the drop-down lists to select the spectral window and parameter 
+(and scaling method) to display. Clicking on any raster image will select and 
+plot the spectrum at that location. By default, selections will be synchronized 
+between panels using physical coordinates, reguardless of the image timestamps.
+Middle clicking any plot will toggle pan/zoom mode for that plot. When toggled 
+on, left click and drag the plot to pan or right click and move your mouse 
+right (or up) to to zoom in and left (or down) to zoom out.
+
+When viewing a level-1 file, clicking on the spectrum will select the center of 
+the wavelength range used to compute the summed raster image. Please note: the 
+data are plotted after including all wavelength corrections, which can result
+in offsets relative to the bin indices used for the sum. Loading a fitting 
+result will also plot all component Gaussians used in the fit. Markers showing
+the theoretical, rest wavelengths of different spectral lines (as given in the 
+`CHAINTI atomic database <https://www.chiantidatabase.org/>`_) can be toggled
+with the "Show line IDs" checkbox in the bottom left of the GUI. 
+
 .. _sec-browse:
 
 eis_browse_templates
@@ -125,3 +169,9 @@ the template relative to representative solar spectra (NOT the data in the
 actual observation). You can then use the "Copy template" button to make a
 copy of the template file in the output directory. Fit templates are
 explained more in the :ref:`sec-fitting` chapter.
+
+.. figure:: figures/eis_browse_templates_example.png
+   :align: center
+   :width: 600px
+
+   The main window of the `eis_browse_templates` GUI tool.

docs/guide/04-fitting.rst

@@ -511,6 +511,23 @@ For now, we will just show you some examples of the quick-look plots.
    *ALL* EIS velocity maps, not just those computed by EISPAC. Please
    use with care.
 
+Exploring Fit Results
+---------------------
+
+As mentioned in the chapter on command line scripts, the :ref:`sec-browse`
+GUI tool can be used to quickly plot and explore fits run using EISPAC.
+After loading a ``.fit.h5`` file made using `~eispac.core.save_fit`, 
+just click anywhere on the image to view the fit spectrum at the selected 
+location. Note: the data values will be loaded from the original level-1
+``.data.h5`` file; currently, viewing the fit for a data cutout will overplot
+the data points from the wrong level-1 pixel location (this bug will be 
+patched om a future version).
+
+.. figure:: figures/eis_explore_raster_fit_results.png
+   :align: center
+   :width: 300px
+
+   Example of viewing fit results in the ``eis_explore_raster`` GUI.
 
 .. rubric:: Footnotes
 

eispac/data/__init__.py

@@ -1,2 +1,3 @@
+from .ref import *
 from .templates import *
 from .test import *

eispac/data/ref/__init__.py

@@ -0,0 +1,38 @@
+"""
+Template files for fitting EIS spectra
+"""
+import os
+import pathlib
+import numpy as np
+
+import eispac
+
+__all__ = ['load_chianti_lines']    
+
+def load_chianti_lines(sort='wave'):
+    """Load reference list of spectral lines from CHIANTI
+
+    Parameters
+    ----------
+    sort : str, optional
+        Array column to sort by. Choose from "wave" or "id". Default is "Wave".
+
+    Returns
+    -------
+    line_arr : numpy recarray
+        Array containing spectral lines in both EIS wavebands as computed using
+        CHIANTI (version 8?). The array has two columns, "wave" which contains 
+        the rest wavelength of the line (in units of [angstrom]) and "id"
+        which gives the spectral line ID (e.g. Fe XII). 
+    """
+
+    ref_dir = pathlib.Path(os.path.dirname(eispac.__file__)) / "data" / "ref"
+    line_id_filepath = ref_dir / 'eis_chianti_lookup_table.txt'
+    line_arr = np.genfromtxt(line_id_filepath, delimiter='  ', 
+                            dtype=['float', 'U8'], names=['wave', 'id'])
+    if sort.lower().startswith('wave'):
+        line_arr = np.sort(line_arr, order=['wave'])
+    elif sort.lower().startswith('id'):
+        line_arr = np.sort(line_arr, order=['id'])
+
+    return line_arr