.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
