Initial commit

1 files changed, 1118 insertions, 0 deletions

diff --git a/noao/onedspec/doc/splot.hlp b/noao/onedspec/doc/splot.hlp
new file mode 100644
index 00000000..a5bc3b96
--- /dev/null
+++ b/noao/onedspec/doc/splot.hlp
@@ -0,0 +1,1118 @@
+.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