Inheritance diagram for lsst.ip.isr.defects.Defects:

Public Member Functions
def	__init__ (self, defectList=None, metadata=None, normalize_on_init=True, *kwargs)

def	__len__ (self)

def	__getitem__ (self, index)

def	__setitem__ (self, index, value)

def	__iter__ (self)

def	__delitem__ (self, index)

def	__eq__ (self, other)

def	__str__ (self)

def	bulk_update (self)

def	append (self, value)

def	insert (self, index, value)

def	copy (self)

def	transpose (self)

def	maskPixels (self, maskedImage, maskName="BAD")

def	toFitsRegionTable (self)

def	fromDict (cls, dictionary)

def	toDict (self)

def	toTable (self)

def	fromTable (cls, tableList, normalize_on_init=True)

def	readLsstDefectsFile (cls, filename, normalize_on_init=False)

def	fromFootprintList (cls, fpList)

def	fromMask (cls, maskedImage, maskName)

def	requiredAttributes (self)

def	requiredAttributes (self, value)

def	getMetadata (self)

def	setMetadata (self, metadata)

def	updateMetadata (self, camera=None, detector=None, filterName=None, setCalibId=False, setCalibInfo=False, setDate=False, **kwargs)

def	calibInfoFromDict (self, dictionary)

def	readText (cls, filename, **kwargs)

def	writeText (self, filename, format='auto')

def	readFits (cls, filename, **kwargs)

def	writeFits (self, filename)

def	fromDetector (self, detector)

def	fromDict (cls, dictionary, **kwargs)

def	fromTable (cls, tableList, **kwargs)

def	validate (self, other=None)

def	apply (self, target)

Public Attributes
	requiredAttributes

	log

Detailed Description

Calibration handler for collections of `lsst.meas.algorithms.Defect`.

Parameters
----------
defectList : iterable of `lsst.meas.algorithms.Defect`
             or `lsst.geom.BoxI`, optional
    Collections of defects to apply to the image.
metadata : `lsst.daf.base.PropertyList`, optional
    Metadata to associate with the defects.  Will be copied and
    overwrite existing metadata, if any. If not supplied the existing
    metadata will be reset.
normalize_on_init : `bool`
    If True, normalization is applied to the defects in ``defectList`` to
    remove duplicates, eliminate overlaps, etc.

Notes
-----
Defects are stored within this collection in a "reduced" or "normalized"
form: rather than simply storing the bounding boxes which are added to the
collection, we eliminate overlaps and duplicates. This normalization
procedure may introduce overhead when adding many new defects; it may be
temporarily disabled using the `Defects.bulk_update` context manager if
necessary.

The attributes stored in this calibration are:

_defects : `list` [`lsst.meas.algorithms.Defect`]
    The collection of Defect objects.

The calibration type used for ingest.

Definition at line 47 of file defects.py.

Constructor & Destructor Documentation

◆ init()

def lsst.ip.isr.defects.Defects.__init__	(		self,
			defectList = `None`,
			metadata = `None`,
		*	normalize_on_init = `True`,
		**	kwargs
	)

Definition at line 83 of file defects.py.

     def __init__(self, defectList=None, metadata=None, *, normalize_on_init=True, **kwargs):
         self._defects = []
  
         if defectList is not None:
             self._bulk_update = True
             for d in defectList:
                 self.append(d)
         self._bulk_update = False
  
         if normalize_on_init:
             self._normalize()
  
         super().__init__(**kwargs)
         self.requiredAttributes.update(['_defects'])
  

Member Function Documentation

◆ delitem()

def lsst.ip.isr.defects.Defects.__delitem__	(	self,
		index
	)

Definition at line 145 of file defects.py.

     def __delitem__(self, index):
         del self._defects[index]
  

◆ eq()

def lsst.ip.isr.defects.Defects.__eq__	(	self,
		other
	)

Compare if two `Defects` are equal.

Two `Defects` are equal if their bounding boxes are equal and in
the same order.  Metadata content is ignored.

Reimplemented from lsst.ip.isr.calibType.IsrCalib.

Definition at line 148 of file defects.py.

     def __eq__(self, other):
         """Compare if two `Defects` are equal.
  
         Two `Defects` are equal if their bounding boxes are equal and in
         the same order.  Metadata content is ignored.
         """
         super().__eq__(other)
  
         if not isinstance(other, self.__class__):
             return False
  
         # checking the bboxes with zip() only works if same length
         if len(self) != len(other):
             return False
  
         # Assume equal if bounding boxes are equal
         for d1, d2 in zip(self, other):
             if d1.getBBox() != d2.getBBox():
                 return False
  
         return True
  

◆ getitem()

def lsst.ip.isr.defects.Defects.__getitem__	(	self,
		index
	)

Definition at line 133 of file defects.py.

     def __getitem__(self, index):
         return self._defects[index]
  

◆ iter()

def lsst.ip.isr.defects.Defects.__iter__ ( self )

Definition at line 142 of file defects.py.

     def __iter__(self):
         return iter(self._defects)
  

◆ len()

def lsst.ip.isr.defects.Defects.__len__ ( self )

Definition at line 130 of file defects.py.

     def __len__(self):
         return len(self._defects)
  

◆ setitem()

def lsst.ip.isr.defects.Defects.__setitem__	(	self,
		index,
		value
	)

Can be given a `~lsst.meas.algorithms.Defect` or a `lsst.geom.BoxI`

Definition at line 136 of file defects.py.

     def __setitem__(self, index, value):
         """Can be given a `~lsst.meas.algorithms.Defect` or a `lsst.geom.BoxI`
         """
         self._defects[index] = self._check_value(value)
         self._normalize()
  

◆ str()

def lsst.ip.isr.defects.Defects.__str__ ( self )

Reimplemented from lsst.ip.isr.calibType.IsrCalib.

Definition at line 170 of file defects.py.

     def __str__(self):
         baseStr = super().__str__(self)
         return baseStr + ",".join(str(d.getBBox()) for d in self) + ")"
  

◆ append()

def lsst.ip.isr.defects.Defects.append	(	self,
		value
	)

Definition at line 215 of file defects.py.

     def append(self, value):
         self._defects.append(self._check_value(value))
         self._normalize()
  

