path: root/noao/digiphot/apphot/doc/specs/Ap.doc

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.