sptime: Spectroscopic exposure time calculator

Package: obsutil

Usage

sptime

Parameters

The parameters in this task have certain common features.

(1)
All parameters, except spectrograph and search, may be specified as spectrograph table parameters of the same name. Some parameters may also be specified in other tables. The tables in which the paramters may be specified are shown in brackets. Table values are used only if a string parameter is "" or a numeric parameter is INDEF. Therefore parameter set values override values in the tables. To override a table specified in the spectrograph file by no file the special value "none" is used. This task also uses default values, shown below in parenthesis, for parameters that have no value specified either in the parameter set or in a table.
(2)
Parameters that specify a table take the value of a file or a numeric constant. A constant is like a table with the same values for all value of the independent variable(s).
(3)
Tables which are specified as filenames are sought first in the current working directory, then in one of the directories given by the search parameter, and finally in the package library directory sptimelib$.
time = INDEF (INDEF) [spectrograph]
Total exposure time in seconds. This time may be divided into shorter individual exposure times as defined by the maxexp parameter. If the value is INDEF then the exposure time needed to achieve the signal-to-noise per pixel specified by the sn parameter is computed.
sn = 25. (25.) [spectrograph]
Desired signal-to-noise per pixel at the central wavelength if the exposure time parameter is not specified.

The following parameters define the source and sky/atmosphere background spectra.

spectrum = "blackbody"
Source spectrum. This may be a table or one of the following special words:
blackbody
Blackbody spectrum with temperature given by the temperature parameter.
flambda_power
Power law in f(lambda) with index given by the index parameter; f(lambda) proportional to lambda^(index).
fnu_power
Power law in f(nu) with index given by the index parameter; f(nu) proportional to nu^(index).
The table is a two column text file of wavelength in Angstroms and flux in ergs/s/cm^2/A.
spectitle = "" [spectrum|spectrograph]
Spectrum title.
E = 0. (0.) [spectrum|spectrograph]
The E(B-V) color excess to apply a reddening to the source spectrum. The reddening maintains the same table or reference flux at the reference wavelength. A value of zero corresponds to no reddening.
R = 3.1 (3.1) [spectrum|spectrograph]
The R(V) = A(V)/E(B-V) for the extinction law. The extinction law is that of Cardelli, Clayton, and Mathis, ApJ 345:245, 1989. The default R(V) is typical of the interstellar medium.
sky = "" ("none") [spectrograph]
Sky or background table. The table is a two or three column text file consisting of wavelength in Angstroms, optional moon phase between 0 (new moon) and 14 (full moon), and flux in ergs/s/cm^2/A/arcsec^2.
skytitle = "" [sky|spectrograph]
Sky title.
extinction = "" ("none") [spectrograph]
Extinction table. The table is a two column text file consisting of wavelength in Angstroms and extinction in magnitudes per airmass.
exttitle = "" [spectrograph]
Extinction title.

The following parameters are used with the source spectrum is specified by the special functions.

refwave = INDEF (INDEF) [spectrum|spectrograph]
Reference wavelength, in units given by the units parameter, defining the flux of the source. This is also used as the wavelength where reddening does not change the spectrum flux. A value of INDEF uses the observation central wavelength.
refflux = 10. (10.) [spectrograph]
Reference source flux or magnitude at the reference wavelength for the model spectral distributions. The units are specified by the funits parameter.
funits = "AB" ("AB") [spectrograph]
Flux units for the reference flux. The values are "AB" for monochromatic magnitude, "F_lambda" for ergs/s/cm^2/A, "F_nu" for ergs/s/cm^2/Hz, and standard bandpasses of U, B, V, R, I, J, H, Ks, K, L, L' and M.
temperature = 6000. (6000.) [spectrograph]
Blackbody temperature for a blackbody source spectrum in degrees Kelvin.
index = 0. (0.) [spectrograph]
Power law index for the power law source spectrum.

The following parameters are observational parameters describing either the observing conditions or spectrograph setup.

seeing = 1. (1.) [spectrograph]
The full width at half maximum (FWHM) of a point source in arc seconds.
airmass = 1. (1.) [spectrograph]
The airmass of the observation. This is only used if an extinction table is specified.
phase = 0. (0.) [spectrograph]
The moon phase running from 0 for new moon to 14 for full moon. This is used if the sky spectrum is given as a function of the moon phase.
thermal = 0. (0.) [telescope|spectrograph]
Temperature in degress Kelvin for the thermal background of the telescope and spectrograph. If greater than zero a blackbody surface brightness background is computed and multiplied by an emissivity specified by the emissivity table.
wave = INDEF (INDEF) [spectrograph]
Central wavelength of observation in units given by the units parameter. If the value is INDEF it is determined from the efficiency peak of the disperser.
order = INDEF (INDEF) [spectrograph]
Order for grating or grism dispersers. If the value is INDEF it is determined from the order nearest the desired central wavelength. If both the order and central wavelength are undefined the first order is used.
xorder = INDEF (INDEF) [spectrograph]
Order for grating or grism cross dispersers. If the value is INDEF it is determined from the order nearest the desired central wavelength. If both the order and central wavelength are undefined the first order is used.
width = INDEF (-2.) [aperture|spectrograph]
The aperture width (dispersion direction) for rectangular apertures such as slits. Values may be positive to specify in arc seconds or negative to specify in projected pixels on the detector.
length = INDEF (-100.) [aperture|spectrograph]
The aperture length (cross dispersion direction) for rectangular apertures such as slits. Values may be positive to specify in arc seconds or negative to specify in projected pixels on the detector.
diameter = INDEF (-2.) [fiber|aperture|spectrograph]
The aperture diameter for circular apertures. Values may be positive to specify in arc seconds or negative to specify in projected pixels on the detector. If it is found in the fiber table, positive values are treated as mm at the focal plane instead of arc seconds.
xbin = 1 (1) [detector|spectrograph]
Detector binning along the dispersion direction.
ybin = 1 (1) [detector|spectrograph]
Detector binning along the spatial direction.