◆ apply()

def lsst.ip.isr.calibType.IsrCalib.apply	(	self,
		target
	)

inherited

Method to apply the calibration to the target object.

Parameters
----------
target : `object`
    Thing to validate against.

Returns
-------
valid : `bool`
    Returns true if the calibration was applied correctly.

Raises
------
NotImplementedError :
    Raised if not implemented.

Definition at line 549 of file calibType.py.

     def apply(self, target):
         """Method to apply the calibration to the target object.
  
         Parameters
         ----------
         target : `object`
             Thing to validate against.
  
         Returns
         -------
         valid : `bool`
             Returns true if the calibration was applied correctly.
  
         Raises
         ------
         NotImplementedError :
             Raised if not implemented.
         """
         raise NotImplementedError("Must be implemented by subclass.")
  
  

◆ bulk_update()

def lsst.ip.isr.defects.Defects.bulk_update ( self )

Temporarily suspend normalization of the defect list.

Definition at line 205 of file defects.py.

     def bulk_update(self):
         """Temporarily suspend normalization of the defect list.
         """
         self._bulk_update = True
         try:
             yield
         finally:
             self._bulk_update = False
             self._normalize()
  

◆ calibInfoFromDict()

def lsst.ip.isr.calibType.IsrCalib.calibInfoFromDict	(	self,
		dictionary
	)

inherited

Handle common keywords.

This isn't an ideal solution, but until all calibrations
expect to find everything in the metadata, they still need to
search through dictionaries.

Parameters
----------
dictionary : `dict` or `lsst.daf.base.PropertyList`
    Source for the common keywords.

Raises
------
RuntimeError :
    Raised if the dictionary does not match the expected OBSTYPE.

Definition at line 229 of file calibType.py.

     def calibInfoFromDict(self, dictionary):
         """Handle common keywords.
  
         This isn't an ideal solution, but until all calibrations
         expect to find everything in the metadata, they still need to
         search through dictionaries.
  
         Parameters
         ----------
         dictionary : `dict` or `lsst.daf.base.PropertyList`
             Source for the common keywords.
  
         Raises
         ------
         RuntimeError :
             Raised if the dictionary does not match the expected OBSTYPE.
  
         """
  
         def search(haystack, needles):
             """Search dictionary 'haystack' for an entry in 'needles'
             """
             test = [haystack.get(x) for x in needles]
             test = set([x for x in test if x is not None])
             if len(test) == 0:
                 if 'metadata' in haystack:
                     return search(haystack['metadata'], needles)
                 else:
                     return None
             elif len(test) == 1:
                 value = list(test)[0]
                 if value == '':
                     return None
                 else:
                     return value
             else:
                 raise ValueError(f"Too many values found: {len(test)} {test} {needles}")
  
         if 'metadata' in dictionary:
             metadata = dictionary['metadata']
  
             if self._OBSTYPE != metadata['OBSTYPE']:
                 raise RuntimeError(f"Incorrect calibration supplied.  Expected {self._OBSTYPE}, "
                                    f"found {metadata['OBSTYPE']}")
  
         self._instrument = search(dictionary, ['INSTRUME', 'instrument'])
         self._raftName = search(dictionary, ['RAFTNAME'])
         self._slotName = search(dictionary, ['SLOTNAME'])
         self._detectorId = search(dictionary, ['DETECTOR', 'detectorId'])
         self._detectorName = search(dictionary, ['DET_NAME', 'DETECTOR_NAME', 'detectorName'])
         self._detectorSerial = search(dictionary, ['DET_SER', 'DETECTOR_SERIAL', 'detectorSerial'])
         self._filter = search(dictionary, ['FILTER', 'filterName'])
         self._calibId = search(dictionary, ['CALIB_ID'])
  

◆ copy()

def lsst.ip.isr.defects.Defects.copy ( self )

Copy the defects to a new list, creating new defects from the
bounding boxes.

Returns
-------
new : `Defects`
    New list with new `Defect` entries.

Notes
-----
This is not a shallow copy in that new `Defect` instances are
created from the original bounding boxes.  It's also not a deep
copy since the bounding boxes are not recreated.

Definition at line 223 of file defects.py.

     def copy(self):
         """Copy the defects to a new list, creating new defects from the
         bounding boxes.
  
         Returns
         -------
         new : `Defects`
             New list with new `Defect` entries.
  
         Notes
         -----
         This is not a shallow copy in that new `Defect` instances are
         created from the original bounding boxes.  It's also not a deep
         copy since the bounding boxes are not recreated.
         """
         return self.__class__(d.getBBox() for d in self)
  

◆ fromDetector()

def lsst.ip.isr.calibType.IsrCalib.fromDetector	(	self,
		detector
	)

inherited

Modify the calibration parameters to match the supplied detector.

Parameters
----------
detector : `lsst.afw.cameraGeom.Detector`
    Detector to use to set parameters from.

Raises
------
NotImplementedError
    This needs to be implemented by subclasses for each
    calibration type.

Reimplemented in lsst.ip.isr.linearize.Linearizer.

Definition at line 432 of file calibType.py.

     def fromDetector(self, detector):
         """Modify the calibration parameters to match the supplied detector.
  
         Parameters
         ----------
         detector : `lsst.afw.cameraGeom.Detector`
             Detector to use to set parameters from.
  
         Raises
         ------
         NotImplementedError
             This needs to be implemented by subclasses for each
             calibration type.
         """
         raise NotImplementedError("Must be implemented by subclass.")
  

◆ fromDict() [1/2]

def lsst.ip.isr.defects.Defects.fromDict	(	cls,
		dictionary
	)

Construct a calibration from a dictionary of properties.

Must be implemented by the specific calibration subclasses.

Parameters
----------
dictionary : `dict`
    Dictionary of properties.

Returns
-------
calib : `lsst.ip.isr.CalibType`
    Constructed calibration.

Raises
------
RuntimeError :
    Raised if the supplied dictionary is for a different
    calibration.

