Spectroscopic Exposure Time Calculations

Draft

Contents

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, power law, or a user spectrum, a background "sky", 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 desired output. 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. It then computes signal-to-noise ratios from the detected photons of the source and background, and from 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 included in SPTIME (additional components may be added later) are:

Each of these components specify a transmission function as the fraction of incident light transmitted 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 a function of wavelength.

The spectrograph component can be used in place of some or all of the other components. However, if the other components can be described separately, the spectrograph transmission is used for "fudge" terms. As described later, it is also used to specify default components in order to simplify the parameter description in SPTIME.

To make SPTIME easily configurable by observatories and users, all the component transmission functions are given in text files (called tables since they often contain an interpolation table). The data files may include parameters and an interpolation table. The files are searched for in the users working directory and then using a list of 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. The role of other user interfaces is to map particular sets of data files for a spectrograph to parameters which users either do not see (when a component is always the same) or to a menu selection (such as for gratings).

Another simplifying feature is that many of the numerical parameters may be specified as INDEF to select reasonable defaults. For example if a central wavelength is not specified then the grating/grism blaze wavelength will be used. Other parameters, such as detector gain, will take default values defined in the calibration files.

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.

The following sections discuss the task parameters , the contents of the various calibration data tables , the calculations performed by the task, and guidelines for configuring SPTIME for particular spectrographs.

Parameters

The default parameters for SPTIME are shown below followed by a description of each parameter.
			   I R A F  
	    Image Reduction and Analysis Facility
    PACKAGE = spectime
       TASK = sptime
	
    (time   =    INDEF) Total exposure time (sec)
    (maxexp =    3600.) Maximum time per exposure (sec)
    (sn     =      25.) S/N per pixel if time is INDEF

			# Source and sky parameters
    (spectru=blackbody) Spectrum
    (sky    =         ) Sky spectrum
    (sensfun=         ) Sensitivity function
    (airmass=       1.) Airmass
    (seeing =       1.) Seeing (arcsec)
    (phase  =       0.) Moon phase (0-14)

			# Spectral distribution if no source spectrum
    (tempera=    6000.) Blackbody temperature (K)
    (index  =       0.) Power law index
    (refwave=    INDEF) Reference wavelength (Angstroms)
    (refflux=      10.) Source flux at reference wavelength
    (funits =       AB) Source flux units
    (abjohns=sptimelib$abjohnson) Magnitude conversion table

			# Setup parameters
    (wave   =    INDEF) Central wavelength (Angstroms)
    (order  =    INDEF) Order for grating
    (xorder =    INDEF) Order for cross disperser grating
    (width  =    INDEF) Slit width (-=pixels +=arcsec)
    (length =    INDEF) Slit length (-=pixels +=arcsec)
    (diamete=    INDEF) Circular aperture diameter (-=pixels +=arcsec)
    (inoutan=    INDEF) Incident to diffracted grating angle (deg)
    (xinouta=    INDEF) Incident to diffracted cross disperser grating a
    (xbin   =        1) CCD Binning (Spatial)
    (ybin   =        1) CCD Binning (Dispersion)

			# Spectrograph information
    (search =spectimedb$) List of directories to search
    (spectro=         ) Spectrograph table
    (filter =         ) Filter table
    (filter2=         ) Filter table
    (dispers=         ) Disperser table
    (xdisper=         ) Cross disperser table
    (fiber  =         ) Fiber table

    (telesco=         ) Telescope table
    (adc    =         ) Atmospheric dispersion compensator table
    (collima=         ) Collimator table
    (correct=         ) Corrector table
    (camera =         ) Camera table
    (detecto=         ) Detector table
    (apertur=         ) Aperture table
    (extinct=         ) Extinction table

			# Detector override parameters
    (gain   =    INDEF) Detector gain (e-/ADU)
    (rdnoise=    INDEF) Detector read noise (e-)
    (dark   =    INDEF) Detector dark count rate (e-/s)

			# Sky subtraction parameters
    (skysub = longslit) Type of sky subtaction
    (nskyaps=       10) Number of sky apertures

			# Output parameters
    (output =   object) List of output quantities
    (list   =         ) Output list file
    (graphic= stdgraph) Graphics device
    (interac=      yes) Interactive pause after graphs?
    (nw     =      101) Number of wavelength points
