Coverage for python/lsst/verify/measurement.py : 91%

Hot-keys on this page
r m x p toggle line displays
j k next/prev highlighted chunk
0 (zero) top of page
1 (one) first highlighted chunk
# # LSST Data Management System # # This product includes software developed by the # LSST Project (http://www.lsst.org/). # # See COPYRIGHT file at the top of the source tree. # # This program is free software: you can redistribute it and/or modify # it under the terms of the GNU General Public License as published by # the Free Software Foundation, either version 3 of the License, or # (at your option) any later version. # # This program is distributed in the hope that it will be useful, # but WITHOUT ANY WARRANTY; without even the implied warranty of # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the # GNU General Public License for more details. # # You should have received a copy of the LSST License Statement and # the GNU General Public License along with this program. If not, # see <https://www.lsstcorp.org/LegalNotices/>. #
"""A measurement of a single `~lsst.verify.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 `Blob`\ s (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 `~lsst.verify.Metric` instance. If a `~lsst.verify.Metric` is provided then the units of the ``quantity`` argument are automatically validated. quantity : `astropy.units.Quantity`, optional The measured value as an Astropy `~astropy.units.Quantity`. If a `~lsst.verify.Metric` instance is provided, the units of ``quantity`` are compared to the `~lsst.verify.Metric`\ 's units for compatibility. The ``quantity`` can also be set, updated, or read with the `Measurement.quantity` attribute. blobs : `list` of `~lsst.verify.Blob`\ s, 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 `~lsst.verify.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. """
"""`dict` of `lsst.verify.Blob`\ s associated with this measurement.
See also -------- Measurement.link_blob """
"""`Blob` associated solely to this measurement.
Notes ----- ``extras`` work just like `Blob`\ s, but they're automatically created with each `Measurement`. Add `~lsst.verify.Datum`\ s to ``extras`` if those `~lsst.verify.Datum`\ s only make sense in the context of that `Measurement`. If `Datum`\ s 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. """
notes=None): # Internal attributes # every instance gets a unique identifier, useful for serialization
# must be a name
message = 'Blob {0} is not a Blob-type' raise TypeError(message.format(blob))
# extras is a blob automatically created for a measurement. # by attaching extras to the self.blobs we ensure it is serialized # with other blobs. else: # pre-existing Blobs; such as from a deserialization message = 'Extra {0} is not a Datum-type' raise TypeError(message.format(extra))
def metric(self): """Metric associated with the measurement (`lsst.verify.Metric` or `None`, mutable). """
def metric(self, value):
# Ensure the existing quantity has compatible units 'with existing quantity {1}')
# Reset metric_name for consistency
def metric_name(self): """Name of the corresponding metric (`lsst.verify.Name`, mutable). """
def metric_name(self, value): else: message = "Expected {0} to be a metric's name".format(value) raise TypeError(message) else:
def quantity(self): """`astropy.units.Quantity` component of the measurement (mutable). """
def quantity(self, q): # a quantity can be None or a Quantity 'astropy.units.dimensionless_unscaled')
# check unit consistency "the metric's units {1}")
def identifier(self): """Unique UUID4-based identifier for this measurement (`str`, immutable)."""
"""Get a LaTeX-formatted string representation of the measurement quantity (used in Jupyter notebooks).
Returns ------- rep : `str` String representation. """ return '{0.value:0.1f} {0.unit:latex_inline}'.format(self.quantity)
def description(self): """Description of the metric (`str`, or `None` if `Measurement.metric` is not set). """ else: return None
def datum(self): """Representation of this measurement as a `Datum`.""" label=str(self.metric_name), description=self.description)
"""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 `~lsst.verify.Blob` instance.
Notes ----- After linking, the `Blob` instance can be accessed by name (`Blob.name`) through the `Measurement.blobs` `dict`. """ message = 'Blob {0} is not a Blob-type'.format(blob) raise TypeError(message)
def notes(self): """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 `Specification`\ s, so that `Specification`\ s can be written to test only certain types of `Measurement`\ s. """
def json(self): """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.identifier`\ s for Blobs associated with this measurement.
.. note::
`Blob`\ s 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. """ # ensure metrics are normalized to metric definition's units else:
# Remove any reference to an empty extras blob
'identifier': self.identifier, 'value': _normalized_value, 'unit': _normalized_unit_str, 'blob_refs': blob_refs}
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.identifier`\ s for Blob associated with this measurement. blobs : `BlobSet` `BlobSet` containing all `Blob`\ s 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. """ # Resolve blobs from references: # get only referenced blobs if blob_identifier in blob_refs] # use all the blobs if none were specifically referenced _blobs = blobs else:
# Resolve quantity
(self.metric_name == other.metric_name) and \ (self.notes == other.notes)
return not self.__eq__(other)
"""Container for annotations (notes) associated with a single `lsst.verify.Measurement`.
Typically you will use pre-instantiate ``MeasurementNotes`` objects through the `lsst.verify.Measurement.notes` attribute.
Parameters ---------- metric_name : `Name` or `str` Fully qualified name of the measurement's metric. The metric's name is used as a prefix for key names.
See also -------- lsst.verify.Measurement.notes lsst.verify.Metadata
Examples -------- ``MeasurementNotes`` implements a `dict`-like interface. The only difference is that, internally, keys are always prefixed with the name of a metric. This allows measurement annotations to mesh `lsst.verify.Job` metadata keys (`lsst.verify.Job.meta`).
Users of `MeasurementNotes`, typically though `Measurement.notes`, do not need to use this prefix. Keys are prefixed behind the scenes.
>>> notes = MeasurementNotes('validate_drp') >>> notes['filter_name'] = 'r' >>> notes['filter_name'] 'r' >>> notes['validate_drp.filter_name'] 'r' >>> print(notes) {'validate_drp.filter_name': 'r'} """
# cast Name to str form to deal with prefixes # Enforced key prefix for all notes
"""Ensures the key includes the metric name prefix."""
(self._data == other._data)
return not self.__eq__(other)
return repr(self._data)
"""Get key names.
Returns ------- keys : `list` of `str` List of key names. """
"""Iterate over note key-value pairs.
Yields ------ item : key-value pair Each items is tuple of:
- Key name (`str`). - Note value (object). """
"""Update the notes with key-value pairs from a `dict`-like object.
Parameters ---------- data : `dict`-like `dict`-like object that has an ``items`` method for iteration. The key-value pairs of ``data`` are added to the ``MeasurementNotes`` instance. If key-value pairs already exist in the ``MeasurementNotes`` instance, they are overwritten with values from ``data``. """ |