Metrics

class rubin_sim.maf.metrics.AbsMaxMetric(col=None, metric_name=None, maps=None, units=None, metric_dtype=None, badval=-666, mask_val=None)

Bases: BaseMetric

Calculate the max of the absolute value of a simData column slice.

run(data_slice, slice_point=None)

Calculate metric values.

Parameters:

• data_slice (numpy.ndarray, (N,)) – Values passed to metric by the slicer, which the metric will use to calculate metric values at each slice_point.

• slice_point (dict or None) – Dictionary of slice_point metadata passed to each metric. E.g. the ra/dec of the healpix pixel.

Returns:

metricValue – The metric value at each slice_point.

Return type:

int float or object

class rubin_sim.maf.metrics.AbsMaxPercentMetric(col=None, metric_name=None, maps=None, units=None, metric_dtype=None, badval=-666, mask_val=None)

Bases: BaseMetric

Return the percent of data which matches the absolute value of the max value of the data.

run(data_slice, slice_point=None)

Calculate metric values.

Parameters:

• data_slice (numpy.ndarray, (N,)) – Values passed to metric by the slicer, which the metric will use to calculate metric values at each slice_point.

• slice_point (dict or None) – Dictionary of slice_point metadata passed to each metric. E.g. the ra/dec of the healpix pixel.

Returns:

metricValue – The metric value at each slice_point.

Return type:

int float or object

class rubin_sim.maf.metrics.AbsMeanMetric(col=None, metric_name=None, maps=None, units=None, metric_dtype=None, badval=-666, mask_val=None)

Bases: BaseMetric

Calculate the mean of the absolute value of a simData column slice.

run(data_slice, slice_point=None)

Calculate metric values.

Parameters:

• data_slice (numpy.ndarray, (N,)) – Values passed to metric by the slicer, which the metric will use to calculate metric values at each slice_point.

• slice_point (dict or None) – Dictionary of slice_point metadata passed to each metric. E.g. the ra/dec of the healpix pixel.

Returns:

metricValue – The metric value at each slice_point.

Return type:

int float or object

class rubin_sim.maf.metrics.AbsMedianMetric(col=None, metric_name=None, maps=None, units=None, metric_dtype=None, badval=-666, mask_val=None)

Bases: BaseMetric

Calculate the median of the absolute value of a simData column slice.

run(data_slice, slice_point=None)

Calculate metric values.

Parameters:

• data_slice (numpy.ndarray, (N,)) – Values passed to metric by the slicer, which the metric will use to calculate metric values at each slice_point.

• slice_point (dict or None) – Dictionary of slice_point metadata passed to each metric. E.g. the ra/dec of the healpix pixel.

Returns:

metricValue – The metric value at each slice_point.

Return type:

int float or object

class rubin_sim.maf.metrics.AccumulateCountMetric(col='night', bins=None, bin_col='night', function=<ufunc 'add'>, metric_dtype=<class 'float'>, **kwargs)

Bases: AccumulateMetric

run(data_slice, slice_point=None)

Calculate metric values.

Parameters:

• data_slice (numpy.ndarray, (N,)) – Values passed to metric by the slicer, which the metric will use to calculate metric values at each slice_point.

• slice_point (dict or None) – Dictionary of slice_point metadata passed to each metric. E.g. the ra/dec of the healpix pixel.

Returns:

metricValue – The metric value at each slice_point.

Return type:

int float or object

class rubin_sim.maf.metrics.AccumulateM5Metric(bins=None, bin_col='night', m5_col='fiveSigmaDepth', metric_name='AccumulateM5Metric', **kwargs)

Bases: AccumulateMetric

run(data_slice, slice_point=None)

Calculate metric values.

Parameters:

• data_slice (numpy.ndarray, (N,)) – Values passed to metric by the slicer, which the metric will use to calculate metric values at each slice_point.

• slice_point (dict or None) – Dictionary of slice_point metadata passed to each metric. E.g. the ra/dec of the healpix pixel.

Returns:

metricValue – The metric value at each slice_point.

Return type:

int float or object

class rubin_sim.maf.metrics.AccumulateMetric(col='night', bins=None, bin_col='night', function=<ufunc 'add'>, metric_dtype=<class 'float'>, **kwargs)

Bases: VectorMetric

Calculate the accumulated stat

run(data_slice, slice_point=None)

Calculate metric values.

Parameters:

• data_slice (numpy.ndarray, (N,)) – Values passed to metric by the slicer, which the metric will use to calculate metric values at each slice_point.

• slice_point (dict or None) – Dictionary of slice_point metadata passed to each metric. E.g. the ra/dec of the healpix pixel.

Returns:

metricValue – The metric value at each slice_point.

Return type:

int float or object

class rubin_sim.maf.metrics.AccumulateUniformityMetric(bins=None, bin_col='night', exp_mjd_col='observationStartMJD', metric_name='AccumulateUniformityMetric', survey_length=10.0, units='Fraction', **kwargs)

Bases: AccumulateMetric

Make a 2D version of UniformityMetric

run(data_slice, slice_point=None)

Calculate metric values.

Parameters:

• data_slice (numpy.ndarray, (N,)) – Values passed to metric by the slicer, which the metric will use to calculate metric values at each slice_point.

• slice_point (dict or None) – Dictionary of slice_point metadata passed to each metric. E.g. the ra/dec of the healpix pixel.

Returns:

metricValue – The metric value at each slice_point.

Return type:

int float or object

class rubin_sim.maf.metrics.ActivityOverPeriodMetric(bin_size, snr_limit=5, q_col='q', e_col='e', a_col='a', t_peri_col='tPeri', anomaly_col='meanAnomaly', metric_name=None, **kwargs)

Bases: BaseMoMetric

Count fraction of object period we could identify activity for an SSobject.

Count the fraction of the orbit (when split into n_bins) that receive observations, in order to have a chance to detect activity.

Parameters:

• bin_size (float) – Like window for the ActivityOverTimeMetric, but describes how much of the orbit (considered in mean motion) should be included in a given bin. In degrees.

• snr_limit (None or float, opt) – SNR limit to use for observations. If snr_limit is None, then it uses the completeness calculation added to the ‘vis’ column (probabilistic visibility, based on 5-sigma limit). If snr_limit is not None, it uses this SNR value as a cutoff.

• q_col (str, opt) – The name of the q column in the objects orbit data.

• e_col (str, opt) – The name of the eccentricity column in the objects orbit data.

• t_peri_col (str, opt) – The name of the time of perihelion column in the objects orbit data.

• anomaly_col (str, opt) – The name of the mean anomaly column in the objects orbit data.

• metric_name (str or None, opt) – Name for the metric. If None, one is created from the class name.

run(sso_obs, orb, hval)

Calculate the metric value.

Parameters:

• sso_obs (np.ndarray, (N,)) – The input data to the metric (same as the parent metric).

• orb (np.ndarray, (N,)) – The information about the orbit for which the metric is being calculated.

• hval (float) – The H value for which the metric is being calculated.

Returns:

metric_val

Return type:

float or np.ndarray or dict

class rubin_sim.maf.metrics.ActivityOverTimeMetric(window, snr_limit=5, survey_years=10.0, metric_name=None, **kwargs)

Bases: BaseMoMetric

Count fraction of survey we could identify activity for an SSobject.

Counts the time periods where we would have a chance to detect activity on a moving object. Splits observations into time periods set by ‘window’, then looks for observations within each window, and reports what fraction of the total windows receive ‘nObs’ visits.

Parameters:

• window (float) – The (repeated) time period to search for activity.

• snr_limit (None or float, opt) – SNR limit to use for observations. If snr_limit is None, then it uses the completeness calculation added to the ‘vis’ column (probabilistic visibility, based on 5-sigma limit). If snr_limit is not None, it uses this SNR value as a cutoff.

• survey_years (float, opt) – The length of time of the survey. The test window is repeated over survey_years, and then a fraction calculated from the number of bins in which observations were acquired compared to the total number of bins.

• metric_name (str or None, opt) – Name for the metric. If None, one is created from the class name.

run(sso_obs, orb, hval)

Calculate the metric value.

Parameters:

• sso_obs (np.ndarray, (N,)) – The input data to the metric (same as the parent metric).

• orb (np.ndarray, (N,)) – The information about the orbit for which the metric is being calculated.

• hval (float) – The H value for which the metric is being calculated.

Returns:

metric_val

Return type:

float or np.ndarray or dict

class rubin_sim.maf.metrics.AgeMetric(mjd, mjd_col='observationStartMJD', long_limit=30, metric_name='age', mask_val=nan, **kwargs)

Bases: BaseMetric

run(data_slice, slice_point=None)

Calculate metric values.

Parameters:

• data_slice (numpy.ndarray, (N,)) – Values passed to metric by the slicer, which the metric will use to calculate metric values at each slice_point.

• slice_point (dict or None) – Dictionary of slice_point metadata passed to each metric. E.g. the ra/dec of the healpix pixel.

Returns:

metricValue – The metric value at each slice_point.

Return type:

int float or object

class rubin_sim.maf.metrics.AgnTimeLagMetric(lag=100, z=1, log=False, threshold=2.2, calc_type='mean', mjd_col='observationStartMJD', filter_col='filter', m5_col='fiveSigmaDepth', dust=True, g_cutoff=22.0, r_cutoff=21.8, metric_name=None, **kwargs)

Bases: BaseMetric

run(data_slice, slice_point=None)

Calculate metric values.

Parameters:

• data_slice (numpy.ndarray, (N,)) – Values passed to metric by the slicer, which the metric will use to calculate metric values at each slice_point.

• slice_point (dict or None) – Dictionary of slice_point metadata passed to each metric. E.g. the ra/dec of the healpix pixel.

Returns:

metricValue – The metric value at each slice_point.

Return type:

int float or object

class rubin_sim.maf.metrics.AngularSpreadMetric(col=None, period=6.283185307179586, **kwargs)

Bases: BaseMetric

Compute the angular spread statistic which measures uniformity of a distribution angles accounting for 2pi periodicity.

The strategy is to first map angles into unit vectors on the unit circle, and then compute the 2D centroid of those vectors. A uniform distribution of angles will lead to a distribution of unit vectors with mean that approaches the origin. In contrast, a delta function distribution of angles leads to a delta function distribution of unit vectors with a mean that lands on the unit circle.

The angular spread statistic is then defined as 1 - R, where R is the radial offset of the mean of the unit vectors derived from the input angles. R approaches 1 for a uniform distribution of angles and 0 for a delta function distribution of angles.

The optional parameter period may be used to specificy periodicity other than 2 pi.

run(data_slice, slice_point=None)

Calculate metric values.

Parameters:

• data_slice (numpy.ndarray, (N,)) – Values passed to metric by the slicer, which the metric will use to calculate metric values at each slice_point.

• slice_point (dict or None) – Dictionary of slice_point metadata passed to each metric. E.g. the ra/dec of the healpix pixel.

Returns:

metricValue – The metric value at each slice_point.

Return type:

int float or object

class rubin_sim.maf.metrics.AreaSummaryMetric(col='metricdata', metric_name='AreaSummary', area=18000.0, decreasing=True, reduce_func=None, **kwargs)

Bases: BaseMetric

Find the min/max of a value over the area with the ‘best’ results in the metric. This is a handy substitute for when users want to know “the WFD value”.

Parameters:

• area (float) – The area to consider (sq degrees)

• decreasing (bool) – Should the values be sorted by increasing or decreasing order. For values where “larger is better”, decreasing (True) is probably what you want. For metrics where “smaller is better” (e.g., astrometric precission), set decreasing to False.

• reduce_func (None) – The function to reduce the clipped values by. Will default to min/max depending on the bool val of the decreasing kwarg.

run(data_slice, slice_point=None)

Calculate metric values.

Parameters:

• data_slice (numpy.ndarray, (N,)) – Values passed to metric by the slicer, which the metric will use to calculate metric values at each slice_point.

• slice_point (dict or None) – Dictionary of slice_point metadata passed to each metric. E.g. the ra/dec of the healpix pixel.

Returns:

metricValue – The metric value at each slice_point.

Return type:

int float or object

class rubin_sim.maf.metrics.AreaThresholdMetric(col='metricdata', metric_name='AreaThreshold', upper_threshold=None, lower_threshold=None, **kwargs)

Bases: BaseMetric

Find the amount of area on the sky that meets a given threshold value.

The area per pixel is determined from the size of the metric_values array passed to the summary metric. This assumes that both all values are passed and that the metric was calculated with a healpix slicer.

Parameters:

• upper_threshold (float or None) – The metric value must be below this threshold to count toward the area. Default None implies no upper bound.

• lower_threshold (float or None, opt) – The metric value must be above this threshold to count toward the area. Default None implies no lower bound.

run(data_slice, slice_point=None)

Calculate metric values.

Parameters:

• data_slice (numpy.ndarray, (N,)) – Values passed to metric by the slicer, which the metric will use to calculate metric values at each slice_point.

• slice_point (dict or None) – Dictionary of slice_point metadata passed to each metric. E.g. the ra/dec of the healpix pixel.

Returns:

metricValue – The metric value at each slice_point.

Return type:

int float or object

class rubin_sim.maf.metrics.BDParallaxMetric(metric_name='bdParallax', m5_col='fiveSigmaDepth', filter_col='filter', seeing_col='seeingFwhmGeom', badval=0, mags=None, parallax_snr=10.0, distances=array([10, 20, 30, 40, 50, 60, 70, 80, 90, 100, 110, 120, 130, 140, 150, 160, 170, 180, 190]), atm_err=0.01, normalize=False, **kwargs)

Bases: BaseMetric

Calculate the distance to which one could reach a parallax SNR for a given object

Modification of ParallaxMetric, illustrated in jgizis/ LSST-BD-Cadence/blob/main/bd_allLT_baseline_17.ipynb

Uses columns ra_pi_amp and dec_pi_amp, calculated by the ParallaxFactorStacker.

Parameters:

• metricName (str, opt) – Default ‘parallax’.

• m5_col (str, opt) – The default column name for m5 information in the input data. Default fiveSigmaDepth.

• filter_col (str, opt) – The column name for the filter information. Default filter.

• seeing_col (str, opt) – The column name for the seeing information. Since the astrometry errors are based on the physical size of the PSF, this should be the FWHM of the physical psf. Default seeingFwhmGeom.

• mags (dict or None) – The absolute magnitude of the object in question. Keys of filter name, values in mags. Defaults to an L7 spectral type if None.

• distances (np.array, (N,)) – Distances to try putting the object at (pc).

• atm_err (float, opt) – The expected centroiding error due to the atmosphere, in arcseconds. Default 0.01.

• badval (float, opt) – The value to return when the metric value cannot be calculated. Default 0.

run(data_slice, slice_point=None)

Calculate metric values.

Parameters:

• data_slice (numpy.ndarray, (N,)) – Values passed to metric by the slicer, which the metric will use to calculate metric values at each slice_point.

• slice_point (dict or None) – Dictionary of slice_point metadata passed to each metric. E.g. the ra/dec of the healpix pixel.

Returns:

metricValue – The metric value at each slice_point.

Return type:

int float or object

class rubin_sim.maf.metrics.BaseMetric(col=None, metric_name=None, maps=None, units=None, metric_dtype=None, badval=-666, mask_val=None)

Bases: object

Base class for the metrics. Sets up some basic functionality for the MAF framework: after __init__ every metric will record the columns (and stackers) it requires into the column registry, and the metric_name, metric_dtype, and units for the metric will be set.

Parameters:

• col (str or list [str]) – Names of the data columns that the metric will use. The columns required for each metric is tracked in the ColRegistry, and used to retrieve data from the opsim database. Can be a single string or a list.

• metric_name (str) – Name to use for the metric (optional - if not set, will be derived).

• maps (list [rubin_sim.maf.maps]) – The maps that the metric will need (passed from the slicer).

• units (str) – The units for the value returned by the metric (optional - if not set, will be derived from the ColInfo).

• metric_dtype (str) – The type of value returned by the metric - ‘int’, ‘float’, ‘object’. If not set, will be derived by introspection.

• badval (float) – The value indicating “bad” values calculated by the metric.

run(data_slice, slice_point)

Calculate metric values.

Parameters:

• data_slice (numpy.ndarray, (N,)) – Values passed to metric by the slicer, which the metric will use to calculate metric values at each slice_point.

• slice_point (dict or None) – Dictionary of slice_point metadata passed to each metric. E.g. the ra/dec of the healpix pixel.

Returns:

metricValue – The metric value at each slice_point.

Return type:

int float or object

class rubin_sim.maf.metrics.BaseMoMetric(cols=None, metric_name=None, units='#', badval=0, comment=None, child_metrics=None, app_mag_col='appMag', app_mag_v_col='appMagV', m5_col='fiveSigmaDepth', night_col='night', mjd_col='observationStartMJD', snr_col='SNR', vis_col='vis', ra_col='ra', dec_col='dec', seeing_col='seeingFwhmGeom', exp_time_col='visitExposureTime', filter_col='filter')

Bases: BaseMetric

Base class for the moving object metrics. Intended to be used with the Moving Object Slicer.

Parameters:

• cols (list [str] or None) – List of the column names needed to run the metric. These columns must be in the moving object data files.

• metric_name (str or None) – Name of the metric. If None, a name is created based on the class name.

• units (str, opt) – Units for the resulting metric values.

• badval (float, opt) – Flag “bad” value returned if the metric cannot be calculated.

• comment (str or None, opt) – A default comment to use for the DisplayDict (display caption) if no value is provided elsewhere.

• child_metrics (list [BaseChildMetric] or None, opt) – A list of child metrics to run on the results of (this) metric. Child metrics take the metric results from this metric and add some additional processing or pull out a particular value. The results of the child metric are passed to a new MoMetricBundle.

• app_mag_col (str, opt) – Name of the apparent magnitude column in the object observations. Typically added by a stacker.

• app_mag_v_col (str, opt) – Name of the apparent magnitude V band column in the objects observations.

• m5_col (str, opt) – Name of the m5 limiting magnitude column in the objects observations.

• night_col (str, opt) – Name of the night column in the objects observations.

• mjd_col (str, opt) – Name of the MJD column in the objects observations.

• snr_col (str, opt) – Name of the column describing the SNR of this object in a given observation, in the objects observations. Added by a stacker.

• vis_col (str, opt) – Name of the column describing the probability of detecting this object in a given observation. Added by a stacker.

• ra_col (str, opt) – Name of the column describing the RA of this object in the objects observations.

• dec_col (str, opt) – Name of the column describing the Declination of this object in the objects observations.

• seeing_col (str, opt) – Name of the column describing the seeing to be used in evaluations of this object, in the objects observations. Tpyically this is the geometric seeing, for evaluating streak length.

• exp_time_col (str, opt) – Name of the exposure time column in the objects observations.

• filter_col (str, opt) – Name of the column describing the filter used for a given observation, in the objects observations.

run(sso_obs, orb, hval)

Calculate the metric value.

Parameters:

• sso_obs (np.ndarray, (N,)) – The input data to the metric (same as the parent metric).

• orb (np.ndarray, (N,)) – The information about the orbit for which the metric is being calculated.

• hval (float) – The H value for which the metric is being calculated.

Returns:

metric_val

Return type:

float or np.ndarray or dict

class rubin_sim.maf.metrics.BinaryMetric(col=None, metric_name=None, maps=None, units=None, metric_dtype=None, badval=-666, mask_val=None)

Bases: BaseMetric

Return 1 if there is data, badval otherwise.

run(data_slice, slice_point=None)

Calculate metric values.

Parameters:

• data_slice (numpy.ndarray, (N,)) – Values passed to metric by the slicer, which the metric will use to calculate metric values at each slice_point.

• slice_point (dict or None) – Dictionary of slice_point metadata passed to each metric. E.g. the ra/dec of the healpix pixel.

Returns:

metricValue – The metric value at each slice_point.

Return type:

int float or object

class rubin_sim.maf.metrics.BruteOSFMetric(metric_name='BruteOSFMetric', exp_time_col='visitExposureTime', mjd_col='observationStartMJD', maxgap=10.0, fudge=0.0, **kwargs)

Bases: BaseMetric

Assume I can’t trust the slewtime or visittime colums. This computes the fraction of time the shutter is open, with no penalty for the first exposure after a long gap (e.g., 1st exposure of the night). Presumably, the telescope will need to focus, so there’s not much a scheduler could do to optimize keeping the shutter open after a closure.

Parameters:

• maxgap (float) – The maximum gap between observations, in minutes. Assume anything longer the dome has closed.

• fudge (float) – Fudge factor if a constant has to be added to the exposure time values. This time (in seconds) is added to the exposure time.

• exp_time_col (str) – The name of the exposure time column. Assumed to be in seconds.

• mjd_col (str) – The name of the start of the exposures. Assumed to be in units of days.

run(data_slice, slice_point=None)

Calculate metric values.

Parameters:

• data_slice (numpy.ndarray, (N,)) – Values passed to metric by the slicer, which the metric will use to calculate metric values at each slice_point.

• slice_point (dict or None) – Dictionary of slice_point metadata passed to each metric. E.g. the ra/dec of the healpix pixel.

Returns:

metricValue – The metric value at each slice_point.

Return type:

int float or object

class rubin_sim.maf.metrics.CampaignLengthMetric(mjd_col='observationStartMJD', exp_time_col='visitExposureTime', min_exp_time=20, **kwargs)

Bases: BaseMetric

Calculate the number of seasons (roughly, years) a pointing is observed.

This corresponds to the ‘campaign length’ for lensed quasar time delays.

run(data_slice, slice_point)

Calculate metric values.

Parameters:

• data_slice (numpy.ndarray, (N,)) – Values passed to metric by the slicer, which the metric will use to calculate metric values at each slice_point.

• slice_point (dict or None) – Dictionary of slice_point metadata passed to each metric. E.g. the ra/dec of the healpix pixel.

Returns:

metricValue – The metric value at each slice_point.

Return type:

int float or object

class rubin_sim.maf.metrics.CheckColorSlope(color_length=1.0, slope_length=3.0, filter_col='filter', mjd_col='observationStartMJD')

Bases: object

Check if the data has a color and a slope

Parameters:

• color_length (float) – The maximum length of time different filters be observed to still count as a color (hours). Default 1 hour.

• slope_length (float) – The length of time to demand observations in the same filter be greater than (hours). Default 3 hours.

class rubin_sim.maf.metrics.ChipVendorMetric(cols=None, **kwargs)

Bases: BaseMetric

See what happens if we have chips from different vendors

run(data_slice, slice_point=None)

Calculate metric values.

Parameters:

• data_slice (numpy.ndarray, (N,)) – Values passed to metric by the slicer, which the metric will use to calculate metric values at each slice_point.

• slice_point (dict or None) – Dictionary of slice_point metadata passed to each metric. E.g. the ra/dec of the healpix pixel.

Returns:

metricValue – The metric value at each slice_point.

Return type:

int float or object

