pxcsao: Cross-correlate spectra with templates and save results as parameters

Package: rvsao

Usage

pxcsao spectra

Parameters

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.

specnum = 0: If this is nonzero and spectra 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.

specband = 0: Spectrum band if multispec file

specext = 0: FITS extension containing the spectrum

specdir = "./": Directory containing spectra to analyze.

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.

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.

tempnum = 0: If nonzero and templates 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.

tempband = 1: Template band if template is multispec file

tempdir = "": Directory for template spectra

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 specnum is used for the template rather than the range defined in tempnum.

st_lambda = INDEF: Starting wavelength in angstroms of portion of spectrum to correlate. If INDEF, use beginning of wavelength overlap between template and spectrum.

end_lambda = INDEF: Ending wavelength in angstroms of portion of spectrum to correlate. If INDEF, use end of wavelength overlap between template and spectrum.

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).

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 p. Hard copies to stdplot may also be made using the @ command.

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 object.template, 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 cvel and dvel parameters as velocity correlation pairs.

fixbad = no: If yes, replace portions of spectrum given in file badlines 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)

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 linedir unless a complete pathname starting with "/" is specified.(added in version 2.0)

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.

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.

s_abs_reject 100.: Spectrum absorption line rejection in sigma of fit (0=no rejection)

s_em_reject 2.: Spectrum emission line rejection in sigma of fit (0=no rejection)

t_abs_reject 0.: Template absorption line rejection in sigma of fit (0=no rejection)

t_em_reject 0.: Template emission line rejection in sigma of fit (0=no rejection)

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.

renormalize = no: If yes, the data spectrum is divided by its mean value before being transformed. The minimum value (divided by the mean first) is then subtracted, and the whole thing is multiplied by an arbitrary factor of 1000.0 to put it within normal count levels. This is used on spectra which may have unusual values if they have already been flux-calibrated.

ncols = 2048: Number of columns into which to rebin data before transforming, must be a power of two between 256 and 8192.

interp_mode = "spline3": Interpolation mode to use when rebinning spectra, must be "linear" or "spline3" or "poly3" or "poly5" or "sums".

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.

low_bin = 5, top_low = 10, top_nrun = 80, nrun = 140: The Fourier amplitudes are multiplied by a cosine-bell filter function, starting at low_bin and running to nrun. 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.

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 czguess, "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.

czguess = 0: Velocity in km/sec used as an initial guess if czinit is yes.

nzpass = 0: Number of iterations shifting the template to match features with the spectrum. Zero and one both give one pass through.

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.

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", BCV is used if present in the file header, or else HCV. If "hfile", the header parameter HCV 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. DATE-OBS (date in format 'dd-mm-yy') UT (U.T. at end of exposure as 'hh:mm:ss') and UTOPEN (U.T. at start of exposure as 'hh:mm:ss') or /fIEXPTIME/fR/EXPOSURE (length of exposure in seconds) are used to compute the midtime of the exposure. RA (right ascension as 'hh:mm:ss.ss'), DEC (declination as 'dd:mm:ss.ss'), and EPOCH (epoch of coordinates defaults to 1950.0) give the position of the object whose spectrum this is. SITELONG (observatory longitude as 'dd:mm:ss.ss' or degrees), SITELAT (observatory latitude as 'dd:mm:ss.ss' or degrees), and SITEELEV (observatory altitude in meters) give the observatory position.

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.

pkmode = 1: Flag for peak fitting: 0=parabola, 1=quartic, 3=cos/(1+x^2), 0=all three

pkfrac = 0.5: Fraction of peak or number of points for peak fitting. If pkfrac is negated, the points used in the fit will be marked. (option added in 1.8)

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.

minvel = -1000.: Minimum allowable correlation peak velocity shift in km/sec.

maxvel = 100000.: Maximum allowable correlation peak velocity shift in km/sec.

report_mode = 1

Mode in which results of fit are reported.

=1 commented text

=2 one line per spectrum-template combination.: Includes filenames, R, velocity and error in km/sec, and height and width of correlation peak.

=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.

=4 one line per spectrum-template combination.: Includes filenames, R value, velocity, and error.

=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.

=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

=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.

=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.

=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.

=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.

=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.

=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.

=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.

=14 one long line per spectrum, including spectrum filename, Julian: date of observation, emission line velocity, error, number of lines found, and number of lines fit, number and name of best template in list, and filename, velocity, error, and R-value for each template. (mode added in version 2.0)

