APER
Name
APER
Purpose
Compute concentric aperture photometry (adapted from DAOPHOT)
Explanation
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.
Calling Sequence
APER, image, xc, yc, [ mags, errap, sky, skyerr, phpadu, apr, skyrad,
badpix, /NAN, /EXACT, /FLUX, PRINT = , /SILENT,
/MEANBACK, MINSKY=, SETSKYVAL = ]
Inputs
IMAGE - input image array
XC - vector of x coordinates.
YC - vector of y coordinates
Optional Inputs
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.
Optional Keyword Inputs
CLIPSIG - if /MEANBACK is set, then this is the number of sigma at which
to clip the background. Default=3
CONVERGE_NUM: if /MEANBACK is set then if the proportion of
rejected pixels is less than this fraction, the iterations stop.
Default=0.02, i.e., iteration stops if fewer than 2% of pixels
excluded.
/EXACT - By default, APER counts subpixels, but uses a polygon
approximation for the intersection of a circular aperture with
a square pixel (and normalizes 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.
MAXITER if /MEANBACK is set then this is the ceiling on number of
clipping iterations of the background. Default=5
/MEANBACK - if set, then the background is computed using the 3 sigma
clipped mean (using meanclip.pro) rather than using the mode
computed with mmm.pro. This keyword is useful for the Poisson
count regime or where contamination is known to be minimal.
MINSKY - Integer giving mininum number of sky values to be used with MMM
APER will not compute a flux if fewer valid sky elements are
within the sky annulus. Default = 20.
/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.
Outputs
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
Example
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
Procedures Used
GETOPT, MMM, PIXWT(), STRN(), STRNUMBER()
Notes
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. In this case the negative
flux and error are returned.
For the case where the source is fainter than the background, APER will
return negative fluxes if /FLUX is set, but will otherwise give
invalid data (since negative fluxes can't be converted to magnitudes)
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)
Revison History
Adapted to IDL from DAOPHOT June, 1989 B. Pfarr, STX
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
Added MEANBACK keyword W. Landsman October 2005
Correct typo when /EXACT and multiple apertures used. W.L. Dec 2005
Remove VMS-specific code W.L. Sep 2006
Add additional keywords if /MEANBACK is set W.L Nov 2006
Allow negative fluxes if /FLUX is set W.L. Mar 2008
Previous update would crash if first star was out of range W.L. Mar 2008
Fix floating equality test for bad magnitudes W.L./J.van Eyken Jul 2009
Added MINSKY keyword W.L. Dec 2011