diff options
Diffstat (limited to 'noao/digiphot/apphot/doc/specs')
| -rw-r--r-- | noao/digiphot/apphot/doc/specs/Ap.doc | 1071 | ||||
| -rw-r--r-- | noao/digiphot/apphot/doc/specs/Ap.spc | 1032 | ||||
| -rw-r--r-- | noao/digiphot/apphot/doc/specs/apphot.db | 366 | ||||
| -rw-r--r-- | noao/digiphot/apphot/doc/specs/apphot.spc | 1296 | ||||
| -rw-r--r-- | noao/digiphot/apphot/doc/specs/apphot.spc.lw | 1296 | ||||
| -rw-r--r-- | noao/digiphot/apphot/doc/specs/apphot.spc.toc | 111 |
6 files changed, 5172 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. diff --git a/noao/digiphot/apphot/doc/specs/Ap.spc b/noao/digiphot/apphot/doc/specs/Ap.spc new file mode 100644 index 00000000..911d04f1 --- /dev/null +++ b/noao/digiphot/apphot/doc/specs/Ap.spc @@ -0,0 +1,1032 @@ +.help apphot Aug83 "Digital Aperture Photometry Package" +.sh +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. + +.sh +2. Requirements +.ls 4 +.ls (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. +.le +.ls (2) +Given as input the approximate coordinates of a single object in the image, +the program shall perform the following operations: +.ls 4 +.ls 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. +.le +.ls 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. +.le +.ls 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. +.le +.le +.le +.ls (3) +The following options shall be provided to modify the operation of the +above functions: +.ls +.ls o +Use a user supplied constant background value and background noise estimate +instead of fitting the background. +.le +.ls o +Use the starting center as the actual center in all cases. +.le +.ls 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. +.le +.ls 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. +.le +.le +.le +.ls (4) +At a minimum, the following parameters shall be calculated and output +for each object: +.ls +.ls o +The coordinates of the object, and the estimated error in these coordinates. +.le +.ls o +The mode and standard deviation of the background; the number of pixels +left in the background region after pixel rejection. +.le +.ls 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. +.le +.le +.le +.ls (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. +.le +.ls (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. +.le +.le + +.sh +2.1 Summary of the Limitations of APPHOT + + The APPHOT package is designed to perform simple aperture photometry +subject to the following restrictions: +.ls +.ls (1) +Objects must be circular or nearly circular, since the aperture is +circular. +.le +.ls (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. +.le +.ls (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. +.le +.ls (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. +.le +.le + +.sh +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: + +.ks +.nf + 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. +.fi +.ke + +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 eventually +supplant both the KPNO AUTOPHOT and KPNO "Mountain Photometry Code" packages. + +.sh +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: +.ls +.ls (1) +Use RADPROF to determine values for the following parameters: + +.nf + - the object aperture radius or radii, in pixels + - the inner radius of the annular (sky) region + - the width of the annular region +.fi +.le +.ls (2) +Use FITPSF to fit gaussians to isolated, high signal to noise data objects, +to determine the FWHM of the point spread function. +.le +.ls (3) +Use FITSKY to determine the sky sigma (standard deviation). +APPHOT assumes that sigma is approximately constant throughout the image. +.le +.ls (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: +.ls +.ls o +By running RCURSOR with the standard output redirected into the list file. +.le +.ls o +By transforming an existing list with COORDTR, OPSTRM, MATCH, SORT, WINDOW, +the editor, or some other filter. +.le +.ls o +By an automatic object finding procedure, if one is available. +.le +.ls 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. +.le +.ls o +APPHOT output may be used as coordinate input in a subsequent run. +.le +.le +.le +.ls (5) +Finally, APPHOT is run to measure the objects. The user 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. +.le +.le + +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. + +.sh +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): +.ls +.ls (1) +The mode and sigma of an annular background region centered on the object +is calculated. +.le +.ls (2) +The center of the object is determined. +.le +.ls (3) +The background is subracted from the object, and the total flux within +the object aperture or apertures is calculated. +.le +.le + +Steps (1) and (2) above are optional; the background and center may be +determined externally, rather than by APPHOT, if desired. +.sh +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. + + +.ks +.nf +Positional or query mode parameters: + + image filename + apertures string + annulus real + width_annulus real + fwhm_psf real + sky_sigma real +.fi +.ke + + +.ks +.nf +List structured parameters (filename may be given on command line): + + sky_mode *real + coords *imcur +.fi +.ke + + +.ks +.nf +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 +.fi +.ke + + +The function and format of each of these parameters is explained in more +detail below. + +.ls +.ls 16 image +The name of the image or image section to be processed. +.le +.ls 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. +.le +.ls 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 "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. +.le +.ls annulus +The inner radius of the annular sky region, in pixels. +.le +.ls width_annulus +The width of the annular sky region, in pixels. +.le +.ls fwhm_psf +The FWHM of the psf, in pixels. Used as a scale factor to control the +internal algorithms. +.le +.ls 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. +.le +.ls 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. +.le +.ls 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. +.le +.ls 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. +.le +.ls 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. +.le +.ls 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. +.le +.ls k1 +The k-sigma clipping factor for the first phase of the sky fitting algorithm. +.le +.ls k2 +The k-sigma clipping factor for the second, iterative, phase of the +sky fitting algorithm. +.le +.ls 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. +.le +.ls clean +A switch used to specify whether or not the symmetry-clean algorithm +is to be employed during centering. +.le +.ls cleaning_radius +The cleaning radius for the symmetry-clean algorithm, in units of +FWHM_PSF. +.le +.ls clipping_radius +The clipping radius for the symmetry-clean algorithm, in units of +FWHM_PSF. +.le +.ls 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. +.le +.ls 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. +.le +.ls zmag +Zero point for the output magnitude scale. +.le +.ls 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. +.le +.le + +.sh +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. + +The algorithm used in APPHOT is as follows: + + +.ks +.nf + 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 +.fi +.ke + + +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. + +.sh +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: + + +.ks +.nf + 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 +.fi +.ke + + +The actual center determination is carried out by the following +algorithm: + + +.ks +.nf + 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 +.fi +.ke + + +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 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. + +.sh +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. + +.sh +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): + + +.nf + 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 +.fi + + +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. + +.sh +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. + +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. + + +.ks +.nf +positional arguments: + + xshift real + yshift real + xcenter real + ycenter real + theta real +.fi +.ke + + +.ks +.nf +hidden parameters: + + translate boolean yes + rotate boolean no +.fi +.ke + + +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. + +.sh +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: + + +.ks +.nf +Positional or query mode parameters: + + image filename + annulus real + width_annulus real + fwhm_psf real +.fi +.ke + + +.ks +.nf +List structured parameters (filename may be given on command line): + + coords *imcur +.fi +.ke + + +.ks +.nf +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 +.fi +.ke + + +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. + +.sh +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. + + +.ks +.nf +Positional parameters: + + image filename + aperture real + annulus real + width_annulus real + sky_mode real + coords *imcur +.fi +.ke + + +.ks +.nf +Hidden parameters: + + fitsky boolean yes + center boolean yes + spool boolean no + output filename "fitpsf.out" + verbose boolean yes +.fi +.ke + + +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. + +.sh +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. + +.sh +3.7 The IMMARK Program + + The function of IMMARK is to draw marks on the diplay device. +IMMARK is useful for verifying coordinate lists. + + +.ks +.nf +parameters: + + mark_type string + mark_size real + coords *imcur +.fi +.ke + + +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. + +.sh +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. + + +.ks +.nf +positional arguments: + + image filename + aperture real + step_size real + annulus real + width_annulus real + sky_mode real +.fi +.ke + + +.ks +.nf +hidden parameters: + + fitsky boolean yes + center boolean yes + verbose boolean yes +.fi +.ke + + +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) + +.nf +where + + r radius in pixels + i(r) raw intensity at r + inorm(r) normalized intensity at r (range 0-1) + fraction(r) fraction of total integral at r +.fi + + +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. + +.sh +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): + +.nf + 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 +.fi + +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). + +.nf + ap> getcols spoolfile,"4-5" | getcols | average + 2.83133 0.0569725 6 +.fi + +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). + + 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: + +.nf + 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): +.fi + +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. + +.nf + ap> lparam apphot > blue.out + ap> apphot >> blue.out & + [1] +.fi + +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. diff --git a/noao/digiphot/apphot/doc/specs/apphot.db b/noao/digiphot/apphot/doc/specs/apphot.db new file mode 100644 index 00000000..df5dc2f3 --- /dev/null +++ b/noao/digiphot/apphot/doc/specs/apphot.db @@ -0,0 +1,366 @@ +# APPHOT.DDF -- Data definition for apphot package output + +builtin catalog functions +builtin domain statements + +------------------------------------------------------------------------------- + +# domain statements + +domain bool type=short format="%b" +domain posint type=short format="%5d" +domain pixels type=real format="%9.3f" +domain fwhmpsf type=real format="%9.3f" +domain counts type=real format="%15.7g" +domain sigma type=real format="%15.7g" +domain mag type=real format="%7.3f" +domain pars type=real format="%15.7g" +domain electrons type=short format="%5d" +domain ratio type=real format=%15.7g" + +# Apphot database descriptor +record apphot { + iraf char[] "current version of iraf" + host char[] "host machine" + user char[] "user name" + package char[] "package name" + version char[] "package version" +} + +-------------------------------------------------------------------------------- + +# History record (1 per modification of the apphot database) +record history { + task char[] "task name" + date ltime "date dask was run" + firstrec posint "first record written by task" + lastrec posint "last record written by task" +} + +------------------------------------------------------------------------------ + +# Data dependent parameter set (>= 1 per task execution) +record datapars { + fwhmpsf pixels "full width half max of the psf" + emission bool "emission/absorption" + noise model char[] "data noise mode" + threshold counts "intensity threshold" + sigma counts "sigma of sky pixels" + gain char[] "image gain keyword" + epadu ratio "gain electrons/adu" + ccread char[] "image readout noise keyword" + readnoise electrons "readout noise electrons" +} + +# Centering algorithm parameter set (>= 1 per task execution) +record centerpars { + calgorithm char[] "centering algoritm" + cboxwidth fwhmpsf "centering box width" + maxshift fwhmpsf "maximum shift" + cmaxiter posint "maximum number of iterations" + minsnratio ratio "minimum signal to noise ratio" + clean bool "use clean algorithm" + rclean fwhmpsf "cleaning radius" + rclip fwhmpsf "clipping radius" + kclean sigma "sigma clean" +} + +# Sky fitting algorithm parameter set (>= 1 per task execution) +record fitskypars { + salgorithm char[] "sky fitting algorithm" + annulus fwhmpsf "inner sky annulus" + dannulus fwhmpsf[] "width of inner sky annulus" + smaxiter posint "maximum number od iterations" + skreject sigma "ksigma rejection" + snreject posint "maximum number of rejections" + khist sigma "half width of histogram" + binsize sigma "binsize of histogram" + smooth bool "smooth the histogram" + rgrow fwhmpsf "region growing radius" + skyvalue counts "user supplied sky value" +} + +# Photometry parameter set (>= 1 per task execution) +record photpars { + weighting char[] "weighting scheme" + apertures fwhmpsf "list of apertures" + zmagnitude mag "magnitude zero point" + exposure char[] "image exposure time keyword" + itime "" "exposure time" +} + +# Polygonal photometry parameter set (>= 1 per task execution) +record polypars { + zmagnitude mag "magnitude zero point" + exposure char[] "image exposure time keyword" + itime "" "exposure time" +} + +# Radial profile fitting parameters (>= 1 per task execution) +record radprofpars { + radius fwhmpsf "maximum profile radius" + stepsize fwhmpsf "profile step size" + order posint "number of spline pieces in fit" + kreject sigma "k sigma rejection" + nreject posint "max number of rejection cycles" +} + +# Point spread function modeling parameters (>= 1 per task execution) +record psfpars { + function char[] "analytic function" + box fwhmpsf "fitting box size" + kreject sigma "sigma rejection limit" + nreject posint "max number of rejections" +} + +-------------------------------------------------------------------------------- + +# Computed center answers (1 per star) +record center { + + datapars posint "record id of datapars record" + centerpars posint "record id of centerpars record" + + image char[] "image name" + xinit pixels "initial x position" + yinit pixels "initial y position + id posint "sequence number in table" + coords char[] "coordinate list filename" + lid posint "sequence number in coord list" + + xcenter pixels "x center position" + ycenter pixels "y center position" + xshift pixels "x position shift" + yshift pixels "y position shift" + xerror pixels "x position error" + yerror pixels "y position error" + cerrcode posint "centering error code" + cerrstring char[] "centering error message" + +} + +# Computed fitsky answers (1 per star) +record fitsky { + + datapars posint "record id of datapars record" + fitskypars posint "record id of fitskyprs record" + + image char[] "image name" + xinit pixels "initial x position" + yinit pixels "initial y position + id posint "sequence number in table" + coords char[] "coordinate list filename" + lid posint "sequence number in coord list" + + skyvalue counts "sky value" + skysigma counts "standard deviation of sky" + skyskew counts "skew of sky pixels" + nskypix posint "number of sky pixels" + nskyreject posint "number of rejected pixels" + serrcode posint "sky fitting error code" + serrstring char[] "sky fitting error message" + +} + +# Computed phot answers (1 per star) +record phot { + + datapars posint "record id of datapars record" + centerpars posint "record id of centerpars record" + photpars posint "record id of photometry record" + + image char[] "image name" + xinit pixels "initial x position" + yinit pixels "initial y position + id posint "sequence number in table" + coords char[] "coordinate list filename" + lid posint "sequence number in coord list" + + xcenter pixels "x center position" + ycenter pixels "y center position" + xshift pixels "x position shift" + yshift pixels "y position shift" + xerror pixels "x position error" + yerror pixels "y position error" + cerrcode posint "centering error code" + cerrstring char[] "centering error message" + + skyvalue counts "sky value" + skysigma counts "standard deviation of sky" + skyskew counts "skew of sky pixels" + nskypix posint "number of sky pixels" + nskyreject posint "number of rejected pixels" + serrcode posint "sky fitting error code" + serrstring char[] "sky fitting error message" + + aperts pixels[] "list of apertures" + sums counts[] "list of sums" + areas pixels[] "list of areas" + mags mag[] "list of magnitudes" + magerrs mag[] "list of mag errors + merrcodes posint[] "list of errcodes + merrstrings char[] "list of error messages" + +} + +# Computed wphot answers (1 per star) +record wphot { + + datapars posint "record id of datapars record" + centerpars posint "record id of centerpars record" + fitskypars posint "record id of fitskypars record" + photpars posint "record id of photpars record" + + image char[] "image name" + xinit pixels "initial x position" + yinit pixels "initial y position + id posint "sequence number in table" + coords char[] "coordinate list filename" + lid posint "sequence number in coord list" + + xcenter pixels "x center position" + ycenter pixels "y center position" + xshift pixels "x position shift" + yshift pixels "y position shift" + xerror pixels "x position error" + yerror pixels "y position error" + cerrcode posint "centering error code" + cerrstring char[] "centering error message" + + skyvalue counts "sky value" + skysigma counts "standard deviation of sky" + skyskew counts "skew of sky pixels" + nskypix posint "number of sky pixels" + nskyreject posint "number of rejected pixels" + serrcode posint "sky fitting error code" + serrstring char[] "sky fitting error message" + + aperts pixels[] "list of apertures" + sums counts[] "list of sums" + areas pixels[] "list of areas" + mags mag[] "list of magnitudes" + magerrs mag[] "list of mag errors + merrcode posint[] "list of errcodes + merrstrings char[] "list of error messages" +} + +# Computed polyphot answers (1 per star) +record polyphot { + + datapars posint "record id of datapars record" + centerpars posint "record id of centerpars record" + fitskypars posint "record id of fitskypars record" + polypars posint "record id of polypars record" + + image char[] "image name" + xinit pixels "initial x position" + yinit pixels "initial y position + id posint "sequence number in table" + coords char[] "coordinate list filename" + lid posint "sequence number in coord list" + + xcenter pixels "x center position" + ycenter pixels "y center position" + xshift pixels "x position shift" + yshift pixels "y position shift" + xerror pixels "x position error" + yerror pixels "y position error" + cerrcode posint "centering error code" + cerrstring char[] "centering error message" + + skyvalue counts "sky value" + skysigma counts "standard deviation of sky" + skyskew counts "skew of sky pixels" + nskypix posint "number of sky pixels" + nskyreject posint "number of rejected pixels" + serrcode posint "sky fitting error code" + serrstring char[] "sky fitting error message" + + sum counts[] "aperture sum" + area pixels[] "aperture area" + mag mag[] "magnitude" + magerr mag[] "magnitude error" + merrcode posint[] "error code" + merrstring char[] "error message" + + polygons char[] "name of polygons files" + pid posint "polygon sequence number" + oldxmean pixels "original mean x of polygon" + oldymean pixels "original mean y of polygon" + minradius pixels "min sky radius to exclude polygon" + nver posint "number of vertices" + xvertices pixels[] "list of x vertices coords" + yvertices pixels[] "list of y vertices coords" +} + +# Computed radprof answers (1 per star) +record radprof { + + datapars posint "record id of datapars record" + centerpars posint "record id of centerpars record" + fitskypars posint "record id of fitskypars record" + photpars posint "record id of photpars record" + radprofpars posint "record id of radprofpars record" + + image char[] "image name" + xinit pixels "initial x position" + yinit pixels "initial y position + id posint "sequence number in table" + coords char[] "coordinate list filename" + lid posint "sequence number in coord list" + + xcenter pixels "x center position" + ycenter pixels "y center position" + xshift pixels "x position shift" + yshift pixels "y position shift" + xerror pixels "x position error" + yerror pixels "y position error" + cerrcode posint "centering error code" + cerrstring char[] "centering error message" + + skyvalue counts "sky value" + skysigma counts "standard deviation of sky" + skyskew counts "skew of sky pixels" + nskypix posint "number of sky pixels" + nskyreject posint "number of rejected pixels" + serrcode posint "sky fitting error code" + serrstring char[] "sky fitting error message" + + aperts pixels[] "list of apertures" + sums counts[] "list of sums" + areas pixels[] "list of areas" + mags mag[] "list of magnitudes" + magerrs mag[] "list of mag errors + merrs posint[] "list of error codes + merrstrings char[] "list of error messages" + + pfwhm pixels "fitted profile fwhmpsf" + inorm counts "intensity normalization factor" + tinorm counts "total intensity normalization factor" + errcode posint "error code" + errstring char[] "error message" + rlist pixels[] "radii" + intensities counts[] "fitted intensities" + tintensities counts[] "integral of fitted total intensities" +} + +# Computed fitpsf answers (1 per star) +record fitpsf { + + datapars posint "record id of datapars record" + fitpsfpars posint "record id of fitpsf record" + + image char[] "image name" + xinit pixels "initial x position" + yinit pixels "initial y position + id posint "sequence number in table" + coords char[] "coordinate list filename" + lid posint "sequence number in coord list" + + npars posint "number of parameters" + params pars[] "list of parameters" + parerrs pars[] "list of parameter errors" + +} + +------------------------------------------------------------------------------- diff --git a/noao/digiphot/apphot/doc/specs/apphot.spc b/noao/digiphot/apphot/doc/specs/apphot.spc new file mode 100644 index 00000000..ecfdf364 --- /dev/null +++ b/noao/digiphot/apphot/doc/specs/apphot.spc @@ -0,0 +1,1296 @@ +.EQ +delim $$ +.EN + +.RP +.TL +Specifications for the Aperture Photometry Package +.AU +Lindsey Davis +.AI +.K2 "" "" "*" +Revised October 1987 + +.AB +The APPHOT package is a set of tasks for performing aperture photometry +on uncrowded or moderately crowded fields, in either interactive or batch mode. +The photometric technique employed is fractional pixel aperture +integration. Point spread function fitting techniques are not used and no +knowledge of the point spread function is required for the computation of +magnitudes. Separate tasks are provided for creating and modifying object lists, +computing accurate centers for a list of objects, computing sky values for +a list of objects and performing aperture photometry inside circular or +polygonal apertures. +.AE + +.NH +Introduction +.PP +The APPHOT package is a set of tasks for performing +aperture photometry on uncrowded or moderately crowded fields. +The photometric technique employed is fractional pixel integration. Point +spread function techniques are not used and no knowledge of the point spread +function is required for the computation of magnitudes. +.PP +The APPHOT package performs multi-aperture photometry on digitized starfields +maintained as IRAF image files. Input to the package consists of an +image file, a list of object coordinates, numerous parameters controlling +the analysis algorithms and, optionally, the graphics terminal and/or +display. APPHOT output consists of successive lines of text where each line +summarizes the results of the analysis for a particular object. +.PP +Given starting coordinates and an IRAF image, the principal APPHOT +task computes accurate centers, sky values and magnitudes +for a list of objects. Separate +IRAF callable tasks in APPHOT exist to create and modify object +lists, to determine image characteristics such as the full width half maximum +of the point spread function or standard deviation of the sky pixels, +to compute accurate centers for a list of objects, to compute accurate local sky +values for a list of objects, and to compute magnitudes inside a polygonal +aperture. + +.NH +APPHOT Package Requirements +.NH 2 +APPHOT Package Input +.NH 3 +The IRAF Image +.PP +APPHOT assumes that images exist on disk in IRAF format. Facilities for reading +and writing images exist elsewhere in IRAF such as in package DATAIO or +MTLOCAL. +.PP +APPHOT assumes that the image data is linear. +The input image is assumed to have been corrected for those instrumental +defects which affect the intensity of a pixel. These include pixel to +pixel variations in the bias values, pixel to pixel gain variations, +cosmic rays, cosmetic defects, geometric distortion, +and detector non-linearities. +.PP +APPHOT assumes that the local sky background is approximately flat in the +vicinity of the object being measured. This assumption is equivalent to +assuming that the local sky region has a unique mode. Therefore any +variations in the sky background which occur at the same scale as the +sky region should be removed prior to entering APPHOT. +.PP +The point spread function of the image is assumed to be constant for all +regions of the image. This is particularly critical in the case of faint objects +for which small apertures which minimize the effects of crowding and +sky noise in the aperture are used. The wings of the object will +almost certainly extend beyond the aperture and good results will only be +obtained if +objects are consistently well centered and the shape and diameter of an object +is constant throughout the image and invariant to magnitude. + +.NH 3 +The Coordinate Lists +.PP +All APPHOT tasks operate on lists of object coordinates or interactive cursor +input. Lists are maintained as text files, +one object per line with the x and y coordinates in +columns one and two respectively. List files may be created interactively +with either the graphics or image cursor, by a previously executed APPHOT +task, by a previously executed IRAF task or by a user task. +.PP +The x and y coordinates contained in the list file can be either the +starting centers for the objects of interest or the true centers. +In either case the aperture centered around the object position must +not extend beyond the boundary of the image. To obtain reliable results +from the centering algorithm the starting centers should not be more than +1 fwhmpsf pixels from the true centers. + +.NH 3 +Algorithm Parameters +.PP +Many tasks in the APPHOT package have an associated set of algorithm parameters +which control the operation of the analysis routines. For example the +centering and sky fitting algorithms each have an associated group of +parameters. +The APPHOT tasks supply reasonable defaults for these parameters. However +the user may alter them at any time in interactive mode or by editing the +appropriate parameter file before running the task in batch. + +.NH 3 +Terminal Graphics and the Image Display +.PP +Most APPHOT programs may be run in either interactive or batch mode. +In interactive mode, the user can mark the positions of objects by +interactively, positioning the image cursor on the display device. +Simple cursor commands can interactively alter the algorithm parameters. +In batch mode the algorithm parameters are +fixed and object coordinates are taken from the user supplied coordinate list. +The display device is not required in batch mode. +.PP +At present there is no high level IRAF display interface. Therefore the present +version of APPHOT replaces the display device with terminal +graphics. For example it is possible to load a contour plot of an image +or image section, and run the APPHOT tasks, interactively marking +positions on the plot. This is a temporary measure to tide thing over until +the display interface is available. Furthermore this option is only +really suitable for those terminal which have both text and graphics +windows displayed at the same time. +.PP +Certain APPHOT tasks such as FITSKY occasionally require an interactive graphics +capability. For example it is sometimes desirable to plot the histogram +of the sky pixels and mark the peak of the histogram interactively rather +than using the automatic sky fitting routines. +Graphics capablity has been added to APPHOT tasks as deemed useful. + +.NH 2 +APPHOT Package Functions +.NH 3 +Creating Coordinate Lists +.PP +APPHOT task(s) shall exist to create coordinate lists interactively within +APPHOT by loading the IRAF image into the image display +and successively marking the objects to be measured with the image cursor. +It shall be possible to mark the positions of objects on the display, and draw +circles of arbitrary size around the objects of interest. +It shall be possible to verify existing coordinate lists by marking the object +coordinates on the image display. +.PP +At present the full image display cababilities do not exist in IRAF. +Therefore as a temporary measure most tasks will run with a contour +plot and the graphics cursor as a substitute for the image display and +image cursor by setting the image cursor to stdgraph and the display +parameter for each task to stdgraph. +The output coordinates will be written to a text file and may be used as +starting coordinates for the APPHOT routines. +.PP +Those sites which have SUN workstations can use the IMTOOL facilites to +create cursor lists. +.PP +APPHOT tasks shall exist to automatically detect objects by specifying the IRAF +image to be searched, plus a few image characteristics such as a detection +threshold and the full width half maximum of the point spread function. +The output coordinates plus a few object statistics will be written to a +text file. + +.NH 3 +Coordinate List Operations +.PP +General list processing tasks are or will be available in the IRAF lists +package. Examples of useful currently existing tasks are list sorting by for +example magnitude and performing a linear transformations +on coordinate lists. +.PP +It may eventually be necessary to add some specialized list processing tasks +to APPHOT. One example is a list matching facility in which objects in +common to two lists are combined and output to a third list. + +.NH 3 +Determining the Image Characteristics +.PP +APPHOT tasks shall exist to estimate certain image +characteristics such as the full width half maximum of the image point spread +function and the standard deviation of the background. In order to obtain +meaningful error estimates it is also necessary to specify the noise +charactersitics of the detector and a noise model. +In this version of APPHOT two noise +functions will be supported a constant sky background noise, +and constant background noise plus Poisson statistics in the object. +.PP +The reason for this capability is that the majority of the APPHOT +algorithm parameters scale with these two image characteristics. +For example all the pixel scale dependent parameters such as the centering +aperture, object apertures, the two sky annuli and the +maximum shift parameter all scale with the full width half +maximum of the point spread function. Similarly most of the pixel intensity +dependent parameters scale with the standard deviation of the sky pixels. + +.NH 3 +Centering +.PP +An APPHOT task shall exist to determine accurate centers for a list of objects, +using the approximate object coordinates as a starting point. +The centering aperture may extend beyond the boundaries of the image but +a warning message will be generated. +.PP +A choice of centering algorithms with a range of efficiency and accuracy will +be available. The center determination must be resistant to the affects of +nearby contaminating objects. +.PP +The user may opt to use the starting center as the actual center in all cases, +to use the starting center as the actual center if the object is very faint, +or tweak up the center if the signal to noise is above a certain threshold. +.PP +The output of the centering algorithm will the set of computed coordinates +and their errors. + +.NH 3 +Fitting the Sky +.PP +An APPHOT task shall exist to compute 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 background shall +be excluded from the fit. +.PP +The user may supply a constant background, with zero-valued noise and skew +value or read appropriate values from a file instead of computing the +background. +.PP +The output of the sky fitting algorithm shall be +the mode, standard deviation and skew of the sky as well as the number +of pixels left in the background region after pixel rejection and the number +rejected. + +.NH 3 +Multi-aperture Photometry +.PP +APPHOT routines shall exist to compute 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. Both normal and weighted photometry routines shall +be available. +.PP +It shall be possible to normalize the output magnitudes to a user specified +integration time using values stored in the IRAF image header. +.PP +The output shall consist of magnitudes and errors for each of the specified +apertures. +.NH 3 +Polygonal Aperture Photometry +.PP +Determine the integral of the object within a specified +polygon. Aperture integration shall be by fractional pixel summation +of successive image lines. + +.NH +Specifications +.NH 2 +Apphot CL Callable Tasks +.PP +The CL callable part of the APPHOT package consists of the following +routines:\fL + +.nf +.na + mark -- create/verify coordinate lists interactively + polymark -- create/verify polygon lists interactively + daofind -- automatic image finder from DAOPHOT + lintran -- linearly transform a list of coordinates (LISTS package) + + radprof -- compute the radial profile of an object. + fitpsf -- model the PSF + + center -- compute accurate centers for a list of objects + fitsky -- compute accurate sky values for a list of objects + phot -- perform multi-aperture photometry on a set of objects + polyphot -- compute the flux inside a set of irregular polygons\fR + wphot -- perform weighted multi-aperture photometry +.ad +.fi + +.NH 2 +Standard Analysis Procedures +.PP +A standard reduction procedure would be something as follows. +.IP 1. +Estimate the image and data characteristics in the following manner. +.RS +.IP 1. +Use the interactive setup option (i key) in the PHOT task to specify the +fwhm of the psf, +the centering apperture, the sky annuli, the photometry apertures as +well as estimate the sky sigma. +Examine the results (:show command) and optionally store the +new parameters in the parameter files (w key). +.IP 2. +Use the EPAR task to edit the parameter files directly. For example the +detector gain and readout noise must be known before running PHOT in +order to get reliable error estimates. +.RE +.IP 2. +Prepare a coodinate list in one of the following ways. +.RS +.IP 1. +Running MARK or POLYMARK. +.IP 2. +Run DAOFIND or some other automatic image finder. +.IP 3. +Run another APPHOT task such as CENTER . +.IP 4. +Run any other IRAF or user program which generates the appropriate +format. +.IP 5. +Transform an existing list using the LISTS package facilities +.RE +.IP 3. +Run PHOT or WHOT in non-interactive mode to perform the multi-aperture +photometry. The user should be familiar +with the algorithms used to measure the object center, to fit the background, +and compute the aperture integral, magnitude, and errors. The values of +all visible and hidden PHOT parameters should be inspected before doing +any serious processing. Note that CENTER and FITSKY can be run independently +of PHOT and their output used as input to PHOT. +.EQ +delim $$ +.EN + +.NH 2 +The APPHOT Algorithms +.PP +The principal APPHOT algorithms are described below. + +.NH 3 +The RADPROF Algorithm +.PP +The function of the RADPROF task is to compute the radial profile of +selected, isolated, high signal to noise objects in an IRAF image. +.PP +Given the IRAF image, an initial center, an aperture and a step size, +RADPROF computes the radial profile of an object in the following manner. +.IP 1. +The APPHOT centering routines are used to compute an accurate center for the +object. The new center is used to compute the radial coordinate for each +pixel in the subraster. +.IP 2. +The APPHOT sky fitting routines are used to compute an accurate sky value +for the object. The new sky value is used to compute the object intensity +for each pixel in the subraster. +.IP 3. +The CURFIT package routines are used to produce a smooth intensity versus +radius curve by fitting a cubic least squares spline function to the data +using linear least squares techniques. +.IP 4. +The fitted curve is evaluated at equally spaced intervals to produce the +final radial profile. The profile is normalised using the r = 0 value. +.IP 5. +The smoothed curve is integrated using the +1D integration routines IMINTERP to evalute the fraction of the total +integral at each interval. +.IP 6. +The three quantities $I sub r$ the raw intensity, $Inorm sub r$ the +normalized intensity, and $Ifraction sub r$ the fraction of the total +intensity inside radius at r, are plotted on the terminal and +output as a function of r to a text file. +.PP +RADPROF is used principally to compute the stellar image and setup the +parameters for doing photometry. Its default output is a radial profile +plot with the phot parameters marked on it. + +.NH 3 +The FITPSF Algorithm +.PP +The function of the FITPSF task is to fit an analytic model to an object +in order to derive information about the point spread function. Given +an IRAF image, an initial center and an aperture, FITPSF computes the +model parameters in the following manner. +.IP 1. +The fitting function is chosen. +The present version of FITPSF offers two function choices a 2D radial Gaussian +function and an elliptical Gaussian function. +A third option, moment analysis, has been added to the FITPSF package. +The image characteristics are evaluted by using the 0th, 1st and 2nd order +moments of the image. +.IP 2 +Initial guesses for the parameters are made from the subraster data. +.IP 3 +The parameters and their errors are derived using standard non-linear least +squares techniques and the NLFIT package. + +.NH 3 +The DAOFIND Algorithm +.PP +The function of the DAOFIND task is to automatically detect objects +in an IRAF image above a certain intensity threshold. +The user specifies an intensiyt threshold, +the estimated full width half maximum of +the point spread function, +and limits on the sharpness and roundness of the objects to be detected. +DAOFIND produces a list of x and y coordinates and a sharpness +and roundness statistic for each detected object. +.PP +The DAOFIND algorithm works in the following way. +.IP 1. +The user specifies an intensity threshold above local sky and estimates +the full width half maximum of the point spread function. +.IP 2. +DAOFIND computes a convolution kernel which is a linear +function of the brightness values in an approximately circular array of +pixels. The original data is convolved with the computed kernel. +The equivalent mathematical +operation is a convolution of the original data +with truncated, lowered circular Gaussian function with the specified FWHM, +computed in such a way as to be the mathematical +equivalent of fitting a Gaussian stellar profile to the object data by least +squares. The coefficients of the linear function sum to zero so that the +overall bias level (local sky) cancels out exactly. Since the function is +symmetric about a single pixel, a smooth gradient in the sky brightness +also cancels exactly. Therefore the user does not have to specify an +absolute brightness threshold but only a threshold above local sky. +.IP 3 +The convolved data is searched for local maxima. Local maxima which are +less than the specified threshold are rejected. A pixel is defined to be +a local maximum when it is the brightest pixel within +$n ~*~ sigma sub Gauss$. +.IP 4. +Using the original data, DAOFIND computes an object sharpness statistic which +can be used to reject +hot or cold pixels. The sharp parameter is defined below. +Detected objects with a sharpness parameter outside the range specifed +by sharplo and sharphi are rejected. Typical values for sharplo and +sharphi are 0.2 and 1.0 respectively. +.nf + + $I sub delta$ = height of best fitting $delta$ function = pixel value + + $I sub Gauss$ = height of best fitting Gaussian function = convolved value + + sharplo <= sharp = ${I sub delta} over {I sub Gauss}$ <= sharphi + +.fi +If the brightness enhancement detected in the convolved data is due to +a single bright pixel, then the best fitting delta function will have an +amplitude equal to the height of this pixel above the local background, +while the amplitude of the best fitting Gaussian will be pulled down by +the surrounding low valued pixels. Sharp will be a number significantly +greater than one. A single cold pixel will produce +brightness enhancements approximately 0.5 * FWHM away +from the pixel in question in all directions. In this case the height +of the delta +function which best fits these spurious maxima is close to zero, while the +height of the best fitting Gaussian is some small positive number. +In this case sharp will be close to zero. +.IP 5. +The roundess statistic is computed from the original picture data by fitting +1D Gaussians +to the marginal sums in x and y. If the height of either 1D +Gaussian is negative the object is rejected. If both heights are +positive the roundness parameter is computed. +.nf + + $DELTA I ~=~ I sub {x ~ Gauss} ~-~ I sub {y ~ Gauss}$ + + $<I> ~=~ I sub {x ~ Gauss} ~+~ I sub {y ~ Gauss}$ + + $roundlo ~<=~ round ~=~ {DELTA I} over <I> ~<=~ roundhi$ + +.fi +Objects which are elongated in the +x direction have roundness values less than zero and those elongated in +the y direction have roundness greater than zero. +Round discriminates only against objects which are elongated +along either rows or columns. Objects elongated at a 45 degree angle will +not be rejected. +.IP 6. +Finally the approximate x and y centroids of the detected objects, +rough magnitudes relative to threshold are computed, and object is added +to the output file. + + +.NH 3 +The CENTER Task + +.NH 4 +Centering Package Routines +.PP +The following are the principal programmer callable routines routines in the +centering package. +.nf +\fL + + apcinit (ap, cfunction, cbox, fwhmpsf, noise) + ier = apfitcenter (ap, im, xinit, yinit) + ier = aprefitcenter (ap) + value = apstat[ir] (ap, param) + apstats (ap, param, str, maxch) + apset[sir] (ap, param, value) + apcfree (ap) + +\fR +.fi +.PP +The following quantities can be examined or set by apstat/apset calls +.nf +\fL + data 1. fwhmpsf full width half maximum of psf in pixels +parameters 2. threshold minimum intensity for centering + 3. noise noise model + 4. sigma standard deviation of background + 5. readnoise readout noise of CCD in electrons + 6. epadu electrons per adu + +centering 1. calgorithm centering algorithm +parameters 2. positive emission / absorption features + 3. cbox centering radius in fwhmpsf + 4. cmaxiter maximum number of fitting iterations + 5. maxshift maximum permitted shift in fwhmpsf + 6. minsnratio minimum permitted signal to noise ratio + 7. clean clean subraster before centering + 8. rclean cleaning radius in fwhmpsf + 9. rclip clipping radius in fwhmpsf + 10.kclean k-sigma rejection for cleaning in sigma +\fR +.fi + +.PP +The following computed quantities can be examined by apstat calls. +.nf +\fL + 1. xcenter computed x coordinate + 2. ycenter computed y coordinate + 3. xerr computed x coordinate error + 4. yerr computed y coordinate error +\fR +.fi +.PP +See the manual pages for CENTER and CENTERPARS for a detailed description +of the centering parameters. + +.NH 4 +The Centering Algorithm +.PP +The function of the CENTER task is to compute accurate centers and errors +for objects in an IRAF image given a list of initial positions and a +centering aperture. +.IP 1. +If the centering algorithm is disabled, the computed center is set to the +initial center and the uncertainty estimate is set to zero. +.IP 2. +If the cleaning algorithm is enabled, clean the subraster before centering. +.IP 3. +Estimate is made of the signal to noise of the object. If this quantity is +less than a certain minimum value the computed center is kept +but a warning message is issued. +.IP 4. +The center and errors are computed using one of several algorithms. +.IP 5. +If the computed center is greater than a user specified distance from the +initial center then the computed center is returned with an error +message. + +.NH 4 +Symmetry Clean Algorithm +.PP +The symmetry-clean algorithm attempts to remove defects in the centering +subraster by assuming that the object has radial symmetry and comparing +pixels on the opposite sides of the center of symmetry. The algorithm +works in the following way. +.IP 1. +The center of symmetry is computed. Normally the center of symmetry is assumed +to coincide with the position of the brightest pixel in the subarray. +However if the maximum pixel is more than a user specified distance away +from the intial center, the initial center is used as the center of symmetry. +.IP 2. +Pixels inside a specified cleaning radius are unaltered. +.IP 3. +Pairs of pixels diametrically opposed about the center +in the cleaning region between the cleaning and clipping +radii are tested for equality. If the difference between the pixels is +greater than a specified k-sigma rejection limit, the larger value is replaced +by the smaller. +In this region sigma is computed from Poisson statistics. +.IP 4. +Pairs of pixels in the clippping +region are compared in the same manner as those in the cleaning region +except that sigma is the standard deviation of the sky pixels. +.PP +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 distributions. + +.NH 4 +Signal to Noise Estimate + +.PP +The signal to noise of the object is estimated from the data values +in the subraster in the following way. +.nf + + $SNR ~=~ N sub object over {sqrt {n sub pix ~*~sigma sub sky sup 2}}$ + + or + + $SNR ~=~ N sub object over {sqrt {N sub object ~+~ n sub pix~*~sigma sub sky sup 2}}$ + +.fi +where $N sub *$ is the number of counts in the object above threshold, +$sigma sub sky$ +is the standard deviation of the pixels in the sky region and +$n sub pix$ is the number of pixels in the object aperture. +The first approximation corresponds to constant sky noise only, +the second includes Poisson noise in the object. + +.NH 4 +Centroid +.PP +The centroid centering algorithm is similar to that used in MPC and can +be briefly described as follows. For more detailed description +see (Stellar Magnitudes From Digital Pictures, 1980, Adams et al). +.IP 1. +The marginal distributions in x and y are accumulated. +.IP 2. +The intensity weighted centroid positions for the marginals is computed +using only data pixels which are above the threshold intensity. If the +threshold parameter is 0 the mean intensity of the marginal is used +in place of the threshold +.nf + + $I sub i ~=~ I sub i ~-~ threshold ~~~~~ I sub i ~>~ 0.0$ + + $x sub c ~=~ {sum I sub i ~ x sub i} over {sum I sub i}$ + +.fi +.IP 3. +The errors are estimated in the following way +.nf + + $sigma sup 2 ~=~ {sum I sub i ~ x sub i sup 2} over {sum I sub i} ~-~ x sub c sup 2$ + + $err sub xc ~=~ sqrt {{sigma sup 2} ~/~ sum I sub i}$ + +.fi + +.NH 4 +Gaussian Fit to the Marginals +.PP +The fit is performed in the following way. +.IP 1. +The marginal distributions in x and y are accumulated. +.IP 2. +Initial guesses for the parameters of the 1D Gaussians $I sub Gauss$, +$x sub c$ and $I sub sky$ are derived from the marginal distributions +themselves. The width $sigma$ is held constant. +.IP 3. +The best fit parameters and their errors are derived using non-linear +least-squares techniques and the NLFIT package. + +.NH 4 +Optimal Filtering of Marginals +.PP +The fit is performed is the following way. +.IP 1. +The marginal distributions in x and y are accumulated. +.IP 2. +The centroid of the observed distribution is computed by solving the +following equation. +.nf + + $PSI (x sub c ) ~=~ sum omega sub i (x sub c ) ~ PHI sub i ~=~ 0$ + + $omega sub i ~=~ {{partial phi sub i} ~/~ {partial x sub c}} over {phi sub i~+~b}$ + +.fi +The assumptions are that the observed distribution $PHI sub i$ is correctly +modeled by the profile function $phi sub i$. The usual choise of profile +model for centering is a Gaussian. Howver in the interests of speed a triangle +function has been substituted. This causes at most a 7% increase in the +random centering error. +.IP 3. +The startup procedure is based on the following fact. +.nf + + $PSI (x sub n )~>~0~~for~~ x sub n ~<~ x sub c$ + + $PSI (x sub n ) ~<~0~~for~~ x sub n ~>~ x sub c$ + +.fi +The iteration is initialized by assuming that $x sub 1$ = $x sub c$ and +computing $PSI (x sub 1 )$. The initial x +value is incremented by $+- sigma sub Gauss$ depending on the sign of $PSI$. The +search is repeated until $PSI (x sub {n-1})$ and $PSI (x sub n)$ have +opposite signs. At this point the true center is bracketed by the +estimated positions $(x sub n, ~ x sub {n-1})$ and we have a table of at +least 2 values of $PSI (x sub n )$. +.IP 4. +The computation proceeds by interpolating in the table of values for the +estimated position $x sub {n+1}$ where $PSI$ = 0. If the table contains only +two values as may be the case for the inititial interpolation, linear +interpolation is used. In all other cases a quadratic fit to the three +most recent $PSI$ values is used. The computation is complete when +two successive estimates differ by less than some tolerance typically +0.001 pixel. +.IP 5. +The errors are estimated as follows. +.nf + + $sigma sup 2 ~=~ ( {int {( partial phi ~/~ partial x sub c )} sup 2 over { + phi + b}} ) sup -1$ + + $err sub xc ~=~ sqrt {sigma sup 2}$ + +.fi + +.NH 4 +Other Centering Methods +.PP +The code is constructed in such a way that new algorithms may be +easily added at a future date, such as the more sophisticated techniques +required for accurate astrometry. +.EQ +delim $$ +.EN +.NH 3 +The FITSKY Task + +.NH 4 +Sky Fitting Routines + +.PP +The following are the main entry points in the sky fitting package. +.nf +\fL + apsinit (ap, function, annulus, dannulus, fwhmpsf, noise) + ier = apfitsky (ap, im, xpos, ypos, sd, gd) + ier = aprefitsky (ap, sd, gd) + value = apstat[ir] (ap, param) + apstats (ap, param, str, maxch) + apset[irs] (ap, param, value) + apsfree (ap) +\fR +.fi +.PP +The following quantities can be examined or set with apset/apstat calls. +.nf +\fL +data 1. fwhmpsf full width half maximum of the psf +parameters 2. sigma standard deviation of sky pixels + +sky fitting 1. annulus inner radius of sky annulus in fwhmpsf +parameters 2. dannulus outer radius of sky annulus in fwhmpsf + 3. sfunction sky fitting algorithm + 4. smaxiter maximum number of fitting iterations + 5. kreject k-sigma rejection limit sigma + 6. nreject maximum number of rejection cycles + 7. rgrow region growing radius in fwhmpsf + + 8. khist half-wdth of histogram in sigma + 9. binsize binsize of histogram in sigma + 10.smooth Lucy smooth the histogram + + 11.skyfile name of text file containing sky values + 12.skyvaluser supplied constant value for sky +\fR +.fi +.PP +The following computed quantities can only be examined with apstat calls. +.nf +\fL + 1. skymode computed sky value + 2. skysig computed sky sigma + 3. skyskew computed sky skew + 4. nsky number of sky pixels + 5. nsky_reject number of rejected sky pixels +\fR +.fi + +.NH 4 +The Sky Fitting Algorithms +.PP +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. +.PP +The main algorithm used in APPHOT is the following. +.IP 1. +If the skyfitting switch is disabled either read the sky values from a text +file or accept a user supplied constant for the sky. +.IP 2. +Perform the initial sky fit using one of the specified algorithms. The +sky fitting algorithms fall into three general categories, those that use +the actual sky pixel array itself, those that operate on a histogram of +sky values and those that rely on user interaction. +.IP 3. +If the pixel rejection flags are set perform pixels rejection with optional +region growing. + +.NH 4 +Sky Pixel Array Techniques + +.NH 5 +Median +.IP 1. +Sort the array of sky pixels. This is necessary to avoid quantization effects. +.IP 2. +Compute the median, and the standard deviation and skew with respect to the +mean. +.IP 3. +If the k-sigma rejection limit is greater than zero and the maximum number +of rejection cycles is greater than one, perform pixel rejection. +Pixels greater than k-sigma from the median are rejected. Region growing +is optional. +.IP 4. +Stop the rejection cycle on any given iteration if the maximum number of +rejection cycles ix exceeded, no more sky pixels are left or no more +pixels are rejected. + +.NH 5 +Mode +.IP 1. +Sort the array of sky pixels. This is necessary to avoid quantization effects. +.IP 2. +Compute the mode, and the standard deviation and skew +with respect to the mean. +.nf + + $I sub mode ~=~ 3.0 ~*~ I sub median ~-~ 2.0 ~*~ I sub mean$ + +.fi +.IP 3. +If the k-sigma rejection limit is greater than zero and the maximum number +of rejection cycles is greater than one, perform pixel rejection. +Pixels greater than k-sigma from the mode are rejected. Region growing +is optional. +.IP 4. +Stop the rejection cycle on any given iteration if the maximum number of +rejection cycles ix exceeded, no more sky pixels are left or no more +pixels are rejected. + + +.NH 4 +Histogram Techniques +.PP +The following three techniques all operate on the histogram of the sky pixels. +The routines all construct the histogram in the following identical manner. +.IP 1. +The mean of the sky distribution is computed. +.IP 2. +If the user specified standard deviation of the sky pixels is INDEF the +algorithm computes the standard deviation of the sky pixels with respect +to the mean. +.IP 3. +All pixels within plus or minus sigma standard +deviations are accumulated into a histogram. The user specifies the bin size. +.IP 4. +The histogram may optionally be Lucy smoothed before any operation is performed +on it. + +.NH 5 +Centroid +.PP +The mode, sigma and skew of the sky pixels are computed in the following +manner. +.IP 1. +The histogram is compiled as above. +.IP 2. +The mode, standard deviation and skew of the sky pixels are computed in the +following manner. + +.nf + $I sub 0 ~=~ sum I sub i$ + $I sub 1 ~=~ sum I sub i ~ x sub i$ + $I sub 2 ~=~ sum I sub i ~ x sub i sup 2$ + $I sub 3 ~=~ sum I sub i ~ x sub i sup 3$ + + $I sub mode ~=~ {I sub 1} ~/~ {I sub 0}$ + $sigma ~=~ {( I sub 2 ~/~ I sub 0 ~-~ I sub mode sup 2 )} sup {1/2}$ + $skew ~=~ ( {I sub 3 ~/~ I sub 0 ~-~ I sub mode ~*~ sigma sup 2 ~-~ I sub mode sup 3} ) sup {1/3}$ + +.fi +.IP 3 +If pixel rejection is enabled sky pixels within a user supplied limit of +the mode are rejected with optional region growing. + +.NH 5 +Gaussian Fit +.PP +The mode, standard deviation and skew of the sky pixels are derived from a +model fit in the following way. +.IP 1. +The histogram of the sky pixels is compiled as above. +.IP 2. +Initial guesses to the model parameters, $N sub max$, $I sub mode$, +$sigma$, and $skew$ are made from the histogram itself. +.IP 3. +Final parameters and their errors are derived using non-linear least squares +techniques and the NLFIT package. +.IP 4. +If pixel rejection is enabled sky pixels within a user supplied limit of +the computed mode are rejected with optional region growing. + +.NH 5 +Optimal Filtering +.PP +The method is as follows. +.IP 1. +The histogram is compiled as above. +.IP 2. +Using the mean of the sky pixels as the intital value of the sky mode, +a new mode is computed using the optimal filtering technique +described for centering. +.IP 4 +If pixel rejection is enabled sky pixels within a user supplied limit of +the computed mode are rejected with optional region growing. + +.NH 5 +Cross Correlation +.PP +The method is as follows. +.IP 1. +The histogram is compiled as above. +.IP 2. +The noise function is estimated using the standard deviation of the sky +pixels and the cross-correlation function is computed. +.IP 3. +The mode is computed using quadratic interpolation around the peak of the +distribution. +.IP 4 +If pixel rejection is enabled sky pixels within a user supplied limit of +the mode are rejected with optional region growing. + +.NH 4 +Interactive Techniques + +.NH 5 +Histogram Plot +.PP +The histogram is compiled as described above and the user marks the peak +on the histogram plot with the graphics cursor. The sigma and skew of the +sky distribution with respect to the mean is also computed. + +.NH 5 +Radial Distribution +.PP +A radial profile plot of the sky region is plotted and the user marks the +sky value on the plot with the graphics cursor. The sigma and skew of the sky +distribution with respect to the mean is computed. + +.NH 4 +Pixel Rejection and Region Growing +.PP +All the sky fitting algorithms permit pixel rejection and +optional region growing. +Pixel rejection and region growing are +performed by locating all pixels more than k * 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. +.PP +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. + +.NH 4 +The Principal PHOT Routines +.PP +The main entries in the photometry routine are the following. +.nf +\fL + apinit (ap, cfunction, cbox, sfunction, annulus, dannulus, + aperts, napert, fwhmpsf, noise) + ier = apfitcenter (ap, im, xinit, yinit) + ier = aprefitcenter (ap) + ier = apfitsky (ap, im, xcenter, ycenter, sd, gd) + ier = aprefitsky (ap, sd, gd) + ier = apmag (ap, im, xcenter, ycenter, skyval, skysig, nsky) + ier = apwmag (ap, im, xcenter, ycenter, positive, skyval, skysig, nsky) + ier = apremag (ap, positive, skyval, skysig, nsky) + ier = apwremag (ap, positive, skyval, skysig, nsky) + value = apstat[ir] (ap, param) + apstats (ap, param, str, maxch) + apset[sir] (ap, param, value) + apfree (ap) + +\fR +.fi +.PP +The following parameters can be examined or altered by apset/apstat calls. +.nf +\fL + 1. weighting weighting scheme for wphot + 2. aperts list of apertues + 3. naperts number of apertures + 4. zmag zero point of magnitude scale + 5. itime effective integration time +\fR +.fi +.PP +The following quantities can be examined with apstat calls. +.nf +\fL + + 1. sums array of aperture sums + 2. areas array of areas + 3. mags array of magnitudes + 4. magerrs array of magnitude errors + +\fR +.fi + +.NH 4 +The PHOT Aperture Integration Algorithm +.PP +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. +.PP +The inclusion of a partial pixel inside the aperture is done as follows. +.IP 1. +If the distance of the current pixel from the center of the star, r, is +exactly equal to the radius of the aperture R then one-half the counts in +the pixel are included. +.IP 2. +If r < R - 0.5 the entire pixel is included while if r > R + 0.5 the pixel +is wholly excluded. +.IP 3. +In between the fraction of the counts varies linearly. A circular aperture +is approximated by an irregular polygon. +.PP +The simplicity of aperture photometry limits the amount of information +available for error analysis. The following three sources of error are +considered. +.IP 1. +The error due to sky noise in the aperture. +.nf + + $error sub 1 ~=~ sigma sub sky ~*~ {A sub apert} sup {1/2}$ + +.fi +.IP 2. +The error in the aperture sum. +.nf + + $error sub 2 ~=~ ( {A sub "sum" ~/~ phpadu} ) sup {1/2}$ + +.fi +.IP 3. +The mean error of the sky. +.nf + + $error sub 3 ~=~ sigma sub sky ~*~ A sub apert ~/~ nsky sup {1/2}$ + + +.fi +where $sigma sub sky$ is either computed by the background fitting +algorithm or set by the user, +and $A sub apert$ is the fractional pixel area of the +aperture. + +.NH 4 +The WPHOT Algorithm +.PP +The WPHOT algorithm computes a weighted aperture sum in an attempt to +minimize noise in the sky. The algorithm is the following where w is +the weight for each pixel, p is the noise free profile value and +$sigma$ is the noise per pixel from all sources. (See the paper +by Stover and Allen 1987 for details) +.nf + + $A sub sum ~=~ sum {w sub i ~*~ (I sub i ~-~ sky)}$ + + $w sub i ~=~ C ~*~ p sub i ~/~ sigma sup 2 sub i$ + + $C ~=~ sum {p sub j} / sum {p sub j ~*~ w sub j}$ +.fi + +.NH 4 +The POLYPHOT ROUTINES +.PP +The principal polyphot routines are the following. + +.nf +\fL + apyinit (ap, sfunction, annulus, dannulus, noise) + ier = apfitcenter (ap, im, wx, wy) + ier = aprefitcenter (ap) + ier = apfitsky (ap, im, xcenter, ycenter, sd, gd) + ier = aprefitsky (ap, sd, gd) + ier = polyfit (ap, im, xver, yver, nver) + value = apstat[ir] (ap, param) + apstats (ap, param, str, maxch) + apset[sir] (ap, param, value) + apfree (ap) + +\fR +.fi + +.PP +.NH 4 +The POLYPHOT Algorithm +.PP +The function of the POLYPHOT task is to compute the flux inside an +irregular polygon given a list of the coordinates of the vertices of a polygon. +The polygon must be entirely inside the image and the vertices of the polygon +must be specified in clockwise or counterclockwise order. +The actual algorithm used is as follows. +.IP 1. +The range of image lines which intersect the polygon are computed. +.IP 2. +For each image line in the specified range the intersection points with the +polygon are computed. +.IP 3. +The flux between pairs of limits is summed using a fractional pixel +approximation for the endpoints. +.IP 4. +The sky is fitted using any of the methods previously discussed and a +user specified annular region. +.IP 5. +The errors are computed as specified in the PHOT specifications. +.PP +.EQ +delim $$ +.EN + +.NH +Example +.PP +A brief example may help illustrate the use of the package. Suppose +we want to process a few hundred stars on image "blue". +.PP +The first step is to prepare a list of objects to be measured. The simplest +way to do this is to interactively mark the objects with the image +cursor using the display (graphics) device and the RIMCURSOR (RGCURSOR) +task. +.nf +\fL + + ... load image on the display ... + + ap> rimcursor > starlist + + ... move cursor and mark stars ... + + + ... load contour plot on graphics terminal ... + + ap> rgcursor > starlist + + ... move cursor and mark stars ... +\fR +.fi + +Alternatively one can run DAOFIND to compute a list of candidate objects +in the frame. +The name of the coordinate file is stored in the PHOT parameter set. + +.nf +\fL + ap> phot.coords=starlist +\fR +.fi + +.PP +The next step is to set up the PHOT parameters interactively. +First we load the image (contour plot) blue on the display (graphics +terminal). Next we call up PHOT in interactive mode. + +.nf +\fL + ap> phot blue + ... cursor appears ... + +\fR +.fi + +.PP +PHOT takes input by reading the image (graphics) +display (terminal) cursor. In order to display the available commands +we tap the ? key and the following text appears on the screen. + +.nf +\fL + Interactive Phot Commands + +? Print options +: Colon command see below +i Setup PHOT parameters interactively +w Write PHOT parameters to the parameter files +l Process the remainder of the coordinate list +r Rewind the coordinate list +c Fit center around the current cursor position +t Fit sky around the current cursor position +s Fit sky around the current center position +p Compute magnitudes around the cursor position +f Fit center, sky and compute magnitudes +sp Fit center, sky, compute magnitudes, and save +q Exit program + +Phot parameters are listed or set with the following commands. + +:m [n] Move cursor to the [nth] object in the coordinate list +:n [n] Measure the [nth] object in the coordinate list + +:show [center/sky/phot/all] List the aphot parameters +:fwhmpsf [value] Full width half maximum of the PSF +:noise [string] Noise model +:threshold [value] Threshold value for centering +:sigma [value] Standard deviation of the background +:ccdread CCD readout noise keyword +:readnoise Readout noise in electrons +:gain Gain keyword +:epadu Electrons per adu + +:calgorithm [string] Centering function +:positive [y/n] Emission or absorption feature +:cbox [value] Width of the centering box in fwhmpsf +:cmaxiter [value] Maximum number of centering iterations +:maxshift [value] Maximum shift in fwhmpf +:minsnratio [value] Minimum signal to noise ratio of pixels +:clean [y/n] Clean subraster before centering +:rclip [value] Clipping radius in fwhmpsf +:rclean [value] Cleaning radius in fwhmpsf +:kclean [value] Sigma for clean algorithm +:mkcenter [y/n] Mark the centers on the display + +:salgorithm [string] Sky fitting algorithm +:annulus [value] Inner radius of sky annulus in fwhmpsf +:dannulus [value] Width of sky annulus in fwhmpsf +:skyvalue [value] User supplied sky +:smaxiter [value] Maximum number of rejection cycles +:skreject [value] +/- Pixel rejection limits in sky sigma +:snreject [value] Maximum number of rejection interations +:khist [value] +/- Sky histogram size in sky sigma +:binsize [value] Resolution of sky histogram in sky sigma +:smooth [y/n] Lucy smooth the sky histogram +:rgrow [value] Region growing radius in fwhmpsf +:marksky [y/n] Mark the sky annuli on the display + +:weighting Weighting for wphot +:aperts [string] Aperture radii in fwhmpsf +:zmag [value] Zero point of magnitude scale +:exposure [string] Exposure time keyword +:itime [value] Integration time +\fR +.fi + +.PP +We select the interactive setup option, move the image +cursor to a high signal-to-noise, isolated star and tap the i key. +PHOT responds by plotting the radial profile of the star on the +screen and requesting the user to mark the fwhm of +the psf, the centering aperture, the inner and outer sky annuli, +the sky background and sigma and the set of circular apertures. +The parameters so set can be examined and/or reset with the : commands as shown +above. Sample measurements can be made of several stars by moving the +cursor and typing the f command. Finally when we are happy with the +parameter set we type w to store the parameters and q to exit the program. +.PP +Now we are ready to do photometry. We enter the PHOT program in batch mode. + +.nf +\fL + ap> phot blue inter- & +\fR +.fi + +The batch job is now running, appending output lines to the file "blue.mag.#". +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. + +.NH +The APPHOT Tasks +.PP +Manual pages for the APHOT tasks are attached. Although the working of the +various tasks may change in detail, the help pages attached here should +provide a good description of the function of each task. +.PP +When the package has stabilized a detailed users guide will be written. diff --git a/noao/digiphot/apphot/doc/specs/apphot.spc.lw b/noao/digiphot/apphot/doc/specs/apphot.spc.lw new file mode 100644 index 00000000..71285557 --- /dev/null +++ b/noao/digiphot/apphot/doc/specs/apphot.spc.lw @@ -0,0 +1,1296 @@ +.EQ +delim $$ +.EN + +.RP +.TL +Specifications for the Aperture Photometry Package +.AU +Lindsey Davis +.AI +.K2 "" "" "*" +Revised October 1987 + +.AB +The APPHOT package is a set of tasks for performing aperture photometry +on uncrowded or moderately crowded fields, in either interactive or batch mode. +The photometric technique employed is fractional pixel aperture +integration. Point spread function fitting techniques are not used and no +knowledge of the point spread function is required for the computation of +magnitudes. Separate tasks are provided for creating and modifying object lists, +computing accurate centers for a list of objects, computing sky values for +a list of objects and performing aperture photometry inside circular or +polygonal apertures. +.AE + +.NH +Introduction +.PP +The APPHOT package is a set of tasks for performing +aperture photometry on uncrowded or moderately crowded fields. +The photometric technique employed is fractional pixel integration. Point +spread function techniques are not used and no knowledge of the point spread +function is required for the computation of magnitudes. +.PP +The APPHOT package performs multi-aperture photometry on digitized starfields +maintained as IRAF image files. Input to the package consists of an +image file, a list of object coordinates, numerous parameters controlling +the analysis algorithms and, optionally, the graphics terminal and/or +display. APPHOT output consists of successive lines of text where each line +summarizes the results of the analysis for a particular object. +.PP +Given starting coordinates and an IRAF image, the principal APPHOT +task computes accurate centers, sky values and magnitudes +for a list of objects. Separate +IRAF callable tasks in APPHOT exist to create and modify object +lists, to determine image characteristics such as the full width half maximum +of the point spread function or standard deviation of the sky pixels, +to compute accurate centers for a list of objects, to compute accurate local sky +values for a list of objects, and to compute magnitudes inside a polygonal +aperture. + +.NH +APPHOT Package Requirements +.NH 2 +APPHOT Package Input +.NH 3 +The IRAF Image +.PP +APPHOT assumes that images exist on disk in IRAF format. Facilities for reading +and writing images exist elsewhere in IRAF such as in package DATAIO or +MTLOCAL. +.PP +APPHOT assumes that the image data is linear. +The input image is assumed to have been corrected for those instrumental +defects which affect the intensity of a pixel. These include pixel to +pixel variations in the bias values, pixel to pixel gain variations, +cosmic rays, cosmetic defects, geometric distortion, +and detector non-linearities. +.PP +APPHOT assumes that the local sky background is approximately flat in the +vicinity of the object being measured. This assumption is equivalent to +assuming that the local sky region has a unique mode. Therefore any +variations in the sky background which occur at the same scale as the +sky region should be removed prior to entering APPHOT. +.PP +The point spread function of the image is assumed to be constant for all +regions of the image. This is particularly critical in the case of faint objects +for which small apertures which minimize the effects of crowding and +sky noise in the aperture are used. The wings of the object will +almost certainly extend beyond the aperture and good results will only be +obtained if +objects are consistently well centered and the shape and diameter of an object +is constant throughout the image and invariant to magnitude. + +.NH 3 +The Coordinate Lists +.PP +All APPHOT tasks operate on lists of object coordinates or interactive cursor +input. Lists are maintained as text files, +one object per line with the x and y coordinates in +columns one and two respectively. List files may be created interactively +with either the graphics or image cursor, by a previously executed APPHOT +task, by a previously executed IRAF task or by a user task. +.PP +The x and y coordinates contained in the list file can be either the +starting centers for the objects of interest or the true centers. +In either case the aperture centered around the object position must +not extend beyond the boundary of the image. To obtain reliable results +from the centering algorithm the starting centers should not be more than +1 fwhmpsf pixels from the true centers. + +.NH 3 +Algorithm Parameters +.PP +Many tasks in the APPHOT package have an associated set of algorithm parameters +which control the operation of the analysis routines. For example the +centering and sky fitting algorithms each have an associated group of +parameters. +The APPHOT tasks supply reasonable defaults for these parameters. However +the user may alter them at any time in interactive mode or by editing the +appropriate parameter file before running the task in batch. + +.NH 3 +Terminal Graphics and the Image Display +.PP +Most APPHOT programs may be run in either interactive or batch mode. +In interactive mode, the user can mark the positions of objects by +interactively, positioning the image cursor on the display device. +Simple cursor commands can interactively alter the algorithm parameters. +In batch mode the algorithm parameters are +fixed and object coordinates are taken from the user supplied coordinate list. +The display device is not required in batch mode. +.PP +At present there is no high level IRAF display interface. Therefore the present +version of APPHOT replaces the display device with terminal +graphics. For example it is possible to load a contour plot of an image +or image section, and run the APPHOT tasks, interactively marking +positions on the plot. This is a temporary measure to tide thing over until +the display interface is available. Furthermore this option is only +really suitable for those terminal which have both text and graphics +windows displayed at the same time. +.PP +Certain APPHOT tasks such as FITSKY occasionally require an interactive graphics +capability. For example it is sometimes desirable to plot the histogram +of the sky pixels and mark the peak of the histogram interactively rather +than using the automatic sky fitting routines. +Graphics capablity has been added to APPHOT tasks as deemed useful. + +.NH 2 +APPHOT Package Functions +.NH 3 +Creating Coordinate Lists +.PP +APPHOT task(s) shall exist to create coordinate lists interactively within +APPHOT by loading the IRAF image into the image display +and successively marking the objects to be measured with the image cursor. +It shall be possible to mark the positions of objects on the display, and draw +circles of arbitrary size around the objects of interest. +It shall be possible to verify existing coordinate lists by marking the object +coordinates on the image display. +.PP +At present the full image display cababilities do not exist in IRAF. +Therefore as a temporary measure most tasks will run with a contour +plot and the graphics cursor as a substitute for the image display and +image cursor by setting the image cursor to stdgraph and the display +parameter for each task to stdgraph. +The output coordinates will be written to a text file and may be used as +starting coordinates for the APPHOT routines. +.PP +Those sites which have SUN workstations can use the IMTOOL facilites to +create cursor lists. +.PP +APPHOT tasks shall exist to automatically detect objects by specifying the IRAF +image to be searched, plus a few image characteristics such as a detection +threshold and the full width half maximum of the point spread function. +The output coordinates plus a few object statistics will be written to a +text file. + +.NH 3 +Coordinate List Operations +.PP +General list processing tasks are or will be available in the IRAF lists +package. Examples of useful currently existing tasks are list sorting by for +example magnitude and performing a linear transformations +on coordinate lists. +.PP +It may eventually be necessary to add some specialized list processing tasks +to APPHOT. One example is a list matching facility in which objects in +common to two lists are combined and output to a third list. + +.NH 3 +Determining the Image Characteristics +.PP +APPHOT tasks shall exist to estimate certain image +characteristics such as the full width half maximum of the image point spread +function and the standard deviation of the background. In order to obtain +meaningful error estimates it is also necessary to specify the noise +charactersitics of the detector and a noise model. +In this version of APPHOT two noise +functions will be supported a constant sky background noise, +and constant background noise plus Poisson statistics in the object. +.PP +The reason for this capability is that the majority of the APPHOT +algorithm parameters scale with these two image characteristics. +For example all the pixel scale dependent parameters such as the centering +aperture, object apertures, the two sky annuli and the +maximum shift parameter all scale with the full width half +maximum of the point spread function. Similarly most of the pixel intensity +dependent parameters scale with the standard deviation of the sky pixels. + +.NH 3 +Centering +.PP +An APPHOT task shall exist to determine accurate centers for a list of objects, +using the approximate object coordinates as a starting point. +The centering aperture may extend beyond the boundaries of the image but +a warning message will be generated. +.PP +A choice of centering algorithms with a range of efficiency and accuracy will +be available. The center determination must be resistant to the affects of +nearby contaminating objects. +.PP +The user may opt to use the starting center as the actual center in all cases, +to use the starting center as the actual center if the object is very faint, +or tweak up the center if the signal to noise is above a certain threshold. +.PP +The output of the centering algorithm will the set of computed coordinates +and their errors. + +.NH 3 +Fitting the Sky +.PP +An APPHOT task shall exist to compute 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 background shall +be excluded from the fit. +.PP +The user may supply a constant background, with zero-valued noise and skew +value or read appropriate values from a file instead of computing the +background. +.PP +The output of the sky fitting algorithm shall be +the mode, standard deviation and skew of the sky as well as the number +of pixels left in the background region after pixel rejection and the number +rejected. + +.NH 3 +Multi-aperture Photometry +.PP +APPHOT routines shall exist to compute 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. Both normal and weighted photometry routines shall +be available. +.PP +It shall be possible to normalize the output magnitudes to a user specified +integration time using values stored in the IRAF image header. +.PP +The output shall consist of magnitudes and errors for each of the specified +apertures. +.NH 3 +Polygonal Aperture Photometry +.PP +Determine the integral of the object within a specified +polygon. Aperture integration shall be by fractional pixel summation +of successive image lines. + +.NH +Specifications +.NH 2 +Apphot CL Callable Tasks +.PP +The CL callable part of the APPHOT package consists of the following +routines:\f(CW + +.nf +.na + mark -- create/verify coordinate lists interactively + polymark -- create/verify polygon lists interactively + daofind -- automatic image finder from DAOPHOT + lintran -- linearly transform a list of coordinates (LISTS package) + + radprof -- compute the radial profile of an object. + fitpsf -- model the PSF + + center -- compute accurate centers for a list of objects + fitsky -- compute accurate sky values for a list of objects + phot -- perform multi-aperture photometry on a set of objects + polyphot -- compute the flux inside a set of irregular polygons + wphot -- perform weighted multi-aperture photometry\fR +.ad +.fi + +.NH 2 +Standard Analysis Procedures +.PP +A standard reduction procedure would be something as follows. +.IP 1. +Estimate the image and data characteristics in the following manner. +.RS +.IP 1. +Use the interactive setup option (i key) in the PHOT task to specify the +fwhm of the psf, +the centering apperture, the sky annuli, the photometry apertures as +well as estimate the sky sigma. +Examine the results (:show command) and optionally store the +new parameters in the parameter files (w key). +.IP 2. +Use the EPAR task to edit the parameter files directly. For example the +detector gain and readout noise must be known before running PHOT in +order to get reliable error estimates. +.RE +.IP 2. +Prepare a coodinate list in one of the following ways. +.RS +.IP 1. +Running MARK or POLYMARK. +.IP 2. +Run DAOFIND or some other automatic image finder. +.IP 3. +Run another APPHOT task such as CENTER . +.IP 4. +Run any other IRAF or user program which generates the appropriate +format. +.IP 5. +Transform an existing list using the LISTS package facilities +.RE +.IP 3. +Run PHOT or WHOT in non-interactive mode to perform the multi-aperture +photometry. The user should be familiar +with the algorithms used to measure the object center, to fit the background, +and compute the aperture integral, magnitude, and errors. The values of +all visible and hidden PHOT parameters should be inspected before doing +any serious processing. Note that CENTER and FITSKY can be run independently +of PHOT and their output used as input to PHOT. +.EQ +delim $$ +.EN + +.NH 2 +The APPHOT Algorithms +.PP +The principal APPHOT algorithms are described below. + +.NH 3 +The RADPROF Algorithm +.PP +The function of the RADPROF task is to compute the radial profile of +selected, isolated, high signal to noise objects in an IRAF image. +.PP +Given the IRAF image, an initial center, an aperture and a step size, +RADPROF computes the radial profile of an object in the following manner. +.IP 1. +The APPHOT centering routines are used to compute an accurate center for the +object. The new center is used to compute the radial coordinate for each +pixel in the subraster. +.IP 2. +The APPHOT sky fitting routines are used to compute an accurate sky value +for the object. The new sky value is used to compute the object intensity +for each pixel in the subraster. +.IP 3. +The CURFIT package routines are used to produce a smooth intensity versus +radius curve by fitting a cubic least squares spline function to the data +using linear least squares techniques. +.IP 4. +The fitted curve is evaluated at equally spaced intervals to produce the +final radial profile. The profile is normalised using the r = 0 value. +.IP 5. +The smoothed curve is integrated using the +1D integration routines IMINTERP to evalute the fraction of the total +integral at each interval. +.IP 6. +The three quantities $I sub r$ the raw intensity, $Inorm sub r$ the +normalized intensity, and $Ifraction sub r$ the fraction of the total +intensity inside radius at r, are plotted on the terminal and +output as a function of r to a text file. +.PP +RADPROF is used principally to compute the stellar image and setup the +parameters for doing photometry. Its default output is a radial profile +plot with the phot parameters marked on it. + +.NH 3 +The FITPSF Algorithm +.PP +The function of the FITPSF task is to fit an analytic model to an object +in order to derive information about the point spread function. Given +an IRAF image, an initial center and an aperture, FITPSF computes the +model parameters in the following manner. +.IP 1. +The fitting function is chosen. +The present version of FITPSF offers two function choices a 2D radial Gaussian +function and an elliptical Gaussian function. +A third option, moment analysis, has been added to the FITPSF package. +The image characteristics are evaluted by using the 0th, 1st and 2nd order +moments of the image. +.IP 2 +Initial guesses for the parameters are made from the subraster data. +.IP 3 +The parameters and their errors are derived using standard non-linear least +squares techniques and the NLFIT package. + +.NH 3 +The DAOFIND Algorithm +.PP +The function of the DAOFIND task is to automatically detect objects +in an IRAF image above a certain intensity threshold. +The user specifies an intensiyt threshold, +the estimated full width half maximum of +the point spread function, +and limits on the sharpness and roundness of the objects to be detected. +DAOFIND produces a list of x and y coordinates and a sharpness +and roundness statistic for each detected object. +.PP +The DAOFIND algorithm works in the following way. +.IP 1. +The user specifies an intensity threshold above local sky and estimates +the full width half maximum of the point spread function. +.IP 2. +DAOFIND computes a convolution kernel which is a linear +function of the brightness values in an approximately circular array of +pixels. The original data is convolved with the computed kernel. +The equivalent mathematical +operation is a convolution of the original data +with truncated, lowered circular Gaussian function with the specified FWHM, +computed in such a way as to be the mathematical +equivalent of fitting a Gaussian stellar profile to the object data by least +squares. The coefficients of the linear function sum to zero so that the +overall bias level (local sky) cancels out exactly. Since the function is +symmetric about a single pixel, a smooth gradient in the sky brightness +also cancels exactly. Therefore the user does not have to specify an +absolute brightness threshold but only a threshold above local sky. +.IP 3 +The convolved data is searched for local maxima. Local maxima which are +less than the specified threshold are rejected. A pixel is defined to be +a local maximum when it is the brightest pixel within +$n ~*~ sigma sub Gauss$. +.IP 4. +Using the original data, DAOFIND computes an object sharpness statistic which +can be used to reject +hot or cold pixels. The sharp parameter is defined below. +Detected objects with a sharpness parameter outside the range specifed +by sharplo and sharphi are rejected. Typical values for sharplo and +sharphi are 0.2 and 1.0 respectively. +.nf + + $I sub delta$ = height of best fitting $delta$ function = pixel value + + $I sub Gauss$ = height of best fitting Gaussian function = convolved value + + sharplo <= sharp = ${I sub delta} over {I sub Gauss}$ <= sharphi + +.fi +If the brightness enhancement detected in the convolved data is due to +a single bright pixel, then the best fitting delta function will have an +amplitude equal to the height of this pixel above the local background, +while the amplitude of the best fitting Gaussian will be pulled down by +the surrounding low valued pixels. Sharp will be a number significantly +greater than one. A single cold pixel will produce +brightness enhancements approximately 0.5 * FWHM away +from the pixel in question in all directions. In this case the height +of the delta +function which best fits these spurious maxima is close to zero, while the +height of the best fitting Gaussian is some small positive number. +In this case sharp will be close to zero. +.IP 5. +The roundess statistic is computed from the original picture data by fitting +1D Gaussians +to the marginal sums in x and y. If the height of either 1D +Gaussian is negative the object is rejected. If both heights are +positive the roundness parameter is computed. +.nf + + $DELTA I ~=~ I sub {x ~ Gauss} ~-~ I sub {y ~ Gauss}$ + + $<I> ~=~ I sub {x ~ Gauss} ~+~ I sub {y ~ Gauss}$ + + $roundlo ~<=~ round ~=~ {DELTA I} over <I> ~<=~ roundhi$ + +.fi +Objects which are elongated in the +x direction have roundness values less than zero and those elongated in +the y direction have roundness greater than zero. +Round discriminates only against objects which are elongated +along either rows or columns. Objects elongated at a 45 degree angle will +not be rejected. +.IP 6. +Finally the approximate x and y centroids of the detected objects, +rough magnitudes relative to threshold are computed, and object is added +to the output file. + + +.NH 3 +The CENTER Task + +.NH 4 +Centering Package Routines +.PP +The following are the principal programmer callable routines routines in the +centering package. +.nf +\f(CW + + apcinit (ap, cfunction, cbox, fwhmpsf, noise) + ier = apfitcenter (ap, im, xinit, yinit) + ier = aprefitcenter (ap) + value = apstat[ir] (ap, param) + apstats (ap, param, str, maxch) + apset[sir] (ap, param, value) + apcfree (ap) + +\fR +.fi +.PP +The following quantities can be examined or set by apstat/apset calls +.nf +\f(CW + data 1. fwhmpsf full width half maximum of psf in pixels +parameters 2. threshold minimum intensity for centering + 3. noise noise model + 4. sigma standard deviation of background + 5. readnoise readout noise of CCD in electrons + 6. epadu electrons per adu + +centering 1. calgorithm centering algorithm +parameters 2. positive emission / absorption features + 3. cbox centering radius in fwhmpsf + 4. cmaxiter maximum number of fitting iterations + 5. maxshift maximum permitted shift in fwhmpsf + 6. minsnratio minimum permitted signal to noise ratio + 7. clean clean subraster before centering + 8. rclean cleaning radius in fwhmpsf + 9. rclip clipping radius in fwhmpsf + 10.kclean k-sigma rejection for cleaning in sigma +\fR +.fi + +.PP +The following computed quantities can be examined by apstat calls. +.nf +\f(CW + 1. xcenter computed x coordinate + 2. ycenter computed y coordinate + 3. xerr computed x coordinate error + 4. yerr computed y coordinate error +\fR +.fi +.PP +See the manual pages for CENTER and CENTERPARS for a detailed description +of the centering parameters. + +.NH 4 +The Centering Algorithm +.PP +The function of the CENTER task is to compute accurate centers and errors +for objects in an IRAF image given a list of initial positions and a +centering aperture. +.IP 1. +If the centering algorithm is disabled, the computed center is set to the +initial center and the uncertainty estimate is set to zero. +.IP 2. +If the cleaning algorithm is enabled, clean the subraster before centering. +.IP 3. +Estimate is made of the signal to noise of the object. If this quantity is +less than a certain minimum value the computed center is kept +but a warning message is issued. +.IP 4. +The center and errors are computed using one of several algorithms. +.IP 5. +If the computed center is greater than a user specified distance from the +initial center then the computed center is returned with an error +message. + +.NH 4 +Symmetry Clean Algorithm +.PP +The symmetry-clean algorithm attempts to remove defects in the centering +subraster by assuming that the object has radial symmetry and comparing +pixels on the opposite sides of the center of symmetry. The algorithm +works in the following way. +.IP 1. +The center of symmetry is computed. Normally the center of symmetry is assumed +to coincide with the position of the brightest pixel in the subarray. +However if the maximum pixel is more than a user specified distance away +from the intial center, the initial center is used as the center of symmetry. +.IP 2. +Pixels inside a specified cleaning radius are unaltered. +.IP 3. +Pairs of pixels diametrically opposed about the center +in the cleaning region between the cleaning and clipping +radii are tested for equality. If the difference between the pixels is +greater than a specified k-sigma rejection limit, the larger value is replaced +by the smaller. +In this region sigma is computed from Poisson statistics. +.IP 4. +Pairs of pixels in the clippping +region are compared in the same manner as those in the cleaning region +except that sigma is the standard deviation of the sky pixels. +.PP +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 distributions. + +.NH 4 +Signal to Noise Estimate + +.PP +The signal to noise of the object is estimated from the data values +in the subraster in the following way. +.nf + + $SNR ~=~ N sub object over {sqrt {n sub pix ~*~sigma sub sky sup 2}}$ + + or + + $SNR ~=~ N sub object over {sqrt {N sub object ~+~ n sub pix~*~sigma sub sky sup 2}}$ + +.fi +where $N sub *$ is the number of counts in the object above threshold, +$sigma sub sky$ +is the standard deviation of the pixels in the sky region and +$n sub pix$ is the number of pixels in the object aperture. +The first approximation corresponds to constant sky noise only, +the second includes Poisson noise in the object. + +.NH 4 +Centroid +.PP +The centroid centering algorithm is similar to that used in MPC and can +be briefly described as follows. For more detailed description +see (Stellar Magnitudes From Digital Pictures, 1980, Adams et al). +.IP 1. +The marginal distributions in x and y are accumulated. +.IP 2. +The intensity weighted centroid positions for the marginals is computed +using only data pixels which are above the threshold intensity. If the +threshold parameter is 0 the mean intensity of the marginal is used +in place of the threshold +.nf + + $I sub i ~=~ I sub i ~-~ threshold ~~~~~ I sub i ~>~ 0.0$ + + $x sub c ~=~ {sum I sub i ~ x sub i} over {sum I sub i}$ + +.fi +.IP 3. +The errors are estimated in the following way +.nf + + $sigma sup 2 ~=~ {sum I sub i ~ x sub i sup 2} over {sum I sub i} ~-~ x sub c sup 2$ + + $err sub xc ~=~ sqrt {{sigma sup 2} ~/~ sum I sub i}$ + +.fi + +.NH 4 +Gaussian Fit to the Marginals +.PP +The fit is performed in the following way. +.IP 1. +The marginal distributions in x and y are accumulated. +.IP 2. +Initial guesses for the parameters of the 1D Gaussians $I sub Gauss$, +$x sub c$ and $I sub sky$ are derived from the marginal distributions +themselves. The width $sigma$ is held constant. +.IP 3. +The best fit parameters and their errors are derived using non-linear +least-squares techniques and the NLFIT package. + +.NH 4 +Optimal Filtering of Marginals +.PP +The fit is performed is the following way. +.IP 1. +The marginal distributions in x and y are accumulated. +.IP 2. +The centroid of the observed distribution is computed by solving the +following equation. +.nf + + $PSI (x sub c ) ~=~ sum omega sub i (x sub c ) ~ PHI sub i ~=~ 0$ + + $omega sub i ~=~ {{partial phi sub i} ~/~ {partial x sub c}} over {phi sub i~+~b}$ + +.fi +The assumptions are that the observed distribution $PHI sub i$ is correctly +modeled by the profile function $phi sub i$. The usual choise of profile +model for centering is a Gaussian. Howver in the interests of speed a triangle +function has been substituted. This causes at most a 7% increase in the +random centering error. +.IP 3. +The startup procedure is based on the following fact. +.nf + + $PSI (x sub n )~>~0~~for~~ x sub n ~<~ x sub c$ + + $PSI (x sub n ) ~<~0~~for~~ x sub n ~>~ x sub c$ + +.fi +The iteration is initialized by assuming that $x sub 1$ = $x sub c$ and +computing $PSI (x sub 1 )$. The initial x +value is incremented by $+- sigma sub Gauss$ depending on the sign of $PSI$. The +search is repeated until $PSI (x sub {n-1})$ and $PSI (x sub n)$ have +opposite signs. At this point the true center is bracketed by the +estimated positions $(x sub n, ~ x sub {n-1})$ and we have a table of at +least 2 values of $PSI (x sub n )$. +.IP 4. +The computation proceeds by interpolating in the table of values for the +estimated position $x sub {n+1}$ where $PSI$ = 0. If the table contains only +two values as may be the case for the inititial interpolation, linear +interpolation is used. In all other cases a quadratic fit to the three +most recent $PSI$ values is used. The computation is complete when +two successive estimates differ by less than some tolerance typically +0.001 pixel. +.IP 5. +The errors are estimated as follows. +.nf + + $sigma sup 2 ~=~ ( {int {( partial phi ~/~ partial x sub c )} sup 2 over { + phi + b}} ) sup -1$ + + $err sub xc ~=~ sqrt {sigma sup 2}$ + +.fi + +.NH 4 +Other Centering Methods +.PP +The code is constructed in such a way that new algorithms may be +easily added at a future date, such as the more sophisticated techniques +required for accurate astrometry. +.EQ +delim $$ +.EN +.NH 3 +The FITSKY Task + +.NH 4 +Sky Fitting Routines + +.PP +The following are the main entry points in the sky fitting package. +.nf +\f(CW + apsinit (ap, function, annulus, dannulus, fwhmpsf, noise) + ier = apfitsky (ap, im, xpos, ypos, sd, gd) + ier = aprefitsky (ap, sd, gd) + value = apstat[ir] (ap, param) + apstats (ap, param, str, maxch) + apset[irs] (ap, param, value) + apsfree (ap) +\fR +.fi +.PP +The following quantities can be examined or set with apset/apstat calls. +.nf +\f(CW +data 1. fwhmpsf full width half maximum of the psf +parameters 2. sigma standard deviation of sky pixels + +sky fitting 1. annulus inner radius of sky annulus in fwhmpsf +parameters 2. dannulus outer radius of sky annulus in fwhmpsf + 3. sfunction sky fitting algorithm + 4. smaxiter maximum number of fitting iterations + 5. kreject k-sigma rejection limit sigma + 6. nreject maximum number of rejection cycles + 7. rgrow region growing radius in fwhmpsf + + 8. khist half-wdth of histogram in sigma + 9. binsize binsize of histogram in sigma + 10.smooth Lucy smooth the histogram + + 11.skyfile name of text file containing sky values + 12.skyvaluser supplied constant value for sky +\fR +.fi +.PP +The following computed quantities can only be examined with apstat calls. +.nf +\f(CW + 1. skymode computed sky value + 2. skysig computed sky sigma + 3. skyskew computed sky skew + 4. nsky number of sky pixels + 5. nsky_reject number of rejected sky pixels +\fR +.fi + +.NH 4 +The Sky Fitting Algorithms +.PP +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. +.PP +The main algorithm used in APPHOT is the following. +.IP 1. +If the skyfitting switch is disabled either read the sky values from a text +file or accept a user supplied constant for the sky. +.IP 2. +Perform the initial sky fit using one of the specified algorithms. The +sky fitting algorithms fall into three general categories, those that use +the actual sky pixel array itself, those that operate on a histogram of +sky values and those that rely on user interaction. +.IP 3. +If the pixel rejection flags are set perform pixels rejection with optional +region growing. + +.NH 4 +Sky Pixel Array Techniques + +.NH 5 +Median +.IP 1. +Sort the array of sky pixels. This is necessary to avoid quantization effects. +.IP 2. +Compute the median, and the standard deviation and skew with respect to the +mean. +.IP 3. +If the k-sigma rejection limit is greater than zero and the maximum number +of rejection cycles is greater than one, perform pixel rejection. +Pixels greater than k-sigma from the median are rejected. Region growing +is optional. +.IP 4. +Stop the rejection cycle on any given iteration if the maximum number of +rejection cycles ix exceeded, no more sky pixels are left or no more +pixels are rejected. + +.NH 5 +Mode +.IP 1. +Sort the array of sky pixels. This is necessary to avoid quantization effects. +.IP 2. +Compute the mode, and the standard deviation and skew +with respect to the mean. +.nf + + $I sub mode ~=~ 3.0 ~*~ I sub median ~-~ 2.0 ~*~ I sub mean$ + +.fi +.IP 3. +If the k-sigma rejection limit is greater than zero and the maximum number +of rejection cycles is greater than one, perform pixel rejection. +Pixels greater than k-sigma from the mode are rejected. Region growing +is optional. +.IP 4. +Stop the rejection cycle on any given iteration if the maximum number of +rejection cycles ix exceeded, no more sky pixels are left or no more +pixels are rejected. + + +.NH 4 +Histogram Techniques +.PP +The following three techniques all operate on the histogram of the sky pixels. +The routines all construct the histogram in the following identical manner. +.IP 1. +The mean of the sky distribution is computed. +.IP 2. +If the user specified standard deviation of the sky pixels is INDEF the +algorithm computes the standard deviation of the sky pixels with respect +to the mean. +.IP 3. +All pixels within plus or minus sigma standard +deviations are accumulated into a histogram. The user specifies the bin size. +.IP 4. +The histogram may optionally be Lucy smoothed before any operation is performed +on it. + +.NH 5 +Centroid +.PP +The mode, sigma and skew of the sky pixels are computed in the following +manner. +.IP 1. +The histogram is compiled as above. +.IP 2. +The mode, standard deviation and skew of the sky pixels are computed in the +following manner. + +.nf + $I sub 0 ~=~ sum I sub i$ + $I sub 1 ~=~ sum I sub i ~ x sub i$ + $I sub 2 ~=~ sum I sub i ~ x sub i sup 2$ + $I sub 3 ~=~ sum I sub i ~ x sub i sup 3$ + + $I sub mode ~=~ {I sub 1} ~/~ {I sub 0}$ + $sigma ~=~ {( I sub 2 ~/~ I sub 0 ~-~ I sub mode sup 2 )} sup {1/2}$ + $skew ~=~ ( {I sub 3 ~/~ I sub 0 ~-~ I sub mode ~*~ sigma sup 2 ~-~ I sub mode sup 3} ) sup {1/3}$ + +.fi +.IP 3 +If pixel rejection is enabled sky pixels within a user supplied limit of +the mode are rejected with optional region growing. + +.NH 5 +Gaussian Fit +.PP +The mode, standard deviation and skew of the sky pixels are derived from a +model fit in the following way. +.IP 1. +The histogram of the sky pixels is compiled as above. +.IP 2. +Initial guesses to the model parameters, $N sub max$, $I sub mode$, +$sigma$, and $skew$ are made from the histogram itself. +.IP 3. +Final parameters and their errors are derived using non-linear least squares +techniques and the NLFIT package. +.IP 4. +If pixel rejection is enabled sky pixels within a user supplied limit of +the computed mode are rejected with optional region growing. + +.NH 5 +Optimal Filtering +.PP +The method is as follows. +.IP 1. +The histogram is compiled as above. +.IP 2. +Using the mean of the sky pixels as the intital value of the sky mode, +a new mode is computed using the optimal filtering technique +described for centering. +.IP 4 +If pixel rejection is enabled sky pixels within a user supplied limit of +the computed mode are rejected with optional region growing. + +.NH 5 +Cross Correlation +.PP +The method is as follows. +.IP 1. +The histogram is compiled as above. +.IP 2. +The noise function is estimated using the standard deviation of the sky +pixels and the cross-correlation function is computed. +.IP 3. +The mode is computed using quadratic interpolation around the peak of the +distribution. +.IP 4 +If pixel rejection is enabled sky pixels within a user supplied limit of +the mode are rejected with optional region growing. + +.NH 4 +Interactive Techniques + +.NH 5 +Histogram Plot +.PP +The histogram is compiled as described above and the user marks the peak +on the histogram plot with the graphics cursor. The sigma and skew of the +sky distribution with respect to the mean is also computed. + +.NH 5 +Radial Distribution +.PP +A radial profile plot of the sky region is plotted and the user marks the +sky value on the plot with the graphics cursor. The sigma and skew of the sky +distribution with respect to the mean is computed. + +.NH 4 +Pixel Rejection and Region Growing +.PP +All the sky fitting algorithms permit pixel rejection and +optional region growing. +Pixel rejection and region growing are +performed by locating all pixels more than k * 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. +.PP +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. + +.NH 4 +The Principal PHOT Routines +.PP +The main entries in the photometry routine are the following. +.nf +\f(CW + apinit (ap, cfunction, cbox, sfunction, annulus, dannulus, + aperts, napert, fwhmpsf, noise) + ier = apfitcenter (ap, im, xinit, yinit) + ier = aprefitcenter (ap) + ier = apfitsky (ap, im, xcenter, ycenter, sd, gd) + ier = aprefitsky (ap, sd, gd) + ier = apmag (ap, im, xcenter, ycenter, skyval, skysig, nsky) + ier = apwmag (ap, im, xcenter, ycenter, positive, skyval, skysig, + nsky) + ier = apremag (ap, positive, skyval, skysig, nsky) + ier = apwremag (ap, positive, skyval, skysig, nsky) + value = apstat[ir] (ap, param) + apstats (ap, param, str, maxch) + apset[sir] (ap, param, value) + apfree (ap) + +\fR +.fi +.PP +The following parameters can be examined or altered by apset/apstat calls. +.nf +\f(CW + 1. weighting weighting scheme for wphot + 2. aperts list of apertues + 3. naperts number of apertures + 4. zmag zero point of magnitude scale + 5. itime effective integration time +\fR +.fi +.PP +The following quantities can be examined with apstat calls. +.nf +\f(CW + + 1. sums array of aperture sums + 2. areas array of areas + 3. mags array of magnitudes + 4. magerrs array of magnitude errors + +\fR +.fi + +.NH 4 +The PHOT Aperture Integration Algorithm +.PP +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. +.PP +The inclusion of a partial pixel inside the aperture is done as follows. +.IP 1. +If the distance of the current pixel from the center of the star, r, is +exactly equal to the radius of the aperture R then one-half the counts in +the pixel are included. +.IP 2. +If r < R - 0.5 the entire pixel is included while if r > R + 0.5 the pixel +is wholly excluded. +.IP 3. +In between the fraction of the counts varies linearly. A circular aperture +is approximated by an irregular polygon. +.PP +The simplicity of aperture photometry limits the amount of information +available for error analysis. The following three sources of error are +considered. +.IP 1. +The error due to sky noise in the aperture. +.nf + + $error sub 1 ~=~ sigma sub sky ~*~ {A sub apert} sup {1/2}$ + +.fi +.IP 2. +The error in the aperture sum. +.nf + + $error sub 2 ~=~ ( {A sub "sum" ~/~ phpadu} ) sup {1/2}$ + +.fi +.IP 3. +The mean error of the sky. +.nf + + $error sub 3 ~=~ sigma sub sky ~*~ A sub apert ~/~ nsky sup {1/2}$ + + +.fi +where $sigma sub sky$ is either computed by the background fitting +algorithm or set by the user, +and $A sub apert$ is the fractional pixel area of the +aperture. + +.NH 4 +The WPHOT Algorithm +.PP +The WPHOT algorithm computes a weighted aperture sum in an attempt to +minimize noise in the sky. The algorithm is the following where w is +the weight for each pixel, p is the noise free profile value and +$sigma$ is the noise per pixel from all sources. (See the paper +by Stover and Allen 1987 for details) +.nf + + $A sub sum ~=~ sum {w sub i ~*~ (I sub i ~-~ sky)}$ + + $w sub i ~=~ C ~*~ p sub i ~/~ sigma sup 2 sub i$ + + $C ~=~ sum {p sub j} / sum {p sub j ~*~ w sub j}$ +.fi + +.NH 4 +The POLYPHOT ROUTINES +.PP +The principal polyphot routines are the following. + +.nf +.na +\f(CW + apyinit (ap, sfunction, annulus, dannulus, noise) + ier = apfitcenter (ap, im, wx, wy) + ier = aprefitcenter (ap) + ier = apfitsky (ap, im, xcenter, ycenter, sd, gd) + ier = aprefitsky (ap, sd, gd) + ier = polyfit (ap, im, xver, yver, nver) + value = apstat[ir] (ap, param) + apstats (ap, param, str, maxch) + apset[sir] (ap, param, value) + apfree (ap) + +\fR +.ad +.fi + +.PP +.NH 4 +The POLYPHOT Algorithm +.PP +The function of the POLYPHOT task is to compute the flux inside an +irregular polygon given a list of the coordinates of the vertices of a polygon. +The polygon must be entirely inside the image and the vertices of the polygon +must be specified in clockwise or counterclockwise order. +The actual algorithm used is as follows. +.IP 1. +The range of image lines which intersect the polygon are computed. +.IP 2. +For each image line in the specified range the intersection points with the +polygon are computed. +.IP 3. +The flux between pairs of limits is summed using a fractional pixel +approximation for the endpoints. +.IP 4. +The sky is fitted using any of the methods previously discussed and a +user specified annular region. +.IP 5. +The errors are computed as specified in the PHOT specifications. +.PP +.EQ +delim $$ +.EN + +.NH +Example +.PP +A brief example may help illustrate the use of the package. Suppose +we want to process a few hundred stars on image "blue". +.PP +The first step is to prepare a list of objects to be measured. The simplest +way to do this is to interactively mark the objects with the image +cursor using the display (graphics) device and the RIMCURSOR (RGCURSOR) +task. +.nf +\f(CW + + ... load image on the display ... + + ap> rimcursor > starlist + + ... move cursor and mark stars ... + + + ... load contour plot on graphics terminal ... + + ap> rgcursor > starlist + + ... move cursor and mark stars ... +\fR +.fi + +Alternatively one can run DAOFIND to compute a list of candidate objects +in the frame. +The name of the coordinate file is stored in the PHOT parameter set. + +.nf +\f(CW + ap> phot.coords=starlist +\fR +.fi + +.PP +The next step is to set up the PHOT parameters interactively. +First we load the image (contour plot) blue on the display (graphics +terminal). Next we call up PHOT in interactive mode. + +.nf +\f(CW + ap> phot blue + ... cursor appears ... + +\fR +.fi + +.PP +PHOT takes input by reading the image (graphics) +display (terminal) cursor. In order to display the available commands +we tap the ? key and the following text appears on the screen. + +.nf +\f(CW + Interactive Phot Commands + +? Print options +: Colon command see below +i Setup PHOT parameters interactively +w Write PHOT parameters to the parameter files +l Process the remainder of the coordinate list +r Rewind the coordinate list +c Fit center around the current cursor position +t Fit sky around the current cursor position +s Fit sky around the current center position +p Compute magnitudes around the cursor position +f Fit center, sky and compute magnitudes +sp Fit center, sky, compute magnitudes, and save +q Exit program + +Phot parameters are listed or set with the following commands. + +:m [n] Move cursor to the [nth] object in the coordinate list +:n [n] Measure the [nth] object in the coordinate list + +:show [center/sky/phot/all] List the aphot parameters +:fwhmpsf [value] Full width half maximum of the PSF +:noise [string] Noise model +:threshold [value] Threshold value for centering +:sigma [value] Standard deviation of the background +:ccdread CCD readout noise keyword +:readnoise Readout noise in electrons +:gain Gain keyword +:epadu Electrons per adu + +:calgorithm [string] Centering function +:positive [y/n] Emission or absorption feature +:cbox [value] Width of the centering box in fwhmpsf +:cmaxiter [value] Maximum number of centering iterations +:maxshift [value] Maximum shift in fwhmpf +:minsnratio [value] Minimum signal to noise ratio of pixels +:clean [y/n] Clean subraster before centering +:rclip [value] Clipping radius in fwhmpsf +:rclean [value] Cleaning radius in fwhmpsf +:kclean [value] Sigma for clean algorithm +:mkcenter [y/n] Mark the centers on the display + +:salgorithm [string] Sky fitting algorithm +:annulus [value] Inner radius of sky annulus in fwhmpsf +:dannulus [value] Width of sky annulus in fwhmpsf +:skyvalue [value] User supplied sky +:smaxiter [value] Maximum number of rejection cycles +:skreject [value] +/- Pixel rejection limits in sky sigma +:snreject [value] Maximum number of rejection interations +:khist [value] +/- Sky histogram size in sky sigma +:binsize [value] Resolution of sky histogram in sky sigma +:smooth [y/n] Lucy smooth the sky histogram +:rgrow [value] Region growing radius in fwhmpsf +:marksky [y/n] Mark the sky annuli on the display + +:weighting Weighting for wphot +:aperts [string] Aperture radii in fwhmpsf +:zmag [value] Zero point of magnitude scale +:exposure [string] Exposure time keyword +:itime [value] Integration time +\fR +.fi + +.PP +We select the interactive setup option, move the image +cursor to a high signal-to-noise, isolated star and tap the i key. +PHOT responds by plotting the radial profile of the star on the +screen and requesting the user to mark the fwhm of +the psf, the centering aperture, the inner and outer sky annuli, +the sky background and sigma and the set of circular apertures. +The parameters so set can be examined and/or reset with the : commands as shown +above. Sample measurements can be made of several stars by moving the +cursor and typing the f command. Finally when we are happy with the +parameter set we type w to store the parameters and q to exit the program. +.PP +Now we are ready to do photometry. We enter the PHOT program in batch mode. + +.nf +\f(CW + ap> phot blue inter- & +\fR +.fi + +The batch job is now running, appending output lines to the file "blue.mag.#". +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. + +.NH +The APPHOT Tasks +.PP +Manual pages for the APPHOT tasks are available in the IRAF on line help +database. diff --git a/noao/digiphot/apphot/doc/specs/apphot.spc.toc b/noao/digiphot/apphot/doc/specs/apphot.spc.toc new file mode 100644 index 00000000..757f9a79 --- /dev/null +++ b/noao/digiphot/apphot/doc/specs/apphot.spc.toc @@ -0,0 +1,111 @@ +.LP +.sp +1.\h'|0.4i'\fBIntroduction\fP\l'|5.6i.'\0\01 +.sp +2.\h'|0.4i'\fBAPPHOT Package Requirements\fP\l'|5.6i.'\0\01 +.br +\h'|0.4i'2.1.\h'|0.9i'APPHOT Package Input\l'|5.6i.'\0\01 +.br +\h'|0.9i'2.1.1.\h'|1.5i'The IRAF Image\l'|5.6i.'\0\01 +.br +\h'|0.9i'2.1.2.\h'|1.5i'The Coordinate Lists\l'|5.6i.'\0\02 +.br +\h'|0.9i'2.1.3.\h'|1.5i'Algorithm Parameters\l'|5.6i.'\0\02 +.br +\h'|0.9i'2.1.4.\h'|1.5i'Terminal Graphics and the Image Display\l'|5.6i.'\0\02 +.br +\h'|0.4i'2.2.\h'|0.9i'APPHOT Package Functions\l'|5.6i.'\0\03 +.br +\h'|0.9i'2.2.1.\h'|1.5i'Creating Coordinate Lists\l'|5.6i.'\0\03 +.br +\h'|0.9i'2.2.2.\h'|1.5i'Coordinate List Operations\l'|5.6i.'\0\03 +.br +\h'|0.9i'2.2.3.\h'|1.5i'Determining the Image Characteristics\l'|5.6i.'\0\03 +.br +\h'|0.9i'2.2.4.\h'|1.5i'Centering\l'|5.6i.'\0\03 +.br +\h'|0.9i'2.2.5.\h'|1.5i'Fitting the Sky\l'|5.6i.'\0\04 +.br +\h'|0.9i'2.2.6.\h'|1.5i'Multi-aperture Photometry\l'|5.6i.'\0\04 +.br +\h'|0.9i'2.2.7.\h'|1.5i'Polygonal Aperture Photometry\l'|5.6i.'\0\04 +.sp +3.\h'|0.4i'\fBAPPHOT Package Specifications\fP\l'|5.6i.'\0\04 +.br +\h'|0.4i'3.1.\h'|0.9i'Apphot CL Callable Tasks\l'|5.6i.'\0\04 +.br +\h'|0.4i'3.2.\h'|0.9i'Standard Analysis Procedures\l'|5.6i.'\0\05 +.br +\h'|0.4i'3.3.\h'|0.9i'The APPHOT Algorithms\l'|5.6i.'\0\05 +.br +\h'|0.9i'3.3.1.\h'|1.5i'The RADPROF Algorithm\l'|5.6i.'\0\05 +.br +\h'|0.9i'3.3.2.\h'|1.5i'The FITPSF Algorithm\l'|5.6i.'\0\06 +.br +\h'|0.9i'3.3.3.\h'|1.5i'The DAOFIND Algorithm\l'|5.6i.'\0\06 +.br +\h'|0.9i'3.3.4.\h'|1.5i'The CENTER Algorithm\l'|5.6i.'\0\08 +.br +\h'|1.5i'3.3.4.1.\h'|2.2i'Centering Package Routines\l'|5.6i.'\0\08 +.br +\h'|1.5i'3.3.4.2.\h'|2.2i'The General Centering Procedure\l'|5.6i.'\0\09 +.br +\h'|1.5i'3.3.4.3.\h'|2.2i'Symmetry Clean Algorithm\l'|5.6i.'\010 +.br +\h'|1.5i'3.3.4.4.\h'|2.2i'Signal to Noise Estimate\l'|5.6i.'\010 +.br +\h'|1.5i'3.3.4.5.\h'|2.2i'Centroid\l'|5.6i.'\010 +.br +\h'|1.5i'3.3.4.6.\h'|2.2i'Gaussian Fit to the Marginals\l'|5.6i.'\011 +.br +\h'|1.5i'3.3.4.7.\h'|2.2i'Radial Gaussian Fit to the Subraster\l'|5.6i.'\011 +.br +\h'|1.5i'3.3.4.8.\h'|2.2i'Optimal Filtering of Marginals\l'|5.6i.'\011 +.br +\h'|1.5i'3.3.4.9.\h'|2.2i'2D Optimal Filtering\l'|5.6i.'\012 +.br +\h'|1.5i'3.3.4.10.\h'|2.2i'Other Centering Methods\l'|5.6i.'\012 +.br +\h'|0.9i'3.3.5.\h'|1.5i'The FITSKY Task\l'|5.6i.'\013 +.br +\h'|1.5i'3.3.5.1.\h'|2.2i'Sky Fitting Package Routines\l'|5.6i.'\013 +.br +\h'|1.5i'3.3.5.2.\h'|2.2i'General Sky Fitting Procedures\l'|5.6i.'\014 +.br +\h'|1.5i'3.3.5.3.\h'|2.2i'Sky Pixel Array Techniques\l'|5.6i.'\014 +.br +\h'|2.2i'3.3.5.3.1.\h'|2.9i'Mean\l'|5.6i.'\014 +.br +\h'|2.2i'3.3.5.3.2.\h'|2.9i'Median\l'|5.6i.'\014 +.br +\h'|2.2i'3.3.5.3.3.\h'|2.9i'Mode\l'|5.6i.'\015 +.br +\h'|1.5i'3.3.5.4.\h'|2.2i'Histogram Techniques\l'|5.6i.'\015 +.br +\h'|2.2i'3.3.5.4.1.\h'|2.9i'Centroid\l'|5.6i.'\015 +.br +\h'|2.2i'3.3.5.4.2.\h'|2.9i'Gaussian Fit\l'|5.6i.'\016 +.br +\h'|2.2i'3.3.5.4.3.\h'|2.9i'Optimal Filtering\l'|5.6i.'\016 +.br +\h'|2.2i'3.3.5.4.4.\h'|2.9i'Cross Correlation\l'|5.6i.'\016 +.br +\h'|1.5i'3.3.5.5.\h'|2.2i'Interactive Techniques\l'|5.6i.'\016 +.br +\h'|2.2i'3.3.5.5.1.\h'|2.9i'Histogram Plot\l'|5.6i.'\016 +.br +\h'|2.2i'3.3.5.5.2.\h'|2.9i'Radial Distribution\l'|5.6i.'\016 +.br +\h'|1.5i'3.3.5.6.\h'|2.2i'Pixel Rejection and Region Growing\l'|5.6i.'\017 +.br +\h'|0.9i'3.3.6.\h'|1.5i'The APPHOT Task\l'|5.6i.'\017 +.br +\h'|1.5i'3.3.6.1.\h'|2.2i'The APPHOT Package Routines\l'|5.6i.'\017 +.br +\h'|1.5i'3.3.6.2.\h'|2.2i'The APPHOT Aperture Integration Algorithm\l'|5.6i.'\018 +.br +\h'|0.9i'3.3.7.\h'|1.5i'The POLYPHOT Algorithm \l'|5.6i.'\018 +.sp +4.\h'|0.4i'\fBExample\fP\l'|5.6i.'\019 +.sp +5.\h'|0.4i'\fBThe APHOT Tasks\fP\l'|5.6i.'\021 |