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

.help specfocus Nov01 noao.obsutil
.ih
NAME
specfocus -- Determine spectral focus and alignment variations
.ih
USAGE
specfocus images
.ih
PARAMETERS
.ls images
List of 1D or 2D focus images.  Typically the input is a list of raw
2D CCD images of arc slit spectra.  The 1D image input is provided to
allow use of extraction techniques beyond those provided by this task.
.le
.ls focus = ""
List of focus identification values to be associated with each input image
or an image header keyword containing the values.  The list may be an
explicit list of values, a range specification, an @ file containing the
values, or an image header keyword.  If none of these is given the
identification values are simple index values in the order of the input
images.  A range specification has the forms A, AxC, A-BxC where A is a
starting value, B is an ending value, and C is an increment.
.le
.ls corwidth = 20.
Correlation width in pixels.
.le
.ls level = 0.5
Percent or fraction of the correlation peak at which to measure focus
widths.  The default is 50% or full width at half maximum.
.le
.ls shifts = yes
Compute dispersion shifts across the dispersion when there are multiple
samples?  If yes and there are multiple samples across the dispersion
(\fIndisp\fR > 1), pixel shifts relative to the central sample are
determine by crosscorrelation.
.le

.ls dispaxis = 2
Dispersion axis for 2D images.  The image header keyword DISPAXIS has
precedence over this value.
.le
.ls nspectra = 1, ndisp = 1
The number of spectral samples across the dispersion
and the number of subpieces along the dispersion to divide the spectra
into.  If \fInspectra\fR is greater than one then information about
variations across the dispersion will be determined and if \fIndisp\fR is
greater than 1 information about variations along the dispersion will be
determined.  \fINspectra\fR applies only to 2D images.  For 1D spectra in
multispec format each line is used as a separate sample.
.le
.ls slit1 = INDEF, slit2 = INDEF
The lower and upper edges of the slit (or data region) in pixel
coordinates (lines or columns) across the dispersion axis.  A value
of INDEF specifies the image edges.
.le

.ls logfile = "logfile"
File in which to record the results.  If no file is specified no log
output is produced.
.le
.ih
CURSOR COMMANDS
All keys select an image and a sample (one of the \fIndisp\fR samples along
the dispersion and one of the \fInspectra\fR samples across the dispersion)
which is then generally highlighted.

.nf
   ?  Help summary
   b  Best focus at each sample summary graphs
   d  Delete image, sample, or point
   p  Profiles at one sample for all images and all samples for one image
   q  Quit
   r  Redraw
   s  Spectra at one sample for all images and all samples for one image
   u  Undelete spectrum, sample, or point
   w  Profile widths verses focus and distribution of widths
   z  Zoom on a single sample showing correlation profile and spectrum
   <space>  Status line output for selected image and sample
.fi

.ih
DESCRIPTION
This task estimates the dispersion width of spectral lines in sequences of
arc spectra taken at different focus settings (or with some other parameter
varied).  The widths can be measured at different spatial and dispersion
positions, called "samples", on the detector.  The width estimates are
recorded and displayed graphically to investigate dependencies and
determine appropriate settings for the spectrograph setup.  The task may
also measure dispersion shifts when multiple spectral samples are
specified.  This task does not measure the focus point-spread-function
width across the dispersion.

The input images are specified with an image template list.  The list may
consist of explicit image names, wildcard templates, and @ files.  A
"focus" value is associated with each image.  This may be any numeric
quantity (integer or floating point).  The focus values may be specified in
several ways.  If no value is given then index numbers are assigned to
the images in the order in which they appear in the image list.  A range
list may be specified 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.  Finally, a parameter in the image header may be used for the
focus values by simply specifying the parameter name.

