path: root/noao/onedspec/doc/splot.hlp

.help splot Jul95 noao.onedspec
.ih
NAME
splot -- plot and analyze spectra
.ih
USAGE
splot images [line [band]]
.ih
PARAMETERS
.ls images
List of images (spectra) to plot.  If the image is 2D or 3D the line
and band parameters are used.  Successive images are plotted
following each 'q' cursor command.  One may use an image section
to select a desired column, line, or band but the full image will
be in memory and any updates to the spectrum will be part of the
full image.
.le
.ls line, band
The image line/aperture and band to plot in two or three dimensional
images.  For multiaperture spectra the aperture specified by the line
parameter is first sought and if not found the specified image line is
selected.  For other two dimensional images, such as long slit spectra, the
line parameter specifies a line or column.  Note that if
the line and band parameters are specified on the command line it will not
be possible to change them interactively.
.le
.ls units = ""
Dispersion coordinate units for the plot.  If the spectra have known units,
currently this is generally Angstroms, the units may be converted
to other units for plotting as specified by this task parameter.
If this parameter is the null string and the world coordinate system
attribute "units_display" is defined then that will
be used.  If both this task parameters and "units_display" are not
given then the spectrum dispersion units will be used.
The units
may also be changed interactively.  See the units section of the
\fBpackage\fR help for a further description and available units.
.le
.ls options = "auto" [auto,zero,xydraw,histogram,nosysid,wcreset,flip,overplot]
A list of zero or more, possibly abbreviated, options.  The options can
also be toggled with colon commands.  The currently defined options are
"auto", "zero", "xydraw", "histogram", "nosysid", "wreset", "flip", and
"overplot".  Option "auto" automatically replots the graph whenever changes
are made.  Otherwise the graph is replotted with keystrokes 'c' or 'r'.
Option "zero" makes the initial minimum y of the graphs occur at zero.
Otherwise the limits are set automatically from the range of the data or
the \fIymin\fR parameter.  Option "xydraw" changes the 'x' draw key to use
both x and y cursor values for drawing rather than the nearest pixel value
for the y value.  Option "histogram" plots the spectra in a histogram style
rather than connecting the pixel centers.  Option "nosysid" excludes the
system banner from the graph title.  Option "wreset" resets the graph
limits to those specified by the \fIxmin, xmax, ymin, ymax\fR parameters
whenever a new spectrum is plotted.  The "flip" option selects that
initially the spectra be plotted with decreasing wavelengths.  The options
may be queried and changed interactively.  The "overplot" options overplots
all graphs and a screen erase only occurs with the redraw key.
.le
.ls xmin = INDEF, xmax = INDEF, ymin = INDEF, ymax = INDEF
The default limits for the initial graph.  If INDEF then the limit is
determined from the range of the data (autoscaling).  These values can
be changed interactively with 'w' window key options or the cursor commands
":/xwindow" and ":/ywindow" (see \fBgtools\fR).
.le
.ls save_file = "splot.log"
The file to contain any results generated by the equivalent width or
deblending functions.  Results are added to this file until the file is
deleted.  If the filename is null (""), then no results are saved.
.le
.ls graphics = "stdgraph"
Output graphics device: one of "stdgraph", "stdplot", "stdvdm", or device
name.
.le
.ls cursor = ""
Graphics cursor input.  When null the standard cursor is used otherwise
the specified file is used.
.le

The following parameters are used for error estimates in the 'd',
'k', and 'e' key measurements.  See the ERROR ESTIMATES section for a
discussion of the error estimates.
.ls nerrsample = 0
Number of samples for the error computation.  A value less than 10 turns
off the error computation.  A value of ~10 does a rough error analysis, a
value of ~50 does a reasonable error analysis, and a value >100 does a
detailed error analysis.  The larger this value the longer the analysis
takes.
.le
.ls sigma0 = INDEF, invgain = INDEF
The pixel sigmas are modeled by the formula:

.nf
    sigma**2 = sigma0**2 + invgain * I
.fi

where I is the pixel value and "**2" means the square of the quantity.  If
either parameter is specified as INDEF or with a value less than zero then
no sigma estimates are made and so no error estimates for the measured
parameters are made.
.le

The following parameters are for the interactive curve fitting function
entered with the 't' key.  This function is usually used for continuum
fitting.  The values of these parameters are updated during the fitting.
See \fBicfit\fR for additional details on interactive curve fitting.
.ls function = "spline3"
Function to be fit to the spectra.  The functions are
"legendre" (legendre polynomial), "chebyshev" (chebyshev polynomial),
"spline1" (linear spline), and "spline3" (cubic spline).  The functions
may be abbreviated.
.le
.ls order = 1
The order of the polynomials or the number of spline pieces.
.le
.ls low_reject = 2., high_reject = 4.
Rejection limits below and above the fit in units of the residual sigma.
Unequal limits are used to reject spectral lines on one side of the continuum
during continuum fitting.
.le
.ls niterate = 10
Number of rejection iterations.
.le
.ls grow = 1.
When a pixel is rejected, pixels within this distance of the rejected pixel
are also rejected.
.le
.ls markrej = yes
Mark rejected points?  If there are many rejected points it might be
desired to not mark rejected points.
.le

