From fa080de7afc95aa1c19a6e6fc0e0708ced2eadc4 Mon Sep 17 00:00:00 2001 From: Joseph Hunkeler Date: Wed, 8 Jul 2015 20:46:52 -0400 Subject: Initial commit --- noao/digiphot/daophot/doc/peak.hlp | 439 +++++++++++++++++++++++++++++++++++++ 1 file changed, 439 insertions(+) create mode 100644 noao/digiphot/daophot/doc/peak.hlp (limited to 'noao/digiphot/daophot/doc/peak.hlp') 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 -- cgit