IRAF paso a paso: 2 - Packages and Tasks

Start: load and use packages

To start IRAF, type ecl.
This "Enhanced cl" provides a tcsh-style editing of the line command, a tab completion of file names, the possibility of moving through the history using the arrows, and a very much improved handling of errors in scripts and programs.
Remember that ecl must be started from the directory where you keep your file.

If you want to use ecl, and start IRAF from any directory, you should first define the environment variable UPARM to your uparm directory, for instance:
setenv UPARM /home/ncaon/iraf212/uparm/

The startup screen looks like the following:

cl startup window

The startup message contains useful hints, for instance the current IRAF version.
Names followed by a dot are packages (ex. adccdrom, arnica, etc.); names without dot are tasks (ex. apropos, describe, examples).
The prompt is the name of the last package loaded (in the startup screen, the prompt is "ecl").

Getting info on packages
You type: What happens
name_of_package The package is loaded; prompt changes to the package name.
? List tasks in the most recently-loaded package.
?? List all tasks loaded, regardless of package.
package List all packages loaded.
? images List tasks or subpackages in package images.
bye Exit the current package.

There are no limitations to the number of packages that can be loaded at any given time.

Getting help

The help command allows to get help on a package or on a task.
It has several options, described in the following table:  
Getting help on known tasks or packages
Command Action
help task Show the whole help page for the task.
help package Prints a one-line description of each task or subpackage in the package. If you omit the package name, it will apply to the currently loaded package.
phelp task Like "help task", but allows to move forward and backword through the help file (= help | page).
example task Show only the example section of the task.
describe task Show only the description section.
help task opt=source Show the actual code (useful if you wish to understand in detail how a task works).
help package opt=sysdoc A general description of the package (available for a few, for instance isophote, nebular).
help task device=gui Help is displayed in a nice GUI, which allows to navigate through the IRAF help docs (new in IRAF 2.12.2).
help task device=ps >
help task device=html > task.html
Help is output in a postscript or an HTML file (new in IRAF 2.12.2)

The help GUI interface can also be launched by loading the guiapps package and then executing the xhelp task. This should be considered a prototype application for trial use, so it may still have some bugs or inconsistencies (such as hanging the XGterm in a RHEL platform.)

If you do not know what task does what you need, you can use:

Finding the task you need
Command Action
apropos <keyword> Look through a list of IRAF + STSDAS menus to find tasks matching the keyword. Package name is also shown in parenthesis. Notice that depending on when and how the apropos database was built, there might be packages and tasks not included in it.
refer <keyword> Search the help database for tasks related to the keyword. An alternative to apropos.

Curious users want to know whether the task they're using is a real IRAF program (written in SPP) or just a CL script. What would you do?

Anatomy of a task

The way a task operates is determined by its parameters.
There are two types of parameters:

required Must be specified to the task. If not, the task prompts for them.
They are always learned, i.e. become the default for the following run.
Must be given in the correct order in the command line.
hidden Do not need to be specified. Task will use default values. They might be learned or not according to how they are set.
If specified on command line, the syntax is parameter=value. May be put in any order, but must follow required parameters.

All parameters of a task can be displayed doing: lpar task:

editing task parameters
Hidden parameters are the ones within parenthesis.
Alternatively, parameters may be listed with the command:
cl> dpar task
This is useful if they are to be written to a file.

Also, the command:
cl> =package.task.parameter
will show the value of that parameter.

Three ways to set or tell the task the parameter values:

Command Description Example
epar task Edit interactively parameter values.
You move through the parameters menu and change them.
Exit with :q to save, :q! to discard changes, :go to start task execution. Also, :w file will output the parameter list (in an unfriendly format) on file file.par; :r file.par will read back a saved parameter file.
epar imarith ...editing... :q
task <list of parameters>i Parameters are specified in the command line imarith image1 + image2 result title="SUM" pixtype=real
set explicitely Syntax: task.parameter=value imarith.pixtype=real or imarith.title="SUM"

Though hidden parameters may seem less important than the required ones, actually they not always are. Before running any task, it is good practice to revise carefully all its parameters and change their settings to suit your needs. (As an example, in the task fitcoords the default value for xorder and yorder is 6. My experience with such task, applied to logn-slit spectra, is that such values produce wild oscillations in the fitted surface, and smaller values, typically 3 or 4, are much better).

Why do you think IRAF people defined and implemented these two different sets of parameters? What if they were all required? And what if they were all hidden?

