STScI Logo

xcsao



.help xcsao Jun 2005rvsao
.ih
NAME
xcsao -- Compute redshift using the cross-correlation technique
.ih
USAGE
xcsao spectra
.ih
PARAMETERS
.ls spectra = ""
List of file names of spectra to analyze.
@<filename> indicates list should come from file <filename>.
<filename>[<range>] indicates that a range of apertures in a multispec
file should be processed, where <range> is a comma- and/or
hyphen-separated list of numbers.
.le
.ls specnum = 0
If this is nonzero and \fIspectra\fR contains a single file name, this is
a range of spectrum numbers in a multispec file which will be cross-
correlated.  For each spectrum number, n, wavelength dispersion information
is read from APNUMn, and velocity information is read from APVELn and saved
in APVELn and APVXCn, the values of which contain multiple values.  If
specnum is zero, velocity information is in separate keywords for each value.
.le
.ls specdir = "./"
Directory containing spectra to analyze.
.le
.ls correlate = yes
If "yes" or "velocity", cross-correlate object spectrum against specified
template spectrum in log wavelength, displaying spectrum, correlation
peak (if display mode 1), and detailed results for the best 12 templates.
If "wavelength", cross-correlate object spectrum against specified template
spectrum in wavelength, displaying spectrum, correlation peak (if display
mode 1), and detailed results for the best 12 templates.
If "pixel", cross-correlate object spectrum against specified template
spectrum in pixels, displaying the  spectrum, correlation peak (if display
mode 1), and detailed results for the best 12 templates.
If "no", display spectrum with previous results read from the spectrum image
header with no correlation peak plot.  If the spectrum is recorrelated,
it is processed in log wavelength, and "velocity" is assumed.
.le
.ls templates = ""
Template file or comma-separated list of file names of images to use as
templates or name of file containing template file names, one per line.
Apertures of multispec template files can be entered as numbers, lists,
or ranges enclosed in brackets after each file name in the list or file.
Wavelength (or pixel) ranges of templates to be correlated can be specified
by appending :w1-w2 (:p1-p2) to the template name. Multiple pieces of a
single template spectrum can thus be correlated agains multiple pieces of
an object spectrum.
.le
.ls tempnum = 0
If nonzero and \fItemplates\fR contains a single file name, this is a range
of spectrum numbers in a multispec file to be used as templates.
Wavelength dispersion information is read from APNUMn, and velocity
information is read from APVELn.
.le
.ls tempdir = ""
Directory for template spectra
.le
.ls echelle = no
If yes, the spectrum is assumed to be a multispec file containing
multiple orders.  The range of spectrum numbers (which may not have the
same numbers as the echelle orders) defined by \fIspecnum\fR is used
for the template rather than the range defined in \fItempnum\fR.
.le
.ls st_lambda = INDEF
Starting wavelength in angstroms of portion of spectrum to correlate.
If INDEF, use beginning of wavelength overlap between template and
spectrum.
.le
.ls end_lambda = INDEF
Ending wavelength in angstroms of portion of spectrum to correlate.
If INDEF, use end of wavelength overlap between template and spectrum.
.le
.ls obj_plot = yes
If yes, a plot of the object spectrum is displayed.  During this time the
normal IRAF cursor commands are active as well as several more that are
itemized below.A  If emission lines are chopped, before and after plots
are displayed, as well as the chopped line(s).
.le
.ls xcor_plot = yes
If yes, a plot of the filtered cross-correlation function is displayed.
Cursor commands are activated, and a peak other than the maximum
can be chosen to be the center with the keystroke \fIp\fR.  Hard copies 
to stdplot may also be made using the \fI@\fR command.
.le
.ls xcor_file = yes
If yes, files are written containing the filtered cross-correlation function
for each object/template pair.  The name of each file is
\fIobject\fR.\fItemplate\fR, and there is one line of header containing
the object and template names and the Julian date of the observation.
The correlation is listed in ASCII format over the range specified by the
\fIcvel\fR and \fIdvel\fR parameters as \fIvelocity correlation\fR pairs.
.le
.ls s_emchop = "no"
Chop out emission lines from object spectrum before cross-correlating with
template if "yes".  If "tempfile", emission lines are removed if the value
of the CHOPEM keyword in the template image header is T.  If the keyword is
not present or is F, emission lines are not removed.  If "specfile", emission
lines are removed if the value of the CHOPEM keyword in the object spectrum
image header is T.  If the keyword is not present or is F, emission lines
are not removed.  If "no", emission lines are never removed.  If EMCHOP
in the object spectrum file is 1, emission lines are never removed.
.le
.ls t_emchop = "no"
Chop out emission lines from template spectrum before cross-correlating
with object if "yes".  If "tempfile", emission lines are removed if the
value of the CHOPEM keyword in the template image header is T.  If the
keyword is not present or is F, emission lines are not removed.  If "specfile",
emission lines are removed if the value of the CHOPEM keyword in the object
spectrum image header is T.  If the keyword is not present or is F, emission
lines are not removed.  If "no", emission lines are never removed.  If EMCHOP
in the template spectrum file is 1, emission lines are never removed.
.le
.ls s_abs_reject 100.
Spectrum absorption line rejection in sigma of fit (0=no rejection)
.le
.ls s_em_reject 2.
Spectrum emission line rejection in sigma of fit (0=no rejection)
.le
.ls t_abs_reject 0.
Template absorption line rejection in sigma of fit (0=no rejection)
.le
.ls t_em_reject 0.
Template emission line rejection in sigma of fit (0=no rejection)
.le
.ls bell_window = 0.05
A fraction bell_window of the ends of the object and template spectrum are
multiplied by a cosine bell.  This is to reduce high wave number Fourier
components that would be produced by abrupt cutoffs at the ends of the spectra.
.le
.ls renormalize = no
If yes, renormalize spectrum before crosscorrelating by multiplying each pixel
by 1000 times the mean pixel value for the spectrum.  Set this to "yes" for
fluxed spectra.  If set to "no" and all values of the object spectrum are
less than 1, the spectrum is renormalized anyway, to avoid crashing the
program.
.le
.ls ncols = 2048
Number of columns into which to rebin data before transforming, must be
a power of two between 256 and 8192.
.le
.ls interp_mode = "spline3"
Interpolation mode to use when rebinning spectra, must be
"linear" or "spline3" or "poly3" or "poly5" or "sums".
.le
.ls fixbad = no
If yes, replace portions of spectrum given in file \fIbadlines\fR with
a straight line linking the adjacent points.  This feature can be used
to eliminate emission and absorption features caused by poor removal of
night sky emission lines. (added in version 2.0)
.le
.ls badlines = "badlines.dat"
File containing list of starting and stopping wavelengths in Angstroms for
removal of portions of all object spectra.  All information after the
second wavelength is a comment field. This file is assumed to be in the
directory \fIlinedir\fR unless a complete pathname starting with "/" is
specified.(added in version 2.0)
.le
.ls zero_pad = no
If yes, pad Fourier transforms of both object and template spectra with
an equal amount of zeroes to avoid wrap-around correlations.  This usually
gives better results, but the option of turning it off has been
kept to allow comparison of results with older versions of XCSAO.
*If zero_pad=yes, double low_bin, top_low, top_nrun, and nrun.
.le
.ls low_bin = 5, top_low = 10, top_nrun = 80, nrun = 140
The Fourier amplitudes are multiplied by a cosine-bell filter function,
starting at \fIlow_bin\fR and running to \fInrun\fR.
Values chosen for low_bin and nrun are not critical.  Generally low_bin
should be about 5 to 10 for a 1024 point spectrum of 2-4 pixel resolution.
Set nrun based upon the number of points in your spectrum and the resolution.
For a spectrum of NPTS pixels and resolution FWHM,
nrun ~ NPTS / (2*PI * FWHM/2.355).  See Tonry and Davis 1979, A.J., 84,
1511.
.le
.ls vel_init = zero
Make an inital velocity guess.  It is used to shift the template in
wavelength to give a better overlap region.The options are: "zero" to
use no initial velocity, "guess" to use \fIczguess\fR, "correlation"
to use the correlation velocity in the spectrum header parameter CZXC,
"emission" to use the emission line velocity in the spectrum header
parameter CZEM, and "combination" to use the velocity in the spectrum header
parameter VELOCITY. 
.le
.ls czguess = 0
Velocity in km/sec used as an initial guess if \fIczinit\fR is yes.
.le
.ls nzpass = 0
Number of iterations shifting the template to match features with the
spectrum.  Zero and one both give one pass through.
.le
.ls tshift = 0.
Night to night velocity zero point shift.  If this is zero, each template
spectrum header is checked for a TSHIFT parameter, and that is used if
present.
.le
.ls svel_corr = "file"
Spectrum velocity correction to the solar system barycenter.  Set to
"none" if spectrum has already been shifted or if this correction is
unnecessary.  If "file", \fIBCV\fR is used if present in the file header,
or else \fIHCV\fR.  If "hfile", the header parameter \fIHCV\fR is always
used.  If neither is found, no correction is made.  If "heliocentric"
or "barycentric" corrections are chosen, position and time parameters
are read from the spectrum data file header.  \fIDATE-OBS\fR (date in
format 'dd-mm-yy') \fIUT\fR (U.T. at end of exposure as 'hh:mm:ss')
and \fIUTOPEN\fR (U.T. at start of exposure as 'hh:mm:ss') or
\fIEXPOSURE\fR (length of exposure in seconds) are used to compute
the midtime of the exposure.  \fIRA\fR (right ascension as 'hh:mm:ss.ss'),
\fIDEC\fR (declination as 'dd:mm:ss.ss'), and \fIEPOCH\fR (epoch of
coordinates defaults to 1950.0) give the position of the object whose
spectrum this is.  \fISITELONG\fR (observatory longitude as 'dd:mm:ss.ss'
or degrees), \fISITELAT\fR (observatory latitude as 'dd:mm:ss.ss' or
degrees), and \fISITEELEV\fR (observatory altitude in meters) give the
observatory position.
.le
.ls tvel_corr = "file"
Template velocity correction.  Set to "none" if template is already
corrected to "heliocentric", else "heliocentric", "barycentric", or
"file".  If "file", BCV is used if present in header, else HCV.
VELOCITY in the template file header is assumed to be the barycentric
corrected velocity.  If the spectrum is unshifted, this correction must
be made; if the spectrum has been shifted, this should be "none" and the
BCV parameter in the template header should be 0.  If "barycentric" or
"heliocentric", the same parameters as above must be present in the template
file header.
.le
.ls pkmode = 1
Flag for peak fitting: 0=parabola, 1=quartic, 3=cos/(1+x^2), 0=all three
.le
.ls pkfrac = 0.5
Fraction of peak or number of points for peak fitting.
If \fIpkfrac\fR is negated, the points used in the fit will be marked.
(option added in 1.8)
.le
.ls pksrch = 25
When a correlation peak is manually selected, the position used as the peak
is the maximum correlation value within this many bins of the cursor-selected
bin.
.le
.ls minvel = -1000.
Minimum allowable correlation peak velocity shift in km/sec.
.le
.ls maxvel = 100000.
Maximum allowable correlation peak velocity shift in km/sec.
.le
.ls report_mode = 1
Mode in which results of fit are reported.
.ls =1  commented text
.le
.ls =2  one line per spectrum-template combination.
Includes filenames, R, velocity and error in km/sec, and height and
width of correlation peak.
.le
.ls =3 one line per spectrum giving best fit and previous results
Previous results are read from the image header and written alternately
with new results: file, old R, new R, old velocity, new velocity, old
error, new error, Julian date of observation, and name of best
template.
.le
.ls =4  one line per spectrum-template combination.
Includes filenames, R value, velocity, and error.
.le
.ls =5  one long line per spectrum-template combination.
Includes 4 filter parameters, template file name, tshift from template
header, spectrum filename, velocity, R value, peak height and width, and
heliocentric velocity correction.
.le
.ls =6 One long line per spectrum-template combination, including
spectrum and template names, Julian date, velocity,
error, R-value, correlation peak height and width, and velocity
correction to solar system barycenter 
.le
.ls =7 one long line per spectrum-template combination, including
per template results from current correlation and from previous
correlation as saved in the spectrum header. Includes filename,
old and new R-vaule, old and new velocity, old and new error, old
and new peak height, old and new ARMS, Julian date of observation,
and old and new template names. 
.le
.ls =8 one long line per spectrum combination, including spectrum
filename, instrument code, object name, Julian date of observation,
emission line velocity and error, correlation velocity, error, and
R-value, number of emission lines found and fit, and the name of the
template giving the highest R-value. 
.le
.ls =9 one long line per spectrum-template combination, including
observatory code, spectrum filename, template filename, Julian date
of observation, velocity, error, and R-value, correlation peak height
and width, barycentric velocity correction.  The sigma of
the spectrum transform, sigma of the template transform, and name of
the file containing the correlation vector for this spectrum-template
combination are added to the end of the line if such a file is written.
.le
.ls =10 one long line per spectrum, including spectrum filename, Julian
date of observation, number of best template in list, name of best
template, velocity, error, and R-value for best, and each template. 
.ls =11 one long line per spectrum, including spectrum filename, Julian
date of observation, number of best template in list, filename, velocity,
error, and R-value for best template, filename, velocity, error, and
R-value for each template. 
.le
.ls =12  one long line per spectrum, including spectrum filename,
Julian date of observation, number of best template in list, and
filename, velocity, error, and R-value for each template.
.le
.ls =13  one long line per spectrum-template combination, including
observatory code, spectrum filename, template filename, Julian date of
observation, velocity (from the searched, not fit, peak), peak height
and width, barycentric velocity correction.  The sigma of the spectrum
transform, sigma of the template transform, and name of the file
containing the correlation vector for this spectrum-template combination
are added to the end of the line if such a file is written.
.le
.le
.ls logfiles = "STDOUT,xcsao.log"
All results from XCOR are recorded in these files.
.le
.ls save_vel = no
If yes, save emission line velocity and error in IRAF image header as CZXC and
CZXCERR, and R-value as CZXCR (or APVELn and APVXCn if a multispec file).
.le
.ls archive = no
If yes, save emission line results in SAO TDC archive records in the current
directory.
.le
.ls nsmooth = 0
If >0, the data spectrum is smoothed \fIsmooth\fR times for the final
one-page display.  The spectrum is NEVER smoothed for the correlation.
.le
.ls cvel = INDEF
Center velocity of the summary velocity correlation graph in km/sec.
This defaults to the velocity from the cross-correlation with the
highest R value.
.le
.ls dvel = INDEF
Velocity half-width of the summary velocity correlation graph in km/sec.
This defaults to 20 times the width of the peak of the cross-correlation
with the highest R value.
.le
.ls ablines = "ablines.dat"
Name of file containing an absorption line list.  It is used if the "l"
cursor option is selected to label absorption lines.  Each line has
.br
        Center wavelength of line in angstroms
