Merge pull request #488 from PaulHuwe/RCAL-324_UpdatePhotomDocs

RCAL-324: Update documentation for photom step
spacetelescope · May 5, 2022 · c3812ba · c3812ba
2 parents aec23b9 + 32ddd2b
commit c3812ba
Show file tree

Hide file tree

Showing 11 changed files with 84 additions and 84 deletions.
diff --git a/CHANGES.rst b/CHANGES.rst
@@ -13,6 +13,9 @@ Documentation
 
 - Add documentation for DNS build 0.5, e.g. reference array trimming [#457]
 
+- Updated documentation for the photom step and removed the area reference
+  documentation. [#488]
+
 
 linearity
 ---------

diff --git a/docs/roman/introduction.rst b/docs/roman/introduction.rst
@@ -232,5 +232,6 @@ Corrected ramp data                            rampfit
 Optional fitting results from ramp_fit step    fitopt
 Assign WCS                                     assign_wcs
 Flat field                                     flat
+Photometric calibration			       phot
 Calibrated image                               cal
 =============================================  ============
diff --git a/docs/roman/photom/arguments.rst b/docs/roman/photom/arguments.rst
@@ -0,0 +1,10 @@
+Step Arguments
+==============
+
+The photometric calibration step has one step-specific argument:
+
+*  ``--photom``
+
+If the ``photom`` argument is given with a filename for its value,
+the photometric calibrated data that are created within the step will be
+saved to that file.
diff --git a/docs/roman/photom/description.rst b/docs/roman/photom/description.rst
@@ -0,0 +1,39 @@
+Description
+============
+
+Algorithm
+---------
+The ``photom`` step adds flux (photometric) calibrations to the metadata of 
+a data product. The calibration information is read from a photometric reference 
+file, and the exact nature of the calibration information loaded from the reference file
+is described below. This step does not affect the pixel values of the data product.
+
+Upon successful completion of the photometric correction, the "photom" keyword in 
+"cal_step" in the metadata is set to "COMPLETE".
+
+
+Photom and Pixel Area Data
+--------------------------------
+
+The photom reference file contains a table of
+exposure parameters that define the flux
+conversion and pixel area data for each optical element. The table contains one row
+for each optical_element, and the photom step searches the
+table for the row that matches the parameters of the science exposure and
+then loads the calibration information from that row of the table.
+
+
+
+For these table-based PHOTOM reference files, the calibration information in each
+row includes a scalar flux conversion constant, the conversion uncertainty, and the nominal pixel area.
+
+The scalar conversion constant is copied to the header keyword "conversion_megajanskys", which
+gives the conversion from DN/s to megaJy/steradian, and converted to microJy/square arcseconds and saved to 
+the header keyword "conversion_microjanskys". The same process is performed for the uncertainty, with 
+the values saved in "conversion_megajanskys_uncertainty" and "conversion_microjanskys_uncertainty", 
+respectively.
+
+The step also populates the metadata keywords "pixelarea_steradians" and "pixelarea_arcsecsq" in the
+science data product, which give the average pixel area in units of
+steradians and square arcseconds, respectively.
+
diff --git a/docs/roman/photom/index.rst b/docs/roman/photom/index.rst
@@ -7,5 +7,10 @@ Photometric Calibration
 .. toctree::
    :maxdepth: 2
 
+   description.rst
+   arguments.rst
    reference_files.rst
 
+
+.. automodapi:: romancal.photom
+
diff --git a/docs/roman/photom/reference_files.rst b/docs/roman/photom/reference_files.rst
@@ -1,8 +1,7 @@
 Reference Files
 ===============
 The ``photom`` step uses :ref:`PHOTOM <photom_reffile>`
-and pixel :ref:`AREA <area_reffile>` reference files.
+reference files.
 
 .. include:: ../references_general/photom_reffile.inc
 
-.. include:: ../references_general/area_reffile.inc
diff --git a/docs/roman/references_general/area_reffile.inc b/docs/roman/references_general/area_reffile.inc
diff --git a/docs/roman/references_general/area_selection.inc b/docs/roman/references_general/area_selection.inc
diff --git a/docs/roman/references_general/photom_reffile.inc b/docs/roman/references_general/photom_reffile.inc
@@ -16,15 +16,17 @@ pixel values into physical units.
 Type Specific Keywords for PHOTOM
 +++++++++++++++++++++++++++++++++
 In addition to the standard reference file keywords listed above,
-the following keywords are *required* in PHOTOM reference files,
-because they are used as CRDS selectors
+the following keywords are *required* in PHOTOM reference files. The first (detector) is 
+needed because it is used as a CRDS selector. The second (optical_element) is used to 
+select the appropriate set of photometric parameters.
 (see :ref:`photom_selectors`):
 
-===============   ======================================  ==============
-Attribute          Fully qualified path                    Instruments
-===============   ======================================  ==============
-detector           model.meta.instrument.detector          WFI
-===============   ======================================  ==============
+===============   =======================================  ==============
+Attribute          Fully qualified path                     Instruments
+===============   =======================================  ==============
+detector           model.meta.instrument.detector           WFI
+optical_element    model.meta.instrument.optical_element    WFI
+===============   =======================================  ==============
 
 
 Tabular PHOTOM Reference File Format
@@ -34,23 +36,25 @@ The format and content of the file is as follows
 (see `~romancal.datamodels.WfiImgPhotomRefModel`):
 
 Data is stored in a 2D table, with optical elements for the row names:
-+------------+-------------+-------------------------------------------------------+
+
++------------+---------------------------------------------------------------------+
 | Instrument | Row names                                                           |                                                       
-+============+=============+=======================================================+
++============+=====================================================================+
 | WFI        | F062, F087, F106, F129, W146, F158, F184, F213, GRISM, PRISM, DARK  | 
-+------------+-------------+-------------------------------------------------------+
++------------+---------------------------------------------------------------------+
 
 
 And the variable attributes for the columns (with data type):
+
 +------------+----------------+-----------+------------+------------------------+
 | Instrument | Column name    | Data type | Dimensions | Units                  |
-+============+=======+================+===========+============+================+
-| WFI        | photmjsr       | float     | scalar     | MJy/steradian          |
++============+================+===========+============+========================+
+| WFI        | photmjsr       | quantity  | scalar     | MJy/steradian          |
 +            +----------------+-----------+------------+------------------------+
-|            | uncertainty    | float     | scalar     | MJy/steradian          |
+|            | uncertainty    | quantity  | scalar     | MJy/steradian          |
 +            +----------------+-----------+------------+------------------------+
-|            | pixelareasr    | float     | scalar     | steradian              |
-+------------+-------+----------------+-----------+------------+----------------+
+|            | pixelareasr    | quantity  | scalar     | steradian              |
++------------+----------------+-----------+------------+------------------------+
 
 The pixelareasr variable attribute gives the average pixel area in units of steradians.
 
diff --git a/docs/roman/references_general/photom_selection.inc b/docs/roman/references_general/photom_selection.inc
@@ -2,12 +2,12 @@
 
 Reference Selection Keywords for PHOTOM
 +++++++++++++++++++++++++++++++++++++++
-CRDS selects appropriate PHOTOM references based on the following keywords.
+CRDS selects appropriate PHOTOM reference based on the following keyword.
 PHOTOM is not applicable for instruments not in the table.
 All keywords used for file selection are *required*.
 
-===============   ======================================  ==============
-Attribute           Fully qualified path                   Instruments
-===============   ======================================  ==============
-detector           model.meta.instrument.detector          WFI
-===============   ======================================  ==============
+========== ===========================================
+Instrument  Keyword Attributes                                                                                           
+========== ===========================================
+WFI	    instrument, date, time
+========== ===========================================
diff --git a/docs/roman/references_general/references_general.rst b/docs/roman/references_general/references_general.rst
@@ -57,8 +57,6 @@ documentation on each reference file.
 | :ref:`linearity <linearity_step>`           | :ref:`LINEARITY <linearity_reffile>`             |
 +---------------------------------------------+--------------------------------------------------+
 | :ref:`photom <photom_step>`                 | :ref:`PHOTOM <photom_reffile>`                   |
-+                                             +--------------------------------------------------+
-|                                             | :ref:`AREA <area_reffile>`                       |
 +---------------------------------------------+--------------------------------------------------+
 | :ref:`ramp_fitting <ramp_fitting_step>`     | :ref:`GAIN <gain_reffile>`                       |
 +                                             +--------------------------------------------------+
@@ -71,8 +69,6 @@ documentation on each reference file.
 +--------------------------------------------------+---------------------------------------------+
 | Reference File Type (reftype)                    | Pipeline Step                               |
 +==================================================+=============================================+
-| :ref:`AREA <area_reffile>`                       | :ref:`photom <photom_step>`                 |
-+--------------------------------------------------+---------------------------------------------+
 | :ref:`DARK <dark_reffile>`                       | :ref:`dark_current <dark_current_step>`     |
 +--------------------------------------------------+---------------------------------------------+
 | :ref:`FLAT <flat_reffile>`                       | :ref:`flatfield <flatfield_step>`           |