rubin-sim 2.6.1.dev2__py3-none-any.whl

rubin_sim/maf/metrics/snr_weight.py

@@ -0,0 +1,24 @@
+__all__ = ("SnrWeightedMetric",)
+
+import numpy as np
+
+from rubin_sim.maf.utils import m52snr
+
+from .base_metric import BaseMetric
+
+
+class SnrWeightedMetric(BaseMetric):
+    """Take the SNR weighted average of a column."""
+
+    def __init__(self, col, m5_col="fiveSigmaDepth", metric_name=None, **kwargs):
+        if metric_name is None:
+            metric_name = "SNR Weighted %s" % col
+        super(SnrWeightedMetric, self).__init__(col=[m5_col, col], metric_name=metric_name, **kwargs)
+        self.m5_col = m5_col
+        self.col = col
+        self.star_mag = 20.0  # Arbitrary reference, value doesn't matter
+
+    def run(self, data_slice, slice_point=None):
+        snr = m52snr(self.star_mag, data_slice[self.m5_col])
+        result = np.average(data_slice[self.col], weights=snr)
+        return result

rubin_sim/maf/metrics/star_density.py

@@ -0,0 +1,77 @@
+__all__ = ("StarDensityMetric",)
+
+import warnings
+
+from scipy.interpolate import interp1d
+
+from .base_metric import BaseMetric
+
+
+class StarDensityMetric(BaseMetric):
+    """Interpolate the stellar luminosity function to return the number of
+    stars per square arcsecond brighter than the mag_limit.
+    Note that the map is built from CatSim stars in the range 20 < r < 28.
+    mag_limit values outside that the range of the map's starMapBins will
+    return self.badval
+
+    The stellar density maps are available in any bandpass, but bandpasses
+    other than r band must use a pre-configured StellarDensityMap (not just the
+    default). In other words, when setting up the metric bundle for an i-band
+    stellar density using (as an example) a HealpixSlicer:
+    ```
+    map = maf.StellarDensityMap(filtername='i')
+    metric = maf.StarDensityMetric(filtername='i', mag_limit=25.0)
+    slicer = maf.HealpixSlicer()
+    bundle = maf.MetricBundle(metric, slicer, "", mapsList=[map])
+    ```
+
+    Parameters
+    ----------
+    mag_limit : `float`, opt
+        Magnitude limit at which to evaluate the stellar luminosity function.
+        Returns number of stars per square arcsecond brighter than this limit.
+        Default 25.
+    filtername : `str`, opt
+        Which filter to evaluate the luminosity function in; Note that using
+        bands other than r will require setting up a custom (rather than
+        default) version of the stellar density map.
+        Default r.
+    units : `str`, opt
+        Units for the output values. Default "stars/sq arcsec".
+    maps : `list` of `str`, opt
+        Names for the maps required. Default "StellarDensityMap".
+
+    Returns
+    -------
+    result : `float`
+        Number of stars brighter than mag_limit in filtername, based on the
+        stellar density map.
+    """
+
+    def __init__(
+        self, mag_limit=25.0, filtername="r", units="stars/sq arcsec", maps=["StellarDensityMap"], **kwargs
+    ):
+        super(StarDensityMetric, self).__init__(col=[], maps=maps, units=units, **kwargs)
+        self.mag_limit = mag_limit
+        if "rmagLimit" in kwargs:
+            warnings.warn(
+                "rmagLimit is deprecated; please use mag_limit instead "
+                "(will use the provided rmagLimit for now)."
+            )
+            self.mag_limit = kwargs["rmagLimit"]
+        self.filtername = filtername
+
+    def run(self, data_slice, slice_point=None):
+        # Interpolate the data to the requested mag
+        interp = interp1d(
+            slice_point["starMapBins_%s" % self.filtername][1:],
+            slice_point["starLumFunc_%s" % self.filtername],
+        )
+        # convert from stars/sq degree to stars/sq arcsec
+        try:
+            result = interp(self.mag_limit) / (3600.0**2)
+        except ValueError:
+            # This probably means the interpolation went out of range
+            # (magLimit <15 or >28)
+            return self.badval
+        return result

