Initial commit

1 files changed, 1071 insertions, 0 deletions

diff --git a/noao/digiphot/apphot/doc/specs/Ap.doc b/noao/digiphot/apphot/doc/specs/Ap.doc
new file mode 100644
index 00000000..66744d58
--- /dev/null
+++ b/noao/digiphot/apphot/doc/specs/Ap.doc
@@ -0,0 +1,1071 @@
+APPHOT (Aug83)    Digital Aperture Photometry Package     APPHOT (Aug83)
+
+
+
+1. Introduction
+
+    The  APPHOT  package  will  provide a set of routines for performing
+aperture photometry  on  uncrowded  or  moderately  crowded  fields,  in
+either  interactive  or  batch  mode.   The  basic  photometry technique
+employed  shall  be  fractional-pixel  aperture  integration;   no   PSF 
+fitting  techniques  shall  be  employed,  and  no  knowledge of the PSF
+shall be required.  This document presents the formal  requirements  and
+specifications  for  the  package,  and  describes  the algorithms to be
+used.
+
+
+
+2. Requirements
+
+    (1) The program shall take as input an IRAF imagefile  containing  a
+        starfield  which  has  been  corrected  for  pixel to pixel gain
+        variations,  high  frequency  fluctuations  in  the  background, 
+        nonlinearity,  and  any other instrumental defects affecting the
+        intensity value of a pixel.
+
+    (2) Given as input the approximate coordinates of  a  single  object
+        in   the   image,   the  program  shall  perform  the  following 
+        operations:
+
+            o   Determine a constant background  value  by  analysis  of
+                an   annular   region   surrounding   the  object.   The 
+                background is assumed to be flat in the  region  of  the
+                object,   but   may  contain  contaminating  objects  or 
+                defects which shall be detected and  eliminated  by  the
+                fitting  algorithm.   It  shall  be  permissible for the
+                background region to extend  beyond  the  boundaries  of
+                the  image;  the  out  of  bounds  region of the annulus
+                shall be excluded from the fit.
+
+            o   Determine  the  center  of  the   object,   taking   the 
+                approximate  object  coordinates  given  as  input  as a
+                starting  point.   The  center  determination  shall  be 
+                resistant   to   the  affects  of  nearby  contaminating 
+                objects.  The centering algorithm may  assume  that  the
+                object  is  circularly symmetric, or nearly so, and that
+                the object flux is positive.
+
+            o   Determine  the  integral  of  object  minus   background 
+                within  one  or  more  circular  apertures centered upon
+                the object.  The integration shall  be  performed  using
+                partial  pixel  techniques,  to  minimize the effects of
+                sampling.   If  the  aperture  contains  any  indefinite 
+                pixels,  or  if the aperture extends beyond the boundary
+                of the image, an indefinite result shall be returned.
+
+    (3) The  following  options  shall  be  provided   to   modify   the 
+        operation of the above functions:
+
+
+                                  -1-
+APPHOT (Aug83)    Digital Aperture Photometry Package     APPHOT (Aug83)
+
+
+
+            o   Use  a  user  supplied  constant  background  value  and 
+                background  noise  estimate  instead  of   fitting   the 
+                background.
+
+            o   Use  the  starting  center  as  the actual center in all
+                cases.
+
+            o   Use the starting center as  the  actual  center  if  the
+                object  is  very  faint,  but tweak up the center if the
+                signal to noise is above a certain threshold.
+
+            o   Allow the object aperture to  extend  beyond  the  image
+                boundary,  using  only  that  portion  of  the  aperture 
+                which  is  in  bounds  when   computing   the   aperture 
+                integral.
+
+    (4) At  a  minimum, the following parameters shall be calculated and
+        output for each object:
+
+            o   The coordinates of the object, and the  estimated  error
+                in these coordinates.
+
+            o   The  mode  and standard deviation of the background; the
+                number of pixels left in  the  background  region  after
+                pixel rejection.
+
+            o   The  magnitude  of  the  object,  to  within an arbitary
+                zero-point,  and  the  statistical  uncertainty  of  the 
+                magnitude.   If  multiple concentric apertures are used,
+                a magnitude and uncertainty shall be given for each.
+
+    (5) The program shall be usable  both  interactively  and  in  batch
+        mode.   In  interactive  use, the user shall be able to mark the
+        positions of the objects by interactively positioning  a  cursor
+        on  a  2-dim  display device.  It shall be possible to enter the
+        control parameters for the analysis routines  interactively  for
+        each  object.   In  batch  mode, the control parameters shall be
+        fixed, and  object  coordinates  shall  be  taken  from  a  user
+        supplied  list.   The  display  device  shall not be required in
+        batch mode.
+
+    (6) The APPHOT package shall be  written  in  the  SPP  language  in
+        conformance  with  the  standards  and conventions of IRAF.  The
+        code shall be portable and device independent.
+
+
+
+2.1 Summary of the Limitations of APPHOT
+
+    The  APPHOT  package  is  designed  to   perform   simple   aperture 
+photometry subject to the following restrictions:
+
+    (1) Objects   must   be  circular  or  nearly  circular,  since  the 
+
+
+                                  -2-
+APPHOT (Aug83)    Digital Aperture Photometry Package     APPHOT (Aug83)
+
+
+
+        aperture is circular.
+
+    (2) All pixels within the  object  aperture  are  weighted  equally.
+        All  pixels  in  the object aperture must be present; the object
+        aperture may not normally extend outside the  image.   Defective
+        pixels within the object aperture may not be detected.
+
+    (3) The  background  must  be approximately flat in the neighborhood
+        of the object  being  measured.   The  background  must  have  a
+        unique  mode,  or the background fitting routine will reject the
+        object.   Any  low  frequency  fluctuations  in  the  background 
+        should be removed before using APPHOT.
+
+    (4) The   object  aperture  must  be  kept  small  to  minimize  the 
+        degradation of signal to noise caused by sky pixels  within  the
+        aperture,  and  to minimize the effects of crowding.  Therefore,
+        the wings of the object will extend beyond the  aperture.   Good
+        photometric  results  will  be  obtained only if the aperture is
+        consistently well centered, and if the  shape  and  diameter  of
+        an  object  is  constant throughout the image and invariant with
+        respect to magnitude.
+
+
+
+3. Specifications
+
+    The  APPHOT  package  performs  aperture  photometry  on   digitized 
+starfields   maintained  as  IRAF  imagefiles.   Input  to  the  package 
+consists of an imagefile, a list of  object  coordinates,  and  numerous
+parameters  controlling  the  analysis  algorithms.   Output consists of
+successive lines of text, where each  line  summarizes  the  results  of
+the  analysis  for  a  particular  object.  The output may be saved in a
+textfile, which may easily be printed  or  written  onto  a  card  image
+tape   for   export.    The   package   routines   may  be  used  either 
+interactively or in batch mode.
+
+The CL callable part of the APPHOT package  consists  of  the  following
+routines:
+
+        apphot   -- the main aperture photometry routine.
+        coordtr  -- translations and rotations of coord lists.
+        fitsky   -- computes mode and sigma of a sky region.
+        fitpsf   -- compute the FWHM of the PSF.
+        imcursor -- reads the image cursor; used to make lists.
+        immark   -- marks objects on the display device.
+        radprof  -- computes the radial profile of an object.
+
+Routines  for  general list manipulation, reading and writing card image
+tapes,  reading  and  writing  images  to  FITS  tapes,   removing   the 
+instrumental   signature   from  the  data,  and  so  on  are  available 
+elsewhere in the  IRAF  system.   The  package  is  easily  extended  to
+include  peak  finding,  matching of object lists from different images,
+background fitting and removal, and so on.   The  APPHOT  package  shall
+
+
+                                  -3-
+APPHOT (Aug83)    Digital Aperture Photometry Package     APPHOT (Aug83)
+
+
+
+eventually   supplant   both   the  KPNO  AUTOPHOT  and  KPNO  "Mountain 
+Photometry Code" packages.
+
+
+
+3.1 Standard Analysis Procedures
+
+    Before performing aperture photometry one must determine the  radius
+of  the  object  aperture  to  be used, the inner radius and size of the
+annulus to be used to fit the background, the full  width  at  half  max
+(FWHM)  of  the  point  spread  function  (PSF),  and so on.  Additional
+parameters are required by the centering algorithm.  A  list  of  object
+centers  must  be  prepared  if APPHOT is to be used in batch mode.  The
+standard procedure is as follows:
+
+    (1) Use RADPROF to determine values for the following parameters:
+
+            - the object aperture radius or radii, in pixels
+            - the inner radius of the annular (sky) region
+            - the width of the annular region
+
+    (2) Use FITPSF to fit gaussians to isolated, high  signal  to  noise
+        data  objects,  to  determine  the  FWHM  of  the  point  spread 
+        function.
+
+    (3) Use FITSKY to determine  the  sky  sigma  (standard  deviation).
+        APPHOT  assumes  that sigma is approximately constant throughout
+        the image.
+
+    (4) If one does not wish to  manually  mark  object  positions  with
+        the  cursor  during  analysis,  i.e.  when the analysis is to be
+        done in batch, a list of object coordinates  must  be  prepared.
+        This may be done in many ways:
+
+            o   By  running  RCURSOR with the standard output redirected
+                into the list file.
+
+            o   By transforming an existing list with  COORDTR,  OPSTRM,
+                MATCH, SORT, WINDOW, the editor, or some other filter.
+
+            o   By  an  automatic  object  finding  procedure, if one is
+                available.
+
+            o   By any other program which generates a  list  of  object
+                coordinates,  where  each line of the list describes one
+                object, and where x  and  y  in  pixel  coordinates  are
+                given  in  columns  one and two.  Additional columns, if
+                present, are ignored.
+
+            o   APPHOT output may be  used  as  coordinate  input  in  a
+                subsequent run.
+
+    (5) Finally,  APPHOT  is  run  to  measure  the  objects.   The user
+
+
+                                  -4-
+APPHOT (Aug83)    Digital Aperture Photometry Package     APPHOT (Aug83)
+
+
+
+        should  be  familiar  with  the  algorithms  used  to  fit   the 
+        background,   measure   the   object  center,  and  compute  the 
+        aperture integral, magnitude, and errors.   The  values  of  all
+        visible   and  hidden  APPHOT  parameters  should  be  inspected 
+        before doing any serious processing.
+
+The general purpose IRAF list processing tools may be used  for  further
+analysis  of  APPHOT  output.   Output  lists  may be filtered to select
+objects based on the value of a  list  column,  i.e.,  all  the  objects
+within   a  certain  magnitude  range  may  be  selected,  objects  with 
+estimated errors larger than a certain value may be deleted, or  a  list
+may  be  sorted using the value in any column.  Columns may be extracted
+from a list to form new lists or to provide  input  to  a  plot  filter,
+and  lists  may  be  merged.   Arithmetic  may  be performed on lists to
+calculate colors, etc.
+
+The remainder of this section presents detailed specifications  for  the
+analysis procedures in the APPHOT package.
+
+
+
+3.2 The APPHOT Program
+
+    The  function  of  the  APPHOT  procedure  is  to  perform  aperture 
+photometry on isolated objects within an  image.   The  principal  input
+operands  are  the  name  of  the imagefile and the rough coordinates of
+the objects to be processed.  The  principal  output  operands  are  the
+coordinates and magnitudes of the objects.
+
+In  order  to  perform  aperture  photometry  APPHOT  must  perform  the 
+following  sequence  of  operations   (the   algorithms   employed   are 
+explained in more detail later in this section):
+
+    (1) The  mode  and sigma of an annular background region centered on
+        the object is calculated.
+
+    (2) The center of the object is determined.
+
+    (3) The background is subracted  from  the  object,  and  the  total
+        flux within the object aperture or apertures is calculated.
+
+Steps  (1)  and (2) above are optional; the background and center may be
+determined externally, rather than by APPHOT, if desired.
+
+
+3.2.1 APPHOT parameters
+
+    APPHOT has quite a few parameters  due  to  the  complexity  of  the
+algorithms  employed.   All  data dependent parameters are query mode to
+ensure that they get set properly when a new image  is  processed.   The
+data  independent  algorithm control parameters are hidden mode, and are
+given reasonable default values.   The  names,  datatypes,  and  default
+values of the APPHOT parameters are shown below.
+
+
+                                  -5-
+APPHOT (Aug83)    Digital Aperture Photometry Package     APPHOT (Aug83)
+
+
+
+Positional or query mode parameters:
+
+        image           filename
+        apertures       string
+        annulus         real
+        width_annulus   real
+        fwhm_psf        real
+        sky_sigma       real
+
+
+List structured parameters (filename may be given on command line):
+
+        sky_mode        *real
+        coords          *imcur
+
+
+Hidden parameters:
+
+        spool           boolean         no
+        output          filename        "apphot.out"
+        fitsky          boolean         yes
+        max_sky_iter    integer         50
+        growing_radius  real            1.0 (fwhm_psf units)
+        k1              real            5.0
+        k2              real            2.0
+        center          boolean         yes
+        clean           boolean         yes
+        cleaning_radius real            0.8 (fwhm_psf units)
+        clipping_radius real            1.5 (fwhm_psf units)
+        max_cen_shift   real            1.0 (fwhm_psf units)
+        min_snratio     real            0.5
+        zmag            real            26.0
+        verbose         boolean         yes
+
+
+The  function  and  format  of  each of these parameters is explained in
+more detail below.
+
+
+    image           The name  of  the  image  or  image  section  to  be
+                    processed.
+
+    output          The  name  of  the  output  textfile  used  to spool
+                    APPHOT  output.   If  null,  output  will   not   be 
+                    spooled.   Note  that  output  always appears on the
+                    standard output,  whether  or  not  spooling  is  in
+                    effect.
+
+    apertures       The   radii  in  pixels  of  the  concentric  object 
+                    apertures, given all on  the  same  line,  delimited
+                    by  blanks.   At  least  one aperture must be given;
+                    the maximum number of apertures is  limited  by  the
+                    length  of  a  line.  A sample input string might be
+
+
+                                  -6-
+APPHOT (Aug83)    Digital Aperture Photometry Package     APPHOT (Aug83)
+
+
+
+                    "5.0 5.5 6.0 6.5 7.0".  If only  a  single  aperture
+                    is  to  be  used,  a  real  expression  may  be used
+                    instead of a string type  argument.   The  apertures
+                    need  not  be  given  in  any particular order.  The
+                    average  radius  will  be  used   to   compute   the 
+                    uncertainty in the object magnitude.
+
+    annulus         The  inner  radius  of  the  annular  sky region, in
+                    pixels.
+
+    width_annulus   The width of the annular sky region, in pixels.
+
+    fwhm_psf        The FWHM of the psf, in pixels.   Used  as  a  scale
+                    factor to control the internal algorithms.
+
+    sky_sigma       The  standard  deviation  (noise value) of a typical
+                    region  of  sky  in  the  image.   Used  for   pixel 
+                    rejection in the sky fitting algorithm.
+
+    sky_mode        The  name  of a list file containing the mode of the
+                    background  of   each   of   the   objects   to   be 
+                    processed.   Required  only  if  FITSKY  is switched
+                    off.  If sky fitting is disabled, and no  list  file
+                    is given, APPHOT will query for the sky value.
+
+    coords          The  name  of a list file containing the coordinates
+                    of  the  objects  to  be  processed.    If   absent, 
+                    objects   may   be  marked  interactively  with  the 
+                    cursor.
+
+    fitsky          A  switch  used  to  specify  whether  or  not   the 
+                    background  will  be  fitted.  If background fitting
+                    is disabled, the mode and sigma  of  the  background
+                    will  be  read  from  the SKY_FILE list each time an
+                    object is processed.
+
+    max_sky_iter    The  maximum  number  of  iterations  for  the   sky 
+                    fitting    algorithm.    Since   the   sky   fitting  
+                    algorithm   is   guaranteed   to   converge,    this  
+                    parameter  should  normally  have a large value.  If
+                    the value is zero, the  median  of  the  sky  region
+                    will be used instead of the mode.
+
+    growing_radius  The  region  growing  radius  for pixel rejection in
+                    the sky region, in units of FWHM_PSF.   When  a  bad
+                    sky   pixel   is   detected,   all   pixels   within  
+                    (growing_radius  *  fwhm_psf)  pixels  of  the   bad 
+                    pixel  will  be rejected.  Used to exclude the wings
+                    of contaminating objects from  the  sky  sample,  to
+                    avoid biasing the mode.
+
+    k1              The  k-sigma  clipping factor for the first phase of
+                    the sky fitting algorithm.
+
+
+                                  -7-
+APPHOT (Aug83)    Digital Aperture Photometry Package     APPHOT (Aug83)
+
+
+
+    k2              The  k-sigma  clipping  factor   for   the   second, 
+                    iterative, phase of the sky fitting algorithm.
+
+    center          A  switch  used  to specify whether or not centering
+                    is to be performed.  If centering is  disabled,  the
+                    initial center will be used as the object center.
+
+    clean           A   switch  used  to  specify  whether  or  not  the 
+                    symmetry-clean algorithm is to  be  employed  during
+                    centering.
+
+    cleaning_radius The   cleaning   radius   for   the   symmetry-clean  
+                    algorithm, in units of FWHM_PSF.
+
+    clipping_radius The   clipping   radius   for   the   symmetry-clean  
+                    algorithm, in units of FWHM_PSF.
+
+    max_cen_shift   The  maximum  permissible  shift of center, in units
+                    of  FWHM_PSF.   If  the  shift   produced   by   the 
+                    centering  algorithm  is larger than this value, the
+                    fit  will  terminate  and  no  magnitude   will   be 
+                    calculated.
+
+    min_snratio     Centering  will  be  skipped  if the signal to noise
+                    of  the  object,  as  calculated  from  the  initial 
+                    center,  is  less  than  the  value  given  by  this 
+                    parameter.
+
+    zmag            Zero point for the output magnitude scale.
+
+    verbose         If enabled, the output columns  are  labeled.   Note
+                    that  the  presence  of  column labels in the output
+                    may interfere with the use of  the  list  processing
+                    tools.
+
+
+
+3.2.2 The APPHOT Background Fitting Algorithm
+
+    A  good background fit is essential to aperture photometry.  Fitting
+the background is trivial in a sparse field, but difficult in a  crowded
+field.   In  general  the  background  region will contain contaminating
+objects which must be detected and excluded if  a  good  fit  is  to  be
+obtained.
+
+The  algorithm  employed  here  is  based  on the fact that contaminated
+pixels are  almost  always  spatially  correlated.   Background  fitting
+algorithms  which  work with a one dimensional sample (mode, median), or
+with the  one  dimensional  histogram  (mode  of  hgm)  have  difficulty
+rejecting  the  faint  wings of contaminated regions.  This is a serious
+defect of one  dimensional  fitting  algorithms,  because  it  is  these
+faint  wings,  not  the  bright central pixels, which are most likely to
+bias the calculated background value.
+
+
+                                  -8-
+APPHOT (Aug83)    Digital Aperture Photometry Package     APPHOT (Aug83)
+
+
+
+The algorithm used in APPHOT is as follows:
+
+
+    algorithm fit_sky
+
+    begin
+            # Reject gross deviants.
+            compute the median of the annular region
+            detect pixels more than (k1*sky_sigma) from the median
+            reject all such pixels, without region growing
+
+            # Detect and reject contaminating objects.
+            while (number of iterations <= max_sky_iter) {
+                compute the histogram of the reduced sample
+                compute the sigma and mode of the histogram
+                detect pixels more than k2*sigma from the mode
+                reject all such pixels, with region growing
+                if (no pix rejected or all pix rejected)
+                    terminate loop
+            }
+
+            return the final mode, sigma, and sample size
+    end
+
+
+The mode of the histogram  is  found  by  cross  correlating  the  noise
+function  with  the  histogram.   The width of the the noise function is
+given  by  the  standard  deviation  of  the  current   sample.    Pixel 
+rejection  is  performed  by locating all pixels more than k2*sigma from
+the mode, and blindly rejecting all pixels within a  certain  radius  of
+each  deviant  pixel.   This  simple  algorithm  works  well because the
+sample is large, and therefore there is little  penalty  for  discarding
+pixels  that  might  not  be  deviant.   Region  growing  also  tends to
+accelerate convergence significantly.
+
+Very faint contaminating objects are difficult  to  detect  and  reject.
+If  there  are enough such objects, they should not be rejected, because
+there are probably a few in the object aperture as well.  A  higher  sky
+sigma  will  be calculated and the computed uncertainty in the magnitude
+will increase.  The best solution to this problem  may  be  to  increase
+the  size of the annulus to minimize the bias and maximize the liklihood
+of a detection.
+
+
+
+3.2.3 The APPHOT Centering Algorithm
+
+    The centering algorithm used in APPHOT  is  that  of  Auer  and  Van
+Altena,  with  the addition of the symmetry-clean algorithm developed by
+Barry Newell.  The main algorithm is as follows:
+
+
+
+
+
+                                  -9-
+APPHOT (Aug83)    Digital Aperture Photometry Package     APPHOT (Aug83)
+
+
+
+    algorithm get_center
+
+    begin
+            if (centering is disabled) {
+                return initial center, zero uncertainty estimate
+
+            } else if (signal to noise of object < MIN_SNRATIO) {
+                compute uncertainty using initial center
+                return initial center, computed uncertainty
+
+            } else {
+                call measure_center
+                return image center and estimated uncertainty
+            }
+    end
+
+
+The  actual  center  determination  is  carried  out  by  the  following 
+algorithm:
+
+
+    algorithm measure_center
+
+    begin
+            extract subarray from the main data array
+
+            # Perform symmetry-cleaning.
+            if (cleaning is enabled) {
+                for (each pair of pixels diametrically opposed about
+                    the image center beyond the cleaning radius)
+                        if (i2 > i1 + 2*sky_sigma)
+                            replace i2 by i1
+                        else if (i1 > i2 + 2*sky_sigma)
+                            replace i1 by i2
+
+                perform 2*sky_sigma noniterative clip of all pixels
+                beyond the clipping radius, to remove any remaining
+                radially symmetric structures
+            }
+
+            # Compute the image center and uncertainty.
+            compute x and y marginals of the cleaned subarray
+            fit a gaussian of width FWHM_PSF to each marginal
+            compute the centering error from the covariance matrix
+
+            return image center and estimated uncertainty
+    end
+
+
+The  effect  of  the  symmetry-clean  algorithm  is  to edit the raster,
+removing any contaminating  objects  in  the  vicinity  of  the  primary
+object.   This  simplifies  the  fitting  algorithm  and  increases  its 
+reliability, since it does not have  to  deal  with  multipeak  marginal
+
+
+                                 -10-
+APPHOT (Aug83)    Digital Aperture Photometry Package     APPHOT (Aug83)
+
+
+
+distributions.
+
+A  gaussian  is  fitted  to  the  marginal  distributions  because it is
+expected  to  yield  a  better  center  determination  for  undersampled 
+data.    An   alternative   is   to   empirically  derive  the  marginal 
+distributions of the psf and fit these to each data object.  This  is  a
+better  approach  in some cases, but in the case of undersampled data it
+is difficult to  derive  the  marginal  distributions  due  to  sampling
+effects,  and  fitting is difficult due to interpolation error.  The use
+of  a  gaussian  eliminates  interpolation  error.    Eventually,   both 
+techniques should be made available.
+
+
+
+3.2.4 The APPHOT Aperture Integration Algorithm
+
+    The  integral  of the flux within a circular aperture is computed by
+fractional pixel techniques.  Pixels are assumed to be square  apertures
+arranged  in  a  rectangular  grid.   The fraction of a pixel which lies
+within the circular APPHOT aperture is  computed  by  an  approximation,
+and all such contributions are summed to produce the total integral.
+
+The  simplicity  of aperture photometry limits the amount of information
+available for error analysis.   Using  only  the  noise  value  for  the
+background, the estimated error in the aperture integral is given by
+
+        flux_error = sky_sigma * sqrt (aperture_area)
+
+where  "sky_sigma"  is  either  the  sigma  calculated by the background
+fitting algorithm or the parameter SKY_SIGMA, depending on  whether  sky
+fitting  is  enabled,  and where "aperture_area" is the fractional pixel
+area of the aperture.
+
+It is possible, however, to produce a more useful error estimate  if  we
+include  some  information  about  the  psf.   For  the  purposes  of an
+improved error estimate, we assume that the PSF is  a  gaussian.   Given
+the  object  center,  the  background,  and  the  FWHM of the PSF, it is
+trivial to fit a two dimensional gaussian to the  object.   An  estimate
+of  the  average noise value for the pixels within the aperture may then
+be obtained by computing the standard deviation of the  residual  formed
+by  subtracting  the  fitted  two-dimensional  gaussian  from  the data.
+This value is used in place of SKY_SIGMA in the above  equation  for  an
+improved estimate of the actual flux error.
+
+In  the  limit  as the gaussian goes to zero, both uncertainty estimates
+tend to the same  value,  as  they  should.   For  bright  objects,  the
+uncertainty  produced  by  analysis  of  the  residual  will  tend to be
+pessimistic, since it is unlikely that the PSF can actually  be  modeled
+by  a  simple  gaussian.   Nonetheless,  a  plot  of  uncertainty versus
+magnitude should reveal objects which are  blended,  which  contain  bad
+pixels,  and  so  on.  The accuracy of the gaussian model will determine
+how reliably deviant objects can be discriminated.
+
+
+
+                                 -11-
+APPHOT (Aug83)    Digital Aperture Photometry Package     APPHOT (Aug83)
+
+
+
+3.2.5 APPHOT Output
+
+    For each object processed, APPHOT prints a single line  of  text  on
+the  standard  output.   If  desired,  APPHOT  will simultaneously spool
+output into a user specified text file.  Each output line  will  contain
+the following information (excluding the commas):
+
+
+    x,y,cenerr,shift, mode,sigma,nskypix, mag1,...,magn,magerr
+
+where
+
+    x,y         object coordinates in pixels
+    cenerr      estimated uncertainty in the object center
+    shift       shift of center from initial coordinates
+    mode        mode of the background
+    sigma       sigma of the background
+    nskypix     number of sky pixels left after rejection
+    mag1        magnitude within the first annulus
+    magn        magnitude within the Nth annulus
+    magerr      estimated mag. uncertainty at the average radius
+
+
+Note  that  the estimated uncertainty in the magnitude is given only for
+the average object aperture  radius.   The  uncertainty  for  the  other
+apertures  can  easily  be  calculated  given SIGMA and the area of each
+aperture.  The zero point for  the  magnitude  scale  is  given  by  the
+hidden parameter ZMAG.
+
+Additional  information  could  be  calculated  and  output (such as the
+moments of the object and the  skew  of  the  background),  but  in  our
+experience  few people ever look at such information, and a more complex
+output format would be required.  Probably the calculation  of  anything
+but  object  centers,  magnitudes,  and  errors  should be left to other
+programs.
+
+
+
+3.3 The COORDTR Program
+
+    The function of COORDTR is to effect  a  linear  translation  and/or
+rotation  of  a  coordinate list.  COORDTR is a filter; coordinate lines
+are read from the standard input and written  to  the  standard  output.
+COORDTR  is  concerned  only  with coordinate transformations, and knows
+nothing about image boundaries.  A transformed coordinate may no  longer
+lie within an image.
+
+        x y other_stuff
+
+The  format  of a coordinate line is shown above.  COORDTR operates only
+on the coordinate pair x,y.  Any additional information on the  line  is
+passed on to the output without modification.
+
+
+
+                                 -12-
+APPHOT (Aug83)    Digital Aperture Photometry Package     APPHOT (Aug83)
+
+
+
+COORDTR  is  actually  a  general  purpose list processing operator, and
+belongs in  a  list  processing  package,  rather  than  in  the  APPHOT
+package.   When  a list processing package is developed, COORDTR will be
+moved to that package.
+
+A COORDTR transformation consists of a linear  translation  followed  by
+a  rotation.   Either  the  translation,  the  rotation,  or both may be
+skipped.  The COORDTR parameters are summarized below.
+
+
+positional arguments:
+
+        xshift          real
+        yshift          real
+        xcenter         real
+        ycenter         real
+        theta           real
+
+
+hidden parameters:
+
+        translate       boolean         yes
+        rotate          boolean         no
+
+
+If more than two positional arguments  are  given,  COORDTR  knows  that
+both  a  translation  and a rotation are desired.  Otherwise the boolean
+parameters TRANSLATE and ROTATE are read to  determine  what  additional
+parameters  are  needed.   Thus  a  simple  linear  translation  of +2.5
+pixels in X and -0.2 pixels in Y would be specified by the command
+
+        coordtr (2.5, -.2, < "input", > "output")
+
+which transforms the list in file "input", writing the output  into  the
+new file "output".
+
+If  a  rotation  is  desired, XCENTER, YCENTER, and THETA must be given.
+The first two parameters specify the  pixel  coordinates  of  the  point
+about  which  the rotation is to be performed, while THETA specifies the
+rotation angle in degrees.  Positive THETA produces  a  counterclockwise
+rotation, if positive X is to the right and positive Y is up.
+
+
+
+3.4 The FITSKY Program
+
+    The  function  of  the  FITSKY  program is to determine the mode and
+sigma of the specified annular  regions,  printing  the  results  (mode,
+sigma,  and  npix)  on  the  standard  output.   FITSKY  is  similar  in 
+operation to APPHOT, except  that  its  function  is  to  fit  sky,  not
+perform aperture photometry.  The FITSKY parameters are the following:
+
+
+
+
+                                 -13-
+APPHOT (Aug83)    Digital Aperture Photometry Package     APPHOT (Aug83)
+
+
+
+Positional or query mode parameters:
+
+        image           filename
+        annulus         real
+        width_annulus   real
+        fwhm_psf        real
+
+
+List structured parameters (filename may be given on command line):
+
+        coords          *imcur
+
+
+Hidden parameters:
+
+        spool           boolean         no
+        output          filename        "fitsky.out"
+        max_sky_iter    integer         50
+        growing_radius  real            1.0 (fwhm_psf units)
+        k1              real            5.0
+        k2              real            2.0
+        verbose         boolean         yes
+
+
+The  names  and functions of the FITSKY parameters are the same as those
+for APPHOT.  Note that ANNULUS  may  be  set  to  zero  to  measure  the
+background   within   a   circular  aperture.   The  maximum  number  of 
+iterations may be set to zero to measure the median of the  sky  sample.
+FITSKY output may be spooled into a file and used as input to APPHOT.
+
+
+
+3.5 The FITPSF Program
+
+    The  function  of the FITPSF program is to determine the FWHM of the
+point spread function.  This is done  by  selecting  an  isolated,  high
+signal  to  noise  object,  computing the x and y marginal profiles, and
+fitting a gaussian to each  profile.   Output  consists  of  the  object
+center,  the  error in the center, and the FWHM of the fitted gaussians.
+Note that the sigma of a gaussian may be obtained by dividing  the  FWHM
+by 2.354.
+
+        x y err x_fwhm y_fwhm
+
+The input parameters for the FITPSF program are shown below.
+
+
+
+
+
+
+
+
+
+
+                                 -14-
+APPHOT (Aug83)    Digital Aperture Photometry Package     APPHOT (Aug83)
+
+
+
+Positional parameters:
+
+        image           filename
+        aperture        real
+        annulus         real
+        width_annulus   real
+        sky_mode        real
+        coords          *imcur
+
+
+Hidden parameters:
+
+        fitsky          boolean         yes
+        center          boolean         yes
+        spool           boolean         no
+        output          filename        "fitpsf.out"
+        verbose         boolean         yes
+
+
+If  background  fitting  is disabled, the parameter SKY_MODE defines the
+sky  level.   The  background  fitting  algorithm  is  a  simple  median 
+calculation  without  pixel  rejection  or  iteration.   This  should be
+sufficient, since FITPSF is expected to  be  used  mainly  in  uncrowded
+regions on high signal to noise objects.
+
+Note  that  FITPSF  is  set  up to process a list of input objects.  The
+list processing tools  (i.e.,  AVERAGE)  may  be  used  to  average  the
+results to produce the final FWHM of the PSF for the image.
+
+
+
+3.6 The IMCURSOR Program
+
+    The  function  of  the  IMCURSOR  program  is  to  read the STDIMAGE
+cursor, writing the cursor coordinates  on  the  standard  output.   The
+cursor  is  read  until  the  EOF  character is entered to terminate the
+loop.  The standard output may be redirected into a file to  generate  a
+coordinate list.  IMCURSOR has no parameters.
+
+
+
+3.7 The IMMARK Program
+
+    The  function  of  IMMARK  is  to  draw  marks on the diplay device.
+IMMARK is useful for verifying coordinate lists.
+
+
+parameters:
+
+        mark_type       string
+        mark_size       real
+        coords          *imcur
+
+
+
+                                 -15-
+APPHOT (Aug83)    Digital Aperture Photometry Package     APPHOT (Aug83)
+
+
+
+Output is  the  current  frame  of  the  STDIMAGE  device.   Mark  types
+include  "circle",  "box",  "cross", "plus", and "diamond".  The size of
+a  mark  is  given  in  pixels.   The  third  parameter  is  a  standard 
+coordinate  list.   If  no  list is given, the image cursor will be read
+instead.
+
+
+
+3.8 The RADPROF Program
+
+    The function of  the  RADPROF  program  is  to  compute  the  radial
+profile  of  an object.  The output of RADPROF consists of a sequence of
+lines of text, each line  defining  the  profile  at  a  single  radius.
+Since  RADPROF  may  generate  many  lines  of output for a single input
+object, it is set up to process  only  a  single  input  object.   A  CL
+while loop may be written to process multiple objects, if desired.
+
+
+positional arguments:
+
+        image           filename
+        aperture        real
+        step_size       real
+        annulus         real
+        width_annulus   real
+        sky_mode        real
+
+
+hidden parameters:
+
+        fitsky          boolean         yes
+        center          boolean         yes
+        verbose         boolean         yes
+
+
+The  radial  profile  is  calculated  from  the  image center out to the
+radius specified by  the  parameter  APERTURE,  in  steps  of  STEP_SIZE
+pixels.   The  remaining  RADPROF  parameters  are  similar  to those of
+APPHOT and will not be discussed in detail.  If  background  fitting  is
+disabled,   the   parameter   SKY_MODE   defines  the  sky  level.   The 
+background fitting algorithm is  a  simple  median  calculation  without
+pixel   rejection  or  iteration.   This  should  be  sufficient,  since 
+RADPROF is expected to be used  mainly  in  uncrowded  regions  on  high
+signal  to  noise  objects.   Centering  is  via  gaussian  fits  to the
+marginal profiles, without cleaning.
+
+RADPROF output lines contain the following fields:
+
+        r, i(r), inorm(r), fraction(r)
+
+where
+
+        r               radius in pixels
+
+
+                                 -16-
+APPHOT (Aug83)    Digital Aperture Photometry Package     APPHOT (Aug83)
+
+
+
+        i(r)            raw intensity at r
+        inorm(r)        normalized intensity at r (range 0-1)
+        fraction(r)     fraction of total integral at r
+
+
+RADPROF does not  generate  any  plots.   If  one  wishes  to  plot  the
+contents  of  an  output column, the column may be extracted with a list
+processing filter and piped to a graphics task.
+
+
+
+4.0 Example
+
+    A brief  example  may  help  illustrate  the  use  of  the  package.
+Suppose  we  want  to  process  a few hundred stars on images "blue" and
+"red".  We start by analyzing the blue image.
+
+        ap> radprof blue,15,0.5,20,10
+
+This gives us a radial profile printout for one  of  the  "blue"  stars.
+We  decide  that  an  aperture radius of 2.5 pixels is about right.  The
+annulus will start at a  radius  of  10.0  pixels  and  extend  to  20.0
+pixels.  The next step is to determine the FWHM of the PSF:
+
+        ap> fitpsf blue,3,10,20 | tee spoolfile
+
+By  default, the program will take coordinate input by reading the image
+display cursor.  When the program is waiting for cursor input,  it  will
+cause  the display cursor to blink rapidly; normally the cursor does not
+blink.  One has to be aware of this, because no other prompt is  issued.
+We  postion  the  cursor  on  several  stars,  and  tap the space bar to
+measure each one.  When finished we type  the  EOF  character  (<ctrl/z>
+on  our  systems)  to terminate the loop.  The screen will now look like
+this (the output column labels are ommitted):
+
+        ap> fitpsf blue,3,10,20 | tee spoolfile
+         283.12  157.40 0.035  2.887  2.751
+         546.08  213.45 0.023  2.833  2.902
+         318.32  354.73 0.064  2.791  2.824
+
+Since we elected to use TEE to spool the output, rather than  the  SPOOL
+parameter  of  FITPSF,  we will not see the results until all stars have
+been measured.  The next step is to average the  results,  to  determine
+the  final  FWHM  (the  FITPSF  output could have been piped directly to
+GETCOLS without using an intermediate spoolfile, if desired).
+
+        ap> getcols spoolfile,"4-5" | getcols | average
+        2.83133 0.0569725 6 
+
+There are many ways this average could have been  computed,  of  course;
+this  is  only  one  example.   Next,  to avoid having to write down the
+FWHM value, we put it into the appropriate APPHOT parameter  (note  that
+the parameter name is abbreviated).
+
+
+                                 -17-
+APPHOT (Aug83)    Digital Aperture Photometry Package     APPHOT (Aug83)
+
+
+
+        ap> apphot.fwhm = 2.831
+
+Finally,  we  must  determine a representative backround sigma value for
+the image.  This is done by using FITSKY to measure several  sky  areas,
+and  averaging column two of the output, much as we did for FITPSF.  The
+final value may be saved in "apphot.sky_sigma".
+
+By this point we have determined all the necessary  parameters,  and  it
+is  time  to  do  some photometry.  The only APPHOT argument we are sure
+of is the image name parameter,  so  that  is  all  we  include  on  the
+command line:
+
+        ap> apphot blue
+        aperture radii, pixels: 2.4 2.5 2.75 3.0
+        inner radius of sky annulus: 10
+        width of sky annulus (1 - ): 10
+        full width at half max of psf (2.831):
+        standard deviation of the image noise function (23.733):
+
+After  responding  to  the  prompts shown above, APPHOT will ask for the
+first pair of object coordinates,  and  the  cursor  blink  prompt  will
+again  be  given.  Several objects may be measured to verify that all is
+working.
+
+The last step is to prepare a list of  objects  to  be  processed.   The
+simplest  way  to  do this is to interactively mark the objects with the
+cursor.  Later, when we process the "red"  image,  the  same  coordinate
+list may again be used, possibly after filtering with COORDTR.
+
+        ap> imcursor > objlist
+
+At  this  point,  all  of the APPHOT parameters have been set, we have a
+list of objects to be processed, and we  are  ready  to  run  APPHOT  in
+batch  mode.   We  decide to save the output in the file "blue.out".  To
+ensure that we have a record of the parameters  used  for  the  fit,  we
+first  print  the  APPHOT parameters into the output file, then we start
+up the APPHOT batch run.
+
+        ap> lparam apphot > blue.out
+        ap> apphot >> blue.out &
+        [1]
+
+The batch job is  now  running,  appending  output  lines  to  the  file
+"blue.out".   We  can  proceed  to  set up the job for the red image, in
+much the same way that we set up the  job  for  the  blue  image.   When
+both  jobs  finish,  we  can use the list processing tools to filter out
+the good objects and calculate colors.