diff options
Diffstat (limited to 'noao/obsutil/src/doc/sptime.hlp')
| -rw-r--r-- | noao/obsutil/src/doc/sptime.hlp | 1218 |
1 files changed, 1218 insertions, 0 deletions
diff --git a/noao/obsutil/src/doc/sptime.hlp b/noao/obsutil/src/doc/sptime.hlp new file mode 100644 index 00000000..a2c0f242 --- /dev/null +++ b/noao/obsutil/src/doc/sptime.hlp @@ -0,0 +1,1218 @@ +.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 |