Defects

class lsst.ip.isr.Defects(defectList=None, metadata=None, *, normalize_on_init=True, **kwargs)

Bases: lsst.ip.isr.IsrCalib

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

Parameters:

defectList : iterable, optional

Collections of defects to apply to the image. Can be an iterable of lsst.meas.algorithms.Defect or lsst.geom.BoxI.

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.

Attributes Summary

requiredAttributes

Methods Summary

append(value)
apply(target)	Method to apply the calibration to the target object.
bulk_update()	Temporarily suspend normalization of the defect list.
calibInfoFromDict(dictionary)	Handle common keywords.
copy()	Copy the defects to a new list, creating new defects from the bounding boxes.
determineCalibClass(metadata, message)	Attempt to find calibration class in metadata.
fromDetector(detector)	Modify the calibration parameters to match the supplied detector.
fromDict(dictionary)	Construct a calibration from a dictionary of properties.
fromFootprintList(fpList)	Compute a defect list from a footprint list, optionally growing the footprints.
fromMask(maskedImage, maskName)	Compute a defect list from a specified mask plane.
fromTable(tableList[, normalize_on_init])	Construct a Defects from the contents of a BaseCatalog.
getMetadata()	Retrieve metadata associated with this calibration.
insert(index, value)
maskPixels(maskedImage[, maskName])	Set mask plane based on these defects.
readFits(filename, **kwargs)	Read calibration data from a FITS file.
readLsstDefectsFile(filename[, …])	Read defects information from a legacy LSST format text file.
readText(filename, **kwargs)	Read calibration representation from a yaml/ecsv file.
setMetadata(metadata)	Store a copy of the supplied metadata with this calibration.
toDict()	Return a dictionary containing the calibration properties.
toFitsRegionTable()	Convert defect list to BaseCatalog using the FITS region standard.
toTable()	Convert defects to a simple table form that we use to write to text files.
transpose()	Make a transposed copy of this defect list.
updateMetadata([camera, detector, …])	Update metadata keywords with new values.
validate([other])	Validate that this calibration is defined and can be used.
writeFits(filename)	Write calibration data to a FITS file.
writeText(filename[, format])	Write the calibration data to a text file.

Attributes Documentation

requiredAttributes

Methods Documentation

append(value)

apply(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.

bulk_update()

Temporarily suspend normalization of the defect list.

calibInfoFromDict(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.

copy()

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.

classmethod determineCalibClass(metadata, message)

Attempt to find calibration class in metadata.

Parameters:

metadata : dict or lsst.daf.base.PropertyList

Metadata possibly containing a calibration class entry.

message : str

Message to include in any errors.

Returns:

calibClass : object

The class to use to read the file contents. Should be an lsst.ip.isr.IsrCalib subclass.

Raises:

ValueError

Raised if the resulting calibClass is the base lsst.ip.isr.IsrClass (which does not implement the content methods).

fromDetector(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

Raised if not implemented by a subclass. This needs to be implemented by subclasses for each calibration type.

classmethod fromDict(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.

classmethod fromFootprintList(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.

classmethod fromMask(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.

classmethod fromTable(tableList, normalize_on_init=True)

Construct a Defects from the contents of a 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 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.

getMetadata()

Retrieve metadata associated with this calibration.

Returns:

meta : lsst.daf.base.PropertyList

Metadata. The returned PropertyList can be modified by the caller and the changes will be written to external files.

insert(index, value)

maskPixels(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.

classmethod readFits(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.

classmethod readLsstDefectsFile(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.

classmethod readText(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 : IsrCalibType

Calibration class.

Raises:

RuntimeError

Raised if the filename does not end in “.ecsv” or “.yaml”.

setMetadata(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.

toDict()

Return a dictionary containing the calibration properties.

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

Returns:

dictionary : dict

Dictionary of properties.

toFitsRegionTable()

Convert defect list to BaseCatalog using the FITS region standard.

Returns:

table : lsst.afw.table.BaseCatalog

Defects in tabular form.

Notes

The table created uses the FITS regions 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.

toTable()

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.

transpose()

Make a transposed copy of this defect list.

Returns:

retDefectList : Defects

Transposed list of defects.

updateMetadata(camera=None, detector=None, filterName=None, setCalibId=False, setCalibInfo=False, setDate=False, **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.

validate(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.

writeFits(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.

writeText(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.