The following parameters a miscellaneous parameters for the task.

minexp = 0.01 (0.01) [spectrograph]
Minimumm time in seconds per individual exposure time. This only applies when time is INDEF. Adjustment of the exposure time for saturation will not allow the exposure time to fall below this value.
maxexp = 3600. (3600.) [spectrograph]
Maximum time in seconds per individual exposure. The minimum exposure time has precedence over this value. If the total exposure time exceeds this amount by more than 1% then the total exposure time will be divided up into the fewest individual exposures with equal exposure time that are less than this amount. Note that by making the minimum and maximum times the same a fixed integration time can be defined.
units = "Angstroms" ("Angstroms") [spectrograph]
Dispersion units for input and output dispersion coordinates. The units syntax is described in the UNITS section. The most common units are "Angstroms", "nm", "micron", and "wn". Note that this does not apply to the dispersion units in the tables which are always in Angstroms.
skysub = "" (default based on context) [spectrograph]
Type of sky and background subtraction. The values are "none" for no background subtraction, "longslit" for subtraction using pixels in the aperture, "multiap" for background determined from a number of other apertures, and "shuffle" for shuffled observations. The multiap case is typical for fiber spectrographs. For shuffle the duty cycle is 50% and the exposure times are the sum of both sky and object. If no sky or thermal background is specified then the default is "none". If a fiber table or circular aperture is specified the default is "multiap" otherwise the default is "longslit".
nskyaps = 10 (10) [spectrograph]
Number of sky apertures when using "multiap" sky subtraction.
subpixels = 1 (1) [spectrograph]
Number of subpixels within each computed pixel. The dispersion pixel width is divided into this number of equal width subpixels. The flux at the dispersions represented by the subpixels are computed and then summed to form the full pixel flux. This option is used when there is structure in the tables, such as the sky and filter tables to simulate instrumental masking of sky lines, which is finer than a pixel dispersion width.
sensfunc = "" [spectrograph]
Sensitivity function table. This is a two column text file consisting of wavelength in Angstroms and sensitivity defined as 2.5*(log(countrate)-log(flambda)), where countrate is the count rate (without extinction) in counts/s/A and flambda is the source flux in ergs/s/cm^2/A. This table is used to compute an efficiency correction given a measurement of the sensitivity function from standard stars for the instrument.

The following parameters control the output of the task. The task always prints a result page at the central wavelength but additional graphical and text output may be produced at a set of equally spaced points across the size of the detector.

output = "object" ("") [spectrograph]
List of quantities to output as graphs and/or in a text file. These are given as a function of dispersion (as specified by units parameters) sampled across the dispersion coverage of the detector. The choices are:
counts
Object and background counts per individual exposure.
snr
Signal-to-noise ratio per pixel per individual exposure.
object
Object counts per individual exposure. This includes contribution from other orders if there is no cross dispersion and the blocking filters do not completely exclude other orders.
rate
Photons/second/A per individual exposure for the object and background.
atmosphere
Percent transmission of the atmosphere.
telescope
Percent transmission of the telescope.
adc
Percent transmission of the ADC if one is used.
aperture
Percent transmission of the aperture.
fiber
Percent transmission of the fiber if one is used.
filter
Percent transmission of the first filter if one is used.
filter2
Percent transmission of the second filter if one is used.
collimator
Percent transmission of the collimator.
disperser
Percent efficiency of the disperser.
xdisperser
Percent efficiency of the cross disperser if one is used.
corrector
Percent transmission of the corrector if one is used.
camera
Percent transmission of the camera.
detector
Percent DQE of the detector.
spectrograph
Percent transmission of the spectrograph if a transmission function is defined.
emissivity
Emissivity of the telescope/spectrograph if an emissivity function is defined.
thruput
Percent system thruput from telescope to detected photons.
sensfunc
Sensitivity function values given as 2.5*(log(countrate)-log(flambda)), where countrate is the count rate (without extinction) in counts/s/A and flambda is the source flux in ergs/s/cm^2/A.
correction
Multiplicative correction factor needed to convert the computed count rate to that given by an input sensitivity function.
ALL
All of the above.
nw = 101 (101) [spectrograph]
Number of dispersion points to use in the output graphs and text file. Note that this is generally less than the number of pixels in the detector for execution speed.
list = "" [spectrograph]
Filename for list output of the selected quantities. The output will be appended if the file already exists.
graphics = "stdgraph" ("stdgraph") [spectrograph]
Graphics output device for graphs of the output quantities.
interactive = "yes" ("yes") [spectrograph]
Interactive pause after each graph? If "yes" then cursor input is enabled after each graph otherwise all the graphs will be drawn without pause. When viewing the graphs interactively this should be "yes" otherwise the graphs will flash by rapidly leaving the last graph on the screen. When outputing only one graph or when redirecting the graphs to a printer or file then setting this parameter to "no" is suggested.

