DOC: Complete API for flatfield

docs/jwst/flatfield/api_ref.rst

@@ -0,0 +1,15 @@
+===
+API
+===
+
+Public Step API
+===============
+
+.. automodapi:: jwst.flatfield.flat_field_step
+   :no-inheritance-diagram:
+
+Complete Developer API
+======================
+
+.. automodapi:: jwst.flatfield.flat_field
+   :no-inheritance-diagram:

docs/jwst/flatfield/index.rst

@@ -7,7 +7,6 @@ Flatfield Correction
    :maxdepth: 2
 
    main.rst
-   reference_files.rst
    arguments.rst
-
-.. automodapi:: jwst.flatfield
+   reference_files.rst
+   api_ref.rst

docs/jwst/flatfield/main.rst

@@ -1,7 +1,7 @@
 Description
 ===========
 
-:Class: `jwst.flatfield.FlatFieldStep`
+:Class: `jwst.flatfield.flat_field_step.FlatFieldStep`
 :Alias: flat_field
 
 At its basic level this step flat-fields an input science dataset by dividing
@@ -17,7 +17,7 @@ to "COMPLETE" in the output science data.
 
 Imaging and Non-NIRSpec Spectroscopic Data
 ------------------------------------------
-Simple imaging data, usually in the form of an ImageModel, and some
+Simple imaging data, usually in the form of an `~stdatamodels.jwst.datamodels.ImageModel`, and some
 spectroscopic modes, use a straight-forward approach that involves applying
 a single flat-field reference file to the science image. The spectroscopic
 modes included in this category are NIRCam WFSS and Time-Series Grism,
@@ -75,7 +75,7 @@ that is divided into the SCI and ERR arrays is constructed on-the-fly
 by extracting the relevant section from the reference files, and then --
 for each pixel -- interpolating to the appropriate wavelength for that
 pixel.  This interpolation requires knowledge of the dispersion direction,
-which is read from keyword "DISPAXIS."  See the Reference File section for
+which is read from keyword "DISPAXIS."  See :ref:`flat_ref_nirspec_spec` for
 further details.
 
 For NIRSpec Fixed Slit (FS) and MOS exposures, an on-the-fly flat-field is
@@ -84,8 +84,8 @@ exposure. For NIRSpec IFU exposures, a single full-frame flat-field is
 constructed, which is applied to the entire science image.
 
 NIRSpec NRS_BRIGHTOBJ data are processed just like NIRSpec fixed slit
-data, except that NRS_BRIGHTOBJ data are stored in a CubeModel,
-rather than a MultiSlitModel.  A 2-D flat-field image is constructed
+data, except that NRS_BRIGHTOBJ data are stored in a `~stdatamodels.jwst.datamodels.CubeModel`,
+rather than a `~stdatamodels.jwst.datamodels.MultiSlitModel`.  A 2-D flat-field image is constructed
 on-the-fly as usual, but this image is then divided into each plane of
 the 3-D science data arrays.
 

docs/jwst/flatfield/reference_files.rst

