path: root/noao/obsutil/src/doc/starfocus.hlp

.help starfocus Nov01 noao.obsutil
.ih
NAME
starfocus -- Measure focus variations using stellar images
.ih
USAGE
starfocus images
.ih
PARAMETERS
.ls images
List of images.  The images may be either taken at a sequence
of focus values or be multiple shifted exposures at a sequence of
focus settings.
.le
.ls focus = "1x1"
If the parameter \fIfstep\fR is not set (a "" null string) then this
parameter is interpreted as either a list of focus values or an
image header keyword to one focus value per image.  A list may be an explicit
list of values, a range specification, or an @ file containing the values.
If there is only a single exposure per image then the focus list gives one
value per image while if there are multiple exposures per image the list
applies to the multiple exposures with the same values reused for other
images.  If the parameter \fIfstep\fR is given then this parameter is
interpreted as a single starting focus value and the focus step
defines the increment between subsequent single exposure images or
for the various exposures in a multiple exposure image.
.le
.ls fstep = ""
A focus increment value or an image header keyword to the focus increment.
.le

.ls nexposures = "1"
The number of exposures per image specified either as a value or as
an image header keyword.  A double step gap in a multiple
exposure sequence does not count as an exposure.
.le
.ls step = "30."
The step in pixels between exposures specified either as a value or
as an image header keyword.
.le
.ls direction = "-line" (-line|+line|-column|+column)
The direction of the exposure sequence in the image.  The values are
"-line" for successive object images appearing at smaller line numbers,
"+line" for objects appearing at larger line numbers, "-column" for
objects appearing at smaller column numbers, and "+column" for objects
appearing at larger column numbers.
.le
.ls gap = "end" (none|beginning|end)
Location of a double step gap in a sequence with the specified direction.
The available cases are "none" for an even sequence with no gap,
"beginning" where a double step is taken between the first and
the second exposure, and "end" where a double step is taken before
the last exposure.  Note that "beginning" and "end" are defined in
terms of the \fIdirection\fR parameter.
.le

.ls coords = "mark1" (center|mark1|markall)
Method by which the coordinates of objects to be measured are specified.
If "center" then a single object at the center of each image is measured.
If "mark1" then the \fIimagecur\fR parameter, typically the interactive
image display cursor, defines the coordinates of one or more objects in the
first image ending with a 'q' key value and then the same coordinates are
automatically used in subsequent images.  If "markall" then the
\fIimagecur\fR parameter defines the coordinates for objects in each image
ending with a 'q' key value.
.le
.ls wcs = "logical" (logical|physical|world)
Coordinate system for input coordinates.  When using image cursor input
this will always be "logical".  When using cursor input from a file this
could be "physical" or "world".
.le
.ls display = yes, frame = 1
Display the image or images as needed?  If yes the image display is checked
to see if the image is already in one of the display frames.  If it is not
the \fBdisplay\fR task is called to display the image in the frame
specified by the \fBframe\fR parameter.  All other display parameters are
taken from the current settings of the task.  This option requires that the
image display be active.  A value of no is typically used when an input
cursor file is used instead of the image display cursor.  An image display
need not be active in that case.
.le

.ls level = 0.5
The parameter used to quantify an object image size is the radius from the
image center enclosing the fraction of the total flux given by this
parameter.  If the value is greater than 1 it is treated as a percentage.
.le
.ls size = "FWHM" (Radius|FWHM|GFWHM|MFWHM)
There are four ways the PSF size may be shown in graphs and given in
the output.  These are:

.nf
    Radius - the radius enclosing the specified fraction of the flux
    FWHM   - a direct FWHM from the measured radial profile
    GFWHM  - the FWHM of the best fit Gaussian profile
    MFWHM  - the FWHM of the best fit Moffat profile
.fi

