Merge pull request #2089 from kbwestfall/spec1d_docs

kbwestfall · web-flow · commit d5f8d74da16e · 2026-03-23T11:34:35.000-07:00
Move key-binding descriptions from class docstring to `pypeit_show_1dspec` description
diff --git a/doc/help/pypeit_show_1dspec.rst b/doc/help/pypeit_show_1dspec.rst
@@ -2,14 +2,15 @@
 
     $ pypeit_show_1dspec -h
     usage: pypeit_show_1dspec [-h] [-v VERBOSITY] [--log_file LOG_FILE]
-                              [--log_level LOG_LEVEL] [--list] [--exten EXTEN]
-                              [--obj OBJ] [--extract EXTRACT] [--flux] [-m]
+                              [--log_level LOG_LEVEL] [--list] [--exten EXTEN |
+                              --obj OBJ] [--extract {BOX,OPT}] [--flux] [-m]
                               file
     
     Show a 1D spectrum
     
     positional arguments:
-      file                  Spectral file
+      file                  PypeIt spec1d file (this script does not work with
+                            coadd_1dspec output spectra).
     
     options:
       -h, --help            show this help message and exit
@@ -25,12 +26,13 @@
                             Verbosity level for the log file. If a log file is
                             produce and this is None, the file log will match the
                             console stream log. (default: None)
-      --list                List the extensions only? (default: False)
-      --exten EXTEN         FITS extension (default: 1)
-      --obj OBJ             Object name in lieu of extension, e.g.
+      --list                Instead of plotting any spectra, simply list the
+                            extensions with spectra (default: False)
+      --exten EXTEN         Number of the extension to plot (default: 1)
+      --obj OBJ             Extension (object) name to plot, e.g.
                             SPAT0424-SLIT0000-DET01 (default: None)
-      --extract EXTRACT     Extraction method. Default is OPT. ['BOX', 'OPT']
-                            (default: OPT)
-      --flux                Show fluxed spectrum? (default: False)
-      -m, --unmasked        Only show unmasked data. (default: True)
+      --extract {BOX,OPT}   Method used to extract the spectrum (default: OPT)
+      --flux                Show the flux-calibrated spectrum (if available)
+                            (default: False)
+      -m, --unmasked        Only show the unmasked data. (default: True)
     
diff --git a/doc/help/run_pypeit.rst b/doc/help/run_pypeit.rst
@@ -6,7 +6,7 @@
                       pypeit_file
     
     PypeIt: The Python Spectroscopic Data Reduction Pipeline
-    Version 1.18.2.dev643+g76c0191d0
+    Version 2.0.1.dev23+g72bf91080.d20260323
     
     Available spectrographs include:
         aat_uhrf, apf_levy, bok_bc, gemini_flamingos1, gemini_flamingos2,
diff --git a/doc/include/gemini_gnirs_echelle_A.pypeit.rst b/doc/include/gemini_gnirs_echelle_A.pypeit.rst
@@ -1,7 +1,7 @@
 .. code-block:: console
 
-    # Auto-generated PypeIt input file using PypeIt version: 1.18.1
-    # UTC 2025-09-29T12:51:17
+    # Auto-generated PypeIt input file using PypeIt version: 2.0.0
+    # UTC 2026-02-10T07:57:06
     
     # User-defined execution parameters
     [rdx]
diff --git a/doc/include/keck_deimos_A.pypeit.rst b/doc/include/keck_deimos_A.pypeit.rst
@@ -1,7 +1,7 @@
 .. code-block:: console
 
-    # Auto-generated PypeIt input file using PypeIt version: 1.18.1
-    # UTC 2025-09-29T12:51:17
+    # Auto-generated PypeIt input file using PypeIt version: 2.0.0
+    # UTC 2026-02-10T07:57:06
     
     # User-defined execution parameters
     [rdx]
diff --git a/doc/include/keck_nires_A.pypeit.rst b/doc/include/keck_nires_A.pypeit.rst
@@ -1,7 +1,7 @@
 .. code-block:: console
 
-    # Auto-generated PypeIt input file using PypeIt version: 1.18.1
-    # UTC 2025-09-29T12:51:17
+    # Auto-generated PypeIt input file using PypeIt version: 2.0.0
+    # UTC 2026-02-10T07:57:06
     
     # User-defined execution parameters
     [rdx]
diff --git a/doc/include/shane_kast_blue_A.pypeit.rst b/doc/include/shane_kast_blue_A.pypeit.rst
@@ -1,7 +1,7 @@
 .. code-block:: console
 
-    # Auto-generated PypeIt input file using PypeIt version: 1.18.1
-    # UTC 2025-09-29T12:51:17
+    # Auto-generated PypeIt input file using PypeIt version: 2.0.0
+    # UTC 2026-02-10T07:57:06
     
     # User-defined execution parameters
     [rdx]
