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 theRegistry
: 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 aDimensionRecord
subclass. MostDimensionElement
instances are instances of itsDimension
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 aDimensionUniverse
. 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 sameDimensionUniverse
.Attributes Summary
Return the record subclass for this element.
Additional unique key fields for this dimension element that are not the primary key (
NamedValueAbstractSet
ofKeyColumnSpec
).Indicate if the element should always be included.
Whether this element's records define one or more relationships that must be satisfied in rows over dimensions that include it.
Return all dimensions.
Extended description of this dimension element.
Return the governor dimension.
Return minimal graph that includes this element (
DimensionGraph
).Whether this element should have its own table in the database.
Return the implied dimensions.
If not
None
, another element whose implied values for this element form the set of allowable values.Whether this element's records should be aggressively cached, because they are small in number and rarely inserted.
Additional metadata fields included in this element's table.
Additional metadata fields included in this element's table.
Return minimal dimension group that includes this element.
Return unique string identifier for this endpoint (
str
).The dimension that this element's records are always inserted, exported, and imported alongside.
Return the required dimensions.
A description of the columns in this element's records and (at least conceptual) table.
Return this endpoint's
SPATIAL
family.Return this endpoint's
TEMPORAL
family.Return the relationship families to which this endpoint belongs.
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
ofKeyColumnSpec
).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 itsrequired
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
andimplied
, with all elements inrequired
before any elements inimplied
.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, orNone
if there is no such dimension (GovernorDimension
orNone
).
- graph¶
Return minimal graph that includes this element (
DimensionGraph
).self.graph.required
includes all dimensions whose primary key values are sufficient (often necessary) to uniquely identifyself
(includingself
ifisinstance(self, Dimension)
.self.graph.implied
includes all dimensions also identified (possibly recursively) by this set.
- 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 allband
values in thephysical_filter
table, so theimplied_union_target
forband
isphysical_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
ofFieldSpec
).
- metadata_columns¶
Additional metadata fields included in this element’s table.
(
NamedValueSet
ofMetadataColumnSpec
).
- 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 identifyself
(includingself
ifisinstance(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 asgraph.required
, but that may not be true forDimensionElement
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.
- topology¶
Return the relationship families to which this endpoint belongs.
It is keyed by the category for that family.
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_str
str
Representation of the dimensions in JSON format as created by
to_json()
.- universe
DimensionUniverse
, optional The special graph of all known dimensions. Passed directly to
from_simple()
.- registry
lsst.daf.butler.Registry
, optional Registry to use to convert simple name of a DatasetType to a full
DatasetType
. Passed directly tofrom_simple()
.
- json_str
- 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:
- simple
str
The value returned by
to_simple()
.- universe
DimensionUniverse
The special graph of all known dimensions.
- registry
lsst.daf.butler.Registry
, optional Registry from which a universe can be extracted. Can be
None
if universe is provided explicitly.
- simple
- Returns:
- dataId
DimensionElement
Newly-constructed object.
- dataId
- 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).