rubin_sim/maf/metrics/string_count_metric.py

@@ -0,0 +1,95 @@
+__all__ = ("StringCountMetric",)
+
+from collections import Counter
+
+import numpy as np
+
+from .base_metric import BaseMetric
+
+
+class Keylookerupper:
+    """Helper object to unpack dictionary values as reduceFunction results."""
+
+    def __init__(self, key="blank", name=None):
+        self.key = key
+        self.__name__ = name
+
+    def __call__(self, indict):
+        return np.max(indict[self.key])
+
+
+class StringCountMetric(BaseMetric):
+    """Count up the number of times each string appears in a column.
+
+    Dynamically builds reduce functions for each unique string value,
+    so summary stats can be named the same as strings in the
+    simData array without knowing the values of those strings ahead of time.
+
+
+    Parameters
+    ----------
+    metric_name : `str`, opt
+        Name of the metric.
+    col : `str`, opt
+        Column name that has strings to look at.
+    percent : `bool`, opt
+        Normalize and return results as percents rather than raw count.
+    clip_end : `bool`
+        Clip if the end of a string if it ends with a comma and number.
+    """
+
+    def __init__(
+        self, metric_name="stringCountMetric", col="filter", percent=False, clip_end=False, **kwargs
+    ):
+        if percent:
+            units = "percent"
+        else:
+            units = "count"
+        self.percent = percent
+        cols = [col]
+        super().__init__(cols, metric_name, units=units, metric_dtype=object, **kwargs)
+        self.col = col
+        self.clip_end = clip_end
+
+    def run(self, data_slice, slice_point=None):
+
+        # If we need to clip off trailing integer
+        if self.clip_end:
+            replace_col = []
+            for val in data_slice[self.col]:
+                if ", " in val:
+                    chunks = val.split(", ")
+                    if chunks[-1].isdigit():
+                        new_val = ", ".join(chunks[0:-1])
+                        replace_col.append(new_val)
+                    else:
+                        replace_col.append(val)
+                else:
+                    replace_col.append(val)
+            data_slice[self.col] = replace_col
+
+        counter = Counter(data_slice[self.col])
+        # convert to a numpy array
+        lables = list(counter.keys())
+        # Numpy can't handle empty string as a dtype
+        lables = [x if x != "" else "blank" for x in lables]
+        metric_value = np.zeros(1, dtype=list(zip(lables, [float] * len(counter.keys()))))
+        for key in counter:
+            if key == "":
+                metric_value["blank"] = counter[key]
+            else:
+                metric_value[key] = counter[key]
+        if self.percent:
+            norm = sum(metric_value[0]) / 100.0
+            # Not sure I really like having to loop here,
+            # but the dtype is inflexible
+            for key in metric_value.dtype.names:
+                metric_value[key] = metric_value[key] / norm
+
+        # Now to dynamically set up the reduce functions
+        for i, key in enumerate(metric_value.dtype.names):
+            name = key
+            self.reduce_funcs[name] = Keylookerupper(key=key, name=name)
+            self.reduce_order[name] = i
+
+        return metric_value

rubin_sim/maf/metrics/summary_metrics.py

