Metric

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

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

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

descriptionstr

Short description about the metric.

unitstr 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.

tagslist of str

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

reference_docstr, optional

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

reference_urlstr, optional

The document’s URL.

reference_pagestr, 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:
quantityastropy.units.Quantity

Quantity to be tested.

Returns:
is_equivalentbool

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

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

Returns:
metricMetric

A Metric instance.

static jsonify_dict(d)

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

Parameters:
ddict

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

Returns:
json_dictdict

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

Destination file name for JSON output.