@@ -7,13 +7,20 @@ spectroscopic exposures use the three reference files :ref:`fflat_reffile` (fore
 
 .. include:: ../references_general/flat_reffile.inc
 
+.. _flat_ref_nirspec_spec:
+
 Reference Files for NIRSpec Spectroscopy
 ========================================
 For NIRSpec spectroscopic data, the flat-field reference files allow for variations in
 the flat field with wavelength, as well as from pixel to pixel.  There is a
 separate flat-field reference file for each of three sections of the
-instrument:  the fore optics (FFLAT), the spectrograph (SFLAT), and the
-detector (DFLAT).  The contents of the reference files differ from one mode
+instrument:
+
+* the fore optics (:ref:`fflat_reffile`)
+* the spectrograph (:ref:`sflat_reffile`)
+* the detector (:ref:`dflat_reffile`)
+
+The contents of the reference files differ from one mode
 to another (see below), but in general they may contain a flat-field image and
 a 1-D array.  The image provides pixel-to-pixel values for the flat field
 that may vary slowly (or not at all) with wavelength, while the 1-D array
@@ -45,8 +52,8 @@ there are different flat fields for fixed-slit data, IFU data, and for
 multi-object spectroscopic data.  Here is a summary of the contents of these
 files.
 
-For the fore optics (FFLAT), the flat field for fixed-slit data contains just a
-FAST_VARIATION table (i.e. there is no image).  This table has five rows,
+For the fore optics (:ref:`fflat_reffile`), the flat field for fixed-slit data contains just a
+FAST_VARIATION table (i.e., there is no image).  This table has five rows,
 one for each of the fixed slits.  The FFLAT for IFU data also contains
 just a FAST_VARIATION table, but it has only one row with the value "ANY"
 in the "slit_name" column.  For multi-object spectroscopic data, the FFLAT
@@ -57,22 +64,18 @@ than to detector pixels.  The array size is 365 columns by 171 rows,
 and there are multiple planes to handle the slow variation
 of flat field with wavelength.
 
-For the spectrograph optics (SFLAT), the flat-field files have nearly the same
+For the spectrograph optics (:ref:`sflat_reffile`), the flat-field files have nearly the same
 format for fixed-slit data, IFU, and multi-object data.  The difference is
 that for fixed-slit and IFU data, the image is just a single plane,
-i.e. the only variation with wavelength is in the FAST_VARIATION table,
+i.e., the only variation with wavelength is in the FAST_VARIATION table,
 while there are multiple planes in the image for multi-object spectroscopic
 data (and therefore there is also a corresponding WAVELENGTH table, with
 one row for each plane of the image).
 
-For the detector section, the DFLAT file contains a 3-D image
-(i.e. the flat field at multiple wavelengths), a corresponding
+For the detector section, the :ref:`dflat_reffile` contains a 3-D image
+(i.e., the flat field at multiple wavelengths), a corresponding
 WAVELENGTH table, and a FAST_VARIATION table with one row.
 
-As just described, there are 3 types of reference files for NIRSpec (FFLAT,
-SFLAT, and DFLAT), and within each of these types, there are several formats,
-which are now described.
-
 .. include:: ../references_general/fflat_reffile.inc
 
 .. include:: ../references_general/sflat_reffile.inc

docs/jwst/references_general/dflat_reffile.inc

@@ -24,22 +24,22 @@ DQ_DEF         BINTABLE   2   TFIELDS = 4           N/A
 
 .. include:: ../includes/dq_def.inc
 
-The keyword NAXIS3 in the SCI extension specifies the number, n_wl, of monochromatic
-slices, each of which gives the flat_field value for every pixel for the corresponding
+The keyword NAXIS3 in the SCI extension specifies the number, ``n_wl```, of monochromatic
+slices, each of which gives the ``flat_field`` value for every pixel for the corresponding
 wavelength, which is specified in the WAVELENGTH table.
 
 The WAVELENGTH table contains a single column:
 
-* wavelength: float 1-D array, values of wavelength
+* ``wavelength``: float 1-D array, values of wavelength
 
 Each of these wavelength values corresponds to a single plane of the SCI IMAGE array.
 
 The FAST_VARIATION table contains four columns:
 
-* slit_name: the string "ANY"
-* nelem: integer, maximum number of wavelengths
-* wavelength: float 1-D array, values of wavelength
-* data: float 1-D array, flat field values for each wavelength
+* ``slit_name``: the string "ANY"
+* ``nelem``: integer, maximum number of wavelengths
+* ``wavelength``: float 1-D array, values of wavelength
+* ``data``: float 1-D array, flat field values for each wavelength
 
 The flat field values in this table are used to account for a wavelength-dependence on a
 much finer scale than given by the values in the SCI array.  There is a single row in

docs/jwst/references_general/dflat_selection.inc

@@ -5,8 +5,7 @@ DFLAT is not applicable for instruments not in the table.
 Non-standard keywords used for file selection are *required*.
 
 ========== ================================================
-Instrument Keywords                                         
+Instrument Keywords
 ========== ================================================
-NIRSpec    INSTRUME, DETECTOR, EXP_TYPE, DATE-OBS, TIME-OBS 
+NIRSpec    INSTRUME, DETECTOR, EXP_TYPE, DATE-OBS, TIME-OBS
 ========== ================================================
-

docs/jwst/references_general/fflat_reffile.inc

@@ -5,33 +5,42 @@ FFLAT Reference File
 
 :REFTYPE: FFLAT
 
-There are 3 forms of NIRSpec FFLAT reference files: fixed slit, MSA spec, and IFU.
-For each type the primary HDU does not contain a data array.
+There are 3 forms of NIRSpec FFLAT reference files:
+
+* :ref:`fflat_fixed_slit`
+* :ref:`fflat_msa`
+* :ref:`fflat_ifu`
+
+For each type, the primary HDU does not contain a data array.
 
 .. include:: ../references_general/fflat_selection.inc
 
-*Fixed Slit*
-++++++++++++
+.. _fflat_fixed_slit:
+
+Fixed Slit
+++++++++++
 :Data model: `~stdatamodels.jwst.datamodels.NirspecFlatModel`
 
-The fixed slit FFLAT files have EXP_TYPE=NRS_FIXEDSLIT, and have a single BINTABLE
+The fixed slit FFLAT files have ``EXP_TYPE=NRS_FIXEDSLIT``, and have a single BINTABLE
 extension, labeled FAST_VARIATION.
 
 The table contains four columns:
 
-* slit_name: string, name of slit
-* nelem: integer, maximum number of wavelengths
-* wavelength: float 1-D array, values of wavelength
-* data: float 1-D array, flat field values for each wavelength
+* ``slit_name``: string, name of slit
+* ``nelem``: integer, maximum number of wavelengths
+* ``wavelength``: float 1-D array, values of wavelength
+* ``data``: float 1-D array, flat field values for each wavelength
 
 The number of rows in the table is given by NAXIS2, and each row corresponds to a
 separate slit.
 
-*MSA Spec*
-++++++++++++
+.. _fflat_msa:
+
+MSA Spec
+++++++++
 :Data model: `~stdatamodels.jwst.datamodels.NirspecQuadFlatModel`
 
-The MSA Spec FFLAT files have EXP_TYPE=NRS_MSASPEC, and contain data pertaining
+The MSA Spec FFLAT files have ``EXP_TYPE=NRS_MSASPEC``, and contain data pertaining
 to each of the 4 quadrants.  For each quadrant, there is a set of 5 extensions -
 SCI, ERR, DQ, WAVELENGTH, and FAST_VARIATION.
 The file also contains a single DQ_DEF extension.
@@ -61,35 +70,37 @@ wavelength of each pixel.
 
 The WAVELENGTH table contains a single column:
 
-* wavelength: float 1-D array, values of wavelength
+* ``wavelength``: float 1-D array, values of wavelength
 
 Each of these wavelength values corresponds to a single plane of the IMAGE arrays.
 
 The FAST_VARIATION table contains four columns:
 
-* slit_name: the string "ANY"
-* nelem: integer, maximum number of wavelengths
-* wavelength: float 1-D array, values of wavelength
-* data: float 1-D array, flat field values for each wavelength
+* ``slit_name``: the string "ANY"
+* ``nelem``: integer, maximum number of wavelengths
+* ``wavelength``: float 1-D array, values of wavelength
+* ``data``: float 1-D array, flat field values for each wavelength
 
 The flat field values in this table are used to account for a wavelength-dependence on a
 much finer scale than given by the values in the SCI array.  There is a single row in
 this table, which contains 1-D arrays of wavelength and flat-field values.
 The same wavelength-dependent value is applied to all pixels in a quadrant.
 
-*IFU*
-+++++
+.. _fflat_ifu:
+
+IFU
++++
 :Data model: `~stdatamodels.jwst.datamodels.NirspecFlatModel`
 
-The IFU FFLAT files have EXP_TYPE=NRS_IFU.  These have one extension,
+The IFU FFLAT files have ``EXP_TYPE=NRS_IFU``.  These have one extension,
 a BINTABLE extension labeled FAST_VARIATION.
 
 The FAST_VARIATION table contains four columns:
 
-* slit_name: the string "ANY"
-* nelem: integer, maximum number of wavelengths
-* wavelength: float 1-D array, values of wavelength
-* data: float 1-D array, flat field values for each wavelength
+* ``slit_name``: the string "ANY"
+* ``nelem``: integer, maximum number of wavelengths
+* ``wavelength``: float 1-D array, values of wavelength
+* ``data``: float 1-D array, flat field values for each wavelength
 
 For each pixel in the science data, the wavelength of the light that fell
 on that pixel will be determined from the WAVELENGTH array in the science exposure

docs/jwst/references_general/fflat_selection.inc

@@ -5,8 +5,7 @@ FFLAT is not applicable for instruments not in the table.
 Non-standard keywords used for file selection are *required*.
 
 ========== ==============================================
-Instrument Keywords                                       
+Instrument Keywords
 ========== ==============================================
-NIRSpec    INSTRUME, FILTER, EXP_TYPE, DATE-OBS, TIME-OBS 
+NIRSpec    INSTRUME, FILTER, EXP_TYPE, DATE-OBS, TIME-OBS
 ========== ==============================================
-

docs/jwst/references_general/flat_reffile.inc

@@ -7,7 +7,8 @@ FLAT Reference File
 :Data model: `~stdatamodels.jwst.datamodels.FlatModel`
 
 The FLAT reference file contains pixel-by-pixel detector response values.
-It is used for all instrument modes except the NIRSpec spectroscopic modes.
+It is used for all instrument modes except for the
+:ref:`NIRSpec spectroscopic modes <flat_ref_nirspec_spec>`.
 
 .. include:: ../references_general/flat_selection.inc
 
@@ -55,5 +56,5 @@ used in the DQ array.
 
 For application to imaging data, the FITS file contains a single set of SCI,
 ERR, DQ, and DQ_DEF extensions.  Image dimensions should be 2048x2048 for the
-NIR detectors and 1032x1024 for MIRI (i.e. they include reference pixels),
+NIR detectors and 1032x1024 for MIRI (i.e., they include reference pixels),
 unless data were taken in subarray mode.

docs/jwst/references_general/sflat_reffile.inc

@@ -6,27 +6,36 @@ SFLAT Reference File
 :REFTYPE: SFLAT
 :Data model: `~stdatamodels.jwst.datamodels.NirspecFlatModel`
 
-There are 3 types of NIRSpec SFLAT reference files: fixed slit, MSA spec, and IFU.
-For each type the primary HDU does not contain a data array.
+There are 3 types of NIRSpec SFLAT reference files:
+
+* :ref:`sflat_fixed_slit`
+* :ref:`sflat_msa`
+* :ref:`sflat_ifu`
+
+For each type, the primary HDU does not contain a data array.
 
 .. include:: ../references_general/sflat_selection.inc
 
-*Fixed Slit*
-++++++++++++
-The fixed slit references files have EXP_TYPE=NRS_FIXEDSLIT, and have a BINTABLE
+.. _sflat_fixed_slit:
+
+Fixed Slit
+++++++++++
+The fixed slit references files have ``EXP_TYPE=NRS_FIXEDSLIT``, and have a BINTABLE
 extension labeled FAST_VARIATION. The table contains four columns:
 
-* slit_name: string, name of slit
-* nelem: integer, maximum number of wavelengths
-* wavelength: float 1-D array, values of wavelength
-* data: float 1-D array, flat field values for each wavelength
+* ``slit_name``: string, name of slit
+* ``nelem``: integer, maximum number of wavelengths
+* ``wavelength``: float 1-D array, values of wavelength
+* ``data``: float 1-D array, flat field values for each wavelength
 
 The number of rows in the table is given by NAXIS2, and each row corresponds to a
 separate slit.
 
-*MSA Spec*
-++++++++++
-The MSA Spec SFLAT files have EXP_TYPE=NRS_MSASPEC.
+.. _sflat_msa:
+
+MSA Spec
+++++++++
+The MSA Spec SFLAT files have ``EXP_TYPE=NRS_MSASPEC``.
 They contain 6 extensions, with the following characteristics:
 
 ============== ======== ===== ===================== =========
@@ -42,22 +51,22 @@ DQ_DEF         BINTABLE   2   TFIELDS = 4           N/A
 
 .. include:: ../includes/dq_def.inc
 
-The keyword NAXIS3 in the 3 IMAGE extensions specifies the number, n_wl, of monochromatic
-slices, each of which gives the flat_field value for every pixel for the corresponding
+The keyword NAXIS3 in the 3 IMAGE extensions specifies the number, ``n_wl``, of monochromatic
+slices, each of which gives the ``flat_field`` value for every pixel for the corresponding
 wavelength, which is specified in the WAVELENGTH table.
 
 The WAVELENGTH table contains a single column:
 
-* wavelength: float 1-D array, values of wavelength
+* ``wavelength``: float 1-D array, values of wavelength
 
 Each of these wavelength values corresponds to a single plane of the IMAGE arrays.
 
 The FAST_VARIATION table contains four columns:
 
-* slit_name: the string "ANY"
-* nelem: integer, maximum number of wavelengths
-* wavelength: float 1-D array, values of wavelength
-* data: float 1-D array, flat field values for each wavelength
+* ``slit_name``: the string "ANY"
+* ``nelem``: integer, maximum number of wavelengths
+* ``wavelength``: float 1-D array, values of wavelength
+* ``data``: float 1-D array, flat field values for each wavelength
 
 The flat field values in this table are used to account for a wavelength-dependence on a
 much finer scale than given by the values in the SCI array.  For each pixel in the
@@ -67,3 +76,11 @@ using the WCS interface).
 The flat-field value for that pixel will then be obtained by
 interpolating within the wavelength and data arrays from the FAST_VARIATION
 table.
+
+.. _sflat_ifu:
+
+IFU
++++
+The IFU SFLAT file has essentially the same structure as
+:ref:`sflat_fixed_slit`, except that there is only one row in the
+FAST_VARIATION table.

docs/jwst/references_general/sflat_selection.inc

@@ -9,4 +9,3 @@ Instrument Keywords
 ========== ===============================================================================
 NIRSpec    INSTRUME, DETECTOR, FILTER, GRATING, EXP_TYPE, LAMP, OPMODE, DATE-OBS, TIME-OBS
 ========== ===============================================================================
-