FIGARO. A General Introduction.

Keith Shortridge, AAO

18th April 1995

1. Introduction

Figaro is a data reduction system that originated at Caltech and whose development continued at the Anglo-Australian Observatory. Although it is intended to be able to deal with any sort of data, almost all its applications to date are geared towards processing optical and infra-red data. Figaro was originally written to run under DEC's VMS operating system, but is now available both for VMS and for various flavours of UNIX.

This document is intended to introduce you to Figaro. It will explain how to invoke it, and will describe some of the commands and a little of the philosophy behind the system. The command syntax is intended to be quite flexible, which means that there are usually a number of ways in which parameters for a command may be specified. This note will describe the various alternatives; different people seem to feel happier with different styles. The main thing is to be aware of the possibilities.

Obviously, a short document can only give a brief overview of a large system. Other documents provide more details, and this merely attempts to point you at these where possible.

Note that this document refers specifically to the version of Figaro referred to as `Portable standalone Figaro'. This is the version of Figaro that runs directly from the command prompt of the operating system and does not use some additional environment such as Starlink's ADAM system. This mainly affects the details of the way the parameter system works, and not all the features described here will work on other versions. This document is being released with Figaro 4.1.

Wherever possible, the information given in this document refers to both the UNIX and VMS versions. However, there are differences between the two, and these will be flagged where necessary.

2. Invoking Figaro

Figaro is invoked by just typing `figaro'. Try it.

If all you get is a `command not recognised' message, then some initial setup is required. This is described in the section `Setting up to run Figaro', and you're going to have to work through that first. For the moment, let's assume it works.

When Figaro starts up, it prints a number of possibly informative

messages, usually news about new Figaro commands, bug fixes, and so forth.

You should now get a normal operating system prompt, because you will now have been returned to a normal operating system command line. Under UNIX, you will be back at the prompt for whatever command shell you happen to be running. Under VMS you will be back at a DCL prompt. This document does not normally show command prompts, except where program output is shown as well, in which case a `$' symbol is used to represent the command prompt.

3. Running Figaro programs

From the fact that you are now back with an operating system prompt, you should be able to deduce that Figaro is not just a big single program that you start up and then have to stay in. The usual way to run Figaro is as a set of individual programs, and that's what's being described here.

When you typed `figaro', a procedure was run through which, amongst other things, set things up so that Figaro programs can now be run just by typing the appropriate command. Typing the command name runs the Figaro program that services that command.

Figaro tries to fit in with the system it runs under. This means that under UNIX, Figaro looks like a set of UNIX commands, and under VMS it looks like a set of VMS commands. Commands that run Figaro programs can be intermingled with standard operating system commands. So you can change your default directory, list the files in the new directory using the standard operating system command, and then run Figaro programs that operate on those files. You delete and copy files using the normal operating system delete and copy commands. Figaro data files are single, self-contained files and work naturally with such operating system commands.

This means, of course, that you need to know your way round the operating system in order to make good use of Figaro.

You don't have to exit from Figaro -- the concept doesn't really exist, because you are never actually `in' a program called Figaro. Remember that all the `figaro' command does is enable the other Figaro commands

4. A first command -- reading a FITS file

Let's look at a first Figaro command. Since to do anything with Figaro you need to read data into it, and since most astronomical data is passed around in FITS format, we'll look at the `rdfits' (`read disk FITS') command.

Assume we're in a directory with no files other than a single FITS format disk file called `n6770.fits'. This is a standard test image used by Figaro and supplied with the release. First, just to be sure, we look at the directory contents. This, of course, is different under the different operating systems.

UNIX VMS

$ ls $ dir

n6770.fits N6770.FITS

Now, we use the Figaro `rdfits' command to read the file into Figaro. If you've run Figaro before, you may get different default values shown in the prompts, but if you're starting entirely from scratch it should look like this. You type in the responses to the first two prompts and just hit the return key for the second two.

$ rdfits

(FIle) Name of 'Disk FITS' format file [ ] - n6770.fits

(IMage) Name of resulting image [ ] - n6770

(SWap) Swap byte order? [YES] -

(FLoat) Convert data to floating point? [YES] -

$

and then we look to make sure a new file has been created.

UNIX VMS

$ ls $ dir

n6770.fits n6770.sdf N6770.FITS N6770.SDF

indeed, there is a new, Figaro format, data file. Figaro data files come in two different formats, with either a .sdf or a .dst file extension. For most purposes, the differences are unimportant, and which you get depends on some details of the Figaro setup. So don't be surprised if you try this and find .dst files being created.

For the moment, the interesting thing is to look at the prompts you got from the Figaro program `rdfits'. We'll go into more detail about prompts in the next section, but these make a good introduction, since they are fairly typical of Figaro prompts.

