path: root/noao/obsutil/src/doc/sptime.hlp

.help sptime Nov01 noao.obsutil
.ih
NAME
sptime -- spectroscopic exposure time calculator
.ih
USAGE
sptime
.ih
PARAMETERS
The parameters in this task have certain common features.
.ls (1)
All parameters, except \fIspectrograph\fR and \fIsearch\fR, 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.
.le
.ls (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).
.le
.ls (3)
Tables which are specified as filenames are sought first in the current
working directory, then in one of the directories given by the
\fIsearch\fR parameter, and finally in the package library directory
sptimelib$.
.le


.ls time = INDEF (INDEF) [spectrograph]
Total exposure time in seconds.  This time may be divided into shorter
individual exposure times as defined by the \fImaxexp\fR parameter.  If
the value is INDEF then the exposure time needed to achieve the
signal-to-noise per pixel specified by the \fIsn\fR parameter is computed.
.le
.ls sn = 25. (25.) [spectrograph]
Desired signal-to-noise per pixel at the central wavelength if the
exposure \fItime\fR parameter is not specified.
.le


The following parameters define the source and sky/atmosphere background
spectra.
.ls spectrum = "blackbody"
Source spectrum.  This may be a table or one of the following  special words:
.ls blackbody
Blackbody spectrum with temperature given by the \fItemperature\fR
parameter.
.le
.ls flambda_power
Power law in f(lambda) with index given by the \fIindex\fR parameter;
f(lambda) proportional to lambda^(index).
.le
.ls fnu_power
Power law in f(nu) with index given by the \fIindex\fR parameter;
f(nu) proportional to nu^(index).
.le

The table is a two column text file of wavelength in Angstroms and flux in
ergs/s/cm^2/A.
.le
.ls spectitle = "" [spectrum|spectrograph]
Spectrum title.
.le
.ls 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.
.le
.ls 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, \fBApJ 345:245\fR, 1989.  The default
R(V) is typical of the interstellar medium.
.le
.ls 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.
.le
.ls skytitle = "" [sky|spectrograph]
Sky title.
.le
.ls extinction = "" ("none") [spectrograph]
Extinction table.  The table is a two column text file consisting of
wavelength in Angstroms and extinction in magnitudes per airmass.
.le
.ls exttitle = "" [spectrograph]
Extinction title.
.le


The following parameters are used with the source spectrum is specified
by the special functions.
.ls refwave = INDEF (INDEF) [spectrum|spectrograph]
Reference wavelength, in units given by the \fIunits\fR 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.
.le
.ls 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.
.le
.ls 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.
.le
.ls temperature = 6000. (6000.) [spectrograph]
Blackbody temperature for a blackbody source spectrum in degrees Kelvin.
.le
.ls index = 0. (0.) [spectrograph]
Power law index for the power law source spectrum.
.le


The following parameters are observational parameters describing either
the observing conditions or spectrograph setup.
.ls seeing = 1. (1.) [spectrograph]
The full width at half maximum (FWHM) of a point source in arc seconds.
.le
.ls airmass = 1. (1.) [spectrograph]
The airmass of the observation.  This is only used if an extinction table
is specified.
.le
.ls 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.
.le
.ls 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 \fIemissivity\fR table.
.le
.ls wave = INDEF (INDEF) [spectrograph]
Central wavelength of observation in units given by the \fIunits\fR
parameter.  If the value is INDEF it is determined from the efficiency peak
of the disperser.
.le
.ls 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.
.le
.ls 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.
.le
.ls 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.
.le
.ls 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.
.le
.ls 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.
.le
.ls xbin = 1 (1) [detector|spectrograph]
Detector binning along the dispersion direction.
.le
.ls ybin = 1 (1) [detector|spectrograph]
Detector binning along the spatial direction.
.le


