STScI Logo

simimg stsdas.hst_calib.synphot.simulators


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

NAME

simimg -- Two-dimensional HST imaging instrument simulator

USAGE

simimg obsmode input output

DESCRIPTION

This task computes a simulated image for HST instruments with two-dimensional formats (FOC, WFPC, WFPC2, and NICMOS), given an observing configuration and a table describing the objects to be simulated. This task will compute the distribution of light on the detector, convolve it with the point-response function (PSF), and normalize it to the computed throughput for each object. It will also optionally model and add the celestial and/or instrument background, and introduce 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 detector. (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 all the input objects that fall within the instrument's field of view.

The addition of background and noise are controlled by the three task parameters, "calcback", "calcnoise", and "backfile". Calcback and calcnoise control the addition of calculated background and noise, respectively, and backfile control the addition of background from a file. Calcback and calcnoise are boolean flags and the respective calculations are done if their values are yes. Backfile is a string containing the name of the background file to be added to the output. No background file will be added if the parameter is blank or set to "none". All three switches are independent, one can have all three or none of the types of background added to an image.

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 right ascension, declination, magnitude, spectrum, and shape. If the table is a text table, the columns must be in this order; the right ascension must be in hours and the declination must be in degrees. 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.
(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.
(skycoord = yes) [bool]
Use sky coordinates for object position? If this parameter is yes, object coordinates are right ascension and declination. If this parameter is no, object coordinates are arcseconds from the detector aperture center.
(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.
(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.

(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.
(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 on the edge of an elliptical galaxy with detector 2 the WFPC-2 camera, using the F555W filter. First, create an input file named "object.dat" containing the two lines:

00:00:00    00:00:00    15.0    bb(4000)    devauc(00:00:01,.5,0)
00:00:00    00:00:01	14.0    bb(10000)

Then run this task with the command:

    cl> simimg wfpc2,f555w,2 object.dat output.hhh

BUGS

The code which convolves extended objects with the psf is slow. No good PSF catalog has been created yet.

REFERENCES

Written by Bernie Simon.

SEE ALSO

calcspec, obsmode, ttools.tcreate


Source Code · Package Help · Search Form · STSDAS