What you are seeing in action here is the Figaro parameter system in action. Almost all Figaro commands are parameterised in some way; `rdfits' has one parameter that specifies the FITS file to be read and another to specify the name of the Figaro format file to be created. (And two others that control the more esoteric aspects of byte-swapping and output format.) Everything you type on the command line (at the dollar prompt) is passed to the Figaro parameter system, which will try to see if you have specified any of the parameter values it needs as part of the command you typed. If not, it will prompt you for them.

Look at the first prompt you were given:

(FIle) Name of 'Disk FITS' format file [ ] - n6770.fits

This is a prompt asking for the name of the FITS file to be read. The `FIle' in parentheses is the name of the parameter. All Figaro parameters are named, and `FILE' is a pretty obvious name to use here. The name is useful mainly when you want to specify it directly on the command line. The reason only the first two letters are capitalised is to indicate that it can be abbreviated, but those first two letters are required. So `FIL' (or `fil', since Figaro parameter names are not case-sensitive) is acceptable, but `F' is not.

The [ ] is indicating the default value for the parameter. At the moment, it's really indicating that there is no default value. You respond to the prompt by entering the name of the file you want to be read. You have to enter the full file name (`rdfits' does not assume that FITS file have a .fits extension) and whether this is case-sensitive depends on the system being used; UNIX file names are case-sensitive, VMS file names aren't. Now look at the next prompt:

(IMage) Name of resulting image [ ] - n6770

