diff options
Diffstat (limited to 'noao/onedspec/doc/telluric.hlp')
| -rw-r--r-- | noao/onedspec/doc/telluric.hlp | 350 |
1 files changed, 350 insertions, 0 deletions
diff --git a/noao/onedspec/doc/telluric.hlp b/noao/onedspec/doc/telluric.hlp new file mode 100644 index 00000000..f0bfe597 --- /dev/null +++ b/noao/onedspec/doc/telluric.hlp @@ -0,0 +1,350 @@ +.help telluric Mar97 noao.onedspec +.ih +NAME +telluric -- remove telluric features from 1D spectra +.ih +SUMMARY +Telluric calibration spectra are shifted and scaled to best divide out +telluric features from data spectra. This may be done non-interactively to +minimize the RMS in some region or regions of the data spectra and +interactively with a graphically search. +.ih +USAGE +telluric input output cal +.ih +PARAMETERS +.ls input +List of input data images containing one dimensional spectra to be +corrected. All spectra in each image are corrected. The spectra need not +be wavelength calibrated. +.le +.ls output +List of output corrected images. The list must either match the input list +or be an empty list. If an empty list is specified the input spectra will +be replaced by the corrected spectra. The input spectra will also be +replaced if the input and output image names are the same. Any other image +name must be for a new image otherwise a warning message will be given and +the task will proceed to the next input image. +.le +.ls cal +List of telluric calibration images. If a single image is specified it +will apply to all the input images. Otherwise the list of calibration +images must match the list of input images. +.le +.ls ignoreaps = no +Ignore aperture numbers between the input spectra and the calibration +spectra? If "no" then the calibration image must contain a spectrum +with the same aperture number as each spectrum in the input image. +Otherwise the first spectrum in the calibration image will be used +for all spectra in the input image. +.le +.ls xcorr = yes +Cross-correlate each input spectrum with the calibration spectrum to +determine an shift for the calibration spectrum? Only regions specified by +the sample regions parameter will be used in the cross-correlation. +.le +.ls tweakrms = yes +Search for the minimum RMS in the corrected spectrum by adjusting the +shifts and scales between the input spectrum and the calibration spectrum? +The RMS is minimized in the specified sample regions. +.le +.ls interactive = yes +Enter an interactive graphical mode to search for the best shift +and scale between the input spectra and calibration spectra? This +is done after the optional automatic cross-correlation and RMS minimization +step. A query is made for each input spectrum so that the interactive +step may be skipped during the execution of the task. +.le +.ls sample = "*" +Sample regions to use for cross-correlation, automatic RMS minimization, +and RMS values. The sample regions are specified by a list of comma +separated ranges. The ranges are colon separate coordinate values. +For dispersion calibrated spectra the coordinate values are in the +dispersion units otherwise they are in pixel coordinates. The string "*" +selects the entire spectrum. The sample regions may be changed +interactively either with the cursor or with a colon command. +.le +.ls threshold = 0. +Since the calibration consists of division by the scaled calibration data +it is possible for totally saturated lines to have zero or negative values. +The task will quit if detects negative or zero calibration values. The +\fIthreshold\fR allows applying a minimum threshold to the calibration +values so the task may continue. +.le +.ls lag = 10 +The cross-correlation lag to use when \fIxcorr\fR = yes. The lag +is given in pixels. This is the distance to either side of the +initial shift over which the cross-correlation profile is computed. +If a value of zero is given then the cross-correlation step is not done. +.le +.ls shift = 0., dshift = 1. +The initial shift and shift step in pixels. This initializes the shift +search parameters for the first spectrum. If \fIdshift\fR is zero then +there will be no search for a new shift and the 'x' interactive function is +disabled. These parameters may be changed interactively. After the +first spectrum subsequent spectra begin with the values from the last +spectrum. +.le +.ls scale = 1., dscale = 0.2 +The initial scale and scale step. This initializes the scale +search parameters for the first spectrum. If \fIdscale\fR is zero then +there will be no search for a new scale and the 'y' interactive function is +disabled. These parameters may be changed interactively. After the +first spectrum subsequent spectra begin with the values from the last +spectrum. +.le +.ls offset = 1. +The interactive search displays three candidate corrected spectra which +have been normalized to a mean of one. The offset is added and subtracted +to separate the three candidates. The value may be changed interactively. +.le +.ls smooth = 1 +The displayed candidate corrected spectra are smoothed by a moving +boxcar average with a box size specified by this parameter. The smoothing +only applies to the displayed spectra and does not affect the measured +RMS or the output corrected spectra. The value may be changed interactively. +.le +.ls cursor = "" +Input cursor for the interactive graphics. A null value selects the +graphics cursor otherwise a file of cursor values may be specified. +.le +.ls airmass +Query parameter for the airmass. If the airmass is not in the image +header under the keyword AIRMASS the user is queried for the airmass. +This parameter should not be specified on the command line. +.le +.ls answer +Query parameter for responding to the interactive question. This parameter +should not be specified on the command line. +.le +.ls interp = poly5 +The \fBpackage\fR parameter specifying the interpolation function for shifting +the calibration spectra to match the input spectra. +.le +.ih +DESCRIPTION +Input one dimensional spectra are corrected to remove telluric features by +dividing by shifted and scaled calibration spectra. The calibration +spectra are generally of hot, nearly featureless stars; hence this procedure +is sometimes referred to as a B-star correction. The shifting +allows for possible small shifts or errors in the dispersion zeropoints. +The intensity scaling allows for differences in the airmass and variations +in the abundance of the telluric species. The intensity scaling +uses Beer's law which is the approximation that the change in absorption +with abundance is an exponential relation. + +The following describes the correction. Let J(x_i) be the calibration +spectrum at a set of pixels x_i. An interpolation function is fit to this +spectrum to give J(x). The shifted and scaled calibration function +is then + +.nf + (1) J'(x) = max (threshold, J(x+dx)) ** (A / A_cal * scale) +.fi + +where dx is the pixel shift parameter, A is the airmass of the input +spectrum, A_cal is the airmass of the calibration spectrum, and +scale is the scale parameter. The operator "**" is exponentiation. +The max operation limits the calibration spectrum to be greater +than or equal to the specified threshold value. If the calibration +value is ever less than or equal to zero then the task will quit +with a warning error. + +The output corrected spectrum is then computed as + +.nf + (2) I'(x_i) = I(x_i) / (J'(x_i) / <J'>) +.fi + +where I' is the corrected spectrum, I is the input spectrum, and <J'> is +the mean of the shifted and scaled calibration spectrum to keep the output +intensities comparable to the input spectrum. The value of <J'> is +printed in the output as the "normalization". If the spectra are +dispersion calibrated, possibly with different dispersion parameters, then +the x values in (2) from the input spectrum are converted to matching +pixels in the calibration spectrum using the dispersion functions of the +two spectra. + +The purpose of this task is to determine the best values of the +shift and scale parameters dx and scale. There +are automatic and interactive methods provided. The automatic +methods are cross-correlation of the calibration and input spectra +to find a shift and an iterative search for the in both +shift and scale that minimizes the RMS of I' in some region. +The automatic methods are performed first, if selected, followed +by the interactive, graphical step. The following describes +the steps in the order in which they occur. + +The initial values of the shift and scale are set by the parameters +\fIshift\fR and \fIscale\fR for the first spectrum. After that the values +determined for the previous spectrum, those actually applied to correcting +that spectrum, are used as the initial values for the next spectrum. The +search steps and sample regions are also initialized by task parameters but +may be modified during the interactive step and the modified values apply +to subsequent spectra. + +If the \fIxcorr\fR parameter is yes and the \fIlag\fR parameter is +not zero the calibration spectrum is cross-correlated against the input +spectrum. Each spectrum is prepared as follows. A large scale continuum +is fit by a quadratic chebyshev using 5 iterations of sigma clipping with a +clipping factor of 3 sigma below the fit and 1 sigma above the fit and +rejecting the deviant points along with one pixel on either side. This +attempts to eliminate the effects of absorption lines. The continuum fit +is subtracted from the spectrum and the spectrum is extended and tapered by +a cosine function of length given by the \fIlag\fR parameter. + +The prepared spectra are then cross-correlated by shifting the calibration +spectrum plus and minus the specified \fIlag\fR amount about the current +shift value. Only the regions in the input spectrum specified by the +sample regions parameter are used in the correlation. This produces a +correlation profile whose peak defines the relative shift between the two +spectra. The current shift value is updated. This method assumes the +common telluric features dominate within the specified sample regions. The +lag size should be roughly the profile widths of the telluric features. + +If the \fItweakrms\fR parameter is yes and \fIdshift\fR is greater than +zero trial corrections at the current shift value and plus and minus one +shift step with the scale value fixed at its current value are made and the +RMS in the sample regions computed. If the RMS is smallest at the current +shift value the shift step is divided in half otherwise the current shift +value is set to the shift with the lowest RMS. The process is then +repeated with the new shift and shift step values. This continues until +either the shift step is less than 0.01 pixels or the shift is more than +two pixels from the initial shift. In the latter case the final shift is +reset to the original shift. + +The scale factor is then varied if \fIdscale\fR is greater than zero by the +scale step at a fixed shift in the same way as above to search for a +smaller RMS in the sample regions. This search terminates when the scale +step is less than 0.01 or if the scale value has departed by 100% of the +initial value. In the latter case the scale value is left unchanged. + +The search over the shifts and scales is repeated a second time after which +the tweak algorithm terminates. + +After the optional cross-correlation and tweak steps the interactive search +mode may be entered. This occurs if \fIinteractive\fR = yes. A query is +asking whether to search interactively. The answers may be "no", "yes", +"NO", or "YES". The lower case answers apply to the current spectrum and +the upper case answers apply to all subsequent spectra. This means that if +an answer of "NO" or "YES" is given then there will be no further queries +for the remaining input spectra. + +If the interactive step is selected a graph of three candidate corrections +for the input spectrum is displayed. There also may be a graph of the +calibration or input spectrum shown for reference. Initially the +calibration spectrum is displayed. The additional graph may be toggled off +and on and between the input and calibration spectra with the 'c' and 'd' +keys. The three candidate corrected spectra will be with the current shift +and scale in the middle and plus or minus one step in either the shift or +scale. Initially the spectra will be at different scale values. +Information about the current shift and scale and the step used is given in +the graph title. + +One may toggle between shift steps and scale steps with the 'x' (for shift) +or 'y' (for scale) keys. The RMS in the title is the RMS within the +currently defined sample regions. If one of the step values is zero then a +display of different values of that parameter will not be selected. The +step size will need to be set with a colon command to search in that +parameter. + +If 'x' is typed when the three spectra are at different shifts then the +nearest spectrum to the y cursor at the x cursor position will be +selected. If the central spectrum is selected the step size is divided in +half otherwise the current shift is changed and the selected spectrum +becomes the middle spectrum. Three new spectra are then shown. The same +applies if 'y' is typed when the three spectra are at different scales. +This allows an interactive search similar to the iterative tweakrms method +described previously except the user can use whatever criteria is desired +to search for the best scale and shift. + +There are additional keystrokes and colon commands to set or change sample +regions, reset the current shift, scale, and step sizes, expand the step +size in the current mode, adjust the offsets between the spectra, and +get help. The 'w' key and GTOOLS colon commands are available to window +the graphs. Any changes in the x limits apply to both graphs while y limit +adjustments apply to the graph pointed to by the cursor. + +Two other commands require a short explanation. The 'a' key may +be used to run the tweakrms algorithm starting from the current +shift, scale, and steps and the current sample regions. This allows +one to graphically set or reset the sample regions before doing +the RMS minimization. The ":smooth" command and associated +\fIsmooth\fR task parameter allow the corrected spectra to be +displayed with a boxcar smoothing to better see faint features in +noise. It is important to realize that the smoothing is only +done on the displayed spectra. The telluric correction and computed RMS +are done in the unsmoothed data. + +After the interactive step is quit with 'q' or if the interactive +step is not done then the final output spectrum is computed and +written to the output image. A brief log output is printed for +each spectrum. +.ih +CURSOR KEYS AND COLON COMMANDS +.nf +? - print help +a - automatic RMS minimization within sample regions +c - toggle calibration spectrum display +d - toggle data spectrum display +e - expand (double) the step for the current selection +q - quit +r - redraw the graphs +s - add or reset sample regions +w - window commands (see :/help for additional information) +x - graph and select from corrected shifted candidates +y - graph and select from corrected scaled candidates + +:help - print help +:shift [value] - print or reset the current shift +:scale [value] - print or reset the current scale +:dshift [value] - print or reset the current shift step +:dscale [value] - print or reset the current scale step +:offset [value] - print or reset the current offset between spectra +:sample [value] - print or reset the sample regions +:smooth [value] - print or reset the smoothing box size +.fi +.ih +EXAMPLES +1. To interactively search for a best correction with the default +cross-correlation and tweak steps: + +.nf + cl> telluric spec001.ms telspec001.ms spec005.ms +.fi + +2. To search only for a scale factor: + +.nf + cl> telluric spec001.ms telspec001.ms spec005.ms xcorr- dshift=0. +.fi + +3. To processes a set of spectra non-interactively with the same calibration +spectrum and to replace the input spectra with the corrected spectra and +log the processing: + +.nf + cl> telluric spec* "" calspec inter- > log +.fi + +4. To apply the simplest scaling by the ratio of the airmasses alone: + +.nf + cl> telluric spec* tel//spec* calspec inter- xcorr- tweak- inter- \ + >>> scale=1. shift=0. +.fi +.ih +REVISIONS +.ls TELLURIC V2.12.3 +The normalization is printed. +.le +.ls TELLURIC V2.11.2 +Threshold parameter added. +.le +.ls TELLURIC V2.11 +This task is new in this version. +.le +.ih +SEE ALSO +skytweak +.endhelp |