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

rubin_sim/maf/metrics/coverage_metric.py

@@ -0,0 +1,48 @@
+__all__ = ("YearCoverageMetric",)
+
+import numpy as np
+
+from .base_metric import BaseMetric
+
+
+class YearCoverageMetric(BaseMetric):
+    """Count the number of `bins` covered by night_col.
+
+    The default `bins` cover years 0 to 10.
+    Handy for checking that a point on the sky gets observed every year,
+    as the default settings result in the metric returning the number years
+    in the data_slice (when used with a HealpixSlicer).
+
+    Parameters
+    ----------
+    night_col : `str`, opt
+        Data column to histogram. Default 'night'.
+    bins : `np.ndarray`, (N,), opt
+        Bins to use in the histogram. Default corresponds to years 0-10
+        (with 365.25 nights per year).
+    units : `str`, opt
+        Units to use for the metric result. Default 'N years'.
+
+    Returns
+    -------
+    nbins : `int`
+        Number of histogram bins where the histogram value is greater than 0.
+        Typically this will be the number of years in the 'night_col'.
+    """
+
+    def __init__(self, night_col="night", bins=None, units=None, **kwargs):
+        self.night_col = night_col
+        if bins is None:
+            self.bins = np.arange(0, np.ceil(365.25 * 10.0), 365.25) - 0.5
+        else:
+            self.bins = bins
+
+        if units is None:
+            units = "N years"
+
+        super().__init__([night_col], units=units)
+
+    def run(self, data_slice, slice_point):
+        hist, be = np.histogram(data_slice[self.night_col], bins=self.bins)
+        result = np.where(hist > 0)[0].size
+        return result

rubin_sim/maf/metrics/crowding_metric.py