class rubin_sim.maf.metrics.CoaddM5PerNightMetric(night_col='night', m5_col='fiveSigmaDepth', bins=array([20., 20.05, 20.1, 20.15, 20.2, 20.25, 20.3, 20.35, 20.4, 20.45, 20.5, 20.55, 20.6, 20.65, 20.7, 20.75, 20.8, 20.85, 20.9, 20.95, 21., 21.05, 21.1, 21.15, 21.2, 21.25, 21.3, 21.35, 21.4, 21.45, 21.5, 21.55, 21.6, 21.65, 21.7, 21.75, 21.8, 21.85, 21.9, 21.95, 22., 22.05, 22.1, 22.15, 22.2, 22.25, 22.3, 22.35, 22.4, 22.45, 22.5, 22.55, 22.6, 22.65, 22.7, 22.75, 22.8, 22.85, 22.9, 22.95, 23., 23.05, 23.1, 23.15, 23.2, 23.25, 23.3, 23.35, 23.4, 23.45, 23.5, 23.55, 23.6, 23.65, 23.7, 23.75, 23.8, 23.85, 23.9, 23.95, 24., 24.05, 24.1, 24.15, 24.2, 24.25, 24.3, 24.35, 24.4, 24.45, 24.5, 24.55, 24.6, 24.65, 24.7, 24.75, 24.8, 24.85, 24.9, 24.95]), units='mag', **kwargs)

Bases: BaseMetric

Histogram the coadded depth of visits in each night.

Splits the visits by night, then histograms the coadded depth.

Parameters:

• night_col (str, optional) – The column name for the night of each observation. Default ‘night’.

• m5_col (str, optional) – The column name for the five sigma depth of each observation.

• bins (np.ndarray, (N,) optional) – The bins to use for the histogram of magnitude values.

Returns:

histogram – Returns a histogram of the coadded depth per night at each slice point; these histograms can be combined and plotted using the ‘SummaryHistogram plotter’.

Return type:

np.ndarray

run(data_slice, slice_point=None)

Calculate metric values.

Parameters:

• data_slice (numpy.ndarray, (N,)) – Values passed to metric by the slicer, which the metric will use to calculate metric values at each slice_point.

• slice_point (dict or None) – Dictionary of slice_point metadata passed to each metric. E.g. the ra/dec of the healpix pixel.

Returns:

metricValue – The metric value at each slice_point.

Return type:

int float or object

class rubin_sim.maf.metrics.Coaddm5Metric(m5_col='fiveSigmaDepth', metric_name='CoaddM5', filter_name=None, filter_col='Filter', units='mag', **kwargs)

Bases: BaseMetric

Calculate the coadded m5 value.

Parameters:

• m5_col (str, optional) – Name of the m5 column. Default fiveSigmaDepth.

• metric_name (str, optional) – Name to associate with the metric output. Default “CoaddM5”.

• filter_name (str, optional) – Optionally specify a filter to sub-select visits. Default None, does no sub-selection or checking.

• filter_col (str, optional) – Name of the filter column.

• units (str, optional) – Units for the metric. Default “mag”.

run(data_slice, slice_point=None)

Calculate metric values.

Parameters:

• data_slice (numpy.ndarray, (N,)) – Values passed to metric by the slicer, which the metric will use to calculate metric values at each slice_point.

• slice_point (dict or None) – Dictionary of slice_point metadata passed to each metric. E.g. the ra/dec of the healpix pixel.

Returns:

metricValue – The metric value at each slice_point.

Return type:

int float or object

class rubin_sim.maf.metrics.ColRegistry

Bases: object

ColRegistry tracks the columns needed for all metric objects (kept internally in a set).

ColRegistry.col_set : a set of all unique columns required for metrics. ColRegistry.dbCols : the subset of these which come from the database. ColRegistry.stackerCols : the dictionary of [columns: stacker class].

add_cols(col_array)

Add the columns in ColArray into the ColRegistry.

Add the columns in col_array into the ColRegistry set (self.col_set) and identifies their source, using ColInfo (rubin_sim.maf.stackers.getColInfo).

Parameters:

col_array (list) – list of columns used in a metric.

clear_reg()

Clear the registry

class rubin_sim.maf.metrics.ColorAsteroidMetric(weight_det=10, snr_max=20, snr_limit=None, **kwargs)

Bases: BaseMoMetric

Calculate the likelihood of being able to calculate the color of an object. This metric is appropriate for MBAs and NEOs, and other inner solar system objects.

Parameters:

• weight_det (float, opt) – The SNR-weighted number of detections required (per bandpass in any ONE of the filters in filterlist). Default 10.

• snr_limit (float or None, opt) – If snr_limit is set as a float, then requires object to be above snr_limit SNR in the image. If snr_limit is None, this uses the probabilistic ‘visibility’ calculated by the vis stacker, which means SNR ~ 5. Default is None.

• snr_max (float, opt) – Maximum value toward the SNR-weighting to consider. Default 20.

Returns:

flag – An integer ‘flag’ that indicates whether the mean magnitude (and thus a color) was determined in: 0 = no bands 1 = g and (r or i) and (z or y). i.e. obtain colors g-r or g-i PLUS g-z or g-y 2 = Any 4 different filters (from grizy). i.e. colors = g-r, r-i, i-z, OR r-i, i-z, z-y.. 3 = All 5 from grizy. i.e. colors g-r, r-i, i-z, z-y. 4 = All 6 filters (ugrizy) – best possible! add u-g.

Return type:

int

Notes

The metric evaluates if the SNR-weighted number of observations are enough to determine an approximate lightcurve and phase function – and from this, then a color for the asteroid can be determined. The assumption is that you must fit the lightcurve/phase function in each bandpass, and could do this well-enough if you have at least weight_det SNR-weighted observations in the bandpass. e.g. to find a g-r color, you must have 10 (SNR-weighted) obs in g and 10 in r.

For more details, see https://docs.google.com/document/d/1GAriM7trpTS08uanjUF7PyKALB2JBTjVT7Y6R30i0-8/edit?usp=sharing

Contributed by Wes Fraser, Steven Chesley & the inner solar system working group.

run(sso_obs, orb, hval)

Calculate the metric value.

Parameters:

• sso_obs (np.ndarray, (N,)) – The input data to the metric (same as the parent metric).

• orb (np.ndarray, (N,)) – The information about the orbit for which the metric is being calculated.

• hval (float) – The H value for which the metric is being calculated.

Returns:

metric_val

Return type:

float or np.ndarray or dict

class rubin_sim.maf.metrics.ColorSlope2NightMetric(mag=None, night_col='night', filter_col='filter', m5_col='fiveSigmaDepth', color_length=1.0, slope_length=15.0, time_col='observationStartMJD', units='#', metric_name='ColorSlope2Night', **kwargs)

Bases: ColorSlopeMetric

Like ColorSlopeMetric, but span over 2 nights

Parameters:

• mag (dict) – Dictionary with filternames as keys and minimum depth m5 magnitudes as values. If None, defaults to mag 20 in ugrizy.

• color_length (float) – The maximum length of time different filters be observed to still count as a color (hours). Default 1 hour.

• slope_length (float) – The length of time to demand observations in the same filter be greater than (hours). Default 15 hours.

run(data_slice, slice_point=None)

Calculate metric values.

Parameters:

• data_slice (numpy.ndarray, (N,)) – Values passed to metric by the slicer, which the metric will use to calculate metric values at each slice_point.

• slice_point (dict or None) – Dictionary of slice_point metadata passed to each metric. E.g. the ra/dec of the healpix pixel.

Returns:

metricValue – The metric value at each slice_point.

Return type:

int float or object

class rubin_sim.maf.metrics.ColorSlopeMetric(mag=None, night_col='night', filter_col='filter', m5_col='fiveSigmaDepth', color_length=1.0, slope_length=3.0, time_col='observationStartMJD', units='#', metric_name='ColorSlope', **kwargs)

Bases: BaseMetric

How many times do we get a color and slope in a night

A proxy metric for seeing how many times there would be the possibility of identifying and classifying a transient.

Parameters:

• mag (dict) – Dictionary with filternames as keys and minimum depth m5 magnitudes as values. If None, defaults to mag 20 in ugrizy.

• color_length (float) – The maximum length of time different filters be observed to still count as a color (hours). Default 1 hour.

• slope_length (float) – The length of time to demand observations in the same filter be greater than (hours). Default 3 hours.

run(data_slice, slice_point=None)

Calculate metric values.

Parameters:

• data_slice (numpy.ndarray, (N,)) – Values passed to metric by the slicer, which the metric will use to calculate metric values at each slice_point.

• slice_point (dict or None) – Dictionary of slice_point metadata passed to each metric. E.g. the ra/dec of the healpix pixel.

Returns:

metricValue – The metric value at each slice_point.

Return type:

int float or object

class rubin_sim.maf.metrics.CountBeyondThreshold(col=None, lower_threshold=None, upper_threshold=None, **kwargs)

Bases: BaseMetric

Count the number of entries in a data column above or below the threshold.

run(data_slice, slice_point=None)

Calculate metric values.

Parameters:

• data_slice (numpy.ndarray, (N,)) – Values passed to metric by the slicer, which the metric will use to calculate metric values at each slice_point.

• slice_point (dict or None) – Dictionary of slice_point metadata passed to each metric. E.g. the ra/dec of the healpix pixel.

Returns:

metricValue – The metric value at each slice_point.

Return type:

int float or object

class rubin_sim.maf.metrics.CountExplimMetric(min_exp=20.0, expected_exp=30.0, exp_col='visitExposureTime', **kwargs)

Bases: BaseMetric

Count the number of x second visits. Useful for rejecting very short exposures and counting 60s exposures as 2 visits.

Parameters:

• min_exp (float, optional) – Minimum exposure time to consider as a “visit”. Exposures shorter than this will not be counted (count as 0).

• expected_exp (float, optional) – Typical exposure time to expect. Exposures longer than this will be counted as round(visit exposure time / expected_exp). (i.e. 40s = 1, 50s = 2).

• exp_col (str, optional) – Column name to use for visit exposure time.

Returns:

value – The number of visits longer than min_exp and weighted by expected_exp.

Return type:

int

run(data_slice, slice_point=None)

Calculate metric values.

Parameters:

• data_slice (numpy.ndarray, (N,)) – Values passed to metric by the slicer, which the metric will use to calculate metric values at each slice_point.

• slice_point (dict or None) – Dictionary of slice_point metadata passed to each metric. E.g. the ra/dec of the healpix pixel.

Returns:

metricValue – The metric value at each slice_point.

Return type:

int float or object

class rubin_sim.maf.metrics.CountMetric(col=None, units='#', **kwargs)

Bases: BaseMetric

Count the length of a simData column slice.

run(data_slice, slice_point=None)

Calculate metric values.

Parameters:

• data_slice (numpy.ndarray, (N,)) – Values passed to metric by the slicer, which the metric will use to calculate metric values at each slice_point.

• slice_point (dict or None) – Dictionary of slice_point metadata passed to each metric. E.g. the ra/dec of the healpix pixel.

Returns:

metricValue – The metric value at each slice_point.

Return type:

int float or object

class rubin_sim.maf.metrics.CountRatioMetric(col=None, norm_val=1.0, metric_name=None, units='', **kwargs)

Bases: BaseMetric

Count the length of a column slice, then divide by norm_val.

run(data_slice, slice_point=None)

Calculate metric values.

Parameters:

• data_slice (numpy.ndarray, (N,)) – Values passed to metric by the slicer, which the metric will use to calculate metric values at each slice_point.

• slice_point (dict or None) – Dictionary of slice_point metadata passed to each metric. E.g. the ra/dec of the healpix pixel.

Returns:

metricValue – The metric value at each slice_point.

Return type:

int float or object

class rubin_sim.maf.metrics.CountSubsetMetric(col=None, subset=None, units='#', **kwargs)

Bases: BaseMetric

Count the length of a column slice which matches subset.

run(data_slice, slice_point=None)

Calculate metric values.

Parameters:

• data_slice (numpy.ndarray, (N,)) – Values passed to metric by the slicer, which the metric will use to calculate metric values at each slice_point.

• slice_point (dict or None) – Dictionary of slice_point metadata passed to each metric. E.g. the ra/dec of the healpix pixel.

Returns:

metricValue – The metric value at each slice_point.

Return type:

int float or object

class rubin_sim.maf.metrics.CountUniqueMetric(col=None, metric_name=None, maps=None, units=None, metric_dtype=None, badval=-666, mask_val=None)

Bases: BaseMetric

Return the number of unique values.

run(data_slice, slice_point=None)

Calculate metric values.

Parameters:

• data_slice (numpy.ndarray, (N,)) – Values passed to metric by the slicer, which the metric will use to calculate metric values at each slice_point.

• slice_point (dict or None) – Dictionary of slice_point metadata passed to each metric. E.g. the ra/dec of the healpix pixel.

Returns:

metricValue – The metric value at each slice_point.

Return type:

int float or object

class rubin_sim.maf.metrics.CrowdingM5Metric(crowding_error=0.1, filtername='r', seeing_col='seeingFwhmGeom', metric_name=None, maps=['StellarDensityMap'], **kwargs)

Bases: 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 – The magnitude of a star which has a photometric error of crowding_error

Return type:

float

run(data_slice, slice_point=None)

Calculate metric values.

Parameters:

• data_slice (numpy.ndarray, (N,)) – Values passed to metric by the slicer, which the metric will use to calculate metric values at each slice_point.

• slice_point (dict or None) – Dictionary of slice_point metadata passed to each metric. E.g. the ra/dec of the healpix pixel.

Returns:

metricValue – The metric value at each slice_point.

Return type:

int float or object

class rubin_sim.maf.metrics.CrowdingMagUncertMetric(rmag=20.0, seeing_col='seeingFwhmGeom', units='mag', metric_name=None, filtername='r', maps=['StellarDensityMap'], **kwargs)

Bases: BaseMetric

Calculate the mean uncertainty in magnitude due to crowding.

Parameters:

rmag (float) – The magnitude of the star to consider.

Returns:

mag_uncert – The uncertainty in magnitudes caused by crowding for a star of rmag.

Return type:

float

run(data_slice, slice_point=None)

Calculate metric values.

Parameters:

• data_slice (numpy.ndarray, (N,)) – Values passed to metric by the slicer, which the metric will use to calculate metric values at each slice_point.

• slice_point (dict or None) – Dictionary of slice_point metadata passed to each metric. E.g. the ra/dec of the healpix pixel.

Returns:

metricValue – The metric value at each slice_point.

Return type:

int float or object

class rubin_sim.maf.metrics.CumulativeMetric(metric_name='Cumulative', time_col='observationStartMJD', night_col='night', interp_points=None, **kwargs)

Bases: 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.

run(data_slice, slice_point=None)

Calculate metric values.

Parameters:

• data_slice (numpy.ndarray, (N,)) – Values passed to metric by the slicer, which the metric will use to calculate metric values at each slice_point.

• slice_point (dict or None) – Dictionary of slice_point metadata passed to each metric. E.g. the ra/dec of the healpix pixel.

Returns:

metricValue – The metric value at each slice_point.

Return type:

int float or object

class rubin_sim.maf.metrics.DcrPrecisionMetric(metric_name='DCRprecision', seeing_col='seeingFwhmGeom', m5_col='fiveSigmaDepth', ha_col='HA', pa_col='paraAngle', filter_col='filter', atm_err=0.01, sed_template='flat', rmag=20.0, **kwargs)

Bases: 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.

run(data_slice, slice_point=None)

Calculate metric values.

Parameters:

• data_slice (numpy.ndarray, (N,)) – Values passed to metric by the slicer, which the metric will use to calculate metric values at each slice_point.

• slice_point (dict or None) – Dictionary of slice_point metadata passed to each metric. E.g. the ra/dec of the healpix pixel.

Returns:

metricValue – The metric value at each slice_point.

Return type:

int float or object

class rubin_sim.maf.metrics.DiscoveryDistanceMetric(parent_discovery_metric, distance_col='geo_dist', badval=-999, **kwargs)

Bases: BaseChildMetric

Returns the distance of the first discovery track of an SSobject.

Parameters:

• parentDiscoveryMetric (BaseMoMetric) – The ‘parent’ metric which generated the metric data used calculate this ‘child’ metric.

• badval (float, opt) – Value to return when metric cannot be calculated.

run(sso_obs, orb, hval, metric_values)

Calculate the child metric value.

Parameters:

• sso_obs (np.ndarray, (N,)) – The input data to the metric (same as the parent metric).

• orb (np.ndarray, (N,)) – The information about the orbit for which the metric is being calculated.

• hval (float) – The H value for which the metric is being calculated.

• metric_values (dict or np.ndarray, (N,)) – The return value from the parent metric.

Returns:

metric_val

Return type:

float

class rubin_sim.maf.metrics.DiscoveryEclonlatMetric(parent_discovery_metric, badval=None, **kwargs)

Bases: BaseChildMetric

Returns the ecliptic lon/lat and solar elong of the first discovery track of an SSobject.

Parameters:

• parentDiscoveryMetric (BaseMoMetric) – The ‘parent’ metric which generated the metric data used calculate this ‘child’ metric.

• badval (float, opt) – Value to return when metric cannot be calculated.

run(sso_obs, orb, hval, metric_values)

Calculate the child metric value.

Parameters:

• sso_obs (np.ndarray, (N,)) – The input data to the metric (same as the parent metric).

• orb (np.ndarray, (N,)) – The information about the orbit for which the metric is being calculated.

• hval (float) – The H value for which the metric is being calculated.

• metric_values (dict or np.ndarray, (N,)) – The return value from the parent metric.

Returns:

metric_val

Return type:

float

class rubin_sim.maf.metrics.DiscoveryMetric(n_obs_per_night=2, t_min=0.003472222222222222, t_max=0.0625, n_nights_per_window=3, t_window=15, snr_limit=None, badval=None, **kwargs)

Bases: BaseMoMetric

Identify the discovery opportunities for an SSobject.

Parameters:

• n_obs_per_night (int, opt) – Number of observations required within a single night. Default 2.

• t_min (float, opt) – Minimum time span between observations in a single night, in days. Default 5 minutes (5/60/24).

• t_max (float, opt) – Maximum time span between observations in a single night, in days. Default 90 minutes.

• n_nights_per_window (int, opt) – Number of nights required with observations, within the track window. Default 3.

• t_window (int, opt) – Number of nights included in the track window. Default 15.

• snr_limit (None or float, opt) – SNR limit to use for observations. If snr_limit is None, (default), then it uses the completeness calculation added to the ‘vis’ column (probabilistic visibility, based on 5-sigma limit). If snr_limit is not None, it uses this SNR value as a cutoff.

• metricName (str, opt) – The metric name to use. Default will be to construct Discovery_nObsPerNightxnNightsPerWindowintWindow.

run(sso_obs, orb, hval)

Calculate the metric value.

Parameters:

• sso_obs (np.ndarray, (N,)) – The input data to the metric (same as the parent metric).

• orb (np.ndarray, (N,)) – The information about the orbit for which the metric is being calculated.

• hval (float) – The H value for which the metric is being calculated.

Returns:

metric_val

Return type:

float or np.ndarray or dict

class rubin_sim.maf.metrics.DiscoveryNChancesMetric(parent_discovery_metric, badval=0, **kwargs)

Bases: BaseChildMetric

Calculate total number of discovery opportunities for an SSobject.

Returns total number of discovery opportunities. Child metric to be used with the Discovery Metric.

Parameters:

• parentDiscoveryMetric (BaseMoMetric) – The ‘parent’ metric which generated the metric data used calculate this ‘child’ metric.

• badval (float, opt) – Value to return when metric cannot be calculated.

run(sso_obs, orb, hval, metric_values)

Return the number of different discovery chances we had for each object/H combination.

class rubin_sim.maf.metrics.DiscoveryNObsMetric(parent_discovery_metric, badval=0, **kwargs)

Bases: BaseChildMetric

Calculates the number of observations in the first discovery track of an SSobject.

Parameters:

• parentDiscoveryMetric (BaseMoMetric) – The ‘parent’ metric which generated the metric data used calculate this ‘child’ metric.

• badval (float, opt) – Value to return when metric cannot be calculated.

run(sso_obs, orb, hval, metric_values)

Calculate the child metric value.

Parameters:

• sso_obs (np.ndarray, (N,)) – The input data to the metric (same as the parent metric).

• orb (np.ndarray, (N,)) – The information about the orbit for which the metric is being calculated.

• hval (float) – The H value for which the metric is being calculated.

• metric_values (dict or np.ndarray, (N,)) – The return value from the parent metric.

Returns:

metric_val

Return type:

float

class rubin_sim.maf.metrics.DiscoveryRadecMetric(parent_discovery_metric, badval=None, **kwargs)

Bases: BaseChildMetric

Returns the RA/Dec of the first discovery track of an SSobject.

Parameters:

• parentDiscoveryMetric (BaseMoMetric) – The ‘parent’ metric which generated the metric data used calculate this ‘child’ metric.

• badval (float, opt) – Value to return when metric cannot be calculated.

run(sso_obs, orb, hval, metric_values)

Calculate the child metric value.

Parameters:

• sso_obs (np.ndarray, (N,)) – The input data to the metric (same as the parent metric).

• orb (np.ndarray, (N,)) – The information about the orbit for which the metric is being calculated.

• hval (float) – The H value for which the metric is being calculated.

• metric_values (dict or np.ndarray, (N,)) – The return value from the parent metric.

Returns:

metric_val

Return type:

float

class rubin_sim.maf.metrics.DiscoveryTimeMetric(parent_discovery_metric, t_start=None, badval=-999, **kwargs)

Bases: BaseChildMetric

Returns the time of the first discovery track of an SSobject.

Parameters:

• parentDiscoveryMetric (BaseMoMetric) – The ‘parent’ metric which generated the metric data used calculate this ‘child’ metric.

• badval (float, opt) – Value to return when metric cannot be calculated.

run(sso_obs, orb, hval, metric_values)

Calculate the child metric value.

Parameters:

• sso_obs (np.ndarray, (N,)) – The input data to the metric (same as the parent metric).

• orb (np.ndarray, (N,)) – The information about the orbit for which the metric is being calculated.

• hval (float) – The H value for which the metric is being calculated.

• metric_values (dict or np.ndarray, (N,)) – The return value from the parent metric.

Returns:

metric_val

Return type:

float

class rubin_sim.maf.metrics.DiscoveryVelocityMetric(parent_discovery_metric, badval=-999, **kwargs)

Bases: BaseChildMetric

Returns the sky velocity of the first discovery track of an SSobject.

Parameters:

• parentDiscoveryMetric (BaseMoMetric) – The ‘parent’ metric which generated the metric data used calculate this ‘child’ metric.

• badval (float, opt) – Value to return when metric cannot be calculated.

run(sso_obs, orb, hval, metric_values)

Calculate the child metric value.

Parameters:

• sso_obs (np.ndarray, (N,)) – The input data to the metric (same as the parent metric).

• orb (np.ndarray, (N,)) – The information about the orbit for which the metric is being calculated.

• hval (float) – The H value for which the metric is being calculated.

• metric_values (dict or np.ndarray, (N,)) – The return value from the parent metric.

Returns:

metric_val

Return type:

float

class rubin_sim.maf.metrics.ExgalM5(m5_col='fiveSigmaDepth', metric_name='ExgalM5', units='mag', filter_col='filter', **kwargs)

Bases: 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 – Coadded m5 value, corrected for galactic dust extinction.

