documentation updates for WFSS and TSGRISM mode (#1710, #1756)

docs/jwst/assign_wcs/exp_types.rst

@@ -33,7 +33,7 @@ WCS reference file information per EXP_TYPE
   | Implements: Distortion file created from TEL team data.
 
 :NRC_WFSS, NRC_TSGRISM:
-  | reftypes: *specwcs*, *distortion* *wavelengthrange*
+  | reftypes: *specwcs*, *distortion* 
   | WCS pipeline coordinate frames: grism_detector, detector, v2v3, world
   | Implements: reference files provided by NIRCAM team
 

docs/jwst/assign_wcs/main.rst

@@ -45,8 +45,7 @@ associated with the telescope, and a standard celestial system.
 Using the WCS interactively
 ---------------------------
 
-Once a FITS file is opened as a `DataModel` the WCS can be accessed as an attribute of the meta object.
-Calling it as a function with detector positions as inputs returns the
+Once a FITS file is opened as a `DataModel` the WCS can be accessed as an attribute of the meta object. Calling it as a function with detector positions as inputs returns the
 corresponding world coordinates. Using MIRI LRS fixed slit as an example:
 
 >>> from jwst.datamodels import ImageModel
@@ -55,15 +54,15 @@ corresponding world coordinates. Using MIRI LRS fixed slit as an example:
 >>> print(ra, dec, lam)
     (329.97260532549336, 372.0242999250267, 5.4176100046836675)
 
-The GRISM modes for NIRCAM and NIRISS have a slightly different calling structure,
+The WFSS modes for NIRCAM and NIRISS have a slightly different calling structure,
 in addition to the (x, y) coordinate, they need to know other information about the
 spectrum or source object. In the JWST backward direction (going from the sky to
 the detector) the WCS model also looks for the wavelength and order and returns
 the (x,y) location of that wavelength+order on the dispersed image and the original
 source pixel location, as entered, along with the order that was specified:
 
 >>> form jwst.datamodels import ImageModel
->>> exp = ImageModel('nircam_grism_assign_wcs.fits')
+>>> exp = ImageModel('nircam_wfss_assign_wcs.fits')
 >>> x, y, x0, y0, order = exp.meta.wcs(x0, y0, wavelength, order)
 >>> print(x0, y0, wavelength, order)
     (365.523884327, 11.6539963919, 2.557881113, 2)

docs/jwst/assign_wcs/reference_files.rst

@@ -339,7 +339,7 @@ For NIRISS SOSS mode the file is in ASDF format with the following structure.
 
 :model: A tabular model with the wavelength solution.
 
-For NIRCAM WFSS and TSGRIM modes the file is in ASDF format with the following structure:
+For NIRCAM WFSS and TSGRISM modes the file is in ASDF format with the following structure:
 
 :displ: The wavelength transform models
 :dispx: The x-dispersion models
@@ -385,14 +385,4 @@ For NIRSPEC the file is a dictionary storing information about default wavelengt
 :filter_grating:
                  :order: Default spectral order
                  :range: Default wavelength range
-
-For NIRCAM WFSS and TSGRIM modes and NIRISS WFSS mode the wavelengthrange file contains the wavelength limits to use when caluclating the minimum and maximum dispersion extents on the detector. The selection of the
-correct minimum and maximum wavelength range is done with the following logic, where the index of
-the desired filter is used as the reference into wrange_selector, and the same for the index of the order:
-
-wave_min, wave_max = wrange[order][wrange_selector[filter name]]
-
-:order: a list of orders
-:wrange: a 2D list of wavelength ranges, ordered in the same way as the orders
-:wrange_selector: The list of FILTER names, these are used to select the correct wavelength range
-
+

docs/jwst/extract_2d/main.rst

@@ -22,13 +22,13 @@ source catalog that may be associated with the dispersed image. Instead, there
 is a helper method that is used to calculate the bounding boxes that contain
 the dispersed spectra for each object. One box is made for each order. ``extract2d``
 uses the source catalog referenced in the input models meta information to create
-the list of objects and their corresponding bounding box, this list is used to make
+the list of objects and their corresponding bounding box. This list is used to make
 the 2D cutouts from the dispersed image.
 
 Algorithm
 ---------
 The step is currently applied only to NIRSpec Fixed Slit, NIRSPEC MSA, NIRSPEC TSO,
-NIRCAM WFSS and NIRISS WFSS observations.
+NIRCAM and NIRISS WFSS, and NIRCAM TSGRISM observations.
 
 For NIRSPEC:
 
@@ -68,23 +68,50 @@ of ``GrismObjects`` outside of these, the ``GrismObject`` itself can be imported
 ``jwst.transforms.models``.
 
 
+For NIRCAM TSGRISM:
+
+There is no source catalog created for TSO observations because the source is always
+placed on the same pixel, the user can only vary the size of the subarray. All of the
+subarrays have their "bottom" edge located at the physical bottom edge of the detector
+and grow in size vertically. The source spectrum trace will always be centered
+somewhere near row 34 in the vertical direction (dispersion running parallel to rows).
+So the larger subarrays will just result in larger amount of sky above the spectrum.
+
+`extract_2d` will always produce a cutout that is 64 pixels in height
+(cross-dispersion direction) for all subarrays and full frame exposures,
+which is equal to the height of the smallest available subarray (2048 x 64).
+This is to allow area within the cutout for sampling the background in later steps,
+such as `extract_1d`. The slit height is a parameter that a user can set
+(during reprocessing) to tailor their results. 
+
+
 Step Arguments
 ==============
-The extract_2d step has two optional arguments for NIRSPEC observations:
+The `extract_2d` step has two optional arguments for NIRSPEC observations:
 
 * ``--slit_name``: name (string value) of a specific slit region to
   extract. The default value of None will cause all known slits for the
   instrument mode to be extracted. Currently only used for NIRspec fixed slit
   exposures.
 
-* ``--apply_wavecorr``: bool (default is True). Flag indicating whether to apply the
-   Nirspec wavelength zero-point correction.
+* ``--apply_wavecorr``: bool (default is True). Flag indicating whether to apply the Nirspec wavelength zero-point correction.
 
 
-For NIRCAM and NIRISS, the extract_2d step has only one optional argument:
+For NIRCAM and NIRISS WFSS, the `extract_2d` step has three optional arguments:
 
 * ``--grism_objects``: list (default is empty). A list of ``jwst.transforms.models.GrismObject``.
 
+* ``--mmag_extract``: float. (default is 99.) the minimum magnitude object to extract
+
+* ``--extract_orders``: list. The list of orders to extract. The default is taken from the `wavelengthrange` reference file.
+
+
+For NIRCAM TSGRISM, the `extract_2d` step has two optional arguments:
+
+* ``--extract_orders``: list. The list of orders to extract. The default is taken from the `wavelengthrange` reference file.
+
+* ``--extract_height``: int. The cross-dispersion size to extract
+
 
 Reference Files
 ===============
@@ -94,6 +121,15 @@ with EXP_TYPE of "NRS_FIXEDSLT", "NRS_BRIGHTOBJ" or "NRS_MSASPEC". This is an op
 correction (on by default). It can be turned off by specifying ``apply_wavecorr=False``
 when running the step.
 
-NIRCAM WFSS and NIRISS WFSS observations use the wavelengthrange reference file in order
-to construct the bounding boxes around each objects orders. If a list of ``GrismObject``
+NIRCAM WFSS and NIRISS WFSS observations use the `wavelengthrange` reference file in order
+to construct the bounding boxes around each objects orders. If a list of ``GrismObject``s
 is supplied, then no reference file is neccessary.
+
+For NIRCAM WFSS and TSGRIM modes and NIRISS WFSS mode the `wavelengthrange` file contains the wavelength limits to use when caluclating the minimum and maximum dispersion extents on the detector. It also contains the default list of orders that should be extracted for each filter.
+To be consistent with other modes, and for conveniance,it also lists the orders and filters that are valid  with the file.
+
+:order: A list of orders this file covers
+:wavelengthrange: A list containing the list of [order, filter, wavelength min, wavelength max] 
+:waverange_selector: The list of FILTER names available
+:extract_orders: A list containing the list of orders to extract for each filter
+