The labels in the graphs and output will be the value of this parameter
to distinguish the different types of size measurements.
.le
.ls beta = INDEF
For the Moffat profile fit (size = MFWHM) the exponent parameter may
be fixed at a specified value or left free to be determined from the
fit.  The exponent parameter is determined by the fit if \fIbeta\fR
task parameter is INDEF.
.le
.ls scale = 1.
Pixel scale in user units per pixel.  Usually the value is 1 to measure
sizes in pixels or the image pixel scale in arc seconds per pixel.
.le
.ls radius = 5., iterations = 2
Measurement radius in pixels and number of iterations on the radius.  The
enclosed flux profile is measured out to this radius.  This radius may be
adjusted if the \fIiteration\fR parameter is greater than 1.  In that case
after each iteration a new radius is computed from the previous FWHM
estimate to be the radius the equivalent gaussian enclosing 99.5% of the
light.  The purpose of this is so that if the initial PSF size of the image
need not be known.  However, the radius should then be larger than true
image size since the iterations best converge to smaller values.
.le
.ls sbuffer = 5, swidth = 5.
Sky buffer and sky width in pixels.  The buffer is added to the specified
measurement \fIradius\fR to define the inner radius for a circular sky
aperture.  The sky width is the width of the circular sky aperture.
.le
.ls saturation=INDEF, ignore_sat=no
Data values (prior to sky subtraction) to be considered saturated within
measurement radius.  A value of INDEF treats all pixels as unsaturated.  If
a measurement has saturated pixels there are two actions.  If
\fIignore_sat\fR=no then a warning is given but the measurement is saved
for use.  The object will also be indicated as saturated in the output
log.  If \fIignore_sat\fR=yes then a warning is given and the object is
discarded as if it was not measured.  In a focus sequence only the
saturated objects are discarded and not the whole sequence.
.le
.ls xcenter = INDEF, ycenter = INDEF
The optical field center of the image given in image pixel coordinates.
These values need not lie in the image.  If INDEF the center of the image
is used.  These values are used to make plots of size verse distance from
the field center for studies of radial variations.
.le
.ls logfile = "logfile"
File in which to record the final results.  If no log file is desired a
null string may be specified.
.le

.ls imagecur = ""
Image cursor input for the "mark1" and "markall" options.  If null then the
image dispaly cursor is used interactively.  If a file name is specified
then the coordinates come from this file.  The format of the file are lines
of x, y, id, and key.  Values of x an y alone may be used to select objects
and the single character 'q' (or the end of the file) may be used to end
the list.
.le
.ls graphcur = ""
Graphics cursor input.  If null then the standard graphics cursor
is used otherwise a standard cursor format file may be specified.
.le
.ih
CURSOR COMMANDS
When selecting objects with the image cursor the following commands are
available.

.nf
?  Page cursor command summary
g  Measure object and graph the results.
m  Measure object.
q  Quit object marking and go to next image.
   At the end of all images go to analysis of all measurements.

:show  Show current results.
.fi

When in the interactive graphics the following cursor commands are available.
All plots may not be available depending on the number of focus values and
the number of stars.

.nf
?  Page cursor command summary
a  Spatial plot at a single focus
b  Spatial plot of best focus values
d  Delete star nearest to cursor
e  Enclosed flux for stars at one focus and one star at all focus
f  Size and ellipticity vs focus for all data
i  Information about point nearest the cursor
m  Size and ellipticity vs relative magnitude at one focus
n  Normalize enclosed flux at x cursor position
o  Offset enclosed flux to by adjusting background
p  Radial profiles for stars at one focus and one star at all focus
q  Quit
r  Redraw
s  Toggle magnitude symbols in spatial plots
t  Size and ellipticity vs radius from field center at one focus
u  Undelete all deleted points
x  Delete nearest point, star, or focus (selected by query)
z  Zoom to a single measurement
<space> Step through different focus or stars in current plot type


:beta <val>     Beta parameter for Moffat fit
:level <val>	Level at which the size parameter is evaluated
:overplot <y|n> Overplot the profiles from the narrowest profile?
:radius <val>   Change profile radius
:show <file>	Page all information for the current set of objects
:size <type>	Size type (Radius|FWHM)
:scale <val>	Pixel scale for size values
:xcenter <val>	X field center for radius from field center plots
:ycenter <val>	Y field center for radius from field center plots

The profile radius may not exceed the initial value set by the task
parameter.
.fi
.ih
DESCRIPTION
This task measures the point-spread function (PSF) width of stars or other
unresolved objects in digital images.  The width is measured based on the
circular radius which encloses a specified fraction of the background
subtracted flux.  The details of this are described in the ALGORITHMS
section.  When a sequence of images or multiple exposures in a single image
are made with the focus varied the program provides an estimate of the best
focus and various views of how the PSF width varies with focus and position
in the image.  A single star may be measured at each focus or measurements
of multiple stars may be made and combined.  The task has three stages;
selecting objects and measuring the PSF width and other parameters, an
interactive graphical analysis, and a final output of the results to the
terminal and to a logfile.

