ForcedMeasurementTask¶

class lsst.meas.base.ForcedMeasurementTask(refSchema, algMetadata=None, **kwds)¶

Bases: lsst.meas.base.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 or None: Will be updated in place to to record information about each algorithm. An empty PropertyList will be created if None.
**kwds: Keyword arguments are passed to the supertask constructor.

Notes

Note that while SingleFrameMeasurementTask is passed an initial Schema that is appended to in order to create the output Schema, ForcedMeasurementTask is initialized with the Schema of the reference catalog, from which a new Schema for the output catalog is created. Fields to be copied directly from the reference Schema are added before Plugin fields are added.

Attributes Summary

`algMetadata`
`plugins`

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.
`emptyMetadata`()	Empty (clear) the metadata for this Task and all sub-Tasks.
`generateMeasCat`(exposure, refCat, refWcs[, …])	Initialize an output catalog from the reference catalog.
`getAllSchemaCatalogs`()	Get schema catalogs for all tasks in the hierarchy, combining the results into a single dict.
`getFullMetadata`()	Get metadata for all tasks.
`getFullName`()	Get the task name as a hierarchical name including parent task names.
`getName`()	Get the name of the task.
`getSchemaCatalogs`()	Get the schemas generated by this task.
`getTaskDict`()	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¶

plugins = None¶

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.

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

Footprints 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 downgrades HeavyFootprints into regular Footprints, destroying deblend information.

See the documentation for run for information about the relationships between run, generateMeasCat, and attachTransformedFootprints.

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().

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 no limit.

Others are are forwarded to plugin.measure().

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:	plugin : subclass 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()`.

Notes

This method can be used with plugins that have different signatures; the only requirement is that plugin and measRecord 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:	plugin : subclass 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()`.

Notes

This method can be used with plugins that have different signatures; the only requirement is that the plugin and measCat 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.

emptyMetadata()¶: Empty (clear) the metadata for this Task and all sub-Tasks.

generateMeasCat(exposure, refCat, refWcs, idFactory=None)¶

Initialize an output catalog from the reference catalog.

Parameters:	exposure : `lsst.afw.image.exposureF` Image to be measured. refCat : iterable of `lsst.afw.table.SourceRecord` Catalog of reference sources. refWcs : `lsst.afw.geom.SkyWcs` Defines the X,Y coordinate system of `refCat`. idFactory : `lsst.afw.table.IdFactory`, optional Factory for creating IDs for sources.
Returns:	meascat : `lsst.afw.table.SourceCatalog` Source catalog ready for measurement.

Notes

This generates a new blank SourceRecord for each record in refCat. Note that this method does not attach any Footprints. Doing so is up to the caller (who may call attachedTransformedFootprints or define their own method - see run for more information).

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.

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 : `TaskMetadata` The keys are the full task name. Values are metadata for the top-level task and all subtasks, sub-subtasks, etc.

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”.

getName()¶

Get the name of the task.

Returns:	taskName : `str` Name of the task.

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()¶

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.

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__, a schema` 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)¶

Make a lsst.pex.config.ConfigurableField for this task.

Parameters:	doc : `str` Help text for the field.
Returns:	configurableField : `lsst.pex.config.ConfigurableField` A `ConfigurableField` for this task.

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, **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”.

Notes

The subtask must be defined by Task.config.name, an instance of ConfigurableField or RegistryField.

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 output SourceRecord.
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.

Notes

Fills the initial empty SourceCatalog with forced measurement results. Two steps must occur before run can be called:

generateMeasCat must be called to create the output measCat argument.
Footprints appropriate for the forced sources must be attached to the measCat records. The attachTransformedFootprints method can be used to do this, but this degrades “heavy” (i.e., including pixel values) Footprints to regular Footprints, leading to non-deblended measurement, so most callers should provide Footprints 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.

timer(name, logLevel=10)¶

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` and `End`. logLevel A `logging` level constant.

Navigation

ForcedMeasurementTask¶