ForcedMeasurementTask¶
- class lsst.meas.base.ForcedMeasurementTask(refSchema, algMetadata=None, **kwds)¶
Bases:
BaseMeasurementTask
Measure sources on an image, constrained by a reference catalog.
A subtask for measuring the properties of sources on a single image, using an existing “reference” catalog to constrain some aspects of the measurement.
- Parameters:
- refSchema
lsst.afw.table.Schema
Schema of the reference catalog. Must match the catalog later passed to ‘ForcedMeasurementTask.generateMeasCat` and/or
ForcedMeasurementTask.run
.- algMetadata
lsst.daf.base.PropertyList
orNone
Will be updated in place to to record information about each algorithm. An empty
PropertyList
will be created ifNone
.- **kwds
Keyword arguments are passed to the supertask constructor.
- refSchema
Notes
Note that while
SingleFrameMeasurementTask
is passed an initialSchema
that is appended to in order to create the outputSchema
,ForcedMeasurementTask
is initialized with theSchema
of the reference catalog, from which a newSchema
for the output catalog is created. Fields to be copied directly from the referenceSchema
are added beforePlugin
fields are added.Attributes Summary
Metadata about active plugins (
lsst.daf.base.PropertyList
).Plugins to be invoked (
PluginMap
).Methods Summary
attachPsfShapeFootprints
(sources, exposure)Attach Footprints to blank sources prior to measurement, by creating elliptical Footprints from the PSF moments.
attachTransformedFootprints
(sources, refCat, ...)Attach Footprints to blank sources prior to measurement, by transforming Footprints attached to the reference catalog.
callMeasure
(measRecord, *args, **kwds)Call
measure
on all plugins and consistently handle exceptions.callMeasureN
(measCat, *args, **kwds)Call
measureN
on all plugins and consistently handle exceptions.doMeasurement
(plugin, measRecord, *args, **kwds)Call
measure
on the specified plugin.doMeasurementN
(plugin, measCat, *args, **kwds)Call
measureN
on the specified plugin.Empty (clear) the metadata for this Task and all sub-Tasks.
generateMeasCat
(exposure, refCat, refWcs[, ...])Initialize an output catalog from the reference catalog.
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.
initializePlugins
(**kwds)Initialize plugins (and slots) according to configuration.
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
(measCat, exposure, refCat, refWcs[, ...])Perform forced measurement.
timer
(name[, logLevel])Context manager to log performance data for an arbitrary block of code.
Attributes Documentation
- algMetadata = None¶
Metadata about active plugins (
lsst.daf.base.PropertyList
).Contains additional information about active plugins to be saved with the output catalog. Will be filled by subclasses.
- plugins = None¶
Plugins to be invoked (
PluginMap
).Initially empty, this will be populated as plugins are initialized. It should be considered read-only.
Methods Documentation
- attachPsfShapeFootprints(sources, exposure, scaling=3)¶
Attach Footprints to blank sources prior to measurement, by creating elliptical Footprints from the PSF moments.
- Parameters:
- sources
lsst.afw.table.SourceCatalog
Blank catalog (with all rows and columns, but values other than
coord_ra
,coord_dec
unpopulated). to which footprints should be attached.- exposure
lsst.afw.image.Exposure
Image object from which peak values and the PSF are obtained.
- scaling
int
, optional Scaling factor to apply to the PSF second-moments ellipse in order to determine the footprint boundary.
- sources
Notes
This is a utility function for use by parent tasks; see
attachTransformedFootprints
for more information.
- attachTransformedFootprints(sources, refCat, exposure, refWcs)¶
Attach Footprints to blank sources prior to measurement, by transforming Footprints attached to the reference catalog.
Notes
Footprint
s for forced photometry must be in the pixel coordinate system of the image being measured, while the actual detections may start out in a different coordinate system. This default implementation transforms the Footprints from the reference catalog from the WCS to the exposure’s WCS, which downgradesHeavyFootprint
s into regularFootprint
s, destroying deblend information.See the documentation for
run
for information about the relationships betweenrun
,generateMeasCat
, andattachTransformedFootprints
.
- callMeasure(measRecord, *args, **kwds)¶
Call
measure
on all plugins and consistently handle exceptions.- Parameters:
- measRecord
lsst.afw.table.SourceRecord
The record corresponding to the object being measured. Will be updated in-place with the results of measurement.
- *args
Positional arguments forwarded to
plugin.measure
- **kwds
Keyword arguments. Two are handled locally:
- beginOrder
int
Beginning execution order (inclusive). Measurements with
executionOrder
<beginOrder
are not executed.None
for no limit.- endOrder
int
Ending execution order (exclusive). Measurements with
executionOrder
>=endOrder
are not executed.None
for no limit.
Others are forwarded to
plugin.measure()
.- beginOrder
- measRecord
Notes
This method can be used with plugins that have different signatures; the only requirement is that
measRecord
be the first argument. Subsequent positional arguments and keyword arguments are forwarded directly to the plugin.This method should be considered “protected”: it is intended for use by derived classes, not users.
- callMeasureN(measCat, *args, **kwds)¶
Call
measureN
on all plugins and consistently handle exceptions.- Parameters:
- measCat
lsst.afw.table.SourceCatalog
Catalog containing only the records for the source family to be measured, and where outputs should be written.
- *args
Positional arguments forwarded to
plugin.measure()
- **kwds
Keyword arguments. Two are handled locally:
- beginOrder:
Beginning execution order (inclusive): Measurements with
executionOrder
<beginOrder
are not executed.None
for no limit.- endOrder:
Ending execution order (exclusive): measurements with
executionOrder
>=endOrder
are not executed.None
for nolimit
.
Others are are forwarded to
plugin.measure()
.
- measCat
Notes
This method can be used with plugins that have different signatures; the only requirement is that
measRecord
be the first argument. Subsequent positional arguments and keyword arguments are forwarded directly to the plugin.This method should be considered “protected”: it is intended for use by derived classes, not users.
- doMeasurement(plugin, measRecord, *args, **kwds)¶
Call
measure
on the specified plugin.Exceptions are handled in a consistent way.
- Parameters:
- pluginsubclass of
BasePlugin
Plugin that will be executed.
- measRecord
lsst.afw.table.SourceRecord
The record corresponding to the object being measured. Will be updated in-place with the results of measurement.
- *args
Positional arguments forwarded to
plugin.measure()
.- **kwds
Keyword arguments forwarded to
plugin.measure()
.
- pluginsubclass of
Notes
This method can be used with plugins that have different signatures; the only requirement is that
plugin
andmeasRecord
be the first two arguments. Subsequent positional arguments and keyword arguments are forwarded directly to the plugin.This method should be considered “protected”: it is intended for use by derived classes, not users.
- doMeasurementN(plugin, measCat, *args, **kwds)¶
Call
measureN
on the specified plugin.Exceptions are handled in a consistent way.
- Parameters:
- pluginsubclass of
BasePlugin
Plugin that will be executed.
- measCat
lsst.afw.table.SourceCatalog
Catalog containing only the records for the source family to be measured, and where outputs should be written.
- *args
Positional arguments forwarded to
plugin.measureN()
.- **kwds
Keyword arguments forwarded to
plugin.measureN()
.
- pluginsubclass of
Notes
This method can be used with plugins that have different signatures; the only requirement is that the
plugin
andmeasCat
be the first two arguments. Subsequent positional arguments and keyword arguments are forwarded directly to the plugin.This method should be considered “protected”: it is intended for use by derived classes, not users.
- generateMeasCat(exposure, refCat, refWcs, idFactory=None)¶
Initialize an output catalog from the reference catalog.
- Parameters:
- exposure
lsst.afw.image.exposureF
Image to be measured.
- refCatiterable of
lsst.afw.table.SourceRecord
Catalog of reference sources.
- refWcs
lsst.afw.geom.SkyWcs
Defines the X,Y coordinate system of
refCat
. This parameter is not currently used.- idFactory
lsst.afw.table.IdFactory
, optional Factory for creating IDs for sources.
- exposure
- Returns:
- meascat
lsst.afw.table.SourceCatalog
Source catalog ready for measurement.
- meascat
Notes
This generates a new blank
SourceRecord
for each record inrefCat
. Note that this method does not attach anyFootprint
s. Doing so is up to the caller (who may callattachedTransformedFootprints
or define their own method - seerun
for more information).
- getAllSchemaCatalogs() Dict[str, Any] ¶
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() TaskMetadata ¶
Get metadata for all tasks.
- Returns:
- metadata
TaskMetadata
The 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() str ¶
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() Dict[str, Any] ¶
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 implementation 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() Dict[str, ReferenceType[Task]] ¶
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
- initializePlugins(**kwds)¶
Initialize plugins (and slots) according to configuration.
- Parameters:
- **kwds
Keyword arguments forwarded directly to plugin constructors.
Notes
Derived class constructors should call this method to fill the
plugins
attribute and add corresponding output fields and slot aliases to the output schema.In addition to the attributes added by
BaseMeasurementTask.__init__
, aschema`
attribute holding the output schema must be present before this method is called.Keyword arguments are forwarded directly to plugin constructors, allowing derived classes to use plugins with different signatures.
- classmethod makeField(doc: str) ConfigurableField ¶
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("brief description of task")
- makeSubtask(name: str, **keyArgs: Any) None ¶
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 ofConfigurableField
orRegistryField
.
- run(measCat, exposure, refCat, refWcs, exposureId=None, beginOrder=None, endOrder=None)¶
Perform forced measurement.
- Parameters:
- exposure
lsst.afw.image.exposureF
Image to be measured. Must have at least a
lsst.afw.geom.SkyWcs
attached.- measCat
lsst.afw.table.SourceCatalog
Source catalog for measurement results; must be initialized with empty records already corresponding to those in
refCat
(via e.g.generateMeasCat
).- refCat
lsst.afw.table.SourceCatalog
A sequence of
lsst.afw.table.SourceRecord
objects that provide reference information for the measurement. These will be passed to each plugin in addition to the outputSourceRecord
.- refWcs
lsst.afw.geom.SkyWcs
Defines the X,Y coordinate system of
refCat
.- exposureId
int
, optional Optional unique exposureId used to calculate random number generator seed in the NoiseReplacer.
- beginOrder
int
, optional Beginning execution order (inclusive). Algorithms with
executionOrder
<beginOrder
are not executed.None
for no limit.- endOrder
int
, optional Ending execution order (exclusive). Algorithms with
executionOrder
>=endOrder
are not executed.None
for no limit.
- exposure
Notes
Fills the initial empty
SourceCatalog
with forced measurement results. Two steps must occur beforerun
can be called:generateMeasCat
must be called to create the outputmeasCat
argument.Footprint
s appropriate for the forced sources must be attached to themeasCat
records. TheattachTransformedFootprints
method can be used to do this, but this degrades “heavy” (i.e., including pixel values)Footprint
s to regularFootprint
s, leading to non-deblended measurement, so most callers should provideFootprint
s some other way. Typically, calling code will have access to information that will allow them to provide heavy footprints - for instance,ForcedPhotCoaddTask
uses the heavy footprints from deblending run in the same band just before non-forced is run measurement in that band.