SEE_ALSO

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