JP-3864: Move to unified bkg reftype for wfss

changes/9584.background.rst

@@ -0,0 +1 @@
+Change the background reference filetype for WFSS processing from ``wfssbkg`` to ``bkg``.

docs/jwst/background_subtraction/reference_files.rst

@@ -2,12 +2,12 @@ Reference Files
 ===============
 The background image subtraction step uses reference files only when
 processing Wide-Field Slitless Spectroscopy (WFSS) exposures. Two reference
-files are used for WFSS mode: WFSSBKG and WAVELENGTHRANGE. The
+files are used for WFSS mode: BKG and WAVELENGTHRANGE. The
 WAVELENGTHRANGE reference file is used in the process of determining the
 locations of source spectra in the image, and conversely the image areas
 that contain only background signal.
 
-.. include:: ../references_general/wfssbkg_reffile.inc
+.. include:: ../references_general/bkg_reffile.inc
 
 .. include:: ../references_general/wavelengthrange_reffile.inc
 

docs/jwst/references_general/bkg_reffile.inc

@@ -0,0 +1,66 @@
+.. _bkg_reffile:
+
+Background reference file
+-------------------------
+
+:REFTYPE: BKG
+
+The WFSS background reference file contains a "master" image of the
+dispersed background produced by a particular filter+grism combination.
+
+.. include:: ../references_general/bkg_selection.inc
+
+.. include:: ../includes/standard_keywords.inc
+
+Type Specific Keywords for BKG
+++++++++++++++++++++++++++++++
+In addition to the standard reference file keywords listed above,
+the following keywords are *required* in BKG reference files,
+because they are used as CRDS selectors.
+(see :ref:`bkg_selectors`):
+
+=========  ==============================
+Keyword    Data Model Name
+=========  ==============================
+DETECTOR   model.meta.instrument.detector
+EXP_TYPE   model.meta.exposure.type
+FILTER     model.meta.instrument.filter
+PUPIL      model.meta.instrument.pupil
+=========  ==============================
+
+Reference File Format
++++++++++++++++++++++
+BKG reference files are in FITS format. The content of the background references differ
+based on exposure type:
+
+:Data model: `~jwst.datamodels.WfssBkgModel`
+
+Wide-field slitless spectroscopy (WFSS) background files contain 3 IMAGE extensions and
+1 BINTABLE extension. The FITS primary HDU does not contain a data array.
+The characteristics of the FITS extensions are as follows:
+
+=======  ========  =====  ==============  =========
+EXTNAME  XTENSION  NAXIS  Dimensions      Data type
+=======  ========  =====  ==============  =========
+SCI      IMAGE       2    ncols x nrows   float
+ERR      IMAGE       2    ncols x nrows   float
+DQ       IMAGE       2    ncols x nrows   integer
+DQ_DEF   BINTABLE    2    TFIELDS = 4     N/A
+=======  ========  =====  ==============  =========
+
+.. include:: ../includes/dq_def.inc
+
+:Data model: `~jwst.datamodels.SossBkgModel`
+
+Background reference files supporting NIRISS SOSS exposures contain three
+image extensions, each with three dimensions. The extensions contain templates
+of reference backgrounds. The FITS primary HDU does not contain a data array.
+The characteristics of the FITS extensions are as follows:
+
+=======  ========  =====  ==========================   =========
+EXTNAME  XTENSION  NAXIS  Dimensions                   Data type
+=======  ========  =====  ==========================   =========
+SCI      IMAGE       3    ncols x nrows x ntemplates   float
+ERR      IMAGE       3    ncols x nrows x ntemplates   float
+DQ       IMAGE       3    ncols x nrows x ntemplates   integer
+=======  ========  =====  ==========================   =========

docs/jwst/references_general/wfssbkg_selection.inc → docs/jwst/references_general/bkg_selection.inc

@@ -1,9 +1,9 @@
-.. _wfssbkg_selectors:
+.. _bkg_selectors:
 
-Reference Selection Keywords for WFSSBKG
-++++++++++++++++++++++++++++++++++++++++
-CRDS selects appropriate WFSSBKG references based on the following keywords.
-WFSSBKG is not applicable for instruments not in the table.
+Reference Selection Keywords for BKG
+++++++++++++++++++++++++++++++++++++
+CRDS selects appropriate BKG references based on the following keywords.
+BKG is not applicable for instruments not in the table.
 
 ========== ===============================================================
 Instrument Keywords                                                        