If a saturation value is specified then all pixels within the specified
measurement radius are checked for saturation.  If any saturated pixels are
found a warning is given and \fIignore_sat\fR parameter may be used ot
ignore the measurement.  If not ignored the object will still be indicated
as saturated in the output log.  In a focus sequence only the saturated
objects are discarded and not the whole sequence.

The input images are specified by an image template list.  The list may
consist of explicit image names, wildcard templates, and @ files.  A
"focus" value or values is associated with each image; though this may be
any numeric quantity (integer or floating point) and not just a focus.  The
focus values may be specified in several ways.  If each image has a focus
value recorded in the image header, the keyword name may be specified.  If
the images consists of multiple exposures the \fIfstep\fR parameter would
specify a second image header keyword (or constant value) giving the
focus increment per exposure.  

The focus values may also be specified as a range list
as described in the help topic \fBranges\fR.  This consists of
individual values, ranges of values, a starting value and a step, and a
range with a step.  The elements of the list are separated by commas,
ranges are separated by hyphens, and a step is indicated by the character
'x'.  Long range lists, such as a list of individual focus values, may be
placed in a file and specified with the @<filename> convention.  The
assignment of a focus value from a list depends on whether the images
are single or multiple exposure as specified by the \fInexposure\fR
parameter.  Single exposure images are assigned focus values from the
list in the order in which the images and focus values are given.  If
the images are multiple exposure focus frames in which each offset exposure
has a different focus, the focus values from the list are assigned in
order to the multiple exposures and if there are multiple images the
assignments are repeated.

For a simple sequence of a starting focus value and focus increment,
either for multiple single exposure images or multiple exposure
images the \fIfocus\fR and \fIfstep\fR parameters by be used
togther as single values or image header keywords.  Note that if
\fIfstep\fR is specified then the focus parameter is NOT interpreted
as a list.

There are two common ways of doing focus sequences.  One is to take an
exposure at each focus value.  In this case the parameter \fInexposure\fR
is given the value 1.  The second is to take an image with multiple
exposures where the objects in the image are shifted between exposures and
the focus is changed.  In this case \fInexposure\fR is greater than 1 and
other parameters are used to specify the shift size and direction.  The
\fInexposure\fR parameter may be a number of an image header keyword.

Currently the task allows only multiple exposure shifts along either the
column or line dimension and the shifts must be the same between each
exposure except that there may be a double shift at either end of the
sequence.  The shift magnitude, in pixels, is specified as either a number
or image header keyword.  The shift direction is given by the
\fIdirection\fR parameter.  It is specified relative to the image; i.e. it
need not be the same as the physical shifts of the telescope or detector
but depends on how the image was created.  Steps in which the object
positions decrease in column or line are specified with a leading minus and
those which increase with a leading plus.  The step is specified as a
positive number of pixels between exposures.  Often a double shift is made
at the beginning or end of the sequence.  If this is done the \fIgap\fR
parameter is used to identify which end the gap is on.  Note that one may
change the sense of the exposure sequence from that used to make the focus
frame by properly adjust the direction, the gap, the focus list, and which
object is marked as the start of the sequence.

Identifying the object or objects to be measured may be accomplished in
several ways.  If a single object near the center of the image is to be
measured then the \fIcoords\fR parameter takes the value "center".  This
may be used with multiple exposure focus frames if the first exposure of
the object sequence is at the center.  When the "center" option is used
the \fIdisplay\fR and \fIimagecur\fR parameters are ignored.

If there are multiple objects or the desired object is not at the center of
the frame the object coordinates are entered with the \fIimagecur\fR
parameter.  This type of coordinate input is selected by specifying either
"mark1" or "markall" for the \fIcoords\fR parameter.  If the value is
"mark1" then the coordinates are entered for the first image and the same
values are automatically used for subsequent images.  If "markall" is
specified then the objects in each image are marked.

Normally the \fIimagecur\fR parameter would select the interactive image
display cursor though a standard cursor file could be used to make this
part noninteractive.  When the image display cursor is used either the
image must be displayed previously by the user, or the task may be allowed
to load the image display using the \fBdisplay\fR task by setting the
parameter \fIdisplay\fR to yes and \fIframe\fR to a display frame.  If yes
the image display must be active.  The task will look at the image names as
stored in the image display and only load the display if needed.

