Metric

class lsst.verify.Metric(name, description, unit, tags=None, reference_doc=None, reference_url=None, reference_page=None)

Bases: lsst.verify.jsonmixin.JsonSerializationMixin

Container for the definition of a metric.

Metrics can either be instantiated programatically, or from a metric YAML file through lsst.verify.MetricSet.

Parameters:
name : str

Name of the metric (e.g., 'PA1').

description : str

Short description about the metric.

unit : str or astropy.units.Unit

Units of the metric. Measurements of this metric must be in an equivalent (that is, convertable) unit. Argument can either be an astropy.unit.Unit instance, or a Unit-compatible string representation. Use an empty string, '', or astropy.units.dimensionless_unscaled for a unitless quantity.

tags : list of str

Tags associated with this metric. Tags are user-submitted string tokens that are used to group metrics.

reference_doc : str, optional

The document handle that originally defined the metric (e.g., 'LPM-17').

reference_url : str, optional

The document’s URL.

reference_page : str, optional

Page where metric in defined in the reference document.

Attributes Summary

description Short description of the metric (str).
json dict that can be serialized as semantic JSON, compatible with the SQUASH metric service.
name Metric’s name (Name).
reference Documentation reference as human-readable text (str, read-only).
reference_doc Name of the document that specifies this metric (str).
reference_page Page number in the document that specifies this metric (int).
reference_url URL of the document that specifies this metric (str).
tags Tag labels (set of str).
unit The metric’s unit (astropy.units.Unit).
unit_str The string representation of the metric’s unit (Unit-compatible str).

Methods Summary

check_unit(quantity) Check that a Quantity has equivalent units to this metric.
deserialize([name, description, unit, tags, …]) Create a Metric instance from a parsed YAML/JSON document.
jsonify_dict(d) Recursively build JSON-renderable objects on all values in a dict.
write_json(filepath) Write JSON to a file.

Attributes Documentation

description = None

Short description of the metric (str).

json

dict that can be serialized as semantic JSON, compatible with the SQUASH metric service.

name

Metric’s name (Name).

reference

Documentation reference as human-readable text (str, read-only).

Uses reference_doc, reference_page, and reference_url, as available.

reference_doc = None

Name of the document that specifies this metric (str).

reference_page = None

Page number in the document that specifies this metric (int).

reference_url = None

URL of the document that specifies this metric (str).

tags

Tag labels (set of str).

unit

The metric’s unit (astropy.units.Unit).

unit_str

The string representation of the metric’s unit (Unit-compatible str).

Methods Documentation

check_unit(quantity)

Check that a Quantity has equivalent units to this metric.

Parameters:
quantity : astropy.units.Quantity

Quantity to be tested.

Returns:
is_equivalent : bool

True if the units are equivalent, meaning that the quantity can be presented in the units of this metric. False if not.

classmethod deserialize(name=None, description=None, unit=None, tags=None, reference=None)

Create a Metric instance from a parsed YAML/JSON document.

Parameters:
kwargs : dict

Keyword arguments that match fields from the Metric.json serialization.

Returns:
metric : Metric

A Metric instance.

static jsonify_dict(d)

Recursively build JSON-renderable objects on all values in a dict.

Parameters:
d : dict

Dictionary to convert into a JSON-serializable object. Values are recursively JSON-ified.

Returns:
json_dict : dict

Dictionary that can be serialized to JSON.

Examples

Subclasses can use this method to prepare output in their json-method implementation. For example:

def json(self):
    return JsonSerializationMixin.jsonify_dict({
        'value': self.value,
    })
write_json(filepath)

Write JSON to a file.

Parameters:
filepath : str

Destination file name for JSON output.