diff options
Diffstat (limited to 'noao/digiphot/daophot/doc')
27 files changed, 17806 insertions, 0 deletions
diff --git a/noao/digiphot/daophot/doc/addstar.hlp b/noao/digiphot/daophot/doc/addstar.hlp new file mode 100644 index 00000000..f2e08a45 --- /dev/null +++ b/noao/digiphot/daophot/doc/addstar.hlp @@ -0,0 +1,365 @@ +.help addstar May00 noao.digiphot.daophot +.ih +NAME +addstar -- add artificial stars to images +.ih +USAGE +addstar image photfile psfimage addimage +.ih +PARAMETERS +.ls image +The list of images to which artificial stars are to be added. +.le +.ls photfile +The list of photometry files containing the x and y coordinates and magnitudes +of the artificial stars to be added to \fIimage\fR. If photfile is undefined, +then \fInstar\fR artificial stars uniformly distributed in position, and in +magnitude between \fIminmag\fR and \fImaxmag\fR are added to \fIimage\fR. If +photfile is defined, there must be one photometry file for every input image. +Photfile may be a simple text file containing x, y, magnitude, and id number in +columns 1, 2, 3, and 4 respectively (\fIsimple_text\fR = yes), an APPHOT/DAOPHOT +text database file (\fIsimple_text\fR = no), or an STSDAS binary table file. +.le +.ls psfimage +The list of images containing the PSF models computed by the DAOPHOT PSF task. +The number of PSF images must be equal to the number of input images. If +psfimage is "default", "dir$default", or a directory specification, then PEAK +will look for an image with the name image.psf.?, where ? is the highest +existing version number. +.le +.ls addimage +The root name of the output images. There must be one output root image name + for every input image. If addimage is "default", "dir$default" or a directory +specification, then an output artificial image and artificial star list called +image.add.? and image.art.? respectively are created, where ? is the next +available version number. If the DAOPHOT package parameter \fItext\fR is "yes", +then an APPHOT/DAOPHOT text database file is written, otherwise an STSDAS binary +table is written. +.le +.ls minmag +The minimum magnitude of the computer generated artificial stars to be +added to the image. The actual intensities of the pixels in the artificial +stars are computed with respect to the magnitude of the PSF stored in +\fIpsfimage\fR. +.le +.ls maxmag +The maximum magnitude of the computer generated artificial stars to be +added to the image. The actual intensities of the pixels in the artificial +stars are computed with respect to the magnitude of the PSF stored in +\fIpsfimage\fR. +.le +.ls nstar +The number of computer generated artificial stars to be added to the input +image. +.le +.ls datapars = "" +The text file in which the data dependent parameters are stored. The gain +parameter \fIepadu\fR in electrons per ADU is stored here. If datapars is +undefined then the default parameter set in the user's uparm directory is used. +.le +.ls daopars = "" +The text file in which the daophot fitting parameters are stored. The PSF +radius parameter \fIpsfrad\fR in scale units is stored here. If daopars is +undefined then the default parameter set in the user's uparm directory is used. +.le +.ls simple_text = no +If \fIphotfile\fR is a text file and \fIsimple_text\fR = "no", then ADDSTAR +expects an APPHOT/DAOPHOT database. Otherwise ADDSTAR expects a simple list +format with x, y, magnitude, and id in columns 1, 2,3, and 4 respectively. +.le +.ls seed = 0 +The seed for the random number generator used to generate the positions +and magnitudes of the artificial stars. +.le +.ls nimage = 1 +The number of output images to be created per input image. +.le +.ls idoffset = 0 +The integer offset to be added to the id numbers of stars in the output +artificial photometry file. By default the artificial stars are numbered from 1 +to N where N is the number of artificial stars added to the input frame. +.le +.ls wcsin = ")_.wcsin", wcsout = ")_.wcsout", wcspsf = ")_.wcspsf" +The coordinate system of the input coordinates read from \fIphotfile\fR, of the +psf model \fIpsfimage\fR, and of the output coordinates written to +\fIaddimage\fR respectively. The image header coordinate system is used to +transform from the input coordinate system to the "logical" pixel coordinate +system used internally, from the internal logical system to the PSF model +system, and from the internal "logical" pixel coordinate system to the output +coordinate system. The input coordinate system options are "logical", "tv", +"physical", and "world". The PSF model and output coordinate system options +are "logical", "tv", and "physical". The image cursor coordinate system is +assumed to be the "tv" system. +.ls logical +Logical coordinates are pixel coordinates relative to the current image. +The logical coordinate system is the coordinate system used by the image +input/output routines to access the image data on disk. In the logical +coordinate system the coordinates of the first pixel of a 2D image, e.g. +dev$ypix and a 2D image section, e.g. dev$ypix[200:300,200:300] are +always (1,1). +.le +.ls tv +Tv coordinates are the pixel coordinates used by the display servers. Tv +coordinates include the effects of any input image section, but do not +include the effects of previous linear transformations. If the input +image name does not include an image section, then tv coordinates are +identical to logical coordinates. If the input image name does include a +section, and the input image has not been linearly transformed or copied from +a parent image, tv coordinates are identical to physical coordinates. +In the tv coordinate system the coordinates of the first pixel of a +2D image, e.g. dev$ypix and a 2D image section, e.g. dev$ypix[200:300,200:300] +are (1,1) and (200,200) respectively. +.le +.ls physical +Physical coordinates are pixel coordinates invariant with respect to linear +transformations of the physical image data. For example, if the current image +was created by extracting a section of another image, the physical +coordinates of an object in the current image will be equal to the physical +coordinates of the same object in the parent image, although the logical +coordinates will be different. In the physical coordinate system the +coordinates of the first pixel of a 2D image, e.g. dev$ypix and a 2D +image section, e.g. dev$ypix[200:300,200:300] are (1,1) and (200,200) +respectively. +.le +.ls world +World coordinates are image coordinates in any units which are invariant +with respect to linear transformations of the physical image data. For +example, the ra and dec of an object will always be the same no matter +how the image is linearly transformed. The units of input world coordinates +must be the same as those expected by the image header wcs, e. g. +degrees and degrees for celestial coordinate systems. +.le +The wcsin, wcspsf, and wcsout parameters default to the values of the package +parameters of the same name. The default values of the package parameters +wcsin, wcspsf, and wcsout are "logical", "physical" and "logical" respectively. +.le +.ls cache = ")_.cache" +Cache the image pixels in memory. Cache may be set to the value of the apphot +package parameter (the default), "yes", or "no". By default caching is +disabled. +.le +.ls verify = ")_.verify" +Verify the critical ADDSTAR task parameters? Verify may be set to the +daophot package parameter value (the default), "yes", or "no". +.le +.ls update = ")_.update" +Update the critical ADDSTAR task parameters if \fIverify\fR = "yes"? +Update may be set to the daophot package parameter value (the default), +"yes", or "no". +.le +.ls verbose = ")_.verbose" +Print messages about the progress of ADDSTAR? Verbose may be set to the +daophot package parameter value (the default), "yes", or "no". +.le + +.ih +DESCRIPTION + +ADDSTAR adds artificial stars, whose positions and magnitudes are listed in +\fIphotfile\fR or generated at random by the computer, to the input image +\fIimage\fR using the PSF in \fIpsfimage\fR, and writes the result to the +output image and output photometry file \fIaddimage\fR. If \fIphotfile\fR is +undefined then ADDSTAR generates an artificial photometry list containing +\fInstar\fR stars uniformly distributed in position over the image and in +magnitude between \fIminmag\fR and \fImaxmag\fR. The input photometry file +may be an STSDAS binary table or an APPHOT/DAOPHOT text database file (the +output of the PHOT, PSF, PEAK, NSTAR, or ALLSTAR tasks) or a simple text file +with the x and y positions, magnitude, and id in columns 1, 2, 3 and 4 +respectively. The ids of stars in the output photometry file may be set to +numbers outside the range of the real data by setting the parameter +\fIoffset\fR. Several output images may be written for each input image by +setting the parameter \fInimage\fR greater than 1. + +The coordinates read from \fIphotfile\fR are assumed to be in coordinate +system defined by \fIwcsin\fR. If photfile is undefined the input coordinate +system is logical. The options are "logical", "tv", "physical", and "world" +and the transformation from the input coordinate system to the internal +"logical" system is defined by the image coordinate system. The simplest +default is the "logical" pixel system. Users working on with image sections but + importing pixel coordinate lists generated from the parent image must use the +"tv" or "physical" input coordinate systems. + +The coordinate system of the PSF model is the coordinate system defined by the +\fIwcspsf\fR parameter. Normally the PSF model was derived from the input image +and this parameter default to "logical". However if the PSF model was derived +from a larger image which is a "parent" of the input image, then wcspsf should +be set to "tv" or "physical" depending on the circumstances. + +The coordinates written to \fIaddimage\fR are in the coordinate system defined +by \fIwcsout\fR. The options are "logical", "tv", and "physical". The simplest +default is the "logical" system. Users wishing to correlate the output +coordinates of objects measured in image sections or mosaic pieces with +coordinates in the parent image must use the "tv" or "physical" coordinate +systems. + +If \fIcache\fR is yes and the host machine physical memory and working set size +are large enough, the output image pixels are cached in memory. If caching +is enabled and the first artificial star addition will appear +to take a long time as the entire input image must be read into the output +image before the first artificial star addition is actually made. All +subsequent measurements will be very fast because ADDSTAR is accessing memory +not disk. The point of caching is to speed up random image access by making +the internal image i/o buffers the same size as the image itself. However if +the input object lists are sorted in row order and sparse caching may actually +worsen not improve the execution time. Also at present there is no point in +enabling caching for images that are less than or equal to 524288 bytes, i.e. +the size of the test image dev$ypix, as the default image i/o buffer is exactly +that size. However if the size of dev$ypix is doubled by converting it to a +real image with the chpixtype task then the effect of caching in interactive +is can be quite noticeable if measurements of objects in the top and bottom +halves of the image are alternated. + +The intensities in the artificial stellar images are computed relative to the +intensities in the PSF image, by scaling the magnitudes of the artificial stars +to the magnitude of the PSF in \fIpsfimage\fR. Poisson noise is added to the +artificial stars using the value of the gain stored in the image header keyword +specified by the DATAPARS parameter \fIgain\fR if present, or the value of the +DATAPARS parameter \fIepadu\fR. + +.ih +OUTPUT + +If \fIverbose\fR = yes, a line of output is written to the terminal for each +artificial star added to the input image. + +Full output is written to the output photometry file \fIaddimage\fR. At the +beginning of each file is a header listing the current values of all the +parameters. For each artificial star added to the input image the following +record is written. + +.nf + id xcenter ycenter mag +.fi + +Id is the id number of the star, xcenter and ycenter are its coordinates, and +mag is its magnitude. + +.ih +EXAMPLES + +1. Add 30 stars uniformly distributed between 17 and 20th magnitude and in +position to the input image m92. Display the new image and mark the +artificial stars. Good stars for making the PSF model can be found at +(442,410), (348,189), and (379,67). + +.nf + da> daofind dev$ypix default fwhmpsf=2.5 sigma=5.0 threshold=20.0 + + ... answer verify prompts + + ... find stars in the image + + ... answer will appear in ypix.coo.1 + + da> phot dev$ypix default default annulus=10. dannulus=5. \ + apertures = 5.0 + + ... answer verify prompts + + ... do aperture photometry on the detected stars + + ... answer will appear in ypix.mag.1 + + da> display dev$ypix 1 + + ... display the image + + da> psf dev$ypix default "" default default default psfrad=9.0 \ + fitrad=3.0 mkstars=yes display=imdr + + ... verify the critical parameters + + ... move the image cursor to a candidate star and hit the a key, + a plot of the stellar data appears + + ... type ? for a listing of the graphics cursor menu + + ... type a to accept the star, d to reject it + + ... move to the next candidate stars and repeat the previous + steps + + ... type l to list all the psf stars + + ... type f to fit the psf + + ... move cursor to first psf star and type s to see residuals, + repeat for all the psf stars + + ... type w to save the PSF model + + ... type q to quit, and q again to confirm + + ... the output will appear in ypix.psf.1.imh, ypix.pst.1 and + ypix.psg.1 + + da> addstar dev$ypix "" default default 12.0 17.0 30 epadu=14.0 + + ... verify the critical parameters + + da> display ypix.add.1 2 + + ... display the artificial image + + da> pdump ypix.art.1 xcenter,ycenter yes | tvmark 2 STDIN col=204 + + ... mark the stars on the artificial image +.fi + + +2. Repeat example 1 using the output starlist as input. + +.nf + da> addstar dev$ypix ypix.art.1 default default simple- epadu=14.0 + + ... the answers will appear in ypix.add.2 and ypix.art.2 +.fi + + +3. Repeat example 1 using a simple text file as input. + +.nf + da> pdump ypix.art.1 xc,yc,mag yes > artdata + + ... create a simple text file from the addstar output + + da> addstar dev$ypix artdata default default simple+ epadu=14.0 + + ... the answers will appear in ypix.add.3 and ypix.art.3 +.fi + + +4. Run addstar on a section of the input image using the PSF model derived in +example 1 for the parent image, the artificial star list from examples 2 and +3, and write the results in the coordinate system of the image section +not the parent image. + +.nf + da> addstar dev$ypix[150:450,150:450] artdata default default simple+ \ + epadu=14.0 wcsin=tv wcspsf=tv wcsout=logical + + ... answer the verify prompts + + ... fit the stars + + ... the results will appear in ypix.add.4 and ypix.art.4 + + da> display ypix.add.4 1 + + ... display the image + + da> pdump ypix.art.4 xc,yc yes | tvmark 1 STDIN col=204 + + ... mark the stars + +.fi + + +.ih +TIME REQUIREMENTS +.ih +BUGS +.ih +SEE ALSO +datapars,daopars +.endhelp diff --git a/noao/digiphot/daophot/doc/allstar.hlp b/noao/digiphot/daophot/doc/allstar.hlp new file mode 100644 index 00000000..ab70ff00 --- /dev/null +++ b/noao/digiphot/daophot/doc/allstar.hlp @@ -0,0 +1,519 @@ +.help allstar May00 noao.digiphot.daophot +.ih +NAME +allstar -- group and fit psf to multiple stars simultaneously +.ih +USAGE +allstar image photfile psfimage allstarfile rejfile subimage +.ih +PARAMETERS +.ls image +The list of images containing the stars to be fit. +.le +.ls photfile +The input photometry files containing the initial estimates of the positions, +sky values, and magnitudes of the stars to be fit. There must be one input +photometry file for every input image. If photfile is "default", "dir$default", +or a directory specification, then ALLSTAR looks for a file with the name +image.mag.? where ? is the highest existing version number. Photfile is usually +the output of the DAOPHOT PHOT task but may also be the output of the PSF, PEAK +and NSTAR tasks, or the ALLSTAR task itself. +.le +.ls psfimage +The list of images containing the PSF models computed by the DAOPHOT PSF task. +The number of PSF images must be equal to the number of input images. If +psfimage is "default", "dir$default", or a directory specification, then PEAK +will look for an image with the name image.psf.?, where ? is the highest +existing version number. +.le +.ls allstarfile +The list of output photometry files. There must be one output photometry +file for every input image. If allstarfile is "default", "dir$default", or a +directory specification, then ALLSTAR will write an output file with the name +image.als.? where ? is the next available version number. Allstarfile is a text +database if the DAOPHOT package parameter text is "yes", an STSDAS table +database if it is "no". +.le +.ls rejfile +The list of output rejected photometry files containing the positions and sky +values of stars that could not be fit. If rejfile is undefined, results for all +the stars in photfile are written to \fIallstarfile\fR, otherwise only the stars +which were successfully fit are written to \fIallstarfile\fR and the remainder +are written to rejfile. If rejfile is "default", "dir$default", or a directory +specification ALLSTAR writes an output file with the name image.als.? where ? is +the next available version number. Otherwise rejfile must specify one output +photometry file for every input image. Rejfile is a text database if the +DAOPHOT package parameter \fItext\fR is "yes", an STSDAS binary table database +if it is "no". +.le +.ls subimage +The list of output images with the fitted stars subtracted. There must be one +subtracted image for every input image. If subimage is "default", "dir$default", +or a directory specification, then ALLSTAR will create an image with the name +image.sub.? where ? is the next available version number. Otherwise +\fIsubimage\fR must specify one output image for every image in \fIimage\fR. +.le +.ls datapars = "" +The name of the file containing the data dependent parameters. The parameters +\fIscale\fR, \fIdatamin\fR, and \fIdatamax\fR are located here. If datapars +is undefined then the default parameter set in uparm directory is used. +.le +.ls daopars = "" +The name of the file containing the daophot fitting parameters. The parameters +\fIpsfrad\fR and \fIfitrad\fR are located here. If \fIdaopars\fR is undefined +then the default parameter set in uparm directory is used. +.le +.ls wcsin = ")_.wcsin", wcsout = ")_.wcsout", wcspsf = ")_.wcspsf" +The coordinate system of the input coordinates read from \fIphotfile\fR, of the +psf model \fIpsfimage\fR, and of the output coordinates written to +\fIallstarfile\fR and \fIrejfile\fR respectively. The image header coordinate +system is used to transform from the input coordinate system to the "logical" +pixel coordinate system used internally, from the internal logical system to +the PSF model system, and from the internal "logical" pixel coordinate system +to the output coordinate system. The input coordinate system options are +"logical", "tv", "physical", and "world". The PSF model and output coordinate +system options are "logical", "tv", and "physical". The image cursor coordinate +system is assumed to be the "tv" system. +.ls logical +Logical coordinates are pixel coordinates relative to the current image. +The logical coordinate system is the coordinate system used by the image +input/output routines to access the image data on disk. In the logical +coordinate system the coordinates of the first pixel of a 2D image, e.g. +dev$ypix and a 2D image section, e.g. dev$ypix[200:300,200:300] are +always (1,1). +.le +.ls tv +Tv coordinates are the pixel coordinates used by the display servers. Tv +coordinates include the effects of any input image section, but do not +include the effects of previous linear transformations. If the input +image name does not include an image section, then tv coordinates are +identical to logical coordinates. If the input image name does include a +section, and the input image has not been linearly transformed or copied from +a parent image, tv coordinates are identical to physical coordinates. +In the tv coordinate system the coordinates of the first pixel of a +2D image, e.g. dev$ypix and a 2D image section, e.g. dev$ypix[200:300,200:300] +are (1,1) and (200,200) respectively. +.le +.ls physical +Physical coordinates are pixel coordinates invariant with respect to linear +transformations of the physical image data. For example, if the current image +was created by extracting a section of another image, the physical +coordinates of an object in the current image will be equal to the physical +coordinates of the same object in the parent image, although the logical +coordinates will be different. In the physical coordinate system the +coordinates of the first pixel of a 2D image, e.g. dev$ypix and a 2D +image section, e.g. dev$ypix[200:300,200:300] are (1,1) and (200,200) +respectively. +.le +.ls world +World coordinates are image coordinates in any units which are invariant +with respect to linear transformations of the physical image data. For +example, the ra and dec of an object will always be the same no matter +how the image is linearly transformed. The units of input world coordinates +must be the same as those expected by the image header wcs, e. g. +degrees and degrees for celestial coordinate systems. +.le +The wcsin, wcspsf, and wcsout parameters default to the values of the package +parameters of the same name. The default values of the package parameters +wcsin, wcspsf, and wcsout are "logical", "physical" and "logical" respectively. +.le +.ls cache = yes +Cache all the data in memory ? If \fIcache\fR is "yes", then ALLSTAR attempts +to preallocate sufficient space to store the input image plus the two +image-sized working arrays it requires, plus space for the starlist, in memory. +This can significantly reduce the total execution time. Users should however +beware of creating a situation where excessive paging occurs. If \fIcache\fR = +"no", ALLSTAR operates on subrasters containing the group currently being +reduced, and writes the intermediate results to temporary scratch images. This +option will work on any-sized image (unless a single group becomes the size of +the entire image!) but can become slow of there are a large number of disk +accesses. Users may wish to experiment to see which mode of operation suits +their system best. +.le +.ls verbose = ")_.verbose" +Print messages about the progress of the task ? Verbose can be set to the +DAOPHOT package parameter value (the default), "yes", or "no". +.le +.ls verify = ")_.verify" +Verify the critical ALLSTAR task parameters. Verify can be set to the daophot +package parameter value (the default), "yes", or "no". +.le +.ls update = ")_.update" +Update the critical ALLSTAR task parameters if \fIverify\fR = "yes". Update +can be set to the daophot package parameter value (the default), "yes", or +"no". +.le + +.ih +DESCRIPTION + +ALLSTAR computes x and y centers, sky values, and magnitudes for the stars in +\fIphotfile\fR by fitting the PSF \fIpsfimage\fR to groups of stars in the IRAF +image \fIimage\fR. Initial estimates of the centers, sky values, and +magnitudes, are read from the photometry list \fIphotfile\fR. ALLSTAR groups +the stars dynamically, performing a regrouping operation after every iteration. +The new computed centers, sky values, and magnitudes are written to +\fIallstarfile\fR along with the number of iterations it took to fit the +star, the goodness of fit statistic chi, and the image sharpness statistic +sharp. If \fIrejfile\fR is not null (""), only stars that are successfully fit +are written to \fIallstarfile\fR, and the remainder are written to +\fIrejfile\fR. Otherwise all the stars are written to \fIallstarfile\fR. +\fIAllstarfile\fR and \fIrejfile\fR are text databases if the DAOPHOT package +parameter \fItext\fR is "yes", STSDAS table databases if it is "no". An image +with all the fitted stars subtracted out is written to \fIsubimage\fR. In +effect ALLSTAR performs the combined operations of GROUP, GRPSELECT, NSTAR, +and SUBSTAR. + +The coordinates read from \fIphotfile\fR are assumed to be in coordinate +system defined by \fIwcsin\fR. The options are "logical", "tv", "physical", +and "world" and the transformation from the input coordinate system to the +internal "logical" system is defined by the image coordinate system. The +simplest default is the "logical" pixel system. Users working on with image +sections but importing pixel coordinate lists generated from the parent image +must use the "tv" or "physical" input coordinate systems. + +The coordinate system of the PSF model is the coordinate system defined by the +\fIwcspsf\fR parameter. Normally the PSF model was derived from the input image +and this parameter default to "logical". However if the PSF model was derived +from a larger image which is a "parent" of the input image, then wcspsf should +be set to "tv" or "physical" depending on the circumstances. + +The coordinates written to \fIallstarfile\fR and \fIrejfile\fR are in the +coordinate system defined by \fIwcsout\fR. The options are "logical", "tv", and +"physical". The simplest default is the "logical" system. Users wishing to +correlate the output coordinates of objects measured in image sections or +mosaic pieces with coordinates in the parent image must use the "tv" or +"physical" coordinate systems. + +By default ALLSTAR computes new centers for all the stars in \fIphotfile\fR. +However if the DAOPARS parameter \fIrecenter\fR is "no", ALLSTAR assumes that +the x and y centers in \fIphotfile\fR are the true centers and does not refit +them. This option can be quite useful in cases where accurate center values +have been derived from an image that has been through some non-linear image +restoration algorithm, but the photometry must be derived from the original +unrestored image. + +By default (\fIgroupsky\fR = "yes") ALLSTAR computes the sky value for each +group by averaging the individual sky values in \fIphotfile\fR for all the +stars in the group. If \fIgroupsky\fR = "no", the sky value for each pixel +which contributes to the group fit is set equal to the mean of the sky values +for those stars for which the pixel falls within one fitting radius. If the +DAOPARS parameter \fIfitksy\fR is "yes", then ALLSTAR recomputes the individual +sky values before averaging over the group, by, every third iteration, +subtracting off the current best fit for the star and using the pixel values in +the annulus defined by the DAOPARS parameters \fIsannulus\fR and \fIwsannulus\fR +to recompute the sky. The actual sky recomputation is done by averaging forty +percent of the sky pixels centered on the median of the distribution. +Recomputing the sky can significantly reduce the scatter in the magnitudes in +regions where the sky background is varying rapidly. + +Only pixels within the good data range defined by the DATAPARS task parameters +\fIdatamin\fR and \fIdatamax\fR are included in the fit. Most users set +\fIdatamin\fR and \fIdatamax\fR so as to exclude pixels outside the linearity +regime of the detector. By default all the data is fit. Users are advised to +determine accurate values for these parameters for their detector and set the +values in DATAPARS before beginning any DAOPHOT reductions. + +Only pixels within the fitting radius parameter \fIfitrad\fR / \fIscale\fR are +included in the fit for each star. \fIFitrad\fR is located in the DAOPARS task +and \fIscale\fR is located in the DATAPARS task. Since the non-linear +least-squares fits normally compute three unknowns, the x and y position of +the star's centroid and its brightness, the value of \fIfitrad\fR must be +sufficiently large to include at least three pixels in the fit for each star. +To accelerate the convergence of the non-linear least-squares fitting algorithm +pixels within \fIfitrad\fR are assigned weights which are inversely +proportional to the radial distance of the pixel from the x and y centroid of +the star, falling from a maximum at the centroid to zero at the fitting radius. +\fIFitrad\fR must be sufficiently large to include at least three pixels with +non-zero radial weights in the fit for each star. ALLSTAR arbitrarily imposes a +minimum number of good pixels limit of four. Values of \fIfitrad\fR close to +the full-width at half-maxima of the PSF are recommended. + +ALLSTAR computes a weighted fit to the PSF. The weight of each pixel is +computed by combining, the radial weighting function described above, with +weights derived from the random errors ALLSTAR predicts based on the detector +noise characteristics specified by the DATAPARS parameters \fIreadnoise\fR and +\fIepadu\fR, and the flat-fielding and profile interpolation errors specified +by the DAOPARS task \fIflaterr\fR and \fIproferr\fR parameters. Both to obtain +optimal fits, and because ALLSTAR employs a conservative formula for reducing +the weights of deviant pixels (parametrized by the \fIclipexp\fR and +\fIcliprange\fR parameters in the DAOPARS task) which do not approach the model +as the fit proceeds, which depends on \fIreadnoise\fR, \fIepadu\fR, +\fIflaterr\fR, and \fIproferr\fR, users are strongly advised to determine those +parameters accurately and to enter their values in DATAPARS and DAOPARS before +beginning any DAOPHOT reductions. + +By default for each group of stars to be fit during each iteration, ALLSTAR +extracts a subraster from \fIimage\fR which extends approximately \fIfitrad\fR +/ \fIscale\fR + 1 pixels wide past the limiting values of x and y coordinates +of the stars in the group. \fIFitrad\fR is the fitting radius specified in the +DAOPARS task. \fIScale\fR is the image scale specified by the DATAPARS task. +\fIFitrad\fR may be less than or equal to but can never exceed the value of the +image header parameter "PSFRAD" in \fIpsfimage\fR. + +If the \fIcache\fR parameter is set to "yes" then ALLSTAR attempts to store all +the vectors and arrays in memory. This can significantly reduce the system +overhead but may cause excessive paging on machines with a small amount of +memory. For large images it may be necessary to set \fIcache\fR to "no", and +use the disk for scratch storage. Users should experiment to see what suits +them best. + +As well as the computed x and y centers, sky values, and magnitudes, ALLSTAR +outputs the number of times the PSF fit had to be iterated before convergence +was achieved. The minimum number of iterations is four. The maximum number of +iteration permitted is specified by the \fImaxiter\fR parameter in the DAOPARS +task. Obviously the results for stars which have reached the maximum iteration +count should be viewed with suspicion. However since the convergence criteria +are quite strict, (the computed magnitude must change by less than .0005 +magnitudes or 0.10 sigma whichever is larger and the x and y centroids must +change by less than 0.002 pixels from one iteration to the next), even these +stars may be reasonably well measured. + +ALLSTAR computes a goodness of fit statistic chi which is essentially the ratio +of the observed pixel-to-pixel scatter in the fitting residuals to the expected +scatter. Since the expected scatter is dependent on the DATAPARS task parameters +\fIreadnoise\fR and \fIepadu\fR, and the DAOPARS parameters \fIflaterr\fR and +\fIproferr\fR, it is important for these values to be set correctly. A plot of +chi versus magnitude should scatter around unity with little or no trend in chi +with magnitude, except at the bright end where saturation effects may be +present. + +Finally ALLSTAR computes the statistic sharp which estimates the intrinsic +angular size of the measured object outside the atmosphere. Sharp is roughly +defined as the difference between the square of the width of the object and the +square of the width of PSF. Sharp has values close to zero for single stars, +large positive values for blended doubles and partially resolved galaxies and +large negative values for cosmic rays and blemishes. + +ALLSTAR implements a sophisticated star rejection algorithm. First of all any +group of stars which is more than a certain size is not reduced. This maximum +group size is specified by the \fImaxgroup\fR parameter in the DAOPARS task. +Large groups may run into numerical precision problems during the fits, so +users should increase this parameter with caution. ALLSTAR however, in +contrast to NSTAR, attempts to subdivide large groups. If the group is too +dense to reduce in size, ALLSTAR throws out the faintest star in the group +and tries to rereduce it. If two stars in a group have centroids separated +by a critical distance currently set arbitrarily to 0.37 * the FWHM of the +stellar core and their photocentric position and combined magnitude is assigned +to the brighter of the two and the fainter is eliminated. Any star which +converges to magnitude 12.5 magnitudes greater than the magnitude of the PSF +is considered to be non-existent and eliminated from the group. + +After iteration 5, if the faintest star in the group has a brightness less +than one sigma above zero it is eliminated. After iteration 10 if the faintest +star in the group has a brightness less than 1.5 sigma above zero it is +eliminated. After iteration 15, or whenever the solutions has converged +whichever comes first, if the faintest star in the group has a brightness less +than 2.0 sigma above zero it is eliminated. After iterations 5, 10 and 15 if +two stars are separated by more than 0.37 * FWHM and less than 1.0 * FWHM and +if the fainter of the two is more uncertain than 1.0, 1.5 or 2.0 sigma +respectively the fainter one is eliminated. + +ALLSTAR replaces the functionality of the GROUP, GRPSELECT, NSTAR and SUBSTAR +task. However the user has little control over the grouping process and does +not know at the end which stars were fit together. The grouping process is +dynamic, as the groups are recomputed after each iteration, and stars can be +fit and leave the group at any point after the fourth iteration. Therefore the +quality of the fits may vary over the image as a function of crowding in an +unknown way. However ALLSTAR is in most cases the routine of choice. NSTAR +is the task of choice when a user wants to maintain control over the +composition of the stellar groups. + +.ih +OUTPUT + +If \fIverbose\fR = yes, a single line is output to the terminal for each star +fit or rejected. Full output is written to \fIallstarfile\fR and \fIrejfile\fR. +At the beginning of these two files a header listing the current values of the +parameters is written. For each star fit/rejected the following quantities are +written to the output file. + +.nf + id xcenter ycenter mag merr msky niter sharpness chi + pier perr +.fi + +Id is the id number of the star. Xcenter and ycenter are the fitted coordinates +in pixels. Mag and merr are the fitted magnitude and magnitude error +respectively. Msky is the individual sky value for the star. Niter is the +number of iterations it took to fit the star and sharpness and chi are the +sharpness and goodness of fit statistic respectively. Pier and perror are the +photometry error code and accompanying error message respectively. + +.ih +ERRORS + +If no errors occur during the fitting process then pier is 0. Non-zero +values of pier flag the following error conditions. + +.nf + 0 # No error + 1 # The star is in a group too large to fit + 2 # The sky is undefined + 3 # There are too few good pixels to fit the star + 4 # The fit is singular + 5 # The star is too faint + 6 # The star has merged with a brighter star + 7 # The star is off the image +.fi + +.ih +EXAMPLES + +1. Fit the PSF to a list stars in the test image dev$ypix. Good stars for +making the PSF model can be found at (442,410), (348,189), and (379,67). + +.nf + da> datapars.epadu = 14.0 + da> datapars.readnoise = 75.0 + + ... set the gain and readout noise for the detector + + da> daofind dev$ypix default fwhmpsf=2.5 sigma=5.0 threshold=20.0 + + ... answer verify prompts + + ... find stars in the image + + ... answer will appear in ypix.coo.1 + + da> phot dev$ypix default default annulus=10. dannulus=5. \ + apertures = 3.0 + + ... answer verify prompts + + ... do aperture photometry on the detected stars + + ... answer will appear in ypix.mag.1 + + da> display dev$ypix 1 + + da> psf dev$ypix default "" default default default psfrad=11.0 \ + fitrad=3.0 mkstars=yes display=imdr + + ... verify the critical parameters + + ... move the image cursor to a candidate star and hit the a key, + a plot of the stellar data appears + + ... type ? for a listing of the graphics cursor menu + + ... type a to accept the star, d to reject it + + + ... move to the next candidate stars and repeat the previous + steps + + ... type l to list all the psf stars + + ... type f to fit the psf + + ... move cursor to first psf star and type s to see residuals, + repeat for all the psf stars + + ... type w to save the PSF model + + ... type q to quit, and q again to confirm + + ... the output will appear in ypix.psf.1.imh, ypix.pst.1 and + ypix.psg.1 + + da> allstar dev$ypix default default default default default + + ... verify the prompts + + ... the results will appear in ypix.als.1 and ypix.arj.1 + + da> pdump ypix.als.1 sharpness,chi yes | graph + + ... plot chi versus sharpness, the stars should cluster around + sharpness = 0.0 and chi = 1.0, note that the frame does + not have a lot of stars + + da> display ypix.sub.1 2 + + ... note that the psf stars subtract reasonably well but other + objects which are not stars don't +.fi + + +2. Repeat example 1 but refit the sky using an annulus with an inner sky +radius of 3.0 and an outer radius of 15.0. + +.nf + da> allstar dev$ypix default default default default default fitsky+ \ + sannulus=3.0 wsannulus=12.0 + + ... verify the prompts + + ... the results will appear in ypix.als.2 and ypix.arj.2 + + da> pdump ypix.als.2 sharpness,chi yes | graph + + ... plot chi versus sharpness, the stars should cluster around + sharpness = 0.0 and chi = 1.0, note that the frame does + not have a lot of stars + + da> display ypix.sub.2 2 + + ... note that the psf stars subtract reasonably well but other + objects which are not stars don't +.fi + + + +3. Run allstar on a section of the input image using the group file and PSF +model derived in example 1 for the parent image and writing the results +in the coordinate system of the parent image. + +.nf + da> allstar dev$ypix[150:450,150:450] default default default default \ + default wcsin=tv wcspsf=tv wcsout=tv + + ... answer the verify prompts + + ... fit the stars + + ... the results will appear in ypix.als.3 and ypix.arj.3 + + da> display dev$ypix[150:450,150:450] 1 + + ... display the image + + da> pdump ypix.als.3 xc,yc yes | tvmark 1 STDIN col=204 + + ... mark the stars on the original image + + da> display ypix.sub.3 2 + + ... display the subtracted image section + +.fi + + +4. Run allstar exactly as in example 1 but submit the task to the background. +Turn off verify and verbose. + +.nf + da> allstar dev$ypix default default default default default verbose- \ + verify- & + + ... the results will appear in ypix.als.4 and ypix.arj.4 +.fi + + +4. Run ALLSTAR exactly as in example 3 but turn caching off. + +.nf + da> allstar m92 m92.grp.1 m92.psf.1 default "" default verb+ veri- \ + cache- > allstar.out & +.fi + +.ih +TIME REQUIREMENTS +.ih +BUGS +.ih +SEE ALSO +datapars,daopars,peak,nstar +.endhelp diff --git a/noao/digiphot/daophot/doc/centerpars.hlp b/noao/digiphot/daophot/doc/centerpars.hlp new file mode 100644 index 00000000..7b461cb1 --- /dev/null +++ b/noao/digiphot/daophot/doc/centerpars.hlp @@ -0,0 +1,207 @@ +.help centerpars May00 noao.digiphot.daophot +.ih +NAME +centerpars -- edit the centering algorithm parameters +.ih +USAGE +centerpars +.ih +PARAMETERS +.ls calgorithm = "none" +The centering algorithm. The "gauss" and "ofilter" centering algorithms +depend critically on the value of the fwhmpsf parameter in the DATAPARS task. +The centering options are: +.ls none +The initial positions are assumed to be the true centers. Users should +select this option if the initial centers are known to be accurate, +e.g. they were computed by DAOFIND task. +.le +.ls centroid +The object centers are determined by computing the intensity weighted means +of the marginal profiles in x and y. Centroid is the recommended centering +algorithm for users running PHOT interactively and selecting objects +with the image display cursor, or when the input coordinates may be inaccurate. +.le +.ls gauss +The object centers are computed by fitting a Gaussian of fixed fwhmpsf, +specified by the DATAPARS fwhmpsf parameter, to the marginal profiles in +x and y using non-linear least squares techniques. +.le +.ls ofilter +The object centers are computed using optimal filtering techniques, +a triangular weighting function of half width equal to fwhmpsf as +specified by the DATAPARS fwhmpsf parameter, and the marginal distributions +in x and y. +.le +.le +.ls cbox = 5.0 (scale units) +The width of the subraster used for object centering in units of the +scale parameter. Cbox needs to be big enough to include sufficient +pixels for centering but not so large as to include a lot of noise. +Reasonable starting values are 2.5-4.0 * FWHM of the PSF. +.le +.ls cthreshold = 0.0 (sigma units) +xels cthreshold * sigma above (emission features) or below (absorption +features) the data minimum or maximum respectively are used by the centering +algorithms where sigma is equal to the value of the DATAPARS sigma parameter. +features) the data minimum or maximum are used by the centering algorithms. +DAOPHOT users should leave this value at 0.0 which invokes the appropriate +default thresholding technique for each centering algorithm. Setting +cthreshold to INDEF turns off thresholding altogether for all the centering +algorithms. +.le +.ls minsnratio = 1.0 +The minimum signal to noise ratio for object centering. If the estimated signal +to noise ratio is less than minsnratio the computed center will be returned +with an error flag. +.le +.ls cmaxiter = 10 +The maximum number of iterations performed by the centering algorithm. +All the centering algorithms use this parameter. +.le +.ls maxshift = 1.0 (scale units) +The maximum permissible shift of the center with respect to the initial +coordinates in units of the scale parameter. If the shift produced by the +centering algorithms is larger than maxshift, the computed center is returned +with an error flag. +.le +.ls clean = no +Symmetry-clean the centering subraster before centering? DAOPHOT users should +leave clean set to "no". +.le +.ls rclean = 1.0 (scale units) +The cleaning radius for the symmetry-clean algorithm in units of +the scale parameter. +.le +.ls rclip = 2.0 (scale units) +The clipping radius for the symmetry-clean algorithm in units of +the scale parameter. +.le +.ls kclean = 3.0 (sigma) +The number of standard sky deviations for the symmetry-clean algorithm. +.le +.ls mkcenter = no +Mark the fitted centers on the displayed image ? +.le +.ih +DESCRIPTION + +The centering algorithm parameters control the action of the centering +algorithms. The default parameters values have been proven to produce +reasonable results in the majority of cases. Several of the centering +parameters are defined in terms of the DATAPARS parameter \fIscale\fR, +the scale of the image, and \fIsigma\fR the standard deviation of +the sky pixels. + +For each object to be measured a subraster of data \fIcbox\fR / \fIscale\fR +pixels wide around the initial position supplied by the user is extracted +from the IRAF image. If scale is defined in units of the number +the half-width half-maximum of the psf per pixel, then a single value of +cbox can be used for centering objects in images with different psfs. + +If \fIclean\fR is "yes" the symmetry-clean algorithm is applied to the +centering subraster prior to centering. The cleaning algorithm attempts +to correct defects in the centering subraster by assuming that the image +is radially symmetric and comparing pixels on opposite sides of the center +of symmetry. The center of symmetry is assumed to be the maximum pixel +in the subraster, unless the maximum pixel is more than \fImaxshift / +scale\fR from the initial center, in which case the initial center is used +as the center of symmetry. Pixels inside the cleaning radius are not edited. +Pairs of pixels in the cleaning region, r > \fIrclean\fR / \fIscale\fR +and r <= \fIrclip\fR / \fIscale\fR and diametrically opposed about the +center of symmetry are tested for equality. If the difference between the +pixels is greater than \fIkclean * sigma\fR, the larger value is replaced +by the smaller. In the cleaning region the sigma is determined by the +noise model assumed for the data. Pairs of pixels in the clipping region, +r > \fIrclip\fR / \fIscale\fR are tested in the same manner as those in +the cleaning region. However the sigma employed is the sigma of the +sky background. DAOPHOT users should leave clean set to "no". + + + + +New centers are computed using the centering algorithm specified by +\fIcalgorithm\fR, the data specified by \fIcbox / scale\fR, and pixels +that are some threshold above (below) an estimate of the local minimum +(maximum). \fICthreshold\fR values of 0.0, a positive number, and INDEF +invoke the default thresholding algorithm, a threshold equal to the +local minimum (maximum) plus (minus) \fIdatapars.sigma * cthreshold\fR, +and a threshold exactly equal to the local minimum (maximum) respectively. + +After thresholding the signal to noise ratio of the subraster is estimated. +If the SNR < \fIminsnratio\fR the new center is still computed but an error +flag is set. + +The default centering algorithm is \fInone\fR is which case the initial +centers are assumed to be accurate and no recentering is done. + +The simplest centering algorithm is \fIcentroid\fR. Centroid computes the +intensity weighted mean and mean error of the centering box x and y marginal +distributions using points in the marginal arrays above (below) the minimum +(maximum) data pixel plus (minus) a threshold value. The threshold value is +either the mean, \fIdatapars.sigma * cthreshold\fR above (below) the local +minimum (maximum) if \fIcthreshold\fR is greater than zero, or zero above +(below) the local minimum (maximum) if \fIcthreshold\fR is INDEF. The centroid +algorithm is similar to that by the old KPNO Mountain Photometry Code. +Note that centroid is the only centering algorithm which does not depend +on the value of \fIdatapars.fwhmpsf\fR. + +The centering algorithm \fIgauss\fR computes the new centers by fitting a +1D Gaussian function to the marginal distributions in x and y using a +fixed fwhmpsf set by \fIdatapars.fwhmpsf\fR. Initial guesses for the fit +parameters are derived from the data. The gauss algorithm iterates until +a best fit solution is achieved. + +The final centering algorithm choice \fIofilter\fR employs a variation of the +optimal filtering technique in which the profile is simulated by a triangle +function of width \fIdatapars.fwhmpsf\fR. + +The default thresholding algorithm for all centering algorithms other +than "centroid" is no thresholding. + +If the computed shift in either coordinate > \fImaxshift\fR / \fIscale\fR, +the new center is returned but an error flag is set. + + +1. List the centering parameters. + +.nf + da> lpar centerpars +.fi + +2. Edit the centering parameters. + +.nf + da> centerpars +.fi + +3. Edit the CENTERPARS parameters from with the PHOT task. + +.nf + da> epar phot + + ... edit a few phot parameters + + ... move to the centerpars parameter and type :e + + ... edit the centerpars parameters and type :wq + + ... finish editing the phot parameters and type :wq +.fi + +4. Save the current CENTERPARS parameter set in a text file ctrnite1.par. +This can also be done from inside a higher level task as in the +above example. + +.nf + da> epar centerpars + + ... type ":w ctrnite1.par" from within epar +.fi +.ih +BUGS + +.ih +SEE ALSO +epar,lpar,datapars,phot +.endhelp diff --git a/noao/digiphot/daophot/doc/daoedit.hlp b/noao/digiphot/daophot/doc/daoedit.hlp new file mode 100644 index 00000000..fa3ed38d --- /dev/null +++ b/noao/digiphot/daophot/doc/daoedit.hlp @@ -0,0 +1,164 @@ +.help daoedit May00 noao.digiphot.daophot +.ih +NAME +daoedit -- edit the daophot package parameters interactively +.ih +USAGE +daoedit image +.ih +PARAMETERS +.ls image +.le +.ls icommands = "" +The image display cursor or image cursor commands file. +.le +.ls gcommands = "" +The graphics cursor or graphics cursor commands file. +.le +.ls cache = ")_.cache" +Cache the image pixels in memory. Cache may be set to the value of the apphot +package parameter (the default), "yes", or "no". By default caching is +disabled. +.le +.ls graphics = ")_.graphics" +The standard graphics device. +.le +.ls display = ")_.display" +The standard display device. +.le +.ih +DESCRIPTION + +DAOEDIT is a general purpose tool for interactively examining and editing +the DAOPHOT algorithm parameters located in the parameter sets DATAPARS, +FINDPARS, CENTERPARS, FITSKYPARS, PHOTPARS, and DAOPARS. These five parameter +sets can be listed, edited, and/or unlearned as a group from within DAOEDIT +using the IRAF LPAR, EPAR and UNLEARN utilities. Any parameter in each of +these five parameter sets can be examined or edited individual using a simple +command. Parameters which are defined in terms of radial distance from the +center of a star or in terms of image counts can be examined and edited +interactively using radial profile plots and the graphics cursor. + +If \fIcache\fR is yes and the host machine physical memory and working set size +are large enough, the input image pixels are cached in memory. If caching +is enabled the first data measurement will appear to take a long time as the +entire image must be read in before the measurement is actually made. All +subsequent measurements will be very fast because DAOEDIT is accessing memory +not disk. The point of caching is to speed up random image access by making +the internal image i/o buffers the same size as the image itself. At present +there is no point in enabling caching for images that are less than or equal +to 524288 bytes, i.e. the size of the test image dev$ypix, as the default image + i/o buffer is exactly that size. However if the size of dev$ypix is doubled by + converting it to a real image with the chpixtype task then the effect of +caching in interactive is can be quite noticeable if measurements of objects +in the top and bottom halves of the image are alternated. + +.ih +CURSOR COMMANDS + +.nf + Interactive Keystroke Commands + +? Print help +: Colon commands +a Estimate center, sky, skysigma, fwhmpsf and magnitude of a star +r Plot the radial profile of a star and its integral +i Set selected parameters interactively using a radial profile plot +g Toggle between image and graphics cursor +x Toggle the radial profile plot between pixel and scale units +y Toggle the radial profile plot between counts and normal units +q Quit task + + Colon Commands + +:lparam/eparam/unlearn pset List/edit/unlearn the named pset +:parameter [value] List or set an individual pset parameter + + + Psets + +datapars The data dependent parameters +findpars The daofind task object detection parameters +centerpars The phot task centering algorithm parameters +fitskypars The phot task sky fitting algorithm parameters +photpars The phot task photometry algorithm parameters +daopars The psf fitting algorithm parameters + + +The following commands are available from within the interactive setup +menu. + + + Interactive Daoedit Setup Menu + +? Print help +spbar Mark/verify critical parameters (f, s, a, d, r, w, b) +q Quit + +f Mark/verify the fwhm of the psf on the radial profile plot +s Mark/verify the sky sigma on the radial profile plot +l Mark/verify the minimum good data value on the radial profile plot +u Mark/verify the maximum good data value on the radial profile plot + +c Mark/verify the centering box half-width on the radial profile plot +n Mark/verify the cleaning radius on the radial profile plot +p Mark/verify the clipping radius on the radial profile plot + +a Mark/verify the inner sky annulus radius on the radial profile plot +d Mark/verify the width of the sky annulus on the radial profile plot +g Mark/verify the sky region growing radius on the radial profile plot + +r Mark/verify the photometry aperture(s) on the radial profile plot +w Mark/verify the psf function radius on the radial profile plot +b Mark/verify the psf fitting radius on the radial profile plot + +.fi + +.ih +EXAMPLES + +1. Setup the daophot package parameters interactively for the image m92. +This example assumes that the parameters are all initially at their +default values. + +.nf + da> display dev$ypix 1 + da> daoedit dev$ypix + + ... type :e datapars to edit the data dependent parameters + ... leave scale at 1.0 and datamin at INDEF but set the + datamax, readnoise, epadu, exposure, airmass, filter, + and obstime parameters to appropriate values + ... type :l datapars to check the results of the editing + + ... type :e findpars to check the object detection parameters + ... change the findpars threshold parameter from 4.0 to 5.0 + using the command :threshold 5.0 + + ... type i to enter the interactive setup menu + set the fwhmpsf, sigma, inner radius of the sky annulus, + width of the sky annulus, photometry aperture(s), psf + radius, and fitting radius using the radial profile + plot and graphics cursor + + ... select a bright non-saturated star and check that its + radial profile is normal using the r keystroke command + ... note the value of the standard deviation of the sky + background written in the plot header + ... set the datapars sigma parameter to this value using + the command :sigma <value> + + ... check the data definition, centering, sky fitting, + photometry, and psf fitting parameters with the commands + :l datapars, :l centerpars, :l fitskypars, :l photpars, + and :l daopars +.fi + +.ih +TIME REQUIREMENTS +.ih +BUGS +.ih +SEE ALSO +datapars,findpars,centerpars,fitskypars,photpars,daopars,setimpars +.endhelp diff --git a/noao/digiphot/daophot/doc/daofind.hlp b/noao/digiphot/daophot/doc/daofind.hlp new file mode 100644 index 00000000..a2b1c3f8 --- /dev/null +++ b/noao/digiphot/daophot/doc/daofind.hlp @@ -0,0 +1,601 @@ +.help daofind May00 noao.digiphot.daophot +.ih +NAME +daofind -- automatically detect objects in images +.ih +USAGE +daofind image output +.ih +PARAMETERS +.ls image +The list of images in which objects are to be detected. +.le +.ls output +The name of the results file or the results directory. If output is +"default", "dir$default" or a directory specification then a results file +name of the form dir$root.extension.version is constructed, where +dir is the directory, root is the root image name, extension is "coo" +and version is the next available version number for the file. If the +output string is undefined then no output file is created. One output +file is created for every input image. +.le +.ls starmap = "" +The name of the image prefix and/or directory where the density enhancement +image will be stored. If starmap is undefined or a directory, +DAOFIND will create a temporary image which is deleted on exit from +the program. Otherwise starmap is prefixed to the image name +and the density enhancement image will be saved for use in a subsequent +run of DAOFIND. +.le +.ls skymap = "" +The name of the image prefix and/or directory where the mean density +image will be stored. If skymap is undefined or a directory, no mean density +image is created. Otherwise skymap is prefixed to the image name +and the mean density image will be saved on disk. Skymap is not used by +the DAOFIND algorithms, but may be used by the user as a check on DAOFIND, +since the sum of starmap and skymap is a type of best fit to the original +image. +.le +.ls datapars = "" +The name of the file containing the data dependent parameters. The critical +parameters \fIfwhmpsf\fR and \fIsigma\fR are located here. If \fIdatapars\fR +is undefined then the default parameter set in the user's uparm directory is +used. +.le +.ls findpars = "" +The name of the file containing the object detection parameters. The +parameter \fIthreshold\fR is located here. If findpars is undefined then +the default parameter set in the user's uparm directory is used. +.le +.ls boundary = "nearest" +The type of boundary extension. The choices are: +.ls nearest +Use the value of the nearest boundary pixel. +.le +.ls constant +Use a constant value. +.le +.ls reflect +Generate a value by reflecting around the boundary. +.le +.ls wrap +Generate a value by wrapping around to the other side of the image. +.le +.le +.ls constant = 0 +The constant for constant boundary extension. +.le +.ls interactive = no +Interactive or batch mode? +.le +.ls icommands = "" +The image display cursor or image cursor command file. +.le +.ls gcommands = "" +The graphics cursor or graphics cursor command file. +.le +.ls wcsout = ")_.wcsout" +The coordinate system of the output coordinates written to \fIoutput\fR. The +image header coordinate system is used to transform from the internal "logical" +pixel coordinate system to the output coordinate system. The output coordinate +system options are "logical", "tv", and "physical". The image cursor coordinate + system is assumed to be the "tv" system. +.ls logical +Logical coordinates are pixel coordinates relative to the current image. +The logical coordinate system is the coordinate system used by the image +input/output routines to access the image data on disk. In the logical +coordinate system the coordinates of the first pixel of a 2D image, e.g. +dev$ypix and a 2D image section, e.g. dev$ypix[200:300,200:300] are +always (1,1). +.le +.ls tv +Tv coordinates are the pixel coordinates used by the display servers. Tv +coordinates include the effects of any input image section, but do not +include the effects of previous linear transformations. If the input +image name does not include an image section, then tv coordinates are +identical to logical coordinates. If the input image name does include a +section, and the input image has not been linearly transformed or copied from +a parent image, tv coordinates are identical to physical coordinates. +In the tv coordinate system the coordinates of the first pixel of a +2D image, e.g. dev$ypix and a 2D image section, e.g. dev$ypix[200:300,200:300] +are (1,1) and (200,200) respectively. +.le +.ls physical +Physical coordinates are pixel coordinates invariant with respect to linear +transformations of the physical image data. For example, if the current image +was created by extracting a section of another image, the physical +coordinates of an object in the current image will be equal to the physical +coordinates of the same object in the parent image, although the logical +coordinates will be different. In the physical coordinate system the +coordinates of the first pixel of a 2D image, e.g. dev$ypix and a 2D +image section, e.g. dev$ypix[200:300,200:300] are (1,1) and (200,200) +respectively. +.le +The wcsout parameter defaults to the value of the package parameter of the same + name. The default values of the package parameters wcsin and wcsout are +"logical" and "logical" respectively. +.le +.ls cache = ")_.cache" +Cache the image pixels in memory. Cache may be set to the value of the apphot +package parameter (the default), "yes", or "no". By default caching is +disabled. +.le +.ls verify = ")_.verify" +Automatically confirm the critical parameters when running in non-interactive +mode ? Verify may be set to the daophot package parameter value (the default), +"yes", or "no". +.le +.ls update = ")_.update" +Automatically update the parameters when running in non-interactive mode if +verify is "yes"? Update may be set to the daophot package parameter value +(the default), "yes", or "no". +.le +.ls verbose = ")_.verbose" +Print out information about the progress of the task in non-interactive mode. +Verbose may be set to the daophot package parameter value (the default), "yes", +or "no". +.le +.ls graphics = ")_.graphics" +The standard graphics device. Graphics may be set to the apphot package +parameter value (the default), "yes", or "no". +.le +.ls display = ")_.display" +The standard image display device. Display may be set to the apphot package +parameter value (the default), "yes", or "no". By default graphics overlay is +disabled. Setting display to one of "imdr", "imdg", "imdb", or "imdy" enables +graphics overlay with the IMD graphics kernel. Setting display to "stdgraph" +enables DAOFIND to work interactively from a contour plot. +.le + +.ih +DESCRIPTION + +DAOFIND searches the IRAF images \fIimage\fR for local density maxima, +with a full-width half-maxima of \fIdatapars.fwhmpsf\fR, and a peak amplitude +greater than \fIfindpars.threshold\fR * \fIdatapars.sigma\fR above the local +background, and writes a list of detected objects in the file \fIoutput\fR. +The detected objects are also listed on the standard output if the program is +running in interactive mode or if the \fIverbose\fR switch is enabled in +non-interactive mode. + +The coordinates written to \fIoutput\fR are in the coordinate +system defined by \fIwcsout\fR. The options are "logical", "tv", +and "physical". The simplest default is the "logical" system. Users +wishing to correlate the output coordinates of objects measured in +image sections or mosaic pieces with coordinates in the parent +image must use the "tv" or "physical" coordinate systems. + +If \fIcache\fR is yes and the host machine physical memory and working set size +are large enough, the input and output image pixels are cached in memory. If +caching is enabled and DAOFIND is run interactively the first measurement +will appear to take a long time as the entire image must be read in before the +measurement is actually made. All subsequent measurements will be very fast +because DAOFIND is accessing memory not disk. The point of caching is to speed +up random image access by making the internal image i/o buffers the same size +as the image itself. However if the input object lists are sorted in row order +and sparse caching may actually worsen not improve the execution time. Also at +present there is no point in enabling caching for images that are less than +or equal to 524288 bytes, i.e. the size of the test image dev$ypix, as the +default image i/o buffer is exactly that size. However if the size of dev$ypix +is doubled by converting it to a real image with the chpixtype task then the +effect of caching in interactive is can be quite noticeable if measurements +of objects in the top and bottom halves of the image are alternated. + +DAOFIND can be run either interactively or in batch mode by setting the +parameter \fIinteractive\fR. In interactive mode the user can examine, +adjust and save algorithm parameters, and fit or refit the entire list +with the chosen parameter set. The \fIverify\fR parameter can be used to +automatically confirm the critical parameters \fIdatapars.fwhmpsf\fR and +\fIdatapars.sigma\fR when running in non-interactive mode. + + +.ih +CURSOR COMMANDS + +.nf + + Interactive Keystroke Commands + +? Print help +: Colon commands +v Verify critical parameters +w Save the current parameters +d Plot radial profile of star near cursor +i Interactively set parameters using star near cursor +f Find stars in the image +spbar Find stars in the image and output results +q Exit task + + + Colon Commands + +:show [data/find] List the parameters + + Colon Commands + +# Image and file name parameters + +:image [string] Image name +:output [string] Output file name + +# Data dependent parameters + +:scale [value] Image scale (units per pixel) +:fwhmpsf [value] Full width half maximum of psf (scale units) +:emission [y/n] Emission feature (y), absorption (n) +:sigma [value] Standard deviation of sky (counts) +:datamin [value] Minimum good data value (counts) +:datamax [value] Maximum good data value (counts) + +# Noise description parameters + +:noise [string] Noise model (constant|poisson) +:gain [string] Gain image header keyword +:ccdread [string] Readout noise image header keyword +:epadu [value] Gain (electrons per adu) +:readnoise [value] Readout noise (electrons) + +# Observation parameters + +:exposure [string] Exposure time image header keyword +:airmass [string] Airmass image header keyword +:filter [string] Filter image header keyword +:obstime [string] Time of observation image header keyword +:itime [value] Exposure time (time units) +:xairmass [value] Airmass value (number) +:ifilter [string] Filter id string +:otime [string] Time of observation (time units) + +# Object detection parameters + +:nsigma [value] Size of Gaussian kernel (sigma) +:threshold [value] Detection intensity threshold (counts) +:ratio [value] Sigmay / sigmax of Gaussian kernel +:theta [value] Position angle of Gaussian kernel +:sharplo [value] Lower bound on sharpness +:sharphi [value] Upper bound on sharpness +:roundlo [value] Lower bound on roundness +:roundhi [value] Upper bound on roundness + +# Plotting and marking commands + +:mkdetections [y/n] Mark detections on the image display + + + +The following commands are available from inside the interactive setup menu. + + + Interactive Daofind Setup Menu + + v Mark and verify critical daofind parameters (f,s) + + f Mark and verify the full-width half-maximum of the psf + s Mark and verify the standard deviation of the background + l Mark and verify the minimum good data value + u Mark and verify the maximum good data value + +.fi + +.ih +ALGORITHMS + +DAOFIND approximates the stellar point spread function with an elliptical +Gaussian function, whose sigma along the semi-major axis is 0.42466 * +\fIdatapars.fwhmpsf\fR / \fIdatapars.scale\fR pixels, semi-minor to semi-major +axis ratio is \fIratio\fR, and major axis position angle is \fItheta\fR. +Using this model, a convolution kernel, truncated at \fInsigma\fR sigma, +and normalized so as to sum to zero, is constructed. + +The density enhancement image \fIstarmap\fR is computed by convolving the input +image with the Gaussian kernel. This operation is mathematically equivalent to +fitting, in the least-squares sense, the image data at each point with a +truncated, lowered elliptical Gaussian function. After convolution each point +in \fIstarmap\fR contains as estimate of the amplitude of the best fitting +Gaussian function at that point. Each point in \fIskymap\fR, if the user +chooses to compute it, contains an estimate of the best fitting sky value +at that point. + +After image convolution , DAOFIND steps through \fIstarmap\fR searching +for density enhancements greater than \fIfindpars.threshold\fR * +\fIdatapars.sigma\fR, and brighter than all other density enhancements within +a semi-major axis of 0.42466 \fIfindpars.nsigma\fR * \fIdatapars.fwhmpsf\fR. +As the program selects candidates, it computes three shape characteristics, +sharpness and 2 estimates of roundness. The sharpness statistic measures the +ratio of, the difference between the height of the central pixel and the mean +of the surrounding non-bad pixels, to the height of the best fitting Gaussian +function at that point. The first roundness characteristic computes the ratio +of a measure of the bilateral symmetry of the object to a measure of the +four-fold symmetry of the object. The second roundness statistic measures the +ratio of, the difference in the height of the best fitting Gaussian function +in x minus the best fitting Gaussian function in y, over the average of the +best fitting Gaussian functions in x and y. The limits on these parameters +\fIfindpars.sharplo\fR, \fIfindpars.sharphi\fR \fIfindpars.roundlo\fR, and +\fIfindpars.roundhi\fR, are set to weed out non-astronomical objects and +brightness enhancements that are elongated in x and y respectively. + +Lastly the x and y centroids of the detected objects are computed by estimating +the x and y positions of the best fitting 1D Gaussian functions in x and y +respectively, a rough magnitude is estimated by computing the ratio of the +amplitude of the best fitting Gaussian at the object position to +\fIfindpars.threshold\fR * \fIdatapars.sigma\fR, and the object is added to +the output coordinate file. + + +.ih +OUTPUT + +In interactive mode or in non-interactive with the verbose switch turned on +the following quantities are written to the terminal as each object is +detected. + +.nf + xcenter ycenter mag sharpness sround ground id + + where + + mag = -2.5 * log10 (peak density / detection threshold) +.fi + + +The object centers are in pixels and the magnitude estimate measures the +ratio of the maximum density enhancement to the detection threshold. +Sharpness is typically around .5 to .8 for a star with a fwhmpsf similar to +the pattern star. Both sround and ground are close to zero for a truly +round star. Id is the sequence number of the star in the list. + +In both interactive and batch mode the full output is written to the text +file \fIoutput\fR. At the beginning of each file is a header, listing +the current values of the parameters when the first stellar record was +written. The parameters can subsequently be altered. + + +.ih +EXAMPLES + +1. Run daofind on the test image dev$ypix. + +.nf + da> daofind dev$ypix default fwhmpsf=2.5 sigma=5.0 threshold=20 + + ... answer the verify prompts + + ... the output will appear in ypix.coo.1 +.fi + + +2. Run daofind interactively on dev$ypix using the image display +and image display cursor. Set the fwhmpsf and sigma parameters +with the graphics cursor, radial profile plot, and the interactive +setup key i. + +.nf + da> display dev$ypix 1 fi+ + + ... display the image + + da> daofind dev$ypix default interactive+ + + ... type ? to see help screen + + ... move display cursor to a star + ... type i to enter the interactive setup menu + ... enter maximum radius in pixels of the radial profile or + accept default with a CR + ... type v to enter the default setup menu + ... set the fwhmpsf and sigma using the graphics cursor and the + radial profile plot + ... typing <CR> leaves the parameters at their default values + ... type q to quit setup menu + + ... type the v key to verify the critical parameters + + ... type the w key to save the parameters in the parameter files + + ... type the space bar to detect stars in the image + + ... a 1 line summary of the answers will appear on the standard + output for each star measured + + ... type q to quit and q again to confirm the quit + + ... full output will appear in the text file ypix.coo.2 + +.fi + + +3. Run daofind interactively on a single image using a contour plot in place +of the image and the graphics cursor in place of the image cursor. +This option is only useful for those (now very few) users who have access to +a graphics terminal but not to an image display server. Set the fwhmpsf and +sigma parameters with the graphics cursor and radial profile plot and the +interactive setup key i. + +.nf + da> show stdimcur + + ... record the default value of stdimcur + + da> set stdimcur = stdgraph + + ... define the image cursor to be the graphics cursor + + da> contour dev$ypix + + ... make a contour plot of dev$ypix + + da> contour dev$ypix >G ypix.plot1 + + ... store the contour plot of ypix in the file ypix.plot + + da> daofind dev$ypix default display=stdgraph interactive+ + + ... type ? to see the help screen + + ... move graphics cursor to a setup star + ... type i to enter the interactive setup menu + ... enter maximum radius in pixels of the radial profile or + accept the default with a CR + ... type v to enter the default setup menu + ... set the fwhmpsf and sigma using the graphics cursor and the + radial profile plot + ... typing <CR> leaves the parameters at their default values + ... type q to quit the setup menu + + ... type the v key to confirm the critical parameters + + ... type the w key to save the parameters in the parameter files + + ... retype :.read ypix.plot1 to reload the contour plot + + ... type the space bar to detect stars in the image + + ... a 1 line summary of the answers will appear on the standard + output for each star measured + + ... full output will appear in the text file ypix.coo.3 + + da> set stdimcur = <default> + + ... reset the image cursor to its default value + +.fi + + +4. Run DAOFIND interactively without using the image display cursor. + +.nf + da> show stdimcur + + ... record the default value of stdimcur + + da> set stdimcur = text + + ... set the image cursor to the standard input + + da> display dev$ypix 1 + + ... display the image + + da> daofind dev$ypix default interactive+ + + ... type ? for help + + ... type "442 409 101 i" in response to the image cursor query where + x and y are the coordinates of the star to be used as setup, + 101 is the default world coordinate system, and i enters the + interactive setup menu. + ... enter maximum radius in pixels of the radial profile or + type CR to accept the default + ... type v to enter the default setup menu + ... set the fwhmpsf and sigma using the graphics cursor and the + radial profile plot + ... typing <CR> leaves the parameters at their default values + ... type q to quit the setup menu + + ... type the v key to verify the parameters + + ... type the w key to save the parameters in the parameter files + + ... type the space bar to detect stars in the image + + ... a 1 line summary of the answers will appear on the standard + output for each star measured + + ... type q to quit and q again to confirm + + ... full output will appear in the text file ypix.coo.4 + + da> set stdimcur = <default> + + ... reset the image cursor to its default value +.fi + + +5. Run daofind on a list of 3 images contained in the file imlist in batch mode. +The program will ask the user to verify that the fwhmpsf and the threshold are +correct before beginning execution. + +.nf + da> type imlist + dev$ypix + dev$wpix + dev$pix + + da> daofind @imlist default + + ... answer the verify prompts + + ... the output will appear in ypix.coo.5, wpix.coo.1, pix.coo.1 +.fi + + +6. Display and find stars in an image section. Write the output coordinates +in the coordinate system of the parent image. Mark the detected stars on +the displayed image. + +.nf + da> display dev$ypix[150:450,150:450] 1 + + ... display the image section + + da> daofind dev$ypix[150:450,150:450] default wcsout=tv + + ... answer the verify prompts + + ... output will appear in ypix.coo.6 + + da> tvmark 1 ypix.coo.6 col=204 +.fi + + +7. Repeat example 5 but submit the job to the background and turn off the +verify and verbose switches. + +.nf + da> daofind @imlist default verify- verbose- & + + ... the output will appear in ypix.coo.7, wpix.coo.2, pix.coo.2 +.fi + + +8. Use an image cursor command file to drive the daofind task. The cursor +command file shown below sets the fwhmpsf, sigma, and threshold parameters, +located stars in the image, updates the parameter files, and quits the task. + +.nf + da> type cmdfile + : fwhmpsf 2.5 + : sigma 5.0 + : threshold 10.0 + \040 + w + q + + da> daofind dev$ypix default icommands=cmdfile verify- + + ... full output will appear in ypix.coo.8 +.fi + + +.ih +TIME REQUIREMENTS + +.ih +BUGS + +It is currently the responsibility of the user to make sure that the +image displayed in the frame is the same as that specified by the image +parameter. + +Commands which draw to the image display are disabled by default. +To enable graphics overlay on the image display, set the display +parameter to "imdr", "imdg", "imdb", or "imdy" to get red, green, +blue or yellow overlays and set the findpars mkdetections switch to +"yes". It may be necessary to run gflush and to redisplay the image +to get the overlays position correctly. + +.ih +SEE ALSO +datapars,findpars +.endhelp diff --git a/noao/digiphot/daophot/doc/daopars.hlp b/noao/digiphot/daophot/doc/daopars.hlp new file mode 100644 index 00000000..80f340b6 --- /dev/null +++ b/noao/digiphot/daophot/doc/daopars.hlp @@ -0,0 +1,331 @@ +.help daopars May00 noao.digiphot.daophot +.ih +NAME +daopars -- edit the daophot fitting parameters +.ih +USAGE +daopars +.ih +PARAMETERS +.ls function = "gauss" +The functional form of the analytic component of the PSF model computed by the +DAOPHOT PSF task. The better this function matches the true PSF, especially in +the cores of the stars, the smaller the interpolation errors will be. The +choices are the following. + +.ls gauss +An elliptical Gaussian function aligned along the x and y axes of the +input image. +.le +.ls moffat15 +An elliptical Moffat function with a beta parameter of 1.5. +.le +.ls moffat25 +An elliptical Moffat function with a beta parameter of 2.5. +.le +.ls lorentz +An elliptical Lorentzian function with beta parameter of 1.0. +.le +.ls penny1 +A Gaussian core with Lorentzian wings function, where the Gaussian core may be +tilted, but the Lorentzian wings are elongated along the x or y axes. The +Lorentzian wings have a beta parameter of 1.0. +.le +.ls penny2 +A Gaussian core with Lorentzian wings function, where the Gaussian core and +Lorentzian wings may be tilted in different directions. The Lorentzian wings +have a beta parameter of 1.0. +.le +.ls auto +The PSF task computes the analytic PSF model for each of the six analytic model +PSFs in turn and selects the one that produces the smallest standard deviation +for the model fit. +.le +.ls func1,func2,... +The PSF task computes the analytic PSF model for each of a subset of the six +defined functions in turn, and selects the one that produces the smallest +standard deviation for the model fit. +.le + +In general "gauss" is the best and most efficient choice for a well-sampled +ground-based image, "lorentz" is best for old ST images, and "moffat15" or +"moffat25" are best for under-sampled ground-based images. +.le +.ls varorder = 0 +The order of variability of the PSF model computed by the DAOPHOT PSF task. +Varorder sets the number of look-up tables containing the deviations of the +true PSF from the analytic model PSF that are computed by the model. +.ls "-1" +Only the analytic function specified by \fIfunction\fR is used to compute +the PSF model. The PSF model is constant over the image. +.le +.ls "0" +The analytic function and one look-up table are used to compute the +PSF model. The PSF model is constant over the image. +.le +.ls "1" +The analytic function and three look-up tables are used to compute the PSF +model. The PSF model is linearly variable over the image, with terms +proportional to 1, x and y. +.le +.ls "2" +The analytic function and six look-up tables are used to compute the +PSF model. The PSF model is quadratically variable over the image, with terms +proportional to 1, x, y, x**2, xy, y**2. +.le +.le +.ls nclean = 0 +The number of additional iterations the PSF task performs to compute the PSF +look-up tables. If \fInclean\fR is > 0, stars which contribute deviant +residuals to the PSF look-up tables in the first iteration, will be +down-weighted in succeeding iterations. +.le +.ls saturated = no +Use saturated stars to improve the signal-to-noise in the wings of the PSF +model computed by the PSF task? This parameter should only be set to +"yes" where there are too few high signal-to-noise unsaturated stars +in the image to compute a reasonable model for the stellar profile wings. +.le +.ls matchrad = 3.0 (scale units) +The tolerance in scale units for matching the stellar x and y centroids in the +input photometry file with the image cursor position. Matchrad is currently +used by the PSTSELECT and PSF tasks to match stars shown on the image display +with stars in the photometry list. +.le +.ls psfrad = 11.0 (scale units) +The radius of the circle in scale units within which the PSF model is defined. +Psfrad should be a pixel or two larger than the radius at which the intensity +of the brightest star of interest fades into the noise. Psfrad can never be +set larger than the size of the PSF model but may set smaller in tasks +like GROUP, ALLSTAR, SUBSTAR, and ADDSTAR. +.le +.ls fitrad = 3.0 (scale units) +The fitting radius in scale units. Only pixels within the fitting radius of +the center of a star will contribute to the fits computed by the PEAK, NSTAR +and ALLSTAR tasks. For most images the fitting radius should be approximately +equal to the FWHM of the PSF. Under severely crowded conditions a somewhat +smaller value may be used in order to improve the fit. If the PSF is variable, +the FWHM is very small, or sky fitting is enabled in PEAK and NSTAR on the +other hand, it may be necessary to increase the fitting radius to achieve a +good fit. +.le +.ls recenter = yes (peak, nstar, and allstar) +Compute new positions as well as magnitudes for all the stars in the input +photometry list? +.le +.ls fitsky = no (peak, nstar, and allstar) +Compute new sky values for the stars in the input list (peak, nstar, allstar). +If fitsky = "no", the PEAK, NSTAR, and ALLSTAR tasks compute a group sky value +by averaging the sky values of the stars in the group. If fitsky = "yes", +PEAK and NSTAR fit the group sky simultaneously with the positions and +magnitudes. If fitsky = yes the ALLSTAR task computes new sky values for each +star every third iteration by subtracting off the best current fit for the star +and and estimating the median of the pixels in the annulus defined by +\fIsannulus\fR and \fIwsannulus\fR. The new group sky value is the average of +the new individual values. +.le +.ls groupsky = yes (nstar and allstar) +If groupsky is "yes", then the sky value for every pixel which contributes to +the fit is identical and equal to the mean of the sky values of all the stars +in the group. If \fIgroupsky\fR is "no", then the sky value for every pixel +which contributes to the fit is equal to the mean of the sky values of all the +stars in the group for which that pixel is within one fitting radius. +.le +.ls sannulus = 0.0 (scale units, allstar) +The inner radius of the sky annulus used by ALLSTAR to recompute the sky +values. +.le +.ls wsannulus = 11 (scale units, allstar) +The width of the sky annulus used by ALLSTAR to recompute the sky values. +.le +.ls flaterr=0.75 (percent, peak, nstar, allstar) +The image flat-fielding error in percent used to compute the predicted +errors of the fit. +.le +.ls proferr = 5.0 (percent, peak, nstar, allstar) +The profile or interpolation fitting error in percent used to compute +the predicted errors of the fit. +.le +.ls maxiter = 50 (peak, nstar, allstar) +The maximum number of times that the PSF fitting tasks PEAK, NSTAR, and ALLSTAR +will iterate on the PSF fit before giving up. +.le +.ls cliprange = 2.5, clipexp = 6.0 (peak, nstar, allstar) +The parameters of the down-weighting scheme in the fitting code used to resist +bad data. For values of clipexp greater than 1 a residual small compared to +cliprange standard deviations does not have its weight significantly altered, +one with exactly \fIcliprange\fR standard deviations is assigned half its +normal weight, and large residuals are assigned weights which fall off as the +standard deviation to the minus clipexp power. For normal applications users +should leave these parameter at their default value. +.le +.ls critsnratio = 1.0 (group) +The ratio of the model intensity of the brighter star computed at a distance of +one fitting radius from the center of the fainter star, to the expected random +error computed from the readout noise, gain and value of the PSF. The critical +signal-to-noise ratio parameter is used to group stars. In general if a small +value such as 0.1 divides all the stars in an image into groups less than +\fImaxgroup\fR, then the expected random errors will determine the accuracy +of the photometry. On the other hand if a value of critical overlap much +greater than one is required to divide up the stars, crowding errors will +dominate random errors. If a value of 1 is sufficient then crowding and +random errors are roughly equivalent. +.le +.ls mergerad = INDEF (scale units, nstar, allstar) +The critical separation in scale units between two objects for an object merger +to be considered. Objects with separations > mergerad will not be merged; faint +objects with separations <= mergerad will be considered for merging. The +default value of mergerad is sqrt (2 *(PAR1**2 + PAR2**2)), where PAR1 and PAR2 +are the half-width at half-maximum along the major and minor axes of the psf +model. Merging can be turned off altogether by setting mergerad to 0.0. +.le +.ls maxnstar = 10000 (pstselect, psf, group, allstar, substar) +The initial star list buffer size. If there are more than maxnstar stars in the +input photometry file buffer, DAOPHOT will resize the buffers as needed. +The only limitation is the memory and configuration of the host computer. +.le +.ls maxgroup = 60 (nstar, allstar) +The maximum numbers of stars that the multiple star fitting tasks NSTAR and +ALLSTAR will fit simultaneously. NSTAR will not to fit groups large than +maxgroup. ALLSTAR dynamically regroups the stars in large groups until the +group is either maxgroup or smaller in size or becomes too dense to group, +after which the faintest stars are rejected until the group is less than +maxgroup ins size. +.le + +.ih +DESCRIPTION + +DAOPARS is a parameter set task which stores the DAOPHOT parameters +required by all those DAOPHOT tasks which compute the PSF model, fit stars +to the PSF model, or evaluate the PSF model. + +Typing DAOPARS on the terminal invokes the EPAR parameter editing task. The +DAOPARS parameters may also be edited from within an EPAR command on task, +for example PSF, which references them. The DAOPARS parameters may also +be changed on the command line in the usual manner when any task which +references them is executed. + +Any given set of DAOPARS parameters may stored in a text file along with +the data being reduced by typing the :w command from within the EPAR task. If +the user then sets the value of the \fIdaopars\fR parameter to the name of +the file containing the stored parameter set, the stored parameters will be +used instead of the default set in the uparm directory. + +.ih +ALGORITHMS + +The functional forms of the analytic PSF functions are as follows. The +A is simply an amplitude or normalization constant The Pn are parameters +which are fit during the PSF model generation process. + +.nf + z = x ** 2 / p1 ** 2 + y ** 2 / p2 ** 2 + gauss = A * exp (-0.5 * z) + + z = x ** 2 / p1 ** 2 + y ** 2 / p2 ** 2 + x * y * p3 + moffat15 = A / (1 + z) ** 1.5 + moffat25 = A / (1 + z) ** 2.5 + + z = x ** 2 / p1 ** 2 + y ** 2 / p2 ** 2 + x * y * p3 + lorentz = A / (1.0 + z) + + z = x ** 2 / p1 ** 2 + y ** 2 / p2 ** 2 + e = x ** 2 / p1 ** 2 + y ** 2 / p2 ** 2 + x * y * p4 + penny1 = A * ((1 - p3) / (1.0 + z) + p3 * exp (-0.693*e)) + + z = x ** 2 / p1 ** 2 + y ** 2 / p2 ** 2 + p5 * x * y + e = x ** 2 / p1 ** 2 + y ** 2 / p2 ** 2 + x * y * p4 + penny2 = A * ((1 - p3) / (1.0 + z) + p3 * exp (-0.693*e)) +.fi + + +The predicted errors in the DAOPHOT photometry are computed per +pixel as follows, where terms 1, 2, 3, and 4 represent the readout +noise, the poisson noise, the flat-fielding error, and the interpolation +error respectively. The quantities readnoise, epadu, I, M, p1, and p2 +are the readout noise in electrons, the gain in electrons per ADU, +the pixel intensity in ADU, the PSF model intensity in ADU, the FWHM +in x and the FWHM in y, both in pixels. + +.nf + error = sqrt (term1 + term2 + term3 + term4) (ADU) + term1 = (readnoise / epadu) ** 2 + term2 = I / epadu + term3 = (.01 * flaterr * I) ** 2 + term4 = (.01 * proferr * M / p1 / p2) ** 2 +.fi + +The radial weighting function employed by all the PSF fitting tasks is +the following, where dx and dy are the distance of the pixel from the +centroid of the star being fit. + +.nf + wtr = 5.0 / (5.0 + rsq / (1.0 - rsq)) + rsq = (dx ** 2 + dy ** 2) / fitrad ** 2 +.fi + +The weight assigned each pixel in the fit then becomes the following. + +.nf + wtp = wtr / error ** 2 +.fi + +After a few iterations and if clipexp > 0, a clipping scheme to reject bad +data is enabled. The weights of the pixels are recomputed as follows. + +.nf + wt = wtp / (1.0 + (residual / error / chiold / + cliprange) ** clipexp) +.fi + +Pixels having a residual of cliprange sigma will have their weight reduced +by half. + +.ih +EXAMPLES + +1. Print the DAOPARS task parameters. + +.nf + da> lpar daopars +.fi + +2. Edit the DAOPARS parameters. + +.nf + da> daopars +.fi + +3. Edit the DAOPARS parameters from with the PSF task. + +.nf + da> epar psf + + ... edit a few psf parameters + + ... move to the daopars parameter and type :e + + ... edit the daopars parameters and type :wq + + ... finish editing the psf parameters and type :wq +.fi + +4. Save the current DAOPARS parameter set in a text file daonite1.par. + This can also be done from inside a higher level task as in the + above example. + +.nf + da> epar daopars + + ... type ":w daonite1.par" from within epar +.fi + +.ih +TIME REQUIREMENTS +.ih +BUGS +.ih +SEE ALSO +pstselect,psf,peak,group,nstar,allstar,substar,addstar,setimpars +.endhelp diff --git a/noao/digiphot/daophot/doc/daotest.hlp b/noao/digiphot/daophot/doc/daotest.hlp new file mode 100644 index 00000000..e7d455ae --- /dev/null +++ b/noao/digiphot/daophot/doc/daotest.hlp @@ -0,0 +1,89 @@ +.help daotest Dec92 noao.digiphot.daophot +.ih +NAME +daotest -- run basic tests on the daophot package tasks +.ih +USAGE +daotest imname +.ih +PARAMETERS +.ls imname +The root name of the output test images. The input test image is stored in +fits format in the DAOPHOT package test directory. If the image already exists +DAOTEST will exit with a warning message. +.le +.ls daologfile = "" +The name of the output log file. By default all the output image header +listings and photometry file output is logged in a file +called \fI"imname.log"\fR. If the log file already exists DAOTEST will +exit with a warning message. +.le +.ls daoplotfile = "" +The name of the output plot file. By default all the graphics output is +logged in a file called \fI"imname.plot"\fR. If the plot file already exists +DAOTEST will exit with a warning message. +.le +.ih +DESCRIPTION +DAOTEST is a simple script which exercises each of the major tasks in the +DAOPHOT package in turn. At startup DAOTEST reads a small fits image stored +in the DAOPHOT test subdirectory and creates the image \fIimname\fR in +the user's working directory. DAOTEST initializes the DAOPHOT package by +returning +all the parameters to their default state, runs each of the DAOPHOT +tasks in non-interactive mode, spools the text output to the file +\fIdaologfile\fR, the graphics output from the PSF task to the plot +metacode file \fIapplotfile\fR, and the image output from PSF, SUBSTAR +and ADDSTAR to \fIimname.psf.1\fR, \fIimname.sub.1\fR, and \fIimname.add.1\fR +respectively. +.ih +EXAMPLES + +1. Check to see that all the DAOPHOT tasks are functioning correctly. +.nf + da> daophot + + ... load the daophot package + + da> daotest testim + + ... run the test script + + da> lprint testim.log + + ... print the text output + + da> gkidir testim.plot + + ... list the contents of the plot file + + da> gkiextract testim.plot 1-N | stdplot + + ... send the plots to the plotter + + da> display testim 1 + + ... display the original image + + da> surface testim.psf.1 + + ... make a surface plot of the psf look-up table + + da> display testim.sub.1 1 + + ... display the image with all the stars fitted by ALLSTAR + subtracted out + + da> display testim.add.1 1 + + ... display the image containing three additional artificial + stars added by the ADDSTAR routine +.fi + +.ih +TIME REQUIREMENTS +.ih +BUGS +.ih +SEE ALSO +.endhelp diff --git a/noao/digiphot/daophot/doc/datapars.hlp b/noao/digiphot/daophot/doc/datapars.hlp new file mode 100644 index 00000000..3e4345a1 --- /dev/null +++ b/noao/digiphot/daophot/doc/datapars.hlp @@ -0,0 +1,289 @@ +.help datapars May00 noao.digiphot.daophot +.ih +NAME +datapars -- edit the data dependent parameters +.ih +USAGE +datapars +.ih +PARAMETERS +.ls scale = 1.0 +The scale of the image in user units, e.g. arcseconds per pixel. All DAOPHOT +distance dependent parameters are assumed to be in units of scale. If +\fIscale\fR = 1.0 these parameters are assumed to be in units of pixels. Most +DAOPHOT users should leave \fIscale\fR set to 1.0 unless they intend to compare +their aperture photometry results directly with data in the literature. +.le +.ls fwhmpsf = 2.5 (scale units) +The full-width half-maximum of the point spread function in scale units. +The DAOFIND task and the PHOT task "gauss" and "ofilter" centering algorithms +depend on the value of fwhmpsf. DAOPHOT users can either determine a value +for fwhmpsf using an external task such as IMEXAMINE, or make use of the +interactive capabilities of the DAOPHOT tasks to set and store it. +.le +.ls emission = yes +The features to be measured are above sky. By default the DAOPHOT package +considers all features to be emission features. DAOPHOT users should +leave this parameter set to "yes". +.le +.ls sigma = 0.0 +The standard deviation of the sky pixels. The DAOFIND task and the PHOT task +"constant" sky fitting algorithm error estimate depend on the value of sigma. +DAOPHOT users should set sigma to a value representative of the noise in +the sky background. +.le +.ls datamin = INDEF +The minimum good pixel value. Datamin defaults to -MAX_REAL the minimum +floating point number supported by the host computer. Datamin is used +to detect and remove bad data from the sky aperture, detect and flag +bad data in the aperture photometry aperture, and detect and remove bad +data from the PSF fitting aperture. DAOPHOT users should either leave +datamin set to INDEF or set it to a number between 5-7 sigma below the +sky background value. +.le +.ls datamax = INDEF +The maximum good pixel value. Datamax defaults to MAX_REAL the maximum +floating point number supported by the host computer. Datamax is used +to detect and remove bad data from the sky aperture, detect and flag +bad data in the aperture photometry aperture, and detect and remove bad +data from the PSF fitting aperture. DAOPHOT users should either leave +datamax set to INDEF or set it to the linearity or saturation +limit of the detector. +.le +.ls noise = "poisson" +The noise model used to estimate the uncertainties in the computed +magnitudes. DAOPHOT users must leave noise set to "poisson". +.le +.ls ccdread = "" +The image header keyword defining the readout noise parameter whose units +are assumed to be electrons. +.le +.ls gain = "" +The image header keyword defining the gain parameter whose units are assumed to +be electrons per adu. +.le +.ls readnoise = 0.0 +The readout noise of the detector in electrons. DAOPHOT users should set +readnoise or ccdread to its correct value before running any of the DAOPHOT +package tasks in order to ensure that the PSF fitting weights, magnitude +error estimates, and chi values are correct. +.le +.ls epadu = 1.0 +The gain of the detector in electrons per adu. DAOPHOT users should set this +epadu or gain to its correct value before running any of the DAOPHOT package +tasks in order to ensure that the PSF fitting weights, magnitude error +estimates, and chi values are correct. +.le +.ls exposure = "" +The image header exposure time keyword. The time units are arbitrary but +must be consistent for any list of images whose magnitudes are to be compared. +The computed magnitudes are normalized to one timeunit by the PHOT task. +As the magnitude scale of the DAOPHOT package is set by the PHOT task, +setting exposure can save DAOPHOT users a lot of unnecessary zero point +corrections in future analysis and calibration steps. +.le +.ls airmass = "" +The image header airmass keyword. The airmass parameter is not used +directly by DAOPHOT but the airmass value is stored in the output file +and its presence there will simplify future calibration steps. +.le +.ls filter = "" +The image header filter id keyword. The filter parameter is not used +directly by DAOPHOT but the filter id is stored in the output file +and its presence there will simplify future calibration steps. +.le +.ls obstime = "" +The image header time of observation keyword. The obstime parameter is not used +directly by DAOPHOT but the obstime value is stored in the output file +and its presence there will simplify future calibration steps. +.le +.ls itime = 1.0 +The exposure time for the image in arbitrary units. The DAOPHOT magnitudes are +normalized to 1 timeunit by the PHOT task using the value of exposure in the +image header if exposure is defined or the value of itime. +.le +.ls xairmass = INDEF +The airmass value. The airmass is read from the image header if airmass +is defined or from xairmass. The airmass value is stored in the DAOPHOT +output files. +.le +.ls ifilter = "INDEF" +The filter id string. The filter id is read from the image header if filter +is defined otherwise from ifilter. The filter id is stored in the DAOPHOT +output files. +.le +.ls otime = "INDEF" +The value of the time of observation. The time of observation is read from +the image header if obstime is defined otherwise from otime. The time of +observation is stored in the DAOPHOT output files. +.le + +.ih +DESCRIPTION + +\fIDatapars\fR sets the image data dependent parameters. These parameters are +functions, of the instrument optics, the noise characteristics and range of +linearity of the detector, and the observing conditions. Many of the +centering, sky fitting, and photometry algorithm parameters in the CENTERPARS, +FITSKYPARS, PHOTPARS, and DAOPARS parameter sets scale with the data dependent +parameters. + +The parameter \fIscale\fR sets the scale of the apertures used by the +centering, sky fitting, aperture photometry, and psf fitting algorithms. +Scale converts radial distance measurements in pixels to radial distance +measurements in scale units. The DAOPHOT parameters cbox, maxshift, rclean +and rclip in the CENTERPARS parameter set; annulus, dannulus, and rgrow in +FITSKYPARS parameter set; apertures in the PHOTPARS parameter set; and psfrad, +fitrad, sannulus, wsannulus, and matchrad in the DAOPARS parameter set are +expressed in units of the scale. The scale parameter is useful in cases where +the observations are to be compared to published aperture photometry +measurements in the literature. + +The parameter \fIfwhmpsf\fR defines the full-width at half-maximum of the +stellar point spread function. The DAOFIND task, the PHOT task centering +algorithms "gauss" and "ofilt", and the PSF modeling task PSF all require +an accurate estimate for this parameter. + +By setting the \fIscale\fR and \fIfwhmpsf\fR appropriately the aperture +sizes and radial distances may be expressed in terms of the half-width +at half-maximum of the stellar point spread function. The way to do this +is to define the scale parameter in units of the number of half-width at +half-maximum per pixel, set the fwhmpsf parameter to 2.0, and then +set the remaining scale dependent centering, sky fitting, aperture photometry, +and psf fitting algorithm parameters in CENTERPARS, FITSKYPARS, PHOTPARS, +and DAOPARS to appropriate values in units of the half-width at half-maximum +of the point-spread function. Once an optimum set of algorithm parameters is +chosen, the user need only alter the DATAPARS scale parameter before +executing a DAOPHOT task on a new image. + +If \fIemission\fR is "yes", the features to be measured are assumed to +be above sky. By default the DAOPHOT package considers all features to be +emission features. DAOPHOT users should leave this parameter set to "yes". +Although the DAOFIND and PHOT tasks can detect and measure absorption features +the PSF fitting tasks currently cannot. + +The parameter \fIsigma\fR estimates the standard deviation of the sky +background pixels. The star finding algorithm in DAOFIND uses sigma +and the \fIfindpars.threshold\fR parameter to define the stellar +detection threshold in adu. The PHOT task centering algorithms use sigma, +1) with the \fIcenterpars.kclean\fR parameter to define deviant pixels +if \fIcenterpars.clean\fR is enabled; 2) to estimate the signal to +noise ratio in the centering box; 3) and with the \fIcenterpars.cthreshold\fR +parameter to define a lower intensity limit for the pixels to be used +for centering. If sigma is undefined or <= 0.0 1) no cleaning is performed +regardless of the value of centerpars.clean; 2) the background noise in the +centering box is assumed to be 0.0; and 3) default cutoff intensity is used +for centering. + +The \fIdatamin\fR and \fIdatamax\fR parameters define the good data range. +If datamin or datamax are defined bad data is removed from the sky pixel +distribution before the sky is fit, data containing bad pixels in the +photometry apertures is flagged and the corresponding aperture photometry +magnitudes are set to INDEF, and bad data removed from the PSF fitting +aperture. DAOPHOT users should set datamin and datamax to appropriate values +before running the DAOPHOT tasks. + +DAOPHOT users must leave \fInoise\fR set to "poisson". This model includes +Poisson noise from the object and both Poisson and readout noise in the sky +background. + +The parameters \fIgain\fR and \fIepadu\fR define the image gain. +The gain parameter specifies which keyword in the image header contains +the gain value. If gain is undefined or not present in the image header +the value of epadu is used. Epadu must be in units of electrons per adu. +DAOPHOT users should set either gain or epadu to a correct value before +running any of the DAOPHOT package tasks to ensure that the aperture +photometry magnitude error estimates, and the PSF fitting weights, chis, and +magnitude error estimates are computed correctly. + +The two parameters \fIccdread\fR and \fIreadnoise\fR define the image +readout noise. The ccdread parameter specifies which keyword in the +image header contains the readout noise value. If ccdread is undefined or +not present in the image header the value of readnoise is used. +Readnoise is assumed to be in units of electrons. +DAOPHOT users should set either ccdread or readnoise before running any +DAOPHOT tasks to insure that the PSF fitting weights, chis, and magnitude +error estimates are computed correctly. + +The magnitudes computed by PHOT are normalized to an exposure time of 1 +timeunit using the value of the exposure time in the image header parameter +\fIexposure\fR or \fIitime\fR. If exposure is undefined or not present +in the image header a warning message is issued and the value of itime +is used. The itime units are arbitrary but must be consistent for images +analyzed together. As the magnitude scale in DAOPHOT is determined by the +PHOT task setting either exposure or itime can save DAOPHOT users a lot +of unnecessary zero point corrections in future analysis and calibration +steps. + +The parameters \fIairmass\fR and \fIxairmass\fR define the airmass +of the observation. The airmass parameter specifies which keyword in the +image header contains the airmass value. If airmass is undefined or +not present in the image header the value of xairmass is used. +The airmass values are not used in any DAOPHOT computations, however their +presence in the DAOPHOT output files will simplify future reduction steps. + +The parameters \fIfilter\fR and \fIifilter\fR define the filter +of the observation. The filter parameter specifies which keyword in the +image header contains the filter id. If filter is undefined or not present +in the image header the value of ifilter is used. The filter id values are +not used in any DAOPHOT computations, however their presence in the DAOPHOT +output files can will simplify future reduction steps. + +The parameters \fIobstime\fR and \fIotime\fR define the time +of the observation (e.g. UT). The obstime parameter specifies which keyword +in the image header contains the time stamp of the observation. If obstime is +undefined or not present in the image header the value of otime is used. +The time of observations values are not used in any DAOPHOT +computations, however their presence in the DAOPHOT output files can +greatly simplify future reduction steps. + + +.ih +EXAMPLES + +1. List the data dependent parameters. + +.nf + da> lpar datapars +.fi + +2. Edit the data dependent parameters. + +.nf + da> datapars +.fi + +3. Edit the data dependent parameters from within the PSF task. + +.nf + da> epar psf + + ... edit a few parameters + + ... move to the datapars parameter and type :e + + ... edit the datapars parameters and type :wq + + ... finish editing the psf parameter and type :wq +.fi + +4. Save the current DATAPARS parameter set in a text file datnite1.par. +This can also be done from inside a higher level task as in the previous +example. + +.nf + da> epar datapars + + ... edit a few parameters + + ... type ":w datnite1.par" from within epar +.fi +.ih +TIME REQUIREMENTS +.ih +BUGS + +.ih +SEE ALSO +epar,lpar,daofind,phot,pstselect,psf,group,peak,nstar,allstar,substar,addstar +.endhelp diff --git a/noao/digiphot/daophot/doc/findpars.hlp b/noao/digiphot/daophot/doc/findpars.hlp new file mode 100644 index 00000000..1c0bfe1a --- /dev/null +++ b/noao/digiphot/daophot/doc/findpars.hlp @@ -0,0 +1,135 @@ +.help findpars May00 noao.digiphot.daophot +.ih +NAME +findpars -- edit the object detection parameters +.ih +USAGE +findpars +.ih +PARAMETERS +.ls threshold = 4.0 (sigma) +The object detection threshold above local background in units of +\fIdatapars.sigma\fR. +.le +.ls nsigma = 1.5 +The semi-major axis of the Gaussian convolution kernel used to computed the +density enhancement and mean density images in Gaussian sigma. This semi- +major axis is equal to min (2.0, 0.42466 * \fInsigma\fR * +\fIdatapars.fwhmpsf\fR / \fIdatapars.scale\fR) pixels. +.le +.ls ratio = 1.0 +The ratio of the sigma of the Gaussian convolution kernel along the minor axis +direction to the sigma along the major axis direction. \fIRatio\fR defaults +to 1.0 in which case the image is convolved with a circular Gaussian. +.le +.ls theta = 0.0 +The position of the major axis of the elliptical Gaussian. \fITheta\fR is +measured counter-clockwise from the x axis. +.le +.ls sharplo = .2, sharphi = 1.0 +\fISharplo\fR and \fIsharphi\fR are numerical cutoffs on the image sharpness +statistic chosen to eliminate brightness maxima which are due to bad pixels +rather than to astronomical objects. +.le +.ls roundlo = -1.0 roundhi = 1.0 +\fIRoundlo\fR and \fIroundhi\fR are numerical cutoffs on the image roundness +statistic chosen to eliminate brightness maxima which are due to bad rows or +columns rather than to astronomical objects. +.le +.ls mkdetections = no +Mark the positions of the detected objects on the displayed image ? +.le + +.ih +DESCRIPTION + +DAOFIND approximates the stellar point spread function with an elliptical +Gaussian function, whose sigma along the semi-major axis is 0.42466 * +\fIdatapars.fwhmpsf\fR / \fIdatapars.scale\fR pixels, semi-minor to semi-major +axis ratio is \fIratio\fR, and major axis position angle is \fItheta\fR. +Using this model, a convolution kernel, truncated at \fInsigma\fR sigma, +and normalized to sum to zero, is constructed. + +The density enhancement image \fIstarmap\fR is computed by convolving the input +image with the Gaussian kernel. This operation is mathematically equivalent to +fitting, in the least-squares sense, the image data at each point with a +truncated, lowered elliptical Gaussian function. After convolution each point +in \fIstarmap\fR contains as estimate of the amplitude of the best fitting +Gaussian function at that point. Each point in \fIskymap\fR, if the user +chooses to compute it, contains an estimate of the best fitting sky value +at that point. + +After image convolution DAOFIND steps through \fIstarmap\fR searching +for density enhancements greater than \fIfindpars.threshold\fR * +\fIdatapars.sigma\fR, and brighter than all other density enhancements +within a semi-major axis of 0.42466 \fIfindpars.nsigma\fR * +\fIdatapars.fwhmpsf\fR. As the program selects candidates, it computes two +shape characteristics sharpness and roundness. The sharpness statistic +measures the ratio of the difference between the height of the central pixel +and the mean of the surrounding non-bad pixels, to the height of the best +fitting Gaussian function at that point. The roundness statistics measures +the ratio of, the difference in the height of the best fitting Gaussian +function in x minus the best fitting Gaussian function in y, over the average +of the best fitting Gaussian functions in x and y. The limits on these +parameters \fIfindpars.sharplo\fR, \fIfindpars.sharphi\fR, +\fIfindpars.roundlo\fR, and \fIfindpars.roundhi\fR, are set to weed out +non-astronomical objects and brightness enhancements that are elongated in +x and y respectively. + +Lastly the x and y centroids of the detected objects are computed by +estimating the x and y positions of the best fitting 1D Gaussian +functions in x and y respectively, a rough magnitude is estimated +by computing the ratio of the amplitude of the best fitting Gaussian at +the object position to \fIfindpars.threshold\fR * \fIdatapars.sigma\fR, +and the object is added to the output coordinate file. + + +.ih +EXAMPLES + +1. List the object detection parameters. + +.nf + da> lpar findpars +.fi + +2. Edit the object detection parameters. + +.nf + da> findpars +.fi + +3. Edit the FINDPARS parameters from within the DAOFIND task. + +.nf + da> epar daofind + + ... edit a few daofind parameters + + ... move to the findpars parameter and type :e + + ... edit the findpars parameter and type :wq + + ... finish editing the daofind parameters and type :wq +.fi + +4. Save the current FINDPARS parameter set in a text file fndnite1.par. +This can also be done from inside a higher level task as in the previous +example. + +.nf + da> findpars + + ... edit the parameters + + ... type ":w fndnite1.par" from within epar +.fi + +.ih +BUGS +daofind + +.ih +SEE ALSO +epar,lpar,daofind,datapars +.endhelp diff --git a/noao/digiphot/daophot/doc/fitskypars.hlp b/noao/digiphot/daophot/doc/fitskypars.hlp new file mode 100644 index 00000000..6642a551 --- /dev/null +++ b/noao/digiphot/daophot/doc/fitskypars.hlp @@ -0,0 +1,212 @@ +.help fitskypars May00 noao.digiphot.daophot +.ih +NAME +fitskypars - edit the sky fitting algorithm parameters +.ih +USAGE +fitskypars +.ih +PARAMETERS +.ls salgorithm = "mode" +The sky fitting algorithm. The sky fitting options are: +.ls constant +Use a user supplied constant sky value. +This algorithm is useful for measuring large resolved objects on flat +backgrounds such as galaxies or comets. +.le +.ls file +Read sky values from a text file. This option is useful for importing +user determined sky values into DAOPHOT. +.le +.ls mean +Compute the mean of the sky pixel distribution. This algorithm is useful +for computing sky values in regions with few background counts. +.le +.ls median +Compute the median of the sky pixel distribution. This algorithm is a useful +for computing sky values in regions with rapidly varying sky backgrounds +and is a good alternative to "centroid". +.le +.ls mode +Compute the mode of the sky pixel distribution using the mean and median. +This is the recommended algorithm for DAOPHOT users measuring stellar objects in +crowded stellar fields. Mode may not perform well in regions with +rapidly varying sky backgrounds. +.le +.ls centroid +Compute the intensity weighted mean of the sky pixel histogram. This algorithm +is reasonably robust in regions with rapidly varying or crowded sky backgrounds +and is a good alternative to "median". +.le +.ls gauss +Fit a Gaussian function to the sky pixel histogram using non-linear least- +squares techniques to determine the peak. +.le +.ls ofilter +Optimally filter the sky pixel histogram using a triangular weighting +function to determine the peak. +.le +.ls crosscor +Compute the peak of the cross-correlation function of the pixel distribution +and a Gaussian noise function to determine the peak. +.le +.ls histplot +Mark the peak of the sky pixel histogram with the graphics cursor. +This algorithm is useful for making careful interactive sky measurements +for a small number of objects in complicated regions or for checking the +behavior of other sky algorithms. +.le +.ls radplot +Mark the sky level on a radial profile plot with the graphics cursor. +This algorithm is useful for making careful interactive sky measurements +for a small number of objects in complicated regions or for checking the +behavior of other sky algorithms. +.le +.le +.ls annulus = 10.0 (scale units) +The inner radius of the annular sky fitting region in units of the DATAPARS +scale parameter. +.le +.ls dannulus = 10.0 (scale units) +The width of the annular sky fitting region in units of the DATAPARS scale +parameter. +.le +.ls skyvalue = 0.0 +The constant for constant sky subtraction. +.le +.ls smaxiter = 10 +The maximum number of iterations performed by the sky fitting algorithm. +Smaxiter is required by the "gauss" and "ofilter" sky fitting algorithms. +.le +.ls sloclip = 0.0, shiclip = 0.0 (percent) +The high and low side clipping parameters in percent of the total number +of pixels. If either of these parameters > 0.0 then the specified +percentage of the pixels will be removed from the sky pixel distribution +before any sky fitting is done. +.le +.ls snreject = 50 +The maximum number of sky pixel rejection cycles. +.le +.ls sloreject = 3.0, shireject = 3.0 +The k-sigma clipping factors for the pixel rejection phase of the +sky fitting algorithm. Sloreject and shireject are in units of the +computed sky sigma. +.le +.ls khist = 3.0 +The k-sigma clipping factor for computing the sky pixels histogram. Khist is in +units of sigma of the local sky pixel distribution. The histogram will be +2.0 * khist * sigma wide. Khist is used by the "centroid", "gauss", +"crosscor", "ofilter", and "histplot" sky fitting algorithms. +.le +.ls binsize = 0.10 +The width of a single bin of the sky pixel histogram. Binsize is in units of +the sigma of the local sky pixel distribution. Binsize is used by the +"centroid", "gauss", "crosscor", "ofilter", and "histplot" sky fitting +algorithms. +.le +.ls smooth = no +Boxcar smooth the sky pixel histogram before computing a sky value. +Smooth is used by the "centroid", "gauss", "crosscor", "ofilter", and +"histplot" sky fitting algorithms. +.le +.ls rgrow = 0.0 (scale units) +The region growing radius for pixel rejection in the sky region in units +of the DATAPARS scale parameter. When a bad sky_pixel is detected, all pixels +within rgrow / scale pixels of the bad pixel will be rejected. If rgrow is +0.0 region growing is disabled. +.le +.ls mksky = no +Mark the sky annuli on the displayed image ? +.le +.ih +DESCRIPTION +The sky fitting algorithm parameters control the action of the sky fitting +algorithms. The default parameter settings should give reasonable results in +the majority of cases. Several of the sky fitting parameters scale with +image scale, \fIscale\fR which is data dependent. +\fIScale\fR is defined in the DATAPARS parameter set. + +Sky pixels in an annular region of inner radius \fIannulus / scale\fR pixels +and a width of \fIdannulus / scale\fR pixels are extracted from the IRAF image. +If the \fIscale\fR parameter is defined in terms of the number of half-width +at half-maximum of the point spread function per pixel, then single values of +annulus and dannulus will work well for images with different seeing and +detector characteristics. + +Pixels outside of the good data range specified by \fIdatamin\fR and +\fIdatamax\fR are rejected from the sky pixel distribution. After bad +data rejection \fIPloclip\fR and \fIphiclip\fR percent pixels are rejected +from the low and high sides of the sorted pixel distribution before any +sky fitting is done. + +Sky values are computed using the sky fitting algorithm specified by +\fIsalgorithm\fR. The default value is "centroid". If \fIsalgorithm\fR += "mean", "median" or "mode", the sky value is computed directly from the +array of sky pixels. The remaining sky fitting algorithms use the histogram +of the object sky pixels. The computed histogram is \fIkhist\fR * sigma wide +with a bin width of \fIbinsize\fR * sigma where sigma is the computed +standard deviation of the sky pixels for each object. If \fIsmooth\fR = yes, +boxcar smoothing is performed on the computed histogram before sky fitting. +The mode of the histogram is computed using, a non-linear least squares +fit to a Gaussian (salgorithm = "gauss"), optimal filtering of the histogram +(salgorithm = "ofilter"), computing the centroid of the histogram +(salgorithm = "centroid"), or by cross-correlation techniques +(salgorithm = "crosscor"). + +Two interactive methods of fitting sky are also available. If \fIsalgorithm\fR +is "radplot" or "histplot", the user must interactively set +the value of the sky using a radial profile or a histogram plot. + +Pixels which deviate from the sky value by more than \fIkreject times the +computed sky sigma are rejected from the fit. If \fIrgrow\fR > 0, pixels +within a radius of rgrow / scale of the rejected pixel are also rejected from +the fit. The rejection procedure iterates until no further pixels are rejected, +all pixels are rejected, or the maximum number of rejection cycles +\fIsnreject\fR iterations is reached. + +.ih +EXAMPLES + +1. List the sky fitting parameters. + +.nf + da> lpar fitskypars +.fi + +2. Edit the sky fitting parameters. + +.nf + da> fitskypars +.fi + +3. Edit the FITSKYPARS parameters from with the PHOT task. + +.nf + da> epar phot + + ... edit a few phot parameters + + ... move to the fitskypars parameter and type :e + + ... edit the fitskypars parameters and type :wq + + ... finish editing the phot parameters and type :wq +.fi + +4. Save the current FITSKYPARS parameter set in a text file skynite1.par. +This can also be done from inside a higher level task as in the +above example. + +.nf + da> epar fitskypars + + ... type ":w skynite1.par" from within epar +.fi +.ih +TIME REQUIREMENTS +.ih +BUGS +.ih +SEE ALSO +epar,lpar,datapars,phot +.endhelp diff --git a/noao/digiphot/daophot/doc/group.hlp b/noao/digiphot/daophot/doc/group.hlp new file mode 100644 index 00000000..a8cc35d5 --- /dev/null +++ b/noao/digiphot/daophot/doc/group.hlp @@ -0,0 +1,304 @@ +.help group May00 noao.digiphot.daophot +.ih +NAME +group -- group stars in a photometry file +.ih +USAGE +group image photfile psfimage groupfile +.ih +PARAMETERS +.ls image +The list of images containing the stars to be grouped. +.le +.ls photfile +The list of input photometry files containing initial estimates of the +positions and magnitudes of the stars to be fit. The number of photometry +files must be equal to the number of input images. If photfile is "default", +"dir$default", or a directory specification PSF searches for a file called +dir$image.mag.# where # is the highest available version number for the file. +Photfile is normally the output of the PHOT task but may also be the output of +the PSF, PEAK, NSTAR and ALLSTAR tasks. Photfile may be an APPHOT/DAOPHOT +text database or an STSDAS binary table. +.le +.ls psfimage +The list of images containing the PSF models computed by the DAOPHOT PSF task. +The number of PSF images must be equal to the number of input images. If +psfimage is "default", "dir$default", or a directory specification, +then PEAK will look for an image with the name image.psf.?, where +? is the highest existing version number. +.le +.ls groupfile = +The list of output grouped photometry files. There must be one output group +photometry file for every input image. If groupfile is "default", +"dir$default", or a directory specification then GROUP writes a file called +image.grp.? where ? is the next available version number. If the DAOPHOT +package parameter \fItext\fR is "yes" then an APPHOT/DAOPHOT text database is +written, otherwise an STSDAS table is written. +.le +.ls datapars = "" +The name of the file containing the data dependent parameters. The parameters +\fIscale\fR, \fIdatamin\fR, and \fIdatamax\fR are located here. If datapars +is undefined then the default parameter set in uparm directory is used. +.le +.ls daopars = "" +The name of the file containing the daophot fitting parameters. The parameters +\fIpsfrad\fR and \fIfitrad\fR are located here. If \fIdaopars\fR is undefined +then the default parameter set in uparm directory is used. +.le +.ls wcsin = ")_.wcsin", wcsout = ")_.wcsout", wcspsf = ")_.wcspsf" +The coordinate system of the input coordinates read from \fIphotfile\fR, of the +psf model \fIpsfimage\fR, and of the output coordinates written to +\fIgroupfile\fR. The image header coordinate system is used to transform from +the input coordinate system to the "logical" system used internally, from the +internal logical system to the PSF model system, and from the internal +"logical" pixel coordinate system to the output coordinate system. The input +coordinate system options are "logical", "tv", "physical", and "world". The PSF +model and output coordinate system options are "logical", "tv", and "physical". +The image cursor coordinate system is assumed to be the "tv" system. +.ls logical +Logical coordinates are pixel coordinates relative to the current image. +The logical coordinate system is the coordinate system used by the image +input/output routines to access the image data on disk. In the logical +coordinate system the coordinates of the first pixel of a 2D image, e.g. +dev$ypix and a 2D image section, e.g. dev$ypix[200:300,200:300] are +always (1,1). +.le +.ls tv +Tv coordinates are the pixel coordinates used by the display servers. Tv +coordinates include the effects of any input image section, but do not +include the effects of previous linear transformations. If the input +image name does not include an image section, then tv coordinates are +identical to logical coordinates. If the input image name does include a +section, and the input image has not been linearly transformed or copied from +a parent image, tv coordinates are identical to physical coordinates. +In the tv coordinate system the coordinates of the first pixel of a +2D image, e.g. dev$ypix and a 2D image section, e.g. dev$ypix[200:300,200:300] +are (1,1) and (200,200) respectively. +.le +.ls physical +Physical coordinates are pixel coordinates invariant with respect to linear +transformations of the physical image data. For example, if the current image +was created by extracting a section of another image, the physical +coordinates of an object in the current image will be equal to the physical +coordinates of the same object in the parent image, although the logical +coordinates will be different. In the physical coordinate system the +coordinates of the first pixel of a 2D image, e.g. dev$ypix and a 2D +image section, e.g. dev$ypix[200:300,200:300] are (1,1) and (200,200) +respectively. +.le +.ls world +World coordinates are image coordinates in any units which are invariant +with respect to linear transformations of the physical image data. For +example, the ra and dec of an object will always be the same no matter +how the image is linearly transformed. The units of input world coordinates +must be the same as those expected by the image header wcs, e. g. +degrees and degrees for celestial coordinate systems. +.le +The wcsin, wcspsf, and wcsout parameters default to the values of the package +parameters of the same name. The default values of the package parameters +wcsin, wcspsf, and wcsout are "logical", "physical" and "logical" respectively. +.le +.ls cache = ")_.cache" +Cache the image pixels in memory. Cache may be set to the value of the apphot +package parameter (the default), "yes", or "no". By default caching is +disabled. +.le +.ls verify = ")_.verify" +Verify the critical GROUP task parameters? Verify can be set to the DAOPHOT +package parameter value (the default), "yes", or "no". +.le +.ls update = ")_.update" +Update the GROUP task parameters if \fIverify\fR is "yes"? Update can be +set to the default daophot package parameter value, "yes", or "no". +.le +.ls verbose = ")_.verbose" +Print messages about the progress of the task ? Verbose can be set to the +DAOPHOT package parameter value (the default), "yes", or "no". +.le +.ih +DESCRIPTION +GROUP takes the photometry file \fIphotfile\fR file containing the stellar +coordinates and photometry and associates the stars into natural groups based +upon proximity and the magnitude level at which they overlap. The results are +written into \fIgroupfile\fR. If the DAOPHOT package parameter \fItext\fR is +"yes" then \fIgroupfile\fR is a text database, otherwise it is an STSDAS table. + +The coordinates read from \fIphotfile\fR are assumed to be in coordinate +system defined by \fIwcsin\fR. The options are "logical", "tv", "physical", +and "world" and the transformation from the input coordinate system to the +internal "logical" system is defined by the image coordinate system. The +simplest default is the "logical" pixel system. Users working on with image +sections but importing pixel coordinate lists generated from the parent image +must use the "tv" or "physical" input coordinate systems. + +The coordinate system of the PSF model is the coordinate system defined by the +\fIwcspsf\fR parameter. Normally the PSF model was derived from the input image +and this parameter default to "logical". However if the PSF model was derived +from a larger image which is a "parent" of the input image, then wcspsf should +be set to "tv" or "physical" depending on the circumstances. + +The coordinates written to \fIgroupfile\fR are in the coordinate system +defined by \fIwcsout\fR. The options are "logical", "tv", and "physical". The +simplest default is the "logical" system. Users wishing to correlate the +output coordinates of objects measured in image sections or mosaic pieces +with coordinates in the parent image must use the "tv" or "physical" +coordinate systems. + +If \fIcache\fR is yes and the host machine physical memory and working set size +are large enough, the input image pixels are cached in memory. If caching +is enabled and the first data access will appear to take a long time as the +entire image must be read in before the measurement is actually made. All +subsequent data requests will be very fast because GROUP is accessing memory +not disk. The point of caching is to speed up random image access by making +the internal image i/o buffers the same size as the image itself. There is +no point in turning caching on unless a lot of the input magnitudes are INDEF. +In that case GROUP must access the image to estimate a magnitude. Also at +present there is no point in enabling caching for images that are less than +or equal to 524288 bytes, i.e. the size of the test image dev$ypix, as the +default image i/o buffer is exactly that size. However if the size of dev$ypix +is doubled by converting it to a real image with the chpixtype task then the +effect of caching in interactive is can be quite noticeable if measurements +of objects in the top and bottom halves of the image are alternated. + + +The algorithm works in the following manner. If two stars are within a +distance R pixels of one another, where R = \fIpsfrad\fR / \fIscale\fR + +\fIfitrad\fR / \fIscale\fR + 1, the PSF of the brighter one is evaluated at +a distance d pixels, where d = \fIfitrad\fR / \fIscale\fR + 1 away from the +fainter. If this value is larger than \fIcritsnratio\fR times the expected +noise per pixel then the two stars are put into the same group since the +brighter star is capable of affecting the photometry of the fainter. +\fIPsfrad\fR, \fIfitrad\fR and \fIcritsnratio\fR are the psf radius, the +fitting radius, and the critical S/N ratio respectively and are located +in the DAOPARS task. \fIScale\fR is the image scale parameter and is located +in the DATAPARS task. In order for this algorithm to work correctly it is +imperative that the DATAPARS readnoise and gain parameters \fIreadnoise\fR +and \fIgain\fR be set correctly as these values are used to compute the +expected random noise per pixel. + +The correct value of \fIcritsnratio\fR must be determined by trial and error. +For example if a critical S/N ratio of 0.1 divides all the stars in the image +into groups smaller than the \fImaxgroup\fR parameter in the DAOPARS task, then +unavoidable random errors will dominate over crowding errors. If a critical +S/N ratio of 1.0 works, then crowding errors will be no worse than the random +errors. If a critical S/N ratio much greater than 1 is required then in most +cases crowding will be the dominant source or error. + +If \fIverbose\fR is set to "yes", GROUP will write a table on the terminal +showing the number of groups as a function of group size. If any group is +larger than \fImaxgroup\fR then \fIcritnsratio\fR must be increased or +the GRPSELECT task used to cut large groups out of the file. When crowding +conditions vary across the frame, GROUP and GRPSELECT can be used together +to get the best possible photometry for stars in different crowding regimes. + +If any stars in \fIphotfile\fR have INDEF magnitudes, GROUP will attempt +to estimate a magnitude for them based on the weighted sum of the pixels +of a radial weighting function and the value of the PSF at that point. + + +.ih +EXAMPLES + +1. Group the PHOT task output results for the test image dev$ypix using +a critical S/N ratio of 1 and printing the output summary on the terminal. +Good stars for making the PSF model can be found at (442,410), (348,189), +and (379,67). + +.nf + da> datapars.epadu = 14.0 + da> datapars.readnoise = 75.0 + + ... set the gain and readout noise for the detector + + da> daofind dev$ypix default fwhmpsf=2.5 sigma=5.0 threshold=20.0 + + ... answer verify prompts + + ... find stars in the image + + ... answer will appear in ypix.coo.1 + + da> phot dev$ypix default default annulus=10. dannulus=5. \ + apertures = 3.0 + + ... answer verify prompts + + ... do aperture photometry on the detected stars + + ... answer will appear in ypix.mag.1 + + da> display dev$ypix 1 + + da> psf dev$ypix default "" default default default psfrad=11.0 \ + fitrad=3.0 mkstars=yes display=imdr + + ... verify the critical parameters + + ... move the image cursor to a candidate star and hit the a key, + a plot of the stellar data appears + + ... type ? for a listing of the graphics cursor menu + + ... type a to accept the star, d to reject it + + ... move to the next candidate stars and repeat the previous + steps + + ... type l to list all the psf stars + + ... type f to fit the psf + + ... move cursor to first psf star and type s to see residuals, + repeat for all the psf stars + + ... type w to save the PSF model + + ... type q to quit, and q again to confirm + + ... the output will appear in ypix.psf.1.imh, ypix.pst.1 and + ypix.psg.1 + + + da> group dev$ypix default default default crit=1.0 verbose+ + + ... verify the critical parameters + + ... answers will appear in ypix.grp.1 + +.fi + + +2. Run group on a section of the input image using the photometry file and PSF +model derived in example 1 for the parent image and writing the results +in the coordinate system of the parent image. Note that the results for +example 2 are identical to those in example 1. + +.nf + da> group dev$ypix[150:450,150:450] default default default \ + wcsin=tv wcspsf=tv wcsout=tv + + ... answer the verify prompts + + ... fit the stars + + ... the results will appear in ypix.grp.2 + + da> display dev$ypix[150:450,150:450] 1 + + ... display the image + + da> pdump ypix.grp.2 xc,yc yes | tvmark 1 STDIN col=204 + + ... mark the stars + +.fi + + +.ih +TIME REQUIREMENTS +.ih +BUGS +.ih +SEE ALSO +psf,grpselect,nstar +.endhelp diff --git a/noao/digiphot/daophot/doc/grpselect.hlp b/noao/digiphot/daophot/doc/grpselect.hlp new file mode 100644 index 00000000..f2381fb7 --- /dev/null +++ b/noao/digiphot/daophot/doc/grpselect.hlp @@ -0,0 +1,73 @@ +.help grpselect May00 noao.digiphot.daophot +.ih +NAME +grpselect -- select groups from a group file by group size +.ih +USAGE +grpselect ingroupfile outgroupfile min_group max_group +.ih +PARAMETERS +.ls ingroupfile +The list of input group files. Ingroupfile must have been written by the +DAOPHOT PSF, GROUP, or NSTAR tasks. Ingroupfile may be an APPHOT/DAOPHOT text +database or an STSDAS table. +.le +.ls outgroupfile +The list of output group files. There must be one output group file for every +input group file. Outgroupfile has the same file type as \fIingroupfile\fR. +.le +.ls min_group +The minimum group size to select from the input group file(s). +.le +.ls max_group +The maximum group size to select from the input group file(s). +.le +.ls verbose = ")_.verbose" +Print messages about the progress of the task? Verbose may be set to the value +of the daophot package parameter (the default), "yes", or "no". +.le +.ih +DESCRIPTION +GRPSELECT creates a new GROUP file \fIoutgroupfile\fR by selecting groups from +the input GROUP file \fIingroupfile\fR within a range of group sizes specified +by \fImin_group\fR and \fImax_group\fR. If \fIingroupfile\fR is a DAOPHOT text +database, \fIoutgroupfile\fR is a text database. Conversely if \fIingroupfile\fR +is a DAOPHOT STSDAS table database, \fIoutgroupfile\fR is an STSDAS table +database. + +A typical use for GRPSELECT is to create a new database containing only groups +which are less than the value of the \fImaxgroup\fR parameter in the DAOPARS +task for direct input into the NSTAR task. The remaining stars in the larger +groups are reduced by running GRPSELECT once more, selecting only groups +greater than \fImaxgroup\fR, rerunning GROUP on the output with a less +stringent value of the DAOPARS parameter task \fIcritovlap\fR to reduce the +group sizes and inputting the result into NSTAR. + +.ih +EXAMPLES + +1. Select groups with between 1 and 70 stars from the GROUP task output file +ypix.grp.1 and write them into a new file named ypixsmall.grp. + +.nf + da> grpselect ypix.grp.1 ypixsmall.grp 1 70 + +.fi + +2. Select groups larger than 70 from the same input group file and rerun +group with a new value of the critoverlap parameter on the results. + +.nf + da> grpselect ypix.grp.1 ypixlarge.grp 71 400 + da> group dev$ypix ypixlarge.grp ypix.psf.1 default crit=5.0 + +.fi + +.ih +TIME REQUIREMENTS +.ih +BUGS +.ih +SEE ALSO +group +.endhelp diff --git a/noao/digiphot/daophot/doc/nstar.hlp b/noao/digiphot/daophot/doc/nstar.hlp new file mode 100644 index 00000000..cf7c9936 --- /dev/null +++ b/noao/digiphot/daophot/doc/nstar.hlp @@ -0,0 +1,501 @@ +.help nstar May00 noao.digiphot.daophot +.ih +NAME +nstar -- fit the PSF to groups of stars simultaneously +.ih +USAGE +nstar image groupfile psfimage nstarfile rejfile +.ih +PARAMETERS +.ls image +The list of images containing the stellar groups to be fit. +.le +.ls groupfile +The list of input group photometry files containing the group membership +information and initial estimates for the positions and magnitudes of the stars +to be measured. There must be one group file for every input image. If +groupfile is "default", "dir$default", or a directory specification then NSTAR +will look for a file with the name image.grp.? where ? is the highest existing +version number. Groupfile is usually the output of the DAOPHOT GROUP task, but +may also be the output of the NSTAR and PSF tasks. Groupfile may be an +APPHOT/DAOPHOT text database or an STSDAS binary table. +.le +.ls psfimage +The list of images containing the PSF models computed by the DAOPHOT PSF task. +The number of PSF images must be equal to the number of input images. If +psfimage is "default", "dir$default", or a directory specification, +then PEAK will look for an image with the name image.psf.?, where +? is the highest existing version number. +.le +.ls nstarfile +The list of output photometry files. There must be one output photometry +file for every input image. If nstarfile is "default", "dir$default", or a +directory specification, then NSTAR will write an output file with the name +image.nst.? where ? is the next available version number. Nstarfile is a text +database if the DAOPHOT package parameter text is "yes", an STSDAS table +database if it is "no". +.le +.ls rejfile +The list of output rejected photometry files containing the positions and sky +values of stars that could not be fit. If rejfile is undefined, results for all +the stars in photfile are written to \fInstarfile\fR, otherwise only the stars +which were successfully fit are written to \fInstarfile\fR and the remainder are +written to rejfile. If rejfile is "default", "dir$default", or a directory +specification NSTAR writes an output file with the name image.nst.? where ? is +the next available version number. Otherwise rejfile must specify one output +photometry file for every input image. Rejfile is a text database if the +DAOPHOT package parameter \fItext\fR is "yes", an STSDAS binary table database +if it is "no". +.le +.ls datapars = "" +The name of the file containing the data dependent parameters. The parameters +\fIscale\fR, \fIdatamin\fR, and \fIdatamax\fR are located here. If datapars +is undefined then the default parameter set in uparm directory is used. +.le +.ls daopars = "" +The name of the file containing the daophot fitting parameters. The parameters +\fIpsfrad\fR and \fIfitrad\fR are located here. If \fIdaopars\fR is undefined +then the default parameter set in uparm directory is used. +.le +.ls wcsin = ")_.wcsin", wcsout = ")_.wcsout", wcspsf = ")_.wcspsf" +The coordinate system of the input coordinates read from \fIgroupfile\fR, of the +psf model \fIpsfimage\fR, and of the output coordinates written to +\fInstarfile\fR and \fIrejfile\fR respectively. The image header coordinate +system is used to transform from the input coordinate system to the "logical" +pixel coordinate system used internally, from the internal logical system to +the PSF model system, and from the internal "logical" pixel coordinate system +to the output coordinate system. The input coordinate system options are +"logical", "tv", "physical", and "world". The PSF model and output coordinate +system options are "logical", "tv", and "physical". The image cursor coordinate +system is assumed to be the "tv" system. +.ls logical +Logical coordinates are pixel coordinates relative to the current image. +The logical coordinate system is the coordinate system used by the image +input/output routines to access the image data on disk. In the logical +coordinate system the coordinates of the first pixel of a 2D image, e.g. +dev$ypix and a 2D image section, e.g. dev$ypix[200:300,200:300] are +always (1,1). +.le +.ls tv +Tv coordinates are the pixel coordinates used by the display servers. Tv +coordinates include the effects of any input image section, but do not +include the effects of previous linear transformations. If the input +image name does not include an image section, then tv coordinates are +identical to logical coordinates. If the input image name does include a +section, and the input image has not been linearly transformed or copied from +a parent image, tv coordinates are identical to physical coordinates. +In the tv coordinate system the coordinates of the first pixel of a +2D image, e.g. dev$ypix and a 2D image section, e.g. dev$ypix[200:300,200:300] +are (1,1) and (200,200) respectively. +.le +.ls physical +Physical coordinates are pixel coordinates invariant with respect to linear +transformations of the physical image data. For example, if the current image +was created by extracting a section of another image, the physical +coordinates of an object in the current image will be equal to the physical +coordinates of the same object in the parent image, although the logical +coordinates will be different. In the physical coordinate system the +coordinates of the first pixel of a 2D image, e.g. dev$ypix and a 2D +image section, e.g. dev$ypix[200:300,200:300] are (1,1) and (200,200) +respectively. +.le +.ls world +World coordinates are image coordinates in any units which are invariant +with respect to linear transformations of the physical image data. For +example, the ra and dec of an object will always be the same no matter +how the image is linearly transformed. The units of input world coordinates +must be the same as those expected by the image header wcs, e. g. +degrees and degrees for celestial coordinate systems. +.le +The wcsin, wcspsf, and wcsout parameters default to the values of the package +parameters of the same name. The default values of the package parameters +wcsin, wcspsf, and wcsout are "logical", "physical" and "logical" respectively. +.le +.ls cache = ")_.cache" +Cache the image pixels in memory. Cache may be set to the value of the apphot +package parameter (the default), "yes", or "no". By default caching is +disabled. +.le +.ls verify = ")_.verify" +Verify the critical NSTAR task parameters? Verify can be set to the DAOPHOT +package parameter value (the default), "yes", or "no". +.le +.ls update = ")_.update" +Update the NSTAR task parameters if \fIverify\fR is "yes"? Update can be +set to the default daophot package parameter value, "yes", or "no". +.le +.ls verbose = ")_.verbose" +Print messages about the progress of the task ? Verbose can be set to the +DAOPHOT package parameter value (the default), "yes", or "no". +.le +.ih +DESCRIPTION +NSTAR computes x and y centers and magnitudes for all the stellar groups in +\fIgroupfile\fR by fitting the PSF \fIpsfimage\fR to the data in \fIimage\fR. +NSTAR reads the group membership information along with initial estimates of +the centers and magnitudes, and the sky values from the photometry file +\fIgroupfile\fR. \fIGroupfile\fR is usually the output of the DAOPHOT GROUP +task but may also be the output of the PSF and NSTAR tasks. The computed +centers and magnitudes are written to \fInstarfile\fR along with the sky +values, the number of iterations it took to fit the star, the goodness of fit +statistic chi and the image sharpness statistic sharp. If \fIrejfile\fR is +undefined, only stars that are successfully fit are written to \fInstarfile\fR, +and the remainder are written to \fIrejfile\fR. Otherwise all the stars are +written to \fInstarfile\fR. \fINstarfile\fR and \fIrejfile\fR are text +databases if the DAOPHOT package parameter \fItext\fR is "yes", an STSDAS table +database if it is "no". + +The coordinates read from \fIgroupfile\fR are assumed to be in coordinate +system defined by \fIwcsin\fR. The options are "logical", "tv", "physical", +and "world" and the transformation from the input coordinate system to the +internal "logical" system is defined by the image coordinate system. The +simplest default is the "logical" pixel system. Users working on with image +sections but importing pixel coordinate lists generated from the parent image +must use the "tv" or "physical" input coordinate systems. + +The coordinate system of the PSF model is the coordinate system defined by the +\fIwcspsf\fR parameter. Normally the PSF model was derived from the input image +and this parameter default to "logical". However if the PSF model was derived +from a larger image which is a "parent" of the input image, then wcspsf should +be set to "tv" or "physical" depending on the circumstances. + +The coordinates written to \fInstarfile\fR and \fIrejfile\fR are in the +coordinate system defined by \fIwcsout\fR with the exception of the psf model +center coordinates PSFX and PSFY which are always in the logical system of +the input image. The options are "logical", "tv", and "physical". The simplest +default is the "logical" system. Users wishing to correlate the output +coordinates of objects measured in image sections or mosaic pieces with +coordinates in the parent image must use the "tv" or "physical" coordinate +systems. + +If \fIcache\fR is yes and the host machine physical memory and working set size +are large enough, the input image pixels are cached in memory. If caching +is enabled and NSTAR is run interactively the first measurement will appear +to take a long time as the entire image must be read in before the measurement +is actually made. All subsequent measurements will be very fast because NSTAR +is accessing memory not disk. The point of caching is to speed up random +image access by making the internal image i/o buffers the same size as the +image itself. However if the input object lists are sorted close to row order +and sparse caching may actually worsen not improve the execution time. Also at +present there is no point in enabling caching for images that are less than +or equal to 524288 bytes, i.e. the size of the test image dev$ypix, as the +default image i/o buffer is exactly that size. However if the size of dev$ypix +is doubled by converting it to a real image with the chpixtype task then the +effect of caching in interactive is can be quite noticeable if measurements +of objects in the top and bottom halves of the image are alternated. + +By default NSTAR computes new centers for all the stars in \fIgroupfile\fR. +However if the DAOPARS parameter \fIrecenter\fR is "no", NSTAR assumes that the +x and y centers in \fIgroupfile\fR are the true centers and does not refit +them. This option can be quite useful in cases where accurate center values +have been derived from an image that has been through some non-linear image +restoration algorithm, but the photometry must be derived from the original +unrestored image. + +By default NSTAR computes the sky value for each group by averaging the +individual sky values in \fIgroupfile\fR for all the stars in the group. If +\fIgroupsky\fR is "no" then the sky value for a particular pixel which +contributes to the group fit is set to the mean of the sky values of only those +stars for which the pixel is within one fitting radius. However if the DAOPARS +parameter \fIfitksy\fR is "yes", then NSTAR computes a new group sky value as +part of the non-linear least-squares fit. Recomputing the sky can significantly +reduce the scatter in the magnitudes in regions where the sky background is +varying rapidly, but users may need to increase \fIfitrad\fR to include more +sky pixels in the fit. Users should experiment cautiously with this option. + +Only pixels within the good data range delimited by the DATAPARS task +parameters \fIdatamin\fR and \fIdatamax\fR are included in the fit. Most users +set \fIdatamin\fR and \fIdatamax\fR so as to exclude pixels outside the +linearity regime of the detector. By default all the data is fit. Users are +advised to determine accurate values for these parameters and set the +appropriate parameters in DATAPARS before beginning any DAOPHOT reductions. + +Only pixels within the fitting radius \fIfitrad\fR / \fIscale\fR are included +in the fit for each star. \fIFitrad\fR is located in the DAOPARS task and +\fIscale\fR is located in the DATAPARS task. Since the non-linear least-squares +fitting algorithm determines three unknowns, the x and y position of the star's + centroid and its brightness, the value of \fIfitrad\fR must be sufficiently +large to include at least three pixels in the fit for each star. To accelerate +the convergence of the non-linear least-squares fitting algorithm pixels within +\fIfitrad\fR are assigned weights which are inversely proportional to the +radial distance of the pixel from the x and y centroid of the star, falling +from a maximum at the centroid to zero at the fitting radius. \fIFitrad\fR must + be sufficiently large to include at least three pixels with non-zero weights +in the fit for each star. Values of \fIfitrad\fR close to the full-width at +half-maxima of the PSF are recommended. In actual fact NSTAR imposes a minimum +number of pixel limit of four. + +NSTAR performs a weighted fit to the PSF. The weight of each pixel is computed +by combining, the radial weighting function described above, with weights +derived from the random errors NSTAR predicts based on the values of the +DATAPARS parameters \fIreadnoise\fR and \fIepadu\fR, and the flat-fielding and +profile interpolation errors specified by the DAOPARS \fIflaterr\fR and +\fIproferr\fR parameters. To obtain optimal fits, users are strongly advised +to determine those parameters accurately and to enter their values in DATAPARS +and DAOPARS before beginning any DAOPHOT reductions. + +For each group of stars to be fit, NSTAR extracts a subraster from \fIimage\fR +which extends approximately \fIpsfrad\fR / \fIscale\fR + 1 pixels wide past +the limiting values of the x and y coordinates of the stars in the group. +\fIPsfrad\fR is the PSF radius specified in the DAOPARS task, and \fIscale\fR +is the image scale specified by the DATAPARS task. \fIPsfrad\fR may be less +than or equal to but can never exceed the value of the image header parameter +"PSFRAD" in \fIpsfimage\fR. \fIPsfrad\fR should always be several pixels larger +than \fIfitrad\fR to permit the x and y centroids to wander during the fitting +process. + +As well as the computed x and y centers and magnitudes, NSTAR outputs the number + of times the PSF fit had to be iterated before reaching convergence. The +minimum number of iterations is four. The maximum number of iteration permitted +is specified by the \fImaxiter\fR parameter in the DAOPARS task. Obviously the +results for stars which have reached the maximum iteration count should be +viewed with suspicion. However since the convergence criteria are quite strict, +(the computed magnitude must change by less than .0005 magnitudes or 0.10 +sigma whichever is larger, and the x and y centroids must change by less than +0.002 pixels from one iteration to the next), even these stars may be +reasonably well measured. It must be emphasized that every star in the group +must individually satisfy the convergence criteria in order for the group to be + considered adequately reduced. + +NSTAR computes a goodness of fit statistic chi which is essentially the ratio +of the observed pixel-to-pixel scatter in the fitting residuals to the expected +scatter. Since the expected scatter is dependent on the DATAPARS task parameters +\fIreadnoise\fR and \fIepadu\fR, and the DAOPARS parameters \fIflaterr\fR and +\fIproferr\fR it is important for these values to be set correctly. A plot of +chi versus magnitude should scatter around unity with little or no trend in +chi with magnitude, except at the bright end where saturation effects may be +present. + +Finally NSTAR computes the statistic sharp which estimates the intrinsic angular +size of the measured object outside the atmosphere. Sharp is roughly defined as +the difference between the square of the width of the object and the square of +the width of PSF. Sharp has values close to zero for single stars, large +positive values for blended doubles and partially resolved galaxies and large +negative values for cosmic rays and blemishes. + +NSTAR implements a highly sophisticated star rejection algorithm. First of all, + any group of stars which is more than a certain size is simply not fit. The +maximum group size is specified by the \fImaxgroup\fR parameter in the DAOPARS +task. Larger groups may run into numerical precision problems during the fits. +Users should exercise care in increasing the \fImaxgroup\fR parameter. If two +stars in a group have centroids separated by a critical distance, currently set +arbitrarily to 0.37 * the FWHM of the stellar core, their photocentric position +and combined magnitude is assigned to the brighter of the two stars, and the +fainter is eliminated. Any star which converges to 12.5 magnitudes greater than + the magnitude of the PSF is considered to be non-existent and eliminated from +the group. + +After iteration 5, if the faintest star in the group has a brightness less than + one sigma above zero, it is eliminated. After iterations 10, if the faintest +star in the group has a brightness less than 1.5 sigma above zero, it is +eliminated. After iterations 15 to 50 or whenever the solutions has converged +whichever comes first, if the faintest star in the group has a brightness less +than 2.0 sigma above zero, it is eliminated. After iterations 5, 10 and 15, +if two stars are separated by more than 0.37 * FWHM and less than 1.0 * FWHM +and if the fainter of the two is more uncertain than 1.0, 1.5 or 2.0 sigma +respectively the fainter one is eliminated. + +Whenever a star is eliminated the iteration counter is backed up by one and +reduction proceeds with a smaller set of stars. Backing up the counter gives +the second least certain star in the group two iterations to settle into a new +fit before its fate is decided. The star rejection algorithm depends upon the +DATAPARS \fIreadnoise\fR and \fIgain\fR parameters and the DAOPARS parameter +\fIflaterr\fR and \fIproferr\fR. Therefore these parameters should be set to +reasonable values before running NSTAR. + +NSTAR operates in a very similar manner to PEAK. However because it fits groups + of stars simultaneously it is much more accurate than PEAK in crowded regions. +The ALLSTAR task also fits groups of stars simultaneously, both grouping the +stars dynamically as well as producing a subtracted image. Essentially it +replaces GROUP, GRPSELECT, NSTAR and SUBSTAR. However the user has little +control over the grouping process and does not know at the end which stars were +actually fit together. NSTAR is the task of choice when a user wants to +maintain rigorous control over the composition of the stellar groups. + +.ih +OUTPUT + +If \fIverbose\fR = yes, a single line is output to the terminal for each star +fit or rejected. Full output is written to \fInstarfile\fR and \fIrejfile\fR. +At the beginning of these two files a header listing the current values of the +parameters is written. For each star fit/rejected the following quantities are +written to the output file. + +.nf + id group xcenter ycenter mag merr msky niter sharpness + chi pier perr +.fi + +Id is the id number of the star and group is its group number. Xcenter and +ycenter are the fitted coordinates in pixels. Mag and merr are the fitted +magnitude and magnitude error respectively. Msky is the individual sky value +for the star. Niter is the number of iterations it took to fit the star and +sharpness and chi are the sharpness and goodness of fit statistic respectively. +Pier and perror are the photometry error code and accompanying error message +respectively. + +.ih +ERRORS + +If no errors occur during the fitting process then pier is 0. Non-zero +values of pier flag the following error conditions. + +.nf + 0 # No error + 1 # The star is in a group too large to fit + 2 # The sky is undefined + 3 # There are too few good pixels to fit the star + 4 # The fit is singular + 5 # The star is too faint + 6 # The star has merged with a brighter star + 7 # The star is off the image +.fi + +.ih +EXAMPLES + +1. Fit the PSF to a list stars in the test image dev$ypix. Good stars for +making the PSF model can be found at (442,410), (348,189), and (379,67). + +.nf + da> datapars.epadu = 14.0 + da> datapars.readnoise = 75.0 + + ... set the gain and readout noise for the detector + + da> daofind dev$ypix default fwhmpsf=2.5 sigma=5.0 threshold=20.0 + + ... answer verify prompts + + ... find stars in the image + + ... answer will appear in ypix.coo.1 + + da> phot dev$ypix default default annulus=10. dannulus=5. \ + apertures = 3.0 + + ... answer verify prompts + + ... do aperture photometry on the detected stars + + ... answer will appear in ypix.mag.1 + + da> display dev$ypix 1 + + da> psf dev$ypix default "" default default default psfrad=11.0 \ + fitrad=3.0 mkstars=yes display=imdr + + ... verify the critical parameters + + ... move the image cursor to a candidate star and hit the a key, + a plot of the stellar data appears + + ... type ? for a listing of the graphics cursor menu + + ... type a to accept the star, d to reject it + + ... move to the next candidate stars and repeat the previous + steps + + ... type l to list all the psf stars + + ... type f to fit the psf + + ... move cursor to first psf star and type s to see residuals, + repeat for all the psf stars + + ... type w to save the PSF model + + ... type q to quit, and q again to confirm + + ... the output will appear in ypix.psf.1.imh, ypix.pst.1 and + ypix.psg.1 + + da> group dev$ypix default default default + + ... verify the prompts + + ... the output will appear in ypix.grp.1 + + da> nstar dev$ypix default default default default + + ... verify the prompts + + ... the results will appear in ypix.nst.1 and ypix.nrj.1 + + da> pdump ypix.nst.1 sharpness,chi yes | graph + + ... plot chi versus sharpness, the stars should cluster around + sharpness = 0.0 and chi = 1.0, note that the frame does + not have a lot of stars + + da> substar dev$ypix default "" default default + + ... subtract the fitted stars + + da> display ypix.sub.1 2 + + ... note that the psf stars subtract reasonably well but other + objects which are not stars don't +.fi + + +2. Run nstar on a section of the input image using the group file and PSF +model derived in example 1 for the parent image and writing the results +in the coordinate system of the parent image. + +.nf + da> nstar dev$ypix[150:450,150:450] default default default default \ + wcsin=tv wcspsf=tv wcsout=tv + + ... answer the verify prompts + + ... fit the stars + + ... the results will appear in ypix.nst.2 and ypix.nrj.2 + + da> display dev$ypix[150:450,150:450] 1 + + ... display the image + + da> pdump ypix.nst.2 xc,yc yes | tvmark 1 STDIN col=204 + + ... mark the stars + + da> substar dev$ypix ypix.nst.2 "" default default + + ... subtract stars from parent image + + ... the output images is ypix.sub.2 + + + da> substar dev$ypix[150:450,150:450] ypix.nst.2 "" default default \ + wcsin=tv wcspsf=tv wcsout=tv + + ... subtract stars from the nstar input image + + ... the output images is ypix.sub.3 + +.fi + + + +3. Run nstar exactly as in example 1 but submit the task to the background. +Turn off verify and verbose. + +.nf + da> nstar dev$ypix default default default default verbose- \ + verify- & + + ... the results will appear in ypix.nst.3 and ypix.nrj.3 +.fi + + +.ih +TIME REQUIREMENTS +.ih +BUGS +.ih +SEE ALSO +datapars,daopars,peak,allstar +.endhelp diff --git a/noao/digiphot/daophot/doc/peak.hlp b/noao/digiphot/daophot/doc/peak.hlp new file mode 100644 index 00000000..9017dcb2 --- /dev/null +++ b/noao/digiphot/daophot/doc/peak.hlp @@ -0,0 +1,439 @@ +.help peak May00 noao.digiphot.daophot +.ih +NAME +peak -- fit the PSF model to single stars +.ih +USAGE +peak image photfile psfimage peakfile rejfile +.ih +PARAMETERS +.ls image +The list of images containing the stars to be fit. +.le +.ls photfile +The list of input photometry files containing initial estimates of the +positions and magnitudes of the stars to be fit. The number of photometry +files must be equal to the number of input images. If photfile is "default", +"dir$default", or a directory specification PSF searches for a file called +dir$image.mag.# where # is the highest available version number for the file. +Photfile is usually the output of the DAOPHOT PHOT task, but may also be the + output of PEAK itself, or of the DAOPHOT package GROUP, NSTAR, ALLSTAR or +PSF tasks. Photfile may be an APPHOT/DAOPHOT text database or an STSDAS table. +.le +.ls psfimage +The list of images containing the PSF models computed by the DAOPHOT PSF task. +The number of PSF images must be equal to the number of input images. If +psfimage is "default", "dir$default", or a directory specification, +then PEAK will look for an image with the name image.psf.?, where +? is the highest existing version number. +.le +.ls peakfile +The list of output photometry files. There must be one output photometry +file for every input image. If peakfile is "default", "dir$default", or a +directory specification, then PEAK will write an output file with the name +image.pk.? where ? is the next available version number. Peakfile is a text +database if the DAOPHOT package parameter text is "yes", an STSDAS table +database if it is "no". +.le +.ls rejfile +The list of output rejected photometry files containing the positions and sky +values of stars that could not be fit. If rejfile is undefined, results for all +the stars in photfile are written to \fIpeakfile\fR, otherwise only the stars +which were successfully fit are written to \fIpeakfile\fR and the remainder are +written to rejfile. If rejfile is "default", "dir$default", or a directory +specification PEAK writes an output file with the name image.prj.? where ? is +the next available version number. Otherwise rejfile must specify one output +photometry file for every input image. Rejfile is a text database if the +DAOPHOT package parameter \fItext\fR is "yes", an STSDAS binary table database +if it is "no". +.le +.ls datapars = "" +The name of the file containing the data dependent parameters. The parameters +\fIscale\fR, \fIdatamin\fR, and \fIdatamax\fR are located here. If datapars +is undefined then the default parameter set in uparm directory is used. +.le +.ls daopars = "" +The name of the file containing the daophot fitting parameters. The parameters +\fIpsfrad\fR and \fIfitrad\fR are located here. If \fIdaopars\fR is undefined +then the default parameter set in uparm directory is used. +.le +.ls wcsin = ")_.wcsin", wcsout = ")_.wcsout", wcspsf = ")_.wcspsf" +The coordinate system of the input coordinates read from \fIphotfile\fR, of the +psf model \fIpsfimage\fR, and of the output coordinates written to +\fIpeakfile\fR and \fIrejfile\fR respectively. The image header coordinate +system is used to transform from the input coordinate system to the "logical" +pixel coordinate system used internally, from the internal logical system to +the PSF model system, and from the internal "logical" pixel coordinate system +to the output coordinate system. The input coordinate system options are +"logical", "tv", "physical", and "world". The PSF model and output coordinate +system options are "logical", "tv", and "physical". The image cursor coordinate +system is assumed to be the "tv" system. +.ls logical +Logical coordinates are pixel coordinates relative to the current image. +The logical coordinate system is the coordinate system used by the image +input/output routines to access the image data on disk. In the logical +coordinate system the coordinates of the first pixel of a 2D image, e.g. +dev$ypix and a 2D image section, e.g. dev$ypix[200:300,200:300] are +always (1,1). +.le +.ls tv +Tv coordinates are the pixel coordinates used by the display servers. Tv +coordinates include the effects of any input image section, but do not +include the effects of previous linear transformations. If the input +image name does not include an image section, then tv coordinates are +identical to logical coordinates. If the input image name does include a +section, and the input image has not been linearly transformed or copied from +a parent image, tv coordinates are identical to physical coordinates. +In the tv coordinate system the coordinates of the first pixel of a +2D image, e.g. dev$ypix and a 2D image section, e.g. dev$ypix[200:300,200:300] +are (1,1) and (200,200) respectively. +.le +.ls physical +Physical coordinates are pixel coordinates invariant with respect to linear +transformations of the physical image data. For example, if the current image +was created by extracting a section of another image, the physical +coordinates of an object in the current image will be equal to the physical +coordinates of the same object in the parent image, although the logical +coordinates will be different. In the physical coordinate system the +coordinates of the first pixel of a 2D image, e.g. dev$ypix and a 2D +image section, e.g. dev$ypix[200:300,200:300] are (1,1) and (200,200) +respectively. +.le +.ls world +World coordinates are image coordinates in any units which are invariant +with respect to linear transformations of the physical image data. For +example, the ra and dec of an object will always be the same no matter +how the image is linearly transformed. The units of input world coordinates +must be the same as those expected by the image header wcs, e. g. +degrees and degrees for celestial coordinate systems. +.le +The wcsin, wcspsf, and wcsout parameters default to the values of the package +parameters of the same name. The default values of the package parameters +wcsin, wcspsf, and wcsout are "logical", "physical" and "logical" respectively. +.le +.ls cache = ")_.cache" +Cache the image pixels in memory. Cache may be set to the value of the apphot +package parameter (the default), "yes", or "no". By default caching is +disabled. +.le +.ls verify = ")_.verify" +Verify the critical PEAK task parameters? Verify can be set to the DAOPHOT +package parameter value (the default), "yes", or "no". +.le +.ls update = ")_.update" +Update the PEAK task parameters if \fIverify\fR is "yes"? Update can be +set to the default daophot package parameter value, "yes", or "no". +.le +.ls verbose = ")_.verbose" +Print messages about the progress of the task ? Verbose can be set to the +DAOPHOT package parameter value (the default), "yes", or "no". +.le +.ih +DESCRIPTION +PEAK computes x and y centers, sky values and magnitudes for all the stars in +\fIphotfile\fR by fitting the PSF model in \fIpsfimage\fR to single stars in +\fIimage\fR. PEAK reads initial estimates of the centers and magnitudes along +with the sky values from the photometry file \fIphotfile\fR. \fIPhotfile\fR is +usually the output of the DAOPHOT PHOT task but may also be the output of PEAK +itself, NSTAR, ALLSTAR, GROUP or PSF. The computed centers, sky values, and +magnitudes are written to \fIpeakfile\fR along with the number of iterations +it took to fit the star, the goodness of fit statistic chi, and the image +sharpness statistic sharp. If \fIrejfile\fR is defined only stars that are +successfully fit are written to \fIpeakfile\fR. The remainder are written to +\fIrejfile\fR. Otherwise all the stars are written to \fIpeakfile\fR. +\fIPeakfile\fR and \fIrejfile\fR are APPHOT/DAOPHOT text databases if the +DAOPHOT package parameter \fItext\fR is "yes", STSDAS binary table databases +if it is "no". + +The coordinates read from \fIphotfile\fR are assumed to be in coordinate +system defined by \fIwcsin\fR. The options are "logical", "tv", "physical", +and "world" and the transformation from the input coordinate system to the +internal "logical" system is defined by the image coordinate system. The +simplest default is the "logical" pixel system. Users working on with image +sections but importing pixel coordinate lists generated from the parent image +must use the "tv" or "physical" input coordinate systems. + +The coordinate system of the PSF model is the coordinate system defined by the +\fIwcspsf\fR parameter. Normally the PSF model was derived from the input image +and this parameter default to "logical". However if the PSF model was derived +from a larger image which is a "parent" of the input image, then wcspsf should +be set to "tv" or "physical" depending on the circumstances. + +The coordinates written to \fIpeakfile\fR and \fIrejfile\fR are in the +coordinate system defined by \fIwcsout\fR. The options are "logical", "tv", +and "physical". The simplest default is the "logical" system. Users wishing to +correlate the output coordinates of objects measured in image sections or +mosaic pieces with coordinates in the parent image must use the "tv" or +"physical" coordinate systems. + +If \fIcache\fR is yes and the host machine physical memory and working set size +are large enough, the input image pixels are cached in memory. If caching +is enabled and the first measurement will appear to take a long time as the +entire image must be read in before the measurement is actually made. All +subsequent measurements will be very fast because PEAK is accessing memory not +disk. The point of caching is to speed up random image access by making the +internal image i/o buffers the same size as the image itself. However if the +input object lists are sorted in row order and sparse caching may actually +worsen not improve the execution time. Also at present there is no point in +enabling caching for images that are less than or equal to 524288 bytes, i.e. +the size of the test image dev$ypix, as the default image i/o buffer is exactly +that size. However if the size of dev$ypix is doubled by converting it to a +real image with the chpixtype task then the effect of caching in interactive +is can be quite noticeable if measurements of objects in the top and bottom +halves of the image are alternated. + +By default PEAK computes new centers for all the stars in \fIphotfile\fR. +However if the DAOPARS parameter \fIrecenter\fR is "no", PEAK assumes that the +x and y centers in \fIphotfile\fR are the true centers and does not refit them. +This option can be quite useful in cases where accurate center values have been +derived from an image that has been through some non-linear image restoration +algorithm, but the photometry must be derived from the original unrestored +image. + +By default PEAK uses the sky value in \fIphotfile\fR. However if the DAOPARS +parameter \fIfitsky\fR is "yes", then PEAK computes a new sky value as part of +the non-linear least-squares fit. Recomputing the sky can significantly reduce +the scatter in the magnitudes in regions where the sky background is varying +rapidly, but users may need to increase the \fIfitrad\fR parameter to include +more sky pixels in the fit. Users should experiment cautiously with this option. + +Only pixels within the good data range delimited by the DATAPARS task parameters +\fIdatamin\fR and \fIdatamax\fR are included in the fit. Most users set +\fIdatamin\fR and \fIdatamax\fR to exclude pixels outside the linearity +regime of the detector. By default all the data is fit. Users are advised to +determine the values of these parameters for their detector and set the values +in DATAPARS before beginning DAOPHOT reductions. + +Only pixels within the fitting radius set by the DAOPARS task parameter +\fIfitrad\fR divided by the DATAPARS parameter \fIscale\fR are included in the +fit. Since the non-linear least-squares fits determine three unknowns, the x +and y position of the star's centroid and its brightness, the value of +\fIfitrad\fR must be sufficiently large to include at least three pixels in +the fit. To accelerate the convergence of the non-linear least-squares fitting +algorithm, pixels within \fIfitrad\fR are assigned weights which are inversely +proportional to the radial distance of the pixel from the x and y centroid of +the star, falling from a maximum at the centroid to zero at the fitting radius. +\fIFitrad\fR must be sufficiently large to include at least three pixels with +non-zero weights in the fit. Values of \fIfitrad\fR close to the full-width at +half-maxima of the PSF are recommended. + +PEAK performs a weighted fit to the PSF. The weight of each pixel is computed +by combining the radial weighting function described above with weights derived +from the expected random errors computed using the values of the DATAPARS +parameters \fIreadnoise\fR and \fIepadu\fR specified by the user. Both to +obtain optimal fits, and because PEAK employs a conservative formula, dependent +on \fIreadnoise\fR and \fIepadu\fR, for reducing the weights of deviant pixels +which do not approach the model as the fit proceeds, users are strongly +advised to determine the values of these parameters accurately, and to enter +these values in DATAPARS before beginning any DAOPHOT reductions. + +For each star to be fit, PEAK extracts a subraster from \fIimage\fR which is N +by N pixels square where N is approximately 2 * \fIpsfrad\fR / \fIscale\fR + 1 +pixels wide. \fIPsfrad\fR is the PSF radius specified in the DAOPARS task and +\fIscale\fR is the scale factor specified in the DATAPARS task. \fIPsfrad\fR may +be less than or equal to, but can never exceed the value of the image header +parameter "PSFRAD" in \fIpsfimage\fR. \fIPsfrad\fR should be set to a value +several pixels larger than \fIfitrad\fR in order to permit the x and y +centroids to wander during the fitting process. + +Along with the computed x and y centers and magnitudes, PEAK outputs the number +of times the PSF fit had to be iterated to reach convergence for each star. The +minimum number of iterations is three. The maximum number of iteration permitted +is specified by the \fImaxiter\fR parameter in the DAOPARS task. Obviously the +results for stars which have reached the maximum iteration count should be +viewed with suspicion. However since the convergence criteria are quite strict, +(the computed magnitude must change by less than .001 magnitudes or 0.05 sigma +whichever is larger and the x and y centroids must change by less than 0.01 +pixels from one iteration to the next), even these stars may be reasonably well +measured. + +PEAK computes a goodness of fit statistic chi which is essentially the ratio of +the observed pixel-to-pixel scatter in the fit residuals to the expected +scatter. Since the expected scatter is dependent on the DATAPARS task parameters +\fIreadnoise\fR and \fIepadu\fR, it is important for these values to be set +correctly. A plot of chi versus magnitude should scatter around unity with +little or no trend in chi with magnitude, except at the bright end where +saturation effects may be present. + +Finally PEAK computes the statistic sharp which estimates the intrinsic angular +size of the measured object outside the atmosphere. Sharp is roughly defined as +the difference between the square of the width of the object and the square of +the width of PSF. Sharp has values close to zero for single stars, large +positive values for blended doubles and partially resolved galaxies, and large +negative values for cosmic rays and blemishes. + +Because PEAK cannot fit stars in crowded fields with overlapped images like the +NSTAR and ALLSTAR tasks do, and for sparsely populated frames aperture +photometry produced by PHOT is often just as good and faster to compute, PEAK +has few unique functions. PEAK is often useful however for fitting and removing +single stars in images where the stars are interfering with the real object of +interest such as a galaxy. In that case the PEAK results can be input to SUBSTAR +which will then remove the interfering stars. Another potential use of PEAK +is the removal of stars from sparsely populated sky flats in preparation +for smoothing. + +.ih +OUTPUT + +If \fIverbose\fR = yes, a single line is output to the terminal for each star +fit or rejected. Full output is written to \fIallstarfile\fR and \fIrejfile\fR. +At the beginning of these two files a header listing the current values of the +parameters is written. For each star fit/rejected the following quantities are +written to the output file. + +.nf + id xcenter ycenter mag merr msky niter sharpness chi + pier perr +.fi + +Id is the id number of the star. Xcenter and ycenter are the fitted coordinates +in pixels. Mag and merr are the fitted magnitude and magnitude error +respectively. Msky is the individual sky value for the star. Niter is the +number of iterations it took to fit the star and sharpness and chi are the +sharpness and goodness of fit statistic respectively. Pier and perror are the +photometry error code and accompanying error message respectively. + +.ih +ERRORS + +If no errors occur during the fitting process then pier is 0. Non-zero +values of pier flag the following error conditions. + +.nf + 0 # No error + 1 # The sky is undefined + 2 # There are too few good pixels to fit the star + 3 # The fit is singular + 4 # The star is too faint +.fi + +.ih +EXAMPLES + + +1. Compute the PSF model for the test image dev$ypix. Good stars for making the +PSF model can be found at (442,410), (348,189), and (379,67). + + +.nf + da> datapars.epadu = 14.0 + da> datapars.readnoise = 75.0 + + ... set the gain and readout noise for the detector + + da> daofind dev$ypix default fwhmpsf=2.5 sigma=5.0 threshold=20.0 + + ... answer verify prompts + + ... find stars in the image + + ... answer will appear in ypix.coo.1 + + da> phot dev$ypix default default annulus=10. dannulus=5. \ + apertures = 3.0 + + ... answer verify prompts + + ... do aperture photometry on the detected stars + + ... answer will appear in ypix.mag.1 + + da> display dev$ypix 1 + + da> psf dev$ypix default "" default default default psfrad=11.0 \ + fitrad=3.0 mkstars=yes display=imdr + + ... verify the critical parameters + + ... move the image cursor to a candidate star and hit the a key, + a plot of the stellar data appears + + ... type ? for a listing of the graphics cursor menu + + ... type a to accept the star, d to reject it + + ... move to the next candidate stars and repeat the previous + steps + + ... type l to list all the psf stars + + ... type f to fit the psf + + ... move cursor to first psf star and type s to see residuals, + repeat for all the psf stars + + ... type w to save the PSF model + + ... type q to quit, and q again to confirm + + ... the output will appear in ypix.psf.1.imh, ypix.pst.1 and + ypix.psg.1 + + da> peak dev$ypix default default default default + + ... the results will appear in ypix.pk.1 and ypix.prj.1 + + da> pdump ypix.pk.1 sharpness,chi yes | graph + + ... plot chi versus sharpness, the stars should cluster around + sharpness = 0.0 and chi = 1.0, note that the frame does + not have a lot of stars + + da> substar dev$ypix ypix.pk.1 "" default default + + ... subtract the fitted stars + + da> display ypix.sub.1 2 + + ... note that the psf stars subtract reasonably well but other + objects which are not stars don't +.fi + + +2. Run peak on a section of the input image using the photometry file and PSF +model derived in example 1 for the parent image and writing the results +in the coordinate system of the parent image. + +.nf + da> peak dev$ypix[150:450,150:450] default default default default \ + wcsin=tv wcspsf=tv wcsout=tv + + ... answer the verify prompts + + ... fit the stars + + ... the results will appear in ypix.pk.2 and ypix.prj.2 + + da> display dev$ypix[150:450,150:450] 1 + + ... display the image + + da> pdump ypix.pk.2 xc,yc yes | tvmark 1 STDIN col=204 + + ... mark the stars + + da> substar dev$ypix ypix.pk.2 "" default default + + ... subtract stars from parent image + + ... the output images is ypix.sub.2 + + + da> substar dev$ypix[150:450,150:450] ypix.pk.2 "" default default \ + wcsin=tv wcspsf=tv wcsout=tv + + ... subtract stars from the peak input image + + ... the output images is ypix.sub.3 + +.fi + +.ih +TIME REQUIREMENTS + +.ih +BUGS +.ih +SEE ALSO +datapars,daopars,nstar,allstar +.endhelp diff --git a/noao/digiphot/daophot/doc/pexamine.hlp b/noao/digiphot/daophot/doc/pexamine.hlp new file mode 100644 index 00000000..920634bc --- /dev/null +++ b/noao/digiphot/daophot/doc/pexamine.hlp @@ -0,0 +1,780 @@ +.help pexamine May00 noao.digiphot.daophot +.ih +NAME +pexamine -- interactively examine or edit a photometry catalog +.ih +USAGE +pexamine input output image +.ih +PARAMETERS +.ls input +The name of the input photometry catalog. Input may be either an APPHOT/DAOPHOT +text database file or an STSDAS binary table database. +.le +.ls output +The name of the edited output catalog. Output is either an APPHOT/DAOPHOT text +database or an STSDAS binary table database depending on the file type of +\fIinput\fR. If output = "" no output catalog is written. +.le +.ls image +The name of the input image corresponding to the input photometry catalog. If +\fIimage\fR is "" no image will be attached to PEXAMINE and some interactive +catalog examining commands will not be available. All the catalog editing +commands however are still available. +.le +.ls deletions = "" +The name of an optional output deletions photometry catalog. Deletions is either +an APPHOT/DAOPHOT text database or an STSDAS binary table database depending on +the file type of \fIinput\fR. If deletions is "" no deletions file is written. +.le +.ls photcolumns = "daophot" +The list of standard photometry columns that are loaded when pexamine is run. +The options are listed below. +.ls "daophot" +The standard columns for the DAOPHOT package. The current list is GROUP, ID, +XCENTER, YCENTER, MSKY, MAG, MERR, CHI, SHARP and NITER. If any of these columns +are multi-valued, (as in the case of magnitudes measured through more than one +aperture), the first value is selected. The standard list may easily be +extended at user request. +.le +.ls "apphot" +The standard columns for the APPHOT package. The current list is ID, XCENTER, +YCENTER, MSKY, MAG, and MERR. If any of these columns are multi-valued, (as in +the case of magnitudes measured through more than one aperture), the first +value is selected. The standard list may easily be extended at user request. +.le +.ls user list +A user supplied list of standard columns. Column names are listed in full in +either upper or lower case letters, separated by commas. If more than one value +of a multi-valued column is requested the individual values must be listed +separately as in the following example ID, XCENTER, YCENTER, MAG[1], MERR[1], +MAG[2], MERR[2]. +.le +Photcolumns can be changed interactively from within PEXAMINE at the cost +of rereading the database. +.le +.ls xcolumn = "mag" (magnitude), ycolumn = "merr" (magnitude error) +The names of the two columns which define the default X-Y plot. Xcolumn and +ycolumn must be listed in \fIphotcolumns\fR or \fIusercolumns\fR but may be +changed interactively by the user. If either xcolumn or ycolumn is a +multi-valued quantity and more than one value is listed in \fIphotcolumns\fR +or \fIusercolumns\fR then the desired value number must be specified explicitly +in, e.g. MAG[2] or MERR[2]. +.le +.ls hcolumn = "mag" (magnitude) +The name of the column which defines the default histogram plot. Hcolumn +must be listed in \fIphotcolumns\fR or \fIusercolumns\fR but may be changed +interactively by the user. If hcolumn is a multi-valued quantity and more than +one value is listed in \fIphotcolumns\fR or \fIusercolumns\fR then the desired +value must be specified explicitly in hcolumn, e.g. MAG[2]. +.le +.ls xposcolumn = "xcenter", yposcolumn = "ycenter" +The names of the two columns which define the X and Y coordinates in \fIimage\fR +of the objects in the catalog. This information is required if the image +display and image cursor are to be used to visually identify objects in the +image with objects in the catalog or if plots of image data are requested. +Xposcolumn and yposcolumn must be listed in \fIphotcolumns\fR or +\fIusercolumns\fR but may be changed interactively by the user. +.le +.ls usercolumns = "" +The list of columns loaded into memory in addition to the standard photometry +columns \fIphotcolumns\fR. The column names are listed in full in upper or +lower case letters and separated by commas. Usercolumns can be changed +interactively from within PEXAMINE at the cost of rereading the database. +.le +.ls first_star = 1 +The index of the first object to be read out of the catalog. +.le +.ls max_nstars = 5000 +The maximum number of objects that are loaded into memory at task startup time, +beginning at object \fIfirst_star\fR. If there are more than max_nstars in the +catalog only the first max_nstars objects are read in. +.le +.ls match_radius = 2.0 +The tolerance in pixels to be used for matching objects in the catalog with +objects marked on the display with the image cursor. +.le +.ls use_display = yes +Use the image display? Users without access to an image display should set +use_display to "no". +.le +.ls icommands = "" +The image display cursor. If null the standard image cursor is used whenever +image cursor input is requested. A cursor file in the appropriate format may be +substituted by specifying the name of the file. Also the image cursor may be +changed to query the graphics device or the terminal by setting the environment +variable "stdimcur" to "stdgraph" or "text" respectively. +.ls gcommands = "" +The graphics cursor. If null the standard graphics cursor is used whenever +graphics cursor input is requested. A cursor file in the appropriate format may +be substituted by specifying the name of the file. +.le +.ls graphics = "stdgraph" +The default graphics device. +.le + +.ih +PLOTTING PARAMETERS + +PEXAMINE supports five types of plots 1) an X-Y column plot 2) a histogram +column plot 3) a radial profile plot 4) a surface plot and 5) a contour plot. +Each supported plot type has its own parameter set which controls the +appearance of the plot. The names of the five parameter sets are listed below. + +.nf + cntrplot Parameters for the contour plot + histplot Parameters for the column histogram plot + radplot Parameters for radial profile plot + surfplot Parameters for surface plot + xyplot Parameters for the X-Y column plot +.fi + +The same parameters dealing with graph formats occur in many of the parameter +sets while some are specific only to one parameter set. In the summary below +those common to more than one parameter set are shown only once. The characters +in parenthesis are the graph key prefixes for the parameter sets in which the +parameter occurs. + +.ls angh = -33., angv = 25. (s) +Horizontal and vertical viewing angles in degrees for surface plots. +.le +.ls axes = yes (s) +Draw axes along the edge of surface plots ? +.le +.ls banner = yes (chrsx) +Add a standard banner to a graph ? The standard banner includes the IRAF user +and host identification and the date and time. +.le +.ls box = yes (chrx) +Draw graph box and axes ? +.le +.ls ceiling = INDEF (cs) +Ceiling data value for contour and surface plots. A value of INDEF does not +apply a ceiling. In contour plots a value of 0. also does not apply a ceiling. +.le +.ls dashpat = 528 (c) +Dash pattern for negative contours. +.le +.ls fill = no (yes) (c) (hrx) +Fill the output viewport regardless of the device aspect ratio ? +.le +.ls floor = INDEF (cs) +Floor data value for contour and surface plots. A value of INDEF does not apply +a floor. In contour plots a value of 0. also does not apply a floor. +.le +.ls grid = no (rx) +Draw grid lines at major tick marks ? +.le +.ls interval = 0.0 (c) +Contour interval. If 0.0, a contour interval is chosen which places 20 to 30 +contours spanning the intensity range of the image. +.le +.ls label= no (c) +Label the major contours in the contour plot ? +.le +.ls logx = no, logy = no (rx) (hrx) +Plot the x or y axis logarithmically ? The default for histogram plots is to +plot the y axis logarithmically. +.le +.ls majrx=5, minrx=5, majry=5, minry=5 (chrx) +Maximum number of major tick marks on each axis and number of minor tick marks +between major tick marks. +.le +.ls marker = "box" (rx) +Marker to be drawn. Markers are "point", "box", "cross", "plus", "circle", +"hline", "vline" or "diamond". +.le +.ls nbins = 512 (h) +The number of bins in, or resolution of, histogram plots. +.le +.ls ncolumns = 21, nlines = 21 (cs) +Number of columns and lines used in contour and surface plots. +.le +.ls ncontours = 5 (c) +Number of contours to be drawn. If 0, the contour interval may be specified, +otherwise 20 to 30 nicely spaced contours are drawn. A maximum of 40 contours +can be drawn. +.le +.ls nhi = -1 (c) +If -1, highs and lows are not marked. If 0, highs and lows are marked on the +plot. If 1, the intensity of each pixel is marked on the plot. +.le +.ls rinner = 0, router = 8 +The inner and outer radius of the region whose radial profile is to be plotted. +.le +.ls round = no (chrx) +Extend the axes up to "nice" values ? +.le +.ls szmarker = 1 (rx) +Size of mark except for points. A positive size less than 1 specifies a fraction +of the device size. Values of 1, 2, 3, and 4 signify default sizes of increasing +size. +.le +.ls ticklabels = yes (chrx) +Label the tick marks ? +.le +.ls top_closed = no (h) +Include z2 in the top histogram bin ? Each bin of the histogram is a subinterval +that is half open at the top. Top_closed decides whether those pixels with +values equal to z2 are to be counted in the histogram. If top_closed is yes, +the top bin will be larger than the other bins. +.le +.ls x1 = INDEF, x2 = INDEF, y1 = INDEF, y2 = INDEF (hrx) +Range of graph along each axis. If INDEF the range is determined from the data +range. The default y1 for histogram plots is 0. +.le +.ls zero = 0. (c) +Grayscale value of the zero contour, i.e., the value of a zero point shift +to be applied to the image data before plotting. Does not affect the values +of the floor and ceiling parameters. +.le +.ls z1 = INDEF, z2 = INDEF (h) +Range of pixel values to be used in histogram. INDEF values default to the +range in the region being histogramed. +.le + +.ih +DESCRIPTION + +PEXAMINE is a general purpose tool for interactively examining and editing +photometry catalogs produced by the APPHOT or DAOPHOT packages. It is intended +to aid the user in assessing the accuracy of the photometry, in diagnosing +problems with particular catalog objects, in searching the photometry data for +relationships between the computed quantities, and in editing the catalog +based on those observed relationships. PEXAMINE is intended to complement the +more batch oriented editing facilities of the PSELECT task. + +PEXAMINE takes the input catalog \fIinput\fR and the corresponding image +\fIimage\fR (if defined) and produces an output catalog of selected objects +\fIoutput\fR (if defined) and an output catalog of deleted objects +\fIdeletions\fR (if defined). The input catalog may be either an APPHOT/DAOPHOT +text database or an ST binary table database. The file type of the output +catalogs \fIoutput\fR and \fIdeletions\fR is the same as that of \fIinput\fR. + +READING IN THE DATA + +PEXAMINE reads the column data specified by \fIphotcolumns\fR and +\fIusercolumns\fR for up to \fImax_nstars\fR into memory. If there are more +than \fImax_nstars\fR in the input catalog only the data for the first +\fImax_nstars\fR is read. The \fIphotcolumns\fR parameter defines the list of +standard photometry columns to be loaded. If "daophot" or "apphot" is selected +then the standard columns are GROUP, ID, XCENTER, YCENTER, MSKY, MAG, MERR, +CHI, SHARP and NITER and ID, XCENTER, YCENTER, MSKY, MAG and MERR respectively. +Otherwise the user must set \fIphotcolumns\fR to his or her own preferred list +of standard photometry columns. Non-standard columns may also be specified +using the parameter \fIusercolumns\fR. Valid column lists contain the full +names of the specified columns in upper or lower case letters, separated by +commas. Either \fIphotcolumns\fR or \fIusercolumns\fR may be redefined +interactively by the user after the task has started up, but only at the +expense of rereading the data from \fIinput\fR. + +PEXAMINE will fail to load a specified column if that column is not in the +photometry database, is of a datatype other than integer or real, or adding +that column would exceed the maximum number of columns limit currently set at +twenty. The user can interactively examine the list of requested and loaded +standard photometry columns, as well as list all the columns in the input after +the task has started up. + +GRAPHICS AND IMAGE COMMAND MODE + +PEXAMINE accepts commands either from the graphics cursor \fIgcommands\fR +(graphics command mode) or the image display cursor \fIicommands\fR if available +(image command mode). PEXAMINE starts up in graphics command mode, but all the +interactive commands are accessible from both modes and the user can switch +modes at any time assuming that the \fIuse_display\fR parameter to "yes". + +PEXAMINE interprets the cursor position in graphics mode differently from how +it interprets it in image command mode. In graphics command mode the cursor +coordinates are the position of the cursor in the current plot, whereas in +image command mode they are the x and y coordinates of the cursor in the +displayed image. For example, if the user issues a command to PEXAMINE to +locate the object in the catalog nearest the point in the current X-Y plot +marked by the graphics cursor, PEXAMINE does so by searching the data for the +object whose values of \fIxcolumn\fR and \fIycolumn\fR most closely match those +of the current cursor position. If the user issues a command to PEXAMINE to +locate the object in the catalog corresponding to the object marked on the +image display with the image cursor, PEXAMINE does so by searching the data for +the object whose values of \fIxposcolumn\fR and \fIyposcolumn\fR most closely +match and fall within \fImatch_radius\fR of the current cursor position. + +Input to PEXAMINE is through single keystroke commands or colon commands. +Keystroke commands are simple commands that may optionally use the cursor +position but otherwise require no arguments. The PEXAMINE keystroke commands +fall into three categories, basic commands, data examining commands and data +editing commands, all described in detail in the following sections. Colon +commands take an optional argument and function differently depending on the +presence or absence of that argument. When the argument is absent colon +commands are used to display the current value of a parameter or list of +parameters. When the argument is present they change their current value to +that argument. The basic colon commands are described in detail below. + +BASIC KEYSTROKE COMMANDS + +These keystroke commands are used to display the help page, switch from +graphics to image command mode and quit the task. + +.ls ? +Page through the help for the PEXAMINE task +.le +.ls : +Execute a PEXAMINE colon command. +.le +.ls g +Change to graphics command mode. Throughout PEXAMINE graphics command mode is +the default. All PEXAMINE commands are available in graphics command mode. +.le +.ls i +Change to image command mode. All the PEXAMINE commands are available in image +command mode. However if \fIuse_display\fR is no and the image cursor has not +been aliased to the standard input or a text file image command mode is +disabled. +.le +.ls q +Quit PEXAMINE without writing an output catalog. PEXAMINE queries the user for +confirmation of this option. +.le +.ls e +Quit PEXAMINE and write the output catalog. +.le + +DATA EXAMINING COMMANDS + +The data examining commands fall into two categories, those that examine the +catalog data including 'l' (catalog listing), 'o' (object listing), 'x' (Y +column versus X column plot) and 'h' (histogram column plot) commands, and +those which examine the image data around specific catalog objects including +'r' (radial profile plotting), 's' (surface plotting), 'c' (contour plotting) +and 'm' (pixel dumping). The latter group require that \fIimage\fR be defined. +A brief summary of each data examining command is given below. +.ls l +Print out the name, datatype, and units for all the columns in the input +catalog. The list command can be used to check the contents of the input +catalog and/or determine why a particular column was not loaded. +.le +.ls o +Print out the names and values of the stored columns of the object nearest the +cursor. In graphics mode the current plot type must be X-Y. In image command +mode the object nearest the cursor must also be no more than \fImatch-radius\fR +pixels away from the image cursor to be found. If an object is found and the +current plot type is X-Y the graphics cursor is moved to the position of the +selected object in the X-Y plot. +.le +.ls x +Plot the data in \fIycolumn\fR versus the data in \fIxcolumn\fR excluding any +already deleted points and identifying objects marked for deletion with a +cross. X-Y plotting is undefined if \fIxcolumn\fR or \fIycolumn\fR is undefined. +.le +.ls h +Plot the histogram of the data in \fIhcolumn\fR excluding any already deleted +points and those marked for deletion. Histogram plotting is disabled if +\fIhcolumn\fR is undefined. +.le +.ls r +Plot the radial profile of the object nearest the cursor including only pixels +within a distance of \fIrinner\fR and \fIrouter\fR of the object center. Radial +profile plotting is disabled if \fIimage\fR or \fIxposcolumn\fR or +\fIyposcolumn\fR is undefined. +.le +.ls s +Plot the surface plot of the object nearest the cursor including only pixels +within an image section \fIncols\fR by \fInlines\fR around the object center. +Surface plotting is disabled if \fIimage\fR or \fIxposcolumn\fR or +\fIyposcolumn\fR is undefined. +.le +.ls c +Plot the contour plot of the object nearest the cursor including only pixels +within an image section \fIncols\fR by \fInlines\fR around the object center. +Contour plotting is disabled if \fIimage\fR or \fIxposcolumn\fR or +\fIyposcolumn\fR is undefined. +.le +.ls m +Dump the pixel values of a grid of 10 by 10 pixels around the object nearest +the cursor. Pixel value dumping is disabled if \fIimage\fR or \fIxposcolumn\fR +or \fIyposcolumn\fR is undefined. +.le +.ls p +Replot the current graph. +.le + +DATA EDITING COMMANDS + +Data points can be deleted from the catalog in either graphics command mode or +image command mode. In graphics command mode the graphics cursor and either the +X-Y or histogram plot is used to delete points. In image command mode the image +cursor and the displayed image are used to delete points. A data point has three +possible states good, marked for deletion and deleted. Any one of the keystroke +commands 'd' (delete point), '(' (delete points with x less than x cursor), +')' (delete points with x greater than x cursor, '^' (delete points with y > y +cursor), 'v' (delete points with y < y cursor) or 'b' (delete points in a box) +can be used to mark points for deletion. The 'f' key is used to actually delete +the points and replot the data. In between marking the points for deletion and +actually deleting the marked points the 't' (toggle) key can be used to undelete +the last set marked. The full list of the data editing keystroke commands is +given below. + +.ls z +Undelete not just unmark all the data points replot. +.le +.ls f +Delete points marked for deletion and replot. Points marked for deletion but +not actually deleted will be written to the output catalog and not written to +the deletions catalog. +.le +.ls d +Mark the point nearest the cursor for deletion. +.le +.ls u +Undelete the marked point nearest the cursor. +.le +.ls ( +Mark all points with x values less than the x value of the cursor for deletion. +In graphics command mode points can only be marked for deletion if the current +plot type is "xyplot" or "histplot". In image command mode \fIxposcolumn\fR and +\fIyposcolumn\fR must be defined before points can be marked for deletion. +.le +.ls ) +Mark all points with x values greater than the x value of the cursor for +deletion. In graphics command mode points can only be marked for deletion if +the current plot type is "xyplot" or "histplot". In image command mode +\fIxposcolumn\fR and \fIyposcolumn\fR must be defined before points can be +marked for deletion. +.le +.ls v +Mark all points with y values less than the y value of the cursor for deletion. +In graphics command mode points can only be marked for deletion if the current +plot type is "xyplot". In image command mode \fIxposcolumn\fR and +\fIyposcolumn\fR must be defined before points can be marked for deletion. +.le +.ls ^ +Mark all points with y values greater than the y value of the cursor for +deletion. In graphics command mode points can only be marked for deletion if +the current plot type is "xyplot". In image command mode \fIxposcolumn\fR and +\fIyposcolumn\fR must be defined before points can be marked for deletion. +.le +.ls b +Mark all points within a box whose lower left and upper right hand corners are +marked by the cursor for deletion. In graphics mode points can only be marked +for deletion if the current plot type is "xyplot". In image command mode +\fIxposcolumn\fR and \fIyposcolumn\fR must be defined before points can be +marked for deletion. +.le +.ls t +Toggle between marking points for deletion or undeletion. The default is to +mark points for deletion. +.le + +BASIC COLON COMMANDS + +All the PEXAMINE parameters can be changed interactively with colon commands, +including those which determine which data is read in, which data is plotted +and the parameters of each plot. A brief description of the basic commands is +given here. The full list is given in the following section. + +.ls :photcolumns [col1,col2,...] +Show or set the list of requested standard photometry columns and the list +of loaded photometry columns. If the user supplies a new list of columns the +data will be reread from disk. +.le +.ls :usercolumns [col1,col2,...] +Show or set the list of requested user columns and the list of loaded user +columns. If the user supplies a new list of columns the data will be reread +from disk. +.le +.ls :xcolumn [colname] +Show or set the name of the column to be plotted along the x axis of the X-Y +plot. +.le +.ls :ycolumn [colname] +Show or set the name of the column to be plotted along the y axis of the X-Y +plot. +.le +.ls :hcolumn [colname] +Show or set the name of the column to be whose histogram is to be plotted. +.le +.ls :eparam [cntrplot/histplot/radplot/surfplot/xyplot] +Review or edit the list of parameters for the various plot types. +.le +.ls :unlearn [cntrplot/histplot/radplot/surfplot/xyplot] +Return the list of parameters for the various plot types to their default +values. +.le +.ls :x y key cmd +Execute any defined keystroke "key" supplying the appropriate x and y value in +place of the cursor position. In graphics command mode the x and y position are +assumed to be the position in the current graph. In image command mode the x +and y position are assumed to be the x and y coordinate in the image display. +.le + +.ih +COMMANDS + +.nf + PEXAMINE Interactive Cursor Keystroke Commands + + Basic Commands + +? Print help for the PEXAMINE task +: PEXAMINE colon commands +g Activate the graphics cursor +i Activate the image cursor +e Exit PEXAMINE and save the edited catalog +q Quit PEXAMINE and discard the edited catalog + + Data Examining Commands + +l List the name, datatype and units for all columns in the catalog +o Print out the names and values of the stored columns for the + object nearest the cursor +x Replot the current y column versus the current x column +h Replot the current histogram +r Plot the radial profile of the object nearest the cursor +s Plot the surface of the object nearest the cursor +c Plot the contour plot of the object nearest the cursor +m Print the data values of the object nearest the cursor +p Replot the current graph + + Data Editing Commands + +z Reinitialize the data by removing all deletions and replot +d Mark the point nearest the cursor for deletion +u Undelete the marked point nearest the cursor +t Toggle between marking points for deletion or undeletion +( Mark points with X < X (cursor) for deletion or undeletion +) Mark points with X > X (cursor) for deletion or undeletion +v Mark points with Y < Y (cursor) for deletion or undeletion +^ Mark points with Y > Y (cursor) for deletion or undeletion +b Mark points inside a box for deletion or undeletion +f Actually delete the marked points and replot + + + PEXAMINE Interactive Colon Commands + +:xcolumn [name] Show/set the X-Y plot X axis quantity +:ycolumn [name] Show/set the X-Y plot Y axis quantity +:hcolumn [name] Show/set the histogram plot quantity +:photcolumns [col1,col2,...] Show/set the list of photometry columns +:usercolumns [col1,col2,...] Show/set the list of user columns +:delete [yes/no] Delete or undelete points +:eparam [x/h/r/s/c] Edit/unlearn the specified plot pset + or +:unlearn + + + PEXAMINE Interactive X-Y Plotting Commands + +:x1 [value] Left world x-coord if not autoscaling +:x2 [value] Right world x-coord if not autoscaling +:y1 [value] Lower world y-coord if not autoscaling +:y2 [value] Upper world y-coord if not autoscaling +:szmarker [value] Marker size +:marker [point|box|plus|cross|circle|diamond|hline|vline] Marker type +:logx [yes/no] Log scale the x axis? +:logy [yes/no] Log scale the y axis? +:box [yes/no] Draw box around periphery of window? +:ticklabels [yes/no] Label tick marks? +:grid [yes/no] Draw grid lines at major tick marks? +:majrx [value] Number of major divisions along x axis +:minrx [value] Number of minor divisions along x axis +:majry [value] Number of major divisions along y axis +:minry [value] Number of minor divisions along y axis +:round [yes/no] Round axes to nice values? +:fill [yes/no] Fill viewport vs enforce unity aspect ratio? + + + PEXAMINE Interactive Histogram Plotting Commands + +:nbins [value] Number of bins in the histogram +:z1 [value] Minimum histogram intensity +:z2 [value] Maximum histogram intensity +:top_closed [y/n] Include z in the top bin? +:x1 [value] Left world x-coord if not autoscaling +:x2 [value] Right world x-coord if not autoscaling +:y1 [value] Lower world y-coord if not autoscaling +:y2 [value] Upper world y-coord if not autoscaling +:logy [yes/no] Log scale the y axis? +:box [yes/no] Draw box around periphery of window? +:ticklabels [yes/no] Label tick marks? +:majrx [value] Number of major divisions along x axis +:minrx [value] Number of minor divisions along x axis +:majry [value] Number of major divisions along y axis +:minry [value] Number of minor divisions along y axis +:round [yes/no] Round axes to nice values? +:fill [yes/no] Fill viewport vs enforce unity aspect ratio? + + PEXAMINE Interactive Radial Profile Plotting Commands + +:rinner [value] Inner radius of the region to be plotted +:router [value] Outer radius of the region to be plotted +:x1 [value] Left world x-coord if not autoscaling +:x2 [value] Right world x-coord if not autoscaling +:y1 [value] Lower world y-coord if not autoscaling +:y2 [value] Upper world y-coord if not autoscaling +:szmarker [value] Marker size +:marker [point|box|plus|cross|circle|diamond|hline|vline] Marker type +:logx [yes/no] Log scale the x axis? +:logy [yes/no] Log scale the y axis? +:box [yes/no] Draw box around periphery of window? +:ticklabels [yes/no] Label tick marks? +:grid [yes/no] Draw grid lines at major tick marks? +:majrx [value] Number of major divisions along x axis +:minrx [value] Number of minor divisions along x axis +:majry [value] Number of major divisions along y axis +:minry [value] Number of minor divisions along y axis +:round [yes/no] Round axes to nice values? +:fill [yes/no] Fill viewport vs enforce unity aspect ratio? + + + PEXAMINE Interactive Surface Plotting Commands + +:ncolumns [value] Number of columns to be plotted +:nlines [value] Number of lines to be plotted +:axes [yes/no] Draw axes? +:angh [value] Horizontal viewing angle +:angv [value] Vertical viewing angle +:floor [value] Minimum value to be plotted +:ceiling [value] Maximum value to be plotted + + + PEXAMINE Interactive Contour Plotting Commands + +:ncolumns [value] Number of columns to be plotted +:nlines [value] Number of lines to be plotted +:floor [value] Minimum value to be plotted +:ceiling [value] Maximum value to be plotted +:zero [value] Grayscale value of zero contour +:ncontours [value] Number of contours to be drawn +:interval [value] Contour interval +:nhi [value] Hi/low marking option +:dashpat [value] Bit pattern for generating dashed lines +:label [yes/no] Label major contours with their values? +:box [yes/no] Draw box around periphery of window? +:ticklabels [yes/no] Label tick marks? +:majrx [value] Number of major divisions along x axis +:minrx [value] Number of minor divisions along x axis +:majry [value] Number of major divisions along y axis +:minry [value] Number of minor divisions along y axis +:round [yes/no] Round axes to nice values? +:fill [yes/no] Fill viewport vs enforce unity aspect ratio? +.fi + +.ih +EXAMPLES + +1. Examine and edit an APPHOT aperture photometry catalog and a DAOPHOT +allstar catalog without either attaching the associated image or using the +image display. + +.nf + pt> pexamine ypix.mag.1 ypix.mag.ed use_display- + + ... a plot of magnitude error versus magnitude appears on + the screen and the graphics cursor comes up ready to accept + commands + + ... the user sees a generally smooth trend of increasing + magnitude error with increasing magnitude except for a + single deviant point at the bright end of the plot + + ... the user decides to remove the deviant point using the + 'd' keystroke command to mark the point and the 'f' + keystroke command to actually delete and replot the graph + + ... after examining the plot further the user decides to delete + all objects for which the magnitude error is > 0.1 magnitudes + using the '^' keystroke command, followed by the 'f' + keystroke command to actually replot and delete the data. + + ... after deciding that this new plot is satisfactory the user + issues the 'e' keystroke command to exit pexamine and save + the good data in m92.mag.ed + + pt> pexamine ypix.als.1 ypix.als.ed use_display- + + ... a plot of magnitude error versus magnitude appears on the + screen and the graphics cursor comes up ready to accept + commands + + ... after looking at the plot the user decides that what they + really want to see is a plot of the goodness of fit parameter + chi versus magnitude + + ... the user issues the colon command :ycol chi followed by 'p' + keystroke command to replot the data + + ... the user sees a generally smooth trend of increasing + chi with increasing magnitude + + ... after examining the plot further the user decides to delete + all objects for which the chi value > 2.0 and the + magnitude is > 25 using the '^' key and ')' keystroke + commands followed by 'f' to save the deletions and replot + the data + + ... after deciding that this new plot is satisfactory the user + issues the 'e' keystroke command to exit pexamine and save + the good data in m92.als.ed +.fi + +2. Examine and edit a DAOPHOT allstar catalog using the subtracted image, the +original image and the image display. + +.nf + pt> display ypix.sub.1 1 + + ... display the subtracted image + + pt> pexamine ypix.als.1 ypix.als.ed dev$ypix xcol=mag ycol=chi + + ... a plot of the goodness of fit versus magnitude appears + on the terminal and the graphics cursor comes up ready to + accept commands + + ... the user notices some very anomalous chi values and decides + to see if these correspond to objects which have poor + subtraction on the displayed image + + ... the user switches to image command mode by tapping the 'i' + key, moves to the first poorly subtracted object and taps + the 'o' key + + ... a list of the values of the loaded columns including chi + appears in the text window , the program switches to graphics + mode and places the graphics cursor on the corresponding + point in the X-Y plot + + ... the point in question indeed has a very high chi value + and the user decides to try and investigate the reason for the + anomalous value + + ... the user taps the 'r' key to get a radial profile of the + object in the original image + + ... after carefully examining the profile it appears that the + object's profile is too broad and that it is not a star + + ... the user switches back to the X-Y plot with the 'x' key, + marks the point with the 'd' key and saves the deletions + and replots with the 'f' key. + + ... the user goes back to image command mode with the 'i' key + and begins investigating the next object + + ... finally after examining the image and making all the changes + the user decides to quit and save the changes with the 'e' key + +.fi + +.ih +TIME REQUIREMENTS + +.ih +BUGS + +INDEF valued points cannot be accessed by PEXAMINE. INDEF valued points should +be removed from the input catalog with PSELECT prior to entering PEXAMINE. + +.ih +SEE ALSO +ptools.pselect, ptools.txselect,ptools.tselect + +.endhelp diff --git a/noao/digiphot/daophot/doc/pfmerge.hlp b/noao/digiphot/daophot/doc/pfmerge.hlp new file mode 100644 index 00000000..a85b60ee --- /dev/null +++ b/noao/digiphot/daophot/doc/pfmerge.hlp @@ -0,0 +1,65 @@ +.help pfmerge May00 noao.digiphot.daophot +.ih +NAME +pfmerge -- merge a list of photometry files +.ih +USAGE +pfmerge inphotfiles outphotfile +.ih +PARAMETERS +.ls inphotfiles +The list of photometry files to be merged. Inphotfiles may be the output of the +DAOPHOT tasks PHOT, PSTSELECT, PSF, PEAK, GROUP, GRPSELECT, NSTAR, or ALLSTAR. +Inphotfiles may be either a list of APPHOT/DAOPHOT text databases or a list of +STSDAS binary tables. +.le +.ls outphotfile +The output photometry file. Outphotfile consists of the header of the first +input photometry file, followed by a list of records, one per input file +record, each consisting of five fields: ID, XCENTER, YCENTER, MAG, and MSKY. +Outphotfile is a an APPHOT/DAOPHOT text database if the first photometry file +is a text database, an STSDAS binary table if the first photometry file is an +ST table. +.le +.ls verbose +Print messages about the progress of the task ? +.le +.ih +DESCRIPTION +PFMERGE creates a new photometry file suitable for input to PSF, PEAK, GROUP, +or ALLSTAR by extracting the header of the first input photometry file and the +values of the five fields: ID, XCENTER, YCENTER, MAG, and MSKY from each +photometry record in each input file, and writing them to \fIoutphotfile\fR. +\fIInphotfiles\fR may be either APPHOT/DAOPHOT text databases or STSDAS binary +tables, but \fIoutphotfile\fR inherits the type of the first input photometry +file. + +The principal application of PFMERGE is to combine the results of one of the +DAOPHOT fitting tasks, e.g. ALLSTAR, with the results of the aperture photometry +task PHOT, to create a new photometry file suitable for input to the fitting +task. e.g. ALLSTAR, since it if often the case that the user wishes to combine +preliminary results for a few additional stars with the best fit results to +date on the original star list. + +PFMERGE is intended to combine photometry files from different DAOPHOT tasks. +The task PCONCAT can be used to combine photometry files produced by the same +task. + +.ih +EXAMPLES + +1. Combine the results of the first allstar run with phot task results +on a small list of stars detected after the first list of stars was +subtracted from the original image. + +.nf + cl> pfmerge m92.als.1,m92.mag.5 m92.als.2 +.fi +.ih +TIME REQUIREMENTS +.ih +BUGS +.ih +SEE ALSO +pconcat +.endhelp diff --git a/noao/digiphot/daophot/doc/phot.hlp b/noao/digiphot/daophot/doc/phot.hlp new file mode 100644 index 00000000..cc0033c8 --- /dev/null +++ b/noao/digiphot/daophot/doc/phot.hlp @@ -0,0 +1,831 @@ +.help phot May00 noao.digiphot.daophot +.ih +NAME +phot -- do aperture photometry on a list of stars +.ih +USAGE +phot image coords output +.ih +PARAMETERS +.ls image +The list of images containing the objects to be measured. +.le +.ls coords +The list of text files containing initial coordinates for the objects to +be centered. Objects are listed in coords one object per line with the +initial coordinate values in columns one and two. The number of coordinate +files must be zero, one, or equal to the number of images. If coords is +"default", "dir$default", or a directory specification then a coords file name +of the form dir$root.extension.version is constructed and searched for, +where dir is the directory, root is the root image name, extension is "coo" +and version is the highest available version number for the file. +.le +.ls output +The name of the results file or results directory. If output is +"default", "dir$default", or a directory specification then an output file name +of the form dir$root.extension.version is constructed, where dir is the +directory, root is the root image name, extension is "mag" and version is +the next available version number for the file. The number of output files +must be zero, one, or equal to the number of image files. In both interactive +and batch mode full output is written to output. In interactive mode +an output summary is also written to the standard output. +.le +.ls skyfile = "" +The list of text files containing the sky values, of the measured objects, +one object per line with x, y, the sky value, sky sigma, sky skew, number of sky +pixels and number of rejected sky pixels in columns one to seven respectively. +The number of sky files must be zero, one, or equal to the number of input +images. A skyfile value is only requested if \fIfitskypars.salgorithm\fR = +"file" and if PHOT is run non-interactively. +.le +.ls plotfile = "" +The name of the file containing radial profile plots of the stars written +to the output file. If plotfile is defined then a radial profile plot +is written to plotfile every time a record is written to \fIoutput\fR. +The user should be aware that this can be a time consuming operation. +.le +.ls datapars = "" +The name of the file containing the data dependent parameters. The critical +parameters \fIfwhmpsf\fR and \fIsigma\fR are located here. If \fIdatapars\fR +is undefined then the default parameter set in uparm directory is used. +.le +.ls centerpars = "" +The name of the file containing the centering parameters. The critical +parameters \fIcalgorithm\fR and \fIcbox\fR are located here. +If \fIcenterpars\fR is undefined then the default parameter set in +uparm directory is used. +.le +.ls fitskypars = "" +The name of the text file containing the sky fitting parameters. The critical +parameters \fIsalgorithm\fR, \fIannulus\fR, and \fIdannulus\fR are located here. +If \fIfitskypars\fR is undefined then the default parameter set in uparm +directory is used. +.le +.ls photpars = "" +The name of the file containing the photometry parameters. The critical +parameter \fIapertures\fR is located here. If \fIphotpars\fR is undefined +then the default parameter set in uparm directory is used. +.le +.ls interactive = no +Run the task interactively ? +.le +.ls radplots = no +If \fIradplots\fR is "yes" and PHOT is run in interactive mode, a radial +profile of each star is plotted on the screen after the star is measured. +.le +.ls icommands = "" +The image display cursor or image cursor command file. +.le +.ls gcommands = "" +The graphics cursor or graphics cursor command file. +.le +.ls wcsin = ")_.wcsin", wcsout = ")_.wcsout" +The coordinate system of the input coordinates read from \fIcoords\fR and +of the output coordinates written to \fIoutput\fR respectively. The image +header coordinate system is used to transform from the input coordinate +system to the "logical" pixel coordinate system used internally, +and from the internal "logical" pixel coordinate system to the output +coordinate system. The input coordinate system options are "logical", "tv", +"physical", and "world". The output coordinate system options are "logical", +"tv", and "physical". The image cursor coordinate system is assumed to +be the "tv" system. +.ls logical +Logical coordinates are pixel coordinates relative to the current image. +The logical coordinate system is the coordinate system used by the image +input/output routines to access the image data on disk. In the logical +coordinate system the coordinates of the first pixel of a 2D image, e.g. +dev$ypix and a 2D image section, e.g. dev$ypix[200:300,200:300] are +always (1,1). +.le +.ls tv +Tv coordinates are the pixel coordinates used by the display servers. Tv +coordinates include the effects of any input image section, but do not +include the effects of previous linear transformations. If the input +image name does not include an image section, then tv coordinates are +identical to logical coordinates. If the input image name does include a +section, and the input image has not been linearly transformed or copied from +a parent image, tv coordinates are identical to physical coordinates. +In the tv coordinate system the coordinates of the first pixel of a +2D image, e.g. dev$ypix and a 2D image section, e.g. dev$ypix[200:300,200:300] +are (1,1) and (200,200) respectively. +.le +.ls physical +Physical coordinates are pixel coordinates invariant with respect to linear +transformations of the physical image data. For example, if the current image +was created by extracting a section of another image, the physical +coordinates of an object in the current image will be equal to the physical +coordinates of the same object in the parent image, although the logical +coordinates will be different. In the physical coordinate system the +coordinates of the first pixel of a 2D image, e.g. dev$ypix and a 2D +image section, e.g. dev$ypix[200:300,200:300] are (1,1) and (200,200) +respectively. +.le +.ls world +World coordinates are image coordinates in any units which are invariant +with respect to linear transformations of the physical image data. For +example, the ra and dec of an object will always be the same no matter +how the image is linearly transformed. The units of input world coordinates +must be the same as those expected by the image header wcs, e. g. +degrees and degrees for celestial coordinate systems. +.le +The wcsin and wcsout parameters default to the values of the package +parameters of the same name. The default values of the package parameters +wcsin and wcsout are "logical" and "logical" respectively. +.le +.ls cache = ")_.cache" +Cache the image pixels in memory. Cache may be set to the value of the apphot +package parameter (the default), "yes", or "no". By default caching is +disabled. +.le +.ls verify = ")_.verify" +Verify the critical PHOT parameters in non-interactive mode ? Verify can be set +to the DAOPHOT package parameter value (the default), "yes", or "no". +.le +.ls update = ")_.update" +Update the algorithm parameter values if \fIverify\fR is "yes" and +\fIinteractive\fR is "no" ? Update can be set to the DAOPHOT package parameter +value (the default), "yes", or "no". +.le +.ls verbose = ")_.verbose" +Print results on the screen in non-interactive mode ? Verbose can be set to +the DAOPHOT package parameter value (the default), "yes", or "no". +.le +.ls graphics = ")_.stdgraph" +The default graphics device. Graphics may be set to the DAOPHOT package +parameter value (the default), "yes", or "no". +.le +.ls display = ")_.display" +The default display device. Display may be set to the DAOPHOT package +parameter value (the default), "yes", or "no". By default graphics overlay is +disabled. Setting display to one of "imdr", "imdg", "imdb", or "imdy" enables +graphics overlay with the IMD graphics kernel. Setting display to "stdgraph" +enables PHOT to work interactively from a contour plot. + +.le + +.ih +DESCRIPTION + +PHOT computes accurate centers, sky values, and magnitudes for a list of +objects in the IRAF image \fIimage\fR whose coordinates are read from +the text file \fIcoords\fR or the image display cursor, and writes the +computed x and y coordinates, sky values, and magnitudes to the text +file \fIoutput\fR. + +The coordinates read from \fIcoords\fR are assumed to be in coordinate +system defined by \fIwcsin\fR. The options are "logical", "tv", "physical", +and "world" and the transformation from the input coordinate system to +the internal "logical" system is defined by the image coordinate system. +The simplest default is the "logical" pixel system. Users working on with +image sections but importing pixel coordinate lists generated from the parent +image must use the "tv" or "physical" input coordinate systems. +Users importing coordinate lists in world coordinates, e.g. ra and dec, +must use the "world" coordinate system and may need to convert their +equatorial coordinate units from hours and degrees to degrees and degrees first. + +The coordinates written to \fIoutput\fR are in the coordinate +system defined by \fIwcsout\fR. The options are "logical", "tv", +and "physical". The simplest default is the "logical" system. Users +wishing to correlate the output coordinates of objects measured in +image sections or mosaic pieces with coordinates in the parent +image must use the "tv" or "physical" coordinate systems. + +In interactive mode the user may either define the list of objects to be +measured interactively with the image cursor or create an object list prior +to running PHOT. In either case the user may adjust the centering, sky fitting, + and photometry algorithm parameters until a satisfactory fit is achieved +and optionally store the final results in \fIoutput\fR. In batch mode the +initial positions are read from the text file \fIcoords\fR or the image +cursor parameter \fIicommands\fR can be redirected to a text file containing +a list of cursor commands. In batch mode the current set of algorithm +parameters is used. + +If \fIcache\fR is yes and the host machine physical memory and working set size +are large enough, the input image pixels are cached in memory. If caching +is enabled and PHOT is run interactively the first measurement will appear +to take a long time as the entire image must be read in before the measurement +is actually made. All subsequent measurements will be very fast because PHOT +is accessing memory not disk. The point of caching is to speed up random +image access by making the internal image i/o buffers the same size as the +image itself. However if the input object lists are sorted in row order and +sparse caching may actually worsen not improve the execution time. Also at +present there is no point in enabling caching for images that are less than +or equal to 524288 bytes, i.e. the size of the test image dev$ypix, as the +default image i/o buffer is exactly that size. However if the size of dev$ypix +is doubled by converting it to a real image with the chpixtype task then the +effect of caching in interactive is can be quite noticeable if measurements +of objects in the top and bottom halves of the image are alternated. + + +PHOT computes accurate centers for each object using the centering +parameters defined in \fIcenterpars\fR, computes an accurate sky value +for each object using the sky fitting parameters defined in \fIfitskypars\fR, + and computes magnitudes using the photometry parameters defined in +\fIphotpars\fR. The image data characteristics of the data are specified +in \fIdatapars\fR. + +Unlike the APPHOT versions of PHOT the DAOPHOT version of PHOT does NOT +recenter the stars, as the default input coordinate list is created +by the DAOFIND task which itself computes accurate centers for the stars. +DAOPHOT users should set the CENTERPARS task parameter \fIcalgorithm\fR +to "centroid" if they need to measure stars interactively with the +image display and image display cursor. The PHOT tasks centers provide +initial guesses for the PSF modeling and fitting routines in the PSF, +PEAK, NSTAR, and ALLSTAR tasks. + +The DAOPHOT version of PHOT sets the sky fitting algorithm to "mode". +This algorithm which uses the mean and median to estimate the value +that the sky would have if the star of interest wasn't there, is in most +cases the one which will give the best results in crowded fields. Users +interested in reducing small stellar groups should realizes that they can, +fix the sky by setting the FITSKYPARS parameter \fIsalgorithm\fR to "constant" +and setting \fIskyvalue\fR to the desired sky value, or set the sky +interactively using the "radplot" or "histplot" options. Users with rapidly +varying sky backgrounds may wish to explore the "median" or "centroid" sky +fitting algorithm which can be more stable than the "mode" algorithm +against complex sky pixel histograms. Users with very few counts in their +data or with quantized data where the standard deviation is small with +respect to the quantization level may wish to explore the "mean", +and "centroid" sky fitting algorithms. + +The PHOT task sets the instrumental magnitude scale for all the subsequent +DAOPHOT tasks. Users should be sure they have set the PHOTPARS \fIapertures\fR +parameter to a reasonable value, and that they have accounted for the +exposure time by setting either the DATAPARS \fIexposure\fR or \fIitime\fR +parameters. + + +.ih +CURSOR COMMANDS + +The following list of cursor commands are currently available. + +.nf + Interactive Keystroke Commands + +? Print help +: Colon commands +v Verify critical parameters +w Save current parameters +d Plot radial profile of current star +i Set parameters interactively using current star +c Fit center for current star +t Fit sky around cursor +s Fit sky around current centered star +p Do photometry for current star, using current sky +o Do photometry for current star, using current sky, output results +f Do photometry for current star +spbar Do photometry for current star, output results +m Move to next star in coordinate list +n Do photometry for next star in coordinate list, output results +l Do photometry for remaining stars in coordinate list, output results +e Print error messages +r Rewind coordinate list +q Exit task + + +Photometry parameters are listed or set with the following commands. + + Colon commands + +:show [data/center/sky/phot] List the parameters +:m [n] Move to next [nth] star in coordinate list +:n [n] Measure next [nth] star in coordinate list, output results + + Colon Parameter Editing Commands + +# Image and file name parameters + +:image [string] Image name +:coords [string] Coordinate file name +:output [string] Output file name + +# Data dependent parameters + +:scale [value] Image scale (units per pixel) +:fwhmpsf [value] Full width half maximum of PSF (scale units) +:emission [y/n] Emission feature (y), absorption (n) +:sigma [value] Standard deviation of sky (counts) +:datamin [value] Minimum good data value (counts) +:datamax [value] Maximum good data value (counts) + +# Noise parameters + +:noise [string] Noise model (constant|poisson) +:gain [string] Gain image header keyword +:ccdread [string] Readout noise image header keyword +:epadu [value] Gain (electrons per adu) +:readnoise [value] Readout noise (electrons) + +# Observations parameters + +:exposure [string] Exposure time image header keyword +:airmass [string] Airmass image header keyword +:filter [string] Filter image header keyword +:obstime [string] Time of observation image header keyword +:itime [value] Integration time (time units) +:xairmass [value] Airmass value (number) +:ifilter [string] Filter id string +:otime [string] Time of observation (time units) + +# Centering algorithm parameters + +:calgorithm [string] Centering algorithm +:cbox [value] Width of the centering box (scale units) +:cthreshold [value] Centering intensity threshold (sigma) +:cmaxiter [value] Maximum number of iterations +:maxshift [value] Maximum center shift (scale units) +:minsnratio [value] Minimum S/N ratio for centering +:clean [y/n] Clean subraster before centering +:rclean [value] Cleaning radius (scale units) +:rclip [value] Clipping radius (scale units) +:kclean [value] Clean K-sigma rejection limit (sigma) + +# Sky fitting algorithm parameters + +:salgorithm [string] Sky fitting algorithm +:skyvalue [value] User supplied sky value (counts) +:annulus [value] Inner radius of sky annulus (scale units) +:dannulus [value] Width of sky annulus (scale units) +:khist [value] Sky histogram extent (+/- sky sigma) +:binsize [value] Resolution of sky histogram (sky sigma) +:smooth [y/n] Lucy smooth the sky histogram +:sloclip [value] Low-side clipping factor in percent +:shiclip [value] High-side clipping factor in percent +:smaxiter [value] Maximum number of iterations +:snreject [value] Maximum number of rejection cycles +:sloreject [value] Low-side pixel rejection limits (sky sigma) +:shireject [value] High-side pixel rejection limits (sky sigma) +:rgrow [value] Region growing radius (scale units) + +# Photometry parameters + +:apertures [string] List of aperture radii (scale units) +:zmag [value] Zero point of magnitude scale + +# Plotting and marking parameters + +:mkcenter [y/n] Mark computed centers on display +:mksky [y/n] Mark the sky annuli on the display +:mkapert [y/n] Mark apertures on the display +:radplot [y/n] Plot radial profile of object + + +The following commands are available from inside the interactive setup menu. + + Interactive Phot Setup Menu + + v Mark and verify the critical parameters (f,s,c,a,d,r) + + f Mark and verify the full-width half-maximum of psf + s Mark and verify the standard deviation of the background + l Mark and verify the minimum good data value + u Mark and verify the maximum good data value + + c Mark and verify the centering box width + n Mark and verify the cleaning radius + p Mark and verify the clipping radius + + a Mark and verify the inner radius of the sky annulus + d Mark and verify the width of the sky annulus + g Mark and verify the region growing radius + + r Mark and verify the aperture radii +.fi + +.ih +ALGORITHMS + +A brief description of the data dependent parameters, centering algorithms, +sky fitting algorithms and photometry parameters can be found in the +online help pages for the DATAPARS, CENTERPARS, FITSKYPARS, and PHOTPARS +tasks. + +.ih +OUTPUT + +In interactive mode the following quantities are printed on the standard +output as each object is measured. Err is a simple string indicating whether +or not an error was detected in the centering algorithm, the sky fitting +algorithm or the photometry algorithm. Mag are the magnitudes in apertures 1 +through N respectively and xcenter, ycenter and msky are the x and y centers +and the sky value respectively. + +.nf + image xcenter ycenter msky mag[1 ... N] error +.fi + +In both interactive and batch mode full output is written to the text file +\fIoutput\fR. At the beginning of each file is a header listing the +current values of the parameters when the first stellar record was written. +These parameters can be subsequently altered. For each star measured the +following record is written + +.nf + image xinit yinit id coords lid + xcenter ycenter xshift yshift xerr yerr cier error + msky stdev sskew nsky nsrej sier serror + itime xairmass ifilter otime + rapert sum area mag merr pier perr +.fi + +Image and coords are the name of the image and coordinate file respectively. +Id and lid are the sequence numbers of stars in the output and coordinate +files respectively. Cier and cerror are the centering algorithm error code +and accompanying error message respectively. Xinit, yinit, xcenter, ycenter, +xshift, yshift, and xerr, yerr are self explanatory and output in pixel units. +The sense of the xshift and yshift definitions is the following. + + +.nf + xshift = xcenter - xinit + yshift = ycenter - yinit +.fi + +Sier and serror are the sky fitting error code and accompanying error +message respectively. Msky, stdev and sskew are the best estimate of the sky +value (per pixel), standard deviation and skew respectively. Nsky and nsrej +are the number of sky pixels and the number of sky pixels rejected respectively. + +Itime is the exposure time, xairmass is self-evident, ifilter is an +id string identifying the filter used in the observations, and otime is +a string containing the time of the observation in whatever units the +user has set up. + +Rapert, sum, area, and flux are the radius of the aperture in scale units, +the total number of counts including sky in the aperture, the area of the +aperture in square pixels, and the total number of counts excluding sky +in the aperture. Mag and merr are the magnitude and error in the magnitude +in the aperture (see below). + +.nf + flux = sum - area * msky + mag = zmag - 2.5 * log10 (flux) + 2.5 * log10 (itime) + merr = 1.0857 * err / flux + err = sqrt (flux / epadu + area * stdev**2 + + area**2 * stdev**2 / nsky) +.fi + +Pier and perror are photometry error code and accompanying error message. + +In interactive mode a radial profile of each measured object is plotted +in the graphics window if \fIradplots\fR is "yes". + +In interactive and batchmode a radial profile plot is written to +\fIplotfile\fR if it is defined each time the result of an object +measurement is written to \fIoutput\fR . + + +.ih +ERRORS + +If the object centering was error free then the field cier will be zero. +Non-zero values of cier flag the following error conditions. + +.nf + 0 # No error + 101 # The centering box is off image + 102 # The centering box is partially off the image + 103 # The S/N ratio is low in the centering box + 104 # There are two few points for a good fit + 105 # The x or y center fit is singular + 106 # The x or y center fit did not converge + 107 # The x or y center shift is greater than maxshift + 108 # There is bad data in the centering box +.fi + +If all goes well during the sky fitting process then the error code sier +will be 0. Non-zero values of sier flag the following error conditions. + +.nf + 0 # No error + 201 # There are no sky pixels in the sky annulus + 202 # Sky annulus is partially off the image + 203 # The histogram of sky pixels has no width + 204 # The histogram of sky pixels is flat or concave + 205 # There are too few points for a good sky fit + 206 # The sky fit is singular + 207 # The sky fit did not converge + 208 # The graphics stream is undefined + 209 # The file of sky values does not exist + 210 # The sky file is at EOF + 211 # Cannot read the sky value correctly + 212 # The best fit parameter are non-physical +.fi + +If no error occurs during the measurement of the magnitudes then pier is +0. Non-zero values of pier flag the following error conditions. + +.nf + 0 # No error + 301 # The aperture is off the image + 302 # The aperture is partially off the image + 303 # The sky value is undefined + 305 # There is bad data in the aperture +.fi + +.ih +EXAMPLES + +1. Run PHOT on the image dev$ypix using the coordinate list ypix.coo.1 +created by DAOFIND and the default setup. + +.nf + da> daofind dev$ypix default fwhmpsf=2.6 sigma=5.0 threshold=20. \ + verify- + + ... make the coordinate list ypix.coo.1 + + da> phot dev$ypix default default + + ... answer the verify prompts + + ... the results will appear in ypix.mag.1 +.fi + + +2. Compute the magnitudes for a few stars in dev$ypix using the display +and the image cursor. Setup the task parameters using the interactive +setup menu defined by the i key command and a radial profile plot. + +.nf + da> display dev$ypix 1 fi+ + + ... display the image + + da> phot dev$ypix "" default calgorithm=centroid interactive+ + + ... type ? to print an optional help page + + ... move the image cursor to a star + ... type i to enter the interactive setup menu + ... enter maximum radius in pixels of the radial profile or hit + CR to accept the default + ... type v to enter the default menu + ... set the fwhmpsf, centering radius, inner and outer sky annuli, + photometry apertures, and sigma using the graphics cursor and + the stellar radial profile plot + ... typing <CR> leaves everything at the default value + ... type q to quit the setup menu + + ... type the v key to verify the parameters + + ... type the w key to save the parameters in the parameter files + + ... move the image cursor to the stars of interest and tap + the space bar + + ... a one line summary of the fitted parameters will appear on the + standard output for each star measured + + ... type q to quit and q again to confirm the quit + + ... the output will appear in ypix.mag.2 +.fi + + +3. Compute the magnitudes for a few stars in dev$ypix using a contour plot +and the graphics cursor. This option is only useful for those (now very few) +users who have access to a graphics terminal but not to an image display +server. Setup the task parameters using the interactive setup menu defined by +the i key command as in example 1. + +.nf + da> show stdimcur + + ... record the default value of stdimcur + + da> set stdimcur = stdgraph + + ... define the image cursor to be the graphics cursor + + da> contour dev$ypix + + ... make a contour plot of dev$ypix + + da> contour dev$ypix >G ypix.plot1 + + ... store the contour plot of dev$ypix in the file ypix.plot1 + + da> phot dev$ypix "" default calgorithm="centroid" interactive+ \ + display=stdgraph + + ... type ? to get an optional help page + + ... move graphics cursor to a star + ... type i to enter the interactive setup menu + ... enter maximum radius in pixels of the radial profile or CR + to accept the default value + ... type v to enter the default menu + ... set the fwhmpsf, centering radius, inner and outer sky annuli, + apertures, and sigma using the graphics cursor and the + stellar radial profile plot + ... typing <CR> leaves everything at the default value + ... type q to quit the setup menu + + ... type the v key to verify the critical parameters + + ... type the w key to save the parameters in the parameter files + + ... retype :.read ypix.plot1 to reload the contour plot + + ... move the graphics cursor to the stars of interest and tap + the space bar + + ... a one line summary of the fitted parameters will appear on the + standard output for each star measured + + ... type q to quit and q again to verify + + ... full output will appear in the text file ypix.mag.3 + + da> set stdimcur = <default> + + ... reset stdimcur to its previous value +.fi + + +4. Setup and run PHOT interactively on a list of objects temporarily +overriding the fwhmpsf, sigma, cbox, annulus, dannulus, and apertures +parameters determined in examples 1 or 2. + +.nf + + da> display dev$ypix 1 + + ... display the image + + da> phot dev$ypix ypix.coo.1 default calgorithm="centroid" \ + cbox=7.0 annulus=12.0 dannulus=5.0 apertures="3.0,5.0" \ + interactive+ + + ... type ? for optional help + + + ... move the graphics cursor to the stars and tap space bar + + or + + ... select stars from the input coordinate list with m / :m # + and measure with spbar + + ... measure stars selected from the input coordinate list + with n / n # + + ... a one line summary of results will appear on the standard output + for each star measured + + ... type q to quit and q again to confirm the quit + + ... the output will appear in ypix.mag.4 ... +.fi + + +5. Display and measure some stars in an image section and write the output +coordinates in the coordinate system of the parent image. + +.nf + da> display dev$ypix[150:450,150:450] 1 + + ... display the image section + + da> phot dev$ypix[150:450,150:450] "" default wcsout=tv \ + calgorithm="centroid" interactive+ + + ... move cursor to stars and type spbar + + ... type q to quit and q again to confirm quit + + ... output will appear in ypix.mag.5 + + da> pdump ypix.mag.5 xc,yc yes | tvmark 1 STDIN col=204 +.fi + + +6. Run PHOT in batch mode using the coordinate file and the previously +saved parameters. Verify the critical parameters. + +.nf + ap> phot dev$ypix default default + + ... output will appear in ypix.mag.6... +.fi + + +7. Repeat example 6 but assume that the input coordinate are ra and dec +in degrees and degrees, turn off verification, and submit the task to to +the background. + +.nf + da> display dev$ypix 1 + + ap> rimcursor wcs=world > radec.coo + + ... move to selected stars and type any key + + ... type ^Z to quit + + da> phot dev$ypix radec.coo default wcsin=world verify- verbose- & + + ... output will appear in ypix.mag.7 + + da> pdump ypix.mag.7 xc,yc yes | tvmark 1 STDIN col=204 + + ... mark the stars on the display +.fi + + +8. Run PHOT interactively without using the image display cursor. + +.nf + da> show stdimcur + + ... record the default value of stdimcur + + da> set stdimcur = text + + ... set the image cursor to the standard input + + da> phot dev$ypix default default interactive+ + + ... type ? for optional help + + ... type :m 3 to set the initial coordinates to those of the + third star in the list + + ... type i to enter the interactive setup menu + ... enter the maximum radius in pixels for the radial profile or + accept the default with a CR + ... type v to enter the default menu + ... set the fwhmpsf, centering radius, inner and outer sky annuli, + apertures, and sigma using the graphics cursor and the + stellar radial profile plot + ... typing <CR> after the prompt leaves the parameter at its default + value + ... type q to quit the setup menu + + ... type r to rewind the coordinate list + + ... type l to measure all the stars in the coordinate list + + ... a one line summary of the answers will appear on the standard + output for each star measured + + ... type q to quit followed by q to confirm the quit + + ... full output will appear in the text file ypix.mag.8 + + da> set stdimcur = <default> + + ... reset the value of stdimcur + +.fi + +8. Use a image cursor command file to drive the PHOT task. The cursor command +file shown below sets the cbox, annulus, dannulus, and apertures parameters +computes the centers, sky values, and magnitudes for 3 stars, updates the +parameter files, and quits the task. + +.nf + da> type cmdfile + : calgorithm centroid + : cbox 9.0 + : annulus 12.0 + : dannulus 5.0 + : apertures 5.0 + 442 410 101 \040 + 349 188 101 \040 + 225 131 101 \040 + w + q + + da> phot dev$ypix "" default icommands=cmdfile verify- + + ... full output will appear in ypix.mag.9 +.fi + + + + + +.ih +TIME REQUIREMENTS +.ih +BUGS + +It is currently the responsibility of the user to make sure that the +image displayed in the frame is the same as that specified by the image +parameter. + +Commands which draw to the image display are disabled by default. +To enable graphics overlay on the image display, set the display +parameter to "imdr", "imdg", "imdb", or "imdy" to get red, green, +blue or yellow overlays and set the centerpars mkcenter switch to +"yes", the fitskypars mksky switch to"yes", or the photpars mkapert +switch to "yes". It may be necessary to run gflush and to redisplay the image +to get the overlays position correctly. + +.ih +SEE ALSO +datapars, centerpars, fitskypars, photpars +.endhelp diff --git a/noao/digiphot/daophot/doc/photpars.hlp b/noao/digiphot/daophot/doc/photpars.hlp new file mode 100644 index 00000000..98f4e5f1 --- /dev/null +++ b/noao/digiphot/daophot/doc/photpars.hlp @@ -0,0 +1,100 @@ +.help photpars May00 noao.digiphot.daophot +.ih +NAME +photpars -- edit the photometry parameters +.ih +USAGE +photpars +.ih +PARAMETERS +.ls weighting = "constant" +The type of weighting. The weighting is ignored by the PHOT task. The options +are: +.ls constant +Uniform weights of 1 for each pixel are used. +.le +.ls cone +A conical weighting function of full width half maximum \fIfwhmpsf\fR as +defined in the DATAPARS parameter set is used. +.le +.ls gauss +A Gaussian weighting function of full width half maximum \fIfwhmpsf\fR as +defined in the DATAPARS parameter set is used. +.le +.le +.ls apertures = "3" (scale units) +A list of aperture radii in units of the scale parameter or the name of the +file containing the list of apertures. List elements may be separated by +whitespace or commas. A ranges syntax of the form ap1:apN:apstep is also +supported. +.le +.ls zmag = 25.00 +The zero point offset for the magnitude scale. +.le +.ls mkapert = no +Mark the photometry apertures on the displayed image? +.le + +.ih +DESCRIPTION + +The integral of the flux within the circular apertures specified by +\fIapertures\fR is computed by summing pixels in the aperture with +the specified weighting function \fIweighting\fR. The fraction of each pixel +lying within the aperture is computed by an approximation and all the +approximations are summed. The zero point of the magnitude +scale is determined by \fIzmag\fR. + +\fRApertures\fR is specified in units of the image scale. If \fIscale\fR +is specified in units of the half-width at half-maximum of the point +spread function the aperture per pixel a single value of apertures +will work well on images with differing psfs. + + +.ih +EXAMPLES + +1. List the PHOTPARS parameters. + +.nf + da> lpar photpars +.fi + +2. Edit the PHOTPARS parameters. + +.nf + da> photpars +.fi + +3. Edit the PHOTPARS parameters from with the PHOT task. + +.nf + da> epar phot + + ... edit a few phot parameters + + ... move to the photpars parameter and type :e + + ... edit the photpars parameters and type :wq + + ... finish editing the phot parameters and type :wq +.fi + +4. Save the current PHOTPARS parameter set in a text file photnite1.par. + This can also be done from inside a higher level task as in the above + example. + +.nf + da> photpars + + ... type ":w photnite1.par" from within epar +.fi + +.ih +TIME REQUIREMENTS +.ih +BUGS +.ih +SEE ALSO +epar,datapars,centerpars,fitskypars,phot +.endhelp diff --git a/noao/digiphot/daophot/doc/psf.hlp b/noao/digiphot/daophot/doc/psf.hlp new file mode 100644 index 00000000..5613a8b2 --- /dev/null +++ b/noao/digiphot/daophot/doc/psf.hlp @@ -0,0 +1,752 @@ +.help psf May00 noao.digiphot.daophot +.ih +NAME +psf -- build the point spread function for an image +.ih +USAGE +psf image photfile pstfile psfimage opstfile groupfile +.ih +PARAMETERS +.ls image +The images for which the PSF model is to be built. +.le +.ls photfile +The list of input photometry files. The number of photometry files must +be equal to the number of input images. If photfile is "default", "dir$default", +or a directory specification PSF searches for a file called dir$image.mag.# +where # is the highest available version number for the file. Photfile is +normally the output of the PHOT task but may also be the output of the PSF, +PEAK, NSTAR and ALLSTAR tasks. Photfile may be an APPHOT/DAOPHOT text database +or an STSDAS binary table. +.le +.ls pstfile +The list of input psf star photometry files. The ids of the psf stars in these +files must be the same as their ids in \fIphotfile\fR. The number of psf +star files must be zero or equal to the number of input images. If pstfile +is "default", "dir$default" or a directory specification, PSF searches for +a file called image.pst.? where ? is the highest existing version number. +Pstfile is usually the output of the DAOPHOT PSTSELECT task but may also be +the appropriately edited output psf file produced by PSF itself, or the output +of the GROUP, NSTAR, PEAK or ALLSTAR tasks. Photfile may be an APPHOT/DAOPHOT +text database or an STSDAS table. +.le +.ls psfimage +The output PSF model image names or directory. The must be one PSF image name +for every input image. If psfimage is "default", "dir$default", or a directory +specification, then PSF creates an image called image.psf.? where ? is the next +available version number. +.le +.ls opstfile +The output psf star files containing lists of the stars actually used to +compute the PSF model. There must be one output psf star file for every input +image. If opstfile is "default", "dir$default", or a directory specification +then PSF creates a file called image.pst.? where ? is the next available +version number. If the DAOPHOT package parameter \fItext\fR is "yes" then an +APPHOT/DAOPHOT text database is written, otherwise an STSDAS binary table is +written. +.le +.ls groupfile +The output psf star group files listing the PSF stars and their neighbors that +were used to create the PSF models. There must be one output group file for +every input image. If groupfile is "default", "dir$default", or a directory +specification then PSF creates a file called image.psg.? where ? is the +next available version number. If the DAOPHOT package parameter \fItext\fR is +"yes" then an APPHOT/DAOPHOT text database is written, otherwise an STSDAS +table database is written. +.le +.ls plotfile = "" +The name of the output file containing mesh, contour, or profile plots of the +selected PSF stars. If plotfile is undefined no plot file is created, +otherwise a mesh, contour, or profile plot is written to this file for each PSF +star selected. Plotfile is opened in append mode and may become very large. +.le +.ls datapars = "" +The name of the file containing the data dependent parameters. The parameters +\fIscale\fR, \fIdatamin\fR, and \fIdatamax\fR are located here. If datapars +is undefined then the default parameter set in uparm directory is used. +.le +.ls daopars = "" +The name of the file containing the daophot fitting parameters. The parameters +\fIpsfrad\fR and \fIfitrad\fR are located here. If \fIdaopars\fR is undefined +then the default parameter set in uparm directory is used. +.le +.ls matchbyid = yes +Match the stars in the psf star list(s) if any to the stars in the input +photometry files using id numbers (matchbyid = yes) or x and y positions +(matchbyid = no). +.le +.ls interactive = yes +Fit the PSF interactively ? If interactive = yes and \fIicommands\fR is +undefined, PSF reads selects the initial list of PSF stars from \fIpstfile\fR +and waits for commands from the user. If interactive = no and \fIicommands\fR +is undefined, PSF reads in the candidate PSF stars from \fIpstfile\fR, computes + the PSF, and writes it to \fIpsfimage\fR without input from the user. If +\fIicommands\fR is defined, then interactive = no, and commands are read from +the image cursor command file. +.le +.ls mkstars = no +Mark the selected or deleted psf stars on the image display ? +.le +.ls showplots = yes +Show plots of the selected PSF stars? After each star is selected +interactively by the user, a mesh, contour, or profile plot of the data +subraster around the candidate star is displayed. At this point the user +can accept or reject the star. In interactive mode the user can set showplots +to "yes" or "no". In non-interactive mode showplots is always "no". +.le +.ls plottype = "mesh" +The default type of plot displayed when selecting PSF stars. The choices +are "mesh", "contour", or "radial". +.le +.ls icommands = "" +The image display cursor or the name of the image cursor command file. +.le +.ls gcommands = "" +The graphics cursor or the name of the graphics cursor command file. +.le +.ls wcsin = ")_.wcsin", wcsout = ")_.wcsout" +The coordinate system of the input coordinates read from \fIphotfile\fR and +\fIpstfile\fR, and of the output coordinates written to \fIpsfimage\fR, +\fIopstfile\fR, \fIgroupfile\fR respectively. The image header coordinate +system is used to transform from the input coordinate system to the "logical" +pixel coordinate system used internally, and from the internal "logical" pixel +coordinate system to the output coordinate system. The input coordinate system +options are "logical", tv", "physical", and "world". The output coordinate +system options are "logical", "tv", and "physical". The image cursor coordinate +system is assumed to be the "tv" system. +.ls logical +Logical coordinates are pixel coordinates relative to the current image. +The logical coordinate system is the coordinate system used by the image +input/output routines to access the image data on disk. In the logical +coordinate system the coordinates of the first pixel of a 2D image, e.g. +dev$ypix and a 2D image section, e.g. dev$ypix[200:300,200:300] are +always (1,1). +.le +.ls tv +Tv coordinates are the pixel coordinates used by the display servers. Tv +coordinates include the effects of any input image section, but do not +include the effects of previous linear transformations. If the input +image name does not include an image section, then tv coordinates are +identical to logical coordinates. If the input image name does include a +section, and the input image has not been linearly transformed or copied from +a parent image, tv coordinates are identical to physical coordinates. +In the tv coordinate system the coordinates of the first pixel of a +2D image, e.g. dev$ypix and a 2D image section, e.g. dev$ypix[200:300,200:300] +are (1,1) and (200,200) respectively. +.le +.ls physical +Physical coordinates are pixel coordinates invariant with respect to linear +transformations of the physical image data. For example, if the current image +was created by extracting a section of another image, the physical +coordinates of an object in the current image will be equal to the physical +coordinates of the same object in the parent image, although the logical +coordinates will be different. In the physical coordinate system the +coordinates of the first pixel of a 2D image, e.g. dev$ypix and a 2D +image section, e.g. dev$ypix[200:300,200:300] are (1,1) and (200,200) +respectively. +.le +.ls world +World coordinates are image coordinates in any units which are invariant +with respect to linear transformations of the physical image data. For +example, the ra and dec of an object will always be the same no matter +how the image is linearly transformed. The units of input world coordinates +must be the same as those expected by the image header wcs, e. g. +degrees and degrees for celestial coordinate systems. +.le +The wcsin and wcsout parameters default to the values of the package +parameters of the same name. The default values of the package parameters +wcsin and wcsout are "logical" and "logical" respectively. +.le +.ls cache = ")_.cache" +Cache the image pixels in memory. Cache may be set to the value of the apphot +package parameter (the default), "yes", or "no". By default caching is +disabled. +.le +.ls verify = ")_.verify" +Verify the critical PSF task parameters? Verify can be set to the DAOPHOT +package parameter value (the default), "yes", or "no". +.le +.ls update = ")_.update" +Update the PSF task parameters if \fIverify\fR is "yes"? Update can be +set to the default daophot package parameter value, "yes", or "no". +.le +.ls verbose = ")_.verbose" +Print messages about the progress of the task ? Verbose can be set to the +DAOPHOT package parameter value (the default), "yes", or "no". +.le +.ls graphics = ")_.graphics" +The default graphics device. Graphics can be set to the default DAOPHOT package +parameter value, "yes", or "no". +.le +.ls display = ")_.display" +The default image display device. Display can be set to the DAOPHOT +package parameter value (the default), "yes", or "no". By default graphics +overlay is disabled. Setting display to one of "imdr", "imdg", "imdb", or +"imdy" enables graphics overlay with the IMD graphics kernel. +.le + +.ih +DESCRIPTION + +The PSF task builds the point spread function for the IRAF image \fIimage\fR +using stars selected, from the input photometry file \fIphotfile\fR with the +image cursor, and/or by their ids stored in the psf star file \fIpstfile\fR, +and writes the PSF model out to the IRAF image \fIpsfimage\fR, the final +PSF star list to \fIopstfile\fR, and group membership information for the +selected PSF stars to \fIgroupfile\fR. If the DAOPHOT package parameter +\fItext\fR is "yes", then \fIgroupfile\fR is an APPHOT/DAOPHOT text database, +otherwise it is an STSDAS binary table. + +The coordinates read from \fIphotfile\fR and \fIpstfile\fR are assumed to be +in coordinate system defined by \fIwcsin\fR. The options are "logical", "tv", +"physical", and "world" and the transformation from the input coordinate +system to the internal "logical" system is defined by the image coordinate +system. The simplest default is the "logical" pixel system. Users working on +with image sections but importing pixel coordinate lists generated from the +parent image must use the "tv" or "physical" input coordinate systems. + +The coordinates written to \fIpsfimage\fR, \fIpstfile\fR and \fIgroupfile\fR +are in the coordinate system defined by \fIwcsout\fR with the exception +of the psf model center coordinates PSFX and PSFY which are always in the +logical system of the input image. The options are "logical", "tv", and +"physical". The simplest default is the "logical" system. Users wishing to +correlate the output coordinates of objects measured in image sections or +mosaic pieces with coordinates in the parent image must use the "tv" +or "physical" coordinate systems. + +Suitable PSF stars are normally selected interactively using the image display +and image cursor and matched with the stars in \fIphotfile\fR using the cursor +position and a tolerance specified by the \fImatchrad\fR parameter in the +DAOPARS task. A star must be in the photometry file before it can be used as +a PSF star. If a match is found, PSF checks that the candidate star is not too +close to the edge of the image and that it contains no bad pixels as defined +by \fIdatamin\fR and \fIdatamax\fR in the DATAPARS task. After selection a +mesh, contour, or profile plot of the data subraster around the candidate star +is displayed in the graphics window, PSF enters graphics cursor command mode +and the user is given the option to accept or reject the star. If the user +accepts the star it is added to the PSF star list. Commands in the graphics +cursor menu permit the user to manipulate the floor and ceiling levels of the +contour plot and the viewing angles for the mesh plot interactively. + +Users who know which stars they wish to use as PSF stars ahead of time or +who are without access to an image display can also select PSF stars by id +number, after which mesh, contour, or radial profile plots will be displayed in +the graphics window in the usual way. + +If the user does not wish to see any plots of the PSF stars or interact with +the fitting process, the image cursor may be redirected to a text +file containing cursor commands \fIicommands\fR which specify the PSF stars +to be used in the fit. If \fIplotfile\fR is defined contour, mesh, or profile +plots of the selected psf stars can be saved in a metacode plot file for later +examination. + +In interactive mode the PSF star may be initialized by setting \fIpstfile\fR +to a file created by the PSTSELECT task. If \fIshowplot\fR = "yes" the user is +asked to accept or delete each star in the input psf star list. Other stars +may also be added or deleted from this list at any time with the image cursor. +If \fIinteractive\fR=no or \fIicommands\fR is defined, the PSF stars are read +in from \fIpstfile\fR, and the PSF model is computed and saved without +input from the user. + +If \fIcache\fR is yes and the host machine physical memory and working set size +are large enough, the input image pixels are cached in memory. If caching +is enabled and PSF is run interactively the first data access will appear +to take a long time as the entire image must be read in before the data +is actually read. All subsequent measurements will be very fast because PSF +is accessing memory not disk. The point of caching is to speed up random +image access by making the internal image i/o buffers the same size as the +image itself. However if the input object lists are sorted in row order and +sparse caching may actually worsen not improve the execution time. Also at +present there is no point in enabling caching for images that are less than +or equal to 524288 bytes, i.e. the size of the test image dev$ypix, as the +default image i/o buffer is exactly that size. However if the size of dev$ypix +is doubled by converting it to a real image with the chpixtype task then the +effect of caching in interactive is can be quite noticeable if measurements +of objects in the top and bottom halves of the image are alternated. + +The output PSF image \fIpsfimage\fR is normally a 2D image containing the +image header parameters, "XPSF", "YPSF", "PSFMAG" and "PSFRAD" which define the +centroid, magnitude and size of the PSF model, the parameters "FUNCTION", +"PSFHEIGH", "NPARS", and "PAR#" which define the analytic component of the PSF, +and a single look-up table of residuals from the analytic fit subsampled by a +factor of 2 with respect to the parent image. + +If the DAOPARS parameter \fIvarorder\fR = -1, the PSF is fit by the analytic +function and \fIpsfimage\fR has no pixel file. + +If the DAOPARS parameter \fIvarorder\fR = 1 or 2, then two or five additional +lookup tables are computed and \fIpsfimage\fR is a 3D image with 3 or 6 planes +respectively. The first two additional look-up tables contain the first +derivatives of the PSF wrt the x and y positions in the image (varorder = 1), +and the next three contains the second derivatives with respect to x ** 2, xy, +and y ** 2 (varorder = 2). + +The positions and magnitudes of each of the stars contributing to the PSF model +are also stored in the PSF image header. + +\fIGroupfile\fR contains a list of the PSF stars, their nearest neighbors, and +friends of the neighbors. A neighbor is defined to be any star within a +distance of 1.5 * \fIpsfrad\fR / \fIscale\fR + 2.0 * \fIfitrad\fR / +\fIscale\fR + 1 pixels of the PSF star. Friends of the neighbors are defined +to be any stars within 2.0 * \fIfitrad\fR / \fIscale\fR + 1.0 of a neighbor +star. \fIFitrad\fR and \fIpsfrad\fR are respectively the fitting radius and psf +radius parameters in the DAOPARS task. \fIScale\fR is the scale factor defined +in the DATAPARS task. + +.ih +CURSOR COMMANDS + +The following cursor commands are available once the image cursor has +been activated. + +.nf + Keystroke Commands + +? Print help +p Print photometry for star nearest the cursor +l List the current psf stars +a Add star nearest cursor to psf star list +f Fit the psf +r Review the fit for all the psf stars +s Subtract fitted psf from psf star nearest cursor +d Delete psf star nearest cursor from psf star list +w Write the psf to the psf image +z Rebuild the psf from scratch +q Quit task + + Colon Commands + +:p [n] Print photometry for star n +:a [n] Add star n to psf star list +:d [n] Delete star n from psf star list +:s [n] Subtract fitted psf from psf star n + + Colon Parameter Editing Commands + +# Data dependent parameters which affect the psf computation + +:scale [value] Show/set the image scale (units / pixel) +:fwhmpsf [value] Show/set the fwhm of psf (scale units) +:datamin [value] Show/set the minimum good data value (counts) +:datamax [value] Show/set the maximum good data value (counts) +:matchrad [value] Show/set matching radius (scale units) + +# Psf computation parameters + +:psfimage [name,name] Show/set the psf image and groupfile +:function [string] Show/set the analytic psf function +:varorder [integer] Show/set order of psf function variability +:nclean [integer] Show/set number of cleaning iterations +:saturated [y/n] Show/set the use saturated star flag +:psfrad [value] Show/set the psf radius (scale units) +:fitrad [value] Show/set the fitting radius (scale units) + + +The following cursor commands are available once a star has been selected +and the graphics cursor has been activated. + + Interactive Graphics Keystroke Commands + +? Print help +p Print the photometry for this star +t Print the plot parameters and data minimum and maximum +a Accept star and proceed +d Reject star and select another with image cursor +m Plot the default mesh plot for this star +n Increase vertical angle by 15 degrees (mesh plot only) +s Decrease vertical angle by 15 degrees (mesh plot only) +w Decrease horizontal angle by 15 degrees (mesh plot only) +e Increase horizontal angle by 15 degrees (mesh plot only) +c Plot the default contour plot for this star +r Plot the radial profile for this star + + + Colon Graphics Commands + +:m [val] [val] Set the mesh plot vertical and horizontal viewing angles +:v [val] Set the mesh plot vertical viewing angle +:h [val] Set the mesh plot horizontal viewing angle +:c [val] [val] Set the contour plot floor and ceiling levels +:l [value] Set the contour plot floor level +:u [value] Set the contour plot ceiling level +.fi + +.ih +ALGORITHMS +The PSF is determined from the actual observed brightness values as a function +of x and y +for one or more stars in the frame and stored as a two-component model. +The first component is an analytic function which approximates +the light distribution in the cores of the PSF stars. There are +currently 6 choices for the analytic component of the model: +"gauss", "moffat15", "moffat25", "lorentz", "penny1", and "penny2". +The parameters of the analytic component of the psf model are stored +in the psf image header parameters "FUNCTION", "PSFHEIGH", "NPARS", +and "PARN". The magnitude, size, and centroid of the PSF are stored +in the image header parameters "PSFMAG", "PSFRAD", +"XPSF", "and "YPSF". If \fImatchbyid\fR is "no" or there is no input psf star list "PSFMAG" is +set to the magnitude of the first PSF star in the input photometry file. If \fImatchbyid\fR +is "yes", and there is an input psf star list "PSFMAG" is set to the magnitude of the first psf star +in the psf star list. "XPSF" and "YPSF" are the center of the image. +If \fIvarorder\fR >= 0, +the residuals from this fit are stored as a lookup +table with twice the sampling interval of the original image. +This lookup table is used as additive corrections from the integrated +analytic function to actual observed empirical PSF. +The parameters of the analytic function are computed by fitting +all the stars weighted by their signal-to-noise. +so that the signal-to-noise ratio in +the PSF does not deteriorate as fainter stars are added in. The more +crowded the field the more PSF stars are required to lower the noise +generated by neighbor subtraction. + +If the \fIvarorder\fR parameter in the DAOPARS task is set to 1 or 2, two +or five additional lookup +tables containing the first derivatives of the PSF in x and y +and the second order derivatives of the image with respect to +x ** 2, x * y, and y ** 2 are also written. +This model +permits the PSF fitting process to take account of smooth linear +or quadratic changes in the PSF across the frame caused for example by a tilt in +the detector with respect to the optical axis or low order optical +aberrations. +Users of this option should ensure that the PSF varies in a systematic +way across the frame and that the chosen PSF stars span the entire +region of interest in the frame. To avoid mistaking +neighbor stars for variations in the PSF it is recommended that the +first few iterations of PSF be run with a constant PSF. Only after +neighbor stars have been subtracted reasonably cleanly should +the variable PSF option be enabled. + +The brightness of any hypothetical pixel at any arbitrary point within +the PSF is computed as follows. The analytic function +is integrated over the area of the pixel, a correction is determined +by bicubic interpolation within the lookup table and added to the +integral. Since the values in the table of residuals differ by smaller +amounts between adjacent grid points than the original brightness data +would have, the errors in the interpolation are much less than they would +have been if one had tried to interpolate directly within the original +data. + +.ih +GUIDE TO COMPUTING A PSF IN A CROWDED FIELD + +The following is a rough guide to the methodology of computing the +PSF in a crowded field. The procedure outlined below assumes +that the user can either make use of the IRAF display facilities or +has access to a local display program. At a minimum the display program +should be able to display an image, read back the coordinates of objects in the +image, and mark objects in the image. + +The crowded field PSF fitting procedure makes use of many of the +DAOPHOT tasks. Details on the setup and operation of each task can be found +in the appropriate manual pages. + +.ls [1] +RUN THE DAOFIND and PHOT TASKS ON THE IMAGE OF INTEREST. +.le +.ls [2] +EXAMINE THE IMAGE. Load the image on the display with the IRAF display task. +Using the display itself, the DAOEDIT task, or the IRAF IMEXAMINE task, estimate the radius +at which +the stellar light distribution disappears into the noise for the +brightest candidate PSF star. Call this parameter \fIpsfrad\fR and record it. +Mark the objects detected by DAOFIND with dots on the image display using the +IRAF TVMARK +task. Users at sites with display devices not currently supported by +IRAF should substitute their local versions of DISPLAY and TVMARK. +.le +.ls [3] +SELECT CANDIDATE PSF STARS. +Good PSF stars should have no neighbors +within the fitting radius stored in the DAOPARS task parameter \fIfitrad\fR. +In addition all stars within 1.5 times the psf radius, +(stored in the DAOPARS task parameter +\fIpsfrad\fR), should be significantly fainter than the candidate star. +There should be no bad columns, bad rows or blemishes +near the candidate star. A sufficient number of stars should be +selected in order to reduce the increased noise resulting from the +neighbor subtraction process. Users of the variable PSF option should +take care that the list of PSF stars span the area of interest on the +image. Twenty-five to thirty stars is not unreasonable in this case. + +The task PSTSELECT can be used to preselect candidate PSF stars. +These candidate PSF stars can be marked on the image display using the +PDUMP, and TVMARK tasks. Be sure to mark the PSF stars in another +color from the stars found by DAOFIND. Stars can be added to or +subtracted from this list interactively when PSF is run. +.le +.ls [4] +EXAMINE THE PSF STARS FOR NEIGHBORS MISSED BY DAOFIND AND ADD THESE TO +THE PHOT FILE. +Examine the vicinity of the PSF stars on the display checking for neighbor +stars which do not have dots on them indicating that they were +missed by DAOFIND. +If IRAF supports the local display device simply run PHOT interactively +selecting the missing stars with the image cursor. +Be sure to use the same set of PHOT parameters used in step [1] with +the exception of the CENTERPARS +task parameter \fIcalgorithm\fR which should be temporarily set to "centroid". +If IRAF does not support the +local display generate a list of the approximate coordinates of the +missing stars. +Run PHOT in batch mode with this coordinate list as input and with the +parameters set as described above. +Create a new PHOT file by using PCONCAT to add the new PHOT output to the +PHOT output from [1] and renumber using PRENUMBER. Do not resort. +.le +.ls [5] +ESTIMATE OF THE PSF. +Run PSF using the combined PHOT output from [4] and +the list of candidate stars from [3]. +Write out the PSF image (extension .psf.#) and the psf group file +(extension .psg.#). The PSF image is the current estimate of the PSF. +.le +.ls [6] +FIT ALL THE STARS IN EACH PSF STAR GROUP IN THE ORIGINAL IMAGE. +Run NSTAR on the image using the output group file (extension .psg.#) +of [5] as the input photometry list. To help prevent the bumps in the initial +PSF from interfering with the profile fits in NSTAR, it may +be necessary to temporarily set the psf radius, +\fIpsfrad\fR in the DAOPARS task, +to about one pixel greater than the separation of the nearest neighbor +to a PSF star. +The fitting radius, \fIfitrad\fR in the +DAOPARS task, should be sufficiently large to include enough +pixels for a good fit but not so large as to include any neighbors +inside the fitting radius. +.le +.ls [7] +SUBTRACT ALL THE FITTED STARS FROM THE ORIGINAL IMAGE. +Run SUBSTAR to subtract the NSTAR results from the original image. +Use the IRAF DISPLAY task or the local display program to display +the subtracted image. If you decreased the value of \fIpsfrad\fR +in [6] use this smaller value when you subtract as well. +.le +.ls [8] +CHECK FOR PREVIOUSLY INVISIBLE FAINT COMPANIONS. +Check to see whether the PSF stars and neighbors subtracted +cleanly or whether there are faint companions that were not previously +visible before. +.le +.ls [9] +APPEND THESE COMPANIONS TO THE PHOT FILE. +Run PHOT on the faint companions in the subtracted image +and append the results to the PHOT file created in [4] using PCONCAT. +Renumber the stars using PRENUMBER. +.le +.ls [10] +SUBTRACT ALL THE PSF NEIGHBOR STARS FROM THE ORIGINAL IMAGE. +Edit the nstar output file (extension .nst.#) removing all the PSF stars +from the file. The PSF stars is the first one in each group. In the +near future this will be done with the PEXAMINE task but at the +moment the text editor can be used for text databases and the TTOOLS +package task TEDIT can be used for tables. PSELECT can also be used +to remove stars with specific id numbers. Run SUBSTAR using the edited +nstar output file as input. +.le +.ls [11] +RECOMPUTE THE PSF. +Run PSF on the subtracted image from [10] using the PHOT file from [9] +as the input stellar photometry file. +Temporarily set the minimum good data value, the \fIdatamin\fR parameter +in the DATAPARS task to a large negative number, to avoid the +enhanced noise where the +stars were subtracted from triggering the bad pixel detector in PSF. +A new psf (extension .psf.#) and new psf group file (extension .psg.#) +will be created. Be sure to increase the \fIpsfrad\fR value to the +original large value found in [2]. +.le +.ls [12] +RERUN NSTAR. +Rerun NSTAR on the original image with the newly created group file +(extension .psg.#) as the input stellar photometry file and the newly +computed PSF image (extension .psf.#). +It should not be necessary to reduce the psf radius as in [6] +but the fitting radius should be left at a generous number. +.le +.ls [13] +REPEAT STEPS [7-12] UNTIL THE PSF FIT IS ACCEPTABLE. +If any neighbors are still visible iterate on this process by repeating +steps [7] to [12] until the neighbors completely disappear. The main +point to remember is that each time through the loop the PSF is obtained +from an image in which the neighbors but not the PSF stars have been +subtracted out while NSTAR and SUBSTAR should be run on the original +picture with all the stars still in it. +.le + +.ih +EXAMPLES + +1. Compute the PSF for the image dev$ypix. Select stars using the display and +the image cursor and show plots of the data and the residuals from the fit +for each star. Good stars for making the PSF model can be found at (442,410), +(348,189), and (379,67). + +.nf + da> daofind dev$ypix default fwhmpsf=2.5 sigma=5.0 threshold=20.0 + + ... answer verify prompts + + ... find stars in the image + + ... answer will appear in ypix.coo.1 + + da> phot dev$ypix default default annulus=10. dannulus=5. \ + apertures = 5.0 + + ... answer verify prompts + + ... do aperture photometry on the detected stars + + ... answer will appear in ypix.mag.1 + + da> display dev$ypix 1 + + ... display the image + + da> psf dev$ypix default "" default default default psfrad=9.0 \ + fitrad=3.0 mkstars=yes display=imdr + + ... verify the critical parameters + + ... move the image cursor to a candidate star and hit the a key, + a plot of the stellar data appears + + ... type ? for a listing of the graphics cursor menu + + ... type a to accept the star, d to reject it + + ... move to the next candidate stars and repeat the previous + steps + + ... type l to list all the psf stars + + ... type f to fit the psf + + ... move cursor to first psf star and type s to see residuals, + repeat for all the psf stars + + ... type w to save the PSF model + + ... type q to quit, and q again to confirm + + ... the output will appear in ypix.psf.1.imh, ypix.pst.1 and + ypix.psg.1 +.fi + + +2. Run PSF non-interactively using the photometry file and psf star file +created in the previous example. + +.nf + da> psf dev$ypix default default default default default \ + psfrad=9.0 fitrad=3.0 interactive- plotfile=psf.plots + + ... the output will appear in ypix.psf.2, ypix.psg.2, and + ypix.pst.2 + + da> gkidir psf.plots + + ... list the plots created by psf + + da> gkiextract psf.plots 1 | stdgraph + + ... display the surface plots of the first psf star + + da> seepsf ypix.psf.2 ypixpsf + + ... convert the sampled PSF look-up table to a PSF image +.fi + + +3. Setup and run PSF interactively without using the image display cursor. +Use the photometry file created in example 1. Before running PSF in this +manner the user should have a list of the candidate PSF star ids. + +.nf + da> show stdimcur + + ... store the default value + + da> set stdimcur = text + + ... define the image cursor to be the standard input + + da> epar psf + + ... edit the psf parameters + + ... move to the datapars line and type :e edit the data dependent + parameters, type :q to quit the datapars menu + + ... move to the daopars line and type :e edit the daophot fitting + parameters, type :q to quit the daopars menu + + ... finish editing the psf parameters + + da> psf dev$ypix default "" default default default \ + plottype=radial + + ... verify critical parameters + + ... type :a # where # stands for the id number of the star, + a plot of the stellar data appears + + ... type a to accept the star, d to reject it + + ... repeat for all the PSF stars + + ... type l to list the psf stars + + ... type f to fit the PSF + + ... type :s # where # stands for the id of the psf star, a plot + of the model residuals appears + + ... type w to save the PSF + + ... type q to quit PSF and q again to confirm the quit + + ... the output will appear in ypix.psf.3, ypix.pst.3, ypix.psg.3 + + da> set stdimcur = stdimage + + ... reset the image cursor +.fi + + +4. Run PSF in non-interactive mode using an image cursor command file of +instructions called icmds. + +.nf + da> type icmds + :a 106 + :a 24 + :a 16 + :a 68 + f + w + q + + da> psf dev$ypix default "" default default default \ + icommands=icmds + + ... verify the critical parameters + + ... the PSF will be constructed from stars 106, 24, 16, 68 + in the input photometry file + + ... the output will appear in ypix.psf.4, ypix.pst.4, ypix.psg.4 + +.fi + + +.ih +TIME REQUIREMENTS +.ih +BUGS +.ih +SEE ALSO +datapars,daopars,pstselect,seepsf +.endhelp diff --git a/noao/digiphot/daophot/doc/pstselect.hlp b/noao/digiphot/daophot/doc/pstselect.hlp new file mode 100644 index 00000000..2dd110bd --- /dev/null +++ b/noao/digiphot/daophot/doc/pstselect.hlp @@ -0,0 +1,418 @@ +.help pstselect May00 noao.digiphot.daophot +.ih +NAME +pstselect -- select candidate psf stars from a photometry file +.ih +USAGE +pstselect image photfile pstfile maxnpsf +.ih +PARAMETERS +.ls image +The list of images containing the candidate psf stars. +.le +.ls photfile +The list of input photometry files. The number of photometry files must +be equal to the number of input images. If photfile is "default", "dir$default", +or a directory specification PSTSELECT searches for a file called +dir$image.mag.# where # is the highest available version number for the file. +Photfile is normally the output of the PHOT task but may also be the output +of the PSF, PEAK, NSTAR and ALLSTAR tasks. Photfile may be a +text file or an STSDAS binary table. +.le +.ls pstfile +The list of output psf star photometry files. There must be one output +psf star photometry file for every input image. If pstfile is "default", +"dir$default", or a directory specification then PSTSELECT writes +a file called dir$image.pst.# where # is the next available version number. +Pstfile inherits its file type, it may be either an APPHOT/DAOPHOT +text or STSDAS binary file, from photfile. +.le +.ls maxnpsf = 25 +The maximum number of candidate psf stars to be selected. +.le +.ls mkstars = no +Mark the selected or deleted psf stars on the image display ? +.le +.ls plotfile = "" +The name of the output file containing mesh, contour, or profile plots of the +selected PSF stars. If plotfile is undefined no plot file is created; otherwise +a mesh, contour, or profile plot is written to this file for each PSF star +selected. Plotfile is opened in append mode and may become very large. +.le +.ls datapars = "" +The name of the file containing the data dependent parameters. The parameter +\fIscale\fR is located here. If \fIdatapars\fR is undefined then the default +parameter set in uparm directory is used. +.le +.ls daopars = "" +The name of the file containing the daophot fitting parameters. The parameters +\fIpsfrad\fR and \fIfitrad\fR are located here. If \fIdaopars\fR is undefined +then the default parameter set in uparm directory is used. +.le +.ls interactive = no +Select the psf stars interactively ? If interactive = yes and icommands is +undefined, PSTSELECT reads in the star list from \fIphotfile\fR, sorts the +stars by magnitude and waits for commands from the user. If interactive = no +and icommands="", PSTSELECT selects candidate PSF stars from \fIphotfile\fR +automatically. If icommands is not undefined then interactive is automatically +set to "no", and commands are read from the image cursor command file. +.le +.ls plottype = "mesh" +The default plot type displayed when a psf star is selected interactively. +The choices are "mesh", "contour", or "radial". +.le +.ls icommands = "" +The image display cursor or image cursor command file. +.le +.ls gcommands = "" +The graphics cursor or graphics cursor command file. +.le +.ls wcsin = ")_.wcsin", wcsout = ")_.wcsout" +The coordinate system of the input coordinates read from \fIphotfile\fR and +of the output coordinates written to \fIpstfile\fR respectively. The image +header coordinate system is used to transform from the input coordinate +system to the "logical" pixel coordinate system used internally, +and from the internal "logical" pixel coordinate system to the output +coordinate system. The input coordinate system options are "logical", "tv", +"physical", and "world". The output coordinate system options are "logical", +"tv", and "physical". The image cursor coordinate system is assumed to +be the "tv" system. +.ls logical +Logical coordinates are pixel coordinates relative to the current image. +The logical coordinate system is the coordinate system used by the image +input/output routines to access the image data on disk. In the logical +coordinate system the coordinates of the first pixel of a 2D image, e.g. +dev$ypix and a 2D image section, e.g. dev$ypix[200:300,200:300] are +always (1,1). +.le +.ls tv +Tv coordinates are the pixel coordinates used by the display servers. Tv +coordinates include the effects of any input image section, but do not +include the effects of previous linear transformations. If the input +image name does not include an image section, then tv coordinates are +identical to logical coordinates. If the input image name does include a +section, and the input image has not been linearly transformed or copied from +a parent image, tv coordinates are identical to physical coordinates. +In the tv coordinate system the coordinates of the first pixel of a +2D image, e.g. dev$ypix and a 2D image section, e.g. dev$ypix[200:300,200:300] +are (1,1) and (200,200) respectively. +.le +.ls physical +Physical coordinates are pixel coordinates invariant with respect to linear +transformations of the physical image data. For example, if the current image +was created by extracting a section of another image, the physical +coordinates of an object in the current image will be equal to the physical +coordinates of the same object in the parent image, although the logical +coordinates will be different. In the physical coordinate system the +coordinates of the first pixel of a 2D image, e.g. dev$ypix and a 2D +image section, e.g. dev$ypix[200:300,200:300] are (1,1) and (200,200) +respectively. +.le +.ls world +World coordinates are image coordinates in any units which are invariant +with respect to linear transformations of the physical image data. For +example, the ra and dec of an object will always be the same no matter +how the image is linearly transformed. The units of input world coordinates +must be the same as those expected by the image header wcs, e. g. +degrees and degrees for celestial coordinate systems. +.le +The wcsin and wcsout parameters default to the values of the package +parameters of the same name. The default values of the package parameters +wcsin and wcsout are "logical" and "logical" respectively. +.le +.ls cache = ")_.cache" +Cache the image pixels in memory. Cache may be set to the value of the apphot +package parameter (the default), "yes", or "no". By default caching is +disabled. +.le +.ls verify = ")_.verify" +Verify the critical PSTSELECT parameters ? +Verify can be set to the DAOPHOT package parameter value (the default), +"yes", or "no". +.le +.ls update = ")_.update" +Update the algorithm parameters if verify is "yes"? +Update can be set to the DAOPHOT package parameter value (the default), +"yes", or "no". +.le +.ls verbose = ")_.verbose" +Print messages about the progress of the task in non-interactive mode ? +Verbose can be set to the DAOPHOT package parameter value (the default), +"yes", or "no". +.le +.ls +graphics = ")_.graphics" +The default graphics device. Graphics can be set to the default +daophot package parameter value, "yes", or "no". +.le +.ls display = ")_.display" +The default image display device. Display can be set to the DAOPHOT +package parameter value (the default), "yes", or "no". By default graphics +overlay is disabled. Setting display to one of "imdr", "imdg", "imdb", or +"imdy" enables graphics overlay with the IMD graphics kernel. +.le + +.ih +DESCRIPTION + +PSTSELECT reads the input photometry file \fIphotfile\fR, extracts the ID, +XCENTER, YCENTER, MAG, and MSKY fields for up to \fImaxnpsf\fR psf stars, +and the results to \fIpstfile\fR. \fIPstfile\fR automatically inherits the +file format of \fIphotfile\fR. + +The coordinates read from \fIphotfile\fR are assumed to be in coordinate +system defined by \fIwcsin\fR. The options are "logical", "tv", "physical", +and "world" and the transformation from the input coordinate system to +the internal "logical" system is defined by the image coordinate system. +The simplest default is the "logical" pixel system. Users working on with +image sections but importing pixel coordinate lists generated from the parent +image must use the "tv" or "physical" input coordinate systems. + +The coordinates written to \fIpstfile\fR are in the coordinate system defined +by \fIwcsout\fR. The options are "logical", "tv", and "physical". The simplest +default is the "logical" system. Users wishing to correlate the output +coordinates of objects measured in image sections or mosaic pieces with +coordinates in the parent image must use the "tv" or "physical" coordinate +systems. + +After reading the star list from \fIphotfile\fR, PSTSELECT sorts the list in +order of increasing magnitude, after rejecting any stars that have INDEF +valued magnitudes, or which lie less than \fIfitrad\fR / \fIscale\fR +pixels from the edge of the \fIimage\fR. From this list the brightest +\fImaxnpsf\fR stars which have no brighter neighbor stars within (\fIpsfrad\fR + +\fIfitrad\fR) / \fIscale\fR + 1 pixels are selected as candidate psf stars. +\fIPsfrad\fR and \fIfitrad\fR are the psf radius and fitting radius parameters +respectively and are stored in the DAOPARS parameter set. \fIScale\fR is the +image scale parameter and is located in the DATAPARS parameter set. Plots, +either mesh, contour or radial profile depending on the value of +\fIplottype\fR, of the selected stars may be saved in the file \fIplotfile\fR. + +If \fIinteractive\fR = "no", PSTSELECT reads the star list in \fIphotfile\fR, +selects the candidate psf stars as described above, and writes the results to +\fIpstfile\fR automatically. If interactive = "yes", PSTSELECT reads +the star list, selects the candidate psf stars and waits for further +instruction from the user. At this point the user can step through the stars +chosen by PSTSELECT, check their surface, contour, or radial profile plots +for blemishes, neighbors etc, and accept the good candidates and reject +the poor ones, or use the image cursor and/or id number to select psf +stars until a maximum of \fImaxnpsf\fR stars is reached. At any point in +this process a previously selected psf star can be deleted. + +If \fIcache\fR is yes and the host machine physical memory and working set size +are large enough, the input image pixels are cached in memory. If caching +is enabled and PSTSELECT is run interactively the first data access will appear +to take a long time as the entire image must be read in before the data +is actually fetched. All subsequent measurements will be very fast because +PSTSELECT is accessing memory not disk. The point of caching is to speed up +random image access by making the internal image i/o buffers the same size as +the image itself. However if the input object lists are sorted in row order and +sparse caching may actually worsen not improve the execution time. Also at +present there is no point in enabling caching for images that are less than +or equal to 524288 bytes, i.e. the size of the test image dev$ypix, as the +default image i/o buffer is exactly that size. However if the size of dev$ypix +is doubled by converting it to a real image with the chpixtype task then the +effect of caching in interactive is can be quite noticeable if measurements +of objects in the top and bottom halves of the image are alternated. + + +.ih +CURSORS + + The following cursor commands are available once the image cursor + has been activated. + +.nf + + Keystroke Commands + +? Print help +p Print photometry for star nearest the cursor +l List the current psf stars +n Select the next good candidate psf star from the list +a Add star nearest cursor to psf star list +d Delete psf star nearest cursor from psf star list +q Quit task + + Colon Commands + +:p [n] Print photometry for star n +:a [n] Add star n to psf star list +:d [n] Delete star n from psf star list + +The following cursor commands are available once a star has been selected +and the graphics cursor has been activated. + + Interactive Graphics Keystroke Commands + +? Print help +p Print the photometry for this star +t Print the plot parameters and data minimum and maximum +a Accept star and proceed +d Reject star and select another with image cursor +m Plot the default mesh plot for this star +n Increase vertical angle by 15 degrees (mesh plot only) +s Decrease vertical angle by 15 degrees (mesh plot only) +w Decrease horizontal angle by 15 degrees (mesh plot only) +e Increase horizontal angle by 15 degrees (mesh plot only) +c Plot the default contour plot for this star +r Plot the radial profile for this star + + + Colon Graphics Commands + +:m [val] [val] Set the mesh plot vertical and horizontal viewing angles +:v [val] Set the mesh plot vertical viewing angle +:h [val] Set the mesh plot horizontal viewing angle +:c [val] [val] Set the contour plot floor and ceiling levels +:l [value] Set the contour plot floor level +:u [value] Set the contour plot ceiling level +.fi + +.ih +OUTPUT + +If \fIverbose\fR = "yes" a single line is written to the terminal for each +star added to the candidate psf star list. Full output is written to the +file \fIpstfile\fR. At the beginning of this file is a header listing the +values of all the important parameters. For each star included in the candidate +psf star list the following quantities are written. + +.nf + id xcenter ycenter mag msky +.fi + +Id, xcenter, ycenter, mag, and msky are the id, x and y coordinates, +magnitudes and sky values for the candidate psf stars listed in +\fIphotfile\fR. + +.ih +EXAMPLES + +1. Select up to 10 psf stars from the PHOT task output non-interactively. +Save surface plots of the selected stars in the file "psf.plots". + +.nf + da> daofind dev$ypix default fwhmpsf=2.5 sigma=5.0 threshold=20.0 + + ... answer verify prompts + + ... find stars in the image + + ... answer will appear in ypix.coo.1 + + da> phot dev$ypix default default annulus=10. dannulus=5. \ + apertures = 5.0 + + ... answer verify prompts + + ... do aperture photometry on the detected stars + + ... answer will appear in ypix.mag.1 + + da> pstselect dev$ypix default default 10 psfrad=9.0 fitrad=3.0 \ + plotfile=psf.plots + + ... answer verify prompts + + ... select candidate psf stars + + ... the output will appear in ypix.pst.1 + + da> display dev$ypix 1 + + ... display the image + + da> pdump ypix.pst.1 xc,yc yes | tvmark 1 STDIN col=204 + + ... mark the stars + + da> gkiextract psf.plots 1 | stdgraph + + ... make a surface plot of the first candidate psf star +.fi + + +2. Repeat the previous results for an image section while preserving the +coordinate system of the original image. + + +.nf + da> daofind dev$ypix[150:450,150:450] default wcsout=tv fwhmpsf=2.5 \ + sigma=5.0 threshold=20.0 + + ... answer verify prompts + + ... find stars in the image + + ... answer will appear in ypix.coo.2 + + da> phot dev$ypix[150:450,150:450] default default wcsin=tv wcsout=tv \ + annulus=10. dannulus=5. apertures = 5.0 + + ... answer verify prompts + + ... do aperture photometry on the detected stars + + ... answer will appear in ypix.mag.2 + + da> pstselect dev$ypix[150:450,150:450] default default 10 wcsin=tv \ + wcsout=tv psfrad=9.0 fitrad=3.0 plotfile=psf.plots2 + + ... answer verify prompts + + ... select candidate psf stars + + ... the output will appear in ypix.pst.2 + + da> display dev$ypix[150:450,150:450] 1 + + ... display the image + + da> pdump ypix.pst.2 xc,yc yes | tvmark 1 STDIN col=204 + + ... mark the stars + + da> gkiextract psf.plots2 4 | stdgraph + + ... make a surface plot of the 4th candidate psf star +.fi + + +3. Repeat example 1 but run pstselect in interactive mode and do not save the +plots. + +.nf + da> display dev$ypix 1 + + ... display the image + + da> pstselect dev$ypix ypix.mag.1 default 10 psfrad=9. fitrad=3. \ + interactive+ mkstars+ display=imdr + + ... verify the critical parameters as instructed + + ... when the image cursor appears type the n keystroke + command to select the first suitable candidate psf + star, examine its surface plot, and type a or d to + accept or reject the candidate + + ... repeat the previous command until 10 psf stars have + been selected, the end of the star list is reached, + or a sufficient number of stars but fewer than maxnpsf + have been selected + + ... if fewer than maxnpsf stars are found automatically + add psf stars to the list with the a keystroke command + + ... type q to quit + +.fi + +.ih +TIME REQUIREMENTS +.ih +BUGS +.ih +SEE ALSO +datapars,daopars,phot,psf +.endhelp diff --git a/noao/digiphot/daophot/doc/seepsf.hlp b/noao/digiphot/daophot/doc/seepsf.hlp new file mode 100644 index 00000000..ed7a5728 --- /dev/null +++ b/noao/digiphot/daophot/doc/seepsf.hlp @@ -0,0 +1,101 @@ +.help seepsf May00 noao.digiphot.daophot +.ih +NAME +seepsf -- convert a sampled PSF lookup table to a PSF image +.ih +USAGE +seepsf psfimage image +.ih +PARAMETERS +.ls psfimage +The list of input PSF images computed by the PSF task. Each PSF image consists +of the parameters of a 2D analytic function stored in the image header and an +optional sampled lookup table of residuals from that fit stored in the image +pixels. +.le +.ls image +The list of output PSF images consisting of the sum of the analytic function +and the residuals in the lookup table. There must be one output PSF image for +each input PSF image. +.le +.ls dimension = INDEF +The dimensions of the output PSF image. By default \fIimage\fR is a 2D image +with dimensions of N by N where N = 2 * nint (psfrad / scale) + 1 with the +same scale as the original image from which \fIpsfimage\fR was derived. +\fIPsfrad\fR is the PSF fitting radius stored in the \fIpsfimage\fR image +header parameter "PSFRAD". \fIScale\fR is the image scale stored in the image +header parameter "SCALE". +.le +.ls xpsf = INDEF +The x coordinate of the output PSF. \fIXpsf\fR is only used if \fIpsfimage\fR +was computed with the variable PSF parameter \fIvarorder\fR in the DAOPARS task +set to > 0. +.le +.ls ypsf = INDEF +The y coordinate of the output PSF. \fIYpsf\fR is only used if \fIpsfimage\fR +was computed with the variable PSF parameter \fIvarorder\fR in the DAOPARS task +set to > 0. +.le +.ls magnitude = INDEF +The intensity scale of the output PSF. By default the intensity scale is set by +the magnitude of the first star used by the PSF task to compute \fIpsfimage\fR. +This parameter is stored in the keyword "PSFMAG" in \fIpsfimage\fR. +.le +.ih +DESCRIPTION +SEEPSF takes the input PSF \fIpsfimage\fR computed by the PSF task, consisting +of the parameters of a 2D analytic function stored in the image header and an +optional lookup table of residuals from the fit stored in the image pixels, and +computes an output PSF, \fIimage\fR, consisting of the sum of the analytic +function and the residuals. + +By default \fIimage\fR is a 2D image of dimensions N by N where N = 2 * nint +(psfrad) + 1 and the scale of \fIimage\fR is the same as the scale of the +original image from which \fIpsfimage\fR was derived. If \fIdimension\fR is +greater or less than N then the output PSF is block-averaged or subsampled with +respect to the original image. \fIPsfrad\fR is the value of the psf radius +parameter in the task DAOPARS used to compute \fIpsfimage\fR and is stored in +the \fIpsfimage\fR header parameter "PSFRAD". + +If \fIpsfimage\fR was computed with the variable PSF parameter \fIvarorder\fR +set to > 0, then \fIimage\fR is computed at a point (xpsf, ypsf) defined +relative to the original image. By default \fIimage\fR is computed at the +centroid of the PSF defined by the \fIpsfimage\fR header parameters "XPSF" +and "YPSF". + +The intensity scale of \fIimage\fR is determined by the value of \fImagnitude\fR +relative to the magnitude of the PSF. By default the output PSF has the +magnitude of the first PSF star stored in the \fIpsfimage\fR header parameter +"PSFMAG". + +SEEPSF is most commonly used for visualizing the PSF in image scale coordinates +and checking the form of any variability as a function of position. However +\fIimage\fR can also be used as input to other image processing program, for +example it might be used as the kernel in a convolution operation. + +.ih +EXAMPLES + +1. Compute the output PSF in image scale coordinates of PSF function +for image dev$ypix. + +.nf + da> seepsf ypix.psf.3 ypixpsf +.fi + +2. Compute the output PSF in image scale coordinates of the variable +PSF for the image m92b at position (113.63,50.48) pixels relative to the +original image. + +.nf + da> seepsf m92b.psf.2 m92psf xpsf=113.63 ypsf=50.48 +.fi + +.ih +TIME REQUIREMENTS +.ih +BUGS +.ih +SEE ALSO +datapars,daopars,psf +.endhelp diff --git a/noao/digiphot/daophot/doc/setimpars.hlp b/noao/digiphot/daophot/doc/setimpars.hlp new file mode 100644 index 00000000..dad0d4d1 --- /dev/null +++ b/noao/digiphot/daophot/doc/setimpars.hlp @@ -0,0 +1,165 @@ +.help setimpars May00 noao.digiphot.daophot +.ih +NAME +setimpars -- save / restore the daophot parameters for a particular image +.ih +USAGE +setimpars image restore update +.ih +PARAMETERS +.ls image +The image for which the daophot parameters are to be saved or restored. +.le +.ls restore +If restore = yes, parfile is "", and the file "image.pars" exists, SETIMPARS +sets the current algorithm parameters by reading in the file "image.pars". If +parfile is not "", then restore is automatically assumed to be yes. +.le +.ls update +If update = yes, SETIMPARS saves the new current values of the DAOPHOT algorithm +parameters in the file \fIimage.pars\fR and any previously existing file of the same name is overwritten. +.le +.ls review = no +Review and/or edit the values of the parameters in the parameter sets DATAPARS, +FINDPARS, CENTERPARS, FITSKYPARS, PHOTPARS, and DAOPARS by calling up the EPAR +task for each of the named parameter sets in turn? +.le +.ls parfile +The name of the input file containing the values of the DAOPHOT algorithm +parameters to be restored. If defined \fIparfile\fR must have been written +by SETIMPARS. If parfile is null (""), SETIMPARS searches for a file named +\fIimage.pars\fR in the user's current directory. If no file is found, the +DAOPHOT algorithm parameters are restored from the files \fIdatapars\fR, +\fIfindpars\fR, \fIcenterpars\fR, \fIfitskypars\fR, \fIphotpars\fR, and +\fIdaopars\fR. +.le +.ls datapars = "" +The name of the file containing the DATAPARS parameter values. Datapars must be +a named DATAPARS parameter set file written by the EPAR task, or "" in which +case the default DATAPARS parameter set in the user's uparm directory is used. +If the parameter \fIunlearn\fR is "yes" and datapars is "", DATAPARS is +unlearned. +.le +.ls findpars = "" +The name of the file containing the FINDPARS parameter values. Findpars +must be a named FINDPARS parameter set file written by the EPAR task, or "" +in which case the default FINDPARS parameter set in the user's uparm +directory is used. If the parameter \fIunlearn\fR is "yes" and findpars +is "", FINDPARS is unlearned. +.le +.ls centerpars = "" +The name of the file containing the CENTERPARS parameter values. Centerpars +must be a named CENTERPARS parameter set file written by the EPAR task, or "" +in which case the default CENTERPARS parameter set in the user's uparm +directory is used. If the parameter \fIunlearn\fR is "yes" and centerpars +is "", CENTERPARS is unlearned. +.le +.ls fitskypars = "" +The name of the file containing the FITSKYPARS parameter values. Fitskypars +must be a named FITSKYPARS parameter set file written by the EPAR task, or "" +in which case the default FITSKYPARS parameter set in the user's uparm +directory is used. If the parameter \fIunlearn\fR is "yes" and fitskypars +is "", FITSKYPARS is unlearned. +.le +.ls photpars = "" +The name of the file containing the PHOTPARS parameter values. Photpars must be +a named PHOTPARS parameter set file written by the EPAR task, or "" in which +case the default PHOTPARS parameter set in the user's uparm directory is used. +If the parameter \fIunlearn\fR is "yes" and photpars is "", PHOTPARS is +unlearned. +.le +.ls daopars = "" +The name of the file containing the DAOPARS parameter values. Daopars must be a +named DAOPARS parameter set file written by the EPAR task, or "" in which case +the default DAOPARS parameter set in the user's uparm directory is used. If the +parameter \fIunlearn\fR is "yes" and daopars is "", DAOPARS is unlearned. +.le +.ls unlearn = no +Return the values of the parameters in the parameter sets DATAPARS, FINDPARS, +CENTERPARS, FITSKYPARS, PHOTPARS, and DAOPARS to their default values? +.le +.ih +DESCRIPTION + +SETIMPARS saves and restores the DAOPHOT task and algorithm parameters for the +image \fIimage\fR. On startup SETIMPARS initializes all the DAOPHOT package +input and output coordinates and photometry file names, input and output images, +and input and output plot files to their default values or \fIimage\fR whichever +is appropriate. Next SETIMPARS reads in the values of the algorithm parameters +from \fIparfile\fR if it is defined, or from the file \fIimage.pars\fR if it +exists and \fIrestore\fR is "yes", or from the named parameter set files +\fIdatapars\fR, \fIfindpars\fR, \fIcenterpars\fR, \fIfitskypars\fR, +\fIphotpars\fR, and \fIdaopars\fR if they exist, or from the default parameters +sets in the user's uparm directory. If \fIunlearn\fR is "yes", these default +parameter sets are unlearned. + +If \fIreview\fR is "yes", the user can review and or edit the newly set +algorithm parameters in DATAPARS, FINDPARS, CENTERPARS, FITSKYPARS, PHOTPARS, +and DAOPARS using the IRAF EPAR task. + +If \fIupdate\fR is "yes", SETIMPARS saves the new current values of the DAOPHOT +algorithm parameters DATAPARS, FINDPARS, CENTERPARS, FITSKYPARS, PHOTPARS, and +DAOPARS in the file \fIimage.pars\fR. Any previously existing file of the same +name is overwritten. + +.ih +EXAMPLES + +1. Save the current values of the daophot task and algorithm parameters for +the image m92v. + +.nf + da> setimpars m92v no yes + + ... m92v parameters are saved in m92v.pars +.fi + +2. Make some minor alterations in the current values of the m92v algorithm +parameters and save the new parameters set. + +.nf + da> setimpars m92v no yes + + ... m92v parameters are saved in new version of m92v.pars +.fi + +3. Begin work on the image m92b. Initialize the values of the daophot task +and algorithm parameters for m92b using those stored for m92v. After doing +some preliminary editing and reductions for m92b, save the parameters, +and return to work on m92v. + +.nf + da> setimpars m92b yes no parfile=m92v.pars + + ... current parameters for m92v are set using saved + m92v parameters + + da> daoedit m92b + + ... edit the parameters as necessary for the new image + + da> daofind m92b + + ... find the stars in m92b + + da> phot m92b + + ... do the initial photometry for stars in m92b + + da> setimpars m92b no yes + + ... current m92b parameters are saved in m92b.pars + + da> setimpars m92v yes no + + ... m92v parameters are restored from m92v.pars +.fi + +.ih +TIME REQUIREMENTS +.ih +BUGS +.ih +SEE ALSO +daoedit,datapars,findpars,centerpars,fitskypars,photpars,daopars +.endhelp diff --git a/noao/digiphot/daophot/doc/specs/daophot.spc b/noao/digiphot/daophot/doc/specs/daophot.spc new file mode 100644 index 00000000..221630d5 --- /dev/null +++ b/noao/digiphot/daophot/doc/specs/daophot.spc @@ -0,0 +1,1047 @@ +.help daophot Sep87 "Crowded Field Stellar Photometry' +.sh +1. Introduction + + The DAOPHOT package will provide a set of routines for performing +stellar photometry on crowded fields in either interactive or batch mode. +DAOPHOT works by fitting an empirical point spread function (PSF) +to each object in the field +allowing for overlap of closely spaced images. This document presents the +the requirements and specifications for the package and describes some of +the algorithms to be used. Most of the algorithms are described in +the original article by Peter Stetson (1987 P.A.S.P. 99,191). + +.sh +2. Requirements +.ls 4 +.ls (1) +The tasks in the DAOPHOT package shall take as input an IRAF imagefile +containing two-dimensional image data which has been corrected for +pixel to pixel gain variations, high frequency variations in the background, +any nonlinearitys in the data except for those which can be specified as +a lower and/or upper bound, +and any other instrumental defects affecting the intensity value of an +individual pixel. However, it shall be possible to exclude bad pixels, +rows or columns from analysis by DAOPHOT routines in a very crude manner. +.le +.ls (2) +The tasks in the package which produce tabular output shall use the +SDAS Tables for their output and those tasks which read output from other +DAOPHOT tasks will be able to read SDAS Tables. In the future the input/output +shall make use of the DBIO package. +.le +.ls (3) +The DAOPHOT package shall work in conjunction with the APPHOT package produced +at NOAO. DAOPHOT will not have any provision to do aperture photometry of its +own. The output format from DAOPHOT tasks will be consistent with APPHOT. +.le +.ls (4) +Given as input a reduced two-dimensional image which has been processed by the +APPHOT package, the DAOPHOT package shall be able to perform the following +functions: +.ls 4 +.ls o +Interactively define a PSF for the data frame. The PSF will be defined +empirically from one or more stars in the field. The task to determine the +PSF shall be interactive and the user shall be able to use a +graphics terminal and/or an image display device to select the stars which +will make up the PSF. The user will be able to evaluate the PSF through +different means including contour plots, 3-d mesh plots, and displaying the +PSF on an image display device. +The user shall be able to "mask" out parts of the PSF which may be contaminated +by nearby stars, bad pixels etc. Only the non-masked portions of the PSF will +be used in the fitting routines. +.le +.ls o +Fit the PSF simultaneously to groups of stars in the image frame whose +images overlap to some degree. The parameters in the fit shall include the +the object brightness, X and Y position of the star and potentially the sky +background. The sky shall be able to be specified as either a flat uniform +background or a simple tilted planar sky. The photometry routines shall +produce realistic errors in the photometry assuming that realistic numbers +for the characteristics of the data are input. +.le +.ls o +Subtract the fitted stars from the data frame to produce a subtracted +image for further analysis. +.le +.ls o +Add artificial stars to the data frame in order to check accuracy and +completeness in the photometry. The user shall have control over the +number of stars added, the brightness range, the area of the image to contain +the added stars and the noise characteristics of the added stars. +.le +.le +.ls (5) +The DAOPHOT package shall include tasks to inspect and edit the results from the +photometry routines. These shall include tasks such as interactively +rejecting particular stars from the results, +producing plots of errors versus brightness, errors versus position etc. +.le +.ls (6) +The DAOPHOT package shall provide utility packages to handle the output +data from the fitting routines. These shall include such tasks as +aperture growth curves, photometric calibrations, color-magnitude and +color-color diagrams. +.le +.ls (7) +The DAOPHOT routines shall optionally keep a history file to keep +track of the processing done on the images. This will include the values of +various parameters used in the various tasks of the DAOPHOT package. +.le +.ls (8) +The tasks shall be able to be run in batch mode as well as interative +mode. In batch mode use of a graphics terminal or image display shall not +be required. +.le +.ls (9) +The DAOPHOT 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 Limitations of the Initial DAOPHOT Package + +The DAOPHOT package shall perform PSF fitting photometry with the following +restrictions: +.ls +.ls (1) +The PSF used will be determined empirically and analytic specification of +the PSF will not be possible. This restricts the use of DAOPHOT to image +data which is not too badly undersampled. +.le +.ls (2) +There will be an upper limit to the number of stars for which the PSF will +be fit simultaneously. The initial version of DAOPHOT will have this limit +set to 60 stars. +.le +.ls (3) +The initial version of DAOPHOT will not have the sky included as a parameter +in the fitting routines. +.le +.ls (4) +Initially the use will not be able to mask out bad portions of the PSF for +fitting. +.le +.le + +.sh +3. Specifications + + The DAOPHOT package performs stellar photometry on digital data, maintained +as IRAF image files. DAOPHOT performs this photometry by fitting the PSF +to the stellar images in the image file. DAOPHOT works by fitting the PSF to +a maximum number of stars simultaneously thus allowing for overlapping images. +Input to the package consists of an imagefile and the output from the APPHOT +package, which contains simple aperture photometry for the objects which have +been identified in the image frame, and numerous parameters controlling the +analysis algorithms. Output from the analysis tasks consists of tabular data +containing the results of the analysis routines. The output will be in the +form of SDAS tables and will thus be able to be manipulated by various +other utility tasks available in IRAF. + +The CL callable part of the DAOPHOT package consists of the following routines: + +.ks +.nf + addstar -- adds synthetic stars to an image file + allstar -- fits multiple, overlapping PSFs to star images + *calibrate -- apply photometric calibration + *cmd -- color-magnitude, color-color diagrams + daopars -- DAOPHOT pset parameters + examine -- interactively examine/edit photometry results + group -- divides stars into natural groupings + *growth -- aperture growth curves <--> PSF magnitudes + peak -- fit PSF to single stars in an image file + psf -- interactively construct a PSF for the frame + nstar -- fits multiple, overlapping PSFs to star images + seepsf -- converts a PSF file into a IRAF image file + select -- selects natural groups with a certain range of sizes + substar -- subtract fitted profiles from an image file +.fi +.ke + +There are routines available in other IRAF/STSDAS tasks for manipulating +SDAS Tables or DBIO. The capabilities inside the DAOPHOT are specifically +suited to dealing with large tables of results from these photometry routines. + +.sh +3.1 Standard Analysis Procedures + + Before performing DAOPHOT photometry one must perform certain other tasks +beforehand. This includes using the APPHOT package to produce an object list +and aperture photometry for objects in this list. The DAOPHOT package contains +an additional object finder but one must use APPHOT to obtain the aperture +photometry results. The standard analysis procedure, including APPHOT, is as +follows: +.ls +.ls (1) +Use an object finder to produce a list of object coordinates. This may be done +in many ways: +.ls +.ls o +By using the interactive cusrsor routines available elsewhere in IRAF and +redirecting the output into a list file. +.le +.ls o +By transforming an existing list using an existing IRAF task or the OFFSET +task in the DAOPHOT package. +.le +.ls o +By using an automatic object finding procedure such as the one available +in the APPHOT package or the one in the DAOPHOT package. +.le +.ls o +By any other program which generates a list of objects in suitable format (SDAS +Tables) for input to the APPHOT routines. +.le +.le +.ls (2) +The APPHOT package is run to measure the objects identified in the above +step. One should refer to the APPHOT documentation to understand the +algorithms and procedures which are used in APPHOT. +.le +.ls (3) +One needs to set up the parameters in the analysis routines for this particular +image file. OPTIONS allows you to set such parameters as the number of +electrons/ADC, the fitting radius, and the radius within which the PSF +is defined. +.le +.ls (4) +The next step is to produce a PSF for the image file currently being processed. +In crowed fields this is a tricky, iterative procedure which should be done very +carefully. This is best done using a graphics terminal and/or an image display +device. +.le +.ls (5) +If one plans on using NSTAR, then the GROUP task must be run. This task +divides the stars in the output from the APPHOT into natural groups. The size +of the groups produced depends upon how crowded the field is and what degree of +overlap of the images one considers. +.le +.ls (6) +Use either NSTAR, if you have grouped the objects using GROUP, or +ALLSTAR which will dynamically group the stars as the image file is +processed. These routines will produce the objects' positions and +intrumental magnitudes by means of multiple-profile fits. +.le +.ls (7) +Use SUBSTAR to subtract the fitted profiles from the image file, thus producing +a new image file containing the fitting residuals. This will usually contain +many stars which were missed in the original identification because they lie +in the wings of brighter objects. +.le +.ls (8) +One now basically runs through steps (1) - (6) one or more times, +merging the identified object lists each time to produce a master object list, +until one is satisfied with the final results. There are many subtlties in this +procedure which are described in the DAOPHOT User's Manual. +.le +.ls (9) +After obtaining the photometry results one may edit the results by throwing out +those results which do not meet certain criteria. EXAMINE is an interactive +task which allows the user to examine the results for each individual object +in the list and either accept or reject that object. There are also routines +available for courser rejection of results, e.g. reject all objects with +errors larger than 0.2 magnitudes. +.le +.ls (10) +One may wish to use the tasks to plot up color-color or color-magnitude +diagrams. Other general purpose list processing tools available in +IRAF/SDAS may also be used for analysis of DAOPHOT output. +.le +.le + +.sh +3.2 The ADDSTAR Task + + The function of ADDSTAR is to add synthetic stars to the image file. +These stars may be placed randomly by the computer, placed with a certain +distribution as specifed by the user or at predetermined locations specified +by the user. Likewise the brightness of these added objects may be completely +random or may follow a specified distribution. + +Objects are added by taking the specified PSF, scaling it, and moving it +to the desired location. ADDSTAR will also add Poisson noise to the star +images to make them more realistic. + +.sh +3.2.1 ADDSTAR Parameters + + ADDSTAR has several parameters which control the addition of stars +into a image file. All data dependent parameters are query mode to ensure +that they get set properly for the particular image under consideration. +The data independent parameters are hidden mode, and are given reasonable +default values. The names, datatypes, and default values of the ADDSTAR +parameters are shown below. + +.ks +.nf +Positional or query mode parameters: + + input_image filename + output_image filename + minmag real + maxmag real +.fi +.ke + +.ks +.nf +List structured parameter (filename may be given on command line): + + add_data *imcur +.fi +.ke + +.ks +.nf +Hidden Parameters: + + daopars pset "daophot$daopars.par" + nstar integer 100 + nframe integer 1 + xmin integer 1 + ymin integer 1 + xmax integer NX + ymax integer NY + verbose boolean false +.fi +.ke + +The function and format of each of these parameters is explained in +more detail below. + +.ls +.ls 16 input_image +The name of the image or image section to which artificial stars will be added +.le +.ls output_image +The name of outout image which will contain the added stars. +.le +.ls minmag +The minumum magnitude of artificial star to add to the data. The magnitude +scale is set by the magnitude of the PSF. +.le +.ls maxmag +The maximum magnitude of artificial star to add to the data. The magnitude +scale is set by the magnitude of the PSF. +.le +.ls add_data +This parameter is used to specify a file as input to the ADDSTAR task. This +file should contain centroid positions and magnitudes for the stars you +want to add. It is possible to specify the positions of the added stars +interactively with the image display by setting this parameter to *imcur. +In this case the user is prompted for the magnitude of each star to be added. +If this parameter is the null string then the stars are added in a random +fashion by the ADDSTAR routine. +.le +.ls nstar +The number of artificial stars to add to the input image file. +.le +.ls daopars +This is the name of a file containing parameters which are common to +many DAOPHOT tasks. This pset parameter serves as a pointer to the external +parameter set for the DAOPHOT algorithms. The parameters contained in this +pset and their function are described in section 3.6.1. +.le +.ls nframe +The number of new image files to create. If this parameter is greater +than one then the new image files will use the output image name as +a root and produce image files with '.xxx' appended to the root, where +xxx will range from 001 to nframe. If nframe is one then the output image +name will be used as is. +.le +.ls xmin, ymin, xmax, ymax +These define the subsection of the image in which to add the artificial +stars. The default is to add artificial stars to the complete image. +.le +.ls verbose +Controls the amount of output from the ALLSTAR function. The default is +to have minimal output to STDOUT. +.le +.le + +.sh +3.2.2 ADDSTAR Output + + The output of ADDSTAR consists of two parts, an image file and an +output SDAS Table. The image file is a copy of the input image file but +with the artificial stars generated by ADDSTAR added. The output table +contains the x,y position and magnitude of each of the added stars. When the +nframe parameter is set greater than one then there will be nframe pairs of +output files generated. + +.sh +3.3 ALLSTAR + + ALLSTAR fits multiple, overlapping point-spread functions to stars images +in the input image file. It uses as input the results from APPHOT and an +input PSF and will automatically reduce the entire image performing the necessary +grouping. It will recalculate the grouping after each iteration. ALLSTAR will +also produce the star-subtracted image file. + +.sh +3.3.1 ALLSTAR Parameters + +ALLSTAR has several parameters which control the fitting algorithms. The +names, datatypes, default values for the ALLSTAR parameters are given below. + +.ks +.nf +Positional parameters: + + input_image filename + photometry filename + output filename + sub_image filename +.fi +.ke + +.ks +.nf +Hidden parameters: + + daopars pset "daophot$daopars.par" + max_group integer 60 + redeterm_cent boolean true + max_crit real 2.5 + min_crit real 1.2 + clip_exp integer 6 + clip_range real 2.5 + verbose boolean false +.fi +.ke + +These parameters perform the following functions: + +.ls 4 +.ls 16 input_image +The name of the input image file. +.le +.ls photometry +The name of the input photometry SDAS table. This may contain output from either +the APPHOT package or from NSTAR or previous ALLSTAR runs. +.le +.ls output +The name of the SDAS table to contain the results of the psf fittting. +.le +.ls sub_image +The name of the output image file which will have all of the fitted stars +subtracted from it. If this file is the null string then no star-subtracted +image file will be produced. +.le +.ls daopars +The pset parameter file containing the DAOPHOT parameter set. +.le +.ls max_group +The maximum size group which ALLSTAR will process. The absolute maximum +is 60 stars. +.le +.ls redeterm_cent +If true then the centers of the stars are redetermined before each +iteration. +.le +.ls max_crit +The initial value which ALLSTAR uses as the critical separation for +use in grouping stars together. For groups larger than "max_group" ALLSTAR +will use progressively smaller values for the critical separation until the +group breaks up into units containing fewer than "max_group" stars or until +the value of "min_crit" is reached. +.le +.ls min_crit +The smallest value of the critical separation which ALLSTAR will use in +grouping stars together. +.le +.ls clip_exp, clip_range +These parameters are used to "resist bad data". These two +parameters control the weighting of each pixel as a function of it's +residual from the fit. Clip_range us variable "a" and clip_exp is +variable "b" in the paper by Stetson (P.A.S.P. 99, 191) +.le +.le + +.sh +3.3.2 The ALLSTAR PSF Fitting Algorithm + + The algorithms which ALLSTAR uses to do the psf fitting photometry are +very nearly the same as those used by NSTAR. One is referred to Stetson, +P.A.S.P. 99, 191, for the details on the various fitting, star rejection, +and weighting algorithms used in this task. +.sh +3.3.3 The Output from ALLSTAR + + The output from ALLSTAR consists of three parts. There is the output +photometry results, an SDAS Table, and a subtracted image file. The subtracted +image file is a copy of the input image file minus the fitted stars. + +For each object processed by ALLSTAR there is one row in the output SDAS +Table. Each measured object will have entries for the following items: + +.nf + star, x, y, mag, magerr, sky, niter, chi, sharp + +where + + star star ID number + x,y coordinates of the stellar centroid + mag magnitude relative to the magnitude of the PSF star + magerr estimated standard error of the star's magnitude + sky estimated sky as returned by APPHOT + niter number of iterations for convergence + chi observed pixel to pixel scatter DIVIDED BY the expected + pixel to pixel scatter + sharp an index describing the spatial distribution of the residuals + around the star. Objects with SHARP significantly greater + than zero are extended (possibly galaxies), while objects with + SHARP significantly less than zero may be bad pixels or cosmic + rays +.fi + +Other noteworthy pieces of information will be stored in the output SDAS +Table header. This includes such things as the time and date of processing, +the name of the PSF file, the name of the input photometry file, the +fitting radius etc. + +.sh +3.4 The CALIBRATE Task + +.sh +3.5 The CMD Task + +.sh +3.6 The DAOPARS Task + + This is a pset-task which is used to describe a particular image file +for use with the DAOPHOT package. This pset contains parameters which describe the +data, e.g. the read out noise, the background sky value, the number of photons +per ADC unit, etc., and also parameters which control the DAOPHOT tasks, e.g. +the fitting radius to use. The parameters in this pset are used by several +DAOPHOT tasks, hence their grouping into a pset. + +.sh +3.6.1 daopars Parameters + + The parameters in this task either describe the data in +a particular image file +or are parameters which are used by more algorithms in more than one +DAOPHOT task. The following parameters make up this pset: + +.ks +.nf + + fitrad real 2.5 (pixels) + psfrad real 11.0(pixels) + phot_adc real 10.0 + read_noise real 20.0 + max_good real 32766. + min_good real 0.0 + sky_val real 0.0 + numb_exp integer 1 + comb_type string "average" + var_psf boolean false +.fi +.ke + +The function and format of each of these parameters is described below: + +.ls 4 +.ls 16 fitrad +The fitting radius to use in the PEAK, NSTAR, ALLSTAR and PSF tasks. Only +the pixels within one fitting radius are actually used in the fit. This should +normally be on the order of the FWHM of the stellar images. +.le +.ls psfrad +The radius of the circle within which the PSF is defined. This should be +somewhat larger than the actual radius of the brightest star you are +interested in. +.le +.ls maxgood +The maximum data value in ADC units at which the CCD or other detector +is believed to operate linearly. +.le +.ls mingood +The minimum data value in ADC units which should be used as "real" data. +Dead pixels, bad columns etc. in the image file can be excluded from use in +the analysis by setting this parameters properly. Any data value which +falls below this minimum is ignored by DAOPHOT tasks. +.le +.ls sky_val +The typical sky brightness in ADC units for the image file. This parameter is +updated by the SKY task within the DAOPHOT package. +.le +.ls phot_adc +The number of photons per ADC unit of the CCD or other detector. +.le +.ls read_noise +The readout noise in ADC units of the CCD or other detector. +.le +.ls numb_exp +The number of individual exposures which have been combined to produce the +current image file. This number combined with information on whether the +exposures were summed or averaged is used to get a better handle on the +error estimates of the photometry. +.le +.ls comb_type +Describes whether the individual exposures which went into making up this +image file were "summed" or "averaged" +.le +.ls var_psf +Controls whether the shape of the PSF is to be regarded as constant over the +complete image file. Slight and smooth variations can be accomodated by the +DAOPHOT tasks. +.le +.le + + These parameters should be initially set by the user before starting any +analysis with the DAOPHOT package. Each image file may have it's own set of +parameters and these should be stored in separate pset files. +.sh +3.7 The EXAMINE Task + + EXAMINE allows the user to interactively examine the results of the +DAOPHOT reduction and to accept or reject individual stars. EXAMINE will +accept as input the output photometry list from either ALLSTAR or NSTAR. +For each star in the input list the user can examine either a 3-d meshplot +or a contour diagram of both the input image and the star-subtracted image. +The results of the photometry for the star under consideration is also +displayed. + +Two output star lists are produced using this task. One is a list +of stars which have been "accepted" by the user, the other being a list +of stars which have been "rejected". + +If the TV option is selected then both the original image and subtracted +image are displayed on the "stdimage" and the star under consideration is +identified. The user has the ability to blink these two frames to +evaluate the results of the photometry. + +This task is controlled via input from the terminal with various keys +performing a variety of functions. + +.sh +3.7.1 EXAMINE Parameters + There are several parameters which control various aspects of the +EXAMINE task. The parameters control such things as the input photometry +list, the type of graphical display desired and whether to use the +display capabilities. + +.ks +.nf +Query mode parameters: + + phot_list filename + + fwhm real (pixels) + threshold real (in units of sigma) + output_file filename +.fi +.ke + +.sh +3.9 The GROUP Task + + GROUP is used to divide the stars in the image file into natural +groups prior to analysis with NSTAR. GROUP works on the following +principle: if two stars are close enough that the light of one will +influence the profile fit of the other, then they belong in the same +group. + +.sh +3.9.1 GROUP Parameters + + GROUP only has a few parameters which govern its operation. These +are: + +.ks +.nf +Query mode parameters: + + input_image filename + psf_file filename + crit_overlap real + output filename +.fi +.ke + +.ks +.nf +Hidden mode parameters: + + daopars pset "daophot$daopars.par" +.fi +.ke + +These parameters perform the following functions: + +.ls 4 +.ls 16 input_image +The name of the input image file. +.le +.ls psf_file +The name of the file containing the PSF. +.le +.ls crit_overlap +The "critical overlap" before one star is determined to influence +another. When GROUP examines two stars to see whether they might influence +each others' fits, it firts identifies the fainter of the two stars. It then +calculates the brightness of the brighter star at a distanceof one fitting +radius plus one pixel from the center of the fainter. If this brightness is +greater than the "critical overlap" times the random error per pixel, then +the brighter star is deemed to be capable of affecting the photometry of the +fainter, and the two stars are grouped together. +.le +.ls output +The name of the SDAS table which will contain the stellar groups. +.le +.ls daopars +The name of of a pset file containing the daophot parameters. The specific +parameters which are used from this include the following: +.le +.le +.sh +3.10 The GROWTH Task + +.sh +3.11 The OFFSET task + +.sh +3.12 The PEAK Task + + PEAK fits the PSF to a single star. It is useful for sparsely populated +image files where the stars of interest are not blended. In this cases aperture +photometry is often fine and the use of PEAK is of limited interest. This task +is included in the DAOPHOT package mainly for completeness. + +.sh +3.12.1 PEAK Parameters + + The parameters specific to the PEAK task are used for specifying the +input and output from this routine. The names of the parameters and their +functions are: + +.ks +.nf +Positional or query parameters: + + input_image filename + psf_file filename + output filename +.fi +.ke + +.ks +.nf +Hidden parameters: + + daopars pset "daophot$daopars.par" + verbose boolean false +.fi +.ke + +.ls 4 +.ls 16 input_image +The name of the input image file. +.le +.ls psf_file +The name of the input file containing the point-spread function. +.le +.ls output +The name of the SDAS table to contain the output from PEAK. +.le +.ls verbose +If true then PEAK outputs more information about what it is doing. +.le +.ls daopars +The name of a pset file which contains the parameters specific to the +input image file. The parameters which PEAK uses from this pset include: +sthe fitting radius, the maximum and minimum good data value and whether +a variable PSF is to be used. +.le +.le +.sh +3.13 The PSF Task + + The PSF task is used for obtaining the point-spread function which +will be used in the rest of the DAOPHOT reductions. DAOPHOT uses an +empirical point-spread function as opposed to a mathematically defined +function. The PSF is defined from the actual brightness distribution +of one or more stars in the frame under consideration. It is stored as +a two-component model: (1) an analytic Gaussian profile which approximately +matches the core of the point-spread function, and (2) a look-up table of +residuals, which are used as additive corrections to the integrated +analytic Gaussian function. + +The brightness in a hypothetical pixel at an arbitrary point within the +point-spread function is determined in the following manner. First +the bivariate Gaussian function is integrated over the area of the pixel, +and then a correction is determined by double cubic interpolation +within the lookup table, and is added to the integrated intensity. + +The PSF is stored as a binary data file and is in a format specific +to DAOPHOT. The format of this file is very similar to that used by the +VMS version of DAOPHOT but is stored in binary for compactness. +A function is provided to take the PSF and convert it +to a IRAF image file so that it can be manipulated by other IRAF +tasks. + +PSF allows the user to perform most functions from within the interactive +graphics part of its operation. PSF allows the user to modify the +perspective of hist mesh plot, the contouring interval, the PSF radius +etc. from within the PSF interactive graphics. + +.sh +3.13.1 PSF Parameters + + The PSF task has many parameters which specify the input and +output files as well as specifying other information. These are +divided in query mode parameters and hidden parameters. + +.ks +.nf +Positional or query parameters: + + input_image filename + phot_list filename + psf_stars filename + psf_file filename +.fi +.ke + +.ks +.nf +Hidden parameters: + + daopars pset "daophot$daopars.par" + verbose boolean false +.fi +.ke + +.ls 4 +.ls 16 input_image +The name of the input image file. +.le +.ls phot_list +The name of the input file containing the aperture photometry +results for this image frame. +.le +.ls psf_stars +The name of file coordinate file containing the list of stars +to be used as PSF candidates. +.le +.ls psf_file +The name of the output file for storing the PSF. +.le +.ls verbose +If true then PEAK outputs more information about what it is doing. +.le +.ls daopars +The name of a pset file which contains the parameters specific to the +input image file. The parameters which PEAK uses from this pset include: +sthe fitting radius, the maximum and minimum good data value and whether +a variable PSF is to be used. +.le +.le +.sh +3.14 The NSTAR Task + + NSTAR is one of DAOPHOT's multiple, simultaneous, profile-fitting +photometry routine. It is similar to ALLSTAR except that NSTAR must have +the objects grouped (using the GROUP task) and it does not dynamically +alter the groups while running. NSTAR also does not automatically produce the +star subtracted image file. + +.sh +3.14.1 NSTAR Parameters + + There are several parameters which control the function of the +NSTAR task. These are the following: + +.ks +.nf +Positional or Query Parameters: + + input_image filename + psf_file filename + group_file filename + output_file filename +.fi +.ke + +.ks +.nf +Hidden parameters: + + daopars pset "daophot$daopars.par" + verbose boolean false +.fi +.ke + +.sh +3.15 The SEEPSF Task + + The SEEPSF task produces an IRAF image file from the given PSF +file. This allows other IRAF tasks, especially display and plotting tasks, +to use access the point-spread function. The user has the ability to create +any size of image from the PSF enlargements being handled by a number of +different interpolation schemes. + +.sh +3.15.1 SEEPSF Parameters + + The parameters wich control this task are limted. They basically +control the input, output and size of the image. + +.ks +.nf +Positional or Query Parameters: + + psf_file filename + image_name filename + image_size integer +.fi +.ke + +.ks +.nf +Hidden parameters: + + interpolation string "nearest" + boundary string "constant" + constant real 0.0 + daopars pset "daophot$daopars.par" + verbose boolean false +.fi +.ke + +.ls 4 +.ls 16 psf_file +This specifies the input PSF file which is to be transformed into an +IRAF image. +.le +.ls image_name +The name of the output IRAF image. +.le +.ls image_size +The size of the output image in pixels per side. Note that only square PSFs +and PSF images are alllowed. +.le +.ls interpolation +The type of interpolation to be used in expanding the image. The choices +are "nearest" neighbor, "linear" bilinear, "poly3" bicubic polynomial, +"poly5" biquintic polynomial, and "spline3" bicubic spline. +.le +.ls boundary +The type of boundary extension to use for handling references to pixels +outside the bounds of the input image. The choices are: "constant", +"nearest" edge, "reflect" about the boundary and "wrap" to the other side +of the image. +.le +.le +.sh +3.16 The SELECT Task + + The SELECT task is used to select groups of stars with a particular +range of sizes from a group file which has been produced by GROUP. This +task is used when some of the groups in the group file are large than the +maximum allowed in NSTAR, currently 60 stars. + +.sh +3.16.1 SELECT Parameters + + The parameters which control the SELECT task are the following: + +.ks +.nf +Positional or Query Parameters: + + input_group filename + output_group filename + min_group integer + max_group integer +.fi +.ke + +.le 4 +.ls 16 input_group +The input group file which is to be searched for groups within the +limits specified by min_group and max_group. +.le +.ls output_group +The output group file which will consist of groups between 'min_group' +and 'max_group' in size. +.le +.ls min_group +The minimum group size to be extracted from the input group file. +.le +.ls max_group +The maximum group size to be extracted from the input group file. +.le +.le +.sh +3.17 The SKY Task + +.sh +3.18 The SORT Task + +.sh +3.19 The SUBSTAR Task + + The SUBSTAR command takes the point-spread function for an image +frame and a file containing the x,y coordinates and apparent magnitudes +for a group of stars, usually an output file from one of the photometry +routines, shifts and scales the PSF function +according to each position and magnitude, and then subtracts it from the +original image frame. + +.sh +3.19.1 SUBSTAR Parameters + + The parameters for SUBSTAR control the input and output from this +task. + +.ks +.nf +Positional or Query Parameters: + + psf_file filename + phot_file filename + input_image filename + output_image filename +.fi +.ke + +.ks +.nf +Hidden parameters: + + verbose boolean false +.fi +.ke + +.ls 4 +.ls 16 psf_file +The name of the file containing the PSF which is to be used as the template +in the star subtraction. +.le +.ls phot_file +The file containing the photometry results for the stars which are to be +subtracted from the input image. +.le +.ls input_image +The name of the input image file from which the stars are to be subtracted. +.le +.ls output_image +The name of the output image file which will be a copy of the input frame +except for the subtracted stars. +.le +.ls verbose +If this parameter is set to true then more information about the progress +of SUBSTAR is output. +.le +.le +.sh +4.0 Example + +.endhelp diff --git a/noao/digiphot/daophot/doc/specs/daoutils.spc b/noao/digiphot/daophot/doc/specs/daoutils.spc new file mode 100644 index 00000000..d943d63a --- /dev/null +++ b/noao/digiphot/daophot/doc/specs/daoutils.spc @@ -0,0 +1,700 @@ +.help daoutils Jan89 "Utility Package for DAOPHOT" +.sh +1. Introduction + +The DAOUTILS package will provide a set of tools for working +with the output from DAOPHOT. These tools will provide the user with +the ability to select data upon ranges and limits for any of the +fields in a daophot output table. The package will also provide tools +for merging results contained in different output files. + +.sh +2. Requirements +.ls 4 +.ls (1) +The tasks in the DAOUTILS package shall take as input the output ST Tables +from the DAOPHOT tasks. The convert task in the daophot package shall be +used to convert the output from apphot tasks into the proper format for use +with the daoutils package. +.le +.ls (2) +The tasks in the package which produce tabular output shall use the +ST Tables for their output and those tasks which read output from other +DAOUTILS tasks will be able to read ST Tables. +.le +.ls (3) +The DAOUTILS package shall include tasks to inspect and edit the results +from the photometry routines. These shall include tasks such as interactively +rejecting particular stars from the results, +producing plots of errors versus brightness, errors versus position etc. There +will also be a task for merging the results contained in several different +Tables. It shall also be possible to interactively examine the photometry +results with various graphical and/or display tools for inspecting/editing the +results. It shall also be possible to construct growth curves from the +aperture photometry for the purpose of calibrating the daophot magnitudes +to total magnitudes. There shall also be routines for calibrating the +photometry by the use of standard stars. +.le +.ls (4) +The tasks shall be able to be run in batch mode as well as interative +mode. In batch mode use of a graphics terminal or image display shall not +be required. +.le +.ls (5) +The DAOPHOT 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 Limitations of the Initial DAOUTILS Package + +The DAOUTILS package will have the following limitations: +.ls +.ls (1) +The initial version of DAOUTILS will not make direct use of the interactive +image display. It will make use of cursor readback however. +.le +.le + +.sh +3. Specifications + +The DAOUTILS package will take the output from the DAOPOHT package as input +and provide a variety of tools which will allow the use to examine, edit and +calibrate the output from DAOPHOT. The output from DAOUTILS will consist of +ST Tables, graphical displays and printed summaries. + +The CL callable part of the DAOUTILS package will consist of the following +tasks: + +.ks +.nf + merge -- Merge the results from different runs of daophot + daograph -- Graph the results of daophot stored in ST Tables + gtedit -- Interactive graphical data editor + examine -- Interactively examine the output from daophot + growth -- aperture growth curves <--> PSF magnitudes + cmd -- Color-magnitude and color-color plots + calibrate -- do photometric calibration + +.fi +.ke + +In addition the ttools package provided as part of STSDAS provides for +many generic tools for working with the ST Tables are will be usable for +many of the data selection tasks which most users will wish to apply to +daophot output. + +.sh +3.1 The GTEDIT Task + +The user will be able to plot any two columns of a Table versus each other +and with the cursor interactively delete records. The user will move the +graphics cursor near the point on the graph which represents the record +which he wishes to delete from the input record. The user will also be able +to specify 'areas' of the plot for which all records pointed to by points +in the indicated sections will be deleted. The user will also be +able to undelete records. The records will not actually be deleted until the +task ends. The user will also be able to interactively change which columns +are being plotted versus each other. The user will also have the option of +editing the table in place or to create a new output table which will contain +the edited results of the input table. + +.sh +3.1.1 GEDIT Parameters + +GEDIT will have input parameters which control the input and initial +operation of the task. + +.ks +.nf +Positional or query mode parameters: + + input - filename + xcolumn - column name (string) + ycolumn - column name (string) +.fi +.ke + +.ks +.nf +Hidden parameters: + + inplace boolean "false" + output filename "" + reject filename "" +.fi +.ke + +The function and format of these parameters is decsribed in more detail +below. + +.ls +.ls 16 input +The name of the input table which contains the output from DAOPHOT. +.le +.ls xcolumn +The name of the column in the input table which will be used for the +X axis of the plot +.le +.ls ycolumn +The name of the column in the input table which will be used for the +Y axis of the plot +.le +.ls inplace +Controls whether the input table is modified in place or whether a new +table is created. +.le +.ls output +If inplace is false then the value of this parameter will be the name of +the output table which will contain the edited output. +.le +.ls reject +The name of the output file containing those objects which have been +deleted. If this parameter is NULL then the records which have been +deleted are not saved. +.le +.le + +.sh +3.1.2 Interactive GEDIT Commands + +Once GEDIT has plotted the two columns specified as the input there are +several commands available to the user. These allow the user to delete/undelete +points, change which columns are plotted, view a particular record from the +input table and exit GEDIT. + +.ks +.nf +In the interactive mode the following cursor keys are active: + + x -- delete the record represented by the point nearest the cursor + > -- delete all records represented by Y values > than the cursor + < -- delete all records represented by Y values < than the cursor + + -- delete all records represented by X values > than the cursor + - -- delete all records represented by X values < than the cursor + b -- mark the corner of box containing records to be deleted. + u -- undelete the record(s) deleted by the last delete operation + q -- exit GEDIT +.fi +.ke + +.ks +.nf +In addition the following colon commands are available: + + :xcol <name> Use the column <name> as the X axis + :ycol <name> Use the column <name> as the Y axis +.fi +.ke + +.sh +3.1.3 GEDIT OUTPUT + +The output from GEDIT is a direct copy of the input table with the records +which the user marked for deletion removed. If the parameter 'inplace' was +set to true then the edited table replaces the original table, otherwise a +new table is created. Is it important that no records be deleted until the +user exits GEDIT and confirms that the update is to take place. + +.sh +3.2 TGRAPH + +This task is will produce plots from the DAOPHOT output tables. It is similar +to the sgraph task in STSDAS but does not have the option of plotting image +sections. It does have the ability to plot error bars and columns of data from +two different tables. + +The following is the help for sgraph: + +.ih +NAME +graph -- graph one or more lists, image sections, or tables +.ih +USAGE +graph input +.ih +PARAMETERS +.ls input +List of operands to be graphed. May be STDIN, or one or more image +sections, tables and columns, or lists. SDAS table input is specified +by: a table name and column name, a table and two column names, or a +pair of table and column names, separated by white space. +.le +.ls stack = no +If stack = yes, plot multiple curves on separate axes (WCS) stacked +vertically rather than on the same axes. +.le +.ls wx1=0., wx2=0., wy1=0., wy2=0. +The range of user coordinates spanned by the plot. If the range of values +in x or y = 0, the plot is automatically scaled from the minimum to +maximum data value along the degenerate dimension. +.le +.ls vx1=0., vx2=0., vy1=0., vy2=0. +NDC coordinates (0-1) of the device plotting viewport. If not set by +the user, a suitable viewport which allows sufficient room for all labels +is used. +.le +.ls pointmode = no +If \fBpointmode\fR = yes, plot points or markers at data values, rather than +connected lines. +.le +.ls marker = "box" +Marker to be drawn if \fBpointmode\fR = yes. Markers are "point", "box", +"cross", "plus" or "circle". +.le +.ls szmarker = 0.005 +The size of a marker in NDC coordinates (0 to 1 spans the screen). +If zero and the input operand is a list, marker sizes are taken individually +from the third column of each list element. If positive, all markers are +of size \fBszmarker\fR. If negative and the input operand is a list, +the size of a marker is the third column of each list element times the +absolute value of \fBszmarker\fR. +.le +.ls xlabel = "", ylabel = "" +Label for the X-axis or Y-axis. +.le +.ls title = "imtitle" +Plot title. If \fBtitle\fR = "imtitle" +and the first operand in \fBinput\fR is an image, the image title is used +as the plot title. +.le +.ls box = yes +Draw axes at the perimeter of the plotting window. +.le +.ls fill = yes +Fill the output viewport regardless of the device aspect ratio? +.le +.ls axis = 1 +Axis along which the projection is to be computed, if an input operand is +an image section of dimension 2 or higher. Axis 1 is X (line average), +2 is Y (column average), and so on. +.le +.ls erraxis = 0 +If pointmode = no and erraxis is 1 or 2, the axis parallel to which +error bars are plotted (1 ==> X, 2 ==> Y). +.le +.ls errcolumn = "" +The column(s) in the input table to be used as the error amplitude(s). +If one column name, then symmetrical symmetrical error bars are drawn, +centered on the data points with the total size, in WC specified by the +values in the column from the same table specified in parameter input. +Two names specify two table columns for the lower and upper errors, +respectively. +.le +.ls pattern = "solid" +The line pattern for the first curve. Subsequent curves on the same +plot cycle through the set of patterns: solid, dashed, dotted, dotdash. +.le +.ls crvstyle = "straight" +The style of the plotted curve: "straight" is the usual straight +line connection between points, "pseudohist" consists of horizontal +segments at each data point connected by vertical segments, "fullhist" +is a bar graph or histogram style plot. +.le +.ls transpose = no +Swap the X and Y axes of the plot. If enabled, the axes are transposed +after the optional linear transformation of the X-axis. +.le +.ls xflip = no, yflip = no +Flip the axis? That is, plot and label X values increasing right to +left instead of left to right and/or Y values top to bottom instead of +bottom to top. +.le +.ls logx = no, logy = no +Log scale the X or Y axis. Zero or negative values are indefinite and +will not be plotted, but are tolerated. +.le +.ls ticklabels = yes +Label the tick marks. +.le +.ls majrx=5, minrx=5, majry=5, minry=5 +Number of major tick marks on each axis; number of minor tick marks between +major tick marks. Ignored if log scaling is in effect for an axis. +.le +.ls lintran = no +Perform a linear transformation of the X-axis upon input. Used to assign +logical coordinates to the indices of pixel data arrays (image sections). +.le +.ls p1=0, p2=0, q1=0, q2=1 +If \fBlintran\fR is enabled, pixel index P1 is mapped to Q1, and P2 to Q2. +If P1 and P2 are zero, P1 is set to 1 and P2 to the number of pixels in +the input array. +.le +.ls round = no +Extend the axes up to "nice" values. +.le +.ls append = no +Append to an existing plot. +.le +.ls device = "stdgraph" +The output device. +.le +.ih +DESCRIPTION +\fBGraph\fR graphs one or more lists, image sections, or table columns; +lists and image sections may be mixed in the input list at will. If the +curves are not all the same length the plot will be scaled to the +longest curve and all curves will be plotted left justified. If an +image section operand has more than one dimension the projection +(average) along a designated axis will be computed and plotted. By +default, a unique dash pattern is used for each curve, up to a maximum +of 4. + +List input may be taken from the standard input or from a file, +and consists of a sequence of Y values, X and Y values, or X, Y, +and marker size values, one pair of coordinates per line in the list. +Blank lines, comment lines, and extra columns are ignored. +The first element in the list determines whether the list is a Y list +or and X,Y list; it is an error if an X,Y list has fewer than two +coordinates in any element. INDEF valued elements appear as gaps +in the plot. + +SDAS table input is specified by a table name and column name, a table +and two columns, or a pair of table and column names separated by white +space. The table name may be a file name template. Note that this is a +single string, so that it must be quoted if entered on the command line. + +Error bars may be plotted for data from list or table input. Errors may +be in X or in Y and separate upper and lower errors may be specified. +If `pointmode' is "no" then the parameter `erraxis' specifies if the +errors are in X or in Y if its value is 1 or 2, respectively. If +`pointmode' is "no" and `erraxis' is zero, a polyline is plotted (see +below). If the input data come from a list, then the third (size) +column specifies the amplitude of symmetrical error bars. If there is a +fourth column, the third and fourth columns specify the amplitudes of +the lower and upper errors, respectively. If the input data are in a +table, the parameter `errcol' specifies the source of the errors. +If `errcol' contains a single word, it is the column in the same table +as the input data containing the amplitudes of symmetrical errors. If +`errcol' contains two words, they specify the columns in the same table +containing the amplitudes of the lower and upper errors, respectively. +If the X and Y data come from different tables, then `erraxis' specifies +which table contains the error column or columns. Error data may not +come from image data. The `append' parameter may be used +to overplot several curves of different style. + +Different line types and curve styles may be selected. The string +parameter `crvstyle' may take on one of the values: "none", "straight", +"pseudohist", or "fullhist", specifying the style of connections between +data points; the string parameter `pattern' can take on one of the +values "solid", "dashed", "dotted", "dotdash" to indicate the style +of the first line drawn. Subsequent lines drawn on the same graph cycle +the available styles. + +If \fBappend\fR is enabled, previous values for \fBbox\fR, +\fBfill\fR, \fBround\fR, the plotting viewport (\fBvx1\fR, \fBvx2\fR, +\fBvy1\fR, \fBvy2\fR), and the plotting window (\fBwx1\fR, \fBwx2\fR, +\fBwy1\fR, \fBwy2\fR) are used. + +By default, the plot drawn will fill the device viewport, if the viewport +was either specified by the user or automatically calculated by +\fIgraph\fR. Setting +the value of \fBfill\fR to "no" means the viewport will be adjusted so +that equal numbers of data values in x and y will occupy equal lengths +when plotted. That is, when \fBfill = no\fR, a unity aspect ratio is +enforced, and plots +appear square regardless of the device aspect ratio. On devices with non +square full device viewports (e.g., the vt640), a plot drawn by \fIgraph\fR +appears extended in the x direction unless \fBfill\fR = no. + +.ih +EXAMPLES +Plot the output of a list processing filter: + + cl> ... list_filter | graph + +Plot a graph entered interactively from the terminal: + + cl> graph STDIN + +Overplot two lists: + + cl> graph list1,list2 + +Graph line 128 of image "pix": + + cl> graph pix[*,128] + +Graph the average of columns 50 through 100: + + cl> graph pix[50:100,*] axis=2 + +Graph two columns from a table against each other: + + cl> graph "table xcol ycol" + +Graph a list in point plot mode: + + cl> graph list po+ + +Annotate a graph: + +.nf + cl> graph pix[*,10],pix[*,20] xlabel=column\ + >>> ylabel=intensity title="lines 10 and 20 of pix" +.fi + +Direct the graph to the standard plotter device: + + cl> graph list device=stdplot +.ih +BUGS +Indefinites are not recognized when computing image projections. + +End sgraph help. + +.sh +3.3 The MERGE Task + +This task will merge the results from a maximum of four DAOPHOT output +files based upon positional coincidence. This task will work on files +which could have been run images with different scales, orientations etc. +MERGE will need to transform the coordinate systems of the input photometry +lists to a common coordinate system. There will be two ways of inputing the +transformations to be applied to the coordinate lists: 1) Simple X, Y shifts +or 2) transformations as determined by the GEOMAP task. This will allow the +most common cases to handled in a simple way without having to run the GEOMAP +task. + +The user will be able to specify a match radius which will determine how +close to each other two objects must be to be considered a coincidence. +The user will also be able to specify the number of lists an object must +be identified in to be included in the output file. For example, if the +user was merging photometry results from four different output tables +he could request that the output table would contain entries for matches +between any two or more of the four tables. The output Table from MERGE +will simply contain pointers to the corresponding rows of the various +input tables and not contain a copy of the complete row from each table +for those objects which were matched. The user will then run another task, +MSELECT to select the fields he wants from the original photometry files. +This will allow the user to select only the fields he wants and to do the +selection more than once without remerging the individual files. + +.sh +3.3.1 MERGE Parameters + +MERGE shall have parameters which control the input and functioning of the +task. + +.ks +.nf +Positional or query parameters: + + ptable1 -- Input photometry table #1 + ptable2 -- Input photometry table #2 + ptable3 -- Input photometry table #3 + ptable4 -- Input photometry table #4 + matchrad -- Matching radius for coincidence + nmatch -- minimum number of matches to be included in output + merge_table -- output table containing merge pointers +.fi +.ke + +.ks +.nf +Hidden Parameters: + + gmfile12 -- geomap database name for transforming #1 -> #2 + gmrec12 -- geomap database record for transforming #1 -> #2 + gmfile13 -- geomap database name for transforming #1 -> #3 + gmrec13 -- geomap database record for transforming #1 -> #3 + gmfile14 -- geomap database name for transforming #1 -> #4 + gmrec14 -- geomap database record for transforming #1 -> #4 + dx12 -- X offset (x2 - x1) + dy12 -- Y offset (y2 - y1) + dx13 -- X offset (x3 - x1) + dy13 -- Y offset (y3 - y1) + dx14 -- X offset (x4 - x1) + dy14 -- Y offset (y4 - y1) +.fi +.ke + +These parameters perform the following functions: + +.ls 4 +.ls 16 ptable1 +The name of the first input photometry table. This should be a standard +DAOPHOT output table or one whose column names have been modified to agree +with the DAOPHOT standard. +.le +.ls ptable2 +The name of the second input photometry table. +.le +.ls ptable3 +The name of the third input photometry table. +.le +.ls ptable4 +The name of the fourth input photometry table. +.le +.ls matchrad +The matching radius for determining whether two objects should be identified +with the same object and potentially included in the output table. +.le +.ls nmatch +The minumum number of matches among the input photometry files for an object +to be included in the output Table. If there were four input files and +\fInmatch\fR was set to two then an object would be included in the output +if it was matched in files 1/2, 1/3, 1/4, 2/3, 2/4 or 3/4. If \fInmatch\fR +was three then the object would have to be identified in files 1/2/3, +2/3/4, 1/2/4 or 1/3/4 +.le +.ls gmfile12 +The name of the \fIGEOMAP\fR database containing the record which specifies +the transformation between photometry list 2 and photometry list 2 in the +sense of mapping objects in list #2 into the coordinate frame of the +list #1 +.le +.ls gmrec12 +The name of \fIGEOMAP\fR database record within \fIgmfile12\fR which +describes the transformation from coordinate system #2 to system #1 +.le +.ls gmfile13 +The name of the \fIGEOMAP\fR database containing the record which specifies +the transformation between photometry list 3 and photometry list 3 in the +sense of mapping objects in list #3 into the coordinate frame of the +list #1 +.le +.ls gmrec13 +The name of \fIGEOMAP\fR database record within \fIgmfile13\fR which +describes the transformation from coordinate system #3 to system #1 +.le +.ls gmfile14 +The name of the \fIGEOMAP\fR database containing the record which specifies +the transformation between photometry list 4 and photometry list 4 in the +sense of mapping objects in list #4 into the coordinate frame of the +list #1 +.le +.ls gmrec14 +The name of \fIGEOMAP\fR database record within \fIgmfile14\fR which +describes the transformation from coordinate system #4 to system #1 +.le +.ls dx12 +The X offset between coordinate system #2 and coordinate system #1 +in the sense of (x2 - x1). +.le +.ls dy12 +The Y offset between coordinate system #2 and coordinate system #1 +in the sense of (y2 - y1). +.le +.ls dx13 +The X offset between coordinate system #3 and coordinate system #1 +in the sense of (x3 - x1). +.le +.ls dy13 +The Y offset between coordinate system #3 and coordinate system #1 +in the sense of (y3 - y1). +.le +.ls dx14 +The X offset between coordinate system #4 and coordinate system #1 +in the sense of (x4 - x1). +.le +.ls dy14 +The Y offset between coordinate system #4 and coordinate system #1 +in the sense of (y4 - y1). +.le +.le + +If the parameters specifying the \fIGEOMAP\fR database file name for +a particular transformation is empty then the corresponding parameters +describing the transformation in terms of a simple shift are queried. + +.sh +3.3.2 +The Output from MERGE + +\fIMERGE\fR will produce an STSDAS Table as output with the table +containing pointers to records in the input Tables which identify the +objects which are positionally coincident. The output Table will contain +columns with the names \fIpoint0\fR, \fIpoint1\fR, \fIpoint2\fR and +\fIpoint3\fR. If an object is identified in a particular input photometry +list and also meets the \fInmatch\fR criterion then the entry in the +output Table will contain the row number in the corrsponding input Table. +For those objects which are included in the output Table but which are not +identified in a particular input Table the corrsponding entry will be +INDEF. + +.ks +.nf +Sample Output Format (ASCII representation) + + Point0 Point1 Point2 Point3 + + 1 3 INDEF 2 + 3 2 2 4 + 4 5 4 INDEF + INDEF 8 7 6 + + .fi + .ke + + In the above sample the first matched object corrsponds to rows 1, 3 and + 2 in input Tables 0, 1 and 3 respectively. This object was not matched + in input Table 0. + +The header of the Table output by MERGE shall contain the necessary information +for tracking the original data files, the data and time the merge was done etc. +The MSELECT task should check that the original photometry files have not been +modified since MERGE was run to ensure data integrity. + +.sh +3.4 MSELECT + +This task is used to select fields from the photometry Tables which +were used as input to the \fIMERGE\fR task. The output from \fIMERGE\fR +is a set of pointers to the appropriate records in the input tables. +Using \fIMSELECT\fR on an output file from \fIMERGE\fR will produce an +output file which will contain the specified fields for each of the +objects which have been matched. If an object has not been identified +in a particular Table then the values for each output field are set to +INDEF. + +.sh +3.4.1 MSELECT Parameters + +MERGE will have parameters wich will control the input and functioning +of the task. + +.ks +.nf +Positional Parameters: + + input filename "" + fields string "" + output string "" +.fi +.ke + +.ks +.nf +Hidden Parameters: + + tables string "" +.fi +.ke + +These parameters perform the following functions: + +.ls 4 +.ls 16 input +This specifies the input Table which must be an output Table from the +\fIMERGE\fR task. \fIMSELECT\fR will get the names of the actual +photometry Tables from the header of the input merge table. +.le +.ls fields +A list of fields to extract from the input photometry tables. +.le +.ls output +The name of the output table. This table will contain entries for +each of the selected fields of each photometry table. The values for +each field in the output table will be the values of the selected fields +for each of the input photometry tables. For those entries which were not +nmatched the corresponding entries will be INDEF. +.le +.ls tables +This parameter is used to select output for only a subset of the input +photometry tables. +.le + +.endhelp diff --git a/noao/digiphot/daophot/doc/substar.hlp b/noao/digiphot/daophot/doc/substar.hlp new file mode 100644 index 00000000..5de81b85 --- /dev/null +++ b/noao/digiphot/daophot/doc/substar.hlp @@ -0,0 +1,323 @@ +.help substar May00 noao.digiphot.daophot +.ih +NAME +substar -- subtract photometry results from an image +.ih +USAGE +substar image photfile exfile psfimage subimage +.ih +PARAMETERS +.ls image +The list of images from which to subtract the scaled and shifted PSF. +.le +.ls photfile +The list of PSF fitted photometry files. There must be one photometry file +for every input image. If photfile is "default", "dir$default", or a directory +specification, SUBSTAR will look for a file called image.nst.? where the +question mark stands for the highest existing version number. Photfile is +usually the output of the NSTAR task but may also be the output of the PEAK +and ALLSTAR tasks or even the PHOT task. Photfile may be an APPHOT/DAOPHOT text +database or an STSDAS table. +.le +.ls exfile +The list of photometry files containing the ids of stars to be excluded +from the subtraction. Exfile must be undefined or contain one exclude file +for every input image. If exfile is "default", "dir$default", or a directory +specification, SUBSTAR will look for a file called image.pst.? where the ? +mark stands for the highest existing version number. Exfile is usually the +output of the PSTSELECT task but may also be the output of the PEAK, NSTAR and +ALLSTAR tasks or even the PHOT task. Exfile may be an APPHOT/DAOPHOT text +database or an STSDAS table. +.le +.ls psfimage +The list of images containing the PSF models computed by the DAOPHOT PSF task. +The number of PSF images must be equal to the number of input images. If +psfimage is "default", "dir$default", or a directory specification, +then PEAK will look for an image with the name image.psf.?, where +? is the highest existing version number. +.le +.ls subimage +The list of output subtracted images. There must be one output subtracted +image for every input image. If subimage is "default", "dir$default", or a +directory specification, then SUBSTAR will write an image called image.sub.? +where question mark stands for the next available version number. +.le +.ls datapars = "" +The name of the file containing the data dependent parameters. The parameters +\fIscale\fR, \fIdatamin\fR, and \fIdatamax\fR are located here. If datapars +is undefined then the default parameter set in uparm directory +.le +.ls daopars = "" +The name of the file containing the daophot fitting parameters. The parameters +\fIpsfrad\fR and \fIfitrad\fR are located here. If \fIdaopars\fR is undefined +then the default parameter set in uparm directory is used. +.le +.ls wcsin = ")_.wcsin", wcsout = ")_.wcsout", wcspsf = ")_.wcspsf" +The coordinate system of the input coordinates read from \fIphotfile\fR, of the +psf model \fIpsfimage\fR, and of the output coordinates written to +the standard output if \fIverbose\fR = "yes". The image header coordinate +system is used to transform from the input coordinate system to the "logical" +pixel coordinate system used internally, from the internal logical system to +the PSF model system, and from the internal "logical" pixel coordinate system +to the output coordinate system. The input coordinate system options are +"logical", "tv", "physical", and "world". The PSF model and output coordinate +system options are "logical", "tv", and "physical". The image cursor coordinate +system is assumed to be the "tv" system. +.ls logical +Logical coordinates are pixel coordinates relative to the current image. +The logical coordinate system is the coordinate system used by the image +input/output routines to access the image data on disk. In the logical +coordinate system the coordinates of the first pixel of a 2D image, e.g. +dev$ypix and a 2D image section, e.g. dev$ypix[200:300,200:300] are +always (1,1). +.le +.ls tv +Tv coordinates are the pixel coordinates used by the display servers. Tv +coordinates include the effects of any input image section, but do not +include the effects of previous linear transformations. If the input +image name does not include an image section, then tv coordinates are +identical to logical coordinates. If the input image name does include a +section, and the input image has not been linearly transformed or copied from +a parent image, tv coordinates are identical to physical coordinates. +In the tv coordinate system the coordinates of the first pixel of a +2D image, e.g. dev$ypix and a 2D image section, e.g. dev$ypix[200:300,200:300] +are (1,1) and (200,200) respectively. +.le +.ls physical +Physical coordinates are pixel coordinates invariant with respect to linear +transformations of the physical image data. For example, if the current image +was created by extracting a section of another image, the physical +coordinates of an object in the current image will be equal to the physical +coordinates of the same object in the parent image, although the logical +coordinates will be different. In the physical coordinate system the +coordinates of the first pixel of a 2D image, e.g. dev$ypix and a 2D +image section, e.g. dev$ypix[200:300,200:300] are (1,1) and (200,200) +respectively. +.le +.ls world +World coordinates are image coordinates in any units which are invariant +with respect to linear transformations of the physical image data. For +example, the ra and dec of an object will always be the same no matter +how the image is linearly transformed. The units of input world coordinates +must be the same as those expected by the image header wcs, e. g. +degrees and degrees for celestial coordinate systems. +.le +The wcsin, wcspsf, and wcsout parameters default to the values of the package +parameters of the same name. The default values of the package parameters +wcsin, wcspsf, and wcsout are "logical", "physical" and "logical" respectively. +.le +.ls cache = ")_.cache" +Cache the image pixels in memory. Cache may be set to the value of the apphot +package parameter (the default), "yes", or "no". By default caching is +disabled. +.le +.ls verify = ")_.verify" +Verify the critical SUBSTAR task parameters? Verify can be set to the DAOPHOT +package parameter value (the default), "yes", or "no". +.le +.ls update = ")_update" +Update the SUBSTAR task parameters if \fIverify\fR is "yes"? Update can be +set to the default daophot package parameter value, "yes", or "no". +.le +.ls verbose = ")_.verbose" +Print messages about the progress of the task ? Verbose can be set to the +DAOPHOT package parameter value (the default), "yes", or "no". +.le + +.ih +DESCRIPTION +SUBSTAR task takes an input photometry list \fIphotfile\fR containing +the fitted coordinates and magnitudes, and an input PSF \fIpsfimage\fR, and +for each star in the photometry list scales and shifts the PSF and subtracts +it from the input image \fIimage\fR. The final subtracted image is saved in the +output image \fIsubimage\fR. + +The input photometry list can be the output from of the PEAK, NSTAR or ALLSTAR +tasks or even the PHOT task although most people would not want to use the PHOT +output for this purpose. + +Selected stars may be omitted from the subtraction by supplying their ids in +the file \fIexfile\fR. \fIExfile\fR is normally the output the PSTSELECT task +and is used to tell SUBSTAR to subtract the PSF star neighbors, but not the +PSF stars themselves. + +The coordinates read from \fIphotfile\fR are assumed to be in coordinate +system defined by \fIwcsin\fR. The options are "logical", "tv", "physical", +and "world" and the transformation from the input coordinate system to the +internal "logical" system is defined by the image coordinate system. The +simplest default is the "logical" pixel system. Users working on with image +sections but importing pixel coordinate lists generated from the parent image +must use the "tv" or "physical" input coordinate systems. + +The coordinate system of the PSF model is the coordinate system defined by the +\fIwcspsf\fR parameter. Normally the PSF model was derived from the input image +and this parameter default to "logical". However if the PSF model was derived +from a larger image which is a "parent" of the input image, then wcspsf should +be set to "tv" or "physical" depending on the circumstances. + +The coordinates written to the standard output if \fIverbose\fR = yes are in the +coordinate system defined by \fIwcsout\fR. The options are "logical", "tv", +and "physical". The simplest default is the "logical" system. Users wishing to +correlate the output coordinates of objects measured in image sections or +mosaic pieces with coordinates in the parent image must use the "tv" or +"physical" coordinate systems. + +If \fIcache\fR is yes and the host machine physical memory and working set size +are large enough the input and output image pixels are cached in memory. If +caching is enabled and SUBSTAR is run interactively the first subtraction +will appear to take a long time as the entire image must be read in before +the measurement is actually made. All subsequent measurements will be very +fast because SUBSTAR is accessing memory not disk. The point of caching is +to speed up random image access by making the internal image i/o buffers the +same size as the image itself. However if the input object lists are sorted +in row order which SUBSTAR does internally and are sparse caching may +actually worsen not improve the execution time. Also at present there is no +point in enabling caching for images that are less than or equal to 524288 +bytes, i.e. the size of the test image dev$ypix, as the default image i/o +buffer is exactly that size. However if the size of dev$ypix is doubled by +converting it to a real image with the chpixtype task then the effect of +caching in interactive is can be quite noticeable if measurements +of objects in the top and bottom halves of the image are alternated. + + +The SUBSTAR task is most commonly used to check on the quality of the PSF +fitting produced by PEAK and NSTAR, to search for non-stellar objects and close +binary stars, to generate an improved PSF in crowded fields, and to remove +neighbors from bright stars which are to be used to determine aperture +corrections. + +.ih +EXAMPLES + +1. Subtract the NSTAR photometry results for the test image dev$ypix from the +image dev$ypix. + +.nf + da> datapars.epadu = 14.0 + da> datapars.readnoise = 75.0 + + ... set the gain and readout noise for the detector + + da> daofind dev$ypix default fwhmpsf=2.5 sigma=5.0 threshold=20.0 + + ... answer verify prompts + + ... find stars in the image + + ... answer will appear in ypix.coo.1 + + da> phot dev$ypix default default annulus=10. dannulus=5. \ + apertures = 3.0 + + ... answer verify prompts + + ... do aperture photometry on the detected stars + + ... answer will appear in ypix.mag.1 + + da> display dev$ypix 1 + + da> psf dev$ypix default "" default default default psfrad=11.0 \ + fitrad=3.0 mkstars=yes display=imdr + + ... verify the critical parameters + + ... move the image cursor to a candidate star and hit the a key, + a plot of the stellar data appears + + ... type ? for a listing of the graphics cursor menu + + ... type a to accept the star, d to reject it + + ... move to the next candidate stars and repeat the previous + steps + + ... type l to list all the psf stars + + ... type f to fit the psf + + ... move cursor to first psf star and type s to see residuals, + repeat for all the psf stars + + ... type w to save the PSF model + + ... type q to quit, and q again to confirm + + ... the output will appear in ypix.psf.1.imh, ypix.pst.1 and + ypix.psg.1 + + da> group dev$ypix default default default + + ... verify the prompts + + ... the output will appear in ypix.grp.1 + + da> nstar dev$ypix default default default default + + ... verify the prompts + + ... the results will appear in ypix.nst.1 and ypix.nrj.1 + + da> pdump ypix.nst.1 sharpness,chi yes | graph + + ... plot chi versus sharpness, the stars should cluster around + sharpness = 0.0 and chi = 1.0, note that the frame does + not have a lot of stars + + da> substar dev$ypix default "" default default + + ... subtract the fitted stars + + da> display ypix.sub.1 2 + + ... note that the psf stars subtract reasonably well but other + objects which are not stars don't +.fi + + +2. Rerun the previous example on a section of the test image using the group +file and PSF model derived in example 1 for the parent image and writing the +results in the coordinate system of the parent image. + +.nf + da> nstar dev$ypix[150:450,150:450] default default default default \ + wcsin=tv wcspsf=tv wcsout=tv + + ... answer the verify prompts + + ... fit the stars + + ... the results will appear in ypix.nst.2 and ypix.nst.2 + + da> display dev$ypix[150:450,150:450] 1 + + ... display the image + + da> pdump ypix.nst.2 xc,yc yes | tvmark 1 STDIN col=204 + + ... mark the stars + + da> substar dev$ypix ypix.nst.2 "" default default + + ... subtract stars from parent image + + ... the output images is ypix.sub.2 + + + da> substar dev$ypix[150:450,150:450] ypix.nst.2 "" default default \ + wcsin=tv wcspsf=tv wcsout=tv + + ... subtract stars from the nstarinput image + + ... the output images is ypix.sub.3 + +.fi + +.ih +TIME REQUIREMENTS +.ih +BUGS +.ih +SEE ALSO +datapars,daopars,nstar,peak +.endhelp diff --git a/noao/digiphot/daophot/doc/userdocs/daophot.usr.tex b/noao/digiphot/daophot/doc/userdocs/daophot.usr.tex new file mode 100644 index 00000000..ce4ed623 --- /dev/null +++ b/noao/digiphot/daophot/doc/userdocs/daophot.usr.tex @@ -0,0 +1,2005 @@ +%de 21 (summer solstice, midnight, la serena) (this is IT, Phil!) +%more done on Dec 27th or so +%typos fixed 28 Dec 1pm +%more done on Dec 28th (1st 4-m night morning) +%copy xfered from Chile on Jan 1, 1990 +%modifications made after the AAS meeting, Jan 15 1990: +% end itemize problems fixed +% buku aperture photometry stuff added Jan 15/16 +% started to make Lindsey's changes Jan 28th +% Next set of changes made Feb. 18th when we SHOULD have been +% off with marcia having a good time. +% more modifications Monday Feb 19 +% march 20/21 mods made in Boulder----Lindsey's comments +% march 20/21 mods made in Boulder---beginning of JB's comments +% march 27 mods back in Tucson +% may 11th, fixed the sumed/average read-noise problem! +\documentstyle[11pt,moretext]{article} +\begin{document} +\title{A User's Guide to Stellar CCD Photometry with IRAF} +\author{Philip Massey \and Lindsey E. Davis} +\date{March 29, 1990} +\maketitle +\begin{abstract} +This document is intended to guide you through the steps for obtaining +stellar photometry from CCD data using IRAF. It deals both with the +case that the frames are relatively uncrowded (in which case simple +aperture photometry may suffice) and with the case that the frames +are crowded and require more sophisticated point-spread-function +fitting methods (i.e., {\bf daophot}). In addition we show how one +goes about obtaining photometric solutions for the standard stars, and +applying these transformations to instrumental magnitudes. +\end{abstract} +\tableofcontents +\eject +\section{Introduction} +This user's guide deals with both the ``relatively simple" case of +isolated +stars on a CCD frame (standard stars, say, or uncrowded program stars) +and the horrendously more complicated case of crowded field +photometry. We describe here all the steps needed to obtain instrumental +magnitudes and to do the transformation to the standard system. There +are, of course, many possible paths to this goal, and IRAF provides no +lack of options. We have chosen to illuminate a straight road, but many +side trails are yours for the taking, and we will occasionally point +these out (``let many flowers bloom"). This Guide is {\it not} intended +as a reference manual; for that, you have available (a) the various +``help pages" for the routines described herein, (b) ``A User's Guide +to the IRAF APPHOT Package" by Lindsey Davis, and (c) ``A Reference +Guide to the IRAF/DAOPHOT Package" by +Lindsey Davis. (For the ``philosophy" and algorithms of DAOPHOT, see +Stetson 1987 {\it PASP} {\bf 99}, 111.) +What {\it this} manual is intended to be is a real +``user's guide", in which we go through all of the steps necessary to go +from CCD frames to publishable photometry. (N.B.: as of this writing +the IRAF routines for determining the standard transformations and +applying those transformations are still being written.) We outline +a temporary kludge that will work with Peter Stetson's CCDRED VMS +Fortran package. Hopefully the PHOTRED package currently under +development at Cerro Tololo will be available by Spring 1990, and +this manual will then be revised. + +The general steps involved are as follows: (1) fixing the header +information to reflect accurate exposure times and airmasses, +(2) determining and cataloging the characteristics of your data (e.g., +noise, seeing, etc.), +(3) obtaining instrumental magnitudes for all the standard stars +using aperture photometry, (4) obtaining instrumental magnitudes for +your program stars using IRAF/daophot, (5) determining the aperture +correction for your program stars, (6) computing the transformation +equations for the standard star photometry, and (7) applying these +transformations to your program photometry. We choose to illustrate +these reductions using {\it UBV} CCD data obtained with an RCA chip on the 0.9-m +telescope at Cerro Tololo, but the techniques are applicable to data +taken with any detector whose noise characteristics mimic those of a +CCD. + +If you are a brand-new IRAF user we strongly recommend first reading the +document ``A User's Introduction to the IRAF +Command Language" by Shames and Tody, which can be found in Volume 1A +of the 4 blue binders that compose the IRAF documentation. (Actually +if you are a brand-new IRAF user one of us recommends that you find +some simpler task to work on before you tackle digital stellar photometry!) +The procedures described here will work on any system supported by IRAF; +for the purposes of discussion, however, we will assume that you are +using the image display capabilities of a SUN. If this is true you then +may also want to familiarize yourself with the ins and outs of using +the SUN Imtool window; the best description is to be found in ``IRAF +on the SUN". + +We assume that your data has been read onto disk, and that the basic +instrumental signature has been removed; i.e., that you are ready +to do some photometry. If you haven't processed your +data this far yet, we +refer you to ``A User's Guide to Reducing CCD Data with IRAF" by Phil +Massey. + +\section{Getting Started} + +\subsection{Fixing your headers} +You're going to have to this some time or another; why not now? There +are two specific things we may need to fix at this point: (a) Add any +missing header words if you are reducing non-NOAO data, (b) correct the +exposure time for any shutter opening/closing time, and (c) correct the +airmass to the effective middle of the exposure. + +Two things that will be useful to have in your headers are the exposure +time and the airmass. If you are reducing NOAO data then you will +already have the exposure time (although this may need to be corrected +as described in the next paragraph) and enough information for the {\bf +setairmass} task described below to compute the effective airmass of the +observation. You can skip to the ``Correcting the exposure time" +section below. +If +you are reducing non-NOAO data you should examine your header with a + +\centerline{ {\bf imhead} imagename{\bf l+ $|$ page} } + +\noindent +and see exactly what information {\it is} there. If you are lacking the +exposure time you can add this by doing an + +\centerline{ {\bf hedit} imagename{\bf ``ITIME"} value {\bf add+ up+ +ver- show+} } + +\noindent +If you know the effective airmasses you can add an ``AIRMASS" keyword in +the same manner, or if you want to compute the effective airmass +(corrected to mid-exposure) using {\bf setairmass} as described below, +you will need to have the celestial coordinates key words ``RA" and +``DEC", as well as the siderial-time (``ST"), +and preferably the coordinate ``EPOCH" and the date-of-observation +(``DATE-OBS"), all of which should have the form shown in Fig.~\ref{header}. + +You may want to take this opportunity to review the filter numbers in the +headers, and fix any that are wrong. If you are lacking filter numbers +you may want to add them at this point. + +\subsubsection{Correcting the exposure time} +The CTIO 0.9-m has an effective exposure time that is +25-30ms longer than the requested exposure time (Massey et al. 1989 {\it +A.J.} {\bf 97}, 107; Walker 1988 {\it NOAO Newsletter} {\bf No. 13}, +20). First see what "keyword" in your header gives the exposure time: + +\centerline{ +{\bf imhead} imagename{\bf.imh l+ $|$ page} } + +\noindent +will produce a listing such as +given in Figure~\ref{header}. +\begin{figure} +\vspace{3.2in} +\caption{\label{header}Header information for image n602alu.imh}. +\end{figure} +The exposure time keyword in this header is ``ITIME". In this case +we wish to add a new exposure time to each of the headers; we will call +this corrected exposure time +EXPTIME, and make it 25 ms larger than whatever value is listed as +ITIME. To do this we use the {\bf hedit} command as follows: + +\centerline{ +{\bf hedit *.imh EXPTIME ``(ITIME+0.025)" ver- show+ add+}.} + +\noindent +An inspection of the headers will now show a new keyword EXPTIME. +(Walker lists a similar correction for the CTIO 1.5-m shutter, but the +CTIO 4-m P/F shutters have a negligible correction. +The direct CCD shutters on the Kitt Peak CCD cameras give +an additional 3.5ms of integration on the edges but 13.0ms in the +center [e.g., Massey 1985 {\it KPNO Newsletter} {\bf 36}, p. 6]; +if you have any 1 second exposures you had best correct these by +10ms or so if you are interested in 1\% photometry.) + +\subsubsection{Computing the effective airmass} +The task {\bf setairmass} in the {\bf astutil} package will compute +the effective airmass of your exposure, using the header values of RA, +DEC, ST, EPOCH, and DATE-OBS, and whatever you specify for the observatory +latitude. An example is shown in Fig.~\ref{setairmass}. +\begin{figure} +\vspace{2.5in} +\caption{\label{setairmass} The parameter file for {\bf setairmass}.} +\end{figure} +The default for the latitude is usually the IRAF +variable {\bf observatory.latitude}. To by-pass this ``feature", simply +put the correct latitude in the parameter file +(e.g., $-30.1652$ for CTIO, +$+31.963$ for KPNO; $+19.827$ for Mauna Kea.). + +\subsection{{\bf imexamine:} A Useful Tool} + +The {\bf proto} package task {\bf imexamine} is a powerful and versatile task +which can be used to interactively examine image data at all stages of +the photometric reduction process. In this section we discuss and +illustrate those aspects of {\bf imexamine} which are most useful to +photometrists with emphasis on three different applications of the task: +1) examining the image, for example plotting lines and columns +2) deriving image characteristics, for example computing the +FWHM of the point-spread function 3) comparing the same region +in different images. + +The task +{\bf imexamine} lives within the {\bf proto} package, and you will also need +to load {\bf images} and {\bf tv}. Then +{\bf display} the image, and type {\bf imexamine}. +When the task is ready to accept input the image cursor will begin blinking +in the display window, and the user can begin executing various keystroke +and colon commands. The most useful data examining commands are summarized +below. The column, contour, histogram, line and surface plotting commands +each have their own parameter sets which set the region to be plotted and +control the various plotting parameters. All can be examined and edited +interactively from within the {\bf imexamine} task using the +appropriate {\bf :epar} command. + +\begin{description} + \item[c] - Plot the column nearest the image cursor + \item[e] - Make a contour plot of a region around the image cursor + \item[h] - Plot the histogram of a region around the image cursor + \item[l] - Plot the line nearest the image cursor + \item[s] - Make a surface plot of a region around the image cursor + \item[:c N] - Plot column N + \item[:l N] - Plot line N + \item[x] - Print the x, y, z values of the pixel nearest the image cursor + \item[z] - Print a 10 by 10 grid of pixels around the image cursor + \item[o] - Overplot + \item[g] - Activate the graphics cursor + \item[i] - Activate the image cursor + \item[?] - Print help + \item[q] - Quit {\bf imexamine} + \item[:epar c] - Edit the column plot parameters + \item[:epar e] - Edit the contour plot parameters + \item[:epar h] - Edit the histogram plot parameters + \item[:epar l] - Edit the line plot parameters + \item[:epar s] - Edit the surface plot parameters + +\end{description} + + +Example 1 below shows how a user can interactively +make and make hardcopies of image line plots using {\bf imexamine} and at the same time +illustrates many of the general features of the task. + +The {\bf imexamine} task also has some elementary image analysis capability, including +the capacity to do simple aperture photometry, compute image statistics +and fit radial profiles. The most useful image analysis commands are +listed below. + +\begin{description} +\item[h] - Plot the histogram of a region around the cursor +\item[r] - Plot the radial profile of a region around the cursor +\item[m] - Plot the statistics of a region around the cursor +\item[:epar h] - Edit the histogram parameters +\item[:epar r] - Edit the radial profile fitting parameters +\end{description} + +Example 2 shows how a photometrist might use {\bf imexamine} +and the above commands to estimate the following image characteristics: +1) the full width at +half maximum (FWHM) of the point-spread function, 2) the background sky level +3) the standard deviation of the background level 4) and the radius at which +the light from the brightest star of interest disappears into the noise +(this will be used to specify the size of the point-spread-function, +e.g.,PSFRAD). + +Finally {\bf imexamine} can be used to compare images. Example 3 +shows how to compare regions in the original image and in the +same image with all the fitted stars subtracted out. The example +assumes that the target image display device supports multiple frame buffers, +i.e. the user can load at +least two images into the display device at once. + +The {\bf imexamine} task offers even more features than are discussed here and the +user should refer to the manual page for more details. + +\vspace{12pt} +{\bf Example 1:} Plot and make hardcopies of image lines within {\bf imexamine}. + +\begin{itemize} +\item {\bf display} the image and then type {\bf imexamine}. +\item move the image cursor to a star and tap {\bf l} to plot the image +line nearest the cursor +\item tap the {\bf g} key to activate the graphics cursor +\item type {\bf :.snap} to make a hardcopy of the plot on your default device +\item expand a region of interest by first moving the graphics +cursor to the lower left corner of the region and typing {\bf E}, +and then moving the graphics cursor to the upper right corner +of the region and typing anything +\item type {\bf :.snap} to make a hardcopy of the new plot +\item tap the {\bf i} key to return to the image cursor menu +\item type {\bf :epar l} to enter the line plot parameter set, change the +value of the logy parameter to yes and type {\bf CNTL-Z} to exit and +save the change +\item repeat the previous line plotting commands +\item type {\bf q} to quit {\bf imexamine} +\end{itemize} + +{\bf Example 2:} Compute some elementary image characteristics using +{\bf imexamine}. + +\begin{itemize} +\item {\bf display} the image and then type {\bf imexamine}. +\item move to a bright star and tap the {\bf r} key +\item examine the resulting radial profile plot and note the final +number on the status line which is the FWHM of the best fitting +Gaussian +\item repeat this procedure for several stars to estimate a good +average value for the FWHM +\item set the parameters of the statistics box ncstat and nlstat +from 5 and 5 to 21 and 21 with {\bf :ncstat 21} and {\bf :nlstat 21} +commands so that the sizes of the statistics and histogram +regions will be identical +\item move to a region of blank sky and tap the {\bf m} key to get an +estimate of the mean, median and standard deviation of the +sky pixels in a region 21 by 21 pixels in size around the +image cursor +\item leave the cursor at the same position and tap the {\bf h} key to +get a plot of the histogram of the pixels in the same region +\item tap the {\bf g} key to activate the graphics cursor, move the +cursor to the peak of the histogram and type {\bf C} to print out +the cursor's value. The ``x" value then gives you a good estimate of +the sky. Similarly, you can move the cursor to the +half-power point of +the histogram and type {\bf C} to estimate the standard deviation +of the sky pixels. Tap the {\bf i} key to return to the +image cursor menu +\item compare the results of the h and m keys +\item repeat the measurements for several blank sky regions and note +the results +\item move to a bright unsaturated star and turn up the zoom and + contrast of the display device as much as possible +\item using the {\bf x} key mark the point on either side of the center +where the light from the star disappears into the noise +and estimate PSFRAD +\item type {\bf :epar r} to edit the radial profile fitting parameters +and set rplot to something a few pixels larger than PSFRAD +and tap the {\bf r} key +\item note the radius where the light levels off and compare with +the eyeball estimate +\item repeat for a few stars to check for consistency +\item type {\bf q} to quit imexamine +\end{itemize} + +\noindent +{\bf Example 3:} Overplot lines from two different images. + +\begin{itemize} +\item {\bf imexamine image1,image2} +\item move the image cursor to a star and type {\bf z} to print the +pixel values near the cursor +\item tap the {\bf n} key to display the second image followed by {\bf z} +to look at the values of the same pixels in the second +image +\item tap the {\bf p} key to return to the first image +\item tap {\bf l} to plot a line near the center of the star and tap +the {\bf o} key to overlay the next plot +\item tap the {\bf p} key to return to the second image and without +moving the image cursor tap the l key again to overplot +the line +\item type {\bf q} to quit imexamine +\end{itemize} + +\subsection{Dealing with Parameter Files (Wheels within Wheels)} + +The {\bf daophot} (and {\bf apphot}) packages are unique in IRAF in that +they obtain +pertinent information out of separate ``parameter files" that can be +shared between tasks. As anyone that +has used IRAF knows, each IRAF command has its own parameter file that +can +be viewed by doing an {\bf lpar} {\it command} or edited by doing an +{\bf epar} {\it command}. +However, in {\bf daophot} and {\bf apphot} there are ``wheels within +wheels"---some of the parameters are in fact parameter files themselves. +For instance, the aperture photometry routine {\bf phot} does not +explicitly +show you the methods and details of +the sky fitting in its parameter file. +However, if you do an {\bf lpar phot} +you will see a parameter +called ``fitskypars" which +contains, among many other things, the radii of the annulus to be used +in determining the sky value. +You will also find listed ``datapars" (which specifies the properties +of your data, such as photons per ADU and read-noise), ``centerpars" +(which +specifies the centering algorithm to be used), and ``photpars" (which gives +the +size of the digital apertures and the zero-point magnitude). +The contents of any of these parameter files can be altered either by +{\bf epar}ing them on their own or by typing a ``:e" while on that +line of the main parameter file. If you do the latter, a control-z +or a ``:q" will bring you back. +For example, to examine or edit {\bf fitskypars}, you can +do an explicit {\bf lpar fitskypars} +or {\bf epar fitskypars}, or you can do an {\bf epar phot}, move the +cursor down to the ``fitskypars" line, and then type a {\bf :e} to edit +(see Fig.~\ref{wheels}). +\begin{figure} +\vspace{4.2in} +\caption{\label{wheels}Changing the Sky Annulus in {\bf fitskypars}.} +\end{figure} +Confusing? You bet! +But once you are used to it, it is a convenient and powerful way to +specify a whole bunch of things that are used by several different +commands---i.e., you are guaranteed of using the same parameters in +several different tasks. If there is only one thing that you want to +change in +a parameter file you {\it can} enter it on the command line when +you run the command, just as if it were a ``normal" (hidden) parameter, +i.e., {\bf phot imagename dannulus=8.} does the same as +running {\bf epar fitskypars} and changing the ``width of sky annulus" +{\bf dannulus} to 8.0. + +Mostly these things are kept out of the way (``very hidden" parameters) +because you {\it don't} want to be changing them, once you have set them +up for your data. There are exceptions, such as changing the PSF radius +in making a point-spread function in a crowded field (Sec. 4.6). +However, +you are well protected here if you leave the {\bf verify} switch on. +A task will then give you an opportunity to take one last look at +anything +that you really care about when you run the task. For instance, if we +had simply run {\bf phot} on an image (we'll see how to do this shortly) +it would have said ``Width of sky annulus (10.)", at which point we +could +either have hit [CR] to have accepted the 10., or we could have +entered a new value. + + +\section{Aperture Photometry on your Standards} + +Standard stars provide a good example of relatively uncrowded +photometry, +and in this section we will describe how to obtain instrumental +magnitudes for your standards using {\bf phot}. +The basic steps are +\begin{itemize} + \item Decide what aperture size you wish to use for measuring your + standards {\bf (this should be the same for all the frames).} At the + same time we will pick a sky annulus. + \item Set up the various parameter files ({\bf datapars, + centerpars, fitskypars, photpars}) to have the correct values. + \item For each frame: + \begin{enumerate} + \item Identify the standard star(s) either + interactively using a cursor + or by using the automatic star finding algorithm + {\bf daofind}. + \item Run the aperture photometry program {\bf phot} + on each of your standard star frames. +\end{enumerate} +\end{itemize} +Although the routines you will need to use are available both in the +{\bf daophot} and {\bf apphot} packages, we strongly advise you to run +them from the {\bf daophot} package: the default setup is somewhat different, +and the two packages each have their own data parameter files. + +\subsection{Picking an Aperture Size} +Unfortunately, there are not good tools available with IRAF to do this +yet, and we will restrict our discussion here to some of the +considerations before telling you to just go ahead and use a radius that +is something like 4 or 5 times the FWHM of a stellar image; e.g., +12 or 15 +pixels as a radius, assuming you have the usual sort of ``nearly +undersampled" FWHM$\approx3$ data. +You might naively expect (as I did) that you wish to pick an aperture +size +that will ``contain all the light" from your standard stars, but in fact +this is impossible: the wings of a star's profile extend much further +than you imagine at a ``significant" level. King (1971 {\it Publ. +A.S.P.} {\bf 83}, 199) and Kormendy (1973 {\it A.J.} {\bf 78}, 255) +discuss the fact that on photographic plates the profile of a star +extends out to {\it arcminutes} at an intensity level far exceeding the +diffraction profile; Kormendy attributes this to scattering off of dust +and surface irregularities on the optical surfaces. +Massey {\it et al}.\ (1989 {\bf 97}, 107) discusses +this in regards to CCD's and standard star solutions using the very data +we are using here as an example (which is not exactly a coincidence). +Although the intensity profile falls off rapidly, the increase in area +with radius increases rapidly, and in practical terms Massey {\it et +al.} +found that in cases where the FWHM was typically small (2.5-3 pixels), +increasing the digital aperture size from a diameter of 18 pixels to +one of 20 pixels resulted in an additional 1-2\% increase in light +for a well-exposed star, and that this increase continues +for larger apertures until masked by the photometric errors. + +Given that you presumably want 1\% photometry or better, what should you +do? +Well, the fact that photoelectric photometery through fixed apertures +in fact does +work suggests that there is some radius beyond which the same fraction +of +light is excluded, despite variations in the seeing and guiding. You do +not want to choose a gigantic aperture ($>$ 20 pixels, say) because the +probability of your having a bad pixel or two goes up with the area. +But you do not want to choose too small an aperture ($<$10 pixels, say) +or you will find yourself at the mercy of the seeing and guiding. Most +photoelectric photometrists will use an aperture of at least 10 +arcseconds in diameter, but remember you have one advantage over them: +you are not sensitive to centering errors, since any digital aperture can +be exactly centered. +If you +have enough standard star observations (I used about 300 obtained over a +10 night run) you can +compute magnitude differences between a large aperture (20 pixels), +and a series of smaller apertures (8, 10, 12, 15, 18) for each filter, +and then see for which radius the difference (in magnitudes) becomes +constant. Unfortunately, there are no tools currently available within +IRAF for taking the differences between two apertures, or for conveniently +plotting these differences, so you are on your own. My recommendation +would be that if you have typical data with a +FWHM of $\leq 4$ pixels, that you use something like an aperture of 12 to 15 +pixels in radius for your standard stars. {\bf You can save yourself a lot +of trouble if you simply adopt a single radius for all the standards +from all the nights for all filters.} + +\subsection{Setting Things Up} + +As discussed in ``Dealing with Parameter Files" (Section 2.1) we must +setup the parameter files from which {\bf phot} will get the details of +what it is going to do. The easiest way to do this is to simply +{\bf epar phot}, and on each of the four parameter lists to do a +{\bf :e}. Mostly we will leave the defaults alone, but in fact you will +have to change at least one thing in each of the four files. + +\begin{figure} +\vspace{3.5in} +\caption{\label{photdatapars} Parameters for {\bf datapars}.} +\end{figure} +In {\bf datapars} (Fig.~\ref{photdatapars}) we need to specify both +the FWHM +of a star image ({\it fwhmpsf}) and the +threshold value above sky ({\it threshold}) if we are going to use the +automatic star-finding routine {\bf daofind}; the choices for these +are discussed further below. In order to have +realistic +error estimates for our aperture photometry we need to specify +the CCD readnoise {\it readnoise} in electrons and the +gain (photons per ADU) for the CCD {\it epadu}. +In order to +correct the results for the exposure time we need the exposure time +keyword {\it +exposure}. Do an + +\centerline{{\bf imhead} {\it imagename} {\bf l+ $|$ page}} + +\noindent +to see a +listing of all the header information (Fig.~\ref{phothead}). +\begin{figure} +\vspace{4.0in} +\caption{\label{phothead} Header information for std159.imh} +\end{figure} +By specifying the (effective) airmass and filter keywords, +these can be carried along in the photometry file for use when we do +the standards solution ({\it airmass} and {\it filter}). Finally we use +{\it datamin} and {\it datamax} so we will know if we exceeded the +linearity of the CCD in the exposure, or whether there is some anomalously +low valued pixel on which our star is sitting. +Since the value of the sky on our standard exposures is +probably nearly zero, {\it datamin} should be set to a negative value +about three times the size of the readnoise in {\it ADU's}; e.g., $-3 \times +65. \div 2.25 \approx -90$ in this example. Note that although we will +later argue that the shape of the PSF changes a little about 20000 +ADU's (presumably due to some sort of charge-transfer problem), +for the purposes of simple aperture photometry we are happy +using 32000 ADU's as the maximum good data value. (We do not really +want to use 32767 as afterall the overscan bias was probably at a +level of several hundred.) + +\begin{figure} +\vspace{3.0in} +\caption{\label{photcenterpars} Parameters for {\bf centerpars}.} +\end{figure} +In {\bf centerpars} (Fig.~\ref{photcenterpars}) we need to +change the centering algorithm {\it calgorithm} +from the default value of ``none" to +``centroid". If the FWHM of your frames are unusually large ($>4$, say, +you would also do well to up the size of {\bf cbox} to assure that the +centering works well; make it something like twice the FWHM. In this +case the FWHM is 3 pixels or a bit smaller, and we are content to leave +it a the default setting of 5 pixels. + +\begin{figure} +\vspace{2.7in} +\caption{\label{photfitskypars} Parameters for {\bf fitskypars}.} +\end{figure} +In {\bf fitskypars} (Fig.~\ref{photfitskypars}) +the only things we must specify are the size and +location of the annulus in which the modal value of the sky will be +determined. If you are going to use a value of 15 for your photometry +aperture, you probably want to start the sky around pixel 20. Keeping +the width of the +annulus large (5 pixels is plenty) assures you of good sampling, but +making it too large increases the chances of getting some bad pixels in +the sky. + +\begin{figure} +\vspace{2.7in} +\caption{\label{photphotpars} Parameters for {\bf photpars}.} +\end{figure} +In {\bf photpars} (Fig.~\ref{photphotpars}) +we merely need to specify the size (radius) of the +aperture we wish to use in measuring our standards. + +\subsection{Doing It} +There are basically two ways of proceeding in running photometry on the +standard stars, depending upon how you are going to identify the +relevant star(s) on each frame. If you have only one (or two) +standard stars on each frame, and it is always one of the brightest +stars present, then you can avoid a lot of the work and use the +automatic star-finding program {\bf daofind} to find all your standards +and the whole thing can be done fairly non-interactively. However, +if you are one of the believers in cluster field standards, then you +may actually want to identify the standards in each field using the +cursor on the image display so that the numbering scheme makes sense. +We describe below each of the two methods. + +\subsubsection{Automatic star finding} +First let's put the name of each frame containing standard stars into +a file; if you've put the standard star exposures into a separate +directory this can be done simply by a {\bf files *.imh $>$ stands}. +This will leave us with funny default output file +names for a while (we advise against +including the ``.imh" extension when we discuss crowded field photometry +in the next section), but this will only be true for a short +intermediate +stage. + +We want to run {\bf daofind} in such a way that it finds only the +brightest +star or two (presumably your standard was one of the brightest stars +in the field; +if not, you are going to have to do this stuff as outlined below in +the ``Photometry by eye" section). We will delve more fully into the +nitty-gritty of {\bf daofind} in the crowded-field photometry section, +but here we are content if we can simply find the brightest few stars. +Thus the choice of the detection +threshold is a critical one. If you make it too low you will find all +sorts of junk; if you make it too high then you may not find any stars. +You may need to run {\bf imexamine} on a few of your images: first +{\bf display} the image, and then {\bf imexamine}, using the ``r" cursor +key to produce a radial profile plot. Things to note are the +typical full-width-half-maximum and the peak value. If your sky is +really around zero for your standard exposures, then using a value +that is, say, twenty times the readnoise (in ADU's) is nearly guaranteed to +find only the brightest few stars; do your radial plots in {\bf +imexamine} show this to be a reasonable value? In the example here we +have decided to use 500 ADUs as the threshold ($20 \times 65 \div 2.25 +\approx 500$). + +Now {\bf epar daofind} so it resembles that of Fig.~\ref{photdaofind}. +\begin{figure} +\vspace{3.5in} +\caption{\label{photdaofind} Parameter file for {\bf daofind}.} +\end{figure} +Go ahead and execute it (Fig. ~\ref{daoout}). +\begin{figure} +\vspace{3.5in} +\caption{\label{daoout} Screen output from a {\bf daofind} run.} +\end{figure} +Note that since {\it verify} is on that you +will be given a chance to revise the FWHM and detection threshold. By +turning verbose on you will see how many stars are detected on each +frame. +%Probably the best way of doing this is to write the output from +%{\bf daofind} into a file; do a +% +%\centerline{ {\bf daofind @stands $|$ tee starsfound} } +% +%\noindent +%to put the output into the file ``starsfound" as well as on the screen. +Make a note of any cases where no stars were found; these you will have +to +go back and do with a lower threshold. + +The run of {\bf daofind} produced one output file named {\it +imagename.imh.coo.1} for each input file. If you {\bf page} one of +these you will find that it resembles that of Fig.~\ref{photcooout}. +\begin{figure} +\vspace{3.7in} +\caption{\label{photcooout} Output file from {\bf daofind}.} +\end{figure} +The file contains many lines of header, followed by the {\it x} and {\it +y} center values, the magnitudes above the threshold value, the ``sharpness" +and ``roundness" values, and finally an ID number. +In the example shown +here in Fig.~\ref{photcooout} two stars were found: one 2.9 mags +brighter than our detection threshold, and one about 0.4 mag brighter +than our detection threshold. + +In a few cases we doubtlessly found more than one star; this is a good +time to get rid of the uninteresting non-standards in each field. +If things went by too fast on the screen for you to take careful notes +while running {\bf daofind} we can find these cases now: do a + +\centerline{ {\bf txdump *coo* image,id,x,y yes }} + + +\noindent +to get a listing of the location and number of stars found on each image. +If you have cases where there were lots of +detections (a dozen, say) you may find it easier to first {\bf sort +*.coo* mag} in order to resort the stars in each file by how bright they +are. Of course, your standard may not be the brightest star in each +field; you may want to keep an eye on the {\it x} and {\it y} values to +see if it is the star you thought you were putting in the middle! +To get rid of the spurious stars you will need to {\bf edit} each of the +output files (e.g., {\bf edit std148.imh.coo.1} ) and simply delete the +extras. + +Finally we can run aperture photometry on these frames, using the +``.coo" files to locate the standard star in each frame. {\bf epar +phot} until it resembles that of Fig.~\ref{photphot}. +\begin{figure} +\vspace{3.5in} +\caption{\label{photphot} The parameter file for a run of {\bf phot}.} +\end{figure} +Note that we are specifying a {\it single} output file name +(``standstuff" in this example); {\it all} the photometry output will be +dumped into this single file, including things like the airmass and filter +number. Go ahead and execute {\bf phot}. +You should see something much like that of Fig.~\ref{photrun} on the +screen. +\begin{figure} +\vspace{5.5in} +\caption{\label{photrun} Running {\bf phot} non-interactively +on the standard stars.} +\end{figure} +We will discuss the output below under ``Examining the results". + +\subsubsection{Photometry by Eye} +In this section we will discuss the case of selecting stars {\it +without} +running the automatic star-finding program, using the image display +window and the cursor. The first step is to {\bf epar phot} so it +resembles that of Fig.~\ref{photeye}. +\begin{figure} +\vspace{3.5in} +\caption{\label{photeye} Parameter file for {\bf phot} when stars will +be selected interactively.} +\end{figure} +Note that we have replaced the {\bf coords} coordinate list with the +null string (two adjacent double-quotes) and turned ``interactive" on. + +We need to display the frame we are going to work on in the imtool +window: + +\centerline { {\bf display std145 1} } + +\noindent +will display image {\bf std145.imh} in the first frame buffer. + +Now let's run {\bf phot}. We are not likely to be {\it too} accurate +with where we place the cursor, so to be generous we will increase the +allowable center shift to 3 pixels; otherwise we will get error messages +saying that the ``shift was too large": + +\centerline{ {\bf phot std145 maxshift=3.} } + +\noindent +(Note that even though {\bf maxshift} is a parameter of {\bf centerpars} +we can change it on the command line for {\bf phot}.) Also note that we +left off the ``{\bf .imh}" extension for a reason: we are going to take +the default names for the output files, and they will be given names +such as {\bf std145.mag.1} and so on. If we had included the {\bf .imh} +extension would would now be getting {\bf std145.imh.mag.1} names. + +At this point I get a flashing circle in my {\bf imtool} window; I don't +know what you get (it depends upon how your defaults are set up) but +there should be some sort of obvious marker on top of your image. +Put it on the first star you wish to measure and hit the space bar. The +coordinates and magnitude should appear in the {\bf gterm} window, and +you are ready to measure the next star on this frame. Proceed until all +the stars on this frame are measured, and then type a ``q" followed by +another ``q". Display the next frame, and run {\bf phot} on it. + +When you get done you will have kerjillions of files. + +\subsection{Examining the Results: the power of {\bf txdump }} + +Depending upon which of the two methods you selected you will either +have a single file {\bf standstuff} containing the results of all your +aperture photometry, or you will have a file for each frame ({\bf +stand145.mag.1}, {\bf stand146.mag.1} \ldots)containing the stars +on each frame. In either event the file will pretty much resemble that +shown in Fig.~\ref{photphotout}. +\begin{figure} +\vspace{7.5in} +\caption{\label{photphotout} Output file from {\bf phot}.} +\end{figure} +The file begins with a large header describing the parameters in +force at the time that {\bf phot} was run. There is, however, a real +subtlety to this statement. If you had changed a parameter in {\bf +datapars}, say, (or any of the other parameters) between running {\bf +daofind} and {\bf phot}, the header in {\bf phot} will reflect only the +setting that was in force at the time that {\bf phot} was run---in other +words, it does not take the values of what was used for the {\bf +threshold} from the coordinate file and retain these, but instead simply +copies what value of {\bf thresh} happens to be in {\bf datapars} at the +time that {\bf phot} is run. To those used to the +``self-documenting" feature of VMS DAOPHOT this is a major change! + +Once we get past the header information we find that there are 5 lines +per star measured. The ``key" to these five lines of information are +found directly above the measurement of the first star. On the first +line we have ``general information" such as the +image name, the beginning x and y values, the id, +and the coordinate file. On the next line we have all the centering +information: the computed x and y centers, +the x and y shift, and any centering errors. On the third line of the +file we have information about the sky. On the fourth line we have some +information out of the image header: what was the integration time, what +was the airmass, and what was the filter. Note +that {\bf phot} has used that integration time in producing the +magnitude---the exposures are now normalized to a 1.0 sec exposure. +The fifth line gives the actual photometry, including the size of the +measuring aperture, the total number of counts within the aperture, the +area of the aperture, and the output magnitude, photometric error, and +any problems encountered (such as a bad pixel within the aperture). + +We can extract particular fields from this file (or files) by using the +{\bf txdump} command. For instance, are there any cases where there +there were problems in the photometry? We can see those by saying + +\centerline{\bf txdump standstuff image,id,perror} + +\noindent +(If you did ``Photometry by eye" you can substitute {\bf *mag*} for {\bf +standstuff}.) +When it queries you for the ``boolean expression" type + +\centerline{ {\bf perror!$=$"No\_error"} } + +\noindent +The ``!$=$" construction is IRAF-ese for "not equal to"; therefore, this +will select out anything for which there was some problem in the +photometry. + +We can create a single file at this point containing just the +interesting results from the photometry file(s): do a + +\centerline{ {\bf txdump standstuff +image,id,ifilt,xair,mag,merr yes $>$ standsout} } + +\noindent +to dump the image name, id-number, filter, airmass, magnitude, +and magnitude error into a file {\bf standsout}. (Again, if you did +``Photometry by Eye" substitute {\bf *mag*} for {\bf standstuff}). +Unfortunately, what you do with this file is up to you right now until +the standard reductions routines become available. In the example shown +here we have selected the fields in the same order as used in Peter +Stetson's VMS CCDCAL software, and at the end of this manual we will +describe a (painful) kludge that nevertheless {\it will} let you use +these numbers with that software. + +\section{Crowded Field Photometry: IRAF/daophot} +\subsection{Historical Summary} + +In the beginning (roughly 1979) astronomers +interested in obtaining photometry from stars in ``relatively" crowded fields +would make the journey to Tucson in order to use Doug Tody's RICHFLD +program which ran on the IPPS display system. +RICHFLD allowed the user to define a +point-spread-function (PSF), and then fit this PSF to the brightest star +in a group, subtract off this star, and then proceed to the next +brightest star, etc. This represented a giant qualitative improvement +over the possibilities of aperture photometry, and allowed stars +separated by a few FWHM's to be accurately measured. + +Beginning in 1983, a group of RICHFLD users at the DAO (including +Ed Olszewski and Linda Stryker) began modifications to the ``poorman" +program of Jeremy Mould. This was largely motivated by the +implementation of the ``Kitt Peak CCD" at the prime-focus of the Tololo +4-m, and the idea was to design a crowded-field +photometry +program that (a) allowed simultaneous PSF-fitting, (b) made +use of the {\it known noise characteristics of a CCD} to do the fitting +in a +statistically correct manner (i.e., to make ``optimal" use of the data), +and (c) to be largely batch oriented. +In mid-1983 Peter Stetson arrived at the DAO, and took over +the effort. The result was +DAOPHOT, which did all these things and more. +By 1986 DAOPHOT was well distributed within the astronomical community. +The basic algorithms and philosophy can be found in Stetson 1987 (PASP +{\bf 99}, 111). + +DAOPHOT (and its companion program ALLSTAR) were not part of a +photometry +package; they were instead stand-alone Fortran +programs which did not deal in any way with the issue of image display +or what to do with the instrumental magnitudes once you had them. They +were also only supported on VMS, although several ``frozen" versions +were translated into UNIX by interested parties around the country. +There was therefore +much to be gained from integrating the algorithms of daophot +with IRAF in order to make use of +the image display capabilities and general tools for manipulating +images. Also, since many astronomers were now reducing their CCD data +with IRAF, it avoided the necessity of translating the IRAF files into +the special format needed by VMS DAOPHOT. Dennis Crabtree began this +translation program while at the DAO; it was taken over by Lindsey Davis +of the IRAF group in early 1989, and taken to completion in early 1990. +Pedro Gigoux of CTIO is currently hard at work on the photometry +reduction package, scheduled for completion sometime during the spring. + +\subsection{{\bf daophot} +Overview} +The steps involved in running daophot are certainly more involved than +in simple aperture photometry, but they are relatively straightforward. +The following sections will lead you through the necessary procedures. +Alternative routes will be noted at some points, and more may be gleaned +from reading the various "help" pages. A general outline is given here +so that you have some overview in mind; a detailed step-by-step summary +is provided at the end of this section. + +\begin{itemize} +\item Before you reduce the first frame, {\bf imexamine} your data to +determine FWHM's and the radius at which the brightest star you wish to +reduce blends into the sky. Run {\bf imhead} to find the ``key-words" +in your data headers for exposure times, filter number, and airmass. +Enter these, along with the characteristics of your chip (read-noise, +photons per ADU, maximum good data value) +into the parameter sets {\bf datapars} and {\bf +daopars}. +\item Use {\bf daofind} and {\bf tvmark} +to produce a list of x and y positions of most +stars on the frame. +\item Use {\bf phot} to perform aperture photometry on the identified +stars. This photometry will be the basis of the zero-point of +your frame via the PSF stars. This is also the only point where sky +values are determined for your stars. +\item Use {\bf psf} to define the PSF for your frame. If your PSF stars are crowded this +will require some iteration using the routines {\bf nstar} and {\bf +substar}. +\item Use {\bf allstar} to do simultaneous PSF-fitting for all the stars +found on your frame, and to produce a subtracted frame. +\item Use {\bf +daofind} on the subtracted frame to identify stars that had been +previously hidden. +\item Run {\bf phot} {\it on the original frame} to obtain aperture photometry +and sky values for the stars on the new list. +\item Use {\bf append} to merge the two aperture photometry lists. +\item Run {\bf allstar} again on the merged list. +\end{itemize} +When you have done this for your {\it U, B,} and {\it V} frames it is +then time to +\begin{itemize} +\item Use {\bf txdump}, {\bf tvmark}, and the image display +capabilities to come up with a consistent matching between the frames. +If there are additions or deletions then you will need to re-run +{\bf phot} and {\bf allstar} one more time. +\end{itemize} +Finally you will need to +\begin{itemize} +\item Determine the aperture correction for each frame by subtracting +all but the brightest few isolated stars on your frames and then running +{\bf phot} to determine the light lost between your zero-point aperture +and the large aperture you used on your standard stars. +\end{itemize} + +\subsection{How Big Is A Star: A Few Useful Definitions} + +The parameter files {\bf datapars} and {\bf daopars} contain three +``size-like" variables, and although this document is not intended as +a reference guide, there is bound to be confusion over these three +parameters, particularly among those new to DAOPHOT. In the hopes +of un-muddying the waters, we present the following. + +\begin{description} +\item[fwhmpsf] This is the full-width at half-maximum of a stellar object +(point-spread function, or psf). The value for {\bf fwhmpsf} gets used +only by the automatic star-finding algorithm {\bf daophot}, unless you +do something very bad like setting {\bf scale} to non-unity. + +\item[psfrad] This is the ``radius" of the PSF. When you construct a PSF, +the PSF will consist of an array that is +$$(2 \times psfrad +1) \times +(2 \times psfrad + 1)$$ +on a side. The idea here is that ``nearly all" of the light of the brightest +star you care about will be contained within this box. If you were to construct +a PSF with some large value of {\bf psfrad} and then run {\bf nstar} or +{\bf allstar} +specifying +a smaller value of {\bf psfrad}, the smaller value would be used. Making +the {\bf psfrad} big enough is necessary to insure that the wings of some +nearby bright star are properly accounted for when fitting a faint star. + +\item[fitrad] This is how much of the psf is used in making the fit +to a star. The ``best" photometry will be obtained (under most circumstances) +if this radius is set to something like the value for the fwhm. + +\end{description} + +\subsection{Setting up the parameter files ``daopars" and ``datapars" } + +The first step in using IRAF/daophot is to determine and store the +characteristics of your data in two parameter files called ``datapars" +and ``daopars"; these will be used by the various daophot commands. +In Section 1 we discussed how to deal with parameter files, and +in Section 2 we went through setting up ``datapars" for the standard +star solutions; at the risk of repeating ourselves, we will go through +this again as the emphasis is now a little different. + + +First inspect your headers by doing an {\bf imhead} imagename {\bf long+ +$|$ page}. +This will produce a listing similar to that shown in Fig.~\ref{newhead}. +\begin{figure} +\vspace{3.0in} +\caption{\label{newhead}Header for image n602alu.imh.} +\end{figure} +The things to note here are (a) what the filter keyword is (we can +see from Fig.~\ref{newhead} that the answer is F1POS; while there is +an F2POS also listed, the second filter bolt was not used and was always +in position ``zero"), +(b) what the effective exposure +time keyword is (EXPTIME in this example), and (c) what the effective +airmass keyword is (AIRMASS in this example). + +Next you need to examine some ``typical" frames in order to determine +the FWHM ({\bf fwhmpsf}) and the radius of the brightest star for which +you plan to do photometry ({\bf psfrad}). +First {\bf display} an image, and use the +middle button of the mouse (or whatever you need to do on your image +display) to zoom on a few bright stars. On the SUN the "F6" key will +let you see x and y values. The ``default" PSF radius is 11 pixels: +are your stars bigger than 23 pixels($23=2 \times 11 + 1$) +pixels from one side to the other? The FWHM is undoubtably variable +from frame to frame, but unless these change by drastic amounts (factors +of two, say) using a ``typical" value will doubtless suffice. You can +use the {\bf imexamine} routine to get some idea of the FWHM; do +{\bf imexamine} filename and then strike the ``r" key (for radial +profile) after centering the cursor on a bright (but unsaturated) star. +The last number on the plot is the FWHM of the best-fit Gaussian. + +We are now ready to do an {\bf epar datapars}. This parameter file +contains information which is data-specific. We set {\bf fwhmpsf} to the FWHM +determined above, and we enter the names of the keywords determined from +the header inspection above. The ``gain" and ``read-noise" are values +you have either determined at the telescope (using the Tololo routines) +or which are carved in stone for your chip. Choosing the value +for datamax, the ``Maximum good data value", +(in ADU's, NOT electrons) is a little bit trickier. In the case of +aperture photometry we were satisfied to take the nominal value for +the chip, but point-spread-function fitting is a bit more demanding +in what's ``linear". The data obtained +here was taken with an RCA chip, and we all know that RCA chips are +linear well past 100,000 e-. Thus, naively, we would expect that +with a gain of 2.25 that the chip was still linear when we hit the +digitization limit of 32,767 ADU's. Subtract off 500 for the likely +bias, and we {\it might} think that we were safe up to 32,200. However, +we would be wrong. Experience with PSF fitting on these data shows that +something (presumably in those little silver VEB's) has resulted in +these data being non-linear above 20,000 ADU's. My suggestion here is +to start with the nominal value but be prepared to lower it if the +residuals from PSF fitting appear to be magnitude dependent (more on this +later). The value for +{\bf datamin}, the +``Minimum good +data value", will be different for each frame (depending what the sky +level is) and there is not much point in entering a value for that yet. +Similarly the value we will use for threshold will change +from frame to frame depending upon what the sky level is. +When you are done your {\bf datapars} should resemble that of +Fig.~\ref{datapars}. +\begin{figure} +\vspace{2.7in} +\caption{\label{datapars} A sample {\bf datapars} is shown.} +\end{figure} + +Next we will {\bf epar daopars}. This parameter file contains +information specific to what you want {\bf daophot} to do. The only things here +we might want to change at this point are the ``Radius of the psf" {\bf psfrad} +(if your experiment above showed it should be increased somewhat), and +you might want to change the fitting radius {\bf fitrad}. Leaving the fitting +radius to ``something like" the FWHM results in the best SNR (you can +work this out for yourself for a few different regimes if you like to +do integrals). The ``standard values" are shown in Fig.~\ref{daopars}. +\begin{figure} +\vspace{2.7in} +\caption{\label{daopars} A sample {\bf daopars} is shown.} +\end{figure}. + +\subsection{Finding stars: {\bf daofind} and {\bf tvmark} } +The automatic star finder {\bf daofind} convolves a Gaussian of +width FWHM with the image, and looks for peaks greater than some +threshold in the smoothed image. It then keeps only the ones that are +within certain roundness and sharpness criteria in order to reject +non-stellar objects (cosmic rays, background galaxies, bad columns, +fingerprints). We have already entered a reasonable value for the FWHM +into {\bf datapars}, but what should we use as a threshold? We expect +some random fluctuations due to the photon statistics of the sky +and to the read-noise of the chip. You can calculate this easily by +first +measuring the sky value on your frame by +using {\bf imexamine} and the ``h" key to produce a histogram of +the data ({\bf implot} and the ``s" key is another way). In the example +shown in Fig~\ref{hist} we see that the sky value is roughly 150. +\begin{figure} +\vspace{3.6in} +\caption{\label{hist} The {\bf imexamine} histogram (``h" key) indicates +that the sky value is roughly 150.} +\end{figure} +In general, if $s$ is the sky value in ADU, $p$ is the number of +photons per ADU, and $r$ is the read-noise in units of electrons, +then the expected $1\sigma$ variance in the sky +will be +$$\left(\sqrt{s\times p + r^2}\right)/p$$ +in units of ADU's. For the example here we expect +$1\sigma=\left(\sqrt{150.\times 2.25 + 65^2}\right)/2.25=30$ ADU's. +Of course, if you have averaged N frames in producing your image, +then you should be using +$N\times p$ as the gain both here and in the value entered in +{\bf datapars}; similarly the readnoise is really just $r \times \sqrt{N}$. +If instead you summed N frames then the gain is just {\it p} and the +readnoise is still $r\times \sqrt{N}$. + +In the example shown here the expected $1\sigma$ variation of the sky is +30 ADU's; we might therefore want to set our star detection threshold to +3.5 times that amount. That won't guarantee that every last star we +find is real, nor will it find every last real star, but it should do +pretty close to that! + +We should use this opportunity to set datamin in {\bf +datapars} to some value like $s-3\sigma$. In this case we will set it +to 60. This is not currently used by {\bf daofind} but will be used +by all the photometry routines. Fig.~\ref{ndatapars} shows the data +parameters with the appropriate values of threshold and datamin now +entered. +\begin{figure} +\vspace{3.0in} +\caption{\label{ndatapars} Datapars with {\bf threshold} and {\bf datamin} +entered.} +\end{figure} + +We now can {\bf epar daofind} so it resembles that of +Fig.~\ref{daofind}. +\begin{figure} +\vspace{3.0in} +\caption{\label{daofind} Parameters for {\bf daofind}.} +\end{figure} +Note that although nothing appears to be listed under {\bf datapars} the +default name is ``datapars"; you could instead have created a separate +data parameter file for each ``type" of data you have and have called +them separate names (you could do this by doing an {\bf epar datapars} +and then exiting with a ``:w newnamepar"). This might be handy if +all your {\it U} frames were averages, say, but your {\it B} and {\it V} +frames were +single exposures; that way you could keep track of the separate +effective gain and readnoise values. In that case you would enter the +appropriate data parameter name under {\bf datapars}. As explained earlier, +you could also do a +``:e" on the {\bf datapars} line and essentially do the {\bf epar datapars} from +within the {\bf epar daofind}. +For normal star images, the +various numerical values listed are best kept exactly the way they are; +if you have only football shaped images, then read the help page for +{\bf daofind} for hints how best to find footballs. + +We can now run {\bf daofind} by simply typing {\bf daofind}. +As shown in Fig.~\ref{daofind} that we were asked for the FWHM and threshold +values; this is a due to having turned ``verify" on in the parameter +set. This safeguards to a large extent over having forgotten to set +something correctly. A [CR] simply takes the default value listed. + +Running {\bf daofind} produced an output file with the (default) +filename of {\bf n602csb.coo.1}. +(Do {\it not} give the {\bf .imh} extension +when specifying the image name, or the default naming +process will get very confused!) We can page +through that and see the x and y centers, the number of magnitudes +brighter than the cutoff, the sharpness and roundness values, and the +star number. However, of more immediate use is to use this file +to mark the found stars on the image display and see how we did. +If we have already displayed the frame in frame 1, then we can {\bf epar +tvmark} to make it resemble Fig.~\ref{tvmark}. +\begin{figure} +\vspace{2.7in} +\caption{\label{tvmark} Parameter file for {\bf tvmark}.} +\end{figure} +This will put red dots on top of each star found. + +We can see from Fig.~\ref{dots} that {\bf daofind} did a pretty nice +\begin{figure} +\vspace{7.0in} +\caption{\label{dots} Stars found with {\bf daofind} and marked with +{\bf tvmark}.} +\end{figure} +job. If we didn't like what we saw at this point we could rerun +{\bf daofind} with a slightly higher or slightly lower threshold---try +varying the threshold by half a sigma or so if you are almost right. +As you may have guessed, subsequent runs will produce output files with +the names n602csb.coo.2, n602csb.coo.3,... +If you are using a very slow computer, or are exceedingly impatient, + you could have saved some +time by putting a ``c" (say) under ``convolv" in your first run of +{\bf daofind}---this would have saved the +smoothed image as cn602csb.imh, and would drastically reduce +the number of cpu cycles needed to rerun {\bf daofind} with +a different threshold value. +If you really very happy with what {\bf daofind} did but you +just want to add one or two stars at this point, you +can in fact do that quite readily using {\bf tvmark}. Set the +parameters as in Fig.~\ref{tvmark}, but turn interactive on. +Position the cursor on top of the star you wish to add and strike +the ``a" key. Note that this will ``disturb" the format of the file, +but we really don't care; it will still work just fine as the input to +{\bf phot}. + +Note that it is fairly important that you do a good job at this stage. +If you have used too low a threshold, and have a lot of junk marked as +stars, these fictitious objects are likely to wander around during the +PSF-fittings until they find something to latch onto---{\it not} a good +idea. However, you also do not want the threshold to be so high that +you are missing faint stars. Even if you are not planning to publish +photometry of these faint guys, you need to have included them in the +list of objects if they are near enough to affect the photometry of +stars for which you do have some interest. If you find that varying the +threshold level does not result in a good list, then something is +wrong---probably you have badly over- or under-estimated the FWHM. +When you are close to the ``perfect" value of the threshold, +changing its value by as little as half a sigma will make a substantial +difference between getting junk and real stars. + +\subsection{Aperture Photometry with {\bf phot} } +The next step is to do simple aperture photometry for each of the stars +that have been found. These values will be used as starting points in +doing the PSF fitting, and this is the only time that sky values will be +determined. + +{\bf One of the few ways of ``crash landing" in the current +implementation of the software is to forget to reset ``datamin" in the +datapars file before running phot on a new frame. It is the only +critical parameter which is not queried when verify is turned on. Therefore, +this is a good time to check to see that ``datamin" is really set to +several sigma lower than the sky value of this particular frame.} + +The aperture photometry routine {\bf phot} has more parameters than all +the others put together: there are the parameter files +{\bf centerpars}, {\bf fitskypars}, and {\bf photpars}. +Fortunately the ``verify" +option frees you from having to look at these, and helps prevent you +from making a mistake. If this is your first pass through DAOPHOT it is +worth your while to do the following: + +\centerline{ {\bf unlearn centerpars} } + +\centerline{ {\bf unlearn fitskypars} } + +\centerline{ {\bf unlearn photpars} } + +\noindent +If you have used {\bf phot} for measuring standard stars, then this will +reset the defaults to reasonable values for crowded-field photometry; +in particular, we want to make sure that the centering +algorithm in {\bf centerpars} is set to ``none". +Do an {\bf epar phot} and make it look like that of Fig.~\ref{phot}. +Since we have the ``verify" switch turned on, we can be happy, not +worry, and simply type {\bf phot}. +{\bf phot} will then prompt you as shown in +Fig.~\ref{phot}. +\begin{figure} +\vspace{7.0in} +\caption{\label{phot} Questions and answers with {\bf phot}.} +\end{figure} +Note that the answers were particularly simple: we told it the name of +the frame we wished to work with, we accepted the default for the coordinate +list (it will take the highest ``version" of image.coo.NUMBER) and the +default for the output photometry list (n602csb.mag.1 will be produced +in this case.) We accepted the centers from {\bf daofind} as being +``good enough" to not have to recenter (they are good to about one-third +of a pixel, plenty good enough for aperture sizes of 2.5 pixels and +bigger; when we run this routine later on the second pass we would make +a Big Mistake by turning centering on here, so leave it off). +The sky +values will be taken from an annulus extending from a radius of 10 +pixels to a radius of 20 pixels, and it will determine the standard +deviation of the sky from the actual data. Note that this is probably a +lot closer in than you used on your standard stars; in crowded regions +of variable background keeping this annulus relatively close in will +help. +Finally, we used a measuring +aperture of 3 pixels. The number of counts within this aperture will be +what defines the zero-point of your frame, as we will see in Section 4.9, +and keeping this value {\it fixed} to some value like your typical FWHM +will keep you safe. + +\subsection{Making the PSF with {\bf psf} } + +If you are used to the VMS version of DAOPHOT, you are in for a pleasant +surprise when it comes to making a PSF within the IRAF version. +Nevertheless, just because it's easy doesn't mean that you shouldn't be +careful. + +What constitutes a good PSF star? Stetson recommends that a good PSF +star meets the following criteria: +\begin{enumerate} +\item No other star at all contributes any light within one fitting +radius of the center of the candidate star. (The fitting radius will be +something like the FWHM.) +\item Such stars as lie near the candidate star are significantly +fainter. (``Near" being defined as, say, 1.5 times the radius of the +brightest star you are going to measure.) +\item There are no bad columns or rows near the candidate star; there +should also be no bad pixels near the candidate star. +\end{enumerate} + + +In making a PSF, you wish to +construct a PSF which is free from bumps and wiggles (unless those +bumps and wiggles are really what a single isolated star would look like.) +First off, does it matter if we get the PSF ``right"? If we had +only isolated stars, then the answer would be no---any +old approximation to the PSF would give you +good relative magnitudes, and there are programs in the literature +which do exactly this. However, if your stars are relatively isolated +you are not going to gain anything by PSF-fitting over aperture photometry +anyway, so why bother? If you are dealing with crowded images, then the +PSF has to be right {\it even in the wings}, and for that reason we +construct a PSF empirically using the brightest and least crowded stars +in our frame. +If you are very, very +lucky you will find that your brightest, unsaturated star is well +isolated, and has no neighbors about it---if that's the case, use that +one and forget about the rest. Usually, however, you will find that +it isn't quite that easy, and it will be necessary to construct the PSF +interatively. The steps involved will be +\begin{enumerate} + \item Select the brightest, least-crowded stars for the zeroth-order + PSF. + \item Decrease the size of the PSF radius and fit these stars + with their neighbors using {\bf nstar}. + \item Subtract off the PSF stars and their neighbors using + {\bf substar} to see + if any of the PSF stars are ``funny"; if so, go back to + the step 1 and start over. + \item Edit the {\bf nstar} results file ({\bf imagename.nst.N}) + and delete the entries for the PSF stars. You are left + with a file containing the magnitudes and positions of just + the neighbors. + \item Subtract off just the neighbors using this file as input + to {\bf substar}. Display + the results, and examine the region around each PSF star. + Are the neighbors cleanly removed? + \item Increase the PSF radius back to the original value. + Construct an improved PSF using the new frame (the one with the + neighbors gone.) + \item Run {\bf nstar} on the PSF stars and their neighbors again, and + again subtract these using {\bf substar}. Examine the results. + If you are happy, proceed; otherwise, if the neighbors need + to be removed a bit more cleanly go back to step 4. +\end{enumerate} + +First {\bf display} the frame, and put dots on all the stars you've found +using {\bf tvmark} as discussed above. Next {\bf epar psf} and make sure +it looks like that of Fig.~\ref{psfparams}. +\begin{figure} +\vspace{2.5in} +\caption{\label{psfparams} Parameter file for {\bf psf}} +\end{figure} +We have set this up so we can choose the stars interactively from the +display window. + +Next run {\bf psf}. The defaults that you will be asked to {\bf verify} +are probably fine, but pay particular attention to {\bf psf radius} +and {\bf fitting radius}. The {\bf psf radius} should be as large +as you determined above (11 usually works well on ``typical" CCD +frames whose star images have FWHM's $\approx 3$). The ``fitting radius" +should be relatively generous here---maybe even larger than what you +want to use on your program stars. A reasonable choice is approximately +that of the FWHM. + +You will find that the cursor has turned into a circle and is sitting +on your image in the display window. Position it on a likely looking +PSF star, and strike the ``a" key. You will be confronted with a mesh +plot that shows the star and it surroundings. To find out more +about the star (such as what the peak data value is you can type +an ``s" while looking at the mesh plot. To reject the star type an +``x", to accept the star type an ``o". In the latter case, you will +next see a mesh plot that +shows you the star with a two-dimensional Gaussian fit removed from the +star. +Again, exit this with a ``o". If you don't find these mesh +plots particularly useful, you can avoid them by setting {\bf showplot=no} +in the {\bf psf} parameters (see Fig.~\ref{psfparams}). +At this point you will be told what the star number was, what the +magnitude was, and what the minimum and maximum data values within +the PSF were. (If you picked a star whose peak intensity was greater +than ``datamax" it will tell you this and not let you use this star.) +When you are done selecting stars, type a ``w" (to write the PSF to +disk) followed by a ``q". + +If in making the PSF you noticed that there were stars you could have +used but didn't because they had faint neighbors not found in the earlier +step of star finding, you can add these by hand by simply +running {\bf tvmark} interactively and marking the extra stars. First +{\bf epar tvmark} so it resembles that of Fig.~\ref{tvmark}. Then: + +\centerline{ {\bf display n602csb 1} } + +\centerline{ {\bf tvmark 1 n602csb.coo.1 interactive+} } + +\noindent + +Striking the ``l" key will mark the stars it already knows about onto +the display (as red dots this time around); positioning the cursor on the +first star you wish to add and type an ``a". When you are done adding +stars exit with a ``q" and re-run {\bf phot}. + +Now that you have made your preliminary PSF, do a {\bf directory}. You'll +notice that in addition to the image {\bf n602csb.psf.1.imh} that the +{\bf psf} routine has also added a text file {\bf n602csb.psg.1}. If +you {\bf page} this file you will see something like that of Fig.~\ref{psg}. +\begin{figure} +\vspace{3.5in} +\caption{\label{psg} The ``point spread function group" file +{\bf n602csb.psg.1}} +\end{figure} +This contains the aperture photometry of each PSF star plus its neighbors, +with each set constituting a ``group". Running the psf-fitting photometry +routine {\bf nstar} will fit PSF's to each of the stars within a group +simultaneously. + +Before we run {\bf nstar}, however, we must decide what psf radius to use. +Why not simply keep it set to the value found above (e.g., something like 11 +pixels)? The answer to this is a bit subtle, but understanding it will +help you diagnose what is going wrong when you find a PSF going awry (and +don't worry, you will). Let's consider the case that you construct a PSF +from a single star with one neighbor whose center is 12 pixels away from +the center of the PSF star, and let's have the PSF radius be 11 and the PSF +fitting radius be 3. The PSF looks something like that of Fig.~\ref{bump}. +\begin{figure} +\vspace{5.0in} +\caption{\label{bump} The zeroth order PSF of a star with a neighbor 12 pixels +away.} +\end{figure} +The light from the neighbor star ``spills +over" into the PSF. + +What happens when you try to fit two PSF's simultaneously? The bump from the +PSF of the brighter star sits within the fitting radius of the fainter star, +and it is the sum of the PSF's which are being fit to each star (that's +what ``simultaneous" means). Thus there is an ``implicit subtraction" of +the fainter star simply from fitting the bumpy PSF to the brighter star, +and the brightness of the fainter star will be underestimated. The way +to avoid this is to see that the PSF of the brighter star does not come +within the fitting radius of the fainter star, and {\it that} we can +accomplish easily by truncating the PSF size to something like the separation +of the two stars minus the fitting radius. Thus in the example here +we would want to fit the two stars using PSF's that were only ($12-3=9$) +pixels in radius. It's true that there may still be light of the PSF +star beyond this radius, but that will matter only if the PSF star is still +going strong when you get within the {\it fitting radius} of the fainter +star. + +Now that we understand all that, run {\bf nstar}. Specify the appropriate +image name for ``image corresponding to photometry" and give it +the ``.psg" file {\bf n602csb.psg.1} for the ``input group file". +Remember to decrease +the {\bf psf radius} when it tries to verify that number. {\bf nstar} +will produce a photometry output file {\bf n60csb.nst.1}. +You can +subtract the fitted PSF's from these stars now by running {\bf substar}. +Again, {\bf verify} the PSF radius to the smaller value. When the routine +finishes, {\bf display} the resultant frame {\bf n60csb.sub.1.imh} and +take a look at the PSF stars...or rather, where the PSF stars (and their +neighbors) were. Are they subtracted cleanly? Does one of the PSF +stars have residuals that look the reverse of the residuals of the others? +If so, it would be best to reconstruct the PSF at this point throwing out +that star---possibly it has a neighbor hidden underneath it, or has something +else wrong with it. Are the variations in the cores of the subtracted image +consistent with photon statistics? To answer this you may want to play +around with {\bf imexamine} on both the original and subtracted images, +but if the stars have cleanly disappeared and you can't even tell where +they were, you are doing fine. + +The worst thing to find at this point +is that there is a systematic pattern with position on the chip. This +would indicate that the PSF is variable. There is the option for making +a variable PSF, but the assumption is that the PSF varies smoothly in x +and +y; usually this is not the case. (In the case of the non-flat TI chips +the variations are due to the potato-chip like shape.) If you {\it do} +decide the PSF is variable, be sure to use plenty of stars in making the +PSF. As it says in the ``help page", +twenty-five to thirty is then not an unreasonable number. If that +doesn't scare you off, nothing will. + +If the brightest stars have residuals that are systematically different than +those of the fainter stars, maybe that chip wasn't quite as linear as you +thought, or perhaps there are charge transfer problems. This proved to +be the case for the RCA CCD data being reduced here. In Fig.~\ref{yuko} +we show the residuals that result when we based our PSF on a star whose +peak counts were 30000 ADUs. +Empirically we found that stars with peaks of 18K ADUs (a mere 40K electrons) +were safe to use, with the result that the dynamic range of our data +was simply not quite as advertised. Although the PSF function broke down +above 18K, the chip remained ``linear" in the sense that aperture photometry +continued to give good results---the total number of counts continued to +scale right up to the A/D limit of 32,767 ADUs (72K electrons after bias +is allowed for). This appears to be a subtle charge transfer +\begin{figure} +\vspace{7.0in} +\caption{\label{yuko} A ``before" and ``after" pair of images, where the +PSF was constructed with a star that was too bright. Note the systematic +residuals for the two bright stars. A ``bad" PSF star would result in a +similar effect; however, in these data we found that there was always a +systematic effect if the PSF stars were about 18000 ADU.} +\end{figure} +problem. + +We will assume that you have gotten the PSF to the point where +the cores of the stars disappear cleanly, although there may be residuals +present due to the neighbors. Our next step is to get rid of these neighbors +so that you can make a cleaner PSF. Edit the {\bf nstar} output file +{\bf n602csb.nst.1} and delete the lines associated with the PSF stars, +leaving only the neighbors behind. You can recognize the PSF stars, as +they are the first entry in each group. When you are done with this +editing job, re-run {\bf substar}, using the edited ``.nst" file as the +photometry file. Again in running {\bf substar} make sure you {\bf verify} +the PSF radius to the smaller value you decided above. Examine the results +on the image display. Now the PSF stars should be there but the neighbors +should be cleanly subtracted. Are they? If so, you are ready to proceed. +If not, re-read the above and keep at it until you get those neighbors +reasonably well out of the frame. + +We can now run {\bf psf} on the subtracted frame---the one with only the +neighbors gone. We have added some noise by doing the subtraction, and +so we should reset {\bf datamin} to several sigma below the previously +used +value. We are going to have to do more typing this time when +we run it, as the defaults for things will get very confused when we +tell it that the ``Image for which to build PSF" is actually +{\bf n60csb.sub.1}. For the ``Aperture photometry file" we can tell +it the original photometry file {\bf n602csb.mag.1} if we want, or +even the old ``.psg" file {\bf n602csb.psg.1} since every star that +we are concerned about (PSF star plus neighbor) is there. Go ahead +and give it the next `version" number for the ``Output psf image" +{\bf n602csb.psf.2} and for the ``Output psf group file" +{\bf n602csb.psg.2}. +We can of course do this all on the command line: + +\centerline{ {\bf psf n602csb.sub.1 n602csb.mag.1 n602csb.psf.2 +n602csb.psg.2 datamin=-150.} } + +\noindent +An example is shown in Fig.~\ref{psf1}. +{\it This time make sure you take the +large psf radius.} +\begin{figure} +\vspace{7.0in} +\caption{\label{psf1} Making the first revision PSF using the frames with the +neighbors subtracted. Compare this to Fig. 23, which shows the +same region before the neighbors have been removed.} +\end{figure} +Make a new PSF using the cursor as before. + +How good is this revised PSF? There's only one way to find out: run +{\bf nstar} on the original frame, this time keeping the psf radius large. +Then do {\bf substar} and examine the frame with both the PSF stars and +neighbors subtracted. Does this show a substantial improvement over the +first version? Now that you have a cleaner PSF it may be necessary to repeat +this procedure (edit the {\bf n602csb.nst.2} file, remove the PSF stars, +run {\bf substar} using this edited file to produce a frame with the +just the neighbors subtracted this time using a better PSF, run {\bf psf} +on this improved subtracted frame) but probably not. + +\subsection{Doing the psf-fitting: {\bf allstar}.} +The next step is to go ahead and run simultaneous PSF-fitting on all +your stars, and produce a subtracted frame with these stars removed. +To do both these things you need only run {\bf allstar}. The defaults +are likely to be right: see Fig.~\ref{allstar}. +\begin{figure} +\vspace{3.5in} +\caption{\label{allstar} Running {\bf allstar}.} +\end{figure} +As you may imagine, {\bf allstar} produces a photometry file +{\bf n602csb.als.1}, and another subtracted image: {\bf imagename.sub.N}. + +Display the subtracted frame, and blink it against the original. Has +IRAF/daophot done a nice job? If the stars are clearly gone with a few +hidden ones now revealed, you can be proud of yourself---if the results +are disappointing, there is only one place to look, and that is in the +making of the PSF. Assuming that all is well, it is now time to +add those previously hidden stars into the photometry. +The easiest way to do this is to run {\bf daofind} on the subtracted +image. +Set the value of {\bf datamin} to a value several sigma lower +than what you had used earlier in case the subtraction process generated +some spuriously small values, and you will want to {\it increase} the +value of threshold by 1 or 2 sigma above what you used previously. +Why? Because the subtraction process has certainly added noise to the +frame, and if you don't do this you will be mainly adding spurious +detections. Use {\bf tvmark} as before to examine the results of {\bf +daofind}; remember that the coordinate file name will be +{\bf imagename.sub.N.coo.1} this time around. If you are really close, +but want to add a couple of stars, re-run {\bf tvmark} on this file +using +{\bf interactive+}; this will allow you to add (and delete) coordinates +from the file. + +Now run {\bf phot} using this new coordinate file as the input list. +However, you do want to use the {\it original} frame for this photometry; +otherwise the sky values for the newly found stars will be very messed +up owing to the many subtracted images. A new aperture photometry file +{\bf n602csb.mag.2} will have been produced. Use {\bf append} to +concatenate these two files: {\bf append n602csb.mag.1,n602csb.mag.2 +n602csb.mag.3}. You can now re-run {\bf allstar} using this combined +photometry file as the input. + +\subsection{Matching the frames} +In the example here we have been reducing the {\it B} frame of +a set of {\it UBV}. Once all three frames have been reduced it is often +necessary to do a little fiddling. Have the same stars been identified +in each group? In many cases you don't want the same stars to have been +identified in each clump---afterall, some stars are red, some are blue +(that's presumably why you are doing this afterall, right?), but in some +cases you may find that a clump was identified as three objects on the +{\it U} and the {\it V} frames and clearly should have been three on the +{\it B} frame but instead is four or two. What to do? + +Using {\bf tvmark} it is relatively easy to set this right. First we +need to use {\bf txdump} to produce a file for each frame that can be +displayed. Do something like an + +\centerline{ {\bf txdump n602csu.als.2 $>$ tvu}} + +\noindent +followed by an + +\centerline{ {\bf txdump n602csb.als.2 $>$ +tvb}} + +\noindent +and a + +\centerline{ {\bf +txdump n602csv.als.2 $>$ tvv}} + +\noindent +In each case select {\bf xc,yc} and use +{\bf MAG!=INDEF} as a selection criteria. Thus you will then have three text +files that contain only the x's and y's of the stars with photometry. + +Next display the three frames ({\bf display n602csu 1}, {\bf display +n602csb 2}, {\bf display n602csv 3}) and put colored dots up to denote +the different allstar stars: + +\centerline{ {\bf tvmark 1 tvu color=204 inter-},} + +\centerline{ +{\bf tvmark 2 tvb color=205 inter-},} + +\noindent +and + +\centerline{ {\bf tvmark 3 tvv color=206 +inter-}} + +\noindent +will give pleasing results. Zoom, pan, register, and blink +around the frames until you are convinced that you really do want to +add or delete a star here or there. If you want to add or delete a star to the +{\it U} frame list, do a + +\centerline{ {\bf tvmark 1 tvu color=203 inter+}} + +\noindent +You are +now in interactive mode, and centering the cursor on the star you want +to add and striking the ``a" key will append the x and y value of the +cursor the tvu list. Similarly, striking the ``u" key +will delete a star from the list if you are using IRAF v2.9 or later. +(For earlier versions you are just going to have to do a little +editing by hand, good luck!) The star you add or delete will have +a white dot appear on top of it. +If you need to switch to a different coordinate file, simply exit the +interactive {\bf tvmark} with a ``q" and re-execute it specifying, for +example, {\bf tvmark 3 tvv color=203 inter+}. + +When you are done with adding and deleting stars, then it is time to +redo the photometry. Do a {\bf phot n602csu coords=tvv datamin=100} +in order to generate new aperture photometry and sky values. These +can then be run through {\bf allstar}, and the procedure repeated for +each +of the frames. + +\subsection{Determining the Aperture Correction} + +The zero-point of your magnitudes have been set as follows. When you +ran {\bf phot} using a small aperture (3 pixels in the example above) +magnitudes were defined as -2.5 * log{(Counts above sky)/(Exposure +time)} + Const. +(The constant Const was hidden away in {\bf photpars} and is the +magnitude assigned to a star that had a total of one ADU per second +within the measuring aperture you used.) When you defined your PSF the +magnitudes of the PSF stars determined from the aperture photometry were +then used to set the zero-point of the PSF. However, your standard +stars were presumably measured (if you did things right) through a much +larger aperture, and what we must do now is measure how much brighter +the PSF would have been had its zero-point been tied to the same size +aperture used for the standard stars. + +We need to determine the aperture correction from the brightest, +unsaturated stars (so there will still be reasonable signal above sky +at the size of the large aperture); if you can pick out stars that are +reasonably well isolated, so much the better. If this sounds vaguely +familiar to you, you're right---this is basically what you did for +selecting PSF stars, and these would be a good starting point for +selecting stars for determining the aperture correction. Ideally you +would like to use at least five such stars, but since when is data +reduction ideal? Nevertheless, it is in the determination of the +aperture correction the largest uncertainty enters in doing CCD +photometry on crowded fields. + +We will first need to pick out the brightest, isolated stars and then +to subtract off any stars that might affect their being measured through +the large ``standard star" aperture (e.g., something like 15 pixels). +To do this we need good photometry of any of these neighbor stars, and +we describe two ways to do this (1) the very long complicated way, and +(2) the very short easy way: + +\begin{enumerate} + +\item {\bf Method 1: Using the image display} +We can also use {\bf tvmark} to mark the stars that we wish to use for +aperture photometry. First we should remind ourselves what are multiple +stars and what aren't: {\bf display} the image, and then use {\bf +tvmark} to mark the stars with {\bf allstar} photometry: + +\centerline{ {\bf display n602csb 1} } + +\centerline{ {\bf txdump n602csb.als.2 xc,yc yes $>$ tvb} } + +\centerline{ {\bf tvmark 1 tvb color=204 interact-} } + +\noindent +Now go through and mark the stars you want to use as the aperture +correction stars {\it plus any neighbors that might contribute light +to a large aperture centered on the bright stars:} + +\centerline{ {\bf tvmark 1 bapstars color=203 interact+ }} + +\noindent +Use the ``a" key to generate a list ({\bf bapstars}) of the approximate +{\it x} and {\it y} positions of these stars. Next run this list +through {\bf phot} to generate improved centers and good sky values: + +\centerline{ {\bf phot n602csb bapstars bapphot calgor=``centroid" } } + +\noindent +Next run the photometry output file {\bf bapphot} through {\bf group}: + +\centerline{ {\bf group n602csb bapphot default default crit=0.2} } + +\noindent +This will have generated a ``group" file {\bf n602csb.grp.1}. + +\noindent +Finally (!) run this group file through {\bf nstar}: + +\centerline{ {\bf nstar n602csb default default default} } + +\item {\bf Method 2: Using the ``.psg" files} +If you used a goodly number ($>3-5$, say) stars in +making the PSF, then we will simply use these stars as the aperture +correction stars. Your last {\bf nstar} run should have produced an +``{\bf .nst}" file that contains good photometry for the PSF stars {\it +and} their neighbors. (If you don't remember if you did this, run {\bf +nstar} using the ``{\bf .psg}" as the input group file.) Note that this +method relies upon the assumption that the sum of the psf radius and psf +fitting radius is about as large as the size of the large aperture you +will use, so that all the important neighbors have been included in the +point-spread-function group, but this is probably a reasonable +assumption. + +\end{enumerate} + +Now that we are done with the preliminaries (!!), +we now want to produce two files: one of them containing only the +neighbors that we wish to subtract off, and another containing only the +bright isolated stars which we want to use in computing the aperture +correction. To do this we will use {\bf group} to divide up the ``{\bf +.nst}" file (we could simply use the editor but that would be a lot of +work). First we will use {\bf txdump} on the {\bf nstar} file to see the magnitude +range covered by the PSF stars and their neighbors: hopefully there +won't be any overlap. To do this try + +\centerline{ {\bf txdump n602csb.nst.3 id,group,mag yes} } + +\noindent +In the example shown in Fig.~\ref{grouping} we see that the PSF stars +\begin{figure} +\vspace{2.0in} +\caption{\label{grouping} The three PSF stars and their groups.} +\end{figure} +have magnitudes of 13.9, 15.0, and 16.5 in the three groups; all the +neighbor stars are fainter than 17.0. Thus we can use {\bf select} +to create a file containing the +photometry of the faint stars: + +\centerline{ {\bf select n602csb.nst.3 n602csbsub} } + +\noindent +and answer {\bf MAG$>$17.0} when you are queried for the ``Boolean +expression". This will put the photometry of the stars you wish to get +rid of into the file {\bf n602csbsub}. Next do an + +\centerline{ {\bf txdump n602csb.nst.3 xc,yc $>$ n602csbap} } + +\noindent +and answer {\bf MAG$<$17.0} in response to ``Boolean expression". This +will put the {\it x} and {\it y} values of the stars we wish to use for +the aperture correction into the file +{\bf n602csbap}. Next subtract the stars in the first file: + +\centerline{ {\bf substar n602csb n602csbsub} } + +\noindent and accept the defaults. This will result in the subtracted +image {\bf n602csb.sub.N}. It is this file on which we wish to run +the aperture photometry to determine the aperture correction: + +\centerline{ +{\bf phot n602csb.sub.N n602csbap n602csbapresults apertures=3.,15. annulus=20. dannu=5.} } + +\noindent +You will see something like Fig.~\ref{apcor1} on your terminal. +In this example we've made the assumption that the aperture size that +set your zero-point in making the PSF was 3 pixels (i.e., what you used +with {\bf phot} Way Back When), and that the aperture size used on your +standard stars was 15 pixels. +\begin{figure} +\vspace{3.0in} +\caption{\label{apcor1} The aperture correction run of {\bf phot}.} +\end{figure} +It is time to drag out your hand calculator. Using all three stars we +find an average aperture correction of $-0.371$ with a standard +deviation of the mean of 0.012 mag; given the large range in magnitude, +I might have been tempted to ignore the two fainter stars and keep the +aperture correction based only upon the brightest star (the frame is +sparsely populated, and there isn't a whole heck of a lot else we can +do). By an amazing coincidence, the aperture correction based just on +the brightest star is also $-0.371$. + + +\subsection{{\bf daophot} summary} +\begin{itemize} +\item Set up {\bf datapars} and {\bf daopars}. + \begin{enumerate} + \item Do an {\bf imhead} on some image and note the keywords for the + filter position, the effective exposure time, and the effective + airmass. + \item Use {\bf display} and {\bf imexamine} on a few frames to + determine the typical full-width-half-max + of stars and what would be a good + value to use for the radius of the psf (i.e., what radius will + contain the brightest star for which you wish to do photometry.) + \item Enter these into {\bf daopars} (psfrad) and {\bf datapars} + (header key words, fwhm). Also check that the correct values + are entered in {\bf datapars} for the gain (photons per ADU) + and read-noise (in electrons), as well as the ``maximum good data + value". + \end{enumerate} +\item Find stars. + \begin {enumerate} + \item Do an {\bf implot} or {\bf imexamine} to determine the sky + level on your frame. Calculate the expected $1\sigma$ error. + \item Enter the sky value minus 3$\sigma$ as your value for + {\bf datamin} in {\bf datapars}. + \item Run {\bf daofind} using as a threshold value 3 to 5 $\sigma$. + \item Use {\bf tvmark} to mark the stars found ({\bf imagename.coo.1}). + If you need to, rerun {\bf daofind} with a larger or small + threshold. + \end {enumerate} +\item Run aperture photometry using {\bf phot}. +\item Generate a PSF. Run {\bf psf} and add stars using the ``a" key. Try + to select bright, uncrowded stars. Then: + \begin {enumerate} + \item Run {\bf nstar} using the file {\bf imagename.psg.1} as the + ``input photometry group" file. If there are neighbors, be sure + to decrease the psf radius as explained above. + Run {\bf substar} (also using the smaller sized psf radius) + and display the + resultant subtracted frame {\bf imagename.sub.1}. Do the residuals + of the PSF stars look consistent, or is one of them funny? If need + be, start over. + \item Remove any neighbor stars by editing the PSF stars out of the + ``.nst" file, and rerunning {\bf substar}. Run + {\bf psf} on the subtracted file, using the normal psf radius again. + You will have to over-ride the defaults for the input and output file + names now that you are using the subtracted image. Rerun {\bf nstar} + on the original frame using the normal psf radius and the revised + PSF. Run {\bf substar} and display the results. Are the PSF stars + nicely removed, and do the areas around the PSF stars look clean? + It may be necessary to remove neighbors again using this revised + PSF. + \end {enumerate} +\item Run {\bf allstar}. Display the subtracted frame and see if your stars + have been nicely subtracted off. +\item Run {\bf daofind} on the subtracted frame, using a value for + {\bf threshold} which is another $\sigma$ or two larger than before, + and a value for {\bf datamin} which is several $\sigma$ lower than + before. Use {\bf tvmark} to examine the results, and if need be + run {\bf tvmark} interactively so that you may add any extra stars. +\item Run aperture photometry using {\bf phot} {\it on the original frame}, + using the new coordinate list produced above. +\item {\bf append} the two aperture photometry files. +\item Run {\bf allstar} using the combine photometry file. +\item Repeat all of the above for each frame in your ``set" (e.g., all short + and long exposures in each filter of a single field, say. +\item Use {\bf txdump} to select the stars from the allstar files which + have magnitudes not equal to ``INDEF". Mark these stars using + {\bf tvmark}, and then use the capabilities of the image display + and {\bf tvmark} to match stars consistently from frame to frame. + Rerun {\bf phot} and {\bf allstar} on the final coordinate lists. +\item Determine the aperture corrections. +\item Transform + to the standard system (see the next section) and then + publish the results. +\end{itemize} +\section{Transforming to the Standard System} + +This section will eventually tell you how to easily and painless obtain +the transformation equations for going from your instrumental magnitudes +to the standard system, and how to apply these transformation equations +to your program fields. Unfortunately, the IRAF routines for doing this +are still under construction. +In the meanwhile, we are providing here a kludge solution that can be +used by initiates of Stetson's VMS CCDCAL routines. If you haven't been +made a member of the club yet, and don't feel like waiting until the +IRAF routines are become available before you get results, then I would +recommend getting a hold of the good Dr. Stetson and bribing him until he +offers to send you a copy of CCDCAL. There is an excellent manual that +comes along with it, and we will not attempt to repeat any of that +material here. + +\subsection{Standard Star Solution} +First we will describe how to get output good enough to fool +the CCDCAL software into believing the photometry was produced by CCDOBS +(for the standard magnitudes), and what modifications need to be made +to CCDSTD.FOR + +On the standard file do a {\bf txdump standstuff lid,ifilt,xair,mag,merr +$>$ foolit} to dump the star number, filter number, airmass, and +instrumental magnitudes and errors into the file {\bf foolit}. +Unfortunately, you are now going to have to edit this file and stick in +the star name (in what ever form you have it in creating the library of +standard stars with CCDLIB) in place of the image name and star ID. +(These were simply placed in the file to help guide you). While you are +at it, line up the filter numbers, airmasses, and magnitudes into nice, +neat columns. When you get done, stick in a line at the top that gives +the number of instrumental magnitudes and their names, using a +i1,13x,n(6x,a6) format. For instance, in the case shown here there +are 3 instrumental magnitudes, U, B, and V. Finally, the filter numbers +have to be edited so they agree with these (e.g., they must denote +instrumental magnitude 1, 2, and 3...now aren't you sorry you didn't +decide to wait until the IRAF routines were finished?). In +Fig~\ref{groan} we show an example of the ``before" and ``after" file. +\begin{figure} +\vspace{3.5in} +\caption{\label{groan}The output of {\bf txdump} and the final file +ready for {\bf ccdstd}. Note the switching of the filter number ``5" +with ``1".} +\end{figure} + +CCDOBS.FOR itself now needs to be modified. Search for line statement +``1120" (which will say JSTAR=JSTAR+1). Add a line that sets the +integration time to 1 (tint=1.). Modify the READ statement as shown +in Fig.~\ref{ccdobs}, and finally modify the 213 FORMAT statement +so it actually matches your data file. +\begin{figure} +\vspace{2.5in} +\caption{\label{ccdobs} Modifications to CCDOBS.FOR} +\end{figure} +You should now be able to compile, link, and run this modified +version of CCDOBS and have it work on your standard star data. + +\subsection{Program Stars} +The work required for faking ``CCDCAL" is actually a lot less. The data +files are easily produced. Do a + +\centerline{{\bf txdump n602csu.als.2 +id,xc,yc,mag,merr,nit,chi $>$ csu} } + +\centerline{{\bf txdump n602csb.als.2 id,xc,yc,mag,merr,nit,chi $>$ +csb}} + +\centerline{{\bf txdump n602csv.als.2 id,xc,yc,mag,merr,nit,chi $>$ +csv}} + +\noindent +answering {\bf MAG!=INDEF} to ``boolean expression" each time. +These three files ({\bf csu}, {\bf csb}, {\bf csv} can be used +with CCDCAL once a single modification is made to CCDCAL.FOR: on +statement number 2020 change the format to ``free format", e.g., +2020 IF(NL(IOBS).NE.2) READ(2,*,END=2040). When CCDCAL queries +you for an integration time, be sure to tell it 1.0, as your data have +already been corrected for exposure times. + +\section{Acknowledgements} +We are grateful to Jeannette Barnes and Carol Neese for critical +readings of this document, although final blame for style and content +of course rests with the authors. +\end{document} diff --git a/noao/digiphot/daophot/doc/userdocs/daoref.ms b/noao/digiphot/daophot/doc/userdocs/daoref.ms new file mode 100644 index 00000000..6ef3d1f6 --- /dev/null +++ b/noao/digiphot/daophot/doc/userdocs/daoref.ms @@ -0,0 +1,6290 @@ +.LP +\0 +.de XS +.DS +.ps -1 +.vs -1p +.ft CB +.. +.de XE +.DE +.ft R +.ps +.vs +.. +.de YS +.nf +.ps -1 +.vs -1p +.ft CB +.. +.de YE +.fi +.ft R +.ps +.vs +.. +.RP +.TL +A Reference Guide to the IRAF/DAOPHOT Package +.AU +Lindsey E. Davis +.AI +IRAF Programming Group +.K2 +.ce +.TU +.br +.ce +January 1994 +.AB +.PP +DAOPHOT is a software package for doing stellar photometry in crowded stellar +fields +developed by Peter Stetson (1987) of the Dominion Astrophysical +Observatory. IRAF/DAOPHOT uses the task structure and +algorithms of DAOPHOT to do crowded-field stellar photometry within the +IRAF data reduction and analysis environment. +.PP +This document briefly describes the principal similarities and differences +between DAOPHOT and IRAF/DAOPHOT, the data preparation required to +successfully use IRAF/DAOPHOT, how to examine and edit the IRAF/DAOPHOT +algorithm parameters, how to run the IRAF/DAOPHOT package tasks interactively, +non-interactively, or in the background, and how to examine +and perform simple database operations on the output photometry files. +.PP +This document is +intended as a reference guide to the details of using and +interpreting the results of IRAF/DAOPHOT not a user's cookbook or a general +guide to doing photometry in IRAF. Its goal is to take the user +from a fully reduced image of a crowded stellar field to aperture +corrected instrumental magnitudes using a small artificial image as a +sample data set. +First time IRAF/DAOPHOT users +should consult \fIA User's Guide to Stellar Photometry With IRAF\fR, by +Phil Massey and Lindsey Davis. Detailed descriptions of the DAOPHOT photometry +algorithms can be found in Stetson (1987, 1990, 1992). +.AE +.ds CH +.bp +\0 +.bp +.PP +.na +.LP +\fBContents\fP +.sp 1 +1.\h'|0.4i'\fBIntroduction\fP\l'|5.6i.'\0\01 +.sp +2.\h'|0.4i'\fBDAOPHOT and IRAF/DAOPHOT\fP\l'|5.6i.'\0\01 +.sp +3.\h'|0.4i'\fBPreparing Data for DAOPHOT\fP\l'|5.6i.'\0\03 +.sp +4.\h'|0.4i'\fBSome IRAF Basics for New IRAF and DAOPHOT Users\fP\l'|5.6i.'\0\04 +.br +.sp +\h'|0.4i'4.1.\h'|0.9i'\fBPre-loaded Packages\fP\l'|5.6i.'\0\04 +.br +\h'|0.9i'4.1.1.\h'|1.5i'The DATAIO Package\l'|5.6i.'\0\05 +.br +\h'|0.9i'4.1.2.\h'|1.5i'The PLOT Package\l'|5.6i.'\0\05 +.br +\h'|0.9i'4.1.3.\h'|1.5i'The IMAGES Package\l'|5.6i.'\0\05 +.br +\h'|0.9i'4.1.4.\h'|1.5i'The TV Package\l'|5.6i.'\0\05 +.br +\h'|0.4i'4.2.\h'|0.9i'\fBOther Useful Packages and Tasks\fP\l'|5.6i.'\0\05 +.br +\h'|0.4i'4.3.\h'|0.9i'\fBImage Types, Image Directories, and Image Headers\fP\l'|5.6i.'\0\05 +.br +\h'|0.4i'4.4.\h'|0.9i'\fBThe Image Display and Image Cursor\fP\l'|5.6i.'\0\06 +.br +\h'|0.4i'4.5.\h'|0.9i'\fBThe Graphics Device and Graphics Cursor\fP\l'|5.6i.'\0\07 +.sp +5.\h'|0.4i'\fBSome DAOPHOT Basics for New DAOPHOT Users\fP\l'|5.6i.'\0\08 +.br +.sp +\h'|0.4i'5.1.\h'|0.9i'\fBLoading the DAOPHOT Package\fP\l'|5.6i.'\0\08 +.br +\h'|0.4i'5.2.\h'|0.9i'\fBLoading the TABLES Package\fP\l'|5.6i.'\0\08 +.br +\h'|0.4i'5.3.\h'|0.9i'\fBRunning the Test Script\fP\l'|5.6i.'\0\08 +.br +\h'|0.4i'5.4.\h'|0.9i'\fBOn-line Help\fP\l'|5.6i.'\0\09 +.br +\h'|0.4i'5.5.\h'|0.9i'\fBEditing the Package Parameters\fP\l'|5.6i.'\010 +.br +\h'|0.4i'5.6.\h'|0.9i'\fBEditing the Task Parameters\fP\l'|5.6i.'\011 +.br +\h'|0.4i'5.7.\h'|0.9i'\fBInput and Output Image Names\fP\l'|5.6i.'\011 +.br +\h'|0.4i'5.8.\h'|0.9i'\fBInput and Output File Names\fP\l'|5.6i.'\012 +.br +\h'|0.4i'5.9.\h'|0.9i'\fBAlgorithm Parameter Sets\fP \l'|5.6i.'\012 +.br +\h'|0.4i'5.10.\h'|0.9i'\fBInteractive Mode and Non-Interactive Mode\fP \l'|5.6i.'\014 +.br +\h'|0.4i'5.11.\h'|0.9i'\fBImage and Graphics Cursor Input\fP\l'|5.6i.'\014 +.br +\h'|0.4i'5.12.\h'|0.9i'\fBGraphics Output\fP\l'|5.6i.'\015 +.br +\h'|0.4i'5.13.\h'|0.9i'\fBVerify, Update, and Verbose\fP\l'|5.6i.'\015 +.br +\h'|0.4i'5.14.\h'|0.9i'\fBBackground Jobs\fP\l'|5.6i.'\015 +.br +\h'|0.4i'5.15.\h'|0.9i'\fBTiming Tests\fP\l'|5.6i.'\016 +.sp +6.\h'|0.4i'\fBDoing Photometry with DAOPHOT\fP\l'|5.6i.'\016 +.br +.sp +\h'|0.4i'6.1.\h'|0.9i'\fBThe Test Image\fP\l'|5.6i.'\016 +.br +\h'|0.4i'6.2.\h'|0.9i'\fBTypical Analysis Sequence\fP\l'|5.6i.'\017 +.br +\h'|0.4i'6.3.\h'|0.9i'\fBCreating and Organizing an Analysis Directory\fP\l'|5.6i.'\019 +.br +\h'|0.4i'6.4.\h'|0.9i'\fBReading the Data\fP \l'|5.6i.'\019 +.br +\h'|0.4i'6.5.\h'|0.9i'\fBEditing the Image Headers\fP\l'|5.6i.'\019 +.br +\h'|0.9i'6.5.1.\h'|1.5i'The Minimum Image Header Requirements\l'|5.6i.'\019 +.br +\h'|0.9i'6.5.2.\h'|1.5i'The Effective Gain and Readout Noise\l'|5.6i.'\019 +.br +\h'|0.9i'6.5.3.\h'|1.5i'The Maximum Good Data Value\l'|5.6i.'\021 +.br +\h'|0.9i'6.5.4.\h'|1.5i'The Effective Exposure Time\l'|5.6i.'\022 +.br +\h'|0.9i'6.5.5.\h'|1.5i'The Airmass, Filter Id, and Time of Observation\l'|5.6i.'\022 +.br +\h'|0.9i'6.5.6.\h'|1.5i'Batch Header Editing\l'|5.6i.'\024 +.br +\h'|0.4i'6.6.\h'|0.9i'\fBEditing, Checking, and Storing the Algorithm Parameters\fP\l'|5.6i.'\024 +.br +\h'|0.9i'6.6.1.\h'|1.5i'The Critical Algorithm Parameters\l'|5.6i.'\024 +.br +\h'|0.9i'6.6.2.\h'|1.5i'Editing the Algorithm Parameters Interactively with Daoedit \l'|5.6i.'\024 +.br +\h'|1.5i'6.6.2.1.\h'|2.2i'The Data Dependent Algorithm Parameters \l'|5.6i.'\025 +.br +\h'|1.5i'6.6.2.2.\h'|2.2i'The Centering Algorithm Parameters\l'|5.6i.'\028 +.br +\h'|1.5i'6.6.2.3.\h'|2.2i'The Sky Fitting Algorithm Parameters\l'|5.6i.'\029 +.br +\h'|1.5i'6.6.2.4.\h'|2.2i'The Aperture Photometry Parameters\l'|5.6i.'\029 +.br +\h'|1.5i'6.6.2.5.\h'|2.2i'The Psf Modeling and Fitting Parameters\l'|5.6i.'\030 +.br +\h'|1.5i'6.6.2.6.\h'|2.2i'Setting the Algorithm Parameters Graphically\l'|5.6i.'\031 +.br +\h'|0.9i'6.6.3.\h'|1.5i'Checking the Algorithm Parameters with Daoedit\l'|5.6i.'\031 +.br +\h'|0.9i'6.6.4.\h'|1.5i'Storing the Algorithm Parameter Values with Setimpars\l'|5.6i.'\032 +.br +\h'|0.9i'6.6.5.\h'|1.5i'Restoring the Algorithm Parameter Values with Setimpars\l'|5.6i.'\032 +.br +\h'|0.4i'6.7.\h'|0.9i'\fBCreating a Star List\fP\l'|5.6i.'\032 +.br +\h'|0.9i'6.7.1.\h'|1.5i'The Daofind Task\l'|5.6i.'\033 +.br +\h'|1.5i'6.7.1.1.\h'|2.2i'The Daofind Algorithm\l'|5.6i.'\033 +.br +\h'|1.5i'6.7.1.2.\h'|2.2i'The Daofind Algorithm Parameters\l'|5.6i.'\033 +.br +\h'|1.5i'6.7.1.3.\h'|2.2i'Running Daofind Non-Interactively\l'|5.6i.'\034 +.br +\h'|1.5i'6.7.1.4.\h'|2.2i'Running Daofind Interactively\l'|5.6i.'\034 +.br +\h'|1.5i'6.7.1.5.\h'|2.2i'The Daofind Output\l'|5.6i.'\036 +.br +\h'|1.5i'6.7.1.6.\h'|2.2i'Examining the Daofind Output\l'|5.6i.'\037 +.br +\h'|0.9i'6.7.2.\h'|1.5i'Rgcursor and Rimcursor\l'|5.6i.'\038 +.br +\h'|0.9i'6.7.3.\h'|1.5i'User Program\l'|5.6i.'\039 +.br +\h'|0.9i'6.7.4.\h'|1.5i'Modifying an Existing Coordinate List\l'|5.6i.'\039 +.br +\h'|0.4i'6.8.\h'|0.9i'\fBInitializing the Photometry with Phot\fP\l'|5.6i.'\039 +.br +\h'|0.9i'6.8.1.\h'|1.5i'The Phot Algorithm\l'|5.6i.'\039 +.br +\h'|0.9i'6.8.2.\h'|1.5i'The Phot Algorithm Parameters\l'|5.6i.'\040 +.br +\h'|0.9i'6.8.3.\h'|1.5i'Running Phot Non-interactively\l'|5.6i.'\040 +.br +\h'|0.9i'6.8.4.\h'|1.5i'Running Phot Interactively\l'|5.6i.'\042 +.br +\h'|0.9i'6.8.5.\h'|1.5i'The Phot Output\l'|5.6i.'\043 +.br +\h'|0.9i'6.8.6.\h'|1.5i'Examining the Results of Phot\l'|5.6i.'\044 +.br +\h'|0.4i'6.9.\h'|0.9i'\fBCreating a Psf Star List with Pstselect\fP\l'|5.6i.'\044 +.br +\h'|0.9i'6.9.1.\h'|1.5i'The Pstselect Algorithm\l'|5.6i.'\045 +.br +\h'|0.9i'6.9.2.\h'|1.5i'The Pstselect Algorithm Parameters\l'|5.6i.'\045 +.br +\h'|0.9i'6.9.3.\h'|1.5i'How Many Psf Stars Should Be Selected ?\l'|5.6i.'\046 +.br +\h'|0.9i'6.9.4.\h'|1.5i'Running Pstselect Non-interactively\l'|5.6i.'\047 +.br +\h'|0.9i'6.9.5.\h'|1.5i'Running Pstselect Interactively\l'|5.6i.'\047 +.br +\h'|0.9i'6.9.6.\h'|1.5i'The Pstselect Output\l'|5.6i.'\048 +.br +\h'|0.9i'6.9.7.\h'|1.5i'Examining and/or Editing the Results of Pstselect\l'|5.6i.'\048 +.br +\h'|0.4i'6.10.\h'|0.9i'\fBComputing the Psf Model with Psf\fP\l'|5.6i.'\049 +.br +\h'|0.9i'6.10.1.\h'|1.5i'The Psf Algorithm\l'|5.6i.'\049 +.br +\h'|0.9i'6.10.2.\h'|1.5i'Choosing the Appropriate Analytic Function\l'|5.6i.'\050 +.br +\h'|0.9i'6.10.3.\h'|1.5i'The Analytic Psf Model\l'|5.6i.'\050 +.br +\h'|0.9i'6.10.4.\h'|1.5i'The Empirical Constant Psf Model\l'|5.6i.'\051 +.br +\h'|0.9i'6.10.5.\h'|1.5i'The Empirical Variable Psf Model\l'|5.6i.'\051 +.br +\h'|0.9i'6.10.6.\h'|1.5i'Rejecting Bad Data from the Psf Model\l'|5.6i.'\051 +.br +\h'|0.9i'6.10.7.\h'|1.5i'The Model Psf Psfrad and Fitrad\l'|5.6i.'\052 +.br +\h'|0.9i'6.10.8.\h'|1.5i'Modeling the Psf Interactively Without a Psf Star List\l'|5.6i.'\052 +.br +\h'|0.9i'6.10.9.\h'|1.5i'Fitting the Psf Model Interactively Using an Initial Psf Star List\l'|5.6i.'\054 +.br +\h'|0.9i'6.10.10.\h'|1.5i'Fitting the Psf Model Interactively Without an Image Display\l'|5.6i.'\055 +.br +\h'|0.9i'6.10.11.\h'|1.5i'Fitting the Psf Model Non-interactively\l'|5.6i.'\056 +.br +\h'|0.9i'6.10.12.\h'|1.5i'The Output of Psf\l'|5.6i.'\057 +.br +\h'|0.9i'6.10.13.\h'|1.5i'Checking the Psf Model\l'|5.6i.'\059 +.br +\h'|0.9i'6.10.14.\h'|1.5i'Removing Bad Stars from the Psf Model\l'|5.6i.'\062 +.br +\h'|0.9i'6.10.15.\h'|1.5i'Adding New Stars to a Psf Star Group\l'|5.6i.'\062 +.br +\h'|0.9i'6.10.16.\h'|1.5i'Refitting the Psf Model With the New Psf Star Groups\l'|5.6i.'\062 +.br +\h'|0.9i'6.10.17.\h'|1.5i'Computing the Final Psf Model\l'|5.6i.'\063 +.br +\h'|0.9i'6.10.18.\h'|1.5i'Visualizing the Psf Model with the Seepsf Task\l'|5.6i.'\063 +.br +\h'|0.9i'6.10.19.\h'|1.5i'Problems Computing the Psf Model\l'|5.6i.'\064 +.br +\h'|0.4i'6.11.\h'|0.9i'\fBDoing Psf Fitting Photometry with Peak, Nstar, or Allstar\fP \l'|5.6i.'\065 +.br +\h'|0.9i'6.11.1.\h'|1.5i'Fitting Single Stars with Peak\l'|5.6i.'\065 +.br +\h'|1.5i'6.11.1.1.\h'|2.2i'The Peak Algorithm\l'|5.6i.'\065 +.br +\h'|1.5i'6.11.1.2.\h'|2.2i'Running Peak \l'|5.6i.'\065 +.br +\h'|1.5i'6.11.1.3.\h'|2.2i'The Peak Output\l'|5.6i.'\066 +.br +\h'|0.9i'6.11.2.\h'|1.5i'Fitting Stars with Group, Grpselect, Nstar and Substar\l'|5.6i.'\067 +.br +\h'|1.5i'6.11.2.1.\h'|2.2i'The Group and Nstar Algorithms\l'|5.6i.'\067 +.br +\h'|1.5i'6.11.2.2.\h'|2.2i'Running Group, Grpselect, and Nstar\l'|5.6i.'\068 +.br +\h'|1.5i'6.11.2.3.\h'|2.2i'The Nstar Output\l'|5.6i.'\070 +.br +\h'|0.9i'6.11.3.\h'|1.5i'Fitting Stars With Allstar\l'|5.6i.'\071 +.br +\h'|1.5i'6.11.3.1.\h'|2.2i'The Allstar Algorithm\l'|5.6i.'\071 +.br +\h'|1.5i'6.11.3.2.\h'|2.2i'Running Allstar\l'|5.6i.'\072 +.br +\h'|1.5i'6.11.3.3.\h'|2.2i'The Allstar Output\l'|5.6i.'\073 +.br +\h'|0.4i'6.12.\h'|0.9i'\fBExamining the Output Photometry Files\fP\l'|5.6i.'\073 +.br +\h'|0.4i'6.13.\h'|0.9i'\fBProblems with the Photometry\fP\l'|5.6i.'\074 +.br +\h'|0.4i'6.14.\h'|0.9i'\fBDetecting Stars Missed By Daofind\fP\l'|5.6i.'\075 +.br +\h'|0.4i'6.15.\h'|0.9i'\fBInitializing the Missing Star Photometry with Phot\fP\l'|5.6i.'\075 +.br +\h'|0.4i'6.16.\h'|0.9i'\fBMerging Photometry Files with Pfmerge\fP\l'|5.6i.'\076 +.br +\h'|0.4i'6.17.\h'|0.9i'\fBRefitting the Stars with Allstar\fP\l'|5.6i.'\076 +.br +\h'|0.4i'6.18.\h'|0.9i'\fBExamining the Subtracted Image\fP\l'|5.6i.'\076 +.br +\h'|0.4i'6.19.\h'|0.9i'\fBComputing an Aperture Correction\fP\l'|5.6i.'\076 +.sp +7.\h'|0.4i'\fBReferences\fP\l'|5.6i.'\077 +.sp +8.\h'|0.4i'\fBAppendices\fP\l'|5.6i.'\077 +.br +.sp +\h'|0.4i'8.1.\h'|0.9i'\fBThe Instrumental Magnitude Scale\fP\l'|5.6i.'\077 +.br +\h'|0.4i'8.2.\h'|0.9i'\fBThe Analytic Psf Models\fP\l'|5.6i.'\077 +.br +\h'|0.4i'8.3.\h'|0.9i'\fBThe Error Model\fP\l'|5.6i.'\078 +.br +\h'|0.4i'8.4.\h'|0.9i'\fBThe Radial Weighting Function\fP\l'|5.6i.'\078 +.br +\h'|0.4i'8.5.\h'|0.9i'\fBTotal Weights\fP\l'|5.6i.'\078 +.br +\h'|0.4i'8.6.\h'|0.9i'\fBBad Data Detection\fP\l'|5.6i.'\078 +.br +\h'|0.4i'8.7.\h'|0.9i'\fBStellar Mergers\fP\l'|5.6i.'\079 +.br +\h'|0.4i'8.8.\h'|0.9i'\fBFaint Stars\fP\l'|5.6i.'\079 +.br +.bp +\0 +.ds CH - % - +.bp 1 +\0 + +.TL +A Reference Guide to the IRAF/DAOPHOT Package +.AU +Lindsey E. Davis +.AI +IRAF Programming Group +.K2 +.ce +.TU +.br +.ce +January 1994 + +.NH +Introduction + +.PP +DAOPHOT is a software package for doing stellar photometry +in crowded fields developed by Peter Stetson of the DAO (1987, 1990, 1992). +The IRAF/DAOPHOT package uses the task structure and algorithms of DAOPHOT +to do crowded field photometry within the IRAF data reduction and +analysis environment. +.PP +Input to IRAF/DAOPHOT consists of an IRAF image file, numerous parameters +controlling the analysis algorithms and, optionally, graphics cursor and/or +image display cursor input. IRAF/DAOPHOT produces output photometry files +in either text format or STSDAS binary table format. Some IRAF/DAOPHOT tasks +also produce image output and graphics output in the form of plot metacode +files. +.PP +Separate tasks are provided for examining, editing, storing, and recalling +the analysis parameters, creating and editing star +lists, computing accurate centers, sky values and initial magnitudes +for the stars in the list, computing the point-spread function, +grouping the stars into physical associations, fitting the stars either +singly or in groups, subtracting the fitted stars from the original image, +and adding artificial test stars to the original image. A set of tools are +also provided for examining and editing the output photometry files. + +.NH +DAOPHOT and IRAF/DAOPHOT + +.PP +The principal similarities and differences between DAOPHOT and IRAF/DAOPHOT +are summarized below. +.IP [1] +The structure of IRAF/DAOPHOT is very similar to the +structure of DAOPHOT. All the DAOPHOT photometry tasks and many of +the utilities tasks are present in +IRAF/DAOPHOT and in many cases the DAOPHOT task names have been preserved. +A listing of the DAOPHOT photometry tasks and their closest IRAF/DAOPHOT +equivalents is shown below. + +.TS +l l +l l +l l. +DAOPHOT\tIRAF/DAOPHOT +TASK\tEQUIVALENT + +add*\taddstar +allstar\tallstar +attach\tN/A +append\tpfmerge,pconcat +find\tdaofind +group\tgroup +monitor\tdaophot.verbose=yes +nomonitor\tdaophot.verbose=no +nstar\tnstar +offset\tpcalc +options\tdaoedit +peak\tpeak +photometry\tphot +pick\tpstselect +psf\tpsf +select\tgrpselect +sort\tpsort,prenumber +sub*\tsubstar +.TE + +.IP [2] +Some DAOPHOT utilities tasks are missing from IRAF/DAOPHOT. +The DAOPHOT tasks \fBdump\fR, \fBexit\fR, \fBfudge\fR, +\fBhelp\fR, \fBlist\fR, and \fBsky\fR +have been replaced with general IRAF tasks, or with IRAF system facilities +that perform the equivalent function. The missing DAOPHOT utilities tasks +and their IRAF equivalents are shown below. + +.TS +l l +l l +l l. +DAOPHOT\tIRAF/DAOPHOT +TASK\tEQUIVALENT + +dump\tlistpixels,imexamine +exit\tbye +fudge\timreplace,fixpix,imedit +help\thelp daophot +list\timheader +sky\timstatistics,phistogram,imexamine +.TE + +.IP [3] +The IRAF/DAOPHOT default algorithms are the DAOPHOT II algorithms +(Stetson 1992). +.IP [4] +Users have more choice of and control over the algorithms +in IRAF/DAOPHOT than they do in DAOPHOT. For example the +IRAF/DAOPHOT aperture photometry task \fBphot\fR offers several +sky fitting algorithms besides the default "mode" algorithm, +and full control over the sky fitting algorithm parameters. +.IP [5] +The algorithm parameters in IRAF/DAOPHOT are grouped by function into +six parameter sets or psets rather than three as in DAOPHOT. +The six IRAF/DAOPHOT parameter sets with their DAOPHOT equivalents +in brackets are: +1) \fBdatapars\fR, the data definition parameters (daophot.opt), +2) \fBfindpars\fR, the detection algorithm parameters (daophot.opt), +3) \fBcenterpars\fR, the aperture photometry centering algorithm parameters +(no equivalent), +4) \fBfitskypars\fR, the aperture photometry sky fitting parameters (photo.opt), +5) \fBphotpars\fR, the aperture photometry parameters (photo.opt), +6) \fBdaopars\fR, the IRAF/DAOPHOT psf fitting parameters (daophot.opt, +allstar.opt). +.IP [6] +The IRAF/DAOPHOT algorithm parameter sets unlike the DAOPHOT parameter sets +can be interactively examined, +edited and saved with the \fBdaoedit\fR task using the image display +and radial profile plots. +.IP [7] +The IRAF/DAOPHOT algorithm parameter sets unlike the DAOPHOT parameter sets +can be saved and restored as a function of image using the \fBsetimpars\fR task. +.IP [8] +Memory allocation in IRAF/DAOPHOT is dynamic not static as in +DAOPHOT. IRAF/DAOPHOT allocates and frees memory as required +at run-time subject to the physical memory and swap space limitations of +the host computer. +.IP [9] +The IRAF/DAOPHOT point-spread function look-up table is stored in an +IRAF image not an ASCII table as in DAOPHOT. +.IP [10] +Unlike DAOPHOT, the IRAF/DAOPHOT tasks \fBdaofind\fR, \fBphot\fR, +\fBpstselect\fR +and \fBpsf\fR can be run interactively using the image display and graphics +window or non-interactively. Display and graphics capabilities were +deliberately omitted from DAOPHOT to minimize portability problems. +.IP [11] +The IRAF/DAOPHOT output photometry files can be written in either text +format as in DAOPHOT or STSDAS binary table format. +.IP [12] +Unlike DAOPHOT, fields or columns in both IRAF/DAOPHOT text and +STSDAS binary table photometry files are identified +by name and have an associated units and format specifier. +The IRAF/DAOPHOT photometry file input routines search for column +names, for example "GROUP,ID,XCENTER,YCENTER,MAG,MSKY" as +appropriate but are independent +of their placement in the input file. +.IP [13] +Several general purpose IRAF/DAOPHOT tasks are available for performing +operations on the final output photometry catalogs. In addition to +\fBpcalc\fR, \fBpconcat\fR, \fBpfmerge\fR, \fBprenumber\fR, +and \fBpsort\fR which are +also available in DAOPHOT, there are three photometry file editing tasks which +have no analog in DAOPHOT \fBpdump\fR, \fBpexamine\fR, and \fBpselect\fR. +All these tasks work on IRAF/DAOPHOT output text files or STSDAS binary +tables. An IRAF/DAOPHOT task is supplied for converting output text files to +STSDAS binary tables so as to make use of the even more general STSDAS +tables manipulation tools in the TABLES package. +.IP [14] +The IRAF/DAOPHOT output files are self-documenting. +All the information required to comprehend the history of or decode the +output photometry file is in the file itself, including the IRAF version +number, host computer, date, time, and names of all the +input and output files and the values of all the parameters. +.PP +For the remainder of this document IRAF/DAOPHOT will be referred to +as DAOPHOT. + +.NH +Preparing Data for DAOPHOT + +.IP [1] +DAOPHOT assumes that the images to be analyzed exist on disk in IRAF +image format. DAOPHOT can read and write old IRAF format ".imh" images +and ST IRAF format ".hhh" images. +When the IRAF FITS kernel becomes available DAOPHOT will be able +to read FITS images on disk as well. +QPOE IRAF format ".qp" images must be rasterized before they can +be input to DAOPHOT. +.IP [2] +All internal DAOPHOT calculations are done in real precision. +The pixel type of the image data on disk may be any of the following +data types: short integer, unsigned short integer, integer, long integer, +real or double. Users should realize that the extra precision in +images of type double will not be used by DAOPHOT. +.IP [3] +The instrumental signature must be removed from the input images +prior to running DAOPHOT. All CCD images should be overscan +corrected, bias corrected, dark current corrected and flat-fielded. +Users should be aware of the IRAF CCDRED package for reducing CCD data. +.IP [4] +DAOPHOT assumes that the input pixel data is linear. +If the data is non-linear over a large fraction of its total dynamic range, +the data must be linearized before running DAOPHOT. +.IP [5] +Saturated pixels or pixels distinguishable from good data by intensity, +do not need to be removed from the image prior to running DAOPHOT. +For example if the data +is non-linear only above 25000 counts, DAOPHOT can be instructed to +ignore pixels above 25000 counts. +.IP [6] +Extreme-valued pixels should be removed from the images prior to running +DAOPHOT. Extreme-valued pixels include those with values at or near +the floating point limits of the host machine and host machine special +numbers produced by operations like divide by zero, floating point +underflows and overflows, etc. The latter category of extreme-valued +pixels should not be produced by IRAF software, but may be produced by +user programs including imfort programs. +Floating point operations involving such numbers will frequently cause +arithmetic exception errors, since for efficiency and portability reasons +the DAOPHOT package and most IRAF tasks do not test for +their presence. +The \fBimreplace\fR task in the PROTO package can be used to remove extreme- +valued pixels. +.IP [7] +The background sky value should NOT be subtracted from the image prior +to entering the DAOPHOT package. The DAOPHOT fitting routines use an optimal +weighting scheme which depends on the readout noise, the gain, and the +true counts in the pixels. If the mean sky has been subtracted +then the counts in the image are not the true counts and the computed weights +will be incorrect. For similar reasons users should not attempt to +correct their magnitudes for exposure time by dividing their images +by the exposure time. +.IP [8] +Cosmic ray and bad pixel removal programs should be used with caution. If the +data and parameter values are set such that the cosmic ray and bad pixel +detection and +removal algorithms have difficulty distinguishing between stars and bad +pixels or cosmic rays, +the peaks of the stars may be clipped, altering the point-spread function +and introducing errors into the photometry. +.IP [9] +DAOPHOT assumes that the local sky background is approximately flat in the +vicinity of the object being measured. This assumption is equivalent to +requiring that the local sky region have a unique mode. Variations +in the sky background which occur on the same scale as the size of the +local sky region will introduce errors into the photometry. +.IP [10] +The point spread function must be constant or smoothly +varying with position over the entire image. This is the fundamental +assumption +underlying all of DAOPHOT. All stars in the image must be indistinguishable +except for position and magnitude. The variable point spread function +option is capable of handling second order variability as a function of +position in the image. +.IP [11] +The input images should not have undergone any operations which fundamentally +alter the image point spread function or the image statistics in a non-linear +way. For example, non-linear image restoration tasks must not be run on +the image to prior to running DAOPHOT. +.IP [12] +The gain, readout noise, exposure time, +airmass, filter, and observing time should be present and correct in the +image headers before DAOPHOT reductions are begun. +DAOPHOT tasks can extract this information from the image headers, use it +in the computations, and/or store +it in the output photometry files, greatly simplifying the analysis +and subsequent calibration procedures. +.fi + +.NH +Some IRAF Basics for New IRAF and DAOPHOT Users + +.NH 2 +Pre-loaded Packages + +.PP +Under IRAF versions 2.10 and later the DATAIO, PLOT, IMAGES, TV and NOAO +packages are pre-loaded so that all the tasks directly under them are +available when +IRAF is started. Each of these packages contains tasks which are useful +to DAOPHOT users for various reasons, and each is discussed briefly below. + +.NH 3 +The DATAIO Package + +.PP +DAOPHOT users should be aware of the DATAIO \fBrfits\fR and \fBwfits\fR tasks +which are used to transport data into and out of IRAF. Any input +and output images, including point-spread function look-up table images, +should normally be archived with \fBwfits\fR. +The cardimage reader and writer tasks for archiving text files, +\fBrcardimage\fR and \fBwcardimage\fR, are also located here. + +.NH 3 +The PLOT Package + +.PP +Various general purpose image and file plotting utilities can be found +in the PLOT packages. DAOPHOT users should be aware of the interactive image +row and column plotting task \fBimplot\fR, the image contour plotting task +\fBcontour\fR, the image surface plotting task \fBsurface\fR, image +histogram plotting task \fBphistogram\fR, the image radial profile +plotting task \fBpradprof\fR, and the general purpose graphing tool +\fBgraph\fR. The tasks \fBgkidir\fR and \fBgkiextract\fR are also useful +for extracting individual plots from the plot metacode files which may +be produced by some DAOPHOT tasks. + +.NH 3 +The IMAGES Package + +.PP +The IMAGES package contains a set of general purpose image operators. DAOPHOT +users +should be aware of the image header examining tasks \fBimheader\fR and +\fBhselect\fR, the header editing task \fBhedit\fR, the coordinate and +pixel value dumping task \fBlistpixels\fR, and the image statistics +task \fBimstatistics\fR. + +.NH 3 +The TV Package + +.PP +The TV package contains tasks which interact with the image display including +the all important \fBdisplay\fR task for displaying images, the +interactive image examining task \fBimexamine\fR, and the \fBtvmark\fR task +for marking objects on the image display. DAOPHOT users should become +familiar with all three of these tasks. + +.NH 2 +Other Useful Packages and Tasks + +.PP +The NPROTO package contains two useful tasks, \fBfindgain\fR, +for computing the gain and readout noise of a CCD +from a pair of biases and flats, and \fBfindthresh\fR for computing +the standard deviation of the background in a CCD frame given the +readout noise and gain. The ASTUTIL package contains the \fBsetairmass\fR +task for computing and/or correcting the airmass given the appropriate +input data. +Users might also wish to experiment with the tasks in the artificial +data package ARTDATA, and run the resulting images through DAOPHOT. + +.NH 2 +Image Types, Image Directories, and Image Headers + +.PP +The IRAF image environment is controlled by several +environment variables. The most important of these for DAOPHOT users +are: \fBimtype\fR the disk image format, \fBimdir\fR the default pixel +directory, and \fBmin_lenuserarea\fR the maximum length of the image header. +The values of these environment variables can be listed +as shown below. + +.YS +cl> show imtype +imh +cl> show imdir +/data/davis/pixels/ +cl> show min_lenuserarea +24000 +.YE + +.PP +\fB"imh"\fR is the default image format for most IRAF users, \fB"hhh"\fR the +default image format for ST users, and \fB"qp"\fR the photon counting format +used for photon counting data. DAOPHOT will work transparently on +"imh" and "hhh" images. "qp" event lists must be rasterized prior to using +DAOPHOT. When IRAF supports FITS images on disk, image format "fits", DAOPHOT +will be able to work directly on FITS images as well. IRAF uses the +image name extension, e.g. "imh" to automatically sense the image +disk format on input. The output disk format is set by: 1) the +extension of the output image name if present e.g. "imh", 2) the cl +environment variable \fBimtype\fR if the output image is opened as a new +image, e.g. the output of the \fBrfits\fR task, 3) the type of the input +image if the output image is opened as a new copy of an existing image, +e.g. the output of the \fBimcopy\fR task. +.PP +\fBimdir\fR specifies the default image pixel directory for "imh" format +files. The image header files are written to the current directory +and the pixel files are written to imdir. imdir can be set +to an existing directory on a scratch disk, the current +directory "HDR$", or the subdirectory pixels under the current +directory "HDR$pixels/". DAOPHOT users should keep both the intrinsic +speed of a disk and its network configuration in mind when setting +imdir. +.PP +\fBmin_lenuserarea\fR is the size of the image header area reserved +in memory when a new or existing image is opened. +The current default value of 24000 corresponds to space for approximately +300 keywords. +If an image on disk has a header larger than this the image header will +be truncated when it is read. +For most DAOPHOT users the default value is sufficient. However users whose +images have large headers or who are +creating a point-spread function using more than ~70 stars should set +min_lenuserarea to a larger value, e.g. 40000. +.PP +The following example shows how to change the default pixel directory to +HDR$pixels/ and set min_lenuserarea to 40000. To avoid redefining these +quantities for every session, users should enter the redefinitions into +their login.cl or loginuser.cl files. + + +.YS +cl> reset imdir = "HDR$pixels/" +cl> reset min_lenuserarea = 40000 +.YE + +.NH 2 +The Image Display and Image Cursor + +.PP +Several DAOPHOT tasks are interactive tasks or have an interactive as well +as a non-interactive mode. In interactive mode these tasks must be able to +read the image cursor on a displayed image and perform various +actions depending on the position of the image cursor and the keystroke +command typed. +.PP +DAOPHOT will work with the display servers Imtool, Saoimage, and Ximtool. +DAOPHOT users should be aware that both Imtool and Ximtool support multiple +frame buffers while SAOimage does not. Multiple frame buffers are an +important feature for users who wish to compare their original +images with the DAOPHOT output images from which all the fitted +stars have been subtracted. Users running DAOPHOT on a remote machine, e.g. +one with lots of memory and/or disk space, but displaying on their local +machine also need to set the \fBnode\fR environment variable to +the name of the local machine. + +.YS +cl> show node +ERROR: No such environment variable + show (node) +cl> set node = mymachine +.YE + +.PP +The maximum size of the display server frame buffer is defined by the +environment variable \fBstdimage\fR whose value can be printed as +shown below. + +.YS +cl> show stdimage +imt512 +.YE + +In the previous example the default frames buffers are 512 pixels square. +A user whose images are 2K square will want to reset the default frame +buffer size as shown below. + +.YS +cl> reset stdimage = imt2048 +cl> show stdimage +imt2048 +.YE + +.PP +In order for image cursor read-back to function correctly the environment +variable \fBstdimcur\fR must be set to "stdimage" as shown below. + +.YS +cl> show stdimcur +stdimage +.YE + +To check that image cursor read-back is functioning correctly the user +should display an image and try to bring up the image display cursor +as shown below. + +.YS +cl> display image 1 +cl> =imcur +.YE + +The image cursor should appear on the image display reading the correct +image pixel coordinates and ready to accept a +keystroke command. Any keystroke will terminate the cursor read. + +.NH 2 +The Graphics Device and Graphics Cursor + +.PP +Some interactive DAOPHOT tasks have graphics submenus which require +them to be able to read the graphics cursor on for example a radial +profile plot and perform various +actions based on the position of the graphics cursor in the +plot and the keystroke +command issued. The default graphics device is determined by +the \fBstdgraph\fR environment variable as shown below. + +.YS +cl> show stdgraph +xgterm +.YE + +To check that graphics cursor read-back is functioning correctly the user +should draw a plot and try to bring up the graphics cursor as +shown below. + +.YS +cl> contour image +cl> =gcur +.YE + +The graphics cursor should appear in the graphics window ready to accept a +keystroke command. Any keystroke will terminate the cursor read. + +.NH +Some DAOPHOT Basics for New DAOPHOT Users + +.NH 2 +Loading the DAOPHOT Package + +.PP +The DAOPHOT package is located in the digital stellar photometry package +DIGIPHOT. To load DIGIPHOT and DAOPHOT the user types the package names +in sequence as shown below, + +.YS +cl> digiphot +di> daophot +.YE + +after which the following menu of tasks appears. + +.YS +addstar daotest nstar pexamine psf +allstar datapars@ pcalc pfmerge psort +centerpars@ findpars@ pconcat phot pstselect +daoedit fitskypars@ pconvert photpars@ seepsf +daofind group pdump prenumber setimpars +daopars@ grpselect peak pselect substar +.YE + +Task names with a trailing "@" are parameter set tasks. +The remaining tasks are script and/or compiled tasks. +After the DAOPHOT package is loaded the user can redisplay +the package menu at any time with the command. + +.YS +da> ? daophot +.YE + +.NH 2 +Loading the TABLES Package + +.PP +The DAOPHOT photometry tasks write their output photometry files in +either text format (the default) or ST binary tables format. Users wishing +to use the ST binary tables format should acquire and install +the ST TABLES external package. Without the TABLES package the DAOPHOT +photometry tasks will read and write ST binary tables, but DAOPHOT +utilities like \fBpsort\fR which call TABLES package +tasks will not run on ST binary tables. +.PP +When DAOPHOT is loaded, it checks to see if the TABLES package is defined, +and if so loads it. A warning message is issued if the TABLES package is +undefined. The TABLES package tasks can be listed at any time after DAOPHOT +is loaded with the following command. + +.YS +da> ? tables +.YE + +.NH 2 +Running the Test Script + +.PP +The DAOPHOT package includes a script task \fBdaotest\fR which +executes each of the core DAOPHOT photometry tasks in turn using a test +image stored +in FITS format in the DAOPHOT test directory. \fBDaotest\fR is run as +shown below. + +.YS +da> daotest + +DAOTEST INITIALIZES THE DAOPHOT TASK PARAMETERS +TYPE 'q' or 'Q' TO QUIT, ANY OTHER KEY TO PROCEED + +Name of the output test image: test + +INITIALIZE THE DAOPHOT PACKAGE + +TESTING THE DAOFIND TASK +TESTING THE PHOT TASK +TESTING THE PSTSELECT TASK +TESTING THE PSF TASK +TESTING THE PEAK TASK +TESTING THE GROUP TASK +TESTING THE GRPSELECT TASK +TESTING THE NSTAR TASK +TESTING THE ALLSTAR TASK (CACHE=YES) +TESTING THE ALLSTAR TASK (CACHE=NO) +TESTING THE SUBSTAR TASK +TESTING THE ADDSTAR TASK + +DAOPHOT PACKAGE TESTS COMPLETED +.YE + +On task completion the user will find the input image in +test.imh, the psf image in test.psf.1.imh, the subtracted image produced +by \fBallstar\fR in test.sub.1.imh, the input image with artificial stars +added in test.add.1.imh, copies of all the output photometry files in +test.log, and copies of the plots produced by the \fBpsf\fR task +in test.plot on disk. +.PP +Users should be aware that the \fBdaotest\fR task will reset the DAOPHOT +task and algorithm parameters to their default values before and after it +is executed. + +.NH 2 +On-line Help + +.PP +A one-line description of each DAOPHOT task can be obtained by typing +the following command, + +.YS +da> help daophot\fR +.YE + +upon which the following package menu appears. + +.YS +digiphot.daophot: + addstar - Add stars to an image using the computed psf + allstar - Group and fit psf to multiple stars simultaneously +centerpars - Edit the centering algorithm parameters + daoedit - Review/edit algorithm parameters interactively + daofind - Find stars in an image using the DAO algorithm + daopars - Edit the daophot algorithms parameter set + daotest - Run basic tests on the daophot package tasks + datapars - Edit the image data dependent parameters + findpars - Edit the star detection parameters +fitskypars - Edit the sky fitting algorithm parameters + group - Group stars based on position and signal/noise + nstar - Fit the psf to predefined groups of stars + peak - Fit the psf to single stars + phot - Compute skies and initial magnitudes for a star list + photpars - Edit the aperture photometry parameters + psf - Compute the point spread function + seepsf - Compute an image from the point spread function + setimpars - Save/restore parameter sets for a particular image + substar - Subtract the fitted stars from the original image + + pcalc - Do arithmetic operations on list of daophot databases + pconcat - Concatenate a list of daophot databases + pconvert - Convert a text database to a tables database + pdump - Print selected fields from daophot databases + pfmerge - Merge a list of photometry databases + pstselect - Select candidate psf stars based on proximity + grpselect - Select groups from a daophot database + pexamine - Interactively examine and edit a daophot database + prenumber - Renumber stars in a daophot database + pselect - Select records from a daophot database + psort - Sort a daophot database\fR +.YE + +.PP +All the DAOPHOT tasks have on-line manual pages which can be +listed on the terminal. The following command lists the help for the +\fBphot\fR task on the terminal. + +.YS +da> phelp phot\fR +.YE + +Any section of the manual pages can be listed individually. +For example the examples section of the \fBphot\fR manual page can be +listed as follows. + +.YS +da> phelp phot sections=examples\fR +.YE + +The help page for \fBphot\fR can be piped to the local default printer as +follows. + +.YS +da> phelp phot | lprint\fR +.YE + +Finally the manual pages for the whole DAOPHOT package can be printed +by typing. + +.YS +da> phelp daophot.* | lprint\fR +.YE + + +.NH 2 +Editing the Package Parameters + +.PP +DAOPHOT has a package parameter set which defines the DAOPHOT +package environment. The DAOPHOT package parameters can edited +with epar as shown below. + +.YS +da> epar daophot +.YE + +.YS +Image Reduction and Analysis Facility + PACKAGE = digiphot + TASK = daophot + (version = "Dec92") + (text = yes) Text file on output ? + (verify = yes) Verify critical parameters ? + (update = no) Update critical parameters ? + (verbose = yes) Print verbose output ? +(graphics = "stdgraph") Default graphics device + (display = "stdimage") Default display device + (mode = "ql") +.YE + +To edit a parameter simply move the cursor to the parameter in question, +enter the new value, type return, and finally type \fB:wq\fR to quit and +update the parameter set. Package parameters can also be edited on the +command line as shown below. + +.YS +da> daophot.text = yes +.YE + +.PP +The DAOPHOT package parameters control the operation of the DAOPHOT package +as a whole. For example the \fBtext\fR parameter specifies whether the +output photometry files will be written in text or STSDAS binary tables format, +the parameters \fBverify\fR, \fBupdate\fR, and \fBverbose\fR determine +the default mode of operation of the DAOPHOT package tasks, and the parameters +\fBgraphics\fR and \fBdisplay\fR determine the default graphics and display +devices for the entire package. + +.NH 2 +Editing the Task Parameters + +.PP +The DAOPHOT task level parameters specify the input and output images and +files, the algorithm parameter sets, the graphics and image display input and +output devices, and the mode of operation of each DAOPHOT task. +.PP +To enter and edit the parameter set for the DAOPHOT \fBphot\fR task +the user types the following command, + +.YS +cl> epar phot +.YE + +after which the parameter set for the \fBphot\fR task appears on the +terminal ready for editing as shown below. + +.YS +Image Reduction and Analysis Facility +PACKAGE = daophot + TASK = phot + +image = Input image(s) +coords = default Input coordinate list(s) +output = default Output photometry file(s) +skyfile = Input sky value file(s) +(plotfil= ) Output plot metacode file +(datapar= ) Data dependent parameters +(centerp= ) Centering parameters +(fitskyp= ) Sky fitting parameters +(photpar= ) Photometry parameters +(interac= no) Interactive mode ? +(radplot= no) Plot the radial profiles? +(verify = )_.verify) Verify critical phot parameters ? +(update = )_.update) Update critical phot parameters ? +(verbose= )_.verbose) Print phot messages ? +(graphic= )_.graphics) Graphics device +(display= )_.display) Display device +(icomman= ) Image cursor: [x y wcs] key [cmd] +(gcomman= ) Graphics cursor: [x y wcs] key [cmd] +(mode = ql) +.YE + +The \fBphot\fR parameters can be edited by moving +the cursor to the line opposite the parameter name, entering the new value +followed by a carriage return, and typing \fB:wq\fR to exit the +\fBepar\fR task and update the parameters. +.PP +In the following sections the \fBphot\fR task is used to illustrate +some general features of the DAOPHOT package. + +.NH 2 +Input and Output Image Names + +.PP +The \fBphot\fR parameter \fIimage\fR +defines the image to be analyzed. The +root image name, the value of \fIimage\fR +stripped of directory and section information, +sets up the default input and output image naming convention for the task. +Users should avoid appending the ".imh" or ".hhh" extension +to their image name specification as these extensions are not required by IRAF +image i/o and become part of the default output image names. +.PP +The \fBphot\fR task does not create an output image but DAOPHOT tasks +which do, will by default create an output image name of the form +"image.extension.?" where image is the input image name +stripped of directory +and section information, extension is an id appropriate +to the task, and ? is the next available version number. +For example the first run of the \fBsubstar\fR task on the image "image" +will create an image called "image.sub.1", the second an image +called "image.sub.2", and so on. The default output image naming convention +can always be overridden by the user in any task. + +.NH 2 +Input and Output File Names + +.PP +DAOPHOT uses a default input and output file naming convention based on the +root image name or the input image name with the directory and +section specification removed. Users should avoid appending the ".imh" or +".hhh" extension to their input image name specification as these extensions +are not required by IRAF image i/o and become part of the default input +and output file names. +.PP +If a DAOPHOT task expects its input to have been written +by another DAOPHOT task, and the input file parameter value is "default", +the task will search for an existing +file called "image.extension.?" where image is the root image +name, extension identifies the task expected to have written the file, +and version is the highest version number for that file. For example, +if the user sets the \fBphot\fR parameters \fIimage\fR and +\fIcoords\fR to "m92b" and "default", \fBphot\fR will search +for a coordinate file called "m92b.coo.#" written by the +\fBdaofind\fR task. The default input file naming convention +can be over-ridden by the user at any point. +.PP +The output file naming convention works +in an identical manner to the input file naming convention, +although in this situation ? is the next available +version number. For example if the user sets the \fBphot\fR task +parameter \fIoutput\fR to "default", the output photometry file name +will be "image.mag.?" +where ? is 1 for the first run of \fBphot\fR, 2 for the second run, and so +on. The default output file naming convention can be over-ridden +by the user at any point. + +.NH 2 +Algorithm Parameter Sets + +.PP +The DAOPHOT parameters have been grouped together into parameter sets +or psets. +The use of psets encourages the logical grouping of parameters, permits +the various DAOPHOT tasks to share common parameters, and +permits the user to optionally store the DAOPHOT algorithm parameters +with the data rather than in the default uparm directory. +.PP +Six DAOPHOT psets, \fBdatapars\fR, \fBfindpars\fR, \fBcenterpars\fR, +\fBfitskypars\fR, \fBphotpars\fR and \fBdaopars\fR +control the DAOPHOT algorithm parameters. The \fBphot\fR task +uses four of them, \fBdatapars\fR which specifies data dependent +parameters like \fIfwhmpsf\fR (the full-width half-maximum of the psf), +\fIsigma\fR (the standard deviation of +the sky background), \fIepadu\fR and \fIreadout noise\fR +(the gain and readout noise of the detector), +and the \fBcenterpars\fR, \fBfitskypars\fR and \fBphotpars\fR parameter +sets which define the centering algorithm, sky fitting algorithm +and aperture photometry algorithm parameters respectively, +used by phot to compute initial centers, sky values, +and initial magnitudes for the stars to be analyzed. The \fBfindpars\fR pset +controls the star detection algorithm parameters used by the \fBdaofind\fR +task. The \fBdaopars\fR pset defines the psf model fitting +and evaluation parameters including the radius of the psf, the fitting radius, +and the grouping parameters used by all the psf fitting tasks. +.PP +By default the pset parameters can be examined, edited and stored +in the user's uparm directory, in the same manner as the task level +parameters. For example to list the current \fBdatapars\fR +pset the user types. + +.YS +da> lpar datapars +.YE + +To edit the \fBdatapars\fR parameter set, the user types either + +.YS +da> epar datapars + +or + +da> datapars +.YE + +and edits the parameter set in the usual manner with \fBepar\fR. +All the DAOPHOT tasks which reference this +pset will pick up the changes from the uparm directory, assuming +that the \fIdatapars\fR parameter is specified as "" in the calling task. +The user can also edit the \fBdatapars\fR +pset from within the \fBphot\fR +task or any other task which calls it as shown below. + +.YS +da> epar phot +.YE + +Move the cursor to the \fBdatapars\fR parameter line and type \fB:e\fR. +The menu for the +\fBdatapars\fR pset will appear ready for editing. Edit the desired +parameters and type \fB:wq\fR. \fBEpar\fR will return to the main +\fBphot\fR parameter set after which other psets or the main task parameters +can be edited. +.PP +Psets may also be stored in user files providing +a mechanism for saving a particular pset +with the data. +The example below shows how to store a pset in a file in the same directory +as the data and recall it for use by the \fBphot\fR task. The user types + +.YS +da> epar phot +.YE + +as before, enters the \fBdatapars\fR menu with \fB:e\fR and edits the +parameters. The command \fB:w data1.par\fR +writes the parameter set to a file called "data1.par" and a \fB:q\fR +returns to the main task menu. +A file called "data1.par" containing the new \fBdatapars\fR parameters +is written in the current directory. At this point the user is still in the +\fBphot\fR parameter set at the line opposite \fBdatapars\fR. He/she +enters "data1.par" on the line opposite this parameter. +The next time \fBphot\fR is run the parameters will +be read from "data1.par" not from the pset in the uparm directory. +The new parameter set can be edited in the usual way by typing + +.YS +da> epar data1.par + +or + +da> epar phot +.YE + +Users should be sure to append a .par extension to any pset files they +create as IRAF needs this extension to identify the file as a pset. +.PP +It is possible to develop quite efficient and creative schemes for using psets. +For example a user might choose to copy each crowded stellar field +image to its own directory, copy the default psets \fBdatapars\fR, +\fBfindpars\fR, \fBcenterpars\fR, \fBfitskypars\fR, \fBphotpars\fR +and \fBdaopars\fR to the files "datapars.par", "findpars.par", +"centerpars.par", "fitskypars.par", "photpars.par" and "daopars.par" in +each image directory, and then edit +the parameter sets of the top level tasks to look for psets with those names. +Once this is done the psets in each directory can be edited at will +without ever needing to edit the names of the psets in the top +level tasks. +.PP +The individual pset parameters themselves have the same attributes as +task level parameters. Hidden pset parameters may be altered on the +command line in the same way as task parameters. +The only distinction between task level parameters and pset parameters +is that the latter may be stored in or read from a user defined file. + +.NH 2 +Interactive Mode and Non-Interactive Mode + +.PP +The \fBphot\fR task's \fIinteractive\fR parameter +switches the task between interactive and non-interactive mode. +.PP +In interactive mode user instructions in the form of single keystroke +commands or colon commands are read from the image cursor. +For example the \fBphot\fR task \fB'i'\fR keystroke command enters the +interactive setup menu and the \fB'v'\fR keystroke command verifies the +current parameters. The colon commands are used to show or set any parameter. +For example, if the user does not like the fact that the full-width +half-maximum of a star +as measured with the cursor is 2.5368945 he/she can set it to 2.54 by +typing \fB:fw 2.54\fR. +.PP +In non-interactive mode the input files and images are read, +the parameters are read from the psets, +and the output files are written, +all, with the exception of an optional verification step, without the +intervention of the user. +.PP +The DAOPHOT parameter editing task \fBdaoedit\fR and the photometry catalog +examining task \fBpexamine\fR are interactive tasks. +Four other DAOPHOT tasks, \fBdaofind\fR, \fBphot\fR, \fBpstselect\fR, +and \fBpsf\fR +have an interactive and a non-interactive mode. The default mode for +\fBdaofind\fR, \fBphot\fR, and \fBpstselect\fR is non-interactive while +for \fBpsf\fR +it is interactive. +The remaining DAOPHOT tasks are currently non-interactive tasks. + +.NH 2 +Image and Graphics Cursor Input + +.PP +All tasks which can be run interactively accept commands from the logical image +cursor parameter \fIicommands\fR. Logical image cursor commands can +read from the logical image cursor, \fIicommands\fR = "" or a file, +\fIicommands\fR = "filename". The logical image cursor is normally +the physical image cursor and the value of the IRAF environment +variable \fBstdimcur\fR is normally "stdimage". In cases where the image +display device is non-existent or cursor read-back is not implemented for +a particular device the logical image cursor may be reassigned globally to the +the graphics cursor or the standard input +by setting the IRAF environment variable \fBstdimcur\fR as follows. + +.YS +da> set stdimcur = "stdimage" (image cursor default) + +da> set stdimcur = stdgraph (graphics cursor) + +da> set stdimcur = "text" (standard input) +.YE + +If logical image cursor commands are read from the standard input or a +file, the commands must have the following format + +.YS +[x y wcs] key [cmd]\fR +.YE + +where x and y stand for the x and y position of the image cursor, wcs defines +the world coordinate system, key is +a keystroke command, and cmd is an optional user command. +Quantities in square brackets are optional. The necessity for their +presence is dictated by the nature of the keystroke command. In the +case of the \fBphot "i"\fR keystroke described above they are required, whereas +in the case of the \fBphot "v"\fR keystroke they are not. +.PP +Some interactive commands require input from the logical graphics cursor +parameter \fIgcommands\fR which may be the logical graphics cursor, +\fIgcommands\fR = "", or a file of graphics cursor commands, +\fIgcommands\fR = "filename". +In DAOPHOT the logical graphics cursor must be set to the physical +graphics cursor and the value of the IRAF environment variable +\fBstdgcur\fR should be "stdgraph". + +.NH 2 +Graphics Output + +.PP +The \fBphot\fR parameters \fIgraphics\fR and \fIdisplay\fR specify the +default vector graphics and image display graphics devices. +Vector graphics output is written to the user's +graphics window, and image +graphics is overlaid on the user's image display. window +All interactive vector graphics output is written to +the device specified by \fIgraphics\fR. An example of this type of graphics +output is the +radial profile plot of a star plotted by the \fBphot\fR interactive +setup menu. +Image graphics is written to the image display device +specified by \fIdisplay\fR. +Examples of this type of output are the optional crosses +which mark the centers of the stars being measured by \fBphot\fR. +\fBIRAF does not currently support writing interactive graphics +to the image display device +so the display marking features of DAOPHOT are not supported\fR. +The single exception occurs in the situation +where the user is running interactively +off a contour plot as described in the \fBphot\fR help documentation. +In this case marking will work if +the parameter \fIdisplay\fR is set to "stdgraph". +DAOPHOT tasks which reference \fIgraphics\fR or \fIdisplay\fR will, in +interactive mode, issue +a warning if they cannot open either or both of these devices, +and continue execution. +.PP +Some DAOPHOT tasks permit the user to save plots of the results +for each measured star in a plot metacode file. +For example. if the \fBphot\fR task parameter \fIplotfile\fR is defined, +then for each star written to \fIoutput\fR +a radial profile plot is written to the plot metacode file \fIplotfile\fR. +\fIPlotfile\fR is opened in append mode and succeeding executions +of \fBphot\fR will write to the end of the same file. +Users should be aware plotfile can become very large and +that writing radial profile plots +to \fIplotfile\fR will greatly slow the execution of \fBphot\fR or any +other task. + +.NH 2 +Verify, Update, and Verbose + +.PP +In non-interactive mode the algorithm parameter values are read from the psets, +critical parameters are verified if the \fIverify\fR switch is on, and +updated if both the \fIverify\fR and \fIupdate\fR switches are on. +The \fIverify\fR and \fIupdate\fR options are also available as +separate keystroke commands in interactive mode. +Users must remember to turn off the +\fIverify\fR switch if they submit a task to the background or the task +will pause and wait indefinitely for input from the terminal. +.PP +In interactive or non-interactive mode a results summary and/or +error messages are written +to the standard output if the \fIverbose\fR switch is on. +Users must remember to redirect +any verbose output to a file if they submit the task to the background or +it will be lost. + +.NH 2 +Background Jobs + +.PP +Any DAOPHOT task can be run in background by appending an ampersand +to the end of the command. For example the \fBphot\fR task can be run +as a background job as shown below. + +.YS +da> phot image image.coo.1 image.mag.1 verbose- verify- & +.YE + +The user must be sure to turn off verbose mode +and set the verify switch to no. VMS users may have to append a queue +name after the trailing ampersand. +If verbose output is desired it can be captured in a file as shown +in the example below below. The & after the > will ensure that any error +output is also captured. + +.YS +da> phot image image.coo.1 image.mag.1 verbose+ inter- verify- \\ + >& listing & +.YE + +.NH 2 +Timing Tests + +.PP +Any DAOPHOT or IRAF task can be timed by prepending a $ sign to the +command as shown below. + +.YS +da> $phot image image.coo.1 image.mag.1 inter- verify- verbose- & +.YE + +At task termination the computer will print the cpu and elapsed +time on the terminal. +.PP +Care must be taken in using this feature +to make timing comparisons between hosts or even between runs on the same host, +as factors like which queue a task is submitted to (VMS), which version of +the OS the host is running, which version of the compiler +two programs were compiled under, +whether the disks are local or networked, and the number of users on the +machine will effect the elapsed time and/or the cpu time. + +.NH +Doing Photometry with DAOPHOT + +.NH 2 +The Test Image + +.PP +Each of the DAOPHOT analysis steps summarized in the following section +and discussed in detail in succeeding +sections uses the artificial image stored in fits format in +the file "daophot$test/fits3.fits" as test data. This image is small, +51 by 51 pixels, contains 10 stars whose coordinates and magnitudes +are listed below, has, a mean background level of ~100, poisson noise +statistics, a gain of 1.0, and a readout noise of 0.0. + +.YS +# Artificial Stars for Image Test + + 41.0 4.0 17.268 + 23.0 7.0 17.600 + 18.0 8.0 17.596 + 26.0 22.0 16.777 + 36.0 22.0 16.317 + 8.0 23.0 16.631 + 31.0 25.0 16.990 + 21.0 26.0 19.462 + 29.0 34.0 17.606 + 36.0 42.0 16.544 +.YE + +.PP +Results for this test image are used to illustrate the text. It is hoped +that users so inclined will be able to mimic the reductions on +their host machine. The fact that the image is small, means that +the tasks execute quickly, it is possible to display all the +important results in the manual, and it is possible for +the user to track and examine all the important numbers, something not +easy with larger images. Users are encouraged to construct more +challenging artificial images with the ARTDATA package, and to run +them through DAOPHOT. +.PP +All the examples in the following text were run +under IRAF 2.10.3 on a SPARCstation IPX. Users with different hardware +may see minor deviations from the output shown here due to machine +precision differences. + +.NH 2 +Typical Analysis Sequence + +.PP +The following sequence of operations summarizes the steps required to analyze +a crowded stellar field with DAOPHOT. +.IP [1] +Create a directory in which to analyze the image and make it the current +working directory. By default all output photometry and image files +will be written there. +.IP [2] +Read the reduced image into the working directory with the DATAIO package +task \fBrfits\fR. +.IP [3] +Check that the correct exposure time, airmass, filter id, time of +observation, gain, and readout noise are present and correct +in the image header with the \fBhselect\fR task. Enter / edit them +with the \fBhedit\fR task if they are not. Correct the exposure time for +shutter error, the airmass to mid-exposure, and the gain +and readout noise to the effective gain and readout noise, using the +\fBhedit\fR and/or \fBsetairmass\fR tasks. +.IP [4] +Edit the DAOPHOT algorithm psets with the interactive \fBdaoedit\fR +task. The parameters that require editing at this point are: +1) the numerical parameters +\fIfwhmpsf\fR (full-width at half-maximum of the point-spread function), +\fIsigma\fR (standard deviation of the background in counts), \fIdatamin\fR +(the minimum good data value in counts), \fIdatamax\fR (the maximum good +data value in counts), and the image header keyword parameters +\fIccdread\fR, \fIgain\fR, \fIexposure\fR, \fIairmass\fR, \fIfilter\fR, +and \fIobstimes\fR in the \fBdatapars\fR parameter set, +2) \fIcbox\fR (the centering box width) in the \fBcenterpars\fR parameter set, +3) \fIannulus\fR (inner radius of the sky annulus) and +\fIdannulus\fR (width of the sky annulus) in the \fBfitskypars\fR parameter set, +4) \fIapertures\fR (radii of the photometry apertures) in the \fBphotpars\fR +parameter set, and 5) \fIpsfrad\fR (maximum radius of the psf model) +and \fIfitrad\fR (psf model fitting radius) in the \fBdaopars\fR parameter set. +.IP [5] +Create an initial star list using the \fBdaofind\fR task. +Mark the detected stars on the image display with the \fBtvmark\fR task +and adjust the \fBfindpars\fR parameter \fIthreshold\fR until +a satisfactory star list is created. +.IP [6] +Compute sky background values and initial magnitudes for +the detected stars using the \fBphot\fR task and the star +list written by the \fBdaofind\fR task in step [5]. +.IP [7] +Create a psf star list using the \fBpstselect\fR task +and the photometry file written by \fBphot\fR in step [6]. Mark +the coordinates of the psf stars on the image display with the +\fBtvmark\fR task +and edit out any non-stellar objects, stars with +neighbors within \fIfitrad\fR pixels, or stars with obvious +cosmetic blemishes, using the \fBpexamine\fR task. +.IP [8] +Compute the current psf model using the +\fBpsf\fR task, the input photometry file written by the \fBphot\fR task +in step [6], and the psf star list written by the \fBpstselect\fR task +in step [7]. +.IP [9] +Fit the current psf model to the psf stars and their neighbors +using the \fBnstar\fR task, the psf star group photometry file +written by the \fBpsf\fR task in step [8] or created by the user in step [11], +and the current psf model written by the \fBpsf\fR task in steps [8] or [13]. +Subtract the fitted psf stars +and their neighbors from the original image using the \fBsubstar\fR task, +the photometry file written by the \fBnstar\fR task, and the current +psf model. +Display the subtracted image, mark the psf stars and their neighbors +on the display with the \fBtvmark\fR task, +and examine the \fBnstar\fR photometry +file and the subtracted image with the \fBpexamine\fR task. +If all the psf stars subtract out cleanly and none of them have any +significant neighbors, skip directly to step [14]. If all the psf stars +and their neighbors subtract out cleanly, and one or more of the psf +stars do have significant neighbors, skip directly to step [13]. +.IP [10] +Reexamine the subtracted image written in step [9]. Remove any psf stars +revealed by the subtraction to be non-stellar, multiple, or to contain +cosmetic blemishes, +from the psf star list written by the \fBpsf\fR task in step +[8] using the \fBpexamine\fR task. +If any bad psf stars are detected recompute the psf model by returning to +step [8] using the newly edited psf star list in place +of the one written by the previous execution of the \fBpsf\fR task in step [8]. +.IP [11] +Add any psf star neighbors too faint to be detected by the \fBdaofind\fR +task in step [5] but bright enough to effect the computation of the +psf model, to the original psf star group photometry file written +by the \fBpsf\fR task in step [8], +by estimating their positions, sky values, and magnitudes interactively +with the \fBphot\fR task, merging the results with the original psf star group +photometry file +using the \fBpfmerge\fR task, and regrouping the stars with the \fBgroup\fR +task. Refit the newly grouped psf stars and their neighbors using +the current psf model by returning to step [9], +replacing the original input group photometry file with the one +including the new psf star neighbors. +.IP [12] +Using the subtracted image written by the \fBsubstar\fR task in step [9], +note any systematic patterns in the psf star residuals with distance from +the star (\fIthese indicate a poorly chosen value for the annulus, +dannulus, function, or psfrad parameters), +position in the image (\fIthese suggest that the psf is variable +and that the value of the varorder parameter should be increased\fR), +or intensity (\fIthis suggests problems with the image data itself, e.g. +non-linearity\fR). If the problem is in the sky fitting parameters +edit the appropriate algorithm parameters and return to step [6]. If +the problem is in the psf modeling and fitting parameters, edit the +appropriate algorithm parameters and return to step [7]. I the problem +appears to be in the data or the data reduction procedures, review the +data taking and reduction history of the image before proceeding. +.IP [13] +Subtract the psf star neighbors but not the psf stars from the original +image using the \fBsubstar\fR task, +the photometry file written by the \fBnstar\fR task +in step [9], and the psf star list and current psf model written by +the \fBpsf\fR task in step [8]. +Recompute the current psf model using +the psf neighbor star subtracted image, the psf star group photometry file +written by the \fBpsf\fR task in step [8] or created by the user in step [11], +and the psf star list written in step [8]. +If the \fIvarorder\fR parameter was changed +return to step [9]. +Otherwise save the psf star neighbor subtracted image as it may be +required for computing the image +aperture correction in step [20], and proceed to step [14]. +.IP [14] +Fit the final psf model computed in steps [8] or [13] +to the stars in the photometry file written in +step [6] using the \fBallstar\fR task. +.IP [15] +Run \fBdaofind\fR on the subtracted image produced by \fBallstar\fR in step +[14] in order to pick up stars missed by the first pass of \fBdaofind\fR in +step [5]. +.IP [16] +Run \fBphot\fR on the original image using the new star list produced by +\fBdaofind\fR in step [15] and the \fBphot\fR algorithm parameters used +in step [6]. +.IP [17] +Merge the photometry file produced by \fBallstar\fR in step [14] with +the one produced by \fBphot\fR in step [16] using the \fBpfmerge\fR +task. +.IP [18] +Rerun \fBallstar\fR on the original image using the merged photometry file +created in step [17] and the psf model created in steps [8] or [13]. +.IP [19] +Repeat steps [15]-[18] as required, remembering to run \fBdaofind\fR +on the subtracted image produced by \fBallstar\fR and \fBphot\fR on the +original image. +.IP [20] +If the psf model is constant, compute the aperture correction for the +image using the original image and a sample of bright well-isolated stars +if possible, or the image with +the psf neighbor stars subtracted if necessary, the +\fBphot\fR task, and the PHOTCAL package \fBmkapfile\fR task. +If the psf model is variable, compute the aperture correction by calculating +the mean magnitude difference, for the psf stars with any +the neighbors subtracted, between the psf model fitted magnitudes computed +by the \fBnstar\fR task, and large aperture photometry magnitudes computed +with the \fBphot\fR task. +.IP [21] +Archive the algorithm parameters for the image with the \fBsetimpars\fR task +and proceed to the next image. + + +.NH 2 +Creating and Organizing an Analysis Directory + +.PP +By default DAOPHOT reads and writes data from and to the current working +directory. To create and set a new working directory the user must +execute the commands \fBmkdir\fR and \fBchdir\fR as shown below. + +.YS +da> mkdir testim +da> chdir testim +.YE + +.PP +DAOPHOT can in the course of reducing a single image, +generate a large number of photometry catalogs and output images. +Users should take a moment to consider how they wish to organize their data +directories before beginning any DAOPHOT analysis. Some possibilities for data +directory organization are: 1) by night of observation for standard star fields, +2) by star field for multi-filter observations of a crowded field, or +3) by individual image for single filter observations of several fields, +or any combination of the above. + +.NH 2 +Reading the Data + +.PP +DAOPHOT input images are normally read into IRAF from FITS files with +the DATAIO package task \fBrfits\fR. The following example shows how to +read the DAOPHOT test image stored in the FITS file "daophot$test/fits3.fits" +into the IRAF image test.imh. + +.YS +da> rfits daophot$test/fits3.fits 1 test +File: test Artificial Starfield Size = 51 x 51 +.YE + +When IRAF supports FITS format images on disk this step will no longer be +necessary, although for some images it may still be desirable for +image i/o efficiency reasons. + +.NH 2 +Editing the Image Headers + +.NH 3 +The Minimum Image Header Requirements + +.PP +Before beginning DAOPHOT reductions the user must gather +all the data required to determine the following quantities: +1) the effective readout noise of the detector in electrons, 2) the effective +gain of the detector in electrons per count, 3) the maximum good data value +of the detector in counts, 4) the effective exposure time in any units +as long as these units are identical for all the images to be analyzed +together, +5) the filter id, 6) the effective airmass of the observation at mid-exposure, +and 7) the time of the observation. + +.NH 3 +The Effective Gain and Readout Noise + +.PP +The DAOPHOT package tasks require correct effective +gain and readout noise values for: +1) the computation of the magnitude errors in the \fBphot\fR (gain only +required), \fBpeak\fR, \fBnstar\fR and \fBallstar\fR tasks, +2) the computation of the optimal weights used by the non-linear +least-squares fitting code in the \fBpeak\fR, \fBnstar\fR, and +\fBallstar\fR tasks, +3) the computation of the predicted signal-to-noise +ratios in the \fBgroup\fR task, +4) the computation of the sharpness and chi statistics in the \fBpeak\fR, +\fBnstar\fR, and \fBallstar\fR tasks, and 5) the correct computation of +the poisson noise (gain only required) in the \fBaddstar\fR task. +.PP +Nominal gain and readout noise values for a single image +should be obtained from the instrument +scientist. These values should also be determined/checked empirically with the +PROTO package task \fBfindgain\fR using bias and flat-field frames that +are unprocessed and uncoadded so that the noise characteristics of the +original data are preserved. +.PP +If the input image is the sum or average of several frames +the gain and readout noise values in the image headers must be edited +from single frame to effective gain and readout noise values +as shown below. In the following examples +gain and effective gain are in electrons / ADU, +readout noise and effective readout noise are in electrons, and N is the +number of individual frames which +have been summed, averaged, or medianed to create the input image. + +.nf + [1]. The image is the sum of N frames + + effective gain = gain + effective readout noise = sqrt (N) * readout noise + + [2]. The image is the average of N frames + + effective gain = N * gain + effective readout noise = sqrt (N) * readout noise + + [3]. The image is the median of N frames + + effective gain = 2.0 * N * gain / 3 + effective readout noise = sqrt (2 * N / 3) * readout noise +.fi + +.PP +The following example shows how to add the correct values of gain and +readout noise, which in this very artificial example are 1.0 and 0.0 +respectively, to the header of the test image with the \fBhedit\fR task. + +.YS +da> imheader test l+ +test[51,51][real]: Artificial Starfield with Noise + No bad pixels, no histogram, min=71.00896, max=535.1335 + Line storage mode, physdim [51,51], length of user area 163 s.u. + Created Mon 09:59:00 17-May-93, Last modified Mon 09:59:00 17-May-93 + Pixel file 'tucana!/d0/iraf/davis/test.pix' [ok] + 'KPNO-IRAF' / + '10-05-93' / + IRAF-MAX= 5.351335E2 / DATA MAX + IRAF-MIN= 7.100896E1 / DATA MIN + IRAF-BPX= 32 / DATA BITS/PIXEL + IRAFTYPE= 'REAL ' / PIXEL TYPE +da> hedit test gain 1.0 add+ verify- +add test,gain = 1. +test updated +da> hedit test rdnoise 0.0 add+ verify- +add test,rdnoise = 0. +test updated +da> imheader test l+ +test[51,51][real]: Artificial Starfield with Noise + No bad pixels, no histogram, min=71.00896, max=535.1335 + Line storage mode, physdim [51,51], length of user area 244 s.u. + Created Mon 09:59:00 17-May-93, Last modified Mon 09:59:00 17-May-93 + Pixel file 'tucana!/d0/iraf/davis/test.pix' [ok] + 'KPNO-IRAF' / + '10-05-93' / + IRAF-MAX= 5.351335E2 / DATA MAX + IRAF-MIN= 7.100896E1 / DATA MIN + IRAF-BPX= 32 / DATA BITS/PIXEL + IRAFTYPE= 'REAL ' / PIXEL TYPE + GAIN = 1. + RDNOISE = 0.\fR +.YE + +.PP +The following example shows how to correct the single frame +values of gain and readout noise, already present in the input image +header, to account for the fact that the input image is actually the +average of three frames (note that the frames are NOT actually independent +in this example!). + +.YS +da> imsum test,test,test testav3 option=average +da> hedit testav3 gain "(3.0*gain)" verify- +testav3,GAIN: 1. -> 3. +testav3 updated +da> hedit testav3 rdnoise "(rdnoise*sqrt(3.0))" verify- +testav3,RDNOISE: 0. -> 0. +testav3 updated +da> imheader testav3 l+ +testav3.imh[51,51][real]: Artificial Starfield with Noise + No bad pixels, no histogram, min=unknown, max=unknown + Line storage mode, physdim [51,51], length of user area 244 s.u. + Created Mon 11:02:22 17-May-93, Last modified Mon 11:02:22 17-May-93 + Pixel file 'tucana!/d0/iraf/davis/testav3.pix' [ok] + 'KPNO-IRAF' / + '10-05-93' / + New copy of test + IRAF-MAX= 5.351335E2 / DATA MAX + IRAF-MIN= 7.100896E1 / DATA MIN + IRAF-BPX= 32 / DATA BITS/PIXEL + IRAFTYPE= 'REAL ' / PIXEL TYPE + GAIN = 3. + RDNOISE = 0. +.YE + +.NH 3 +The Maximum Good Data Value + +.PP +Datamax is the maximum good data value in counts. Datamax +is the count level at which the detector saturates or the count +level at which it becomes non-linear, whichever is lower. DAOPHOT requires +a correct value of datamax to: 1) identify bad data in the \fBdaofind\fR, +\fBphot\fR, \fBpsf\fR, \fBpeak\fR, \fBgroup\fR, \fBnstar\fR, +and \fBallstar\fR tasks, and 2) identify saturated stars in the \fBphot\fR, +\fBpsf\fR, and \fBsubstar\fR tasks. +.PP +Users should be sure to allow adequate leeway for the detector bias level +in their determination of datamax. Test is an artificial image +linear over its entire data range. However as an example assume that it was +actually observed with a detector which is linear from 0 to 25000 counts +at a gain setting of 1.0, and that the mean bias level that was subtracted +from the raw data was ~400 counts. +In that case the user should set datamax to something like 24500 not 25000 +counts. +.PP +Datamax may be stored in the image header with \fBhedit\fR +as shown below. The use of the header keyword gdatamax instead of +datamax avoids any confusion with the reserved FITS keywords +datamin and datamax should they already be present in the image header, +or the IRAF keywords iraf-max and iraf-min which have the same meaning. + +.YS +da> hedit test gdatamax 24500 add+ verify- +add test,gdatamax = 24500 +test updated +.YE + +.NH 3 +The Effective Exposure Time + +.PP +The exposure time is used by the \fBphot\fR task to normalize the computed +initial magnitudes to an effective exposure time of one time unit. The +magnitude scale established in \fBphot\fR is preserved +in all the subsequent DAOPHOT analysis. Setting the correct exposure +time in the image headers before beginning DAOPHOT reductions will +simplify the book-keeping required in the later calibration step +significantly. +.PP +Exposure times should also be corrected +for any timing errors in the instrument shutter, although this is normally +important only for short exposure observations of standard stars. +.PP +The following example shows how to add the exposure time in seconds +to the image header, and how to correct it for a known shutter error +of 13 milli-seconds. Note that rather than overwrite the nominal exposure time +exptime, the user has chosen to store the corrected exposure time in +a new keyword cexptime. + +.YS +da> hedit test exptime 1.0 add+ verify- +add test,exptime = 1. +test updated +da> hedit test cexptime "(exptime+.013)" add+ verify- +add test,cexptime = 1.013 +test updated +da> imheader test l+ +test[51,51][real]: Artificial Starfield with Noise + No bad pixels, no histogram, min=71.00896, max=535.1335 + Line storage mode, physdim [51,51], length of user area 365 s.u. + Created Mon 09:59:00 17-May-93, Last modified Mon 09:59:00 17-May-93 + Pixel file 'tucana!/d0/iraf/davis/test.pix' [ok] + 'KPNO-IRAF' / + '10-05-93' / + IRAF-MAX= 5.351335E2 / DATA MAX + IRAF-MIN= 7.100896E1 / DATA MIN + IRAF-BPX= 32 / DATA BITS/PIXEL + IRAFTYPE= 'REAL ' / PIXEL TYPE + GAIN = 1. + RDNOISE = 0. + GDATAMAX= 24500 + EXPTIME = 1. + CEXPTIME= 1.013 +.YE + +.NH 3 +The Airmass, Filter Id, and Time of Observation + +.PP +The airmass, filter id, and time of observation are not used directly by +any of the DAOPHOT tasks. They are read from the image header and recorded +in the output photometry files. Correctly setting the airmass, +filter id, and the time of observation in the image headers before running +any DAOPHOT tasks will however significantly reduce the book-keeping +required in the subsequent calibration step. +.PP +The airmass can be computed and/or corrected to mid-exposure with the +ASTUTIL package task \fBsetairmass\fR. By default \fBsetairmass\fR requires +that the name of the observatory, date of observation, ra and dec, epoch of +the ra and dec, sidereal time, and exposure time be recorded +in the image header in the appropriate units in the keywords +observat, date-obs, ra, dec, epoch, st, and exptime. Hopefully most or +all of this information is already in the image header but in case +it is not, the following example shows how to edit it in and run +\fBsetairmass\fR. + +.YS +da> hedit test observat "CTIO" add+ verify- show- +da> hedit test "date-obs" "12/10/88" add+ verify- show- +da> hedit test ra "(str('21:51:59.0'))" add+ verify- show- +da> hedit test dec "(str('02:33:31.0'))" add+ verify- show- +da> hedit test epoch 1985.0 add+ verify- show- +da> hedit test st "(str('20:47:55.0'))" add+ verify- show- +da> setairmass test show- +da> imheader test l+ +test[51,51][real]: Artificial Starfield with Noise + No bad pixels, no histogram, min=71.00896, max=535.1335 + Line storage mode, physdim [51,51], length of user area 649 s.u. + Created Mon 09:59:00 17-May-93, Last modified Mon 09:59:00 17-May-93 + Pixel file 'tucana!/d0/iraf/davis/test.pix' [ok] + 'KPNO-IRAF' / + '10-05-93' / + IRAF-MAX= 5.351335E2 / DATA MAX + IRAF-MIN= 7.100896E1 / DATA MIN + IRAF-BPX= 32 / DATA BITS/PIXEL + IRAFTYPE= 'REAL ' / PIXEL TYPE + GAIN = 1. + RDNOISE = 0. + GDATAMAX= 24500 + EXPTIME = 1. + CEXPTIME= 1.013 + OBSERVAT= 'CTIO ' + DATE-OBS= '12/10/88' + RA = '21:51:59.0' + DEC = '02:33:31.0' + EPOCH = 1985. + ST = '20:47:55.0' + AIRMASS = 1.238106 +.YE + +The tortuous syntax required to enter the ra, dec, and st keywords is +necessary in order to avoid \fBhedit\fR turning strings like +"21:51:59.0" into numbers, +e.g. 21.86639. \fBSetairmass\fR permits the user to change the +default names for the date-obs and exptime image header keywords but +not those of observat, ra, dec, epoch or st. +To list the observatories in the IRAF observatory database and/or to find out +how to deal with the case of data taken at an observatory not in the +observatory database, the user should consult the help page for the +\fBobservatory\fR task. +.PP +The filter id is a string defining the filter used to take the observations. +It can be easily edited into the image header as shown below. + +.YS +da> hedit test filters V add+ verify- show- +.YE + +Users should be aware that any embedded blanks will be removed from the +filter id after it is read from the image header, but before it is +recorded in the photometry files. For example a filter id of "V band" +in the image header will become "Vband" in the photometry file. +.PP +The time of observation is a string defining the time at which the +observation was taken. The time of observation may be ut or local +standard time. If the time of observation is not already recorded in +the image header it can be entered in the usual fashion as shown below. + +.YS +da> hedit test ut "(str('00:07:59.0'))" add+ verify- show- +.YE + +.PP +After editing the "final" image header should look something like the +following. + +.YS +da> imheader test l+ +test[51,51][real]: Artificial Starfield with Noise + No bad pixels, no histogram, min=71.00896, max=535.1335 + Line storage mode, physdim [51,51], length of user area 730 s.u. + Created Mon 09:59:00 17-May-93, Last modified Mon 09:59:00 17-May-93 + Pixel file 'tucana!/d0/iraf/davis/test.pix' [ok] + 'KPNO-IRAF' / + '10-05-93' / + IRAF-MAX= 5.351335E2 / DATA MAX + IRAF-MIN= 7.100896E1 / DATA MIN + IRAF-BPX= 32 / DATA BITS/PIXEL + IRAFTYPE= 'REAL ' / PIXEL TYPE + GAIN = 1. + RDNOISE = 0. + GDATAMAX= 24500 + EXPTIME = 1. + CEXPTIME= 1.013 + OBSERVAT= 'CTIO ' + DATE-OBS= '12/10/88' + RA = '21:51:59.0' + DEC = '02:33:31.0' + EPOCH = 1985. + ST = '20:47:55.0' + AIRMASS = 1.238106 + FILTER = 'V ' + UT = '00:07:59.0'\fR +.YE + + +.NH 3 +Batch Header Editing + +.PP +The previous examples described in detail how to enter each of the required +keyword and value pairs into the image header using the \fBhedit\fR task. +Users with large number of header keywords to enter should consider using the +more batch oriented alternative task \fBasthedit\fR. + + +.NH 2 +Editing, Checking, and Storing the Algorithm Parameters + +.NH 3 +The Critical Algorithm Parameters + +.PP +The critical DAOPHOT algorithm parameters that should be set +before beginning any DAOPHOT analysis are: +1) the +full-width at half-maximum of the psf \fIfwhmpsf\fR, the standard +deviation of the sky background in counts \fIsigma\fR, the minimum and +maximum good data values \fIdatamin\fR and \fIdatamax\fR, and the image +header keyword parameters +\fIccdread\fR, \fIgain\fR, \fIexposure\fR, \fIairmass\fR, \fIfilter\fR, +and \fIobstimes\fR in the \fBdatapars\fR parameter set, +2) the default centering algorithm \fIcalgorithm\fR and centering box +\fIcbox\fR parameters in the \fBcenterpars\fR parameter set, 3) the sky fitting +algorithm \fIsalgorithm\fR, and the sky annulus \fIannulus\fR and +\fIdannulus\fR parameters in the \fBfitskypars\fR parameter set, +4) the \fIapertures\fR parameter in the \fBphotpars\fR parameter set, +and 5) the psf radius \fIpsfrad\fR +and fitting radius \fIfitrad\fR parameters in the \fBdaopars\fR parameter set. +The reamining parameters should be left at their default values, at least +initially. + +.NH 3 +Editing the Algorithm Parameters Interactively with Daoedit + +.PP +The DAOPHOT algorithm parameter editing task is \fBdaoedit\fR. \fBDaoedit\fR +permits +the user to edit all the algorithm parameter sets at once. It offers all the +capabilities of the IRAF parameter editing task \fBepar\fR, plus the +ability to set parameters using the displayed image and radial +profile plots of isolated stars. +.PP +To run \fBdaoedit\fR the user displays the image, types \fBdaoedit\fR, and waits +for the image cursor to appear ready to accept user commands. The following +example summarizes a typical \fBdaoedit\fR parameter editing session. + +.YS +da> display test 1 fi+ +da> daoedit test +.YE + +.IP ... +Execute the command \fB":epar datapars"\fR and enter the correct +values for the \fIdatamax\fR parameter, and the image header +keyword parameters \fIccdread\fR, \fIgain\fR, \fIexposure\fR, \fIairmass\fR, +\fIfilter\fR, and \fIobstime\fR. +.IP ... +Choose a bright isolated star and execute the \fBr\fR cursor +keystroke command to plot its radial profile. +.IP ... +From the information in the radial plot header and the plot +itself estimate reasonable values for the full-width at +half-maximum of the psf, the sky level, and the standard +deviation of the sky level in the image. +.IP ... +Repeat the previous step for several stars in order to +confirm that the original estimated values are reasonable. +.IP ... +Execute the \fB":epar datapars"\fR command once more and enter +the estimated values of the full-width at half-maximum of the psf and +the standard deviation of the sky background in the \fIfwhmpsf\fR +and \fIsigma\fR parameters respectively. +.IP ... +Set the \fIdatamin\fR parameter to the estimated sky background level +minus k times the standard deviation of the sky background, where +k is a number between 5.0 and 7.0. + +.IP +then + +.IP ... +Execute the command \fB":epar centerpars"\fR and set the \fIcbox\fR +parameter to 5 pixels or ~ 2 * \fIfwhmpsf\fR whichever is +greater. +.IP ... +Execute the command \fB":epar fitskypars"\fR and set the \fIannulus\fR +parameter to ~ 4 * \fIfwhmpsf\fR and the \fIdannulus\fR parameter to a +number between 2.5 * \fIfwhmpsf\fR and 4.0 * \fIfwhmpsf\fR. +.IP ... +Execute the command \fB":epar photpars"\fR and set the apertures +parameter to ~ 1.0 * fwhmpsf or 3 pixels whichever is greater. +.IP ... +Execute the command \fB":epar daopars"\fR and set the \fIpsfrad\fR +parameter to ~ 4 * \fIfwhmpsf\fR + 1 and the \fIfitrad\fR parameter to +~ 1.0 * \fIfwhmpsf\fR or 3 pixels whichever is greater. + +.IP +or alternatively + +.IP ... +Move to a bright star and execute the \fBi\fR cursor keystroke +command to enter the interactive setup menu. +.IP ... +Mark the \fIfwhmpsf\fR, \fIcbox\fR, \fIannulus\fR, \fIdannulus\fR, +\fIapertures\fR, \fIpsfrad\fR, and \fIfitrad\fR parameters with the +graphics cursor on the displayed radial profile plot, and verify and/or +roundoff the marked values. +.PP +The following sections discuss in detail how to edit each of the +parameter sets using the test image as a specific example. + +.NH 4 +The Data Dependent Algorithm Parameters + +.PP +A subset of the datapars parameters are used to specify the +characteristics of the detector, including the saturation or linearity +limit (\fIdatamax\fR) and noise model (\fIccdread\fR +and \fIgain\fR), and the parameters of the observation, including +exposure time (\fIexposure\fR), +airmass (\fIairmass\fR), filter (\fIfilter\fR), and time of observation +(\fIobstime\fR). +.PP +To edit the \fBdatapars\fR algorithm parameter set +from within the \fBdaoedit\fR task the user enters the command +\fB":epar datapars"\fR to invoke the \fBepar\fR task and edits the +parameters in the usual manner. +Editing is terminated with the usual \fB":wq"\fR command which returns the +user to the main \fBdaoedit\fR command loop. +.PP +After the appropriate \fIdatamax\fR, \fIccdread\fR, \fIgain\fR, +\fIexposure\fR, \fIairmass\fR, +\fIfilter\fR, and \fIobstime\fR parameter values for the +test image are entered, the \fBdatapars\fR +parameter should look as follows. + +.YS +Image Reduction and Analysis Facility +PACKAGE = daophot + TASK = datapars + +(scale = 1.) Image scale in units per pixel +(fwhmpsf= 2.5) FWHM of the PSF in scale units +(emissio= yes) Features are positive ? +(sigma = 0.) Standard deviation of background in counts +(datamin= INDEF) Minimum good data value +(datamax= 24500) Maximum good data value +(noise = poisson) Noise model +(ccdread= rdnoise) CCD readout noise image header keyword +(gain = gain) CCD gain image header keyword +(readnoi= 0.) CCD readout noise in electrons +(epadu = 1.) Gain in electrons per count +(exposur= cexptime) Exposure time image header keyword +(airmass= airmass) Airmass image header keyword +(filter = filter) Filter image header keyword +(obstime= ut) Time of observation image header keyword +(itime = 1.) Exposure time +(xairmas= INDEF) Airmass +(ifilter= INDEF) Filter +(otime = INDEF) Time of observation +(mode = ql) +.YE + +.PP +Users should realize that the values of the parameters \fIreadnoise\fR +and \fIepadu\fR will be used for the gain and readout noise if the image +header keywords specified by \fIccdread\fR and \fIgain\fR are not found +in the image header or cannot be correctly decoded. Similarly the values of +the \fIitime\fR, +\fIxairmass\fR, \fIifilter\fR, and \fIotime\fR parameters will be used +for the exposure time, airmass, filter id, and time of observation if +the image header keywords specified by \fIexposure\fR, \fIairmass\fR, +\fIfilter\fR, and \fIobstime\fR are not found in the image header +or cannot be correctly decoded. +.PP +The \fBdatapars\fR parameters \fIfwhmpsf\fR, \fIsigma\fR, and \fIdatamin\fR +are used to: 1) determine the size of star for which the \fBdaofind\fR star +detection algorithm is optimized (fwhmpsf), 2) define the \fBdaofind\fR +algorithm detection threshold for faint objects (sigma), +3) define the fwhm of the psf for the \fBphot\fR task centering algorithms +"gauss" and "ofilter" (fwhmpsf), +4) supply a first guess for the true fwhm of the psf to the psf +function fitting task \fBpsf\fR (fwhmpsf), 5) determine the +minimum good data value +in the \fBdaofind\fR, \fBphot\fR, \fBpsf\fR, \fBpeak\fR, \fBgroup\fR, +\fBnstar\fR, and \fBallstar\fR tasks (datamin). +.PP +Reasonable values for these parameters can be obtained by examining the +radial profile plots of several isolated stars from within the +\fBdaoedit\fR task as outlined below: + +.IP ... +Move the image cursor on the displayed image to a +reasonably bright isolated star (a good candidate is +the star at pixel 8,23 in the test image) and execute +the \fBr\fR keystroke command. +A radial and integrated profile plot of the selected +star will appear on the screen with the largest photometry aperture radius, +inner and outer radii of the sky annulus, and median sky level in the sky +annulus marked on the plot. +.IP ... +Assuming that the plot is normal, note the computed +fwhmpsf (2.6 rounded to the nearest tenth of a pixel for +the star at 8,23), median sky value (100 counts rounded +to the nearest count for the star at 8,23), and standard +deviation of the sky values (10 counts rounded to the +nearest count for the star at 8,23) written in the plot header. +These numbers suggest a value of ~50 for datamin (50 is ~5 +standard deviations of the background counts below the +background count estimate) +.IP ... +Edit the estimated values into the datapars pset by +typing the command \fB":epar datapars"\fR, entering the values, +and typing \fB":wq"\fR to update the parameter set. + +.IP +or + +.IP ... +Enter them individually using the daoedit colon commands, +e.g. \fB":fwhmpsf 2.5"\fR, \fB":sigma 10.0"\fR, and \fB":datamin 50.0"\fR. +.IP ... +Check the new values of \fIfwhmpsf\fR, \fIsigma\fR, and \fIdatamin\fR +by doing radial profile plots of several +other isolated stars (the stars at 36,42 and 41,4 in +the test image are good test stars). +.IP ... +On the basis of the estimated \fIfwhmpsf\fR of these stars change the +fwhmpsf parameter back to 2.5 with the command +\fB":fwhmpsf 2.5"\fR. +.IP ... +Check that the observed standard deviation of the sky +background, sigma, agrees reasonably well with the +predicted value, psigma, based on the median sky level, +and the effective gain and readout noise of the image. +For the test image these numbers are related as shown below. + +.nf + psigma = sqrt (median sky / effective gain + + (effective rdnoise / effective gain) ** 2) + ~ sqrt (100.0 / 1.0 + (0. / 1.0) ** 2) + ~ 10.0 + ~ sigma +.fi + +.IP ... +If psigma and sigma are significantly different check +that the sky region is uncrowded, that the effective +gain and readout noise values are correct, and that +earlier reduction procedures have not altered the image +statistics in some fundamental manner + +.PP +The \fIemission\fR parameter must be left at "yes", +since DAOPHOT assumes that stars are local maxima not local minima. +.PP +The \fInoise\fR parameter must be left at "poisson" since poisson noise +statistics are assumed throughout the DAOPHOT package. +.PP +The \fIscale\fR parameter defines the units in which radial distances +in the image will be measured. For example if the image scale +is 0.25 "/pixel, users can set \fIscale\fR to 0.25 if they wish +to define the \fIfwhmpsf\fR, \fIcbox\fR, \fIannulus\fR, \fIdannulus\fR, +\fIapertures\fR, \fIpsfrad\fR, \fIfitrad\fR and all the other algorithm +parameters which are defined in terms of a radial distance in arc-seconds. +For simplicity most users choose to leave scale set to 1.0 and +work in pixels. +.PP +The final version of the \fBdatapars\fR parameter set should look something +like the following. + +.YS +Image Reduction and Analysis Facility +PACKAGE = daophot + TASK = datapars + +(scale = 1.) Image scale in units per pixel +(fwhmpsf= 2.5) FWHM of the PSF in scale units +(emissio= yes) Features are positive ? +(sigma = 10.) Standard deviation of background in counts +(datamin= 50.) Minimum good data value +(datamax= 24500) Maximum good data value +(noise = poisson) Noise model +(ccdread= rdnoise) CCD readout noise image header keyword +(gain = gain) CCD gain image header keyword +(readnoi= 0.) CCD readout noise in electrons +(epadu = 1.) Gain in electrons per count +(exposur= cexptime) Exposure time image header keyword +(airmass= airmass) Airmass image header keyword +(filter = filter) Filter image header keyword +(obstime= obstime) Time of observation image header keyword +(itime = 1.0) Exposure time +(xairmas= INDEF) Airmass +(ifilter= INDEF) Filter +(otime = INDEF) Time of observation +(mode = ql) +.YE + + +.NH 4 +The Centering Algorithm Parameters + +.PP +The \fBcenterpars\fR parameter set controls the centering algorithms used by +the \fBphot\fR aperture photometry task. DAOPHOT users should concern +themselves with only two of these parameters, \fIcalgorithm\fR and \fIcbox\fR, +and leave the remaining \fBcenterpars\fR parameters at their default values. +.PP +\fICalgorithm\fR specifies the default \fBphot\fR centering algorithm. Its value +should be "none" if the input coordinate list is the output of the +\fBdaofind\fR task, or "centroid", "gauss", or "ofilter" if the input +coordinate list was +created with the image or graphics cursor list tasks \fBrimcursor\fR +or \fBrgcursor\fR or the coordinates are +read from the image cursor in interactive mode. The choice of centering +algorithm is not critical since the centers are recomputed using accurate +non-linear least-squares fitting techniques during the psf fitting +process. The most efficient and simplest choice is "centroid", although +more accurate results may be obtained with "gauss" which is +very similar to the centering algorithm used in \fBdaofind\fR. +.PP +The \fIcbox\fR +parameter determines the width in scale units of the data used to compute +the center if \fIcalgorithm \fR is not "none". +For reasonable results \fIcbox\fR should be set to the equivalent of 5 or +~ 2 * \fIfwhmpsf\fR in pixels whichever is larger. +.PP +\fBCenterpars\fR can be edited from within the \fBdaoedit\fR task +with the command \fB":epar centerpars"\fR. After editing, the \fBcenterpars\fR +parameter set should look like the example below. Note that for the test +image \fIfwhmpsf\fR is ~2.5 pixels so \fIcbox\fR is left at 5.0. + +.YS +PACKAGE = daophot +TASK = centerpars + +(calgori= none) Centering algorithm +(cbox = 5.) Centering box width in scale units +(cthresh= 0.) Centering threshold in sigma above background +(minsnra= 1.) Minimum signal-to-noise ratio +(cmaxite= 10) Maximum iterations +(maxshif= 1.) Maximum center shift in scale units +(clean = no) Symmetry clean before centering +(rclean = 1.) Cleaning radius in scale units +(rclip = 2.) Clipping radius in scale units +(kclean = 3.) K-sigma rejection criterion in skysigma +(mkcente= no) Mark the computed center +(mode = ql) +.YE + +.NH 4 +The Sky Fitting Algorithm Parameters + +.PP +The \fBfitskypars\fR parameter set controls the sky fitting algorithm +parameters used by the \fBphot\fR task. At this point DAOPHOT users should +concern themselves with only three of these parameters: \fIsalgorithm\fR, +\fIannulus\fR, and \fIdannulus\fR. +.PP +Users should realize that the \fBphot\fR task computes sky values +for the individual stars, and that these values are +used in the \fBpsf\fR task to compute the psf, averaged to form a group sky +value in the \fBpeak\fR, \fBnstar\fR and \fBallstar\fR tasks if sky refitting +is disabled (the default) or an initial sky value if sky refitting +is enabled, and used +to compute the predicted signal-to-noise ratios in the \fBgroup\fR task. +Although the option to refit the skies at a later stage of analysis exists, +there are difficulties associated with this choice. It is +in the user's best interest to determine the skies as accurately as +possible as early as possible, since sky determination will probably be +the single most important factor in doing good photometry. +.PP +In cases where contamination of the sky region is mostly due +to crowding by neighboring stars users should use the default sky fitting +algorithm "mode"; if the variations in the background are due instead +to nebulosity or large contaminating objects so that the sky statistics are +confused +"median", "centroid", or "crosscor" might be a better choice; in cases +where the sky statistics +are so poor that the histogram is aliased, undersampled, or sparse such +as might be the case with +very low sky backgrounds "mean" might be the best choice. +When in doubt about the correct choice the user should leave \fIsalgorithm\fR +at "mode" but examine the results carefully for accuracy at each step. +.PP +A good starting value for the inner radius of the sky annulus is ~ 4 * +\fIfwhmpsf\fR +or ~ 10 pixels for the test image. The width of the sky annulus should be +sufficient to give a reasonable sample of sky pixels, >= 5 pixels. We have +chosen a dannulus of ~4 * \fIfwhmpsf\fR or 10 pixels for the test image. +.PP +\fBFitskypars\fR can be edited from within the \fBdaoedit\fR task +with the command \fB":epar fitskypars"\fR. After editing the \fBfitskypars\fR +parameter set should look like the example below. + +.YS +PACKAGE = daophot +TASK = fitskypars + +(salgori= mode) Sky fitting algorithm +(annulus= 10.) Inner radius of sky annulus in scale units +(dannulu= 10.) Width of sky annulus in scale units +(skyvalu= 0.) User sky value +(smaxite= 10) Maximum number of sky fitting iterations +(sloclip= 0.) Lower clipping factor in percent +(shiclip= 0.) Upper clipping factor in percent +(snrejec= 50) Maximum number of sky fitting rejection iteratio +(sloreje= 3.) Lower K-sigma rejection limit in sky sigma +(shireje= 3.) Upper K-sigma rejection limit in sky sigma +(khist = 3.) Half width of histogram in sky sigma +(binsize= 0.1) Binsize of histogram in sky sigma +(smooth = no) Boxcar smooth the histogram +(rgrow = 0.) Region growing radius in scale units +(mksky = no) Mark sky annuli on the display +(mode = ql) +.YE + +.NH 4 +The Aperture Photometry Parameters + +.PP +The \fBphotpars\fR parameter set controls the aperture photometry algorithm +parameters used by the \fBphot\fR task. At this point DAOPHOT users should +concern themselves with only one of these, \fIapertures\fR, the radius +of the aperture through which the initial magnitudes will be computed. +A good rule of thumb is to set the aperture radius to the maximum +of 3 pixels or 1.0 * \fIfwhmpsf\fR pixels. Although magnitudes can be measured +through more than one aperture at a time, it is the magnitude of the +smallest aperture radius along with \fIzmag\fR and the exposure time +which set the DAOPHOT instrumental magnitude scale, and +the magnitudes through the other apertures contribute nothing to the +DAOPHOT analysis until it comes time to compute accurate aperture +corrections. Therefore it is in the user's best interest to set \fIapertures\fR +to a single value at this point and carefully record it. +.PP +\fBPhotpars\fR can be edited from within the \fBdaoedit\fR task +with the command \fB":epar photpars"\fR. After editing the \fBphotpars\fR +parameter set should look like the example below. Note that in this example +\fIfwhmpsf\fR is ~2.5 pixels so \fIapertures\fR is left at 3.0. + +.YS +PACKAGE = daophot +TASK = photpars + +(weighti= constant) Photometric weighting scheme +(apertur= 3.0) List of aperture radii in scale units +(zmag = 25.) Zero point of magnitude scale +(mkapert= no) Draw apertures on the display +(mode = ql) +.YE + +.NH 4 +The Psf Modeling and Fitting Parameters + +.PP +The \fBdaopars\fR parameter set controls the psf computation, star grouping, +and psf fitting +parameters used by the \fBpstselect\fR, \fBpsf\fR, \fBpeak\fR, +\fBgroup\fR, \fBnstar\fR, +\fBallstar\fR, \fBsubstar\fR, and \fBaddstar\fR tasks. At this point +DAOPHOT users should +concern themselves with only two of these parameters \fIpsfrad\fR, the radius +over which the psf will be defined, and \fIfitrad\fR, the radius +over which the psf will be fit to the individual stars. A good rule of thumb is +to set \fIpsfrad\fR to the radius at which the radial profile of the brightest +star of interest disappears into the noise plus 1, something like +~ 4 * \fIfwhmpsf\fR + 1, and +to set \fIfitrad\fR to the maximum of 3 pixels or ~ 1 * \fIfwhmpsf\fR in pixels. + +.PP +\fBDaopars\fR can be edited from within the daoedit task +with the command \fB":epar daopars"\fR. After editing the \fBdaopars\fR +parameter set should look something like the example below for the +test image. + +.YS +PACKAGE = daophot +TASK = daopars + +(functio= gauss) Analytic component of psf +(varorde= 0) Order of psf variation +(nclean = 0) Number of cleaning passes +(saturat= no) Use wings of saturated stars +(matchra= 3.) Matching radius in scale units +(psfrad = 11.) Radius of psf in scale units +(fitrad = 3.) Fitting radius in scale units +(recente= yes) Recenter stars during fit +(fitsky = no) Recompute group sky value during fit +(sannulu= 0.) Inner radius of sky annulus in scale units +(wsannul= 11.) Width of sky annulus in scale units +(flaterr= 0.75) Flat field error in percent +(proferr= 5.) Profile error in percent +(maxiter= 50) Maximum number of iterations +(clipexp= 6) Data clipping exponent +(clipran= 2.5) Data clipping range in sigma +(critove= 1.) Critical overlap group for membership +(maxnsta= 10000) Maximum number of stars to fit +(maxgrou= 60) Maximum number of stars to fit per group +(mode = ql) +.YE + +.NH 4 +Setting the Algorithm Parameters Graphically + +.PP +Each of the radial distance dependent parameters \fIfwhmpsf\fR, +\fIcbox\fR, \fIannulus\fR, \fIdannulus\fR, \fIapertures,\fR, +\fIpsfrad\fR, \fIfitrad\fR can be edited +individually and interactively by marking the current radial profile +plot with the +graphics cursor after executing the appropriate keystroke command. +For example the \fBf\fR keystroke command will prompt the user to +mark the fwhm of +the psf on the current radial profile plot, +verify the marked value, and update the \fIfwhmpsf\fR parameter. +.PP +All the radial distance dependent parameters listed above +can be edited at once my moving the +image cursor to a bright star, typing the \fB daoedit i\fR keystroke command +to invoke the interactive graphics setup menu. +The size of the radial profile plot and the sky regions +are set by the \fIscale\fR, \fIannulus\fR, and \fIdannulus\fR parameters. +The centering algorithm +used is always "centroid" regardless of the value of the \fIcalgorithm\fR +parameter, \fIcbox\fR and \fIscale\fR determine the centering box size, +and the photometry is computed inside the largest aperture specified by +the \fIapertures\fR parameter. After the user finishes marking all the +parameters on the plot +he/she is given an opportunity to verify or edit the results, e.g., change the +value for fwhmpsf from 2.536 as read from the graphics cursor to 2.5. + +.NH 3 +Checking the Algorithm Parameters with Daoedit + +.PP +The purpose of setting all the critical algorithm parameters to reasonable +values before beginning any DAOPHOT analysis, is to ensure that the user +gets off to a good start. Although setting the parameters to unreasonable +values often results in bizarre results which are immediately obvious, +e.g., the detection of thousands of +noise spikes, the problems can sometimes be more subtle. +For example, a sky annulus that is too close to the star will result in +measured sky values which are too high and poor subtractions of +the fitted stars which may not be discovered until the user has +become thoroughly exasperated trying to produce good fits to the psf +stars. +.PP +The current DAOPHOT algorithm parameters can be checked at any time with +the \fBdaoedit\fR task and the \fB":lpar"\fR command. For example the +\fBdatapars\fR parameters set can be listed with the \fBdaoedit +":lpar datapars"\fR command. The remaining parameters sets \fBfindpars\fR, +\fBcenterpars\fR, \fBfitskypars\fR, \fBphotpars\fR, and \fBdaopars\fR +may be listed in the same way. +.PP +When listing the algorithm parameters users should check that: +.IP [1] +the \fBdatapars\fR image header keyword parameters \fIccdread\fR, \fIgain\fR, +\fIexposure\fR, \fIairmass\fR, \fIfilter\fR, and \fIobstime\fR are +properly set. +.IP [2] +the \fBdatapars\fR \fIfwhmpsf\fR, \fIsigma\fR, \fIdatamin\fR, and \fIdatamax\fR parameters +are appropriate for the image. Be especially careful of datamin as the +correct value for this parameter varies with the mean sky. +.IP [3] +the \fBdatapars\fR parameter \fIscale\fR is 1.0 unless the user is +thoroughly aware of the meaning of this parameter and the consequences +of setting it to something other than 1.0, and \fIemission\fR is "yes". +.IP [4] +the \fBcenterpars\fR \fIcbox\fR parameter is +appropriate for the image and the remaining \fBcenterpars\fR parameters +are at their default values unless the user +really understands the consequences of altering these parameters. +.IP [5] +the \fBfitskypars\fR \fIannulus\fR, and \fIdannulus\fR +parameters are appropriate for the image and the remaining \fBfitkskypars\fR +parameters are at their default values unless the user really +understands the consequences of altering these parameters. +.IP [6] +the \fBphotpars\fR \fIapertures\fR parameter is appropriate for the image +and the remaining parameters are at their default values unless the user +really understands the consequences of altering these parameters. +.IP [6] +the \fBdaopars\fR \fIpsfrad\fR and \fIfitrad\fR parameters are appropriate +for the image and all the remaining \fBdaopars\fR parameters are at their +default values unless the user really understands the consequences of +altering these parameters. + +.NH 3 +Storing the Algorithm Parameter Values with Setimpars + +.PP +The current values of all the algorithm parameters for a particular +image may be saved in a file on disk at any +point in the reduction sequence by executing the \fBsetimpars\fR task. +The following command saves the current values of the parameters for +the test image in a file called "test.pars". + +.YS +da> setimpars test no yes +.YE + +Repeating the previous command at any point in the reduction sequence will +replace the stored parameter values with the current parameter values. + + +.NH 3 +Restoring the Algorithm Parameter Values with Setimpars + +.PP +At some point the user may wish to interrupt work on a particular image and +begin work on a different image. This should be no problem as long as the +user remembers to save the algorithm parameter sets with \fBsetimpars\fR +as described in the previous section. +.PP +The command to restore the algorithm parameter sets for the test image is: + +.YS +da> setimpars test yes no +.YE + +or + +.YS +da> setimpars test yes no parfile=test.pars +.YE + + +.NH 2 +Creating a Star List + +.PP +The initial input to the DAOPHOT package is a star list. +Star lists may be created with the DAOPHOT package task \fBdaofind\fR, +interactively with the image or graphics cursor (the +\fBrimcursor\fR and \fBrgcursor\fR tasks), by another IRAF task, or by +any user program which writes a text file in the correct format. +.PP +Legal star lists are text files containing a list of stars, one star +per line with the x and y coordinates in columns one and two. +Blank lines, lines beginning with "#", and lines containing anything other +than numbers in columns one and two are ignored. +A sample DAOPHOT star list is shown below. + +.YS +# Artificial Stars for Image Test + + 41.0 4.0 17.268 + 23.0 7.0 17.600 + 18.0 8.0 17.596 + 26.0 22.0 16.777 + 36.0 22.0 16.317 + 8.0 23.0 16.631 + 31.0 25.0 16.990 + 21.0 26.0 19.462 + 29.0 34.0 17.606 + 36.0 42.0 16.544 +.YE + +.NH 3 +The Daofind Task + +.PP +The \fBdaofind\fR task, searches for point sources +in an image whose peak intensities are above some user-defined threshold, +computes approximate centers, magnitudes, and +shape characteristics for all the detected objects, and writes the results +to the output star list. + +.NH 4 +The Daofind Algorithm + +.PP +By default the \fBdaofind\fR algorithm performs the following steps: +.IP[1] +reads the \fBdaofind\fR task parameters, including the input image +and output star list names and the \fBdatapars\fR and \fBfindpars\fR +algorithm parameters, and asks the user to verify the +\fIfwhmpsf\fR, \fIsigma\fR, +\fIthreshold\fR, \fIdatamin\fR, and \fIdatamax\fR parameters +.IP[2] +calculates the convolution kernel whose mathematical function when +convolved with the input image is to +compute the amplitude of the best-fitting Gaussian of +full-width half-maximum \fIfwhmpsf\fR at each point in the input image +.IP[3] +convolves the input image with the convolution kernel after +eliminating bad data with the \fIdatamin\fR and \fIdatamax\fR parameters, +and writes the results to a temporary convolved image +.IP[4] +searches for local maxima in the convolved image whose amplitudes are greater +than the detection threshold, and greater than the amplitudes of any neighbors +within a region the size of the convolution kernel +.IP[5] +computes approximate centers, magnitudes, and shape +statistics for these local maxima +.IP[6] +eliminates local maxima whose centers are outside the image, and whose +sharpness and roundness statistics are outside the limits set by the user +.IP[7] +writes the centers, approximate magnitudes, sharpness and roundness +statistics, and id number for the remaining local maxima, to the +output star list +.IP[8] +deletes the convolved image + +.NH 4 +The Daofind Algorithm Parameters + +.PP +The critical \fBdaofind\fR algorithm parameters are \fIfwhmpsf\fR, +\fIdatamin\fR, \fIdatamax\fR, \fIsigma\fR, and \fIthreshold\fR. +These parameters are verified at startup time by \fBdaofind\fR. +.PP +The \fIfwhmpsf\fR parameter should be close +to the true full-width at half-maximum of the psf in order +to optimize the detection algorithm for stellar objects. If \fIfwhmpsf\fR +is too far from the true value, stars may be omitted from the star list +and/or non-stellar objects added to it. +.PP +The \fIdatamin\fR and \fIdatamax\fR parameters are used to flag and remove +bad data from the convolved image. +If \fIdatamin\fR and \fIdatamax\fR are +too far from the true value stars may be omitted from the star list +and/or non-stellar objects added to it. +.PP +The \fIsigma\fR parameter should be close to the true standard deviation of +the sky background in an uncrowded region of the frame. This parameter +in combination with \fIthreshold\fR +determines the detection threshold in counts for faint objects. If it is +incorrect either too few or too many objects will be detected. +.PP +The \fIthreshold\fR parameter should normally be set to some small +number between 3.0 and 5.0. If threshold is too big only +the brightest stars will be detected. If threshold is too small too +many noise spikes will be detected. + +.NH 4 +Running Daofind Non-Interactively + +.PP +The following example shows how to run \fBdaofind\fR in non-interactive mode. + +.YS +da> daofind test default + +FWHM of features in scale units (2.5) (CR or value): + New FWHM of features: 2.5 scale units 2.5 pixels +Standard deviation of background in counts (10.) (CR or value): + New standard deviation of background: 10. counts +Detection threshold in sigma (4.) (CR or value): + New detection threshold: 4. sigma 40. counts +Minimum good data value (50.) (CR or value): + New minimum good data value: 50. counts +Maximum good data value (24500.) (CR or value): + New maximum good data value: 24500. counts + +Image: test.imh fwhmpsf: 2.5 ratio: 1. theta: 0. nsigma: 1.5 + + 40.97 4.02 -1.663 0.612 0.017 1 + 23.06 7.03 -1.214 0.636 -0.019 2 + 18.02 7.96 -1.318 0.622 0.010 3 + 25.99 22.01 -2.167 0.658 0.001 4 + 35.98 22.00 -2.499 0.572 -0.039 5 + 8.02 22.97 -2.239 0.550 0.068 6 + 30.97 25.01 -1.934 0.711 -0.044 7 + 28.96 33.92 -1.087 0.418 0.132 8 + 35.98 42.03 -2.332 0.639 0.108 9 + +threshold: 40. relerr: 1.140 0.2 <= sharp <= 1. -1. <= round <= 1.\fR +.YE + +If this is the first time \fBdaofind\fR has been run the results will appear +in the file "test.coo.1". +.PP +The detected objects can be marked on the image display using the +\fBtvmark\fR task as shown below. + +.YS +da> display test 1 fi+ +da> tvmark 1 test.coo.1 col=204 +.YE + +In this example the detected stars will be marked on the displayed image +as red dots. If too many faints stars have been missed the user +can rerun \fBdaofind\fR with a lower value of the \fIthreshold\fR +parameter. + +.NH 4 +Running Daofind Interactively + +.PP +\fBDaofind\fR may also be run in interactive mode. +Most users will only exercise this option for small images which do not +require long cpu/elapsed times to perform the convolution. +.PP +The following example shows how to run \fBdaofind\fR interactively. + +.YS +da> display test 1 fi+ + +da> daofind test default inter+ +.YE + +.IP ... +Type the \fBv\fR keystroke command to verify the critical algorithm +parameters. +.LP + +.YS +FWHM of features in scale units (2.5) (CR or value): + New FWHM of features: 2.5 scale units 2.5 pixels +Standard deviation of background in counts (10.) (CR or value): + New standard deviation of background: 10. counts +Detection threshold in sigma (4.) (CR or value): + New detection threshold: 4. sigma 40. counts +Minimum good data value (50.) (CR or value): + New minimum good data value: 50. counts +Maximum good data value (24500.) (CR or value): + New maximum good data value: 24500. counts +.YE + +.IP ... +Type the \fBspacebar\fR keystroke command to detect the objects and write them +out to the star list file. +.LP + +.YS +Image: test.imh fwhmpsf: 2.5 ratio: 1. theta: 0. nsigma: 1.5 + + 40.97 4.02 -1.663 0.612 0.017 1 + 23.06 7.03 -1.214 0.636 -0.019 2 + 18.02 7.96 -1.318 0.622 0.010 3 + 25.99 22.01 -2.167 0.658 0.001 4 + 35.98 22.00 -2.499 0.572 -0.039 5 + 8.02 22.97 -2.239 0.550 0.068 6 + 30.97 25.01 -1.934 0.711 -0.044 7 + 28.96 33.92 -1.087 0.418 0.132 8 + 35.98 42.03 -2.332 0.639 0.108 9 + +threshold: 40. relerr: 1.140 0.2 <= sharp <= 1. -1. <= round <= 1. + +Output file: test.coo.1 +.YE + +.IP ... +Change \fIthreshold\fR to 3.0 with the colon command \fB:threshold 3.0\fR. +.IP ... +Type the \fBspacebar\fR keystroke command to detect the objects and write +them out to a new star list file. +.LP + +.YS +Image: test.imh fwhmpsf: 2.5 ratio: 1. theta: 0. nsigma: 1.5 + + 40.97 4.02 -1.975 0.577 0.017 1 + 23.06 7.03 -1.526 0.604 -0.019 2 + 18.02 7.96 -1.631 0.587 0.010 3 + 25.99 22.01 -2.480 0.626 0.001 4 + 35.98 22.00 -2.811 0.537 -0.039 5 + 8.02 22.97 -2.551 0.515 0.068 6 + 30.97 25.01 -2.246 0.681 -0.044 7 + 21.27 25.94 -0.146 0.804 -0.558 8 + 28.96 33.92 -1.400 0.379 0.132 9 + 35.98 42.03 -2.645 0.606 0.108 10 + +threshold: 30. relerr: 1.140 0.2 <= sharp <= 1. -1. <= round <= 1. + +Output file: test.coo.2 +.YE + +.IP ... +Change \fIthreshold\fR to 5.0 with the colon command \fB:threshold 5.0. +.IP ... +Type the \fBspacebar\fR keystroke command to detect the objects and write them +out to a new coordinate file. +.LP + +.YS +Image: test.imh fwhmpsf: 2.5 ratio: 1. theta: 0. nsigma: 1.5 + + 40.97 4.02 -1.420 0.577 0.017 1 + 23.06 7.03 -0.972 0.604 -0.019 2 + 18.02 7.96 -1.076 0.587 0.010 3 + 25.99 22.01 -1.925 0.626 0.001 4 + 35.98 22.00 -2.257 0.537 -0.039 5 + 8.02 22.97 -1.997 0.515 0.068 6 + 30.97 25.01 -1.692 0.681 -0.044 7 + 28.96 33.92 -0.845 0.379 0.132 8 + 35.98 42.03 -2.090 0.606 0.108 9 + +threshold: 50. relerr: 1.140 0.2 <= sharp <= 1. -1. <= round <= 1. + +Output file: test.coo.3 +.YE + +.IP ... +Type the \fBq\fR keystroke, first in the image display window then the +text window to quit the task. +.LP + +If this is the first run of \fBdaofind\fR, +the three star list files for the \fIthreshold\fR values of +4.0, 3.0, and 5.0 will be written to "test.coo.1", "test.coo.2", and +"test.coo.3" respectively. +.PP +The \fBdaofind\fR results for different thresholds can be evaluated by +marking the detected objects on the image display using the \fBtvmark\fR +task and different +colors for each threshold. In the following example objects detected +at threshold=3.0 are marked in red, at threshold=4.0 in green, at threshold= +5.0 in blue. + +.YS +da> display test 1 fi+ +da> tvmark 1 test.coo.2 col=204 point=3 +da> tvmark 1 test.coo.1 col=205 point=3 +da> tvmark 1 test.coo.3 col=206 point=3 +.YE + +Note that the identical stars were detected at thresholds 4.0 and 5.0 but +the faint star at 21,26 was only detected at threshold=3.0. +.PP +In this example the user decides that threshold = 4.0 is the +"best" threshold, sets the \fIthreshold\fR parameter appropriately as shown +below, and deletes the the star lists for threshold = 3.0 and threshold = 5.0. + +.YS +da> findpars.threshold = 4.0 +da> delete test.coo.2,test.coo.3 +.YE + +.NH 4 +The Daofind Output + +.PP +The quantities xcenter, ycenter, mag, sharpness, roundness, and id +are recorded for each detected object. Each is described briefly below. +.IP [1] +\fIXcenter\fR and \fIycenter\fR are the coordinates of +the detected object in fractional pixel units. They are computed by +fitting one-dimensional Gaussian functions of full-width at half-maximum +\fIfwhmpsf\fR to the x and y marginal pixel distributions centered on +the star. The computed coordinates can be overlaid on the +displayed image with the \fBtvmark\fR command. +.IP [2] +The estimated magnitude is measured relative to the detection threshold +and is defined as + +.YS +mag = -2.5 * log10 (density / (relerr * threshold * sigma)) +.YE + +where density is the peak density of the object in the convolved image, +relerr an internally +computed factor measuring the amount by which the standard error in one pixel +in the input image must be multiplied to obtain the standard error +in one pixel in the convolved image, and threshold and sigma +are the values of the corresponding \fIthreshold\fR and \fIsigma\fR +parameters. For stellar +objects the computed magnitude is directly proportional to the true +magnitude of the star. Stars with a peak density exactly equal to +the detection threshold will have a magnitude of 0.0. The remaining +stars will have negative magnitudes. +.IP [3] +The sharpness statistic is the ratio of the amplitude of the best fitting +delta function at the position of a detected object to the amplitude of +the best fitting gaussian at the same position as shown below. + +.YS +sharpness = (data - <data>) / density +.YE + +The amplitude of the best fitting gaussian is simply the density +of the detected object in the convolved image. +The amplitude of the best fitting delta function is defined +as corresponding original image data value minus the average of all +the neighboring +pixels in the image <data>. Typical values of sharpness are of ~0.6 for +approximately gaussian stars and \fInsigma\fR = 1.5. +Hot pixels will have sharpness values >> 1 and cold pixels will have +sharpness values +of ~0, hence reasonable limits for the \fIsharphi\fR and \fIsharplo\fR +parameters are 1.0 and 0.2 respectively. +Increasing the size of convolution box defined by the +\fInsigma\fR parameter from its default value of 1.5 to a larger value +(smaller values should be avoided !) while keeping the \fIfwhmpsf\fR the +same, will increase the average value of the sharpness statistic because +more pixels further from the center of the star are included in the +computation of <data>. If \fInsigma\fR is changed +the \fBfindpars\fR parameters \fIsharphi\fR and \fIsharplo\fR +will also need to be changed. +.IP [4] +The roundness statistic is computed by fitting a one-dimensional +gaussian function of full-width at half-maximum \fIfwhmpsf\fR to the +x and y marginal pixel distributions. + +.YS +roundness = 2.0 * (hx - hy) / (hx + hy) +.YE + +hx and hy are the heights of the best fitting one-dimensional +gaussians in x and y. A totally +round object will have a roundness of ~ 0.0. If the object is very +elongated in x roundness will be a large negative number; a large positive +number if it is elongated in y. The roundness statistic is +effective at filtering out bad columns and rows of data. It is not +effective at filtering out objects elongated at intermediate angles. +.IP [5] +Id is a sequence number which identifies the star. + +.NH 4 +Examining the Daofind Output + +.PP +The easiest way to check that \fBdaofind\fR is performing correctly is to mark +the detected stars on the image display with \fBtvmark\fR. +.PP +If the marked image suggests that \fBdaofind\fR is detecting too few or +too many stars the first items to check are the the values of the +\fIsigma\fR and \fIthreshold\fR parameters since these parameters determine the +detection threshold. Sigma should be +the standard deviation of the sky pixels in an uncrowded region of the image. +Threshold should normally be some number between 3.0 and 5.0. If sigma +and threshold are reasonable the user should compare the observed value of +sigma with the predicted value derived from the median background level and the +effective gain and readout noise values. If there is a significant +mismatch in these numbers the user should check the reduction history of the +image. The number of spurious detections goes up dramatically for +thresholds less than ~3.0 * sigma. A plot of number +of detections versus threshold will show a change in slope at some point below +this threshold. Users who wish to detect faint objects while keeping +spurious detections at a manageable minimum should +set the detection threshold to a value just above the threshold at +which this change in slope occurs. +.PP +Users should also check the values of the +parameters \fIsharplo\fR, \fIsharphi\fR, +\fIroundlo\fR, and \fIroundhi\fR parameters to ensure that +detected objects are not being unfairly filtered out. In particular the values +of \fIsharplo\fR and \fIsharphi\fR should be changed if the \fInsigma\fR +parameter is changed. +.PP +Finally the user should check +the \fIfwhmpsf\fR, \fInsigma\fR, \fIdatamin\fR and \fIdatamax\fR parameters +for correctness since these parameters control the computation of the +convolution kernel and the density enhancement image. +.PP +Histograms of the various columns in the \fBdaofind\fR output can be +plotted using the \fBpdump\fR and \fBphistogram\fR tasks. The following +example shows how to plot a histogram of the magnitudes. + +.YS +da> pdump test.coo.1 mag yes | phistogram STDIN binwidth=.1 +.YE + +The various columns can also be plotted against each other. +The following example shows how to plot magnitude error versus magnitude. + +.YS +da> pdump test.coo.1 mag,merr yes | graph point+ +.YE + +.PP +By setting the \fBdaofind\fR \fIstarmap\fR and \fIskymap\fR parameters the +user can save and examine the density enhancement image and the corresponding +background density image. The sum of these two images should yield a +close representation of the original image except for regions of +bad data and edge pixels. Due to the nature of the convolution kernel +the starmap image will have a mean value of +~0.0 in the sky regions, an rms \(~= relerr * sigma in the sky regions, +and positive peaks of intensity surrounded by negative valleys at the positions +of bright stars. The skymap image will have a mean value \(~= sky in +the sky regions, an rms \(~= sqrt (sigma ** 2 / N + K * (relerr * sigma) ** 2), +(N is the number of pixels in the gaussian kernel and K is the average power +in the gaussian kernel), and dips in intensity surrounded by +bright rings at the position of the stars. + +.NH 3 +Rgcursor and Rimcursor + +.PP +The LISTS package tasks \fBrimcursor\fR and \fBrgcursor\fR can be used to +generate coordinate lists interactively. For example a coordinate +list can be created using the image display and the image display cursor +as shown below. + +.YS +da> display test 1 fi+ + +da> rimcursor > test.coo +.YE + +.IP ... +Move cursor to stars of interest and tap the space bar. +.IP ... +Type <EOF> to terminate the list. + +.PP +A coordinate list can also be created using a contour plot and the graphics +cursor as shown below. + +.YS +da> contour test + +da> rgcursor > test.coo +.YE + +.IP ... +Move the cursor to the stars of interest and tap the space bar. +.IP ... +Type <EOF> to terminate the list. + +.PP +In both cases the text file "test.coo" contains the x and y coordinates of +the marked stars in image pixel units. The output of \fBrimcursor\fR or +\fBrgcursor\fR can +be read directly by the DAOPHOT \fBphot\fR task. + +.NH 3 +User Program + +.PP +Any user program which produces a text file with the stellar coordinates +listed one per line with x and y in columns 1 and 2, can be used to produce +DAOPHOT coordinate files which can be read by the \fBphot\fR task. + +.NH 3 +Modifying an Existing Coordinate List + +.PP +The LISTS package routine \fBlintran\fR +can be used to perform simple coordinate transformations on +coordinate lists including shifts, magnifications, and rotations. + +.NH 2 +Initializing the Photometry with Phot + +.PP +The \fBphot\fR task computes initial centers, +sky values, and initial magnitudes for all the objects in the input +star list. The centers and magnitudes are used as starting +values for the non-linear +least-squares psf computation and fitting routines in the \fBpsf\fR, +\fBpeak\fR, \fBnstar\fR, and \fBallstar\fR tasks, and to estimate +signal-to-noise +values in the \fBgroup\fR task. The individual sky values +computed by \fBphot\fR are used directly by the \fBpsf\fR task to compute +the psf model, by the +\fBpeak\fR, \fBnstar\fR, +and \fBallstar\fR tasks to compute the group sky values, and by the +\fBgroup\fR task to estimate signal-to-noise ratios. + +.NH 3 +The Phot Algorithm + +.PP +By default the \fBphot\fR task performs the following functions: +.IP [1] +reads in the \fBphot\fR task parameters including the input image name, +the input coordinate file name, the output photometry file name, +the \fBdatapars\fR, \fBcenterpars\fR, \fBfitskypars\fR, and \fBphotpars\fR +algorithm parameters, and determines whether the task mode of operation +is interactive or non-interactive +.IP [2] +reads in the initial coordinates of a star from the coordinate list and/or +the image cursor, and computes new coordinates for the star using the centering +algorithm defined by the \fIcalgorithm\fR parameter (if \fIcalgorithm\fR +is not "none") using data in a box whose size is defined by the \fIcbox\fR +parameter +.IP [3] +computes the sky value for the star using the default algorithm +specified by the \fIsalgorithm\fR parameter and the data in an annulus of +pixels defined by the \fIannulus\fR and \fIdannulus\fR parameters +.IP [4] +computes the instrumental magnitude and magnitude error for each star +inside the aperture radii +specified by the \fIapertures\fR parameter using fractional pixel techniques, +the computed sky value, the standard deviation of the sky pixels, and the +gain of the CCD +.IP [6] +sets the instrumental magnitude scale for the image using the +\fBphotpars\fR \fIzmag\fR parameter and the exposure time specified by +the \fBdatapars\fR \fIexposure\fR or \fIitime\fR parameters +.IP [7] +sets the magnitude(s) to INDEF for stars which are saturated or contain +bad data, +for which the aperture is partially off the image, for which a sky +value could not be computed, or for which the +signal is fainter than the background +.IP [8] +writes the results to the output photometry file + +.NH 3 +The Phot Algorithm Parameters + +.PP +The critical \fBphot\fR algorithm parameters are \fIcalgorithm\fR, +\fIsalgorithm\fR, +\fIannulus\fR, \fIdannulus\fR, \fIapertures\fR, \fIdatamin\fR and +\fIdatamax\fR. These parameters are verified by \fBphot\fR +at startup time. +.PP +The \fIcalgorithm\fR parameter tells \fBphot\fR how to compute +centers for the objects in the coordinate list. Calgorithm should be "none" +if the coordinate +list was computed by \fBdaofind\fR or the coordinates are known to +be precise; otherwise calgorithm should one of "centroid", "gauss", or +"ofilter". "centroid" is quick and sufficiently accurate in most cases; +"gauss" and "ofilter" take longer but are more accurate. If calgorithm is +not "none", +\fBphot\fR will ask the user to verify the centering box size +\fIcbox\fR. \fIcbox\fR should be set to 5 or ~2 * \fIfwhmpsf\fR pixels wide +whichever is greater. +.PP +The \fIsalgorithm\fR parameter tells \fBphot\fR how to compute the sky +values. If the +fluctuations in the sky background are due primarily to crowding the +default choice +"mode" should be used. If the fluctuations in the sky background +are due to nebulosity or large galaxies +and the sky statistics are confused, "median", "centroid" or +"crosscor" might be the best choice. In cases where the +background is very low and the sky histogram is sparse or +undersampled "mean" might be the best choice. +.PP +The \fIannulus\fR and \fIdannulus\fR parameters tell \fBphot\fR the +position of the sky annulus with respect to the star. The sky region +must be far enough away from the star to avoid contamination from +the star itself, but close enough +to be representative of the intensity distribution under the star. Values of +~ 4.0 * \fIfwhmpsf\fR for both parameters are good starting values. +.PP +The \fIapertures\fR parameter tells \fBphot\fR the radius of the +photometry aperture. The photometry through this aperture sets the +instrumental magnitude scale for all the subsequent DAOPHOT +reductions. \fIApertures\fR should be ~ 1.0 * \fIfwhmpsf\fR. +.PP +The \fIdatamin\fR and \fIdatamax\fR parameters are used to detect +bad data in the photometry and sky apertures. Bad data is removed from +the sky pixel list before sky fitting takes place so it is important +that datamax and datamin, but particularly datamin, be correct. +Stars which have bad data in the photometry apertures will have their +magnitudes set to INDEF and be flagged with an error. + +.NH 3 +Running Phot Non-interactively + +.PP +The following example shows how to run \fBphot\fR in non-interactive +mode using the results of \fBdaofind\fR as input. + +.YS +da> phot test default default + +Centering algorithm (none) (CR or value): + New centering algorithm: none +Sky fitting algorithm (mode) (CR or value): + Sky fitting algorithm: mode +Inner radius of sky annulus in scale units (10.) (CR or value): + New inner radius of sky annulus: 10. scale units 10. pixels +Width of the sky annulus in scale units (10.) (CR or value): + New width of the sky annulus: 10. scale units 10. pixels +File/list of aperture radii in scale units (3.0) (CR or value): 3.0 + Aperture radius 1: 3. scale units 3. pixels +Minimum good data value (50.) (CR or value): + New minimum good data value: 50. counts +Maximum good data value (24500.) (CR or value): + New maximum good data value: 24500. counts + +test 40.97 4.02 100.7955 17.218 ok +test 23.06 7.03 100.3257 17.650 ok +test 18.02 7.96 99.40262 17.484 ok +test 25.99 22.01 101.3196 16.800 ok +test 35.98 22.00 101.1601 16.373 ok +test 8.02 22.97 98.89139 16.603 ok +test 30.97 25.01 101.2904 17.051 ok +test 28.96 33.92 100.6189 17.782 ok +test 35.98 42.03 101.043 16.594 ok + +.YE + +\fBPhot\fR looks for an input star list called "test.coo.?", +creates a file called "test.mag.?", and verifies +the critical parameters. By default the verbose switch is set to "yes", +so a short summary of the results for each star is printed on the +terminal as it is computed. +.PP +\fBPhot\fR may also be run non-interactively from a coordinate list created +with the image cursor list task \fBrimcursor\fR as shown below. Note +that centering has been turned on, and the verify switch has been turned off. + +.YS +da> display test 1 fi+ + +da> rimcursor > cursor.coo + +da> page cursor.coo + +41.02 4.033 101 \040 +22.918 6.969 101 \040 +18.123 7.849 101 \040 +25.951 21.939 101 \040 +35.736 21.744 101 \040 + 7.947 23.016 101 \040 +30.843 24.777 101 \040 +28.984 33.779 101 \040 +36.127 41.705 101 \040 + +da> phot test cursor.coo default calg=centroid verify- + +test 40.92 4.04 100.8871 17.222 ok +test 23.17 6.97 100.6163 17.666 ok +test 18.04 7.92 99.55305 17.487 ok +test 25.96 21.97 101.4161 16.801 ok +test 35.94 21.98 101.2101 16.373 ok +test 8.05 23.00 98.74371 16.601 ok +test 30.94 25.02 101.3224 17.052 ok +test 28.91 33.85 100.6207 17.786 ok +test 35.96 42.08 100.9039 16.591 ok\fR +.YE + +The "centroid" algorithm +computes a new center by doing an intensity-weighted sum of the +x and y marginals, whereas the \fBdaofind\fR algorithm +fits a 1D gaussian to the marginal pixel distributions in x and y. +The following example shows the results for the almost equivalent +\fBphot\fR centering algorithm "gauss". + +.YS +da> phot test cursor.coo default calg=gauss verify- + +test 41.00 4.03 100.8698 17.219 ok +test 23.11 7.03 100.3567 17.653 ok +test 18.02 7.96 99.40262 17.484 ok +test 25.98 21.97 101.4021 16.801 ok +test 35.96 21.99 101.2101 16.373 ok +test 8.02 22.98 98.77907 16.601 ok +test 30.97 25.02 101.2904 17.051 ok +test 28.93 33.94 100.6726 17.783 ok +test 35.97 42.02 100.976 16.593 ok\fR +.YE + +The positions produced by the "gauss" algorithm are closer to +the positions computed by the \fBdaofind\fR task, +than those computed by the "centroid" algorithm. +However as the positions computed by \fBphot\fR are used as initial +positions by the DAOPHOT tasks, +it is usually not necessary to go to the more expensive "gauss" algorithm. + +.NH 3 +Running Phot Interactively + +.PP +\fBPhot\fR can also be configured to run interactively using the +image display and image +cursor for coordinate input. In this mode the user loads the image +into the display and runs +\fBphot\fR interactively by turning the interactive switch on as +shown below. +When the program is ready to accept input the cursor will begin +blinking in the display window. The following series of steps will +do photometry on stars selected with the image cursor. + +.YS +da> display test 1 fi+ + +da> phot test "" default interactive+ calgorithm=centroid +.YE + +.IP ... +Execute the \fBv\fR keystroke command to verify the critical parameters. +.LP + +.YS +Centering algorithm (centroid) (CR or value): + New centering algorithm: centroid +Centering box width in scale units (5.) (CR or value): + New centering box width: 5. scale units 5. pixels +Sky fitting algorithm (mode) (CR or value): + Sky fitting algorithm: mode +Inner radius of sky annulus in scale units (10.) (CR or value): + New inner radius of sky annulus: 10. scale units 10. pixels +Width of the sky annulus in scale units (10.) (CR or value): + New width of the sky annulus: 10. scale units 10. pixels +File/list of aperture radii in scale units (3.) (CR or value): + Aperture radius 1: 3. scale units 3. pixels +Standard deviation of background in counts (10.) (CR or value): + New standard deviation of background: 10. counts +Minimum good data value (50.) (CR or value): + New minimum good data value: 50. counts +Maximum good data value (24500.) (CR or value): + New maximum good data value: 24500. counts +.YE + +.IP ... +Move the cursor to the stars of interest and tap the \fBspacebar\fR to do +the photometry. +.LP + +.YS +test 40.92 4.04 100.8871 17.222 ok +test 23.17 6.97 100.6163 17.666 ok +test 18.04 7.92 99.55305 17.487 ok +test 25.96 21.97 101.4161 16.801 ok +test 35.94 21.98 101.2101 16.373 ok +test 8.05 23.00 98.74371 16.601 ok +test 30.94 25.02 101.3224 17.052 ok +test 28.91 33.85 100.6207 17.786 ok +test 35.96 42.08 100.9039 16.591 ok +.YE + +.IP ... +Type \fBq\fR to quit image, and \fBq\fR again to exit task. +.LP + +The coordinate file name has been set to "" so that initial +positions for the stars to be measured will be read from the image +cursor, and the centering algorithm has been temporarily changed +on the command line +from "none" to "centroid" so that new centers will be computed. +The user simply points the cursor to the stars to be measured and taps the +space bar to measure the star. This option is often useful for +picking up stars missed by \fBdaofind\fR in a previous iteration, +or in cases where the user only wishes to measure a small group of stars. + +.NH 3 +The Phot Output + +.PP +\fBPhot\fR produces a large output file containing many parameters, +intermediate and final results. The principle +quantities of interest are: 1) the position +of the star xcenter and ycenter, 2) the sky value, +its standard deviation, and the number of pixels used to compute +it, msky, stdev, and nsky 3) the total +counts inside the aperture and the effective area of the aperture, +sum and area 4) the magnitude and magnitude error in the +aperture, mag and merr, +and 5) the exposure time, airmass, filter, and time of observation, itime, +xairmass, ifilter, and otime. +.IP [1] +\fIXcenter\fR and \fIycenter\fR are the computed coordinates for +the detected objects in fractional pixels. They can be overlaid on the +displayed image with the \fBtvmark\fR command. These numbers should be compared +with the initial coordinates xinit and yinit, to which they will be equal +if the centering algorithm was "none", or to which they should be close +if the centering algorithm is "centroid", "gauss", or "ofilter" assuming +that the original x and y positions were reasonable. +.IP [2] +\fIMsky\fR, \fIstdev\fR and \fInsky\fR are the estimated sky value in counts, +its standard deviation in counts, and the number of pixels used to compute it. +Users should, check that the position of the sky annulus is reasonable +and, check that the msky, stdev, and nsky values are reasonable +for a few isolated stars before proceeding. +.IP [3] +\fISum\fR and \fIarea\fR are the total counts (star + sky) in the +photometry aperture and area is area of the aperture in pixels squared +and should be roughly +equal to PI * r ** 2 where r is the radius of the photometry aperture +in pixels. +.IP [4] +\fIMag\fR and \fImerr\fR are the magnitude and magnitude error respectively +computed as follows. + +.YS + mag = zmag - 2.5 * log10(sum - area * msky) + 2.5 * log10(itime) + +merr = 1.0857 * sqrt((sum - area * msky) / gain + area * stdev ** 2 + + area ** 2 * stdev ** 2 / nsky) / (sum - area * msky) +.YE + +Users should check that the exposure time \fIitime\fR is correct since it +is used to determine the instrumental magnitude scale. The correct value +of gain is also required in order to get a correct estimate of the +magnitude error. Stdev is the observed standard deviation +of the sky pixels not the predicted value. +.IP [5] +The remaining quantities itime, \fIxairmass\fR, \fIifilter\fR, and \fIotime\fR +should be checked for correctness, e.g., were they read correctly from the image +header. + +.NH 3 +Examining the Results of Phot + +.PP +The user can check the results of \fBphot\fR in several +ways. The following command will mark all +stars in the \fBphot\fR output file on the display in red. + +.YS +da> display test 1 +da> pdump test.mag.1 xcenter,ycenter yes | tvmark 1 STDIN col=204 +.YE + +The following command will mark all the stars whose magnitudes are INDEF on +the screen in green. + +.YS +da> pdump test.mag.1 xcenter,ycenter "mag == INDEF" | tvmark \\ + 1 STDIN col=205 +.YE + +The following command will plot magnitude error versus magnitude for all +the stars in the photometry file. + +.YS +da> pdump test.mag.1 mag,merr yes | graph STDIN point+ +.YE + +The following command will plot a histogram of the magnitude distribution. + +.YS +da> pdump test.mag.1 mag,merr yes | phist STDIN plot_type=box +.YE + +The photometry file can be examined interactively with the \fBpexamine\fR +task as shown below. + +.YS +da> pexamine test.mag.1 "" test +.YE +.IP ... +A vector plot of magnitude error versus magnitude appears on the screen. +.IP ... +To examine individual stars in the vector plot move the graphics cursor to a +star and type \fBo\fR to get a record listing for the star, +followed by \fBr\fR, \fBc\fR, or \fBs\fR to see a radial profile plot, +contour plot, or surface plot respectively, of the star. +.IP ... +To activate the image cursor type \fBi\fR, move the cursor to a star +and type \fBo\fR to get a record listing +for the star, followed by \fBr\fR, \fBc\fR or \fBs\fR to draw the desired plot. +To reactivate the graphics cursor type \fBg\fR. +.IP ... +To plot magnitude error versus x coordinate for all the stars in the file, type +\fB:xcolumn xcenter\fR and \fB:ycolumn merr\fR followed by \fBp\fR to +redraw the plot. +.IP ... +To plot a histogram of the magnitudes of the objects type \fBh\fR. +.IP ... +Type \fBq\fR to quit. + +.NH 2 +Creating a Psf Star List with Pstselect + +.PP +The psf model fitting routines require a list of bright isolated stars +well distributed over the image to use as psf model templates. +The \fBpstselect\fR +task is used to select suitable candidate stars from the photometry file +for input to the psf modeling task \fBpsf\fR. + +.NH 3 +The Pstselect Algorithm + +.PP +By default the \fBpstselect\fR task performs the following functions: +.IP[1] +reads the task parameters including the input image name, input +photometry file, and output psf star list, reads the \fBdatapars\fR +and \fBdaopars\fR algorithm parameters, and determines whether the +task will be run interactively or non-interactively +.IP [2] +reads the dimensions of the input image from the input image header, and +the ids, x and y coordinates, magnitudes, and sky values of up to +\fImaxnstar\fR stars from the input photometry file +.IP [2] +assigns a large negative number to the magnitudes of all stars whose +measured magnitudes are INDEF in the input photometry file +.IP [3] +sorts the stars in order of increasing magnitude so that +the saturated and brightest stars are at the beginning of the list +.IP [4] +selects the +brightest \fImaxnpsf\fR stars (where maxnpsf is a number chosen by the user) +which are, not saturated, more than \fIfitrad\fR pixels away from the edge +of the input image, have no bad data within \fIfitrad\fR pixels, +and have no brighter neighbor stars within +(\fIpsfrad\fR + \fIfitrad\fR + 2) pixels +.IP [5] +writes the ids, x and y coordinates, magnitudes, and sky values +of the selected stars as read from the input photometry list +to the output psf star list + +.NH 3 +The Pstselect Algorithm Parameters + +.PP +The critical \fBpstselect\fR algorithm parameters are \fIpsfrad\fR, +\fIfitrad\fR, \fIdatamin\fR, and \fIdatamax\fR. +.PP +\fIPsfrad\fR and \fIfitrad\fR are used by \fBpstselect\fR to eliminate +potential psf stars which have bright neighbors. +For the test image these parameters are currently set +to 4 * \fIfwhmpsf\fR + 1 and 1 * \fIfwhmpsf\fR or 11 and 3 pixels respectively. +However as \fBpstselect\fR is the first task to actually use the values +of these parameters, the user should +check them here one more time before running \fBpstselect\fR. +\fIFitrad\fR should be ~ 1 * \fIfwhmpsf\fR +for optimal psf model computation and fitting so the user leaves it +at its current value of 3.0. \fIPsfrad\fR should be set to the radius at which +the profile of the brightest stars of interest disappear into the +noise. Normally 4 * \fIfwhmpsf\fR + 1 pixels is a good starting value for +this quantity. +If \fIpsfrad\fR is too small the fitted stars will not subtract completely +from the input image, if it is too big DAOPHOT +will consume cpu time doing unnecessary data extractions +and subtractions. +One way to check the value of the \fIpsfrad\fR parameter is to +use the \fBdaoedit\fR task to examine +radial profiles of isolated stars in the input image as shown below. + +.YS +da> display test 1 fi+ + +da> daoedit test +.YE + +.IP ... +Move cursor to star at 36,42 and press the \fBr\fR key. +.IP ... +Examine the resulting radial profile and note that the stellar profile +disappears into the noise at ~4 pixels. +.IP ... +Move the cursor to the star at 8,23 and press the \fBr\fR key. +.IP ... +Examine the radial profile and note that this stellar profile +also disappears into the noise at ~4 pixels. +.IP ... +Set \fIpsfrad\fR to 5.0 pixels by typing the command \fB:psfrad 5.0\fR. +.IP ... +Type \fBq\fR to quit the \fBdaoedit\fR task. +.YE + +.PP +The \fBpexamine\fR task and the input photometry file can also be +used to examine the radial profiles of isolated stars in the +photometry file. + +.YS +da> display test 1 fi+ + +da> pexamine test.mag.1 "" test +.YE + +.IP ... +A plot of magnitude error versus magnitude appears on the screen. +.IP ... +Type \fBi\fR to activate the image cursor. +.IP ... +Move the cursor to the star at 36,42 and type \fBr\fR, adjust the +outer radius of the plot with the command \fB:router\fR if necessary, +e.g., \fB:router 10\fR. +.IP ... +Examine the radial profile and note that it disappears into the noise at a +radius of ~4 pixels. +.IP ... +Move the cursor to the star at 8,23 and type \fBr\fR. +.IP ... +Examine the radial profile and note that that it +also disappears into the noise at a radius of ~4 pixels. +.IP ... +Type \fBq\fR to quit the pexamine task. +.LP + +The new value of \fIpsfrad\fR can be stored by editing the \fBdaopars\fR +parameter set with \fBepar\fR in the usual manner or on the command +line as shown below. + +.YS +da> daopars.psfrad = 5.0 +.YE + +.PP +Why is the value of 5.0 pixels for \fBpsfrad\fR so different from the +original estimate of 11.0 ? +There are two reasons. Firstly the stars in artificial image +test are quite faint, +with the brightest peaking at ~400 counts above background. Their stellar +profiles disappear into the noise quite quickly. Secondly the artificial +stars are gaussian in shape with a sigma \(~= 1.0 pixels. +Unlike real stars they have almost all their light +in the core and none in the wings. For realistic optical images +11.0 pixels rather than 5.0 would be a more reasonable choice +for \fIpsfrad\fR than 5.0. +.PP +The \fIdatamin\fR and \fIdatamax\fR parameters are used to reject +psf stars with bad data within \fIfitrad\fR pixels. +If \fIdatamin\fR and \fIdatamax\fR are set correctly before +the \fBphot\fR task is run, these parameters are redundant as stars +with bad data inside the photometry aperture will have INDEF magnitudes. +.PP +At this point the user should check that the current value of the +\fImaxnstar\fR parameter is larger than the total number of stars +in the photometry file written by the \fBphot\fR task. If \fImaxnstar\fR +is too small, \fBpstselect\fR cannot read the entire input photometry +file into memory and potential psf stars may be missed. + +.NH 3 +How Many Psf Stars Should Be Selected ? + +.PP +How many stars should the user select to create the psf model ? +An absolute minimum +set by the mathematics is 1 star for a constant psf model, +3 stars for a linearly variable psf model, and +6 stars for a quadratically variable psf model. A more reasonable minimum +suggested by Stetson (1992) is 3 stars +per degree of freedom or, +3 stars for a constant psf model, 9 stars for a linearly variable psf model, +and 18 stars for a quadratically variable psf model. If a variable psf model +is required, it is vitally important that the psf star list +sample the region of interest in the input image completely and +reasonably uniformly. +As the contribution of each psf star to the psf model is weighted by +its signal-to-noise, the psf stars may cover a range in magnitude without +compromising the resulting psf model. + +.NH 3 +Running Pstselect Non-interactively + +.PP +The following example shows how to run the \fBpstselect\fR task +in non-interactive mode. + +.YS +da> pstselect image default default 3 + +Psf radius in scale units (5.): + New psf radius: 5. scale units 5. pixels +Fitting radius in scale units (3.): + New fitting radius: 3. scale units 3. pixels +Minimum good data value (50.) (CR or value): + New minimum good data value: 50. counts +Maximum good data value (24500.) (CR or value): + New maximum good data value: 24500. counts + +Star 5 has been added to the PSF star list + X: 35.98 Y: 22.00 Mag: 16.372 Dmin: 82.96088 Dmax: 535.1335 +Star 9 has been added to the PSF star list + X: 35.98 Y: 42.03 Mag: 16.594 Dmin: 80.25255 Dmax: 489.9732 +Star 6 has been added to the PSF star list + X: 8.02 Y: 22.97 Mag: 16.603 Dmin: 71.00896 Dmax: 436.3393 + +Total of 3 PSF stars selected\fR +.YE + +By default \fBpstselect \fR looks for an input photometry file called +"test.mag.?" and writes an output psf star list called +"test.pst.?". + +.NH 3 +Running Pstselect Interactively + +.PP +\fBPstselect\fR may also be run interactively. In this mode of operation +the stars selected +by \fBpstselect\fR are examined by the user and accepted or rejected on +the basis of the appearance of their mesh, contour or radial profile plots +until a total of \fImaxnpsf\fR psf stars is reached. +Stars from the input photometry file which do not meet the +\fBpstselect\fR task selection criteria, +can be added to the psf star list by the user with the image cursor +until a total of \fImaxnpsf\fR psf stars have been selected. +.PP +The following example shows how to run \fBpstselect\fR in interactive +mode. + +.YS +da> pstselect image default default 3 inter+ plottype=radial + +Psf radius in scale units (5.): + New psf radius: 5. scale units 5. pixels +Fitting radius in scale units (3.): + New fitting radius: 3. scale units 3. pixels +Minimum good data value (50.) (CR or value): + New minimum good data value: 50. counts +Maximum good data value (24500.) (CR or value): +.YE + +.IP ... +The image cursor appears on the screen ready to accept user input. +.IP ... +Type \fBn\fR to display the first potential psf star found by +\fBpstselect\fR, \fBa\fR to select the star, or \fBd\fR to delete it. +.IP ... +Repeat the previous step for 2 more stars. +.IP ... +Type \fBl\fR to list the selected psf stars. +.IP ... +Type \fBq\fR to quit the task. + +.PP +By default \fBpstselect \fR looks for an input photometry file called +"test.mag.?" and writes an output psf star list called +"test.pst.?" as before. + +.NH 3 +The Pstselect Output + +.PP +The output psf star list consists of the ids, x and y coordinates, +magnitudes, and sky values of the selected psf stars copied from the +input photometry file without change. + +.NH 3 +Examining and/or Editing the Results of Pstselect + +.PP +The \fBpdump\fR and \fBtvmark\fR commands can be used to mark +and label the selected psf stars on the image display as shown in the +following example. + +.YS +da> display test 1 fi+ +da> pdump test.pst.1 xcenter,ycenter,id yes | tvmark 1 STDIN \\ + col=204 label+\fR +.YE + +Bad stars can be removed from the psf star list using the displayed and +labeled image and +the text editor, the \fBpselect\fR task, or +the \fBpexamine\fR task. +.PP +The following command shows how to create a new psf star list +without the psf star whose id is "5" using the \fBpselect\fR task. + +.YS +da> pselect test.pst.1 test.pst.2 "id != 5"\fR +.YE + +.PP +The same operation can be accomplished using the \fBpexamine\fR task +as shown below. + +.YS +da> pexamine test.pst.1 test.pst.2 test +.YE + +.IP ... +A message appears on the screen to the affect that +pexamine cannot plot x versus y since the default y +column merr is not in the input file. +.IP ... +The user types \fBh\fR to plot a histogram of the magnitudes +and notes that there are three stars in the histogram. +.IP ... +The user decides that the star with id number 5 marked on the +display should be deleted because it is too crowded. +.IP ... +The user types the \fBi\fR key to bring up the image cursor, moves +it to star number 5, types the \fBd\fR key to delete the star, and +the \fBp\fR key to replot the data. +.IP ... +The user types the \fBf\fR key to make the deletions permanent and the \fBe\fR +key to exit the task, and update the output catalog. +.LP + +Finally the user marks the new list on the display image using a +different marking color. + +.YS +da> pdump test.pst.2 xcenter,ycenter,id yes | tvmark 1 STDIN \\ + col=205 label+ +.YE +.LP + +.NH 2 +Computing the Psf Model with Psf + +.PP +The \fBpsf\fR task computes the psf model used by the +\fBpeak\fR, \fBnstar\fR, and \fBallstar\fR tasks to do psf fitting +photometry, by the \fBgroup\fR task to estimate magnitudes for stars +whose initial magnitudes are INDEF, and by the \fBaddstar\fR and +\fBsubstar\fR tasks to add stars to and subtract stars from an image. + +.NH 3 +The Psf Algorithm + +.PP +By default the \fBpsf\fR task performs the following functions: +.IP [1] +reads the \fBpsf\fR task parameters including, the input image name, +the input photometry file name, the input psf star list name, +the output psf image name, +the output psf star list name, the output psf star group file name, and +the \fBdatapars\fR and \fBdaopars\fR algorithm parameters +.IP [2] +reads the ids, x and y coordinates, magnitudes, and sky values +of the first \fImaxnstar\fR stars in the input photometry file +.IP [3] +reads the ids, x and y coordinates, magnitudes, and sky values +of the candidate psf stars from the input psf star list and/or +the image cursor, rejecting stars +which are not in the input photometry file, are within \fIfitrad\fR pixels +of the edge of the image, are saturated (if +the parameter \fIsaturated\fR is "no"), +or have bad data within \fIfitrad\fR pixels +.IP [4] +computes the analytic component of the psf model +specified by the parameter \fIfunction\fR using, data within \fIfitrad\fR +pixels of each psf star, weights proportional to the signal-to-noise +ratio in each psf star, and non-linear least-squares fitting techniques +.IP [5] +computes the residuals of each psf star from the best fit analytic function +within a radius of \fIpsfrad\fR + 2 pixels +.IP [6] +scales the residuals for each psf star to match the intensity of the first +psf star, subsamples the scaled residuals in x and y by a factor of 2, +weights the residuals by the signal-to-noise ratio of the psf star, +and combines the scaled, subsampled, and weighted residuals +to create 0, 1, 3, or 6, depending on the \fIvarorder\fR parameter, +psf model look-up tables +.IP [7] +repeats steps [5] and [6] \fInclean\fR times, down-weighting the contributions +to the psf model look-up table(s) of pixels with particularly large +residuals each time through the loop +.IP [8] +estimates magnitudes for the saturated psf stars (if any exist and +if the parameter \fIsaturated\fR is "yes"), +by fitting the current psf model to the wings of the saturated stars +using the \fBpeak\fR task fitting algorithm, +.IP [9] +computes the residuals of each saturated psf star (if any exist and they +were successfully fit) from the best fit +analytic function within a radius of \fIpsfrad\fR + 2 pixels, weights +the residuals by a factor of 0.5, and adds +the contribution of the scaled, subsampled, and weighted residuals +to the psf model look-up table(s) +.IP [10] +writes the computed analytic function parameters and +look-up tables to the output psf image +.IP [11] +identifies all stars within (psfrad + 2 * fitrad + 1) pixels of +a psf star as psf star neighbors, and stars within (2 * fitrad) pixels of +the psf star neighbors as friends of the neighbors +.IP [12] +writes the ids, x and y coordinates, magnitudes, and sky values of +the final list of psf stars to the output psf star list, and the group +and star ids, +x and y coordinates, magnitudes, and sky values of the psf stars, +psf star neighbors, and friends of the psf star neighbors +to the output psf star group file + +.NH 3 +Choosing the Appropriate Analytic Function + +.PP +DAOPHOT offers several choices for the functional form of the analytic +component of the psf model (see Appendix 8.2 for details). +To achieve the best fits and to minimize interpolation errors in +the psf model look-up tables, +users should choose the analytic function that most closely +approximates the stellar psf. The options are: +.IP [1] +\fBgauss\fR (2 parameters), +a 2D elliptical gaussian function aligned along the x and y axes of the image. +Gauss is generally the best choice for well-sampled, fwhmpsf >= 2.5 pixels, +ground-based images because the interpolation errors are small +and evaluation is efficient as the function is separable in x and y. +.IP [2] +\fBmoffat25\fR and \fBmoffat15\fR (3 parameters), +elliptical Moffat functions of beta 2.5 and 1.5 respectively which can +be aligned along an arbitrary position angle. The Moffat functions +are good choices for under-sampled ground-based data. +.IP [3] +\fBlorentz\fR (3 parameters), +an elliptical Lorentz function which can be aligned along an arbitrary position +angle. The Lorenz function is a good choice for old ST data since it has +extended wings. +.IP [4] +\fBpenny1\fR (4 parameters), +a two component model consisting of an elliptical gaussian core +which can be aligned along an arbitrary position angle and +lorentzian wings aligned along the x and y axes of the image. +The Penny1 function is a good choice for a purely analytic psf model. +.IP [5] +\fBpenny2\fR (5 parameters), +a two component model consisting of an elliptical gaussian core +aligned along an arbitrary position angle and lorentzian wings aligned +along an arbitrary position angle which may be different from that of the +core. The Penny2 function is a good choice for a purely analytic psf model. +.IP [6] +\fBauto\fR (2, 3, 4 or 5 parameters), +try each of the 6 analytic psf functions in turn and select the one which +yields the smallest scatter in the fit. Users should use +this option with caution +since the greater number of free parameters in some models may +artificially produce a fit with less scatter without significantly +improving the resulting photometry. +.IP [7] +\fBlist\fR (2, 3, 4 or 5 parameters), +check only those functions in a user specified list, e.g. +"gauss,moffat25,lorentz" and select the one that gives the smallest +scatter. +.PP +Users uncertain of which analytic function to choose should leave +\fIfunction\fR set to "gauss" +and only if the results prove unsatisfactory experiment with one of the +more complicated analytic functions. + +.NH 3 +The Analytic Psf Model + +.PP +A purely analytic psf model may be computed +by setting the \fBdaopars\fR parameter \fIvarorder\fR = -1. +Analytic psf models are +constant, i.e. they have the same shape everywhere in the +image. +In the majority +of cases this is NOT the best modeling option, +as a better representation of the true psf is almost always obtained by +computing an empirical psf model composed of an +analytic function plus one look-up table. +.PP +An analytic psf model may be required to model severely undersampled +data because interpolation errors can produce large uncertainties +in the computed look-up tables and the resulting fits. +.PP +Fields which are so crowded that +isolated psf stars are non-existent, may also require psf modeling and +psf star neighbor subtraction with an analytic psf model, +before a more accurate higher order model free of ghosts produced +by the psf star neighbors can be computed. +This step is particularly important if the field is very crowded AND the +psf is known to be variable. + +.NH 3 +The Empirical Constant Psf Model + +.PP +Most users with typical ground-based optical +data choose to compute an empirical constant psf +model composed of an analytic component and a single look-up table, +by setting the \fBdaopars\fR parameter \fIvarorder\fR = 0. +This type of model is constant, i.e. the psf model has +the same shape everywhere in the image. +.PP +Because of interpolation errors, severely undersampled data may be better +fit with a purely analytic psf model as described in the previous section. +.PP +Fields which are so crowded that +isolated psf stars are non-existent may require psf modeling and +psf neighbor star subtraction with an analytic psf model, +before an accurate look-up table free of ghosts caused by the bright +psf star neighbors can be computed. + +.NH 3 +The Empirical Variable Psf Model + +.PP +Psf models which vary linearly or quadratically +with position in the image can be computed by setting +the \fIvarorder\fR parameter to 1 or 2 respectively. +In the first case a total of 3 look-up tables will be computed; +in the second case 6 look-up tables will be computed. +Users should always begin their analysis with \fIvarorder\fR = -1 or +0 if their data is from a telescope/instrument combination that +is unfamiliar to them. Only if the patterns of the residuals around stars +fit and subtracted with a constant psf model show systematic variations +with position +in the image, should the user proceed to experiment with the variable +psf models. +.PP +In very crowded regions it may be necessary to compute a good +variable psf model iteratively, starting with \fIvarorder\fR = -1 +and proceeding to \fIvarorder\fR = 2 by, computing the psf model, +fitting the psf model to the psf stars and their neighbors, subtracting +the psf star neighbors but not the psf stars from the original image, +increasing \fIvarorder\fR by 1, and recomputing the +psf model using the subtracted image, until all the psf stars and their +neighbors subtract out cleanly. + +.NH 3 +Rejecting Bad Data from the Psf Model + +.PP +The \fBpsf\fR task uses the \fBdatapars\fR parameters \fIdatamin\fR +and \fIdatamax\fR to flag bad data. +If the \fBdaopars\fR parameter \fIsaturated\fR is "no", a prospective +psf star +will be rejected outright if it has high or low bad data inside the fitting +radius; if \fIsaturated\fR is "yes" a star with low bad data will +be rejected outright but one with high bad data will be flagged +as saturated and accepted. Except in rare cases (see below) users should leave +\fIsaturated\fR set to "no". Stars with bad data outside the fitting radius +but inside the psf radius are flagged, and the user warned, but are still +accepted as psf stars. +.PP +All data within one fitting radius of the unsaturated psf stars is weighted by +the signal-to-noise ratio of the psf star and used to compute the +analytic component of the psf model. +Pixels which deviate strongly from the current best fit +analytic function are down-weighted during the course of the fit. +.PP +After the analytic function is fit, the residuals of the psf star data +from the best fit analytic function are computed, scaled to the magnitude +of the first psf star, weighted by the signal-to-noise in the psf star, +subsampled for a factor +of 2 in x and y, and added into the look-up table(s). +If there are too few psf stars with +good data to compute a particular element of the look-up table(s), +\fBpsf\fR will quit with an error. If the \fBdaopars\fR parameter +\fInclean\fR > 0, deviant pixels contributing to the psf model look-up tables +are down-weighted and the look-up table(s) are recomputed \fInclean\fR +times. +.PP +For images where all the bright candidate psf stars are saturated and all the +remaining +candidate psf stars are faint, it may be necessary to use the faint stars to +compute the analytic component of the psf model and bright saturated stars +to compute the look-up tables(s). +In this circumstance the user must set the parameter \fIsaturated\fR +to "yes" and include several saturated stars in the psf star list. +After the analytic function and an initial set of look-up tables(s) +is computed without using the saturated psf stars, the \fBpeak\fR task +fitting algorithm is used to compute accurate magnitudes for the +saturated psf stars by fitting the wings of the saturated stars to +the current psf model. New look-up table(s) are computed +which include the contributions weighted by 0.5 of the saturated psf stars. + +.NH 3 +The Model Psf Psfrad and Fitrad + +.PP +The \fBdaopars\fR parameter \fIpsfrad\fR defines the region over which +the psf model is defined. This radius should equal the radius at which the +radial profile of the brightest star of interest disappears into the noise, +e.g. \(~= 5 pixels for the test image as determined +in the section describing the +\fBpstselect\fR task. The fitting radius defines the region of data around +each psf star used to compute the analytic component of the psf model +and should be the larger of the numbers 3 and 1 * \fIfwhmpsf\fR pixels. + +.NH 3 +Modeling the Psf Interactively Without a Psf Star List + +.PP +The psf can be modeled interactively without an initial list of candidate +psf stars by displaying the image and selecting candidate psf stars +with the image +cursor. Good candidate psf stars must be in the input photometry file, +have no neighbors within \fIfitrad\fR +pixels, and be free of cosmetic blemishes. +.PP +The following example shows how to model the psf interactively without +using an initial psf star list. + +.YS +da> display test 1 fi+ + +da> psf test default "" default default default + +Analytic psf function(s) (gauss): + Analytic psf function(s): gauss +Order of variable psf (0): + Order of variable psf: 0 +Psf radius in scale units (5.): + New psf radius: 5. scale units 5. pixels +Fitting radius in scale units (3.): + New fitting radius: 3. scale units 3. pixels +Minimum good data value (50.) (CR or value): + New minimum good data value: 50. counts +Maximum good data value (24500.) (CR or value): + New maximum good data value: 24500. counts + +Warning: Graphics overlay not available for display device. + +Computing PSF for image: test +9 stars read from test.mag.1 +.YE + +.IP ... +A message appears on the screen telling the user how +many stars have been read from the photometry file +(users should make sure that this is the entire star list) +and the image cursor begins blinking. +.IP ... +The user types the \fBa\fR keystroke at pixel 36,42 +followed by another \fBa\fR keystroke after the default +plot appears, +to add star 9 psf star list. Star 6 at pixel 8,23 is added +to the psf star list in the identical manner. +.LP + +.YS +Star 9 has been added to the PSF star list + X: 35.98 Y: 42.03 Mag: 16.594 Dmin: 80.25255 Dmax: 489.9732 +Star 6 has been added to the PSF star list + X: 8.02 Y: 22.97 Mag: 16.603 Dmin: 71.00896 Dmax: 436.3393 +.YE + +.IP ... +The user types the \fBl\fR keystroke command to list the selected psf stars. +.LP + +.YS +Current PSF star list + Star: 9 X: 35.98 Y: 42.03 Mag: 16.59 Sky: 101.0 + Star: 6 X: 8.02 Y: 22.97 Mag: 16.60 Sky: 98.9 +.YE +.LP + +.IP ... +The user types the \fBf\fR keystroke command to compute the psf model. +.LP + +.YS +Fitting function gauss norm scatter: 0.03422394 + +Analytic PSF fit + Function: gauss X: 25. Y: 25. Height: 523.8066 Psfmag: 16.594 + Par1: 1.082032 Par2: 1.162063 + +Computed 1 lookup table(s) +.YE + +.IP ... +The user reviews the model fit with the \fBr\fR keystroke command and +decides to keep both psf stars. +.LP + +.YS +PSF star 9 saved by user +PSF star 6 saved by user +.YE + +.IP ... +The user types the \fBf\fR keystroke command to remodel the psf. +.LP + +.YS +Fitting function gauss norm scatter: 0.03422394 + +Analytic PSF fit + Function: gauss X: 25. Y: 25. Height: 523.8066 Psfmag: 16.594 + Par1: 1.082032 Par2: 1.162063 + +Computed 1 lookup table(s) +.YE + +.IP ... +The user types the \fBw\fR keystroke command to save the psf model +followed by the \fBq\fR keystroke command, executed twice, to quit the task. +.LP + +.YS +Writing PSF image test.psf.1.imh +Writing output PSF star list test.pst.1 +Writing output PSF star group file test.psg.1 +.YE + +.PP +At this point the user has created an initial psf model in the image +test.psf.1, a list of the psf stars in test.pst.1, and a list of the +psf stars and their neighbors in the file +test.psg.1 respectively. +.PP +Users may occasionally see "Star not found" messages when +selecting psf stars with the image cursor. This may mean: 1) that the star +is truly not in the input photometry file (this can be checked +with the \fBtvmark\fR task), 2) that the image cursor +is more than \fImatchrad\fR pixels from the position of the star +in the input photometry file (either position the image cursor more +carefully by hand or increase the value of the \fImatchrad\fR parameter), or, +3) that the input photometry file contains +more than \fImaxnstar\fR stars (increase the value of the parameter +\fImaxnstar\fR so that it is greater than the number of stars in +the photometry file). + +.NH 3 +Fitting the Psf Model Interactively Using an Initial Psf Star List + +.PP +The \fBpsf\fR task can also be run interactively using an initial list of +psf stars chosen by the user with the \fBpstselect\fR task. +If the \fBpsf\fR task parameter \fIshowpsf\fR is "yes" (the default), +the psf stars are read from the psf star list one at a time, +a mesh, contour, or radial profile plot is displayed in the graphics window, +and the user can accept or delete the star with the \fBa\fR or \fBd\fR +keystroke commands. If +\fIshowplots\fR is "no", the psf star list is read without intervention +by the user. In both cases new stars can be added to the end of the psf +star list with the image cursor in the usual manner. +.PP +A sample run is shown below. + +.YS +da> display test 1 fi+ + +da> pdump test.pst.1 xcenter,ycenter,id yes | tvmark 1 STDIN \\ + col=205 label+ +.YE + +.IP ... +The user marks and labels the initial list of psf stars on the image display. +.LP + +.YS +da> psf test default test.pst.1 default default default + +Analytic psf function(s) (gauss): + Analytic psf function(s): gauss +Order of variable psf (0): + Order of variable psf: 0 +Psf radius in scale units (5.): + New psf radius: 5. scale units 5. pixels +Fitting radius in scale units (3.): + New fitting radius: 3. scale units 3. pixels +Minimum good data value (50.) (CR or value): + New minimum good data value: 50. counts +Maximum good data value (24500.) (CR or value): + New maximum good data value: 24500. counts + +Warning: Graphics overlay not available for display device. + +Computing PSF for image: test +9 stars read from test.mag.1 +.YE + +.IP ... +The user rejects or accepts the stars in the .pst file by typing the +\fBd\fR or \fBa\fR keystroke commands respectively after the +default plot appears. +.LP + +.YS +Star 5 rejected by user +Star 9 has been added to the PSF star list + X: 35.98 Y: 42.03 Mag: 16.594 Dmin: 80.25255 Dmax: 489.9732 +Star 6 has been added to the PSF star list + X: 8.02 Y: 22.97 Mag: 16.603 Dmin: 71.00896 Dmax: 436.3393 + +2 PSF stars read from test.pst.1 +.YE + +.IP ... +The user types the \fBl\fR keystroke command to view the psf star +list one more time. +.LP + +.YS +Current PSF star list + Star: 9 X: 35.98 Y: 42.03 Mag: 16.59 Sky: 101.0 + Star: 6 X: 8.02 Y: 22.97 Mag: 16.60 Sky: 98.9 +.YE + +.IP ... +The user computes the psf model with the \fBf\fR keystroke command. +.LP + +.YS +Fitting function gauss norm scatter: 0.03422394 + +Analytic PSF fit + Function: gauss X: 25. Y: 25. Height: 523.8066 Psfmag: 16.594 + Par1: 1.082032 Par2: 1.162063 + +Computed 1 lookup table(s) +.YE + +.IP ... +The user saves the psf model with the \fBw\fR keystroke command. +.LP + +.YS +Writing PSF image test.psf.1.imh +Writing output PSF star list test.pst.2 +Writing output PSF star group file test.psg.1 +.YE + +.IP ... +The user types the \fBq\fR keystroke command to quit the task. +.LP + +The user notes that the output psf star list is given a version number +of 2 in this example, since version 1 was written by the \fBpstselect\fR task. + +.NH 3 +Fitting the Psf Model Interactively Without an Image Display + +.PP +Users without access to an image display, may still run \fBpsf\fR +interactively by redirecting +the image cursor commands to the terminal as shown below. + +.YS +da> set stdimcur = text + +da> psf test default test.pst.1 default default default + +Analytic psf function(s) (gauss): + Analytic psf function(s): gauss +Order of variable psf (0): + Order of variable psf: 0 +Psf radius in scale units (5.): + New psf radius: 5. scale units 5. pixels +Fitting radius in scale units (3.): + New fitting radius: 3. scale units 3. pixels +Minimum good data value (50.) (CR or value): + New minimum good data value: 50. counts +Maximum good data value (24500.) (CR or value): + New maximum good data value: 24500. counts + +Warning: Graphics overlay not available for display device. + +Computing PSF for image: test +9 stars read from test.mag.1 +.YE + +.IP ... +The user rejects or accepts the stars in the .pst file by typing +the \fBd\fR or \fBa\fR keystroke commands respectively at the prompt. +.LP + +.YS +Star 5 rejected by user +Star 9 has been added to the PSF star list + X: 35.98 Y: 42.03 Mag: 16.594 Dmin: 80.25255 Dmax: 489.9732 +Star 6 has been added to the PSF star list + X: 8.02 Y: 22.97 Mag: 16.603 Dmin: 71.00896 Dmax: 436.3393 + +2 PSF stars read from test.pst.1 +.YE + +.IP ... +The user types the \fBl\fR keystroke command at the prompt to +view the psf star list one more time. +.LP + +.YS +Current PSF star list + Star: 9 X: 35.98 Y: 42.03 Mag: 16.59 Sky: 101.0 + Star: 6 X: 8.02 Y: 22.97 Mag: 16.60 Sky: 98.9 +.YE + +.IP ... +The user computes the psf model by typing the \fBf\fR keystroke +command at the prompt. +.LP + +.YS +Fitting function gauss norm scatter: 0.03422394 + +Analytic PSF fit + Function: gauss X: 25. Y: 25. Height: 523.8066 Psfmag: 16.594 + Par1: 1.082032 Par2: 1.162063 + +Computed 1 lookup table(s) +.YE + +.IP ... +The user saves the psf model by typing the \fBw\fR keystroke command +at the prompt. +.LP + +.YS +Writing PSF image test.psf.1.imh +Writing PSF output star list test.pst.2 +Writing PSF output star group file test.psg.1 +.YE + +.IP ... +The user types the \fBq\fR keystroke command at the prompt to quit the task. +.LP + +Additional stars can be added to the psf star list by commands of +the form \fB":a id#"\fR or \fB"100.2 305.6 1 a"\fR typed in at the +terminal prompt. +The user should remember to reset the image cursor to the logical +image cursor with the command \fB"reset stdimcur = stdimage"\fR +after running the \fBpsf\fR task in "no image display" mode. + +.NH 3 +Fitting the Psf Model Non-interactively + +.PP +Finally the psf model can be fit non-interactively by setting the +\fIinteractive\fR parameter to "no", and using the list of psf stars produced by +the \fBpstselect\fR task as input. This is the preferred method for computing +the psf model when the number of psf stars is large (e.g. the psf +model to be computed is variable). + +.YS +da> psf test default test.pst.1 default default default inter- +.YE + +.NH 3 +The Output of Psf + +.PP +\fBPsf\fR writes an output psf star list test.pst.# containing the ids, x and +y coordinates, magnitudes, and sky values, copied from the +input photometry file, +of the psf stars actually used to compute the final psf model. +Because of the ability +to add and subtract stars within \fBpsf\fR itself, this list may be different +from the input psf star list if any. A sample output psf star list is +shown below. + +.YS +#K IRAF = NOAO/IRAFV2.10EXPORT version %-23s +#K USER = davis name %-23s +#K HOST = tucana computer %-23s +#K DATE = 05-28-93 mm-dd-yr %-23s +#K TIME = 14:34:31 hh:mm:ss %-23s +#K PACKAGE = daophot name %-23s +#K TASK = psf name %-23s +#K IMAGE = test imagename %-23s +#K PHOTFILE = test.mag.1 filename %-23s +#K PSTFILE = test.pst.1 filename %-23s +#K PSFIMAGE = test.psf.1 imagename %-23s +#K GRPSFILE = test.psg.1 filename %-23s +#K OPSTFILE = test.pst.2 filename %-23s +#K SCALE = 1. units/pix %-23.7g +#K OTIME = 00:07:59.0 timeunit %-23s +#K IFILTER = V filter %-23s +#K XAIRMASS = 1.238106 number %-23.7g +#K PSFRAD = 5. scaleunit %-23.7g +#K FITRAD = 3. scaleunit %-23.7g +# +#N ID XCENTER YCENTER MAG MSKY \\ +#U ## pixels pixels magnitudes counts \\ +#F %-9d %-10.3f %-10.3f %-12.3f %-12.3f +# +9 35.980 42.029 16.594 101.043 +6 8.022 22.970 16.603 98.891 +.YE + +.PP +\fBPsf\fR also writes an output psf star group photometry file +test.psg.? containing the group ids, and the star ids, +x and y coordinates, magnitudes, and sky values +copied from the input photometry file, +for the psf stars and their +neighbors. A sample psf star group file is shown below. + +.YS +#K IRAF = NOAO/IRAFV2.10EXPORT version %-23s +#K USER = davis name %-23s +#K HOST = tucana computer %-23s +#K DATE = 05-26-93 mm-dd-yr %-23s +#K TIME = 16:10:48 hh:mm:ss %-23s +#K PACKAGE = daophot name %-23s +#K TASK = psf name %-23s +#K IMAGE = test imagename %-23s +#K PHOTFILE = test.mag.2 filename %-23s +#K PSTFILE = test.pst.2 filename %-23s +#K PSFIMAGE = test.psf.2 imagename %-23s +#K GRPSFILE = test.psg.2 filename %-23s +#K SCALE = 1. units/pix %-23.7g +#K OTIME = 00:07:59.0 timeunit %-23s +#K IFILTER = V filter %-23s +#K XAIRMASS = 1.238106 number %-23.7g +#K PSFRAD = 5. scaleunit %-23.7g +#K FITRAD = 3. scaleunit %-23.7g +# +#N ID GROUP XCENTER YCENTER MAG MSKY \\ +#U ## ## pixels pixels magnitudes counts \\ +#F %-9d %-6d %-10.3f %-10.3f %-12.3f %-14.3f +# +9 1 35.980 42.029 16.594 101.043 +8 1 28.958 33.924 17.781 100.619 +6 2 8.022 22.970 16.603 98.891 +.YE + +There are two stellar groups, one group per psf star, +in this file. The first psf star +has a single neighbor so there are two stars in the first group. +The first star in a group is always the psf star. The header parameters +record the input and output image and file names, the name of the +computed psf model, and the values +of the parameters +\fIpsfrad\fR and \fIfitrad\fR used to define the psf star groups. +.PP +The psf image contains, in the image header, the values of the +parameters that were used +to compute the psf model, the best fit values of the parameters of +the chosen analytic function, and a record of all the +psf stars used to compute the psf, and in the image pixels, the best fit +look-up table(s) of the residuals from the analytic function +subsampled by a factor of 2. +The psf image look-up table(s) can be plotted and examined just like any +other IRAF image. +.PP +A sample psf image header is shown below. + +.YS +test.psf.2[23,23][real]: PSF for image: test + No bad pixels, no histogram, min=unknown, max=unknown + Line storage mode, physdim [23,23], length of user area 1540 s.u. + Created Wed 16:10:47 26-May-93, Last modified Wed 16:10:47 26-May-93 + Pixel file 'tucana!/d0/iraf/davis/test.psf.2.pix' [ok] + IRAF = 'NOAO/IRAFV2.10EXPORT' + HOST = 'tucana ' + USER = 'davis ' + DATE = '05-26-93' + TIME = '16:10:48' + PACKAGE = 'daophot ' + TASK = 'psf ' + IMAGE = 'test ' + PHOTFILE= 'test.mag.2' + PSTFILE = 'test.pst.2' + PSFIMAGE= 'test.psf.2' + GRPSFILE= 'test.psg.2' + SCALE = 1. + PSFRAD = 5. + FITRAD = 3. + DATAMIN = 50. + DATAMAX = 24500. + NCLEAN = 0 + USESAT = F + FUNCTION= 'gauss ' + PSFX = 25. + PSFY = 25. + PSFHEIGH= 523.8066 + PSFMAG = 16.594 + NPARS = 2 + PAR1 = 1.082032 + PAR2 = 1.162063 + VARORDER= 0 + FEXPAND = F + NPSFSTAR= 2 + ID1 = 9 + X1 = 35.98 + Y1 = 42.029 + MAG1 = 16.594 + ID2 = 6 + X2 = 8.022 + Y2 = 22.97 + MAG2 = 16.603 +.YE + +This psf image header records that: the psf model +was computed with a gaussian +analytic function (function = gauss), the analytic +function has two parameters (npars=2) +whose values are 1.08 and 1.16 (par1 and par2 are the fwhm of the function +in x and y respectively in this case), the psf is constant but there is +1 look-up +table (varorder = 0), no saturated stars were used to compute the psf +(usesat=no), and no cleaning of bad pixels was done to compute the +lookup table (nclean=0). The number of psf stars and their positions +and magnitudes +are also listed. The psf model is defined over a radius of 5 +pixels (psfrad = 5.0), resulting in a square look-up table with dimensions +of 2 * (nint (2 * psfrad) + 1) + 1 pixels in x and y, and a fitting radius +of 3 (fitrad = 3.0) was used to compute the analytic portion of the psf +model. +.PP +The height of the best fit gaussian psfheigh is 523.81 counts. +The psf model has been assigned a magnitude of 16.594 which is the +magnitude of the first psf star in the input photometry file. +All fits to the psf model are scaled with respect to this +magnitude. Therefore a star which is twice as bright as the psf model will +have a fitted magnitude of ~15.841. +.PP +Psfx and psfy define the distance from the center of the input image to the +center of the edge pixels in x and y respectively, e.g psfx = +(ncols - 1.0) / 2.0 and psfy = (nlines - 1) / 2.0. These numbers are used to +evaluate the psf model only if the model is variable, \fIvarorder\fR > 0. +.PP +If the value of \fIvarorder\fR in this example had been 1 or 2 the +psf model image would have been 3-dimensional with 3 and 6 23 by 23 +pixel look-up +tables in planes 1-3 and 1-6 of the image respectively. +In both cases planes 1-3 would contain the 0th, 1st order in x, +and 1st order in y Taylor expansion coefficients around the analytic function. +In the latter case planes 4-6 would contain the +2nd order in x, 2nd order in xy, and 2nd order in y Taylor expansion +coefficients. If the value of \fIvarorder\fR +had been -1 no look-up tables would have been computed and the +psf model image would consist of an image header but no pixel file. + +.NH 3 +Checking the Psf Model + +.PP +To check the accuracy of the psf model, the user must fit each psf +star and its neighbors and friends +as a group using the \fBnstar\fR task, and the psf model and psf star group +photometry file +produced by \fBpsf\fR as shown below. In the following example +the user has chosen to set the rejections +file to "", so that all stars, even those too faint to be properly +fit, will be placed in the same output file. + +.YS +da> nstar test test.psg.1 default default "" + +Recenter the stars (yes): + Recenter the stars: yes +Refit the sky (no): + Refit the sky: no +Psf radius in scale units (5.): + New psf radius: 5. scale units 5. pixels +Fitting radius in scale units (3.): + New fitting radius: 3. scale units 3. pixels +Maximum group size in number of stars (60): + New maximum group size: 60 stars +Minimum good data value (50.) (CR or value): + New minimum good data value: 50. counts +Maximum good data value (24500.) (CR or value): + New maximum good data value: 24500. counts + +Group: 1 contains 2 stars + ID: 9 XCEN: 35.98 YCEN: 42.01 MAG: 16.60 + ID: 8 XCEN: 28.96 YCEN: 33.91 MAG: 17.73 +Group: 2 contains 1 stars + ID: 6 XCEN: 8.02 YCEN: 22.97 MAG: 16.63 +.YE + +The results of the fits will appear in test.nst.? as shown below. + +.YS +da> page test.nst.1 + +#K IRAF = NOAO/IRAFV2.10EXPORT version %-23s +#K USER = davis name %-23s +#K HOST = tucana computer %-23s +#K DATE = 05-28-93 mm-dd-yy %-23s +#K TIME = 14:46:13 hh:mm:ss %-23s +#K PACKAGE = daophot name %-23s +#K TASK = nstar name %-23s +#K IMAGE = test imagename %-23s +#K GRPFILE = test.psg.1 filename %-23s +#K PSFIMAGE = test.psf.1 imagename %-23s +#K NSTARFILE = test.nst.1 filename %-23s +#K REJFILE = "" filename %-23s +#K SCALE = 1. units/pix %-23.7g +#K DATAMIN = 50. counts %-23.7g +#K DATAMAX = 24500. counts %-23.7g +#K GAIN = 1. number %-23.7g +#K READNOISE = 0. electrons %-23.7g +#K OTIME = 00:07:59.0 timeunit %-23s +#K XAIRMASS = 1.238106 number %-23.7g +#K IFILTER = V filter %-23s +#K RECENTER = yes switch %-23b +#K FITSKY = no switch %-23b +#K PSFMAG = 16.594 magnitude %-23.7g +#K PSFRAD = 5. scaleunit %-23.7g +#K FITRAD = 3. scaleunit %-23.7g +#K MAXITER = 50 number %-23d +#K MAXGROUP = 60 number %-23d +#K FLATERROR = 0.75 percentage %-23.7g +#K PROFERROR = 5. percentage %-23.7g +#K CLIPEXP = 6 number %-23d +#K CLIPRANGE = 2.5 sigma %-23.7g +# +#N ID GROUP XCENTER YCENTER MAG MERR MSKY \\ +#U ## ## pixels pixels magnitudes magnitudes counts \\ +#F %-9d %-6d %-10.3f %-10.3f %-12.3f %-14.3f %-12.3f +# +#N NITER SHARPNESS CHI PIER PERROR \\ +#U ## ## ## ## perrors \\ +#F %-17d %-12.3f %-12.3f %-6d %-13s +# +9 1 35.982 42.006 16.601 0.019 101.043 \\ + 4 -0.019 0.512 0 No_error +8 1 28.962 33.912 17.730 0.074 100.619 \\ + 4 0.026 1.093 0 No_error +6 2 8.017 22.968 16.628 0.021 98.891 \\ + 3 0.022 0.558 0 No_error +.YE + +In this example the chi values computed by \fBnstar\fR for the two +psf stars are lower than expected, ~ 0.5 instead of ~ 1.0, meaning that the +observed errors are less than the predicted errors. +This occurs because there are only 2 psf stars, +and therefore the model psf and the fitted psf stars are not totally +independent. +For example, if only one psf star is used to compute +the psf model, the chi +computed by \fBnstar\fR for that star would be ~ 0.0 and for any others +such as its neighbors ~ 1.0. +.PP +After checking that the chi values look reasonable, the user subtracts the +fitted psf stars and their neighbors from the input image +with the \fBsubstar\fR task, and examines the residuals +of the fit around the psf stars as shown below. After \fBsubstar\fR is +run the subtracted +image is displayed and the psf stars are marked in green and the +psf neighbor stars are marked in red. + +.YS +da> substar test default "" default default + +Psf radius in scale units (5.): + New psf radius: 5. scale units 5. pixels +Minimum good data value (50.) (CR or value): + New minimum good data value: 50. counts +Maximum good data value (24500.) (CR or value): + New maximum good data value: 24500. counts + +SUBTRACTING - Star: 6 X = 8.02 Y = 22.97 Mag = 16.63 +SUBTRACTING - Star: 8 X = 28.96 Y = 33.91 Mag = 17.73 +SUBTRACTING - Star: 9 X = 35.98 Y = 42.01 Mag = 16.60 + +A total of 3 stars were subtracted out of a possible 3 + +da> display test.sub.1 1 fi+ +da> pdump test.nst.1 xc,yc,id yes | tvmark 1 STDIN col=204 label+ +da> pdump test.pst.1 xc,yc,id yes | tvmark 1 STDIN col=205 label+ +.YE + +.PP +The psf stars and their neighbors should subtract out cleanly +with no systematic patterns in the residuals as a function of distance +from the star (note this may not be the case if the psf is purely analytic +or so severely undersampled that the interpolation errors near the +center are very large), with magnitude, or with position in the image. +There should be no hidden +underlying neighbors revealed after the subtraction (these psf stars +should be rejected) or neighbors +that are not in the photometry file (this can be fixed up later). +The amplitudes of the fit residuals +should be consistent with the noise if sufficient stars are +used to determine the psf model. +.PP +The displayed and marked subtracted image and the output of \fBnstar\fR can +be examined in more detail with the \fBpexamine\fR task as shown below. + +.YS +da> pexamine test.nst.1 "" test.sub.1 +.YE +.IP ... +A plot of magnitude versus magnitude error for the psf stars and their +neighbors will appear. +.IP ... +Change the default plot to mag versus chi with the command \fB:ycolumn chi\fR +followed by the \fBp\fR keystroke command. +.IP ... +Activate the image cursor with the \fBi\fR keystroke command. +.IP ... +Move to psf star number 9 and type \fBr\fR to examine the radial profile +of the subtracted star, followed by \fBo\fR to get a listing of its position, +magnitude, magnitude error, sky value, etc. +.IP ... +Examine the radial profiles of the other subtracted psf stars and their +neighbors. +.IP ... +Type \fBq\fR to quit the task. + +.PP +For the test image "test", examination of the radial profiles of the +subtracted stars shows that the residuals are +consistent with the noise in the image and have no unusual features +leading to the conclusion that the current psf model is a good representation +of the true psf. + +.NH 3 +Removing Bad Stars from the Psf Model + +.PP +Bad psf stars detected after the psf star and neighbor subtraction, +for example those with +a cosmetic blemish, a close double, or an underlying neighbor star, +should be removed altogether from +the psf star list. This can be done by editing the psf star list written +by \fBpsf\fR with the text editor, with the \fBpselect\fR task and an +expression, e.g. "id != 5", specifying the star to be deleted, or +with the interactive \fBpexamine\fR task using the delete and update keys, +and rerunning \fBpsf\fR with the new psf star list. +.PP +This step is not required for the test image as both psf stars and their +neighbors subtracted cleanly from the image. + +.NH 3 +Adding New Stars to a Psf Star Group + +.PP +Occasionally stars that are too faint to be included +in initial star list produced by \fBdaofind\fR and measured with \fBphot\fR, are +nevertheless sufficiently bright and close to a psf star +to affect the computation of the psf model. +Ideally the psf stars should have no such companions and/or the look-up +table cleaning option in the \fBpsf\fR task should minimize the problem of +undetected neighbors. However in some cases it is necessary for +the user to intervene and add faint stars to the photometry list. +.PP +The easiest way to accomplish this +is to run \fBphot\fR interactively, selecting the +missing neighbor stars with the image cursor and appending the results +for the new neighbor stars to the photometry file produced by the first +run of \fBnstar\fR. + +.YS +da> phot test "" psf.mag inter+ calgorithm=centroid +.YE + +.IP ... +Point cursor to undetected psf star neighbors and hit spacebar. +.IP ... +Type \fBq\fR to quit. +.LP + +.YS +da> prenumber psf.mag idoffset=5000 +.YE + +.IP ... +Renumber the stars in the new file starting with a number greater +than the number of stars in the original photometry file in order +to insure that all the stars have unique ids. +.LP + +.YS +da> pfmerge test.psg.1,psf.mag test.psf.psg +.YE + +.IP ... +Combine the psf star group photometry file produced by the \fBpsf\fR task +with the photometry file for the new psf star neighbors produced by +the \fBphot\fR task. +.LP + +Users should note that there is no input coordinate list to \fBphot\fR in +this case. Therefore the coordinate list is set to "", interactive mode +is on, and centering is turned on. +The remaining photometry parameters should be set exactly as they were in the +first run of \fBphot\fR. +.PP +This step is not required for the test image as all the significant +psf star neighbors were detected by the first run of the \fBdaofind\fR task. + +.NH 3 +Refitting the Psf Model With the New Psf Star Groups + +.PP +After the \fBpsf \fR and \fBphot\fR results have been merged, the +user must regroup the psf stars and their neighbors with +the \fBgroup\fR task, and refit the +new groups with the \fBnstar\fR task. + +.YS +da> group test test.psf.psg default test.grp critov=.2 +.YE + +.IP ... +Regroup the stars using a very small value for the critical overlap +parameter. +.LP + +.YS +da> nstar test test.grp default default "" +.YE + +.IP ... +Rerun nstar on the new psf star groups. +.LP + +.YS +da> substar test test.nst.2 "" default default +.YE + +.IP ... +Check that the new psf star groups subtract cleanly from the original +image. +.PP +This step is not required for the test image as all the significant +psf star neighbors were detected by the first run of the \fBdaofind\fR task. + + +.NH 3 +Computing the Final Psf Model + +.PP +Once the psf star and psf star neighbors subtract out cleanly +from the input image with the current psf model, +a final psf model should be computed using an image from which all +the psf star neighbors but not the psf stars have been subtracted. +To do this the user runs the \fBsubstar\fR task, setting the input photometry +file to the final output of \fBnstar\fR, and the exclude file to the final +psf star list written by the \fBpsf\fR task, and reruns \fBpsf\fR. +An example of this procedure is shown below. + +.YS +da> substar test test.nst.2 test.pst.2 default default +da> psf test.sub.3 test.grp test.pst.2 test.psf.2 test.pst.3 \\ + test.psg.3 inter- +.YE + +After this step the user should have a good psf model and can proceed to do +psf fitting photometry. +.PP +This step is not required for the test image as the single psf star +neighbor is sufficiently far from the psf star to have a negligible +effect on the computation of the psf model. + +.NH 3 +Visualizing the Psf Model with the Seepsf Task + +.PP +The psf analytic function parameters are stored in the psf image header +and the look-up table(s) in the psf image pixels. The look-up table(s) are +subsampled by a factor of 2 with respect to the image, and cannot +be used directly to visualize what the psf model looks like +at the scale of the image. The task \fBseepsf\fR can be used to +do this conversion as shown below. + +.YS +da> seepsf test.psf.3 psf3 +.YE + +The output image will contain a picture of what an ideal star of magnitude +equal to the magnitude of the psf (see the psfmag keyword in the psf +image header) should look like at the center of the image. +.PP +In the case of a variable psf the appearance of the psf model can be examined at +various +places in the image by specifying a position at which to compute the psf +model. + +.YS +da> seepsf test.psf.3 psf.13.8 xpsf=13 ypsf=8 +.YE + +.PP +The total power in a variable psf should be constant +as a function of position in the image even though its shape is +different. The variable psf fitting code +in DAOPHOT does perform flux conservation. Users can check this by using +the \fBimstatistics\fR task to check that there is no net power in the +look-up tables 2-3 or +2-6 if the psf order is 1 or 2. Similarly they can use \fBseepsf\fR to compute +the psf at various positions in the input image and \fBimstat\fR to check +that the net power in the psf is constant over the image +even though the shape of the +psf is variable. + +.NH 3 +Problems Computing the Psf Model + +.PP +Computing the psf model is the most crucial step in DAOPHOT. +The \fBdaofind\fR and \fBphot\fR +steps are usually straight-forward, and the principal fitting task +\fBallstar\fR runs entirely in batch once started. However computing +a good psf model requires user input. +.PP +This section suggests a few +things to check if the computed psf model is not doing a good +job of fitting and subtracting the psf or program stars. The user +should check: +.IP [1] +that the sky annulus chosen in the \fBphot\fR step is neither too +close or too far from the stars. If the sky annulus is too close +the computed skies will tend to be too high and the psf model +will have too small an amplitude, +producing false halos around the fitted and subtracted stars. If the sky annulus +is too far away the computed sky value will not represent the sky under the +psf star well, adding scatter to the photometry. +.IP [2] +the psf radius. +If the stars appear to be well fit in the cores but have residual halos with a +sharp inner edge around +them then the psf radius may be too small. The psf radius needs to +be big enough to give good subtractions for the brightest stars of interest. +.IP [3] +that the analytic component of the psf function is appropriate for +the data. +If the data is somewhat undersampled, fwhmpsf < 2.5 pixels, +one of the Moffat functions may give a better fit to the data than +the Gauss function. If that data is extremely undersampled an analytic +function may do better than one involving look-up tables. +.IP [4] +the psf stars. +One or more of the psf stars may not be stars, may be doubles, or contain +bad data. Although psf does try to detect and down-weight bad data it may +not be completely successful. Users need to examine the subtracted image +for objects with bad residuals and for stars with large fitted chi values +and eliminate them. +.IP [5] +for psf variability with position in the image. The true psf may be variable +and inadequately fit by a constant psf model. The user should examine the +residuals around the subtracted psf stars to see if there are patterns +with position in the image and +increase the order of the psf model if these are detected. +Large fitted chi values may also be an indication of a poor psf model. +.IP [6] +the distribution of the psf stars. +If the psf is variable the user must ensure that the psf stars adequately +cover the region of interest in the image. For example if there are no +psf stars in a certain portion of the image the psf may not +be well represented there. +.IP [7] +the data. If the psf is a higher order than quadratic \fBpsf\fR may +not be able to model it adequately. The user should check the image data +reduction history, and investigate any image combining, bad pixel and cosmic +ray removal +operations, etc., that may have fundamentally altered the data. +The data should also be checked for linearity. +.IP [8] +the noise model. If the chi values for the fitted psf stars are unusually +large or small, the effective readout noise and gain for the image +may not be correct. The user should check that these values are +being read from the image header correctly and that they are appropriate +for the data. + + +.NH 2 +Doing Psf Fitting Photometry with Peak, Nstar, or Allstar + +.PP +There are three psf fitting +photometry tasks in DAOPHOT. The \fBpeak\fR task fits the current psf +model to stars individually; the \fBnstar\fR task fits the psf model to +stars in fixed stellar groups simultaneously; the \fBallstar\fR task +groups and fits the psf model to stellar groups dynamically +and subtracts the fitted stars from the input image. +\fBAllstar\fR is the +task of choice for the majority of users, but all three options are +discussed in the following sections. + +.NH 3 +Fitting Single Stars with Peak + +.PP +\fBPeak\fR is the simplest psf fitting task. +\fBPeak\fR fits the psf model to the stars in the +input photometry list individually. Because \fBpeak\fR cannot fit stars in +groups as the \fBnstar\fR and \fBallstar\fR tasks do, and in +uncrowded frames aperture photometry is often simpler and just as accurate, +\fBpeak\fR has few unique functions. +However \fBpeak\fR can be useful in cases where the user wishes to: 1) improve +the signal to noise of faint stars by taking advantage of +\fBpeak's\fR optimal weighting scheme, 2) do astrometry of single +stars, 3) fit and remove single stars from the frame in order to +examine the underlying light distribution. + +.NH 4 +The Peak Algorithm + +.PP +By default the \fBpeak\fR task performs the following functions: +.IP [1] +reads the task parameters, including the name of +the input image, the input photometry file, the psf model, the +output photometry and rejections files, and the +\fBdatapars\fR and \fBdaopars\fR algorithm parameter sets +.IP [2] +reads the id, x and y coordinates, magnitude, and sky value +of a star from the input photometry file +.IP [3] +rejects the star if it has an undefined sky value, too +few good data pixels to obtain a fit, or is too faint +.IP [4] +extracts the image data within one fitting radius of each star and +performs an optimally weighted non-linear least-squares fit of the psf model +to the extracted data +.IP [5] +rejects the star if its signal-to-noise ratio is too low +or a unique solution cannot be found +.IP [6] +computes the best fit x, y, and magnitude for the star +.IP [7] +writes the id, new x and y coordinates, sky value, new magnitude, magnitude +error, number of iterations required to fit the star, chi statistic, +and sharpness +statistic for the fitted star to the +output photometry file, and the id, last computed x and y position, +and sky value of the rejected star, to +the rejections file +.IP [8] +repeats steps [2]-[7] for each star in the input photometry list + +.NH 4 +Running Peak + +.PP +A sample run of the \fBpeak\fR task is shown below. The user is prompted +for all the input and output file names and asked to verify the +critical parameters \fIrecenter\fR, \fIfitsky\fR, \fIpsfrad\fR, \fIfitrad\fR, +\fIdatamin\fR, and \fIdatamax\fR. + +.YS +da> peak test default default default default + +Recenter the stars (yes): + Recenter the stars: yes +Refit the sky (no): + Refit the sky: no +Psf radius in scale units (5.): + New psf radius: 5. scale units 5. pixels +Fitting radius in scale units (3.): + New fitting radius: 3. scale units 3. pixels +Minimum good data value (50.) (CR or value): + New minimum good data value: 50. counts +Maximum good data value (24500.) (CR or value): + New maximum good data value: 24500. counts + +Star: 1 X: 40.97 Y: 4.01 Mag: 17.22 Sky: 100.74 + FIT: Star: 1 X: 41.01 Y: 4.03 Mag: 17.22 Sky = 100.74 +Star: 2 X: 23.06 Y: 7.03 Mag: 17.65 Sky: 100.33 + FIT: Star: 2 X: 23.02 Y: 7.05 Mag: 17.75 Sky = 100.33 +Star: 3 X: 18.02 Y: 7.96 Mag: 17.48 Sky: 99.40 + FIT: Star: 3 X: 17.98 Y: 8.00 Mag: 17.57 Sky = 99.40 +Star: 4 X: 25.99 Y: 22.01 Mag: 16.80 Sky: 101.34 + FIT: Star: 4 X: 25.99 Y: 22.01 Mag: 16.81 Sky = 101.34 +Star: 5 X: 35.98 Y: 22.00 Mag: 16.37 Sky: 101.12 + FIT: Star: 5 X: 35.97 Y: 22.02 Mag: 16.39 Sky = 101.12 +Star: 6 X: 8.02 Y: 22.97 Mag: 16.60 Sky: 98.89 + FIT: Star: 6 X: 8.02 Y: 22.97 Mag: 16.63 Sky = 98.89 +Star: 7 X: 30.97 Y: 25.01 Mag: 17.05 Sky: 101.29 + FIT: Star: 7 X: 30.96 Y: 25.04 Mag: 17.05 Sky = 101.29 +Star: 8 X: 28.96 Y: 33.92 Mag: 17.78 Sky: 100.62 + FIT: Star: 8 X: 28.96 Y: 33.93 Mag: 17.74 Sky = 100.62 +Star: 9 X: 35.98 Y: 42.03 Mag: 16.59 Sky: 101.04 + FIT: Star: 9 X: 35.98 Y: 42.01 Mag: 16.60 Sky = 101.04\fR +.YE + +In this example the user chose to recenter the stars (almost always +the best choice), and not to refit the sky (usually the best choice). +Recentering should only be turned off if the initial centers in the input +photometry file are known to be very accurate, e.g. they +are derived from a better seeing +image or one that has gone through some image restoration program. +Users who elect to refit the sky, +should realize that they will almost certainly need to increase +the fitting radius to +obtain a reasonable fitted sky value. Increasing the fitting radius +however may also increase the scatter caused by neighboring stars. +.PP +The fitted stars can be subtracted from the input image with the \fBsubstar\fR +task as shown below. + +.YS +da> substar test test.pk.1 "" default default\fR +.YE + +.PP + +.NH 4 +The Peak Output + +.PP +Peak writes the quantities: id, xcenter, ycenter, mag, merr, msky, +niter, chi, sharp, pier, and perror to the output photometry file and the +rejections file. +.IP [1] +Id is the id number of the star as read from the input photometry file. +.IP [2] +Xcenter and ycenter are the best fit position of the star. +If the star was rejected xcenter and ycenter will be the computed +values of x and +y at the time it was rejected. If \fIrecenter\fR is "no", xcenter and ycenter +will be the position of the star in the input photometry file. +.IP [3] +Mag and merr are the best fit magnitude and magnitude error respectively. +The instrumental magnitude is computed relative to the +magnitude assigned to the +psf model. +Mag and merr are set to INDEF if the star cannot be fit to the psf model. +.IP [4] +Msky is the sky value in the input photometry file if fitsky = "no", +otherwise it is the +fitted sky value. If the star is not fit for some reason, +msky is the computed sky value +at the time the star was rejected. +.IP [5] +Niter is the number of iterations it took to fit the star. If this +number if equal to the \fBdaopars\fR parameter \fImaxiter\fR the user should be +suspicious of the computed positions, magnitudes, and sky values. +However as the convergence criteria are +conservative the star may still be reasonably well fit. +Niter is set to 0 if the star cannot be fit to the psf model. +.IP [6] +Chi and sharp are measures of the goodness of fit and the shape +of the star respectively. Chi should be ~ 1.0. If it is not then, +either the object is not a single star, the noise model including +one or more of the gain, readout noise, flat-fielding error, and +interpolation error parameters for the image are incorrect, the +psf model is a poor representation of the true psf, or the input +image does not conform to the requirements of the DAOPHOT package. +Sharp is a measure of the difference between the observed width +of the object and the width of the psf model. Stars should have a sharpness +value ~ 0.0, resolved objects a sharpness of > 0.0, and cosmic rays and similar +blemishes a sharpness of < 0. Chi and sharp are set to INDEF if the star +cannot be fit to the psf model. +.IP [7] +Pier and perror are an integer error code and error string respectively. +If no error was encountered during the fit pier is 0 and perror is +"No_error". Stars are rejected by the \fBpeak\fR task if 1) the sky value of +the star is INDEF 2) there are too few good data pixels to fit the star +3) the fitting matrix is singular meaning a unique solution could not +be found 4) the star is too faint, i.e. its signal / noise < 2.0. A fifth +condition, the solution did not converge by \fImaxiter\fR iterations, is not +used to reject the star, although users should be suspicious of a star +for which niter = \fImaxiter\fR. + + +.NH 3 +Fitting Stars with Group, Grpselect, Nstar and Substar + +.PP +Stars can be fit simultaneously in fixed groups using the +\fBnstar\fR task. +This psf fitting technique requires grouping the stars +into physically meaningful +associations with the \fBgroup\fR and/or the \fBgrpselect\fR tasks, +fitting the stars in each group simultaneously with the \fBnstar\fR task, +and subtracting +the fitted stars from the image with the \fBsubstar\fR task. +\fBNstar\fR is the task of choice when the user wishes to explicitly +control the grouping process or fit stars in a small number of +widely separated groups efficiently. +\fBNstar\fR is most commonly used to fit the psf model to the psf stars and +their neighbors. + +.NH 4 +The Group and Nstar Algorithms + +.PP +By default the \fBgroup\fR task performs the following steps: + +.IP [1] +reads the task parameters, including the name of the input image, the input +photometry file, the psf model, the output photometry +file, and the \fBdatapars\fR and \fBdaopars\fR +algorithm parameter sets +.IP [2] +reads the ids, x and y coordinates, magnitudes, and sky values +of up to \fImaxnstar\fR stars in the input photometry file, computes an +approximate magnitude for the stars with INDEF magnitudes, and sorts +the stars in increasing order of y +.IP [3] +finds all the stars which are within \fIpsfrad\fR + \fIfitrad\fR + 1 pixels +of a given star, evaluates the psf of the brighter star at a distance +of \fIfitrad\fR pixels from +the fainter, and if this value is larger than \fIcritovlap\fR +times the expected +error per pixel, or the two stars are within \fIfitrad\fR + 1 pixels of +each other, adds the star to the group +.IP [4] +writes the group and star ids, x and y coordinates, magnitudes and sky values +for all the groups, to the output group photometry file. + +.PP +By default the \fBnstar\fR task performs the following steps: + +.IP [1] +reads the task parameters including the name of +the input image, the input group file, the psf image, the +output group photometry and rejections files and the \fBdatapars\fR and +\fBdaopars\fR algorithm parameter sets +.IP [2] +reads the group and star ids, x and y coordinates, magnitudes, and +sky values for all the stars in a group from the input group photometry +file +.IP [3] +extracts the data within psfrad + fitrad pixels +around the group and +performs a weighted least-squares fit of the psf model to the extracted +data +.IP [4] +rejects stars which have an undefined sky value, which are too faint (more +than 12.5 magnitudes fainter than the psf), which are +too noisy (faintest star in the group less than a 1.0, 1.5, or 2.0 +sigma detection after 5, 10, and 15 iterations or convergence respectively), +for which there are too few good +pixels to compute a fit, for which a unique solution cannot +be found, which have merged with another star (fainter star < 0.37 * +fwhmpsf from a brighter star in the group), which are both too +noisy and too +close to a brighter star (a star is between .37 and 1.0 fwhm of +a brighter star and is a 1.0, 1.5, or 2.0 sigma detection before +iterations 5, 10, and 15 respectively), or which are in a group +too large (> than the value of the \fImaxgroup\fR parameter) to be reduced. +.IP [5] +estimates new x and y coordinates and magnitudes for each star in +the group +.IP [6] +iterates until all the stars in the group satisfy the convergence criteria +backing up the iteration counter by 1 each time a star is rejected from +the group to allow the remaining stars time to settle into a new fit +.IP [7] +writes the star and group ids, new x and y coordinates, sky values, +new magnitudes and magnitude errors, chi and sharpness statistics +for the fitted stars to the +output group photometry and rejections files +.IP [8] +repeats steps [2]-[7] for each group in the input group photometry file. + +.NH 4 +Running Group, Grpselect, and Nstar + +.PP +Before \fBnstar\fR can be run the stars must be grouped with the +\fBgroup\fR task as shown below. + +.YS +da> group test default default default + +Psf radius in scale units (5.): + New psf radius: 5. scale units 5. pixels +Fitting radius in scale units (3.): + New fitting radius: 3. scale units 3. pixels +Critical overlap in stdevs per pixel (1.): .2 + New critical overlap: 0.2 stdevs per pixel +Minimum good data value (50.) (CR or value): + New minimum good data value: 50. counts +Maximum good data value (24500.) (CR or value): + New maximum good data value: 24500. counts + +Size of Number of +group groups + +1 4 +2 1 +3 1 + +Total of 9 stars in 6 groups\fR +.YE + +The critical overlap parameter \fIcritovlap\fR determines the degree +to which crowding and/or random photometric errors are expected/allowed +to influence the photometry. If the default value of 1 is required to group +all the stars into associations of <= the current value of +\fImaxgroup\fR stars, then unavoidable random photometric errors and +crowding errors will affect the photometry about equally. +If a critical +overlap much greater than 1 is required, then crowding errors will +dominate the random photometric errors. If a critical overlap +much less than 1 does the +job then +unavoidable random photometric errors will dominate, and crowding errors +are relatively insignificant. +In +the previous example the user chose to set \fIcritovlap\fR to a value +much smaller +than 1 to test whether random photometric rather than crowding errors will +dominate the photometry. +.PP +If the first run of \fBgroup\fR separates all the stars into groups of less than +60 all is well and the user can proceed to the \fBnstar\fR task. Otherwise +the \fBgrpselect\fR task must be used to select out the larger groups +and subdivide them as shown in the following example. + +.YS +da> grpselect test.grp.1 small.grp 1 60 +.YE + +.IP ... +First separate out the small groups. +.LP + +.YS +da> grpselect test.grp.1 big.grp.1 61 10000 +.YE + +.IP ... +Next separate out the large groups. +.LP + +.YS +da> group test big.grp.1 default big.grp.2 critovlap=1.0 +.YE + +.IP ... +Rerun the group task on the large group file with a bigger value +of critovlap. +.LP + +.YS +da> pconcat small.grp,big.grp.2 all.grp +.YE + +.IP ... +Finally concatenate all the new group files together. +.LP +This step is not required for the test image since there are only a +few stars and the field is not very crowded. + +.PP +Run \fBnstar\fR on the grouped photometry file and \fBsubstar\fR on the +fitted photometry file. + +.YS +da> nstar test default default default default + +Recenter the stars (yes): + Recenter the stars: yes +Refit the sky (no): + Refit the sky: no +Psf radius in scale units (5.): + New psf radius: 5. scale units 5. pixels +Fitting radius in scale units (3.): + New fitting radius: 3. scale units 3. pixels +Maximum group size in number of stars (60): + New maximum group size: 60 stars +Minimum good data value (50.) (CR or value): + New minimum good data value: 50. counts +Maximum good data value (24500.) (CR or value): + New maximum good data value: 24500. counts + +Group: 1 contains 1 stars + ID: 1 XCEN: 41.01 YCEN: 4.03 MAG: 17.22 +Group: 2 contains 2 stars + ID: 2 XCEN: 23.04 YCEN: 7.07 MAG: 17.75 + ID: 3 XCEN: 17.99 YCEN: 8.00 MAG: 17.57 +Group: 3 contains 3 stars + ID: 5 XCEN: 35.98 YCEN: 22.01 MAG: 16.39 + ID: 7 XCEN: 30.99 YCEN: 25.04 MAG: 17.04 + ID: 4 XCEN: 26.00 YCEN: 22.01 MAG: 16.80 +Group: 4 contains 1 stars + ID: 6 XCEN: 8.02 YCEN: 22.97 MAG: 16.63 +Group: 5 contains 1 stars + ID: 8 XCEN: 28.96 YCEN: 33.93 MAG: 17.74 +Group: 6 contains 1 stars + ID: 9 XCEN: 35.98 YCEN: 42.01 MAG: 16.60 + +da> substar test default "" default default +.YE + +The parameter \fImaxgroup\fR specifies the +maximum number of stars that \fBnstar\fR will +fit simultaneously. The default value of 60 +is a conservative number based +on the observed numerical behavior of the matrix inversion routines. +.PP +For most crowded field photometry applications it is simpler and easier +to use the automated \fBallstar\fR task. + +.NH 4 +The Nstar Output + +.PP +By default \fBnstar\fR writes the quantities: id, group, xcenter, ycenter, +mag, merr, msky, niter, chi, sharp, pier, and perror to the output +photometry and rejections files. +.IP [1] +Id and group are the star and group id numbers in the input group +photometry file. +.IP [2] +Xcenter and ycenter are the best fit coordinates of the star. +If the star was rejected xcenter and ycenter will be the best fit +values of x and y at the time it was rejected. If \fIrecenter\fR is "no" +xcenter and ycenter will be the position of the star in the input +group photometry file. +.IP [3] +Mag and merr are the best fit magnitude and magnitude error respectively. +The instrumental magnitude is computed relative to the magnitude +of the psf model. +Mag and merr are set to INDEF if the star cannot be fit to the +psf model. +.IP [4] +Msky is always the individual sky for the star in the input photometry +file regardless of whether fitsky is "no" or "yes". In the former +case the actual value of the sky used in \fBnstar\fR is +the mean of all the sky values for all the stars in the group. In the +latter case it is a fitted parameter. +.IP [5] +Niter is the number of iterations it took to fit the star. If \fBniter\fR +is equal to the parameter \fImaxiter\fR the user should be +suspicious of the result. However since the convergence criteria are +quite tightly constrained the result may still be reasonable. +Niter is set to 0 if the star cannot be fit to the psf model. +.IP [6] +Chi and sharp are measures of the goodness of fit and the star's shape +respectively. Chi should be ~ 1.0. If it is not then +either the object is not a single star, +the noise model including the ccd gain and readout noise, the flat +fielding error and the interpolation error parameters assumed for the image are +not correct, the +psf model is a poor representation of the true psf, or the input +image does not conform to the requirements of the DAOPHOT package. +Sharp is a measure of the difference between the observed width +of the object and the width of the psf model. Stars should have sharpness +values \(~= 0.0, resolved objects sharpness values > 0.0, and cosmic rays +and similar blemishes sharpnesses values < 0.0. Chi and sharp are set to INDEF +if the star cannot be fit to the psf model. +.IP [7] +Pier and perror are an integer error code and error string respectively. +If no error was encountered during the fit, pier is 0 and perror is +"No_error". + +.NH 3 +Fitting Stars With Allstar + +.PP +\fBAllstar\fR groups, fits +and subtracts the fitted stars from the input image without intervention +by the user. +Because the grouping process is dynamic and the best +fit stars are fit and subtracted first, fewer weak stars +and noise spikes migrate to the position of stronger stars in \fBallstar\fR +than is the case with \fBnstar\fR. \fBAllstar\fR replaces the functionality +of the tasks \fBgroup\fR, \fBgrpselect\fR, \fBnstar\fR, and \fBallstar\fR. +\fBAllstar\fR is the task of choice for doing crowded +field photometry with DAOPHOT. + +.NH 4 +The Allstar Algorithm + +.PP +By default the \fBallstar\fR task performs the following steps: +.IP [1] +reads the task parameters including the name of the input image, the input +photometry file, the psf +model, the output photometry and rejections files, the output +subtracted image, and the \fBdatapars\fR and \fBdaopars\fR algorithm +parameter sets +sets +.IP [2] +reads the ids, x and y coordinates, magnitudes, and sky values for +the first \fImaxnstars\fR stars in the input photometry file, rejecting +at the start stars which have undefined sky values or which +are too close to another star +.IP [3] +reads the original image into a working array and initializes +two scratch arrays containing 1) the noise model and 2) the residuals from +the current best fit for all the stars +.IP [4] +at the beginning of each iteration: +1) groups the stars into physical associations that contain fewer +than \fImaxgroup\fR +stars, regrouping as necessary until all the groups are less than +\fImaxgroup\fR or until the group is too dense to reduce, 2) +subtracts the current best fit for all the stars that are still unfit from +the working copy of the image and stores the results in the residuals +array 3) initializes the weight array for all the unfitted stars +.IP [5] +during each iteration: 1) extracts the data within fitrad pixels +around each star in each group from the residuals image, 2) +performs a weighted non-linear least-squares fit of the psf model to +the extracted +data, ignoring bad pixels and down-weighting pixels that deviate too +far from the psf model, and 3) computes new x and y coordinates and +magnitudes for each star in each group +.IP [6] +after the fourth iteration 1) writes the id, new x and y coordinates, +sky value, new magnitude and magnitude error, number of iterations +required to fit the star, and the chi and sharpness statistic of stars +which meet the convergence criteria, to +the output photometry file, 2) subtracts the fitted star permanently from +the working copy of the image, 3) updates the +noise model in the weight array, 4) and eliminates the star from +the active star list +.IP [7] +after the fourth iteration rejects stars which: 1) are too faint +(more than 12.5 magnitudes fainter +than the psf model), 2) have too low a signal-to- +noise ratio (1.0, 1.5 and 2.0 sigma detection after 5, 10, and 15 iterations +respectively), 3) have too few good +pixels to compute a fit, 4) do not permit a unique solution, +5) have merged with another star (star is +< 0.37 * fwhmpsf from a brighter star), 6) are both too noisy +and too close to a neighbor star (star is between 0.37 and 1.0 * fwhmpsf from +a brighter star in the group and is a 1.0, 1.5, or 2.0 sigma +detection before iterations 5, 10, and 15 respectively), +or 7) are part of a group too dense to be reduced. +.IP [8] +writes out the final version of the work array into the output subtracted +image + +.NH 4 +Running Allstar + +.PP +\fBAllstar\fR is run as shown below. + +.YS +da> allstar test default default default default default + +Recenter the stars (yes): + Recenter the stars: yes +Refit the sky (no): + Refit the sky: no +Psf radius in scale units (5.): + New psf radius: 5. scale units 5. pixels +Fitting radius in scale units (3.): + New fitting radius: 3. scale units 3. pixels +Maximum group size in number of stars (60): + New maximum group size: 60 stars +Minimum good data value (50.) (CR or value): + New minimum good data value: 50. counts +Maximum good data value (24500.) (CR or value): + New maximum good data value: 24500. counts + +NITER = 1 +NITER = 2 +NITER = 3 +NITER = 4 +FITTING: ID: 1 XCEN: 41.01 YCEN: 4.03 MAG: 17.22 +FITTING: ID: 4 XCEN: 26.00 YCEN: 22.01 MAG: 16.80 +FITTING: ID: 7 XCEN: 30.99 YCEN: 25.04 MAG: 17.04 +FITTING: ID: 6 XCEN: 8.02 YCEN: 22.97 MAG: 16.63 +FITTING: ID: 8 XCEN: 28.96 YCEN: 33.93 MAG: 17.74 +FITTING: ID: 9 XCEN: 35.98 YCEN: 42.01 MAG: 16.60 +NITER = 5 +FITTING: ID: 2 XCEN: 23.04 YCEN: 7.05 MAG: 17.75 +FITTING: ID: 3 XCEN: 18.00 YCEN: 7.99 MAG: 17.56 +FITTING: ID: 5 XCEN: 35.98 YCEN: 22.01 MAG: 16.39 +.YE + +.PP +Users can easily run \fBallstar\fR as a background job as shown below. + +.YS +da> allstar test default default default default default verify- \\ + >& allstar.out & +.YE + +.NH 4 +The Allstar Output + +.PP +\fBAllstar\fR writes the following +quantities: id, xcenter, ycenter, mag, merr, msky, niter, chi, sharp, +pier, and perror to the output photometry and +rejections files. +.IP [1] +Id is the id number of the star as read from the input photometry file. +.IP [2] +Xcenter and ycenter are the best fit position of the star. +If the star was rejected xcenter and ycenter will be the computed +values of x and +y at the time it was rejected. If \fIrecenter\fR is "no", xcenter and ycenter +will be the position of the star in the input photometry file. +.IP [3] +Mag and merr are the best fit magnitude and magnitude error respectively. +The instrumental magnitude is computed relative to the magnitude of the +psf model. +Mag and merr are set to INDEF if the star cannot be fit to the psf model. +.IP [4] +Msky is the sky value in the input photometry file if \fIfitsky\fR = "no", +otherwise it is the +recomputed sky value. If \fIfitsky\fR is "yes" the sky is recomputed +every third iteration after the current best fit for the star is +subtracted from the image data. The new sky value is set to the +average of 40% of the sky pixels, centered on the median sky value, +which are inside the sky +annulus defined by the parameters \fIsannulus\fR and +\fIwsannulus\fR. The sky value is not recomputed +if there are fewer than 100 sky pixels in the specified sky annulus +even if \fIfitsky\fR is "yes". +If the star is not fit for some reason, +msky is the sky value at the time the star was rejected. +.IP [5] +Niter is the number of iterations it took to fit the star. If this +number is equal to \fImaxiter\fR the user should be +suspicious of the result. However as the convergence criteria are +conservative the star may still be reasonably well fit. +Niter is set to 0 if the star cannot be fit to the psf model. +.IP [6] +Chi and sharp are measures of the goodness of fit and the shape +respectively. Chi should be ~ 1.0. If it is not, then +either the object is not a single star, the noise model including +one or more of the gain, readout noise, flat-fielding error, and +interpolation error parameters for the image are incorrect, the +psf model is a poor representation of the true psf, or the input +image does not conform to the requirements of the DAOPHOT package. +Sharpness is a measure of the difference between the observed width +of the object and the width of the psf model. Stars should have a sharpness +value ~ 0.0, resolved objects a sharpness of > 0.0, and cosmic rays and similar +blemishes a sharpness of < 0. Chi and sharp are set to INDEF if the star +cannot be fit for some reason. +.IP [7] +Pier and perror are an integer error code and error string respectively. +If no error was encountered during the fit, pier is 0 and perror is +"No_error". + +.NH 2 +Examining the Output Photometry Files + +.PP +The identical tools can be used to examine the output of the \fBpeak\fR, +\fBnstar\fR, and \fBallstar\fR tasks. Some examples using the output of +\fBallstar\fR are shown below. +.PP +The following command produces a plot of magnitude error versus magnitude. + +.YS +da> pdump test.als.1 mag,merr yes | graph point+ +.YE + +The following command produces a plot of chi versus magnitude. + +.YS +da> pdump test.als.1 mag,chi yes | graph STDIN point+ +.YE + +The following command produces a plot of chi versus sharpness. + +.YS +da> pdump test.als.1 sharp,chi yes | graph STDIN point+ +.YE + +The output photometry file can also be examined interactively +with the \fBpexamine\fR task and the displayed subtracted image. +Note that the fitted stars are marked in green and the rejected stars +are marked in red on the display. + +.YS +da> display test.sub.1 1 fi+ + +da> pdump test.als.1 xcenter,ycenter yes | tvmark 1 STDIN col=205 + +da> pdump test.arj.1 xcenter,ycenter yes | tvmark 1 STDIN col=204 + +da> pexamine test.als.1 "" test.sub.1 +.YE + +.IP ... +A plot of magnitude error versus magnitude appears on the screen. +.IP ... +The user moves to a discrepant point in the graph and types o to get a +listing of the results for the star, r to get a radial profile plot +around the subtracted star, and concludes on the basis of the plots +that the bad chi value is due to the star being a close double. +.IP ... +The user types i to switch to image cursor mode, +moves to several other stars with poor subtractions and types +s to see a surface plot of the residuals. +.IP ... +The user types q to quit. + +.NH 2 +Problems with the Photometry + +.PP +Bad chi values in, and poor +subtractions of, \fBpeak\fR, \fBnstar\fR or \fBallstar\fR +photometry can usually be traced to: 1) a psf model which was +poorly determined in the first place, e.g. poor choice of +parameters, bad choice of +psf stars or too few stars used for determining a good variable psf model, +2) data reduction problems e.g. the mean sky value was subtracted from the +image, the image statistics have been altered, or cosmic ray removal +clipped the tops of the stars, to give a few of many examples, +or 3) the properties of the image, e.g. non-linearity, a psf which has +very high order variability or very undersampled data, make computation +of a good psf model difficult or impossible. +.PP +Bad chi values can also be caused by incorrect +values of gain and readout noise or by a data reduction operation +which has significantly affected the image statistics. +.PP +Poor sky fitting can also cause scatter +in the photometry. Users should carefully check the position of the +sky annulus used in \fBphot\fR if they are seeing poor subtractions. +If the images have a rapidly varying +background due, due for example to nebulosity, it might be useful to +check out the alternate sky fitting routines, median or centroid, in the +\fBphot\fR task. The refit sky option in \fBpeak\fR and \fBnstar\fR +should be exercised with caution +since a larger fitting radius is often required +to get a reasonable sky fit, than is required to get good positions +and magnitudes, and this in turn can cause more scatter +in the photometry due to the influence of neighbors. On the other +hand the refit sky option in \fBallstar\fR can often significantly +reduce scatter in very crowded regions since it can use data closer to +or even underneath (!) the star to improve the sky estimate. +Users who use this option must remember to set the inner +radius of the \fBallstar\fR sky annulus to avoid the inner stellar +core region where there is a lot of noise in the subtraction. +.PP +After running \fBsubstar\fR on a file produced by the \fBpeak\fR +task, users will sometimes see large holes in the data at the +position of some subtracted +stars. This is usually caused by fainter stars (which are fit individually) +migrating to the position of a brighter nearby star and then being +subtracted out twice by \fBsubstar\fR. Keeping the fitting radius small +will help minimize this problem, but if it is frequent and the frame +is somewhat crowded, the user should run \fBnstar\fR or \fBallstar\fR +instead of \fBpeak\fR. +.PP +A similar problem can be caused by users running \fBdaofind\fR +with a very low threshold and detecting a lot of noise spikes, which +then migrate to the positions of brighter stars +and cause scatter and holes in the subtracted \fBpeak\fR photometry, +or attach themselves to noise spikes in the stellar profiles and cause +scatter and holes in the subtracted \fBnstar\fR photometry. +Similar problems can affect \fBallstar\fR photometry but to a much +lesser degree since the +stars are grouped dynamically and subtracted from the input data as +they are fit. For all three photometry tasks spurious detections +can consume a lot of excess computer time because the stellar groups +become much larger. + +.NH 2 +Detecting Stars Missed By Daofind + +.PP +In very crowded fields many new stars, missed by the first run of \fBdaofind\fR, +will be detected after +the first run of \fBpeak\fR+\fBsubstar\fR, \fBnstar\fR+\fBsubstar\fR, +or \fBallstar\fR. If there +are many "missed" stars +\fBdaofind\fR should be run on the subtracted image after increasing the +\fIthreshold\fR parameter to avoid detecting the residuals +of previously subtracted stars. If there +are only a few such stars they can be "detected" by creating a coordinate +file using the subtracted image and \fBtvmark\fR in interactive mode. +Examples of both techniques are shown below. + +.YS +da> daofind test.sub.1 newstars.coo threshold=5.0 +.YE + +or + +.YS +da> display test.sub.1 1 fi+ + +da> pdump test.als.1 xcen,ycen yes | tvmark 1 STDIN col=204 + +da> tvmark 1 newstars.coo inter+ +.YE + +.IP ... +Move cursor to missing stars and tap the \fBa\fR key to append them to the +output coordinate file. + +.NH 2 +Initializing the Missing Star Photometry with Phot + +.PP +The next step is to get initial photometry for the "missing" +stars. The simplest way is +to run \fBphot\fR on the original image using the coordinate list created +by \fBdaofind\fR or \fBtvmark\fR, and the same algorithm parameters as +were used +in the first run of \fBphot\fR. It is also possible to use \fBphot\fR directly +in interactive mode to create a photometry file of missed stars. Both +options are shown below. + +.YS +da> phot test newstars.coo newstars.mag +.YE + +or + +.YS +da> display test.sub.1 1 fi+ + +da> pdump test.als.1 xcen,ycen yes | tvmark 1 STDIN col=204 + +da> phot test "" newstars.mag centroid=calgorithm inter+ +.YE + +.IP ... +Point the cursor to the missing stars and tap \fBspacebar\fR. +.LP + +Note that if the stars are or were marked with the cursor, the user must +turn centroiding on in order to center them correctly. + +.NH 2 +Merging Photometry Files with Pfmerge + +.PP +The photometry file containing the aperture photometry for the new stars +can be combined with the best psf fitting photometry already computed +by the \fBnstar\fR or \fBallstar\fR tasks +for the original star list, using the task \fBpfmerge\fR as shown below. +The \fBprenumber\fR task ensures that the new stars all have unique ids. + +.YS +da> pfmerge test.als.1,newstars.mag newstars.als.1 +da> prenumber newstars.als.1\fR +.YE + + +.NH 2 +Refitting the Stars with Allstar + +.PP +After the photometry files have been merged a final run of \fBallstar\fR or +\fBgroup\fR+\fBnstar\fR+\fBsubstar\fR on the combined file in order +to compute accurate magnitudes for the new stars should be made +as shown below. + +.YS +da> allstar test newstars.als.1 default default default default +.YE + +.NH 2 +Examining the Subtracted Image + +.PP +The user should search the subtracted image for any remaining unfit +stars and perform another iteration of \fBdaofind\fR, \fBphot\fR, +\fBpfmerge\fR and \fBallstar\fR to computed fitted magnitudes for +the new objects. + +.NH 2 +Computing an Aperture Correction + +.PP +The aperture correction is the number which must be added to the +fitted instrumental magnitudes computed by the \fBpeak\fR, +\fBnstar\fR, or \fBallstar\fR tasks to produce the total instrumental +magnitude. +.PP +In order to compute aperture corrections for an image with a constant psf model +the user must: +.IP [1] +identify several bright isolated stars in the input image or subtract +all the neighbors from around several bright stars such as the +psf stars using the current psf model and the \fBsubstar\fR task +.IP [2] +using a minimum aperture radius equal to the one used in \fBphot\fR to compute +initial aperture photometry for all the crowded field stars, +and a maximum aperture radius equal to the one through which +the instrumental magnitudes of the standard stars were or will be measured, +use the \fBphot\fR task to +do multi-aperture photometry of the stars identified in [1] through at +least five apertures +.IP [3] +run the \fBmkapfile\fR task in the PHOTCAL package on the aperture +photometry file produced in 2, to determine the aperture +correction for the image as shown below +.LP + +.YS +da> phot test "" test.apmags calg=centroid aperture="3,3.5,4.0,4.5 5.0" +.YE + +.IP ... +Do multi-aperture photometry of the selected stars. +.LP + +.YS +da> mkapfile test.apmags 5 test.apcors +.YE + +.IP ... +Compute the aperture correction between apertures 1 and 5. + +.PP +To compute compute aperture corrections for an image with a variable psf model +the user must: +.IP [1] +identify several bright isolated stars in the input image or subtract +all the neighbors from around several bright stars such as the +psf stars using the current psf model and the \fBsubstar\fR task +.IP [2] +using a photometry aperture equal to the one through which +the magnitudes of the standard stars were or will be measured, +use the \fBphot\fR task to +do aperture photometry of the stars identified in [1] +.IP [3] +extract the fitted magnitudes for these stars from existing \fBnstar\fR +or \fBallstar\fR photometry or recompute them using the +\fBnstar\fR or \fBallstar\fR tasks and the current psf model +.IP [4] +set the aperture correction to the mean difference between the fitted +magnitudes computed in [3] and the aperture photometry magnitudes +computed through the large aperture in [2] + +.NH +References + +.LP +.nf +Stetson, P. B. 1987 Pub .A.S.P., \fB99\fR, 191 +Stetson, P. B., Davis, L.E. and Crabtree, D.B. 1989, in + \fICCDs in Astronomy\fR, G.H. Jacoby, San Francisco: Astronomical + Society of the Pacific, 289 +Stetson, P. B. 19 Pub .A.S.P., \fB102\fR, 932 +Stetson, P.B, 1992, \fIUser's Manual for DAOPHOT II\fR +Stetson, P. B. 1992 in \fIAstronomical Data Analysis Software and Systems I\fR, + D.M. Worall, C. Biemesderfer, and J. Barnes, San Francisco: Astronomical + Society of the Pacific, 297 +.fi + +.NH +Appendices + +.NH 2 +The Instrumental Magnitude Scale + +.PP +The instrumental magnitude scale is set by the magnitude assigned +to the psf model, the quantity \fIpsfmag\fR stored in the psf image header. +Psfmag is the magnitude of the first psf star in the input photometry +file, usually but not always the file written by the \fBphot\fR task. +If magnitudes were measured through more than one aperture +in \fBphot\fR, the magnitude used will be the +magnitude through the smallest aperture. + +.NH 2 +The Analytic Psf Models + +.PP +The functional forms of the currently supported analytic psf models +are listed below. +The quantity A is a normalization factor. The Pn are +the parameters which are fit during the psf modeling process. + +.nf + z = x ** 2 / p1 ** 2 + y ** 2 / p2 ** 2 + gauss = A * exp (-0.5 * z) + + z = x ** 2 / p1 ** 2 + y ** 2 / p2 ** 2 + x * y * p3 + moffat15 = A / (1 + z) ** 1.5 + moffat25 = A / (1 + z) ** 2.5 + + z = x ** 2 / p1 ** 2 + y ** 2 / p2 ** 2 + x * y * p3 + lorentz = A / (1.0 + z) + + z = x ** 2 / p1 ** 2 + y ** 2 / p2 ** 2 + e = x ** 2 / p1 ** 2 + y ** 2 / p2 ** 2 + x * y * p4 + penny1 = A * ((1 - p3) / (1.0 + z) + p3 * exp (-0.693*e)) + + z = x ** 2 / p1 ** 2 + y ** 2 / p2 ** 2 + p5 * x * y + e = x ** 2 / p1 ** 2 + y ** 2 / p2 ** 2 + x * y * p4 + penny2 = A * ((1 - p3) / (1.0 + z) + p3 * exp (-0.693*e)) +.fi + +.NH 2 +The Error Model + +.PP +The predicted errors in the the DAOPHOT photometry are computed per +pixel as shown below, where terms 1, 2, 3, and 4 represent the readout +noise, the poisson noise, the flat-fielding error, and the +interpolation error respectively. The quantities readnoise, epadu, +I, M, p1, and p2 are the effective readout noise in electrons, the +effective gain in +electrons per ADU, the pixel intensity in ADU, the PSF model +intensity in ADU, the FWHM in x in pixels, and the FWHM in y in pixels. + +.nf + error = sqrt (term1 + term2 + term3 + term4) (ADU) + term1 = (readnoise / epadu) ** 2 + term2 = I / epadu + term3 = (.01 * flaterr * I) ** 2 + term4 = (.01 * proferr * M / p1 / p2) ** 2 +.fi + + +.NH 2 +The Radial Weighting Function + +.PP +The radial weighting function employed by all the psf fitting tasks +is shown below, where dx and dy are the distance of the pixel +in question from the centroid of the star being fit. + +.nf + wtr = 5.0 / (5.0 + rsq / (1.0 - rsq)) + rsq = (dx ** 2 + dy ** 2) / fitrad ** 2 +.fi + +.NH 2 +Total Weights + +.PP +The total weight assigned each pixel in the fit is the +following. + +.nf + wtp = wtr / error ** 2 +.fi + +.NH 2 +Bad Data Detection + +.PP +Pixels less than the good data minimum \fIdatamax\fR or greater than +the good data maximum \fIdatamax\fR are rejected immediately from the +fit. +.PP +After a few iterations and if clipexp > 0, a clipping scheme to +reject bad data is enabled. The weights of the pixels are +recomputed as follows. Pixels having a residual of cliprange sigma +will have their weight reduced by half. + +.nf + wt = wtp / (1.0 + (residual / error / chiold / + cliprange) ** clipexp) +.fi + +.NH 2 +Stellar Mergers + +.PP +In order for two stars to merge during the course of the psf fitting +process either their separation must be < 0.37 * FWHM of the psf model, +or their separation must be > 0.37 * FWHM but < 1.0 * FWHM of the +psf model and the signal-to-noise ratio of the fainter is less than 1.0, 1.5, +or 2.0 after iterations 4, 9, and 14 respectively. + +.NH 2 +Faint Stars + +.PP +Stars are considered to be too faint if they are more than 12.5 +magnitudes fainter than the psf, or if after a certain number of iterations, +they have a signal-to-noise ratio less than 2.0. |