If one wants to enter a coordinate list rather than use the interactive
image cursor the list can consist of just the column and line coordinates
since the key will default to 'm'.  To finish the list either the end
of file may be encountered or a single 'q' may be given since the
coordinates are irrelevant.  For the "markall" option with multiple
images there would need to be a 'q' at the end of each object except
possibly the last.

When objects are marked interactively with the image cursor there
are a four keys which may be used as shown in the CURSOR COMMAND section.
The important distinction is between 'm' to mark and measure an
object and 'g' to mark, measure, and graph the results.  The former
accumulates the results until the end while the latter can give an
immediate result to be examined.  Unless only one object is marked
the 'g' key also accumulates the results for later graphical analysis.
It is important to note that the measurements are done as each
object is marked so there can be a significant delay before the
next object may be marked.

The quantities measured and the algorithms used are described in the
ALGORITHMS section.  Once all the objects have been measured an
interactive (unless only one object is measured) graphical presentation
of the measurements is entered.

When the task exits it prints the results to the terminal (STDOUT)
and also to the \fIlogfile\fR if one is specified.  The results may
also be previewed during the execution of the task with the
":show" command.  The results begin with a banner and the overall
estimate of the best focus and PSF size.  If there are multiple
stars measured at multiple focus values the best focus estimate
for each star is printed.  The star is identified by it's position
(the starting position for multiple exposure images).  The average
size, relative magnitude, and best focus estimate are then given.
If there are multiple focus values the average of the
PSF size over all objects at each focus are listed next.
Finally, the individual measurements are given.  The columns
give the image name, the column and line position, the relative
magnitude, the focus value, the PSF size as either the enclosed
flux radius or the FWHM, the ellipticity, the position angle, and
an indication of saturation.
.ih
ALGORITHMS
The PSF of an object is characterized using a radially symmetric
enclosed flux profile.  First the center of the object is determined from
an initial rough coordinate.  The center is computed from marginal profiles
which are sums of lines or columns centered at the initial coordinate and
with a width given by the sum of the \fIradius\fR, \fIsbuffer\fR, and
\fIswidth\fR parameters.  The mean of the marginal profile is determined
and then the centroid of the profile above this is computed.  The centroids
from the two marginal profiles define a new object center.  These steps of
forming the marginal profiles centered at the estimated object position and
then computing the centroids are repeated until the centroids converge or
three iterations have been completed.

Next a background is determined from the mode of the pixel values in the
sky annulus defined by the object center and \fIradius\fR, \fIsbuffer\fR,
and \fIswidth\fR parameters.  The pixel values in the annulus are sorted
and the mode is estimated as the point of minimum slope in this sorted
array using a width of 5% of the number of points.  If there are multiple
regions with the same minimum slope the lowest pixel value is used.

The background subtracted enclosed flux profile is determined next.
To obtain subpixel precision and to give accurate estimates for small
widths relative to the pixel sampling, several things are done.
First interpolation between pixels is done using a cubic spline surface.
The radii measured are in subpixel steps.  To accommodate small and
large PSF widths (and \fIradius\fR parameters) the steps are nonuniform
with very fine steps at small radii (steps of 0.05 pixels in the
central pixel) and coarser steps at larger radii (beyond 9 pixels
the steps are one pixel) out to the specified \fIradius\fR.  Similarly each
pixel is subsampled finely near the center and more coarsely at larger
distances from the object center.  Each subpixel value, as obtained by
interpolation, is background subtracted and added into the enclosed flux
profile.  Even with subpixel sampling there is still a point where a
subpixel straddles a particular radius.  At those points the fraction of
the subpixel dimension in radius falling within the radius being measured
is used as the fraction of the pixel value accumulated.

Because of errors in the background determination due to noise and
contaminating objects it is sometimes the case that the enclosed flux
is not completely monotonic with radius.  The enclosed flux
normalization, and the magnitude used in plots and reported in
results, is the maximum of the enclosed flux profile even if it
occurs at a radius less than the maximum radius.  It is possible
to change the normalization and subtract or add a background correction
interactively.

Because a very narrow PSF will produce significant errors in the cubic
spline interpolation due to the steepness and rapid variation in the pixel
values near the peak, the Gaussian profile with FWHM that encloses the same
80% of the flux is computed as:

    FWHM(80%) = 2 * r(80%) * sqrt (ln(2) / (ln (1/.2)))

