Measurement

class lsst.verify.Measurement(metric, quantity=None, blobs=None, extras=None, notes=None)

Bases: lsst.verify.jsonmixin.JsonSerializationMixin

A measurement of a single Metric.

A measurement is associated with a single Metric and consists of a astropy.units.Quantity value. In addition, a measurement can be augmented with Blobs (either shared, or directly associated with the measurement’s Measurement.extras) and metadata (Measurement.notes).

Parameters:

metric : str, lsst.verify.Name, or lsst.verify.Metric

The name of this metric or the corresponding Metric instance. If a Metric is provided then the units of the quantity argument are automatically validated.

quantity : astropy.units.Quantity, optional

The measured value as an Astropy Quantity. If a Metric instance is provided, the units of quantity are compared to the Metric‘s units for compatibility. The quantity can also be set, updated, or read with the Measurement.quantity attribute.

blobs : list of Blobs, optional

List of lsst.verify.Blob instances that are associated with a measurement. Blobs are datasets that can be associated with many measurements and provide context to a measurement.

extras : dict of lsst.verify.Datum instances, optional

Datum instances can be attached to a measurement. Extras can be accessed from the Measurement.extras attribute.

notes : dict, optional

Measurement annotations. These key-value pairs are automatically available from Job.meta, though keys are prefixed with the metric’s name. This metadata can be queried by specifications, so that specifications can be written to test only certain types of measurements.

Raises:

TypeError

Raised if arguments are not valid types.

Attributes Summary

blobs	dict of lsst.verify.Blobs associated with this measurement.
datum	Representation of this measurement as a Datum.
description	Description of the metric (str, or None if Measurement.metric is not set).
extras	Blob associated solely to this measurement.
identifier	Unique UUID4-based identifier for this measurement (str, immutable).
json	A dict that can be serialized as semantic SQUASH JSON.
metric	Metric associated with the measurement (lsst.verify.Metric or None, mutable).
metric_name	Name of the corresponding metric (lsst.verify.Name, mutable).
notes	Measurement annotations as key-value pairs (dict).
quantity	astropy.units.Quantity component of the measurement (mutable).

Methods Summary

deserialize([metric, identifier, value, ...])	Create a Measurement instance from a parsed YAML/JSON document.
jsonify_dict(d)	Recursively build JSON-renderable objects on all values in a dict.
link_blob(blob)	Link a Blob to this measurement.
write_json(filepath)	Write JSON to a file.

Attributes Documentation

blobs = None

dict of lsst.verify.Blobs associated with this measurement.

See also

Measurement.link_blob

datum

Representation of this measurement as a Datum.

description

Description of the metric (str, or None if Measurement.metric is not set).

extras = None

Blob associated solely to this measurement.

Notes

extras work just like Blobs, but they’re automatically created with each Measurement. Add Datums to extras if those Datums only make sense in the context of that Measurement. If Datums are relevant to multiple measurements, add them to an external Blob instance and attach them to each measurements’s Measurement.blobs attribute through the Measurement.link_blob method.

identifier

Unique UUID4-based identifier for this measurement (str, immutable).

json

A dict that can be serialized as semantic SQUASH JSON.

Fields:

• metric (str) Name of the metric the measurement measures.
• identifier (str) Unique identifier for this measurement.
• value (float) Value of the measurement.
• unit (str) Units of the value, as an astropy.units-compatible string.
• blob_refs (list of str) List of Blob.identifiers for Blobs associated with this measurement.

Note

Blobs are not serialized with a measurement, only their identifiers. The lsst.verify.Job class handles serialization of blobs alongside measurements.

Likewise, Measurement.notes are not serialized with the measurement. They are included with lsst.verify.Job‘s serialization, alongside job-level metadata.

metric

Metric associated with the measurement (lsst.verify.Metric or None, mutable).

metric_name

Name of the corresponding metric (lsst.verify.Name, mutable).

notes

Measurement annotations as key-value pairs (dict).

These key-value pairs are automatically available from Job.meta, though keys are prefixed with the Metric‘s name. This metadata can be queried by Specifications, so that Specifications can be written to test only certain types of Measurements.

quantity

astropy.units.Quantity component of the measurement (mutable).

Methods Documentation

classmethod deserialize(metric=None, identifier=None, value=None, unit=None, blob_refs=None, blobs=None, **kwargs)

Create a Measurement instance from a parsed YAML/JSON document.

Parameters:

metric : str

Name of the metric the measurement measures.

identifier : str

Unique identifier for this measurement.

value : float

Value of the measurement.

unit : str

Units of the value, as an astropy.units-compatible string.

blob_refs : list of str

List of Blob.identifiers for Blob associated with this measurement.

blobs : BlobSet

BlobSet containing all Blobs referenced by the measurement’s blob_refs field. Note that the BlobSet must be created separately, prior to deserializing measurement objects.

Returns:

measurement : Measurement

Measurement 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,
    })

link_blob(blob)

Link a Blob to this measurement.

Blobs can be linked to a measurement so that they can be retrieved by analysis and visualization tools post-serialization. Blob data is not copied, and one blob can be linked to multiple measurements.

Parameters:

blob : lsst.verify.Blob

A Blob instance.

Notes

After linking, the Blob instance can be accessed by name (Blob.name) through the Measurement.blobs dict.

write_json(filepath)

Write JSON to a file.

Parameters:

filepath : str

Destination file name for JSON output.