Runz Users Guide

Last revised: Dec 10 Scott Croom


Runz is the generic name for the redshift-fitting software originally written by WJS for determining redshifts in the 2df Galaxy Redshift Survey. It was built on earlier code using the cross-correlation method of Tonry & Davis. Further modifications have been made by WS (for application to 6dF), RDC (for use in the 2SLAQ survey) and SMC (for application to the Wigglez survey), as well as smaller contributions from a number of others. Please include this acknowledgement in any publication making use of runz: "This work makes use of the runz redshifting code developed by Will Sutherland, Will Saunders, Russell Cannon and Scott Croom".

The original version of the code ran on starlink NDF format data, but has now been converted to run on FITS format data. If you have NDF format data you wish to analyse with the latest version of runz then please convert it to FITS using the 2dfdr version of ndf2fits. The main code is written in Fortran 77 and is called crcor.f. It is run by a shell script called runz. The details on using runz discussed below refer to the apr07 version of the runz script and the 070416 version of the crcor program.


The code has the following dependencies:

Setting up runz

  1. Make a directory to put the code:
    cd /my/code/
    mkdir runz
    cd runz

  2. Unpack the runz distribution from the tar file:
    gunzip runz_linux_070416_scroom.tar.gz
    tar xvf runz_linux_070416_scroom.tar

  3. There will usually be a pre-compiled version, if so, skip to the section on usage. If you need to recompile then first enable starlink. The starlink libraries are only required for the PDA numerical algorithms, these should be replaced at some point.
    source /star/etc/login
    source /star/etc/cshrc

  4. Build the code:
    make crcor

Running runz

  1. First set the environmental variable RUNZ to the directory you put the code in, e.g.
    setenv RUNZ /my/code/runz/

  2. The way RUNZ works can be modified slightly for different projects. This is largely controlled by an environmental variable RUNZ_PROJECT. Currently the allowed values for this are 0, 1 or 2 for the generic, WiggleZ and LRG flavours. The default behaviour is for the generic version, so generally this variable does not need to be set. In some cases there are specific startup scripts that set these values (e.g. runz_wigglez).

  3. run the command with:
    this will give you the version and the different usage options. The usual mode is to run it passing a single argument which is a FITS file containing reduced spectra. e.g.:
    $RUNZ/runz r03f22s01_0611_BR.fits

There are several command line options that you can use:

runz <file>
Standard default interactive mode.
runz <file> -a
Automatic mode (no uder interaction)
runz <file> -q
Quick mode. Only manually intervene for questionable redshifts.
runz <listfile> -l
List mode. Input a list file of 1-D spectra.
runz <file> -s <number>
Single object mode. Input a fibre number to examine only a single object.
runz <file> -h
Helpful plots. Just produces the quality plots and then quits. The plots are written to a postscript file *

Some other functionality can be varied by editing variables in the runz script. For details see below.

Using runz

In the non-automatic modes, the first thing that runz will request is your initials. Next it will ask you what to do if it finds that there are previous output files for the current input FITS file.

Then runz will show some diagnostic plots (showing the absorption band correction, the mean S/N per pixel, the catalogue magnitude versus the fibre magnitude, and the difference between catalogue and fibre magnitudes as a function of position on the field) in the pgplot window. Press q with the cursor in the pgplot window to stop there. Any other key will go on to plot the templates (for iplot>2 - set this in the runz script - step through them with spacebar) and stop at the first galaxy spectrum.

For the objects, the upper plot is the noise-weighted cross-correlation function (white line), together with the 'prior' expected z-distribution for this template (green line). This prior is set (for non-qso,non-stellar templates) in the runz script. The vertical red line shows the position of the current best redshift and the red circle marks the best cross-correlation peak. the coloured asterisks show various possible emission line redshifts.

The lower plot is the galaxy spectrum (white line), error spectrum (green line), sky spectrum (yellow line - with a log scaling to better show a wide range of night sky emission lines) and the telluric absorption specrtrum (red line). Superimposed in this are emission (dotted cyan lines) and absorption (dotted green lines) features at the best automatic redshift (all the common features, whether actually detected in this spectrum or not). Also shown are the strongest of the night sky emission lines (dotted magenta lines).

