Initial commit

1 files changed, 948 insertions, 0 deletions

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.