path: root/noao/digiphot/apphot/doc/userdocs/apuser.ms

.RP

.TL
A User's Guide to the IRAF Apphot Package

.AU
Lindsey Elspeth Davis
.AI

.K2 "" "" "*"
Revised May 1989

.AB
.PP
The APPHOT package is a set of tasks for performing aperture photometry
on uncrowded or moderately crowded stellar fields in either interactive or batch
mode. The photometric technique employed is fractional pixel 
integration. Point spread function fitting techniques are not used and no
knowledge of the point spread function is required for the computation of
magnitudes. Separate tasks are provided for creating and modifying object
lists, computing accurate centers and sky values for a list of objects,
and performing photometry inside concentric
circular or polygonal apertures.
.PP
This document describes the data preparation required to run APPHOT, how
to set up the display and graphics devices, how to set the algorithm
parameters, how to run the package tasks in interactive or batch mode
and how to selectively examine the results. Detailed descriptions of the
algorithms can be found in the document \fISpecifications for the
APPHOT Package\fR by the author.
.PP
This document applies to APPHOT under IRAF version 2.8.  APPHOT
can be run under IRAF versions 2.5, 2.6 and 2.7  with only minor changes in
the task setup. These differences are documented
where appropriate in the text.
.AE

.NH
Introduction
.PP
The APPHOT package is a set of tasks for performing
aperture photometry on uncrowded or moderately crowded fields.
The photometric technique employed is fractional pixel integration. Point
spread function techniques are not used and no knowledge of the point spread
function is required for the computation of magnitudes.
.PP
The APPHOT package performs multi-aperture photometry on digitized starfields
maintained as IRAF image files. Input to the package consists of an
image file(s), an optional list(s) of object coordinates,
numerous parameters controlling
the analysis algorithms and, optionally, the graphics terminal and/or
display. APPHOT output consists of successive records, where each record
records the results of the analysis for a single object. Some tasks 
also produce graphics output in the form of plot metacode files.
.PP
Given starting coordinates and an IRAF image, the principal APPHOT
task \fBphot\fR computes accurate centers, sky values and magnitudes
for a list of objects.  Separate
IRAF callable tasks in APPHOT exist to create and modify object
lists, to determine image characteristics such as the full width half maximum
of the point spread function or standard deviation of the sky pixels,
to compute accurate centers for a list of objects, to compute accurate local sky
values for a list of objects, and to compute magnitudes inside a polygonal
aperture.
.PP
The image data requirements of the APPHOT package are described in section 2.
Section 3 describes various ways to tailor the IRAF environment to run
the APPHOT package. Section 4 describes how to load the APPHOT tasks and how
use the on-help facility.  Section 5 describes how to examine and edit the
APPHOT task and algorithm parameters. Several methods of creating and
modifying APPHOT coordinate lists files are described in section 6.
Sections 7 and 8 describe how to run the APPHOT tasks interactively without
and with a coordinate list respectively. Batch mode reductions in APPHOT are
described in section 9.  Section 10 describes the format of the APPHOT output
catalogue and plot files. Section 12 lists various APPHOT recipes for reducing
common types of astronomical data with APPHOT.

.NH
Data Preparation and Requirements
.PP
APPHOT assumes that the images to be analyzed exist on disk in IRAF readable
format.  Facilities for reading and writing images exist elsewhere in IRAF
in the DATAIO and MTLOCAL packages. None of the current APPHOT
tasks alter the disk input images in any way.
.PP
APPHOT assumes that the pixel data is linear. The input images should be
corrected for those instrumental defects which affect the intensity
of a pixel prior to entering the APPHOT package. These defects include pixel
to pixel variations in the bias values,
pixel to pixel gain variations, cosmic rays, cosmetic defects, geometric
distortion and detector non-linearities. Users should be aware of the IRAF
CCDRED package for reducing CCD data and the DTOI package for converting
photographic density data to intensity data.
.PP
Extreme valued pixels should be removed from the images prior to entering
the APPHOT package. These include pixel values at or near the data limits of the
host machine as well as any host machine values such as INDEF,
produced by divide by zero, and floating point underflows and overflows.
Floating point operations involving such numbers may crash
with arithmetic exception errors. For efficiency and portability reasons
the APPHOT package and most IRAF routines do not test for these numbers.
The \fBimreplace\fR and \fBimedit\fP tasks in the PROTO  package can be used to replace extreme
valued pixels.  More general system facilities for handling bad pixels
inside IRAF are planned for the near future.
.PP
In order to normalize the magnitude scales of a list of images to a common
integration time,
APPHOT requires that the image exposure times be stored in the image header.
Similarly the correct computation of magnitude errors requires that
the readout noise and gain parameters also be present in the image
header or be supplied as constants in the APPHOT parameter files.
The readout noise must be supplied in units of electrons and the gain
is assumed to be in electrons per adu. The time units are arbitrary
but must be consistent for a given set of images.
APPHOT tasks access this information using a keyword and value scheme.
The IMAGES package task \fBhedit\fR can be used to insert or edit this
information prior to entering the APPHOT package. For example the following
commands will enter the gain, readout noise and exposure time information
into the headers of a list of images.