@@ -0,0 +1,255 @@
+__all__ = ("CrowdingM5Metric", "CrowdingMagUncertMetric", "NstarsMetric")
+
+import healpy as hp
+import numpy as np
+from scipy.interpolate import interp1d
+
+from rubin_sim.maf.metrics import BaseMetric
+
+# Originally contributed by Knut Olson (@knutago).
+
+
+def _comp_crowd_error(mag_vector, lum_func, seeing, single_mag=None):
+    """
+    Compute the photometric crowding error given the luminosity
+    function and best seeing.
+
+    Equation from Olsen, Blum, & Rigaut 2003, AJ, 126, 452
+
+    Parameters
+    ----------
+    mag_vector : `np.array` (N,)
+        Stellar magnitudes.
+    lum_func : `np.array` (N,)
+        Stellar luminosity function.
+    seeing : `float`
+        The best seeing conditions.
+        Assuming forced-photometry can use the best seeing conditions
+        to help with confusion errors.
+    single_mag : `float` or None
+        If single_mag is None, the crowding error is calculated
+        for each mag in mag_vector. If single_mag is a float,
+        the crowding error is interpolated to that single value.
+
+    Returns
+    -------
+    mag_uncert : `np.array` (N,)
+        Magnitude uncertainties.
+    """
+    # Our saved luminosity functions are cumulative,
+    # so we must here convert to differential
+    lum_func = np.diff(lum_func)
+    mag_vector = mag_vector[1:]
+    lum_area_arcsec = 3600.0**2
+    lum_vector = 10 ** (-0.4 * mag_vector)
+    coeff = np.sqrt(np.pi / lum_area_arcsec) * seeing / 2.0
+    my_int = (np.add.accumulate((lum_vector**2 * lum_func)[::-1]))[::-1]
+    temp = np.sqrt(my_int) / lum_vector
+    if single_mag is not None:
+        interp = interp1d(mag_vector, temp)
+        temp = interp(single_mag)
+    crowd_error = coeff * temp
+    return crowd_error
+
+
+class CrowdingM5Metric(BaseMetric):
+    """Calculate the magnitude at which the photometric error exceeds
+    the crowding error threshold.
+
+    Parameters
+    ----------
+    crowding_error : `float`, optional
+        The magnitude uncertainty from crowding in magnitudes.
+        Default 0.1 mags.
+    filtername : `str`, optional
+        The bandpass in which to calculate the crowding limit. Default r.
+    seeing_col : `str`, optional
+        The name of the seeing column.
+    m5Col : `str`, optional
+        The name of the m5 depth column.
+    maps : `list` [`str`], optional
+        Names of maps required for the metric.
+
+    Returns
+    -------
+    mag : `float`
+        The magnitude of a star which has a photometric error of
+        `crowding_error`
+    """
+
+    def __init__(
+        self,
+        crowding_error=0.1,
+        filtername="r",
+        seeing_col="seeingFwhmGeom",
+        metric_name=None,
+        maps=["StellarDensityMap"],
+        **kwargs,
+    ):
+        cols = [seeing_col]
+        units = "mag"
+        self.crowding_error = crowding_error
+        self.filtername = filtername
+        self.seeing_col = seeing_col
+        if metric_name is None:
+            metric_name = "Crowding to Precision %.2f" % (crowding_error)
+        super().__init__(col=cols, maps=maps, units=units, metric_name=metric_name, **kwargs)
+
+    def run(self, data_slice, slice_point=None):
+        # Set mag_vector to the same length as starLumFunc
+        # (lower edge of mag bins)
+        mag_vector = slice_point[f"starMapBins_{self.filtername}"][1:]
+        # Pull up density of stars at this point in the sky
+        lum_func = slice_point[f"starLumFunc_{self.filtername}"]
+        # Calculate the crowding error using the best seeing value
+        # (in any filter?)
+        crowd_error = _comp_crowd_error(mag_vector, lum_func, seeing=min(data_slice[self.seeing_col]))
+        # Locate at which point crowding error is greater than user-defined
+        # limit
+        above_crowd = np.where(crowd_error >= self.crowding_error)[0]
+
+        if np.size(above_crowd) == 0:
+            result = max(mag_vector)
+        else:
+            crowd_mag = mag_vector[max(above_crowd[0] - 1, 0)]
+            result = crowd_mag
+
+        return result
+
+
+class NstarsMetric(BaseMetric):
+    """Calculate the number of stars detectable above some uncertainty
+    limit, taking image depth and crowding into account.
+
+    Parameters
+    ----------
+    crowding_error : `float`, opt
+        The magnitude uncertainty from crowding in magnitudes.
+        Default 0.1 mags.
+    filtername : `str`, opt
+        The bandpass in which to calculate the crowding limit. Default r.
+    seeing_col : `str`, opt
+        The name of the seeing column.
+    m5_col : `str`, opt
+        The name of the m5 depth column.
+    maps : `list` [`str`], opt
+        Names of maps required for the metric.
+    ignore_crowding : `bool`, opt
+        Ignore the crowding limit.
+
+    Returns
+    -------
+    nstars : `float`
+        The number of stars above the error limit.
+    """
+
+    def __init__(
+        self,
+        crowding_error=0.1,
+        filtername="r",
+        seeing_col="seeingFwhmGeom",
+        m5_col="fiveSigmaDepth",
+        metric_name=None,
+        maps=["StellarDensityMap"],
+        ignore_crowding=False,
+        **kwargs,
+    ):
+        cols = [seeing_col, m5_col]
+        units = "N stars"
+        self.crowding_error = crowding_error
+        self.m5_col = m5_col
+        self.filtername = filtername
+        self.seeing_col = seeing_col
+        self.ignore_crowding = ignore_crowding
+        if metric_name is None:
+            metric_name = "N stars to Precision %.2f" % (crowding_error)
+        super().__init__(col=cols, maps=maps, units=units, metric_name=metric_name, **kwargs)
+
+    def run(self, data_slice, slice_point=None):
+        pix_area = hp.nside2pixarea(slice_point["nside"], degrees=True)
+        # Set mag_vector to the same length as starLumFunc
+        # (lower edge of mag bins)
+        mag_vector = slice_point[f"starMapBins_{self.filtername}"][1:]
+        # Pull up density of stars at this point in the sky
+        lum_func = slice_point[f"starLumFunc_{self.filtername}"]
+        # Calculate the crowding error using the best seeing value
+        # (in any filter?)
+        crowd_error = _comp_crowd_error(mag_vector, lum_func, seeing=min(data_slice[self.seeing_col]))
+        # Locate at which point crowding error is greater than
+        # user-defined limit
+        above_crowd = np.where(crowd_error >= self.crowding_error)[0]
+
+        if np.size(above_crowd) == 0:
+            crowd_mag = max(mag_vector)
+        else:
+            crowd_mag = mag_vector[max(above_crowd[0] - 1, 0)]
+
+        # Compute the coadded depth, and the mag where that depth
+        # hits the error specified
+        coadded_depth = 1.25 * np.log10(np.sum(10.0 ** (0.8 * data_slice[self.m5_col])))
+        mag_limit = -2.5 * np.log10(1.0 / (self.crowding_error * (1.09 * 5))) + coadded_depth
+
+        # Use the shallower depth, crowding or coadded
+        if self.ignore_crowding:
+            min_mag = mag_limit
+        else:
+            min_mag = np.min([crowd_mag, mag_limit])
+
+        # Interpolate to the number of stars
+        result = (
+            np.interp(
+                min_mag,
+                slice_point[f"starMapBins_{self.filtername}"][1:],
+                slice_point[f"starLumFunc_{self.filtername}"],
+            )
+            * pix_area
+        )
+
+        return result
+
+
+class CrowdingMagUncertMetric(BaseMetric):
+    """Calculate the mean uncertainty in magnitude due to crowding.
+
+    Parameters
+    ----------
+    rmag : `float`
+        The magnitude of the star to consider.
+
+    Returns
+    -------
+    mag_uncert : `float`
+        The uncertainty in magnitudes caused by crowding for a star of rmag.
+    """
+
+    def __init__(
+        self,
+        rmag=20.0,
+        seeing_col="seeingFwhmGeom",
+        units="mag",
+        metric_name=None,
+        filtername="r",
+        maps=["StellarDensityMap"],
+        **kwargs,
+    ):
+        self.filtername = filtername
+        self.seeing_col = seeing_col
+        self.rmag = rmag
+        if metric_name is None:
+            metric_name = "CrowdingError at %.2f" % (rmag)
+        super().__init__(col=[seeing_col], maps=maps, units=units, metric_name=metric_name, **kwargs)
+
+    def run(self, data_slice, slice_point=None):
+        mag_vector = slice_point[f"starMapBins_{self.filtername}"][1:]
+        lum_func = slice_point[f"starLumFunc_{self.filtername}"]
+        # Magnitude uncertainty given crowding
+        # Use minimum here, however this may not be appropriate in all cases.
+        # (minimum makes value here match MagCrowding above, however
+        # the minimum seeing could also correlate with poor m5 values)
+        # Likely there should be some comparison between errors from crowding
+        # and errors from photometric noise that we're just not doing.
+        dmag_crowd = _comp_crowd_error(
+            mag_vector, lum_func, min(data_slice[self.seeing_col]), single_mag=self.rmag
+        )
+        result = np.mean(dmag_crowd)
+        return result