The following parameters a miscellaneous parameters for the task.
.ls search = "spectimedb$"
List of directories to search for the various table files.  The current
direction is always searched first and the directory sptimelib$ is searched
last so it is not necessary to include these directories.  The list may be
a comma delimited list of directories, an @file, or a template.
.le
.ls minexp = 0.01 (0.01) [spectrograph]
Minimumm time in seconds per individual exposure time.  This only applies
when \fItime\fR is INDEF.  Adjustment of the exposure time for saturation
will not allow the exposure time to fall below this value.
.le
.ls 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.
.le
.ls 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.
.le
.ls 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".
.le
.ls nskyaps = 10  (10) [spectrograph]
Number of sky apertures when using "multiap" sky subtraction.
.le
.ls 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.
.le
.ls 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.
.le


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.
.ls 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:
.ls counts
Object and background counts per individual exposure.
.le
.ls snr
Signal-to-noise ratio per pixel per individual exposure.
.le
.ls 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.
.le
.ls rate
Photons/second/A per individual exposure for the object and background.
.le
.ls atmosphere
Percent transmission of the atmosphere.
.le
.ls telescope
Percent transmission of the telescope.
.le
.ls adc
Percent transmission of the ADC if one is used.
.le
.ls aperture
Percent transmission of the aperture.
.le
.ls fiber
Percent transmission of the fiber if one is used.
.le
.ls filter
Percent transmission of the first filter if one is used.
.le
.ls filter2
Percent transmission of the second filter if one is used.
.le
.ls collimator
Percent transmission of the collimator.
.le
.ls disperser
Percent efficiency of the disperser.
.le
.ls xdisperser
Percent efficiency of the cross disperser if one is used.
.le
.ls corrector
Percent transmission of the corrector if one is used.
.le
.ls camera
Percent transmission of the camera.
.le
.ls detector
Percent DQE of the detector.
.le
.ls spectrograph
Percent transmission of the spectrograph if a transmission
function is defined.
.le
.ls emissivity
Emissivity of the telescope/spectrograph if an emissivity function
is defined.
.le
.ls thruput
Percent system thruput from telescope to detected photons.
.le
.ls 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.
.le
.ls correction
Multiplicative correction factor needed to convert the computed
count rate to that given by an input sensitivity function.
.le
.ls ALL  
All of the above.
.le
.le
.ls 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.
.le
.ls list = "" [spectrograph]
Filename for list output of the selected quantities.  The output
will be appended if the file already exists.
.le
.ls graphics = "stdgraph" ("stdgraph") [spectrograph]
Graphics output device for graphs of the output quantities.
.le
.ls 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.
.le

The last parameter is a "parameter set" ("pset") containing all the
spectrograph parameters.
.ls specpars = ""
Spectrograph parameter set.  If "" then the default pset \fBspecpars\fR
is used otherwise the named pset is used.
.le



SPECPARS PARAMETERS
.ls 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.
.le
.ls title = "" [spectrograph]
Title for the spectrograph.
.le
.ls 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).
.le
.ls 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.
.le
.ls 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.
.le


.ls telescope = "" [spectrograph]
Telescope efficiency table as a function of wavelength.  
.le
.ls teltitle = "" [telescope|spectrograph]
Telescope title.
.le
.ls 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.
.le
.ls scale = INDEF (10.) [telescope|spectrograph]
Telescope plate scale, in arcsec/mm, at the entrance aperture of the
spectrograph.
.le
.ls emissivity = "" [telescope|spectrograph]
Emissivity table.  The emissivity is for all elements in the telescope
and spectrograph.  If an emissivity is specified and an the \fIthermal\fR
temperature parameter is greater than zero then a thermal background
is added to the calculation.
.le
.ls emistitle = "" [emissivity|spectrograph]
Title for the emissivity table used.
.le


.ls corrector = "" [spectrograph]
Efficiency table for one or more correctors.
.le
.ls cortitle = "" [corrector|spectrograph]
Title for corrector table used.
.le
.ls adc = "" [spectrograph]
Efficiency table for atmospheric dispersion compensator.
.le
.ls adctitle = "" [adc|spectrograph]
Title for ADC table used.
.le


.ls 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.
.le
.ls disptitle = "" [disperser|spectrograph]
Title for disperser.
.le
.ls 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.
.le
.ls 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.
.le
.ls 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.
.le
.ls oref = INDEF (1) [disperser|spectrograph]
When a central (blaze) wavelength is specified this parameter indicates
which order it is for.
.le
.ls 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.
.le
.ls 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.
.le
.ls 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.
.le
.ls 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.
.le


