DatasetRef¶

class lsst.daf.butler.DatasetRef(datasetType: lsst.daf.butler.core.datasets.type.DatasetType, dataId: lsst.daf.butler.core.dimensions._coordinate.DataCoordinate, *, id: Optional[int] = None, run: Optional[str] = None, conform: bool = True)¶

Bases: object

Reference to a Dataset in a Registry.

A DatasetRef may point to a Dataset that currently does not yet exist (e.g., because it is a predicted input for provenance).

Parameters:

datasetType : DatasetType: The DatasetType for this Dataset.
dataId : DataCoordinate: A mapping of dimensions that labels the Dataset within a Collection.
id : int, optional: The unique integer identifier assigned when the dataset is created.
run : str, optional: The name of the run this dataset was associated with when it was created. Must be provided if id is.
conform : bool, optional: If True (default), call DataCoordinate.standardize to ensure that the data ID’s dimensions are consistent with the dataset type’s. DatasetRef instances for which those dimensions are not equal should not be created in new code, but are still supported for backwards compatibility. New code should only pass False if it can guarantee that the dimensions are already consistent.

Raises:

ValueError: Raised if run is provided but id is not, or if id is provided but run is not.

Attributes Summary

`dataId`	A mapping of `Dimension` primary key values that labels the dataset within a Collection (`DataCoordinate`).
`datasetType`	The definition of this dataset (`DatasetType`).
`dimensions`	The dimensions associated with the underlying `DatasetType`
`id`	Primary key of the dataset (`int` or `None`).
`run`	The name of the run that produced the dataset.

Methods Summary

`expanded`(dataId)	Return a new `DatasetRef` with the given expanded data ID.
`from_json`(json_str, universe, registry)	Convert a JSON string created by `to_json` and return something of the supplied class.
`from_simple`(simple, universe, registry)	Construct a new object from the data returned from the `to_simple` method.
`getCheckedId`()	Return `self.id`, or raise if it is `None`.
`groupByType`(refs)	Group an iterable of `DatasetRef` by `DatasetType`.
`isComponent`()	Boolean indicating whether this `DatasetRef` refers to a component of a composite.
`isComposite`()	Boolean indicating whether this `DatasetRef` is a composite type.
`makeComponentRef`(name)	Create a `DatasetRef` that corresponds to a component of this dataset.
`makeCompositeRef`()	Create a `DatasetRef` of the composite from a component ref.
`resolved`(id, run)	Return a new `DatasetRef` with the same data ID and dataset type and the given ID and run.
`to_json`(minimal)	Convert this class to JSON form.
`to_simple`(minimal)	Convert this class to a simple python type suitable for serialization.
`unresolved`()	Return a new `DatasetRef` with the same data ID and dataset type, but no ID or run.

Attributes Documentation

dataId¶

A mapping of Dimension primary key values that labels the dataset within a Collection (DataCoordinate).

Cannot be changed after a DatasetRef is constructed.

datasetType¶

The definition of this dataset (DatasetType).

Cannot be changed after a DatasetRef is constructed.

dimensions¶: The dimensions associated with the underlying DatasetType

id¶

Primary key of the dataset (int or None).

Cannot be changed after a DatasetRef is constructed; use resolved or unresolved to add or remove this information when creating a new DatasetRef.

run¶

The name of the run that produced the dataset.

Cannot be changed after a DatasetRef is constructed; use resolved or unresolved to add or remove this information when creating a new DatasetRef.

Methods Documentation

expanded(dataId: lsst.daf.butler.core.dimensions._coordinate.DataCoordinate) → lsst.daf.butler.core.datasets.ref.DatasetRef¶

Return a new DatasetRef with the given expanded data ID.

Parameters:	dataId : `DataCoordinate` Data ID for the new `DatasetRef`. Must compare equal to the original data ID.
Returns:	ref : `DatasetRef` A new `DatasetRef` with the given data ID.

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

Convert 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 to `from_simple()`.
Returns:	constructed : Any Newly-constructed object.