This is similar, except that you are now being prompted for the parameter called `image' -- the name of the Figaro format file to be created. Since the input file was called `n6770.fits' it seems reasonable to call the output file `n6770' as well -- that is the name of the object in question, after all. When you're prompted for the name of a Figaro file, you generally don't include the file extension. Depending on the Figaro setup, either a .dst or a .sdf file will be created, and usually you don't want to try to control that. You can reply with `n6770.sdf' if you like -- often people do this without even thinking about it, because they know that's what's going to be created. (Earlier versions of Figaro used to misinterpret `n6770.sdf', for reasons that will become clearer when we talk about the contents of Figaro data files. Later versions realise that you mean the file extension.)

The last two prompts are about details of the conversion from FITS to Figaro format. In each case they are asking a `YES' or `NO' question, and in each case they supply a default of `YES', which you take by just hitting the return key.

(SWap) Swap byte order? [YES] -

(FLoat) Convert data to floating point? [YES] -

Of course, if you don't understand just what the question means, you don't really know if you ought to accept the suggested default. That's where the on-line help comes in, and we cover that in a couple of sections time. (If you can't wait to know the answer, you type `?' in response to the prompt, and it tells more about the parameter.)

5. Reading FITS files from tape.

If you want to read FITS files from tape, you can use the `fits' command instead of `rdfits'. This works in just the same way, except that instead of reading from a disk file, it reads the next FITS image from the specified input tape. This means that you have to set the tape device to read from before you can use `fits'. You do this using the `tape' command, whose single parameter is the name of thetape drive to use. The way a tape drive is specified is different on different operating systems, but will probably be something like:

tape mta0 (VMS)

tape /dev/nrst5 (UNIX)

(Note that under UNIX you should almost always use the `no rewind' form for tape device names -- use `nrst5' instead of `rst5', for example.)

Having done that, you can read the next file from the tape using a command like:

fits image1 \\

which will read that next file from tape and will create the Figaro format file `image1'. The `\\' at the end of the line stops Figaro prompting for the other parameters (the byte swopping option and the floating point option) and makes it take the default values. We will return to this syntax later, when we use the `image' command to look at the way parameters are specified.

A common question is `How do I read all the files from a FITS tape?' The full answer is complicated, and is provided in the parameter system documentation, but a form that works is

fits 'image{1:}' \\ (UNIX)

fits image{1:} \\ (VMS)

This is not the place to explain the details of this syntax, which is explained in the parameter system documentation, but this will read files from the tape, calling them `image1', `image2', `image3', etc. until it finally reaches the end of the input tape.

6. The contents of Figaro files, and the EXAM command

Now that you have a Figaro format file, you may be interested in what it contains. There are a number of commands for looking at the contents of files (`istat'', for example, will give you statistics about the data), but one of the most general is the `exam' command. This shows you some of the internals of the file. You can just give the `exam' command and let it prompt you for what to examine, but you can also put the object name parameter on the command line, eg:

$ exam n6770

n6770

.TITLE[32] Char n6770

.DATA_ARRAY[463,241] Float 115.7 125.9 122.6 105.9 116.8 120.4

.... 124.7 127.8 121.8 122.4 119.1

.MORE Ext

What this shows you is that a Figaro file is a structured file. Rather like a directory system on disk, where you have directories that can contain other directories or ordinary files, a Figaro file is a structure containing `objects' that are either primitive objects (character strings, floating point arrays, etc.) or are themselves structures that can contain other structures. You can see that the n6770.sdf file contains three items at its top level: a title string, a 2D floating point array (this is the actual image data), and a thing called .MORE which doesn't look like a primitive item at all. It isn't, it's a structure, and you can use `exam' to see what it contains:

$ exam n6770.more

n6770.more Ext

.FITS[80,19] Char NBIN1 = 1 /

NBIN2 = 1 /

IMAGE# = 138 /

NAME_OBJ= 'V6770 ' /

UTSTART = '16:35:14' /

UTEND = '16:37:14' /

EXPOSURE= 120 /

EXPOSED = 120.012 /

ELAPSED = 120.154 /

UTDATE = '05/06/86' /

INSTRUME= 'RGOCCD ' /

MEAN_RA = 288.5166 /

MEAN_DEC= -60.59558 /

EQUINOX = 1950. /

..............etc.........

END

What it turns out to contain is a two-dimensional character array that looks remarkably as if it contains FITS keywords. In fact, this is where the FITS keywords from the file n6770.fits have been put. You notice that `exam' doesn't list all the lines in the array -- if you count them you'll see that the array has 19 lines of 80 characters, but only 15 of them were listed, the `...etc..' standing for the missing lines. This is done because some such arrays would be far too long to list. We'll return to how to list all of the FITS keywords in this array in the next section. (Can't wait? OK, `exam' has a parameter that will make it list the whole of a character array like this.)

We might add, at this point, that one of the more useful things `exam' can do is list the whole structure of a file, listing each sub-structure recursively as it comes across it. The way to make it do this is to put one or more dots after the name of the object to be examined (the number of dots doesn't matter), like this:

$ exam n6770..

n6770

.TITLE[32] Char n6770

.DATA_ARRAY[463,241] Float 115.7 125.9 122.6 105.9 116.8 120.4

.... 124.7 127.8 121.8 122.4 119.1

.MORE Ext

.FITS[80,19] Char NBIN1 = 1 /

NBIN2 = 1 /

IMAGE# = 138 /

NAME_OBJ= 'V6770 ' /

UTSTART = '16:35:14' /

UTEND = '16:37:14' /

EXPOSURE= 120 /

EXPOSED = 120.012 /

ELAPSED = 120.154 /

UTDATE = '05/06/86' /

INSTRUME= 'RGOCCD ' /

MEAN_RA = 288.5166 /

MEAN_DEC= -60.59558 /

EQUINOX = 1950. /

..............etc.........

END

Figaro gets a lot of its flexibility from the file structure it uses. Note that all the items in the structure are named, and have types and dimensions associated with them. Most Figaro files have a main data array in them., even if they don't have anything else Some also have error arrays, quality information, axis information, etc. A Figaro program, given a Figaro file, can look into it and see what it contains; can see if there is quality information associated with the array, can see if there is axis information available, and can handle the file intelligently depending on what it finds in it.

We might allow a brief aside on the subject of file formats here. A Figaro program can look at the file and find the names of all the items in it. However, to know that the object called `DATA_ARRAY' is actually the main data array and not, for example, the axis data, requires that conventions be adopted for the contents of files. The main difference between the .sdf and .dst files that you see being used with Figaro is that the two represent different conventions for the internal layout of the file structure. Figaro knows both conventions, and can work equally well with either. (The .dst conventions are those originally used by Figaro. The .sdf conventions are those defined rather later by Starlink in the UK. These are more rigidly defined and are used by other Starlink packages as well as by Figaro, so these are a slightly more portable format. Confusingly, the Starlink format is called `NDF' -- N-dimensional data format -- but the standard file extension for NDF format files is .sdf)

It's also worth explaining how to control whether you get .sdf or .dst files when you run Figaro programs. This all depends on the setting of the environment variable (in UNIX) or logical name (VMS) FIGARO_FORMATS. If this is undefined, Figaro will assume that files have a .dst extension if none is specified explicitly, and will create any new files in .dst format. If it is set to just `ndf', the assumed extension will be .sdf and new files will be .sdf files. If it is set to `ndf,dst', then Figaro will look for files of either extension if none is specified -- so is able to default to either, depending on what is there -- but will produce .sdf files when a completely new file has to be created. The other possibility is `dst,ndf', in which case the default is again either depending on what is present, but completely new files are created in .dst format.

7. On-line help for a specific command

If you don't know much about how to run a command like `exam', there is some on-line help available. It's usually pretty safe to type the command name and see what happens. With `exam' what happens is:

$ exam

(OBJect) Name of object to be examined [n6770..] -

It isn't obvious at this point (that's why you're reading a document like this, after all) but you can enter a `?' in response to any prompt to get some additional help about the parameter in question. If you try it here, you get:

$ exam

(OBJect) Name of object to be examined [n6770..] - ?

----------------------------------------------------------------------<> EXAM lists the contents of a Figaro data object. This can be the name of a top level structure - ie the actual file name (without the .DST extension) eg 'EXAM FILE' - or the name of a single object in that file eg 'EXAM FILE.OBS' or 'EXAM FILE.OBS.OBJECT'. If the name ends with one or more dots, eg 'EXAM FILE..' then the whole underlying structure is listed. Otherwise structures are only listed to a single level down.

----------------------------------------------------------------------<>

OBJECT is a character parameter.

The default value, which will be used if you just hit the return key, is n6770...

To accept the default and suppress any further prompting, just enter a single "\". To abort the program, enter "!!".

(OBJect) Name of object to be examined [n6770..] -

With luck, this has told you something useful. (If nothing else, it tells you the help information was written when there were only .dst format files and when all file names were in upper case!). Note that the default value shown here is just the last value given to this parameter. This is usually the case with Figaro parameters -- the last value used is the default. The rest of the stuff about entering `\' or `!!' hints at further capabilities of the parameter system, which we will come to later.

You can get more details about a specific command using the standard `help' facility provided with the system. The output is different from system to system (VMS has a rather more nicely structured help system than does UNIX), but either `help exam' (VMS) or `man exam' (UNIX) will produce something useful:

8. Displaying an image

Of course, having got a Figaro format file that you know contains a reasonably interesting image, you'll want to display it as a picture, not just the list of numbers produced by `exam', no matter how intrinsically interesting the details of the file format might be. Figaro provides an `image' command for this purpose, and an image display subsystem that works with the `image' command.

The image display subsystem differs from system to system -- the VMS version of Figaro supports both X-based displays and the older separate display devices such as the `Ikon' or the `Args', while the UNIX version only supports X-based displays. For the purposes of this introduction, we'll concentrate on X-terminals. The commands needed to setup the display differ slightly from system to system, but usually this is what is required. Here, `XtermName' needs to be the name of the X-terminal you are using (mine is `AAOXTF', you'll need to find out what yours is). If you're using the console of a workstation, you don't need to bother with the bit involving the terminal name.

