STScI Logo

calcspec stsdas.hst_calib.synphot


NAME · USAGE · DESCRIPTION_ · PARAMETERS · EXAMPLES · REFERENCES
SEE_ALSO

NAME

calcspec -- Calculate synthetic spectra.

USAGE

calcspec spectrum output

DESCRIPTION

This task writes a synthetic spectrum to a file. Several functions are available for creating synthetic spectra. Spectra can also be read from files. Calcspec supports the four basic functions plus negation. Expressions can be parenthesized to change the default order of evaluation. Spaces are not significant, except for the division operator, which must be surrounded by blanks so that it will not be mistaken for part of a filename. Calcspec evaluates expressions containing filenames, constants, and variables. When calcspec sees a filename, it determines if the file is a passband or a spectrum and reads it interpolated on the wavelength grid. Constants are either numbers or strings. String constants are NOT surrounded by quote marks. Numeric constants are interpreted as real numbers and all mathematical operations between filenames and constants are legal.

Calcspec prevents physically meaningless expressions from being computed by keeping track of the degree of the expression during computation. The degree of the entire expression must be zero or one. If the degree of the expression is zero, the result of calcspec is a passband. If it is one, the result is a spectrum. Although calcspec is primarily intended for producing spectra, it can also to compute passbands.

The degree of the entire expression is computed from the subexpressions that make it up. Constants and passbands have a degree of zero. Spectra have a degree of one. Each function also has a degree, which is either zero or one. Multiplying two subexpressions yields a result whose degree is the sum of the degrees of the two subexpressions. Dividing two subexpressions yields a result whose degree is the difference between the degrees of the two subexpressions. Adding or subtracting two subexpressions yields a result whose degree is the same as the degrees of both subexpressions. Adding or subtracting two subexpressions whose degrees are different is forbidden and causes an error exit. Negation gives a result whose degree is the same as the subexpression.

PARAMETERS

spectrum [string]
This is a sequence of commands and arguments that specify 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 such a command file is treated as a separate set of commands.

Calcspec supports a variety of different functions. The following table lists these functions, their degree, amd their arguments. The name of the arguments indicate the argument type: NUM for numeric constants, STR for string constants, BAND for passbands, and SPEC for spectra. Ellipsis marks indicate that an indefinite number of arguments of the same type as the last explicitly stated argument may be included in the function.

FUNCTION			DEG	DESCRIPTION
----------------------------------------------------------------------
band(str1, ...)			0	Telescope passband
bb(num1)			1	Black body spectrum
box(num1, num2)			0	Rectangular passband
cat(str1, ...)			1	Read from a catalog of spectra
ebmv(num1)			0	Galactic extinction curve
ebmvx(num1, str1)		0	Other extinction curves
em(num1, num2, num3, str1)	1	Emission line spectrum
gauss(num1, num2)		0	Normal curve passband
grid (str1, num1)		1	Interpolated spectrum in grid
hi(num1, num2)			1	Hydrogen absorption spectrum
icat(str1, ...)			1	Interpolate in a catalog of spectra
lgauss(num1, num2)		0	Log normal curve passband
pl(num1, num2, str1)		1	Power law spectrum
poly(num1, num2, num3, ...)	0	Legendre polynomial 
rn(spec1, band1, num1, str1)	1	Renormalize spectrum
spec(str1)			1	Read a spectrum
thru(str1)			0	Read a passband
tilt(band1, num1, ...)		0	Legendre polynomial product
unit(num1, str1)		1	Constant spectrum
z(spec1, num1)			1	Redshift spectrum

The following is a more detailed description of each of the functions.

band(str1, ...)
str1:	observation mode keyword

A passband associated with a telescope observing mode. The observing mode is specified by the arguments to the function. The combination of the arguments should uniquely specify an observing mode. The arguments to the band() function are explained further in the obsmode task.

bb(num1)
num1:	temperature in Kelvin

A black body spectrum normalized in flux to be equal to a one solar radius star at a distance of one kiloparsec.

