1 | \secA{Introduction and getting going quickly} |
---|
2 | |
---|
3 | This document provides a user's guide to \duchamp, an object-finder |
---|
4 | for use on spectral-line data cubes. The basic execution of \duchamp |
---|
5 | is to read in a FITS data cube, find sources in the cube, and produce |
---|
6 | a text file of positions, velocities and fluxes of the detections, as |
---|
7 | well as a postscript file of the spectra of each detection. |
---|
8 | |
---|
9 | \secB{What to do} |
---|
10 | |
---|
11 | So, you have a FITS cube, and you want to find the sources in it. What |
---|
12 | do you do? First, you need to get \duchamp: there are instructions in |
---|
13 | Appendix~\ref{app-install} for obtaining and installing it. Once you |
---|
14 | have it running, the first step is to make an input file that contains |
---|
15 | the list of parameters. Brief and detailed examples are shown in |
---|
16 | Appendix~\ref{app-input}. This file provides the input file name, the |
---|
17 | various output files, and defines various parameters that control the |
---|
18 | execution. |
---|
19 | |
---|
20 | The standard way to run \duchamp is by the command |
---|
21 | \begin{quote} |
---|
22 | {\footnotesize |
---|
23 | \texttt{> Duchamp -p [parameter file]} |
---|
24 | } |
---|
25 | \end{quote} |
---|
26 | replacing \texttt{[parameter file]} with the name of the file listing |
---|
27 | the parameters. |
---|
28 | |
---|
29 | An even easier way is to use the default values for all parameters |
---|
30 | (these are given in Appendix~\ref{app-param} and in the file |
---|
31 | \texttt{InputComplete} included in the distribution directory) and use |
---|
32 | the syntax |
---|
33 | \begin{quote} |
---|
34 | {\footnotesize |
---|
35 | \texttt{> Duchamp -f [FITS file]} |
---|
36 | } |
---|
37 | \end{quote} |
---|
38 | where \texttt{[FITS file]} is the file you wish to search. |
---|
39 | |
---|
40 | The default action includes displaying a map of detected objects in a |
---|
41 | PGPLOT X-window. This can be disabled by setting the parameter |
---|
42 | \texttt{flagXOutput=false} or using the \texttt{-x} command-line |
---|
43 | option, as in |
---|
44 | \begin{quote} |
---|
45 | {\footnotesize |
---|
46 | \texttt{> Duchamp -x -p [parameter file]} |
---|
47 | } |
---|
48 | \end{quote} |
---|
49 | and similarly for the \texttt{-f} case. |
---|
50 | |
---|
51 | Once a FITS file and parameters have been set, the program will then |
---|
52 | work away and give you the list of detections and their spectra. The |
---|
53 | program execution is summarised below, and detailed in |
---|
54 | \S\ref{sec-flow}. Information on inputs is in \S\ref{sec-param} and |
---|
55 | Appendix~\ref{app-param}, and descriptions of the output is in |
---|
56 | \S\ref{sec-output}. |
---|
57 | |
---|
58 | \secB{Guide to terminology and conventions} |
---|
59 | |
---|
60 | First, a brief note on the use of terminology in this guide. \duchamp |
---|
61 | is designed to work on FITS ``cubes''. These are FITS\footnote{FITS is |
---|
62 | the Flexible Image Transport System -- see \citet{hanisch01} or |
---|
63 | websites such as |
---|
64 | \href{http://fits.cv.nrao.edu/FITS.html}{http://fits.cv.nrao.edu/FITS.html} |
---|
65 | for details.} image arrays with (at least) three dimensions. They |
---|
66 | are assumed to have the following form: the first two dimensions |
---|
67 | (referred to as $x$ and $y$) are spatial directions (that is, relating |
---|
68 | to the position on the sky -- often, but not necessarily, |
---|
69 | corresponding to Equatorial or Galactic coordinates), while the third |
---|
70 | dimension, $z$, is the spectral direction, which can correspond to |
---|
71 | frequency, wavelength, or velocity. The three dimensional analogue of |
---|
72 | pixels are ``voxels'', or volume cells -- a voxel is defined by a |
---|
73 | unique $(x,y,z)$ location and has a single value of flux, intensity |
---|
74 | or brightness (or something equivalent) associated with it. |
---|
75 | |
---|
76 | Sometimes, some pixels in a FITS file are labelled as BLANK -- that |
---|
77 | is, they are given a nominal value, defined by FITS header keywords |
---|
78 | \textsc{blank, bscale, \& bzero}, that marks them as not having a flux |
---|
79 | value. These are often used to pad a cube out so that it has a |
---|
80 | rectangular spatial shape. \duchamp has the ability to avoid these: |
---|
81 | see \S\ref{sec-blank}. |
---|
82 | |
---|
83 | Note that it is possible for the FITS file to have more than three |
---|
84 | dimensions (for instance, there could be a fourth dimension |
---|
85 | representing a Stokes parameter). Only the two spatial dimensions and |
---|
86 | the spectral dimension are read into the array of pixel values that is |
---|
87 | searched for objects. All other dimensions are ignored\footnote{This |
---|
88 | actually means that the first pixel only of that axis is used, and the |
---|
89 | array is read by the \texttt{fits\_read\_subsetnull} command from the |
---|
90 | \textsc{cfitsio} library.}. Herein, we discuss the data in terms of |
---|
91 | the three basic dimensions, but you should be aware it is possible for |
---|
92 | the FITS file to have more than three. Note that the order of the |
---|
93 | dimensions in the FITS file does not matter. |
---|
94 | |
---|
95 | With this setup, each spatial pixel (a given $(x,y)$ coordinate) can |
---|
96 | be said to be a single spectrum, while a slice through the cube |
---|
97 | perpendicular to the spectral direction at a given $z$-value is a |
---|
98 | single channel, with the 2-D image in that channel called a channel |
---|
99 | map. |
---|
100 | |
---|
101 | Detection involves locating a contiguous group of voxels with fluxes |
---|
102 | above a certain threshold. \duchamp makes no assumptions as to the |
---|
103 | size or shape of the detected features, other than having |
---|
104 | user-selected minimum size criteria. Features that are detected are |
---|
105 | assumed to be positive. The user can choose to search for negative |
---|
106 | features by setting an input parameter -- this inverts the cube prior |
---|
107 | to the search (see \S\ref{sec-detection} for details). |
---|
108 | |
---|
109 | Finally, note that it is possible to run \duchamp on a |
---|
110 | two-dimensional image (\ie one with no frequency or velocity |
---|
111 | information), or indeed a one-dimensional array, and many of the |
---|
112 | features of the program will work fine. The focus, however, is on |
---|
113 | object detection in three dimensions, one of which is a spectral |
---|
114 | dimension. |
---|
115 | |
---|
116 | \secB{A summary of the execution steps} |
---|
117 | |
---|
118 | The basic flow of the program is summarised here -- all steps are |
---|
119 | discussed in more detail in the following sections. |
---|
120 | \begin{enumerate} |
---|
121 | \item The necessary parameters are recorded. |
---|
122 | |
---|
123 | How this is done depends on the way the program is run from the |
---|
124 | command line. If the \texttt{-p} option is used, the parameter file |
---|
125 | given on the command line is read in, and the parameters therein are |
---|
126 | read. All other parameters are given their default values (listed in |
---|
127 | Appendix~\ref{app-param}). |
---|
128 | |
---|
129 | If the \texttt{-f} option is used, all parameters are assigned their |
---|
130 | default values. |
---|
131 | |
---|
132 | \item The FITS image is located and read in to memory. |
---|
133 | |
---|
134 | The file given is assumed to be a valid FITS file. As discussed |
---|
135 | above, it can have any number of dimensions, but \duchamp only |
---|
136 | reads in the two spatial and the one spectral dimensions. A subset |
---|
137 | of the FITS array can be given (see \S\ref{sec-input} for details). |
---|
138 | |
---|
139 | \item If requested, a FITS file containing a previously reconstructed |
---|
140 | or smoothed array is read in. |
---|
141 | |
---|
142 | When a cube is either smoothed or reconstructed with the \atrous |
---|
143 | wavelet method, the result can be saved to a FITS file, so that |
---|
144 | subsequent runs of \duchamp can read it in to save having to re-do |
---|
145 | the calculations (as they can be relatively time-intensive). |
---|
146 | |
---|
147 | \item \label{step-blank} If requested, BLANK pixels are trimmed from |
---|
148 | the edges, and the baseline of each spectrum is removed. |
---|
149 | |
---|
150 | BLANK pixels, while they are ignored by all calculations in |
---|
151 | \duchamp, do increase the size in memory of the array above that |
---|
152 | absolutely needed. This step trims them from the spatial edges, |
---|
153 | recording the amount trimmed so that they can be added back in |
---|
154 | later. |
---|
155 | |
---|
156 | A spectral baseline (or bandpass) can also be removed at this point |
---|
157 | as well. This may be necessary if there is a ripple or other |
---|
158 | large-scale feature present that will hinder detection of faint |
---|
159 | sources. |
---|
160 | |
---|
161 | \item If the reconstruction method is requested, and the reconstructed |
---|
162 | array has not been read in at Step 3 above, the cube is |
---|
163 | reconstructed using the \atrous wavelet method. |
---|
164 | |
---|
165 | This step uses the \atrous method to determine the amount of |
---|
166 | structure present at various scales. A simple thresholding technique |
---|
167 | then removes random noise from the cube, leaving the significant |
---|
168 | signal. This process can greatly reduce the noise level in the cube, |
---|
169 | enhancing the detectability of sources. |
---|
170 | |
---|
171 | \item Alternatively (and if requested), the cube is smoothed, either |
---|
172 | spectrally or spatially. |
---|
173 | |
---|
174 | This step presents two options. The first considers each spectrum |
---|
175 | individually, and convolves it with a Hanning filter (with width |
---|
176 | chosen by the user). The second considers each channel map |
---|
177 | separately, and smoothes it with a Gaussian kernel of size and shape |
---|
178 | chosen by the user. This step can help to reduce the amount of noise |
---|
179 | visible in the cube and enhance fainter sources. |
---|
180 | |
---|
181 | \item A threshold for the cube is then calculated, based on the pixel |
---|
182 | statistics (unless a threshold is manually specified by the user). |
---|
183 | |
---|
184 | The threshold can either be chosen as a simple $n\sigma$ threshold |
---|
185 | (\ie a certain number of standard deviations above the mean), or |
---|
186 | calculated via the ``False Discovery Rate'' method. Alternatively, |
---|
187 | the threshold can be specified as a simple flux value, without care |
---|
188 | as to the statistical significance (\eg ``I want every source |
---|
189 | brighter than 10mJy''). |
---|
190 | |
---|
191 | By default, the full cube is used for the statistics calculation, |
---|
192 | although the user can nominate a subsection of the cube to be used |
---|
193 | instead. |
---|
194 | |
---|
195 | \item Searching for objects then takes place, using the requested |
---|
196 | thresholding method. |
---|
197 | |
---|
198 | The cube is searched one channel-map at a time. Detections are |
---|
199 | compared to already detected objects and either combined with a |
---|
200 | neighbouring one or added to the end of the list. |
---|
201 | |
---|
202 | \item The list of objects is condensed by merging neighbouring objects |
---|
203 | and removing those deemed unacceptable. |
---|
204 | |
---|
205 | While some merging has been done in the previous step, this process |
---|
206 | is a much more rigorous comparison of each object with every other |
---|
207 | one. If a pair of objects lie within requested limits, they are |
---|
208 | combined. |
---|
209 | |
---|
210 | After the merging is done, the list is culled (although see comment |
---|
211 | for the next step). There are certain criteria the user can specify |
---|
212 | that objects must meet: minimum numbers of spatial pixels and |
---|
213 | spectral channels, and minimum separations between neighbouring |
---|
214 | objects. Those that do not meet these criteria are deleted |
---|
215 | from the list. |
---|
216 | |
---|
217 | \item If requested, the objects are ``grown'' down to a lower |
---|
218 | threshold, and then the merging step is done a second time. |
---|
219 | |
---|
220 | In this case, each object has pixels in its neighbourhood examined, |
---|
221 | and if they are above a secondary threshold, they are added to the |
---|
222 | object. The merging process is done a second time in case two |
---|
223 | objects have grown over the top of one another. Note that the |
---|
224 | rejection part of the previous step is not done until the end of the |
---|
225 | second merging process. |
---|
226 | |
---|
227 | \item The baselines and trimmed pixels are replaced prior to output. |
---|
228 | |
---|
229 | This is just the inverse of step~\#\ref{step-blank}. |
---|
230 | |
---|
231 | \item The details of the detections are written to screen and to the |
---|
232 | requested output file. |
---|
233 | |
---|
234 | Crucial properties of each detection are provided, showing its |
---|
235 | location, extent, and flux. These are presented in both pixel |
---|
236 | coordinates and world coordinates (\eg sky position and |
---|
237 | velocity). Any warning flags are also printed, showing detections to |
---|
238 | be wary of. Alternative output options are available, such as a |
---|
239 | VOTable or a Karma annotation file. |
---|
240 | |
---|
241 | \item Maps showing the spatial location of the detections are written. |
---|
242 | |
---|
243 | These are 2-dimensional maps, showing where each detection lies on |
---|
244 | the spatial coverage of the cube. This is provided as an aid to the |
---|
245 | user so that a quick idea of the distribution of object positions |
---|
246 | can be gained \eg are all the detections on the edge? |
---|
247 | |
---|
248 | Two maps are provided: one is a 0th moment map, showing the 0th |
---|
249 | moment (\ie a map of the integrated flux) of each detection in its |
---|
250 | appropriate position, while the second is a ``detection map'', |
---|
251 | showing the number of times each spatial pixel was detected in the |
---|
252 | searching routines (including those pixels rejected at step 9 and so |
---|
253 | not in any of the final detections). |
---|
254 | |
---|
255 | These maps are written to postscript files, and the 0th moment map |
---|
256 | can also be displayed in a PGPLOT X-window. |
---|
257 | |
---|
258 | \item The integrated or peak spectra of each detection are written to a |
---|
259 | postscript file. |
---|
260 | |
---|
261 | The spectral equivalent of the maps -- what is the spectral profile |
---|
262 | of each detection? Also provided here are basic information for each |
---|
263 | object (a summary of the information in the results file), as well |
---|
264 | as a 0th moment map of the detection. |
---|
265 | |
---|
266 | \item If requested, the reconstructed or smoothed array can be written |
---|
267 | to a new FITS file. |
---|
268 | |
---|
269 | If either of these procedures were done, the resulting array can be |
---|
270 | saved as a FITS file for later use. The FITS header will be the same |
---|
271 | as the input file, with a few additional keywords to identify the |
---|
272 | file. |
---|
273 | |
---|
274 | \end{enumerate} |
---|
275 | |
---|