The last parameter is a "parameter set" ("pset") containing all the spectrograph parameters.

specpars = ""
Spectrograph parameter set. If "" then the default pset specpars is used otherwise the named pset is used.

SPECPARS PARAMETERS

spectrograph = ""
Spectrograph efficiency table. This text file may contain parameters and an efficiency table. The table consists of two columns containing wavelengths and efficiencies. The efficiencies are for all elements which are not accounted for by other tables.
title = "" [spectrograph]
Title for the spectrograph.
apmagdisp = INDEF (1.), apmagxdisp = INDEF (1.) [spectrograph]
Magnification between the entrance aperture and the detector along and across the dispersion direction. This describes any magnification (or demagnification) in the spectrograph other than that produced by the ratio of the collimator and camera focal lengths and anamorphic magnification from the disperser. The may consist of actual magnification optics or projection effects such as tilted aperture plates (when the aperture size is specified in the untilted plate).
inoutangle = INDEF (INDEF) [spectrograph]
Incident to diffracted grating angle in degrees for grating dispersers. For typical spectrographs which are not cross dispersed this is the collimator to camera angle. If the value is INDEF derived from the grating parameters.
xinoutangle = INDEF (INDEF) [spectrograph]
Incident to diffracted grating angle in degrees for grating cross dispersers. If the value is INDEF it is derived from the grating parameters.
telescope = "" [spectrograph]
Telescope efficiency table as a function of wavelength.
teltitle = "" [telescope|spectrograph]
Telescope title.
area = INDEF (1.) [telescope|spectrograph]
Effective collecting area of the telescope in m^2. The effective area includes reductions in the primary area due to obstructions.
scale = INDEF (10.) [telescope|spectrograph]
Telescope plate scale, in arcsec/mm, at the entrance aperture of the spectrograph.
emissivity = "" [telescope|spectrograph]
Emissivity table. The emissivity is for all elements in the telescope and spectrograph. If an emissivity is specified and an the thermal temperature parameter is greater than zero then a thermal background is added to the calculation.
emistitle = "" [emissivity|spectrograph]
Title for the emissivity table used.
corrector = "" [spectrograph]
Efficiency table for one or more correctors.
cortitle = "" [corrector|spectrograph]
Title for corrector table used.
adc = "" [spectrograph]
Efficiency table for atmospheric dispersion compensator.
adctitle = "" [adc|spectrograph]
Title for ADC table used.
disperser = "" [spectrograph]
Disperser table. If this file contains an efficiency table it applies only to first order. An alternate first order table and tables for other orders are given by table parameters "effN", where N is the order.
disptitle = "" [disperser|spectrograph]
Title for disperser.
disptype = "" ("grating") [disperser|spectrograph]
Type of disperser element. The chocies are "grating", "grism", or "generic". The generic setting will simply use the desired central wavelength and dispersion without a grating or grism model. One effect of this is that the mapping between detector pixel and wavelength is linear; i.e. a constant dispersion per pixel.
gmm = INDEF (300.) [disperser|spectrograph]
Ruling in lines per mm. If not specified it will be derived from the other disperser parameters. If there is not enough information to derive the ruling then an ultimate default of 300 lines/mm is used.
blaze = INDEF (6.) [disperser|spectrograph]
Blaze (grating) or prism (grism) angle in degrees. If not specified it will be derived from the other disperser parameters. If there is not enough information to derive the angle then an ultimate default of 6 degrees is used.
oref = INDEF (1) [disperser|spectrograph]
When a central (blaze) wavelength is specified this parameter indicates which order it is for.
wavelength = INDEF (INDEF) [disperser|spectrograph]
Central (blaze) wavelength in Angstroms for the reference order. This parameter only applies to gratings. If it is not specified it will be derived from the other disperser parameters.
dispersion = INDEF (INDEF) [disperser|spectrograph]
Central dispersion in A/mm for the reference order. This parameter only applies to gratings. If it is not specified it will be derived from the other disperser parameters.
indexref = INDEF (INDEF) [disperser|spectrograph]
Grism index of refraction for the reference order. This parameter only applies to grisms. If it is not specified it will be derived from the other disperser parameters.
eff = INDEF (1.) [disperser|spectrograph]
Peak efficiency for the theoretical disperser efficiency function. When an efficiency table is not specified then a theoretical efficiency is computed for the disperser. This theoretical efficiency is scaled to peak efficiency given by this parameter.
xdisperser = "" [spectrograph]
Crossdisperser table. If this file contains an efficiency table it applies only to first order. An alternate first order table and tables for other orders are given by table parameters "xeffN", where N is the order.
xdisptitle = "" [xdisperser|spectrograph]
Title for crossdisperser.
disptype = "" ("grating") [xdisperser|spectrograph]
Type of crossdisperser element. The chocies are "", "grating", "grism", or "generic". The empty string eliminates use of a cross disperser. The generic setting will simply use the desired central wavelength and dispersion without a grating or grism model. One effect of this is that the mapping between detector pixel and wavelength is linear; i.e. a constant dispersion per pixel.
gmm = INDEF (INDEF) [xdisperser|spectrograph]
Ruling in lines per mm. If not specified it will be derived from the other crossdisperser parameters.
xblaze = INDEF (6.) [xdisperser|spectrograph]
Blaze (grating) or prism (grism) angle in degrees. If not specified it will be derived from the other crossdisperser parameters.
xoref = INDEF (1) [xdisperser|spectrograph]
When a central (blaze) wavelength is specified this parameter indicates which order it is for.
xwavelength = INDEF (INDEF) [xdisperser|spectrograph]
Central (blaze) wavelength in Angstroms for the reference order. This parameter only applies to gratings. If it is not specified it will be derived from the other crossdisperser parameters.
xdispersion = INDEF (INDEF) [xdisperser|spectrograph]
Central dispersion in A/mm for the reference order. This parameter only applies to gratings. If it is not specified it will be derived from the other crossdisperser parameters.
xindexref = INDEF (INDEF) [xdisperser|spectrograph]
Grism index of refraction for the reference order. This parameter only applies to grisms. If it is not specified it will be derived from the other crossdisperser parameters.
xeff = INDEF (1.) [xdisperser|spectrograph]
Peak efficiency for the theoretical crossdisperser efficiency function. When an efficiency table is not specified then a theoretical efficiency is computed for the crossdisperser. This theoretical efficiency is scaled to peak efficiency given by this parameter.
aperture = "" (default based on context) [spectrograph]
Aperture table. The text file gives aperture thruput as a function of the aperture size in units of seeing FWHM. For rectangular apertures there are two independent variables corresponding to the width and length while for circular apertures there is one independent variable corresponding to the diameter. If not specified a default table is supplied. If a fiber table or a diameter is specified then the table "circle" is used otherwise the table "slit" is used. Because "sptimelib$" is the last directory searched there are default files with these names in this directory for Gaussian seeing profiles passing through a circular or slit aperture.
aptitle = "" [aperture|spectrograph]
Title for aperture used.
aptype = "" (default based on context) [aperture|spectrograph]
The aperture types are "rectangular" or "circular". If the parameter is not specified then if the aperture table has two columns the type is "circular" otherwise it is "rectangular".
fiber = "" [spectrograph]
Fiber transmission table. The transmission is a function of wavelength in Angstroms. If no fiber transmission is specified then no fiber component is included.
fibtitle = "" [fiber|spectrograph]
Title for fiber transmission used.
filter = "" [spectrograph]
Filter transmission table. The transmission is a function of wavelength in Angstroms. If no filter transmission is specified then no filter component is included.
ftitle = "" [filter|spectrograph]
Title for filter transmission used.
filter2 = "" [spectrograph]
Filter transmission table. The transmission is a function of wavelength in Angstroms. If no filter transmission is specified then no filter component is included.
f2title = "" [filter|spectrograph]
Title for filter transmission used.
block = "" ("no") [filter|spectrograph]
If "yes" then no check will be made for other orders.
collimator = "" (1.) [spectrograph]
Collimator transmission table. The transmission is a function of wavelength in Angstroms. If no collimator is specified then a unit transmission is used.
coltitle = "" [collimator|spectrograph]
Title for collimator.
colfl = INDEF (1.) [collimator|spectrograph]
Collimator focal length in meters. The ratio of the collimator to camera focal lengths determines the magnification between the aperture and the detector.
camera = "" (1.) [spectrograph]
Camera transmission table. The transmission is a function of wavelength in Angstroms. If no camera is specified then a unit transmission is used.
camtitle = "" [camera|spectrograph]
Title for camera.
camfl = "" (1.) [camera|spectrograph]
Camera focal length in meters. The ratio of the collimator to camera focal lengths determines the magnification between the aperture and the detector. The camera focal length also determines the dispersion scale at the detector.
resolution = "" (2 pixels) [camera|spectrograph]
Camera resolution on the detector in mm.
vignetting = "" (1.) [camera|spectrograph]
Vignetting table. The independent variable is distance from the center of the detector in mm. The value is the fraction the light transmitted. If no vignetting table is specified then no vignetting effect is applied.
detector = "" (1.) [spectrograph]
Detector DQE table. The DQE is a function of wavelength in Angstroms.
dettitle = "" [detector|spectrograph]
Title for detector.
ndisp = INDEF (2048) [detector|spectrograph]
Number of pixels along the dispersion.
pixsize = INDEF (0.02) [detector|spectrograph]
Pixel size (assumed square) in mm.
gain = INDEF (1.) [detector|spectrograph]
The conversion between photons and detector data numbers or counts. This is given as photons/ADU where ADU is analog-to-digital unit.
rdnoise = INDEF (0.) [detector|spectrograph]
Readout noise in photons.
dark = INDEF (0.) [detector|spectrograph]
Dark count rate in photons/s.
saturation = INDEF [detector|spectrograph]
Number of detected photons in a pixel resulting in saturation. The default is no saturation. The time per exposure will be reduced, but no lower than the minimum time per exposure, and the number of exposures increased to try and avoid saturation.
dnmax = INDEF [detector|spectrograph]
Maximum data number or ADU allowed. The default is no maximum. The time per exposure will be reduced, but no lower than the minimum time per exposure, and the number of exposures increased to try and avoid overflow.
xbin = 1 (1) [detector|spectrograph]
Detector binning along the dispersion direction.
ybin = 1 (1) [detector|spectrograph]
Detector binning along the spatial direction.