box(num1, num2)
num1:	passband center
num2:	passband width

A passband that is one inside the specified region and zero outside.

cat(str1, str2, ...)
str1: catalog name
str2: search key

A spectrum selected from a catalog of spectra. The first argument specifies the catalog name and the remaining arguments specify the spectrum within the catalog. The catalog name must be a subdirectory of crgrid$. This directory contains a file named catalog.tab that is read by this function. The first column of the table, INDEX, contains a comma separated list of keywords used to select the row by matching the the second and following arguments of the function. String arguments must match exactly (except for case). If there are numeric arguments, the function will choose the spectrum with the minimum distance.

ebmv(num1)
num1:	number of magnitudes of extinction

Interstellar reddening function for our galaxy, according to Seaton's paper. This function is equivalent to using ebmvx() with the second argument set to gal1.

ebmvx(num1, str1)
num1:	number of magnitudes of extinction
str1:	extinction law used

The extended reddening function, supporting a number of different reddening laws. The second argument selects the type of reddening law used to compute the extinction. The task supports three galactic reddening laws (gal1 to gal3) and one law each for the Small Magellanic Cloud (smc), Large Magellanic Cloud (lmc), and extra-galactic objects (xgal). The laws are derived from the following papers.

gal1	Seaton (1979) MNRAS, vol 187, p. 75 
gal2	Savage & Mathis (1979) ARA&A, vol. 17, p. 73-111
gal3	Cardelli, Clayton & Mathis (1989) ApJ vol. 345, p. 245-256
smc	Prevot et al. (1984) A&A, vol. 132, p. 389-392
lmc	Howarth (1983) MNRAS, vol. 203, p. 301
xgal	Calzetti, Kinney and Storchi-Bergmann, (1994) ApJ, vol. 429, p.582

em(num1, num2, num3, str1)
num1:	mean wavelength of emission line
num2:	full width half maximum of emission line
num3:	total flux in emission line
str1:	flux units

An emission line with a gaussian profile and specified flux. The emission line can be added to another spectrum or subtracted from it to create an absorption line.

gauss(num1, num2)
num1:	mean of normal distribution
num2:	full width half maximum of distribution

A passband with normal distribution. The full width half maximum is sqrt(8 * ln(2)) times the standard deviation.

grid (str1, num1)
str1:	ascii file containing a list of filenames
num1:	point to interpolate at  

A spectrum interpolated in a grid of spectra. The second argument gives the interpolation point. For example, 2.3 interpolates .3 of the way between the second and third spectra.

hi(num1, num2)
num1:	temperature in Kelvin
num2:	column density in cm^-3

An absorption spectrum for a black body embedded in hydrogen. If the column density is less than 80, it is assumed to be a logarithm of the column density. Flux is normalized to be equal to a one solar radius at one kiloparsec.

icat(str1, str2, ...)
str1: catalog name
str2: search key

A spectrum selected from a catalog of spectra. The first argument specifies the catalog name and the remaining arguments specify the spectrum within the catalog. The catalog name must be a subdirectory of crgrid$. This directory contains a file named catalog.tab that is read by this function. The first column of the table, INDEX, contains a comma separated list of keywords used to select the row by matching the the second and following arguments of the function. String arguments must match exactly (except for case). If there are numeric arguments, the function will interpolate between spectra which bracket the arguments. If there is no complete bracket, the function will choose the spectrum with the minimum distance.

lgauss(num1, num2)
num1:	mean of distribution
num2:	full width half maximum of distribution

A passband with normal distribution in the logarithm of the wavelength.

pl(num1, num2, str1)
num1:	reference wavelength
num2:	power law exponent
str1:	flux units

A power law spectrum. The flux is one at the reference wavelength in the specified units, unless the units are magnitude units, in which case the flux is zero in the specified units.

poly(num1, num2, num3, ...)
num1:	mean of polynomial
num2:	full width half maximum
num3:	polynomial coefficient

