CCLRC / Rutherford Appleton Laboratory SG/12.1
Particle Physics & Astronomy Research Council
Starlink Project
Starlink Guide 12.1
R. Morris, G.J. Privett & A.C. Davenhall
30th December 1998
Starlink Guide12.1
R. Morris, G.J. Privett & A.C. Davenhall
30th December 1998
This document is an introduction to the IRAF software package and its use on Starlink systems. IRAF is a powerful and comprehensive environment for reducing and analysing astronomical data. It was developed at the National Optical Astronomy Observatories, Tucson and is in widespread use around the world. IRAF has its own data file format, command language, on-line help system and programming language. It is a modular system. The basic core, which is always present, provides general facilities for image processing and data reduction. For more specialised tasks additional packages are loaded to augment the core system. Software for processing most sorts of astronomical data is available for the IRAF environment.
This document is aimed at people who are considering whether or not to use IRAF or who are using it for the first time.
This document is an introduction to the IRAF (Image Reduction and Analysis Facility) software package and its use on Starlink systems. It is aimed at people who are considering whether or not to use IRAF or who are using it for the first time.
IRAF is a powerful and comprehensive environment for reducing and analysing astronomical data. It was developed at the National Optical Astronomy Observatories (NOAO), Tucson and is now in widespread use around the world. IRAF has its own data file format, command language, on-line help system and programming language. It is a modular system. The basic core, which is always present, provides general facilities for image processing and data reduction. For more specialised tasks additional packages are loaded to augment the core system. Software for processing most sorts of astronomical data is available for the IRAF environment. IRAF is available on all the variants of Unix currently supported by Starlink: Digital Alpha/Digital Unix, SUN/Solaris and PC/Linux.
IRAF is one of several major software environments which are available to Starlink users and upon which entire data-analysis campaigns can be based. Some other examples include: Starlink's own large collection of utilities and application packages, the various incarnations of the Figaro package (SUN/86[]), AIPS (SUN/207[]) and MIDAS. Each package has its own particular strengths and special capabilities; IRAF, AIPS and Figaro are probably the most extensive.
IRAF is a sound choice for many Starlink data-analysis users, especially where compatibility with overseas collaborators is a requirement. The choice is harder for those wishing to develop major applications of their own, who may be reluctant to adopt IRAF's non-standard programming language, SPP, or who feel that the `flat' IRAF data format is inadequate for their purposes (see Section for further details). Those who need formal guarantees of future support should also be very wary about committing themselves to any package which is not under UK control. However, IRAF is an important weapon in the armoury of the average Starlink data-analysis user and likely to remain so for some years.
The structure of this document is:
The presence of IRAF is not mandatory at Starlink sites, though in practice it is available at most sites. You should check the arrangements at your site with your local site manager. If IRAF is not available at your site it is possible to obtain a copy via the Internet; the following section gives the details.
You can retrieve a copy of IRAF via the Internet by anonymous ftp. It can be downloaded from either the original NOAO site in Tucson or from a mirror (that is, an identical copy) maintained by Starlink at the Rutherford Appleton Laboratory. The latter is quicker and more convenient for sites in the UK. The Starlink mirror is updated from the NOAO original every night and hence can be no more than twenty-four hours out of date. The access details are as follows.
Anonymous ftp
| site: | ftp.noao.edu |
| directory: | /iraf |
Retrieve file README for further details.
Anonymous ftp
| site: | ftp.starlink.rl.ac.uk |
| directory: | /pub/mirrors/iraf |
Retrieve file README for further details.
If you are not familiar with the ftp utility then ask a colleague or your site manager for assistance. Alternatively, the books by Krol[] and Thomas[] include good descriptions.
A great deal of documentation is available for IRAF. Most of the documentation comprises detailed manuals for the various individual, specialised packages. However, some more general documentation is available and, in particular, there is an introductory guide for new users: A Beginner's Guide to Using IRAF []. IRAF is a complex and in some ways non-intuitive system and it is well worth taking the time and trouble to learn the basics of its operation before attempting a complicated data-reduction task. The Beginner's Guide is an accessible and thorough document and is a good place to start. Even if you are already familiar with IRAF it is still worthwhile having a look at the Beginner's Guide because it may well still contain useful information which is new to you. Another useful document is A User's Introduction to the IRAF Command Language [] which describes the IRAF command language, cl.
Copies of these documents can be retrieved from the IRAF anonymous ftp sites (see Section 3 for details). The directory specifications given below are relative to the `top-level' IRAF directory given in Section 3. The Beginner's Guide is available as file:
pub/beguide.ps.Z
The Introduction to the IRAF Command Language is available as file:
iraf/docs/cluser.ps.Z
Both of these files are in compressed postscript format. Remember to set ftp to binary mode prior to retrieving them. Once retrieved, they should be decompressed using Unix command uncompress (sic) and can then be printed on a postscript printer. Most IRAF documents (but not the Beginner's Guide ) are kept in directory iraf/docs. A complete, up-to-date list of documents is kept in file:
iraf/docs/README
which is a simple ASCII text file.
The IRAF Web sites contain a great deal of useful information. See Section 3 for the URLs.
An excellent, up-to-date list of Frequently Asked Questions (FAQs) is maintained for IRAF. It is, perhaps, the single most useful IRAF document and you should familiarise yourself with it; it will probably contain the answers to most of your initial queries about IRAF. An on-line version is available at the following URLs:
| NOAO, Tucson: | http://iraf.noao.edu/iraf/web/faq/FAQ.html |
| Starlink mirror: | http://www.starlink.rl.ac.uk/iraf/web/faq/FAQ.html |
A simple ASCII text version (suitable for printing) can be retrieved by anonymous ftp from file:
iraf/FAQ
A Newsletter describing recent enhancements and developments of IRAF is published intermittently. To subscribe to this Newsletter send an e-mail message to username iraf@noao.edu asking to be added to the distribution list and including your e-mail and postal address. Alternatively use ftp to retrieve the registration file:
iraf/REGISTER
and return it to username iraf-requests@noao.edu.
Back issues of the Newsletter are available on the IRAF Web pages. A table-of-contents for all the issues can be retrieved by anonymous ftp from file:
iraf/docs/TOC_news.txt
and is available from the Web pages.
Currently the most recent major release of IRAF (at least for the three variants of Unix supported by Starlink) is version 2.11. However, the previous version, 2.10, is still in use at some sites. There are significant differences between versions 2.10 and 2.11, particularly in the data formats which they support (see Section ). These differences will be alluded to at various points in the present document.
The basic IRAF data file format is the so-called Old IRAF Format (OIF). Despite this name there is no `new' IRAF format. Most IRAF tasks use the OIF format. Some brief details of it are given below.
In IRAF version 2.11 and subsequent versions most tasks can also access data files in the widely-used international standard FITS1 (Flexible Image Transport System) format.
Other formats are used for more specialised purposes. For example, the STF format is used by the STSDAS package for storing HST data, the QPOE format is used to hold photon event lists (which are usually produced by X-ray astronomy satellites) and the PLIO format for pixel lists (which flag individual pixels in an image).
The IRAF dataio package contains tasks for converting between numerous different formats.
A dataset, typically an image or spectrum, in the Old IRAF Format (OIF) format consists of two files: a header file which has file-type .imh and a pixel file which has file-type .pix. These files are usually stored in standard locations in your IRAF directories. The .pix files are large and can be stored in either the same directory as the header files or in a different directory. The header file contains the dimensions of the data array, the name of the pixel file and optionally any auxiliary information describing the image, expressed as a series of keywords and their values. These OIF keywords deliberately have a syntax similar to FITS keywords. The image dimensions and name of the pixel file are stored in a binary format, but the keywords are stored as simple ASCII characters. Thus, you can check the values of the keywords by listing a header file on the terminal.
There are several points about the OIF format which you should be aware (and beware) of.
set oifversion=1
The Space Telescope Format (STF) is used for storing Hubble Space Telescope (HST) data. It was introduced for the STSDAS package (see Section ), but is now understood by most IRAF tasks. Like the OIF format, an STF dataset comprises two files: one is the header file, and has the extension .xx h, where x can be any alphanumeric character, while the other contains the actual data values and has a .xx d suffix. The most usual file extensions are .hhh for header files and .hhd for data files. These files are usually kept together in the same directory. STSDAS files have the advantage that the header file is an ASCII file and can be read on a terminal without using IRAF at all (which is not true of .imh files; see above).
IRAF's `tasks', as the individual programs are usually called, are divided into packages. Each of the packages may contain tasks or further subpackages. For example, loading the noao package by typing ` noao', leads to further subpackages, while loading the dataio package makes available tasks for importing and exporting data to and from IRAF. You cannot use any task until you have loaded the package which contains it. Typing `bye' unloads the most recently loaded package.
A couple of the more common IRAF packages are described briefly below.
STSDAS (Space Telescope Science Data Analysis System) is a package for analysing data acquired with the Hubble Space Telescope (HST). It was developed at the Space Telescope Science Institute (STScI) in Baltimore. Further information is available at URL:
http://ra.stsci.edu/STSDAS.html
including details of retrieving the software and documentation. Note that installing STSDAS requires about 85 Mbytes of free disk space. Also note that STSDAS requires the TABLES package for manipulating tables to be installed. TABLES is also available from the STScI. Inquiries, queries, bug reports etc. about STSDAS can be sent by e-mail to the HST Help Desk at username help@stsci.edu.
PROS (Post-Reduction Off-line Software) is a package for analysing X-ray astronomy data. It is not specific to any one X-ray astronomy satellite and, in particular, it has facilities to handle data from the EINSTEIN, ROSAT, ASCA and AXAF satellites. It can also be used for non-X-ray data and is particularly suitable for generating pixel masks. It was developed at the Smithsonian Astrophysical Observatory, Cambridge, Massachusetts. Further information is available at URL:
http://hea-www.harvard.edu/PROS/pros.html
including details of retrieving the software and documentation. Inquiries, queries, bug reports etc. about PROS can be sent by e-mail to the PROS user support hotline at username hotseat@cfa.harvard.edu.
Most Starlink software is written using the Starlink software environment and stores data in the N-dimensional Data Format (NDF; SUN/33[]). A substantial degree of inter-operability is possible between this software and IRAF.
At the most basic level Starlink provides the CONVERT package (SUN/55[]) which is a set of applications for converting data files between a number of different data formats. It includes applications for converting an NDF format file to one in the IRAF OIF format (see Section 6) and vice versa. You should be aware, however, that the NDF format is more capable, and can contain more auxiliary information, than the IRAF OIF format. When an NDF file is converted to the OIF format such information is lost. In particular, the NDF format has standard ways of representing arrays of errors associated with arrays of data and many applications in the Figaro package process and propagate these errors. Error arrays are not accommodated in the OIF format and are lost when an NDF is converted to this format.
In addition to explicitly converting NDF files, most Starlink applications which read and write NDF files can be configured to read and write IRAF OIF files instead. Again see SUN/55[] for details.
Some Starlink packages have been enhanced so that they can be run from the IRAF command language, cl. When used in this way the Starlink packages behave like `native' IRAF packages loaded on top of the basic IRAF; they read and write data files in the native IRAF format and their parameters can be set and inspected using the usual mechanisms of the IRAF command language. Tasks in the Starlink packages can be intermixed freely with the standard IRAF tasks (again, just like `native' IRAF packages). There are a few differences between Starlink and `native' IRAF tasks, principally in the way that graphics are displayed; see SUN/217[] for details.
The principal Starlink packages which have been enhanced in this way are Figaro, KAPPA and GAIA. Their use from the IRAF command language is described in SUN/217[] and SUN/221[] and Section gives a worked example. The details of the technical legerdemain which allows applications written for the Starlink software environment to be run from the IRAF cl will not be of interest to most users. However, for completeness it is documented in SSN/35[]. The Figaro, KAPPA and GAIA packages themselves are documented in SUN/86[], SUN/95[] and SUN/214[] respectively.
For queries about how IRAF is installed at your site or assistance with obtaining and installing it you should consult your local site manager.
If you have a problem with or query about using IRAF then your first port of call should be the FAQ (see Section 4.2), which will often have the answer.
The IRAF Project in Tucson provides a support service for users. If your query is not covered by the FAQ then you can send it in an e-mail message to username iraf@noao.edu. The response is usually pretty swift, but do bear in mind the time difference between the UK and Tucson.
Because the support provided by the IRAF Project is excellent, little additional support by Starlink is either called for or provided. However, there is a Starlink contact for assistance with IRAF problems; you should send an e-mail message to username iraf@star.rl.ac.uk. This contact is particularly appropriate if you encounter problems inter-operating Starlink and IRAF software.
This part of the document provides a few simple, introductory examples of using IRAF. The examples are:
/star/examples/sg12
The examples given here form only the briefest of introductions and there are many facilities which are not described. There are further examples, and more detailed descriptions, in the Beginner's Guide [].
There are also a set of exercises which demonstrate how to reduce various sorts of data. They can retrieved by anonymous ftp (see Section 3 for details) from file:
iraf/misc/exer2102.tar.Z
The file is a compressed tar archive. Remember to set ftp to binary mode prior to retrieving it. The file should be decompressed using Unix command uncompress (sic). Instructions for installing the examples are given in file exer2102.readme (which is included in the tar archive).
Starting IRAF for the first time is non-trivial and hence this example is provided as an illustration of the procedure. The example is broadly correct, and works in Edinburgh. However, some of the details, in particular the file locations, may be different at your site. You should check the details at your site with your site manager.
An additional complication is that IRAF has various ways of displaying two-dimensional images (such as the CCD frames), none of which can be considered standard. Some of the common alternatives are to use either SAOTNG, its predecessor SAOIMAGE (see SUN/166[]) or XIMTOOL. SAOTNG and SAOIMAGE are separate image display applications which are not part of IRAF (though, obviously, they can display IRAF images). SAOIMAGE works correctly with IRAF version 2.10, but there seem to be problems with using it with version 2.11. Hence SAOTNG is used in the current example. It is also worth noting that when using IRAF you will not always need to display two-dimensional images, though in practice you usually will. Consequently setting up SAOTNG is integrated with the instructions here. The IRAF Beginner's Guide [] covers starting IRAF for the first time, but not all the details of setting up an image display.
The procedure is as follows.
/home/acd/iraf
This directory will be used in this example, though if you are working through it you should substitute your own chosen IRAF directory.
/net/reaxp02/packages2/iraf211/jbin/login
See your site manager for the details at your site. It is probably most convenient to put these lines at the end of the file.
mkiraf
You will be prompted for the terminal type; reply xgterm. Subdirectory uparm will be created in your IRAF directory, as will file login.cl. The latter is the IRAF start up script. It contains various options and defaults which you can change, but you should not need to do so.
/star/examples/sg12/loginuser.cl
You can simply copy this file to your IRAF directory. (It configures IRAF to handle the large headers often associated with fibre spectroscopy data and specifies that the pixel files associated with bulk datasets, such as images or spectra, are to be kept in subdirectory pixels of the IRAF home directory. Section gives some notes on how to specify the directory in which the pixel files are to be kept.)
saotng &
The `&' is, of course, simply to run SAOTNG as a detached process, which is more convenient.
xgterm &
A new window with a distinctive appearance is created. You will use this window to run IRAF. You can run IRAF from your normal login window, but using an xgterm window allows you to make better use of the workstation or X-terminal graphics.
Depending on the configuration options in place at your site the xgterm window might be created without a scroll bar. If so, and you want to add a scroll bar (which is often useful), then from the xgterm window hold down the Ctrl key and simultaneously click on the right mouse button. A window containing a list of options should appear; simply click on the scrollbar item and a scroll bar should be added to the window.
cl
An introductory message should be displayed and the prompt should change to `cl>'. You are now running the IRAF command language and ready to issue IRAF commands. See the Beginner's Guide [] for an introduction to the commands available and Section for a simple example.
As a quick check that the image display is working correctly type:
display dev$pix 1
An IRAF test image of the spiral galaxy M51 should appear in the SAOTNG display.
Type logout to leave the IRAF command language and return to the Unix shell prompt.
Once you have set up for using IRAF it is not necessary to repeat the entire foregoing procedure every time you use IRAF. For subsequent IRAF sessions in which you will use an image display you need repeat only steps 7, 8 and 9. For sessions in which an image display is not needed just repeat steps 8 and 9.
The directory which is to contain the pixel files associated with bulk datasets (such as images or spectra) is specified by the value of environment variable imdir. For example, the sample loginuser.cl customisation file contains the line:
set imdir=HDR$pixels/
which specifies that the pixel files are to be kept in subdirectory pixels of your IRAF home directory. Note that the trailing `/' is important. Here HDR$ denotes your IRAF home directory, which contains the header files. If you wanted to keep the pixel files with the header files in your IRAF home directory you would simply specify:
set imdir=HDR$
This example demonstrates a simple session using IRAF. It covers: converting a FITS image to the IRAF OIF format, displaying an image and calculating statistics for an image. It also introduces the IRAF on-line help system and displaying and setting IRAF task parameters.
The FITS image used in this example is available as file:
/star/examples/sg12/ccdimage.fit
If you intend to work through the example using this image you should make a copy of it in your IRAF directory. Alternatively, you may prefer to use a FITS image of your own.
rfits ccdimage.fit 1 ccdframe
rfits ccdimage.fit 0 ccdframe
File: ccdframe KAPPA - Cadd Size = 384 x 256
File ccdframe.imh should be created in your IRAF directory and file ccdframe.pix in the pixels directory (probably subdirectory pixels if you have used the loginuser.cl file supplied with this document). From the IRAF command language you can show the files in the current directory with command dir, change to a new directory with cd and list a text file with cat; these commands behave similarly to the equivalent Unix commands. You can use these commands to check that the header and pixel files have been created. When you are satisfied that all is well, make your IRAF directory your current directory again.
imhead ccdframe
display ccdframe 1
The image should be displayed in the SAOTNG window. You can use the various buttons in the SAOTNG window to customise the display.
imstat ccdframe
Output similar to the following should be listed:
# IMAGE NPIX MEAN STDDEV MIN MAX
ccdframe 98304 508. 308.3 330. 31988.
help imstat
A description of the command and its various parameters will be displayed. Some brief details of the IRAF on-line help are given in Section , below. So far, we have been specifying information to IRAF tasks by giving mandatory parameters on the command line. IRAF tasks also have so-called `hidden' parameters which adopt a default value if you do not specify them. You can show the current value of all the parameters of a task using the command lpar. For example:
lpar imstat
The output should be something like:
images = "ccdframe" Images
(fields = "image,npix,mean,stddev,min,max") Fields to be printed
(lower = INDEF) Lower cutoff for pixel values
(upper = INDEF) Upper cutoff for pixel values
(binwidth = 0.1) Bin width of histogram in sigma
(format = yes) Format output and print column labels?
(mode = "ql")
The parameters enclosed in brackets are hidden (in this case this is all of them except images).
imstat.fields = "mean,stddev,skew,kurtosis"
If imstat is run again:
imstat ccdframe
the output should now be:
# MEAN STDDEV SKEW KURTOSIS
508. 308.3 62.03 4728.
In addition to setting parameter values from the command line they can also be edited using task epar; see the Beginner's Guide [] for further details.
logout
To leave IRAF.
On-line help on individual tasks is available from the IRAF command language.
help task-name
from the IRAF command line. For example:
help imstat
and the help text for task imstat is displayed. The bottom line of the window gives a summary of the commands available (type q to quit and return to the IRAF cl> prompt).
apropos topic
For example, if you were looking for commands to mosaic several CCD frames together you might type:
apropos mosaic
This command searches all the available IRAF help databases and lists a summary of all the tasks with (in this example) the word `mosaic' in their title. Note, however, that apropos is part of STSDAS and hence is only available if STSDAS is installed.
This example shows a simple session using a Starlink package from within IRAF. It covers loading the package and calculating statistics for an image.
Several Starlink packages are available from within IRAF, of which the principal ones are KAPPA (see SUN/95[]) and Figaro (see SUN/86[]). When used from within the IRAF command language these packages behave in most respects like `native' IRAF packages: they can read and write IRAF OIF format data files and their parameters can be displayed and controlled using the usual mechanisms of the IRAF command language. Tasks in the Starlink packages can be intermixed freely with the standard IRAF tasks (again, just like `native' IRAF packages). There are a few differences between Starlink and `native' IRAF tasks, principally in the way that graphics are displayed; see SUN/217[] for details.
This example uses the Figaro application istat to display the statistics of an image in order to compare and contrast it with the standard IRAF application imstat used in the previous example. The IRAF OIF image ccdframe which was used in the previous example will also be used again here.
figaro
A list similar to the following should be displayed:
abconv cset fscrunch ilog lxset sfit abline cspike fwconv image lyset slice adjoin delobj gauss imult mask soft:
Also the prompt should be reset to `fi>'. The list comprises all the commands in the Figaro package. If instead of the list of commands you get an error message like:
ERROR: task `figaro' not found
then Figaro has not been installed in the version of IRAF available at your site. Section below gives a few hints on how to proceed in this case.
However, assuming that the package loaded successfully, then all the Figaro tasks are now available, in addition to the basic IRAF tasks. Here Figaro is behaving just like a `native' IRAF package. For any IRAF package, native or Starlink, you can:
bye
Figaro will be removed and the prompt will be reset to cl>.
istat ccdframe
Output similar to the following should be listed:
Y-range 1 to 256 X-range 1 to 384 Total (over 98304.0 pixels) = 4.9943E+7 Max = 31988 in pixel (332,108) Min = 330 in pixel (1,256) Mean = 508.05 Sigma = 308.263
Compare this output with that produced by imstat in the previous example. As in this case, Starlink applications are usually somewhat more verbose than standard IRAF tasks.
help istat
A description of the command and its various parameters will be displayed. Again as for the standard tasks, the parameters of Figaro applications can be shown in the usual way:
lpar istat
The output should be something like:
image = "" (IMage) Name of image to examine
ystart = *! (YStart) First Y value to be used
yend = *! (YEnd) Last Y value to be used
xstart = *! (XStart) First X value to be used
xend = *! (XEnd) Last X value to be used
(pass2 = no) (PAss2) Pass twice through data for better sigm
(median = no) (MEDian) Calculate median as well as other stat
(stat_total = 0.)
(stat_max = 0.)
(stat_min = 0.)
(stat_mean = 0.)
(stat_sigma = 0.)
(stat_size = 0.)
(stat_xmax = 0.)
(stat_xmin = 0.)
(stat_ymax = 0.)
(stat_ymin = 0.)
(stat_xstart = 0.)
(stat_xend = 0.)
(stat_ystart = 0.)
(stat_yend = 0.)
(stat_median = 0.)
(mode = "ql")
istat.median = yes
Now run istat again:
istat ccdframe
The output should now be:
Y-range 1 to 256 X-range 1 to 384 Total (over 98304.0 pixels) = 4.9943E+7 Max = 31988 in pixel (332,108) Min = 330 in pixel (1,256) Mean = 508.05 Sigma = 308.263 Median 494
Note that the median is now calculated and displayed.
IRAF installations at Starlink sites will usually have the additional Starlink packages installed. However, if they appear not to be available at your site then this section gives a few hints on how to proceed.
The directory /star/iraf should contain a subdirectory for every Starlink IRAF package present at your site. Check that this directory exists and that there is a subdirectory for the package that you are interested in. If the required subdirectory is absent then ask your site manager to install the package.
If the directory is present but the package is still not available when you start IRAF the most likely explanation is that the package is not known to IRAF as an external package. An entry for the package should be added to the hlib$extern.pkg file. Your site manager will have to add this entry. SSN/35[], Section 4.8 contains the necessary details.
As an interim measure, perhaps to establish the cause of the problem, you can add an entry to your own login.cl file. For example, for Figaro add the following lines:
reset figaro = starlink$figaro/ task figaro.pkg = figaro$figaro.cl
These lines must be added just before the user package definition. The helpdb definition can be extended by a command like:
reset helpdb = (envget("helpdb") // ",figaro$helpdb.mip")
For other packages you would add equivalent lines, substituting the name of the package for figaro.
A series of IRAF commands can be executed as a script by putting them in a file and then running the file. The IRAF command language, cl, is also a programming language and contains many features which allow you to write scripts to perform repetitive tasks automatically. It is also possible to run IRAF scripts as Unix background jobs. This facility is particularly useful if you want to run lengthy tasks at low priority without tying up your terminal. This example is a simple introduction to IRAF scripts and background jobs.
The scripts used in this example is available as files:
/star/examples/sg12/submean.cl
/star/examples/sg12/background.csh
If you intend to work through the example you should copy these files to your IRAF directory. The IRAF OIF image ccdframe, which was used in the previous examples, should also be available.
File submean.cl is a script of IRAF commands. It is shown in Figure . It calculates the mean value of all the pixels in an image and then generates a new image in which the mean value is subtracted from every pixel.
# IRAF script to calculate a mean and subtract
# it from an image.
# Load images package.
images
# Initialize the cl list variable.
list = " "
# Store a temporary file name in string s3.
s3 = "temp.file"
# Configure imstat to display only the mean
imstat.format=no
imstat.fields="mean"
# Redirect imstat output to temporary file.
imstat "ccdframe" > (s3)
# Associate temporary file with list variable.
list = (s3)
# Read the value in the file into parameter 'x'
i= fscan (list,x)
# Use imarith to subtract x from the image.
imarith ("ccdframe","-",x,"newframe")
# Reconfigure imstat and then look at statistics of
# new image to see if the subtraction worked.
imstat.format=yes
imstat.fields="image,npix,mean,stddev,min,max"
imstat ("newframe")
# Delete the temporary file.
delete ("temp.file", verify=no)
# Print an output message
print("Subtracted ",x,"to create file newframe.")
As with any unfamiliar programming language, your first reaction is probably one of trepidation as you wonder what is going on. No variables were declared at the start of this script although variables are used throughout the program for parameter passing. The cl has some built-in variables which do not need to be declared. There are three string variables named s1 to s3, three real variables x, y and z, three integers i, j and k, three booleans and other more esoteric ones. Type `lpar cl' for a full list of the parameters available for immediate use. Other variables can be used but they need to be declared: see the cl manual[] for information on how to do this. List-type parameters are useful, they are usually associated with files, and they allow you to use fscan and fprint for reading and writing to files. These functions are similar to the equivalent functions in the C language.
The command imstat is used to calculate the mean. Some IRAF tasks have output parameters which allow their results to be stored and subsequently accessed by another task. Unfortunately, imstat does not have any such output parameters. Instead, it is configured so that the only output that it generates is the mean value, without any annotation. This output is redirected to temporary file temp.file using the Unix-like output redirection capabilities of the IRAF cl.
The fscan function is used to read the value from the file and store it in variable x. The imarith task (from the images package) is then used to subtract the mean value from each pixel and create a new image newframe. Finally, imstat is reconfigured to display its default output and the statistics for image newframe displayed as a check that the script has worked correctly.
Quoted parameters are passed to the tasks as they are; the brackets around some of the parameter lists indicate that the cl language is meant to interpret these parameters as variables. Programming in cl can be tricky sometimes: putting `echo=yes' at the start of the script means that all commands are echoed to the terminal as they are executed, which can be useful for debugging. The file name `ccdframe' was of course hardwired into the script; a more typical application would operate on every file in a list, or loop until some condition is satisfied. The cl can support loops of various types. See A User's Introduction to the IRAF Command Language [] for more information.
The procedure to run the script is as follows.
task $submean=home$submean.cl
`home' is specifying that the script file resides in your root IRAF directory.
submean
Output similar to the following should appear:
# IMAGE NPIX MEAN STDDEV MIN MAX
newframe 98304 3.044E-5 308.3 -178. 31480.
Subtracted 508.046 to create file newframe.
You can check that image newframe has been created by typing dir and display it with SAOIMAGE by typing:
display newframe 1
imdelete newframe
Note that the script will not work correctly if newframe already exists, so you must delete it before running the script again.
It is possible to run IRAF scripts as background jobs. It is necessary to prepare a Unix shell script which starts IRAF and then runs the IRAF script. File background.csh is an example shell script. It is shown in Figure . This example invokes IRAF and uses it to run script submean.cl.
#!/bin/csh # Make sure a C shell is used # Run IRAF from the UNIX shell, taking parameters # up until the word END. cl <<END >log.file images task \$submean = home\$submean.cl submean logout END
The script first ensures that a C shell is used, if it is run as an executable shell script, then IRAF is started and fed with commands. Notice how the $ signs need to be escaped in the task definition to stop the UNIX shell from interpreting them as shell variables. The output is written to file log.file. There is further information about shell scripts in SC/4: C-shell Cookbook []).
The script is run from the Unix shell prompt. Simply type:
background.csh &
Output will be written to file log.file. Remember that script submean.cl will only run successfully if image newframe does not already exist.
This appendix gives a few brief notes about obtaining and installing IRAF. A typical Starlink user is unlikely to be able to carry out a complete IRAF installation. The assistance of your site manager is likely to be required for at least some of the stages and he will probably carry out the complete installation.
IRAF is available for all the variants of Unix currently supported by Starlink (and on various other operating systems). A basic IRAF installation, without any external packages, requires about 100 Mbytes of disk space, though the actual amount varies somewhat between the different variants of Unix. However, about half this space can, if necessary, be reclaimed by deleting source files once the installation is complete.
A copy of IRAF can be retrieved by anonymous ftp from NOAO or the Starlink mirror. The IRAF Web pages (see Section 3) give the necessary details. Alternatively the NOAO can send you a copy on tape or CD-ROM, though a small charge is made. Again see the Web pages for details. There is a separate distribution of IRAF for each version of Unix supported and there is no compilation involved in making the installation (though source is supplied).
Before installing IRAF you should obtain and read the following documents:
The REGISTRATION file is important as it contains a form to be filled in and returned to NOAO by e-mail, so that you can be added to the mailing list for the IRAF Newsletter (see Section 4.3).
We are grateful to Dave Bowen for advice and assistance with using IRAF and useful comments on the draft version of the document. Nigel Hambly also gave several helpful tips on using IRAF. Martin Bly, Alan Chipperfield and Rodney Warren-Smith provided useful comments on the draft.
Any mistakes, of course, are our own.
1 The original FITS format was proposed by Wells et al. []. However, it has been developed and enhanced over the years. The FITS standard is now maintained and documented by the FITS Support Office of the Astrophysics Data Facility at the NASA Goddard Space Flight Center (see URL: http://www.gsfc.nasa.gov/astro/fits/fits_home.html). Though FITS is basically an astronomical format it is sometimes mentioned in books about standard image formats. See, for example, Graphics File Formats by Kay and Levine[].
2 The skewness and kurtosis are standard statistical quantities. See, for example, Wall[].