Merge pull request #1877 from pypeit/state_and_steps

Enable users to run and re-run one step of Calibrations

doc/releases/1.17.2dev.rst

@@ -1,5 +1,5 @@
 
-Version 1.17.1dev
+Version 1.17.2dev
 =================
 
 Installation Changes
@@ -36,6 +36,11 @@ Script Changes
 
 - `pypeit_setup_gui` script has been removed. The Setup GUI can be started with `pypeit_setup -G`.
 
+- Added ``pypeit_run_to_calibstep`` to run PypeIt to an input calibration
+  step. This script is useful to re-generate calibration files for a given
+  configuration without running the full reduction.
+
+
 Datamodel Changes
 -----------------
 

doc/running.rst

@@ -35,7 +35,7 @@ Before executing ``run_pypeit``, you must have
     #. Edited the :doc:`pypeit_file` in that directory as recommended for a
        successful reduction.
 
-    #. (optional) Removed any calibration files in the ``Calibrations/`` folder.
+    #. (optional) Remove any calibration files in the ``Calibrations/`` folder.
        This is particularly necessary if you're re-reducing data that was
        previously reduced by an older PypeIt version.  However, when in doubt,
        it's good practice to perform a fresh reduction by removing these files

doc/scripts.rst

@@ -201,6 +201,40 @@ run_pypeit
 This is the main executable for PypeIt for its core end-to-end data processing.
 See :ref:`run-pypeit` for details.
 
+pypeit_run_to_calibstep
+-----------------------
+
+This runs PypeIt to a given calibration step for a given frame.
+This is primarily provided to re-run a single calibration step after 
+the user has modified their ``pypeit`` file.  It is expected that
+the user has already attempted a full reduction with ``run_pypeit``.
+following the details in :ref:`run-pypeit`.
+
+The user provides: (1) the PypeIt file, (2) the calibration step
+to re-run to, and
+(3) either the raw science file whose 
+calibration file(s) you wish to re-run or the calib_group ID. 
+All steps up to and including the requested step will be
+run, although previous steps will be skipped if the calibration files
+are already present (these will be loaded, as appropriate).
+
+Users are strongly advised to use this script until you are happy
+with the calibration of this single step.  Once you are, you should
+re-run the full reduction with ``run_pypeit`` after first removing
+*all* previously generated calibration and science files.
+
+The script usage can be displayed by calling the script with the
+``-h`` option:
+
+.. include:: help/pypeit_run_to_calibstep.rst
+
+An example call is:
+
+.. code-block:: console
+
+    pypeit_run_to_calibstep shane_kast_blue_A.pypeit wv_calib --science_frame b28.fits.gz 
+
+
 pypeit_trace_edges
 ------------------