[158] | 1 | \secA{Outputs} |
---|
| 2 | \label{sec-output} |
---|
| 3 | |
---|
| 4 | \secB{During execution} |
---|
| 5 | |
---|
| 6 | \duchamp\ provides the user with feedback whilst it is running, to |
---|
| 7 | keep the user informed on the progress of the analysis. Most of this |
---|
| 8 | consists of self-explanatory messages about the particular stage the |
---|
| 9 | program is up to. The relevant parameters are printed to the screen at |
---|
| 10 | the start (once the file has been successfully read in), so the user |
---|
| 11 | is able to make a quick check that the setup is correct (see |
---|
| 12 | Appendix~{app-input} for an example). |
---|
| 13 | |
---|
| 14 | If the cube is being trimmed (\S\ref{sec-modify}), the resulting |
---|
| 15 | dimensions are printed to indicate how much has been trimmed. If a |
---|
| 16 | reconstruction is being done, a continually updating message shows |
---|
| 17 | either the current iteration and scale, compared to the maximum scale |
---|
| 18 | (when \texttt{reconDim=3}), or a progress bar showing the amount of |
---|
| 19 | the cube that has been reconstructed (for smaller values of |
---|
| 20 | \texttt{reconDim}). |
---|
| 21 | |
---|
| 22 | During the searching algorithms, the progress through the 1D and 2D |
---|
| 23 | searches are shown. When the searches have completed, the number of |
---|
| 24 | objects found in both the 1D and 2D searches are reported (see |
---|
| 25 | \S\ref{sec-detection} for details). |
---|
| 26 | |
---|
| 27 | In the merging process (where multiple detections of the same object |
---|
| 28 | are combined -- see \S\ref{sec-merger}), two stages of output |
---|
| 29 | occur. The first is when each object in the list is compared with all |
---|
| 30 | others. The output shows two numbers: the first being how far through |
---|
| 31 | the list the current object is, and the second being the length of the |
---|
| 32 | list. As the algorithm proceeds, the first number should increase and |
---|
| 33 | the second should decrease (as objects are combined). When the numbers |
---|
| 34 | meet (\ie the whole list has been compared), the second phase begins, |
---|
| 35 | in which multiply-appearing pixels in each object are removed, as are |
---|
| 36 | objects not meeting the minimum channels requirement. During this |
---|
| 37 | phase, the total number of accepted objects is shown, which should |
---|
| 38 | steadily increase until all have been accepted or rejected. Note that |
---|
| 39 | these steps can be very quick for small numbers of detections. |
---|
| 40 | |
---|
| 41 | Since this continual printing to screen has some overhead of time and |
---|
| 42 | CPU involved, the user can elect to not print this information by |
---|
| 43 | setting the parameter \texttt{verbose = 0}. In this case, the user is |
---|
| 44 | still informed as to the steps being undertaken, but the details of |
---|
| 45 | the progress are not shown. |
---|
| 46 | |
---|
[162] | 47 | There may also be Warning or Error messages printed to screen. The |
---|
| 48 | Warning messages occur when something happens that is unexpected (for |
---|
| 49 | instance, a desired keyword is not present in the FITS header), but |
---|
| 50 | not detrimental to the execution. An Error message is something more |
---|
| 51 | serious, and indicates some part of the program was not able to |
---|
| 52 | complete its task. The message will also indicate which function or |
---|
| 53 | subroutine generated it -- this is primarily a tool for debugging, but |
---|
| 54 | can be useful in determining what went wrong. |
---|
| 55 | |
---|
[158] | 56 | \secB{Results} |
---|
| 57 | |
---|
| 58 | \secC{Table of results} |
---|
| 59 | |
---|
| 60 | Finally, we get to the results -- the reason for running \duchamp\ in |
---|
| 61 | the first place. Once the detection list is finalised, it is sorted by |
---|
| 62 | the mean velocity of the detections (or, if there is no good WCS |
---|
[162] | 63 | associated with the cube, by the mean $z$-pixel position). The results |
---|
[158] | 64 | are then printed to the screen and to the output file, given by the |
---|
| 65 | \texttt{OutFile} parameter. The results list, an example of which can |
---|
| 66 | be seen in Appendix~\ref{app-output}, contains the following columns |
---|
| 67 | (note that the title of the columns depending on WCS information will |
---|
[162] | 68 | depend on the details of the WCS projection: they are shown below for |
---|
| 69 | the Equatorial and Galactic projection cases). |
---|
[158] | 70 | |
---|
| 71 | \begin{entry} |
---|
| 72 | \item[Obj\#] The ID number of the detection (simply the sequential |
---|
| 73 | count for the list, which is ordered by increasing velocity, or |
---|
| 74 | channel number, if the WCS is not good enough to find the velocity). |
---|
| 75 | \item[Name] The ``IAU''-format name of the detection (derived from the |
---|
| 76 | WCS position -- see below for a description of the format). |
---|
| 77 | \item[X] The average X-pixel position (averaged over all detected |
---|
| 78 | voxels). |
---|
| 79 | \item[Y] The average Y-pixel position. |
---|
| 80 | \item[Z] The average Z-pixel position. |
---|
| 81 | \item[RA/GLON] The Right Ascension or Galactic Longitude of the centre |
---|
| 82 | of the object. |
---|
| 83 | \item[DEC/GLAT] The Declination or Galactic Latitude of the centre of |
---|
| 84 | the object. |
---|
| 85 | \item[VEL] The mean velocity of the object [units given by the |
---|
| 86 | \texttt{spectralUnits} parameter]. |
---|
| 87 | \item[w\_RA/w\_GLON] The width of the object in Right Ascension or |
---|
| 88 | Galactic Longitude [arcmin]. |
---|
| 89 | \item[w\_DEC/w\_GLAT] The width of the object in Declination Galactic |
---|
| 90 | Latitude [arcmin]. |
---|
| 91 | \item[w\_VEL] The full velocity width of the detection (max channel |
---|
| 92 | $-$ min channel, in velocity units [see note below]). |
---|
| 93 | \item[F\_int] The integrated flux over the object, in the units of |
---|
| 94 | flux times velocity, corrected for the beam if necessary. |
---|
| 95 | \item[F\_peak] The peak flux over the object, in the units of flux. |
---|
| 96 | \item[X1, X2] The minimum and maximum X-pixel coordinates. |
---|
| 97 | \item[Y1, Y2] The minimum and maximum Y-pixel coordinates. |
---|
| 98 | \item[Z1, Z2] The minimum and maximum Z-pixel coordinates. |
---|
| 99 | \item[Npix] The number of voxels (\ie distinct $(x,y,z)$ coordinates) |
---|
| 100 | in the detection. |
---|
| 101 | \item[Flag] Whether the detection has any warning flags (see below). |
---|
| 102 | \end{entry} |
---|
[162] | 103 | |
---|
[158] | 104 | The Name is derived from the WCS position. For instance, a source |
---|
| 105 | centred on the RA,Dec position 12$^h$53$^m$45$^s$, |
---|
| 106 | -36$^\circ$24$'$12$''$ will be called J125345$-$362412 (if the epoch |
---|
| 107 | is J2000) or B125345$-$362412 (if B1950). An alternative form is used |
---|
| 108 | for Galactic coordinates: a source centred on the position ($l$,$b$) = |
---|
| 109 | (323.1245, 5.4567) will be called G323.124$+$05.457. If the WCS is not |
---|
| 110 | valid (\ie is not present or does not have all the necessary |
---|
| 111 | information), the Name, RA, DEC, VEL and related columns are not |
---|
| 112 | printed, but the pixel coordinates are still provided. |
---|
| 113 | |
---|
| 114 | The velocity units can be specified by the user, using the parameter |
---|
| 115 | \texttt{spectralUnits} (enter it as a single string). The default |
---|
| 116 | value is km/s, which should be suitable for most users. These units |
---|
| 117 | are also used to give the units of integrated flux. Note that if there |
---|
| 118 | is no rest frequency specified in the FITS header, the \duchamp\ |
---|
| 119 | output will instead default to using Frequency, with units of MHz. |
---|
| 120 | |
---|
| 121 | If the WCS is not specified sufficiently to be used, then all columns |
---|
| 122 | from RA/GLON to w\_VEL will be left blank. Also, F\_int will be |
---|
| 123 | replaced with the more simple F\_tot -- the total flux in the |
---|
| 124 | detection, being the sum of all detected voxels. |
---|
| 125 | |
---|
| 126 | The last column contains any warning flags about the detection. There |
---|
| 127 | are currently two options here. An `E' is printed if the detection is |
---|
| 128 | next to the edge of the image, meaning either the limit of the pixels, |
---|
| 129 | or the limit of the non-BLANK pixel region. An `N' is printed if the |
---|
| 130 | total flux, summed over all the (non-BLANK) pixels in the smallest box |
---|
| 131 | that completely encloses the detection, is negative. Note that this |
---|
| 132 | sum is likely to include non-detected pixels. It is of use in pointing |
---|
| 133 | out detections that lie next to strongly negative pixels, such as |
---|
| 134 | might arise due to interference -- the detected pixels might then also |
---|
| 135 | be due to the interference, so caution is advised. |
---|
| 136 | |
---|
| 137 | \secC{Other results lists} |
---|
| 138 | |
---|
[162] | 139 | Two additional results files can also be requested. One option is a |
---|
[158] | 140 | VOTable-format XML file, containing just the RA, Dec, Velocity and the |
---|
| 141 | corresponding widths of the detections, as well as the fluxes. The |
---|
| 142 | user should set \texttt{flagVOT = 1}, and put the desired filename in |
---|
| 143 | the parameter \texttt{votFile} -- note that the default is for it not |
---|
| 144 | to be produced. This file should be compatible with all Virtual |
---|
| 145 | Observatory tools (such as Aladin\footnote{ Aladin can be found on the |
---|
| 146 | web at |
---|
| 147 | \href{http://aladin.u-strasbg.fr/}{http://aladin.u-strasbg.fr/}}). The |
---|
| 148 | second option is an annotation file for use with the Karma toolkit of |
---|
| 149 | visualisation tools (in particular, with \texttt{kvis}). This will |
---|
[162] | 150 | draw a circle at the position of each detection, scaled by the spatial |
---|
| 151 | size of the detection, and number it according to the Obj\# given |
---|
| 152 | above. To make use of this option, the user should set |
---|
| 153 | \texttt{flagKarma = 1}, and put the desired filename in the parameter |
---|
| 154 | \texttt{karmaFile} -- again, the default is for it not to be produced. |
---|
[158] | 155 | |
---|
| 156 | As the program is running, it also (optionally) records the detections |
---|
| 157 | made in each individual spectrum or channel (see \S\ref{sec-detection} |
---|
| 158 | for details on this process). This is recorded in the file given by |
---|
| 159 | the parameter \texttt{LogFile}. This file does not include the columns |
---|
| 160 | \texttt{Name, RA, DEC, w\_RA, w\_DEC, VEL, w\_VEL}. This file is |
---|
| 161 | designed primarily for diagnostic purposes: \eg to see if a given set |
---|
| 162 | of pixels is detected in, say, one channel image, but does not survive |
---|
| 163 | the merging process. The list of pixels (and their fluxes) in the |
---|
| 164 | final detection list are also printed to this file, again for |
---|
| 165 | diagnostic purposes. The file also records the execution time, as well |
---|
| 166 | as the command-line statement used to run \duchamp. The creation of |
---|
[162] | 167 | this log file can be prevented by setting \texttt{flagLog = false}. |
---|
[158] | 168 | |
---|
| 169 | \secC{Graphical output -- spectra} |
---|
| 170 | |
---|
[160] | 171 | \begin{figure}[t] |
---|
| 172 | \begin{center} |
---|
| 173 | \includegraphics[width=\textwidth]{example_spectrum} |
---|
| 174 | \end{center} |
---|
| 175 | \caption{\footnotesize An example of the spectrum output. Note several |
---|
| 176 | of the features discussed in the text: the red lines indicating the |
---|
| 177 | reconstructed spectrum; the blue dashed lines indicating the |
---|
| 178 | spectral extent of the detection; the green hashed area indicating |
---|
| 179 | the Milky Way channels that are ignored by the searching algorithm; |
---|
| 180 | the blue border showing its spatial extent on the 0th moment map; |
---|
| 181 | and the 15~arcmin-long scale bar.} |
---|
| 182 | \label{fig-spect} |
---|
| 183 | \end{figure} |
---|
| 184 | |
---|
| 185 | \begin{figure}[!t] |
---|
| 186 | \begin{center} |
---|
| 187 | \includegraphics[width=\textwidth]{example_moment_map} |
---|
| 188 | \end{center} |
---|
| 189 | \caption{\footnotesize An example of the moment map created by |
---|
| 190 | \duchamp. The full extent of the cube is covered, and the 0th moment |
---|
| 191 | of each object is shown (integrated individually over all the |
---|
| 192 | detected channels). The purple line indicates the limit of the |
---|
| 193 | non-BLANK pixels.} |
---|
| 194 | \label{fig-moment} |
---|
| 195 | \end{figure} |
---|
| 196 | |
---|
[158] | 197 | As well as the output data file, a postscript file is created that |
---|
| 198 | shows the spectrum for each detection, together with a small cutout |
---|
| 199 | image (the 0th moment) and basic information about the detection (note |
---|
| 200 | that any flags are printed after the name of the detection, in the |
---|
| 201 | format \texttt{[E]}). If the cube was reconstructed, the spectrum from |
---|
| 202 | the reconstruction is shown in red, over the top of the original |
---|
| 203 | spectrum. The spectral extent of the detected object is indicated by |
---|
| 204 | two dashed blue lines, and the region covered by the ``Milky Way'' |
---|
| 205 | channels is shown by a green hashed box. An example detection can be |
---|
| 206 | seen below in Fig.~\ref{fig-spect}. |
---|
| 207 | |
---|
| 208 | The spectrum that is plotted is governed by the |
---|
[162] | 209 | \texttt{spectralMethod} parameter. It can be either \texttt{peak} (the |
---|
| 210 | default), where the spectrum is from the spatial pixel containing the |
---|
[158] | 211 | detection's peak flux; or \texttt{sum}, where the spectrum is summed |
---|
| 212 | over all spatial pixels, and then corrected for the beam size. The |
---|
| 213 | spectral extent of the detection is indicated with blue lines, and a |
---|
| 214 | zoom is shown in a separate window. |
---|
| 215 | |
---|
| 216 | The cutout image can optionally include a border around the spatial |
---|
| 217 | pixels that are in the detection (turned on and off by the parameter |
---|
| 218 | \texttt{drawBorders} -- the default is \texttt{true}). It includes a |
---|
| 219 | scale bar in the bottom left corner to indicate size -- its length is |
---|
| 220 | indicated next to it (the choice of length depends on the size of the |
---|
| 221 | image). |
---|
| 222 | |
---|
| 223 | There may also be one or two extra lines on the image. A yellow line |
---|
[162] | 224 | shows the limits of the cube's spatial region: when this is shown, the |
---|
| 225 | detected object will lie close to the edge, and the image box will |
---|
| 226 | extend outside the region covered by the data. A purple line, however, |
---|
| 227 | shows the dividing line between BLANK and non-BLANK pixels. The BLANK |
---|
| 228 | pixels will always be shown in black. The first type of line is always |
---|
| 229 | drawn, while the second is governed by the parameter |
---|
| 230 | \texttt{drawBlankEdges} (whose default is \texttt{true}), and |
---|
| 231 | obviously whether there are any BLANK pixel present. |
---|
[158] | 232 | |
---|
| 233 | \secC{Graphical output -- maps} |
---|
| 234 | |
---|
| 235 | Finally, a couple of images are optionally produced: a 0th moment map |
---|
| 236 | of the cube, combining just the detected channels in each object, |
---|
| 237 | showing the integrated flux in grey-scale; and a ``detection image'', |
---|
| 238 | a grey-scale image where the pixel values are the number of channels |
---|
| 239 | that spatial pixel is detected in. In both cases, if |
---|
| 240 | \texttt{drawBorders = true}, a border is drawn around the spatial |
---|
| 241 | extent of each detection, and if \texttt{drawBlankEdges = true}, the |
---|
| 242 | purple line dividing BLANK and non-BLANK pixels (as described above) |
---|
| 243 | is drawn. An example moment map is shown in Fig.~\ref{fig-moment}. |
---|
| 244 | The production or otherwise of these images is governed by the |
---|
| 245 | \texttt{flagMaps} parameter. |
---|
| 246 | |
---|
| 247 | The purpose of these images are to provide a visual guide to where the |
---|
| 248 | detections have been made, and, particularly in the case of the moment |
---|
| 249 | map, to provide an indication of the strength of the source. In both |
---|
| 250 | cases, the detections are numbered (in the same sense as the output |
---|
| 251 | list and as the spectral plots), and the spatial borders are marked |
---|
| 252 | out as for the cutout images in the spectra file. Both these images |
---|
| 253 | are saved as postscript files (given by the parameters |
---|
| 254 | \texttt{momentMap} and \texttt{detectionMap} respectively), with the |
---|
| 255 | latter also displayed in a \textsc{pgplot} window (regardless of the |
---|
| 256 | state of \texttt{flagMaps}). |
---|