This article summarizes how users can find data quality information in Roman Wide Field Instrument (WFI) data products, including how to extract and interpret it.

Pixel-Based Data Quality Arrays

Introduction to Data Quality Flags

Data Quality (DQ) flags are bit-encoded indicators of pixel conditions or behaviors. They provide diagnostic context to users by flagging the locations of abnormal detector behavior or exposure artifacts, and they are also used in romancal pipeline processing to flag pixels that should not be used in subsequent processing steps, thereby preventing downstream calibration effects in data products. 

DQ information is stored as bit values (powers of 2; e.g., 1, 2, 4, 8, ..., 1024, 2048, etc.) in multi-dimensional arrays in Level 2 (L2) products. Multiple bit flags can be combined using a bitwise OR operation to obtain the complete set of flags (e.g., a DQ value of 1031 is made up of the flags 1 + 2 + 4 + 1024). The value of a bitwise OR operation is such that it can only be decomposed into the unique flags that make it up, with no ambiguity. The values in these DQ arrays originate from two primary sources: calibration pipeline reference files that encode known pixel behavior, and calibration pipeline steps that algorithmically identify conditions present in a specific exposure.

It is recommended that pixels containing the DQ flag value DO_NOT_USE (DQ bit 2^0=1) should be excluded from scientific analysis. This is true even when the DO_NOT_USE flag is combined with other bit values (e.g., a DQ value of 1025 is the combination of 1024 and 1); care should be taken to exclude any pixels that contain this flag.

Reference File Contributions to the Data Quality Array

Certain DQ flags originate from the Bad Pixel Mask (BPM) reference file and encode known pixel behavior families identified by instrument characterization activities. These reference files describe pixels whose abnormal properties are intrinsic to the detector rather than specific to a single exposure. During calibration processing, the BPM is applied in the romancal.dq_init.DQInitStep() step of romancal . In this step, detector BPM information is copied into the pixel DQ arrays of the data model (see the romancal.dq_init.DQInitStep() section of the Exposure Level Pipeline article for more information). These flags form the initial DQ state that subsequent calibration steps build upon. 

The BPM reference files are available in the Calibration Reference Data System (CRDS) and will be updated regularly in commissioning and operations as more on-orbit data is available and detector behavior is better understood. They are generated from analyses of calibration data, including flat-field and dark exposures. The Pixel Behavior Families article provides additional background on the algorithms used to identify these detector effects and the classes of pixels associated with them. 

The BPM currently includes flags for the following pixel classes: 

• Dead Pixels
• Low Quantum Efficiency (QE) Pixels
• Resistor-Capacitor (RC) and Inverse RC Pixels
• Telegraph Pixels
• Open Pixels and Adjacent to Open Pixels

Beyond the BPM, additional detector behavior classes are identified in other reference files derived from calibration analyses. Such reference files contain an additional DQ array encoding specific bit values relevant to that reference file. Examples include:

• Hot and Warm Pixels identified from dark current analysis
• Pixels with a non-linear response or lacking a linearity correction

The corresponding flags from these reference files are combined with the DQ arrays using a bitwise OR operation during their respective calibration steps. Some of the pixel classes listed above will, in addition to their specific flag, also have set the DO_NOT_USE flag (DQ bit 2^0=1), meaning that affected pixels are excluded from downstream pipeline calculations and are generally considered unsuitable for science analysis. Currently, dead pixels, RC and Inverse RC pixels, telegraph pixels, and open/adjacent to open pixels have an additional DO_NOT_USE flag. This list is expected to evolve on-orbit. Following this initialization from the BPM reference files, additional DQ flags may be introduced as the exposure proceeds through later calibration steps.

Calibration Step Contributions to the Data Quality Array

In addition to the detector behavior mapped in the BPM reference files, DQ flags are also introduced during subsequent steps of  romancal  processing. These flags record conditions identified in a specific exposure, such as detector response effects, transient events, or outcomes of calibration corrections.

Calibration steps do not replace existing DQ values. Instead, new flags are combined with the existing DQ array using a bitwise OR operator, preserving the full history of both detector properties and exposure-specific conditions. A single pixel, therefore, carries multiple flags simultaneously.