time = INDEF
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.
maxexp = 3600.
Maximum time in seconds per individual exposure. 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.
sn = 25.
Desired signal-to-noise per pixel at the central wavelength if the exposure time (time parameter) is not specified.

spectrum = "blackbody"
The source spectrum. This may be given as a table or with the special values

blackbody
Blackbody spectrum with temperature given by the \fItemperature\fR
parameter.
flambda_power
Power law in f(lambda) with index given by the \fIindex\fR parameter; f(lambda) proportional to lambda^(index).
fnu_power
Power law in f(nu) with index given by the \fIindex\fR parameter; f(nu) proportional to nu^(index).

The spectrum file is a two column text table of wavelength in Angstroms and flux in ergs/s/cm^2/A. See the spectrum section for more details.

sky = ""
Optional file containing the sky/background spectrum. The file is sought in the search path. If not specified, indicated by a null string, the parameter is sought in the spectrograph file. A value of "none" may be used to force no file even if a value is given in the spectrograph file. The sky file is a two column text table of wavelength in Angstroms and flux in ergs/s/cm^2/A/arcsec^2. See the sky spectrum section for more details.
sensfunc = ""
Optional file containing a sensitivity function. The file is sought in the search path. The sensitivity file is a two column text table of wavelength in Angstroms and 2.5*(log(countrate)-log(flambda)). This file is used for determining correction factors between the computed sensitivity function and one derived from observations.

airmass = 1.
The airmass of the observation. This is only used if an extinction table is specified.
seeing = 1.
The full width at half maximum (FWHM) of a point source in arc seconds.
phase = 0.
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.

temperature = 6000.
Blackbody temperature for a blackbody source spectrum in degrees Kelvin.
index = 0.
Power law index.
refwave = INDEF
Reference wavelength in Angstroms defining the flux of the source. A value of INDEF uses the observation central wavelength. For the broadband magnitudes this value is not used.
refflux = 10.
Reference source flux or magnitude at the reference wavelength. The units are specified by the funits parameter.
funits = "AB" (AB|F_lambda|F_nu|U|B|V|R|I)
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, and I. Note that the broadband magnitudes are color dependent.
abjohnson = "sptimelib$abjohnson"
File defining the broadband to AB magnitude correction.

wave = INDEF
Central wavelength of observation in Angstroms. If the value is INDEF it is determined from the blaze peak of the disperser.
order = INDEF
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
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
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. If the value is INDEF it is sought in the spectrograph or fiber data files.
length = INDEF
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. If the value is INDEF it is sought in the spectrograph or fiber data files.
diameter = INDEF
The aperture diameter for circular apertures such as fibers. Values may be positive to specify in arc seconds or negative to specify in projected pixels on the detector. If the value is INDEF it is sought in the spectrograph or fiber data files.
inoutangle = INDEF
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 it is determined from the spectrograph data file or a suitable value is derived from the grating parameters.
xinoutangle = INDEF
Incident to diffracted grating angle in degrees for grating cross dispersers. If the value is INDEF it is determined from the spectrograph data file or a suitable value is derived from the grating parameters.
xbin = 1
Detector binning along the dispersion direction.
ybin = 1
Detector binning along the spatial direction.

search = "spectimedb$"
List of directories to search for the various table files. The current direction is always searched first so it is not necessary to include that directory. The list may be a comma delimited list of directories, an @file, or a template.
spectrograph = ""
Required spectrograph table file.
filter = ""
Optional first filter table file. If not specified, indicated by a null string, the parameter is sought in the spectrograph file. A value of "none" may be used to force no file even if a value is given in the spectrograph file.
filter2 = ""
Optional second filter table file. If not specified, indicated by a null string, the parameter is sought in the spectrograph file. A value of "none" may be used to force no file even if a value is given in the spectrograph file.
disperser = ""
Required primary disperser table file. If not specified, indicated by a null string, the parameter is sought in the spectrograph file.
xdisperser = ""
Optional cross disperser table file. If not specified, indicated by a null string, the parameter is sought in the spectrograph file. A value of "none" may be used to force no file even if a value is given in the spectrograph file.
fiber = ""
Optional fiber table file. If not specified, indicated by a null string, the parameter is sought in the spectrograph file. A value of "none" may be used to force no file even if a value is given in the spectrograph file.
telescope = ""
Required telescope table file. If not specified, indicated by a null string, the parameter is sought in the spectrograph file.
adc = ""
Optional atmospheric dispersion compensator table file. If not specified, indicated by a null string, the parameter is sought in the spectrograph file. A value of "none" may be used to force no file even if a value is given in the spectrograph file.
collimator = ""
Required collimator table file. If not specified, indicated by a null string, the parameter is sought in the spectrograph file.
corrector = ""
Optional corrector table file. If not specified, indicated by a null string, the parameter is sought in the spectrograph file. A value of "none" may be used to force no file even if a value is given in the spectrograph file.
camera = ""
Required corrector table file. If not specified, indicated by a null string, the parameter is sought in the spectrograph file.
detector = ""
Required detector table file. If not specified, indicated by a null string, the parameter is sought in the spectrograph file.
aperture = ""
Required aperture table file. If not specified, indicated by a null string, the parameter is sought in the spectrograph file. If not found in the spectrograph file it is sought in the fiber file (if one is specified).
extinction = ""
Optional extinction table file. If not specified, indicated by a null string, the parameter is sought in the spectrograph file. A value of "none" may be used to force no file even if a value is given in the spectrograph file.

gain = INDEF
Detector gain in photons/electrons per data number. If the value is INDEF it is determined from the detector file.
rdnoise = INDEF
Detector readout noise in photons/electrons. If the value is INDEF it is determined from the detector file.
dark = INDEF
Detector dark count rate in photons/electrons per second. If the value is INDEF it is determined from the detector file.

skysub = "longslit" (none|longslit|multiap)
Type of sky subtraction. The values are "none" for no sky subtraction, "longslit" for sky subtraction using pixels in the aperture, and "multiap" for sky determined from a number of other sky apertures. The last case is typical for fiber spectrographs.
nskyaps = 10
Number of sky apertures when using "multiap" sky subtraction.

output = "object"
List of quantities to output as graphs and/or in a text file. These are given as a function of wavelength sampled across the wavelength coverage of the observation. The choices are:

counts
Object and sky data counts per individual exposure.
snr
Signal to noise ratio per pixel per individual exposure.
object
Object data 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 per second per Angstrom per individual exposure for the object and sky.
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.
thruput
Percent system thruput from telescope to detected photons.
sensfunc
Sensitivity function 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.
correction
Multiplicative correction factor needed to convert the computed count rate to that given by an input sensitivity function.
ALL
All of the above.

list = ""
Filename for list output of the above output selections. The output will be appended if the file already exists.
graphics = "stdgraph"
Graphics output device.
interactive = yes
Interactive pause after each graph? If yes then cursor input is enabled after each graph otherwise all the graphs will be drawn without pause and so only the last graph will be seen.
nw = 101
Number of wavelength points to used in the output graphs and lists.

Calibration Tables

SPTIME uses text files to provide parameters and interpolation tables. These the source and sky/background input spectra are also given by 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.

Some parameters are common to all tables and others are specific to a particular type of file. The common parameters are

	  title - Title for the file used in documentation and labels.
    description - Descriptive information that may be included in
		  documentation.  There may be multiple parameters of
		  this type.
     tablescale - Multiplicative factor to be applied to the table
		  values.
    

The optional table 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). If a "tablescale" parameter is specified then the table values in the last column are multiplied by this value before use by the program.

The types of tables used in SPTIME are listed below and described in the following subsections.

Spectrum

Parameters

There are no special spectrum file parameters.

Table

A spectrum table has two columns, the wavelength in Angstroms and the flux in ergs/s/cm^2/A.

Example

    # title = "My spectrum"

    3200.0   1.4072E-12
    3250.0   1.3769E-12
    3300.0   1.3111E-12
    3350.0   1.2723E-12
    3400.0   1.2015E-12
    3450.0   1.1351E-12
    3500.0   1.0928E-12
    3571.0   1.0306E-12
    3636.0   9.5812E-13
    3704.0   8.9810E-13
    3862.0   7.8894E-13
    4036.0   7.4949E-13
    4167.0   6.7146E-13
    4255.0   6.2068E-13
    4464.0   5.0959E-13
    4566.0   4.7819E-13
    4785.0   3.9346E-13
    5000.0   3.2865E-13
    5263.0   2.6804E-13
    5556.0   2.1935E-13
    5840.0   1.7776E-13
    6056.0   1.5076E-13
    6436.0   1.1520E-13
    6790.0   9.7933E-14
    7100.0   8.4752E-14
    7550.0   6.5279E-14
    7780.0   5.8710E-14
    8090.0   4.9977E-14