Return type:

float

run(data_slice, slice_point)

Compute the co-added m5 depth and then apply dust extinction to that magnitude.

class rubin_sim.maf.metrics.ExgalM5WithCuts(m5_col='fiveSigmaDepth', filter_col='filter', metric_name='Exgalm5WithCuts', units='mag', lsst_filter='i', extinction_cut=0.2, depth_cut=25.9, n_filters=6, **kwargs)

Bases: BaseMetric

Calculate co-added five-sigma limiting depth, but apply dust extinction and depth cuts. This means that places on the sky that don’t meet the dust extinction, coadded depth, or filter coverage cuts will have masked values on those places.

This metric is useful for DESC static science and weak lensing metrics. In particular, it is required as input for the StaticProbesFoMEmulatorMetricSimple (a summary metric to emulate a 3x2pt FOM).

Note: this metric calculates the depth after dust extinction in band ‘lsst_filter’, but because it looks for coverage in all bands, there should generally be no filter-constraint on the sql query.

run(data_slice, slice_point)

Calculate metric values.

Parameters:

• data_slice (numpy.ndarray, (N,)) – Values passed to metric by the slicer, which the metric will use to calculate metric values at each slice_point.

• slice_point (dict or None) – Dictionary of slice_point metadata passed to each metric. E.g. the ra/dec of the healpix pixel.

Returns:

metricValue – The metric value at each slice_point.

Return type:

int float or object

class rubin_sim.maf.metrics.FOArea(col='metricdata', n_visit=825, asky=18000.0, nside=128, norm=False, **kwargs)

Bases: 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.

run(data_slice, slice_point=None)

Calculate metric values.

Parameters:

• data_slice (numpy.ndarray, (N,)) – Values passed to metric by the slicer, which the metric will use to calculate metric values at each slice_point.

• slice_point (dict or None) – Dictionary of slice_point metadata passed to each metric. E.g. the ra/dec of the healpix pixel.

Returns:

metricValue – The metric value at each slice_point.

Return type:

int float or object

class rubin_sim.maf.metrics.FONv(col='metricdata', asky=18000.0, nside=128, n_visit=825, norm=False, **kwargs)

Bases: 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.

run(data_slice, slice_point=None)

Calculate metric values.

Parameters:

• data_slice (numpy.ndarray, (N,)) – Values passed to metric by the slicer, which the metric will use to calculate metric values at each slice_point.

• slice_point (dict or None) – Dictionary of slice_point metadata passed to each metric. E.g. the ra/dec of the healpix pixel.

Returns:

metricValue – The metric value at each slice_point.

Return type:

int float or object

class rubin_sim.maf.metrics.FftMetric(times_col='expmjd', metric_name='Fft', n_coeffs=100, **kwargs)

Bases: BaseMetric

Calculate a truncated FFT of the exposure times.

run(data_slice, slice_point=None)

Calculate metric values.

Parameters:

• data_slice (numpy.ndarray, (N,)) – Values passed to metric by the slicer, which the metric will use to calculate metric values at each slice_point.

• slice_point (dict or None) – Dictionary of slice_point metadata passed to each metric. E.g. the ra/dec of the healpix pixel.

Returns:

metricValue – The metric value at each slice_point.

Return type:

int float or object

class rubin_sim.maf.metrics.FootprintFractionMetric(footprint=None, n_min=1, **kwargs)

Bases: 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

run(data_slice, slice_point=None)

Calculate metric values.

Parameters:

• data_slice (numpy.ndarray, (N,)) – Values passed to metric by the slicer, which the metric will use to calculate metric values at each slice_point.

• slice_point (dict or None) – Dictionary of slice_point metadata passed to each metric. E.g. the ra/dec of the healpix pixel.

Returns:

metricValue – The metric value at each slice_point.

Return type:

int float or object

class rubin_sim.maf.metrics.FracAboveMetric(col=None, cutoff=0.5, scale=1, metric_name=None, **kwargs)

Bases: BaseMetric

Find the fraction of data values above a given cutoff.

run(data_slice, slice_point=None)

Calculate metric values.

Parameters:

• data_slice (numpy.ndarray, (N,)) – Values passed to metric by the slicer, which the metric will use to calculate metric values at each slice_point.

• slice_point (dict or None) – Dictionary of slice_point metadata passed to each metric. E.g. the ra/dec of the healpix pixel.

Returns:

metricValue – The metric value at each slice_point.

Return type:

int float or object

class rubin_sim.maf.metrics.FracBelowMetric(col=None, cutoff=0.5, scale=1, metric_name=None, **kwargs)

Bases: BaseMetric

Find the fraction of data values below a given cutoff.

run(data_slice, slice_point=None)

Calculate metric values.

Parameters:

• data_slice (numpy.ndarray, (N,)) – Values passed to metric by the slicer, which the metric will use to calculate metric values at each slice_point.

• slice_point (dict or None) – Dictionary of slice_point metadata passed to each metric. E.g. the ra/dec of the healpix pixel.

Returns:

metricValue – The metric value at each slice_point.

Return type:

int float or object

class rubin_sim.maf.metrics.FullRangeAngleMetric(col=None, metric_name=None, maps=None, units=None, metric_dtype=None, badval=-666, mask_val=None)

Bases: BaseMetric

Calculate the full range of an angular (degrees) column slice.

‘FullRangeAngle’ differs from ‘FullRange’ in that it accounts for wraparound at 2pi.

run(data_slice, slice_point=None)

Calculate metric values.

Parameters:

• data_slice (numpy.ndarray, (N,)) – Values passed to metric by the slicer, which the metric will use to calculate metric values at each slice_point.

• slice_point (dict or None) – Dictionary of slice_point metadata passed to each metric. E.g. the ra/dec of the healpix pixel.

Returns:

metricValue – The metric value at each slice_point.

Return type:

int float or object

class rubin_sim.maf.metrics.FullRangeMetric(col=None, metric_name=None, maps=None, units=None, metric_dtype=None, badval=-666, mask_val=None)

Bases: BaseMetric

Calculate the range of a simData column slice.

run(data_slice, slice_point=None)

Calculate metric values.

Parameters:

• data_slice (numpy.ndarray, (N,)) – Values passed to metric by the slicer, which the metric will use to calculate metric values at each slice_point.

• slice_point (dict or None) – Dictionary of slice_point metadata passed to each metric. E.g. the ra/dec of the healpix pixel.

Returns:

metricValue – The metric value at each slice_point.

Return type:

int float or object

class rubin_sim.maf.metrics.GalPlaneFootprintMetric(science_map, tau_obs=None, mag_cuts=None, filter_col='filter', m5_col='fiveSigmaDepth', filterlist=None, **kwargs)

Bases: BaseMetric

Evaluate the survey overlap with desired regions in the Galactic Plane and Magellanic Clouds, by referencing the pre-computed priority maps provided. These priority maps are keyed by science area (science_map) and per filter. The returned metric values are summed over all filters.

Parameters:

• science_map (str) – Name of the priority footprint map key to use from the column headers contained in the priority_GalPlane_footprint_map_data tables.

• tau_obs (np.ndarray or list of float, opt) – Timescales of minimum-required observations intervals for various classes of time variability. Default (None), uses TAU_OBS. In general, this should be left as the default and consistent across all galactic-plane oriented metrics.

• mag_cuts (dict of float, opt) – Magnitudes to use as cutoffs for individual image depths. Default None uses a default set of values which correspond roughly to the 50th percentile.

• filter_col (str, opt) – Name of the filter column. Default ‘filter’.

• m5_col (str, opt) – Name of the five-sigma depth column. Default ‘fiveSigmaDepth’.

• filterlist (list of str, opt) – The filters to consider from the priority map and observations. Default None uses u, g, r, i, z, and y.

• metricName (str, opt) – Name for the metric. Default ‘GalPlaneFootprintMetric_{scienceMap}

run(data_slice, slice_point)

Calculate the number of observations that meet the mag_cut values at each slice_point.

Also calculate the number of observations * the priority map summed over all filter. Return both of these values as a dictionary.

class rubin_sim.maf.metrics.GalPlaneSeasonGapsTimescaleMetric(science_map, tau_var=None, mag_limit=22.0, expected_season_gap=145, mjd_col='observationStartMJD', m5_col='fiveSigmaDepth', **kwargs)

Bases: BaseMetric

Evaluate the gap between sequential seasonal gaps in observations in a lightcurve relative to the scientifically desired sampling interval.

Parameters:

• science_map (str) – Name of the priority footprint map key to use from the column headers contained in the priority_GalPlane_footprint_map_data tables.

• tau_var (np.ndarray or list of float, opt) – Timescales of variability for various classes of time variability. Default (None), uses TAU_OBS * 5. In general, this should be left as the default and consistent across all galactic-plane oriented metrics.

• mag_limit (float, opt) – Magnitude limit to use as a cutoff for various observations. Default 22.0.

• expected_season_gap (float, opt) – The typical season gap expected for a galactic plane field in days. The default, 145 days, is typical for a bulge field.

• mjd_col (str, opt) – The name of the observation start MJD column. Default ‘observationStartMJD’.

• m5_col (`str’, opt) – The name of the five sigma depth column. Default ‘fiveSigmaDepth’.

run(data_slice, slice_point)

Calculate metric values.

Parameters:

• data_slice (numpy.ndarray, (N,)) – Values passed to metric by the slicer, which the metric will use to calculate metric values at each slice_point.

• slice_point (dict or None) – Dictionary of slice_point metadata passed to each metric. E.g. the ra/dec of the healpix pixel.

Returns:

metricValue – The metric value at each slice_point.

Return type:

int float or object

class rubin_sim.maf.metrics.GalPlaneTimePerFilterMetric(science_map, mag_cuts=None, mjd_col='observationStartMJD', exp_time_col='visitExposureTime', filter_col='filter', m5_col='fiveSigmaDepth', filterlist=None, **kwargs)

Bases: BaseMetric

Evaluate the fraction of exposure time spent in each filter as a fraction of the total exposure time dedicated to that healpix in the weighted galactic plane priority maps.

Parameters:

• scienceMap (str) – Name of the priority footprint map key to use from the column headers contained in the priority_GalPlane_footprint_map_data tables.

• magCuts (dict of float, opt) – Magnitudes to use as cutoffs for individual image depths. Default None uses a default set of values which correspond roughly to the 50th percentile.

• mjd_col (str, opt) – Name of the observation start MJD column. Default ‘observationStartMJD’.

• exp_time_col (str, opt) – Name of the exposure time column. Default ‘visitExposureTime’.

• filter_col (str, opt) – Name of the filter column. Default ‘filter’.

• m5_col (str, opt) – Name of the five-sigma depth column. Default ‘fiveSigmaDepth’.

• filterlist (list of str, opt) – The filters to consider from the priority map and observations. Default None uses u, g, r, i, z, and y.

• metricName (str, opt) – Name for the metric. Default ‘GalPlaneFootprintMetric_{scienceMap}

run(data_slice, slice_point)

Calculate the ratio of the actual on-sky exposure time per filter compared to the ideal on-sky exposure time per filter at this point on the sky across all filters.

class rubin_sim.maf.metrics.GalPlaneVisitIntervalsTimescaleMetric(science_map, tau_obs=None, mag_limit=22.0, mjd_col='observationStartMJD', m5_col='fiveSigmaDepth', **kwargs)

Bases: BaseMetric

Evaluate the intervals between sequential observations in a lightcurve relative to the scientifically desired sampling interval.

Parameters:

• science_map (str) – Name of the priority footprint map key to use from the column headers contained in the priority_GalPlane_footprint_map_data tables.

• tau_obs (np.ndarray or list of float, opt) – Timescales of minimum-required observations intervals for various classes of time variability. Default (None), uses TAU_OBS. In general, this should be left as the default and consistent across all galactic-plane oriented metrics.

• mag_limit (float, opt) – Magnitude limit to use as a cutoff for various observations. Default 22.0.

• mjd_col (str, opt) – The name of the observation start MJD column. Default ‘observationStartMJD’.

• m5_col (`str’, opt) – The name of the five sigma depth column. Default ‘fiveSigmaDepth’.

run(data_slice, slice_point=None)

Calculate metric values.

Parameters:

• data_slice (numpy.ndarray, (N,)) – Values passed to metric by the slicer, which the metric will use to calculate metric values at each slice_point.

• slice_point (dict or None) – Dictionary of slice_point metadata passed to each metric. E.g. the ra/dec of the healpix pixel.

Returns:

metricValue – The metric value at each slice_point.

Return type:

int float or object

class rubin_sim.maf.metrics.GapsMetric(times_col='observationStartMJD', time_scale=2.0, units='N', **kwargs)

Bases: BaseMetric

Compute the number of times a gaps of a specified timescale (+/- 1/2 timescale) is sampled.

Parameters:

• times_col (str, optional) – The column name for the exposure times. Values assumed to be in days. Default is ‘observationStartMJD’.

• time_scale (float, optional) – Time scale to see how well it is sampled (hours). For example, the default of 2 hours means observations spaced anywhere between 1 and 3 hours apart will count as a sample. Default 2 hours.

• units (str, optional) – Default units to use for plots, etc. Default is “N” (for number).

run(data_slice, slice_point=None)

Calculate metric values.

Parameters:

• data_slice (numpy.ndarray, (N,)) – Values passed to metric by the slicer, which the metric will use to calculate metric values at each slice_point.

• slice_point (dict or None) – Dictionary of slice_point metadata passed to each metric. E.g. the ra/dec of the healpix pixel.

Returns:

metricValue – The metric value at each slice_point.

Return type:

int float or object

class rubin_sim.maf.metrics.GeneralUniformityMetric(col='observationStartMJD', units='', min_value=None, max_value=None, **kwargs)

Bases: BaseMetric

Calculate how uniformly any values are distributed.

This is based on how a KS-test works: look at the cumulative distribution of data, and compare to a perfectly uniform cumulative distribution. Perfectly uniform observations = 0, perfectly non-uniform = 1. To be “perfectly uniform” here, the endpoints need to be included.

Parameters:

• col (str, optional) – The column of data to use for the metric. The default is “observationStartMJD” as this is most typically used with time.

• min_value (float, optional) – The minimum value expected for the data. Default None will calculate use the minimum value in this dataslice (which may not cover the full range).

• max_value (float, optional) – The maximum value expected for the data. Default None will calculate use the maximum value in this dataslice (which may not cover the full range).

run(data_slice, slice_point=None)

Calculate metric values.

Parameters:

• data_slice (numpy.ndarray, (N,)) – Values passed to metric by the slicer, which the metric will use to calculate metric values at each slice_point.

• slice_point (dict or None) – Dictionary of slice_point metadata passed to each metric. E.g. the ra/dec of the healpix pixel.

Returns:

metricValue – The metric value at each slice_point.

Return type:

int float or object

class rubin_sim.maf.metrics.HighVelocityMetric(psf_factor=2.0, snr_limit=None, velocity_col='velocity', **kwargs)

Bases: BaseMoMetric

Count number of times an SSobject appears trailed.

Count the number of times an asteroid is observed with a velocity high enough to make it appear trailed by a factor of (psf_factor)*PSF - i.e. velocity >= psf_factor * seeing / visitExpTime. Simply counts the total number of observations with high velocity.

Parameters:

• psf_factor (float, opt) – The factor to multiply the seeing/VisitExpTime by to compare against velocity.

• snr_limit (float or None) – If None, uses the probabilistic detection likelihood. If float, uses the SNR value as a flat cutoff value.

run(sso_obs, orb, hval)

Calculate the metric value.

Parameters:

• sso_obs (np.ndarray, (N,)) – The input data to the metric (same as the parent metric).

• orb (np.ndarray, (N,)) – The information about the orbit for which the metric is being calculated.

• hval (float) – The H value for which the metric is being calculated.

Returns:

metric_val

Return type:

float or np.ndarray or dict

class rubin_sim.maf.metrics.HighVelocityNightsMetric(psf_factor=2.0, n_obs_per_night=2, snr_limit=None, velocity_col='velocity', **kwargs)

Bases: BaseMoMetric

Count the number of discovery opportunities (via trailing) for an SSobject.

Determine the first time an asteroid is observed is observed with a velocity high enough to make it appear trailed by a factor of psf_factor*PSF with n_obs_per_night observations within a given night.

Parameters:

• psf_factor (float, opt) – Object velocity (deg/day) must be >= 24 * psf_factor * seeingGeom (”) / visitExpTime (s). Default is 2 (i.e. object trailed over 2 psf’s).

• n_obs_per_night (int, opt) – Number of observations per night required. Default 2.

• snr_limit (float or None) – If snr_limit is set as a float, then requires object to be above snr_limit SNR in the image. If snr_limit is None, this uses the probabilistic ‘visibility’ calculated by the vis stacker, which means SNR ~ 5.

• velocity_col (str, opt) – Name of the velocity column in the obs file. Default ‘velocity’. (note this is deg/day).

Returns:

time – The time of the first detection where the conditions are satisfed.

Return type:

float

run(sso_obs, orb, hval)

Calculate the metric value.

Parameters:

• sso_obs (np.ndarray, (N,)) – The input data to the metric (same as the parent metric).

• orb (np.ndarray, (N,)) – The information about the orbit for which the metric is being calculated.

• hval (float) – The H value for which the metric is being calculated.

Returns:

metric_val

Return type:

float or np.ndarray or dict

class rubin_sim.maf.metrics.HistogramM5Metric(bins=None, bin_col='night', m5_col='fiveSigmaDepth', units='mag', metric_name='HistogramM5Metric', **kwargs)

Bases: HistogramMetric

Calculate the coadded depth for each bin (e.g., per night).

run(data_slice, slice_point=None)

Calculate metric values.

Parameters:

• data_slice (numpy.ndarray, (N,)) – Values passed to metric by the slicer, which the metric will use to calculate metric values at each slice_point.

• slice_point (dict or None) – Dictionary of slice_point metadata passed to each metric. E.g. the ra/dec of the healpix pixel.

Returns:

metricValue – The metric value at each slice_point.

Return type:

int float or object

class rubin_sim.maf.metrics.HistogramMetric(bins=None, bin_col='night', col='night', units='Count', statistic='count', metric_dtype=<class 'float'>, **kwargs)

Bases: VectorMetric

A wrapper to stats.binned_statistic

run(data_slice, slice_point=None)

Calculate metric values.

Parameters:

• data_slice (numpy.ndarray, (N,)) – Values passed to metric by the slicer, which the metric will use to calculate metric values at each slice_point.

• slice_point (dict or None) – Dictionary of slice_point metadata passed to each metric. E.g. the ra/dec of the healpix pixel.

Returns:

metricValue – The metric value at each slice_point.

Return type:

int float or object

class rubin_sim.maf.metrics.HourglassMetric(telescope='LSST', mjd_col='observationStartMJD', filter_col='filter', night_col='night', delta_t=60.0, **kwargs)

Bases: BaseMetric

Plot the filters used as a function of time. Must be used with the Hourglass Slicer. Will totally fail in the arctic circle.

run(data_slice, slice_point=None)

Calculate metric values.

Parameters:

• data_slice (numpy.ndarray, (N,)) – Values passed to metric by the slicer, which the metric will use to calculate metric values at each slice_point.

• slice_point (dict or None) – Dictionary of slice_point metadata passed to each metric. E.g. the ra/dec of the healpix pixel.

Returns:

metricValue – The metric value at each slice_point.

Return type:

int float or object

class rubin_sim.maf.metrics.IdentityMetric(col=None, metric_name=None, maps=None, units=None, metric_dtype=None, badval=-666, mask_val=None)

Bases: 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.

run(data_slice, slice_point=None)

Calculate metric values.

Parameters:

• data_slice (numpy.ndarray, (N,)) – Values passed to metric by the slicer, which the metric will use to calculate metric values at each slice_point.

• slice_point (dict or None) – Dictionary of slice_point metadata passed to each metric. E.g. the ra/dec of the healpix pixel.

Returns:

metricValue – The metric value at each slice_point.

Return type:

int float or object

class rubin_sim.maf.metrics.InstantaneousColorMetric(n_pairs=1, snr_limit=10, n_hours=0.5, b_one='g', b_two='r', **kwargs)

Bases: BaseMoMetric

Identify SSobjects which could have observations suitable to determine instanteous colors.

This is roughly defined as objects which have more than n_pairs pairs of observations with SNR greater than snr_limit, in bands bandOne and bandTwo, within n_hours.

Parameters:

• n_pairs (int, opt) – The number of pairs of observations (in each band) that must be within n_hours. Default 1.

• snr_limit (float, opt) – The SNR limit for the observations. Default 10.

• n_hours (float, opt) – The time interval between observations in the two bandpasses (hours). Default 0.5 hours.

• b_one (str, opt) – The first bandpass for the color. Default ‘g’.

• b_two (str, opt) – The second bandpass for the color. Default ‘r’.

Returns:

flag – 0 (no color possible under these constraints) or 1 (color possible).

Return type:

int

run(sso_obs, orb, hval)

Calculate the metric value.

Parameters:

• sso_obs (np.ndarray, (N,)) – The input data to the metric (same as the parent metric).

• orb (np.ndarray, (N,)) – The information about the orbit for which the metric is being calculated.

• hval (float) – The H value for which the metric is being calculated.

Returns:

metric_val

Return type:

float or np.ndarray or dict

class rubin_sim.maf.metrics.InterNightGapsMetric(mjd_col='observationStartMJD', night_col='night', reduce_func=<function median>, metric_name='Median Inter-Night Gap', **kwargs)

Bases: BaseMetric

Calculate the (reduce_func) of the gap between consecutive observations in different nights, in days.

Parameters:

reduce_func (function, optional) – Function that can operate on array-like structures. Typically numpy function. Default np.median.

run(data_slice, slice_point=None)

Calculate metric values.

Parameters:

• data_slice (numpy.ndarray, (N,)) – Values passed to metric by the slicer, which the metric will use to calculate metric values at each slice_point.

• slice_point (dict or None) – Dictionary of slice_point metadata passed to each metric. E.g. the ra/dec of the healpix pixel.

Returns:

metricValue – The metric value at each slice_point.

Return type:

int float or object

class rubin_sim.maf.metrics.IntraNightGapsMetric(mjd_col='observationStartMJD', night_col='night', reduce_func=<function median>, metric_name='Median Intra-Night Gap', **kwargs)

Bases: BaseMetric

Calculate the (reduce_func) of the gap between consecutive observations within a night, in hours.

Parameters:

reduce_func (function, optional) – Function that can operate on array-like structures. Typically numpy function. Default np.median.

run(data_slice, slice_point=None)

Calculate metric values.

Parameters:

• data_slice (numpy.ndarray, (N,)) – Values passed to metric by the slicer, which the metric will use to calculate metric values at each slice_point.

• slice_point (dict or None) – Dictionary of slice_point metadata passed to each metric. E.g. the ra/dec of the healpix pixel.

Returns:

metricValue – The metric value at each slice_point.

Return type:

int float or object

class rubin_sim.maf.metrics.KnownObjectsMetric(elong_thresh=100.0, v_mag_thresh1=20.0, eff1=0.1, t_switch1=53371, v_mag_thresh2=21.5, eff2=0.1, t_switch2=57023, v_mag_thresh3=22.0, eff3=0.1, t_switch3=59580, v_mag_thresh4=22.0, eff4=0.2, elong_col='Elongation', mjd_col='MJD(UTC)', **kwargs)

Bases: BaseMoMetric

Identify SSobjects which could be classified as ‘previously known’ based on their peak V magnitude. This is most appropriate for NEO surveys, where most of the sky has been covered so the exact location (beyond being in the visible sky) is not as important.

Default parameters tuned to match NEO survey capabilities. Returns the time at which each first reached that threshold V magnitude. The default values are calibrated using the NEOs larger than 140m discovered in the last 20 years and assuming a 30% completeness in 2017.

Note: the default parameters here were set up in ~2012, and are likely out of date (potentially adding another epoch of discovery).

Parameters:

• elong_thresh (float, opt) – The cutoff in solar elongation to consider an object ‘visible’. Default 100 deg.

• v_mag_thresh1 (float, opt) – The magnitude threshold for previously known objects. Default 20.0.

• eff1 (float, opt) – The likelihood of actually achieving each individual input observation. If the input observations include one observation per day, an ‘eff’ value of 0.3 would mean that (on average) only one third of these observations would be achieved. This is similar to the level for LSST, which can cover the visible sky every 3-4 days. Default 0.1

• t_switch1 (float, opt) – The (MJD) time to switch between v_mag_thresh1 + eff1 to v_mag_thresh2 + eff2, e.g. the end of the first period. Default 53371 (2005).

• v_mag_thresh2 (float, opt) – The magnitude threshhold for previously known objects. Default 22.0. This is based on assuming PS and other surveys will be efficient down to V=22.

• eff2 (float, opt) – The efficiency of observations during the second period of time. Default 0.1

• t_switch2 (float, opt) – The (MJD) time to switch between v_mag_thresh2 + eff2 to v_mag_thresh3 + eff3. Default 57023 (2015).

• v_mag_thresh3 (float, opt) – The magnitude threshold during the third period. Default 22.0, based on PS1 + Catalina.

• eff3 (float, opt) – The efficiency of observations during the third period. Default 0.1

• t_switch3 (float, opt) – The (MJD) time to switch between v_mag_thresh3 + eff3 to v_mag_thresh4 + eff4. Default 59580 (2022).

• v_mag_thresh4 (float, opt) – The magnitude threshhold during the fourth (last) period. Default 22.0, based on PS1 + Catalina.

• eff4 (float, opt) – The efficiency of observations during the fourth (last) period. Default 0.2

run(sso_obs, orb, hval)

Calculate the metric value.

Parameters:

• sso_obs (np.ndarray, (N,)) – The input data to the metric (same as the parent metric).

• orb (np.ndarray, (N,)) – The information about the orbit for which the metric is being calculated.

• hval (float) – The H value for which the metric is being calculated.

Returns:

metric_val

Return type:

float or np.ndarray or dict

class rubin_sim.maf.metrics.KuiperMetric(col=None, metric_name=None, maps=None, units=None, metric_dtype=None, badval=-666, mask_val=None)

Bases: BaseMetric

Find the Kuiper V statistic for a distribution, useful for angles.

Value of 0 means perfecty uniform, 1 means delta function

class rubin_sim.maf.metrics.LightcurveColorOuterMetric(snr_limit=None, num_req=30, num_sec_filt=20, filterlist=('u', 'g', 'r', 'i', 'z', 'y'), **kwargs)

Bases: BaseMoMetric

Calculate the liklihood of being able to calculate a color and lightcurve for outer solar system objects.

Parameters:

• snr_limit (float or None, opt) – If snr_limit is set as a float, then requires object to be above snr_limit SNR in the image. If snr_limit is None, this uses the probabilistic ‘visibility’ calculated by the vis stacker, which means SNR ~ 5. Default is None.

• num_req (int, opt) – Number of observations required for a lightcurve fitting. Default 30.

• num_sec_filt (int, opt) – Number of observations required in a secondary band for color only. Default 20.

• filterlist (list [str], opt) – Filters that the primary/secondary measurements can be in.

Returns:

flag – A flag that indicates whether a color/lightcurve was generated in: 0 = no lightcurve (although may have had ‘color’ in one or more band) 1 = a lightcurve in a single filter (but no additional color information) 2+ = lightcurves in more than one filter (or lightcurve + color) e.g. lightcurve in 2 bands, with additional color information in another = 3.

Return type:

int

Notes

This metric is appropriate for outer solar system objects, such as TNOs and SDOs.

This metric evaluates whether the number of observations is sufficient to fit a lightcurve in a primary and secondary bandpass. The primary bandpass requires more observations than the secondary. Essentially, it’s a complete lightcurve in one or both bandpasses, with at least a semi-complete lightcurve in the secondary band.

The lightcurve/color can be calculated with any two of the bandpasses in filterlist.

Contributed by Wes Fraser.

run(sso_obs, orb, hval)

Calculate the metric value.

Parameters:

• sso_obs (np.ndarray, (N,)) – The input data to the metric (same as the parent metric).

• orb (np.ndarray, (N,)) – The information about the orbit for which the metric is being calculated.

• hval (float) – The H value for which the metric is being calculated.

Returns:

metric_val

Return type:

float or np.ndarray or dict

class rubin_sim.maf.metrics.LightcurveInversionAsteroidMetric(weight_det=50, snr_limit=None, snr_max=100, filterlist=('u', 'g', 'r', 'i', 'z', 'y'), **kwargs)

Bases: BaseMoMetric

Evaluate the liklihood that the detections could be used to enable lightcurve inversion. This metric is generally applicable only to inner solar system objects (NEOs, MBAs).

Parameters:

• weight_det (float, opt) – The SNR-weighted number of detections required (per bandpass in any ONE of the filters in filterlist). Default 50.

• snr_limit (float or None, opt) – If snr_limit is set as a float, then requires object to be above snr_limit SNR in the image. If snr_limit is None, this uses the probabilistic ‘visibility’ calculated by the vis stacker, which means SNR ~ 5. Default is None.

• snr_max (float, opt) – Maximum value toward the SNR-weighting to consider. Default 100.

• filterlist (list [str], opt) – The filters which the lightcurve inversion could be based on. Requirements must be met in one of these filters.

Returns:

metric_value – 0 (could not perform lightcurve inversion) or 1 (could)

Return type:

int

Notes

This metric determines if the cumulative sum of observations of a target are enough to enable lightcurve inversion for shape modeling. For this to be true, multiple conditions need to be satisfied:

1) The SNR-weighted number of observations (each observation is weighted by its SNR, up to a max of 100) must be larger than the threshold weight_det (default 50) 2) Ecliptic longitudinal coverage needs to be at least 90 degrees, and the absolute deviation needs to be at least 1/8th the longitudinal coverage. 3) The phase angle coverage needs to span at least 5 degrees.

For evaluation of condition 2, the median ecliptic longitude is subtracted from all longitudes, and the modulo 360 of those values is taken. This ensures that the wrap around 360 is handled correctly.

For more information on the above conditions, please see https://docs.google.com/document/d/1GAriM7trpTS08uanjUF7PyKALB2JBTjVT7Y6R30i0-8/edit?usp=sharing

Contributed by Steve Chesley, Wes Fraser, Josef Durech, and the inner solar system working group.

run(sso_obs, orb, hval)

Calculate the metric value.

Parameters:

• sso_obs (np.ndarray, (N,)) – The input data to the metric (same as the parent metric).

• orb (np.ndarray, (N,)) – The information about the orbit for which the metric is being calculated.

• hval (float) – The H value for which the metric is being calculated.

Returns:

metric_val

Return type:

float or np.ndarray or dict

class rubin_sim.maf.metrics.MagicDiscoveryMetric(n_obs=6, t_window=60, snr_limit=None, **kwargs)

Bases: BaseMoMetric

Count the number of nights with discovery opportunities with very good software for an SSobject.

Parameters:

• n_obs (int, opt) – Total number of observations required for discovery.

• t_window (float, opt) – The timespan of the discovery window (days).

• snr_limit (float or None) – If None, uses the probabilistic detection likelihood. If float, uses the SNR value as a flat cutoff value.

run(sso_obs, orb, hval)

Calculate the metric value.

Parameters:

• sso_obs (np.ndarray, (N,)) – The input data to the metric (same as the parent metric).

• orb (np.ndarray, (N,)) – The information about the orbit for which the metric is being calculated.

• hval (float) – The H value for which the metric is being calculated.

Returns:

metric_val

Return type:

float or np.ndarray or dict

class rubin_sim.maf.metrics.MaxGapMetric(mjd_col='observationStartMJD', **kwargs)

Bases: BaseMetric

Find the maximum gap (in days) in between successive observations.

Useful for making sure there is an image within the last year that would make a good template image.

Parameters:

mjd_col (str, opt) – The column name of the night of each observation.

Returns:

maxGap – The maximum gap (in days) between visits.

Return type:

float

run(data_slice, slice_point=None)

Calculate metric values.

Parameters:

• data_slice (numpy.ndarray, (N,)) – Values passed to metric by the slicer, which the metric will use to calculate metric values at each slice_point.

• slice_point (dict or None) – Dictionary of slice_point metadata passed to each metric. E.g. the ra/dec of the healpix pixel.

Returns:

metricValue – The metric value at each slice_point.

Return type:

int float or object

class rubin_sim.maf.metrics.MaxMetric(col=None, metric_name=None, maps=None, units=None, metric_dtype=None, badval=-666, mask_val=None)

Bases: BaseMetric

Calculate the maximum of a simData column slice.

run(data_slice, slice_point=None)

Calculate metric values.

Parameters:

• data_slice (numpy.ndarray, (N,)) – Values passed to metric by the slicer, which the metric will use to calculate metric values at each slice_point.

• slice_point (dict or None) – Dictionary of slice_point metadata passed to each metric. E.g. the ra/dec of the healpix pixel.

Returns:

metricValue – The metric value at each slice_point.

Return type:

int float or object

class rubin_sim.maf.metrics.MaxPercentMetric(col=None, metric_name=None, maps=None, units=None, metric_dtype=None, badval=-666, mask_val=None)

Bases: BaseMetric

Return the percent of data which matches the maximum value of the data.

run(data_slice, slice_point=None)

Calculate metric values.

Parameters:

• data_slice (numpy.ndarray, (N,)) – Values passed to metric by the slicer, which the metric will use to calculate metric values at each slice_point.

• slice_point (dict or None) – Dictionary of slice_point metadata passed to each metric. E.g. the ra/dec of the healpix pixel.

Returns:

metricValue – The metric value at each slice_point.

Return type:

int float or object

class rubin_sim.maf.metrics.MaxStateChangesWithinMetric(change_col='filter', time_col='observationStartMJD', metric_name=None, timespan=20, **kwargs)

Bases: BaseMetric

Compute the maximum number of changes of state that occur within a given timespan. (useful for calculating time between filter changes in particular).

Parameters:

• change_col (str) – Column that we are tracking changes in.

• time_col (str) – Column with the time of each visit

• timespan (float) – The timespan to count the number of changes within (in minutes).

run(data_slice, slice_point=None)

Calculate metric values.

Parameters:

• data_slice (numpy.ndarray, (N,)) – Values passed to metric by the slicer, which the metric will use to calculate metric values at each slice_point.

• slice_point (dict or None) – Dictionary of slice_point metadata passed to each metric. E.g. the ra/dec of the healpix pixel.

Returns:

metricValue – The metric value at each slice_point.

Return type:

int float or object

class rubin_sim.maf.metrics.MeanAngleMetric(col=None, metric_name=None, maps=None, units=None, metric_dtype=None, badval=-666, mask_val=None)

Bases: BaseMetric

Calculate the mean of an angular (degree) column slice.

‘MeanAngle’ differs from ‘Mean’ in that it accounts for wraparound at 2pi.

run(data_slice, slice_point=None)

Calculate mean angle via unit vectors. If unit vector ‘strength’ is less than 0.1, then just set mean to 180 degrees (as this indicates nearly uniformly distributed angles).

class rubin_sim.maf.metrics.MeanCampaignFrequencyMetric(mjd_col='observationStartMJD', exp_time_col='visitExposureTime', min_exp_time=20, night_col='night', **kwargs)

Bases: BaseMetric

Calculate the mean separation between nights, within a season - then the mean over the campaign.

Calculate per season, to avoid any influence from season gaps.

run(data_slice, slice_point)

Calculate metric values.

Parameters:

• data_slice (numpy.ndarray, (N,)) – Values passed to metric by the slicer, which the metric will use to calculate metric values at each slice_point.

• slice_point (dict or None) – Dictionary of slice_point metadata passed to each metric. E.g. the ra/dec of the healpix pixel.

Returns:

metricValue – The metric value at each slice_point.

Return type:

int float or object

class rubin_sim.maf.metrics.MeanMetric(col=None, metric_name=None, maps=None, units=None, metric_dtype=None, badval=-666, mask_val=None)

Bases: BaseMetric

Calculate the mean of a simData column slice.

run(data_slice, slice_point=None)

Calculate metric values.

Parameters:

• data_slice (numpy.ndarray, (N,)) – Values passed to metric by the slicer, which the metric will use to calculate metric values at each slice_point.

• slice_point (dict or None) – Dictionary of slice_point metadata passed to each metric. E.g. the ra/dec of the healpix pixel.

Returns:

metricValue – The metric value at each slice_point.

Return type:

int float or object

class rubin_sim.maf.metrics.MeanValueAtHMetric(h_mark=22, reduce_func=<function mean>, metric_name=None, **kwargs)

Bases: BaseMoMetric

Return the mean value of a metric at a given H.

Allows the metric values to be multi-dimensional (i.e. use a cloned H distribution).

Parameters:

h_mark (float, optional) – The H value at which to look up the metric value.

Returns:

value

Return type:

: float

run(metric_vals, h_vals)

Calculate the metric value.

Parameters:

• sso_obs (np.ndarray, (N,)) – The input data to the metric (same as the parent metric).

• orb (np.ndarray, (N,)) – The information about the orbit for which the metric is being calculated.

• hval (float) – The H value for which the metric is being calculated.

Returns:

metric_val

Return type:

float or np.ndarray or dict

class rubin_sim.maf.metrics.MedianMetric(col=None, metric_name=None, maps=None, units=None, metric_dtype=None, badval=-666, mask_val=None)

Bases: BaseMetric

Calculate the median of a simData column slice.

run(data_slice, slice_point=None)

Calculate metric values.

Parameters:

• data_slice (numpy.ndarray, (N,)) – Values passed to metric by the slicer, which the metric will use to calculate metric values at each slice_point.

• slice_point (dict or None) – Dictionary of slice_point metadata passed to each metric. E.g. the ra/dec of the healpix pixel.

Returns:

metricValue – The metric value at each slice_point.

Return type:

int float or object

class rubin_sim.maf.metrics.MetricRegistry(name, bases, dict)

Bases: type

Meta class for metrics, to build a registry of metric classes.

class rubin_sim.maf.metrics.MinMetric(col=None, metric_name=None, maps=None, units=None, metric_dtype=None, badval=-666, mask_val=None)

Bases: BaseMetric

Calculate the minimum of a simData column slice.

run(data_slice, slice_point=None)

Calculate metric values.

Parameters:

• data_slice (numpy.ndarray, (N,)) – Values passed to metric by the slicer, which the metric will use to calculate metric values at each slice_point.

• slice_point (dict or None) – Dictionary of slice_point metadata passed to each metric. E.g. the ra/dec of the healpix pixel.

Returns:

metricValue – The metric value at each slice_point.

Return type:

int float or object

class rubin_sim.maf.metrics.MinTimeBetweenStatesMetric(change_col='filter', time_col='observationStartMJD', metric_name=None, **kwargs)

Bases: BaseMetric

Compute the minimum time between changes of state in a column value. (useful for calculating fastest time between filter changes in particular). Returns delta time in minutes!

Parameters:

• change_col (str) – Column that we are tracking changes in.

• time_col (str) – Column with the time of each visit

run(data_slice, slice_point=None)

Calculate metric values.

Parameters:

• data_slice (numpy.ndarray, (N,)) – Values passed to metric by the slicer, which the metric will use to calculate metric values at each slice_point.

• slice_point (dict or None) – Dictionary of slice_point metadata passed to each metric. E.g. the ra/dec of the healpix pixel.

Returns:

metricValue – The metric value at each slice_point.

Return type:

int float or object

class rubin_sim.maf.metrics.MoCompletenessAtTimeMetric(times, hval=None, cumulative=None, hindex=0.33, **kwargs)

Bases: BaseMoMetric

Calculate the completeness (relative to the entire population) <= a given H as a function of time, given the times of each discovery.

Input values of the discovery times can come from the Discovery_Time (child) metric or the KnownObjects metric.

Parameters:

• times (np.ndarray, (N,) or list [float]) – The bins to distribute the discovery times into. Same units as the discovery time (typically MJD).

• hval (float, optional) – The value of H to count completeness at, or cumulative completeness to. Default None, in which case a value halfway through h_vals (the slicer H range) will be chosen.

• cumulative (bool, optional) – If True, calculate the cumulative completeness (completeness <= H). If False, calculate the differential completeness (completeness @ H). Default None which becomes ‘True’, unless metric_name starts with ‘differential’.

• hindex (float, optional) – Use hindex as the power law to integrate over H, if cumulative is True.

run(discovery_times, h_vals)

Calculate the metric value.

Parameters:

• sso_obs (np.ndarray, (N,)) – The input data to the metric (same as the parent metric).

• orb (np.ndarray, (N,)) – The information about the orbit for which the metric is being calculated.

• hval (float) – The H value for which the metric is being calculated.

Returns:

metric_val

Return type:

float or np.ndarray or dict

class rubin_sim.maf.metrics.MoCompletenessMetric(threshold=1, nbins=20, min_hrange=1.0, cumulative=None, hindex=0.33, **kwargs)

Bases: BaseMoMetric

Calculate the fraction of the population that meets threshold value or higher. This is equivalent to calculating the completeness (relative to the entire population) given the output of a Discovery_N_Chances metric, or the fraction of the population that meets a given cutoff value for Color determination metrics.

Any moving object metric that outputs a float value can thus have the ‘fraction of the population’ with greater than X value calculated here, as a summary statistic.

Parameters:

• threshold (int, optional) – Count the fraction of the population that exceeds this value.

• nbins (int, optional) – If the H values for the metric are not a cloned distribution, then split up H into this many bins.

• min_hrange (float, optional) – If the H values for the metric are not a cloned distribution, then split up H into at least this range (otherwise just use the min/max of the H values).

• cumulative (bool, optional) – If False, simply report the differential fractional value (or differential completeness). If True, integrate over the H distribution (using IntegrateOverH) to report a cumulative fraction. Default of None will use True, unless metric_name is set and starts with “Differential” - then default will use False.

• hindex (float, optional) – Use hindex as the power law to integrate over H, if cumulative is True.

run(metric_values, h_vals)

Calculate the metric value.

Parameters:

• sso_obs (np.ndarray, (N,)) – The input data to the metric (same as the parent metric).

• orb (np.ndarray, (N,)) – The information about the orbit for which the metric is being calculated.

• hval (float) – The H value for which the metric is being calculated.

Returns:

metric_val

Return type:

float or np.ndarray or dict

class rubin_sim.maf.metrics.NChangesMetric(col='filter', order_by='observationStartMJD', **kwargs)

Bases: BaseMetric

Compute the number of times a column value changes. (useful for filter changes in particular).

run(data_slice, slice_point=None)

Calculate metric values.

Parameters:

• data_slice (numpy.ndarray, (N,)) – Values passed to metric by the slicer, which the metric will use to calculate metric values at each slice_point.

• slice_point (dict or None) – Dictionary of slice_point metadata passed to each metric. E.g. the ra/dec of the healpix pixel.

Returns:

metricValue – The metric value at each slice_point.

Return type:

int float or object

class rubin_sim.maf.metrics.NNightsMetric(snr_limit=None, **kwargs)

Bases: BaseMoMetric

Count the number of distinct nights an SSobject is observed.

Parameters:

snr_limit (float or None) – If the snr_limit is None, detection of the object in a visit is determined using the _calcVis method (completeness calculation). If not None, the snr is calculated and used as a flat cutoff instead.

run(sso_obs, orb, hval)

Calculate the metric value.

Parameters:

• sso_obs (np.ndarray, (N,)) – The input data to the metric (same as the parent metric).

• orb (np.ndarray, (N,)) – The information about the orbit for which the metric is being calculated.

• hval (float) – The H value for which the metric is being calculated.

Returns:

metric_val

Return type:

float or np.ndarray or dict

class rubin_sim.maf.metrics.NObsMetric(snr_limit=None, **kwargs)

Bases: BaseMoMetric

Count the total number of observations where an SSobject was ‘visible’.

Parameters:

snr_limit (float or None) – If the snr_limit is None, detection of the object in a visit is determined using the _calcVis method (completeness calculation). If not None, the snr is calculated and used as a flat cutoff instead.

run(sso_obs, orb, hval)

Calculate the metric value.

Parameters:

• sso_obs (np.ndarray, (N,)) – The input data to the metric (same as the parent metric).

• orb (np.ndarray, (N,)) – The information about the orbit for which the metric is being calculated.

• hval (float) – The H value for which the metric is being calculated.

Returns:

metric_val

Return type:

float or np.ndarray or dict

class rubin_sim.maf.metrics.NObsNoSinglesMetric(snr_limit=None, **kwargs)

Bases: BaseMoMetric

Count the number of observations for an SSobject, without singles. Don’t include observations where it was a single observation on a night.

Parameters:

snr_limit (float or None) – If the snr_limit is None, detection of the object in a visit is determined using the _calcVis method (completeness calculation). If not None, the snr is calculated and used as a flat cutoff instead.

run(sso_obs, orb, hval)

Calculate the metric value.

Parameters:

• sso_obs (np.ndarray, (N,)) – The input data to the metric (same as the parent metric).

• orb (np.ndarray, (N,)) – The information about the orbit for which the metric is being calculated.

• hval (float) – The H value for which the metric is being calculated.

Returns:

metric_val

Return type:

float or np.ndarray or dict

class rubin_sim.maf.metrics.NRevisitsMetric(mjd_col='observationStartMJD', d_t=30.0, normed=False, metric_name=None, **kwargs)

Bases: BaseMetric

Calculate the number of consecutive visits with time differences less than d_t.

Parameters:

• d_t (float, optional) – The time interval to consider (in minutes). Default 30.

• normed (bool, optional) – Flag to indicate whether to return the total number of consecutive visits with time differences less than d_t (False), or the fraction of overall visits (True). Note that we would expect (if all visits occur in pairs within d_t) this fraction would be 0.5!

run(data_slice, slice_point=None)

Calculate metric values.

Parameters:

• data_slice (numpy.ndarray, (N,)) – Values passed to metric by the slicer, which the metric will use to calculate metric values at each slice_point.

• slice_point (dict or None) – Dictionary of slice_point metadata passed to each metric. E.g. the ra/dec of the healpix pixel.

Returns:

metricValue – The metric value at each slice_point.

Return type:

int float or object

class rubin_sim.maf.metrics.NStateChangesFasterThanMetric(change_col='filter', time_col='observationStartMJD', metric_name=None, cutoff=20, **kwargs)

Bases: BaseMetric

Compute the number of changes of state that happen faster than ‘cutoff’. (useful for calculating time between filter changes in particular).

Parameters:

• change_col (str) – Column that we are tracking changes in.

• time_col (str) – Column with the time of each visit

• cutoff (float) – The cutoff value for the time between changes (in minutes).

run(data_slice, slice_point=None)

Calculate metric values.

Parameters:

• data_slice (numpy.ndarray, (N,)) – Values passed to metric by the slicer, which the metric will use to calculate metric values at each slice_point.

• slice_point (dict or None) – Dictionary of slice_point metadata passed to each metric. E.g. the ra/dec of the healpix pixel.

Returns:

metricValue – The metric value at each slice_point.

Return type:

int float or object

class rubin_sim.maf.metrics.NVisitsPerNightMetric(night_col='night', bins=array([0, 1, 2, 3, 4, 5, 6, 7, 8, 9]), units='#', **kwargs)

Bases: BaseMetric

Histogram the number of visits in each night.

Splits the visits by night, then histograms how many visits occur in each night.

Parameters:

• night_col (str, optional) – The column name for the night of each observation. Default ‘night’.

• bins (np.ndarray, optional) – The bins to use for the histogram of time gaps (in days, or same units as timesCol). Default values are bins from 0 to 5 visits, in steps of 1.

Returns:

histogram – Returns a histogram of the number of visits per night at each slice point; these histograms can be combined and plotted using the ‘SummaryHistogram plotter’.

Return type:

np.ndarray

run(data_slice, slice_point=None)

Calculate metric values.

Parameters:

• data_slice (numpy.ndarray, (N,)) – Values passed to metric by the slicer, which the metric will use to calculate metric values at each slice_point.

• slice_point (dict or None) – Dictionary of slice_point metadata passed to each metric. E.g. the ra/dec of the healpix pixel.

Returns:

metricValue – The metric value at each slice_point.

Return type:

int float or object

class rubin_sim.maf.metrics.NgalScaleMetric(seeing_col='seeingFwhmEff', m5_col='fiveSigmaDepth', metric_name='NgalScale', filtername='i', a_max=0.2, m5min=26.0, filter_col='filter', **kwargs)

Bases: BaseMetric

Approximate number of galaxies, scaled by median seeing.

Parameters:

• a_max (float) – The maximum dust extinction to allow. Anything with higher dust extinction is considered to have zero usable galaxies.

• m5min (float) – The minimum coadded 5-sigma depth to allow. Anything less is considered to have zero usable galaxies.

• filter (str) – The filter to use. Any visits in other filters are ignored.

run(data_slice, slice_point)

Calculate metric values.

Parameters:

• data_slice (numpy.ndarray, (N,)) – Values passed to metric by the slicer, which the metric will use to calculate metric values at each slice_point.

• slice_point (dict or None) – Dictionary of slice_point metadata passed to each metric. E.g. the ra/dec of the healpix pixel.

Returns:

metricValue – The metric value at each slice_point.

Return type:

int float or object

class rubin_sim.maf.metrics.NightPointingMetric(alt_col='altitude', az_col='azimuth', filter_col='filter', mjd_col='observationStartMJD', metric_name='NightPointing', telescope='LSST', **kwargs)

Bases: BaseMetric

Gather relevant information for a night to plot.

run(data_slice, slice_point=None)

Calculate metric values.

Parameters:

• data_slice (numpy.ndarray, (N,)) – Values passed to metric by the slicer, which the metric will use to calculate metric values at each slice_point.

• slice_point (dict or None) – Dictionary of slice_point metadata passed to each metric. E.g. the ra/dec of the healpix pixel.

Returns:

metricValue – The metric value at each slice_point.

Return type:

int float or object

class rubin_sim.maf.metrics.NightTimespanMetric(percentile=75, night_col='night', mjd_col='observationStartMJD', **kwargs)

Bases: BaseMetric

Calculate the maximum time span covered in each night, report the percentile value of all timespans.

Parameters:

• percentile (float, opt) – Percentile value to report. Default 75th percentile.

• night_col (str, opt) – Name of the night column. Default ‘night’.

• mjd_col (str, opt) – Name of the MJD visit column. Default ‘observationStartMJD’.

run(data_slice, slice_point=None)

Calculate metric values.

Parameters:

• data_slice (numpy.ndarray, (N,)) – Values passed to metric by the slicer, which the metric will use to calculate metric values at each slice_point.

• slice_point (dict or None) – Dictionary of slice_point metadata passed to each metric. E.g. the ra/dec of the healpix pixel.

Returns:

metricValue – The metric value at each slice_point.

Return type:

int float or object

class rubin_sim.maf.metrics.NightgapsMetric(night_col='night', all_gaps=False, bins=array([0, 1, 2, 3, 4, 5, 6, 7, 8, 9]), units='nights', **kwargs)

Bases: BaseMetric

Histogram the number of nights between observations.

Measure the gaps between observations. By default, only gaps between neighboring visits are computed. If all_gaps is set to true, all gaps are computed (i.e., if there are observations at 10, 20, 30 and 40 the default will histogram [10,10,10] while all_gaps histograms [10,10,10,20,20,30])

Parameters:

• night_col (str, optional) – The column name for the night of each observation. Default ‘night’.

• all_gaps (bool, optional) – Histogram the gaps between all observations (True) or just successive observations (False)? Default is False. If all gaps are used, this metric can become significantly slower.

• bins (np.ndarray, optional) – The bins to use for the histogram of time gaps (in days, or same units as timesCol). Default values are bins from 0 to 10 days, in 1 day intervals.

Returns:

histogram – Returns a histogram of the deltaT between nights at each slice point; these histograms can be combined and plotted using the ‘SummaryHistogram plotter’.

Return type:

np.ndarray

run(data_slice, slice_point=None)

Calculate metric values.

Parameters:

• data_slice (numpy.ndarray, (N,)) – Values passed to metric by the slicer, which the metric will use to calculate metric values at each slice_point.

• slice_point (dict or None) – Dictionary of slice_point metadata passed to each metric. E.g. the ra/dec of the healpix pixel.

Returns:

metricValue – The metric value at each slice_point.

Return type:

int float or object

class rubin_sim.maf.metrics.NlcPointsMetric(ndpmin=10, mags=21.0, m5_col='fiveSigmaDepth', filter_col='filter', metric_name='NlcPoints', maps=None, nside=128, **kwargs)

Bases: BaseMetric

Number of points in stellar light curves

Parameters:

• ndpmin (int) – The number of points to demand on a lightcurve in a single filter to have that light curve qualify.

• mags (float) – The magnitude of our fiducial object (maybe make it a dict in the future to support arbitrary colors).

• maps (list [map] or None) – List of stellar density maps to use. Default of None loads Trilegal maps.

• nside (int) – The nside is needed to make sure the loaded maps match the slicer nside.

run(data_slice, slice_point)

Calculate metric values.

Parameters:

• data_slice (numpy.ndarray, (N,)) – Values passed to metric by the slicer, which the metric will use to calculate metric values at each slice_point.

• slice_point (dict or None) – Dictionary of slice_point metadata passed to each metric. E.g. the ra/dec of the healpix pixel.

Returns:

metricValue – The metric value at each slice_point.

Return type:

int float or object

class rubin_sim.maf.metrics.NormalizeMetric(col='metricdata', norm_val=1, **kwargs)

Bases: BaseMetric

Return a metric values divided by ‘norm_val’. Useful for turning summary statistics into fractions.

run(data_slice, slice_point=None)

Calculate metric values.

Parameters:

• data_slice (numpy.ndarray, (N,)) – Values passed to metric by the slicer, which the metric will use to calculate metric values at each slice_point.

• slice_point (dict or None) – Dictionary of slice_point metadata passed to each metric. E.g. the ra/dec of the healpix pixel.

Returns:

metricValue – The metric value at each slice_point.

Return type:

int float or object

class rubin_sim.maf.metrics.NoutliersNsigmaMetric(col=None, n_sigma=3.0, metric_name=None, **kwargs)

Bases: BaseMetric

Calculate the # of visits less than n_sigma below the mean (n_sigma<0) or more than n_sigma above the mean.

run(data_slice, slice_point=None)

Calculate metric values.

Parameters:

• data_slice (numpy.ndarray, (N,)) – Values passed to metric by the slicer, which the metric will use to calculate metric values at each slice_point.

• slice_point (dict or None) – Dictionary of slice_point metadata passed to each metric. E.g. the ra/dec of the healpix pixel.

Returns:

metricValue – The metric value at each slice_point.

Return type:

int float or object

class rubin_sim.maf.metrics.NstarsMetric(crowding_error=0.1, filtername='r', seeing_col='seeingFwhmGeom', m5_col='fiveSigmaDepth', metric_name=None, maps=['StellarDensityMap'], ignore_crowding=False, **kwargs)

Bases: 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 – The number of stars above the error limit.

Return type:

float

run(data_slice, slice_point=None)

Calculate metric values.

Parameters:

• data_slice (numpy.ndarray, (N,)) – Values passed to metric by the slicer, which the metric will use to calculate metric values at each slice_point.

• slice_point (dict or None) – Dictionary of slice_point metadata passed to each metric. E.g. the ra/dec of the healpix pixel.

Returns:

metricValue – The metric value at each slice_point.

Return type:

int float or object

class rubin_sim.maf.metrics.ObsArcMetric(snr_limit=None, **kwargs)

Bases: BaseMoMetric

Calculate the difference in time between the first and last observation of an SSobject.

Parameters:

snr_limit (float or None) – If the snr_limit is None, detection of the object in a visit is determined using the _calcVis method (completeness calculation). If not None, the snr is calculated and used as a flat cutoff instead.

run(sso_obs, orb, hval)

Calculate the metric value.

Parameters:

• sso_obs (np.ndarray, (N,)) – The input data to the metric (same as the parent metric).

• orb (np.ndarray, (N,)) – The information about the orbit for which the metric is being calculated.

• hval (float) – The H value for which the metric is being calculated.

Returns:

metric_val

Return type:

float or np.ndarray or dict

class rubin_sim.maf.metrics.OpenShutterFractionMetric(metric_name='OpenShutterFraction', slew_time_col='slewTime', exp_time_col='visitExposureTime', visit_time_col='visitTime', **kwargs)

Bases: BaseMetric

Compute the fraction of time the shutter is open compared to the total time spent observing.

run(data_slice, slice_point=None)

Calculate metric values.

Parameters:

• data_slice (numpy.ndarray, (N,)) – Values passed to metric by the slicer, which the metric will use to calculate metric values at each slice_point.

• slice_point (dict or None) – Dictionary of slice_point metadata passed to each metric. E.g. the ra/dec of the healpix pixel.

Returns:

metricValue – The metric value at each slice_point.

Return type:

int float or object

class rubin_sim.maf.metrics.OptimalM5Metric(m5_col='fiveSigmaDepth', opt_m5_col='m5Optimal', filter_col='filter', mag_diff=False, normalize=False, **kwargs)

Bases: BaseMetric

Compare the co-added depth of the survey to one where all the observations were taken on the meridian.

Parameters:

• m5_col (str ('fiveSigmaDepth')) – Column name that contains the five-sigma limiting depth of each observation

• opt_m5_col (str ('m5Optimal')) – The column name of the five-sigma-limiting depth if the observation had been taken on the meridian.

• normalize (bool (False)) – If False, metric returns how many more observations would need to be taken to reach the optimal depth. If True, the number is normalized by the total number of observations already taken at that position.

• mag_diff (bool (False)) – If True, metric returns the magnitude difference between the achieved coadded depth and the optimal coadded depth.

Returns:

• numpy.array

• If mag_diff is True, returns the magnitude difference between the

• optimal and actual coadded depth. If normalize is False

• (default), the result is the number of additional observations

• (taken at the median depth) the survey needs to catch up to

• optimal. If normalize is True, the result is divided by the

• number of observations already taken. So if a 10-year survey

• returns 20%, it would need to run for 12 years to reach the same

• depth as a 10-year meridian survey.

run(data_slice, slice_point=None)

Calculate metric values.

Parameters:

• data_slice (numpy.ndarray, (N,)) – Values passed to metric by the slicer, which the metric will use to calculate metric values at each slice_point.

• slice_point (dict or None) – Dictionary of slice_point metadata passed to each metric. E.g. the ra/dec of the healpix pixel.

Returns:

metricValue – The metric value at each slice_point.

Return type:

int float or object

class rubin_sim.maf.metrics.PairFractionMetric(mjd_col='observationStartMJD', metric_name='PairFraction', min_gap=15.0, max_gap=90.0, **kwargs)

Bases: BaseMetric

What fraction of observations are part of a pair.

Note, an observation can be a member of more than one “pair”. For example, t=[0, 5, 30], all observations would be considered part of a pair because they all have an observation within the given window to pair with (the observation at t=30 pairs twice).

Parameters:

• min_gap (float, optional) – Minimum time to consider something part of a pair (minutes). Default 15.

• max_gap (float, optional) – Maximum time to consider something part of a pair (minutes). Default 90.

run(data_slice, slice_point=None)

Calculate metric values.

Parameters:

• data_slice (numpy.ndarray, (N,)) – Values passed to metric by the slicer, which the metric will use to calculate metric values at each slice_point.

• slice_point (dict or None) – Dictionary of slice_point metadata passed to each metric. E.g. the ra/dec of the healpix pixel.

Returns:

metricValue – The metric value at each slice_point.

Return type:

int float or object

class rubin_sim.maf.metrics.PairMetric(mjd_col='observationStartMJD', metric_name='Pairs', match_min=20.0, match_max=40.0, bin_size=5.0, **kwargs)

Bases: BaseMetric

Count the number of pairs of visits that could be used for Solar System object detection.

Parameters:

• mjd_col (str, opt) – Name of the MJD column in the observations.

• metric_name (str, opt) – Name for the resulting metric. If None, one is constructed from the class name.

• match_min (float, opt) – Minutes after first observation to count something as a match.

• match_max (float, opt) – Minutes after first observation to count something as a match.

• bin_size (float, opt) – bin_size to use (minutes). Note that bin_size should be considerably smaller than the difference between match_min and match_max.

• Result

• ------

• num_pairs (float) – The number of pairs of visits within the min and max time range.

run(data_slice, slice_point=None)

Calculate metric values.

Parameters:

• data_slice (numpy.ndarray, (N,)) – Values passed to metric by the slicer, which the metric will use to calculate metric values at each slice_point.

• slice_point (dict or None) – Dictionary of slice_point metadata passed to each metric. E.g. the ra/dec of the healpix pixel.

Returns:

metricValue – The metric value at each slice_point.

Return type:

int float or object

class rubin_sim.maf.metrics.ParallaxCoverageMetric(metric_name='ParallaxCoverageMetric', m5_col='fiveSigmaDepth', mjd_col='observationStartMJD', filter_col='filter', seeing_col='seeingFwhmGeom', rmag=20.0, sed_template='flat', atm_err=0.01, theta_range=0.0, snr_limit=5, **kwargs)

Bases: BaseMetric

Check how well the parallax factor is distributed.

Subtracts the weighted mean position of the parallax offsets, then computes the weighted mean radius of the points. If points are well distributed, the mean radius will be near 1. If phase coverage is bad, radius will be close to zero.

For points on the Ecliptic, uniform sampling should result in a metric value of ~0.5. At the poles, uniform sampling would result in a metric value of ~1. Conceptually, it is helpful to remember that the parallax motion of a star at the pole is a (nearly circular) ellipse while the motion of a star on the ecliptic is a straight line. Thus, any pair of observations separated by 6 months will give the full parallax range for a star on the pole but only observations on very specific dates will give the full range for a star on the ecliptic.

Optionally also demand that there are observations above the snr_limit kwarg spanning theta_range radians.

Parameters:

• m5_col (str, optional) – Column name for individual visit m5. Default fiveSigmaDepth.

• mjd_col (str, optional) – Column name for exposure time dates. Default observationStartMJD.

• filter_col (str, optional) – Column name for filter. Default filter.

• seeing_col (str, optional) – Column name for seeing (assumed FWHM). Default seeingFwhmGeom.

• rmag (float, optional) – Magnitude of fiducial star in r filter. Other filters are scaled using sedTemplate keyword. Default 20.0

• sedTemplate (str, optional) – Template to use (can be ‘flat’ or ‘O’,’B’,’A’,’F’,’G’,’K’,’M’). Default ‘flat’.

• atm_err (float, optional) – Centroiding error due to atmosphere in arcsec. Default 0.01 (arcseconds).

• theta_range (float, optional) – Range of parallax offset angles to demand (in radians). Default=0 (means no range requirement).

• snr_limit (float, optional) – Only include points above the snr_limit when computing theta_range. Default 5.

Returns:

metricValu e – Returns a weighted mean of the length of the parallax factor vectors. Values near 1 imply that the points are well distributed. Values near 0 imply that the parallax phase coverage is bad. Near the ecliptic, uniform sampling results in metric values of about 0.5.

Return type:

float

Notes

Uses the ParallaxFactor stacker to calculate ra_pi_amp and dec_pi_amp.

run(data_slice, slice_point=None)

Calculate metric values.

Parameters:

• data_slice (numpy.ndarray, (N,)) – Values passed to metric by the slicer, which the metric will use to calculate metric values at each slice_point.

• slice_point (dict or None) – Dictionary of slice_point metadata passed to each metric. E.g. the ra/dec of the healpix pixel.

Returns:

metricValue – The metric value at each slice_point.

Return type:

int float or object

class rubin_sim.maf.metrics.ParallaxDcrDegenMetric(metric_name='ParallaxDcrDegenMetric', seeing_col='seeingFwhmGeom', m5_col='fiveSigmaDepth', atm_err=0.01, rmag=20.0, sed_template='flat', filter_col='filter', tol=0.05, **kwargs)

Bases: BaseMetric

Use the full parallax and DCR displacement vectors to find if they are degenerate.

Parameters:

• metricName (str, optional) – Default ‘ParallaxDcrDegenMetric’.

• seeing_col (str, optional) – Default ‘FWHMgeom’

• m5_col (str, optional) – Default ‘fiveSigmaDepth’

• filter_col (str) – Default ‘filter’

• atm_err (float) – Minimum error in photometry centroids introduced by the atmosphere (arcseconds). Default 0.01.

• rmag (float) – r-band magnitude of the fiducual star that is being used (mag).

• SedTemplate (str) – The SED template to use for fiducia star colors, passed to rubin_scheduler.utils.stellarMags. Default ‘flat’

• tol (float) – Tolerance for how well curve_fit needs to work before believing the covariance result. Default 0.05.

Returns:

metricValue – Returns the correlation coefficient between the best-fit parallax amplitude and DCR amplitude. The RA and Dec offsets are fit simultaneously. Values close to zero are good, values close to +/- 1 are bad. Experience with fitting Monte Carlo simulations suggests the astrometric fits start becoming poor around a correlation of 0.7.

Return type:

float

run(data_slice, slice_point=None)

Calculate metric values.

Parameters:

• data_slice (numpy.ndarray, (N,)) – Values passed to metric by the slicer, which the metric will use to calculate metric values at each slice_point.

• slice_point (dict or None) – Dictionary of slice_point metadata passed to each metric. E.g. the ra/dec of the healpix pixel.

Returns:

metricValue – The metric value at each slice_point.

Return type:

int float or object

class rubin_sim.maf.metrics.ParallaxMetric(m5_col='fiveSigmaDepth', filter_col='filter', seeing_col='seeingFwhmGeom', rmag=20.0, sed_template='flat', badval=-666, atm_err=0.01, normalize=False, **kwargs)

Bases: BaseMetric

Calculate the uncertainty in a parallax measurement given a series of observations.

Uses columns ra_pi_amp and dec_pi_amp, calculated by the ParallaxFactorStacker.

Parameters:

• m5_col (str, optional) – The default column name for m5 information in the input data.

• filter_col (str, optional) – The column name for the filter information.

• seeing_col (str, optional) – The column name for the seeing information. Since the astrometry errors are based on the physical size of the PSF, this should be the FWHM of the physical psf, e.g. seeingFwhmGeom.

• rmag (float, optional) – The r magnitude of the fiducial star in r band. Other filters are scaled using sedTemplate keyword.

• SedTemplate (str, optional) – The template to use. This can be ‘flat’ or ‘O’,’B’,’A’,’F’,’G’,’K’,’M’.

• atm_err (float, optional) – The expected centroiding error due to the atmosphere, in arcseconds. Default 0.01.

• normalize (bool, optional) – Compare the astrometric uncertainty to the uncertainty that would result if half the observations were taken at the start and half at the end. A perfect survey will have a value close to 1, while a poorly scheduled survey will be close to 0.

• badval (float, optional) – The value to return when the metric value cannot be calculated.

run(data_slice, slice_point=None)

Calculate metric values.

Parameters:

• data_slice (numpy.ndarray, (N,)) – Values passed to metric by the slicer, which the metric will use to calculate metric values at each slice_point.

• slice_point (dict or None) – Dictionary of slice_point metadata passed to each metric. E.g. the ra/dec of the healpix pixel.

Returns:

metricValue – The metric value at each slice_point.

Return type:

int float or object

class rubin_sim.maf.metrics.PassMetric(cols=None, **kwargs)

Bases: BaseMetric

Pass the entire dataslice array back to the MetricBundle.

This is most likely useful while prototyping metrics and wanting to just ‘get the data at a point in the sky’, while using a HealpixSlicer or a UserPointSlicer.

run(data_slice, slice_point=None)

Calculate metric values.

Parameters:

• data_slice (numpy.ndarray, (N,)) – Values passed to metric by the slicer, which the metric will use to calculate metric values at each slice_point.

• slice_point (dict or None) – Dictionary of slice_point metadata passed to each metric. E.g. the ra/dec of the healpix pixel.

Returns:

metricValue – The metric value at each slice_point.

Return type:

int float or object

class rubin_sim.maf.metrics.PeakVMagMetric(**kwargs)

Bases: BaseMoMetric

Pull out the peak V magnitude of all observations of the SSobject.

run(sso_obs, orb, hval)

Calculate the metric value.

Parameters:

• sso_obs (np.ndarray, (N,)) – The input data to the metric (same as the parent metric).

• orb (np.ndarray, (N,)) – The information about the orbit for which the metric is being calculated.

• hval (float) – The H value for which the metric is being calculated.

Returns:

metric_val

Return type:

float or np.ndarray or dict

class rubin_sim.maf.metrics.PercentileMetric(col=None, percentile=90, metric_name=None, **kwargs)

Bases: BaseMetric

Find the value of a column at a given percentile.

run(data_slice, slice_point=None)

Calculate metric values.

Parameters:

• data_slice (numpy.ndarray, (N,)) – Values passed to metric by the slicer, which the metric will use to calculate metric values at each slice_point.

• slice_point (dict or None) – Dictionary of slice_point metadata passed to each metric. E.g. the ra/dec of the healpix pixel.

Returns:

metricValue – The metric value at each slice_point.

Return type:

int float or object