The following parameters are used to overplot standard star fluxes with
the 'y' key.  See \fBstandard\fR for more information about these parameters.
.ls star_name
Query parameter for the standard star fluxes to be overplotted.
Unrecognized names or a "?" will print a list of the available stars
in the specified calibration directory.
.le
.ls mag
The magnitude of the observed star in the band given by the
\fImagband\fR parameter.  If the magnitude is not in the same band as
the blackbody calibration file then the magnitude may be converted to
the calibration band provided the "params.dat" file containing relative
magnitudes between the two bands is in the calibration directory
.le
.ls magband
The standard band name for the input magnitude.  This should generally
be the same band as the blackbody calibration file.  If it is
not the magnitude will be converted to the calibration band.
.le
.ls teff
The effective temperature (deg K) or the spectral type of the star being
calibrated.  If a spectral type is specified a "params.dat" file must exist
in the calibration directory.  The spectral types are specified in the same
form as in the "params.dat" file.  For the standard blackbody calibration
directory the spectral types are specified as A0I, A0III, or A0V, where A
can be any letter OBAFGKM, the single digit subclass is between 0 and 9,
and the luminousity class is one of I, III, or V.  If no luminousity class
is given it defaults to dwarf.
.le
.ls caldir = ")_.caldir"
The standard star calibration directory.  The default value redirects the
value to the parameter of the same name in the package parameters.
.le
.ls fnuzero = 3.68e-20
The absolute flux per unit frequency at a magnitude of zero used to
to convert the calibration magnitudes to absolute flux.
.le

The following parameters are used for queries in response to particular
keystrokes.
.ls next_image
In response to 'g' (get next image) this parameter specifies the image.
.le
.ls new_image
In response to 'i' (write current spectrum) this parameter specifies the
name of a new image to create or existing image to overwrite.
.le
.ls overwrite = no
Overwrite an existing output image?  If set to yes it is possible to write
back into the input spectrum or to some other existing image.  Otherwise
the user is queried again for a new image name.
.le
.ls spec2
When adding, subtracting, multiplying, or dividing by a second spectrum
('+', '-', '*', '/' keys in the 'f' mode) this parameter is used to get
the name of the second spectrum.
.le
.ls constant
When adding or multiplying by a constant ('p' or 'm' keys in the 'f' mode)
the parameter is used to get the constant.
.le
.ls wavelength
This parameter is used to get a dispersion coordinate value during deblending or
when changing the dispersion coordinates with 'u'.
.le
.ls linelist
During deblending this parameter is used to get a list of line positions,
peak values, profile types, and widths.
.le
.ls wstart, wend, dw
In response to 'p' (convert to a linear wavelength scale) these parameters
specify the starting wavelength, ending wavelength, and wavelength per pixel.
.le
.ls boxsize
In response to 's' (smooth) this parameter specifies the box size in pixels
to be used for the boxcar smooth.  The value must be odd.  If an even
value is specified the next larger odd value is actually used.
.le
.ih
DESCRIPTION
\fBSplot\fR provides an interactive facility to display and analyze
spectra.  See also \fBbplot\fR for a version of this task useful for making
many plots noninteractively.  Each spectrum in the image list is displayed
successively.  To quit the current image and go on to the next the 'q'
cursor command is used.  If an image is two-dimensional, such as with
multiple aperture or long slit spectra, the aperture or image column/line
to be displayed is needed.  If the image is three-dimensional, such as with
the extra information produced by \fBapextract\fR, the band is needed.
These parameters are queried unless specified on the command line.  If
given on the command line it will not be possible to change them
interactively.

The plots are made on the specfied graphics device which is usually to
the graphics terminal.  The initial plot limits are set with the parameters
\fIxmin, xmax, ymin\fR, and \fIymax\fR.  If a limit is INDEF then that limit
is determined from the range of the data.  The "zero" option may also
be set in the \fIoptions\fR parameter to set the lower intensity limit
to zero.  Other options that may be set to control the initial plot
are to exclude the system identification banner, and to select a
histogram line type instead of connecting the pixel centers.
The dispersion units used in the plot are set by the \fIunits\fR
parameter.  This allows converting to units other than those in which the
dispersion coordinates are defined in the spectra.

The \fIoption\fR parameter, mentioned in the previous paragraph, is a
a list of zero or more options.  As previously noted, some of the options
control the initial appearance of the plots.  The "auto" option determines
how frequently plots are redrawn.  For slow terminals or via modems one
might wish to minimize the redrawing.  The default, however, is to redraw
when changes are made.  The "xydraw" parameter is specific to the 'x'
key.

After the initial graph is made an interactive cursor loop is entered.
The \fIcursor\fR parameter may be reset to read from a file but generally
the graphics device cursor is read.  The cursor loop takes single
keystroke commands and typed in commands begun with a colon, called
colon commands.  These commands are described below and a summary of
the commands may be produced interactively with the '?' key or
a scrolling help on the status line with the '/' key.

Modifications to the spectra being analyzed may be saved using the 'i' key
in a new, the current, or other existing spectra.  A new image is created
as a new copy of the current spectrum and so if the current spectrum is
part of a multiple spectrum image (including a long slit spectrum) the
other spectra are copied.  If other spectra in the same image are then
modified and saved use the overwrite option to replace then in the new
output image.  If the output spectrum already exists then the
\fIoverwrite\fR flag must be set to allow modifying the data.  This
includes the case when the output spectrum is the same as the input
spectrum.  The only odd case here is when the input spectrum is one
dimensional and the output spectrum is two dimensional.  In this case the
user is queried for the line to be written.