@@ -0,0 +1,201 @@
+__all__ = (
+    "FootprintFractionMetric",
+    "FOArea",
+    "FONv",
+    "IdentityMetric",
+    "NormalizeMetric",
+    "ZeropointMetric",
+)
+
+
+import healpy as hp
+import numpy as np
+
+from .base_metric import BaseMetric
+
+# Metrics which are primarily intended to be used as summary statistics.
+
+
+class FootprintFractionMetric(BaseMetric):
+    """Calculate fraction of a desired footprint got covered.
+    Helpful to check if everything was covered in first year
+
+    Parameters
+    ----------
+    footprint : `np.ndarray`, (N,)
+        The HEALpix footprint to compare to.
+        Nside of the footprint should match nside of the slicer.
+    n_min : `int`
+        The number of visits to require to consider an area covered
+    """
+
+    def __init__(self, footprint=None, n_min=1, **kwargs):
+        super().__init__(**kwargs)
+        self.footprint = footprint
+        self.nside = hp.npix2nside(footprint.size)
+        self.npix = np.where(self.footprint > 0)[0].size
+        # get whole array passed
+        self.mask_val = 0
+        self.n_min = n_min
+
+    def run(self, data_slice, slice_point=None):
+        overlap = np.where((self.footprint > 0) & (data_slice["metricdata"] >= self.n_min))[0]
+        result = overlap.size / self.npix
+        return result
+
+
+class FONv(BaseMetric):
+    """Given asky area, what is the minimum and median NVISITS obtained over
+    that area?
+    (chooses the portion of the sky with the highest number of visits first).
+
+    Parameters
+    ----------
+    col : `str` or `list` of `strs`, optional
+        Name of the column in the numpy recarray passed to the summary metric.
+    asky : `float`, optional
+        Area of the sky to base the evaluation of number of visits over.
+    nside : `int`, optional
+        Nside parameter from healpix slicer, used to set the physical
+        relationship between on-sky area and number of healpixels.
+    n_visit : `int`, optional
+        Number of visits to use as the benchmark value, if choosing to return
+        a normalized n_visit value.
+    norm : `bool`, optional
+        Normalize the returned "n_visit" (min / median) values by n_visit,
+        if true.
+    metric_name : `str`, optional
+        Name of the summary metric. Default FONv.
+    """
+
+    def __init__(self, col="metricdata", asky=18000.0, nside=128, n_visit=825, norm=False, **kwargs):
+        """asky = square degrees"""
+        super().__init__(col=col, **kwargs)
+        self.nvisit = n_visit
+        self.nside = nside
+        # Determine how many healpixels are included in asky sq deg.
+        self.asky = asky
+        self.scale = hp.nside2pixarea(self.nside, degrees=True)
+        self.npix__asky = int(np.ceil(self.asky / self.scale))
+        self.norm = norm
+
+    def run(self, data_slice, slice_point=None):
+        result = np.empty(2, dtype=[("name", np.str_, 20), ("value", float)])
+        result["name"][0] = "MedianNvis"
+        result["name"][1] = "MinNvis"
+        # If there is not even as much data as needed to cover Asky:
+        if len(data_slice) < self.npix__asky:
+            result["value"][0] = self.badval
+            result["value"][1] = self.badval
+            return result
+        # Otherwise, calculate median and mean Nvis:
+        nvis_sorted = np.sort(data_slice[self.colname])
+        # Find the Asky's worth of healpixels with the largest # of visits.
+        nvis__asky = nvis_sorted[-self.npix__asky :]
+        result["value"][0] = np.median(nvis__asky)
+        result["value"][1] = np.min(nvis__asky)
+        if self.norm:
+            result["value"] /= float(self.nvisit)
+        return result
+
+
+class FOArea(BaseMetric):
+    """Given an n_visit threshold, how much AREA receives at least that many
+    visits?
+
+    Parameters
+    ----------
+    col : `str` or `list` of `strs`, optional
+        Name of the column in the numpy recarray passed to the summary metric.
+    n_visit : `int`, optional
+        Number of visits to use as the minimum required --
+        metric calculated area that has this many visits.
+    asky : `float`, optional
+        Area to use as the benchmark area value,
+        if choosing to return a normalized Area value.
+    nside : `int`, optional
+        Nside parameter from healpix slicer, used to set the physical
+        relationship between on-sky area and number of healpixels.
+    norm : `bool`, optional
+        If true, normalize the returned area value by asky.
+    """
+
+    def __init__(
+        self,
+        col="metricdata",
+        n_visit=825,
+        asky=18000.0,
+        nside=128,
+        norm=False,
+        **kwargs,
+    ):
+        """asky = square degrees"""
+        super().__init__(col=col, **kwargs)
+        self.nvisit = n_visit
+        self.nside = nside
+        self.asky = asky
+        self.scale = hp.nside2pixarea(self.nside, degrees=True)
+        self.norm = norm
+
+    def run(self, data_slice, slice_point=None):
+        nvis_sorted = np.sort(data_slice[self.colname])
+        # Identify the healpixels with more than Nvisits.
+        nvis_min = nvis_sorted[np.where(nvis_sorted >= self.nvisit)]
+        if len(nvis_min) == 0:
+            result = self.badval
+        else:
+            result = nvis_min.size * self.scale
+            if self.norm:
+                result /= float(self.asky)
+        return result
+
+
+class IdentityMetric(BaseMetric):
+    """Return the metric value.
+
+    This is primarily useful as a summary statistic for UniSlicer metrics,
+    to propagate the ~MetricBundle.metric_value into the results database.
+    """
+
+    def run(self, data_slice, slice_point=None):
+        if len(data_slice[self.colname]) == 1:
+            result = data_slice[self.colname][0]
+        else:
+            result = data_slice[self.colname]
+        return result
+
+
+class NormalizeMetric(BaseMetric):
+    """
+    Return a metric values divided by 'norm_val'.
+    Useful for turning summary statistics into fractions.
+    """
+
+    def __init__(self, col="metricdata", norm_val=1, **kwargs):
+        super(NormalizeMetric, self).__init__(col=col, **kwargs)
+        self.norm_val = float(norm_val)
+
+    def run(self, data_slice, slice_point=None):
+        result = data_slice[self.colname] / self.norm_val
+        if len(result) == 1:
+            return result[0]
+        else:
+            return result
+
+
+class ZeropointMetric(BaseMetric):
+    """
+    Return a metric values with the addition of 'zp'.
+    Useful for altering the zeropoint for summary statistics.
+    """
+
+    def __init__(self, col="metricdata", zp=0, **kwargs):
+        super(ZeropointMetric, self).__init__(col=col, **kwargs)
+        self.zp = zp
+
+    def run(self, data_slice, slice_point=None):
+        result = data_slice[self.colname] + self.zp
+        if len(result) == 1:
+            return result[0]
+        else:
+            return result