UNIX VMS

$ setenv DISPLAY XtermName:0 $ xon XtermName

$ figdisp $ figdisp

In both cases the result should be an image display window starting up on the X-terminal. The way the displays work is rather different in the two systems, but the way the `image' command work is the same for both.

The `image' command has a large number of parameters, but the easiest way to use it introduces two new features of the Figaro parameter system, and for the case of the n6770 data file is as follows:

$ image n6770 res \\

This syntax is worth remembering -- both `image' and the line graphics display command `splot' work well using this syntax. (Actually, Figaro only requires a single backslash, but since this is a character with special significance to UNIX, it has to be specified under UNIX as a double backslash. All but the most recent VMS versions of Figaro only expect a single `\', and are confused by a double backslash, but the latest versions accept any number of them, so as not to confuse people switching between the systems.)

The `res' is short for `reset', and says: `set all the parameters for the command to their "reset" values.' All parameters in Figaro have both `current' values -- the last values used -- and `reset' values, which are values determined by the program as sensible defaults. In some cases, the program really has no idea what might be sensible, but in the case of `image' the reset values for the parameters cause the whole of the image to be displayed (not just a subset, which can be selected by the use of various parameters), and with a scale determined automatically by looking at the data. There are some perverse images that don't display nicely with this scaling, but most do and it's worth trying it first. So this single `res' has set all the parameters to some fairly sensible values.

Well, all the parameters bar one. You notice the name of the object to be displayed is specified explicitly on the command line. The first parameter for `image' is the name of the object to be displayed, so `image' will assume that that's what `n6770' means. There isn't any sensible reset value for the name of the image -- actually, a blank is used, which would force `image' to prompt you for it if you didn't specify it explicitly. `Reset' really means: `use the reset values for all the parameters not specified explicitly on the command line'.

Having specified all the parameters in one go with `reset', you don't want to be prompted for them all one by one. That's where the `\' comes in. It means: `don't prompt for any unspecified parameters'. In the absence of the `reset' on the command line, the `\' would mean: `use the default values of the parameters, that is, the values used last time'.

There isn't room here to describe the `image' parameters in detail. The easiest way to find out about them is either `man image' (UNIX) or `help image' (VMS), or just give the `image' command and see what happens. For more details about the `figdisp' display server, see the document on `Using Image and Figdisp'.

9. Plotting a spectrum

Figaro thinks of any one-dimensional data array as a `spectrum'. The `splot' command (for `spectrum plot') displays such a spectrum on a graphics terminal. Before the `splot' command can be given, however, it needs to know just which device to use, and it needs to know what type of device is being used.

The way the device is specified differs between the VMS and UNIX implementations. It may help you to know that Figaro uses the `PGPLOT' package originally developed at Caltech by Tim Pearson for its line graphics, but on a VAX it uses the Starlink version of PGPLOT, and on UNIX it uses the original Caltech version. The main difference is in the way the display device is specified. The VMS (Starlink) version uses a set of pre-defined names, which specify both the device and its type. For example, under VMS, you might use

