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