Definition at line 329 of file defects.py.

     def fromDict(cls, dictionary):
         """Construct a calibration from a dictionary of properties.
  
         Must be implemented by the specific calibration subclasses.
  
         Parameters
         ----------
         dictionary : `dict`
             Dictionary of properties.
  
         Returns
         -------
         calib : `lsst.ip.isr.CalibType`
             Constructed calibration.
  
         Raises
         ------
         RuntimeError :
             Raised if the supplied dictionary is for a different
             calibration.
         """
         calib = cls()
  
         if calib._OBSTYPE != dictionary['metadata']['OBSTYPE']:
             raise RuntimeError(f"Incorrect crosstalk supplied.  Expected {calib._OBSTYPE}, "
                                f"found {dictionary['metadata']['OBSTYPE']}")
  
         calib.setMetadata(dictionary['metadata'])
         calib.calibInfoFromDict(dictionary)
  
         xCol = dictionary['x0']
         yCol = dictionary['y0']
         widthCol = dictionary['width']
         heightCol = dictionary['height']
  
         with calib.bulk_update:
             for x0, y0, width, height in zip(xCol, yCol, widthCol, heightCol):
                 calib.append(lsst.geom.Box2I(lsst.geom.Point2I(x0, y0),
                                              lsst.geom.Extent2I(width, height)))
         return calib
  

◆ fromDict() [2/2]

def lsst.ip.isr.calibType.IsrCalib.fromDict	(		cls,
			dictionary,
		**	kwargs
	)

inherited

Construct a calibration from a dictionary of properties.

Must be implemented by the specific calibration subclasses.

Parameters
----------
dictionary : `dict`
    Dictionary of properties.
kwargs : `dict` or collections.abc.Mapping`, optional
    Set of key=value options.

Returns
------
calib : `lsst.ip.isr.CalibType`
    Constructed calibration.

Raises
------
NotImplementedError :
    Raised if not implemented.

Definition at line 449 of file calibType.py.

     def fromDict(cls, dictionary, **kwargs):
         """Construct a calibration from a dictionary of properties.
  
         Must be implemented by the specific calibration subclasses.
  
         Parameters
         ----------
         dictionary : `dict`
             Dictionary of properties.
         kwargs : `dict` or collections.abc.Mapping`, optional
             Set of key=value options.
  
         Returns
         ------
         calib : `lsst.ip.isr.CalibType`
             Constructed calibration.
  
         Raises
         ------
         NotImplementedError :
             Raised if not implemented.
         """
         raise NotImplementedError("Must be implemented by subclass.")
  

◆ fromFootprintList()

def lsst.ip.isr.defects.Defects.fromFootprintList	(	cls,
		fpList
	)

Compute a defect list from a footprint list, optionally growing
the footprints.

Parameters
----------
fpList : `list` of `lsst.afw.detection.Footprint`
    Footprint list to process.

Returns
-------
defects : `Defects`
    List of defects.

Definition at line 638 of file defects.py.

     def fromFootprintList(cls, fpList):
         """Compute a defect list from a footprint list, optionally growing
         the footprints.
  
         Parameters
         ----------
         fpList : `list` of `lsst.afw.detection.Footprint`
             Footprint list to process.
  
         Returns
         -------
         defects : `Defects`
             List of defects.
         """
         # normalize_on_init is set to False to avoid recursively calling
         # fromMask/fromFootprintList in Defects.__init__.
         return cls(itertools.chain.from_iterable(lsst.afw.detection.footprintToBBoxList(fp)
                                                  for fp in fpList), normalize_on_init=False)
  

◆ fromMask()

def lsst.ip.isr.defects.Defects.fromMask	(	cls,
		maskedImage,
		maskName
	)

Compute a defect list from a specified mask plane.

Parameters
----------
maskedImage : `lsst.afw.image.MaskedImage`
    Image to process.
maskName : `str` or `list`
    Mask plane name, or list of names to convert.

Returns
-------
defects : `Defects`
    Defect list constructed from masked pixels.

Definition at line 658 of file defects.py.

     def fromMask(cls, maskedImage, maskName):
         """Compute a defect list from a specified mask plane.
  
         Parameters
         ----------
         maskedImage : `lsst.afw.image.MaskedImage`
             Image to process.
         maskName : `str` or `list`
             Mask plane name, or list of names to convert.
  
         Returns
         -------
         defects : `Defects`
             Defect list constructed from masked pixels.
         """
         mask = maskedImage.getMask()
         thresh = lsst.afw.detection.Threshold(mask.getPlaneBitMask(maskName),
                                               lsst.afw.detection.Threshold.BITMASK)
         fpList = lsst.afw.detection.FootprintSet(mask, thresh).getFootprints()
         return cls.fromFootprintList(fpList)

◆ fromTable() [1/2]

def lsst.ip.isr.calibType.IsrCalib.fromTable	(		cls,
			tableList,
		**	kwargs
	)

inherited

Construct a calibration from a dictionary of properties.

Must be implemented by the specific calibration subclasses.

Parameters
----------
tableList : `list` [`lsst.afw.table.Table`]
    List of tables of properties.
kwargs : `dict` or collections.abc.Mapping`, optional
    Set of key=value options.

Returns
------
calib : `lsst.ip.isr.CalibType`
    Constructed calibration.

Raises
------
NotImplementedError :
    Raised if not implemented.

Definition at line 492 of file calibType.py.

     def fromTable(cls, tableList, **kwargs):
         """Construct a calibration from a dictionary of properties.
  
         Must be implemented by the specific calibration subclasses.
  
         Parameters
         ----------
         tableList : `list` [`lsst.afw.table.Table`]
             List of tables of properties.
         kwargs : `dict` or collections.abc.Mapping`, optional
             Set of key=value options.
  
         Returns
         ------
         calib : `lsst.ip.isr.CalibType`
             Constructed calibration.
  
         Raises
         ------
         NotImplementedError :
             Raised if not implemented.
         """
         raise NotImplementedError("Must be implemented by subclass.")
  

◆ fromTable() [2/2]

def lsst.ip.isr.defects.Defects.fromTable	(	cls,
		tableList,
		normalize_on_init = `True`
	)

Construct a `Defects` from the contents of a
`~lsst.afw.table.BaseCatalog`.

Parameters
----------
table : `lsst.afw.table.BaseCatalog`
    Table with one row per defect.
normalize_on_init : `bool`, optional
    If `True`, normalization is applied to the defects listed in the
    table to remove duplicates, eliminate overlaps, etc. Otherwise
    the defects in the returned object exactly match those in the
    table.

Returns
-------
defects : `Defects`
    A `Defects` list.

Notes
-----
Two table formats are recognized.  The first is the
`FITS regions <https://fits.gsfc.nasa.gov/registry/region.html>`_
definition tabular format written by `toFitsRegionTable` where the
pixel origin is corrected from FITS 1-based to a 0-based origin.
The second is the legacy defects format using columns ``x0``, ``y0``
(bottom left hand pixel of box in 0-based coordinates), ``width``
and ``height``.

The FITS standard regions can only read BOX, POINT, or ROTBOX with
a zero degree rotation.

Definition at line 489 of file defects.py.

     def fromTable(cls, tableList, normalize_on_init=True):
         """Construct a `Defects` from the contents of a
         `~lsst.afw.table.BaseCatalog`.
  
         Parameters
         ----------
         table : `lsst.afw.table.BaseCatalog`
             Table with one row per defect.
         normalize_on_init : `bool`, optional
             If `True`, normalization is applied to the defects listed in the
             table to remove duplicates, eliminate overlaps, etc. Otherwise
             the defects in the returned object exactly match those in the
             table.
  
         Returns
         -------
         defects : `Defects`
             A `Defects` list.
  
         Notes
         -----
         Two table formats are recognized.  The first is the
         `FITS regions <https://fits.gsfc.nasa.gov/registry/region.html>`_
         definition tabular format written by `toFitsRegionTable` where the
         pixel origin is corrected from FITS 1-based to a 0-based origin.
         The second is the legacy defects format using columns ``x0``, ``y0``
         (bottom left hand pixel of box in 0-based coordinates), ``width``
         and ``height``.
  
         The FITS standard regions can only read BOX, POINT, or ROTBOX with
         a zero degree rotation.
         """
         table = tableList[0]
         defectList = []
  
         schema = table.columns
         # Check schema to see which definitions we have
         if "X" in schema and "Y" in schema and "R" in schema and "SHAPE" in schema:
             # This is a FITS region style table
             isFitsRegion = True
         elif "x0" in schema and "y0" in schema and "width" in schema and "height" in schema:
             # This is a classic LSST-style defect table
             isFitsRegion = False
         else:
             raise ValueError("Unsupported schema for defects extraction")
  
         for record in table:
             if isFitsRegion:
                 # Coordinates can be arrays (some shapes in the standard
                 # require this)
                 # Correct for FITS 1-based origin
                 xcen = cls._get_values(record['X']) - 1.0
                 ycen = cls._get_values(record['Y']) - 1.0
                 shape = record['SHAPE'].upper().rstrip()
                 if shape == "BOX":
                     box = lsst.geom.Box2I.makeCenteredBox(lsst.geom.Point2D(xcen, ycen),
                                                           lsst.geom.Extent2I(cls._get_values(record['R'],
                                                                                              n=2)))
                 elif shape == "POINT":
                     # Handle the case where we have an externally created
                     # FITS file.
                     box = lsst.geom.Point2I(xcen, ycen)
                 elif shape == "ROTBOX":
                     # Astropy regions always writes ROTBOX
                     rotang = cls._get_values(record['ROTANG'])
                     # We can support 0 or 90 deg
                     if math.isclose(rotang % 90.0, 0.0):
                         # Two values required
                         r = cls._get_values(record['R'], n=2)
                         if math.isclose(rotang % 180.0, 0.0):
                             width = r[0]
                             height = r[1]
                         else:
                             width = r[1]
                             height = r[0]
                         box = lsst.geom.Box2I.makeCenteredBox(lsst.geom.Point2D(xcen, ycen),
                                                               lsst.geom.Extent2I(width, height))
                     else:
                         log.warning("Defect can not be defined using ROTBOX with non-aligned rotation angle")
                         continue
                 else:
                     log.warning("Defect lists can only be defined using BOX or POINT not %s", shape)
                     continue
  
             else:
                 # This is a classic LSST-style defect table
                 box = lsst.geom.Box2I(lsst.geom.Point2I(record['x0'], record['y0']),
                                       lsst.geom.Extent2I(record['width'], record['height']))
  
             defectList.append(box)
  
         defects = cls(defectList, normalize_on_init=normalize_on_init)
         newMeta = dict(table.meta)
         defects.updateMetadata(setCalibInfo=True, **newMeta)
  
         return defects
  

◆ getMetadata()

def lsst.ip.isr.calibType.IsrCalib.getMetadata ( self )

inherited

Retrieve metadata associated with this calibration.

Returns
-------
meta : `lsst.daf.base.PropertyList`
    Metadata. The returned `~lsst.daf.base.PropertyList` can be
    modified by the caller and the changes will be written to
    external files.

Definition at line 114 of file calibType.py.

     def getMetadata(self):
         """Retrieve metadata associated with this calibration.
  
         Returns
         -------
         meta : `lsst.daf.base.PropertyList`
             Metadata. The returned `~lsst.daf.base.PropertyList` can be
             modified by the caller and the changes will be written to
             external files.
         """
         return self._metadata
  

◆ insert()

def lsst.ip.isr.defects.Defects.insert	(	self,
		index,
		value
	)

Definition at line 219 of file defects.py.

     def insert(self, index, value):
         self._defects.insert(index, self._check_value(value))
         self._normalize()
  

◆ maskPixels()

def lsst.ip.isr.defects.Defects.maskPixels	(	self,
		maskedImage,
		maskName = `"BAD"`
	)

Set mask plane based on these defects.

Parameters
----------
maskedImage : `lsst.afw.image.MaskedImage`
    Image to process.  Only the mask plane is updated.
maskName : str, optional
    Mask plane name to use.