soft xwindows (VMS)

to specify the X-windows graphics server (GWM) provided by Starlink, or might use

soft tek (VMS)

to specify that your default terminal is to be used and that it is a Tektronix emulator (nowadays this is most often used when logged on over a modem using a terminal emulator that supports Tektronix protocols -- there are relatively few actual Tektronix displays being used now).

Under the Caltech PGPLOT used by Figaro under UNIX, the specification used is always of the form `device/type', where `device' specifies the device to be used (and defaults to something sensible, usually your logged in terminal) and `/type' is used to specify the device type. The most common device used for the UNIX version of Figaro is the graphics window provided by the `Figdisp' display server, which is specified as:

soft /xdisp (UNIX)

and the default terminal as a Tektronix display (usually an emulator) is specified as:

soft /tek (UNIX)

Having set that up, a spectrum can be displayed using `splot'. The simplest form of the command is

splot myspec res \\

Again, as in the case of the `image' command, `splot' has a set of reset parameter values that display the whole of the spectrum, scaling it so that all of the data fits into the display. `splot' has a large number of parameters to control the details of the display, including a number of `hidden' parameters. You can find out about these either directly, by asking the on-line help provides, using `help splot' (VMS) or `man splot' (UNIX). Or you can find out about them experimentally, just giving the `splot' command and waiting to see what you are prompted for.

10. More about the Figaro parameter system

The various examples so far have shown you something of the Figaro parameter system in action. It is worth knowing how to get the best out of the parameter system, since it represents your main way of controlling the way Figaro programs run. There are a number of features to the parameter system, some fairly obvious, some obscure but often useful such as the `\' used to suppress parameter prompting, and some that are just obscure (being able to enter floating point numbers in hexadecimal, for example).

There is a fairly comprehensive document describing the details of the parameter system from the user's point of view, but it is fairly long and dry. It may be worth summarising some of the more useful features at this point.

All parameters have names, and can be specified on the command line if you know the name (or an accepted abbreviation), using the form `name = value'. You can even miss out the equals sign. Keyword parameters can just be specified by name -- if you give the name in the command line the keyword is true, if you preface the name with `NO' then it is false. However, you can also specify keywords as `name = YES' or `name = NO' if you prefer.

Parameters are character strings, floating point numbers, arrays of numbers, or keywords. Generally speaking, the parameter system expects the values for most of the numeric and character parameters to remain the same from one invocation of a command to the next, while keywords are used as a sort of one-off switch to turn on or off some specific behaviour for just the current invocation of a command. This works well for display-type commands such as `image' or `splot', where one often displays the same data several times, each time changing just only a few parameters -- the image scale, for example -- and now and again wanting to invoke some one-off behaviour such as suppressing the erase before a spectrum is plotted.

So the default value for a character or numeric parameter is usually just the last value it had, and unless you explicitly change it this is what you will get. So, `splot' will always plot the same spectrum until you change it, since the default value for its `spectrum' parameter will be the last value you gave it.

