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 |
---|
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. |
---|
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}} |
---|
190 | |
---|
191 | %% THE FOLLOWING IS FROM THE MNRAS PAPER |
---|
192 | %The flux of the source is given by the peak flux and both the ``total |
---|
193 | %flux'', defined above as $F_T$, and the ``integrated flux'' $F_I$, or |
---|
194 | %the total flux integrated over the spectral extent and corrected for |
---|
195 | %the beam: |
---|
196 | %\[ |
---|
197 | %F_I = \frac{\sum F_i \Delta v_i}{B} |
---|
198 | %\] |
---|
199 | %where $B=\pi \alpha \beta / 4 \ln(2)$ is the area of a beam of major |
---|
200 | %and minor axes $\alpha$ and $\beta$ (in pixels), and $\Delta v_i$ is |
---|
201 | %the spectral width of each voxel. |
---|
202 | |
---|
203 | There are two measurements of the total flux of the detection. The |
---|
204 | simplest, \texttt{F\_tot}, is just the sum of all detected pixels in |
---|
205 | the image: $F_\text{tot}=\sum F_i$. The alternative, \texttt{F\_int}, |
---|
206 | is the flux integrated over the detected pixels, taking into account |
---|
207 | the spectral range. For the case of velocity, the expression is |
---|
208 | $F_\text{int} = \sum F_i \Delta v_i$, where $\Delta v_i$ is the |
---|
209 | velocity width of the channel containing pixel $i$. The actual units |
---|
210 | of the spectral range are as described in \S\ref{sec-vel}. |
---|
211 | |
---|
212 | When the cube brightness units are quoted per beam (\eg Jy/beam), then |
---|
213 | the integrated flux \texttt{F\_int} includes a correction for |
---|
214 | this. This involves dividing by the integral over the beam. This is |
---|
215 | calculated using the BMAJ, BMIN \& BPA header keywords from the FITS |
---|
216 | file. BMAJ and BMIN are assumed to be the full-width at half maximum |
---|
217 | (FWHM) in the major and minor axis directions of a Gaussian beam. The |
---|
218 | integral is calculated as follows: the functional form of a 2D |
---|
219 | elliptical Gaussian can be written as |
---|
220 | $\exp(-((x^2/2\sigma_x^2)+(y^2/2\sigma_y^2)))$, and the FWHM in a |
---|
221 | given direction is then $f=2\sqrt{2\ln2}\sigma$. Then, $F_\text{int} = |
---|
222 | C \sum F_i \Delta v_i$, where |
---|
223 | \[ |
---|
224 | C = \int\exp\left(-\left(\frac{x^2}{2\sigma_x^2}+\frac{y^2}{2\sigma_y^2}\right)\right) |
---|
225 | = 2\pi\sigma_x\sigma_y |
---|
226 | =\frac{\pi f_x f_y}{4\ln2} |
---|
227 | \] |
---|
228 | provides the correction factor to go from units of Jy/beam to Jy. |
---|
229 | |
---|
230 | If the FITS file does not have the beam information, the user can |
---|
231 | either: |
---|
232 | \begin{enumerate} |
---|
233 | \item Specify the FWHM of the beam in pixels (assuming a circular |
---|
234 | beam) via the parameter \texttt{beamFWHM}. |
---|
235 | \item Specify the area of the beam, again in pixels, via the parameter |
---|
236 | \texttt{beamArea}\footnote{Note that this is equivalent to the old |
---|
237 | parameter \texttt{beamSize}, which was highlighted as being |
---|
238 | ambiguous.}. This should be the value given by the equation above. |
---|
239 | \end{enumerate} |
---|
240 | If both are given, \texttt{beamFWHM} takes precendence. If neither are |
---|
241 | given, and there is no beam information in the header, then no |
---|
242 | correction to the integrated flux is made (and so it will stay in |
---|
243 | units of Jy/beam or equivalent). |
---|
244 | |
---|
245 | Note that these parameters are measured using \textit{only the |
---|
246 | detected pixels}. The summing of the flux will not include voxels |
---|
247 | that fall below the detection (or growth) threshold -- which is in |
---|
248 | accord with the definition of the threshold as dividing source and |
---|
249 | non-source voxels. If the threshold is not low enough, this will bias |
---|
250 | the measurement of the fluxes. This applies to all parameters (with |
---|
251 | the exception of the \texttt{w\_50} and \texttt{w\_20} widths, which |
---|
252 | are measured from the integrated spectrum, including channels not |
---|
253 | necessarily forming part of the detection). |
---|
254 | |
---|
255 | Finally, the peak flux \texttt{F\_peak} is simply the maximum value of |
---|
256 | the flux over all the detected pixels. |
---|
257 | |
---|
258 | |
---|
259 | \secB{Error on total/integrated flux, \texttt{eF\_tot, eF\_int}} |
---|
260 | |
---|
261 | Both \texttt{F\_tot} and \texttt{F\_int} can also have their |
---|
262 | associated error calculated (\texttt{eF\_tot} and \texttt{eF\_int} |
---|
263 | respectively). This is the random error due to the noise in the image, |
---|
264 | and is simply the sum in quadrature of the noise on each of the |
---|
265 | voxels, and, in the case of \texttt{F\_int} multiplied by the spectral |
---|
266 | width and corrected for the beam if necessary. Since we assume a |
---|
267 | constant noise level in the image ($\sigma_i=\sigma\ \forall i$), we |
---|
268 | have: |
---|
269 | \begin{eqnarray*} |
---|
270 | eF_\text{int} &= & \sqrt{\sum\sigma_i^2} \\&= &\sigma \sqrt{N}\\ |
---|
271 | eF_\text{tot} &= & \sqrt{\sum C^2\sigma_i^2 \Delta v_i^2} \\&= &C \sigma |
---|
272 | \sqrt{N} \Delta v \text{ (for the case of $\Delta v_i = \Delta v$)} |
---|
273 | \end{eqnarray*} |
---|
274 | In the case that a flux threshold is provided, these quantities are |
---|
275 | not calculated, since we don't measure the image noise |
---|
276 | statistics. |
---|
277 | |
---|
278 | |
---|
279 | \secB{Peak signal-to-noise, \texttt{S/Nmax}} |
---|
280 | |
---|
281 | This parameter converts the peak flux to a signal-to-noise value, |
---|
282 | based on the measured noise level in the image. As for the error |
---|
283 | quantities above, if no noise is measured (\ie a flux threshold is |
---|
284 | provided by the user), then this is not calculated. |
---|
285 | |
---|
286 | \secB{Pixel ranges, \texttt{X1, X2, Y1, Y2, Z1, Z2}} |
---|
287 | |
---|
288 | These quantities give the range of pixel values spanned by the |
---|
289 | detection in each of the three axes. \texttt{X1, Y1, Z1} give the |
---|
290 | minimum pixel in each direction, while \texttt{X2, Y2, Z2} give the |
---|
291 | maximum pixel. |
---|
292 | |
---|
293 | \secB{Size, \texttt{Npix}} |
---|
294 | |
---|
295 | The number of detected pixels that make up the detection |
---|
296 | |
---|
297 | \secB{Warning Flags, \texttt{Flag}} |
---|
298 | \label{sec-flags} |
---|
299 | |
---|
300 | The detection can have warning flags recorded, to highlight potential |
---|
301 | issues: |
---|
302 | \begin{itemize} |
---|
303 | \item \textbf{E} -- The detection is next to the spatial edge of the |
---|
304 | image, meaning either the limit of the pixels, or the limit of the |
---|
305 | non-BLANK pixel region. |
---|
306 | \item \textbf{S} -- The detection lies at the edge of the spectral |
---|
307 | region. |
---|
308 | \item \textbf{M} -- The detection is adjacent to, or overlaps the |
---|
309 | ``Milky Way'' range of channels (see \S\ref{sec-MW}). |
---|
310 | \item \textbf{N} -- The total flux, summed over all the (non-BLANK) |
---|
311 | pixels in the smallest box that completely encloses the detection, |
---|
312 | is negative. Note that this sum is likely to include non-detected |
---|
313 | pixels. It is of use in pointing out detections that lie next to |
---|
314 | strongly negative pixels, such as might arise due to interference -- |
---|
315 | the detected pixels might then also be due to the interference, so |
---|
316 | caution is advised. |
---|
317 | \item \textbf{W} -- The weighting of fluxes in the shape calculation |
---|
318 | (Sec~\ref{sec-shape}) failed, so the unweighted calculation was |
---|
319 | used. This likely indicates some very disordered shape for the |
---|
320 | moment-0 map. |
---|
321 | \end{itemize} |
---|
322 | In the absence of any of these flags, a \textbf{-} will be recorded. |
---|
323 | |
---|
324 | |
---|
325 | %%% Local Variables: |
---|
326 | %%% mode: latex |
---|
327 | %%% TeX-master: "Guide" |
---|
328 | %%% End: |
---|