D Applications in detail

 D.1 ABCONV-Convert spectrum from Janskys into AB magnitudes
 D.2 ABLINE-Interactive absorption line analysis
 D.3 ADJOIN-Append two spectra (strictly a merge by wavelength value)
 D.4 ALASIN-Read a spectrum in ALAS (Abs. Line Analysis System) format
 D.5 ALASOUT-Output a spectrum in ALAS (Abs. Line Analysis System) format
 D.6 APERTURE-Do simple minded aperture photometry on a series of frames
 D.7 ARC-Interactive manual arc line identification
 D.8 ARC2D-Calibrates distortions in 2D arc line data.
 D.9 ARCDISP-Fit polynomial dispersion curve.
 D.10 ARCGENDB-Convert list of laboratory values to feature data base.
 D.11 ARCIDENT-Auto-identify located features.
 D.12 ARCLOCAT-Locate line features in a set of spectra.
 D.13 ARCSDI-Corrects for arc line curvature
 D.14 ASCIN-Read a 1-D or N-D data set from an ASCII table.
 D.15 ASCOUT-Write an NDF to an ASCII table.
 D.16 BBODY-Calculate a black body spectrum.
 D.17 BCLEAN-Automatic removal of bad lines and cosmic rays from CCD data
 D.18 BFFT-Takes the reverse FFT of a complex data structure
 D.19 BSMULT-Atmospheric band removal using a B star calibration spectrum
 D.20 CADD-Add back fitted continuum
 D.21 CALDIV-Generate calibration spectrum from continuum standard spectra
 D.22 CCDLIN-Applies a linearity correction to AAO CCD data
 D.23 CCUR-After SPLOT, uses graphics cursor to indicate data values
 D.24 CDIST-S-distortion correction using SDIST results
 D.25 CENTERS-Generate file of object centroids from ICUR, IGCUR or IMPOS output
 D.26 CFIT-Generate a spectrum using the cursor
 D.27 CHANGED-Indicate fits invalidated due to "cleaning" of an image
 D.28 CLEAN-Interactive patching of bad lines, bad pixels in an image
 D.29 CLIP-Clip data above and below a pair of threshold values
 D.30 CMPLX2I-Extracts the imaginary part of a complex data structure
 D.31 CMPLX2M-Extracts the modulus of a complex data structure
 D.32 CMPLX2R-Extracts the real part of a complex data structure
 D.33 CMPLXADD-Add two complex structures
 D.34 CMPLXCONJ-Produce the complex conjugate of a complex structure
 D.35 CMPLXDIV-Divide two complex structures
 D.36 CMPLXFILT-Create a mid-pass filter for complex data
 D.37 CMPLXMULT-Multiply two complex structures
 D.38 CMPLXSUB-Subtract two complex structures
 D.39 COADD-Form the spectrum which is the mean of the rows in an image
 D.40 COLOUR-Set colour table for image display
 D.41 COMB-Corrects for S-distortion using continua
 D.42 COMBINE-Combine two spectra, adding with weights according to errors
 D.43 COPOBJ-Copy an HDS object
 D.44 CORREL-Correlate two or three data sets.
 D.45 COSBELL-Create data that goes to zero at the edges in a cosine bell
 D.46 COSREJ-Reject cosmic rays from a set of supposedly identical spectra
 D.47 CREOBJ-Create a data object or file
 D.48 CRIGAUSS-Creates a file with a profile of 1 to 5 gaussians
 D.49 CSCAN-Plot array of profiles from a 3D array
 D.50 CSET-Interactively set regions of a spectrum to a constant value
 D.51 CSPIKE-Create calibration spiketrum given spiketrum and standard spectrum
 D.52 CSUB-Subtracts a continuum from 2 dimensional data
 D.53 CUBE2LONG-Takes a longslit spectrum from a non-sorted TAURUS cube
 D.54 DELOBJ-Delete a data object or a file
 D.55 DVDPLOT-Plot the data in one file against the data in another
 D.56 ECHARC-Wavelength calibrate an echelle arc
 D.57 ECHFIND-Locate spectra in echelle data
 D.58 ECHMASK-Produce an extraction mask from an SDIST analysis
 D.59 ECHMERGE-Merge echelle spectra into a single long spectrum
 D.60 ECHSELECT-Interactive selection of sky and object spectra for an echelle
 D.61 EDITEXT-Edit the Specdre Extension.
 D.62 ELSPLOT-Produces a long (<3m) error bar plot of a spectrum
 D.63 EMLT-Fits gaussians to the strongest lines in a spectrum
 D.64 ERRCON-Converts percentage error values to absolute values
 D.65 ESPLOT-Produces an error bar plot of a spectrum
 D.66 EVALFIT-Evaluate fit results.
 D.67 EXAM-Display the contents/structure of data file
 D.68 EXTIN-Correct spectrum for atmospheric extinction
 D.69 EXTLIST-Adds non-contiguous lines of an image to form a spectrum
 D.70 EXTRACT-Adds contiguous lines of an image to form a spectrum
 D.71 FET321-Extracts a spectrum from 1 detector from etalon mode FIGS data
 D.72 FF-Flat field an image (uses Jon Tonry’s algorithm)
 D.73 FFCROSS-Cross-correlate an image and a flat field (mainly IPCS data)
 D.74 FFT-Takes the forward FFT of a complex data structure
 D.75 FIB2CUBE-Arranges fibre output into 3-d data file
 D.76 FIBDISP-Fits 3D cubes and plots the results
 D.77 FIBSEP-Separate spectra in 2D array
 D.78 FIGHELP-Provide Figaro on-line help
 D.79 FIGINFO-Describes the contents of a Figaro data file
 D.80 FIGS321-Processes a FIGS data cube down to a single spectrum
 D.81 FIGS322-Processes a FIGS data cube down to an image
 D.82 FIGS422-Process a FIGS image-mode hypercube down to an image
 D.83 FIGS423-Process a FIGS image-mode hypercube down to a cube
 D.84 FIGS424-Sort a FIGS image-mode hypercube into wavelength order
 D.85 FIGSEE-Generate a seeing ripple spectrum from a FIGS spectrum
 D.86 FIGSFLUX-Flux calibrates a FIGS spectrum
 D.87 FILLCUBE-Copy one NDF into part of another.
 D.88 FINDSP-Locate fibre spectra in an image
 D.89 FITBB-Fit diluted Planck curves to a spectrum.
 D.90 FITCONT-Fits a Chebyshev polynomial to the continuum for 2D data
 D.91 FITGAUSS-Fit Gauss profiles to a spectrum.
 D.92 FITPOLY-Fit a polynomial to a spectrum.
 D.93 FITSET-Set the value of a FITS keyword
 D.94 FITSKEYS-List the FITS keywords in a data file
 D.95 FITTRI-Fit triangular profiles to a spectrum.
 D.96 FLAG2QUAL-Converts ‘flagged’ values to produce a quality array
 D.97 FLAIRCOMP-Compresses a FLAIR frame to give a weight vector.
 D.98 FLAIREXT-Optimally extracts spectra from a FLAIR NDF to form a new NDF.
 D.99 FLCONV-Convert a spectrum in Janskys into one in erg/s/cm**2/Angstrom
 D.100 FOTO-Perform aperture photometry given CENTERS output
 D.101 FSCRUNCH-Rebin data with a disjoint wavelength coverage to a linear one
 D.102 FWCONV-General unit conversion for spectra
 D.103 GAUSS-Interactive fit of Gaussians to emission or absorption lines
 D.104 GOODVAR-Replace negative, zero and bad variance values
 D.105 GROW-Copy an N-dimensional cube into part of an (N+M)-dimensional one.
 D.106 GROWX-Performs reverse function to that of EXTRACT
 D.107 GROWXT-Copies an image into contiguous XT planes of a cube
 D.108 GROWXY-Copies an image into contiguous XY planes of a cube
 D.109 GROWY-Performs reverse function to that of YSTRACT
 D.110 GROWYT-Copies an image into contiguous YT planes of a cube
 D.111 GSPIKE-Generates a ’spiketrum’ from a table of values
 D.112 HARD-Sets the file name for hard copy output
 D.113 HCROSS-Cross-correlate two spectra and get redshift and error
 D.114 HIMAGE-Creates greyscale plot of image
 D.115 HIST-Produce histogram of data value distribution in an image
 D.116 HOPT-Histogram optimization of an image
 D.117 I2CMPLX-Copies an array into the imaginary part of a complex structure
 D.118 IADD-Adds two images (or two spectra)
 D.119 IALOG-Takes the antilog of an image
 D.120 IARC-Given fit to single spectrum, fit all spectra in a 2-D arc
 D.121 ICADD-Adds a constant to an image
 D.122 ICDIV-Divides an image by a constant
 D.123 ICMULT-Multiplies an image by a constant
 D.124 ICONT-Produces a contour map of an image
 D.125 ICONV3-Convolve an image with a 3x3 convolution kernel
 D.126 ICOR16-Corrects 16 bit data from signed to unsigned range
 D.127 ICSET-Set a selected region of an image to a constant value
 D.128 ICSUB-Subtracts a constant from an image
 D.129 ICUR-Inspect an image with cursor
 D.130 IDEV-Set the device for image display
 D.131 IDIFF-Takes the ’differential’ of an image
 D.132 IDIV-Divides two images (or two spectra)
 D.133 IGCONV-Convolve an image with a specified filter
 D.134 IGCUR-Use cursor to show X, Y and data values
 D.135 IGREY-Produces a grey-scale plot of an image
 D.136 ILIST-List the data in an image (or spectrum)
 D.137 ILOG-Takes the logarithm of an image
 D.138 IMAGE-Display an image
 D.139 IMPOS-read positions from a file into environment variables
 D.140 IMULT-Multiplies two images (or two spectra)
 D.141 INTERP-Interpolates points of a ’spiketrum’ to form a spectrum
 D.142 IPLOTS-Plots successive cross-sections of an image, several to a page
 D.143 IPOWER-Raises an image to a specified power
 D.144 IRCONV-Converts data in Janskys to W/m**2/um
 D.145 IREVX-Reverse an image (or spectrum) in the X-direction
 D.146 IREVY-Reverse an image in the Y-direction
 D.147 IRFLAT-Generates a ripple spectrum from an IR spectrum
 D.148 IRFLUX-Flux calibrates an IR spectrum using a black-body model
 D.149 IROT90-Rotates an image through 90 degrees
 D.150 ISCAN-Displays cuts through an IMAGE
 D.151 ISCRUNCH-Rebin an image to linear wavelength scale given IARC results
 D.152 ISCRUNI-Like ISCRUNCH, but interpolates between two IARC result sets
 D.153 ISEDIT-Allows interactive editing of a 1-D or 2-D spectrum
 D.154 ISHIFT-Applies a linear X and a linear Y shift to an image
 D.155 ISMOOTH-2-D smooth of image using 9-point smoothing algorithm
 D.156 ISPLOT-Plots successive cross-sections through an image
 D.157 ISTAT-Provides some statistics about an image (max, min etc.)
 D.158 ISTRETCH-Stretches and shifts an image in X and Y.
 D.159 ISUB-Subtracts two images (or two spectra)
 D.160 ISUBSET-Produces a subset of an image
 D.161 ISUPER-Produces a superset of an image
 D.162 ISXADD-Adds a spectrum to each X direction X-section of an image
 D.163 ISXDIV-Divides a spectrum into each X direction x-section of an image
 D.164 ISXMUL-Multiplies each X direction image x-sect by a spectrum
 D.165 ISXSUB-Subtracts each X direction image x-sect from a spectrum
 D.166 ISYADD-Adds a spectrum to each Y direction x-section of an image
 D.167 ISYDIV-Divides a spectrum into each Y direction x-section of an image
 D.168 ISYMUL-Multiplies each Y direction image x-sect by a spectrum
 D.169 ISYSUB-Subtracts each Y direction image x-sect from a spectrum
 D.170 IXSMOOTH-Smooth in X-direction by gaussian convolution
 D.171 LINTERP-Interpolates between spiketrum points to form a spectrum
 D.172 LONGSLIT-Fits 2D longslit arrays and plots results
 D.173 LSPLOT-Hardcopy spectrum plot of specified size (up to 3 metres)
 D.174 LXSET-Set X array of spectrum/image to specified range
 D.175 LYSET-Set Y array of spectrum/image to specified range
 D.176 MASK-Generate a mask spectrum given a spectrum and a mask table
 D.177 MASKEXT-Extracts echelle orders using a mask created by ECHMASK
 D.178 MCFIT-Fit a continuum to a spectrum, given a mask spectrum
 D.179 MEDFILT-Applies a median filter to an image
 D.180 MEDFILTR-Applies a rectangular median filter to an image
 D.181 MEDSKY-Take the median of a number of images
 D.182 MOMENTS-Calculate moments of spectra in a cube.
 D.183 MOVIE-Browse through slices of a cube.
 D.184 MSPLOT-Plots a long spectrum as a series of separate plots
 D.185 NCSET-Set a region of a spectrum to a constant
 D.186 OFFDIST-Applies an offset to an SDIST fit
 D.187 OPTEXTRACT-Extracts a long-slit spectrum using Horne’s algorithm
 D.188 OVERPF-Overlays a FINDSP fit on another image
 D.189 PEAK-Determines position of highest peak in a spectrum
 D.190 POLEXT-Extract fibre spectra from an image after a FINDSP analysis
 D.191 POLYSKY-Fits and subtracts sky from a long-slit spectrum
 D.192 PROFILE-Profiles a long-slit spectrum for use by OPTEXTRACT
 D.193 Q2BAD-Converts a datafile’s quality into bad values
 D.194 QUAL2FLAG-Converts a quality array into ‘flagged’ values
 D.195 R2CMPLX-Creates a complex data structure from a real data array
 D.196 RCGS2-Reads UKIRT CGS2 spectrum (also UKT9 and UKT6 CVF)
 D.197 RDFITS-Read file in AAO de facto ’Disk FITS’ format
 D.198 RDIPSO-Read file in DIPSO/IUEDR/SPECTRUM format
 D.199 REMBAD-Removes pixels that have been flagged as bad from data
 D.200 RENOBJ-Change the name or location of an object within an HDS file
 D.201 RESAMP-Re-sample and average several spectra (was Specdre RESAMPLE).
 D.202 RESAMPLE-Rebin an image to different dimensions and/or orientation
 D.203 RESCALE-Rescale using user-defined upper and lower limits
 D.204 RETYPE-Changes the type of the main data array in a file
 D.205 ROTX-Rotate data along the X-axis
 D.206 SCLEAN-Interactive patching of images, especially SCUBA data.
 D.207 SCNSKY-Calculates a sky spectrum for a scanned CCD image
 D.208 SCROSS-Cross-correlate two spectra and get relative shift
 D.209 SCRUNCH-Rebin a spectrum to a linear wavelength range
 D.210 SDIST-Analyse an image containing spectra for S-distortion
 D.211 SETOBJ-Assign value to an HDS primitive
 D.212 SFIT-Fit a polynomial to a spectrum
 D.213 SKYLINER-Removes a sky spectrum normalised the 5577 [OI] line.
 D.214 SLICE-Takes a slice with arbitrary end points through an image
 D.215 SOFT-Sets the device/type for terminal graphics
 D.216 SPECCONT-Contour a two-dimensional cut.
 D.217 SPECGRID-Plot spectra on position grid.
 D.218 SPECPLOT-Plot a spectrum.
 D.219 SPFLUX-Applies a flux calibration spectrum to an observed spectrum
 D.220 SPIED-Interactive spiketrum editor
 D.221 SPIFIT-Fits a global polynomial to a spiketrum to form a spectrum
 D.222 SPLOT-Plots a spectrum
 D.223 SQRTERR-Generates an error array as Error = Square Root of (Data/Const)
 D.224 SUBSET-Take a subset of a data set.
 D.225 TABLE-List contents of a SPICA memory file
 D.226 TIPPEX-Modify individual pixel values with cursor
 D.227 TRIMFILE-Creates a copy of an HDS file without unused space
 D.228 VACHEL-Air to vacuum, and/or recession velocity wavelength conversion
 D.229 VIG-Corrects a 2D array for vignetting
 D.230 WDFITS-Writes an image out in the AAO de facto ’Disk FITS’ format
 D.231 WDIPSO-Writes a file in DIPSO/IUEDR/SPECTRUM format
 D.232 XCADD-Adds a constant to the X data in a file
 D.233 XCDIV-Divides the X data in a file by a constant
 D.234 XCMULT-Multiplies the X data in a file by a constant
 D.235 XCOPI-Like XCOPY but interpolates X-data from 2 files
 D.236 XCOPY-Copy X-info (e.g. wavelengths) into a spectrum
 D.237 XCSUB-Subtracts a constant from the X data in a file
 D.238 XCUR-Uses cursor to delimit part of a spectrum
 D.239 XTPLANE-Adds XT planes of a data cube to form an image
 D.240 XTRACT-Average an N-dimensional cube into an (N-M)-dimensional one.
 D.241 XYPLANE-Adds XY planes of a data cube to form an image
 D.242 YCADD-Adds a constant to the Y data in a file
 D.243 YCDIV-Divides the Y data in a file by a constant
 D.244 YCMULT-Multiplies the Y data in a file by a constant
 D.245 YCSUB-Subtracts a constant from the Y data in a file
 D.246 YSTRACT-Adds contiguous columns of an image to form a spectrum
 D.247 YTPLANE-Adds contiguous YT planes of a data cube to form an image

D.1 ABCONV-Convert spectrum from Janskys into AB magnitudes

Description:
ABCONV generates a spectrum in AB magnitudes, given a spectrum in some other units. At present, only Janskys, milli-Janskys and micro-Janskys can be handled.
Parameters:
SPECTRUM
The name of a spectrum whose units are (currently) either Janskys, milli-Janskys, or micro-Janskys.
OUTPUT
The resulting spectrum, whose units will be AB magnitudes. OUTPUT can be the same as SPECTRUM, in which case the conversion will be performed in situ.
Source comments:
   A B C O N V  /  F L C O N V  /  I R C O N V
  
   Converts a spectrum into AB magnitudes (ABCONV) or f-lambda
   units (erg/s/cm**2/Angstrom) (FLCONV), or W/m**2/um (IRCONV).
   The original units of the data may be Jy (Janskys), mJy
   (milli-Janskys), or uJy (micro-Janskys). Other possibilities
   may be added later.
  
   Command parameters -
  
   SPECTRUM The name of the structure containing the spectrum.
            currently used for the spectrum.  For FLCONV
            an x-axis data structure giving the wavelengths of the
            data elements is also required.
  
   OUTPUT   The name of the result of the operation.  This can
            be the same as for SPECTRUM. If not, a new structure
            is created, with everything but the data a direct
            copy of the input.
  
   Command keywords  - None
  
   User variables used - None
                                    KS / CIT 18th May 1984

D.2 ABLINE-Interactive absorption line analysis

Description:
ABLINE is an interactive Figaro program whose main purpose is to find wavelengths and equivalent widths of absorption lines. It includes the ability to fit a polynomial to selected regions of the continuum. As well as wavelengths and equivalent widths, the program also estimates width and asymmetry parameters for each line analysed. For a full description, see the TECHNIQUES ABLINE section of the Figaro documentation.
Parameters:
SPECTRUM
SPECTRUM is the name of the Figaro file containing the spectrum to be analysed. It should have a linear X array, since this is assumed in the calculations, and it is intended that the units be Angstroms, although other units will work (with some interpretation of the results being needed).
OLDCONT
ABLINE allows you to fit local polynomials to parts of the spectrum which, together with its discrepant point rejection algorithm, usually allows a satisfactory continuum to be determined. Such a continuum may be written out by ABLINE and then re-read subsequently. Alternatively, the ability to read a pre-computed continuum may be used to read a continuum fitted in some different way, using other more appropriate techniques. If such a continuum is to be read, OLDCONT should be set.
CONTIN
If OLDCONT was set, ABLINE will read in a continuum from the file specified by CONTIN. This should be a normal Figaro one-dimensional spectrum, with the same number of channels as the spectrum to be analysed. ABLINE assumes that the continuum channels map directly onto those of the spectrum.
SIG
The continuum fitting in the specified regions is an iterative process. A curve is fitted and points that are more than SIG times the standard deviation will be rejected and ignored in the next iteration. 2.25 seems to work quite well.
ITN
ITN is the number of iterations used in determining the continuum. Usually, 4 seems to be adequate.
DEG
DEG is the degree of polynomial to be used when the continuum is fitted. It should be as low as possible while still able to follow the believable trend of the continuum in the area in question. Normal values would be in the range 1 to 3.
LIMIT
It is usual to operate with LIMIT set. In this case, when you delimit a line using the cursor, ABLINE will cutoff its integrations for the equivalent width and wavelength calculation at the channels indicated. If LIMIT is not set, ABLINE will calculate its own limits, taking the channels at which the spectrum first exceeds the continuum (having started from the middle of the indicated range). At present, the algorithm used only works for absorption lines, so LIMIT must be set if emission lines are being analysed.
WIDTH
WIDTH is used to control how much of the spectrum is displayed at one time by ABLINE. Sometimes it helps to use a large width to get a continuum fit and then a small width to home in on a line with the cursor. ABLINE has inbuilt limits to to number of channels it can display at once, and you may find that you exceed these if you make WIDTH too high (in which case you have to select a smaller WIDTH).
NEWCONT
If NEWCONT is set, the continuum produced by ABLINE will be written out as a spectrum. This spectrum can then be used for subsequent ABLINE runs, or for some other purpose altogether.
CONTOUT
If NEWCONT is set, ABLINE writes the continuum out to the file specified by CONTOUT. If this is the same as the input continuum file, the input continuum is over-written. If it is different, a new spectrum is generated with the same structure as the input spectrum and data from the fitted continuum.
CMD
If you enter a number, it will be taken as the central wavelength for a new region to be displayed. The other commands that are accepted are:

SIG x Set ’multiple of sigma’ continuum rejection parameter to x. DEG n Set polynomial degree for continuum fit to n (1..7). ITN n Set ’number of iterations’ continuum rejection parameter to n. LIMIT Line will be delimited by the cursor positions indicated. NOLIM Line delimited by points where data becomes < continuum. WIDTH x Set wavelength range displayed to x. CONT Determine continuum, starting with subsegment selection by cursor. RECONT Repeat continuum fit, using same segments as last time. FIT Analyse a line, delimiting it using the cursor. HELP (or ?) Output this information. QUIT Exit ABLINE.

Commands may be abbreviated. Omitted numeric parameters are prompted for.

Generally, the sequence is: 1) Select center wavelength, 2) CONTinuum, 3) FIT one or more lines. To change degree of continuum fit, use DEG followed by RECONT. Similarly for other continuum parameters.

More details should be available from the printed documentation.

LINENAME
The name of a line to be fitted.
HARDCOPY
Yes if hardcopy of soft plot to be made.
COMMENT
A comment for a hardcopy
Source comments:
A B L I N E

This routine does interactive analysis of absorption lines in spectra.

The user designates a segment of the input spectrum to be analysed in each pass. First a continuum is fitted to this region, using only wavelength subsegments selected graphically by the user (i.e. ignoring the absorption line in question and any other nearby lines or spikes). In addition to this selection, iterative rejection of discrepant points is performed. The functional form of the continuum is a polynomial of degree specified by the user (0 - 7). Alternatively, if a precomputed continuum spectrum is available, it can be used instead.

The user specifies the wavelength limits of the interval containing the line itself: the median wavelength and equivalent width of the absorption line are calculated.

The routine finishes up each segment with a hard copy plot showing the data, continuum and wavelength limits of the line, with a printout of results.

Command line parameters -

SPECTRUM Name of the file containing the spectrum with lines to be fitted CONTIN File containing precomputed continuum, if one is to be used. SIG Multiple of sigma for continuum point rejection ITN Number of iterations for continuum point rejection DEG Degree of polynomial for continuum fit WIDTH Wavelength range to display at one time CONTOUT Output continuum file name, if one is written. If CONTOUT is the same as CONTIN, the new continuum overwrites the old. Otherwise, a new file, the same as SPECTRUM except for the data, is created. CMD The command in the main menu. LINENAME The name of a line to be fitted. COMMENT A comment for a hardcopy

Command keywords -

OLDCONT Set if a precomputed continuum is to be used. LIMIT LIMIT is set if the limits of a line are to be taken as the limits indicated with the cursor. Otherwise, the program will look for the points within the indicated limits where the data drops below the continuum. NEWCONT Set if the continuum constructed during the run is to be written to a file. HARDCOPY Yes if hardcopy of soft plot to be made.

User variables - (">" input, "<" output)

(>) SOFT (Character) Device/type for soft plots (>) HARD (Character) " " " hard " (<) TVXST (Numeric) ) (<) TVXEN (Numeric) ) Used to set the soft plot (<) TVHIGH (Numeric) ) parameters so that (<) TVLOW (Numeric) ) routines such as CCUR (<) XSTART (Numeric) ) know what the display (<) XEND (Numeric) ) limits for the currently (<) HIGH (Numeric) ) displayed plot have (<) LOW (Numeric) ) been set to. (<) TVFILE (Character)) (<) TVCOLOR (Numeric) ) JGR Jan 1985

D.3 ADJOIN-Append two spectra (strictly a merge by wavelength value)

Description:
ADJOIN is a Figaro routine whose primary function is to append one spectrum to another. That is, given two spectra, it produces one output spectrum where the X-axis and data arrays are formed by appending the second spectrum data onto the end of the data from the first.

In detail, ADJOIN is a little more complex, since it produces a spectrum in which the X data increase. This may involve the sorting of the various arrays, so ADJOIN can be regarded as a program that merges two spectra into increasing X order.

If neither spectrum has any X information (i.e. no wavelength array), the sort order will be first and then second. If one or both have X data, the resulting spectrum will be in order of X value.

Parameters:
SPECTRUM
SPECTRUM to be appended to.
SPECTRUM1
SPECTRUM1 specifies the second of the two spectra. Note that it is the structure of the first spectrum that is copied to the output spectrum. Only data arrays will be copied from the second.
OUTPUT
OUTPUT is the name of the resulting spectrum. Note that ADJOIN always produces a new file, even if OUTPUT has the same name as one of the input spectra. OUTPUT will have essentially the same structure as the first spectrum, but any array found in the X-axis or data structure of both input spectra, with the same length as the main data array in both spectra, will appear in OUTPUT as an array whose length is the sum of the two arrays.
Source comments:
   A D J O I N
  
   ADJOIN is a Figaro routine whose primary function is to
   append one spectrum to another.  That is, given two spectra,
   it produces one output spectrum where the .X and .Z arrays
   are formed by appending the second spectrum data onto the end
   of the data from the first.  In detail, ADJOIN is a little
   more complex, since it produces a spectrum in which the
   X data (the contents of the data object .X.DATA) increase.
   This may involve the sorting of the various arrays, so ADJOIN
   can be regarded as a program that merges two spectra into
   increasing X order. The resulting spectrum makes perfect
   sense if the data represent flux density measurements, but
   may be misleading if the data represent total flux measured
   within wavelength bins.  The X array may well not represent
   even a smooth wavelength vs channel relationship, let alone
   scrunched data.  Care should be taken in the use of this routine.
  
   Command parameters -
  
   SPECTRUM    (Character) The first of the two spectra.
   SPECTRUM1   (Character) The second of the two spectra.
   OUTPUT      (Character) The resulting output spectrum.
  
   Command keywords - None
                                              KS  / AAO 18th June 1985

D.4 ALASIN-Read a spectrum in ALAS (Abs. Line Analysis System) format

Description:
ALASIN reads a ’Computed Profile File’ as generated by ALAS (Absorption Line Analysis Software) and writes it to a FIGARO spectrum.
Parameters:
ALASFILE
The name of the input ALAS format file. (This is an ASCII file, with one value of radial velocity (km/s) and the corresponding value of residual intensity on each line.) The file type should be given (default is .DAT)
SPECTRUM
SPECTRUM is the name of the output file. It will have a number of channels equal to the number in the input ALASFILE. The X-axis values are velocities in km/s, as output by ALAS. The data values are the residual intensities as computed by ALAS, i.e. values of intensity normalised by the continuum.
Source comments:
   A L A S I N
  
   ALASIN reads a ’Computed Profile File’ generated by ALAS
   (Absorption Line Analysis Software) and creates an
   equivalent FIGARO spectrum.
      The ALAS ’Computed Profile’ is an ASCII file with each line
   containing a radial velocity and the corresponding residual
   intensity value (i.e. normalised by the continuum).  This is
   converted to a standard Figaro spectrum, except that the X values
   are velocities rather than wavelengths.
  
   Command Parameters
  
   ALASFILE    Name (including type) of the input ALAS format file
   SPECTRUM    The output FIGARO format spectrum
  
                               J.G. Robertson  September 1985

D.5 ALASOUT-Output a spectrum in ALAS (Abs. Line Analysis System) format

Description:
ALASOUT writes a section of a spectrum to an output file suitable for use as an ’Observed Profile’ by ALAS (Absorption Line Analysis Software).
Parameters:
SPECTRUM
The input spectrum. A section of this spectrum, as specified by XSTART and XEND, will be written to the output file (ALASFILE). Note that ALAS expects the spectrum to have been normalised by the continuum.
XSTART
The X value of the first channel which will be written to the output (ALASFILE).
XEND
The X value of the last channel which will be written to the output (ALASFILE). The total number of channels converted (XEND - XSTART + 1) may not exceed 1500; ALAS (version as per Starlink LUN/41.1) accepts a maximum of 300 channels in one file.
ALASFILE
The name of the output ALAS format file. The file type should not be given: the file type is set internally and is always .ALS. If the type is given it will be ignored.
Source comments:
   A L A S O U T
  
   ALASOUT takes data from a FIGARO spectrum and writes it to a file
   in ACSII format, suitable for input to ALAS (Absorption Line
   Analysis Software) as an ’Observed Profile File’.
   The user can select the X range to be transferred, i.e. to cover
   the desired line without too much extra spectrum.  This is
   important since ALAS has a limit of 300 channels for these input
   files (at least in version as per Starlink LUN/41.1).
   For each selected channel an output line is written to the
   file, giving the X value (F9.3) and the data value (F9.5).
   Note that ALAS expects these data values to have been
   normalised by the continuum.
   The file created will have file type .ALS.
  
   Command parameters
  
   SPECTRUM    The input FIGARO spectrum
   XSTART      First X value to transfer
   XEND        Last X value to transfer
   ALASFILE    File name of ALAS format output file (no file type
               or version should be appended).
  
                              J.G. Robertson   September 1985

D.6 APERTURE-Do simple minded aperture photometry on a series of frames

Description:
The image name is read and that image is plotted on the current plot device. The user is presented with a menu which allows him/her/it to specify object and sky regions, change the colour levels, change the radius of the aperture, show cuts or quit. Integrations are a simple sum of the values of the pixels within the aperture radius.
Parameters:
OUTPUT
The name of the file where the answers will be written.
IMAGE
The name of the file with the frame to be analysed.
OPT
The option parameter. Type H for help.
LOW
The low data value for 2-D plots.
HIGH
The high data value for 2-D plots.
RADIUS
The radius of the circle to be used for the integration.
OK
Say "yes" when you are happy with the apearture.
Source comments:
   A P E R T U R E
  
   Description
   -----------
   Do simple minded aperture photometry on a series of frames
  
   Scope of program
   ----------------
   - Handles 2-D images only.
   - Data array converted to FLOAT.
   - Magic values supported.
   - Error arrays not supported
   - Quality arrays not supported.
   - Batch execution not supported.
  
   Parameters
   ----------
   OUTPUT    Name of output ASCII file for results. The output info goes in
             the following order: (1) Either ’O’ or ’S’ for "object" or
             "sky"; (2) a sequence number; (3) the x,y coords of the
             cursor, (4) the radius of the aperture; (5) the total
             flux in pixels which are with a radial distance less than
             or equal to the aperture radius.  No correction is made for
             partial pixels; (6) the total number of pixels included.
             (character)(prompted for)
  
   IMAGE     Name of individual images in case you’re not using a
             list file. (character)(prompted for)
  
   RADIUS    Radius for integration. (real)(prompted for)
  
   LOW       Data value for lowest level in 2-d plot (real)(prompted for)
  
   HIGH      Data value for highest level in 2-d plot (real)(prompted for)
  
   Keywords
   --------
   OK
  
   Method
   ------
   - The image name is read and that image is plotted on the current
     plot device.
   - The user is presented with a menu which allows him/her/it to specify
     object and sky regions, change the colour levels, change the radius
     of the aperture, show cuts or quit.
   - Integrations are a simple sum of the values of the pixels within the
     aperture radius.
  
   Author/s
   --------
   Jim Lewis RGO (jrl@ast.cam.ac.uk)

D.7 ARC-Interactive manual arc line identification

Description:
ARC is a Figaro program that can be used for interactive identif- ication of arc lines.

Each invocation of ARC produces a file arlines.lis in the working directory. This file must be renamed or deleted before re-invoking ARC.

Parameters:
SPECTRUM
The arc data. If there is an X-axis data component the information it contains will be used during the program. At the end of the program the X-axis data component can be set to contain the wavelengths determined by the fit.
ARCTYPE
The type of arc that was used - e.g. HELIUM, NEON, etc. ARC will look for a file called ARCTYPE.ARC which should hold the line list for the arc. Can be up to three types, separated by commas.
SIGMA
Arc line half width in pixels.
ORDER
Polynomial order for 1st fit.
PREVIOUS
If set, ARC will read in the line list from the previous fit as a starting point.
ARFILE
The name of the list file from which the previous fit is to be read. Only used if PREVIOUS is set. Note that the output is always written to ARLINES.LIS. Default extension is .LIS
XCORR
If the previous arc fit was to a different arc, then there is the possibility that the current arc is similar to the previous one but has been shifted. If this is the case, ARC can attempt to determine the shift by cross-correlation of the current arc and the previous one, and can then redetermine the arc line centers by looking for the listed lines at their shifted positions.
OUTPUT
If the final fit obtained is to be used, it is used to reset the x-axis structure in the arc spectrum, giving a new output file. OUTPUT is the name of output file, which can be the same as SPECTRUM, in which case the x-axis structure of SPECTRUM is replaced.
DISNCHAN
Length of displayed sections.
MOVETOX
New plot centre x value.
CMD
At this stage in ARC you have the following options available -

Fit - Repeat the fit. Disp - Display the deviation of the fit from a linear fit. This shows the trend of the fit, and the errors in each line. Order - Change the order of the fit. Edit - Delete or change the wavelength of one or more of the selected lines, without returning to the cursor selection. Reselect - Return to selection using the cursor. Print - Prints a copy of the fit (what ARLINES.LIS would look like if you were to exit now). Auto - Starting from your current fit and arc line list, ARC looks for additional line in the arc at wavelengths given in the line list and adds any it finds to the identified line tables. Xauto - Deletes all the lines found by ’Auto’. Modify - Allows you some control over the Autofit parameters. Quit - Start to exit ARC. Help - (or ?) Display this information.

The first letter of each command is sufficient.

LINENO
Number of line to be edited.
WAVELEN
Wavelength specification.
CHFACT
The autofit algorithm is parameterised as follows.

It takes each pixel in turn. If that pixel is more than CHFACT times the current sigma value from any line already found, it uses that pixel as the starting point for a line search. If anything resembling a line can be found, it calculates its wavelength and looks in the line tables for a line close to that wavelength.

A line is accepted if the discrepancy between calculated and tabulated wavelength is less than SIGFACT times the current RMS value. This means that the criterion for accepting new lines is based on how their wavelength discrepancies compare with those for the lines that have already been accepted.

SIGFACT is the more important parameter.

SIGFACT
The autofit algorithm is parameterised as follows.

It takes each pixel in turn. If that pixel is more than CHFACT times the current sigma value from any line already found, it uses that pixel as the starting point for a line search. If anything resembling a line can be found, it calculates its wavelength and looks in the line tables for a line close to that wavelength.

A line is accepted if the discrepancy between calculated and tabulated wavelength is less than SIGFACT times the current RMS value. This means that the criterion for accepting new lines is based on how their wavelength discrepancies compare with those for the lines that have already been accepted.

SIGFACT is the more important parameter.

WRITEARC
If set, an output spectrum using the arc fit is written.
HARDARC
If set, the output spectrum is plotted in a hard copy.
HARDISP
If set, the dispersion curve is plotted in a hard copy.
QUITSEL
Used to confirm quitting line selection.
LINEOK
Used to confirm a choice of line for deletion, editing etc.
RESOLVE
Used to decide what to do if a line is used twice.
Source comments:
   A R C
  
   Interactively associates lines in an arc spectrum with
   their wavelengths and performs a fit to these values.
  
   Command parameters -
  
   SPECTRUM   The arc data. If there is an x-axis data
              component the information it contains will be
              used during the program.  At the end of the
              program the x-axis data component can be set to
              contain the wavelengths determined by the fit.
   ARCTYPE    The type of arc that was used - e.g. HELIUM,
              NEON, etc.  ARC will look for a file called
              ARCTYPE.ARC which should hold the line list for
              the arc.  Can be up to three types, separated by
              commas.
   ORDER      The initial order for the polynomial fit.
   SIGMA      The initial value for the line width.
   ARFILE     The name of the list file from which the previous
              fit is to be read.  Only used if PREVIOUS is
              set.  Note that the output is always written
              to ARLINES.LIS.  Default extension is .LIS
   OUTPUT     If the final fit obtained is to be used, it is
              used to reset the x-axis structure in the arc spectrum,
              giving a new output file.  OUTPUT is the name of
              output file, which can be the same as SPECTRUM, in
              which case the x-axis structure of SPECTRUM is replaced.
  
   Command keywords -
  
   PREVIOUS   If set, ARC will read in the line list from
              the previous fit as a starting point.
   XCORR      If set, and arc is not the same as the arc used
              to generate the previous line list, a shift between the
              two will be determined and the line centers reanalyysed.
  
   User variables -
  
   (>) SOFT   (Char) The device/type to be used for graphics
              soft plots.  See the SOFT command for details.
              The device must support a cursor.
   (>) HARD   (Char) The device/type for graphics hard plots.
  
   Input -
  
   As named    May use the lines from a previous run.  If so
   by ARFILE   these are read from the previous run’s output
               file.  See below.
  
   Output -
  
   ARLINES.LIS File containing the lines used in the final fit.
               Format is as follows -
               Number of lines used in fit and file name (I5,23X,A)
               1 blank record, then one header record.
               Then one record for each line, giving channel number,
               wavelength, calculated wavelength and wavelength
               discrepancy line number and auto flag (4F13.4,I7,A4)
               The auto flag is either " (A)" or is a blank string.
               Then one blank record, then a record giving the RMS
               error and the value of SIGMA used (12X,F10.2,19X,F5.2)
               Then one blank record, then one record giving the
               order of fit (i.e. 1 less than number of coefficients)
               (15X,I3), then one blank record, then one or more
               records giving the coefficients (3D23.16)
  
                                         KS / CIT  13th June 1984

D.8 ARC2D-Calibrates distortions in 2D arc line data.

Description:
This program controls both 1D and 2D wavlength calibration and can operate either in BATCH or INTERACTIVE modes. The philosophy behind it is somewhat different to those presented in the existing SPICA/SDRSYS and FIGARO software in many respects. In particular its exclusive use of gausian fitting of arclines, its demand for "intellegent" users, who can decide which lines they want to use initially and then allow them to make objective assesments of which,if any are erroneous. Typical diagnostic information given are plots of residuals from the fit versus line width,flux and position. This is all made possible by the use of the Gaussian fitting. The least squares polynomial fitting allows weights to be included for each line(again derived from the formal Gaussian fits).Thus it is possible to constrain the polynomial in difficult regions eg "the 5100 gap" without distorting the global fit.
Parameters:
IMAGE
IMAGE = FILE (Read) Name of image for input This should be a file containing an arc spectrum.
ARC_OPTS
ARC_OPTS = CHARACTER (Read) Enter arc fit option NEW : set up a new wavelength calibration REPEAT : Itterate on previous calibration CLONE : CLone a previous calibration
YSTART
YSTART = INTEGER (Read) analysis lower limit The data between the limits ystart and yend is extracted and the resultant spectrum is used to locate the lines.
YEND
YEND = INTEGER (Read) analysis upper limit The data between the limits ystart and yend is extracted and the resultant spectrum is used to locate the lines.
YBLOCK
YBLOCK = INTEGER (Read) Enter analysis x-sect width Each window is of this width (except perhaphs the final one).
ITERATION
ITERATION = INTEGER*2 (Read) New value of iteration
ORDER
ORDER = INTEGER (Read) order for polynomial fitting This is for the continuity correction of the data. Idealy the arc should have been pre-processed with ARCSDI, so a low order e.g. 2 should be used.
MAXLINES
MAXLINES = INTEGER (Read) Maximum number of lines to allow room for This must be greater than or equal to the number of lines fitted, so room should be allowed in case any more are to be added later.
CLFILE
CLFILE = FILE (Read) Name of image for cloning from This should be a file containing an arc spectrum.
TOLS
TOLS = CHARACTER (Read) For use in batch only
KEEP_ITT
KEEP_ITT = LOGICAL (Read) keep itteration files’
PRFITS
PRFITS = LOGICAL (Read) Print out details of fitting
Source comments:
    none available
  

D.9 ARCDISP-Fit polynomial dispersion curve.

Usage:

arcdisp in order

Description:
This routine fits a polynomial dispersion curve to a list of identified arc features and transforms the NDF pixel coordinates to spectroscopic values. Optionally you can use a graphical dialogue to improve on the previous feature identification, until you like the appearance of the dispersion curve.
Parameters:
DIALOG
DIALOG = _CHAR (Read) If this is ’Y’, ’T’ or ’G’, then the graphical dialogue is entered before the polynomial dispersion curve for any row is accepted and applied. If this is ’N’ or ’F’ then the dialogue is not entered and separate dispersion curves are applied to all rows. The string is case-insensitive. [’G’]
IN
IN = NDF (Read) The spectrum or set of spectra in which emission features are to be located. This must be a base NDF, the spectroscopic axis must be the first axis. No spectroscopic values or widths must exist in the Specdre Extension. The pixel centres along the first axis must be NDF pixel coordinates. Update access is necessary, the results structure in the Specdre Extension may be modified, an array of spectroscopic values will be created in the Specdre Extensions.
ORDER
ORDER = _INTEGER (Read) The polynomial order of dispersion curves. This cannot be changed during the graphical dialogue. Neither can it differ between rows. [2]
FDB
FDB = NDF (Read) The feature data base. Only the simple list of values FTR_WAVE is used and only in graphics dialogue. It serves to find the identification for an as yet unidentified - but located feature.
DEVICE
DEVICE = GRAPHICS (Read) The graphics device to be used. This is unused if DIALOG is false.
WRANGE
WRANGE( 2 ) = _REAL (Read) In graphical dialogue this parameter is used repeatedly to get a range of laboratory values. This is used for plotting as well as for finding identifications in the feature data base.
Source comments:
     A R C D I S P
  
     The input data must be a base NDF. They can be a single spectrum
     or a set of spectra. Examples for the latter are a long slit
     spectrum, a set of extracted fibre spectra, or a collapsed
     echellogram (a set of extracted orders from an echelle
     spectrograph). It is necessary that the spectroscopic axis be the
     first axis in the data set. It does not matter how many further
     axes there are, the data will be treated as a linear set of rows
     with each row a spectrum.
  
     The actual input is the results structure in the Specdre
     Extension. This must be a set of components of type ’arc
     feature’. Each must have two parameters ’centre’ and ’laboratory
     value’. These must be corresponding locations one expressed in
     NDF pixel coordinates, the other in spectroscopic values
     (wavelength, frequency etc.). The centres must be strictly
     monotonically increasing, their variances must be available.
     Laboratory values may be bad values to signify unidentified
     features.
  
     In the graphical dialogue the results structure may be updated.
     The locations remain unchanged; all located features form a fixed
     list of potentially identified features. Identifications may be
     added, deleted or modified. The user has to work on each row in
     turn (unless Quit is chosen). When the user switches from one row
     to the next, the dispersion curve for the finished row is applied
     and its spectroscopic values in the Specdre Extension are set.
     When the last row is finished, the application exits; the output
     of this routine is (i) an updated list of identifications in the
     results structure of the Specdre Extension and (ii) an array of
     spectroscopic values according to the dispersion curves for each
     row, also in the Specdre Extension. At any point the user can
     quit. In this case the array of spectroscopic values is
     discarded, but the updated identifications are retained. If run
     without dialogue, this routine simply performs the polynomial fit
     of the dispersion curve for each row in turn and works out the
     array of spectroscopic values. The list of identifications is
     input only and remains unchanged. If for any row the fit cannot
     be performed, then the spectroscopic values calculated so far are
     discarded and the routine aborts.
  
     There must not yet be any spectroscopic value information: There
     must be no array of spectroscopic values or widths in the Specdre
     Extension. The pixel centre array for the spectroscopic axis
     (i.e. the first axis) must be NDF pixel coordinates (usually 0.5,
     1.5, ...).
  
     This routine works on each row (spectrum) in turn. It fits a
     polynomial to the existing identifications. In the optional
     graphical dialogue two plots are displayed and updated as
     necessary. The lower panel is a plot of laboratory values
     (wavelength, frequency etc.) versus pixel coordinate shows
  
     -  all possible identifications from the feature data base as
        horizontal lines,
     -  all unidentified located features as vertical lines,
     -  all identified located features as diagonal crosses,
     -  the dispersion curve.
  
     In the upper panel, a linear function is subtracted so that it
     displays the higher-order components of the dispersion curve.
     Crosses indicate the identified located features. Since the scale
     of this upper panel is bigger, it can be used to spot outlying
     feature identifications. In the dialogue you can
        R - Switch to next row, accepting the current fit for this row
        X - X-zoom 2x on cursor
        Y - Y-zoom 2x on cursor
        W - Unzoom to show whole row
        N - Pan by 75% of current plot range
        A - Add ID for location nearest to cursor (from FDB)
        S - Set ID for location nearest to cursor (from cursor y pos.)
        D - Delete ID for feature nearest to cursor
        Q - Quit (preserves updated IDs, discards applied fits for all
            rows)
        ? - Help
  
     Whenever the list of identifications is changed, the dispersion
     curve is fitted again and re-displayed. If there are too few
     identifications for the order chosen, then the dialogue will
     display the maximum order possible. But such an under-order fit
     cannot be accepted, the R option will result in an error.
  
     The Q option will always result in an error report, formally the
     routine aborts. After all, it does not achieve the main goal of
     applying individual dispersion curves to all rows.
  
     On one hand the output of this routine may be an updated list of
     identifications, which could in principle be used in a future run
     of this routine. On the other hand this routine will always
     result in an array of spectroscopic values. The existence of
     these spectroscopic values prevents using this routine again.
     Before using this routine again on the same input NDF you have to
     delete the SPECVALS component in the Specdre Extension.
  
     In order to facilitate repeated use of this routine on the same
     data, it always uses the Specdre Extension to store spectroscopic
     values, even if the data are one-dimensional and the first axis
     centre array would suffice to hold that information. This leaves
     the first axis centre array at NDF pixel coordinates, as
     necessary for re-use of this routine.
  
Notes:
This routine recognises the Specdre Extension v. 0.7.

This routine works in situ and modifies the input file.

D.10 ARCGENDB-Convert list of laboratory values to feature data base.

Usage:

arcgendb in fdb

Description:
This routine converts an arc line list - i.e. an ASCII list of laboratory wavelengths or frequencies of known features in an arc spectrum - into a feature data base. That can be used for automatic identification of features in an observed arc spectrum.
Parameters:
INFO
INFO = _LOGICAL (Read) If true, informational messages will be issued.
IN
IN = FILENAME (Read) The name of the input ASCII list of wavelengths or frequencies. The list must be strictly monotonically increasing.
FDB
FDB = NDF (Read) The name of the output file to hold the feature data base. This is formally an NDF.
Examples:
  arcgendb $FIGARO_PROG_S/thar.arc thar_arc
     This will convert the Th-Ar list from the Figaro release into a
     "feature data base" by the name of "thar_arc.sdf".
References:
Mills, D., 1992, Automatic ARC wavelength calibration, in P.J. Grosbol, R.C.E. de Ruijsscher (eds), 4th ESO/ST-ECF Data Analysis Workshop, Garching, 13 - 14 May 1992, ESO Conference and Workshop Proceedings No. 41, Garching bei Muenchen, 1992
Source comments:
     A R C G E N D B
  
     Since generating the feature data base may take some time, you may
     want to do it once for any line lists you often use, and keep the
     feature data bases. On the other hand, the feature data bases may
     be rather big.
  
     This routine reads a list of laboratory values (wavelengths or
     frequencies). The list must be an unformatted ASCII file. From the
     beginning of each line one value is read. If this fails, the line
     is ignored. Comment lines can be inserted by prefixing them with
     "*", "!" or "#". The value can be followed by any comment, but can
     be preceded only by blanks. The list must be strictly
     monotonically increasing.
  
     The list should to some degree match an expected observation. Its
     spectral extent should be wider than that of an expected
     observation. But it should not contain a significant number of
     features that are usually not detected. This is because the
     automatic identification algorithm uses relative distances between
     neighbouring features. If most neighbours in the list of
     laboratory values are not detected in the actual arc observation,
     then the algorithm may fail to find a solution or may return the
     wrong solution.
  
     The given list is converted to a feature data base according to
     Mills (1992). The data base contains information about the
     distances between neighbours of features. The scope of the feature
     data base is the number of neighbours about which information is
     stored. The feature data base is stored in an extension to a dummy
     NDF. The NDF itself has only the obligatory data array. The data
     array is one-dimensional with 1 pixel. All the actual information
     is in an extension with the name "ECHELLE" and of type
     "ECH_FTRDB". Its HDS components are:
  
     -  FTR_WAVE(NLINES)           <_REAL>
     -  FTR_DB(10,10,NLINES)       <_REAL>
     -  FTR_LEFT(10,10,NLINES)     <_BYTE>
     -  FTR_RIGHT(10,10,NLINES)    <_BYTE>
     -  WAVE_INDEX(10,10,NLINES)   <_UWORD>
     -  QUICK_INDEX(5000)          <\_INTEGER>
     -  QENTRIES(5000)             <_REAL>
  
     NLINES is the number of features listed in the input file. The
     scope (=10) controls about how many neighbours information is
     stored in the data base. The index size is fixed to 5000, which
     seems sufficient for NLINES = 3500. The size of the FDB is
  
        (804 * NLINES + 40000) bytes
  
     plus a small overhead for the HDS structure and the nominal NDF.
     So it is 10 to 100 times bigger than the original ASCII list. The
     point about the FDB is the reduced computing time when
     auto-identifying features in an observed arc spectrum.
  

D.11 ARCIDENT-Auto-identify located features.

Usage:

arcident in out fdb wrange=?

Description:
This routine identifies located features in a set of spectra. Auto-identification is done from scratch (without prior identification of any features) with the algorithm by Mills (1992).
Parameters:
INFO
INFO = _LOGICAL (Read) If false, the routine will issue only error messages and no informational messages. [YES]
ECHELLE
ECHELLE = _LOGICAL (Read) If false, the given WRANGE is used for each row, assuming the rows are similar spectra (long slit or fibre). If true, a collapsed echellogram is assumed. In that case each row is an extracted order with different wavelength/frequency range. This routine will divide the given WRANGE into as many sub-ranges as there are rows (orders) in the given input. [NO]
IN
IN = NDF (Read) The spectrum or set of spectra in which located features are to be identified. This must be a base NDF, the spectroscopic axis must be the first axis. No spectroscopic values or widths must exist in the Specdre Extension. The pixel centres along the first axis must be NDF pixel coordinates. The input NDF must have a results structure in its Specdre Extension, and the results must contain a number of line components with strictly monotonically increasing position (centre).
OUT
OUT = NDF (Read) The output NDF is a copy of the input, except that the results structure holds feature identifications rather than locations (’peak’ parameters will have been replaced with ’laboratory value’ parameters).
FDB
FDB = NDF (Read) The feature data base. The actual data base is a set of primitive arrays in an extension to this NDF called ECHELLE. A feature data base can be generated from a list of wavelengths or frequencies with ARCGENDB.
WRANGE
WRANGE( 2 ) = _REAL (Read) The approximate range of wavelengths or frequencies. The narrower this range the faster is the identification algorithm. But if in doubt give a wider range.
DRANGE
DRANGE( 2 ) = _REAL (Read) The range into which the dispersion in pixels per wavelength or per frequency falls. The narrower this range the faster is the identification algorithm. But if in doubt give a wider range.
STRENGTH
STRENGTH = _REAL (Read) This specifies the maximum ratio between the strength of features that are to be used initially for identification. If the strongest feature has peak 1000, then the weakest feature used initially has peak greater than 1000/STRENGTH. [50.0]
THRESH
THRESH = _REAL (Read) This specifies the maximum difference between the ratios of neighbour distances as observed and as found in the feature data base. The difference is evaluated as ABS(1 - ABS(obs/ref)) <? THRESH. Values much larger than 0.1 are likely to generate a lot of coincidence matches; values less than 0.01 may well miss ’good’ matches in less-than-ideal data. You may need to relax this parameter if your arc spectra are very distorted (non-linear dispersion). [0.03]
MAXLOC
MAXLOC = _INTEGER (Read) This specifies the maximum number of features to be used when generating ratios for initial identification. In general, a good solution can be found using only the strongest 8 to 16 features. The program slowly increases the number of features it uses until an adequate solution if found. However, there may be a large numbers of weak features present which are not in the reference database. This parameter allows the setting of an absolute maximum on the number of features (per row) which are to be considered. If less than MAXLOC features are located in a given row, then the number of identified features is used instead for that row. [30]
MINIDS
MINIDS = _INTEGER (Read) The minimum number of features that must be identified for the algorithm to be successful. If fewer than MINIDS features are located in a given row, then a smaller number is used instead for that row. [9]
NEIGHB
NEIGHB( 2 ) = _INTEGER (Read) NEIGHB(1) specifies the starting number of neighbouring features (on each side) to examine when generating ratios for matching. (These are neighbours in the observed spectra, not in the feature data base.) Increasing this will lead to exponential increases in CPU time, so it should be used with caution when all else fails. The default value is 3. Higher values are tried automatically by the program if no solution can be found. The number of neighbours considered is increased until it reaches the maximum of NEIGHB(2), when the program gives up. [3,6]
Source comments:
     A R C I D E N T
  
     The input data must be a base NDF. They can be a single spectrum
     or a set of spectra. Examples for the latter are a long slit
     spectrum, a set of extracted fibre spectra, or a collapsed
     echellogram (a set of extracted orders from an echelle
     spectrograph). It is necessary that the spectroscopic axis be the
     first axis in the data set. It does not matter how many further
     axes there are, the data will be treated as a linear set of rows
     with each row a spectrum.
  
     The features for which an identification should be attempted must
     have been located. That is, they must be components of type
     ’Gauss’, ’triangle’, ’Gauss feature’ or ’triangle feature’ in the
     results structure of the Specdre Extension. Each of these
     components must have at least a ’centre’ and ’peak’ parameter. The
     centres (feature locations) must be a strictly monotonically
     increasing list. Their variances must be available. The locations
     (centre parameters) must be in terms of NDF pixel coordinates. The
     peaks must be positive. They are used as a measure of the
     importance of a feature.
  
     The coverage in spectroscopic values of all spectra (rows) should
     either be similar (long slit or fibres) or roughly adjacent
     (echellogram). There must not yet be any spectroscopic value
     information: There must be no array of spectroscopic values or
     widths in the Specdre Extension. The pixel centre array for the
     spectroscopic axis (i.e. the first axis) must be NDF pixel
     coordinates (usually 0.5, 1.5, ...). The data must be arranged
     such that spectroscopic values increase left to right. In the case
     of rows with adjacent coverage spectroscopic values must also
     increase with row number. In a collapsed echellogram this usually
     means that for wavelength calibration the order number must
     decrease with increasing row number. If this is not the case then
     it is still possible to work on a collapsed echellogram: You can
     set ECHELLE false and thus use the full WRANGE for each row, but
     you must adjust DRANGE to be a more reasonable guess of the
     dispersion.
  
     Identification is done by comparison with a feature data base
     according to Mills (1992). The feature data base should to some
     degree match the observation. Its spectral extent should be wider
     than that of the observation. But it should not contain a
     significant number of features that are not located. This is
     because the automatic identification algorithm uses relative
     distances between neighbouring features. If most neighbours in the
     list of laboratory values are not detected in the actual arc
     observation, then the algorithm may fail to find a solution or may
     return the wrong solution.
  
     This routine works on each row (spectrum) in turn. It establishes
     information about relative distances between neighbouring located
     features and compares this with a feature data base. This serves
     to identify at least a specified number of features. An
     auto-identification should always be checked in the process of
     fitting a polynomial dispersion curve. All located features are
     retained by this routine, so that further identifications can be
     added or some identifications can be cancelled.
  
     The result of this routine is a list of feature identifications.
     All located features are retained, though some will have not been
     identified. The locations and identifications (pixel coordinates
     and laboratory values) are stored in the results structure of the
     Specdre Extension of the input data. This replaces the
     pre-existing results extension. The locations are strictly
     monotonically increasing, as are in all probability the
     identifications.
  
     The new results structure provides for as many component as the
     old one had components of any recognised type. Each component has
     on output the type ’arc feature’. It has two parameters ’centre’
     and ’laboratory value’. Located but unidentified features will
     have bad values as laboratory values. The variances of laboratory
     values are set to zero.
  
     Mills’ (1992) algorithm performs only an initial line
     identification. It is important to verify the returned values by
     fitting a wavelength or frequency scale (e.g. polynomial or spline
     fit), and to reject any out-liers. The algorithm should be given
     the positions of all conceivable features in the spectra. It does
     not use the fainter ones unless it is unable to identify using
     only the brightest, but you will get more robust behaviour if you
     always provide all possible candidate lines for potential
     identification. The algorithm should not be fed severely blended
     line positions as the chance of incorrect identifications will be
     significantly higher (this is the exception to the rule above).
  
     The speed of the algorithm varies approximately linearly with
     wavelength/frequency range and also with dispersion range so the
     better constraints you provide the faster it will run. The
     algorithm takes your constraints as hard limits and it is usually
     more robust to accept a slightly longer runtime by relaxing the
     ranges a little.
  
     If the algorithm runs and keeps looping increasing its set of
     neighbours, then the most likely causes are as follows:
  
     -  wavelength/frequency scale does not increase with increasing x
        (set the CHKRVS parameter true and try again).
     -  WRANGE or DRANGE are too small (increase them both by
        a factor of 2 and try again).
Notes:
This routine recognises the Specdre Extension v. 0.7.
References:
Mills, D., 1992, Automatic ARC wavelength calibration, in P.J. Grosbol, R.C.E. de Ruijsscher (eds), 4th ESO/ST-ECF Data Analysis Workshop, Garching, 13 - 14 May 1992, ESO Conference and Workshop Proceedings No. 41, Garching bei Muenchen, 1992

D.12 ARCLOCAT-Locate line features in a set of spectra.

Usage:

arclocat in fwhm thresh

Description:
This routine locates narrow features in a set of spectra. Features can be located from scratch automatically. In a different mode, feature locations can be added or deleted in a graphical dialogue. The feature location and peak are determined by a Gauss or triangle line fit.
Parameters:
INFO
INFO = _LOGICAL (Read) If true, messages about the progress of auto-locating features are issued. [YES]
DIALOG
DIALOG = _CHAR (Read) If this is ’Y’, ’T’ or ’G’, then no auto-locating takes place and the graphics dialogue is entered. If this is ’N’ or ’F’ then the dialogue is not entered and auto-locating is done instead. The string is case-insensitive. [’G’]
MODE
MODE = _CHAR (Read) This can be ’Gauss’ or ’triangle’ and chooses the line profile to be fitted. This string is case-insensitive and can be abbreviated to one character. [’Gauss’]
IN
IN = NDF (Read) The spectrum or set of spectra in which emission features are to be located. This must be a base NDF, the spectroscopic axis must be the first axis. No spectroscopic values or widths must exist in the Specdre Extension. The pixel centres along the first axis must be NDF pixel coordinates. Update access is necessary, the results structure in the Specdre Extension will be modified, possibly re-created.
FWHM
FWHM = _REAL (Read) The guessed full width at half maximum of the features to be located. This is used to estimate the maximum number of features that might be located, to locate baseline ranges next to suspected features, and as a guess for the line fit.
THRESH
THRESH = _REAL (Read) The threshold. While scanning a pixel must exceed this threshold to initiate a line fit. The fitted peak also must exceed the threshold in order that the feature location be accepted. This parameter is significant only for automatic location of features.
DEVICE
DEVICE = GRAPHICS (Read) The graphics device to be used. This is unused if DIALOG is false.
ROWNUM
ROWNUM = _INTEGER (Read) In graphics dialogue this parameter is used to switch to a different row (spectrum).
Source comments:
     A R C L O C A T
  
     The input data must be a base NDF. They can be a single spectrum
     or a set of spectra. Examples for the latter are a long slit
     spectrum, a set of extracted fibre spectra, or a collapsed
     echellogram (a set of extracted orders from an echelle
     spectrograph). It is necessary that the spectroscopic axis be the
     first axis in the data set. It does not matter how many further
     axes there are, the data will be treated as a set of rows with
     each row a spectrum.
  
     The coverage in spectroscopic values of all spectra (rows) should
     either be similar (long slit or fibres) or roughly adjacent
     (echellogram). There must not yet be any spectroscopic value
     information: There must be no array of spectroscopic values or
     widths in the Specdre Extension. The pixel centre array for the
     spectroscopic axis (i.e. the first axis) must be NDF pixel
     coordinates (usually 0.5, 1.5, ...). The data must be arranged
     such that spectroscopic values increase left to right. In the case
     of rows with adjacent coverage spectroscopic values must also
     increase with row number. In a collapsed echellogram this usually
     means that for wavelength calibration the order number must
     decrease with increasing row number.
  
     In automatic mode this routine works on each row (spectrum) in
     turn. It scans through the spectrum and looks for pixels that
     exceed the local background level by at least the given threshold
     value. When such a pixel is spotted, a single-component line fit
     is tried no the local profile. The local profile is centred on the
     pixel suspected to be part of an emission feature. It includes 1.5
     times the guessed FWHM on either side and a further 5 baseline
     pixels on either side. A local linear baseline is subtracted prior
     to the line fit. In order for the feature to be entered into the
     list of located features, the fit must succeed, the fitted peak
     must exceed the threshold, and the fitted peak must exceed the
     absolute difference of background levels between the left and
     right.
  
     When run with graphics dialogue this routine works on any choice
     of rows. It uses a pre-existing list of located features to which
     can be added or from which features can be deleted. Graphics
     dialogue can also be used to just check the locations. The graph
     displays the spectrum currently worked on in bin-style. The current
     list of located features is indicated by dashed vertical lines.
     The options in the graphical dialogue are:
        R - Choose different row to work on
        X - X-zoom 2x on cursor
        Y - Y-zoom 2x on cursor
        W - Unzoom to show whole row
        N - Pan left/right by 75% of current x range
        A - Add the feature under cursor to list (subject to line fit)
        S - Add the cursor position as feature to list
        D - Delete the feature nearest cursor from list
        Q - Quit, preserving the updated list of located features
        ? - Help
  
     The difference between the A and S options is that A tries a line
     fit to the local profile around the cursor, while S accepts the
     cursor x position as exact centre and the cursor y position as
     exact peak of a new feature; (the variance of the centre is set
     to 0.25, the variance of the peak to the bad value).
  
     The result of this routine is a list of Gauss or triangle
     features. Their locations in NDF pixel coordinates and their peak
     values are stored in the results structure of the Specdre
     Extension of the input data. If run in automatic mode, this
     routine will replace any previously existing results structure. If
     run with graphics dialogue, this routine will try to work with a
     pre-existing list of located features. But if the pre-existing
     results structure does not conform to the required format, then a
     new results structure is created.
  
     The list of located features (for each row) is always sorted such
     that the locations are strictly monotonically increasing.
  
     The results structure provides for a certain number of components.
     These have component type ’Gauss feature’ or ’triangle feature’.
     Each component has two parameters ’centre’ and ’peak’. The number
     of components is determined when the results structure is created,
     it is derived from the approximate width of features and the
     number of pixels in each spectrum.
  
Examples:
  arclocat in 4. 20. mode=triangle dialog=f
     This will scan through (all rows of) the NDF called "in". It
     looks out for features of 4 pixels full width at half maximum
     and with a peak value of at least 20 above the local
     background. The features are fitted as triangles. The search is
     automatic. Thus a new results structure in the input NDF’s
     Specdre Extension is created with the locations (centres) and
     peaks of located features.
  
  arclocat in 4. mode=Gauss dialog=g rownum=5
     This will use the graphic dialogue. Starting with the fifth row
     the user can use the mouse cursor to choose features that are
     to be deleted from or added to the list of located features.
     This can be used to improve on an automatic run, or when no
     features have been located so far. If you try to add a feature
     to the list, a Gauss fit is tried in the vicinity of the
     cursor-selected position.
  
Notes:
This routine recognises the Specdre Extension v. 0.7.

This routine works in situ and modifies the input file.

D.13 ARCSDI-Corrects for arc line curvature

Description:
Program to allow correction of 2-d spectra for S-distortion using an arc - as a preliminary stage prior to wavelength calibration and scrunching. The lines are located by fitting gaussians to them. These positions are then used to fit a chebyshev polynomial to - one for each line. The intermediate positions are interpolated from these. Once this is done the data are shifted and interpolated in the x-section direction to align them all.
Parameters:
IMAGE
IMAGE = FILE (Read) Name of image for input This should be a file containing an arc spectrum.
ARC_OPTS
ARC_OPTS = CHARACTER (Read) Enter arc fit option NEW : set up a new wavelength calibration REPEAT : Itterate on previous calibration. CLONE : CLone a previous calibration. OLD : Correct using previous results
OUTPUT
OUTPUT = FILE (Write) Name of output file File to contain corrected data.
YSTART
YSTART = INTEGER (Read) analysis lower limit The data between the limits ystart and yend is extracted and the resultant spectrum is used to locate the lines.
YEND
YEND = INTEGER (Read) analysis upper limit The data between the limits ystart and yend is extracted and the resultant spectrum is used to locate the lines.
YBLOCK
YBLOCK = INTEGER (Read) Enter analysis x-sect width Each window is of this width (except perhaphs the final one).
ITERATION
ITERATION = INTEGER*2 (Read) New value of iteration
ORDER
ORDER = INTEGER (Read) order for polynomial fitting This is for the continuity correction of the data. Idealy the arc should have been pre-processed with ARCSDI, so a low order e.g. 2 should be used.
MAXLINES
MAXLINES = INTEGER (Read) Maximum number of lines to allow room for This must be greater than or equal to the number of lines fitted, so room should be allowed in case any more are to be added later.
CLFILE
CLFILE = FILE (Read) Name of image for cloning from This should be a file containing an arc spectrum.
TOLS
TOLS = CHARACTER (Read) For use in batch only
KEEP_ITT
KEEP_ITT = LOGICAL (Read) keep itteration files’
PRFITS
PRFITS = LOGICAL (Read) Print out details of fitting
PLOTCORR
PLOTCORR = LOGICAL (Read) Plot correction?
Source comments:
    none available
  

D.14 ASCIN-Read a 1-D or N-D data set from an ASCII table.

Usage:

ascin in lines colaxes=? coldata=? [start=? step=? end=?] out=?

Description:
This routine reads axis values, pixel widths, data values, and data errors from an ASCII table into an NDF data structure. Most of these items are optional, mandatory are only axis values for each axis and data values. Pixel widths can be read only in the one-dimensional case.
Parameters:
INFO
INFO = _LOGICAL (Read) If false, the routine will issue only error messages and no informational messages. This parameter is of significance only if the output is multi-dimensional. [YES]
TOL
TOL = _REAL (Read) The tolerated fraction of the pixel size by which the table coordinates may deviate from the pixel coordinates. For a line read from the ASCII table, if any one of the axis values deviates by more than TOL times the pixel step, then the information from the table is disregarded. This parameter is of no significance, if the output is one-dimensional, since in that case the axis values found will define the exact (non-linear) grid. [0.2]
BAD
BAD = _REAL (Read) The alternative bad value, i.e. the bad value used in the table. Any data or error value found in the table that is equal to BAD, is replaced by the bad value before insertion into the output. [-999999.]
IN
IN = FILENAME (Read) The file containing the ASCII table.
LINES
LINES( 2 ) = _INTEGER (Read) The line numbers of the first and last lines to be used from the table file. [1,9999]
COLAXES
COLAXES( 7 ) = _INTEGER (Read) The column numbers where the axis values are to be found. All axes must be specified, i.e. at least one. The number of leading non-zero elements defines the number of axes in the output. [1,2]
COLWIDTH
COLWIDTH = _INTEGER (Read) The column numbers where the pixel width values are to be found. This parameter is of significance only if the output is one-dimensional. Enter a 0 if no width information is available. [0]
COLDATA
COLDATA( 2 ) = _INTEGER (Read) The column numbers where the data values (first element) and their associated error values (second element) are to be found. If no error information is available, enter 0 as second element. [3,0]
START
START( 7 ) = _REAL (Read) The coordinates of the first pixel. This parameter is of no significance, if the output is one-dimensional, since in that case the axis values found will define the exact (non-linear) grid.
STEP
STEP( 7 ) = _REAL (Read) The coordinate increments per pixel. This parameter is of no significance, if the output is one-dimensional, since in that case the axis values found will define the exact (non-linear) grid.
END
END( 7 ) = _REAL (Read) The coordinates of the last pixel. This parameter is of no significance, if the output is one-dimensional, since in that case the axis values found will define the exact (non-linear) grid.
OUT
OUT = NDF (Read) The NDF where to store the data.
Source comments:
     A S C I N
  
     The user specifies in which columns the different items are to be
     found. A range of line numbers to be used can be specified.
     Comment lines may be interspersed in this line range, if they are
     marked by an exclamation mark in the first or second character.
     All columns leftward of the rightmost used column must be
     numeric, non-numeric data may follow in further columns.
     Up to 132 characters are read from table lines. Numbers are read
     as \_REAL.
  
     If the result is one-dimensional, the axis values will be taken
     literally to define a grid, which in general may be non-linear and
     non-monotonic. If the result is multi-dimensional, the routine
     will guess from the table a grid that is linear in all directions.
     The parameter system is consulted to confirm or modify the
     suggested grid.
  
     The data value read from a line will be stored into exactly one
     output pixel, if and only if the table coordinates match that
     pixel’s coordinate to within a specified fraction of the pixel
     step. Pixels for which no data are in the table are assigned the
     bad value. Table data equal to a specified "alternative bad value"
     are replaced by the bad value before insertion into the data set.
     Where more than one table line corresponds to the same pixel, the
     pixel is assigned the last value from the table. That is, later
     specifications of the same pixel override previous ones.
  
Examples:
  ascin in [1,9999] colaxes=[1,2] coldata=[3,4]
  
  start=[0,0] end=[2.5,5] step=[0.1,1] out=out
     This will read the data from the ASCII file IN, using line
     numbers 1 to 9999 (or till end of file if there are less lines
     in IN). The 1st axis data are taken from the first column, the
     2nd axis data from the second column. The image data are taken
     from the 3rd column and their errors from the 4th column. The
     routine tries to store the table data into a grid with the 1st
     axis running from 0 to 2.5 in steps of 0.1 (26 pixels) and the
     2nd axis running from 0 to 5 in steps of 1 (6 pixels). If a
     coordinate pair from columns 1&2 matches any pixel centre well
     enough, the data from columns 4&5 are entered into the
     corresponding element of the data and errors array. The data
     file is OUT.
  
  ascin in out [25,39] colaxes=5 coldata=[3,0]
     Here the output is one-dimensional and without errors array
     (thus the zero in COLDATA). Only lines 25 to 39 from IN are
     used. The axis data are from the 5th column and the spectrum
     data from the 3rd column. (Note that columns 1, 2 and 4 must
     contain numeric data.) The axis grid need not be specified. The
     axis values from the table will be taken literally to form a
     grid that is in general non-linear and non-monotonic.
Implementation status:
It is not possible to read axis values from the table in double precision or create a double precision axis array.

D.15 ASCOUT-Write an NDF to an ASCII table.

Usage:

ascout in out

Description:
This routine takes an NDF (section) and writes it to an ASCII table.
Parameters:
WIDTH
WIDTH = _LOGICAL (Read) True if pixel widths are to be written, too. [NO]
BAD
BAD = _REAL (Read) The alternative bad value. Where the data or variance array has bad values, BAD is written to the ASCII table.
IN
IN = NDF (Read) The input NDF.
OUT
OUT = FILENAME (Read) The ASCII output file.
Source comments:
     A S C O U T
  
     The first part of the output file is a header giving
     textual information and a head for the table. These lines start
     with a blank carriage return control character followed by an
     exclamation mark as the first printed character. The table itself
     has to the left all the axis values and optionally the pixel
     widths, and to the right the data value and its error if known.
     The spectroscopic axis is written with higher precision (12
     significant digits instead of 7) if its storage type is \_DOUBLE.
     The total number of table columns can be 8 at most. All pixel
     widths are written if and only if requested, regardless of whether
     there is explicit information in the input file. Each width
     occupies the column to the right of the corresponding centre
     value.
  
Examples:
  ascout in(1.5:2.5) out
     This expects a 1-D data set in IN and will write to the ASCII
     file OUT the information for axis values between 1.5 and 2.5.
     Should IN be more than 1-D, the first hyper-row would be used.
  
  ascout in(1.5:2.5,10:15) out
     This will accept a 2-D data set in IN and write to OUT the
     information for 1st axis coordinate values between 1.5 and 2.5
     and for 2nd axis pixel number between 10 and 15. Note that
     integers in the section specification are interpreted as pixel
     numbers.
Notes:
This routine recognises the Specdre Extension v. 0.7.

This routine is available in the Specdre graphical user interface.

D.16 BBODY-Calculate a black body spectrum.

Usage:

bbody temp in=? xstart=? xstep=? xend=? xlabel=? xunit=? out=?

Description:

This routine calculates for a given (vacuum) wavelength or frequency axis the intensity of a black body at given temperature. The intensity is the energy per unit time, per unit area, per unit solid angle, and per unit frequency (and for all polarisations):

             2 h nu^3          1
     B_nu = ---------- ------------------
                c^2     exp(h nu/kT) - 1

where c is the velocity of light, and h and k are the Planck and Boltzmann constants.

Parameters:
LOGAR
LOGAR = LOGICAL (Read) True if the common logarithm of intensity is to be written rather than the intensity itself. [NO]
TEMP
TEMP = REAL (Read) The black body temperature in Kelvin.
ERRTEMP
ERRTEMP = REAL (Read) The error in the black body temperature in Kelvin.
IN
IN = NDF (Read) The file holding axis data to be used. Enter the null value (!) to read axis data parameters from keyboard.
XSTART
XSTART = REAL (Read) The spectroscopic value (pixel centre) for the first output pixel.
XSTEP
XSTEP = REAL (Read) The spectroscopic step (pixel distance) for the output pixels.
XEND
XEND = REAL (Read) The spectroscopic value (pixel centre) for the last output pixel.
XLABEL
XLABEL = CHARACTER (Read) The label for the spectroscopic axis. Allowed values are "wavelength" and "frequency". [wavelength]
XUNIT
XUNIT = CHARACTER (Read) The unit for the spectroscopic axis. If the label is "wavelength" then the unit can basically be "m" for metre, "um" or "micron" for micrometre, or "Angstrom" for Angstroem. If the label is "frequency" then the unit must be basically "Hz" for Hertz. Any of these units may be preceded by a power of ten, so it could be "10**1*Angstrom" if you want to use nanometre as unit, or "10**-9*m" to the same effect. The power must be an integer. You can achieve a logarithmic axis by specifying something like "log10(10**-3*micron)". In this example the axis values will be the common logarithms of the wavelength in nanometres.
OUT
OUT = NDF (Read) The output file.
Examples:
  bbody 5500 in=in out=out
     This calculates the black-body spectrum for 5500 K. The
     spectrum is written to file OUT. The routine tries to find all
     necessary information for the 1st (and only) axis in OUT from
     the spectroscopic axis of the file IN. Since LOGAR is left at
     its default value of FALSE, the data are intensity in Jy/sr.
  
  bbody 2.7 logar=true in=! xstart=0 xstep=0.05 xend=6
  
  xlabel=wavelength xunit=log(micron) out=out
     This calculates the black-body spectrum for 2.7 K. The spectrum
     is written to OUT. No input file is specified. The axis
     contains the logarithms of wavelengths in micron, which run
     from 0 (1 micron) to 6 (1 metre). Since LOGAR=TRUE, the data
     are the logarithms of intensity in Jy/sr.
  
  bbody 1e6 logar=true in=! xstart=-1 xstep=0.05 xend=2
  
  xlabel=frequency xunit=log10(10**15*Hz) out=out
     This calculates the black-body spectrum for 1 million K. This
     time the axis is logarithms of frequency, the units used are
     10^15 Hz. The frequency range covered is from 10^14 Hz to
     10^17 Hz.
Notes:
This routine recognises the Specdre Extension v. 0.7.
References:
Lang, K.R., 1980, Astrophysical Formulae, Springer, Heidelberg, Berlin, New York, p. 21

D.17 BCLEAN-Automatic removal of bad lines and cosmic rays from CCD data

Description:
BCLEAN runs non-interactive cleaning algorithms on a CCD image to detect and remove bad lines and cosmic rays.
Parameters:
IMAGE
The name of the image to be cleaned of bad rows and cosmic rays. Generally, this will be a CCD image. Note the program assumes the image is oriented so that bad lines are horizontal (i.e., occupy contiguous regions in memory).
CRSIG
The cosmic ray search algorithm looks at every pixel in the image and compares its value with the average value of its four nearest neighbours. To be regarded as a cosmic ray, the pixel must exceed that average value by an amount greater than CRSIG times the square root of the average value. Sensible numbers are probably in the range 2.0 to 10.0, but the best way to tune the operation is to try with a few different values, looking at the unfixed results to see which pixels were considered cosmic rays. This constraint is in addition to those enforced by CRFACT and CRMINV. If you set the SHARPNESS keyword, a test of the sharpness of the cosmic ray is also performed.
CRFACT
To be regarded as a cosmic ray, a pixel value must exceed the average of its neighbours by an amount that exceeds CRFACT times that average value. This constraint is in addition to those enforced by CRSIG and CRMINV.
CRMINV
To be regarded as a cosmic ray, a pixel value must exceed the average of its neighbours by at least CRMINV. This constraint is in addition to those enforced by CRSIG and CRFACT.
CRSHARPNESS
If you set the SHARPNESS keyword, then a sharpness test is performed on each pixel that passes the constraints of CRSIG, CRMINV, and CRFACT. The sharpness test measures the ratio of the height of the "core" of the cosmic ray to the height of the "wings". Stars, even under conditions of excellent seeing, tend to have wings that are a significant fraction of the peak height, whereas cosmic rays tend to have much sharper edges.
BRFACT
The bad row search algorithm looks through an array formed by collapsing the image along the rows, searching for rows that are lower than their neighbours by a value that is greater than BRFACT times the median difference between adjacent elements of the array in the local neighbourhood. Sensible values of BRFACT are quite low, especially if combined with a larg-ish value for BRPASS. BRFACT=1.5, BRPASS=4 are reasonable values, and BRFACT can be taken lower if necessary.
BRPASS
The bad row searcher makes BRPASS passes through the data, each time taking a different set of columns evenly distr- ibuted through the image. A row has to show up as bad in every pass in order to be considered bad.
DEGFIX
Bad data areas are interpolated by fitting local polynomials to the data. DEGFIX is the degree of polynomial to be used. Three seems a reasonable value for most data. DEGFIX is only prompted for if FIX is set.
OUTPUT
The name of the output image to be generated. If OUTPUT is the same IMAGE, the data is modified in situ.
NBROWS
The number of bad rows to be cleaned in the image. Note that a ’row’ is a horizontal (as seen on the Grinnell) line in the image. Note that NBROWS and BROWS are not prompted for unless AUTOROW is not set.
BROWS
An array giving the numbers of the bad rows to be cleaned in the array. Note that NBROWS and BROWS are not prompted for unless AUTOROW is not set.
AUTOROW
If AUTOROW is set, the program will perform a search for bad rows, using the BRFACT and BRPASS parameters. If it is not set, the rows will be prompted for as NBROWS and BROWS. AUTOROW is set by default.
FIX
If FIX is set, the output file has the detected cosmic rays and bad rows corrected by interpolation. If FIX is not set, the data is not corrected, but is written out with the bad areas flagged by being set to a value 1000 less than the previous minimum value in the image. FIX=NO can be used to highlight the areas that will be fixed with the current parameter values. FIX is the default. Note that an image that has been run through BCLEAN with FIX=NO will not subsequently BCLEAN properly, so should usually be output to a scratch file.

WARNING - you should examine the output from BCLEAN carefully to ensure that the parameters that you have chosen are appropriate. FIX=NO and TEXTFILE are useful here.

SHARPNESS
If SHARPNESS is set, the program will perform a test on the sharpness of possible cosmic rays events. This test is in addition to those specified by CRSIG, CRFACT, and CRMINV.
TEXTFILE
If TEXTFILE is set, the program will produce a text file containing the results of the cosmic ray search. This file is very useful when trying to choose appropriate values for CRSIG, CRFACT, CRMINV, and CRSHARPNESS. The file is called BCLEAN.LIS.
DIRECTION
In the zapping of cosmic rays, the pixels are replaced with a value interpolated from the neighboring pixels. This can be done along rows or columns, or one can let the computer decide which one gives smaller residuals (i.e., the best).
See also:
FIGARO: CLEAN, COSREJ, MEDFILT, MEDSKY, TIPPEX.
KAPPA: FFCLEAN, CHPIX, FILLBAD, GLITCH, MEDIAN, MSTATS, ZAPLIN.
Source comments:
   B C L E A N
  
   This is the non-interactive CCD image cleaning program,
   which removes bad rows and cosmic rays from images.  Note
   that it expects the data to be orientated so that bad
   transfer lines in the chip are horizontal - i.e. are rows,
   rather than columns.  The program will detect and blank out
   the bad data, and optionally fix it up.  Running without the
   fixup allows the user to see what parts of the image will be
   affected and provides a chance to modify the cleaning parameters
   accordingly.  For details of the cleaning algorithms used, see
   the comments in the listings of FIG_ABROWS, FIG_ZAPRAYS,
   FIG_VERTICAL, FIG_FIXAREA.  There are four parameters connected
   with cosmic ray detection, two which affect bad line detection,
   and one that controls the interpolation used to fix the data.
  
   WARNING: you are strongly advised to examine the effects of this
            program on your images.
  
   Command line parameters -
  
   IMAGE     (Character) The name of the image to be cleaned.
   CRSIG     (Numeric) Cosmic Ray SIGma value.  The cosmic ray
             searcher tests the value of each pixel against the
             average value of the surrounding pixels.  It must
             exceed the average value by more than CRSIG*(square
             root of average value).
   CRFACT    (Numeric) Cosmic Ray FACTor.  A cosmic ray must also
             exceed the average value by CRFCT*(the average value).
   CRMINV    (Numeric) Cosmic Ray MINimum Value.  A cosmic ray
             must also exceed the average value by CRMINV.
   CRSHARPNESS (Numeric) Cosmic Ray SHARPNESS. If the SHARPNESS
             keyword has been set, then a cosmic ray must also
             satisfy the sharpness criterion: the height of the cosmic
             ray above the immediately surrounding sky must exceed the
             difference between the immediately surrounding sky and the
             sky a bit further away, by more than a ratio of CRSHARPNESS.
             Stars tend to have lower values of this ratio than cosmic
             rays. The default value is 10.
   BRFACT    (Numeric) The bad row searcher looks through an array
             formed by collapsing the image along the rows, looking
             for rows that are lower than their neighbours by a
             value that is greater than BRFACT*(median difference
             between neighbours in the neighbourhood).
   BRPASS    (Numeric) Bad Row PASS value.  The bad row searcher
             makes BRPASS passes through the data, each time taking
             a different set of columns evenly distributed through
             the image.  A bad row must show up in all passes.
   DEGFIX    (Numeric) The degree of polynomials to be used in
             interpolating over bad data.
   OUTPUT    (Character) The name of the output image to be
             generated.  If this is the same as IMAGE, the
             correction will be performed in situ.
   NBROWS    (Numeric) The number of bad rows to be fixed.
   BROWS     (Numeric vector) The numbers of the bad rows to
             be fixed.  If NBROWS and BROWS are specified
             explicitly, then they will be used.  Otherwise
             an automatic bad line search will be preformed,
             unless overidden by the setting of the AUTOROW
             keyword.
   DIRECTION (Numeric) Indicates along which direction on the CCD
             the cosmic rays will be interpolated across. 1 means
             columns, -1 means rows, and 0 means let the computer
             decide which gives smaller residuals.
  
   Command keywords -
  
   AUTOROW   If set, an automatic bad row search will be performed.
             If NBROWS or BROWS are specified explicitly,
             AUTOROW=NO will be assumed.
   FIX       If set, the bad data found will be fixed.
             Otherwise, the output image will simply have the bad
             pixels flagged by a specific flag value.
   SHARPNESS If set, the "sharpness" test for cosmic rays will
             be performed in addition to the other tests.
   TEXTFILE  If set, a text file (BCLEAN.LIS) will be
             produced giving a summary of the cosmic ray test
             results. This file is useful when deciding on the
             cosmic ray selection parameters.
  
                                       KS / CIT 29th June 1984

D.18 BFFT-Takes the reverse FFT of a complex data structure

Usage:
bfft frequency_data spatial_data
Description:
These Figaro functions take the FFT of the data in a file. FFT performs a forward transform, BFFT performs an inverse transform. The input file must contain a complex data structure, i.e. one with IMAGINARY and DATA components.

The data may be multi-dimensional; if it is, a multi-dimensional FFT is performed. Note that the Figaro routine R2CMPLX will turn an existing real data structure into a complex one acceptable to this routine. FFT does not perform any cosine belling or other tapering of the data, nor does it reduce it to a zero mean.

Parameters:
CDATA
CDATA is the name of a complex data structure. Such structures for the spatial domain are most easily produced using the R2CMPLX command. For the frequency domain, such data were usually created by R2CMPLX and transformed by FFT.
OUTPUT
OUTPUT is the name of the resulting Fourier transformed data. If OUTPUT is the same as CDATA then the transform is performed in situ; otherwise, a new file is created.
Notes:
The fourier transform routines available in the various math libraries (NAG, IMSL, etc) all have slightly different characteristics, which show up in the programs that use them. This routine has been written around the NAG library (mainly the routines C06FAF and C06FJF), so many of its characteristics may be deduced by reading the relevant parts of the NAG manuals. In version 5.0 this routine was changed to use the PDA library, effectively FFTPACK routines. The data is re-ordered by FFT after the transform so that the zero frequency component is in the center of the resulting array, and this re-ordering is reversed by BFFT before the transform. This means that after FFT has been run, the various axes all go from -N to +N where N is the Nyquist frequency. New axis data structures that reflect this are created by FFT and will be deleted by BFFT.
See also:
FIGARO: FFT, COSBELL, CMPLX2I, CMPLX2R, CMPLX2M, I2CMPLX, R2CMPLX.
KAPPA: CONVOLVE, LUCY, MEM2D, WIENER.
Authors:
ks: Keith Shortridge (AAO)

jm: Jo Murray (RAL, Starlink)

jms: ??? (AAO)

hme: Horst Meyerdierks (UoE, Starlink)

D.19 BSMULT-Atmospheric band removal using a B star calibration spectrum

Description:
BSMULT applies the calibration spectrum derived from a B-star (for atmospheric bands) to the spectrum of an object.
Parameters:
SPECTRUM
The spectrum specified by SPECTRUM will be multiplied by the B star calibration spectrum (specified by BSTAR). BSMULT differs from a simple multiplication (e.g. IMULT) in taking account of the differences in air mass of the calib- ration object and the object being calibrated. So both should have valid values for .OBS.SECZ (the program will complain if they don’t). Note that the calibration is by multiplication, and so is not suitable for data in logarithmic flux units such as magnitudes.
BSTAR
BSTAR specifies the B-star calibration spectrum, obtained by dividing a B star (or other suitable calibration spetrum) by its continuum. Any regions where no correction is desired should be set to 1.0.
OUTPUT
OUTPUT specifies the name of the calibrated spectrum to be produced by BSMULT. Note that this can be the same as for SPECTRUM, in which case the operation will be performed in situ.
BETA
The algorithm used by BSMULT is:

OUTPUT=SPECTRUM*(BSTAR**(SSECZ/BSECZ)**BETA))

where SSECZ and BSECZ are the air masses for the spectrum and the B star respectively. BETA should be 0.5 for saturated lines, 1.0 for unsaturated lines, and the generally accepted best compromise value for all lines (determined by P.J. Young) is 0.55.

Source comments:
   B S M U L T
  
   Multiplies a spectrum by a B star calibration spectrum - which
   should be 1.0 except in regions where there are atmospheric
   bands.  This routine differs from an ordinary multiplication (e.g.
   as in IMULT) since it includes a term for the correction due
   to the different air masses of the two objects.  This means
   that both the original spectrum and the B star spectrum must
   have valid .OBS.SECZ values.  If the spectrum to be multiplied
   is 2 dimensional, the same operation is repeated for each of
   the spectra it contains.
  
   Command parameters -
  
   SPECTRUM    (Character) The spectrum to be corrected.
   BSTAR       (Character) The B star calibration spectrum.
   BETA        (Numeric) Power to which relative air mass is
               to be raised - see FIG_BSMULT.
   OUTPUT      (Character) The resulting spectrum.
  
   Command keywords - None
  
   User variables used - None
  
                                       KS / CIT 3rd July 1984

D.20 CADD-Add back fitted continuum

Description:
A polynomial previously fitted to the continuum is evaluated and this is added.
Parameters:
IMAGE
IMAGE = FILE (Read) Name of image for input
OUTPUT
OUTPUT = FILE (Write) OUTput Name of output file OUTPUT is the name of the resulting spectrum. If OUTPUT is the same as INPUT the data in the input file will be modified in situ.Otherwise a new file will be created.
Source comments:
    none available
  

D.21 CALDIV-Generate calibration spectrum from continuum standard spectra

Description:
Given a standard spectrum giving the continuum flux densities for each element for a particular standard star (probably generated by GSPIKE followed by INTERP) and the continuum of an observed spectrum of the same object, CALDIV calculates the instrumental response for each element. Note - this routine is intended for standards where the tables give the calculated continuum values at various points (e.g. Filippenko/ Greenstein standards), rather than the average measured flux density over a given wavelength range centered on each point. CALDIV will not accept a standard spectrum that has data in magnitude units.
Parameters:
STANDARD
A spectrum giving the actual continuum flux density at each point for a standard star. This will probably have been generated by GSPIKE followed BY INTERP. The data shoule not be in magnitude units.
SPECTRUM
An observed spectrum of the object whose tabulated fluxes were used to generate STANDARD. Note that CALDIV does not insist on the spectrum’s having been scrunched, but things are usually easier if it has been. The wavelength range of SPECTRUM must match that of STANDARD exactly.
OUTPUT
A spectrum whose values give the instrumental response in "units per (counts per second per angstrom)", where "units" are the units used by the input standard spectrum.
Source comments:
   C A L D I V
  
   Divides the interpolated continuum spectrum of a standard
   star (e.g. a Filippenko/Greenstein standard, probably created
   by GSPIKE and INTERP) by the observed continuum of the same
   star, in order to generate the instrumental response calibration
   spectrum.
  
   Command parameters -
  
   STANDARD    (Character) The interpolated continuum spectrum of
               the standard star.  Note: This should not be in
               magnitude units, and should probably not contain a
               .TABLE.BANDWIDTH data object, since this would
               indicate that this was generated from published
               data giving average observed flux density over a
               wavelength range (e.g. Oke/Gunn data) rather than a
               fitted continuum.
  
   SPECTRUM    (Character) The observed continuum spectrum of the
               standard star.  Note that both STANDARD and SPECTRUM
               should be on the same wavelength scale (given by
               a .X.DATA array) and ideally this will be a linear
               scale.
  
   OUTPUT      (Character) The resulting calibration spectrum.
  
   Command keywords -  None
  
   User variables used -  None
  
                                      KS / CIT 28th May 1984

D.22 CCDLIN-Applies a linearity correction to AAO CCD data

Description:
CCDLIN applies a linearity correction to AAO CCD data. The correction applied has the form determined by John Barton (RCA#5 Non-Linearity Correction - AAO internal document), and has two parameters: a correction factor (alpha), and a bias whose value is assumed when applying the correction.
Parameters:
IMAGE
The name of the image to be corrected for non-linearity. It should be a raw image obtained with an AAO CCD.
OUTPUT
Specifies the resulting corrected image. If this is the same as IMAGE, the image is corrected in situ. Otherwise, a new image is created.
ALPHA
The value of the correction factor used. The correction is given by

M=C*(1+alpha*C)

where M and C are the measured and corrected intensities (after bias subtraction) respectively. John Barton’s memo gives a value of alpha=3.16E-6, and this is the reset value.

CBIAS
Since the linearity correction is expressed in terms of intensities after bias subtraction, a bias must be assumed during the calculation. The value is not very critical (any error in bias results in a much smaller error in the corrected data), and can safely be assumed to be constant over the image. The reset value is 180.
Source comments:
   C C D L I N
  
   Applies a linearity correction to data from the AAO RCA CCD.
   The correction applied is that given by John Barton (RCA#5
   Non-Linearity Correction, AAO Internal Document).
  
   Command parameters -
  
   IMAGE   (Character) The name of the structure containing the image.
  
   ALPHA   (Numeric) The value of the constant alpha in the expression
           giving the linearity correction.
  
   CBIAS   (Numeric) The value of the bias level to be applied when
           making the correction.  This is not a particularly critical
           parameter.
  
   OUTPUT  (Character) The name of the result of the operation.  This
           can be the same as for IMAGE.  If not, a new structure
           is created, with everything but the data a direct
           copy of the input.
                                    KS / AAO 10th Sept 1986

D.23 CCUR-After SPLOT, uses graphics cursor to indicate data values

Description:
If a spectrum has been displayed on the current soft plotting device, CCUR allows the user to move the cursor around the display, indicating the current cursor position and data value each time a terminal key is pressed.
Parameters:
SCREEN
The screen management routines used by CCUR do not know how to handle all the various types of VDU. If you find that you are having problems getting output from CCUR, try setting SCREEN=NO - this bypasses the fancy screen formatting and puts out the data crudely but directly to the terminal as though it were not a VDU.
Source comments:
   C C U R
  
   Uses the cursor to get information about data as displayed on
   the soft graphics device.
  
   Command variables - None.
  
   Command keywords - None.
  
   User variables -     (">" input, "<" output)
  
   (>) SOFT     (Character) Device / type for soft plots.
                See documentation on ’SOFT’ command for
                details.
   (>) TVXST    (Numeric) X-start value for current plot.
   (>) TVXEN    (Numeric) X-end value for current plot.
   (>) TVLOW    (Numeric) Lowest value of current plot.
   (>) TVHIGH   (Numeric) Highest value of current plot.
   (>) TVFILE   (Character) Name of currently displayed data.
  
                                KS / CIT 23rd July 1984

D.24 CDIST-S-distortion correction using SDIST results

Description:
Applies the distortion correction determined by SDIST to an image.
Parameters:
IMAGE
The name of the S-distorted image that is to be corrected.
YSTART
If the image contains, for example, a single spectrum in the center and a lot of unused background at the edges, it can save processing time if only a part of the Y-range of the data is corrected. YSTART is the first Y value in the range corrected by CDIST.
YEND
Specifies the last Y value in the range corrected by CDIST.
OUTPUT
Specifies the name of the resulting, corrected, image. If OUTPUT is different to IMAGE, a new image will be created. If it is the same, the correction will be performed in situ.
MAXDEGY
If a number of spectra have been used to determine the image distortion, CDIST interpolates between their fitted positions by fitting a low order polynomial to them. MAXDEGY specifies the order of this polynomial.
ROTATE
The processing performed by CDIST normally involves accessing the image in a way that causes excessive paging on the VAX. This paging may be considerably reduced by rotating the image (in a relatively efficient way) before and after the correction. Of course, this introduces the overhead of the two rotations. Generally, large images should be rotated, small images should not. The results should be identical in both cases.
Source comments:
   C D I S T
  
   Performs an S-distortion correction for an image, using the
   distortion analysis provided by SDIST.  If the SDIST analysis
   was for a single spectrum, the the correction is ’1-dimensional’
   in that it consists simply of applying a shift in Y to the
   data for each column of the image.  The shift is determined
   separately for each column from the polynomial fitted by SDIST.
   If the SDIST analysis was for more than one spectrum, the
   correction is what might be termed ’1.5-dimensional’ - the
   data is only redistributed within columns, but the amount of
   shift varies along each column in a manner determined by fitting
   a low order polynomial to the results of evaluating the polynomials
   that SDIST fitted to each spectrum.  The 1.5D algorithm actually
   reduces to the 1-D case when there is only one spectrum, but it
   simplifies things to think of them as distinct cases.
  
   Command parameters -
  
   IMAGE    (Character) The name of the image to be corrected.
  
   YSTART   (Numeric) The first Y value to be used.
  
   YEND     (Numeric) The last Y value to be used.  Using YSTART
            and YEND to limit the range of data corrected will
            speed up the operation.
  
   OUTPUT   (Character) The name of the resulting image.  This
            can be the same as IMAGE, in which case the correction
            will be performed in situ.
  
   MAXDEGY  (Numeric) The maximum degree polynomial to fit to the
            spectral positions in the case where there is more
            than one spectrum covered by the SDIST analysis.
  
   Command keywords -
  
   ROTATE   If set, the image to be corrected will be rotated
            prior to the application of the correction.  This
            minimises the number of page faults during the correction,
            but at the expense of the overheads of the rotation itself.
  
   User variables - None
  
   Input files -
  
   SDIST.DAT contains the results of the fit(s), as written by
             SDIST, in a format treated as follows -
  
             3 header lines, all beginning with ’*’
             One line giving the number of spectra traced, in the
             format 20X,I5.
             Then, for each spectrum traced, one record giving
             the spectrum number, and the leftmost and rightmost
             pixels covered by the trace, in format
             11X,I5,17X,I5,4X,I5, then 1 record giving the average
             Y value in the spectrum, in format 16X,F13.7,
             which is followed by 3 records giving the 11
             polynomial coefficients for the fit, in 3D23.16.
             Coefficients are given constant first, with any unused
             coefficients set to zero.
  
                                            KS / CIT 6th Feb 1984

D.25 CENTERS-Generate file of object centroids from ICUR, IGCUR or IMPOS output

Description:
Figaro function that takes a list of approximate X,Y positions of objects in a two-dimensional direct image and calculates centroids (that is, accurate positions) for these objects.

The approximate positions input are obtained from environment variables. These variables should be set up prior to running CENTERS, usually by using Figaro functions IGCUR or ICUR. Alternatively, you may enter the positions into a text file and use IMPOS to read this file and copy the values into the environment variables required by CENTERS.

The computed centroids are output to a new file called center.dat.

Parameters:
IMAGE
The name of the image containing the objects. This need not be the image used to generate the original list of points - it may be a similar image in a different waveband, with offsets in X and Y with respect to the original image.
APERTURE
The aperture used for the centroiding. The aperture actually used is a box APERTURE*2+1 pixels square, which is a rough approximation to a circle of radius APERTURE.
XOFF
The offset in X, in pixels.
YOFF
The offset in Y, in pixels.
PROFBOX
Size of profile box.
PROFMIN
Minimum displayed value.
PROFMAX
Maximum displayed value.
PFILE
If set, a formatted file giving the summed radial profiles will be produced.
DISPROF
If set, the profile is displayed.
CHGPROF
If set, the profile display can be changed.
Source comments:
   C E N T E R S
  
   Figaro function that takes a list of approximate X,Y positions
   of objects in a two-dimensional direct image and calculates
   centroids (that is, accurate positions) for these objects.
  
   The approximate positions input are obtained from environment
   variables.  These variables should be set up prior to running
   CENTERS, usually by using Figaro functions IGCUR or ICUR.
   Alternatively, you may enter the positions into a text file and use
   IMPOS to read this file and copy the values into the environment
   variables required by CENTERS.
  
   The computed centroids are output to a new file called center.dat.
  
   Command parameters -
  
   IMAGE    (Character) The name of the image containing the
            objects.  This need not be the image used to
            generate the original list of points - it may be
            a similar image in a different waveband, with
            offsets in X and Y with respect to the original image.
   APERTURE (Integer) The aperture used for the centroiding.
            The aperture actually used is a box APERTURE*2+1
            pixels square, which is a rough approximation to a
            circle of radius APERTURE.
   XOFF     (Real) The offset in X, in pixels.
   YOFF     (Real) The offset in Y, in pixels.
   PROFBOX  (Real) Size of profile box.
   PROFMIN  (Real) Minimum displayed value.
   PROFMAX  (Real) Maximum displayed value.
  
   Command keywords -
  
   PFILE    If specified, a formatted file giving the summed
            radial profiles will be produced.
   DISPROF  If specified, the profile is displayed.
   CHGPROF  If specified, the profile display can be changed.
  
   User variables - (">" input
  
   (>) SOFT    (Character) The current device/type for soft plots.
   (>) NPIXELS (Real) Number of objects for which positions are
                specified.
   (>) XPIXELS (Real array) List of approximate X positions of the
               objects for which the centroids are to be computed
               (pixels).
   (>) YPIXELS (Real array) List of approximate Y positions of the
               objects for which the centroids are to be computed
               (pixels).
  
   Output -
  
   center.dat contains one record for each point, giving
              XCENT,YCENT,IX,IY,DX,DY,AP
              in the format 2F8.2,2I5,2F8.2,I4 where
              XCENT,YCENT give the position of the centroid
              IX,IY are the original pixel position of the point.
              DX,DY are the offsets in X and Y, and
              AP is the value used for APERTURE.
              If the centroid for a point cannot be determined, a
              record is written giving
              ’*** No centroid ’,IX,IY,DX,DY,AP
              in the format A,2I5,2F8.2,I4.
  
                                       KS / CIT 29th Sept 1983

D.26 CFIT-Generate a spectrum using the cursor

Description:
Figaro function to generate a spectrum by interpolation between points selected interactively using a display device cursor. CFIT assumes that a spectrum has already been displayed by SPLOT, and will generate a new data structure based on the spectrum displayed, with only the data changed.
Parameters:
OUTPUT
The name of the output file to be created. If this is the same as the displayed spectrum, the data in the displayed spectrum will be modified.
CHANGE
Set to mofify points.
REDRAW
Set to redraw the original spectrum.
Source comments:
   C F I T
  
   Figaro function to generate a spectrum by interpolation
   between points selected interactively using a display
   device cursor.  CFIT assumes that a spectrum has already
   been displayed by SPLOT, and will generate a new data
   structure based on the spectrum displayed, with only the
   data changed.
  
   Command parameters -
  
   OUTPUT      (Character) The name of the output file to
               be created.  If this is the same as the displayed
               spectrum, the data in the displayed spectrum will
               be modified.
  
   Command keywords -
  
   CHANGE      Set to mofify points.
   REDRAW      Set to redraw the original spectrum.
  
   User variables used -  (">" input, "<" output)
  
   (>) TVFILE  The name of the displayed spectrum
   (>) TVXST   The first displayed x-value
   (>) TVXEN   The last displayed x-value
   (>) TVHIGH  The maximum displayed y-value
   (>) TVLOW   The minimum displayed y-value
   (>) TVCOLOR The GRPLOT code for the plot colour
   (>) SOFT    The device/type string defining the display device
  
                                            KS / CIT 17th May 1983

D.27 CHANGED-Indicate fits invalidated due to "cleaning" of an image

Description:
To indicate which fits have changed due to "cleaning" of image duing fitting (this is due to bits missed previously). This is set at data being different by more than 1, or 1% of the mean value whichever is larger. This situation can arise with data badly affected with cosmic rays where some are initially missed.
Parameters:
IMAGE
IMAGE = FILE (Read) Name of image for input
IMAGE2
IMAGE2 = FILE (Read) Name of image for input
Source comments:
    none available
  

D.28 CLEAN-Interactive patching of bad lines, bad pixels in an image

Description:
CLEAN is an interactive routine for fixing bad pixels and rows in CCD data. CLEAN can be used either as a prelude to BCLEAN, in order to see what parameters may be suitable or else it may be used after BCLEAN, to patch up any rows or pixels that BCLEAN missed.
Parameters:
IMAGE
IMAGE is the image - usually a CCD image - that is to be interactively cleaned of bad rows and bad pixels. Note that the orientation of the image data should be such that bad rows are horizontal (as seen on the Grinnell).
OUTPUT
OUTPUT is the name of the image that results from the cleaning process. If OUTPUT is the same as IMAGE (the default value) the correction will be performed in situ.
QUIT
Used to confirm quitting the application.
DEG
Degree of fit to use for interpolation.
XSIZE
Size of deletion box in X.
YSIZE
Size of deletion box in Y.
HIGH
Highest displayed data value.
LOW
Lowest displayed data value.
See also:
FIGARO: BCLEAN, COSREJ, MEDFILT, MEDSKY, SCLEAN, TIPPEX.
KAPPA: FFCLEAN, CHPIX, FILLBAD, GLITCH, MEDIAN, MSTATS, ZAPLIN.
Source comments:
   C L E A N
  
   Main routine for the Figaro ’CLEAN’ command.  Displays
   a CCD image and then allows the user to move around it with
   the cursor, selecting rows and columns to be corrected and
   cosmic rays to be zapped.  The idea is that this routine can
   be used to fix up any areas in an image that were not fixed
   automatically by the non-interactive version (’BCLEAN’).  It
   may also give a better idea of the best settings for the
   BCLEAN parameters.
  
   Command parameters -
  
   IMAGE      (Character) The name of the image to be displayed.
   OUTPUT     (Character) The name of the resulting cleaned image.
              If the same as IMAGE, the image is cleaned in situ.
   QUIT       (Logical) Used to confirm quitting the application.
   DEG        (Integer) Degree of fit to use for interpolation.
   XSIZE      (Integer) Size of deletion box in X.
   YSIZE      (Integer) Size of deletion box in Y.
   HIGH       (Real) Highest displayed data value.
   LOW        (Real) Lowest displayed data value.
  
   User variables -  ("<" output, "!" modified)
  
   (!) IMARRAY (Numeric array) Contains current image display
               parameters.
   (<) IMFILE  (Character) Contains name of currently displayed
               image file.
   (>) IDEV    (Character) Contains name of display device.
  
                                      KS / CIT 2nd July 1984

D.29 CLIP-Clip data above and below a pair of threshold values

Description:
Clips an image, replacing any elements above a high threshold or below a low threshold with that threshold value.
Parameters:
IMAGE
The datafile to be threshold clipped.
LOWCLIP
Any elements in the image that are less than LOWCLIP are set to LOWCLIP.
HIGHCLIP
Any elements in the image that are greater than HIGHCLIP are set to HIGHCLIP.
OUTPUT
The name of the resulting image. If OUTPUT is the same as IMAGE the operation will be performed in situ. Otherwise a new file will be created.
See also:
FIGARO: IDIFF, RESCALE.
KAPPA: THRESH.
Source comments:
   C L I P
  
   Clips an image (or spectrum, cube or whatever..).  Given a low
   and a high threshold value, CLIP sets any elements above the
   high value or below the low value to the appropriate value.
  
   Command parameters -
  
   IMAGE    (Character) The name of the structure containing the image.
   LOWCLIP  (Numeric) The low threshold value
   HIGHCLIP (Numeric) The high threshold value
   OUTPUT   (Character) The name of the result of the operation.  This
            can be the same as for IMAGE.  If not, a new structure
            is created, with everything but the data a direct
            copy of the input.
                                    KS / AAO 22nd July 1985

D.30 CMPLX2I-Extracts the imaginary part of a complex data structure

Description:
CMPLX2I creates a data structure, in which the data is taken from the imaginary part of a complex data structure. The resulting structure is not complex (i.e. has only a single data array, with no ’real’ and ’imaginary’ arrays).
Parameters:
CDATA
The name of an existing complex data structure. The imaginary array from this will become the data array of the resulting structure.
OUTPUT
The name of the data structure to be created. Its data array will come from the structure specified as CDATA, and it will not have any ’real’ or ’imaginary’ arrays. If OUTPUT is the same as CDATA, CDATA will be transformed into a non-complex structure (which means that its real part will be lost); otherwise, a new file is created.
Source comments:
   C M P L X 2 R    /     C M P L X 2 I   /   C M P L X 2 M
  
   Creates a real data structure (i.e. one with just a real data array)
   as opposed to a complex data structure, (in the Figaro sense of a
   structure with both  real and imaginary data arrays)
   from a complex data structure.
   In the case of CMPLX2R it is the real part of the complex data
   that forms the data array in the resulting structure.
   For CMPLX2I, it is the imaginary part, and for CMPLX2M
   it is the modulus of the complex data.
  
   Command parameters -
  
   CDATA    (Character) The name of the input complex structure.
   OUTPUT   (Character) The name of the resulting structure.  This
            may be the same as CDATA. In either case a new file
            is created.
  
   Command keywords - None
                                       KS / AAO  24th Sept 1986.

D.31 CMPLX2M-Extracts the modulus of a complex data structure

Description:
CMPLX2M creates a data structure, in which the data is taken from the modulus of a complex data structure. The resulting structure is not complex (i.e. has only a single data array, with no ’real’ and ’imaginary’ arrays).
Parameters:
CDATA
The name of an existing complex data structure. The modulus array from this will become the data array of the resulting structure.
OUTPUT
The name of the data structure to be created. Its data array will come from the structure specified as CDATA, and it will not have any ’real’ or ’imaginary’ arrays. If OUTPUT is the same as CDATA, CDATA will be transformed into a non-complex structure (which means that its real and imaginary parts will be lost); otherwise, a new file is created.
Source comments:
   C M P L X 2 R    /     C M P L X 2 I   /   C M P L X 2 M
  
   Creates a real data structure (i.e. one with just a real data array)
   as opposed to a complex data structure, (in the Figaro sense of a
   structure with both  real and imaginary data arrays)
   from a complex data structure.
   In the case of CMPLX2R it is the real part of the complex data
   that forms the data array in the resulting structure.
   For CMPLX2I, it is the imaginary part, and for CMPLX2M
   it is the modulus of the complex data.
  
   Command parameters -
  
   CDATA    (Character) The name of the input complex structure.
   OUTPUT   (Character) The name of the resulting structure.  This
            may be the same as CDATA. In either case a new file
            is created.
  
   Command keywords - None
                                       KS / AAO  24th Sept 1986.

D.32 CMPLX2R-Extracts the real part of a complex data structure

Description:
CMPLX2R creates a data structure, in which the data is taken from the real part of a complex data structure. The resulting structure is not complex (i.e. has only a single data array, with no ’real’ and ’imaginary’ arrays).
Parameters:
CDATA
The name of an existing complex data structure. The real data array from this will become the data array of the resulting structure.
OUTPUT
The name of the data structure to be created. Its data array will come from the structure specified as CDATA, and it will not have any ’real’ or ’imaginary’ arrays. If OUTPUT is the same as CDATA, CDATA will be transformed into a non-complex structure (which means that its imaginary part will be lost); otherwise, a new file is created.
Source comments:
   C M P L X 2 R    /     C M P L X 2 I   /   C M P L X 2 M
  
   Creates a real data structure (i.e. one with just a real data array)
   as opposed to a complex data structure, (in the Figaro sense of a
   structure with both  real and imaginary data arrays)
   from a complex data structure.
   In the case of CMPLX2R it is the real part of the complex data
   that forms the data array in the resulting structure.
   For CMPLX2I, it is the imaginary part, and for CMPLX2M
   it is the modulus of the complex data.
  
   Command parameters -
  
   CDATA    (Character) The name of the input complex structure.
   OUTPUT   (Character) The name of the resulting structure.  This
            may be the same as CDATA. In either case a new file
            is created.
  
   Command keywords - None
                                       KS / AAO  24th Sept 1986.

D.33 CMPLXADD-Add two complex structures

Description:
CMPLXADD adds together two complex data structures. These may have any shape and size, so long as they are both the same. A ’complex data structure’ here means a structure containing a .Z.REAL, a .Z.IMAGINARY and a .Z.DATA array, all with dimensions that factorise easily so that FFTs can be applied to them.
Parameters:
CDATA
The first of the images to be summed.
CDATA1
The second of the images to be summed.
OUTPUT
The name of the resulting structure. This can be the same as CDATA, in which case no new structure is created. Otherwise, OUTPUT will be a new file, with the same structure as CDATA.
Source comments:
   C M P L X A D D   /   C M P L X S U B
  
   C M P L X D I V   /   C M P L X M U L T
  
   This routine services the Figaro complex structure arithmetic
   routines CMPLXADD, CMPLXSUB, CMPLXDIV, and CMPLXMULT.  These
   commands operate on two complex structures, performing element
   by element arithmetic to produce a new structure.  The complex
   structures may be of any dimensions, so long as they match.
  
   Command parameters -
  
   CDATA    (Character) The name of the first complex structure.
   CDATA1   (Character) The name of the second complex structure.
   OUTPUT   (Character) The name of the resulting structure.
  
   Command keywords - None
                                       KS / AAO  10th Sept 1986.

D.34 CMPLXCONJ-Produce the complex conjugate of a complex structure

Description:
CMPLXCONJ takes the complex conjugate of a complex data structure A ’complex data structure’ here means a structure containing a .Z.REAL, a .Z.IMAGINARY and a .Z.DATA array, all with dimensions that factorise easily so that FFTs can be applied to them.
Parameters:
CDATA
The name of the complex data structure of which the complex conjugate is to be taken.
OUTPUT
The name of the resulting structure. This can be the same as CDATA, in which case no new structure is created. Otherwise, OUTPUT will be a new file, with the same structure as CDATA.
Source comments:
   C M P L X C O N J
  
   This routine produces the complex conjugate of a complex data
   structure.
  
   Command parameters -
  
   CDATA    (Character) The name of the first complex structure.
   OUTPUT   (Character) The name of the resulting structure.  This
            may be the same as CDATA, in which case the operation
            is performed in situ.  Otherwise, a new file is created.
  
   Command keywords - None
                                       KS / AAO  23rd Sept 1986.

D.35 CMPLXDIV-Divide two complex structures

Description:
CMPLXDIV divides two complex data structures. These may have any shape and size, so long as they are both the same. A ’complex data structure’ here means a structure containing a .Z.REAL, a .Z.IMAGINARY and a .Z.DATA array, all with dimensions that factorise easily so that FFTs can be applied to them.
Parameters:
CDATA
The complex dividend.
CDATA1
The complex divisor.
OUTPUT
The name of the resulting structure. This can be the same as CDATA, in which case no new structure is created. Otherwise, OUTPUT will be a new file, with the same structure as CDATA.
Source comments:
   C M P L X A D D   /   C M P L X S U B
  
   C M P L X D I V   /   C M P L X M U L T
  
   This routine services the Figaro complex structure arithmetic
   routines CMPLXADD, CMPLXSUB, CMPLXDIV, and CMPLXMULT.  These
   commands operate on two complex structures, performing element
   by element arithmetic to produce a new structure.  The complex
   structures may be of any dimensions, so long as they match.
  
   Command parameters -
  
   CDATA    (Character) The name of the first complex structure.
   CDATA1   (Character) The name of the second complex structure.
   OUTPUT   (Character) The name of the resulting structure.
  
   Command keywords - None
                                       KS / AAO  10th Sept 1986.

D.36 CMPLXFILT-Create a mid-pass filter for complex data

Description:
CMPLXFILT generates a complex data structure whose data have the form of a mid-pass filter that can be applied to other complex data of the same size using CMPLXMULT. The filter is specified by a low and high cutoff. If the low cutoff is specified as 0, a low-pass filter is constructed.
Parameters:
CDATA
CMPLXFILT uses an input complex data structure, specified as CDATA, as a template for the filter it generates. The resulting filter has the same structure (and data dimem- sions) as the template, only the data arrays differing. If the template data is n-dimensional, an n-dimensional filter will be generated, the cutoff frequencies being the same in each dimension.
LOWCUT
The mid-pass filter rises from zero, LOWCUT being the frequency (specified in terms of the Nyquist frequency) at which it reaches a height of exp(-1/2) =  0.6 If LOWCUT is specified as zero, a low-pass filter results. The filter is in fact a falling gaussian with a width specified by HICUT which has subtracted from it a rising gaussian with a width specified by LOWCUT.
HICUT
HICUT is the element at which the filter drops to a height of exp(-1/2) =  0.6 It is specified in terms of the Nyquist frequency.
OUTPUT
The name of the resulting filter. If OUTPUT is the same as CDATA, the filter replaces the data originally in CDATA. Otherwise, a new structure is created.
Source comments:
   C M P L X F I L T
  
   This routine produces a mid-pass complex filter, given a complex
   structure as a template and low and high cutoff values.  The
   filter is produced by the subtraction of two gaussians.  If no
   low value is specified, the result is a single gaussian low-pass
   filter.
  
   Command parameters -
  
   CDATA    (Character) The name of the template complex structure.
   LOWCUT   (Numeric) The low cutoff value for the filter.  This is
            specified in terms of the Nyquist frequency.  It is the
            sigma of the low cut gaussian, i.e. the point at which the
            rising edge of the filter reaches exp(-1/2) =~.6
   HICUT    (Numeric) The high cutoff value for the filter.  This is
            specified in terms of the Nyquist frequency.  It is the
            sigma of the high cut gaussian, i.e. the point at which the
            falling edge of the filter reaches exp(-1/2) =~.6
   OUTPUT   (Character) The name of the resulting structure.  This
            may be the same as CDATA, in which case the operation
            is performed in situ.  Otherwise, a new file is created.
  
   Command keywords - None
  
   Output data -
  
   The resulting complex data have a zero imaginary part, and a real
   part given by F(X)=exp(-X**2/(2*V**2))-exp(-X**2/(2*U**2))
   where U and V are the low and high frequency cutoffs respectively.
   (Note that the actual data generated is symmetrical about the
   mid point of the data, which is assumed to be the zero frequency
   - the Figaro function FFT produces data in this form).
  
                                       KS / AAO  9th Oct 1986.

D.37 CMPLXMULT-Multiply two complex structures

Description:
CMPLXMULT multiplies two complex data structures. These may have any shape and size, so long as they are both the same. A ’complex data structure’ here means a structure containing a .Z.REAL, a .Z.IMAGINARY and a .Z.DATA array, all with dimensions that factorise easily so that FFTs can be applied to them.
Parameters:
CDATA
The first complex data to be multiplied.
CDATA1
The second complex data to be multiplied.
OUTPUT
The name of the resulting structure. This can be the same as CDATA, in which case no new structure is created. Otherwise, OUTPUT will be a new file, with the same structure as CDATA.
Source comments:
   C M P L X A D D   /   C M P L X S U B
  
   C M P L X D I V   /   C M P L X M U L T
  
   This routine services the Figaro complex structure arithmetic
   routines CMPLXADD, CMPLXSUB, CMPLXDIV, and CMPLXMULT.  These
   commands operate on two complex structures, performing element
   by element arithmetic to produce a new structure.  The complex
   structures may be of any dimensions, so long as they match.
  
   Command parameters -
  
   CDATA    (Character) The name of the first complex structure.
   CDATA1   (Character) The name of the second complex structure.
   OUTPUT   (Character) The name of the resulting structure.
  
   Command keywords - None
                                       KS / AAO  10th Sept 1986.

D.38 CMPLXSUB-Subtract two complex structures

Description:
CMPLXSUB subtracts two complex data structures. These may have any shape and size, so long as they are both the same. A ’complex data structure’ here means a structure containing a .Z.REAL, a .Z.IMAGINARY and a .Z.DATA array, all with dimensions that factorise easily so that FFTs can be applied to them.
Parameters:
CDATA
The complex data to be subtracted from.
CDATA1
The complex data to subtract from CDATA.
OUTPUT
The name of the resulting structure. This can be the same as CDATA, in which case no new structure is created. Otherwise, OUTPUT will be a new file, with the same structure as CDATA.
Source comments:
   C M P L X A D D   /   C M P L X S U B
  
   C M P L X D I V   /   C M P L X M U L T
  
   This routine services the Figaro complex structure arithmetic
   routines CMPLXADD, CMPLXSUB, CMPLXDIV, and CMPLXMULT.  These
   commands operate on two complex structures, performing element
   by element arithmetic to produce a new structure.  The complex
   structures may be of any dimensions, so long as they match.
  
   Command parameters -
  
   CDATA    (Character) The name of the first complex structure.
   CDATA1   (Character) The name of the second complex structure.
   OUTPUT   (Character) The name of the resulting structure.
  
   Command keywords - None
                                       KS / AAO  10th Sept 1986.

D.39 COADD-Form the spectrum which is the mean of the rows in an image

Description:
COADD takes a 2-D file as produced by FIGS322 or RCGS2 and combines scans to generate a spectrum with error bars
Parameters:
IMAGE
The name of a 2-D file (wavelength by scan number) as produced, for example, by FIGS322 or RCGS2.
TSTART
The first t-value to be used.
TEND
The last t-value to be used.
YSTART
The first y-value to be used.
YEND
The last y-value to be used.
CUTOFF
Values more than CUTOFF times sigma away from the mean value for the spectral point will not be included in the final spectrum.
SPECTRUM
The name of the resulting single spectrum produced by collapsing down the image.
NORM
NORM=YES causes the data for each cycle to be normalized so that the mean value for each cycle is the same. This gives more reasonable errors when data are taken in the presence of cloud. It should not be used on very faint sources, as the mean level may go negative under these circumstances.
Source comments:
   C O A D D
  
   Form a spectrum which is the mean of all the rows in an image
   or form an image which is the mean of all the planes in a cube.
   The errors on the result are the standard errors of the mean
   (i.e. SIGMA/SQRT(N) when N rows or planes are combined). Any error
   information in the original image or cube is ignored.
  
   An XY image is collapsed along the Y direction to give a spectrum,
   and an XYT cube is collapsed along the T direction to give an XY image.
  
   Typical uses include the combination of the various cycles of a
   CGS2 or FIGS observation as output by the FIGS322 or RCGS2 programs,
   or coadding of CGS4 observations (for this purpose the individual images
   must be first grown into a cube using GROWXY).
  
   If the NORM keyword is set the errors are calculated after
   normalizing each row or plane so that the mean value is the same
   for all rows (planes). This does not effect the output data but
   generates errors which are determined only by the noise level in the
   data and are not influenced by any general trend in the data.
  
   If the CUTOFF parameter is specified, points which deviate from the
   mean by more than CUTOFF times the standard error for the mean are
   excluded from the calculation. The mean is recalculated until no
   points exceed the CUTOFF limit. This procedure allows spikes in the
   data to be removed.
  
   Command parameters -
  
   ’IMAGE’    The name of the input 2-D or 3-D file.
   ’YSTART’   (or TSTART) The first Y or T value to use.
   ’YEND’     (or TEND) The last Y or T value to use.
   ’SPECTRUM’ The name of the resulting spectrum or image.
   ’CUTOFF’   The level (in sigma) at which a point will
              be ignored.
  
   Command keywords -
  
   ’NORM’     Normalize data to mean level.
  
   Input data -
  
                                   JAB / JAC 7th Dec 1990

D.40 COLOUR-Set colour table for image display

Usage:
colour table
Description:
This routine sets the colour table of the image display device. It can either be reset to a grey scale, or an RGB lookup table from a 3xN image can be used. The lookup table must have numbers between 0.0 and 1.0.
Parameters:
TABLE
The colour table file to be used. The programme will look for this file in the default directory and then in the standard Figaro directories. If TABLE is ’grey’ or ’gray’ this is trapped and a grey scale table is set up.
IDEV
The name of the imaging device, normally got from a global parameter which was set with the IDEV command.
Authors:
ks: Keith Shortridge (AAO)

hme: Horst Meyerdierks (UoE, Starlink)

D.41 COMB-Corrects for S-distortion using continua

Description:
This is a program to correct data for s-distortion by moving data in the cross-section direction to line it up for a comb of continua spectra.This correction is then applied to the data itself. A comb dekker is used to produce about ten continuum spectra across an image (this is done at the telescope). This image is then used by the program:- The program requests two adjacent "teeth" to be marked, it locates the remaining teeth and follows them along the image (in the channel direction), finding the line centres by fitting gaussians. The points so obtained are fitted with Chebyshev polynomials (for each tooth), The intermediate positions are interpolated from these, which are then used to evaluate the required movement for each data point. The coefficients are written to a file which may then be read by the program to apply correction to the actual data. Alternatively if QUICK is specified centriods are used rather than Gaussians.
Parameters:
IMAGE
IMAGE = FILE (Read) Name of image for input This should be a file containing continua spectra.
ARC_OPTS
ARC_OPTS = CHARACTER (Read) Enter arc fit option NEW : set up a new wavelength calibration REPEAT : Itterate on previous calibration. CLONE : CLone a previous calibration. OLD : Correct using previous results
OUTPUT
OUTPUT = FILE (Write) Name of output file File to contain corrected data.
XSTART
XSTART = INTEGER (Read) analysis lower limit The data between the limits xstart and xend is extracted and the resultant spectrum is used to locate the lines.
XEND
XEND = INTEGER (Read) analysis upper limit The data between the limits xstart and xend is extracted and the resultant spectrum is used to locate the lines.
XBLOCK
XBLOCK = INTEGER (Read) Enter averaging width in channels Each window is of this width (except perhaphs the final one).
ITERATION
ITERATION = INTEGER*2 (Read) New value of iteration
LEVEL
LEVEL = REAL (Read) Level of edge of tooth
ORDER
ORDER = INTEGER (Read) order for polynomial fitting This is for the continuity correction of the data. Idealy the arc should have been pre-processed with ARCSDI, so a low order e.g. 2 should be used.
MAXLINES
MAXLINES = INTEGER (Read) Maximum number of lines to allow room for This must be greater than or equal to the number of lines fitted, so room should be allowed in case any more are to be added later.
CLFILE
CLFILE = FILE (Read) Name of image for cloning from This should be a file containing an arc spectrum.
TOLS
TOLS = CHARACTER (Read) For use in batch only
KEEP_ITT
KEEP_ITT = LOGICAL (Read) keep itteration files?
QUICK
QUICK = LOGICAL (Read) Centriod rather than fit gaussians?
PRFITS
PRFITS = LOGICAL (Read) Print out details of fitting
PLOTCORR
PLOTCORR = LOGICAL (Read) Plot correction?
Source comments:
    none available
  

D.42 COMBINE-Combine two spectra, adding with weights according to errors

Description:
Combines two spectra, adding them with weights that depend on their errors. Elements with equal errors, for example, will be averaged. COMBINE is intended for use with spectra, but will work on any data that has error values for each data point.
Parameters:
SPECTRUM
The first of the two spectra to be combined.
SPECTRUM1
The second of the two spectra to be combined.
OUTPUT
The name of the resulting spectrum. This can be the same as SPECTRUM, in which case no new spectrum will be created.
Source comments:
   C O M B I N E
  
   Combine two spectra or images. If error or variance information
   is available on the two images a weighted mean of the two
   is formed. If error information is missing for one or both
   images a simple average is formed.
  
   Command parameters -
  
   SPECTRUM  The name of the structure containing the first spectrum
  
   SPECTRUM1 The name of the structure containing the second spectrum
  
   OUTPUT    The name of the result of the operation.  This can
             be the same as for SPECTRUM.  If not, a new structure
             is created, with everything but the data a direct
             copy of the input.
  
                                        JAB / AAO  14th July 1986

D.43 COPOBJ-Copy an HDS object

Usage:
copobj source object
Description:
This routine creates or modifies an object to be a copy of an existing HDS object (in the same or a different container file). The destination object can either be a newly created scalar object or an existing cell of an array. If it is a cell of a structure array, it must be an empty structure.
Parameters:
SOURCE
The existing HDS object to be copied. Specify beginning with directory and file name in the syntax of the operating system, followed by the dot-separated structure hierarchy. Elements of structure arrays are specified in ordinary brackets ().
OBJECT
The HDS object to be created or modified. Specify beginning with directory and file name in the syntax of the operating system, followed by the dot-separated structure hierarchy. Elements of structure arrays are specified in ordinary brackets (). An array element (cell) cannot be created, but an exisiting cell can be modified.
Examples:
   1.  copobj source=@"file1.dst".Z.DATA object=file2.DATA_ARRAY
      Copy the data array from a Figaro DST file into the data array
      of an NDF. Note that file2.DATA_ARRAY must not exist
      beforehand, and that file2 without DATA_ARRAY is not a legal
      NDF. So probably this would be the first action after creation
      of the empty HDS file "file2".
  
See also:
FIGARO: CREOBJ, DELOBJ, RENOBJ, SETOBJ.
KAPPA: ERASE.
Authors:
KS: Keith Shortridge (AAO)

HME: Horst Meyerdierks (UoE, Starlink)

JFL: John Lightfoot (ROE)

D.44 CORREL-Correlate two or three data sets.

Usage:

correl inlist out logfil

Description:

This routine correlates two or three data sets. Either pair is subjected to a linear fit and the third data set is subjected to a two-parameter linear fit (i.e. regarded as a linear function of the first and second data sets). Each data set may be an NDF section. All must have the same dimensions.

Parameters:
INFO
INFO = _LOGICAL (Read) If false, the routine will issue only error messages and no informational messages. [YES]
VARUSE
VARUSE = _LOGICAL (Read) If false, input variances are ignored. [YES]
INLIST
INLIST = LITERAL (Read) The group of input NDFs. Two or three NDFs must be specified. A complicated INLIST could look something like
     M_51(25:35,-23.0,-24.0),M101,^LISTFILE.LIS

This example NDF group specification consists of

  • one identified NDF from which a subset is to be taken,
  • one identified NDF,
  • an indirection to an ASCII file containing more NDF group specifications. That file may have comment lines and in-line comments, which are recognised as beginning with a hash (#).
OUT
OUT = FILENAME (Read) The ASCII output file where the data points are written into a table. A new file will be opened. No file will be opened, if "!" is entered. The table in OUT is without any information else than the values from the 1st, 2nd, 3rd data array and errors from the 1st, 2nd, 3rd variance array in that order. [!]
LOGFIL
LOGFIL = FILENAME (Read) The ASCII log file where fit results are written to. This will be opened for append, if such a file exists.

D.45 COSBELL-Create data that goes to zero at the edges in a cosine bell

Description:
COSBELL generates a spectrum or image which goes to zero at the edges, is unity over its central section, and which rises from 0 to 1 in a cosine bell over a specified outer percentage of its range.
Parameters:
SPECTRUM
A template data file to use when constructing the cosine bell data. The output data will be a copy of the template, except for the main data array. The data may be 1- or 2-dimensional.
BELLPC
The data generated by COSBELL is 1.0 in the centre, 0 at the edges, and rises from 0 to 1 over a range specified as BELLPC % of the total range.
OUTPUT
The name of the resulting datafile. If this is the same as the template SPECTRUM, the data in the template will be lost, being replaced by the cosine bell data. Otherwise, a new file will be created.
Source comments:
   C O S B E L L
  
   Given a template data file, COSBELL creates a data file that is
   the same as the template but in which the data is a cosine bell
   filter.  This can then be applied to the original data (or to
   other data with the same dimensions) using IMULT.
  
   Command parameters -
  
   SPECTRUM (Character) The name of the structure containing the
            template data.
  
   BELLPC   (Numeric) The percentage of the data that is to be covered
            by the rising (or falling) part of the cosine bell.
  
   OUTPUT   (Character) The name of the result of the operation.  This
            can be the same as for SPECTRUM. If not, a new structure
            is created, with everything but the data a direct
            copy of the input.
                                               KS / AAO 23rd Sept 1986

D.46 COSREJ-Reject cosmic rays from a set of supposedly identical spectra

Description:
Given an image whose cross-sections are a set of spectra of the same object all with exactly the same wavelength to pixel mapping (in other words a set of spectra that should be identical, other than for signal to noise effects and possible differences in their total counts due to differing exposure times etc), COSREJ attempts to remove any cosmic rays or other obvious features that might be contaminating some (but not the majority) of the spectra.
Parameters:
IMAGE
A 2-D image in which all the cross sections are a set of similar spectra. Note that each pixel of each spectrum is compared with the corresponding pixels in the other spectra, so they should be properly aligned - probably already scrunched.
XSTART
COSREJ scales up each spectrum to the same mean value. To do this it calculates the mean for each spectrum between the limits sepcified for XSTART and XEND (which are given in terms of the X-axis values, not necessarily in pixels). Normally, you would use the whole spectrum, but there may be end effects you’d prefer to avoid.
XEND
COSREJ scales up each spectrum to the same mean value. To do this it calculates the mean for each spectrum between the limits sepcified for XSTART and XEND (which are given in terms of the X-axis values, not necessarily in pixels). Normally, you would use the whole spectrum, but there may be end effects you’d prefer to avoid.
CRSIG
Each pixel in each spectrum is compared with the equivalent pixels in the other spectra, and any that differ from the mean of the other pixels by more than a given factor (CRSIG) times the standard deviation of the other pixels are rejected. This is repeated until either only two pixels are left, or until no pixels are rejected in a pass through the remaining pixels. The rejected pixels are set to the mean value of the remaining unrejected pixels. If you’re only trying to get rid of gross effects like cosmic rays, CRSIG values around 10 should be satisfactory. The value is unlikely to be critical.
WMEAN
COSREJ can create a ‘spectrum’ with one element for each spectrum in the original image, where each element is the mean value used for that spectrum. This might possibly be used to scale the resulting image using, for example, ISYDIV. Such a spectrum is produced only if WMEAN is set.
MSPECT
If WMEAN is set, MSPECT is the name of the ‘mean spectrum’ generated. This is a file containing nothing but a data array containing the mean values for the spectra in the image.
OUTPUT
The name of the resulting image. The data produced in OUTPUT is the same as that for IMAGE, except that the cosmic rays have been processed out. If OUTPUT and IMAGE are the same, the operation is performed in situ.
See also:
FIGARO: BCLEAN, CLEAN, MEDFILT, MEDSKY, TIPPEX.
KAPPA: FFCLEAN, CHPIX, FILLBAD, GLITCH, MEDIAN, MSTATS, ZAPLIN.
Source comments:
   C O S R E J
  
   Name:
      COSREJ
  
   Function:
      Remove cosmic rays from a set of similar spectra.
  
   Description:
      Given an image whose cross-sections are a set of spectra of the
      same object all with exactly the same wavelength to pixel mapping
      (in other words a set of spectra that should be identical, other
      than for signal to noise effects and possible differences in
      their total counts due to differing exposure times etc), this
      routine attempts to remove any cosmic rays or other obvious
      features that might be contaminating some (but not the majority)
      of the spectra.  First, the mean value for each spectrum over a
      specified range is calculated and this is used to reduce each
      spectrum to the same mean value.  Each pixel in each spectrum is
      compared with the equivalent pixels in the other spectra, and any
      that differ from the mean of the other pixels by more than a
      given factor (the CRSIG parameter) times the standard deviation
      of the other pixels are rejected.  This is repeated until either
      only two pixels are left, or until no pixels are rejected in a
      pass through the remaining pixels.  The rejected pixels are set
      to the mean value of the remaining unrejected pixels.  Finally,
      the spectra are rescaled to their original mean values.  If
      requested, the program can create a ‘spectrum’ with one element
      for each spectrum in the original image, where each element is
      the mean value used for that spectrum.  This might possibly be
      used to scale the resulting image using, for example, ISYDIV.
  
   Command parameters:
      IMAGE    The name of the image in which the spectra are held.
      XSTART   The first x-value of the range to be used to calculate
               the mean value for each spectrum.
      XEND     The last x-value of the range to be used to calculate
               the mean value for each spectrum.
      CRSIG    The cutoff sigma value to be used.
      MSPECT   The name of the mean spectrum produced, if WMEAN is yes.
      OUTPUT   The name of the resulting image with the cosmic rays removed.
  
   Command keywords:
      WMEAN    Yes if a spectrum of mean values is to be produced.
  
   Error array handling: Ignored.
  
   Data quality / flagged value handling:
      Not explicitly performed.  Relies on standard DSA processing.
  
   Files used:
      BADPIX.DAT  Contains a list of the cosmic rays removed from the data.
  
      8th  Sept  1987.   Original version DJA / AAO

D.47 CREOBJ-Create a data object or file

Usage:
creobj type dims object
Description:
This routine creates an HDS object, primitive or structure, scalar or array. In theory it is possible to build up a complete NDF or Figaro DST data file. This is not recommended because the risk of creating an illegal hierarchy of HDS structures - i.e. one not accepted by KAPPA, Figaro, etc. - is very high. This routine is intended only for minor repairs to such files, or in emergencies to create a very simple, minimal, data file.
Parameters:
TYPE
The HDS type of the object to be created. Figaro users note that this is something like ’_REAL’, ’_DOUBLE’, ’_INTEGER’, ’_WORD’ etc. Anything which is not such a primitive HDS type will cause a structure to be created. The type specified here will then be used as that structure’s type. [’_REAL’]
DIMS
The dimensions of the object to be created, i.e. the size of the array along each axis. The number of positive integers specified indicates the dimensionality of the object created. To create a scalar object enter zero, a single zero will do. [0]
OBJECT
The object to be created. Specify beginning with directory and file name in the syntax of the operating system, followed by the dot-separated structure hierarchy. Elements of structure arrays are specified in ordinary brackets (). An array element cannot be created.
Examples:
   1.  creobj type=NDF dims=0 object=file
      This will create an empty HDS file. The top level structure is
      of type "NDF", which has little consequence.
  
   2.  creobj type=ARRAY dims=0 object=file.DATA_ARRAY
      This will create the scalar structure DATA_ARRAY in the top
      level structure of the file "file". The structure type is
      "ARRAY", which has special meaning in the Starlink Data Format.
  
   3.  creobj type=_REAL dims=[20,30] object=file.DATA_ARRAY.DATA
      This will create a two-dimensional array of \_REAL numbers
      called DATA and situeated in file.DATA_ARRAY. The size of the
      new array is 20 by 30 numbers.
  
   4.  creobj type=AXIS dims=2 object=file.AXIS
      This will create a one-dimensional array of AXIS structures
      called AXIS and situated underneath the top level of "file".
  
Authors:
KS: Keith Shortridge (AAO)

HME: Horst Meyerdierks (UoE, Starlink)

D.48 CRIGAUSS-Creates a file with a profile of 1 to 5 gaussians

Description:
The profiles are evaluated and copied to each cross-section. This is really intended for testing software.
Parameters:
IMAGE
IMAGE = FILE (Read) Name of image to be created
YDIM
YDIM = INTEGER (Read) Y dimension of data
XDIM
XDIM = INTEGER (Read) X dimension of data"
XSTART
XSTART = REAL (Read) First X value
XEND
XEND = REAL (Read) Last X value
WIDTH1
WIDTH1 = REAL (Read) WIDTH1 of gaussian (fwhm)
CENTRE1
CENTRE1 = REAL (Read) CENTRE1 of gaussian
HEIGHT1
HEIGHT1 = REAL (Read) HEIGHT1 of gaussian
WIDTH2
WIDTH2 = REAL (Read) WIDTH2 of gaussian (fwhm)
CENTRE2
CENTRE2 = REAL (Read) CENTRE2 of gaussian
HEIGHT2
HEIGHT2 = REAL (Read) HEIGHT2 of gaussian
WIDTH3
WIDTH3 = REAL (Read) WIDTH3 of gaussian (fwhm)
CENTRE3
CENTRE3 = REAL (Read) CENTRE3 of gaussian
HEIGHT3
HEIGHT3 = REAL (Read) HEIGHT3 of gaussian
WIDTH3
WIDTH4 = REAL (Read) WIDTH4 of gaussian (fwhm)
CENTRE4
CENTRE4 = REAL (Read) CENTRE4 of gaussian
HEIGHT4
HEIGHT4 = REAL (Read) HEIGHT4 of gaussian
WIDTH5
WIDTH5 = REAL (Read) WIDTH5 of gaussian (fwhm)
CENTRE5
CENTRE5 = REAL (Read) CENTRE5 of gaussian
HEIGHT5
HEIGHT5 = REAL (Read) HEIGHT5 of gaussian
BASE
BASE = REAL (Read) BASE for gaussian
NCOMP
NCOMP = INTEGER (Read) NCOMP Number of componants
Source comments:
    none available
  

D.49 CSCAN-Plot array of profiles from a 3D array

Description:
This displays line profiles from a sorted data cube (i.e. the first dimension is that of wavelength).
Parameters:
CUBE
CUBE = FILE (Read) Name of CUBE for input
YSTART
YSTART = REAL (Read) display lower limit
YEND
YEND = REAL (Read) display upper limit
TSTART
TSTART = INTEGER (Read) display lower limit
TEND
TEND = INTEGER (Read) display upper limit
HARDCOPY
HARDCOPY = LOGICAL (Read) use hard graphics device for display
Source comments:
    none available
  

D.50 CSET-Interactively set regions of a spectrum to a constant value

Description:
CSET is an interactive program that takes a displayed spectrum and allows the user to select regions that are to be set to constant values. This can be used, for example, to set regions in a B star calibration spectrum to 1., so that they will have no effect when used with BSMULT.
Parameters:
VALUE
CSET lets you select regions of an already displayed spectrum, which are then set to a constant value. This value can be changed if required, but this is the initial setting for it.
OUTPUT
CSET generates an output file that is essentially the data from the displayed spectrum, with certain regions set to constant values. OUTPUT is the name of the resulting spectrum.
QUIT
Used to confirm quitting area selection.
See also:
FIGARO: ICSET, NCSET, TIPPEX.
KAPPA: CHPIX, FILLBAD, SEGMENT, NOMAGIC, RIFT, SETMAGIC, ZAPLIN.
Source comments:
   C S E T
  
   Figaro function to set large interactively selected regions
   of a spectrum to a constant value.  This is intended mainly
   for use in generating mask spectra, or modifying calibration
   spectra such as those used by BSMULT.  CSET assumes that a
   spectrum has already been displayed by SPLOT, and will generate
   a new data structure based on the spectrum displayed, with
   only the data changed.
  
   Command parameters -
  
   VALUE       (Numeric) The value to use for the selected regions
  
   OUTPUT      (Character) The name of the output file to
               be created.  If this is the same as the displayed
               spectrum, the data in the displayed spectrum will
               be modified.
  
   Command keywords -
  
   QUIT        Used to confirm quitting area selection.
  
   User variables used -  (">" input, "<" output)
  
   (>) TVFILE  The name of the displayed spectrum
   (>) TVXST   The first displayed x-value
   (>) TVXEN   The last displayed x-value
   (>) TVHIGH  The maximum displayed y-value
   (>) TVLOW   The minimum displayed y-value
   (>) TVCOLOR The GRPLOT code for the plot colour
   (>) SOFT    The device/type string defining the display device
  
                                            KS / CIT 11th April 1984

D.51 CSPIKE-Create calibration spiketrum given spiketrum and standard spectrum

Description:
Given a ’spiketrum’ generated by GSPIKE from a table of flux densities at given wavelengths for a particular standard star together with a spectrum of that same object, CSPIKE calc- ulates the instrumental response at the various tabulated points. Note - this routine is intended for standards where the tables give the average measured flux density over a given wavelength range for each point, rather than calculated continuum values. CSPIKE will not accept a spiketrum that has data in magnitude units.
Parameters:
SPIKETRUM
A spiketrum (see HELP FIGARO TECHNIQUES SPIKETRA for details) generated from a table of measured average flux densities over given wavelength ranges versus the central wavelengths. The data should not be in magnitude units.
SPECTRUM
An observed spectrum of the object whose tabulated fluxes were used to generate SPIKETRUM. Note that CSPIKE does not insist on the spectrum’s having been scrunched, but things are usually easier if it has been.
OUTPUT
CSPIKE generates a spiketrum whose non-zero values give the instrumental response in "units per counts per second per angstrom", where "units" are the units used by the input spiketrum.
Source comments:
   C S P I K E
  
   Generates a calibration ’spiketrum’, given an observation of
   a standard star and a spiketrum giving the tabulated flux
   values for that star.  The calibration spiketrum has points
   giving the instrumental response calculated at the points
   given by the spikes in the flux spiketrum.  A calibration
   spectrum can then be generated by interpolating between the
   points of the calibration spectrum.
  
   Command Parameters
  
   SPIKETRUM     (Character) The tabulated flux spiketrum.  Note:
                 this should include the BANDWIDTH data
                 object - a spiketrum that does not is probably
                 not appropriate for this function.  Also note that
                 CSPIKE does not work with data in magnitude units.
   SPECTRUM      (Character) The observation of the standard star.
                 Note that this should include an exposure time data
                 object.  If it does not, a time of 1 sec will be
                 assumed, and the calibration will only be relative.
                 Both SPECTRUM and SPIKETRUM should contain an
                 AXIS(1) data array, giving the wavelength values.  These
                 should normally be exactly the same, although this
                 is not essential.
   OUTPUT        (Character) The resulting spiketrum of calibration
                 points.
  
   Command keywords - None
  
   User variables used - None
  
                                    KS / CIT 28th May 1984

D.52 CSUB-Subtracts a continuum from 2 dimensional data

Description:
A polynomial is fitted to the continuum and this is subtracted. As with VIG, lines can be excluded from the polynomial fitting. CSUB stores the polynomial fitting coefficients in the actual data file.
Parameters:
IMAGE
IMAGE = FILE (Read) Name of image for input
OLD
OLD = LOGICAL (Read) Old coefficients are to be used for correction
OUTPUT
OUTPUT = FILE (Write) Name of output file OUTPUT is the name of the resulting spectrum. If OUTPUT is the same as INPUT the data in the input file will be modified in situ. Otherwise a new file will be created.
Source comments:
    none available
  

D.53 CUBE2LONG-Takes a longslit spectrum from a non-sorted TAURUS cube

Description:
This uses cubic spline interpolation to create a 2-d file from a 3-d file, given a location, angle and length.
Parameters:
CUBE
CUBE = FILE (Read) Sorted TAURUS cube
XPOINT
XPOINT = REAL (Read) X point anywhere on slit
YPOINT
YPOINT = REAL (Read) Y point anywhere on slit
ANGLE
ANGLE = REAL (Read) Position angle (degrees)
OUTPUT
OUTPUT = FILE (Write) Output longslit spectrum
Source comments:
    none available
  

D.54 DELOBJ-Delete a data object or a file

Usage:
delobj object
Description:
This routine deletes an HDS object (structure or primitive, scalar or array) in an HDS file.
Parameters:
OBJECT
The object to be deleted. Specify beginning with directory and file name in the syntax of the operating system, followed by the dot-separated structure hierarchy. Elements of structure arrays are specified in ordinary brackets (). An array element cannot be deleted.
Examples:
   1.  delobj file.axis(2).units
      The file in question is in the current working directory and
      has the standard extension ".sdf". The deleted structure is the
      UNITS string in the 2nd element of the structure array AXIS.
      Note that it would be impossible to delete AXIS(2), but one
      could delete AXIS as a whole.
  
   2.  delobj @"/home/resun02/myname/data/file.dst".z.label
      Here the file is specified with its complete Unix directory and
      with its non-standard extension ".dst". The deleted structure
      is the LABEL within the Z structure.
  
See also:
FIGARO: CREOBJ, COPOBJ, RENOBJ, SETOBJ.
KAPPA: ERASE.
Authors:
KS: Keith Shortridge (AAO)

HME: Horst Meyerdierks (UoE, Starlink)

D.55 DVDPLOT-Plot the data in one file against the data in another

Usage:
dvdplot image image2 xlow xhigh low high autoscale
Description:
DVDPLOT (Data Versus Data PLOT) plots the data from the main array in one structure against the data in the corresponding elements of the main array in another structure. It was first written to help with linearity tests (plotting data from an image with high count rates against a similar image with lower count rates).

The Y value for each point is the pixel value from IMAGE and the X value is the value of the corresponding value from IMAGE2.

The images must have identical dimensions.

Parameters:
IMAGE
Y-value image.
IMAGE2
X-value image.
XLOW
XLOW and XHIGH specify the limits in X of the plot. They are values in the same range as the data range as the main array in IMAGE2. If WHOLE is set, XLOW is set to the lowest data value in IMAGE2.
XHIGH
XLOW and XHIGH specify the limits in X of the plot. They are values in the same range as the data range as the main array in IMAGE2. If WHOLE is set, XHIGH is set to the highest data value in IMAGE2.
LOW
LOW and HIGH specify the limits in Y of the plot. They are values in the same range as the data range as the main array in IMAGE. If AUTOSCALE is set, LOW is set to the lowest data value in IMAGE for which the corresponding IMAGE2 pixel is in the range XLOW..XHIGH.
HIGH
LOW and HIGH specify the limits in Y of the plot. They are values in the same range as the data range as the main array in IMAGE. If AUTOSCALE is set, HIGH is set to the highest data value in IMAGE for which the corresponding IMAGE2 pixel is in the range XLOW..XHIGH.
WHOLE
WHOLE has the effect of setting XLOW and XHIGH (the x-limits of the plot) to the extreme data values in IMAGE2. The result is that the plot range in X is such as to cover all the pixels in the image.
AUTOSCALE
The XLOW and XHIGH parameters (or, alternatively, the WHOLE keyword) select the X-range of the plot and hence the pixels that may be plotted. The LOW and HIGH parameters then limit the Y-range of the plot. The AUTOSCALE keyword has the effect of setting LOW and HIGH to the extreme values of the pixels delimited by XLOW and XHIGH. Which is a complicated way of saying it scales the plot so all the points fit in it.
HARDCOPY
Normally, DVDPLOT produces a plot on the current soft plot device - selected using the SOFT command. If the HARDCOPY keyword is set, the plot is made on the current hard copy plot device - selected using the HARD command. Normally, only a plot file is produced and this must be explicitly sent to the hardcopy device once DVIPLOT has finished.
Source comments:
   D V D P L O T
  
   Routine name:
      DVDPLOT
  
   Function:
      Plots the data in one data array against the data in another.
  
   Description:
      DVDPLOT (Data Versus Data PLOT) plots the data in the main data
      array in one Figaro structure against the corresponding data elements
      of the main data array in another structure.  This was originally
      written to help with linearity tests (where data in an image taken
      at a low data rate could be plotted against one taken at a higher
      data rate), but may have other applications.
  
   Usage:
      DVDPLOT IMage IMAGE2 XLow XHigh LOw HIgh AUtoscale
  
   Parameters:
      IMAGE     (Character) The name of the first structure.  It is this
                structure whose data is plotted against the data in IMAGE2,
                so its data values form the Y values of the plotted points.
      IMAGE2    (Character) The name of the second structure.  Its data
                values form the X values of the plotted points.
      XLOW      (Numeric) The low end of the data range plotted in X (i.e.
                the lower limit for the data in IMAGE2).
      XHIGH     (Numeric) The high end of the data range plotted in X (i.e.
                the upper limit for the data in IMAGE2).
      LOW       (Numeric) The low end of the data range plotted in Y (i.e.
                the lower limit for the data in IMAGE).
      HIGH      (Numeric) The high end of the data range plotted in Y (i.e.
                the upper limit for the data in IMAGE).
  
   Keywords:
      WHOLE     If set, XLOW and XHIGH will be set to the limits
                of the data in IMAGE2.
      AUTOSCALE If set, LOW and HIGH will be set to the limits
                of the data in IMAGE.
      HARDCOPY  If set, a hard copy plot will be produced.
  
   User variables used:
      HARD      (Character) PGPLOT specification for hardcopy plot device
      SOFT      (Character) PGPLOT specification for softcopy plot device
  
   Error information:  Ignored.
  
   Quality information:  Handled using flagged values.
  
   Keith Shortridge, AAO

D.56 ECHARC-Wavelength calibrate an echelle arc

Description:
Each invocation of ECHARC produces a file arlines.ech in the working directory. This file must be renamed or deleted before re-invoking ECHARC.
Parameters:
IMAGE
The arc data. This should be a .dst file with a two dimensional .z.data component (pixels,orders). ECHARC assumes there is a .y.data component giving order numbers "m" (such as produced as output from the command ECHTRACT). If there is a .x.data component the information it contains will be used during the program, although usually the .x.data will simply be pixel number.
ARCTYPE
The type of arc that was used - e.g. HELIUM, NEON, etc. ARC will look for a file called ARCTYPE.ARC which should hold the line list for the arc.
INTERACTIVE
Number of orders to fit interactively.
ORDERS
The array of INTERACTIVE order numbers to be fit.
SIGMA
Arc line half width in pixels.
ORDERFIT
Polynomial order for 1st fit
PREVIOUS
If set, ARC will read in the line list from the previous session as a starting point.
MONITOR
Monitor ECHARC autofitting on plot device?
ARFILE
The name of the list file from which the previous fit is to be read. Only used if PREVIOUS is set, Note that the output is always written to ARLINES.ECH. Default extension is .ECH
DOWAVES
Write wavelength information to separate file?
WAVES
An output image containing the fitted wavelengths from this ECHARC solution as image data (not as axis data). This is created only if DOWAVES is set.
OUTPUT
The name of the output file that combines the input image data with the fitted wavelengths as axis data. This is created only if DOWAVES is NO.
CONTINUE
At this stage in ECHARC you can:

Continue - go to the next order to be fitted interactively. Repeat - return to working on the order just completed. Start - back to square one. Quit - quit prematurely.

ORDPPAG
The number of sub-orders to be plotted per page in the hard copy line atlas.
DISNCHAN
Length of displayed sections.
MOVETOX
New plot centre x value.
CMD
At this stage in ECHARC you have the following options available:

Fit - Repeat the fit. O_fit - Change the order of the fit. Disp - Display the deviation of the fit from a linear fit. This shows the trend of the fit, and the errors in each line. Edit - Delete or change the wavelength of one or more of the selected lines, without returning to the cursor selection. Reselect - Return to selection using the cursor. Continue - Start to quit this order. Print - Prints a copy of the fit (what ARLINES.LIS would look like if you were to exit now). Auto - Starting from your current fit and arc line list, ECHARC looks for additional line in the arc at wavelengths given in the line list and adds any it finds to the identified line tables. Xauto - Deletes all the lines found by ’Auto’. Modify - Allows you some control over the Autofit parameters. Help - (or ?) Display this information.

The first letter of each command is sufficient.

LINENO
Number of line to be edited.
WAVELEN
Wavelength specification.
CHFACT
The autofit algorithm is parameterised as follows-

It takes each pixel in turn. If that pixel is more than CHFACT times the current sigma value from any line already found, it uses that pixel as the starting point for a line search. If anything resembling a line can be found, it calculates its wavelength and looks in the line tables for a line close to that wavelength.

A line is accepted if the discrepancy between calculated and tabulated wavelength is less than SIGFACT times the current RMS value. This means that the criterion for accepting new lines is based on how their wavelength discrepancies compare with those for the lines that have already been accepted.

SIGFACT is the more important parameter.

SIGFACT
The autofit algorithm is parameterised as follows-

It takes each pixel in turn. If that pixel is more than CHFACT times the current sigma value from any line already found, it uses that pixel as the starting point for a line search. If anything resembling a line can be found, it calculates its wavelength and looks in the line tables for a line close to that wavelength.

A line is accepted if the discrepancy between calculated and tabulated wavelength is less than SIGFACT times the current RMS value. This means that the criterion for accepting new lines is based on how their wavelength discrepancies compare with those for the lines that have already been accepted.

SIGFACT is the more important parameter.

HLINEMAP
If set, a map of line locations is plotted as a hard copy.
HATLAS
If set, an atlas of lines is plotted as a hard copy.
ANALYSIS
If set, a detailed line-by-line analysis of the arc fit is written to the file "echarc.lis".
HARDARC
If set, the output spectrum is plotted in a hard copy.
HARDISP
If set, the dispersion curve is plotted in a hard copy.
QUITSEL
Used to confirm quitting line selection.
LINEOK
Used to confirm a choice of line for deletion, editing etc.
RESOLVE
Used to decide what to do if a line is used twice.
Source comments:
   E C H A R C                    (Version 1.0, 18-NOV-1987 ff.)
                                  (Version 1.5, 08-DEC-1987 ff.)
  
   This substantially revised version of ECHARC0 performs the 1-D
   ARC process on 3-30 orders of a collapsed echelle image, and
   then automatically detects lines and performs fits to all the
   remaining orders.  The output from the program is a complete
   listing of all lines found (ARLINES.ECH) and an output image
   with WAVES.Z.DATA containing the fitted wavelengths.  One can
   then use ICMULT and IADD to compute a weighted average of two
   or more such output fits, and then ECHXREBIN to rebin the data
   onto a constant "Meff * Lambda" .X.DATA scale.
  
   Command parameters -
  
   IMAGE        The arc data.  This should be a two-dimensional
                image. ECHARC assumes there is a y axis giving
                order numbers "m". If there is an x axis
                component the information it contains will be
                used during the program, although usually the
                x data will simply be pixel number.
   ARCTYPE      The type of arc that was used - e.g. HELIUM,
                NEON, etc.  ARC will look for a file called
                ARCTYPE.ARC which should hold the line list for
                the arc.
   INTERACTIVE  The number of orders to be fit interactively.
   ORDERS       The array of INTERACTIVE order numbers to be fit.
   ORDERFIT     The initial order of the polynomial fit.
   SIGMA        The initial value for the line width.
   ARFILE       The name of the list file from which the previous
                fit is to be read.  Only used if PREVIOUS is
                set.  Note that the output is always written
                to ARLINES.ECH.  Default extension is .ECH
   WAVES        An output image containing the fitted wavelengths
                from this ECHARC solution as image data (not as axis
                data). This is created only if DOWAVES is set.
   OUTPUT       The name of the output file that combines the input
                image data with the fitted wavelengths as axis
                data. This is created only if DOWAVES is no.
   CONTINUE     Command after an order is done with.
   ORDPPAG      The number of sub-orders to be plotted per page in
                the hard copy line atlas.
   DISNCHAN     Length of displayed sections.
   MOVETOX      New plot centre x value.
   CMD          Command in main menu.
   LINENO       Number of line to be edited.
   WAVELEN      Wavelength specification.
   CHFACT
   SIGFACT
  
   Command keywords -
  
   PREVIOUS     If set, ARC will read in the line list from
                the previous session as a starting point.
   DOWAVES      If set, the fitted wavelengths will be stored
                as image data in a separate file. Otherwise the
                fitted wavelengths will be stored as axis data along
                with the input image.
   HLINEMAP     If set, a map of line locations is plotted as
                a hard copy.
   HATLAS       If set, an atlas of lines is plotted as a
                hard copy.
   ANALYSIS     If set, a detailed line-by-line analysis of the
                arc fit is written to the file "echarc.lis".
   HARDARC      If set, the output spectrum is plotted in a
                hard copy.
   HARDISP      If set, the dispersion curve is plotted in a
                hard copy.
   QUITSEL      Used to confirm quitting line selection.
   LINEOK       Used to confirm a choice of line for deletion,
                editing etc.
   RESOLVE      Used to decide what to do if a line is used twice.
  
   User variables -
  
   (>) SOFT     (Char) The device/type to be used for graphics
                soft plots.  See the SOFT command for details.
                The device must support a cursor.
   (>) HARD     (Char) The device/type for graphics hard plots.
  
   Input -
  
   As named     May use the lines from a previous run.  If so
   by ARFILE    these are read from the previous run’s output
                file.  See below.
  
   Output -
  
   ARLINES.ECH  File containing the lines used in the final fit.
                Format is as follows -
                Number of lines used in fit (I5)
                1 blank record, then one header record.
                Then one record for each line, giving order, channel
                number, wavelength, calculated wavelength, wavelength
                discrepancy, line number and auto flag (I3,4F13.4,I7,A4)
                The auto flag is either " (A)" for a single order Auto
                fit, " (E)" for complete echelle order auto fit, or is
                a blank string for lines explicitly identified by user.
                Then one blank record, then a record giving the RMS
                error and the value of SIGMA used (12X,F10.2,19X,F5.2)
                Then one blank record, then one record giving the
                number of coefficients of the fit (15X,I3).
  
   Functions / subroutines used -
  
   ECH_ARINTR  (FIGARO)  Plots an order section by section and
                         allows user to identify lines, fit a
                         polynomial to those lines, and repeat.
                         When an order is finished, the lines
                         identified within it are written to
                         the file ARLINES.ECH in case of problems
                         during the fit to the next order.
   ECH_ARGETL  (FIGARO)  Reads order, channel, wavelength, etc.,
                         information from an existing ARLINES.ECH
                         -format file to use as a starting point
                         for fits to the current order.
  
   Originally  ARC :                             KS / CIT 13 Jun 1984
   Stolen & Modified --> ECHARC0:               JKM / CIT  9 Dec 1986
   Modified:         --> ECHARC:  v. 1.0        JKM / ESO 18 Nov 1987
   Modified:         --> ECHARC:  v. 1.5        JKM / ESO  8 Dec 1987

D.57 ECHFIND-Locate spectra in echelle data

Description:
Find orders within an echelle image and optionally write a mask image that can be used for quick-look extraction of orders from a raw echelle image.
Parameters:
IMAGE
Name of echelle image in which to search.
PERISCOPE
Is the periscope fitted?
YSTART
Y value to start search for orders.
YEND
Y value to stop search for orders.
MSTART
Number of the first order in range.
MDELTA
Order number increment (-1 or +1).
SDIST
Write output file SDIST.DAT in SDIST format?
OUTFILE
Name of output report file.
THRESH
Threshold above which orders are deemed to exist.
MINHW
Minimum half-width of orders.
DOMASK
Create an output mask image?
OUTPUT
Name of mask image showing order positions.
Source comments:
   E C H F I N D
  
   Program name:
      ECHFIND
  
   Function:
      Find orders within an echelle image and optionally write a mask
      image that can be used for quick-look extraction of orders from a
      raw echelle image.
  
   Description:
      Note: This program is believed to work, but it has not been as
      extensively used and tested as has the ICUR/SDIST method.
      ICUR/SDIST is believed to be a superior if slightly less
      convenient way of locating and tracking orders. Having said this,
      you are welcome to try this program!
  
      The program can be run in several different ways. The SDIST
      keyword controls whether an SDIST.DAT file (which can later be
      used by CDIST) is created and the DOMASK keyword controls whether
      a mask image (that can later be applied by MASKEXT) is created.
  
      The program locates the orders by taking a vertical cut (i.e. in the
      cross-dispersion direction) through the data (averaging 7 columns)
      and then searches for peaks occurring above a user-specified
      threshhold.  Unfortunately this threshhold has to be a constant
      and this, plus knowing a sensible value to give for it, is one of
      the major limitations of the program.
  
      Having located the orders, they are tracked using a method that is
      a combination of edge detection and centroiding. Little of the
      feedback and control that is available with SDIST is available and
      this is another major problem.
  
      Having tracked the orders, the SDIST.DAT file is written if
      requested.  If an SDIST.DAT file is not required, a more
      user-readable listing file is written. Finally, the mask image is
      written if requested.  The values in the mask are set to be zero
      if that pixel in the mask does not lie in an order and to a number
      derived from the order number otherwise (see below). It is
      guaranteed that every order is extracted using the same number of
      rows, but of course the position of these rows may vary along an
      order so one can expect visible jumps in the extracted data,
      especially if too fews rows are extracted to take all the data
      from the object.
  
      The PERISCOPE keyword (see below) determines whether each order
      has two separate parts (corresponding to object and sky and due to
      the special periscope that samples object and sky at a wide
      spacing and brings them together on the slit) or one part
      (corresponding simply to the slit).  The data values in the mask
      are 10 * (true order number) + (sub-order number) where the
      sub-order number is 0 if there is no periscope fitted, 1 if this
      is the first part of an order and 2 if this is the second part of
      the order. The "first" and "second" parts of an order are defined
      so that the actual data values in the mask are monotonic along a
      vertical slice through it, i.e. they might go 412, 411, 402, 401 if
      the periscope is fitted and they might go 410, 400 if it is not
      fitted.
  
      If PERISCOPE is NO, then unlike in ECHMASK, the user has no
      option of splitting the data in an order into object and sky.
      There is room for enhancement here.
  
   Parameters:
  
      (>) IMAGE         (File) The name of the raw echelle image.
      (>) YSTART        (Integer) The starting and ending Y positions to
      (>) YEND          (Integer) search for orders. Default entire image.
      (>) PERISCOPE     (Keyword) Whether or not the periscope is fitted.
                        Default YES.
      (>) MSTART        (Integer) The order number of the first
                        "spectrum" in the coefficient file. Default 1.
      (>) MDELTA        (Integer) +1 if order numbers increase as
                        "spectrum number" increased, -1 otherwise.
                        Default -1.
      (>) SDIST         (Keyword) Whether to write an SDIST.DAT file.
                        Default NO.
      (>) OUTFILE       (Character) If SDIST is NO, the name of the
                        listing file.
      (>) THRESH        (Real) The threshhold above which peaks in the
                        profile across the orders must lie in order to
                        be considered as order peaks. Default 1000.
      (>) MINHW         (Integer) The half width that is used for the
                        median filter that is passed through the
                        profiles to remove rogue data before looking for
                        orders. Default 5.
      (>) DOMASK        (Keyword) Whether to write a mask image. Default
                        NO.
      (<) OUTPUT        (File) If DOMASK is YES, the name of the mask
                        image. Default MASK.
  
   Language:
      FORTRAN
  
   External variables used:
  
      None
  
   Prior requirements:
      None
  
Authors:
William Lupton, AAO

D.58 ECHMASK-Produce an extraction mask from an SDIST analysis

Description:
The program reads a file that identifies where the orders are in the image and sets the values in the mask to be zero if that pixel in the mask does not lie in an order and to a number derived from the order number otherwise (see below). It is guaranteed that every order is extracted using the same number of rows, but of course the position of these rows may vary along an order so one can expect visible jumps in the extracted data, especially if too fews rows are extracted to take all the data from the object.

The coefficient file will normally have been written by SDIST and if so must have been written by the version of SDIST that was modified to support ECHMASK.

The PERISCOPE keyword (see below) determines whether each order has two separate parts (corresponding to object and sky and due to the special periscope that samples object and sky at a wide spacing and brings them together on the slit) or one part corresponding simply to the slit). The data values in the mask are 10 * (true order number) + (sub-order number) where the sub-order number is 0 if there is no periscope fitted, 1 if this is the first part of an order and 2 if this is the second part of the order. The "first" and "second" parts of an order are defined so that the actual data values in the mask are monotonic along a vertical slice through it, i.e. they might go 412, 411, 402, 401 if the periscope is fitted and they might go 410, 400 if it is not fitted.

If PERISCOPE is NO then the user has the option of splitting the data in an order into object and up to two separate regions of sky. The object is assigned sub-order 1 and the sky is assigned sub-order 2. Note that this assignment may differ from when PERISCOPE is yes, since in that case there is no guarantee that sub-order 1 is object - it may be sky! There may be room for enhancement here.

Parameters:
COFILE
The name of the file that contains details of where the orders lie within the raw input image. It will normally have been created by SDIST. Note that it is necessary to use a version of SDIST that has been specially modified to write details of the dimensions of the input image and of the widths of the orders.
PERISCOPE
It is possible to fit a periscope to the spectrograph that collects object and sky light from widely separated areas of the sky and brings them together in a single order separated by at least one blank row. If the periscope is fitted the program must be told so that it knows that each order actually looks like two orders in the raw data. When the periscope is fitted it is the user’s responsibility to ensure that the first two "orders" listed in the coefficient file are indeed an object / sky pair. If this is not obvious, look at an arc image.
OBJWIDTH
The same number of rows will be extracted from each order. This is necessary to preserve counts in the extracted echell- ograms. You can either specify the number explicitly or else specify zero, in which case a sensible number will be derived from the information in the coefficient file - assuming that there are enough orders, the width of the third widest will be used. In this casem if a non-zero value for OBJOFFSET is spec- ified, twice this value will be extracted from OBJWIDTH so as to ensure that the extracted rows lie within the order.
OBJOFFSET
The centre of the order corresponds to the centre of the slit. If the object is not centred on the slit, you can specify an offset (which is a floating point number) from the centre. A positive offset corresponds to a higher Y value (i.e. a position further up the image when displayed in conventional orientation).
S1WIDTH
Up to two regions of sky can be defined. Each is defined in a similar manner to the object except that the offset is an off- set from the centre of the object and not from the centre of the order.
S1OFFSET
Up to two regions of sky can be defined. Each is defined in a similar manner to the object except that the offset is an off- set from the centre of the object and not from the centre of the order.
S2WIDTH
Up to two regions of sky can be defined. Each is defined in a similar manner to the object except that the offset is an off- set from the centre of the object and not from the centre of the order.
S2OFFSET
Up to two regions of sky can be defined. Each is defined in a similar manner to the object except that the offset is an off- set from the centre of the object and not from the centre of the order.
MSTART
This is the order number of the first order whose fit is listed in the coefficient file. Conventionally this should be the order with the smallest Y value and is the order with the highest order number.
MDELTA
This is the increment to the order number as the orders listed in the coefficient file are processed. Conventionally, if the first order is that with the lowest Y value, the increment will be -1.
MASK
This file will be created and will have the same dimensions as the raw input image. Areas where there are no orders will have zero data values and areas that are deemed to lie within an order will have a data value of 10 * (order number) + sub-order number) where "sub-order number" is 1 or 2. When the periscope is fitted the sub-order number is 2 for the first "order" of each pair and 1 for the second one. Otherwise it is always 1 for object and 2 for sky. The MASKEXT program can be used to generate an exhellogram from this mask and the raw input image and it permits selection of which sub-orders to extract (one, the other or both).
Source comments:
   E C H M A S K
  
   Program name:
      ECHMASK
  
   Function:
      Write a mask image that can be used for quick-look extraction of
      orders from a raw echelle image.
  
   Description:
      The program reads a file that identifies where the orders are in
      the image and sets the values in the mask to be zero if that pixel
      in the mask does not lie in an order and to a number derived from
      the order number otherwise (see below). It is guaranteed that
      every order is extracted using the same number of rows, but of
      course the position of these rows may vary along an order so one
      can expect visible jumps in the extracted data, especially if too
      fews rows are extracted to take all the data from the object.
  
      The coefficient file will normally have been written by SDIST and
      if so must have been written by the version of SDIST that was
      modified to support ECHMASK.
  
      The PERISCOPE keyword (see below) determines whether each order
      has two separate parts (corresponding to object and sky and due to
      the special periscope that samples object and sky at a wide
      spacing and brings them together on the slit) or one part
      (corresponding simply to the slit).  The data values in the mask
      are 10 * (true order number) + (sub-order number) where the
      sub-order number is 0 if there is no periscope fitted, 1 if this
      is the first part of an order and 2 if this is the second part of
      the order. The "first" and "second" parts of an order are defined
      so that the actual data values in the mask are monotonic along a
      vertical slice through it, i.e. they might go 412, 411, 402, 401 if
      the periscope is fitted and they might go 410, 400 if it is not
      fitted.
  
      If PERISCOPE is NO then the user has the option of splitting
      the data in an order into object and up to two separate regions of
      sky. The object is assigned sub-order 1 and the sky is assigned
      sub-order 2. Note that this assignment may differ from when
      PERISCOPE is yes, since in that case there is no guarantee that
      sub-order 1 is object - it may be sky!  There may be room for
      enhancement here.
  
   Parameters:
  
      (>) COFILE        (Character) The name of the coefficient file.
                        Default SDIST.
      (>) PERISCOPE     (Keyword) Whether or not the periscope is fitted.
                        Default YES.
      (>) OBJWIDTH      (Integer) The number of rows to be extracted on
                        behalf of the object per order.  If PERISCOPE is
                        YES then object and sky are not distinguished
                        between and this width also applies to the sky.
                        If PERISCOPE is NO then this width applies
                        only to the object and the position of the sky
                        is specified using the S1* and S2* parameters.
                        If OBJWIDTH is specified as zero then the width
                        information from the coefficient file is used to
                        derive a sensible value. Default 0.
      (>) OBJOFFSET     (Float) The offset of the centre of the object
                        data from the centre of each order. If specified
                        as being non-zero and if OBJWIDTH is zero, the
                        derived width is adjusted to take account of the
                        offset. Default 0.
      (>) S1WIDTH       (Integer) The number of rows to be extracted on
                        behalf of the first region of sky per order.
                        This and the other S* parameters are prompted
                        for only if PERISCOPE is NO. If specified as
                        zero, it is assumed that no sky is to be
                        extracted and the remaining S* parameters are
                        not prompted for. Default 0.
      (>) S1OFFSET      (Float) The offset of the centre of the first
                        region of sky from the centre of the object data
                        (not necessarily from the centre of the order).
                        Default 0.
      (>) S2WIDTH       (Integer) These parameters are the same as
      (>) S2OFFSET      (Float)   S1WIDTH and S2OFFSET but they refer to
                                  the second region of sky if any.
                                  Defaults 0.
      (>) MSTART        (Integer) The order number of the first
                        "spectrum" in the coefficient file. Default 1.
      (>) MDELTA        (Integer) +1 if order numbers increase as
                        "spectrum number" increased, -1 otherwise.
                        Default -1.
      (<) MASK          (File) The name of the output mask image. This
                        is created with only a .Z.DATA structure.
                        Default MASK.
  
   Language:
      FORTRAN
  
   External variables used:
      None
  
   Prior requirements:
      None
  
Authors:
William Lupton, AAO

D.59 ECHMERGE-Merge echelle spectra into a single long spectrum

Description:
The program expects two input files, each of which may be 1-D or 2-D, but both of which must have the same number of pixels in X, must have a recognised wavelength unit as the units of X and must have (near enough) identical .X.DATA arrays. In practice this means that both must have been scrunched on to the same wavelength scale. (The details of this may change when SCRUNCH has been upgraded to write an output file with a 2-D .X.DATA array describing the discontinuous scrunched orders.)

It creates a 1-D output file which consists of all the orders from the input files. Where orders overlap a weighted sum of the overlapping orders is used. The formula used is:

in1weight(i) * in1(i) + in2weight(i) * in2(i) in1weight(i) + in2weight(i)

and the weights are simply the result of median smoothing the data that they weight. This means that more weight is given to stronger signal data, that data where one of the inputs is zero is set to the other of the inputs and that data where both of the inputs are equal is left unaltered. All of these are desirable qualities. There may be less desirable statistical consequences and it is not obvious that signal to noise ratio cannot be degraded although intuitively it will not be since on the assumption of Poisson statistics the weights are essentially just the inverse variances. At low signal, a cutoff applies since the major noise contribution will no longer be Poisson.

The output file can be the same as either of the two input files and the second input file can be given a blank name, in which case it is not required. Often the first run will use a single input file to create the output file and subsequent runs will add in more input files to the existing output file.

Parameters:
IMAGE
ECHMERGE merges one or two images that contain scrunched echelle orders. The images must have the same size in the X direction but each may be 1-D or 2-D.
IMAGE1
The name of the image that is to be merged with IMAGE. A blank name can be given.
BOX
The input and output data is smoothed (in workspace) in order to provide slowly varying data from which to derive weights. This is the total width of the median filter used. An even value is rounded down to the next odd number.
CUTOFF
If the ration (stronger signal)/(weaker signal) exceeds CUTOFF, only the stronger signal will be used. This is an attempt to prevent signal to noise degradation due to adding in of weak signal.
OUTPUT
The name of the resulting image. The output image is a single long spectrum containing the merged orders from IMAGE and IMAGE1.
Source comments:
   E C H M E R G E
  
   Program name:
      ECHMERGE
  
   Function:
      Merge scrunched echelle orders into a single long spectrum.
  
   Description:
      The program expects two input files, each of which may be 1-D or
      2-D, but both of which must have the same number of pixels in X,
      must have a recognised wavelength unit as the units of X and must
      have (near enough) identical .X.DATA arrays. In practice this
      means that both must have been scrunched on to the same wavelength
      scale. (The details of this may change when SCRUNCH has been
      upgraded to write an output file with a 2-D .X.DATA array
      describing the discontinuous scrunched orders.)
  
      It creates a 1-D output file which consists of all the orders from
      the input files. Where orders overlap a weighted sum of the
      overlapping orders is used. The formula used is:
  
                     in1weight(i) * in1(i) + in2weight(i) * in2(i)
                              in1weight(i) + in2weight(i)
  
      and the weights are simply the result of median smoothing the data
      that they weight. This means that more weight is given to stronger
      signal data, that data where one of the inputs is zero is set to
      the other of the inputs and that data where both of the inputs are
      equal is left unaltered. All of these are desirable qualities.
      There may be less desirable statistical consequences and it is not
      obvious that signal to noise ratio cannot be degraded although
      intuitively it will not be since on the assumption of Poisson
      statistics the weights are essentially just the inverse variances.
      At low signal, a cutoff applies since the major noise contribution
      will no longer be Poisson.
  
      The output file can be the same as either of the two input files
      and the second input file can be given a blank name, in which case
      it is not required. Often the first run will use a single input
      file to create the output file and subsequent runs will add in
      more input files to the existing output file.
  
   Parameters:
  
      (>) IMAGE    (File) The name of the first input image. This can be
                   1-D or 2-D and will normally be the output from
                   SCRUNCH.  However it can also be the results of a
                   previous run of this program.
      (>) IMAGE1   (File) The name of the second input image. This can
                   be 1-D or 2-D and will normally be the output from
                   SCRUNCH. However it can also be the results of a
                   previous run of this program. It must have the same X
                   size as IMAGE, must agree in X units (which must be
                   a recognised wavelength unit) and must more or less
                   agree in the contents of .X.DATA. If no second
                   input image is required, its name can be specified
                   as blank.
      (>) BOX      (Integer) The size of the box (in pixels) to be used
                   in calculating the medians.  Should be odd; if even,
                   BOX-1 will be used.
      (>) CUTOFF   (Real) The ratio of higher signal to lower signal at
                   which no contribution from the lower signal will be
                   taken.
      (<) OUTPUT   (File) The name of the output image. This will be
                   a 1-D image with the same size and X information as a
                   row of either of the input images.
  
   Language:
      FORTRAN
  
   External variables used:
  
      None
  
   Prior requirements:
      None
  
Authors:
William Lupton, AAO

D.60 ECHSELECT-Interactive selection of sky and object spectra for an echelle

Description:
ECHSELECT allows the user to indicate interactively the cross-sections of a corrected echellogram (one straightened by CDIST for example) to be used as object and sky for the various orders. It then creates a collapsed echellogram for the object orders, and (optionally) one for the sky orders.
Parameters:
IMAGE
IMAGE is used to specify the corrected echellogram to be processed by ECHSELECT. It should have its orders straight and parallel to the x-axis (i.e. as processed by CDIST).
PREVIOUS
If PREVIOUS is selected, the results of a previous selection are read from a file called ECHSELECT.LIS in the default directory and may be modified. Otherwise, you start from a clean slate. Note that this allows you to apply a selection based on one image to data in another - for example you can process an arc according to the selection made using an associated object exposure.
WHOLE
ECHSELECT gets you to select cross-sections by indicating them on a plot of a 1-D cut through the original image. This cut is orthogonal to the wavelength direction, so the various orders should show up as peaks in the plot. Often, the ends of the image have odd effects and should not be included in this cut. If you want to specify the limits of the plot explicitly, set WHOLE to NO. Otherwise the whole image will be summed to produce the cut.
XSTART
If WHOLE is not selected, XSTART gives the x-axis value for the first of the cross-sections to be summed to give the cut through the image
XEND
If WHOLE is not selected, XEND gives the x-axis value for the last of the cross-sections to be summed to give the cut through the image
MSTART
This is the order number of the first order in IMAGE. Getting this right is unimportant, since you have to option of setting the order numbers explicitly during ECHSELECT.
MDELTA
This is the increment to the order number as the orders listed in the coefficient file are processed. Conventionally, if the first order is that with the lowest Y value, the increment will be -1. Note that the order in which the orders appear in the collapsed echellogram depends on the sign of MDELTA.
OBJOUT
Once the cross-sections for each order are selected, ECHSELECT sums those for each order to produce the collapsed echellograms. Those selected for the object go into one, whose name is given by OBJOUT, and those for the sky into another. The object cross-sections for each order are simply summed into one cross-section of OBJOUT. The order in which the orders appear in the collapsed echellograms depends on MDELTA - if MDELTA is -1, higher orders are at lower cross-section numbers.
SKYOUT
Once the cross-sections for each order are selected, ECHSELECT sums those for each order to produce the collapsed echellograms. Those selected for the object go into one, those for the sky into another whose name is given by SKYOUT. The sky cross-sections for each order are summed into one cross-section of SKYOUT, but are scaled to match the number of object cross-sections for the same order. This should allow the two collapsed echellograms to be directly subtracted.
DISNCHAN
Length of displayed section.
MOVETOX
New plot centre x value.
ORDER
Next echelle order to work on.
LOW
Minimum value to display.
HIGH
Maximum value to display.
ADD
Used to confirm that more than one cross section are to be used for an order’s object.
CLEAR
Used to confirm that all settings for an order to be cleared.
QUITSEL
Used to confirm quitting work on an echelle order.
Source comments:
   E C H S E L E C T
  
   Routine name:
      ECHSELECT
  
   Function:
      Interactive object and sky selection from echellogram.
  
   Description:
      This application takes a corrected echellogram (one that has had
      the orders straightened, probably by CDIST), and generates a
      number of collapsed echellograms (images where each cross-section
      is a separate echelle spectrum).  To determine which cross-sections
      should be added to produce the sky and object spectra it gets the
      user to indicate the relevant limits on a plot of the corrected
      echelogram collapsed in the spectra direction.  For each order
      the user can select a range of cross-sections to be used for the
      object, and a number of ranges of cross-sections to be used for
      the sky.  For each order, the object cross-sections are added
      and the sky cross-sections are added and then scaled by the
      factor (number of object cross-sections / number of sky cross
      sections).  The object cross-sections are formed into one collapsed
      echellogram and the sky cross-sections are formed into another
      collapsed echellogram.  Optionally, a straightened arc can also
      be processed using the same object and sky cross-section information,
      in this case producing two collapsed arc echellograms, one for the
      cross-sections designated as object, one for those designated as
      sky, but in this case without any scaling being applied.
  
   Command parameters:
      IMAGE       (File) The name of the corrected echellogram.
      XSTART      (Numeric) The first x-value to be used when collapsing
                  the image along the wavelength direction.
      XEND        (Numeric) The last x-value to be used when collapsing
                  the image along the wavelength direction.
      MSTART      (Integer) The order number for the first order.
      MDELTA      (Integer) 1 if order numbers increase with cross-
                  section, -1 if they decrease.
      OBJOUT      (File) The name of the object collapsed echellogram.
      SKYOUT      (File) The name of the sky collapsed echellogram.
      DISNCHAN    (Integer) Length of displayed section.
      MOVETOX     (Numeric) New plot centre x value.
      ORDER       (Integer) Next echelle order to work on.
      LOW         (Numeric) Minimum value to display.
      HIGH        (Numeric) Maximum value to display.
  
   Command keywords:
      WHOLE       Yes if all of spectral range is to be used
      PREVIOUS    Yes if previous selection is to be used as a starting
                  point for the interactive selection.
      ADD         Used to confirm that more than one cross section are
                  to be used for an order’s object.
      CLEAR       Used to confirm that all settings for an order to be
                  cleared.
      QUITSEL     Used to confirm quitting work on an echelle order.
  
   Data quality information:  Ignored.
  
   Error data: Ignored.
  
   Authors: Keith Shortridge, AAO
  
   Files:
      Selections made by ECHSELECT are written to ECHSELECT.LIS in the
      default directory.  This begins with a number of comment lines -
      all of which have an ’*’ in the first column, and is then followed
      by a single line for each cross-section which has been selected,
      giving cross-section number and order number, in format 2I10.
      If the cross-section is part of the sky selected for that order,
      the order number given is the negative of the actual order number.
      (Note that this program cannot cope with zeroth order!).  This
      file is also that read if PREVIOUS is set.

D.61 EDITEXT-Edit the Specdre Extension.

Usage:

editext request in

Description:

This routine allows the user to modify the Specdre Extension. See the topic "Requests" for details. Users should also consult the description of the Specdre Extension in SUN/140.

Parameters:
REQUEST
REQUEST = _CHAR (Read) The action required. This consists of blank separated words. The following is a brief reminder of the syntax and permissible requests. For the full details refer to the "Requests" topic.

- LIST - CREATE - CREATE RESULTS type1 type2 type3 int1 int2 - DELETE - DELETE struct - SET ndf-struct - SET SPECVALS.comp value - SET COORD1.comp value - SET COORD2.comp value - SET scalar value - SET vector element value - TYPE scalar type - TYPE ndf-struct type - TYPE RESULTS type1 type2 type3 - SHAPE RESULTS int1 int2

IN
IN = NDF (Read) The NDF the Specdre Extension of which is to be modified. The modification is done in situ, i.e. there is no separate output NDF. In most modes, the routine requires update access. Only in list mode is read access sufficient.
LOGFIL
LOGFIL = FILENAME (Read) The filename for the ASCII output file in list mode. If this file exists, it is opened for append access. A null value for this parameter will signal that no file is to be used. The output will then be directed to the standard output device (the user’s screen). [!]
Examples:
  editext list in accept
     This will look for the Specdre Extension to the main NDF called IN
     and list the Extension’s contents to the default output device
     (usually the user’s screen). Some character strings that may be
     up to 32 characters long are truncated to 16 characters in
     order to fit on the screen.
  
  editext list in logfil=out
     This will look for the Specdre Extension to the main NDF called IN
     and list the Extension’s contents to the ASCII file out.
     This happens without string truncation.
  
  editext delete in
     This will look for the Specdre Extension to the main NDF called IN
     and delete the Extension.
  
  editext "set restframe heliocentric" in
     This will access the main NDF called IN, find or create its Specdre
     Extension, find or create the RESTFRAME structure in the
     Extension, and put the string "heliocentric" into the RESTFRAME
     structure.
  
  editext "set frequnit 6"
     This will access the main NDF called IN, find or create its Specdre
     Extension, find or create the FREQUNIT structure in the
     Extension, and put the value 6 into the FREQUNIT structure.
     This is to mean that reference and laboratory frequencies will
     be expressed in MHz (10**6 Hz).
  
  editext "set labfreq 5 1420" in
     This will access the main NDF called IN, find its Specdre Extension
     and find the RESULTS structure in the Extension (which is an
     NDF). If this is successful the routine will find the LABFREQ
     extension of the result NDF and set its fifth element to 1420.
     This is the laboratory frequency of the fifth spectral
     component. In conjunction with a FREQUNIT of 6, this is
     (very roughly) the frequency of the 21 cm ground state
     hyperfine transition of neutral atomic hydrogen.
  
  editext "set npara 5 3" in
     This will access the main NDF called IN, find its Specdre Extension
     and find the RESULTS structure in the Extension (which is an
     NDF). If this is successful the routine will find the NPARA
     extension of the result NDF and set its fifth element to 3.
     This is to mean that the fifth spectral component is allocated
     space for three parameters in the result NDF. Changing this
     number may require to increase the total number of parameters
     which in turn affects the shape of the result NDF and of the
     PARATYPE extension to the result NDF. Changing NPARA(5) also
     makes it necessary to shift information in the result NDF’s
     data and variance structures as well as in the PARATYPE
     extension to the result NDF. All this is handled consistently by
     this routine.
  
  editext "shape results 6 20" in
     This will access the main NDF called IN, find or create its Specdre
     Extension, find or create the RESULTS structure in the
     Extension, and shape it to provide for six spectral components
     and a total of 20 parameters. If results existed before, it
     will be expanded or contracted "at the end". That is, existing
     components 1 to 6 and parameter 1 to 20 would be retained.
Notes:
This routine recognises the Specdre Extension v. 1.1.

This routine works in situ and modifies the input file.

Requests:
The request or action required consists of blank-separated words. The first word is a verb specifying the kind of action. The verb can be LIST, CREATE, DELETE, SET, TYPE or SHAPE. The verb is case-insensitive. The length of the request is restricted to 130 characters.

There may or may not follow a second word specifying the structure affected. This can be any of the scalar structures in the Specdre Extension, i.e. SPECAXIS, RESTFRAME, INDEXREFR, FREQREF, FREQUNIT. It can also be any of the NDF-type structures in the Specdre Extension, i.e. SPECVALS, SPECWIDS, COVRS, RESULTS. Finally it can be any structure which is an extension to the (NDF-)structure RESULTS. These latter structures are all HDS vectors, their names are LINENAME, LABFREQ, COMPTYPE, NPARA, MASKL, MASKR, PARATYPE. The structure specification is case-insensitive.

Further words contain parameter values, usually one word per parameter. But if the last parameter is a string, it may consist of several words. No quotes are necessary.

There is only one LIST request, namely the sole word LIST. This will cause the complete Specdre Extension - except the contents of NDF arrays - to be listed to the log file or to the screen.

There are two possible CREATE requests.

- "CREATE" on its own will create an empty Specdre Extension, or fail if a Specdre Extension already exists.

- "CREATE RESULTS type1 type2 type3 int1 int2" needs five parameters. Three parameters are case-insensitive HDS data types. These are either _DOUBLE or assumed to be _REAL. The result structure is an NDF-type structure and the different type specifications apply to (i) the data and variance structures of the NDF, (ii) the laboratory frequency extension to the result NDF, (iii) the left and right mask extensions to the result NDF. All extensions to the result NDF are HDS vectors. Some of these have one element for each spectral component, their created length is specified by the fourth (last but one) request parameter, i.e. the sixth word. This word must convert to an integer greater than zero. Other HDS vectors in the extension to the result NDF have one element for each result parameter, their created length is specified by the fifth (last) request parameter, i.e. the seventh word. This word must convert to an integer greater than zero. "CREATE RESULTS" fails if the result NDF already exists.

"DELETE" on its own will delete the whole Specdre Extension. "DELETE struct" will delete the specified structure. This can be any of the NDF-type structures SPECVALS, SPECWIDS, COORD, COVRS, RESULTS. Deleting a structure does not include deleting the whole Extension, even if it becomes empty.

All SET request will create the Specdre Extension, even if the request is not recognised as a valid one.

"SET ndf-struct", where the second word specifies an NDF-type structure, will set the values of the specified structure to the default values. This does not work for COVRS, since it defaults to non-existence. The structure is created if it does not already exist. For SPECVALS and SPECWIDS only the NDF’s data structure is affected. For RESULTS the NDF’s data and variance structures are set to bad values, but all the vectors in the result NDF’s extension remain unchanged.

- "SET SPECVALS" will set the values in the data array of spectroscopic values to the default values. These are copies of the spectroscopic axis centres in the main NDF.

- "SET SPECWIDS" will set the values in the data array of spectroscopic widths to the default values. These are copies of the spectroscopic axis widths in the main NDF.

- "SET COORD" will set the values in the data array of COORD1 and COORD2 to the default values. These are copies axis centres for the first and second non-spectroscopic axes in the main NDF.

- "SET RESULTS" will set the values in the data and variance arrays of the result NDF to bad values.

"SET SPECVALS.comp value" can be used to set the label and unit components of the spectroscopic values’ NDF.

- "SET SPECVALS.LABEL label" will set the value of the label of the spectroscopic values’ NDF.

- "SET SPECVALS.UNITS unit" will set the value of the unit of the spectroscopic values’ NDF.

- "SET COORD1.LABEL label1" will set the value of the label of the COORD1 NDF. Similarly for COORD2.

- "SET COORD1.UNITS unit1" will set the value of the units of the COORD1 NDF. Similarly for COORD2.

"SET scalar value" will convert the third word to a value and put it in the scalar structure specified by the second word.

- "SET SPECAXIS int" will try to convert the third word into an integer. It must be between 1 and the number of axes in the NDF to which this Specdre Extension is an extension. If the value is actually changed, then this command will also delete the NDF-type structures SPECVALS, COVRS and RESULTS. This is because the contents of those structures depends on the choice of spectroscopic axis and become invalid when the value is changed. This command will also create the Specdre Extension and spectroscopic axis structure if they do not yet exist.

- "SET RESTFRAME more words" will put the third and following words (case-sensitive) into the reference frame structure. This command will also create the Specdre Extension and reference frame structure if they do not yet exist.

- "SET INDEXREFR value" will try to convert the third word into a real or double value, depending on the current type of the refractive index structure. This command will also create the Specdre Extension and refractive index structure if they do not yet exist.

- "SET FREQREF value" will try to convert the third word into a real or double value, depending on the current type of the reference frequency structure. This command will also create the Specdre Extension and reference frequency structure if they do not yet exist.

- "SET FREQUNIT int" will try to convert the third word into an integer. This command will also create the Specdre Extension and frequency unit structure if they do not yet exist.

"SET vector element value" will change the value of the specified element in the specified vector. The vector must be one of the extensions of the result NDF. The result NDF must exist beforehand, which implies the existence of the vector. The vector must also be long enough to contain the element specified and the element number must be integer and greater than zero. There are two kinds of vectors, those indexed by spectral component and those indexed by result parameter.

- "SET LINENAME comp more words" will put the forth and following words (case-sensitive) into the comp-th element of the line name structure.

- "SET LABFREQ comp value" will try to convert the fourth word into a real or double value, depending on the current type of the laboratory frequency structure. It will then put the value into the comp-th element of the laboratory frequency structure.

- "SET COMPTYPE comp more words" will put the forth and following words (case-sensitive) into the comp-th element of the component type structure.

- "SET NPARA comp npara" will try to convert the fourth word into an integer greater than or equal to zero. This is the new number of parameters allocated to the comp-th component. Changing this value will affect several parts of the result structure both in their shapes and values. If the comp-th spectral component is allocated more parameters than before, then it may be necessary to provide for a higher total number of parameters, which implies increasing the size of .MORE.SPECDRE.RESULTS.DATA_ARRAY and VARIANCE and of .MORE.SPECDRE.RESULTS.MORE.PARATYPE. At any rate, the information about spectral components with indices higher than comp must be relocated within those arrays.

- "SET MASKL comp value" and "SET MASKR comp value" will try to convert the fourth word into a real or double value, depending on the current type of the mask structures. It will then put the value into the comp-th element of the relevant mask structure.

- "SET PARATYPE para more words" will put the forth and following words (case-sensitive) into the para-th element of the parameter type structure.

A TYPE request can be applied to _REAL or _DOUBLE structures, and of these to scalars and NDF-type structures. Changing the type(s) of the result NDF needs specification of three separate types.

- "TYPE scalar type" can be applied to INDEXREFR and FREQREF. The type specification is case-insensitive. If it is not _DOUBLE, then _REAL is assumed.

- "TYPE ndf-struct type", will change the type of the specified NDF. The type specification is case-insensitive. It must be _DOUBLE or is assumed to be _REAL. This command can be applied to SPECVALS, SPECWIDS, COORD, and COVRS. SPECVALS, SPECWIDS, COORD1 and COORD2 will be created if necessary, COVRS will not be created.

- "TYPE RESULTS type1 type2 type3" will change the types of (i) the NDF’s data and variance, (ii) the NDF’s laboratory frequency extension, (iii) the NDF’s mask extensions. the parameters are case-insensitive. They must be _DOUBLE or are assumed to be _REAL. This command includes creation of the result structure if necessary.

"SHAPE RESULTS int1 int2" will change the shape of the result structure. The two command parameters must convert to integers greater than zero. The first is the number of spectral components to be provided for, the second is the total number of parameters. If the result structure does not exist, then it is created. If it exists, then existing values are retained unless they were stored outside the new bounds.

D.62 ELSPLOT-Produces a long (<3m) error bar plot of a spectrum

Description:
ELSPLOT produces an error bar plot of a spectrum with a physical size that can be specified (in metres) by the user. It will allow plots up to the maximum size allowed by the GKS driver being used - in some cases this means that a non-standard device name must be specified in order to allow a larger maximum size than usual. ELSPLOT is very similar to ESPLOT, except that it has plot dimension parameters and does not support build plots.
Parameters:
SPECTRUM
The name of the spectrum to be plotted by ELSPLOT It should be a 1-dimensional array.
XSIZE
The length of the plot in metres. ELSPLOT can produce plots up to 10 metres in length.
YSIZE
The height of the plot in metres. The reset value is the full page height for the device.
WHOLE
If WHOLE is set, the whole of the spectrum is plotted. Otherwise, the limits plotted are determined by the values of XSTART and XEND, which you will be prompted for if they were not specified in the command string.
AUTOSCALE
If AUTOSCALE is set, the plot is scaled so that all of the data to be plotted just fits on the display. Otherwise, the scale of the plot is determined by the values of HIGH and LOW, which you will be prompted for if they were not specified in the command string.
XSTART
Specifies the first X value to be plotted, in the units used by the data - angstroms, for example, if the data is wavelength calibrated. XSTART can be set before the start of the data, if necessary. RESET will set XSTART to the first X value in the data.
XEND
Specifies the last X value to be plotted, in the units used by the data - angstroms, for example, if the data is wavelength calibrated. XEND can be set after the end of the data, if necessary. RESET will set XEND to the last X value in the data.
HIGH
The maximum data value to be plotted - i.e. the top Y axis value for the plot.
LOW
The minimum data value to be plotted - i.e. the bottom Y axis value for the plot.
BIAS
A bias value applied to the data, usually to bias up a plot which is to be superimposed upon a previous plot of almost identical data values. This makes the comparison easier. BIAS N is essentially equivalent to setting HIGH and LOW down by an amount N, so can result in unexpected axis values.
LABEL
The label that will appear at the top of the plot.
Source comments:
   L S P L O T    /    E L S P L O T
  
   These are versions of SPLOT and ESPLOT that allow the size of
   the plot to be specified.  LSPLOT produces a plot of a single
   spectrum, while ESPLOT produces an error bar plot of a spectrum
   which has error information.
  
   Command parameters -
  
   XSIZE       The size of the plot in X, in metres.
   YSIZE       The size of the plot in Y, in metres.
   SPECTRUM    The data to be plotted.  If there
               is an x-axis data component this will be used to
               give the x-axis.  If not, the x-axis will just
               have to be the numbers from 1 to n.
   XSTART      The x-value at which plotting is to start.
   XEND        The x-value at which plotting is to end.
               (XSTART and XEND are not required if the
               WHOLE keyword is set.)
   HIGH        The maximum value to be used for the plot.
   LOW         The minimum value to be used for the plot.
   BIAS        A value used to displace the plot - BIAS is
               effectively a value added to the data before
               it is plotted. (It is implemented as a value
               subtracted from both HIGH and LOW.)
               (HIGH,LOW and BIAS are not required if the
               AUTOSCALE keyword is set.)
   LABEL       A label for the plot.
  
   Command keywords -
  
   AUTOSCALE   The program is to work out the values for HIGH
               and LOW, using the maximum and minimum values
               in the data over the specified range.
   WHOLE       The program is to display all of the spectrum.
   LINES       The plot is not done as a histogram, but as
               a ’join the dots’ line plot.  (LSPLOT only)
  
   User variables used:
  
   HARD        (Character) The device used for HARD plots.
  
   Note:
  
   The original version of LSPLOT used GKS 6.2 and the DIAGRAM
   package.  This has now been discontinued, and some of the
   functionality of DIAGRAM (the ability to specify the size of
   the plot in physical units) has appeared in PGPLOT.  This new
   version uses PGPLOT.  It can produce a plot of the specified
   size, BUT only if that size is SMALLER than the default size
   for the device.  In practice, this means that it can only work
   in the way it was intended with ‘unusual’ devices that have
   particularly large default plot sizes (which often need to be set
   up specially for the purpose).
                                       KS / AAO 30th Jan 1984

D.63 EMLT-Fits gaussians to the strongest lines in a spectrum

Description:
Analyses an emission line spectrum (typically an arc), and produces a list of the strongest lines, giving their widths and strengths. Can also produce a synthetic spectrum from the positions, widths and strengths of the fitted lines.
Parameters:
SPECTRUM
Specifies the spectrum whose strongest emission lines are to be fitted. If the data is more than one- dimensional, the analysis is repeated for each cross- section (i.e. spectrum) in the data.
XSTART
Specifies the X-value (wavelength for calibrated data, or pixel number for uncalibrated data) at which the analysis is to start.
XEND
Specifies the X-value (wavelength for calibrated data, or pixel number for uncalibrated data) at which the analysis is to end.
LINES
If LINES is non-zero, it specifies that only the indicated number of strongest lines are to be included in the analysis. If zero, all lines for which a reasonable fit can be obtained are included.
FWHM
If FWHM is zero, the fits performed are unconstrained; that is, the fit determines full width at half maximum for each line independently. If FWHM is non-zero, it specifies a fullwidth at half maximum (in pixels) for each line in the spectrum, and the fit is constrained accordingly.
MOMENTS
If MOMENTS is set, a center of moment analysis is performed (in addition to the gaussian fit) for each line and the results included in the output. This analysis is performed for each line found, not just the LINES strongest lines.
SYNTH
If SYNTH is set, a synthetic spectrum based on the fitted positions, strengths and widths of the lines is generated.
OUTPUT
The name of the resulting synthetic spectrum, if one is to be created.
Source comments:
   E M L T
  
   Figaro version of the original SDRSYS routine EMLT, which analyses
   emission lines in a spectrum, fitting gaussians to the strongest
   lines and logging their positions, widths and centers.  Optionally,
   it will also give line centers using a centre of moment analysis,
   and can also produce a synthetic spectrum generated from the
   positions and widths of the located lines.  Note: Figaro and SDRSYS
   differ in their pixel numbering, Figaro counting from 1 and SDRSYS
   counting from 0, so there will be a discrepancy of 1 between the
   output from the two versions for any pixel number values; wavelength
   values produced by the two should be the same.
  
   Parameters -
  
   SPECTRUM    (Character) The name of the spectrum to be analysed.
   XSTART      (Numeric) The first X-value to be used for the analysis.
   XEND        (Numeric) The last X-value to be used for the analysis.
   LINES       (Numeric) If LINES is zero, all lines that can be
               fitted are listed.  Otherwise, it gives the number of
               lines to be included in the analysis, starting with the
               strongest and cutting off the weaker lines.
   FWHM        (Numeric) If non-zero, all lines fitted are constrained
               to a full width at half maximum of this value - in pixels.
   OUTPUT      (Character) The name of any synthetic spectrum to be
               generated.
  
   Keywords -
  
   MOMENTS     If set, a center of moment analysis is also performed
               on all lines found.
   SYNTH       If set, a synthetic spectrum is generated.
  
   User variables -  (">" input, "<" output)
  
   (<) EMLT_LINES    (Real) Number of lines found.
   (<) EMLT_BIN      (Real array) List of line centres (pixels).
   (<) EMLT_POS      (Real array) List of line centres (wavelength units).
   (<) EMLT_FWHM_BIN (Real array) List of FWHM (pixels).
   (<) EMLT_FWHM_ANG (Real array) List of FWHM (wavelength units).
   (<) EMLT_STREN    (Real array) List of line strengths.
   (<) EMLT_PEAK     (Real array) List of peak heights.
  
                                                KS / AAO  4th March 1988

D.64 ERRCON-Converts percentage error values to absolute values

Description:
At one stage in their development, Figaro routines held error data as percentage values. This was a bad idea, and all the routines were converted to use absolute error values. ERRCON converts a file with percentage errors into one with absolute errors. It should only be needed for old data files written by the old (%) versions of the various Figaro routines.
Parameters:
SPECTRUM
The name of a file that contains an error array whose values are expressed as a percentage of the data values.
OUTPUT
The name of the resulting file, with the error array containing absolute error values. If OUTPUT is the same as SPECTRUM (the default) the operation will be performed in situ. Otherwise a new file will be created.
Source comments:
   E R R C O N
  
   Converts a Figaro file that has an error array containing
   percentage errors into one that has absolute values in the
   error array.  This is needed because of the ill-thought-out
   use of percentage errors at one stage in Figaro.
  
   Command parameters -
  
   SPECTRUM  (Character) The name of the file to be converted.
             This will usually be a spectrum, but data of any
             dimension will be accepted.
  
   OUTPUT    (Character) The name of the resulting file. This
             can be the same as for SPECTRUM. If not, a new
             structure is created, with everything but the error
             array a direct copy of the input.
  
                                    KS / AAO. 21st July 1986

D.65 ESPLOT-Produces an error bar plot of a spectrum

Description:
The ESPLOT command will plot a spectrum on the current hard or soft graphics device, producing an error bar plot.
Parameters:
SPECTRUM
The name of the spectrum to be plotted by ESPLOT. It should be a 1-dimensional array.
HARDCOPY
If HARDCOPY is set, the plot is written to the device defined as the current hardcopy device. Generally, this is a disk file which will then have to printed. If HARDCOPY is not set, the plot will go to the current soft copy device The hard and soft copy devices are specifed using the HARD and SOFT commands respectively. e.g. SOFT /VT
WHOLE
If WHOLE is set, the whole of the spectrum is plotted. Otherwise, the limits plotted are determined by the values of XSTART and XEND, which you will be prompted for if they were not specified in the command string.
AUTOSCALE
If AUTOSCALE is set, the plot is scaled so that all of the data to be plotted just fits on the display. Otherwise, the scale of the plot is determined by the values of HIGH and LOW, which you will be prompted for if they were not specified in the command string.
XSTART
Specifies the first X value to be plotted, in the units used by the data - angstroms, for example, if the data is wavelength calibrated. XSTART can be set before the start of the data, if necessary. RESET will set XSTART to the first X value in the data.
XEND
XEND specifies the last X value to be plotted, in the units used by the data - angstroms, for example, if the data is wavelength calibrated. XEND can be set after the end of the data, if necessary. RESET will set XEND to the last X value in the data.
HIGH
The maximum data value to be plotted, i.e. the top Y axis value for the plot.
LOW
The minimum data value to be plotte, i.e. the bottom Y axis value for the plot.
BIAS
A bias value applied to the data, usually to bias up a plot which is to be superimposed upon a previous plot of almost identical data values. This makes the comparison easier. BIAS N is essentially equivalent to setting HIGH and LOW down by an amount N, so can result in unexpected axis values if it is not accompanied by AXES=NO.
LABEL
The label that will appear at the top of the plot.
ERASE
Specifies that the screen is to be erased before the plot is made. Usually ERASE and AXES will not be set when a plot is superimposed on a previous one.
AXES
Specifies that the axes for the plot are to be drawn. These should be omitted if the plot is being superimposed on a previous one, or sometimes just to save plotting time.
COLOUR
Used to specify the colour for the data to be plotted in. The axes are always plotted in white. The colours allowed are Blue, White, Red, Green, Black, Cyan, Magenta, Yellow. Using Black will have the effect of erasing anything where the data is plotted. This only works on the Grinnell.
THICKNESS
Only used for ’build’ or ’hard’ plots. It is used to increase the thickness of the lines plotted in order to increase legibility, particularly on the Versatec. Generally 1 or 3 is reasonable for the Versatec - depending on how well set up it is at the present, and 1 should be used for other devices.
See also:
FIGARO: IPLOTS, MSPLOT, SPLOT.
KAPPA: LINPLOT, MLINPLOT.
Source comments:
   S P L O T    /    E S P L O T
  
   Produces a plot of a spectrum.  The plot is directed
   to the device defined by the user variables ’SOFT’ and
   ’HARD’, and by the value of the command keyword ’HARDCOPY’,
   so will appear immediately if these specify a video
   device (VT125, Args, etc.).  If a hardcopy device
   is specified, the file for that device will be produced,
   but SPLOT does not attempt to spool it off for printing.
  
   ESPLOT is similar to SPLOT, but plots error bars based on the
   errors in the data.
  
   Command parameters -
  
   SPECTRUM    The data to be plotted.  If this contains X-axis
               information, this will be used.  If not, the X-axis
               will just have to be the numbers from 1 to n.
   XSTART      The x-value at which plotting is to start.
   XEND        The x-value at which plotting is to end.
               (XSTART and XEND are not required if WHOLE is set.)
   HIGH        The maximum value to be used for the plot.
   LOW         The minimum value to be used for the plot.
   BIAS        A value used to displace the plot - BIAS is
               effectively a value added to the data before
               it is plotted. (It is implemented as a value
               subtracted from both HIGH and LOW.)
               (HIGH,LOW and BIAS are not required if
               AUTOSCALE is set.)
   LABEL       A label for the plot.
   COLOUR      The colour for the plot, assuming the display device
               supports it.  The axes are always white.
   THICKNESS   The width of the lines used for the plot.  This is
               only used for ’hard’ & ’build’ plots, and should
               really be 1 for anything other than a high-resolution
               device like a Versatec or a laser printer.
  
   Command keywords -
  
   AUTOSCALE   The program is to work out the values for HIGH
               and LOW, using the maximum and minimum values
               in the data over the specified range.
   WHOLE       The program is to display all of the spectrum.
   HARDCOPY    The plot is to produce a hard copy.
   AXES        Axes will be plotted.
   ERASE       The screen will be erased before the plot.
   LINES       The plot is not done as a histogram, but as
               a ’join the dots’ line plot.  (Only applies
               to SPLOT.)
  
   User variables -    (">" input, "<" output)
  
   (>) SOFT    Specifies the device and type to be used for soft
               plots.  See the SOFT command for more details.
   (>) HARD    Specifies the device and type to be used for hard
               plots.  See the HARD command for more details.
   (<) TVXST   is set to the starting x-value for the plot.
   (<) TVXEN   Is set to the final x-value for the plot.
   (<) TVHIGH  Is set to the same value as HIGH.
   (<) TVLOW   Is set to the same value as LOW.
   (<) TVFILE  Is set to the value of SPECTRUM.
   (<) TVCOLOR Is set to the GRPCKG code for the plot colour.
               (The TV.. variables are intended for use by
               cursor routines, and reflect the settings for the
               last plot made, even if XSTART etc are changed.)
  
   (Other user variables may be set by the command processor, in
   connection with the parameter values.)
  
                                       KS / CIT  30th April 1984

D.66 EVALFIT-Evaluate fit results.

Usage:

evalfit in out comp=?

Description:
This routine turns components in the result structure of the Specdre Extension into a fake data set representing those results. Such a data set is necessary to perform arithmetic operations between the result (otherwise expressed only as a set of parameters) and the original data.
Parameters:
INFO
INFO = _LOGICAL (Read) If false, this routine will issue only error messages and no informational message. [YES]
DIALOG
DIALOG = _CHAR (Read) If ’T’, the routine can evaluate several sets of components. After a set of components has been evaluated, the user will be asked whether she wants to specify another set. [’T’]
IN
IN = NDF (Read) The input NDF. This must be a base NDF. If you need only a section of an NDF, you use SUBSET first to create the section permanently.
OUT
OUT = NDF (Read) The output NDF.
COMP
COMP = _INTEGER (Read) The numbers of up to 6 components to be added into the output data component. If you are not sure which component is which, you should inspect the result structure of the data first with EDITEXT.
REPLY
REPLY = _LOGICAL (Read) Set true to work on another set of components. This parameter is relevant only if DIALOG is true. [NO]
Examples:
  evalfit in out comp=[2,5,1,2] accept
     This will take the input NDF IN and create an equally shaped
     NDF called OUT. The specified components stored in IN’s (and
     OUT’s) Specdre Extension are evaluated and added up to make up
     the main data in OUT. Note that component no. 2 is added twice.
  
Source comments:
     E V A L F I T
  
     The routine takes as input a base NDF (a section is not
     acceptable). The output is a copy of the input, except for the
     main NDF data and variance components. These are re-calculated from
     certain components in the result structure of the Specdre
     Extension. Thus the output contains the fit results both in the
     result structure and in the main NDF. The main NDF can then be
     compared pixel by pixel with the original data.
  
     If the input main NDF has a variance component, the output
     variances will be set to zero.
  
     This routine recognises result components created by FITCHEBY (the
     precursor of FITPOLY), FITGAUSS, FITPOLY, or FITTRI. Unrecognised
     components are ignored, i.e. not added into the data. A warning to
     that effect is given.
     If a component in any particular position has bad values as
     parameters, then that component is ignored on that position. No
     warning to this effect is given.
  
     A component is accepted as 7th order series of Chebyshev
     polynomials if the component type is ’Chebyshev series’ and it has
     11 parameters. These are assumed to be order, xmin, xmax, coeff0,
     ... coeff7.
  
     A component is accepted as 7th order polynomial if the component
     type is ’polynomial’ and it has 9 parameters. These are assumed to
     be order, coeff0, ... coeff7.
  
     A component is accepted as Gauss or triangle if the component type
     is ’Gauss’ or ’triangle’ and it has 4 parameters. The first three
     are assumed to be centre, peak, FWHM.
  
     The string comparison to check the component type is
     case-insensitive.
  
Notes:
This routine recognises the Specdre Extension v. 0.7.

D.67 EXAM-Display the contents/structure of data file

Notes:
The EXAM application has been removed. Please use the Starlink utility HDSTRACE (cf. SUN/102). For example, if you want a listing of the contents of a data file use:

% hdstrace datafile full

D.68 EXTIN-Correct spectrum for atmospheric extinction

Description:
Given a spectrum and a calibration spectrum whose elements give the extinction coefficients at the wavelengths of the spectrum, corrects that spectrum for atmospheric extinction.
Parameters:
SPECTRUM
The spectrum specified by SPECTRUM will be corrected for extinction, given the extinction coefficients in the coefficient spectrum, and taking account of the air mass of the observation. So SPECTRUM should have a valid value for .OBS.SECZ (the program will complain if it doesn’t). The correction algorithm used allows for the data being calibrated in magnitudes.
COEFF
A spectrum whose elements give the extinction coefficients applicable for the observation. COEFF will normally have been prepared by first generating a spiketrum from a table of coefficients using GSPIKE and then using LINTERP to linearly interpolate between them.
OUTPUT
Specifies the name of the calibrated spectrum to be produced by EXTIN. Note that this can be the same as for SPECTRUM, in which case the operation will be performed in situ.
Source comments:
   E X T I N
  
   Corrects a spectrum for extinction, given a coefficient spectrum
   which gives the interpolated extinction coefficients over the
   wavelength range of the spectrum.  The spectrum must have
   a valid .OBS.SECZ value.
  
   Command parameters -
  
   SPECTRUM    (Character) The spectrum to be corrected.
   COEFF       (Character) The coefficient spectrum.
   OUTPUT      (Character) The resulting spectrum.
  
   Command keywords - None
  
   User variables used - None
  
                                       KS / CIT 24th July 1984

D.69 EXTLIST-Adds non-contiguous lines of an image to form a spectrum

Description:
The EXTLIST command extracts specific cross-sections of an image, adding them together to give one spectrum. The cross-section numbers are specified by an array of section numbers - this allows up to 40 non-contiguous cross-sections to be specified, rather than the single range allowed by EXTRACT.
Parameters:
IMAGE
The name of a 2-dimensional image. A number of rows (cross-sections) will be extracted from this image and added to form a single spectrum.
NROWS
Used to specify the number of cross-sections (rows) to be added together to form the single spectrum. It has to be specified here because the defaulting of values for the list makes it impossible to know otherwise how many of the values you actually intend to be used.
SECTIONS
The cross-sections of IMAGE specified by the array of row numbers given in SECtions will be added together.
SPECTRUM
Used to specify the name of the resulting 1-dimensional array. A new file will be created.
Source comments:
   E X T L I S T
  
   Adds the rows from IMAGE specified by the array of row numbers
   in SECTIONS and produces a 1-D data object called SPECTRUM.
  
   Command parameters -
  
   ’IMAGE’    The name of the image from which the rows
               are to be taken.
  
   ’NROWS’    The number of rows to be added.
  
   ’SECTIONS’ The array of row numbers.
  
   ’SPECTRUM’ The name of the resulting data.
  
   Output data -
  
   SPECTRUM is created with the same structure as IMAGE,
   except that data array will only have one dimension, and if
   IMAGE has Y-axis information, this will be omitted.  Any X-axis
   information will be copied unchanged.
  
                                 DJA / AAO 10th July 1987

D.70 EXTRACT-Adds contiguous lines of an image to form a spectrum

Description:
Adds a number of consecutive rows from an image to produce a 1-D data object. (A ’row’ is all the pixels with a given Y-value.)
Parameters:
IMAGE
Name of the image from which to extract data.
YSTART
First y-value to be used.
YEND
Last y-value to be used.
SPECTRUM
Name of output spectrum.
Source comments:
   E X T R A C T
  
   Adds a number of consecutive rows from an image to
   produce a 1-D data object.  (A ’row’ is all the
   pixels with a given y-value.)
  
   Command parameters -
  
   ’IMAGE’    The name of the image from which the rows
              are to be taken.
  
   ’YSTART’   The Y-value of the first row to be used.
              If IMAGE has a Y axis structure, the data from this
              is used.  If not, the row numbers are used,
              starting from 1.
  
   ’YEND’     The Y-value of the last row to be used.
  
   ’SPECTRUM’ The name of the resulting data.
  
   Output data -
  
   SPECTRUM is created with the same structure as IMAGE,
   except that the data will only have one dimension, and if
   IMAGE had a Y axis structure, this will be omitted.  Any X
   axis structure will be copied unchanged.
  
                                   KS / CIT 29th June 1984

D.71 FET321-Extracts a spectrum from 1 detector from etalon mode FIGS data

Description:
FET321 takes a FIGS data cube, as produced by the FIGS data acquisition system running in etalon mode, and reduces it to a single spectrum, summing up the various cycles and performing the beamswitch and chopping subtractions. Data from only one detector is extracted.
Parameters:
CUBE
The name of a data cube produced by the FIGS data acquisition system. That is is should have the dimensions (wavelength steps,8,beamswitch cycles) The cube should have been taken in Etalon mode.
DETECTOR
In etalon mode, each of the FIGS detectors produces data over a different wavelength range. Rather than produce a single spectrum covering disjoint wavelength ranges, FET321 uses DETECTOR to specify a single detector to be used to produce the spectrum.
SPECTRUM
The name of the resulting single spectrum produced by collapsing down the FIGS data cube.
CUTOFF
Values more than CUTOFF times sigma away from the mean value for the spectral point will not be included in the final spectrum.
ADD
Disables the subtraction of the background beamswitch and chopping data. This is unusual (ADD=NO is the default) and is generally only required for test data.
BACK
Returns the background spectrum only, rather than the background subtracted source data.
NORM
Causes the data for each cycle to be normalized so that the mean value for each cycle is the same. This gives more reasonable errors when data are taken in the presence of cloud. It should not be used on very faint sources, as the mean level may go negative under these circumstances
Source comments:
   F E T 3 2 1
  
   Given a FIGS data cube as produced by the FIGS data acquisition
   system running in one of the etalon modes, processes it to produce
   a single spectrum, for one of the detectors only.
  
   Command parameters -
  
   ’CUBE’     The name of the cube from which the planes
              are to be taken.  This should be a raw FIGS data
              cube.
   ’DETECTOR’ The number of the detector to be used.
   ’SPECTRUM’ The name of the resulting spectrum.
   ’CUTOFF’   The level (in sigma) at which a point will
              be ignored (FIGS321 only)
  
   Command keywords -
  
   ’ADD’      Add the data together rather than subtracting the
              beamswitch and chop backgrounds
  
   ’BACK’     Return the background spectrum only
  
   ’NORM’     Normalize data to mean level of each cycle.
  
   Input data -
  
   CUBE is assumed to have a structure with the actual
   cube data in CUBE.Z.DATA
  
   This routine assumes that the first axis of the cube data
   represents wavelength, that the second represents spectral
   scans in the order A1a,A1b,B1a,B1b,B2a,B2b,A2a,A2b, where
   A1,A2,B1,B2 represent the parts of the beamswitch ABBA cycle
   and a and b represent the signal and background chop positions
   respectively.  In etalon mode 2, there are no chop positions,
   and the second axis is just A1,B1,A2,B2. This means that the
   second dimension of the cube has to be either 4 or 8.  The
   cube third axis represents beamswitch cycle number.
   The data is normalized to give a figure in detected photons
   per second.  Along the wavelength axis, the data is assumed
   to be in order of etalon position, each etalon position having
   n values where n is the number of detectors used.
  
   Output data -
  
   IMAGE is created with the same structure as CUBE
   except that .Z.DATA will only have 1 dimension, and any
   .Y or .T sub-structures that CUBE has will be deleted.
   If a spectrum is produced the errors (derived from
   the cycle to cycle statistics) are placed in the .Z.ERRORS
   component
  
    5th May 1988  KS / AAO.   Original version, based on FIGS321.

D.72 FF-Flat field an image (uses Jon Tonry’s algorithm)

Description:
Flat fields an image using Jon Tonry’s algorithm.
Parameters:
IMAGE
Name of data to be flat fielded.
FLAT
Name of flat field to be used.
ORDER
Order for flat field profile fit.
OUTPUT
Name of result of operation.
Source comments:
   F F
  
   Applies a flat field correction to an image.
  
   Command parameters -
  
   IMAGE  The name of the structure containing the image.
  
   FLAT   The name of the structure containing the flat
          field data.
  
   ORDER  The order of the fit to be applied to the flat
          field data profile.
  
   OUTPUT The name of the result of the operation.  This can
          be the same as for IMAGE.  If not, a new structure
          is created, with everything but the data a direct
          copy of the input.
  
                                    KS / CIT 31st MAy 1983

D.73 FFCROSS-Cross-correlate an image and a flat field (mainly IPCS data)

Description:
This is for use with some flat fields (notably IPCS) where there may be a bodily shift between the flat field and the data. For each cross-section in a given range, this routine calculates the cross-correlation between the flat field and the data. It then calculates the average shift for each cross-section, as determined from the individual cross-correlation. It also sums the individual cross-correlations, and calculates the shift given by that summed cross-correlation. The idea is that the shift determined in this way can then be applied using ISHIFT.
Parameters:
IMAGE
Name of image.
FLAT
Name of flat field.
YSTART
First Y value to be used.
YEND
Last Y value to be used.
XSTART
First X value to be used.
XEND
Last X value to be used.
RECORD
Create file to record cross-correlation?
CROSS
Name of cross-correlation data?
LOG
Log individual cross-section shifts?
Source comments:
   F F C R O S S
  
   Main body of the Figaro FFCROSS function.  This is for use
   with some flat fields (notably IPCS) where there may be a bodily
   shift between the flat field and the data.  For each
   cross-section in a given range, this routine calculates the
   cross-correlation between the flat field and the data.  It then
   calculates the average shift for each cross-section, as determined
   from the individual cross-correlation.  It also sums the individual
   cross-correlations, and calculates the shift given by that summed
   cross-correlation.  The idea is that the shift determined in this
   way can then be applied using ISHIFT.
  
   Command parameters -
  
   IMAGE       (Character) The IMAGE to be compared with
               the flat field.
   FLAT        (Character) The FLAT field to be used.
               The FLAT and IMAGE data arrays should have the same
               dimensions.
   YSTART      (Numeric) The first cross-section to be used.
   YEND        (Numeric) The last cross-section to be used.
   XSTART      (Numeric) Data with an AXIS(1) value less than XSTART
               will be ignored in the cross-correlation.
   XEND        (Numeric) Data with an AXIS(1) value greater than XEND
               will also be ignored.  Note that these values are
               used to determine the channel numbers to be used
               for IMAGE and the same ones will be used for
               FLAT even if FLAT has a  different AXIS(1)
               structure.
   CROSS       (Character) the name of the data structure to hold
               the cross-correlation, if it is to be saved.
               The file created will be cross.dst, and will look
               like an ordinary spectrum - i.e. can be plotted by
               SPLOT, etc.  CROSS is ignored if RECORD is not set.
  
   Command keywords -
  
   RECORD      If set, the summed cross-correlation of the two
               images will be recorded as a new data structure.
   LOG         If set, the individual shifts for each cross-
               section will be logged as they are calculated.
  
   User variables used -
  
   SHIFT       (Numeric) The relative shift of the two images as
               determined from the summed cross-correlation.
   AVSHIFT     (Numeric) The average shift of the individual
               cross-sections.
  
                                           KS / CIT 5th Oct 1983

D.74 FFT-Takes the forward FFT of a complex data structure

Usage:
fft spatial_data frequency_data
Description:
These Figaro functions take the FFT of the data in a file. FFT performs a forward transform, BFFT performs an inverse transform. The input file must contain a complex data structure, i.e. one with IMAGINARY and DATA components.

The data may be multi-dimensional; if it is, a multi-dimensional FFT is performed. Note that the Figaro routine R2CMPLX will turn an existing real data structure into a complex one acceptable to this routine. FFT does not perform any cosine belling or other tapering of the data, nor does it reduce it to a zero mean.

Parameters:
CDATA
The name of a complex data structure. Such structures for the spatial domain are most easily produced using the R2CMPLX command. For the frequency domain, such data were usually created by R2CMPLX and transformed by FFT.
OUTPUT
The name of the resulting Fourier transformed data. If OUTPUT is the same as CDATA then the transform is performed in situ; otherwise, a new file is created.
Notes:
The fourier transform routines available in the various math libraries (NAG, IMSL, etc) all have slightly different characteristics, which show up in the programs that use them. This routine has been written around the NAG library (mainly the routines C06FAF and C06FJF), so many of its characteristics may be deduced by reading the relevant parts of the NAG manuals. In version 5.0 this routine was changed to use the PDA library, effectively FFTPACK routines. The data is re-ordered by FFT after the transform so that the zero frequency component is in the center of the resulting array, and this re-ordering is reversed by BFFT before the transform. This means that after FFT has been run, the various axes all go from -N to +N where N is the Nyquist frequency. New axis data structures that reflect this are created by FFT and will be deleted by BFFT.
See also:
FIGARO: COSBELL, BFFT, CMPLX2I, CMPLX2R, CMPLX2M, I2CMPLX, R2CMPLX.
KAPPA: CONVOLVE, LUCY, MEM2D, WIENER.
Authors:
ks: Keith Shortridge (AAO)

jm: Jo Murray (RAL, Starlink)

jms: ??? (AAO)

hme: Horst Meyerdierks (UoE, Starlink)

D.75 FIB2CUBE-Arranges fibre output into 3-d data file

Description:
To convert a longslit spectrum of fibre spectra to a cube in an arbitrary manner. The output cube is "SORTED" in the TAURUS sense.
Parameters:
IMAGE1
IMAGE1,IMAGE2 etc. = FILE (Read) Input images
CUBE
CUBE = FILE (Write) Output cube
FILE
FILE = CHARACTER (Read) File with relationships defined
Source comments:
    none available
  

D.76 FIBDISP-Fits 3D cubes and plots the results

Description:
This cube should have been created using FIB2CUBE. Options available include displaying planes of the cube and profiles and fitting Gaussians etc. to these profiles.
Parameters:
CUBE
CUBE = FILE (Read) Cube for display This should be a file produced by FIB2CUBE, containing a .FIBRE structure.
YSTART
YSTART = REAL (Read) analysis lower limit The data between the limits ystart and yend is extracted and the resultant spectrum is used to locate the lines.
YEND
YEND = REAL (Read) analysis upper limit The data between the limits ystart and yend is extracted and the resultant spectrum is used to locate the lines.
YBLOCK
YBLOCK = REAL (Read) Enter analysis x-sect width Each window is of this width (except perhaps the final one).
TSTART
TSTART = REAL (Read) analysis lower limit The data between the limits tstart and tend is extracted and the resultant spectrum is used to locate the lines.
TEND
TEND = REAL (Read) analysis upper limit The data between the limits tstart and tend is extracted and the resultant spectrum is used to locate the lines.
TBLOCK
TBLOCK = REAL (Read) Enter analysis blocking width in 3rd dimension Each window is of this width (except perhaps the final one).
DEVICE
DEVICE = CHARACTER (Read) Device for display
ITERATION
ITERATION = INTEGER*2 (Read) New value of itteration
OUTABLE
OUTABLE = FILE (Write) Name for EXTATIC file
VCORR
VCORR = REAL (Read) correction to apply to radial velocities
TOLS
TOLS = CHARACTER (Read) For use in batch only
FITRAT
FITRAT = REAL (Read) Ratio of widths, heights, or separation, for double fits
CALRAT
CALRAT = INTEGER (Read) Ratio of number of iteration to default
OUTPUT
OUTPUT = FILE (Write) Name for output file
FIT_MODEL
FIT_MODEL = CHARACTER (Read) Model of fit to perform
LOW
LOW = REAL (Read) Minimum value for display
HIGH
HIGH = REAL (Read) Maximum value for display
ABSORPTION
ABSORPTION = LOGICAL (Read) Allow fitting of absorption lines
BOUNDS
BOUNDS = LOGICAL (Read) Perform bounded fits to lines (in batch)
HARDCOPY
HARDCOPY = LOGICAL (Read) produce hardcopy plots of fits from cube
TABLE
TABLE = LOGICAL (Read) produce table of fits from cube
PRINT
PRINT = LOGICAL (Read) Produce print out of rotation curves
SHAPE
SHAPE = LOGICAL (Read) Carry out shape analysis
KEEP_ITT
KEEP_ITT = LOGICAL (Read) Keep itteration files’
FIT
FIT = LOGICAL (Read) perform fitting
AIC
AIC = LOGICAL (Read) Use Akiakes information criterion for fitting
WEIGHTS
WEIGHTS = LOGICAL (Read) Use weights for fitting
PRFITS
PRFITS = LOGICAL (Read) Print out details of fitting
FULL
FULL = LOGICAL (Read) Print out full details of fits in table
Source comments:
    none available
  

D.77 FIBSEP-Separate spectra in 2D array

Description:
This cube should have been created using FIB2CUBE. Options available include displaying planes of the cube and profiles and fitting Gaussians etc. to these profiles.
Parameters:
CUBE
CUBE = FILE (Read) Cube for display This should be a file produced by FIB2CUBE, containing a .FIBRE structure.
YSTART
YSTART = REAL (Read) analysis lower limit The data between the limits ystart and yend is extracted and the resultant spectrum is used to locate the lines.
YEND
YEND = REAL (Read) analysis upper limit The data between the limits ystart and yend is extracted and the resultant spectrum is used to locate the lines.
YBLOCK
YBLOCK = REAL (Read) Enter analysis x-sect width Each window is of this width (except perhaps the final one).
TSTART
TSTART = REAL (Read) analysis lower limit The data between the limits tstart and tend is extracted and the resultant spectrum is used to locate the lines.
TEND
TEND = REAL (Read) analysis upper limit The data between the limits tstart and tend is extracted and the resultant spectrum is used to locate the lines.
TBLOCK
TBLOCK = REAL (Read) Enter analysis blocking width in 3rd dimension Each window is of this width (except perhaps the final one).
DEVICE
DEVICE = CHARACTER (Read) Device for display
ITERATION
ITERATION = INTEGER*2 (Read) New value of itteration
OUTABLE
OUTABLE = FILE (Write) Name for EXTATIC file
VCORR
VCORR = REAL (Read) correction to apply to radial velocities
TOLS
TOLS = CHARACTER (Read) For use in batch only
FITRAT
FITRAT = REAL (Read) Ratio of widths, heights, or separation, for double fits
CALRAT
CALRAT = INTEGER (Read) Ratio of number of iteration to default
OUTPUT
OUTPUT = FILE (Write) Name for output file
FIT_MODEL
FIT_MODEL = CHARACTER (Read) Model of fit to perform
LOW
LOW = REAL (Read) Minimum value for display
HIGH
HIGH = REAL (Read) Maximum value for display
ABSORPTION
ABSORPTION = LOGICAL (Read) Allow fitting of absorption lines
BOUNDS
BOUNDS = LOGICAL (Read) Perform bounded fits to lines (in batch)
HARDCOPY
HARDCOPY = LOGICAL (Read) produce hardcopy plots of fits from cube
TABLE
TABLE = LOGICAL (Read) produce table of fits from cube
PRINT
PRINT = LOGICAL (Read) Produce print out of rotation curves
SHAPE
SHAPE = LOGICAL (Read) Carry out shape analysis
KEEP_ITT
KEEP_ITT = LOGICAL (Read) Keep itteration files’
FIT
FIT = LOGICAL (Read) perform fitting
AIC
AIC = LOGICAL (Read) Use Akiakes information criterion for fitting
WEIGHTS
WEIGHTS = LOGICAL (Read) Use weights for fitting
PRFITS
PRFITS = LOGICAL (Read) Print out details of fitting
FULL
FULL = LOGICAL (Read) Print out full details of fits in table
Source comments:
    none_available
  

D.78 FIGHELP-Provide Figaro on-line help

Usage:
fighelp [topic]
Description:
This routine interfaces the portable help library for the Figaro package with a terminal. The ADAM parameter TOPIC is used only for the initial entry into the help library. The user can then navigate through the library with the following responses to the prompt:

- A blank response gets you one level up in the topic hierarchy.

- A question mark (?) re-displays the current topic.

- An end-of-file character exits fighelp. Note that this is Ctrl-z under VMS but usually Ctrl-d under Unix.

- Any normal text specifies (sub-) topics to look for.

- Each blank-separated word stands for one topic in the hierarchy. E.g. three blank-separated words go down three levels in the hierarchy.

- Each underscore-separated word stands for an underscore-separated word in a single topic

- Words (whether separated by blanks or underscores) that are not unique topics or include wild card characters are expanded and help is given on all matching topics. Wild card characters are % for a single character and * for any number of characters including none. In the word expansion A_G_N would match active_galactic_nuclei, which is one topic. The same is true for A*_G*_N* or active or active*.

When the help text to be printed is longer than the terminal page, then the user is asked to press the Return key before proceeding with output. At this point, too, can an end-of-file character be given to exit fighelp immediately.

Parameters:
PAGE
The number of lines that are a screen-full of information on the terminal. This is used so that FIGHELP knows when to wait for the reader to hit the return key. To turn paging off set this parameter zero. If this is not given, then the routine will try to find out about the terminal on its own.
WIDTH
The number of columns on the screen. If this is not given, then the routine will try to find out about the terminal on its own.
LIBRARY
The full file name of the library to be enquired. If this is not given, then the translation of the environment variable FIG_HELP will be used.
TOPIC
A initial topic to be looked for in the library. If this is not given, the top level of the library will be presented.
Notes:
This routine is available only under Unix from a Unix shell.
Authors:
hme: Horst Meyerdierks (UoE, Starlink)

D.79 FIGINFO-Describes the contents of a Figaro data file

Description:
FIGINFO provides a way of looking at the contents of a Figaro data file through Figaro’s eyes. You can do an hdstrace of file, but this doesn’t necessarily tell you how Figaro will interpret what you find there, particularly in the case of awkward things like the flag that indicates whether or not the file’s main data array may contain flagged data values (which doesn’t necessarily mean that it does, just that it might). This particular flag can be a problem for Figaro files, partly because the default rules - how you interpret it’s absence - is different in the two data formats, .SDF and .DST. If it is set when the file does not in fact contain flagged values then processing the file can be inefficient, particularly for large files. If the file does contain flagged data values but the flag is not set, then very odd results can be obtained when the file is processed. FIGINFO uses the same file access routines as a normal Figaro program to interpret the file contents. It also provides a couple of options for manipulating the ’may contain flagged data values’ flag, should it be mis-set.
Parameters:
INPUT
The name of a datafile. FIGINFO will list its contents - whether it has error or quality information, whether it has a set of FITS keywords, etc. Most of this can be gleaned from doing an hdstrace on the file, but hdstrace just shows the file contents - FIGINFO explains how they are interpreted by FIGARO.
CHECK_FLAGS
If CHECK_FLAGS is set, and the file has the flag set to indicate that it MAY have flagged data values in the main data array, then FIGINFO will read the array and see if there are in fact any flagged data values there. If there are not, it clears the ’may have flagged values’ flag. This will speed up the processing of the file by Figaro programs that do not handle flagged values themselves. There is the overhead of the check, of course, which can be large for very large data arrays, but FIGINFO does this as efficiently as possible. (The same effect can be obtained by doing an ISTAT on the data, but this is much less efficient)
CLEAR_FLAG
If the file has the flag set to indicate that it MAY have flagged data values in the main data array, but the option to check the data array values is not taken - presumably on the grounds that the overhead is not warranted - then the CLEAR_FLAG option may be set to indicate that there are definitely no flagged data values in the array and the file should be modified to show this. This is a DANGEROUS option to use. It should only be taken if the overhead of checking the data array is too large - and that implies a huge data file! - and if the user is CERTAIN that there really are no flagged data values in the data. Use of this option is not recommended.
SET_FLAG
If the file does not have the flag set to indicate that it MAY have flagged data values in the main data array, but nevertheless does have such values, then a number of programs will have problems handling the file. The SET_FLAG option allows this flag to be set. This is a safe option - setting it unnecessarily does no harm, but it does make for rather inefficient processing of the file. However, this really shouldn’t be necessary - except, perhaps to correct for a mistaken use of the CLEAR_FLAG option!
Source comments:
   F I G I N F O
  
   Description:
  
      FIGINFO provides a way of looking at the contents of a Figaro data
      file through Figaro’s eyes. You can do an hdstrace of file, but this
      doesn’t necessarily tell you how Figaro will interpret what you
      find there, particularly in the case of awkward things like the
      flag that indicates whether or not the file’s main data array may
      contain flagged data values (which doesn’t necessarily mean that it
      does, just that it might). This particular flag can be a problem for
      Figaro files, partly because the default rules - how you interpret
      it’s absence - is different in the two data formats, .SDF and .DST.
      If it is set when the file does not in fact contain flagged values then
      processing the file can be inefficient, particularly for large files. If
      the file does contain flagged data values but the flag is not set, then
      very odd results can be obtained when the file is processed. FIGINFO
      uses the same file access routines as a normal Figaro program to
      interpret the file contents. It also provides a couple of options for
      manipulating the ’may contain flagged data values’ flag, should it
      be mis-set.
  
   Parameters:
  
      INPUT     (Character) Is the name of the file to be checked.
  
   Keywords:
  
      CHECK_FLAGS   If set, FIGINFO reads the data in the main data array
                    to see if it does in fact contain flagged data values.
                    If it does not, the ’may contain flagged data values’
                    flag is cleared. (This option is only offered if the
                    flag was initially set.)
      CLEAR_FLAG    A DANGEROUS option that clears the ’may contain flagged
                    data values’ flag without testing the actual data. (This
                    option is only offered if the flag was initially set and
                    CHECK_FLAGS was not set.)
      SET_FLAG      A relatively safe option that sets the ’may contain
                    flagged data values’ flag. The actual data is not tested.
                    (This option is only offered if the flag was not initially
                    set.)
  
      31st Jan 1995.  Original version. KS/AAO.

D.80 FIGS321-Processes a FIGS data cube down to a single spectrum

Description:
FIGS321 takes a FIGS data cube, as produced by the FIGS data acquisition system, and reduces it to a single spectrum, summing up the various cycles and performing the beamswitch and chopping subtractions.
Parameters:
CUBE
The name of a data cube produced by the FIGS data acquisition system. That is is should have the dimensions (wavelength steps,8,beamswitch cycles)
SPECTRUM
The name of the resulting single spectrum produced by collapsing down the FIGS data cube.
CUTOFF
Values more than CUTOFF times sigma away from the mean value for the spectral point will not be included in the final spectrum.
ADD
Disables the subtraction of the background beamswitch and chopping data. This is unusual (ADD=NO is the default) and is generally only required for test data.
BACK
Returns the background spectrum only, rather than the background subtracted source data.
NORM
Causes the data for each cycle to be normalized so that the mean value for each cycle is the same. This gives more reasonable errors when data are taken in the presence of cloud. It should not be used on very faint sources, as the mean level may go negative under these circumstances
Source comments:
   F I G S 3 2 2 ,   F I G S 3 2 1
  
   Given a FIGS data cube as produced by the FIGS data acquisition
   system, processes it to produce either an image of wavelength
   against cycle number (FIGS322) or a single spectrum (FIGS321).
  
   Command parameters -
  
   ’CUBE’     The name of the cube from which the planes
              are to be taken.  This should be a raw FIGS data
              cube.
   ’IMAGE’    The name of the resulting image (FIGS322)
   ’SPECTRUM’ The name of the resulting spectrum (FIGS321)
   ’CUTOFF’   The level (in sigma) at which a point will
              be ignored (FIGS321 only)
  
   Command keywords -
  
   ’ADD’      Add the data together rather than subtracting the
              beamswitch and chop backgrounds
  
   ’BACK’     Return the background spectrum only
  
   ’NORM’     Normalize data to mean level of each cycle.
              (FIGS321 only.)
  
   Input data -
  
   This routine assumes that the first axis of the cube data
   represents wavelength, that the second represents spectral
   scans in the order A1a,A1b,B1a,B1b,B2a,B2b,A2a,A2b, where
   A1,A2,B1,B2 represent the parts of the beamswitch ABBA cycle
   and a and b represent the signal and background chop positions
   respectively.  In grating mode 2, there are no chop positions,
   and the second axis is just A1,B1,A2,B2. Grating mode 3 data
   is modified by the on-line acquisition software so that it
   has the same format as grating mode 1 data.  This means that the
   second dimension of the cube has to be either 4 or 8.  The
   cube third axis represents beamswitch cycle number.
   The data is sorted into wavelength order using the various
   grating parameters read from the .FITS sub-structure of CUBE.
   The data is normalized to give a figure in detected photons
   per second.
  
   Output data -
  
   IMAGE is created with the same structure as CUBE
   except that main data array will only have 1 or 2 dimensions, and any
   AXIS sub-structures that CUBE has will be deleted/renamed
   as appropriate. If a spectrum is produced the errors (derived from
   the cycle to cycle statistics) are generated.
  
                                   KS / AAO 8th June 1985

D.81 FIGS322-Processes a FIGS data cube down to an image

Description:
FIGS321 takes a FIGS data cube, as produced by the FIGS data acquisition system, and reduces it to a single image, subtracting off the various beamswitch and chopping backgrounds.
Parameters:
CUBE
The name of a data cube produced by the FIGS data acquisition system. That is is should have the dimensions (wavelength steps,8,beamswitch cycles).
IMAGE
The name of the resulting single image produced by collapsing down the FIGS data cube.
ADD
Disables the subtraction of the background beamswitch and chopping data. This is unusual (ADD=NO is the default) and is generally only required for test data.
BACK
Returns the background spectrum only, rather than the background subtracted source data.
Source comments:
   F I G S 3 2 2 ,   F I G S 3 2 1
  
   Given a FIGS data cube as produced by the FIGS data acquisition
   system, processes it to produce either an image of wavelength
   against cycle number (FIGS322) or a single spectrum (FIGS321).
  
   Command parameters -
  
   ’CUBE’     The name of the cube from which the planes
              are to be taken.  This should be a raw FIGS data
              cube.
   ’IMAGE’    The name of the resulting image (FIGS322)
   ’SPECTRUM’ The name of the resulting spectrum (FIGS321)
   ’CUTOFF’   The level (in sigma) at which a point will
              be ignored (FIGS321 only)
  
   Command keywords -
  
   ’ADD’      Add the data together rather than subtracting the
              beamswitch and chop backgrounds
  
   ’BACK’     Return the background spectrum only
  
   ’NORM’     Normalize data to mean level of each cycle.
              (FIGS321 only.)
  
   Input data -
  
   This routine assumes that the first axis of the cube data
   represents wavelength, that the second represents spectral
   scans in the order A1a,A1b,B1a,B1b,B2a,B2b,A2a,A2b, where
   A1,A2,B1,B2 represent the parts of the beamswitch ABBA cycle
   and a and b represent the signal and background chop positions
   respectively.  In grating mode 2, there are no chop positions,
   and the second axis is just A1,B1,A2,B2. Grating mode 3 data
   is modified by the on-line acquisition software so that it
   has the same format as grating mode 1 data.  This means that the
   second dimension of the cube has to be either 4 or 8.  The
   cube third axis represents beamswitch cycle number.
   The data is sorted into wavelength order using the various
   grating parameters read from the .FITS sub-structure of CUBE.
   The data is normalized to give a figure in detected photons
   per second.
  
   Output data -
  
   IMAGE is created with the same structure as CUBE
   except that main data array will only have 1 or 2 dimensions, and any
   AXIS sub-structures that CUBE has will be deleted/renamed
   as appropriate. If a spectrum is produced the errors (derived from
   the cycle to cycle statistics) are generated.
  
                                   KS / AAO 8th June 1985

D.82 FIGS422-Process a FIGS image-mode hypercube down to an image

Description:
Given an image mode FIGS data hypercube, produces an image. It included all the scan cycles in the hypercube, but only those wavelength planes within a specified range. The data hypercube may have been sorted into wavelength order (by the program FIGS424) or it may be raw data as produced by the acquisition system.
Parameters:
HCUBE
The name of an image mode FIGS data hypercube, as produced by the FIGS data acquisition system or as sorted by FIGS424.
XSTART
FIGS422 only includes wavelength planes that fall within the wavelength range specified by XSTART..XEND. The program allows some slop in the specification of the wavelength values, so a single plane can be picked out without having to worry about giving its wavelength exactly as it appears in the cube.
XEND
Specifies the end of the wavelength range to be included in the resulting image.
CYSTART
The first cycle number to be included in the output data file(s).
CYEND
The last cycle number to be included in the output data file(s).
IMAGE
The name of the resulting image. FIGS422 always generates a new image file.
SPLIT
If SPLIT is set, then FIGS422 will generate a separate file for each of the cycles in the range CYSTART through CYEND. The files will be given the name specified by IMAGE, but with the cycle number appended. If SPLIT is not set, FIGS422 adds all the cycles in the range to produce a single image whose name is that specified by IMAGE.
Source comments:
   F I G S 4 2 2
  
   Given a FIGS image mode data hypercube, either sorted into
   wavelength order (e.g. by FIGS424) or not, sums all the cycles
   and wavelength planes within a specified wavelength range
   to produce an image.
  
   Command parameters -
  
   ’HCUBE’    (Character) The name of the hypercube to be processed.
   ’XSTART’   (Real) The start of the wavelength range to be included.
   ’XEND’     (Real) The end of the wavelength range to be included.
   ’CYSTART’  (Integer) The first cycle to be included.
   ’CYEND’    (Integer) The last cycle to be included.
   ’IMAGE’    (Character) The name of the resulting image.
  
   Command keywords -
  
   ’SPLIT’    If set, FIGS422 will create a number of output
              files, one for each cycle in the specified range,
              rather than just one with all the cycles in the range
              summed.  In this case, the output files will be named
              using the name specified using ’IMAGE’, but with the
              cycle number appended.
  
   Input data -
  
   HCUBE is assumed is the actual hypercube data.
  
   This routine assumes that the first axis of the cube data
   represents wavelength, that the second and third represent the
   X and Y dimensions of the image (this is an unfortunate,
   since it means that the AXIS(1) structure of the hypercube represents
   wavelength, the AXIS(2) represents the image X axis and so forth)
   and the fourth axis represents scan cycle number.
  
   Output data -
  
   IMAGE is created with the same structure as HCUBE
   except that the main data array will only have 2 dimensions, and any
   AXIS sub-structures that HCUBE has will be
   deleted/renamed as appropriate.
  
                                   KS / AAO 6th Jan 1985

D.83 FIGS423-Process a FIGS image-mode hypercube down to a cube

Description:
Given an image mode FIGS data hypercube, produces a cube, in which all the data from a selected range of cycles has been summed. The data hypercube may have been sorted into wavelength order (by the program FIGS424) or it may be raw data as produced by the acquisition system. In general, it will be better to sort the data before applying FIGS423.
Parameters:
HCUBE
The name of an image mode FIGS data hypercube, as produced by the FIGS data acquisition system or as sorted by FIGS424.
CYSTART
The first cycle number to be included in the output data cube.
CYEND
The last cycle number to be included in the output data cube.
CUBE
The name of the resulting cube. FIGS423 always generates a new image file.
Source comments:
   F I G S 4 2 3
  
   Given a FIGS image mode data hypercube, either sorted into
   wavelength order (e.g. by FIGS424) or not, sums all the cycles
   and wavelength planes within a specified wavelength range
   to produce an image.  Note that it is probably best to have
   performed the wavelength sort first.
  
   Command parameters -
  
   ’HCUBE’    (Character) The name of the hypercube to be processed.
   ’CYSTART’  (Integer) The first cycle to be included.
   ’CYEND’    (Integer) The last cycle to be included.
   ’CUBE’     (Character) The name of the resulting cube..
  
   Input data -
  
   This routine assumes that the first axis of the hcube data
   represents wavelength, that the second and third represent the
   X and Y dimensions of the image (this is an unfortunate,
   since it means that the .X axis of the hypercube represents
   wavelength, the .Y represents the image X axis and so forth)
   and the fourth axis represents scan cycle number.
  
   Output data -
  
   CUBE is created with the same structure as HCUBE
   except that the dta array will only have 3 dimensions, and any
   AXIS(4) sub-structures that HCUBE has will be deleted.
  
                                   KS / AAO 19th May 1986

D.84 FIGS424-Sort a FIGS image-mode hypercube into wavelength order

Description:
Re-orders a raw FIGS image-mode data hypercube so that the spectral dimension is in ascending order of wavelength, instead of in the order as read by the data acquisition system.
Parameters:
HCUBE
The name of an image mode FIGS raw data hypercube, as produced by the FIGS data acquisition system.
OUTPUT
The name of the resulting FIGS image mode hypercube sorted into proper wavelength order, and with a .X structure that contains an appropriate wavelength array. If OUTPUT is the same as HCUBE, the data will be processed in situ; otherwise a new data file will be created.
Source comments:
   F I G S 4 2 4
  
   Given a FIGS image-mode data hypercubecube as produced by the FIGS
   data acquisition system, processes it to produce a hypercube in
   which the data have been sorted into wavelength order in accordance
   with the wavelength parameters included in the hypercube.
  
   Command parameters -
  
   ’HCUBE’    The name of the hypercube to be processed.
              This should be a raw FIGS data hypercube.
   ’OUTPUT’   The name of the resulting hypercube.  If this is the
              same as HCUBE the data is processed in situ, if not
              a new output file is produced.
  
   Command keywords - None
  
   Input data -
  
   HCUBE is assumed to have a structure with the actual
   cube data in HCUBE.Z.DATA
  
   This routine assumes that the first axis of the cube data
   represents wavelength, that the second and third represent the
   X and Y dimensions of the image (this is an unfortunate,
   since it means that the .X axis of the hypercube represents
   wavelength, the .Y represents the image X axis and so forth)
   and the fourth axis represents scan cycle number.
   The data is sorted into wavelength order using the various
   grating parameters read from the .FITS sub-structure of HCUBE.
   The data is only re-ordered in the first dimension of the
   hypercube.
  
   Output data -
  
   OUTPUT is created with the same structure as HCUBE, but with
   a .X structure added to contain the wavelength information.
  
                                   KS / AAO 25th Nov 1985

D.85 FIGSEE-Generate a seeing ripple spectrum from a FIGS spectrum

Description:
FIGSEE generates a seeing ripple spectrum from a FIGS spectrum. In principle, the FIGS data can then be divided by this ripple spectrum to take out the effects of variable seeing during the observation.
Parameters:
SPECTRUM
Spectrum to use for seeing data.
NDET
Number of detectors to use.
DETECTORS
Detectors to use.
OUTPUT
Name of resulting seeing ripple data.
Source comments:
   F I G S E E
  
   Figaro function that attempts to produce a seeing ripple spectrum
   from a Figs spectrum, averaging the data from one or more detectors,
   normalising the result to unity, and generating a spectrum in
   which the normalised data from these detectors (ideally ones not
   contaminated by spectral features) are repeated for each detector.
  
   Command parameters -
  
   SPECTRUM    (Character) The name of the file containing the
               spectrum to be used.
   NDET        (Integer) The number of detectros to be used.
   DETECTORS   (Numeric array) The detectors to be used.
   OUTPUT      (Character) The name of the resulting ripple spectrum.
  
   Command keywords -  None
                                                KS / AAO 11th Feb 1987

D.86 FIGSFLUX-Flux calibrates a FIGS spectrum

Description:
Flux calibrates a FIGS spectrum using a standard spectrum.
Parameters:
SPECTRUM
Name of Star spectrum.
STANDARD
Name of Standard spectrum.
KMAG
K magnitude of standard star.
OUTPUT
Name of resulting spectrum.
Source comments:
   F I G S F L U X
  
   Flux calibrates a FIGS spectrum using a standard spectrum
  
   Command parameters -
  
   SPECTRUM  The name of the structure containing the first image.
  
   STANDARD  The name of the structure containing the second
             image data.
  
   KMAG      The K magnitude of the standard used
  
   OUTPUT    The name of the result of the operation.  This can
             be the same as for SPECTRUM.  If not, a new structure
             is created, with everything but the data a direct
             copy of the input.
  
                                        JAB / AAO  14th June 1985

D.87 FILLCUBE-Copy one NDF into part of another.

Usage:

fillcube in out

Description:
This routine copies data, variance etc. from one NDF into another existing NDF. By successive calls the output NDF can be filled with data from a number of input NDFs. The target area in the output is identified by matching axis data (not pixel indices). Data are copied from input to output only if the input data value is not bad, apart from that existing data in the output are overwritten.
Parameters:
INFO
INFO = _LOGICAL (Read) True if informational messages are to be issued.
TOL
TOL = _REAL (Read) The tolerated fraction of the pixel size by which the input coordinates may deviate from the output coordinates. If any one of the axis values deviates more than TOL times the coordinate step, then the input data are ignored and the output data left unchanged. [0.2]
IN
IN = NDF (Read) The input NDF.
OUT
OUT = NDF (Read) The output NDF. This must already exist, update access is required.
Source comments:
     F I L L C U B E
  
     This application is more akin to ASCIN than to GROW. The main
     differences to ASCIN are that FILLCUBE updates an existing output
     and that its input is an NDF rather than an ASCII table.
     Its main advantage over GROW is that input and output may
     (actually must) have the same dimensionality, but any dimensions
     or axis data can differ. Also it is not necessary that target
     pixels form a contiguous subset in the output: The input pixels
     could match, say, every second or third output pixel.
     The disadvantages are that results and spectroscopic values in the
     Specdre Extension are not handled, and that the coordinates along
     each axis in input and output must be linear.
  
     For each input pixel, FILLCUBE looks for the output pixel that is
     nearest in the space of axis data coordinates. Data are copied
     only if the output pixel is hit close to its centre. However, if
     an axis is degenerate (has only one pixel) in both input and
     output, then the coordinates are assumed to match.
  
     No indication is given as to how many input pixels did not match
     any output pixel.
Notes:
This routine recognises the Specdre Extension v. 0.7, although it is largely ignored.

This routine works in situ on an existing output file.

Spectroscopic values must not exist in the Extension of either the input or the output NDF: A unique coordinate axis is required for all axes, including the spectroscopic one, in order to locate the target pixels by matching coordinates between input and output. If this is inconvenient, GROW may be a more suitable application for your purpose.

Spectroscopic widths must not exist in the Extension of the output NDF and are ignored in the input NDF: This information is likely to be present only when spectroscopic values are present as well.

Covariance row sums must not exist in the Extension of the output NDF: The validity of this information is difficult to assess when only parts of spectra might be copied from one cube to another, and when these parts are contiguous in the input but might not be in the output. Input covariance row sums are ignored.

The results in the input Extension are ignored, and results must not exist in the output Extension.

D.88 FINDSP-Locate fibre spectra in an image

Description:
This routine locates spectra in a large fibre frame and produces a polynomial file. The polynomial file has a version 2 format. Version 1 format uses the coefficients of a Chebyshev series, while version 2 format uses ordinary polynomial coeffients.

The technique of this routine is to

1 Compress the data array, 2 Follow ridges from start positions by centroiding, 3 Fit a polynomial Y(X) to the centroids, 4 Write the polynomial coefficients to a text file.

The text file can be read by the applications OVERPF and POLEXT. Those applications will also be able to read text files in version 1 format.

Parameters:
IMAGE
The fibre frame - one with distorted fibre spectra equally spaced.
BLACK
The data value below which the image display is to have the background colour. The display is scaled linearly between the data values specified as BLACK and WHITE.
WHITE
The data value above which the image display is to have the foreground colour. The display is scaled linearly between the data values specified as BLACK and WHITE.
NUMFIB
The total number of fibres used in the observation, including any dud fibres.
NORDER
The order of the polynomial to be fitted along each spectrum. The default is 6 and the maximum order allowed is 10. An even order is suggested by the presence of ’barrel’ distortion.
NPTS
The image is compressed in the X (wavelength) direction before the centroids are determined. This parameter fixes the number X-direction bins in the compressed frame. This parameter also by definition is the number of points along the spectrum to be used for fitting the polynomial. Choice of this parameter is a trade-off between having enough points along the spectra that the the curved spectra can be reliably followed and having enough S/N in the compressed image to determine a reliable centroid.
FWCENT
The ’full-width’ of the centroiding range in the vertical direction.
CFW
To get the initial centre for the centroiding the program does a linear extrapolation from the last two centroids. The program searches out from the previously determined central centroids. In order to supress large fluctuations that sometimes occur it is necessary to have damping in the extrapolation. If fact this ’Centroid Weighting Function’ parameter is the constant that the true gradient of the linear extrapolation is multiplied by to guess the next centroid. Hence a value of CFW less than 1 damps the extrapolation toward the horizontal.
YFIRST
The position of the centre of the first spectrum. This is expressed as the number of pixels up from the bottom of the image as viewed on the ARGS. Note that the default is only a guess from the size of the image.
YSEP
The average number of pixels separating each spectrum in the input image. Again the default value represents a guess.
PFILE
The file to which the results of the spectrum fitting performed by FINDSP is to be written. If no extension is specified, ‘.pol’ is used.
ADJUST
Used to ask whether centroid start points need adjustment.
CHGPAR
Used to ask whether analysis to be repeated with changed parameters.
REJECT
The number of a fibre to be rejected.
CHGREJ
Used to ask whether the set of fibres to be rejected should be revised.
Authors:
jrl: John Lucey (AAO, Durham)

hme: Horst Meyerdierks (UoE, Starlink)

D.89 FITBB-Fit diluted Planck curves to a spectrum.

Usage:

fitbb in device=? mask1=? mask2=? ncomp=? theta=? alpha=? lgtemp=? sf=? af=? tf=? comp=? logfil=?

Description:
This routine fits up to six diluted Planck curves to a one-dimensional data set. This can be specified as an NDF section. The data set must extend along the spectroscopic axis. The fit is done on a double logarithmic representation of the data. The axis data must be the common logarithm of frequency in Hertz. The data themselves must be the common logarithm of intensity or flux density in arbitrary units.
Parameters:
INFO
INFO = _LOGICAL (Read) If false, this routine will issue only error messages and no informational message. [YES]
VARUSE
VARUSE = _LOGICAL (Read) If false, input variances are ignored. [YES]
DIALOG
DIALOG = _CHAR (Read) If ’T’, the routine offers in general more options for interaction. The mask or guess can be improved after inspections of a plot. Also, the routine can resolve uncertainties about where to store results by consulting the user. [’T’]
IN
IN = NDF (Read) The input NDF. This must be a one-dimensional (section of an) NDF. You can specify e.g. an image column as IN(5,) or part of an image row as IN(2.2:3.3,10). Update access is necessary to store the fit result in the NDF’s Specdre Extension.
REPAIR
REPAIR = _LOGICAL (Read) If DIALOG is true, REPAIR can be set true in order to change the spectroscopic number axis in the Specdre Extension. [NO]
DEVICE
DEVICE = DEVICE (Read) The name of the plot device. Enter the null value (!) to disable plotting. [!]
MASK1
MASK1( 6 ) = _REAL (Read) Lower bounds of mask intervals. The mask is the part(s) of the spectrum that is (are) fitted and plotted. The mask is put together from up to six intervals:

mask = [MASK1(1);MASK2(1)] U [MASK1(2);MASK1(2)] U ... U [MASK1(MSKUSE);MASK2(MSKUSE)].

The elements of the MASK parameters are not checked for monotony. Thus intervals may be empty or overlapping. The number of intervals to be used is derived from the number of lower/upper bounds entered. Either MASK1 or MASK2 should be entered with not more numbers than mask intervals required.

MASK2
MASK2( 6 ) = _REAL (Read) Upper bounds of mask intervals. See MASK1.
NCOMP
NCOMP = _INTEGER (Read) The number of Planck curves to be fitted. Must be between 1 and 6. [1]
THETA
THETA( 6 ) = _REAL (Read) Guess scaling constant for each diluted Planck component.
ALPHA
ALPHA( 6 ) = _REAL (Read) Guess emissivity exponent for each diluted Planck component.
LGTEMP
LGTEMP( 6 ) = _REAL (Read) Guess common logarithm of colour temperature in Kelvin for each diluted Planck component.
SF
SF( 6 ) = _INTEGER (Read) For each component I, a value SF(I)=0 indicates that THETA(I) holds a guess which is free to be fitted. A positive value SF(I)=I indicates that THETA(I) is fixed. A positive value SF(I)=J<I indicates that THETA(I) has to keep a fixed offset from THETA(J).
AF
AF( 6 ) = _INTEGER (Read) For each component I, a value AF(I)=0 indicates that ALPHA(I) holds a guess which is free to be fitted. A positive value AF(I)=I indicates that ALPHA(I) is fixed. A positive value AF(I)=J<I indicates that ALPHA(I) has to keep a fixed offset to ALPHA(J).
TF
TF( 6 ) = _INTEGER (Read) For each component I, a value TF(I)=0 indicates that LGTEMP(I) holds a guess which is free to be fitted. A positive value TF(I)=I indicates that LGTEMP(I) is fixed. A positive value TF(I)=J<I indicates that LGTEMP(I) has to keep a fixed ratio to LGTEMP(J).
REMASK
REMASK = _LOGICAL (Read) Reply YES to have another chance for improving the mask. [NO]
REGUESS
REGUESS = _LOGICAL (Read) Reply YES to have another chance for improving the guess and fit. [NO]
FITGOOD
FITGOOD = _LOGICAL (Read) Reply YES to store the result in the Specdre Extension. [YES]
COMP
COMP = _INTEGER (Read) The results are stored in the Specdre Extension of the data. This parameter specifies which existing components are being fitted. You should give NCOMP values, which should all be different and which should be between zero and the number of components that are currently stored in the Extension. Give a zero for a hitherto unknown component. If a COMP element is given as zero or if it specifies a component unfit to store the results of this routine, then a new component will be created in the result storage structure. In any case this routine will report which components were actually used and it will deposit the updated values in the parameter system. [1,2,3,4,5,6]
LOGFIL
LOGFIL = FILENAME (Read) The file name of the log file. Enter the null value (!) to disable logging. The log file is opened for append. [!]
Source comments:
     F I T B B
  
     This routine fits up to six diluted Planck curves to a
     one-dimensional data set. This can be specified as an NDF section.
     The data set must extend along the spectroscopic axis. The fit is
     done on a double logarithmic representation of the data. The axis
     data must be the common logarithm of frequency in Hertz. The data
     themselves must be the common logarithm of intensity or flux
     density in arbitrary units.
  
     A diluted Plank component is defined as
                                                            3
          f_j     Theta_j        alpha_j                  nu
        10    = 10        (nu/Hz)        (2h/c^2)  -------------------
                                                     exp(hnu/kT_j) - 1
  
     This assumes that the optical depth is small and the emissivity is
     proportional to the frequency to the power of alpha. 10^Theta is
     the hypothetical optical depth at frequency 1 Hz.
  
     If the optical depth is large, a single simple Planck function
     should be fitted, i.e. only one component with alpha = 0. In this
     case 10^Theta is the conversion factor from the Planck function in
     Jy/sr to the (linear) data values. If for example the data are the
     common logarithm of the calibrated flux density of a source in Jy,
     then Theta is the logarithm of the solid angle (in sr) subtended
     by the source.
  
     The fit is performed in double logarithmic representation, i.e.
     the fitted function is
  
        f = lg[ sum_j 10^f_j ]
  
     The choice of Theta, alpha and lg(T) as fit parameters is
     intuitive, but makes the fit routine ill-behaved. Very often alpha
     cannot be fitted at all and must be fixed. Theta and alpha usually
     anti-correlate completely. Even with fixed alpha do Theta and lg(T)
     anti-correlate strongly.
  
     Furthermore, Theta is difficult to guess. From any initial guess
     of Theta one can improve by using Theta plus the average
     deviation of the data from the guessed spectrum.
  
     After accessing the data and the (optional) plot device, the data
     will be subjected to a mask that consists of up to six abscissa
     intervals. These may or may not overlap and need not lie within
     the range of existing data. The masking will remove data which are
     bad, have bad variance or have zero variance. The masking will
     also provide weights for the fit. If the given data have no
     variances attached, or if the variances are to be ignored, all
     weights will be equal.
  
     After the data have been masked, guessed values for the fit are
     required. These are
  
     -  the number of components to be fitted,
  
     -  the components’ guessed scaling constants Theta,
  
     -  emissivity exponents alpha and
  
     -  common logarithms of colour temperatures in Kelvin. Finally,
  
     -  fit flags for each of the parameters are needed.
  
     The fit flags specify whether any parameter is fixed, fitted, or
     kept at a constant offset to another fitted parameter.
  
     The masked data and parameter guesses are then fed into the fit
     routine. Single or multiple fits are made. Fit parameters may be
     free, fixed, or tied to the corresponding parameter of another
     component fitted at the same time. They are tied by fixing the
     offset, Up to six components can be fitted simultaneously.
  
     The fit is done by minimising chi-squared (or rms if variances are
     unavailable or are chosen to be ignored). The covariances between
     fit parameters - and among these the uncertainties of parameters -
     are estimated from the curvature of psi-squared. psi-squared is
     usually the same as chi-squared. If, however, the given data are
     not independent measurements, a slightly modified function
     psi-squared should be used, because the curvature of chi-squared
     gives an overoptimistic estimate of the fit parameter uncertainty.
     In that function the variances of the given measurements are
     substituted by the sums over each row of the covariance matrix of
     the given data. If the data have been re-sampled with a Specdre
     routine, that routine will have stored the necessary additional
     information in the Specdre Extension, and this routine will
     automatically use that information to assess the fit parameter
     uncertainties. A full account of the psi-squared function is given
     in Meyerdierks, 1992a/b. But note that these covariance row sums
     are ignored if the main variance is ignored or unavailable.
  
     If the fit is successful, then the result is reported to
     the standard output device and plotted on the graphics device. The
     final plot view port is saved in the AGI data base and can be used
     by further applications.
  
     The result is stored in the Specdre Extension of the input NDF.
     Optionally, the complete description (input NDF name, mask used,
     result, etc.) is written (appended) to an ASCII log file.
  
     Optionally, the application can interact with the user. In that
     case, a plot is provided before masking, before guessing and
     before fitting. After masking, guessing and fitting, a screen
     report and a plot are provided and the user can improve the
     parameters. Finally, the result can be accepted or rejected, that
     is, the user can decide whether to store the result in the Specdre
     Extension or not.
  
     The screen plot consists of two view ports. The lower one shows the
     data values (full-drawn bin-style) overlaid with the guess or fit
     (dashed line-style). The upper box shows the residuals (cross
     marks) and error bars. The axis scales are arranged such that
     all masked data can be displayed. The upper box displays a
     zero-line for reference, which also indicates the mask.
  
     The Extension provides space to store fit results for each
     non-spectroscopic coordinate. Say, if you have a 2-D image each
     row being a spectrum, then you can store results for each row. The
     whole set of results can be filled successively by fitting one row
     at a time and always using the same component number to store the
     results for that row. (See also the example.)
  
     The components fitted by this routine are specified as follows:
     The line names and laboratory frequencies are the default values
     and are not checked against any existing information in the
     input’s Specdre Extension. The component types are ’Planck’. The
     numbers of parameters allocated to each component are 3, the
     three guessed and fitted parameters. The parameter types are in
     order of appearance: ’Theta’, ’alpha’, ’lg(T)’.
  
Examples:
  fitbb in device=xw mask1=10.5 mask2=14.5
        ncomp=1 theta=0.5 alpha=0 lgtemp=3.5 sf=0 af=1 tf=0
        comp=1 logfil=planck
     This fits a Planck curve to the range of frequencies between
     about 30 GHz and 3E14 Hz. The temperature is guessed to be
     3000 K. The fit result is reported to the text file PLANCK and
     stored as component number 1 in the input file’s Specdre
     Extension.
     Since DIALOG is not turned off, the user will be prompted for
     improvements of the mask and guess, and will be asked whether
     the final fit result is to be accepted (stored in the Extension
     and written to planck).
     The xwindows graphics device will display the spectrum before
     masking, guessing, and fitting. Independent of the DIALOG
     switch, a plot is produced after fitting.
Notes:
This routine recognises the Specdre Extension v. 0.7.

This routine works in situ and modifies the input file.

References:
Meyerdierks, H., 1992a, Covariance in resampling and model fitting, Starlink, Spectroscopy Special Interest Group

Meyerdierks, H., 1992b, Fitting resampled spectra, in P.J. Grosbol, R.C.E. de Ruijsscher (eds), 4th ESO/ST-ECF Data Analysis Workshop, Garching, 13 - 14 May 1992, ESO Conference and Workshop Proceedings No. 41, Garching bei Muenchen, 1992

D.90 FITCONT-Fits a Chebyshev polynomial to the continuum for 2D data

Description:
As with VIG, lines can be excluded from the polynomial fitting. FITCONT stores the polynomial fitting coefficients in the actual data file, for use by LONGSLIT (the program is specfically for use with LONGSLIT, and of no use otherwise).
Parameters:
IMAGE
IMAGE = FILE (Read) Input file
XSECT
XSECT = INTEGER (Read) Cross-section to take first cut from
Source comments:
    none available
  

D.91 FITGAUSS-Fit Gauss profiles to a spectrum.

Usage:

fitgauss in device=? mask1=? mask2=? ncomp=? cont=? centre=? peak=? fwhm=? cf=? pf=? wf=? comp=? logfil=?

Description:
This routine fits up to six Gauss profiles at a time to a one-dimensional data set. This can be specified as an NDF section. The data set must extend along the spectroscopic axis.
Parameters:
INFO
INFO = _LOGICAL (Read) If false, this routine will issue only error messages and no informational message. [YES]
VARUSE
VARUSE = _LOGICAL (Read) If false, input variances are ignored. [YES]
DIALOG
DIALOG = _CHAR (Read) If ’T’, the routine offers in general more options for interaction. The mask or guess can be improved after inspections of a plot. Also, the routine can resolve uncertainties about where to store results by consulting the user. [’T’]
IN
IN = NDF (Read) The input NDF. This must be a one-dimensional (section of an) NDF. You can specify e.g. an image column as IN(5,) or part of an image row as IN(2.2:3.3,10). Update access is necessary to store the fit result in the NDF’s Specdre Extension.
REPAIR
REPAIR = _LOGICAL (Read) If DIALOG is true, REPAIR can be set true in order to change the spectroscopic number axis in the Specdre Extension. [NO]
DEVICE
DEVICE = DEVICE (Read) The name of the plot device. Enter the null value (!) to disable plotting. [!]
MASK1
MASK1( 6 ) = _REAL (Read) Lower bounds of mask intervals. The mask is the part(s) of the spectrum that is (are) fitted and plotted. The mask is put together from up to six intervals:

mask = [MASK1(1);MASK2(1)] U [MASK1(2);MASK1(2)] U ... U [MASK1(MSKUSE);MASK2(MSKUSE)].

The elements of the MASK parameters are not checked for monotony. Thus intervals may be empty or overlapping. The number of intervals to be used is derived from the number of lower/upper bounds entered. Either MASK1 or MASK2 should be entered with not more numbers than mask intervals required.

MASK2
MASK2( 6 ) = _REAL (Read) Upper bounds of mask intervals. See MASK1.
NCOMP
NCOMP = _INTEGER (Read) The number of Gauss profiles to be fitted. Must be between 1 and 6. [1]
CONT
CONT = _REAL (Read) This value indicates the level of the continuum. Any constant value for CONT is acceptable. [0]
CENTRE
CENTRE( 6 ) = _REAL (Read) Guess centre position for each Gauss component.
PEAK
PEAK( 6 ) = _REAL (Read) Guess peak height for each Gauss component.
FWHM
FWHM( 6 ) = _REAL (Read) Guess full width at half maximum for each Gauss component.
CF
CF( 6 ) = _INTEGER (Read) For each Gauss component I, a value CF(I)=0 indicates that CENTRE(I) holds a guess which is free to be fitted. A positive value CF(I)=I indicates that CENTRE(I) is fixed. A positive value CF(I)=J<I indicates that CENTRE(I) has to keep a fixed offset from CENTRE(J).
PF
PF( 6 ) = _INTEGER (Read) For each Gauss component I, a value PF(I)=0 indicates that PEAK(I) holds a guess which is free to be fitted. A positive value PF(I)=I indicates that PEAK(I) is fixed. A positive value PF(I)=J<I indicates that PEAK(I) has to keep a fixed ratio to PEAK(J).
WF
WF( 6 ) = _INTEGER (Read) For each Gauss component I, a value WF(I)=0 indicates that FWHM(I) holds a guess which is free to be fitted. A positive value WF(I)=I indicates that FWHM(I) is fixed. A positive value WF(I)=J<I indicates that FWHM(I) has to keep a fixed ratio to FWHM(J).
REMASK
REMASK = _LOGICAL (Read) Reply YES to have another chance for improving the mask. [NO]
REGUESS
REGUESS = _LOGICAL (Read) Reply YES to have another chance for improving the guess and fit. [NO]
FITGOOD
FITGOOD = _LOGICAL (Read) Reply YES to store the result in the Specdre Extension. [YES]
COMP
COMP = _INTEGER (Read) The results are stored in the Specdre Extension of the data. This parameter specifies which existing components are being fitted. You should give NCOMP values, which should all be different and which should be between zero and the number of components that are currently stored in the Extension. Give a zero for a hitherto unknown component. If a COMP element is given as zero or if it specifies a component unfit to store the results of this routine, then a new component will be created in the result storage structure. In any case this routine will report which components were actually used and it will deposit the updated values in the parameter system. [1,2,3,4,5,6]
LOGFIL
LOGFIL = FILENAME (Read) The file name of the log file. Enter the null value (!) to disable logging. The log file is opened for append. [!]
FCENTRE
FCENTRE( 6 ) = _REAL (Write) Fitted centre position for each Gauss component.
FPEAK
FPEAK( 6 ) = _REAL (Write) Fitted peak height for each Gauss component.
FFWHM
FFWHM( 6 ) = _REAL (Write) Fitted full width at half maximum for each Gauss component.
Source comments:
     After accessing the data and the (optional) plot device, the data
     will be subjected to a mask that consists of up to six abscissa
     intervals. These may or may not overlap and need not lie within
     the range of existing data. The masking will remove data which are
     bad, have bad variance or have zero variance. The masking will
     also provide weights for the fit. If the given data have no
     variances attached, or if the variances are to be ignored, all
     weights will be equal.
  
     After the data have been masked, guessed values for the fit are
     required. These are
  
     -  the number of components to be fitted,
     -  the value of any underlying constant continuum (this must be an
        a-priori known constant),
     -  the components’ guessed centre positions,
     -  peak heights and
     -  full widths at half maxima. Finally,
     -  fit flags for each of the Gauss parameters are needed.
  
     The fit flags specify whether any parameter is fixed, fitted, or
     kept at a constant ratio or offset to another fitted parameter.
  
     The masked data and parameter guesses are then fed into the fit
     routine. Single or multiple Gauss fits are made to line features.
     Gauss fit parameters may be free, fixed, or tied to the
     corresponding parameter of another Gauss component fitted at the
     same time. Peak and width are tied by fixing the ratios, the
     centre is tied by fixing the offset. Up to six Gauss components
     can be fitted simultaneously.
  
     The fit is done by minimising chi-squared (or rms if variances are
     unavailable or are chosen to be ignored). The covariances between
     fit parameters - and among these the uncertainties of parameters -
     are estimated from the curvature of psi-squared. psi-squared is
     usually the same as chi-squared. If, however, the given data are
     not independent measurements, a slightly modified function
     psi-squared should be used, because the curvature of chi-squared
     gives an overoptimistic estimate of the fit parameter uncertainty.
     In that function the variances of the given measurements are
     substituted by the sums over each row of the covariance matrix of
     the given data. If the data have been re-sampled with a Specdre
     routine, that routine will have stored the necessary additional
     information in the Specdre Extension, and this routine will
     automatically use that information to assess the fit parameter
     uncertainties. A full account of the psi-squared function is given
     in Meyerdierks, 1992a/b. But note that these covariance row sums
     are ignored if the main variance is ignored or unavailable.
  
     If the fit is successful, then the result is reported to
     the standard output device and plotted on the graphics device. The
     final plot view port is saved in the AGI data base and can be used
     by further applications.
  
     The result is stored in the Specdre Extension of the input NDF.
     Optionally, the complete description (input NDF name, mask used,
     result, etc.) is written (appended) to an ASCII log file.
  
     Optionally, the application can interact with the user. In that
     case, a plot is provided before masking, before guessing and
     before fitting. After masking, guessing and fitting, a screen
     report and a plot are provided and the user can improve the
     parameters. Finally, the result can be accepted or rejected, that
     is, the user can decide whether to store the result in the Specdre
     Extension or not.
  
     The screen plot consists of two view ports. The lower one shows the
     data values (full-drawn bin-style) overlaid with the guess or fit
     (dashed line-style). The upper box shows the residuals (cross
     marks) and error bars. The axis scales are arranged such that
     all masked data can be displayed. The upper box displays a
     zero-line for reference, which also indicates the mask.
  
     The Extension provides space to store fit results for each
     non-spectroscopic coordinate. Say, if you have a 2-D image each
     row being a spectrum, then you can store results for each row. The
     whole set of results can be filled successively by fitting one row
     at a time and always using the same component number to store the
     results for that row. (See also the example.)
  
     The components fitted by this routine are specified as follows:
     The line names and laboratory frequencies are the default values
     and are not checked against any existing information in the
     input’s Specdre Extension. The component types are ’Gauss’. The
     numbers of parameters allocated to each component are 4, the
     three guessed and fitted parameters and the line integral. The
     parameter types are in order of appearance: ’centre’, ’peak’,
     ’FWHM’, ’integral’.
  
Examples:
  fitgauss in device=xw mask1=-1.5 mask2=2.5
        ncomp=1 cont=1.0 centre=0.5 peak=-0.5 fwhm=1.5 cf=0 pf=0 wf=0
        comp=1 logfil=line
     This fits a single Gauss profile to the x range [-1.5,2.5]. The
     continuum is assumed to be constant at 1.0. The Gauss is
     guessed to be centred at 0.5 with width 1.5. It is guessed to
     be an absorption line with an amplitude of -0.5.
     All Gauss parameters are free to be fitted. The fit result is
     reported to the text file line and stored as component
     number 1 in the input file’s Specdre Extension.
     Since DIALOG is not turned off, the user will be prompted for
     improvements of the mask and guess, and will be asked whether
     the final fit result is to be accepted (stored in the Extension
     and written to line).
     The xwindows graphics device will display the spectrum before
     masking, guessing, and fitting. Independent of the DIALOG
     switch, a plot is produced after fitting.
  
  fitgauss in(,5) device=! mask1=-1.5 mask2=2.5
        ncomp=1 cont=0.0 centre=0.5 peak=13.0 fwhm=1.5 cf=0 pf=0 wf=1
        comp=0 logfil=! dialog=f
     This fits a single Gauss profile to the x range [-1.5,2.5] of
     the 5th row in the 2-D image IN. The baseline is assumed to be
     constant at 0.0. The Gauss is guessed to be centred at 0.5 with
     width 1.5. It is guessed to be an emission line with an
     amplitude of 13. Centre position and peak height are free to be
     fitted, but the width is fixed to 1.5. User interaction
     (DIALOG) and plotting (DEVICE) are de-selected. There is also no
     log file where to the results are written. If INFO were also
     switched off, no report whatsoever would be made. However, the
     results are stored as a new component (COMP=0) in the Specdre
     Extension of the input file.
Notes:
This routine recognises the Specdre Extension v. 0.7.

This routine works in situ and modifies the input file.

References:
Meyerdierks, H., 1992a, Covariance in resampling and model fitting, Starlink, Spectroscopy Special Interest Group

Meyerdierks, H., 1992b, Fitting resampled spectra, in P.J. Grosbol, R.C.E. de Ruijsscher (eds), 4th ESO/ST-ECF Data Analysis Workshop, Garching, 13 - 14 May 1992, ESO Conference and Workshop Proceedings No. 41, Garching bei Muenchen, 1992

D.92 FITPOLY-Fit a polynomial to a spectrum.

Usage:

fitpoly in device=? mask1=? mask2=? order=? comp=? logfil=?

Description:

This routine fits a polynomial to a one-dimensional data set. This can be specified as an NDF section. The data set must extend along the spectroscopic axis.

Parameters:
INFO
INFO = _LOGICAL (Read) If false, the routine will issue only error messages and no informational messages. [YES]
VARUSE
VARUSE = _LOGICAL (Read) If false, input variances are ignored. [YES]
DIALOG
DIALOG = _CHAR (Read) If ’T’, the routine offers in general more options for interaction. The mask or guess can be improved after inspections of a plot. Also, the routine can resolve uncertainties about where to store results by consulting the user. [’T’]
IN
IN = NDF (Read) The input NDF. This must be a one-dimensional (section of an) NDF. You can specify e.g. an image column as IN(5,) or part of an image row as IN(2.2:3.3,10). Update access is necessary to store the fit result in the NDF’s Specdre Extension.
REPAIR
REPAIR = _LOGICAL (Read) If DIALOG is true, REPAIR can be set true in order to change the spectroscopic number axis in the Specdre Extension. [NO]
DEVICE
DEVICE = DEVICE (Read) The name of the plot device. Enter the null value (!) to disable plotting. [!]
MASK1
MASK1( 6 ) = _REAL (Read) Lower bounds of mask intervals. The mask is the part(s) of the spectrum that is (are) fitted and plotted. The mask is put together from up to six intervals:

mask = [MASK1(1);MASK2(1)] U [MASK1(2);MASK1(2)] U ... U [MASK1(MSKUSE);MASK2(MSKUSE)].

The elements of the MASK parameters are not checked for monotony. Thus intervals may be empty or overlapping. The number of intervals to be used is derived from the number of lower/upper bounds entered. Either MASK1 or MASK2 should be entered with not more numbers than mask intervals required.

MASK2
MASK2( 6 ) = _REAL (Read) Upper bounds of mask intervals. See MASK1.
ORDER
ORDER = _INTEGER (Read) The polynomial order of the fit. Must be between 0 and 7. [1]
REMASK
REMASK = _LOGICAL (Read) Reply YES to have another chance for improving the mask. [NO]
REGUESS
REGUESS = _LOGICAL (Read) Reply YES to have another chance for improving the guess and fit. [NO]
FITGOOD
FITGOOD = _LOGICAL (Read) Reply YES to store the result in the Specdre Extension. [YES]
COMP
COMP = _INTEGER (Read and Write) The results are stored in the Specdre Extension of the data. This parameter specifies which existing component is being fitted. It should be between zero and the number of components that are currently stored in the Extension. Give zero for a hitherto unknown component. If COMP is given as zero or if it specifies a component unfit to store the results of this routine, then a new component will be created in the result storage structure. In any case this routine will report which component was actually used and it will deposit the updated value in the parameter system. [1]
LOGFIL
LOGFIL = FILENAME (Read) The file name of the log file. Enter the null value (!) to disable logging. The log file is opened for append. [!]
Source comments:
     F I T P O L Y
  
     After accessing the data and the (optional) plot device, the data
     will be subjected to a mask that consists of up to six abscissa
     intervals. These may or may not overlap and need not lie within
     the range of existing data. The masking will remove data which are
     bad, have bad variance or have zero variance. The masking will
     also provide weights for the fit. If the given data have no
     variances attached, or if the variances are to be ignored, all
     weights will be equal.
  
     The masked data are then fed into the fit routine. The highest
     polynomial order possible is 7. The fit weights data points
     according to their errors. The coefficients reported are those of
     an ordinary polynomial. Let (x,y) be the measurements, y(x) be the
     polynomial of order n fitting the measurements, c_i (i = 1, ...,
     n+1) be the fitted coefficients. Then y(x) can be calculated as
  
        y(x) = c_1 + c_2 x + c_3 x**2 + ... + c_{n+1} x**n
  
     If the fit is successful, then the result is reported to the
     screen and plotted on the graphics device. The final plot view port
     is saved in the AGI data base and can be used by further
     applications.
  
     The result is stored in the Specdre Extension of the input NDF.
     Optionally, the complete description (input NDF name, mask used,
     result, etc.) is written (appended) to an ASCII log file.
  
     Optionally, the application can interact with the user. In that
     case, a plot is provided before masking and before specifying the
     polynomial order. After masking and fitting, a screen report and a
     plot (optional) are provided and the user can improve the
     parameters. Finally, the result can be accepted or rejected, that
     is the user can decide whether to store the result in the Specdre
     Extension or not.
  
     The screen plot consists of two view ports. The lower one shows the
     data values (full-drawn bin-style) overlaid with the fit (dashed
     line-style). The upper box shows the residuals (cross marks)
     and error bars. The axis scales are arranged such that
     all masked data can be displayed. The upper box displays a
     zero-line for reference, which also indicates the mask.
  
     The Extension provides space to store fit results for each
     non-spectroscopic coordinate. Say, if you have a 2-D image each
     row being a spectrum, then you can store results for each row. The
     whole set of results can be filled successively by fitting one row
     at a time and always using the same component number to store the
     results for that row. (See also the example.)
  
     The component fitted by this routine is specified as follows: The
     line name and laboratory frequency are the default values and are
     not checked against any existing information in the input’s
     Specdre Extension. The component type is ’polynomial’. The
     number of parameters allocated to the component is 9. The
     parameter types are in order of appearance: ’order’, ’coeff0’,
     ... ’coeff7’. Unused coefficient are stored as zero.
  
Examples:
  fitpoly in device=! mask1=2.2 mask2=3.3 order=3 comp=1 logfil=!
     IN is a 1-D NDF. A 3rd order fit is made to the abscissa range
     between 2.2 and 3.3. The result is stored in component number 1
     of the result structure in the Specdre Extension of IN. The
     plot device and ASCII log file are de-selected.
  
  fitpoly in(,15) device=xw mask1=[2.0,2.3,3.4] mask2=[2.1,3.2,4.0]
        order=2 comp=0 logfil=myfil
     Here IN is 2-D and the 15th row is selected as the 1-D input
     for the fit. The mask consists of three intervals
     [2.0;2.1] U [2.3;3.2] U [3.4,4.0]. The fit is a parabola. Space
     for a new component is created for storage in the Specdre
     Extension. The plot device is xwindows.
  
  fitpoly in(,20) device=xw mask1=[2.0,2.3,3.4] mask2=[2.1,3.2,4.0]
        order=4 comp=2 logfil=myfil
     In a follow-up from the previous example, now the 20th row is
     fitted with 4th order. If in the previous run the routine told
     us that it had used component number 2, then COMP=2 is what we
     want to use to store a similar fit for a different row.
     The first time round, the description of component 2 was
     created, saying that it is a polynomial with order of 7
     or less etc. And the fit result for the 15th row was stored in
     an array that has space for all rows in the input file.
     So the second time round, FITPOLY checks whether component 2
     is suitable, whether it is a polynomial with maximum
     order 7. It then stores the new result for the 20th row in the
     place reserved for this row.
     Gradually all rows can be fitted and their results stored in
     the Extension. Possibly this could be automated by writing a
     looping ICL procedure or shell script.
     In the end the corresponding results for all rows are stored in
     one data structure, and could for example be converted into a
     plot of the n-th parameter value versus row number.
Notes:
This routine recognises the Specdre Extension v. 0.7.

This routine works in situ and modifies the input file.

D.93 FITSET-Set the value of a FITS keyword

Description:
FIGARO program to set (or modify) a FITS keyword in a Figaro file. This program accepts the name of a single FITS keyword and a new value for it. If the keyword already exists it will be changed, unless it is one of the special keywords ("HISTORY", "COMMENT", or ’blank’) that can have multiple values, in which case the new value will be added to those already in the file.
Parameters:
FILE
The name of the Figaro file one of whose keywords is to be changed.
KEYWORD
The name of the FITS keyword to be set or modified. If the keyword already exists it will be listed by the program. Note that FITS keyword names should be limited to 8 characters in length, but this is not enforced by this program. Note: if you set the value of one of the standard keywords that can be deduced from the rest of the data in the file, such as ’NAXIS’ or ’CRDELTn’ or ’BITPIX’ you may get confusing results. This is not recommended.
VALUE
The new value for the FITS keyword specified. This is specified as a character string, so may need to be given enclosed by quotes. Note that the FITS standard limits character values to upper case, so any lower case characters will be folded to upper case. If the value is to be treated as a logical value, it should be either ’T’ or ’F’. Numeric and logical values are treated slightly differently to the way string values are treated. By default, if the value given can be interpreted as a number by FITSET then it will be; otherwise it will be treated as a literal string. This can be overriden by the STRING and LOGICAL keywords.
COMMENT
Each FITS keyword has a comment string associated with it. COMMENT supplies the comment string to be associated with the KEYWORD being set. If a keyword already exists, then the exisitng comment (if any) is used as the default comment.
LOGICAL
If LOGICAL is set, then FITSET will treat the supplied value as a logical one. In this case the string supplied for VALUE must have been either ’T’ or ’F’. Logical values are stored internally in FITS files slightly differently to the way string values are treated. In most cases, this doesn’t matter much, but systems other than Figaro may be fussy about the types of specific keywords.
STRING
If STRING is set, then FITSET will treat the supplied value as a literal character string, even if it can be interpreted as a number. Numeric values are stored internally in FITS files slightly differently to the way string values are treated. In most cases, this doesn’t matter much, but systems other than Figaro may be fussy about the types of specific keywords.
Source comments:
   F I T S E T
  
   Function:
      Figaro routine to set (or modify) a FITS keyword in a file.
  
   Description:
      This routine allows a FITS keyword in a file to be set or, if it
      already exists, to be modified. This routine is needed mainly because
      of the difficulty of changing items in a FITS header when the file
      in question is in NDF format. (A .DST file has the FITS information
      in separate structure items which can easily be modified using LET,
      but an NDF format file has all the FITS keywords in a single
      character array which is not amenable to such changes.)
  
   Invocation:
      FITSET file keyword value comment [logical] [string]
  
   Parameters:
      file     (Filename) The name of the Figaro format file in which the
               keyword is to be set.
      keyword  (Character string) The name of the FITS keyword that is to be
               set.
      value    (Character string) The new value of the FITS keyword. If
               this can be interpreted as a numeric value it will be set as
               such. Otherwise it will be kept as a character string.
      comment  (Character string) The comment to be associated with the
               keyword.
      logical  (Keyword) If set, forces the value to be treated as a logical
               value, in which case it must be one of ’T’ or ’F’ and will
               be set as such in the output file.
      string   (Keyword) If set, forces the value to be treated as a literal
               string; in this case it will not be treated as a number even if
               it can be.
  
      Keith Shortridge, AAO.

D.94 FITSKEYS-List the FITS keywords in a data file

Description:
FITSKEYS lists all the items in the FITS-specific sub-structure associated with a specified data structure.
Parameters:
INPUT
INPUT can be any Figaro structure. If it has any items in a FITS substructure, these are listed.
See also:
FIGARO: RDFITS, WDFITS.
KAPPA: FITSDIN, FITSIN, FITSHEAD, FITSIMP, FITSLIST.
Source comments:
   F I T S K E Y S
  
   Name: FITSKEYS
  
   Function:
      List the contents of a FITS-specific structure.
  
   Description:
      This Figaro program lists all the items in the FITS-specific
      substructure associated with a data structure.  It doesn’t
      give any information that can’t be obtained using hdstrace, but
      it presents it in a more convenient form, especially when the
      structure contains multiple comment keywords.
  
   Command Parameters:
      INPUT     (Character) Name of structure whose FITS substructure
                is to be listed.
  
   Command keywords: None.
  
   K. Shortridge, AAO

D.95 FITTRI-Fit triangular profiles to a spectrum.

Usage:

fittri in device=? mask1=? mask2=? ncomp=? cont=? centre=? peak=? fwhm=? cf=? pf=? wf=? comp=? logfil=?

Description:

This routine fits up to six triangular profiles at a time to a one-dimensional data set. This can be specified as an NDF section. The data set must extend along the spectroscopic axis.

Parameters:
INFO
INFO = _LOGICAL (Read) If false, this routine will issue only error messages and no informational message. [YES]
VARUSE
VARUSE = _LOGICAL (Read) If false, input variances are ignored. [YES]
DIALOG
DIALOG = _CHAR (Read) If ’T’, the routine offers in general more options for interaction. The mask or guess can be improved after inspections of a plot. Also, the routine can resolve uncertainties about where to store results by consulting the user. [’T’]
IN
IN = NDF (Read) The input NDF. This must be a one-dimensional (section of an) NDF. You can specify e.g. an image column as IN(5,) or part of an image row as IN(2.2:3.3,10). Update access is necessary to store the fit result in the NDF’s Specdre Extension.
REPAIR
REPAIR = _LOGICAL (Read) If DIALOG is true, REPAIR can be set true in order to change the spectroscopic number axis in the Specdre Extension. [NO]
DEVICE
DEVICE = DEVICE (Read) The name of the plot device. Enter the null value (!) to disable plotting. [!]
MASK1
MASK1( 6 ) = _REAL (Read) Lower bounds of mask intervals. The mask is the part(s) of the spectrum that is (are) fitted and plotted. The mask is put together from up to six intervals:

mask = [MASK1(1);MASK2(1)] U [MASK1(2);MASK1(2)] U ... U [MASK1(MSKUSE);MASK2(MSKUSE)].

The elements of the MASK parameters are not checked for monotony. Thus intervals may be empty or overlapping. The number of intervals to be used is derived from the number of lower/upper bounds entered. Either MASK1 or MASK2 should be entered with not more numbers than mask intervals required.

MASK2
MASK2( 6 ) = _REAL (Read) Upper bounds of mask intervals. See MASK1.
NCOMP
NCOMP = _INTEGER (Read) The number of triangle profiles to be fitted. Must be between 1 and 6. [1]
CONT
CONT = _REAL (Read) This value indicates the level of the continuum. Any constant value for CONT is acceptable. [0]
CENTRE
CENTRE( 6 ) = _REAL (Read) Guess centre position for each triangle component.
PEAK
PEAK( 6 ) = _REAL (Read) Guess peak height for each triangle component.
FWHM
FWHM( 6 ) = _REAL (Read) Guess full width at half maximum for each triangle component.
CF
CF( 6 ) = _INTEGER (Read) For each triangle component I, a value CF(I)=0 indicates that CENTRE(I) holds a guess which is free to be fitted. A positive value CF(I)=I indicates that CENTRE(I) is fixed. A positive value CF(I)=J<I indicates that CENTRE(I) has to keep a fixed offset from CENTRE(J).
PF
PF( 6 ) = _INTEGER (Read) For each triangle component I, a value PF(I)=0 indicates that PEAK(I) holds a guess which is free to be fitted. A positive value PF(I)=I indicates that PEAK(I) is fixed. A positive value PF(I)=J<I indicates that PEAK(I) has to keep a fixed ratio to PEAK(J).
WF
WF( 6 ) = _INTEGER (Read) For each triangle component I, a value WF(I)=0 indicates that FWHM(I) holds a guess which is free to be fitted. A positive value WF(I)=I indicates that FWHM(I) is fixed. A positive value WF(I)=J<I indicates that FWHM(I) has to keep a fixed ratio to FWHM(J).
REMASK
REMASK = _LOGICAL (Read) Reply YES to have another chance for improving the mask. [NO]
REGUESS
REGUESS = _LOGICAL (Read) Reply YES to have another chance for improving the guess and fit. [NO]
FITGOOD
FITGOOD = _LOGICAL (Read) Reply YES to store the result in the Specdre Extension. [YES]
COMP
COMP = _INTEGER (Read) The results are stored in the Specdre Extension of the data. This parameter specifies which existing components are being fitted. You should give NCOMP values, which should all be different and which should be between zero and the number of components that are currently stored in the Extension. Give a zero for a hitherto unknown component. If a COMP element is given as zero or if it specifies a component unfit to store the results of this routine, then a new component will be created in the result storage structure. In any case this routine will report which components were actually used and it will deposit the updated values in the parameter system. [1,2,3,4,5,6]
LOGFIL
LOGFIL = FILENAME (Read) The file name of the log file. Enter the null value (!) to disable logging. The log file is opened for append. [!]
Source comments:
     F I T T R I
  
     After accessing the data and the (optional) plot device, the data
     will be subjected to a mask that consists of up to six abscissa
     intervals. These may or may not overlap and need not lie within
     the range of existing data. The masking will remove data which are
     bad, have bad variance or have zero variance. The masking will
     also provide weights for the fit. If the given data have no
     variances attached, or if the variances are to be ignored, all
     weights will be equal.
  
     After the data have been masked, guessed values for the fit are
     required. These are
  
     -  the number of components to be fitted,
     -  the value of any underlying constant continuum (this must be an
        a-priori known constant),
     -  the components’ guessed centre positions,
     -  peak heights and
     -  full widths at half maxima. Finally,
     -  fit flags for each of the triangle parameters are needed.
  
     The fit flags specify whether any parameter is fixed, fitted, or
     kept at a constant ratio or offset to another fitted parameter.
  
     The masked data and parameter guesses are then fed into the fit
     routine. Single or multiple triangle fits are made to line
     features. Triangle fit parameters may be free, fixed, or tied to
     the corresponding parameter of another triangle component fitted
     at the same time. Peak and width are tied by fixing the ratios,
     the centre is tied by fixing the offset. Up to six triangle
     components can be fitted simultaneously.
  
     The fit is done by minimising chi-squared (or rms if variances are
     unavailable or are chosen to be ignored). The covariances between
     fit parameters - and among these the uncertainties of parameters -
     are estimated from the curvature of psi-squared. psi-squared is
     usually the same as chi-squared. If, however, the given data are
     not independent measurements, a slightly modified function
     psi-squared should be used, because the curvature of chi-squared
     gives an overoptimistic estimate of the fit parameter uncertainty.
     In that function the variances of the given measurements are
     substituted by the sums over each row of the covariance matrix of
     the given data. If the data have been re-sampled with a Specdre
     routine, that routine will have stored the necessary additional
     information in the Specdre Extension, and this routine will
     automatically use that information to assess the fit parameter
     uncertainties. A full account of the psi-squared function is given
     in Meyerdierks, 1992a/b. But note that these covariance row sums
     are ignored if the main variance is ignored or unavailable.
  
     If the fit is successful, then the result is reported to
     the standard output device and plotted on the graphics device. The
     final plot view port is saved in the AGI data base and can be used
     by further applications.
  
     The result is stored in the Specdre Extension of the input NDF.
     Optionally, the complete description (input NDF name, mask used,
     result, etc.) is written (appended) to an ASCII log file.
  
     Optionally, the application can interact with the user. In that
     case, a plot is provided before masking, before guessing and
     before fitting. After masking, guessing and fitting, a screen
     report and a plot are provided and the user can improve the
     parameters. Finally, the result can be accepted or rejected, that
     is, the user can decide whether to store the result in the Specdre
     Extension or not.
  
     The screen plot consists of two view ports. The lower one shows the
     data values (full-drawn bin-style) overlaid with the guess or fit
     (dashed line-style). The upper box shows the residuals (cross
     marks) and error bars. The axis scales are arranged such that
     all masked data can be displayed. The upper box displays a
     zero-line for reference, which also indicates the mask.
  
     The Extension provides space to store fit results for each
     non-spectroscopic coordinate. Say, if you have a 2-D image each
     row being a spectrum, then you can store results for each row. The
     whole set of results can be filled successively by fitting one row
     at a time and always using the same component number to store the
     results for that row. (See also the example.)
  
     The components fitted by this routine are specified as follows:
     The line names and laboratory frequencies are the default values
     and are not checked against any existing information in the
     input’s Specdre Extension. The component types are ’triangle’. The
     numbers of parameters allocated to each component are 4, the
     three guessed and fitted parameters and the line integral. The
     parameter types are in order of appearance: ’centre’, ’peak’,
     ’FWHM’, ’integral’.
Examples:
  fittri in device=xw mask1=-1.5 mask2=2.5
        ncomp=1 cont=1.0 centre=0.5 peak=-0.5 fwhm=1.5 cf=0 pf=0 wf=0
        comp=1 logfil=line
     This fits a single triangular profile to the x range
     [-1.5,2.5]. The continuum is assumed to be constant at 1.0. The
     triangle is guessed to be centred at 0.5 with width 1.5. It is
     guessed to be an absorption line with an amplitude of -0.5.
     All triangle parameters are free to be fitted. The fit result
     is reported to the text file LINE and stored as component
     number 1 in the input file’s Specdre Extension.
     Since DIALOG is not turned off, the user will be prompted for
     improvements of the mask and guess, and will be asked whether
     the final fit result is to be accepted (stored in the Extension
     and written to line).
     The xwindows graphics device will display the spectrum before
     masking, guessing, and fitting. Independent of the DIALOG
     switch, a plot is produced after fitting.
  
  fittri in(,5) device=! mask1=-1.5 mask2=2.5
        ncomp=1 cont=0.0 centre=0.5 peak=13.0 fwhm=1.5 cf=0 pf=0 wf=1
        comp=0 logfil=! dialog=f
     This fits a single triangular profile to the x range [-1.5,2.5]
     of the 5th row in the 2-D image IN. The baseline is assumed to
     be constant at 0.0. The triangle is guessed to be centred at
     0.5 with width 1.5. It is guessed to be an emission line with
     an amplitude of 13. Centre position and peak height are free to
     be fitted, but the width is fixed to 1.5. User interaction
     (DIALOG) and plotting (DEVICE) are de-selected. There is also no
     log file where to the results are written. If INFO were also
     switched off, no report whatsoever would be made. However, the
     results are stored as a new component (COMP=0) in the Specdre
     Extension of the input file.
Notes:
This routine recognises the Specdre Extension v. 0.7.

This routine works in situ and modifies the input file.

References:
Meyerdierks, H., 1992a, Covariance in resampling and model fitting, Starlink, Spectroscopy Special Interest Group

Meyerdierks, H., 1992b, Fitting resampled spectra, in P.J. Grosbol, R.C.E. de Ruijsscher (eds), 4th ESO/ST-ECF Data Analysis Workshop, Garching, 13 - 14 May 1992, ESO Conference and Workshop Proceedings No. 41, Garching bei Muenchen, 1992

D.96 FLAG2QUAL-Converts ‘flagged’ values to produce a quality array

Description:
FLAG2QUAL removes ’flagged’ (or ’magic’) data values from the main array of a Figaro file. Any such values are replaced either with a single specified data value, or else FLAG2QUAL replaces them with data values obtained by interpolation between the good pixels on each side. (This is not a particularly sophisticated interpolation, but then, these are data values that shouldn’t ever actually be used, since they are still flagged as bad in the quality array.) When FLAG2QUAL replaces a flagged data value it sets the corresponding element of the associated quality array to indicate that the pixel is not to be trusted. If there was already a quality array associated with the data it is used when deciding which pixels to use for interpolation and is updated to reflect those flagged pixels that have been replaced. If the file did not already have a quality array then one is created. Many Figaro routines prefer to use quality arrays when dealing with data, and operate more efficiently if the data is not flagged. Also, there may be some programs that are confused by the presence in the file of flagged data values. Finally, having both forms of data quality information in a file can be confusing and FLAG2QUAL can tidy things up.
Parameters:
INPUT
The name of a Figaro format file that might contain flagged (or ’magic’) data values. It may also contain an associated quality array. Whatever it contains, FLAG2QUAL will process it so that the resulting file has an array that does not contain any flagged data values. Any information that was held in the form of such flagged data values will be held in a quality array in the resulting file.
OUTPUT
The name of the resulting file. This can be the same as the input file, in which case all changes are made in situ. The resulting file will have all its data quality information held in a quality array and will have no flagged data values in its main array.
FIXED
The flagged data values in the input array have to be replaced. If FIXED is set, they are replaced by a single data value specified in the VALUE parameter. If FIXED is not set, then FLAG2QUAL replaces them using values calculated by interpolation between the previous and next good pixels.
VALUE
If FIXED is set, then VALUE is used to specify the single data value to be used to replace the flagged values in the main data array. This can be any value - although it would be perverse to use the actual flag value!
Source comments:
   F L A G 2 Q U A L
  
   Description:
      This is a Figaro program that removes any ’flagged’ values from
      the main data array in a Figaro data file. If there are in fact
      such values in the main data array (many arrays are flagged as
      ’may contain flagged values’, but in fact do not) then this
      routine sets the equivalent elements of an associated quality
      array (which it may have to create).
  
   Command parameters:
  
      INPUT  (Character) The name of the structure containing the data.
  
      OUTPUT (Character) The name of the result of the operation.  This
             can be the same as for INPUT.  If not, a new structure
             is created, with everything but the data a direct
             copy of the input.
  
      VALUE  (Numeric) If a fixed value is to be used to replace flagged
             data values, this supplies that value.
  
   Command keywords:
  
      FIXED  If set, a fixed value (supplied in VALUE) is used
             to replace the flagged data values. If not, the program
             interpolates over them.
  
      11th Feb 1995  KS / AAO.  Original version.
  

D.97 FLAIRCOMP-Compresses a FLAIR frame to give a weight vector.

Description:
This application takes a FLAIR frame stored in an NDF and compresses it along the y axis, normalises the compressed array by its mean value, and then finds the minima in the values and set these to the bad value. Thus it provides the weights for an optimal extraction. It reports the number of fibres found in the NDF.

This assumes stability (x positions of the fibres do not move), and vertical orientation of the fibres. These are satisfied by FLAIR (Parker, private communication).

Usage:
flaircomp in out
Parameters:
IN
The input two-dimensional NDF. This should be the co-added arc or sky flat-field frames, so that the compressed array gives the instrumental response of the detector system.
OUT
The vector of weights to use during optimal extraction.
TITLE
Value for the title of the output NDF. A null (!) propagates the title from input NDF to the output. [!]
Source comments:
   None available.
  

D.98 FLAIREXT-Optimally extracts spectra from a FLAIR NDF to form a new NDF.

Description:
This application takes a FLAIR frame stored in an NDF with the dispersion along the y axis, and extracts the individual spectra using an optimal extraction. It stores the spectra in an output two-dimensional NDF, configured such that the dispersion is along x axis, and wavelength increases with pixel index, and each spectrum occupies one line.

This assumes stability (x positions of the fibres do not move), and vertical orientation of the fibres. These are satisfied by FLAIR (Parker, private communication).

Usage:
flairext in profile out fibres
Parameters:
FIBRES
The number of fibres to extract. This must be in the range 1 to 92. [92]
IN
A list of the input two-dimensional NDFs containing FLAIR spectra to be extracted.
PROFILE
The vector of weights to use during optimal extraction, as derived from FLAIRCOMP.
OUT
The list of the two-dimensional NDF containing the extracted FLAIR spectra. There should be as many files in this list as for parameter IN. The nth item in this list will be the extracted spectra for the nth file in IN.
TITLE
Value for the title of the output NDF. A null value (!) will cause the title of the input NDF to be used. [!]
Source comments:
   None available.
  

D.99 FLCONV-Convert a spectrum in Janskys into one in erg/s/cm**2/Angstrom

Description:
FLCONV generates a spectrum in erg/s/cm**2/Angstrom, given a spectrum in some other units. At present, only Janskys, milli-Janskys and micro-Janskys can be handled.
Parameters:
SPECTRUM
A spectrum whose units are (currently) either Janskys, milli-Janskys, or micro-Janskys. It needs to be wavelength calibrated, in Angstroms.
OUTPUT
The resulting spectrum, whose units will be ergs/s/cm**2/A. OUTPUT can be the same as SPECTRUM, in which case the conversion will be performed in situ.
Source comments:
   A B C O N V  /  F L C O N V  /  I R C O N V
  
   Converts a spectrum into AB magnitudes (ABCONV) or f-lambda
   units (erg/s/cm**2/Angstrom) (FLCONV), or W/m**2/um (IRCONV).
   The original units of the data may be Jy (Janskys), mJy
   (milli-Janskys), or uJy (micro-Janskys). Other possibilities
   may be added later.
  
   Command parameters -
  
   SPECTRUM The name of the structure containing the spectrum.
            currently used for the spectrum.  For FLCONV
            an x-axis data structure giving the wavelengths of the
            data elements is also required.
  
   OUTPUT   The name of the result of the operation.  This can
            be the same as for SPECTRUM. If not, a new structure
            is created, with everything but the data a direct
            copy of the input.
  
   Command keywords  - None
  
   User variables used - None
                                    KS / CIT 18th May 1984

D.100 FOTO-Perform aperture photometry given CENTERS output

Description:
The FOTO command performs aperture photometry on objects in an image.
Parameters:
IMAGE
The name of the image on which the photometry is to be performed. A file giving the centers of the objects in IMAGE to be measured should already have been created, probably by the sequence CPOS, CENTERS.
RA1
The inner radius of the circular aperture to be used to calculate the sky values. It should be large enough to clear the objects being measured.
RA2
The outer radius of the circular aperture to be used to calculate the sky values.
NRADII
The number of circular apertures around the objects being measured for which magnitudes will be calculated.
RADII
The values of the radii of the circular apertures, in pixels, around the objects being measured.
BAD
The value below which pixels will be ignored.
PHOTONS
The number of photons per output unit - i.e. the number of photons actually represented by each count in the data array.
READNS
The expected error in the readout when the data was taken. It is only used in the calculation of the error values.
MZERO
The offset that has to be applied to the calculated magnitudes in order to get the actual magnitude values. If you don’t care about absolute values, you can leave this as zero.
SKYVAL
User-specified sky value.
SIGMA
User-specified sigma.
DISHIST
Used to ask whether sky histogram to be displayed.
CONFIRM
Used to confirm acceptability of sky value and sigma.
Source comments:
   F O T O
  
   Main routine for the Figaro aperture photometry function, FOTO.
   This gets the required parameter values and then leaves the real
   work to PHOTSUB, which is a modification for Figaro of a routine
   originally written at KPNO by Don Wells.
  
   Command parameters -
  
   IMAGE   (Character) The name of the image being analysed.
   RA1     (Numeric) The inner radius in pixels of the sky aperture.
   RA2     (Numeric) The outer   "     "   "    "    "   "    "
   NRADII  (Numeric) The number of apertures to use.
   RADII   (Numeric array) The values of the radii, in pixels.
   BAD     (Numeric) Bad pixel rejection threshold.
   PHOTONS (Numeric) Number of photons per ADU.
   READNS  (Numeric) Readout noise.
   MZERO   (Numeric) Magnitude offset.
   SKYVAL  (Numeric) User-specified sky value.
   SIGMA   (Numeric) User-specified sigma.
  
   Command keywords -
  
   DISHIST  Used to ask whether sky histogram to be displayed.
   CONFIRM  Used to confirm acceptability of sky value and sigma.
  
   User variables used -  (">" input, "<" output)
  
   (>) SOFT  (Character) The soft plot device/type, as required by
             PGPLOT.
  
   Input -
  
   CENTER.DAT contains one record for each point, giving
              XCENT,YCENT,IX,IY,DX,DY,AP
              in the format 2F8.2,2I5,2F8.2,I4 where
              XCENT,YCENT give the position of the centroid
              IX,IY are the original pixel position of the point.
              DX,DY are the offsets in X and Y, and
              AP is the value used for APERTURE.
              If the centroid for a point cannot be determined, a
              record is written giving
              ’*** No centroid ’,IX,IY,DX,DY,AP
              in the format A,2I5,2F8.2,I4.
  
   Output -
  
   MAGS.DAT   lists the magnitudes as determined by the program.
  
                                         KS / CIT 1st June 1983

D.101 FSCRUNCH-Rebin data with a disjoint wavelength coverage to a linear one

Description:
FSCRUNCH rebins a spectrum or a set of spectra so that the result- ing data have either a linear wavelength scale or a wavelength scale that is logarithmic (i.e. has a constant velocity step). FSCRUNCH is intended for use where the input data have wavelength bins that are discontinuous, or overlapping, or both.
Parameters:
SPECTRUM
The spectrum (or spectra) to be scrunched. If SPECTRUM is an image (i.e. 2-D data) it will be treated as a set of spectra all of which will be scrunched individually. In this case, if the wavelength data is a 2-D array each of the data spectra will be scrunched according to the corresponding cross-section of the wavelength array. If the wavelength array is 1-D, this single array will be used for all the spectra.
WSTART
The wavelength of the center of the first bin of the resulting output data. Note that FSCRUNCH needs the output data to be in increasing wavelength order.
WEND
Normally, represents the wavelength of the center of the last bin of the resulting output data. Because this is not always the most convenient value to supply, FSCRUNCH will allow WEND to be used to specify the wavelength increment value (for linear data, this is the constant wavelength difference between bins; for logarithmic data it is the constant velocity step in Km/sec). The way WEND is interpreted may be controlled explicitly by the FINAL and INCREMENT hidden keywords, but by default FSCRUNCH will assume WEND is an incremental value if it is less than WSTART, and a final value if it is greater than WSTART.
BINS
The number of elements to be used for the resulting spectrum.
INORDER
The order of fit to be used during the scrunching in order to interpolate between input data points. A value of zero means that all the input bins will be treated as flat. Values of 1 or 2 will cause linear or quadratic interpolation to be used. Generally, the best results are obtained with quadratic inter- polation.
OUTPUT
The name of the resulting data file containing the scrunched spectrum or set of spectra. The structure of OUTPUT will be the same as that of the input file, except that the data array will generally be a different size.
INCREMENT
If set, FSCRUNCH will assume WEND is an incremental value (a velocity or wavelength step)
FINAL
If set, SCRUNCH will assume that WEND is the wavelength of the final element of the resulting spectrum.
LOG
Controls whether or not the data is binned to a linear or a logarithmic wavelength scale.
DENSITY
If the input data represents data whose units are flux per unit wavelength (AB magnitudes,Janskys, etc) rather than total flux over a wavelength range (photons, for example) then it should be scrunched so as to conserve the mean value of the data, and DENSITY should be set. See HELP FIGARO TECHNIQUES WAVELENGTH for more details on this point.
Source comments:
   F S C R U N C H
  
   Figaro routine to scrunch a spectrum or set of spectra in which
   the input wavelength ranges for the various pixels are not
   necessarily continuous, and may overlap.  It can scrunch
   either into a linear wavelength scale, where the wavelength
   increment from bin to bin is constant across the spectrum, or
   into a logarithmic scale, where the increment of the log of
   the wavelength from bin to bin is constant.
  
   If the input file is 2-D data, then it is treated as a set of
   1-D spectra and each is scrunched individually.   If the wavelength
   array (.X.DATA) is 1-D, then this single array will be used for all
   the spectra.  If it is 2-D, then each spectrum will be scrunched
   according to the corresponding cross-section of the wavelength
   array.
  
   The routine can either conserve flux or the mean value
   of the data.  Conserving flux is appropriate where the data is
   actually in flux units (photons/sec, for example), but not when
   the data is in units of flux per unit wavelength (AB magnitudes,
   Janskys, etc). Consider the case where each input bin maps to two
   output bins; if the data is in flux units - photon counts, for
   example - then flux should be conserved and the mean data level
   should drop by a factor 2; if the data is in magnitudes, then
   the rebinning should not change the mean level.  The program
   tries to determine for itself whether the data is in flux
   or in flux per unit wavelength by looking at the units, but
   uses a command keyword (DENSITY) to confirm its guess.
  
   Command parameters -
  
   SPECTRUM     (Character) The name of the spectrum to be scrunched.
   WSTART       (Numeric) The wavelength of the CENTER of the first
                bin of the resulting scrunched spectrum.
   WEND         (Numeric) The wavelength of the CENTER of the final
                bin of the resulting scrunched spectrum.  If WEND is
                less than WSTART, then FSCRUNCH assumes that it is the
                increment rather than the final value that is being
                specified.  If the scrunch is logarithmic and WSTART
                is greater than WEND, FSCRUNCH assumes that the WEND
                value represents a velocity in km/sec.  These
                assumptions can be controlled directly by the keywords
                INCREMENT and FINAL, if they will not give the desired
                effect.
   BINS         (Numeric) The number of bins for the resulting spectrum.
   INORDER      (Numeric) The order of local fit to be used for the
                input data.   Can be 0,1 or 2.
   OUTPUT       (Character) The name of the resulting spectrum.
                Note that FSCRUNCH cannot rebin a spectrum into itself
                and so will always create a new output file.
  
   Command keywords -
  
   LOG          Bin into logarithmic wavelength bins.
   DENSITY      Treat input data as being in units of flux per unit
                wavelength.
   INCREMENT    WEND is an increment value, even though it is > WSTART.
   FINAL        WEND is a final value, even though it is < WSTART.
  
   User variables -
  
   SCRUNCH_INC  Is set to the wavelength increment if linear
                rebinning is used, and to the velocity increment if
                log rebinning is used.
   SCRUNCH_END  Is set to the final wavelength value.  (This is for
                those cases where the WEND value represents an
                increment.)
  
   Input data -
  
   The input file is expected to contain a data array giving
   the wavelengths of the centres of the data elements, and an
   width specification which can be either a single number,
   a 1-D array, or a 2-D array, giving the wavelength range covered
   by each of the input data elements.  If an error array exists
   this will be used as well.
                                            KS / AAO 17th June 1986

D.102 FWCONV-General unit conversion for spectra

Description:
FWCONV converts the flux units of a spectrum from AB magnitudes, Janskys, milli-Janskys, micro-Janskys or erg/s/cm**2/Angstrom to any of these.
Parameters:
SPECTRUM
A spectrum whose units are either Janskys, milli-Janskys, micro-Janskys, erg/s/cm**2/Angstrom or AB magnitudes.
FLUX_UNIT
Units of either Janskys, milli-Janskys, micro-Janskys, erg/s/cm**2/Angstrom or AB magnitudes.
OUTPUT
The resulting spectrum, whose units will be either Janskys, milli-Janskys, micro-Janskys, erg/s/cm**2/Angstrom or AB magnitudes. OUTPUT can be the same as SPECTRUM, in which case the conversion will be performed in situ.
Source comments:
   F W C O N V
  
   Converts flux units of a spectrum from/to either
   F_lambda (ergs/sec/cm**2/A), AB magnitudes or F_nu (Janskys).
  
   Command parameters -
  
   SPECTRUM The name of the structure containing the spectrum.
            An x-axis data structure giving the wavelengths of the
            data elements is also required.
  
   OUTPUT   The name of the result of the operation.  This can
            be the same as for SPECTRUM. If not, a new structure
            is created, with everything but the data a direct
            copy of the input.
  
   Command keywords  - None
  
   User variables used - None
  
   4th  Feb 1991.  SMH/ AAO.  Original version, based on ABCONV code,

D.103 GAUSS-Interactive fit of Gaussians to emission or absorption lines

Description:
The GAUSS command will plot a spectrum on the current soft graphics device and allow interactive Gaussian fitting of upto ten Gaussians on a polynomial continuum.
Parameters:
TOL
The tolerance on the value of the optimised function required by the NAG routine E04JBF.
SPECTRUM
The name of the spectrum to be plotted and analysed. It should be a 1-dimensional array
FILE
Yes if results of the continuum and Gaussian fitting are to be written to a data file
FILNAM
The name for the data file to which results of the continuum and Gaussian fit are written
WHOLE
If set, the whole of the spectrum is plotted. Otherwise, the limits plotted are determined by the values of XSTART and XEND, which you will be prompted for if they were not specified in the command string.
AUTOSCALE
If set, the plot is scaled so that all of the data to be plotted just fits on the display. Otherwise, the scale of the plot is determined by the values of HIGH and LOW, which you will be prompted for if they were not specified in the command string.
XSTART
Specifies the first X value to be plotted, in the units used by the data - angstroms, for example, if the data is wavelength calibrated. XSTART can be set before the start of the data, if necessary. RESET will set XSTART to the first X value in the data.
XEND
Specifies the last X value to be plotted, in the units used by the data - angstroms, for example, if the data is wavelength calibrated. XEND can be set after the end of the data, if necessary. RESET will set XEND to the last X value in the data.
HIGH
The maximum data value to be plotted - i.e. the top Y axis value for the plot.
LOW
The minimum data value to be plotted - i.e. the bottom Y axis value for the plot.
BIAS
A bias value applied to the data, usually to bias up a plot which is to be superimposed upon a previous plot of almost identical data values. This makes the comparison easier. BIAS N is essentially equivalent to setting HIGH and LOW down by an amount N, so can result in unexpected axis values if it is not accompanied by AXES=NO.
LABEL
The label that will appear at the top of the plot and the results data file.
ORD
The order of the least squares polynomial fit to the continuum (maximum = 7).
SIG
The factor * the sigma on the last polynomial continuum fit such that a point with a deviation greater than SIG * sigma from the last fitted continuum will not be included in the next fit.
ERR
The factor * the error on a point such that a point with a deviation greater than ERR * error from the fitted continuum will not be included in the next fit.
ITN
The number of iterations for performing the polynomial fit to the continuum with rejection of points with large deviations from the fit (maximum = 10).
INDEX
The index number ( as listed ) of the Gaussian whose parameters are to be altered.
DELE
The index number ( as listed ) of the Gaussian which is to be deleted.
Pn_Hn_Wn_S

P followed by number -100 to 100 to alter position. ( 1 unit = line extent/100 ) H followed by number -100 to 100 to alter height. ( 1 unit = line height/100 ) W followed by number -100 to 100 to increase width. ( 1 unit = line extent/100 ) S to plot modified line and return to menu.

CONSTR
The fitted Gaussian parameters (peak position, peak height or line width) can be singly constrained or chained to vary together in groups.
SINCON
The fit parameters (peak position, peak height and width) of any of the Gaussian components can be constrained so as not to vary in the optimization process.
NPCON
The Gaussian number n can be constrained to the manually fitted value of peak position (P), height (H) or width (W). A value of -1 indicates the end of the single constraints.
MULTCON
Sets of Gaussians can have their fit parameters constrained so that the values are "chained" to vary together. The line seperations of Gaussians can be set; the ratio of their peak heights can be fixed and the ratio of their line widths can be fixed.
NCHAIN
NCHAIN is the number of Gaussians to chain together so that line seperation, height or width varies together. Must be less than or equal to the number of fitted Gaussians. A value of -1 indicates that there are no more chains to input.
CHAIN
Gaussian parameter to be chained: - P to keep Gaussian line seperations fixed; H to keep peak heights in specific ratio; W to keep Gaussian widths varying in ratio.
ICHAIN
ICHAIN is the index number of the Gaussian which is to be chained.
RCHAIN
RCHAIN is the value of the seperation between two chained Gaussians, the ratio of the heights of two chained Gaussians or the ratio of their line widths.
WGHT
Weighting of the residuals to be used in the optimization.

Options are: N for no weighting V for weighting by Y value E for weighting by 1/error**2

MAN
If set, the results of the manual fit will be written to the terminal and the results file (if open). If not set, then a return to the menu is made so the fit can be altered.
RECNAME
The name of the data file produced by GAUSS from which a fit is to be recalled and plotted for subsequent manipulation.
GAUFIT
The name of the continuum and Gaussian fit spectrum file to be written. It has the same dimension as the input spectrum.
CCMD
Continuum fitting menu entry. Alternatives are:

CUR - indicate continuum regions by cursor. ORD - order of polynomial fit. SIG - factor*sigma on fit for continuum point rejection. ERR - factor*error on point for rejection from continuum fit. ITN - number of iterations for continuum point rejection. FIT - perform the polynomial fitting. GAU - proceed to Gaussian fitting (continuum set).

GCMD
Gaussian fitting menu entry. Alternatives are:

LIM _ delimit edges of line (default is adjacent continuum edges). SIN - fit a single Gaussian to an indicated line. NEW - introduce a Gaussian at the cursor defined position. NEX - introduce a new Gaussian at the peak. INCH - interactively alter peak position, height or width. LIS - list the Gaussians fitted. SEL - select a line to be modified. DEL - delete a selected Gaussian. OPT - optimize the fit. RECAL - read a previous fit data file and plot this fit. HARD - plot results of fit for hardcopy device. SAVE - save the Gaussian fit spectrum as a file (name prompted for on quitting). CON - move to another section of continuum for more fitting. QUIT - quit from program (spectrum analysis complete).

Source comments:
   G A U S S
  
   Interactively fits Gaussians to an emission or absorption
   feature in a spectrum. A spectrum, whose length is prompted
   for, is plotted on the selected ’SOFT’ device together with a
   residual plot above. Regions of continuum are demarcated with
   the cursor. Continuum is fitted by a polynomial with rejection
   of points a selected sigma from this continuum or a fraction
   of the error bar ( if available ). Single or multiple Gaussian
   fits are made to the emission/absorption feature. In the case
   of multiple fits interactive fitting of the profile by Gaussians
   whose parameters are altered from the terminal occurs. The
   residuals on the fit ( observed - fitted ) are plotted in the
   residuals box above the main plot. If error bars are available
   for the spectrum they are plotted in the residuals box. The fit
   may be optimized and any single Gaussian parameter can be
   constrained or its value chained to another. The residuals on
   the fit for the purposes of the optimization can be weighted either
   by value or error. Data on the fit - central wavelength, height and
   sigma - are reported for each Gaussian and r.m.s. and mean
   fractional error ( if errors available ) on fit. The results may be
   recorded on a data file. The final fit spectrum can be saved as a
   file for subsequent analysis.
  
   Command parameters -
  
   SPECTRUM    The data to be fitted. This should be a
               1-d .dst file with a .z.data component.  If there
               is a .x.data component this will be used to
               give the x-axis.  If not, the x-axis will just
               have to be the numbers from 1 to n.
   XSTART      The x-value at which plotting is to start.
   XEND        The x-value at which plotting is to end.
               (XSTART and XEND are not required if the
               WHOLE keyword is set.)
   HIGH        The maximum value to be used for the plot.
   LOW         The minimum value to be used for the plot.
   BIAS        Value to be added to zero for the plot.
   LABEL       A label for the plot and the data file.
  
   Command keywords -
  
   AUTOSCALE   The program is to work out the values for HIGH
               and LOW, using the maximum and minimum values
               in the data over the specified range.
   WHOLE       The program is to display all of the spectrum.
  
   User variables -    (">" input, "<" output)
  
   (>) SOFT    Specifies the device and type to be used for soft
               plots.  See the SOFT command for more details.
   (>) HARD    Specifies the device and type to be used for hard
               plots.  See the HARD command for more details.
   (<) TVXST   is set to the starting x-value for the plot.
   (<) TVXEN   Is set to the final x-value for the plot.
   (<) TVHIGH  Is set to the same value as HIGH.
   (<) TVLOW   Is set to the same value as LOW.
   (<) TVFILE  Is set to the value of SPECTRUM.
  
   Subroutines called:
     MAPSPEC  -  unmaps the X and Z from virtual memory into arrays
                 in the program
     MAPSPECE  -  unmaps the X, Z and error data from virtual memory
                  into arrays in the program
     MAPSPECG  - maps the output fitting spectrum Z component into
                 virtual memory
     GAUS_XZPLOT  -  handles all the PGPLOT plotting of spectrum,
                     continuum fit, Gaussian fit, residuals and
                     error bars
     CONMENU  -  the continuum fitting menu for polynomial continuum
                 fitting
     GAUMENU  -  the Gaussian fitting menu for all Gaussian fitting
  
                                        JRW / AAO March 1987

D.104 GOODVAR-Replace negative, zero and bad variance values

Usage:
goodvar in out bad neg zero
Description:
This routine checks the variance component of a datafile for values that are bad, negative, or zero and replaces them by values specified by the user. The specified value can be the null value ("!") which is translated into the bad value.
Parameters:
IN
The input datafile.
OUT
The output datafile.
BAD
The value which replaces bad values. Enter an exclamation mark to keep bad values. Bad values in VARIANCE or ERRORS are not allowed by Figaro. If DSA has to convert these arrays while mapping them, floating overflows or square roots of negative numbers may occur, and the application is liable to crash. [!]
NEG
The value which replaces negative values. Enter an exclamation mark to replace negative values with the bad value. Negative errors or variances are nonsense. Negative variances often will cause an application to crash because it takes the square root to calculate the error. [!]
ZERO
The value which replaces zeroes. Enter an exclamation mark to replace zeroes with the bad value. Errors of zero sometimes are reasonable or necessary for error propagation. In other instances they cause problems, because statistical weights often are the reciprocal of the variance. [!]
Authors:
HME: Horst Meyerdierks (UoE, Starlink)

D.105 GROW-Copy an N-dimensional cube into part of an (N+M)-dimensional one.

Usage:

grow in expand stapix endpix size=? out=?

Description:

This routine increases the number of axes of a data set by duplicating pixels along some axes while retaining other axes. A simple and common example is turning a single row into a set of identical rows or a set of identical columns. This routine copies an N-dimensional cube into (part of) an (N+M)-dimensional one. The input cube is in general copied several times into the output, but need not fill the output cube. If the output file is new, its size has to be given. If it is an existing file, it cannot be reshaped, the axes of input and output have to be consistent.

Parameters:
INFO
INFO = _LOGICAL (Read) If false, the routine will issue only error messages and no informational messages. [YES]
NEW
NEW = _LOGICAL (Read) True if a new output file is to be created. [NO]
IN
IN = NDF (Read) Input NDF.
EXPAND
EXPAND( 7 ) = _INTEGER (Read) For each axis in OUT a 0 indicates that this is an axis with a correspondent in IN. A 1 indicates that it is an new (or expanded axis without correspondent in IN.
STAPIX
STAPIX( 7 ) = _INTEGER (Read) There is an EXPAND vector parameter that indicates which axes in OUT are new or have a corresponding axis in IN. Here, for each axis in OUT the value indicates where the multiple copy of input should start. Only the values for new axes in OUT are relevant, but a value for each axis in OUT must be supplied. The number of STAPIX elements given must match the number of axes in OUT.
ENDPIX
ENDPIX( 7 ) = _INTEGER (Read) There is an EXPAND vector parameter that indicates which axes in OUT are new or have a corresponding axis in IN. Here, for each axis in OUT the value indicates where the multiple copy of input should end. Only the values for new axes in OUT are relevant, but a value for each axis in OUT must be supplied. The number of ENDPIX elements given must match the number of axes in OUT.
SIZE
SIZE( 7 ) = _INTEGER (Read) For each axis in OUT a 0 indicates that the axis is to be taken from IN, an integer greater than 1 indicates that the axis is a new one and that the SIZE value is to be the length of that axis. The number of SIZE elements given must match the number of axes in OUT. The number of zeros given must be the number of axes in IN.
OUT
OUT = NDF (Read) Output NDF, containing the expanded data set.
Examples:
  grow spectrum [0,1] [0,1] [0,5] size=[0,5] out=image new=t info=f
     Grows a spectrum into an image of 5 identical rows. It forces
     the creation of a new output file even if IMAGE exists.
     Informational messages are suppressed.
  
  grow spectrum [1,0] [2,0] [4,0] out=image
     Grows a spectrum into an image of 3 identical columns. Column 1
     and columns beyond 4 in IMAGE remain unchanged. Since NEW is
     not specified, IMAGE must already exist. Its second axis must
     match the first axis of SPECTRUM, and its first axis must be
     at least 4 pixels long.
  
  grow spectrum [0,1,1] [0,1,1] [0,2,4] out=cube size=[0,4,8] new=t
     Grow the spectrum into a cube with the spectral axis the 1st
     cube axis.
  
  grow spectrum [1,0,1] [1,0,1] [2,0,4] out=cube size=[4,0,8] new=t
     Grow the spectrum into a cube with the spectral axis the 2nd
     cube axis.
  
  grow spectrum [1,0,1] [1,1,0] [2,4,0] out=cube size=[4,8,0] new=t
     Grow the spectrum into a cube with the spectral axis the 3rd
     cube axis.
  
  grow image [0,0,1] [0,0,1] [0,0,5] out=cube size=[0,0,5] new=t
     Grow an image into a cube, using the image as an xy-plane.
  
  grow image [0,1,0] [0,1,0] [0,5,0] out=cube size=[0,5,0] new=t
     Grow an image into a cube, using the image as an xt-plane.
  
  grow image [1,0,0] [1,0,0] [5,0,0] out=cube size=[5,0,0] new=t
     Grow an image into a cube, using the image as a yt-plane.
Notes:
This routine recognises the Specdre Extension v. 0.7. This routine does not propagate any other extensions even when a new output file is created.

This routine may work in situ on an existing output file.

When IN is given as a subset of lower actual dimensionality than its base NDF, the dimensionality will formally be the same as that of the base NDF with interspersed dimensions (axis lengths) of 1. If this is inconvenient, use the application SUBSET to create the subset in advance and without degenerate axes.

D.106 GROWX-Performs reverse function to that of EXTRACT

Description:
Replicates a spectrum to form an image. The source spectrum runs along the X-axis.
Parameters:
SPECTRUM
Spectrum to be ’grown’ into image.
IMAGE
Image to grow spectrum into.
YSTART
First cross-section to copy spectrum into.
YEND
Last cross-section to copy spectrum into.
NEW
Force creation of a new image?
YSIZE
Y-dimension of new image.
Source comments:
   G R O W
  
   This is the main routine for the Figaro commands GROWX
   and GROWY.  These both copy a spectrum into one or more
   cross-sections of an image, GROWX copying into cross-
   sections of constant AXIS(2), and GROWY copying into cross-
   sections of constant AXIS(1).  The operation performed by GROWX
   is the inverse of that performed by EXTRACT, and similarly
   for GROWY and YSTRACT.
  
   Command parameters:
  
   SPECTRUM    (Character) The name of the input spectrum file.
  
   IMAGE       (Character) The name of the image into which the
               spectrum is to be copied.  If the image file does
               not exist, or if NEW is set a new file is created
               with all other data elements set to zero.
  
   XSTART      (Numeric) The number of the first cross-section
     or        into which the spectrum is to be copied.  XSTART
   YSTART      is used by GROWY, YSTART by GROWX.
  
   XEND        (Numeric) The number of the last cross-section
     or        into which the sepctrum is to be copied.  XEND
   YEND        is used by GROWY, YEND by GROWX.
  
   XSIZE       (Numeric) If a new image has to be created, one
     or        of its dimensions will be that of the spectrum, but
   YSIZE       the other is unknown.  This has to be specified as
               XSIZE (for GROWY) or YSIZE for GROWX.
  
   Command Keywords:
  
   NEW         Used to force the creation of a new image, even if
               such an image exists already.
  
   User variables used:  None
  
   Error information:  Ignored.
  
   Data quality information: Handled using flagged data values.
  
                                           KS / CIT 19th Sept 1983

D.107 GROWXT-Copies an image into contiguous XT planes of a cube

Description:
GROWXT copies an image into successive planes of a cube (strictly a cuboid) for which the Y value is constant. This is the reverse of the XTPLANE function, except that all the planes grown into the cube are the same.
Parameters:
IMAGE
The name of the image to be used.
CUBE
The name of the data cube into which the image is to be grown. Successive ’Y’ planes (planes for which the second array index is constant) will be set the same as IMAGE. If CUBE does not exist, one will be created. If it does exist, its first and third dimensions must match the dimensions of IMAGE.
YSTART
The number of the first plane in the cube involved in this operation.
YEND
The number of the last plane in the cube involved in this operation.
NEW
If not set, and a cube of the specified name exists, then IMAGE will be grown into that existing cube. If NEW is set, a new cube will always be created.
YSIZE
If a new cube has to be created, its second dimension is unknown and has to specified as YSIZE. The other two dimensions will be those of the image.
Source comments:
   G R O W 3
  
   This is the main routine for the Figaro commands GROWXY, GROWXT
   and GROWYT.  These both copy an cube into one or more
   planes of a cuboid, GROWXY copying into planes of constant T,
   GROWYT into planes of constant X, and GROWXT into planes of
   constant Y.  The operations performed by GROWXY, GROWXT and
   GROWYT are the inverses of XYPLANE, XTPLANE and YTPLANE
   respectively.
  
   Command parameters -
  
   IMAGE       (Character) The name of the input image file.
               This will actually be image.dst.
  
   CUBE        (Character) The name of the cube into which the
               image is to be copied.  If the cube file does
               not exist, or if NEW is set, a new file is
               created with all other data elements set to zero.
  
   XSTART,     (Numeric) The number of the first plane
   YSTART or   into which the image is to be copied.  XSTART
   TSTART      is used by GROWYT, YSTART by GROWXT, TSTART by GROWXY.
  
   XEND,       (Numeric) The number of the last plane
   YEND, or    into which the image is to be copied.  XEND is
   TEND        used by GROWYT, YEND by GROWXT, TEND by GROWXY.
  
   XSIZE,      (Numeric) If a new cube has to be created, two
   YSIZE, or   of its dimensions will be those of the image, but
   TSIZE       the other is unknown.  This has to be specified as
               XSIZE, YSIZE or TSIZE for GROWYT, GROWXT, GROWXY
               respectively.
  
   Command Keywords
  
   NEW         Used to force the creation of a new cube, even if
               such an cube exists already.
  
   User variables used -  None
                                           KS / AAO 15th April 1985

D.108 GROWXY-Copies an image into contiguous XY planes of a cube

Description:
GROWXY copies an image into successive planes of a cube (strictly a cuboid) for which the T value is constant. This is the reverse of the XYPLANE fnction, except that all the planes grown into the cube are the same.
Parameters:
IMAGE
The name of the image to be used.
CUBE
The name of the data cube into which the image is to be grown. Successive ’T’ planes (planes for which the third array index is constant) will be set the same as IMAGE. If CUBE does not exist, one will be created. If it does exist, its first and second dimensions must match the dimensions of IMAGE.
TSTART
The number of the first plane in the cube involved in this operation.
TEND
The number of the last plane in the cube involved in this operation.
NEW
If not set, and a cube of the specified name exists, then IMAGE will be grown into that existing cube. If NEW is set, a new cube will always be created.
TSIZE
If a new cube has to be created, its third dimension is unknown and has to specified as TSIZE. The other two dimensions will be those of the image.
Source comments:
   G R O W 3
  
   This is the main routine for the Figaro commands GROWXY, GROWXT
   and GROWYT.  These both copy an cube into one or more
   planes of a cuboid, GROWXY copying into planes of constant T,
   GROWYT into planes of constant X, and GROWXT into planes of
   constant Y.  The operations performed by GROWXY, GROWXT and
   GROWYT are the inverses of XYPLANE, XTPLANE and YTPLANE
   respectively.
  
   Command parameters -
  
   IMAGE       (Character) The name of the input image file.
               This will actually be image.dst.
  
   CUBE        (Character) The name of the cube into which the
               image is to be copied.  If the cube file does
               not exist, or if NEW is set, a new file is
               created with all other data elements set to zero.
  
   XSTART,     (Numeric) The number of the first plane
   YSTART or   into which the image is to be copied.  XSTART
   TSTART      is used by GROWYT, YSTART by GROWXT, TSTART by GROWXY.
  
   XEND,       (Numeric) The number of the last plane
   YEND, or    into which the image is to be copied.  XEND is
   TEND        used by GROWYT, YEND by GROWXT, TEND by GROWXY.
  
   XSIZE,      (Numeric) If a new cube has to be created, two
   YSIZE, or   of its dimensions will be those of the image, but
   TSIZE       the other is unknown.  This has to be specified as
               XSIZE, YSIZE or TSIZE for GROWYT, GROWXT, GROWXY
               respectively.
  
   Command Keywords
  
   NEW         Used to force the creation of a new cube, even if
               such an cube exists already.
  
   User variables used -  None
                                           KS / AAO 15th April 1985

D.109 GROWY-Performs reverse function to that of YSTRACT

Description:
Replicates a spectrum to form an image. The source spectrum runs along the Y-axis.
Parameters:
SPECTRUM
Spectrum to be ’grown’ into image.
IMAGE
Image to grow spectrum into.
XSTART
First cross-section to copy spectrum into.
XEND
Last cross-section to copy spectrum into.
NEW
Force creation of a new image?
XSIZE
X-dimension of new image.
Source comments:
   G R O W
  
   This is the main routine for the Figaro commands GROWX
   and GROWY.  These both copy a spectrum into one or more
   cross-sections of an image, GROWX copying into cross-
   sections of constant AXIS(2), and GROWY copying into cross-
   sections of constant AXIS(1).  The operation performed by GROWX
   is the inverse of that performed by EXTRACT, and similarly
   for GROWY and YSTRACT.
  
   Command parameters:
  
   SPECTRUM    (Character) The name of the input spectrum file.
  
   IMAGE       (Character) The name of the image into which the
               spectrum is to be copied.  If the image file does
               not exist, or if the ’NEW’ keyword is specified,
               a new file is created with all other data elements
               set to zero.
  
   XSTART      (Numeric) The number of the first cross-section
     or        into which the spectrum is to be copied.  XSTART
   YSTART      is used by GROWY, YSTART by GROWX.
  
   XEND        (Numeric) The number of the last cross-section
     or        into which the sepctrum is to be copied.  XEND
   YEND        is used by GROWY, YEND by GROWX.
  
   XSIZE       (Numeric) If a new image has to be created, one
     or        of its dimensions will be that of the spectrum, but
   YSIZE       the other is unknown.  This has to be specified as
               XSIZE (for GROWY) or YSIZE for GROWX.
  
   Command Keywords:
  
   NEW         Used to force the creation of a new image, even if
               such an image exists already.
  
   User variables used:  None
  
   Error information:  Ignored.
  
   Data quality information: Handled using flagged data values.
  
                                           KS / CIT 19th Sept 1983

D.110 GROWYT-Copies an image into contiguous YT planes of a cube

Description:
GROWYT copies an image into successive planes of a cube (strictly a cuboid) for which the X value is constant. This is the reverse of the YTPLANE fnction, except that all the planes grown into the cube are the same.
Parameters:
IMAGE
The name of the image to be used.
CUBE
The name of the data cube into which the image is to be grown. Successive ’X’ planes (planes for which the first array index is constant) will be set the same as IMAGE. If CUBE does not exist, one will be created. If it does exist, its second and third dimensions must match the dimensions of IMAGE.
XSTART
The number of the first plane in the cube involved in this operation.
XEND
The number of the last plane in the cube involved in this operation.
NEW
If not set, and a cube of the specified name exists, then IMAGE will be grown into that existing cube. If NEW is set, a new cube will always be created.
XSIZE
If a new cube has to be created, its first dimension is unknown and has to specified as XSIZE. The other two dimensions will be those of the image.
Source comments:
   G R O W 3
  
   This is the main routine for the Figaro commands GROWXY, GROWXT
   and GROWYT.  These both copy an cube into one or more
   planes of a cuboid, GROWXY copying into planes of constant T,
   GROWYT into planes of constant X, and GROWXT into planes of
   constant Y.  The operations performed by GROWXY, GROWXT and
   GROWYT are the inverses of XYPLANE, XTPLANE and YTPLANE
   respectively.
  
   Command parameters -
  
   IMAGE       (Character) The name of the input image file.
               This will actually be image.dst.
  
   CUBE        (Character) The name of the cube into which the
               image is to be copied.  If the cube file does
               not exist, or if NEW is set, a new file is created
               with all other data elements set to zero.
  
   XSTART,     (Numeric) The number of the first plane
   YSTART or   into which the image is to be copied.  XSTART
   TSTART      is used by GROWYT, YSTART by GROWXT, TSTART by GROWXY.
  
   XEND,       (Numeric) The number of the last plane
   YEND, or    into which the image is to be copied.  XEND is
   TEND        used by GROWYT, YEND by GROWXT, TEND by GROWXY.
  
   XSIZE,      (Numeric) If a new cube has to be created, two
   YSIZE, or   of its dimensions will be those of the image, but
   TSIZE       the other is unknown.  This has to be specified as
               XSIZE, YSIZE or TSIZE for GROWYT, GROWXT, GROWXY
               respectively.
  
   Command Keywords
  
   NEW         Used to force the creation of a new cube, even if
               such an cube exists already.
  
   User variables used -  None
                                           KS / AAO 15th April 1985

D.111 GSPIKE-Generates a ’spiketrum’ from a table of values

Description:
Given a template spectrum - from which it gets the wavelength range required - and a table file giving wavelength and data values, GSPIKE generates a ’spiketrum’; a spectrum where all the elements except for those at the tablulated values are zero.
Parameters:
SPECTRUM
A template spectrum to determine the wavelength range over which to generate the ’spiketrum’ from tabulated values. Must have a proper array of X values.
TABLE
The name of the table file holding the pairs of values (wavelength and data) for the points to be used to generate the ’spiketrum’. If no extension is specified, .TAB will be used. The table may be in any of the standard Figaro directories, or in the current default directory. Or it may be specified in a form that includes the directory name.
SPIKETRUM
The name of the resulting ’spiked spectrum’ (hence ’spiketrum’) produced by GSPIKE. It will always be a new file.
Source comments:
   G S P I K E
  
   Generates a ’spiketrum’ from a table of X and Z values, given a
   spectrum to use as a template for the X range to be used.  The
   resulting spiketrum will be a spectrum with the same .X structure
   as the template spectrum, and a .Z structure that has zeros
   everywhere except at the points given in the table.  The table file
   can include SET commands that set individual item values in the
   resulting file, but the item names need to have been defined in the
   file SPIKETRUM.DEF.
  
   Command parameters -
  
   SPECTRUM    (Character) The name of the template spectrum.
   TABLE       (Character) The name of the file containing the
               table of X and Z values.  If TABLE contains no
               extension then ’.TAB’ will be assumed.
   SPIKETRUM   (Character) The name of the spiketrum to be creeated.
               Note that this will always be a new file.
  
   Command keywords -  None
  
   User variables used - None
  
                                         KS / CIT 7th May 1984

D.112 HARD-Sets the file name for hard copy output

Description:
The HARD command is used to set the current device and type for all hardcopy graphics output
Parameters:
HARDDEV
Used to specify the device to which all hardcopy graphics output is to be sent. Normally, a device name as recognised by SGS should be used - that is, the device specified should be one of those listed in response to the OPTIONS keyword - i.e. by the command HARD OPTIONS=YES. If necessary, a device type and connection ID can be used, by specifying e.g. HARDDEV="827,1" and by setting FORCE=YES.
OPTIONS
If set, a list of all the device names recognised by the SGS system is output.
FORCE
Normally, HARD will reject a device specification that is not known to SGS. However, if FORCE is set, it will use whatever is specified for HARDDEV unquestioningly. If it fails, that’s your problem.
DRAW
If set, HARD will output a test plot to the specified device. This acts as a test that the specification was correct.
Source comments:
   S O F T  /  H A R D  /  I D E V
  
   SOFT is used to set the user variable (SOFT) that controls
   the soft copy graphics output of Figaro programs.  HARD is
   used to set the user variable (HARD) that controls the
   hardcopy graphics output. IDEV is used to set the user variable
   (IDEV) that controls the image display.
  
   Command parameters -
  
   HARDDEV  (Character string) A device name recognised by
     or     the GKS version of PGPLOT.  Normally, what should
   SOFTDEV  be used is one of the device names recognised by
     or     GNS.  HARDDEV and SOFTDEV are used by HARD and SOFT
   IMAGDEV  respectively.
  
   Command keywords -
  
   OPTIONS  Causes a list of the various acceptable SGS device
            names to be output.
  
   FORCE    Forces the device specification to be accepted even
            if it does not match one of the acceptable SGS names.
  
   DRAW     Draws a test diagram on the screen.  (DRAW is the
            default for SOFT and IDEV, DRAW=NO is the default for
            HARD)
  
                                   KS / AAO 16th March 1988

D.113 HCROSS-Cross-correlate two spectra and get redshift and error

Description:
This computes the cross-correlation of two spectra and the location of the central peak of the cross-correlation. It can be used to determine a relative shift between two spectra. Routines added to calculate the confidence levels and improved error estimates (CCFPAR) according to analysis in Heavens A.F.,1993, MNRAS, 263, 735. The cross correlation function can also be saved in a disk structure.
Parameters:
SPECTRUM
Name of spectrum.
TEMPLATE
Name of template spectrum.
VELOCITIES
If yes, redshift is in km/S rather than Z.
BASERED
Redshift of template spectrum.
BASERR
Redshift error of template spectrum.
BASEVEL
Velocity (km/s) of template spectrum.
BASEVERR
Velocity error (km/s) of template spectrum.
XSTART
First X value to be used.
XEND
Last X value to be used.
FITCONT
Fit continuum?
CBPC
Percentage of spectrum covered by cosine bell.
RECORD
Create file to record cross-correlation?
CROSS
Name of cross-correlation data?
Source comments:
   H C R O S S
  
   Main body of the Figaro HCROSS function.  This computes
   the cross-correlation of two spectra and the location of the
   central peak of the cross-correlation.  It can be used to
   determine a relative shift between two spectra. Routines added to
   calculate the confidence levels and improved error estimates (CCFPAR)
   according to analysis in Heavens A.F.,1993, MNRAS, 263, 735.
   Routine added to calculate the redshift and error in redshift
   directly (GET_LOGSTEP and CALCRS).  The cross correlation
   function can also be saved in a disk structure.
  
   Command parameters -
  
   SPECTRUM    (Character) The spectrum to be compared with
               a template spectrum.
   TEMPLATE    (Character) The template spectrum to be used.
               The two spectra should be the same length.
   BASERED     (Numeric) Redshift of template spectrum.
               Negative=blueshift.  Required if VELOCITIES=NO
   BASERR      (Numeric) Redshift error of template.
               Required if VELOCITIES=NO
   BASEVEL     (Numeric) Recession velocity in km/s
               (see keyword VELOCITIES below) of template spectrum.
               Negative=blueshift. Required if VELOCITIES=YES
   BASEVERR    (Numeric) Velocity error of template (km/s).
               Required if VELOCITIES=YES
   XSTART      (Numeric) Data with an axis data value less than XSTART
               will be ignored in the cross-correlation.
   XEND        (Numeric) Data with an axis data value greater than XEND
               will also be ignored.  Note that these values are
               used to determine the channel numbers to be used
               for SPECTRUM, and the same ones will be used for
               TEMPLATE, even if TEMPLATE has a  different axis
               structure.
   CBPC        (Numeric) Percentage of spectrum covered by a cosine
               bell prior to application of the FFT.
   CROSS       (Character) the name of the data structure to hold
               the cross-correlation, if it is to be saved.
               The file created will be cross.dst, and will look
               like an ordinary spectrum - i.e. can be plotted by
               SPLOT, etc.  CROSS is ignored if RECORD is not
               set.
  
   Command keywords -
  
   FITCONT     If set, a continuum fit is performed on the two
               spectra prior to application of the cosine bell.
   RECORD      If set, the cross-correlation of the two spectra
               will be recorded as a new data structure.
   VELOCITIES  If yes, template redshift and error are entered in
               km/s (Negative=blueshift), and results are printed in km/s.
               Recommended option, and default, is NO
               i.e. a redshift z is expected and returned.
               Velocity option only makes sense if v<<c.
               v=cz and is accurate to O(z)
  
   User variables used -
  
   SHIFT       (Numeric) The relative shift of the two spectra.
   REDSHIFT    (Numeric) The redshift of the spectrum.
   REDERR      (Numeric) Redshift error of spectrum.
   VELOCITY    (Numeric) Recession velocity of spectrum (km/s):
                         Only meaningful if <<c.
   VELERR      (Numeric) Recession velocity error of spectrum (km/s)
   CONF        (Numeric) The confidence in the redshift of the spectrum
   WARN        (Numeric) =1 if routine detects badly-matched spectra.
                         =0 otherwise (not a guarantee of good spectra)
  
   5th  Oct. 1993. AFH, NEJ / UoE.
  

D.114 HIMAGE-Creates greyscale plot of image

Description:
Handles an ’HIMAGE’ command, producing an image on any suitable device. Originally based on the routine IMAGE.
Parameters:
IMAGE
IMAGE = FILE (Read) The name of the first image to be displayed.
YSTART
YSTART = REAL (Read) The first Y value to be displayed.
YEND
YEND = REAL (Read) The last Y value to be displayed.
XSTART
XSTART = REAL (Read) The first X value to be displayed.
XEND
XEND = REAL (Read) The last X value to be displayed. X and Y are the horizontal and vertical directions - as displayed on the Grinnell - respectively. The first value for each is 1.
LOW
LOW = REAL (Read) The minimum count level for the display, for the first image.
HIGH
HIGH = REAL (Read) The maximum count level for the display, for the first image.
PLOTDEV
PLOTDEV = CHARACTER (Read) The name of the plotting device
ASPECT
ASPECT = REAL (Read) The apect ratio of the plot
SHRINK
SHRINK = LOGICAL (Read) If to shrink image to leave margin all round
LOG
LOG = LOGICAL (Read) To take logarithms of the image to display it
Source comments:
    none available
  

D.115 HIST-Produce histogram of data value distribution in an image

Description:
HIST produces a histogram showing the distribution of data values in a Figaro data file. The histrogram is produced in the form of a one dimensional data structure, which can be plotted using SPLOT
Parameters:
IMAGE
The name of the file containing the data to be histogrammed. The data may have any dimensions.
MINVAL
The value of the center of the first bin of the histogram. Data less than MINVAL is not included in the histogram, so if delta is the bin width (Delta=(Maxval-Minval)/(Bins-1)), the first bin of the result gives the number of pixels between Minval and (Minval+delta/2), while the bin centered on value will give the number of pixels between value-delta/2 and value+delta/2.
MAXVAL
The value of the center of the last bin of the histogram. Data greater than MAXVAL is not included in the histogram.
BINS
The number of bins to be used in the histogram.
SPECTRUM
The histogram produced by HIST is in the form of a one dimensional data array, i.e. a sort of spectrum which may, for example, be plotted by SPLOT.
Source comments:
   H I S T
  
   Creates a one dimensional data structure containing a histogram
   of the data distribution in another structure.
  
   Command parameters -
  
   IMAGE    (Character) The name of the data structure (not necessarily
            two dimensional) to be histogrammed.
   MINVAL   (Numeric) The minimum value for the histogram.
   MAXVAL   (Numeric) The maximum value for the histogram.
   BINS     (Numeric) The number of bins to be used for the histogram.
   SPECTRUM (Character) The histogram produced from the input data.
  
   Command keywords -  None
  
                                   KS / CIT 29th June 1984

D.116 HOPT-Histogram optimization of an image

Description:
Performs a histogram equalisation on an image in an attempt to enhance the contrast. See, for example, Gonzalez and Wintz, ’Digital Image Processing’, Addison-Wesley).
Parameters:
IMAGE
Name of image to be equalised.
MINVAL
Minimum data value to be used.
MAXVAL
Maximum data value to be used.
EQUALISE
Generate equalised output data?
OUTPUT
Name of resulting image.
See also:
KAPPA: LAPLACE, LUTABLE, SHADOW, THRESH.
Source comments:
   H O P T
  
   Performs a histogram equalisation on an image in an attempt
   to enhance the contrast.  See, for example, Gonzalez and
   Wintz, ’Digital Image Processing’, Addison-Wesley).
  
   Command parameters -
  
   IMAGE  The name of the structure containing the image.
  
   MINVAL The minimum value to be used in generating the
          histogram.
  
   MAXVAL The maximum value to be used in generating the
          histogram.
  
   OUTPUT The name of the result of the operation.  This can
          be the same as for IMAGE.  If not, a new structure
          is created, with everything but the data a direct
          copy of the input.
  
   Command keywords -
  
   EQUALISE  Actually perform an equalisation.  If this is
             no (most likely if EQUALISE is not set) then
             all that happens is that the distribution
             histogram is generated and displayed.
  
   User variables -
  
   SOFT    (Character) The device/type to be used for terminal
           graphics.
  
                                    KS / CIT 27th Jan 1983

D.117 I2CMPLX-Copies an array into the imaginary part of a complex structure

Description:
I2CMPLX copies the data from a specified file (usually not a complex one) into the imaginary part of an existing complex data file, usually one created by R2CMPLX.
Parameters:
IDATA
The name of an existing file that contains a data array that is to become the imaginary part of an existing complex data structure.
CDATA
The name of the existing complex data structure whose imaginary part is to be set. CDATA may be the same as IDATA (which will have to be a complex structure), in which case one gets the odd effect of setting the imaginary part equal to the previous value of the modulus. Normally, CDATA is a separate file recently created by R2CMPLX.
Source comments:
   I 2 C M P L X
  
   Sets the imaginary part of an existing complex data structure.
   The complex data structure will probably have been created in the
   first instance by R2CMPLX, which leaves the imaginary part zero.
   I2CMPLX takes the data array from a specified file (usually not a
   complex one - note that if it is complex, it is the modulus that
   is used) and uses it to form the imaginary part of the complex
   data.
  
   Command parameters -
  
   IDATA       (Character) The data structure containing the array
               that is to form the imaginary part of the complex data.
               That is, the data array of IDATA becomes the
               imaginary data array of the output complex structure.
   CDATA       (Character) The resulting complex data structure.  Note
               that this is an already existing structure.
  
                                           KS / AAO 8th Sept 1986

D.118 IADD-Adds two images (or two spectra)

Description:
IADD adds together two images of identical dimensions. The number of dimensions does not have to be 2, so IADD can add both spectra and data cubes as well as images.
Parameters:
IMAGE
The first of the two images to be added.
IMAGE1
The second of the two images to be added.
OUTPUT
The name of the resulting image. This can be the same as IMAGE, in which case no new image will be created.
See also:
FIGARO: ISUB, IMULT, IDIV, ICADD, ICSUB, ICMULT, ICDIV.
KAPPA: CADD, CDIV, CMULT, CSUB, MATHS, ADD, SUB, MULT, DIV.
Source comments:
   I A D S U B
  
   Adds, multiplies, divides or subtracts two images.
  
   Command parameters -
  
   IMAGE  The name of the structure containing the first image.
  
   IMAGE1 The name of the structure containing the second
          image data.
  
   OUTPUT The name of the result of the operation.  This can
          be the same as for IMAGE.  If not, a new structure
          is created, with everything but the data (and any error
          or data quality information) a direct copy of the first
          image.
  
   The command itself (IADD,IMULT,IDIV or ISUB) is used to
   differentiate between the two operations.
  
                                    KS / CIT 26th Sept 1983

D.119 IALOG-Takes the antilog of an image

Description:
IALOG takes the base 10 antilog of each pixel in an image. Each pixel in the output image takes the value 10 to the power of the corresponding pixel in the input image.
Parameters:
IMAGE
The datafile to be processed.
OUTPUT
The name of the resulting image. If this is the same as IMAGE (the default) the operation will be performed in situ. Otherwise a new image will be created.
See also:
FIGARO: ILOG.
KAPPA: LOG10, LOGAR, LOGE.
Source comments:
   I A L O G
  
   Takes the base 10 antilog of an image.
  
   Command parameters -
  
   IMAGE  The name of the structure containing the image.
  
   OUTPUT The name of the result of the operation.  This can
          be the same as for IMAGE.  If not, a new structure
          is created, with everything but the data a direct
          copy of the input.
  
   Command keywords  - None
  
   User variables used - None
                                    KS / CIT 22nd April 1984

D.120 IARC-Given fit to single spectrum, fit all spectra in a 2-D arc

Description:
The manual arc line fitter, ARC, can be used to fit a single spectrum obtained by summing successive cross-sections taken from the center of a 2-D arc. IARC will then apply that fit to all the rows in the 2-D arc, starting from the center and working out in both directions.
Parameters:
IMAGE
EXTRACT can be used to sum cross-sections from the center of a 2-D arc - an image containing a set of arc spectra (a long-slit arc). ARC can then be used to fit them, producing a list of identified arc lines, channel number & wavelengths. IARC can then use this fit - in the file ARLINES.LIS - as a starting point for a fit to each of the cross-sections in the 2-D arc in the file whose name is given by IMAGE.
RSTART
Normally, IARC starts in the center - where the initial fit should be best - and works its way out. RSTART is the cross-section (or row) at which it starts, and should normally be the central cross-section of those summed to produce the arc spectrum used in the initial ARC fit.
RWIDTH
IARC can sum consecutive rows of a 2-D arc, instead of fitting each row individually. Increasing RWIDTH will speed up the fitting, since it reduced the number of spectra fitted, and may reduce the number of lines that get rejected, since the signal to noise ratio in the summed rows will be improved. However, it will degrade the smooth progression from one row to the next, and may make the lines broader.
FILE
The results of the 2-D fit are written to a file in a form suitable for use by the image scrunchers, ISCRUNCH and ISCRUNI. For ISCRUNCH the default name is usually satisfactory. For ISCRUNI you may want to exercise more control over the process and the files used.
RSIGMA
Normally, you should use the same sigma (the line width parameter) for IARC as was used for the original ARC fit, and this is always the default. However, IARC is a little more tolerant in searching for lines than is ARC, and there may sometimes be a case for using a slightly lower value of sigma, especially if the arc lines are very close together.
SPREAD
IARC normally searches for lines in a new cross-section in two steps, once with a larger sigma than that specified in order to make it less likely to loose lines that may be a little further away than expected, and then with the specified sigma in order to tighten up the centering. Setting SPREAD=NO will disable this feature and the search will be performed once, with the specified sigma.
GAP
If IARC fails to find a line, it will use the position it had previously for the line. If the line is missing a specified number of times, however, it is deleted from the line list. This maximum number of times is specified by GAP. The correct setting for GAP depends on the nature of the arc - an arc with high distortion should have a low GAP value to avoid lines becomming confused. If distortion is low but several cross-sections are missing or have poor data, GAP should be higher to let IARC ’jump’ over them.
SIGMIN
SIGMIN is a measure of the strength of an arc line. When the program searches for lines to use as ’lock’ lines, it evaluates their sigma - here the line height as a multiple of the square of the local continuum. Any line for which this value is less than SIGMIN will not be used.
XCORR
If XCORR is set, IARC will attempt to determine a linear shift between successive spectra using cross-correlation and will apply this to the arc lines found in the previous spectrum before looking for them in the new spectrum. This is particularly applicable to fibre data, where such linear shifts often occur. It is probably not useful for cases such as image tube distortion, where the spectra should change in a constant manner.
DETAIL
If DETAIL is set, IARC will list the details line position, wavelength, fitted wavelength, error) for each line fitted. This is a lot of information, and is not normally useful.
LOCK
If the original fit has regions where there are strongish lines that have not been identified, it may help to use their positions to lock down the fit in those regions. This does not improve the fit, since the wavelengths are simply assumed to be those given by the original fit, but the automatic fits will not be so free to wiggle in these regions. However, you have to be careful not to get a large number of weak lines that dominate the fit at the expense of stronger lines that were positively identified.
WEIGHT
Indicates whether the least-squares fit is to be weighted using the peak intensity of each line (so that more weight is given to strong lines).
Source comments:
   I A R C
  
   Performs a 2-D fit to an arc spectrum, given an initial fit
   to a single arc spectrum as a starting point.  Generally, the
   starting spectrum will have been extracted from the center of the
   2-D arc.  IARC then starts at a suitable cross-section in the
   2-D arc - usually the central one - and works out from there,
   fitting each cross-section individually, looking for the lines in
   the starting spectrum.  For each line, the program looks for a
   peak close to where it was found in the previous fit.  If a line
   does not show up in one cross-section, the previous position will
   be used, but if it fails to show up in the next cross-section, it
   will be dropped from the search list.  In many cases, there may be
   strong lines which were not indentified; these cannot be used to
   improve the fit, but they can be used to ’lock’ it down in the
   regions where there are few or no identified lines.
  
   Command parameters -
  
   IMAGE     (Character) The name of the image containing the 2-D arc.
   RSTART    (Numeric) The starting cross-section to be used.
   RWIDTH    (Numeric) The number of cross-sections to be added
             together for each fit - if the arc is weak, this will
             need to be increased.
   RSIGMA    (Numeric) Normally, the sigma value from the arc line
             file is used, but this can be overidden by RSIGMA.
   GAP       (Numeric) Number of cross sections over which IARC can
             fail to find a line before deleting it from the lists.
   FILE      (Character) The name of the file to which the results
             are to be written.  If an extension is not given, .IAR
             will be used.
   SIGMIN    (Numeric) The minimum acceptable value for the sigma of
             an arc line found in the locking process.  Sigma here is
             the height of the line relative to the square root of the
             continuum.  Only used if LOCK set.
  
   Command keywords -
  
   LOCK      Indicates that a search is to be made for lines to
             ’lock’ the fit.
   SPREAD    Indicates that IARC looks for lines first with an
             increased sigma, then with the specified sigma in order
             to refine the fit.  If SPREAD is not set, the search
             is just with the specified sigma value.
   DETAIL    Indicates that full details of the fits are to be output
             (This is mainly a diagnostic tool.)
   XCORR     If set, IARC will attempt to determine a linear shift
             between successive spectra using cross-correlation. This
             is particularly applicable to fibre data, where such linear
             shifts may occur. It is probably not useful for cases such
             as image tube distortion, where the spectra should change
             in a constant manner.
   WEIGHT    Indicates whether the least-squares fit is to be weighted
             using the peak intensity of each line (so that more weight
             is given to strong lines).
  
   User variables used -
  
   (<) IARC_WMAX   (Numeric) Maximum wavelength for any of the spectra.
   (<) IARC_WMIN   (Numeric) Minimum     "       "   "  "   "    "
   (<) NOFITS      (Numeric) The number of rows that could not be fitted.
   (<) ORDER       (Numeric) The order of the original fit.
   (<) RMSMAX      (Numeric) Maximum RMS error from the fits.
  
   Input files -
  
   ARLINES.LIS   Contains the details of the starting fit.  For format
                 details see comments for subroutine ARGETL, or the
                 ARC command.
  
   Output files -
  
   As named by   Contains the details of the 2-D fit.  Format :
   the FILE      Name of image, (24X,A).
   parameter.    Dimensions, NX, NY (17X,I5,4X,I5).
                 # rows not fitted properly, (42X,I5).
                 Maximum RMS error, (20X,F10.2).
                 Maximum order used, - ORDER - (33X,I3).
                 Then, for each row, row number and ORDER+1 polynomial
                 coefficients, the constant term being the last
                 non-zero term.  (I14,10X,2D24.16,3(/3D24.16)).
  
                                  KS / CIT  15th June 1984

D.121 ICADD-Adds a constant to an image

Description:
A constant value FACTOR is added to each pixel in the dataset IMAGE.
Parameters:
IMAGE
Name of image to be added to.
FACTOR
Additive constant.
OUTPUT
Name of resulting image.
See also:
FIGARO: ICSUB, ICMULT, ICDIV, IADD, ISUB, IMULT, IDIV.
KAPPA: CADD, CDIV, CMULT, CSUB, MATHS, ADD, SUB, MULT, DIV.
Source comments:
   I C O N S T
  
   This routine is the main body of ICMULT,ICDIV,ICADD and ICSUB,
   and of XCMULT, XCDIV, XCADD and XCSUB.  The Ixxxx routines
   operate on the data in an image, the Xxxx routines operate on
   the data in the X array of the input file.
   ICMULT multiplies an image by a constant.  Since the constant
   can be less than 1., this function will also divide an
   image by a constant, but ICDIV saves the caller from having
   to calculate a reciprocal. ICADD adds a constant to an image and
   ICSUB subtracts a constant from an image.
  
   Command parameters -
  
   IMAGE  (Character) The name of the structure containing the image.
          Uses main data array, or the x-axis data for the XCxxx routines.
  
   FACTOR (Numeric) The value of the constant factor.
  
   OUTPUT (Character) The name of the result of the operation.  This
          can be the same as for IMAGE.  If not, a new structure
          is created, with everything but the data a direct
          copy of the input.
  
   The command name is used to distinguish between the
   possible operations.
                                    KS / CIT 12th June 1984

D.122 ICDIV-Divides an image by a constant

Description:
Each pixel in the dataset IMAGE is divided by the constant value FACTOR.
Parameters:
IMAGE
Name of image to be divided.
FACTOR
Value of divisor.
OUTPUT
Name of resulting image.
See also:
FIGARO: ICSUB, ICMULT, ICADD, IADD, ISUB, IMULT, IDIV.
KAPPA: CADD, CDIV, CMULT, CSUB, MATHS, ADD, SUB, MULT, DIV.
Source comments:
   I C O N S T
  
   This routine is the main body of ICMULT,ICDIV,ICADD and ICSUB,
   and of XCMULT, XCDIV, XCADD and XCSUB.  The Ixxxx routines
   operate on the data in an image, the Xxxx routines operate on
   the data in the X array of the input file.
   ICMULT multiplies an image by a constant.  Since the constant
   can be less than 1., this function will also divide an
   image by a constant, but ICDIV saves the caller from having
   to calculate a reciprocal. ICADD adds a constant to an image and
   ICSUB subtracts a constant from an image.
  
   Command parameters -
  
   IMAGE  (Character) The name of the structure containing the image.
          Uses main data array, or the x-axis data for the XCxxx routines.
  
   FACTOR (Numeric) The value of the constant factor.
  
   OUTPUT (Character) The name of the result of the operation.  This
          can be the same as for IMAGE.  If not, a new structure
          is created, with everything but the data a direct
          copy of the input.
  
   The command name is used to distinguish between the
   possible operations.
                                    KS / CIT 12th June 1984

D.123 ICMULT-Multiplies an image by a constant

Description:
Each pixel in the dataset IMAGE is multiplied by the constant value FACTOR.
Parameters:
IMAGE
Name of image to be multiplied.
FACTOR
Multiplicative constant.
OUTPUT
Name of resulting image.
See also:
FIGARO: ICSUB, ICADD, ICDIV, IADD, ISUB, IMULT, IDIV.
KAPPA: CADD, CDIV, CMULT, CSUB, MATHS, ADD, SUB, MULT, DIV.
Source comments:
   I C O N S T
  
   This routine is the main body of ICMULT,ICDIV,ICADD and ICSUB,
   and of XCMULT, XCDIV, XCADD and XCSUB.  The Ixxxx routines
   operate on the data in an image, the Xxxx routines operate on
   the data in the X array of the input file.
   ICMULT multiplies an image by a constant.  Since the constant
   can be less than 1., this function will also divide an
   image by a constant, but ICDIV saves the caller from having
   to calculate a reciprocal. ICADD adds a constant to an image and
   ICSUB subtracts a constant from an image.
  
   Command parameters -
  
   IMAGE  (Character) The name of the structure containing the image.
          Uses main data array, or the x-axis data for the XCxxx routines.
  
   FACTOR (Numeric) The value of the constant factor.
  
   OUTPUT (Character) The name of the result of the operation.  This
          can be the same as for IMAGE.  If not, a new structure
          is created, with everything but the data a direct
          copy of the input.
  
   The command name is used to distinguish between the
   possible operations.
                                    KS / CIT 12th June 1984

D.124 ICONT-Produces a contour map of an image

Description:
Produces a contour map of an image.
Parameters:
IMAGE
Name of image to be contoured.
YSTART
First Y value to be displayed.
YEND
Last Y value to be displayed.
XSTART
First X value to be displayed.
XEND
Last X value to be displayed.
LOW
Lowest contour level.
HIGH
Highest contour level.
CONTOURS
Number of contour levels.
LABEL
Label for plot.
THICKNESS
Width of plotted lines.
LEVELS
Explicit contour levels to use.
ADJUST
Adjust scales so as to fill display?
BYVALUE
Specify contour level array explicitly?
HARDCOPY
Generate a hardcopy plot?
See also:
KAPPA: CONTOUR.
Source comments:
   I C O N T    /    I G R E Y
  
   Handles an ’ICONT’ command, producing a contour plot of an
   image on either the current hard or soft graphics device,
   or an ’IGREY’ command, which produces a grey-scale plot.
  
   Command parameters -
  
   IMAGE    (Character) The name of the image to be contoured.
   YSTART   (Numeric) The first Y value to be displayed.
   YEND     (Numeric) The last Y value to be displayed.
   XSTART   (Numeric) The first X value to be displayed.
   XEND     (Numeric) The last X value to be displayed.
            Note that this initial version only accepts these
            values as pixel numbers.
   LOW      (Numeric) The minimum contour level (ICONT) or
            the black level (IGREY).
   HIGH     (Numeric) The maximum contour level (ICONT) or
            the white level (IGREY).
   CONTOURS (Numeric) The number of contours displayed - these
            will be divided evenly between HIGH and LOW, unless
            explicitly specified as BYVALUE. (ICONT only).
   LABEL    (Character) A label for the plot.
   THICKNESS(Numeric) Thickness to use for lines (only used if
            the HARDCOPY parameter is specified, and ICONT only)
   LEVELS   (Numeric array) The contour levels to use (ICONT only,
            and only if the BYVALUE keyword is specified).
  
   Command keywords -
  
   HARDCOPY Output the plot to the current hard graphics device.
   ADJUST   Adjust scales so as to fill screen.
   BYVALUE  For ICONT, indicates that explicit contour values are
            specified in the LEVELS parameter.
  
   User variables used -   (">" input, "<" output)
  
   (>) SOFT     Current device/type (PGPLOT convention) for soft
                graphics output.
   (>) HARD     Current device/type (PGPLOT convention) for hardcopy
                graphics output.
   (<) TVXST    is set to the starting x-value for the plot.
   (<) TVXEN    Is set to the final x-value for the plot.
   (<) TVYST    is set to the starting y-value for the plot
   (<) TVYEN    is set to the final y-value for the plot.
   (<) TVHIGH   Is set to the same value as HIGH.
   (<) TVLOW    Is set to the same value as LOW.
   (<) PGENVARG Arguments used for PGENV.
   (<) IMFILE   File containing the displayed image.
  
                                             KS / CIT 21st March 1984.

D.125 ICONV3-Convolve an image with a 3x3 convolution kernel

Description:
ICONV3 convolves an image with a 3x3 symmetric convolution kernel, defined by its central value and its edge value. So the image is convolved with a 9 element array that has the 8 edge elements all set to one value and the central element to another. For example, CENTER=-9, EDGE=-1 is a highpass filter, CENTER=0.1, EDGE=0.1 would be a lowpass filter, while CENTER=8, EDGE=-1 would be a Laplacian edge enhancement filter.
Parameters:
IMAGE
The image to be filtered.
CENTER
Central value of 3x3 convolution array.
EDGE
Edge value of 3x3 convolution array.
OUTPUT
The name of the resulting filtered image. This may be the same as IMAGE, in which case the filtering will be performed in situ, or different, in which case a new file will be created.
See also:
FIGARO: ISMOOTH, IXSMOOTH, MEDFILT.
KAPPA: CONVOLVE, FFCLEAN, GAUSMOOTH, MEDIAN.
Source comments:
   I C O N V 3
  
   Convolves an image with a 3x3 symmetric convolution kernel.
   This allows a variety of spatial filters to be applied to
   an image.  The 3 by 3 array convolved with the image is defined
   by two values, the central value and the single value used
   for the eight edge elements.  That is, if C is the central and
   E the edge value, the kernel array looks like
  
                     E  E  E
                     E  C  E
                     E  E  E
  
   Command parameters -
  
   IMAGE    The name of the structure containing the image.
  
   CENTER   The value for the kernel central element.
  
   EDGE     The value for the kernel edge element.
  
   OUTPUT   The name of the result of the operation.  This can
            be the same as for IMAGE.  If not, a new structure
            is created, with everything but the data a direct
            copy of the input.
                                    KS / AAO 30th Oct 1987

D.126 ICOR16-Corrects 16 bit data from signed to unsigned range

Description:
ICOR16 takes an image that was written as 16 bit unsigned data, but has been read as 16 bit signed data (a particular problem with FITS data) and corrects it.
Parameters:
IMAGE
The name of an image (or possibly a spectrum) that has been read as signed 16 bit integers, but actually contained unsigned 16 bit integers. The data range in the image will be modified from -32767..32768 to 0..65535 (only the negative values will be changed.)
OUTPUT
The name of the resulting image. If this is the same as IMAGE (the default) the operation will be performed in situ. Otherwise a new image will be created.
Source comments:
   I C O R 1 6
  
   It is possible to have an image written on tape in what looks
   like unsigned 16 bit data, when what is intended is actually
   signed 16 bit data.  This is often true of FITS tapes, where
   16 bit data is always assumed to be unsigned.  ICOR16 corrects
   such an image.
  
   Command parameters -
  
   IMAGE  The name of the structure containing the image.
  
   OUTPUT The name of the result of the operation.  This can
          be the same as for IMAGE.  If not, a new structure
          is created, with everything but the data a direct
          copy of the input.
  
   Command keywords  - None
  
   User variables used - None
                                    KS / AAO 6th Dec 1984

D.127 ICSET-Set a selected region of an image to a constant value

Description:
ICSET sets a specified region in an image to a constant value. This is a modification of NCSET to operate on a 2-D image, and is a non-interactive version of CSET, which allows the region to be specified precisely in terms of the X-values of the data.
Parameters:
IMAGE
The name of the image to be modified by NCSET. It should be a 2-dimensional array.
YSTART
The first Y value to be set to the constant, in units used by the data - angstroms, for example, if the data is wavelength calibrated. RESET will set YSTART to the first Y value in the data.
YEND
The last Y value to be set to the constant, in units used by the data - angstroms, for example, if the data is wavelength calibrated. RESET will set YEND to the last Y value in the data.
XSTART
The first X value to be set to the constant, in units used by the data - angstroms, for example, if the data is wavelength calibrated. RESET will set XSTART to the first X value in the data.
XEND
The last X value to be set to the constant, in units used by the data - angstroms, for example, if the data is wavelength calibrated. RESET will set XEND to the last X value in the data.
CONSTANT
The selected region of the image (from XSTART to XEND) will be set to CONSTANT. No noise added on this level.
OUTPUT
NCSET generates an output file that is essentially the data from the input image, with one region set to the constant (user-specified) value. OUTPUT is the name of the resulting spectrum.
See also:
FIGARO: CSET, NCSET, TIPPEX.
KAPPA: CHPIX, FILLBAD, SEGMENT, NOMAGIC, RIFT, SETMAGIC, ZAPLIN.
Source comments:
   I C S E T
  
   Figaro function to set a selected region of an image to a constant
   value.  This is a modification of the standard FIGARO program
   NCSET to handle 2-D data arrays (which in turn is a non-interactive
   version of CSET, but has the possible advantage of allowing the
   region to be specified precisely in terms of the X values of the
   data).
  
   This program overcomes the limitations of CLEAN or BCLEAN (qv)
   which inherently assume the data to be modified is in the rows
   of the input array. This may not be the case for CCD images, and
   certainly not for 2-D spectra where modification of data over a
   specified wavelength region is most often required.
  
   USES:
  
   Anticipated uses are patching out of dud columns in a CCD image,
   or removal of data over a specified wavelength range (whose X
   limits are supplied by the user). The latter may be used to remove
   residuals after less-than-perfect sky subtraction.
  
   Command parameters -
  
   IMAGE       (Character) The image to be modified.
   YSTART      (Numeric) The Y-value of the start of the region.
   YEND        (Numeric) The Y-value of the end of the region.
   XSTART      (Numeric) The X-value of the start of the region.
   XEND        (Numeric) The X-value of the end of the region.
   VALUE       (Numeric) The value to use for the selected region.
   OUTPUT      (Character) The name of the output file to
               be created.  If this is the same as the input
               image, the data will be modified in situ.
  
   Command keywords - None
  
   User variables used -  None
  
                                            KS / CIT 27th March 1985

D.128 ICSUB-Subtracts a constant from an image

Description:
The constant FACTOR is subtracted from each pixel in IMAGE.
Parameters:
IMAGE
Name of image to be subtracted from.
FACTOR
Constant to be subtracted from image.
OUTPUT
Name of resulting image.
See also:
FIGARO: ICADD, ICMULT, ICDIV, IADD, ISUB, IMULT, IDIV.
KAPPA: CADD, CDIV, CMULT, CSUB, MATHS, ADD, SUB, MULT, DIV.
Source comments:
   I C O N S T
  
   This routine is the main body of ICMULT,ICDIV,ICADD and ICSUB,
   and of XCMULT, XCDIV, XCADD and XCSUB.  The Ixxxx routines
   operate on the data in an image, the Xxxx routines operate on
   the data in the X array of the input file.
   ICMULT multiplies an image by a constant.  Since the constant
   can be less than 1., this function will also divide an
   image by a constant, but ICDIV saves the caller from having
   to calculate a reciprocal. ICADD adds a constant to an image and
   ICSUB subtracts a constant from an image.
  
   Command parameters -
  
   IMAGE  (Character) The name of the structure containing the image.
          Uses main data array, or the x-axis data for the XCxxx routines.
  
   FACTOR (Numeric) The value of the constant factor.
  
   OUTPUT (Character) The name of the result of the operation.  This
          can be the same as for IMAGE.  If not, a new structure
          is created, with everything but the data a direct
          copy of the input.
  
   The command name is used to distinguish between the
   possible operations.
                                    KS / CIT 12th June 1984

D.129 ICUR-Inspect an image with cursor

Description:
This routine displays the position and data value according to the position of the cursor on the image display. Up to 50 pixel positions can be recorded for later use by other applications.

Use the cursor to select a position in the image previously displayed with the application IMAGE. Press one of the following:

D to display coordinates and pixel value, <space> to record pixel position, Q to quit the application.

Any other key is treated like ’D’, alphabetic keys are case-insensitive.

Parameters:
IDEV
The name of the imaging device, normally got from a global parameter which was set with the IDEV command.
IMARRAY
Information about the displayed part of the image and the part of the display used - set by IMAGE or similar.
IMFILE
File name of the image displayed - set by IMAGE or similar.
XPIXELS
The pixel numbers in X for the points indicated by the cursor.
YPIXELS
The pixel numbers in Y for the points indicated by the cursor.
NPIXELS
The number of points selected by the cursor. Note: if no points are selected, the values of NPIXELS, XPIXELS, YPIXELS are left unchanged.
See also:
FIGARO: IGCUR.
KAPPA: CURSOR, PICCUR;
GAIA.
Authors:
KS: Keith Shortridge (CIT, AAO)
Implementation status:
This routine does not provide a continuous display of coordinates and image value.

D.130 IDEV-Set the device for image display

Description:
The IDEV command is used to set the current device and type for all imaging output.
Parameters:
IMAGDEV
The device to which all imaging output is to be sent. Normally, a device name as recognised by SGS should be used - that is, the device specified should be one of those listed in response to the OPTIONS keyword - i.e. by the command SOFT OPTIONS. If necessary, a device type and connection id can be used, by specifying e.g. IMAGDEV="827,1" and by setting FORCE=YES.
OPTIONS
If set, a list of all the device names recognised by the SGS system is output.
FORCE
Normally, SOFT will reject a device specification that is not known to SGS. However, if FORCE is set, it will use whatever is specified for SOFTDEV unquestioningly. If it fails, that’s your problem.
DRAW
If set, SOFT will output a test plot to the specified device. This acts as a test that the specification was correct.
Source comments:
   S O F T  /  H A R D  /  I D E V
  
   SOFT is used to set the user variable (SOFT) that controls
   the soft copy graphics output of Figaro programs.  HARD is
   used to set the user variable (HARD) that controls the
   hardcopy graphics output. IDEV is used to set the user variable
   (IDEV) that controls the image display.
  
   Command parameters -
  
   HARDDEV  (Character string) A device name recognised by
     or     the GKS version of PGPLOT.  Normally, what should
   SOFTDEV  be used is one of the device names recognised by
     or     GNS.  HARDDEV and SOFTDEV are used by HARD and SOFT
   IMAGDEV  respectively.
  
   Command keywords -
  
   OPTIONS  Causes a list of the various acceptable SGS device
            names to be output.
  
   FORCE    Forces the device specification to be accepted even
            if it does not match one of the acceptable SGS names.
  
   DRAW     Draws a test diagram on the screen.  (DRAW is the
            default for SOFT and IDEV, NODRAW is the default for HARD)
  
                                   KS / AAO 16th March 1988

D.131 IDIFF-Takes the ’differential’ of an image

Description:
IDIFF takes an input image and creates a new image where each pixel is the average absolute difference between the corresponding pixel in the original image and its nearest neighbours. This emphasises those regions in the image where the data is changing rapidly.
Parameters:
IMAGE
IMAGE must contain two-dimensional data. IDIFF creates a resulting image where each pixel is the average absol- ute difference between the corresponding pixel in IMAGE and its nearest neighbours.
OUTPUT
The name of the resulting image. If this is the same as IMAGE (the default) the operation will be performed in situ. Otherwise a new image will be created.
Source comments:
   I D I F F
  
   Given an image, creates a new image in which each pixel
   is the average absolute difference between the corresponding
   pixel in the input image and its immediate neighbours.  This
   highlights regions in the image where the data is changing
   rapidly.
  
   Command parameters -
  
   IMAGE  The name of the structure containing the image.
  
   OUTPUT The name of the result of the operation.  This can
          be the same as for IMAGE.  If not, a new structure
          is created, with everything but the data a direct
          copy of the input.
  
   Command keywords  - None
  
   User variables used - None
                                    KS / CIT 22nd April 1984

D.132 IDIV-Divides two images (or two spectra)

Description:
Each pixel in IMAGE is divided by the corresponding pixel in IMAGE1. The result is stored in OUTPUT.
Parameters:
IMAGE
Name of first image.
IMAGE1
Name of second image.
OUTPUT
Name of resulting image.
See also:
FIGARO: IADD, ISUB, IMULT, ICADD, ICSUB, ICMULT, ICDIV.
KAPPA: CADD, CDIV, CMULT, CSUB, MATHS, ADD, SUB, MULT, DIV.
Source comments:
   I A D S U B
  
   Adds, multiplies, divides or subtracts two images.
  
   Command parameters -
  
   IMAGE  The name of the structure containing the first image.
  
   IMAGE1 The name of the structure containing the second
          image data.
  
   OUTPUT The name of the result of the operation.  This can
          be the same as for IMAGE.  If not, a new structure
          is created, with everything but the data (and any error
          or data quality information) a direct copy of the first
          image.
  
   The command itself (IADD,IMULT,IDIV or ISUB) is used to
   differentiate between the two operations.
  
                                    KS / CIT 26th Sept 1983

D.133 IGCONV-Convolve an image with a specified filter

Description:
This Figaro function convolves an image with a box array that is defined in a text file as a set of numbers. This is more flexible - though less efficient - than the simple convolution performed by ICONV3.
Parameters:
IMAGE
The name of a 1- or 2-dimensional data file that is to be convoled with the data array defined in the file specified by the CONVOL parameter.
CONVOL
A text file (default extension .cvf) which contains the definition of the data array that the IMAGE data is to be convolved with. The convolution data often referred to as a filter, since one of the main uses of this routine is to apply sharpening or smoothing filters to images) is specified as a series of numbers in free format (blank lines and lines starting with ’*’ being ignored). Normally one line of the filter is specified by one line of the file, but a line can be continued by ending it with a ’ćharacter.
OUTPUT
The name of the resulting data file. This will be a copy of the input file, except that the main data array will have been convolved with the specified array.
Source comments:
   I G C O N V
  
   This is a general-purpose convolution program, able to convolve the
   main data array in a Figaro file with a rectangular array of any
   dimensions. This is a more flexible routine than ICONV3, where the
   convolution is with a 3x3 array specified only by a center and an
   edge value, but the additional flexibility probably makes it
   noticeably slower, particularly for very large convolution arrays.
  
   Command parameters -
  
   IMAGE    The name of the structure containing the image.
  
   CONVOL   This is the name of a text file that contains the
            definition of the convolution array. See below for the
            format.
  
   OUTPUT   The name of the result of the operation.  This can
            be the same as for IMAGE.  If not, a new structure
            is created, with everything but the data a direct
            copy of the input.
  
   File format:
      The text file defining the convolution array should simply contain
      the values for the array in a free format, one line at a time. Lines
      beginning with a ’*’ are ignored, as are blank lines. If the data for
      a line of the array has to be continued onto another line, a ’\’
      should appear at the end of the line to be continued.
  
   11th Mar 1994.  Original version.  KS / AAO

D.134 IGCUR-Use cursor to show X, Y and data values

Description:
Interative task to determine pixel values in a dataset. This task can be used to mark points to be used by other tasks.
Parameters:
No user parameters.
See also:
FIGARO: ICUR.
KAPPA: CURSOR, PICCUR.
GAIA.
Source comments:
   I G C U R
  
   Services an ’IGCUR’ command.   Displays position and
   data value on the image display, depending on cursor position.
  
   Command parameters, keywords - None
  
   User variables used -   (">" input, "<" output)
  
   (>) IMFILE    (Character) The name of the data currently
                 displayed.  Set by IGREY or similar.
   (>) PGENVARG  (Numeric array) The argument list for PGENV that was
                 used in displaying the image.
   (<) XPIXELS   (Numeric) The pixel numbers in X for the
                 points indicated by the cursor.
   (<) YPIXELS   (Numeric) The pixel numbers in Y for the
                 points indicated by the cursor.
   (<) NPIXELS   (Numeric) The number of points selected by
                 the cursor.  Note: if no points are selected,
                 the values of NPIXELS, XPIXELS and YPIXELS
                 are left unchanged.
  
                                        KS / CIT 20th March 1984

D.135 IGREY-Produces a grey-scale plot of an image

Description:
Plots an image using a monochrome display look-up table.
Parameters:
IMAGE
Name of image to be grey-scaled.
YSTART
First Y value to be displayed.
YEND
Last Y value to be displayed.
XSTART
First X value to be displayed.
XEND
Last X value to be displayed.
LOW
Lowest data level used (black level).
HIGH
Highest data level used (white level).
LABEL
Label for plot.
ADJUST
Adjust scales so as to fill display?
HARDCOPY
Generate a hardcopy plot?
See also:
FIGARO: IMAGE.
KAPPA: DISPLAY;
KAPRH:GREYPLOT.
Source comments:
   I C O N T    /    I G R E Y
  
   Handles an ’ICONT’ command, producing a contour plot of an
   image on either the current hard or soft graphics device,
   or an ’IGREY’ command, which produces a grey-scale plot.
  
   Command parameters -
  
   IMAGE    (Character) The name of the image to be contoured.
   YSTART   (Numeric) The first Y value to be displayed.
   YEND     (Numeric) The last Y value to be displayed.
   XSTART   (Numeric) The first X value to be displayed.
   XEND     (Numeric) The last X value to be displayed.
            Note that this initial version only accepts these
            values as pixel numbers.
   LOW      (Numeric) The minimum contour level (ICONT) or
            the black level (IGREY).
   HIGH     (Numeric) The maximum contour level (ICONT) or
            the white level (IGREY).
   CONTOURS (Numeric) The number of contours displayed - these
            will be divided evenly between HIGH and LOW, unless
            explicitly specified as BYVALUE. (ICONT only).
   LABEL    (Character) A label for the plot.
   THICKNESS(Numeric) Thickness to use for lines (only used if
            the HARDCOPY parameter is specified, and ICONT only)
   LEVELS   (Numeric array) The contour levels to use (ICONT only,
            and only if the BYVALUE keyword is specified).
  
   Command keywords -
  
   HARDCOPY Output the plot to the current hard graphics device.
   ADJUST   Adjust scales so as to fill screen.
   BYVALUE  For ICONT, indicates that explicit contour values are
            specified in the LEVELS parameter.
  
   User variables used -   (">" input, "<" output)
  
   (>) SOFT     Current device/type (PGPLOT convention) for soft
                graphics output.
   (>) HARD     Current device/type (PGPLOT convention) for hardcopy
                graphics output.
   (<) TVXST    is set to the starting x-value for the plot.
   (<) TVXEN    Is set to the final x-value for the plot.
   (<) TVYST    is set to the starting y-value for the plot
   (<) TVYEN    is set to the final y-value for the plot.
   (<) TVHIGH   Is set to the same value as HIGH.
   (<) TVLOW    Is set to the same value as LOW.
   (<) PGENVARG Arguments used for PGENV.
   (<) IMFILE   File containing the displayed image.
  
                                             KS / CIT 21st March 1984.

D.136 ILIST-List the data in an image (or spectrum)

Description:
Displays the values of pixels in a dataset.
Parameters:
IMAGE
Name of image to be listed.
YSTART
First Y value for list.
YEND
Last Y value for list.
XSTART
First X value for list.
XEND
Last X value for list.
HARDCOPY
Produce a file containing list?
Source comments:
   I L I S T
  
   Lists the data in a subset of an image.
  
   Command parameters -
  
   IMAGE  (Char)    The name of the structure containing the image.
   YSTART (Numeric) The Y value for the start of the subset.
   YEND   (Numeric) The Y value for the end of the subset.
   XSTART (Numeric) The X value for the start of the subset.
   XEND   (Numeric) The X value for the end of the subset.
  
   Command keywords -
  
   HARDCOPY   List data in a file ready for printing.
  
                                    KS / CIT 16th July 1983

D.137 ILOG-Takes the logarithm of an image

Description:
ILOG takes the base 10 log of each pixel in an image. Negative pixels are set to zero in the output image.
Parameters:
IMAGE
The datafile to be processed.
OUTPUT
The name of the resulting image. If this is the same as IMAGE (the default) the operation will be performed in situ. Otherwise a new image will be created.
See also:
FIGARO: IALOG.
KAPPA: LOG10, LOGAR, LOGE.
Source comments:
   I L O G
  
   Takes the base 10 log of an image.  Any pixels that are
   negative will give a zero pixel in the resulting image.
  
   Command parameters -
  
   IMAGE  The name of the structure containing the image.
  
   OUTPUT The name of the result of the operation.  This can
          be the same as for IMAGE.  If not, a new structure
          is created, with everything but the data a direct
          copy of the input.
  
   Command keywords  - None
  
   User variables used - None
                                    KS / CIT 22nd April 1984

D.138 IMAGE-Display an image

Usage:
image image ystart yend xstart xend low high xplaces yplaces atx aty xorigin yorigin xpixels ypixels optimize=? [autoscale=? negative=? aspect=? log=? erase=? hardcopy=?]
Description:
This routine displays an image on the image display. Note that the colour tables are not changed by this command, nor is the device reset. The data can be logarithmised and/or histogram-optimised prior to display.
Parameters:
IMAGE
The image to be displayed.
YSTART
The first Y value to be displayed.
YEND
The last Y value to be displayed.
XSTART
The first X value to be displayed.
XEND
The last X value to be displayed.
LOW
The lowest data value to be displayed. [0.]
HIGH
The highest data value to be displayed. [1000.]
XPLACES
If not 0, the number of sub-displays in X. Enter 0 to specify a display region explicitly through X/YORIGIN and X/YPIXELS. [1]
YPLACES
If not 0, the number of sub-displays in Y. [1]
ATX
Which sub-display in X to use, counting from 1. [1]
ATY
Which sub-display in Y to use, counting from 1. [1]
XORIGIN
The first pixel in X to be used for display, counting from 0. [0]
YORIGIN
The first pixel in Y to be used for display, counting from 0. [0]
XPIXELS
How many pixels to use in X.
YPIXELS
How many pixels to use in Y.
OPTIMIZE
The degree of histogram optimisation to be applied. 0 for no optimsation, 1 for full optimisation. Optimisation is applied after taking common logarithms if LOG is YES. [0.5]
AUTOSCALE
Yes if the display thresholds are to be the minimum and maximum data values in the subset to be displayed. [T]
NEGATIVE
Yes if the auto-scaling should be reversed. [F]
ASPECT
Yes if data pixels are to be displayed as square pixels. [T]
LOG
Yes if the common logarithm of data is to be displayed rather than the data themselves. [F]
ERASE
Yes if the display is to be erased before display. [F]
HARDCOPY
Yes if the display is to be on the device set by the HARD command. The "idev" device is commonly a screen display, while the "hard" device is commonly a printer. Be wary of the NEGATIVE keyword in conjunction with HARDCOPY: A "positive" display will display the minimum as white and the maximum as black, and it in that sense negative. If you set the NEGATIVE keyword to YES, your hard copy will be "positive".
IDEV
The name of the imaging device, normally got from a global parameter which was set with the IDEV command.
HARD
The name of the "hard" device, normally got from a global parameter which was set with the HARD command.
IMARRAY
Information about the displayed part of the image and the part of the display used.
IMFILE
File name of the image displayed.
See also:
FIGARO: IGREY.
KAPPA: DISPLAY, GREYPLOT.
Authors:
KS: Keith Shortridge (AAO)

HME: Horst Meyerdierks (UoE, Starlink)

D.139 IMPOS-read positions from a file into environment variables

Description:
Input a list of positions from a file to the environment variables from which CENTERS obtains its input.

CENTERS requires a list of approximate X,Y input positions which it reads from environment variables. Usually this list is created interactively with ICUR or IGCUR. IMPOS creates the list by reading it from a text file, thus allowing CENTERS to be used non-interactively.

The input file is free-format, with one X,Y position per line. The X and Y values should be separated by one or more spaces and be expressed in pixels. Up to a hundred positions may be included.

Usage:
impos file-name
Parameters:
INPFLE
INPFLE = _CHAR (Read) Name of the input file containing the list of positions.
XPIXELS
XPIXELS = _REAL (Write) List of X coordinates (pixels).
YPIXELS
YPIXELS = _REAL (Write) List of Y coordinates (pixels).
NPIXELS
NPIXELS = _REAL (Write) Number of points in the list.
Source comments:
   Input a list of positions from a file to the environment variables
   from which CENTERS obtains its input.
  
   The contents of an example input file containing positions for
   three objects might be:
  
        103.4   67.8
        231.6  134.5
        246.7   89.2

D.140 IMULT-Multiplies two images (or two spectra)

Description:
Each pixel in IMAGE is multiplied by the corrsponding pixel of IMAGE1. The result is troed in OUTPUT.
Parameters:
IMAGE
Name of first image.
IMAGE1
Name of second image.
OUTPUT
Name of resulting image.
See also:
FIGARO: IADD, ISUB, IDIV, ICADD, ICSUB, ICMULT, ICDIV.
KAPPA: CADD, CDIV, CMULT, CSUB, MATHS, ADD, SUB, MULT, DIV.
Source comments:
   I A D S U B
  
   Adds, multiplies, divides or subtracts two images.
  
   Command parameters -
  
   IMAGE  The name of the structure containing the first image.
  
   IMAGE1 The name of the structure containing the second
          image data.
  
   OUTPUT The name of the result of the operation.  This can
          be the same as for IMAGE.  If not, a new structure
          is created, with everything but the data (and any error
          or data quality information) a direct copy of the first
          image.
  
   The command itself (IADD,IMULT,IDIV or ISUB) is used to
   differentiate between the two operations.
  
                                    KS / CIT 26th Sept 1983

D.141 INTERP-Interpolates points of a ’spiketrum’ to form a spectrum

Description:
INTERP interpolates between the points of a ’spiketrum’ - an array where most of the data is zero except for a few elements whose values are set - to produce a spectrum. Interpolation is by spline fitting, except for those cases where there are not enough points available; in these cases a global polynomial will be used.
Parameters:
SPIKETRUM
The name of the spiketrum - an array where only a few elements are set to the correct values, the other elements all being zero - which is to be used to produce a spectrum by interpolation between those specified elements. SPIKETRUM has probably been produced by GSPIKE from a table of values.
SPECTRUM
The name of the spectrum to be produced by interpolation between the points of the spiketrum.
LOG
It doesn’t usually make much difference whether you fit to the log of the data or to the data itself, but if the data is changing very rapidly, particularly at the ends, the fit may be better constrained if the log is used.
LINEND
A spline fit tends to go a little wild at the ends of the fitted spectrum - before the first and after the last point defined by the spiketrum. Using linear interpolation in these extreme ranges prevents this, at the expense of the smoothness of the resulting curve. Usually, it doesn’t make much difference.
Source comments:
   I N T E R P    /     S P I F I T    /   L I N T E R P
  
   Interpolates between the points of a ’spiketrum’ to
   generate a spectrum.   The INTERP command does this by
   spline interpolation, the SPIFIT command uses global polynomial
   fitting, and the LINTERP command uses linear interpolation.
  
   Command parameters -
  
   SPIKETRUM  The name of the structure containing the spiketrum
  
   ORDER      The order for the global polynomial to be fitted
              (SPIFIT only).
  
   SPECTRUM   The name of the result of the operation.  This can
              be the same as for SPIKE.  If not, a new structure
              is created, with everything but the data a direct
              copy of the input.
  
   Command keywords  -
  
   LOG        (INTERP & SPIFIT only) Perform the interpolation on
              the log of the data
  
   LINEND     (INTERP only) Use a linear interpolation for the
              ends of the data - spline fits can go wild outside the
              range of the defined points.
  
   User variables used - None
                                    KS / CIT 6th July 1984

D.142 IPLOTS-Plots successive cross-sections of an image, several to a page

Description:
The command IPLOTS extracts cross-sections from an image and plots them on the current hardcopy device, several to a page.
Parameters:
IMAGE
Must be either a one- or two-dimensional.
WHOLE
If WHOLE is set, the whole of each cross-section is plotted. Otherwise, the limits plotted are determined by the values of XSTART and XEND, which you will be prompted for if they were not specified in the command string. Note that WHOLE does not imply the plotting of EVERY cross-section.
XSTART
Start of spectrum to be plotted.
XEND
End of spectrum.
YSTART
First spectrum to be plotted.
YEND
Last spectrum to be plotted.
AUTOSCALE
If set, then each spectrum is scaled according to its own minimum and maximum values. Otherwise the collective minimum and maximum of all the spectra is used to scale them all equally.
NSPECT
Number of spectra per page.
LABEL
The label that will appear at the top of the plot.
HARDCOPY
If set, the plot is written to the device defined as the current hardcopy device. Generally, this is a disk file which will then have to printed. If HARDCOPY is not set, the plot will go to the current softcopy device. The hard- and soft- copy devices are specifed using the HARD and SOFT commands respectively.
COLOUR
The colour for the data to be plotted in. The axes are always plotted in white. The colours allowed are Blue, White, Red, Green, Black, Cyan, Magenta, Yellow. Using Black will have the effect of erasing anything where the data is plotted. This only works on the Grinnell.
NEXT
Used to pause between plots.
See also:
FIGARO: ESPLOT, MSPLOT, SPLOT.
KAPPA: LINPLOT, MLINPLOT;
GAIA.
Source comments:
   I P L O T S
  
   Produces a plot of successive cross-sections of an image ,
   several to a page. The plot is directed to the device
   defined by the user variable ’HARD’, and by the value of
   the command keyword ’HARDCOPY’.
  
   Command parameters -
  
   IMAGE       The data to be plotted.  If there is X-axis information
               then this will be used.  If not, the X-axis will just
               have to be the numbers from 1 to n.
   XSTART      The x-value at which plotting is to start. XSTART and
               XEND are only prompted for if WHOLE is not set.
   XEND        The x-value at which plotting is to end.
   YSTART      The first cross-section to be plotted.
   YEND        The last cross-section to be plotted.
   LABEL       A label for the plot.
   COLOUR      The colour for the plot (only meaningful for the
               Grinnell - later may be extended to map onto
               different line types).  The axes are always white.
   NSPECT      The number of cross-sections to be plotted per sheet.
  
   Command keywords -
  
   WHOLE       The program is to display all of each cross-section.
   AUTOSCALE   If NO (the default) , then each spectrum will be scaled to
               the extrema of all the sections under consideration. If YES
               then all spectra will be autoscaled individually.
   HARDCOPY    If set then output is sent to the device determined
               by HARD. If no device is specified by HARD, or HARDCOPY is
               not set, then IPLOTS will attempt to plot on the current
               SOFT device.
   NEXT        Used to pause between plots.
  
   User variables -    (">" input, "<" output)
  
   (>) SOFT    Specifies the device and type to be used for soft
               plots.  See the SOFT command for more details.
   (>) HARD    Specifies the device and type to be used for hard
               plots.  See the HARD command for more details.
  
  
                                       D.J.A  AAO  9th July 1987

D.143 IPOWER-Raises an image to a specified power

Description:
IPOWER raises each pixel in an image to a specified power. This can be used, for example, to take the square root of an image (by using a power of 0.5). Any pixel for which the operation is not legal - e.g. -ve pixels being raised to a non-integer power - are set to zero in the output image.
Parameters:
IMAGE
Name of the datafile to be processed.
POWER
The power to which the input image is to be raised. So setting POWER=0.5 will take the square root of the image, POWER=2.0 will square the image, POWER=-1 will give the inverse of the image, etc.
OUTPUT
The name of the resulting image. If this is the same as IMAGE (the default) the operation will be performed in situ. Otherwise a new image will be created.
See also:
KAPPA: POW.
Source comments:
   I P O W E R
  
   Raises the data in an image to a power of itself.  This can be used
   to multiply an image by itself (POWER=2.0) or to take the square
   root of an image (POWER=0.5), or may be used with an arbitrary power.
   Pixels whose value is such that the operation is illegal will give
   a zero result.
  
   Command parameters -
  
   IMAGE  (File) The name of the structure containing the image.
  
   POWER  (Numeric) The power to which the image is to be raised.
  
   OUTPUT (File) The name of the result of the operation.  This can
          be the same as for IMAGE.  If not, a new structure
          is created, with everything but the data a direct
          copy of the input.
  
   Command keywords  - None
  
   User variables used - None
                                    KS / AAO 28th May 1987

D.144 IRCONV-Converts data in Janskys to W/m**2/um

Description:
IRCONV generates a spectrum in W/m**2/um, given a spectrum in some other units. At present, only Janskys, milli-Janskys and micro-Janskys can be handled.
Parameters:
SPECTRUM
A spectrum whose units are (currently) either Janskys, milli-Janskys, or micro-Janskys. It needs to be wavelength calibrated, in Angstroms or microns.
OUTPUT
The resulting spectrum, whose units will be W/m**2/um. It can be the same as SPECTRUM, in which case the conversion will be performed in situ.
Source comments:
   A B C O N V  /  F L C O N V  /  I R C O N V
  
   Converts a spectrum into AB magnitudes (ABCONV) or f-lambda
   units (erg/s/cm**2/Angstrom) (FLCONV), or W/m**2/um (IRCONV).
   The original units of the data may be Jy (Janskys), mJy
   (milli-Janskys), or uJy (micro-Janskys). Other possibilities
   may be added later.
  
   Command parameters -
  
   SPECTRUM The name of the structure containing the spectrum.
            currently used for the spectrum.  For FLCONV
            an x-axis data structure giving the wavelengths of the
            data elements is also required.
  
   OUTPUT   The name of the result of the operation.  This can
            be the same as for SPECTRUM. If not, a new structure
            is created, with everything but the data a direct
            copy of the input.
  
   Command keywords  - None
  
   User variables used - None
                                    KS / CIT 18th May 1984

D.145 IREVX-Reverse an image (or spectrum) in the X-direction

Description:
The data are reversed in X. The result is an image where the left and right have changed places.
Parameters:
IMAGE
Name of image to be reversed.
OUTPUT
Name of resulting image.
See also:
FIGARO: IREVY, IROT90.
KAPPA: FLIP, REGRID, ROTATE.
Source comments:
   I R E V
  
   Figaro routine to reverse an image (or a spectrum, which
   is treated as an image with one dimension 1).  The reversal
   is in the X-direction or the Y-direction.
  
   Command parameters -
  
   IMAGE    (Character) The name of the file containing the image.
            The data and error components are reversed; the quality
            component is reversed implicitly by internally using
            flagged values; the x-axis or y-axis data
            component is reversed if it contains anything other than
            just the bin numbers.
  
   OUTPUT   (Character) The name of the result of the operation.
            This can be the same as IMAGE, in which case the
            operation is performed in situ.
  
   Command keywords - None
  
   User variables - None
  
                                       KS / CIT 20th July 1983

D.146 IREVY-Reverse an image in the Y-direction

Description:
The data are reversed in Y. The result is an image where the top and bottom have changed places.
Parameters:
IMAGE
Name of image to be reversed.
OUTPUT
Name of resulting image.
See also:
FIGARO: IREVX, IROT90.
KAPPA: FLIP, REGRID, ROTATE.
Source comments:
   I R E V
  
   Figaro routine to reverse an image (or a spectrum, which
   is treated as an image with one dimension 1).  The reversal
   is in the X-direction or the Y-direction.
  
   Command parameters -
  
   IMAGE    (Character) The name of the file containing the image.
            The data and error components are reversed; the quality
            component is reversed implicitly by internally using
            flagged values; the x-axis or y-axis data
            component is reversed if it contains anything other than
            just the bin numbers.
  
   OUTPUT   (Character) The name of the result of the operation.
            This can be the same as IMAGE, in which case the
            operation is performed in situ.
  
   Command keywords - None
  
   User variables - None
  
                                       KS / CIT 20th July 1983

D.147 IRFLAT-Generates a ripple spectrum from an IR spectrum

Description:
IRFLAT generates a ripple spectrum from an IR spectrum. In principle, the (raw or ratioed) data can then be divided by this ripple spectrum to take out the effects of different detector responses, which produces a periodic pattern on the continuum of the data (with period equal to the number of detectors).
Parameters:
SPECTRUM
Spectrum containing data.
CGS2
Flag indicating whether to operate in ’CGS 2’ mode.
PERIOD
Period of the ripple (pixels).
OUTPUT
The name of resulting ripple spectrum.
XSTART
First X value for region to be used.
XEND
Second X value for region to be used.
MORE
Include additional ranges? (If TRUE the prompts for XSTART and XEND are repeated for another region.)
Source comments:
   I R F L A T
  
   Figaro function that produces a "flatfield" ripple
   spectrum from a infrared  spectrum, by averaging the data from
   regions of the spectrum uncontaminated with spectral features
   (i.e. assumed flat) to determine the relative response of each
   detector or scan. The output spectrum can be divided into the original
   spectrum using IDIV to flat field the data.
  
   The program is used to remove two kinds of ripple from spectra.
   In instruments which interleave a number of scan positions to give
   a fully sampled spectrum (such as CGS3 and CGS4), the program removes
   ripple which results from seeing or transparency fluctuations between
   scan positions. In an instrument such as CGS2 it can remove the ripple
   which results from the fact that the flatfield (i.e. relative detector
   responses) is different for extended and point sources. In the case of
   CGS2 data it makes use of a .MORE.PIXELS extension in the data which
   specifies the detector and scan position corresponding to each pixel.
   If this structure is not present it prompts for a period and assumes
   a periodic ripple. The period will normally be the oversampling factor,
   typically 2 or 3 for CGS4 or CGS3 data.
  
   If the program is run in batch only one region can be specified.
   Multiple regions can only be specified in interactive mode.
  
   Command parameters -
  
   SPECTRUM    (Character) The name of the file containing the
               spectrum to be used.
   CGS2        (Logical) Flag indicating whether to operate in ’CGS 2’
               mode.
   PERIOD      (Real) The period of the ripple (in pixels).
   OUTPUT      (Character) The name of the resulting ripple spectrum.
   XSTART      (Real) First X value for region to be used.
   XEND        (Real) Second X value for region to be used.
  
   Command keywords -
  
   MORE        If YES, the prompts for XSTART and XEND are repeated for
               another region.
  
   10th Dec 1990 - JAB / JAC

D.148 IRFLUX-Flux calibrates an IR spectrum using a black-body model

Description:
Flux calibrates an IR spectrum using a black body model for a standard star.
Parameters:
SPECTRUM
Name of Star spectrum.
STANDARD
Name of Standard spectrum.
TEMP
Temperature of standard.
CALTYPE
Type of calibration data.
MAG
Magnitude of standard star.
FLUX
Flux of standard star at calib wavelength (mJy).
WAVE
Calibration wavelength (microns).
OUTPUT
Name of resulting spectrum.
Source comments:
   I R F L U X
  
   Flux calibrates an IR spectrum using a black body model for a
   standard star
  
   Command parameters -
  
   SPECTRUM  The name of the structure containing the first image.
  
   STANDARD  The name of the structure containing the second
             image data.
  
   TEMP      The temperature of the black body to be used.
  
   CALTYPE   The type of calibration data. A single character as follows:
                ’J’,’H’,’K’,’L’,’M’ - magnitude in a standard band
                ’F’ - Flux at specified wavelength
  
   MAG       The magnitude of the standard used.
  
   FLUX      The flux in mJy of the standard.
  
   WAVE      The wavelength at which the flux is specified.
  
   OUTPUT    The name of the result of the operation.  This can
             be the same as for SPECTRUM.  If not, a new structure
             is created, with everything but the data a direct
             copy of the input.
  
                                        JAB / JAC  19th Sep 1990

D.149 IROT90-Rotates an image through 90 degrees

Description:
The datafile is rotated throught 90 degrees in a clockwise direction, unless ANTI is specifified, in which case the rotatation is anti-clockwise.
Parameters:
IMAGE
The name of the structure containing the image.
OUTPUT
The name of the result of the operation. This can be the same as for IMAGE. In any case, a new structure is created, with everything but the data a direct copy of the input.
ANTI
If set, the rotation is anti-clockwise.
See also:
FIGARO: IREVX, IREVY.
KAPPA: FLIP, REGRID, ROTATE.
Source comments:
   I R O T 9 0
  
   Rotates an image through 90 degrees
  
   Command parameters -
  
   IMAGE  The name of the structure containing the image.
  
   OUTPUT The name of the result of the operation.  This can
          be the same as for IMAGE.  In any case, a new structure
          is created, with everything but the data a direct
          copy of the input.
  
   Command keywords -
  
   ANTI   If set, the rotation is anti-clockwise.
  
                                    KS / CIT 7th March 1983

D.150 ISCAN-Displays cuts through an IMAGE

Description:
Either the user can go into a loop in which (s)he is prompted for the start and end x-sects to extract, or the program will go through the data, displaying successive cuts.
Parameters:
IMAGE
IMAGE = FILE (Read) Image to take cuts from
XSTART
XSTART = REAL (Read) Starting wavelength (or pixel number if not calibrated)
XEND
XEND = REAL (Read) End wavelength etc.
YSTART
YSTART = INTEGER (Read) Starting cross-section
YEND
YEND = INTEGER (Read) End cross-section
YBLOCK
YBLOCK = INTEGER (Read) Width to extract from data in cross-sections (if scanning)
SCAN
SCAN = LOGICAL (Read) If to scan through data
HARDCOPY
HARDCOPY = LOGICAL (Read) If to plot in hard-copy
Source comments:
    none available
  

D.151 ISCRUNCH-Rebin an image to linear wavelength scale given IARC results

Description:
ISCRUNCH rebins an image that contains a set of spectra, so that the resulting data have either a linear wavelength scale or a wavelength scale that is logarithmic (i.e. has a constant velocity step). ISCRUNCH differs from SCRUNCH in that it uses a file that contains a set of polynomial fits to a 2-D arc in order to get the wavelength-channel relationship for each cross-section in the image, while SCRUNCH uses the values in the image’s X-axis array. Note that ISCRUNCH is not suitable for data in which the bins contain data that covers discontinuous or overlapping wavelength ranges (FIGS data, for example).
Parameters:
IMAGE
The name of the image to be scrunched. Each cross-section of the image is handled separately, and the channel-wavelength relationship for each cross- section is assumed to be given by a set of polynomial coefficients held in a file. These coefficients will have been determined by an analysis of a 2-D arc, and IMAGE must specify data of the same dimensions as the 2-D arc used.
FILE
ISCRUNCH is driven from the results of a 2-D arc fit - usually performed by IARC - and needs to know where to find the file that contains the polynomial coefficients determined by this fit. Usually, the default value will be the file generated the last time IARC was run. If no extension is specified, .IAR is assumed.
WSTART
The wavelength of the center of the first bin of the resulting output data.
WEND
Normally, represents the wavelength of the center of the last bin of the resulting output data. Because this is not always the most convenient value to supply, ISCRUNCH will allow WEND to be used to specify the wavelength increment value (for linear data, this is the constant wavelength difference between bins; for logarithmic data it is the constant velocity step in Km/sec). The way WEND is interpreted may be controlled explicitly by the FINAL and INCREMENT hidden keywords, but by default ISCRUNCH will assume WEND is an incremental value if it is less than WSTART, and a final value if it is greater than WSTART.
BINS
The number of elements to be used for the wavelength dimension of the resulting image.
OUTPUT
The name of the resulting data file containing the scrunched image. The structure of OUTPUT will be the same as that of the input file, except that the data array will generally be a different size, and any error array will have been deleted. (Eventually ISCRUNCH may be able to calculate the errors in the new image..)
INCREMENT
If set, ISCRUNCH will assume WEND is an incremental value (a velocity or wavelength step), even if it is greater than WSTART.
FINAL
If set, ISCRUNCH will assume that WEND is the wavelength of the final element of the resulting data, even if it is less than WSTART.
LOG
Controls whether or not the data is binned to a linear or a logarithmic wavelength scale.
LINEAR
Specifies that linear rather than quadratic interpolation is to be used during the scrunching. Usually, better results are obtained with quadratic interpolation. Note that LINEAR is the opposite of QUAD, and NOT of LOG.
QUAD
Specifies that quadratic rather than linear interpolation is to be used during the scrunching. Usually, better results are obtained with quadratic interpolation.
DENSITY
If the input data represents data whose units are flux per unit wavelength (AB magnitudes,Janskys, etc) rather than total flux over a wavelength range (photons, for example) then it should be scrunched so as to conserve the mean value of the data, and DENSITY should be set. See HELP FIGARO TECHNIQUES WAVELENGTH for more details on this point.
Source comments:
   I S C R U N C H      /      I S C R U N I
  
   Applies the set of polynomial fits determind by IARC to
   an image, re-binning each cross-section of the image to
   either a linear or logarithmic wavelength scale.  ISCRUNCH
   uses the results from a single 2-D arc fit as performed by
   IARC to get the channel/wavelength relation.  ISCRUNI uses
   two such fits, and performs a linear interpolation between
   the two.
  
   The routine can either conserve flux or the mean value
   of the data.  Conserving flux is appropriate where the data is
   actually in flux units (photons/sec, for example), but not when
   the data is in units of flux per unit wavelength (AB magnitudes,
   Janskys, etc). Consider the case where each input bin maps to two
   output bins; if the data is in flux units - photon counts, for
   example - then flux should be conserved and the mean data level
   should drop by a factor 2; if the data is in magnitudes, then
   the rebinning should not change the mean level.  The program
   tries to determine for itself whether the data is in flux
   or in flux per unit wavelength by looking at the units, but
   uses a command keyword (DENSITY) to confirm its guess.
  
   Command parameters -
  
   IMAGE      (Character) Image to be scrunched.
   FILE       (Character) File containing results of 2-D arc fit
              as produced by IARC.  If no extension supplied,
              .IAR is assumed.
   FILE2      (Character) ISCRUNI only. Second file containing
              IARC results.
   FRACTION   (Numeric) ISCRUNI only.  Controls the interpolation
              between the two sets of wavelength information.
              Value used=
                  (File value)+(File2 value - File value)*FRACTION
   WSTART     (Numeric) The wavelength of the CENTER of the first
              bin of the resulting scrunched spectrum.
   WEND       (Numeric) The wavelength of the CENTER of the final
              bin of the resulting scrunched spectrum.  If WEND is
              less than WSTART, then SCRUNCH assumes that it is the
              increment rather than the final value that is being
              specified.  If the scrunch is logarithmic and WSTART
              is greater than WEND, SCRUNCH assumes that the WEND
              value represents a velocity in km/sec.  These
              assumptions can be controlled directly by the keywords
              INCREMENT and FINAL, if they will not give the desired
              effect.
   BINS       (Numeric) The number of bins for the resulting spectrum.
   OUTPUT     (Character) Name of resulting image.  Note that an image
              cannot be scrunched into itself, so a new output file
              will always be created.
  
   Command keywords -
  
   LOG        Bin into logarithmic wavelength bins.
   DENSITY    Treat input data as being in units of flux per unit
              wavelength.
   LINEAR     Use linear interpolation when rebinning.
   QUAD       Use quadratic interpolation when rebinning.
   INCREMENT  WEND is an increment value, even though it is > WSTART.
   FINAL      WEND is a final value, even though it is < WSTART.
  
   User variables - None
  
                                       KS / CIT 22nd June 1984

D.152 ISCRUNI-Like ISCRUNCH, but interpolates between two IARC result sets

Description:
ISCRUNI rebins an image that contains a set of spectra, so that the resulting data have either a linear wavelength scale or a wavelength scale that is logarithmic (i.e. has a constant velocity step). ISCRUNI differs from SCRUNCH in that it uses files that contains a set of polynomial fits to a 2-D arc in order to get the wavelength-channel relationship for each cross-section in the image, while SCRUNCH uses the values in the image’s X-axis array. It differs from ISCRUNCH in using 2 such files, and taking values intermediate between the two when calculating its wavelengths. Note that ISCRUNI is not suitable for data in which the bins contain data that covers discontinuous or overlapping wavelength ranges (FIGS data, for example).
Parameters:
IMAGE
The name of the image to be scrunched. Each cross-section of the image is handled separately, and the channel-wavelength relationship for each cross- section is assumed to be given by a set of polynomial coefficients held in a file. These coefficients will have been determined by an analysis of a 2-D arc, and IMAGE must specify data of the same dimensions as the 2-D arc used.
FILE
ISCRUNI is driven from the results of a 2-D arc fit - usually performed by IARC - and needs to know where to find the file that contains the polynomial coefficients determined by this fit. Usually, the default value will be the file generated the last time IARC was run. If no extension is specified, .IAR is assumed.
FILE2
The name of the second of the sets of IARC results used by ISCRUNI in calculating the wavelength to channel relation for its input data.
FRACTION
When ISCRUNI calculates an input wavelength for a pixel, it calculates it first using the data from FILE, then repeats the calculation using the data from FILE2, and combines them to get an intermediate result using the supplied value of FRACTION. FRACTION=0.5 will give an average of the two, FRACTION=0.0 will effectively just use the values from FILE and FRACTION=1.0 will just use the values from FILE2.
WSTART
The wavelength of the center of the first bin of the resulting output data.
WEND
Normally, represents the wavelength of the center of the last bin of the resulting output data. Because this is not always the most convenient value to supply, ISCRUNI will allow WEND to be used to specify the wavelength increment value (for linear data, this is the constant wavelength difference between bins; for logarithmic data it is the constant velocity step in Km/sec). The way WEND is interpreted may be controlled explicitly by the FINAL and INCREMENT hidden keywords, but by default ISCRUNI will assume WEND is an incremental value if it is less than WSTART, and a final value if it is greater than WSTART.
BINS
The number of elements to be used for the wavelength dimension of the resulting image.
OUTPUT
The name of the resulting data file containing the scrunched image. The structure of OUTPUT will be the same as that of the input file, except that the data array will generally be a different size, and any error array will have been deleted. (Eventually ISCRUNI may be able to calculate the errors in the new image..)
INCREMENT
If set, ISCRUNI will assume WEND is an incremental value (a velocity or wavelength step), even if it is greater than WSTART.
FINAL
If set, ISCRUNI will assume that WEND is the wavelength of the final element of the resulting data, even if it is less than WSTART.
LOG
Controls whether or not the data is binned to a linear or a logarithmic wavelength scale.
LINEAR
Specifies that linear rather than quadratic interpolation is to be used during the scrunching. Usually, better results are obtained with quadratic interpolation. Note that LINEAR is the opposite of QUAD, and NOT of LOG.
QUAD
Specifies that quadratic rather than linear interpolation is to be used during the scrunching. Usually, better results are obtained with quadratic interpolation.
DENSITY
If the input data represents data whose units are flux per unit wavelength (AB magnitudes,Janskys, etc) rather than total flux over a wavelength range (photons, for example) then it should be scrunched so as to conserve the mean value of the data, and DENSITY should be set. See HELP FIGARO TECHNIQUES WAVELENGTH for more details on this point.
Source comments:
   I S C R U N C H      /      I S C R U N I
  
   Applies the set of polynomial fits determind by IARC to
   an image, re-binning each cross-section of the image to
   either a linear or logarithmic wavelength scale.  ISCRUNCH
   uses the results from a single 2-D arc fit as performed by
   IARC to get the channel/wavelength relation.  ISCRUNI uses
   two such fits, and performs a linear interpolation between
   the two.
  
   The routine can either conserve flux or the mean value
   of the data.  Conserving flux is appropriate where the data is
   actually in flux units (photons/sec, for example), but not when
   the data is in units of flux per unit wavelength (AB magnitudes,
   Janskys, etc). Consider the case where each input bin maps to two
   output bins; if the data is in flux units - photon counts, for
   example - then flux should be conserved and the mean data level
   should drop by a factor 2; if the data is in magnitudes, then
   the rebinning should not change the mean level.  The program
   tries to determine for itself whether the data is in flux
   or in flux per unit wavelength by looking at the units, but
   uses a command keyword (DENSITY) to confirm its guess.
  
   Command parameters -
  
   IMAGE      (Character) Image to be scrunched.
   FILE       (Character) File containing results of 2-D arc fit
              as produced by IARC.  If no extension supplied,
              .IAR is assumed.
   FILE2      (Character) ISCRUNI only. Second file containing
              IARC results.
   FRACTION   (Numeric) ISCRUNI only.  Controls the interpolation
              between the two sets of wavelength information.
              Value used=
                  (File value)+(File2 value - File value)*FRACTION
   WSTART     (Numeric) The wavelength of the CENTER of the first
              bin of the resulting scrunched spectrum.
   WEND       (Numeric) The wavelength of the CENTER of the final
              bin of the resulting scrunched spectrum.  If WEND is
              less than WSTART, then SCRUNCH assumes that it is the
              increment rather than the final value that is being
              specified.  If the scrunch is logarithmic and WSTART
              is greater than WEND, SCRUNCH assumes that the WEND
              value represents a velocity in km/sec.  These
              assumptions can be controlled directly by the keywords
              INCREMENT and FINAL, if they will not give the desired
              effect.
   BINS       (Numeric) The number of bins for the resulting spectrum.
   OUTPUT     (Character) Name of resulting image.  Note that an image
              cannot be scrunched into itself, so a new output file
              will always be created.
  
   Command keywords -
  
   LOG        Bin into logarithmic wavelength bins.
   DENSITY    Treat input data as being in units of flux per unit
              wavelength.
   LINEAR     Use linear interpolation when rebinning.
   QUAD       Use quadratic interpolation when rebinning.
   INCREMENT  WEND is an increment value, even though it is > WSTART.
   FINAL      WEND is a final value, even though it is < WSTART.
  
   User variables - None
  
                                       KS / CIT 22nd June 1984

D.153 ISEDIT-Allows interactive editing of a 1-D or 2-D spectrum

Description:
Interactively edit a 1-D or 2-D spectrum allowing points or complete spectra to be removed.
Parameters:
IMAGE
IMAGE should be the name of a 1-D or 2-D file.
WHOLE
If set, the whole of the spectrum is plotted. Otherwise, the limits plotted are determined by the values of XSTART and XEND, which you will be prompted for if they were not specified in the command string.
XSTART
Specifies the first X value to be plotted, in the units used by the data - angstroms, for example, if the data is wavelength calibrated. RESET will set XSTART to the first X value in the data.
XEND
Specifies the last X value to be plotted, in the units used by the data - angstroms, for example, if the data is wavelength calibrated. RESET will set XEND to the last X value in the data.
YVALUE
The number of the row to be worked on next.
OUTPUT
The name of the resulting edited data.
Source comments:
   I S E D I T
  
   Interactively edit a 1-D or 2-D spectrum allowing points or
   complete spectra to be removed
  
   Command parameters -
  
   ’IMAGE’    The name of the input file.
   ’XSTART’   Starting X value to plot
   ’XEND’     Ending X value to plot
   ’YVALUE’   Number of the row to be plotted.
   ’OUTPUT’   The name of the output file.
  
   Command keywords -
  
   ’WHOLE’    Plot all of spectrum
  
  
                                   JAB / JAC 11th Dec 1990

D.154 ISHIFT-Applies a linear X and a linear Y shift to an image

Description:
Applies a linear X and Y shift to an image.

The VARIANCE array, if present, is propagated in exactly the same way as the DATA array. This procedure it not formally correct if re-sampling occurs (that is, if either of the shifts is non-integer) and in this case the resulting variance will probably under-estimate the true error.

Parameters:
IMAGE
Name of image to be shifted.
XSHIFT
Shift in X.
YSHIFT
Shift in Y.
XSPLIT
Subdivision of X pixels.
YSPLIT
Subdivision of Y pixels.
OUTPUT
Name of resulting image.
Source comments:
   I S H I F T
  
   Shifts an image in both X and Y, by, in each direction,
   a constant amount expressed in pixels.
  
   The VARIANCE array, if present, is propagated in exactly the same
   way as the DATA array.  This procedure it not formally correct if
   re-sampling occurs (that is, if either of the shifts is non-integer)
   and in this case the resulting variance will probably under-estimate
   the true error.
  
   Command parameters -
  
   IMAGE  The name of the structure containing the image.
  
   XSHIFT (Numeric) The number of pixels the image is to be
          shifted in X.  A -ve number shifts towards lower
          numbered pixels.
  
   YSHIFT (Numeric) The number of pixels the image is to be
          shifted in Y.  Sense is as for XSHIFT.
  
   XSPLIT (Numeric) The number of sub-divisions to be made in
          each of the original pixels in X.
  
          Note that if both YSHIFT and XSHIFT are integers, the
          routine will just perform a fast data move, rather
          than hit the problem with the big hammer of a general
          rebinning.  YSPLIT and XSPLIT will be ignored.
  
   YSPLIT (Numeric) The number of sub-divisions to be made in
          each of the original pixels in Y.
  
          Note that if XSPLIT or YSPLIT are greater than 1,
          the data will be interpolated using a fit to a 2-D
          parabola.  This increases the accuracy (sometimes)
          of the rebinning, but results in increased CPU usage.
  
   OUTPUT The name of the result of the operation.  This can
          be the same as for IMAGE.  If not, a new structure
          is created, with everything but the data a direct
          copy of the input.
  
   Command keywords -  None
  
                                    KS / CIT 11th Sept 1983

D.155 ISMOOTH-2-D smooth of image using 9-point smoothing algorithm

Description:
ISMOOTH, which smooths a 2-D image using a nine-point 2-D smoothing algorithm. This is a 2-D extension of the 3-point spectrum smoothing algorithm which replaces each pixel with 1/2 its own value plus 1/4 of the value of each of its two neighbours. The routine used here replaces each pixel with a fraction of its own value plus a fraction of the value of its eight nearest neighbours. The fraction from a ’corner’ neighbour is 1.414 times less than from a ’side’ neighbour. Repeating the process increases the amount of smothing applied, and the operation is close in effect to a gaussian convolution.
Parameters:
IMAGE
Name of image to be smoothed.
FRACTION
Fraction of pixel data for redistribution.
REPEAT
Number of times to repeat basic smoothing.
OUTPUT
Name of resulting image.
See also:
FIGARO: ICONV3, IXSMOOTH, MEDFILT.
KAPPA: CONVOLVE, FFCLEAN, GAUSMOOTH, MEDIAN.
Source comments:
   I S M O O T H
  
   This routine is the main body of ISMOOTH, which smooths
   a 2-D image using a nine-point 2-D smoothing algorithm.  This
   is a 2-D extension of the 3-point spectrum smoothing algorithm
   which replaces each pixel with 1/2 its own value plus 1/4 of
   the value of each of its two neighbours.  The routine used here
   (see GEN_ASMOTH for details) replaces each pixel with a fraction
   of its own value plus a fraction of the value of its eight nearest
   neighbours.  The fraction from a ’corner’ neighbour is 1.414 times
   less than from a ’side’ neighbour.  Repeating the process increases
   the amount of smothing applied, and the operation is close in
   effect to a gaussian convolution.
  
   Command parameters -
  
   IMAGE    The name of the structure containing the image.
  
   FRACTION (Numeric) The fraction of each pixel’s value to be
            distributed to its neighbours.  The higher this
            value the greater the smoothing effect.
  
   REPEAT   (Numeric) The number of times the operation is to
            be repeated.  The higher this value, the greater
            the smoothing effect.
  
   OUTPUT   The name of the result of the operation.  This can
            be the same as for IMAGE.  If not, a new structure
            is created, with everything but the data a direct
            copy of the input.
  
                                    KS / CIT 21st June 1983

D.156 ISPLOT-Plots successive cross-sections through an image

Description:
The ISPLOT command will plot a series of cross-sections through an image as hidden line histograms on the current hard or soft graphics device.
Parameters:
IMAGE
The name of the image whose data is to be plotted by ISPLOT. Successive cross-sections (cuts of constant Y) are plotted as hidden line histograms. ISPLOT is probably most appropriate when IMAGE contains a set of long-slit spectra. If IMAGE is a 1-D array, SPLOT should be used.
HARDCOPY
If set, the plot is written to the device defined as the current hardcopy device. Generally, this is a disk file which will then have to printed. If HARDCOPY is not set, the plot will go to the current softcopy device. The hard and soft copy devices are specifed using the HARD and SOFT commands respectively.
YSTART
ISPLOT plots a series of cross-sections (cuts of constant Y value). YSTART and YEND are used to delimit these. YSTART should be the Y value of the lowest numbered cross-section to be plotted. Note that REVERSE should be used to cause cross-sections to be plotted in reverse order. Attempting to obtain the same effect by specifying YSTART < YEND will not work.
YEND
The Y value of the highest numbered cross-section plotted. See the help text for YSTART for more details.
WHOLE
If set, the whole of each cross-section is plotted. Otherwise, the limits plotted are determined by the values of XSTART and XEND, which you will be prompted for if they were not specified in the command string. Note that WHOLE does not imply the plotting of EVERY cross-section.
AUTOSCALE
If set, the plot is scaled so that all of the data to be plotted just fits on the display. Otherwise,the scale of the plot is determined by the values of HIGH, LOW, and OFFSET, which you will be prompted for if they were not specified in the command string.
XSTART
The first X value to be plotted, in the units used by the data - angstroms, for example, if the data is wavelength calibrated. XSTART can be set before the start of the data, if necessary. RESET will set XSTART to the first X value in the data.
XEND
The last X value to be plotted, in the units used by the data - angstroms, for example, if the data is wavelength calibrated. XEND can be set after the end of the data, if necessary. RESET will set XEND to the last X value in the data.
REVERSE
If set, the cross-sections will be plotted in the reverse of the order implied by the values of YSTART and YEND. Sometimes two plots, one reversed, the other not, are needed to give a proper picture of the data in IMAGE.
HIGH
The maximum data value to be plotted - i.e. the top Y axis value for the plot.
LOW
The minimum data value to be plotted - i.e. the bottom Y axis value for the plot.
OFFSET
A value added to each cross-section in order to bias it up above the previous cross-section. Offset is normally calculated by the program, but can be over-ridden - there may be some reason to set it to zero, for example.
SLANT
A number of elements of the data array by which successive cross-sections are to be offset in order to obtain a ’3-D’ effect for the plot. A positive value causes a slant to the right, a negative value a slant to the left.
LABEL
The label that will appear at the top of the plot.
ERASE
Specifies that the screen is to be erased before the plot is made. Usually ERASE and AXES will not be set when a plot is superimposed on a previous one.
AXES
Specifies that the axes for the plot are to be drawn. These should be omitted if the plot is being superimposed on a previous one, or sometimes just to save plotting time.
COLOUR
The colour for the data to be plotted in. The axes are always plotted in white. The colours allowed are Blue, White, Red, Green, Black, Cyan, Magenta, Yellow. Using Black will have the effect of erasing anything where the data is plotted. This only works on the Grinnell.
Source comments:
   I S P L O T
  
   Produces a hidden line histogram plot of an image.  This routine
   is really intended for the case where the image is a 2-D set of
   spectra.  The plot may be slanted to give a ’3-D’ effect if
   required, and may be in reverse order.  The plot is directed
   to the device defined by the user variables ’SOFT’ and
   ’HARD’, and by the value of the command keyword ’HARDCOPY’,
   so will appear immediately if these specify a video
   device (VT125, Grinnell, etc.).  If a hardcopy device is
   specified, the file for that device will be produced,
   but SPLOT does not attempt to spool it off for printing.
  
   Command parameters -
  
   IMAGE       The data to be plotted.  This should have a
             two dimensional data structure. If there
               is an x-axis component this will be used to
               give the x-axis.  If not, the x-axis will just
               have to be the numbers from 1 to n.
   YSTART      The y-value at which plotting is to start.
   YEND        The y-value at which plotting is to end.
   XSTART      The x-value at which plotting is to start.
   XEND        The x-value at which plotting is to end.
               (XSTART and XEND are not required if the
               WHOLE keyword is set.)
   HIGH        The maximum value to be used for the plot.
   LOW         The minimum value to be used for the plot.
               (HIGH and LOW are not required if the
               AUTOSCALE keyword is set.)
   OFFSET      A bias to be added to each successive cross-section
               to offset it from the previous one.  Normally, this
               will be allowed to default, unless it is explicitly
               specified in the command line.
   LABEL       A label for the plot.
   COLOUR      The colour for the plot (only meaningful for the
               Grinnell - later may be extended to map onto
               different line types).  The axes are always white.
  
   Command keywords -
  
   AUTOSCALE   The program is to work out the values for HIGH
               and LOW, using the maximum and minimum values
               in the data over the specified range.
   WHOLE       The program is to plot the whole of each cross-section
               of the image - note, not all the image, i.e. not every
               cross-section.
   HARDCOPY    The plot is to produce a hard copy.
   AXES        Axes will be plotted.
   ERASE       The screen will be erased before the plot.
   REVERSE     The cross-sections will be plotted in reverse order.
  
   User variables -    (">" input, "<" output)
  
   (>) SOFT    Specifies the device and type to be used for soft
               plots.  See the SOFT command for more details.
   (>) HARD    Specifies the device and type to be used for hard
               plots.  See the HARD command for more details.
   (<) TVDIM   is set to 1 if a single spectrum is plotted, to
               2 otherwise.
   (<) TVYST   is set to the starting y-value for the plot.
   (<) TVYEN   is set to the final y-value for the plot.
   (<) TVXST   is set to the starting x-value for the plot.
   (<) TVXEN   Is set to the final x-value for the plot.
   (<) TVHIGH  Is set to the same value as HIGH.
   (<) TVLOW   Is set to the same value as LOW.
   (<) TVFILE  Is set to the value of IMAGE.
   (<) TVCOLOR Is set to the GRPCKG code for the plot colour.
               (The TV.. variables are intended for use by
               cursor routines, and reflect the settings for the
               last plot made, even if XSTART etc are changed.)
  
   (Other user variables may be set by the command processor, in
   connection with the parameter values.)
  
                                       KS / CIT  5th March 1984

D.157 ISTAT-Provides some statistics about an image (max, min etc.)

Description:
ISTAT examines an image, or a rectangular subset of an image or spectrum, and outputs a number of statistics about it, such as maximum and minimum value, mean and sigma, etc. The results are used to set Figaro user variables, so can be used by Figaro procedures. There are a number of examples in the documentation
Parameters:
IMAGE
The name of the image (or spectrum) for which statistics are to be determined.
YSTART
First Y value to be used.
YEND
Last Y value to be used.
XSTART
First X value to be used.
XEND
Last X value to be used.
PASS2
setting PASS2 makes ISTAT take two passes through the data in order to calculate Sigma more accurately. This accuracy is, of course, gained at the expense of time taken. For cases where fewer than 10,000 pixels are involved, ISTAT always uses two passes, since the other overheads dominate the time taken. If in doubt, try both, and see if the slower algorithm gives significantly different answers to the faster one. If so, use PASS2.
MEDIAN
Setting MEDIAN makes ISTAT calculate the median value in the specified range. This can be a time-consuming operation, so is not performed by default.
See also:
KAPPA: HISTAT, HISTOGRAM, MSTATS, NUMB, STATS;
GAIA.
Source comments:
   I S T A T
  
   Examines an image (or a subset of an image) an determines
   a number of useful statistics about the data in it, such as
   the mean, max and minimum values.  For a full list, see below
   under ’user variables’.
  
   Command parameters -
  
   IMAGE  (Char) The name of the structure containing the image.
   YSTART (Numeric) The Y value for the start of the subset.
   YEND   (Numeric) The Y value for the end of the subset.
   XSTART (Numeric) The X value for the start of the subset.
   XEND   (Numeric) The X value for the end of the subset.
  
   Command keywords
  
   PASS2   If set, the sigma value is calculated using two
           passes throught the data.  The one-pass algorithm normally
           used is prone to rounding error when large numbers of
           pixels are involved, but is rather faster.  If fewer than
           10,000 pixels are involved, ISTAT always uses two passes,
           since the other overheads dominate the time taken.
   MEDIAN  If set, the median value of the image data is
           calculated (a possibly time-consuming business).
  
   User variables -   ("<" output)
  
   (<) STAT_TOTAL   The sum of the data.
   (<) STAT_MIN     The minimum data value.
   (<) STAT_MAX     The maximum data value.
   (<) STAT_MEAN    The mean data value.
   (<) STAT_MEDIAN  The median data value (only set if MEDIAN set)
   (<) STAT_XMAX    The x-value of the pixel where the max was found.
   (<) STAT_YMAX    The y-  "   "   "    "     "     "   "   "    "
   (<) STAT_XMIN    The x-  "   "   "    "     "     " min   "    "
   (<) STAT_YMIN    The y-  "   "   "    "     "     "   "   "    "
   (<) STAT_SIGMA   The standard distribution of the data
   (<) STAT_SIZE    The number of pixels examined
   (<) STAT_XSTART  The first pixel number examined in X
   (<) STAT_XEND    The last    "     "        "     " X
   (<) STAT_YSTART  The first pixel number examined in Y
   (<) STAT_YEND    The last    "     "        "     " Y
  
                                    KS / CIT 7th June 1984

D.158 ISTRETCH-Stretches and shifts an image in X and Y.

Description:
Shifts an image in both X and Y, by, in each direction, a constant amount expressed in pixels and stretches it by a given factor - this is a linear stretch, combined with a shift. Note that this is functionally a superset of ISHIFT, but ISHIFT should be used for cases where the stretch is 1.0 in both X and Y, since it uses a simpler algorithm for very simple cases.
Parameters:
IMAGE
Name of image to be stretched.
XSTRETCH
Stretch factor in X.
YSTRETCH
Stretch factor in Y.
XSHIFT
Shift in X.
YSHIFT
Shift in Y.
XSPLIT
Subdivision of X pixels.
YSPLIT
Subdivision of Y pixels.
OUTPUT
Name of resulting image.
See also:
KAPPA: BLOCK, COMPAVE, COMPICK, PIXDUPE, REGRID, SQORST.
Source comments:
   I S T R E T C H
  
   Shifts an image in both X and Y, by, in each direction,
   a constant amount expressed in pixels and stretches it
   by a given factor - this is a linear stretch, combined
   with a shift.  Note that this is functionally a superset
   of ISHIFT, but ISHIFT should be used for cases where the
   stretch is 1.0 in both X and Y, since it uses a simpler
   algorithm for very simple cases.
  
   Command parameters -
  
   IMAGE    The name of the structure containing the image.
  
   XSTRETCH (Numeric) The stretch factor to be applied in X.
  
   YSTRECTH (Numeric) The stretch factor to be applied in Y.
  
   XSHIFT   (Numeric) The number of pixels the image is to be
            shifted in X.  A -ve number shifts towards lower
            numbered pixels.
  
   YSHIFT   (Numeric) The number of pixels the image is to be
            shifted in Y.  Sense is as for XSHIFT.
  
   XSPLIT   (Numeric) The number of sub-divisions to be made in
            each of the original pixels in X.
  
   YSPLIT   (Numeric) The number of sub-divisions to be made in
            each of the original pixels in Y.
  
            Note that if XSPLIT or YSPLIT are greater than 1,
            the data will be interpolated using a fit to a 2-D
            parabola.  This increases the accuracy (sometimes)
            of the rebinning, but results in increased CPU usage.
  
   OUTPUT   The name of the result of the operation.  This can
            be the same as for IMAGE.  If not, a new structure
            is created, with everything but the data a direct
            copy of the input.  Note that the size of the image
            is the same as before - so either some pixels will
            be stretched out of the image, or some pixels will
            just be zero.
  
   Command keywords -  None
  
                                    KS / CIT 5th Dec 1983

D.159 ISUB-Subtracts two images (or two spectra)

Description:
Subtracts from the value of each pixel in an image the value of the corresponding pixel in a second image.
Parameters:
IMAGE
Name of first image.
IMAGE1
Name of second image.
OUTPUT
Name of resulting image.
See also:
FIGARO: IADD, IMULT, IDIV, ICADD, ICSUB, ICMULT, ICDIV.
KAPPA: CADD, CDIV, CMULT, CSUB, MATHS, ADD, SUB, MULT, DIV.
Source comments:
   I A D S U B
  
   Adds, multiplies, divides or subtracts two images.
  
   Command parameters -
  
   IMAGE  The name of the structure containing the first image.
  
   IMAGE1 The name of the structure containing the second
          image data.
  
   OUTPUT The name of the result of the operation.  This can
          be the same as for IMAGE.  If not, a new structure
          is created, with everything but the data (and any error
          or data quality information) a direct copy of the first
          image.
  
   The command itself (IADD,IMULT,IDIV or ISUB) is used to
   differentiate between the two operations.
  
                                    KS / CIT 26th Sept 1983

D.160 ISUBSET-Produces a subset of an image

Description:
ISUBSET takes a subset of an image. The result is a new image which is a rectangular subset of the original data.
Parameters:
IMAGE
The name of the image from which a subset is to be taken. IMAGE may be 1 or 2 dimensional.
YSTART
The value of the Y-coordinate for the first pixel in the input image to be included in the subset. Note that the subsetting is done on a whole pixel basis, so the resulting subset may not begin exactly on YSTART, but will start with the first pixel that covers that Y value.
YEND
The value of the Y-coordinate for the last pixel in the input image to be included in the subset. Note that the subsetting is done on a whole pixel basis, so the resulting subset may not end exactly on YEND, but will end with the first pixel that covers that Y value.
XSTART
The value of the X-coordinate for the first pixel in the input image to be included in the subset. Note that the subsetting is done on a whole pixel basis, so the resulting subset may not begin exactly on XSTART, but will start with the first pixel that covers that X value.
XEND
The value of the X-coordinate for the last pixel in the input image to be included in the subset. Note that the subsetting is done on a whole pixel basis, so the resulting subset may not end exactly on XEND, but will end with the first pixel that covers that X value.
OUTPUT
The name of the resulting subset image. If this is different to IMAGE, then a new file will be created, with everything bar the data a copy of the original image. If OUTPUT is the same as IMAGE, then the input file will be modified to contain just a subset of its original data.
Source comments:
   I S U B S E T
  
   Creates a subset of an image.
  
   Command parameters -
  
   IMAGE  (Char) The name of the structure containing the image.
   YSTART (Numeric) The AXIS(2) value for the start of the subset.
   YEND   (Numeric) The AXIS(2) value for the end of the subset.
   XSTART (Numeric) The AXIS(1) value for the start of the subset.
   XEND   (Numeric) The AXIS(1) value for the end of the subset.
   OUTPUT The name of the result of the operation.  This can
          be the same as for IMAGE.  If not, a new structure
          is created, with everything but the data a direct
          copy of the input.
  
                                    KS / CIT 19th June 1984

D.161 ISUPER-Produces a superset of an image

Description:
Given an input image, ISUPER creates a similar image whose dimensions are (possibly) different and where there is an overlap between the pixels of the two images. The overlap pixels are copied directly into the output image from the input, and all other pixels of the output image are zeroed. The overlap is specified in terms of the position of the left bottom (1,1) pixel of the input image on the output image. X and Y data arrays will also be supersetted if they contain linear data - otherwise no X and Y sub-structures will be created in the output structure.
Parameters:
IMAGE
The name of the input image.
XSIZE
The number of pixels in the X-direction for the output image. This can be more than, less than, or the same as, the number of X-pixels in the input image.
YSIZE
The number of pixels in the Y-direction for the output image. This can be more than, less than, or the same as, the number of Y-pixels in the input image.
XPIXEL
The overlap between the input and output images is specified in terms of the position of the bottom left (1,1) pixel of the input image in the output image. If this pixel does not map onto a pixel of the output image, the position should be given as a negative number, or as 0. (0 is the position of an imaginary pixel just outside the image.)
YPIXEL
The overlap between the input and output images is specified in terms of the position of the bottom left (1,1) pixel of the input image in the output image. If this pixel does not map onto a pixel of the output image, the position should be given as a negative number, or as 0. (0 is the position of an imaginary pixel just outside the image.)
OUTPUT
The name of the resulting superset image.
Source comments:
   I S U P E R
  
   Supersets an image or a spectrum, creating a new image
   with larger dimensions than the input, and with the input
   data just a part of the output image.  If the AXIS(1) or
   AXIS(2) arrays contain linear data, then output AXIS(1) and
   AXIS(2) sub-structures will be created reflecting this data.
   If they contain non-linear data, ISUPER will not attempt to
   extrapolate the data values and will omit the AXIS(1) or AXIS(2)
   sub-structure in question from the output structure.
   Note: It is also capable of subsetting.
  
   Command Parameters -
  
   IMAGE    (Character) The name of the input image.
   XSIZE    (Numeric) The AXIS(1)-dimension of the output image.
   YSIZE    (Numeric) The AXIS(2)-dimension of the output image.
   XPIXEL   (Numeric) The pixel number in AXIS(1) at which the input
            image is to start.
   YPIXEL   (Numeric) The pixel number in AXIS(2) at which the input
            image is to start.  That is, pixel (1,1) of the input
            image maps onto pixel (XPIXEL,YPIXEL) of the output.
            These values may be such that not all the input image
            appears in the output - they may even be negative.
   OUTPUT   (Character) The name of the output image.
  
   Command keywords -  None
  
   User variables used -  None
  
                                          KS / CIT 9th Aug 1984

D.162 ISXADD-Adds a spectrum to each X direction X-section of an image

Description:
A value is added to each pixel of each column in the image. The values to be added come from the corresponding pixels in an input spectrum.
Parameters:
IMAGE
Name of image.
SPECTRUM
Name of spectrum.
OUTPUT
Name of resulting image.
Source comments:
   I S O P S
  
   Performs a number of operations all of the general form
  
   Image=function(image,spectrum)
  
   Specifically, if an image is of format (IX,IY) then
  
   ISXSUB is Result = IMAGE(I,N)-SPECTRUM(I) 1<=I<=IX 1<=N<=IY
   ISXADD  "   "    = IMAGE(I,N)+SPECTRUM(I)    "        "
   ISXDIV  "   "    = IMAGE(I,N)/SPECTRUM(I)    "        "
   ISXMUL  "   "    = IMAGE(I,N)*SPECTRUM(I)    "        "
   ISYSUB is Result = IMAGE(N,I)-SPECTRUM(I) 1<=N<=IX 1<=I<=IY
   ISYADD  "   "    = IMAGE(N,I)+SPECTRUM(I)    "        "
   ISYDIV  "   "    = IMAGE(N,I)/SPECTRUM(I)    "        "
   ISYMUL  "   "    = IMAGE(N,I)*SPECTRUM(I)    "        "
  
   So the ISX... operations require a spectrum IX elements long,
   and the ISY... operations need one IY elements long.
  
   Command parameters -
  
   IMAGE    The name of the structure containing the first image.
  
   SPECTRUM The name of the structure containing the second
            image data.
  
   OUTPUT   The name of the result of the operation.  This can
            be the same as for IMAGE.  If not, a new structure
            is created, with everything but the data a direct
            copy of the input.
  
   The command itself (IXSADD,IXSMUL, etc.) is used to
   differentiate between the possible operations.
  
                                    KS / CIT 18th Feb 1983

D.163 ISXDIV-Divides a spectrum into each X direction x-section of an image

Description:
Each pixel of each column in the image is divided by a value. The divisor values come from the corresponding pixels in an input spectrum.
Parameters:
IMAGE
Name of image.
SPECTRUM
Name of spectrum.
OUTPUT
Name of resulting image.
Source comments:
   I S O P S
  
   Performs a number of operations all of the general form
  
   Image=function(image,spectrum)
  
   Specifically, if an image is of format (IX,IY) then
  
   ISXSUB is Result = IMAGE(I,N)-SPECTRUM(I) 1<=I<=IX 1<=N<=IY
   ISXADD  "   "    = IMAGE(I,N)+SPECTRUM(I)    "        "
   ISXDIV  "   "    = IMAGE(I,N)/SPECTRUM(I)    "        "
   ISXMUL  "   "    = IMAGE(I,N)*SPECTRUM(I)    "        "
   ISYSUB is Result = IMAGE(N,I)-SPECTRUM(I) 1<=N<=IX 1<=I<=IY
   ISYADD  "   "    = IMAGE(N,I)+SPECTRUM(I)    "        "
   ISYDIV  "   "    = IMAGE(N,I)/SPECTRUM(I)    "        "
   ISYMUL  "   "    = IMAGE(N,I)*SPECTRUM(I)    "        "
  
   So the ISX... operations require a spectrum IX elements long,
   and the ISY... operations need one IY elements long.
  
   Command parameters -
  
   IMAGE    The name of the structure containing the first image.
  
   SPECTRUM The name of the structure containing the second
            image data.
  
   OUTPUT   The name of the result of the operation.  This can
            be the same as for IMAGE.  If not, a new structure
            is created, with everything but the data a direct
            copy of the input.
  
   The command itself (IXSADD,IXSMUL, etc.) is used to
   differentiate between the possible operations.
  
                                    KS / CIT 18th Feb 1983

D.164 ISXMUL-Multiplies each X direction image x-sect by a spectrum

Description:
Each pixel of each column in the image is multiplied by a value. The multiplier values come from the corresponding pixels in an input spectrum.
Parameters:
IMAGE
Name of image.
SPECTRUM
Name of spectrum.
OUTPUT
Name of resulting image.
Source comments:
   I S O P S
  
   Performs a number of operations all of the general form
  
   Image=function(image,spectrum)
  
   Specifically, if an image is of format (IX,IY) then
  
   ISXSUB is Result = IMAGE(I,N)-SPECTRUM(I) 1<=I<=IX 1<=N<=IY
   ISXADD  "   "    = IMAGE(I,N)+SPECTRUM(I)    "        "
   ISXDIV  "   "    = IMAGE(I,N)/SPECTRUM(I)    "        "
   ISXMUL  "   "    = IMAGE(I,N)*SPECTRUM(I)    "        "
   ISYSUB is Result = IMAGE(N,I)-SPECTRUM(I) 1<=N<=IX 1<=I<=IY
   ISYADD  "   "    = IMAGE(N,I)+SPECTRUM(I)    "        "
   ISYDIV  "   "    = IMAGE(N,I)/SPECTRUM(I)    "        "
   ISYMUL  "   "    = IMAGE(N,I)*SPECTRUM(I)    "        "
  
   So the ISX... operations require a spectrum IX elements long,
   and the ISY... operations need one IY elements long.
  
   Command parameters -
  
   IMAGE    The name of the structure containing the first image.
  
   SPECTRUM The name of the structure containing the second
            image data.
  
   OUTPUT   The name of the result of the operation.  This can
            be the same as for IMAGE.  If not, a new structure
            is created, with everything but the data a direct
            copy of the input.
  
   The command itself (IXSADD,IXSMUL, etc.) is used to
   differentiate between the possible operations.
  
                                    KS / CIT 18th Feb 1983

D.165 ISXSUB-Subtracts each X direction image x-sect from a spectrum

Description:
A value is subtracted from each pixel of each column in the image. The values to be subtracted come from the corresponding pixels in an input spectrum.
Parameters:
IMAGE
Name of image.
SPECTRUM
Name of spectrum.
OUTPUT
Name of resulting image.
Source comments:
   I S O P S
  
   Performs a number of operations all of the general form
  
   Image=function(image,spectrum)
  
   Specifically, if an image is of format (IX,IY) then
  
   ISXSUB is Result = IMAGE(I,N)-SPECTRUM(I) 1<=I<=IX 1<=N<=IY
   ISXADD  "   "    = IMAGE(I,N)+SPECTRUM(I)    "        "
   ISXDIV  "   "    = IMAGE(I,N)/SPECTRUM(I)    "        "
   ISXMUL  "   "    = IMAGE(I,N)*SPECTRUM(I)    "        "
   ISYSUB is Result = IMAGE(N,I)-SPECTRUM(I) 1<=N<=IX 1<=I<=IY
   ISYADD  "   "    = IMAGE(N,I)+SPECTRUM(I)    "        "
   ISYDIV  "   "    = IMAGE(N,I)/SPECTRUM(I)    "        "
   ISYMUL  "   "    = IMAGE(N,I)*SPECTRUM(I)    "        "
  
   So the ISX... operations require a spectrum IX elements long,
   and the ISY... operations need one IY elements long.
  
   Command parameters -
  
   IMAGE    The name of the structure containing the first image.
  
   SPECTRUM The name of the structure containing the second
            image data.
  
   OUTPUT   The name of the result of the operation.  This can
            be the same as for IMAGE.  If not, a new structure
            is created, with everything but the data a direct
            copy of the input.
  
   The command itself (IXSADD,IXSMUL, etc.) is used to
   differentiate between the possible operations.
  
                                    KS / CIT 18th Feb 1983

D.166 ISYADD-Adds a spectrum to each Y direction x-section of an image

Description:
A value is added to each pixel of each row in the image. The values to be added come from the corresponding pixels in an input spectrum.
Parameters:
IMAGE
Name of image.
SPECTRUM
Name of spectrum.
OUTPUT
Name of resulting image.
Source comments:
   I S O P S
  
   Performs a number of operations all of the general form
  
   Image=function(image,spectrum)
  
   Specifically, if an image is of format (IX,IY) then
  
   ISXSUB is Result = IMAGE(I,N)-SPECTRUM(I) 1<=I<=IX 1<=N<=IY
   ISXADD  "   "    = IMAGE(I,N)+SPECTRUM(I)    "        "
   ISXDIV  "   "    = IMAGE(I,N)/SPECTRUM(I)    "        "
   ISXMUL  "   "    = IMAGE(I,N)*SPECTRUM(I)    "        "
   ISYSUB is Result = IMAGE(N,I)-SPECTRUM(I) 1<=N<=IX 1<=I<=IY
   ISYADD  "   "    = IMAGE(N,I)+SPECTRUM(I)    "        "
   ISYDIV  "   "    = IMAGE(N,I)/SPECTRUM(I)    "        "
   ISYMUL  "   "    = IMAGE(N,I)*SPECTRUM(I)    "        "
  
   So the ISX... operations require a spectrum IX elements long,
   and the ISY... operations need one IY elements long.
  
   Command parameters -
  
   IMAGE    The name of the structure containing the first image.
  
   SPECTRUM The name of the structure containing the second
            image data.
  
   OUTPUT   The name of the result of the operation.  This can
            be the same as for IMAGE.  If not, a new structure
            is created, with everything but the data a direct
            copy of the input.
  
   The command itself (IXSADD,IXSMUL, etc.) is used to
   differentiate between the possible operations.
  
                                    KS / CIT 18th Feb 1983

D.167 ISYDIV-Divides a spectrum into each Y direction x-section of an image

Description:
Each pixel of each row in the image is divided by a value. The divisor values come from the corresponding pixels in an input spectrum.
Parameters:
IMAGE
Name of image.
SPECTRUM
Name of spectrum.
OUTPUT
Name of resulting image.
Source comments:
   I S O P S
  
   Performs a number of operations all of the general form
  
   Image=function(image,spectrum)
  
   Specifically, if an image is of format (IX,IY) then
  
   ISXSUB is Result = IMAGE(I,N)-SPECTRUM(I) 1<=I<=IX 1<=N<=IY
   ISXADD  "   "    = IMAGE(I,N)+SPECTRUM(I)    "        "
   ISXDIV  "   "    = IMAGE(I,N)/SPECTRUM(I)    "        "
   ISXMUL  "   "    = IMAGE(I,N)*SPECTRUM(I)    "        "
   ISYSUB is Result = IMAGE(N,I)-SPECTRUM(I) 1<=N<=IX 1<=I<=IY
   ISYADD  "   "    = IMAGE(N,I)+SPECTRUM(I)    "        "
   ISYDIV  "   "    = IMAGE(N,I)/SPECTRUM(I)    "        "
   ISYMUL  "   "    = IMAGE(N,I)*SPECTRUM(I)    "        "
  
   So the ISX... operations require a spectrum IX elements long,
   and the ISY... operations need one IY elements long.
  
   Command parameters -
  
   IMAGE    The name of the structure containing the first image.
  
   SPECTRUM The name of the structure containing the second
            image data.
  
   OUTPUT   The name of the result of the operation.  This can
            be the same as for IMAGE.  If not, a new structure
            is created, with everything but the data a direct
            copy of the input.
  
   The command itself (IXSADD,IXSMUL, etc.) is used to
   differentiate between the possible operations.
  
                                    KS / CIT 18th Feb 1983

D.168 ISYMUL-Multiplies each Y direction image x-sect by a spectrum

Description:
Each pixel of each row in the image is multiplied by a value. The multiplier values come from the corresponding pixels in an input spectrum.
Parameters:
IMAGE
Name of image.
SPECTRUM
Name of spectrum.
OUTPUT
Name of resulting image.
Source comments:
   I S O P S
  
   Performs a number of operations all of the general form
  
   Image=function(image,spectrum)
  
   Specifically, if an image is of format (IX,IY) then
  
   ISXSUB is Result = IMAGE(I,N)-SPECTRUM(I) 1<=I<=IX 1<=N<=IY
   ISXADD  "   "    = IMAGE(I,N)+SPECTRUM(I)    "        "
   ISXDIV  "   "    = IMAGE(I,N)/SPECTRUM(I)    "        "
   ISXMUL  "   "    = IMAGE(I,N)*SPECTRUM(I)    "        "
   ISYSUB is Result = IMAGE(N,I)-SPECTRUM(I) 1<=N<=IX 1<=I<=IY
   ISYADD  "   "    = IMAGE(N,I)+SPECTRUM(I)    "        "
   ISYDIV  "   "    = IMAGE(N,I)/SPECTRUM(I)    "        "
   ISYMUL  "   "    = IMAGE(N,I)*SPECTRUM(I)    "        "
  
   So the ISX... operations require a spectrum IX elements long,
   and the ISY... operations need one IY elements long.
  
   Command parameters -
  
   IMAGE    The name of the structure containing the first image.
  
   SPECTRUM The name of the structure containing the second
            image data.
  
   OUTPUT   The name of the result of the operation.  This can
            be the same as for IMAGE.  If not, a new structure
            is created, with everything but the data a direct
            copy of the input.
  
   The command itself (IXSADD,IXSMUL, etc.) is used to
   differentiate between the possible operations.
  
                                    KS / CIT 18th Feb 1983

D.169 ISYSUB-Subtracts each Y direction image x-sect from a spectrum

Description:
A value is subtracted from each pixel of each row in the image. The values to be subtracted come from the corresponding pixels in an input spectrum.
Parameters:
IMAGE
Name of image.
SPECTRUM
Name of spectrum.
OUTPUT
Name of resulting image.
Source comments:
   I S O P S
  
   Performs a number of operations all of the general form
  
   Image=function(image,spectrum)
  
   Specifically, if an image is of format (IX,IY) then
  
   ISXSUB is Result = IMAGE(I,N)-SPECTRUM(I) 1<=I<=IX 1<=N<=IY
   ISXADD  "   "    = IMAGE(I,N)+SPECTRUM(I)    "        "
   ISXDIV  "   "    = IMAGE(I,N)/SPECTRUM(I)    "        "
   ISXMUL  "   "    = IMAGE(I,N)*SPECTRUM(I)    "        "
   ISYSUB is Result = IMAGE(N,I)-SPECTRUM(I) 1<=N<=IX 1<=I<=IY
   ISYADD  "   "    = IMAGE(N,I)+SPECTRUM(I)    "        "
   ISYDIV  "   "    = IMAGE(N,I)/SPECTRUM(I)    "        "
   ISYMUL  "   "    = IMAGE(N,I)*SPECTRUM(I)    "        "
  
   So the ISX... operations require a spectrum IX elements long,
   and the ISY... operations need one IY elements long.
  
   Command parameters -
  
   IMAGE    The name of the structure containing the first image.
  
   SPECTRUM The name of the structure containing the second
            image data.
  
   OUTPUT   The name of the result of the operation.  This can
            be the same as for IMAGE.  If not, a new structure
            is created, with everything but the data a direct
            copy of the input.
  
   The command itself (IXSADD,IXSMUL, etc.) is used to
   differentiate between the possible operations.
  
                                    KS / CIT 18th Feb 1983

D.170 IXSMOOTH-Smooth in X-direction by gaussian convolution

Description:
IXSMOOTH smooths cross-sections of an array in the X-direction by convolving them with a gaussian of specified sigma and a specified cutoff width. Note that this is not a 2-D smooth, but a series of 1-D smooths; hence the name.

The VARIANCE array, if present, is propagated in exactly the same way as the DATA array. This procedure it not formally correct and the computed variance will probably under-estimate the true error.

Parameters:
IMAGE
Name of data to be smoothed.
SIGMA
Gaussian half width in pixels.
WIDTH
Pixels over which gaussian is calculated.
OUTPUT
Name of resulting data.
See also:
FIGARO: ICONV3, ISMOOTH, MEDFILT.
KAPPA: CONVOLVE, FFCLEAN, GAUSMOOTH, MEDIAN.
Source comments:
   I X S M O O T H
  
   This routine is the main body of IXSMOOTH, which smooths
   cross-sections of an array in the X-direction by convolving
   them with a gaussian of specified sigma and a specified
   cutoff width.  Note that this is not a 2-D smooth, but a series
   of 1-D smooths; hence the name.
  
   The VARIANCE array, if present, is propagated in exactly the same
   way as the DATA array.  This procedure it not formally correct and
   the computed variance will probably under-estimate the true error.
  
   Command parameters -
  
   IMAGE  The name of the structure containing the image.
  
   SIGMA  (Numeric) The sigma of the gaussian, expressed in array
          elements.  (This is approximately the half width at
          half maximum, to within a factor of ~1.17).
  
   WIDTH  (Numeric) The number of array elements over which the
          gaussian is calcualted - i.e. outside this range the
          gaussian is assumed to be zero.  This simplifies the
          computation and also allows the use of strangely shaped
          functions such as gaussians with very large sigmas but
          small widths - which are almost the same as rectangular
          filters.
  
   OUTPUT The name of the result of the operation.  This can
          be the same as for IMAGE.  If not, a new structure
          is created, with everything but the data a direct
          copy of the input.
  
                                    KS / CIT 23rd March 1983

D.171 LINTERP-Interpolates between spiketrum points to form a spectrum

Description:
LINTERP interpolates between the points of a ’spiketrum’ - an array where most of the data is zero except for a few elements whose values are set - to produce a spectrum. Interpolation is linear between the points of the spiketrum.
Parameters:
SPIKETRUM
The name of the spiketrum - an array where only a few elements are set to the correct values, the other elements all being zero - which is to be used to produce a spectrum by interpolation between those specified elements. SPIKETRUM has probably been produced by GSPIKE from a table of values.
SPECTRUM
The name of the spectrum to be produced by interpolation between the points of the spiketrum.
Source comments:
   I N T E R P    /     S P I F I T    /   L I N T E R P
  
   Interpolates between the points of a ’spiketrum’ to
   generate a spectrum.   The INTERP command does this by
   spline interpolation, the SPIFIT command uses global polynomial
   fitting, and the LINTERP command uses linear interpolation.
  
   Command parameters -
  
   SPIKETRUM  The name of the structure containing the spiketrum
  
   ORDER      The order for the global polynomial to be fitted
              (SPIFIT only).
  
   SPECTRUM   The name of the result of the operation.  This can
              be the same as for SPIKE.  If not, a new structure
              is created, with everything but the data a direct
              copy of the input.
  
   Command keywords  -
  
   LOG        (INTERP & SPIFIT only) Perform the interpolation on
              the log of the data
  
   LINEND     (INTERP only) Use a linear interpolation for the
              ends of the data - spline fits can go wild outside the
              range of the defined points.
  
   User variables used - None
                                    KS / CIT 6th July 1984
  

D.172 LONGSLIT-Fits 2D longslit arrays and plots results

Description:
LONGSLIT can fit Gaussians, skew Gaussians, Lorentzians and Cauchy functions to line profiles, and can carry out line profile analysis to produce the Whittle and Heckman asymmetry parameters. Much of this can be carried out in batch mode. This program generates rotation curves from 2D data, for a number of emission/absorption lines. Options are available to automatically fit each line in the spectrum or to do it in an interactive manner allowing unsatisfactory fits to be rejected. Unsatisfactory fits may then be refitted on a second pass. For each line a table is created containing all the fit parameters as a function of crossection.If the data has been block averaged in an range of XSECTS the average XSECT value and the XSECT range are computed and stored. In manual mode the user can sweep through the XSECTS choosing different BLOCKINGS and line types repeatedly until he either accepts the fit or issues an instruction not to fit a given range of XSECTS. Continuum Fitting is provided in two ways. Firstly a GLOBAL continuum may be defined for each block of data. This is a continuum which is fitted to all regions of the spectrum which do NOT contain lines. A variety of models are available. Chebyshev Polynomials, Splines, (Power Law, Black Body, Black Body with optical depth cuttoff, Empirical, and Balmer Continuum). Secondly, A local continuum may be applied to each INDIVIDUAL line. This continuum is applied in addition to that created by GLOBAL but is confined to the regions of the spectra containing a particular line. Because most of the allowed line options also fit a FLAT base the combination of these fits can be made to match even the most complex continua The types of allowed continuum models for INDIVIDUAL is restricted to Spline, Flat or Chebyshev. It is possible to Edit the results cube created by LONGSLIT and to create new Synthetic spectra by doing model -data manipulations or from the models themselves. During this process several usefull things can be done to the output spectra, notably changing their Redshift, applying or removing Reddening. A similar approach creating Sky subracted data and using sky lines for correcting for instrumental vignetting is also possible. Rotation curves in individual lines are produced as requested in the PLOT mode. In addition it is possible to calculate a mean rotation curve. In the current release the user now has complete control over the plotting parameters and the lines being plotted.
Parameters:
IMAGE
IMAGE = FILE (Read) Name of image for input This is the data. This should be a .dst file with a .Z.DATA component. This should also have a .X.DATA array which contains the wavelengths of the lines. For the identification files supplied with the program the units should be Angstroms, but if the user supplies his/her own files, this need not apply, although some plots may have the wrong labels.
ARC_OPTS
ARC_OPTS = CHARACTER (Read) Enter fit option NEW : set up a new analysis REPEAT : iterate on previous analysis CLONE : Clone an analysis from another file (line locations etc.)
YSTART
YSTART = INTEGER (Read) analysis lower limit
YEND
YEND = INTEGER (Read) analysis upper limit
YBLOCK
YBLOCK = INTEGER (Read) Enter analysis x-sect width
ITERATION
ITERATION = INTEGER*2 (Read) New value of iteration
MAXLINES
MAXLINES = INTEGER (Read) Maximum number of lines to allow room for
CLFILE
CLFILE = FILE (Read) Name of image for cloning from
OUTABLE
OUTABLE = FILE (Write) Name for extactic file
VCORR
VCORR = REAL (Read) correction to apply to radial velocities
TOLS
TOLS = CHARACTER (Read) For use in batch only
INHERIT
INHERIT = INTEGER (Read) Number to control inheritance of previous fits If zero no inheritance of fits If one then inherited from next block If minus one then inherited from previous block
DEVICE
DEVICE = CHARACTER (Read) Device to use for greyscale plots
FITRAT
FITRAT = REAL (Read) Ratio for double fitting (of widths/heights or separation)
CALRAT
CALRAT = INTEGER (Read) Ratio to multiply default number of iterations in Nag optimisation
WHITE
WHITE = REAL (Read) White level for greyscale plots
BLACK
BLACK = REAL (Read) Black level for greyscale plots
MAXGAUSS
MAXGAUSS = INTEGER (Read) Maximum number of Gaussians to allow room for LONGSLIT can fit up to 9 component fits, but the results array for such is quite large. This allows the user to set the maximum number of components he/she is likely to fit, since very little data requires 9 components!
TSTART
TSTART = REAL (Read) analysis lower limit
TEND
TEND = REAL (Read) analysis upper limit
TBLOCK
TBLOCK = REAL (Read) Analysis blocking width in T direction
FIT_MODEL
FIT_MODEL = CHARACTER (Read) Model of fit to perform
PLOTLIM
PLOTLIM(4) = REAL ARRAY (Read) Limits for velocity plots
OUTPUT
OUTPUT = FILE (Write) Name of output file
HARDCOPY
HARDCOPY = LOGICAL (Read) produce hardcopy plots of fits from cube
TABLE
TABLE = LOGICAL (Read) produce table of fits from cube
PLOT
PLOT = LOGICAL (Read) produce plots of rotation curves
PRINT
PRINT = LOGICAL (Read) produce print out of rotation curves
SHAPE
SHAPE = LOGICAL (Read) carry out shape analysis
KEEP_ITT
KEEP_ITT = LOGICAL (Read) keep iteration files
FIT
FIT = LOGICAL (Read) perform fitting
COPY
COPY = LOGICAL (Read) copy previous fits This will repeat all the fits previously made, which is likely to be of use if data is co-added after one file has been analysed. Also, when used with CLONE the entire .RES structure is copied without any change. For the new fits the previous fits (suitably scaled) are used as first guesses.
ABSORPTION
ABSORPTION = LOGICAL (Read) Allow fitting of absorption lines
BOUNDS
BOUNDS = LOGICAL (Read) Perform bounded fits to lines (in batch)
LABEL
LABEL = LOGICAL (Read) Put labels on plots
CONTOUR
CONTOUR = LOGICAL (Read) Create contour plots
GREY
GREY = LOGICAL (Read) Create greyscale plots
LOG
LOG = LOGICAL (Read) Use logarithmic scale for CONTOUR and GREY
WEIGHTS
WEIGHTS = LOGICAL (Read) Use weights for fitting
PRFITS
PRFITS = LOGICAL (Read) Print out details of fitting
FULL
FULL = LOGICAL (Read) Print out full details of fits in table
CHECK
CHECK = LOGICAL (Read) Plot array of line profiles
Source comments:
    none available
  

D.173 LSPLOT-Hardcopy spectrum plot of specified size (up to 3 metres)

Description:
LSPLOT produces a splot of a spectrum, usually on a hard copy device, with a physical size that can be specified (in metres) by the user. The device used is that specified by the HARD command. It will allow plots up to the maximum size allowed by the GKS driver being used - in some cases this means that a non-standard device name must be specified in order to allow a larger maximum size than usual. LSPLOT is very similar to SPLOT, except that it has plot dimension parameters and does not support build plots.
Parameters:
SPECTRUM
The name of the spectrum to be plotted by LSPLOT. It should be a 1-dimensional array.
XSIZE
The length of the plot in metres. LSPLOT can produce plots up to 10 metres in length.
YSIZE
The height of the plot in metres. The reset value is the full page height for the device.
WHOLE
If set, the whole of the spectrum is plotted. Otherwise, the limits plotted are determined by the values of XSTART and XEND, which you will be prompted for if they were not specified in the command string.
AUTOSCALE
If set, the plot is scaled so that all of the data to be plotted just fits on the display. Otherwise, the scale of the plot is determined by the values of HIGH and LOW, which you will be prompted for if they were not specified in the command string.
XSTART
Specifies the first X value to be plotted, in the units used by the data - angstroms, for example, if the data is wavelength calibrated. XSTART can be set before the start of the data, if necessary. RESET will set XSTART to the first X value in the data.
XEND
Specifies the last X value to be plotted, in the units used by the data - angstroms, for example, if the data is wavelength calibrated. XEND can be set after the end of the data, if necessary. RESET will set XEND to the last X value in the data.
HIGH
The maximum data value to be plotted - i.e. the top Y axis value for the plot.
LOW
The minimum data value to be plotted - i.e. the bottom Y axis value for the plot.
BIAS
A bias value applied to the data, usually to bias up a plot which is to be superimposed upon a previous plot of almost identical data values. This makes the comparison easier. BIAS N is essentially equivalent to setting HIGH and LOW down by an amount N, so can result in unexpected axis values.
LABEL
The label that will appear at the top of the plot.
LINES
Specifies that the plot is to made as a ’point-plot’, in a ’join the dots’ fashion. The alternative is a histogram plot. LINES will usually be a little faster, but messier, because the resolution of the plotting device may result in stepped lines.
Source comments:
   L S P L O T    /    E L S P L O T
  
   These are versions of SPLOT and ESPLOT that allow the size of
   the plot to be specified.  LSPLOT produces a plot of a single
   spectrum, while ESPLOT produces an error bar plot of a spectrum
   which has error information.
  
   Command parameters -
  
   XSIZE       The size of the plot in X, in metres.
   YSIZE       The size of the plot in Y, in metres.
   SPECTRUM    The data to be plotted.  If there
               is an x-axis data component this will be used to
               give the x-axis.  If not, the x-axis will just
               have to be the numbers from 1 to n.
   XSTART      The x-value at which plotting is to start.
   XEND        The x-value at which plotting is to end.
               (XSTART and XEND are not required if the
               WHOLE keyword is set.)
   HIGH        The maximum value to be used for the plot.
   LOW         The minimum value to be used for the plot.
   BIAS        A value used to displace the plot - BIAS is
               effectively a value added to the data before
               it is plotted. (It is implemented as a value
               subtracted from both HIGH and LOW.)
               (HIGH,LOW and BIAS are not required if the
               AUTOSCALE keyword is set.)
   LABEL       A label for the plot.
  
   Command keywords -
  
   AUTOSCALE   The program is to work out the values for HIGH
               and LOW, using the maximum and minimum values
               in the data over the specified range.
   WHOLE       The program is to display all of the spectrum.
   LINES       The plot is not done as a histogram, but as
               a ’join the dots’ line plot.  (LSPLOT only)
  
   User variables used:
  
   HARD        (Character) The device used for HARD plots.
  
   Note:
  
   The original version of LSPLOT used GKS 6.2 and the DIAGRAM
   package.  This has now been discontinued, and some of the
   functionality of DIAGRAM (the ability to specify the size of
   the plot in physical units) has appeared in PGPLOT.  This new
   version uses PGPLOT.  It can produce a plot of the specified
   size, BUT only if that size is SMALLER than the default size
   for the device.  In practice, this means that it can only work
   in the way it was intended with ‘unusual’ devices that have
   particularly large default plot sizes (which often need to be set
   up specially for the purpose).
                                       KS / AAO 30th Jan 1984

D.174 LXSET-Set X array of spectrum/image to specified range

Description:
LXSET is a fudging routine used to set the X values for an image or spectrum, given a start and end value. The values can be set to vary linearly or logarithmically.
Parameters:
IMAGE
The name of the image (or spectrum) whose X values are to be set. If IMAGE already has an X array, this will be modified. If it does not, a new one will be created.
WSTART
Specifies the value (usually a wavelength) to be used for the first element of the X array. Note that the value refers to the CENTER of the bin - it’s easy to find yourself one bin out.
WEND
Specifies the value (usually a wavelength) to be used for the last element of the X array. Note that the value refers to the CENTER of the bin - it’s easy to find yourself one bin out.
OUTPUT
The name of the resulting image (or spectrum). If this is the same as IMAGE, the original file will be modified. Otherwise, a new file will be created.
LOG
If set, the X values will vary in a logarithmic manner between WSTART and WEND. The default is for them to vary linearly.
See also:
FIGARO: LYSET.
KAPPA: SETAXIS, AXCONV, AXLABEL, AXUNITS.
Source comments:
   L S E T
  
   This routine is the main body of LXSET,LYSET
  
   LXSET is a fudging routine that sets the range of the first axis
   associated with a spectrum or image, given a start and end wavelength and
   whether or not the wavelengths are to be scaled logarithmically.
  
   LYSET performs an analgous set for the second axis structure
   (for images).
  
   Command parameters -
  
   IMAGE      (Character) The name of the structure containing the image.
  
   WSTART or  (Numeric) The value of the CENTER of the first
   VSTART      bin of the resulting data. WSTART and VSTART are used
               by  LXSET and LYSET respectively)
  
   WEND  or   (Numeric) The value of the CENTER of the final
   VEND        bin of the resulting data. WEND and VEND are used
               by  LXSET and LYSET respectively)
  
   OUTPUT     (Character) The name of the result of the operation.
              This can be the same as for IMAGE.  If not, a new structure
              is created, with everything but the axis data a direct
              copy of the input.
  
   Command keywords -
  
   LOG    Axis values are to increase logarithmically.
  
                                    KS / AAO 28th MArch 1985

D.175 LYSET-Set Y array of spectrum/image to specified range

Description:
LYSET is a fudging routine used to set the Y values for an image given a start and end value. The values can be set to vary linearly or logarithmically.
Parameters:
IMAGE
The name of the image whose Y values are to be set. If IMAGE already has an Y array, this will be modified. If it does not, a new one will be created.
VSTART
Specifies the value to be used for the first element of the Y array. Note that the value refers to the CENTER of the bin - it’s easy to find yourself one bin out.
VEND
Specifies the value to be used for the last element of the Y array. Note that the value refers to the CENTER of the bin - it’s easy to find yourself one bin out.
OUTPUT
The name of the resulting image (or spectrum). If this is the same as IMAGE, the original file will be modified. Otherwise, a new file will be created.
LOG
If set, the Y values will vary in a logarithmic manner between VSTART and VEND. The default is for them to vary linearly.
See also:
FIGARO: LXSET.
KAPPA: SETAXIS, AXCONV, AXLABEL, AXUNITS.
Source comments:
   L S E T
  
   This routine is the main body of LXSET,LYSET
  
   LXSET is a fudging routine that sets the range of the first axis
   associated with a spectrum or image, given a start and end wavelength and
   whether or not the wavelengths are to be scaled logarithmically.
  
   LYSET performs an analgous set for the second axis structure
   (for images).
  
   Command parameters -
  
   IMAGE      (Character) The name of the structure containing the image.
  
   WSTART or  (Numeric) The value of the CENTER of the first
   VSTART      bin of the resulting data. WSTART and VSTART are used
               by  LXSET and LYSET respectively)
  
   WEND  or   (Numeric) The value of the CENTER of the final
   VEND        bin of the resulting data. WEND and VEND are used
               by  LXSET and LYSET respectively)
  
   OUTPUT     (Character) The name of the result of the operation.
              This can be the same as for IMAGE.  If not, a new structure
              is created, with everything but the axis data a direct
              copy of the input.
  
   Command keywords -
  
   LOG    Axis values are to increase logarithmically.
  
                                    KS / AAO 28th MArch 1985

D.176 MASK-Generate a mask spectrum given a spectrum and a mask table

Description:
Given a spectrum and a table of masked regions, MASK creates a mask spectrum which is the same as the original spectrum in the masked regions, but zero everywhere else. The mask will have the same x-values as the original spectrum.
Parameters:
SPECTRUM
The name of the original spectrum.
TABLE
The name of the file containing the regions to be masked. This is a text file. If no extension is specified, .MSK will be assumed. The table can be one supplied as part of Figaro, or can be one supplied by the user, either in the current default directory or in one with the logical name FIGARO_PROG_U. (There is usually no need to specify the directory, since the program will search for it.)
MASK
The name of the mask spectrum generated.
Source comments:
   M A S K
  
   Generates a spectral mask given a spectrum and a mask
   table file.  The mask table contains a set of central
   wavelengths and number of anstroms covered, one for each
   part of the spectrum to be masked.  The program generates
   a spectrum covering the same wavelength range as the
   original spectrum, with the masked areas set to the same
   values as the original spectrum in those areas, and the
   unmasked areas set to zero.
  
   Command parameters -
  
   SPECTRUM   (Character) The spectrum to be used
   TABLE      (Character) The mask table file to be used - if
              the file has no extension, .MSK will be assumed.
              The program searches for the mask file in the
              standard Figaro search path for such files.
   MASK       (Character) The output mask name.
  
   User variables used - None
                                        KS / CIT 4th April 1984

D.177 MASKEXT-Extracts echelle orders using a mask created by ECHMASK

Description:
Extracts spectra from an image using a mask image. The mask pixel values should be the numbers of the spectra that fall in that pixel of the image. This routine is intended for use with echelle data, and the numbers in the image are expected to be based on echelle order numbers. The spectra are extracted into an image whose Y-axis is the order number of the spectra, and whose X-axis is that of the original data. The actual numbers in the image are expected to have the form (echelle order number)*10 + (sub order number), sub orders referring to separate spectra from the same order, as produced, for example, by the UCL echelle at AAO. MASKEXT will extract one specified sub-order from each order, or will add all the sub-orders together for each order.
Parameters:
IMAGE
Name of image containing spectra.
MASK
Name of mask image.
MLOW
Lowest order number to extract.
MHIGH
Highest order number to extract.
SUBORD
Sub-order to extract (0 => all).
REVERSE
Create output with order numbers reversed?
OUTPUT
Name of resulting set of spectra
Source comments:
   M A S K E X T
  
   Extracts spectra from an image using a mask image.  The mask
   pixel values should be the numbers of the spectra that fall
   in that pixel of the image.  This routine is intended for use
   with echelle data, and the numbers in the image are expected
   to be based on echelle order numbers.  The spectra are extracted
   into an image whose Y-axis is the order number of the spectra,
   and whose X-axis is that of the original data.  The actual
   numbers in the image are expected to have the form
   (echelle order number)*10 + (sub order number), sub orders
   referring to separate spectra from the same order, as
   produced, for example, by the UCL echelle at AAO.
   MASKEXT will extract one specified sub-order from each
   order, or will add all the sub-orders together for each order.
  
   Command parameters -
  
   IMAGE      (Character) The name of the image containing the
              spectra to be extracted
   MASK       (Character) The name of the mask image.
   MLOW       (Integer) The lowest order number to be extracted.
   MHIGH      (Integer) The higest order number to be extracted.
   SUBORD     (Integer) The sub-order number to be extracted.
              If zero, all sub-orders are added for each order.
   OUTPUT     (Character) The name of the resulting image.
  
   Command keywords -
  
   REVERSE    If set, the image created will have the
              spectral orders in reverse order - higher order
              numbers being at the start of the image.
  
   29th May 1988  KS/AAO.  Original version.
  
   Note -
  
   This version is an interim one - it really needs re-writing
   using DSA_RESHAPE_DATA and DSA_RESHAPE_AXIS.

D.178 MCFIT-Fit a continuum to a spectrum, given a mask spectrum

Description:
Performs a masked fit to a spectrum. At a given number of equally separated points in the spectrum, the average of the surrounding points is taken and a new spectrum is formed by interpolating between the resulting values. Any points in spectrum for which the corresponding element of the mask spectrum is non-zero will be ignored.
Parameters:
SPECTRUM
The spectrum to which the masked fit is to be applied. At a given number of equally separated points in SPECTRUM, the average of the surrounding data is taken and a new spectrum formed by interpolating between the resulting values.
MASK
The name of the spectrum to be used as a mask. Any points in SPECTRUM for which the corresponding element in MASK is non-zero will be ignored in the fit.
POINTS
The number of spline points to be used in the fit. The actual number used may be less, since the points are equispaced and some may be masked out.)
OUTPUT
The name of the resulting fitted spectrum. Note that the default is the same as SPECTRUM - i.e. the fitting will be performed in situ, which is faster but destroys the original data.
Source comments:
   M C F I T
  
   Performs a masked fit to a spectrum.  At a given number of
   equally separated points in the spectrum, the average of the
   surrounding points is taken and a new spectrum is formed by
   interpolating between the resulting values.  Any points in the
   spectrum for which the corresponding element of the mask spectrum
   is non-zero will be ignored.
  
   Command parameters -
  
   SPECTRUM     (Character) The spectrum to be fitted
   MASK         (Character) The mask spectrum to be used
   POINTS       (Numeric) The number of points to be used
   OUTPUT       (Character) The name of the resulting spectrum
  
   Command keywords - None
  
   User variables used - None
                                  KS / CIT 8th April 1984

D.179 MEDFILT-Applies a median filter to an image

Description:
The result of this operation is an image in which the value of each pixel is the median value of a rectangular box of pixels centered on the corresponding pixel in the original array. MEDFILT only supports a square box. MEDFILTR allows rectangular boxes to be used.
Parameters:
IMAGE
Name of image to be smoothed.
BOX
Size of box for median calculations.
OUTPUT
Name of resulting image.
See also:
FIGARO: MEDFILTR, BCLEAN, CLEAN, COSREJ, ISMOOTH, IXSMOOTH.
KAPPA: FFCLEAN, GAUSMOOTH, MEDIAN.
Source comments:
   M E D F I L T   /    M E D F I L T R
  
   Figaro routines to median filter an image.  The result of
   this operation is an image in which the value of each pixel
   is the median value of a rectangular box of pixels centered on the
   corresponding pixel in the original array. MEDFILTR allows the
   box to be specified with different X and Y dimensions, while the
   original MEDFILT only supported a square box. MEDFILTR is therefore
   a full superset of MEDFILT, but the older application has to be
   retained for compatability reasons.
  
   Command parameters for MEDFILT -
  
   IMAGE    The name of the structure containing the image.
  
   BOX      (Numeric) The size of the box (in pixels) to be
            used in calculating the medians.  Should be odd;
            if even, BOX-1 will be used.
  
   OUTPUT   The name of the result of the operation.  This can
            be the same as for IMAGE.  If not, a new structure
            is created, with everything but the data a direct
            copy of the input.
  
                                    KS / CIT 28th Jan 1984

D.180 MEDFILTR-Applies a rectangular median filter to an image

Description:
MEDFILTR passes a rectangular median filter through the main data array of an image. The result is an image where each pixel is set to the median value found in the image within a box of the given size centered on that pixel. MEDFILT is a similar program, but it uses a square shaped filter box whereas MEDFILTR allows the box to have different dimensions in X and Y.
Parameters:
IMAGE
The name of a Figaro format data file. A rectangular median filter of size XBOX by YBOX will be passed through the main data array of the file. The file should normally contain two-dimensional data, but other data can be accomodated - this will require YBOX to be set to 1.
XBOX
The X-dimension of the box to be used for the median filter. It is specified in pixels, and ought to be an odd number. If an even number is used, XBOX-1 will be used instead.
YBOX
The Y-dimension of the box to be used for the median filter. It is specified in pixels, and ought to be an odd number. If an even number is used, YBOX-1 will be used instead. If the data is not a 2-D image, YBOX will be forced to 1.
OUTPUT
The name of the resulting new image file. If it differs from that specified for IMAGE then a new file is created, otherwise the filter is applied in situ.
Source comments:
   M E D F I L T   /    M E D F I L T R
  
   Figaro routines to median filter an image.  The result of
   this operation is an image in which the value of each pixel
   is the median value of a rectangular box of pixels centered on the
   corresponding pixel in the original array. MEDFILTR allows the
   box to be specified with different X and Y dimensions, while the
   original MEDFILT only supported a square box. MEDFILTR is therefore
   a full superset of MEDFILT, but the older application has to be
   retained for compatability reasons.
  
   Command parameters for MEDFILTR -
  
   IMAGE    The name of the structure containing the image.
  
   XBOX     (Numeric) The X-dimension of the box (in pixels) to be
            used in calculating the medians.  Should be odd;
            if even, XBOX-1 will be used.
  
   YBOX     (Numeric) The Y-dimension of the box (in pixels) to be
            used in calculating the medians.  Should be odd;
            if even, YBOX-1 will be used.
  
   OUTPUT   The name of the result of the operation.  This can
            be the same as for IMAGE.  If not, a new structure
            is created, with everything but the data a direct
            copy of the input.
  
                                    KS / CIT 28th Jan 1984

D.181 MEDSKY-Take the median of a number of images

Description:
MEDSKY takes a series of images and produces a single image in which each pixel is the median of the corresponding pixels in the series of images. Note that this is a time-consuming operation. The algorithm used attempts to optimise itself for the amount of memory available and will run much faster if the user has a large working set.
Parameters:
FILES
The name of a text file, each line of which should give the name of an input image. These are the images that will be used to form the output median image.
OUTPUT
The name of the file to be created, in which the value of each pixel is the median value of the corresponding pixels in the input images. Note that OUTPUT must not have the same name as any of the input images - the results will be incorrect if this is the case.
IMGLOG
If LOG is set, IMGLOG supplies the name of the ’log’ file produced. This has nothing but a data array containing the numbers from 1 to N of the images that supplied the corresponding median values in the output median image. (Note that if more than one image contained a given median value, the number chosen will be the lowest of the possible values - i.e. the first image has precedence)
SCALED
If set, then MEDSKY calculates the overall median value for each image in turn, and before using the data from an image, multiplies it by a scaling factor given by the median value of the first image divided by the median value of the image being used. This means that all images are conceptually scaled to the median level of the first image before being used. If SCALED is set a file - MEDSKY.LOG - is written giving the file name, median value, and scaling factor used for each image.
LOG
LOG can be set to produce a diagnostic image called a ’log’ image as well as the normal output median image. A ’log’ image is an integer array of the same size as the output image, in which each pixel contains the image number in the order given in the file giving the list of images) of the image that supplied the median value used. If LOG is set, the name of the ’log’ image is supplied by the IMGLOG parameter.
See also:
FIGARO: BCLEAN, CLEAN, COSREJ, MEDFILT.
KAPPA: MEDIAN, MSTATS.
Source comments:
   M E D S K Y
  
   MEDSKY is a program for constructing sky flats for direct imaging,
   using an algorithm due to Schneider, Schmidt and Gunn.
  
   A list of images is read in from file,and the medians of
   equivalent pixels in all the images are found, eg. for N images
   (of any size), the first pixel ( the top-left one) in each image
   is fetched : the median of these N pixels is then found, the
   result becoming the first pixel in the output image. This process
   is repeated for all the pixels in the input images to construct a
   complete output image. In practice, more than one pixel is
   analysed per pass through the image file list, the number being
   determined by the memory available to the program. MEDSKY attempts
   to minimise the page faulting which would occur by accessing too
   much virtual memory at once by processing fewer pixels per pass,
   on the assumption that the extra overheads in doing more passes
   will be more than offset by fewer page faults. This approach seems
   to have been justified, but performance is very sensitive to
   changes in the proportions of memory allocated, and it is possible
   that improvements could be made.
  
   Command parameters -
  
   FILES  The name of a .DAT file containing a list of names
          of images. All these images must have dimensions
          equal to those of the first image in the list, FIRST.
  
   OUTPUT The name of the result of the operation.  This can
          be the same as for FIRST.  If not, a new structure
          is created, with everything but the data a direct
          copy of the input.
  
   IMGLOG Only used if the LOG keyword is set.  This supplies
          the name of the ’log’ image created.  This will contain
          a single integer data array.
  
   Important
   ~~~~~~~~~
   MEDSKY does not check that the output image name is not a member
   of the image file list.
  
   Command keywords  -
  
   SCALED If set, MEDSKY attempts to compensate for differences
          in data scale between the different images.  It does this
          by conceptually scaling all images so that they have the
          same median value as the first image.
  
   LOG    If set, MEDSKY creates a ’log’ image.  This is an
          image with the same dimensions as the output image, with
          each pixel a number from 1 to N (the number of files)
          showing the image number which for each output pixel had
          the data value closest to the median value calculated.
          This can be used to see if any image dominates the others,
          or if there is any trend across the image. This is a rather
          specialised option, and is not expected to be used much.
  
   User variables used - None
                                    DJA / AAO. 16th Aug 1987

D.182 MOMENTS-Calculate moments of spectra in a cube.

Usage:

moments in comp

Description:

This routine calculates the moments for each spectrum in a cube.

Parameters:
INFO
INFO = _LOGICAL (Read) If false, this routine will issue only error messages and no informational message. [YES]
VARUSE
VARUSE = _LOGICAL (Read) If false, input variances are ignored. [YES]
IN
IN = NDF (Read) The input NDF. Update access is necessary to store the results in the Specdre Extension. The NDF can be a section, as in myndf(5:9,). The spectroscopic axis must be the first non-degenerate axis.
COMP
COMP = _INTEGER (Read and Write) The component number to be used to store the results. This should be either an existing component of type ’moments’ or zero. If it is zero, or if the component specified does not exist, or if it is not of type ’moments’, then a new component will be created in the results structure. In any case, if INFO is true this routine will report which component number has actually been used. [0]
BIAS
BIAS = _REAL (Read) y(x) is not itself used as the probability of x, but y(x)-bias. Thus for a spectrum that was normalised to the continuum level, give BIAS=1.0. A bias of zero is suitable for baseline-corrected spectra. [0]
Examples:
  moments in(-25.:+25.,,) 5
     The NDF is probably three-dimensional. Analysis is restricted
     to pixels between the pixels nearest to x=-25 and +25,
     according to the AXIS(1) information. If there are five or more
     components in the results structure and if the fifth is of type
     ’moments’ then it will be used to store the results. Otherwise
     a new component will be created for storage.
  
Source comments:
     M O M E N T S
  
     For most of the calculated moments each spectrum y(x) is regarded
     as probability distribution of x-values. That is to say that y(x)-b
     is a proportional to the probability of the value x. The results for
     each spectrum are stored in the result structure of the Specdre
     Extension of the input NDF. The component stored is of type ‘moments’.
     The numbers calculated are:
  
     -  minimum pos.: The smallest x found.
     -  maximum pos.: The largest x found.
     -  data minimum: The smallest data minus bias found.
     -  data maximum: The largest data minus bias found.
     -  sum of data: The sum of all values of data minus bias. This
        value is bad if any addend or its variance is bad.
     -  pos. of minimum: The x value where the minimum data value was
        found.
     -  pos. of maximum: The x value where the maximum data value was
        found.
     -  median: The median is currently not calculated. The stored
        value is the bad value.
     -  centroid: The mean x value. Contrary to the sum of data, this
        is calculated using only from data points where data and
        variance are not bad.
     -  variance: The variance of the x values. This is calculated in a
        second pass after the centroid is known. An approximate
        rounding error correction is made according to Press et
        al. 1992, p. 607.
     -  mean abs. dev.: The mean absolute deviation of the x values
        from the centroid. This is calculated in a second pass after
        the centroid is known.
     -  skewness: The skewness gives a measure of the asymmetry of the
        profile of data minus bias versus x. It is positive when the
        profile has a tail towards large x, negative when the profile
        has a wing at small x.
     -  kurtosis: The kurtosis gives a measure of the ‘‘peakedness’’ of
        the profile. It is zero for a Gaussian profile, positive if the
        profile peak is more pronounced, negative if the profile is
        flatter at the centre.
     -  momentum: If x is radial velocity and data minus bias is a
        measure of mass, then this is a measure of the radial momentum
        (inertia). This value is bad if any addend or its variance is
        bad.
     -  energy: If x is radial velocity and data minus bias is a
        measure of mass, then this is a measure of the kinetic
        energy. This value is bad if any addend or its variance is bad.
  
     Note that the higher moments (variance, skewness, kurtosis) are
     rather unreliable unless the spectral features are very strong. For
     further discussion see Press et al. 1992, chapter 14.1.
Notes:
This routine recognises the Specdre Extension v. 0.7.

This routine works in situ and modifies the input file.

References::
Press W.H., Teukolsky S.A., Vetterling W.T., Flannery B.P., 1992, Numerical recipes, Second edition, Cambridge University Press

D.183 MOVIE-Browse through slices of a cube.

Usage:

movie in axis low=? high=?

Description:

This routine takes a three-dimensional NDF and displays its two-dimensional slices sequentially on a grey or colour graphics device.

Parameters:
DIALOG
DIALOG = _CHAR (Read) The dialogue mode. If false (’F’ or ’N’) all frames of the cube will be displayed once in forward order. If true (’T’ or ’Y’) the routine will not display anything initially, but repeatedly ask for a menu option via the MENU parameter. ’G’ for graphic is also permitted, but has the same meaning as ’T’. [’F’]
INFO
INFO = _LOGICAL (Read) If true, informational messages are given. Such as, which frame is currently displayed. [YES]
MODE
MODE = _CHAR (Read) ’Fast’, ’Fill’, or ’Square’ for (i) a tiny but quick display, (ii) to use the whole display area available, (iii) the biggest display with square pixels that is possible in the area available. The mode can be abbreviated to two characters and is case-insensitive. [’Fast’]
IN
IN = NDF (Read) The input NDF. It must be three-dimensional - not counting degenerate axes.
DEVICE
DEVICE = GRAPHICS (Read) The graphics display device. It must be a screen device, not a printer device.
AXIS
AXIS = _INTEGER (Read) The number of the movie axis. Of the three axes in the input cube this is the one not visible in the display. This is the axis to count the frames of the movie. [3]
LOW
LOW = _REAL (Read) The minimum data value from the cube to be displayed. Values less than this are displayed in the same colour.
HIGH
HIGH = _REAL (Read) The maximum data value from the cube to be displayed. Values greater than this are displayed in the same colour.
MENU
MENU = _CHAR (Read) The application will ask repeatedly for the menu option, until ’Q’ is chosen. These options are also available from the keyboard if dialogue is graphic. [’F’] - F: Display each frame in forward order. - B: Display each frame in backward order. - I: Ask for FRAME parameter and display specified frame. - P: Display previous frame. - N: Display next frame. - Q: Quit. - ?: Help.
FRAME
FRAME = _INTEGER (Read) The frame number to be displayed next. Note that frames are counted in NDF pixel indices, i.e. from the NDF’s lower bound to its upper bound.
Source comments:
     The colour table of the display is unaltered so that a previously
     loaded colour table will be used. Bad values will be displayed in
     the display background colour, which in general is distinct from
     the colour for the lowest (or highest) data value.
  
     This routine is quite primitive. It does not use axis data or
     spectroscopic values from the Specdre Extension. Pixels and slices
     in the cube are addressed by their NDF pixel indices, which are
     integer numbers, usually starting at 1.
  
     The routine also does not pay much attention to the precise timing
     of the display. The following list gives activities that the routine
     spends time on and how the user can exert some control over the
     timing.
  
     -  Before a frame can be displayed it must be extracted from the
        cube. The time taken for this depends greatly on whether the
        frame counting axis is the first or last axis. Taking slices is
        fastest if AXIS=3 and can be very slow if AXIS=1, so it may be
        useful to re-arrange the axes of a cube that will be viewed
        often with the same frame-counting axis. Another way to reduce
        the time for taking slices from the cube is to use as small a
        cube as possible: If it is a-priori known that only a certain
        range of frames will be looked at, or that only a certain part
        of all frames is interesting, then the input cube can be given
        as an appropriate subset of the actual disk file.
  
     -  Also before a frame can be displayed it must be converted
        according to the colour capabilities of the display.
  
     -  Each frame needs to be extracted and converted only once and
        can be viewed several times, converted frames are kept in a
        workspace until the routine exits.
  
     -  In the sequence displays each frame is converted and displayed
        before the routine goes on to the next frame.
  
     -  When a specific frame is requested it is extracted, converted
        and displayed (unless it has been viewed before).
  
     -  When the next or previous frame relative to the displayed one
        is requested, it is extracted and converted if necessary. Then
        it is displayed. In anticipation of another request of the same
        type the next or previous frame is extracted and converted
        immediately.
  
     -  Even if a frame has been converted before, it takes some time
        to re-sample it from cube pixels to display pixels. This time
        can be minimised by choosing the fast mode, where a cube pixel
        is only one display pixel.
  
     -  Disruptions occur in the display of a sequence of frames due to
        the unpredictable need for the machine to page memory.
  
     -  Display may be over a network and bandwidth has to be shared
        with other users. This too causes disruptions of frame
        sequences.
  
     In summary, it may be best to
  
     -  put on your spectacles and settle for the fast (and tiny)
        display,
     -  decide which part of the cube is interesting and specify
        only that sub-cube as input,
     -  begin the forward sequence to convert the whole input sub-cube,
     -  have a cup of tea if AXIS=3 and the cube is not small,
     -  use the options ’I’, ’P’, ’N’ to look at individual frames in
        your own time.
  
     It is not possible to write the cube as converted for display.
     Such a cube would be of limited use, since it might contain only
     part of the input cube and since its scaling depends on the colour
     capabilities of the display used.

D.184 MSPLOT-Plots a long spectrum as a series of separate plots

Description:
The MSPLOT command will plot a spectrum on the current hard or soft graphics device, splitting it into a series of individual plots running down the plotting surface.
Parameters:
SPECTRUM
SPECTRUM is the name of the spectrum to be plotted by MSPLOT. It should be a 1-dimensional array.
HARDCOPY
If set, the plot is written to the device defined as the current hardcopy device. Generally, this is a disk file which will then have to explicitly spooled to the actual plotting device. If HARDCOPY is not set, the plot will go to the current softcopy device. The hard and soft copy devices are specifed using the HARD and SOFT commands respectively.
WHOLE
If set, the whole of the spectrum is plotted. Otherwise, the limits plotted are determined by the values of XSTART and XEND, which you will be prompted for if they were not specified in the command string.
SAMESCALE
MSPLOT always autoscales the data - you do not have the chance to specify the range explicitly. However, there is the option of using the same scale for every spctrum plotted, (which you get if you set SAMESCALE), or of having each individual plot autoscaled.
XSTART
The first X value to be plotted, in the units used by the data - angstroms, for example, if the data is wavelength calibrated. XSTART can be set before the start of the data, if necessary. RESET will set XSTART to the first X value in the data.
XEND
The last X value to be plotted, in the units used by the data - angstroms, for example, if the data is wavelength calibrated. XEND can be set after the end of the data, if necessary. RESET will set XEND to the last X value in the data.
NSPECT
The maximum number of spectra to plot on one page. The sensible maximum is depends on the resolution of your output device - a 300dpi laser printer in portrait mode can handle about 10 - after this it starts to get silly.
XRANGE
The spectrum is broken up into individual sections, each covering the same axis range. The amount of axis range covered by a single spectrum is specified by XRANGE. So, for example, to split the plot into 5 sections, XRANGE should be (XEND-XSTART)/5. If XRANGE is such that more than NSPECT plots are needed to cover the spectrum, further sets of plots will be drawn. If the soft plotting device is used, you will be prompted at the end of each page of plots.
LABEL
The label that will appear at the top of the plot.
COLOUR
The colour for the data to be plotted in. The axes are always plotted in white. The colours allowed are Blue, White, Red, Green, Black, Cyan, Magenta, Yellow. Using Black will have the effect of erasing anything where the data is plotted. This only works on the Grinnell.
THICKNESS
Only used for ’build’ or ’hard’ plots. It is used to increase the thickness of the lines plotted in order to increase legibility, particularly on the Versatec. Generally 1 or 3 is reasonable for the Versatec - depending on how well set up it is at the present, and 1 should be used for other devices.
NEXT
Used to pause before a new page.
Source comments:
   M S P L O T
  
   Produces a plot of a spectrum, splitting it up into a number of
   sections, each plotted separately in a series down the plotting
   surface.  The plots are directed to the device defined by the
   user variables ’SOFT’ and ’HARD’, and by the value of the command
   keyword ’HARDCOPY’, so will appear immediately if these specify a
   video device (VT125, Args, etc.).  If a hardcopy device is
   specified, the file for that device will be produced, but MSPLOT
   does not attempt to spool it off for printing.
  
   Command parameters -
  
   SPECTRUM    The data to be plotted.  If this contains X-axis
               information, this will be used.  If not, the X-axis
               will just have to be the numbers from 1 to n.
   XSTART      The x-value at which plotting is to start.
   XEND        The x-value at which plotting is to end.
               (XSTART and XEND are not required if the
               WHOLE keyword is set.)
   LABEL       A label for the plot.
   COLOUR      The colour for the plot, assuming the display device
               supports it.  The axes are always white.
   THICKNESS   The width of the lines used for the plot.  This is
               only used for ’hard’ & ’build’ plots, and should
               really be 1 for anything other than a high-resolution
               device like a Versatec or a laser printer.
  
   Command keywords -
  
   SAMESCALE   The program is to use a the same scale for all the
               plots (i.e. the scale is to be global).  Otherwise the
               plots will be autoscaled individually.  The global
               scale values are determined from the data range of
               the whole of the spectrum to be ploted.
   SHOWZERO    If yes, the autoscale values are constrained to
               include zero.
   WHOLE       The program is to display all of the spectrum.
   HARDCOPY    The plot is to produce a hard copy.
   NEXT        Used to pause before a new page.
  
   User variables -    (">" input, "<" output)
  
   (>) SOFT    Specifies the device and type to be used for soft
               plots.  See the SOFT command for more details.
   (>) HARD    Specifies the device and type to be used for hard
               plots.  See the HARD command for more details.
  
   (Other user variables may be set by the command processor, in
   connection with the parameter values.)
  
                                       KS / AAO 15th Dec 1988

D.185 NCSET-Set a region of a spectrum to a constant

Description:
NCSET sets a specified region in a spectrum to a constant value. This is a non-interactive version of CSET, which allows the region to be specified precisely in terms of the X-values of the data.
Parameters:
SPECTRUM
The name of the spectrum to be modified by NCSET. It should be a 1-dimensional array.
XSTART
The first X value to be set to the constant, in units used by the data - angstroms, for example, if the data is wavelength calibrated. RESET will set XSTART to the first X value in the data.
XEND
The last X value to be set to the constant, in units used by the data - angstroms, for example, if the data is wavelength calibrated. RESET will set XEND to the last X value in the data.
VALUE
The selected region of the spectrum (from XSTART to XEND) will be set to VALUE.
OUTPUT
NCSET generates an output file that is essentially the data from the displayed spectrum, with one regions set to the constant value. OUTPUT is the name of the resulting spectrum.
See also:
FIGARO: CSET, ICSET, TIPPEX.
KAPPA: CHPIX, FILLBAD, SEGMENT, NOMAGIC, RIFT, SETMAGIC, ZAPLIN.
Source comments:
   N C S E T
  
   Figaro function to set a selected region of a spectrum to a
   constant value.  This is a non-interactive version of CSET,
   and has the possible advantage of allowing the region to be
   specified precisely in terms of the X values of the data.
  
   Command parameters -
  
   SPECTRUM    (Character) The spectrum to be modified.
   XSTART      (Numeric) The X-value of the start of the region.
   XEND        (Numeric) The X-value of the end of the region.
   VALUE       (Numeric) The value to use for the selected region.
   OUTPUT      (Character) The name of the output file to
               be created.  If this is the same as the input
               spectrum, the data will be modified in situ.
  
   Command keywords - None
  
   User variables used -  None
  
                                            KS / CIT 27th March 1985

D.186 OFFDIST-Applies an offset to an SDIST fit

Description:
OFFDIST reads the s-distortion fit file produced by SDIST and writes a modified version in which a specified offset in Y has been added to all the fits. This allows the same distortion analysis to be applied to data which has the same shape but is physically displaced from the data originally analysed.
Parameters:
INFILE
The name of the distortion file to which an offset is to be added. This will have been produced by SDIST, and so will normally be called SDIST.DAT.
OFFSET
The offset in Y to be applied to the data is specified by OFFSET. A positive value moves the fits up (in the sense that it will move the lines displayed by ODIST up the screen of an image display). OFFSET is a value in pixels.
OUTFILE
The name of the distortion file to be created with the offset value applied. A new file is always created, even if the names supplied for OUTFILE and INFILE are the same (a new version is created). Most applications that use these files expect them to be called SDIST.DAT, so if you use anything else some creative RENAMEing may be needed.
Source comments:
   O F F D I S T
  
   Modifies the output s-distortion file produced by SDIST
   to add an offset in Y to the fitted positions.
  
   Command parameters -
  
   INFILE    (Character) The name of the distortion file to
             be modified.
   OFFSET    (Numeric) The offset in Y to be added to the fits.
   OUTFILE   (Character) The name of the resulting modified file.
             Note that many of the applications that use these
             files assume explicitly that they are called SDIST.DAT.
             If OUTFILE is the same as INFILE, a new version of the
             file is produced.
  
   Command keywords - None
  
   Input and output files -
  
   SDIST.DAT contains the results of the fit(s), as written by
             SDIST, in a format treated as follows -
  
             3 header lines, all beginning with ’*’
             One line giving the number of spectra traced, in the
             format 20X,I5.
             Then, for each spectrum traced, one record giving
             the spectrum number, and the leftmost and rightmost
             pixels covered by the trace, then 1 record including
             the average Y value in the spectrum, in format 16X,F13.7,
             which is followed by 4 records giving the 11
             polynomial coefficients for the fit.  Note that this
             program only assumes the number of records for each
             spectrum, and the position of the average Y value.  It
             carefully only modifies the Y value fields, leaving all
             the rest unchanged.

D.187 OPTEXTRACT-Extracts a long-slit spectrum using Horne’s algorithm

Description:
OPTEXTRACT performs optimal extraction of a star spectrum from a 2-D long slit spectrum using the algorithm of Horne 1986 (PASP 98,609). A spatial profile image should have previously been determined using the PROFILE command, and the 2-D spectrum to be extracted must be sky subtracted (e.g. using the POLYSKY command).

The input IMAGE array may have error and quality information. An error or variance array is required to perform true optimal extraction as the points should be weighted using the errors on each point as well as the spatial profile information. If an error array is not present (or not all the errors in a column are known) the extraction is performed assuming equal errors on every point in the column. The output spectrum has an error array only if the input image has an error array. The WEIGHT keyword may be set to NO to suppress error weighting even when errors are available.

Parameters:
IMAGE
The name of a 2-D long slit spectrum.
PROFILE
The name of the normalized spatial profile image for the object to be extracted. This can be obtained using the PROFILE command.
SPECTRUM
The name of the resulting single spectrum.
WEIGHT
If WEIGHT is set, the error or variance information associated with the data is used to weight the data. Each point is weighted as 1/variance. If not set, or if no error information is available all points are given equal weight.
Source comments:
   O P T E X T R A C T
  
   OPTEXTRACT performs optimal extraction of a star spectrum from a
   2-D long slit spectrum using the algorithm of Horne 1986 (PASP 98,609).
   A spatial profile image should have previously been determined using
   the PROFILE command, and the 2-D spectrum to be extracted must be
   sky subtracted (e.g. using the POLYSKY command).
  
   The input IMAGE array may have error and quality information. An error
   or variance array is required to perform true optimal extraction as
   the points should be weighted using the errors on each point as well
   as the spatial profile information. If an error array is not present (or
   not all the errors in a column are known) the extraction is performed
   assuming equal errors on every point in the column. The output spectrum
   has an error array only if the input image has an error array. The
   WEIGHT keyword may be set to NO to suppress error weighting even
   when errors are available.
  
   The spatial profile array used by OPTEXTRACT must satisfy the following
   requirements.
    (i)  Its quality array must specify a window (of arbitrary shape)
         in which the extraction will be performed. Points inside the window
         must have zero quality values, other points must have non zero
         quality values
    (ii) The data must be normalized. i.e. The sum along each column
         must be one.
    (iii) The data values may not be negative.
  
   Command parameters -
  
   ’IMAGE’    The name of the input 2-D file. This should be a
              sky subtracted 2-D spectrum from which the spectrum
              of an object is to be extracted. It may have error and
              quality arrays
   ’PROFILE’  The normalized spatial profile image used to perform the
              extraction. The quality array should specify a window
              in which the profile is determined. The data within
              this window is the spatial profile to be used.
   ’SPECTRUM’ The name of the resulting 1-D spectrum. If the input image
              has errors, so will the output spectrum. The quality
              will be set to bad only if there is no data in the
              relevant column.
  
   Command keywords -
  
   ’WEIGHT’    Use the error or variance array to weight the
               pixels during extraction.
  
  
                                   JAB / JAC 8th Feb 1991

D.188 OVERPF-Overlays a FINDSP fit on another image

Description:
Overlays the Polynominal Fits on an image. Displaying a zoomed part of the image is possible. To be used with FINDSP and POLEXT.
Parameters:
IMAGE
The fibre frame - one with distorted fibre spectra approximately equally spaced.
BLACK
The data value below which the image display is to have the background colour. The display is scaled linearly between the data values specified as BLACK and WHITE.
WHITE
The data value above which the image display is to have the foreground colour. The display is scaled linearly between the data values specified as BLACK and WHITE.
PFILE
The file containing the polynominal fits. If no extension is specified, ‘.pol’ is used.
YSTART
First Y value to be displayed.
YEND
Last Y value to be displayed.
XSTART
First X value to be displayed.
XEND
Last X value to be displayed.
EXTWID
The input may be integer or real. An integer input causes edges of pixels included to be drawn, whereas real input causes trams lines of width EXTWID to be drawn surrounding each polynomial fit.
REPEAT
Used to ask whether a display with different parameters should be made.
Authors:
jrl: John Lucey (AAO, Durham)

hme: Horst Meyerdierks (UoE, Starlink)

D.189 PEAK-Determines position of highest peak in a spectrum

Description:
Returns the position and width of the highest peak in a data array. This is intended for the analysis of cross-correlation results.
Parameters:
SPECTRUM
The name of a file containing a 1-D data array, in which PEAK will determine the shift relative to the first element, and the width, of the highest peak.
Source comments:
   P E A K
  
   Determines the position and width of the largest peak in a data
   array.  The data is treated as circular - i.e. the first element is
   regarded as adjacent to the last element.  This routine is
   intended for use analysing the results of cross-correlations,
   and returns the position in terms of a shift relative to the
   first element.  The algorithm used is a two step one: first a
   parabolic fit to the five points closest to the peak gives a
   value for the shift and width; the shift is then refined by
   convolution with the derivative of a gaussian.
  
   Command parameters -
  
   SPECTRUM (Character) The name of the data to to be analysed.
  
   User variables -
  
   (<) SHIFT   (Numeric) The shift of the peak relative to the
               center of the first element, in pixels.
   (<) WIDTH   (Numeric) The width of the peak, again in pixels.
  
                                               KS / AAO 29th Sept 1986

D.190 POLEXT-Extract fibre spectra from an image after a FINDSP analysis

Description:
POLEXT extracts a set of fibre spectra from a fibre image, given a file (usually produced by FINDSP) that gives the positions and shapes of the fibre spectra in terms of a set of fitted polynomials
Parameters:
IMAGE
The name of the image that contains the fibre spectra to be extracted.
PFILE
The name of a file (usually produced by FINDSP) that contains the polynomials fitted to the spectra to be extracted. If no extension is specified, .POL is assumed.
DFILE
The name of a file that lists any dud fibres - fibres to be ignored in the extraction process. If no extension is specified, .DUD is assumed. If there are no dud fibres, DFILE can be specified as blank - which may mean specifying it as " " (a blank within quotes).
EXTWIDTH
The polynomial file is used to determine the positions of the centres of all the fibre spectra. EXTWIDTH is used to specify the width of the spectra, and is specified in pixels. Note that this does not have to be an integer.
OUTPUT
The name of the resulting fibre image. Each cross-section of OUTPUT is a single exctracted fibre spectrum.
Source comments:
   P O L E X T
  
   Given an image containing Fibre data, and a polynomial file
   (produced, probably, by FINDSP) that gives the positions of the
   centres of the spectra, POLEXT extracts the spectra to produce
   a new image in which each cross-section is one of the fibre
   spectra.
  
   Command parameters -
  
   IMAGE     (Character) The name of the image containing the
             distorted fibre spectra.
   PFILE     (Character) The name of the polynomial file that
             describes the fibre positions.  Default extension
             is .POL
   DFILE     (Character) The name of an optional dud fibre file
             that lists the numbers of any dud fibres.  If blank,
             no file is used.  Default extension is .DUD.  If the
             file cannot be opened, this is not regarded as a
             fatal error, so it is possible to specify a
             non-existent file, such as ’NONE’
   EXTWIDTH  (Real) The width of the spectra in pixels.
   OUTPUT    (Character) The name of the resulting image.
  
   Command keywords - None
  
   Original version by John Lucey (JRL), AAO

D.191 POLYSKY-Fits and subtracts sky from a long-slit spectrum

Description:
Subtract sky from a long slit spectrum by fitting a polynomial in the spatial direction.
Parameters:
IMAGE
The name of a 2-D file containing a long-slit spectrum with the spectra being along the rows (i.e. the X axis).
YS1
The first Y value to be used for the first sky region.
YE1
The last Y value to be used for the first sky region.
YS2
The first Y value to be used for the second sky region.
YE2
The last Y value to be used for the second sky region.
DEGREE
Degree of polynomial to be fitted.
NREJECT
Number of points to reject from each column. The NREJECT points which deviate most from the mean will not be included in the polynomial fit.
OUTPUT
The name of the resulting sky subtracted data.
WEIGHT
If set, the error or variance information associated with the data is used to weight the fit. Each point is weighted as 1/variance. If not set, or if no error information is available all points are given equal weight.
Source comments:
   P O L Y S K Y
  
   POLYSKY is used to subtract sky from a long slit spectrum by
   polynomial fitting in the spatial direction to two regions of
   sky on either side of an object of interest.
  
   Only the region of the image between the outer edges of the two sky
   fields is sky subtracted. Data outside this region is unchanged.
   This enables POLYSKY to be used repeatedly to remove sky from more
   than one object spectrum on an image.
  
   The input image may optionally have associated error and quality
   information. If quality is present points with bad quality will
   be omitted from the fit. If error or variance is present the values
   may be used to weight the fit.
  
   If a non zero value for NREJECT is specified this number of points
   will be omitted from the fit to each column. The points chosen for
   omission will be those which deviate most from the mean for the column.
  
   Command parameters -
  
   ’IMAGE’    The name of the input file.
   ’YS1’      Starting Y value to use for first sky field
   ’YE1’      Ending Y value to use for first sky field
   ’YS2’      Starting Y value to use for first sky field
   ’YE2’      Ending Y value to use for first sky field
   ’DEGREE’   Degree of the polynomial fit
   ’NREJECT’  Number of points to reject in each fit
   ’OUTPUT’   The name of the output subtracted file.
  
   Command keywords -
  
   ’WEIGHT’   Use the error or variance array to weight the
              polynomial fit.
  
                                   JAB / JAC 7th Feb 1991

D.192 PROFILE-Profiles a long-slit spectrum for use by OPTEXTRACT

Description:
Determine spatial profile image from a 2-D spectrum using the algorithm of Horne, 1986 (PASP 98, 609).
Parameters:
IMAGE
The name of a 2-D file.
YSTART
Specifies the first Y value to be used.
YEND
Specifies the last Y value to be used.
DEGREE
Degree of polynomial to be fitted.
NREJECT
Number of points to reject in each fit.
PROFILE
The name of the resulting profile data.
RESIDUAL
The name of an image containing the residuals of the fit.
WEIGHT
If set, the error or variance information associated with the data is used to weight the fit. Each point is weighted as 1/variance. If not set, or if no error information is available all points are given equal weight.
Source comments:
   P R O F I L E
  
   PROFILE determines a spatial profile image for subsequent use
   by the optimum extraction program OPTEXTRACT. PROFILE uses the
   technique described by Horne, 1986 (PASP 98, 609). An initial
   (noisy) estimate of the spatial profile is made by dividing the
   values along each column by the sum over that column. A smoothed
   version of this profile is then constructed by fitting polynomials
   along each row to account for smooth variations of the spatial profile
   with wavelength. The technique ensures that the profile is normalized
   (sums to one along each column) and is everywhere positive. Rejection
   of the NREJECT worst points in each fit allows the method to be
   insensitive to cosmic ray hits or other bad data points.
  
   Error and quality information may be present on the input image. Points
   with bad quality will be ignored in the fit, and the errors may
   be used to weight the fit.
  
   An image containing the residuals of the fit to the profile is
   generated and may be used to judge the quality of the fit.
  
   The Horne algorithm is appropriate for the case where there is only
   a slight tilt or distortion on the spectrum. Where the tilt or
   distortion is more extreme, such as in a cross-dispersed echelle
   spectrum, an algorithm such as that of Marsh, 1989 (PASP 101, 1032)
   should be used to generate the spatial profile.
  
   Command parameters -
  
   ’IMAGE’     The name of the input file.
   ’YSTART’    Starting Y value to use.
   ’YEND’      Ending Y value to use.
   ’DEGREE’    Degree of polynomial to use in fit.
   ’NREJECT’   Number of points to reject in each fit.
   ’PROFILE’   The name of the output file containing the normalized
                  spatial profile.
   ’RESIDUAL’  The name of the data file containing the residuals of
                  the fit.
  
   Command keywords -
  
   ’WEIGHT’    Use the error or variance array to weight the
               polynomial fit.
  
  
                                   JAB / JAC 8th Feb 1991

D.193 Q2BAD-Converts a datafile’s quality into bad values

Description:
The routine converts an datafiles quality information into bad values. There is no QUALITY structure in the output. This is a temporary measure required whilst Figaro cannot handle datafiles with both a QUALITY structure and flagged values.
Parameters:
IN
The input datafile.
OUT
The output datafile.
See also:
KAPPA: SETBB.
Authors:
JM: Jo Murray (STARLINK)

HME: Horst Meyerdierks (UoE, Starlink)

D.194 QUAL2FLAG-Converts a quality array into ‘flagged’ values

Description:
QUAL2FLAG turns a Figaro file that holds data quality information in a quality array (or as combination of a quality array with flagged data values) into one that holds the data quality information solely in the form of flagged data values. Generally, Figaro programs prefer to work with quality arrays - which allow the original data values to be kept available even though the data element is indicated as being bad through the quality array - but there are some programs that may prefer to work with flagged data values and these will run more efficiently on data that is actually held in that form on disk. Having both forms of data quality information in a file can be confusing and QUAL2FLAG can tidy things up.
Parameters:
INPUT
The name of a Figaro format file that contains an associated quality array. It may also have some data elements flagged using ’flagged’ (or ’magic’) data values. Whatever it contains, QUAL2FLAG will process it so that the resulting file does not have a quality array, and all quality information will be held in the form of flagged data values in the main data array.
OUTPUT
The name of the resulting file. This can be the same as the input file, in which case all changes are made in situ. The resulting file will have all its data quality information held as flagged data values in its main array, and will not have a quality array.
Source comments:
   Q U A L 2 F L A G
  
   Description:
      This is a Figaro program that removes the quality array from a
      Figaro data file. If the quality array indicated that any of
      the data array elements were bad, then those elements of the
      main data array are set to the ’flagged’ or ’magic’ value. Note
      that this replaces the previous value in the data array, which is
      therefore left - so this process can remove information from the
      file, which is why Figaro tends to prefer the use of quality
      arrays rather than flagged data arrays.
  
   Command parameters:
  
      INPUT  (Character) The name of the structure containing the data.
  
      OUTPUT (Character) The name of the result of the operation.  This
             can be the same as for INPUT.  If not, a new structure
             is created, with everything but the data a direct
             copy of the input.
  
      12th Feb 1995  KS / AAO.  Original version.

D.195 R2CMPLX-Creates a complex data structure from a real data array

Usage:
r2cmplx rdata cdata
Description:
Creates a complex data structure from a real data structure. RCMPLX sets the imaginary part of the complex data to zero. It can be set subsequently using the I2CMPLX command.

The output data follows the input in structure, except that the data array is of type DOUBLE. A zero-filled imaginary data array is also created. Any axis structures are retained.

Parameters:
RDATA
RDATA is the name of an existing file that contains a data array that is to become the real part of the complex data structure that is created by R2CMPLX.
CDATA
CDATA is the name of the complex data structure to be created. Its real part will come from the structure specified as RDATA, and its imaginary part will be set to zero. If CDATA is the same as RDATA, RDATA will be transformed into a complex structure; otherwise, a new file is created.
Authors:
ks: Keith Shortridge (AAO)

D.196 RCGS2-Reads UKIRT CGS2 spectrum (also UKT9 and UKT6 CVF)

Description:
Reads a UKIRT CGS2 spectrum out of its original container file and create a Figaro spectrum from it. (Also works for UKT9 and UKT6 CVF spectra).
Parameters:
FILE
The name of the container file to read in.
OBS
The observation number in the container file.
TWOD
If set, a 2-dimensional file is created giving all scans. Otherwise a indivdual scan can be specified or the coadded data used in a 1-D file.
SCAN
The scan number in the observation.
OUTPUT
The name of the Figaro file to be created from the CGS2 Data.
Source comments:
   R C G S 2
  
   Reads a UKIRT CGS2 spectrum out of its original container file
   and create a Figaro spectrum from it. (Also works for UKT9
   and UKT6 CVF spectra).
  
   Command parameters -
  
   FILE    (Character) The name of the container file
   OBS     (Numeric) The observation number to be read from
           the container file.
   SCAN    (Numeric) The scan number to be read from the observation
           (Only used if TWOD is not set) use zero to read the coadded data.
   OUTPUT  (Character) The name of the Figaro file to be created.
  
   Command keywords -
  
   TWOD    If set create a 2-D array of wavelength by scan
           number.
  
   User variables used - None
  
                                    JAB / JAC  25th Feb 1990

D.197 RDFITS-Read file in AAO de facto ’Disk FITS’ format

Description:
RDFITS reads a disk file containing data in a ’Disk FITS’ format and creates a Figaro data file from it. RDFITS was originally intended to handle the AAO ’de facto disk FITS’ format, but the addition of the SWAP keyword and code to determine the disk format in use has made it rather more general. Note that RDFITS with SWAP set to NO can read files written in the ’JT disk FITS’ format handled by RJT.
Parameters:
FILE
The name of a disk file containing an image in ’Disk FITS’ format - i.e. 2880 byte records looking exactly the same as the records in a FITS tape.
IMAGE
The name of the resulting Figaro image. Note that this will contain the image data itself and the ’FITS’ header information in a .FITS structure. The conventions used by the header information - e.g. is RA in hours, minutes and seconds or in fractional minutes? - may not be those used by normal Figaro routines, so be wary of just copying them into any standard observation structure.
SWAP
FITS data is by definition stored on tape in IBM byte order which is the reverse of internal storage on a VAX. SWAP = YES for de facto ’disk FITS’ files such as that from AAO and written by the Figaro function WDFITS. Some other ’disk FITS’ formats such as JT’s may require SWAP=NO.
FLOAT
The default setting for FLOAT is YES, and this causes FITS to generate an output data structure with a main data array whose type will be FLOAT. This is the recommended way to create the file. If the data was originally written with BITPIX=16, then disk space can be saved by setting FLOAT=NO. FLOAT=NO will be overidden if the FITS header specifies BSCALE and BZERO values other than 1.0 and 0.0 respectively, although the special case of FLOAT=NO combined with BSCALE=1.0 BZERO=32768.0, BITPIX=16 is trapped and produces a main data array of unsigned 16bit integers (some FITS writers, notably WDFITS, use this as an efficient way of writing 16bit unsigned integer data).
See also:
FIGARO: WDFITS, FITSKEYS.
KAPPA: FITSDIN, FITSIN, FITSHEAD, FITSIMP, FITSLIST.
Source comments:
   R D F I T S
  
   Figaro routine to read file in a ’Disk FITS’ format,
   creating a Figaro data structure file that contains all
   the information from the disk file (although not necessarily in
   an ideal form, since the program cannot guess at the meaning
   of all the various FITS keywords).  For more details, see the
   listing for FIG_FITIN.
  
   Command parameters -
  
   FILE       (Character) The name of the ’Disk Fits’ file.
  
   IMAGE      (Character) The name of the Figaro output file.
  
   Command keywords -
  
   SWAP       Swap bytes.  This should be set to YES if the data
              have been stored in the proper FITS format (IBM-style)
              and the program is running on a non-IBM byte order
              machine such as a VAX.  On a VAX, you should use:
              SWAP=YES for AAO de facto ’disk FITS’.
              SWAP=NO for WJT ’disk FITS’.
  
   FLOAT      Convert the data to floating point numbers. This is
              normally what will be required, although note that only
              single precision is supported.  If FLOAT=NO is specified,
              FITS will still convert to floating point if the data have
              scaling and offset factors that are not 1.0 and 0.0
              respectively.  The case where FLOAT=NO, BITPIX=16,
              BSCALE=1.0, BZERO=32768 is treated as a special case and
              will generate an array of unsigned 16 bit integers.
              FLOAT=NO is usually only useful in this special case and
              in the case where BSCALE=1.0, BZERO=0.0, BITPIX=16, where
              it will create a smaller data file with no loss of precision.
  
   User Variables used -   None
  
   Note:  Most of the various ’disk FITS’ formats differ only in
          whether or not they swap bytes, and in the details of the
          way the disk data is organised in records.  For example,
          a VAX VMS file may have a ’FIXED’, ’VARIABLE’, or ’SEGMENTED’
          format, whereas UNIX files are generally simpler.  Also on
          a machine that has a record-based file structure (like a VAX)
          the record lengths may or may not be the 2880 bytes that would
          match a FITS tape. This program determines the disk format
          (fixed, variable,segmented) and record length for itself, and
          uses the SWAP keyword to indicate whether the data bytes are to
          be treated as swapped or not.  It should therefore be able to
          handle most of the available ’disk FITS’ formats.
  
                                           KS / AAO 17th June 1986

D.198 RDIPSO-Read file in DIPSO/IUEDR/SPECTRUM format

Description:
Reads a file in DIPSO/IUEDR format and creates a Figaro file from the data in it. The file can have been written in any of what IUEDR calls SPECTRUM type 0, type 1 or type 2 format.
Parameters:
FILE
The name of the DIPSO file to be read in. If no extension is specified, .DAT will be used.
CODE
There are three SPECTRUM formats used by DIPSO, and RDIPSO can handle any of them. Type 0 is unformatted, and is the most compact and fastest to use, but cannot be read as a text file. Type 1 is a fixed format text file, and type 2 is a free-format text file.
SPECTRUM
The name of the Figaro file to be created from the data in the DIPSO format file.
Source comments:
   R D I P S O
  
   Reads a file in DIPSO/IUEDR format and creates a Figaro file from
   the data in it.  The file can have been written in any of what IUEDR
   calls SPECTRUM type 0, type 1 or type 2 format.
  
   Command parameters -
  
   FILE      (Character) The name of the DIPSO format file to be read.
   CODE      (Numeric) The SPECTRUM type code for the format (0,1 or 2).
   SPECTRUM  (Character) The name of the Figaro file to be created.
  
   Command keywords -  None
                                             KS / AAO 13th Oct 1986

D.199 REMBAD-Removes pixels that have been flagged as bad from data

Description:
Remove from a spectrum points which are flagged as bad or shown as bad in the quality array. The main purpose of this command is to allow such spectra to be correctly processed by FIGARO commands which do not support data quality.
Parameters:
SPECTRUM
Spectrum containing bad points.
OUTPUT
Name of resulting spectrum.
See also:
FIGARO: BCLEAN, CLEAN, COSREJ, MEDFILT, MEDSKY, TIPPEX.
KAPPA: CHPIX, FILLBAD, GLITCH, MEDIAN, ZAPLIN.
Source comments:
   R E M B A D
  
   Remove from a spectrum points which are flagged as bad or
   shown as bad in the quality array. The main purpose of this
   command is to allow such spectra to be correctly processed by
   FIGARO commands which do not support data quality.
  
   Command parameters -
  
   SPECTRUM    The spectrum from which bad points will be removed.
   OUTPUT      The resulting spectrum.
  
   Command keywords -
                                       JAB/ JAC  16th Dec 1990

D.200 RENOBJ-Change the name or location of an object within an HDS file

Usage:
renobj source=? destin=?
Description:
This routine either renames an HDS object in place or moves it to a different place in the structure hierarchy of the same file. It is not possible to reshape objects, i.e. to change their dimensions or dimensionality.
Parameters:
SOURCE
The existing HDS object to be renamed. Specify beginning with directory and file name in the syntax of the operating system, followed by the dot-separated structure hierarchy. Elements of structure arrays are specified in ordinary brackets (). An array element cannot be renamed.
DESTIN
The new name for the HDS object. Specify beginning with directory and file name in the syntax of the operating system, followed by the dot-separated structure hierarchy. Elements of structure arrays are specified in ordinary brackets (). The destination cannot be an array element. The destination object must not exist beforehand.
Examples:
   1.  renobj source=file.MORE.FIGARO.OBS.TIME destin=file.MORE.FIGARO.TIME
     This moves the time specification from .MORE.FIGARO.OBS one
     level up into .MORE.FIGARO.
  
   2.  renobj source=file.ERRORS destin=file.VARIANCE
     This renames the object ERRORS into VARIANCE, but the location
     remains the same. (The contents remain the same anyway.)
  
See also:
FIGARO: CREOBJ, COPOBJ, DELOBJ, SETOBJ.
KAPPA: ERASE.
Authors:
KS: Keith Shortridge (AAO)

HME: Horst Meyerdierks (UoE, Starlink)

D.201 RESAMP-Re-sample and average several spectra (was Specdre RESAMPLE).

Usage:

resamp mode inlist out start step end

Description:

(This command was called RESAMPLE in Specdre, but because of a command of the same name in Figaro, it has been renamed.)

Depending on the operation mode this routine either

- takes a list of one-dimensional NDFs as input, re-samples them to a common linear grid of axis values, and averages them into a single one-dimensional NDF, or

- takes a single N-dimensional NDF as input and re-samples each row into a new row of a similar output NDF; re-sampling is along the first axis, all further axes are retained.

Parameters:
MODE
MODE = _CHAR (Read) The operating mode. This can be abbreviated to one character, is case-insensitive and must be one of the following:

- ’SPECTRA’: Average several 1-D input NDFs into a single 1-D output NDF. Re-sample before averaging.

- ’CUBE’: Accept only one - but N-D - input NDF. Re-sample each row (1-D subset extending along first axis) separately.

Note that a single spectrum could be handled by both modes; it is more effective to treat it as a 1-D cube than as an N=1 average. [’Cube’]

INFO
INFO = _LOGICAL (Read) If false, informational and warning messages are suppressed. [YES]
VARUSE
VARUSE = _LOGICAL (Read) If true, input NDFs without variance information are skipped. If false, variance information in the input is ignored. [YES]
INLIST
INLIST = LITERAL (Read) The group of input NDFs. In a complicated case this could be something like
        M_51(25:35,-23.0,-24.0),M101,^LISTFILE.LIS

This NDF group specification consists of

  • one identified NDF from which a subset is to be taken,
  • one identified NDF,
  • an indirection to an ASCII file containing more NDF group specifications. That file may have comment lines and in-line comments, which are recognised as beginning with a hash (#).
OUT
OUT = NDF (Read) The output NDF.
START
START = _DOUBLE (Read) The first pixel position in the output NDF. The prompt value is derived from the first valid input NDF.
STEP
STEP = _DOUBLE (Read) The pixel position increment in the output NDF. The prompt value is derived as the average increment in the first valid input NDF.
END
END = _DOUBLE (Read) The last pixel position in the output NDF. The prompt value is derived from the first valid input NDF.
Source comments:
     R E S A M P
  
     The re-sampling creates an interdependence between pixels of the
     output NDF. Only limited information on this interdependence is
     stored in the output and ignored by most applications. Data input
     to this routine is assumed to have no such interdependence.
  
     The re-sampling algorithm is reintegration (Meyerdierks, 1992a)
     and it is applied to each input NDF separately. Any re-sampled data
     value is a weighted sum of the input values. The weights are the
     normalised overlaps between the output and input pixels. The
     re-sampled spectra are averaged pixel by pixel.
  
     If input variances are to be ignored it is assumed that the
     variance is a global constant, i.e. equal in all pixels of all
     input NDFs. The re-sampling may still result in different weights
     for different pixels. In the averaging process the global input
     variance is calculated and reported. The output variance will be
     derived on a pixel-by-pixel basis from the data scatter in the
     averaging process.
  
     In any input NDF, this routine recognises axis centres (pixel
     positions), pixel widths, data values, and data variances. (This
     routine also recognises the Specdre Extension and will use it
     where relevant.) Any other information is propagated from the
     first input NDF.
  
     Labels and units are checked for consistency, but only a warning
     is given. In interpreting the data all labels and units are
     assumed to be the same as in the first input NDF.
  
     All input NDFs must have a variance component (unless VARUSE is
     set false). NDFs without variances are ignored. A warning to that
     effect is issued. If VARUSE is set false, input NDFs may or may
     not have variances, such information will be ignored at any rate.
  
     The output NDF is based primarily on the first input NDF. There
     will be no pixel widths, since the pixel positions are linear and
     the pixels contiguous. The pixel positions, data values, and
     data variances will be affected by the re-sampling process. The
     output Specdre Extension will be based on the first input NDF or
     will be created.
  
     The vector of row sums of the covariance matrix (Meyerdierks,
     1992a/b) will be created in the Specdre Extension. This is an NDF
     structure with only a data component of the same shape as the main
     data array. If such a structure is found in one of the input
     NDFs, a warning is issued but such information is ignored.
Examples:
  resample spectra ^inlist out 3.5 0.0254902 10.0
     The names of input NDFs are read from an ASCII list file called
     INLIST. The result will be stored in OUT which has 256
     pixels covering the coordinates from 3.5 to 10.0
  
  resample spectra ^inlist out varuse=false accept
     The names of input NDFs are read from an ASCII list file called
     INLIST. The input NDFs either have no variance, or their
     variance information is to be ignored. The output will be in
     OUT. The start and end pixel positions for OUT are the same as
     in the first input NDF. OUT also has the same number of pixels.
     The pixel spacings are constant in OUT while they may not be in
     the input NDF.
  
  resample cube ^inlist out 3.5 0.0254902 10.0
     INLIST contains only one NDF probably with more than one
     dimension. OUT will have the same dimensions except the first,
     which is the re-sampled one.
Notes:
The axis normalisation flag is ignored.

This routine recognises the Specdre Extension v. 0.7.

Pitfalls:
This routine uses pixel widths. If there is no width array in the input NDF, the widths default as described in SUN/33. This may have undesired effects on re-sampling spectra that cover several non-adjacent coordinate ranges and where the missing ranges are not covered by bad pixels. Such spectra have highly non-linear pixel positions and the default pixel widths will not be as desired. To illustrate this consider the following spectrum with four pixels, the intended extents of the pixels and the defaulted extents:

x x x x

|1111111|2222222| |3333333|4444444|

|1111111| |333333333333333333333333333333333| |222222222222222222222222222222222| |4444444|

Since this routine uses the overlap between input and output pixels as weights for re-sampling, non-bad pixels next to such a gap in data will affect too many output pixels with too much weight. Users should be aware that spectra as illustrated here are somewhat pathologic and that they should be given an explicit width array.

The routine accesses one input NDF at a time and needs not hold all input NDFs at the same time. However, The routine needs temporary workspace. If KMAX is the number of pixels in an input NDF and LMAX the number of output pixels, the routine needs - one vector of length LMAX, - one matrix of size KMAX by LMAX, - two matrices of size LMAX by LMAX.

These workspaces are usually of type _REAL. All (!) are of type _DOUBLE if the first valid input NDF has type _DOUBLE for either of the following: - pixel position, - pixel width, - data value, - data variance.

In addition one integer vector of length LMAX is needed.

There is an oddity about this routine if only one input NDF is used and its variance array is used and some or all variance values are zero. In this case the output will formally still be an average of input NDFs using 1/variance as weights. Data with zero variance cannot be weighted and are regarded as bad. If this is a problem, users can set VARUSE false to ignore all the input variances. (Note that zero variances always cause that pixel to be ignored by this routine. But where it really calculates an average of two or more spectra, this is considered proper procedure.)

Timing:
The time used by this routine is about proportional to the number of input NDFs. It is proportional to the square of the number of output pixels. Timing can be optimized, if the input NDFs cover about the same coordinate range as the output NDF rather than include a lot of data irrelevant for the output.
References:
Meyerdierks, H., 1992a, Covariance in resampling and model fitting, Starlink, Spectroscopy Special Interest Group

Meyerdierks, H., 1992b, Fitting resampled spectra, in P.J. Grosbol, R.C.E. de Ruijsscher (eds), 4th ESO/ST-ECF Data Analysis Workshop, Garching, 13 - 14 May 1992, ESO Conference and Workshop Proceedings No. 41, Garching bei Muenchen, 1992

D.202 RESAMPLE-Rebin an image to different dimensions and/or orientation

Description:
Given an input image, RESAMPLE creates an output image which is the result of rotating/shifting/shearing/scaling the input image. The transformation between the input and output pixel coordinates can be specified by giving a rotation ANGLE and scale factors to be applied to the X and Y axes (XMAG, YMAG), or by explicitly specifying the transformation matrix (using TRANSFORM). The later option allows shears to be specified. The first option automatically selects the output image shift and size so that the entire input image is present. The interpolation used in setting the values of the output pixels can be either ’nearest pixel’, ’linear’, or ’constant noise’.
Parameters:
IMAGE
The name of the input image.
TRANSFORM
Allows you to specify the transformation between the input and output pixel coordinates. You can enter a 6-element array, where the elements have the following meanings:

XIN = C(1)+C(2)*XOUT+C(3)*YOUT YIN = C(4)+C(5)*XOUT+C(6)*YOUT

You can invert the transformation by using the INVERT keyword. If you don’t wish to enter TRANSFORM, respond with a <CR> and you will be prompted for XMAG, YMAG, and ROTATE instead.

XMAG
The scale factor to be applied to the X coordinate. For example, if you want the input image blown up by a factor of two in the X direction, specify XMAG=2. The scaling is done before any rotation.
YMAG
The scale factor to be applied to the Y coordinate. For example, if you want the input image blown up by a factor of two in the Y direction, specify YMAG=2. The scaling is done before any rotation.
ANGLE
The number of degrees you wish to rotate the input image. The angle is measured counterclockwise. Rotation is performed after any scaling you have requested.
INVERT
Allows you to invert the transformation that you have specified.
METHOD
Allows you to chose the interpolation method used when selecting the output pixel values. The three choices are:

1 - Nearest pixel. No interpolation is performed, the value of the nearest pixel is used. This is fast. 2 - Linear. A linear interpolation is performed using the values of the 4 nearest pixels. 3 - Constant noise. Uses the 9 nearest pixels in some mysterious way.

XSIZE
Gives the number of pixels in the X-direction for the output image. The default value is that required to fit the input image after transformation.
YSIZE
Gives the number of pixels in the Y-direction for the output image. The default value is that required to fit the input image after transformation.
INVALID
The value for a pixel which is assumed to mean that the pixel is invalid (which usually means that it falls off the edge of the image). Such pixels are not used for interpolations purposes.
OUTPUT
The name of the resulting resampled image.
Source comments:
   R E S A M P L E
  
   Given an input image, RESAMPLE creates an output image which
   is the result of rotating/shifting/shearing/scaling the input
   image. The transformation between the input and output pixel
   coordinates can be specified by giving a rotation ANGLE and
   scale factors to be applied to the X and Y axes (XMAG, YMAG),
   or by explicitly specifying the transformation matrix (using
   TRANSFORM). The later option allows shears to be specified.
   The first option automatically selects the output image
   shift and size so that the entire input image is present.
   The interpolation used in setting the values of the output
   pixels can be either ’nearest pixel’, ’linear’, or ’constant
   noise’.
  
   IMAGE      (Character) The name of the input image.
   TRANSFORM  (6 element array) The transformation coefficients.
   XMAG       (Numeric) The X magnification factor.
   YMAG       (Numeric) The Y magnification factor.
   ANGLE      (Numeric) The rotation angle (degrees).
   INVERT     (Keyword) Whether to invert the transformation.
   METHOD     (Numeric) The interpolation method (1, 2, or 3).
   XSIZE      (Numeric) The X-dimension of the output image.
   YSIZE      (Numeric) The Y-dimension of the output image.
   INVALID    (Numeric) The value of an invalid pixel.
   OUTPUT     (Character) The name of the output image.
  
   User variables used -  None
  
                                Michael Ashley / MSSSO 12th Dec 1986

D.203 RESCALE-Rescale using user-defined upper and lower limits

Description:
This task rescales spectra/images using user-defined upper and lower limits. The scaling is such that the interval [LOWFACT,HIGHFACT] becomes the interval [0,1]. The "limits" are not thresholds, i.e. data values beyond the limits are also scaled.
Parameters:
IMAGE
Name of image to be rescaled.
LOWFACT
lower limit of rescaling.
HIGHFACT
upper limit of rescaling.
OUTPUT
Name of resulting image.
Source comments:
   R E S C A L E
  
   This routine rescales spectra/images using user-defined upper and
   lower limits. The scaling is such that the interval
   [LOWFACT,HIGHFACT] becomes the interval [0,1]. The "limits" are
   not thresholds, i.e. data values beyond the limits are also
   scaled.
  
   Command parameters -
  
   IMAGE  (Character) The name of the structure containing the image.
          Uses main data array, or the x-axis data for the XCxxx routines.
  
   LOWFAC (Numeric) The lower limit of the rescaling.
  
   HIGHFAC (Numeric) The upper limit of the rescaling.
  
   OUTPUT (Character) The name of the result of the operation.  This
          can be the same as for IMAGE.  If not, a new structure
          is created, with everything but the data a direct
          copy of the input.
  
   02-MAY-1992  MAS (UoM): Original version.

D.204 RETYPE-Changes the type of the main data array in a file

Description:
RETYPE changes the type of the main data array in a Figaro data structure. It converts the data into the new type (warning of any conversion errors that this might generate). Depending on the structure of the file, RETYPE might leave some deadwood in the output file (i.e. it may be larger than it need be). If so, this may be removed using TRIMFILE.
Parameters:
INPUT
The name of the input data structure in which the type of the main data array is to be changed.
TYPE
The new type for the data array in the data structure. It should be any type recognised by FIGARO (i.e., one of ’FLOAT’, ’INT’, ’DOUBLE’, ’SHORT’, ’BYTE’, and ’USHORT’).
OUTPUT
The name of the resulting data file which will be the same as the original data except for the type of the main data array.
Source comments:
   R E T Y P E
  
   Name:
      RETYPE
  
   Function:
      Change the type of the main data array in a Figaro structure.
  
   Description:
      RETYPE converts the data in the main array of a Figaro structure
      from its current type to a specified type.  For example, it could
      convert a USHORT data array created by a data acquisition system
      into a FLOAT array (which is easier to work with, especially if
      you contemplate dividing your data by things such as flat fields).
  
   Parameters:
      INPUT     (Character) The name of the input data structure.
      TYPE      (Character) The type to which the data array is to be
                converted.  This can be any of the types recognised
                by Figaro.
      OUTPUT    (Character) The name of the output data structure.
  
   Keywords: None
  
   Note:
      Depending on the structure of the file, RETYPE may end up creating
      files that are larger than they need to be.  In this case,
      TRIMFILE can be used to cut out the deadwood.
  
   K.Shortridge, AAO.

D.205 ROTX-Rotate data along the X-axis

Description:
ROTX rotates the data in a file in the X-direction. Data that is shifted out of one end is shifted in at the other end. The data have to be rotated by an integer number of pixels.
Parameters:
IMAGE
The name of the data to be rotated in the X-direction. The data may have any number of dimensions. Data with more than one dimension is treated as a set of one dimensional arrays, and each is rotated independently.
PIXELS
The number of pixels that the data is to be rotated. This must be an integer, and will be truncated if a non-integer value is specified. A positive value indicates a rotation towards higher pixel numbers in X.
OUTPUT
The name of the resulting rotated data. If this is the same as IMAGE, (the default), the rotation takes place in situ. Otherwise, a new file is created. Note that the X data structure (if any) is unchanged by ROTX.
Source comments:
   R O T X
  
   Rotates a data array by an integer number of pixels in the
   X direction.  The X data is not changed.
  
   Command parameters -
  
   IMAGE  (Character) The name of the structure containing the data to
          be rotated.
  
   PIXELS (Numeric) The number of pixels by which the data is to be
          rotated.  A positive number indicates a shift towards higher
          pixel numbers.
  
   OUTPUT (Character) The name of the result of the operation.  This
          can be the same as for IMAGE.  If not, a new structure
          is created, with everything but the data a direct
          copy of the input.
                                          KS / AAO 23rd Sept 1986

D.206 SCLEAN-Interactive patching of images, especially SCUBA data.

Description:
SCLEAN is an interactive routine for marking and fixing bad pixels, rows and columns in two dimensional images. It has all the facilities of CLEAN, plus some additional ones suitable for use with files generated by the SCUBA instrument.

The principal advantages for SCUBA users of SCLEAN over CLEAN are that this application marks bad pixels by setting one of the bits (specified by the parameter BITNUM) of the quality array, rather than simply setting the data value to the magic bad value, and that an additional viewing mode is available which enables a plot of the values for a given bolometer to be seen easily.

In interactive mode, an image is displayed and operations are specified using the cursor and keyboard. In batch mode, the program will read a file of instructions and perform the operations without user intervention. SCLEAN will also optionally write a log file of the operations it has performed in the batch file format, so that a set of operations can be performed interactively, and then reperformed on the same or a different NDF by writing to the log file in the first instance and using that as a batchfile for subsequent runs.

Parameters:
IMAGE
IMAGE is the image - usually a SCUBA NDF - that is to be cleaned of bad pixels.
OUTPUT
OUTPUT is the name of the image that results from the cleaning process.
IDEV
IDEV is the name of the image device to use for display. In batch mode (i.e. if BATCHFILE is non-null) it defaults to null, in which case no graphic display is performed. It is an error for IDEV to be null in interactive mode.
QUIT
Used to confirm quitting the application.
DEG
Degree of fit to use for interpolation.
XSIZE
Size of interpolation box in X.
YSIZE
Size of interpolation box in Y.
HIGH
Highest displayed data value.
LOW
Lowest displayed data value.
BITNUM
Bit number of quality mask to modify for bad pixels.
ZOOM
Minimum pixel magnification factor in Expanded and SCUBA mode.
LOGFILE
Name of a file to log to. If null, no logging is performed. The log file begins with comment lines naming the IMAGE and OUTPUT NDFs, and continues with one line per cleaning operation, consisting of the command letter followed by zero, one or two arguments. This log file is understood if read by a subsequent invocation of the program as the BATCHFILE parameter.
BATCHFILE
Name of a file from which to read batch input. If null (the default) the program will run in interactive mode, but if this parameter has a value the named file will be read to determine the cleaning operations to be performed so that no user intervention is requested.

If a line is encountered which cannot be executed (e.g. it contains an invalid command or refers to a region outside the image) the user is notified and the line is ignored. No other attempt is made to verify that the commands in the batch file are appropriate for the particular image being examined.

Normally the batchfile will have been written by a previous invocation of SCLEAN using the LOGFILE parameter, but it can in principle be modified or written by hand. The format of the file is plain text consisting of one single letter command in column one followed by zero, one or two numeric arguments. Anything after a hash (#), and blank lines, are ignored.

Commands:
The following keys are recognised -

W - display Whole image E - Expand image around cursor position B - SCUBA type display for cursor column R - delete indicated Row (horizontal line) & fix it C - delete indicated Column (vertical line) & fix it X - delete indicated area and fix by interpolation in the x direction Y - like X, but uses vertical interpolation L - delete indicated line, but don’t fix K - delete indicated column, but don’t fix A - delete pixel at cursor, but don’t fix G - mark as Good pixel at cursor S - set stretch, ie High & low limits for display D - set degree of fit used for interpolation N - set size of deleted area for "X" and "Y" P - indicate current cursor position T - test area to see what BCLEAN might find there U - Undo last operation - replace with original image data Q - Quit program

H
H - help

A summary of available commands is displayed.

W
W - display Whole image

The whole image is displayed, stretched or compressed in both directions to fit the available plotting surface.

E
E - Expand image around cursor position

A section of the image around the cursor position is displayed with ZOOM * ZOOM display pixels representing each image pixel.

B
B - SCUBA type display for cursor column

A special display mode is used suitable for NDFs from the SCUBA instrument. Each image pixel is at least ZOOM display pixels in X and Y directions, although it will be displayed larger if there is space. Additionally, on one half of the screen is displayed a line plot of one column (the column the cursor was on when ’B’ was selected). If the cursor is on the graph half of the screen it is considered to be on the column plotted.

R
R - delete indicated Row (horizontal line) & fix it

The row of pixels at the cursor is replaced by interpolation.

C
C - delete indicated Column (vertical line) & fix it

The column of pixels at the cursor is replaced by interpolation.

X
X - delete indicated area and fix by interpolation in X direction

The XSIZE * YSIZE region at the cursor is replaced by a horizontal interpolation using a polynomial fit of degree DEG.

Y
Y - delete indicated area and fix by interpolation in Y direction

The XSIZE * YSIZE region at the cursor is replaced by a vertical interpolation using a polynomial fit of degree DEG.

S
S - set stretch, ie high & low limits for display

The user is queried for the parameters HIGH and LOW, the highest and lowest values of pixel to be represented in the colour mapping.

L
L - delete indicated line, but don’t fix

The row at the cursor is marked as bad.

K
K - delete indicated column, but don’t fix

The column at the cursor is marked as bad.

A
A - delete pixel at cursor, but don’t fix

The pixel at the cursor is marked as bad.

G
G - mark as Good pixel at cursor

The pixel at the cursor is marked as good (In fact the bit BITNUM in the quality byte is set to zero. If other bits in the quality byte are set, or if the data value itself is flagged bad, the pixel may still be bad.)

D
D - set degree of fit used for interpolation

The user is prompted for the parameter DEG, the degree of the polynomial used for interpolation by the X and Y commands.

N
N - set size of deleted area for "X" and "Y"

The user is prompted for the values of the parameters XSIZE and YSIZE, the dimensions of the box used for interpolation by the X and Y commands.

P
P - indicate current cursor position

The current cursor position is printed.

T
T - test area to see what BCLEAN might find there

The algorithm used by the BCLEAN application is run and the user is informed what spikes it would identify.

U
U - Undo last operation - replace with original image data

The last operation which modified the data is undone. Until the undo buffer fills up (usually it does not) all cleaning operations back to the start of the session can be undone in a Last In First Out fashion.

Q
Q - Quit program

The program is exited following a prompt for confirmation.

See also:
FIGARO: BCLEAN, CLEAN, COSREJ, MEDFILT, MEDSKY, TIPPEX.
KAPPA: FFCLEAN, CHPIX, FILLBAD, GLITCH, MEDIAN, MSTATS, ZAPLIN.
Source comments:
   S C L E A N
  
   Main routine for the Figaro ’SCLEAN’ command.  Displays
   a CCD image and then allows the user to move around it with
   the cursor, selecting rows and columns to be corrected and
   cosmic rays to be zapped.  The idea is that this routine can
   be used to fix up any areas in an image that were not fixed
   automatically by the non-interactive version (’BCLEAN’).  It
   may also give a better idea of the best settings for the
   BCLEAN parameters.  A mode is provided especially suited for
   examination of SCUBA data files.
  
   The task works internally with a quality array, setting the
   bit specified by the parameter BITNUM to mark pixels as bad,
   but if the input NDF uses flagged bad values and no quality
   array, the output NDF will represent quality information in
   the same way.
  
   Variances are propagated, but if any changes are made to the
   data array, the corresponding element of the variance array
   is set to zero.  This is intended to mark it as a bad value,
   since Figaro does not support explicitly flagged bad values
   in the variance array.  If this has been done, the user is
   warned at the end of processing.
  
   Command parameters -
  
   IMAGE      (Character) The name of the image to be displayed.
   OUTPUT     (Character) The name of the resulting cleaned image.
              If the same as IMAGE, the image is cleaned in situ.
   QUIT       (Logical) Used to confirm quitting the application.
   DEG        (Integer) Degree of fit to use for interpolation.
   XSIZE      (Integer) Size of deletion box in X.
   YSIZE      (Integer) Size of deletion box in Y.
   HIGH       (Real) Highest displayed data value.
   LOW        (Real) Lowest displayed data value.
   BITNUM     (Integer) Number of quality bit to modify.
   ZOOM       (Integer) Minimum pixel zoom factor.
   LOGFILE    (Character) The name of a file to log to.  If null,
              no logging is performed.
   BATCHFILE  (Character) The name of a file (in SCLEAN log file
              format) to draw batch input from.  If null (default),
              run in interactive mode.
  
   User variables -  ("<" output, "!" modified)
  
   (!) IMARRAY (Numeric array) Contains current image display
               parameters.
   (<) IMFILE  (Character) Contains name of currently displayed
               image file.
   (>) IDEV    (Character) Contains name of display device.
  
                                      MBT / IoA 29th July 1998

D.207 SCNSKY-Calculates a sky spectrum for a scanned CCD image

Description:
Uses the ’minimum median’ algorithm to create a sky spectrum from an image without any lines clear of stars. Each column of the image is split into sections of a specified length and the median of each section is calculated. The sky element corresponding to the column is set to the value of the minimum median for that column (on the assumption that this is an uncontaminated value). This algorithm is suitable for exposures taken using a CCD in scanned mode, hence the name of the routine.
Parameters:
IMAGE
Name of image to obtain sky from.
SECTION
Length of each Y-section.
SPECTRUM
Name of spectrum to be generated.
LIMIT
Ignore pixels below a minimum value?
MINIMUM
Minimum valid pixel value"
Source comments:
   S C N S K Y
  
   Uses the ’minimum median’ algorithm to create a sky spectrum
   from an image without any lines clear of stars.  Each column
   of the image is split into sections of a specified length and
   the median of each section is calculated.  The sky element
   corresponding to the column is set to the value of the minimum
   median for that column (on the assumption that this is an
   uncontaminated value).  This algorithm is suitable for exposures
   taken using a CCD in scanned mode, hence the name of the routine.
  
   Command parameters -
  
   ’IMAGE’    The name of the image
  
   ’SECTION’  The number of pixels in each section.
  
   ’MINIMUM’  A minimum ’valid’ pixel value.  A median value
              will be ignored if the range of pixels over which it
              was calculated contained pixels below this value.
  
   ’SPECTRUM’ The name of the resulting sky spectrum.
  
   Command keywords -
  
   ’LIMIT’    Use the minimum pixel value to limit the median
              calculations - this is needed because there is no
              obviously illegal value for ’MINIMUM’ which the
              program can take as an indication that it is to be
              ignored.  (If ’MINIMUM’ is given in the command
              string explicitly, ’LIMIT’ need not be set.)
  
   Input data -
  
   IMAGE is assumed to have a 2-D data structure.
  
   Output data -
  
   SPECTRUM is created with the same structure as IMAGE,
   except that the data will only have one dimension, and if
   IMAGE has an AXIS(2) structure, this will be omitted.  Any
   AXIS(1) structure will be copied unchanged.
  
                                   KS / CIT 25th May 1983

D.208 SCROSS-Cross-correlate two spectra and get relative shift

Description:
SCROSS cross-correlates two spectra and reports a relative shift in pixels between the two.
Parameters:
SPECTRUM
The name of the spectrum whose shift relative to a template spectrum is to be determined.
TEMPLATE
The name of the spectrum to be used as a template - the spectrum relative to which the shift of SPECTRUM is to be determined.
XSTART
The shift determination can be carried out over a restricted number of pixels. XSTART is the X-value of the first pixel to be used. If SPECTRUM and TEMPLATE have different X arrays then that of SPECTRUM is used. Ie, XSTART is converted into a pixel number using the calibration for SPECTRUM, ditto XEND, and this then gives the pixel range used from both SPECTRUM and TEMPLATE.
XEND
The end of the range used. Note that XSTART and XEND effectively specify a spectrum which is a subset of the original spectrum, and it is these subset spectra that are used - i.e. the cosine bell is applied to these subsets, not the whole spectrum, and similarly for the other operations performed.
FITCONT
SCROSS - unlike some other cross-correlators - attempts a continuum fit to the spectra prior to applying a cosine bell and taking the fourier transform. This replaces the reduction to zero mean sometime applied. For some data, this may not be a suitable thing to do, and it can be inhibited by setting FITCONT=NO. However, if you do so, you should have applied your own reduction to zero mean to the data prior to using SCROSS. FITCONT is the recommended option.
CBPC
By default, a cosine bell covering 10% of the specturm is applied. This is normally OK, but it can be changed by specifying a different value for CBPC.
RECORD
As an option, SCROSS will create a file containing the cross-correlation function. This can be used to see how good the cross-correlation was, or can be used to re- calculate the shift, by applying a different centering algorithm to the central spike. (You can use it as input to ARC, for example.)
CROSS
If RECORD has been set, CROSS gives the name of the cross-correlation spectrum to be created.
Source comments:
   S C R O S S
  
   Main body of the Figaro SCROSS function.  This computes
   the cross-correlation of two spectra and the location of the
   central peak of the cross-correlation.  It can be used to
   determine a relative shift between two spectra.  The cross
   correlation function can also be saved in a disk structure.
  
   SCROSS uses the Fourier cross-correlation technique, which is
   described in, for example:
  
     R. W. Hunstead, 1980, Proc. Astron. Soc. Australia, vol. 4, no. 1,
     pp. 77-80.
  
     J. Tonry and M. Davis, 1979, Astron. J, vol. 84, pp.1511-1525.
  
   Command parameters -
  
   SPECTRUM    (Character) The spectrum to be compared with
               a template spectrum.
   TEMPLATE    (Character) The template spectrum to be used.
               The two spectra should be the same length.
   XSTART      (Numeric) Data with an axis data value less than XSTART
               will be ignored in the cross-correlation.
   XEND        (Numeric) Data with an axis data value greater than XEND
               will also be ignored.  Note that these values are
               used to determine the channel numbers to be used
               for SPECTRUM, and the same ones will be used for
               TEMPLATE, even if TEMPLATE has a  different axis
               structure.
   CBPC        (Numeric) Percentage of spectrum covered by a cosine
               bell prior to application of the FFT.
   CROSS       (Character) the name of the data structure to hold
               the cross-correlation, if it is to be saved.
               The file created will be cross.dst, and will look
               like an ordinary spectrum - i.e. can be plotted by
               SPLOT, etc.  CROSS is ignored if RECORD is not
               set.
  
   Command keywords -
  
   FITCONT     If set, a continuum fit is performed on the two
               spectra prior to application of the cosine bell.
   RECORD      If set, the cross-correlation of the two spectra
               will be recorded as a new data structure.
  
   User variables used -
  
   SHIFT       (Numeric) The relative shift of the two spectra.
  
                                           KS / CIT 3rd Oct 1983

D.209 SCRUNCH-Rebin a spectrum to a linear wavelength range

Description:
SCRUNCH rebins a spectrum or a set of spectra so that the resulting data have either a linear wavelength scale or a wavelength scale that is logarithmic (i.e. has a constant velocity step). Note that SCRUNCH is not suitable for data in which the bins contain data that covers discontinuous or overlapping wavelength ranges (FIGS data, for example).
Parameters:
SPECTRUM
The spectrum (or spectra) to be scrunched. If SPECTRUM is an image (i.e. 2-D data) it will be treated as a set of spectra all of which will be scrunched individually. In this case, if the wavelength data is a 2-D array each of the data spectra will be scrunched according to the corresponding cross-section of the wavelength array. If the wavelength array is 1-D, this single array will be used for all the spectra.
WSTART
The wavelength of the center of the first bin of the resulting output data.
WEND
Normally, represents the wavelength of the center of the last bin of the resulting output data. Because this is not always the most convenient value to supply, SCRUNCH will allow WEND to be used to specify the wavelength increment value (for linear data, this is the constant wavelength difference between bins; for logarithmic data it is the constant velocity step in Km/sec). The way WEND is interpreted may be controlled explicitly by the FINAL and INCREMENT hidden keywords, but by default SCRUNCH will assume WEND is an incremental value if it is less than WSTART, and a final value if it is greater than WSTART.
BINS
The number of elements to be used for the resulting spectrum.
OUTPUT
The name of the resulting data file containing the scrunched spectrum or set of spectra. The structure of OUTPUT will be the same as that of the input file, except that the data array will generally be a different size, and any error array will have been deleted. Eventually SCRUNCH will be able to calculate the errors in the new spectrum..)
INCREMENT
If set, SCRUNCH will assume WEND is an incremental value (a velocity or wavelength step), even if it is greater than WSTART.
FINAL
If set, SCRUNCH will assume that WEND is the wavelength of the final element of the resulting spectrum, even if it is less than WSTART.
LOG
Controls whether or not the data is binned to a linear or a logarithmic wavelength scale.
LINEAR
Specifies that linear rather than quadratic interpolation is to be used during the scrunching. Usually, better results are obtained with quadratic interpolation. Note that LINEAR is the opposite of QUAD, and NOT of LOG.
QUAD
Specifies that quadratic rather than linear interpolation is to be used during the scrunching. Usually, better results are obtained with quadratic interpolation.
FLUX
If the input data represents flux (photons, for example) rather than flux density (AB magnitudes, Janskys, etc) then it should be scrunched so as to conserve flux, and FLUX should be set. See HELP FIGARO TECHNIQUES WAVELENGTH fo more details on this point.
MEAN
If the input data represents flux density (AB magnitudes, Janskys, etc) rather than flux (photons, for example) then it should be scrunched so as to conserve the mean value of the data, and MEAN should be set. See HELP FIGARO TECHNIQUES WAVELENGTH fo more details on this point.
Source comments:
   S C R U N C H
  
   Figaro routine to scrunch a spectrum or set of spectra.  Can scrunch
   either into a linear wavelength scale, where the wavelength
   increment from bin to bin is constant across the spectrum, or
   into a logarithmic scale, where the increment of the log of
   the wavelength from bin to bin is constant.  The operation
   is performed by the routine FIG_REBIN.
  
   If the input file is 2-D data, then it is treated as a set of
   1-D spectra and each is scrunched individually.   If the wavelength
   array is 1-D, then this single array will be used for all
   the spectra.  If it is 2-D, then each spectrum will be scrunched
   according to the corresponding cross-section of the wavelength
   array.
  
   The routine can either conserve flux or the mean value
   of the data.  Conserving flux is appropriate where the data is
   actually in flux units, but not when the data is in magnitude
   units.  (Consider the case where each input bin maps to two
   output bins; if the data is in flux units - photon counts, for
   example - then flux should be conserved and the mean data level
   should drop by a factor 2; if the data is in magnitudes, then
   the rebinning should not change the mean level.)  The program
   does not try to determine for itself whether the data is in flux
   or in magnitudes - it uses a command keyword.
  
   Command parameters -
  
   SPECTRUM     (Character) The name of the spectrum to be scrunched.
   WSTART       (Numeric) The wavelength of the CENTER of the first
                bin of the resulting scrunched spectrum.
   WEND         (Numeric) The wavelength of the CENTER of the final
                bin of the resulting scrunched spectrum.  If WEND is
                less than WSTART, then SCRUNCH assumes that it is the
                increment rather than the final value that is being
                specified.  If the scrunch is logarithmic and WSTART
                is greater than WEND, SCRUNCH assumes that the WEND
                value represents a velocity in km/sec.  These
                assumptions can be controlled directly by the keywords
                INCREMENT and FINAL, if they will not give the desired
                effect.
   BINS         (Numeric) The number of bins for the resulting spectrum.
   OUTPUT       (Character) The name of the resulting spectrum.
                Note that SCRUNCH cannot rebin a spectrum into itself
                and so will always create a new output file.
  
   Command keywords -
  
   LOG          Bin into logarithmic wavelength bins.
   MEAN         Conserve mean data level rather than flux.
   FLUX         Conserve flux rather than mean data level.
   LINEAR       Use linear interpolation when rebinning.
   QUAD         Use quadratic interpolation when rebinning.
   INCREMENT    WEND is an increment value, even though it is > WSTART.
   FINAL        WEND is a final value, even though it is < WSTART.
  
   User variables -
  
   SCRUNCH_INC  Is set to the wavelength increment if linear
                rebinning is used, and to the velocity increment if
                log rebinning is used.
   SCRUNCH_END  Is set to the final wavelength value.  (This is for
                those cases where the WEND value represents an
                increment.)
  
                                            KS / CIT 7th Feb 1984

D.210 SDIST-Analyse an image containing spectra for S-distortion

Description:
SDIST traces curved continuous spectra in an image. These can be due to image tube S-distortion (the original use of the program), or may perhaps be curved echelle orders. SDIST fits polynomials to the spectra and writes the fits to a file that may be used by other programs such as CDIST. Before using SDIST, starting points for all the spectra to be traced must be indicated, usually by displaying the image using IMAGE and selecting points in the centers of the various spectra using ICUR.
Parameters:
IMAGE
The image that contains the spectra to be traced. Normally, this will be already displayed on the image display, and the centers of the spectra (the places SDIST is to start tracing from - it goes to the edge in both directions out from the selected points) should have been selected using ICUR.
COLUMNS
SDIST adds the data in several columns at a time to get a cross-section through the spectrum it is tracing. The more columns it averages, the better the signal to noise it obtains, the faster the processing, but the jumpier the fit may become. A few columns is normally enough. It should be increased for noisier data.
TRACE
SDIST applies one of a selection of algorithms to trace the spectra. Four are available at present:

G (the original option) fits a guassian to the profile of the data. This is suitable for stellar spectra taken with a wide slit, or any data that genuinely is gaussian. E (Edge) uses an algorithm that looks for the edges in data and takes the average edge position. It is suitable for data that is roughly ‘top-hat’ in shape but tends to give rather quantised results when the edges are very sharp (such edges cannot be determined to better than a pixel). This shows up clearly if the SOFTD option is used. C (COG) is a compromise option for non-gaussian data that determines the edges, then used the center of gravity of the data between them. B (Balance) is an extremely crude algorithm that determines the centre of gravity over the width specified. It is very robust, but very crude - use only in desperation.

WIDTH
SDIST needs an indication of the width of the spectra it is to trace. If the trace mode is G, this is the half width of the gaussians it fits to the data, so can be quite critical. Do not make this too large. In particular, the greater SDIST is, the further from the center it looks, and can go off the edge of the image for extreme spectra. For the edge tracing options, the width must not be so great that it encompases the falling edges of the next spectrum out. Try to give an accurate value for WIDTH.
MAXDEG
SDIST fits polynomials of degree MAXDEG to the spectra it traces. In general, MAXDEG should be as no higher than is needed to get a satisfactory fit, since this minimises any effects at the edges if the spectra could not be traced all the way to the edges of the image.
SOFTD
If set, SDIST plots for each spectrum the points traced and the curve fitted to them. This can be particularly useful when trying to decide on the trace mode to use - the quantised effects sometimes found with the E(dge) trace show up very well here.
DIAGNOSE
If set, the detailed reasons for any failures to trace the various spectra are logged. This is too detailed to be of general interest, being most useful when new trace algorithms are being debugged.
NEXT
Used to pause between plot pages.
Source comments:
   S D I S T
  
   Determines the s-distortion parameters for a star spectrum.
   This program requires as input an image containing at least one
   stellar spectrum.  For each spectrum it is to examine, it
   assumes that a point has been indicated somewhere in the center
   of the spectrum.  Starting at that point, it attempts to follow
   the spectrum and so map out the distortion.
  
   Command parameters -
  
   IMAGE      (Character) the image containing the spectra.
   COLUMNS    (Numeric) The number of columns to be added
              together when tracing the spectra.
   TRACE      (Character) Controls the algorithm used to follow
              the spectra.  Only the first character is significant.
              ’E’ (Edges) Indicates that the data profile is a ’top-hat’
              shape - as you might get from a continuum source
              through a dekker.  If EDGES is set, an edge
              locating algorithm is used, and the width of the
              top hat is assumed to be approximately WIDTH*2.
              ’C’ is the same as ’E’, except that the center is
              taken as the center of gravity of the data within the
              edges, while ’E’ takes it as the average of the edges.
              ’G’ (Gaussian) Indicates that the profile is roughly
              gaussian, of half width WIDTH.
   WIDTH      (Numeric) The expected half-width of the spectra in
              pixels.
   MAXDEG     (Numeric) The maximum degree polynomial to be
              fitted.
  
   Command keywords -
  
   SOFTD      Indicates that the fit results are to be plotted on
              the current soft graphics device.
   DIAGNOSE   Requests more detailed diagnostics on the tracing
   NEXT       Used to pause between plot pages.
  
   User variables -  (">" input, "<" output)
  
   (>) IMARRAY  (Numeric array) Contains the parameters that
                specify the current image display.  See IMAGE
                for full details.
   (>) NPIXELS  (Numeric) Number of points selected using ICUR
   (>) XPIXELS  (Numeric array) X positions of points selected
   (>) YPIXELS  (Numeric array) Y      "    "     "      "
  
   Output files -
  
   SDIST.DAT contains the results of the fit(s), in a format that
             can be treated as follows -
  
             3 header lines, all beginning with ’*’
             One line giving the number of spectra traced, and the
             dimensions of the image used, in the format
             20X,I5,15X,I8,4X,I8.
             Then, for each spectrum traced, one record giving
             the spectrum number, and the leftmost and rightmost
             pixels covered by the trace, in format
             11X,I5,17X,I5,4X,I5, then 1 record giving the average
             Y value in the spectrum, and the width of the
             spectrum, in format 16X,F13.7,10X,F9.2,
             which is followed by 3 records giving the 11
             polynomial coefficients for the fit, in 3D23.16.
             Coefficients are given constant first, with any unused
             coefficients set to zero.
  
                                           KS / CIT 5th Feb 1984

D.211 SETOBJ-Assign value to an HDS primitive

Usage:
setobj value object
Description:
This routine assigns a specified (numeric or string) value to an existing HDS primitive. The destination object must exist. It can be a primitive scalar or a cell in a primitive array.
Parameters:
VALUE
The value the scalar primitive HDS object is to assume.
OBJECT
The HDS object to be modified. Specify beginning with directory and file name in the syntax of the operating system, followed by the dot-separated structure hierarchy. Elements of structure arrays are specified in ordinary brackets ().
Examples:
   1.  setobj value=90. object=file.MORE.FIGARO.TIME
     Store the number or string 90 in the existing scalar HDS
     object MORE.FIGARO.TIME in the file "file".
  
See also:
FIGARO: CREOBJ, COPOBJ, DELOBJ, RENOBJ.
KAPPA: ERASE.
Authors:
KS: Keith Shortridge (AAO)

HME: Horst Meyerdierks (UoE, Starlink)

JFL: John Lightfoot (ROE)

D.212 SFIT-Fit a polynomial to a spectrum

Description:
Task to generate a spectrum by fitting a polynomial to an input spectrum. An orthogonal polynomial of specified order is fitted either to the spectrum or to its logarithm, and the result is used to generate a new spectrum.
Parameters:
SPECTRUM
Name of spectrum to be fitted.
ORDER
Order of fitted polynomial.
LOGS
Fit to logarithms of data.
OUTPUT
Name of resulting spectrum.
Source comments:
   S F I T
  
   Figaro function to generate a spectrum by fitting a polynomial
   to an input spectrum.  An orthogonal polynomial of specified
   order is fitted either to the spectrum or to its logarithm, and
   the result is used to generate a new spectrum.
  
   Command parameters -
  
   SPECTRUM    (Character) The name of the spectrum to be fitted.
  
   ORDER       (Numeric) The order to be used for the fit.
  
   OUTPUT      (Character) The name of the output file to
               be created.  If this is the same as the input
               spectrum, the data in the input spectrum will
               be modified.
  
   Command keywords -
  
   LOGS        Indicates that the logs of the pixel values
               of the input spectrum are to be fitted.
  
                                            KS / CIT 5th June 1983

D.213 SKYLINER-Removes a sky spectrum normalised the 5577 [OI] line.

Description:
Removes a sky spectrum normalised by the height of the 5577 [OI] emission line.
Usage:
skyliner in sky out
Parameters:
IN
The one- or two-dimensional spectrum to be sky-subtracted.
SKY
The one-dimensional sky spectrum. It must not contain bad pixels as they could affect the estimation of the [OI] line strength.
OUT
The sky-subtracted one- or two-dimensional spectrum.
Source comments:
   None available.
  

D.214 SLICE-Takes a slice with arbitrary end points through an image

Description:
SLICE creates a ’spectrum’ by taking a slice through a two dimensional image. This particular program is essentially lifted from the AIPS package and uses the scheme described there as ’Everett Interpolation’. Note that the ’slice’ through the image is conceptually of zero width - i.e. it is a slice through the interpolated surface represented by the discrete image data.
Parameters:
IMAGE
The image file to be sliced.
YSTART
The Y value of the starting end of the slice. Note that SLICE conceptually takes a slice of zero width through the interpolated surface generated from the image data. Therefore, the ends of the slice need not be centered on an image pixel. The convention used is that the X and Y values ued for a pixel refer to the CENTER of the pixel. It may help to point out that if IMAGE were a 256 by 256 image, the commands SLICE IMAGE XST=1. XEN=256. YST=128. YEN=128. EL=256 EXTRACT IMAGE YST=128 YEN=128 would be equivalent
YEND
The Y value of the terminating end of the slice. Note that YEND may be less than YSTART.
XSTART
The X value for the starting end of the slice.
XEND
The X value of the terminating end of the slice. Note that XEND may be less than XSTART.
ELEMENTS
Since the slice is taken - conceptually - through a continuous surface generated by interpolating between the pixel values in the image, it can have any number of pixels desired.
SPECTRUM
The name of the spectrum generated. Any data objects in the original image will be copied over into SPECTRUM, except for the X and Y information. Which is a good reason for using EXTRACT or YSTRACT even in cases where SLICE would generate equivalent data.
Source comments:
   S L I C E
  
   SLICE creates a ’spectrum’ by taking a slice through a two
   dimensional image.  This particular program is essentially
   lifted from the AIPS package and uses the scheme described there
   as ’Everett Interpolation’.  For more details see the comments
   for the various subroutines such as FIG_CSLICE.  Note that the
   ’slice’ through the image is conceptually of zero width - i.e. it
   is a slice through the interpolated surface represented by the
   discrete image data.
  
   Command parameters -
  
   IMAGE     (Character) The image from which the slice is to be
             taken.
   YSTART    (Numeric) The AXIS(2) value for the start of the slice.
   YEND      (Numeric) The AXIS(2) value for the end of the slice.
   XSTART    (Numeric) The AXIS(1) value for the start of the slice.
   XEND      (Numeric) The AXIS(1) value for the end of the slice.
             Note that YSTART etc can represent any point in the
             image, and the convention is that axis data values
             for pixels refer to the CENTERS of those pixels -
             This means, for example, that if IMAGE is a 256 by 256
             image, the commands
             SLICE IMAGE XSTART=1.0 XEND=256.0 YSTART=128.0 YEND=128.0
             EXTRACT IMAGE,128,128   will have exactly the same
             results.
   ELEMENTS  (Numeric) Number of pixels in the resulting spectrum.
   SPECTRUM  (Character) The resulting spectrum.
  
                                             KS / CIT 23rd March 1984

D.215 SOFT-Sets the device/type for terminal graphics

Description:
The SOFT command is used to set the current device and type for all ’soft-copy’ (as opposed to ’hardcopy’) graphics output.
Parameters:
SOFTDEV
The device to which all soft-copy (as opposed to hardcopy) graphics output is to be sent. Normally, a device name as recognised by SGS should be used - that is, the device specified should be one of those listed in response to the OPTIONS keyword - i.e. by the command SOFT OPTIONS. If necessary, a device type and connection id can be used, by specifying e.g. SOFTDEV="827,1" and by setting FORCE=YES.
OPTIONS
If set, a list of all the device names recognised by the SGS system is output.
FORCE
Normally, SOFT will reject a device specification that is not known to SGS. However, if FORCE is set, it will use whatever is specified for SOFTDEV unquestioningly. If it fails, that’s your problem.
DRAW
If set, SOFT will output a test plot to the specified device. This acts as a test that the specification was correct.
Source comments:
   S O F T  /  H A R D  /  I D E V
  
   SOFT is used to set the user variable (SOFT) that controls
   the soft copy graphics output of Figaro programs.  HARD is
   used to set the user variable (HARD) that controls the
   hardcopy graphics output. IDEV is used to set the user variable
   (IDEV) that controls the image display.
  
   Command parameters -
  
   HARDDEV  (Character string) A device name recognised by
     or     the GKS version of PGPLOT.  Normally, what should
   SOFTDEV  be used is one of the device names recognised by
     or     GNS.  HARDDEV and SOFTDEV are used by HARD and SOFT
   IMAGDEV  respectively.
  
   Command keywords -
  
   OPTIONS  Causes a list of the various acceptable SGS device
            names to be output.
  
   FORCE    Forces the device specification to be accepted even
            if it does not match one of the acceptable SGS names.
  
   DRAW     Draws a test diagram on the screen.  (DRAW is the
            default for SOFT and IDEV, DRAW=NO is the default for
            HARD)
  
                                   KS / AAO 16th March 1988

D.216 SPECCONT-Contour a two-dimensional cut.

Usage:

speccont in overlay=? world=? start=? step=? end=?

Description:

This routine displays a two-dimensional cut as a contour plot. The cut can be an ordinary image, a long-slit spectrum, or any cut through a spectroscopic data cube. The plot area is the current (AGI) picture of the graphics device.

Parameters:
CLEAR
CLEAR = _LOGICAL (Read) If true the plot area will be cleared before plotting. [FALSE]
OVERLAY
OVERLAY = _LOGICAL (Read) If true then the last (AGI) data picture inside the current (AGI) picture is used to define the plot area and its world coordinates. Only that area will be cleared if CLEAR is true. No new labelling of the plot will occur. [FALSE]
IN
IN = NDF (Read) The input NDF. It must be two-dimensional - not counting degenerate axes.
DEVICE
DEVICE = GRAPHICS (Read) The graphics display device.
FILL
FILL = _LOGICAL (Read) If false then the plot window will be adjusted to give the same plot scale horizontally and vertically. If true, scaling is independent in each direction and the plot will fill the area available. This parameter is used only if OVERLAY is false. [FALSE]
ROMAN
ROMAN = _LOGICAL (Read) If true, PGPLOT’s roman font is used for drawing text. If false, the normal (single-stroke) font is used. [FALSE]
HEIGHT
HEIGHT = _REAL (Read) The height of the characters measured in units of PGPLOT default text height, which is approximately 1/40 of the height of the (AGI) base picture (i.e. 1/40 the height of the work station window, screen or paper). HEIGHT will be used for labelling the plot box. The contour labels are always half that size. [1.]
COLOUR
COLOUR = _INTEGER (Read) The PGPLOT colour index to be used for the plot. This can be formally between 0 and 255, but not all devices support all colours. The default colour representation is: - 0: Background, - 1: Foreground (default), - 2: Red, - 3: Green, - 4: Blue, - 5: Cyan, - 6: Magenta, - 7: Yellow, - 8: Orange, - 9: Green/Yellow, - 10: Green/Cyan, - 11: Blue/Cyan, - 12: Blue/Magenta, - 13: Red/Magenta, - 14: Dark grey, - 15: Light grey.
THICK
THICK = _INTEGER (Read) The PGPLOT line thickness. Can be between 1 and 21. [1]
DASH
DASH = _INTEGER (Read) The PGPLOT dash pattern: - 1: Full line, - 2: Long dash, - 3: Dash-dot-dash-dot, - 4: Dotted, - 5: Dash-dot-dot-dot.
AXES
AXES = _CHAR (Read) Array of switches to turn on or off the drawing of either of the four box sides. The sides are counted from bottom clockwise: bottom, left, top, right. Any switch can be "0" or "+". E.g. ’00++’ would switch off the bottom and left axes and switch on the top and right axes. [’++++’]
TICK
TICK = _CHAR (Read) Array of switches to turn on or off the drawing of ticks along either axis. Ticks are drawn only if the corresponding axis is also drawn. The sides are counted from bottom clockwise: bottom, left, top, right. Any switch can be "0", "+" or "-". E.g. ’00+-’ would switch off the bottom and left ticks and switch on the top and right ticks. The top axis would have ticks outward, the right axis would have ticks inward. Note that with the current plot software, ticks are drawn only if the axis is drawn as well. [’—-’]
NUML
NUML = _CHAR (Read) Array of switches to turn on or off the drawing of numeric labels along either axis. The sides are counted from bottom clockwise: bottom, left, top, right. Any switch can be "0" or "+"; the second and fourth switch can also be "-". E.g. ’0+0-’ would switch off the bottom and top labels and switch on the left and right labels. The left axis would have labels horizontal (orthogonal), the right axis would have labels vertical (parallel). [’++00’]
TEXT
TEXT = _CHAR (Read) Array of switches to turn on or off the drawing of text labels along either axis. The sides are counted from bottom clockwise: bottom, left, top, right. Any switch can be "0" or "+". E.g. ’0++0’ would switch off the bottom and right labels and switch on the left and top labels. [’++++’]
MAJOR
MAJOR = _REAL (Read) The distance in world coordinates between major tick marks. The first element is for the horizontal direction, the second for the vertical direction. This is also the distance along the axis between numeric labels. Values of 0 cause PGPLOT to choose the major tick interval automatically. [0.,0.]
MINOR
MINOR = _INTEGER (Read) The number of minor tick intervals per major tick interval. The first element is for the horizontal direction, the second for the vertical direction. Values of 0 for MINOR or MAJOR cause PGPLOT to choose the minor tick interval automatically. [0,0]
BOTTOM
BOTTOM = _CHAR (Read) The text label for the bottom axis. Give null to construct the label from the input NDF axis label and unit. Within the string, you can use the following escape sequences:
  • \fn Normal (single stroke) font,
  • \fr Roman font,
  • \fi Italic font,
  • \fs Script font,
  • \u Superscript (use only paired with \d),
  • \d Subscript (use only paired with \u),
  • \b Backspace,
  • \\Backslash,
  • \A Danish umlaut (Angstroem),
  • \g Any greek letter.
LEFT
LEFT = _CHAR (Read) The text label for the left axis. Give null to construct the label from the input NDF axis label and unit. Within the string, you can use the following escape sequences:
  • \fn Normal (single stroke) font,
  • \fr Roman font,
  • \fi Italic font,
  • \fs Script font,
  • \u Superscript (use only paired with \d),
  • \d Subscript (use only paired with \u),
  • \b Backspace,
  • \\Backslash,
  • \A Danish umlaut (Angstroem),
  • \g Any greek letter.
TOP
TOP = _CHAR (Read) The text label for the top axis. Give null to use the title from the input NDF. Within the string, you can use the following escape sequences:
  • \fn Normal (single stroke) font,
  • \fr Roman font,
  • \fi Italic font,
  • \fs Script font,
  • \u Superscript (use only paired with \d),
  • \d Subscript (use only paired with \u),
  • \b Backspace,
  • \\Backslash,
  • \A Danish umlaut (Angstroem),
  • \g Any greek letter.
RIGHT
RIGHT = _CHAR (Read) The text label for the right axis. Give null to construct the label from the input NDF label and unit. Within the string, you can use the following escape sequences:
  • \fn Normal (single stroke) font,
  • \fr Roman font,
  • \fi Italic font,
  • \fs Script font,
  • \u Superscript (use only paired with \d),
  • \d Subscript (use only paired with \u),
  • \b Backspace,
  • \\Backslash,
  • \A Danish umlaut (Angstroem),
  • \g Any greek letter.
LABSPC
LABSPC( 4 ) = _REAL (Read) If the plot is not an overlay then this specifies the space left at the bottom, left, top, and right between the plot window and the current (AGI) picture. The space is measured as a fraction of the current picture. Ticks and numeric labels are drawn outward from the plot window, but text labels are drawn inward from the current picture. The labelling space must be between zero and 0.5. [0.1,0.1,0.05,0.05]
WORLD
WORLD( 4 ) = _REAL (Read) The world coordinates of the plot window. Give null to use the extent of the input NDF instead. The four elements are the bounds on the left, right, bottom, and top in that order. Left and right bound must not be equal, neither must bottom and top. [!]
START
START = _REAL (Read) The first contour level.
STEP
STEP = _REAL (Read) The step between successive major contour levels. If zero is given then only one contour at value START will be drawn. STEP can be negative. In addition to the major contours, three minor contours will be drawn between successive major contours. The major contours are thick and labelled with the contour value. The minor contours are thin and labelled with an arrow pointing counter-clockwise around a local maximum.
END
END = _REAL (Read) The last contour level. This may be adjusted slightly so as to comply with START and STEP. If given equal to START then only one contour at value START will be drawn. END can be smaller than START.
Source comments:
     S P E C C O N T
  
     The plot can be an overlay over the most recent data picture
     inside the current picture, or a new plot inside the current
     picture. (The current picture after SPECCONT is the same as
     before.)
  
     The screen contents of the current picture can be erased or not.
     If the plot is not an overlay, then the space to be left for axis
     labels as well as the exact labelling can be specified.
  
     The labelling consists of axes, axis ticks, numeric labels at the
     major ticks, and text labels. The axes are counted from bottom
     clockwise. Each axis can be drawn or not. Each drawn axis can have
     ticks or not. Each axis can have numeric labels or not. The left
     and right axes can have either horizontal (orthogonal) or vertical
     (parallel) numeric labels. Each axis can have a text label or not.
  
     The kind of labelling is controlled by several 4-character
     strings. Each character is the switch for axis 1, 2, 3, 4
     respectively. "0" turns an option off for that axis, "+" turns it
     on. For the ticks and for numeric labels of axes 2 and 4, "-" is
     also allowed. It yields inward ticks and vertical numeric labels.
  
     The attributes of the plot can be selected. These are
     -  colour
     -  line thickness
     -  character height
     -  simple or roman font
     -  dash pattern
  
     Most parameters default to the last used value.
Examples:
  speccont cube(,5,) start=2 step=2 end=10 accept
     This takes the fifth xz-cut from the input cube. It draws
     contours at values 2, 4, 6, 8, and 10.
Notes:
This routine recognises the Specdre Extension v. 0.7.

This routine recognises and uses coordinate transformations in AGI pictures.

D.217 SPECGRID-Plot spectra on position grid.

Usage:

specgrid in overlay=? bottom=? left=? top=? right=? labspc=? cworld=? legend=? sworld=? xlegend=? ylegend=?

Description:
This routine takes an NDF and displays all the spectra (rows) in it. Each spectrum occupies a cell in the plot which is positioned according to its coordinates. The coordinates for each spectrum are normally stored in the Specdre Extension, but for an NDF of at least three dimensions the first two non-spectroscopic axes can be used instead. The plot area is the current (AGI) picture of the graphics device.
Parameters:
CLEAR
CLEAR = _LOGICAL (Read) If true the plot area will be cleared before plotting. When plotting to a printer file, set this false. Otherwise the output may be preceded by an empty page. [FALSE]
OVERLAY
OVERLAY = _LOGICAL (Read) If true then the last (AGI) data picture inside the current (AGI) picture is used to define the plot area and its world coordinates. Only that area will be cleared if CLEAR is true. No new labelling of the plot will occur. [FALSE]
IN
IN = NDF (Read) The input NDF. If it does not have explicit components COORD1 and COORD2 in its Specdre Extension, then the NDF must have at least three dimensions (one spectroscopic and two positional axes). In any case, the spectroscopic axis must be the first non-degenerate axis.
DEVICE
DEVICE = GRAPHICS (Read) The graphics display device.
LIN
LIN = _LOGICAL (Read) If true, the spectral data points will be connected by a line-style polygon. [TRUE]
BIN
BIN = _LOGICAL (Read) If true, the spectral data points will be connected by a bin-style (or histogram-style) polygon. [FALSE]
MARK
MARK = _INTEGER (Read) This parameter determines the kind of marker to be drawn at each spectral data point [0]: - 0: No markers drawn, - 1: Diagonal cross, - 2: Asterisk, - 3: Open circle, - 4: Open square, - 5: Filled circle, - 6: Filled square.
ERROR
ERROR = _LOGICAL (Read) If true and variance information available, error bars will be drawn for each spectral data point. [FALSE]
WIDTH
WIDTH = _LOGICAL (Read) If true, the pixel width will be indicated by horizontal bars for each spectral data point. [FALSE]
FRAME
FRAME = _LOGICAL (Read) If true, each spectral cell gets a plain box drawn around it. [TRUE]
FILL
FILL = _LOGICAL (Read) If false then the plot window will be adjusted to give the same plot scale horizontally and vertically. If true, scaling is independent in each direction and the plot will fill the area available. This parameter is used only if OVERLAY is false. [FALSE]
ROMAN
ROMAN = _LOGICAL (Read) If true, PGPLOT’s roman font is used for drawing text. If false, the normal (single-stroke) font is used. [FALSE]
HEIGHT
HEIGHT = _REAL (Read) The height of the characters measured in units of PGPLOT default text height, which is approximately 1/40 of the height of the (AGI) base picture (i.e. 1/40 the height of the work station window, screen or paper). HEIGHT will be used for labelling the plot box (coordinate space). The legend cell labels are always half that size. [1.]
COLOUR
COLOUR = _INTEGER (Read) The PGPLOT colour index to be used for the plot. This can be formally between 0 and 255, but not all devices support all colours. The default colour representation is: - 0: Background, - 1: Foreground (default), - 2: Red, - 3: Green, - 4: Blue, - 5: Cyan, - 6: Magenta, - 7: Yellow, - 8: Orange, - 9: Green/Yellow, - 10: Green/Cyan, - 11: Blue/Cyan, - 12: Blue/Magenta, - 13: Red/Magenta, - 14: Dark grey, - 15: Light grey.
THICK
THICK = _INTEGER (Read) The PGPLOT line thickness. Can be between 1 and 21. [1]
DASH
DASH = _INTEGER (Read) The PGPLOT dash pattern [1]:
  • 1: Full line,
  • 2: Long dash,
  • 3: Dash-dot-dash-dot,
  • 4: Dotted,
  • 5: Dash-dot-dot-dot.
AXES
AXES = _CHAR (Read) Array of switches to turn on or off the drawing of either of the four box sides. The sides are counted from bottom clockwise: bottom, left, top, right. Any switch can be "0" or "+". E.g. ’00++’ would switch off the bottom and left axes and switch on the top and right axes. [’++++’]
TICK
TICK = _CHAR (Read) Array of switches to turn on or off the drawing of ticks along either axis. Ticks are drawn only if the corresponding axis is also drawn. The sides are counted from bottom clockwise: bottom, left, top, right. Any switch can be "0", "+" or "-". E.g. ’00+-’ would switch off the bottom and left ticks and switch on the top and right ticks. The top axis would have ticks outward, the right axis would have ticks inward.
NUML
NUML = _CHAR (Read) Array of switches to turn on or off the drawing of numeric labels along either axis. The sides are counted from bottom clockwise: bottom, left, top, right. Any switch can be "0" or "+"; the second and fourth switch can also be "-". E.g. ’0+0-’ would switch off the bottom and top labels and switch on the left and right labels. The left axis would have labels horizontal (orthogonal), the right axis would have labels vertical (parallel). [’++00’]
TEXT
TEXT = _CHAR (Read) Array of switches to turn on or off the drawing of text labels along either axis. The sides are counted from bottom clockwise: bottom, left, top, right. Any switch can be "0" or "+". E.g. ’0++0’ would switch off the bottom and right labels and switch on the left and top labels. [’++++’]
MAJOR
MAJOR = _REAL (Read) The distance in world coordinates between major tick marks. The first element is for the horizontal direction, the second for the vertical direction. This is also the distance along the axis between numeric labels. Values of 0 cause PGPLOT to choose the major tick interval automatically. [0.,0.]
MINOR
MINOR = _INTEGER (Read) The number of minor tick intervals per major tick interval. The first element is for the horizontal direction, the second for the vertical direction. Values of 0 for MINOR or MAJOR cause PGPLOT to choose the minor tick interval automatically. [0,0]
BOTTOM
BOTTOM = _CHAR (Read) The text label for the bottom axis. Give null to construct the label from the input NDF axis label and unit. Within the string, you can use the following escape sequences [!]:
  • \fn Normal (single stroke) font,
  • \fr Roman font,
  • \fi Italic font,
  • \fs Script font,
  • \u Superscript (use only paired with \d),
  • \d Subscript (use only paired with \u),
  • \b Backspace,
  • \\Backslash,
  • \A Danish umlaut (Angstroem),
  • \g Any greek letter.
LEFT
LEFT = _CHAR (Read) The text label for the left axis. Give null to construct the label from the input NDF axis label and unit. Within the string, you can use the following escape sequences [!]:
  • \fn Normal (single stroke) font,
  • \fr Roman font,
  • \fi Italic font,
  • \fs Script font,
  • \u Superscript (use only paired with \d),
  • \d Subscript (use only paired with \u),
  • \b Backspace,
  • \\Backslash,
  • \A Danish umlaut (Angstroem),
  • \g Any greek letter.
TOP
TOP = _CHAR (Read) The text label for the top axis. Give null to use the title from the input NDF. Within the string, you can use the following escape sequences [!]:
  • \fn Normal (single stroke) font,
  • \fr Roman font,
  • \fi Italic font,
  • \fs Script font,
  • \u Superscript (use only paired with \d),
  • \d Subscript (use only paired with \u),
  • \b Backspace,
  • \\Backslash,
  • \A Danish umlaut (Angstroem),
  • \g Any greek letter.
RIGHT
RIGHT = _CHAR (Read) The text label for the right axis. Give null to construct the label from the input NDF label and unit. Within the string, you can use the following escape sequences [!]:
  • \fn Normal (single stroke) font,
  • \fr Roman font,
  • \fi Italic font,
  • \fs Script font,
  • \u Superscript (use only paired with \d),
  • \d Subscript (use only paired with \u),
  • \b Backspace,
  • \\Backslash,
  • \A Danish umlaut (Angstroem),
  • \g Any greek letter.
LABSPC
LABSPC( 4 ) = _REAL (Read) This is a measure for the distance of the text labels from the coordinate view port. The elements are for the bottom, left, top, and right edge respectively. In the first instance the whole plot is inside the current (AGI) picture and LABSPC specifies the fraction of this view surface to be reserved for labelling. However, if FILL is false, then the view port will shrink further either horizontally or vertically to give equal plot scales. The labelling area will then move inwards as well. The labelling space is measured as a fraction of the current picture. The values must be between zero and 0.5. [0.1,0.1,0.05,0.05]
CWORLD
CWORLD( 4 ) = _REAL (Read) The world coordinates of the plot window. Give null to use the coordinate extent of the input NDF instead. The elements are
  • 1: Left bound in coordinate space,
  • 2: Right bound in coordinate space,
  • 3: Bottom bound in coordinate space,
  • 4: Top bound in coordinate space,

Left and right bound must not be equal, neither must bottom and top. [!]

LEGEND
LEGEND( 2 ) = _REAL (Read) The coordinates of the legend cell. Each spectral cell has coordinates according to the NDF’s Specdre Extension (or positional axes). LEGEND is in the same units the position of the empty cell that explains the spectral and intensity coverage of all cells. Give null to avoid the legend cell being drawn. [!]
CELLSZ
CELLSZ( 2 ) = _REAL (Read) The size of the spectral cells, specified in coordinate units. These must be positive. [1.,1.]
SWORLD
SWORLD( 4 ) = _REAL (Read) The world coordinates within the spectrum cells. Give null to use the spectral extent and data range of the input NDF instead. The elements are
  • 1: Left bound in spectroscopic space,
  • 2: Right bound in spectroscopic space,
  • 3: Bottom bound in spectroscopic space,
  • 4: Top bound in spectroscopic space.

Left and right bound must not be equal, neither must bottom and top. [!]

XLEGEND
XLEGEND = _CHAR (Read) The text label for the bottom axis of the legend cell. Give null to construct the label from the input NDF axis label and unit. Within the string, you can use the following escape sequences [!]:
  • \fn Normal (single stroke) font,
  • \fr Roman font,
  • \fi Italic font,
  • \fs Script font,
  • \u Superscript (use only paired with \d),
  • \d Subscript (use only paired with \u),
  • \b Backspace,
  • \\Backslash,
  • \A Danish umlaut (Angstroem),
  • \g Any greek letter.
YLEGEND
YLEGEND = _CHAR (Read) The text label for the left axis of the legend cell. Give null to construct the label from the input NDF label and unit. Within the string, you can use the following escape sequences [!]:
  • \fn Normal (single stroke) font,
  • \fr Roman font,
  • \fi Italic font,
  • \fs Script font,
  • \u Superscript (use only paired with \d),
  • \d Subscript (use only paired with \u),
  • \b Backspace,
  • \\Backslash,
  • \A Danish umlaut (Angstroem),
  • \g Any greek letter.
Source comments:
     S P E C G R I D
  
     The plot can be an overlay in coordinate space to a previous plot,
     or a new plot. A plot can be combined from spectra in different
     NDFs, or it can overlay spectra on an image of the same or a
     similar region in coordinate space.
  
     The previous contents of the plot area can be erased or not.
     If the plot is not an overlay, then the space to be left for
     axis labels as well as the exact labelling can be specified.
  
     The labelling (in coordinate space) consists of axes, axis ticks,
     numeric labels at the major ticks, and text labels. The axes are
     counted from bottom clockwise. Each axis can be drawn or not. Each
     drawn axis can have ticks or not. Each axis can have numeric
     labels or not. The left and right axes can have either horizontal
     (orthogonal) or vertical (parallel) numeric labels. Each axis can
     have a text label or not.
  
     The kind of labelling is controlled by several 4-character
     strings. Each character is the switch for axis 1, 2, 3, 4
     respectively. "0" turns an option off for that axis, "+" turns
     it on. For the ticks and for numeric labels of axes 2 and 4, "-"
     is also allowed. It yields inward ticks and vertical numeric
     labels.
  
     Labelling in spectroscopic space (e.g. wavelength-intensity space)
     is optional. It is in the form of an empty spectrum cell at a
     specified position in coordinate space. This legend cell is
     labelled with the ranges in spectroscopic space that is covered by
     each cell. It also has text labels to indicate what quantities are
     displayed.
  
     The attributes of the plot can be selected. These are
     -  colour
     -  line thickness
     -  character height
     -  simple or roman font
     -  dash pattern
  
     Most parameters default to the last used value.
Examples:
  specgrid in accept
     Let’s assume the given NDF is three-dimensional and has neither
     a Specdre Extension, nor any axis information. This implies
     that the first axis is spectroscopic with pixel centres 0.5,
     1.5, ..., NX-0.5. The second and third axes will thus be used
     to position the plots of the individual spectra horizontally
     and vertically. The positions will also be (0.5,0.5),
     (1.5,0.5), ..., (NY-0.5,NZ-0.5). Each cell has the default size
     of 1.0 by 1.0, thus neighbouring pixels in the Y-Z plane of the
     NDF will be in adjacent cells on the plot. All cells use
     internally the same scales for the spectroscopic value and the
     data value. Since these are not specified in parameters, each
     cell goes from 0.5 to NX-0.5 horizontally and from the minimum
     data value to the maximum data value vertically. There will be
     no legend cell, since its position was not given.
  
Notes::
This routine recognises the Specdre Extension v. 1.1.

This routine recognises and uses coordinate transformations in AGI pictures.

D.218 SPECPLOT-Plot a spectrum.

Usage:

specplot in overlay=? bottom=? left=? top=? right=? labspc=? world=?

Description:

This routine plots a spectrum (or any one-dimensional NDF section) in the current (AGI) picture of the graphics device.

Parameters:
INFO
INFO = _LOGICAL (Read) If false, the routine will issue only error messages and no informational messages. [TRUE]
CLEAR
CLEAR = _LOGICAL (Read) If true, the part of the graphics device corresponding to the current (AGI) picture is erased before the plot is drawn. [FALSE]
OVERLAY
OVERLAY = _LOGICAL (Read) If true, the plot will be an overlay on the most recent (AGI) data picture within the current (AGI) picture. If false, the plot will be user-defined, but the inner box is restricted to the current (AGI) picture.
IN
IN = NDF (Read) The input NDF.
LIN
LIN = _LOGICAL (Read) If true, the data points will be connected by a line-style polygon. [TRUE]
BIN
BIN = _LOGICAL (Read) If true, the data points will be connected by a bin-style (or histogram-style) polygon. [FALSE]
MARK
MARK = _INTEGER (Read) This parameter determines the kind of marker to be drawn at each data point [0]: - 0: No markers drawn, - 1: Diagonal cross, - 2: Asterisk, - 3: Open circle, - 4: Open square, - 5: Filled circle, - 6: Filled square.
ERROR
ERROR = _LOGICAL (Read) If true and variance information available, error bars will be drawn. [FALSE]
WIDTH
WIDTH = _LOGICAL (Read) If true, the pixel width will be indicated by horizontal bars. [FALSE]
ROMAN
ROMAN = _LOGICAL (Read) If true, PGPLOT’s roman font is used for drawing text. If false, the normal (single-stroke) font is used. [FALSE]
HEIGHT
HEIGHT = _REAL (Read) The height of the characters. This also affects the size of the markers. Markers are about half the size of characters. The height is measured in units of PGPLOT default text heights, which is approximately 1/40 of the height of the (AGI) base picture (i.e. 1/40 the height of the work station window, screen or paper). [1.]
COLOUR
COLOUR = _INTEGER (Read) The PGPLOT colour index to be used for the plot. This can be formally between 0 and 255, but not all devices support all colours. The default colour representation is: - 0: Background, - 1: Foreground (default), - 2: Red, - 3: Green, - 4: Blue, - 5: Cyan, - 6: Magenta, - 7: Yellow, - 8: Orange, - 9: Green/Yellow, - 10: Green/Cyan, - 11: Blue/Cyan, - 12: Blue/Magenta, - 13: Red/Magenta, - 14: Dark grey, - 15: Light grey.
THICK
THICK = _INTEGER (Read) The PGPLOT line thickness. Can be between 1 and 21. [1]
DASH
DASH = _INTEGER (Read) The PGPLOT dash pattern [1]: - 1: Full line, - 2: Long dash, - 3: Dash-dot-dash-dot, - 4: Dotted, - 5: Dash-dot-dot-dot.
AXES
AXES = _CHAR (Read) Array of switches to turn on or off the drawing of either of the four box sides. The sides are counted from bottom clockwise: bottom, left, top, right. Any switch can be "0" or "+". E.g. ’00++’ would switch off the bottom and left axes and switch on the top and right axes. [’++++’]
TICK
TICK = _CHAR (Read) Array of switches to turn on or off the drawing of ticks along either axis. Ticks are drawn only if the corresponding axis is also drawn. The sides are counted from bottom clockwise: bottom, left, top, right. Any switch can be "0", "+" or "-". E.g. ’00+-’ would switch off the bottom and left ticks and switch on the top and right ticks. The top axis would have ticks outward, the right axis would have ticks inward. [’—-’]
NUML
NUML = _CHAR (Read) Array of switches to turn on or off the drawing of numeric labels along either axis. The sides are counted from bottom clockwise: bottom, left, top, right. Any switch can be "0" or "+"; the second and fourth switch can also be "-". E.g. ’0+0-’ would switch off the bottom and top labels and switch on the left and right labels. The left axis would have labels horizontal (orthogonal), the right axis would have labels vertical (parallel). [’++00’]
TEXT
TEXT = _CHAR (Read) Array of switches to turn on or off the drawing of text labels along either axis. The sides are counted from bottom clockwise: bottom, left, top, right. Any switch can be "0" or "+". E.g. ’0++0’ would switch off the bottom and right labels and switch on the left and top labels. [’+++0’]
NORTHO
NORTHO = _REAL (Read) If orthogonal numeric labels have been selected, you must specify how much space there must be between the axis and the text label, i.e. how long the longest numeric label along the left or right axis will be. The unit is character heights. [1]
MAJOR
MAJOR( 2 ) = _REAL (Read) The distance in world coordinates between major tick marks. The first element is for the horizontal direction, the second for the vertical direction. This is also the distance along the axis between numeric labels. Values of 0 cause PGPLOT to choose the major tick interval automatically. [0.,0.]
MINOR
MINOR( 2 ) = _INTEGER (Read) The number of minor tick intervals per major tick interval. The first element is for the horizontal direction, the second for the vertical direction. Values of 0 for MINOR or MAJOR cause PGPLOT to choose the minor tick interval automatically. [0,0]
BOTTOM
BOTTOM = _CHAR (Read) The text label for the first axis. Within the string, you can use the following escape sequences:
  • \fn Normal (single stroke) font,
  • \fr Roman font,
  • \fi Italic font,
  • \fs Script font,
  • \u Superscript (use only paired with \d),
  • \d Subscript (use only paired with \u),
  • \b Backspace,
  • \\Backslash,
  • \A Danish umlaut (Angstroem),
  • \g Any greek letter.
LEFT
LEFT = _CHAR (Read) The text label for the second axis. Within the string, you can use the following escape sequences:
  • \fn Normal (single stroke) font,
  • \fr Roman font,
  • \fi Italic font,
  • \fs Script font,
  • \u Superscript (use only paired with \d),
  • \d Subscript (use only paired with \u),
  • \b Backspace,
  • \\Backslash,
  • \A Danish umlaut (Angstroem),
  • \g Any greek letter.
TOP
TOP = _CHAR (Read) The text label for the third axis. Within the string, you can use the following escape sequences:
  • \fn Normal (single stroke) font,
  • \fr Roman font,
  • \fi Italic font,
  • \fs Script font,
  • \u Superscript (use only paired with \d),
  • \d Subscript (use only paired with \u),
  • \b Backspace,
  • \\Backslash,
  • \A Danish umlaut (Angstroem),
  • \g Any greek letter.
RIGHT
RIGHT = _CHAR (Read) The text label for the fourth axis. Within the string, you can use the following escape sequences:
  • \fn Normal (single stroke) font,
  • \fr Roman font,
  • \fi Italic font,
  • \fs Script font,
  • \u Superscript (use only paired with \d),
  • \d Subscript (use only paired with \u),
  • \b Backspace,
  • \\Backslash,
  • \A Danish umlaut (Angstroem),
  • \g Any greek letter.
DEVICE
DEVICE = DEVICE (Read) The graphics device for the plot.
LABSPC
LABSPC( 4 ) = _REAL (Read) The space between outer box (AGI current picture) and inner box measured in units of character heights. The four numbers are for the bottom, left, top, right labelling space in that order. The dynamic default offered is based on the space requirements for the axis labelling, and can in general be accepted.
WORLD
WORLD( 4 ) = _REAL (Read) The world coordinates that the left, right, bottom and top ends of the inner box should correspond to. The dynamic default is based on the coordinates of the first and last pixel of the selected subset and on the extreme data values of the selected subset. Reverse axes can be achieved by giving WORLD(1) > WORLD(2) and/or WORLD(3) > WORLD(4).
Source comments:
     S P E C P L O T
  
     The plot can basically be an overlay over the most recent data
     picture inside the current picture, or a new plot inside the
     current picture. (The current picture after SPECPLOT is the
     same as before.)
  
     The screen contents of the current picture can be erased or not.
  
     The plot location and size is governed by the outer and the
     inner box. The inner box is the area where data are plotted,
     the outer box contains the inner box and the plot labels.
  
     In the overlay case the inner box and its world coordinates are
     identified with the most recent data picture inside the current
     picture. No labelling is done in the overlay case, so the outer
     box has no meaning in this case.
  
     In the case of a new plot, the outer box will be identified
     with the current picture, although the plot labels are allowed
     to extend beyond this area. Depending on the choice of
     labelling, a sensible location for the inner box is offered.
     After the inner box is specified, its world coordinates are
     enquired. The prompt values correspond to the extreme values
     found in the data. The location and world coordinates of the inner
     box are saved as a data picture in the AGI data base.
  
     The labelling consists of axes, axis ticks, numeric labels at
     the major ticks, and text labels. The axes are counted from
     bottom clockwise. Each axis can be drawn or not. Each
     drawn axis can have ticks or not. Each axis can have numeric
     labels or not. The left and right axes can have either
     horizontal (orthogonal) or vertical (parallel) numeric labels.
     Each axis can have a text label or not.
  
     The kind of labelling is controlled by several 4-character
     strings. Each character is the switch for axis 1, 2, 3, 4
     respectively. "0" turns an option off for that axis, "+" turns
     it on. For the ticks and for numeric labels of axes 2 and 4,
     "-" is also allowed. It yields inward ticks and vertical
     numeric labels.
  
     The data can be plotted as a set of markers, as a line-style
     polygon connecting the data points, or as a bin-style polygon.
     In addition error bars or pixel width bars can be plotted. Each
     of the options can be selected independent of the others, i.e.
     several (or all) options can be selected at the same time. If
     no variance information is available, error bars are de-selected
     automatically. Bad data are omitted from the plot. If error
     bars are selected, bad variances cause the corresponding data
     also to be omitted.
  
     The attributes of the plot can be selected. These are
     -  colour
     -  line thickness
     -  character height (equivalent to marker size)
     -  simple or roman font
     -  dash pattern for polygon connections
  
     Most parameters default to the last used value.
Examples:
  specplot spectrum accept
     This is the simplest way to plot a 1-D data set in its full
     length.
  
  specplot imagerow(-100.:50.,15.) accept
     This will take a 2-D data set IMAGEROW and plot part of the
     row specified by the second coordinate being 15. The part of
     the row plotted corresponds to the first coordinate being
     between -100 and +50. Note that the decimal point forces use of
     axis data. Omitting the period would force use of pixel
     numbers.
  
  specplot imagecol(15.,-100.:50.) accept
     This will take a 2-D data set IMAGEROW and plot part of the
     column specified by the first coordinate being 15. The part of
     the row plotted corresponds to the second coordinate being
     between -100 and +50. Note that the decimal point forces use of
     axis data. Omitting the period would force use of pixel
     numbers.
  
  specplot spectrum lin=false bin=true accept
     Replace direct connections between data points by bin-style
     connections.
  
  specplot spectrum mark=1 accept
     Mark each data point by a diagonal cross.
  
  specplot spectrum error=true width=true accept
     Draw an error bar and a pixel width bar for each data point.
  
  specplot spectrum roman=true height=1.5 colour=3 accept
     Draw text with the roman font, draw text and makers 1.5 times
     their normal size, and plot the whole thing in green colour.
  
  specplot spectrum bottom=Weekday left="Traffic noise [dBA]" accept
     Specify text labels on the command line instead of constructing
     them from the file’s axis and data info.
  
  specplot spectrum overlay=true clear=false accept
     The position and scale of the plot are determined by the
     previous plot (which might have been produced by a different
     application).
  
  specplot spectrum world=[0.,1.,-1.,1.] accept
     Use plot limits different from the extreme data values.
Notes:
This routine recognises the Specdre Extension v. 0.7.

This routine recognises and uses coordinate transformations in AGI pictures.

D.219 SPFLUX-Applies a flux calibration spectrum to an observed spectrum

Description:
SPFLUX takes a spectrum - ideally a scrunched one - and a calib- ration spectrum (usually one produced by CSPIKE and then some interpolation routine) and produces a flux calibrated spectrum.
Parameters:
SPECTRUM
The spectrum to be calibrated. It should be currently in raw counts, preferably scrunched to a linear wavelength scale.
CALSPECT
The calibration spectrum to be applied. Each element of the data should contain the instrumental response, in ’units’ per count per second per angstrom, where ’units’ may be any linear unit, but should not be magnitudes. CALSPECT is usually interpolated from a spiketrum generated by CSPIKE.
OUTPUT
The name of the resulting calibrated spectrum.
Source comments:
   S P F L U X
  
   Applies a flux calibration spectrum (typically generated
   by the sequence CSPIKE, INTERP) to a spectrum, generating
   a flux calibrated spectrum.
  
   Command parameters -
  
   SPECTRUM    (Character) The spectrum to be calibrated.
   CALSPECT    (Character) The calibration spectrum.
   OUTPUT      (Character) The resulting calibrated spectrum.
  
   Commnad keywords -  None
  
   User variables used -  None
  
                                   KS / CIT 16th May 1984

D.220 SPIED-Interactive spiketrum editor

Description:
SPIED allows the user to edit a spiketrum - deleting points and adding new points - in order to control the spectrum obtained by interpolating between the points (e.g. by INTERP or SPIFIT).
Parameters:
SPIKETRUM
The spiketrum to be edited (probably generated either by CSPIKE or by GSPIKE). For more details see HELP FIGARO TECHNIQUES SPIKETRA.
OUTPUT
The name of the resulting edited spiketrum. It may be the same as SPIKETRUM, in which case the result will replace the input in the same file.
COLOUR
The colour for the data to be plotted in. The axes are always plotted in white. The colours allowed are Blue, White, Red, Green, Black, Cyan, Magenta, Yellow. This only works on a colour display, of course. Fitted data will be plotted in the complementary colour
HIGH
The maximum Y value for the plot.
LOW
The minimum Y value for the plot.
XSTART
The maximum X value for the plot.
XEND
The minimum X value for the plot.
ORDER
The order for the polynomial fit.
QUIT
Used to confirm quitting from application.
Source comments:
   S P I E D
  
   SPIketrum EDitor.  Allows the values of a spiketrum to be
   edited interactively, until the user is satisfied with the
   data that results from interpolating between them.
  
   Command Parameters -
  
   SPIKETRUM    (Character) The name of the spiketrum to be
                edited.
   OUTPUT       (Character) The name of the resulting edited
                spiketrum.
   COLOUR       (Character) The colour to be used for the data
                when it is ploted.
   HIGH         (Real) The maximum Y value for the plot.
   LOW          (Real) The minimum Y value for the plot.
   XSTART       (Real) The maximum X value for the plot.
   XEND         (Real) The minimum X value for the plot.
   ORDER        (Integer) The order for the polynomial fit.
  
   Command keywords -
  
   QUIT         Used to confirm quitting from application.
  
   User variables used -    (">" input)
  
   (>) SOFT     (Character) The device/type of the current soft
                graphics device.
  
                                      KS / CIT 23rd May 1984

D.221 SPIFIT-Fits a global polynomial to a spiketrum to form a spectrum

Description:
SPIFIT interpolates between the points of a ’spiketrum’ - an array where most of the data is zero except for a few elements whose values are set - to produce a spectrum. Interpolation is by fitting a global polynomial to the data points.
Parameters:
SPIKETRUM
The name of the spiketrum - an array where only a few elements are set to the correct values, the other elements all being zero - which is to be used to produce a spectrum by interpolation between those specified elements. SPIKETRUM has probably been produced by GSPIKE from a table of values.
ORDER
The order of polynomial to be fitted to the points of the spiketrum.
SPECTRUM
The name of the spectrum to be produced by interpolation between the points of the spiketrum.
LOG
It doesn’t usually make much difference whether you fit to the log of the data or to the data itself, but if the data is changing very rapidly, particularly at the ends, the fit may be better constrained if the log is used.
Source comments:
   I N T E R P    /     S P I F I T    /   L I N T E R P
  
   Interpolates between the points of a ’spiketrum’ to
   generate a spectrum.   The INTERP command does this by
   spline interpolation, the SPIFIT command uses global polynomial
   fitting, and the LINTERP command uses linear interpolation.
  
   Command parameters -
  
   SPIKETRUM  The name of the structure containing the spiketrum
  
   ORDER      The order for the global polynomial to be fitted
              (SPIFIT only).
  
   SPECTRUM   The name of the result of the operation.  This can
              be the same as for SPIKE.  If not, a new structure
              is created, with everything but the data a direct
              copy of the input.
  
   Command keywords  -
  
   LOG        (INTERP & SPIFIT only) Perform the interpolation on
              the log of the data
  
   LINEND     (INTERP only) Use a linear interpolation for the
              ends of the data - spline fits can go wild outside the
              range of the defined points.
  
   User variables used - None
                                    KS / CIT 6th July 1984

D.222 SPLOT-Plots a spectrum

Description:
The SPLOT command will plot a spectrum on the current hard or soft graphics device.
Parameters:
SPECTRUM
The name of the spectrum to be plotted by SPLOT. It should be a 1-dimensional array.
HARDCOPY
If set, the plot is written to the device defined as the current hardcopy device. Generally, this is a disk file which will then have to printed. If HARDCOPY is not set, the plot will go to the current softcopy device. The hard and soft copy devices are specifed using the HARD and SOFT commands respectively.
WHOLE
If set, the whole of the spectrum is plotted. Otherwise, the limits plotted are determined by the values of XSTART and XEND, which you will be prompted for if they were not specified in the command string.
AUTOSCALE
If set, the plot is scaled so that all of the data to be plotted just fits on the display. Otherwise, the scale of the plot is determined by the values of HIGH and LOW, which you will be prompted for if they were not specified in the command string.
XSTART
The first X value to be plotted, in the units used by the data - angstroms, for example, if the data is wavelength calibrated. XSTART can be set before the start of the data, if necessary. RESET will set XSTART to the first X value in the data.
XEND
The last X value to be plotted, in the units used by the data - angstroms, for example, if the data is wavelength calibrated. XEND can be set after the end of the data, if necessary. RESET will set XEND to the last X value in the data.
HIGH
The maximum data value to be plotted - i.e. the top Y axis value for the plot.
LOW
The minimum data value to be plotted - i.e. the bottom Y axis value for the plot.
BIAS
A bias value applied to the data, usually to bias up a plot which is to be superimposed upon a previous plot of almost identical data values. This makes the comparison easier. BIAS N is essentially equivalent to setting HIGH and LOW down by an amount N, so can result in unexpected axis values if it is not accompanied by AXES=NO.
LABEL
The label that will appear at the top of the plot.
ERASE
Specifies that the screen is to be erased before the plot is made. Usually ERASE and AXES will not be set when a plot is superimposed on a previous one.
AXES
Specifies that the axes for the plot are to be drawn. These should be omitted if the plot is being superimposed on a previous one, or sometimes just to save plotting time.
LINES
Specifies that the plot is to made as a ’point-plot’, in a ’join the dots’ fashion. The alternative is a histogram plot. LINES will usually be a little faster, but messier, because the resolution of the plotting device will result in stepped lines.
COLOUR
The colour the data are to be plotted in. The axes are always plotted in white. The colours allowed are Blue, White, Red, Green, Black, Cyan, Magenta, Yellow. Using Black will have the effect of erasing anything where the data is plotted. This only works on the Grinnell.
THICKNESS
Only used for ’build’ or ’hard’ plots. It is used to increase the thickness of the lines plotted in order to increase legibility, particularly on the Versatec. Generally 1 or 3 is reasonable for the Versatec - depending on how well set up it is at the present, and 1 should be used for other devices.
See also:
FIGARO: ESPLOT, IPLOTS, MSPLOT.
KAPPA: LINPLOT, MLINPLOT.
Source comments:
   S P L O T    /    E S P L O T
  
   Produces a plot of a spectrum.  The plot is directed
   to the device defined by the user variables ’SOFT’ and
   ’HARD’, and by the value of the command keyword ’HARDCOPY’,
   so will appear immediately if these specify a video
   device (VT125, Args, etc.).  If a hardcopy device
   is specified, the file for that device will be produced,
   but SPLOT does not attempt to spool it off for printing.
  
   ESPLOT is similar to SPLOT, but plots error bars based on the
   errors in the data.
  
   Command parameters -
  
   SPECTRUM    The data to be plotted.  If this contains X-axis
               information, this will be used.  If not, the X-axis
               will just have to be the numbers from 1 to n.
   XSTART      The x-value at which plotting is to start.
   XEND        The x-value at which plotting is to end.
               (XSTART and XEND are not required if the
               WHOLE keyword is set.)
   HIGH        The maximum value to be used for the plot.
   LOW         The minimum value to be used for the plot.
   BIAS        A value used to displace the plot - BIAS is
               effectively a value added to the data before
               it is plotted. (It is implemented as a value
               subtracted from both HIGH and LOW.)
               (HIGH,LOW and BIAS are not required if the
               AUTOSCALE keyword is set.)
   LABEL       A label for the plot.
   COLOUR      The colour for the plot, assuming the display device
               supports it.  The axes are always white.
   THICKNESS   The width of the lines used for the plot.  This is
               only used for ’hard’ & ’build’ plots, and should
               really be 1 for anything other than a high-resolution
               device like a Versatec or a laser printer.
  
   Command keywords -
  
   AUTOSCALE   The program is to work out the values for HIGH
               and LOW, using the maximum and minimum values
               in the data over the specified range.
   WHOLE       The program is to display all of the spectrum.
   HARDCOPY    The plot is to produce a hard copy.
   AXES        Axes will be plotted.
   ERASE       The screen will be erased before the plot.
   LINES       The plot is not done as a histogram, but as
               a ’join the dots’ line plot.  (Only applies
               to SPLOT.)
  
   User variables -    (">" input, "<" output)
  
   (>) SOFT    Specifies the device and type to be used for soft
               plots.  See the SOFT command for more details.
   (>) HARD    Specifies the device and type to be used for hard
               plots.  See the HARD command for more details.
   (<) TVXST   is set to the starting x-value for the plot.
   (<) TVXEN   Is set to the final x-value for the plot.
   (<) TVHIGH  Is set to the same value as HIGH.
   (<) TVLOW   Is set to the same value as LOW.
   (<) TVFILE  Is set to the value of SPECTRUM.
   (<) TVCOLOR Is set to the GRPCKG code for the plot colour.
               (The TV.. variables are intended for use by
               cursor routines, and reflect the settings for the
               last plot made, even if XSTART etc are changed.)
  
   (Other user variables may be set by the command processor, in
   connection with the parameter values.)
  
                                       KS / CIT  30th April 1984

D.223 SQRTERR-Generates an error array as Error = Square Root of (Data/Const)

Description:
SQRTERR produces an error array, given a data array and a constant. Each element of the data array is calculated as the square root of the equivalent element of the data array, after division by a specified constant factor.
Parameters:
IMAGE
The name of the file containing the data for which an error array is to be caluclated. The data can have any dimensions. If there is already an error array, its contents are replaced.
FACTOR
Calculating the errors as just the square root of the data is OK only for certain types of data, such as raw data from photon counting detectors. For this type of data, FACTOR should be set to 1.0. Some other types of data, such as raw data from CCD detectors, can be handled if the data value is first divided by a constant factor - the data number per photon value (or ADU/photon value). Other types of data should not be treated using this routine, in general.
OUTPUT
The name of the resulting image. This can be the same as the input image, in which case the error array is added to the original image, or different, in which case a new file containing an error array is created.
Source comments:
   S Q R T E R R
  
   Sets an error array for which the value of each element is
   given by the square root of the corresponding data array
   element.  Optionally, the data array element value may be divided
   by a specified constant before the square root is taken.  The
   case where the constant is 1 is suitable for data such as
   photon-counting data is being used.  For CCDs and similar devices,
   the constant should be equal to the ADU/photon value.
  
   Command parameters -
  
   IMAGE  (Character) The name of the structure containing the image.
  
   FACTOR (Numeric) The value of the constant by which the data
          values are divided before the square root is taken.
  
   OUTPUT (Character) The name of the result of the operation.  This
          can be the same as for IMAGE.  If not, a new structure
          is created, with everything but the error array a direct
          copy of the input.
                                    KS / AAO 8th Jan 1987

D.224 SUBSET-Take a subset of a data set.

Usage:

subset in out

Description:

Takes a rectangular subset of a data set. The given data set and the resulting subset may have up to seven axes. Axes that become degenerate by sub-setting - i.e. along which only one pixel is chosen - are deleted from the subset. Thus the subset may have smaller dimensionality than the original.

Parameters:
IN
IN = NDF (Read) The input file.
OUT
OUT = NDF (Read) The output file.
Examples:
  subset in(1.5:2.5,10:12) out
     This takes the data from IN and writes the subset to OUT. The
     subset is specified as having 1st axis coordinates between 1.5
     and 2.5 and 2nd axis pixel numbers between 10 and 12.
Notes:
This routine recognises the Specdre Extension v. 0.7.

D.225 TABLE-List contents of a SPICA memory file

Description:
This function produces a list of a SPICA memory file contents on the screen, and in a file. If required, the file may then be printed.
Parameters:
FILE
The name of the SPICA Memory file from which the records are to be listed. The name of the file should be given in full - e.g. ’ABCD1D.DAT’. The Memory file can be 1-D or 2-D.
PRINT
If set, the table will be printed on the default printer queue. Default is PRINT=NO.
DELETE
If set, the table will be deleted at the end or after printing. If DELETE is not set, the table will be saved in the file TABLE.LIS in the default directory. Default is DELETE=YES.
Source comments:
   T A B L E
  
    This function produces a list of a SPICA memory file contents
    on the screen, and in a file. If required, the file may then
    be printed. The command is TABLE
  
    With parameter
  
    FILE     name of SPICA memory file
  
    With keywords
  
    PRINT=NO   specifies that the list is not to be printed (D)
    PRINT=YES  that the list is to be printed
  
    DELETE=NO  that the listing file is to be kept
    DELETE=YES that the listing file is to be deleted (D)
  
  
    SUBROUTINES AND FUNCTIONS CALLED :
  
    ICH_LEN - (F) Looks for position of last non space in a string
    INDSORT - Sorts index records                     (from SPSUBS)
    PAR_WRUSER  - Writes a string to the terminal
    PAR_RDCHAR  -
    PAR_RDKEY   -
    GEN_FORTERR -
    FIG_SETERR  -
  
  
    VARIABLES AND PARAMETERS :
  
    DESREC : Desired record
    HEADER : Array holding entry header
    I, J   : Loop counters
    LABEL  : Label of memory file entry
    LISLU  : (P) LU on which listing file is opened
    MEMLU  : (P) LU on which the memory file is opened
    MEMORY : Memory file name
    NI     : Number of channels in the data
    NL     : Number of X sections in the data
    NUMBER : Index entry number
    RLVAL  : General REAL variable
    STATUS : Status return
    STRING : Output string
    WSTAT  : Dummy status for PAR_WRUSER
  
  
    Programmer :  S. A. Morris            Date :  21-APR-1983
    Modified to sort the records    Alan Bridger  21-SEP-1983
    Modified for FIGARO environment     P.W.Hill  16-MAR-1986

D.226 TIPPEX-Modify individual pixel values with cursor

Description:
Modifies individual pixel values with cursor.
Parameters:
OUTPUT
The name of the output file to be created. If this is the same as the displayed spectrum, the data in the displayed spectrum will be modified.
CONFIRM
Used to confirm change to data.
QUIT
Used to confirm quitting application.
See also:
FIGARO: CSET, ICSET, NCSET.
KAPPA: CHPIX, FILLBAD, SEGMENT, NOMAGIC, SETMAGIC, ZAPLIN.
Source comments:
   T I P P E X
  
   Figaro function to modify a displayed spectrum using the
   cursor.
  
   Command parameters -
  
   OUTPUT      (Character) The name of the output file to
               be created.  If this is the same as the displayed
               spectrum, the data in the displayed spectrum will
               be modified.
  
   Command keywords -
  
   CONFIRM     Used to confirm change to data.
   QUIT        Used to confirm quitting application.
  
   User variables used -  (">" input, "<" output)
  
   (>) TVFILE  The name of the displayed spectrum
   (>) TVXST   The first displayed x-value
   (>) TVXEN   The last displayed x-value
   (>) TVHIGH  The maximum displayed y-value
   (>) TVLOW   The minimum displayed y-value
   (>) TVCOLOR The GRPLOT code for the plot colour
   (>) SOFT    The device/type string defining the display device
  
                                            KS / CIT 25th May 1983

D.227 TRIMFILE-Creates a copy of an HDS file without unused space

Usage:
trimfile in out
Description:
Certain changes to HDS files may cause them to contain unused space, deleted or temporary structures, etc. This routine will create a new copy of the file which will only contain actually used structures. This is in fact only a call to HDS_COPY.
Parameters:
IN
The HDS file suspected to contain a lot of garbage. The default extension is .sdf. For other extensions use the @-sign and double quotes as in @"file.dst".
OUT
The name of the new, clean copy of the HDS file. The default extension is .sdf. For other extensions just specify them as in file2.dst or "file2.dst", but not @"file2.dst".
Authors:
KS: Keith Shortridge (AAO)

HME: Horst Meyerdierks (UoE, Starlink)

D.228 VACHEL-Air to vacuum, and/or recession velocity wavelength conversion

Description:
VACHEL provides facilities for conversion of the X-array (wave- length) from air to vacuum values, and/or correction of the wavelengths for the effects of a Doppler shift (e.g. to correct from observed to heliocentric velocity frame).
Parameters:
IMAGE
The name of the image (or spectrum) whose X values are to be converted. IMAGE must already have a valid X-array.
OUTPUT
The name of the resulting image (or spectrum). If this is the same as IMAGE, the original file will be modified. Otherwise, a new file will be created.
VEL
The recession velocity in Km/s whose effects will be removed by this routine. Use a negative VELOCITY to correct for a velocity of approach.
VAC
If VAC is set, the input wavelengths will be assumed to be in air, and will be converted to vacuum values. The input wavelengths must be in Angstroms for this to give the correct result. The resulting wavelength scale will be (slightly) non-linear due to the wavelength dependence of the refractive index of air. Therefore it is generally advisable to rescrunch after use of this correction.
DPLR
If DPLR is set, the input wavelengths will be corrected for the effects of a recession velocity of VEL Km/S.
Source comments:
   V A C H E L
  
   VACHEL alters the wavelength (X) structure, to convert it from
   air to vacuum wavelengths, and to correct for a recession velocity
   (user supplied value).  Usually (but not necessarily) the velocity
   will be the recession velocity required to correct from observed
   wavelengths to heliocentric. The velocity correction uses the
   relativistic formula.
       Either or both of the vacuum and recession corrections may be
   applied in the one run.
       The resulting X structure will be (slightly) non-linear, due
   to the wavelength dependence of the refractive index of air. It
   will therefore generally be advisable to rescrunch after use of
   this routine.  An exception is if only a recession correction is
   made: this leaves a linear scale (if the input is linear).
       The input wavelength (X) data must be in Angstroms for the
   air to vacuum conversion to work correctly.
  
  
   Command parameters -
  
   IMAGE  (Character) The name of the structure containing the image.
   VEL    (Float) Recession velocity for which wavelength is to be
          corrected
   OUTPUT (Character) The name of the result of the operation.  This
          can be the same as for IMAGE.  If not, a new structure
          is created, with everything but the x-data a direct
          copy of the input.
  
   Command keywords -
  
   VAC=YES  Correction from air to vacuum is to be made
   VAC=NO   No correction from air to vacuum is to be made
   DPLR=YES Correction for (+ or -) recession velocity is to
            be made
   DPLR=NO  No velocity correction
  
                                    JGR  July 1985

D.229 VIG-Corrects a 2D array for vignetting

Description:
This routine accepts a sky or flat field IMAGE obtained at the same filter for imaging , or at the same grating angle as a series of spectra which need to be corrected for vignetting in 2D. Two orthogonal one dimensional cuts through the 2D IMAGE are formed and fitted with Chebyshev polynomials to form flattening functions on the respective axes. The correction applied to the data is formed from the product of the terms of each of these two series. Because the correction IMAGES may include unwanted signals, such as sky lines the users can specify regions of the data which may be excluded from the fits. In practice rather actaully restructure the template cuts formed in the two directions,by deleteing these data this is achieved by ascribing them a very low weight in the fitting process. At the current time it has been found that a wright of 1E-6 is an effective way of elimanting such points.
Parameters:
IMAGE
IMAGE = FILE (Read) Name of image for input
OLD
OLD = LOGICAL (Read) old coefficients are to be used for correction
OUTPUT
OUTPUT = FILE (Write) OUTput Name of output file OUTPUT is the name of the resulting image. If OUTPUT is the same as INPUT the data in the input file will be modified in situ.Otherwise a new file will be created.
YSTART
YSTART = INTEGER (Read) start value to extract in channel direction The data between the limits ystart and yend is extracted and the resultant spectrum is used to find the vignetting in the channel direction.
YEND
YEND = INTEGER (Read) end value to extract in channel direction The data between the limits ystart and yend is extracted and the resultant spectrum is used to find the vignetting in the channel direction.
XSTART
XSTART = INTEGER (Read) start value to extract in x-sect direction The data between the limits xstart and xend is extracted and the resultant spectrum is used to find the vignetting in the cross-section direction.
XEND
XEND = INTEGER (Read) end value to extract in x-sect direction The data between the limits xstart and xend is extracted and the resultant spectrum is used to find the vignetting in the cross-section direction.
Source comments:
    none available
  

D.230 WDFITS-Writes an image out in the AAO de facto ’Disk FITS’ format

Description:
WDFITS writes a Figaro image out in the AAO de facto standard ’Disk FITS’ format. This is used at the AAO for archiving of data, and is a byte-swapped, 2880 byte record, format.
Parameters:
IMAGE
The name of the image to be written out to a disk file in the ’Disk FITS’ format. The data written out will be the main image in the file, and any subsidiary information held in a .FITS structure that is not an array. Not all the information held in a general Figaro file can be written out, since the Figaro format is a superset of that used by FITS.
FILE
The name of the ’Disk FITS’ format file that will be created by WDFITS.
BIT16
Normally, WDFITS writes real data (FLOAT or DOUBLE arrays) as 32 bit integers in order to preserve the maximum amount of precision. However, to conserve space, it is possible to specify BIT16, in which case the data will be written as 16 bit integers. In both cases, a BSCALE a BZERO value will be used to scale the real data to make maximum use of all the 32 or 16 bits.
See also:
FIGARO: RDFITS, FITSKEYS.
KAPPA: FITSDIN, FITSIN, FITSHEAD, FITSIMP, FITSLIST.
CONVERT: NDF2FITS.
Source comments:
   W D F I T S
  
   Name:
      WDFITS
  
   Function:
      Writes a Figaro image out to disk in FITS format.
  
   Description:
      Writes a Figaro image out to disk in FITS format.  Since the
      Figaro format is a superset of FITS, not all the information
      held in the Figaro file can be written to tape, so this
      routine concentrates on the main data array.  This means that
      it is really only suitable for images with no associated
      calibration data.  If the file has axis structures that
      contain linear data arrays, these will be converted into the
      appropriate CDELTn, CRPIXn and CRVALn keywords.  Non-linear axis
      data will be ignored. The only other information written into
      the FITS header will be taken from the FITS-specific data
      structure, should the structure contain one.  Any entries in this
      structure that can reasonably be output as header quantities (arrays
      of data cannot) will be.
  
      If the end of the tape is reached while the data is being written,
      the tape is backspaced to the start of the image data and an
      end of tape mark is written.  The user is then given the option
      of mounting a new tape and repeating the output.  Note that the
      ’standard’ FITS recipie for handling end of tape - which allows
      images to span tapes - is not followed.  In batch mode the user
      is not given this option.
  
      This program serves for the command WDFITS, which writes
      an image out in the AAO de facto ’Disk Fits’ format - i.e. to a
      disk file whose 2880 byte records are exactly the same as the
      records on a FITS tape would be, except that the data is not
      byte-swapped.
  
   Parameters:
      IMAGE     (Character) The file containing the Figaro data
                structure to be written to disk.
      FILE      (Character) The name of the
                disk file to which the data is to be written.
  
   Keywords:
      BIT16     Forces real data to be written out as 16 bit rather
                than as 32 bit data.
  
   User variables used:    (">" input, "<" output)
  
   Keith Shortridge, AAO.

D.231 WDIPSO-Writes a file in DIPSO/IUEDR/SPECTRUM format

Description:
WDIPSO creates a copy of a specified Figaro file in the SPECTRUM format used by DIPSO.
Parameters:
SPECTRUM
The name of the Figaro file to be output in a format DIPSO can read. It should contain one- dimensional data, wavelength calibrated.
CODE
There are three SPECTRUM formats used by DIPSO, and WDIPSO can handle any of them. Type 0 is unformatted, and is the most compact and fastest to use, but cannot be read as a text file. Type 1 is a fixed format text file, and type 2 is a free-format text file. Unless it is important that a readable text file be produced, type 0 is probably the best format to use. Type 1 output is easier to read that type 2, but more prone to rounding errors due to the fixed format.
FILE
The name of the DIPSO file to be created. If no extension is specified, .DAT will be used.
Source comments:
   W D I P S O
  
   Writes a copy of a Figaro file in DIPSO/IUEDR format.  The file
   can be written in any of what IUEDR calls SPECTRUM type 0, type 1
   or type 2 format.
  
   Command parameters -
  
   SPECTRUM  (Character) The name of the Figaro file to be converted.
   CODE      (Numeric) The type code for the format used.
   FILE      (Character) The name of the DIPSO format file to be
             created.
  
   Command keywords -  None
                                             KS / AAO 10th Oct 1986

D.232 XCADD-Adds a constant to the X data in a file

Description:
Adds a constant to the X-axis values of the datafile.
Parameters:
IMAGE
Image with X data to be added to.
FACTOR
Additive constant.
OUTPUT
Name of resulting image.
Source comments:
   I C O N S T
  
   This routine is the main body of ICMULT,ICDIV,ICADD and ICSUB,
   and of XCMULT, XCDIV, XCADD and XCSUB.  The Ixxxx routines
   operate on the data in an image, the Xxxx routines operate on
   the data in the X array of the input file.
   ICMULT multiplies an image by a constant.  Since the constant
   can be less than 1., this function will also divide an
   image by a constant, but ICDIV saves the caller from having
   to calculate a reciprocal. ICADD adds a constant to an image and
   ICSUB subtracts a constant from an image.
  
   Command parameters -
  
   IMAGE  (Character) The name of the structure containing the image.
          Uses main data array, or the x-axis data for the XCxxx routines.
  
   FACTOR (Numeric) The value of the constant factor.
  
   OUTPUT (Character) The name of the result of the operation.  This
          can be the same as for IMAGE.  If not, a new structure
          is created, with everything but the data a direct
          copy of the input.
  
   The command name is used to distinguish between the
   possible operations.
                                    KS / CIT 12th June 1984

D.233 XCDIV-Divides the X data in a file by a constant

Description:
Dividies the X-axis values of the datafile by a constant.
Parameters:
IMAGE
Image with X data to be divided.
FACTOR
Constant.
OUTPUT
Name of resulting image.
Source comments:
   I C O N S T
  
   This routine is the main body of ICMULT,ICDIV,ICADD and ICSUB,
   and of XCMULT, XCDIV, XCADD and XCSUB.  The Ixxxx routines
   operate on the data in an image, the Xxxx routines operate on
   the data in the X array of the input file.
   ICMULT multiplies an image by a constant.  Since the constant
   can be less than 1., this function will also divide an
   image by a constant, but ICDIV saves the caller from having
   to calculate a reciprocal. ICADD adds a constant to an image and
   ICSUB subtracts a constant from an image.
  
   Command parameters -
  
   IMAGE  (Character) The name of the structure containing the image.
          Uses main data array, or the x-axis data for the XCxxx routines.
  
   FACTOR (Numeric) The value of the constant factor.
  
   OUTPUT (Character) The name of the result of the operation.  This
          can be the same as for IMAGE.  If not, a new structure
          is created, with everything but the data a direct
          copy of the input.
  
   The command name is used to distinguish between the
   possible operations.
                                    KS / CIT 12th June 1984

D.234 XCMULT-Multiplies the X data in a file by a constant

Description:
Multiplies the X-axis values of the datafile by a constant.
Parameters:
IMAGE
Image with X data to be multiplied.
FACTOR
Multiplicative constant.
OUTPUT
Name of resulting image.
Source comments:
   I C O N S T
  
   This routine is the main body of ICMULT,ICDIV,ICADD and ICSUB,
   and of XCMULT, XCDIV, XCADD and XCSUB.  The Ixxxx routines
   operate on the data in an image, the Xxxx routines operate on
   the data in the X array of the input file.
   ICMULT multiplies an image by a constant.  Since the constant
   can be less than 1., this function will also divide an
   image by a constant, but ICDIV saves the caller from having
   to calculate a reciprocal. ICADD adds a constant to an image and
   ICSUB subtracts a constant from an image.
  
   Command parameters -
  
   IMAGE  (Character) The name of the structure containing the image.
          Uses main data array, or the x-axis data for the XCxxx routines.
  
   FACTOR (Numeric) The value of the constant factor.
  
   OUTPUT (Character) The name of the result of the operation.  This
          can be the same as for IMAGE.  If not, a new structure
          is created, with everything but the data a direct
          copy of the input.
  
   The command name is used to distinguish between the
   possible operations.
                                    KS / CIT 12th June 1984

D.235 XCOPI-Like XCOPY but interpolates X-data from 2 files

Description:
The main use of this task is to set the axis data in a data file to values intermediate between those of two other files. Typically, the first file will be a spectrum, the others will be arcs taken either side of the spectrum. The whole axis structure from the first ’arc’ file replaces that from the original file, and then the axis data array is modified to give the required intermediate result.
Parameters:
SPECTRUM
File requiring X data.
ARC
File containing X data.
ARC2
Second file containing X data.
FRACTION
Fraction in the relationship:

X data OUTPUT=ARC+(ARC2-ARC1)*FRACTION.

OUTPUT
Name of resulting file.
Source comments:
   X C O P I
  
   The main use of this routine is to set the axis data in
   a data file to values intermediate between those of
   two other files.  Typically, the first file will be a
   spectrum, the others will be arcs taken either side
   of the spectrum.  The whole axis structure from the first
   ’arc’ file replaces that from the original file, and then
   the axis data array is modified to give the required
   intermediate result.
  
   Command parameters -
  
   SPECTRUM    (Character) The file name of the spectrum whose
               data is to be combined with the axis data from the
               arcs.
  
   ARC         (Character) The file name of the arc spectrum - i.e.
               the spectrum whose axis information is to be used.
  
   ARC2        (Character) The file name of the second arc
               spectrum whose axis array is to be used.
  
   FRACTION    (Numeric) The fractional value controlling the
               weight given to the different arc data arrays.
               If 0., the output data is the same as for ARC,
               and the simpler XCOPY routine should be used.
               If 1., the output data is the same as for ARC2.
               If .5, the output is the average of the two arcs.
               Etc.
  
   OUTPUT      (Character) The file name for the resulting data
               structure.  If this is the same as SPECTRUM, the
               axis data in SPECTRUM will be changed in situ.
  
   Command keywords - None
  
   User variables used - None
  
                                           KS / CIT 1st July 1983

D.236 XCOPY-Copy X-info (e.g. wavelengths) into a spectrum

Description:
Copies the axis information from one datafile (typically an arc) into another (typically some other spectrum). The result is either a modified version of the second datafile, or a new datafile.
Parameters:
SPECTRUM
File requiring X data.
ARC
File containing X data.
OUTPUT
Name of resulting file.
Source comments:
   X C O P Y
  
   Copies the axis information from one Figaro data structure
   (typically an arc) into another data structure (typically
   some other spectrum).  The result is either a modified version
   of the other data structure, or a new structure.
  
   Command parameters -
  
   SPECTRUM    (Character) The file name of the spectrum whose
               data is to be combined with the axis data from the
               arc.
  
   ARC         (Character) The file name of the arc spectrum - i.e.
               the spectrum whose axis information is to be used.
  
   OUTPUT      (Character) The file name for the resulting data
               structure.  If this is the same as SPECTRUM, the
               axis data in SPECTRUM will be changed in situ.
  
   Command keywords - None
  
   User variables used - None
  
                                           KS / CIT 7th June 1983

D.237 XCSUB-Subtracts a constant from the X data in a file

Description:
Subtracts a constant value from each X-axis value in a datafile.
Parameters:
IMAGE
Image with X data to be subtracted from.
FACTOR
Constant to be subtracted from data.
OUTPUT
Name of resulting image.
Source comments:
   I C O N S T
  
   This routine is the main body of ICMULT,ICDIV,ICADD and ICSUB,
   and of XCMULT, XCDIV, XCADD and XCSUB.  The Ixxxx routines
   operate on the data in an image, the Xxxx routines operate on
   the data in the X array of the input file.
   ICMULT multiplies an image by a constant.  Since the constant
   can be less than 1., this function will also divide an
   image by a constant, but ICDIV saves the caller from having
   to calculate a reciprocal. ICADD adds a constant to an image and
   ICSUB subtracts a constant from an image.
  
   Command parameters -
  
   IMAGE  (Character) The name of the structure containing the image.
          Uses main data array, or the x-axis data for the XCxxx routines.
  
   FACTOR (Numeric) The value of the constant factor.
  
   OUTPUT (Character) The name of the result of the operation.  This
          can be the same as for IMAGE.  If not, a new structure
          is created, with everything but the data a direct
          copy of the input.
  
   The command name is used to distinguish between the
   possible operations.
                                    KS / CIT 12th June 1984

D.238 XCUR-Uses cursor to delimit part of a spectrum

Description:
If a spectrum has been displayed on the current soft display device, XCUR allows the user to delimit a range of it in X using the cursor. The sequence ’SPLOT parms’, ’XCUR’, ’SPLOT ẃill result in the display of the delimited part of the spectrum.
Source comments:
   X C U R
  
   Uses the graphics cursor to delimit a range in X,
   setting the user variables XSTART and XEND accordingly.
  
   Command variables / keywords - None.
  
   User variables -     (">" input, "<" output)
  
   (>) SOFT     (Character) Device / type for soft plots.
                See documentation on ’SOFT’ command for
                details.
   (>) TVXST    (Numeric) X-start value for current plot.
   (>) TVXEN    (Numeric) X-end value for current plot.
   (>) TVLOW    (Numeric) Lowest value of current plot.
   (>) TVHIGH   (Numeric) Highest value of current plot.
   (<) XSTART   (Numeric) X-start for next plot.
   (<) XEND     (Numeric) X-end for next plot.
  
                                KS / CIT 26th July 1982

D.239 XTPLANE-Adds XT planes of a data cube to form an image

Description:
Given a data cube (strictly a cuboid) XTPLANE extracts a 2-D image from it by adding together a number of planes of constant Y.
Parameters:
CUBE
The name of a 3-dimensional data cuboid, from which XTPLANE is to extract a 2-D image by adding together contiguous planes of constant Y value, the Y dimension being the second dimension of the data.
YSTART
The Y value of the first of the planes to be added together to form the extracted image. If the Y axis of the cube is calibrated, YSTART must be specified in the units in which it is calibrated. Otherwise, the element number (1..N) should be used.
YEND
The Y value of the last of the planes to be added together to form the extracted image.
IMAGE
The name of the 2-D image to be created by XTPLANE.
Source comments:
   Y T P L A N E ,   X T P L A N E,    X Y P L A N E
  
   Adds a number of consecutive planes from a cube to
   produce a 2-D data object.  YTPLANE, XTPLANE and XYPLANE
   take planes whose X,Y or T values respectively are
   constant over the extracted plane.  (Pedantic note:
   strictly, a cuboid is meant, rather than a cube.)
   (Further pedantic note: the X, Y and T axes
   mentioned in this routine should really be referred to
   as AXIS(1), AXIS(2) and AXIS(3) respectively. However,
   explanations become confusing if this is done, so the references to
   X, Y and T remain. This does not mean that the data is stored in
   .X .Y and .T structures - JM.)
  
   Command parameters -
  
   ’CUBE’     The name of the cube from which the planes
              are to be taken.
  
   ’XSTART’   The X,Y, or T-value of the first plane to be used.
   ’YSTART’   If CUBE has a X, Y or T  structure, the data
   ’TSTART’   from this is used.  If not, the plane numbers
              are used, starting from 1.
  
   ’XEND’     The X, Y, or T-value of the last plane to be used.
   ’YEND’
   ’TEND’
  
   ’IMAGE’    The name of the resulting data structure.
  
   Input data -
  
   CUBE - 3-D data-array
  
   Output data -
  
   IMAGE is created with the same structure as CUBE
   except that the data array will only have 2 dimensions, and if
   CUBE has a X,Y or T structure, this will be omitted -
   that is, XPLANE will omit any X structure, YPLANE any
   Y structure and  etc.
                                   KS / AAO 8th Jan 1985

D.240 XTRACT-Average an N-dimensional cube into an (N-M)-dimensional one.

Usage:

xtract in colaps out

Description:

This routine reduces the number of axes of a data set by averaging pixels along some axes while retaining other axes. A simple and common example is averaging all or a certain range of rows (or columns) of an image to create a single row, e.g. an averaged spectrum from a 2-D slit spectrum. Input pixels with bad or zero variance are treated as bad, i.e. disregarded in the averaging (unless NOVAR is true).

Parameters:
INFO
INFO = _LOGICAL (Read) If false, the routine will issue only error messages and no informational messages. [YES]
VARUSE
VARUSE = _LOGICAL (Read) If false, data variance in the input is ignored and output variance is calculated from the scatter of averaged values. If true, data variance in the input is used to weight mean values and to calculate output variance. [YES]
IN
IN = NDF (Read) Input file.
COLAPS
COLAPS( 7 ) = _INTEGER (Read) For each axis in IN a 0 indicates that the axis is to be retained in OUT, a 1 indicates that along that axis pixels from IN are to be averaged.
OUT
OUT = NDF (Read) Output file, containing the extracted data set.
Examples:
  xtract cube(-30.:30.,1.5:2.5,10:20) [0,0,1] xyplane
     This first takes a subset from the 3-D data cube extending
     from -30 to +30, 1.5 to 2.5, 10 to 20 along the 1st, 2nd, 3rd
     axes respectively. (Coordinates are used along the 1st and 2nd
     axes, pixel indices along the 3rd.) From that sub-cube all the
     x-y-planes are averaged to create a 2-D image.
     (E.g. this averages the channel maps between 10 and 20 into an
     integrated map.)
  
  xtract cube(-30.:30.,1.5:2.5,10:20) [1,1,0] spectrum
     This averages each x-y-plane into a single point of the output
     row. The subset used is the same as above. (E.g. this averages
     the cube of channel maps into a mean spectrum.)
  
  xtract image(-30.:30.,1.5:2.5) [0,1] spectrum info=no varuse=no
     This averages all rows between 1.5 and 2.5 into a spectrum. The
     spectrum extends from -30 to +30. Informational messages are
     suppressed, and data variances in the image are ignored. The
     variances in the spectrum are calculated from the row-to-row
     scatter in each column.
Notes:
This routine recognises the Specdre Extension v. 0.7. However, no extraction is performed on NDFs in the input Specdre Extension. If the spectroscopic axis is retained, then the scalar components in the Extension are propagated. If the spectroscopic axis is collapsed, the Extension is not propagated at all.

D.241 XYPLANE-Adds XY planes of a data cube to form an image

Description:
Given a data cube (strictly a cuboid) XYPLANE extracts a 2-D image from it by adding together a number of planes of constant T.
Parameters:
CUBE
The name of a 3-dimensional data cuboid, from which XYPLANE is to extract a 2-D image by adding together contiguous planes of constant T value, the T dimension being the third dimension of the data.
TSTART
The T value of the first of the planes to be added together to form the extracted image. If the T axis of the cube is calibrated, TSTART must be specified in the units in which it is calibrated. Otherwise, the element number (1..N) should be used.
TEND
The T value of the last of the planes to be added together to form the extracted image.
IMAGE
The name of the 2-D image to be created by XYPLANE.
Source comments:
   Y T P L A N E ,   X T P L A N E,    X Y P L A N E
  
   Adds a number of consecutive planes from a cube to
   produce a 2-D data object.  YTPLANE, XTPLANE and XYPLANE
   take planes whose X,Y or T values respectively are
   constant over the extracted plane.  (Pedantic note:
   strictly, a cuboid is meant, rather than a cube.)
   (Further pedantic note: the X, Y and T axes
   mentioned in this routine should really be referred to
   as AXIS(1), AXIS(2) and AXIS(3) respectively. However,
   explanations become confusing if this is done, so the references to
   X, Y and T remain. This does not mean that the data is stored in
   .X .Y and .T structures - JM.)
  
   Command parameters -
  
   ’CUBE’     The name of the cube from which the planes
              are to be taken.
  
   ’XSTART’   The X,Y, or T-value of the first plane to be used.
   ’YSTART’   If CUBE has a X, Y or T  structure, the data
   ’TSTART’   from this is used.  If not, the plane numbers
              are used, starting from 1.
  
   ’XEND’     The X, Y, or T-value of the last plane to be used.
   ’YEND’
   ’TEND’
  
   ’IMAGE’    The name of the resulting data structure.
  
   Input data -
  
   CUBE - 3-D data-array
  
   Output data -
  
   IMAGE is created with the same structure as CUBE
   except that the data array will only have 2 dimensions, and if
   CUBE has a X,Y or T structure, this will be omitted -
   that is, XPLANE will omit any X structure, YPLANE any
   Y structure and  etc.
                                   KS / AAO 8th Jan 1985

D.242 YCADD-Adds a constant to the Y data in a file

Description:
Adds a constant value to each Y-axis value in a datafile.
Parameters:
IMAGE
Image with Y data to be added to.
FACTOR
Additive constant.
OUTPUT
Name of resulting image.
Source comments:
   I C O N S T
  
   This routine is the main body of ICMULT,ICDIV,ICADD and ICSUB,
   and of XCMULT, XCDIV, XCADD and XCSUB.  The Ixxxx routines
   operate on the data in an image, the Xxxx routines operate on
   the data in the X array of the input file.
   ICMULT multiplies an image by a constant.  Since the constant
   can be less than 1., this function will also divide an
   image by a constant, but ICDIV saves the caller from having
   to calculate a reciprocal. ICADD adds a constant to an image and
   ICSUB subtracts a constant from an image.
  
   Command parameters -
  
   IMAGE  (Character) The name of the structure containing the image.
          Uses main data array, or the x-axis data for the XCxxx routines.
  
   FACTOR (Numeric) The value of the constant factor.
  
   OUTPUT (Character) The name of the result of the operation.  This
          can be the same as for IMAGE.  If not, a new structure
          is created, with everything but the data a direct
          copy of the input.
  
   The command name is used to distinguish between the
   possible operations.
                                    KS / CIT 12th June 1984

D.243 YCDIV-Divides the Y data in a file by a constant

Description:
Divides each Y-axis value in a datafile by a constant.
Parameters:
IMAGE
Image with Y data to be divided.
FACTOR
Constant.
OUTPUT
Name of resulting image.
Source comments:
   I C O N S T
  
   This routine is the main body of ICMULT,ICDIV,ICADD and ICSUB,
   and of XCMULT, XCDIV, XCADD and XCSUB.  The Ixxxx routines
   operate on the data in an image, the Xxxx routines operate on
   the data in the X array of the input file.
   ICMULT multiplies an image by a constant.  Since the constant
   can be less than 1., this function will also divide an
   image by a constant, but ICDIV saves the caller from having
   to calculate a reciprocal. ICADD adds a constant to an image and
   ICSUB subtracts a constant from an image.
  
   Command parameters -
  
   IMAGE  (Character) The name of the structure containing the image.
          Uses main data array, or the x-axis data for the XCxxx routines.
  
   FACTOR (Numeric) The value of the constant factor.
  
   OUTPUT (Character) The name of the result of the operation.  This
          can be the same as for IMAGE.  If not, a new structure
          is created, with everything but the data a direct
          copy of the input.
  
   The command name is used to distinguish between the
   possible operations.
                                    KS / CIT 12th June 1984

D.244 YCMULT-Multiplies the Y data in a file by a constant

Description:
Multiplies each Y-axis value in a datafile by a constant.
Parameters:
IMAGE
Image with Y data to be multiplied.
FACTOR
Multiplicative constant.
OUTPUT
Name of resulting image.
Source comments:
   I C O N S T
  
   This routine is the main body of ICMULT,ICDIV,ICADD and ICSUB,
   and of XCMULT, XCDIV, XCADD and XCSUB.  The Ixxxx routines
   operate on the data in an image, the Xxxx routines operate on
   the data in the X array of the input file.
   ICMULT multiplies an image by a constant.  Since the constant
   can be less than 1., this function will also divide an
   image by a constant, but ICDIV saves the caller from having
   to calculate a reciprocal. ICADD adds a constant to an image and
   ICSUB subtracts a constant from an image.
  
   Command parameters -
  
   IMAGE  (Character) The name of the structure containing the image.
          Uses main data array, or the x-axis data for the XCxxx routines.
  
   FACTOR (Numeric) The value of the constant factor.
  
   OUTPUT (Character) The name of the result of the operation.  This
          can be the same as for IMAGE.  If not, a new structure
          is created, with everything but the data a direct
          copy of the input.
  
   The command name is used to distinguish between the
   possible operations.
                                    KS / CIT 12th June 1984

D.245 YCSUB-Subtracts a constant from the Y data in a file

Description:
Subtracts a constant value from each Y-axis value in a datafile.
Parameters:
IMAGE
Image with Y data to be subtracted from.
FACTOR
Constant to be subtracted from data.
OUTPUT
Name of resulting image.
Source comments:
   I C O N S T
  
   This routine is the main body of ICMULT,ICDIV,ICADD and ICSUB,
   and of XCMULT, XCDIV, XCADD and XCSUB.  The Ixxxx routines
   operate on the data in an image, the Xxxx routines operate on
   the data in the X array of the input file.
   ICMULT multiplies an image by a constant.  Since the constant
   can be less than 1., this function will also divide an
   image by a constant, but ICDIV saves the caller from having
   to calculate a reciprocal. ICADD adds a constant to an image and
   ICSUB subtracts a constant from an image.
  
   Command parameters -
  
   IMAGE  (Character) The name of the structure containing the image.
          Uses main data array, or the x-axis data for the XCxxx routines.
  
   FACTOR (Numeric) The value of the constant factor.
  
   OUTPUT (Character) The name of the result of the operation.  This
          can be the same as for IMAGE.  If not, a new structure
          is created, with everything but the data a direct
          copy of the input.
  
   The command name is used to distinguish between the
   possible operations.
                                    KS / CIT 12th June 1984

D.246 YSTRACT-Adds contiguous columns of an image to form a spectrum

Description:
Adds a number of consecutive columns from an image to produce a 1-D data object. (A ’column’ is all the pixels with a given X-value.)
Parameters:
IMAGE
Name of image to extract data from.
XSTART
First x-value to be used.
XEND
Last x-value to be used.
SPECTRUM
Name of spectrum to be generated.
Source comments:
   Y S T R A C T
  
   Adds a number of consecutive columns from an image to
   produce a 1-D data object.  (A ’column’ is all the
   pixels with a given AXIS(1) value.)
  
   Command parameters -
  
   ’IMAGE’    The name of the image from which the rows
              are to be taken.
  
   ’XSTART’   The AXIS(1)-value of the first row to be used.
              If IMAGE has an AXIS(1) structure, the data from this
              is used.  If not, the column numbers are used,
              starting from 1.
  
   ’XEND’     The AXIS(1)-value of the last column to be used.
  
   ’SPECTRUM’ The name of the resulting data.
  
   Input data - an IMAGE
  
   Output data -
  
   SPECTRUM is created with the same structure as IMAGE,
   except that the data-array will only have one dimension, and if
   IMAGE has an AXIS(1) structure, this will be omitted.  Any AXIS(2)
   structure will be copied unchanged.
  
                                   KS / CIT 22nd March 1984

D.247 YTPLANE-Adds contiguous YT planes of a data cube to form an image

Description:
Given a data cube (strictly a cuboid) YTPLANE extracts a 2-D image from it by adding together a number of planes of constant X.
Parameters:
CUBE
The name of a 3-dimensional data cuboid, from which YTPLANE is to extract a 2-D image by adding together contiguous planes of constant X value, the X dimension being the first dimension of the data.
XSTART
The X value of the first of the planes to be added together to form the extracted image. If the X axis of the cube is calibrated, XSTART must be specified in the units in which it is calibrated. Otherwise, the element number (1..N) should be used.
XEND
The X value of the last of the planes to be added together to form the extracted image.
IMAGE
The name of the 2-D image to be created by YTPLANE.
Source comments:
   Y T P L A N E ,   X T P L A N E,    X Y P L A N E
  
   Adds a number of consecutive planes from a cube to
   produce a 2-D data object.  YTPLANE, XTPLANE and XYPLANE
   take planes whose X,Y or T values respectively are
   constant over the extracted plane.  (Pedantic note:
   strictly, a cuboid is meant, rather than a cube.)
   (Further pedantic note: the X, Y and T axes
   mentioned in this routine should really be referred to
   as AXIS(1), AXIS(2) and AXIS(3) respectively. However,
   explanations become confusing if this is done, so the references to
   X, Y and T remain. This does not mean that the data is stored in
   .X .Y and .T structures - JM.)
  
   Command parameters -
  
   ’CUBE’     The name of the cube from which the planes
              are to be taken.
  
   ’XSTART’   The X,Y, or T-value of the first plane to be used.
   ’YSTART’   If CUBE has a X, Y or T  structure, the data
   ’TSTART’   from this is used.  If not, the plane numbers
              are used, starting from 1.
  
   ’XEND’     The X, Y, or T-value of the last plane to be used.
   ’YEND’
   ’TEND’
  
   ’IMAGE’    The name of the resulting data structure.
  
   Input data -
  
   CUBE - 3-D data-array
  
   Output data -
  
   IMAGE is created with the same structure as CUBE
   except that the data array will only have 2 dimensions, and if
   CUBE has a X,Y or T structure, this will be omitted -
   that is, XPLANE will omit any X structure, YPLANE any
   Y structure and  etc.
                                   KS / AAO 8th Jan 1985