The other form of output, apart from that produced on the terminal, are
measurements of equivalent widths, and other analysis functions.  This
information will be recorded in the \fIsave_file\fR if specified.

The following keystrokes are active in addition to the normal IRAF
cursor facilities (available with ":.help"):

.ls ?
Page help information.
.le
.ls /
Cycle through short status line help.
.le
.ls <space>
The space bar prints the cursor position and value of the nearest
pixel.
.le
.ls a
Expand and autoscale to the data range between two cursor positions.
See also 'w', and 'z'.  Selecting no range, that is the two
cursor positions the same, produces an autoscale of the whole spectrum.
.le
.ls b
Set the plot base level to zero rather than autoscaling.
.le
.ls c
Clear all windowing and redraw the full current spectrum.  This redraws the
spectrum and cancels any effects of the 'a', 'z', and 'w' keys.  The 'r'
key is used to redraw the spectrum with the current windowing.
.le
.ls d
Mark two continuum points and fit (deblend) multiple line profiles.
The center, continuum at the center, core intensity, integrated flux,
equivalent width, FWHMs for each profile are printed and saved
in the log file.  See 'k' for fitting a single profile and
'-' to subtract the fitted profiles.
.le
.ls e
Measure equivalent width by marking two continuum points around the line
to be measured.  The linear continuum is subtracted and the flux is
determined by simply summing the pixels with partial pixels at the ends.
Returned values are the line center, continuum at the region center,
flux above or below the continuum, and the equivalent width.
.le
.ls f
Enter arithmetic function mode. This mode allows arithmetic functions to be
applied to the spectrum. The pixel values are modified according to the
function request and may be saved as a new spectrum with the 'i'
command.  Operations with a second spectrum are done in wavelength
space and the second spectrum is automatically resampled if necessary.
If one spectrum is longer than the other, only the smaller number of
pixels are affected.  To exit this mode type 'q'.

