[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} |
---|
| 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 |
---|
| 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 |
---|
[298] | 46 | (when \texttt{reconDim = 3}), or a progress bar showing the amount of |
---|
[158] | 47 | the cube that has been reconstructed (for smaller values of |
---|
| 48 | \texttt{reconDim}). |
---|
| 49 | |
---|
[298] | 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). |
---|
[158] | 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 |
---|
[265] | 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. |
---|
[158] | 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 |
---|
[298] | 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 |
---|
[158] | 73 | the progress are not shown. |
---|
| 74 | |
---|
[162] | 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 | |
---|
[285] | 84 | \secB{Text-based output files} |
---|
[158] | 85 | |
---|
| 86 | \secC{Table of results} |
---|
[285] | 87 | \label{sec-results} |
---|
[158] | 88 | |
---|
[258] | 89 | Finally, we get to the results -- the reason for running \duchamp in |
---|
[571] | 90 | the first place. Once the detection list is finalised, it is sorted |
---|
| 91 | according to the value of the \texttt{sortingParam}. This can take the |
---|
| 92 | value ``x-value'', ``y-value'', ``z-value'', ``ra'', ``dec'', ``vel'', |
---|
| 93 | ``w50'', ``iflux'' (for integrated flux), or ``pflux'' (for peak |
---|
[572] | 94 | flux), or ``snr''. The default value is ``vel''. If no good WCS |
---|
[571] | 95 | exists, the mean pixel position equivalent is used (``ra'' is replaced |
---|
| 96 | by ``x-value'', ``dec'' by ``y-value'', ``vel'' and ``w50'' by |
---|
| 97 | ``z-value''). The results are then printed to the screen and to the |
---|
| 98 | output file, given by the \texttt{OutFile} parameter. |
---|
[158] | 99 | |
---|
[364] | 100 | The output consists of two sections. First, a list of the parameters |
---|
[194] | 101 | are printed to the output file, for future reference. Next, the |
---|
[285] | 102 | detection threshold that was used is given, so comparison can be made |
---|
[386] | 103 | with other searches. The statistics estimating the noise parameters |
---|
| 104 | are given (see \S\ref{sec-stats}). Thirdly, the number of detections |
---|
| 105 | are reported. |
---|
[194] | 106 | |
---|
[364] | 107 | All this information, known as the ``header'', can either be written |
---|
| 108 | to the start of the output file (denoted by the parameter |
---|
| 109 | \texttt{OutFile}), or written to a separate file from the list of |
---|
| 110 | detections. This second option is activated by the parameter |
---|
| 111 | \texttt{flagSeparateHeader}, and the information is written to the |
---|
| 112 | file given by \texttt{HeaderFile}. |
---|
| 113 | |
---|
[194] | 114 | The most interesting part, however, is the list of detected |
---|
| 115 | objects. This list, an example of which can be seen in |
---|
| 116 | Appendix~\ref{app-output}, contains the following columns (note that |
---|
| 117 | the title of the columns depending on WCS information will depend on |
---|
| 118 | the details of the WCS projection: they are shown below for the |
---|
| 119 | Equatorial and Galactic projection cases). |
---|
| 120 | |
---|
[306] | 121 | \begin{Lentry} |
---|
| 122 | \item[{Obj\#}] The ID number of the detection (simply the |
---|
[303] | 123 | sequential count for the list, which is ordered by increasing |
---|
| 124 | velocity, or channel number, if the WCS is not good enough to find |
---|
| 125 | the velocity). |
---|
[306] | 126 | \item[{Name}] The ``IAU''-format name of the detection (derived from the |
---|
[158] | 127 | WCS position -- see below for a description of the format). |
---|
[306] | 128 | \item[{X,Y,Z}] The ``centre'' pixel position, determined by the input |
---|
[285] | 129 | parameter \texttt{pixelCentre}. |
---|
[306] | 130 | \item[{RA/GLON}] The Right Ascension or Galactic Longitude of the centre |
---|
[285] | 131 | of the object. |
---|
[306] | 132 | \item[{DEC/GLAT}] The Declination or Galactic Latitude of the centre of |
---|
[285] | 133 | the object. |
---|
[306] | 134 | \item[{VEL}] The mean velocity of the object [units given by the |
---|
[158] | 135 | \texttt{spectralUnits} parameter]. |
---|
[306] | 136 | \item[{w\_RA/w\_GLON}] The width of the object in Right Ascension or |
---|
[285] | 137 | Galactic Longitude (depending on FITS coordinates) [arcmin]. |
---|
[306] | 138 | \item[{w\_DEC/w\_GLAT}] The width of the object in Declination Galactic |
---|
[158] | 139 | Latitude [arcmin]. |
---|
[471] | 140 | \item[{w\_50}] The velocity width of the detection at 50\% of the peak |
---|
| 141 | flux (the measured full-width at half-maximum, FWHM), in velocity |
---|
| 142 | units [see note below]. |
---|
[306] | 143 | \item[{F\_int}] The integrated flux over the object, in the units of |
---|
[675] | 144 | flux times velocity, corrected for the beam if necessary. See below |
---|
| 145 | for a discussion on this correction. |
---|
[306] | 146 | \item[{F\_peak}] The peak flux over the object, in the units of flux. |
---|
| 147 | \item[{S/Nmax}] The signal-to-noise ratio at the peak pixel. |
---|
| 148 | \item[{X1, X2}] The minimum and maximum X-pixel coordinates. |
---|
| 149 | \item[{Y1, Y2}] The minimum and maximum Y-pixel coordinates. |
---|
| 150 | \item[{Z1, Z2}] The minimum and maximum Z-pixel coordinates. |
---|
| 151 | \item[{Npix}] The number of voxels (\ie distinct $(x,y,z)$ coordinates) |
---|
[158] | 152 | in the detection. |
---|
[306] | 153 | \item[{Flag}] Whether the detection has any warning flags (see below). |
---|
| 154 | \end{Lentry} |
---|
[162] | 155 | |
---|
[471] | 156 | These parameters are written to the screen during execution. There are |
---|
| 157 | alternative ways of calculating the total flux, the position and |
---|
| 158 | velocity width, however, and so additional parameters are written to |
---|
| 159 | the output file: |
---|
[306] | 160 | \begin{Lentry} |
---|
[471] | 161 | \item[{w\_20}] The velocity width of the detection at 20\% of the peak |
---|
| 162 | flux, in velocity units [see note below]. |
---|
| 163 | \item[{w\_VEL}] The full velocity width of the detection (max channel |
---|
| 164 | $-$ min channel, in velocity units). |
---|
| 165 | \item[{F\_tot}] The sum of the flux values of all detected voxels. |
---|
[306] | 166 | \item[{X\_av, Y\_av, Z\_av}] The average pixel value in each |
---|
[303] | 167 | axis direction \ie X\_av is the average of the $x$-values of all |
---|
| 168 | pixels in the detection. |
---|
[306] | 169 | \item[{X\_cent, Y\_cent, Z\_cent}] The centroid position, being |
---|
[303] | 170 | the flux-weighted average of the pixels. |
---|
[306] | 171 | \item[{X\_peak, Y\_peak, Z\_peak}] The location of the pixel |
---|
[303] | 172 | containing the peak flux value. |
---|
[306] | 173 | \end{Lentry} |
---|
[471] | 174 | The velocity width of the detection is calculated at 50\% and 20\% of |
---|
| 175 | the peak flux, as well as the full detected width (if the detection |
---|
| 176 | threshold is greater than 20\% or 50\% of the peak, then these values |
---|
| 177 | will be the same as \texttt{w\_VEL}. The type of position value given |
---|
| 178 | in the \texttt{X, Y, Z} columns in the screen output is determined by |
---|
| 179 | the \texttt{pixelCentre} parameter. All three alternatives are shown |
---|
| 180 | in the output file. |
---|
[285] | 181 | |
---|
[471] | 182 | The user can specify the precision used to display the flux, velocity |
---|
| 183 | and S/Nmax values, by using the input parameters \texttt{precFlux}, |
---|
| 184 | \texttt{precVel} and \texttt{precSNR} respectively. These values apply |
---|
| 185 | to the tables written to the screen and to the output file, as well as |
---|
| 186 | for the VOTable (see below). |
---|
| 187 | |
---|
[303] | 188 | The \texttt{Name} is derived from the WCS position. For instance, a |
---|
| 189 | source that is centred on the RA,Dec position 12$^h$53$^m$45$^s$, |
---|
[231] | 190 | -36$^\circ$24$'$12$''$ will be given the name J125345$-$362412, if the |
---|
| 191 | epoch is J2000, or the name B125345$-$362412 if it is B1950. An |
---|
| 192 | alternative form is used for Galactic coordinates: a source centred on |
---|
| 193 | the position ($l$,$b$) = (323.1245, 5.4567) will be called |
---|
| 194 | G323.124$+$05.457. If the WCS is not valid (\ie is not present or does |
---|
[303] | 195 | not have all the necessary information), the \texttt{Name, RA, DEC, |
---|
| 196 | VEL} and related columns are not printed, but the pixel coordinates |
---|
| 197 | are still provided. |
---|
[158] | 198 | |
---|
| 199 | The velocity units can be specified by the user, using the parameter |
---|
[298] | 200 | \texttt{spectralUnits} (enter it as a single string with no |
---|
| 201 | spaces). The default value is km/s, which should be suitable for most |
---|
| 202 | users. These units are also used to give the units of integrated |
---|
| 203 | flux. Note that if there is no rest frequency specified in the FITS |
---|
| 204 | header, the \duchamp output will instead default to using Frequency, |
---|
| 205 | with units of MHz. |
---|
[158] | 206 | |
---|
[675] | 207 | When the cube brightness units are quoted per beam (\eg Jy/beam), then |
---|
| 208 | the integrated flux \texttt{F\_int} includes a correction for |
---|
| 209 | this. This involves dividing by the integral over the beam. This is |
---|
| 210 | calculated using the BMAJ, BMIN \& BPA header keywords from the FITS |
---|
| 211 | file. BMAJ and BMIN are assumed to be the full-width at half maximum |
---|
| 212 | (FWHM) in the major and minor axis directions of a Gaussian beam. The |
---|
| 213 | integral is calculated as follows: the functional form of a 2D |
---|
| 214 | elliptical Gaussian can be written as |
---|
| 215 | $\exp(-((x^2/2\sigma_x^2)+(y^2/2\sigma_y^2)))$, and the FWHM in a |
---|
| 216 | given direction is then $f=2\sqrt{2\ln2}\sigma$. Then, |
---|
| 217 | \[ |
---|
| 218 | \int |
---|
| 219 | \exp\left(-\left(\frac{x^2}{2\sigma_x^2}\right)+\left(\frac{y^2}{2\sigma_y^2}\right)\right) |
---|
| 220 | = 2\pi\sigma_x\sigma_y |
---|
| 221 | =\frac{\pi f_x f_y}{4\ln2} |
---|
| 222 | \] |
---|
| 223 | provides the correction factor to go from units of Jy/beam to Jy. |
---|
| 224 | |
---|
| 225 | If the FITS file does not have the beam information, the user can |
---|
| 226 | either: |
---|
| 227 | \begin{enumerate} |
---|
| 228 | \item Specify the FWHM of the beam in pixels (assuming a circular |
---|
| 229 | beam) via the parameter \texttt{beamFWHM}. |
---|
| 230 | \item Specify the area of the beam, again in pixels, via the parameter |
---|
| 231 | \texttt{beamArea}\footnote{Note that this is equivalent to the old |
---|
| 232 | parameter \texttt{beamSize}, which was highlighted as being |
---|
| 233 | ambiguous.}. This should be the value given by the equation above. |
---|
| 234 | \end{enumerate} |
---|
| 235 | If \texttt{beamFWHM}, is given, that will be used for the calculation, |
---|
| 236 | otherwise \texttt{beamArea} (which defaults to 10 pixels) is used. |
---|
| 237 | |
---|
[194] | 238 | If the WCS is absent or not sufficiently specified, then all columns |
---|
[303] | 239 | from \texttt{RA/GLON} to \texttt{w\_VEL} will be left blank. Also, |
---|
| 240 | \texttt{F\_int} will be replaced with the more simple \texttt{F\_tot}. |
---|
[158] | 241 | |
---|
[303] | 242 | The \texttt{Flag} column contains any warning flags, such as: |
---|
[195] | 243 | \begin{itemize} |
---|
| 244 | \item \textbf{E} -- The detection is next to the spatial edge of the image, |
---|
| 245 | meaning either the limit of the pixels, or the limit of the non-BLANK |
---|
| 246 | pixel region. |
---|
| 247 | \item \textbf{S} -- The detection lies at the edge of the spectral region. |
---|
| 248 | \item \textbf{N} -- The total flux, summed over all the (non-BLANK) |
---|
| 249 | pixels in the smallest box that completely encloses the detection, is |
---|
| 250 | negative. Note that this sum is likely to include non-detected |
---|
| 251 | pixels. It is of use in pointing out detections that lie next to |
---|
| 252 | strongly negative pixels, such as might arise due to interference -- |
---|
| 253 | the detected pixels might then also be due to the interference, so |
---|
| 254 | caution is advised. |
---|
| 255 | \end{itemize} |
---|
[520] | 256 | In the absence of any of these flags, a \textbf{-} will be recorded in |
---|
| 257 | this column. |
---|
[194] | 258 | |
---|
[158] | 259 | \secC{Other results lists} |
---|
| 260 | |
---|
[425] | 261 | Three additional results files can also be requested. One option is a |
---|
[158] | 262 | VOTable-format XML file, containing just the RA, Dec, Velocity and the |
---|
| 263 | corresponding widths of the detections, as well as the fluxes. The |
---|
[298] | 264 | user should set \texttt{flagVOT = true}, and put the desired filename |
---|
| 265 | in the parameter \texttt{votFile} -- note that the default is for it |
---|
| 266 | not to be produced. This file should be compatible with all Virtual |
---|
[285] | 267 | Observatory tools (such as Aladin% |
---|
| 268 | \footnote{%Aladin can be found on the web at |
---|
| 269 | \href{http://aladin.u-strasbg.fr/}{http://aladin.u-strasbg.fr/}} |
---|
| 270 | or TOPCAT\footnote{%Tool for OPerations on Catalogues And Tables: |
---|
| 271 | \href{http://www.star.bristol.ac.uk/~mbt/topcat/}% |
---|
[425] | 272 | {http://www.star.bristol.ac.uk/~mbt/topcat/}}). |
---|
[158] | 273 | |
---|
[425] | 274 | A second option is an annotation file for use with the Karma toolkit |
---|
[447] | 275 | of visualisation tools (in particular, with \texttt{kvis}). There are |
---|
| 276 | two options on how objects are represented, governed by the |
---|
| 277 | \texttt{annotationType} parameter. Setting this to \texttt{borders} |
---|
| 278 | results in a border being drawn around the spatial pixels of the |
---|
| 279 | object, in a manner similar to that seen in Fig.~\ref{fig-spect}. Note |
---|
| 280 | that Karma/\texttt{kvis} does not always do this perfectly, so the |
---|
| 281 | lines may not be directly lined up with pixel borders. The other |
---|
| 282 | option is \texttt{annotationType = circles}. This will draw a circle |
---|
| 283 | at the position of each detection, scaled by the spatial size of the |
---|
| 284 | detection, and number it according to the Obj\# given above. To make |
---|
| 285 | use of this option, the user should set \texttt{flagKarma = true}, and |
---|
| 286 | put the desired filename in the parameter \texttt{karmaFile} -- again, |
---|
| 287 | the default is for it not to be produced. |
---|
[425] | 288 | |
---|
| 289 | The final optional results file produced is a simple text file that |
---|
| 290 | contains the spectra for each detected object. The format of the file |
---|
| 291 | is as follows: the first column has the spectral coordinate, over the |
---|
| 292 | full range of values; the remaining columns represent the flux values |
---|
| 293 | for each object at the corresponding spectral position. The flux value |
---|
| 294 | used is the same as that plotted in the spectral plot detailed below, |
---|
| 295 | and governed by the \texttt{spectralMethod} parameter. An example of |
---|
| 296 | what a spectral text file might look like is given below: |
---|
| 297 | |
---|
| 298 | \begin{quote} |
---|
| 299 | {\footnotesize |
---|
| 300 | \begin{tabular}{lllll} |
---|
| 301 | 1405.00219727 &0.01323344 &0.23648241 &0.04202826 &-0.00506790 \\ |
---|
| 302 | 1405.06469727 &0.01302835 &0.27393046 &0.04686056 &-0.00471084 \\ |
---|
| 303 | 1405.12719727 &0.01583361 &0.27760920 &0.04114933 &-0.01168737 \\ |
---|
| 304 | 1405.18969727 &0.01271889 &0.31489247 &0.03307962 &-0.00300790 \\ |
---|
| 305 | 1405.25219727 &0.01597644 &0.30401203 &0.05356426 &-0.00551653 \\ |
---|
| 306 | 1405.31469727 &0.00773827 &0.30031312 &0.04074831 &-0.00570147 \\ |
---|
| 307 | 1405.37719727 &0.00738304 &0.27921870 &0.05272378 &-0.00504959 \\ |
---|
| 308 | 1405.43969727 &0.01353923 &0.26132512 &0.03667958 &-0.00151006 \\ |
---|
| 309 | 1405.50219727 &0.01119724 &0.28987029 &0.03497849 &-0.00645589 \\ |
---|
| 310 | 1405.56469727 &0.00813379 &0.29839963 &0.04711142 &0.00536576 \\ |
---|
| 311 | 1405.62719727 &0.00774377 &0.26530230 &0.04620502 &0.00724631 \\ |
---|
| 312 | 1405.68969727 &0.00576067 &0.23215000 &0.04995513 &0.00290841 \\ |
---|
| 313 | 1405.75219727 &0.00452834 &0.16484940 &0.04261605 &-0.00612812 \\ |
---|
| 314 | 1405.81469727 &0.01406293 &0.15989439 &0.03817926 &-0.00758385 \\ |
---|
| 315 | 1405.87719727 &0.01116611 &0.11890682 &0.05499069 &-0.00626362 \\ |
---|
| 316 | 1405.93969727 &0.00687582 &0.10620256 &0.04743370 &0.00055177 \\ |
---|
| 317 | $\vdots$ &$\vdots$ &$\vdots$ &$\vdots$ &$\vdots$ \\ |
---|
| 318 | \end{tabular} |
---|
| 319 | } |
---|
| 320 | \end{quote} |
---|
| 321 | |
---|
| 322 | In addition to these three files, a log file can also be produced. As |
---|
| 323 | the program is running, it also (optionally) records the detections |
---|
[158] | 324 | made in each individual spectrum or channel (see \S\ref{sec-detection} |
---|
| 325 | for details on this process). This is recorded in the file given by |
---|
| 326 | the parameter \texttt{LogFile}. This file does not include the columns |
---|
| 327 | \texttt{Name, RA, DEC, w\_RA, w\_DEC, VEL, w\_VEL}. This file is |
---|
| 328 | designed primarily for diagnostic purposes: \eg to see if a given set |
---|
| 329 | of pixels is detected in, say, one channel image, but does not survive |
---|
| 330 | the merging process. The list of pixels (and their fluxes) in the |
---|
| 331 | final detection list are also printed to this file, again for |
---|
| 332 | diagnostic purposes. The file also records the execution time, as well |
---|
| 333 | as the command-line statement used to run \duchamp. The creation of |
---|
[280] | 334 | this log file can be prevented by setting \texttt{flagLog = false} |
---|
| 335 | (which is the default). |
---|
[158] | 336 | |
---|
[285] | 337 | \secB{Graphical output} |
---|
[380] | 338 | |
---|
[447] | 339 | \begin{figure}[t] |
---|
| 340 | \begin{center} |
---|
| 341 | \includegraphics[width=\textwidth]{example_spectrum} |
---|
| 342 | \end{center} |
---|
| 343 | \caption{\footnotesize An example of the spectral output. Note several |
---|
| 344 | of the features discussed in the text: the red lines indicating the |
---|
| 345 | reconstructed spectrum; the blue dashed lines indicating the |
---|
| 346 | spectral extent of the detection; the green hashed area indicating |
---|
| 347 | the Milky Way channels that are ignored by the searching algorithm; |
---|
| 348 | the blue border showing its spatial extent on the 0th moment map; |
---|
| 349 | and the 15~arcmin-long scale bar.} |
---|
| 350 | \label{fig-spect} |
---|
| 351 | \end{figure} |
---|
| 352 | |
---|
| 353 | \begin{figure}[!t] |
---|
| 354 | \begin{center} |
---|
| 355 | \includegraphics[width=\textwidth]{example_moment_map} |
---|
| 356 | \end{center} |
---|
| 357 | \caption{\footnotesize An example of the moment map created by |
---|
| 358 | \duchamp. The full extent of the cube is covered, and the 0th moment |
---|
| 359 | of each object is shown (integrated individually over all the |
---|
| 360 | detected channels). The purple line indicates the limit of the |
---|
| 361 | non-BLANK pixels.} |
---|
| 362 | \label{fig-moment} |
---|
| 363 | \end{figure} |
---|
| 364 | |
---|
[380] | 365 | \secC{Mask image} |
---|
| 366 | \label{sec-maskOut} |
---|
| 367 | |
---|
| 368 | It is possible to create a FITS file containing a mask array. This |
---|
[522] | 369 | array is designed to indicate the location of detected objects. The |
---|
| 370 | value of the detected pixels is determined by the |
---|
| 371 | \texttt{flagMaskWithObjectNum} parameter: if \texttt{true}, the value |
---|
| 372 | of the pixels is given by the corresponding object ID number; if |
---|
| 373 | \texttt{false}, they take the value 1 for all objects. Pixels not in a |
---|
| 374 | detected object have the value 0. To create this FITS file, set the |
---|
[525] | 375 | input parameter \texttt{flagOutputMask=true}. The file will be named |
---|
| 376 | according to the \texttt{fileOutputMask} parameter, or, if this is not |
---|
| 377 | given, \texttt{image.MASK.fits} (where the input image is called |
---|
[522] | 378 | \texttt{image.fits}). |
---|
[380] | 379 | |
---|
[285] | 380 | \secC{Spectral plots} |
---|
[158] | 381 | |
---|
[373] | 382 | As well as the output data file, a postscript file (with the filename |
---|
| 383 | given by the \texttt{spectralFile} parameter) is created that shows |
---|
| 384 | the spectrum for each detection, together with a small cutout image |
---|
| 385 | (the 0th moment) and basic information about the detection (note that |
---|
| 386 | any flags are printed after the name of the detection, in the format |
---|
| 387 | \texttt{[E]}). If the cube was reconstructed, the spectrum from the |
---|
| 388 | reconstruction is shown in red, over the top of the original |
---|
[285] | 389 | spectrum. The spectral extent of the detected object is indicated by |
---|
| 390 | two dashed blue lines, and the region covered by the ``Milky Way'' |
---|
| 391 | channels is shown by a green hashed box. An example detection can be |
---|
[447] | 392 | seen in Fig.~\ref{fig-spect}. |
---|
[285] | 393 | |
---|
[158] | 394 | The spectrum that is plotted is governed by the |
---|
[162] | 395 | \texttt{spectralMethod} parameter. It can be either \texttt{peak} (the |
---|
| 396 | default), where the spectrum is from the spatial pixel containing the |
---|
[158] | 397 | detection's peak flux; or \texttt{sum}, where the spectrum is summed |
---|
| 398 | over all spatial pixels, and then corrected for the beam size. The |
---|
| 399 | spectral extent of the detection is indicated with blue lines, and a |
---|
| 400 | zoom is shown in a separate window. |
---|
| 401 | |
---|
| 402 | The cutout image can optionally include a border around the spatial |
---|
[231] | 403 | pixels that are in the detection (turned on and off by the |
---|
| 404 | \texttt{drawBorders} parameter -- the default is \texttt{true}). It |
---|
| 405 | includes a scale bar in the bottom left corner to indicate size -- its |
---|
| 406 | length is indicated next to it (the choice of length depends on the |
---|
| 407 | size of the image). |
---|
[158] | 408 | |
---|
| 409 | There may also be one or two extra lines on the image. A yellow line |
---|
[162] | 410 | shows the limits of the cube's spatial region: when this is shown, the |
---|
| 411 | detected object will lie close to the edge, and the image box will |
---|
| 412 | extend outside the region covered by the data. A purple line, however, |
---|
| 413 | shows the dividing line between BLANK and non-BLANK pixels. The BLANK |
---|
| 414 | pixels will always be shown in black. The first type of line is always |
---|
| 415 | drawn, while the second is governed by the parameter |
---|
| 416 | \texttt{drawBlankEdges} (whose default is \texttt{true}), and |
---|
| 417 | obviously whether there are any BLANK pixel present. |
---|
[158] | 418 | |
---|
[373] | 419 | \secC{Output for 2-dimensional images} |
---|
| 420 | |
---|
| 421 | When the input image is two-dimensional, with no spectral dimension, |
---|
| 422 | this spectral plot would not make much sense. Instead, \duchamp |
---|
| 423 | creates a similar postscript file that simply includes the text |
---|
| 424 | headers as well as the 0th-moment map of the detection. As for the |
---|
| 425 | normal spectral case, this file will be written to the filename given |
---|
| 426 | by the \texttt{spectralFile} parameter. |
---|
| 427 | |
---|
[285] | 428 | \secC{Spatial maps} |
---|
[158] | 429 | |
---|
| 430 | Finally, a couple of images are optionally produced: a 0th moment map |
---|
| 431 | of the cube, combining just the detected channels in each object, |
---|
| 432 | showing the integrated flux in grey-scale; and a ``detection image'', |
---|
| 433 | a grey-scale image where the pixel values are the number of channels |
---|
| 434 | that spatial pixel is detected in. In both cases, if |
---|
| 435 | \texttt{drawBorders = true}, a border is drawn around the spatial |
---|
| 436 | extent of each detection, and if \texttt{drawBlankEdges = true}, the |
---|
| 437 | purple line dividing BLANK and non-BLANK pixels (as described above) |
---|
| 438 | is drawn. An example moment map is shown in Fig.~\ref{fig-moment}. |
---|
| 439 | The production or otherwise of these images is governed by the |
---|
| 440 | \texttt{flagMaps} parameter. |
---|
| 441 | |
---|
[285] | 442 | The moment map is also displayed in a PGPlot XWindow (with the |
---|
| 443 | \texttt{/xs} display option). This feature can be turned off by |
---|
[298] | 444 | setting \texttt{flagXOutput = false} -- this might be useful if |
---|
| 445 | running \duchamp on a terminal with no window display capability, or |
---|
| 446 | if you have set up a script to run it in a batch mode. |
---|
[195] | 447 | |
---|
[670] | 448 | The moment map can also be written to a FITS file, so that it can be |
---|
| 449 | examined more closely, and have annotation files overlaid. This works |
---|
| 450 | in the same way as for the mask image. To create the FITS file, set the |
---|
| 451 | input parameter \texttt{flagOutputMomentMap=true}. The file will be named |
---|
| 452 | according to the \texttt{fileOutputMomentMap} parameter, or, if this is not |
---|
| 453 | given, \texttt{image.MOM0.fits} (where the input image is called |
---|
| 454 | \texttt{image.fits}). |
---|
| 455 | |
---|
[158] | 456 | The purpose of these images are to provide a visual guide to where the |
---|
| 457 | detections have been made, and, particularly in the case of the moment |
---|
| 458 | map, to provide an indication of the strength of the source. In both |
---|
| 459 | cases, the detections are numbered (in the same sense as the output |
---|
| 460 | list and as the spectral plots), and the spatial borders are marked |
---|
| 461 | out as for the cutout images in the spectra file. Both these images |
---|
| 462 | are saved as postscript files (given by the parameters |
---|
| 463 | \texttt{momentMap} and \texttt{detectionMap} respectively), with the |
---|
| 464 | latter also displayed in a \textsc{pgplot} window (regardless of the |
---|
| 465 | state of \texttt{flagMaps}). |
---|
[482] | 466 | |
---|
| 467 | |
---|
| 468 | |
---|
| 469 | \secB{Re-using previous detections} |
---|
| 470 | \label{sec-reuse} |
---|
| 471 | |
---|
| 472 | It may be the case that, once you have run \duchamp with a set of |
---|
| 473 | parameters, you are unsatisfied with the output spectra -- perhaps you |
---|
| 474 | would have preferred integrated rather than peak flux to be |
---|
| 475 | plotted. However, the searching might have taken a while to run, and |
---|
| 476 | the thought of doing it again just for different plots may be a bit |
---|
| 477 | off-putting. |
---|
| 478 | |
---|
| 479 | Well, provided you have made a log file when running \duchamp (with |
---|
| 480 | the \texttt{flagLog=true} setting), it is possible to do this easily |
---|
| 481 | without having to go through the process of detecting your sources a |
---|
| 482 | second time. By using the same input file, with the additional |
---|
| 483 | parameter \texttt{usePrevious=true}, the log file that was created |
---|
| 484 | with a previous \duchamp run can be read to extract each of the |
---|
| 485 | individual detections. The output stage is then run again, with the |
---|
| 486 | parameters (in particular \texttt{pixelCentre} and |
---|
| 487 | \texttt{spectralMethod}) as given in the input file. |
---|
| 488 | |
---|
| 489 | Perhaps you would also like to extract a single source's |
---|
| 490 | spectral plot (\eg for use in a journal paper). The use-previous |
---|
| 491 | method allows you to specify particular sources to re-plot. Only these |
---|
| 492 | sources will be plotted in the \texttt{SpectraFile} file, and |
---|
| 493 | individual files will be created for each of the listed sources. Their |
---|
| 494 | filenames will follow the format of \texttt{SpectraFile}: if, |
---|
| 495 | \texttt{SpectraFile=file.ps}, source \#3 will appear in |
---|
| 496 | \texttt{file-03.ps}. To give a list of sources, use the |
---|
| 497 | \texttt{objectList} parameter, and provide a string with individual |
---|
| 498 | object numbers or object ranges: \eg 1,2,4-7,8,11. |
---|