class rubin_sim.maf.metrics.PeriodicDetectMetric(mjd_col='observationStartMJD', periods=2.0, amplitudes=0.1, m5_col='fiveSigmaDepth', metric_name='PeriodicDetectMetric', filter_col='filter', star_mags=20, sig_level=0.05, sed_template='F', **kwargs)

Bases: BaseMetric

Determine if we would be able to classify an object as periodic/non-uniform, using an F-test.

The idea here is that if a periodic source is aliased, it will be indistinguishable from a constant source, so we can find a best-fit constant, and if the reduced chi-squared is ~1, we know we are aliased.

Parameters:

• mjd_col (str, opt) – Name of the MJD column in the observations.

• periods (float or np.ndarray, (N,), opt) – The period of the star (days). Can be a single value, or an array. If an array, amplitude and starMag should be arrays of equal length.

• amplitudes (float, opt) – The amplitude of the stellar variability, (mags).

• m5_col (str, opt) – The name of the m5 limiting magnitude column in the observations.

• metric_name (str, opt) – The name for the metric.

• starMags (float, opt) – The mean magnitude of the star in r (mags).

• sig_level (float, opt) – The value to use to compare to the p-value when deciding if we can reject the null hypothesis.

• sed_template (str, opt) – The stellar SED template to use to generate realistic colors (default is an F star, so RR Lyrae-like)

Returns:

flag – Returns 1 if we would detect star is variable, 0 if it is well-fit by a constant value. If using arrays to test multiple period-amplitude-mag combinations, will be the sum of the number of detected stars.

Return type:

int

run(data_slice, slice_point=None)

Calculate metric values.

Parameters:

• data_slice (numpy.ndarray, (N,)) – Values passed to metric by the slicer, which the metric will use to calculate metric values at each slice_point.

• slice_point (dict or None) – Dictionary of slice_point metadata passed to each metric. E.g. the ra/dec of the healpix pixel.

Returns:

metricValue – The metric value at each slice_point.

Return type:

int float or object

class rubin_sim.maf.metrics.PeriodicQualityMetric(mjd_col='observationStartMJD', period=2.0, m5_col='fiveSigmaDepth', metric_name='PhaseCoverageMetric', star_mag=20, **kwargs)

Bases: BaseMetric

Evaluate phase coverage over a given period.

Parameters:

• mjd_col (str, opt) – Name of the MJD column in the observations.

• period (float, opt) – Period to check.

• m5_col (str, opt) – Name of the m5 column in the observations.

• metric_name (str, opt) – Name of the metric.

• star_mag (float, opt) – Magnitude of the star to simulate coverage for.

Returns:

value – Value representing phase_coverage * amplitude_snr. Ranges from 0 (poor) to 1.

Return type:

float

run(data_slice, slice_point=None)

Calculate metric values.

Parameters:

• data_slice (numpy.ndarray, (N,)) – Values passed to metric by the slicer, which the metric will use to calculate metric values at each slice_point.

• slice_point (dict or None) – Dictionary of slice_point metadata passed to each metric. E.g. the ra/dec of the healpix pixel.

Returns:

metricValue – The metric value at each slice_point.

Return type:

int float or object

class rubin_sim.maf.metrics.PhaseGapMetric(col='observationStartMJD', n_periods=5, period_min=3.0, period_max=35.0, n_visits_min=3, metric_name='Phase Gap', **kwargs)

Bases: BaseMetric

Measure the maximum gap in phase coverage for observations of periodic variables.

Parameters:

• col (str, optional) – Name of the column to use for the observation times (MJD)

• n_periods (int, optional) – Number of periods to test

• period_min (float, optional) – Minimum period to test, in days.

• period_max (float, optional) – Maximum period to test, in days

• n_visits_min (int, optional) – Minimum number of visits necessary before looking for the phase gap.

Returns:

metric_value – Calculates a dictionary of max gap in phase coverage for each period.

Return type:

dict {periods: float, maxGaps : float}

reduce_largest_gap(metric_val)

At each slice_point, return the largest phase gap value.

reduce_mean_gap(metric_val)

At each slice_point, return the mean gap value.

reduce_median_gap(metric_val)

At each slice_point, return the median gap value.

reduce_worst_period(metric_val)

At each slice_point, return the period with the largest phase gap.

run(data_slice, slice_point=None)

Calculate metric values.

Parameters:

• data_slice (numpy.ndarray, (N,)) – Values passed to metric by the slicer, which the metric will use to calculate metric values at each slice_point.

• slice_point (dict or None) – Dictionary of slice_point metadata passed to each metric. E.g. the ra/dec of the healpix pixel.

Returns:

metricValue – The metric value at each slice_point.

Return type:

int float or object

class rubin_sim.maf.metrics.ProperMotionMetric(metric_name='properMotion', m5_col='fiveSigmaDepth', mjd_col='observationStartMJD', filter_col='filter', seeing_col='seeingFwhmGeom', rmag=20.0, sed_template='flat', badval=-666, atm_err=0.01, normalize=False, baseline=10.0, **kwargs)

Bases: BaseMetric

Calculate the uncertainty in the returned proper motion.

This metric assumes gaussian errors in the astrometry measurements.

Parameters:

• metricName (str, optional) – Default ‘properMotion’.

• m5_col (str, optional) – The default column name for m5 information in the input data. Default fiveSigmaDepth.

• mjd_col (str, optional) – The column name for the exposure time. Default observationStartMJD.

• filterCol (str, optional) – The column name for the filter information. Default filter.

• seeing_col (str, optional) – The column name for the seeing information. Since the astrometry errors are based on the physical size of the PSF, this should be the FWHM of the physical psf. Default seeingFwhmGeom.

• rmag (float, optional) – The r magnitude of the fiducial star in r band. Other filters are sclaed using sedTemplate keyword. Default 20.0

• SedTemplate (str, optional) – The template to use. This can be ‘flat’ or ‘O’,’B’,’A’,’F’,’G’,’K’,’M’. Default flat.

• atm_err (float, optional) – The expected centroiding error due to the atmosphere, in arcseconds. Default 0.01.

• normalize (bool, optional) – Compare the astrometric uncertainty to the uncertainty that would result if half the observations were taken at the start and half at the end. A perfect survey will have a value close to 1, while a poorly scheduled survey will be close to 0. Default False.

• baseline (float, optional) – The length of the survey used for the normalization, in years. Default 10.

• badval (float, optional) – The value to return when the metric value cannot be calculated. Default -666.

run(data_slice, slice_point=None)

Calculate metric values.

Parameters:

• data_slice (numpy.ndarray, (N,)) – Values passed to metric by the slicer, which the metric will use to calculate metric values at each slice_point.

• slice_point (dict or None) – Dictionary of slice_point metadata passed to each metric. E.g. the ra/dec of the healpix pixel.

Returns:

metricValue – The metric value at each slice_point.

Return type:

int float or object

class rubin_sim.maf.metrics.QSONumberCountsMetric(lsst_filter, m5_col='fiveSigmaDepth', units='mag', extinction_cut=1.0, filter_col='filter', metric_name='QSONumberCountsMetric', qlf_module='Shen20', qlf_model='A', sed_model='Richards06', zmin=0.3, zmax=None, **kwargs)

Bases: BaseMetric

Calculate the number of quasars expected with SNR>=5 according to the Shen et al. (2020) QLF - model A in the redshift range zmin < z < zmax.

The 5 sigma depths are obtained using the ExgalM5 metric. Only quasars fainter than the saturation magnitude are counted.

By default, zmin is 0.3 and zmax is the minimum between 6.7 and the redshift at which the Lyman break matches the effective wavelength of the band. For bands izy, zmax is 6.7. This default choice is to match Table 10.2 for i-band quasar counts in the LSST Science book.

run(data_slice, slice_point=None)

Calculate metric values.

Parameters:

• data_slice (numpy.ndarray, (N,)) – Values passed to metric by the slicer, which the metric will use to calculate metric values at each slice_point.

• slice_point (dict or None) – Dictionary of slice_point metadata passed to each metric. E.g. the ra/dec of the healpix pixel.

Returns:

metricValue – The metric value at each slice_point.

Return type:

int float or object

class rubin_sim.maf.metrics.RIZDetectionCoaddExposureTime(exp_time_col='visitExposureTime', filter_col='filter', ebvlim=0.2, min_expTime=15, det_bands=None, min_bands=None, metric_name='riz_detcoadd_exptime', **kwargs)

Bases: BaseMetric

A metric computing the total exposure time of an riz coadd.

This metric is intended to be used as a proxy for depth fluctuations in catalogs detected from coadds of the r, i and z bands together. This coadding + detection scheme is used by metadetection (weak lensing shear estimator) and will likely be adopted by the Rubin science pipelines.

It counts the total exposure time in all three bands, excluding dusty regions, exposures that are too short, or areas where not all bands ugrizY are present. We do not make a depth cut explicitly since that is circular (and thus confuses MRB’s feeble mind :/).

TODO maybe:

• apply some sort of inverse variance weighting to the coadd based on sky level?

• use some sort of effective exposure time that accounts for the PSF?

• @rhiannonlynne nicely suggested this Teff computation: rubin_sim/rubin_sim/maf/metrics/technicalMetrics.py

However, given the unknown nature of detection will look like in LSST, a simple sum of exposure time is probably ok.

Parameters:

• bins (list of float) – The bin edges. Typically this will be a list of nights for which to compute the riz coadd exposure times.

• bin_col (str, optional) – The column to bin on. The default is ‘night’.

• exp_time_col (str, optional) – The column name for the exposure time.

• filter_col (str, optional) – The column name for the filter name.

• ebvlim (float, optional) – The upper limit on E(B-V). Regions with E(B-V) greater than this limit are excluded.

• min_exp_time (float, optional) – The minimal exposure time for a visit to contribute to a coadd.

• det_bands (list of str, optional) – If not None, the bands to use for detection. If None, defaults to riz.

• min_bands (list of str, optional) – If not None, the bands whose presence is used to cut the survey data. If None, defaults to ugrizY.

run(data_slice, slice_point)

Calculate metric values.

Parameters:

• data_slice (numpy.ndarray, (N,)) – Values passed to metric by the slicer, which the metric will use to calculate metric values at each slice_point.

• slice_point (dict or None) – Dictionary of slice_point metadata passed to each metric. E.g. the ra/dec of the healpix pixel.

Returns:

metricValue – The metric value at each slice_point.

Return type:

int float or object

class rubin_sim.maf.metrics.RadiusObsMetric(metric_name='radiusObs', ra_col='fieldRA', dec_col='fieldDec', units='radians', **kwargs)

Bases: BaseMetric

Evaluate slice point radial position in the focal plane of each visit, reducing to the mean, rms and full range of these radial distances.

run(data_slice, slice_point)

Calculate metric values.

Parameters:

• data_slice (numpy.ndarray, (N,)) – Values passed to metric by the slicer, which the metric will use to calculate metric values at each slice_point.

• slice_point (dict or None) – Dictionary of slice_point metadata passed to each metric. E.g. the ra/dec of the healpix pixel.

Returns:

metricValue – The metric value at each slice_point.

Return type:

int float or object

class rubin_sim.maf.metrics.RapidRevisitMetric(mjd_col='observationStartMJD', metric_name='RapidRevisit', d_tmin=0.0004629629629629629, d_tpairs=0.013888888888888888, d_tmax=0.020833333333333332, min_n1=28, min_n2=82, **kwargs)

Bases: BaseMetric

run(data_slice, slice_point=None)

Calculate metric values.

Parameters:

• data_slice (numpy.ndarray, (N,)) – Values passed to metric by the slicer, which the metric will use to calculate metric values at each slice_point.

• slice_point (dict or None) – Dictionary of slice_point metadata passed to each metric. E.g. the ra/dec of the healpix pixel.

Returns:

metricValue – The metric value at each slice_point.

Return type:

int float or object

class rubin_sim.maf.metrics.RapidRevisitUniformityMetric(mjd_col='observationStartMJD', min_nvisits=100, d_tmin=0.0004629629629629629, d_tmax=0.020833333333333332, metric_name='RapidRevisitUniformity', **kwargs)

Bases: BaseMetric

Calculate uniformity of time between consecutive visits on short timescales (for RAV1).

Uses the same ‘uniformity’ calculation as the UniformityMetric, based on the KS-test. A value of 0 is perfectly uniform; a value of 1 is purely non-uniform.

Parameters:

• mjd_col (str, optional) – The column containing the ‘time’ value. Default observationStartMJD.

• min_nvisits (int, optional) – The minimum number of visits required within the time interval (d_tmin to d_tmax). Default 100.

• d_tmin (float, optional) – The minimum dTime to consider (in days). Default 40 seconds.

• d_tmax (float, optional) – The maximum dTime to consider (in days). Default 30 minutes.

run(data_slice, slice_point=None)

Calculate metric values.

Parameters:

• data_slice (numpy.ndarray, (N,)) – Values passed to metric by the slicer, which the metric will use to calculate metric values at each slice_point.

• slice_point (dict or None) – Dictionary of slice_point metadata passed to each metric. E.g. the ra/dec of the healpix pixel.

Returns:

metricValue – The metric value at each slice_point.

Return type:

int float or object

class rubin_sim.maf.metrics.RealMeanMetric(col=None, metric_name=None, maps=None, units=None, metric_dtype=None, badval=-666, mask_val=None)

Bases: BaseMetric

Calculate the mean of a column with no nans or infs.

run(data_slice, slice_point=None)

Calculate metric values.

Parameters:

• data_slice (numpy.ndarray, (N,)) – Values passed to metric by the slicer, which the metric will use to calculate metric values at each slice_point.

• slice_point (dict or None) – Dictionary of slice_point metadata passed to each metric. E.g. the ra/dec of the healpix pixel.

Returns:

metricValue – The metric value at each slice_point.

Return type:

int float or object

class rubin_sim.maf.metrics.RelRmsMetric(col=None, metric_name=None, maps=None, units=None, metric_dtype=None, badval=-666, mask_val=None)

Bases: BaseMetric

Calculate the relative scatter metric (RMS divided by median).

run(data_slice, slice_point=None)

Calculate metric values.

Parameters:

• data_slice (numpy.ndarray, (N,)) – Values passed to metric by the slicer, which the metric will use to calculate metric values at each slice_point.

• slice_point (dict or None) – Dictionary of slice_point metadata passed to each metric. E.g. the ra/dec of the healpix pixel.

Returns:

metricValue – The metric value at each slice_point.

Return type:

int float or object

class rubin_sim.maf.metrics.RmsAngleMetric(col=None, metric_name=None, maps=None, units=None, metric_dtype=None, badval=-666, mask_val=None)

Bases: BaseMetric

Calculate the standard deviation of an angular (degrees) column slice.

‘RmsAngle’ differs from ‘Rms’ in that it accounts for wraparound at 2pi.

run(data_slice, slice_point=None)

Calculate metric values.

Parameters:

• data_slice (numpy.ndarray, (N,)) – Values passed to metric by the slicer, which the metric will use to calculate metric values at each slice_point.

• slice_point (dict or None) – Dictionary of slice_point metadata passed to each metric. E.g. the ra/dec of the healpix pixel.

Returns:

metricValue – The metric value at each slice_point.

Return type:

int float or object

class rubin_sim.maf.metrics.RmsMetric(col=None, metric_name=None, maps=None, units=None, metric_dtype=None, badval=-666, mask_val=None)

Bases: BaseMetric

Calculate the standard deviation of a simData column slice.

run(data_slice, slice_point=None)

Calculate metric values.

Parameters:

• data_slice (numpy.ndarray, (N,)) – Values passed to metric by the slicer, which the metric will use to calculate metric values at each slice_point.

• slice_point (dict or None) – Dictionary of slice_point metadata passed to each metric. E.g. the ra/dec of the healpix pixel.

Returns:

metricValue – The metric value at each slice_point.

Return type:

int float or object

class rubin_sim.maf.metrics.RobustRmsMetric(col=None, metric_name=None, maps=None, units=None, metric_dtype=None, badval=-666, mask_val=None)

Bases: BaseMetric

Use the inter-quartile range of the data to estimate the RMS. Robust, as this calculation does not include outliers in the distribution.

run(data_slice, slice_point=None)

Calculate metric values.

Parameters:

• data_slice (numpy.ndarray, (N,)) – Values passed to metric by the slicer, which the metric will use to calculate metric values at each slice_point.

• slice_point (dict or None) – Dictionary of slice_point metadata passed to each metric. E.g. the ra/dec of the healpix pixel.

Returns:

metricValue – The metric value at each slice_point.

Return type:

int float or object

class rubin_sim.maf.metrics.SFUncertMetric(mag=22, times_col='observationStartMJD', m5_col='fiveSigmaDepth', all_gaps=True, units='mag', bins=array([1.00000000e+00, 1.72777104e+00, 2.98519278e+00, 5.15772963e+00, 8.91137591e+00, 1.53968172e+01, 2.66021750e+01, 4.59624676e+01, 7.94126206e+01, 1.37206826e+02, 2.37061981e+02, 4.09588826e+02, 7.07675714e+02, 1.22270161e+03, 2.11254843e+03, 3.65000000e+03]), weight=None, metric_name='Structure Function Uncert', snr_cut=5, filter_col='filter', dust=True, **kwargs)

Bases: BaseMetric

Structure Function (SF) Uncertainty Metric. Developed on top of LogTGaps

Adapted from Weixiang Yu & Gordon Richards at: RichardsGroup/ LSST_SF_Metric/blob/main/notebooks/00_SFErrorMetric.ipynb

Parameters:

• mag (float) – The magnitude of the fiducial object. Default 22.

• times_col (str) – Time column name. Defaults to “observationStartMJD”.

• all_gaps (bool) – Whether to use all gaps (between any two pairs of observations). If False, only use consecutive paris. Defaults to True.

• units (str) – Unit of this metric. Defaults to “mag”.

• bins (object) – An array of bin edges. Defaults to “np.logspace(0, np.log10(3650), 16)” for a total of 15 (final) bins.

• weight (object) – The weight assigned to each delta_t bin for deriving the final metric. Defaults to flat weighting with sum of 1. Should have length 1 less than bins.

• snr_cut (float) – Ignore observations below an SNR limit, default 5.

• dust (bool) – Apply dust extinction to the fiducial object magnitude. Default True.

run(data_slice, slice_point=None)

Code executed at each healpix pixel to compute the metric

class rubin_sim.maf.metrics.SNCadenceMetric(metric_name='SNCadenceMetric', mjd_col='observationStartMJD', ra_col='fieldRA', dec_col='fieldDec', filter_col='filter', m5_col='fiveSigmaDepth', exptime_col='visitExposureTime', night_col='night', obsid_col='observationId', nexp_col='numExposures', vistime_col='visitTime', coadd=True, lim_sn=None, **kwargs)

Bases: BaseMetric

Metric to estimate the redshift limit for faint supernovae (x1,color) = (-2.0,0.2)

Parameters:

• list (str, optional) – Name of the columns used to estimate the metric

• coadd (bool, optional) – to make “coaddition” per night (uses snStacker) Default True

• lim_sn (class, optional) – Reference data used to estimate redshift values (interpolation)

run(data_slice, slice_point=None)

Calculate metric values.

Parameters:

• data_slice (numpy.ndarray, (N,)) – Values passed to metric by the slicer, which the metric will use to calculate metric values at each slice_point.

• slice_point (dict or None) – Dictionary of slice_point metadata passed to each metric. E.g. the ra/dec of the healpix pixel.

Returns:

metricValue – The metric value at each slice_point.

Return type:

int float or object

class rubin_sim.maf.metrics.SNNSNMetric(metric_name='SNNSNMetric', mjd_col='observationStartMJD', filter_col='filter', m5_col='fiveSigmaDepth', exptime_col='visitExposureTime', night_col='night', obsid_col='observationId', nexp_col='numExposures', vistime_col='visitTime', seeing_col='seeingFwhmEff', note_col='scheduler_note', season=[-1], coadd_night=True, zmin=0.1, zmax=0.5, z_step=0.03, daymax_step=3.0, verbose=False, ploteffi=False, n_bef=3, n_aft=8, snr_min=1.0, n_phase_min=1, n_phase_max=1, sigma_c=0.04, zlim_coeff=0.95, bands='grizy', add_dust=False, hard_dust_cut=0.25, gamma_name='gamma_WFD.hdf5', **kwargs)

Bases: BaseMetric

Measure zlim of type Ia supernovae.

Parameters:

• metricName (str, opt) – metric name (default : SNSNRMetric)

• mjd_col (str, opt) – mjd column name (default : observationStartMJD)

• filter_col (str, opt) – filter column name (default: filter)

• m5_col (str, opt) – five-sigma depth column name (default : fiveSigmaDepth)

• exptime_col (str, opt) – exposure time column name (default : visitExposureTime)

• night_col (str, opt) – night column name (default : night)

• obsid_col (str, opt) – observation id column name (default : observationId)

• nexp_col (str, opt) – number of exposure column name (default : numExposures)

• vistime_col (str, opt) – visit time column name (default : visitTime)

• seeing_col (str, opt) – seeing column name (default: seeingFwhmEff)

• note_col (str, opt) – note column name (default: note)

• season (list, opt) – list of seasons to process (float)(default: -1 = all seasons)

• coadd (bool, opt) – coaddition per night (and per band) (default : True)

• zmin (float, opt) – min redshift for the study (default: 0.0)

• zmax (float, opt) – max redshift for the study (default: 1.2)

• verbose (bool, opt) – verbose mode (default: False)

• n_bef (int, opt) – number of LC points LC before T0 (default:5)

• n_aft (int, opt) – number of LC points after T0 (default: 10)

• snr_min (float, opt) – minimal SNR of LC points (default: 5.0)

• n_phase_min (int, opt) – number of LC points with phase<= -5(default:1)

• n_phase_max (int, opt) – number of LC points with phase>= 20 (default: 1)

• zlim_coeff (float, opt) – corresponds to the zlim_coeff fraction of SN with z<zlim

• bands (str, opt) – bands to consider (default: grizy)

• gammaName (str, opt) – name of the gamma ref file to load (default: gamma_WFD.hdf5)

• dust (bool, opt) – Apply dust extinction to visit depth values (default False)

• hard_dust_cut (float, opt) – If set, cut any point on the sky that has an ebv extinction higher than the hard_dust_cut value. Default 0.25

calc_daymax(grp, daymax_step)

Method to estimate T0 (daymax) values for simulation.

Parameters:

• grp (group (pd.DataFrame sense)) – group of data to process with the following cols: t0_min: T0 min value (per season) t0_max: T0 max value (per season)

• daymax_step (float) – step for T0 simulation

Return type:

pd.DataFrame with daymax, min_rf_phase, max_rf_phase values

check_dur_z(dur_z, nmin=2)

” Method to remove seasons with a poor redshift range due to too low season length

Parameters:

• dur_z (pd.DataFrame) – data to process

• nmin (int, opt) – minimal number of redshift points per season (default: 2)

Returns:

dur_z_subset – dur_z but only with seasons having at least nmin points in redshift

Return type:

pd.DataFrame

coadd(obs)

Method to coadd data per band and per night

Parameters:

data (pd.DataFrame) – pd.DataFrame of observations

Returns:

