From fa080de7afc95aa1c19a6e6fc0e0708ced2eadc4 Mon Sep 17 00:00:00 2001 From: Joseph Hunkeler Date: Wed, 8 Jul 2015 20:46:52 -0400 Subject: Initial commit --- noao/rv/doc/rv.spc | 918 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 918 insertions(+) create mode 100644 noao/rv/doc/rv.spc (limited to 'noao/rv/doc/rv.spc') diff --git a/noao/rv/doc/rv.spc b/noao/rv/doc/rv.spc new file mode 100644 index 00000000..720f1b0b --- /dev/null +++ b/noao/rv/doc/rv.spc @@ -0,0 +1,918 @@ +.help rvxcor Aug90 noao.rv +.ih +INTRODUCTION + +Specifications are presented for a Fourier cross-correlation task used +to compute either relative or heliocentric radial velocities. Input +data need not be dispersion corrected, and the user has full control +over cross-correlation function (ccf) peak fitting, continuum subtraction, +and Fourier filtering of the data. Several sub-modes exist wherein the +user may examine the Fourier characteristics of the data, interactively +fit the continuum, and examine the input spectra themselves. Output +options include a text logfile which may be parsed with the IRAF \fIfields\fR +task, a GKI metacode file containing a summary plot of the correlation, +and optionally a text or IRAF image of the ccf itself (from interactive +operation only). + +.ih +SUMMARY +.nf + + BASIC TASK ORGANIZATION + + List of object and template spectra + | + | +------------------------+ + | | Rebin the data? | + +--------------+ | Fit/subtract continuum | + | Prepare data |<----->| Zero endpoints and pts | + +--------------+ | not in sample | + | | Subtract bias | + | | Apodize end regions | + +----------------------+ | Center in FFT array | + | Compute correlation | +------------------------+ + | Display correlation | + | Fit correlation peak | + +----------------------+ + | + +--------------------+-----------------------+ + ^ ^ ^ + / \ / \ / \ + | | | + \ / \ / \ / + ` ` ` ++-------------------+ +---------------------+ +-------------------+ +| Fourier filtering |-->| Spectra review |-->| Continuum fitting | +| |<--| Mark sample regions |<--| ICFIT | ++-------------------+ +---------------------+ +-------------------+ + + TASK PARAMETERS + +Input parameters: objects + templates + apertures = "*" + cursor = "" + +Data preparation: continuum = "both" + filter = "none" + sample = "*" + apodize = 0.2 + +Peak fitting: function = "gaussian" + width = INDEF + height = 0.0 + peak = no + minwidth = 3. + maxwidth = 11. + weights = 1.0 + background = 0.0 + window = 20 + +Output parameters: output = "" + verbose = "yes" + imupdate = "no" + graphics = "stdgraph" + +Control parameters: interactive = "yes" + autowrite = "yes" + ccftype = "image" + +Parameter sets: continpars = "" + filterpars = "" + rvkeywords = "" + observatory = "" + +MAIN CORRELATION FITTING COMMAND SUMMARY + +? Print list of cursor key and colon commands +- Subtract blended component from correlation peak ++ Toggle status line output +a Display the antisymmetric noise component of the correlation +b Fix background level for Gaussian fit +c Plot polymarkers of actual CCF points on the plot +d Deblend multiple correlation peak +e Preview the summary plot of the correlation +f Fourier filtering and display mode +g Mark correlation peak lag limits and fit +j Plot the residuals of the fit to the peak +k Plot the ratio of the fit to the peak +l Page the log file of results +n Go to next (template --> aperture --> object) +o Fit or refit object spectrum continuum for subtraction +p Go to previous (template --> aperture --> object) +q Quit task +r Redraw +s Examine object/template spectra and display mode +t Fit or refit template spectrum continuum for subtraction +v Print full correlation results in text window +w Write current correlation results to the log file +x Compute a new correlation +y Mark correlation peak lower limit and fit +z Expand on different correlation peak using full correlation plot + +:next [template|aperture|object] Go to next correlation pair +:parameters List current parameters +:previous [template|aperture|object] Go to previous correlation pair +:results [file] Page results +:wccf file Write the CCF to an image/text file + +Other colon commands set or show parameter values + +FOURIER FILTERING COMMAND SUMMARY + +? Print list of cursor key and colon commands +b Display power spectra before filtering +f Display Fourier transforms after filtering +g Display Fourier transforms before filtering +i Print period trend information +p Display power spectra after filtering +q Quit +r Redraw +s Enter spectrum mode +x Return to correlation mode + +:log_scale [yes|no] Set log scaling on Y axis +:overlay [yes|no] Overlay filter function +:parameters List current parameter values +:zoom [factor] Zoom x region + +Other colon commands set or show parameter values + +SPECTRUM REVIEW COMMAND SUMMARY + +? Print list of cursor key and colon commands +d Print velocity difference between two cursor positions +e Plot a preview of the summary plot +f Enter Fourier mode +i Display original input spectra +n Display continuum subtracted spectra +q Quit +r Redraw +s Mark sample regions +x Return to correlation mode + +:sample [list] List of sample regions + +CONTINUUM FITTING COMMAND SUMMARY + +See \fBicfit\fR. +.fi +.bp +.ih +NAME +rvxcor -- compute radial velocities via Fourier cross correlation +.ih +USAGE +rvxcor objects templates +.ih +PARAMETERS +.ce +INPUT PARAMETERS +.ls objects +The list of image names for the input object spectra. +.le +.ls templates +The list of image names that will be used as templates for the cross +correlation. +.le +.ls apertures = "*" +List of apertures to be used. This number is used for \fIboth\fR the +object and reference spectra. A '*' means to process all of the +apertures in the spectrum. If the template spectrum is one-dimensional, +that spectrum will be used as a template for all specified apertures in +the object spectrum. +.le +.ls cursor = "" +Graphics cursor input. +.le + +.ce +DATA PREPARATION PARAMETERS +.ls continuum = "both" +Continuum subtract the spectra prior to correlation? Possible values for +this parameter are any of the strings (or abbreviations) "object" (for object +spectrum only), "template" (for template spectrum only), or "both" for +continuum flattening both object and template spectra, or simply "none" for +flattening neither spectrum. The \fIcontinpars\fR pset is used to specify +the continuum fitting parameters. +.le +.ls filter = "none" +Fourier filter the spectra prior to correlation? Possible values for +this parameter are any of the strings (or abbreviations) "object" (for object +spectrum only), "template" (for template spectrum only), or "both" for +fourier filtering both object and template spectra, or simply "none" for +filtering neither spectrum. The \fIfilterpars\fR pset holds the parameters +for the filtering (filter type and width). +.le +.ls sample = "*" +Sample regions of the spectrum to be used in the correlation specified +in pixels if the first character is a 'p' or angstroms if the first +character is an 'a'. The default (i.e. no 'a' or 'p' as the first +character), if a range is provided, is a range specified in pixels. +This string value will be updated in an interactive session as sample +regions are re-selected. The default, '*', is the entire spectrum. The +region is specified as a starting value, a '-', and an ending value. +.le +.ls apodize = 0.2 +Fraction of endpoints to apodize with a cosine bell when preparing the data +prior to the FFT. +.le + +.ce +CORRELATION PEAK FITTING PARAMETERS +.ls function = "gaussian" +Function used to find the center and width of the correlation peak. +Possible choices are "gaussian", "parabola", "lorentzian", or "center1d". +If a parabola or center1d fit is selected then only the center is determined. +.le +.ls width = INDEF +Width of the fitting region in pixels. The fitting weights are +zero at the endpoints so the width should be something +like the expected full width. If INDEF, then the width is +set by the \fIheight\fR and \fIpeak\fR parameters. If other than INDEF, +this parameter will override the \fIheight\fR and \fIpeak\fR parameters. +It is recommended that an odd value of \fIwidth\fR be used to assure an +even number of pixels around the peak height. +.le +.ls height = 0. +The width of the fitting region is defined by where the correlation +function crosses this height starting from the peak. The height is +specified as either a normalized correlation level (this is like +the 'y' interactive key) or normalized to the peak. The type of +level is selected by the peak parameter. +.le +.ls peak = no +Measure the height parameter relative to the correlation peak value +rather than as a normalized correlation level? If yes, then \fIheight\fR +is a fraction of the peak height with an assumed base of zero. +.le +.ls minwidth = 3., maxwidth = 11. +The minimum and maximum widths allowed when the width is determined +from the height. +.le +.ls weights = 1. +Power of distance defining the fitting weights. The points used +in fitting the correlation peak are weighted by a power of the +distance from the center as given by the equation +.nf + + 1 - (distance / (width/2)) ** weights + +.fi +Note that a weight parameter of zero is equivalent to uniform weights. +The center1d fitting algorithm uses it's own weighting function. +.le +.ls background = 0.0 +Background level, in normalized correlation units, for a Gaussian or +Lorentzian fitting function. If set to INDEF, the background is a free +parameter in the fit. +.le +.ls window = 20 +Size of the window in the correlation plot. The peak will be displayed +with a window centered on the peak maximum and two times \fIwindow\fR +lags wide. +.le + +.ce +OUTPUT PARAMETERS +.ls output = "" +File name of file to which output will be written. If no file name is given +then no log files will be kept, but the user will be queried for a file name +if a write operation is performed. Text output will have a ".txt" sufix +appended, and the graphics metacode file will be appended with a ".gki" suffix. +.le +.ls verbose = "yes" +Print a verbose output record to the \fIoutput\fR file? The verbose output +will be a single line ~160 characters wide. The \fIfields\fR task may +be used to strip out selected columns. Non-verbose output is ~80 chars wide. +.le +.ls imupdate = "no" +Update the image header with the computed velocities? If set to yes, then +the image will be updated with the observed and heliocentric velocities +by adding the \fIrvkeywords.vobs\fR and \fIrvkeywords.vhelio\fR keywords +respectively. Two-dimensional spectra will have the keywords added with +the aperture number appended to the keyword. +.le +.ls graphics = "stdgraph" +Output graphics device. +.le + +.ce +CONTROL PARAMETERS +.ls interactive = "yes" +Process spectra interactively? +.le +.ls autowrite = "yes" +Automatically record the last fit to the log file when moving to the next +spectrum? If set to "no", the user will be queried whether to write the +results if no write was performed, and possibly queried for a file name +if \fIoutput\fR isn't set. +.le +.ls ccftype = "image" +Type of output to create when writing out the correlation function with +the ":wccf file" command. Possible choices are "text" which will be a +simple list of (lag,correlation_value) pairs, or "image" which will be an +IRAF image whose header would describe the lag limits and selected peak. +.le + +.ce +ADDITIONAL PARAMETER SETS +.ls continpars = "" +The processing parameters as described in the \fIcontinpars\fR named pset. +.le +.ls filterpars = "" +This is a parameter set defining the parameters to be used in filtering the +data prior to the correlation. +.le +.ls rvkeywords = "" +The image header keyword translation table as described in +the \fIrvkeywords\fR named pset. +.le +.ls observatory = "" +The observatory parameter set giving the location of the observation. These +values are used in the heliocentric correction routines. +.le +.ih +DESCRIPTION +\fIRvxcor\fR performs a Fourier cross-correlation on the input list of object +and template spectra. Object spectra may be either one or two dimensional +(in `echelle' or `multispec' format), and may be correlated against a one +or two dimensional template. If the template spectrum is only one dimensional +but the object is two dimensional, the template is used to correlate each of +the apertures specified by the \fIapertures\fR parameter. Two dimensional +templates will correlate corresponding apertures. + +If the input spectra are not dispersion corrected (DC-FLAG parameter missing +or less than zero) then only a pixel space correlation is done. This is +appropriate for a simple cross-correlation of images whether spectra or not. +If the spectra are dispersion corrected a log binned correlation is +performed and various radial velocity measurements are made. At a minimum, +a relative velocity between the object and template spectra are produced. +If the image headers contain sufficient information for heliocentric +velocity corrections (see help for \fBrvkeywords\fR), the corrections are +computed and possibly recorded in the image header. If the value of the +heliocentric velocity is returned as INDEF, the user may use the 'v' +keystroke to see the full results of the correlation, including errors +which occured causing the corrections to not be done. + +A number of operations may be performed to prepare the data for +correlation. If a linear wavelength dispersion is defined the spectra +are rebinned to a log-linear dispersion. The starting and ending wavelength, +the dispersion in log space, and the number of pixels are determined from +the template. If the \fIcontinuum\fR flag is set to sonething other than +"none", the object and/or template data will +be continuum subtracted using the fitting parameters found in the +\fIcontinpars\fR pset on input. The data is zeroed outside the sample +region specified by the \fIsample\fR parameter, the bias is subtracted, +and the ends apodized. If the \fIfilter\fR flag is set to something other than +"none", the data are Fourier filtered according to the parameters in +the \fIfilterpars\fR pset prior to the correlation computation. + +Once the correlation is computed, the maximum peak is found and fit +according to the \fIwidth\fR, \fIheight\fR and \fIpeak\fR parameters. +A small, unlabelled plot of the entire correlation function is +drawn above a larger, +expanded plot centered on the peak in a window of size specified by the +\fIwindow\fR parameter. The dashed lines in the small plot +show the limits of the expanded plot. The bottom axis is labelled with +pixel lag and, if dispersion information is present, the top axis +is labelled with relative velocity. The status line will contain a +summary of the pixel shift from the fit and optional velocity +information. The 'v' keystroke may be used to suspend graphics and get +a more detailed description of the correlation and fit. To view the +antisymmetric noise component of the correlation function, simply hit +the 'a' keystroke followed by any keystroke to return to the correlation +plot. Similarly, the 'e' keystroke may be used to preview the summary +plot of the correlation, again hitting any key to return to the correlation. + +If the user is dissatisfied with the fit to the peak, he can mark the +left and right side of the peak with the 'g' keystroke to redo the fit, +or else set the cursor to mark a cutoff with the 'y' keystroke, and all +points from the peak maximum to the cursor will be fit. To fix the background +of a Gaussian fit (i.e. change the \fIbackground\fR parameter graphically), +type the 'b' keystroke at the desired level. To choose a different +peak to fit, move the cursor to the top plot of the whole ccf and hit the +'z' keystroke at the desired peak. The plot will be redrawn with the new +peak now centered in the window and a fit automatically done. The 'r' +keystroke may be used at any time to redraw the plot, and the 'x' keystroke +can be used to compute a new correlation if any of the parameters relating +to the correlation are changed +(e.g. the apodize percentage). New correlations are automatically computed +when new images are read in, the data are continuum subtracted, a different +region is selected for correlation, or Fourier filtering is done. + +For binary star work, the user may type the 'd' and/or '-' keystrokes to fit +and then subtract up to four Gaussians to the peaks. This feature behaves +exactly as the deblending functions in the task \fIonedspec.splot\fR. Consult +the \fIsplot\fR help page for details. If multiple peaks were fit, +a separate entry +will be made in the log file for each peak with a comment that it was part of +a blended peak. The metacode file will contain only one summary plot with +each peak marked with it's heliocentric velocity (if velocities requested) +or pixel shift and error. + +To move to the next spectrum, simply hit the 'n' keystroke. Similary, +the 'p' keystroke will move to the previous spectrum. These commands +have a hitch, though. By default, the next/previous commands will move +first to the next template in the template image list. Once the end of the +template image list is reached, the next spectrum will be the next aperture +in the list specified by \fIapertures\fR, resetting the template image list +automatically and possibly updating the aperture in the template image +as well. Finally, after correlating all of the templates against +all of the apertures, the next/previous command will move to the next +object image, again resetting the template image and/or aperture list. +To override this sequence, the user may use the ":next" +or ":previous" commands and specify one of "aperture", "object", or +"template". If the \fIautowrite\fR is set, the results of the last +fit will be written to the log automatically. To write any one of the +fits explicity, use the 'w' keystroke. + +The \fIrvxcor\fR task also contains three submodes discussed in detail below. +Briefly, the 'f' keystroke will put the user in the "fourier mode", +where he can examine the Fourier transform of the spectra in various +ways and change/examine the filtering parameters. The 'o' and 't' +keystrokes let the user examine and fit the continuum for the object +and template spectra, respectively, using the \fBicfit\fR commands. +Upon exiting the continuum fitting the spectra are continuum subtracted +and a new correlation is computed. Finally the 's' keystroke will put +the user in "spectrum mode", in which he may graphically select the +region to be correlated, compute an approximate shift using the cursor, +or simply examine the two spectra in a variety of ways. All of these +submodes are exited with the 'q' keystroke, after which the correlation +will be redone, if necessary, and the ccf plot redrawn. + +To exit the task, the user simply types a 'q' keystroke. Results will be saved +to the logfile automatically if one was specified, otherwise the user will +be asked if he wants to save the results, and if so queried for a file name +before exiting if no \fIoutput\fR file was defined. + +(References: Tonry, J. and Davis, M. 1979 \fIAstron. J.\fR \fB84,\fR 1511, +and Wyatt, W.F. 1985 in \fIIAU Coll. No 88, Stellar Radial Velocities\fR, +p 123). + +.ce +CURSOR KEYS AND COLON COMMANDS + +.nf +? Print list of cursor key and colon commands +- Subtract blended component from correlation peak ++ Toggle status line output +a Display the antisymmetric noise component of the correlation +b Fix the background level for the Gaussian fit +c Plot polymarkers of actual CCF points on the plot +d Deblend multiple correlation peak +e Preview the summary plot of the correlation +f Fourier filtering and FFT display mode +g Mark correlation peak lag limits and fit +j Plot the residuals of the fit to the peak +k Plot the ratio of the fit to the peak +l Page the current logfile of results +n Go to next (template --> aperture --> object) +o Fit or refit object spectrum continuum for subtraction +p Go to previous (template --> aperture --> object) +q Quit task +r Redraw +s Examine object/template spectra and display mode +t Fit or refit template spectrum continuum for subtraction +v Print full correlation result in text window +w Write current correlation results to the log file +x Compute correlation +y Mark correlation peak lower limit and fit +z Expand on different correlation peak using full correlation plot + +:next [template|aperture|object] Go to next correlation pair +:parameters List current parameters +:previous [template|aperture|object] Go to previous correlation pair +:results [file] Page results + +Other colon commands set or show parameter values +.fi + +.ih +FOURIER MODE DESCRIPTION +Fourier mode is entered from the main task via the 'f' keystroke. By +default, the user is presented with a split plot of the power spectra of +the object and template spectra (object on top) and the requested filter +overlayed. The X-axis is double-labelled with wavenumbers on the bottom +and frequency on top. The ":log_scale" command can be used to toggle +the log scaling of the Y-axis of the plot, and the ":overlay" command +will toggle whether or not the filter function (if specified) is overlayed +on the plot. By default the entire power spectrum is displayed, but +the ":zoom" command may be used to specify a blowup factor for the +display (e.g. ":zoom 2" will display only the first half of the power +spectrum). Plot scaling parameters are learned for the next invocation +of this mode. + +The plot contents may also be changed through various keystroke commands. +The 'p' keystroke will display the power spectrum (the default), the 'f' +keystroke will display the two FFT's, and the 's' keystroke will display the +unfiltered and filtered spectra vertically offset. The 'b' and 'g' +keystrokes may be used to examine the power spectra and FFT's +respectively \fIbefore\fR filtering. The user can determine the period +trend in the data by placing the cursor at a particular wavenumber/frequency +and hitting the 'i' keystroke (this command will not work on a plot of +the filtered spectra). The 'r' key will redraw whichever plot is currently +selected and a 'q' will return the user to the main task mode. + +Colon commands are also used to specify or examine the filtering parameters +by simply typing a ':' followed by the parameter name found in +the \fIfilterpars\fR pset. The user still has full access to the colon +commands in the main task mode. + +.ce +CURSOR KEYS AND COLON COMMANDS + +.nf +? Print list of cursor key and colon commands +b Display power spectra before filtering +f Enter Fourier mode +g Display Fourier transforms before filtering +i Print period trend information +o Display filtered and unfiltered object spectrum +p Display power spectra after filtering +q Quit +r Redraw +s Display spectra +t Display filtered and unfiltered template spectrum +x Return to correlation mode + +:log_scale [yes|no] Set log scaling on Y axis +:overlay [yes|no] Overlay filter function +:parameters List current parameter values +:zoom [factor] Zoom x region + +Other colon commands set or show parameter values +.fi + +.ih +CONTINUUM MODE DESCRIPTION +Automatic continuum subtraction is controlled by the \fIcontinpars\fR +pset. These may be reset from the main +correlation function mode. To interactively fit and modify the continuum +fitting parameters the 'o' and 't' keys are used. This enters +the ICFIT package which is described elsewhere. Exiting the fitting, +with 'q', causes a recomputation of the correlation function and peak +fit. To view the flattened spectra use the spectrum review mode +entered with the 's' key. Fitting parameters changed while doing the +interactive continuum fitting are learned. + +.ce +CURSOR KEYS AND COLON COMMANDS + +See \fBicfit\fR. + +.ih +SPECTRUM MODE DESCRIPTION +Spectrum mode is entered from the main task via the 's' keystroke. +The user may select plots of the original input spectra 'i', the +continuum subtracted spectra 'n', and the filtered and unfilter spectra 'f'. +In addition, a sample region for the correlation is +marked on the bottom of the plots. To select a new sample region, use the 's' +keystroke to select the endpoints of the region. It may be selected +explicity by using the ":sample" command. The region will be checked to +see if it lies within the range of the spectrum. The 'd' keystroke may be +used to print the difference in pixels (and/or velocity) between two points +on the spectrum. This is useful for getting an approximate shift. +The 'w' keystroke or ":/" commands will invoke the standard +GTOOLS windowing commands. +To return to the correlation simply type 'q'. + +(NOTE: More functionality is planned for this mode) + +.ce +CURSOR KEYS AND COLON COMMANDS + +.nf +? Print list of cursor key and colon commands +d Print velocity difference between two cursor positions +f Enter Fourier mode +i Display original input spectra +n Display continuum subtracted spectra +q Quit +r Redraw +s Enter Spectrum mode +w Window graphs with GTOOLS commands +x Return to correlation mode + +:sample [list] List of sample regions +.fi + +.ih +OUTPUT FILES +If the \fIoutput\fR parameter is set, two files will be created; one with +a ".gki" suffix containing metacode output of a summary plot, and one with +text output in the standard IRAF 'list' format containing either verbose or +non-verbose output +having a ".txt" suffix. If a write operation is performed and no output file +is specified, the user will be queried for a file name and the files will +be created. Text file output may be have selected columns extracted +using the iraf \fIfields\fR task (where string valued fields will have +blank spaces replaced with an underscore), and specific metacode plots may +be extracted or displayed with the iraf \fIgkiextract\fR and/or +\fIstdgraph\fR/\fIgkimosaic\fR tasks. +.ls METACODE FILES +For each correlation fit recorded a metacode plot will be drawn to the file +named by the \fIoutput\fR parameter with the ".gki" extension. This plot +will have a plot of the flattened object spectrum on top, with any selected +regions for the correlation marked. The bottom of the plot will be similar +to the standard correlation plot, but text will be overlaid showing the fitted +peak shift, width and computed velocities. + +For a blended peak, the plot will be the same with the exception that each of +the peak components will be labelled with the computed velocity, and the +text labelling will be suppressed. +.le +.ls TEXT FILES +For each correlation fit recorded a text entry will be written to the file +named by the \fIoutput\fR parameter with the ".txt" extension. Regardless +of whether the file contains verbose output, the file header will have comment +lines (beginning with a "#" in column 1) identifying each template used +with a letter code, followed by a description of the image name, template +source name, velocity dispersion (which will be the same for the object +spectra, and specified velocity. A similar comment will be written with +a unique ID whenever a new template image is read into the task interactively. +Similar comments will also be written to identify error codes, abbreviations +used, column headings, and the region used in the correlation. +.ls NON-VERBOSE OUTPUT +(NOTE: Details about field width and such will be worked out later on...) + +Non-verbose output will contain the object image name, object source name +(usually the star name), heliocentric Julian data, aperture number, +a code field identifying whether the data were +filtered, type of fitting function, and/or continuum subtracted, the pixel +shift (and error), velocity FWHM, observed velocity, heliocentric +velocity, and velocity error, as well as an error code field. + +This output will extend approximately less than 80 characters. +.le +.ls VERBOSE OUTPUT +(NOTE: Details about field width and such will be worked out later on...) + +Verbose text output will contain all of the above fields in the header. +Also written will be the Tonry & Davis "R" value, correlation peak height, +FWHM error, and covariance of the correlation. + +This output will extend approximately less than 160 characters. +.le +.le + +.ih +ALGORITHM DISCUSSIONS +.ih +SUMMARY OF THE BASIC TASK STRUCTURE +In this section we discuss the steps taken in preparing and filtering the +data prior to the correlation computation. We will use pseudocode to describe +this process as it is more detailed than the graphical display shown earlier. + +.nf +begin + # Data Rebinning on input + IF (DC-FLAG flag does not exist in object) + DC-FLAG(object) = -1 + IF (DC-FLAG flag does not exist in template) + DC-FLAG(template) = -1 + IF (DC-FLAG(object) * DC-FLAG(template) < 0) + Print error and go on to next correlation pair + ELSE { + IF (DC-FLAG exists in template header && DC-FLAG >= 0) + rebin data to log-linear dispersion + IF (DC-FLAG exists in object header && DC-FLAG >= 0) + rebin to log-linear using template wpc and npts values + } + + # Continuum normaliztion and data preparation + IF (continuum == "object" || continuum == "both") + fit and subtract the object continuum + IF (continuum == "template" || continuum == "both") + fit and subtract the template continuum + FOR (object and template spectrum) { + zero non-overlapping points + zero points outside sample region + subtract the bias + apodize remaining data + center in FFT array of length 2^N + normalize data by the number of FFT points + } + + # Do the Fourier filtering + compute the FFT of both object and template + IF (filter == "object" || filter == "both") + multiply specified filter by object FFT + IF (filter == "template" || filter == "both") + multiply specified filter by template FFT + + calculate the cross correlation + + # Get interactive use set up + display the ccf to the screen + select max peak in ccf + determine fit endpoints from "height" (and "nfit"/"threshold") params + Fit the selected peak + IF (sufficient header information) + compute heliocentric velocity from pixel shift + ELSE + compute only a relative velocity from pixel shift + print results to the status line + + # Process the interactive cursor commands + REPEAT { + # A few example commands + SWITCH (cursor command) { + : + CASE 'f': + enter Fourier mode + : + CASE 'o': + enter ICFIT for object spectrum continuum removal + : + CASE 's': + enter Spectrum mode + : + CASE 't': + enter ICFIT for template spectrum continuum removal + } + } +end +.fi +.ih +PEAK FITTING ALGORITHM +Determining the center of the cross correlation peak is the key step in +measuring a relative shift or velocity between the object and template. +The width of the correlation peak is also of interest for measuring +a line broadening between the two samples. Since people have different +preferences and prejudices about these important measurement a variety +of methods with a range of parameters is provided. + +In all cases one must specify the fitting function and a sample width; +i.e. the range of points about the correlation peak to be used in the +measurement. Note that the width defines where the fitting weights +vanish and should be something like the full width. For the CENTER1D +algorithm the maximum weights are at the half width points while for the +other methods greater weight is given to data nearer the center. + +The width may be specified in three ways. The first is as an actual +width in pixels. This is the most straightforward and is independent +of quirks in the actual shape of the peak. The second way is to find +where the correlation function crosses a specified height or level. +The height may be specified in normalized correlation units or as a +fraction of the peak height. The former is equivalent to the +interactive 'y' key setting while the latter may be used to select some +"flux" point. A value of 0.5 in the latter would be approximately the +full widht at half intensity point except that the true zero or base of +the peak is somewhat uncertain and one needs to keep in mind that the +weights go to zero at this point. Note that a level may be negative. +In this method the actual width may go to zero or include the entire +data range if the level fall above the peak or below the minimum of the +correlation. The minimum and maximum width parameters are applied to +constrain the fitting region. The last method is to interactively mark +the fitting region with the 'g' key. A note will be made in the logfile +if an inflection of the peak is found within the sample range, indicating +a possible second peak or binary component. + +There are four methods for determining the correlation peak position. +The CENTER1D algorithm has been heavily used in IRAF and is quite +stable and reliable. It is independent of a particular model for the +shape of the peak or the background determination and is based on +bisecting the integral. It uses antisymmetric weights with maxima +at points half way between the estimated center and the fitting +region endpoint. A parabola fit is also independent of background +determinations and also does not determine a width. It is included +because it is a common method of peak centering. + +The gaussian and lorentzian function fits are model dependent and +determine a center, width, and peak value. The background may also +be determined simultaneously but this extra degree of freedom +for a function which is not strictly gaussian or lorentzian may +produce results which are sensitive to details of the shape of the +correlation function. The widths reported are the full width at +half maximum from the fits. + +The parabola, gaussian, and lorentzian methods use weights which +vary continuously from 1 at the estimated center to zero at the +endpoints of the fitting region. The functional form of the +weights is a power law with specified exponent. A value of zero +for the exponent produces uniform weights. However, this is +discontinuous at the endpoints and so is very sensitive to the data +window. A value of one (the default) produces linearly decreasing weights. + +All these methods produce centers which depend on the actual +data points and weights used. Thus, it is important to iterate +using the last determined center as the center of the data window +with continuous weights in order to find a self-consistent center. +The methods are iterated until the center does not change by more +than 0.01 pixels or a maximum of 100 iterations is reached. + +Errors in the pixel shift are computed from the center parameter of the fitting +function. Velocity errors are computed based on the fitted peak height and +the antisymmetric noise as described in the Tonry & Davis paper (1979, +\fIAstron. J.\fR \fB84,\fR 1511). Dispersion/pixel-width errors are computed +similarly. + +The initial peak fit will be the maximum of the ccf. This will be the only +peak fit in non-interactive mode but a confidence level will be entered in +the logfile. In interactive mode, the user may select a different peak with +the 'z' keystroke, and the maximum peak within the specified \fIwindow\fR +(centered on the cursor) will be fit. The user has full control in interactive +mode over the points used in the fit. Once the endpoints of the peak have +been selected, the actual data points are shown with '+' signs on the ccf, +the fitted curve drawn, and a horizontal bar showing the location of the +FWHM calculation is displayed. The status line will show a summary of the +fit, and the user may type the 'v' keystroke for a more detailed description +of the fit and correlation. + +.ih +EXAMPLES +.nf + 1. Cross correlate a list of 1-dimensional object spectra against + three 1-dimensional template spectra, saving results automatically + and not continuum subtracting or filtering the data: + + rv> rvxcor.interactive = no # Do it in batch mode + rv> rvxcor obj* temp1,temp2,temp3 autowrite+ continuum="no" + >>> filter="no" output="results" + + 2. Compute a velocity for a list of apertures in a 2-dimensional + multispec format object image, using only one aperture of a multispec + image as a template: + + rv> rvxcor.interactive = no # Do it in batch mode + rv> rvxcor object.ms temp.ms[*,35:35] apertures="1-7,10,12-35" + + 3. Compute a velocity by fitting a fixed number of points on the peak, + using uniform weighting: + + rv> rvxcor obj temp width=8 weights=0. + + 4. Compute a velocity by fitting a Gaussian to the points on the ccf + peak above the 0.1 correlation level. Constrain the number of points + to be less than 15, and linearly decrease the weights: + + rv> rvxcor obj temp func="gaussian" width=INDEF height=0.1 + >>> maxwidth=15 weights=1. + + 5. Compute a velocity by fitting a Lorentzian to the peak, from the + peak maximum to it's half power point: + + rv> rvxcor obj temp func-"lorentz" width=INDEF height=0.5 peak+ + >>> maxwidth=15 weights=1. + + 6. Process a 1-dimensional object against a 1-dimensional template + interactively, examining the FFT, and input spectra to define a sample + region for the correlation: + + rv> rvxcor obj temp inter+ continuum="both" autowrite- output="" + Screen is cleared and ccf peak with fit displayed + + ... to refit peak, move cursor to left side of peak and type 'g' + ... move cursor to right side of peak and hit any key + + New fit is drawn and results displayed to the status line + + ... type the 'v' key for a detailed description of the correlation + + Graphics are suspended and the text screen shows various + parameters of the correlation and fit. + + ... type 'q' to get back to graphics mode + + ... to examine the FFT's of the spectra, type the 'f' keystroke. + + The screen is cleared and a split plot of the two power spectra + after filtyering is drawn with the requested filter overlayed. + ... type the 'f' keystroke + The screen is cleared and the absolute value of the two FFT's + after filtering is plotted, again with the filter overlayed. + ... type ":overlay no", followed by a 'g' keystroke + The spectra are redrawn prior to filtering, with no filter over- + lay + ... type 'q' to return to correlation mode + + The screen is redrawn with the ccf plot and peak fit + + ... type 's' to enter spectrum mode + + The screen is cleared and the the input spectra displayed + ... type 's' to mark the endpoints of a sample region for correl- + ... ation. Then type 'q' to quit this mode + + A new correlation is computed and the peak refit automatically + + ... type 'q' to quit the task, satisfied with the results + The user is asked whether he wants to save results + ... type 'y' or to save results + The user is prompted for an output file name since one wasn't + specified in the parameter set + ... type in a file name + + The task exits. +.fi + +.ih +TIME REQUIREMENTS +To be determined + +.ih +SEE ALSO +continpars, filterpars, observatory, rvkeywords, center1d +.bp +.endhelp -- cgit