Measure the PSF. More...

Inheritance diagram for lsst.pipe.tasks.measurePsf.MeasurePsfTask:

Public Member Functions
def	__init__
	Create the detection task. More...

def	run
	Measure the PSF. More...

Public Attributes
	candidateKey

	usedKey

	starSelector

	psfDeterminer

Static Public Attributes
	ConfigClass = MeasurePsfConfig

Static Private Attributes
string	_DefaultName = "measurePsf"

Detailed Description

Measure the PSF.

Description

A task that wraps two algorithms set via a pair of registries specified in the task's Configuration parameters. Both algorithms are classes with a constructor taking a pex.config.Config object (e.g. lsst.meas.algorithms.objectSizeStarSelector.ObjectSizeStarSelector.__init__).

The algorithms are:

a star selector with API:
1 selectStars(self, exposure, catalog, matches=None)

which returns a list of lsst.meas.algorithms.PsfCandidate (e.g. lsst.meas.algorithms.objectSizeStarSelector.ObjectSizeStarSelector.selectStars)
a psf estimator with API:
1 determinePsf(exposure, psfCandidateList, metadata=None, flagKey=None)

which returns an lsst.afw.detection.Psf and lsst.afw.math.SpatialCellSet (e.g. lsst.meas.algorithms.pcaPsfDeterminer.PcaPsfDeterminer.determinePsf). MeasurePsfTask calls determinePsf with flagKey set to "calib.psf.used" if a schema is passed to its constructor (see Task initialisation).

See also lsst.meas.algorithms.starSelectorRegistry.starSelectorRegistry and lsst.meas.algorithms.psfDeterminerRegistry.psfDeterminerRegistry.

Warning: There is no establised set of configuration parameters for these algorithms, so once you start modifying parameters (as we do in A complete example of using MeasurePsfTask) your code is no longer portable.

Task initialisation

Create the detection task. Most arguments are simply passed onto pipe.base.Task.

Parameters

schema	An lsst::afw::table::Schema used to create the output lsst.afw.table.SourceCatalog
**kwargs	Keyword arguments passed to lsst.pipe.base.task.Task.__init__.

If schema is not None, 'calib.psf.candidate' and 'calib.psf.used' fields will be added to identify which stars were employed in the PSF estimation.

Note: This task can add fields to the schema, so any code calling this task must ensure that these fields are indeed present in the input table.

Invoking the Task

Measure the PSF.

Parameters

[in,out]	exposure	Exposure to process; measured PSF will be added.
[in,out]	sources	Measured sources on exposure; flag fields will be set marking stars chosen by the star selector and the PSF determiner if a schema was passed to the task constructor.
[in]	matches	a list of lsst.afw.table.ReferenceMatch objects (i.e. of lsst.afw.table.Match with `first` being of type lsst.afw.table.SimpleRecord and `second` type lsst.afw.table.SourceRecord — the reference object and detected object respectively) as returned by e.g. the AstrometryTask. Used by star selectors that choose to refer to an external catalog.

Returns

a pipe.base.Struct with fields:

psf: The measured PSF (also set in the input exposure)
cellSet: an lsst.afw.math.SpatialCellSet containing the PSF candidates as returned by the psf determiner.

Configuration parameters

See MeasurePsfConfig.

Warning: The star selector and psf determiner registries should be modified to return a class which has a ConfigClass attribute and can be instantiated with a config. Until then, there's no obvious way to get a registry algorithm's Config from another Config.

Debug variables

The command line task interface supports a flag -d to import debug.py from your PYTHONPATH; see Using lsstDebug to control debugging output for more about debug.py files.

display: If True, display debugging plots
displayExposure: display the Exposure + spatialCells
displayPsfCandidates: show mosaic of candidates
showBadCandidates: Include bad candidates
displayPsfMosaic: show mosaic of reconstructed PSF(xy)
displayResiduals: show residuals
normalizeResiduals: Normalise residuals by object amplitude

Additionally you can enable any debug outputs that your chosen star selector and psf determiner support.

A complete example of using MeasurePsfTask

This code is in measurePsfTask.py in the examples directory, and can be run as e.g.

1 examples/measurePsfTask.py --ds9

The example also runs SourceDetectionTask and SourceMeasurementTask; see meas_algorithms_measurement_Example for more explanation.

Import the tasks (there are some other standard imports; read the file to see them all):

 from lsst.meas.algorithms.detection import SourceDetectionTask
 from lsst.meas.base                 import SingleFrameMeasurementTask
 from lsst.pipe.tasks.measurePsf     import MeasurePsfTask

We need to create the tasks before processing any data as the task constructor can add an extra column to the schema, but first we need an almost-empty Schema:

1 schema = afwTable.SourceTable.makeMinimalSchema()