Sky

Parameters

      units - Units of sky brightness (currently not used).

Table

The sky brightness table has two or three columns. The first column is wavelength in Angstroms. The last column is the sky brightness in flux units of ergs/s/cm^s/A/arcsec^2 (currently this is the only units allowed but in future other units will be added). If there are only two columns then the sky brightness "spectrum" is used for all moon phases. If there are three columns then the second column is the moon phase given between new moon (phase of 0) and full moon (phase of 14). If no table is given then a sky brightness of 0 is assumed.

Examples

    # title = "CTIO sky brightness as a function of moon phase"
    # units = ergs/s/cm^2/A/arcsec^2

      3600  0 6.63797E-18
      4400  0 5.48524E-18
      5500  0 6.87303E-18
      6400  0 9.83901E-18
      7900  0 1.34297E-17
     24000  0 5.57523E-16
      3600  3 1.05170E-17
      4400  3 7.23239E-18
      5500  3 7.53758E-18
      6400  3 1.07888E-17
      7900  3 1.34297E-17
     24000  3 5.57523E-16
      3600  7 4.59085E-17
      4400  7 1.51104E-17
      5500  7 9.93574E-18
      6400  7 1.29707E-17
      7900  7 1.61454E-17
     24000  7 5.57523E-16
      3600 10 1.66694E-16
      4400 10 3.46180E-17
      5500 10 1.89324E-17
      6400 10 1.71019E-17
      7900 10 1.94116E-17
     24000 10 5.57523E-16
      3600 14 6.63797E-16
      4400 14 1.04558E-16
      5500 14 3.60735E-17
      6400 14 2.47186E-17
      7900 14 2.55972E-17
     24000 14 5.57523E-16

Sensitivity Function

Parameters

There are no special file parameters.

Table

A sensitivity function table has two columns, the wavelength in Angstroms and the sensitivity function magnitude defined as
    2.5 * (log (countrate) - log (f_lambda))
where countrate is the measured count rate corrected to remove extinction in counts/s/A and f_lambda is the source flux in units of ergs/s/cm^2/A.

Example

   ...
   4672.9375     37.940693
   4729.4702     38.038231
   4786.0029     38.129082
   4842.5356     38.212406
   ...

Spectrographs

Parameters

The spectrograph file provides default values for all the SPTIME table parameters. This allows a convenient way to fix components that do not vary for a particular spectroscopic system and set defaults so that in SPTIME only the spectrograph file needs to be specified. The default parameters are optional and any value given directly as a task parameter overrides the value in the spectrograph file. The task parameters that can be specified in this file, where the table parameter name is the same as the task parameter name, are

	sky - Sky brightness table/spectrum.
 extinction - Extinction table.
  telescope - Telescope table.
	adc - ADC table.
   aperture - Aperture table.
      fiber - Fiber table.
 collimator - Collimator table.
     filter - Primary filter table.
    filter2 - Secondary filter table.
  disperser - Disperser table.
 xdisperser - Cross-disperser table.
  corrector - Corrector table.
     camera - Camera table.
   detector - Detector table.
Default values for the incident to diffraction angles may also be defined in the spectrograph file with the parameters
     inoutangle - Incident to diffraction angle for
		  primary grating.
    xinoutangle - Incident to diffraction angle for
		  cross disperser grating.

The two common magnification terms in a spectrograph are from the camera and from the grating. The former is determined from focal length parameters in the collimator and camera descriptions and the later is determined from the grating description. In some cases there may be other sources of magnification. The following parameters provide for such magnification (remember do not include camera and grating magnification)

  apmagdisp - Aperture magnification in dispersion direction.
 apmagxdisp - Aperture magnification in cross dispersion direction.

One source of magnification is when the aperture mechanism (such as the slit plate) is tilted for viewing and the user input for the aperture size is the unprojected slit size. For instance if the slit is tilted about the long axis the "apmagdisp" would be the cosine of the tilt to convert input slit widths to projected slit widths.

