JP-3794: Add trace-based extraction option for NIRSpec

changes/9022.extract_1d.rst

@@ -0,0 +1,2 @@
+Expanded the ``use_source_posn`` option to calculate a source trace from WCS and expected source positions for unresampled NIRSpec and MIRI LRS fixed slit data.
+Added the step parameter ``position_offset`` to allow an additional aperture offset in pixels.

docs/jwst/extract_1d/arguments.rst

@@ -26,9 +26,13 @@ Step Arguments for Slit and Slitless Spectroscopic Data
   file should be shifted to account for the expected position of the source. If None (the default),
   the step will decide whether to use the source position based
   on the observing mode and the source type. By default, source position corrections
-  are attempted only for NIRSpec MOS and NIRSpec and MIRI LRS fixed-slit point sources.
+  are attempted only for point sources in NIRSpec MOS/FS/BOTS and MIRI LRS fixed-slit exposures.
   Set to False to ignore position estimates for all modes; set to True to additionally attempt
-  source position correction for NIRSpec BOTS data or extended sources.
+  source position correction for extended sources.
+
+``--position_offset``
+  Specify a number of pixels (fractional pixels are allowed) to offset the 
+  extraction aperture from the nominal position.  The default is 0.
 
 ``--smoothing_length``
   If ``smoothing_length`` is greater than 1 (and is an odd integer), the

docs/jwst/extract_1d/description.rst

@@ -160,17 +160,26 @@ If `extract_width` is also given, the start and stop values are used to define
 the center of the extraction region in the cross-dispersion direction, but the
 width of the aperture is set by the `extract_width` value.
 
-For some instruments and modes, the cross-dispersion start and stop values may be shifted
-to account for the expected location of the source.  This option
-is available for NIRSpec MOS, fixed-slit, and BOTS data, as well as MIRI LRS fixed-slit.
+For some instruments and modes, the extraction region may be adjusted
+to account for the expected location of the source with the `use_source_posn` 
+option. This option is available for NIRSpec MOS, fixed-slit, and BOTS data, 
+as well as MIRI LRS fixed-slit.
 If `use_source_posn` is set to None via the reference file or input parameters,
-it is turned on by default for all point sources in these modes, except NIRSpec BOTS.
-To turn it on for NIRSpec BOTS or extended sources, set `use_source_posn` to True.
+it is turned on by default for all point sources in these modes.
+To turn it on for extended sources, set `use_source_posn` to True.
 To turn it off for any mode, set `use_source_posn` to False.
-If source position correction is enabled, the planned location for the source is
-calculated internally, via header metadata recording the source position and the
-spectral WCS transforms, then used to offset the extraction start and stop values
-in the cross-dispersion direction.
+If source position option is enabled, the planned location for the source and its 
+trace are calculated internally via header metadata recording the source position 
+and the spectral WCS transforms.  The source location will be used to offset the 
+extraction start and stop values in the cross-dispersion direction.
+If `extract_width` is provided, the source extraction region will be centered 
+on the calculated trace with a width set by the `extract_width` value.  
+For resampled, "s2d", products this will effectively be the rectangular 
+extraction region offset in the cross-dispersion direction.  For 
+"cal" or "calints" products that have not been resampled, the extraction region 
+will be curved to follow the calculated trace.
+If no `extract_width` has been provided, the shifted extraction start and 
+stop values will be used.
 
 A more flexible way to specify the source extraction region is via the `src_coeff`
 parameter. `src_coeff` is specified as a list of lists of floating-point