_exposureSummaryStats.py

Go to the documentation of this file.

# This file is part of afw.
#
# Developed for the LSST Data Management System.
# This product includes software developed by the LSST Project
# (https://www.lsst.org).
# See the COPYRIGHT file at the top-level directory of this distribution
# for details of code ownership.
#
# This program is free software: you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by
# the Free Software Foundation, either version 3 of the License, or
# (at your option) any later version.
#
# This program is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
# GNU General Public License for more details.
#
# You should have received a copy of the GNU General Public License
# along with this program.  If not, see <https://www.gnu.org/licenses/>.
from __future__ import annotations
 
import dataclasses
from typing import TYPE_CHECKING
import yaml
import warnings
 
import numpy as np
 
from ..typehandling import Storable, StorableHelperFactory
 
if TYPE_CHECKING:
    from ..table import BaseRecord, Schema
 
__all__ = ("ExposureSummaryStats", )
 
 
def _default_corners():
    return [float("nan")] * 4
 
 
@dataclasses.dataclass
class ExposureSummaryStats(Storable):
    _persistence_name = 'ExposureSummaryStats'
 
    _factory = StorableHelperFactory(__name__, _persistence_name)
 
    version: int = 0
 
    psfSigma: float = float('nan')
    """PSF determinant radius (pixels)."""
 
    psfArea: float = float('nan')
    """PSF effective area (pixels**2)."""
 
    psfIxx: float = float('nan')
    """PSF shape Ixx (pixels**2)."""
 
    psfIyy: float = float('nan')
    """PSF shape Iyy (pixels**2)."""
 
    psfIxy: float = float('nan')
    """PSF shape Ixy (pixels**2)."""
 
    ra: float = float('nan')
    """Bounding box center Right Ascension (degrees)."""
 
    dec: float = float('nan')
    """Bounding box center Declination (degrees)."""
 
    pixelScale: float = float('nan')
    """Measured detector pixel scale (arcsec/pixel)."""
 
    zenithDistance: float = float('nan')
    """Bounding box center zenith distance (degrees)."""
 
    expTime: float = float('nan')
    """Exposure time of the exposure (seconds)."""
 
    zeroPoint: float = float('nan')
    """Mean zeropoint in detector (mag)."""
 
    skyBg: float = float('nan')
    """Average sky background (ADU)."""
 
    skyNoise: float = float('nan')
    """Average sky noise (ADU)."""
 
    meanVar: float = float('nan')
    """Mean variance of the weight plane (ADU**2)."""
 
    raCorners: list[float] = dataclasses.field(default_factory=_default_corners)
    """Right Ascension of bounding box corners (degrees)."""
 
    decCorners: list[float] = dataclasses.field(default_factory=_default_corners)
    """Declination of bounding box corners (degrees)."""
 
    psfAdaptiveThresholdValue: float = float('nan')
    """Threshold value used in the adaptive threshold detection pass for PSF modelling."""
 
    psfAdaptiveIncludeThresholdMultiplier: float = float('nan')
    """Threshold multiplier used in the adaptive threshold detection pass for PSF modelling."""
 
    nShapeletsStar: int = 0
    """Number of sources used in the shapelet decomposition."""
 
    shapeletsOnlyIqScore: float = float('nan')
    """The dimensionless image quality score as determined from the shapelets decomposition
    that includes power only from the non-atmospheric decomposition coefficients. The
    score spans the range [0.0, 1.0] with lower values indicating better image quality.
    """
 
    shapeletsIqScore: float = float('nan')
    """The dimensionless image quality score as determined from the shapelets decomposition
    that includes power from the median centroid offset between those used in the decomposition
    and those of the centroid slot in addition to non-atmospheric decomposition coefficients.
    The score spans the range [0.0, 1.0] with lower values indicating better image quality.
    """
 
    shapeletsCoeffs: list[float] = dataclasses.field(default_factory=list)
    """List of coefficients from the PSF star shapelet decomposition."""
 
    centroidDiffShapeletsVsSlotMedian: float = float('nan')
    """Median centroid difference (sqrt((slot_x - shapelet_x)**2 + (slot_y - shapelet_y)**2)) for
    sources used in the shapelet decomposition (pixels).
    """
 
    shapeletsStarEMedian: float = float('nan')
    """Median ellipticity (sqrt(starE1**2.0 + starE2**2.0)) of the sources used in the
    shapelet decomposition.
    """
 
    shapeletsStarUnNormalizedEMedian: float = float('nan')
    """Median un-normalized ellipticity (sqrt((starXX - starYY)**2.0 + (2.0*starXY)**2.0))
    of the sources used in the shapelet decomposition (pixels**2).
    """
 
    refCatSourceDensity: float = float('nan')
    """Source density for the detector region as computed from the loaded reference catalog
    (number per degrees**2).
    """
 
    astromOffsetMean: float = float('nan')
    """Astrometry match offset mean."""
 
    astromOffsetStd: float = float('nan')
    """Astrometry match offset stddev."""
 
    nPsfStar: int = 0
    """Number of stars used for psf model."""
 
    psfStarDeltaE1Median: float = float('nan')
    """Psf stars median E1 residual (starE1 - psfE1)."""
 
    psfStarDeltaE2Median: float = float('nan')
    """Psf stars median E2 residual (starE2 - psfE2)."""
 
    psfStarDeltaE1Scatter: float = float('nan')
    """Psf stars MAD E1 scatter (starE1 - psfE1)."""
 
    psfStarDeltaE2Scatter: float = float('nan')
    """Psf stars MAD E2 scatter (starE2 - psfE2)."""
 
    psfStarDeltaSizeMedian: float = float('nan')
    """Psf stars median size residual (starSize - psfSize)."""
 
    psfStarDeltaSizeScatter: float = float('nan')
    """Psf stars MAD size scatter (starSize - psfSize)."""
 
    psfStarScaledDeltaSizeScatter: float = float('nan')
    """Psf stars MAD size scatter scaled by psfSize**2."""
 
    psfTraceRadiusDelta: float = float('nan')
    """Delta (max - min) of the model psf trace radius values evaluated on a
    grid of unmasked pixels (pixels).
    """
 
    psfApFluxDelta: float = float('nan')
    """Delta (max - min) of the model psf aperture flux (with aperture radius of
    max(2, 3*psfSigma)) values evaluated on a grid of unmasked pixels.
    """
 
    psfApCorrSigmaScaledDelta: float = float('nan')
    """Delta (max - min) of the psf flux aperture correction factors scaled (divided)
    by the psfSigma evaluated on a grid of unmasked pixels.
    """
 
    maxDistToNearestPsf: float = float('nan')
    """Maximum distance of an unmasked pixel to its nearest model psf star
    (pixels).
    """
 
    starEMedian: float = float('nan')
    """Median ellipticity (sqrt(starE1**2.0 + starE2**2.0)) of the stars used
    in the PSF model.
    """
 
    starUnNormalizedEMedian: float = float('nan')
    """Median un-normalized ellipticity (sqrt((starXX - starYY)**2.0 + (2.0*starXY)**2.0))
    of the stars used in the PSF model (pixel**2).
    """
 
    starComa1Median: float = float('nan')
    """Coma-like higher-order moment combination: median M30 + M12
    of the stars used in the PSF model.
    """
 
    starComa2Median: float = float('nan')
    """Coma-like higher-order moment combination: median M21 + M03
    of the stars used in the PSF model.
    """
 
    starTrefoil1Median: float = float('nan')
    """Trefoil-like higher-order moment combination: median M30 - 3*M12
    of the stars used in the PSF model.
    """
 
    starTrefoil2Median: float = float('nan')
    """Trefoil-like higher-order moment combination: median 3*M21 - M03
    of the stars used in the PSF model.
    """
 
    starKurtosisMedian: float = float('nan')
    """Kurtosis-like higher-order moment combination: median M40 + 2*M22 + M04
    of the stars used in the PSF model.
    """
 
    starE41Median: float = float('nan')
    """Fourth-order ellipticity-like higher-order moment combination: median M40 - M04
    of the stars used in the PSF model.
    """
 
    starE42Median: float = float('nan')
    """Fourth-order ellipticity-like higher-order moment combination: median 2*(M31 + M13)
    of the stars used in the PSF model.
    """
 
    effTime: float = float('nan')
    """Effective exposure time calculated from psfSigma, skyBg, and
    zeroPoint (seconds).
    """
 
    effTimePsfSigmaScale: float = float('nan')
    """PSF scaling of the effective exposure time."""
 
    effTimeSkyBgScale: float = float('nan')
    """Sky background scaling of the effective exposure time."""
 
    effTimeZeroPointScale: float = float('nan')
    """Zeropoint scaling of the effective exposure time."""
 
    magLim: float = float('nan')
    """Magnitude limit at fixed SNR (default SNR=5) calculated from psfSigma, skyBg,
    zeroPoint, and readNoise.
    """
 
    def __post_init__(self):
        Storable.__init__(self)
 
    def isPersistable(self):
        return True
 
    def _getPersistenceName(self):
        return self._persistence_name
 
    def _getPythonModule(self):
        return __name__
 
    def _write(self):
        return yaml.dump(dataclasses.asdict(self), encoding='utf-8')
 
    @staticmethod
    def _read(bytes):
        yamlDict = yaml.load(bytes, Loader=yaml.SafeLoader)
 
        # Special list of fields to forward to new names.
        forwardFieldDict = {"decl": "dec"}
 
        # For forwards compatibility, filter out any fields that are
        # not defined in the dataclass.
        droppedFields = []
        for _field in list(yamlDict.keys()):
            if _field not in ExposureSummaryStats.__dataclass_fields__:
                if _field in forwardFieldDict and forwardFieldDict[_field] not in yamlDict:
                    yamlDict[forwardFieldDict[_field]] = yamlDict[_field]
                else:
                    droppedFields.append(_field)
                yamlDict.pop(_field)
        if len(droppedFields) > 0:
            droppedFieldString = ", ".join([str(f) for f in droppedFields])
            plural = "s" if len(droppedFields) != 1 else ""
            them = "them" if len(droppedFields) > 1 else "it"
            warnings.warn(
                f"Summary field{plural} [{droppedFieldString}] not recognized by this software version;"
                f" ignoring {them}.",
                FutureWarning,
                stacklevel=2,
            )
        return ExposureSummaryStats(**yamlDict)
 
    @classmethod
    def update_schema(cls, schema: Schema) -> None:
        """Update an schema to includes for all summary statistic fields.
 
        Parameters
        -------
        schema : `lsst.afw.table.Schema`
            Schema to add which fields will be added.
        """
        schema.addField(
            "psfSigma",
            type="F",
            doc="PSF model second-moments determinant radius (center of chip) (pixel)",
            units="pixel",
        )
        schema.addField(
            "psfArea",
            type="F",
            doc="PSF model effective area (center of chip) (pixel**2)",
            units='pixel**2',
        )
        schema.addField(
            "psfIxx",
            type="F",
            doc="PSF model Ixx (center of chip) (pixel**2)",
            units='pixel**2',
        )
        schema.addField(
            "psfIyy",
            type="F",
            doc="PSF model Iyy (center of chip) (pixel**2)",
            units='pixel**2',
        )
        schema.addField(
            "psfIxy",
            type="F",
            doc="PSF model Ixy (center of chip) (pixel**2)",
            units='pixel**2',
        )
        schema.addField(
            "raCorners",
            type="ArrayD",
            size=4,
            doc="Right Ascension of bounding box corners (degrees)",
            units="degree",
        )
        schema.addField(
            "decCorners",
            type="ArrayD",
            size=4,
            doc="Declination of bounding box corners (degrees)",
            units="degree",
        )
        schema.addField(
            "ra",
            type="D",
            doc="Right Ascension of bounding box center (degrees)",
            units="degree",
        )
        schema.addField(
            "dec",
            type="D",
            doc="Declination of bounding box center (degrees)",
            units="degree",
        )
        schema.addField(
            "zenithDistance",
            type="F",
            doc="Zenith distance of bounding box center (degrees)",
            units="degree",
        )
        schema.addField(
            "pixelScale",
            type="F",
            doc="Measured detector pixel scale (arcsec/pixel)",
            units="arcsec/pixel",
        )
        schema.addField(
            "expTime",
            type="F",
            doc="Exposure time of the exposure (seconds)",
            units="second",
        )
        schema.addField(
            "zeroPoint",
            type="F",
            doc="Mean zeropoint in detector (mag)",
            units="mag",
        )
        schema.addField(
            "skyBg",
            type="F",
            doc="Average sky background (ADU)",
            units="adu",
        )
        schema.addField(
            "skyNoise",
            type="F",
            doc="Average sky noise (ADU)",
            units="adu",
        )
        schema.addField(
            "meanVar",
            type="F",
            doc="Mean variance of the weight plane (ADU**2)",
            units="adu**2"
        )
        schema.addField(
            "psfAdaptiveThresholdValue",
            type="F",
            doc="Threshold value used in the adaptive threshold detection pass for PSF modelling.",
            units="",
        )
        schema.addField(
            "psfAdaptiveIncludeThresholdMultiplier",
            type="F",
            doc="Threshold multiplier used in the adaptive threshold detection pass for PSF modelling.",
            units="",
        )
        schema.addField(
            "nShapeletsStar",
            type="I",
            doc="Number of sources used in the shapelet decomposition.",
            units="count",
        )
        schema.addField(
            "shapeletsOnlyIqScore",
            type="F",
            doc="The dimensionless image quality score as determined from the shapelets "
            "decomposition that includes power only from the non-atmospheric decomposition "
            "coefficients. The score spans the range [0.0, 1.0] with lower values indicating "
            "better image quality.",
            units="",
        )
        schema.addField(
            "shapeletsIqScore",
            type="F",
            doc="The dimensionless image quality score as determined from the shapelets "
            "decomposition that includes power from the median centroid offset between those "
            "used in the decomposition and those of the centroid slot in addition to "
            "non-atmospheric decomposition coefficients. The score spans the range [0.0, 1.0] "
            "with lower values indicating better image quality.",
            units="",
        )
        schema.addField(
            "shapeletsCoeffs",
            type="ArrayD",
            size=0,  # dynamic size
            doc="List of coefficients from the PSF star shapelet decomposition.",
            units="",
        )
        schema.addField(
            "centroidDiffShapeletsVsSlotMedian",
            type="F",
            doc="Median centroid difference (sqrt((slot_x - shapelet_x)**2 + (slot_y - shapelet_y)**2)) "
            "for sources used in the shapelet decomposition.",
            units="pixel",
        )
        schema.addField(
            "shapeletsStarEMedian",
            type="F",
            doc="Median ellipticity (sqrt(starE1**2.0 + starE2**2.0)) of the stars used in the "
            "shapelet decomposition.",
            units="",
        )
        schema.addField(
            "shapeletsStarUnNormalizedEMedian",
            type="F",
            doc="Median un-normalized ellipticity (sqrt((starXX - starYY)**2.0 + (2.0*starXY)**2.0)) "
            "of the stars used in the shapelet decomposition.",
            units="pixel**2",
        )
        schema.addField(
            "refCatSourceDensity",
            type="F",
            doc="Source density for the detector region as computed from the loaded reference catalog "
            "(number per degrees**2)",
            units="degree**-2",
        )
        schema.addField(
            "astromOffsetMean",
            type="F",
            doc="Mean offset of astrometric calibration matches (arcsec)",
            units="arcsec",
        )
        schema.addField(
            "astromOffsetStd",
            type="F",
            doc="Standard deviation of offsets of astrometric calibration matches (arcsec)",
            units="arcsec",
        )
        schema.addField("nPsfStar", type="I", doc="Number of stars used for PSF model")
        schema.addField(
            "psfStarDeltaE1Median",
            type="F",
            doc="Median E1 residual (starE1 - psfE1) for psf stars",
        )
        schema.addField(
            "psfStarDeltaE2Median",
            type="F",
            doc="Median E2 residual (starE2 - psfE2) for psf stars",
        )
        schema.addField(
            "psfStarDeltaE1Scatter",
            type="F",
            doc="Scatter (via MAD) of E1 residual (starE1 - psfE1) for psf stars",
        )
        schema.addField(
            "psfStarDeltaE2Scatter",
            type="F",
            doc="Scatter (via MAD) of E2 residual (starE2 - psfE2) for psf stars",
        )
        schema.addField(
            "psfStarDeltaSizeMedian",
            type="F",
            doc="Median size residual (starSize - psfSize) for psf stars (pixel)",
            units="pixel",
        )
        schema.addField(
            "psfStarDeltaSizeScatter",
            type="F",
            doc="Scatter (via MAD) of size residual (starSize - psfSize) for psf stars (pixel)",
            units="pixel",
        )
        schema.addField(
            "psfStarScaledDeltaSizeScatter",
            type="F",
            doc="Scatter (via MAD) of size residual scaled by median size squared",
        )
        schema.addField(
            "psfTraceRadiusDelta",
            type="F",
            doc="Delta (max - min) of the model psf trace radius values evaluated on a grid of "
            "unmasked pixels (pixel).",
            units="pixel",
        )
        schema.addField(
            "psfApFluxDelta",
            type="F",
            doc="Delta (max - min) of the model psf aperture flux (with aperture radius of "
            "max(2, 3*psfSigma)) values evaluated on a grid of unmasked pixels.",
        )
        schema.addField(
            "psfApCorrSigmaScaledDelta",
            type="F",
            doc="Delta (max - min) of the model psf aperture correction factors scaled (divided) "
            "by the psfSigma evaluated on a grid of unmasked pixels.",
        )
        schema.addField(
            "maxDistToNearestPsf",
            type="F",
            doc="Maximum distance of an unmasked pixel to its nearest model psf star (pixel).",
            units="pixel",
        )
        schema.addField(
            "starEMedian",
            type="F",
            doc="Median ellipticity (sqrt(starE1**2.0 + starE2**2.0)) of the stars used in "
            "the PSF model.",
        )
        schema.addField(
            "starUnNormalizedEMedian",
            type="F",
            doc="Median un-normalized ellipticity (sqrt((starXX - starYY)**2.0 + (2.0*starXY)**2.0)) "
            "of the stars used in the PSF model.",
        )
        schema.addField(
            "starComa1Median",
            type="F",
            doc="Coma-like higher-order moment combination: median M30 + M12 "
            "of the stars used in the PSF model.",
        )
        schema.addField(
            "starComa2Median",
            type="F",
            doc="Coma-like higher-order moment combination: median M21 + M03 "
            "of the stars used in the PSF model.",
        )
        schema.addField(
            "starTrefoil1Median",
            type="F",
            doc="Trefoil-like higher-order moment combination: median M30 - 3*M12 "
            "of the stars used in the PSF model.",
        )
        schema.addField(
            "starTrefoil2Median",
            type="F",
            doc="Trefoil-like higher-order moment combination: median 3*M21 - M03 "
            "of the stars used in the PSF model.",
        )
        schema.addField(
            "starKurtosisMedian",
            type="F",
            doc="Kurtosis-like higher-order moment combination: median M40 + 2*M22 + M04 "
            "of the stars used in the PSF model.",
        )
        schema.addField(
            "starE41Median",
            type="F",
            doc="Fourth-order ellipticity-like higher-order moment combination: median M40 - M04 "
            "of the stars used in the PSF model.",
        )
        schema.addField(
            "starE42Median",
            type="F",
            doc="Fourth-order ellipticity-like higher-order moment combination: median 2*(M31 + M13) "
            "of the stars used in the PSF model.",
        )
        schema.addField(
            "effTime",
            type="F",
            doc="Effective exposure time calculated from psfSigma, skyBg, and "
            "zeroPoint (seconds).",
            units="second",
        )
        schema.addField(
            "effTimePsfSigmaScale",
            type="F",
            doc="PSF scaling of the effective exposure time."
        )
        schema.addField(
            "effTimeSkyBgScale",
            type="F",
            doc="Sky background scaling of the effective exposure time."
        )
        schema.addField(
            "effTimeZeroPointScale",
            type="F",
            doc="Zeropoint scaling of the effective exposure time."
        )
        schema.addField(
            "magLim",
            type="F",
            doc="Magnitude limit at SNR=5 (M5) calculated from psfSigma, "
            "skyBg, zeroPoint, and readNoise.",
            units="mag",
        )
 
    def update_record(self, record: BaseRecord) -> None:
        """Write summary-statistic columns into a record.
 
        Parameters
        ----------
        record : `lsst.afw.table.BaseRecord`
            Record to update.  This is expected to frequently be an
            `ExposureRecord` instance (with higher-level code adding other
            columns and objects), but this method can work with any record
            type.
        """
        for field in dataclasses.fields(self):
            value = getattr(self, field.name)
            if field.name == "version":
                continue
            elif field.type.startswith("list"):
                record[field.name] = np.array(value, dtype=record[field.name].dtype)
            else:
                record[field.name] = value
 
    @classmethod
    def from_record(cls, record: BaseRecord) -> ExposureSummaryStats:
        """Read summary-statistic columns from a record into ``self``.
 
        Parameters
        ----------
        record : `lsst.afw.table.BaseRecord`
            Record to read from.  This is expected to frequently be an
            `ExposureRecord` instance (with higher-level code adding other
            columns and objects), but this method can work with any record
            type, ignoring any attributes or columns it doesn't recognize.
 
        Returns
        -------
        summary : `ExposureSummaryStats`
            Summary statistics object created from the given record.
        """
        return cls(
            **{
                field.name: (
                    record[field.name] if not field.type.startswith("list")
                    else [float(v) for v in record[field.name]]
                )
                for field in dataclasses.fields(cls)
                if field.name != "version"
            }
        )