.br
        Name of line (terminated by end of line or space)
.le
.ls emlines = "emlines.dat"
Name of file containing an absorption line list.  It is used if the "l"
cursor option is selected and the "e" cursor command is used to identify
an emission line in the spectrum.  If the filename is preceded by a "+",
emission lines are always labelled.  Each line contains:
.br
        Center wavelength of line in angstroms
.br
        Starting wavelength in angstroms for continuum for this line
.br
        Ending wavelength in angstroms for continuum for this line
.br
        Half-width in angstroms for region to fit for this line
.br
        Name of line (terminated by end of line or space)

.le
.ls linedir = rvsao$lib/
Directory for emission and absorption information files.  If the name of
one of the individual files containis "/" or "$", it is assumed to be a
full path name, and \fIlinedir\fR is not used.
.le
.ls dispmode = 1
Display modes 
.ls =1 Display spectrum and cross-correlation with template information.
.le
.ls =-1 Display spectrum, plotted from 0, and cross-correlation with
template information.
.le
.ls =2 Display spectrum with absorption and known emission lines labelled
and tables of template and emission line information.
.le
.ls =3 Display spectrum with absorption and known emission lines labelled
using the entire display without the table of results
.le
.ls =4 Display continuum-subtracted spectrum with absorption and known
emission lines labelled and tables of template and emission line information.
.le
.ls =5 Display continuum-subtracted spectrum with absorption and known
emission lines labelled using the entire display without the table of results.
.le
.le
.ls displot = yes
Display graphic summary of results on an interactive display \fIdevice\fR.
.le
.ls device = "stdgraph"
Interactive device on which to display a graphic summary of XCSAO's results.
.le
.ls curmode = no
If yes, wait in cursor mode after each spectrum is processed.  Cursor
mode commands may be listed by typing "?".
.le
.ls hardcopy = yes
Display graphic summary of results on \fIplotter\fR.
.le
.ls plotter = "stdplot"
Second, non-interactive device on which to plot the graphic summary of results.
.le
.ls contsub_plot = yes
If yes, plots of the continuum-subtracted object and template spectra are
displayed.  This is most useful for determining the appropriateness of
the order of the polynomial chosen to fit the continuum.
.le
.ls apodize_plot = yes
If yes, plots of the windowed object and template spectra are displayed.
This is most useful for determining the size of the cosine bell window
applied to either end of the spectrum.
.le
.ls fft_plot = yes
If yes, the power spectrum of the transformed object data is displayed.
This is useful for setting the low order cutoff for the fits and for seeing
if any periodic noise is present in the data.
.ls uxcor_plot = yes
If yes, the unfiltered cross-correlation data is plotted.
.le
.ls phase_plot = yes
If yes, the phase of the cross-correlation function is plotted.
.le
.ls debug = no
If yes, values of the parameters fit to the selected peak
are recorded in the log files.  This is most useful for debugging.
.le
.ls nsum = 1
Number of pixels to sum across dispersion.
.le
.ls cursor = ""
Graphics cursor input.  When null the standard cursor is used otherwise
the specified file is used.
.le
 
