---

Runz Users Guide

---

Introduction

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.

Dependencies

• PGPLOT - can be either the standalone or starlink version. This is required for both building and running. You may need to set some PGPLOT evironmental variables to get this working properly (see below).

• PDA - Starlink public domain algorithms (NAG replacement). This requires linking to more than one starlink library due to various inter-dependencies that starlink have introduced. We hope to remove this dependency at some point. This is only required for building.

• CFITSIO - this is used for FITS I/O stuff. The current build uses the version in the starlink distribution as default. Only required on building.
  

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:
   $RUNZ/runz
   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

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

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.

• 0 means spectrum flawed (e.g. bad reduction or fringing). Effectively saying that it should be counted as if the fibre had not been put on the object.
• 1 means a poor spectrum (e.g. low S/N or featureless) of no further use.
• 2 means a possible redshift, not good enough in its own right, but might be confirmed on reobservation.
• 3 means a probable redshift, i.e. sort of 75% confidence.
• 4 means a reliable redshift (at least 95% confidence)
• 5 means a reliable redshift and a high-quality spectrum, e.g. 3 or more features visible at high significance.
• 6 means a reliable redshift and a high-quality spectrum, but not extragalactic. Usually reserved for stars or PN.
• a accepts the quality proposed by runz.

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

• templist - a text file containing a list of spectral templates for cross-correlation.
• fit_lines.txt - a text file containing the wavelength of possible emission/absorption lines to fit when using the feature fit function (the f command).
• templates/ - the default location for cross-correlation templates.
• README - a brief summary of how to build and use the code.
• HISTORY - a summary of changes to the code.
• TODO - list of things still to implement (including bug fixes).
• zguide.html - this HTML guide to using runz.
  

Output

There are five files written out by the program:

• a detailed log file: *z.zlog
• The main results file with object name, RA, Dec, mag and and various redshifts (including the final z): *z.rz
• a copy of the input FITS file with the redshift and quality flags added to the header: *z.fits

Parameters in the RUNZ script

• project - project code. Enables project specific functionality, e.g. the Wigglez BAO survey. Current options are: 0 - default behaviour; 1 - Wigglez.
• igalt - Set which templates to use: 0 - all; 1 - gal+star; 2 - QSO+star. This can be overridden by user input in the main code.
• smsig - default smoothing sigma for smoothing of displayed spectra.
• plotim - flag to select whether to plot FITS images as well as spectra. This is only used in list mode when multiple FITS spectra are being read in.
• zav, zsig - redshift prior for galaxies (not used for QSO or stellar templates). The prior is a Gaussian distribution with average and sigma given by these parameters.

List mode

Output .rz file format

Hints

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

• The PGPLOT window is not displaying and/or I'm getting lots of device related errors in the terminal window:
  Remember to set the PGPLOT environmental variables:
  setenv PGPLOT_DIR /my/location/pgplot
setenv PGPLOT_FONT /my/location/pgplot/grfont.dat


• Runz crashed and I lost all my redshifts!!!
  A temporary file called temp.rz is written as the code goes along. Rename this to the correct file name and continue from where you left off. The reason that the main .rz file is not written as we go is that this causes problems when using the back (b) command.