SpecificationSet

class lsst.verify.SpecificationSet(specifications=None, partials=None)

Bases: lsst.verify.jsonmixin.JsonSerializationMixin

A collection of Specifications.

Parameters:
specifications : list or tuple of Specification instances

A sequence of Specification-type instances.

partials : list or tuple of SpecificationPartial instances

A sequence of SpecificationPartial instances. These partials can be used as bases for specification definitions.

Attributes Summary

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

Methods Summary

deserialize([specifications]) Deserialize a specification set from a JSON serialization.
insert(spec) Insert a Specification into the set.
items() Iterate over name, specification pairs.
jsonify_dict(d) Recursively build JSON-renderable objects on all values in a dict.
keys() Get a sequence of specification names, which are keys to the set.
load_metrics_package([package_name_or_path, …]) Create a SpecificationSet from an Verification Framework metrics package.
load_single_package(package_specs_dirname) Create a SpecificationSet from a filesystem directory containing specification YAML files for a single package.
report(measurements[, name, meta, …]) Create a report that details specification tests against the given measurements.
resolve_document(spec_doc) Resolve inherited properties in a specification document using specifications available in the repo.
subset([name, meta, required_meta, …]) Create a new SpecificationSet with specifications belonging to a single package or metric, and that apply to the given metadata.
update(other) Merge another SpecificationSet into this one.
write_json(filepath) Write JSON to a file.

Attributes Documentation

json

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

Methods Documentation

classmethod deserialize(specifications=None)

Deserialize a specification set from a JSON serialization.

Parameters:
specifications : list, optional

List of specification JSON objects.
Returns:
spec_set : SpecificationSet

SpecificationSet instance.
insert(spec)

Insert a Specification into the set.

A pre-existing specification with the same name is replaced.

Parameters:
spec : Specification-type

A specification.
items()

Iterate over name, specification pairs.

Yields:
item : tuple

Tuple containing:
static 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,
    })
keys()

Get a sequence of specification names, which are keys to the set.

Returns:
keys : sequence of Name

Keys to the specification set.
classmethod load_metrics_package(package_name_or_path='verify_metrics', subset=None)

Create a SpecificationSet from an Verification Framework metrics package.

Parameters:
package_name_or_path : str, optional

Name of an EUPS package that hosts metric and specification definition YAML files or the file path to a metrics package. verify_metrics is the default package, and is where metrics and specifications are defined for most packages.

subset : str, optional

If set, only specifications defined for this package are loaded. For example, if subset='validate_drp', only validate_drp specifications are included in the SpecificationSet. This argument is equivalent to the SpecificationSet.subset method. Default is None.
Returns:
spec_set : SpecificationSet

A SpecificationSet containing Specification instances.

See also

lsst.verify.SpecificationSet.load_single_package

Notes

EUPS packages that host metrics and specification definitions for the Verification Framework have top-level directories named 'metrics' and 'specs'.

Within 'specs/', directories are named after packages that have defined metrics. Contained within these directories are YAML files defining specifications for those metrics.

To make a SpecificationSet from a single package’s YAML definition directory that is not contained in a metrics package, use load_single_package instead.

classmethod load_single_package(package_specs_dirname)

Create a SpecificationSet from a filesystem directory containing specification YAML files for a single package.

Parameters:
package_specs_dirname : str

Directory containing specification definition YAML files for metrics of a single package. The name of this directory (final path component) is taken as the name of the package.
Returns:
spec_set : SpecificationSet

A SpecificationSet containing Specification instances.

See also

lsst.verify.SpecificationSet.load_metrics_package

Notes

This SpecificationSet constructor is useful for loading specifications from a directory containing specification definitions for a single package. The directory name is interpreted as a package name for fully-qualified metric and specification names.

To load a Verification Framework metrics package, like verify_metrics, with specifications for multple packages, use load_metrics_packge instead.

report(measurements, name=None, meta=None, spec_tags=None, metric_tags=None, metrics=None)