Definition at line 257 of file defects.py.

     def maskPixels(self, maskedImage, maskName="BAD"):
         """Set mask plane based on these defects.
  
         Parameters
         ----------
         maskedImage : `lsst.afw.image.MaskedImage`
             Image to process.  Only the mask plane is updated.
         maskName : str, optional
             Mask plane name to use.
         """
         # mask bad pixels
         mask = maskedImage.getMask()
         bitmask = mask.getPlaneBitMask(maskName)
         for defect in self:
             bbox = defect.getBBox()
             lsst.afw.geom.SpanSet(bbox).clippedTo(mask.getBBox()).setMask(mask, bitmask)
  

◆ readFits()

def lsst.ip.isr.calibType.IsrCalib.readFits	(		cls,
			filename,
		**	kwargs
	)

inherited

Read calibration data from a FITS file.

Parameters
----------
filename : `str`
    Filename to read data from.
kwargs : `dict` or collections.abc.Mapping`, optional
    Set of key=value pairs to pass to the ``fromTable``
    method.

Returns
-------
calib : `lsst.ip.isr.IsrCalib`
    Calibration contained within the file.

Definition at line 370 of file calibType.py.

     def readFits(cls, filename, **kwargs):
         """Read calibration data from a FITS file.
  
         Parameters
         ----------
         filename : `str`
             Filename to read data from.
         kwargs : `dict` or collections.abc.Mapping`, optional
             Set of key=value pairs to pass to the ``fromTable``
             method.
  
         Returns
         -------
         calib : `lsst.ip.isr.IsrCalib`
             Calibration contained within the file.
         """
         tableList = []
         tableList.append(Table.read(filename, hdu=1))
         extNum = 2  # Fits indices start at 1, we've read one already.
         keepTrying = True
  
         while keepTrying:
             with warnings.catch_warnings():
                 warnings.simplefilter("error")
                 try:
                     newTable = Table.read(filename, hdu=extNum)
                     tableList.append(newTable)
                     extNum += 1
                 except Exception:
                     keepTrying = False
  
         for table in tableList:
             for k, v in table.meta.items():
                 if isinstance(v, fits.card.Undefined):
                     table.meta[k] = None
  
         return cls.fromTable(tableList, **kwargs)
  

◆ readLsstDefectsFile()

def lsst.ip.isr.defects.Defects.readLsstDefectsFile	(	cls,
		filename,
		normalize_on_init = `False`
	)

Read defects information from a legacy LSST format text file.

Parameters
----------
filename : `str`
    Name of text file containing the defect information.

normalize_on_init : `bool`, optional
    If `True`, normalization is applied to the defects listed in the
    table to remove duplicates, eliminate overlaps, etc. Otherwise
    the defects in the returned object exactly match those in the
    table.

Returns
-------
defects : `Defects`
    The defects.

Notes
-----
These defect text files are used as the human readable definitions
of defects in calibration data definition repositories.  The format
is to use four columns defined as follows:

x0 : `int`
    X coordinate of bottom left corner of box.
y0 : `int`
    Y coordinate of bottom left corner of box.
width : `int`
    X extent of the box.
height : `int`
    Y extent of the box.

Files of this format were used historically to represent defects
in simple text form.  Use `Defects.readText` and `Defects.writeText`
to use the more modern format.

Definition at line 587 of file defects.py.

     def readLsstDefectsFile(cls, filename, normalize_on_init=False):
         """Read defects information from a legacy LSST format text file.
  
         Parameters
         ----------
         filename : `str`
             Name of text file containing the defect information.
  
         normalize_on_init : `bool`, optional
             If `True`, normalization is applied to the defects listed in the
             table to remove duplicates, eliminate overlaps, etc. Otherwise
             the defects in the returned object exactly match those in the
             table.
  
         Returns
         -------
         defects : `Defects`
             The defects.
  
         Notes
         -----
         These defect text files are used as the human readable definitions
         of defects in calibration data definition repositories.  The format
         is to use four columns defined as follows:
  
         x0 : `int`
             X coordinate of bottom left corner of box.
         y0 : `int`
             Y coordinate of bottom left corner of box.
         width : `int`
             X extent of the box.
         height : `int`
             Y extent of the box.
  
         Files of this format were used historically to represent defects
         in simple text form.  Use `Defects.readText` and `Defects.writeText`
         to use the more modern format.
         """
         # Use loadtxt so that ValueError is thrown if the file contains a
         # non-integer value. genfromtxt converts bad values to -1.
         defect_array = np.loadtxt(filename,
                                   dtype=[("x0", "int"), ("y0", "int"),
                                          ("x_extent", "int"), ("y_extent", "int")])
  
         defects = (lsst.geom.Box2I(lsst.geom.Point2I(row["x0"], row["y0"]),
                                    lsst.geom.Extent2I(row["x_extent"], row["y_extent"]))
                    for row in defect_array)
  
         return cls(defects, normalize_on_init=normalize_on_init)
  

◆ readText()

def lsst.ip.isr.calibType.IsrCalib.readText	(		cls,
			filename,
		**	kwargs
	)

inherited

Read calibration representation from a yaml/ecsv file.

Parameters
----------
filename : `str`
    Name of the file containing the calibration definition.
kwargs : `dict` or collections.abc.Mapping`, optional
    Set of key=value pairs to pass to the ``fromDict`` or
    ``fromTable`` methods.

Returns
-------
calib : `~lsst.ip.isr.IsrCalibType`
    Calibration class.

Raises
------
RuntimeError :
    Raised if the filename does not end in ".ecsv" or ".yaml".

Definition at line 284 of file calibType.py.

     def readText(cls, filename, **kwargs):
         """Read calibration representation from a yaml/ecsv file.
  
         Parameters
         ----------
         filename : `str`
             Name of the file containing the calibration definition.
         kwargs : `dict` or collections.abc.Mapping`, optional
             Set of key=value pairs to pass to the ``fromDict`` or
             ``fromTable`` methods.
  
         Returns
         -------
         calib : `~lsst.ip.isr.IsrCalibType`
             Calibration class.
  
         Raises
         ------
         RuntimeError :
             Raised if the filename does not end in ".ecsv" or ".yaml".
         """
         if filename.endswith((".ecsv", ".ECSV")):
             data = Table.read(filename, format='ascii.ecsv')
             return cls.fromTable([data], **kwargs)
  
         elif filename.endswith((".yaml", ".YAML")):
             with open(filename, 'r') as f:
                 data = yaml.load(f, Loader=yaml.CLoader)
             return cls.fromDict(data, **kwargs)
         else:
             raise RuntimeError(f"Unknown filename extension: {filename}")
  

◆ requiredAttributes() [1/2]

def lsst.ip.isr.calibType.IsrCalib.requiredAttributes ( self )

inherited

Definition at line 107 of file calibType.py.

     def requiredAttributes(self):
         return self._requiredAttributes
  

◆ requiredAttributes() [2/2]

def lsst.ip.isr.calibType.IsrCalib.requiredAttributes	(	self,
		value
	)

inherited

Definition at line 111 of file calibType.py.

     def requiredAttributes(self, value):
         self._requiredAttributes = value
  

◆ setMetadata()

def lsst.ip.isr.calibType.IsrCalib.setMetadata	(	self,
		metadata
	)

inherited

Store a copy of the supplied metadata with this calibration.

Parameters
----------
metadata : `lsst.daf.base.PropertyList`
    Metadata to associate with the calibration.  Will be copied and
    overwrite existing metadata.

Definition at line 126 of file calibType.py.

     def setMetadata(self, metadata):
         """Store a copy of the supplied metadata with this calibration.
  
         Parameters
         ----------
         metadata : `lsst.daf.base.PropertyList`
             Metadata to associate with the calibration.  Will be copied and
             overwrite existing metadata.
         """
         if metadata is not None:
             self._metadata.update(metadata)
  
         # Ensure that we have the obs type required by calibration ingest
         self._metadata["OBSTYPE"] = self._OBSTYPE
         self._metadata[self._OBSTYPE + "_SCHEMA"] = self._SCHEMA
         self._metadata[self._OBSTYPE + "_VERSION"] = self._VERSION
  
         if isinstance(metadata, dict):
             self.calibInfoFromDict(metadata)
         elif isinstance(metadata, PropertyList):
             self.calibInfoFromDict(metadata.toDict())
  

◆ toDict()

def lsst.ip.isr.defects.Defects.toDict ( self )

Return a dictionary containing the calibration properties.

The dictionary should be able to be round-tripped through
`fromDict`.

Returns
-------
dictionary : `dict`
    Dictionary of properties.

Reimplemented from lsst.ip.isr.calibType.IsrCalib.

Definition at line 370 of file defects.py.

     def toDict(self):
         """Return a dictionary containing the calibration properties.
  
         The dictionary should be able to be round-tripped through
         `fromDict`.
  
         Returns
         -------
         dictionary : `dict`
             Dictionary of properties.
         """
         self.updateMetadata()
  
         outDict = {}
         metadata = self.getMetadata()
         outDict['metadata'] = metadata
  
         xCol = []
         yCol = []
         widthCol = []
         heightCol = []
  
         nrows = len(self._defects)
         if nrows:
             for defect in self._defects:
                 box = defect.getBBox()
                 xCol.append(box.getBeginX())
                 yCol.append(box.getBeginY())
                 widthCol.append(box.getWidth())
                 heightCol.append(box.getHeight())
  
         outDict['x0'] = xCol
         outDict['y0'] = yCol
         outDict['width'] = widthCol
         outDict['height'] = heightCol
  
         return outDict
  

◆ toFitsRegionTable()

def lsst.ip.isr.defects.Defects.toFitsRegionTable ( self )

Convert defect list to `~lsst.afw.table.BaseCatalog` using the
FITS region standard.

Returns
-------
table : `lsst.afw.table.BaseCatalog`
    Defects in tabular form.

Notes
-----
The table created uses the
`FITS regions <https://fits.gsfc.nasa.gov/registry/region.html>`_
definition tabular format.  The ``X`` and ``Y`` coordinates are
converted to FITS Physical coordinates that have origin pixel (1, 1)
rather than the (0, 0) used in LSST software.