diff --git a/doc/out_spec1D.rst b/doc/out_spec1D.rst
@@ -112,54 +112,77 @@ Here is a typical call:
     file is typically written to the ``VERSPYP`` header keyword) or re-reduce
     the data with the new PypeIt version.
 
-Options
--------
-
-Here are the typical options you will use:
-
---list
-++++++
-
-This prints a list to the screen of all the objects extracted.  An example:
-
-.. code-block:: console
-
-    EXT0000001 = SPAT0351-SLIT0000-DET01
-    EXT0000002 = SPAT0392-SLIT0001-DET01
-    EXT0000003 = SPAT0463-SLIT0003-DET01
-    EXT0000004 = SPAT0556-SLIT0004-DET01
-    EXT0000005 = SPAT0621-SLIT0005-DET01
-    EXT0000006 = SPAT0731-SLIT0006-DET01
-    EXT0000007 = SPAT0824-SLIT0007-DET01
-    EXT0000008 = SPAT0865-SLIT0007-DET01
-    EXT0000009 = SPAT0910-SLIT0008-DET01
-    EXT0000010 = SPAT0962-SLIT0009-DET01
-    EXT0000011 = SPAT0073-SLIT0000-DET02
-    EXT0000012 = SPAT0093-SLIT0000-DET02
-    EXT0000013 = SPAT0130-SLIT0001-DET02
-
-This indicates the extension of the object with this :ref:`spec1d-naming`.
-
---exten
+.. _pypeit_show_1dspec_interact:
+
+Interacting with the display
+----------------------------
+
+The spec1d mode is a mode enabled by ginga to interact with the spectrum plot.
+**To get a listing of the key-bindings in the ginga window, type 'h'.**  If that
+doesn't work, or if the key bindings themselves don't seem to work, you may have
+exited the mode.  To restart the mode, hit the space-bar and then the 1 key.  If
+you're still having trouble, please submit an issue via GitHub or post a
+question to the Users Slack.
+
+The key-bindings below are copied from the relevant docstring; if anything is
+different from the dialog you get when pressing 'h' in ginga, you should defer
+to what is shown there.  The key-bindigs are as follows:
+
+Enter the mode
+++++++++++++++
+* Space, then "1"
+
+Exit the mode
++++++++++++++
+* Esc
+
+Mouse/trackpad bindings in mode
++++++++++++++++++++++++++++++++
+* Shift + left click : set pan position
+* middle click : set pan position
+* scroll : zoom in/out
+* ctrl + scroll : zoom in/out X axis only
+* shift + scroll : zoom in/out Y axis only (On MacOS, trackpad only)
+* alt + scroll(mouse) : zoom in/out Y axis only (Option key on Macs)
+* alt + scroll : zoom in/out at cursor
+
+Zooming
 +++++++
+* equals : zoom in one zoom level
+* ctrl + equals : zoom in X axis one zoom level
+* plus (shift + equals) : zoom in Y axis one zoom level
+* minus : zoom out one zoom level
+* ctrl + minus : zoom out X axis one zoom level
+* underscore (shift + minus): zoom out Y axis one zoom level
+* 9 : zoom out maintaining cursor position
+* ctrl + 9 : zoom out X axis maintaining cursor position
+* left paren (shift + 9): zoom out Y axis maintaining cursor position
+* 0 : zoom in maintaining cursor position
+* ctrl + 0 : zoom in X axis maintaining cursor position
+* right paren (shift + 0): zoom in Y axis maintaining cursor position
+* backquote : zoom X and Y axes to fit window
+* 1 : zoom X axis only to fit window
+* 2 : zoom Y axis only to fit window
+* k : set lower X range to X value at cursor
+* l : set upper X range to X value at cursor
+* K : set lower Y range to Y value at cursor
+* L : set upper Y range to Y value at cursor
+
+Panning
++++++++
+* left arrow : pan left
+* right arrow : pan right
+* up arrow : pan up
+* down arrow : pan down
 
-This is a short-cut of sorts to pull the object you want without
-typing in its name.
-
---obj
-+++++
-
-Plot this object.
-
---extract
-+++++++++
-
-Choice of :ref:`spec1d-extraction` method.
-
---flux
-++++++
-
-Show the fluxed spectrum (only if it has been fluxed!)
+Regions
++++++++
+* [ : mark lower X boundary of region
+* ] : mark upper X boundary of region
+* backslash : clear region
+* singlequote : (zoom) set X range to region
+* f : fit a Gaussian to the region and show result
+* c : clear fit result
 
 ----
 
