The main changes are
The on-line help is mainly what was the ‘commands.hlb’ library. It includes all the new prologues. Also the hierarchy was changed so that it is in line with the (A)PAR parameter system run-time help.
The general help ‘figaro.hlp’ as in Figaro 3.0 was not ported. Much of the information is not exactly applicable to Portable Figaro. The user guide was identical to that help library. The relevant parts were updated and included in this document. That user guide also made references to further documents that existed only on-line. Those were also reviewed and included in this document.
The on-line help is complemented by the printed version of Starlink User Note 86, and both are combined in the Web version of SUN/86.
The Figaro Programmers’ Guide of January 1991 is largely still valid, apart from section 12. A recipe for building VAX/ICL monoliths from Figaro-ish applications was outlined in section 3.3 of SSN/40. However that is not exactly applicable under Unix; refer also to the section for programmers in this document. And note that Figaro is no longer recommended as a programming environment. New software should use Starlink libraries.
The port started out from Standard Figaro version 3.0 as modified and extended by Starlink/UK National Figaro version 3.0-6. These are releases for VAX machines. The DTA library had been ported by Keith Shortridge in early 1992 and had been released in Sun Figaro version 2.4.5 patch 5. The DSA library has been ported in August 1992 by Keith Shortridge with contributions from Horst Meyerdierks. A small number of routines that were in VAX Macro or in VAX Pascal have not been taken from Figaro 3.0. Instead their C or Fortran counterparts in Sun Figaro 2.4.5 were used and reviewed. The C code is now ANSI-compliant and its interface to the Fortran code is portable since it uses the ‘F77’ macros.
Portable Figaro 3.1-0 concentrated on providing as many Figaro 3.0 applications as possible in a portable release and on a reasonable time scale. Version 3.1-1 added the most important missing applications, those for image display etc. Version 3.2 was a complete port of Figaro 3.0 in that is also contained disk-FITS readers and writers. Fringe items like ‘dta2hds’ or ‘cabujy’ are not available. Nor is there a software development environment; programmers have to adapt their software to ‘alink’ and ‘compifl’ themselves.
There is only one executable system similar to the monolithic ICL Figaro 3.0. DCL and Callable Figaro are not available. However, Portable Figaro uses the ADAM parameter system in a much improved way; it is superior to ICL Figaro 3.0. The Figaro libraries are available only as object libraries, no sharable libraries exist.
Portable Figaro does not include the TVPCKG or MTPCKG libraries. It also does not include DSK which affects one mode of operation of a small number of line graphics applications. CNV is discontinued, the small number of calls to it could be re-directed to one new routine ‘dsa_fmtcon’. DYN was merged into DSA, VARS into PAR. With TVPCKG gone, DUT and MEM are not needed either. Since Portable Figaro does not support tape handling, there is only a dummy TIO library. The FIT library is complete, in order to support disk-FITS. NAG_FIX was eliminated by changing the out-of-date calls to NAG. FIG and GEN were ported only to the extent that ported applications called these routines. The JTY (formerly JT) library was brought into line with the other libraries: the routine names and file names now have prefixes JTY and the files contain in general one routine only.
What remains of the Figaro environment—apart from the object libraries—are some environment variables. These are set in the Starlink startup scripts:
FIGARO_FORMATS is in fact no longer used by Figaro itself. Applications that are linked against DSA/DTA will be subject to your data format choice in FIGARO_FORMATS.
The usual file search path is the same, only that the directory of the executable is not available:
The ‘_U’ variable is free for the user to set, ‘_L’ is for the site manager to set. They can of course be left un-set. The concept of a national directory is given up, since it did not work out quite as well as one might have thought. With Portable Figaro being a release from Starlink, there is no longer the need for a separate directory for Starlink’s modifications.
Portable Figaro relies on Starlink infrastructure software to a larger extent than Figaro 3.0 did. In general more reliance on Starlink software results in easier maintenance of the resulting Figaro package. Figaro 3.0 did already use
In Portable Figaro the following were added:
Colour tables are no longer un-formatted 2-byte integer arrays in the range 0 to 255 with 3 records of 256 integers. Instead they are 3-by-N images in NDF format. The values range from 0 to 1 now. All existing colour tables happen to be 3 by 256. Colour tables are still stored in the directory ‘$FIGARO_PROG_S’, they have names ‘table_lut.sdf’. Not only the traditional tables from Figaro 3.0 were ported, but also some tables from NDPROGS. In addition, KAPPA’s colour tables have the same format and can be used.
There are two directories with application source code, ‘applic’ for the traditional sources and ‘appstl’ for a small set of ‘pure Starlink’ applications. The latter are written in quite different style; they use only Starlink libraries and no Figaro libraries. In addition, ‘appsub’ is used to absorb any subroutines that were split off the otherwise biggest application source files in ‘applic’ (the sources that exceeded 50 kByte).
Most applications were ported straight from VAX Figaro 3.0, either from the Standard release or the National release. The changes made to these applications are mainly hard-wired file names or parts thereof, which must be lower case now. Also OPEN, CLOSE, INQUIRE statements sometimes used VAX extensions to Fortran 77. Some bugs were fixed (in addition to fixes already in National Figaro 3.0-6).
Some applications use text files with fixed names for output. This may prevent running them again before the output file is deleted or renamed. The problem was serious for ‘echselect’, which uses such a file for input and subsequently for output. ‘echselect’ will now delete any existing file before writing. This is in effect the same as on VAX, only that VAX/VMS would keep old versions of the file.
A small number of applications have been renamed: ‘fitslist’ becomes ‘fitskeys’, ‘rotate’ becomes ‘irot90’, ‘ndfbad’ becomes ‘q2bad’.
‘soft’, ‘hard’, ‘idev’ use GNS instead of SGS to check the device name. This allows device names to be abbreviated. The new imaging routines replace calls to TVPCKG with calls to PGPLOT. ‘findsp’ and ‘overpf’—which used raw GKS before—have been converted to PGPLOT. Thus all graphics is done with PGPLOT.
‘abline’, ‘echarc’, ‘echfind’, ‘echmask’, ‘echmerge’, ‘fet321’ and ‘figs424’ have been converted to use the DSA library rather than DTA. All of Figaro supports DST and NDF formats.
‘abline’, ‘arc’, ‘centers’, ‘cfit’, ‘clean’, ‘cset’, ‘echarc’, ‘echselect’, ‘findsp’, ‘foto’, ‘gauss’, ‘iplots’, ‘isedit’, ‘msplot’, ‘sdist, spied’ and ‘tippex’ have been modified to avoid calls to ‘par_q*’ or ‘par_rduser’. Instead of asking with a generic parameter name and a dynamic parameter prompt string, these routines now have additional parameters with static prompt strings. This should not affect the use of these applications, the new parameters are not to be given on the command line anyway, and users are used to the questions that are being asked. However, it is now possible to abort the application when it was not possible before.
‘dvdplot’, ‘hopt’, ‘icont’, ‘igrey’, ‘image’, ‘splot’, and ‘esplot’ are passively AGI compliant. Their PGPLOT view port is saved as an AGI picture so that other applications can pick up information about the plot made.
As of version 5.0, NAG is no longer used. Instead the PDA library is used. The resulting changes to applications are in general minor. An exception is ‘gauss’ where a different fit algorithm was adopted. The new algorithm is the same as in the Specdre package.
The ‘straight port’ traditional Figaro routines are:
Apart from ‘clean’, which could be modified to use PGPLOT instead of TVPCKG, the imaging routines have been re-written. ‘idev’ has been added to select the imaging device. ‘image’ and ‘clean’ now support bad values (or quality). ‘igcur’ is an equivalent to ‘icur’, but uses a previous display on the ‘soft’ device made with ‘igrey’ or ‘icont’. The routines re-written in traditional Figaro style are:
Most of the HDS file structure manipulation routines have been re-written as ‘Starlink-style’ A-tasks and are stored in the ‘appstl’ directory. ‘crobj’ is replaced by ‘creobj’, ‘let’ by ‘copobj’ and ‘setobj’. This group also contains the on-line help program ‘fighelp’, and the two NDF-fixing routines ‘q2bad’ to merge quality into bad values and ‘goodvar’ to replace bad and negative variances.
These applications not being in the traditional Figaro style and not using (F)PAR, the syntax to specify HDS structures is slightly different. Where traditionally array elements were specified in square brackets [ ], you must now use parentheses ( ). Array shapes and sizes are no longer part of a structure specification, but are passed as separate parameters. Furthermore, data types must be HDS types, e.g. ‘Float’ becomes ‘_REAL’.
The A-task applications in ‘appstl’ are:
‘appstl’ contains not only the A-task routines, but also the subroutines called by these A-tasks. Those have names with the FIG prefix; they are kept here to isolate Starlink-ish routines from Figaro-ish ones.
A number of bugs were fixed in various applications since the first version of Portable Figaro (3.1-0).
New applications are:
A number of applications could not be ported because tape handling is not supported or DSK is not available. Other un-ported applications have to do with image pairs, since they rely on the display device being 8 bit deep. In addition most format conversions were not ported. Furthermore some applications are meaningless in an environment other than DCL Figaro or Callable Figaro. Finally ‘extlist’ never worked, but is now included as a new application. The un-ported applications are:
The Figaro PAR and VAR routines have been merged into one library (F)PAR (retaining the original routine prefixes). The routines translate more or less directly into calls to the ADAM parameter system (A)PAR. They emulate the behaviour of the Figaro 3.0 parameter and variable system as best as possible under these circumstances. The @-feature to repeat the application for an edited sequence of parameter settings is not supported.
Variables are still supported, but formally become global parameters and must be declared as such in the interface files.
In some circumstances VAR routines may prompt for global parameters. Say, the ‘soft’
application has never been used to select a plot device. When an application tries to get the
value of the global parameter ‘soft’ it will prompt the user. Also if the ‘prompt’ keyword is
specified by the user, variables are just normal parameters and will be prompted for. The
inconvenience this causes amounts only to hitting the
<Return> key in order to accept the default
The application interface files ‘applic.ifl’ derive from the Figaro 3.0 binary parameter files ‘applic.par’. For Figaro 3.0 this conversion had been done automatically with the utility ‘creifl.exe’. Figaro 3.0 (on VAX only!) does contain the utility ‘par2ifl’ for this conversion. See also Section F.1.
No keywords are used in the interfaces. In ICL Figaro 3.0 a shortest abbreviation had to be used. From version 5.1-3 onwards, parameter names can be abbreviated if the environment variable ADAM_ABBRV is set.
In National Figaro 3.0-6 a small number of parameters in a moderate number of ICL Figaro applications (mostly parameters ‘xstart/xend’) had been changed to become global parameters. The only global parameters in Portable Figaro are ‘image/spectrum’ in all applications, and ‘xstart/xend’ in ‘xcur’ and ‘splot/esplot’.
While in Figaro 3.0 all non-logical parameters were of type ‘LITERAL’, numeric parameters are now of type ‘_REAL’. Portable Figaro itself does not use any double precision parameters, those would be of type ‘_DOUBLE’. Since Figaro 5.1 parameters related to opening data sets via ‘dsa_input’, ‘dsa_output’ etc. are of type ‘NDF’. Their values are obtained within the FDA library by calls to SUBPAR.
Non-global prompt paths are usually ‘CURRENT,DYNAMIC’. So normally the current value is used, but with the ‘reset’ keyword the dynamic value is used.
All interface files connect to the help library ‘FIG_HELP:’. For all parameters the help key ‘*’ is used, equivalent to ‘applic Parameters param’.
‘par_wruser’ will now strip off a leading ‘$’ or ‘+’ thus disabling the line feed control. The status argument of ‘par_wruser’ is a returned argument; ‘par_wruser’ works even when called with bad status, but it turns the status into ‘OK’.
Null and abort responses given by the user to (A)PAR are detected as non-OK status by (F)PAR. (F)PAR will set the abort flag in its common block. The ‘normal’ (F)PAR routines ‘par_rdchar’, ‘par_rdkey, par_rdval’, ‘par_rdvald’ and ‘par_rdary’ will return without action if the abort flag has been set by a previous call to (F)PAR. Applications should test the abort flag and take appropriate action. Most do.
The ‘abnormal’ (F)PAR routines ‘par_qnum’, ‘par_qstr’, ‘par_quest’ and ‘par_rduser’ do not handle abort requests. Also these routines use dynamic prompt strings. Both these features make them difficult to use on top of (A)PAR. Use of these routines should be avoided. Portable Figaro does avoid them, though they are still included in the object library.
In the ADAM environment PGPLOT is not allowed to communicate with the user when ‘pgadvance’ is called. Thus ideally any call to ‘pgbegin’ should be followed by a ‘CALL PGASK(.FALSE.)’, at least if the application also calls ‘pgadvance’. Where it is necessary for the application to hold before clearing the previous plot, this should be achieved through the parameter system.
As of version 5.1, Portable Figaro no longer uses the DSA and DTA libraries for data access, but uses instead the FDA library. This provides an interface to the NDF library. FDA tries to be a simple and direct interface to NDF, but emulates DSA at truly as possible. The routine names and argument lists are the same as in DSA/DTA.
Detailed information on the FDA library is beyond the scope of this document.
The need for the VAX error condition handler has been eliminated by more robust coding of some routines and by using PRIMDAT routines. It is however necessary that applications use ‘UPDATE’ access for existing output data that must be read as well a written, and that they use ‘WRITE’ access when output data do not exist. The latter is important, otherwise applications are liable to be aborted by the operating system.
A problem arose with the use of the string ‘n’ in the buffered output by calls to ‘dsa_wruser’. The backslash is not in the Fortran character set. In Sun Fortran it is interpreted in a similar way as in Unix or C. ‘dsa_wruser’ should no longer be called with the new-line escape sequence ‘n’. Instead an extra call to ‘dsa_wrflush’ should be made. In general, applications should call ‘par_wruser’ instead of ‘dsa_wruser’. Where a backslash is needed in source code—e.g. in text strings for PGPLOT—‘CHAR(92)’ should be used.
‘dsa_map_data’ would un-flag data even when access was ‘WRITE’. In that case the mapped array contains garbage. Comparing it against the bad value results in the occasional invalid operand, and will often encounter ‘NaN’s. The routine now does not un-flag write-accessed data. ‘dsa_map_errors’ and ‘dsa_map_variance’ did not zero-initialise an existing write-accessed array; they do now.
One feature of DST-format axes cannot be accommodated in NDF-format data: In DST each axis exists independent of the others. In an NDF either the whole axis structure array is absent, or each axis up to the dimensionality of the main data exists and has a ‘DATA_ARRAY’. (By default that data array contains pixel numbers minus 0.5, Figaro uses by default pixel numbers ignoring origin, i.e. numbers 1,2,3,...)
A check and rectification is performed now when a structure or DSA itself closes down: ‘dsa_check_structure’ now at the very end makes a check of the ‘.AXIS’ structure if the structure to be checked is an NDF. This is done by a call to ‘dsa_check_ndf_axis’, which is new. Note that this check is made for all DSA structures of NDF type even if they were opened for input and are write-protected. If the rectification fails a message is issued telling whether the whole axis structure was deleted or the structure remained in contravention of the NDF specification.
The present DTA library derives from the one released in Sun Figaro 2.4.5, patch 5. The folding of file names and appending of version numbers on Unix systems via ‘dta_filefold’ and ‘dta_versname’ has been discarded.
There was a bug in ‘dta_dlvar’ and ‘dta_rnvar’ regarding their use of ‘dta_splitn’ and ‘dta_locate’ when an upper level structure was a cell in a structure array. This has been fixed. dta_cyvar’s job is not quite as easy as it was before structure arrays could be encountered. The routine was completely re-written.
An obscure problem occurred whenever a DSA structure reference name was the same as the corresponding parameter name and the parameter also had a global association. This was tracked down to be a problem of conflicting names of HDS locator groups as used by DTA and (A)PAR. DTA now constructs group names by appending and extra ‘G’. Group names must be no longer than 15 characters. This now implies that DTA top level names and DSA reference names must be 14 characters or less.
In version 3.1-1 DTA was converted to use ‘DAT__SZLOC’ instead of the constant 15. On OSF/1, HDS locators are of length 16.
In version 5.0-0 a new routine dta_dfned had to be introduced to fix the N-D axis handling in DSA.
In version 5.1-3 ‘dsa_input’ and ‘dsa_named_input’ received additional entry points ‘dsa_input_update’ and ‘dsa_named_input_update’ respectively. In FDA the routines are distinct, and the entry points are provided to allow modified applications to be linked against DSA/DTA instead of FDA. For the same reason ‘dsa_map_complex’ was added to DSA in order to map real and imaginary parts of the data in a single call.
Virtually all source files have been split into single-routine files and all externally called routines have now the FIG prefix in their names. Thus ‘wxyfit, seterr, figx_shift’ have changed name. Some file names are abbreviated routine names in order to be only 12 characters long (excluding the extension ‘.for’). Only ‘fig_eterp.for’ contains subsidiary routines without FIG prefix and all in one file.
While FIG still calls DSA, DSA no longer calls FIG; FIG need not appear twice in the link command.
‘fig_rebin2d’ uses DSA to get a work space needed to call ‘gen_poly2d’. Thus ‘dsa_open’ must have been called before ‘fig_rebin2d’, and ‘dsa_close’ must be called some time after ‘fig_rebin2d’.
Two routines are added in version 5.0. ‘fig_pgbeg’ and ‘fig_pgend’ can be used to replace ‘pgbegin’ and ‘pgend’. The effect is that the last PGPLOT view port is saved as an AGI picture when ‘fig_pgend’ is called.
In version 5.1-3 ‘fig_convchk’ and ‘fig_dtaerr’ have been removed because of their relationship with DTA. Figaro applications no longer need these routines.
The files that contained the JT routines have been split into single-routine files. Both routine names and file names have the JTY prefix now. In some cases file names are shorter (12 character plus ‘.for’) than routine names.
Some care had to be taken when changing routine names to ‘jty_*’, because some were functions and implicitly typed ‘REAL’. The prefix would imply them to be ‘INTEGER’. Care must be taken wherever the functions ‘evaleg, getrms, poly2d, rmsfilter’ are used. They must be declared properly when changed to ‘jty_*’.
Many routines used ‘PARAMETER’ statements without parentheses around the assignment. This is a VAX extension to Fortran 77; standard Fortran statements are used now. Some routines might have written to Fortran unit 6; these statements have been replaced with calls to ‘par_wruser’.
There are some C routines. In general an ANSI-compliant C compiler must be used, the makefile uses ‘$(CC)’. Due to alignment problems on Sun4 work-stations, ‘gen_qdisort.c’ was withdrawn and sorting must take place with an equivalent single-precision vector.
Some C routines come in machine-dependent versions. The problem is not the non-portability of the interface to Fortran code—the interface to Fortran is portable by using F77/CNF—but the machine-dependency of binary data. Disk-FITS support requires byte-swapping on Digital hardware, but no swapping on Sun hardware.
The bug in ‘gen_gconv’ causing problems with an un-initialised work array element in the case of even ‘WIDTH’ argument was fixed. ‘gen_poly2d’ was translated to Fortran. It must now be given an extra work space by the calling routine. The most likely such routine is ‘fig_rebin2d’. ‘gen_errmsg’ is no longer available. A new routine ‘gen_astatb’ is like ‘gen_astat’, but recognises bad values. Another routine ‘gen_getcwd’ can be used on Unix platforms to find out the current working directory.
All GKD routines have been ported. ‘gkd_clear_alpha’, ‘gkd_close’, ‘gkd_init’ are dummy routines. The rest are simple calls to (F)PAR. Calls to GKD should be avoided and (F)PAR be called directly.
‘ich_cf’ and ‘ich_cd’ were modified to avoid copying substrings within one string. ‘ich_dfold’ was included to provide for folding to lower case.
Version 3.1 included a library RTL, which was only an interim measure to satisfy numerous calls to VAX/VMS system routines on other platforms. Such calls have been eliminated from all code, the RTL library is withdrawn.
The printed documentation for Portable Figaro 3.1 is Starlink User Note 86. The changes between versions 3.1-0 and 3.1-1 have not been included in SUN/86.
In version 3.1-1 the following imaging commands have been added:
The following three applications are also new and replace two discontinued ones:
So, whenever SUN/86 tells you to use ‘igrey’ and/or ‘igcur’ you can use ‘image’ and ‘icur’ instead. But note that you must use the matching cursor routine. ‘igcur’ will not work porperly on displays made with ‘image’ and ‘icur’ will not work properly on displays made with igrey or icont.
Colour tables are stored as NDFs of size 3 by N. Their names end in ‘_lut’ now. These are stored in $FIGARO_PROG_S, a list can be produced with ‘ls $FIGARO_PROG_S/*_lut.sdf’. When specifying the table to the ‘colour’ application, don’t include ‘$FIGARO_PROG_S’ or ‘.sdf’. As an example, the STANDARD lookup table would appear in the ‘ls’ command as ‘/star/etc/figaro/standard_lut.sdf’, but to load it into the display, just use the command ‘colour standard_lut’.
idev works similar to soft. It will draw the text ‘PGPLOT imaging’ on the device, and it will reset the colour table to grey. Note that a newly created GWM window has arbitrary colours—often all black. If the display generated with ‘image’ looks odd, try to load a grey scale with ‘colour grey’.
The ‘idev’ and ‘soft’ devices can be the same. A device-erasing line plot will, however, reset the colour table. The rationale of separate devices is that you can set the image display to ‘xw’ once and for all, but set the ‘soft’ device to ‘xw’ today, ‘graph_on’ tomorrow, or ‘x2w’ next week.
You can have two separate GWM windows ‘xwindows’ (device ‘xw’) and ‘xwindows2’ (device ‘x2w’) for ‘soft’ plots and image display resp.
GWM windows are usually created with 780x512 pixels and 64 colours, unless your .Xdefaults specifies otherwise. 16 colours are reserved for PGPLOT line graphics, the rest is used for image display. It may be sensible to create two windows explicitly and to use them as ‘soft’ and ‘idev’ devices:
To start Figaro on Unix, type:
You should ensure you have a directory $HOME/adam. Help on Figaro may be obtained by typing
Further details can also be found in SUN/86.9.
The printed documentation for Portable Figaro 3.2 is Starlink User Note 86.
Figaro 3.2 includes disk-FITS support, i.e. the applications
There is no support for tape-FITS, but FITS files can be copied from and to tape with "dd" using a block size of 2880 byte for the tape. On Unix systems each tape tends to have two devices, e.g. "/dev/rst0" and "/dev/nrst0" for rewound and non-rewound. To skip files etc. use the "mt" command, like:
This recipe is offered without warranty. Tapes on Unix systems come with all sorts of peculiarities, and you must try how things work on each tape drive individually.
The following applications were converted from using DTA-only data access to DSA-only data access:
Thus all applications now support both data formats. However the NDF format still forbids N-dimensional axis arrays, so from ECHARC / XCOPY to SCRUNCH you still need to use DST format.
The following applications have been changed in the way they use the Figaro parameter system.
New parameters have been introduced to replace the general parameters LOGICAL_VALUE etc. Users will hardly notice the difference, all these are prompted parameters that cannot be given on the command line. Users may notice that they now can abort these applications at any prompt.
Major changes is this release are:
Various changes have been made to a number of applications, some have been changed in more than one respect. Below is a table stating which changes affect which applications.
Figaro 5.0 can be started from ICL simply with the command ‘figaro’. On-line help is available via the ICL command ‘help’ (not ‘fighelp’, which is only for use from the Unix shell). The ICL Figaro test script (demo.icl) has been changed from VMS to Unix.
The complete documentation (Starlink User Note 86 plus the on-line help library) has been reviewed and is available in HyperText format. It can be viewed with World Wide Web browsers like Mosaic. One set of documentation is held centrally at RAL. Starlink sites in all probability have a local set as well. The Mosaic browser can be started with the Figaro command ‘figwww’ so as to enter the Figaro documentation immediately. figwww works from ICL as well as from the Unix shell. Mosaic is started as a background process and the terminal remains free for use as the Figaro command interface.
The improvements to the DSA library that were introduced in Standalone Portable Figaro 4.2, are included in this version (Portable Figaro 5.0). These improvements are
Where the version of DSA in Portable Figaro 3.2 was already better than that in Standalone Portable Figaro 4.2, these improvements have been retained. This is the case for the handling of file names and file units, handling of memory work spaces, and avoidance of the—interim—RTL library.
Two bugs introduced in DSA 4.2 have been fixed for version 5.0. One in effect prevented creation of complex data structures, the other allowed a certain form of invalid NDF axis to remain in the case of an N-D axis array.
A minor improvement to the DTA library (from 4.2) is that is now recognises a larger variety of error codes from the underlying HDS library. A new routine dta_dfned had to be introduced (in 5.0) to fix the N-D axis handling in DSA.
Improved versions of several GEN routines were adopted from Standalone Portable Figaro 4.2. A portable implementation for gen_rename was written for Portable Figaro 5.0 (i.e. this release).
Figaro does no longer use the NAG library. Starlink are in the process of gathering Public Domain routines in a new PDA library to replace most or all NAG routines currently used by Starlink applications. Figaro is the first package to be free of NAG. This has positive effects as regards porting to new platforms, but mostly in respect of the software distribution policy.
Due to the use of FFTPACK routines instead of NAG routines, there is no restriction any more on the shape of complex data sets.
‘gauss’ now uses a different fit algorithm for line fits. The new algorithm is copied from the ‘fitgauss’ application in the Specdre package. The change was necessary, in order to avoid use of the NAG library. As a side effect, the fit algorithm is more stable. A limit of 10 line components for a single optimisation is now enforced (NEXT option in the line fit menu). Before, you could enter more lines, but would mess up the application’s internal storage.
The applications ‘dvdplot’, ‘hopt’, ‘icont’, ‘igrey’, ‘image’, ‘splot’, and ‘esplot’ are now passively
AGI-compliant. That means that information about the plot is stored in the AGI data base. Other
applications (in non-Figaro packages) can then use this information. As an example, you can use the
KAPPA command ‘cursor’ to enquire positions in an image or spectrum plot produced with
Figaro. There will be one AGI data base for each machine you run graphics applications on.
These files will be created either in $AGI_USER if defined, or in $HOME. The file names are
and should be removed occasionally. These files grow ever bigger, while most of the information
pertains to plots that are no longer visible.
Similarly, the Figaro-internal storage of the image/spectrum file name is increased to 132 characters. For example, ‘splot’ followed by ‘ccur’ will now work, even when the data files are in a deep level of the directory tree.
‘findsp’ and ‘overpf’ have been re-coded to use PGPLOT rather than GKS (and SGS) directly. Portable Figaro therefore uses only PGPLOT for graphics. Also, ‘findsp’, ‘overpf’, and ‘polext’ no longer use the NAG library, of course.
The application ‘hcross’, introduced in the previous version, now allows the template parameters to be given as redshifts or as radial velocities. Also, if the template and object spectra do not match well, the results will still be reported.
A typo was corrected in the standard star tables for BD +17 4708, both the linear and the AB magnitude table.
The application interfaces as used by the graphical user interface Xadam now include information as to which data structure is input and output. This should facilitate the auto-display in Xadam.
The package is now built by a makefile based on the Mark V Starlink template makefile. As a consequence the object libraries now are all in /star/figaro rather than sub-directories thereof. The directory /star/figaro/lib no longer exists. Similarly, the only include file available is /star/figaro/dynamic_memory, the directory /star/figaro/inc no longer exists.
Version 5.0-1 is an update to the previous release of Figaro 5.0-0. Several problems in the new data access library (DSA 4.2) regarding the handling of quality information have been fixed.
The previously recommended work-around of using ‘q2bad’ whenever a quality array was created, is now obsolete.
The segmentation violation in ‘coadd’ does no longer occur. And the floating-point exceptions in ‘isubset’ and ‘coadd’ also no longer occur. ‘optextract’—which suffered from the same problem as COADD—works now as well.
Modified versions of ‘flag2qual’ and ‘qual2flag’ are used, which no longer cause the warning that the applications might not work correctly. (They did work correctly anyway.)
In this version of Figaro the principal change is the use of a new data access library (FDA), but this made minor modifications to several applications necessary. The old libaries DSA and DTA are kept as part of the release, but are unused by Figaro itself.
With the new data access library, the principal data format is NDF. On the other hand, a number of foreign file formats can be used in addition to NDF itself. The old Figaro DST format is one such foreign format, others include FITS, IRAF, and GIF.
In order to use any foreign format, you must start up CONVERT in addition to Figaro. From the Unix shell:
and from ICL:
The data format is selected by the user on a per-file basis by specifying a file name extension:
will try all known formats in order of priority, to choose a format explicitly:
Currently the extensions recognised, the formats addressed, and the priority list are:
In addition to foreign file formats, users can now use NDF sections of data sets. You can use a number of ways to specify a section as shown in this 7-D example:
Apart from the availability of foreign file formats and NDF sections, there should be hardly any perceptible change for the user.
Users can abbreviate parameter names on the command line, e.g. instead of ‘istat image=myfile’, ‘istat im=myfile’ can be used. Name abbreviation can be turned on and off with ‘abbrev’ and ‘noabbrev’ respectively.
‘exam’ has been removed, use the Starlink utility ‘hdstrace’ instead.
‘figwww’ has been removed, use ’showme sun86’ instead.
Bug fixes in applications:
The source code of ‘echfind’, ‘fet321’, ‘figs322’, ‘figs321’, ‘icur’, ‘gauss’ no longer uses the problematic splitting of string constants by simply breaking the source code line. Proper string concatenation is now used. Minor bugs in fig_hdsdig and fig_pgend were fixed.
The release has been tidied with respect to differences between Unix and VMS versions. All that remains of the VMS version is the link options file ‘linkmono.opt’. ‘rdispo’ and ‘wdipso’ have been formally added. ‘table’ has been formally added and ‘rspica’ and ‘wspica’ have been formally removed. Startup scripts exist only for C shell and Unix ICL, the test script exists only for ICL. The test script has been extended to cover a wider range of applications.
The move to the new data access library prompted:
This is a shortened copy of the News item describing Figaro 5.1-4. Some items described in previous release notes have been removed.
You may have noticed some recent changes to Starlink Figaro—perhaps unfavourably—and wondered what was happening and why. This news item describes the new features, their benefits, and the rationale behind the main changes. It also offers some tips on getting the most from Starlink Figaro, and alternative routes where some functionality has had to be withdrawn. Finally, it announces and gives details of the release of a new version: 5.1-4.
Here is a summary:
Figaro 5.1-4 release—main changes:
See §G.7.1 for further details.
§G.7.3 describes these.
§G.7.2 contains practical information on the following.
Switching between Pixel Indices and Axes Values
With the introduction of FDA in Figaro 5.1-3, the handling of default axis-centre numbering changed from the Figaro-style indices (start from the lower bound and increment by one per pixel) to the Starlink standard default pixel co-ordinates; these are pixel indices less 0.5.
From Figaro 5.1-4, the old-style behaviour can be selected by defining the environment variable FIGARO_AXES. The value of the variable does not matter: its presence selects Figaro-style indices; its absence selects Starlink standard co-ordinates. If your dataset has existing axis centres, they will be used irrespective of FIGARO_AXES.
Since V5.1-3 appeared you may have created NDFs that have axis centres in Starlink pixel co-ordinates. To get the former behaviour you will either need to remove the entire axis structure (so that it stays a valid NDF), for instance
removes the axis structure from the NDF named myndf. However, erasing the axis structure also loses any other axis information such as the label, and the axis centres along other dimensions. You can replace the axis centres with pixel indices along an individual axis using the KAPPA task SETAXIS. For instance,
would assign pixel indices to the axis centres in the 1-dimensional NDF called spectrum, and to the second dimension’s axis centres in the NDF called image.
Fixes to applications:
One way to process several files in a UNIX C-shell is using a foreach loop. For example, if you wanted to add a constant to all the files matching the wildcard run1??.sdf you might:
If you wanted the resulting output files to have the same root name but with some string appended, for example image.sdf to become image_db.sdf, then the above would change to:
Similarly, you might like to store the commands in a script (lets call it icmadd) instead of having to type them each time:
The basic icmadd script would look like this:
If you use ‘isubset’ to remove unwanted parts of an image the output file produced remains approximately the same size as the input file. This is the case even if you select only a very small part of the input dataset.
Using NDF sections, this effect can be eliminated, resulting in output files of the expected size. For example, if you wanted to take a -pixel subset from an image, and would normally use:
(note the use of abbreviated parameter names, see notes for 5.1-3), the same subset can be obtained by:
The difference being that the file produced by this command will be smaller. If your dataset does not contain n-dimensional axis centres then the KAPPA command NDFCOPY is more succinct.
Sometimes you may want, for example, to take the median obtained using ‘istat’ and use this value as the FACTOR in an ‘icsub’ command. This can be done as follows:
This assumes that the environment variable ADAM_USER points to the directory where your parameter files are stored; this is by default the directory adam in your home directory (~/adam).
If you wish to access a data file which has the same root name as an NDF you must give the full file name to explicitly select that file. For example, if you have two files image.sdf (an NDF) and image.dst (a DST) in the same directory then
will select the NDF, assuming you have not altered the default precedence used (see notes for 5.1-3), and
will select the DST file explicitly.
The environment variable FIGARO_FORMATS is no longer used.
If it ain’t broke…
The conversion to use the NDF library was requested by the Spectroscopy Software Strategy Group (cf. SGP/48, Appendix A2.1).
The change adds functionality to Figaro, namely automatic access to foreign data formats, NDF sections, and history recording. It gives more consistency with other Starlink packages; this is important when your data-processing path requires functionality not available in Figaro. Figaro will be able to take advantage of any future developments to the NDF library, such as astrometry and processing of wildcarded lists of files. The change to FDA also opens the way to have Figaro operating from the IRAF cl.
As automatic conversion requires the NDF library to be called, the move to FDA had the side effects of changing the default axis centres and the removal of the ‘exam’ command. The former is circumvented through the new FIGARO_AXES environment variable, and there is a ready replacement—HDSTRACE—for the latter.
Since the FDA library calls the NDF library, you can record the data-processing history of an NDF. Since the information can be bulky compared to the data array, especially for a spectrum, history recording is disabled by default.
The KAPPA command HISSET lets you change the level of history recording from one of four levels: Disabled, Quiet, Normal, and Verbose. The following command sets the recording level to normal in NDF spectrum.
Thereafter whenever you alter this NDF or create another NDF from it, the Figaro task will automatically record the name of the task run, the date and time, and some text comprising the command-line parameters and the full path of the application.
You can disable or erase the history using HISSET.
KAPPA also provides commands for adding commentary (HISCOM), and listing the history records (HISLIST). If you enter
and select the link “NDF History” in SUN/95, you will find more information and examples of using these commands.
EXAM has been removed
The Figaro command ‘exam’ has been removed. This is for two reasons: first, ‘exam’ calls the DTA library, which is no longer used elsewhere in Starlink Figaro, and so would need major modification to call HDS directly; second, the functionality of ‘exam’ is available in the task HDSTRACE, which already calls HDS.
All the facilities of ‘exam’ are available in hdstrace. One common use for ‘exam’ was to list all the objects present in a file. This would have been done by:
The same thing can be done using hdstrace by:
(and the full keyword is only required if you want to view all elements of any array of structures, such as the axis structure in a multi-dimensional NDF). Note that HDSTRACE displays the standard HDS data types so, for instance, you’ll see <_REAL> for Float, and a string of say six characters has type <_CHAR*6> rather than a six-element array of Char type.
You can access individual components like this:
This value could be used in a C-shell script like this:
then $airmass will substitute the airmass value.
If you want to trace a DST file, the syntax is a little more complicated. Here are two examples.
Note the backslash is needed to escape the " special character from the UNIX shell.
This is a copy of the News item describing Figaro 5.1-6.
Version 5.1-5 of Figaro was only made available on the Starlink Linux CD, Version 1.3. Version 5.1-6 is identical to 5.1-5, except for the changes to the HELP text and the DSA_RESHAPE_DATA improvement (see below).
This news item accompanies the latest release of Figaro: version 5.1-6. This is a maintenance release with some small performance improvements and bug fixes. There has been an update of SUN/86 due to the recent withdrawal of XADAM. Some tips on tuning the performance of Figaro are included below.
The main changes at this release are:
The applications for which this change will be significant are:
‘Istat’ is only effected if median=true. ‘Medfilt’, ‘medfiltr’, and ‘retype’ are only effected if the output is to the same file as used for input. About 40 other applications should see a slight improvement in performance.
When you access data stored on a disk connected to a different machine to the one on which your shell process is running, commands take more time to run. There a several reasons for this: the level of network activity, the load on the remote machine, and so on. Generally, you’re better off working with data on a disk connected to the machine you’re using; but it isn’t always possible, or helpful, to do this.
When accessing input data files, Figaro sometimes has to create temporary files. These are, by default, placed in your current working directory. What this means is that if you are working on ‘remote’ data, and your working directory is also ‘remote’, Figaro has to write and then read back data across the network. This can slow things down quite a bit! There is no once-and-for-all way around this, but you may be able to take advantage of a feature of HDS which lets you control where the temporary files are stored. For example, if your home directory is on the local machine you might
Temporary files would then be placed in your home directory. Bare in mind that temporary files can be quite large for some applications, and the area available in the directory $HDS_SCRATCH needs to be of requisite size.
This is closely related to the first tip. Figaro can use on-the-fly conversions from, for example, FITS format. So, if you have some fits dataset starimage.fit, you can display it thus:
If starimage.fit is on an NFS-mounted disk, and in your working directory, it will take a while to display. This is because all the conversion data is being transferred over the network. The first action to tune this procedure is to setup $HDS_SCRATCH to point to a local disk (see above). The next thing to do is set $NDF_TEMP_FITS to be a local filename, the complete process is:
The first four lines of the above example need be issued once per session. Remember the directory you use must be on a local disk, and there must be enough space for the temporary NDF created by CONVERT. The intermediate NDF will be stored in the file
There are similar tuning parameters for other data formats, to get the full details see ‘Specifying Where the Native NDF is Stored’ in SSN/20.
Fixes to applications:
This news item accompanied the release of Figaro version 5.2-0.
The main changes at this release are:
There is a world-wide web page including Figaro documentation and related information:
It is now possible to propagate the errors through the complete reduction of simple single-order spectra. A recommended reduction recipe is described in SUN/86.
Tasks which now include error propagation include:
In the following tasks, error handling has been added or corrected at this release:
All the above now include propagation of the variance arrays into the output. The errors are propagated in the standard way (see e.g. Bevington and Robinson9) for most routines.
There are a few circumstances in which the error propagation is not completely formal which are documented.
The following Figaro tasks also support error propagation:
Fixes to applications:
Fixes to Linux release:
The following notes are a slightly modified version of the news item which accompanied the release of Figaro version 5.3-0 (spring 1998).
The major changes in version 5.3-0 are:
In addition there are a couple of minor enhancements.
A.C. Davenhall (
email@example.com), 19 December 1997.
The spectroscopy package SPECDRE has been incorporated into Figaro. The SPECDRE commands are available automatically when Figaro is started. The SPECDRE commands available within Figaro differ from the previous stand-alone ones in the following respects:
RESAMPLEis now command
RESAMP(to avoid a name clash with the Figaro command
GOODVARhas been withdrawn because the same functionality is already available within Figaro.
SUN/140, which described SPECDRE, has been withdrawn and its contents incorporated in SUN/86.
The IRAFFIG package is a set of files which allows Figaro to be run from the IRAF command language CL. In practice it makes Figaro available to IRAF users. For convenience it is now released as part of Figaro.
SUN/220, which described IRAFFIG, has been withdrawn and instructions for running Figaro from IRAF have been included in SUN/86.
Version 5.3-0 includes the following minor enhancements:
ECHARCnow simply overwrite any pre-existing file called
arlines.lisrather than terminating with a message,
SCRUNCHhas been increased to 5,000,000.
In addition there have been a couple of bug fixes.
The following notes are a slightly modified version of the news item which accompanied the release of Figaro version 5.4-0 (spring 1999).
The major change in version 5.4-0 is the addition of the application
SCLEAN for removing bad lines and
pixels from images obtained with the SCUBA instrument on the JCMT.
SCLEAN reprises the
functionality of the traditional Figaro application
CLEAN, but it correctly handles the array of quality
flags associated with the data array in SCUBA images. It also provides a new display mode suitable
for use with SCUBA data.
In addition a number of bugs have been fixed.
The following notes are a slightly modified version of the news item which accompanied the release of Figaro version 5.5-0 (autumn 1999).
The major change in version 5.5-0 is the incorporation of the Twodspec package, which is used for longslit spectroscopy data reduction and analysis. It provides tools for calibration/correction of data and fitting of 2-D longslit arrays, either automatically or as an interactive process. These tools also offer a number of options for generating hard copy output of the resulting fits.
The original stand-along Twodspec accessed data files using the DSA and DTA subroutine libraries. As part of the process of incorporating it into Figaro it was modified to use the FDA library and hence it now accesses NDF data files. Consequently, the Twodspec applications are inter-operable with the basic Figaro ones. However, changing the data-access subroutine library introduced or revealed a number of bugs, some of which are still extant. These problems will be identified and corrected in future releases.
In addition there are a number of bug fixes not related to Twodspec.
The following notes are a slightly modified version of the news item which accompanied the release of Figaro version 5.5-1 (spring 2000).
Version 5.5-1 is a bug fix release which updates the interface file for the EMLT task to include some parameter defaults that were missing.
The following notes are a slightly modified version of the news item which accompanied the release of Figaro version 5.5-2 (spring 2001).
Version 5.5-2 includes a number of bug fixes to Figaro and some minor corrections to SUN/86.
The following notes are a slightly modified version of the news item which accompanied the release of Figaro version 5.6-0 (autumn 2001).
Version 5.6-0 contains relatively few changes: the automatic propagation of errors has been added to a few more applications, there have been a number of bug fixes and minor enhancements and there is one new minor application. In addition the user manual has been slightly revised. Brief details of the changes are given below.
Error Propagation has been added to the following applications:
Either bugs have been fixed in, or minor enhancements have been made to, the following applications:
SPFLUX. In addition, corrections have been made to
the documentation for
The new application
IMPOS has been added. It simply reads a text file containing a list of
positions and writes them to the environment variables which input values to application
Thus, it provides a mechanism for using
CENTERS from a script rather than interactively.
The following notes are a slightly modified version of the news item which accompanied the release of Figaro version 5.6-1 (winter 2002).
Version 5.6-1 contains relatively few changes: there have been several bug fixes and an enhancement
IARC. There have also been some revisions to the user manual. Brief details of the
changes are given below.
Some spectrophotometric flux tables of standard stars suitable for use in flux calibration with Figaro have been recovered and made available again. These data were previously available on the now-defunct RAL central database machine STADAT.
Bugs have been fixed in:
An option has been added to
IARC to allow it to perform weighted as well as un-weighted
Two additional sets of spectrophotometric flux tables suitable for use in flux calibration with Figaro are available. One comprises 25 standard stars observed by Oke, the other 27 HST standard stars. Copies can be retrieved by anonymous ftp.
The following notes are a slightly modified version of the news item which accompanied the release of Figaro version 5.6-2 (summer 2003).
The only changes in Version 5.6-2 are a couple of bug fixes.
The following notes are a slightly modified version of the news item which accompanied the release of Figaro version 5.6-3 (spring 2004).
The changes in Version 5.6-3 comprise only a few minor bug fixes and enhancements, and a missing flux calibration file has been added. Brief details of the changes are given below.
IARC have each received both a bug fix and a minor enhancement. Consequently, there has
been an equally minor revision to the description of
GAUSS in the user manual.
EMLT has a new NOISE keyword. If it is specified, allowance for noise is made when determining the
line limits. This is intended for broad emission features or beam location rather than narrow arc lines.
It defaults to the former behaviour.
SDIST allows for broader spectral profiles when tracing a spectrum. There was an arbitrary cut-off of
the size of the extracted cross-section to be fitted.
The flux calibration file for Hiltner 102,
hil102.tab, was missing. It has been added.
9P.R. Bevington and D.K. Robinson, 1992, Data Reduction and Error Analysis for the Physical Sciences, second edition (McGraw-Hill: New York). See especially equation 3.14, p43.