Definition at line 274 of file defects.py.

     def toFitsRegionTable(self):
         """Convert defect list to `~lsst.afw.table.BaseCatalog` using the
         FITS region standard.
  
         Returns
         -------
         table : `lsst.afw.table.BaseCatalog`
             Defects in tabular form.
  
         Notes
         -----
         The table created uses the
         `FITS regions <https://fits.gsfc.nasa.gov/registry/region.html>`_
         definition tabular format.  The ``X`` and ``Y`` coordinates are
         converted to FITS Physical coordinates that have origin pixel (1, 1)
         rather than the (0, 0) used in LSST software.
         """
         self.updateMetadata()
         nrows = len(self._defects)
  
         if nrows:
             # Adding entire columns is more efficient than adding
             # each element separately
             xCol = []
             yCol = []
             rCol = []
             shapes = []
             for i, defect in enumerate(self._defects):
                 box = defect.getBBox()
                 center = box.getCenter()
                 # Correct for the FITS 1-based offset
                 xCol.append(center.getX() + 1.0)
                 yCol.append(center.getY() + 1.0)
  
                 width = box.width
                 height = box.height
  
                 if width == 1 and height == 1:
                     # Call this a point
                     shapeType = "POINT"
                 else:
                     shapeType = "BOX"
  
                 # Strings have to be added per row
                 shapes.append(shapeType)
  
                 rCol.append(np.array([width, height], dtype=np.float64))
  
         table = astropy.table.Table({'X': xCol, 'Y': yCol, 'SHAPE': shapes,
                                      'R': rCol, 'ROTANG': np.zeros(nrows),
                                      'COMPONENT': np.arange(nrows)})
         table.meta = self.getMetadata().toDict()
         return table
  

◆ toTable()

def lsst.ip.isr.defects.Defects.toTable ( self )

Convert defects to a simple table form that we use to write
to text files.

Returns
-------
table : `lsst.afw.table.BaseCatalog`
    Defects in simple tabular form.

Notes
-----
These defect tables are used as the human readable definitions
of defects in calibration data definition repositories.  The format
is to use four columns defined as follows:

x0 : `int`
    X coordinate of bottom left corner of box.
y0 : `int`
    Y coordinate of bottom left corner of box.
width : `int`
    X extent of the box.
height : `int`
    Y extent of the box.

Reimplemented from lsst.ip.isr.calibType.IsrCalib.