.nf
	\f(CWcl> hedit *.imh gain 14.0 add+ ver-
	cl> hedit *.imh readout 20.0 add+ ver-
	cl> hedit *.imh exptime add+ ver+\fR
.fi

.PP
The point spread function is assumed to be constant for all regions
of the image. This is critical in the case of faint objects for
which small apertures which minimize the effects of crowding and sky noise in
the aperture are used. The wings of the object will almost certainly extend
beyond the aperture and good results will only be obtained if objects
are consistently well centered and the shape and diameter of an object is
constant throughout the object and invariant to magnitude.
.PP
The centering routines built into the APPHOT package  assume that
the images are close to circularly symmetric over the region to be used
in centering although small deviations do not
significantly affect the accuracy of the results.
The user should be aware of the more sophisticated 
but less efficient centering routines in the \fBdaofind\fR and \fBfitpsf\fR
routines. Several choices of centering algorithm are available in
APPHOT including  no centering.
.PP
APPHOT assumes that the local sky background is approximately flat in the
vicinity of the object being measured. This assumption is equivalent to
assuming that
the local sky region has a unique mode. Therefore any variations in the
sky background which occur at the same scale as the sky region should be
removed prior to entering the APPHOT package.

.NH
Setting up the IRAF Environment for APPHOT
.NH 2
Script, Compiled and Pset Tasks
.PP
IRAF supports three types of tasks: scripts, compiled tasks and pset tasks.
In order to distinguish one type of task from another, APPHOT users should 
set the cl parameter \fBshowtype\fR to yes as shown below.

.nf
	\f(CWcl> cl.showtype=yes\fR
.fi

The cl command \fB?\fR or \fB?\fR \fIpackage\fR identifies script
tasks by a terminating period and pset tasks by a terminating @.
No trailing characters are added to the compiled task names. Pset tasks are
important to the APPHOT package and will be discussed further in
section 5.

.NH 2
Other IRAF Packages
.PP
Before running APPHOT, users may wish to load the IRAF packages, DATAIO,
IMAGES, 
TV and PLOT. Various input and output routines exist in the DATAIO package,
including the fits reader and writer and the cardimage reader and
writer. The IMAGES package contains routines for basic image arithmetic,
for computing image statistics, for listing individual pixel values,
and for examining and
modifying the image headers. TV, a subpackage of IMAGES, contains the
\fBdisplay\fR task for loading images into the display device.
The PLOT package contains tasks for plotting
image data and for extracting and displaying individual plots from the plot
metacode files produced by the APPHOT tasks.
.PP
Various useful tasks for manipulating and displaying the data produced by
APPHOT can be found in the PROTO package under the NOAO package. In
particular the user should be aware of the \fBfields\fR, \fBmkhistogram\fR
and \fBtvmark\fP tasks.

.NH 2
The Image Cursor and Display Device
.PP
The APPHOT tasks are designed in interactive mode to read the image cursor
and to perform various actions based on the position of the image cursor
and the keystroke typed. The image cursor is directed to the display
device defined by the environment variable \fBstdimage\fR. To check the
value of the default display device, type the following command.

.nf
	\f(CWcl> show stdimage
	imt512\fR
.fi

In this example the default display device is the 512 pixel square SUN
imtool window.
All tasks which write images to the display access this
device. For example the
TV package \fBdisplay\fR program will load an image onto this device.
.PP
In normal operation IRAF tasks which read the image cursor would read
the hardware cursor from this device.
In response to the user command

.nf
	\f(CWcl> =imcur
	or
	cl> show imcur\fR
.fi

the cursor would come up on the image display ready to accept a
keystroke command.  At this point the user should check that the display
is reading the correct image coordinates by moving the image cursor to
the lower left hand corner of the display image and tapping any key.
The coordinates should read x,y = (1,1) if the whole image was
displayed.
.PP
Cursor readback is currently implemented under IRAF version 2.7 for the
SUN workstations and the IIS model 70. Users with older versions of IRAF
or other devices cannot run APPHOT tasks directly from the image display
device and must redirect the image cursor.
Two choices are available.
.IP [1]
The image cursor can be directed to accept commands from
the standard input. This is the default setup under IRAF version 2.6.
This setup can be checked by typing the following command.

.nf
	\f(CWcl> show stdimcur
	text\fR
.fi

If the value of \fBstdimcur\fR is not "text" the user can set this value by
typing the following.

.nf
	\f(CWcl> set stdimcur = text\fR
.fi

Each time the cursor is to be read the user will be prompted for image
cursor mode text input. The form and syntax of this command are
described in detail in section 7.3.
.IP [2]
Alternatively a contour plot of the image can be used in place of the
image display and APPHOT tasks can be directed to read the graphics cursor.
To direct the image cursor to the graphics device the user types

.nf
	\f(CWcl> set stdimcur = stdgraph\fR
.fi

This usage permits interactive use of the APPHOT package for users with graphics
terminals but no image display. This setup is most suitable for terminals
which permit the text and graphics planes to be displayed simultaneously.
.RS
.LP
It is currently the responsibility of the user to ensure that the image
displayed on the image display is the same as the image operated on by
the APPHOT tasks.
.RE

.NH
Loading the Apphot Package
.PP
At this point the user has the local environment set up and is ready to
load the APPHOT package.  APPHOT resides in the DIGIPHOT package (IRAF
version 2.8 and later) under the NOAO suite of packages.
Assuming
that the NOAO package is already loaded the user types the following.

.nf
	\f(CWcl> digiphot
	cl> apphot\fR
.fi

APPHOT can also be an add-on package (IRAF version 2.7 and earlier) 
installed under the
LOCAL package. In this case the user types.

.nf
	\f(CWcl> local
	cl> apphot\fR
.fi

The following menu of tasks is displayed.

.nf
\f(CW
  apselect      daofind     fitsky        photpars@   polyphot   wphot
  center        datapars@   fitskypars@   polymark    qphot    
  centerpars@   fitpsf      phot          polypars@   radprof
\fR
.fi

The APPHOT package is now loaded and ready to run.
A quick one line description of each APPHOT task can be obtained by typing
the following command.

.nf
	\f(CWap> help apphot\fR
.fi

The following text appears.
.KS
.nf
\f(CW
digiphot.apphot:
       apselect - Extract select fields from apphot output files
         center - Compute accurate centers for a list of objects
     centerpars - Edit the centering parameters
        daofind - Find stars in an image using the DAO algorithm
       datapars - Edit the data dependent parameters
         fitpsf - Model the stellar psf with an analytic function
         fitsky - Compute sky values in a list of annular or circular
                  regions
     fitskypars - Edit the sky fitting parameters
           phot - Measure magnitudes for a list of stars
       photpars - Edit the photometry parameters
       polymark - Create polygon and coordinate lists for polyphot
       polyphot - Measure magnitudes inside a list of polygonal regions
       polypars - Edit the polyphot parameters
          qphot - Measure quick magnitudes for a list of stars
        radprof - Compute the stellar radial profile of a list of stars
          wphot - Measure magnitudes with weighting
\fR
.fi
.KE
For the remainder of this document
we will use the principal APPHOT task \fBphot\fR as an example of how to
setup the parameters in both interactive and batch mode.
To get detailed help  on the phot task the user types the following.

.nf
	\f(CWcl> help phot | lprint\fR
.fi

The help page(s) for the \fBphot\fR task will appear on the local default
printer.

.NH
Setting the APPHOT Photometry Task Parameters
.PP
The principal APPHOT task PHOT is described in sections 5.1 to 5.6.  The
quick photometry task QPHOT is described in section 5.7 and the
polygonal aperture photometry task POLYPHOT is described in section
5.8.
.NH 2
The Task Parameters
.PP
The \fBphot\fR task parameter set specifies the required image, coordinate
and output files, the graphics and display devices, the graphics and image
cursor and the mode of use of the task, interactive or batch. To enter
and edit the parameter set for the \fBphot\fR task the user types the
following.

.nf
	\f(CWcl> epar phot\fR
.fi

The parameter set for the \fBphot\fR task will appear on the terminal ready
for editing as follows.

.nf
\f(CW
                             IRAF
             Image Reduction and Analysis Facility

   PACKAGE = apphot
   TASK = phot
   
   image   =                       Input image
   (datapar=                     ) Data dependent parameters
   (centerp=                     ) Centering parameters
   (fitskyp=                     ) Sky fitting parameters
   (photpar=                     ) Photometry parameters
   (coords =                     ) Coordinate list
   skyfile =                       Sky file
   (output =              default) Results file
   (plotfil=                     ) File of plot metacode
   (graphic=             stdgraph) Graphics device
   (display=             stdimage) Display device
   (command=                     ) Image cursor: [x y wcs] key [cmd]
   (cursor =                     ) Graphics cursor: [x y wcs] key [cmd]
   (radplot=                   no) Plot the radial profiles
   (interac=                  yes) Mode of use
   (verify =                  yes) Verify critical parameters in non
                                   interactive mode
   (verbose=                   no) Print messages in non interactive mode
   (mode   =                   ql)
\fR
.fi

The \fBphot\fR parameters can be edited in the usual fashion by successively
moving
the cursor to the line opposite the parameter name, entering the new value,
followed by a carriage return, and finally typing a ^Z to exit the
\fBepar\fR task and update the parameters.
Some general points about the task
parameter sets are summarized below. For more detailed descriptions of each
parameter see the help pages for each task.
.IP [1]
\fBImage\fR specifies the list of input image(s) containing the 
stars to be measured. \fBImage\fR may be a list of images, an image
template or a file containing a list of images.
For example if we wish to measure stars in three images: m31U, m31B and
m31V we could specify the \fBimage\fR parameter in the following three ways.

.nf
\f(CW
   image   =       m31B,m31U,m31V  Input image
	or
   image   =             m31*.imh  Input image
	or
   image   =              @imlist  Input image
\fR
.fi

"Imlist" is the name of a text file containing the list of images
one image name per line. The image list file can easily be created with the cl
package \fBfiles\fR task or the editor.
.IP [2]
Four parameter sets, henceforth psets, \fBdatapars\fR, \fBcenterpars\fR,
\fBfitskypars\fR and \fBphotpars\fR specify the algorithm parameters.
They are described in detail in later sections. 
.IP [3]
\fBCoords\fR specifies the name of the coordinate file(s) containing the
initial positions of the stars to be measured. If \fBcoords\fR = "",
the current image cursor position is read and used as the initial position.
The number of files specified by
\fBcoords\fR must be either one, in  which
case the same coordinate file is used for all the images, or equal in
number to the set of input images.
\fBCoords\fR can be a list of files, a file name template,
or a file
containing the list of x and y coordinates one per line.
For example if we have three coordinate files "m31B.coo", "m31U.coo" and
"m31V.coo" for the three images listed above, we could set the \fBcoords\fR
parameter in the following three ways.

.nf
\f(CW
   (coords = m31B.coo,m31U.coo,m31V.coo) Coordinate list
	or
   (coords =             m31*.coo) Coordinate list
	or
   (coords =           @coordlist) Coordinate list
\fR
.fi

"Coordlist" is the name of a text file containing the names of the coordinate
files in the desired order one per line.
.IP [4]
\fBOutput\fR specifies the name of the results file(s). If \fBoutput\fR =
"default" then a single output file is created for
each input image and the root of the output file name is the name of the
input image. In the case of the above example \fBphot\fR would create three
output files called "m31B.mag.1", "m31U.mag.1" and "m31V.mag.1" assuming
that this was the initial run of \fBphot\fR on these images.
If the user sets the \fBoutput\fR parameter then the number of output files
must be either one or equal to the number of input images. For example the
user could set \fBoutput\fR to either

.nf
\f(CW
   (output =              m31.out) Results
   or
   (output = m31b.out,m31u.out,m31v.out) Results
\fR
.fi

If the user sets \fBoutput\fR = "" then no output file is written.
.IP [5]
The parameters \fBgraphics\fR and \fBdisplay\fR specify the graphics and
image display devices. In IRAF version 2.6 and later the APPHOT tasks
which reference these parameters will in interactive mode issue a warning
if they cannot open either of these devices
and continue execution. In IRAF version 2.5 the \fBdisplay\fR parameter must
be set to "stdgraph" as listed below

.nf
\f(CW
   (display=             stdgraph) Display device
\fR
.fi

or the following system error will be generated.

.nf
\f(CW
    "cannot execute connected subprocess x_stdimage.e"
\fR
.fi
Most of the APPHOT tasks use IRAF graphics in interactive mode to allow
users to set up their parameters and /or examine their results using radial
profile plots. The \fBgraphics\fR specifies which graphics device these plots
will be written to. Similarly most IRAF tasks permit the user to optionally
mark the star positions, apertures and sky annuli on the display device.
The parameter \fBdisplay\fR specifies which image display device this
information will be written to. Currently IRAF does not support an image display
kernel so the display marking features of APPHOT are not available unless
the user chooses to run APPHOT interactively from a contour plot.
.IP [6]
If \fBplotfile\fR is not equal to "", then for each star written to
\fBoutput\fR
a radial profile plot is written to the plot metacode file \fBplotfile\fR.
The \fBplotfile\fR is opened in append mode and succeeding executions
of \fBphot\fR write to the end of the same file which may in the process
become very large.
\fIThe user should be aware that writing radial profile plots
to \fBplotfile\fI can significantly slow the execution of \fBphot\fR.
The variable \fBradplots\fR enables radial profile plotting in interactive mode.
For each star measured a radial profile plot displaying the answers is
plotted on the screen.
.IP [7]
The \fBinteractive\fR parameter switches the task between interactive
and batch mode.
In interactive mode plots and text are written to the terminal as well as the
output file and the user can show and set the parameters. In batch mode
\fBphot\fR executes silently.
.IP [8]
The \fBverify\fP parameter allows the user to verify the critical task
parameters in non interactive mode.  It is normally set to yes but
should be turned off when submitting jobs to background.
.IP [9]
The \fBverbose\fP switch permits the printing of results to the standard
output in non interactive mode.  It is normally turned off.

.NH 2
APPHOT Psets
.PP
APPHOT algorithm parameters have been gathered together into logical
groups and stored in parameter files. The use of psets permits the
user to store APPHOT parameters with their relevant datasets rather than
in the uparm directory and allows APPHOT tasks to share common parameter
sets. APPHOT presently supports 5 pset files: 1) \fBdatapars\fR which contains
the data dependent parameter 2) \fBcenterpars\fR which contains the
centering algorithm parameters 3) \fBfitskypars\fR which contains the
sky fitting
algorithm parameters 4) \fBphotpars\fR which contains the multiaperture
photometry parameters and 5) \fBpolypars\fR which contains the polygonal
aperture
photometry parameters. The user should consult the manual page for each
of the named pset files as well as the attached parameter set document,
\fIExternal Parameter Sets in the CL and Related Revisions\fR, by Doug Tody.
.PP
The default mode of running APPHOT is to edit and store the pset parameter
files in the uparm directory.  For example to edit the
\fBdatapars\fR parameter set, the user types either

.nf
	\f(CWcl> epar datapars\fR
	or
	\f(CWcl> datapars\fR
.fi

and edits the file as usual. All the top level tasks which reference this
pset will pick up the changes from the uparm directory, assuming
datapars = "".
.PP
Alternatively the user can edit the \fBphot\fR
task and its psets all at once as follows using \fBepar\fR.

.nf
	\f(CWcl> epar phot\fR
.fi

Move the cursor to the \fBdatapars\fR parameter line and type \fB:e\fR.
The menu for the 
\fBdatapars\fR pset will appear and is ready for editing. Edit the desired
parameters and type \fB:q\fR. \fBEpar\fR will return to the main
\fBphot\fR parameter set.
Follow the same procedure for the other three psets
\fBcenterpars\fR, \fBfitskypars\fR and \fBphotpars\fR and exit the program
in the usual manner.
.PP
Sometimes it is desirable to store a given pset along with the data.
This provides a facility for keeping many different copies of say the
\fBdatapars\fR pset with the data.
The example below shows how to write a pset out to a file in the same directory
as the data. The user types

.nf
	\f(CWcl> epar phot\fR
.fi

as before, enters the datapars menu with \f(CW:e\fR and edits the parameters.
The command

.nf
	\f(CW:w data1.par\fR
.fi

writes the parameter set to a file called "data1.par" and a \fB:q\fR
returns to the main task menu.
A file called "data1.par" containing the new \fBdatapars\fR parameters
will be written in the current directory. At this point the user is in the
\fBphot\fR parameter set at the line opposite \fBdatapars\fR and
enters "data1.par" on the line opposite this parameter.
The next time \fBphot\fR is run the parameters will
be read from "data1.par" not from the pset in the uparm directory.
This procedure can be repeated for each data set which has distinct parameters,
as in for example data taken on separate nights.

.NH 2
Datapars
.PP
All the data dependent parameters have been gathered together in one
pset \fBdatapars\fR. The idea behind this organization is to facilitate
setting up the algorithm
psets for data taken under different conditions. For example the
user may have determined the optimal centering box size, sky annulus radius
and width and aperture radii in terms of the current \fBfwhmpsf\fR and the
rejection criteria in terms of the current background standard deviation
\fBsigma\fR.  In order to use the same setup on
the next image the user need only reset the \fBscale\fR and background
\fBsigma\fR parameters to the new values.
The only pset which need be edited is \fBdatapars\fR.
.PP
To examine and edit the \fBdatapars\fR pset type

.nf
	\f(CWap> datapars\fR
.fi

and the following menu will appear on the screen.

.nf
\f(CW
                                IRAF
                  Image Reduction and Analysis Facility

   PACKAGE = apphot
   TASK = datapars

   (fwhmpsf=                   1.) FWHM of the PSF in scale units
   (emissio=                  yes) Features are positive
   (noise  =              poisson) Noise model
   (thresho=                   0.) Detection threshold in counts above
                                   background
   (cthresh=                   0.) Centering threshold in counts above
                                   background
   (sigma  =                INDEF) Standard deviation of background in counts 
   (scale  =                   1.) Image scale in units per pixel
   (ccdread=                     ) CCD readout noise image header keyword
   (readnoi=                INDEF) CCD readout noise in electrons
   (gain   =                     ) CCD gain image header keyword
   (epadu  =                   1.) Gain in electrons per count
   (exposur=                     ) Exposure time image header keyword
   (itime  =                INDEF) Integration time
   (datamin=                INDEF) Minimum good data pixel
   (datamax=                INDEF) Maximum good data pixel
   (mode   =                   ql)
   ($nargs =                    0)
\fR
.fi

.PP
The following is a brief description of the parameters and their function
as well as some initial setup recommendations.

.PP
\fBScale\fP is the image scale parameter in units per pixel, for example
arc-seconds per pixel.  All distance dependent parameters in the APPHOT package
including the centering box width \fBcbox\fP in \fBcenterpars\fP, the 
inner radius and width of the sky annulus, \fBannulus\fP and 
\fBdannulus\fP in \fBfitskypars\fP, and the radii of the concentric
circular apertures \fBapertures\fP in \fBphotpars\fP are defined
in scale units, for example arc seconds.  This permits easy comparison
with apertures published in the literature.  Some other algorithm
parameters such as \fBmaxshift\fP in \fBcenterpars\fP and the region
growing radius \fBrgrow\fP in
\fBfitskypars\fP are also defined in scale units.  By default all
distance parameters are defined in pixels.
.PP
\fBFwhmpsf\fP is used as a first guess for modelling the psf in the 
\fBfitpsf\fP task, is important for the optimal use of the \fBdaofind\fP
algorithm, and critical for the centering algorithms "gauss" and
"ofilter" as well as the \fBwphot\fP task.
\fBFwhmpsf\fR as well as the other distance dependent parameters
can be set interactively from inside most of the APPHOT tasks.
.PP
\fBFwhmpsf\fP and \fBscale\fP can be combined in an interesting way.
\fBScale\fP can be defined in units of half width half maximum of the psf per
pixel in which case the value of \fBfwhmpsf\fP should be set to
\fB2.0\fP by definition.  By trial and error and use of the interactive
setup menu optimal values of the remaining distance dependent parameters
can be determined in units of \fBscale\fP.  Once determined the same
setup can be reused on another image by simply reseting the \fBscale\fP
parameter.
.PP
APPHOT photometry routines permit measurement of both emission and absorption
features.  For the majority of applications including photometry of
stars and galaxies
all "objects" are emission "objects" and the \fBemission\fR parameter should
be left at yes.
.PP
APPHOT currently supports two noise models "constant" and "poisson".
If \fBnoise\fR = "constant" the magnitude errors are computed from the
Poisson noise in the sky background plus the readout noise.
If \fBnoise\fR = "poisson"
the magnitude errors are computed on the basis of the Poisson noise in the
constant sky background, Poisson noise in the object and readout noise.
Most users
with CCD data will wish to leave \fBnoise\fR = "poisson".
\fBCthreshold\fR is a parameter required by the centering algorithms.
If \fBcthreshold\fR > 0.0, pixels below the data minimum plus
threshold in the centering subraster are not used by the centering algorithm.
For difficult centering problems the user may wish to adjust
this parameter.
The \fBsigma\fR parameter specifies the standard deviation of the background
in a single pixel. \fBSigma\fR is used
to estimate the signal to noise ratio in the centering subraster and to set
the width and bin size of the histogram of sky pixels, the \fBkhist\fR and
\fBbinsize\fR parameters in the pset \fBfitskypars\fR. Both \fBcthreshold\fR and
\fBsigma\fR can be set interactively from inside the \fBphot\fR task.
.PP
APPHOT currently recognizes three image header keywords \fBccdread\fR,
\fBgain\fR and \fBexposure\fR.  Knowledge of the instrument gain and
readout noise is required for the correct computation of the magnitude
errors but not required for the magnitude computation. The units of
the gain and readout noise are assumed to be electrons per adu
and electrons respectively.
Exposure time information is required to normalize the magnitudes computed
for a series of images to a common exposure time.
The time units are arbitrary but must be consistent for a set of images.
If this information is already in the
image header the user can enter the appropriate header keywords.
Otherwise the instrument constants gain and readout noise can be entered
into the parameters \fBepadu\fR and \fBreadnoise\fR.
If the exposure time information is not present in the image header, the
user can either edit it in with the \fBhedit\fR task or change the \fBitime\fR
parameter for each image reduced. If both image header keywords and
default parameter values are defined the image header keywords take
precedence.
.PP
The two parameters \fBdatamin\fP and \fBdatamax\fP which define the upper
and lower good data limits respectively are not currently implemented by
the APPHOT tasks.  They will be used in future versions of the package 
to, for example, set the limits over which a detector is linear.
.PP
After editing, the new \fBdatapars\fR pset might look like the following.
This user has chosen to wait and set \fBfwhmpsf\fR, \fBthreshold\fR,
\fBcthreshold\fR, and \fBsigma\fR interactively from inside \fBphot\fR but
has decided to set the
image header parameters \fBccdread\fR, \fBgain\fR and \fBexposure\fR.

.nf
\f(CW
                           IRAF
             Image Reduction and Analysis Facility

   PACKAGE = apphot
   TASK = datapars
   
   (fwhmpsf=                   1.) FWHM of the PSF in scale units
   (emissio=                  yes) Features are positive
   (noise  =              poisson) Noise model
   (thresho=                   0.) Detection threshold in counts above 
                                   background
   (cthresh=                   0.) Centering threshold in counts above
                                   background
   (sigma  =                INDEF) Standard deviation of background in counts
   (scale  =                   1.) Image scale in units per pixel
   (ccdread=              readout) CCD readout noise image header keyword
   (readnoi=                INDEF) CCD readout noise in electrons
   (gain   =                 gain) CCD gain image header keyword
   (epadu  =                   1.) Gain in electrons per count
   (exposur=              exptime) Exposure time image header keyword
   (itime  =                INDEF) Integration time
   (datamin=                INDEF) Minimum good data pixel
   (datamax=                INDEF) Maximum good data pixel
   (mode   =                   ql)
   ($nargs =                    0)
\fR
.fi

.NH 2
The Centering Parameters
.PP
The centering algorithm parameters have been grouped together in a single
parameter set \fBcenterpars\fR. To display and edit these parameters type
the command.

.nf
	\f(CWap> centerpars\fR
.fi

The following menu will appear on the terminal.

.nf
\f(CW
                              IRAF
               Image Reduction and Analysis Facility

   PACKAGE = apphot
   TASK = centerpars
   
   (calgori=             centroid) Centering algorithm
   (cbox   =                   5.) Centering box width in scale units 
   (maxshif=                   1.) Maximum center shift in scale units
   (minsnra=                   1.) Minimum SNR ratio for centering
   (cmaxite=                   10) Maximum iterations for centering algorithm
   (clean  =                   no) Symmetry clean before centering
   (rclean =                   1.) Cleaning radius in scale units
   (rclip  =                   2.) Clipping radius in scale units
   (kclean =                   3.) K-sigma rejection criterion in skysigma
   (mkcente=                   no) Mark the computed center
   (mode   =                   ql)
   ($nargs =                    0)
\fR   
.fi

.PP
APPHOT offers three choices for the  centering algorithm:
the default "centroid", "gauss" and "ofilter".
The default centering algorithm does not depend on \fBfwhmpsf\fR but the
remaining two do. For reasons of simplicity and efficiency the author
recommends the default algorithm. In cases where there is significant
crowding or the data is very noisy users may wish to experiment with
the other algorithms. Centering can be disabled by setting
\fBcalgorithm\fR = "none". This option is useful if accurate centers
have already been computed with the \fBdaofind\fR or \fBfitpsf\fR
tasks. More detailed information on the APPHOT centering algorithms
can be found in the document,  \fISpecifications for the Apphot Package\fR
by Lindsey Davis.
.PP
The centering box \fBcbox\fR is defined in units of \fBscale\fR.
Users  should try to set \fBcbox\fR as small as possible to avoid
adding noisy pixels to the centering subraster.
\fBCbox\fR can also be set interactively from inside the APPHOT \fBphot\fR
task.
.PP
If the computed centers are more than \fBmaxshift\fR / \fBscale\fR pixels
from the initial centers or the signal-to-noise ratio in the centering
subraster is less than \fBminsnratio\fR the new center will be computed but
flagged with a warning message.
.PP
For stars which are crowded or contaminated by bad pixels the user may
wish to enable the cleaning algorithm by setting \fBclean\fR = yes.
Its use is complicated and not recommended for most data.  The algorithm is
described in the APPHOT specifications document.
.PP
If \fBmkcenter\fR=yes,  \fBphot\fR tasks will mark the initial
and final centers and draw a line between them on the default display
device. At present this option only works if \fBdisplay\fR="stdgraph".
.PP
In the above example we have elected to leave the \fBcalgorithm\fR parameter
at its default value and set \fBcbox\fR interactively from inside the \fBphot\fR
task.


.NH 2
The Sky Fitting Parameters
.PP
The sky fitting algorithm parameters have been grouped together in a single
parameter set \fBfitskypars\fR. To display and edit these parameters type
the following command.

.nf
	\f(CWap> fitskypars\fR
.fi

The following menu will appear on the terminal.

.nf
\f(CW
                              IRAF
               Image Reduction and Analysis Facility

   PACKAGE = apphot
   TASK = fitskypars
   
   (salgori=                 mode) Sky fitting algorithm
   (annulus=                  10.) Inner radius of sky annulus in scale units
   (dannulu=                  10.) Width of sky annulus in scale units
   (skyvalu=                   0.) User sky value
   (smaxite=                   10) Maximum number of sky fitting iterations
   (snrejec=                   50) Maximum number of sky fitting rejection
                                   iterations
   (skrejec=                   3.) K-sigma rejection limit in sky sigma
   (khist  =                   3.) Half width of histogram in sky sigma
   (binsize=                  0.1) Binsize of histogram in sky sigma
   (smooth =                   no) Lucy smooth the histogram
   (rgrow  =                   0.) Region growing radius in scale units
   (mksky  =                   no) Mark sky annuli on the display
   (mode   =                   ql)
   ($nargs =                    0)
\fR
.fi

.PP
APPHOT offers ten sky fitting algorithms. The algorithms can be grouped
into 4 categories 1) user supplied sky values including "constant" and "file"
2) sky pixel distribution algorithms including "median" and "mode",
3) sky pixel histogram algorithms including "centroid", "crosscor",
"gauss" and "ofilter" 4) interactive algorithms including "radplot"
and "histplot".
The definitions of the mode used by APPHOT is the following.

.nf
\f(CW	mode = 3.0 * median - 2.0 * mean\fP
.fi

Detailed descriptions of the algorithms can be found in the document,
\fISpecifications for the Apphot Package\fR by the author. The author recommends
"mode" the default, and one of the two histogram algorithms "centroid" and
"crosscor".
.PP
The inner radius and width of the sky annulus in terms of \fBscale\fR
are set by the parameters \fBannulus\fR and \fBdannulus\fR. These can
easily be set interactively from within the \fBphot\fR task.
Good statistics require several hundred sky pixels.
The user should be aware that a circular sky region can be defined by
setting \fBannulus\fR to 0.
.PP
The user should ensure that the parameter \fBsigma\fR in the
\fBdatapars\fR parameter set is defined if one of the histogram dependent
sky fitting algorithms is selected.
The extent and resolution of the sky pixel histogram is determined
by \fBkhist\fR and \fBbinsize\fR and their relation to \fBsigma\fR.
If \fBsigma\fR is undefined then the standard deviation of the local
sky background is used to parameterise \fBkhist\fR and \fBbinsize\fR
and the histograms of different stars can deviate widely in resolution.
.PP
The sky rejection algorithms are controlled by the parameters \fBskreject\fR,
\fBsnreject\fR and \fBrgrow\fR. It is strongly recommended that the user
leave pixel rejection enabled. The user should experiment with the region
growing radius if the local sky regions are severely crowded.
.PP
If \fBmksky\fR = yes, \fBphot\fR will mark the inner
and outer sky annuli. At present this option
will only work if \fBdisplay\fR = "stdgraph".

.NH 2
The Photometry Parameters
.PP
The photometry algorithm parameters have been grouped together in a single
parameter set \fBphotpars\fR. To display and edit these parameters type.

.nf
	\f(CWap> photpars\fR
.fi

The following menu will appear on the terminal.

.nf
\f(CW
                              IRAF
               Image Reduction and Analysis Facility

   PACKAGE = apphot
   TASK = photpars
   
   (weighti=             constant) Photometric weighting scheme for wphot
   (apertur=                   3.) List of aperture radii in scale units
   (zmag   =                  26.) Zero point of magnitude scale
   (mkapert=                   no) Draw apertures on the display
   (mode   =                   ql)
   ($nargs =                    0)
\fR
.fi

.PP
There are three weighting options inside APPHOT. The default is "constant".
Inside the \fBphot\fR, \fBradprof\fR and \fBpolyphot\fR tasks only constant
weighting is used. Two other weighting schemes are available for the
experimental \fBwphot\fR task, "gauss" and "cone". "Gauss" is the more
highly recommended.
.PP
The aperture list is specified by \fBapert\fR in terms of \fBscale\fR.
The apertures can be entered in any order but are sorted on output.
\fBApert\fR can be string or the name of a text file containing the
list of apertures. Apertures can either be listed individually and
separated by whitespace or commas or a ranges notation of the
form apstart:apend:apstep can be used.
These can be set interactively from within the \fBphot\fR task.
.PP
Examples of valid aperture strings are listed below.

.nf
\f(CW
	1 2 3
	1.0,2.0,3.0
	1:10:1
\fR
.fi

.PP
An arbitrary zero point is applied to the magnitude scale with \fBzmag\fR.
The user can accept the default or experiment with his/her data until
a suitable value is found. The computation of the magnitude errors
does not depend on the zero point.
.PP
If \fBmkapert\fR = yes, the \fBphot\fR task will draw the concentric
apertures on the display.  At present this option
works only if \fBdisplay\fR = "stdgraph".

.NH 2
The QPHOT Task
.PP
\fBQphot\fP computes accurate centers, sky values and magnitudes for a list
of objects using a restricted subset of the full \fBphot\fP parameter set.
It is intended to be a quick look photometer suitable for use when 
observing on the mountain or in well behaved uncrowded stellar fields.
.PP
The user is automatically queried for the critical parameters \fBcbox\fP,
\fBannulus\fP, \fBdannulus\fP and \fBapertures\fP which are defined in
terms of pixels.  The noise characteristics of the detector are assumed
to obey Poisson statistics.  \fBQphot\fP computes centers for each
object using the "centroid" centering algorithm.  Sky values are
calculated using the "mode" algorithm.  The user can set the zero point
of the magnitude scale, \fBzmag\fP, the gain of the detector, \fBepadu\fP,
and exposure time image header keyword, \fBexposure\fP, but all the
remaining parameters are set to their default values.
.PP
\fBQphot\fP can be driven by the image cursor or a coordinate list in
interactive mode or by a coordinate list in batch mode in exactly 
the same manner as the \fBphot\fP task.

.NH 2
The \fBPOLYPHOT\fP Task
.PP
\fBPolyphot\fP computes accurate centers, sky values and magnitudes for
a list of objects using polygonal shaped apertures.  It is most suitable
for measuring the magnitudes of large extended irregularly shaped objects.
.PP
\fBPolyphot\fP uses \fBdatapars\fP, \fBcenterpars\fP, and
\fBfitskypars\fP in exactly the same manner as the \fBphot\fP task.  In
general users should set the task parameters in the same way as they
set them in \fBphot\fP.  However users who have defined their polygonal
apertures interactively may wish to set the centering algorithm
parameter \fBcalgorithm =\fP "none", to avoid the task trying to center
on the brightest feature in the aperture.
.PP
The apertures are defined either interactively with the image or graphics
cursor or by two files \fBpolygons\fP and \fBcoords\fP.
Polygons defines the shape of the polygonal aperture and coords defines the
initial positions of the apertures.  The polygons file may contain
more than one aperture and the flux through each aperture may be measured
at more than one position.  A detailed description of the file formats
is given in section 6.4

.NH
Creating A Coordinate List
.PP
All APPHOT tasks operate on either lists of object coordinates or
interactive cursor
input. Lists are maintained as text files, one object per line with the x
and y coordinates in columns one and two respectively. The coordinate and
polygon files required by the \fBpolyphot\fR task have a different
format which is described below. List files may be
created interactively with either the graphics or the image cursor, by a
previously executed APPHOT task, by a previously executed IRAF task or by
a user program. Various means of creating coordinate lists within IRAF
are described below. Comments preceded by a # character and blank lines
are ignored.

.nf
\f(CW
                     #Sample Coordinate List
                        53.6    83.25
                        100.0   35.8
                        2.134   86.89
                        ....    ....
\fR
.fi

.NH 2
Daofind
.PP
\fBDaofind\fR is an APPHOT task which detects stellar objects in an image 
automatically. The user sets the \fBfwhmpsf\fR of the psf for which the
detection algorithm is to be
optimized as well as an intensity threshold for detection. \fBDaofind\fR
locates all the qualifying stars  and writes their positions, rough magnitudes
and shape characteristics to a file. This file can then be assigned to
the \fBphot\fR task \fBcoords\fR parameter and read directly.
.PP
For example if we have an image containing stars for which the \fBfwhmpsf\fR
is 4.0 pixels and the sigma of the sky background is 10 we might run
\fBdaofind\fR as follows,

.nf
	\f(CWcl> daofind image fwhmpsf=4.0 threshold=30.0\fR
.fi

where we have set our detection threshold at 3.0 * sigma.

.NH 2
Imtool On the SUN Machines
.PP
The SUN IRAF \fBimtool\fR facility supports both image world coordinate
systems and output coordinate files.  Coordinate lists can be created
interactively by the users in the following way.
.PP
Display the IRAF image in the imtool window using the \fBdisplay\fR task.
Move the mouse to the top of the \fBimtool\fR window, press the right mouse
button to enter the \fBimtool\fR menu, move the mouse to the setup option and
release the mouse button. Press
the return key until the black triangle is opposite the coordinate list file
name parameter.
Delete the default file name, enter the full host system path name of the 
desired coordinate file and press return. This name should now appear at
the top of the imtool window.
Move the mouse to the quit option and press the left mouse button to
quit the setup window.
.PP
To enter the \fBimtool\fR cursor readout mode type the \fBF6\fR key.
The x, y and intensity values at the cursor position
are displayed in the lower right corner of the image.
To mark stars and output their coordinates to the coordinate file, move
the image cursor a star and press the left mouse button. A sequence number
will appear on the display next to the marked position. The numbers can
be changed from black to white and vice versa by toggling the \fBF5\fR key.
The coordinate files are opened in append mode in order that stars may be
added to an already existing list. \fBImtool\fR coordinate files are directly
readable by all APPHOT tasks.

.NH 2
Rgcursor and Rimcursor
.PP
The LISTS package tasks \fBrgcursor\fR and \fBrimcursor\fR can be used to
generate coordinate lists interactively. For example a coordinate
list can be created interactively using the display cursor and
the image display.

.nf
\f(CW
	cl> display image

	... image appears on the display ...

	cl> rimcursor > image.coo

	... move display cursor to stars of interest and tape space bar ...

	... type ^Z to terminate the list ...
\fR
.fi

Similarly a coordinate list
can be created using the graphics cursor and a contour
plot as shown below.

.nf
\f(CW
	cl> contour image

	... contour plot appears on the terminal ...

	cl> rgcursor > image.coo

	... move cursor to stars of interest and tap space bar ...

	... type ^Z to terminate the list ...
\fR
.fi

The text file "image.coo" contains the x and y coordinates of the marked stars
in image pixel units. The output of \fBrimcursor\fR or  \fBrgcursor\fR can
be read directly by the APPHOT \fBphot\fR task.
\fBRimcursor\fR is only available in IRAF versions 2.7 and later and
only for selected devices.

.NH 2
The Polygon List
.PP
A utility routine \fBpolymark\fR has been added to the APPHOT package to
generate polygon and initial center lists for the \fBpolyphot\fR task.
The format of the polygon files is 1 vertex per line with the 
x and y coordinates of the vertex in columns 1 and 2 respectively.
A line containing the single character ';' terminates the lists of vertices.
There can be more than one polygon in a single polygon file.

.nf
\f(CW
            Sample Polygon File

                1.0   1.0
                1.0   51.0
                51.0  51.0
                51.0  1.0
                ;
                80.0  80.0
                80.0  131.0
                131.0 131.0
                131.0 80.0
                ;
\fR
.fi

.PP
The accompanying coordinate file is optional. If no coordinate file is given
the initial center for the polygon is the mean of its vertices in the 
polygon file. If a
coordinate file is specified the initial center for the polygon is the
position in the coordinate file. Each polygonal aperture may be moved
to several positions.

.nf
\f(CW
       Sample Polyphot Coords File

               50. 30.
               80. 100.
               60. 33.
               ;
               90. 50.
               55. 90.
               12. 122.
               ;
\fR
.fi

For example all the coordinates in group 1 will be measured using the
aperture defined by polygon 1 and all the coordinates
in group 2 will be measured with the aperture defined by polygon 2.

.NH 2
User Program
.PP
Obviously any user program which produces a text file with the coordinates
listed 1 per line with x and y in columns 1 and 2 can be used to produce
APPHOT coordinate files.

.NH 2
Modifying an Existing Coordinate List
.PP
The LISTS package routine \fBlintran\fR has been linked into the APPHOT
package. It can be used to perform simple coordinate transformations on
coordinate lists including shifts, magnifications, and rotations.

.NH
Running Apphot in Interactive Mode Without a Coordinate List
.PP
There are currently three ways to run the \fBphot\fR interactively without
a coordinate list:
1) read image display cursor commands 2) read 
graphics cursor commands 3) read commands
from the standard input. The three methods are briefly discussed below.
Detailed examples of all three methods of operation can be found in
the manual pages for each task.

.NH 2
Reading Image Cursor Commands
.PP
The default method of running APPHOT. The user loads an image onto
the display, types \fBphot\fR and enters the image name. The image cursor
appears on the display and the program is ready to accept user commands.
This option is not available under IRAF version 2.6 and earlier
because interactive image cursor readback was not available.

.NH 2
Redirecting the Image Cursor to the Graphics Cursor
.PP
\fBPhot\fR reads the graphics cursor and executes various keystroke
commands. The environment variable \fBstdimcur\fR must be set to "stdgraph".
For full access
to all the graphics commands the parameter \fBdisplay\fR must also be set
to "stdgraph".
The user creates a contour plot of the image on the graphics terminal
with the \fBcontour\fR task, types \fBphot\fR and answers the image name query.
The graphics cursor appears on the contour plot ready for input.
The user can move around the plot with the cursor successively marking stars.

.NH 2
Redirecting the Image Cursor to the Standard Input
.PP
The user can enter cursor commands directly on the standard input.
The environment variable \fBstdimcur\fR must be set to "text".
When the user types the task name \fBphot\fR and enters the image
name, the following prompt appears.

.nf
	\f(CWImage cursor [xcoord ycoord wcs] key [cmd]:\fR
.fi

\fIXcoord\fR and \fIycoord\fR are the coordinates of the object of
interest, \fIwcs\fR is the current world coordinate system, always 1,
\fIkey\fR is a single
character and \fIcmd\fR is an APPHOT task command.
To perform the default action of
the \fBphot\fR task the user responds as follows.

.nf
	\f(CWImage cursor [xcoord ycoord wcs] key [cmd]: 36. 42. 1\fR
.fi

\fBPhot\fR measures the magnitude of the star near pixel coordinates
x,y = (36.,42.) and writes the result to the output file.
In IRAF version 2.5 all the cursor command fields must be typed.
The square brackets
indicate those fields which are optional under IRAF version 2.6 and later.
Users with SUN
workstations may wish to combine the IMTOOL coordinate list cursor readback
facilities which generate coordinate lists  with this mode of running APPHOT
interactively.

.NH 2
The Interactive Keystroke Commands
.PP
A conscious effort has been made to keep the definitions of all the
keystroke commands within the APPHOT package as similar as possible.
The following are the most commonly used  keystrokes in the APPHOT package.

.NH 3
The ? (Help) Keystroke Command
.PP
The ? key prints the help page describing the cursor keystroke and colon
show commands for the specific APPHOT task. An abbreviated help page
is typed by default when a user enters a task in interactive mode.
The ? key can be typed at any point in the APPHOT task.

.NH 3
The :show (Set and Print parameter)  Commands
.PP
Any APPHOT parameter can be displayed by typing :\fIparameter\fR command
in interactive mode.
For example to show the current value of the \fBfwhmpsf\fR parameter
type the following command.

.nf
	\f(CW:fwhmpsf\fR
.fi

To set any APPHOT parameter type :\fIparameter\fR "value". For example
to set the \fBfwhmpsf\fR to 2.0 type.

.nf
	\f(CW:fwhmpsf 2.0\fR
.fi

To display all the centering parameters type.

.nf
	\f(CW:show center\fR
.fi

Similarly the sky fitting and photometry parameters can be displayed by
typing. 

.nf
	\f(CW:show sky\fR
	\f(CW:show phot\fR
.fi

All the parameters can be displayed with the following command.

.nf
	\f(CW:show\fR
.fi

.NH 3
The i (Interactive Setup) Keystroke Command
.PP
This extremely useful key allows one to set up the principal APPHOT
parameters interactively. To use this feature move the image cursor to a star on
the display, or move the graphics cursor to a star on the contour plot
and tap the i key,
or enter the x and y  coordinates, and the world coordinate system
of the star and the i key manually. The program will query the user for
the size of the extraction box and plot a radial profile of the star
on the terminal. The user sets the \fBfwhmpsf\fR, the centering
aperture \fBcbox\fR, the inner sky annulus \fBannulus\fR and \fBdannulus\fR,
the list of apertures \fBaperts\fR and the data \fBsigma\fR,
\fBthreshold\fR and \fBcthreshold\fR using the graphics cursor and the
radial profile plot.
The cursor comes up on the plot at the position of the appropriate parameter.
Typing return will preserve the old value.
If the cursor is outside the range of values on the plot the old value
is kept.
.PP
Setting \fBsigma\fP, \fBcthreshold\fP, and \fBthreshold\fP 
interactively requires two keystrokes.  In each case the measured parameter
is the difference between the two y coordinates of the graphics
cursor. It is recommended in general that the user leave \fBcthreshold\fP
at zero.

.NH 3
The v (Verify) Keystroke Command
.PP
The v key verifies that the values of the critical task parameters 
currently in memory are the ones that the user wants.  To each verify query
the user either types CR to verify the current value or enters a new
value.

.NH 3
The w (Write to Psets) Keystroke Command
.PP
The w key writes the current values of the parameters in memory to the
appropriate psets.
This feature is useful for saving values marked with the
i key. On exiting APPHOT a prompt will remind the user that the current
parameters in memory must be stored in the psets or lost.

.NH 3
The d (Radial Profile Plot) Keystroke Command
.PP
The d key plots a centered radial profile of a star on the graphics device.

.NH 3
The f (Fit) Keystroke Command
.PP
This key performs the default action of each APPHOT task without writing
any results
to the output file. In the \fBphot\fR task the f key will center, fit the
local sky and compute the magnitudes for a star. This key allows the user to
experiment interactively with the data, changing the default parameters,
remeasuring magnitudes and so on before actually writing out any data.

.NH 3
The Space Bar (Fit and Write out Results) Keystroke Command
.PP
This key performs the default action of the task and writes the results
to the output catalog.

.NH
Running Apphot In Interactive Mode From A Coordinate List
.PP
This is currently the best method for running APPHOT interactively for users
without image cursor readback facilities. APPHOT tasks
can pick stars out of the list sequentially or by number,  measure stars
sequentially or by number, rewind the coordinate lists and remeasure all
the stars. Stars which are not in the coordinate list can still be
measured and added to the output catalog.

.IP [1] 
The :m (Move) Keystroke Command
.RS
.LP
This command moves the cursor to the next or a specified star in the
coordinate list.  If the hardware cursor on the
device being read from is enabled the actual physical cursor will move
to the requested star. For
example a user might decide that star # 10 in the coordinate list is the best
setup star. He/she simply types a :m 10 to move to the star in
question followed by the i key to setup the parameters interactively.
.RE

.IP [2]
The :n (Next)  Keystroke Command
.RS
.LP
This command moves to the next or specified star in the list, performs the
default action of the task and writes the results to the output file.
This key is particularly useful in examining the results of a large batch
run.
For example, a user measures the magnitudes of 500 stars using APPHOT in
batch mode.  He/she is suspicious about the results for twenty of the most
crowded stars. By rerunning APPHOT in interactive mode using the original
coordinate list, the user can selectively call up the stars in question,
plot their radial profiles, and examine the results interactively.
.RE

.IP [3]
The l (List) Keystroke Command
.RS
.LP
This command measures all the stars in the coordinate list sequentially from
the current position in the file.
.RE

.IP [4]
The r (Rewind) Keystroke Command
.RS
.LP
This command rewinds the coordinate list.
.RE

.NH
Running Apphot in Batch Mode
.PP
This is the simplest way to run APPHOT. Once the parameters are set and stored
in the pset files the program can be run in batch by setting the parameter
\fBinteractive\fR = no. The program will read the coordinate list
sequentially computing results for each star and writing them to the
output file.

.NH
Apphot Output
.PP
APPHOT tasks write their output to text and/or plot files as well as to the
standard output and graphics terminals.

.NH 2
Text Files
.PP
All APPHOT records are written to text files.
The parameters for the task are listed at the beginning of each APPHOT
output text file and identified with a #K string.
The header record is not written until the record
for the first star is to be written to the database. Parameter changes  will
generate a one line entry in the output text file.
The data records follow the header record in the order in which they
were computed.
If the output file parameter \fBoutput\fR = "" no output file is written.
This is  the default action for the \fBradprof\fR task.
If \fBoutput\fR = "default",
the output file name is constructed using the image name.

.NH 2
Plot Files
.PP
Some APPHOT tasks can optionally produce graphics output.
These files are maintained as plot metacode and may contain many individual
plots.
A directory of plots in each metacode file can be obtained with
\fBgkidir\fR. Individual plots can be extracted with \fBgkiextract\fR and
combined and plotted with \fBgkimosaic\fR.  

.NH 2
Running Apselect on Apphot Output Files 
.PP
Individual fields can be extracted from the APPHOT output files using
the \fBapselect\fR task and a keyword and expression scheme.
For example the user may wish
to extract the x and y center coordinates, the sky value and the
magnitudes from the APPHOT \fBphot\fR catalog. Using apselect they
would type.

.nf
	\f(CWcl> apselect output xc,yc,msky,mag yes > magsfile\fR
.fi

The selected fields would appear in the textfile "magsfile".

.NH
Apphot Recipes
.PP
In the following section three APPHOT reduction sessions which illustrate
different methods of using the APPHOT package are described. In the
first example the user wishes to compute magnitudes for a large number
of stars in a single image. In the second example he/she wishes to
measure the magnitude of a single standard star in each of a long list of
images. Finally in the last example the user wishes to measure the
magnitude of an elliptical galaxy through a list of apertures.
Each example assumes that the user has started with the default set of
package parameters.

.NH 2
Infrared photometry of a Star Field in Orion
.PP
An observer has an IRAF image on disk of a star forming region in Orion taken
with the
IR CCD camera. The Orion image is a composite formed from 64 separate
IR images using the PROTO \fBirmosaic\fR and \fBiralign\fR tasks.
The Orion image contains about 400 stars but is only moderately crowded. The
observer decides to use the APPHOT package to reduce his data.
.PP
The observer decides to run the \fBdaofind\fR routines to create a coordinate
list of stars, to run \fBphot\fR in interactive mode with the image cursor
directed to the standard input to setup and store the \fBphot\fR task
parameters and finally, to run \fBphot\fR in batch mode to do the photometry.
.PP
To create the coordinate list the user needs to supply the full width half
maximum of the pointspread function and an intensity threshold
above background to the
\fBdaofind\fR program. Using the PLOT package task \fBimplot\fR the user
examines several stars in the image and decides that the \fBfwhmpsf\fR
should be 3.0
pixels and that the standard deviation of the background should be 10.0
counts.
The user decides to include all stars with a peak intensity greater
than five standard deviations above local background in the coordinate list.
The user runs \fBdaofind\fR as follows.

.nf
	\f(CWap> daofind orion fwhmpsf=3.0 threshold=50.0\fR
.fi

The x and y coordinates, a magnitude estimate and some statistics on image
sharpness and roundness are output to the file "orion.coo.1".
The user can obtain a printout of the coordinate
list by typing.

.nf
	\f(CWap> lprint orion.coo.1\fR
.fi

.PP
Next the user decides to set up the parameters of the \fBphot\fR task.
Using the \fBepar\fR task he enters the phot task parameter menu,
types "orion" opposite the \fBimage\fR parameter and "orion.coo.1"
opposite the \fBcoords\fR parameter. Next he moves the cursor opposite
the \fBdatapars\fR parameter and types \fB:e\fR to enter the \fBdatapars\fR
menu. He sets the gain parameter \fBepadu\fR to 5.0 electrons per adu
and the readout noise \fBreadnoise\fR to 5.0 electrons. He types \fB:q\fR to
quit and save the \fBdatapars\fR parameters and \fB^Z\fR to quit and save the
\fBphot\fR parameters.
.PP
Now the user is ready to enter the \fBphot\fR task in interactive mode to set
up the remaining data dependent parameters. The user types  the following
sequence of commands in response to the cursor prompt. Note that the
example below assumes that the image cursor has been directed to the
standard input. The image cursor comes up on the screen in the form of
a prompt. This example could equally well be run from the image hardware
cursor in which case the cursor would appear on the displayed image. The
keystroke commands are identical in the two cases.

.br

.nf
\f(CW
	ap> phot orion

	... \fIload the phot task\fR ...

	Image cursor [xcoord ycoord wcs] key [cmd]: ?

	... \fIprint help page for phot task\fR ...

	Image cursor [xcoord ycoord wcs] key [cmd]: :radplots yes

	... \fIenable radial profile plotting\fR ...

	Image cursor [xcoord ycoord wcs] key [cmd]: :m 10

	... \fImove to star 10 in the coordinate list\fR ...

	Image cursor [xcoord ycoord wcs] key [cmd]: i

	... \fIenter interactive setup mode using star 10\fR ...

	... \fImark fwhmpsf, cbox, sky annulus, apertures on the plot\fR ...

        ... \fIleave sigma and cthreshold at their default values\fR ...

	... \fIcheck answers on radial profile plot of the results\fR ...

	Image cursor [xcoord ycoord wcs] key [cmd]: v

        ... \fIverify the critical parameters\fR ...

	Image cursor [xcoord ycoord wcs] key [cmd]: :radplots no

	... \fIdisable radial profile plotting\fR ...

	Image cursor [xcoord ycoord wcs] key [cmd]: w

	... \fIstore new parameters in the psets\fR ...

	Image cursor [xcoord ycoord wcs] key [cmd]: q

	... \fIquit interactive cursor loop\fR ...

	q

	... \fIquit the phot task\fR ...

\fR
.fi
.PP
The user decides he is happy with the current parameter set and decides
to run the \fBphot\fR task in batch and submit it as a background task.

.nf
	\f(CWap> phot orion inter- verify- &\fR
.fi

The results will appear in the text file "orion.mag.1".

.NH 2
Landolt Standards 
.PP
The user has 100 UBVRI images of 20 Landolt Standards
taken on a single night. These frames have been taken at various short
exposures.
The user wishes to process all this data
in batch mode with the output records going to a single file.
.PP
The observer decides to run the \fBdaofind\fR task to create a coordinate
list for each image, to run \fBphot\fR on a representative image
in interactive mode with the image cursor
directed to the standard input to set up and store the \fBphot\fR task
parameters, and finally to run \fBphot\fR in batch mode on all the images
to do the photometry.
.PP
Note that the example below assumes that the image cursor has been redirected
to the standard input.  The image cursor comes up on the screen in the
form of a prompt.  This example could equally well be run from the image 
hardware cursor in which case the cursor would appear on the displayed
image.  The keystroke commands are identical in the two cases.
.PP
To create the coordinate list the user needs to supply the full width half
maximum of the point spread function and an intensity threshold above
local background to the
\fBdaofind\fR task. Using the PLOT package task \fBimplot\fR the user
examines the Landolt standards in several images and decides that the
average \fBfwhmpsf\fR is 4.3
pixels and that the standard deviation of the background is 15.0 counts.
Note that if the user has access to an image display \fBfwhmpsf\fP and
\fBthreshold\fP can be determined interactively from inside the
daofind task itself.
The user decides to include all stars with a peak intensity greater
than five standard deviations above local background in the coordinate list,
which should include weak and spurious objects.
The user runs \fBdaofind\fR as follows.

.nf
	\f(CWap> daofind lan*.imh fwhmpsf=4.3 threshold=75.0 verify- &\fP
.fi

The x and y coordinates, an initial guess at the magnitude and some
sharpness and roundness characteristics are output to the files "lan*.coo.1".
For example the image lan100350.imh will now have a corresponding 
coordinate file lan100350.coo;1. The user may wish at this point
to quickly check the coordinate files for spurious objects.
.PP
Next the user decides to set up the parameters of the phot task.
Using the \fBepar\fR task he enters the phot task parameter set,
enters "lan100350b" opposite the \fBimage\fR parameter and "lan100350b.coo.1"
opposite the \fBcoords\fR parameter. Next he moves the cursor opposite
the \fBdatapars\fR parameter and types \fB:e\fR to enter the \fBdatapars\fR
menu. He sets the gain parameter \fBepadu\fR to 10 electrons per adu
and the readout noise \fBreadnoise\fR to 50.0 electrons. 
Finally in order to normalize all the magnitudes the user enters
the image header exposure time keyword "itime" opposite the
\fBexposure\fP parameter.  He types \fB:q\fR to
quit and save the \fBdatapars\fR parameters and \fB^Z\fR to quit and save the
\fBphot\fR parameters.
.PP
Now the user is ready to enter the \fBphot\fR task in interactive mode to set
up the remaining data dependent parameters. The user types  the following
sequence of commands in response to the cursor prompt.

.nf
\f(CW
	ap> phot lan100350.imh

	... \fIload the phot task\fR ...

	Image cursor [xcoord ycoord wcs] key [cmd]: ?

	... \fIprint help page for phot task\fR ...

	Image cursor [xcoord ycoord wcs] key [cmd]: :radplots yes

	... \fIenable radial profile plotting\fR ...

	Image cursor [xcoord ycoord wcs] key [cmd]: :m #n

	... \fImove to star n in the coordinate list\fR ...

	Image cursor [xcoord ycoord wcs] key [cmd]: i

	... \fIenter interactive setup mode using star n\fR ...

	... \fImark fwhmpsf, cbox, sky annulus, apertures on the plot\fR ...

        ... \fIleave sigma and cthreshold at their default values\fR ...

	... \fIcheck answers on radial profile plot of the results\fR ...

	Image cursor [xcoord ycoord wcs] key [cmd]: v

        ... \fIverify the critical parameters\fR ...

	Image cursor [xcoord ycoord wcs] key [cmd]: :radplots no

	... \fIdisable radial profile plotting\fR ...

	Image cursor [xcoord ycoord wcs] key [cmd]: w

	... \fIstore new parameters in the psets\fR ...

	Image cursor [xcoord ycoord wcs] key [cmd]: q

	... \fIquit interactive cursor loop\fR ...

	q

	... \fIquit the phot task\fR ...

\fR
.fi
.PP
Finally the user runs the \fBphot\fR task on the full list of images,
with their corresponding parameter sets and dumps the output to a single
text file named "output".

.nf
	\f(CWap> phot lan*.imh coords="lan*.coo.*" output=output veri- inter- &\fR
.fi

The results will appear in the text file "output".

.NH 2
Aperture Photometry of an Elliptical Galaxy
.PP
The user has a single image of the elliptical galaxy N315. She
wishes to measure the magnitude of this galaxy through a list of apertures
equal to those published in a well known catalogue of photoelectric photometry.
Her data has been sky subtracted to give an average background value of 0.0
and the standard deviation of the sky background is 20.0 counts.
From the published aperture photometry
and the scale of her telescope she knows that she wishes to measure
the galaxy through aperture radii of 10.5, 15.2, 20.8, and 25.6 arc seconds.
.PP
The user wishes to work in interactive mode using a contour plot
of the image and the graphics cursor to enter commands to the \fBphot\fR
task. She therefore sets the image cursor to "stdgraph" as follows.

.nf
	\f(CWap> set stdimcur = stdgraph\fR
.fi

.PP
Next she makes a contour plot of the image and  writes it to
a plot metacode file as follows.

.nf
\f(CW
	ap> contour N315 

	... \fIcontour plot appears on the terminal\fR ...

	ap> =gcur

	... \fIenter cursor mode\fR ...

	:.write n315.plot

	... \fIwrite the plot to a file\fR ...

	q

	... \fIexit cursor mode\fR ...

\fR
.fi
.PP
Now the user is ready to set up the parameters of the \fBphot\fR task.
Since she already knows the values of the parameters she wishes to use
she types

.nf
	\f(CWap> epar phot\fR
.fi

to enter the phot task menu. She positions the cursor opposite
\fBimage\fR parameter and types "N315", opposite \fBdispay\fR and
types "stdgraph".
Next she moves the cursor opposite
the \fBdatapars\fR parameter and types \fB:e\fR to enter the \fBdatapars\fR
menu. She makes sure that \fBscale =\fP 0.75 arc-seconds per pixel the scale
of the telescope, sets the standard deviation
of the sky background \fBsigma\fR to 20.0, sets the gain
parameter \fBepadu\fR to 5 electrons per adu
and the readout noise \fBreadnoise\fR to 5.0 electrons. She types \fB:q\fR to
quit and save the \fBdatapars\fR parameters. She decides to leave the
centering parameters in \fBcenterpars\fR at their default values.
\fBCbox\fP in particular will be 5.0 arcseconds wide.  The user
has already removed a low order polynomial sky background from this image.
She wishes to fix the sky value at 0.0. She moves the cursor opposite
the \fBfitskypars\fR parameter and types \fB:e\fR to enter the sky fitting menu.
She types "constant" opposite the \fBsalgorithm\fR parameter, "0.0"
opposite the \fBskyvalue\fR parameter and \fB:e\fR to exit
the sky fitting parameter menu. Finally she enters the \fBphotpars\fR
menu and enters the aperture string "10.5,15.2,20.8,25.6" opposite
the \fBapert\fR parameter. 
.PP
To measure the galaxy she types

.nf
	\f(CWap> phot N315\fR
.fi

to enter the phot task, positions the cursor on the center of the
galaxy in the contour plot and taps the space bar to make the measurement.
The results are  written to the file "N315.mag.1".