G Release notes

G.1 Changes from VAX/VMS Figaro 3.0-9 to Portable Figaro 5.1

The main changes are

• Data access is via the NDF library (by means of Figaro’s FDA library). This allows input NDF sections to be specified in the name of the data set. It also allows a variety of foreign formats to be used, if the CONVERT package is initialised in addition to Figaro.
• Access to DST format is as a foreign format. The FDA library does not contain code to access DST format, it relies on conversion programs in the CONVERT package and on the NDF library invoking these as necessary.
• Access to FITS format is available to any data processing application, since disk-FITS is one of the foreign formats supported by the NDF library in conjunction with the CONVERT package.
• Specific conversion from and to FITS within Figaro is supported only from/to disk files. IEEE floating point FITS (BITPIX -32) is not supported. In view of major changes to the FITS standard, Figaro will not contain FITS readers/writers other than the present ‘rdfits’ and ‘wdfits’. Even these will not be upgraded further. Up-to-date FITS support will be a matter for the KAPPA or CONVERT packages.
• The interface files must be ADAM interfaces (‘.ifl’ files).
• The executables are a small number of ‘monoliths’, each responsible for a large number of applications. The monoliths are triggered from the Unix shell or ICL by typing the application name.
• ‘par_batch’ works differently: When the monolith is invoked, it checks the environment variable ‘FIGARO_MODE’. If and only if it exists and its value converted to upper case equals ‘BATCH’, then batch mode is assumed. The application can at any time enquire the mode by calling ‘par_batch’.
• There is little support for Figaro software development.
• The object libraries do not contain all routines from Figaro 3.0.
• An application ‘igcur’ was added to examine an image previously displayed with ‘igrey’ or ‘icont’.
• ‘image’, ‘icur’, ‘colour’ and ‘clean’ were re-written or modified to use a graphics device very similar to the ‘soft’ device. The device is chosen with the command ‘idev’, which is a close relative of ‘soft’ and ‘hard’.
• Image pairs cannot be handled, blinking is not possible. This is primarily because modern displays are less than 8 bit deep.
G.1.1 Documentation

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.

G.1.2 General

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:

FIG_DIR        /star/bin/figaro
FIG_HELP       /star/help/figaro/figaro
FIGARO_PROG_S  /star/etc/figaro
FIGARO_PROG_N  /dev/null
FIGARO_FORMATS ndf,dst

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:

./file
$FIGARO_PROG_U/file$FIGARO_PROG_L/file
$FIGARO_PROG_N/file$FIGARO_PROG_S/file

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

• GKS: Graphics Kernel System (not a Starlink item, but available from RAL),
• SGS: Simple Graphics System,
• GNS: Graphics workstation Name Service,
• GWM: Graphics Window Manager,
• PGPLOT: Graphics Subroutine Library,
• HDS: Hierarchical Data System.

In Portable Figaro the following were added:

• The alink and compifl commands to link and to compile interfaces files.
• (A)PAR: The ADAM parameter system. Used only in a few A-task applications in ‘appstl’ and in FDA’s dsa_axis_range. But also the fundamental basis of (F)PAR.
• SUBPAR: The lower level of the ADAM parameter system. Used only in FDA’s dsa1_rdnam.
• PRIMDAT: Primitive Numerical Data processing. These are used for type conversions, while trapping errors and using bad values.
• PSX: Posix Fortran Interface. Used only in DSA.
• HELP: Interactive Help System.
• NDF: Extensible N-dimensional Data Format access routines. Via Figaro’s FDA library these perform data access to NDF format and indirectly to a multitude of foreign formats, which include DST.
• FIO: Fortran Input/Output routines. These are used to replace the VAX run-time library routines to get and release Fortran I/O units.
• CHR: Character Handling Routines. These are used only in a few A-task applications in ‘appstl’. But also widely used in FDA.
• ERR, EMS, MSG: Starlink error reporting and messaging. These are used in a few A-task applications in ‘appstl’. (F)PAR and FDA use MSG for messaging. DTA and occasionally DSA use EMS to suppress Starlink error reports. FDA uses ERR to report errors and MSG to issue warning messages.
• AGI: Application Graphics Interface. Some applications that are primarily display functions, save their plot in the AGI graphics data base. Other application packages can then pick up that information. The AGI compliance is achieved by calling new routines ‘fig_pgbeg’ and ‘fig_pgend’ instead of ‘pgbegin’ and ‘pgend’. To remove dependency on AGI, these two routines in the FIG library can be changed back to do only the trivial PGPLOT calls.
• PDA: Public Domain Algorithms’ Library. This is a replacement for the—proprietary—NAG library.

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. G.1.3 Ported applications 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: abconv abline adjoin alasin alasout arc bclean bfft bsmult ccdlin ccur caldiv cdist centers cfit clean clip cmplx2i cmplx2m cmplx2r cmplxadd cmplxconj cmplxdiv cmplxfilt cmplxmult cmplxsub coadd combine cosbell cosrej cset cspike dvdplot echarc echfind echmask echmerge echselect emlt elsplot errcon esplot extin extract fet321 ff ffcross fft figs321 figs322 figs422 figs423 figs424 figsee figsflux findsp fitskeys flconv foto fscrunch fwconv gauss growx growxt growxy growy growyt gspike hard hist hopt i2cmplx iadd iarc icadd icdiv icmult iconv3 icont icor16 icset icsub idiff idiv igrey ilist ilog imult interp iplots ipower irconv irevx irevy irflat irflux irot90 iscrunch iscruni isedit ishift ismooth isplot istat istretch isub isubset isuper isxadd isxdiv isxmul isxsub isyadd isydiv isymul isysub ixsmooth linterp lsplot lxset lyset mask maskext mcfit medfilt medsky msplot ncset offdist optextract overpf peak polext polysky profile r2cmplx rcgs2 rdfits rdipso rembad rescale retype rotx scnsky scross scrunch sdist sfit slice soft spflux spied spifit splot sqrterr table tippex vachel wdfits wdipso xcadd xcdiv xcmult xcopi xcopy xcsub xcur xtplane xyplane ystract ytplane 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: colour icur idev igcur image 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: creobj copobj delobj goodvar q2bad renobj setobj trimfile ‘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). G.1.4 New applications New applications are: aperture extlist hcross figinfo fitset flag2qual igconv medfiltr qual2flag resample ycadd ycdiv ycmult ycsub G.1.5 Un-ported applications 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: args blink bplot contract cpair cpos exam expand extlist figset find fits ierase ikon image2 imageps impair odist pair r4s rbaz rcshec rctio recoff recon rewind rjab rjkm rjpl rjt rlol rntyb rpdm rpfuei rshec rsit rspdm rspica rtyb rxmic sfind skip starin starout tape tapeo vshow wais wifits wjab wlol wpdm wjt wspica wvista zoom G.1.6 Parameters and variables: (F)PAR 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 value. 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.

G.1.7 Data access routines: FDA

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.

G.1.8 Old data access routines: DSA and DTA

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 ‘$\setminus$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 ‘$\setminus$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.

G.1.9 High-level subroutines: FIG

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.

G.1.10 The JT-library: JTY

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. G.1.12 Other libraries 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. G.2 Figaro 3.1-1 release 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: IMAGE Display an image ICUR Inspect an image with cursor IDEV Set the device for image display COLOUR Set colour table for image display CLEAN Interactive patching of bad lines, bad pixels in an image The following three applications are also new and replace two discontinued ones: COPOBJ Copy an HDS object (replaces LET) CREOBJ Create a data object or file (replaces CROBJ) SETOBJ Assign value to an HDS primitive (replaces LET) 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 inFIGARO_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:

% xmake xwindows  -colour 16  -geom -0-0
% xmake xwindows2 -colour 128 -geom 512x512-0+0
% figaro
% soft xw
% idev x2w

G.3 Figaro 3.2 release

• Contrary to versions 3.1-0 and 3.1-1 this is regarded as a complete package. A new version of the printed User Guide, Starlink User Note 86, version 9, is associated with this release.
• Figaro 3.2 is released for Sun4 (SunOS 4.x), Sun4 (Solaris), DECstation (Ultrix) and Alpha AXP (OSF/1). It has been tested on VAX/VMS (ICL).
• As a service to non-Starlink sites interested in Figaro, the required items from the Starlink Software Collection have been identified and can be shipped as a tar file for any Starlink-supported combination of hardware and operating system. A minimum set is about 10 MByte in size, the full set (including Figaro sources, Figaro object libraries and necessary Starlink libraries) is about 35 MByte.
• Figaro 3.2 includes disk-FITS support. There is no support for tape-FITS, but FITS files can be copied from and to tape with Unix commands.
• Some remaining non-DSA applications were converted to use the DSA library for data access. Thus all applications now support DST and NDF data format. The only exception is that the multi-dimensional axis array needed by SCRUNCH—and created by ECHARC, XCOPI or XCOPY—is not yet supported in NDF format.
• A number of applications were converted to no longer use 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.
• A number of bugs have been fixed. Most notably, workspaces used internally were not always released after use (by DSA_UNMAP). MEDSKY in particular did often hit the limit of 32 workspace slots and abort.
• FIGHELP will now find out the terminal size (as set with stty) and page accordingly. Its use is simpler and better documented (try "fighelp fighelp"), you can leave FIGHELP at any prompt including the paging prompt.

To start Figaro on Unix, type:

% figaro

You should ensure you have a directory $HOME/adam. Help on Figaro may be obtained by typing % fighelp figaro % fighelp news % fighelp \\ Further details can also be found in SUN/86.9. G.3.1 On-line help topic “News 3.2” The printed documentation for Portable Figaro 3.2 is Starlink User Note 86. Figaro 3.2 includes disk-FITS support, i.e. the applications RDFITS Read file in AAO de facto ’Disk FITS’ format WDFITS Writes an image out in the AAO de facto ’Disk FITS’ format 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: % mt -f /dev/nrst1 eom # forward to end of tape % dd if=file.fits of=/dev/nrst1 obs=2880 # append FITS file to tape % mt -f /dev/nrst1 rewind # rewind % mt -f /dev/nrst1 fsf 5 # skip over five files % dd of=file.fits if=/dev/nrst1 ibs=2880 # copy 6th file from tape 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: ABLINE, ECHARC, ECHFIND, ECHMASK, ECHMERGE, FET321, FIGS424 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. ABLINE, ARC, CENTERS, CFIT, CLEAN, CSET, ECHARC, ECHSELECT, FINDSP, FOTO, GAUSS, IPLOTS, ISEDIT, MSPLOT, SDIST, SPIED, TIPPEX 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. G.4 Figaro 3.2-3 release • Some bugs have been fixed. This involves arc/echarc, copobj, gspike, interp, xcopi. • Version 3.2-3 is linked with HDS 4.1, which provides some safeguard against corrupting an input file. Some applications cannot operate in situ on input data, but force a new output file. In earlier versions if the same name was given for output as for input, then the input (and output) file would have been corrupted. • Version 3.2-3 is linked with PAR 2.0, which supports the use of strings "min" and "max" when prompted for a number. The workaround in previous versions to use ridiculously small and big numbers does no longer work. • There are new applications HCROSS to calculate redshifts and APERTURE for simple photometry. • Version 3.2-3 runs under ICL. To start up the package give the ICL command ICL> load$FIG_DIR/figaro
• The monolith has been split into three separate ones in order that Figaro runs under ICL. The single monolith would have an interface too big for the ADAM parameter system to handle. This does not affect the way the user runs commands.
• The C routine gen_qdisort has been removed. Its maintenance has always been a problem due to different alignment rules for Fortran doubles and C doubles on Sun machines. Figaro’s use of the routine could be diverted to its sister routine gen_qfisort.
• Reading IEEE floating point disk-FITS with RDFITS has been disabled. This did not work on Alpha workstations. The problem was in the interface between routines written in Fortran and C, combined with the different type sizes in different C implementations. IEEE floating point FITS data can be read into NDF format with the FITS readers in the KAPPA package.
• The parameter 16BIT of WDFITS has been changed to BIT16. The parameter name beginning with a digit caused problems in the ADAM parameter system.
• The hints for programmers in SUN/86 are slightly out of date:
• Object libraries are now e.g. /star/figaro/dsa/libdsa.a. Thus each library is in a different directory. For the time being there are symbolic links for all libraries in /star/figaro/lib, so that the old names should still work.
• The directory /star/figaro/mono is discontinued. The relevant information is now in /star/figaro. Also, the monolith source code is now in /star/figaro/figaro[123].for.

G.5 Figaro 5.0 release

Major changes is this release are:

• ICL is preferred command line interface
• HyperText help
• improved DSA library
• the proprietary NAG library is no longer used
• passive AGI compliance
• GKS is no longer called directly, all plotting via PGPLOT
• bug fixes
• new applications

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.

1  2  3  4  5  6  7  8  9 10 11 12
x                       x  abline
x           x     arc
x                             bclean
x              x           bfft
x              ccur
x                          cdist
x           x              cfit
x  cosrej
x              cset
x                       dvdplot
1  2  3  4  5  6  7  8  9 10 11 12
x        x           x     echarc
x                          echfind
x                             emlt
x        x              esplot
x                             exam
x                                extlist
x              x           fft
x                                figinfo
x     x                    findsp
x                                fitset
1  2  3  4  5  6  7  8  9 10 11 12
x                                flag2qual
x           gauss
x        growx
x        growy
x        growxt
x        growxy
x        growyt
x        x  hcross
x                       hopt
x  i2cmplx
1  2  3  4  5  6  7  8  9 10 11 12
x           x     iarc
x           x           icont
x                                igconv
x           x           igrey
x                       image
x                          interp
x           iplots
x  x        iscrunch
x  x        iscruni
x        isubset
1  2  3  4  5  6  7  8  9 10 11 12
x        isuper
x                          mcfit
x                                medfiltr
x                             offdist
x                    overpf
x                    x     polext
x                       x  polysky
x                       x  profile
x                                qual2flag
x  x        r2cmplx
1  2  3  4  5  6  7  8  9 10 11 12
x                             rdispo
x                                resample
x                             retype
x  x                    x     sdist
x                          sfit
x                    x     spied
x        x              splot
x              tippex
x                             wdipso
x        xyplane
1  2  3  4  5  6  7  8  9 10 11 12
x        xtplane
x                                   ycdiv
x                                   ycmult
x                                   ycsub
x        ystract
x        ytplane
1  2  3  4  5  6  7  8  9 10 11 12
(1)
new in 5.0
(2)
new, adopted from Standalone Portable Figaro 4.2
(3)
new version, adopted from Standalone Portable Figaro 4.2
(4)
no longer uses NAG
(5)
saves last plot in AGI data base for the benefit of KAPPA and other application packages
(6)
no longer uses GKS directly
(7)
improved behaviour regarding text output files: arc and echarc will now abort if arlines.* cannot be opened for output; iarc will overwrite the *.iar file if it exists
(8)
improved storage of image file information
(9)
(10)
output data access corrected from ‘update’ to ‘write’
(11)
work space alignment corrected
(12)
other bug fix

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

• Figaro data access now prefers to create ‘simple’ NDF format instead of ‘primitive’ NDF format. This results in more efficient data access and better compatibility with applications that use the NDF library itself to handle NDF format data.
• The data access routines now allow N-dimensional axis data in NDF format (namely 2-D wavelengths arrays in échelle arc calibration).
• It is now permissible to have quality information in two distinct forms. Before, such information had to be either as flagged values or as a quality array. Now both forms may exist at the same time in the same data set.
• It is now possible to replace the input file with the output file even when a new file is required. This is usually a problem when the shape of the output data is different from that of the input data. The processing can then not happen in-situ. On VMS you could create an output file of the same name as the input, but with higher version number. On Unix you can now replace the original file with the new one: the output is created as a file with name ‘Temp_File_1.tmp’ or something similar. The temporary file is renamed when the data access is closed down, hence overwriting the input file. Note that if an application aborts or crashes, such temporary files may become permanent and you may have to delete them explicitly.
• The library is more tolerant (than NDF) in recognising whether data are free of flagged values. This should improve backwards compatibility with NDF data created by Figaro 3.0.

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 agi_$<$host$>$.sdf 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.