Table

The spectrograph table has two columns, the wavelength in Angstroms and the fractional transmission at that wavelength. For values in percent use a "tablescale" parameter of 0.01. If no table is given then 100% transmission at all wavelengths is assumed.

In most cases all the transmission components are given in other tables; telescope, collimator, camera, detector, etc. The table in the spectrograph file provides a place for 1) any components not taken into account in the other tables, 2) a place to put final fudge corrections, and 3) if desired this could be the only table used apart from the filter, disperser, and detector tables.

Examples

    # title = "4-m R-C Spectrograph"
    # telescope = KPNO/Telescopes/mayall4m
    # collimator = KPNO/Collimators/rcspec
    # camera = KPNO/Cameras/uvfast
    # detector = KPNO/Detectors/t2kb
    # extinction = KPNO/kpextinct
    # sky = KPNO/kpsky
    # aperture = slit
    # inoutangle = 46 deg

Extinction

Parameters

There are no special extinction file parameters.

Table

The extinction table has two columns, the wavelength in Angstroms and the extinction in magnitudes per airmass. If no table is defined then no extinction is assumed. However, in that case all that would be needed is to not specify an extinction table to the task.

Examples

    # title = " KPNO Standard Extinction"

    3200. 1.017
    3250. 0.881
    3300. 0.787
       ...
    9832. 0.053
    10256. 0.023
    10400. 0.024

    # Last four extinction coefficients from CTIO list - no data available
    # for KPNO.

Telescopes

Parameters

       area - Effective collecting area in m^2 delivered to the instrument.
      scale - Scale in arcsec/mm delivered to the instrument.
The area needs to take into account any obscurations. If the telescope has different instrument focii and configurations then different telescope tables would be used.

Table

The telescope table has two columns, the wavelength in Angstroms and the fractional transmission at that wavelength. For values in percent use a "tablescale" parameter of 0.01. If no table is given then 100% transmission at all wavelengths is assumed.

Examples

    # title = "KPNO Mayall 4-m Telescope"
    # area = 9.186 m^2
    # scale = 6.624 arcsec/mm (at R-C)

    5000. 0.65

ADC

Parameters

There are no special ADC file parameters.

Table

The ADC table has two columns, the wavelength in Angstroms and the fractional transmission at that wavelength. For values in percent use a "tablescale" parameter of 0.01. If no table is given then 100% transmission at all wavelengths is assumed.

Example

    # title = "4m ADC"

    5000 0.95

Apertures

Parameters

       type - Aperture type (circular or rectangular).
   diameter - Circular aperture diameter in mm or pixels.
      width - Rectangular width (dispersion direction) in mm or pixels.
     length - Rectangular length (spatial direction) in mm or pixels.

The aperture dimensions are optional and provide defaults if not given as program parameters. The dimensions are in mm if the values are positive and in projected pixels if negative. For fibers the diameter is normally given in mm and for slits a default of some number of pixels is defined.

Table

The aperture table has two columns for circular apertures and three columns for rectangular apertures. The last column is the fraction of light transmitted though percentages may be given if the "tablescale" parameter is given as 0.01. The independent columns are the ratio of the aperture size divided by the seeing FWHM, that is, the aperture size in units of seeing FWHM. For rectangular apertures the first column is for the width (dispersion direction) and the second is the length (spatial direction). If no table is given then 100% transmission at all aperture sizes is assumed.

Aperture transmission tables can be made for various types of profiles. However, the most common one would be for Gaussian seeing profiles. The transmission values are then the fraction of the Gaussian profile passing through the aperture as a function of aperture size in units of profile FWHM.

Examples

1. Aperture description for a slit spectrograph.

    # title = "Slit with Gaussian profile"
    # width = -2 (-=pixels +=mm)
    # length = -20 (-=pixels +=mm)

    0.00 0.00 0.000
	...
    0.00 0.63 0.000
    0.10 0.63 0.051
	....
    2.51 0.63 0.541
    3.98 0.63 0.542
    0.00 1.00 0.000
    0.10 1.00 0.071
	....
    2.51 3.98 0.997
    3.98 3.98 1.000

