source: trunk/docs/app-paramEx.tex @ 1213

% -----------------------------------------------------------------------
% app-paramEx.tex: Example input parameter files, and how the
%                  parameters are listed in the output.
% -----------------------------------------------------------------------
% Copyright (C) 2006, Matthew Whiting, ATNF
%
% This program is free software; you can redistribute it and/or modify it
% under the terms of the GNU General Public License as published by the
% Free Software Foundation; either version 2 of the License, or (at your
% option) any later version.
%
% Duchamp is distributed in the hope that it will be useful, but WITHOUT
% ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
% FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
% for more details.
%
% You should have received a copy of the GNU General Public License
% along with Duchamp; if not, write to the Free Software Foundation,
% Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA
%
% Correspondence concerning Duchamp may be directed to:
%    Internet email: Matthew.Whiting [at] atnf.csiro.au
%    Postal address: Dr. Matthew Whiting
%                    Australia Telescope National Facility, CSIRO
%                    PO Box 76
%                    Epping NSW 1710
%                    AUSTRALIA
% -----------------------------------------------------------------------
\secA{Example parameter files}
\label{app-input}

This is what a typical parameter file would look like.

\begin{verbatim}
imageFile       /home/mduchamp/fountain.fits
logFile         logfile.txt
outFile         results.txt
spectraFile     spectra.ps
flagSubsection  false
flagOutputRecon false
flagOutputResid 0
flagTrim        1
flagMW          1
minMW           75
maxMW           112
flagGrowth      1
growthCut       1.5
flagATrous      1
reconDim        1          
scaleMin        1
snrRecon        4
flagFDR         1
alphaFDR        0.1
snrCut          3
threshSpatial   3
threshVelocity  7
\end{verbatim}

Note that, as in this example, the flag parameters can be entered as
strings (\texttt{true}/\texttt{false}) or integers
(\texttt{1}/\texttt{0}). Also, note that it is not necessary to
include all these parameters in the file, only those that need to be
changed from the defaults (as listed in Appendix~\ref{app-param}),
which in this case would be very few. A minimal parameter file might
look like:
\begin{verbatim}
imageFile       /home/mduchamp/fountain.fits
flagLog         false
flagATrous      1
snrRecon        3
snrCut          2.5
minChannels     4
\end{verbatim}
This will reconstruct the cube with a lower SNR value than the
default, select objects at a lower threshold,  with a looser minimum
channel requirement, and not keep a log of the intermediate
detections. 

The following page demonstrates how the parameters are presented to
the user, both on the screen at execution time, and in the output and
log files. On each line, there is a description on the parameter, the
relevant parameter name that is used in the input file (if there is
one that the user can enter), and the value of the parameter being
used.

\newpage
{\scriptsize
\begin{verbatim}
---- Parameters ----
Image to be analysed.........................[imageFile]  =  fountain.fits
Intermediate Logfile...........................[logFile]  =  duchamp-Logfile.txt
Final Results file.............................[outFile]  =  duchamp-Results.txt
Header for results file.....................[headerFile]  =  duchamp-Results.hdr
Spectrum file..............................[spectraFile]  =  duchamp-Spectra.ps
Text file with ascii spectral data.....[spectraTextFile]  =  duchamp-Spectra.txt
VOTable file...................................[votFile]  =  duchamp-Results.xml
Karma annotation file........................[karmaFile]  =  duchamp-Results.ann
DS9 annotation file............................[ds9File]  =  duchamp-Results.reg
0th Moment Map...............................[momentMap]  =  duchamp-MomentMap.ps
Detection Map.............................[detectionMap]  =  duchamp-DetectionMap.ps
Display a map in a pgplot xwindow?.........[flagXOutput]  =  true
Saving reconstructed cube?.............[flagOutputRecon]  =  false
Saving residuals from reconstruction?..[flagOutputResid]  =  false
Saving mask cube?.......................[flagOutputMask]  =  false
Saving 0th moment to FITS file?.........[flagOutputMask]  =  false
------
Type of searching performed.................[searchType]  =  spectral
Blank Pixel Value.......................................  =  -8.00061
Trimming Blank Pixels?........................[flagTrim]  =  false
Searching for Negative features?..........[flagNegative]  =  false
Removing Milky Way channels?....................[flagMW]  =  true
Milky Way Channels.......................[minMW - maxMW]  =  75-113
Area of Beam (pixels)...................................  =  14.6848   (beam: 3.6 x 3.6 pixels)
Removing baselines before search?.........[flagBaseline]  =  false
Smoothing data prior to searching?..........[flagSmooth]  =  false
Using A Trous reconstruction?...............[flagATrous]  =  true
Number of dimensions in reconstruction........[reconDim]  =  1
Minimum scale in reconstruction...............[scaleMin]  =  1
SNR Threshold within reconstruction...........[snrRecon]  =  3
Filter being used for reconstruction........[filterCode]  =  1 (B3 spline function)
Using Robust statistics?...............[flagRobustStats]  =  true
Using FDR analysis?............................[flagFDR]  =  false
SNR Threshold (in sigma)........................[snrCut]  =  3
Minimum # Pixels in a detection.................[minPix]  =  5
Minimum # Channels in a detection..........[minChannels]  =  3
Minimum # Voxels in a detection..............[minVoxels]  =  7
Growing objects after detection?............[flagGrowth]  =  false
Using Adjacent-pixel criterion?...........[flagAdjacent]  =  true
Max. velocity separation for merging....[threshVelocity]  =  7
Reject objects before merging?...[flagRejectBeforeMerge]  =  false
Merge objects in two stages?.......[flagTwoStageMerging]  =  false
Method of spectral plotting.............[spectralMethod]  =  sum
Type of object centre used in results......[pixelCentre]  =  centroid
--------------------
\end{verbatim}
}
%\end{minipage}
%\end{sideways}