STScI Logo

simspec stsdas.hst_calib.synphot.simulators


NAME · USAGE · DESCRIPTION_ · PARAMETERS · EXAMPLES_ · BUGS_
REFERENCES · SEE_ALSO

NAME

simspec -- Two-dimensional HST spectral instrument simulator

USAGE

simspec obsmode input output

DESCRIPTION

This task computes a simulated image for spectral instruments with two-dimensional formats on the HST. Currently, the only such instrument for the HST is the STIS. This task computes a spectral image for long slit and echelle modes, given the observing configuration and the object description table. For each spectral order, the object shapes are convolved with the PSF, masked by the spatial extent of the slit, and optionally maked in the dispersion direction by the appropriate line spread function. Each order is then mapped onto the detector pixels. tHe task also optionally models and add the celestial and/or instrument background, and introduces noise that is appropriate for the specified instrument/detector combination.

The observing configuration (or "observation mode") is a list of space- or comma-separated keywords that uniquely describe the instrument used and its configuration. Typical observation modes name the instrument, filters, and grating. (A list of valid observation mode keywords can be generated by running the `obsmode' task.) The input table describes up to five attributes for each object to be modelled, including its position, brightness, and spatial orientation and extent. The format of the table is described in detail below. The output is an image (in any supported IRAF format) which contains the spectra of all the input objects that fall within the instrument's field of view.

The calculated background has contributions due to zodiacal light, earthlight, and thermal background. Zodiacal light is a function of the relative position of the telescope and sun. The telescope position is set by task parameters "det_ra" and "det_dec", the sun position is set by task parameter "time", which controls the date of the observation. Yhe earthlight background is calculated from task parameter "earthtab", which specifies the maximum earthlight spectrum, and task parameter "eshine", which specifies a fraction of the maximum eathlight. The thermal background is calculated from "thermtab", which specifies the spectrum of the thermal background.

PARAMETERS

obsmode [string]
Telescope observation mode. The observation mode is a comma- or space-separated list of keywords that specifies a valid light path through the telescope. The observation mode is used to compute the instrument throughput, and select the point spread function and detector dimensions.
input [string]
Object description table. The table contains one row for each object to be simulated. It has up to five columns, containing the x position, y position, magnitude, spectrum, and shape. If the table is a text table, the columns must be in this order; the x and y positions are in seconds of arc relative to the detector center. If the table is a binary table, column names are specified by the task parameter "colnames" and the units of right ascension and declination are specified by the column units. Type 'help simulators opt=sysdoc' for more information about the format of the input file, particularly for information about the shape functions.
output [string]
Output image name. The result of running this task is a single group image whose dimensions are set according to the detector that is to be simulated.
(exptime = 1.0) [real] [min = 0.0] [max = INDEF]
Observation exposure time in seconds.
(nread = 1) [int] [min = 1, max = INDEF]
Number of detector reads to obtain the final image. Most of the HST instruments offer the capability of taking more than one exposure on a target in order to reduce the detector read noise and/or detect cosmic rays. This parameter will be used in conjuction with the expression for detector noise to determine the final noise level for the output image.
(verbose = no) [bool]
If this parameter is set to yes, the task prints diagnostic messages describing the progress of the program to STDERR.
(cenwave = INDEF) [real] [min = 1, max = 1e6]
If this task parameter is not INDEF, the task changes the grating tilt so that this wavelength falls in the center of the detector. The cenorder task parameter must also be set if the observation mode is an echelle mode.
(cenorder = INDEF) [int] {min = 1, max = 1000]
This task parameter works with cenwave to specify the echelle order containing the central wavelength, if the observation mode is an echelle mode.
(lsf_flag = no) [bool]
Use the line spread function? If this parameter is set to yes, the object will be convolved with the line spread function, which represents the diffraction effects of the aperture.
(dsf_flag = no) [bool]
Use the detector point spread function? The detector point spread function quantifies how charge "leaks" from a point source on the detector. Its application is controlled by this flag because the required convolution of the output image with the point spread function is computationally expensive.
(calcback = yes) [bool]
Add calculated background to the output image? If this task parameter is set to yes the task will calculate a background and add it to the output image.
(calcnoise = yes) [bool]
Add calculated noise to the output image? If this task parameter is set to yes the task will calculate a poisson random noise with zero mean and add it to the output image.
(quant = no) [bool]
If this parameter is set to yes, counts in each pixel are rounded to the nearest whole number. This allows simulation of the quantization error of the instruments.
(verbose = no) [bool]
If this parameter is set to yes, the task prints diagnostic messages describing the progress of the program to STDERR.
(det_ra = 0.0) [real] [min = 0.0] [max = 24.0]
Right ascension (in hours) of the center of the detector aperture.
(det_dec = 0.0) [real] [min = -90.0] [max = 90.0]
Declination (in degrees) of the center of the detector aperture.
(det_ang = 0.0) [real]
Detector position angle (in degrees) relative to equitorial coordinates. The position angle is measure counterclockwise from north.
(noise = none) [string]
If this task parameter is present, the noise expression will be taken from it instead of being read from the noise keyword in the throughput table header. If it is blank or set to none, the noise expression will be read from the throughput tables. The syntax of the noise expression is explained in the help file for simnoise.
(backfile = "none") [string]
The name of the background image to be added to the output image. The image must be two dimensional and be the same size as the output iamge. If this task parameter is set to "none" (the default) or left blank, no background image will be added to the output.
(noisefile = "none") [string]
The name of the noise image to be added to the output image. The image must be two dimensional and be the same size as the output iamge. If this task parameter is set to "none" (the default) or left blank, no noise image will be added to the output. The distinction between the background and noise image is that the background image is added before flat fielding and the noise image is added after flat fielding.
(wavetab = "none") [string]
Wavelength table An appropriate table can be generated by using the `genwave' task. If a binary table is used, the wavelength column name must be WAVELENGTH. If a text table is used the first column is taken to be the wavelength column. The subdirectory synphot$data has text 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 telescope and magnitude passbands are non-zero. Wavelengths are spaced logarithmically over this range.

(simmodp = "") [pset]
The parameter set containing the model parameters. These are:
(magband = "v") [string]
Passband of object magnitude. The flux of each object is renormalized so that it has the indicated magnitude in the passband specified by magband. The default passband in the Johnson V passband. Other filter systems include "cousins", "landolt", and "stromgren"; see the Synphot User's Guide (Appendix A) for details.
(magform = "vegamag") [string]
Form of object magnitude. 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.
(colnames = "ra dec mag spectrum shape") [string]
Input file column names. The column names specify which columns the right ascension, declination, magnitude, spectrum and object shape are read from, respectively. The column names in the list are separated by commas or spaces. The list may contain fewer than five names, in which case the omitted columns are assumed not to be present in the table and default names are used instead. This task parameter is not used if the input file is a text file.
(dynrange = 1000.) [real] [min = 1.] [max = 1e7]
Dynamic range of the object fluxes distribution. Extended objects and PSFs are truncated when the flux falls to 1/dynrange of its central value.
(nsub = 5) [int] [min = 1] [max = 100]
Number of pixel subdivisions. Results are calculated on a finer grid than the detector's pixel spacing. The number of subpixels along each linear dimension of the pixel is nsub, so the total number of subpixels is nsub ** 2.
(simbackp = "") [pset]
The parameter file containing the noise and background parameters. These are:
(eshine = 0.0) [real] [min = 0.0] [max = 1.0]
Fraction of maximum earhlight to include in spectrum
(time = "Jun 1997 1:55:42 PM") [string]
The time of the observation. The time is used to compute solar position. The background light is a function of the angle between the sun and the telescope, so this date controls the background light contribution. All times are UT (Universal time). The time may be entered in a variety of formats. The month field must be first, followed by the day of month and year. All other fields are optional and will be set to zero if omitted. Fields must be separated by one non-alphanumeric character. Months may be specified by number or any unique abbreviation of the English name.
(seed = 42) [int]
The seed for the random number generator used by the noise model.
(simcatp = "") [pset]
The parameter set containing the file and catalog parameters. These are:
(spectrum = "crcalspec$alpha_lyr_001.tab") [string]
Default spectrum. If a row in the input table does not contain a spectrum field or the field is left blank, the default spectrum will be used instead. This task parameter is mainly intended for reading star positions from catalogs that do not contain a spectral type.
(psfcat = "scidata$synphot_psf.cat") [string]
Point spread function or catalog of point spread functions. If the file is an image, the task will use it as the sole point spread function. If it is not, the task will treat the file as a catalog of point spread functions. The catalog is in the form of a table with three columns: the observation mode, the PSF wavelength, and the filename that contains the PSF image. If the catalog is a binary table, these columns are named OBSMODE, WAVELENGTH, and FILENAME. If the catalog is a text table, they are the first, second, and third table columns. Point spread functions are selected for use if the input observation mode is a superset of the observation mode in the table. The PSF convolved with each object is computed by weighting the selected PSFs according to the flux in the object spectrum. Pixels in each point spread function image are assumed to be square. The size of the pixel is calculated from the world coordinate information (the CD matrix) in the image header. If the CD matrix is zero, a warning message is printed and the pixel scale is assumed to be that of the detector. If the header keywords XCENTER and YCENTER are present, the PSF center is read from these keywords. Otherwise, The PSF is assumed to be approximately centered in the image, and the task takes the pixel with the maximum value in a small box in the center of the PSF to be the central pixel.

The current default catalog contains PSF images for the Nicmos and Wfpc2. If you are using other instruments, you will have to create your own catalog or PSF image.

(lsfcat = " ") [string]
Line spread function or catalog of line spread functions. If the file is an image, the task will use it as the sole line spread function. If it is not, the task will treat the file as a catalog of line spread functions. The structure of the catalog and method of selection is the same as for the point spread function. The size of the pixel is calculated from the world coordinate information (the CD matrix) in the image header. If the CD matrix is zero, a warning message is printed and the pixel scale is assumed to be that of the detector. If the header keyword CENTER is present, the LSF center is read from this keyword. Otherwise, the center is assumed to be the pixel with the maximum value. If more than one pixel has the maximum value, their positions are averaged.
(dsfcat = " ") [string]
Detector point spread function or catalog of point spread functions. If the file is an image, it will use it as the sole detector point spread function. If it is not, the task will treat the file as a catalog of detector point spread functions. If the catalog is a binary table, it has two columns: OBSMODE and FILENAME. If the catalog is a text table these are the first and second columns respectively. The detector point spread function is selected by matching the input observation mode with an observation mode in the catalog. The size of pixels in the detector point spread function are calculated from the world coordinate information in the image header, just as for the point and line spread functions. If the header keywords XCENTER and YCENTER are present, the PSF center is read from these keywords. Otherwise, The PSF is assumed to be approximately centered in the image, and the task takes the pixel with the maximum value in a small box in the center of the PSF to be the central pixel.
(detcat = "simulators$data/detectors.dat") [string]
Catalog of detector dimensions. The catalog is a table containing four columns: the observation mode, the pixel scale, the number of pixels in the X dimension, and the number of pixels in the Y dimension. If the catalog is a binary table, the columns are named OBSMODE, SCALE, NX and NY. If it is a text table, they are the first through fourth columns. The row in the catalog is selected if the input observation mode is a superset of the catalog observation mode. If the table is a binary table, the units of the detector scale are read from the SCALE column units. If the table is a text table, the units are assumed to be arcseconds.
(apercat = "simulators$data/apertures.dat") [string]
Catalog of aperture shapes. The catalog is a table containing two columns: OBSMODE and SHAPE. If the catalog is a text table, these are the first and second columns, respectively. The row where the input observation mode matches the catalog observation mode is selected. The aperture shape is specified as a function call. Type 'help simulators opt=sysdoc' for more information about the shape function names and arguments.
(gratecat = "simulators$data/gratings.dat") [string]
Catalog of grating dispersion parameters. The catalog has fifteen columns. The first column is the OBSMODE column and is used to select a row from the catalog. The remaining columns are M1, the first spectral order modelled, M2, the last spectral order modelled, SIZE, the detector size in milimeters, F, the focal length in milimeters, GY, the grating lines per milimeter, BETA_Y, the grating blaze angle in degrees, SIGMA_Y, the half angle between the collimator and disperser parallel to the ruling, DELTA_Y, the half angle between the grating and ruling perpendicular to the ruling, THETA_Y, the grating scan angle, and GX, BETA_X, SIGMA_X, DELTA_X, and THETA_X, the same quantities for the cross-disperser grating. If there is no cross disperser, these last columns are set to zero. If the catalog is a text table, it has the same fifteen columns in the order described here.
(limitcat = "simulators$data/limits.dat") [string]
Catalog of count rate limits. The task prints a warning message whenever these limits are exceeded. The catalog has five columns. The first is the OBSMODE column and it is used for selecting a row from the catalog. The remaining columns are LOCALCOUNT, the local count rate limit, GLOBALCOUNT, the global count rate limit, LOCALBRIGHT, the local bright object limit, and GLOBALBRIGHT, the global bright object limit. If the catalog is an ascii table, the second through fourth columns contain the same information in the order described here.
(flatcat = "simulators$data/flatfields.dat") [string]
Catalog of inverse flat fields. The inverse flat field tracks the sensitivity of the detector as a function of position. The output image is multiplied by the flat field before noise is added. The flat field images must have the same size as the detector.
(zodtab = "simulators$data/zodiac.dat") [string]
A table of zodiacal light flux. The units of the flux are tenth magnitude solar type stars per square degree. The table is a function of ecliptic latitude and heliocentric longitude of the detector. The heliocentric longitude is the absolute value of the difference of the ecliptic longitude of the detector and the sun. The first row in the table contains the latitudes and the first column contains the longitudes at which the flux values are tabulated. The default table is taken from "A.C. Levasseur-Regourd and R. Dumont, "Absolute Photometry of Zodiacal Light," Astr. and Ap., 84, 277 (1980)". If the table name is blank or set to none, the zodiacal contribution to the background will be omitted.
(earthtab = "simulators$data/earth.dat") [string]
The earthlight spectrum at its maximum value. The flux is given in units per square arcseond. If the table name is blank or set to none, the earthlight contribution to the background will be omitted.
(thermtab = "simulators$data/thermal.dat") [string]
The thermal background spectrum. The flux is given in units of square arcsecond. If the table name is blank or set to none, the thermal contribution to the background will be omitted.
(refdata = "") [pset]
The parameter set for reference data used in calculations. This pset contains the following parameters:
(area = 45238.93416) [real]
HST telescope area in cm**2.
(grtbl = "mtab$*.tmg") [string]
HST graph table. By default, this uses the most recent version.
(cmptbl = "mtab$*.tmc") [string]
Instrument component table. By default, this uses the most recent version.

EXAMPLES

1. Simulate an observation of a star by the STIS using the g140m grating and the s01x003 grating. The object file contains the line:

0.0	0.0	15.0	bb(5e4)

Using the FUV detector PSF image available from the STScI STIS web pages, run the task with the command:

    cl> simspec stis,g140m,s01x003,all object.dat output.hhh \
    >>> psfcat=fuv_psf.fits

BUGS

The code which convolves extended objects with the psf is slow.

REFERENCES

Written by Bernie Simon.

SEE ALSO

calcspec, obsmode, ttools.tcreate


Source Code · Package Help · Search Form · STSDAS