Coverage for python / lsst / meas / base / catalogCalculation.py: 32%

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 

22from collections import namedtuple 

23 

24import lsst.pipe.base 

25import lsst.pex.config 

26import lsst.daf.base 

27from lsst.utils.timer import timeMethod 

28 

29from .pluginsBase import BasePlugin, BasePluginConfig 

30from .pluginRegistry import PluginRegistry, PluginMap 

31from ._measBaseLib import FatalAlgorithmError, MeasurementError 

32 

33# Exceptions that the measurement tasks should always propagate up to their 

34# callers 

35FATAL_EXCEPTIONS = (MemoryError, FatalAlgorithmError) 

36 

37__all__ = ("CatalogCalculationPluginConfig", "CatalogCalculationPlugin", "CatalogCalculationConfig", 

38 "CatalogCalculationTask") 

39 

40 

41class CatalogCalculationPluginConfig(BasePluginConfig): 

42 """Default configuration class for catalog calcuation plugins. 

43 """ 

44 pass 

45 

46 

47class CatalogCalculationPlugin(BasePlugin): 

48 """Base class for catalog calculation plugins. 

49 

50 Parameters 

51 ---------- 

52 config : `CatalogCalculationPlugin.ConfigClass` 

53 Plugin configuration. 

54 name : `str` 

55 The string the plugin was registered with. 

56 schema : `lsst.afw.table.Schema` 

57 The source schema, New fields should be added here to 

58 hold output produced by this plugin. 

59 metadata : `lsst.daf.base.PropertySet` 

60 Plugin metadata that will be attached to the output catalog 

61 """ 

62 

63 ConfigClass = CatalogCalculationPluginConfig # documentation inherited 

64 

65 registry = PluginRegistry(CatalogCalculationPluginConfig) 

66 """List of available plugins (`lsst.meas.base.PluginRegistry`). 

67 """ 

68 

69 plugType = 'single' 

70 """Does the plugin operate on a single source or the whole catalog (`str`)? 

71 

72 If the plugin operates on a single source at a time, this should be set to 

73 ``"single"``; if it expects the whoe catalog, to ``"multi"``. If the 

74 plugin is of type ``"multi"``, the `fail` method must be implemented to 

75 accept the whole catalog. If the plugin is of type ``"single"``, `fail` 

76 should accept a single source record. 

77 """ 

78 

79 def __init__(self, config, name, schema, metadata): 

80 BasePlugin.__init__(self, config, name) 

81 

82 @classmethod 

83 def getExecutionOrder(cls): 

84 r"""Used to set the relative order of plugin execution. 

85 

86 The values returned by `getExecutionOrder` are compared across all 

87 plugins, and smaller numbers run first. 

88 

89 Notes 

90 ----- 

91 `CatalogCalculationPlugin`\s must run with 

92 `BasePlugin.DEFAULT_CATALOGCALCULATION` or higher. 

93 

94 All plugins must implement this method with an appropriate run level 

95 """ 

96 raise NotImplementedError() 

97 

98 def calculate(self, cat, **kwargs): 

99 """Perform the calculation specified by this plugin. 

100 

101 This method can either be used to operate on a single catalog record 

102 or a whole catalog, populating it with the output defined by this 

103 plugin. 

104 

105 Note that results may be added to catalog records as new columns, or 

106 may result in changes to existing values. 

107 

108 Parameters 

109 ---------- 

110 cat : `lsst.afw.table.SourceCatalog` or `lsst.afw.table.SourceRecord` 

111 May either be a `~lsst.afw.table.SourceCatalog` or a single 

112 `~lsst.afw.table.SourceRecord`, depending on the plugin type. Will 

113 be updated in place to contain the results of plugin execution. 

114 **kwargs 

115 Any additional keyword arguments that may be passed to the plugin. 

116 """ 

117 raise NotImplementedError() 

118 

119 

120class CCContext: 

121 """Handle errors that are thrown by catalog calculation plugins. 

122 

123 This is a context manager. 

124 

125 Parameters 

126 ---------- 

127 plugin : `CatalogCalculationPlugin` 

128 The plugin that is to be run. 

129 cat : `lsst.afw.table.SourceCatalog` or `lsst.afw.table.SourceRecord` 

130 May either be a `~lsst.afw.table.SourceCatalog` or a single 

131 `~lsst.afw.table.SourceRecord`, depending on the plugin type. 

132 log : `lsst.log.Log` or `logging.Logger` 

133 A logger. Generally, this should be the logger of the object in which 

134 the context manager is being used. 

135 """ 

136 def __init__(self, plugin, cat, log): 

137 self.plugin = plugin 

138 self.cat = cat 

139 self.log = log 

140 

141 def __enter__(self): 

142 return 

143 

144 def __exit__(self, exc_type, exc_value, traceback): 

145 if exc_type is None: 

146 return True 