rubin_sim/maf/metrics/cumulative_metric.py

@@ -0,0 +1,46 @@
+__all__ = ("CumulativeMetric",)
+
+import numpy as np
+
+from .base_metric import BaseMetric
+
+
+class CumulativeMetric(BaseMetric):
+    """For plotting up the cumulative number of observations.
+    Expected to be used with a UniSlicer or UserPointSlicer with one point.
+
+    Parameters
+    ----------
+    interp_points : `np.array`, (N,)  or None
+        The points to interpolate the cumulative number of observations to.
+        If None, then the range of the data is used with a stepsize of 1.
+    """
+
+    def __init__(
+        self,
+        metric_name="Cumulative",
+        time_col="observationStartMJD",
+        night_col="night",
+        interp_points=None,
+        **kwargs,
+    ):
+        super().__init__(col=[time_col, night_col], metric_name=metric_name, metric_dtype="object", **kwargs)
+        self.time_col = time_col
+        self.night_col = night_col
+        self.interp_points = interp_points
+        self.plot_dict = {"xlabel": "MJD (days)", "ylabel": "N obs"}
+
+    def run(self, data_slice, slice_point=None):
+        data_slice.sort(order=self.time_col)
+        if self.interp_points is None:
+            interp_points = np.arange(
+                data_slice[self.night_col].min(),
+                data_slice[self.night_col].max() + 1,
+                1,
+            )
+        else:
+            interp_points = self.interp_points
+        cumulative_number = np.arange(data_slice.size) + 1
+        yresult = np.interp(interp_points, data_slice[self.night_col], cumulative_number)
+        xresult = interp_points
+        return {"x": xresult, "y": yresult, "plot_dict": self.plot_dict}

