ThresholdSpecification

class lsst.verify.ThresholdSpecification(name, threshold, operator_str, **kwargs)[source]

Bases: lsst.verify.Specification

A threshold-type specification, associated with a Metric, that defines a binary comparison against a measurement.

Parameters:

name : str

Name of the specification for a metric. LPM-17, for example, uses 'design', 'minimum' and 'stretch' terminology.

quantity : astropy.units.Quantity

The specification threshold level.

operator_str : str

The threshold’s binary comparison operator. The operator is oriented so that measurement {{ operator }} threshold quantity is the specification test. Can be one of: '<', '<=', '>', '>=', '==', or '!='.

metadata_query : dict, optional

Dictionary of key-value terms that the measurement’s metadata must have for this specification to apply.

tags : sequence of str, optional

Sequence of tags that group this specification with others.

kwargs : dict

Keyword arguments passed directly to the lsst.validate.base.Specification constructor.
Raises:

TypeError

If name is not compartible with Name, or threshold is not a Quantity, or if the operator_str cannot be converted into a Python binary comparison operator.

Attributes Summary

datum Representation of this ThresholdSpecification‘s threshold as a Datum.
json dict that can be serialized as semantic JSON, compatible with
metric_name Name of the metric this specification corresponds to (lsst.verify.Name).
name Specification name (lsst.verify.Name).
operator Binary comparision operator that tests success of a measurement fulfilling a specification of this metric.
operator_str Threshold comparision operator (‘str’).
tags Tag labels (set of str).
threshold The specification threshold level (astropy.units.Quantity).
type

Methods Summary

check(measurement) Check if a measurement passes this specification.
convert_operator_str(op_str) Convert a string representing a binary comparison operator to the operator function itself.
deserialize([name, threshold, metric, package]) Deserialize from keys in a specification YAML document or a JSON serialization into a ThresholdSpecification instance.
jsonify_dict(d) Recursively build JSON-renderable objects on all values in a dict.
query_metadata(metadata) Query a Job’s metadata to determine if this specification applies.
write_json(filepath) Write JSON to a file.

Attributes Documentation

datum

Representation of this ThresholdSpecification‘s threshold as a Datum.

json

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

metric_name

Name of the metric this specification corresponds to (lsst.verify.Name).

name

Specification name (lsst.verify.Name).

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

Threshold comparision operator (‘str’).

A measurement passes the specification if:

measurement {{ operator }} threshold == True

The operator string is a standard Python binary comparison token, such as: '<', '>', '<=', '>=', '==' or '!='.

tags

Tag labels (set of str).

threshold = None

The specification threshold level (astropy.units.Quantity).

type

Methods Documentation

check(measurement)[source]

Check if a measurement passes this specification.

Parameters:

measurement : astropy.units.Quantity

The measurement value. The measurement Quantity must have units compatible with threshold.
Returns:

passed : bool

True if the measurement meets the specification, False otherwise.
Raises:

astropy.units.UnitError

Raised if the measurement cannot be compared to the threshold. For example, if the measurement is not an astropy.units.Quantity or if the units are not compatible.
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 threshold 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.
Raises:

ValueError

Raised if op_str is not a supported binary comparison operator.
classmethod deserialize(name=None, threshold=None, metric=None, package=None, **kwargs)[source]

Deserialize from keys in a specification YAML document or a JSON serialization into a ThresholdSpecification instance.

Parameters:

name : str or lsst.validate.base.Name

Specification name, either as a string or Name.

threshold : dict

A dict with fields:

  • 'value': threshold value (float or int).
  • 'unit': threshold unit, as an astropy.units.Unit- compatible str.
  • 'operator': a binary comparison operator, described in the class parameters documentation (str).

metric : str or lsst.validate.base.Name, optional

Name of the fully-qualified name of the metric the specification corresponds to. This parameter is optional if name is already fully-qualified.

package : str or lsst.validate.base.Name, optional

Name of the package the specification corresponds to. This parameter is optional if name or metric are already fully-qualified.

kwargs : dict

Keyword arguments passed directly to the lsst.validate.base.Specification constructor.
Returns:

specification : ThresholdSpecification

A specification instance.
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,
    })
query_metadata(metadata)

Query a Job’s metadata to determine if this specification applies.

Parameters:

metadata : lsst.verify.Metadata or dict-type

Metadata mapping. Typically this is the lsst.verify.Job.meta attribute.
Returns:

applies : bool

True if this specification applies to a Job’s measurement, or False otherwise.
write_json(filepath)

Write JSON to a file.

Parameters:

filepath : str

Destination file name for JSON output.