DataIdPacker¶

class lsst.daf.butler.DataIdPacker¶

Bases: object

An abstract base class for a bidirectional mappings between a DataId and a packed integer or bytes blob.

Derived class constructors must accept at least the positional argments required by the base class contructor, but may accept additional keyword subclass-specific arguments as well (see configure).

Parameters:	dimensions : `DataIdPackerDimensions` Struct containing dimensions related to this `DataIdPacker`. kwds Additional subclass-specific keyword arguments. Values for these arguments are obtained from the `Registry` database according to the how the packer is configured in the `Registry`.

Notes

DataIdPacker subclass instances should generally be obtained from a Registry. This involves the following steps:

One or more packers are configured in the dataIdPackers section of the Registry configuration. In YAML form, that looks something like this:
dataIdPackers:
  visit_detector_id:
    given: [instrument]
    required: [visit, detector]
    cls: lsst.daf.butler.instrument.ObservationDataIdPacker
    parameters:
      instrument: instrument.instrument
      obsMax: instrument.visit_max
      detectorMax: instrument.detector_max
See DataIdPackerDimensions for a description of the given and required options. The parameters section maps keyword argument names for the DataIdPacker subclass constructor to dimension metadata fields in the Registry database that provide the values for these arguments.
A DataId that identifies at least the “given” dimensions of the DataIdPacker subclass must be expanded to include those metadata fields, by calling Registry.expandDataId.

Registry.makeDataIdPacker is called with the name of the packer and the expanded DataId. If the DataId also identifies all “required” dimensions for the packer, Registry.packDataId can be called instead for convenience (though this does not provide a way to call unpack).

Attributes Summary

`dimensions`	The dimensions associated with the `DataIdPacker` (`DataIdPackerDimensions`).
`maxBits`	The maximum number of nonzero bits in the packed ID returned by `pack` (`int`).

Methods Summary

`pack`(dataId, *[, returnMaxBits])	Pack the given data ID into a single integer.
`unpack`(packedId)	Unpack an ID produced by `pack` into a full `DataId`.

Attributes Documentation

dimensions¶: The dimensions associated with the DataIdPacker (DataIdPackerDimensions).

maxBits¶

The maximum number of nonzero bits in the packed ID returned by pack (int).

Must be implemented by all concrete derived classes. May return None to indicate that there is no maximum.

Methods Documentation

pack(dataId, *, returnMaxBits=False, **kwds)¶

Pack the given data ID into a single integer.

Parameters:

dataId : dict or DataId: Dictionary-like object identifying (at least) all required dimensions associated with this packer. Subclasses should in general accept an arbitrary mapping and call the DataId constructor internally to standardize. Values for any keys also present in the data ID passed at construction must be the same as the values in the data ID passed at construction.
returnMaxBits : bool: If True, return a tuple of (packed, self.maxBits).
kwds: Additional keyword arguments forwarded to the DataId constructor.

Returns:

packed : int: Packed integer ID.
maxBits : int, optional: Maximum number of nonzero bits in packed. Not returned unless returnMaxBits is True.

Notes

Should not be overridden by derived class (_pack should be overridden instead).

unpack(packedId)¶

Unpack an ID produced by pack into a full DataId.

Must be implemented by all concrete derived classes.

Parameters:	packedId : `int` or `bytes` The result of a call to `pack` on either `self` or an identically-constructed one.
Returns:	dataId : `DataId` Dictionary-like ID that uniquely identifies all covered dimensions.

Navigation

DataIdPacker¶