Note: all user input is done on the graphics window; brief help appears in that window if you hit ?, and more details appear on the xterm. Prompts appear in red, and your input in green. The program estimates two z's for each spectrum: an `absorption-line' one, which is that from the template giving the highest R-value; and an `emission-line' one from fitting Gaussians and searching for a multi-line match, taking the `best' single line if no multi-line match is found. Originally, (as used for 2dFGRS), these were quasi-independent since em.lines were `clipped' before the cross-correlation. The qualities were then compared them and runz chose which it thought the better one. In the current version, the emission line-clipping is switched on/off by a flag in the templist template list file. This is currently set to clip emission lines from the galaxy templates which show the strongest emission lines.

The lower plot has a label showing object name, magnitude, redshift, quality and a set of flags which denote the following: Em means an emission line redshift; Xc means cross-correlation without e-line clipping; Abs is with clipping; an '*' after the redshift type means an insecure reshift, with another CC peak (whether in this or another template) with r-value within 1 of the best; E/X Disc means that there are reasonable emission and cross-correlation redshifts which are discrepant; M indicates a manual intervention.

The options available to use are listed below(? prints a summary on the xterm):

Redshift quality and assignment

Display help
Assign redshift quality and continue (see below for a detailed description)
Accept automatic quality
Select the emission line redshift
Input a redshift value directly (e.g. 0.123). Not very useful but there in case you need it, e.g. if someone else got a different z and you want to see why.
(also middle mouse button) Mark specific emission or absorption features in the spectrum and re-determine the redshift. After hitting m at the feature in question, hit another key to indicate which feature it is (see the terminal window for a list of options). The new redshift is then calculated. If this is followed by f, the program fits a set of common features using this redshift as an initial estimate and refining it from the fits. Hit u to update the redshift from the marked to the fitted value, and replot the spectrum.
As for "m" above, but automatically marks an [OII] 3727 line.
Reset the redshift (and template) to the automatic value.
Add a comment (up to 20 characters). Useful for noting peculiar objects or things where the extraction /data-reduction may have screwed up. Don't bother commenting stars because this is obvious from the z.
Add "QSO" as a comment.
Add "fringed" as a comment.
Fit expected features at the current redshift. Uses line wavelengths given in the fit_lines.txt file. After the fit, hit u to update the redshift to the fitted value, and replot the spectrum.
Other Emission line redshifts. Cycle through all possible emission line redshifts (starting with the most likely).
Cross-correlation commands

