SimplifiedSubtractTask¶

Description¶

This task implements a streamlined image differencing pipeline designed to operate without requiring an input source catalog, while optionally allowing the reuse of an existing point spread function (PSF) matching kernel. The pipeline supports two primary execution methods, each aligned with distinct scientific objectives:

Existing Kernel Method—Utilizes a previously computed PSF matching kernel to reproduce the results of a prior image differencing run.

Derived Kernel Method—Computes the PSF matching kernel internally by performing a streamlined source detection and measurement process, enabling image differencing with minimal required inputs.

Simplified Image Differencing Pipeline with the Existing Kernel Method¶

Use a local version of the AP pipeline configuration to run the pipeline by reusing a precomputed PSF matching kernel. The sample pipeline file, simpleDiffim_existingKernel.yaml, shown below, demonstrates the recommended configuration settings for this method.

description: A simplified single-visit difference image pipeline that reuses an existing PSF matching kernel to reproduce the results of a previous image differencing run.
instrument: lsst.obs.lsst.LsstCam
tasks:
  rewarpTemplate:
    class: lsst.ip.diffim.getTemplate.GetTemplateTask
    config:
      connections.bbox: preliminary_visit_image.bbox
      connections.wcs: preliminary_visit_image.wcs
      connections.coaddExposures: template_coadd
      connections.template: template_detector
  simplifiedSubtractImages:
    class: lsst.ip.diffim.SimplifiedSubtractTask
    config:
      connections.template: template_detector
      connections.science: preliminary_visit_image
      connections.difference: difference_image_predetection
      connections.matchedTemplate: template_matched
      connections.inputPsfMatchingKernel: difference_kernel
      useExistingKernel: True

  detectAndMeasureDiaSource:
    class: lsst.ip.diffim.detectAndMeasure.DetectAndMeasureTask
    config:
      connections.science: preliminary_visit_image
      connections.matchedTemplate: template_matched
      connections.difference:  difference_image_predetection
      connections.outputSchema: dia_source_schema
      connections.diaSources: dia_source_unfiltered
      connections.subtractedMeasuredExposure: difference_image
      connections.maskedStreaks: goodSeeingDiff_streaks
      doSkySources: True
      doCalculateResidualMetics: False

Simplified Image Differencing Pipeline with the Derived Kernel Method¶

Alternatively, the pipeline can compute the PSF matching kernel internally by performing source detection and measurement. This method requires the minimal set of inputs necessary to execute image differencing. The sample pipeline tailored for this mode, simpleDiffim_derivedKernel.yaml, shown below, includes the recommended configuration settings for the Derived Kernel Method.

description: A simplified single-visit difference image pipeline to produce image differencing results with the minimal reqired inputs.
instrument: lsst.obs.lsst.LsstCam
tasks:
  rewarpTemplate:
    class: lsst.ip.diffim.getTemplate.GetTemplateTask
    config:
      connections.bbox: preliminary_visit_image.bbox
      connections.wcs: preliminary_visit_image.wcs
      connections.coaddExposures: template_coadd
      connections.template: template_detector
  simplifiedSubtractImages:
    class: lsst.ip.diffim.SimplifiedSubtractTask
    config:
      connections.template: template_detector
      connections.science: preliminary_visit_image
      connections.difference: difference_image_predetection
      connections.matchedTemplate: template_matched
      connections.kernelSources: difference_kernel_sources
      connections.psfMatchingKernel: difference_kernel
      useExistingKernel: False

  detectAndMeasureDiaSource:
    class: lsst.ip.diffim.detectAndMeasure.DetectAndMeasureTask
    config:
      connections.science: preliminary_visit_image
      connections.matchedTemplate: template_matched
      connections.difference:  difference_image_predetection
      connections.kernelSources: difference_kernel_sources
      connections.outputSchema: dia_source_schema
      connections.diaSources: dia_source_unfiltered
      connections.subtractedMeasuredExposure: difference_image
      connections.maskedStreaks: goodSeeingDiff_streaks
      doSkySources: True
      doCalculateResidualMetics: True

Execute the Simplified Image Differencing Pipeline Using `pipetask run`¶

To execute the pipline using the pipetask run method, implement the following code:

pipetask run -b /repo/main -i /input/collections -o /your/output/collection -d "instrument='LSSTCam' and exposure=2025050100367 and detector=30 and skymap='lsst_cells_v1'" -p /path/to/your/simpleDiffim.yaml

Python API summary¶

from lsst.ip.diffim.subtractImages import SimplifiedSubtractTask

classSimplifiedSubtractTask(**kwargs): Compute the image difference of a science and template image using the Alard & Lupton (1998) algorithm...

attributeconfig: Access configuration fields and retargetable subtasks.

methodrun(template, science, visitSummary=None, inputPsfMatchingKernel=None): PSF match, subtract, and decorrelate two images...

Retargetable subtasks¶

decorrelate¶

Default: lsst.ip.diffim.imageDecorrelation.DecorrelateALKernelTask
Field type: ConfigurableField

Task to decorrelate the image difference.

fallbackSourceSelector¶

Default: lsst.meas.algorithms.sourceSelector.ScienceSourceSelectorTask
Field type: ConfigurableField

Task to select sources to be used for PSF matching.Used only if the kernel calculation fails and`allowKernelSourceDetection` is set. The fallback source detection will not include all of the same plugins as the original source detection, so not all of the same flags can be used.

makeKernel¶

Default: lsst.ip.diffim.makeKernel.MakeKernelTask
Field type: ConfigurableField

Task to construct a matching kernel for convolution.

scaleVariance¶

Default: lsst.meas.algorithms.scaleVariance.ScaleVarianceTask
Field type: ConfigurableField

Subtask to rescale the variance of the template to the statistically expected level.

sourceSelector¶

Default: lsst.meas.algorithms.sourceSelector.ScienceSourceSelectorTask
Field type: ConfigurableField

Task to select sources to be used for PSF matching.

Configuration fields¶

allowKernelSourceDetection¶

Default: False
Field type: bool Field

Re-run source detection for kernel candidates if an error is encountered while calculating the matching kernel.

badMaskPlanes¶

Default: ('NO_DATA', 'BAD', 'SAT', 'EDGE')
Field type: str ListField

Mask planes to interpolate over.

connections¶

Data type: lsst.pipe.base.config.SimplifiedSubtractConfigConnections
Field type: ConfigField

Configurations describing the connections of the PipelineTask to datatypes

detectionThreshold¶

Default: 10
Field type: float Field

Minimum signal to noise ratio of detected sources to use for calculating the PSF matching kernel. Deprecated: No longer used. Will be removed after v30

detectionThresholdMax¶

Default: 500
Field type: float Field

Maximum signal to noise ratio of detected sources to use for calculating the PSF matching kernel. Deprecated: No longer used. Will be removed after v30

doApplyExternalCalibrations¶

Default: False
Field type: bool Field

Replace science Exposure’s calibration objects with those in visitSummary. Ignored if `doApplyFinalizedPsf is True.

doDecorrelation¶

Default: True
Field type: bool Field

Perform diffim decorrelation to undo pixel correlation due to A&L kernel convolution? If True, also update the diffim PSF.

doScaleVariance¶

Default: True
Field type: bool Field

Scale variance of the image difference?

doSubtractBackground¶

Default: False
Field type: bool Field

Subtract the background fit when solving the kernel? It is generally better to instead subtract the background in detectAndMeasure.

excludeMaskPlanes¶

Default: ('NO_DATA', 'BAD', 'SAT', 'EDGE', 'FAKE', 'HIGH_VARIANCE')
Field type: str ListField

Template mask planes to exclude when selecting sources for PSF matching.

maxKernelSources¶

Default: 1000
Field type: int Field

Maximum number of sources to use for calculating the PSF matching kernel.Set to -1 to disable.

minKernelSources¶

Default: 3
Field type: int Field

Minimum number of sources needed for calculating the PSF matching kernel.

minTemplateFractionForExpectedSuccess¶

Default: 0.2
Field type: float Field

Raise NoWorkFound if PSF-matching fails and template covers less than this fraction of pixels. If the fraction of pixels covered by the template is less than this value (and greater than requiredTemplateFraction) this task is attempted but failure is anticipated and tolerated.

mode¶

Default

'convolveTemplate'

Field type

str ChoiceField (optional)

Choices

'auto': Choose which image to convolve at runtime.
'convolveScience': Only convolve the science image.
'convolveTemplate': Only convolve the template image.
None: Field is optional

Choose which image to convolve at runtime, or require that a specific image is convolved.

preserveTemplateMask¶

Default: ('NO_DATA', 'BAD', 'HIGH_VARIANCE')
Field type: str ListField

Mask planes from the template to propagate to the image difference.

renameTemplateMask¶

Default: ('SAT', 'INJECTED', 'INJECTED_CORE')
Field type: str ListField

Mask planes from the template to propagate to the image differencewith ‘_TEMPLATE’ appended to the name.

requiredTemplateFraction¶

Default: 0.1
Field type: float Field

Raise NoWorkFound and do not attempt image subtraction if template covers less than this fraction of pixels. Setting to 0 will always attempt image subtraction.

restrictKernelEdgeSources¶

Default: True
Field type: bool Field

Exclude sources close to the edge from the kernel calculation?

saveLogOutput¶

Default: True
Field type: bool Field

Flag to enable/disable saving of log output for a task, enabled by default.

useExistingKernel¶

Default: True
Field type: bool Field

Use a pre-existing PSF matching kernel?If False, source detection and measurement will be run.

Navigation