G.5.1 Figaro 5.0-1 news item

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.)

G.6 Figaro 5.1-3 release

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:

% figaro
% convert

and from ICL:

ICL> figaro
ICL> convert

The data format is selected by the user on a per-file basis by specifying a file name extension:

ICL> istat myfile

will try all known formats in order of priority, to choose a format explicitly:

ICL> istat myfile.dst

Currently the extensions recognised, the formats addressed, and the priority list are:

.sdf     NDF format
.fit     FITS format (disk FITS, IBM byte order)
.dst     DST format (also called Figaro format)
.imh     IRAF format
.hdr     GASP format
.unf     unformatted binary files
.dat     unf0 binary files
.asc     ASCII files
.txt     text files
.gif     GIF images
.tif     TIFF images
.sdf.Z   compressed NDF files

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:

file(3:5,21.3:44.5,17,17.0,3:,,:99)

(3:5,           1st axis: pixels 3 through 5
21.3:44.5,     2nd axis: pixel centre values 21.3 through 44.5
17,            3rd axis: pixel 17 only
17.0,          4th axis: only the pixel with centre = 17.0
3:,            5th axis: pixels 3 through end of NDF
,              6th axis: all pixels
:99)           7th axis: pixels from start of NDF through to pixel 99

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.

‘figwww’ has been removed, use ’showme sun86’ instead.

Bug fixes in applications:

• ‘cdist’ should now abort with an error message if the end of file is encountered before all information has been read.
• ‘echarc’ has separate parameter ‘output’ now for a copy of input with calibrated wavelengths.
• ‘echmerge’ when given two input files, will now actually map the first and second data, before it mapped the first data twice and ignored the second.
• ‘fet321’ now calls dsa_close at the end. Before it called dsa_open a second time.
• ‘ffcross’ now maps the cross correlation for write instead of update.
• ‘fft’ will now simply replace the axis information according to the Fourier transform that is being applied. It will no longer save the old axis information. ‘bfft’ will therefore simply delete all axis information and not restore the pre-fft information. Users can copy axis information from the pre-fft file to the post-bfft file, of course.
• ‘hcross’ will no longer crash when the power 0.0**0.0 is calculated.
• ‘isplot’ now constructs plot labels as ‘LABEL / UNITS’, before it was the other way round.
• ‘wdfits’ now has initial values for variables BLOCK and NOTERM.
• A possible infinite loop in ‘fitskeys’ has been removed.

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:

• Changes to all interface files, where data sets now have type ’NDF’ instead of ’LITERAL’. (One parameter was left at ’LITERAL’ and had its global association removed.) All NDF-type parameters have access information in the interface file, telling whether the data set is input or output data.
• Use of NDF-type parameters to open data sets in ‘abline’, ‘aperture’, ‘growx’, ‘growy’, ‘growxy’, ‘growxt’, ‘growyt’, ‘hist’, ‘irflat’.
• Use of new routine ‘dsa_input_update’ in ‘figinfo’, ‘fitset’, ‘growx’, ‘growy’, ‘growxy’, ‘growxt’, ‘growyt’, ‘i2cmplx’.
• Changes to call sequence with respect to enquiring an axis range and mapping axis data in ‘alasout’, ‘emlt’, ‘ilist’, ‘iplots’, ‘isplot’, ‘istat’, ‘isubset’, ‘lsplot’, ‘elsplot’, ‘msplot’, ‘splot’ ‘esplot’.
• Changes to call sequence with respect to mapping real part and deleting imaginary part in ‘cmplx2r’, ‘cmplx2i’, ‘cmplx2m’.
• Changes to call sequence with respect to mapping data and quality: ‘surfit’ (not available for use due to NAG call).
• Mapping quality with the correct data type in ‘adjoin’, ‘optextract’.
• Changes to call sequence with respect to re-shaping data and axis in ‘figs422’.
• Use of new routine ‘dsa_map_complex’ in ‘cmplx2r’, ‘cmplx2i’, ‘cmplx2m’, ‘cmplxadd’, ‘cmplxdiv’, ‘cmplxmult’, ‘cmplxadd’, ‘cmplxconj’, ‘cmplxfilt’, ‘fft’, ‘bfft’, ‘i2cmplx’, ‘r2cmplx’.
• Disuse of DTA error messages in ‘alasout’, ‘cspike’, ‘fet321’, ‘figs424’, ‘rcgs2’.
• Avoidance of DTA mapping routines in ‘irflat’, ‘rcgs2’.
• Cosmetic changes to the DYNAMIC_MEMORY include file.
• Addition of routines ‘dsa_input_update’, ‘dsa_named_input_update’, and ‘dsa_map_complex’ to the DSA library. These allow the modified appliclations to be linked against DSA/DTA.
• Removal of routines ‘fig_convchk’ and ‘fig_dtaerr’, which are related to the now unused DTA library.