If this is less than five pixels the Gaussian model is subtracted from the
data.  The Gaussian normalization is chosed to perfectly subtract the
central pixel.  The resulting subtraction will not be perfect but the
residual data will have much lower amplitudes and variations.  A spline
interpolation is fit to this residual data and the enclosed flux profile is
recomputed in exactly the same manner as previously except the subpixel
intensity is evaluated as the sum of the analytic Gaussian and the
interpolation to the residual data.

The Gaussian normalization is chosed to perfectly subtract the central
pixel.  The resulting subtraction will not be perfect but the residual data
will have much lower amplitudes and variations.  A spline interpolation is
fit to this residual data and the enclosed flux profile is recomputed in
exactly the same manner as previously except the subpixel intensity is
evaluated as the sum of the analytic Gaussian and the interpolation to the
residual data.  This technique yields accurate FWHM for simulated Gaussian
PSFs down to at least a FWHM of 1 pixel.

In addition to the enclosed flux profile, an estimate of the radially
symmetric intensity profile is computed from the enclosed flux profile.
This is based on the equation

.nf
    F(R) = integral from 0 to R { P(r) r dr }
.fi

where F(R) is the enclosed flux at radius R and P(r) is the intensity per
unit area profile.  Thus the derivative of F(R) divided by R gives an
estimate of P(R).

Cubic spline interpolation functions are fit to the normalized enclosed
flux profile and the intensity profile.  These are used to find the radius
enclosing any specified fraction of the flux and to find the direct FWHM of
the intensity profile.  These are output when \fIsize\fR is "Radius" or
"FWHM" respectively.

In addition to enclosed flux radius and direct FWHM size measurements
there are also two size measurements based on fitting analytic profiles.
A Gaussian profile and a Moffat profile are fit to the final enclosed flux
profile to the points with enclosed flux less than 80%.  The limit is
included to minimize the effects of poor background values and to make the
profile fit be representative of the core of the PSF profile.  These profiles
are fit whether or not the selected \fIsize\fR requires it.  This is done
for simplicity and to allow quickly changing the size estimate with the
":size" command.

The intensity profile functions (with unit peak) are:

.nf
    I(r) = exp (-0.5 * (r/sigma)**2)			Gaussian
    I(r) = (1 + (r/alpha)**2)) ** (-beta)		Moffat
.fi

with parameters sigma, alpha, and beta.  The normalized enclosed flux
profiles, which is what is actually fit, are then:

.nf
    F(r) = 1 - exp (-0.5 * (r/sigma)**2)		Gaussian
    F(r) = 1 - (1 + (r/alpha)**2)) ** (1-beta)		Moffat
.fi

The fits determine the parameters sigma or alpha and beta (if a
beta value is not specified by the users).  The reported FWHM values
are given by:

.nf
    GFWHM = 2 * sigma * sqrt (2 * ln (2))		Gaussian
    MFWHM = 2 * alpha * sqrt (2 ** (1/beta) - 1)	Moffat
.fi

were the units are adjusted by the pixel scale factor.

In addition to the four size measurements there are several additional
quantities which are determined.  
Other quantities which are computed are the relative magnitude,
ellipticity, and position angle.  The magnitude of an individual
measurement is obtained from the maximum flux attained in the enclosed
flux profile computation.  Though the normalization and background may be
adjusted interactively later, the magnitude is not changed from the
initial determination.  The relative magnitude of an object is then
computed as

.nf
    rel. mag. = -2.5 * log (object flux / maximum star flux)
.fi

The maximum star magnitude over all stars is used as the zero point for the
relative magnitudes (hence it is possible for an individual object relative
magnitude to be less than zero).

The ellipticity and positional angle of an object are derived from the
second central intensity weighted moments.  The moments are:

.nf
	Mxx = sum { (I - B) * x * x } / sum { I - B }
	Myy = sum { (I - B) * y * y } / sum { I - B }
	Mxy = sum { (I - B) * x * y } / sum { I - B }
.fi

where x and y are the distances from the object center, I is
the pixel intensity and B is the background intensity.  The sum is
over the same subpixels used in the enclosed flux evaluation with
intensities above an isophote which is slightly above the background.
The ellipticity and position angles are derived from the moments
by the equations:

.nf
	M1 = (Mxx - Myy) / (Mxx + Myy)
	M2 = 2 * Mxy / (Mxx + Myy)
	ellip = (M1**2 + M2**2) ** 1/2
	pa = atan (M2 / M1) / 2