diff --git a/doc/pypeit_par.rst b/doc/pypeit_par.rst
@@ -1265,7 +1265,6 @@ Alterations to the default parameters are:
       [[flatfield]]
           spat_samp = 0.7
           tweak_slits = False
-          slit_trim = 0
           slit_illum_finecorr = False
       [[wavelengths]]
           method = reidentify
@@ -1299,6 +1298,7 @@ Alterations to the default parameters are:
       [[skysub]]
           global_sky_std = False
           mask_by_boxcar = True
+          no_local_sky = True
       [[extraction]]
           boxcar_radius = 1.728
 
diff --git a/doc/releases/2.0.1.rst b/doc/releases/2.0.1.rst
@@ -0,0 +1,13 @@
+
+Version 2.0.1
+=============
+
+- Add key-binding documentation from ``pypeit/display/pypeit_modes.py`` to the
+  main documentation page, :ref:`pypeit_show_1dspec`.
+
+- Small changes to default parameter values for the APF/Levy spectrograph
+
+- Change an exception raised when a coding-level check failed that was meant to
+  ensure consistency between calibration groups and science frames.  This was
+  causing unintended faults for APF/Levy data.
+
diff --git a/doc/whatsnew.rst b/doc/whatsnew.rst
@@ -11,6 +11,10 @@ What's New in PypeIt
 
 ----
 
+.. include:: releases/2.0.1.rst
+
+----
+
 .. include:: releases/2.0.0.rst
 
 ----
diff --git a/pypeit/display/pypeit_modes.py b/pypeit/display/pypeit_modes.py
@@ -10,6 +10,8 @@
 
 # Note inheritance from Plot2DMode, which already defines many callbacks
 #
+# IMPORTANT: If you change the key bindings, make sure you update both the
+# docstring here **and** the text in `doc/out_spec1D.rst`.
 class Spec1DMode(Plot2DMode):
     """
     Spec1DMode enables special bindings for viewing PypeIt spec1d files.
diff --git a/pypeit/scripts/show_1dspec.py b/pypeit/scripts/show_1dspec.py
@@ -14,18 +14,33 @@ class Show1DSpec(scriptbase.ScriptBase):
     @classmethod
     def get_parser(cls, width=None):
         parser = super().get_parser(description='Show a 1D spectrum', width=width)
-        parser.add_argument("file", type=str, help="Spectral file")
-        parser.add_argument("--list", default=False, help="List the extensions only?",
-                            action="store_true")
-        parser.add_argument("--exten", type=int, default=1, help="FITS extension")
-        parser.add_argument("--obj", type=str,
-                            help="Object name in lieu of extension, e.g. SPAT0424-SLIT0000-DET01")
-        parser.add_argument("--extract", type=str, default='OPT',
-                            help="Extraction method. Default is OPT. ['BOX', 'OPT']")
-        parser.add_argument("--flux", default=False, action="store_true",
-                            help="Show fluxed spectrum?")
-        parser.add_argument('-m', '--unmasked', dest='masked', default=True, action='store_false',
-                            help='Only show unmasked data.')
+        parser.add_argument(
+            'file', type=str,
+            help='PypeIt spec1d file (this script does not work with coadd_1dspec output spectra).'
+        )
+        parser.add_argument(
+            '--list', default=False, action='store_true',
+            help='Instead of plotting any spectra, simply list the extensions with spectra'
+        )
+        grp = parser.add_mutually_exclusive_group()
+        grp.add_argument(
+            '--exten', type=int, default=1, help='Number of the extension to plot'
+        )
+        grp.add_argument(
+            '--obj', type=str, help='Extension (object) name to plot, e.g. SPAT0424-SLIT0000-DET01'
+        )
+        parser.add_argument(
+            '--extract', type=str, default='OPT', choices=['BOX', 'OPT'],
+            help='Method used to extract the spectrum'
+        )
+        parser.add_argument(
+            '--flux', default=False, action='store_true',
+            help='Show the flux-calibrated spectrum (if available)'
+        )
+        parser.add_argument(
+            '-m', '--unmasked', dest='masked', default=True, action='store_false',
+            help='Only show the unmasked data.'
+        )
 #        parser.add_argument('--jdaviz', default=False, action='store_true',
 #                            help='Open the spectrum in jdaviz (requires specutils and jdaviz '
 #                                 'to be installed)')
@@ -106,10 +121,10 @@ def main(cls, args):
 
         if args.obj is not None:
             exten = np.where(sobjs.NAME == args.obj)[0][0]
-            if exten < 0:
-                raise PypeItError(f"Bad input object name: {args.obj}")
         else:
             exten = args.exten-1 # 1-index in FITS file
+        if exten < 0:
+            raise PypeItError(f"Bad input extension/object name: {args.obj}")
 
         # Check Extraction
         if args.extract == 'OPT':
