[303] | 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 | % ----------------------------------------------------------------------- |
---|
[158] | 29 | \secA{Outputs} |
---|
| 30 | \label{sec-output} |
---|
| 31 | |
---|
| 32 | \secB{During execution} |
---|
[1078] | 33 | |
---|
[258] | 34 | \duchamp provides the user with feedback whilst it is running, to |
---|
[158] | 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 |
---|
[964] | 40 | Appendix~\ref{app-input} for an example). |
---|
[158] | 41 | |
---|
[964] | 42 | The extent of memory allocation made at the start is indicated. This |
---|
| 43 | will include the arrays needed for the pixel array, the reconstruction |
---|
| 44 | or smoothed array, and the 2D detection map, but \emph{not} additional |
---|
| 45 | space needed for working within individual algorithms, nor storage |
---|
| 46 | needed for the detected objects. |
---|
| 47 | |
---|
[766] | 48 | \duchamp will report the amount of memory that is allocated when the |
---|
| 49 | image is read in. This includes the storage for the array as well as |
---|
| 50 | additional storage for the reconstructed/smoothed array and/or the |
---|
| 51 | baseline arrays (if these are needed). |
---|
| 52 | |
---|
[158] | 53 | If the cube is being trimmed (\S\ref{sec-modify}), the resulting |
---|
| 54 | dimensions are printed to indicate how much has been trimmed. If a |
---|
| 55 | reconstruction is being done, a continually updating message shows |
---|
| 56 | either the current iteration and scale, compared to the maximum scale |
---|
[298] | 57 | (when \texttt{reconDim = 3}), or a progress bar showing the amount of |
---|
[158] | 58 | the cube that has been reconstructed (for smaller values of |
---|
| 59 | \texttt{reconDim}). |
---|
| 60 | |
---|
[298] | 61 | During the searching algorithms, the progress through the search is |
---|
| 62 | shown. When completed, the number of objects found is reported (this |
---|
| 63 | is the total number found, before any merging is done). |
---|
[158] | 64 | |
---|
| 65 | In the merging process (where multiple detections of the same object |
---|
| 66 | are combined -- see \S\ref{sec-merger}), two stages of output |
---|
| 67 | occur. The first is when each object in the list is compared with all |
---|
| 68 | others. The output shows two numbers: the first being how far through |
---|
| 69 | the list the current object is, and the second being the length of the |
---|
| 70 | list. As the algorithm proceeds, the first number should increase and |
---|
| 71 | the second should decrease (as objects are combined). When the numbers |
---|
[265] | 72 | meet, the whole list has been compared. If the objects are being |
---|
| 73 | grown, a similar output is shown, indicating the progress through the |
---|
| 74 | list. In the rejection stage, in which objects not meeting the minimum |
---|
| 75 | pixels/channels requirements are removed, the total number of objects |
---|
| 76 | remaining in the list is shown, which should steadily decrease with |
---|
| 77 | each rejection until all have been examined. Note that these steps can |
---|
| 78 | be very quick for small numbers of detections. |
---|
[158] | 79 | |
---|
| 80 | Since this continual printing to screen has some overhead of time and |
---|
| 81 | CPU involved, the user can elect to not print this information by |
---|
[298] | 82 | setting the parameter \texttt{verbose = false}. In this case, the user |
---|
| 83 | is still informed as to the steps being undertaken, but the details of |
---|
[158] | 84 | the progress are not shown. |
---|
| 85 | |
---|
[162] | 86 | There may also be Warning or Error messages printed to screen. The |
---|
| 87 | Warning messages occur when something happens that is unexpected (for |
---|
| 88 | instance, a desired keyword is not present in the FITS header), but |
---|
| 89 | not detrimental to the execution. An Error message is something more |
---|
| 90 | serious, and indicates some part of the program was not able to |
---|
[964] | 91 | complete its task. This is not necessary fatal, but it may mean the |
---|
| 92 | full functionality requested will not be achieved. The message will |
---|
| 93 | also indicate which function or subroutine generated it -- this is |
---|
| 94 | primarily a tool for debugging, but can be useful in determining what |
---|
| 95 | went wrong. |
---|
[162] | 96 | |
---|
[285] | 97 | \secB{Text-based output files} |
---|
[158] | 98 | |
---|
| 99 | \secC{Table of results} |
---|
[285] | 100 | \label{sec-results} |
---|
[158] | 101 | |
---|
[258] | 102 | Finally, we get to the results -- the reason for running \duchamp in |
---|
[1159] | 103 | the first place. Once the detection list is finalised and |
---|
| 104 | parameterised according to \S\ref{sec-sourceparam}, it is sorted |
---|
[571] | 105 | according to the value of the \texttt{sortingParam}. This can take the |
---|
[964] | 106 | value ``xvalue'', ``yvalue'', ``zvalue'', ``ra'', ``dec'', ``vel'', |
---|
[571] | 107 | ``w50'', ``iflux'' (for integrated flux), or ``pflux'' (for peak |
---|
[964] | 108 | flux), or ``snr''. The default value is ``vel'' (which means the |
---|
| 109 | spectral WCS value -- this could be frequency or wavelength depending |
---|
| 110 | on the nature of the FITS file). If no good WCS exists, the mean pixel |
---|
| 111 | position equivalent is used (``ra'' is replaced by ``xvalue'', ``dec'' |
---|
| 112 | by ``yvalue'', ``vel'' and ``w50'' by ``zvalue''). The sense of the |
---|
| 113 | sorting will be increasing value with position in the list. To sort in |
---|
| 114 | the opposite sense, prepend the parameter name with a '-' (\eg |
---|
[1159] | 115 | ``-vel'' instead of ``vel''). The object ID number |
---|
| 116 | (\S\ref{sec-objectID}) is determined by the order of the list |
---|
| 117 | \emph{after} this sorting, so sorting by a different parameter will |
---|
| 118 | result in a different object ID for the same object. |
---|
| 119 | |
---|
| 120 | The results are then printed to the screen and to the output file, |
---|
| 121 | given by the \texttt{OutFile} parameter. The output file will contain |
---|
| 122 | all calculated parameters, as described in |
---|
| 123 | \S\ref{sec-sourceparam}. The results list printed to the screen, |
---|
| 124 | however, will leave out certain columns: |
---|
| 125 | \begin{itemize} |
---|
| 126 | \item The spatial extent columns \texttt{w\_RA \& w\_DEC}. |
---|
| 127 | \item The \texttt{w\_20} and \texttt{w\_VEL} spectral width columns. |
---|
| 128 | \item The total flux \texttt{F\_tot} (unless there is no good WCS, in |
---|
| 129 | which case it is printed instead of \texttt{F\_int}), and the errors |
---|
| 130 | on the total and integrated fluxes \texttt{eF\_tot, eF\_int}. |
---|
| 131 | \item The explicit columns for the average, centroid and peak pixel |
---|
| 132 | locations. The only pixel location columns printed are \texttt{X, Y, |
---|
| 133 | Z}, which are determined via the \texttt{pixelCentre} input |
---|
[964] | 134 | parameter. |
---|
[1159] | 135 | \item \textit{If the WCS is no good}, the world-coordinate columns |
---|
| 136 | \texttt{RA, DEC, VEL, F\_int} will not be printed either. |
---|
| 137 | \end{itemize} |
---|
[158] | 138 | |
---|
[1159] | 139 | The output file consists of two sections. The first section contains |
---|
| 140 | the metadata for the search. First, a list of the parameters are |
---|
| 141 | printed to the output file, for future reference. Next, the detection |
---|
| 142 | threshold that was used is given, so comparison can be made with other |
---|
| 143 | searches. The statistics estimating the noise parameters are given |
---|
| 144 | (see \S\ref{sec-stats}). Thirdly, the number of detections are |
---|
| 145 | reported. |
---|
[194] | 146 | |
---|
[364] | 147 | All this information, known as the ``header'', can either be written |
---|
| 148 | to the start of the output file (denoted by the parameter |
---|
| 149 | \texttt{OutFile}), or written to a separate file from the list of |
---|
| 150 | detections. This second option is activated by the parameter |
---|
| 151 | \texttt{flagSeparateHeader}, and the information is written to the |
---|
| 152 | file given by \texttt{HeaderFile}. |
---|
| 153 | |
---|
[1159] | 154 | The second part of the file, however, contains the most interesting |
---|
| 155 | part -- the list of detected objects. This is written as an ASCII |
---|
| 156 | table, properly spaced so that it is readable. An example is shown in |
---|
| 157 | Appendix~\ref{app-output}. |
---|
[194] | 158 | |
---|
[1159] | 159 | The user can specify the precision used to display the flux, spectral |
---|
| 160 | location/width and S/Nmax values, by using the input parameters |
---|
| 161 | \texttt{precFlux}, \texttt{precVel} and \texttt{precSNR} |
---|
| 162 | respectively. These values apply to the tables written to the screen |
---|
| 163 | and to the output file, as well as for the VOTable (see below). |
---|
[162] | 164 | |
---|
[801] | 165 | |
---|
[1159] | 166 | \secC{VOTable catalogue} |
---|
| 167 | \label{sec-votable} |
---|
[285] | 168 | |
---|
[425] | 169 | Three additional results files can also be requested. One option is a |
---|
[1159] | 170 | VOTable-format XML file, containing just the RA, Dec, spectral |
---|
| 171 | location and the corresponding widths of the detections, as well as |
---|
| 172 | the fluxes. The user should set \texttt{flagVOT = true}, and put the |
---|
| 173 | desired filename in the parameter \texttt{votFile} -- note that the |
---|
| 174 | default is for it not to be produced. An example of VOTable output can |
---|
| 175 | be found in Appendix~\ref{app-votable}. This file should be |
---|
| 176 | compatible with all Virtual Observatory tools (such as Aladin% |
---|
[285] | 177 | \footnote{%Aladin can be found on the web at |
---|
[1078] | 178 | \href{http://aladin.u-strasbg.fr/}{http://aladin.u-strasbg.fr/}} or |
---|
| 179 | TOPCAT\footnote{%Tool for OPerations on Catalogues And Tables: |
---|
| 180 | \href{http://www.star.bristol.ac.uk/~mbt/topcat/}% |
---|
| 181 | {http://www.star.bristol.ac.uk/~mbt/topcat/}}). |
---|
[158] | 182 | |
---|
[1159] | 183 | \secC{Annotation and region files} |
---|
| 184 | \label{sec-annotfiles} |
---|
| 185 | |
---|
[1161] | 186 | A second option are annotation files for use with several |
---|
| 187 | visualisation tools, including the Karma toolkit (in particular, with |
---|
| 188 | \texttt{kvis}), SAOImage DS9, and \texttt{casaviewer} (and |
---|
| 189 | \texttt{casapy} itself). |
---|
[425] | 190 | |
---|
[1161] | 191 | There are three options on how objects are represented, governed by the |
---|
| 192 | \texttt{annotationType} parameter. These are: |
---|
| 193 | \begin{itemize} |
---|
| 194 | \item \texttt{borders} -- a border is drawn around the spatial pixels |
---|
| 195 | of the object, in a manner similar to that seen in |
---|
| 196 | Fig.~\ref{fig-spect}. Note that Karma/\texttt{kvis} does not always |
---|
| 197 | do this perfectly, particularly as you change the zoom, so the lines |
---|
| 198 | may not be directly lined up with pixel borders. |
---|
| 199 | \item \texttt{circles} -- draws a circle at the position of each |
---|
| 200 | detection, scaled by the spatial size of the detection. |
---|
| 201 | \item \texttt{ellipses} -- draws an ellipse of size given by the |
---|
| 202 | \texttt{MAJ, MIN, PA} source parameters (\S\ref{sec-shape}). |
---|
| 203 | \end{itemize} |
---|
| 204 | In each case, the object is numbered according to the object ID |
---|
| 205 | (\S\ref{sec-objectID}. To make use of this option, the user should set |
---|
| 206 | \texttt{flagKarma}, \texttt{flagDS9} or \texttt{flagCasa} to |
---|
| 207 | \texttt{true}, and put the desired filename in the parameter |
---|
| 208 | \texttt{karmaFile}, \texttt{ds9File} or \texttt{casaFile} -- again, |
---|
| 209 | the default is for these not to be produced. Examples of these |
---|
| 210 | annotation files are in |
---|
| 211 | Appendices~\ref{app-karma},\ref{app-ds9},\ref{app-casa}. |
---|
| 212 | |
---|
[1159] | 213 | \secC{Spectral text file} |
---|
| 214 | \label{sec-spectraltext} |
---|
| 215 | |
---|
[425] | 216 | The final optional results file produced is a simple text file that |
---|
| 217 | contains the spectra for each detected object. The format of the file |
---|
| 218 | is as follows: the first column has the spectral coordinate, over the |
---|
| 219 | full range of values; the remaining columns represent the flux values |
---|
| 220 | for each object at the corresponding spectral position. The flux value |
---|
| 221 | used is the same as that plotted in the spectral plot detailed below, |
---|
| 222 | and governed by the \texttt{spectralMethod} parameter. An example of |
---|
| 223 | what a spectral text file might look like is given below: |
---|
| 224 | |
---|
| 225 | \begin{quote} |
---|
| 226 | {\footnotesize |
---|
| 227 | \begin{tabular}{lllll} |
---|
| 228 | 1405.00219727 &0.01323344 &0.23648241 &0.04202826 &-0.00506790 \\ |
---|
| 229 | 1405.06469727 &0.01302835 &0.27393046 &0.04686056 &-0.00471084 \\ |
---|
| 230 | 1405.12719727 &0.01583361 &0.27760920 &0.04114933 &-0.01168737 \\ |
---|
| 231 | 1405.18969727 &0.01271889 &0.31489247 &0.03307962 &-0.00300790 \\ |
---|
| 232 | 1405.25219727 &0.01597644 &0.30401203 &0.05356426 &-0.00551653 \\ |
---|
| 233 | 1405.31469727 &0.00773827 &0.30031312 &0.04074831 &-0.00570147 \\ |
---|
| 234 | 1405.37719727 &0.00738304 &0.27921870 &0.05272378 &-0.00504959 \\ |
---|
| 235 | 1405.43969727 &0.01353923 &0.26132512 &0.03667958 &-0.00151006 \\ |
---|
| 236 | 1405.50219727 &0.01119724 &0.28987029 &0.03497849 &-0.00645589 \\ |
---|
| 237 | 1405.56469727 &0.00813379 &0.29839963 &0.04711142 &0.00536576 \\ |
---|
| 238 | 1405.62719727 &0.00774377 &0.26530230 &0.04620502 &0.00724631 \\ |
---|
| 239 | 1405.68969727 &0.00576067 &0.23215000 &0.04995513 &0.00290841 \\ |
---|
| 240 | 1405.75219727 &0.00452834 &0.16484940 &0.04261605 &-0.00612812 \\ |
---|
| 241 | 1405.81469727 &0.01406293 &0.15989439 &0.03817926 &-0.00758385 \\ |
---|
| 242 | 1405.87719727 &0.01116611 &0.11890682 &0.05499069 &-0.00626362 \\ |
---|
| 243 | 1405.93969727 &0.00687582 &0.10620256 &0.04743370 &0.00055177 \\ |
---|
| 244 | $\vdots$ &$\vdots$ &$\vdots$ &$\vdots$ &$\vdots$ \\ |
---|
| 245 | \end{tabular} |
---|
| 246 | } |
---|
| 247 | \end{quote} |
---|
| 248 | |
---|
[1159] | 249 | \secC{Log file} |
---|
| 250 | \label{sec-logfile} |
---|
| 251 | |
---|
[425] | 252 | In addition to these three files, a log file can also be produced. As |
---|
| 253 | the program is running, it also (optionally) records the detections |
---|
[158] | 254 | made in each individual spectrum or channel (see \S\ref{sec-detection} |
---|
| 255 | for details on this process). This is recorded in the file given by |
---|
| 256 | the parameter \texttt{LogFile}. This file does not include the columns |
---|
| 257 | \texttt{Name, RA, DEC, w\_RA, w\_DEC, VEL, w\_VEL}. This file is |
---|
| 258 | designed primarily for diagnostic purposes: \eg to see if a given set |
---|
| 259 | of pixels is detected in, say, one channel image, but does not survive |
---|
| 260 | the merging process. The list of pixels (and their fluxes) in the |
---|
| 261 | final detection list are also printed to this file, again for |
---|
| 262 | diagnostic purposes. The file also records the execution time, as well |
---|
| 263 | as the command-line statement used to run \duchamp. The creation of |
---|
[280] | 264 | this log file can be prevented by setting \texttt{flagLog = false} |
---|
| 265 | (which is the default). |
---|
[158] | 266 | |
---|
[285] | 267 | \secB{Graphical output} |
---|
[380] | 268 | |
---|
[447] | 269 | |
---|
[285] | 270 | \secC{Spectral plots} |
---|
[158] | 271 | |
---|
[373] | 272 | As well as the output data file, a postscript file (with the filename |
---|
| 273 | given by the \texttt{spectralFile} parameter) is created that shows |
---|
| 274 | the spectrum for each detection, together with a small cutout image |
---|
| 275 | (the 0th moment) and basic information about the detection (note that |
---|
| 276 | any flags are printed after the name of the detection, in the format |
---|
| 277 | \texttt{[E]}). If the cube was reconstructed, the spectrum from the |
---|
| 278 | reconstruction is shown in red, over the top of the original |
---|
[1262] | 279 | spectrum. If the spectral baseline was removed prior to source |
---|
| 280 | detection, this is shown in yellow. The spectral extent of the |
---|
| 281 | detected object is indicated by two dashed blue lines, and the regions |
---|
| 282 | covered by the flagged channels are shown by green hashed boxes. An |
---|
| 283 | example detection can be seen in Fig.~\ref{fig-spect}. |
---|
[285] | 284 | |
---|
[158] | 285 | The spectrum that is plotted is governed by the |
---|
[162] | 286 | \texttt{spectralMethod} parameter. It can be either \texttt{peak} (the |
---|
| 287 | default), where the spectrum is from the spatial pixel containing the |
---|
[158] | 288 | detection's peak flux; or \texttt{sum}, where the spectrum is summed |
---|
[1017] | 289 | over all spatial pixels, and then corrected for the beam size. If the |
---|
| 290 | \texttt{peak} method is used, the detection threshold (and growth |
---|
[1262] | 291 | threshold, if used) are indicated by dashed (and dotted) lines. When |
---|
| 292 | the spectral baseline has been removed, the thresholds will be a |
---|
| 293 | constant level above this (and so reflect its variability). Otherwise, |
---|
| 294 | the thresholds will be horizontal lines. The thresholds cannot be |
---|
| 295 | plotted on the integrated spectrum. The spectral extent of the |
---|
| 296 | detection is indicated with blue lines, and a zoom is shown in a |
---|
[1017] | 297 | separate window. |
---|
[158] | 298 | |
---|
[1017] | 299 | \begin{figure}[t] |
---|
| 300 | \begin{center} |
---|
| 301 | \includegraphics[width=\textwidth]{example_spectrum} |
---|
| 302 | \end{center} |
---|
| 303 | \caption{\footnotesize An example of the spectral output. Note |
---|
| 304 | several of the features discussed in the text: the red solid lines |
---|
[1177] | 305 | indicating the reconstructed spectrum; the blue dashed and dotted |
---|
[1017] | 306 | horizontal lines indicating the detection and growth thresholds |
---|
| 307 | respectively; the blue dashed lines indicating the spectral extent |
---|
[1262] | 308 | of the detection; the green hashed area indicating the flagged |
---|
[1017] | 309 | channels that are ignored by the searching algorithm; the blue |
---|
[1177] | 310 | border showing its spatial extent on the 0th moment map; the |
---|
| 311 | ellipses indicating the size of the object and the beam; and the |
---|
[1017] | 312 | 15~arcmin-long scale bar.} |
---|
| 313 | \label{fig-spect} |
---|
| 314 | \end{figure} |
---|
| 315 | |
---|
[1177] | 316 | The cutout image shows a red ellipse indicating the spatial size of the |
---|
| 317 | detection (using \texttt{MAJ, MIN, PA} - \S\ref{sec-shape}). Also |
---|
| 318 | drawn in green in the corner of the image is an ellipse indicating the |
---|
| 319 | beam size (assuming the beam is defined). |
---|
| 320 | |
---|
[158] | 321 | The cutout image can optionally include a border around the spatial |
---|
[231] | 322 | pixels that are in the detection (turned on and off by the |
---|
| 323 | \texttt{drawBorders} parameter -- the default is \texttt{true}). It |
---|
| 324 | includes a scale bar in the bottom left corner to indicate size -- its |
---|
| 325 | length is indicated next to it (the choice of length depends on the |
---|
| 326 | size of the image). |
---|
[158] | 327 | |
---|
| 328 | There may also be one or two extra lines on the image. A yellow line |
---|
[162] | 329 | shows the limits of the cube's spatial region: when this is shown, the |
---|
| 330 | detected object will lie close to the edge, and the image box will |
---|
| 331 | extend outside the region covered by the data. A purple line, however, |
---|
| 332 | shows the dividing line between BLANK and non-BLANK pixels. The BLANK |
---|
| 333 | pixels will always be shown in black. The first type of line is always |
---|
| 334 | drawn, while the second is governed by the parameter |
---|
| 335 | \texttt{drawBlankEdges} (whose default is \texttt{true}), and |
---|
| 336 | obviously whether there are any BLANK pixel present. |
---|
[158] | 337 | |
---|
[831] | 338 | Note that the creation of the spectral plots can be prevented by |
---|
| 339 | setting \texttt{flagPlotSpectra = false}. |
---|
| 340 | |
---|
[373] | 341 | When the input image is two-dimensional, with no spectral dimension, |
---|
| 342 | this spectral plot would not make much sense. Instead, \duchamp |
---|
| 343 | creates a similar postscript file that simply includes the text |
---|
| 344 | headers as well as the 0th-moment map of the detection. As for the |
---|
| 345 | normal spectral case, this file will be written to the filename given |
---|
| 346 | by the \texttt{spectralFile} parameter. |
---|
| 347 | |
---|
[1017] | 348 | When the input image is one-dimensional, the spectral plot is |
---|
| 349 | identical save for the absence of the cutout image. |
---|
| 350 | |
---|
[1159] | 351 | In addition to the spectral plot, it is possible to produce plots for |
---|
| 352 | each spectrum individually. Set |
---|
| 353 | \texttt{flagPlotIndividualSpectra=true}, and a postscript plot will be |
---|
| 354 | produced for each object. If the normal spectral output file |
---|
| 355 | (determined by the \texttt{spectralFile} input parameter) is called |
---|
| 356 | \texttt{duchamp-Spectra.ps}, then the individual files will be called |
---|
| 357 | \texttt{duchamp-Spectra-01.ps} etc. |
---|
| 358 | |
---|
| 359 | |
---|
[285] | 360 | \secC{Spatial maps} |
---|
[1011] | 361 | \label{sec-spatialmaps} |
---|
[158] | 362 | |
---|
[1017] | 363 | \begin{figure}[!t] |
---|
| 364 | \begin{center} |
---|
| 365 | \includegraphics[width=\textwidth]{example_moment_map} |
---|
| 366 | \end{center} |
---|
| 367 | \caption{\footnotesize An example of the moment map created by |
---|
| 368 | \duchamp. The full extent of the cube is covered, and the 0th moment |
---|
| 369 | of each object is shown (integrated individually over all the |
---|
| 370 | detected channels). The purple line indicates the limit of the |
---|
| 371 | non-BLANK pixels.} |
---|
| 372 | \label{fig-moment} |
---|
| 373 | \end{figure} |
---|
| 374 | |
---|
| 375 | Additionally, two types of spatial images are optionally produced: a |
---|
| 376 | combined 0th-moment map of the cube, combining just the detected |
---|
| 377 | channels in each object, showing the integrated flux in grey-scale; |
---|
| 378 | and a ``detection image'', a grey-scale image where the pixel values |
---|
| 379 | are the number of channels in which that spatial pixel is |
---|
| 380 | detected. These detections include pixels that are subsequently |
---|
[1262] | 381 | discarded (due to the minimum- or maximum-size criteria). In both |
---|
| 382 | cases, if \texttt{drawBorders = true}, a border is drawn around the |
---|
| 383 | spatial extent of each detection, and if \texttt{drawBlankEdges = |
---|
| 384 | true}, the purple line dividing BLANK and non-BLANK pixels (as |
---|
| 385 | described above) is drawn. An example moment map is shown in |
---|
| 386 | Fig.~\ref{fig-moment}. The production or otherwise of these images is |
---|
| 387 | governed by the \texttt{flagMaps} parameter. |
---|
[158] | 388 | |
---|
[285] | 389 | The moment map is also displayed in a PGPlot XWindow (with the |
---|
| 390 | \texttt{/xs} display option). This feature can be turned off by |
---|
[298] | 391 | setting \texttt{flagXOutput = false} -- this might be useful if |
---|
| 392 | running \duchamp on a terminal with no window display capability, or |
---|
| 393 | if you have set up a script to run it in a batch mode. |
---|
[195] | 394 | |
---|
[1017] | 395 | If the input image is one-dimensional, such a spatial map is not |
---|
| 396 | possible. Instead, the detection map becomes a detection |
---|
| 397 | spectrum. This shows the full spectral range, indicating (as for the |
---|
| 398 | spectral plots above) the detection and growth thresholds, as well as |
---|
[1262] | 399 | the flagged channels and every detection that appears in the final |
---|
[1017] | 400 | catalogue. It also indicates all pixels that were detected, including |
---|
| 401 | those subsequently discarded, by thick black lines above the |
---|
| 402 | spectrum. An example can be see in |
---|
| 403 | Fig.~\ref{fig-1D-detection-spectrum}. Again, this plot is also |
---|
| 404 | displayed in a PGPlot XWindow. |
---|
[670] | 405 | |
---|
[1017] | 406 | \begin{figure}[!t] |
---|
| 407 | \begin{center} |
---|
| 408 | \includegraphics[width=\textwidth]{example_detection_spectrum} |
---|
| 409 | \end{center} |
---|
| 410 | \caption{\footnotesize An example of the one-dimensional detection |
---|
| 411 | spectrum plot, indicating detected sources and detected pixels, |
---|
| 412 | including those subsquently discarded due to the minimum-size |
---|
| 413 | criteria. The detection threshold is low to show the effect of |
---|
| 414 | detecting lots of single-pixel channels, which are then discarded, |
---|
| 415 | leaving just the two detections delimited by the blue lines.} |
---|
| 416 | \label{fig-1D-detection-spectrum} |
---|
| 417 | \end{figure} |
---|
| 418 | |
---|
| 419 | |
---|
| 420 | |
---|
| 421 | The purpose of these images is to provide a visual guide to where the |
---|
[158] | 422 | detections have been made, and, particularly in the case of the moment |
---|
| 423 | map, to provide an indication of the strength of the source. In both |
---|
| 424 | cases, the detections are numbered (in the same sense as the output |
---|
| 425 | list and as the spectral plots), and the spatial borders are marked |
---|
| 426 | out as for the cutout images in the spectra file. Both these images |
---|
| 427 | are saved as postscript files (given by the parameters |
---|
| 428 | \texttt{momentMap} and \texttt{detectionMap} respectively), with the |
---|
| 429 | latter also displayed in a \textsc{pgplot} window (regardless of the |
---|
| 430 | state of \texttt{flagMaps}). |
---|
[482] | 431 | |
---|
[1017] | 432 | \secB{FITS output} |
---|
[482] | 433 | |
---|
[1017] | 434 | \secC{Moment map} |
---|
[1142] | 435 | \label{sec-momentOut} |
---|
[482] | 436 | |
---|
[1017] | 437 | The moment map described above can also be written to a FITS file, so |
---|
| 438 | that it can be examined more closely, and have annotation files |
---|
| 439 | overlaid. This works in the same way as for the mask image. To create |
---|
| 440 | the FITS file, set the input parameter |
---|
| 441 | \texttt{flagOutputMomentMap=true}. The file will be named according to |
---|
| 442 | the \texttt{fileOutputMomentMap} parameter, or, if this is not given, |
---|
| 443 | \texttt{image.MOM0.fits} (where the input image is called |
---|
| 444 | \texttt{image.fits}). |
---|
| 445 | |
---|
[1142] | 446 | \secC{Mask images} |
---|
[1017] | 447 | \label{sec-maskOut} |
---|
| 448 | |
---|
| 449 | It is also possible to write the mask array to a FITS file, for use in |
---|
| 450 | other forms of post-processing. This array is designed to indicate the |
---|
| 451 | location of detected objects. The value of the detected pixels is |
---|
| 452 | determined by the input parameter \texttt{flagMaskWithObjectNum}: if |
---|
| 453 | \texttt{true}, the value of the pixels is given by the corresponding |
---|
| 454 | object ID number; if \texttt{false}, they take the value 1 for all |
---|
| 455 | objects. Pixels not in a detected object have the value 0. To create |
---|
| 456 | this FITS file, set the input parameter |
---|
| 457 | \texttt{flagOutputMask=true}. The file will be named according to the |
---|
| 458 | \texttt{fileOutputMask} parameter, or, if this is not given, |
---|
| 459 | \texttt{image.MASK.fits} (where the input image is called |
---|
| 460 | \texttt{image.fits}). |
---|
| 461 | |
---|
[1142] | 462 | A spatial mask, or moment-0 mask, can also be written. This is simply |
---|
| 463 | a two-dimensional image that shows which spatial pixels are detected |
---|
| 464 | in one or more channels. Unlike the full mask file above, detected |
---|
| 465 | pixels can only be recorded as 1 (as a given spatial pixel may appear |
---|
| 466 | in multiple objects) -- that is, the parameter |
---|
| 467 | \texttt{flagMaskWithObjectNum} does not affect the moment-0 mask. To |
---|
| 468 | create this FITS file, set the input parameter |
---|
| 469 | \texttt{flagOutputMomentMask=true}. The file will be named according |
---|
| 470 | to the \texttt{fileOutputMomentMask} parameter, or, if this is not |
---|
| 471 | given, \texttt{image.MOM0MASK.fits} (where the input image is called |
---|
| 472 | \texttt{image.fits}). |
---|
| 473 | |
---|
[1028] | 474 | \secC{Smoothed or Reconstructed image} |
---|
| 475 | \label{sec-reconOut} |
---|
[1017] | 476 | |
---|
[1028] | 477 | As discussed in \S\ref{sec-reconIO}, the reconstructed array, its |
---|
| 478 | residual, or the smoothed array can be saved to a FITS file. This |
---|
| 479 | allows examination of them offline, as well as their re-use by |
---|
| 480 | \duchamp to save the expense of re-calculating. This behaviour is |
---|
| 481 | controlled by \texttt{flagOutputRecon}, \texttt{flagOutputResid} and |
---|
| 482 | \texttt{flagOutputSmooth}. Consult \S\ref{sec-reconIO} for further |
---|
| 483 | details. |
---|
| 484 | |
---|
[1162] | 485 | \secC{Baseline image} |
---|
| 486 | \label{sec-baselineOut} |
---|
| 487 | |
---|
| 488 | As mentioned in \S\ref{sec-baseline}, the spectral baseline values can |
---|
| 489 | be saved to a FITS file, allowing examination of them offline. There |
---|
| 490 | is no scope at present for reloading previously-calculated baselines |
---|
| 491 | (although the overheads in calculating these are not too |
---|
| 492 | prohibitive). Saving to a FITS file is controlled by the input |
---|
| 493 | parameters \texttt{flagOutputBaseline} and |
---|
| 494 | \texttt{fileOutputBaseline}. If \texttt{fileOutputBaseline} is not |
---|
| 495 | provided, the file will be named \texttt{image.BASE.fits} (for an |
---|
| 496 | input image called \texttt{image.fits}). |
---|
| 497 | |
---|
| 498 | |
---|
| 499 | |
---|
[1159] | 500 | \secB{Re-examining previous \duchamp results} |
---|
[482] | 501 | \label{sec-reuse} |
---|
| 502 | |
---|
| 503 | |
---|
[1159] | 504 | \secC{Binary Catalogue} |
---|
[1178] | 505 | \label{sec-bincat} |
---|
[482] | 506 | |
---|
[1159] | 507 | It is often the case that the bulk of the work in a \duchamp run is in |
---|
| 508 | the searching for sources. If you are interested in re-doing some of |
---|
| 509 | the spectral plots, or re-parameterising with different |
---|
| 510 | \texttt{spectralType} settings, then having to re-run the searching |
---|
| 511 | can be a bit off-putting. |
---|
[964] | 512 | |
---|
[1159] | 513 | A solution to this problem exists in the ability to save a binary |
---|
| 514 | catalogue, containing the information on the individual pixels |
---|
| 515 | detected in each object. This is sufficient to recreate a set of |
---|
| 516 | detections and re-do the parameterisation. To enable this mode, set |
---|
| 517 | \texttt{flagWriteBinaryCatalogue=true}, and provide a filename with |
---|
| 518 | \texttt{binaryCatalogue} (or use the default of |
---|
| 519 | \texttt{duchamp-Catalogue.dpc}). The following will be written to the |
---|
| 520 | catalogue: |
---|
| 521 | \begin{itemize} |
---|
| 522 | \item Version of \duchamp. If it is not the same version, a warning is raised. |
---|
| 523 | \item Current date and time. |
---|
| 524 | \item The parameter set. Only the parameters affecting the |
---|
| 525 | pre-processing and searching are stored. Those related to, say, |
---|
| 526 | graphical output are not. |
---|
| 527 | \item The measured statistics. |
---|
| 528 | \item The pixels of each detected object, written using the run-length |
---|
| 529 | encoding described in \S\ref{sec-scan}. |
---|
| 530 | \end{itemize} |
---|
| 531 | These are written in binary format to conserve disk space, and are |
---|
| 532 | sufficient to recreate the state of \duchamp after the searching has |
---|
| 533 | taken place. |
---|
[964] | 534 | |
---|
[1159] | 535 | To re-use this catalogue, set the flag \texttt{usePrevious=true} and |
---|
| 536 | provide the binary catalogue filename via |
---|
| 537 | \texttt{binaryCatalogue}. The catalogue will be loaded, and (provided |
---|
| 538 | it loads correctly) the preprocessing and searching steps will be |
---|
| 539 | skipped. The post-processing (\ie plotting and catalogue output) steps |
---|
| 540 | will occur as normal, using the settings provided in the input |
---|
| 541 | parameter file. |
---|
| 542 | |
---|
| 543 | Note that while at this stage this is the only use for the binary |
---|
| 544 | catalogues, it is anticipated that other functionality will be |
---|
| 545 | provided in future - for instance, to allow conversion into mask |
---|
| 546 | images. The binary catalogues are seen as a compact way of storing the |
---|
| 547 | results of a \duchamp run. |
---|
| 548 | |
---|
| 549 | \secC{Selection of objects} |
---|
| 550 | |
---|
| 551 | When re-running \duchamp on a previously-generated catalogue, it is |
---|
| 552 | possible to produce the plots for only a selection of objects. Use the |
---|
| 553 | \texttt{objectList} parameter to specify a set of objects, listing |
---|
| 554 | individual object numbers or ranges, for example ``1,3-6,9,11'' means |
---|
| 555 | objects 1,3,4,5,6,9,11. The output plots will be appropriately |
---|
| 556 | modified: the spectral plots will only show these objects; the moment |
---|
| 557 | map plot will only show the contribution from these objects; the |
---|
| 558 | detection map will show the outlines of only these objects, although |
---|
| 559 | all detected pixels are still shown in greyscale. |
---|
| 560 | |
---|
| 561 | Note that the object numbers here are valid for the catalogue as |
---|
| 562 | sorted according to the \texttt{sortingParam} specification in the |
---|
| 563 | parameter file. If you change this, the order of the catalogue may |
---|
| 564 | change and the specific objects selected by \texttt{objectList} will |
---|
| 565 | differ. |
---|
| 566 | |
---|
| 567 | This option is designed for the case of re-using a catalogue, but can |
---|
| 568 | be used for a blind search as well. Of course, you may not know what |
---|
| 569 | numbers the sources will turn out to be. |
---|
| 570 | |
---|
[964] | 571 | %%% Local Variables: |
---|
| 572 | %%% mode: latex |
---|
| 573 | %%% TeX-master: "Guide" |
---|
| 574 | %%% End: |
---|