classmethod from_simple(simple: Dict, universe: Optional[DimensionUniverse] = None, registry: Optional[Registry] = None) → DatasetRef¶

Construct a new object from the data returned from the to_simple method.

Parameters:

simple : dict of [str, Any]: The value returned by to_simple().
universe : DimensionUniverse: The special graph of all known dimensions. Can be None if a registry is provided.
registry : lsst.daf.butler.Registry, optional: Registry to use to convert simple form of a DatasetRef to a full DatasetRef. Can be None if a full description of the type is provided along with a universe.

Returns:

ref : DatasetRef: Newly-constructed object.

getCheckedId() → int¶

Return self.id, or raise if it is None.

This trivial method exists to allow operations that would otherwise be natural list comprehensions to check that the ID is not None as well.

Returns:	id : `int` `self.id` if it is not `None`.
Raises:	AmbiguousDatasetError Raised if `ref.id` is `None`.

static groupByType(refs: Iterable[lsst.daf.butler.core.datasets.ref.DatasetRef]) → lsst.daf.butler.core.named.NamedKeyDict[lsst.daf.butler.core.datasets.type.DatasetType, typing.List[lsst.daf.butler.core.datasets.ref.DatasetRef]][lsst.daf.butler.core.datasets.type.DatasetType, List[lsst.daf.butler.core.datasets.ref.DatasetRef]]¶

Group an iterable of DatasetRef by DatasetType.

Parameters:	refs : `Iterable` [ `DatasetRef` ] `DatasetRef` instances to group.
Returns:	grouped : `NamedKeyDict` [ `DatasetType`, `list` [ `DatasetRef` ] ] Grouped `DatasetRef` instances.

isComponent() → bool¶

Boolean indicating whether this DatasetRef refers to a component of a composite.

Returns:	isComponent : `bool` `True` if this `DatasetRef` is a component, `False` otherwise.

isComposite() → bool¶

Boolean indicating whether this DatasetRef is a composite type.

Returns:	isComposite : `bool` `True` if this `DatasetRef` is a composite type, `False` otherwise.

makeComponentRef(name: str) → lsst.daf.butler.core.datasets.ref.DatasetRef¶

Create a DatasetRef that corresponds to a component of this dataset.

Parameters:	name : `str` Name of the component.
Returns:	ref : `DatasetRef` A `DatasetRef` with a dataset type that corresponds to the given component, and the same ID and run (which may be `None`, if they are `None` in `self`).

makeCompositeRef() → lsst.daf.butler.core.datasets.ref.DatasetRef¶

Create a DatasetRef of the composite from a component ref.

Requires that this DatasetRef is a component.

Returns:	ref : `DatasetRef` A `DatasetRef` with a dataset type that corresponds to the composite parent of this component, and the same ID and run (which may be `None`, if they are `None` in `self`).

resolved(id: int, run: str) → lsst.daf.butler.core.datasets.ref.DatasetRef¶

Return a new DatasetRef with the same data ID and dataset type and the given ID and run.

Parameters:	id : `int` The unique integer identifier assigned when the dataset is created. run : `str` The run this dataset was associated with when it was created.
Returns:	ref : `DatasetRef` A new `DatasetRef`.

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:	minimal : `bool`, optional Use minimal serialization. Requires Registry to convert back to a full type.
Returns:	json : `str` The class in JSON string format.

to_simple(minimal: bool = False) → Dict[KT, VT]¶

Convert this class to a simple python type suitable for serialization.

Parameters:	minimal : `bool`, optional Use minimal serialization. Requires Registry to convert back to a full type.
Returns:	simple : `dict` or `int` The object converted to a dictionary.

unresolved() → lsst.daf.butler.core.datasets.ref.DatasetRef¶

Return a new DatasetRef with the same data ID and dataset type, but no ID or run.

Returns:	ref : `DatasetRef` A new `DatasetRef`.

Notes

This can be used to compare only the data ID and dataset type of a pair of DatasetRef instances, regardless of whether either is resolved:

if ref1.unresolved() == ref2.unresolved():
    ...

Navigation

DatasetRef¶