SpecificationSet¶

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

Bases: JsonSerializationMixin

A collection of Specifications.

Parameters:

specificationslist or tuple of Specification instances: A sequence of Specification-type instances.
partialslist 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¶

Methods Documentation

classmethod deserialize(specifications=None)¶

Deserialize a specification set from a JSON serialization.

Parameters:

specificationslist, optional: List of specification JSON objects.

Returns:

spec_setSpecificationSet: SpecificationSet instance.

insert(spec)¶

Insert a Specification into the set.

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

Parameters:

specSpecification-type: A specification.

items()¶

Iterate over name, specification pairs.

Yields:

itemtuple

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:

ddict: Dictionary to convert into a JSON-serializable object. Values are recursively JSON-ified.

Returns:

json_dictdict: 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:

keyssequence 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_pathstr, 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.
subsetstr, 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_setSpecificationSet: 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_dirnamestr: 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_setSpecificationSet: 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:

measurementslsst.verify.MeasurementSet: Measurements to test.
namestr 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.
metalsst.verifify.Metadata, optional: Job metadata to ensure the specifications are relevant to the measurements. Typically accessed as Job.meta.
spec_tagssequence 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_tagssequence 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.
metricslsst.verify.MetricSet: MetricSet with metric definitions. This is only needed if a metric_tags argument is provided.

Returns:

reportlsst.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_docdict: 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_docOrderedDict: 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:

namestr 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).
metalsst.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_metadatadict 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_tagssequence 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_tagssequence 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.
metricslsst.verify.MetricSet: MetricSet with metric definitions. This is only needed if a metric_tags argument is provided.

Returns:

spec_subsetSpecificationSet: 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:

otherSpecificationSet: 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:

filepathstr: Destination file name for JSON output.

Navigation

SpecificationSet¶