Create a report that details specification tests against the given measurements.

Parameters:
measurements : lsst.verify.MeasurementSet

Measurements to test.

name : str or lsst.verify.Name, optional

A package or metric name to subset specifications by. When set, only measurement and specification combinations belonging to that package or metric are included in the report.

meta : lsst.verifify.Metadata, optional

Job metadata to ensure the specifications are relevant to the measurements. Typically accessed as Job.meta.

spec_tags : sequence of str, optional

A set of specification tag strings. when given, only specifications that have all the given tags are included in the report. For example, spec_tags=['LPM-17', 'minimum'].

metric_tags : sequence of str, optional

A set of metric tag strings. When given, only specifications belonging to metrics that posess all given tags are included in the report. For example, metric_tags=['LPM-17', 'photometry'] selects sepifications that have both the 'LPM-17' and 'photometry' tags. If set, also provide a lsst.verify.MetricSet with the metrics argument.

metrics : lsst.verify.MetricSet

MetricSet with metric definitions. This is only needed if a metric_tags argument is provided.
Returns:
report : lsst.verify.Report

Report instance. In a Jupyter notebook, you can view the report by calling Report.show.

See also

lsst.verify.Job.report
resolve_document(spec_doc)

Resolve inherited properties in a specification document using specifications available in the repo.

Parameters:
spec_doc : dict

A specification document. A document is typically either a YAML document, where the specification is defined, or a JSON object that was serialized from a Specification instance.
Returns:
spec_doc : OrderedDict

The specification document is returned with bases resolved.
Raises:
SpecificationResolutionError

Raised when a document’s bases cannot be resolved (an inherited Specification cannot be found in the repo).
subset(name=None, meta=None, required_meta=None, spec_tags=None, metric_tags=None, metrics=None)

Create a new SpecificationSet with specifications belonging to a single package or metric, and that apply to the given metadata.

Parameters:
name : str or lsst.verify.Name, optional

Name to subset specifications by. If this is the name of a package, then all specifications for that package are included in the subset. If this is a metric name, then only specifications for that metric are included in the subset. The metric name must be fully-qualified (that is, it includes a package component).

meta : lsst.verify.Metadata, optional

If supplied, only specifications that apply to the given metadata are included in the subset. Metadata is usually obtained from the Job.meta attribute of a Job instance. By default, specifications are selected as long as the meta argument as at least all the terms defined in a specification’s metadata query and their term values do not conflict.

required_metadata : dict or lsst.verify.Metadata, optional

If supplied, only specifications that have all the terms in required_metadata (and their term values match) are selected. This is opposite to the logic of the meta argument where a specification with an empty metadata query is always selected, for example. This query is performed with the arg_driven=True mode of lsst.verify.MetadataQuery.

spec_tags : sequence of str, optional

A set of specification tag strings. when given, only specifications that have all the given tags are included in the report. For example, spec_tags=['LPM-17', 'minimum'].

metric_tags : sequence of str, optional

A set of metric tag strings. When given, only specifications belonging to metrics that posess all given tags are included in the report. For example, metric_tags=['LPM-17', 'photometry'] selects sepifications that have both the 'LPM-17' and 'photometry' tags. If set, also provide a lsst.verify.MetricSet with the metrics argument.

metrics : lsst.verify.MetricSet

MetricSet with metric definitions. This is only needed if a metric_tags argument is provided.
Returns:
spec_subset : SpecificationSet

Subset of this SpecificationSet containing only specifications belonging to the indicated package or metric, and/or that are compatible with the job metadata. Any partials in the SpecificationSet are also included in spec_subset.

See also

lsst.very.MetadataQuery
update(other)

Merge another SpecificationSet into this one.

Parameters:
other : SpecificationSet

Another SpecificationSet. Specifications in other that do not exist in this set are added to this one. Specifications in other replace specifications of the same name in this one.
write_json(filepath)

Write JSON to a file.

Parameters:
filepath : str

Destination file name for JSON output.