DimensionElement¶

class lsst.daf.butler.DimensionElement¶

Bases: TopologicalRelationshipEndpoint

A label and/or metadata in the dimensions system.

A named data-organization concept that defines a label and/or metadata in the dimensions system.

A DimensionElement instance typically corresponds to a _logical_ table in the Registry: either an actual database table or a way of generating rows on-the-fly that can similarly participate in queries. The rows in that table are represented by instances of a DimensionRecord subclass. Most DimensionElement instances are instances of its Dimension subclass, which is used for elements that can be used as data ID keys.

Notes

DimensionElement instances should always be constructed by and retrieved from a DimensionUniverse. They are immutable after they are fully constructed, and should never be copied.

Pickling a DimensionElement just records its name and universe; unpickling one actually just looks up the element via the singleton dictionary of all universes. This allows pickle to be used to transfer elements between processes, but only when each process initializes its own instance of the same DimensionUniverse.

Attributes Summary

`RecordClass`	Return the record subclass for this element.
`alternate_keys`	Additional unique key fields for this dimension element that are not the primary key (`NamedValueAbstractSet` of `KeyColumnSpec`).
`alwaysJoin`	Indicate if the element should always be included.
`defines_relationships`	Whether this element's records define one or more relationships that must be satisfied in rows over dimensions that include it.
`dimensions`	Return all dimensions.
`documentation`	Extended description of this dimension element.
`governor`	Return the governor dimension.
`has_own_table`	Whether this element should have its own table in the database.
`implied`	Return the implied dimensions.
`implied_union_target`	If not `None`, another element whose implied values for this element form the set of allowable values.
`is_cached`	Whether this element's records should be aggressively cached, because they are small in number and rarely inserted.
`metadata`	Additional metadata fields included in this element's table.
`metadata_columns`	Additional metadata fields included in this element's table.
`minimal_group`	Return minimal dimension group that includes this element.
`populated_by`	The dimension that this element's records are always inserted, exported, and imported alongside.
`required`	Return the required dimensions.
`schema`	A description of the columns in this element's records and (at least conceptual) table.
`viewOf`	Name of another table this element's records are drawn from.

Methods Summary

`from_json`(json_str[, universe, registry])	Return new class from JSON string.
`from_simple`(simple[, universe, registry])	Construct a new object from the simplified form.
`hasTable`()	Indicate if this element is associated with a table.
`to_json`([minimal])	Convert this class to JSON form.
`to_simple`([minimal])	Convert this class to a simple python type.

Attributes Documentation

RecordClass¶

Return the record subclass for this element.

The DimensionRecord subclass used to hold records for this element (type).

Because DimensionRecord subclasses are generated dynamically, this type cannot be imported directly and hence can only be obtained from this attribute.

alternate_keys¶

Additional unique key fields for this dimension element that are not the primary key (NamedValueAbstractSet of KeyColumnSpec).

This is always empty for elements that are not dimensions.

If this dimension has required dependencies, the keys of those dimensions are also included in the unique constraints defined for these alternate keys.

alwaysJoin¶

Indicate if the element should always be included.

If True, always include this element in any query or data ID in which its required dimensions appear, because it defines a relationship between those dimensions that must always be satisfied.

defines_relationships¶: Whether this element’s records define one or more relationships that must be satisfied in rows over dimensions that include it.

dimensions¶

Return all dimensions.

The union of required and implied, with all elements in required before any elements in implied.

This differs from self.graph.dimensions both in order and in content:

as in self.implied, implied dimensions are not expanded recursively here;
implied dimensions appear after required dimensions here, instead of being topologically ordered.

As a result, this set is ordered consistently with self.RecordClass.fields.

documentation¶: Extended description of this dimension element.

governor¶

Return the governor dimension.

This is the GovernorDimension that is a required dependency of this element, or None if there is no such dimension (GovernorDimension or None).

