diff options
Diffstat (limited to 'noao/digiphot/daophot/doc/allstar.hlp')
| -rw-r--r-- | noao/digiphot/daophot/doc/allstar.hlp | 519 |
1 files changed, 519 insertions, 0 deletions
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 |