coadded data

Return type:

pd.DataFrame

duration_z(grp, min_duration=60.0)

Method to estimate the season length vs redshift This is necessary to take into account boundary effects when estimating the number of SN that can be detected

daymin, daymax = min and max MJD of a season T0_min(z) = daymin-(1+z)*min_rf_phase_qual T0_max(z) = daymax-(1+z)*max_rf_phase_qual season_length(z) = T0_max(z)-T0_min(z)

Parameters:

• grp (pd.DataFrame group) – data to process: season infos

• min_duration (float, opt) – min season length for a season to be processed (deafult: 60 days)

Return type:

pd.DataFrame with season_length, z, T0_min and T0_max cols

efficiencies(dfo)

” Method to estimate selection efficiencies

Parameters:

df (pd.DataFrame) – data to process

gen_lc(grp, gen_par_orig, x1, color)

Method to generate light curves from observations

Parameters:

• grp (pd group) – observations to process

• gen_par_orig (pd.DataFrame) – simulation parameters

• x1 (float) – SN stretch

• color (float) – SN color

Return type:

light curves as pd.DataFrame

get_epochs(nights, flag, flagph)

Method to get the number of epochs

Parameters:

• nights (array) – night number array

• flag (array(bool)) – flag to apply

• flagph (array(bool)) – flag to apply

Return type:

array with the number of epochs

get_nsn(effi, durinterp_z, zmin, zmax, zstep)

Method to estimate to total number of SN: NSN = Sum(effi(z)*rate(z))

Parameters:

• effi (1D interpolator) – efficiencies vs z

• durinterp_z (1D interpolator) – duration vs z

• zmin (float) – redshift min

• zmax (float) – redshift max

• zstep (float) – redshift step

Returns:

tot_sn – total number of SN up to zmax

Return type:

int

get_season_info(dfa, zseason, min_duration=60.0)

method to get season infos vs z

Parameters:

• dfa (pd.DataFrame) – data to process

• zseason (pd.DataFrame) – redshift infos per season

• min_duration (float, opt) – min season length to be accepted (default: 60 days)

Returns:

season_info

Return type:

pd.DataFrame with season length infos

get_sum(lcarr, varname, nvals, flag)

Method to get the sum of variables using broadcasting

Parameters:

• lcarr (numpy array) – data to process

• varname (str) – col to process in lcarr

• nvals (int) – dimension for tiling

• flag (array(bool)) – flag to apply

Returns:

array

Return type:

the sum of the corresponding variable

getseason(obs, season_gap=80.0, mjd_col='observationStartMJD')

Method to estimate seasons

Parameters:

• obs (np.ndarray) – array of observations

• season_gap (float, optional) – minimal gap required to define a season (default: 80 days)

• mjd_col (str, optional) – col name for MJD infos (default: observationStartMJD)

Returns:

obs – original numpy array with seasonnumber appended

Return type:

np.ndarray

metric(data_slice, zseason, x1=-2.0, color=0.2, zlim=-1, metric='zlim')

Method to run the metric

Parameters:

• data_slice (array) – observations to use for processing

• zseason (array) – season infos (season length vs z)

• x1 (float, opt) – SN stretch (default: -2.0)

• color (float, opt) – SN color (default: -0.2)

• zlim (float, opt) – redshift limit used to estimate NSN (default: -1)

• metric (str, opt) – metric to estimate [zlim or nsn] (default: zlim)

nsn(grp, sn_type='medium')

Method to estimate the metric nsn up to zlim

Parameters:

• grp (pd group)

• sn_type (str, opt) – type of SN to estimate zlim (default: medium)

Returns:

nsn – Dataframe with the metric as cols

Return type:

pd.DataFrame

nsn_expected_z(grp)

Method to estimate the expected nsn vs redshift

Parameters:

grp (pd.DataFrame group) – data to process: season infos

Return type:

pd.DataFrame with season_length, z, nsn_expected cols

nsn_from_rate(grp)

Method to estimate the expected number of supernovae

Parameters:

grp (pd.DataFrame) – data to process

Return type:

pd.DataFrame with z and nsn_expected as cols

run(data_slice, slice_point)

Run method of the metric

Parameters:

• data_slice (np.ndarray) – Observations to process (scheduler simulations)

• slice_point (bool, opt) – Information about the location on the sky from the slicer

Returns:

metricVal – [‘n_sn’, ‘zlim’] at this point on the sky

Return type:

np.ndarray

season_info(grp, min_duration)

Method to estimate seasonal info (cadence, season length, …)

Parameters:

• grp (pd.DataFrame group)

• min_duration (float) – minimal duration for a season to be considered

Returns:

• pd.DataFrame with the following cols

• - Nvisits (number of visits for this group)

• - N_xx (number of visits in xx where xx is defined in self.bandstat)

season_length(seasons, data_slice, zseason)

Method to estimate season lengths vs z

Parameters:

• seasons (list [int]) – list of seasons to process

• data_slice (np.ndarray, (N,)`) – array of observations

• zseason (pd.DataFrame) – redshift infos per season

Returns:

• seasons (list [int]) – list of seasons to process

• dur_z (pd.DataFrame) – season lengths vs z

sigma_s_nparams(grp)

Method to estimate variances of SN parameters from inversion of the Fisher matrix

Parameters:

grp (pd.DataFrame of flux derivatives wrt SN parameters)

Return type:

Diagonal elements of the inverted matrix (as pd.DataFrame)

sn_effi(lc)

Method to transform LCs to supernovae

Parameters:

lc (pd grp) – light curve

Return type:

pd.DataFrame of sn efficiencies vs z

step_efficiencies(lc)

Method to estimate observing efficiencies

Parameter

lc: pd.DataFrame

light curves

rtype:

pd.DataFrame with efficiencies

step_lc(obs, gen_par, x1=-2.0, color=0.2)

Method to generate lc

Parameters:

• obs (array) – observations

• gen_par (array) – simulation parameters

• x1 (float, opt) – stretch value (default: -2.0)

• color (float, opt) – color value (default: 0.2)

Return type:

SN light curves (astropy table)

step_nsn(sn_effis, dur_z)

Method to estimate the number of supernovae from efficiencies

Parameters:

• sn_effis (pd.DataFrame) – data with efficiencies of observation

• dur_z (array) – array of season length

Return type:

initial sn_effis appended with a set of infos (duration, nsn)

z_season(seasons, data_slice)

Fill the z values per season

Parameters:

• seasons (list) – seasons to process

• data_slice (array) – data to process

zlim(grp, sn_type='faint')

Method to estimate the metric zcomp

Parameters:

• grp (pd group)

• sn_type (str, opt) – type of SN to estimate zlim (default: faint)

Returns:

zcomp

Return type:

pd.DataFrame with the metric as cols

zlim_or_nsn(effi, sntype='faint', zlim=-1.0)

Method to estimate the redshift limit or the number of sn

Parameters:

• effi (pd.DataFrame) – data to process

• sntype (str, opt) – type of SN to consider for estimation (default: faint)

• zlim (float, opt) – redshift limit

Returns:

• if zlim<0 (returns the redshift limit)

• if zlim>0 (returns the number of sn up to zlim)

class rubin_sim.maf.metrics.SNSLMetric(metric_name='SNSLMetric', mjd_col='observationStartMJD', filter_col='filter', night_col='night', m5_col='fiveSigmaDepth', season=None, nfilters_min=4, min_season_obs=5, m5mins=None, maps=['DustMap'], **kwargs)

Bases: BaseMetric

Calculate the number of expected well-measured strongly lensed SN (per data_slice).

Parameters:

• metric_name (str, optional) – metric name Default : SNCadenceMetric

• mjd_col (str, optional) – mjd column name Default : observationStartMJD,

• filter_col (str, optional) – filter column name Default: filter

• night_col (str, optional) – night column name Default : night

• m5_col (str, optional) – individual visit five-sigma limiting magnitude (m5) column name Default : fiveSigmaDepth

• season (list [int] or None, optional) – season to process (default: None: all seasons) A list with [-1] processes all seasons, as does None.

• nfilters_min (int, optional) – The number of filters to demand in a season Default: 4.

• min_season_obs (int, optional) – Minimum number of observations per season. Default 5.

• m5mins (dict, optional) – Minimum individual image depth for visit to ‘count’. Default None uses {‘u’: 22.7, ‘g’: 24.1, ‘r’: 23.7, ‘i’: 23.1, ‘z’: 22.2, ‘y’: 21.4}.

• maps (list, optional) – List of maps to use. Default is the dustmap, to reduce m5 limiting mags accordingly.

Returns:

n_slsn – Number of expected well-measured strongly lensed SN

Return type:

float

Notes

The number of expected strongly lensed SN detections with a well-measured time delay is given by:

N (lensed SNe Ia with well measured time delay) = 45.7 * survey_area / (20000 deg^2) * cumulative_season_length / (2.5 years) / (2.15 * exp(0.37 * gap_median_all_filter))

where: survey_area: survey area (in deg2) cumulative_season_length: cumulative season length (in years) gap_median_all_filter: median gap (all filters) (in days)

(reference? metric originated from Simon Huber and Phillipe Gris)

n_lensed(area, cadence, season_length)

Estimate the number of lensed supernovae.

Parameters:

• area (float) – Area in square degrees related to this data_slice (sq deg)

• gap_median (float) – median gap between nights with visits (days) - any filter

• cumul_season (float) – length of the season or period of consideration (years)

Returns:

n_lensed_s_ne__ia – Number of strongly lensed SN expected in this area

Return type:

float

run(data_slice, slice_point=None)

Runs the metric for each data_slice

Parameters:

• data_slice (simulation data)

• slice_point (slice_point(default None))

Return type:

number of SL time delay supernovae

class rubin_sim.maf.metrics.SNSNRMetric(metric_name='SNSNRMetric', mjd_col='observationStartMJD', ra_col='fieldRA', dec_col='fieldDec', filter_col='filter', m5_col='fiveSigmaDepth', exptime_col='visitExposureTime', night_col='night', obsid_col='observationId', nexp_col='numExposures', vistime_col='visitTime', coadd=True, lim_sn=None, names_ref=None, season=1, z=0.01, **kwargs)

Bases: BaseMetric

Metric to estimate the detection rate for faint supernovae (x1,color) = (-2.0,0.2)

Parameters:

• coadd (bool, optional) – to make “coaddition” per night (uses snStacker)

• lim_sn (class, optional) – Reference data used to simulate LC points (interpolation)

• names_ref (str, optional) – names of the simulator used to produce reference data

• season (float, optional) – season num

• z (float, optional) – redshift for this study

check_seasons(tab)

Check whether seasons have no overlap if it is the case: modify MJD_min and season length of the corresponding season return only seasons with season_length > 30 days

Parameters:

tab (array with the following fields:)

Returns:

tab

Return type:

array with the following fields:

detection_rate(snr_obs, snr_fakes)

Estimate the time fraction(per season) for which snr_obs > snr_fakes = detection rate For regular cadences one should get a result close to 1

Parameters:

• snr_obs (array) – array estimated using snr_slice(observations)

• snr_fakes (array) – array estimated using snr_slice(fakes)

Returns:

fieldRA (float) fieldDec (float) season (float) band (str) frac_obs_name_ref (float)

Return type:

record array with the following fields

gen_fakes(slice_sel, band)

Generate fake observations according to observing values extracted from simulations

Parameters:

• slice_sel (np.ndarray, (N,)) – array of observations

• band (str) – band to consider

Returns:

fake_obs_season – array of observations with the following fields observationStartMJD (float) field_ra (float) field_dec (float) filter (U1) fiveSigmaDepth (float) numExposures (float) visitExposureTime (float) season (int)

Return type:

np.ndarray

get_season(t0)

Estimate the seasons corresponding to t0 values

Parameters:

t0 (list [float]) – set of t0 values

Returns:

mean_seasons – list (float) of corresponding seasons

Return type:

list [float]

plot(snr_obs, snr_fakes)

Plot SNR vs time

Parameters:

• snr_obs (np.ndarray, (N,)) – array estimated using snr_slice(observations)

• snr_obs – array estimated using snr_slice(fakes)

plot_history(fluxes, mjd, flag, snr, t0_lc, dates)

Plot history of lightcurve For each MJD, fluxes and snr are plotted Each plot may be saved as a png to make a video afterwards

Parameters:

• fluxes (list [float]) – LC fluxes

• mjd (list(float)) – mjds of the fluxes

• flag (array) – flag for selection of fluxes

• snr (list) – signal-to-noise ratio

• t0_lc (list(float)) – list of T0 supernovae

• dates (list(float)) – date of the display (mjd)

process(sel)

Process one season

Parameters:

• sel (np.narray) – array of observations

• season (int) – season number

Returns:

• record array with the following fields

• fieldRA (float)

• fieldDec (float)

• season (float)

• band (str)

• frac_obs_name_ref (float)

run(data_slice, slice_point=None)

run the metric

Parameters:

data_slice (np.ndarray, (N,)) – simulation data under study

Returns:

detection rate

Return type:

float

season_info(data_slice, season)

Get info on seasons for each data_slice

Parameters:

data_slice (np.ndarray, (N,)) – array of observations

Returns:

• info_season (np.ndarray)

• season, cadence, season_length, MJDmin, MJDmax

snr(time_lc, m5_vals, flag, t0_lc)

Estimate SNR vs time

Parameters:

• time_lc (np.ndarray, (N,))

• m5_vals (list [float]) – five-sigme depth values

• flag (np.ndarray, (N,)) – flag to be applied (example: selection from phase cut)

• season_vals (np.ndarray, (N,)) – season values

• t0_lc (np.ndarray, (N,)) – array of T0 for supernovae

Returns:

• fluxes_tot (list [float]) – list of (interpolated) fluxes

• snr_tab (np.ndarray, (N,)) – snr_name_ref (float) : Signal-to-Noise values season (float) : season num.

snr_fakes(data_slice)

Estimate SNR for fake observations in the same way as for observations (using SNR_Season)

Parameters:

data_slice (np.ndarray, (N,)) – array of observations

Returns:

snr_tab – snr_name_ref (float) : Signal-to-Noise values season (float) : season num.

Return type:

np.ndarray

snr_slice(data_slice, j=-1, output_q=None)

Estimate SNR for a given data_slice

Parameters:

• data_slice (np.ndarray)

• j (int, optional)

• output_q (int, optional)

Returns:

• snr (np.ndarray containing)

• SNR_name_ref (Signal-To-Noise Ratio estimator)

• season (season)

• cadence (cadence of the season)

• season_length (length of the season)

• MJD_min (min MJD of the season)

• DayMax (SN max luminosity MJD (aka T0))

• MJD

• m5_eff (mean m5 of obs passing the min_phase, max_phase cut)

• field_ra (mean field RA)

• field_dec (mean field Dec)

• band (band)

• m5 (mean m5 (over the season))

• nvisits (median number of visits (per observation) (over the season))

• ExposureTime (median exposure time (per observation) (over the season))

class rubin_sim.maf.metrics.SeasonLengthMetric(mjd_col='observationStartMJD', exp_time_col='visitExposureTime', min_exp_time=16, reduce_func=<function median>, metric_name='SeasonLength', **kwargs)

Bases: BaseMetric

Calculate the length of LSST seasons, in days.

Parameters:

• min_exp_time (float, optional) – Minimum visit exposure time to count for a ‘visit’, in seconds. Default 20.

• reduce_func (function, optional) – Function that can operate on array-like structures. Typically numpy function. This reduces the season length in each season from 10 separate values to a single value. Default np.median.

Returns:

seasonlength – The (reduceFunc) of the length of each season, in days.

Return type:

float

run(data_slice, slice_point)

Calculate metric values.

Parameters:

• data_slice (numpy.ndarray, (N,)) – Values passed to metric by the slicer, which the metric will use to calculate metric values at each slice_point.

• slice_point (dict or None) – Dictionary of slice_point metadata passed to each metric. E.g. the ra/dec of the healpix pixel.

Returns:

metricValue – The metric value at each slice_point.

Return type:

int float or object

class rubin_sim.maf.metrics.SkySaturationMetric(metric_name='SkySaturation', units='#', **kwargs)

Bases: BaseMetric

Check if the sky would saturate a visit in an exposure

run(data_slice, slice_point)

Calculate metric values.

Parameters:

• data_slice (numpy.ndarray, (N,)) – Values passed to metric by the slicer, which the metric will use to calculate metric values at each slice_point.

• slice_point (dict or None) – Dictionary of slice_point metadata passed to each metric. E.g. the ra/dec of the healpix pixel.

Returns:

metricValue – The metric value at each slice_point.

Return type:

int float or object

class rubin_sim.maf.metrics.SnrWeightedMetric(col, m5_col='fiveSigmaDepth', metric_name=None, **kwargs)

Bases: BaseMetric

Take the SNR weighted average of a column.

run(data_slice, slice_point=None)

Calculate metric values.

Parameters:

• data_slice (numpy.ndarray, (N,)) – Values passed to metric by the slicer, which the metric will use to calculate metric values at each slice_point.

• slice_point (dict or None) – Dictionary of slice_point metadata passed to each metric. E.g. the ra/dec of the healpix pixel.

Returns:

metricValue – The metric value at each slice_point.

Return type:

int float or object

class rubin_sim.maf.metrics.StarDensityMetric(mag_limit=25.0, filtername='r', units='stars/sq arcsec', maps=['StellarDensityMap'], **kwargs)

Bases: 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 – Number of stars brighter than mag_limit in filtername, based on the stellar density map.

Return type:

float

run(data_slice, slice_point=None)

Calculate metric values.

Parameters:

• data_slice (numpy.ndarray, (N,)) – Values passed to metric by the slicer, which the metric will use to calculate metric values at each slice_point.

• slice_point (dict or None) – Dictionary of slice_point metadata passed to each metric. E.g. the ra/dec of the healpix pixel.

Returns:

metricValue – The metric value at each slice_point.

Return type:

int float or object

class rubin_sim.maf.metrics.StaticProbesFoMEmulatorMetricSimple(nside=128, year=10, col=None, **kwargs)

Bases: BaseMetric

This calculates the Figure of Merit for the combined static probes (3x2pt, i.e., Weak Lensing, LSS, Clustering). This FoM is purely statistical and does not factor in systematics.

This version of the emulator was used to generate the results in https://ui.adsabs.harvard.edu/abs/2018arXiv181200515L/abstract

A newer version is being created. This version has been renamed Simple in anticipation of the newer, more sophisticated metric replacing it.

Note that this is truly a summary metric and should be run on the output of Exgalm5_with_cuts.

run(data_slice, slice_point=None)

Args:

data_slice (ndarray): Values passed to metric by the slicer,

which the metric will use to calculate metric values at each slice_point.

slice_point (Dict): Dictionary of slice_point metadata passed

to each metric.

Returns:

float: Interpolated static-probe statistical Figure-of-Merit.

Raises:

ValueError: If year is not one of the 4 for which a FoM is calculated

class rubin_sim.maf.metrics.StringCountMetric(metric_name='stringCountMetric', col='filter', percent=False, clip_end=False, **kwargs)

Bases: 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.

run(data_slice, slice_point=None)

Calculate metric values.

Parameters:

• data_slice (numpy.ndarray, (N,)) – Values passed to metric by the slicer, which the metric will use to calculate metric values at each slice_point.

• slice_point (dict or None) – Dictionary of slice_point metadata passed to each metric. E.g. the ra/dec of the healpix pixel.

Returns:

metricValue – The metric value at each slice_point.

Return type:

int float or object

class rubin_sim.maf.metrics.SumMetric(col=None, metric_name=None, maps=None, units=None, metric_dtype=None, badval=-666, mask_val=None)

Bases: BaseMetric

Calculate the sum of a simData column slice.

run(data_slice, slice_point=None)

Calculate metric values.

Parameters:

• data_slice (numpy.ndarray, (N,)) – Values passed to metric by the slicer, which the metric will use to calculate metric values at each slice_point.

• slice_point (dict or None) – Dictionary of slice_point metadata passed to each metric. E.g. the ra/dec of the healpix pixel.

Returns:

metricValue – The metric value at each slice_point.

Return type:

int float or object

class rubin_sim.maf.metrics.SurfaceBrightLimitMetric(pixscale=0.2, nsigma=3.0, tot_area=100.0, filter_col='filter', 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)

Bases: 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

run(data_slice, slice_point)

Calculate metric values.

Parameters:

• data_slice (numpy.ndarray, (N,)) – Values passed to metric by the slicer, which the metric will use to calculate metric values at each slice_point.

• slice_point (dict or None) – Dictionary of slice_point metadata passed to each metric. E.g. the ra/dec of the healpix pixel.

Returns:

metricValue – The metric value at each slice_point.

Return type:

int float or object

class rubin_sim.maf.metrics.TdcMetric(mjd_col='observationStartMJD', night_col='night', filter_col='filter', m5_col='fiveSigmaDepth', mag_cuts=None, metric_name='TDC', cad_norm=3.0, sea_norm=4.0, camp_norm=5.0, badval=-999, **kwargs)

Bases: BaseMetric

Calculate the Time Delay Challenge metric, as described in Liao et al 2015 (https://arxiv.org/pdf/1409.1254.pdf).

This combines the MeanCampaignFrequency/MeanNightSeparation, the SeasonLength, and the CampaignLength metrics above, but rewritten to calculate season information only once.

cad_norm = in units of days sea_norm = in units of months camp_norm = in units of years

This metric also adds a requirement to achieve limiting magnitudes after galactic dust extinction, in various bandpasses, in order to exclude visits which are not useful for detecting quasars (due to being short or having high sky brightness, etc.) and to reject regions with high galactic dust extinction.

Parameters:

• mjd_col (str, optional) – Column name for mjd. Default observationStartMJD.

• night_col (str, optional) – Column name for night. Default night.

• filter_col (str, optional) – Column name for filter. Default filter.

• m5_col (str, optional) – Column name for five-sigma depth. Default fiveSigmaDepth.

• mag_cuts (dict, optional) – Dictionary with filtername:mag limit (after dust extinction). Default None in kwarg. Defaults set within metric: {‘u’: 22.7, ‘g’: 24.1, ‘r’: 23.7, ‘i’: 23.1, ‘z’: 22.2, ‘y’: 21.4}

• metricName (str, optional) – Metric Name. Default TDC.

• cad_norm (float, optional) – Cadence normalization constant, in units of days. Default 3.

• sea_norm (float, optional) – Season normalization constant, in units of months. Default 4.

• camp_norm (float, optional) – Campaign length normalization constant, in units of years. Default 5.

• badval (float, optional) – Return this value instead of the dictionary for bad points.

Returns:

TDCmetrics – Dictionary of values for {‘rate’, ‘precision’, ‘accuracy’} at this point in the sky.

Return type:

dict

run(data_slice, slice_point)

Calculate metric values.

Parameters:

• data_slice (numpy.ndarray, (N,)) – Values passed to metric by the slicer, which the metric will use to calculate metric values at each slice_point.

• slice_point (dict or None) – Dictionary of slice_point metadata passed to each metric. E.g. the ra/dec of the healpix pixel.

Returns:

metricValue – The metric value at each slice_point.

Return type:

int float or object

class rubin_sim.maf.metrics.TemplateExistsMetric(seeing_col='seeingFwhmGeom', observation_start_mjd_col='observationStartMJD', metric_name='TemplateExistsMetric', **kwargs)

Bases: BaseMetric

Calculate the fraction of images with a previous template image of desired quality.

run(data_slice, slice_point=None)

Calculate metric values.

Parameters:

• data_slice (numpy.ndarray, (N,)) – Values passed to metric by the slicer, which the metric will use to calculate metric values at each slice_point.

• slice_point (dict or None) – Dictionary of slice_point metadata passed to each metric. E.g. the ra/dec of the healpix pixel.

Returns:

metricValue – The metric value at each slice_point.

Return type:

int float or object

class rubin_sim.maf.metrics.TemplateTime(n_images_in_template=3, seeing_percentile=50, m5_percentile=50, seeing_col='seeingFwhmEff', m5_col='fiveSigmaDepth', night_col='night', mjd_col='observationStartMJD', filter_col='filter', **kwargs)

Bases: BaseMetric

Find the time at which we expect to hit incremental template availability.

Note that there are some complications to real template generation that make this an approximation and not an exact answer – one aspect is that templates are generated in patches and not per pixel. However, it may be possible to generate parts of these patches at about 5 arcsecond scales, which implies running with a healpix slicer at nside=512 or 1024.

Parameters:

• n_images_in_template (int, opt) – Number of qualified visits required for template generation. Default 3.

• seeing_percentile (float, opt) –

  Maximum percentile seeing to allow in the qualified images (0 - 100).

  Default 50.

• m5_percentile (float, opt) –

  Maximum percentile m5 to allow in the qualified images (0 - 100).

  Default 50.

• seeing_col (str, opt) – Name of the seeing column to use.

• m5_col (str, opt) – Name of the five sigma depth columns.

• night_col (str, opt) – Name of the column describing the night of the visit.

• mjd_col (str, opt) – Name of column describing time of the visit

• filter_col (str, opt) – Name of column describing filter

run(data_slice, slice_point=None)

Calculate metric values.

Parameters:

• data_slice (numpy.ndarray, (N,)) – Values passed to metric by the slicer, which the metric will use to calculate metric values at each slice_point.

• slice_point (dict or None) – Dictionary of slice_point metadata passed to each metric. E.g. the ra/dec of the healpix pixel.

Returns:

metricValue – The metric value at each slice_point.

Return type:

int float or object

class rubin_sim.maf.metrics.TgapsMetric(times_col='observationStartMJD', all_gaps=False, bins=array([0., 0.00347222, 0.00694444, 0.01041667, 0.01388889, 0.01736111, 0.02083333, 0.02430556, 0.02777778, 0.03125, 0.03472222, 0.03819444, 0.04166667, 0.04513889, 0.04861111, 0.05208333, 0.05555556, 0.05902778, 0.0625, 0.06597222, 0.06944444, 0.07291667, 0.07638889, 0.07986111]), units='days', **kwargs)

Bases: BaseMetric

Histogram the times of the gaps between observations.

Measure the gaps between observations. By default, only gaps between neighboring visits are computed. If all_gaps is set to true, all gaps are computed (i.e., if there are observations at 10, 20, 30 and 40 the default will return a histogram of [10,10,10] while all_gaps returns a histogram of [10,10,10,20,20,30])

Parameters:

• times_col (str, optional) – The column name for the exposure times. Values assumed to be in days. Default observationStartMJD.

• all_gaps (bool, optional) – Histogram the gaps between all observations (True) or just successive observations (False)? Default is False. If all gaps are used, this metric can become significantly slower.

• bins (np.ndarray, optional) – The bins to use for the histogram of time gaps (in days, or same units as times_col). Default values are bins from 0 to 2 hours, in 5 minute intervals.

Returns:

histogram – Returns a histogram of the tgaps at each slice point; these histograms can be combined and plotted using the ‘SummaryHistogram plotter’.

Return type:

np.ndarray

run(data_slice, slice_point=None)

Calculate metric values.

Parameters:

• data_slice (numpy.ndarray, (N,)) – Values passed to metric by the slicer, which the metric will use to calculate metric values at each slice_point.

• slice_point (dict or None) – Dictionary of slice_point metadata passed to each metric. E.g. the ra/dec of the healpix pixel.

Returns:

metricValue – The metric value at each slice_point.

Return type:

int float or object

class rubin_sim.maf.metrics.TgapsPercentMetric(times_col='observationStartMJD', all_gaps=False, min_time=0.08333333333333333, max_time=0.5833333333333334, units='percent', **kwargs)

Bases: BaseMetric

Compute the fraction of the time gaps between observations that occur in a given time range.

Measure the gaps between observations. By default, only gaps between neighboring visits are computed. If all_gaps is set to true, all gaps are computed (i.e., if there are observations at 10, 20, 30 and 40 the default will compute the percent of gaps between specified endpoints.

This is different from the TgapsMetric in that this only looks at what percent of intervals fall into the specified range, rather than histogramming the entire set of tgaps.

This metric has drawbacks in that the result is tied to the overall number of tgaps (i.e. a result of 100 could still be worse than a different simulation with a result of 50, in terms of how often a particular Tgap is sampled).

Parameters:

• times_col (str, opt) – The column name for the exposure times. Values assumed to be in days. Default observationStartMJD.

• all_gaps (bool, opt) – Histogram the gaps between all observations (True) or just successive observations (False)? Default is False. If all gaps are used, this metric can become significantly slower.

• min_time (float, opt) – Minimum time of gaps to include (days). Default 2/24 (2 hours).

• max_time (float, opt) – Max time of gaps to include (days). Default 14/24 (14 hours).

Returns:

percent – Returns a float percent of the CDF between cdfMinTime and cdfMaxTime - (# of tgaps within min_time/max_time / # of all tgaps).

Return type:

float

run(data_slice, slice_point=None)

Calculate metric values.

Parameters:

• data_slice (numpy.ndarray, (N,)) – Values passed to metric by the slicer, which the metric will use to calculate metric values at each slice_point.

• slice_point (dict or None) – Dictionary of slice_point metadata passed to each metric. E.g. the ra/dec of the healpix pixel.

Returns:

metricValue – The metric value at each slice_point.

Return type:

int float or object

class rubin_sim.maf.metrics.TotalNumberSSO(h_mark=22, dndh_func=<function neo_dndh_granvik>, **kwargs)

Bases: BaseMoMetric

Calculate the total number of objects of a given population expected at a given H value or larger.

Operations on differential completeness values (or equivalent; fractions of the population is ok if still a differential metric result, not cumulative).

Parameters:

• h_mark (float, optional) – The H value at which to calculate the expected total number of objects.

• dndh_func (function, optional) – The dN/dH distribution used calculate the expected population size.

Returns:

nObj – The predicted number of objects in the population.

Return type:

float

run(metric_vals, h_vals)

Calculate the metric value.

Parameters:

• sso_obs (np.ndarray, (N,)) – The input data to the metric (same as the parent metric).

• orb (np.ndarray, (N,)) – The information about the orbit for which the metric is being calculated.

• hval (float) – The H value for which the metric is being calculated.

Returns:

metric_val

Return type:

float or np.ndarray or dict

class rubin_sim.maf.metrics.TotalPowerMetric(col='metricdata', lmin=100.0, lmax=300.0, remove_dipole=True, mask_val=nan, **kwargs)

Bases: BaseMetric

Calculate the total power in the angular power spectrum between lmin/lmax.

run(data_slice, slice_point=None)

Calculate metric values.

Parameters:

• data_slice (numpy.ndarray, (N,)) – Values passed to metric by the slicer, which the metric will use to calculate metric values at each slice_point.

• slice_point (dict or None) – Dictionary of slice_point metadata passed to each metric. E.g. the ra/dec of the healpix pixel.

Returns:

metricValue – The metric value at each slice_point.

Return type:

int float or object

class rubin_sim.maf.metrics.TransientMetric(metric_name='TransientDetectMetric', mjd_col='observationStartMJD', m5_col='fiveSigmaDepth', filter_col='filter', trans_duration=10.0, peak_time=5.0, rise_slope=0.0, decline_slope=0.0, survey_duration=10.0, survey_start=None, detect_m5_plus=0.0, u_peak=20, g_peak=20, r_peak=20, i_peak=20, z_peak=20, y_peak=20, n_pre_peak=0, n_per_lc=1, n_filters=1, n_phase_check=1, count_method='full', **kwargs)

Bases: BaseMetric

Calculate what fraction of the transients would be detected. Best paired with a spatial slicer. We are assuming simple light curves with no color evolution.

Parameters:

• trans_duration (float, optional) – How long the transient lasts (days). Default 10.

• peak_time (float, optional) – How long it takes to reach the peak magnitude (days). Default 5.

• rise_slope (float, optional) – Slope of the light curve before peak time (mags/day). This should be negative since mags are backwards (magnitudes decrease towards brighter fluxes). Default 0.

• decline_slope (float, optional) – Slope of the light curve after peak time (mags/day). This should be positive since mags are backwards. Default 0.

• uPeak (float, optional) – Peak magnitude in u band. Default 20.

• gPeak (float, optional) – Peak magnitude in g band. Default 20.

• rPeak (float, optional) – Peak magnitude in r band. Default 20.

• iPeak (float, optional) – Peak magnitude in i band. Default 20.

• zPeak (float, optional) – Peak magnitude in z band. Default 20.

• yPeak (float, optional) – Peak magnitude in y band. Default 20.

• survey_duration (float, optional) – Length of survey (years). Default 10.

• survey_start (float, optional) – MJD for the survey start date. Default None (uses the time of the first observation).

• detect_m5_plus (float, optional) – An observation will be used if the light curve magnitude is brighter than m5+detect_m5_plus. Default 0.

• n_pre_peak (int, optional) – Number of observations (in any filter(s)) to demand before peak_time, before saying a transient has been detected. Default 0.

• n_per_lc (int, optional) – Number of sections of the light curve that must be sampled above the detect_m5_plus theshold (in a single filter) for the light curve to be counted. For example, setting n_per_lc = 2 means a light curve is only considered detected if there is at least 1 observation in the first half of the LC, and at least one in the second half of the LC. n_per_lc = 4 means each quarter of the light curve must be detected to count. Default 1.

• n_filters (int, optional) – Number of filters that need to be observed for an object to be counted as detected. Default 1.

• n_phase_check (int, optional) – Sets the number of phases that should be checked. One can imagine pathological cadences where many objects pass the detection criteria, but would not if the observations were offset by a phase-shift. Default 1.

• count_method ({'full' 'partialLC'}, defaults to 'full') – Sets the method of counting max number of transients. if ‘full’, the only full light curves that fit the survey duration are counted. If ‘partialLC’, then the max number of possible transients is taken to be the integer floor

light_curve(time, filters)

Calculate the magnitude of the object at each time, in each filter.

Parameters:

• time (numpy.ndarray) – The times of the observations.

• filters (numpy.ndarray) – The filters of the observations.

Returns:

The magnitudes of the object at each time, in each filter.

Return type:

numpy.ndarray

run(data_slice, slice_point=None)

” Calculate the detectability of a transient with the specified lightcurve.

Parameters:

• data_slice (numpy.array) – Numpy structured array containing the data related to the visits provided by the slicer.

• slice_point (dict, optional) – Dictionary containing information about the slice_point currently active in the slicer.

Returns:

The total number of transients that could be detected.

Return type:

float

class rubin_sim.maf.metrics.UniformityMetric(mjd_col='observationStartMJD', units='', survey_length=10.0, **kwargs)

Bases: BaseMetric

Calculate how uniformly the observations are spaced in time.

This is based on how a KS-test works: look at the cumulative distribution of observation dates, and compare to a perfectly uniform cumulative distribution. Perfectly uniform observations = 0, perfectly non-uniform = 1.

Parameters:

• mjd_col (str, optional) – The column containing time for each observation. Default “observationStartMJD”.

• survey_length (float, optional) – The overall duration of the survey. Default 10.

run(data_slice, slice_point=None)

Calculate metric values.

Parameters:

• data_slice (numpy.ndarray, (N,)) – Values passed to metric by the slicer, which the metric will use to calculate metric values at each slice_point.

• slice_point (dict or None) – Dictionary of slice_point metadata passed to each metric. E.g. the ra/dec of the healpix pixel.

Returns:

metricValue – The metric value at each slice_point.

Return type:

int float or object

class rubin_sim.maf.metrics.UniqueRatioMetric(col=None, metric_name=None, maps=None, units=None, metric_dtype=None, badval=-666, mask_val=None)

Bases: BaseMetric

Return the number of unique values divided by the total number of values.

run(data_slice, slice_point=None)

Calculate metric values.

Parameters:

• data_slice (numpy.ndarray, (N,)) – Values passed to metric by the slicer, which the metric will use to calculate metric values at each slice_point.

• slice_point (dict or None) – Dictionary of slice_point metadata passed to each metric. E.g. the ra/dec of the healpix pixel.

Returns:

metricValue – The metric value at each slice_point.

Return type:

int float or object

class rubin_sim.maf.metrics.UseMetric(note_col='scheduler_note', **kwargs)

Bases: BaseMetric

Metric to classify visits by type of visits

run(data_slice, slice_point=None)

Run the metric.

Parameters:

• data_slice (np.ndarray, (N,)`)

