NAME

calcband -- Calculate synthetic instrument passbands.

USAGE

calcband obsmode output

DESCRIPTION

This task will create a synthetic passband by combining existing passbands, certain functional forms such as a Gaussian or a rectangular window, or externally created passbands read in from a file. These data can be multiplied by a function of Legendre polynomials to distort the shape, as appropriate.

This task uses the same back end as calcspec, including the expression evaluator. This help file only discusses those functions most relevant to computing passbands, but the full range of functions described in the help file for calcspec can be used. The reson for supplying a separate front end to handle passbands is that some of the task parameters to calcspec, such as form are not relevant to calcband.

PARAMETERS

obsmode [string]

This is a sequence of commands that create the synthetic passband. 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.

The command interpreter supports addition (+), subtraction (-), multiplication (*), division (/), and negation (-). The division operator should be surrounded by blanks to keep from being interpreted as part of a file name. Operator precedence and associativity is the same as Fortran. Precedence can be changed by enclosing subexpressions in parentheses. The terms which are operated on are either passband files, numeric constants, or functions. As a convenience to users, if the expression consists of a single call to the band() function, only the arguments to the function need be given. For example, the obsmode "band(wfpc,f555w)" can also be given as "wfpc,f555w". The arguments to the band() function are explained further in the obsmode task.

The interpreter supports several functions which return passbands: band(), which returns a passband corresponding to an hst observing mode, box(), which returns a box passband, gauss() and lgauss(), which return gaussian and log gaussian passbands, and poly() and tilt(), which return Legendre polynomial passbands. The following is a more detailed description of these 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.to this 

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

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

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.

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.

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

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.

output [file name]

Name of the STSDAS table to be used as output. The table has two columns, WAVELENGTH and THROUGHPUT. If more than one passband is specified via a file, then a separate THROUGHPUTn column will be created for the nth passband listed in a 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.
	APERAREA	The HST area, in cm^2, used to compute URESP.
	ZEROPT		Photometric zero point of the STMAG system.
	EXPR		Value of spectrum parameter
	URESP		Flux (in flam) of a star that produces a response
			of one photon per second in this passband.
	PIVWV		Passband pivot wavelength.
	BANDW		Passband rms width.
	TPEAK		Peak bandpass throughput
	EQUVW		Passband equivalent width
	RECTW		Passband rectangular width
	EMFLX		Equivalent monochromatic flux

If more than one passband is input via a file, the last eight header keywords will be included once for each passband, with the names EXPRn, URESPn, PIVWVn, BANDWn, TPEAKn, EQUVWn, RECTWn, and EMFLXn for the nth passband.

The seven photometric passbands are defined by the following formulas:

	URESP = H * C / (AREA * INT(THRU * LAM))

	PIVWV = SQRT(INT(THRU * LAM) / INT (THRU / LAM))

	BANDW = BARLAM * SQRT(INT(THRU * LN(LAM / BARLAM) ** 2 / LAM) /
			      INT(THRU / LAM)
	BARLAM = INT(THRU * LN(LAM) / LAM) / INT(THRU / LAM)

	TPEAK = MAX(THRU)

	EQUVW = INT(THRU)

	RECTW = INT(THRU) / MAX(THRU)

	EMFLX = URESP * RECTW * (TPEAK / TLAMBDA)
	TLAMBDA = Throughput at AVGWAV
	AVGWAV = INT(THRU * LAM) / INT(THRU)

In these fromulas, INT() denotes the integral with repect to lambda, SQRT() denotes square root, LN() the natural logarithm, and MAX() the maximum function. The variable LAM is wavelength, THRU is the total throughput, which is a function of wavelength, AREA is the telescope area, and H and C are the usual physical constants.

(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 passband is non-zero. Wavelengths are spaced logarithmically over this range. If there is more than one passband, the range is computed based on the first passband. 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 = "mtab$*.tmc"  Instrument component table.  By 
        default, this uses the most recent version.

EXAMPLES

1. Calculate the combined instrumental throughput of the HRS using the large science aperture (lsa) and the G270M grating. Store the throughput data in a table called hrs.tab.

sy> calcband "band(hrs,lsa,g270m)" hrs

2. The following command computes the same combined throughput using the abbreviated form of the obsmode string.

sy> calcband "hrs,lsa,g270m" hrs

3. Create a Gaussian passband, multiplied by a first-order Legendre polynomial and write the results to a table called gauss_tilt.tab.

sy> calcband "tilt(gauss(4800,1300),10)" gauss_tilt

REFERENCES

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

SEE ALSO

plband, calcspec