.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