APER

      Compute concentric aperture photometry (adapted from DAOPHOT)

     APER can compute photometry in several user-specified aperture radii.
     A separate sky value is computed for each source using specified inner
     and outer sky radii.

     APER, image, xc, yc, [ mags, errap, sky, skyerr, phpadu, apr, skyrad,
                       badpix, /NAN, /EXACT, /FLUX, PRINT = , /SILENT,
                       SETSKYVAL = ]

     IMAGE -  input image array
     XC     - vector of x coordinates.
     YC     - vector of y coordinates

     PHPADU - Photons per Analog Digital Units, numeric scalar.  Converts
               the data numbers in IMAGE to photon units.  (APER assumes
               Poisson statistics.)
     APR    - Vector of up to 12 REAL photometry aperture radii.
     SKYRAD - Two element vector giving the inner and outer radii
               to be used for the sky annulus.   Ignored if the SETSKYVAL
              keyword is set.
     BADPIX - Two element vector giving the minimum and maximum value
               of a good pixel.   If badpix is not supplied or if BADPIX[0] is
               equal to BADPIX[1] then it is assumed that there are no bad
               pixels.     Note that fluxes will not be computed for any star
               with a bad pixel within the aperture area, but that bad pixels
               will be simply ignored for the sky computation.    The BADPIX
               parameter is ignored if the /NAN keyword is set.

     /EXACT -  By default, APER counts subpixels, but uses a polygon
             approximation for the intersection of a circular aperture with
             a square pixel (and normalize the total area of the sum of the
             pixels to exactly match the circular area).   If the /EXACT
             keyword, then the intersection of the circular aperture with a
             square pixel is computed exactly.    The /EXACT keyword is much
             slower and is only needed when small (~2 pixels) apertures are
             used with very undersampled data.
     /FLUX - By default, APER uses a magnitude system where a magnitude of
               25 corresponds to 1 flux unit.   If set, then APER will keep
              results in flux units instead of magnitudes.
     /NAN  - If set then APER will check for NAN values in the image.   /NAN
             takes precedence over the BADPIX parameter.   Note that fluxes
             will not be computed for any star with a NAN pixel within the
             aperture area, but that NAN pixels will be simply ignored for
             the sky computation.
     PRINT - if set and non-zero then APER will also write its results to
               a file aper.prt.   One can specify the output file name by
               setting PRINT = 'filename'.
     READNOISE - Scalar giving the read noise (or minimum noise for any
              pixel.   This value is passed to the procedure mmm.pro when
              computing the sky, and is only need for images where
              the noise is low, and pixel values are quantized.
     /SILENT -  If supplied and non-zero then no output is displayed to the
               terminal.
     SETSKYVAL - Use this keyword to force the sky to a specified value
               rather than have APER compute a sky value.    SETSKYVAL
               can either be a scalar specifying the sky value to use for
               all sources, or a 3 element vector specifying the sky value,
               the sigma of the sky value, and the number of elements used
               to compute a sky value.   The 3 element form of SETSKYVAL
               is needed for accurate error budgeting.

     MAGS   -  NAPER by NSTAR array giving the magnitude for each star in
               each aperture.  (NAPER is the number of apertures, and NSTAR
               is the number of stars).   If the /FLUX keyword is not set, then
               a flux of 1 digital unit is assigned a zero point magnitude of
               25.
     ERRAP  -  NAPER by NSTAR array giving error for each star.  If a
               magnitude could not be determined then  ERRAP = 9.99 (if in
                magnitudes) or ERRAP = !VALUES.F_NAN (if /FLUX is set).
     SKY  -    NSTAR element vector giving sky value for each star in
               flux units
     SKYERR -  NSTAR element vector giving error in sky values

       Determine the flux and error for photometry radii of 3 and 5 pixels
       surrounding the position 234.2,344.3 on an image array, im.   Compute
       the partial pixel area exactly.    Assume that the flux units are in
       Poisson counts, so that PHPADU = 1, and the sky value is already known
       to be 1.3, and that the range [-32767,80000] for bad low and bad high
       pixels
       IDL> aper, im, 234.2, 344.3, flux, eflux, sky,skyerr, 1, [3,5], -1, $
            [-32767,80000],/exact, /flux, setsky = 1.3

       GETOPT, MMM, PIXWT(), STRN(), STRNUMBER()

       Reasons that a valid magnitude cannot be computed include the following:
      (1) Star position is too close (within 0.5 pixels) to edge of the frame
      (2) Less than 20 valid pixels available for computing sky
      (3) Modal value of sky could not be computed by the procedure MMM
      (4) *Any* pixel within the aperture radius is a "bad" pixel
      (5) The total computed flux is negative
       APER was modified in June 2000 in two ways: (1) the /EXACT keyword was
       added (2) the approximation of the intersection of a circular aperture
       with square pixels was improved (i.e. when /EXACT is not used)

       Adapted to IDL from DAOPHOT June, 1989   B. Pfarr, STX
       Adapted for IDL Version 2,               J. Isensee, July, 1990
       Code, documentation spiffed up           W. Landsman   August 1991
       TEXTOUT may be a string                  W. Landsman September 1995
       FLUX keyword added                       J. E. Hollis, February, 1996
       SETSKYVAL keyword, increase maxsky       W. Landsman, May 1997
       Work for more than 32767 stars           W. Landsman, August 1997
       Don't abort for insufficient sky pixels  W. Landsman  May 2000
       Added /EXACT keyword                     W. Landsman  June 2000
       Allow SETSKYVAL = 0                      W. Landsman  December 2000
       Set BADPIX[0] = BADPIX[1] to ignore bad pixels W. L.  January 2001
       Fix chk_badpixel problem introduced Jan 01 C. Ishida/W.L. February 2001
       Set bad fluxes and error to NAN if /FLUX is set  W. Landsman Oct. 2001
       Remove restrictions on maximum sky radius W. Landsman  July 2003
       Added /NAN keyword  W. Landsman November 2004
       Set badflux=0 if neither /NAN nor badpix is set  M. Perrin December 2004
       Added READNOISE keyword   W. Landsman January 2005

[Home Page] [Software, Documentation] [IDL Documentation] [Quick Reference] [Feedback]