diff options
Diffstat (limited to 'noao/onedspec/doc/skytweak.hlp')
| -rw-r--r-- | noao/onedspec/doc/skytweak.hlp | 311 |
1 files changed, 311 insertions, 0 deletions
diff --git a/noao/onedspec/doc/skytweak.hlp b/noao/onedspec/doc/skytweak.hlp new file mode 100644 index 00000000..857e4380 --- /dev/null +++ b/noao/onedspec/doc/skytweak.hlp @@ -0,0 +1,311 @@ +.help skytweak Mar97 noao.onedspec +.ih +NAME +skytweak -- sky subtract 1D spectra after tweaking sky spectra +.ih +SUMMARY +Sky spectra are shifted and scaled to best subtract sky 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 +skytweak 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 sky 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 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 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 sky features by +subtracting a shifted and scaled sky calibration spectra. +The shifting +allows for possible small shifts or errors in the dispersion zeropoints. + +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) = J(x+dx) *scale +.fi + +where dx is the pixel shift parameter and +scale is the scale parameter. +The output corrected spectrum is then computed as + +.nf + (2) I'(x_i) = I(x_i) - J'(x_i) +.fi + +where I' is the corrected spectrum and I is the input spectrum. 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> skytweak spec001.ms skyspec001.ms spec005.ms +.fi + +2. To search only for a scale factor: + +.nf + cl> skytweak spec001.ms skyspec001.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> skytweak spec* "" skyspec inter- > log +.fi +.ih +REVISIONS +.ls SKYTWEAK V2.11 +This task is new in this version. +.le +.ih +SEE ALSO +telluric +.endhelp |