NAME

plspec -- Plot calculated and observed spectra and photometric data

USAGE

plspec obsmode spectrum form

DESCRIPTION

This task plots synthetic spectra generated from observation mode and spectrum expressions. The syntax for the observation mode expression is described in the help file for calcband and the syntax for the spectrum expression is described in the help file for calcspec. Spectra stored in files can also be plotted.

More than one spectrum can be plotted at a time by creating files with one observation mode or passband on each line. The parameter vzero can also be used to substitute a set of values for variable zero in the spectra. All combination of the observation modes, spectra, and values of vzero will be plotted.

The hidden parameter spfile allows the user to plot spectrophotmetric files. Spectrophotometic files differ from ordinary spectra in that they may contain two extra columns, STATERROR and FWHM. These columns contain the errors in flux and wavelength, respectively. The parameter errtyp allows the user to plot these errors in a number of different ways.

The hidden parameter pfile allows the user to plot the photometric tables generated by calcphot. The data are plotted as horizontal lines whose midpoint is marked with a circle. This midpoint had its x value set to the pivot wavelength of the observation mode passband, its y value set to the effective stimulus of the combination of observation mode and spectrum. The length of the line is set to the full width half maximum of the equivalent gaussian of the observation mode passband. The observation mode passbands are overplotted at the base of the plot.

PARAMETERS

obsmode [string]

This is a sequence of commands that creates the synthetic passband. The name of a command file can be passed to obsmode by preceding the file name with a "@" character, for example, "@filename".

Each command may either be a simple bandpass, which is represented by a comma separated string of keywords uniquely specifying an observing mode of the telescope or a more complex command, described in the help file for calcband. The keywords which make up the observing mode are explained further in the obsmode task. If this parameter is left blank or set to "none", a default observation mode that is everywhere one will be used.

spectrum [string]

This is a sequence of commands that create the synthetic spectrum. The commands can be placed in a file, whose name is passed to this parameter, preceded by a "@" character, e.g., @filename. Each line in this command file is treated as a separate set of commands. If this parameter is left blank or set to none, no spectra will be plotted.

The commands that can be passed to this parameter are described in detail in the help file for the calcspec task.

form [string]

Desired output form of the plotted spectrum. The following forms are recognized:

	FNU		erg / s / cm^2 / Hz
	FLAM		erg / s / cm^2 / A
	PHOTNU		photons / s / cm^2 / Hz
	PHOTLAM		photons / s / cm^2 / A
	COUNTS		photons / s 
	ABMAG		-2.5 log_10 (FNU)  - 48.60
	STMAG		-2.5 log_10 (FLAM) - 21.10
	VEGAMAG		-2.5 log_10 (F/F_vega)
	OBMAG		-2.5 log_10 (COUNTS)
	JY		10^-23 erg / s / cm^2 / Hz
 	MJY		10^-26 erg / s / cm^2 / Hz

A standard magnitude system is VEGAMAG, for which Vega by definition has magnitude 0 at all wavelengths. The AB and ST magnitude systems are based on constant flux per unit frequency and per unit wavelength, respectively. The zero points for these two systems are set for convenience so that Vega has magnitude 0 in both systems for the Johnson V passband.

(vzero = " ") [string]

A list of values to substitute for variable zero. Each value in the list is substituted in turn for the string $0 wherever it occurs in the input spectrum. The values must be real numbers. Using vzero is the equivalent of placing the input spectrum several times in a file, with each spectrum containing one of the values in the list. The list may contain single values or ranges. The endpoints of the ranges are separated by a dash. An optional step size follows the range, preceded by the letter x. If the step size is not present, the step size defaults to 1 or -1, depending on the order of the endpoints. The following table gives several examples of valid lists

	.1,.2,.3,.4	A list of single values
	.1-.4x.1	The same list expressed as a range
	-1 - -4 	A range with an implicit step size of -1
	1-9,10-20x2	A list of more than one range

(spfile = "none") [file name]

A table or ascii file containing spectrophotometry data; a list of one or more files can be specified using the "@filename" syntax. If the value of this parameter is "none" or blank, no spectrophotometric data will be plotted. The spectrophotometric table can have the columns WAVELENGTH, FLUX, STATERROR, and FWHM. The STATERROR and FWHM columns can be missing or all INDEF. The WAVENGTH and FLUX columns contain the wavelength and values of flux at that wavelength, respectively. The STATERROR and FWHM collumns contain the respective errors of the FLUX and WAVELENGTH columns. If the spectrophotometry file is an ascii file, the first through fourth columns are the wavelength, flux, staterror, and flux and the third and fourth columns are optional.

