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