Two dimensional long slit images are summed into one or more one
dimensional spectra across the dispersion.  The dispersion axis is defined
either by the image header parameter DISPAXIS or the \fIdispaxis\fR task
parameter with the image header parameter having precedence.  The range of
lines or columns across the dispersion to be used is specified by the
parameters \fIslit1\fR and \fIslit2\fR.  If specified as INDEF then the
image limits are used.  This range is then divided into the number of
spectra given by the parameter \fInspectra\fR.  Use of more than one
spectrum across the dispersion allows investigation of variations along the
slit.  In addition, if the parameter \fIshifts\fR is set the spectrum
nearest the center is used as a reference against which shifts in the
dispersion positions of the features in the other spectra are determined by
crosscorrelation.

The conversion of two dimensional spectra to one dimensional spectra may
also be performed separately using the tasks in the \fBapextract\fR
package.  This would be done typically for multifiber or echelle format
spectra.  If the two dimensional spectra have been extracted to one
dimensional spectra in this way the task ignores the dispersion axis and
number of spectra parameters.  The data limits (\fIslit1\fR and
\fIslit2\fR) are still used to select a range of lines in  "multispec"
format images.  The \fIshifts\fR parameter also applies when there are
multiple spectra per image.  However, it does not make sense in the case of
echelle spectra and so it should be set to no in that case.

In addition to dividing the spatial axis into a number of spectra the
dispersion axis may also be divided into a set of subspectra.  The number
of divisions is specified by the \fIndisp\fR parameter which applies to
both long slit and 1D extracted spectra.  When the dispersion axis is
divided into more than one sample, the dependence of the dispersion widths
and shifts along the dispersion may be investigated.

Each spectral sample has a low order continuum subtracted using a
noninteractive iterative rejection algorithm to exclude the spectral
lines.  This technique is described further under the topic
\fIcontinuum\fR.  The continuum subtracted spectrum is then tapered with a
cosine bell function and autocorrelated.  The length of the taper and the
range of shifts for the correlation is set by the \fIcorwidth\fR
parameter.  This parameter should be only slightly bigger than the expected
feature widths to prevent correlations between different spectral lines.
The correlation profile is offset to zero at the edges of the profile and
normalized to unity at the profile center.  The profiles may be viewed as
described below.

If there is more than one spatial sample the central spectrum is also
crosscorrelated against the other spectra at the same dispersion
sample.  The crosscorrelation is computed in exactly the same way as
the autocorrelation.  The crosscorrelation profiles are only used for
determining shifts between the two samples and are not used in the
width determinations.

A cubic spline interpolator is fit to the profiles and this interpolation
function is used to determined the profile width and center.  The width is
measured at a point given by the \fIlevel\fR parameter relative to the
profile peak.  It may be specified as a fraction of the peak if it is less
than one or a percentage of the peak if it is greater than one.  The
default value of 0.5 selects the full width at half maximum.  The
autocorrelation width is divided by the square root of two to yield an
estimate of the width of the spectral features in the spectrum in units of
pixels.

Having computed the width and shift for each input image at each sample,
the "best focus" values (focus, width, and shift) are estimated for each
sample.  As discussed later, it is possible to exclude some samples
from this calculation by deleting them graphically.
First the images with the smallest measured width at each distinct
focus are selected since it is possible to input more than one image at the
same focus.  The selected images are sorted by focus value and the image
with the smallest width is found.  If that image has the lowest or highest
focus (which will always be the case if there are only one or two images)
then the best focus, width, and shift are those measured for that image.
If there are three or more focus values and the minimum width focus image
is not an endpoint then parabolic interpolation is used to find the minimum
width.  The focus at this minimum width is the "best focus".
The dispersion shift is the parabolic interpolation of the shifts at
the best focus.  The "average best focus" values are then the average of
the "best focus" values over all samples.

