Metric

class lsst.validate.base.Metric(name, description, operator_str, specs=None, parameters=None, reference_doc=None, reference_url=None, reference_page=None)[source]

Bases: lsst.validate.base.jsonmixin.JsonSerializationMixin

Container for the definition of a metric and its specification levels.

Metrics can either be instantiated programatically, or from a metric YAML file with the from_yaml class method.

See also

See the Using metrics and specifications in Python page for usage details.

Parameters:

name : str

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

description : str

Short description about the metric.

operator_str : str

A string, such as '<=', that defines a success test for a measurement (on the left hand side) against the metric specification level (right hand side).

specs : list, optional

A list of Specification objects that define various specification levels for this metric.

parameters : dict, optional

A dict of named Datum values that must be known when measuring a metric.

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
name Name of the metric (str).
operator Binary comparision operator that tests success of a measurement fulfilling a specification of this metric.
operator_str String representation of comparison operator.
parameters dict of named Datum values that must be known when measuring
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).

Methods Summary

check_spec(quantity, spec_name[, filter_name]) Compare a measurement against a named specification level.
convert_operator_str(op_str) Convert a string representing a binary comparison operator to the operator function itself.
from_json(json_data) Construct a Metric from a JSON dataset.
from_yaml(metric_name[, yaml_doc, ...]) Create a Metric instance from a YAML document that defines metrics.
get_spec(name[, filter_name]) Get a specification by name and other qualifications.
get_spec_dependency(spec_name, dep_name[, ...]) Get the Datum of a specification’s dependency.
get_spec_names([filter_name]) List names of all specification levels defined for this metric; optionally filtering by attributes such as filter name.
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 = None

Name of the metric (str).

operator

Binary comparision operator that tests success of a measurement fulfilling a specification of this metric.

Measured value is on left side of comparison and specification level is on right side.

operator_str

String representation of comparison operator.

The comparison is oriented with the measurement on the left-hand side and the specification level on the right-hand side.

parameters = {}

dict of named Datum values that must be known when measuring a metric.

Parameters can also be accessed as attributes of the metric. Attribute names are the same as key names in parameters.

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

Methods Documentation

check_spec(quantity, spec_name, filter_name=None)[source]

Compare a measurement against a named specification level.

Parameters:

value : astropy.units.Quantity

The measurement value.

spec_name : str

Name of a Specification associated with this metric.

filter_name : str, optional

Name of the applicable filter, if needed.
Returns:

passed : bool

True if the value meets the specification, False otherwise.
static convert_operator_str(op_str)[source]

Convert a string representing a binary comparison operator to the operator function itself.

Operators are oriented so that the measurement is on the left-hand side, and specification level on the right hand side.

The following operators are permitted:

op_str Function
>= operator.ge
> operator.gt
< operator.lt
<= operator.le
== operator.eq
!= operator.ne
Parameters:

op_str : str

A string representing a binary operator.
Returns:

op_func : obj

An operator function from the operator standard library module.
classmethod from_json(json_data)[source]

Construct a Metric from a JSON dataset.

Parameters:

json_data : dict

Metric JSON object.
Returns:

metric : Metric

Metric from JSON.
classmethod from_yaml(metric_name, yaml_doc=None, yaml_path=None, resolve_dependencies=True)[source]

Create a Metric instance from a YAML document that defines metrics.

See also

See Defining metrics and specifications in YAML for details on the metric YAML schema.

Parameters:

metric_name : str

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

yaml_doc : dict, optional

A full metric YAML document loaded as a dict. Use this option to increase performance by eliminating redundant reads of a common metric YAML file. Alternatively, set yaml_path.

yaml_path : str, optional

The full file path to a metric YAML file. Alternatively, set yaml_doc.

resolve_dependencies : bool, optional

API users should always set this to True. The opposite is used only used internally.
Raises:

RuntimeError

Raised when neither yaml_doc or yaml_path are set.
get_spec(name, filter_name=None)[source]

Get a specification by name and other qualifications.

Parameters:

name : str

Name of a specification level (e.g., 'design', 'minimum', 'stretch').

filter_name : str, optional

The name of the optical filter to qualify a filter-dependent specification level.
Returns:

spec : Specification

The Specification that matches the name and other qualifications.
Raises:

RuntimeError

If a specification cannot be found.
get_spec_dependency(spec_name, dep_name, filter_name=None)[source]

Get the Datum of a specification’s dependency.

If the dependency is a metric, this method resolves the value of the dependent metric’s specification level spec_name. In other words, spec_name refers to the specification level of both this metric and of the dependency metric.

Parameters:

spec_name : str

dep_name : str

Name of the dependency.

filter_name : str, optional

Name of the optical filter, if this metric’s specifications are optical filter dependent.
Returns:

datum : Datum

The dependency resolved for the metric’s specification.
get_spec_names(filter_name=None)[source]

List names of all specification levels defined for this metric; optionally filtering by attributes such as filter name.

Parameters:

filter_name : str, optional

Name of the applicable filter, if needed.
Returns:

spec_names : list

Specification names as a list of strings, e.g. ['design', 'minimum', 'stretch'].
jsonify_dict(d)

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

Parameters:

d : dict

Dictionary ito 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.