LSSTApplications  10.0-2-g4f67435,11.0.rc2+1,11.0.rc2+12,11.0.rc2+3,11.0.rc2+4,11.0.rc2+5,11.0.rc2+6,11.0.rc2+7,11.0.rc2+8
LSSTDataManagementBasePackage
exampleCmdLineTask.py
Go to the documentation of this file.
1 #!/usr/bin/env python
2 #
3 # LSST Data Management System
4 # Copyright 2014 LSST Corporation.
5 #
6 # This product includes software developed by the
7 # LSST Project (http://www.lsst.org/).
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 LSST License Statement and
20 # the GNU General Public License along with this program. If not,
21 # see <http://www.lsstcorp.org/LegalNotices/>.
22 #
23 from lsst.afw.display.ds9 import mtv
24 import lsst.pex.config as pexConfig
25 import lsst.pipe.base as pipeBase
26 from .exampleStatsTasks import ExampleSigmaClippedStatsTask
27 
28 # The following block adds links to this task from the Task Documentation page.
29 # This works even for task(s) that are not in lsst.pipe.tasks.
30 ## \addtogroup LSST_task_documentation
31 ## \{
32 ## \page pipeTasks_exampleTask
33 ## \ref ExampleCmdLineTask "ExampleCmdLineTask"
34 ## An example intended to show how to write a command-line task.
35 ## \}
36 
37 class ExampleCmdLineConfig(pexConfig.Config):
38  """!Configuration for ExampleCmdLineTask
39  """
40  stats = pexConfig.ConfigurableField(
41  doc = "Subtask to compute statistics of an image",
42  target = ExampleSigmaClippedStatsTask,
43  )
44  doFail = pexConfig.Field(
45  doc = "Raise an lsst.base.TaskError exception when processing each image? " \
46  + "This allows one to see the effects of the --doraise command line flag",
47  dtype = bool,
48  default = False,
49  )
50 
51 class ExampleCmdLineTask(pipeBase.CmdLineTask):
52  """!Example command-line task that computes simple statistics on an image
53 
54  \section pipeTasks_ExampleCmdLineTask_Contents Contents
55 
56  - \ref pipeTasks_ExampleCmdLineTask_Purpose
57  - \ref pipeTasks_ExampleCmdLineTask_Config
58  - \ref pipeTasks_ExampleCmdLineTask_Debug
59  - \ref pipeTasks_ExampleCmdLineTask_Example
60 
61  \section pipeTasks_ExampleCmdLineTask_Purpose Description
62 
63  \copybrief ExampleCmdLineTask
64 
65  This task was written as an example for the documents \ref pipeTasks_writeTask
66  and \ref pipeTasks_writeCmdLineTask.
67  The task reads in a "calexp" (a calibrated science \ref lsst::afw::image::Exposure "exposure"),
68  computes statistics on the image plane, and logs and returns the statistics.
69  In addition, if debugging is enabled, it displays the image in ds9.
70 
71  The image statistics are computed using a subtask, in order to show how to call subtasks and how to
72  \ref pipeBase_argumentParser_retargetSubtasks "retarget" (replace) them with variant subtasks.
73 
74  The main method is \ref ExampleCmdLineTask.run "run".
75 
76  \section pipeTasks_ExampleCmdLineTask_Config Configuration parameters
77 
78  See \ref ExampleCmdLineConfig
79 
80  \section pipeTasks_ExampleCmdLineTask_Debug Debug variables
81 
82  This task supports the following debug variables:
83  <dl>
84  <dt>`display`
85  <dd>If True then display the exposure in ds9
86  </dl>
87 
88  To enable debugging, see \ref baseDebug.
89 
90  \section pipeTasks_ExampleCmdLineTask_Example A complete example of using ExampleCmdLineTask
91 
92  This code is in examples/exampleCmdLineTask.py, and can be run as follows:
93  \code
94  examples/exampleCmdLineTask.py $OBS_TEST_DIR/data/input --id
95  # that will process all data; you can also try any combination of these flags:
96  --id filter=g
97  --config doFail=True --doraise
98  --show config data
99  \endcode
100  """
101  ConfigClass = ExampleCmdLineConfig
102  _DefaultName = "exampleTask"
103 
104  def __init__(self, *args, **kwargs):
105  """Construct an ExampleCmdLineTask
106 
107  Call the parent class constructor and make the "stats" subtask from the config field of the same name.
108  """
109  pipeBase.CmdLineTask.__init__(self, *args, **kwargs)
110  self.makeSubtask("stats")
111 
112  @pipeBase.timeMethod
113  def run(self, dataRef):
114  """!Compute a few statistics on the image plane of an exposure
115 
116  @param dataRef: data reference for a calibrated science exposure ("calexp")
117  @return a pipeBase Struct containing:
118  - mean: mean of image plane
119  - meanErr: uncertainty in mean
120  - stdDev: standard deviation of image plane
121  - stdDevErr: uncertainty in standard deviation
122  """
123  self.log.info("Processing data ID %s" % (dataRef.dataId,))
124  if self.config.doFail:
125  raise pipeBase.TaskError("Raising TaskError by request (config.doFail=True)")
126 
127  # Unpersist the raw exposure pointed to by the data reference
128  rawExp = dataRef.get("raw")
129  maskedImage = rawExp.getMaskedImage()
130 
131  # Support extra debug output.
132  # -
133  import lsstDebug
134  display = lsstDebug.Info(__name__).display
135  if display:
136  frame = 1
137  mtv(rawExp, frame=frame, title="exposure")
138 
139  # return the pipe_base Struct that is returned by self.stats.run
140  return self.stats.run(maskedImage)
141 
142  def _getConfigName(self):
143  """!Get the name prefix for the task config's dataset type, or None to prevent persisting the config
144 
145  This override returns None to avoid persisting metadata for this trivial task.
146 
147  However, if the method returns a name, then the full name of the dataset type will be <name>_config.
148  The default CmdLineTask._getConfigName returns _DefaultName,
149  which for this task would result in a dataset name of "exampleTask_config".
150 
151  Normally you can use the default CmdLineTask._getConfigName, but here are two reasons
152  why you might want to override it:
153  - If you do not want your task to write its config, then have the override return None.
154  That is done for this example task, because I didn't want to clutter up the
155  repository with config information for a trivial task.
156  - If the default name would not be unique. An example is
157  \ref lsst.pipe.tasks.makeSkyMap.MakeSkyMapTask "MakeSkyMapTask": it makes a
158  \ref lsst.skymap.SkyMap "sky map" (sky pixelization for a coadd)
159  for any of several different types of coadd, such as deep or goodSeeing.
160  As such, the name of the persisted config must include the coadd type in order to be unique.
161 
162  Normally if you override _getConfigName then you override _getMetadataName to match.
163  """
164  return None
165 
166  def _getMetadataName(self):
167  """!Get the name prefix for the task metadata's dataset type, or None to prevent persisting metadata
168 
169  This override returns None to avoid persisting metadata for this trivial task.
170 
171  However, if the method returns a name, then the full name of the dataset type will be <name>_metadata.
172  The default CmdLineTask._getConfigName returns _DefaultName,
173  which for this task would result in a dataset name of "exampleTask_metadata".
174 
175  See the description of _getConfigName for reasons to override this method.
176  """
177  return None
def _getConfigName
Get the name prefix for the task config&#39;s dataset type, or None to prevent persisting the config...
def _getMetadataName
Get the name prefix for the task metadata&#39;s dataset type, or None to prevent persisting metadata...
Example command-line task that computes simple statistics on an image.
def run
Compute a few statistics on the image plane of an exposure.