docs/jwst/references_general/explain_rmaps.rst

@@ -167,14 +167,14 @@ example .imap taken from NIRSPEC::
   selector = {
     'AREA' : 'jwst_nirspec_area_0010.rmap',
     'BARSHADOW' : 'jwst_nirspec_barshadow_0002.rmap',
+    'BKG' : 'N/A',
     'CAMERA' : 'jwst_nirspec_camera_0015.rmap',
     ...,
     'PATHLOSS' : 'jwst_nirspec_pathloss_0003.rmap',
     ...,
     'WAVECORR' : 'jwst_nirspec_wavecorr_0003.rmap',
     'WAVELENGTHRANGE' : 'jwst_nirspec_wavelengthrange_0015.rmap',
     'WCSREGIONS' : 'N/A',
-    'WFSSBKG' : 'N/A',
   }
 
 A value of N/A indicates that a particular reference type is not yet used by

docs/jwst/references_general/references_general.rst

@@ -80,7 +80,7 @@ documentation on each reference file.
 +                                                       +--------------------------------------------------+
 |                                                       | :ref:`WAVELENGTHRANGE <wavelengthrange_reffile>` |
 +-------------------------------------------------------+--------------------------------------------------+
-| :ref:`background <background_subtraction>`            | :ref:`WFSSBKG <wfssbkg_reffile>`                 |
+| :ref:`background <background_subtraction>`            | :ref:`BKG <bkg_reffile>`                         |
 +                                                       +--------------------------------------------------+
 |                                                       | :ref:`WAVELENGTHRANGE <wavelengthrange_reffile>` |
 +-------------------------------------------------------+--------------------------------------------------+
@@ -312,7 +312,7 @@ documentation on each reference file.
 +--------------------------------------------------+-------------------------------------------------------+
 | :ref:`WAVECORR <wavecorr_reffile>`               | :ref:`wavecorr <wavecorr_step>`                       |
 +--------------------------------------------------+-------------------------------------------------------+
-| :ref:`WFSSBKG <wfssbkg_reffile>`                 | :ref:`background <background_subtraction>`            |
+| :ref:`BKG <bkg_reffile>`                         | :ref:`background <background_subtraction>`            |
 +--------------------------------------------------+-------------------------------------------------------+
 
 Step Parameters Reference Types
@@ -339,7 +339,7 @@ The required Keywords Documenting Contents of Reference Files are:
 ========  ==================================================================================
 Keyword   Comment
 ========  ==================================================================================
-REFTYPE   `WFSSBKG    Required values are listed in the discussion of each pipeline step.`
+REFTYPE   `BKG        Required values are listed in the discussion of each pipeline step.`
 DESCRIP   `Summary of file content and/or reason for delivery`
 AUTHOR    `Fred Jones     Person(s) who created the file`
 USEAFTER  `YYYY-MM-DDThh:mm:ss Date and time after the reference files will

jwst/background/background_step.py

@@ -32,7 +32,7 @@
     """  # noqa: E501
 
     # These reference files are only used for WFSS/GRISM or SOSS data.
-    reference_file_types = ["bkg", "wfssbkg", "wavelengthrange"]
+    reference_file_types = ["bkg", "wavelengthrange"]
 
     # Define a suffix for optional saved output of the combined background
     bkg_suffix = "combinedbackground"
@@ -60,9 +60,16 @@
 
         if result.meta.exposure.type in ["NIS_WFSS", "NRC_WFSS"]:
             # Get the reference file names
-            bkg_name = self.get_reference_file(result, "wfssbkg")
+            bkg_name = self.get_reference_file(result, "bkg")
             wlrange_name = self.get_reference_file(result, "wavelengthrange")
-            self.log.info("Using WFSSBKG reference file %s", bkg_name)
+
+            if bkg_name == "N/A":
+                self.log.warning("No BKG reference file found. Skipping background subtraction.")
+                result.meta.cal_step.bkg_subtract = "SKIPPED"
+                input_model.close()
+                return result
+
+            self.log.info("Using BKG reference file %s", bkg_name)
             self.log.info("Using WavelengthRange reference file %s", wlrange_name)
 
             # Do the background subtraction for WFSS/GRISM data