[1159] | 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{Source Parameterisation} |
---|
| 30 | \label{sec-sourceparam} |
---|
| 31 | |
---|
| 32 | Once sources have been located, numerous measurements are made so that |
---|
| 33 | they can be placed in a catalogue. This section details each of the |
---|
| 34 | source parameters, explaining what they are and how they are |
---|
| 35 | calculated. Each parameter is referred to by the heading of the |
---|
| 36 | relevant column(s) in the output source list (see |
---|
| 37 | \S\ref{sec-output}). |
---|
| 38 | |
---|
| 39 | \secB{Object ID, \texttt{Obj\#}} |
---|
| 40 | \label{sec-objectID} |
---|
| 41 | |
---|
| 42 | The ID of the detection is an integer, simply the sequential count for the |
---|
| 43 | list. The default is ordering by increasing spectral coordinate, or channel |
---|
| 44 | number, if the WCS is not good enough to determine the spectral world |
---|
| 45 | coordinate, but this can be changed by the \texttt{sortingParam} input |
---|
| 46 | parameter. See Sec~\ref{sec-results} for details. |
---|
| 47 | |
---|
| 48 | \secB{Object Name, \texttt{Name}} |
---|
| 49 | |
---|
| 50 | This is the ``IAU''-format name of the detection, derived from the WCS |
---|
| 51 | position if available. For instance, a source that is centred on the |
---|
| 52 | RA,Dec position 12$^h$53$^m$45$^s$, -36$^\circ$24$'$12$''$ will be |
---|
| 53 | given the name J125345$-$362412, if the epoch is J2000, or the name |
---|
| 54 | B125345$-$362412 if it is B1950. The precision of the RA and Dec |
---|
| 55 | values is determined by the pixel size, such that sufficient precision |
---|
| 56 | is used to uniquely define a position. The RA value will have one |
---|
| 57 | figure greater precision than Dec. |
---|
| 58 | |
---|
| 59 | An alternative form is used for Galactic coordinates: a source centred |
---|
| 60 | on the position ($l$,$b$) = (323.1245, 5.4567) will be called |
---|
| 61 | G323.124$+$05.457. |
---|
| 62 | |
---|
| 63 | If the WCS is not valid (\ie is not present or does not have all the |
---|
| 64 | necessary information), the name will instead be of the form |
---|
| 65 | ``ObjXXX'', where XXX is replaced with the objectID, padded |
---|
| 66 | sufficiently with zeros. |
---|
| 67 | |
---|
| 68 | \secB{Pixel locations} |
---|
| 69 | |
---|
| 70 | There are three ways in which the pixel location of the detection is |
---|
| 71 | calculated: |
---|
| 72 | \begin{itemize} |
---|
| 73 | \item Peak: the pixel value in which the detection has its peak |
---|
| 74 | flux. Appears in the results file under columns \texttt{X\_peak, |
---|
| 75 | Y\_peak, Z\_peak}. |
---|
| 76 | \item Average: the average over all detected pixels. Specifically, |
---|
| 77 | $x_\text{av}=\sum x_i / N$ and similarly for $y_\text{av}$ and |
---|
| 78 | $z_\text{av}$. Appears in the results file under columns \texttt{X\_av, |
---|
| 79 | Y\_av, Z\_av}. |
---|
| 80 | \item Centroid: the flux-weighted average over all detected pixels. Specifically, |
---|
| 81 | $x_\text{cent}=\sum F_i x_i / \sum F_i$ and similarly for $y_\text{cent}$ and |
---|
| 82 | $z_\text{cent}$. Appears in the results file under columns \texttt{X\_cent, |
---|
| 83 | Y\_cent, Z\_cent}. |
---|
| 84 | \end{itemize} |
---|
| 85 | |
---|
| 86 | All three alternatives are calculated, and written to the results |
---|
| 87 | file, but the choice of the \texttt{pixelCentre} input parameter will |
---|
| 88 | determine which option is used for the reference values \texttt{X, Y, |
---|
| 89 | Z}. |
---|
| 90 | |
---|
| 91 | \secB{Spatial world location, \texttt{RA/GLON, DEC/GLAT}} |
---|
| 92 | |
---|
| 93 | These are the conversion of the \texttt{X} and \texttt{Y} pixel |
---|
| 94 | positions to world coordinates (that is, the pixel position determined |
---|
| 95 | by \texttt{pixelCentre}). These will typically be Right Ascension and |
---|
| 96 | Declination, or Galactic Longitude and Galactic Latitude, but the |
---|
| 97 | actual names used in the output file will be taken from the WCS |
---|
| 98 | specification. |
---|
| 99 | |
---|
| 100 | If there is no useful WCS, these are not calculated. |
---|
| 101 | |
---|
| 102 | \secB{Spectral world location, \texttt{VEL}} |
---|
| 103 | \label{sec-vel} |
---|
| 104 | |
---|
| 105 | The conversion of the \texttt{Z} pixel position to the spectral world |
---|
| 106 | coordinates. This is dictated by the WCS of the FITS file plus the |
---|
| 107 | input parameter \texttt{spectralType}. The name of the output column |
---|
| 108 | will come from the CTYPE of the spectral axis (or |
---|
| 109 | \texttt{spectralType} -- see \S\ref{sec-wcs}), specifically , the |
---|
| 110 | 4-character S-type code) (\ie not necessarily ``VEL'') |
---|
| 111 | |
---|
| 112 | The spectral units can be specified by the user, using the input |
---|
| 113 | parameter \texttt{spectralUnits} (enter it as a single string with no |
---|
| 114 | spaces). The default value comes from the FITS header. |
---|
| 115 | |
---|
| 116 | \secB{Spatial size, \texttt{MAJ, MIN, PA}} |
---|
| 117 | \label{sec-shape} |
---|
| 118 | |
---|
| 119 | The spatial size of the detection is measured from the moment-0 map |
---|
| 120 | (in the case of three-dimensional data) or the two-dimensional image, |
---|
| 121 | and is parameterised by the FWHM of the major and minor axes, plus the |
---|
| 122 | position angle of the major axis. |
---|
| 123 | |
---|
| 124 | The method for doing this is is to form the moment-0 map (if |
---|
| 125 | necessary), select all pixels greater than half the maximum, then |
---|
| 126 | calculate the parameters $a$ (major FWHM), $b$ (minor FWHM) and |
---|
| 127 | $\theta$ (position angle) according to |
---|
| 128 | \begin{eqnarray*} |
---|
| 129 | \frac{1}{2} a^2 &= & S_{xx} + S_{yy} + \sqrt{ (S_{xx} - |
---|
| 130 | S_{yy})^2 + 4 (S_{xy})^2}\\ |
---|
| 131 | \frac{1}{2} b^2 &= & S_{xx} + S_{yy} - \sqrt{ (S_{xx} - |
---|
| 132 | S_{yy})^2 + 4 (S_{xy})^2}\\ |
---|
| 133 | \tan 2\theta &= &\frac{2 S_{xy}}{S_{xx} - S_{yy}} |
---|
| 134 | \end{eqnarray*} |
---|
| 135 | where the sums $S_{xx}$, $S_{yy}$ and $S_{xy}$ are calculated in one |
---|
| 136 | of two ways. First, the algorithm tries to weight each pixel by its |
---|
| 137 | flux: |
---|
| 138 | \begin{eqnarray*} |
---|
| 139 | S_{xx} &= &\sum F_i x_i^2 / \sum F_i\\ |
---|
| 140 | S_{yy} &= &\sum F_i y_i^2 / \sum F_i\\ |
---|
| 141 | S_{xy} &= &\sum F_i x_i y_i / \sum F_i |
---|
| 142 | \end{eqnarray*} |
---|
| 143 | Mostly, this will work. But there can be situations where the |
---|
[1178] | 144 | calculated value of $b^2$ is negative (that is, $S_{xx}+S_{yy} < |
---|
| 145 | \sqrt{(S_{xx}-S_{yy})^2+4S_{xy}^2}$, or $S_{xx}S_{yy}<S_{xy}^2$). These situations are |
---|
| 146 | often where the moment-0 map is very disordered with no clear primary |
---|
| 147 | axis. |
---|
[1159] | 148 | |
---|
| 149 | In this case, the calculation of the sums is redone without the flux |
---|
| 150 | weighting ($S_{xx} = \sum x_i^2$ etc), and the shape parameters |
---|
| 151 | recalculated. A \textbf{W} flag will be recorded for the detection to |
---|
| 152 | indicate that the weighting failed: see Sec~\ref{sec-flags} below. |
---|
| 153 | |
---|
| 154 | The position angle will be measured in the usual astronomical sense, |
---|
| 155 | in degrees East of North. The major and minor axes will be specified |
---|
| 156 | in angular units (assuming the WCS allows this), with the units chosen |
---|
| 157 | such that the numbers are not too small. |
---|
| 158 | |
---|
| 159 | The algorithm will first try to calculate $a,b,\theta$ by weighting |
---|
| 160 | |
---|
| 161 | |
---|
| 162 | \secB{Spatial extent, \texttt{w\_RA/w\_GLON, w\_DEC}} |
---|
| 163 | |
---|
| 164 | The extent of the detection in each of the spatial directions is also |
---|
| 165 | calculated. This is simply the angular width of the detection (in |
---|
| 166 | arcmin), converting the minimum and maximum values of $x$ (usually RA) |
---|
| 167 | and $y$ (Dec) to the world coordinates. |
---|
| 168 | |
---|
| 169 | \secB{Spectral width, \texttt{w\_50, w\_20, w\_VEL}} |
---|
| 170 | |
---|
| 171 | Several measures of the spectral extent of a detection are |
---|
| 172 | provided. The simplest is the full spectral width, calculated as for |
---|
| 173 | the spatial extents above. This is referred to as \texttt{w\_VEL}, but |
---|
| 174 | need not be velocity. It is obtained by taking the difference in world |
---|
| 175 | coordinates of the minimum and maximum values of $z$. The units are as |
---|
| 176 | described in \S\ref{sec-vel}. |
---|
| 177 | |
---|
| 178 | Two other measures of the spectral width are provided, \texttt{w\_50} |
---|
| 179 | and \texttt{w\_20}, being the width at 50\% and 20\% of the peak |
---|
| 180 | flux. These are measured on the integrated spectrum (\ie the spectra |
---|
| 181 | of all detected spatial pixels summed together), and are defined by |
---|
| 182 | starting at the outer spectral extent of the object (the highest and |
---|
| 183 | lowest spectral values) and moving in or out until the required flux |
---|
| 184 | threshold is reached. The widths are then just the difference between |
---|
| 185 | the two values obtained. If the detection threshold is greater than |
---|
| 186 | 20\% or 50\% of the peak, then these values will be the same as |
---|
| 187 | \texttt{w\_VEL}. |
---|
| 188 | |
---|
| 189 | \secB{Source flux, \texttt{F\_tot, F\_int, F\_peak}} |
---|
[1199] | 190 | \label{sec-fluxparams} |
---|
[1159] | 191 | |
---|
| 192 | %% THE FOLLOWING IS FROM THE MNRAS PAPER |
---|
| 193 | %The flux of the source is given by the peak flux and both the ``total |
---|
| 194 | %flux'', defined above as $F_T$, and the ``integrated flux'' $F_I$, or |
---|
| 195 | %the total flux integrated over the spectral extent and corrected for |
---|
| 196 | %the beam: |
---|
| 197 | %\[ |
---|
| 198 | %F_I = \frac{\sum F_i \Delta v_i}{B} |
---|
| 199 | %\] |
---|
| 200 | %where $B=\pi \alpha \beta / 4 \ln(2)$ is the area of a beam of major |
---|
| 201 | %and minor axes $\alpha$ and $\beta$ (in pixels), and $\Delta v_i$ is |
---|
| 202 | %the spectral width of each voxel. |
---|
| 203 | |
---|
| 204 | There are two measurements of the total flux of the detection. The |
---|
| 205 | simplest, \texttt{F\_tot}, is just the sum of all detected pixels in |
---|
| 206 | the image: $F_\text{tot}=\sum F_i$. The alternative, \texttt{F\_int}, |
---|
| 207 | is the flux integrated over the detected pixels, taking into account |
---|
| 208 | the spectral range. For the case of velocity, the expression is |
---|
| 209 | $F_\text{int} = \sum F_i \Delta v_i$, where $\Delta v_i$ is the |
---|
| 210 | velocity width of the channel containing pixel $i$. The actual units |
---|
| 211 | of the spectral range are as described in \S\ref{sec-vel}. |
---|
| 212 | |
---|
| 213 | When the cube brightness units are quoted per beam (\eg Jy/beam), then |
---|
| 214 | the integrated flux \texttt{F\_int} includes a correction for |
---|
| 215 | this. This involves dividing by the integral over the beam. This is |
---|
| 216 | calculated using the BMAJ, BMIN \& BPA header keywords from the FITS |
---|
| 217 | file. BMAJ and BMIN are assumed to be the full-width at half maximum |
---|
| 218 | (FWHM) in the major and minor axis directions of a Gaussian beam. The |
---|
| 219 | integral is calculated as follows: the functional form of a 2D |
---|
| 220 | elliptical Gaussian can be written as |
---|
| 221 | $\exp(-((x^2/2\sigma_x^2)+(y^2/2\sigma_y^2)))$, and the FWHM in a |
---|
| 222 | given direction is then $f=2\sqrt{2\ln2}\sigma$. Then, $F_\text{int} = |
---|
| 223 | C \sum F_i \Delta v_i$, where |
---|
| 224 | \[ |
---|
| 225 | C = \int\exp\left(-\left(\frac{x^2}{2\sigma_x^2}+\frac{y^2}{2\sigma_y^2}\right)\right) |
---|
| 226 | = 2\pi\sigma_x\sigma_y |
---|
| 227 | =\frac{\pi f_x f_y}{4\ln2} |
---|
| 228 | \] |
---|
| 229 | provides the correction factor to go from units of Jy/beam to Jy. |
---|
| 230 | |
---|
| 231 | If the FITS file does not have the beam information, the user can |
---|
| 232 | either: |
---|
| 233 | \begin{enumerate} |
---|
| 234 | \item Specify the FWHM of the beam in pixels (assuming a circular |
---|
| 235 | beam) via the parameter \texttt{beamFWHM}. |
---|
| 236 | \item Specify the area of the beam, again in pixels, via the parameter |
---|
| 237 | \texttt{beamArea}\footnote{Note that this is equivalent to the old |
---|
| 238 | parameter \texttt{beamSize}, which was highlighted as being |
---|
| 239 | ambiguous.}. This should be the value given by the equation above. |
---|
| 240 | \end{enumerate} |
---|
| 241 | If both are given, \texttt{beamFWHM} takes precendence. If neither are |
---|
| 242 | given, and there is no beam information in the header, then no |
---|
| 243 | correction to the integrated flux is made (and so it will stay in |
---|
| 244 | units of Jy/beam or equivalent). |
---|
| 245 | |
---|
| 246 | Note that these parameters are measured using \textit{only the |
---|
| 247 | detected pixels}. The summing of the flux will not include voxels |
---|
| 248 | that fall below the detection (or growth) threshold -- which is in |
---|
| 249 | accord with the definition of the threshold as dividing source and |
---|
| 250 | non-source voxels. If the threshold is not low enough, this will bias |
---|
| 251 | the measurement of the fluxes. This applies to all parameters (with |
---|
| 252 | the exception of the \texttt{w\_50} and \texttt{w\_20} widths, which |
---|
| 253 | are measured from the integrated spectrum, including channels not |
---|
| 254 | necessarily forming part of the detection). |
---|
| 255 | |
---|
| 256 | Finally, the peak flux \texttt{F\_peak} is simply the maximum value of |
---|
| 257 | the flux over all the detected pixels. |
---|
| 258 | |
---|
| 259 | |
---|
| 260 | \secB{Error on total/integrated flux, \texttt{eF\_tot, eF\_int}} |
---|
| 261 | |
---|
| 262 | Both \texttt{F\_tot} and \texttt{F\_int} can also have their |
---|
| 263 | associated error calculated (\texttt{eF\_tot} and \texttt{eF\_int} |
---|
| 264 | respectively). This is the random error due to the noise in the image, |
---|
| 265 | and is simply the sum in quadrature of the noise on each of the |
---|
| 266 | voxels, and, in the case of \texttt{F\_int} multiplied by the spectral |
---|
| 267 | width and corrected for the beam if necessary. Since we assume a |
---|
| 268 | constant noise level in the image ($\sigma_i=\sigma\ \forall i$), we |
---|
| 269 | have: |
---|
| 270 | \begin{eqnarray*} |
---|
| 271 | eF_\text{int} &= & \sqrt{\sum\sigma_i^2} \\&= &\sigma \sqrt{N}\\ |
---|
| 272 | eF_\text{tot} &= & \sqrt{\sum C^2\sigma_i^2 \Delta v_i^2} \\&= &C \sigma |
---|
| 273 | \sqrt{N} \Delta v \text{ (for the case of $\Delta v_i = \Delta v$)} |
---|
| 274 | \end{eqnarray*} |
---|
| 275 | In the case that a flux threshold is provided, these quantities are |
---|
| 276 | not calculated, since we don't measure the image noise |
---|
[1199] | 277 | statistics. Likewise, when the array is smoothed we measure the noise |
---|
| 278 | only in the smoothed image, and this value is not applicable to the |
---|
| 279 | flux measured from the original image, so the errors are not |
---|
| 280 | reported. |
---|
[1159] | 281 | |
---|
| 282 | |
---|
| 283 | \secB{Peak signal-to-noise, \texttt{S/Nmax}} |
---|
| 284 | |
---|
| 285 | This parameter converts the peak flux to a signal-to-noise value, |
---|
| 286 | based on the measured noise level in the image. As for the error |
---|
| 287 | quantities above, if no noise is measured (\ie a flux threshold is |
---|
| 288 | provided by the user), then this is not calculated. |
---|
| 289 | |
---|
[1199] | 290 | When the array is pre-processed (via smoothing or wavelet |
---|
| 291 | reconstruction), we take the peak flux here to be the peak in the |
---|
| 292 | smoothed or reconstructed array. This is because this is where the |
---|
| 293 | detection is made, and so the \texttt{S/Nmax} value can be directly |
---|
| 294 | compared to the requested signal-to-noise threshold. Note that the |
---|
| 295 | peak flux discussed in \S\ref{sec-fluxparams} is always measured from |
---|
| 296 | the original image array. |
---|
| 297 | |
---|
[1159] | 298 | \secB{Pixel ranges, \texttt{X1, X2, Y1, Y2, Z1, Z2}} |
---|
| 299 | |
---|
| 300 | These quantities give the range of pixel values spanned by the |
---|
| 301 | detection in each of the three axes. \texttt{X1, Y1, Z1} give the |
---|
| 302 | minimum pixel in each direction, while \texttt{X2, Y2, Z2} give the |
---|
| 303 | maximum pixel. |
---|
| 304 | |
---|
| 305 | \secB{Size, \texttt{Npix}} |
---|
| 306 | |
---|
| 307 | The number of detected pixels that make up the detection |
---|
| 308 | |
---|
| 309 | \secB{Warning Flags, \texttt{Flag}} |
---|
| 310 | \label{sec-flags} |
---|
| 311 | |
---|
| 312 | The detection can have warning flags recorded, to highlight potential |
---|
| 313 | issues: |
---|
| 314 | \begin{itemize} |
---|
| 315 | \item \textbf{E} -- The detection is next to the spatial edge of the |
---|
| 316 | image, meaning either the limit of the pixels, or the limit of the |
---|
| 317 | non-BLANK pixel region. |
---|
| 318 | \item \textbf{S} -- The detection lies at the edge of the spectral |
---|
| 319 | region. |
---|
| 320 | \item \textbf{M} -- The detection is adjacent to, or overlaps the |
---|
| 321 | ``Milky Way'' range of channels (see \S\ref{sec-MW}). |
---|
| 322 | \item \textbf{N} -- The total flux, summed over all the (non-BLANK) |
---|
| 323 | pixels in the smallest box that completely encloses the detection, |
---|
| 324 | is negative. Note that this sum is likely to include non-detected |
---|
| 325 | pixels. It is of use in pointing out detections that lie next to |
---|
| 326 | strongly negative pixels, such as might arise due to interference -- |
---|
| 327 | the detected pixels might then also be due to the interference, so |
---|
| 328 | caution is advised. |
---|
| 329 | \item \textbf{W} -- The weighting of fluxes in the shape calculation |
---|
| 330 | (Sec~\ref{sec-shape}) failed, so the unweighted calculation was |
---|
| 331 | used. This likely indicates some very disordered shape for the |
---|
| 332 | moment-0 map. |
---|
| 333 | \end{itemize} |
---|
| 334 | In the absence of any of these flags, a \textbf{-} will be recorded. |
---|
| 335 | |
---|
| 336 | |
---|
| 337 | %%% Local Variables: |
---|
| 338 | %%% mode: latex |
---|
| 339 | %%% TeX-master: "Guide" |
---|
| 340 | %%% End: |
---|