.ih
DESCRIPTION
XCSAO provides an interactive facility to determine redshifts and
velocity dispersions using the Cross-correlation Technique (e.g.,
Tonry and Davis 1979, A.J., 84, 1511).
 
In brief, the cross-correlation technique assumes that a galaxy spectrum is
simply the convolution of a stellar spectrum with a Gaussian which describes
the line of sight velocity dispersion of the galaxy's constituent stars.
Cross-correlating a template spectrum with the galaxy spectrum then produces
a function with a peak at the redshift of the galaxy with a width related to
the dispersion of the galaxy.  Peaks in the cross-correlation function are
identified and fit by parabolas to obtain their position and width and hence
the redshift and velocity dispersion of the galaxy.

The templates are read separately for each object.  The wavelength scale
may be linear or logarithmic; if it is linear, the data will be rebinned
to a logarythmic scale.  It is specified in the header by the starting
log or linear wavelength (W0, CRVAL1, or APNUMn) and the delta log or
linear wavelength per pixel (WPC, CDELT1 or APNUMn).
The dispersion must run along axis 1 of the image.  The templates should
have the keyword VELOCITY or APVELn in their headers.  This specifies the
CORRECTED velocity (km/sec, + => receding) for the observation.  The
\fItvel_corr\fR parameter tells whether and how this heliocentric velocity
was corrected from an observed velocity.  If VELOCITY is not found, it
is assumed to be zero.  If the templates have a TSHIFT parameter and
\fItshift\fR is zero, that velocity is added to the template velocity.