(pfile = "none") [string]

A file containing photometric data, generated by the calcphot task. A list of files can be passed as "@filename". If the value of this parameter is "none" or blank, no photometric data will be plotted. A table generated by calcphot will have column names DATUM, FORM, OBSMODE and TARGETID. These columns contain the effective stimulus, its form, the observation mode, and spectrum passed to calcphot. The TARGETID column is not used by this task. If the photometric file is an ascii file, the file will have four columns in the order specified above.

(errtyp = "n") [string]

Option for how errors associated with the spectrophotometry (spfile) data should be plotted. The parameter only affects spectrophotometric data. In all cases the vertical error corresponds to the statistical error values and the horizontal error corresponds to the FWHM values as read from spfile. Use the following codes:

     n = none (continuous line plot of flux values only)
     p = plots data as points
     b = plots data as bins (histogram)
     c = plots +/- vertical error as continuous lines
     v = plot vertical error bars
     h = plot horizontal error bars  

Options v and h must be used in conjuction with any of the p, c, or b options. p alone will plot only the flux data as individual points. pv, ph, and pvh will plot the flux data as points and superimpose vertical, horizontal, or both error bars. c causes two continuous lines to be plotted at values corresponding to flux+error and flux-error. ch will overplot horizontal error bars. b plot the flux data in bins (histogram mode), and bv will superimpose vertical error bars on the bins.

(left = INDEF) [real]

Minimum wavelength to plot. If set to INDEF, the task will set it to the minimum wavelength in the wavelength set.

(right = INDEF) [real]

Maximum wavelength to plot. If set to INDEF, the task will set it to the maximum wavelength in the wavelength set.

(bottom = INDEF) [real]

Minimum flux value to plot. If set to INDEF, the task will set it to the minimum flux value.

(top = INDEF) [real]

Maximum flux value to plot. If set to INDEF, the task will set it to the maximum flux value.

(append = no) [boolean]

Append results to an existing plot?

(ltype = "solid") [string]

The line type to be used for plotting the mode1 passband. The allowed values are: clear, solid, dashed, dotted, and dotdash.

(device = "stdgraph") [string]

Send output to the designated device.

(wavetab = "") [file name]

Name of an optional wavelength table or file. An appropriate table can be generated by using the genwave task. If a table is used, the wavelength column name must be "WAVELENGTH". If an ASCII file is used the first column is taken to be the wavelength column. The subdirectory 'synphot$data has ASCII wavelength tables useful for specific HST passbands.

If no wavelength table is specified, a default wavelength set is used. The default wavelength table covers the wavelength range where the spectrum is non-zero. Wavelengths are spaced logarithmically over this range. If there is more than one spectrum, the range is computed based on the first spectrum. If the wavelength range of the spectra differ significantly, a wavelength table should be specified explicitly.

(refdata = " ") [pset name]

Parameter set for reference data used in calculations. The following parameters are stored in this set.

     area = 45238.93416:  HST telescope area in cm**2.

     grtbl = "mtab$*.tmg":  HST graph table.  Uses the
	       most recent version by default.

     cmptbl = "mtab$*.tmc":  Instrument component table.  
                The most recent version is used by default.

EXAMPLES

1. Plot the wfpc,f555w passband and the spectrum of a 5000 K blackbody. No photometry or spectrophotometry data are plotted. The quotes around "bb(5000)" are required to prevent the string from being interpreted by the command interpreter.

sy> plspec wfpc,f555w "bb(5000)" stmag

2. Plot the same spectrum, applying the reddening function ebmv() to the black body with values of 0.0, 0.25, and 0.5

sy> plspec wfpc,f555w "bb(5000)*ebmv($0)" stmag vzero=0.0,0.25,0.5

3. Plot the spectrum of Eta Ursa Majoris in the johnson passbands. The wavelength table is set also set to the spectrum to ensure the plot covers the entire range of the spectrum.

sy> plspec @johnson.lis crcalspec$eta_uma_002.tab vegamag

The file johnson.lis contains the lines:
band(u)
band(b)
band(v)
band(r)
band(i)

4. Plot a photometic file generated by calcphot:

sy> plspec none none counts pfile=phot.tab

REFERENCES

Written by B.Simon based on XCAL code written by Keith Horne

SEE ALSO

calcspec, calcband, plband