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