Determine the cross-correlation redshift
Use Emission lines in the cross-correlation (i.e. don't clip them)
Don't use emission lines in the cross-correlatrion (i.e. clip them)
Look for a peak in the cross-correlation function near the cursor.
Look for a peak in the cross-correlation function near the cursor for all templates.
Look for a peak in the cross-correlation function near the current redshift. Very useful after marking a feature.
Display commands

Smooth the spectrum with a Gaussian. The smoothing cycles though the following values of sigma 0,1,2,3,4,5. On reaching 5, the next step will be to go back to no smoothing (i.e. sigma=0). The current smoothing is displayed at the bottom right of the display. The default smoothing can be set in the runz script.
De-smooth the spectrum, reducing the width of the smoothing oy 1 sigma (reverse of 's' above).
(Also right mouse button) Replot the spectrum and cross-correlation function without changing the redshift and resets the plotting limits.
Line region plot. Plot a close up of various common emission line regions.
One panel. Only plot a single panel in the display rather than the usual two. This persists until the next r command.
Hard copy (postscript) of the spectrum and cross-correlation function.
Hard copy (postscript) of the spectrum only.
(Also left mouse button) Set the plotting limits for the spectrum (hit l again at opposite corner of the box you want).
Spectrum value at cursor position displayed in the terminal window.
Template commands
Plot current template at the current redshift.
Change template and recompute the cross-correlation redshift. Enter a number to select which template. The list of possible templates is written to the terminal.
galaxy and star templates only
QSO and star templates only
Navigation commands

Go back to the previous spectrum (redshifts have then to be re-estimated for all subsequent spectra).
Next spectrum (i.e. skip current object).
Jump to a specific spectrum number.
Quit (will ask for confirmation).
Mode ommands
Interactive mode.
Semi-automatic mode.
Full automatic mode.
Mouse driven commands
Set plotting limits for spectrum (same as l).
Mark specific emission or absorption line (same as m).
Replot spectrum with original limits (same as r)

What do the quality values mean?

Typing 0, 1, 2, 3, 4, 5, 6 or a assigns the currently-plotted redshift estimate to the spectrum, with the assigned quality, and goes onto the next spectrum.

Qualities 1-2 are considered failures, so the redshift completeness is the number of quality 3-4-5 redshifts divided by the total number of galaxies in the field.

Using the above options, step through all the spectra estimating redshifts and assigning quality flags.

Important files

There are a number of important extra files in the runz distribution which users should be aware of. These are


There are five files written out by the program:

The output for the .zlog and .rz files are appended to any previous versions if requested.

Parameters in the RUNZ script

There are a large number of variables set in the runz script which calls the main program. Most of these are internal variables that you should not need to worry about, however, there are a few that can be worth modifying in certain circumstances:

List mode

It is possible to use runz in a list mode, passing it a file containing a list of individual FITS spectra using the -l option above. The list file should have one FITS file name on each line. The default is that it assumes that the data is in extension [0] and the variance in extension [1], but this can be altered by giving the location in the list file in the following format:

The first 3 lines indicate the location of the data, variance and sky spectrum in the FITS files in extended FITS format (e.g. the values above indicate that all components are in extension 7 and the data, variance and sky are in rows 1, 2 and 3 respectively). If the plotim flag is set, then the code can also plot postage stamp images contained within these FITS files as well as the spectra.

Output .rz file format

The main output of the runz code is the .rz file which has a large number of columns. There is also a header which contains info about the file, the runz version, the user, date, heliocentric correction and a few other things. The individual columns are described in the table below. The most important are z_fin and qop which give the final redshift and the quality.
Col numberLabelDescription
1FibFibre number
2Object Object name given in .fld file when configuring
3RA RA hours
4 RA minutes
5 RA seconds
6dec Declination degrees
7 Declination arcminutes
8 Declination arcseconds
9Rmag Reference magnitude given in .fld file
10neb Number of emission lines in best emission line redshift
11neg Number of good potential emission lines found in spectrum
12ze Best emission line redshift
13ze_err Error in best emission line redshift
14qe Quality of best emission line redshift 0=no redshift, 2=one weak line, 3=one strong line, 4=two lines, 5=3 or more lines, 6=galactic emission
15temp Number of best cross-correlation template
16xcor Cross-correlation r value
17zx Best cross-correlation redshift
18zx_err Error on best cross-correlation redshift
19qx Quality of best cross-correlation redshift 1=no redshift, 2=redshift > 0, 3=r>3.5, 4=r>5, 5=r>7
20z_fin Best final redshift
21zf_err Error on best final redshift
22qa Best automatic final quality (chosen from qe or qx). Set to 0 if emission and cross-correlation redshifts do not agree
23qop Quality of best redshift given by user (see above)
24f Flag user modified redshift: 0=no change, 1=redshift not auto best redshift, 2=redshift not best emission or cross-correlation redshift
25fld Field name/number. Generally not used and set to 000
26date UT date from FITS header - may not be the date of last observation if taken over several nights
27ccd Detector identifier: 0=6df, 1=2dF Tek1, 2=2df Tek2, 3=AAOmega blue, 4=AAOmega red
28pl 2dF plate 0/1
29x_posn 2dF x position of fibre in microns
30y_posn 2dF y position of fibre in microns
31S/N Average S/N over spectrum
32spmag Spectrum magnitude summed over whole spectrum with arbitrary zero-point (=33.0): spmag=33.0-2.5*log(summed_counts)
33vsp V-band spectrum magnitude summed over 5150 to 5950A with arbitrary zero-point (=32.0): vsp=32.0-2.5*log(summed_counts)
34rsp R-band spectrum magnitude summed over 5950 to 6800A with arbitrary zero-point (=32.3): rsp=32.3-2.5*log(summed_counts)
35RA(deg) RA in decimal degrees
36dec(deg) Dec in decimal degrees
37...comments Redshifting comments (uses remaining columns)


For `marginal' redshifts, do not place too much reliance in a single strong feature because it could easily be a remaining CR, bad column, etc. Occasionally you have to play around by eye marking feeble features with `m', and see if you can get a couple of them to match. For the R-values, R < 3 is very likely noise, R > 5 is almost certainly right, and in between it's a sliding scale of plausibility. If you see a feeble emission line matching e.g. an R = 3.5 cross-correlation function, that is usually enough to give Q=4, because that is `independent' confirmation.

If you have a `marginal' Halpha line, check it against the sky and bands spectra at the bottom to assess the probability that it is genuine or an artefact of poor sky subtraction.

Problem solving

Will Sutherland, Will Saunders, Scott Croom,