Discussion

OVERVIEW

The spectroscopic exposure time package, SPECTIME, consists of a general calculation engine, SPTIME, and a collection of user or database defined IRAF scripts. The scripts are one type of user interface for SPTIME. Other user interfaces are Web-based forms and IRAF graphics/window applications. The user interfaces customize the general engine to specific spectrographs by hiding components and parameters not applicable to that spectrograph and guiding the user, through menus or other facilities, in the choice of filters, gratings, etc. However, SPTIME is a standard IRAF task that can be executed directly.

SPTIME takes an input source spectrum (either a reference blackbody, a power law, or a user spectrum), a background "sky" spectrum and a instrumental thermal background, reddening to apply to the spectrum, observing parameters such as exposure time, central wavelength, seeing, airmass, and moon phase, instrument parameters such as aperture sizes and detector binning, a description of the spectrograph, and produces information about the expected signal and signal-to-noise ratio in the extracted one-dimensional spectrum. The output consists of a description of the observation, signal-to-noise statistics, and optional graphs and tables of various quantities as a function of wavelength over the spectrograph wavelength coverage.

SPTIME models a spectroscopic system as a flow of photons from a source to the detector through various optical components. Background photons from the sky, atmosphere, and the thermal emission from the telescope and spectrograph are added. It then computes signal-to-noise ratios from the detected photons of the source and background and the instrumental noise characteristics. The spectroscopic system components are defined at a moderate level of detail. It is not so detailed that every optical element has to be described and modeled and not so coarse that a single throughput function is used (though one is free to put all the thruput information into one component). Not all components modeled by the task occur in all spectroscopic systems. Therefore many of the components can be left out of the calculation.

