lsst.pipe.tasks  13.0-66-gfbf2f2ce+5
Public Member Functions | Public Attributes | Static Public Attributes | List of all members
lsst.pipe.tasks.photoCal.PhotoCalTask Class Reference

Calculate the zero point of an exposure given a lsst.afw.table.ReferenceMatchVector. More...

Inheritance diagram for lsst.pipe.tasks.photoCal.PhotoCalTask:

Public Member Functions

def __init__ (self, refObjLoader, schema=None, kwds)
 Create the photometric calibration task. More...
 
def getSourceKeys (self, schema)
 Return a struct containing the source catalog keys for fields used by PhotoCalTask. More...
 
def isUnresolved (self, source, starGalKey=None)
 Return whether the provided source is unresolved or not. More...
 
def selectMatches (self, matches, sourceKeys, filterName, frame=None)
 Select reference/source matches according the criteria specified in the config. More...
 
def extractMagArrays (self, matches, filterName, sourceKeys)
 Extract magnitude and magnitude error arrays from the given matches. More...
 
def run (self, exposure, sourceCat, expId=0)
 Do photometric calibration - select matches to use and (possibly iteratively) compute the zero point. More...
 
def getZeroPoint (self, src, ref, srcErr=None, zp0=None)
 Flux calibration code, returning (ZeroPoint, Distribution Width, Number of stars) More...
 

Public Attributes

 scatterPlot
 
 fig
 
 usedKey
 
 candidateKey
 
 reservedKey
 

Static Public Attributes

 ConfigClass = PhotoCalConfig
 

Detailed Description

Calculate the zero point of an exposure given a lsst.afw.table.ReferenceMatchVector.

Contents

Description

Calculate the zero point of an exposure given a lsst.afw.table.ReferenceMatchVector.

Calculate an Exposure's zero-point given a set of flux measurements of stars matched to an input catalogue. The type of flux to use is specified by PhotoCalConfig.fluxField.

The algorithm clips outliers iteratively, with parameters set in the configuration.

Note
This task can adds fields to the schema, so any code calling this task must ensure that these columns are indeed present in the input match list; see A complete example of using PhotoCalTask

Task initialisation

Create the photometric calibration task. See PhotoCalTask.init for documentation

Inputs/Outputs to the run method

Do photometric calibration - select matches to use and (possibly iteratively) compute the zero point.

Parameters
[in]exposureExposure upon which the sources in the matches were detected.
[in]sourceCatA catalog of sources to use in the calibration (i.e. a list 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 matched object respectively). (will not be modified except to set the outputField if requested.).
Returns
Struct of:
  • calib ----— lsst::afw::image::Calib object containing the zero point
  • arrays ---— Magnitude arrays returned be PhotoCalTask.extractMagArrays
  • matches --— Final ReferenceMatchVector, as returned by PhotoCalTask.selectMatches.
  • zp -------— Photometric zero point (mag)
  • sigma ----— Standard deviation of fit of photometric zero point (mag)
  • ngood ----— Number of sources used to fit photometric zero point

The exposure is only used to provide the name of the filter being calibrated (it may also be used to generate debugging plots).

The reference objects:

The measured sources:

Exceptions
RuntimeErrorwith the following strings:
`sources' schema does not contain the calibration object flag "XXX"`
The constructor added fields to the schema that aren't in the Sources
No input matches
The input match vector is empty
All matches eliminated by source flags
The flags specified by badFlags in the config eliminated all candidate objects
No sources remain in match list after reference catalog cuts
The reference catalogue has a column "photometric", but no matched objects have it set
No sources remaining in match list after magnitude limit cuts
All surviving matches are either too faint in the catalogue or have negative or NaN flux
No reference stars are available
No matches survive all the checks

Configuration parameters

See PhotoCalConfig

Debug variables

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

The available variables in PhotoCalTask are:

display
If True enable other debug outputs
displaySources
If True, display the exposure on ds9's frame 1 and overlay the source catalogue:
red x
Bad objects
blue +
Matched objects deemed unsuitable for photometric calibration. Additional information is:
  • a cyan o for galaxies
  • a magenta o for variables