rubin_sim/maf/metrics/surfb_metric.py

@@ -0,0 +1,175 @@
+__all__ = ("SurfaceBrightLimitMetric",)
+
+import warnings
+
+import numpy as np
+
+from rubin_sim.maf.utils import load_inst_zeropoints
+
+from .base_metric import BaseMetric
+
+
+def surface_brightness_limit_approx(
+    zp,
+    k,
+    airmass,
+    mu_sky,
+    rn=8.8,
+    pixscale=0.2,
+    nsigma=3.0,
+    t_exp=30.0,
+    tot_area=100.0,
+    mag_diff_warn=0.1,
+):
+    """Compute surface brightness limit in 3 limiting cases, return the
+    brightest.
+
+    Algerbra worked out in this technote:
+    https://github.com/lsst-sims/smtn-016
+
+    Parameters
+    ---------
+    zp : `float`
+        Telescope zeropoint (mags)
+    k : `float`
+        Atmospheric extinction term
+    airmass : `float`
+        Airmass
+    mu_sky : `float`
+        Surface brightness of the sky (mag/sq arcsec)
+    rn : `float` (8.8)
+        Readnoise in electrons
+    pixscale : `float` (0.2)
+        Arcseconds per pixel
+    nsigma : `float` (3)
+        The SNR to demand
+    t_exp : `float` (30.)
+        Exposure time (seconds)
+    tot_area : `float` (100)
+        The total area measuring over (sq arcsec)
+    mag_diff_warn : `float` (0.1)
+        If the limiting cases are within mag_diff_warn, throw a warning
+        that the surface brightness limit may be an overestimate.
+
+    Returns
+    -------
+    surface brightness limit in mags/sq arcsec, aka the surface brightness that
+    reaches SNR=nsigma when measured over tot_area.
+    """
+
+    a_pix = pixscale**2
+
+    n_pix = tot_area / a_pix
+
+    # Sky limited case
+    mu_sky_lim = -1.25 * np.log10(nsigma**2 / (a_pix * t_exp * n_pix)) + 0.5 * mu_sky + 0.5 * zp - k * airmass
+
+    # Source limited case
+    # XXX--double check this algerbra. Pretty sure it's right now.
+    mu_source_lim = -5 * np.log10(nsigma) + 2.5 * np.log10(n_pix * a_pix * t_exp) + zp - k * airmass
+
+    # Readnoise limited case
+    mu_rn_lim = -2.5 * np.log10(nsigma * rn / (t_exp * a_pix * n_pix**0.5)) + zp - k * airmass
+
+    d1 = np.min(np.abs(mu_sky_lim - mu_source_lim))
+    d2 = np.min(np.abs(mu_sky_lim - mu_rn_lim))
+    d3 = np.min(np.abs(mu_rn_lim - mu_source_lim))
+
+    if np.min([d1, d2, d3]) < mag_diff_warn:
+        warnings.warn(
+            "Limiting magnitudes in different cases are within %.3f mags, \
+            result may be too optimistic by up 0.38 mags/sq arcsec."
+            % mag_diff_warn
+        )
+
+    result = np.vstack([mu_sky_lim, mu_source_lim, mu_rn_lim])
+    result = np.min(result, axis=0)
+
+    return result
+
+
+class SurfaceBrightLimitMetric(BaseMetric):
+    """Gaussian limit, ignoring systematic errors in photometry
+
+    Parameters
+    ----------
+    pixscale : `float` (0.2)
+        Pixelscale, Arcseconds per pixel
+    nsigma : `float` (3)
+        The detection limit (usuall 3 or 5)
+    tot_area : `float` (100)
+        Total sky area summed over, square arcseconds
+    zpt : `dict` of `float` (None)
+        telescope zeropoints. If None, computed from phot_utils
+    k_atm : `dict` of `float` (None)
+        Atmospheric extinction parameters. If None, computed from phot_utils
+    readnoise : `float` (8.8)
+        Readnoise in electrons
+    """
+
+    def __init__(
+        self,
+        pixscale=0.2,
+        nsigma=3.0,
+        tot_area=100.0,
+        filter_col="band",
+        units="mag/sq arcsec",
+        airmass_col="airmass",
+        exptime_col="visitExposureTime",
+        metric_name="SurfaceBrightLimit",
+        skybrightness_col="skyBrightness",
+        nexp_col="numExposures",
+        zpt=None,
+        k_atm=None,
+        readnoise=8.8,
+        **kwargs,
+    ):
+        super().__init__(
+            col=[filter_col, airmass_col, exptime_col, skybrightness_col, nexp_col],
+            units=units,
+            metric_name=metric_name,
+            **kwargs,
+        )
+        self.filter_col = filter_col
+        self.airmass_col = airmass_col
+        self.exptime_col = exptime_col
+        self.skybrightness_col = skybrightness_col
+        self.nexp_col = nexp_col
+
+        self.readnoise = readnoise
+        self.pixscale = pixscale
+        self.nsigma = nsigma
+        self.tot_area = tot_area
+
+        # Compute default zeropoints
+        if zpt is None:
+            zp_inst, k_atm = load_inst_zeropoints()
+            self.zpt = zp_inst
+            self.k_atm = k_atm
+        else:
+            self.zpt = zpt
+            self.k_atm = k_atm
+
+    def run(self, data_slice, slice_point):
+        filtername = np.unique(data_slice[self.filter_col])
+        if np.size(filtername) > 1:
+            ValueError("Can only coadd depth in single filter, got filters %s" % filtername)
+        filtername = filtername[0]
+
+        # Scale up readnoise if the visit was split into multiple snaps
+        readnoise = self.readnoise * np.sqrt(data_slice[self.nexp_col])
+
+        sb_per_visit = surface_brightness_limit_approx(
+            self.zpt[filtername],
+            self.k_atm[filtername],
+            data_slice[self.airmass_col],
+            data_slice[self.skybrightness_col],
+            rn=readnoise,
+            pixscale=self.pixscale,
+            nsigma=self.nsigma,
+            t_exp=data_slice[self.exptime_col],
+            tot_area=self.tot_area,
+        )
+
+        coadd_sb_limit = 1.25 * np.log10(np.sum(10 ** (0.8 * sb_per_visit)))
+        return coadd_sb_limit