diff options
Diffstat (limited to 'noao/rv/doc')
| -rw-r--r-- | noao/rv/doc/continpars.hlp | 129 | ||||
| -rw-r--r-- | noao/rv/doc/filtpars.hlp | 167 | ||||
| -rw-r--r-- | noao/rv/doc/fxcor.hlp | 1143 | ||||
| -rw-r--r-- | noao/rv/doc/keywpars.hlp | 94 | ||||
| -rw-r--r-- | noao/rv/doc/rv.spc | 918 | ||||
| -rw-r--r-- | noao/rv/doc/rvidlines.hlp | 530 | ||||
| -rw-r--r-- | noao/rv/doc/rvpackage.spc | 948 | ||||
| -rw-r--r-- | noao/rv/doc/rvplan.ms | 91 | ||||
| -rw-r--r-- | noao/rv/doc/rvreidlines.hlp | 405 |
9 files changed, 4425 insertions, 0 deletions
diff --git a/noao/rv/doc/continpars.hlp b/noao/rv/doc/continpars.hlp new file mode 100644 index 00000000..17f9badf --- /dev/null +++ b/noao/rv/doc/continpars.hlp @@ -0,0 +1,129 @@ +.help continpars Jan92 noao.rv +.ih +NAME +continpars -- edit the continuum subtraction parameters +.ih +USAGE +continpars +.ih +PARAMETERS +.ls c_sample = "*" +Lines or columns to be used in the fits. The default value ("*") selects +all pixels. Type \fIhelp ranges\fR for a complete description of the +syntax. +.le +.ls c_function = "spline3" +Continuum function to be fit to the image lines or columns. The functions are +"legendre" (Legendre polynomial), "chebyshev" (Chebyshev polynomial), +"spline1" (linear spline), and "spline3" (cubic spline). The functions +may be abbreviated. +.le +.ls c_interactive = "no" +Interactively fit the continuum? If set to yes, each spectrum will be fit +interactively as they are read into the task if the \fIfxcor.continuum\fR +parameter requires it. The \fIfxcor\fR keystroke commands 'o' and 't' will +automatically fit the continuum interactively. +.le +.ls naverage = 1 +Number of sample points to combined to create a fitting point. +A positive value specifies an average and a negative value specifies +a median. +.le +.ls order = 1 +The order of the polynomials or the number of spline pieces. +.le +.ls replace = no +Replace rejected data points with continuum fit points prior to the +subtraction? If set to yes, points lying outside the \fIlow_reject\fR or +\fIhigh_reject\fR limits are replaced by the fit values prior to the +continuum subtraction. This can be useful in removing emission features +or cosmic ray events, but great care must be taken in setting other parameters +in order to get satisfactory results. Adjusting the \fIgrow\fR or +\fIaverage\fR parameters, and using a low order function usually provide +a good result. +.le +.ls low_reject = 2., high_reject = 2. +Rejection limits below and above the fit in units of the residual sigma. +.le +.ls niterate = 1 +Number of rejection iterations. +.le +.ls grow = 1. +When a pixel is rejected, pixels within this distance of the rejected pixel +are also rejected. +.le + +.ih +DESCRIPTION +The \fIcontinpars\fR pset is used to control the continuum subtraction from +the data. When the \fIfxcor\fR task is run in a batch mode, +the parameters are used to +automatically process the data without intervention from the user. In an +interactive session, the user may experiment with different parameter values by +changing them with the allowed colon commands. + +Continuum subtraction is done exactly as with the \fIonedspec.continuum\fR +task. (Details of the operation are described in the \fIcontinuum\fR +documentation.) The fit to the spectra is subtracted from the data, thus +producing a continuum subtracted spectrum suitable for input to the correlation +routines. + +Users who require the full ability of the \fIonedspec.continuum\fR task to +supply another form of output spectrum, such as the ratio of the fit, or +who wish to make use of the "clean" option, should use that task and disable +continuum subtraction in the \fIrv\fR package tasks. More functionality is +planned for this pset in the future. + +.ih +TASK COLON COMMANDS +The values of the \fIcontinpars\fR pset may be changed, displayed, or updated +from within tasks that use them by means of various colon commands. Simply +typing the parameter name will have the default action of printing the current +value of that parameter. +.ls :unlearn continpars +Reset the continpars pset parameters with their default values. +The argument "continpars" must be present or else the command will default +to the \fIfxcor\fR task command. +.le +.ls :update continpars +Update the continpars pset parameters with the current values. +The argument "continpars" must be present or else the command will default +to the \fIfxcor\fR task command. +.le +.ls :show continpars +Show the current values of the continpars pset parameters. +The argument "continpars" must be present or else the command will default +to the \fIfxcor\fR task command. +.le + +The following parameters will be displayed if it's name it typed, and a new +value accepted if an argument is given. + +.nf +:c_sample [range_string] +:naverage [int_value] +:c_function [spline3|legendre|chebyshev|spline1] +:order [int_value] +:low_reject [int_value] +:high_reject [int_value] +:niterate [int_value] +:grow [int_value] +.fi + +.ih +EXAMPLES +1. List the continuum parameters. + +.nf + rv> lpar continpars +.fi + +2. Edit the continuum parameters + +.nf + rv> continpars +.fi +.ih +SEE ALSO +fxcor, onedspec.continuum, icfit, sfit +.endhelp diff --git a/noao/rv/doc/filtpars.hlp b/noao/rv/doc/filtpars.hlp new file mode 100644 index 00000000..596970ee --- /dev/null +++ b/noao/rv/doc/filtpars.hlp @@ -0,0 +1,167 @@ +.help filtpars Jan91 noao.rv +.ih +NAME +filtpars -- edit the filter function parameters +.ih +USAGE +filtpars +.ih +PARAMETERS +.ls f_type = "ramp" +Type of filter to be used. Possible choices are +.ls ramp +A ramp function which begins to rise at the \fIcuton\fR wavenumber and +reaches full value (i.e. passes the full value of the component) at the +\fIfullon\fR wavenumber. It begin to decline at the \fIcutoff\fR wavenumber +and returns to zero at the \fIfulloff\fR wavenumber. +.le +.ls Hanning +A Hanning function is used to attenuate the fourier components over the +range specified by the \fIcuton\fR and \fIcutoff\fR parameters. +.le +.ls Welch +A Welch function is used to attenuate the fourier components over the range +specified by the \fIcuton\fR and \fIcutoff\fR parameters. +.le +.ls Square +A standard step function which is zero outside the \fIcuton\fR and +\fIcutoff\fR component numbers and one within those numbers. +.le +.le +.ls cuton = 0 +The fourier wavenumber at which the filter begins to pass the filtered fft +component. +.le +.ls cutoff = 0 +The fourier wavenumber at which the filter ceases to pass fft components. +.le +.ls fullon = 0 +Used only for a 'ramp' filter. The fourier wavenumber at which the filter +reaches full value and passes all of the data. +.le +.ls fulloff = 0 +Used only for a 'ramp' filter. The fourier wavenumber at which the filter +reaches zero value and passes none of the data. +.le +.ih +DESCRIPTION +The filtering parameters control the type of filter to be used +on the Fourier transformed data as well as the range in wavenumbers over +which it will operate. Filtering of the data may be necessary to remove +high frequency noise or low-frequency tends not removed by continuum +subtraction. If the filtering is enabled, then once the data have been +transformed, a bandpass filter of the type chosen by the +\fIf_type\fR parameter is applied to the Fourier components of the +spectra. Wavenumbers lower than that specified by the \fIcuton\fR parameter +are set to zero and wavenumbers up to that specified by the \fIcutoff\fR +parameter (or the \fIfulloff\fR parameter in the case of a 'ramp' filter) +are attenuated or passed in full according to the filter chosen. +Since the data are assumed to be linearized in log-wavelength space, applying +a filter to the data in Fourier space introduces no phase shift and has +the same effect as smoothing the data in real space. The data are centered +and zero padded in an array of length 2**N such that the number of elements +is greater than or equal to the number of actual data points. This array in +then Fourier transformed, and the resulting fft is then filtered prior +to correlation. + +Filtering is enabled by turning on the \fIfxcor.filter\fR parameter and setting +it to something other than "none". Filtering may be done on only one of the +two spectra or both prior to correlation. + +The filter choices behave as follows: +.ls Square Filter +The fourier components at wavenumbers between the \fIcuton\fR and \fIcutoff\fR +wavenumbers are passed without change. Those wavenumbers outside this region +are set to zero. +.le +.ls Ramp Filter +Fourier components below the \fIcuton\fR and above the \fIfulloff\fR +wavenumbers are set to zero. +At the \fIcuton\fR wavenumber the filter function +begins to rise until the \fIfullon\fR wavenumber is reached. Data in this +region is weighted by the slope of the filter until at the \fIfullon\fR +wavenumber data are passed through without change. Similarly, the filter +begins to fall at the \fIcutoff\fR wavenumber until it completely blocks +(i.e. zeros) the fourier components at the \fIfulloff\fR wavenumber. +.le +.ls Welch Filter +Fourier components below the \fIcuton\fR and above the \fIcutoff\fR +wavenumbers are set to zero. Components between these regions are weighted +according to the equation for a Welch window. Namely, +.nf + + 2 + w(j) = 1. - [ (j - 1/2(N-1)) / (1/2(N+1)) ] + + where j = (wavenumber - cuton_wavenumber) + N = (cutoff - cuton) + 1 +.fi +.le +.ls Hanning Filter +Fourier components below the \fIcuton\fR and above the \fIcutoff\fR +wavenumbers are set to zero. Components between these regions are weighted +according to the equation for a Hanning window. Namely, +.nf + + w(j) = 1/2 [ 1. - cos( (TWOPI*j) / (N-1) ) ] + + where j = (wavenumber - cuton_wavenumber) + N = (cutoff - cuton) + 1 +.fi +.le + +.ih +TASK COLON COMMANDS +The values of the \fIfiltpars\fR pset may be changed, displayed, or updated +from within the Fourier mode of the \fIfxcor\fR task. Simply +typing the parameter name will have the default action of printing the current +value of that parameter. An optional value may be added to change the named +parameter. +.ls :update filtpars +Update the pset with the current values of the filter parameters. +The argument "filtpars" must be present or else the command will default +to the task parameters. +.le +.ls :unlearn filtpars +Reset the parameter values to their defaults. +The argument "filtpars" must be present or else the command will default +to the task parameters. +.le +.ls :show filtpars +Clear the screen and display all values in the filtpars pset. +The argument "filtpars" must be present or else the command will default +to the task default. +.le +.ls :filttype [ramp|welch|hanning|square|none] +Set or show the current value of the filter type to use +.le +.ls :cuton [int_value] +Set or show the current value of the cuton fourier component +.le +.ls :cutoff [int_value] +Set or show the current value of the cutoff fourier component +.le +.ls :fullon [int_value] +Set or show the current value of the fullon fourier component +.le +.ls :fulloff [int_value] +Set or show the current value of the fulloff fourier component +.le + +.ih +EXAMPLES +1. List the filtering parameters. + +.nf + rv> lpar filtpars +.fi + +2. Edit the filtering parameters + +.nf + rv> filtpars +.fi +.ih +SEE ALSO +fxcor +.endhelp diff --git a/noao/rv/doc/fxcor.hlp b/noao/rv/doc/fxcor.hlp new file mode 100644 index 00000000..7f253a3b --- /dev/null +++ b/noao/rv/doc/fxcor.hlp @@ -0,0 +1,1143 @@ +.help fxcor Mar93 noao.rv +.ih +NAME +fxcor -- compute radial velocities via Fourier cross correlation +.ih +USAGE +fxcor 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. This list need not match the object list. All pairs +between the two lists will be correlated. +.le +.ls apertures = "*" +List of apertures to be correlated in echelle and multispec format spectra. +This parameter is used for \fIboth\fR the object and reference spectra if both +spectra are two dimensional, otherwise the aperture list applies to the object +only if the template is one-dimensional. Individual apertures from a +two-dimensional template may be +extracted to 1-D using the \fIonedspec.scopy\fR task, and these new images may +then be used in the template list as separate images. (See the examples for +how this may be done). The default of '*' means to process all of the +apertures in the spectrum. Note that the sample regions named by the +\fIosample\fR and \fIrsample\fR parameters will apply to all apertures. +.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), "both" for +continuum flattening both object and template spectra, or "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), "both" for +fourier filtering both object and template spectra, or "none" for +filtering neither spectrum. The \fIfiltpars\fR pset holds the parameters +for the filtering (filter type and width). +.le +.ls rebin = "smallest" +Rebin to which spectrum dispersion? If the input dispersions are not equal +prior to the correlation, +one of the two spectra in the pair will be rebinned according to the +\fIrebin\fR parameter. Possible values are "smallest" (to rebin to the +smaller of the two values), "largest" (to rebin to the larger of the two +values), "object" (to force the template to always be rebinned to the object +dispersion), and "template" (to force the object to always be rebinned to the +template dispersion). Input spectra \fImust be\fR linearly corrected. +Support for non-linear input dispersions is not included in this release. +.le +.ls pixcorr = "no" +Do a pixel-only correlation, ignoring any dispersion information? If this +parameter is set to \fIyes\fR, then regardless of whether dispersion +information is present in the image headers, the correlation will be done +without rebinning the data to a log-linear dispersion. This option is useful +when pixel shifts, not velocities, are the desired output. +.le +.ls osample = "*" +Sample regions of the object 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 angstroms. +This string value will be updated in an interactive session as sample +regions are re-selected in spectrum mode. The default, '*', is the entire +spectrum. The region is specified as a starting value, a '-', and an ending +value. If the specified range is out of bounds, the endpoints will be +modified to the nearest boundary, or else the entire spectrum will be +correlated if the whole range is out of bounds. +.le +.ls rsample = "*" +Sample regions of the template 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 angstroms. +This string value will be updated in an interactive session as sample +regions are re-selected in spectrum mode. The default, '*', is the entire +spectrum. The region is specified as a starting value, a '-', and an ending +value. If the specified range is out of bounds, the endpoints will be +modified to the nearest boundary, or else the entire spectrum will be +correlated if the whole range is out of bounds. +.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", "center1d", +or "sinc". If a center1d fit is selected, then only the center is determined. +A "sinc" function uses a sinc interpolator to find the maximum of the +peak by interpolating the points selectes. The FWHM calculation in this +case is computed empirically by finding the half power point according +to the computed peak height and the \fIbackground\fR level. No FWHM +will be computed of the background is not set. The function fitting options +all compute the FWHM from the fitted coefficients of the function. +.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. +.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 \fIpeak\fR 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 = 21. +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 + + weight = 1 - (distance / (width/2)) ** \fIweights\fR + +.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 = INDEF +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 +pixels wide if no dispersion information is present in the image header. +If dispersion information is present, \fIwindow\fR is specified in Km/s. +A value of INDEF results in a default window size of 20 pixels. If the +window proves to be too small for the number of points to be fit selected +with the \fIwidth\fR, \fIheight\fR, and/or \fIpeak\fR parameters, a message +will be written to the ".log" file and/or screen explaining that points +outside the window bounds were used in the fit. The user may wish to +review this fit or increase the window size. +.le +.ls wincenter = INDEF +Center of the peak search window specified in pixel lags if no dispersion +information is present, or specified in Km/s if dispersion information is +present. If set to the default INDEF, the maximum peak in the cross-correlation +function will be fit by default. If set to other than INDEF, the maximum peak +within a window centered on \fIwincenter\fR and two times \fIwindow\fR +lags wide will be used. Note that this parameter can be used to constrain +the velocities computed to a certain range in non-interactive mode. +.le + +.ce +OUTPUT PARAMETERS +.ls output = "" +Name of the 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. Tabular text output will have a ".txt" +suffix appended to the \fIoutput\fR name, a verbose description of each fit +will have ".log" suffix appended and will be written only if the \fIverbose\fR +parameter is set, and the graphics metacode file will be appended with +a ".gki" suffix. (NOTE: Image names will be truncated to 10 characters in the +output file because of space considerations. Verbose output logs will +truncate the image names to 24 characters. Object names are similarly +truncated to 15 characters. If a relative velocity is calculated with a +redshift of more than 0.2, output will be redshift z values rather than +velocities in Km/s.) +.le +.ls verbose = "long" +Set level of verbosity and types of files to create. The \fIverbose\fR +parameter is an enumerated string whose values determine the number and type +of output files created. Up to three files are created: the ".txt", ".log", +and ".gki" files (see the description for the \fIoutput\fR parameter). +Possible values for \fIverbose\fR and the files created are as follows: +.nf + + Value: Files Created: + + short (an 80-char .txt file and a .gki file) + long (a 125-char .txt file, a .log file, a .gki file) + nolog (a 125-char .txt file and a .gki file) + nogki (a 125-char .txt file and a .log file) + txtonly (a 125-char .txt file) + stxtonly (an 80-char .txt file) + +.fi +The \fIfields\fR task +may be used to strip out selected columns from the .txt files. The 125-char +.txt output +may be printed without wrapping the lines either in landscape mode for +a laser printer, or on a 132 column lineprinter. +.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 \fIkeywpars.vobs\fR and \fIkeywpars.vhelio\fR keywords +respectively. Two-dimensional spectra cannot be updated. Additional keywords +defined in the \fIkeywpars\fR pset will also be updated. +.le +.ls graphics = "stdgraph" +Output graphics device. +.le + +.ce +CONTROL PARAMETERS +.ls interactive = "yes" +Process the spectra interactively? +.le +.ls autowrite = "yes" +Automatically record the last fit to the log file when moving to the +next/previous spectrum or quitting? 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 autodraw = "yes" +Automatically redraw the new fit after it changes. If set to the default +"yes" then the old fit is erased and a new one computed and drawn after +the 'g', 'y', 'd', or 'b' keystrokes. If set to "no", then old fits are not +erased and the user must redraw the screen with an 'r' keystroke. +.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 observatory = "kpno" +The location of the observations, as defined by the \fInoao.observatory\fR +task. The image header keyword OBSERVAT will override this parameter, thus +allowing for images which were taken at another observatory to be properly +corrected. These values are used in the heliocentric correction routines. +.le +.ls continpars = "" +The continuum subtraction parameters as described in the \fIcontinpars\fR +named pset. +.le +.ls filtpars = "" +The parameter set defining the parameters to be used in filtering the +data prior to the correlation. +.le +.ls keywpars = "" +The image header keyword translation table as described in +the \fIkeywpars\fR named pset. +.le + +.ce +RV PACKAGE PARAMETERS +.ls dispaxis = 1, nsum = 1 +Parameters for defining vectors in 2D images. The +dispersion axis is 1 for line vectors and 2 for column vectors. +A DISPAXIS parameter in the image header has precedence over the +\fIdispaxis\fR parameter. +.le +.ls z_threshold = 0.2 +Redshift value at which the output logs switch from printing velocities in +units of Km/s to redshift z values. +.le +.ls tolerance = 1.0e-5 +Fitting tolerance for Least Squares fitting. +.le +.ls maxiters = 100 +Maximum number of iterations for Least Squares fitting or any other iterative +algorithm. +.le +.ls interp = "poly5" +Interpolator used when rebinning the data to a log-linear dispersion. See +the section on interpolation for more information. Possible choices are +"nearest", "linear", "poly3", "poly5", "spline3", and "sinc". +.le +.ls line_color = 1 +Color index of overlay plotting vectors. This parameter has no effect on +devices which do not support color vectors. +.le +.ls text_color = 1 +Color index of plot text annotation. This parameter has no effect on +devices which do not support color vectors. +.le +.ls observatory = "observatory" +Observatory at which the spectra were obtained if not specified in the +image header by the keyword OBSERVAT. This parameter is used by several +tasks in the package through parameter redirection so this parameter may be +used to affect all these tasks at the same time. 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 \fBobservatory.observatory\fR, or "obspars" to select the +current parameters set in the \fBobservatory\fR task. See help for +\fBobservatory\fR for additional information. +.le + +.ih +DESCRIPTION +\fIFxcor\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 in the object +spectrum. Two dimensional templates will correlate corresponding apertures. + +If the input spectra are not dispersion corrected (DC-FLAG parameter missing +or less than zero), or the \fIpixcorr\fR parameter is turned on, 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 is produced. +If the image headers contain sufficient information for heliocentric +velocity corrections (see help for \fBkeywpars\fR), the corrections are +computed and possibly recorded in the image header (see below for a full +explanation of the computed velocities). 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 using the interpolant set by the package +parameter \fIinterp\fR (See the section on interpolation for details). +At this time only linear input dispersions are supported for rebinning. +The starting and ending wavelength for +both spectra will remain the same, but the dispersion in log space will be +determined from the \fIrebin\fR parameter if the input disersions aren't +equal, or from the spectrum's endpoints and number of pixels if they are +equal. For example, assuming \fIrebin\fR is set to "smallest", if object +one and the template have the same input log dispersion of 0.5e-4 A/pix the +data will not be rebinned. Object two with a wpc of 0.4e-4 A/pix will force +the template to be rebinned to a common wpc of 0.4e-4 A/pix. If the third +object on the list then has a dispersion of 0.3e-4 A/pix, the template will +again be rebinned from the original 0.5e-4 A/pix dispersion to a new 0.3e-4 +A/pix dispersion. If object three and the template are the same star, the +template spectrum will suffer from interpolation errors that should be +considered when analyzing the results. The output .txt file will update +every time the common dispersion is changed. The suggested course of action +is to bin all spectra to the same dispersion, preferably a log-linear one, +prior to executing this package. + +If the \fIcontinuum\fR flag is set to something 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 are zeroed outside the sample +region specified by the \fIosample\fR and \fIrsample\fR parameters, +the ends of each region are apodized, and the bias is then subtracted. +If the \fIfilter\fR flag is set to something other than +"none", the data are Fourier filtered according to the parameters in +the \fIfiltpars\fR pset prior to the correlation computation. + +Once the correlation is computed, the maximum peak within the window +specified by the \fIwincenter\fR and \fIwindow\fR parameters is found and +fit according to the \fIwidth\fR or \fIheight\fR and \fIpeak\fR parameters. +A small, unlabeled plot of the entire cross correlation function (hereafter +CCF) 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 of the +expanded plot is labeled with pixel lag and, if dispersion information is +present, the top axis is labeled with relative velocity. 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 +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, and +the '+' keystroke will toggle the status line output. 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. An +overplot of the subtracted fit (residuals) may be seen with the 'j' +keystroke. + +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, and a new fit will be 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. Certain colon commands from +within the Fourier or Spectrum mode will also cause a new correlation to be +computed when these modes are exited. + +The 'c' keystroke may be used to get a printout of the cursor position in both +lag and relative velocity. The cursor may be positioned in either the +unlabeled CCF plot on the top, or in the zoomed plot on the bottom. This is +useful for judging the FWHM calculation, or estimating the velocity of a +peak without using the 'z' keystroke to zoom and fit. Note that because of +the plotting implementation, the normal cursor mode keystroke \fIshift-C\fR +should not be used as it may return erroneous results depending upon cursor +position. Note also that velocities printed are only approximate relative +velocities, and the user should properly fit a peak or use the ":correction" +command to get a true heliocentric velocity. + +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. See the discussion +below for more deatils on the use of this feature. 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 +or pixel shift. + +To move to the next spectrum in a list (of images or apertures), 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 \fIautowrite\fR is set, the results of the last fit will be +written to the log automatically. To write any one of the fits explicitly, +use the 'w' keystroke. + +The \fIfxcor\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. + +Colon commands may also be used to examine or change parameter values in +any of the \fIfiltpars\fR, \fIcontinpars\fR, or \fIkeywpars\fR +psets. Simply type a ':' followed by the parameter name and an optional +new value. The \fIobservatory\fR parameters may only be changed outside +the task. + +To exit the task, type 'q'. 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. + +If the \fIoutput\fR parameter is set, several files will be created +depending on the value of the \fIverbose\fR parameter (see the parameter +description for details). These include a file with a ".gki" suffix +containing metacode output of a summary plot, a ".txt" suffix file +containing text output in the standard IRAF 'list' format containing either +verbose or non-verbose output, and a third file having a ".log" suffix +containing a verbose description of the correlation and fit, as well as any +warning messages. This contents of the ".log" file is identical to what is +seen with the 'v' keystroke. If the computed relative velocity exceeds the +package parameter \fIz_threshold\fR, the ".txt" file will contain redshift Z +values rather than the default velocities. 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. + +(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). + +.ih +FOURIER MODE DESCRIPTION +Fourier mode is entered from the main task mode 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-labeled with wavenumbers on the bottom of +the screen 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 and content 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) and the 'f' +keystroke will display the two FFT's. 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 mode which called the Fourier +mode (i.e. either the main task mode or the Spectrum mode). The Spectrum +mode may be entered from within Fourier mode via the 's' keystroke. + +Colon commands are also used to specify or examine the filtering parameters +by simply typing a ':' followed by the parameter name found in +the \fIfiltpars\fR pset. + +.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 (see \fIicfit\fR). +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. + +.ih +SPECTRUM MODE DESCRIPTION +Spectrum mode is entered from the main or fourier mode via the 's' +keystroke. The user may select plots of the original input spectra with the +'i' keystroke, or the continuum subtracted spectra with the 'n' keystroke, +If the data have been rebinned to a log scale, they will still be plotted +on a linear wavelength scale for clarity. Pixel data are plotted identically +to how they were read. (NOTE: For rebinned spectra, a slight slope may be +noticed in the 'original' data because of rebinning effects.) +In addition, a sample regions (if selected) for the correlation are marked +on the bottom of both plots. To select a new sample region, use the 's' +keystroke to select the endpoints of the region. An 's' keystroke on the +top plot will select a sample region for the object spectrum, and an 's' on +the bottom plot will select a template sample, using the 'b' keystroke will +select both samples simultaneously. The regions may be selected +explicitly by using the ":osample" and ":rsample" commands, and selected +sample regions may be cleared entirely using the (e.g.) ":osample *" command, +or individual regions may be unselected by putting the cursor within the +region and typing 'u'. See the +parameter description for syntax of the sample ranges. Regions will be +checked and possibly truncated to see if they +lie 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. Fourier mode may be entered via the 'f' keystroke. To +return to the correlation simply type 'q' or 'x'. + +In addition to the above commands, the user may examine or change the +parameters in the \fIcontinpars\fR pset by simply typing a ':' followed +by the parameter name. Changing these values will not cause a new correlation +until an explicit command is given to redo the continuum subtraction. + +(NOTE: More functionality is planned for this mode.) + +.ih +INTERPOLATION +The interpolation type is set by the package parameter \fIinterp\fR. +The available interpolation types are: + +.nf + nearest - nearest neighbor + linear - linear + poly3 - 3rd order polynomial + poly5 - 5th order polynomial + spline3 - cubic spline + sinc - sinc function +.fi + +The default interpolation type is a 5th order polynomial (poly5). + +The choice of interpolation type depends on the type of data, smooth +verses strong, sharp, undersampled features, and the requirements of +the user. The "nearest" and "linear" interpolation are somewhat +crude and simple but they avoid "ringing" near sharp features. The +polynomial interpolations are smoother but have noticible ringing +near sharp features. They are, unlike the sinc function described +below, localized. + +In V2.10 a "sinc" interpolation option is available. This function +has advantages and disadvantages. It is important to realize that +there are disadvantages! Sinc interpolation approximates applying a phase +shift to the fourier transform of the spectrum. Thus, repeated +interpolations do not accumulate errors (or nearly so) and, in particular, +a forward and reverse interpolation will recover the original spectrum +much more closely than other interpolation types. However, for +undersampled, strong features, such as cosmic rays or narrow emission or +absorption lines, the ringing can be more severe than the polynomial +interpolations. The ringing is especially a concern because it extends +a long way from the feature causing the ringing; 30 pixels with the +truncated algorithm used. Note that it is not the truncation of the +interpolation function which is at fault! + +Because of the problems seen with sinc interpolation it should be used with +care. Specifically, if there are no undersampled, narrow features it is a +good choice but when there are such features the contamination of the +spectrum by ringing is much more severe than with other interpolation +types. + +.ih +DEBLENDING +When entering the deblending function, two cursor settings define the +local background, which may be sloping, and the region to be fit. Note +that both the x and y of the cursor position are used. The lines to be +fit are then entered either with the cursor ('m'), or by typing the +shifts ('t'). The latter is useful if the shifts of the +lines are known accurately and if fits restricting the absolute or +relative positions of the lines will be used (i.e. 'a', 'b', 'd', +'e'). A maximum of four lines may be fit. If fewer lines are desired, +exit the marking step with 'q'. + +There are six types of fits which may be selected. This covers all +combinations of fixing the absolute positions, the relative positions, +the sigmas to be the same, and letting all parameters be determined. +In all cases the peak intensities are also determined for each line. +The options are given below with the appropriate key and mnemonic. + +.nf + a=0p1s Fit intensities and one sigma with positions fixed + b=1p1s Fit intensities, one position, and one sigma with + separations fixed + c=np1s Fit intensities, positions, and one sigma + d=0pns Fit intensities and sigmas with positions fixed + e=1pns Fit intensities, one position, and sigmas with + separations fixed + f=npns Fit intensities, positions, and sigmas +.fi + +This list may also be printed with the '?' key when in the deblending +function. + +As noted above, sometimes the absolute or relative shifts of the +lines are known a priori and this information may be entered by typing +the shifts explicitly using the 't' option during marking. In +this case, one should not use the 'c' or 'f' fitting options since they +will adjust the line positions to improve the fit. Options 'a' and 'd' +will not change the lines positions and fit for one or more sigmas. +Options 'b' and 'e' will maintain the relative positions of the lines +but allow an other than expected shift. + +After the fit, the modeled lines are overplotted. The line center, +flux, equivalent width, and full width half maximum are printed on the +status line for the first line. The values for the other lines and +the RMS of the fit may be examined by scrolling the status line +using the '+', '-', and 'r' keys. Velocity information is obtained by +typing the 'v' keystroke. To continue enter 'q'. + +The fitting may be repeated with different options until exiting with 'q'. + +The fitted model may be subtracted from the data (after exiting the +deblending function) using the '-' (minus) +keystroke to delimit the region for which the subtraction is to +be performed. This allows you to fit a portion of a peak which may +be contaminated by a blend and then subtract away the entire peak +to examine the remaining components. + +The fitting uses an interactive algorithm based on the Levenberg-Marquardt +method. The iterations attempt to improve the fit by varying the parameters +along the gradient of improvement in the chi square. This method requires +that the initial values for the parameters be close enough that the +gradient leads to the correct solution rather than an incorrect local +minimum in the chi square. The initial values are determined as follows: + +.nf + 1. The initial line centers are those specified by the user + either by marking with the cursor or entering the shifts. + 2. The initial peak intensities are the data values at the + given line centers with the marked continuum subtracted. + 3. The initial sigmas are obtained by dividing the width of + the marked fitting region by the number of lines and then + dividing this width by 4. +.fi + +Note that each time a new fitting options is specified the initial parameters +are reset. Thus the results do not depend on the history of previous fits. +However, within each option an iteration of parameters is performed as +described next. + +The iteration is more likely to fail if one initially attempts to fit too +many parameters simultaneously. A constrained approach to the solution +is obtained by iterating starting with a few parameters and then adding +more parameters as the solution approaches the true chi square minimum. +This is done by using the solutions from the more constrained options +as the starting point for the less constrained options. In particular, +the following iterative constraints are used during each option: + +.nf + a: 0p1s + b: 0p1s, 1p1s + c: 0p1s, 1p1s, np1s + d: 0p1s, 0pns + e: 0p1s, 1p1s, 1pns + f: 0p1s, 1p1s, np1s, npns +.fi + +For example, the most general fit, 'f', first fits for only a single sigma +and the peak intensities, then allows the lines to shift but keeping the +relative separations fixed. Next, the positions are allowed to vary +independently but still using a single sigma, and then allows all parameters +to vary. + +To conclude, here are some general comments. The most restrictive 'a' +key will give odd results if the initial positions are not close to the +true centers. The most general 'f' can also lead to incorrect results +by using unphysically different sigmas to make one line very narrow and +another very broad in an attempt to fit very blended lines. The +algorithm works well when the lines are not severely blended and the +shapes of the lines are close to Gaussian. + +.ih +PEAK FITTING/FINDING ALGORITHMS +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 measurements, 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 +(with the exception of "sinc") 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 width 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. + +There are five 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 and sinc +interpolation is also independent of background determinations. The +parabola is included because it is a common method of peak centering. + +The sinc option uses a sinc interpolator together with a maximization +(actually a minimization algorithm) function to determine the peak height +and center. A width will be computed only if a background level has been +set and is determined empirically based on the peak height and background. +Point weighting is not used in this option. + +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 +not computed in this release but are planned for a future release. + +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 +VELOCITY COMPUTATION ALGORITHM +Up to three velocities are computed by the task depending on the completeness +of the images headers and the presence of dispersion information. If only +dispersion information is present, a relative velocity, VREL, and an error +will be computed. If a full header is present (see the \fIkeywpars\fR +help page), an observed and heliocentric velocity (VOBS and VHELIO +respectively) will be computed. + +In short form, here are the equations: +.nf + + ref_rvobs = catalogue_vel_of_template - H(temp) # obs. vel. of temp. + VREL = C * (10 ** (wpc * shift) - 1.) # relative vel. + VOBS = ((1+ref_rvobs/C)*(10**(wpc*shift)-1)) * C # observed vel. + VHELIO = VOBS + H(object) # heliocentric vel. + +.fi +where H() is the heliocentric correction for that observation. The +equation used for the relative velocity is derived from the standard +(1+z), and the VOBS equation reflects that the observed velocty is the +product of (1+z) values for the object and template (this allows for high +redshift templates to be used). The date, time, and position of each +spectrum is found from the image header via the keywords defined in +\fIkeywpars\fR. In the case of the time the task first looks for a +keyword defining the UT mid-point of the observation +(\fIkeywpars.utmiddle\fR). If that is not found any time present in the +header DATE-OBS (\fIkeywpars.date_obs\fR) keyword is used at the UT start +point, if there is no time in the keyword value then the mid-point UT is +computed from the exposure time (\fIkeywpars.exptime\fR) and UT of +observation (\fIkeywpars.ut\fR) keywords. + +The keyword added to the template header (as defined by the +"vhelio" parameter in the \fIkeywpars\fR pset) should be the catalogue velocity +of the template. Since the observation of the template has a slightly +different heliocentric correction, this is subtracted from the template +heliocentric velocity so that the \fIobserved\fR velocity of the template +is used when correcting the relative velocity computed from the shift. +This gives the \fIobserved\fR velocity of the object wrt the template. +Adding the heliocentric correction of the object star then yields the true +heliocentric velocity of the object. + +.bp +.ih +CURSOR KEYS AND COLON COMMANDS SUMMARY + +.ce +CORRELATION MODE COMMANDS +.nf +? Print list of cursor key and colon commands +- Subtract blended component from correlation peak +. Do the continuum subtraction ++ Toggle status line output +a Display the antisymmetric noise component of the correlation +b Fix the background level for the Gaussian fit +c Read out cursor position in pixel lag and velocity +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 +I Interrupt +j Plot the residuals of the fit to the peak +l Page the current logfile of results +m Plot polymarkers of actual CCF points on the plot +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 + +:apertures [range] Set/Show list of apertures to process +:apnum [aperture] Set/Show specific aperture to process +:apodize [fraction] Set/Show fraction of endpts to apodize +:autowrite [y|n] Set/Show autowrite param +:autodraw [y|n] Set/Show autodraw param +:background [background|INDEF] Set/Show background fitting level +:ccftype [image|text] Set/Show type of CCF output +:comment [string] Add a comment to the output logs +:continuum [both|obj|temp|none] Set/Show which spectra to normalize +:correction shift Convert a pixel shift to a velocity +:deltav Print the velocity per pixel dispersion +:disp Print dispersion info +:filter [both|obj|temp|none] Set/Show which spectra to filter +:function [gaussian|lorentzian| Set/Show CCF peak fitting function + center1d|parabola] +:height [height] Set/SHow CCF peak fit height +:imupdate [y|n] Set/Show image update flag +:maxwidth [width] Set/Show min fitting width +:minwidth [width] Set/Show max fitting width +:nbang :Next command without a write +:next [temp|aperture|object] Go to next correlation pair +:objects [list] Set/Show object list +:osample [range] Set/Show object regions to correlate +:output [fname] Set/Show output logfile +:<parameter> [value] Set/Show pset parameter value +:peak [y|n] Set/Show peak height flag +:pbang :Previous command without a write +:previous [temp|aperture|object] Go to previous correlation pair +:printz [y|n] Toggle output of redshift z values +:rebin [small|large|obj|temp] Set/Show the rebin parameter +:results [file] Page results +:rsample [range] Set/Show template regions to correlate +:show List current parameters +:templates [list] Set/Show template list +:tempvel [velocity] Set/Show template velocity +:tnum [temp_code] Move to a specific temp. in the list +:unlearn Unlearn task parameters +:update Update task parameters +:version Show task version number +:verbose [y|n] Set/Show verbose output flag +:wccf Write out the CCF to an image|file +:weights [weight] Set/Show fitting weights +:width [width] Set/Show fitting width about peak +:wincenter [center] Set/Show peak window center +:window [size] Set/Show size of window +:ymin [correlation height] Set/Show lower ccf plot scaling +:ymax [correlation height] Set/Show upper ccf plot scaling +.fi + +.ce +FOURIER MODE 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 Enter Spectrum mode +t Display filtered and unfiltered template spectrum +x Return to parent mode + +:log_scale [y|n] Plot on a Log scale? +:one_image [object|template] What plot on screen +:overlay [y|n] Overlay filt function? +:<parameter> [value] Set/Show the FILTERPARS parameter value +:plot [object|template] What type of plot to draw on single plot? +:split_plot [y|n] Make a split-plot? +:when [before|after] Plot before/after filter? +:zoom [factor] FFT zoom parameter +.fi + +.ce +CONTINUUM MODE COMMANDS + +See \fBicfit\fR. + +.ce +SPECTRUM MODE COMMANDS +.nf +? Print list of cursor key and colon commands +b Select sample regions for both spectra +d Print velocity difference between two cursor positions +f Enter Fourier mode +i Display original input spectra +n Display continuum subtracted spectra +p Display the prepared spectra prior to correlation +q Quit +r Redraw +s Select sample region endpoints +u Unselect a sample region +x Return to correlation mode + +:<parameter> [value] Set/Show parameters in CONTINPARS pset +:osample [list] List of object sample regions +:rsample [list] List of template sample regions +:show List current parameters +.fi + +.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> fxcor.interactive = no # Do it in batch mode + rv> fxcor 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 two apertures of a multispec + image as the templates: + + cl> onedspec + on> scopy object.ms temp apert="8,9" inform="multi" outform="oned" + on> rv + rv> fxcor.interactive = no # Do it in batch mode + rv> fxcor object.ms temp.0008,temp.0009 apertures="1-7,10,12-35" + + In this example, apertures 8 and 9 of the object image will be used + as the template. The \fIscopy\fR task is used to extract the aper- + tures to onedspec format, into two images named "temp.0008" and + "temp.0009". The task is then run with all of the apertures in the + aperture list correlated against the onedspec templates. + + 3. Compute a velocity by fitting a fixed number of points on the peak, + using uniform weighting: + + rv> fxcor 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> fxcor 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> fxcor 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> fxcor 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 filtering is drawn with the requested filter (if any) + 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 input spectra displayed + ... type 's' to mark the endpoints of sample regions for correl- + ... ation. The user can mark either the top or bottom plot to + ... set sample regions for the object and template respectively. + ... 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 <cr> 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. + + 7. Save the correlation function of two galaxy spectra: + + rv> fxcor obj temp inter+ ccftype="text" + Screen is cleared and CCF peak with fit displayed + + ... type ":wccf" to write the CCF + ... type in a filename for the text output + ... quit the task + + rv> rspectext ccf.txt ccf.fits dtype=interp + rv> splot ccf.fits + + The velocity per-pixel-shift is non-linear and is an approximation + which works well for low-velocity shifts. In the case of hi-velocity + correlations (or when there are many points) it is best to save the + CCF as a text file where the velocity at each shift is written to + the file, then use RSPECTEXT to linearize and convert to an image + format. This avoids the task interpolating a saved image CCF in + cases where it may not be required. + + 7. Compute a cross-correlation where the template has already been + corrected to the rest frame and no heliocentric correction is + required: + + Step 1) Use the HEDIT or HFIX tasks to add the following + keywords to the template image: + + DATE-OBS= '1993-03-17T04:56:38.0' + RA = '12:00:00' + DEC = '12:00:00' + EPOCH = 1993.0 + OBSERVAT= 'KPNO' + VHELIO = 0.0 + + These values produce a heliocentric correction of zero + to within 5 decimal places. The VHELIO keyword will + default to zero if not present. + + Step 2) Use the HEDIT task to add an OBSERVAT keyword to each + of the object spectra. The OBSERVATORY task can be used + get a list of recognized observatories. + + Because mixing observatories is not currently well supported, the + use of the OBSERVAT keyword in \fI both\fR images is the only sure + way to apply the proper observatory information to each image. Users + may wish to derive a zero-valued heliocentric correction for their + local observatory and use those values instead. +.fi + +.ih +SEE ALSO +continpars, filtpars, observatory, keywpars, onedspec.specwcs, center1d, +dispcor, stsdas.fourier +.endhelp diff --git a/noao/rv/doc/keywpars.hlp b/noao/rv/doc/keywpars.hlp new file mode 100644 index 00000000..5fd1aa9f --- /dev/null +++ b/noao/rv/doc/keywpars.hlp @@ -0,0 +1,94 @@ +.help keywpars Dec90 noao.rv +.ih +NAME +keywpars -- edit the image header keywords used by the package +.ih +USAGE +keywpars +.ih +PARAMETERS +.ls ra = "RA" +Right Ascension keyword. (Value in HMS format). +.le +.ls dec = "DEC" +Declination keyword. (Value in HMS format). +.le +.ls ut = "UT" +UT of observation keyword. This field is the UT start of the observation. +(Value in HMS Format). +.le +.ls utmiddle = "UTMIDDLE" +UT mid-point of observation keyword. This field is the UT mid-point of +the observation. (Value in HMS Format). +.le +.ls exptime = "EXPTIME" +Exposure time keyword. (Value in Seconds). +.le +.ls epoch = "EPOCH" +Epoch of coordinates keyword. (Value in Years). +.le +.ls date_obs = "DATE-OBS" +Date of observation keyword. Format for this field should be +dd/mm/yy, (old FITS format), yyyy-mm-dd (new FITS format), or +yyyy-mm-ddThh:mm:ss.sss (new FITS format with time). +.le + +.ce +OUTPUT KEYWORDS +.ls hjd = "HJD" +Heliocentric Julian date keyword. (Value in Days). +.le +.ls mjd_obs = "MJD-OBS" +Modified Julian Data keyword. The MJD is defined as the julian date of +the mid-point of the observation - 2440000.5. (Value in Days). +.le +.ls vobs = "VOBS" +Observed radial velocity keyword. (Value in Km/sec). +.le +.ls vrel = "VREL" +Observed radial velocity keyword. (Value in Km/sec). +.le +.ls vhelio = "VHELIO" +Corrected heliocentric radial velocity keyword. (Value in Km/sec). +.le +.ls vlsr = "VLSR" +Local Standard of Rest velocity keyword. (Value in Km/sec). +.le +.ls vsun = "VSUN" +Epoch of solar motion. (Character string with four real valued fields +describing the solar velocity (km/sec), the RA of the solar velocity (hours), +the declination of the solar velocity (degrees), and the epoch of solar +coordinates (years)). +.le +.ih +DESCRIPTION +The image header keywords used by the \fIfxcor\fR task can be +edited if they differ +from the NOAO standard keywords. For example, if the image header keyword +giving the exposure time for the image is written out as "EXP-TIME" instead +of the standard "OTIME" at a given site, the keyword accessed for +that information +may be changed based on the value of the \fIexptime\fR parameter. + +The \fIvhelio\fR keywords must be added to the image header of the template +spectrum and should contain the known radial velocity of the template star. +The output keywords may be added to the object image header if the +tasks \fIfxcor.imudate\fR parameter is set. + +.ih +EXAMPLES +1. List the image header keywords. + +.nf + rv> lpar keywpars +.fi + +2. Edit the image header keywords + +.nf + rv> keywpars +.fi +.ih +SEE ALSO +fxcor +.endhelp 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 ":/<command>" 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 <cr> 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 diff --git a/noao/rv/doc/rvidlines.hlp b/noao/rv/doc/rvidlines.hlp new file mode 100644 index 00000000..2e87a412 --- /dev/null +++ b/noao/rv/doc/rvidlines.hlp @@ -0,0 +1,530 @@ +.help rvidlines Aug93 noao.rv +.ih +NAME +rvidlines -- Measure radial velocities from spectral lines +.ih +USAGE +rvidlines images +.ih +PARAMETERS +.ls images +List of spectral images in which to identify spectral lines and measure a +velocity. The spectra must be dispersion calibrated in Angstroms. +.le +.ls section = "middle line" +If an image is not one dimensional or given as a one dimensional image +section then the image section given by this parameter is used. The +section is used to define the initial vector and the direction (columns, +lines, or "z") of the image vectors to be fit. The image is still considered +to be two or three dimensional and it is possible to change the data vector +within the program. + +The section parameter may be specified directly as an image section or +in one of the following forms + +.nf +line|column|x|y|z first|middle|last|# [first|middle|last|#]] +first|middle|last|# [first|middle|last|#] line|column|x|y|z +.fi + +where each field can be one of the strings separated by | except for # +which is an integer number. The field in [] is a second designator +which is used with 3D data. See the example section for examples of +this syntax. Abbreviations are allowed though beware +that 'l' is not a sufficient abbreviation. +.le +.ls database = "database" +Database in which the feature data and redshifts are recorded. +.le +.ls coordlist = "" +User coordinate list consisting of an ordered list of rest spectral line +coordinates. If a line list is defined lines from the list may be +automatically found and added to the lines being measured. +.le +.ls nsum = "10" +Number of lines, columns, or bands across the designated vector axis to be +summed when the image is a two or three dimensional spatial spectrum. +It does not apply to multispec format spectra. If the image is three +dimensional an optional second number can be specified for the higher +dimensional axis (the first number applies to the lower axis number and +the second to the higher axis number). If a second number is not specified +the first number is used for both axes. +.le +.ls match = 5. +The maximum difference for a match between the measured line coordinate +and a coordinate in the coordinate list. The units of this parameter +is that of the user coordinates. +.le +.ls maxfeatures = 50 +Maximum number of the strongest features to be selected automatically from +the coordinate list (function 'l') or from the image data (function 'y'). +.le +.ls zwidth = 100. +Width of graphs, in user coordinates, when in zoom mode (function 'z'). +.le + +The following parameters are used in determining feature positions. +.ls ftype = "absorption" (emission|absorption|gemission|gabsorption) +Type of features to be identified. The possibly abbreviated choices are +"emission", "absorption", "gemission", and "gabsorption". The first two +select the \fBcenter1d\fR centering algorithm while the last two +select the Gaussian fitting centering algorithm. +.le +.ls fwidth = 4. +Width in pixels of features to be identified. +.le +.ls cradius = 5. +The maximum distance, in pixels, allowed between a feature position +and the initial estimate when defining a new feature. +.le +.ls threshold = 0. +In order for a feature center to be determined the range of pixel intensities +around the feature must exceed this threshold. +.le +.ls minsep = 2. +The minimum separation, in pixels, allowed between feature positions +when defining a new feature. +.le + +The following parameters control the input and output. +.ls logfile = "logfile" +Log file for recording the results of the velocity measurements. The +results are written when exiting or changing input images. The +results can be previewed with the ":features" command. If no log file +is specified then the results are not saved. +.le +.ls autowrite = no +Automatically write or update the logfile and database? If no then a query +is given for writing results to the logfile. A query for writing to the +database is also given if the feature data have been modified. If yes +exiting the program automatically writes to the logfile and updates the +database. +.le +.ls keywpars = "" +The image header keyword translation table as described in +the \fIkeywpars\fR named pset. This defines the header keywords used +to obtain the observation information needed for computing the +heliocentric velocity. +.le +.ls graphics = "stdgraph" +Graphics device. The default is the standard graphics device which is +generally a graphics terminal. +.le +.ls cursor = "" +Cursor input file. If a cursor file is not given then the standard graphics +cursor is read. +.le +.ih +ADDTIONAL PARAMETERS +The measured velocities are corrected to a heliocentric frame of reference +if possible. This requires determining various parameters about the +observation. The latitude, longitude, and altitude of the observation +are determined from the observatory database. The observatory is +defined by either the OBSERVAT image header keyword or the "observatory" +package parameter in that order. See the help for \fBobservatory\fR +for additional information. + +The date, universal time, right ascension, declination, and coordinate epoch +for the observation are obtained from the image header. The keywords +for these parameters are defined in the \fBkeywpars\fR parameter set. +Note that the parameters used are "ra", "dec", "ut", and "date-obs". +The "utmiddle" parameter is not used so if you have a keyword for the +middle of the exposure that you want to use then you must set the +"ut" parameter to reference that keyword. + +Before IRAF V2.12, if the date keyword included a time then that time was +used and the "ut" keyword was not used. In V2.12 this was changed and the +time is always taken from the keyword specified by "ut". However, the +value can be in either a single time or a date/time string. So if you +want to use both the date and time from the same keyword, say DATE-OBS, +then point the "date_obs" and "ut" parameters in KEYWPARS to the same +keyword. +.ih +CURSOR KEYS + +.nf +? Clear the screen and print menu of options +a Apply next (c)enter or (d)elete operation to (a)ll features +b Mark and de(b)lend features by Gaussian fitting +c (C)enter the feature nearest the cursor +d (D)elete the feature nearest the cursor +f (F)it redshift and velocity from the fitted and user coordinates +i (I)nitialize (delete features and coordinate fit) +j Go to the preceding image line/column/band/aperture +k Go to the next image line/column/band/aperture +l Match coordinates in the coordinate (l)ist +m (M)ark new feature near the cursor and enter coord and label +n Move the cursor or zoom to the (n)ext feature (same as +) +o Go to the specified image line/column/band/aperture +p (P)an to user defined window after (z)ooming on a feature +q (Q)uit and continue with next image (also carriage return) +r (R)edraw the graph +t Reset the position of a feature without centering +u Enter a new (u)ser coordinate and label for the current feature +w (W)indow the graph. Use '?' to window prompt for more help. +y Automatically find strongest peaks and identify them +z (Z)oom on the feature nearest the cursor +. Move the cursor or zoom to the feature nearest the cursor ++ Move the cursor or zoom to the next feature +- Move the cursor or zoom to the previous feature +I Interrupt task and exit immediately +.fi + +The parameters are listed or set with the following commands which may be +abbreviated. To list the value of a parameter type the command alone. + +.nf +:show file Show the values of all the parameters +:features file Write feature list to file (default STDOUT) + +:coordlist file Coordinate list file +:cradius value Centering radius in pixels +:threshold value Detection threshold for feature centering +:database name Database for recording feature records +:ftype value Feature type + (emission|absorption|gemission|gabsorption) +:fwidth value Feature width in pixels +:image imagename Set a new image or show the current image +:labels value Feature label type + (none|index|pixel|coords|user|both) +:match value Coordinate list matching distance +:maxfeatures value Maximum number of features automatically found +:minsep value Minimum separation allowed between features +:read name ap Read a record from the database + (name/ap default to the current spectrum) +:write name ap Write a record to the database + (name/ap default to the current spectrum) +:add name ap Add features from the database + (name/ap default to the current spectrum) +:zwidth value Zoom width in user units + +Labels: + none - No labels + index - Sequential numbers in increasing pixel position + pixel - Pixel coordinates + coords - User coordinates such as wavelength + user - User labels + both - Combination of coords and user +.fi +.ih +DESCRIPTION +\fBRvidlines\fR measures radial velocities from spectra by determining the +wavelength shift in spectral lines relative to specified rest wavelengths. +The basic usage consists of identifying one or more spectral lines (also +called features), entering the rest wavelengths, and computing the average +wavelength shift converted to a radial velocity. Additional lines can then +be automatically added from a coordinate list of rest wavelengths. + +Each dispersion calibrated image in the input list is examined in turn. If +the image is not one dimensional or a one dimensional section of an image +then the image section given by the parameter \fIsection\fR is used. This +parameter may be specified in several ways as described in the parameter +and examples sections. The image section is used to select a starting +vector and image axis. The parameter \fInsum\fR determines the number +of lines, columns, or bands to sum in a two or three dimensional image. + +Once a spectrum has been selected it is graphed. The graph title includes +the image name, spectrum title, and the current velocity and redshift if +one has been determined. An initial feature list is read from the database +if an entry exists. The features are marked on the graph by tick marks. +The features may also be labeled using the ":label" option. The graph has +the observed wavelength scale along the bottom and the rest wavelength +scale along the top (if a velocity has been determined). The status line +gives the pixel coordinate, observed wavelength, rest wavelength (as +computed by the last velocity computation), the true rest wavelength, the +velocity residual, and an optional identification string for the "current" +feature. + +The graphics cursor is used to select features and perform various +functions. A menu of the keystroke options and functions is printed with +the key '?'. The cursor keys and their functions are defined in the CURSOR +KEYS section and described further below. The standard cursor mode keys +are also available to window and redraw the graph and to produce hardcopy +"snaps". + +There are two types of feature selection functions; defining new +features and selecting previously defined features. The 'm' key marks +a new feature near the cursor position. The feature position is +determined by a centering algorithm. There are two algorithms; +a flux bisecting algorithm called \fBcenter1d\fR and a gaussian +profile fitting algorithm. The choice of fitting algorithm and whether the +feature is an emission or absorption line is set by the \fIftype\fR +parameter. + +The center1d algorithm is described in the help topic \fBcenter1d\fR. The +parameters which control it are \fIfwidth\fR, \fIftype\fR, \fIcradius\fR, +and \fIthreshold\fR. + +The gaussian fitting algorithm estimates a linear local background by +looking for the minimum or maximum, depending on whether the feature type +is set to absorption or emission, within a distance of the entered cursor +position of one-half the feature width specified by the \fIfwidth\fR +parameter plus the centering error radius specified by the \fIcradius\fR +parameters. This background estimation is crude but generally is not +critical for reasonably strong lines. Once the sloped background is +defined a non-linear Levenberg-Marquardt algorithm determines the gaussian +center, peak strength, and sigma. The initial estimates for these +parameters are the starting center, the background subtracted pixel value +at the starting center, and the \fIfwidth\fR value divided by six. After +fitting the gaussian model it is overplotted on the data for comparison. The +\fIthreshold\fR parameter also applies to this algorithm to check for a +minimum data range and the \fIcradius\fR parameter checks for a maximum +error in the center from the initial value. + +For a more critical setting of the background in the gaussian algorithm or +for the simultaneous solution of multiple gaussian components (deblending) +the 'b' key is available. The 'b' key is used to mark the initial +positions of up to ten features. The feature marking ends with 'q'. The +user is then queried to mark two points for the linear background. After +doing the simultaneous fitting the user is queried sequentially for the +rest wavelengths of each line. Note that the 'b' key will do the gaussian +fitting regardless of whether the \fIftype\fR setting is for a gaussian +or not and can be used for fitting just a single line. + +When a feature is defined the value of \fIftype\fR and \fIfwidth\fR are +associated with the feature. Subsequent recentering will use these values +even if the default values are changed. This is how a combination of +absorption and emission lines may be defined. The only constraint to this +is that the feature data does not record the combination of lines used in a +deblending operation so automatic recentering will treat each line +separately. + +When a new feature is marked if the wavelength is within a distance given +by the parameter \fIminsep\fR of a previous feature it is considered to be +the same feature and replaces the old feature. The coordinate list is +searched for a match between the measured wavelength, corrected to rest +using the current velocity, and a user coordinate in the list. The +matching is based on the nearest line within a specified \fImatch\fR +distance. If a match is found it becomes the default user coordinate which +the user may override. The new feature is marked on the graph and it +becomes the current feature. The redefinition of a feature which is within +the minimum separation may be used to set the user coordinate from the +coordinate list. The 't' key allows setting the position of a feature to +other than that found by the centering algorithms. + +If at least one feature is marked with it's rest wavelength specified then +the 'l' key may be used to identify additional features from a coordinate +list of rest wavelengths. First a velocity is computed from the initial +features. Then each coordinate in the list is corrected to the +observed velocity and a feature is sought in the data at that point. +Up to a maximum number of features, set by the parameter \fImaxfeatures\fR, +may be defined in this way. A new velocity is computed using all the +located features. + +The 'y' key provides another way to add features. Rather than look for +features at the coordinates of a list, a peak finding algorithm is used to +find features up to the specified maximum number. If there are more +peaks only the strongest are kept. The peaks are then matched against the +coordinate list to find user coordinate values. + +To select a different feature as the current feature the keys '.', 'n', +'+', and '-' are used. The '.' selects the feature nearest the cursor, the +'n' and '+' select the next feature, and the '-' selects the previous +feature relative to the current feature in the feature list as ordered by +pixel coordinate. These keys are useful when redefining the user +coordinate with the 'u' key and when examining features in zoom mode. + +The key 'f' computes ("fits") a velocity to the defined features. +This is done by taking a weighted average of the redshifts, + +.nf + z = (measured - true) / true +.fi + +of the individual lines. The default weights are always one but a different +weight may be entered with the 'u' key. The average redshift is +converted to a Cz velocity (redshift times the speed of light) and +corrected to a heliocentric frame if possible. + +The heliocentric correction requires observatory and observation information. +The observatory is determined either from the OBSERVAT keyword in the +image header or by the "rv.observatory" package parameter. For a +discussion of how an observatory is defined and used see the help +for \fBobservatory\fR. In addition to the observatory the right +ascension, declination, coordinate epoch, and date and time of the +observation are required. If the time is in the date string it has +precedence over the time keyword. This information is sought in the image +header using the keywords defined in the \fBkeywpars\fR parameter +file. If there is insufficient information for the heliocentric +velocity correction only the observed velocity will be given. The +type of velocity (both velocity and redshift) is indicated by +identifiers such as Vobs and Vhelio. + +Note that a new velocity is only computed after typing 'f', 'l', +":features", or when exiting and writing the results to the database. +In other words, adding new features or deleting existing features +does not automatically update the velocity determination. + +Features may be deleted with the key 'd'. All features are deleted +when the 'a' key immediately precedes the delete key. Deleting the +features does not reset the velocity. The 'i' key initializes +everything by removing all features and reseting the velocity. + +It is common to transfer the feature identifications and velocities +from one image to another. When a new image without a database entry +is examined, such as when going to the next image in the input list, +changing image lines or columns with 'j', 'k' and 'o', or selecting +a new image with the ":image" command, the current feature list and +velocity are kept. Alternatively, a database record from a different +image may be read with the ":read" command. When transferring feature +identifications between images the feature coordinates will not agree exactly +with the new image feature positions and several options are available to +reregister the feature positions. The key 'c' centers the feature nearest +the cursor using the current position as the starting point. When preceded +with the 'a' key all the features are recentered (the user must refit +the coordinate function if desired). As an aside, the recentering +function is also useful when the parameters governing the feature +centering algorithm are changed. An additional options is the ":add" +command to add features from a database record. This does not overwrite +previous features as does ":read". + +Note that when a set of spectra all have the same features in nearly +the same location the task \fBrvreidlines\fR may be used to reidentify +the lines and compute a new velocity. + +In addition to the single keystroke commands there are commands initiated +by the key ':' (colon commands). As with the keystroke commands there are +a number of standard graphics features available beginning with ":." (type +":.help" for these commands). The rvidlines colon commands allow the task +parameter values to be listed and to be reset within the task. A parameter +is listed by typing its name. The colon command ":show" lists all the +parameters. A parameter value is reset by typing the parameter name +followed by the new value; for example ":match 10". Other colon commands +display the feature list and velocities (:features), control reading and +writing records to the database (:read and :write), and set the graph +display format. + +The feature identification process for an image is completed by typing 'q' +to quit. Attempting to quit an image without explicitly logging the +results or recording changes in the feature database produces a warning +message unless the \fIautowrite\fR parameter is set. If this parameter is +not set prompts are given asking whether to save the results to the log +file and the database, otherwise the results are automatically saved. As +an immediate exit the 'I' interrupt key may be used. This does not save +the feature information and may leave the graphics in a confused state. + +The information recorded in the logfile, if one is specified, includes +information about the observatory used for heliocentric corrections +(to verify the correct observatory was used), the list of features +used in the velocity computation, the wavelength and velocity RMS, +and lines with the observed and heliocentric redshifts and velocities. +These lines include an error in the mean derived from the weighted +RMS and the number of lines used, and the number of lines. This output +format is designed so that if there are multiple velocities recorded +in the same log file they can be easily extracted with the match command: + +.nf + cl> match Vhelio logfile + im1 45 : Vhelio = 15.06 km/s, Mean err = 4.593 km/s, Lines = 7 + im1 40 : Vhelio = 17.77 km/s, Mean err = 3.565 km/s, Lines = 7 + im2 45 : Vhelio = 24.44 km/s, Mean err = 3.741 km/s, Lines = 7 + im2 40 : Vhelio = 14.65 km/s, Mean err = 11.2 km/s, Lines = 7 + ... +.fi +.ih +DATABASE RECORDS +The database specified by the parameter \fIdatabase\fR is a directory of +simple text files. The text files have names beginning with 'id' followed +by the entry name, usually the name of the image. The database text files +consist of a number of records. A record begins with a line starting with the +keyword "begin". The rest of the line is the record identifier. Records +read and written by \fBrvidlines\fR have "identify" as the first word of the +identifier. Following this is a name which may be specified following the +":read" or ":write" commands. If no name is specified then the image name +is used. For 1D spectra the database entry includes the aperture number +and so to read a solution from a aperture different than the current image +and aperture number must be specified. For 2D/3D images the entry name +has the 1D image section which is what is specified to read the entry. +The lines following the record identifier contain +the feature information and redshift (without heliocentric correction). + +The database files have the name "identify" and the prefix "id" because +these files may also be read by the \fBidentify\fR task for changing +the dispersion function based on the rest wavelengths. +.ih +EXAMPLES +1. The radial velocity of the spectrum, kstar1, is to be determined. +The user creates a list of line features to be used in the file +klines.dat. + +.nf + cl> rvidlines kstar1 coord=klines.dat + a. The spectrum is drawn + b. A line is marked with 'm' + c. Enter the rest wavelength + d. Compute a velocity with 'f' + e. Find other lines in the list with 'l' + f. Exit with 'q' + Write velocity data to the logfile (yes)? y + Write feature data to the database (yes)? y + cl> match Vhelio logfile + kstar1 1 : Vhelio = 25.1 km/s, Mean err = 1.123 km/s, Lines = 10 +.fi + +2. For echelle or multispec spectra the keys 'o', 'j', and 'k' may +be used to switch between spectra. Note that the inheritance of features +in echelle orders is not very useful. So the 'i' can be used to +initialize. For similar spectra the 'a''c' key combination may +be used to recenter all lines and the a new 'f' fit can be done. + +3. For images which are two or three dimensional it is necessary to +specify the image axis for the data vector and the number of pixels at each +point across the vector direction to sum. One way specify a vector is to +use an image section to define a vector. For example, to select column +20: + +.nf + cl> rvidlines obj[20,*] +.fi + +The alternative is to use the section parameter. Below are some examples +of the section parameter syntax for an image "im2d" which is 100x200 +and "im3d" which is 100x200x50. On the left is the section string syntax +and on the right is the image section + +.nf + Section parameter | Image section | Description + ------------------|---------------------|--------------------- + first line | im2d[*,1] | First image line + middle column | im2d[50,*] | Middle image column + last z | im3d[100,200,*] | Last image z vector + middle last y | im3d[50,*,50] | Image y vector + line 20 | im2d[*,20] | Line 20 + column 20 | im2d[20,*] | Column 20 + x 20 | im2d[*,20] | Line 20 + y 20 | im2d[20,*] | Column 20 + y 20 30 | im2d[20,*,30] | Column 20 + z 20 30 | im3d[20,30,*] | Image z vector + x middle | im3d[*,100,25] | Middle of image + y middle | im3d[50,*,25] | Middle of image + z middle | im3d[50,100,*] | Middle of image +.fi + +The most common usage should be "middle line", "middle column" or "middle z". + +The summing factors apply to the axes across the specified vector. For +3D images there may be one or two values. The following shows which axes +are summed, the second and third columns, when the vector axis is that shown +in the first column. + +.nf + Vector axis | Sum axis in 2D | Sum axes in 3D + ------------------|---------------------|-------------------- + 1 | 2 | 2 3 + 2 | 1 | 1 3 + 3 | - | 1 2 +.fi + +.ih +REVISIONS +.ls RVIDLINES V2.11 +This task will now work in the units of the input spectra. +.le +.ls RVIDLINES V2.10.3 +This is a new task in this version. +.le +.ih +SEE ALSO +center1d, fxcor, gtools, identify, keywpars, observatory, +rvcorrect, rvreidlines +.endhelp diff --git a/noao/rv/doc/rvpackage.spc b/noao/rv/doc/rvpackage.spc new file mode 100644 index 00000000..216f622b --- /dev/null +++ b/noao/rv/doc/rvpackage.spc @@ -0,0 +1,948 @@ +.EQ +delim $$ +.EN +.RP +.TL +Specifications for the Radial Velocity Analysis Package + +.AU +Michael J. Fitzpatrick +.AI +.K2 "" "" "*" +Revised January 1990 + +.AB +.PP +Specifications are presented for an IRAF package to compute radial velocity, +redshift and dispersion information from both one and two dimensional +IRAF images. Requirements and specifications for each necessary task are +described as well as the algorithms used. Specifications of user input +and program output are also discussed. Detailed manual pages of the tasks +are included following this document. +.AE + +.NH +Introduction +.PP +The following document describes the specifications for the radial velocity +package. This package will be designed to produce radial velocity, redshift +and dispersion data for both one and two dimensional images. To this end +both cross correlation and Fourier techniques will be employed, thus allowing +the user to choose the method of correlation best suited to his data. Since +the needs of the individual astronomer will differ, the tasks in this package +will use different algorithms for computation but will share some common +output. This common output may later be used to compare the results of one +method over another, or one parameter set over another. +.PP +Most radial velocity work is done by cross correlating a standard template star +with an unknown object spectrum. This is most often the case with a one +dimensional data set in which the value of interest is the heliocentric radial +velocity of the object star measured with respect to the template star +(which is usually a radial velocity standard of known velocity). Several + methods will be used to provide this information: +.IP \(bu +A standard Fourier correlation technique in which the data are transformed +and then mulitplied one by the complex conjugate of the other and reverse +transformed, thus procuding a normalized cross correlation function. +Filtering of the data while in Fourier space is allowed. Error calculations +are also better prepared because of the nature of the algorithms. +.IP \(bu +A squared difference method in which the sums of the squared difference between +the intensities of the two spectra are computed at each trial shift. This +produces an unnormalized function which may be used to compute a relative +shift and hence velocity. Restictions on this task will be rather loose +to allow it to be used more efficiently as a "quick-look" device. +.IP \(bu +A direct correlation method, identical in operation to the squared difference +task yet producing a normalized correlation function. +.LP +All of the resulting functions are fit with a user specified function +providing a more accurate velocity. The details of these functions and +relative merits of the methods are discussed below. +.PP +A second desire of astronomers using this package is to correlate a galaxy +spectrum against a standard template spectrum. While this may be done with +one dimensional data to produce a redshift value, it is often used with +two dimensional data in which the aim is produce a velocity dispersion of the +galaxy with respect to a distance \fIr\fR from the center. Using this +information at different position angles across the galaxy image, it is +possible to map a velocity field +within the galaxy, describing it's rotation. Again, two methods will be used +to provide this information. +.IP \(bu +A Fourier quotient method in which the ratio of the Fourier transforms of +the galaxy to the stellar spectra are fit to the Fourier transform of a chosen +broadening function, the results of which provide the velocity dispersion, +redshift, and relative line strength parameter. +.IP \(bu +A Fourier difference method in which the difference of the Fourier transforms +of the galaxy and star spectra are fit to the Fourier transform of a chosen +broadening function, the results of which provide the velocity dispersion, +redshift, and relative line strength parameter. +.LP +The details of these functions and methods and their relative merits +are discussed below. +.PP +Each of the tasks in this package will also act as an interactive parameter +editor, permitting the user to change task parameter values and immediately +examine the effect on the data. The user may then save these parameters for +a batch (non-interactive) run or process each of the images individually. +.PP +Although it will be generally assumed that the data have been prepared using +other applications available within IRAF, a limited set of data preparation +commands will be available within each of the major tasks. (A more in depth +description of these tasks is found below.) These commands will perform the +following functions: +.IP \(bu +Filtering of the data while in Fourier space. Often times it may be necessary +to filter certain frequency components from the data that may artificially +weight the correlation. A choice of filter functions will be available and +the user may specify the fourier components over which the filter will operate. +.IP \(bu +Removal of a local continuum. While this task is easily accomplished with +either the \fICONTINUUM\fR task or selective filtering, it is sometimes +desireable to remove a continuum from the data at this step of the analysis. +The user specifies the order of a polynomial or spline to be fit to the +data to remove low frequency trends in the data. This fitted function may be +either subtracted or divided from the data. +.IP \(bu +Masking of regions to be used in the correlation. To exclude sparse +line regions, +bad pixels, or telluric features, it will sometimes be necessary to input a +specific region to be used in the correlation. The user is able to specify in +either pixel number or wavelength the regions to be included in the +correlation. Since a broad error in the chip or wide feature may weight the +continuum fitting, continuum fitting will also take advantage of regions via +the \fICONTINUUM.SAMPLES\fR parameter. + +.NH +Input Requirements and Specifications +.PP +The following requirements and specifications will be met with regard +to input format to all of the tasks: +.IP \(bu +The object and template stars may both be specified as lists. Both lists +may be positioned forward and backward from interactive operation with a colon +command. In interactive mode the user is required to position each list +separately. In batch mode each object spectrum is correlated to each +template in the list before moving on to the next object. +.IP \(bu +The user may specify an aperture list to be used in the correlation. +This aperture list will be used in both the object and template spectrum. +It may be used to specify an echelle order or simply the row number in +a two dimensional image to be used if for some reason data have been stacked. +In the case of a two dimensional object/template spectrum and it's one +dimensional counterpart, the aperture number will apply only to the two +dimensional data. +.IP \(bu +The new IRAF echelle and multispec formats will be supported. +.IP \(bu +Data are required to be binned linearly in logarithm of the wavelength for +Fourier tasks. The squared difference or direct correlation +task may use either log-wavelength, +wavelength, or pixel scaled data. For pixel scaled data, output will +contain only pixel shift information since velocity information cannot be +computed. Data may be rebinned automaticall with the appropriate task through +use of the \fIPROCESSPARS\fR pset (see below). +.KS +.IP \(bu +The following information must be contained in each object image header in +order for the heliocentric correction to be done properly: +.nf +.ta 1i 2i 3i + ra - Right Ascension of object + dec - Declination of object + date-obs - UT Date of observation + ut - UT time of observation + epoch - Epoch of observation + exptime/otime - Exposure time of frame + w0/crval1 - Starting wavelength in Angstroms or log(Angstroms) + wpc/crdelt1 - Wavelength increment in Angstroms or log(Angstroms) +.fi +Keyword translation is handled by the \fIRVKEYWORDS\fR pset as discussed +below. Warning messages will be issued for missing keywords, which may +affect the accuracy of the results. +.KE +.IP \(bu +The user may input a number of rows that will be averaged according to +user specifications to be used in the correlation for the \fIXCOR2D\fR +task. For two dimensional data it may be desired to average a number of +rows into bins for computation rather than doing each row independantly. +Presently the template spectrum is assumed to be a one dimensional spectrum, +if not only the first row will be used in the correlation. +.IP \(bu +The \fIMKBINS\fR task may be used to create bins of approximately equal +intensity. A description of this task and the database structure used +is described below. + +.NH 2 +Rebinning of Input Data +.PP +Input data should be dispersion corrected, and while certain tasks require that +the data be presented on a logarithmic scale, it shall be possible to input +data which are not logarithmically binned. In this case, and if required by the +task, the data shall be rebinned automatically from the data I/O routines using +the same (or equivalent) starting wavelength and wavelength per channel values. +An informational message will be enetered into the log file indicating that +the data have been rebinned. +.PP +The parameters controlling data rebinning will be retrieved from +the \fIprocesspars\fR pset and the image header. The interpolation function +may be changed with the \fI:rb_func [s_value]\fR command followed by +a \fI:rebin\fR command to perform the action. This ability will be common to +all tasks. When data have been rebinned, a note will be made to the log file. +In batch operation of any task, the data will be rebinned automatically if +required and the appropriate notes made to the log file. +.PP +The \fIw0\fR, \fIwpc\fR and \fInpts\fR parameters will be obtained from the +current image header in the \fIprocesspars\fR value is INDEF, otherwise these +may be set to overide the current value. +.PP +If the user is not satisfied with rebinning the data using the current +dispersion or number of points, the \fIdo_rebin\fR parameter should be turned +off and the data rebinned outside the task using one of the other available +tasks. If \fIdo_rebin\fR is disabled and data must be rebinned, the task +will abort with an error message. +.NH 2 +Continuum Removal From the Data +.PP +It shall be possible for the user to continuum normalize the data in a manner +identical to that done by the \fIonedspec.continuum\fR task. The data +input to the Fourier tasks should be normalized by subtracting the continuum +and dividing by the average to get a mean of zero with excursions of order +unity. The \fIrvfquot\fR and \fIrvfdiff\fR tasks need to know the value of the +spectrum average in order to compute the photon counting statustucs before +normalization so it is advised that continuum +normalization be left to the task (i.e. use the normalization commands +available in the tasks as opposed to the \fIcontinuum\fR task) +The apodized, normalized spectrum may be previewed by issuing a \fI:cont\fR +command to do the normalization and a \fIn\fR keystroke to show a split-plot +of the flattened data +.PP +Interactive flattening of the data behaves exactly like the \fIcontinuum\fR +task, except that the data are divided by the average once the continuum has +been subtracted. If the \fIprocesspars.type\fR parameter is set to "ratio" +then the data will be normalized to a mean of unity and will not be divided +by the average. + +.NH +Output Requirements and Specifications +.PP +Output from the tasks will take the form of either graphics drawn to the +standard graphics device, metacode to a graphics spool file, or text +(sometimes verbose) output to a spool file and the screen (the abridged +version). With the exception of the pset tasks, all other tasks in this +package may have graphics and or text output. +.NH 2 +Graphics Output +.NH 3 +Graphics Metacode +.PP +The simplest graphical output from the tasks \fIrvfquot\fR and \fIrvfdiff\fR, +will be metacode for the quotient or difference plots (if the \fIfit_plot\fR +or \fIdiff_plot\fR parameters are set) and the FFT's of the data (if +the \fIfft_plot\fR parameter is set). +The simplest graphical output from the tasks \fIrvsqdiff\fR and \fIrvxcor\fR +gin + +will be metacode of the correlation plot and it's fitted function (s) directed +to a user named spool file. +.PP +Metacode from the \fIrvdisp\fR task will be written to a user defined file +and consist only of the computed dispersion curves and fit. +.PP +These plots may later be viewed with the \fIgkimosaic\fR task to quickly view +the results of a batch process. Each time the user uses either the 'g' or 'y' +commands to fit to new points, metacode for the new fit will also be written. +.NH 3 +Standard Graphics Plots +.PP +Plots drawn to the screen from the four main cross correlation tasks will +consist of the following: +.IP \(bu +An overplot of the two spectra upon task startup and every time a new image +is read (except when the \fIspec_plot\fR parameter is set). The mean of the +data will be normalized to unity to allow for the overplotting of the two +spectra, which may be at different intensity scales. The mean is used instead +of the maximum so that cosmic ray events will not affect the plotting. +.IP \(bu +A plot of the Fourier transform of each spectrum to aide the user in choosing +a proper filter. This plot will be generated for each spectrum's transform +and shown to the user by typing the 'f' command. After viewing the plots +the user may issue commands to select an appropriate filter. +.IP \(bu +A graph of the fitting function. The fitted function will be overplot on the +correlation function once the endpoints have been selected and the fit +completed. This plot is also written to the metacode file if specified. +.IP \(bu +For the tasks \fIrvxcor\fR and \fIrvsqdiff\fR a correlation plot produced +by those methods. This plot is also written to the metacode file if specified. +.IP \(bu +For the \fIrvfquot\fR task a plot of the ratio of the galaxy to stellar +spectrum projected onto a unit vector $exp(-2 pi i k zeta / n)$ where $zeta$ +is the logarithmic redshift. For two dimensional galaxy spectra, +each bin will produce a quotient plot if the \fIquot_plot\fR parameter +is set. +.IP \(bu +For the \fIrvfdiff\fR task a plot of the difference of the galaxy and stellar +spectrum. For two dimensional galaxy spectra, +each bin will produce a difference plot if the \fIdiff_plot\fR parameter +is set or a summary plot if the \fIsummary_plot\fR parameter is set. +.NH 2 +Text Output +.PP +Text output to the logfile common to each task will be the following: +.IP \(bu +An optional header explaining the meaning of each parameter if the \fIheader\fR +parameter is set. +.IP \(bu +The initial parameters of the reduction, one to a line consisting of a +'#P' in the first two columns identifying the line as a parameter, the +parameter name, and it's value. Each time a parameter is changed from the +command loop, a new line will be written to the log file showing the new +value of the parameter. +.IP \(bu +A keyword formatted the same as the parameter line identifying the +image name (IMAGE), the object name (OBJECT), the template image +name (TEMPLATE), the bin number used (BIN_NO), the correlation or +reduction method (CORM) and the fitting function used (FITF). +.IP \(bu +A date/time string identifying the date/time of reduction. +.IP \(bu +Any error or warning messages issued from the task. +.IP \(bu +A data record containing values input to or computed by the task. +For the \fIrvxcor\fR and \fIrvsqdiff\fR tasks, the data record will +contain: +.RS +.IP \(bu +Heliocentric Julian Date +.IP \(bu +Computed pixel shift and error of fit to CCF +.IP \(bu +FWHM of CCF peak in pixels +.IP \(bu +Height of the peak +.IP \(bu +Observed radial velocity +.IP \(bu +Heliocentric radial velocity +.IP \(bu +The derived velocity dispersion. +.IP \(bu +Comments of reduction, identifying errors or trouble spots. +.RE +For the \fIrvfquot\fR and \fIrvfdiff\fR tasks, the data record will +contain: +.RS +.IP \(bu +Heliocentric Julian Date +.IP \(bu +Observed redshift, line strength parameter and dispersion +.IP \(bu +Heliocentric redshift +.IP \(bu +Error of fit to difference or quotient +.IP \(bu +Comments of reduction, identifying errors or trouble spots. +.RE +.NH 2 +Database Records +.PP +Dispersion calculations require that the solution from fitting the +dispersion curve (i.e. a curve produced by convolving Gaussians +of known width with stellar spectra and comparing the input gaussian +width with the derived correlation peak width) be used by the \fIrvxcor\fR +and \fIrvsqdiff\fR tasks to convert the derived correlation peak widths +to true dispersions. Since this is usually done empirically, the +task \fIrvdisp\fR will be used to convolve a stellar spectrum with +user specified widths and fit the resulting curve with a polynomial +of order $n$. The parameters used to create this curve as well as the +coefficients of the polynomial will be written in the form of a database +record. +.PP +The name of the database file may then be passed to either the \fIrvxcor\fR +or \fIrvsqdiff\fR tasks which will use the coefficients to convert +the correlation widths. The correlation tasks will also check each +record in a file to find one in which the parameters used for the +dispersion curve calculation match those used for the correlation. +Failing a match of parameters, no dispersion calculation will be done, however +a velocity value of the FWHM width will be printed. +Changing parameters in a task will also force a search search for a new +record to match the parameters. +.PP +Below is an example database record used by the \fIrvdisp\fR, \fIrvxcor\fR +and \fIrvsqdiff\fR tasks. +.nf + + #T Aug 31 14:50 + begin + image star001 + object HR1762 + corrfunc fourier + fitfunc parabola + filterpars + filter yes + filtertype hanning + cuton 5 + cutoff 150 + fullon 0 + fulloff 0 + apodize 0.1 + order 4 + vstart 10.0 + vincrement 5.0 + npts 10 + coeffs 4 + 0.21345 + 0.82548 + 0.02345 + 0.00342 +.fi + +.NH +Interactive Parameter Editing +.PP +One common trait of all the tasks is the ability to change +the value of parameters interactively using colon commands. The user +is able to evaluate the result of each parameter change and then decide +on the best value for his reduction. The basic idea is to allow the user to +examine the effects of different parameter values on a typical set of +data and then process the input list with the chosen parameters. The other +envisioned use is of an astronomer that has completely different data and +wishes to reduce each star individually. +.PP +One other point that should be noted is the interaction of parameters between +tasks in the package. For instance, the filtering parameters set by +the \fIfilterpars\fR pset are used by the \fIrvdisp\fR, \fIrvxcor\fR +and \fIrvsqdiff\fR tasks. Similarly, parameters used in the \fIrvdisp\fR +task should match as closely as possible those used in the correlation +tasks since the computation of the dispersion value relies on the fit +to the dispersion curve (which may or may not be the same for different +parameters). For this reason, many of the colon commands will be the +same between different tasks. +.PP +The \fI':update'\fR command is provided to save the chosen parameters to the +task or pset parameter files. +This command will also update the \fIfilterpars\fR +pset if given an argument of 'filter' (likewise for the other package psets). +Similarly, the \fI':unlearn'\fR command is provided to +reset the parameters to their default values. It should, however, be used +with care and as a last resort to reset the parameters to their defaults. +Each time a parameter is changed which will affect the output, a note is made +in the spool file reflecting the new parameter value. + +.br +.NH +Use of Parameter Sets in the Package +.PP +.NH 2 +Image Header Keyword Translation +.PP +The following parameters control translation of image header keywords. If +the exposure time for the frame is given by the "EXPTIME" keyword in your +image header, as opposed to the "OTIME" keyword, just change the value of +the keyword. +.nf + + (ra = "RA") Right Ascension keyword + (dec = "DEC") Declination keyword + (ut = "UT") UT of observation keyword + (exptime = "OTIME") Exposure time keyword + (epoch = "EPOCH") Epoch of observation keyword + (date_obs = "DATE-OBS") Date of observation keyword + (w0 = "W0") Starting wavelength keyword + (wpc = "WPC") Wavelength per channel keyword\n + (hjd = "HJD") Heliocentric Julian date + (vobs = "VOBS") Observed velocity keyword + (vhelio = "VHELIO") Heliocentric velocity keyword + (vlsr = "VLSR") LSR velocity keyword +.fi +.NH 2 +Processing Parameters +.PP +The following parameters control operation of the continuum removal and +data rebinning. INDEF values in the rebinning parameters indicate that +those values should be obtained from the image header. +.nf + (do_cont = yes) Do continuum normalization? + (interactive = no) Fit continuum interactively? + (type = "difference") Type of output (diff|ratio) + (sample = "*") Sample of points to use in fit + (naverage = 1) Number of points in sample averaging + (function = "spline3") Fitting function + (order = 1) Order of fitting function + (low_reject = 2.) Low rejection in sigma of fit + (high_reject = 2.) High rejection in sigma of fit + (niterate = 10) Number of rejection iterations + (grow = 1.) Rejection growing radius + (scale_conser = yes) Maintain scale of input image. + (obj_only = no) Normalize only object image? + + (do_rebin = yes) Rebin data if necessary? + (interp_mode = "poly5") Rebin interpolation method + (rb_order = 1) Order of fitting function + (w0 = INDEF) Starting wavelength + (wpc = INDEF) Wavelength increment + (npts = INDEF) No. of output points + + (ccf_output = "ccfdemo") Output file/image name for ccf dump + (out_type = "image") Type of output file to create + (out_axis = "lag") X-axis for output + +.fi +.NH 2 +Filter Parameters +.PP +The following parameters control filtering of the data while in Fourier +space. +.nf + + (filter = yes) Filter the data before correlation? + (filt_type = "ramp") Filter window type + (cuton = 1) Cuton wavenumber for filter + (cutoff = 100) Cutoff wavenumber for filter + (fullon = 10) Wavenumber at which filter reaches one + (fulloff = 200) Wavenumber at which filter reaches zero +.fi +.NH 2 +Fourier Plotting Parameters +.PP +The following parameters control filtering of the data while in Fourier +space. +.nf + (plot = "amplitude") What form of FFT plot? + (overlay = yes) Overlay the filter function on the plot? + (split_plot = yes) Produce a split plot on the screen? + (one_image = "object") What image is plotted if one screen + (when = "before") Plot FFT before or after filtering + (log_scale = yes) Plot on a log scale? + (x_axis = "frequency") What is the x-axis scaling? + (fft_zoom = 4.) Zoom factor if not displaying whole FFT +.fi + +.NH +Cross Correlation and Fourier Techniques Used +.PP +The requirements and specifications of the correlation and Fourier techniques +to be used are described below along with the gory detail of the algorithms +themselves. +.NH 2 +Requirements and Specifications +.LP +The cross correlation techniques used must provide the following operations: +.IP \(bu +Each one dimensional correlation must produce a value of the relative shift +between the object and template spectrum. +.IP \(bu +Each value of the shift derived from the correlation function shall have an +error estimate attatched to it. +.IP \(bu +Each correlation method must be independant of the data format (i.e. longslit +data which have been averaged into rows, echelle orders, or aperture numbers). +.IP \(bu +There shall be no restriction on the length of the data to be operated upon. +.IP \(bu +The user shall be able to control the range over which the resulting +correlation function is useful. For example, the user may filter out +wavenumbers that are not to be used in the correlation, adjust the range +over which a shift will be searched, or control the number of points in the +correlation function to be fit. +.LP +The following correlation methods will be made available by the package: +.IP \(bu +A squared difference method in which an unnormalized correlation function is +produced by summing the squared difference between the object and template +spectra at a given trial shift. +.IP \(bu +A standard Fourier correlation method in which the data are transformed and +one multiplied by the conjugate of the other and the resultant inverse +transformed to produce a normalized correlation function. +.IP \(bu +A Fourier quotient method in which a galaxy and stellar spectrum are transformed +and their ratio fit to a broadening function, the parameters of which will +describe the relative line strength, velocity dispersion and redshift of +the galaxy spectrum. +.IP \(bu +A Fourier difference method in which a galaxy and stellar spectrum +are transformed and their difference fit to a broadening function, the +parameters of which will describe the relative line strength, velocity +dispersion and redshift of the galaxy spectrum. +.NH 2 +Algorithms +.PP +The basic specific algorithms to be employed are briefly described below. +.NH 3 +Fourier Cross Correlation +.PP +The Fourier cross correlation is to be done in the standard way: The object +and template spectrum are transformed into Fourier space and once there the +object transform is multiplied by the complex conjugate of the template +transform. The resultant is then inverse transformed back to real space +producing a normalized cross correlation function, the peak of which is +at a lag corresponding to the pixel shift between the two spectra. +The error computation +and the algorithm in general will follow the work of Tonry & Davis (1979, +Ast. J, \fI84\fR, 1511). +.NH 3 +Squared Difference Correlation +.PP +This method is most commonly known at NOAO as "Daryl's program" but actually +was described by Weiss et al (1978, Astron. Astrophys., \fI63\fR, 247). The +method works as follows: +.EQ + d sub j ~=~ sum from i=n1 to n2 (x sub i ~-~ y sub i+j ) sup 2 +.EN +where $x sub i$ denotes the intensity of the reference spectrum and $y sub i+j$ +denotes the intensity of the object spectrum at a trial shift $j$. +The resulting $d sub j$ array produces a curve whose minimum is at the pixel +shift between the two spectra. Unfortunately, this method produces an +unnormalized correlation function, thus making an estimate of the quality +of the correlation impossible. +.NH 3 +Fourier Quotient Method +.PP +This method was first described by Sargent et al (1977, Astrophys. J, \fI212\fR, +326) and is still a useful method for obtaining velocity dispersions in +galaxies. It is assumed that the galaxy spectrum is a convolution of an +appropriate mean stellar spectrum with a Doppler broadening function. +From the convolution theorem then, the +Fourier transform of the galaxy spectrum would be the product of the transform +of the stellar spectrum with the transform of the broadening function. The +broadening function is usually assumed to be a Gaussian characterized by a +dispersion $sigma$ and a redshift $z$. +By computing the transforms of the galaxy and template (stellar) spectra, it is +possible to fit the ratio of the galaxy transform to the stellar transform, +adopting the values of $sigma$ and $z$ which yield the best fit. +.PP +Therefore, from the definition of the discrete Fourier transform +F(k) of a function F(j), we find that the broadening function is described +in terms of the transforms of the galaxy spectrum G(j) and the +star spectrum S(j) as +.EQ + { G tilde (k) } over { S tilde (k) } ~~=~~ gamma~ exp left [ - 1 over 2 +left ( {2 pi ks} over n right ) sup 2 ~+~ { { 2 pi k zeta} over n } right ]~~ ; +.EN +.EQ + s ~==~ sigma over { c~ DELTA~ ln lambda} ,~~~~~~~ + zeta ~==~ { ln (1 + z) } over { DELTA~ ln lambda } +.EN +The parameters \fIs\fR and $zeta$ +are the velocity dispersion and logarithmic redshift measured in pixels +respectively. The parameter $gamma$ +is a normalization factor which measures the strength of the galaxy lines +with respect to the stellar lines. +.NH 3 +Fourier Difference Method +.PP +The Fourier difference method is similar to the quotient method in the +assumption that a galaxy spectrum can be treated as a mean stellar spectrum +convolved with a broadening function. It does, however, try to remedy +the inherent deficiency of weighting certain points too heavily that +appears in the Fourier Quotient method. The Fourier difference method is +best described by noting that the galaxy and stellar spectra are fit to +each other rather than to the broadening function, thus making the error +analysis more straightforward. If the noise in the stellar spectrum +is negligable, however, then the two methods are comparable. +.PP +For a given galaxy spectrum \fIG\fR, a stellar spectrum \fIS\fR, and a +broadening function \fIB\fR, we wish to minimize the residual in the Fourier +domain denoted +by +.EQ + chi tilde sup 2 ~=~ sum from j=0 to N-1 ~( G tilde "" sub j sup * ~-~ +B tilde "" sub j sup * G tilde "" sub j sup * )~( G tilde "" sub j ~-~ +B tilde "" sub j G tilde "" sub j ) +.EN +Where $G tilde$, $S tilde$, and $B tilde$ are the Fourier transforms of +the galaxy, star, and broadening function respectively. +This should simplify the numerical fitting because the convolution is now +a simple multiplication in Fourier space. + +.NH +Remaining Task Algorithms +.PP +\fBNOTE:\fI At this writing, the details of these algorithms are not +yet defined.\fR +.NH 2 +Telluric Line Removal +.PP +A task shall be written to automatically remove telluric or other artificial +features. The cross correlation techniques will be employed to compute the +relative shift between the object and template spectra. The relative line +depths will also be computed and the spectra divided to remove the lines +in the template spectrum from the object spectrum. +.NH 2 +Fitting (Emmision) Line Profiles +.PP +A task shall be written to do line profile fitting for the purpose of velocity +analysis. It will be possible to trace the various profile parameters (center, +width, etc) and derive velocity information. This task may also be used to +do postprocessing of the correlation function. + +.NH +Filtering of the Data in Fourier Space +.PP +To remove noise in the data once it has been transformed into the Fourier +domain, it must be possible to filter out unwanted frequencies from the data. +Filtering the data in the Fourier domain by attenuating or eliminating +certain frequencies has the same effect as smoothing the data in real space. +Since the data are assumed to be binned linearly in log wavelength, no +phase shifts are introduced by the filtering. +.NH 2 +Requirements and Specifications +.LP +The following filtering requirements must be met +.IP \(bu +A choice of filtering functions must be made available to the user. +.IP \(bu +The user must specify the wavenumbers over which the filter will operate. +.IP \(bu +The data must be binned linearly with the logarithm of the wavelength so as +not to introduce any phase shifts when filtering. +.IP \(bu +Filtering of data must be possible from any of the tasks using Fourier +techniques. +.IP \(bu +Those wavenumbers outside the specified cuton and cutoff numbers will be set to +zero, while those inside the range will be attenuated according to the +filter function chosen. +.IP \(bu +The specified range over which the filter extends must be the same for both the +object and reference spectrum. +.LP +The following filtering functions will be made available to the user: +.IP \(bu +\fBSquare\fR - A square step function in which the user specifies the +beginning and ending wavenumbers. +.IP \(bu +\fBRamp\fR - A ramp function in which the user must specify the cuton +wavenumber, the wavenumber at which the filter reaches full value, the +wavenumber at which the filter begins to decline and the cutoff wavenumber. +.IP \(bu +\fBHanning\fR - The user must specify the cuton and cutoff wavenumbers. +The data are attentuated according to the function: +.EQ +w sub j ~=~ 1 over 2 left [ 1. ~-~ cos left ( { 2 pi j } over { N-1 } right ) right ] +.EN +.nf +.na + where j = (wavenumber - cuton_wavenumer) + N = (cutoff - cuton) + 1 +.ad +.fi +.IP \(bu +\fBWelch\fR - The user must specify the cuton and cutoff wavenumbers. +The data are attentuated according to the function: +.EQ +w sub j ~=~ 1 ~-~ left [ { j ~-~ 1 over 2 ( N - 1 ) } over { 1 over 2 ( N + 1 ) } right ] sup 2 +.EN +.nf +.na + where j = (wavenumber - cuton_wavenumer) + N = (cutoff - cuton) + 1 +.ad +.fi + +.NH +Dispersion Calculations +.PP +Often times when computing the velocity dispersion from a correlation function, +the simplest thing to be done is to convert the full width at half maximum +(FWHM) of the fitted peak to a velocity. However, this is not fully correct +since the width of the correlation function is "an average of the widths of +galaxy lines quadratically added to the widths of template lines, and is +therefore the quadratic sum of two stellar widths and the velocity broadening +width". If the function fit to the peak is a polynomial (e.g a parabola), +what is required is a method in which to convert a simple FWHM pixel width of +the ccf to a true dispersion. +.PP +When the correlation peak is fit and a width determined, we must define +a relationship between the width $w$ and the width of a Gaussian profile +(the intrinsic dispersion), $gamma$. For a given fit to the +peak, this can be expressed (following Tonry & Davis) as +.EQ +gamma ~=~ f(w) ~=~ s sub 1 ~+~ s sub 2 w ~+~ s sub 3 w sup 2 ~+~ s sub 4 w sup 3 +.EN +.LP +The coefficients for this function are computed by empirically convolving +Gaussians of known velocity width with stellar spectra, thus producing +a plot of dispersion versus width which can be fit to obtain the coefficients +of the polynomial. +It must be remembered that the coefficients $s sub i$ must be recalculated +at each new instrumental setup since the function $f(w)$ is used to also +remove the instrumental distortions that can be caused by varying slit widths. +.PP +The \fIrvdisp\fR task may be used to compute the polynomial coefficients +and produce a database record of the input parameters and coefficients +that will be used bythe correlation tasks. Multiple records per file +are permitted, allowing for varying instrumental setups and parameters since +the correlation tasks will search for a match of parameters. +.NH 2 +Requirements and Specifications +.PP +To meet the needs of the astronomer in calculating dispersions, a task will +be written that meets the following specifications: +.IP \(bu +The user must specify the number of points to be computed, the velocity +increment, and the starting dispersion velocity, +thus producing a lookup table at a specified resolution. +.IP \(bu +The user will specify the name of a database file which will contain the +$s sub i$ coefficients as well as the points used in the fit and parameters +of the task. +.IP \(bu +Each of the tasks that can compute a dispersion can be furnished the +name of this database file and use the information contained to compute +a dispersion value from the width of the correlation function. +.IP \(bu +The task will be able to run in interactive or batch mode. In batch mode the +task will compute the dispersions and output to the database automatically. +In interactive mode the user may adjust parameters as in other tasks in this +package, allowing him to produce database files for various instrumental +setups at one time. +.IP \(bu +The task must be able to call one of the other one dimensional correlation +routines to compute the correlation functions. +.IP \(bu +The task must be able to call one of the other available fitting functions. +.IP \(bu +The task must be able to filter the data if a Fourier method is chosen. + +.NH +Fitting Functions +.PP +A set of non-linear least squares routines is needed to fit the computed +correlation function to obtain a shift, or to fit the entire spectum to +flatten it. Polynomial fitting routines are well known and easy enough to +implement, but we also require more complex functions. Not only is it +desireable to fit a parabola (second order polynomial) to the peak of the +correlation function (which is a real function), but +a Gaussian is sometimes desired. Also, when +fitting the ratio or difference between the transforms of the galaxy and +stellar spectra, a gaussian is needed to fit the complex transform of the +broadening function. +.PP +Since a variety of fitting functions are needed and to ease in the +incorporation of other fitting functions in the future, the non-linear +least squares package \fInlfit\fR written by Lindsay Davis for the \fIAPPHOT\fR +package will be used. This has the distinct advatange that all that is +required to add a new function is to write routines to evaluate the +function and it's derivatives, simplifying things greatly. +.NH 2 +Requirements and Specifications +.PP +The following fitting functions will be provided and are chosen through +the tasks parameters or commands: +.KS +.IP \(bu +Parabola. +.IP \(bu +One dimensional real Gaussian. +.IP \(bu +One dimensional complex Gaussian. +.IP \(bu +$N sup th$-order polynomial. +.KE + +.EQ +delim off +.EN +.NH +Tasks +.PP +The required tasks for this package are the following: +.nf + +.na + mkbins - Create bins of approximately equal flux intensity + observatory - Observatory location database + processpars - Batch processing parameters for RV package + filterpars - Edit the filter function parameters + rvcorrect - Compute radial velocity corrections + rvdisp - Produce velocity dispersions from CCF widths + rvemfit - Fit emmission features in spectra + rvfdiff - Redshifts and dispersions via Fourier Difference techniques + rvfquot - Redshifts and dispersions via Fourier Quotient techniques + rvkeywords - Keyword translation table for RV image headers + rvselect - Select output fields from an RV record + rvskyline - Telluric line removal/fitting task + rvstats - Print information to aide in RV parameter selection + rvsummary - Print a summary table of output from RV tasks + rvsqdiff - Radial velocities via a squared difference correlation + rvxcor - Radial velocities via Fourier cross correlation + xcor2d - Cross correlation of two dimensional data +.ad +.fi + +.NH 2 +Usage +.LP +Some examples of typical usage are listed below. +.IP \(bu +A user has a series of Longslit spectra of galaxies at differing position +angles and wishes to correlate them with a template spectrum to +obtain redshift and dispersion information. +The user then uses the \fIrvfdiff\fR +or \fIrvfquot\fR tasks to correlate the spectra and compute the dispersions. +.IP \(bu +A user is interested in obtaining radial velocities of a series of spectra +obtained over several nights with different instrumental setups. +The \fIrvdisp\fR task is used to create dispersion tables for each instrumental +setup. One of the correlation tasks is then used to correlate each set +of spectra. +.IP \(bu +A user has a small series of unusual spectra of different spectral types +and wishes to obtain radial velocities. +The \fIrvdisp\fR task is used to create dispersion tables for each instrumental +setup. The user then chooses the correlation method he wishes to use and +interactively adjusts parameters for each object spectrum, writing the results +to the logfile when satisfied. +.IP \(bu +A user has a large number of low signal-to-noise spectra to be correlated +to obtain a list of radial velocities. +The \fIrvdisp\fR task is used to create dispersion tables for each new +instrumental setup (if any). The user then chooses the correlation method +he wishes to use and after setting up the parameters, processes the list +as a background job. After returning from coffee, he examines the +output list and graphics spool file for bad fits which can be done by hand +later. +.IP \(bu +A user has an old set of spectra for which he was only able to obtain an +observed radial velocity and wishes to do the heliocentric velocity corrections. +The user may then use the use the \fIimages.hedit\fR tasks to insert the +observed velocity into the image header. The \fIrvcorrect\fR task is then +called to correct each image with respect to the sun (or even the Local +Standard of Rest). + +.NH 1 +Bibliography +.PP +.XP +Press, W.H. et al 1986, \fINumerical Recipes\fR, Cambridge Univ. Press, + Cambridge, Ch 12. +.XP +Rabiner, L.R. and Gold, B. 1975 \fITheory and Application of Digital + Signal Processing\fR, Prentice Hall, Englewood Cliffs, Ch 3. +.XP +Sargent, Schechter, Boksenberg and Shortridge, 1977, "Velocity Dispersions + for 13 Galaxies", \fIAstrop. J.\fR \fB212\fR p326. +.XP +Tonry, J. and Davis, M. 1979, "A Survey of Galaxy Redshift. I. Data + Reduction Techniques", \fIAstron. J.\fR \fB84,\fR p 1511 +.XP +Weiss, W.W. et al 1978, "A Statistical Approach for the Determination + of Relative Zeeman and Doppler Shifts in Spectrograms", \fIAstron. + Astrophys.\fR \fB63\fR, p 247. +.XP +Willmarth, D.W and Abt, H.A., 1985, "Radial Velocities From CCD Detectors" + in \fIIAU Coll. No. 88, Stellar Radial Velocities\fR, p 99 +.XP +Wyatt, W.F., 1985, "The CfA System for Digital Correlations" in + \fIIAU Coll. No 88, Stellar Radial Velocities\fR, p 123 +.PP + +.NH +Detailed Manual Pages +.PP + The individual manual pages for these tasks follow this document. diff --git a/noao/rv/doc/rvplan.ms b/noao/rv/doc/rvplan.ms new file mode 100644 index 00000000..7b81ee1a --- /dev/null +++ b/noao/rv/doc/rvplan.ms @@ -0,0 +1,91 @@ +.OM +.TO +RV folks +.FR +Doug Tody +.SU +RV development plans +.PP +The purpose of this memo is to introduce the RV "level zero specifications" +document enclosed, to explain what that means and what our plans for future +RV package development are, and how the new programming team approach being +used for RV and other projects works. +.SH +Programming Teams +.PP +As was mentioned in our RV meeting a while back, we are experimenting +with the use of small programmer teams for major projects such as RV. +In the case of RV, the programming team is Mike and Frank, with Mike being +the programmer in charge of the project, and Frank the reviewer and critic. +Frank and Mike work together on a daily basis and every few weeks the three +of us have a team meeting to review progress. Similar teams are being set +up for other projects, e.g., Mike (reviewer-critic) and Lindsey (programmer) +are the team for the new PHOTCAL package. +.PP +For each project we maintain a project directory where all design +specifications, email, etc. for the project are kept. You are welcome +to browse this if you wish to know more about the details of the project. +In the case of RV, the project directory is /u2/fitz/iraf/rvproject on +tucana. All of the email exchanged by the team members during the package +design, or mail exchanged with scientists or other users, is saved in the +rvmail file in this directory. If you have detailed comments on any feature +of a package like RV, it is best to send them to one of the team members via +email so that they get logged for the rest of us to read. +.SH +RV Development Plans +.PP +Based upon your input in the RV review meeting a while back, we have come +up with the following plan for the next phase in the development of the +RV package. This plan is intended to serve our immediate needs for radial +velocity analysis as quickly as possible, while providing a fully featured +package in the longer term. +.RS +.IP \(bu +\fBLevel Zero Task\fR. This is intended to provide a basic radial +velocity capability, providing the most needed functions but avoiding +the more ambitious features planned for the eventual full IRAF +package. It is the specifications for the level zero task which are +enclosed for you to review and comment on. Once completed, the level +zero task will be frozen and will continue to be available +indefinitely, without change, providing a stable tool for basic radial +velocity analysis while development and testing of the full package +goes forward. Although the level zero task will provide limited +functionality, those algorithms and features provided are intended to +be about as good as can be done (please let us know if you think +otherwise!) and will have undergone lots of testing with real and +artificial data by the time the software is released. +.IP \(bu +\fBBaseline Package\fR. This will be more or less what Mike has in the +current prototype version of RV, most likely with many changes reflecting +what we learn from the level zero task. +.IP \(bu +\fBFull Package\fR. This will be a second version of the baseline release +adding all the desirable but lower priority functions. Many changes to the +baseline package are sure to be needed once user testing begins, and these +will be incorporated into the full package along with the remaining tasks +not planned for the baseline package. +.RE +.PP +In addition to the above, the current prototype RV package will continue +to be available for use while the new software is under development. +.PP +As you will see from the draft specifications prepared by Mike and +Frank, the level zero task provides fourier cross correlation for both +raw pixel arrays and wavelength calibrated data, including those +features we thought were necessary for even the level zero task for it +to be useful. These include automatic log-lambda mapping of the input +data, continuum fitting and subtraction, fourier filtering, weighting +of the correlation peak fit to minimize sampling errors, and optional +correction to heliocentric velocities. Important changes to the user +interface have also taken place. The database capabilities (RVSELECT) +have been left out, but will be provided in the baseline version of the +package (the lists.fields task can be used to make lists of selected +quantities from the output of the level zero task). Other important +but less essential functions such as the fourier quotient algorithm, +redshift and deredshift functions, etc., will also be deferred to the +baseline package. +.PP +Comments on our plans for further development of the package, or the +draft specifications for level zero, are most welcome. If you need +some feature in level zero which doesn't appear to be there, try to let +us know as soon as possible. diff --git a/noao/rv/doc/rvreidlines.hlp b/noao/rv/doc/rvreidlines.hlp new file mode 100644 index 00000000..763e813a --- /dev/null +++ b/noao/rv/doc/rvreidlines.hlp @@ -0,0 +1,405 @@ +.help rvreidlines Aug93 noao.rv +.ih +NAME +rvreidlines -- Reidentify spectral lines and measure velocities +.ih +USAGE +rvreidlines reference images +.ih +PARAMETERS +.ls reference +Spectrum with previously identified features to be used as reference for +other spectra. If there are multiple apertures, lines, or columns in the +image a master reference is defined by the \fIsection\fR parameter. +The other apertures, lines, or columns selected by \fIstep\fR are +reidentified if needed. +.le +.ls images +List of dispersion corrected spectral images in which the features in the +reference image are to be reidentified. In two and three dimensional +images the reidentifications are done by matching apertures, lines, +columns, or bands with those in the reference image. +.le +.ls interactive = no +Examine and fit features and velocities interactively? If the task is run +interactively a query (which may be turned off during execution) will be +given for each vector reidentified after printing the results of the +automatic determination and the user may chose to enter the interactive +\fBrvidlines\fR task. +.le +.ls section = "middle line" +If the reference image is not one dimensional or given as a one dimensional +image section then this parameter selects the master reference image +vector. The master reference is used when reidentifying other vectors in +the reference image or when other images contain apertures not present in +the reference image. This parameter also defines the direction +(columns, lines, or z) of the image vectors to be reidentified. + +The section parameter may be specified directly as an image section or +in one of the following forms + +.nf +line|column|x|y|z first|middle|last|# [first|middle|last|#]] +first|middle|last|# [first|middle|last|#] line|column|x|y|z +.fi + +where each field can be one of the strings separated by | except for # +which is an integer number. The field in [] is a second designator which +is used with 3D data. See the example section for \fBrvidlines\fR for +examples of this syntax. Abbreviations are allowed though beware that 'l' +is not a sufficient abbreviation. +.le +.ls newaps = yes +Reidentify new apertures in the images which are not in the reference +image? If no, only apertures found in the reference image will be +reidentified in the other images. If yes, the master reference spectrum +is used to reidentify features in the new aperture and then the +new aperture features will be added to the reference apertures. All +further identifications of the new aperture will then use this result. +.le +.ls override = no +Override previous solutions? If there are previous measurements for a +particular image vector being identified, because of a previous +\fBrvidlines\fR or \fBrvreidlines\fR, this parameter selects whether +to simply skip the reidentification or do a reidentification and +velocity measurement and overwrite the results in the logfile and database. +.le + +The following parameters are used for selecting and reidentifying additional +lines, columns, or apertures in two dimensional formats. +.ls trace = no +There are two methods for defining additional reference lines, columns, or +bands in two and three dimensional format images as selected by the +\fIstep\fR parameter. When \fItrace\fR is no the master reference line or +column is used for each new reference vector. When this parameter is yes +then as the reidentifications step across the image the last reidentified +features are used as the reference. This "tracing" is useful if there is a +coherent shift in the features such as with long slit spectra. However, +any features lost during the tracing will be lost for all subsequent lines +or columns while not using tracing always starts with the initial set of +reference features. +.le +.ls step = "10" +The step from the reference aperture, line, column, or band used for +selecting and/or reidentifying additional lines, columns, or bands in a two +or three dimensional reference image. For three dimensional images there +may be two numbers to allow independent steps along different axes. For +multiaperture images the step is typically 1 while for long slit or +Fabry-Perot images the step is large enough to map any significant changes +in the feature positions. If the step is zero then only the reference +line, column, or band is used. +.le +.ls nsum = "10" +Number of lines, columns, or bands across the designated vector axis to be +summed when the image is a two or three dimensional spatial spectrum. +It does not apply to multispec format spectra. If the image is three +dimensional an optional second number can be specified for the higher +dimensional axis (the first number applies to the lower axis number and +the second to the higher axis number). If a second number is not specified +the first number is used for both axes. +.le +.ls shift = "0" +Shift in user coordinates to be added to the reference features before +centering when stepping to other lines, columns, or bands in the reference +image. Generally no shift is used by setting the value to zero. +The shift is used as a slope with positive values increasing towards +larger line or column numbers. This parameter is not used for +reidentifications from the reference image to other images. +If the image is three dimensional then two numbers may be specified +for the two axes. +.le +.ls nlost = 0 +When reidentifying features by tracing, if the number of features not found +in the new image vector exceeds this number then the reidentification +record is not written to the logfile and database and the trace is terminated. A warning is printed in the log and in the verbose output. +.le + +The following parameters define the finding and recentering of features. +See also \fBcenter1d\fR and \fBrvidlines\fR. +.ls cradius = 5. +Centering radius in pixels. If a reidentified feature falls further +than this distance from the previous line or column when tracing or +from the reference feature position when reidentifying a new image +then the feature is not reidentified. +.le +.ls threshold = 10. +In order for a feature center to be determined, the range of pixel +intensities around the feature must exceed this threshold. This parameter +is used to exclude noise peaks and terminate tracing when the signal +disappears. However, failure to properly set this parameter, particularly +when the data values are very small due to normalization or flux +calibration, is a common error leading to failure of the task. +.le + +The following parameters select and control the automatic addition of +new features during reidentification. +.ls addfeatures = no +Add new features from a line list during each reidentification? If +yes then the following parameters are used. This function can be used +to compensate for lost features from the reference solution, particularly +when tracing. Care should be exercised that misidentified features +are not introduced. +.le +.ls coordlist = "" +User coordinate list consisting of an ordered list of rest spectral line +coordinates. +.le +.ls match = 10. +The maximum difference for a match between the feature coordinate function +value and a coordinate in the coordinate list (after correction by the +velocity). +.le +.ls maxfeatures = 50 +Maximum number of the strongest features to be selected automatically from +the coordinate list. +.le +.ls minsep = 2. +The minimum separation, in pixels, allowed between feature positions +when defining a new feature. +.le + +The following parameters determine the input and output of the task. +.ls database = "database" +Database containing the feature data for the reference image and in which +the features for the reidentified images are recorded. +.le +.ls logfiles = "logfile" +List of file in which to record the velocity results and to keep a +processing log. If a null file, "", is given then no log is kept. +.le +.ls verbose = no +Print reidentification and velocity information on the standard output? +.le +.ls keywpars = "" +The image header keyword translation table as described in +the \fIkeywpars\fR named pset. This defines the header keywords used +to obtain the observation information needed for computing the +heliocentric velocity. +.le +.ls graphics = "stdgraph" +Graphics device. The default is the standard graphics device which is +generally a graphics terminal. +.le +.ls cursor = "" +Cursor input file. If a cursor file is not given then the standard graphics +cursor is read. +.le +ADDTIONAL PARAMETERS +The measured velocities are corrected to a heliocentric frame of reference +if possible. This requires determining various parameters about the +observation. The latitude, longitude, and altitude of the observation +are determined from the observatory database. The observatory is +defined by either the OBSERVAT image header keyword or the "observatory" +package parameter in that order. See the help for \fBobservatory\fR +for additional information. + +The date, universal time, right ascension, declination, and coordinate epoch +for the observation are obtained from the image header. The keywords +for these parameters are defined in the \fBkeywpars\fR parameter set. +.ih +DESCRIPTION +\fBRvreidlines\fR takes spectral lines previously identified in a reference +image and recorded in a database and identifies them in other spectra and +determines a radial velocity. If the images are +two or three dimensional or multiaperture format and a \fIstep\fR greater +than zero is specified then additional vectors +(lines/columns/bands/apertures) in the reference image will be reidentified +from the initial master reference vector (as defined by an image section or +\fIsection\fR parameter) provided they have not been reidentified +previously or the \fIoverride\fR flag is set. For multiple aperture +spectra images, called multiaperture, the step size is typically 1; i.e. +reidentify features in all spectra. For two and three dimensional images, +such as long slit and Fabry-Perot spectra, the step(s) should be large enough +to minimize execution time and storage requirements but small enough to +follow shifts in the features (see the discussion below on tracing). The +set of reference identifications is applied to other images in the same +lines, columns, bands, or apertures. In multiaperture images the same +apertures are matched in the reference image regardless of actual line +order; i.e. the apertures need not be in the same order or even have all +apertures present. + +The reidentification of other features in other reference image vectors +may be done in two ways selected by the parameter \fItrace\fR. If not +tracing, the initial reference vector is applied to the other selected +vectors. If tracing, the reidentifications are made with respect to the +last set of identifications as successive steps away from the reference +vector are made. The tracing method is appropriate for two and three +dimensional spatial images, such as long slit and Fabry-Perot spectra, in +which the positions of features traced vary smoothly. This allows +following large displacements from the initial reference by using suitably +small steps. It has the disadvantage that features lost during the +reidentifications will not propagate (unless the \fIaddfeatures\fR option +is used). By not tracing, the original set of features is used for every +other vector in the reference image. + +When reidentifying other vectors in the reference image the parameter +\fBshift\fR may be used to add a shift(s) to the features positions +before recentering. The shift is added to lines, columns, or bands, greater +than the current line, column, or band and subtracted if less. If tracing +the shifts are the same from step to step while if not tracing the +shifts are added to the shifts from the previous step. Thus, in both +cases an approximation of a slope is used. This allows large +slopes in the features to be followed even when not tracing but the +shift value must be predetermined. + +When tracing, the parameter \fInlost\fR is used to terminate the +tracing whenever this number of features has been lost. This parameter, +in conjunction with the other centering parameters which define +when a feature is not found, may be useful for tracing features +which disappear before reaching the limits of the image. + +When reidentifying features in other images, the reference +features are those from the same aperture, line, column, or band of the +reference image. However, if the \fInewaps\fR parameter is set +apertures in multiaperture spectra which are not in the reference +image may be reidentified against the master reference aperture and +added to the list of aperture to be reidentified in other images. +This is useful when specta with different aperture numbers are +stored as one dimensional images. + +There are two centering algorithms; a flux bisecting algorithm called +\fBcenter1d\fR and a gaussian fitting algorithm. These algorithms +are described in the help for \fBrvidlines\fR. The algorithm used +and whether the feature is emission or absorption is the same one used +in the reference image. The only caveat is that multiple gaussian +fitting provided by the interactive 'b' key in \fBrvidlines\fR is +not done by this task and those lines will be fit by gaussians +independently. + +When recentering, if a feature position shifts by more than the +amount set by the parameter \fIcradius\fR from the starting position +(possibly after adding a shift) or the feature strength (peak to valley) is +less than the detection \fIthreshold\fR then the new feature is discarded. +The \fIcradius\fR parameter should be set large enough to find the correct +peak in the presence of any shifts but small enough to minimize incorrect +identifications. The \fIthreshold\fR parameter is used to eliminate +identifications with noise. Failure to set this parameter properly for the +data (say if data values are very small due to a calibration or +normalization operation) is the most common source of problems in using +this task. + +In two and three dimensional images, though not multiaperture images, the +number of lines, columns, or bands given by the parameter \fInsum\fR are summed +to form the one dimensional image vector in which the features are +identified. This increases the accuracy for reidentifying weak +features. + +If the parameter \fIaddfeatures\fR is set additional features may be added +after the initial reidentification and velocity determination using a line +list of rest wavelengths. A maximum number of added features, a matching +distance in user coordinates, and a minimum separation from other features +are additional parameters. This option is similar to that available in +\fBrvidlines\fR and is described more fully in the help for that task. + +A statistics line is generated for each reidentified vector. The line +contains the name of the image being reidentified (which for two +dimensional images includes the image section and for multiaperture +spectra includes the aperture number), the number of features found +relative to the number of features in the reference, the number of +features used in the velocity determination (currently there is +no rejection of lines) relative to the number found, the +mean pixel and user coordinate shfits relative to the reference +coordinates, and the measured velocity and RMS in the velocity. +The velocity is the heliocentric velocity if the necessary observation +information in the image and observatory database are found. + +If the task is run with the \fIinteractive\fR flag the statistics line +is printed to the standard output (the terminal) and a query is +made whether to fit the lines and measure the velocity interactively. +A response +of yes or YES will put the user in the interactive graphical mode +of \fBrvidlines\fR. See the description of this task for more +information. The idea is that one can monitor the statistics information, +particularly the velocity RMS, and select only those which may be +questionable to examine interactively. A response of no or NO will +continue on to the next spectrum. The capitalized responses +turn off the query and act as permanent response for all other +reidentifications. + +This statistics line, including headers, is written to any specified +log files. The log information includes the image being +reidentified and the reference image. +In addition the set of lines, the observatory information used, +and the computed observed and heliocentric velocities and redshifts +are recorded. This is the same information as is produced +by \fBrvidlines\fR. +.ih +DATABASE RECORDS +The database specified by the parameter \fIdatabase\fR is a directory of +simple text files. The text files have names beginning with 'id' followed +by the entry name, usually the name of the image. The database text files +consist of a number of records. A record begins with a line starting with the +keyword "begin". The rest of the line is the record identifier. Records +read and written by \fBrvreidlines\fR have "identify" as the first word of the +identifier. Following this is a name which may be specified following the +":read" or ":write" commands. If no name is specified then the image name +is used. For 1D spectra the database entry includes the aperture number +and so to read a solution from a aperture different than the current image +and aperture number must be specified. For 2D/3D images the entry name +has the 1D image section which is what is specified to read the entry. +The lines following the record identifier contain +the feature information and redshift (without heliocentric correction). + +The database files have the name "identify" and the prefix "id" because +these files may also be read by the \fBidentify\fR task for changing +the dispersion function based on the rest wavelengths. +.ih +EXAMPLES +1. To generate a rotation curve for a long slit spectrum of a +galaxy first use \fBrvidlines\fR to mark some lines at the center of the +galaxy. If the velocities are to be absolute then you give the rest +wavelengths and do a fit. However to get velocities relative to the center +use the measured wavelengths by simply accepting the prompted measured +wavelengths. Then run \fBrvreidlines\fR. The \fInsum\fR and \fIstep\fR +parameters allow controlling the summing size and spacing. + +.nf + rv> rvid lsgal sec="mid col" nsum=5 + Mark lines and then quit. + Write velocity data to the logfile (yes)? + Write feature data to the database (yes)? + rv> rvreid lsgal "" sec="mid col" nsum=5 step=5 trace+ v+ + + RVREIDLINES: NOAO/IRAF V2.10.3 valdes Sat 14:47:55 21-Aug-93 + Reference image = lsgal, New image = lsgal + Image Data Found Fit Pix Shift User Shift Velocity RMS + lsgal[45,*] 7/7 7/7 -0.0181 -0.0212 -1.37 11.3 + lsgal[40,*] 7/7 7/7 0.0147 0.0193 1.34 8.73 + lsgal[35,*] 7/7 7/7 0.0931 0.116 8.01 9.16 + lsgal[30,*] 7/7 7/7 -0.0224 -0.0265 -1.78 27.6 + lsgal[25,*] 7/7 7/7 0.0558 0.07 4.83 33.7 + lsgal[20,*] 7/7 7/7 -0.0317 -0.0379 -3.08 33.6 + lsgal[15,*] 5/7 5/5 0.015 0.0201 0.799 43.7 + lsgal[10,*] 7/7 7/7 0.395 0.489 33.7 54.9 + lsgal[5,*] 4/7 4/4 -1.22 -1.51 -106. 84.3 + lsgal[55,*] 7/7 7/7 0.014 0.0184 1.41 10.5 + lsgal[60,*] 7/7 7/7 -0.0897 -0.109 -7.59 7.21 + lsgal[65,*] 7/7 7/7 -0.0109 -0.0122 -0.957 10.9 + lsgal[70,*] 7/7 7/7 -0.074 -0.0902 -6.55 14.6 + lsgal[75,*] 7/7 7/7 -0.00203 -0.00136 0.227 54.3 + lsgal[80,*] 6/7 6/6 0.08 0.0997 6.66 96.7 + lsgal[85,*] 6/7 6/6 0.289 0.357 27.2 104. + lsgal[90,*] 6/7 6/6 0.459 0.568 40.5 33.2 + lsgal[95,*] 6/7 6/6 0.926 1.14 78.5 65.5 + lsgal[100,* 5/7 5/5 0.696 0.86 59.1 44.2 + rv> match Vobs logfile | fields "" 2,6,11 | \ + >>> graph point- mark=vebar szmark=-1 +.fi + +The last command extracts the Vobs results from the logfile using +\fBmatch\fR, the column number, velocity, and mean error are extract +using \fBfields\fR, and graphs the points with error bars. One +drawback to this method is that the nubmer of columns summed is +constant and so the signal-to-noise decreases with the galaxy light. +.ih +REVISIONS +.ls RVREIDLINES V2.11 +This task will now work in the units of the input spectra. +.le +.ls RVREIDLINES V2.10.3 +This task in new in the version. +.le +.ih +SEE ALSO +center1d, fxcor, keywpars, observatory, rvcorrect, rvidlines +.endhelp |