However, the default value for a keyword parameter is set by the program and is always the same. So `splot' has an `erase' keyword that it always sets to default to `true', and if now and again you want to suppress this (to plot one spectrum on top of another, for example) you have to specify `noerase' in the command line.

Figaro programs often have a number of quite obscure parameters that you don't normally want to be bothered with. You are not normally prompted for these `hidden' parameters. However, if you specify `prompt' (or just `pr') on the command line, you will be prompted for all the hidden parameters as well as the more common ones.

The backslash character `\' can appear on the command line to indicate that any unspecified parameters are to take their default values. Note that this has to be given as `\\' on UNIX systems, since most UNIX shells interpret `\' as an escape character, and need `\\' to specify a literal single backslash character.

When a program asks for the value of a numeric parameter, it specifies a maximum and a minimum value for the parameter. If you give a value that is out of range, you will be asked to enter another value. These values are often ones that you might want to use; for example, the maximum and minimum values for the range of pixels displayed by `image' is set by the size of the image, and you might well want to specify that the whole image should be displayed. You can specify a numeric parameter as `max' or `min' to get those limit values.

Parameter specifications may include expressions enclosed in {braces}. These are usually numeric expressions involving constants and named variables, such as `{stat_max*0.9}'. If they appear in the specification for a character string, the resulting number is formatted and included in the string.

It is possible to specify a number of successive values for the same parameter, in which case the program is rerun as many times as necessary, each time using the next value for the parameter. Such a succession of values may be specified either by putting the values in a disk file and specifying the parameter as `@filename', or by including in the parameter specification an expression that is evaluated as a sequence of numbers, such as `{1:5}', which specifies the sequence 1,2,3,4,5. The use of sequences of parameter values is discussed in more detail in the next section.

11. Repeating the same operation on many files

Commands like `image' and `exam' are ones you tend to use to find out about files. What you do next often depends on what you find. However, there are many cases where you want to execute a pre-determined sequence of Figaro commands. This can be handled in a number of ways in Figaro, although the most common method is to make use of the fact that all Figaro commands act as if they are commands accepted by the operating system's normal command language (at the `$' prompt), and so can be executed as sequences of such commands using the facilities provided by that command language. So under UNIX you can write a shell script (for whatever shell you prefer), under VMS you write a DCL procedure (a .COM file).

However, without going into the complexities of programming command language scripts, there are some repetitive operations that can be handled easily just using the Figaro parameter system. These are the cases where the same command is run on a number of different files. For a specific example, let's introduce the `icadd' (`image constant add') command. The command

$ icadd n6770 42 scrap

will add the value 42 to every pixel of the image in the file n6770 and will create a new file called `scrap' to hold the resulting image. As a variant on this command, having done that previous operation you could then try

$ icadd scrap -42 scrap

This subtracts the value 42 from each pixel of the image in the file `scrap'. The resulting image is specified as `scrap'. Most Figaro programs will allow this, and treat it as a special case. This does not result in the creation of a new file called `scrap' (which in UNIX, but not in VMS, would replace the existing one -- in VMS a new version of the file would be created). Instead, the operation is carried out in situ -- on the data in the original file. This is usually much faster than creating a new file; but it means the original data is lost should you decide you didn't actually want to do that. (Not all actions are as reversible as adding a constant).

The resulting `scrap' file now holds the same data as the original `n6770' file. You could check that with `exam' or with `istat'.

Now this is the sort of operation you might want to perform on a large number of files. You might, for example, want to subtract the same bias value from a number of CCD images. The Figaro parameter system provides two ways of doing this; you can read a set of parameter values from a file, or you can use `incrementing' parameters. The latter only work if you have a suitable naming convention for your files, so first we'll cover the use of a file of parameter values.

Say you have a set of CCD images called `run1', `run2', `run3' etc. up to `run10', and you want to subtract a bias value of 42 from them all, and want the resulting files to be called `run1sub', `run2sub', etc.

You can create two text files, one called `input.lis' and the other called `output.lis', as follows:

input.lis output.lis

run1 run1sub

run2 run2sub

run3 run3sub

..etc.. ..etc..

run10 run10sub

How you create these lists is up to you, and will differ from system to system. However, both VMS and UNIX provide directory listing commands that can be made to produce output lists that can then be edited (or may not even need editing) to produce the required files. having got those files, the single command

$ icadd @input.lis -42 @output.lis

will do exactly what you want. The `@' syntax tells the Figaro parameter system to read the values for the parameter from the specified file, and to repeat the operation until the end of the file is reached. (Obviously, with two such files, you need to be sure that both have the same number of values in them.) The constant to be added (-42) doesn't change, so can be specified explicitly on the command line.

There are a large number of variations on this theme, but this introductory document is not the place to go into much more detail. The additional detail can be found in the document called `The Figaro Parameter System'. However, just to whet the appetite, under UNIX you can do:

$ ls *.sdf > files.lis (UNIX)

$ icadd @files.lis -42 @files.lis (UNIX)

This subtracts 42 from the main data array in every .sdf file in the default directory - the operation is performed in situ, on the data in the input file.

As it happens, the file names chosen in the previous example (`run1', `run2', etc.) can also be handled using the `incrementing parameter' technique. Here, a syntax is used which specifies a range of values at a time:

$ icadd run{1:10} -42 run{1:10}sub (VMS)

(Unfortunately, under UNIX, the curly braces are usually interpreted by the command shell, and to prevent this the command shown above has usually to be given under UNIX as:

$ icadd 'run{1:10} -42 run{1:10}sub' (UNIX)

where the quotes prevent the UNIX command shell interpreting the braces for itself. A number of the more complex Figaro commands have to be given enclosed in quotes under UNIX, which is a shame.)

The specification `run{1:10}' is an incremental specification that generates a sequence of 10 names, `run1', `run2', up to `run10', and the `run{1:10}sub' specification, as you might expect, generates the sequence `run1sub', `run2sub' up to `run10sub'.

A minor variation on this theme can be used in the case where your files are named something like `run0001', `run0002', etc up to `run0010'. (The AAO observing systems generate file sequences like this.) In this case, you can use the syntax:

$ icadd run{0001:10} -42 run{0001:10}sub

Here the leading zeroes in the specification are respected by the Figaro parameter system, to generate the required set of file names. (If you specify `0001' the system will use at least 4 digits to format the sequence of numbers it generates, using leading zeroes where necessary.)

12. Callable Figaro

The `callable Figaro' interface provides a way for a Fortran program to run sequences of Figaro programs. In essence it provides a subroutine called `figaro' which can be called with a character string argument that contains a Figaro command to be executed. There are a number of additional features that make it easier to format the character string argument conveniently, particularly when complex sequences of commands are being given by a program using callable Figaro. The `callable Figaro' interface provides an alternative to the use of command language scripts to run sequences of Figaro programs. More detail can be found elsewhere in the Figaro documentation.

13. User Variables

You will probably not need to know much about the Figaro `user variables', but you should at least be aware of them. They are mainly used to provide a means for the different Figaro programs to communicate with one another, but since they are used in this way it is possible to use them to influence the way a sequence of Figaro commands operate, or to get additional information about a Figaro command once it has completed.

For example, the `soft' command sets a user variable called `soft'. The command

soft /xdisp

sets the variable `soft' to the character string `/xdisp'. The `splot' command picks up the value of the `soft' variable and uses it to determine which device it is to plot on, and what the type of the device is (in this case, the default device running the `figdisp' display server, which provides a line graphics display that `splot' and other graphics packages can use.). Note that `soft' is a Figaro command that happens to work by setting a user variable of the same name. Don't be fooled by the example into thinking you can set any variable just by typing its name followed by a value; for that you need the `let' command, which allows you to do things like

$ let fred = 10

The variables are also used by programs to remember the values of parameters. For each parameter there is a corresponding variable of the same name, and this variable is always set to reflect the current value of that parameter. Then when the same program is run again, it uses the value of that variable as the default value -- this is how the defaulting rule of "the same value that was used last time" works.

Most of this would not affect the user at all, except for a feature of the parameter system, which is that a variable name may be used instead of a constant in a command. For example, using the `let' command to set user variables allows you to have a sequence such as

let string="myspectrum"

let first=100

splot spect=string,xstart=first

which will have the same effect as

splot spect=myspectrum,xstart=100

although the first form is much less efficient. This feature is of use in a sequence such as

istat image=myimage reset \\

image image=myimage high=stat_max low=stat_min

since `istat' determines, amongst other quantities, the maximum and minimum pixel values in a specified range of an image. The reset settings for `istat' are simply the extreme values, so the first command determines the maximum and minimum values in the whole of the image `myimage'. `istat' lists the results, which is all that most people see, but it also sets some user variables, including two called `stat_max' and `stat_min' which are set to the maximum and minimum data values in the specified range. The `image' command shown here then displays the image using these values for the scale limits. This sort of thing becomes useful when automatic sequences of commands are being set up.

Note that it is also possible to use user variables in expressions evaluated by the parameter system. For example, the display limits could be specified as follows to get a bit of headroom in the values used.

istat image=myimage high={stat_max*1.1) low={stat_min*0.9}

However, there is sometimes an ambiguity introduced as a result of this feature. For example,

splot spect=myspect

will normally result in a spectrum called `myspect' being plotted. However, if a variable called `myspect' exists, what will be plotted will be determined by the value of that variable. For this reason, it is a bad idea to call images `image', or spectra `spectrum' since these are almost certain to be the names of user variables. If you must- -- but please try to avoid it --you can sidestep the ambiguity by using quote marks:

splot spectrum="spectrum"

This is not normally a problem, but if you do get unexpected errors it is worth checking to see if you might be running into it. One way to check is by specifying the `list' keyword, so you can see just what values the program is using. This would be avoided if the parameter system evaluated named user variables when they appeared in expressions, enclosed in {braces}, and treated all others literally, and this modification as been mooted. However, it would break a number of existing Figaro command scripts, so has not been implemented yet but is still being considered.

The `vshow' command can be used to show the value of user variables. For example, `vshow' on its own lists all the user variables presently defined, `vshow tv*' lists all the user variables beginning with the characters `tv'.

(A technical note: The variables are held in a structure file called `vars.dst'. This is why this file keeps turning up in your directory structure whenever Figaro is run. The directory in which this appears can be controlled by the use of UNIX environment variables or VMS logical names, but normally it appears in a scratch directory under VMS and your login directory under UNIX. If the `vars.dst' file gets deleted, it usually doesn't matter -- it just means that the system will forget all the parameter values in use at the time. Sometimes, the file can get corrupt; if you have problems that seem to be connected with variables, try deleting it.)

14. Figaro Commands - A Brief Overview

There will be no attempt made here to describe all the Figaro commands, but a brief introductory discussion may be in order.

Figaro is best thought of as a set of tools. It does not attempt to force any particular sequence of data reduction operations on the user; rather, it attempts to provide low-level facilities that the user may use in whatever sequence he or she chooses. For example, Figaro does not provide a single flux-calibration program; since different types of data need to be treated in different ways, Figaro provides a number of operations that form part of flux calibration sequences, and allows its users to build their own sequence out of them, using their own judgement as to the best way to handle his data. The section headed `fluxing' in the `techniques' documentation provides details of the flux calibration routines.

Although the ideal is never realised in practice, Figaro routines try to be as general as possible. People disagree about the point at which data should be reduced to a linear wavelength scale (scrunched), since this rebinning introduces errors. So as far as possible, Figaro routines do not insist on having scrunched data as input. Equally, people disagree about whether wavelength information should be represented by `ordinary' polynomial coefficients, sets of spline fits, or whatever. So the basic Figaro spectrum has an array giving the wavelength values for the centre of each channel, this being the most general way of expressing a wavelength/channel relation, and these wavelength values may be obtained in any way the user wishes. (In practice, the Figaro `arc' command is the only supplied way of obtaining these values, and this uses polynomial fits. However, Figaro places no obstacles in the way of those users who want to write their own arc fitters and produce spectra which have wavelength values obtained in some other way.)

So far as possible, calibrations --filter response, flux calibrations, etc. --are performed by generating a calibration `spectrum' and multiplying the spectrum to be calibrated by it. This is because Figaro has numerous functions that can be used to `fudge' spectra, and if calibration values look like any ordinary spectrum then these fudging routines can be applied to them. (It is an observed fact that most calibration processes often involve fudging the calibration values to some extent.)

Figaro uses only two types of files; text files, and data structures. Calibration tables are kept in text files, arcfit results are written out to text files, etc. Data structures are files that hold data -- spectra, images, and so forth -- in hierarchical structures with all the components named. For more details, see the Figaro Programmers Guide; the important point here is that all the data held in such a file can be easily accessed -- and modified -- through commands such as `exam', `let', `crobj' and `delobj'. This means that all Figaro files are easy to modify, and there are a large number of dirty tricks available involving either a text editor or one those commands.

Currently, most Figaro application programs operate either on one dimensional data (spectra) or on two dimensional data (images), although there are a few commands that manipulate data cubes and even a couple that handle the data hypercubes generated by the AAO instrument, `FIGS'. As a general rule -- but one not at all strictly adhered to -- commands that deal specifically with spectra begin with `s' --`splot' for example. Commands that begin with `i' operate on images. Remember, however, that a spectrum is just an image with one dimension equal to one, and most image commands will work on spectra as well. That is why there is an `iadd' command, but no `sadd' command. `Iadd' will work on any pair of data arrays that have the same dimensions, no matter how many dimensions they have. Similarly, many -- but by no means all -- commands that work on spectra will work on data arrays of higher dimensionality, treating them simply as sets of separate spectra, each of which is handled individually.

A full list of Figaro commands may be obtained from the `Figaro Commands' document, which also includes lists of commands divided into various categories. A good place to browse around is the documentation on `techniques'.

15. Setting up to run Figaro

If Figaro is already installed on your system, very little is normally needed for you to be able to run it. If it is not installed, then this will have to be done first, and this is too large a topic for this document. You need to refer to the installation notes provided with the system.

15.1. UNIX systems

On a UNIX system, you need to know where the main Figaro programs are located. In this directory, there is a file called `figarodef_unix.com'. To define the `figaro' command, you need to `source' this file (it sets environment variables, which is why you have to use `source' instead of executing it in a separate process). The only way to find its location is usually to ask someone who knows -- either a Figaro user, or whoever did the initial installation, in most cases. On some systems, a phoney user called `figaro4' is provided so that the `source' command can be reduced to just:

source ~figaro4/figarodef_unix.com

If you try this and all you get is `no such user', then you do need to know the full path for the main Figaro directory. Assume this is `/data/figaro/figaro'. In this case, the `source' command needs to be:

source /data/figaro/figaro/figarodef_unix.com

This command can reasonably be placed in your .cshrc file, if you are running `csh' or some compatible command shell. Once this command has been sourced, the `figaro' command is defined and should work as described at the start of this document.

15.2. VMS systems

On a VMS system, the main Figaro programs will have been installed in a directory which should be given the logical name `FIGARO_PROG_S'. Usually, this is made a system logical name, and is available to everyone with no further action being needed. Usually, the `FIGARO' command is also defined for general use, in terms of this logical name. If this is not the case, then you need to define both the logical name and the command for yourself. First you will need to discover just which directory is being used, which means asking someone who knows! For the purposes of this discussion, let's assume it is

DISK:[FIGARO.FIGARO]

In this case, to define the required logical name for yourself, you need to give the command:

DEFINE FIGARO_PROG_S DISK:[FIGARO.FIGARO]

This is the sort of command you normally put in your LOGIN.COM file, so it is executed automatically when you log in. Now, if you define a command `FIGARO' as:

FIGARO:==@FIGARO_PROG_S:FIGARO

this `FIGARO' command will now start up Figaro as described at the start of this document. The definition of the `FIGARO' command normally goes in your LOGIN.COM file as well.