1 | % ----------------------------------------------------------------------- |
---|
2 | % outputs.tex: Section detailing the different forms of text- and |
---|
3 | % plot-based output. |
---|
4 | % ----------------------------------------------------------------------- |
---|
5 | % Copyright (C) 2006, Matthew Whiting, ATNF |
---|
6 | % |
---|
7 | % This program is free software; you can redistribute it and/or modify it |
---|
8 | % under the terms of the GNU General Public License as published by the |
---|
9 | % Free Software Foundation; either version 2 of the License, or (at your |
---|
10 | % option) any later version. |
---|
11 | % |
---|
12 | % Duchamp is distributed in the hope that it will be useful, but WITHOUT |
---|
13 | % ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or |
---|
14 | % FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License |
---|
15 | % for more details. |
---|
16 | % |
---|
17 | % You should have received a copy of the GNU General Public License |
---|
18 | % along with Duchamp; if not, write to the Free Software Foundation, |
---|
19 | % Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA |
---|
20 | % |
---|
21 | % Correspondence concerning Duchamp may be directed to: |
---|
22 | % Internet email: Matthew.Whiting [at] atnf.csiro.au |
---|
23 | % Postal address: Dr. Matthew Whiting |
---|
24 | % Australia Telescope National Facility, CSIRO |
---|
25 | % PO Box 76 |
---|
26 | % Epping NSW 1710 |
---|
27 | % AUSTRALIA |
---|
28 | % ----------------------------------------------------------------------- |
---|
29 | \secA{Outputs} |
---|
30 | \label{sec-output} |
---|
31 | |
---|
32 | \secB{During execution} |
---|
33 | |
---|
34 | \duchamp provides the user with feedback whilst it is running, to |
---|
35 | keep the user informed on the progress of the analysis. Most of this |
---|
36 | consists of self-explanatory messages about the particular stage the |
---|
37 | program is up to. The relevant parameters are printed to the screen at |
---|
38 | the start (once the file has been successfully read in), so the user |
---|
39 | is able to make a quick check that the setup is correct (see |
---|
40 | Appendix~{app-input} for an example). |
---|
41 | |
---|
42 | If the cube is being trimmed (\S\ref{sec-modify}), the resulting |
---|
43 | dimensions are printed to indicate how much has been trimmed. If a |
---|
44 | reconstruction is being done, a continually updating message shows |
---|
45 | either the current iteration and scale, compared to the maximum scale |
---|
46 | (when \texttt{reconDim = 3}), or a progress bar showing the amount of |
---|
47 | the cube that has been reconstructed (for smaller values of |
---|
48 | \texttt{reconDim}). |
---|
49 | |
---|
50 | During the searching algorithms, the progress through the search is |
---|
51 | shown. When completed, the number of objects found is reported (this |
---|
52 | is the total number found, before any merging is done). |
---|
53 | |
---|
54 | In the merging process (where multiple detections of the same object |
---|
55 | are combined -- see \S\ref{sec-merger}), two stages of output |
---|
56 | occur. The first is when each object in the list is compared with all |
---|
57 | others. The output shows two numbers: the first being how far through |
---|
58 | the list the current object is, and the second being the length of the |
---|
59 | list. As the algorithm proceeds, the first number should increase and |
---|
60 | the second should decrease (as objects are combined). When the numbers |
---|
61 | meet, the whole list has been compared. If the objects are being |
---|
62 | grown, a similar output is shown, indicating the progress through the |
---|
63 | list. In the rejection stage, in which objects not meeting the minimum |
---|
64 | pixels/channels requirements are removed, the total number of objects |
---|
65 | remaining in the list is shown, which should steadily decrease with |
---|
66 | each rejection until all have been examined. Note that these steps can |
---|
67 | be very quick for small numbers of detections. |
---|
68 | |
---|
69 | Since this continual printing to screen has some overhead of time and |
---|
70 | CPU involved, the user can elect to not print this information by |
---|
71 | setting the parameter \texttt{verbose = false}. In this case, the user |
---|
72 | is still informed as to the steps being undertaken, but the details of |
---|
73 | the progress are not shown. |
---|
74 | |
---|
75 | There may also be Warning or Error messages printed to screen. The |
---|
76 | Warning messages occur when something happens that is unexpected (for |
---|
77 | instance, a desired keyword is not present in the FITS header), but |
---|
78 | not detrimental to the execution. An Error message is something more |
---|
79 | serious, and indicates some part of the program was not able to |
---|
80 | complete its task. The message will also indicate which function or |
---|
81 | subroutine generated it -- this is primarily a tool for debugging, but |
---|
82 | can be useful in determining what went wrong. |
---|
83 | |
---|
84 | \secB{Text-based output files} |
---|
85 | |
---|
86 | \secC{Table of results} |
---|
87 | \label{sec-results} |
---|
88 | |
---|
89 | Finally, we get to the results -- the reason for running \duchamp in |
---|
90 | the first place. Once the detection list is finalised, it is sorted by |
---|
91 | the mean velocity of the detections (or, if there is no good WCS |
---|
92 | associated with the cube, by the mean $z$-pixel position). The results |
---|
93 | are then printed to the screen and to the output file, given by the |
---|
94 | \texttt{OutFile} parameter. |
---|
95 | |
---|
96 | The output consists of three parts. First, a list of the parameters |
---|
97 | are printed to the output file, for future reference. Next, the |
---|
98 | detection threshold that was used is given, so comparison can be made |
---|
99 | with other searches. The noise level and its spread are also reported. |
---|
100 | |
---|
101 | The most interesting part, however, is the list of detected |
---|
102 | objects. This list, an example of which can be seen in |
---|
103 | Appendix~\ref{app-output}, contains the following columns (note that |
---|
104 | the title of the columns depending on WCS information will depend on |
---|
105 | the details of the WCS projection: they are shown below for the |
---|
106 | Equatorial and Galactic projection cases). |
---|
107 | |
---|
108 | \begin{Lentry} |
---|
109 | \item[{Obj\#}] The ID number of the detection (simply the |
---|
110 | sequential count for the list, which is ordered by increasing |
---|
111 | velocity, or channel number, if the WCS is not good enough to find |
---|
112 | the velocity). |
---|
113 | \item[{Name}] The ``IAU''-format name of the detection (derived from the |
---|
114 | WCS position -- see below for a description of the format). |
---|
115 | \item[{X,Y,Z}] The ``centre'' pixel position, determined by the input |
---|
116 | parameter \texttt{pixelCentre}. |
---|
117 | \item[{RA/GLON}] The Right Ascension or Galactic Longitude of the centre |
---|
118 | of the object. |
---|
119 | \item[{DEC/GLAT}] The Declination or Galactic Latitude of the centre of |
---|
120 | the object. |
---|
121 | \item[{VEL}] The mean velocity of the object [units given by the |
---|
122 | \texttt{spectralUnits} parameter]. |
---|
123 | \item[{w\_RA/w\_GLON}] The width of the object in Right Ascension or |
---|
124 | Galactic Longitude (depending on FITS coordinates) [arcmin]. |
---|
125 | \item[{w\_DEC/w\_GLAT}] The width of the object in Declination Galactic |
---|
126 | Latitude [arcmin]. |
---|
127 | \item[{w\_VEL}] The full velocity width of the detection (max channel |
---|
128 | $-$ min channel, in velocity units [see note below]). |
---|
129 | \item[{F\_int}] The integrated flux over the object, in the units of |
---|
130 | flux times velocity, corrected for the beam if necessary. |
---|
131 | \item[{F\_tot}] The sum of the flux values of all detected voxels. |
---|
132 | \item[{F\_peak}] The peak flux over the object, in the units of flux. |
---|
133 | \item[{S/Nmax}] The signal-to-noise ratio at the peak pixel. |
---|
134 | \item[{X1, X2}] The minimum and maximum X-pixel coordinates. |
---|
135 | \item[{Y1, Y2}] The minimum and maximum Y-pixel coordinates. |
---|
136 | \item[{Z1, Z2}] The minimum and maximum Z-pixel coordinates. |
---|
137 | \item[{Npix}] The number of voxels (\ie distinct $(x,y,z)$ coordinates) |
---|
138 | in the detection. |
---|
139 | \item[{Flag}] Whether the detection has any warning flags (see below). |
---|
140 | \end{Lentry} |
---|
141 | |
---|
142 | Note that the \texttt{X, Y, Z} columns depend on the \texttt{pixelCentre} |
---|
143 | parameter. This is because there are three alternative ways of |
---|
144 | expressing the centre of a detection, which are all listed in the list |
---|
145 | of detections written to the output file. These alternatives are: |
---|
146 | \begin{Lentry} |
---|
147 | \item[{X\_av, Y\_av, Z\_av}] The average pixel value in each |
---|
148 | axis direction \ie X\_av is the average of the $x$-values of all |
---|
149 | pixels in the detection. |
---|
150 | \item[{X\_cent, Y\_cent, Z\_cent}] The centroid position, being |
---|
151 | the flux-weighted average of the pixels. |
---|
152 | \item[{X\_peak, Y\_peak, Z\_peak}] The location of the pixel |
---|
153 | containing the peak flux value. |
---|
154 | \end{Lentry} |
---|
155 | These are also written to the table in the output file, although not |
---|
156 | to the screen (as it would make the width of the table |
---|
157 | unwieldy). Similarly, the \texttt{F\_tot} column is only written to the output |
---|
158 | file, and not at run-time. |
---|
159 | |
---|
160 | The \texttt{Name} is derived from the WCS position. For instance, a |
---|
161 | source that is centred on the RA,Dec position 12$^h$53$^m$45$^s$, |
---|
162 | -36$^\circ$24$'$12$''$ will be given the name J125345$-$362412, if the |
---|
163 | epoch is J2000, or the name B125345$-$362412 if it is B1950. An |
---|
164 | alternative form is used for Galactic coordinates: a source centred on |
---|
165 | the position ($l$,$b$) = (323.1245, 5.4567) will be called |
---|
166 | G323.124$+$05.457. If the WCS is not valid (\ie is not present or does |
---|
167 | not have all the necessary information), the \texttt{Name, RA, DEC, |
---|
168 | VEL} and related columns are not printed, but the pixel coordinates |
---|
169 | are still provided. |
---|
170 | |
---|
171 | The velocity units can be specified by the user, using the parameter |
---|
172 | \texttt{spectralUnits} (enter it as a single string with no |
---|
173 | spaces). The default value is km/s, which should be suitable for most |
---|
174 | users. These units are also used to give the units of integrated |
---|
175 | flux. Note that if there is no rest frequency specified in the FITS |
---|
176 | header, the \duchamp output will instead default to using Frequency, |
---|
177 | with units of MHz. |
---|
178 | |
---|
179 | If the WCS is absent or not sufficiently specified, then all columns |
---|
180 | from \texttt{RA/GLON} to \texttt{w\_VEL} will be left blank. Also, |
---|
181 | \texttt{F\_int} will be replaced with the more simple \texttt{F\_tot}. |
---|
182 | |
---|
183 | The \texttt{Flag} column contains any warning flags, such as: |
---|
184 | \begin{itemize} |
---|
185 | \item \textbf{E} -- The detection is next to the spatial edge of the image, |
---|
186 | meaning either the limit of the pixels, or the limit of the non-BLANK |
---|
187 | pixel region. |
---|
188 | \item \textbf{S} -- The detection lies at the edge of the spectral region. |
---|
189 | \item \textbf{N} -- The total flux, summed over all the (non-BLANK) |
---|
190 | pixels in the smallest box that completely encloses the detection, is |
---|
191 | negative. Note that this sum is likely to include non-detected |
---|
192 | pixels. It is of use in pointing out detections that lie next to |
---|
193 | strongly negative pixels, such as might arise due to interference -- |
---|
194 | the detected pixels might then also be due to the interference, so |
---|
195 | caution is advised. |
---|
196 | \end{itemize} |
---|
197 | |
---|
198 | \secC{Other results lists} |
---|
199 | |
---|
200 | Two additional results files can also be requested. One option is a |
---|
201 | VOTable-format XML file, containing just the RA, Dec, Velocity and the |
---|
202 | corresponding widths of the detections, as well as the fluxes. The |
---|
203 | user should set \texttt{flagVOT = true}, and put the desired filename |
---|
204 | in the parameter \texttt{votFile} -- note that the default is for it |
---|
205 | not to be produced. This file should be compatible with all Virtual |
---|
206 | Observatory tools (such as Aladin% |
---|
207 | \footnote{%Aladin can be found on the web at |
---|
208 | \href{http://aladin.u-strasbg.fr/}{http://aladin.u-strasbg.fr/}} |
---|
209 | or TOPCAT\footnote{%Tool for OPerations on Catalogues And Tables: |
---|
210 | \href{http://www.star.bristol.ac.uk/~mbt/topcat/}% |
---|
211 | {http://www.star.bristol.ac.uk/~mbt/topcat/}}). The second option is |
---|
212 | an annotation file for use with the Karma toolkit of visualisation |
---|
213 | tools (in particular, with \texttt{kvis}). This will draw a circle at |
---|
214 | the position of each detection, scaled by the spatial size of the |
---|
215 | detection, and number it according to the Obj\# given above. To make |
---|
216 | use of this option, the user should set |
---|
217 | \texttt{flagKarma = true}, and put the desired filename in the parameter |
---|
218 | \texttt{karmaFile} -- again, the default is for it not to be produced. |
---|
219 | |
---|
220 | As the program is running, it also (optionally) records the detections |
---|
221 | made in each individual spectrum or channel (see \S\ref{sec-detection} |
---|
222 | for details on this process). This is recorded in the file given by |
---|
223 | the parameter \texttt{LogFile}. This file does not include the columns |
---|
224 | \texttt{Name, RA, DEC, w\_RA, w\_DEC, VEL, w\_VEL}. This file is |
---|
225 | designed primarily for diagnostic purposes: \eg to see if a given set |
---|
226 | of pixels is detected in, say, one channel image, but does not survive |
---|
227 | the merging process. The list of pixels (and their fluxes) in the |
---|
228 | final detection list are also printed to this file, again for |
---|
229 | diagnostic purposes. The file also records the execution time, as well |
---|
230 | as the command-line statement used to run \duchamp. The creation of |
---|
231 | this log file can be prevented by setting \texttt{flagLog = false} |
---|
232 | (which is the default). |
---|
233 | |
---|
234 | \secB{Graphical output} |
---|
235 | \secC{Spectral plots} |
---|
236 | |
---|
237 | As well as the output data file, a postscript file is created that |
---|
238 | shows the spectrum for each detection, together with a small cutout |
---|
239 | image (the 0th moment) and basic information about the detection (note |
---|
240 | that any flags are printed after the name of the detection, in the |
---|
241 | format \texttt{[E]}). If the cube was reconstructed, the spectrum from |
---|
242 | the reconstruction is shown in red, over the top of the original |
---|
243 | spectrum. The spectral extent of the detected object is indicated by |
---|
244 | two dashed blue lines, and the region covered by the ``Milky Way'' |
---|
245 | channels is shown by a green hashed box. An example detection can be |
---|
246 | seen below in Fig.~\ref{fig-spect}. |
---|
247 | |
---|
248 | \begin{figure}[t] |
---|
249 | \begin{center} |
---|
250 | \includegraphics[width=\textwidth]{example_spectrum} |
---|
251 | \end{center} |
---|
252 | \caption{\footnotesize An example of the spectral output. Note several |
---|
253 | of the features discussed in the text: the red lines indicating the |
---|
254 | reconstructed spectrum; the blue dashed lines indicating the |
---|
255 | spectral extent of the detection; the green hashed area indicating |
---|
256 | the Milky Way channels that are ignored by the searching algorithm; |
---|
257 | the blue border showing its spatial extent on the 0th moment map; |
---|
258 | and the 15~arcmin-long scale bar.} |
---|
259 | \label{fig-spect} |
---|
260 | \end{figure} |
---|
261 | |
---|
262 | The spectrum that is plotted is governed by the |
---|
263 | \texttt{spectralMethod} parameter. It can be either \texttt{peak} (the |
---|
264 | default), where the spectrum is from the spatial pixel containing the |
---|
265 | detection's peak flux; or \texttt{sum}, where the spectrum is summed |
---|
266 | over all spatial pixels, and then corrected for the beam size. The |
---|
267 | spectral extent of the detection is indicated with blue lines, and a |
---|
268 | zoom is shown in a separate window. |
---|
269 | |
---|
270 | The cutout image can optionally include a border around the spatial |
---|
271 | pixels that are in the detection (turned on and off by the |
---|
272 | \texttt{drawBorders} parameter -- the default is \texttt{true}). It |
---|
273 | includes a scale bar in the bottom left corner to indicate size -- its |
---|
274 | length is indicated next to it (the choice of length depends on the |
---|
275 | size of the image). |
---|
276 | |
---|
277 | There may also be one or two extra lines on the image. A yellow line |
---|
278 | shows the limits of the cube's spatial region: when this is shown, the |
---|
279 | detected object will lie close to the edge, and the image box will |
---|
280 | extend outside the region covered by the data. A purple line, however, |
---|
281 | shows the dividing line between BLANK and non-BLANK pixels. The BLANK |
---|
282 | pixels will always be shown in black. The first type of line is always |
---|
283 | drawn, while the second is governed by the parameter |
---|
284 | \texttt{drawBlankEdges} (whose default is \texttt{true}), and |
---|
285 | obviously whether there are any BLANK pixel present. |
---|
286 | |
---|
287 | \secC{Spatial maps} |
---|
288 | |
---|
289 | \begin{figure}[!t] |
---|
290 | \begin{center} |
---|
291 | \includegraphics[width=\textwidth]{example_moment_map} |
---|
292 | \end{center} |
---|
293 | \caption{\footnotesize An example of the moment map created by |
---|
294 | \duchamp. The full extent of the cube is covered, and the 0th moment |
---|
295 | of each object is shown (integrated individually over all the |
---|
296 | detected channels). The purple line indicates the limit of the |
---|
297 | non-BLANK pixels.} |
---|
298 | \label{fig-moment} |
---|
299 | \end{figure} |
---|
300 | |
---|
301 | Finally, a couple of images are optionally produced: a 0th moment map |
---|
302 | of the cube, combining just the detected channels in each object, |
---|
303 | showing the integrated flux in grey-scale; and a ``detection image'', |
---|
304 | a grey-scale image where the pixel values are the number of channels |
---|
305 | that spatial pixel is detected in. In both cases, if |
---|
306 | \texttt{drawBorders = true}, a border is drawn around the spatial |
---|
307 | extent of each detection, and if \texttt{drawBlankEdges = true}, the |
---|
308 | purple line dividing BLANK and non-BLANK pixels (as described above) |
---|
309 | is drawn. An example moment map is shown in Fig.~\ref{fig-moment}. |
---|
310 | The production or otherwise of these images is governed by the |
---|
311 | \texttt{flagMaps} parameter. |
---|
312 | |
---|
313 | The moment map is also displayed in a PGPlot XWindow (with the |
---|
314 | \texttt{/xs} display option). This feature can be turned off by |
---|
315 | setting \texttt{flagXOutput = false} -- this might be useful if |
---|
316 | running \duchamp on a terminal with no window display capability, or |
---|
317 | if you have set up a script to run it in a batch mode. |
---|
318 | |
---|
319 | The purpose of these images are to provide a visual guide to where the |
---|
320 | detections have been made, and, particularly in the case of the moment |
---|
321 | map, to provide an indication of the strength of the source. In both |
---|
322 | cases, the detections are numbered (in the same sense as the output |
---|
323 | list and as the spectral plots), and the spatial borders are marked |
---|
324 | out as for the cutout images in the spectra file. Both these images |
---|
325 | are saved as postscript files (given by the parameters |
---|
326 | \texttt{momentMap} and \texttt{detectionMap} respectively), with the |
---|
327 | latter also displayed in a \textsc{pgplot} window (regardless of the |
---|
328 | state of \texttt{flagMaps}). |
---|