IRAF help page for package noao.onedspec, program splot

• images
• line, band
• units =
• options = auto [auto,zero,xydraw,histogram,nosysid,wcreset,flip,overplot]
• xmin = INDEF, xmax = INDEF, ymin = INDEF, ymax = INDEF
• save_file = splot.log
• graphics = stdgraph
• cursor =
• sigma0 = INDEF, invgain = INDEF
• function = spline3
• order = 1
• low_reject = 2., high_reject = 4.
• niterate = 10
• grow = 1.
• markrej = yes
• star_name
• caldir = )_.caldir
• fnuzero = 3.68e-20
• next_image
• new_image
• overwrite = no
• spec2
• constant
• wavelength
• linelist
• wstart, wend, dw
• boxsize

• ?
• /
• a
• b
• c
• d
• e
• f
• a
• d
• e
• i
• l
• m
• n
• p
• q
• s
• +
• -3 -
• *
• /
• g
• h
• a
• b
• c
• l
• r
• k
• i
• j
• k
• l
• m
• n
• o
• p
• q
• r
• s
• t
• /
• -
• f
• c
• n
• q
• u
• v
• w
• x
• y
• z
• (
• )
• #
• %
• $
• -4 -
• -4 ','
• .
• I
• :show
• :log
• :nolog
• :dispaxis
• :nsum
• :units
• :#
• :auto [yes|no]
• :zero [yes|no]
• :xydraw [yes|no]
• :hist [yes|no]
• :nosysid [yes|no]
• :wreset [yes|no]
• :flip [yes|no]
• :overplot [yes|no]

• SPLOT V2.11
• SPLOT V2.10

splot images [line [band]]

images

line, band

units =

options = auto [auto,zero,xydraw,histogram,nosysid,wcreset,flip,overplot]

xmin = INDEF, xmax = INDEF, ymin = INDEF, ymax = INDEF

save_file = splot.log

graphics = stdgraph

cursor =

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.

sigma0 = INDEF, invgain = INDEF

    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

order = 1

low_reject = 2., high_reject = 4.

niterate = 10

grow = 1.

markrej = yes

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

star_name

caldir = )_.caldir

fnuzero = 3.68e-20

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

next_image

new_image

overwrite = no

spec2

constant

wavelength

linelist

wstart, wend, dw

boxsize

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 the other spectra are copied. If other spectra in the same image is then modified and saved use the overwrite option to replace then in the new output image. If the current spectrum is a long slit image or other 2D image a 1D spectrum output image is created. It is not possible to write into a 2D 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"):

?

/

>

a

b

c

d

e

f

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

d

e

i

l

m

n

p

q

s

+

-3 -

*

/

g

h

b

c

l

r

k

i

j

k

l

m

n

o

p

q

r

s

t

-

f

c

n

q

u

v

w

x

y

z

(

)

#

%

$

-4 -

-4 ','

.

I

:show

:log

:nolog

:dispaxis

:nsum

:units

:#

:auto [yes|no]

:zero [yes|no]

:xydraw [yes|no]

:hist [yes|no]

:nosysid [yes|no]

:wreset [yes|no]

:flip [yes|no]

:overplot [yes|no]

The single profile ('k') and multiple profile deblending ('d') commands fit simple Gaussian profiles with a linear background. More general fitting and detailed profile models are left to other more specialized tasks. At the time this description was written there were no such tasks but some are under consideration.

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 profile center, peak strength, and width 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 ('m'), 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.

There are three 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 or sigmas 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 measureable doppler shift.

After the fit, the modeled lines are overplotted. The line center, flux, equivalent width, and full width half maximum 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 sigma and FWHM (=2.355 sigma), 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 analytic Gaussian profiles. Thus, even though the fitted region may not extend into the wings of a line the equivalent width measurement included 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 interative 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.  The initial line centers are those specified by the user
	either by marking with the cursor or entering the
	wavelenths.
    2.  The initial peak intensities are the data values at the
	given line centers with the marked continuum subtracted.
    3.  The initial sigmas are obtained by dividing the width of
	the marked fitting region by the number of lines and then
	dividing this width by 10.

Note that each time a new fitting option is specified the initial parameters are reset. Thus the results do not depend on the history of previous fits. However, within each option an iteration of parameters is performed as described next.

The interation 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 sigma are fit first with fixed background. Then multiple sigmas and the background are added.

To conclude here are some general comments. The most restrictive (fixed positions and single sigma) 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 sigmas 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 Gaussian.

There are currently five techniques in SPLOT to measure equivalent widths of lines. The simplest (conceptually) is by integration of the pixel intensities between two marked pixels. This is invoked with the 'e' keystroke. The user marks the two edges of the line at the continuum. The line center is a weighted centroid and the continuum is a linear function between the two points marked.

The most complex method is performed by the Gaussian fitting and deblending commands which compute a non-linear least-squares Gaussian 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 measurments 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 Gaussian profile methods the core intensity above or below the continuum, the sigma, and the FWHM (=2.355 sigma) are also printed. 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 measurments 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 responsiblity 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 the integrated flux will be correct; i.e. ergs/cm2/sec.

The deblending ('d'), Gaussian 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. 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 Gaussian 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. One hundred simulations are created in which random Gaussian noise is added to the noise-free spectrum based on 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 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 such as mm for millimeter.

	   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

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.

SPLOT V2.11

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

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.

bplot, gtools, icfit, standard, package, specplot, graph, implot, fitprofs,