% -----------------------------------------------------------------------
% userInputs.tex: Quick guide to how the input parameters are read.
% -----------------------------------------------------------------------
% 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{User Inputs}

\secB{Parameter file input}
\label{sec-param}

\duchamp allows a large degree of control over the way the different
algorithms work. This is done by means of input parameters, specified
through a parameter file. The parameter file is provided at runtime,
via
\begin{quote}
{\footnotesize
\texttt{> Duchamp -p [parameter file]}
}
\end{quote}
The parameter file simply contains a list of parameter names followed
by the value that should be assigned to them. The syntax used is 
\begin{quote}
\texttt{parameterName value}.
\end{quote}
Parameter names are not case-sensitive, and lines in the input
file that start with \texttt{\#} are ignored. If a parameter is listed
more than once, the latter value is used, but otherwise the order in
which the parameters are listed in the input file is
arbitrary. Example input files can be seen in
Appendix~\ref{app-input}.

If a parameter is not listed, the default value is assumed. The
defaults are chosen to provide a good result (a simple $5\sigma$
search with no pre-processing), so the user doesn't need to specify
many new parameters in the input file. Note that the image file
\textbf{must} be specified!  The parameters that can be set are listed
in Appendix~\ref{app-param}, with their default values in parentheses.

The parameters with names starting with \texttt{flag} are stored as
\texttt{bool} variables, and so are either \texttt{true = 1} or
\texttt{false = 0}. They can be entered in the file either in text or
integer format -- \duchamp will read them correctly in either case.

An example input file is included in the distribution tar file. It is
as follows:

\begin{verbatim}
imageFile       your-file-here
logFile         logfile.txt
outFile         results.txt
spectraFile     spectra.ps
minPix          2
flagATrous      1
snrRecon        5.
snrCut          3.
minChannels     3
flagBaseline    1
\end{verbatim}

You would, of course, replace the ``\texttt{your-file-here}'' with the
FITS file you wanted to search. Further examples are given in
Appendix~\ref{app-input}.

\secB{Command-line control}

\duchamp provides the ability to run without constructing a parameter
file first. Using the \texttt{-f} command-line flag to specify an
image will make use of the default values for all parameters:
\begin{quote}
{\footnotesize
\texttt{> Duchamp -f [FITS image]}
}
\end{quote}

It is possible to specify a flux threshold as well on the command
line, using the \texttt{-t} flag. This allows the user to quickly
search a given image to a given depth (\ie give me all sources in this
image above 1mJy.
\begin{quote}
{\footnotesize
\texttt{> Duchamp -f [FITS image] -t [THRESHOLD]}
}
\end{quote}
The \texttt{-t} flag can also be used with the \texttt{-p} option --
it sets the \texttt{threshold} parameter, and overrides the value
provided in the parameter file specified. The flux threshold should be
in the same brightness units as specified in the FITS image.

The other command-line flag that can be used is \texttt{-x}. This
turns off the X-window output (that graphically shows where the
detected objects are). This makes scripted use of \duchamp somewhat
easier. 



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