LSST Applications  21.0.0+04719a4bac,21.0.0-1-ga51b5d4+f5e6047307,21.0.0-11-g2b59f77+a9c1acf22d,21.0.0-11-ga42c5b2+86977b0b17,21.0.0-12-gf4ce030+76814010d2,21.0.0-13-g1721dae+760e7a6536,21.0.0-13-g3a573fe+768d78a30a,21.0.0-15-g5a7caf0+f21cbc5713,21.0.0-16-g0fb55c1+b60e2d390c,21.0.0-19-g4cded4ca+71a93a33c0,21.0.0-2-g103fe59+bb20972958,21.0.0-2-g45278ab+04719a4bac,21.0.0-2-g5242d73+3ad5d60fb1,21.0.0-2-g7f82c8f+8babb168e8,21.0.0-2-g8f08a60+06509c8b61,21.0.0-2-g8faa9b5+616205b9df,21.0.0-2-ga326454+8babb168e8,21.0.0-2-gde069b7+5e4aea9c2f,21.0.0-2-gecfae73+1d3a86e577,21.0.0-2-gfc62afb+3ad5d60fb1,21.0.0-25-g1d57be3cd+e73869a214,21.0.0-3-g357aad2+ed88757d29,21.0.0-3-g4a4ce7f+3ad5d60fb1,21.0.0-3-g4be5c26+3ad5d60fb1,21.0.0-3-g65f322c+e0b24896a3,21.0.0-3-g7d9da8d+616205b9df,21.0.0-3-ge02ed75+a9c1acf22d,21.0.0-4-g591bb35+a9c1acf22d,21.0.0-4-g65b4814+b60e2d390c,21.0.0-4-gccdca77+0de219a2bc,21.0.0-4-ge8a399c+6c55c39e83,21.0.0-5-gd00fb1e+05fce91b99,21.0.0-6-gc675373+3ad5d60fb1,21.0.0-64-g1122c245+4fb2b8f86e,21.0.0-7-g04766d7+cd19d05db2,21.0.0-7-gdf92d54+04719a4bac,21.0.0-8-g5674e7b+d1bd76f71f,master-gac4afde19b+a9c1acf22d,w.2021.13
LSST Data Management Base Package
forcedMeasurement.py
Go to the documentation of this file.
1 # This file is part of meas_base.
2 #
3 # Developed for the LSST Data Management System.
4 # This product includes software developed by the LSST Project
5 # (https://www.lsst.org).
6 # See the COPYRIGHT file at the top-level directory of this distribution
7 # for details of code ownership.
8 #
9 # This program is free software: you can redistribute it and/or modify
10 # it under the terms of the GNU General Public License as published by
11 # the Free Software Foundation, either version 3 of the License, or
12 # (at your option) any later version.
13 #
14 # This program is distributed in the hope that it will be useful,
15 # but WITHOUT ANY WARRANTY; without even the implied warranty of
16 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
17 # GNU General Public License for more details.
18 #
19 # You should have received a copy of the GNU General Public License
20 # along with this program. If not, see <https://www.gnu.org/licenses/>.
21 
22 r"""Base classes for forced measurement plugins and the driver task for these.
23 
24 In forced measurement, a reference catalog is used to define restricted
25 measurements (usually just fluxes) on an image. As the reference catalog may
26 be deeper than the detection limit of the measurement image, we do not assume
27 that we can use detection and deblend information from the measurement image.
28 Instead, we assume this information is present in the reference catalog and
29 can be "transformed" in some sense to the measurement frame. At the very
30 least, this means that `~lsst.afw.detection.Footprint`\ s from the reference
31 catalog should be transformed and installed as Footprints in the output
32 measurement catalog. If we have a procedure that can transform "heavy"
33 Footprints (ie, including pixel data), we can then proceed with measurement as
34 usual, but using the reference catalog's ``id`` and ``parent`` fields to
35 define deblend families. If this transformation does not preserve
36 heavy Footprints (this is currently the case, at least for CCD forced
37 photometry), then we will only be able to replace objects with noise one
38 deblend family at a time, and hence measurements run in single-object mode may
39 be contaminated by neighbors when run on objects with ``parent != 0``.
40 
41 Measurements are generally recorded in the coordinate system of the image
42 being measured (and all slot-eligible fields must be), but non-slot fields may
43 be recorded in other coordinate systems if necessary to avoid information loss
44 (this should, of course, be indicated in the field documentation). Note that
45 the reference catalog may be in a different coordinate system; it is the
46 responsibility of plugins to transform the data they need themselves, using
47 the reference WCS provided. However, for plugins that only require a position
48 or shape, they may simply use output `~lsst.afw.table.SourceCatalog`\'s
49 centroid or shape slots, which will generally be set to the transformed
50 position of the reference object before any other plugins are run, and hence
51 avoid using the reference catalog at all.
52 
53 Command-line driver tasks for forced measurement include
54 `ForcedPhotCcdTask`, and `ForcedPhotCoaddTask`.
55 """
56 
57 import lsst.pex.config
58 import lsst.pipe.base
59 
60 from .pluginRegistry import PluginRegistry
61 from .baseMeasurement import (BaseMeasurementPluginConfig, BaseMeasurementPlugin,
62  BaseMeasurementConfig, BaseMeasurementTask)
63 from .noiseReplacer import NoiseReplacer, DummyNoiseReplacer
64 
65 __all__ = ("ForcedPluginConfig", "ForcedPlugin",
66  "ForcedMeasurementConfig", "ForcedMeasurementTask")
67 
68 
70  """Base class for configs of forced measurement plugins."""
71 
72  pass
73 
74 
76  """Base class for forced measurement plugins.
77 
78  Parameters
79  ----------
80  config : `ForcedPlugin.ConfigClass`
81  Configuration for this plugin.
82  name : `str`
83  The string with which the plugin was registered.
84  schemaMapper : `lsst.afw.table.SchemaMapper`
85  A mapping from reference catalog fields to output catalog fields.
86  Output fields should be added to the output schema. While most plugins
87  will not need to map fields from the reference schema, if they do so,
88  those fields will be transferred before any plugins are run.
89  metadata : `lsst.daf.base.PropertySet`
90  Plugin metadata that will be attached to the output catalog.
91  logName : `str`, optional
92  Name to use when logging errors.
93  """
94 
95  registry = PluginRegistry(ForcedPluginConfig)
96  """Subclasses of `ForcedPlugin` must be registered here (`PluginRegistry`).
97  """
98 
99  ConfigClass = ForcedPluginConfig
100 
101  def __init__(self, config, name, schemaMapper, metadata, logName=None):
102  BaseMeasurementPlugin.__init__(self, config, name, logName=logName)
103 
104  def measure(self, measRecord, exposure, refRecord, refWcs):
105  """Measure the properties of a source given an image and a reference.
106 
107  Parameters
108  ----------
109  exposure : `lsst.afw.image.ExposureF`
110  The pixel data to be measured, together with the associated PSF,
111  WCS, etc. All other sources in the image should have been replaced
112  by noise according to deblender outputs.
113  measRecord : `lsst.afw.table.SourceRecord`
114  Record describing the object being measured. Previously-measured
115  quantities will be retrieved from here, and it will be updated
116  in-place with the outputs of this plugin.
117  refRecord : `lsst.afw.table.SimpleRecord`
118  Additional parameters to define the fit, as measured elsewhere.
119  refWcs : `lsst.afw.geom.SkyWcs` or `lsst.afw.geom.Angle`
120  The coordinate system for the reference catalog values. An
121  `~lsst.geom.Angle` may be passed, indicating that a local tangent
122  WCS should be created for each object using the given angle as a
123  pixel scale.
124 
125  Notes
126  -----
127  In the normal mode of operation, the source centroid will be set to
128  the WCS-transformed position of the reference object, so plugins that
129  only require a reference position should not have to access the
130  reference object at all.
131  """
132  raise NotImplementedError()
133 
134  def measureN(self, measCat, exposure, refCat, refWcs):
135  """Measure the properties of blended sources from image & reference.
136 
137  This operates on all members of a blend family at once.
138 
139  Parameters
140  ----------
141  exposure : `lsst.afw.image.ExposureF`
142  The pixel data to be measured, together with the associated PSF,
143  WCS, etc. Sources not in the blended hierarchy to be measured
144  should have been replaced with noise using deblender outputs.
145  measCat : `lsst.afw.table.SourceCatalog`
146  Catalog describing the objects (and only those objects) being
147  measured. Previously-measured quantities will be retrieved from
148  here, and it will be updated in-place with the outputs of this
149  plugin.
150  refCat : `lsst.afw.table.SimpleCatalog`
151  Additional parameters to define the fit, as measured elsewhere.
152  Ordered such that ``zip(measCat, refcat)`` may be used.
153  refWcs : `lsst.afw.geom.SkyWcs` or `lsst.afw.geom.Angle`
154  The coordinate system for the reference catalog values. An
155  `~lsst.geom.Angle` may be passed, indicating that a local tangent
156  WCS should be created for each object using the given angle as a
157  pixel scale.
158 
159  Notes
160  -----
161  In the normal mode of operation, the source centroids will be set to
162  the WCS-transformed position of the reference object, so plugins that
163  only require a reference position should not have to access the
164  reference object at all.
165  """
166  raise NotImplementedError()
167 
168 
170  """Config class for forced measurement driver task.
171  """
172 
173  plugins = ForcedPlugin.registry.makeField(
174  multi=True,
175  default=["base_PixelFlags",
176  "base_TransformedCentroid",
177  "base_SdssCentroid",
178  "base_TransformedShape",
179  "base_SdssShape",
180  "base_GaussianFlux",
181  "base_CircularApertureFlux",
182  "base_PsfFlux",
183  "base_LocalBackground",
184  ],
185  doc="Plugins to be run and their configuration"
186  )
187  algorithms = property(lambda self: self.pluginsplugins, doc="backwards-compatibility alias for plugins")
188  undeblended = ForcedPlugin.registry.makeField(
189  multi=True,
190  default=[],
191  doc="Plugins to run on undeblended image"
192  )
193 
195  keytype=str, itemtype=str, doc="Mapping of reference columns to source columns",
196  default={"id": "objectId", "parent": "parentObjectId", "deblend_nChild": "deblend_nChild",
197  "coord_ra": "coord_ra", "coord_dec": "coord_dec"}
198  )
199 
200  checkUnitsParseStrict = lsst.pex.config.Field(
201  doc="Strictness of Astropy unit compatibility check, can be 'raise', 'warn' or 'silent'",
202  dtype=str,
203  default="raise",
204  )
205 
206  def setDefaults(self):
207  self.slotsslots.centroid = "base_TransformedCentroid"
208  self.slotsslots.shape = "base_TransformedShape"
209  self.slotsslots.apFlux = None
210  self.slotsslots.modelFlux = None
211  self.slotsslots.psfFlux = None
212  self.slotsslots.gaussianFlux = None
213  self.slotsslots.calibFlux = None
214 
215 
217  """Measure sources on an image, constrained by a reference catalog.
218 
219  A subtask for measuring the properties of sources on a single image,
220  using an existing "reference" catalog to constrain some aspects of the
221  measurement.
222 
223  Parameters
224  ----------
225  refSchema : `lsst.afw.table.Schema`
226  Schema of the reference catalog. Must match the catalog later passed
227  to 'ForcedMeasurementTask.generateMeasCat` and/or
228  `ForcedMeasurementTask.run`.
229  algMetadata : `lsst.daf.base.PropertyList` or `None`
230  Will be updated in place to to record information about each
231  algorithm. An empty `~lsst.daf.base.PropertyList` will be created if
232  `None`.
233  **kwds
234  Keyword arguments are passed to the supertask constructor.
235 
236  Notes
237  -----
238  Note that while `SingleFrameMeasurementTask` is passed an initial
239  `~lsst.afw.table.Schema` that is appended to in order to create the output
240  `~lsst.afw.table.Schema`, `ForcedMeasurementTask` is initialized with the
241  `~lsst.afw.table.Schema` of the reference catalog, from which a new
242  `~lsst.afw.table.Schema` for the output catalog is created. Fields to be
243  copied directly from the reference `~lsst.afw.table.Schema` are added
244  before ``Plugin`` fields are added.
245  """
246 
247  ConfigClass = ForcedMeasurementConfig
248 
249  def __init__(self, refSchema, algMetadata=None, **kwds):
250  super(ForcedMeasurementTask, self).__init__(algMetadata=algMetadata, **kwds)
251  self.mappermapper = lsst.afw.table.SchemaMapper(refSchema)
252  self.mappermapper.addMinimalSchema(lsst.afw.table.SourceTable.makeMinimalSchema(), False)
253  self.configconfig.slots.setupSchema(self.mappermapper.editOutputSchema())
254  for refName, targetName in self.configconfig.copyColumns.items():
255  refItem = refSchema.find(refName)
256  self.mappermapper.addMapping(refItem.key, targetName)
257  self.configconfig.slots.setupSchema(self.mappermapper.editOutputSchema())
258  self.initializePluginsinitializePlugins(schemaMapper=self.mappermapper)
259  self.schemaschema = self.mappermapper.getOutputSchema()
260  self.schemaschema.checkUnits(parse_strict=self.configconfig.checkUnitsParseStrict)
261 
262  def run(self, measCat, exposure, refCat, refWcs, exposureId=None, beginOrder=None, endOrder=None):
263  r"""Perform forced measurement.
264 
265  Parameters
266  ----------
267  exposure : `lsst.afw.image.exposureF`
268  Image to be measured. Must have at least a `lsst.afw.geom.SkyWcs`
269  attached.
270  measCat : `lsst.afw.table.SourceCatalog`
271  Source catalog for measurement results; must be initialized with
272  empty records already corresponding to those in ``refCat`` (via
273  e.g. `generateMeasCat`).
274  refCat : `lsst.afw.table.SourceCatalog`
275  A sequence of `lsst.afw.table.SourceRecord` objects that provide
276  reference information for the measurement. These will be passed
277  to each plugin in addition to the output
278  `~lsst.afw.table.SourceRecord`.
279  refWcs : `lsst.afw.geom.SkyWcs`
280  Defines the X,Y coordinate system of ``refCat``.
281  exposureId : `int`, optional
282  Optional unique exposureId used to calculate random number
283  generator seed in the NoiseReplacer.
284  beginOrder : `int`, optional
285  Beginning execution order (inclusive). Algorithms with
286  ``executionOrder`` < ``beginOrder`` are not executed. `None` for no limit.
287  endOrder : `int`, optional
288  Ending execution order (exclusive). Algorithms with
289  ``executionOrder`` >= ``endOrder`` are not executed. `None` for no limit.
290 
291  Notes
292  -----
293  Fills the initial empty `~lsst.afw.table.SourceCatalog` with forced
294  measurement results. Two steps must occur before `run` can be called:
295 
296  - `generateMeasCat` must be called to create the output ``measCat``
297  argument.
298  - `~lsst.afw.detection.Footprint`\ s appropriate for the forced sources
299  must be attached to the ``measCat`` records. The
300  `attachTransformedFootprints` method can be used to do this, but
301  this degrades "heavy" (i.e., including pixel values)
302  `~lsst.afw.detection.Footprint`\s to regular
303  `~lsst.afw.detection.Footprint`\s, leading to non-deblended
304  measurement, so most callers should provide
305  `~lsst.afw.detection.Footprint`\s some other way. Typically, calling
306  code will have access to information that will allow them to provide
307  heavy footprints - for instance, `ForcedPhotCoaddTask` uses the
308  heavy footprints from deblending run in the same band just before
309  non-forced is run measurement in that band.
310  """
311  # First check that the reference catalog does not contain any children
312  # for which any member of their parent chain is not within the list.
313  # This can occur at boundaries when the parent is outside and one of
314  # the children is within. Currently, the parent chain is always only
315  # one deep, but just in case, this code checks for any case where when
316  # the parent chain to a child's topmost parent is broken and raises an
317  # exception if it occurs.
318  #
319  # I.e. this code checks that this precondition is satisfied by
320  # whatever reference catalog provider is being paired with it.
321  refCatIdDict = {ref.getId(): ref.getParent() for ref in refCat}
322  for ref in refCat:
323  refId = ref.getId()
324  topId = refId
325  while(topId > 0):
326  if topId not in refCatIdDict:
327  raise RuntimeError("Reference catalog contains a child for which at least "
328  "one parent in its parent chain is not in the catalog.")
329  topId = refCatIdDict[topId]
330 
331  # Construct a footprints dict which looks like
332  # {ref.getId(): (ref.getParent(), source.getFootprint())}
333  # (i.e. getting the footprint from the transformed source footprint)
334  footprints = {ref.getId(): (ref.getParent(), measRecord.getFootprint())
335  for (ref, measRecord) in zip(refCat, measCat)}
336 
337  self.loglog.info("Performing forced measurement on %d source%s", len(refCat),
338  "" if len(refCat) == 1 else "s")
339 
340  if self.configconfig.doReplaceWithNoise:
341  noiseReplacer = NoiseReplacer(self.configconfig.noiseReplacer, exposure,
342  footprints, log=self.loglog, exposureId=exposureId)
343  algMetadata = measCat.getTable().getMetadata()
344  if algMetadata is not None:
345  algMetadata.addInt("NOISE_SEED_MULTIPLIER", self.configconfig.noiseReplacer.noiseSeedMultiplier)
346  algMetadata.addString("NOISE_SOURCE", self.configconfig.noiseReplacer.noiseSource)
347  algMetadata.addDouble("NOISE_OFFSET", self.configconfig.noiseReplacer.noiseOffset)
348  if exposureId is not None:
349  algMetadata.addLong("NOISE_EXPOSURE_ID", exposureId)
350  else:
351  noiseReplacer = DummyNoiseReplacer()
352 
353  # Create parent cat which slices both the refCat and measCat (sources)
354  # first, get the reference and source records which have no parent
355  refParentCat, measParentCat = refCat.getChildren(0, measCat)
356  for parentIdx, (refParentRecord, measParentRecord) in enumerate(zip(refParentCat, measParentCat)):
357 
358  # first process the records which have the current parent as children
359  refChildCat, measChildCat = refCat.getChildren(refParentRecord.getId(), measCat)
360  # TODO: skip this loop if there are no plugins configured for single-object mode
361  for refChildRecord, measChildRecord in zip(refChildCat, measChildCat):
362  noiseReplacer.insertSource(refChildRecord.getId())
363  self.callMeasurecallMeasure(measChildRecord, exposure, refChildRecord, refWcs,
364  beginOrder=beginOrder, endOrder=endOrder)
365  noiseReplacer.removeSource(refChildRecord.getId())
366 
367  # then process the parent record
368  noiseReplacer.insertSource(refParentRecord.getId())
369  self.callMeasurecallMeasure(measParentRecord, exposure, refParentRecord, refWcs,
370  beginOrder=beginOrder, endOrder=endOrder)
371  self.callMeasureNcallMeasureN(measParentCat[parentIdx:parentIdx+1], exposure,
372  refParentCat[parentIdx:parentIdx+1],
373  beginOrder=beginOrder, endOrder=endOrder)
374  # measure all the children simultaneously
375  self.callMeasureNcallMeasureN(measChildCat, exposure, refChildCat,
376  beginOrder=beginOrder, endOrder=endOrder)
377  noiseReplacer.removeSource(refParentRecord.getId())
378  noiseReplacer.end()
379 
380  # Undeblended plugins only fire if we're running everything
381  if endOrder is None:
382  for measRecord, refRecord in zip(measCat, refCat):
383  for plugin in self.undeblendedPluginsundeblendedPlugins.iter():
384  self.doMeasurementdoMeasurement(plugin, measRecord, exposure, refRecord, refWcs)
385 
386  def generateMeasCat(self, exposure, refCat, refWcs, idFactory=None):
387  r"""Initialize an output catalog from the reference catalog.
388 
389  Parameters
390  ----------
391  exposure : `lsst.afw.image.exposureF`
392  Image to be measured.
393  refCat : iterable of `lsst.afw.table.SourceRecord`
394  Catalog of reference sources.
395  refWcs : `lsst.afw.geom.SkyWcs`
396  Defines the X,Y coordinate system of ``refCat``.
397  idFactory : `lsst.afw.table.IdFactory`, optional
398  Factory for creating IDs for sources.
399 
400  Returns
401  -------
402  meascat : `lsst.afw.table.SourceCatalog`
403  Source catalog ready for measurement.
404 
405  Notes
406  -----
407  This generates a new blank `~lsst.afw.table.SourceRecord` for each
408  record in ``refCat``. Note that this method does not attach any
409  `~lsst.afw.detection.Footprint`\ s. Doing so is up to the caller (who
410  may call `attachedTransformedFootprints` or define their own method -
411  see `run` for more information).
412  """
413  if idFactory is None:
415  table = lsst.afw.table.SourceTable.make(self.schemaschema, idFactory)
416  measCat = lsst.afw.table.SourceCatalog(table)
417  table = measCat.table
418  table.setMetadata(self.algMetadataalgMetadata)
419  table.preallocate(len(refCat))
420  for ref in refCat:
421  newSource = measCat.addNew()
422  newSource.assign(ref, self.mappermapper)
423  return measCat
424 
425  def attachTransformedFootprints(self, sources, refCat, exposure, refWcs):
426  r"""Attach Footprints to blank sources prior to measurement.
427 
428  Notes
429  -----
430  `~lsst.afw.detection.Footprint`\s for forced photometry must be in the
431  pixel coordinate system of the image being measured, while the actual
432  detections may start out in a different coordinate system. This
433  default implementation transforms the Footprints from the reference
434  catalog from the WCS to the exposure's WCS, which downgrades
435  ``HeavyFootprint``\s into regular `~lsst.afw.detection.Footprint`\s,
436  destroying deblend information.
437 
438  See the documentation for `run` for information about the
439  relationships between `run`, `generateMeasCat`, and
440  `attachTransformedFootprints`.
441  """
442  exposureWcs = exposure.getWcs()
443  region = exposure.getBBox(lsst.afw.image.PARENT)
444  for srcRecord, refRecord in zip(sources, refCat):
445  srcRecord.setFootprint(refRecord.getFootprint().transform(refWcs, exposureWcs, region))
static std::shared_ptr< IdFactory > makeSimple()
Return a simple IdFactory that simply counts from 1.
Definition: IdFactory.cc:70
A mapping between the keys of two Schemas, used to copy data between them.
Definition: SchemaMapper.h:21
static std::shared_ptr< SourceTable > make(Schema const &schema, std::shared_ptr< IdFactory > const &idFactory)
Construct a new table.
Definition: Source.cc:382
static Schema makeMinimalSchema()
Return a minimal schema for Source tables and records.
Definition: Source.h:260
def doMeasurement(self, plugin, measRecord, *args, **kwds)
def callMeasure(self, measRecord, *args, **kwds)
def callMeasureN(self, measCat, *args, **kwds)
def attachTransformedFootprints(self, sources, refCat, exposure, refWcs)
def __init__(self, refSchema, algMetadata=None, **kwds)
def run(self, measCat, exposure, refCat, refWcs, exposureId=None, beginOrder=None, endOrder=None)
def generateMeasCat(self, exposure, refCat, refWcs, idFactory=None)
def measureN(self, measCat, exposure, refCat, refWcs)
def measure(self, measRecord, exposure, refRecord, refWcs)
def __init__(self, config, name, schemaMapper, metadata, logName=None)