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
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
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.
- this is used for FITS I/O stuff. The current build uses the version
in the starlink distribution as default. Only required on building.
Make a directory to put the code:
Unpack the runz distribution from the tar file:
tar xvf runz_linux_070416_scroom.tar
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.
Build the code:
First set the environmental variable RUNZ to the directory you put the code in, e.g.
setenv RUNZ /my/code/runz/
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.
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.:
||Standard default interactive mode.
||Automatic mode (no uder interaction)
||Quick mode. Only manually intervene for questionable redshifts.
||List mode. Input a list file of 1-D spectra.
||Single object mode. Input a fibre number to examine only a single object.
||Helpful plots. Just produces the quality plots and then quits. The plots are written to a postscript file *_diag.ps.
Some other functionality can be varied by editing variables in the
runz script. For details see below.
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.
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
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
||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).
||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.|
||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
||De-smooth the spectrum,
reducing the width of the smoothing oy 1 sigma (reverse of 's'
||(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.
||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
||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).
||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)
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.
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:
with the redshift and quality flags added to the header:
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.
plotimflag is set, then the code can also plot postage stamp images contained within these FITS files as well as the spectra.
|2||Object||Object name given in .fld file when configuring|
|9||Rmag||Reference magnitude given in .fld file|
|10||neb||Number of emission lines in best emission line redshift|
|11||neg||Number of good potential emission lines found in spectrum|
|12||ze||Best emission line redshift|
|13||ze_err||Error in best emission line redshift|
|14||qe||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|
|15||temp||Number of best cross-correlation template|
|16||xcor||Cross-correlation r value|
|17||zx||Best cross-correlation redshift|
|18||zx_err||Error on best cross-correlation redshift|
|19||qx||Quality of best cross-correlation redshift 1=no redshift, 2=redshift > 0, 3=r>3.5, 4=r>5, 5=r>7|
|20||z_fin||Best final redshift|
|21||zf_err||Error on best final redshift|
|22||qa||Best automatic final quality (chosen from qe or qx). Set to 0 if emission and cross-correlation redshifts do not agree|
|23||qop||Quality of best redshift given by user (see above)|
|24||f||Flag user modified redshift: 0=no change, 1=redshift not auto best redshift, 2=redshift not best emission or cross-correlation redshift|
|25||fld||Field name/number. Generally not used and set to 000|
|26||date||UT date from FITS header - may not be the date of last observation if taken over several nights|
|27||ccd||Detector identifier: 0=6df, 1=2dF Tek1, 2=2df Tek2, 3=AAOmega blue, 4=AAOmega red|
|28||pl||2dF plate 0/1|
|29||x_posn||2dF x position of fibre in microns|
|30||y_posn||2dF y position of fibre in microns|
|31||S/N||Average S/N over spectrum|
|32||spmag||Spectrum magnitude summed over whole spectrum with arbitrary zero-point (=33.0): spmag=33.0-2.5*log(summed_counts)|
|33||vsp||V-band spectrum magnitude summed over 5150 to 5950A with arbitrary zero-point (=32.0): vsp=32.0-2.5*log(summed_counts)|
|34||rsp||R-band spectrum magnitude summed over 5950 to 6800A with arbitrary zero-point (=32.3): rsp=32.3-2.5*log(summed_counts)|
|35||RA(deg)||RA in decimal degrees|
|36||dec(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.
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.