=15 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. It is like mode 6, but with 2 more template name characters and velocities to m/sec. (mode added in version 2.0.1)

=16 one line per spectrum-template combination, including spectrum and: template names (24 and 16 characters, respectively), R-value, radial velocity and error in km/sec, height of correlation peak, template wavelength limits, and center wavelength of correlated template spectrum. This is used with wide synthetic templates of which only portions are used.

=17 one line per spectrum-template combination for Hectochelle, including: aperture, fiber, beam, 24-character spectrum name, last 24 characters of template name, heliocentric Julian Day, radial velocity, velocity error, R-value, correlation peak height and width, and barycentric velocity correction.

logfiles = "STDOUT,xcsao.log": All results from XCOR are recorded in these files.

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).

rvcheck = no: Enable header update if not correlate=no (yes or no)

archive = no: If yes, save emission line results in SAO TDC archive records in the current directory.

nsmooth = 0: If >0, the data spectrum is smoothed smooth times for the final one-page display. The spectrum is NEVER smoothed for the correlation.

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.

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.

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
Center wavelength of line in angstroms
Name of line (terminated by end of line or space)

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:
Center wavelength of line in angstroms
Starting wavelength in angstroms for continuum for this line
Ending wavelength in angstroms for continuum for this line
Half-width in angstroms for region to fit for this line
Name of line (terminated by end of line or space)

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 linedir is not used.

dispmode = 1

Display modes

=1 Display spectrum and cross-correlation with template information.

=-1 Display spectrum, plotted from 0, and cross-correlation with: template information.

=2 Display spectrum with absorption and known emission lines labelled: and tables of template and emission line information.

=3 Display spectrum with absorption and known emission lines labelled: using the entire display without the table of results

=4 Display continuum-subtracted spectrum with absorption and known: emission lines labelled and tables of template and emission line information.

=5 Display continuum-subtracted spectrum with absorption and known: emission lines labelled using the entire display without the table of results.

displot = yes: Display graphic summary of results on an interactive display device.

device = "stdgraph": Interactive device on which to display a graphic summary of XCSAO's results.

curmode = no: If yes, wait in cursor mode after each spectrum is processed. Cursor mode commands may be listed by typing "?".

hardcopy = yes: Display graphic summary of results on plotter.

plotter = "stdplot": Second, non-interactive device on which to plot the graphic summary of results.

besttemp = "": Best template (returned from last cross-correlated spectrum)

velocity = 0.: Velocity for best template (returned from last cross-correlated spectrum)

velerr = 0.: Velocity error for best template (returned from last cross-correlated spectrum)

r = 0.: R-value for best template (returned from last cross-correlated spectrum)

temp_plot = no: Plot the template spectra

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.

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.

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.

uxcor_plot = yes: If yes, the unfiltered cross-correlation data is plotted.

phase_plot = yes: If yes, the phase of the cross-correlation function is plotted.

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.

nsum = 1: Number of pixels to sum across dispersion.

cursor = "": Graphics cursor input. When null the standard cursor is used otherwise the specified file is used.

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 tvel_corr 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 tshift 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 contpars 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.

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"):

@: Make a hard copy on the device designated by plotter.

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.

n: Smooth spectrum n times before plotting. This only affects the current spectrum display and the final spectrum graph, not the spectrum data.

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.

q: Quit and exit.

r: Forces a replot of the current spectrum at the original scale.

u: Redisplay the entire plot after zooming.

z: Zoom in on the region marked by two successive <z>'s

The following keystrokes are active for the final plot in addition to the normal IRAF cursor facilities (list available with the command ":.help"):

c: Reset correlation peak fitting function and fraction to fit. (1.7)

f: Change transform filter parameters. (1.7)

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)

j: Set quality flag to conditional (1.8)

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. (dispmode=2)

n: Set quality flag to unacceptable. (1.8)

p

Rerun cross-correlation, stopping in the filtered cross-correlation plot to select a peak other than the highest one.

u: Unzoom the spectrum graph if using display mode 2 (1.8)

v: Change the velocity limits within which a correlation peak is allowed. (1.7)

x: Plot the spectrum, without line labels, and the cross-correlation on the same page. (dispmode=1)

y: Set quality flag in header to yes. (1.8)

z: Zoom in on the spectrum graph between two cursor clicks if using display mode 2. (1.8)

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.