[158] | 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 | So, you have a FITS cube, and you want to find the sources in it. What |
---|
| 10 | do you do? First, you need to get \duchamp: there are instructions in |
---|
| 11 | Appendix~\ref{app-install} for obtaining and installing it. Once you |
---|
| 12 | have it running, the first step is to make an input file that contains |
---|
| 13 | the list of parameters. Brief and detailed examples are shown in |
---|
| 14 | Appendix~\ref{app-input}. This file provides the input file name, the |
---|
| 15 | various output files, and defines various parameters that control the |
---|
| 16 | execution. |
---|
| 17 | |
---|
| 18 | The standard way to run \duchamp\ is by the command |
---|
| 19 | \begin{quote} |
---|
| 20 | \texttt{Duchamp -p [parameter file]} |
---|
| 21 | \end{quote} |
---|
| 22 | replacing \texttt{[parameter file]} with the name of the file listing |
---|
| 23 | the parameters. |
---|
| 24 | |
---|
| 25 | An even easier way is to use the default values for all parameters |
---|
| 26 | (these are given in Appendix~\ref{app-param} and in the file |
---|
[231] | 27 | \texttt{InputComplete} included in the distribution directory) and use |
---|
| 28 | the syntax |
---|
[158] | 29 | \begin{quote} |
---|
| 30 | \texttt{Duchamp -f [FITS file]} |
---|
| 31 | \end{quote} |
---|
| 32 | where \texttt{[FITS file]} is the file you wish to search. |
---|
| 33 | |
---|
| 34 | In either case, the program will then work away and give you the list |
---|
| 35 | of detections and their spectra. The program execution is summarised |
---|
| 36 | below, and detailed in \S\ref{sec-flow}. Information on inputs is in |
---|
| 37 | \S\ref{sec-param} and Appendix~\ref{app-param}, and descriptions of |
---|
| 38 | the output is in \S\ref{sec-output}. |
---|
| 39 | |
---|
| 40 | \secB{A summary of the execution steps} |
---|
| 41 | |
---|
| 42 | The basic flow of the program is summarised here -- all steps are |
---|
| 43 | discussed in more detail in the following sections. |
---|
| 44 | \begin{enumerate} |
---|
| 45 | \item If the \texttt{-p} option is used, the parameter file given on |
---|
| 46 | the command line is read in, and the parameters absorbed. |
---|
| 47 | \item The FITS image is located and read in to memory. |
---|
| 48 | \item If requested, a FITS image with a previously reconstructed array |
---|
| 49 | is read in. |
---|
| 50 | \item If requested, BLANK pixels are trimmed from the edges, and |
---|
| 51 | the baseline of each spectrum is removed. |
---|
| 52 | \item If the reconstruction method is requested, and the reconstructed |
---|
| 53 | array has not been read in at Step 3 above, the cube is |
---|
| 54 | reconstructed using the \atrous\ wavelet method. |
---|
[208] | 55 | \item Alternatively (and if requested), the each spectral channel is |
---|
| 56 | Hanning-smoothed by a desired amount. |
---|
[194] | 57 | \item A threshold for the cube is then calculated, based on the pixel |
---|
| 58 | statistics (unless a threshold is manually specified by the user). |
---|
[158] | 59 | \item Searching for objects then takes place, using the requested |
---|
| 60 | thresholding method. |
---|
| 61 | \item The list of objects is condensed by merging neighbouring objects |
---|
| 62 | and removing those deemed unacceptable. |
---|
| 63 | \item The baselines and trimmed pixels are replaced prior to output. |
---|
| 64 | \item The details of the detections are written to screen and to the |
---|
| 65 | requested output file. |
---|
| 66 | \item Maps showing the spatial location of the detections are written. |
---|
| 67 | \item The integrated spectra of each detection are written to a |
---|
| 68 | postscript file. |
---|
| 69 | \item If requested, the reconstructed array can be written to a new |
---|
| 70 | FITS file. |
---|
| 71 | \end{enumerate} |
---|
| 72 | |
---|
| 73 | \secB{Guide to terminology and conventions} |
---|
| 74 | |
---|
| 75 | First, a brief note on the use of terminology in this guide. \duchamp\ |
---|
| 76 | is designed to work on FITS ``cubes''. These are FITS\footnote{FITS is |
---|
| 77 | the Flexible Image Transport System -- see \citet{hanisch01} or |
---|
| 78 | websites such as |
---|
| 79 | \href{http://fits.cv.nrao.edu/FITS.html}{http://fits.cv.nrao.edu/FITS.html} |
---|
| 80 | for details.} image arrays with three dimensions -- they are assumed |
---|
| 81 | to have the following form: the first two dimensions (referred to as |
---|
| 82 | $x$ and $y$) are spatial directions (that is, relating to the position |
---|
| 83 | on the sky), while the third dimension, $z$, is the spectral |
---|
| 84 | direction, which can correspond to frequency, wavelength, or |
---|
| 85 | velocity. The three dimensional analogue of pixels are ``voxels'', or |
---|
| 86 | volume cells -- a voxel is defined by a unique $(x,y,z)$ location and |
---|
| 87 | has a unique flux or intensity value associated with it. |
---|
| 88 | |
---|
| 89 | Note that it is possible for the FITS file to have more than three |
---|
| 90 | dimensions (for instance, a fourth dimension representing Stokes |
---|
[160] | 91 | parameters). Only the two spatial dimensions and the spectral |
---|
| 92 | dimension are read into the array of pixel values that is searched for |
---|
| 93 | objects. All other dimensions are ignored\footnote{This actually means |
---|
| 94 | that the first pixel only of that axis is used, and the array is read |
---|
| 95 | by the \texttt{fits\_read\_subsetnull} command from the |
---|
| 96 | \textsc{cfitsio} library.}. Herein, we discuss the data in terms of |
---|
| 97 | the three basic dimensions, but you should be aware it is possible for |
---|
| 98 | the FITS file to have more than three. Note that the order of the |
---|
| 99 | dimensions in the FITS file does not matter. |
---|
[158] | 100 | |
---|
| 101 | Each spatial pixel (a given $(x,y)$ coordinate) can be said to be a |
---|
| 102 | single spectrum, while a slice through the cube perpendicular to the |
---|
| 103 | spectral direction at a given $z$-value is a single channel (the 2-D |
---|
| 104 | image is a channel map). |
---|
| 105 | |
---|
| 106 | Detection involves locating a contiguous group of voxels with fluxes |
---|
| 107 | above a certain threshold. \duchamp\ makes no assumptions as to the |
---|
| 108 | size or shape of the detected features, other than having |
---|
[160] | 109 | user-selected minimum size criteria. Features that are detected are |
---|
| 110 | assumed to be positive. The user can choose to search for negative |
---|
| 111 | features by setting an input parameter -- this inverts the cube prior |
---|
| 112 | to the search (see \S\ref{sec-detection} for details). |
---|
[158] | 113 | |
---|
[160] | 114 | Finally, note that it is possible to run \duchamp\ on a |
---|
| 115 | two-dimensional image (\ie one with no frequency or velocity |
---|
| 116 | information), or indeed a one-dimensional array, and many of the |
---|
| 117 | features of the program will work fine. The focus, however, is on |
---|
| 118 | object detection in three dimensions. |
---|
[158] | 119 | |
---|