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: `Name` of the specification. `Specification`-type object.

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.

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.

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`. `Specification`s in `other` that do not exist in this set are added to this one. `Specification`s 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.

Navigation

SpecificationSet¶