Initial commit

1 files changed, 501 insertions, 0 deletions

diff --git a/noao/digiphot/daophot/doc/nstar.hlp b/noao/digiphot/daophot/doc/nstar.hlp
new file mode 100644
index 00000000..cf7c9936
--- /dev/null
+++ b/noao/digiphot/daophot/doc/nstar.hlp
@@ -0,0 +1,501 @@
+.help nstar May00 noao.digiphot.daophot
+.ih
+NAME
+nstar -- fit the PSF to groups of stars simultaneously
+.ih
+USAGE
+nstar image groupfile psfimage nstarfile rejfile
+.ih
+PARAMETERS
+.ls image
+The list of images containing the stellar groups to be fit.
+.le
+.ls groupfile
+The list of input group photometry files containing the group membership
+information and initial estimates for the positions and magnitudes of the stars
+to be measured. There must be one group file for every input image. If
+groupfile is "default", "dir$default", or a directory specification then NSTAR
+will look for a file with the name image.grp.? where ? is the highest existing
+version number. Groupfile is usually the output of the DAOPHOT GROUP task, but
+may also be the output of the NSTAR and PSF tasks. Groupfile 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 nstarfile
+The list of output photometry files. There must be one output photometry
+file for every input image.  If nstarfile is "default", "dir$default", or a
+directory specification, then NSTAR will write an output file with the name
+image.nst.? where ? is the next available version number. Nstarfile 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 \fInstarfile\fR, otherwise only the stars
+which were successfully fit are written to \fInstarfile\fR and the remainder are
+written to rejfile. If rejfile is "default", "dir$default", or a directory
+specification NSTAR writes an output file with the name image.nst.? 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 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 \fIgroupfile\fR, of the
+psf model \fIpsfimage\fR, and of the output coordinates written to
+\fInstarfile\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 = ")_.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 NSTAR task parameters? Verify can be set to the DAOPHOT
+package parameter value (the default), "yes", or "no".
+.le
+.ls update = ")_.update"
+Update the NSTAR 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
+NSTAR computes x and y centers and magnitudes for all the stellar groups in
+\fIgroupfile\fR by fitting the PSF \fIpsfimage\fR to the data in \fIimage\fR.
+NSTAR reads the group membership information along with initial estimates of
+the centers and magnitudes, and the sky values from the photometry file
+\fIgroupfile\fR.  \fIGroupfile\fR is usually the output of the DAOPHOT GROUP
+task but may also be the output of the PSF and NSTAR tasks. The computed
+centers and magnitudes are written to \fInstarfile\fR along with the sky
+values, 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
+undefined, only stars that are successfully fit are written to \fInstarfile\fR,
+and the remainder are written to \fIrejfile\fR. Otherwise all the stars are
+written to \fInstarfile\fR.  \fINstarfile\fR and \fIrejfile\fR are text
+databases if the DAOPHOT package parameter \fItext\fR is "yes", an STSDAS table
+database if it is "no".
+
+The coordinates read from \fIgroupfile\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 \fInstarfile\fR and \fIrejfile\fR are in the
+coordinate system defined by \fIwcsout\fR with the exception of the psf model
+center coordinates PSFX and PSFY which are always in the logical system of
+the input image. 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 NSTAR is run interactively the first measurement will appear
+to take a long time as the entire image must be read in before the measurement
+is actually made. All subsequent measurements will be very fast because NSTAR
+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. However if the input object lists are sorted close to row order
+and sparse caching may actually worsen not improve the execution time. 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.
+
+By default NSTAR computes new centers for all the stars in \fIgroupfile\fR.
+However if the DAOPARS parameter \fIrecenter\fR is "no", NSTAR assumes that the
+x and y centers in \fIgroupfile\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 NSTAR computes the sky value for each group by averaging the
+individual sky values in \fIgroupfile\fR for all the stars in the group. If
+\fIgroupsky\fR is "no" then the sky value for a particular pixel which
+contributes to the group fit is set to the mean of the sky values of only those
+stars for which the pixel is within one fitting radius. However if the DAOPARS
+parameter \fIfitksy\fR is "yes", then NSTAR computes a new group sky value as
+part of the non-linear least-squares fit. Recomputing the sky can significantly
+reduce the scatter in the magnitudes in regions where the sky background is
+varying rapidly, but users may need to increase \fIfitrad\fR to include more
+sky pixels in the fit. Users should experiment cautiously with this option.
+
+Only pixels within the good data range delimited 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 and set the
+appropriate parameters in DATAPARS before beginning any DAOPHOT reductions.
+
+Only pixels within the fitting radius \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
+fitting algorithm determines 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 weights
+in the fit for each star. Values of \fIfitrad\fR close to the full-width at
+half-maxima of the PSF are recommended. In actual fact NSTAR imposes a minimum
+number of pixel limit of four.
+
+NSTAR performs 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 NSTAR predicts based on the values of the
+DATAPARS parameters \fIreadnoise\fR and \fIepadu\fR, and the flat-fielding and
+profile interpolation errors specified by the DAOPARS \fIflaterr\fR and
+\fIproferr\fR parameters. To obtain optimal fits, users are strongly advised
+to determine those parameters accurately and to enter their values in DATAPARS
+and DAOPARS before beginning any DAOPHOT reductions.
+
+For each group of stars to be fit, NSTAR extracts a subraster from \fIimage\fR
+which extends approximately \fIpsfrad\fR / \fIscale\fR + 1 pixels wide past
+the limiting values of the x and y coordinates of the stars in the group.
+\fIPsfrad\fR is the PSF radius specified in the DAOPARS task, and \fIscale\fR
+is the image scale specified by the DATAPARS task. \fIPsfrad\fR may be less
+than or equal to but can never exceed the value of the image header parameter
+"PSFRAD" in \fIpsfimage\fR. \fIPsfrad\fR should always be several pixels larger
+than \fIfitrad\fR to permit the x and y centroids to wander during the fitting
+process.
+
+As well as the computed x and y centers and magnitudes, NSTAR outputs the number
+ of times the PSF fit had to be iterated before reaching convergence. 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. It must be emphasized that every star in the group
+must individually satisfy the convergence criteria in order for the group to be
+ considered adequately reduced.
+
+NSTAR 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 NSTAR 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.
+
+NSTAR implements a highly sophisticated star rejection algorithm. First of all,
+ any group of stars which is more than a certain size is simply not fit. The
+maximum group size is specified by the \fImaxgroup\fR parameter in the DAOPARS
+task. Larger groups may run into numerical precision problems during the fits.
+Users should exercise care in increasing the \fImaxgroup\fR parameter. 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, their photocentric position
+and combined magnitude is assigned to the brighter of the two stars, and the
+fainter is eliminated. Any star which converges to 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 iterations 10, if the faintest
+star in the group has a brightness less than 1.5 sigma above zero, it is
+eliminated. After iterations 15 to 50 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.
+
+Whenever a star is eliminated the iteration counter is backed up by one and
+reduction proceeds with a smaller set of stars. Backing up the counter gives
+the second least certain star in the group two iterations to settle into a new
+fit before its fate is decided.  The star rejection algorithm depends upon the
+DATAPARS \fIreadnoise\fR and \fIgain\fR parameters and the DAOPARS parameter
+\fIflaterr\fR and \fIproferr\fR. Therefore these parameters should be set to
+reasonable values before running NSTAR.
+
+NSTAR operates in a very similar manner to PEAK. However because it fits groups
+ of stars simultaneously it is much more accurate than PEAK in crowded regions.
+The ALLSTAR task also fits groups of stars simultaneously, both  grouping the
+stars dynamically as well as producing a subtracted image. Essentially it
+replaces GROUP, GRPSELECT, NSTAR and SUBSTAR. However the user has little
+control over the grouping process and does not know at the end which stars were
+actually fit together. NSTAR is the task of choice when a user wants to
+maintain rigorous 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 \fInstarfile\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  group  xcenter  ycenter  mag  merr  msky  niter  sharpness
+	    chi  pier  perr
+.fi
+
+Id is the id number of the star and group is its group number. 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> group dev$ypix default default default 
+
+        ... verify the prompts
+
+        ... the output will appear in ypix.grp.1
+
+    da> nstar dev$ypix default default default default
+
+        ... verify the prompts
+
+        ... the results will appear in ypix.nst.1 and ypix.nrj.1
+
+    da> pdump ypix.nst.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> substar dev$ypix default  "" default default
+
+        ... subtract the fitted 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. Run nstar 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> nstar dev$ypix[150:450,150:450] default default default default \
+        wcsin=tv wcspsf=tv wcsout=tv
+
+        ... answer the verify prompts
+
+        ... fit the stars
+
+        ... the results will appear in ypix.nst.2 and ypix.nrj.2
+
+    da> display dev$ypix[150:450,150:450] 1
+
+        ... display the image
+
+    da> pdump ypix.nst.2 xc,yc yes | tvmark 1 STDIN col=204
+
+        ... mark the stars
+
+    da> substar dev$ypix ypix.nst.2 "" default default
+
+        ... subtract stars from parent image
+
+        ... the output images is ypix.sub.2
+
+
+    da> substar dev$ypix[150:450,150:450] ypix.nst.2 "" default default  \
+        wcsin=tv wcspsf=tv wcsout=tv
+
+        ... subtract stars from the nstar input image
+
+        ... the output images is ypix.sub.3
+
+.fi
+
+
+
+3. Run nstar exactly as in example 1 but submit the task to the background.
+Turn off verify and verbose.
+
+.nf
+    da> nstar dev$ypix default default default default verbose- \
+        verify- &
+
+        ... the results will appear in ypix.nst.3 and ypix.nrj.3
+.fi
+
+
+.ih
+TIME REQUIREMENTS
+.ih
+BUGS
+.ih
+SEE ALSO
+datapars,daopars,peak,allstar
+.endhelp