diff --git a/CHANGES.rst b/CHANGES.rst index 11e2c047b..44e428212 100644 --- 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 index f56c32fc6..45a96592a 100644 --- 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 new file mode 100644 index 000000000..013abc056 --- /dev/null +++ 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 new file mode 100644 index 000000000..d214ef79c --- /dev/null +++ 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 index 5b0afb755..9dc523a81 100644 --- 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 index 070741596..785807c94 100644 --- 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 ` -and pixel :ref:`AREA ` 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 deleted file mode 100644 index be6f841db..000000000 --- a/docs/roman/references_general/area_reffile.inc +++ /dev/null @@ -1,43 +0,0 @@ -.. _area_reffile: - -AREA Reference File -------------------- - -:REFTYPE: AREA -:Data models: `~roman_datamodels.datamodels.PixelareaRefModel` - -The AREA reference file contains pixel area information for a given -detector. - -.. include:: ../references_general/area_selection.inc - -.. include:: ../includes/standard_keywords.inc - -Type Specific Keywords for AREA -+++++++++++++++++++++++++++++++ -In addition to the standard reference file keywords listed above, -the following keywords are *required* in AREA reference files, -because they are used as CRDS selectors -(see :ref:`area_selectors`): - -=============== ====================================== ============== -Attribute Fully qualified path Instruments -=============== ====================================== ============== -detector model.meta.instrument.detector WFI -=============== ====================================== ============== - - -Reference File Format -+++++++++++++++++++++ -AREA reference files are ASDF format, with 2D data arrays. -The format and content of the file is as follows -(see `~roman_datamodels.datamodels.PixelareaRefModel`): - -======= ============ ========================== ============= -Data Array Type Dimensions Data type -======= ============ ========================== ============= -area NDArray 4088 x 4088 float32 -======= ============ ========================== ============= - -The area data array contains a 2-D pixel-by-pixel map of relative -pixel areas, normalized to a value of 1.0. diff --git a/docs/roman/references_general/area_selection.inc b/docs/roman/references_general/area_selection.inc deleted file mode 100644 index fb1ad6ad2..000000000 --- a/docs/roman/references_general/area_selection.inc +++ /dev/null @@ -1,14 +0,0 @@ -.. _area_selectors: - -Reference Selection Keywords for AREA -+++++++++++++++++++++++++++++++++++++ -CRDS selects appropriate AREA references based on the following keywords. -AREA is not applicable for instruments not in the table. -All keywords used for file selection are *required*. - -========== ================================================================= -Instrument Keywords -========== ================================================================= -WFI instrument, detector, date, time -========== ================================================================= - diff --git a/docs/roman/references_general/photom_reffile.inc b/docs/roman/references_general/photom_reffile.inc index 9f7634210..b6f9d0f20 100644 --- 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 index fc3925f52..6862567c3 100644 --- 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 +========== =========================================== \ No newline at end of file diff --git a/docs/roman/references_general/references_general.rst b/docs/roman/references_general/references_general.rst index a5072110c..42d843efa 100644 --- 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 ` | :ref:`LINEARITY ` | +---------------------------------------------+--------------------------------------------------+ | :ref:`photom ` | :ref:`PHOTOM ` | -+ +--------------------------------------------------+ -| | :ref:`AREA ` | +---------------------------------------------+--------------------------------------------------+ | :ref:`ramp_fitting ` | :ref:`GAIN ` | + +--------------------------------------------------+ @@ -71,8 +69,6 @@ documentation on each reference file. +--------------------------------------------------+---------------------------------------------+ | Reference File Type (reftype) | Pipeline Step | +==================================================+=============================================+ -| :ref:`AREA ` | :ref:`photom ` | -+--------------------------------------------------+---------------------------------------------+ | :ref:`DARK ` | :ref:`dark_current ` | +--------------------------------------------------+---------------------------------------------+ | :ref:`FLAT ` | :ref:`flatfield ` |