.fi

where ** is the exponentiation operator and atan is the arc tangent
operator.  The ellipticity is essentially (a - b) / (a + b) where a
is a major axis scale length and b is a minor axis scale length.  A
value of zero corresponds to a circular image.  The position angle is
given in degrees counterclockwise from the x or column axis.

The overall size when there are multiple stars is estimated by averaging
the individual sizes weighted by the flux of the star as described above.
Thus, when there are multiple stars, the brighter stars are given greater
weight in the average size.  This average size is what is given in the
banner for the graphs and in the printed output.

One of the quantities computed for the graphical analysis is the
FWHM of a Gaussian or Moffat profile that encloses the same flux
as the measured object as a function of the level.  The equation are:

.nf
   FWHM = 2 * r(level) * sqrt (ln(2.) / ln (1/(1-level)))  Gaussian

   FWHM = 2 * r(level) * sqrt (2**(1/beta)-1) /
	  sqrt ((1-level)**(1/(1-beta))-1)		   Moffat
.fi

where r(level) is the radius that encloses "level" fraction of the total
flux.  ln is the natural logarithm and sqrt is the square root.  The beta
value is either the user specified value or the value determined by fitting
the enclosed flux profile.

This function of level will be a constant if the object profile matches
the Gaussian or Moffat profile.  Deviations from a constant show
the departures from the profile model.  The Moffat profile used in making
the graphs except for the case where the \fIsize\fR is GFWHM.

The task estimates a value for the best focus and PSF size at that focus
for each star.  This is done by finding the minimum size at each focus
value (in case there are multiple measurements of the same star at the same
focus), sorting them by focus value, finding the focus value with the
minimum size, and parabolically interpolating using the nearest focus
values on each side.  When the minimum size occurs at either extreme of the
focus range the best focus is at that extreme focus; in other words there
is no extrapolation outside the range of focus values.

The overall best focus and size when there are multiple stars are estimated
by averaging the best focus values for each star weighted by the
average flux of the star as described above.  Thus, when there are
multiple stars, the brighter stars are given greater weight in the
overall best average focus and size.  This best average focus and
size are what are given in the banner for the graphs and in the
printed output.

The log output also includes an average PSF size for all measurements
at a single focus value.  This average is also weighted by the
average flux of each star at that focus.
.ih
INTERACTIVE GRAPHICS MODE
The graphics part of \fBstarfocus\fR consists of a number of different
plots selected by cursor keys.  The available plots depend on the
number of stars and the number of focus values.  The various plots
and the keys which select them are summarized below.

.nf
a  Spatial plot at a single focus
b  Spatial plot of best focus values
e  Enclosed flux for stars at one focus and one star at all focus
f  Size and ellipticity vs focus for all data
m  Size and ellipticity vs relative magnitude at one focus
p  Radial profiles for stars at one focus and one star at all focus
t  Size and ellipticity vs radius from field center at one focus
z  Zoom to a single measurement
.fi

If there is only one object at a single focus the only available plot is
the 'z' or zoom plot.  This has three graphs; a graph of the normalized
enclosed flux verses scaled radius, a graph of the intensity profile verses
scaled radius, and equivalent Moffat/Gaussian full width at half maximum verses
enclosed flux fraction.  The latter two graphs are derived from the
normalized enclosed flux profile as described in the ALGORITHMS section.
In the graphs the measured points are shown with symbols, a smooth curve is
drawn through the symbols and dashed lines indicate the measurement level
and enclosed flux radius at that level.

Overplotted on these graphs are the Moffat profile fit or the
Gaussian profile fit when \fIsize\fR is GFWHM.

The zoom plot is always available from any other plot.  The cursor position
when the 'z' key is typed selects a particular object measurement.
This plot is also the one presented with the 'g' key when marking objects for
single exposure images.  In that case the graphs are drawn followed by
a return to image cursor mode.

There are three types of symbol plots showing the measured PSF size (either
enclosed flux radius or FWHM) and ellipticity.  These plot the measurements
verses focus ('f' key), relative magnitude ('m' key), and radius from the
field center ('t' key).  The focus plot includes all measurements and shows
dashed lines at the estimated best focus and size.  This plot is only
available when there are multiple focus values.  It is the initial plot in
this case for both the 'g' key when there are multiple exposures and when
the graphical analysis stage is entered after defining the objects.

