GovernorDimension

class lsst.daf.butler.GovernorDimension(name: str, storage: dict, *, metadata_columns: NamedValueAbstractSet[IntColumnSpec | StringColumnSpec | FloatColumnSpec | HashColumnSpec | BoolColumnSpec], unique_keys: NamedValueAbstractSet[IntColumnSpec | StringColumnSpec | HashColumnSpec], doc: str)

Bases: Dimension

Governor dimension.

A special Dimension with no dependencies and a small number of rows, used to group the dimensions that depend on it.

Parameters:

namestr

Name of the dimension.

storagedict

Fully qualified name of the GovernorDimensionRecordStorage subclass that will back this element in the registry (in a “cls” key) along with any other construction keyword arguments (in other keys).

metadata_columnsNamedValueAbstractSet [ MetadataColumnSpec ]

Field specifications for all non-key fields in this dimension’s table.

unique_keysNamedValueAbstractSet [ KeyColumnSpec ]

Fields that can each be used to uniquely identify this dimension (given values for all required dimensions). The first of these is used as (part of) this dimension’s table’s primary key, while others are used to define unique constraints.

docstr

Extended description of this element.

Notes

Most dimensions have exactly one governor dimension as a required dependency, and queries that involve those dimensions are always expected to explicitly identify the governor dimension value(s), rather than retrieve all matches from the database. Because governor values are thus almost always known at query-generation time, they can be used there to simplify queries, provide sensible defaults, or check in advance for common mistakes that might otherwise yield confusing (albeit formally correct) results instead of straightforward error messages.

Governor dimensions may not be associated with any kind of topological extent.

Governor dimension rows are often affiliated with a Python class or instance (e.g. lsst.obs.base.Instrument) that is capable of generating the rows of at least some dependent dimensions or providing other related functionality. In the future, we hope to attach these instances to governor dimension records (instantiating them from information in the database row when it is fetched), and use those objects to add additional functionality to governor dimensions, but a number of (code) dependency relationships would need to be reordered first.

Attributes Summary

MAX_KEY_LENGTH
RecordClass	Return the record subclass for this element.
alternateKeys	Return alternate keys.
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.
graph	Return minimal graph that includes this element (DimensionGraph).
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, the name of an 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.
name	Return unique string identifier for this endpoint (str).
populated_by	The dimension that this element's records are always inserted, exported, and imported alongside.
primaryKey	Return primary key field for this dimension (FieldSpec).
primary_key	The primary key field for this dimension (KeyColumnSpec).
required	Return the required dimensions.
schema	A description of the columns in this element's records and (at least conceptual) table.
spatial	Return this endpoint's SPATIAL family.
temporal	Return this endpoint's TEMPORAL family.
topology	Return the relationship families to which this endpoint belongs.
uniqueKeys	Return the unique fields.
unique_keys	Descriptions of unique identifiers for this dimension.
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_arrow(dimensions[, spec])	Return an object that converts the primary key value for this dimension to column in an Arrow table.
to_json([minimal])	Convert this class to JSON form.
to_simple([minimal])	Convert this class to a simple python type.

Attributes Documentation

MAX_KEY_LENGTH = 128

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.

alternateKeys

Return alternate keys.

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

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

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

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

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 identify self (including self if isinstance(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

implied_union_target

If not None, the name of an 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

metadata

Additional metadata fields included in this element’s table.

(NamedValueSet of FieldSpec).

metadata_columns

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.

name

populated_by

primaryKey

Return primary key field for this dimension (FieldSpec).

Note that the database primary keys for dimension tables are in general compound; this field is the only field in the database primary key that is not also a foreign key (to a required dependency dimension table).

primary_key

The primary key field for this dimension (KeyColumnSpec).

Note that the database primary keys for dimension tables are in general compound; this field is the only field in the database primary key that is not also a foreign key (to a required dependency dimension table).

required

schema

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

spatial

Return this endpoint’s SPATIAL family.

temporal

Return this endpoint’s TEMPORAL family.

topology

uniqueKeys

Return the unique fields.

All fields that can individually be used to identify records of this element, given the primary keys of all required dependencies (NamedValueAbstractSet of FieldSpec).

unique_keys

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_arrow(dimensions: DimensionGroup, spec: KeyColumnSpec | None = None) → arrow_utils.ToArrow

Return an object that converts the primary key value for this dimension to column in an Arrow table.

Parameters:

dimensionsDimensionGroup

Full set of dimensions over which the rows of the table are unique or close to unique. This is used to determine whether to use Arrow’s dictionary encoding to compress duplicate values.

specKeyColumnSpec, optional

Column specification for this dimension. If not provided, a copy of primary_key the the field name replaced with the dimension name will be used, which is appropriate for when this dimension appears in data ID or the dimension record tables of other dimension elements.

Returns:

converterarrow_utils.ToArrow

Converter for this dimension’s primary key.

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.