The following keystrokes are available in the function mode.  Binary
operations with a constant or a second spectrum produce a query for the
constant value or spectrum name.
.ls a
Absolute value
.le
.ls d
Power of base 10 (inverse log base 10)
.le
.ls e
Power of base e (inverse log base e)
.le
.ls i
Inverse/reciprocal (values equal to zero are set to 0.0 in the inverse)
.le
.ls l
Log base 10 (values less than or equal to 0.0 are set to -0.5)
.le
.ls m
Multiply by a constant (constant is queried)
.le
.ls n
Log base e (values less than or equal to 0.0 are set to -0.5)
.le
.ls p
Add by a constant (constant is queried)
.le
.ls q
Quit Function mode
.le
.ls s
Square root (values less than 0.0 are set to 0.0)
.le
.ls +
Add another spectrum
.le
.ls -3 -
Subtract another spectrum
.le
.ls *
Multiply by another spectrum
.le
.ls /
Divide by another spectrum
.le
.le
.ls g
Get another spectrum. The current spectrum is replaced by the new spectrum.
The aperture/line and band are queried is necessary.
.le
.ls h
Measure equivalent widths assuming a gaussian profile with the width
measured at a specified point.  Note that this is not a gaussian fit (see
'k' to fit a gaussian)!  The gaussian profile determined here may be
subtracted with the '-' key.  A second cursor key is requested with one of
the following values:
.ls a
Mark the continuum level at the line center and use the LEFT half width
at the half flux point.
.le
.ls b
Mark the continuum level at the line center and use the RIGHT half width
at the half flux point.
.le
.ls c
Mark the continuum level at the line center and use the FULL width
at the half flux point.
.le
.ls l
Mark a flux level at the line center relative to a normalized continuum
and use the LEFT width at that flux point.
.le
.ls r
Mark a flux level at the line center relative to a normalized continuum
and use the RIGHT width at that flux point.
.le
.ls k
Mark a flux level at the line center relative to a normalized continuum
and use the FULL width at that flux point.
.le
.le
.ls i
Write the current spectrum out to a new or existing image.  The image
name is queried and overwriting must be confirmed.
.le
.ls j
Set the value of the nearest pixel to the x cursor to the y cursor position.
.le
.ls k + (g, l or v)
Mark two continuum points and fit a single line profile.  The second key
selects the type of profile: g for gaussian, l for lorentzian, and v for
voigt.  Any other second key defaults to gaussian.  The center, continuum
at the center, core intensity, integrated flux, equivalent width, and FWHMs
are printed and saved in the log file.  See 'd' for fitting multiple
profiles and '-' to subtract the fit.
.le
.ls l
Convert to flux per unit wavelength (f-lambda). The spectrum is assumed
to be flux calibrated in flux per unit frequency (f-nu).  See also 'n'.
.le
.ls m
Compute the mean, RMS, and signal-to-noise over a region marked with two
x cursor positions.
.le
.ls n
Convert to flux per unit frequency (f-nu). The spectrum is assumed
to be flux calibrated in flux per unit wavelength (f-lambda).  See also 'l'.
.le
.ls o
Set overplot flag.  The next plot will overplot the current plot.
Normally this key is immediately followed by one of 'g', '#', '%', '(', or ')'.
The ":overplot" colon command and overplot parameter option may be
used to set overplotting to be permanently on.
.le
.ls p
Define a linear wavelength scale.  The user is queried for a starting
wavelength and an ending wavelength.  If either (though not both)
are specified as INDEF a dispersion is queried for and used to compute
an endpoint.  A wavelength scale set this way will be used for
other spectra which are not dispersion corrected.
.le
.ls q
Quit and go on to next input spectrum.  After the last spectrum exit.
.le
.ls r
Redraw the spectrum with the current windowing.  To redraw the full
spectrum and cancel any windowing use the 'c' key.
.le
.ls s
Smooth via a boxcar.  The user is prompted for the box size.
.le
.ls t
Fit a function to the spectrum using the ICFIT mode.  Typically
interactive rejection is used to exclude spectra lines from the fit
in order to fit a smooth continuum.  A second keystroke
selects what to do with the fit.
.ls /
Normalize by the fit.  When fitting the continuum this continuum
normalizes the spectrum.
.le
.ls -3 -
Subtract the fit.  When fitting the continuum this continuum subtracts
the spectrum.
.le
.ls f
Replace the spectrum by the fit.
.le
.ls c
Clean the spectrum by replacing any rejected points by the fit.
.le
.ls n
Do the fitting but leave the spectrum unchanged (a NOP on the spectrum).
This is useful to play with the spectrum using the capabilities of ICFIT.
.le
.ls q
Quit and don't do any fitting.  The spectrum is not modified.
.le
.le
.ls u
Adjust the user coordinate scale.  There are three options, 'd' mark a
position with the cursor and doppler shift it to a specified value,
'z' mark a position with the cursor and zeropoint shift it to a specified
value, or 'l' mark two postions and enter two values to define a linear
(in wavelength) dispersion scale.  The units used for input are those
currently displayed.  A wavelength scale set this way will be used for
other spectra which are not dispersion corrected.
.le
.ls v
Toggle to a velocity scale using the position of the cursor as the
velocity origin and back.
.le
.ls w
Window the graph.  For further help type '?' to the "window:" prompt or
see help under \fBgtools\fR.  To cancel the windowing use 'a'.
.le
.ls x
"Etch-a-sketch" mode. Straight lines are drawn between successive
positions of the cursor. Requires 2 cursor settings in x.  The nearest pixels
are used as the endpoints.  To draw a line between arbitrary y values first
use 'j' to adjust the endpoints or set the "xydraw" option.
.le
.ls y
Overplot standard star values from a calibration file.
.le
.ls z
Zoom the graph by a factor of 2 in x.
.le
.ls (
In multiaperture spectra go to the spectrum in the preceding image line.
If there is only one line go to the spectrum in the preceding band.
.le
.ls )
In multiaperture spectra go to the spectrum in the following image line.
If there is only one line go to the spectrum in the following band.
.le
.ls #
Get a different line in multiaperture spectra or two dimensional images.
The aperture/line/column is queried.
.le
.ls %
Get a different band in a three dimensional image.
.le
.ls $
Switch between physical pixel coordinates and world (dispersion) coordinates.
.le
.ls -4 -
Subtract the fits generated by the 'd' (deblend), 'k' (single profile fit),
and 'h' (gaussian of specified width).  The region to be subtracted is
marked with two cursor positions.
.le
.ls -4 ','
Shift the graph window to the left.
.le
.ls .
Shift the graph window to the right.
.le
.ls I
Force a fatal error interupt to leave the graph.  This is used because
the normal interupt character is ignored in graphics mode.
.le

.ls :show
Page the full output of the previous deblend and equivalent width
measurements.
.le
.ls :log
Enable logging of measurements to the file specified by the parameter
\fIsave_file\fR.  When the program is first entered logging is enabled
(provided a log file is specified).  There is no way to change the file
name from within the program.
.le
.ls :nolog
Disable logging of measurements.
.le
.ls :dispaxis <val>
Show or change dispersion axis for 2D images.
.le
.ls :nsum <val>
Show or change summing for 2D images.
.le
.ls :units <value>
Change the coordinate units in the plot.  See below for more information.
.le
.ls :# <comment>
Add comment to logfile.
.le
.ls Labels:
.ls :label <label> <format>
Add a label at the cursor position.
.le
.ls :mabove <label> <format>
Add a tick mark and label above the spectrum at the cursor position.
.le
.ls :mbelow <label> <format>
Add a tick mark and label below the spectrum at the cursor position.
.le

The label must be quoted if it contains blanks.  A label beginning
with % (i.e. %.2f) is treated as a format for the x cursor position.
The optional format is a gtext string (see help on "cursors").
The labels are not remembered between redraws.
.le

.ls :auto [yes|no]
Enable/disable autodraw option
.le
.ls :zero [yes|no]
Enable/disable zero baseline option
.le
.ls :xydraw [yes|no]
Enable/disable xydraw option
.le
.ls :hist [yes|no]
Enable/disable histogram line type option
.le
.ls :nosysid [yes|no]
Enable/disable system ID option
.le
.ls :wreset [yes|no]
Enable/disable window reset for new spectra option
.le
.ls :flip [yes|no]
Enable/disable the flipped coordinates option
.le
.ls :overplot [yes|no]
Enable/disable the permanent overplot option
.le


