[303] | 1 | % ----------------------------------------------------------------------- |
---|
| 2 | % app-param.tex: Section listing all the possible input parameters and |
---|
| 3 | % their defaults. |
---|
| 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 | % ----------------------------------------------------------------------- |
---|
[158] | 29 | \secA{Available parameters} |
---|
| 30 | \label{app-param} |
---|
| 31 | |
---|
| 32 | The full list of parameters that can be listed in the input file are |
---|
| 33 | given here. If not listed, they take the default value given in |
---|
| 34 | parentheses. Since the order of the parameters in the input file does |
---|
| 35 | not matter, they are grouped here in logical sections. |
---|
| 36 | |
---|
[208] | 37 | \secB*{Input related} |
---|
[306] | 38 | \begin{Lentry} |
---|
| 39 | \item[{ImageFile [no default]}] The filename of the |
---|
| 40 | data cube to be analysed. |
---|
| 41 | \item[{flagSubsection [false]}] A flag to indicate whether one |
---|
[158] | 42 | wants a subsection of the requested image. |
---|
[306] | 43 | \item[{Subsection [ [*,*,*] ]}] The requested subsection |
---|
[258] | 44 | -- see \S\ref{sec-input} for details on the subsection format. If |
---|
| 45 | the full range of a dimension is required, use a \texttt{*} (thus the |
---|
| 46 | default is the full cube). |
---|
[306] | 47 | \item[{flagReconExists [false]}] A flag to indicate whether the |
---|
[158] | 48 | reconstructed array has been saved by a previous run of \duchamp. If |
---|
| 49 | set true, the reconstructed array will be read from the file given |
---|
| 50 | by \texttt{reconFile}, rather than calculated directly. |
---|
[306] | 51 | \item[{reconFile [no default]}] The FITS file that contains the |
---|
[158] | 52 | reconstructed array. If \texttt{flagReconExists} is true and this |
---|
[231] | 53 | parameter is not defined, the default file that is looked for will |
---|
[258] | 54 | be determined by the \atrous parameters (see \S\ref{sec-recon}). |
---|
[306] | 55 | \item[{flagSmoothExists [false]}] A flag to indicate whether the |
---|
[208] | 56 | Hanning-smoothed array has been saved by a previous run of \duchamp. If |
---|
| 57 | set true, the smoothed array will be read from the file given |
---|
| 58 | by \texttt{smoothFile}, rather than calculated directly. |
---|
[306] | 59 | \item[{smoothFile [no default]}] The FITS file that has |
---|
| 60 | a previously smoothed array. If \texttt{flagSmoothExists} |
---|
| 61 | is true and this parameter is not defined, the default file that is |
---|
| 62 | looked for will be determined by the smoothing parameters (see |
---|
[208] | 63 | \S\ref{sec-smoothing}). |
---|
[306] | 64 | \end{Lentry} |
---|
[208] | 65 | |
---|
| 66 | \secB*{Output related} |
---|
[306] | 67 | \begin{Lentry} |
---|
| 68 | \item[{OutFile [duchamp-\\Results.txt]}] The file containing the |
---|
[158] | 69 | final list of detections. This also records the list of input |
---|
[364] | 70 | parameters. |
---|
| 71 | \item[{flagSeparateHeader [false]}] A flag to indicate that the header |
---|
| 72 | information that would normally be printed at the start of the |
---|
| 73 | results file (containing information on the parameters, image |
---|
| 74 | statistics and number of detections) should instead be written to a |
---|
| 75 | separate file. |
---|
| 76 | \item[{HeaderFile [duchamp-\\Results.hdr]}] The file to which the |
---|
[373] | 77 | header information should be written when |
---|
[364] | 78 | \texttt{flagSeparateHeader=true}. |
---|
[306] | 79 | \item[{SpectraFile [duchamp-\\Spectra.ps]}] The postscript file |
---|
[158] | 80 | containing the resulting integrated spectra and images of the |
---|
[306] | 81 | detections. |
---|
| 82 | \item[{flagLog [false]}] A flag to indicate whether the |
---|
[231] | 83 | details of intermediate detections should be logged. |
---|
[306] | 84 | \item[{LogFile [duchamp-\\Logfile.txt]}] The file in which |
---|
[158] | 85 | intermediate detections are logged. These are detections that have |
---|
| 86 | not been merged. This is primarily for use in debugging and |
---|
[306] | 87 | diagnostic purposes: normal use of the program will probably not |
---|
| 88 | require it. |
---|
| 89 | \item[{flagOutputRecon [false]}] A flag to say whether or not |
---|
[158] | 90 | to save the reconstructed cube as a FITS file. The filename will be |
---|
| 91 | derived according to the naming scheme detailed in |
---|
| 92 | Section~\ref{sec-reconIO}. |
---|
[306] | 93 | \item[{flagOutputResid [false]}] As for |
---|
[158] | 94 | \texttt{flagOutputRecon}, but for the residual array -- the |
---|
| 95 | difference between the original cube and the reconstructed cube. The |
---|
| 96 | filename will be derived according to the naming scheme detailed in |
---|
| 97 | Section~\ref{sec-reconIO}. |
---|
[306] | 98 | \item[{flagOutputSmooth [false]}] A flag to say whether or not |
---|
[208] | 99 | to save the smoothed cube as a FITS file. The filename will be |
---|
| 100 | derived according to the naming scheme detailed in |
---|
| 101 | Section~\ref{sec-smoothing}. |
---|
[306] | 102 | \item[{flagVOT [false]}] A flag to say whether to create a |
---|
| 103 | VOTable file with the detection information. This will be an XML |
---|
| 104 | file in the Virtual Observatory VOTable format. |
---|
| 105 | \item[{votFile [duchamp-\\Results.xml]}] The VOTable file with |
---|
[158] | 106 | the list of final detections. Some input parameters are also |
---|
[306] | 107 | recorded. |
---|
| 108 | \item[{flagKarma [false]}] A flag to say whether to create a |
---|
[158] | 109 | Karma annotation file corresponding to the information in |
---|
[306] | 110 | \texttt{outfile}. This can be used as an overlay in Karma |
---|
[158] | 111 | programs such as \texttt{kvis}. |
---|
[306] | 112 | \item[{karmaFile [duchamp-\\Results.ann]}] The Karma annotation |
---|
| 113 | file showing the list of final detections. |
---|
| 114 | \item[{flagMaps [true]}] A flag to say whether to save |
---|
[158] | 115 | postscript files showing the 0th moment map of the whole cube |
---|
| 116 | (parameter \texttt{momentMap}) and the detection image |
---|
| 117 | (\texttt{detectionMap}). |
---|
[306] | 118 | \item[{momentMap [duchamp-\\MomentMap.ps]}] A postscript file |
---|
[158] | 119 | containing a map of the 0th moment of the detected sources, as well |
---|
| 120 | as pixel and WCS coordinates. |
---|
[306] | 121 | \item[{detectionMap [duchamp-\\DetectionMap.ps]}] A postscript |
---|
| 122 | file with a map showing each of the detected objects, coloured in |
---|
| 123 | greyscale by the number of detected channels in each spatial |
---|
| 124 | pixel. Also shows pixel and WCS coordinates. |
---|
| 125 | \item[{flagXOutput [true]}] A flag to say whether to display a |
---|
[294] | 126 | 0th moment map in a PGPlot X-window. This will be in addition to any |
---|
| 127 | that are saved to a file. This parameter can be overridden by the |
---|
| 128 | use of the \texttt{-x} command-line option, which disables the |
---|
| 129 | X-windows output. |
---|
[306] | 130 | \end{Lentry} |
---|
[158] | 131 | |
---|
| 132 | \secB*{Modifying the cube} |
---|
[306] | 133 | \begin{Lentry} |
---|
| 134 | \item[{flagTrim [false]}] A flag to say whether to trim |
---|
[285] | 135 | BLANK pixels from the edges of the cube -- these are typically |
---|
| 136 | pixels set to some particular value because they fall outside the |
---|
| 137 | imaged area, and trimming them can help speed up the execution. |
---|
[306] | 138 | \item[{flagMW [false]}] A flag to say whether to ignore |
---|
[158] | 139 | channels contaminated by Milky Way (or other) emission -- the |
---|
| 140 | searching algorithms will not look at these channels. |
---|
[306] | 141 | \item[{maxMW [112]}] The maximum channel number that contains |
---|
[158] | 142 | ``Milky Way'' emission. |
---|
[306] | 143 | \item[{minMW [75]}] The minimum channel number that contains |
---|
[158] | 144 | ``Milky Way'' emission. Note that the range specified by |
---|
| 145 | \texttt{maxMW} and \texttt{minMW} is inclusive. |
---|
[306] | 146 | \item[{flagBaseline [false]}] A flag to say whether to remove |
---|
[158] | 147 | the baseline from each spectrum in the cube for the purposes of |
---|
| 148 | reconstruction and detection. |
---|
[306] | 149 | \end{Lentry} |
---|
[158] | 150 | |
---|
| 151 | \secB*{Detection related} |
---|
| 152 | |
---|
| 153 | \secC*{General detection} |
---|
[306] | 154 | \begin{Lentry} |
---|
| 155 | \item[{flagStatSec [false]}] A flag indicating whether the |
---|
[258] | 156 | statistics should be calculated on a subsection of the cube, rather |
---|
[265] | 157 | than the full cube. Note that this only applies to the statistics |
---|
| 158 | used to determine the threshold, and not for other statistical |
---|
| 159 | calculations (such as those in the reconstruction phase). |
---|
[306] | 160 | \item[{StatSec [ [*,*,*] ]}] The subsection of the cube used |
---|
[258] | 161 | for calculating statistics -- see \S\ref{sec-input} for details on |
---|
| 162 | the subsection format. Only used if \texttt{flagStatSec=true}. |
---|
[306] | 163 | \item[{flagNegative [false]}] A flag indicating that the |
---|
| 164 | features of interest are negative. The cube is inverted prior to |
---|
| 165 | searching. |
---|
| 166 | \item[{snrCut [3.]}] The threshold, in multiples of $\sigma$ above |
---|
| 167 | the mean. |
---|
| 168 | \item[{threshold [no default]}] The actual value of the |
---|
[194] | 169 | threshold. Normally the threshold is calculated from the cube's |
---|
| 170 | statistics, but the user can manually specify a value to be used |
---|
| 171 | that overrides the calculated value. If this is not specified, the |
---|
| 172 | calculated value is used. Also, when the FDR method is requested |
---|
| 173 | (see below), the value of the \texttt{threshold} parameter is |
---|
[306] | 174 | ignored. |
---|
| 175 | \item[{flagGrowth [false]}] A flag indicating whether or not to |
---|
[158] | 176 | grow the detected objects to a smaller threshold. |
---|
[306] | 177 | \item[{growthCut [2.]}] The smaller threshold using in growing |
---|
[158] | 178 | detections. In units of $\sigma$ above the mean. |
---|
[306] | 179 | \item[{beamSize [10.]}] The size of the beam in pixels. If the |
---|
[162] | 180 | header keywords BMAJ and BMIN are present, then these will be used |
---|
| 181 | to calculate the beam size, and this parameter will be ignored. |
---|
[306] | 182 | \end{Lentry} |
---|
[158] | 183 | |
---|
[258] | 184 | \secC*{\Atrous reconstruction} |
---|
[306] | 185 | \begin{Lentry} |
---|
| 186 | \item[{flagATrous [false]}] A flag indicating whether or not to |
---|
[258] | 187 | reconstruct the cube using the \atrous wavelet |
---|
[158] | 188 | reconstruction. See \S\ref{sec-recon} for details. |
---|
[306] | 189 | \item[{reconDim [1]}] The number of dimensions to use in the |
---|
[158] | 190 | reconstruction. 1 means reconstruct each spectrum separately, 2 |
---|
| 191 | means each channel map is done separately, and 3 means do the whole |
---|
| 192 | cube in one go. |
---|
[306] | 193 | \item[{scaleMin [1]}] The minimum wavelet scale to be used in the |
---|
[158] | 194 | reconstruction. A value of 1 means ``use all scales''. |
---|
[364] | 195 | \item[{scaleMax [0]}] The maximum wavelet scale to be used in the |
---|
| 196 | reconstruction. If the value is $\le0$ then the maximum scale is |
---|
| 197 | calculated from the size of the input array. Similarly, if the value |
---|
| 198 | given is larger than this calculated value, the calculated value is |
---|
| 199 | used instead. |
---|
[306] | 200 | \item[{snrRecon [4]}] The thresholding cutoff used in the |
---|
[158] | 201 | reconstruction -- only wavelet coefficients this many $\sigma$ above |
---|
| 202 | the mean (or greater) are included in the reconstruction. |
---|
[306] | 203 | \item[{filterCode [1]}] The code number of the filter to use in |
---|
[158] | 204 | the reconstruction. The options are: |
---|
| 205 | \begin{itemize} |
---|
| 206 | \item \textbf{1:} B$_3$-spline filter: coefficients = |
---|
| 207 | $(\frac{1}{16}, \frac{1}{4}, \frac{3}{8}, \frac{1}{4}, \frac{1}{16})$ |
---|
| 208 | \item \textbf{2:} Triangle filter: coefficients = |
---|
| 209 | $(\frac{1}{4}, \frac{1}{2}, \frac{1}{4})$ |
---|
| 210 | \item \textbf{3:} Haar wavelet: coefficients = |
---|
| 211 | $(0, \frac{1}{2}, \frac{1}{2})$ |
---|
| 212 | \end{itemize} |
---|
[306] | 213 | \end{Lentry} |
---|
[158] | 214 | |
---|
[208] | 215 | \secC*{Smoothing the cube} |
---|
[306] | 216 | \begin{Lentry} |
---|
| 217 | \item[{flagSmooth [false]}] A flag indicating whether to |
---|
[275] | 218 | smooth the cube. See \S\ref{sec-smoothing} for details. |
---|
[306] | 219 | \item[{smoothType [spectral]}] The smoothing method used: either |
---|
| 220 | ``spectral'' (with a 1D Hanning filter) or ``spatial'' (with a 2D |
---|
| 221 | Gaussian filter). |
---|
| 222 | \item[{hanningWidth [5]}] The width of the Hanning smoothing |
---|
| 223 | kernel. |
---|
| 224 | \item[{kernMaj [3]}] The full-width-half-maximum (FWHM) of the |
---|
| 225 | 2D Gaussian smoothing kernel's major axis. |
---|
| 226 | \item[{kernMin [3]}] The FWHM of the 2D Gaussian smoothing kernel's |
---|
| 227 | minor axis. |
---|
| 228 | \item[{kernPA [0]}] The position angle, in degrees, |
---|
| 229 | anticlockwise from vertical (\ie usually East of North). |
---|
| 230 | \end{Lentry} |
---|
[208] | 231 | |
---|
[158] | 232 | \secC*{FDR method} |
---|
[306] | 233 | \begin{Lentry} |
---|
| 234 | \item[{flagFDR [false]}] A flag indicating whether or not to use |
---|
[158] | 235 | the False Discovery Rate method in thresholding the pixels. |
---|
[306] | 236 | \item[{alphaFDR [0.01]}] The $\alpha$ parameter used in the FDR |
---|
| 237 | analysis. The average number of false detections, as a fraction of |
---|
| 238 | the total number, will be less than $\alpha$ (see |
---|
| 239 | \S\ref{sec-detection}). |
---|
| 240 | \end{Lentry} |
---|
[158] | 241 | |
---|
| 242 | \secC*{Merging detections} |
---|
[306] | 243 | \begin{Lentry} |
---|
| 244 | \item[{minPix [2]}] The minimum number of spatial pixels for a |
---|
[158] | 245 | single detection to be counted. |
---|
[306] | 246 | \item[{minChannels [3]}] At least one contiguous set of this many |
---|
| 247 | channels must be present in the detection for it to be accepted. |
---|
| 248 | \item[{flagAdjacent [true]}] A flag indicating whether to use |
---|
[158] | 249 | the ``adjacent pixel'' criterion to decide whether to merge |
---|
| 250 | objects. If not, the next two parameters are used to determine |
---|
| 251 | whether objects are within the necessary thresholds. |
---|
[306] | 252 | \item[{threshSpatial [3.]}] The maximum allowed minimum spatial |
---|
[158] | 253 | separation (in pixels) between two detections for them to be merged |
---|
| 254 | into one. Only used if \texttt{flagAdjacent = false}. |
---|
[306] | 255 | \item[{threshVelocity [7.]}] The maximum allowed minimum channel |
---|
[158] | 256 | separation between two detections for them to be merged into |
---|
| 257 | one. |
---|
[306] | 258 | \end{Lentry} |
---|
[158] | 259 | |
---|
| 260 | \secC*{Other parameters} |
---|
[306] | 261 | \begin{Lentry} |
---|
| 262 | \item[{spectralMethod [peak]}] This indicates which method is used |
---|
[158] | 263 | to plot the output spectra: \texttt{peak} means plot the spectrum |
---|
| 264 | containing the detection's peak pixel; \texttt{sum} means sum the |
---|
| 265 | spectra of each detected spatial pixel, and correct for the beam |
---|
| 266 | size. Any other choice defaults to \texttt{peak}. |
---|
[306] | 267 | \item[{spectralUnits [km/s]}] The user can specify the units of |
---|
[158] | 268 | the spectral axis. Assuming the WCS of the FITS file is valid, the |
---|
| 269 | spectral axis is transformed into velocity, and put into these units |
---|
| 270 | for all output and for calculations such as the integrated flux of a |
---|
| 271 | detection. |
---|
[306] | 272 | \item[{pixelCentre [centroid]}] Which of the three ways of |
---|
[285] | 273 | expressing the ``centre'' of a detection (see \S\ref{sec-results} |
---|
| 274 | for a description of the options) to use for the X, Y, \& Z |
---|
| 275 | columns in the output list. Alternatives are: \texttt{centroid, peak, |
---|
| 276 | average}. |
---|
[306] | 277 | \item[{drawBorders [true]}] A flag indicating whether to draw |
---|
| 278 | borders around the detected objects in the moment maps included in |
---|
| 279 | the output (see for example Fig.~\ref{fig-spect}). |
---|
| 280 | \item[{drawBlankEdges [true]}] A flag indicating whether to |
---|
| 281 | draw the dividing line between BLANK and non-BLANK pixels on the |
---|
| 282 | 2D images (see for example Fig.~\ref{fig-moment}). |
---|
| 283 | \item[{verbose [true]}] A flag indicating whether to print the |
---|
| 284 | progress of any computationally intensive algorithms (\eg |
---|
[231] | 285 | reconstruction, searching or merging algorithms) to the screen. |
---|
[306] | 286 | \end{Lentry} |
---|
[158] | 287 | |
---|