Add function for interpreting quality flag (#350)

The `QUALITY` keyword in the AIA headers is a 32-bit integer that
denotes the quality of an observation. Flags associated with the
observation quality are encoded bit-wise, with a different message
associated with each bit flag. See [section 7.7.6 of the SDO user
guide](https://www.lmsal.com/sdodocs/doc/dcur/SDOD0060.zip/zip/entry/)
for more details.

This PR adds a function that takes in the value of the `QUALITY` key and
returns a list of messages associated with any quality flags that are
set.

Author: wtbarnes

aiapy/util/tests/test_util.py

@@ -18,3 +18,24 @@ def test_sdo_location_raises_error() -> None:
     # Confirm that an error is raised for a time without records
     with pytest.raises(RuntimeError, match="No data found for this query"):
         aiapy.util.sdo_location("2001-01-01")
+
+
+@pytest.mark.parametrize(
+    "bits",
+    [
+        [],  # nominal
+        [16],  # single message
+        [12, 13, 14, 17, 21],  # multiple messages
+        [4, 5],  # empty bits
+    ],
+)
+def test_check_quality_flag(bits):
+    quality = 0
+    for b in bits:
+        quality = quality | (1 << b)
+    messages = ["nominal"]
+    if bits:
+        from aiapy.util.util import _QUALITY_FLAG_MESSAGES
+
+        messages = [_QUALITY_FLAG_MESSAGES.get(b, "(empty)") for b in bits]
+    assert messages == aiapy.util.check_quality_flag(quality)

aiapy/util/util.py

@@ -13,7 +13,64 @@
 from aiapy.util.decorators import validate_channel
 from aiapy.util.net import _get_data_from_jsoc
 
-__all__ = ["sdo_location", "telescope_number"]
+__all__ = ["check_quality_flag", "sdo_location", "telescope_number"]
+
+# This comes from Table 2 in Section 7.7.6 of the SDO User Guide
+_QUALITY_FLAG_MESSAGES = {
+    0: "Flatfield data are not available",
+    1: "Orbit data are not available",
+    2: "Ancillary science data are not available",
+    3: "Master pointing data are not available",
+    4: "Limb-fit data are not available (generally not applicable to AIA images)",
+    8: "Value of MISSVALS keyword is nonzero",
+    9: "Value of MISSVALS keyword is more than 1% of the value of the TOTVALS keyword",
+    10: "Value of MISSVALS keyword is more than 5% of the value of the TOTVALS keyword",
+    11: "Value of MISSVALS keyword is more than 25% of the value of the TOTVALS keyword",
+    12: "Spacecraft is not in science pointing mode (coincides with ACS_MODE keyword set to a value other than SCIENCE)",
+    13: "Spacecraft eclipse flag is set (coincides with ACS_ECLP keyword set to YES)",
+    14: "Spacecraft sun presence flag is not set (coincides with ACS_SUNP keyword set to NO)",
+    15: "Spacecraft safe mode flag is set (coincides with ACS_SAFE keyword set to YES)",
+    16: "Dark image flag is set (coincides with IMG_TYPE keyword set to DARK)",
+    17: "Image Stabilization System (ISS) loop is open (coincides with AISTATE keyword set to OPEN)",
+    18: "Calibration image",
+    20: "Focus is out of range",
+    21: "Register flag is set",
+    30: "Quicklook image",
+    31: "Image is not available",
+}
+
+
+def check_quality_flag(quality):
+    """
+    Interpret the ``QUALITY`` flag in the header of an AIA observation.
+
+    AIA images are occasionally affected by operations associated with
+    calibration maneuvers or are missing data e.g. due to eclipses. For
+    these operating periods, the ``QUALITY`` keyword in the header,
+    a 32-bit integer, records the reason for the operation not being
+    nominal. Various flags for different operating modes are encoded
+    bitwise such that ``QUALITY`` can indicate multiple non-nominal
+    operating modes. For more information, see
+    `section 7.7.6 of the SDO user guide <https://www.lmsal.com/sdodocs/doc/dcur/SDOD0060.zip/zip/entry/>`__.
+    This function decodes the ``QUALITY`` flag and returns a string
+    indicating the reason(s) for the flags being set. For a nominal
+    operation (``QUALITY==0``), "nominal" is returned.
+
+    Parameters
+    ----------
+    quality: `int`
+        Quality flag encoded as an integer. This is typically found in
+        the ``QUALITY`` keyword in the FITS header.
+
+    Returns
+    -------
+    : `list`
+        Messages associated with quality flags that are set.
+    """
+    flags = [i for i in range(32) if (quality & (1 << i))]
+    if flags:
+        return [_QUALITY_FLAG_MESSAGES.get(f, "(empty)") for f in flags]
+    return ["nominal"]
 
 
 def sdo_location(time):

changelog/350.feature.rst

@@ -0,0 +1 @@
+Added a function `~aiapy.util.check_quality_flag` to interpret quality flags from ``QUALITY`` keyword.