The components currently included in SPTIME are: 

- the atmosphere (extinction and IR transmission)
- the telescope (all elements considered as a unit)
- an optional atmospheric dispersion compensator
- the entrance aperture (slits, fibers, masks, etc.)
- an optional fiber feed
- a spectrograph (for components not represented elsewhere)
- filters
- a collimator
- a disperser (grating, grism, prism, etc)
- a optional cross disperser (grating, grism, prism, etc)
- a corrector (either in the telescope of spectrograph)
- a camera
- a detector

Each of these components represent a transmission function specifying the fraction of incident light transmitted or detected as a function of some parameter or parameters. Except for the aperture, which is a function of the incident source profile (typically the seeing profile) relative to the aperture size, the transmissions of the components listed above are all functions of wavelength.

All the component transmission functions may be specified as either numeric values or as tables. A numeric value is considered to be a special type of table which has the same value at all values of the independent parameters. By specifying only numeric values the task may be run without any table files. To obtain information at a single wavelength this is all that is needed.

To specify a dependence on wavelength or other parameter a text file table with two or more columns may be specified. The tables are interpolated in the parameter columns to find the desired value in the last column. The tables are searched for in the current directory and then in a list of user specified directories. Thus, users may place files in their work area to override system supplied files and observatories can organize the data files in a database directory tree.

In addition to transmission or DQE functions the spectrograph is described by various parameters. All the parameters are described in the PARAMETERS section. For flexibility parameters may be defined either in the parameter set or in one or more table files. In all cases the parameter set values have precedence. But if the values are "" for string parameters or INDEF for numeric parameters the values are found either in the spectrograph table or in a table that is associated with the parameter.

Therefore table files provide for interchangeable components, each with their own transmission curves, and for organizing parameters for different instruments. Note that a table file may contain only parameters, only a table, or both.

There is also another way to maintain a separate file for different instruments. The specpars parameter is a "parameter set" or "pset". The default value of "" corresponds to the pset task specpars. However, using eparam one can edit this pset and then save the parameters to a named parameter file with ":e <name>.par". This pset can be edited with eparam and specified in the specpars parameter. One other point about pset parameters is that they can also be included as command line arguments just as any other parameter in the main task parameters.

Many spectrographs provide a wide variety of wavelength regions and dispersions. For gratings (and to some extent for grisms) this means use of different gratings, orders, tilts, and possibly camera angles in the spectrograph. The transmission as a function of wavelength (the grating efficiency) changes with these different setups. If the transmission function is given as an interpolation table this would require data files for each setup of each disperser. The structure of SPTIME allows for this.