rubin_sim/maf/metrics/dcr_metric.py

@@ -0,0 +1,93 @@
+__all__ = ("DcrPrecisionMetric",)
+
+import numpy as np
+import rubin_scheduler.utils as utils
+
+import rubin_sim.maf.utils as mafUtils
+
+from .base_metric import BaseMetric
+
+
+class DcrPrecisionMetric(BaseMetric):
+    """Determine how precise a DCR correction could be made
+
+    Parameters
+    ----------
+    atm_err : `float`
+        Minimum error in photometry centroids introduced by the atmosphere
+        (arcseconds). Default 0.01.
+    """
+
+    def __init__(
+        self,
+        metric_name="DCRprecision",
+        seeing_col="seeingFwhmGeom",
+        m5_col="fiveSigmaDepth",
+        ha_col="HA",
+        pa_col="paraAngle",
+        filter_col="band",
+        atm_err=0.01,
+        sed_template="flat",
+        rmag=20.0,
+        **kwargs,
+    ):
+        self.m5_col = m5_col
+        self.filter_col = filter_col
+        self.pa_col = pa_col
+        self.seeing_col = seeing_col
+        self.mags = {}
+        self.filters = ["u", "g", "r", "i", "z", "y"]
+        if sed_template == "flat":
+            for f in self.filters:
+                self.mags[f] = rmag
+        else:
+            self.mags = utils.stellarMags(sed_template, rmag=rmag)
+        cols = [
+            "ra_dcr_amp",
+            "dec_dcr_amp",
+            seeing_col,
+            m5_col,
+            filter_col,
+            "zenithDistance",
+            pa_col,
+        ]
+        units = "arcseconds"
+        self.atm_err = atm_err
+        super(DcrPrecisionMetric, self).__init__(cols, metric_name=metric_name, units=units, **kwargs)
+
+    def run(self, data_slice, slice_point=None):
+        snr = np.zeros(len(data_slice), dtype="float")
+        for filt in self.filters:
+            in_filt = np.where(data_slice[self.filter_col] == filt)
+            snr[in_filt] = mafUtils.m52snr(self.mags[filt], data_slice[self.m5_col][in_filt])
+
+        position_errors = np.sqrt(
+            mafUtils.astrom_precision(data_slice[self.seeing_col], snr) ** 2 + self.atm_err**2
+        )
+
+        x_coord = np.tan(np.radians(data_slice["zenithDistance"])) * np.sin(
+            np.radians(data_slice[self.pa_col])
+        )
+        x_coord2 = np.tan(np.radians(data_slice["zenithDistance"])) * np.cos(
+            np.radians(data_slice[self.pa_col])
+        )
+        # Things should be the same for RA and dec.
+        # Now I want to compute the error if I interpolate/extrapolate to +/-1.
+
+        # function is of form, y=ax. a=y/x. da = dy/x.
+        # Only strictly true if we know the unshifted position.
+        # But this should be a reasonable approx.
+        slope_uncerts = position_errors / x_coord
+        slope_uncerts2 = position_errors / x_coord2
+
+        total_slope_uncert = 1.0 / np.sqrt(np.sum(1.0 / slope_uncerts**2) + np.sum(1.0 / slope_uncerts2**2))
+
+        # So, this will be the uncertainty in the RA or Dec offset at
+        # x= +/- 1. A.K.A., the uncertainty in the slope
+        # of the line made by tan(zd)*sin(PA) vs RA offset
+        # or the line tan(zd)*cos(PA) vs Dec offset
+        # Assuming we know the unshfted position of the object
+        # (or there's little covariance if we are fitting for both)
+        result = total_slope_uncert
+
+        return result

