ZogyMapper¶
-
class
lsst.ip.diffim.
ZogyMapper
(*args, **kwargs)¶ Bases:
lsst.ip.diffim.ZogyTask
,lsst.ip.diffim.ImageMapper
Task to be used as an ImageMapper for performing ZOGY image subtraction on a grid of subimages.
Methods Summary
computeDiffim
([inImageSpace, padSize, …])Wrapper method to compute ZOGY proper diffim
computeDiffimFourierSpace
([debug, …])Compute ZOGY diffim
D
as proscribed in ZOGY (2016) manuscriptcomputeDiffimImageSpace
([padSize, debug])Compute ZOGY diffim
D
using image-space convlutionscomputeDiffimPsf
([padSize, keepFourier, …])Compute the ZOGY diffim PSF (ZOGY manuscript eq.
computePrereqs
([psf1, psf2, padSize])Compute standard ZOGY quantities used by (nearly) all methods.
computeScorr
([xVarAst, yVarAst, …])Wrapper method to compute ZOGY corrected likelihood image, optimal for source detection
computeScorrFourierSpace
([xVarAst, yVarAst])Compute corrected likelihood image, optimal for source detection
computeScorrImageSpace
([xVarAst, yVarAst, …])Compute corrected likelihood image, optimal for source detection
Empty (clear) the metadata for this Task and all sub-Tasks.
Get schema catalogs for all tasks in the hierarchy, combining the results into a single dict.
Get metadata for all tasks.
Get the task name as a hierarchical name including parent task names.
getName
()Get the name of the task.
Get the schemas generated by this task.
Get a dictionary of all tasks as a shallow copy.
makeField
(doc)Make a
lsst.pex.config.ConfigurableField
for this task.makeSubtask
(name, **keyArgs)Create a subtask as a new instance as the
name
attribute of this task.run
(subExposure, expandedSubExposure, …)Perform ZOGY proper image subtraction on sub-images
setup
([templateExposure, scienceExposure, …])Set up the ZOGY task.
timer
(name[, logLevel])Context manager to log performance data for an arbitrary block of code.
Methods Documentation
-
computeDiffim
(inImageSpace=None, padSize=None, returnMatchedTemplate=False, **kwargs)¶ Wrapper method to compute ZOGY proper diffim
This method should be used as the public interface for computing the ZOGY diffim.
- Parameters
- inImageSpace
bool
Override config
inImageSpace
parameter- padSize
int
Override config
padSize
parameter- returnMatchedTemplate
bool
Include the PSF-matched template in the results Struct
- **kwargs
additional keyword arguments to be passed to
computeDiffimFourierSpace
orcomputeDiffimImageSpace
.
- inImageSpace
- Returns
- An lsst.pipe.base.Struct containing:
- D
lsst.afw.Exposure
the proper image difference, including correct variance, masks, and PSF
- D
- R
lsst.afw.Exposure
If
returnMatchedTemplate
is True, the PSF-matched template exposure
- R
-
computeDiffimFourierSpace
(debug=False, returnMatchedTemplate=False, **kwargs)¶ Compute ZOGY diffim
D
as proscribed in ZOGY (2016) manuscript- Parameters
- Returns
- result
lsst.pipe.base.Struct
Result struct with components:
D
: 2Dnumpy.array
, the proper image differenceD_var
: 2Dnumpy.array
, the variance image forD
- result
Notes
In all functions, im1 is R (reference, or template) and im2 is N (new, or science) Compute the ZOGY eqn. (13):
\[\widehat{D} = \frac{Fr\widehat{Pr}\widehat{N} - F_n\widehat{Pn}\widehat{R}}{\sqrt{\sigma_n^2 Fr^2 \|\widehat{Pr}\|^2 + \sigma_r^2 F_n^2 \|\widehat{Pn}\|^2}}\]where \(D\) is the optimal difference image, \(R\) and \(N\) are the reference and “new” image, respectively, \(Pr\) and \(P_n\) are their PSFs, \(Fr\) and \(Fn\) are their flux-based zero-points (which we will set to one here), \(\sigma_r^2\) and \(\sigma_n^2\) are their variance, and \(\widehat{D}\) denotes the FT of \(D\).
-
computeDiffimImageSpace
(padSize=None, debug=False, **kwargs)¶ Compute ZOGY diffim
D
using image-space convlutionsThis method is still being debugged as it results in artifacts when the PSFs are noisy (see module-level docstring). Thus there are several options still enabled by the
debug
flag, which are disabled by defult.
-
computeDiffimPsf
(padSize=0, keepFourier=False, psf1=None, psf2=None)¶ Compute the ZOGY diffim PSF (ZOGY manuscript eq. 14)
- Parameters
- padSize
int
Override config
padSize
parameter- keepFourier
bool
Return the FFT of the diffim PSF (do not inverse-FFT it)
- psf12D
numpy.array
(Optional) Input psf of template, override if already padded
- psf22D
numpy.array
(Optional) Input psf of science image, override if already padded
- padSize
- Returns
- Pd2D
numpy.array
The diffim PSF (or FFT of PSF if
keepFourier=True
)
- Pd2D
-
computePrereqs
(psf1=None, psf2=None, padSize=0)¶ Compute standard ZOGY quantities used by (nearly) all methods.
Many of the ZOGY calculations require similar quantities, including FFTs of the PSFs, and the “denominator” term (e.g. in eq. 13 of ZOGY manuscript (2016). This function consolidates many of those operations.
- Parameters
- psf12D
numpy.array
(Optional) Input psf of template, override if already padded
- psf22D
numpy.array
(Optional) Input psf of science image, override if already padded
- padSize
int
, optional Number of pixels to pad the image on each side with zeroes.
- psf12D
- Returns
- A `lsst.pipe.base.Struct` containing:
- - Pr2D
numpy.array
, the (possibly zero-padded) template PSF - - Pn2D
numpy.array
, the (possibly zero-padded) science PSF - - Pr_hat2D
numpy.array
, the FFT ofPr
- - Pn_hat2D
numpy.array
, the FFT ofPn
- - denom2D
numpy.array
, the denominator of equation (13) in ZOGY (2016) manuscript - - Fd
float
, the relative flux scaling factor between science and template
-
computeScorr
(xVarAst=0.0, yVarAst=0.0, inImageSpace=None, padSize=0, **kwargs)¶ Wrapper method to compute ZOGY corrected likelihood image, optimal for source detection
This method should be used as the public interface for computing the ZOGY S_corr.
- Parameters
- Returns
- S
lsst.afw.image.Exposure
The likelihood exposure S (eq. 12 of ZOGY (2016)), including corrected variance, masks, and PSF
- S
-
computeScorrFourierSpace
(xVarAst=0.0, yVarAst=0.0, **kwargs)¶ Compute corrected likelihood image, optimal for source detection
Compute ZOGY S_corr image. This image can be thresholded for detection without optimal filtering, and the variance image is corrected to account for astrometric noise (errors in astrometric registration whether systematic or due to effects such as DCR). The calculations here are all performed in Fourier space, as proscribed in ZOGY (2016).
- Parameters
- xVarAst, yVarAst
float
estimated astrometric noise (variance of astrometric registration errors)
- xVarAst, yVarAst
- Returns
- result
lsst.pipe.base.Struct
Result struct with components:
S
:numpy.array
, the likelihood image S (eq. 12 of ZOGY (2016))S_var
: the corrected variance image (denominator of eq. 25 of ZOGY (2016))Dpsf
: the PSF of the diffim D, likely never to be used.
- result
-
computeScorrImageSpace
(xVarAst=0.0, yVarAst=0.0, padSize=None, **kwargs)¶ Compute corrected likelihood image, optimal for source detection
Compute ZOGY S_corr image. This image can be thresholded for detection without optimal filtering, and the variance image is corrected to account for astrometric noise (errors in astrometric registration whether systematic or due to effects such as DCR). The calculations here are all performed in Real (image) space.
- Parameters
- xVarAst, yVarAst
float
estimated astrometric noise (variance of astrometric registration errors)
- xVarAst, yVarAst
- Returns
- A `lsst.pipe.base.Struct` containing:
- - S
lsst.afw.image.Exposure
, the likelihood exposure S (eq. 12 of ZOGY (2016)), including corrected variance, masks, and PSF
- - D
lsst.afw.image.Exposure
, the proper image difference, including correct variance, masks, and PSF
-
emptyMetadata
()¶ Empty (clear) the metadata for this Task and all sub-Tasks.
-
getAllSchemaCatalogs
()¶ Get schema catalogs for all tasks in the hierarchy, combining the results into a single dict.
- Returns
- schemacatalogs
dict
Keys are butler dataset type, values are a empty catalog (an instance of the appropriate lsst.afw.table Catalog type) for all tasks in the hierarchy, from the top-level task down through all subtasks.
- schemacatalogs
Notes
This method may be called on any task in the hierarchy; it will return the same answer, regardless.
The default implementation should always suffice. If your subtask uses schemas the override
Task.getSchemaCatalogs
, not this method.
-
getFullMetadata
()¶ Get metadata for all tasks.
- Returns
- metadata
lsst.daf.base.PropertySet
The
PropertySet
keys are the full task name. Values are metadata for the top-level task and all subtasks, sub-subtasks, etc..
- metadata
Notes
The returned metadata includes timing information (if
@timer.timeMethod
is used) and any metadata set by the task. The name of each item consists of the full task name with.
replaced by:
, followed by.
and the name of the item, e.g.:topLevelTaskName:subtaskName:subsubtaskName.itemName
using
:
in the full task name disambiguates the rare situation that a task has a subtask and a metadata item with the same name.
-
getFullName
()¶ Get the task name as a hierarchical name including parent task names.
- Returns
- fullName
str
The full name consists of the name of the parent task and each subtask separated by periods. For example:
The full name of top-level task “top” is simply “top”.
The full name of subtask “sub” of top-level task “top” is “top.sub”.
The full name of subtask “sub2” of subtask “sub” of top-level task “top” is “top.sub.sub2”.
- fullName
-
getSchemaCatalogs
()¶ Get the schemas generated by this task.
- Returns
- schemaCatalogs
dict
Keys are butler dataset type, values are an empty catalog (an instance of the appropriate
lsst.afw.table
Catalog type) for this task.
- schemaCatalogs
See also
Task.getAllSchemaCatalogs
Notes
Warning
Subclasses that use schemas must override this method. The default implemenation returns an empty dict.
This method may be called at any time after the Task is constructed, which means that all task schemas should be computed at construction time, not when data is actually processed. This reflects the philosophy that the schema should not depend on the data.
Returning catalogs rather than just schemas allows us to save e.g. slots for SourceCatalog as well.
-
getTaskDict
()¶ Get a dictionary of all tasks as a shallow copy.
- Returns
- taskDict
dict
Dictionary containing full task name: task object for the top-level task and all subtasks, sub-subtasks, etc..
- taskDict
-
classmethod
makeField
(doc)¶ Make a
lsst.pex.config.ConfigurableField
for this task.- Parameters
- doc
str
Help text for the field.
- doc
- Returns
- configurableField
lsst.pex.config.ConfigurableField
A
ConfigurableField
for this task.
- configurableField
Examples
Provides a convenient way to specify this task is a subtask of another task.
Here is an example of use:
class OtherTaskConfig(lsst.pex.config.Config) aSubtask = ATaskClass.makeField("a brief description of what this task does")
-
makeSubtask
(name, **keyArgs)¶ Create a subtask as a new instance as the
name
attribute of this task.- Parameters
- name
str
Brief name of the subtask.
- keyArgs
Extra keyword arguments used to construct the task. The following arguments are automatically provided and cannot be overridden:
“config”.
“parentTask”.
- name
Notes
The subtask must be defined by
Task.config.name
, an instance of pex_config ConfigurableField or RegistryField.
-
run
(subExposure, expandedSubExposure, fullBBox, template, **kwargs)¶ Perform ZOGY proper image subtraction on sub-images
This method performs ZOGY proper image subtraction on
subExposure
using local measures for image variances and PSF.subExposure
is a sub-exposure of the science image. It also requires the corresponding sub-exposures of the template (template
). The operations are actually performed onexpandedSubExposure
to allow for invalid edge pixels arising from convolutions, which are then removed.- Parameters
- subExposure
lsst.afw.image.Exposure
the sub-exposure of the diffim
- expandedSubExposure
lsst.afw.image.Exposure
the expanded sub-exposure upon which to operate
- fullBBox
lsst.geom.Box2I
the bounding box of the original exposure
- template
lsst.afw.image.Exposure
the template exposure, from which a corresponding sub-exposure is extracted
- **kwargs
additional keyword arguments propagated from
ImageMapReduceTask.run
. These include:doScorr
bool
Compute and return the corrected likelihood image S_corr rather than the proper image difference
inImageSpace
bool
Perform all convolutions in real (image) space rather than in Fourier space. This option currently leads to artifacts when using real (measured and noisy) PSFs, thus it is set to
False
by default. These kwargs may also include arguments to be propagated toZogyTask.computeDiffim
andZogyTask.computeScorr
.
- subExposure
- Returns
- result
lsst.pipe.base.Struct
Result struct with components:
subExposure
: Either the subExposure of the proper image differenceD
,or (if
doScorr==True
) the corrected likelihood exposureS
.
- result
Notes
This
run
method accepts parameters identical to those ofImageMapper.run
, since it is called from theImageMapperTask
. See that class for more information.
-
setup
(templateExposure=None, scienceExposure=None, sig1=None, sig2=None, psf1=None, psf2=None, correctBackground=False, *args, **kwargs)¶ Set up the ZOGY task.
- Parameters
- templateExposure
lsst.afw.image.Exposure
Template exposure (“Reference image” in ZOGY (2016)).
- scienceExposure
lsst.afw.image.Exposure
Science exposure (“New image” in ZOGY (2016)). Must have already been registered and photmetrically matched to template.
- sig1
float
(Optional) sqrt(variance) of
templateExposure
. IfNone
, it is computed from the sqrt(mean) of thetemplateExposure
variance image.- sig2
float
(Optional) sqrt(variance) of
scienceExposure
. IfNone
, it is computed from the sqrt(mean) of thescienceExposure
variance image.- psf12D
numpy.array
(Optional) 2D array containing the PSF image for the template. If
None
, it is extracted from the PSF taken at the center oftemplateExposure
.- psf22D
numpy.array
(Optional) 2D array containing the PSF image for the science img. If
None
, it is extracted from the PSF taken at the center ofscienceExposure
.- correctBackground
bool
(Optional) subtract sigma-clipped mean of exposures. Zogy doesn’t correct nonzero backgrounds (unlike AL) so subtract them here.
- *args
additional arguments to be passed to
lsst.pipe.base.Task
- **kwargs
additional keyword arguments to be passed to
lsst.pipe.base.Task
- templateExposure
-
timer
(name, logLevel=10000)¶ Context manager to log performance data for an arbitrary block of code.
- Parameters
- name
str
Name of code being timed; data will be logged using item name:
Start
andEnd
.- logLevel
A
lsst.log
level constant.
- name
See also
timer.logInfo
Examples
Creating a timer context:
with self.timer("someCodeToTime"): pass # code to time
-