ThresholdSpecification

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

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[, arg_driven])	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)

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)

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)

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, arg_driven=False)

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.

arg_driven : bool, optional

If False (default), metadata matches the MetadataQuery if metadata has all the terms defined in MetadataQuery, and those terms match. If metadata has more terms than MetadataQuery, it can still match. This behavior is appropriate for finding if a specification applies to a Job given metadata.

If True, the orientation of the matching is reversed. Now metadata matches the MetadataQuery if MetadataQuery has all the terms defined in metadata and those terms match. If MetadataQuery has more terms than metadata, it can still match. This behavior is appropriate for discovering specifications.

Returns:

matched : bool

True if this specification matches, False otherwise.

See also

lsst.verify.MetadataQuery

write_json(filepath)

Write JSON to a file.

Parameters:

filepath : str

Destination file name for JSON output.