Rcal 740 Add Data Products documentation to RTD (spacetelescope#1064)

Co-authored-by: Zach Burnett <[email protected]> Co-authored-by: Eddie Schlafly <[email protected]> Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
stscieisenhamer · Jan 19, 2024 · bddbf89 · bddbf89
1 parent afabbfd
commit bddbf89
Show file tree

Hide file tree

Showing 11 changed files with 292 additions and 4 deletions.
diff --git a/docs/_static/roman_logo_black_w200px.png b/docs/_static/roman_logo_black_w200px.png
diff --git a/docs/_static/roman_logo_white_w100px.png b/docs/_static/roman_logo_white_w100px.png
diff --git a/docs/_static/stsci_logo.png b/docs/_static/stsci_logo.png
diff --git a/docs/images/wfi_array.png b/docs/images/wfi_array.png
diff --git a/docs/index.rst b/docs/index.rst
@@ -12,6 +12,25 @@ The Roman Space Telescope Calibration Pipeline
    :align: center
    :alt: Nancy Roman Space Telescope
 
+Welcome to the documentation for the Roman calibration software,
+`romancal <https://github.com/spacetelescope/romancal>`__.
+This package contains the Python software suite for the
+Roman Space Telescope (RST) calibration pipeline, which processes data
+from the Roman Wide-Field Instrument (WFI) by applying various corrections
+to produce science-ready, calibrated output products including fully calibrated
+individual exposures as well as high-level data products (mosaics,
+catalogs, etc.). The tools in this package allow users to run and
+configure the pipeline to custom process their Roman data.
+Additionally, the romancal package contains the interface to
+Roman datamodels, the recommended method of reading and writing
+Roman data files in Python.
+
+
+If you have questions or concerns regarding the software, please contact the Roman Help
+desk at `Roman Help Desk <https://stsci.service-now.com/roman>`_.
+
+--------------------------------
+
 .. include:: roman/introduction.rst
 
 .. toctree::
@@ -27,6 +46,12 @@ The Roman Space Telescope Calibration Pipeline
    roman/pipeline_naming_conventions.rst
    roman/error_propagation/index.rst
 
+.. toctree::
+   :maxdepth: 2
+   :caption: Data Products Documentation
+
+   roman/data_products/index.rst
+
 .. toctree::
    :caption: RomanCal Package Index
    :maxdepth: 3

diff --git a/docs/roman/data_products/file_naming.rst b/docs/roman/data_products/file_naming.rst
@@ -0,0 +1,38 @@
+.. _file_naming_schemes:
+
+File Naming Schemes
+-------------------
+
+.. _exp_file_names:
+
+Exposure file names
+^^^^^^^^^^^^^^^^^^^
+The names of the exposure level data are constructed with information from the
+science header of the exposure, allowing users to map it to the observation in their corresponding
+APT files. The ASDF file naming scheme for the Exposure products is::
+
+ r<ppppp><cc><aaa><sss><ooo><vvv>_<gg><s><aa>_<eeeee>_<detector>_<prodType>.fits
+
+where
+
+ - ppppp: program ID number
+ - cc: Execution Plan number
+ - aaa: Pass Number (within execution plan)
+ - sss: Segment Number (within pass)
+ - ooo: observation number
+ - vvv: visit number
+ - gg: visit group
+ - s: sequence ID (1=prime, >1 parallel)
+ - aa: activity number (base 36)
+ - eeeee: exposure number
+ - detector: detector name (e.g. WFI01, WFI02, ...)
+ - prodType: product type identifier (e.g. 'uncal', 'cal')
+
+The standard <prodType> for the pipeline are uncal and cal, for the input products and resulting
+calibrated product. There are optional suffixes for intermediate products that are not routinely
+produced by the pipeline and are based of the processing level and can include dqinit, saturation,
+linearity, jump, darkcurrent, rampfit, assignwcs, flat, and photom.
+
+An example Exposure Level product ASDF file name is::
+
+ r0000101001001001001_01101_0001_WFI01_cal.asdf
diff --git a/docs/roman/data_products/index.rst b/docs/roman/data_products/index.rst
@@ -0,0 +1,12 @@
+.. _data_products:
+
+Data Products Information
+=========================
+
+.. toctree::
+   :maxdepth: 3
+
+   stages.rst
+   file_naming.rst
+   product_types.rst
+   science_products.rst
diff --git a/docs/roman/data_products/product_types.rst b/docs/roman/data_products/product_types.rst
@@ -0,0 +1,51 @@
+Data Product Types
+------------------
+The following tables contain lists of all data product types.
+
+
+
+Exposure Level Data Products
+++++++++++++++++++++++++++++
+
++----------------------------------------------------------------+------------------------+--------------------------+------+-----------------------+---------------------------------------+
+| Pipeline                                                       | Input                  |  Output(s)               | Base | Units                 | Description                           |
++================================================================+========================+==========================+======+=======================+=======================================+
+| :ref:`romancal.pipeline.ExposurePipeline <exposure_pipeline>`  | uncal                  | cal                      | Exp  | DN/s                  | 2-D calibrated data                   |
++----------------------------------------------------------------+------------------------+--------------------------+------+-----------------------+---------------------------------------+
+
+Exposure Step Data Products
++++++++++++++++++++++++++++
+
+The following table contain lists of all data product types for exposure pipeline, as given by their file name suffix. The input uncal file and the final cal file
+are the only files that are produced in the standard processing. All the other are optional (opt) files that can be produced when
+the user is running the pipeline. The input for each optional step is the output of the preceeding step.
+
++------------------------------------------------+-----------------+--------------------------+------------------+---------------------+---------------------------------------+
+| Pipeline Step                                  | Input           |  Output(s)               | Model            | Units               | Description                           |
++================================================+=================+==========================+==================+=====================+=======================================+
+|                                                |                 | uncal                    | ScienceRawModel  | DN                  | 3-D uncalibrated exposure data        |
++------------------------------------------------+-----------------+--------------------------+------------------+---------------------+---------------------------------------+
+| :ref:`dq_init <dq_init_step>`                  | uncal           | dq_init (opt)            | RampModel        | electron            | 3-D data quality flags applied        |
++------------------------------------------------+-----------------+--------------------------+------------------+---------------------+---------------------------------------+
+| :ref:`saturation <saturation_step>`            |                 | saturation (opt)         | RampModel        | electron            | 3-D data saturated values flagged     |
++------------------------------------------------+-----------------+--------------------------+------------------+---------------------+---------------------------------------+
+| :ref:`reference pixels <refpix>`               |                 | ref_pix (opt)            | RampModel        | electron            | 3-D ref pix corrected data            |
++------------------------------------------------+-----------------+--------------------------+------------------+---------------------+---------------------------------------+
+| :ref:`linearity <linearity_step>`              |                 | linearity (opt)          | RampModel        | electron            | 3-D linearity corrected data          |
++------------------------------------------------+-----------------+--------------------------+------------------+---------------------+---------------------------------------+
+| :ref:`dark_current <dark_current_step>`        |                 | dark_current (opt)       | RampModel        | electron            | 3-D dark current subtracted data      |
++------------------------------------------------+-----------------+--------------------------+------------------+---------------------+---------------------------------------+
+| :ref:`ramp_fitting <ramp_fitting_step>`        |                 | ramp_fit (opt)           | ImageModel       | electron/s          | 2-D slope corrected data              |
++------------------------------------------------+-----------------+--------------------------+------------------+---------------------+---------------------------------------+
+| :ref:`assign_wcs <assign_wcs_step>`            |                 | assign_wcs (opt)         | ImageModel       | electron/s          | 2-D data with gwcs                    |
++------------------------------------------------+-----------------+--------------------------+------------------+---------------------+---------------------------------------+
+| :ref:`flat_field <flatfield_step>`             |                 | flat_field (opt)         | ImageModel       | electron/s          | 2-D QE corrected data                 |
++------------------------------------------------+-----------------+--------------------------+------------------+---------------------+---------------------------------------+
+| :ref:`photom <photom_step>`                    |                 | photom (opt)             | ImageModel       | electron/s          | Add phometric data to header          |
++------------------------------------------------+-----------------+--------------------------+------------------+---------------------+---------------------------------------+
+| :ref:`source_detection <source_detection_step>`|                 | photom (opt)             | ImageModel       | electron/s          | Sources identified in the data        |
++------------------------------------------------+-----------------+--------------------------+------------------+---------------------+---------------------------------------+
+| :ref:`tweakreg <tweakreg_step>`                |                 | tweak_reg (opt)          | ImageModel       | electron/s          | WCS aligned with GAIA                 |
++------------------------------------------------+-----------------+--------------------------+------------------+---------------------+---------------------------------------+
+|                                                |                 | cal                      | ImageModel       | electrons/s         | 2-D calibrated exposure data          |
++------------------------------------------------+-----------------+--------------------------+------------------+---------------------+---------------------------------------+