Metric¶

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

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 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: 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. 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. 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. 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 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. 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. The Specification that matches the name and other qualifications. 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. 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. 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: Dictionary ito convert into a JSON-serializable object. Values are recursively JSON-ified. 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.