nstar image groupfile psfimage nstarfile rejfile
image
The list of images containing the stellar groups to be fit.
groupfile
The list of input photometry files, or directory, containing the
group membership information and initial estimates for the positions
and magnitudes of the stars to be measured.
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.
Otherise groupfile must specify one photometry file for each input
image in image.
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 table.
psfimage
The list of images, or directory, containing the PSF computed by
the DAOPHOT PSF task.
If psfimage is "default", "dir$default", or a directory specification,
then NSTAR will look for an image with the name image.psf.? where
? is the highest existing version number.
Otherwise psfimage must specify one PSF image for each input image.
nstarfile
The list of output photometry files.
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.
Otherwise nstarfile must specify one output file for each image in
image.
Nstarfile is text database if the DAOPHOT package parameter text
is "yes", an STSDAS table database if it is "no".
rejfile
The list of output rejected photometry files.
If rejfile is null (""), results for all the stars in groupfile
are written to nstarfile, otherwise only the stars which were
successfully fit are written to nstarfile and the remainder
are written to rejfile.
If rejfile is "default", "dir$default", or a directory specification
then NSTAR will write an output file with the name image.nrj.?
where ? is the next available version number.
Otherwise rejfile must specify one output photometry file
for every image in image.
Rejfile is a text database if the DAOPHOT package parameter text
is "yes", an STSDAS table database if it is "no".
datapars =
The name of the file containing the DAOPHOT data dependent parameters.
If datapars is null ("") then the default parameter set in the user's
uparm directory is used.
daopars =
The name of the file containing the DAPHOT fitting parameters.
If daopars is null ("") then the default parameter set in the user's
uparm directory is used.
verbose = )_.verbose
Print messages about the progress of the NSTAR task?
Verbose may be set to the
daophot package parameter (the default), "yes", or "no".
verify = )_.verify
Verify critical NSTAR task parameters?
Verify may be set to the
daophot package parameter (the default), "yes", or "no".
update = )_.update
Update critical NSTAR task parameters if verify is "yes"?
Update may be set to the
daophot package parameter (the default), "yes", or "no".
NSTAR computes x and y centers and magnitudes for all the stellar groups groupfile, by fitting the PSF psfimage to the data in image. NSTAR reads the group membership information along with initial estimates of the centers and magnitudes, and the sky values from the photometry file groupfile. Groupfile 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 nstarfile 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 rejfile is not null (""), only stars that are successfully fit are written to nstarfile, and the remainder are written to rejfile. Otherwise all the stars are written to nstarfile. Nstarfile and rejfile are text databases if the DAOPHOT package parameter text is "yes", an STSDAS table database if it is "no".
By default NSTAR computes new centers for all the stars in groupfile. However if the DAOPARS parameter recenter is "no", NSTAR assumes that the x and y centers in groupfile 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 groupfile for all the stars in the group. If groupsky 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 fitksy 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 fitrad 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 datamin and datamax are included in the fit. Most users set datamin and datamax 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 fitrad / scale are included in the fit for each star. Fitrad is located in the DAOPARS task and scale 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 fitrad 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 fitrad 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. Fitrad must be sufficiently large to include at least three pixels with non-zero weights in the fit for each star. Values of fitrad 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 readnoise and epadu, and the flat-fielding and profile interpolation errors specified by the DAOPARS flaterr and proferr 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 image which extends approximately psfrad / scale + 1 pixels wide past the limiting values of the x and y coordinates of the stars in the group. Psfrad is the PSF radius specified in the DAOPARS task, and scale is the image scale specified by the DATAPARS task. Psfrad may be less than or equal to but can never exceed the value of the image header parameter "PSFRAD" in psfimage. Psfrad should always be several pixels larger than fitrad 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 maxiter 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 readnoise and epadu, and the DAOPARS parameters flaterr and proferr 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 maxgroup parameter in the DAOPARS task. Larger groups may run into numerical precision problems during the fits. Users should exercise care in increasing the maxgroup 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 readnoise and gain parameters and the DAOPARS parameter flaterr and proferr. 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.
If verbose = yes, a single line is output to the terminal for each star fit or rejected. Full output is written to nstarfile and rejfile. 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.
id group xcenter ycenter mag merr msky niter sharpness chi pier perr
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.
If no errors occur during the fitting process then pier is 0. Non-zero values of pier flag the following error conditions.
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
1. Fit the PSF to a list stars in a crowded field near M92. After the fit subtract the fitted stars from the image.
da> nstar m92 m92.grp.1 m92.psf.1 default "" verb+ veri+
da> substar m92 m92.nst.1 m92.psf.1 default veri-
2. Repeat example 1 but write the stars that were not successfully fit to a separate file.
da> nstar m92 m92.grp.1 m92.psf.1 default default verb+ veri+
da> substar m92 m92.nst.1 m92.psf.1 default veri-
3. Run NSTAR exactly as in example 1 but submit the task to the background saving all the verbose output in a file called nstar.out.
da> nstar m92 m92.grp.1 m92.psf.1 default "" verb+ veri- > nstar.out &
4. Run NSTAR exactly as in example 1, remove all the stars with INDEF valued magnitudes from the output and rerun NSTAR.
da> nstar m92 m92.grp.1 m92.psf.1 default "" verb+ veri+
da> pselect m92.nst.1 m92.nst.2 "MAG != INDEF"
da> nstar m92 m92.nst.2 m92.psf.1 default "" verb+ veri+
datapars, daopars, peak, allstar,