2. Aperture description for a fiber spectrograph. # title = "Hydra red fiber aperture with Gaussian profile" # diameter = 0.31 mm 0.00 0.000 0.10 0.007 0.13 0.011 0.16 0.017 0.20 0.027 0.25 0.043 0.32 0.067 0.40 0.104 0.50 0.160 0.63 0.241 0.79 0.354 1.00 0.500 1.26 0.667 1.58 0.825 2.00 0.937 2.51 0.987 3.16 0.999 3.98 1.000

Fibers

Parameters

   aperture - Default aperture table.
The default aperture table overrides the default value in the spectrograph file. The program aperture parameter overrides any value specified in this file.

Table

The fiber table has two columns, the wavelength in Angstroms and the fractional transmission at that wavelength. For values in percent use a "tablescale" parameter of 0.01. If no table is given then 100% transmission at all wavelengths is assumed.

Examples

    # title = "Hydra red fibers"
    # aperture = "KPNO/Fibers/redfibap"

    3400 0.0
    4000 0.6
    5000 0.81
    6000 0.86
    7000 0.88
    8000 0.90
    9000 0.92
    10000 0.93

Collimators

Parameters

	 fl - Focal length in m.

Table

The collimator table has two columns, the wavelength in Angstroms and the fractional transmission at that wavelength. For values in percent use a "tablescale" parameter of 0.01. If no table is given then 100% transmission at all wavelengths is assumed.

Examples

    # title = "R-C Spectrograph Collimator"
    # fl = 1.161 m

    5000 0.85

Filters

Parameters

There are no special filter file parameters.

Table

The filter table has two columns, the wavelength in Angstroms and the fractional transmission at that wavelength. For values in percent use a "tablescale" parameter of 0.01. If no table is given then 100% transmission at all wavelengths is assumed.

Examples

    # title = "RC Spectrograph GG455 Filter"

       4370.00    0.000
       4400.00    0.085
       4450.00    0.032
       4500.00    0.189
	 ...
      11800.00    0.963
      12000.00    0.961

Dispersers: Gratings

Parameters

	   type - Type of disperser with a value of "grating".
	    gmm - Grooves per mm.
	  blaze - Blaze angle in degrees.
    reflectance - Fractional reflectance of grating.

Table

The grating table has three columns, the first order wavelength in Angstroms, the order, and the fractional efficiency at that wavelength. For values in percent use a "tablescale" parameter of 0.01. If no table is given the efficiency (blaze function) is calculated. Normally the calculated function is used since the grating may be used in a wide range of configurations. However if the grating is used in a limited set of configurations (same spectrograph and a few orders) a table may be appropriate.

Note that the wavelengths are always at first order so that the table may be given in the required regular form. So for multiple orders the sample points are at the same first order values (wavelength * order) though the efficiency values will be for the particular order.

Examples

    # title = "BL 181: 316 l/mm
    # type = grating
    # gmm = 316 groves/mm
    # blaze = 7.396 deg
    # reflectance = 0.78

Dispersers: Grisms

Parameters

The following grism parameters are used.

	    type - Type of disperser with a value of "grism".
	     gmm - Grooves per mm.
	   prism - Prism angle (= blaze angle) in degrees.
	  index1 - Index of refraction of grism in first order
		   (also default).
	  indexN - Index of refraction of grism in Nth order;
		   index2, etc.
    transmission - Fractional transmission of grism.

Table

The grism table has three columns, the first order wavelength in Angstroms, the order, and the fractional transmission at that wavelength. For values in percent use a "tablescale" parameter of 0.01. If no table is given the transmission and blaze function is calculated. Normally the calculated function is used.

Note that the wavelengths are always at first order so that the table may be given in the required regular form. So for multiple orders the sample points are at the same first order values (wavelength * order) though the transmission values will be for the particular order.

Examples

    # title = "Grism 810: 150 l/mm
    # type = grism
    # gmm = 150 groves/mm
    # prism = 10.6 deg
    # index = 1.52
    # transmission = 1.

Correctors

Parameters

There are no special corrector file parameters.

Table

The corrector table has two columns, the wavelength in Angstroms and the fractional transmission at that wavelength. For values in percent use a "tablescale" parameter of 0.01. If no table is given then 100% transmission at all wavelengths is assumed.

Examples

    # title = "Coude Spectrograph Blue Corrector"

    5000 0.8

Cameras