The objects are read one at a time.  Each object-template combination
is rebinned in log-lambda to the designated (power of two) number of points
over the overlapping wavelength region.  Continua are fit to these rebinned
log-wavelength spectra using the IRAF interactive curve fitting software, with
optional emission line removal.  Parameters for these continuum fits are
set using the \fIcontpars\fR pset.  Acceptance limits in sigma can be
set for both absorption and emission features for the continuum fit and
point removal for both object and template spectra.  The spectra are then
optionally renormalized to the average value of the spectrum.  The ends of
the spectra are windowed by a cosine bell to suppress high frequency noise.

The object and template are filtered in Fourier space and multiplied together
to form the transform of the cross-correlation function.  This is transformed
back into real space.  The largest peak is found and fit by a parabola, quartic,
or function of the form cos(x)/(1+x^2).  The fitted parameters are saved, and a
summary output is produced for each object.  In this summary, the redshift is
corrected for the velocity of the template star.  The redshift is given as
cz in km/sec.  The quoted errors are one sigma on each parameter.

.ih
CURSOR
The following keystrokes are active for intermediate spectrum and
cross-correlation plots in addition to the normal IRAF cursor
facilities (a list of those is available with the command ":.help"):

.ls @
Make a hard copy on the device designated by \fIplotter\fR.
.le
.ls d
Replaces a region between the marked vertical cursors with interpolated
values from the edges of the marked region.  This is typically used to
eliminate poorly subtracted night sky lines or emission lines.
.le
.ls n
Smooth spectrum n times before plotting.  This only affects the current
spectrum display and the final spectrum graph, not the spectrum data.
.le
.ls p
Forces the current vertical cursor location to be chosen as the peak in the
cross-correlation function which is used to obtain the redshift and dispersion.
The maximum within 25 pixels of the cursor is actually used.
.le
.ls q
Quit and exit.
.le
.ls r
Forces a replot of the current spectrum at the original scale.
.le
.ls u
Redisplay the entire plot after zooming.
.le
.ls z
Zoom in on the region marked by two successive <z>'s
.le

