RubinDimensionPacker

class lsst.obs.lsst.RubinDimensionPacker(data_id: DataCoordinate, *, config: RubinDimensionPackerConfig | None = None, is_exposure: bool | None = None)

Bases: DimensionPacker

A data ID packer that converts Rubin visit+detector and exposure+detector data IDs to integers.

Parameters:
data_idlsst.daf.butler.DataCoordinate

Data ID identifying at least the instrument dimension. Does not need to have dimension records attached.

configRubinDimensionPackerConfig, optional

Configuration for this dimension packer.

is_exposurebool, optional

If False, construct a packer for visit+detector data IDs. If True, construct a packer for exposure+detector data IDs. If None, this is determined based on whether visit or exposure is present in data_id, with visit checked first and hence used if both are present.

Notes

The packing used by this class is considered stable and part of its public interface so it can be reimplemented in contexts where delegation to this code is impractical (e.g. SQL user-defined functions):

packed =             detector + config.n_detectors * (
        seq_num + config.n_seq_nums * (
            convert_day_obs_to_ordinal(day_obs)
            - convert_day_obs_to_ordinal(config.day_obs_begin)
            + config.n_days * (
                config.controllers[controllers]
                config.n_controllers * is_one_to_one_reinterpretation
            )
        )
    )

See RubinDimensionPackerConfig and pack_decomposition for definitions of the above variables.

Attributes Summary

dimensions

The dimensions of data IDs packed by this instance (DimensionGraph).

maxBits

Return The maximum number of nonzero bits in the packed ID.

universe

Graph containing all known dimensions (DimensionUniverse).

Methods Summary

pack([dataId, returnMaxBits])

Pack the given data ID into a single integer.

pack_decomposition(day_obs, seq_num, detector)

Pack Rubin-specific identifiers directly into an integer.

pack_id_pair(exposure_id, detector[, ...])

Pack data ID values passed as arguments.

unpack(packedId)

Unpack an ID produced by pack into a full DataCoordinate.

unpack_decomposition(packed_id[, config])

Unpack an integer into Rubin-specific identifiers.

unpack_id_pair(packed_id[, config])

Unpack data ID values directly.

Attributes Documentation

dimensions

The dimensions of data IDs packed by this instance (DimensionGraph).

After v27 this will be a DimensionGroup.

maxBits
universe

Graph containing all known dimensions (DimensionUniverse).

Methods Documentation

pack(dataId: DataCoordinate | Mapping[str, Any] | None = None, *, returnMaxBits: bool = False, **kwargs: Any) tuple[int, int] | int

Pack the given data ID into a single integer.

Parameters:
dataIdDataId

Data ID to pack. Values for any keys also present in the “fixed” data ID passed at construction must be the same as the values passed at construction, but in general you must still specify those keys.

returnMaxBitsbool

If True, return a tuple of (packed, self.maxBits).

**kwargs

Additional keyword arguments are treated like additional key-value pairs in dataId.

Returns:
packedint

Packed integer ID.

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

static pack_decomposition(day_obs: int, seq_num: int, detector: int, controller: str = 'O', is_one_to_one_reinterpretation: bool = False, config: RubinDimensionPackerConfig | None = None) int

Pack Rubin-specific identifiers directly into an integer.

Parameters:
day_obsint

Day of observation as a YYYYMMDD decimal integer.

seq_numint

Sequence number

detectorint

Detector ID.

controllerstr, optional

Single-character controller code defined in RubinDimensionPackerConfig.controllers.

is_one_to_one_reinterpretationbool, optional

If True, this is a visit ID that differs from the exposure ID of its first snap because it is the alternate interpretation of that first snap as a standalone visit.

configRubinDimensionPackerConfig, optional

Configuration, including upper bounds on all arguments.

Returns:
packed_idint

Integer that reversibly combines all of the given arguments.

Notes

This is a staticmethod and hence does not respect the config passed in at construction when called on an instance. This is to support usage in contexts where construction (which requires a lsst.daf.butler.DimensionUniverse) is inconvenient or impossible.

static pack_id_pair(exposure_id: int, detector: int, is_one_to_one_reinterpretation: bool = False, config: RubinDimensionPackerConfig | None = None) int

Pack data ID values passed as arguments.

Parameters:
exposure_idint

Integer that uniquely identifies an exposure.

detectorint

Integer that uniquely identifies a detector.

is_one_to_one_reinterpretationbool, optional

If True, instead of packing the given exposure_id, pack a visit ID that represents the alternate interpretation of that exposure (which must be the first snap in a multi-snap sequence) as a standalone visit.

Returns:
packed_idint

Integer that reversibly combines all of the given arguments.

Notes

This is a staticmethod and hence does not respect the config passed in at construction when called on an instance. This is to support usage in contexts where construction (which requires a lsst.daf.butler.DimensionUniverse) is inconvenient or impossible.

unpack(packedId: int) DataCoordinate

Unpack an ID produced by pack into a full DataCoordinate.

Must be implemented by all concrete derived classes.

Parameters:
packedIdint

The result of a call to pack on either self or an identically-constructed packer instance.

Returns:
dataIdDataCoordinate

Dictionary-like ID that uniquely identifies all covered dimensions.

static unpack_decomposition(packed_id: int, config: RubinDimensionPackerConfig | None = None) tuple[int, int, int, str, bool]

Unpack an integer into Rubin-specific identifiers.

Parameters:
packed_idint

Integer produced by one of the methods of this class using the same configuration.

configRubinDimensionPackerConfig, optional

Configuration, including upper bounds on all arguments.

Returns:
day_obsint

Day of observation as a YYYYMMDD decimal integer.

seq_numint

Sequence number

detectorint

Detector ID.

controllerstr

Single-character controller code defined in RubinDimensionPackerConfig.controllers.

is_one_to_one_reinterpretationbool

If True, this is a visit ID that differs from the exposure ID of its first snap because it is the alternate interpretation of that first snap as a standalone visit.

Notes

This is a staticmethod and hence does not respect the config passed in at construction when called on an instance. This is to support usage in contexts where construction (which requires a lsst.daf.butler.DimensionUniverse) is inconvenient or impossible.

static unpack_id_pair(packed_id: int, config: RubinDimensionPackerConfig | None = None) tuple[int, int, bool]

Unpack data ID values directly.

Parameters:
packed_idint

Integer produced by one of the methods of this class using the same configuration.

Returns:
exposure_idint

Integer that uniquely identifies an exposure.

detectorint

Integer that uniquely identifies a detector.

is_one_to_one_reinterpretationbool, optional

If True, instead of packing the given exposure_id, the packed ID corresponds to the visit that represents the alternate interpretation of the first snap in a multi-snap sequence as a standalone visit.

Notes

This is a staticmethod and hence does not respect the config passed in at construction when called on an instance. This is to support usage in contexts where construction (which requires a lsst.daf.butler.DimensionUniverse) is inconvenient or impossible.