The magnitude and field radius plots are only available when there are
multiple objects measured.  The relative magnitude used for a particular
measurement is the average magnitude of the star over all focus values and
not the individual object magnitude.  The data shown is for a single focus
value.  The focus value is selected when typing 'm' or 't' by the focus of
the nearest object to the cursor in the preceding plot.  When in one of
these plots, other focus values may be shown by typing <space>, the space
bar.  This scrolls through the focus values.  The field center for the
field radius graph may be changed interactively using the ":xcenter" and
":ycenter" commands.

Grids of enclosed flux vs. radius, intensity profile vs. radius, and
FWHM vs. enclosed flux fraction are shown with the 'e', 'p', and
'g' keys respectively.  If there are multiple objects at multiple focus
values there are two grids. One grid is all objects at one focus and the
other is one object at all focuses.  The titles identify the object (by
location) and focus.  The profiles in the grids have no axis labels or
ticks.  Within each box are the coordinates of the object or the focus
value, and the PSF size are given.  When there is only one object at
multiple focus values or multiple objects at only one focus value then
there is only one grid and a graph of a one object.  The single object
graph does have axis labels and  ticks.

In the grids there is one profile which is highlighted (by a second
box or by a color border).  The highlighted profile is the current
object.  To change the current object, and thus change either
the contents of the other grid or the single object graphed, one
can type the space bar to advance to the next object or
use the cursor and the 'e', 'p', or 'g' key again.  Other keys
will select another plot using the object nearest the cursor to select
a focus or object.

Any of the graphs with enclosed flux or intensity profiles vs radius may
have the profiles of the object with the smallest size overplotted.  The
overplot has a dashed line, a different color on color graphics devices,
and no symbols marking the measurement points.  The overplots may be
enabled or disabled with the ":overplot" command.  Initially it is
disabled.

The final plots give a spatial representation.  These require more than one
object.  The 'a' key gives a spatial plot at a single focus.  The space bar
can be used to advance to another focus.  This plot has a central graph of
column and line coordinates with symbols indicating the position of an
object.  The objects are marked with a circle (when plotted at unit aspect
ratio) whose size is proportional to the measured PSF size.  In addition an
optional asterisk symbol with size proportional to the relative
brightness of the object may be plotted.  This symbol is toggled with the
's' key.  On color displays the circles may have two colors, one if object
size is above the average best size and the other if the size is below the
best size.  The purpose of this is to look for a spatial pattern in the
smallest PSF sizes.

Adjacent to the central graph are graphs with column or line as one
coordinate and radius or ellipticity as the other.  The symbols
are the same as described previously.  These plots can show spatial
gradients in the PSF size and shape across the image.

The 'b' key gives a spatial plot of the best focus estimates for each
object.  This requires multiple objects and multiple focus values.
As discussed previously, given more than one focus a best focus
value and size at the best focus is computed by parabolic interpolation.
This plot type shows the object positions in the same way as the 'a'
plot except that the radius is the estimated best radius.  Instead
of adjacent ellipticity plots there are plots of best focus verses
columns and lines.  Also the two colors in the symbol plots are
selected depending on whether the object's best focus estimate is
above or below the overall best focus estimate.  This allows seeing
spatial trends in the best focus.

In addition to the keys which select plots there are other keys which
do various things.  These are summarized below.

.nf
?  Page cursor command summary
d  Delete star nearest to cursor
i  Information about point nearest the cursor
n  Normalize enclosed flux at x cursor position
o  Offset enclosed flux by adjusting background
q  Quit
r  Redraw
s  Toggle magnitude symbols in spatial plots
u  Undelete all deleted points
x  Delete nearest point, star, or focus (selected by query)
<space> Step through different focus or stars in current plot type
.fi

The help, redraw, and quit keys are provide the standard functions.
The 's' and space keys were described previously.  The 'i' key
locates the nearest object to the cursor in whatever plot is shown and
prints one line of information about the object on the graphics device
status area.

The 'd' key deletes the star nearest the cursor in whatever plot is
currently displayed.  Deleting a star deletes all measurements of an object
at different focus values.  To delete all objects from an image, all focus
values for one star (the same as 'd'), all objects at one focus, or a
single measurement, the 'x' key is used.  Typing this key produces a query
for which type of deletion and the user responds with 'i', 's', 'f', or
'p'.  The most common use of this is to delete all objects at the extreme
focus values.  Deleted measurements do not appear in any subsequent
graphics, are excluded from all computations, and are not output in the
results.  The 'u' key allows one to recover deleted measurements.  This
undeletes all previously deleted data.