Definition at line 408 of file defects.py.

     def toTable(self):
         """Convert defects to a simple table form that we use to write
         to text files.
  
         Returns
         -------
         table : `lsst.afw.table.BaseCatalog`
             Defects in simple tabular form.
  
         Notes
         -----
         These defect tables are used as the human readable definitions
         of defects in calibration data definition repositories.  The format
         is to use four columns defined as follows:
  
         x0 : `int`
             X coordinate of bottom left corner of box.
         y0 : `int`
             Y coordinate of bottom left corner of box.
         width : `int`
             X extent of the box.
         height : `int`
             Y extent of the box.
         """
         tableList = []
         self.updateMetadata()
  
         xCol = []
         yCol = []
         widthCol = []
         heightCol = []
  
         nrows = len(self._defects)
         if nrows:
             for defect in self._defects:
                 box = defect.getBBox()
                 xCol.append(box.getBeginX())
                 yCol.append(box.getBeginY())
                 widthCol.append(box.getWidth())
                 heightCol.append(box.getHeight())
  
         catalog = astropy.table.Table({'x0': xCol, 'y0': yCol, 'width': widthCol, 'height': heightCol})
         inMeta = self.getMetadata().toDict()
         outMeta = {k: v for k, v in inMeta.items() if v is not None}
         catalog.meta = outMeta
         tableList.append(catalog)
  
         return tableList
  

◆ transpose()

def lsst.ip.isr.defects.Defects.transpose ( self )

Make a transposed copy of this defect list.

Returns
-------
retDefectList : `Defects`
    Transposed list of defects.

Definition at line 240 of file defects.py.

     def transpose(self):
         """Make a transposed copy of this defect list.
  
         Returns
         -------
         retDefectList : `Defects`
             Transposed list of defects.
         """
         retDefectList = self.__class__()
         for defect in self:
             bbox = defect.getBBox()
             dimensions = bbox.getDimensions()
             nbbox = lsst.geom.Box2I(lsst.geom.Point2I(bbox.getMinY(), bbox.getMinX()),
                                     lsst.geom.Extent2I(dimensions[1], dimensions[0]))
             retDefectList.append(nbbox)
         return retDefectList
  

◆ updateMetadata()

def lsst.ip.isr.calibType.IsrCalib.updateMetadata	(		self,
			camera = `None`,
			detector = `None`,
			filterName = `None`,
			setCalibId = `False`,
			setCalibInfo = `False`,
			setDate = `False`,
		**	kwargs
	)

inherited

Update metadata keywords with new values.

Parameters
----------
camera : `lsst.afw.cameraGeom.Camera`, optional
    Reference camera to use to set _instrument field.
detector : `lsst.afw.cameraGeom.Detector`, optional
    Reference detector to use to set _detector* fields.
filterName : `str`, optional
    Filter name to assign to this calibration.
setCalibId : `bool`, optional
    Construct the _calibId field from other fields.
setCalibInfo : `bool`, optional
    Set calibration parameters from metadata.
setDate : `bool`, optional
    Ensure the metadata CALIBDATE fields are set to the current datetime.
kwargs : `dict` or `collections.abc.Mapping`, optional
    Set of key=value pairs to assign to the metadata.

Definition at line 148 of file calibType.py.

                        **kwargs):
         """Update metadata keywords with new values.
  
         Parameters
         ----------
         camera : `lsst.afw.cameraGeom.Camera`, optional
             Reference camera to use to set _instrument field.
         detector : `lsst.afw.cameraGeom.Detector`, optional
             Reference detector to use to set _detector* fields.
         filterName : `str`, optional
             Filter name to assign to this calibration.
         setCalibId : `bool`, optional
             Construct the _calibId field from other fields.
         setCalibInfo : `bool`, optional
             Set calibration parameters from metadata.
         setDate : `bool`, optional
             Ensure the metadata CALIBDATE fields are set to the current datetime.
         kwargs : `dict` or `collections.abc.Mapping`, optional
             Set of key=value pairs to assign to the metadata.
         """
         mdOriginal = self.getMetadata()
         mdSupplemental = dict()
  
         for k, v in kwargs.items():
             if isinstance(v, fits.card.Undefined):
                 kwargs[k] = None
  
         if setCalibInfo:
             self.calibInfoFromDict(kwargs)
  
         if camera:
             self._instrument = camera.getName()
  
         if detector:
             self._detectorName = detector.getName()
             self._detectorSerial = detector.getSerial()
             self._detectorId = detector.getId()
             if "_" in self._detectorName:
                 (self._raftName, self._slotName) = self._detectorName.split("_")
  
         if filterName:
             # TOD0 DM-28093: I think this whole comment can go away, if we
             # always use physicalLabel everywhere in ip_isr.
             # If set via:
             # exposure.getInfo().getFilter().getName()
             # then this will hold the abstract filter.
             self._filter = filterName
  
         if setDate:
             date = datetime.datetime.now()
             mdSupplemental['CALIBDATE'] = date.isoformat()
             mdSupplemental['CALIB_CREATION_DATE'] = date.date().isoformat()
             mdSupplemental['CALIB_CREATION_TIME'] = date.time().isoformat()
  
         if setCalibId:
             values = []
             values.append(f"instrument={self._instrument}") if self._instrument else None
             values.append(f"raftName={self._raftName}") if self._raftName else None
             values.append(f"detectorName={self._detectorName}") if self._detectorName else None
             values.append(f"detector={self._detectorId}") if self._detectorId else None
             values.append(f"filter={self._filter}") if self._filter else None
  
             calibDate = mdOriginal.get('CALIBDATE', mdSupplemental.get('CALIBDATE', None))
             values.append(f"calibDate={calibDate}") if calibDate else None
  
             self._calibId = " ".join(values)
  
         self._metadata["INSTRUME"] = self._instrument if self._instrument else None
         self._metadata["RAFTNAME"] = self._raftName if self._raftName else None
         self._metadata["SLOTNAME"] = self._slotName if self._slotName else None
         self._metadata["DETECTOR"] = self._detectorId
         self._metadata["DET_NAME"] = self._detectorName if self._detectorName else None
         self._metadata["DET_SER"] = self._detectorSerial if self._detectorSerial else None
         self._metadata["FILTER"] = self._filter if self._filter else None
         self._metadata["CALIB_ID"] = self._calibId if self._calibId else None
  
         mdSupplemental.update(kwargs)
         mdOriginal.update(mdSupplemental)
  