Parameters

 	  fl - Focal length in m.
  resolution - Resolution at detector in mm.
 unvignetted - Unvignetted dispersion region in mm at the detector.

The detector specifies the number of pixels along the dispersion. If the full detector is vignetted the unvignetted parameter is used.

Table

The camera table has two columns, the wavelength in Angstroms and the fractional transmission at that wavelength. For values in percent use a "tablescale" parameter of 0.01. If no table is given then 100% transmission at all wavelengths is assumed.

Examples

    # title = "UV Fast Camera"
    # fl = 0.265 m
    # resolution = 0.06 mm

    5000 0.85

Detectors

Parameters

       type - Type of detector.  Currently only "ccd".
      ndisp - Number of pixels along the dispersion.
    pixsize - Pixel size in mm.
       gain - Detector gain in electrons/ADU.
    rdnoise - Detector readout noise in electrons RMS.
       dark - Detector dark count rate in electrons/s/pixel.
 saturation - Saturation in electrons.
      dnmax - Data number maximum.

The gain, readout noise, and dark current are task parameters that can be used to override the default values in the detector file. The saturation and data number maximum values are for an extracted object and so is profile dependent. It is intended to provide a warning of possible error to users.

Table

The detector table has two columns, the wavelength in Angstroms and the fractional detected quantum efficiency (DQE) at that wavelength. For values in percent use a "tablescale" parameter of 0.01. If no table is given then 100% DQE at all wavelengths is assumed.

Examples

    # title = "T2KB - SITe 2048x2048 CCD"
    # type = ccd
    # ndisp = 2048
    # pixsize = 0.024 mm
    # gain = 2.0 e-/ADU
    # rdnoise = 4.0 e-
    # dark = 0 e-/s
    # saturation = 70000 e-
    # dnmax = 65535 counts

     2500 0.00
     3200 0.160
     3650 0.498
     4050 0.649
     5000 0.765
     6000 0.818
     7000 0.799
     8000 0.603
     9000 0.331
    10000 0.10
    10700 0.00

Johnson Magnitude Conversion

Parameters

There are no special parameters.

Table

The table has two columns, the wavelength in Angstroms and the AB magnitude zero point. The relation is

    AB = mag + abzero (lambda)
where "AB" is the AB magnitude corresponding to the broadband magnitude "mag" at wavelength "lambda" and "abzero" is the interpolated table value.

Examples

    # AB zeropoints.
    # Values are from Astrophysical Quantities converted from
    # log f (in W/cm^2/micron) to AB = -2.5 * log (F_lambda) - 5 log (lambda) - 2.4
    # where lambda is in Angstroms and F_lambda is in ergs/s/cm^2/A.  The
    # values are for U, B, V, R, I, J.

     3650  0.714
     4400 -0.167
     5500 -0.052
     7000  0.275
     9000  0.529
    12500  0.815

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 a parameter of the telescope data file. 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. These are parameters of the collimator and camera descriptions. This magnification applies both along and across the dispersion.

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 as given in the detector description. 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 is converted to 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.

Sky Counts

The sky 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. The sky brightness 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 sky photons as the number passing through the aperture per object profile. The final value is the number of sky photons from the object. To get the sky photons per spatial pixel the value is divided by the number of spatial pixels occupied by the source.

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

Signal-to-Noise Ratio

The noise attributed to the source and sky 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 sky subtraction is selected and the number of available sky pixels is greater than zero then the uncertainty in the sky estimation is computed. The uncertainty in a single pixel is the square root of the sky 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 sky pixels to get the uncertainty in the sky estimation for subtraction from the source.

The total noise is the combination of the source, sky, dark count, and readout noise values and the sky 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, 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%.

Hints for Setting Up a Spectrograph

This section gives suggestions for how to set up the calibration files for a spectrograph. There are many other different ways to do this.

Calibration files are specified by filenames. They are first sought in the current directory and then in a list of directories given by the search parameter. For developing the calibration files create the files in your working directory. As a starting point copy files from the demonstration directories under spectimedb$KPNO. Rather than copying some files they can be specified in SPTIME by setting the search parameter to spectimedb$KPNO and then specifying the files as [directory]/[filename]. The calibration files in the demonstration directory should be checked. Many were created with ad hoc values or by rough measurement from graphs for the purpose of testing.

