lsst.pipe.tasks g6a99470703+51f2fbd04f
exampleStatsTasks.py
Go to the documentation of this file.
2# LSST Data Management System
3# Copyright 2014 LSST Corporation.
4#
5# This product includes software developed by the
6# LSST Project (http://www.lsst.org/).
7#
8# This program is free software: you can redistribute it and/or modify
9# it under the terms of the GNU General Public License as published by
10# the Free Software Foundation, either version 3 of the License, or
11# (at your option) any later version.
12#
13# This program is distributed in the hope that it will be useful,
14# but WITHOUT ANY WARRANTY; without even the implied warranty of
15# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
16# GNU General Public License for more details.
17#
18# You should have received a copy of the LSST License Statement and
19# the GNU General Public License along with this program. If not,
20# see <http://www.lsstcorp.org/LegalNotices/>.
21#
22import lsst.afw.image as afwImage
23import lsst.afw.math as afwMath
24import lsst.pex.config as pexConfig
25import lsst.pipe.base as pipeBase
26from lsst.utils.timer import timeMethod
27
28__all__ = ["ExampleSigmaClippedStatsConfig", "ExampleSigmaClippedStatsTask", "ExampleSimpleStatsTask"]
29
30# The following block adds links to these tasks from the Task Documentation
31# page.
32# This works even for task(s) that are not in lsst.pipe.tasks.
33
43
44
45class ExampleSigmaClippedStatsConfig(pexConfig.Config):
46 """!Configuration for ExampleSigmaClippedStatsTask
47 """
48 badMaskPlanes = pexConfig.ListField(
49 dtype=str,
50 doc="Mask planes that, if set, indicate the associated pixel should "
51 "not be included when the calculating statistics.",
52 default=("EDGE",),
53 )
54 numSigmaClip = pexConfig.Field(
55 doc="number of sigmas at which to clip data",
56 dtype=float,
57 default=3.0,
58 )
59 numIter = pexConfig.Field(
60 doc="number of iterations of sigma clipping",
61 dtype=int,
62 default=2,
63 )
64
65
66class ExampleSigmaClippedStatsTask(pipeBase.Task):
67 r"""Example task to compute sigma-clipped mean and standard deviation of an
68 image
69
70 This is a simple example task designed to be run as a subtask by
71 ExampleCmdLineTask. See also ExampleSimpleStatsTask as a variant that is
72 even simpler.
73
74 The main method is ExampleSigmaClippedStatsTask.run "run".
75
76 pipeTasks_ExampleSigmaClippedStatsTask_Config Configuration parameters
77
78 See ExampleSigmaClippedStatsConfig
79
80 pipeTasks_ExampleSigmaClippedStatsTask_Debug Debug variables
81
82 This task has no debug variables.
83
84 pipeTasks_ExampleSigmaClippedStatsTask_Example A complete example
85 of using ExampleSigmaClippedStatsTask
86
87 This code is in examples/exampleStatsTask.py (this one example runs both
88 ExampleSigmaClippedStatsTask and ExampleSimpleStatsTask), and can be run
89 as: examples/exampleStatsTask.py [fitsFile]
90
91 The init method may compute anything that that does not require data.
92 In this case we create a statistics control object using the config
93 (which cannot change once the task is created).
94 """
95 ConfigClass = ExampleSigmaClippedStatsConfig
96 _DefaultName = "exampleSigmaClippedStats"
97
98 def __init__(self, *args, **kwargs):
99 pipeBase.Task.__init__(self, *args, **kwargs)
100
101 self._badPixelMask = afwImage.Mask.getPlaneBitMask(self.config.badMaskPlanes)
102
103 self._statsControl = afwMath.StatisticsControl()
104 self._statsControl.setNumSigmaClip(self.config.numSigmaClip)
105 self._statsControl.setNumIter(self.config.numIter)
106 self._statsControl.setAndMask(self._badPixelMask)
107
108 @timeMethod
109 def run(self, maskedImage):
110 """Compute and return statistics for a masked image
111
112 Parameters
113 ----------
114 maskedImage : `lsst.afw.MaskedImage`
115 masked image
116
117 Returns
118 -------
119 retStruct : `~lsst.pipe.base.Struct`
120 A struct containing following attributes
121 - mean: mean of image plane
122 - meanErr: uncertainty in mean
123 - stdDev: standard deviation of image plane
124 - stdDevErr: uncertainty in standard deviation
125 """
126 statObj = afwMath.makeStatistics(maskedImage, afwMath.MEANCLIP | afwMath.STDEVCLIP | afwMath.ERRORS,
127 self._statsControl)
128 mean, meanErr = statObj.getResult(afwMath.MEANCLIP)
129 stdDev, stdDevErr = statObj.getResult(afwMath.STDEVCLIP)
130 self.log.info("clipped mean=%0.2f; meanErr=%0.2f; stdDev=%0.2f; stdDevErr=%0.2f",
131 mean, meanErr, stdDev, stdDevErr)
132 return pipeBase.Struct(
133 mean=mean,
134 meanErr=meanErr,
135 stdDev=stdDev,
136 stdDevErr=stdDevErr,
137 )
138
139
140class ExampleSimpleStatsTask(pipeBase.Task):
141 r"""
142 Example task to compute mean and standard deviation of an image
143
144 This was designed to be run as a subtask by ExampleCmdLineTask.
145 It is about as simple as a task can be; it has no configuration parameters
146 and requires no special initialization. See also
147 ExampleSigmaClippedStatsTask as a variant that is slightly more
148 complicated.
149
150 The main method is ExampleSimpleTask.run "run".
151
152 pipeTasks_ExampleSimpleStatsTask_Config Configuration parameters
153
154 This task has no configuration parameters.
155
156 pipeTasks_ExampleSimpleStatsTask_Debug Debug variables
157
158 This task has no debug variables.
159
160 pipeTasks_ExampleSimpleStatsTask_Example A complete example of using
161 ExampleSimpleStatsTask
162
163 This code is in examples/exampleStatsTask.py (this one example runs both
164 ExampleSigmaClippedStatsTask and ExampleSimpleStatsTask), and can be run
165 as: examples/exampleStatsTask.py [fitsFile]
166 """
167 # Even a task with no configuration requires setting ConfigClass
168 ConfigClass = pexConfig.Config
169 # Having a default name simplifies construction of the task, since the
170 # parent task need not specify a name. Note: having a default name is
171 # required for command-line tasks.
172 # The name can be simple and need not be unique (except for multiple
173 # subtasks that will be run by a parent task at the same time).
174 _DefaultName = "exampleSimpleStats"
175
176 # The `lsst.utils.timer.timeMethod` decorator measures how long a task
177 # method takes to run, and the resources needed to run it. The information
178 # is recorded in the task's `metadata` field.
179 # Most command-line tasks (not including the example below) save metadata
180 # for the task and all of its subtasks whenver the task is run.
181 @timeMethod
182 def run(self, maskedImage):
183 """Compute and return statistics for a masked image
184
185 Parameters
186 ----------
187 maskedImage : `lsst.afw.MaskedImage`
188 masked image
189
190 Returns
191 -------
192 retStruct : `~lsst.pipe.base.Struct`
193 A struct containing following attributes
194 - mean: mean of image plane
195 - meanErr: uncertainty in mean
196 - stdDev: standard deviation of image plane
197 - stdDevErr: uncertainty in standard deviation
198 """
199 self._statsControl = afwMath.StatisticsControl()
200 statObj = afwMath.makeStatistics(maskedImage, afwMath.MEAN | afwMath.STDEV | afwMath.ERRORS,
201 self._statsControl)
202 mean, meanErr = statObj.getResult(afwMath.MEAN)
203 stdDev, stdDevErr = statObj.getResult(afwMath.STDEV)
204 self.log.info("simple mean=%0.2f; meanErr=%0.2f; stdDev=%0.2f; stdDevErr=%0.2f",
205 mean, meanErr, stdDev, stdDevErr)
206
207 return pipeBase.Struct(
208 mean=mean,
209 meanErr=meanErr,
210 stdDev=stdDev,
211 stdDevErr=stdDevErr,
212 )
Configuration for ExampleSigmaClippedStatsTask.