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, hasParentId: bool = False, 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.

hasParentId : bool, optional

If True this DatasetRef is a component that has the id of the composite parent.

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
hasParentId
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.
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.
resolved(id, run)	Return a new DatasetRef with the same data ID and dataset type and the given ID and run.
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

hasParentId

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.

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, with hasParentId=True, 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.

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