However, it is also possible to specify the grating and spectrograph parameters and have the task predict the grating efficiency in any particular setup. In many cases it may be easier to use the calculated efficiencies rather than measure them. Depending on the level of accuracy desired this may be adequate or deviations from the analytic blaze function can be accounted for in another component.

TABLES

SPTIME uses text files to provide parameters and interpolation tables. The files may contain comments, parameters, and tables.

Comment lines begin with '#' and may contain any text. They can occur anywhere in the file, though normally they are at the beginning of the file.

Parameters are comment lines of the form 

# [parameter] = [value]

where whitespace is required between each field, [parameter] is a single word parameter name, and [value] is a single word value. A quoted string is a single word so if the value field contains whitespace, such as in titles, it must be quoted. Any text following the value is ignored and may be used for units (not read or used by the program) or comments.

The parameters are those described in the PARAMETERS section. The tables in which the parameters may be included are identified in that section in the square brackets. Note that it is generally true that any parameter may appear in the spectrograph table.

The table data is a multicolumn list of numeric values. The list must be in increasing order in the independent columns. Only 1D (two columns) and 2D (three columns) tables are currently supported. 2D tables must form a regular grid. This means that any particular value from column one must occur for all values of column 2 and vice versa. The table is interpolated as needed. The interpolation is linear or bi-linear. Extrapolation outside of the table consists of the taking the nearest value; thus, a single line may be used to define a constant value for all values of the independent variable(s).

Normally the table values, the dependent variable in the last column, are in fractional transmission or DQE. There is a special parameter, "tablescale", which may be specified to multiply the dependent variable column. This would mainly be used to provide tables in percent rather than fraction.

The independent variable columns depend on the type of table. Most tables are a function of wavelength. Currently wavelengths must be in Angstroms.

The types of tables and the units of the columns are listed below. 

    spectrum - Angstroms ergs/s/cm^2/A
         sky - Angstroms ergs/s/cm^2/A/arcsec^2
  extinction - Angstroms mag/airmass
spectrograph - Angstroms transmission
   telescope - Angstroms transmission
  emissivity - Angstroms emissivity
         adc - Angstroms transmission
       fiber - Angstroms transmission
  collimator - Angstroms transmission
      filter - Angstroms transmission
   disperser - Angstroms transmission
  xdisperser - Angstroms transmission
   corrector - Angstroms transmission
      camera - Angstroms transmission
    detector - Angstroms transmission
 sensitivity - Angstroms 2.5*(log(countrate)-log(flambda)),

         sky - Angstroms moonphase ergs/s/cm^2/A/arcsec^2
    aperture - diameter/FWHM transmission
    aperture - width/FWHM length/FWHM transmission
  vignetting - mm transmission

The disperser and crossdisperser files have an additional feature to allow for efficiency curves at different orders. The parameter "effN" (or "xeffN" for crossdispersers), where N is the order, may be specified whose value is a separate table (or constant). If there is no "eff1/xeff1" (efficiency in first order) then any efficiency table in the disperser table is used. In other words, any table in the disperser file applies only to first order and only if there is no "eff1/xeff1" parameter defining a separate first order efficiency file.

DISPERSION UNITS

The output results, text file, and graphs are presented in dispersion units defined by the units parameter. In addition the wave and refwave input parameters are specified in the selected units. All other dispersion values must currently be specified in Angstroms.

The dispersion units are specified by strings having a unit type from the list below along with the possible preceding modifiers, "inverse", to select the inverse of the unit and "log" to select logarithmic units. For example "log angstroms" to select the logarithm of wavelength in Angstroms and "inv microns" to select inverse microns. The various identifiers may be abbreviated as words but the syntax is not sophisticated enough to recognize standard scientific abbreviations except for those given explicitly below. 

   angstroms - Wavelength in Angstroms
  nanometers - Wavelength in nanometers
millimicrons - Wavelength in millimicrons
     microns - Wavelength in microns
 millimeters - Wavelength in millimeters
  centimeter - Wavelength in centimeters
      meters - Wavelength in meters
       hertz - Frequency in hertz (cycles per second)
   kilohertz - Frequency in kilohertz
   megahertz - Frequency in megahertz
    gigahertz - Frequency in gigahertz
         m/s - Velocity in meters per second
        km/s - Velocity in kilometers per second
          ev - Energy in electron volts
         kev - Energy in kilo electron volts
         mev - Energy in mega electron volts

          nm - Wavelength in nanometers
          mm - Wavelength in millimeters
          cm - Wavelength in centimeters
           m - Wavelength in meters
          Hz - Frequency in hertz (cycles per second)
         KHz - Frequency in kilohertz
         MHz - Frequency in megahertz
         GHz - Frequency in gigahertz
          wn - Wave number (inverse centimeters)

The velocity units require a trailing value and unit defining the velocity zero point. For example to transform to velocity relative to a wavelength of 1 micron the unit string would be: 

km/s 1 micron

CALCULATIONS