After computing the correlation profiles, the profile widths and shifts,
and the best focus values, an interactive graphics mode is entered.  This
is described in detail below.  The graphics mode is exited with the 'q'
key.  At this point the results are written to the standard output (usually
the terminal) and to a logfile if one is specified.  The output begins with
a banner identifying the task, version of IRAF, the user, and the date and
time.  The next line gives the best average focus and width.  This banner
also appears in all plots.  Then each image is listed with the focus value
and average width (over all samples).  Finally the image with the smallest
average width is identified and tables showing the width and shifts (if
computed) at each sample position are printed.  If there is only one sample
then the tables are not output.

INTERACTIVE GRAPHICS MODE

There are five types of plot formats which are selected with the 'b', 'p',
's', 'w', and 'z' keys.  The available formats and their content are
modified depending on the number of images and the number of samples.  If
there is only one image or one sample per image some of the plot formats
are not available.  If there are a large number of images or a large number
of samples the content of the plot formats may be abbreviated for
legibility.

In all plots there is a concept of the current image and the current
sample.  In general there is an indication, usually a box, of which image
and sample is the current one.  The current image and sample are
changed by pointing at a particular point, box, circle, or symbol for that
image and sample and typing a key.

The 'b' key produces summary graphs of the best focus values (as described
above) at each sample position.  There must be more than one image and more
than one sample (either along or across the dispersion or both).  This is
the initial plot shown when this condition is satisfied.  The central graph,
which is always drawn, represents the best focus (smallest) width at each
sample by circles of size proportional to the width.  The position of the
circle indicates the central line and column of the sample.  If there are
multiple samples across the dispersion and the \fIshifts\fR parameter is
set then little vectors are also drawn from the center of the circle in the
direction of the shift and with length proportional to the shift.  If there
are 5 or fewer samples in each dimension the values of the best focus and
the width and shift (if computed and nonzero) at that focus, are printed on
the graph next to the circles.  If there are more samples this information
may be obtained by pointing at the sample and typing the space key.

In addition to the spatial graph there may be graphs along the line or column
axes.  These graphs again show the widths as circles but one axis is either
the line or column and the other axis is either the best focus value or the
shift.  The focus graph marks the best average focus (over all samples) by
a dashed line and a solid line connects the mean focus at each column or
line.  The focus graphs will only appear if there is more than one sample
along a particular image axis.  The shift graphs will only appear if the
shifts are computed (\fIshifts\fR parameter is yes) and there is more than
one sample along a particular dimension.  Lines are drawn at zero shift and
connecting the mean shift at each point along the spatial axis.  Note that
there is always a point at zero shift which is the reference sample.

The best focus graphs are the exception in showing a current image and
sample.  When changing to one of the other plots based on a current image
and sample the circle from the central spatial graph nearest the cursor is
used (note that the other focus and shift graphs are ignored).  The sample
is defined by it's spatial position and the image is the one with
focus closest to the best focus value of that sample.

The 'w' key produces a graph showing the sample widths as a function of
focus value.  There must be more than one image and more than one sample
for this type of graph.  The top graph is a symbol plot of width verses
focus.  The symbols are crosses except for the current image which is shown
with pluses.  The current sample is highlighted with a box.  Also shown is
a long dashed line connecting the widths for the current sample at each
focus value and short dashed lines showing the best average focus and
width.

The lower portion of the 'w' key are graphs showing the
widths as circles with size proportional to the width and position
corresponding to the spatial position of the sample in the image.  If there
are more than 5 samples in either dimension the graph is for the current
image.  Otherwise there is a box for each image with the focus value
(provided there are not too many images) indicated.  The circles are
arranged as they would be spatially in columns and rows.  The samples
closest to the best focus are indicated by pluses.  This allows seeing
where the best focus values cluster.  The current image and sample are
indicated by highlighting boxes.

The 'p' key produces graphs of the autocorrelation profiles.  This also
requires more than one image and more than one sample.  The top graph shows
the profiles of all images at a particular sample and the bottom graph shows
the profiles of all samples at a particular image.  The bottom sample boxes
are arranged in columns and rows in the same way the samples are
distributed in the image.  The current image and current sample are
highlighted by a box.