Begin by setting up the files with measured or known transmission curves such as as CCD DQE and filter curves. The calibration files are defined so that it is possible to import digital filter curves with minimal editing. The editing is to remove or comment most of the header data, add a title parameter, and add a tablescale parameter with value of 0.01 to scale from percent to the fractional values expected by SPTIME. See the example in the Filters section.

Next calibrate the telescope transmission if not known. This might be done with direct imaging of standard stars using a CCD with known DQE and filters with measured transmission curves. This is discussed further in the following sections. If it is not possible to measure the telescope transmission then use the number of mirrors and reflectance values (as a function of wavelength if possible) for the coatings to estimate the transmission. The same applies for any lenses using transmission values for the materials.

Try and measure or estimate the transmission of the ADC, collimator, corrector, and camera. Again this might be done using physical values for reflectance or transmission based on the composition of the elements.

Next setup up grating/grism files. As discussed elsewhere, it is best to calculate the efficiencies from the grating parameters than to use an efficiency table because the gratings can be used in different configurations. However, if a grating is always used in one spectrograph with fixed camera-collimator angle then it may be better to use a laboratory measured efficiency. Note that one can use SPTIME to look at the calculated efficiency curves by setting the output parameter to "disperser" and run SPTIME with appropriate calibration files.

The calculated efficiencies use the physical blaze angle rather than a configuration dependent blaze wavelength as is often tabulated in the documentation. One can compute the blaze angle from the wavelength and the camera-collimator angle using the equation

    blaze angle = arcsin (1e-7*(g*w*m)/(2*cos(phi/2)) 
where g is the groves/mm, w is the blaze wavelength in Angstroms, m is the order, and phi is the camera-collimator angle.

For the grisms, the prism angle (which is the same as the blaze angle) and the index of refraction can be computed from the blaze wavelength and dispersion using the equations

    prism angle = arccos (1e-7 * (g*d*m) / f)
    index of refraction = 1e-7 * (g*w*m) / sin(prism angle) + 1
where d is the dispersion in Angstroms per mm and f is the focal length of the camera. It is best to use known values rather than those computed from the blaze wavelength and dispersion if available. The grism files in the demonstration directory had known prism angles and the index of refraction was computed as above.

Finally standard star observations, as described below, are used to get the calibration files for one last element or as a fudge term in the spectrograph calibration file.

Calibration Observations

It is desirable to determine the telescope transmission independently of the spectrograph if it is not already known. This could be done with direct standard star photometry using filters and detectors with measured transmission and DQE. If it is possible to do photometry with the same ADC that is used with the spectrograph then the observations would be done with and without the ADC to separate the ADC transmission function.

Obtain standard star observations in photometric conditions. For slit spectrographs use a wide slit and, if possible, use an ADC or align the slit to avoid atmospheric dispersion effects. Assuming the disperser efficiency can be modeled or determined separately so that the calibration is for the rest of the spectrograph components, the observations need only be done with the lowest dispersion. As many setups as necessary to cover the operating range of the spectrograph need to be obtained.

Reductions

The telescope and ADC transmission functions are determined first. Create the ADC data files. For development you probably would put it in your working directory and set filenames in SPTIME.

Reduce the spectroscopic standard star data for each spectrograph configuration using the standard IRAF reduction path. Use Angstroms for the wavelength calibration and flux units of ergs/s/cm^2/A for the flux calibrations (these are the defaults). The goal is to produce sensitivity function spectra. Convert the sensitivity function image files produced to sensitivity function tables with the command

    cl> listpix [sens] wcs=world > sensfunc.dat
where [sens] is the sensitivity function spectrum produced by SENSFUNC.

Set all the SPTIME parameters to match the observations. The input spectrum used does not matter though you might want to use a final flux calibrated spectrum. Set the output parameter to "correction".

The correction values produced by SPTIME can now be used to fix up any of the calibration tables. The easiest way to apply the correction is to assign the correction to one component (the spectrograph can be used as a fudge term on top of the other components or it could be attributed to the camera). For the target component create the file with no table so that it will use a transmission of 100%. The output correction values would then be those needed in that component to produce the observed count rates. Note that by setting the list parameter to a file name you can get the numbers in the plot as a text file suitable to used in the calibration file.

If several spectrograph settings are required to cover the spectral range of the spectrograph then there will have to be some intelligent merging of the corrections.