This section describes the calculations, and assumptions behind the calculations, performed by SPTIME. These include the dispersion and efficiencies of gratings and grisms, the dispersion resolution, the spatial resolution and how it applies to the number of object and sky pixels in the apertures, the object and sky detected photons/counts, the signal-to-noise ratio , and the exposure time for a given S/N.

Gratings

Gratings are assumed to tilted only around the axis parallel to the groves and with the incident angle greater than the blaze angle. The grating equation is then 

g * m * w = sin(tilt+phi/2) + sin(beta)

where g is the number of groves per wavelength unit, m is the order, w is the wavelength, tilt is the grating tilt measured from the grating normal, phi is the angle between the incident and diffracted rays, and beta is the diffracted angle. Phi is a spectrograph parameter and g is a grating parameter. At the desired central wavelength beta is tilt-phi/2 and at the blaze peak it is 2*blaze-tilt-phi/2 where blaze is the blaze angle.

The tilt is computed from the desired central wavelength. It is also used to compute the grating magnification 

magnification = cos(tilt-phi/2) / cos(tilt+phi/2)

which is used in calculating the projected slit size at the detector. This number is less than zero so the aperture is actually demagnified.

The dispersion, treated as constant over the spectrum for the sake of simplicity, is given by the derivative of the grating equation at the blaze peak, 

dispersion = cos(blaze-phi/2) / (g * m * f)

where f is the camera focal length.

The grating efficiency or blaze function is computed as described by Schroeder and Hilliard (Applied Optics, vol 19, 1980, p. 2833). The requirements on the grating noted previously correspond to their case A. As they show, use of incident angles less than the blaze angle, their case B, significantly degrades the efficiency due to back reflection which is why this case is not included. The efficiency formulation includes variation in the peak efficiency due light diffracted into other orders, shadowing of the groves, and a reflectance parameter. The reflectance parameter is basically the blaze peak normalization and does not currently include a wavelength dependence. Thus the peak efficiency is near the reflectance value but somewhat lower and is order dependent due to the other effects.

Grisms

Grisms are assumed to have a prism angle equal to the blaze angle of the inscribed grating. The index of refraction is treated as constant over the wavelength range of an order, though different index of refraction values can be specified for each order.

The grism formula used is a variation on the grating equation. 

g * m * w = n * sin (theta+prism) - sin (beta+prism)

where n is the index of refraction, prism is the prism or blaze angle, theta is the incident angle relative to the prism face, and beta is the refracted angle relative to the prism face. Theta and beta are defined so that at the undeviated wavelength they are zero. In other words at the undeviated wavelength the light path is a straight through transmission.

The efficiency is also computed in an analogous manner to the reflection grating except that shadowing is not included (a consequence of the blaze face being parallel to the prism face and theta being near zero). Instead of a reflectance value normalizing the blaze function a transmission value is used.

Scales and Sizes

The scale between arc seconds on the sky and millimeters at the aperture(s) of the spectrograph is specified by the scale parameter. This parameter is used to convert aperture sizes between arc seconds and millimeters.

The aperture sizes are magnified or demagnified by three possible factors. The basic magnification is given by the ratio of the collimator focal length to the camera focal length. This magnification applies both along and across the dispersion.

The camera focal length also determines the dispersion scale on the detector. It converts radians of dispersion to mm at the detector.

For grating dispersers there is a demagnification along the dispersion due to the tilt of the grating(s). The demagnification is computed (as given previously) from the grating parameters and the spectrograph parameter giving the angle between the incident and diffracted rays at the detector center.

The last magnification factor is given by the spectrograph parameters "apmagdisp" and "apxmagdisp". These define magnifications of the aperture along and across the dispersion apart from the other two magnifications. These parameters are often missing which means no additional magnifications.

One use for the last magnification parameters is to correct aperture sizes given as millimeters or arc seconds on a plane tilted with respect to the focal plane. Such tilted apertures occur with aperture mechanisms (usually slits) that reflect light for acquisition and guiding. Note that one only needs to use these terms if users are expected to define the apertures sizes on the tilted plane. If instead the projection factors are handled by the spectrograph system and users specify aperture size as millimeters or arc seconds on the sky then these terms are not needed.

The above scale factors map arc seconds on the sky and aperture sizes in millimeter to arc seconds and millimeters projected on the detector. To convert to pixels on the detector requires the pixel size. One option in SPTIME is to specify aperture sizes as projected pixels on the detector (either in the user parameters or in the aperture description file). Using the detector pixel size and the scale factors allows conversion of aperture sizes specified in this way back to the actual aperture size.

Resolution

A camera resolution parameter may be set in the camera description. If a resolution value is not given it is taken to be 2 pixels. This parameter is used to define the dispersion resolution element and the number of pixels across the dispersion imaged by the detector for the aperture and the object. The latter usage is discussed in the next section.

The dispersion resolution element, in pixels, is given by 

                             |  2 pixels
disp resolution = maximum of |  camera resolution
                             |  1 + min (seeing, apsize)