Examples of flags introduced during subsequent calibration steps include: 

• Pixels affected by saturation or with values less than 0 are flagged as SATURATED or AD_FLOOR, respectively, in the  romancal.saturation.SaturationStep()
• Pixels impacted by cosmic-ray events are flagged as JUMP_DET during the Jump Detection stage of the  romancal.ramp_fitting.ramp_fit_step()
• Pixels corresponding to detector regions affected by the guide window readout are flagged as GW_AFFECTED_DATA in the  romancal.dq_init.dq_init_step()

Some calibration steps may assign flags that include the DO_NOT_USE bit in addition to the specific step's flag. These pixel classes include GW_AFFECTED_DATA, AD_FLOOR, OUTLIER, and this list is expected to evolve on-orbit. Pixels carrying this bit are excluded from downstream pipeline calculations to prevent artifacts from propagating through later processing stages.

The DQ arrays produced during exposure-level calibration are used as bitmasks when generating higher-level data products.

Where to Find Data Quality Information in Roman Data Products

Level 2 (L2) Data

Calibrated exposure data products (Level 2, L2) contain a per-pixel DQ array used in scientific analysis. The array is stored alongside the science and uncertainty estimate arrays and has the same pixel dimensions as the calibrated image. The L2 DQ array combines flags originating from detector reference files, as well as those introduced during the calibration pipeline processing with  romancal  (as described in previous sections). It therefore represents the complete pixel-level data quality state for the calibrated exposure.

Additional information on the structure and contents of L2 products is provided in the  romancal  documentation.

Level 3 (L3) Mosaic Data

L3 mosaics do not contain a DQ array by default; since mosaics are combinations of many different images, there isn't a complete 1:1 relationship between the input images' DQ arrays and the L3 output DQ array. Flagged pixels in the input L2 files influence the weighting, masking, and rejection of pixels during image combination, but only pixels without the DO_NOT_USE  flag are included in the output mosaic co-added product. Users can inspect the context array in the mosaic product to see which L2 files contributed to each portion of the mosaic image, and may then examine the DQ arrays of those exposures to assess pixel-level data quality.

Note that when manually running the Mosaic Pipeline, users may select the parameter propagate_dq=True, which will create an additional DQ array in the L3 product as the bitwise addition of the input L2 product DQ arrays with the same dimensions as the output mosaic array.  Further details on mosaic pipeline processing and product structure are available in the Mosaic Pipeline article and the  romancal  documentation.

Utilizing the Data Quality Array

The DQ array stores values using a bitmask representation, so a single pixel value may have multiple DQ flags. To determine whether a specific flag is present, users can perform bitwise arithmetic between the DQ array and the flag value.

For example, to identify pixels marked with the DO_NOT_USE flag:

from romancal.lib import dqflags
do_not_use_mask = (dq & dqflags.pixel["DO_NOT_USE"]) != 0

This operation returns a boolean array indicating which pixels contain that particular flag. Similar comparisons can be used to identify any other DQ flag by substituting the appropriate flag value. The full list of Roman DQ flags and their bit values is available in the roman_datamodels  documentation.

A common use of the DQ array is to construct masks for analysis. For example, pixels not marked with the DO_NOT_USE flag can be selected using:

good_map = (dq & dqflags.pixel["DO_NOT_USE"] == 0)

This mask can then be applied when computing statistics, performing photometry, or visualizing a calibrated image. Users should interpret DQ flags in the context of their science application. Some flags indicate pixels that should generally be excluded from analysis, while others provide diagnostic information that may or may not affect a particular measurement depending on a user's science case. The previous sections describe how these flags enter the data products and where they can be found. Together, the DQ arrays and their associated flag definitions provide a consistent framework for tracking detector behavior and calibration throughout different Roman data products.

Data Quality Information in Catalog (L4) Data Products

L4 source catalogs produced by the SOC contain several columns of bit flags that indicate the quality of the measurements for that source. Additional details on the quality flag definitions and how they are set will be provided in a future RDox release.

For additional questions not answered in this article, please contact the Roman Help Desk.