magenta *
Objects that failed the flux cut
green o
Objects used in the photometric calibration
scatterPlot
Make a scatter plot of flux v. reference magnitude as a function of reference magnitude.
  • good objects in blue
  • rejected objects in red (if scatterPlot is 2 or more, prompt to continue after each iteration)

A complete example of using PhotoCalTask

This code is in examples/photoCalTask.py, and can be run as e.g.

examples/photoCalTask.py

Import the tasks (there are some other standard imports; read the file for details)

We need to create both our tasks before processing any data as the task constructors can add extra columns to the schema which we get from the input catalogue, scrCat:

Astrometry first:

(that filterMap line is because our test code doesn't use a filter that the reference catalogue recognises, so we tell it to use the r band)

Then photometry:

If the schema has indeed changed we need to add the new columns to the source table (yes; this should be easier!)

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

We can then unpack and use the results:


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.endswith(".PhotoCal"):
di.display = 1
return di
lsstDebug.Info = DebugInfo

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

Definition at line 168 of file photoCal.py.

Constructor & Destructor Documentation

◆ __init__()

def lsst.pipe.tasks.photoCal.PhotoCalTask.__init__ (   self,
  refObjLoader,
  schema = None,
  kwds 
)

Create the photometric calibration task.

See PhotoCalTask.init for documentation

Definition at line 296 of file photoCal.py.

Member Function Documentation

◆ extractMagArrays()

def lsst.pipe.tasks.photoCal.PhotoCalTask.extractMagArrays (   self,
  matches,
  filterName,
  sourceKeys 
)

Extract magnitude and magnitude error arrays from the given matches.

Parameters
[in]matchesReference/source matches, a lsst::afw::table::ReferenceMatchVector
[in]filterNameName of filter being calibrated
[in]sourceKeysStruct of source catalog keys, as returned by getSourceKeys()
Returns
Struct containing srcMag, refMag, srcMagErr, refMagErr, and magErr numpy arrays where magErr is an error in the magnitude; the error in srcMag - refMag If nonzero, config.magErrFloor will be added to magErr only (not srcMagErr or refMagErr), as magErr is what is later used to determine the zero point. Struct also contains refFluxFieldList: a list of field names of the reference catalog used for fluxes (1 or 2 strings)
Note
These magnitude arrays are the inputs to the photometric calibration, some may have been discarded by clipping while estimating the calibration (https://jira.lsstcorp.org/browse/DM-813)

Definition at line 481 of file photoCal.py.

◆ getSourceKeys()

def lsst.pipe.tasks.photoCal.PhotoCalTask.getSourceKeys (   self,
  schema 
)

Return a struct containing the source catalog keys for fields used by PhotoCalTask.

Returned fields include:

  • flux
  • fluxErr
  • goodFlags: a list of keys for field names in self.config.goodFlags
  • badFlags: a list of keys for field names in self.config.badFlags
  • starGal: key for star/galaxy classification

Definition at line 314 of file photoCal.py.

◆ getZeroPoint()

def lsst.pipe.tasks.photoCal.PhotoCalTask.getZeroPoint (   self,
  src,
  ref,
  srcErr = None,
  zp0 = None 
)

Flux calibration code, returning (ZeroPoint, Distribution Width, Number of stars)

We perform nIter iterations of a simple sigma-clipping algorithm with a couple of twists:

  1. We use the median/interquartile range to estimate the position to clip around, and the "sigma" to use.
  2. We never allow sigma to go above a critical value sigmaMax — if we do, a sufficiently large estimate will prevent the clipping from ever taking effect.
  3. Rather than start with the median we start with a crude mode. This means that a set of magnitude residuals with a tight core and asymmetrical outliers will start in the core. We use the width of this core to set our maximum sigma (see 2.)
Returns
Struct of:
  • zp -------— Photometric zero point (mag)
  • sigma ----— Standard deviation of fit of zero point (mag)
  • ngood ----— Number of sources used to fit zero point

Definition at line 731 of file photoCal.py.

◆ isUnresolved()

def lsst.pipe.tasks.photoCal.PhotoCalTask.isUnresolved (   self,
  source,
  starGalKey = None 
)

Return whether the provided source is unresolved or not.

This particular implementation is designed to work with the base_ClassificationExtendedness_value=0.0 or 1.0 scheme. Because of the diversity of star/galaxy classification outputs (binary decision vs probabilities; signs), it's difficult to make this configurable without using code. This method should therefore be overridden to use the appropriate classification output.

Parameters
[in]sourceSource to test
[in]starGalKeyStruct of schema keys for source
Returns
boolean value for starGalKey (True indicates Unresolved)

Definition at line 335 of file photoCal.py.

◆ run()

def lsst.pipe.tasks.photoCal.PhotoCalTask.run (   self,
  exposure,
  sourceCat,
  expId = 0 
)

Do photometric calibration - select matches to use and (possibly iteratively) compute the zero point.

Parameters
[in]exposureExposure upon which the sources in the matches were detected.
[in]sourceCatA catalog of sources to use in the calibration (i.e. a list 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 matched object respectively). (will not be modified except to set the outputField if requested.).
Returns
Struct of:
  • calib ----— lsst::afw::image::Calib object containing the zero point
  • arrays ---— Magnitude arrays returned be PhotoCalTask.extractMagArrays
  • matches --— Final ReferenceMatchVector, as returned by PhotoCalTask.selectMatches.
  • zp -------— Photometric zero point (mag)
  • sigma ----— Standard deviation of fit of photometric zero point (mag)
  • ngood ----— Number of sources used to fit photometric zero point

The exposure is only used to provide the name of the filter being calibrated (it may also be used to generate debugging plots).

The reference objects:

  • Must include a field photometric; True for objects which should be considered as photometric standards
  • Must include a field flux; the flux used to impose a magnitude limit and also to calibrate the data to (unless a color term is specified, in which case ColorTerm.primary is used; See https://jira.lsstcorp.org/browse/DM-933)
  • May include a field stargal; if present, True means that the object is a star
  • May include a field var; if present, True means that the object is variable

The measured sources:

Exceptions
RuntimeErrorwith the following strings:
`sources' schema does not contain the calibration object flag "XXX"`
The constructor added fields to the schema that aren't in the Sources
No input matches
The input match vector is empty
All matches eliminated by source flags
The flags specified by badFlags in the config eliminated all candidate objects
No sources remain in match list after reference catalog cuts
The reference catalogue has a column "photometric", but no matched objects have it set
No sources remaining in match list after magnitude limit cuts
All surviving matches are either too faint in the catalogue or have negative or NaN flux
No reference stars are available
No matches survive all the checks

Definition at line 596 of file photoCal.py.

◆ selectMatches()

def lsst.pipe.tasks.photoCal.PhotoCalTask.selectMatches (   self,
  matches,
  sourceKeys,
  filterName,
  frame = None 
)

Select reference/source matches according the criteria specified in the config.

Parameters
[in]matchesReferenceMatchVector (not modified)
[in]sourceKeysStruct of source catalog keys, as returned by getSourceKeys()
[in]filterNamename of camera filter; used to obtain the reference flux field
[in]frameds9 frame number to use for debugging display if frame is non-None, display information about trimmed objects on that ds9 frame:
  • Bad: red x
  • Unsuitable objects: blue + (and a cyan o if a galaxy)
  • Failed flux cut: magenta *
Returns
a lsst.afw.table.ReferenceMatchVector that contains only the selected matches. If a schema was passed during task construction, a flag field will be set on sources in the selected matches.
Exceptions
ValueErrorThere are no valid matches.

Definition at line 352 of file photoCal.py.

Member Data Documentation

◆ candidateKey

lsst.pipe.tasks.photoCal.PhotoCalTask.candidateKey

Definition at line 305 of file photoCal.py.

◆ ConfigClass

lsst.pipe.tasks.photoCal.PhotoCalTask.ConfigClass = PhotoCalConfig
static

Definition at line 293 of file photoCal.py.

◆ fig

lsst.pipe.tasks.photoCal.PhotoCalTask.fig

Definition at line 301 of file photoCal.py.

◆ reservedKey

lsst.pipe.tasks.photoCal.PhotoCalTask.reservedKey

Definition at line 307 of file photoCal.py.

◆ scatterPlot

lsst.pipe.tasks.photoCal.PhotoCalTask.scatterPlot

Definition at line 300 of file photoCal.py.

◆ usedKey

lsst.pipe.tasks.photoCal.PhotoCalTask.usedKey

Definition at line 303 of file photoCal.py.


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