where seeing is the FWHM seeing diameter in pixels and apsize is the aperture size in pixels. For circular apertures the aperture size is the diameter and for rectangular apertures it is the width. The first term comes from sampling considerations, the second from the camera resolution, and the third from the finite resolution of a pixel (the factor of 1) and the spread of wavelengths across the aperture or seeing disk. The dispersion resolution is printed for information and the S/N per dispersion resolution element is given in addition to the per pixel value.

Object and Sky Pixels Across the Dispersion

The number of pixels across the dispersion in the object and the sky are required to compute the S/N statistics. The number of pixels in the projected aperture image is taken to be 

                   | diameter + resolution  (circular apertures)
aperture pixels =  |
                   | length + resolution    (rectangular apertures)

where resolution is the camera resolution discussed previously. The value is rounded up to an integer.

Objects are assumed to fill circular (fiber) apertures. Therefore the number of object pixels is the same as the number of pixels in the aperture. In rectangular (slit) apertures the number of object pixels is taken to be 

                            | 3*seeing + resolution
object pixels = minimum of  |
                            | number of aperture pixels

where seeing is the FWHM seeing diameter converted to pixels. The values are rounded up to an integer.

The number of sky pixels depends on the type of sky subtraction. For "longslit" sky subtraction the number of sky pixels is given by the difference of the number of aperture pixels and the number of object pixels. For circular apertures this always comes out to zero so it does not make sense to use longslit sky subtraction. For rectangular apertures the number of sky pixels in the aperture depends on the aperture size and the seeing. If the number of sky pixels comes out to zero a warning is printed.

For "multiap" sky subtraction the number of sky pixels is the number of sky apertures times the number of pixels per aperture.

Source Counts

The source spectrum flux at each wavelength, either given in a spectrum table or as a model distribution, is in units of photons per second per Angstrom per square centimeter. This is multiplied by the telescope effective area, the exposure time, and the pixel size in Angstroms to give the source photons per dispersion pixel per exposure. This is then multiplied by any of the following terms that apply to arrive at the number of source photons detected over all spatial pixels. The spatial integration is implicit in the aperture function. 

- the extinction using the specified airmass
- the telescope transmission
- the ADC transmission
- the aperture transmission based on the aperture size relative
  to the seeing
- the fiber transmission
- the filter transmission (one or two filters)
- the collimator transmission
- the disperser efficiency (one or two dispersers)
- the corrector transmission
- the camera transmission
- the detector DQE

Background Counts

The sky or atmospheric background spectrum, if one is given, defines a photon flux per square arc second. When it is given as a function of the moon phase it is interpolated to the specified moon phase. In addition if a thermal temperature and an emissivity are given then a thermal background is computed and added to the sky/atmospheric background.

The surface brightness of the background is multiplied by the area of the aperture occupied by the object (in arc seconds) and divided by the aperture transmission of the source. This is the quantity reported in the output for the sky photon flux. It is comparable to the source photon flux.

Next this flux is multiplied by the telescope effective area, the exposure time, and the pixel size in Angstroms. Finally it is multiplied by the same transmission terms as the object except for the extinction. Note that this removes the aperture transmission term included earlier giving the background photons as the number passing through the aperture per object profile. The final value is the number of background photons from the object. To get the background photons per spatial pixel the value is divided by the number of spatial pixels occupied by the source.

If no background subtraction is specified then the background counts are added to the source counts to define the final source counts and the background counts are set to zero.

Signal-to-Noise Ratio

The noise attributed to the source and background is based on Poisson statistics; namely the noise is the square root of the number of photons. The detector noise is given by a dark count component and a readout noise component. The noise from the dark counts is obtain by multiplying the dark count rate by the exposure time and the number of spatial pixels used in extracting the source and taking the square root. The readout noise is the detector readout noise parameter multiplied by the square root of the number of spatial source pixels.

If background subtraction is selected and the number of available background pixels is greater than zero then the uncertainty in the background estimation is computed. The uncertainty in a single pixel is the square root of the background photons per pixel, the dark counts per pixel, and the readout noise per pixel. This is divided by the square root of the number of background pixels to get the uncertainty in the background estimation for subtraction from the source.

The total noise is the combination of the source, background, dark count, and readout noise values and the background subtraction uncertainty added in quadrature.

The signal-to-noise ratio per pixel per exposure is the source counts divided by total noise. This value is multiplied by the square root of number of pixels per resolution element to get the S/N per resolution element. If multiple exposures are used to make up the total exposure time then the single exposure S/N is multiplied by the square root of the number of exposures.

Exposure Time From Signal-to-Noise Ratio

If no exposure time is specified, that is a value of INDEF, then the exposure time required to reach a desired signal-to-noise ratio per pixel is determined. The computation is done at the specified central wavelength. The task iterates, starting with the specified maximum time per exposure, by computing the S/N and adjusting the exposure time (possibly breaking the total exposure up into subexposures) until the computed S/N matches the desired S/N to 0.1%.

In addition to breaking the exposure time into individual exposure less than the maximum per exposure, the task will break single exposures that exceed the specified saturation and maximum data number values at the reference wavelength. If other wavelengths are then saturated or exceed the data maximum a warning is printed.