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 | % ----------------------------------------------------------------------- |
---|
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 | |
---|
37 | \secB*{Input related} |
---|
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 |
---|
42 | wants a subsection of the requested image. |
---|
43 | \item[{Subsection [ [*,*,*] ]}] The requested subsection |
---|
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). |
---|
47 | \item[{flagReconExists [false]}] A flag to indicate whether the |
---|
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. |
---|
51 | \item[{reconFile [no default]}] The FITS file that contains the |
---|
52 | reconstructed array. If \texttt{flagReconExists} is true and this |
---|
53 | parameter is not defined, the default file that is looked for will |
---|
54 | be determined by the \atrous parameters (see \S\ref{sec-recon}). |
---|
55 | \item[{flagSmoothExists [false]}] A flag to indicate whether the |
---|
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. |
---|
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 |
---|
63 | \S\ref{sec-smoothing}). |
---|
64 | \item[{usePrevious [false]}] A flag to indicate that \duchamp should |
---|
65 | read the list of objects from a previously-created log file, rather |
---|
66 | than doing the searching itself. The set of outputs will be created |
---|
67 | according to the flags in the following section. |
---|
68 | \item[{objectList [no default]}] When \texttt{usePrevious=true}, this |
---|
69 | list is used to output individual spectral plots, as well as a |
---|
70 | postscript file for all spectral plots as given by |
---|
71 | \texttt{SpectraFile}. The filenames of the plots will be the same as |
---|
72 | \texttt{SpectraFile}, but with -XX at the end, where XX is the |
---|
73 | object number (\eg \texttt{duchamp-Spectra-07.ps}). The format of |
---|
74 | the parameter value should be a string listing individual objects or |
---|
75 | object ranges: \eg 1,2,4-7,8,14. |
---|
76 | \end{Lentry} |
---|
77 | |
---|
78 | \secB*{Output related} |
---|
79 | \begin{Lentry} |
---|
80 | \item[{OutFile [duchamp-\\Results.txt]}] The file containing the |
---|
81 | final list of detections. This also records the list of input |
---|
82 | parameters. |
---|
83 | \item[{flagSeparateHeader [false]}] A flag to indicate that the header |
---|
84 | information that would normally be printed at the start of the |
---|
85 | results file (containing information on the parameters, image |
---|
86 | statistics and number of detections) should instead be written to a |
---|
87 | separate file. |
---|
88 | \item[{HeaderFile [duchamp-\\Results.hdr]}] The file to which the |
---|
89 | header information should be written when |
---|
90 | \texttt{flagSeparateHeader=true}. |
---|
91 | \item[{SpectraFile [duchamp-\\Spectra.ps]}] The postscript file |
---|
92 | containing the resulting integrated spectra and images of the |
---|
93 | detections. |
---|
94 | \item[{flagTextSpectra [false]}] A flag to say whether the spectra |
---|
95 | should be saved in text form in a single file. See below for a |
---|
96 | description. |
---|
97 | \item[{spectraTextFile [duchamp-\\Spectra.txt]}] The file containing |
---|
98 | the spectra of each object in ascii format. This file will have a |
---|
99 | column showing the spectral coordinates, and one column for each of |
---|
100 | the detected objects, showing the flux values as plotted in the |
---|
101 | graphical output of \texttt{spectraFile}. |
---|
102 | \item[{flagLog [false]}] A flag to indicate whether the |
---|
103 | details of intermediate detections should be logged. |
---|
104 | \item[{LogFile [duchamp-\\Logfile.txt]}] The file in which |
---|
105 | intermediate detections are logged. These are detections that have |
---|
106 | not been merged. This is primarily for use in debugging and |
---|
107 | diagnostic purposes: normal use of the program will probably not |
---|
108 | require it. |
---|
109 | \item[{flagOutputMomentMap [false]}] A flag to say whether or not to save a |
---|
110 | FITS file containing the moment-0 map. |
---|
111 | \item[fileOutputMomentMap{ [see text]}] The file to which the moment-0 array is |
---|
112 | written. If left blank (the default), the naming scheme detailed in |
---|
113 | Section~\ref{sec-maskOut} is used. |
---|
114 | \item[{flagOutputMask [false]}] A flag to say whether or not to save a |
---|
115 | FITS file containing a mask array, with values 1 where there is a |
---|
116 | detected object and 0 elsewhere. |
---|
117 | \item[fileOutputMask{ [see text]}] The file to which the mask array is |
---|
118 | written. If left blank (the default), the naming scheme detailed in |
---|
119 | Section~\ref{sec-maskOut} is used. |
---|
120 | \item[{flagMaskWithObjectNum [false]}] If this flag is true, the |
---|
121 | detected pixels in the mask image have the corresponding object ID |
---|
122 | as their value. If false, they have the value 1. All non-detected |
---|
123 | pixels have the value 0. |
---|
124 | \item[{flagOutputRecon [false]}] A flag to say whether or not |
---|
125 | to save the reconstructed cube as a FITS file. |
---|
126 | \item[fileOutputRecon{ [see text]}] The file to which the reconstructed array |
---|
127 | is written. If left blank (the default), the naming scheme detailed |
---|
128 | in Section~\ref{sec-reconIO} is used. |
---|
129 | \item[{flagOutputResid [false]}] As for |
---|
130 | \texttt{flagOutputRecon}, but for the residual array -- the |
---|
131 | difference between the original cube and the reconstructed cube. |
---|
132 | \item[fileOutputResid{ [see text]}] The file to which the residual array |
---|
133 | is written. If left blank (the default), the naming scheme detailed |
---|
134 | in Section~\ref{sec-reconIO} is used. |
---|
135 | \item[{flagOutputSmooth [false]}] A flag to say whether or not |
---|
136 | to save the smoothed cube as a FITS file. |
---|
137 | \item[fileOutputSmooth{ [see text]}] The file to which the smoothed array |
---|
138 | is written. If left blank (the default), the naming scheme detailed |
---|
139 | in Section~\ref{sec-reconIO} is used. |
---|
140 | \item[{flagVOT [false]}] A flag to say whether to create a |
---|
141 | VOTable file with the detection information. This will be an XML |
---|
142 | file in the Virtual Observatory VOTable format. |
---|
143 | \item[{votFile [duchamp-\\Results.xml]}] The VOTable file with |
---|
144 | the list of final detections. Some input parameters are also |
---|
145 | recorded. |
---|
146 | \item[{flagKarma [false]}] A flag to say whether to create a |
---|
147 | Karma annotation file corresponding to the information in |
---|
148 | \texttt{outfile}. This can be used as an overlay in Karma |
---|
149 | programs such as \texttt{kvis}. |
---|
150 | \item[{karmaFile [duchamp-\\Results.ann]}] The Karma annotation |
---|
151 | file showing the list of final detections. |
---|
152 | \item[{annotationType [borders]}] Which type of annotation plot to |
---|
153 | use. Specifying ``borders'' gives an outline around the detected |
---|
154 | spatial pixels, while ``circles'' gives a circle centred on the |
---|
155 | centre of the object with radius large enough to encompass all |
---|
156 | spatial pixels. |
---|
157 | \item[{flagMaps [true]}] A flag to say whether to save |
---|
158 | postscript files showing the 0th moment map of the whole cube |
---|
159 | (parameter \texttt{momentMap}) and the detection image |
---|
160 | (\texttt{detectionMap}). |
---|
161 | \item[{momentMap [duchamp-\\MomentMap.ps]}] A postscript file |
---|
162 | containing a map of the 0th moment of the detected sources, as well |
---|
163 | as pixel and WCS coordinates. |
---|
164 | \item[{detectionMap [duchamp-\\DetectionMap.ps]}] A postscript |
---|
165 | file with a map showing each of the detected objects, coloured in |
---|
166 | greyscale by the number of detected channels in each spatial |
---|
167 | pixel. Also shows pixel and WCS coordinates. |
---|
168 | \item[{flagXOutput [true]}] A flag to say whether to display a |
---|
169 | 0th moment map in a PGPlot X-window. This will be in addition to any |
---|
170 | that are saved to a file. This parameter can be overridden by the |
---|
171 | use of the \texttt{-x} command-line option, which disables the |
---|
172 | X-windows output. |
---|
173 | \item[{newFluxUnits [no default]}] Flux units that the pixel values |
---|
174 | should be converted into. These should be directly compatible with |
---|
175 | the existing units, given by the BUNIT keyword. |
---|
176 | \item[{precFlux [3]}] The desired precision (\ie number of decimal |
---|
177 | places) for flux values given in the output files and tables. |
---|
178 | \item[{precVel [3]}] The desired precision (\ie number of decimal |
---|
179 | places) for velocity/frequency values given in the output files and |
---|
180 | tables. |
---|
181 | \item[{precSNR [2]}] The desired precision (\ie number of decimal |
---|
182 | places) for the peak SNR value given in the output files and tables. |
---|
183 | \end{Lentry} |
---|
184 | |
---|
185 | \secB*{Modifying the cube} |
---|
186 | \begin{Lentry} |
---|
187 | \item[{flagTrim [false]}] A flag to say whether to trim |
---|
188 | BLANK pixels from the edges of the cube -- these are typically |
---|
189 | pixels set to some particular value because they fall outside the |
---|
190 | imaged area, and trimming them can help speed up the execution. |
---|
191 | \item[{flagMW [false]}] A flag to say whether to ignore |
---|
192 | channels contaminated by Milky Way (or other) emission -- the |
---|
193 | searching algorithms will not look at these channels. |
---|
194 | \item[{maxMW [112]}] The maximum channel number that contains |
---|
195 | ``Milky Way'' emission. This is the channel number in the original |
---|
196 | cube, before any subsection is applied. |
---|
197 | \item[{minMW [75]}] The minimum channel number that contains ``Milky |
---|
198 | Way'' emission. This is the channel number in the original cube, |
---|
199 | before any subsection is applied. Note that the range specified by |
---|
200 | \texttt{maxMW} and \texttt{minMW} is inclusive. |
---|
201 | \item[{flagBaseline [false]}] A flag to say whether to remove |
---|
202 | the baseline from each spectrum in the cube for the purposes of |
---|
203 | reconstruction and detection. |
---|
204 | \end{Lentry} |
---|
205 | |
---|
206 | \secB*{Detection related} |
---|
207 | |
---|
208 | \secC*{General detection} |
---|
209 | \begin{Lentry} |
---|
210 | \item[{searchType [spatial]}] How the searches are done. A value of |
---|
211 | ``spatial'' means each 2D channel map is searched, whereas |
---|
212 | ``spectral'' means each 1D spectrum is searched. |
---|
213 | \item[{flagStatSec [false]}] A flag indicating whether the |
---|
214 | statistics should be calculated on a subsection of the cube, rather |
---|
215 | than the full cube. Note that this only applies to the statistics |
---|
216 | used to determine the threshold, and not for other statistical |
---|
217 | calculations (such as those in the reconstruction phase). |
---|
218 | \item[{StatSec [ [*,*,*] ]}] The subsection of the cube used |
---|
219 | for calculating statistics -- see \S\ref{sec-input} for details on |
---|
220 | the subsection format. Only used if \texttt{flagStatSec=true}. |
---|
221 | \item[{flagRobustStats [true]}] A flag indicating whether to use the |
---|
222 | robust statistics (median and MADFM) to estimate the noise |
---|
223 | parameters, rather than the mean and rms. See \S\ref{sec-stats} for |
---|
224 | details. |
---|
225 | \item[{flagNegative [false]}] A flag indicating that the |
---|
226 | features of interest are negative. The cube is inverted prior to |
---|
227 | searching. |
---|
228 | \item[{snrCut [3.]}] The threshold, in multiples of $\sigma$ above |
---|
229 | the mean. |
---|
230 | \item[{threshold [no default]}] The actual value of the |
---|
231 | threshold. Normally the threshold is calculated from the cube's |
---|
232 | statistics, but the user can manually specify a value to be used |
---|
233 | that overrides the calculated value. If this is not specified, the |
---|
234 | calculated value is used, but this value will take precedence over |
---|
235 | other means of calculating the threshold (\ie via \texttt{snrCut} or |
---|
236 | the FDR method). |
---|
237 | \item[{flagGrowth [false]}] A flag indicating whether or not to |
---|
238 | grow the detected objects to a smaller threshold. |
---|
239 | \item[{growthCut [3.]}] The smaller threshold using in growing |
---|
240 | detections. In units of $\sigma$ above the mean. |
---|
241 | \item[{growthThreshold [no default]}] Alternatively, the threshold to |
---|
242 | which detections are grown can be specified in flux units (in the |
---|
243 | same manner as the \texttt{threshold} parameter). When the |
---|
244 | \texttt{threshold} parameter is given, this option \textbf{must} be |
---|
245 | used instead of \texttt{growthCut}. |
---|
246 | \item[{beamFWHM [0.]}] The full-width at half maximum of the beam, in |
---|
247 | pixels. If the header keywords BMAJ and BMIN are present, then |
---|
248 | these will be used to calculate the beam area, and this parameter |
---|
249 | will be ignored. This will take precedence over \texttt{beamArea} |
---|
250 | (but is ignored if not specified). |
---|
251 | \item[{beamArea [0.]}] The \textbf{area} of the beam in pixels (\ie |
---|
252 | how many pixel does the beam cover?). As above, if the header |
---|
253 | keywords BMAJ and BMIN are present, then these will be used to |
---|
254 | calculate the beam area, and this parameter will be ignored. |
---|
255 | \end{Lentry} |
---|
256 | |
---|
257 | \secC*{\Atrous reconstruction} |
---|
258 | \begin{Lentry} |
---|
259 | \item[{flagATrous [false]}] A flag indicating whether or not to |
---|
260 | reconstruct the cube using the \atrous wavelet |
---|
261 | reconstruction. See \S\ref{sec-recon} for details. |
---|
262 | \item[{reconDim [1]}] The number of dimensions to use in the |
---|
263 | reconstruction. 1 means reconstruct each spectrum separately, 2 |
---|
264 | means each channel map is done separately, and 3 means do the whole |
---|
265 | cube in one go. |
---|
266 | \item[{scaleMin [1]}] The minimum wavelet scale to be used in the |
---|
267 | reconstruction. A value of 1 means ``use all scales''. |
---|
268 | \item[{scaleMax [0]}] The maximum wavelet scale to be used in the |
---|
269 | reconstruction. If the value is $\le0$ then the maximum scale is |
---|
270 | calculated from the size of the input array. Similarly, if the value |
---|
271 | given is larger than this calculated value, the calculated value is |
---|
272 | used instead. |
---|
273 | \item[{snrRecon [4]}] The thresholding cutoff used in the |
---|
274 | reconstruction -- only wavelet coefficients this many $\sigma$ above |
---|
275 | the mean (or greater) are included in the reconstruction. |
---|
276 | \item[{filterCode [1]}] The code number of the filter to use in |
---|
277 | the reconstruction. The options are: |
---|
278 | \begin{itemize} |
---|
279 | \item \textbf{1:} B$_3$-spline filter: coefficients = |
---|
280 | $(\frac{1}{16}, \frac{1}{4}, \frac{3}{8}, \frac{1}{4}, \frac{1}{16})$ |
---|
281 | \item \textbf{2:} Triangle filter: coefficients = |
---|
282 | $(\frac{1}{4}, \frac{1}{2}, \frac{1}{4})$ |
---|
283 | \item \textbf{3:} Haar wavelet: coefficients = |
---|
284 | $(0, \frac{1}{2}, \frac{1}{2})$ |
---|
285 | \end{itemize} |
---|
286 | \end{Lentry} |
---|
287 | |
---|
288 | \secC*{Smoothing the cube} |
---|
289 | \begin{Lentry} |
---|
290 | \item[{flagSmooth [false]}] A flag indicating whether to |
---|
291 | smooth the cube. See \S\ref{sec-smoothing} for details. |
---|
292 | \item[{smoothType [spectral]}] The smoothing method used: either |
---|
293 | ``spectral'' (with a 1D Hanning filter) or ``spatial'' (with a 2D |
---|
294 | Gaussian filter). |
---|
295 | \item[{hanningWidth [5]}] The width of the Hanning smoothing |
---|
296 | kernel. |
---|
297 | \item[{kernMaj [3]}] The full-width-half-maximum (FWHM) of the |
---|
298 | 2D Gaussian smoothing kernel's major axis. |
---|
299 | \item[{kernMin [3]}] The FWHM of the 2D Gaussian smoothing kernel's |
---|
300 | minor axis. |
---|
301 | \item[{kernPA [0]}] The position angle, in degrees, |
---|
302 | anticlockwise from vertical (\ie usually East of North). |
---|
303 | \end{Lentry} |
---|
304 | |
---|
305 | \secC*{FDR method} |
---|
306 | \begin{Lentry} |
---|
307 | \item[{flagFDR [false]}] A flag indicating whether or not to use |
---|
308 | the False Discovery Rate method in thresholding the pixels. |
---|
309 | \item[{alphaFDR [0.01]}] The $\alpha$ parameter used in the FDR |
---|
310 | analysis. The average number of false detections, as a fraction of |
---|
311 | the total number, will be less than $\alpha$ (see |
---|
312 | \S\ref{sec-detection}). |
---|
313 | \item[{FDRnumCorChan [2]}] The number of neighbouring spectral |
---|
314 | channels that are assumed to be correlated. This is needed by the |
---|
315 | FDR algorithm to calculate the normalisation constant $c_N$ (see |
---|
316 | \S\ref{sec-detection}). |
---|
317 | \end{Lentry} |
---|
318 | |
---|
319 | \secC*{Merging detections} |
---|
320 | \begin{Lentry} |
---|
321 | \item[{minPix [2]}] The minimum number of spatial pixels for a |
---|
322 | single detection to be counted. |
---|
323 | \item[{minChannels [3]}] At least one contiguous set of this many |
---|
324 | channels must be present in the detection for it to be accepted. |
---|
325 | \item[{minVoxels [4]}] A detection must have at least this many voxels |
---|
326 | in it to be counted. |
---|
327 | \item[{flagRejectBeforeMerge [false]}] A flag indicating whether to |
---|
328 | reject sources that fail to meet the \texttt{minPix} or |
---|
329 | \texttt{minChannels} criteria \textbf{before} the merging |
---|
330 | stage. Default behaviour is to do the rejection last. |
---|
331 | \item[{flagTwoStageMerging [true]}] A flag indicating whether to do an |
---|
332 | initial merge of newly-detected sources into the source list as they |
---|
333 | are found. If \texttt{false}, new sources are simply added to the |
---|
334 | end of the list for later merging. |
---|
335 | \item[{flagAdjacent [true]}] A flag indicating whether to use |
---|
336 | the ``adjacent pixel'' criterion to decide whether to merge |
---|
337 | objects. If not, the next two parameters are used to determine |
---|
338 | whether objects are within the necessary thresholds. |
---|
339 | \item[{threshSpatial [3.]}] The maximum allowed minimum spatial |
---|
340 | separation (in pixels) between two detections for them to be merged |
---|
341 | into one. Only used if \texttt{flagAdjacent = false}. |
---|
342 | \item[{threshVelocity [7.]}] The maximum allowed minimum channel |
---|
343 | separation between two detections for them to be merged into |
---|
344 | one. |
---|
345 | \end{Lentry} |
---|
346 | |
---|
347 | \secC*{Other parameters} |
---|
348 | \begin{Lentry} |
---|
349 | \item[{spectralMethod [peak]}] This indicates which method is used |
---|
350 | to plot the output spectra: \texttt{peak} means plot the spectrum |
---|
351 | containing the detection's peak pixel; \texttt{sum} means sum the |
---|
352 | spectra of each detected spatial pixel, and correct for the beam |
---|
353 | size. Any other choice defaults to \texttt{peak}. |
---|
354 | \item[{spectralUnits [km/s]}] The user can specify the units of |
---|
355 | the spectral axis. Assuming the WCS of the FITS file is valid, the |
---|
356 | spectral axis is transformed into velocity, and put into these units |
---|
357 | for all output and for calculations such as the integrated flux of a |
---|
358 | detection. |
---|
359 | \item[{pixelCentre [centroid]}] Which of the three ways of |
---|
360 | expressing the ``centre'' of a detection (see \S\ref{sec-results} |
---|
361 | for a description of the options) to use for the X, Y, \& Z |
---|
362 | columns in the output list. Alternatives are: \texttt{centroid, peak, |
---|
363 | average}. |
---|
364 | \item[{sortingParam [vel]}] The parameter on which to sort the output |
---|
365 | list of detected objects. Options are: x-value, y-value, z-value, |
---|
366 | ra, dec, vel, w50, iflux, pflux (integrated and peak flux |
---|
367 | respectively), or snr. |
---|
368 | \item[{drawBorders [true]}] A flag indicating whether to draw |
---|
369 | borders around the detected objects in the moment maps included in |
---|
370 | the output (see for example Fig.~\ref{fig-spect}). |
---|
371 | \item[{drawBlankEdges [true]}] A flag indicating whether to |
---|
372 | draw the dividing line between BLANK and non-BLANK pixels on the |
---|
373 | 2D images (see for example Fig.~\ref{fig-moment}). |
---|
374 | \item[{verbose [true]}] A flag indicating whether to print the |
---|
375 | progress of any computationally intensive algorithms (\eg |
---|
376 | reconstruction, searching or merging algorithms) to the screen. |
---|
377 | \end{Lentry} |
---|
378 | |
---|