◆ validate()

def lsst.ip.isr.calibType.IsrCalib.validate	(	self,
		other = `None`
	)

inherited

Validate that this calibration is defined and can be used.

Parameters
----------
other : `object`, optional
    Thing to validate against.

Returns
-------
valid : `bool`
    Returns true if the calibration is valid and appropriate.

Definition at line 534 of file calibType.py.

     def validate(self, other=None):
         """Validate that this calibration is defined and can be used.
  
         Parameters
         ----------
         other : `object`, optional
             Thing to validate against.
  
         Returns
         -------
         valid : `bool`
             Returns true if the calibration is valid and appropriate.
         """
         return False
  

◆ writeFits()

def lsst.ip.isr.calibType.IsrCalib.writeFits	(	self,
		filename
	)

inherited

Write calibration data to a FITS file.

Parameters
----------
filename : `str`
    Filename to write data to.

Returns
-------
used : `str`
    The name of the file used to write the data.

Definition at line 408 of file calibType.py.

     def writeFits(self, filename):
         """Write calibration data to a FITS file.
  
         Parameters
         ----------
         filename : `str`
             Filename to write data to.
  
         Returns
         -------
         used : `str`
             The name of the file used to write the data.
  
         """
         tableList = self.toTable()
         with warnings.catch_warnings():
             warnings.filterwarnings("ignore", category=Warning, module="astropy.io")
             astropyList = [fits.table_to_hdu(table) for table in tableList]
             astropyList.insert(0, fits.PrimaryHDU())
  
             writer = fits.HDUList(astropyList)
             writer.writeto(filename, overwrite=True)
         return filename
  

◆ writeText()

def lsst.ip.isr.calibType.IsrCalib.writeText	(	self,
		filename,
		format = `'auto'`
	)

inherited

Write the calibration data to a text file.

Parameters
----------
filename : `str`
    Name of the file to write.
format : `str`
    Format to write the file as.  Supported values are:
        ``"auto"`` : Determine filetype from filename.
        ``"yaml"`` : Write as yaml.
        ``"ecsv"`` : Write as ecsv.
Returns
-------
used : `str`
    The name of the file used to write the data.  This may
    differ from the input if the format is explicitly chosen.

Raises
------
RuntimeError :
    Raised if filename does not end in a known extension, or
    if all information cannot be written.

Notes
-----
The file is written to YAML/ECSV format and will include any
associated metadata.

Definition at line 316 of file calibType.py.

     def writeText(self, filename, format='auto'):
         """Write the calibration data to a text file.
  
         Parameters
         ----------
         filename : `str`
             Name of the file to write.
         format : `str`
             Format to write the file as.  Supported values are:
                 ``"auto"`` : Determine filetype from filename.
                 ``"yaml"`` : Write as yaml.
                 ``"ecsv"`` : Write as ecsv.
         Returns
         -------
         used : `str`
             The name of the file used to write the data.  This may
             differ from the input if the format is explicitly chosen.
  
         Raises
         ------
         RuntimeError :
             Raised if filename does not end in a known extension, or
             if all information cannot be written.
  
         Notes
         -----
         The file is written to YAML/ECSV format and will include any
         associated metadata.
  
         """
         if format == 'yaml' or (format == 'auto' and filename.lower().endswith((".yaml", ".YAML"))):
             outDict = self.toDict()
             path, ext = os.path.splitext(filename)
             filename = path + ".yaml"
             with open(filename, 'w') as f:
                 yaml.dump(outDict, f)
         elif format == 'ecsv' or (format == 'auto' and filename.lower().endswith((".ecsv", ".ECSV"))):
             tableList = self.toTable()
             if len(tableList) > 1:
                 # ECSV doesn't support multiple tables per file, so we
                 # can only write the first table.
                 raise RuntimeError(f"Unable to persist {len(tableList)}tables in ECSV format.")
  
             table = tableList[0]
             path, ext = os.path.splitext(filename)
             filename = path + ".ecsv"
             table.write(filename, format="ascii.ecsv")
         else:
             raise RuntimeError(f"Attempt to write to a file {filename} "
                                "that does not end in '.yaml' or '.ecsv'")
  
         return filename
  

Member Data Documentation

◆ log

lsst.ip.isr.calibType.IsrCalib.log

inherited

Definition at line 82 of file calibType.py.

◆ requiredAttributes

lsst.ip.isr.calibType.IsrCalib.requiredAttributes

inherited

Definition at line 77 of file calibType.py.

The documentation for this class was generated from the following file:

/j/snowflake/release/lsstsw/stack/0.4.3/Linux64/ip_isr/21.0.0-11-g2b59f77+a9c1acf22d/python/lsst/ip/isr/defects.py

Public Member Functions

Public Attributes

Detailed Description

Constructor & Destructor Documentation

◆ __init__()

Member Function Documentation

◆ __delitem__()

◆ __eq__()

◆ __getitem__()

◆ __iter__()

◆ __len__()

◆ __setitem__()

◆ __str__()

◆ append()

◆ apply()

◆ bulk_update()

◆ calibInfoFromDict()

◆ copy()

◆ fromDetector()

◆ fromDict() [1/2]

◆ fromDict() [2/2]

◆ fromFootprintList()

◆ fromMask()

◆ fromTable() [1/2]

◆ fromTable() [2/2]

◆ getMetadata()

◆ insert()

◆ maskPixels()

◆ readFits()

◆ readLsstDefectsFile()

◆ readText()

◆ requiredAttributes() [1/2]

◆ requiredAttributes() [2/2]

◆ setMetadata()

◆ toDict()

◆ toFitsRegionTable()

◆ toTable()

◆ transpose()

◆ updateMetadata()

◆ validate()

◆ writeFits()

◆ writeText()

Member Data Documentation

◆ log

◆ requiredAttributes

◆ init()

◆ delitem()

◆ eq()

◆ getitem()

◆ iter()

◆ len()

◆ setitem()

◆ str()