sensfunc standards sensitivity
standards = std
Input standard star data file created by the task standard.
sensitivity = sens
Output sensitivity function image name or rootname. Generally each
aperture results in an independent sensitivity function with the
aperture number appended to the rootname. If the parameter ignoreaps
is set, however, the aperture numbers are ignored and a single sensitivity
function is determined with the output image having the specified name
with no extension.
apertures =
List of apertures to be selected from the input file. All other apertures
are ignored. If no list is specified then all apertures are selected.
See ranges for the syntax.
ignoreaps = no
Ignore aperture numbers and create a single sensitivity function? Normally
each aperture produces an independent sensitivity function. If the
apertures are ignored then all the observations are combined into
a single sensitivity function.
logfile = logfile
Output log filename for statistical information about the stars used
and the sensitivity function and extinction function.
If no filename is given then no file is written.
extinction =
Input extinction file. Any extinction determination made will be
relative to this extinction. If no file is given then no extinction
correction is applied and any extinction determination from the
standard star data will be an absolute determination of the
extinction. The default value is redirected to the package parameter
of the same name. The extinction file is generally one of the standard
extinctions in the calibration directory "onedstds$".
newextinction = extinct.dat
Output revised extinction file. If the extinction is revised and an
output filename is given then a revised extinction file is written. It
has the same format as the standard extinction files.
observatory = )_.observatory
Observatory at which the spectra were obtained if not specified in the
image header by the keyword OBSERVAT. The default is a redirection to look
in the parameters for the parent package for a value. This is only used
when graphing flux calibrated data of spectra which do not include the
airmass in the image header. The observatory may be one of the
observatories in the observatory database, "observatory" to select the
observatory defined by the environment variable "observatory" or the
parameter observatory.observatory, or "obspars" to select the current
parameters set in the observatory task. See help for
observatory for additional information.
function = spline3
Function used to fit the sensitivity data. The function types are
"chebyshev" polynomial, "legendre" polynomial, "spline3" cubic spline,
and "spline1" linear spline. The default value may be changed interactively.
order = 6
Order of the sensitivity fitting function. The value corresponds to the
number of polynomial terms or the number of spline pieces. The default
value may be changed interactively.
interactive = yes
Determine the sensitivity function interactively? If yes the user
graphically interacts with the data, modifies data and parameters
affecting the sensitivity function, and determines a residual extinction.
graphs = sr
Graphs to be displayed per frame. From one to four graphs may be displayed
per frame. The graph types are selected by single characters and are:
a - residual sensitivity vs airmass c - composite residual sensitivity and error bars vs wavelength e - input extinction and revised extinction vs wavelength i - Flux calibrated spectrum vs wavelength r - residual sensitivity vs wavelength s - sensitivity vs wavelength
All other characters including whitespace and commas are ignored. The order and number of graphs determines the positions of the graphs.
marks = plus cross box
Symbols used to mark included, deleted, and added data respectively.
The available mark types are point, box, plus, cross, diamond, hline
(horizontal line), vline (vertical line), hebar (horizontal error bar),
vebar (vertical error bar), and circle.
colors = 2 1 3 4
Colors to use for "lines", "marks", "deleted" data, and "added" data.
The colors associated with the numbers is graphics device dependent.
For example in XGTERM they are defined by resources while on other
devices that don't support colors only one color will appear.
cursor =
Graphics cursor input list. If not specified as a file then standard
graphics cursor is read.
device = stdgraph
Graphics output device.
answer
Query parameter for selecting whether to fit apertures interactively.
? Print help a Add a point at the cursor position c Toggle use of composite points d Delete point, star, or wavelength nearest the cursor e Toggle residual extinction correction f Fit data with a sensitivity function and overplot g Fit data with a sensitivity function and redraw the graph(s) i Print information about point nearest the cursor m Move point, star, wavelength nearest the cursor to new sensitivity o Reset to original data q Quit and write sensitivity function for current aperture r Redraw graph(s) s Toggle shift of standard stars to eliminate mean deviations u Undelete point, star, or wavelength nearest the cursor w Change weights of point, star, or wavelength nearest the cursor :flux [min] [max] Limits for flux calibrated graphs (INDEF for autoscale) :function [type] Function to be fit to sensitivity data: chebyshev - Chebyshev polynomial legendre - Legendre polynomial spline1 - Linear spline spline3 - Cubic spline :graphs [types] Graphs to be displayed (up to four): a - Residual sensitivity vs airmass c - Composite residuals and error bars vs wavelength e - Extinction (and revised extinction) vs wavelength i - Flux calibrated image vs wavelength l - Log of flux calibrated image vs wavelength r - Residual sensitivity vs wavelength s - Sensitivity vs wavelength :images [images] Images to flux calibrate and plot (up to four) :marks marks Mark types to use for included, delete, and added points: point, box, plus, cross, diamond, hline, vline, hebar, vebar, circle :order [order] Order of function :skys [images] Sky images for flux calibration (up to four) :stats [file] Statistics about stars and sensitivity fit :vstats [file] Verbose statistics about sensitivity fit
DESCRIPTION Standard star calibration measurements are used to determine the system sensitivity as a function of wavelength for each independent aperture. If the parameter ignoreaps is set then the aperture numbers are ignored and a single sensitivity function is determined from all the observations. Using measurements spanning a range of airmass it is also possible to derive an adjustment to the standard extinction curve or even an absolute determination. Extinction determination requires that the observations span a good range of airmass during photometric conditions. When conditions are poor and standard star observations are obtained during periods of variable transparency, the entire sensitivity curve may vary by a constant factor, assuming that the cause of the variations has no color effect. This is often the case during periods of thin clouds. In this case the mean sensitivity of each observation may be shifted to match the observation of greatest sensitivity. This allows for the possibility of deriving correct absolute fluxes if one observation of a standard was obtained during a clear period.
The input data is a file of calibration information produced by the task standard. The data consists of a spectrum identification line containing the spectrum image name, the sky image name if beam switching, the aperture number, the length of the spectrum, the exposure time, airmass, wavelength range, and title. Following the identification line are calibration lines consisting of the central bandpass wavelengths, the tabulated fluxes in the bandpasses, the bandpass widths, and the observed counts in the bandpasses. The spectrum identification and calibration lines repeat for each standard star observation. The parameter apertures may be used to select only specific apertures from the input data. This parameter is in the form of a range list (see help for ranges) and if no list is given (specified by the null string "") then all apertures are selected.
An input extinction file may also be specified. Any extinction determinations are then residuals to this input extinction table. The format of this table is described in lcalib.
The calibration factor at each point is computed as
(1) C = 2.5 log (O / (T B F)) + A E
where O is the observed counts in a bandpass of an observation, T is the exposure time of the observation, B is the bandpass width, F is the flux per Angstrom at the bandpass for the standard star, A is the airmass of the observation, and E is the extinction at the bandpass. Thus, C is the ratio of the observed count rate per Angstrom corrected to some extinction curve to the expected flux expressed in magnitudes. The goal of the task is to fit the observations to the relation
(2) C = S(W) + AE(W)
where W is wavelength, S(W) is the sensitivity function, and E(W) is a residual extinction function relative to the extinction used in (1). In later discussion we will also refer to the residual sensitivity which is defined by
(3) R = C - S(W) - AE(W)
The sensitivity function S(W) is output as an one dimensional image much like the spectra. The sensitivities are in magnitude units to better judge the variations and because the interpolation is smoother in the logarithmic space (mags = 2.5 log10[sensitivity]). There is one sensitivity function for each aperture unless the parameter ignoreaps is set. In the first case the image names are formed from the specified rootname with the aperture number as a four digit numerical extension. In the latter case a single sensitivity function is determined from all data, ignoring the aperture numbers, and the specified output image is created without an extension. These images are used by calibrate to correct observations to a relative of absolute flux scale. If no sensitivity function image rootname is specified then the sensitivity curves are not output.
If a revised extinction function E(W) has been determined for one or more of the apertures then the functions are averaged over all apertures, added to the original extinction, and written to the specified extinction table. The format of this table is the same as the standard extinction tables and are, thus, interchangable. If no new extinction filename is specified then no extinction table is recorded.
If a log filename is given then statistical information about the sensitivity function determinations are recorded. This includes the names of the input standard star observations and the tabulated sensitivity, extinction, and error information.
Some points to note are that if no input extinction is given then the E in (1) are zero and the E determined in (2) is the absolute extinction. If the data are not good enough to determine extinction then using one of the standard extinction curves the problem reduces to fitting
(4) C = S(W)
The sensitivity and extinction functions are determined as fitted curves. The curves are defined by a function type and order. There are four function types and the order specifies either the number of terms in the polynomial or the number of pieces in the spline. The order is automatically reduced to the largest value which produces a nonsingular result. In this case the function will attempt to pass through every calibration point. Lower orders provide for a smoother representation of the function. The latter is generally more appropriate for a detector. The initial function type and order for the sensitivity function is specified by the parameters function and order.
If the interactive flag is no then the default function and order is fit to equation (4) (i.e. there is no residual extinction determination or manipulation of the data). The sensitivity functions are output if an image rootname is given and the log information is output if a log filename is given.
When the sensitivity is determined interactively a query is given for each aperture. The responses "no" and "yes" select fitting the sensitivity interactively or not for the specified aperture. The responses "NO" and "YES" apply to all apertures and no further queries will be given. When interactive fitting is selected the data are graphed on the specified graphics device and input is through the specified cursor list. The graphics output consists of from one to four graphs. The user selects how many and which types of graphs to display. The graph types and their single character code used to select them are:
a - residual sensitivity vs airmass c - composite residual sensitivity and error bars vs wavelength e - input extinction and revised extinction vs wavelength i - Flux calibrated spectrum vs wavelength r - residual sensitivity vs wavelength s - sensitivity vs wavelength
The initial graphs are selected with the parameter graphs and changed interactively with the colon command ":graphs types". The ability to view a variety of graphs allows evaluating the effects of the sensitivity curve and extinction in various ways. The flux calibrated spectrum graph uses the current sensitivity function and checks for possible wiggles in the sensitivity curve which affect the shape of the continuum. The choice of graphs also allows the user to trade off plotting speed and resolution against the amount of information available simultaneously. Thus, with some graphics devices or over a slow line one can reduce the number of graphs for greater speed while on very fast devices with large screens one can look at more data. The parameter marks and the associated colon command ":marks types" also let the user define the symbols used to mark included, deleted, and added data points.
The list of interactive commands in given in the section on CURSOR COMMANDS. The commands include deleting, undeleting, adding, moving, and identifying individual data points, whole stars, or all points at the same wavelength. Some other commands include 'c' to create composite points by averaging all points at the same wavelength (this requires exact overlap in the bandpasses) which then replace the individual data points in the fit. This is different than the composite point graph which displays the residual in the mean sensitivity and error in the mean but uses the input data in the fitting. The 's' command shifts the data so that the mean sensitivity of each star is the same as the star with the greatest mean sensitivity. This compensates for variable grey extinction due to clouds. Another useful command is 'o' to recover the original data. This cancels all changes made due to shifting, extinction corrections, deleting points, creating composite points, etc.
The 'e' command attempts to compute a residual extinction by finding correlations between the sensitivity points at different airmass. Note that this is not iterative so that repeating this after having added an extinction correction simply redetermines the correction. At each wavelength or wavelength regions having multiple observations at different airmass a slope with airmass is determined. This slope is the residual extinction at that wavelength. A plot of the residual extinctions at each wavelength is made using the ICFIT procedure. The user may then examine and fit a curve through the residual extinction estimates as a function of wavelength (see icfit for a description of the commands). The user must decide how much wavelength dependence is derivable from the data. In many cases only a constant fit to a "gray extinction" or possibly a linear fit is realistic. The fitting is exited by the key 'q'.
To help evaluate how important the residual extinction determination is a t-statistic significance is computed. This statistic is defined by
(5) t = sqrt (r**2 * (N - 2) / (1 - r**2))
where the correlation coefficient
(6) r = RMS with correction / RMS without correction
is the fractional improvement in the RMS due to the added extinction correction and N is the number of wavelength points. For large N this approaches a gaussian sigma but a more precise significance requires the t-distribution for N-2 degrees of freedom. Basically this asks, was the improvement in the RMS significantly more than would occur with random errors? A value greater than 3 is good while a value less than 1 is not significant. The user may then accept the revised extinction and apply it to the data.
Note that when there are multiple apertures used each aperture has an independent system sensitivity but the residual extinction is the same. Therefore, the residual extinctions from each aperture are averaged at the end. If one determines a new extinction then one may replace the original input extinction by the new extinction and rederive the sensitivity.
1. The following command generates sensitivity spectra
cl> sensfunc std sens
This command uses the data from the standard output file "std" to create sensitivity functions with rootname "sens". If not interactive the task will produce the output with some progress messages being printed. If it is interactive the graphics device will be used to display the data and the fit and user can change the function and order of the fit, delete bad points, shift data to correct for clouds or bandpass errors, and possibly determine a revised extinction function. The statistics of the sensitivity determination are written to the logfile ("logfile" by default).
2. The following examples illustrate the colon command syntax. Generally if no argument is given the current value is displayed. For the statistics commands an optional output file may be given to record the information.
:flux 1e-12 INDEF Set lower limit for flux plots :flux INDEF INDEF Restore autoscaling in flux plots :func spline3 Select cubic spline function :g srae Graph sensitivity, residuals, airmass, and extinction :g sii Graph sensitivity and two images :i n1.0004 n1.0008 Set first two images to graph (the defaults are taken from the standard star list) :skys n1.0005 Subtract this sky image from first image for flux calibrated spectrum :m plus Change the mark type for included points and don't change the deleted or added point mark type :stats Print statistics to terminal :vstats stdstats Print verbose statistics to file
REVISIONS
SENSFUNC V2.10.3
A color parameter was added for graphics terminals supporting color.
SENSFUNC V2.10
The latitude parameter has been replaced by the observatory parameter.
The 'i' flux calibrated graph type now shows flux in linear scaling
while the new graph type 'l' shows flux in log scaling. A new colon
command allows fixing the flux limits for the flux calibrated graphs.
SENSFUNC V2.8
This task has been completely rewritten from that of versions 2.5 and
earlier.
1. The input standard data format is different. 2. Extinction corrections beyond a grey term are now supported. 3. Weighting by the counts is not supported. 4. Tabular input is not supported. 5. The data which can be displayed is greatly improved. 6. The fitting options have been greatly enhanced. 7. The fitting function types available have been extended. 8. One or more flux calibrated images may be displayed using the current sensitivity function. 9. Additional flexibility is provided for treating apertures.
BUGS If the flux points do not span the wavelength range, set by the standard star observations, then the fitting may fail at some maximum order. When it fails there is no message but the highest order which can be successfully fit is used. To work around this one can either add fake points, truncate the wavelength range in the first line of each tabulated object in the file produced by standard, or exclude the part of the image data which cannot be uncalibrated (using scopy or dispcor).
standard, lcalib, calibrate, observatory, icfit, ranges, scopy, dispcor,