.ls :/help
Get help on GTOOLS options.
.le
.ls :.help
Get help on standard cursor mode options
.le
.ih
PROFILE FITTING AND DEBLENDING
The single profile ('k') and multiple profile deblending ('d') commands fit
gaussian, lorentzian, and voigt line profiles with a linear background.
The single profile fit, 'k' key, is a special case of the multiple profile
fitting designed to be simple to use.  Two cursor positions define the
region to be fit and a fixed linear continuum.  The second key is used to
select the type of profile to fit with 'g' for gaussian, 'l' for
lorentzian, and 'v' for voigt.  Any other second key will default to a
gaussian profile.  The profile center, peak strength, and width(s) are then
determined and the results are printed on the status line and in the log
file.  The meaning of these quantities is described later.  The fit is also
overplotted and may be subtracted from the spectrum subsequently with
the '-' key.

The more complex deblending function, 'd' key, defines the fitting region
and initial linear continuum in the same way with two cursor positions.
The continuum may be included in the fitting as an option.  The lines to be
fit are entered with the cursor near the line center ('g' for gaussian, 'l'
for lorentzian, 'v' for voigt), by typing the wavelengths ('t'), or read
from a file ('f').  The latter two methods are useful if the wavelengths of
the lines are known accurately and if fits restricting the absolute or
relative positions of the lines will be used.  The 't' key is
restricted to gaussian fits only.

The 'f' key asks for a line list file.  The format of this file has
one or more columns.  The columns are the wavelength, the peak value
(relative to the continuum with negative values being absorption),
the profile type (gaussian, lorentzian, or voigt), and the
gaussian and/or lorentzian FWHM.  End columns may be missing
or INDEF values may be used to have values be approximated.
Below are examples of the file line formats

.nf
	wavelength
	wavelength peak
	wavelength peak (gaussian|lorenzian|voigt)
	wavelength peak gaussian gfwhm
	wavelength peak lorentzian lfwhm
	wavelength peak voigt gfwhm
	wavelength peak voigt gfwhm lfwhm

	1234.5			<- Wavelength only
	1234.5 -100		<- Wavelength and peak
	1234.5 INDEF v		<- Wavelength and profile type
	1234.5 INDEF g 12	<- Wavelength and gaussian FWHM
.fi

where peak is the peak value, gfwhm is the gaussian FWHM, and lfwhm is
the lorentzian FWHM.  This format is the same as used by \fBfitprofs\fR
and also by \fBartdata.mk1dspec\fR (except in the latter case the
peak is normalized to a continuum of 1).

There are four queries made to define the set of parameters to be fit or
constrained.  The positions may be held "fixed" at their input values,
allowed to shift by a "single" offset from the input values, or "all"
positions may be fit independently.  The widths may be
constrained to a "single" value or "all" fit independently.  The linear
background may be included in the fit or kept fixed at that input using the
cursor.

As noted above, sometimes the absolute or relative wavelengths of the lines
are known a priori and this information may be entered by typing the
wavelengths explicitly using the 't' option or read from a file using the
'f' option during marking.  In this case one should fix or fit a single
shift for the position.  The latter may be useful if the lines are known
but there is a measurable doppler shift.

After the fit, the modeled lines are overplotted.  The line center,
flux, equivalent width, and full width half maxima are printed on the
status line for the first line.  The values for the other lines and
the RMS of the fit may be examined by scrolling the status line
using the '+', '-', and 'r' keys.  To continue enter 'q'.

The fitting may be repeated with different options until exited with 'q'.
For each line in the blend the line center, continuum intensity at the
line center, the core intensity above or below the continuum, the
FWHM for the gaussian and lorentzian parts, the flux above or below the continuum, and the
equivalent width are recorded in the log file.  All these parameters
except the continuum are based on the fitted analytic profiles.
Thus, even though the fitted region may not extend into the wings of a line
the equivalent width measurements include the wings in the fitted profile.
For direct integration of the flux use the 'e' key.

The fitted model may be subtracted from the data (after exiting the
deblending function) using the '-' (minus) keystroke to delimit the region
for which the subtraction is to be performed. This allows you to fit a
portion of a line which may be contaminated by a blend and then subtract
away the entire line to examine the remaining components.

The fitting uses an interactive algorithm based on the Levenberg-Marquardt
method.  The iterations attempt to improve the fit by varying the parameters
along the gradient of improvement in the chi square.  This method requires
that the initial values for the parameters be close enough that the
gradient leads to the correct solution rather than an incorrect local
minimum in the chi square.  The initial values are determined as follows:

.nf
    1.  If the lines are input from a data file then those values
	in the file are used.  Missing information is determined
	as below.
    2.  The line centers are those specified by the user
	either by marking with the cursor, entering the wavelenths,
	for read from a file.
    3.  The initial widths are obtained by dividing the width of
	the marked fitting region by the number of lines and then
	dividing this width by a factor depending on the profile
	type.
    4.  The initial peak intensities are the data values at the
	given line centers with the marked continuum subtracted.
.fi

Note that each time a new fitting option is specified the initial parameters
are those from the previous fits.
Thus the results do depend on the history of previous fits until the
fitting is exited.
Within each fit an iteration of parameters is performed as
described next.

The iteration is more likely to fail if one initially attempts to fit too
many parameters simultaneously.  A constrained approach to the solution
is obtained by iterating starting with a few parameters and then adding
more parameters as the solution approaches the true chi square minimum.
This is done by using the solutions from the more constrained options
as the starting point for the less constrained options.  In particular,
the positions and a single width are fit first with fixed background.
Then multiple widths and the background are added.

