Figure 1: Example GWM spectrum.
In order to run any Starlink software, your Unix startup must be adapted appropriately. If you work at a Starlink site, chances are that your site manager has already taken care of this.
It is necessary that you use a Unix shell similar to the C shell. A Unix shell is a command line interpreter between you and the Unix operating system. When you log into the Unix system one or another shell will be started for you, namely the one that is your ‘login shell’. The most basic Unix shell is the Bourne shell ‘sh’, but the most common interactive shell is the C shell ‘csh’. Some system administrators may try to educate you to use more fashionable shells like ‘korn’ or ‘bash’.
The Starlink startup scripts all assume that you use the C shell, but a similar, enhanced shell is ‘tcsh’, and this is what probably most users of Starlink software have as their login shell.
When you login, the login shell will execute two scripts in your home directory. One is ‘.cshrc’, or Tc shell users may have a similar file ‘.tcshrc’ instead. The second startup script is ‘.login’.
What you have to do to make Starlink software work, is to include one command in each of these two files. In ‘.cshrc’ or ‘.tcshrc’ you insert the line
and in ‘.login’ you insert the equivalent
Figaro and other Starlink packages use a common mechanism for providing input values to, and obtaining output values from, individual applications. This so-called ‘parameter system’ allows values to be passed between related applications, saves un-necessary typing and assists the applications in suggesting sensible default values. The details are not germane here, but files containing the parameter values passed between applications need to be kept somewhere. By default these files reside in a subdirectory of your home directory called (for historical reasons) ‘adam’. This directory is created automatically the first time that you run a Figaro (or other Starlink) application. However, you can create it manually if you prefer. You can choose to use a different directory by adding a command to your ‘.login’ script. Say, you want to use directory ‘parameters’ under your home directory, then add
Similarly, Figaro, and other Starlink packages, use the ‘Applications Graphics Interface’ (AGI) to pass graphical information between related applications, allowing them to inter-operate smoothly. The associated files are created in your home directory by default. However, again you can specify their location by adding a line to your ‘.login’ script. For example
It is a good idea to delete these files occasionally, since they grow ever bigger and mainly contain old, useless information. The files are called ‘agi_host.sdf’ and there is one for each machine you have used for Starlink graphics.
There are three different ways of running Figaro:
These alternatives are described individually below. Each has its advantages. If you plan to make only fairly straightforward use of Figaro then it may be simplest to run it from the Unix shell.
To start Figaro from the Unix shell simply type:
and it responds with a message similar to this:
Once you have given this Figaro startup command you have about 200 new commands at your disposal, the Figaro commands (or Figaro applications; In Figaro, and other Starlink packages, commands are often referred to as ‘applications’ because each command corresponds to an application program which performs some data reduction task). Each Figaro application can be invoked by two different commands. One is simply a name describing the application, the other the same name prefixed by ‘fig_’. E.g. the commands ‘istat’ and ‘fig_istat’ invoke the same application. The reason for this apparent duplication is that some common command names can also be used in other packages. The ‘fig_’ prefix allows the Figaro commands to be specified unambiguously.
The Unix shell has some disadvantages in running Figaro commands. The most annoying feature is
that so-called meta-characters like ()[]’" have special meaning to the Unix shell. If you need these
characters to pass information in the command line to the Figaro command, then you have to take
extra steps to make sure the information makes it through the interpretation by the Unix shell. See
Section 3.1.5 for further details.
Of less importance is that the Unix shell does not have floating point variables and arithmetics, and that it has no knowledge of the parameter system used by Figaro commands. Such features are rarely needed; once you get used to handling the shell meta-characters, you should be all right with the Unix shell.
Figaro can also be run from Starlink’s Interactive Command Language (ICL). ICL is a command line interface which has intimate knowledge of the parameter system and of the command line syntax of Figaro commands. When your procedures get really tricky, ICL is probably a better command line interface than the Unix shell. But even in every-day use, ICL saves you masking all those Unix shell meta-characters.
You start ICL with the shell command
Unlike the Figaro startup command, which only defines new commands for the Unix shell, this starts a new process, a new shell if you like. It is thus no big surprise that the prompt string changes to ‘ICL’.
From this shell you start Figaro with
which will respond with the familiar message
The 200-odd Figaro commands are now at your disposal. However, only the short names without the ‘fig_’ prefix are available.
There is a demonstration procedure, which is intended as a test of the installation, but the script itself can give you hints about writing your own ICL procedures and about the syntax for command line parameters. To execute it, you need an X windows display.
To run the demo type:
To run the Specdre demo, which demonstrates how the Specdre Extension is used to e.g. gather fit results and pass them on to other applications, type
Once in ICL, you can initialise further packages, such as KAPPA
Any additional initialisation may write a message to the terminal that some ‘key has been redefined’. This message indicates that the same command name is used in different packages and probably for quite different purposes. The latest initialisation overrides previous ones, and if you are using several packages it might be important to initialise them in the correct order.
IRAF is a powerful and comprehensive package for reducing and analysing optical astonomical data. It was developed at the National Optical Astronomy Observatory (NOAO) in Tucson, Arizona and is now in widespread use around the world. Users run IRAF applications from a command line interface called CL. It is also possible to run Figaro from CL. There are (at least) two reasons for wanting to do so:
The Figaro and standard IRAF applications can inter-operate, so a given dataset can be processed using a mixture of Figaro and standard IRAF applications.
Figaro and IRAF intrinsically use different data formats (the Figaro formats are described in Section 3.2). However, when Figaro is run from the IRAF CL the system is set up so that the Figaro applications automatically convert to and from the IRAF format on input and output respectively. Thus, you will see only data files in the native IRAF format. This conversion happens automatically and invisibly and as a user you will not normally need to be concerned about how it is done. However, one caveat that you should be aware of is that the native Figaro format is more ‘capable’, in the sense that it can contain more auxiliary information such as quality arrays, error arrays, etc. than the IRAF format. Thus, when datasets are written using the IRAF format some of this auxiliary information can be lost.
The procedure to run Figaro from within IRAF is as follows.
(here ‘cl>’ is the CL prompt, not something that you type in). A welcome message and list of commands will be displayed and the Figaro applications can simply be run.
There are various points which it is useful to be aware of when running Figaro, or other Starlink applications, from within CL. The details are discussed in SUN/217.
Figaro applications can inter-operate with applications in various other packages. Running Figaro from the IRAF CL (see the previous section) allows Figaro to inter-operate with IRAF applications.
Figaro applications can also inter-operate with the applications in most other Starlink packages. The most widely useful are probably those in the general purpose image processing package KAPPA (see SUN/95). To start both Figaro and KAPPA from the Unix shell simply type:
In both cases the start-up messages have been omitted for brevity. The order of the two commands is not important. The applications in both Figaro and KAPPA are now available and to a large extent they inter-operate.
The procedures to run the packages from ICL or to inter-operate with other Starlink packages are similar.
Since you are reading this, you obviously found one way of getting help with Figaro. There are different sorts of help you can get:
From the Unix shell you can get help from the on-line help library. Use the command
and navigate through the hierarchy of information in the help library. You can also specify topics and sub-topics as command parameters. The command
returns
Often the most extensive and interesting information is in the sub-topic ‘source_comments’.
The command
returns
You can also get ‘run-time’ help: When a command prompts you for some additional information and you have no idea what it’s on about, try responding with a question mark. You will then get some help on that parameter of that command, and are re-prompted for the parameter. Observe this:
From ICL you can get help from the on-line help library. Use the command
Help on the commands is also available by giving them as the topic, use e.g. ‘help istat’, not ‘help figaro istat’. Topics other than commands (news, classified list of commands) are available only as follows:
Run-time help is available in the same way as from the Unix shell.
The most comprehensive help for Figaro is the extended, hypertext version of SUN/86 available via the WWW. To access this document on a Starlink system simply type
Otherwise use URL
Figaro also has a WWW ‘home page’ at URL
If you cannot find the information that you need or if you think that you have found an error in Figaro then you can contact Starlink for advice and assistance. In the first instance you should send an e-mail message to username
Suppose you have a data file ‘a_file.sdf’ with a spectrum, i.e. a one-dimensional data set and want to plot is on an X display. This is probably the most commonly used Figaro command, and it is called ‘splot’. Many command names begin with an ‘s’ for spectrum or with an ‘i’ for image. However, before we can plot anything, we need to tell Figaro what our plotting device is.
Consider the following sequence of commands:
The first command is necessary if your X display ‘server’ is not the same as the ‘client’ machine running Figaro for you. It passes the remote client the identity of the local server. You have to declare ‘xdisplay’ each time you log onto the remote client.
Conversely, you may also have to reveal the identity of the remote client to the local server, say with an ‘xhost’ command. Otherwise the remote client may not be allowed use the local server as a display.
The second command tells Figaro which graphics device you want to use. ‘xw’ is an abbreviation for ‘xwindows’. Together with the information from ‘xdisplay’ this is sufficient to open the window. You should now get a display window on your screen, and a box with the word ‘PGPLOT’ in the centre is drawn into the window. You need to give the ‘soft’ command only once. Figaro will always remember that you want to use the device ‘xw’.
The third command finally displays the spectrum contained in the file ‘a_file.sdf’. Data files can have names ending with ‘.sdf’ or ‘.dst’. They must not contain any additional periods. The Figaro commands know about this, and must not be given this file name extension.
Don’t worry about the size of this window. By default you get about 700 by 500 pixels, usually big enough to read the axis labels.
The word ‘accept’ looks like a parameter to the ‘splot’ command. Actually you can use it on any command. It prevents the command from prompting you for information that it can guess itself.
Now consider this more complex sequence of commands. It achieves the same thing, basically.
The ‘xdisplay’ command now tells the remote client explicitly what the Internet host name of the local server is. This is necessary when you log on indirectly, via a third host.
There is also an extra ‘xmake’ command to create the display window explicitly. This way, we can tell it the size and shape of the window, and the colours for background and lines. You can make your personal preference permanent by specifying resources for ‘xmake’ in your ‘.Xdefaults’ file. If you look at the paper copy or on a black/white display, you will notice that this is not a good choice of colours, since the grey values for blue and green are rather similar.
‘xmake’ is paired with a command ‘xdestroy’, which you can use to get rid of the graphics window. That is necessary before you ‘xmake’ it with different parameters, or when you have too many windows on your display.
The ‘splot’ command is different in a number of ways. Before, we had given the input data set as the first parameter. When we are not sure about the sequence of parameters, we can specify them by name. For most Figaro commands that work on spectra as opposed to images, the input data are specified in the parameter called ‘spectrum’.
Next, we have specified the ‘whole’ parameter as false, so that this time we can choose only part of the spectrum to be displayed. We also left out the ‘accept’ keyword, that is why the command asks us a number of questions while it runs.
Suppose you have a data file ‘a_file.sdf’ with an image, i.e. a two-dimensional data set and want to plot is on an X display. This is one of the most common actions in Figaro. Most users will use the ‘image’ command for this purpose. In general it uses a different display window than where most other plots go. The idea is that most plots are line plots and their device is selected with the command ‘soft’. But ‘image’ should display at least in grey, if not in false colours. So you have to specify the imaging device separately, although it can be the same actual device as the ‘soft’ device.
Consider the following sequence of commands:
If you are not familiar with the necessities of using X windows over the computer network, see Section 2.4.
The second command tells Figaro which graphics device you want to use. ‘xw’ is an abbreviation for ‘xwindows’. Together with the information from ‘xdisplay’ this is sufficient to open the window. You should now get a display window on your screen, and a box with the words ‘PGPLOT imaging’ in the centre is drawn into the window. You need to give the ‘idev’ command only once. Figaro will always remember that you want to use the device ‘xw’.
The third command changes the display window to show various levels of grey as representation of the image data values. A new display window may have an undefined ‘colour lookup table’, or a different plot command may have changed the lookup table. The ‘colour’ command with parameter ‘grey’ always brings it back to normal.
The fourth command finally displays the image contained in the file ‘a_file.sdf’. Data files can have names ending with ‘.sdf’ or ‘.dst’. They must not contain any additional periods. The Figaro commands know about this, and must not be given this file name extension.
The keyword ‘accept’ prevents the command from prompting you for information that it can guess itself. Unfortunately, you don’t know what it did guess, and you might never learn how you can exert more control over the display.
Now consider this more complex sequence of commands.
If you are not familiar with the necessities of using X windows over the computer network, see Section 2.4.
In the first ‘image’ command the keyword ‘prompt’ is used. While ‘accept’ suppresses prompting as far as possible, ‘prompt’ causes any command to ask you everything. This is a good way of learning the capabilities of commands, but it also causes some spurious prompts like the ones for ‘idev’, ‘imarray’, and ‘imfile’. You should just accept the defaults offered for these parameters.
The first thing we learn through the ‘prompt’ keyword is that ‘image’ could have ‘displayed’ to a printer file instead of a screen window.
We chose to erase the window this time. That gets rid of the remainders of the original plain box. Via ‘ystart’/‘yend’ and ‘xstart’/‘xend’ we can select only part of the image to be displayed. Since we want the whole image and are not sure about the offered default, we use the words ‘min’ and ‘max’. This time, we set ‘negative’ true: The image file contains a negative, negating it during display makes is look positive. With ‘xplaces’/‘yplaces’ we could sub-divide the window into an array of sub-windows and display into one of them. We leave ‘aspect’ true so that image pixels are displayed as squares. Otherwise the display would be stretched horizontally to fill the window.
Having displayed the whole image, we now run ‘image’ again, but display only part of it. We also set ‘xplaces’ zero. That means, we can specify the display area in pixels. Since we do not erase this time, the previous full display remains partially visible.
While reading Section 2.5.1 you may have wondered why the command to choose grey levels is called ‘colour’. Because it can be used to load an existing colour lookup table. This can be done before or after ‘image’. To put some colour into the display we already have:
There are a number of prepared colour lookup tables. They are ‘.sdf’ files, similar to other data files. By convention their names end in ‘_lut.sdf’, and they are stored in a directory pointed to by the Unix shell environment variable ‘FIGARO_PROG_S’. To see a list of colour tables in that directory:
Finally, how do you prevent line graphics from resetting your image display? You will recall that the line graphics device is selected with ‘soft’, while the imaging device is selected with ‘idev’. You can simply choose separate windows. Consider this:
This will separate the output into two windows. There are four windows possible, but notice the different names in ‘xmake’ and ‘soft’/‘idev’. The ‘-c’ options also reduce the line graphics window to the 16 colours reserved for this, and increase the imaging window to 128 colours.
If for some reason you cannot use ‘image’ to display images, you can still display them as contour plots or as dithered grey plots. This works even when the display window has only two colours, say when you have a b/w X terminal. Like spectral plots (Section 2.4) these plots go to the ‘soft’ device.
If the display window has more than 16 colours, ‘igrey’ will use those resources and display with true grey levels. It will also reset the window colours to grey. Well, strictly speaking the colours are not grey, but go linearly from the background colour to the foreground colour. If you choose pink and green for fore- and background, you can get quite a hideous composition.
In order to get paper copies instead of screen plots, you will usually use the ‘hard’ device instead of the ‘soft’ device. (Finally you understand why it’s called the ‘soft’ device!) Similar to the commands ‘soft’ and ‘idev’ there is a command ‘hard’ to tell Figaro once and for all what your hard-copy device is:
The main hard-copy devices these days are PostScript files—files, not printers! This means your plots go into a series of files. The first is called ‘gks74.ps’, the second is ‘gks74.ps.1’, the third ends with ‘.2’, and so on.
It is a bit difficult to keep track of these files. E.g. after you created three files you might delete the second. The fourth plot may then use the free name and appear to be the second plot. Also, if an application erases the graphics device before plotting, you might get two files: If you ‘print’ the first, you may just get a blank sheet of paper from the printer.
You can use ‘ghostscript’ (Unix command ‘gs’; see SUN/197) or, more simply, ‘ghostview’ to view the plots on the screen before you print the wrong one. E.g. type:
There are a number of PostScript devices you can choose from. When ‘hard’ prompts for the device, you can try ‘options’ to get a list of possible replies. The PostScript devices are:
Before you get enthusiastic about Colour PostScript, it is not possible to use the ‘colour’ application in conjunction with a printer device. This is because ‘colour’ would write its own PostScript file and the information does not go into the PostScript files with the actual display. You need something like KAPPA’s command ‘display’, which can load a colour table immediately before displaying the image. In Figaro the only use for Colour PostScript is probably to get coloured line plots where the applications support this.
The difference between the ‘ps’ and ‘epsf’ devices is that the former are complete and intended to be sent to the printer. The latter are incomplete and intended as elements of more elaborate PostScript documents. You could combine several EPSF files into a single PostScript file, or you could include EPSF files as figures in a TEX or LATEX document. The figures would be included during processing with ‘dvips’.
Consider this example:
We choose the portrait orientation for Encapsulated PostScript. This is helpful for later inclusion in a LATEX document, since it is usually printed in portrait orientation as well.
We use ‘igrey’ and ‘icont’ to produce plots of two images that have the same number of pixels per degree on the sky, and we choose the same part of the image. The two applications also use the same part of the display device. You might be tempted to use this sequence for an overlay on the screen, but ‘icont’ will wipe out the plot that ‘igrey’ made.
We use the ‘hardcopy’ keyword to direct the plots to the ‘hard’ device rather than the ‘soft’ device. The result are two files ‘gks74.ps*’.
Instead of printing each on its own piece of paper, we use the ‘psmerge’ utility (see SUN/164) to combine the two into a single figure. ‘psmerge’ can not only combine several EPSF files, it can also scale, shift and rotate each EPSF graphic individually in the process. The ‘-s’ option scales the graphs to half the size in and in .
The ‘-e’ option here means that the output is again EPSF rather than PostScript. The idea is that we want to include ‘hardcopy.eps’ in the LATEX version of this document like such:
We are cheating here, because the GKS EPSF files have an unsuitable ‘BoundingBox:’. You have to edit these files and move one line from the end of the file to the beginning: There are two lines in the EPSF file that begin with ‘%%BoundingBox:’. At the top of the file it says ‘(atend)’ and at the bottom of the file it says e.g. ‘0 0 271 395’. The line at the end must be moved to where the first line is, and the first line must be removed. Since PostScript files contain plain text, you can use the ‘vi’ editor to do this.
Also, this BoundingBox is somewhat too large, it contains not only the graphic but some white space. You can use ‘ghostview’ to display the EPSF file. Its cursor position is constantly displayed, so you can move the cursor to the actual corners of the graph and thus find out better numbers for the BoundingBox.
Instead of ‘igrey’, you can used ‘image’ of course to make use of its histogram optimisation. You will find it very difficult to align it with any contour plot though.
Many line plot commands have a ‘hardcopy’ keyword to choose between the ‘soft’ and ‘hard’ device, or between the ‘idev’ and ‘hard’ device. However, some don’t and others use both devices for different plots.
If you actually tried to enter ‘options’ as hard device you will have noticed that the list contains the screen devices as well. In fact there is no principal difference between all those devices, each can be selected as ‘soft’, ‘hard’, or ‘idev’ device. The three commands to select the three devices just help Figaro to remember more than one device name and to channel the right output to the right device. You can send your hard-copies to the X screen and your screen plots into a PostScript file!
This is a valid option. If there is an application that sends your favourite plot always to the screen, you can
and all your plots go into PostScript files. Note that you should use the ‘draw’ keyword to suppress the creation of an extra page with the frame plotted by ‘soft’ and ‘idev’.
If you have displayed an image with ‘image’ (Section 2.5.1), you can use ‘icur’ to move a cursor over the image. Stop at a point of interest, and you can be told the coordinates and data value of that point.
On the first three positions ‘d’ was used, on the latter three the space bar. ‘Recording’ a pixel does not tell you its brightness, but the position is stored for future use.
If you used ‘igrey’ or ‘icont’ to display, (Section 2.6), then you can use ‘igcur’ in a similar way to find out about pixels.
Another useful inspection command is ‘istat’. It does not need any display, but works on the data directly.
With Figaro you can not only look at data that happen to be lying around, you can also process data and thus change the contents of data files. The simplest operations are adding or subtracting a constant, or multiplying or dividing a constant into a data set. These four commands are ‘icadd’, ‘icsub’, ‘icmult’, and ‘icdiv’.
If you compare the statistics of the old ‘a_file.sdf’ and the new ‘b_file.sdf’, you will find that 25 has been added to each pixel value.
What happens if you give for ‘output’ the same file name as for ‘image’? In most cases this is possible. You will then not get a second file, but the first file will be modified to contain the new data.
What if you have a spectrum and not an image? Usually that does not matter. When a command asks for the ‘spectrum’ parameter it usually has to be a spectrum. But when it asks for the ‘image’ parameter you can in most cases give a spectrum instead.
You can also use two images as operands instead of an image and a constant. The commands for this are ‘iadd’, ‘isub’, ‘imult’, and ‘idiv’.
The first operand is overwritten with the result.