A passband which is a function of legendre polynomials. First, sigma is computed from the full width half maximum using the formula: sigma = fwhm / sqrt (8 * ln(2)) Then the independent variable is transformed from wavelength with the formula:

	u = (wave - mean) / sigma
The sum of the legendre polynomials is computed with the formula
	sum = SUM[ coef_n * legendre_n (u)]
The final passband is given by the formula
	band = sum + 1 if sum >= 0
	band = exp (sum) if sum < 0

rn(spec1, band1, num1, str1)
spec1:	spectrum to be renormalized
band1:	passband to normalize spectrum over
num1:	flux of normalized spectrum
str1:	flux units

A spectrum normalized to a specified flux value when integrated over a specified passband.

spec(str1)
str1:	spectrum filename

Read a file as a spectrum. This function is intended for those cases where a filename might be interpreted as a number or contain arithmetic operators as characters. Otherwise, the filename can be placed in the expression without using this function.

thru(str1)
str1:	passband filename

Read a file as a passband. This function is intended for those cases where a passband file may be mistaken for a spectrum or may be interpreted as a number or contain arithmetic operators. Otherwise, the filename can be placed in the expression without using this function.

tilt(band1, num1, ...)
band1:	passband from which mean and fwhm are computed
num1:	polynomial coefficient

A passband similar to that produced by poly(), except that the mean and full width half maximum are computed from the wavelength.

unit(num1, str1)
num1:	flux value
str1:	flux units

A constant spectrum with the specified value and units.

z(spec1, num1)
spec1:	spectrum to be redshifted
num1:	z value used in shift

Redshift a spectrum by the z value given in the second argument.

output [string]
Output STSDAS table name. This table has two columns, named WAVELENGTH and FLUX. If more than one spectrum is specified via a file, then a separate FLUXn column will be created for the nth spectrum listed in the file.

The output table contains the following header keywords:


	KEYWORD		PARAMETER
	=======		=========
	GRFTABLE	Name of the instrument graph table.
	CMPTABLE	Name of the component lookup table.
	EXPR		Value of spectrum parameter

If more than one spectrum is input via a file, each will be listed as a header keyword, with the name EXPRn.

The form of the output table is somewhat different if the result is passband. The form of an output table containing a passband is discussed in the help file for calcband.

(form = photlam) [string]
Desired output form for the calculated spectrum. The form is ignored if the output is a passband. 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
(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. This pset contains the following parameters:

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

grtbl = "mtab$*.tmg":  HST graph table.  By default, this
        uses the most recent version. 

cmptbl = "mab$*.tmc":  Instrument component table.  By 
        default, this uses the most recent version.

EXAMPLES

1. Calculate a blackbody spectrum and renormalize it to have an integrated V band magnitude of 18.6. Store the spectral data in an STSDAS table called bb18p6.tab, in units of f-lambda.

sy> calcspec "rn(bb(5000),band(v),18.6,vegamag)" bb18p6 form=flam

2. Simulate an observation of BD+75 325 using the FOS blue side with the 4.3 arcsec aperture and the G160l grating. The spectral data for BD+75 325 are stored in the table bd75d325.tab in units of STMAG (unit conversion will be performed in real time by calcspec). Because this spectrum has been arbitrarily normalized in intensity, we must first renormalize it to its proper U magnitude of 9.5 and then multiply by the FOS instrument mode passband. The spectrum, in units of photlam (photons/sec/cm**2/A), will be stored in table bd75.tab.

sy> calcspec "rn(bd75d325,band(u),9.5,vegamag)*band(fos,blue,4.3,g160l)" \
>>> bd75 form=photlam

3. A star observed using the wfpc with filter f555w is observed to have 1200 counts per second. What would its spectrum be for various assumed black body temperatures? Store the results in table bbody.tab

sy> calcspec "rn(bb($0),band(wfpc,f555w),1200,counts)" bbody.tab \
>>> vzero="5e3-20e3x1e3"

REFERENCES

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

SEE ALSO

calcband, plband, plspec


Source Code · Package Help · Search Form · STSDAS