Merge pull request #223 from PaulHuwe/RCAL-134_MaskDocs

Added RTD for masks.

CHANGES.rst

@@ -17,6 +17,8 @@ general
 
 - Update setup for more strict PEP8 checking [#176]
 
+- Added documentation fo rmask files. [#181]
+
 datamodels
 ----------
 

docs/roman/includes/dq_def.inc

@@ -1,14 +1,14 @@
-The DQ_DEF extension contains the bit assignments used in the DQ array.
+The dq_def extension contains the bit assignments used in the DQ array.
 It contains the following 4 columns:
 
-===========  =======  ===============================================
-TTYPE        TFORM    Description
-===========  =======  ===============================================
-BIT          integer  The bit number, starting at zero
-VALUE        integer  The equivalent base-10 value of BIT
-NAME         string   The mnemonic name of the data quality condition
-DESCRIPTION  string   A description of the data quality condition
-===========  =======  ===============================================
+===========  ===========  =================================================
+Flags         Data Type    Description
+===========  ===========  =================================================
+BIT          int32         The bit number, starting at zero
+VALUE        uint32        The equivalent base-10 value of BIT
+NAME         string        The mnemonic name of the data quality condition
+DESCRIPTION  string        A description of the data quality condition
+===========  ===========  =================================================
 
 **NOTE:** For more information on standard bit definitions see: :ref:`Data Quality Flags`.
 

docs/roman/references_general/mask_reffile.inc

@@ -0,0 +1,50 @@
+.. _mask_reffile:
+
+MASK Reference File
+-------------------
+
+:reftype: MASK
+:Data model: `~romancal.datamodels.MaskModel`
+
+The MASK reference file contains pixel-by-pixel DQ flag values that indicate
+problem conditions.
+
+.. include:: ../references_general/mask_selection.inc
+
+.. include:: ../includes/standard_keywords.inc
+
+Type Specific Keywords for MASK
++++++++++++++++++++++++++++++++
+In addition to the standard reference file keywords listed above,
+the following keywords are *required* in MASK reference files,
+because they are used as CRDS selectors
+(see :ref:`mask_selectors`):
+
+===============   ======================================  ==============
+Attribute          Fully qualified path                    Instruments
+===============   ======================================  ==============
+detector           model.meta.instrument.detector          WFI
+===============   ======================================  ==============
+
+
+Reference File Format
++++++++++++++++++++++
+MASK reference files are ASDF format, with 2 data objects. 
+The format and content of the file is as follows:
+
+=======  ============ ==============  =============
+Data      Object Type  Dimensions      Data type
+=======  ============ ==============  =============
+dq        NDArray      4096 x 4096      uint32
+dq_def	  Table TBD
+=======  ============ ==============  =============
+
+The values in the ``dq`` array give the per-pixel flag conditions that are
+to be propagated into the science exposure's ``pixeldq`` array.
+The dimensions of the ``dq`` array should be equal to the number of columns
+and rows in a full-frame readout of a given detector, including reference
+pixels.
+
+The ASDF file contains a single dq array and dq flag definition table.
+
+.. include:: ../includes/dq_def.inc

docs/roman/references_general/mask_selection.inc

@@ -0,0 +1,12 @@
+.. _mask_selectors:
+
+Reference Selection Keywords for MASK
++++++++++++++++++++++++++++++++++++++
+CRDS selects appropriate MASK references based on the following keywords.
+MASK is not applicable for instruments not in the table.
+
+============ ==========================================================
+ Instrument   Metadata                                                   
+============ ==========================================================
+ WFI	      instrument, detector, date, time
+============ ==========================================================

docs/roman/references_general/references_general.rst

@@ -36,23 +36,27 @@ Most reference files have a one-to-one relationship with calibration steps, e.g.
 there is one step that uses one type of reference file. Some steps, however, use
 several types of reference files and some reference file types are used by more
 than one step. The tables below show the correspondence between pipeline steps and
-refernece file types. The first table is ordered by pipeline step, while the second
+reference file types. The first table is ordered by pipeline step, while the second
 is ordered by reference file type. Links to the reference file types provide detailed
 documentation on each reference file.
 
 +---------------------------------------------+--------------------------------------------------+
-| Pipeline Step                               | Reference File Type (REFTYPE)                    |
+| Pipeline Step                               | Reference File Type (reftype)                    |
 +=============================================+==================================================+
 +---------------------------------------------+--------------------------------------------------+
 | :ref:`flatfield <flatfield_step>`           | :ref:`FLAT <flat_reffile>`                       |
 +---------------------------------------------+--------------------------------------------------+
+| dq_init TBD                                 | MASK TBD with DQ                                 |
++---------------------------------------------+--------------------------------------------------+
 
 
 +--------------------------------------------------+---------------------------------------------+
-| Reference File Type (REFTYPE)                    | Pipeline Step                               |
+| Reference File Type (reftype)                    | Pipeline Step                               |
 +==================================================+=============================================+
 | :ref:`FLAT <flat_reffile>`                       | :ref:`flatfield <flatfield_step>`           |
 +--------------------------------------------------+---------------------------------------------+
+| MASK TBD with DQ                                 | dq_init TBD                                 |
++--------------------------------------------------+---------------------------------------------+
 
 .. _`Standard ASDF metadata`: