% -----------------------------------------------------------------------
% 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
flaggedChannels 75-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
# CASA annotation file..............................[casaFile]  =  duchamp-Results.crf
# 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]  =  true --> fountain.RECON-1-1-4-1-8-0.005.fits
# Saving residuals from reconstruction?......[flagOutputResid]  =  true --> latestResid.fits
# Saving mask cube?...........................[flagOutputMask]  =  true --> latestmask2.fits
# Saving 0th moment to FITS file?........[flagOutputMomentMap]  =  true --> latestmom0.fits
# Saving 0th moment mask to FITS file?..[flagOutputMomentMask]  =  true --> latestmom0mask.fits
# Saving baseline values to FITS file?....[flagOutputBaseline]  =  false
# ------
# Type of searching performed.....................[searchType]  =  spectral
# Blank Pixel Value...........................................  =  -8.00061
# Trimming Blank Pixels?............................[flagTrim]  =  false
# Searching for Negative features?..............[flagNegative]  =  false
# Channels flagged by user...................[flaggedChannels]  =  75-112
# 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
# Scales used in reconstruction............[scaleMin-scaleMax]  =  1-8
# SNR Threshold within reconstruction...............[snrRecon]  =  4
# Residual convergence criterion............[reconConvergence]  =  0.005
# 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.5
# 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]  =  peak
# Type of object centre used in results..........[pixelCentre]  =  centroid
# --------------------
\end{verbatim}
}
%\end{minipage}
%\end{sideways}

%%% Local Variables: 
%%% mode: latex
%%% TeX-master: "Guide"
%%% End: