lsst.pipe.tasks g3ecd7dbb19+c6a4abf551
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 page.
31# This works even for task(s) that are not in lsst.pipe.tasks.
32
41
42
43class ExampleSigmaClippedStatsConfig(pexConfig.Config):
44 """!Configuration for ExampleSigmaClippedStatsTask
45 """
46 badMaskPlanes = pexConfig.ListField(
47 dtype=str,
48 doc="Mask planes that, if set, indicate the associated pixel should "
49 "not be included when the calculating statistics.",
50 default=("EDGE",),
51 )
52 numSigmaClip = pexConfig.Field(
53 doc="number of sigmas at which to clip data",
54 dtype=float,
55 default=3.0,
56 )
57 numIter = pexConfig.Field(
58 doc="number of iterations of sigma clipping",
59 dtype=int,
60 default=2,
61 )
62
63
64class ExampleSigmaClippedStatsTask(pipeBase.Task):
65 r"""!
66 Example task to compute sigma-clipped mean and standard deviation of an image
67
68 \section pipeTasks_ExampleSigmaClippedStatsTask_Contents Contents
69
70 - \ref pipeTasks_ExampleSigmaClippedStatsTask_Purpose
71 - \ref pipeTasks_ExampleSigmaClippedStatsTask_Config
72 - \ref pipeTasks_ExampleSigmaClippedStatsTask_Debug
73 - \ref pipeTasks_ExampleSigmaClippedStatsTask_Example
74
75 \section pipeTasks_ExampleSigmaClippedStatsTask_Purpose Description
76
77 \copybrief ExampleSigmaClippedStatsTask
78
79 This is a simple example task designed to be run as a subtask by ExampleCmdLineTask.
80 See also ExampleSimpleStatsTask as a variant that is even simpler.
81
82 The main method is \ref ExampleSigmaClippedStatsTask.run "run".
83
84 \section pipeTasks_ExampleSigmaClippedStatsTask_Config Configuration parameters
85
86 See \ref ExampleSigmaClippedStatsConfig
87
88 \section pipeTasks_ExampleSigmaClippedStatsTask_Debug Debug variables
89
90 This task has no debug variables.
91
92 \section pipeTasks_ExampleSigmaClippedStatsTask_Example A complete example
93 of using ExampleSigmaClippedStatsTask
94
95 This code is in examples/exampleStatsTask.py (this one example runs both
96 ExampleSigmaClippedStatsTask and ExampleSimpleStatsTask), and can be run as:
97 \code
98 examples/exampleStatsTask.py [fitsFile]
99 \endcode
100 """
101 ConfigClass = ExampleSigmaClippedStatsConfig
102 _DefaultName = "exampleSigmaClippedStats"
103
104 def __init__(self, *args, **kwargs):
105 """!Construct an ExampleSigmaClippedStatsTask
106
107 The init method may compute anything that that does not require data.
108 In this case we create a statistics control object using the config
109 (which cannot change once the task is created).
110 """
111 pipeBase.Task.__init__(self, *args, **kwargs)
112
113 self._badPixelMask = afwImage.Mask.getPlaneBitMask(self.config.badMaskPlanes)
114
115 self._statsControl = afwMath.StatisticsControl()
116 self._statsControl.setNumSigmaClip(self.config.numSigmaClip)
117 self._statsControl.setNumIter(self.config.numIter)
118 self._statsControl.setAndMask(self._badPixelMask)
119
120 @timeMethod
121 def run(self, maskedImage):
122 """!Compute and return statistics for a masked image
123
124 @param[in] maskedImage: masked image (an lsst::afw::MaskedImage)
125 @return a pipeBase Struct containing:
126 - mean: mean of image plane
127 - meanErr: uncertainty in mean
128 - stdDev: standard deviation of image plane
129 - stdDevErr: uncertainty in standard deviation
130 """
131 statObj = afwMath.makeStatistics(maskedImage, afwMath.MEANCLIP | afwMath.STDEVCLIP | afwMath.ERRORS,
132 self._statsControl)
133 mean, meanErr = statObj.getResult(afwMath.MEANCLIP)
134 stdDev, stdDevErr = statObj.getResult(afwMath.STDEVCLIP)
135 self.log.info("clipped mean=%0.2f; meanErr=%0.2f; stdDev=%0.2f; stdDevErr=%0.2f",
136 mean, meanErr, stdDev, stdDevErr)
137 return pipeBase.Struct(
138 mean=mean,
139 meanErr=meanErr,
140 stdDev=stdDev,
141 stdDevErr=stdDevErr,
142 )
143
144
145class ExampleSimpleStatsTask(pipeBase.Task):
146 r"""!
147 Example task to compute mean and standard deviation of an image
148
149 \section pipeTasks_ExampleSimpleStatsTask_Contents Contents
150
151 - \ref pipeTasks_ExampleSimpleStatsTask_Purpose
152 - \ref pipeTasks_ExampleSimpleStatsTask_Config
153 - \ref pipeTasks_ExampleSimpleStatsTask_Debug
154 - \ref pipeTasks_ExampleSimpleStatsTask_Example
155
156 \section pipeTasks_ExampleSimpleStatsTask_Purpose Description
157
158 \copybrief ExampleSimpleStatsTask
159
160 This was designed to be run as a subtask by ExampleCmdLineTask.
161 It is about as simple as a task can be; it has no configuration parameters and requires no special
162 initialization. See also ExampleSigmaClippedStatsTask as a variant that is slightly more complicated.
163
164 The main method is \ref ExampleSimpleTask.run "run".
165
166 \section pipeTasks_ExampleSimpleStatsTask_Config Configuration parameters
167
168 This task has no configuration parameters.
169
170 \section pipeTasks_ExampleSimpleStatsTask_Debug Debug variables
171
172 This task has no debug variables.
173
174 \section pipeTasks_ExampleSimpleStatsTask_Example A complete example of using ExampleSimpleStatsTask
175
176 This code is in examples/exampleStatsTask.py (this one example runs both
177 ExampleSigmaClippedStatsTask and ExampleSimpleStatsTask), and can be run as:
178 \code
179 examples/exampleStatsTask.py [fitsFile]
180 \endcode
181 """
182 # Even a task with no configuration requires setting ConfigClass
183 ConfigClass = pexConfig.Config
184 # Having a default name simplifies construction of the task, since the parent task
185 # need not specify a name. Note: having a default name is required for command-line tasks.
186 # The name can be simple and need not be unique (except for multiple subtasks that will
187 # be run by a parent task at the same time).
188 _DefaultName = "exampleSimpleStats"
189
190 # The `lsst.utils.timer.timeMethod` decorator measures how long a task method takes to run,
191 # and the resources needed to run it. The information is recorded in the task's `metadata` field.
192 # Most command-line tasks (not including the example below) save metadata for the task
193 # and all of its subtasks whenver the task is run.
194 @timeMethod
195 def run(self, maskedImage):
196 """!Compute and return statistics for a masked image
197
198 @param[in] maskedImage: masked image (an lsst::afw::MaskedImage)
199 @return a pipeBase Struct containing:
200 - mean: mean of image plane
201 - meanErr: uncertainty in mean
202 - stdDev: standard deviation of image plane
203 - stdDevErr: uncertainty in standard deviation
204 """
205 self._statsControl = afwMath.StatisticsControl()
206 statObj = afwMath.makeStatistics(maskedImage, afwMath.MEAN | afwMath.STDEV | afwMath.ERRORS,
207 self._statsControl)
208 mean, meanErr = statObj.getResult(afwMath.MEAN)
209 stdDev, stdDevErr = statObj.getResult(afwMath.STDEV)
210 self.log.info("simple mean=%0.2f; meanErr=%0.2f; stdDev=%0.2f; stdDevErr=%0.2f",
211 mean, meanErr, stdDev, stdDevErr)
212
213 return pipeBase.Struct(
214 mean=mean,
215 meanErr=meanErr,
216 stdDev=stdDev,
217 stdDevErr=stdDevErr,
218 )
Configuration for ExampleSigmaClippedStatsTask.
Example task to compute sigma-clipped mean and standard deviation of an image.
def run(self, maskedImage)
Compute and return statistics for a masked image.
def __init__(self, *args, **kwargs)
Construct an ExampleSigmaClippedStatsTask.
Example task to compute mean and standard deviation of an image.
def run(self, maskedImage)
Compute and return statistics for a masked image.