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.