.ls 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.
.le
.ls xdisptitle = "" [xdisperser|spectrograph]
Title for crossdisperser.
.le
.ls 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.
.le
.ls gmm = INDEF (INDEF) [xdisperser|spectrograph]
Ruling in lines per mm.  If not specified it will be derived from the
other crossdisperser parameters.
.le
.ls 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.
.le
.ls xoref = INDEF (1) [xdisperser|spectrograph]
When a central (blaze) wavelength is specified this parameter indicates
which order it is for.
.le
.ls 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.
.le
.ls 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.
.le
.ls 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.
.le
.ls 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.
.le


.ls 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.
.le
.ls aptitle = "" [aperture|spectrograph]
Title for aperture used.
.le
.ls 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".
.le


.ls 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.
.le
.ls fibtitle = "" [fiber|spectrograph]
Title for fiber transmission used.
.le


.ls 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.
.le
.ls ftitle = "" [filter|spectrograph]
Title for filter transmission used.
.le
.ls 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.
.le
.ls f2title = "" [filter|spectrograph]
Title for filter transmission used.
.le
.ls block = "" ("no") [filter|spectrograph]
If "yes" then no check will be made for other orders.
.le


.ls 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.
.le
.ls coltitle = "" [collimator|spectrograph]
Title for collimator.
.le
.ls 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.
.le

.ls 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.
.le
.ls camtitle = "" [camera|spectrograph]
Title for camera.
.le
.ls 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.
.le
.ls resolution = "" (2 pixels) [camera|spectrograph]
Camera resolution on the detector in mm.
.le
.ls 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.
.le


.ls detector = "" (1.) [spectrograph]
Detector DQE table.  The DQE is a function of wavelength in Angstroms.
.le
.ls dettitle = "" [detector|spectrograph]
Title for detector.
.le
.ls ndisp = INDEF (2048) [detector|spectrograph]
Number of pixels along the dispersion.
.le
.ls pixsize = INDEF (0.02) [detector|spectrograph]
Pixel size (assumed square) in mm.
.le
.ls 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.
.le
.ls rdnoise = INDEF (0.) [detector|spectrograph]
Readout noise in photons.
.le
.ls dark = INDEF (0.) [detector|spectrograph]
Dark count rate in photons/s.
.le
.ls 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.
.le
.ls 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.
.le
.ls xbin = 1 (1) [detector|spectrograph]
Detector binning along the dispersion direction.
.le
.ls ybin = 1 (1) [detector|spectrograph]
Detector binning along the spatial direction.
.le
.ih
DISCUSSION


OVERVIEW

The spectroscopic exposure time package, \fBSPECTIME\fR, consists of a
general calculation engine, \fBSPTIME\fR, and a collection of user or
database defined IRAF scripts.  The scripts are one type of user interface
for \fBSPTIME\fR.  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,
\fBSPTIME\fR is a standard IRAF task that can be executed directly.

\fBSPTIME\fR 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.

\fBSPTIME\fR 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 \fBSPTIME\fR are:

.nf
    - 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
.fi

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 \fIspecpars\fR parameter is a "parameter set" or "pset".
The default value of "" corresponds to the pset task \fBspecpars\fR.
However, using \fBeparam\fR 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 \fBeparam\fR and specified in the
\fIspecpars\fR 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 \fBSPTIME\fR 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

\fBSPTIME\fR 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

.nf
    # [parameter] = [value]
.fi

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.

.nf
        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
.fi

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 \fIunits\fR parameter.  In addition the \fIwave\fR
and \fIrefwave\fR 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.

.nf
	   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)
.fi

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:

.nf
	km/s 1 micron
.fi


CALCULATIONS

This section describes the calculations, and assumptions behind the
calculations, performed by \fBSPTIME\fR.  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

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

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

.nf
    magnification = cos(tilt-phi/2) / cos(tilt+phi/2)
.fi

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,

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

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.

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

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 \fIscale\fR 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 \fBSPTIME\fR 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

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

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

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

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

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

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.

.nf
    - 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
.fi


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.
.endhelp