To conclude, here are some general comments.  The most restrictive
(fixed positions and single width(s)) will give odd results if the initial
positions are not close to the true centers.  The most general
(simultaneous positions, widths, and background) can also lead to
incorrect results by using unphysically different widths to make one
line very narrow and another very broad in an attempt to fit very
blended lines.  The algorithm works well when the lines are not
severely blended and the shapes of the lines are close to the profile
type.
.ih
CENTROID, FLUX, AND EQUIVALENT WIDTH DETERMINATIONS
There are currently five techniques in SPLOT to measure equivalent widths
and other line profile parameters. The simplest (conceptually) is by
integration of the pixel values between two marked pixels. This is
invoked  with the 'e' keystroke.  The user marks the two edges of the line
at the continuum.  The measured line center, contiuum value, line flux, and
equivalent width are given by:

.nf
	center = sum (w(i) * (I(i)-C(i))**3/2) / sum ((I(i)-C(i))**3/2)
	continuum = C(midpoint)
	flux = sum ((I(i)-C(i)) * (w(i2) - w(i1)) / (i2 - i2)
	eq. width = sum (1 - I(i)/C(i))
.fi

where w(i) is the wavelength of pixel i,  i1 and i2 are the nearest integer
pixel limits of the integrated wavelength range, I(i) is the data value of
pixel i, C(i) is the continuum at pixel (i), and the sum is over the marked
range of pixels.  The continuum is a linear function between the two points
marked.  The factor mulitplying the continuum subtracted pixel values
in the flux calculation is the wavelength interval per pixel so that
the flux integration is done in wavelength units.  (See the discussion
at the end of this section concerning flux units).

The most complex method for computing line profile parameters is performed
by the profile fitting and deblending commands which compute a non-linear
least-squares fit to the line(s).  These are invoked with the 'd' or 'k'
keystroke.  These were described in detail previously.

The fourth and fifth methods, selected with the 'h' key, determine the
equivalent width from a gaussian profile defined by a constant continuum
level "cont", a core depth "core", and the width of the line "dw" at some
intermediate level "Iw".

.nf
     I(w) = cont + core * exp (-0.5*((w-center)/sigma)**2)
     sigma = dw / 2 / sqrt (2 * ln (core/Iw))
     fwhm = 2.355 * sigma
     flux = core * sigma * sqrt (2*pi)
     eq. width = abs (flux) / cont
.fi

where w is wavelength.

For ease of use with a large number of lines only one cursor position is
used to mark the center of the line and one flux level.  Note that both
the x any y cursor positions are read simultaneously.  From the x cursor
position the line center and core intensity are determined.  The region around
the specified line position is searched for a minimum or maximum and a
parabola is fit to better define the extremum.

The two methods based on the simple gaussian profile model differ in how
they use the y cursor position and what part of the line is used.  After
typing 'h' one selects the method and whether to use the left, right, or
both sides of the line by a second keystroke.  The 'l', 'r', and 'k' keys
require a continuum level of one.  The y cursor position defines where the
width of the line is determined.  The 'a', 'b', and 'c' keys use the y
cursor position to define the continuum and the line width is determined at
the point half way between the line core and the continuum.  In both cases
the width at the appropriate level is determined by the interception of the
y level with the data using linear interpolation between pixels.  The
one-sided measurements use the half-width on the appropriate side and
the two-sided measurements use the full-width.

The adopted gaussian line profile is drawn over the spectrum and the
horizontal and vertical lines show the measured line width and the depth of
the line center from the continuum.  This model may also be subtracted
from the spectrum using the '-' key.

The major advantages of these methods are that only a single cursor setting
(both the x and y positions are used) is required and they are fast.  The
'l', 'r', and 'k' keys give more flexibility in adjusting the width of the
gaussian line at the expense or requiring that the spectrum be normalized
to a unit continuum.  The 'a', 'b', and 'c' keys allow measurements at any
continuum level at the expense of only using the half flux level to
determine the gaussian line width.

All these methods print and record in the log file the line center,
continuum intensity at the line center, the flux, and the equivalent
width.  For the 'e' key the flux is directly integrated while for the other
methods the fitted gaussian is integrated.  In addition, for the profile
fitting methods the core intensity above or below the continuum, and the
FWHMs are also printed.  A zero value is record for the gaussian or
lorentzian width if the value is not determined by profile fit.  A brief
line of data for each measurement is printed on the graphics status line.
To get the full output and the output from previous measurements use the
command ":show".  This pages the output on the text output which may
involve erasing the graphics.

The integrated fluxes for all the methods  are in the same units as the
intensities and the integration is done in the same units as the
plotted scale.  It is the user's responsibility to keep track of the flux
units.  As a caution, if the data is in flux per unit frequency, say
ergs/cm2/sec/hz, and the dispersion in Angstroms then the integrated
flux will not be in the usual units but will be A-ergs/cm2/sec/hz.
For flux in wavelength units, ergs/cm2/sec/A and the dispersion scale
in Angstroms the integrated flux will be correct; i.e. ergs/cm2/sec.

Note that one can compute integrated flux in pixel units  by using the '$'
to plot in pixels.  This is appropriate if the pixel values are in
data numbers or photon counts to get total data number or photons.
.ih
ERROR ESTIMATES
The deblending ('d'), single profile fitting ('k'), and profile integration and
equivalent width ('e') functions provide error estimates for the measured
parameters.  This requires a model for the pixel sigmas.  Currently this
model is based on a Poisson statistics model of the data.  The model
parameters are a constant gaussian sigma and an "inverse gain" as specified
by the parameters \fIsigma0\fR and \fIinvgain\fR.  These parameters are
used to compute the pixel value sigma from the following formula:

.nf
    sigma**2 = sigma0**2 + invgain * I
.fi

where I is the pixel value and "**2" means the square of the quantity.

If either the constant sigma or the inverse gain are specified as INDEF or
with values less than zero then no noise model is applied and no error
estimates are computed.  Also if the number of error samples is less than
10 then no error estimates are computed.  Note that for processed spectra
this noise model will not generally be the same as the detector readout
noise and gain.  These parameters would need to be estimated in some way
using the statistics of the spectrum.  The use of an inverse gain rather
than a direct gain was choosed to allow a value of zero for this
parameters.  This provides a model with constant uncertainties.

The direct profile integration error estimates are computed by error
propagation assuming independent pixel sigmas.  Also it is assumed that the
marked linear background has no errors.  The error estimates are one sigma
estimates.  They are given in the log output (which may also be view
without exiting the program using the :show command) below the value to
which they apply and in parenthesis.

The deblending and profile fit error estimates are computed by Monte-Carlo
simulation.  The model is fit to the data (using the sigmas) and this model
is used to describe the noise-free spectrum.  A number of simulations,
given by the \fInerrsample\fR parameter, are created in which random
gaussian noise is added to the noise-free spectrum using the pixel
sigmas from the noise model.  The model fitting is done for each simulation
and the absolute deviation of each fitted parameter to model parameter is
recorded.  The error estimate for the each parameter is then the absolute
deviation containing 68.3% of the parameter estimates.  This corresponds to
one sigma if the distribution of parameter estimates is gaussian though
this method does not assume this.

The Monte-Carlo technique automatically includes all effects of
parameter correlations and does not depend on any approximations.
However the computation of the errors does take a significant
amount of time.  The amount of time and the accuracy of the
error estimates depend on how many simulations are done.  A
small number of samples (of order 10) is fast but gives crude
estimates.  A large number (greater than 100) is slow but gives
good estimates.  A compromise value of 50 is recommended
for many applications.
.ih
UNITS
The dispersion units capability of \fBsplot\fR allows specifying the
units with the \fIunits\fR parameter and interactively changing the units
with the ":units" command.  In addition the 'v' key allows plotting in
velocity units with the zero point velocity defined by the cursor
position.

The units are specified by strings having a unit type from the list below
along with the possible preceding modifiers, "inverse", to select the
inverse of the unit and "log" to select logarithmic units. For example "log
angstroms" to plot the logarithm of wavelength in Angstroms and "inv
microns" to plot inverse microns.  The various identifiers may be
abbreviated as words but the syntax is not sophisticated enough to
recognized standard scientific abbreviations except as noted below.

.nf
	   angstroms - Wavelength in Angstroms
	  nanometers - Wavelength in nanometers
	millimicrons - Wavelength in millimicrons
	     microns - Wavelength in microns
	 millimeters - Wavelength in millimeters
	  centimeter - Wavelength in centimeters
	      meters - Wavelength in meters
	       hertz - Frequency in hertz (cycles per second)
	   kilohertz - Frequency in kilohertz
	   megahertz - Frequency in megahertz
	    gigahertz - Frequency in gigahertz
	         m/s - Velocity in meters per second
	        km/s - Velocity in kilometers per second
	          ev - Energy in electron volts
	         kev - Energy in kilo electron volts
	         mev - Energy in mega electron volts

	          nm - Wavelength in nanometers
	          mm - Wavelength in millimeters
	          cm - Wavelength in centimeters
	           m - Wavelength in meters
	          Hz - Frequency in hertz (cycles per second)
	         KHz - Frequency in kilohertz
	         MHz - Frequency in megahertz
	         GHz - Frequency in gigahertz
		  wn - Wave number (inverse centimeters)
.fi

The velocity units require a trailing value and unit defining the
velocity zero point.  For example to plot velocity relative to
a wavelength of 1 micron the unit string would be:

.nf
	km/s 1 micron
.fi

Some additional examples of units strings are:

.nf
	milliang
	megahertz
	inv mic
	log hertz
	m/s 3 inv mic
.fi
.ih
EXAMPLES
This task has a very large number of commands and capabilities which
are interactive and  graphical.  Therefore it these examples are
fairly superficial.  The user is encouraged to simply experiment with
the task.  To get some help use the '?' or '/' keys.

1.  To plot a single spectrum and record any measurements in the file
'ngc7662':

	cl> splot spectrum save_file=ngc7662

2.  To force all plots to display zero as the minimum y value:

	cl> splot spectrum options="auto, zero"

Note that the options auto and zero can be abbreviated to one character.

3.  To successively display graphs for a set of spectra with the wavelength
limits set to 3000 to 6000 angstroms:

	cl> splot spec* xmin=3000 xmax=6000

4.  To make batch plots create a file containing the simple cursor command

	0 0 0 q

or an empty file and then execute one of the following:

.nf
	cl> splot spec* graphics=stdplot cursor=curfile
	cl> set stdvdm=splot.mc
	cl> splot spec* graphics=stdvdm cursor=curfile
	cl> splot spec* cursor=curfile >G splot.mc
.fi

The first example sends the plots to the standard plot device specified
by the environment variable "stdplot".  The next example sends the plots
to the standard virtual display metacode file specified by the
environment variable "stdvdm".  The last example redirects the
standard graphics to the metacode file splot.mc.  To spool the metacode
file the tasks \fBstdplot\fR and \fBgkimosaic\fR may be used.
For a large number of plots \fBgkimosaic\fR is prefered since it places
many plots on one page instead of one plot per page.
The other GKI tasks in the \fBplot\fR package may be used to examine
the contents of a metacode file.  A simple script call \fBbplot\fR is provided
which has the default cursor file given above and default device of "stdplot".

5.  More complex plots may be produced both interactively using the
'=' key or the ":.snap"  or ":.write" commands or by preparing a script
of cursor commands.
.ih
REVISIONS
.ls SPLOT V2.11
The profile fitting and deblending was expanded to include lorentzian
and voigt profiles.  A new parameter controls the number of Monte-Carlo
samples used in the error estimates.

Added colon commands for labeling.
.le
.ls SPLOT V2.10.3
The 'u' key now allows three ways to adjust the dispersion scale.  The
old method of setting a linear dispersion scale is retained as well
as adding a doppler and zeropoint adjustment.  The coordinates are
input in the currently displayed units.

If a wavelength scale is set with either 'p' or 'u' then any other
spectra which are not dispersion corrected will adopt this wavelength
scale.

The '(' and ')' keys cycle through bands if there is only one spectrum.

A new option, "flip", has been added to the options parameter to select
that the spectra are plotted in decreasing wavelength.

A new options "overplot" has been added to the options parameters and
colon commands to permanently set overplotting.  This allows quickly
overplotting many spectra.

This task will now write out the current display units in the "units_display"
WCS attribute.  The default task units have been changed to "" to allow
picking up the "units_display" units if defined.

The deblending and gaussian fitting code now subsamples the profile by
a factor of 3 and fits the data pixels to the sum of the three
subsamples.  This accounts for finite sampling of the data.

Error estimates are provided for the deblending ('d'), gaussian fitting
('k'), and profile integration ('e') results.
.le
.ls SPLOT V2.10
This is a new version with a significant number of changes.  In addition to
the task changes the other general changes to the spectroscopy packages
also apply.  In particular, long slit spectra and spectra with nonlinear
dispersion functions may be used with this task.  The image header or
package dispaxis and nsum parameters allow automatically extracting spectra
from 2D image.  The task parameters have been modified primarily to obtain
the desired initial graph without needing to do it interactively.  In
particular, the new band parameter selects the band in 3D images, the units
parameter selects the dispersion units, and the new histogram, nosysid, and
xydraw options select histogram line type, whether to include a system ID
banner, and allow editing a spectrum using different endpoint criteria.

Because nearly every key is used there has been some shuffling,
consolidating, or elimination of keys.  One needs to check the run time '?'
help or the help to determine the key changes.

Deblending may now use any number of components and simultaneous fitting of
a linear background.  A new simplified version of Gaussian fitting for a
single line has been added in the 'k' key.  The old 'k', 'h', and 'v'
equivalent width commands are all part of the single 'h' command using a
second key to select a specific option.  The Gaussian line model from these
modes may now be subtracted from the spectrum in the same way as the
Gaussian fitting.  The one-sided options, in particular, are interesting in
this regard as a new capability.

The arithmetic functions between two spectra are now done in wavelength
with resampling to a common dispersion done automatically.  The 't' key now
provides for the full power of the ICFIT package to be used on a spectrum
for continuum normalization, subtraction, or line and cosmic ray removal.
The 'x' editing key may now use the nearest pixel values rather than only
the y cursor position to replace regions by straight line segments.  The
mode is selected by the task option parameter "xydraw".

Control over the graph window (plotting limits) is better integrated so
that redrawing, zooming, shifting, and the GTOOLS window commands all work
well together.  The new 'c' key resets the window to the full spectrum
allowing the 'r' redraw key to redraw the current window to clean up
overplots from the Gaussian fits or spectrum editing.

The dispersion units may now be selected and changed to be from hertz to
Mev and the log or inverse (for wave numbers) of units taken.  As part of
the units package the 'v' key or colon commands may be used to plot in
velocity relative to some origin.  The $ key now easily toggles between the
dispersion units (whatever they may be) and pixels coordinates.

Selection of spectra has become more complex with multiaperture and long
slit spectra.  New keys allow selecting apertures, lines, columns, and
bands as well as quickly scrolling through the lines in multiaperture
spectra.  Overplotting is also more general and consistent with other tasks
by using the 'o' key to toggle the next plot to be overplotted.  Overplots,
including those of the Gaussian line models, are now done in a different
line type.

There are new colon commands to change the dispersion axis and summing
parameters for 2D image, to toggle logging, and also to put comments
into the log file.  All the options may also be set with colon commands.
.le
.ih
SEE ALSO
bplot, gtools, icfit, standard, package, specplot, graph, implot, fitprofs
.endhelp