147 if exc_type in FATAL_EXCEPTIONS: 

148 return False 

149 elif exc_type is MeasurementError: 

150 self.plugin.fail(self.cat, exc_value) 

151 elif issubclass(exc_type, Exception): 

152 self.log.warning("Error in %s.calculate: %s", self.plugin.name, exc_value) 

153 else: 

154 # In general, BaseExceptions are unrelated to the code and should not be caught 

155 return False 

156 return True 

157 

158 

159class CatalogCalculationConfig(lsst.pex.config.Config): 

160 """Config class for the catalog calculation driver task. 

161 

162 Specifies which plugins will execute when the `CatalogCalculationTask` 

163 associated with this configuration is run. 

164 """ 

165 

166 plugins = CatalogCalculationPlugin.registry.makeField( 

167 multi=True, 

168 default=["base_ClassificationExtendedness", 

169 "base_FootprintArea"], 

170 doc="Plugins to be run and their configuration") 

171 

172 

173class CatalogCalculationTask(lsst.pipe.base.Task): 

174 """Run plugins which operate on a catalog of sources. 

175 

176 This task facilitates running plugins which will operate on a source 

177 catalog. These plugins may do things such as classifying an object based 

178 on source record entries inserted during a measurement task. 

179 

180 Parameters 

181 ---------- 

182 plugMetaData : `lsst.daf.base.PropertyList` or `None` 

183 Will be modified in-place to contain metadata about the plugins being 

184 run. If `None`, an empty `~lsst.daf.base.PropertyList` will be 

185 created. 

186 **kwargs 

187 Additional arguments passed to the superclass constructor. 

188 

189 Notes 

190 ----- 

191 Plugins may either take an entire catalog to work on at a time, or work on 

192 individual records. 

193 """ 

194 ConfigClass = CatalogCalculationConfig 

195 _DefaultName = "catalogCalculation" 

196 

197 def __init__(self, schema, plugMetadata=None, **kwargs): 

198 lsst.pipe.base.Task.__init__(self, **kwargs) 

199 self.schema = schema 

200 if plugMetadata is None: 

201 plugMetadata = lsst.daf.base.PropertyList() 

202 self.plugMetadata = plugMetadata 

203 self.plugins = PluginMap() 

204 

205 self.initializePlugins() 

206 

207 def initializePlugins(self): 

208 """Initialize the plugins according to the configuration. 

209 """ 

210 

211 pluginType = namedtuple('pluginType', 'single multi') 

212 self.executionDict = {} 

213 # Read the properties for each plugin. Allocate a dictionary entry for each run level. Verify that 

214 # the plugins are above the minimum run level for an catalogCalculation plugin. For each run level, 

215 # the plugins are sorted into either single record, or multi record groups to later be run 

216 # appropriately 

217 for executionOrder, name, config, PluginClass in sorted(self.config.plugins.apply()): 

218 if executionOrder not in self.executionDict: 

219 self.executionDict[executionOrder] = pluginType(single=[], multi=[]) 

220 if PluginClass.getExecutionOrder() >= BasePlugin.DEFAULT_CATALOGCALCULATION: 

221 plug = PluginClass(config, name, self.schema, metadata=self.plugMetadata) 

222 self.plugins[name] = plug 

223 if plug.plugType == 'single': 

224 self.executionDict[executionOrder].single.append(plug) 

225 elif plug.plugType == 'multi': 

226 self.executionDict[executionOrder].multi.append(plug) 

227 else: 

228 errorTuple = (PluginClass, PluginClass.getExecutionOrder(), 

229 BasePlugin.DEFAULT_CATALOGCALCULATION) 

230 raise ValueError("{} has an execution order less than the minimum for an catalogCalculation " 

231 "plugin. Value {} : Minimum {}".format(*errorTuple)) 

232 

233 @timeMethod 

234 def run(self, measCat): 

235 """The entry point for the catalog calculation task. 

236 

237 Parameters 

238 ---------- 

239 meascat : `lsst.afw.table.SourceCatalog` 

240 Catalog for measurement. 

241 """ 

242 self.callCompute(measCat) 

243 

244 def callCompute(self, catalog): 

245 """Run each of the plugins on the catalog. 

246 

247 Parameters 

248 ---------- 

249 catalog : `lsst.afw.table.SourceCatalog` 

250 The catalog on which the plugins will operate. 

251 """ 

252 for runlevel in sorted(self.executionDict): 

253 # Run all of the plugins which take a whole catalog first 

254 for plug in self.executionDict[runlevel].multi: 

255 with CCContext(plug, catalog, self.log): 

256 plug.calculate(catalog) 

257 # Run all the plugins which take single catalog entries 

258 for measRecord in catalog: 

259 for plug in self.executionDict[runlevel].single: 

260 with CCContext(plug, measRecord, self.log): 

261 plug.calculate(measRecord)