lsst.pipe.tasks  13.0-66-gfbf2f2ce+5
exampleStatsTasks.py
Go to the documentation of this file.
1 #
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 #
22 from __future__ import absolute_import, division, print_function
23 import lsst.afw.image as afwImage
24 import lsst.afw.math as afwMath
25 import lsst.pex.config as pexConfig
26 import lsst.pipe.base as pipeBase
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 #------------------------- ExampleSigmaClippedStatsTask -------------------------#
43 
44 
45 class 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 
66 class ExampleSigmaClippedStatsTask(pipeBase.Task):
67  """!Example task to compute sigma-clipped mean and standard deviation of an image
68 
69  \section pipeTasks_ExampleSigmaClippedStatsTask_Contents Contents
70 
71  - \ref pipeTasks_ExampleSigmaClippedStatsTask_Purpose
72  - \ref pipeTasks_ExampleSigmaClippedStatsTask_Config
73  - \ref pipeTasks_ExampleSigmaClippedStatsTask_Debug
74  - \ref pipeTasks_ExampleSigmaClippedStatsTask_Example
75 
76  \section pipeTasks_ExampleSigmaClippedStatsTask_Purpose Description
77 
78  \copybrief ExampleSigmaClippedStatsTask
79 
80  This is a simple example task designed to be run as a subtask by ExampleCmdLineTask.
81  See also ExampleSimpleStatsTask as a variant that is even simpler.
82 
83  The main method is \ref ExampleSigmaClippedStatsTask.run "run".
84 
85  \section pipeTasks_ExampleSigmaClippedStatsTask_Config Configuration parameters
86 
87  See \ref ExampleSigmaClippedStatsConfig
88 
89  \section pipeTasks_ExampleSigmaClippedStatsTask_Debug Debug variables
90 
91  This task has no debug variables.
92 
93  \section pipeTasks_ExampleSigmaClippedStatsTask_Example A complete example 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  @pipeBase.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 #------------------------- ExampleSimpleStatsTask -------------------------#
145 
146 
147 class ExampleSimpleStatsTask(pipeBase.Task):
148  """!Example task to compute mean and standard deviation of an image
149 
150  \section pipeTasks_ExampleSimpleStatsTask_Contents Contents
151 
152  - \ref pipeTasks_ExampleSimpleStatsTask_Purpose
153  - \ref pipeTasks_ExampleSimpleStatsTask_Config
154  - \ref pipeTasks_ExampleSimpleStatsTask_Debug
155  - \ref pipeTasks_ExampleSimpleStatsTask_Example
156 
157  \section pipeTasks_ExampleSimpleStatsTask_Purpose Description
158 
159  \copybrief ExampleSimpleStatsTask
160 
161  This was designed to be run as a subtask by ExampleCmdLineTask.
162  It is about as simple as a task can be; it has no configuration parameters and requires no special
163  initialization. See also ExampleSigmaClippedStatsTask as a variant that is slightly more complicated.
164 
165  The main method is \ref ExampleSimpleTask.run "run".
166 
167  \section pipeTasks_ExampleSimpleStatsTask_Config Configuration parameters
168 
169  This task has no configuration parameters.
170 
171  \section pipeTasks_ExampleSimpleStatsTask_Debug Debug variables
172 
173  This task has no debug variables.
174 
175  \section pipeTasks_ExampleSimpleStatsTask_Example A complete example of using ExampleSimpleStatsTask
176 
177  This code is in examples/exampleStatsTask.py (this one example runs both
178  ExampleSigmaClippedStatsTask and ExampleSimpleStatsTask), and can be run as:
179  \code
180  examples/exampleStatsTask.py [fitsFile]
181  \endcode
182  """
183  # Even a task with no configuration requires setting ConfigClass
184  ConfigClass = pexConfig.Config
185  # Having a default name simplifies construction of the task, since the parent task
186  # need not specify a name. Note: having a default name is required for command-line tasks.
187  # The name can be simple and need not be unique (except for multiple subtasks that will
188  # be run by a parent task at the same time).
189  _DefaultName = "exampleSimpleStats"
190 
191  # The `lsst.pipe.timeMethod` decorator measures how long a task method takes to run,
192  # and the resources needed to run it. The information is recorded in the task's `metadata` field.
193  # Most command-line tasks (not including the example below) save metadata for the task
194  # and all of its subtasks whenver the task is run.
195  @pipeBase.timeMethod
196  def run(self, maskedImage):
197  """!Compute and return statistics for a masked image
198 
199  @param[in] maskedImage: masked image (an lsst::afw::MaskedImage)
200  @return a pipeBase Struct containing:
201  - mean: mean of image plane
202  - meanErr: uncertainty in mean
203  - stdDev: standard deviation of image plane
204  - stdDevErr: uncertainty in standard deviation
205  """
206  self._statsControl = afwMath.StatisticsControl()
207  statObj = afwMath.makeStatistics(maskedImage, afwMath.MEAN | afwMath.STDEV | afwMath.ERRORS,
208  self._statsControl)
209  mean, meanErr = statObj.getResult(afwMath.MEAN)
210  stdDev, stdDevErr = statObj.getResult(afwMath.STDEV)
211  self.log.info("simple mean=%0.2f; meanErr=%0.2f; stdDev=%0.2f; stdDevErr=%0.2f" %
212  (mean, meanErr, stdDev, stdDevErr))
213 
214  return pipeBase.Struct(
215  mean=mean,
216  meanErr=meanErr,
217  stdDev=stdDev,
218  stdDevErr=stdDevErr,
219  )
Example task to compute sigma-clipped mean and standard deviation of an image.
def __init__(self, args, kwargs)
Construct an ExampleSigmaClippedStatsTask.
def run(self, maskedImage)
Compute and return statistics for a masked image.
def run(self, maskedImage)
Compute and return statistics for a masked image.
Configuration for ExampleSigmaClippedStatsTask.
Example task to compute mean and standard deviation of an image.