has_own_table¶: Whether this element should have its own table in the database.

implied¶

Return the implied dimensions.

Other dimensions that are uniquely identified directly by a record of this dimension element.

For elements with a database representation, these are exactly the dimensions used to form foreign key constraints whose fields are not (wholly) also part of the primary key.

Unlike self.graph.implied, this set is not expanded recursively.

implied_union_target¶

If not None, another element whose implied values for this element form the set of allowable values.

For example, in the default dimension universe, the allowed values for band is the union of all band values in the physical_filter table, so the implied_union_target for band is physical_filter.

is_cached¶: Whether this element’s records should be aggressively cached, because they are small in number and rarely inserted.

metadata¶

Additional metadata fields included in this element’s table.

(NamedValueSet of FieldSpec).

metadata_columns¶

Additional metadata fields included in this element’s table.

(NamedValueSet of MetadataColumnSpec).

minimal_group¶

Return minimal dimension group that includes this element.

self.minimal_group.required includes all dimensions whose primary key values are sufficient (often necessary) to uniquely identify self (including self if isinstance(self, Dimension). self.minimal_group.implied includes all dimensions also identified (possibly recursively) by this set.

populated_by¶

The dimension that this element’s records are always inserted, exported, and imported alongside.

Notes

When this is None (as it will be, at least at first, for any data repositories created before this attribute was added), records for this element will often need to be exported manually when datasets associated with some other related dimension are exported, in order for the post-import data repository to function as expected.

required¶

Return the required dimensions.

Dimensions that are necessary to uniquely identify a record of this dimension element.

For elements with a database representation, these dimension are exactly those used to form the (possibly compound) primary key, and all dimensions here that are not self are also used to form foreign keys.

For Dimension instances, this should be exactly the same as graph.required, but that may not be true for DimensionElement instances in general. When they differ, there are multiple combinations of dimensions that uniquely identify this element, but this one is more direct.

schema¶: A description of the columns in this element’s records and (at least conceptual) table.

viewOf¶

Name of another table this element’s records are drawn from.

(str or None).

Methods Documentation

classmethod from_json(json_str: str, universe: DimensionUniverse | None = None, registry: Registry | None = None) → SupportsSimple¶

Return new class from JSON string.

Converts a JSON string created by to_json and return something of the supplied class.

Parameters:

json_strstr: Representation of the dimensions in JSON format as created by to_json().
universeDimensionUniverse, optional: The special graph of all known dimensions. Passed directly to from_simple().
registrylsst.daf.butler.Registry, optional: Registry to use to convert simple name of a DatasetType to a full DatasetType. Passed directly to from_simple().

Returns:

constructedAny: Newly-constructed object.

classmethod from_simple(simple: str, universe: DimensionUniverse | None = None, registry: Registry | None = None) → DimensionElement¶

Construct a new object from the simplified form.

Usually the data is returned from the to_simple method.

Parameters:

simplestr: The value returned by to_simple().
universeDimensionUniverse: The special graph of all known dimensions.
registrylsst.daf.butler.Registry, optional: Registry from which a universe can be extracted. Can be None if universe is provided explicitly.

Returns:

dataIdDimensionElement: Newly-constructed object.

hasTable() → bool¶

Indicate if this element is associated with a table.

Return True if this element is associated with a table (even if that table “belongs” to another element).

to_json(minimal: bool = False) → str¶

Convert this class to JSON form.

The class type is not recorded in the JSON so the JSON decoder must know which class is represented.

Parameters:

minimalbool, optional: Use minimal serialization. Requires Registry to convert back to a full type.

Returns:

jsonstr: The class in JSON string format.

to_simple(minimal: bool = False) → str¶

Convert this class to a simple python type.

This is suitable for serialization.

Parameters:

minimalbool, optional: Use minimal serialization. Has no effect on for this class.

Returns:

simplestr: The object converted to a single string.

Navigation

DimensionElement¶