ExposureIdInfo

class lsst.obs.base.ExposureIdInfo(expId=0, expBits=1, maxBits=None)

Bases: object

Struct representing an exposure ID and the number of bits it uses.

Parameters:
expId : int

Exposure ID. Note that this is typically the ID of an afw.image.Exposure, not the ID of an actual observation, and hence it usually either includes a detector component or is derived from SkyMap IDs, and the observation ID component usually represents a visit rather than exposure. For code using the Gen3 butler, this will usually be obtained via a DimensionPacker (see example below).

expBits : int

Maximum number of bits allowed for exposure IDs of this type.

maxBits : int, optional

Maximum number of bits available for values that combine exposure ID with other information, such as source ID. If not provided (recommended when possible), unusedBits will be computed by assuming the full ID must fit an an lsst.afw.table RecordId field.

Examples

One common use is creating an ID factory for making a source table. For example, given a ExposureIdInfo instance info,

from lsst.afw.table import SourceTable
schema = SourceTable.makeMinimalSchema()
#...add fields to schema as desired, then...
sourceTable = SourceTable.make(self.schema, info.makeSourceIdFactory())

An ExposureIdInfo instance can be obtained from a Gen2 data butler butler and dictionary dataId that identifies a visit and a detector via

info = butler.get("expIdInfo", dataId)

The Gen3 version is

expandedDataId = butler.registry.expandDataId(dataId)
info = ExposureIdInfo.fromDataId(expandedDataId, "visit_detector")

The first line should be unnecessary for the data IDs passed to PipelineTask methods, as those are already expanded, and "visit_detector" can be replaced by other strings to pack data IDs with different dimensions (e.g. "tract_patch" or "tract_patch_band"); see the data repository’s dimensions configuration for other options.

At least one bit must be reserved for the exposure ID, even if there is no exposure ID, for reasons that are not entirely clear (this is DM-6664).

Attributes Summary

unusedBits Maximum number of bits available for non-exposure info (int).

Methods Summary

fromDataId(dataId[, name, maxBits]) Construct an instance from a fully-expanded data ID.
makeSourceIdFactory() Make a lsst.afw.table.SourceTable.IdFactory instance from this exposure information.

Attributes Documentation

unusedBits

Maximum number of bits available for non-exposure info (int).

Methods Documentation

classmethod fromDataId(dataId, name='visit_detector', maxBits=None)

Construct an instance from a fully-expanded data ID.

Parameters:
dataId : lsst.daf.butler.DataCoordinate

An expanded data ID that identifies the dimensions to be packed and contains extra information about the maximum values for those dimensions. An expanded data ID can be obtained from Registry.expandDataId, but all data IDs passed to PipelineTask methods should already be expanded.

name : str, optional

Name of the packer to use. The set of available packers can be found in the data repository’s dimension configuration (see the “packers” section of dimensions.yaml in daf_butler for the defaults).

maxBits : int, optional

Forwarded as the __init__ parameter of the same name. Should usually be unnecessary.

Returns:
info : ExposureIdInfo

An ExposureIdInfo instance.

makeSourceIdFactory()

Make a lsst.afw.table.SourceTable.IdFactory instance from this exposure information.

Returns:
idFactory : lsst.afw.table.SourceTable.IdFactory

An ID factory that generates new IDs that fold in the image IDs managed by this object.