• slice_point (dict) – Dictionary of slice_point metadata passed to each metric. E.g. the ra/dec of the healpix pixel.

Returns:

use_name – use at each slice_point.

Return type:

str

class rubin_sim.maf.metrics.ValueAtHMetric(h_mark=22, **kwargs)

Bases: BaseMoMetric

Return the metric value at a given H value.

Requires the metric values to be one-dimensional (typically, completeness values).

Parameters:

h_mark (float, optional) – The H value at which to look up the metric value.

Returns:

value

Return type:

: float

run(metric_vals, h_vals)

Calculate the metric value.

Parameters:

• sso_obs (np.ndarray, (N,)) – The input data to the metric (same as the parent metric).

• orb (np.ndarray, (N,)) – The information about the orbit for which the metric is being calculated.

• hval (float) – The H value for which the metric is being calculated.

Returns:

metric_val

Return type:

float or np.ndarray or dict

class rubin_sim.maf.metrics.VisitGapMetric(mjd_col='observationStartMJD', night_col='night', reduce_func=<function median>, metric_name='VisitGap', **kwargs)

Bases: BaseMetric

Calculate the (reduce_func) of the gap between any consecutive observations, in hours, regardless of night boundaries.

Different from inter-night and intra-night gaps, because this is really just counting all of the times between consecutive observations (not time between nights or time within a night).

Parameters:

reduce_func (function, optional) – Function that can operate on array-like structures. Typically numpy function. Default np.median.

run(data_slice, slice_point=None)

Calculate metric values.

Parameters:

• data_slice (numpy.ndarray, (N,)) – Values passed to metric by the slicer, which the metric will use to calculate metric values at each slice_point.

• slice_point (dict or None) – Dictionary of slice_point metadata passed to each metric. E.g. the ra/dec of the healpix pixel.

Returns:

metricValue – The metric value at each slice_point.

Return type:

int float or object

class rubin_sim.maf.metrics.VisitGroupsMetric(time_col='observationStartMJD', nights_col='night', metric_name='VisitGroups', delta_t_min=0.010416666666666666, delta_t_max=0.0625, min_n_visits=2, window=30, min_n_nights=3, **kwargs)

Bases: BaseMetric

Count the number of visits per night within delta_t_min and delta_t_max.

reduce_max_seq_lunations(metricval)

Count the max number of sequential lunations (unique 30 day windows) that contain at least one ‘group’: a set of more than minNVisits per night, with more than minNNights of visits within ‘window’ time period.

reduce_median(metricval)

Reduce to median number of visits per night.

reduce_n_lunations(metricval)

Reduce to number of lunations (unique 30 day windows) that contain at least one ‘group’: a set of more than minNVisits per night, with more than minNNights of visits within ‘window’ time period.

reduce_n_nights_in_window(metricval)

Reduce to max number of nights with more than minNVisits, within ‘window’ over all windows.

reduce_n_nights_with_n_visits(metricval)

Reduce to total number of nights with more than ‘minNVisits’ visits.

reduce_n_visits_in_window(metricval)

Reduce to max number of total visits on all nights with more than minNVisits, within any ‘window’ (default=30 nights).

run(data_slice, slice_point=None)

Return a dictionary of: the number of visits within a night (within delta tmin/tmax of another visit), and the nights with visits > minNVisits. Count two visits which are within tmin of each other, but which have another visit within tmin/tmax interval, as one and a half (instead of two).

So for example: 4 visits, where 1, 2, 3 were all within deltaTMax of each other, and 4 was later but within deltaTmax of visit 3 – would give you 4 visits. If visit 1 and 2 were closer together than deltaTmin, the two would be counted as 1.5 visits together (if only 1 and 2 existed, then there would be 0 visits as none would be within the qualifying time interval).

class rubin_sim.maf.metrics.VolumeSumMetric(col=None, metric_name='VolumeSum', nside=None, **kwargs)

Bases: BaseMetric

Compute the total volume assuming a metric has values of distance.

run(data_slice, slice_point=None)

Calculate metric values.

Parameters:

• data_slice (numpy.ndarray, (N,)) – Values passed to metric by the slicer, which the metric will use to calculate metric values at each slice_point.

• slice_point (dict or None) – Dictionary of slice_point metadata passed to each metric. E.g. the ra/dec of the healpix pixel.

Returns:

metricValue – The metric value at each slice_point.

Return type:

int float or object

class rubin_sim.maf.metrics.WeakLensingNvisits(m5_col='fiveSigmaDepth', exp_time_col='visitExposureTime', filter_col='filter', lsst_filter='i', depth_cut=24.5, ebvlim=0.2, min_exp_time=15, **kwargs)

Bases: BaseMetric

A proxy metric for WL systematics. Higher values indicate better systematics mitigation.

Weak Lensing systematics metric : Computes the average number of visits per point on a HEALPix grid after a maximum E(B-V) cut and a minimum co-added depth cut. Intended to be used to count visits in gri, but can be any filter combination as long as it includes lsst_filter band visits.

run(data_slice, slice_point)

Calculate metric values.

Parameters:

• data_slice (numpy.ndarray, (N,)) – Values passed to metric by the slicer, which the metric will use to calculate metric values at each slice_point.

• slice_point (dict or None) – Dictionary of slice_point metadata passed to each metric. E.g. the ra/dec of the healpix pixel.

Returns:

metricValue – The metric value at each slice_point.

Return type:

int float or object

class rubin_sim.maf.metrics.YearCoverageMetric(night_col='night', bins=None, units=None, **kwargs)

Bases: 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 – Number of histogram bins where the histogram value is greater than 0. Typically this will be the number of years in the ‘night_col’.

Return type:

int

run(data_slice, slice_point)

Calculate metric values.

Parameters:

• data_slice (numpy.ndarray, (N,)) – Values passed to metric by the slicer, which the metric will use to calculate metric values at each slice_point.

• slice_point (dict or None) – Dictionary of slice_point metadata passed to each metric. E.g. the ra/dec of the healpix pixel.

Returns:

metricValue – The metric value at each slice_point.

Return type:

int float or object

class rubin_sim.maf.metrics.ZeropointMetric(col='metricdata', zp=0, **kwargs)

Bases: BaseMetric

Return a metric values with the addition of ‘zp’. Useful for altering the zeropoint for summary statistics.

run(data_slice, slice_point=None)

Calculate metric values.

Parameters:

• data_slice (numpy.ndarray, (N,)) – Values passed to metric by the slicer, which the metric will use to calculate metric values at each slice_point.

• slice_point (dict or None) – Dictionary of slice_point metadata passed to each metric. E.g. the ra/dec of the healpix pixel.

Returns:

metricValue – The metric value at each slice_point.

Return type:

int float or object

rubin_sim.maf.metrics.find_season_edges(seasons)

Given the seasons, return the indexes of each start/end of the season.

Parameters:

seasons (np.ndarray, (N,)) – Seasons, such as calculated by calc_season. Note that seasons should be sorted!!

Returns:

first, last – The indexes of the first and last date in the season.

Return type:

np.ndarray, (N,), np.ndarray, (N,)

rubin_sim.maf.metrics.galplane_nvisits_thresholds(tau_obs, nyears=10)

Return estimated nvisits required to well-sample lightcurves that need sampling every tau_obs (days).

This does a very basic estimate, just counting how many visits you would have if you distributed them at tau_obs intervals for a period of nyears, assuming a season length of 6.5 years and that visits in each night are in pairs.

Parameters:

• tau_obs (np.ndarray or list of float) – Timescale that variability must be sampled at, in days.

• nyears (float, opt) – Number of years in the survey (as sampled). Default 10.

Returns:

n_visits_thresholds – Estimated number of visits required to well sample lightcurves which require sampling on tau_obs

Return type:

np.ndarray

rubin_sim.maf.metrics.galplane_priority_map_thresholds(science_map)

Return minimum threshold for priority maps, when considering filter balance.

Parameters:

science_map (str) – The name of the science map in the galactic plane priority map.

Returns:

priority_threshold – The minimum threshold to consider from the priority map

Return type:

float

rubin_sim.maf.metrics.integrate_over_h(metric_values, hvalues, dndh_func=<function power_law_dndh>, **kwargs)

Calculate a metric value integrated over an h_range. This is the metric value weighted by the size distribution.

Parameters:

• metric_values (numpy.ndarray) – The metric values at each H value.

• hvalues (numpy.ndarray) – The H values corresponding to each metric_value (must be the same length).

• dndh_func (function, optional) – One of the dN/dH functions defined below.

• **kwargs (dict, optional) – Keyword arguments to pass to dndh_func

Returns:

int_vals – The integrated metric values.

Return type:

np.ndarray, (N,)

rubin_sim.maf.metrics.power_law_dndh(hvalues, hindex=0.33, no=None, ho=None, **kwargs)

Power law distribution of objects.

Parameters:

• hvalues (np.ndarray, (N,)) – The H values corresponding to each metric_value (must be the same length). The hvalues are expected to be evenly spaced.

• hindex (float, optional) – The power-law index expected for the H value distribution. Default is 0.33 (dN/dH = 10^(hindex * H) ).

• no (float, optional)

• ho (float, optional) – If no and ho are specified, this provides an anchor for the power law distribution,so that the expected number no of objects at ho is returned. Does not need to be set if just doing comparative weighting.

Returns:

dndh

Return type:

np.ndarray, (N,)

rubin_sim.maf.metrics.sum_over_h(metric_values, hvalues, dndh_func=<function power_law_dndh>, **kwargs)

Calculate the sum of the metric value multiplied by the number of objects at each H value. This is equivalent to calculating the number of objects meeting X requirement in the differential completeness or fraction of objects with lightcurves, etc.

Parameters:

• metric_values (np.ndarray, (N,)) – The metric values at each H value.

• hvalues (np.ndarray, (N,)) – The H values corresponding to each metric_value.

• dndh_func (function, optional) – One of the dN/dH functions defined below.

• **kwargs (dict, optional) – Keyword arguments to pass to dndh_func

Returns:

sum_vals – The cumulative metric values.

Return type:

np.ndarray, (N,)