lsst.meas.base  14.0-18-g5442b95
pluginRegistry.py
Go to the documentation of this file.
1 #!/usr/bin/env python
2 #
3 # LSST Data Management System
4 # Copyright 2008-2015 AURA/LSST.
5 #
6 # This product includes software developed by the
7 # LSST Project (http://www.lsst.org/).
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 LSST License Statement and
20 # the GNU General Public License along with this program. If not,
21 # see <http://www.lsstcorp.org/LegalNotices/>.
22 #
23 """Registry for measurement plugins and associated utilities generateAlgorithmName and PluginMap
24 """
25 import collections
26 
27 from builtins import object
28 
29 import lsst.pipe.base
30 import lsst.pex.config
31 from .apCorrRegistry import addApCorrName
32 
33 __all__ = ("generateAlgorithmName", "PluginRegistry", "register", "PluginMap")
34 
35 
36 def generateAlgorithmName(AlgClass):
37  """Generate a string name for an algorithm class that strips away terms that are generally redundant
38  while (hopefully) remaining easy to trace to the code.
39 
40  The returned name will cobmine the package name, with any "lsst" and/or "meas" prefix removed,
41  with the class name, with any "Algorithm" suffix removed. For instance,
42  lsst.meas.base.SdssShapeAlgorithm becomes "base_SdssShape".
43  """
44  name = AlgClass.__name__
45  pkg = AlgClass.__module__
46  name = name.replace("Algorithm", "")
47  terms = pkg.split(".")
48  # Hide private module name only if it's part of a public package
49  if len(terms) > 1 and terms[-1].startswith("_"):
50  terms = terms[:-1]
51  if len(terms) > 1 and terms[-1].endswith("Lib"):
52  terms = terms[:-1]
53  if terms[0] == "lsst":
54  terms = terms[1:]
55  if terms[0] == "meas":
56  terms = terms[1:]
57  if name.lower().startswith(terms[-1].lower()):
58  terms = terms[:-1]
59  return "%s_%s" % ("_".join(terms), name)
60 
61 
62 class PluginRegistry(lsst.pex.config.Registry):
63  """!
64  Base class for plugin registries
65 
66  The Plugin class allowed in the registry is defined in the ctor of the registry.
67 
68  Single-frame and forced plugins have different registries.
69  """
70 
71  class Configurable(object):
72  """!
73  Class used as the actual element in the registry
74 
75  Rather than constructing a Plugin instance, its __call__ method
76  (invoked by RegistryField.apply) returns a tuple
77  of (executionOrder, name, config, PluginClass), which can then
78  be sorted before the plugins are instantiated.
79  """
80 
81  __slots__ = "PluginClass", "name"
82 
83  def __init__(self, name, PluginClass):
84  """!
85  Create a Configurable object for the given PluginClass and name
86  """
87  self.name = name
88  self.PluginClass = PluginClass
89 
90  @property
91  def ConfigClass(self):
92  return self.PluginClass.ConfigClass
93 
94  def __call__(self, config):
95  return (self.PluginClass.getExecutionOrder(), self.name, config, self.PluginClass)
96 
97  def register(self, name, PluginClass, shouldApCorr=False, apCorrList=()):
98  """!
99  Register a Plugin class with the given name.
100 
101  The same Plugin may be registered multiple times with different names; this can
102  be useful if we often want to run it multiple times with different configuration.
103 
104  @param[in] name name of plugin class. This is used as a prefix for all fields produced by the Plugin,
105  and it should generally contain the name of the Plugin or Algorithm class itself
106  as well as enough of the namespace to make it clear where to find the code.
107  For example "base_GaussianFlux" indicates an algorithm in meas_base
108  that measures Gaussian Flux and produces fields such as "base_GaussianFlux_flux",
109  "base_GaussianFlux_fluxSigma" and "base_GaussianFlux_flag".
110  @param[in] shouldApCorr if True then this algorithm measures a flux that should be aperture
111  corrected. This is shorthand for apCorrList=[name] and is ignored if apCorrList is specified.
112  @param[in] apCorrList list of field name prefixes for flux fields that should be aperture corrected.
113  If an algorithm produces a single flux that should be aperture corrected then it is simpler
114  to set shouldApCorr=True. But if an algorithm produces multiple such fields then it must
115  specify apCorrList, instead. For example modelfit_CModel produces 3 such fields:
116  apCorrList=("modelfit_CModel_exp", "modelfit_CModel_exp", "modelfit_CModel_def")
117  If apCorrList is non-empty then shouldApCorr is ignored.
118  """
119  lsst.pex.config.Registry.register(self, name, self.Configurable(name, PluginClass))
120  if shouldApCorr and not apCorrList:
121  apCorrList = [name]
122  for prefix in apCorrList:
123  addApCorrName(prefix)
124 
125  def makeField(self, doc, default=None, optional=False, multi=False):
126  return lsst.pex.config.RegistryField(doc, self, default, optional, multi)
127 
128 
129 def register(name, shouldApCorr=False, apCorrList=()):
130  """!
131  A Python decorator that registers a class, using the given name, in its base class's PluginRegistry.
132  For example,
133  @code
134  @register("base_TransformedCentroid")
135  class ForcedTransformedCentroidPlugin(ForcedPlugin):
136  ...
137  @endcode
138  is equivalent to:
139  @code
140  class ForcedTransformedCentroidPlugin(ForcedPlugin):
141  ...
142  @ForcedPlugin.registry.register("base_TransformedCentroid", ForcedTransformedCentroidPlugin)
143  @endcode
144  """
145  def decorate(PluginClass):
146  PluginClass.registry.register(name, PluginClass, shouldApCorr=shouldApCorr, apCorrList=apCorrList)
147  return PluginClass
148  return decorate
149 
150 
151 class PluginMap(collections.OrderedDict):
152  """!
153  Map of plugins (instances of subclasses of BasePlugin) to be run for a task
154 
155  We assume plugins are added to the PluginMap according to their "Execution Order", so this
156  class doesn't actually do any of the sorting (though it does have to maintain that order,
157  which it does by inheriting from OrderedDict).
158  """
159 
160  def iter(self):
161  """!Return an iterator over plugins for which plugin.config.doMeasure is true
162 
163  @note plugin.config.doMeasure is usually a simple boolean class attribute, not a normal Config field.
164  """
165  for plugin in self.values():
166  if plugin.config.doMeasure:
167  yield plugin
168 
169  def iterN(self):
170  """!Return an iterator over plugins for which plugin.config.doMeasureN is true
171 
172  @note plugin.config.doMeasureN is usually a simple boolean class attribute, not a normal Config field.
173  """
174  for plugin in self.values():
175  if plugin.config.doMeasureN:
176  yield plugin
def makeField(self, doc, default=None, optional=False, multi=False)
def addApCorrName(name)
Add to the set of field name prefixes for fluxes that should be aperture corrected.
Class used as the actual element in the registry.
def register(name, shouldApCorr=False, apCorrList=())
A Python decorator that registers a class, using the given name, in its base class&#39;s PluginRegistry...
Base class for plugin registries.
def iter(self)
Return an iterator over plugins for which plugin.config.doMeasure is true.
Map of plugins (instances of subclasses of BasePlugin) to be run for a task.
def register(self, name, PluginClass, shouldApCorr=False, apCorrList=())
Register a Plugin class with the given name.
def iterN(self)
Return an iterator over plugins for which plugin.config.doMeasureN is true.
def __init__(self, name, PluginClass)
Create a Configurable object for the given PluginClass and name.