rubin_sim/maf/metrics/exgal_m5.py

@@ -0,0 +1,57 @@
+__all__ = ("ExgalM5",)
+
+from rubin_sim.phot_utils import DustValues
+
+from .base_metric import BaseMetric
+from .simple_metrics import Coaddm5Metric
+
+
+class ExgalM5(BaseMetric):
+    """
+    Calculate co-added five-sigma limiting depth after dust extinction.
+
+    Uses phot_utils to calculate dust extinction.
+
+    Parameters
+    ----------
+    m5_col : `str`, optional
+        Column name for five sigma depth. Default 'fiveSigmaDepth'.
+    unit : `str`, optional
+        Label for units. Default 'mag'.
+
+    Returns
+    -------
+    coadd_m5 : `float`
+        Coadded m5 value, corrected for galactic dust extinction.
+    """
+
+    def __init__(
+        self, m5_col="fiveSigmaDepth", metric_name="ExgalM5", units="mag", filter_col="band", **kwargs
+    ):
+        # Set the name for the dust map to use.
+        # This is gathered into the MetricBundle.
+        maps = ["DustMap"]
+        self.m5_col = m5_col
+        self.filter_col = filter_col
+        super().__init__(
+            col=[self.m5_col, self.filter_col], maps=maps, metric_name=metric_name, units=units, **kwargs
+        )
+        # Set the default wavelength limits for the lsst filters.
+        # These are approximately correct.
+        dust_properties = DustValues()
+        self.ax1 = dust_properties.ax1
+        # We will call Coaddm5Metric to calculate the coadded depth.
+        # Set it up here.
+        self.coaddm5_metric = Coaddm5Metric(m5_col=m5_col)
+
+    def run(self, data_slice, slice_point):
+        """Compute the co-added m5 depth and then apply
+        dust extinction to that magnitude.
+        """
+        m5 = self.coaddm5_metric.run(data_slice)
+        if m5 == self.coaddm5_metric.badval:
+            return self.badval
+        # Total dust extinction along this line of sight.
+        # Correct default A to this EBV value.
+        a_x = self.ax1[data_slice[self.filter_col][0]] * slice_point["ebv"]
+        return m5 - a_x

rubin_sim/maf/metrics/fft_metric.py

@@ -0,0 +1,27 @@
+__all__ = ("FftMetric",)
+
+from scipy import fftpack
+
+from .base_metric import BaseMetric
+
+
+class FftMetric(BaseMetric):
+    """Calculate a truncated FFT of the exposure times."""
+
+    def __init__(self, times_col="expmjd", metric_name="Fft", n_coeffs=100, **kwargs):
+        """Instantiate metric.
+
+        'times_col' = column with the time of the visit (default expmjd),
+        'n_coeffs' = number of coefficients of the (real) FFT to keep."""
+        self.times = times_col
+        super(FftMetric, self).__init__(col=[self.times], metric_name=metric_name, **kwargs)
+        # Set up length of return values.
+        self.n_coeffs = n_coeffs
+        return
+
+    def run(self, data_slice, slice_point=None):
+        fft = fftpack.rfft(data_slice[self.times])
+        return fft[0 : self.n_coeffs]
+
+    def reduce_peak(self, fft_coeff):
+        pass