JP-3352 update residual fringe documentation (#8371)

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

CHANGES.rst

@@ -68,6 +68,8 @@ documentation
 
 - Updated ``outlier_detection`` for IFU data to explain the method more clearly. [#8360]
 
+- Adds documentation on the 1-D residual fringe correction for MIRI MRS data that is done in ``extract_1d``. [#8371]
+
 
 emicorr
 -------

docs/jwst/extract_1d/description.rst

@@ -276,7 +276,6 @@ aperture is centered at the RA/DEC target location indicated by the header. If t
 region is the  center of the IFU cube. For extended source data, anything specified in the reference file
 or step arguments will be ignored; the entire image will be extracted, and no background subtraction will be done.
 
-
 For point sources a circular extraction aperture is used, along with an optional
 circular annulus for background extraction and subtraction. The size of the extraction
 region and the background annulus size varies with wavelength. 
@@ -302,3 +301,53 @@ non-differentiated error term.  Note that while covariance is also extremely imp
 (as the IFUs themselves are significantly undersampled) this term is not presently computed or taken
 into account in the ``extract_1d`` step.  As such, the error estimates should be taken as a rough
 approximation that will be characterized and improved as flight data become available. 
+
+
+.. _MIRI-MRS-1D-residual-fringe:
+
+MIRI MRS 1D Residual Fringe Correction
+--------------------------------------
+For MIRI MRS IFU data there is also a correction for fringing.
+As is typical for spectrometers, the MIRI MRS detectors are affected by fringes.
+The primary MRS fringe, observed in all MRS bands, is caused by the etalons between the anti-reflection coating
+and lower layers, encompassing the detector substrate and the infrared-active layer. Since the thickness
+of the substrate is not the same in the SW and LW detectors, the fringe frequency differs in the two detectors.
+Shortward of 16 microns, this fringe is produced by the anti-reflection coating and  pixel metalization etalons, whereas
+longward of 16 microns it is produced by the anti-reflection coating and  bottom contact etalon, resulting in a
+different fringe frequency.
+
+The JWST pipeline contains multiple steps to mitigate the impact of fringing on science spectra and these
+steps generally suffice to reduce the fringe signal to below a few percent of the target flux.
+
+The first correction is applied by default in the :ref:`fringe <fringe_step>` step in the
+:ref:`calwebb_spec2 <calwebb_spec2>` pipeline and consists of dividing the uncalibrated "rate" image
+by a static fringe flat constructed from observations of a bright source that fills the entire MRS field of
+view. For more details see the :ref:`fringe <fringe_step>` step.
+This step generally does a good job of removing the strongest fringes from an astronomical scene, particularly
+for nearly-uniform extended sources. Since the fringe signal is different for point sources, however, and varies
+as a function of the location of a point source within the FOV, the static fringe flat cannot fully correct
+such objects. The default high level data products will therefore still show appreciable fringes.
+
+The pipeline also includes two optional residual fringe correction steps whose purpose is to find and remove signals
+whose periodicity is consistent with known fringe frequencies (set by the optical thickness of the detectors
+and dichroics) using a Lomb-Scargle periodogram. The number of fringe components to be removed is governed by
+a Bayesian evidence calculation. The first of these residual fringe correction steps is a 2-D correction that
+can be applied to the flux-calibrated detector data in the :ref:`residual_fringe <residual_fringe_step>` step. This step
+is part of the :ref:`calwebb_spec2 <calwebb_spec2>` pipeline, but currently it is skipped by default. For more
+information see :ref:`residual_fringe <residual_fringe_step>`.
+
+The pipeline also can apply a 1-D residual fringe correction. This correction is only relevant for MIRI MRS data and 
+can be turned on by setting the optional parameter ``extract_1d.ifu_rfcorr = True``  in the ``extract_1d`` step. 
+Empirically, the 1-D correction step has been found to work better than the 2-D correction step if it is
+applied to per-band spectra.
+
+When using the ``ifu_rfcorr`` option in the ``extract_1d`` step  to apply a 1-D residual fringe
+correction, it is applied during the extraction of spectra from the IFU cube. The 1D residual fringe code can also
+be called outside the pipeline to correct an extracted spectrum. If running outside the pipeline, the correction
+works best on single-band cubes, and the channel of
+the data must be given. The steps to run this correction outside the pipeline are::
+
+  from jwst.residual_fringe.utils import fit_residual_fringes_1d as rf1d
+  flux_cor = rf1d(flux, wave, channel=4)
+
+where ``flux`` is the extracted spectral data, and the data are from channel 4 for this example. 

docs/jwst/residual_fringe/main.rst

@@ -4,35 +4,47 @@ Description
 :Class: `jwst.residual_fringe.ResidualFringeStep`
 :Alias: residual_fringe
 
-The JWST pipeline contains two steps devoted to the removal of fringes on MIRI MRS images.
-The first correction is applied in the ``fringe_step`` in the :ref:`calwebb_spec2 <calwebb_spec2>` pipeline
-and  consists in dividing
-detector-level data by a fringe-flat and is described in the :ref:`fringe <fringe_step>` step.
-Applying the fringe flat should eliminate fringes from spectra of spatially extended sources, however
-residual fringes can remain. For spatially unresolved (point) sources or extended sources with structure,
-applying the fringe flat will undoubtedly leave residual fringes since these produce different fringe patterns
-on the detector than accounted for by the fringe flat. The second step for fringe removal is the
-``residual_fringe_step``. This step is part of the :ref:`calwebb_spec2 <calwebb_spec2>` pipeline, but currently
+The JWST pipeline contains multiple steps to mitigate the impact of fringing on science spectra, which
+generally suffice to reduce the fringe signal to below a few percent of the target flux.
+
+The first correction is applied by default in the :ref:`fringe <fringe_step>` step in the
+:ref:`calwebb_spec2 <calwebb_spec2>` pipeline
+and  consists of dividing the uncalibrated "rate" image by a static fringe flat constructed from observations of a
+bright source that fills the entire MRS field of view. For more details see the :ref:`fringe <fringe_step>` step.
+This  step generally does a good job of removing the strongest fringes from an astronomical scene, particularly
+for nearly-uniform extended sources. Since the fringe signal is different for point sources, however, and varies
+as a function of the location of a point source within the FOV, the static fringe flat cannot fully correct
+such objects and the default high level data products will therefore still
+show appreciable fringes.
+
+The pipeline also includes two optional residual fringe correction steps whose purpose is to find and remove signals
+whose periodicity is consistent with known fringe frequencies (set by the optical thickness of the detectors
+and dichroics) using a Lomb-Scargle periodogram. The number of fringe components to be removed is governed
+by a Bayesian evidence calculation.
+The first of these residual fringe correction steps is a 2-D correction that can be applied to the flux-calibrated detector data
+in the :ref:`residual_fringe <residual_fringe_step>` step. This step is part of the :ref:`calwebb_spec2 <calwebb_spec2>` pipeline, but currently
 it is skipped by default. To apply this step set the step parameter,  ``--skip = False``. This step is applied after
 :ref:`photom <photom_step>`, but before :ref:`cube_build <cube_build_step>`.
 
 
-
 The ``residual_fringe`` step can accept several different forms of input data, including:
 
 #. a single file containing a 2-D IFU image
 
 #. a data model (`~jwst.datamodels.IFUImageModel`) containing a 2-D IFU image
 
 #. an association table (in json format) containing a single input file
+
+The second of the residual fringe correction steps is a 1-D correction  that can be applied to one-dimensional
+spectra extracted from MRS data cubes by setting the optional parameter ``extract_1d.ifu_rfcorr = True``
+in the :ref:`extract_1d <extract_1d_step>` step.  Empirically, the 1-D correction step has been found to work
+better than the 2-D correction step if it is applied to per-band spectra.
+For more details on this step see :ref:`extract_1d <extract_1d_step>` step. 
 
 
 Assumptions
 -----------
 This step only works on MIRI MRS data.
-It is assumed that the calwebb_spec2 pipeline has been run on the data. In addition, the detection of residual fringes
-are  better determined if the ``mrs_imatch``  step has also been applied to the data.
-
 
 
 Fringe Background Information
@@ -52,4 +64,9 @@ produced by the anti-reflection coating and  bottom contact etalon, resulting in
 The information in the fringe frequency
 reference file  is used to determine, for each MRS band, the frequencies to fit to this main fringe component.
 The residual fringes are corrected for by fitting and removing sinusoidal gain to the detector level data.
+While the fringe frequencies are well known, amplitudes can vary due to beating between the different fringe components
+and additionally are sensitive to the detailed location and intensity of objects within a given astronomical scene.
+Fringing thus cannot be corrected in its entirety for an arbitrary astronomical scene without forward modeling.
+
+