path: root/noao/digiphot/daophot/doc/allstar.hlp

.help allstar May00 noao.digiphot.daophot
.ih
NAME
allstar -- group and fit psf to multiple stars simultaneously
.ih
USAGE
allstar image photfile psfimage allstarfile rejfile subimage
.ih
PARAMETERS
.ls image
The list of images containing the stars to be fit.
.le
.ls photfile
The input photometry files containing the initial estimates of the positions,
sky values, and magnitudes of the stars to be fit. There must be one input
photometry file for every input image.  If photfile is "default", "dir$default",
or a directory specification, then ALLSTAR looks for a file with the name
image.mag.? where ? is the highest existing version number. Photfile is usually
the output of the DAOPHOT PHOT task but may also be the output of the PSF, PEAK
and NSTAR tasks, or the ALLSTAR task itself.
.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 allstarfile
The list of output photometry files. There must be one output photometry
file for every input image.  If allstarfile is "default", "dir$default", or a
directory specification, then ALLSTAR will write an output file with the name
image.als.? where ? is the next available version number. Allstarfile 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 \fIallstarfile\fR, otherwise only the stars
which were successfully fit are written to \fIallstarfile\fR and the remainder
are written to rejfile. If rejfile is "default", "dir$default", or a directory
specification ALLSTAR writes an output file with the name image.als.? 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 subimage
The list of output images with the fitted stars subtracted. There must be one
subtracted image for every input image. If subimage is "default", "dir$default",
or a directory specification, then ALLSTAR will create an image with the name
image.sub.? where ? is the next available version number. Otherwise
\fIsubimage\fR must specify one output image for every image in \fIimage\fR.
.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
\fIallstarfile\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 = yes
Cache all the data in memory ? If \fIcache\fR is "yes", then ALLSTAR attempts
to preallocate sufficient space to store the input image plus the two
image-sized working arrays it requires, plus space for the starlist, in memory.
This can significantly reduce the total execution time. Users should however
beware of creating a situation where excessive paging occurs.  If \fIcache\fR =
"no", ALLSTAR operates on subrasters containing the group currently being
reduced, and writes the intermediate results to temporary scratch images. This
option will work on any-sized image (unless a single group becomes the size of
the entire image!) but can become slow of there are a large number of disk
accesses. Users may wish to experiment to see which mode of operation suits
their system best.
.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
.ls verify = ")_.verify"
Verify the critical ALLSTAR task parameters. Verify can be set to the daophot
package parameter value (the default), "yes", or "no".
.le
.ls update = ")_.update"
Update the critical ALLSTAR task parameters if \fIverify\fR = "yes".  Update
can be set to the daophot package parameter value (the default), "yes", or
"no".
.le

.ih
DESCRIPTION

ALLSTAR computes x and y centers, sky values, and magnitudes for the stars in
\fIphotfile\fR by fitting the PSF \fIpsfimage\fR to groups of stars in the IRAF
image  \fIimage\fR. Initial estimates of the centers, sky values, and
magnitudes, are read from the photometry list \fIphotfile\fR. ALLSTAR groups
the stars dynamically, performing a regrouping operation after every iteration.
The new computed centers, sky values, and magnitudes are written to
\fIallstarfile\fR along with 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 not null (""), only stars that are successfully fit
are written to \fIallstarfile\fR, and the remainder are written to
\fIrejfile\fR. Otherwise all the stars are written to \fIallstarfile\fR.
\fIAllstarfile\fR and \fIrejfile\fR are text databases if the DAOPHOT package
parameter \fItext\fR is "yes", STSDAS table databases if it is "no". An image
with all the fitted stars subtracted out is written to \fIsubimage\fR. In
effect ALLSTAR performs the combined operations of GROUP, GRPSELECT, NSTAR,
and SUBSTAR.

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 \fIallstarfile\fR and \fIrejfile\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.

By default ALLSTAR computes new centers for all the stars in \fIphotfile\fR.
However if the DAOPARS parameter \fIrecenter\fR is "no", ALLSTAR assumes that
the x and y centers in \fIphotfile\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 (\fIgroupsky\fR = "yes") ALLSTAR computes the sky value for each
group by averaging the individual sky values in \fIphotfile\fR for all the
stars in the group. If \fIgroupsky\fR = "no", the sky value for each pixel
which contributes to the group fit is set equal to the mean of the sky values
for those stars for which the pixel falls within one fitting radius.  If the
DAOPARS parameter \fIfitksy\fR is "yes", then ALLSTAR recomputes the individual
sky values before averaging over the group, by, every third iteration,
subtracting off the current best fit for the star and using the pixel values in
the annulus defined by the DAOPARS parameters \fIsannulus\fR and \fIwsannulus\fR
to recompute the sky. The actual sky recomputation is done by averaging forty
percent of the sky pixels centered on the median of the distribution.
Recomputing the sky can significantly reduce the scatter in the magnitudes in
regions where the sky background is varying rapidly.

Only pixels within the good data range defined 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 for their detector and set the
values in DATAPARS before beginning any DAOPHOT reductions.

Only pixels within the fitting radius parameter \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 fits normally compute 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 radial weights in the fit for each star. ALLSTAR arbitrarily imposes a
minimum number of good pixels limit of four. Values of \fIfitrad\fR close to
the full-width at half-maxima of the PSF are recommended.

