splot: Preliminary spectral plot/analysis

Package: iids

Usage

splot images [line [band]]

Parameters

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.

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.

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 package help for a further description and available units.

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 ymin 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 xmin, xmax, ymin, ymax 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.

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 gtools).

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.

graphics = "stdgraph": Output graphics device: one of "stdgraph", "stdplot", "stdvdm", or device name.

cursor = "": Graphics cursor input. When null the standard cursor is used otherwise the specified file is used.

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.

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.

sigma0 = INDEF, invgain = INDEF

The pixel sigmas are modeled by the formula:

sigma**2 = sigma0**2 + invgain * I

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.

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 icfit for additional details on interactive curve fitting.

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.

order = 1: The order of the polynomials or the number of spline pieces.

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.

niterate = 10: Number of rejection iterations.

grow = 1.: When a pixel is rejected, pixels within this distance of the rejected pixel are also rejected.

markrej = yes: Mark rejected points? If there are many rejected points it might be desired to not mark rejected points.

The following parameters are used to overplot standard star fluxes with the 'y' key. See standard for more information about these parameters.

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.

mag: The magnitude of the observed star in the band given by the magband 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

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.

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.

caldir = ")_.caldir": The standard star calibration directory. The default value redirects the value to the parameter of the same name in the package parameters.

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.

The following parameters are used for queries in response to particular keystrokes.

next_image: In response to 'g' (get next image) this parameter specifies the image.

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.

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.

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.

constant: When adding or multiplying by a constant ('p' or 'm' keys in the 'f' mode) the parameter is used to get the constant.

wavelength: This parameter is used to get a dispersion coordinate value during deblending or when changing the dispersion coordinates with 'u'.

linelist: During deblending this parameter is used to get a list of line positions, peak values, profile types, and widths.

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.

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.

Description

Splot provides an interactive facility to display and analyze spectra. See also bplot 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 apextract, 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 xmin, xmax, ymin, and ymax. 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 options 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 units parameter. This allows converting to units other than those in which the dispersion coordinates are defined in the spectra.

The option 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 cursor 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 overwrite 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 save_file if specified.

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

?: Page help information.

/: Cycle through short status line help.

<space>: The space bar prints the cursor position and value of the nearest pixel.

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.

b: Set the plot base level to zero rather than autoscaling.

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.

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.

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.

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.

a: Absolute value

d: Power of base 10 (inverse log base 10)

e: Power of base e (inverse log base e)

i: Inverse/reciprocal (values equal to zero are set to 0.0 in the inverse)

l: Log base 10 (values less than or equal to 0.0 are set to -0.5)

m: Multiply by a constant (constant is queried)

n: Log base e (values less than or equal to 0.0 are set to -0.5)

p: Add by a constant (constant is queried)

q: Quit Function mode

s: Square root (values less than 0.0 are set to 0.0)

+: Add another spectrum

-: Subtract another spectrum

*: Multiply by another spectrum

/: Divide by another spectrum

g: Get another spectrum. The current spectrum is replaced by the new spectrum. The aperture/line and band are queried is necessary.

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:

a: Mark the continuum level at the line center and use the LEFT half width at the half flux point.

b: Mark the continuum level at the line center and use the RIGHT half width at the half flux point.

c: Mark the continuum level at the line center and use the FULL width at the half flux point.

l: Mark a flux level at the line center relative to a normalized continuum and use the LEFT width at that flux point.

r: Mark a flux level at the line center relative to a normalized continuum and use the RIGHT width at that flux point.

k: Mark a flux level at the line center relative to a normalized continuum and use the FULL width at that flux point.

i: Write the current spectrum out to a new or existing image. The image name is queried and overwriting must be confirmed.

j: Set the value of the nearest pixel to the x cursor to the y cursor position.

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.

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'.

m: Compute the mean, RMS, and signal-to-noise over a region marked with two x cursor positions.

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'.

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.

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.

q: Quit and go on to next input spectrum. After the last spectrum exit.

r: Redraw the spectrum with the current windowing. To redraw the full spectrum and cancel any windowing use the 'c' key.

s: Smooth via a boxcar. The user is prompted for the box size.

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.

/: Normalize by the fit. When fitting the continuum this continuum normalizes the spectrum.

-: Subtract the fit. When fitting the continuum this continuum subtracts the spectrum.

f: Replace the spectrum by the fit.

c: Clean the spectrum by replacing any rejected points by the fit.

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.

q: Quit and don't do any fitting. The spectrum is not modified.

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.

v: Toggle to a velocity scale using the position of the cursor as the velocity origin and back.

w: Window the graph. For further help type '?' to the "window:" prompt or see help under gtools. To cancel the windowing use 'a'.

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.

y: Overplot standard star values from a calibration file.

z: Zoom the graph by a factor of 2 in x.

(: 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.

): 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.

#: Get a different line in multiaperture spectra or two dimensional images. The aperture/line/column is queried.

%: Get a different band in a three dimensional image.

$: Switch between physical pixel coordinates and world (dispersion) coordinates.

-: 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.

',': Shift the graph window to the left.

.: Shift the graph window to the right.

I: Force a fatal error interupt to leave the graph. This is used because the normal interupt character is ignored in graphics mode.

:show: Page the full output of the previous deblend and equivalent width measurements.

:log: Enable logging of measurements to the file specified by the parameter save_file. 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.

:nolog: Disable logging of measurements.

:dispaxis <val>: Show or change dispersion axis for 2D images.

:nsum <val>: Show or change summing for 2D images.

:units <value>: Change the coordinate units in the plot. See below for more information.

:# <comment>: Add comment to logfile.

Labels:

:label <label> <format>: Add a label at the cursor position.

:mabove <label> <format>: Add a tick mark and label above the spectrum at the cursor position.

:mbelow <label> <format>: Add a tick mark and label below the spectrum at the cursor position.

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.

:auto [yes|no]: Enable/disable autodraw option

:zero [yes|no]: Enable/disable zero baseline option

:xydraw [yes|no]: Enable/disable xydraw option

:hist [yes|no]: Enable/disable histogram line type option

:nosysid [yes|no]: Enable/disable system ID option

:wreset [yes|no]: Enable/disable window reset for new spectra option

:flip [yes|no]: Enable/disable the flipped coordinates option

:overplot [yes|no]: Enable/disable the permanent overplot option

:/help: Get help on GTOOLS options.

:.help: Get help on standard cursor mode options

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

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

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 fitprofs and also by artdata.mk1dspec (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:

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.

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.

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:

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))

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".

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

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.

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 sigma0 and invgain. These parameters are used to compute the pixel value sigma from the following formula:

sigma**2 = sigma0**2 + invgain * I

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 nerrsample 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.

Units

The dispersion units capability of splot allows specifying the units with the units 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.

   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)

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:

km/s 1 micron

Some additional examples of units strings are:

milliang
megahertz
inv mic
log hertz
m/s 3 inv mic

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:

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

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 stdplot and gkimosaic may be used. For a large number of plots gkimosaic is prefered since it places many plots on one page instead of one plot per page. The other GKI tasks in the plot package may be used to examine the contents of a metacode file. A simple script call bplot 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.

Revisions

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.

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.

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.