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