Sometimes, the parameters of a particularly complex task (ex. imexamine), or which may be common to a set of tasks (as in the package daophot), are grouped into psets.
To edit the parameters in a pset (ex. imexamine's pset rimexam), do:
cl> epar rimexam  or just type   cl> rimexam

Psets can also be modified from inside the parameters of a task using them. For instance, doing epar phot, you can edit the centerpars pset by moving to the "centerp=" line and typing :e.

psets are identified in the package menu by a trailing "@" character. (Load the package daophot or apphot to see quite a few).

Expressions in parameters:
Simple numerical expressions, surrounded by parenthesis, can be given as the value of a parameter. For instance, we might do:
cl> display.z1=(200-3*60) ; display.z2=(200+3*60)    or
cl> display dev$pix 1 zr- zs- z1=(200-3*60) z2=(200+3*60)

Executing tasks

There are several possibilities on how to run a task:

  1. Type its name (or an unambiguos abbreviation) and enter parameters when prompted. Hidden parameters won't be queried, task will use the current ones.
    cl> imstat
    Images: dev$pix
    # IMAGE NPIX MEAN STDDEV MIN MAX dev$pix 262144 108.3 131.3 -1. 19936.
  2. Specify parameters values on the command line when you run the task (required parameters are learned, and their default value is printed upon prompting; hidden ones are not).
    cl> imstat dev$pix fields="min,max" format-
  3. Type epar task, change all the parameters you want, then type :go. Task starts immediately (maybe the simplest method).

Tasks can be executed in the background, tied together, or their output can be redirected.

  1. Background: A task may be executed in the background by ending the task command line with a &
    cl> imstat dev$pix form- &
    If not all required parameters are specified, CL stops and waits for response.
  2. Redirection: Output of a task can be redirected using symbols ">" and ">>" (as in Unix).
    cl> imstat dev$pix form- > imstat.txt
    Use ">&" to redirect both output and error messages.
  3. Pipe: Output of a task may be used as input to another task (as in UNIX):
    cl> imhead dev$pix long+ | page
    cl> ?? | words | sort | table
    The output of imheader is fed as input to the task page; the output from ?? is broken into individual words, sorted, and printed in tabular format.
  4. Command line too long: Commands can be extended to two or more lines using the "\" character. Line break can come at end of parameter string, or after a comma in a parameter list (no preceding space is then allowed).
    cl> imstat dev$pix fields="mean,stddev,min,max,median" \
    >>> lower=0 upper=1000
    >>> means that IRAF is expecting completion of command line.
    If you try to edit a multi-line command, you generally get a messed-up output. A useful alternative is to write down the command in a file, and copy-and-paste it into IRAF. If you wish to modify it, do it so in the file, and repeat the copy-and-paste.
  5. Commands on same line: Two or more commands may be written on the same line, provided they are separated by a ";" (semicolon, exactly as in Unix). Ex:
    cl> time ; dir ; show stdimage
  6. Execution time: Preceding the command string by a "$" sign (no blanks between "$" and taskname!), IRAF displays the CPU time once the task is terminated. Ex:
    cl> $imstat dev$pix fields="mean,midpt,stddev,mode"

Foreign tasks
The file contains definitions of commands which are declared as $foreign. They are not tasks written outside of the U.S., and for which the CIA and the FBI keep an eye out, but rather Operating System-level commands that can be used similarly to IRAF tasks, with arguments, input or output redirected, used with pipes. However they cannot be used in background, nor have parameter files. Also they may not work well with IRAF pathnames, compare for instance: cl> ls images$  with cl> dir images$

Warning: If you happen to abort a task (Ctrl-C), type flpr twice to clean up IRAF memory, which can get corrupted by the abortion.
Sometimes, if IRAF behaves strangely, a couple of flpr might solve the problem. At times, it may be necessary to logout of IRAF and start again.

Quiz 1:
A user, who is using a VAX/VMS system, would like to know whether also the foreign tasks may participate in I/O redirection and piping (which are not implemented in the VMS Operating system). What should he do?
Quiz 2:
A user just started to work with IRAF at his workstation when he realizes that the ">" key in her keyboard does not work anymore; worse, she was planning to do a lot of output redirection, thus using that key very frequently. What can he do to keep on working until the ">" key gets fixed?

Note: The standard IRAF installation include some images and files with which to do experiments, try tasks, etc.
2 images are available: dev$pix.imh and dev$wpix.imh ; the latter includes the WCS in the header (see Chapter 4). Also, there is a metacode file, called dev$vdm.gki .
Furthermore, directory scidata$ contains a variety of HST-related images and tables.