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

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, spec_tags, metric_tags, ...])	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

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:

• Name of the specification.
• Specification-type object.

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, 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.

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.

update(other)

Merge another SpecificationSet into this one.

Parameters:

other : SpecificationSet

Another SpecificationSet. Specifications in other that do 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.