We can now call the constructors for the tasks we need to find and characterize candidate PSF stars:

     config = SourceDetectionTask.ConfigClass()
     config.reEstimateBackground = False
     detectionTask = SourceDetectionTask(config=config, schema=schema)
 
     config = SingleFrameMeasurementTask.ConfigClass()
     # Use the minimum set of plugins required.
     config.plugins.names.clear()
     for plugin in ["base_SdssCentroid", "base_SdssShape", "base_CircularApertureFlux", "base_PixelFlags"]:
         config.plugins.names.add(plugin)
     config.plugins["base_CircularApertureFlux"].radii = [7.0]
     config.slots.psfFlux = "base_CircularApertureFlux_7_0" # Use of the PSF flux is hardcoded in secondMomentStarSelector
     measureTask = SingleFrameMeasurementTask(schema, config=config)

Note that we've chosen a minimal set of measurement plugins: we need the outputs of base_SdssCentroid, base_SdssShape and base_CircularApertureFlux as inputs to the PSF measurement algorithm, while base_PixelFlags identifies and flags bad sources (e.g. with pixels too close to the edge) so they can be removed later.

Now we can create and configure the task that we're interested in:

     config = MeasurePsfTask.ConfigClass()
 
     psfDeterminer = config.psfDeterminer.apply()
     psfDeterminer.config.sizeCellX = 128
     psfDeterminer.config.sizeCellY = 128
     psfDeterminer.config.spatialOrder = 1
     psfDeterminer.config.nEigenComponents = 3
 
     measurePsfTask = MeasurePsfTask(config=config, schema=schema)

We're now ready to process the data (we could loop over multiple exposures/catalogues using the same task objects). First create the output table:

1 tab = afwTable.SourceTable.make(schema)

And process the image:

     sources = detectionTask.run(tab, exposure, sigma=2).sources
     measureTask.measure(exposure, sources)
 
     result = measurePsfTask.run(exposure, sources)

We can then unpack and use the results:

1 psf = result.psf

2 cellSet = result.cellSet

If you specified –ds9 you can see the PSF candidates:

     if display:                         # display on ds9 (see also --debug argparse option)
         frame = 1
         ds9.mtv(exposure, frame=frame)
 
         with ds9.Buffering():
             for s in sources:
                 xy = s.getCentroid()
                 ds9.dot('+', *xy, frame=frame)
                 if s.get("calib.psf.candidate"):
                     ds9.dot('x', *xy, ctype=ds9.YELLOW, frame=frame)
                 if s.get("calib.psf.used"):
                     ds9.dot('o', *xy, size=4, ctype=ds9.RED, frame=frame)

To investigate the Debug variables, put something like

 import lsstDebug
 def DebugInfo(name):
     di = lsstDebug.getInfo(name)        # N.b. lsstDebug.Info(name) would call us recursively
 
     if name == "lsst.pipe.tasks.measurePsf" :
         di.display = True
         di.displayExposure = False          # display the Exposure + spatialCells
         di.displayPsfCandidates = True      # show mosaic of candidates
         di.displayPsfMosaic = True          # show mosaic of reconstructed PSF(xy)
         di.displayResiduals = True          # show residuals
         di.showBadCandidates = True         # Include bad candidates
         di.normalizeResiduals = False       # Normalise residuals by object amplitude
 
     return di
 
 lsstDebug.Info = DebugInfo

into your debug.py file and run measurePsfTask.py with the –debug flag.

Definition at line 41 of file measurePsf.py.

Constructor & Destructor Documentation

def lsst.pipe.tasks.measurePsf.MeasurePsfTask.__init__	(	self,
		schema = `None`,
		kwargs
	)

Create the detection task.

Most arguments are simply passed onto pipe.base.Task.

Parameters

schema	An lsst::afw::table::Schema used to create the output lsst.afw.table.SourceCatalog
**kwargs	Keyword arguments passed to lsst.pipe.base.task.Task.__init__.

If schema is not None, 'calib.psf.candidate' and 'calib.psf.used' fields will be added to identify which stars were employed in the PSF estimation.

Note: This task can add fields to the schema, so any code calling this task must ensure that these fields are indeed present in the input table.

Definition at line 212 of file measurePsf.py.

 
     def __init__(self, schema=None, **kwargs):
         """!Create the detection task.  Most arguments are simply passed onto pipe.base.Task.
 
         \param schema An lsst::afw::table::Schema used to create the output lsst.afw.table.SourceCatalog
         \param **kwargs Keyword arguments passed to lsst.pipe.base.task.Task.__init__.
 
         If schema is not None, 'calib.psf.candidate' and 'calib.psf.used' fields will be added to
         identify which stars were employed in the PSF estimation.
 
         \note This task can add fields to the schema, so any code calling this task must ensure that
         these fields are indeed present in the input table.
         """
 
         pipeBase.Task.__init__(self, **kwargs)
         if schema is not None:
             self.candidateKey = schema.addField(
                 "calib_psfCandidate", type="Flag",
                 doc=("Flag set if the source was a candidate for PSF determination, "
                      "as determined by the '%s' star selector.") % self.config.starSelector.name
             )
             self.usedKey = schema.addField(
                 "calib_psfUsed", type="Flag",
                 doc=("Flag set if the source was actually used for PSF determination, "
                      "as determined by the '%s' PSF determiner.") % self.config.psfDeterminer.name
             )
         else:
             self.candidateKey = None
             self.usedKey = None
         self.starSelector = self.config.starSelector.apply()
         self.psfDeterminer = self.config.psfDeterminer.apply()