The following keystrokes are active for the final plot in addition to
the normal IRAF cursor facilities (list available with the command ":.help"):
.ls c
Reset correlation peak fitting function and fraction to fit. (1.7)
.le
.ls f
Change transform filter parameters. (1.7)
.le
.ls g
Smooth spectrum n times before plotting.  This only affects the current
spectrum display and the final spectrum graph, not the spectrum data.  (1.8)
.le
.ls j
Set quality flag to conditional (1.8)
.le
.ls l
Plot spectrum with absorption lines labelled.  Label emission lines
if the R-value for an emission line template (emission lines not
chopped) is > 5 or if they have already been fit by EMSAO.
(\fIdispmode\fR=2)
.le
.ls n
Set quality flag to unacceptable. (1.8)
.le
.ls p
Rerun cross-correlation, stopping in the filtered cross-correlation
plot to select a peak other than the highest one.
.ls u
Unzoom the spectrum graph if using display mode 2 (1.8)
.le
.le
.ls v
Change the velocity limits within which a correlation peak is allowed. (1.7)
.le
.ls x
Plot the spectrum, without line labels, and the cross-correlation on
the same page.  (\fIdispmode\fR=1)
.le
.ls y
Set quality flag in header to yes. (1.8)
.le
.ls z
Zoom in on the spectrum graph between two cursor clicks if using
display mode 2.  (1.8)
.le

.ih
EXAMPLES
To obtain the redshift and dispersion of a single galaxy

        cl> xcsao galaxy templates=template

To obtain redshifts for a whole night's worth of galaxy spectra using 5
different templates:

        cl> xcsao @nite1.ls templates=@temp.ls

where the file temp.ls contains the names of the 5 template images and the
file nite1.ls contains the name of the galaxy images.
.ih
SEE ALSO
On-line help is available on the World Wide Web at
http://tdc-www.harvard.edu/iraf/rvsao/xcsao
.endhelp

Source Code · Search Form · STSDAS