The profiles are drawn with a solid line using the interpolator function
and the actual pixel lags are indicated with pluses.  The profiles are
drawn shifted by the amount computed from the crosscorrelation.
Note that the shift is added to the autocorrelation profile
and the crosscorrelation profile is not what is plotted.  The zero shift
position is indicated by a vertical line.  If there are less than 25 boxes
the boxes are labeled by the width, shift (if nonzero), and focus.

The 's' key plot is similar to the 'p' key plot but shows the spectra
rather than the profiles.  The top graphs are the spectra of each image at
a particular sample and the bottom graphs are the spectra of each sample
for a particular image.  The current image and sample are highlighted by a
box.

The 'z' key graphs the autocorrelation profile and the spectrum
of a single sample.  This graph provides scales which are not
provided with the 'p' and 's' graphs.  If there is only one image
and one sample then this is the only plot available.

It is possible to exclude some of the samples from the calculation
of the best focus and best average focus values.  This is done by
deleting them using the 'd' key.  When using the 'd' key you must
specify the sample to be deleted in one of the graphs.  You are
then asked if only that sample (point) is to be deleted, if all
samples from that image are to be deleted, or if the same sample
from all images is to be deleted.  The deleted data is no longer
shown explicitly but the space occupied by the data is still present
so that the data may be included again by typing the 'u' undelete
key.  When the task is exited with the 'q' key the printed and
logged results will have the deleted data excluded.

The remaining cursor keys do the following.  The '?' key gives a
summary of the cursor keys.  The 'r' key redraws the current plot.
The space key prints information about the current sample.  This
is mostly used when there are too many images or samples to annotate
the graphs with the focus, width, and shift.  Finally the 'q'
key quits the task.
.ih
EXAMPLES
1.  A series of 2D focus images is obtained with focus values
starting at 400 in steps of -50.  The slit is between columns 50
and 130.  There are 3 samples across the dispersion and 3 along
the dispersion.

.nf
    cl> lpar specfocus
	   images = "@imlist"       List of images
	   (focus = "400x-50")     Focus values
	(corwidth = 20)             Correlation width
	   (level = 0.5)            Percent or fraction of peak
	  (shifts = yes)            Compute shifts across the disp?\n
	(dispaxis = 2)              Dispersion axis (long slit only)
	(nspectra = 3)              Number of spec samples (ls only)
	   (ndisp = 3)              Number of dispersion samples
	   (slit1 = 50)             Lower slit edge
	   (slit2 = 130)            Upper slit edge\n
	 (logfile = "logfile")      Logfile
	    (mode = "ql")
    cl> specfocus @imlist
    <Interactive graphics which is exited with the 'q' key>
    SPECFOCUS: NOAO/IRAF V2.10EXPORT valdes Thu 19:41:41 17-Sep-92
      Best avg focus at 206.6584 with avg width of 2.91 at 50% of peak

      -- Average Over All Samples

				     Image  Focus  Width
				jdv011.imh   100.   3.78
				jdv010.imh   150.   3.28
				jdv009.imh   200.   2.95
				jdv008.imh   250.   3.17
				jdv007.imh   300.   3.41
				jdv006.imh   350.   3.74
				jdv005.imh   400.   4.16

      -- Image jdv009.imh at Focus 200. --


	    Width at 50% of Peak:

			 Columns
			   50-76      77-103    104-130 
	       Lines  +---------------------------------
	       2-267  |    2.93       2.58       2.74   
	     268-533  |    3.17       2.76       2.89   
	     534-799  |    3.77       2.23       3.50   

	    Position Shifts Relative To Central Sample:

			 Columns
			   50-76      77-103    104-130 
	       Lines  +---------------------------------
	       2-267  |    0.68       0.00       0.18   
	     268-533  |    0.64       0.00       0.13   
	     534-799  |    0.92       0.00       0.16   
.fi
.ih
SEE ALSO
imexamine, implot, ranges, splot
.endhelp