Due to various sources of error the sky value may be wrong causing
the enclosed flux profile to not converge properly but instead
decreases beyond some point (overestimated sky) or linearly
increases with radius (underestimated sky).  This affects the size
measurement by raising or lowering the normalization and altering
the shape of the enclosed flux profile.  The 'n' and 'o' keys allow
fudging the enclosed flux profiles.  These keys apply only in
the zoom plot of the enclosed flux profile or the case where
a single enclosed flux profile is shown with the 'e' key; in other
words plots of the enclosed flux which have axes labels.

The 'n' key normalizes the enclosed flux profile at the point
set by the x position of the cursor.  The 'o' key increases or
decreases the background estimate to bring curve up or down to
the point specified by the cursor.  The effect of this is to
add or subtract a quadratic function since the number of pixels
at a particular radius varies as the square of the radius.
To restore the original profile, type 'n' or 'o' at a radius
less than zero.

The colon commands, shown below, allow checking or changing parameters
initially set by the task parameters, toggling the overplotting of the
smallest PSF profiles, and showing the current results.  The overplotting
option and the contents of the results displayed by :show were described
previously.

.nf
:beta <val>     Beta parameter for Moffat fits
:level <val>	Level at which the size parameter is evaluated
:overplot <y|n> Overplot the profiles from the narrowest profile?
:radius <val>   Change profile radius
:show <file>	Page all information for the current set of objects
:size <type>	Size type (Radius|FWHM)
:scale <val>	Pixel scale for size values
:xcenter <val>	X field center for radius from field center plots
:ycenter <val>	Y field center for radius from field center plots
.fi

The important values which one might want to change interactively are
the measurement level and the profile radius.  The measurement level
directly affects the results reported.  When it is changed the sizes
of all object PSFs are recomputed and the displayed plots and title
information are updated.  The profile radius is the
maximum radius shown in plots and used to set the enclosed flux normalization.
It does not affect the object centering or sky region definition and
evaluation which are done when the image data is accessed.  Because
the objects are not remeasured from the image data the radius may
not be made larger than the radius defined by the task parameter though
it may be decreased and then increased again.
.ih
EXAMPLES
1.  A multiple exposure frame is taken with 7 exposures of a bright
star, each exposure shifted by 50 pixels to lower line positions, with a
double gap at the end.  The exposure pattern is typical of Kitt Peak and
the default values for the direction and gap position are applicable.  The
default focus value numbering and measurements in pixels are also used.

.nf
cl> starfocus focus1 nexp=7 step=50
<The image is displayed and the image cursor activated>
<The bright star is marked with 'm'>
<Marking is finished with 'q'>
<A graph of FWHM vs focus index is shown>
<Exit with 'q'>
NOAO/IRAF IRAFV2.10.3 valdes@puppis Wed 16:09:39 30-Jun-93
  Best focus of 4.12073 with FWHM (at 50% level) of 3.04

   Image  Column    Line     Mag   Focus    FWHM   Ellip      PA SAT
  focus1  536.63  804.03    0.07      1.  13.878    0.06     -11
	  535.94  753.28   -0.11      2.   8.579    0.09      89
	  535.38  703.96   -0.08      3.   5.184    0.11     -87
	  537.12  655.36   -0.02      4.   3.066    0.07     -77
	  534.20  604.59    0.00      5.   4.360    0.10      74
	  534.41  554.99   -0.00      6.   9.799    0.09     -35
	  534.83  456.08    0.16      7.  12.579    0.13     -10
.fi

The estimated best focus is between the 4th and 5th focus setting
and the best focus FWHM is 3.04 pixels.

Note that in more recent Kitt Peak multiple exposure focus images the
starting focus value, the focus step, the number of exposures, and
the shift are recorded in the image header with the keywords
FOCSTART, FOCSTEP, FOCNEXPO, and FOCSHIFT.  Thus the task parameters
\fIfocus\fR, \fIfstep\fR, \fInexposures\fR, and \fIstep\fR may be
set to those names.  However, rather than use \fBstarfocus\fR
one would use the more convenient \fBkpnofocus\fR.
.ih
SEE ALSO
.nf
imexamine, implot, kpnofocus, pprofile, pradprof, psfmeasure, radlist,
radplt, radprof, ranges, specfocus, splot
.endhelp