Using metrics and specifications in Python

Metrics and their specifications are typically defined in YAML files. This page describes how to work with those metrics and specifications within Python using the lsst.validate.base.Metric and lsst.validate.base.Specification classes.

See also

Defining metrics and specifications in YAML.

Creating Metric objects in Python

A Metric object is typically built from a YAML definition with the Metric.from_yaml class method. Metric.from_yaml takes the metric name and either the path of a metric YAML file (yaml_path keyword argument) or a pre-parsed YAML object (yaml_doc keyword argument).

For example:

import os
import astropy.units as u
from lsst.utils import getPackageDir
from lsst.validate.base import Metric
yaml_path = os.path.join(getPackageDir('validate_drp'),
                         'metrics.yaml')
am1 = Metric.from_yaml('AM1', yaml_path=yaml_path)

See also

To create Metric instances from all metrics in a YAML file, use the load_metrics function.

Checking a measurement against a Specification

A Metric object is useful for validating a measurement against a specification. For this, use the Metric.check_spec method:

measured_value = 2. * u.arcmin  # hypothetical measured value
am1.check_spec(measured_value, 'design')

The last statement returns True if the measured value fulfills the ‘design’ specification. If a specification is filter-dependent, the filter’s name needs to be passed to the filter_name keyword argument of Metric.check_spec.

See Creating measurement classes for details on how to make measurements with the lsst.validate.base API.

Accessing Specification objects of a Metric

Since some measurements need to know about the specification levels of a Metric, Metrics provide a Metric.get_spec method to resolve and retrieve a Specification. For example:

design_spec = pf1.get_spec('design')

If specification levels are filter-dependent, the filter’s name can be provided with the filter_name keyword argument.

The properties of a specification are retrieved through attributes:

design_spec.quantity  # an astropy.units.Quantity
design_spec.unit  # an astropy.units.Unit
design_spec.label
design_spec.filter_names
design_spec.latex_unit  # units marked up as LaTeX math

Dependencies of specification levels can be obtained as attributes corresponding to their labels. Dependencies themselves are Datum objects, with a value and units. For example,

design_spec.PA2  # the PA2 dependency as a Datum
design_spec.PA2.quantity  # value of distance parameter
design_spec.PA2.unit  # units of the distance parameter

See Creating measurement classes for examples of measurements that retrieve dependencies of metrics and their specification levels.