ALLSTAR computes 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 ALLSTAR predicts based on the detector
noise characteristics specified by the DATAPARS parameters \fIreadnoise\fR and
\fIepadu\fR, and the flat-fielding and profile interpolation errors specified
by the DAOPARS task \fIflaterr\fR and \fIproferr\fR parameters. Both to obtain
optimal fits, and because ALLSTAR employs a conservative formula for reducing
the weights of deviant pixels (parametrized by the \fIclipexp\fR and
\fIcliprange\fR parameters in the DAOPARS task) which do not approach the model
as the fit proceeds, which depends on \fIreadnoise\fR,  \fIepadu\fR,
\fIflaterr\fR, and \fIproferr\fR, users are strongly advised to determine those
parameters accurately and to enter their values in DATAPARS and DAOPARS before
beginning any DAOPHOT reductions.

By default for each group of stars to be fit during each iteration, ALLSTAR
extracts a subraster from \fIimage\fR which extends approximately \fIfitrad\fR
/ \fIscale\fR + 1 pixels wide past the limiting values of x and y coordinates
of the stars in the group. \fIFitrad\fR is the fitting radius specified in the
DAOPARS task. \fIScale\fR is the image scale specified by the DATAPARS task.
\fIFitrad\fR may be less than or equal to but can never exceed the value of the
image header parameter "PSFRAD" in \fIpsfimage\fR.

If the \fIcache\fR parameter is set to "yes" then ALLSTAR attempts to store all
the vectors and arrays in memory.  This can significantly reduce the system
overhead but may cause excessive paging on machines with a small amount of
memory. For large images it may be necessary to set \fIcache\fR to "no", and
use the disk for scratch storage. Users should experiment to see what suits
them best.

As well as the computed x and y centers, sky values, and magnitudes, ALLSTAR
outputs the number of times the PSF fit had to be iterated before convergence
was achieved. 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.

ALLSTAR 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 ALLSTAR 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.

ALLSTAR implements a sophisticated star rejection algorithm. First of all any
group of stars which is more than a certain size is not reduced. This maximum
group size is specified by the \fImaxgroup\fR parameter in the DAOPARS task.
Large groups may run into numerical precision problems during the fits, so
users should increase this parameter with caution.  ALLSTAR however, in
contrast to NSTAR, attempts to subdivide large groups. If the group is too
dense to reduce in size, ALLSTAR throws out the faintest star in the group
and tries to rereduce it.  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 and their photocentric position and combined magnitude is assigned
to the brighter of the two and the fainter is eliminated. Any star which
converges to magnitude  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 iteration 10 if the faintest
star in the group has a brightness less than 1.5 sigma above zero it is
eliminated. After iteration 15, 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.

ALLSTAR replaces the functionality of the GROUP, GRPSELECT, NSTAR and SUBSTAR
task. However the user has little control over the grouping process and does
not know at the end which stars were fit together. The grouping process is
dynamic, as the groups are recomputed after each iteration, and stars can be
fit and leave the group at any point after the fourth iteration. Therefore the
quality of the fits may vary over the image as a function of crowding in an
unknown way. However ALLSTAR is in most cases the routine of choice.  NSTAR
is the task of choice when a user wants to maintain 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 \fIallstarfile\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  xcenter  ycenter  mag  merr  msky  niter  sharpness  chi
	    pier  perr
.fi

Id is the id number of the star. 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> allstar dev$ypix default default default default default

        ... verify the prompts

        ... the results will appear in ypix.als.1 and ypix.arj.1

    da> pdump ypix.als.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> display ypix.sub.1 2

        ... note that the psf stars subtract reasonably well but other
            objects which are not stars don't
.fi


2. Repeat example 1 but refit the sky using an annulus with an inner sky
radius of 3.0 and an outer radius of 15.0.

.nf
    da> allstar dev$ypix default default default default default fitsky+ \
        sannulus=3.0 wsannulus=12.0

        ... verify the prompts

        ... the results will appear in ypix.als.2 and ypix.arj.2

    da> pdump ypix.als.2 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> display ypix.sub.2 2

        ... note that the psf stars subtract reasonably well but other
            objects which are not stars don't
.fi



3. Run allstar 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> allstar dev$ypix[150:450,150:450] default default default default \
        default wcsin=tv wcspsf=tv wcsout=tv

        ... answer the verify prompts

        ... fit the stars

        ... the results will appear in ypix.als.3 and ypix.arj.3

    da> display dev$ypix[150:450,150:450] 1

        ... display the image

    da> pdump ypix.als.3 xc,yc yes | tvmark 1 STDIN col=204

        ... mark the stars on the original image

    da> display ypix.sub.3 2

       ... display the subtracted image section

.fi


4. Run allstar exactly as in example 1 but submit the task to the background.
Turn off verify and verbose.

.nf
    da> allstar dev$ypix default default default default default verbose- \
        verify- &

        ... the results will appear in ypix.als.4 and ypix.arj.4
.fi


4. Run ALLSTAR exactly as in example 3 but turn caching off.

.nf
    da> allstar m92 m92.grp.1 m92.psf.1 default "" default verb+ veri- \
        cache- > allstar.out & 
.fi

.ih
TIME REQUIREMENTS
.ih
BUGS
.ih
SEE ALSO
datapars,daopars,peak,nstar
.endhelp