Initial commit

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