JP-3291 and JP-3319 and JP-2994 Cube build enhancements (#7783)

Co-authored-by: Howard Bushouse <[email protected]>

CHANGES.rst

@@ -4,8 +4,7 @@
 assign_wcs
 ----------
 
-- Use isinstance instead of comparison with a type for lamp_mode
-  inspection [#7801]
+- Use isinstance instead of comparison with a type for lamp_mode inspection [#7801]
 
 calwebb_spec2
 -------------
@@ -14,6 +13,12 @@ calwebb_spec2
   that is returned by the pipeline to ensure a file is created with the
   expected ``_cal`` suffix. [#7772]
 
+cube_build
+----------
+
+- Replace scale1 and scale2 arguments with scalexy, add debug option debug_spaxel,
+  and add more details to docs. [#7783]
+
 datamodels
 ----------
 
@@ -62,7 +67,9 @@ residual_fringe
 set_telescope_pointing
 ----------------------
 
-- Commanded Guide Star is always relative to FGS1 [#7804]
+- Fixes to account for the fact that the commanded Guide Star position is always
+  relative to FGS1 even when guiding with FGS2. [#7804]
+
 
 1.11.3 (2023-07-17)
 ===================

docs/jwst/cube_build/arguments.rst

@@ -14,17 +14,19 @@ each band will be created.
   If the ``channel`` argument is given, then only data corresponding to that channel  will be used in
   constructing the cube.  A comma-separated list can be used to designate multiple channels.
   For example, to create a cube with data from channels 1 and 2, specify the
-  list as ``--channel='1,2'``. If this argument is not specified, the output will be a set of IFU cubes, one for each
-  channel/sub-channel combination contained in the input data.
+  list as ``--channel='1,2'``.  All the sub-channels (bands) for the chosen channel(s) will
+  be used to create the IFU cube, unless the ``band`` argument is used to select specific bands.  This parameter can be combined
+  with the ``output_type``  parameter  to fully control the type of IFU cubes to make.
 
 ``band [string]``
   This is a MIRI only option and the valid values are SHORT, MEDIUM, LONG, and ALL.
   If the ``band`` argument is given, then only data corresponding
-  to that sub-channel will be used in constructing the cube. Only one value can be specified, so IFU cubes are
-  created either per sub-channel or using all the sub-channels of the data.  If this argument is not specified,
-  a set of IFU cubes is created, one for each band. Note we use the name ``band`` for this argument instead of
+  to that sub-channel will be used in constructing the cube. Only one value can be specified. 
+  Note we use the name ``band`` for this argument instead of
   ``subchannel``, because the keyword ``band`` in the input images is used to indicate which MIRI subchannel the
-  data covers.
+  data cover.   This parameter can be combined
+  with the ``output_type``  parameter  to fully control the type of IFU
+  cubes to make.
 
 ``grating [string]``
   This is a NIRSpec only option with valid values PRISM, G140M, G140H, G235M, G235H, G395M, G395H, and ALL.
@@ -44,26 +46,26 @@ each band will be created.
   with the options above [band, channel, grating, filter] to fully control the type of IFU
   cubes to make.
 
-  - ``output_type = band`` is the default mode for calspec3 and creates IFU cubes containing only one band
+  - ``output_type = band`` creates IFU cubes containing only one band
     (channel/sub-channel for MIRI or grating/filter combination for NIRSpec).
 
   - ``output_type = channel`` creates a single IFU cube from each unique channel of MIRI data
-    (or just those channels set by the 'channel' option).
+    (or just those channels set by the 'channel' option). This is the default mode for the
+    :ref:`calwebb_spec3 <calwebb_spec3>` pipeline for MIRI data. 
 
   - ``output_type = grating`` combines all the gratings in the NIRSpec data or set by the
-    grating option into a single IFU cube.
+    grating option into a single IFU cube. The is the default mode for the
+    :ref:`calwebb_spec3 <calwebb_spec3>` pipeline for NIRSpec data. 
 
-  - ``output_type = multi`` combines data  into a single "uber" IFU cube, this the default mode for calspec2. If in addition,
-    channel, band, grating, or filter are also set, then only the data set by those
+  - ``output_type = multi`` combines data  into a single "uber" IFU cube, this the default mode for
+    :ref:`calwebb_spec2 <calwebb_spec2>` pipeline.  
+    If in addition,  channel, band, grating, or filter are also set, then only the data set by those
     parameters will be combined into an "uber" cube.
 
 The following arguments control the size and sampling characteristics of the output IFU cube.
 
-``scale1``
-  The output cube's spaxel size in axis 1 (spatial).
-
-``scale2``
-  The output cube's spaxel size in axis 2 (spatial).
+``scalexy``
+  The output cube's spaxel size for  axis 1 and 2 (spatial).
 
 ``scalew``
   The output cube's spaxel size in axis 3 (wavelength).
@@ -98,3 +100,10 @@ The arguments related to region of interest and how the fluxes are combined toge
 
   For more details on how the weighting of the detector pixel fluxes are used in determining the final spaxel flux see
   the :ref:`weighting` section.
+
+A parameter only used for investigating which detector pixels contributed to a cube spaxel is ``debug_spaxel``. This option is only valid if the ``weighting`` parameter is set to ``drizzle`` (default). 
+
+``debug_spaxel [string]``
+
+  The string is the x,y,z value of the cube spaxel that is being investigated. The  numbering starts counting at 0.
+  To print information to the screeen about the x = 10, y = 20, z = 35 spaxel the parameter string value is '10 20 35'.