DataId

class lsst.daf.butler.DataId(dataId=None, *, dimensions=None, dimension=None, universe=None, region=None, entries=None, extra=None, **kwds)

Bases: collections.abc.Mapping

A dict-like identifier for data usable across multiple collections and DatasetTypes.

Parameters:
dataId : dict or DataId

A dict-like object containing Dimension links. If this is a true DataId and the set of dimensions identified does not change, this object will be updated in-place and returned instead of a new instance.

dimensions : iterable of Dimension or str, optional

The set of dimensions the DataId will identify, either as Dimension instances or string names thereof.

dimension : Dimension or str, optional

The single dimension this DataId will identify (along with all of its required dependencies).

universe : DimensionGraph, optional

A graph containing all known dimensions and joins. Must be provided if names are passed instead of Dimension instances in dimensions or dimension, or when dimensions are inferred from the provided link keys.

region : lsst.sphgeom.ConvexPolygon, optional

Spatial region on the sky associated with this combination of dimension entries.

entries : dict, optional

A nested dictionary of additional metadata column values associated with these dimensions, with DimensionElement instances or str names as the outer keys, str column names as inner keys, and column values as inner dictionary values.

extra : dict, optional

Additional key-value pairs to update dataId with.

kwds : dict, optional

Additional key-value pairs to update dataId with.
Raises:
ValueError

Raised if incomplete or incompatible arguments are provided.

Notes

The keys of a DataId correspond to the “link” columns of one or more Dimensions, while values identify particular rows in the tables or views for those Dimensions. In addition to implementing the (immutable) collections.abc.Mapping API, DataIds have additional attributes to hold additional metadata, regions, and definitions for those Dimensions. They are also hashable, and hence can be used as keys in dictionaries.

The DataId class represents a complete ID that has either been obtained from or validated with the set of known Dimensions. Regular dicts are typically used to represent conceptual data IDs that have not been validated. The DataId constructor serves as a sort of standardization routine; most APIs that conceptually operate on DataIds should accept either true DataIds or regular dicts via a single dataId argument, and pass this through the DataId construction (usually with additional keyword arguments forwarded) to guarantee a true DataId. When convenient, that DataId should also be returned.

The set of dimensions a DataId identifies can be provided to the constructor four ways:

  • Multiple dimensions may be passed via the dimensions argument.
  • A single dimension may be passed via the dimension argument.
  • If a true DataId is passed, its dimensions will be used if they are not overridden by one of the above.
  • If none of the above is provided, the dimensions are inferred from the set of keys provided in dataId, extra, and kwds; any dimensions in universe whose links are a subset of those keys is included.

Attributes Summary

dimensions The dimensions this DataId identifies (DimensionGraph).
entries A nested dictionary of additional values associated with the identified dimension entries (dict).

Methods Summary

fields(element[, region, metadata]) Return the entries for a particular DimensionElement.
get(k[,d])
items()
keys()
values()

Attributes Documentation

dimensions

The dimensions this DataId identifies (DimensionGraph).

entries

A nested dictionary of additional values associated with the identified dimension entries (dict).

The outer dictionary maps DimensionElement objects to dictionaries of field names and values.

Entry values are not in general guaranteed to have been validated against any actual Registry schema.

Methods Documentation

fields(element, region=True, metadata=True)

Return the entries for a particular DimensionElement.

Parameters:
element : DimensionElement or str

The Dimension or DimensionJoin for which fields should be returned.

region : bool

Whether to include the region in the result. Ignored if this DataId has no region or the given Dimension is not the region holder for it.

metadata : bool

Whether to include metadata (non-link, non-region columns) in the result. Ignored if this DataId has no metadata for the given Dimension.
Returns:
fields : dict

A dictionary of column name-value pairs.
get(k[, d]) → D[k] if k in D, else d. d defaults to None.
items() → a set-like object providing a view on D's items
keys() → a set-like object providing a view on D's keys
values() → an object providing a view on D's values