G.7 Figaro 5.1-4 release

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:

• New Starlink support team for Figaro.
• Addition of the ability to select between using pixel indices and pixel centres in addressing data arrays.
• Bug fixes.

See §G.7.1 for further details.

Recent Developments

• Rationale for the change.
• History Recording.
• Removal of the ‘exam’ command (and what replaces it).

§G.7.3 describes these.

Practical Information

§G.7.2 contains practical information on the following.

• How to process a list of files with a command.
• How to save disk space when using ‘isubset’.
• How to use the value of a parameter from one command when using a second command.
• How to explicitly access a non-NDF file via the new Figaro Data Access Library (FDA).
G.7.1 Release notes

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

% delobj myndf.axis

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,

% kappa    # only needed if you have not activated KAPPA already
% setaxis spectrum mode=expr exprs=index
% setaxis image 2 expr exprs=index

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.

Bug Fixes

Fixes to applications:

• ‘adjoin’ — the input SPECTRUM can now be overwritten.
• ‘irconv’ — a bug caused by the use of a locator to an existing Figaro extension in a file prior to obtaining the locator has been removed. This prevented the magnitude flag from being written.
• ‘irflat’ — the scan position array is now fully filled.
• ‘irflux’ — a parameter missing from the interface file has been added.
• ‘isubset’ — several bugs related to the propagation of 2-D axis data from the input to the output have been removed.
• ‘profile’ — an error in the ordering of two DSA_ calls has been fixed ensuring that the output dataset exists before being written to.
• ‘wdfits’ — A bug which could generate a second END card in the FITS header has been removed.
• ‘icmult/icdiv’ — Now correctly propagate errors for negative values of FACTOR.
• Abort to Parameters - in many applications an abort response (!!) to a parameter prompt would not have the desired effect. This has been fixed in 28 tasks.

Other fixes:

• If UPDATE access to a dataset is requested via the FDA library, a check that the output target exists is made before attempting access. If the target does not exist it is created.
• Trailing blanks present in input NDF axes LABEL and UNITS strings are now propagated to the output. Previously, these were truncated, leading to an error in the case of a completely blank string.
• Accesses to undefined AXIS UNITS in FDA have been removed.
• Some applications request input or output datafile names other than for NDFs. The maximum length of the path and filename allowed for these has been standardised at 132 characters. Previously, this varied from 32 to 132 characters. 29 applications have been altered as a result.
• The maximum Y-dimension of images used by ‘findsp’ has been increased from 500 to 4096 pixels.
G.7.2 Figaro tips
(1)
How to process a list of files with a command

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:

% foreach f ( run1??.sdf )
? icadd $f:r 5.6$f:r
? end

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:

% foreach f ( run1??.sdf )
? icadd $f:r 5.6$f:r_db
? end

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:

#!/bin/csh
set c = $1 # Gets constant to be added from first arg. shift # Throws away constant from list of args. foreach f ($* ) # Processes list of files.
icadd $f:r$f:r_db
end
(2)
How to save disk space when using ISUBSET

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 $100×100$-pixel subset from an image, and would normally use:

% isubset im=inimage ys=200 ye=299 xs=250 xe=349 out=outimage

(note the use of abbreviated parameter names, see notes for 5.1-3), the same subset can be obtained by:

% isubset im=inimage’(200:299,250:349)’ ys=min ye=max \
xs=min xe=max out=outimage

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.

% ndfcopy inimage’(200:299,250:349)’ outimage
(3)
How to use the value of a parameter from one command when using a second command

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:

% istat im=image median
% icsub im=image fac=@$ADAM_USER/istat.median out=outimage 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). (4) How to explicitly access a non-NDF file via the new Figaro Data-Access Library (FDA) 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 % figaro % convert % icsub image 4 output will select the NDF, assuming you have not altered the default precedence used (see notes for 5.1-3), and % figaro % convert % icsub image.dst 4 output will select the DST file explicitly. The environment variable FIGARO_FORMATS is no longer used. G.7.3 New Figaro features 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. History Recording 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. % hisset 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. % hisset spectrum disabled % hisset spectrum erase KAPPA also provides commands for adding commentary (HISCOM), and listing the history records (HISLIST). If you enter % findme "NDF History" 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: % exam image.. The same thing can be done using hdstrace by: % hdstrace image full (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: % hdstrace image.more.figaro.airmass might display: STRUCT.MORE.FIGARO.AIRMASS <_REAL> AIRMASS 1.324 End of Trace. This value could be used in a C-shell script like this: set airmass = ‘hdstrace image.more.figaro.airmass \ | grep " AIRMASS"‘ shift airmass # Throws away the object’s name 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.

% hdstrace @\"image.dst\"
% hdstrace @\"image.dst\".obs.airmass

Note the backslash is needed to escape the " special character from the UNIX shell.

G.8 Figaro 5.1-6 release

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.

G.8.1 Release notes

The main changes at this release are:

• The HELP text has been tidied as part of the preparation for an IRAF version of Figaro.
• Workspace for internal calculations is now allocated from memory, rather than in temporary NDFs. This leads to an improvement in speed for applications effected. The difference is generally quite small, except where the working directory resides on a ‘remote’ NFS-mounted disk. In this case the change is quite significant and is most noticeable with a command like ‘image’. Typically, the task completes in 15–25% of the time previously taken, depending on the level of network activity and disk usage. After the image is displayed, there is no longer a delay before the shell prompt returns. See ‘Figaro Tips’ below for more information on optimising your use of Figaro.

The applications for which this change will be significant are:

APERTURE CLEAN    COADD   ECHARC FIGS321  FIGS322
IGCONV   IMAGE    ISEDIT  ISHIFT ISTAT    ISTRETCH
MEDFILT  MEDFILTR MEDSKY  OVERPF RETYPE

‘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.

• The routine DSA_RESHAPE_DATA has been modified to ensure that the minimum space required for an output file is used. Previously, the size of an output file from a task using DSA_RESHAPE_DATA would be the same as the input file. This change effects several applications, notably ‘extract’ and ‘ystract’. These two commands, which produce spectra from input 2-D datasets, would previously produce output files much larger than needed.
• Bug fixes.
• The Introduction and Beginners sections of SUN/86 have been updated; this reflects the withdrawal of XADAM.
G.8.2 Figaro tips
(1)
Speeding up processing of data stored on remote disks

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. (2) Speeding up ‘on-the-fly’ data format conversions 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: % figaro % convert % image starimage.fit 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:

% figaro
% convert
% image starimage.fit

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.

G.8.3 Bug fixes

Fixes to applications:

• ‘alasin’ — Now works again, an error searching for End-of-file has been fixed.
• ‘icur’ — The output list of user-selected points is limited in size to the number of points, rather than the maximum number of points. This change will only effect those using Figaro under the IRAF cl.
• ‘medsky’ — The size of an internal workspace array has been enlarged by a factor of 16. For input data with quality information ‘medsky’ will run about 10 times faster than previously. There is a small improvement in speed for all data, regardless of the presence of a QUALITY component.

G.9 Figaro 5.2-0 release

This news item accompanied the release of Figaro version 5.2-0.

G.9.1 Release notes

The main changes at this release are:

• Enhanced and updated error propagation in many tasks. See below for more details.
• New task ‘ialog’ to take the antilog of pixels in a dataset. See SUN/86 or the on-line HELP for details.
• Bug fixes in Linux version.

There is a world-wide web page including Figaro documentation and related information:

• http://www.star.ucl.ac.uk/˜mjc/figaro/
G.9.2 Error propagation

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:

• The majority of the mathematical operations
• B-star spectra
• Variance "fudging" for fitting data
• Removal of cosmic rays and bad columns

In the following tasks, error handling has been added or corrected at this release:

BCLEAN     BSMULT     CSET       EXTRACT    FF         GROWX
GROWY      IALOG      ICADD      ICDIV      ICMULT     ICSUB
ISYDIV     ISYMULT    ISYSUB     POLYSKY    YSTRACT

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:

ABCONV     ADJOIN     COMBINE    ERRCON     FIGSFLUX   FSCRUNCH
GAUSS      IADD       IDIV       ILOG       IMULT      ISUB
IREVX      IREVY      IRFLUX     IROT90     ISEDIT     ISUBSET
G.9.3 Bug fixes

Fixes to applications:

• ‘istat’ — A bug in the Linux version of ‘istat’, resulting in a random output message for 1-D data, has been removed.
• ‘medsky’ — A bug in the Linux version of ‘medsky’, causing the task to fail completely, has been removed.

Fixes to Linux release:

• For some applications with variance propagation, a segmentation fault would occur if one or more of the input data files were incorrectly specified (if the file did not exist for example). This error has been removed.

G.10 Figaro 5.3-0 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:

• incorporation of the SPECDRE spectroscopy package,
• incorporation of IRAFFIG (which allows Figaro to be run from IRAF).

In addition there are a couple of minor enhancements.

A.C. Davenhall (acd@roe.ac.uk), 19 December 1997.

G.10.1 Incorporation of SPECDRE

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:

• SPECDRE command RESAMPLE is now command RESAMP (to avoid a name clash with the Figaro command RESAMPLE),
• command GOODVAR has 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.

G.10.2 Incorporation of IRAFFIG

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.

G.10.3 Minor enhancements

Version 5.3-0 includes the following minor enhancements:

• Applications ARC and ECHARC now simply overwrite any pre-existing file called arlines.lis rather than terminating with a message,
• the maximum permitted number of elements in a re-binned spectrum created with SCRUNCH has been increased to 5,000,000.

In addition there have been a couple of bug fixes.

G.11 Figaro 5.4-0 release

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.

G.12 Figaro 5.5-0 release

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.

G.13 Figaro 5.5-1 release

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.

G.14 Figaro 5.5-2 release

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.

G.15 Figaro 5.6-0 release

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.

G.15.1 Error Propagation

Error Propagation has been added to the following applications: BBODY, FWCONV, IRFLAT, ISHIFT, IXSMOOTH and SFIT.

G.15.2 Bug Fixes and Minor Enhancements

Either bugs have been fixed in, or minor enhancements have been made to, the following applications: CSPIKE, ECHSELECT, EMLT, FITGAUSS, SCROSS and SPFLUX. In addition, corrections have been made to the documentation for CENTERS and SPECCONT.

G.15.3 New Application

The new application IMPOS has been added. It simply reads a text file containing a list of $x,y$ positions and writes them to the environment variables which input values to application CENTERS. Thus, it provides a mechanism for using CENTERS from a script rather than interactively.

G.16 Figaro 5.6-1 release

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 to application 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.

G.16.1 Bug Fixes and Minor Enhancements

Bugs have been fixed in: EMLT, ICUR, IMAGE, POLYSKY and XTRACT.

An option has been added to IARC to allow it to perform weighted as well as un-weighted fits.

G.16.2 Flux calibration standard stars

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.

G.17 Figaro 5.6-2 release

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.

G.18 Figaro 5.6-3 release

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.

G.18.1 Bug Fixes and Minor Enhancements

GAUSS and 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.

G.18.2 Flux Calibration Files

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.