JP-3887: Add support for time dependent photometry corrections (#9736)

Author: melanieclarke

changes/9736.photom.rst

@@ -0,0 +1,2 @@
+Add support for time dependent photometry corrections for all instruments and modes.
+Corrections may have linear, exponential, or power law form, or any combination of these.

docs/jwst/photom/Model_summary.png

@@ -11,6 +11,6 @@ The ``photom`` step has the following optional arguments.
   Force the processing to use the given source type (POINT, EXTENDED),
   instead of using the information contained in the input data.
 
-``--mrs_time_correction`` (boolean, default=True)
-   A flag to indicate whether to turn on the time and wavelength dependent
-   correction for MIRI MRS data.
+``--apply_time_correction`` (boolean, default=True)
+   A flag to indicate whether to apply time-dependent corrections
+   if available.

docs/jwst/photom/arguments.rst

@@ -76,14 +76,6 @@ The step also computes the equivalent conversion factor to units of
 microJy/square-arcsecond (or microjanskys) and stores it in the header
 keyword PHOTUJA2.
 
-MIRI Imaging
-^^^^^^^^^^^^
-For MIRI imaging mode, the reference file can optionally contain a table of
-coefficients that are used to apply time-dependent corrections to the scalar
-conversion factor. If the time-dependent coefficients are present in the
-reference file, the photom step will apply the correction based on the
-observation date of the exposure being processed.
-
 NIRSpec Fixed Slit Primary Slit
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 The primary slit in a NIRSpec fixed slit exposure receives special handling.
@@ -164,21 +156,73 @@ from countrate to surface brightness.
 Variance arrays are multiplied by the square of the conversion factors.
 
 MIRI MRS data have a time-variable photometric response that is significant at
-long wavelengths. A correction has been derived from observations of calibration standard stars.
-The form of the correction uses an exponential function that asymptotically approaches a
-constant value in each wavelength band. A plot of the count rate loss in each MRS
+long wavelengths. A correction has been derived from regular observations of internal
+calibration lamps augmented by repeated observations of spectrophotometric standard stars.
+The correction uses a power law function of time with coefficients optimized for each
+of the twelve spectral bands. A plot of the count rate loss in each MRS
 band, as a function of time, is shown in Figure 1.
 
 .. figure:: Model_summary.png
    :scale: 50%
    :align: center
 
 Figure 1:
-Time-dependent decrease in the observed MRS count rate as measured from internal flat-field exposures.
-Solid points illustrate measurements at the central wavelength of each of the 12 MRS bands;
-curves represent the best fit models used for correction in the pipeline.
+Time-dependent decrease in the observed MRS count rate as measured from internal
+calibration lamp exposures. Points illustrate measurements at the central wavelength
+of each of the 12 MRS bands; curves represent the best fit models used for correction
+in the pipeline. See
+`JDox <https://jwst-docs.stsci.edu/jwst-calibration-status/miri-calibration-status/miri-mrs-calibration-status>`__
+for an updated version of this figure.
 
 The MRS photom reference file contains a table of correction coefficients
 for each band in which a correction has been determined. If the time-dependent
 coefficients are present in the reference file for a given band, the photom step will
 apply the correction to the exposure being processed.
+
+Time-Dependent Corrections
+--------------------------
+
+For any mode other than MIRI MRS (described above), the reference file can
+optionally contain tables of coefficients that are used to apply time-dependent
+corrections to the scalar conversion factor, based on the observation date of
+the exposure being processed. Each table present describes a different functional
+form for the time-dependent sensitivity loss: exponential, linear, or
+power law.  If multiple tables are present, the corrections are multiplied together
+before being applied.  If no tables are present, no time correction is applied.
+These coefficient tables also contain the descriptive exposure parameters present in
+the photometric data table (e.g. filter, pupil, grating), and the rows present
+must match the length and order of the photometric table.
+
+The correction factor described in all cases is defined as the fractional amount
+of light recorded now divided by the light recorded on the zero-day MJD (t0).
+The scalar conversion factor is divided by the correction factor to account for
+the sensitivity loss.
+
+For a linear correction, the correction factor (*corr*) is defined as:
+
+.. math::
+   corr = 1 - lossperyear * (t-t0) / 365
+
+where *lossperyear* (fractional loss of throughput per year, e.g., 0.1 is 10% in 1 year)
+and *t0* (reference day in MJD) are stored as coefficients in the TIMECOEFF_LINEAR
+extension of the PHOTOM reference file.
+
+For an exponential correction:
+
+.. math::
+   corr = amplitude * exp(-(t-t0)/tau) + const
+
+where *amplitude*, *t0* (reference day in MJD), *tau* (e-folding time constant), and
+*const* (long-term asymptote) are stored as coefficients in the TIMECOEFF_EXPONENTIAL
+extension.
+
+For a power law correction:
+
+.. math::
+   norm = (365 + tsoft)^{alpha} / year1value
+
+   corr = (t - t0 + tsoft)^{alpha} / norm
+
+where *year1value* (relative throughput one year after t0), *t0* (reference day in MJD),
+*tsoft* (softening parameter for the initial decline), and *alpha* (loss coefficient)
+are stored as coefficients in the TIMECOEFF_POWERLAW extension.