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