C Twodspec

 C.1 Introduction
 C.2 Line Profile Analysis
 C.3 ARC2D—Wavelength Calibration
 C.4 COMB and ARCSDI-Correction for Geometrical Distortions
 C.5 Display Programs
 C.6 Removing Continua
 C.7 Getting 3-D Data into the Correct Form for FIBDISP or LONGSLIT
 C.8 Miscellaneous Programs
 C.9 Note on Menus
 C.10 The Defaults File
 C.11 References

C.1 Introduction

Twodspec is a package of programs for the reduction and analysis of long-slit and optical fibre array spectra. It was originally developed as a separate package which complemented, and shared a common data format with, Figaro. For convenience, it has subsequently been incorporated into Figaro. This appendix is more-or-less the final version of the stand-alone Twodspec manual, with only a few minor changes. You should be aware that Twodspec’s style of interaction with the user is somewhat different to that of the basic Figaro applications. The best way to learn to use Twodspec is to find someone who is already familiar with it and persuade them to demonstrate it to you.

LONGSLIT is a program for the analysis of calibrated long-slit spectra. It has, among other things, the capability to fit Gaussians, either manually or automatically—in batch. It can, however, handle data with two spatial dimensions, such as obtained using TAURUS. The program FIBDISP provides further options useful for such data, although this is primarily designed for fibre array data. An extensive range of options is available, especially in terms of output. ARC2D is a two-dimensional arc calibration program. COMB and ARCSDI are for the correction of data for S-distortion and line curvature respectively.

Note that these programs are designed to do as much as possible for the user, to assist quick reduction and analysis of data—LONGSLIT can fit multiple Gaussians to line profiles in batch for example, and will decide how many components to fit. More information on the aims behind the package are given in Wilkins 1988 and Wilkins & Axon 1991.

Users of Twodspec are requested to acknowledge its original authors, T.N. Wilkins and D.J. Axon, in any publications resulting from its use.

C.2 Line Profile Analysis

C.2.1 Introduction

In order to parameterise a long-slit spectrum, it is often convenient to fit a function to the spectral lines. The most commonly used function is a Gaussian, defined as:

f(x) = He((xx0)2/2σ2) (1)

where σ is the standard deviation of the line, x0 is its centre, and H is its height. If the gas consists of a number of discrete clumps, moving at the same velocity, then a series of Gaussians would normally accurately represent the line profile (although the instrumental profile may alter this).

The Cauchy function may also be used:

f(x) = H 1 + [2(xx0)/w]2 (2)

The instrumental line profiles from a Fabry-Perot interferometer are approximate Cauchy functions. The precise form (Bland 1986) is:

A(x, y, z) = [1 + (2N/π)2 sin 2((2πμl(z) cos Q)/λ)]1 (3)

where N is the finesse of the etalon, μ the refractive index of air, l(z) the etalon spacing, Q the angle to the optical axis, and λ the wavelength of the light concerned.

Frazer and Suzuki (1969) give a function which varies smoothly between a Gaussian and a Cauchy function:

f(x) = H (1 + [2a2 1][2(xx0)/w]2) (4)

where as a tends to 0, this function tends to a Gaussian, and for a = 1, it is a Cauchy function.

The fitting consists of optimising the values of the free parameters, that is H, x0, etc. Normally one would also allow the fitting routines to vary the base level.

The programs LONGSLIT and FIBDISP can fit Gaussians (single or multiple), Lorentz profiles and Cauchy functions (actually the function of equation 4) to line profiles. From the fitting velocity plots may be produced by the programs, as can plots of line width and line flux (not FIBDISP), for each line against cross-section (greyscale in FIBDISP). It is also possible to output greyscale or contour velocity plots. LONGSLIT is designed to operate in batch as much as possible.

C.2.2 LONGSLIT

LONGSLIT is designed primarily for the analysis of long-slit spectra, although this is mainly a matter of the display options available—the fitting routines, for example, can cope with three-dimensional data.

The basic method of operation of LONGSLIT is as follows:

(1)
Locate lines. This is done by extracting part (or all) of the image and displaying it. The user is then required to mark to either side of the lines with a cursor and to identify the lines so located. Alternatively CLONE (see section C.2.2) may be used. A great advantage with CLONE here is that, since the data is calibrated, for a lot of data the tram positions will be the same. This makes CLONING in batch very useful, since only one spectrum need be calibrated before submitting a job to calibrate the rest and then perform Gaussian fitting. This part is the same as for ARC2D (see section C.3).
(2)
Choose the fit type. The type of fit to be performed is entered into the array .RES.CONTROL (see appendix 3.2.8 for a description of the results structure), for the relevant line and cross-section. This defaults to a single Gaussian with a base.
(3)
Perform the fit. The fit type is read from .RES.CONTROL, the fit is performed, and the results are stored in .RES.DATA.
(4)
Output results. This can be in the form of plots or tables for a range of variables.

The fact that LONGSLIT uses its own structure in the data file (the .RES structure, see appendix 3.2.8), means that the different stages above can easily be carried out at separate times, without needing to stay in the program between them.

There are two principle modes of operation for line fitting:

AUTO mode
In this the fits, blocking etc. are defined beforehand, and then performed without any further reference to the user (except for interactive multiple fits). This can be carried out in batch, thus saving time at the terminal.
MANUAL mode
In this the user can choose the blocking and fit type for each line as the fits are made, or the fit types may be defined in manual mode, but actually performed in AUTO mode, in batch for example. It is also possible to combine any range of cross-sections for a fit. Any previous fits may be displayed (this is the default), and it is possible to scan though the data, either individual cross-sections or with whole window’s being averaged up for each plot.

If you are unfamiliar with LONGSLIT you should first read sections C.2.2, C.2.2 and C.2.2. If you get stuck try looking at section C.2.2. Line Identification  Since ARC2D and ARCSDI have much in common with LONGSLIT as regards line selection, we will only describe this part once, noting the differences when they occur.

  % longslit
  (IMage) Name of image for input [1052-5VIG] -
  1052-5VIG[2040,171] HH 1-2 HALPHA/[N II]
  
  =========< A r c _ O p t s >=========
  
  New    : Set up line identifications from scratch
  Repeat : Use existing line identifications
  Clone  : Use line identifications from another file
  Fit option [REPEAT] - NEW
The options here are:
NEW
Used on a file LONGSLIT has not been used on before, a .RES structure is created and the user is asked to locate and identify the lines.
CLONE
As NEW, but used where line identifications are to be copied from another file.
REPEAT
Used when a .RES structure already exists, that is if LONGSLIT (or ARC2D) has already been run on the file.

NEW mode is needed to set up line identifications.

  (MAXLines) Maximum number of lines to allow room for [10] -

This only affects the size of the arrays to be used, so you are not committed to 10 lines! You cannot, however, later have more than the number set here.

  (MAXGauss) Maximum number of Gaussians to allow room for [5] -

Similarly this only sets the maximum allowed number of components in a fit. Note that this is the only “hard” limit to the number of components to be fitted when guesses are made for multiple component fits. A look at the data should allow a sensible value to be selected, five is a reasonable value (data rarely needs more components than this).

  (YStart) analysis lower limit [160] -
  (YEnd) analysis upper limit [200] -

A one-dimensional spectrum is extracted from the two-dimensional spectrum, and used for line selection. For LONGSLIT it is probably best to include all the data as here (the example data has 171 cross-sections), but for ARC2D and ARCSDI a central portion should be chosen (e.g. cross-sections 70–80 for a total of 171 cross-sections). At this stage the actual lines are located by marking to either side with a cursor. Be sure to include some base to either side, so that the optimisation routines can determine the base level precisely.

  Locate Line :   1
  2nd tram line
  Locate Line :   2
  2nd tram line
  Locate Line :   3

A list of cursor options can be obtained by hitting the “?’ key (hitting any key will then return to displaying the spectrum). Note that the options change depending upon whether the display is zoomed, and also upon whether any lines are identified (see below). If the key “Y” is pressed, this causes the program to set a new maximum Y value for the display based on the current cursor position. This is used to select weak lines, where the default display is such that they are small on the display, due to the presence nearby of much stronger line(s). The remaining lines are located.

Alternatively we could have used an automatic line-finding algorithm, by hitting key A. This option is available only while no lines have been found, or those found have only been located using this option (in which case the previously identified lines are discarded if the option is selected). This uses a routine adapted from SPICA, the predecessor to FIGARO. The automatic line finding algorithm checks for a minimum acceptable height for a line and for the values of the data dropping off to either side. It then finds the centroids and checks that the possible lines are above a minimum width. A check is also made for the line’s being sufficiently above the noise, and for not being a side-peak to another line.

The lines have now been located, LONGSLIT and ARC2D now need to know the identifications of these lines. Line lists are provided and users may create their owns lists. Alternatively the “ID” option in the “Identification Menu” can be used, in which a wavelength and name are used as given. Since ARCSDI only aims to straighten the lines, you would leave ARCSDI here.

  =========< L i n e   L i s t   M e n u >=========
  
  Emission   : Emission lines
  Absorption : Absorption lines
  Neon       : Neon arc
  Cuar       : Copper-argon arc
  Helium     : Helium arc
  Iron       : Iron arc
  SKy        : Sky lines
  STored     : User supplied list in file
  Ok         : All tables read in
  Line List Menu - e
  
   Emission line list.
   Current version August 1990
    78 lines read from EMISSION

The user can create his/her own file for use here. No responsibility is accepted for the wavelengths of the lines in the lists supplied. The format is as below, and the files can be created using an editor. The header consists of a number (as many as you want) of lines with an asterix in the first column, the only thing that is done with these is that they are written to the terminal (without the asterix). Blank lines are ignored, and all remaining lines are taken as data lines. The data lines have the wavelength (read free-format) followed by the (optional) name, the array for the names is character*10 line_name(number of line slots). These files can be placed in the default directory (the program will search there first, so they can have the same names as those supplied). The first few lines of the emission line list supplied are given here:

  * Emission line list.
  * Current version August 1990
  
   3726.1600 [OII]
   3728.9100 [OII]
   4101.0000 HDELTA
   4276.8300 [FeII]
   4287.4000 [FeII]
   4319.6200 [FeII]

It is possible to specify the FIGARO .ARC files, as alternatives, but if there is a file included with Twodspec with the same name, excluding the extension, then the extension must be given (note that most of these do not include line names, so these will be left blank). When you have read in all the required line lists, you reply “ok” to the above menu.

  L I N E   I D E N T I F I C A T I O N
  -------------------------------------
  Identify line number  1

The line with some of the surrounding spectrum is displayed so the user can, it is hoped, recognise the line! If the displayed width is not satisfactory, it can be changed using the WIDTH option of the menu shown below. A default response is given which is the value of the X array at the peak in intensity within the line boundaries. If, however, you already have two or more lines identified, the default will be interpolated or extrapolated from these (again using the positions of the maximum intensities within the line boundaries). It is possible to leave lines unidentified, although at present the only way to get back to the menu is by identifying at least one more line—you can edit the line list, but you then don’t have the advantage of the interpolation to help guessing (the fitting of the dispersion relationship in ARC2D can be used to help line identification). You can keep looping around the line list, identifying the lines in any order.

  =========< I d e n t i f i c a t i o n   M e n u >=========
  
  [number]               : Line wavelength
  Width         [number] : Redraw with different width
  Next                   : Go to next line
  Display                : Start/stop displaying tables of wavelengths
  Id [wavelength] [name] : Give line ID/wavelength (just taken as given)
  Quit                   : Exit leaving lines unidentified
  Identification Menu [ 6548.4] -
  6548.1001 [NII]6548 ok? [YES]
  Identify line number  2
  
  =========< I d e n t i f i c a t i o n   M e n u >=========
  
  [number]               : Line wavelength
  Width         [number] : Redraw with different width
  Next                   : Go to next line
  Display                : Start/stop displaying tables of wavelengths
  Id [wavelength] [name] : Give line ID/wavelength (just taken as given)
  Quit                   : Exit leaving lines unidentified
  Identification Menu [ 6563.1] -
  6562.8169 HALPHA ok? [YES]

If you enter just a wavelength the nearest line in the lists will be located, and you will be asked if this is what you want (as shown).

  =========< I d e n t i f i c a t i o n   M e n u >=========
  [number]               : Line wavelength
  Width         [number] : Redraw with different width
  Next                   : Go to next line
  Display                : Start/stop displaying tables of wavelengths
  Id [wavelength] [name] : Give line ID/wavelength (just taken as given)
  Quit                   : Exit leaving lines unidentified
  Identification Menu [ 6730.5752] -
  6730.8501 [SII]6731 ok? [YES]
  
   C U R R E N T   L I N E   L I S T
   _________________________________
  line No     identification      wavelength
     1           [NII]6548          6548.1001
     2           HALPHA             6562.8169
     3           [NII]6584          6583.6001
     4           [SII]6717          6716.4702
     5           [SII]6731          6730.8501
  Edit line list? [NO]

Errors can be corrected using this edit option. The user now reaches the Main Menu:

  Current value of iteration is   1
  
  =========< M a i n   m e n u >=========
  
  ADd       : Add more lines
  It        : Change iteration
  TEmplates : Input data for template based fits
  AUto      : Fixed window & fits type menu (use DEFINE to setup models)
  Manual    : Interactive setup of window & fits
  Define    : Define fits for AUTO
  EDit      : Edit/look at results structures
  TOls      : Apply tolerances
  Output    : Create output plots, etc.
  SKy       : Sky subtraction and data vignetting corrections
  SYnthetic : Generate synthetic spectra from input data and/or fits
  EXit      : Leave program
  Main menu [MANUAL] -

Once you have located and identified lines in one file, this information may be CLONED to another file. A powerful feature of ARC2D and LONGSLIT is the ability to CLONE a set of line locations from another file, rather than, or in addition to (but preceding), the normal line selection. For this, the two arcs are plotted one above the other and, from three points marked by the user on each arc, the locations of the lines are interpolated for the new arc. The wavelengths and identifications are then also copied over. This means that if two spectra of the same wavelength range are to be used, without co-adding, then the whole process of line identification can be circumvented. If the spectra are very similar, then the information can be copied straight over, even in batch mode. The parts of the images to be extracted for the plots are prompted for. MAIN MENU  This controls the interactive use of LONGSLIT, apart from the initial line identification. The options are:

ADD
Add more lines
IT
Change iteration. This allows reduction of iteration, in order to allow previous fits to be over-ridden (they can also be over-ridden in MANUAL mode fitting).
AUTO
In this mode one defines fits beforehand, and then goes though the lines and cross-sections in order performing the fits. This is the mode of fitting in batch, and ideally should not be carried out interactively.
MANUAL
In this mode one does the fits in whatever order is preferred. This can also be used for checking fits performed in batch mode. The line selected is indicated above the menu. Initially this is line one in the list. MANUAL mode is also driven by a menu:
Line name
to go to that line. By stating the line name, or any unique abbreviation, the line will be set to that selected.
LAST
Move back to previous line in line list.
NEXT
Move on to next line in line list.
TRIM
Limit the range of cross-sections. This is useful for altering the block start/end in window mode (see below)
CHECK
This displays 20 profile plots at a time. At present this will start at the current line, cross-section one, and scan through. When a screen is full, the user is asked whether he/she wants to see the next plots. This is designed for a quick look, before more detailed checking and re-fitting, if that is required. It is also useful to provide a convenient record of the line profiles to refer to, in which case the hardcopy option should be used. Note that if the “quick plot” option here (which gives plots of similar quality to softcopy plots) is not used the plots files can be very large.
FIT
Fit this window as it stands
ADVANCE
Go to next WINDOW
BACK
Go to previous window
SEE
Look at individual elements of window
WIDTH
Change window width
SCAN
Scan through windows
OLD
Start/stop plotting old fits
DELETE
Delete fits in this range
HARD
Produce hardcopy of data with fit
EXIT
Return to main menu
DEFINE
Define fits for AUTO mode, for batch or interactive use. This defines fits, either for all the lines at a time, or for each line separately. To define fits differently within a line, use MANUAL mode as described above.
LOOK
Look at values of data cube. This just lists the values in the results array.
TOLS
Apply tolerances. This will reject fits which have, for example, too great a width.
OUTPUT
These options are the main ways of producing output from the program. Selection of this puts the user into the “OUTPUT MENU”, with the following options:
HARDCOPY
Produce plots of profile fits. The line profile is displayed, together with the fit. It is possible to preview the fits first in softcopy (unless all fits are being plotted, using the option “plot whole cube”). If the option “plot whole cube?” is not being used, then the X-axis of the plots can be in km s1 or Ångstroms, otherwise they are in Ångstroms.
TABLE
Print table of profile parameters
PLOT
Plot rotation curves. Also width v. cross-section and flux v. cross-section plots can be made. All these can be made in softcopy or hardcopy. Also a plot of average velocities v. cross-section will be plotted, if the plot is in hardcopy, and there is more than one line.
PRINT
Print rotation curves
RATIO
Evaluate line ratios
GREY
Produce greyscale plot of data. This is for one line at a time, using the wavelength limits for the line from the initial line location. A velocity scale is plotted on the X-axis.
CONTOUR
This is similar to the GREY option, but uses contours rather than a greyscale image.
FULL
This produces a table suitable for input to a FORTRAN program, including the information from both PRINT and PLOT.
CHECK
This produces an array of line profiles to which successful (or NAG error failed fits if allowed) have been made, with the fits superimposed.
SOFT
This says whether plots are in softcopy (as opposed to hardcopy). This only affects the PLOT, CONTOUR and CHECK options.
VELOCITY
Plot with velocity scale for X axis. This affects the PLOT and HARDCOPY options above.
EXIT
Exit and accept current setting of the options. When any selected plots etc. have been carried out, the user is returned to the main menu.

If the PLOT option is selected the user will be presented with the following menu, to select precisely which plots are required:

VELOCITY
Radial velocities
WIDTH
Widths
FLUX
Fluxes
AVERAGE
Average velocities
ALL
Velocities on 1 plot
EXIT
Exit menu and perform plotting

The output options (except GREY and RATIO) can be given in the command line as keywords. An example of the use of the OUTPUT option is given in section C.2.2.

SKY
Not yet implemented
SYNTHETIC
Not yet implemented
EXIT
Leave program
CUBAN
Display array of profiles (3-dimensional data only), and move around under cursor control. This is the same as the option in the main menu of FIBDISP (see below).
Use of LONGSLIT in Auto Mode  LONGSLIT can be used to fit profiles in an automatic mode which saves a great deal of time but still provides the user with many options for this process. To do so the lines must first be located as described in section C.2.2. The desired fit type must then be defined, by selecting the DEFINE option at the main menu. We will assume that the fit model is to be defined interactively, in which case the user is then asked if the same model is to be used for all lines (if there is more than one line present), and to give the required model(s). In the following example all lines are to be fitted with double Gaussians (“untied” means that the two Gaussians are independent of each other).
  =========< M a i n   m e n u >=========
  
  ADd       : Add more lines
  It        : Change iteration
  TEmplates : Input data for template based fits
  AUto      : Fixed window & fits type menu (use DEFINE to setup models)
  Manual    : Interactive setup of window & fits
  Define    : Define fits for AUTO
  EDit      : Edit/look at results structures
  TOls      : Apply tolerances
  Output    : Create output plots, etc.
  SKy       : Sky subtraction and data vignetting corrections
  SYnthetic : Generate synthetic spectra from input data and/or fits
  EXit      : Leave program
  Main menu [MANUAL] - DEFINE
  Use same fit model for all lines? [YES] YES
  
  =========< F i t   M e n u >=========
  
  GUess       : Alter guessing ...... Multiples - SCRATCH, Singles - MAXIMUM
  BAse        : Alter base model .................................. CONSTANT
  BImodal     : Test for bimodality before fitting
  Instant     : Perform fits immediately
  ABsorption  : Fit ABSORPTION lines
  TEsts       : Alter tests for auto ......... AIC after fits (max cmps 5)
  Nofit       : Don’t fit this position
  GAussian    : Fit Gaussian(s) ...................................... *******
  Cauchy      : Fit a single Cauchy function
  Lorentzian  : Fit Lorentzian(s)
  SIngle      : Fit single(s)
  TSep        : Fit two Gaussians with fixed separation
  TWidth      : Fit two Gaussians with fixed width ratio
  THeight     : Fit two Gaussians with fixed height ratio
  Double      : Fit double(s)
  Manual      : Perform manual fitting
  AUto        : Automatic multiple Gaussian/Lorentzian ............. *******
  TRansfer %F : Start from fit to another line
  Exit        : Exit menu and perform any fitting
  Fit Menu [EXIT] - DO

Normally you would fit lines with the same model along all of the slit length, but in the following case line 2 is to be fitted with a double Gaussian (unconstrained) for the first 90 cross-sections, and a Cauchy function for the rest. The default fit type is a Gaussian with a base.

DEFINE can be used if you want to fit a whole line with a given type of fit e.g. a Lorentzian. The ADD option puts you back into the line selection as above, but without the option of automatic line location. The option is given to edit the line list again:

  Lines identified:
  [NII]6584 (6583.6)       [NII]6548 (6548.1)       HALPHA (6562.817)
  
  Enter starting line number [1] - 2
  (YBlock) Analysis x-sect width [5] - 90
  Number of blocks = 2
  Enter starting cross-section number [1] -

The line is displayed.

If a previous fit has been made on the same data, this is displayed at this stage (but this can be suppressed).

  No previous fit
  
  =========< M a n u a l   M o d e >=========
  
  [name]  : Line name to go to that line
  Last    : Move back to previous Line
  Next    : Move on to next line in list
  Trim    : LIMIT the range of X-sects
  Check   : Check previous fits (20 to a screen)
  FIt     : Fit this window as it stands
  Advance : Go to next WINDOW
  Back    : Go to previous window
  SEe     : Look at individual elements of window
  Width   : Change window width
  SCan    : Scan through windows
  Old     : Start/stop plotting old fits
  Delete  : Delete fits in this range
  Hard    : Produce hardcopy of data with fit
  Exit    : Return to main menu
  Manual Mode [FIT] -
  
  =========< F i t   M e n u >=========
  
  GUess       : Alter guessing ........... Multiples - SCRATCH, Singles - MAXIMUM
  BAse        : Alter base model ....................................... CONSTANT
  BImodal     : Test for bimodality before fitting
  Instant     : Define fits only
  ABsorption  : Fit ABSORPTION lines
  TEsts       : Alter tests for auto ................ AIC after fits (max cmps 5)
  Nofit       : Don’t fit this position
  GAussian    : Fit Gaussian(s) ......................................... *******
  Cauchy      : Fit a single Cauchy function
  Lorentzian  : Fit Lorentzian(s)
  SIngle      : Fit single(s) ........................................... *******
  TSep        : Fit two Gaussians with fixed separation
  TWidth      : Fit two Gaussians with fixed width ratio
  THeight     : Fit two Gaussians with fixed height ratio
  Double      : Fit double(s)
  Manual      : Perform manual fitting
  AUto        : Automatic multiple Gaussian/Lorentzian
  TRansfer    : Start from fit to another line
  Exit        : Exit menu and perform any fitting
  Fit Menu [EXIT] - D
  
  =========< F i t   M e n u >=========
  
  GUess       : Alter guessing ........... Multiples - SCRATCH, Singles - MAXIMUM
  BAse        : Alter base model ....................................... CONSTANT
  BImodal     : Test for bimodality before fitting
  Instant     : Define fits only
  ABsorption  : Fit ABSORPTION lines
  TEsts       : Alter tests for auto ................ AIC after fits (max cmps 5)
  Nofit       : Don’t fit this position
  GAussian    : Fit Gaussian(s) ......................................... *******
  Cauchy      : Fit a single Cauchy function
  Lorentzian  : Fit Lorentzian(s)
  SIngle      : Fit single(s)
  TSep        : Fit two Gaussians with fixed separation
  TWidth      : Fit two Gaussians with fixed width ratio
  THeight     : Fit two Gaussians with fixed height ratio
  Double      : Fit double(s) ........................................... *******
  Manual      : Perform manual fitting
  AUto        : Automatic multiple Gaussian/Lorentzian
  TRansfer    : Start from fit to another line
  Exit        : Exit menu and perform any fitting
  Fit Menu [EXIT] -
  
  =========< M a n u a l   M o d e >=========
  
  [name]  : Line name to go to that line
  Last    : Move back to previous Line
  Next    : Move on to next line in list
  Trim    : LIMIT the range of X-sects
  Check   : Check previous fits (20 to a screen)
  FIt     : Fit this window as it stands
  Advance : Go to next WINDOW
  Back    : Go to previous window
  SEe     : Look at individual elements of window
  Width   : Change window width
  SCan    : Scan through windows
  Old     : Start/stop plotting old fits
  Delete  : Delete fits in this range
  Hard    : Produce hardcopy of data with fit
  Exit    : Return to main menu
  Manual Mode [FIT] - ADVANCE

The line is displayed.

  No previous fit
  
  =========< F i t   M e n u >=========
  
  GUess       : Alter guessing ........... Multiples - SCRATCH, Singles - MAXIMUM
  BAse        : Alter base model ....................................... CONSTANT
  BImodal     : Test for bimodality before fitting
  Instant     : Define fits only
  ABsorption  : Fit ABSORPTION lines
  TEsts       : Alter tests for auto ................ AIC after fits (max cmps 5)
  Nofit       : Don’t fit this position
  GAussian    : Fit Gaussian(s) ......................................... *******
  Cauchy      : Fit a single Cauchy function
  Lorentzian  : Fit Lorentzian(s)
  SIngle      : Fit single(s) ........................................... *******
  TSep        : Fit two Gaussians with fixed separation
  TWidth      : Fit two Gaussians with fixed width ratio
  THeight     : Fit two Gaussians with fixed height ratio
  Double      : Fit double(s)
  Manual      : Perform manual fitting
  AUto        : Automatic multiple Gaussian/Lorentzian
  TRansfer    : Start from fit to another line
  Exit        : Exit menu and perform any fitting
  Fit Menu [EXIT] - C

Just reply with “EXIT” from now on to leave the program.

  
  =========< M a n u a l   M o d e >=========
  
  [name]  : Line name to go to that line
  Last    : Move back to previous Line
  Next    : Move on to next line in list
  Trim    : LIMIT the range of X-sects
  Check   : Check previous fits (20 to a screen)
  FIt     : Fit this window as it stands
  Advance : Go to next WINDOW
  Back    : Go to previous window
  SEe     : Look at individual elements of window
  Width   : Change window width
  SCan    : Scan through windows
  Old     : Start/stop plotting old fits
  Delete  : Delete fits in this range
  Hard    : Produce hardcopy of data with fit
  Exit    : Return to main menu
  Manual Mode [FIT] - EXIT
   Fits defined =    2
  Current value of iteration is   1
  
  =========< M a i n   m e n u >=========
  
  ADd       : Add more lines
  It        : Change iteration
  TEmplates : Input data for template based fits
  AUto      : Fixed window & fits type menu (use DEFINE to setup models)
  Manual    : Interactive setup of window & fits
  Define    : Define fits for AUTO
  EDit      : Edit/look at results structures
  TOls      : Apply tolerances
  Output    : Create output plots, etc.
  SKy       : Sky subtraction and data vignetting corrections
  SYnthetic : Generate synthetic spectra from input data and/or fits
  EXit      : Leave program
  Main menu [MANUAL] -

The setting up of lines in ARCSDI is similar to the above, except that the program is exited after the “OK?” question above (before line identification).

The automatic fitting of the lines can then be carried out by selecting the AUTO option in the main menu. Fitting Multiple Components in Auto mode  If LONGSLIT, when in auto mode, comes across a fit defined as multiple, it will attempt to fit it with as many lines as it thinks are needed! It uses the tolerance settings for minimum and maximum width, and minimum height. These are used for the guesses and the final answers, and will probably need some tweaking. Also it will of course still need checking afterwards. It may well have more than one attempt at fitting. This checking is easily carried out using the CHECK option in MANUAL mode—it is best to use this to produce hardcopy plots which can be kept beside the terminal while you go through checking (you may find 20% of the profiles need re-fitting, but this will depend upon the line profiles, as well as the values of the tolerances). You may also need to investigate cross-sections for which no fit is given—this may be because there is no emission at that point, or the fit may have failed for some reason, even with strong emission (it may guess too many components for example, and then crash in the fitting). Note that LONGSLIT outputs to the screen the reason why the next component was not accepted when it searches for components. The display also contain details of any re-fitting. Thus if the fits are not acceptable after the first attempt at using this the user can alter the tolerances accordingly. The option AIC in the fit defining menu determines whether Akaike’s information criterion (Akaike 1973) is used during multiple fitting to decide how many components to fit. This is true by default. The guesses are made in the same way, whether or not this is true, except that the widths are allowed to be a little larger—in both cases the guesses to the widths are allowed to the value in the tolerances array, to allow for errors in guessing (the fits are only accepted if they are actually within the tolerances), this ratio is larger if AIC is true. The value of the criterion is then calculated, and the best value is selected after progressively removing components to the fit. Thus if the guessing produces three components, the program will also “see what happens” with two components, one component and just a base. The criterion is

C = M× ln S + 2 ×N (5)
where C is Akaike’s information criterion, M is the number of data points, S is the weighted sum of squares, and N is the number of fit parameters. The fit with the lowest value of C is used. For fitting the tolerances should be as close as possible to the expected values of the parameters. The user is encouraged to learn to use this option, since it can give considerable time savings. N.B. To refit a cube which has already been fitted, but the values changed, e.g. flux-calibrated, use the keyword COPY, which will use scaled existing values as first guesses, repeating all the fits in the “cube”. If used with CLONE, it enables similar spectra to be easily fitted. Fitting Gaussians etc. Interactively  The main method of fitting these is the WINDOW option of MANUAL mode. First select MANUAL at the main menu.
  =========< M a i n   m e n u >=========
  
  ADd       : Add more lines
  It        : Change iteration
  TEmplates : Input data for template based fits
  AUto      : Fixed window & fits type menu (use DEFINE to setup models)
  Manual    : Interactive setup of window & fits
  Define    : Define fits for AUTO
  EDit      : Edit/look at results structures
  TOls      : Apply tolerances
  Output    : Create output plots, etc.
  SKy       : Sky subtraction and data vignetting corrections
  SYnthetic : Generate synthetic spectra from input data and/or fits
  EXit      : Leave program
  Main menu [MANUAL] - MANUAL
Say which line you wish to start working on, give the required blocking (number of cross-sections added together) and the starting cross-section.
  Lines identified:
  [NII]6584 (6583.6)       [NII]6548 (6548.1)       HALPHA (6562.817)
  
  Enter starting line number [1] - 3
  (YBlock) Analysis x-sect width [5] - 10
  Number of blocks = 2
  Enter starting cross-section number [1] - 110

The line is displayed. This then puts you into MANUAL menu. Select FIT and then select the fit type required. MG allows the user to set the guesses required for optimisation, and to constrain the fits if required. TG allows the ratio of the heights or widths, or the separation of the lines, to be fixed. The other fit types are entirely automatic. Note that the “Cauchy” function is actually a function which varies smoothly between a true Cauchy function and a Gaussian (equation 4).

  No previous fit
  
  =========< M a n u a l   M o d e >=========
  
  [name]  : Line name to go to that line
  Last    : Move back to previous Line
  Next    : Move on to next line in list
  Trim    : LIMIT the range of X-sects
  Check   : Check previous fits (20 to a screen)
  FIt     : Fit this window as it stands
  Advance : Go to next WINDOW
  Back    : Go to previous window
  SEe     : Look at individual elements of window
  Width   : Change window width
  SCan    : Scan through windows
  Old     : Start/stop plotting old fits
  Delete  : Delete fits in this range
  Hard    : Produce hardcopy of data with fit
  Exit    : Return to main menu
  Manual Mode [FIT] -
  
  =========< F i t   M e n u >=========
  
  GUess       : Alter guessing ........... Multiples - SCRATCH, Singles - MAXIMUM
  BAse        : Alter base model ....................................... CONSTANT
  BImodal     : Test for bimodality before fitting
  Instant     : Define fits only
  ABsorption  : Fit ABSORPTION lines
  TEsts       : Alter tests for auto ................ AIC after fits (max cmps 5)
  Nofit       : Don’t fit this position
  GAussian    : Fit Gaussian(s) ......................................... *******
  Cauchy      : Fit a single Cauchy function
  Lorentzian  : Fit Lorentzian(s)
  SIngle      : Fit single(s) ........................................... *******
  TSep        : Fit two Gaussians with fixed separation
  TWidth      : Fit two Gaussians with fixed width ratio
  THeight     : Fit two Gaussians with fixed height ratio
  Double      : Fit double(s)
  Manual      : Perform manual fitting
  AUto        : Automatic multiple Gaussian/Lorentzian
  TRansfer    : Start from fit to another line
  Exit        : Exit menu and perform any fitting
  Fit Menu [EXIT] - MG
  
  =========< F i t   M e n u >=========
  
  GUess       : Alter guessing ........... Multiples - SCRATCH, Singles - MAXIMUM
  BAse        : Alter base model ....................................... CONSTANT
  BImodal     : Test for bimodality before fitting
  Instant     : Define fits only
  ABsorption  : Fit ABSORPTION lines
  TEsts       : Alter tests for auto ................ AIC after fits (max cmps 5)
  Nofit       : Don’t fit this position
  GAussian    : Fit Gaussian(s) ......................................... *******
  Cauchy      : Fit a single Cauchy function
  Lorentzian  : Fit Lorentzian(s)
  SIngle      : Fit single(s)
  TSep        : Fit two Gaussians with fixed separation
  TWidth      : Fit two Gaussians with fixed width ratio
  THeight     : Fit two Gaussians with fixed height ratio
  Double      : Fit double(s)
  Manual      : Perform manual fitting .................................. *******
  AUto        : Automatic multiple Gaussian/Lorentzian
  TRansfer    : Start from fit to another line
  Exit        : Exit menu and perform any fitting
  Fit Menu [EXIT] - MG

We choose MG for this example. The program plots the line profile with the current guesses (either taken from a previous fit or “guessed” from scratch).

  HALPHA (line = 2)
  Previous fit
  Single emission    Gaussian with base
  successful
  Will fit a multiple Gaussian
  Number of gaussians in previous fit = 2
  Guesses:-
  Component     Centre        fwhm       Height    Base
     1       6564.599       0.8904        255.1        2.934
     2       6561.983        1.485        23.98

The user is free to alter the parameters and to add or delete components. When satisfactory, the parameters are optimised. Hit “F” or click in the rectangle labelled “FIT”. Background Models  The default model is a flat background, which is quite sufficient for many objects such as many emission nebulae where there is not a strongly varying background. For some objects, however, this will not be sufficient, and allowance must be made for a varying background (e.g. a stellar continuum). LONGSLIT provides three solutions to this problem

(1)
Fit a Chebyshev polynomial to the base immediately before fitting the line profile. The polynomial it fitted to the whole of the spectrum, except for those parts within the boundaries of the identified lines. The order for the polynomial is stored in the results block, and this is used to re-create the fit as required (e.g. for profile plots). Although this cuts down on storage requirements, it does mean that if you identify any further lines, these will cause the program to make incorrect assumptions. For this the blocking is, of course the same as for the profile fitting. The order can be varied as required for different lines. If this option is used, it is essential that the spectrum is not trimmed (subsetted) too close to the line.
(2)
Use a cubic spline to interpolate the values in the range of fitting. As with the Chebyshev polynomial the blocking is as for the fit, and the areas within the line boundaries are not used to constrain the splines.
(3)
Use Chebyshev polynomials, but perform their fitting using FITCONT. LONGSLIT can then pick up the coefficients (from a special coefficient structure), and use them to obtain the base. Since the blocking to be used by LONGSLIT is not known at this stage (by FITCONT at least), the fits are to single cross-sections, and the results are added when required. The areas to be excluded from the fitting are marked with a cursor (this is more versatile than when the fitting is performed by LONGSLIT).

To select a model other than a flat base, use the DEFINE option in the main menu, in which case you will be asked for the background model. Note that once set up, the model remains in force for fitting until the user leaves the program.

If you select option (i) above at the MANUAL menu, LONGSLIT gets you to decide upon the order to fit at that time—various plots are available to help. If you select this from DEFINE, then you be asked to decide upon the order before the first fit, unless you have already given it the order (in WINDOW for example). For this reason, this option cannot yet be used in batch mode. Producing Output Plots, Tables etc.  When all the desired fits have been done (or earlier to get a check on them), you should used the standard FIGARO function HARD to set the hardcopy device (like SOFT for a softcopy device), for example:

  % hard ps_l
Then enter the program and at the main menu select “OUTPUT”. Then enter the options required e.g.:
  ......
  ......
  Output   : Create output plots, etc.
  Exit     : Leave program
  Main menu [MANUAL] - OUTPUT
  
  =========< O u t p u t   O p t i o n s >=========
  
  Hardcopy : Plots of profile fits.............. F
  Table    : Table of profile parameters........ F
  PLot     : Plot rotation curves............... F
  PRint    : Print rotation curves.............. F
  Ratio    : Output line ratios (with plots).... F
  Grey     : Greyscale plot of velocity......... F
  COntour  : Contour plot of velocity........... F
  Full     : Large table........................ F
  CHeck    : Profile array...................... F
  SOft     : Plot in softcopy (* above) ...... = T
  Velocity : Use velocity scale (+ above) .... = T
  Exit     : Exit menu
  Output Options - TABLE

The selection of options here is to “toggle” the option on or off, so entering an option once will select it, twice will cancel the selection. The options are performed when this menu is left.

  =========< O u t p u t   O p t i o n s >=========
  
  Hardcopy : Plots of profile fits.............. F
  Table    : Table of profile parameters........ T
  PLot     : Plot rotation curves............... F
  PRint    : Print rotation curves.............. F
  Ratio    : Output line ratios (with plots).... F
  Grey     : Greyscale plot of velocity......... F
  COntour  : Contour plot of velocity........... F
  Full     : Large table........................ F
  CHeck    : Profile array...................... F
  SOft     : Plot in softcopy (* above) ...... = T
  Velocity : Use velocity scale (+ above) .... = T
  Exit     : Exit menu
  Output Options [TABLE] - PLOT
  
  =========< O u t p u t   O p t i o n s >=========
  
  Hardcopy : Plots of profile fits.............. F
  Table    : Table of profile parameters........ T
  PLot     : Plot rotation curves............... T
  PRint    : Print rotation curves.............. F
  Ratio    : Output line ratios (with plots).... F
  Grey     : Greyscale plot of velocity......... F
  COntour  : Contour plot of velocity........... F
  Full     : Large table........................ F
  CHeck    : Profile array...................... F
  SOft     : Plot in softcopy (* above) ...... = T
  Velocity : Use velocity scale (+ above) .... = T
  Exit     : Exit menu
  Output Options [PLOT] - PRINT
  
  =========< O u t p u t   O p t i o n s >=========
  
  Hardcopy : Plots of profile fits.............. F
  Table    : Table of profile parameters........ T
  PLot     : Plot rotation curves............... T
  PRint    : Print rotation curves.............. T
  Ratio    : Output line ratios (with plots).... F
  Grey     : Greyscale plot of velocity......... F
  COntour  : Contour plot of velocity........... F
  Full     : Large table........................ F
  CHeck    : Profile array...................... F
  SOft     : Plot in softcopy (* above) ...... = T
  Velocity : Use velocity scale (+ above) .... = T
  Exit     : Exit menu
  Output Options [PRINT] - EXIT
  
  =========< P l o t   O p t i o n s >=========
  
  Velocity : Radial velocities .. = T
  Width    : Widths ............. = T
  Flux     : Fluxes ............. = T
  AVerage  : Average velocities . = T
  ALl      : Velocities on 1 plot = T
  Exit     : Exit menu
  Plot Options [] - EXIT
  Evaluate correction for Earth motion etc. [YES]
   DEC -6 48 0
   RA 5 33 56.8
  Day of observation? [339] -
   Date:- 339/1/1984
   UT 17 51 13
   Observatory position 149 3 57.91 -31 16 37.34

If the program cannot find information on the observatory, then it will ask. The reply can be the position, or an observatory name (type “HELP”) for help. Likewise the position of the object, date of observation etc. will be prompted for if required. Note that it is satisfactory to give the date as (for example) the 60th day of the year, giving the month as 1, rather than giving the true month, if this is preferred.

The velocity may be corrected to heliocentric, local standard of rest, galactic, or local group. This uses the STARLINK SLA library (Wallace 1990) and is based on the STARLINK program RV (Wallace 1987).

  Is longitude ok, taking longitude as +ve west [YES] n
   V_HEL=-4.16896E+00 V_LSR= 1.40857E+01
   V_GAL= 1.33324E+02 V_LGROUP= 1.38917E+02
  
  =========< V e l o c i t y   C o r r e c t i o n >=========
  
  Hel     : Suns ref frame
  Lsr     : Local standard of rest
  GAl     : Galaxy ref frame
  GRoup   : Local galactic group ref frame
  Other   : Other - enter from terminal
  Velocity Correction [LSR] -
  OK? [YES]
  Show fits which had NAG errors [NO]
  Is data flux calibrated? [NO]
  Printing fits
  Indicate presence of failed fits [NO]
  
  =========< F l u x   M a r k i n g >=========
  
  No           : Don’t mark points according to flux
  Continuous   : Mark using a continuous scale
  Three        : Mark by grading into 3 divisions
  Flux Marking [CONTINUOUS] -
  Plotting Velocities
  Line number  1
  Line number  2
  Line number  3
  Plotting average velocities
  Plot flux v. xsect? [YES] n
  Plot width v. xsect? [YES] n
  Job 123 entered on queue SYS_LASER
  Print of velocities

Unless NOFIT was specified (in which case the user would miss out the main menu entirely), the user is now returned to the main menu.

The option to mark the points can either put the markers so that the most intense 3rd of the points have a filled circle, the next 3rd an open one, and the remainder are not marked, or the area can be proportional to the logarithm of the flux. The latter is recommended.

Note that if NOLABEL is given in the command line the titles will be omitted for many of the output plots.

In some cases LONGSLIT may not have been able to obtain errors on the fits—this involves inverting a matrix. For such cases the errors will be given as zero (obviously not a correct value!) when the fits are listed. The Keyword FIT  This will cause the program to run though the fitting part of the program, by default it is true, so may be ignored. It is, however, possible to specify NOFIT in a command line, to run LONGSLIT in batch without performing fits (or just to skip the middle part of the program when running interactively) e.g.:

  % longslit t1 repeat table nofit
This will produce a table of the fit results. It may be used for other output options (except RATIO), e.g.:
  % longslit t1 repeat print table plot hardcopy nofit vcorr=10

In batch correction may be made for the Earth’s motion by using the parameter VCORR as above, this will be subtracted from the radial velocities calculated. TRANSFER Option  The OL option in select fit type is for use with the TRANSFER option to transfer fits between different lines. For this to work the fits must be defined using the DEFINE option, before fitting in AUTO mode, preferably in batch. The fits are copied so that one line becomes a copy of another as regards fit type, blocking, etc., but of course the fits are optimised on the data for the current line. If the fits are not re-defined, then other modes will not work for that line (except COPY). TRANSFER does NOT override masking as COPY does, and is selected by specifying OL as the fit type. If this option is used, all the cross-sections of a line should be so defined. INHERIT Option  This is an option to do any fitting in batch, provided the program has a fit to one block, and the data is fairly continuous. Value -1 to inherit from previous block, +1 to inherit from next. The fit to this block used as the guess for the next fit. Likewise INHERIT must be given on the command line. Use of Tolerances  The option to apply tolerances interactively is selected at the main menu. First of all the user is asked to confirm (and alter if required) the values of the tolerances to apply, and then the user can select which tolerances to use. It is possible merely to set the values, but not to apply them at the time, for example if you wanted to set them up for use in batch mode. In the following example the maximum allowed height is set to 107, and then tolerances are applied on height, centre and width.

  Main menu [MANUAL] - TOLS
  Tolerances on position are relative to the line’s rest wavelength
  
  =========< E d i t   T o l e r a n c e s >=========
  
  V_Tol %F : Absolute error of line centre .... = 1.8994141E-02
  V_MAx %F : Max allowed line centre .......... = 3
  V_MIn %F : Min line centre .................. = -3
  W_Tol %F : Absolute error of line width ..... = 1.8994141E-02
  W_MAx %F : Max allowed line width ........... = 4
  W_MIn %F : Min allowed line width ........... = 0.1899414
  W_S_n %F : Width signal/noise ............... = 5
  H_MAx %F : Max allowed line height .......... = 1000
  H_MIn %F : Min allowed line height .......... = 20
  H_S_n %F : Height signal/noise .............. = 5
  C_tol %F : Absolute error of Cauchy parameter = 2.0000001E-03
  S_tol %F : Absolute error of Skew parameter . = 2.0000001E-03
  H_Tol %F : Absolute error of height ......... = 3
  Apply    : Apply tolerances now
  Exit     : Exit but don’t apply tolerances now
  Edit Tolerances - H_MAX 1E7
  
  =========< E d i t   T o l e r a n c e s >=========
  
  V_Tol %F : Absolute error of line centre .... = 1.8994141E-02
  V_MAx %F : Max allowed line centre .......... = 3
  V_MIn %F : Min line centre .................. = -3
  W_Tol %F : Absolute error of line width ..... = 1.8994141E-02
  W_MAx %F : Max allowed line width ........... = 4
  W_MIn %F : Min allowed line width ........... = 0.1899414
  W_S_n %F : Width signal/noise ............... = 5
  H_MAx %F : Max allowed line height .......... = 1.E7
  H_MIn %F : Min allowed line height .......... = 20
  H_S_n %F : Height signal/noise .............. = 5
  C_tol %F : Absolute error of Cauchy parameter = 2.0000001E-03
  S_tol %F : Absolute error of Skew parameter . = 2.0000001E-03
  H_Tol %F : Absolute error of height ......... = 3
  Apply    : Apply tolerances now
  Exit     : Exit but don’t apply tolerances now
  Edit Tolerances - APPLY
  
  =========< S e t   R e j e c t i o n   C r i t e r i a >=========
  
  Height      : Test on HEIGHT....... = F
  Centre      : Test on CENTRE....... = F
  Width       : Test on WIDTH........ = F
  Errors      : Test on ERRORS....... = F
  S/n         : Test on S/N.......... = F
  SHape       : Test on SHAPE........ = F
  SEparations : Test on SEPARATIONS.. = F
  Log         : Log failures ........ = F
  Apply       : Apply tolerances now
  Set Rejection Criteria - CENTRE
  
  =========< S e t   R e j e c t i o n   C r i t e r i a >=========
  
  Height      : Test on HEIGHT....... = F
  Centre      : Test on CENTRE....... = T
  Width       : Test on WIDTH........ = F
  Errors      : Test on ERRORS....... = F
  S/n         : Test on S/N.......... = F
  SHape       : Test on SHAPE........ = F
  SEparations : Test on SEPARATIONS.. = F
  Log         : Log failures ........ = F
  Apply       : Apply tolerances now
  Set Rejection Criteria - HEIGHT
  
  =========< S e t   R e j e c t i o n   C r i t e r i a >=========
  
  Height      : Test on HEIGHT....... = T
  Centre      : Test on CENTRE....... = T
  Width       : Test on WIDTH........ = F
  Errors      : Test on ERRORS....... = F
  S/n         : Test on S/N.......... = F
  SHape       : Test on SHAPE........ = F
  SEparations : Test on SEPARATIONS.. = F
  Log         : Log failures ........ = F
  Apply       : Apply tolerances now
  Set Rejection Criteria - WIDTH
  
  =========< S e t   R e j e c t i o n   C r i t e r i a >=========
  
  Height      : Test on HEIGHT....... = T
  Centre      : Test on CENTRE....... = T
  Width       : Test on WIDTH........ = T
  Errors      : Test on ERRORS....... = F
  S/n         : Test on S/N.......... = F
  SHape       : Test on SHAPE........ = F
  SEparations : Test on SEPARATIONS.. = F
  Log         : Log failures ........ = F
  Apply       : Apply tolerances now
  Set Rejection Criteria - APPLY
  Testing on: HEIGHT CENTRE WIDTH
  75 fits rejected
The option to log the failures lists, for each fit at each cross-section which fails the tolerances, the reason why it failed, and the value of the relevant parameter. For a large data set this can produce a large amount of output! Returned fits will also be listed (if you relaxed your rejection criteria). Otherwise the number of fits rejected is all that is listed. Note that the testing ignores blocking, so each cross-section for each line is counted as a separate fit.

The tolerances are as follows, and apply to each component of the fit unless otherwise stated (i.e. if one component fails, the fit is rejected):

HEIGHT
Fits are accepted only if their height is greater than H_MIN and and less than H_MAX.
CENTRE
Fits are accepted only if their centre is greater than V_MIN and and less than V_MAX.
WIDTH
Fits are accepted only if their width is greater than w_MIN and and less than W_MAX.
ERRORS
Fits are accepted only if the error on the height is less than H_TOL, that on width less than W_TOL and that on centre less than V_TOL.
S/N
Fits are accepted only if the ratio of Height to Error on height is greater than H_S_N and if the ratio of width to its error is greater than W_S_N.
SHAPE
The fit is rejected if the error on a Cauchy fit is greater than C_TOL.
SEPARATIONS
For the moment this is ignored!
Summary of Parameters 
IMage
(char) Name of image for input, This is the data and should be a FIGARO format data file. This should also have a .X axis array which contains the wavelengths of the lines. For the identification files supplied with the program the units should be Ångstroms. However, if the user supplies his/her own files, this need not apply, although some plots may have the wrong labels.
ARC_OPTS
(char) Fit option:
NEW (N)
Set up a new analysis
REPEAT (R)
Iterate on previous analysis
CLONE (C)
CLONE an analysis from another file
YStart
(int) Analysis lower limit
YEnd
(int) Analysis upper limit
YBlock
(int) Analysis cross-section width
ITeration
(int) New value of iteration
MAXLines
(int) Maximum number of lines to allow room for
CLfile
(char) Name of image for CLONING from
VCorr
(real) Correction to apply to radial velocities
TOls
(char) For use in batch only
INherit
(int) Number to control inheritance of previous fits:
0
no inheritance of fits
1
inheritance from next block
-1
inheritance from previous block
DEvice
(char) Device to use for plotting (greyscale)
FITRat
(real) Ratio of widths, heights, or separation, for double fits
CAlrat
(int) Ratio of number of iteration to default
WHite
(float) Level to plot as white (greyscale option)
BLack
(float) Level to plot as black (greyscale option)
MAXGauss
(int) Maximum number of Gaussians that can be fitted to a profile.
TStart
(int) Analysis lower limit
TEnd
(int) Analysis upper limit
TBlock
(int) Analysis width in T direction
FIT_MODEL
(char) Model for fitting
PLOTLim
(float) Limits of plot (world coordinates). This is to allow velocity plots to be forced to all have the same scale, making comparison easier.
HArdcopy
(key) Produce hardcopy plots of fits from cube
TAble
(key) Produce table of fits from cube
PLOT
(key) Produce plots of rotation curves
PRInt
(key) Produce print out of rotation curves
KEEP_ITT
(key) Keep iteration files. These files contain details of the fitting process. If a fit succeeds the file is always deleted, if it crashed it is always kept, this keyword controls whether it is deleted if a NAG error occurs.
FIT
(key) Perform fitting
COPY
(key) Copy previous fits This will repeat all the fits previously made, which is likely to be of use if data is co-added after one file has been analysed. Also, when used with CLONE the entire .RES structure is copied without any change. For the new fits the previous fits (suitably scaled) are used as first guesses.
ABsorption
(key) Allow fitting of absorption lines. This allows absorption fits to be defined—once defined they can be fitted whatever the value of this.
BOunds
(key) Perform bounded fits to lines (in batch). This only bounds the widths.
LAbel
(key) Put labels on plots. This is true by default, but it may be preferable if plots are to be used in a paper to not have labels.
CONtour
(key) Produce contour plots
GRey
(key) Produce greyscale plots
LOG
(key) Use log scale for greyscale and contour plots
WEIghts
(key) Use weighted fitting (default is true).
PRFits
(key) Print out details of fitting. This is true by default, but if you wish to avoid large log files set it to false.
FULL
(key) Print out full details of fits in table. This provides the information in a form which is easier to read into a FORTRAN program, and includes the information given in PRINT and TABLE.
CHECK
(key) This produces an array of line profiles with the fits superimposed.
The options HARDCOPY, TABLE, PLOT, PRINT, SHAPE and FULL are the same as for the OUTPUT MENU, except that in batch mode HARDCOPY will work on all line profiles/blockings which have a successful fit. CONTOUR and GREYSCALE work on all the lines in batch mode.

Note that the use of TSTART and TEND is with 3-dimensional data files. At present LONGSLIT only partially supports these, but some of the same code is used as in FIBDISP.

The keyword PRFITS is true by default but the user may set it to false to avoid large log files when running in batch.

C.2.3 FIBDISP—Analyise 3-d Data (spectral)

This performs a similar function to LONGSLIT, but is optimised for three-dimensional data arrays. In interactive use a greyscale softcopy device such as a GWM (the X window you get from GKS) is used, and profiles are selected using a cursor. Alternatively an array of profiles may be displayed using line graphics. If run in batch mode the whole data block may be fitted with Gaussians etc. The same fitting options are available as for LONGSLIT (see section C.2.2). The file should already have a results structure (unlike LONGSLIT, FIBDISP does not create one), this can be created by FIB2CUBE or LONGSLIT.

FIBDISP can handle arrays in which the pixels correspond to a rectangular or hexagonal grid on the sky.

On entry to the program the user is prompted for the name of the data cube and then enters the main menu. Main Menu  The options in the main menu are as follows:

RESULTS
Display a plane of the results block. The plane is accessed by name, and this is one of only two places in the whole of Twodspec that cares about the case of the answer given by the user (the other is MODPARAMS). For example, if you wanted to display the centre of the first component, you would enter “Centre_1”.
DATA
Display a plane of the data
PROFILE
Examine line profiles. The profiles are selected using a cursor. If more than one is selected they are added together. Gaussians etc. may be fitted to the profile, and the results stored. The fitting is similar to that of LONGSLIT. Hard-copy plots of the profile may also be made.
XCUT
Take a cut through the data in the X direction, and display on a greyscale device. The position is marked with a cursor, and the nearest pixels are chosen (i.e. no interpolation).
YCUT
Take a cut through the data in the Y direction, and display on a greyscale device. Similar to XCUT.
XOUT
Output to file X direction cut through data. This is like XCUT, but the output is to a file, rather than an image display.
YOUT
Output to file Y direction cut through data. Similar to YOUT.
IT
Reduce iteration
CHECK
Display an array of line profiles—this can be in soft or hard-copy
TOTAL
Display the summed intensity through the image
LIMIT
Limit X and Y range for display. This acts as a toggle, so if you have limited plots and select this option again, you will return to full range.
TOLS
Apply/set tolerances
LOOK
Look at values in results cube
DELETE
Delete fits from results cube
DEFINE
Define fits for batch mode. The fits are defined and stored in the control array.
OUTPUT
This allows the user to list all the fits onto the line printer, or to produce hardcopy plots of all the fits.
EXIT
Leave the program
CUBAN
Cuban-style display/motion. This is better than CHECK for large data-sets (such as from TAURUS). An array of profiles is plotted, with a small greyscale representation of the total intensity in the top right-hand corner—the centre of the array plot is marked on this with a cross. The user has the following options (decided by cursor keys):
A
Add profiles to fit (end with F)
C
Centre here
D
Down
E
Exit
F
Make fit to point
H
Make hardcopy of current plot
J
Jump to new area (using greyscale plot)
L
Left
P
Indicate position
R
Right
S
Set scaling for profile plots
U
Up
X
Erase fit
?
Help
Note that the following options require the use of a greyscale display: RESULTS; DATA; XCUT; YCUT and TOTAL, although PGPLOT is capable of producing a simulated greyscale on line graphics devices, if the array is rectangular. Summary of Parameters 
CUbe
(file) Cube for display
YStart
(int) analysis lower limit
YEnd
(int) analysis upper limit
YBlock
(int) Enter analysis x-sect width
TStart
(int) analysis lower limit
TEnd
(int) analysis upper limit
TBlock
(int) Enter analysis blocking width in 3rd dimension
DEvice
(char) Device for display
ITeration
(short) New value of iteration
VCorr
(float) Correction to apply to radial velocities
TOls
(char) For use in batch only
FITRat
(real) Ratio of widths, heights, or separation, for double fits
CAlrat
(int) Ratio of number of iteration to default
OUTPut
file: Name for output file
FIT_MODEL
(char) Model for fitting
LOw
(float) Minimum value for display
HIgh
(float) Maximum value for display
ABsorption
(key) Allow fitting of absorption lines
BOunds
(key) Perform bounded fits to lines (in batch)
HArdcopy
(key) Produce hardcopy plots of fits from cube
TAble
(key) Produce table of fits from cube
PRInt
(key) Produce print out of radial velocities
KEEP_ITT
(key) Keep iteration files
FIT
(key) Perform fitting
WEIghts
(key) Use weighted fitting (default is true). This only applies if the file contains an error array.
PRFits
(key) Print out details of fitting. When fitting large data-sets in batch this would normally be set to false, otherwise a very large log file will be created.
SHAPE is not yet implemented.

C.3 ARC2D—Wavelength Calibration

C.3.1 Introduction

Once the data has been corrected for distortions or has been “cleaned”, it must be converted to a linear (calibrated) scale in wavelength, or at least the relationship must be defined. In practice it is much easier to handle a re-binned file.

The “traditional” way of doing this is to take one or more spectra of an arc lamp (which has lines of known wavelength), using the same spectrometer arrangement, fairly close in time to the exposures of the objects. This spectrum will contain information on the wavelengths corresponding to different channels. The user will then indicate the locations of the lines in some way to a program, and then this program will find the centroid of each line at each cross-section, or group of cross-sections—a block). These positions are then used to obtain the relationships of the channel number to wavelength, by fitting polynomials to the line positions and wavelengths. The coefficients of these are then used for the re-binning onto a linear scale.

This reduction method has several disadvantages:

ARC2D is a two-dimensional arc calibration program. It makes use of a calibration arc as above, but Gaussians are fitted to the arc-lines in order to locate them with maximum precision, as well as to give information on errors. The continuity of the arc lines is taken into account. Rather than locating the line centres immediately prior to fitting the polynomials (to determine the dispersion relationship) whilst travelling up the spectrum, ARC2D finds all the line centres, and the fit to any cross-section can be checked, and poor lines rejected. Then all the polynomials can be fitted and, if satisfactory, written to the output file. Conventional programs require the order of the polynomial and the arc lines to be used to be guessed, before any fits are made (or at best when only one cross-section or block has been fitted)!

The line identification part of ARC2D is the same as for LONGSLIT (see section C.2.2).

The line positions ARC2D has at this stage are approximate since they are only lower and upper limits in channels for the optimisation.

The lines are then accurately located (automatically) at each cross-section by fitting Gaussians to them, assuming a Gaussian can successfully be fitted. For this the data from successive cross-sections can be blocked together, to improve the signal to noise ratio. In our case we typically co-add ten successive cross-sections. This fitting is a least squares optimisation, including a flat base, and is the same as used for LONGSLIT.

ARC2D creates a file for use with ISCRUNCH. Weighted fitting may be used for the polynomials to determine the dispersion relation. In addition polynomials may be fitted to the relation of line centre to cross-section for each line, and the polynomial values from this fitting used instead of the Gaussian centres, to give a smooth variation of the dispersion relation across the spectrum.

To use ARC2D you should do the following:-

(1)
Set up tram arrays—to to tell the program where the lines are and to identify them
(2)
Fit Gaussians to lines.
(3)
Apply continuity correction (this is not essential).
(4)
Fit polynomials to define the correction to be applied to “scrunch” the data (you automatically end up here unless you answer “YES” to leave program now...).
(5)
If you are satisfied with the fits, create a calibration file and use it as input to ISCRUNCH.

Parts (1) and (2) above are as for LONGSLIT, except that only AUTO mode is available for (2) and the program will follow any curvature of the lines during fitting.

In the main menu LOOK, TOLS,EXIT and ADD are the same as in LONGSLIT, and GAUS is similar to the AUTO option in LONGSLIT. POLY and DISP are described in the next two sections. SOFT and HARD produce plots of use in determining which lines to include in the fitting. These are of line centre against cross-section, line width against centre and error on centre v. height.

C.3.2 Continuity Correction

In order to avoid “steps” in the scrunched data, it is advisable to use this option for long-slit spectra (of course this isn’t applicable to data such as form fibre arrays where a smooth curve is not to be expected). Select the POLY option in the main menu:

  =========< M a i n   M e n u >=========
  
  Look   : Look at values of data cube
  Gaus   : Fit Gaussians to line profiles
  Soft   : Produce soft-copy plots of diagnostics
  Hard   : Produce hard-copy plots of diagnostics
  Tols   : Apply tolerances
  Disp   : Evaluate dispersion relation
  Add    : Add more lines
  Poly   : Fit polynomials in X-Sect direction
  Exit   : Leave the program
  Main Menu [EXIT] - POLY
  keep fits with nag errors for poly fitting? [NO]
  Weight fits? [YES]
  Performing weighted fit

A plot of the sum of the squares of the residuals against order is displayed.

  Go onto next plot? [YES]
   S E E K   M E N U

The residuals are plotted against cross-section. When these appear to be due to noise only, answer “NO” to leave the loop, and reply with the order required. A plot of the fit over the centres is given, and similar plots are displayed (two to a page) for the remaining lines, but can be suppressed.

  Y for next plot;N to stop [YES]
  Y for next plot;N to stop [YES]
  Y for next plot;N to stop [YES] NO
  (ORder) order for polynomial fitting [3] -
  Order returned =   3
  Further plotting may be suppressed by typing ‘‘N’’
  Go onto next plot? [YES]
  Performing weighted fit
  Go onto next plot? [YES]
  Performing weighted fit
  Go onto next plot? [YES]
  Performing weighted fit
  Go onto next plot? [YES] NO
  Performing weighted fit
  Produce hardcopies of line centre & residual plots [NO]
  
  =========< C o n t i n u i t y   F i t s >=========
  
  Accept   : Accept fits
  Retry    : Try again
  Quit     : Give up
  Continuity Fits [ACCEPT] -

The results are now stored and the user returned to the main menu.

C.3.3 Evaluating the Dispersion Relation

Select the DISP option at the main menu:

  =========< M a i n   M e n u >=========
  
  Look   : Look at values of data cube
  Soft   : Produce soft-copy plots of diagnostics
  Hard   : Produce hard-copy plots of diagnostics
  Tols   : Apply tolerances
  Exit   : Leave the program
  Disp   : Evaluate dispersion relation
  Gaus   : Fit Gaussians to line profiles
  Add    : Add more lines
  Poly   : Fit polynomials in X-Sect direction
  Main Menu [EXIT] - DISP

You now are given a list of the lines on the graphics screen. You can hit “?” to see what the options are. This part of the program is designed to be used with a cursor, rather than using menus. You can edit line lists, set parameters, etc. Typing “f” will then perform a fit and you will be given plots of the fit and residuals.

When you have the fit/residuals plots, the lines used are shown with filled-in markers, and open markers indicate unused lines. Note that, although the lines used are updated on the lower plot, only when you hit “f” again will new fits be performed, so until then the residuals etc. will refer to the old fit.

   ARCFIT :   Order = 3,  cross-section 85
  
  Coefficients of fit are -
  
    8.27062E-16 -3.97077E-12  3.86509E-09
    4.17852E-06  0.00000E+00  0.00000E+00
  
  Start wavelength = 4827.310,     End wavelength = 5152.441
  Central wavelength = 4989.621,   Mean dispersion (per channel) = 0.1601613
  
            Line    Wavelength    Calculated   Discrepancy
                                  Wavelength
  
          133.35       4847.81       4847.81          0.00
          396.13       4889.04       4889.06         -0.02

A list of line wavelengths with fitted wavelengths is written to the terminal. If there are any lines not used in the fit, these are still output (after those which are used), so that, if required, estimates of the wavelengths of unidentified lines can be obtained.

         1646.52       5090.50       5090.51         -0.01
         1971.84       5141.78       5141.78          0.00
  
  Chi-squared(ang**2) = 1.1019063E-04

The fits should be checked at several positions across the data and, when satisfactory, the tables etc. should be suppressed, and the results written to a file (the “A” option will accept the fits). If “continuity corrected” data is used, then each cross-section is treated separately, otherwise each block is treated as one fit.

  Minimum start wavelength = 4824.331, maximum end wavelength = 5153.783
  Copy any coefficients from one line to another? [NO]
  Fits OK? [YES]
  
  Summary of Image Arc Fit Results -
  -----------------------------------
  
  Image dimensions  2040 by   171
  Number of rows that could not be fitted =     0
  Maximum chi-Squared error =       0.00
  Maximum degree polynomial used =   3
  
  Fit results written to matching .iar file
  
  
  =========< M a i n   M e n u >=========
  
  Look   : Look at values of data cube
  Gaus   : Fit Gaussians to line profiles
  Soft   : Produce soft-copy plots of diagnostics
  Hard   : Produce hard-copy plots of diagnostics
  Tols   : Apply tolerances
  Disp   : Evaluate dispersion relation
  Add    : Add more lines
  Poly   : Fit polynomials in X-Sect direction
  Exit   : Leave the program
  Main Menu [EXIT] -
C.3.4 Summary of Parameters
IMage
(file) Name of image for input. This should be a file containing an arc spectrum.
ARC_OPTS
(char) Enter arc fit option:
NEW (N)
set up a new wavelength calibration
REPEAT (R)
Iterate on previous calibration.
CLONE (C)
CLone a previous calibration.
YStart
(int) analysis lower limit The data between the limits ystart and yend is extracted and the resultant spectrum is used to locate the lines.
YEnd
(int) analysis upper limit. The data between the limits ystart and yend is extracted and the resultant spectrum is used to locate the lines.
YBlock
(int) Enter analysis x-sect width Each window is of this width (except perhaps the final one).
ITeration
(short) New value of iteration
ORder
(int) order for polynomial fitting This is for the continuity correction of the data. Ideally the arc should have been pre-processed with ARCSDI, so a low order e.g. 2 should be used.
MAXLines
(int) 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
(file) Name of image for cloning from. This should be a file containing an arc spectrum.
TOls
(char) For use in batch only
KEEP_ITT
(key) keep iteration files
PRFits
(key) Print out details of fitting

C.4 COMB and ARCSDI-Correction for Geometrical Distortions

C.4.1 COMB—Correction for S-Distortion

This program takes a long-slit spectrum with one or more continua, and creates a file which allows it to apply a correction to further files, such that the continua are made straight. This performs a similar function to the FIGARO function SDIST, but is more automatic (it may be run completely in batch if required).

Since the philosophy of all the software we have written is to be as automatic as possible, COMB will automatically find the “teeth” of the comb, and can be run completely in batch, if so required. This enables quicker processing of data, since in practice the order required for the Chebyshev polynomials is found to be 3 for all combs on which the program has been run. It is probably best, however, to initially locate the teeth interactively (for setting the values in the tram arrays, which define the edges of the line at the centre of the data), since some experimentation may be required. The operation of COMB is as follows:

(1)
Locate ‘teeth’. A cut is taken from the data, along the slit direction, from the central 20 channels of the data. The algorithm looks for the highest point in this data, and searches outwards to find other teeth, whether a new “tooth” is accepted depends upon the value of the parameter LEVEL, which is the minimum acceptable ratio of an new tooth’s height to that of one already accepted. If too many or too few teeth are found, a different value of LEVEL may be used, or the teeth may be selected manually. To confirm the correct location of teeth, these are output to the user (or batch log file), at the start of the program. Thus a check of the teeth locations may also be made if they are located in batch.
(2)
The program then follows the “teeth” along the image (in the channel direction), finding the line centres by fitting Gaussians, or alternatively by finding centroids. Finding centroids is quicker than fitting Gaussians, and may be more suitable for some data. Fitting Gaussians is often more accurate, and gives estimates of the errors. For this the program will co-add a number of channels (say 20) to obtain a higher signal to noise (and reduce the time taken to find the centres). The teeth are located in the centre of the data (in the channel direction), and followed out from there in both directions (they are likely to be strongest in the centre). Since the variation along the image may be considerable, the tram positions (the Y values of the range used for fitting) must be updated using the centre from the last fit, before being used. This enables the program to follow the continua.
(3)
The points so obtained are fitted with Chebyshev polynomials (for each tooth). If the parameter ORDER, the order of the polynomial to be fitted is specified in the command line, then it is taken as that. Otherwise the program plots the residuals for each order until told to stop, and then prompts for the order. In batch mode the program will exit at this stage unless ORDER is given in the command line. This is similar to the continuity correction part of ARC2D (see section C.3.2).
(4)
The Chebyshev polynomials are then evaluated at each channel for each “tooth”, within the limits used for fitting the polynomials, and the points outside these limits are evaluated using (local) cubic splines (Akima 1972). When a value for the cross-section position of each “tooth” has been obtained, these are used for interpolating (again using cubic splines), the values of the data at the positions at the current channels corresponding to each cross-section at the reference position (the central channel). The correction is such that the data is lined up with this reference channel.

COMB outputs plots of the locations of the teeth at the start (i.e. at the central channel) and a few other points along the data, and also outputs a plot of the positions of all the points on the teeth found by the Gaussian fitting, enabling a check to be made as to whether the results seem reasonable. Plots of the polynomial fits to the teeth and of the residuals on these fits (typically up to about 0.2 cross-sections) are also output. If running interactively these are in soft-copy, otherwise in hard-copy. To apply the correction, use OLD mode, the correction file (i.e. the file with the polynomial coefficients) is COMB.GMC.

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 locates the 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, centroids are used rather than the fitting of Gaussians. Since fitting Gaussians is generally quite fast, this is only really likely to be needed when the profiles are significantly different from Gaussian. Summary of Parameters 

IMage
(file) Name of image for input. This should be a file containing continua spectra.
ARC_OPTS
(char) Enter arc fit option:
NEW (N)
set up a new wavelength calibration
REPEAT (R)
Iterate on previous calibration
CLONE (C)
CLone a previous calibration
OLD (O)
Correct using previous results
OUtput
(file) Name of output file. File to contain corrected data.
XStart
(int) analysis lower limit. The data between the limits xstart and xend is extracted and the resultant spectrum is used to locate the lines.
XEnd
(int) analysis upper limit. The data between the limits xstart and xend is extracted and the resultant spectrum is used to locate the lines.
XBlock
(int) Enter averaging width in channels. Each window is of this width (except perhaps the final one).
ITeration
(short) New value of iteration
LEvel
(float) Level of edge of tooth
ORder
(int) order for polynomial fitting This is for the continuity correction of the data.
MAXLines
(int) 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
(file) Name of image for cloning from. This should be a file containing an comb spectrum.
TOls
(char) For use in batch only
KEEP_ITT
(key) keep iteration files?
QUick
(key) Centroid rather than fit Gaussians?
PRFits
(key) Print out details of fitting
PLOtcorr
(key) Plot correction?
Main Menu 
LOOK
Look at values of data cube
SOFT
Produces soft copy plots of diagnostics
HARD
Produces hard copy plots of diagnostics
TOLS
Apply tolerances
POLY
Fit polynomials to results
CENTRES
Find line centres-takes a long time. This is similar to the GAUS option of ARC2D.
ADD
Add more lines
EXIT
Exit program
C.4.2 ARCSDI—Correction for Line Curvature

This corrects data for line curvature, using an arc spectrum. The function is the same as for comb, but it works in the perpendicular direction (again this is for long-slit spectra).

The aim is to give ARC2D a spectrum with fairly straight arc lines, so it can ‘block’ more cross-sections together to obtain a higher signal to noise. The operation is similar to parts (1) to (3) of ARC2D, except that ARCSDI does not need to know the line identifications. To apply the correction, use OLD mode, the correction file (i.e. the file with the polynomial coefficients) is ARCSDI.GMC. The main menu is the same as for COMB.

The arc lines are located using much of the same code as in ARC2D described below, including the fitting of Gaussians. The reason for doing preliminary correction of this nature, rather than using ARC2D straight away, is that for data which is fairly noisy, it is desirable to give ARC2D as many cross-sections at a time for the fitting. It is intended that ARCSDI be used with a long exposure from a chimney arc. Another problem overcome by this is that of vignetting which occurs in the comparison arc optics of the RGO spectrograph at the AAT. ‘Chimney’ arcs are reflected off the dome, and do not suffer from this problem (the same optical path is used as for the observations). It is often an advantage to use an arc from another wavelength range, if this has more suitable lines, or if they are better distributed along the spectrum.

Once the lines are located, they are treated in much the same way as the positions of continua in COMB. Chebyshev polynomials are fitted to these and the results used to determine the required shifts. Summary of Parameters 

IMage
(file) Name of image for input. This should be a file containing an arc spectrum.
ARC_OPTS
(char) Enter arc fit option:
NEW (N)
set up a new wavelength calibration
REPEAT (R)
Iterate on previous calibration
CLONE (C)
CLone a previous calibration
OLD (O)
Correct using previous results
OUtput
(file) Name of output file File to contain corrected data.
YStart
(int) analysis lower limit The data between the limits ystart and yend is extracted and the resultant spectrum is used to locate the lines.
YEnd
(int) analysis upper limit The data between the limits ystart and yend is extracted and the resultant spectrum is used to locate the lines.
YBlock
(int) Enter analysis x-sect width Each window is of this width (except perhaps the final one).
ITeration
(short) New value of iteration
ORder
(int) order for polynomial fitting This is for the continuity correction of the data. Ideally the arc should have been pre-processed with ARCSDI, so a low order e.g. 2 should be used.
MAXLines
(int) 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
(file) Name of image for cloning from This should be a file containing an arc spectrum.
TOls
(char) For use in batch only
KEEP_ITT
(key) keep iteration files
PRFits
(key) Print out details of fitting
PLOtcorr
(key) Plot correction? This is used with the OLD option.

C.5 Display Programs

C.5.1 ISCAN—Plot Spectra Extracted From an Image

This produces plots of 1-d spectra which it extracts from a long-slit spectrum (i.e. it acts as if it were a wrap-up of the FIGARO functions EXTRACT and SPLOT). To use ISCAN just set the hard or softcopy device using HARD or SOFT, then type ISCAN, and answer the questions. To use in batch follow the instructions given by the program BATCH. Summary of Parameters 

IMage
(file) Name of image for input
XStart
(float) display lower limit
XEnd
(float) display upper limit
YStart
(int) display lower limit
YEnd
(int) display upper limit
YBlock
(int) Enter display x-sect width
SCan
(key) Scan through data
HArd
(key) use hard graphics device for display
C.5.2 HIMAGE—Greyscale Display

This uses GKS to plot a greyscale image of an image (in the FIGARO sense). It can plot on a GKS greyscale device such as a GWM or Postscript laser printer. The plot can include a key. Unfortunately this program takes a fair time to scale the image, so will “sit there” for a minute or so before anything appears on the screen (this does, of course, depend upon the image size). The parameters are as follows:

IMage
(file) Name of image to be displayed
YStart
(int) First Y value to be displayed
YEnd
(Int) Last Y value to be displayed
XStart
(int) First X value to be displayed
XEnd
(int) Last X value to be displayed
Low
(int) Minimum count level for display
High
(int) Maximum count level for display
PLOTdev
The device to plot on (translated using GNS, so should be “xwindows” etc.).
ASPect
This is the aspect ratio (X/Y) of the plot (excluding any key). The default is set to the value which gives square pixels.
SHRINK
This gives a wide margin to the plot.
LOG
(key) Display using logarithmic scaling
KEY
This plots a key giving the data values corresponding to given greyscale values.
C.5.3 CSCAN—Plot Array of Line Profiles from Data “Cube”

This produces as array of line profiles from a 3-d data array, where the first dimension corresponds to wavelength. The data is scaled using the maximum and minimum intensities in the whole data cube, rather than of the individual profiles. Summary of Parameters 

CUBE
(file) Name of CUBE for input
YStart
(float) display lower limit
YEnd
(float) display upper limit
TStart
(int) display lower limit
TEnd
(int) display upper limit
HArd
(key) use hard graphics device for display
As regards the parameters, Y is the first spatial dimension and T the second.

C.6 Removing Continua

C.6.1 FITCONT—Fit Polynomial to Continuum

The optimisation in LONGSLIT allows for a flat base. Although this is generally satisfactory, for some data the base varies significantly. The user then has various options: the base can be subtracted from the using CSUB (which subtracts a polynomial fit to the base from the data); the data can be divided by the base; or the base can be left as it is, but a polynomial fit can be subtracted during the actual fitting. The latter option has the advantage that any plots of line profile etc. will still show the base as in the original data. This option is available by the use of the routine FITCONT, or totally within LONGSLIT. In general it is better to use the version in LONGSLIT, but this will not always cope with “difficult” data sets, so FITCONT may be required. The main difference here which allows FITCONT to deal with these cases is that it allows the weighting to be set using a cursor (in LONGSLIT it is done simply by excluding the areas within line boundaries, which is less versatile). This is similar to CSUB in fitting a Chebyshev polynomial to the base. However the data itself is not altered. When LONGSLIT fits a line it can subtract this base. Alternatively the base may be interpolated over the line using cubic splines (FITCONT is not needed for this). Summary of Parameters 

IMage
The file with the data in
XSect
The cross-section to use for the first fit
C.6.2 CSUB—Subtract Continuum

This is similar in function to FITCONT, except that is performs the continuum subtraction itself.

C.6.3 CADD—Add Back Continuum Previously Subtracted

This add back a continuum previously subtracted using CSUB, making use of the information CSUB stores in the data file.

C.7 Getting 3-D Data into the Correct Form for FIBDISP or LONGSLIT

These programs were designed for use with a fibre array on the Manchester Echelle Spectrometer (Meaburn et al 1984). The fibres effectively make it a multi-slit spectrometer, with the fibres gathered into three (for example) rows at the input to the spectrometer. The first task is to extract the data from the individual fibres, the data is then wavelength calibrated and combined into a three-dimensional array, simulating the relative positions of the input ends to the fibres. FIBSEP extracts the data from the individual fibres into what looks like a long-slit spectrum for each row of fibres (at their output end). ARC2D can then be used for the wavelength calibration, and FIB2CUBE will re-arrange them into the format required for FIBDISP (FIB2CUBE also created the results structure).

C.7.1 FIBSEP—Extract Data from Individual Fibres

This separates out the individual fibres from a 2-d spectrum. It is assumed that the data had previously been corrected for S-distortion. This first produces a greyscale plot of the data (in a GWM window for example), and then the user is asked to mark two fibres and the limits (in X) that the program is to consider. If there is more than one “slit”, then each must be dealt with by separate runs of the program. The method is to find the centres of the fibres by fitting Gaussians, and to divide the data half-way between these points. Since the separation of the fibres may vary slightly, the user is recommended to use CSUB on the data first. This method is fairly crude and the user may well wish to improve upon it, but if all that is required is radial velocities this should be adequate. Summary of Parameters 

IMage
(file) Name of image to be displayed
OUTput
(file) Name of image to create
FILE
(char) Name of file for positions of fibres
YStart
(int) First Y value to be displayed
YEnd
(int) Last Y value to be displayed
XStart
(int) First X value to be displayed
XEnd
(int) Last X value to be displayed
Low
(int) Minimum count level for display
High
(int) Maximum count level for display
DEVICE
(char) Plotting device (normally something like “xwindows”)
NFIB
(int) Approximate number of fibres expected
LOG
(key) Display using logarithmic scaling
OLD
(key) Use previous results to extract data
C.7.2 FIB2CUBE—Convert Fibre Data to “Cube”

This converts calibrated long-slit spectra from a fibre array into a 3-d data cube for use by FIBDISP. Data from separate slits should be in different files, prompted for as IMAGE1, IMAGE2, etc. CUBE is the output file. FILE is a file listing the X, Y positions of each fibre in the output array (default type .DAT), probably produced by ENCODE. Note that, although CSCAN can produce plots from a file produced by FIB2CUBE for types “HEX” and “RECT”, these are only correct for type “RECT”. FIB2CUBE create files with all the structures required by FIBDISP. The emission line is delimited using the same code as used in LONGSLIT. The code only allows for one spectral line per file.

IMAGE1
(file) Input image 1
IMAGE2
(file) Input image 2
IMAGE3
(file) Input image 3
IMAGE4
(file) Input image 4
IMAGE5
(file) Input image 5
CUBE
(file) Output data cube
FILE
(char) Name of file with coordinates for output cube This file must contain the two spatial dimensions of the output cube followed by the number of input images in the first record. After that the X, Y coordinates of the input spectra (a cross-section at a time, starting at 1) in the output cube. After that the contents of the X displacement array (if any). Comments lines start with an exclamation mark.
MAXGAUSS
(int) Maximum number of Gaussians that can be fitted to a profile.

C.8 Miscellaneous Programs

C.8.1 CUBE2LONG—Extract a Spectrum from a Spectral “Cube”

This extracts a long-slit-type spectrum from a 3-d data array, which has the dimension corresponding to wavelength last. The values are obtained using local cubic spline interpolation. The program requires a position (xpoint, ypoint) on the “slit”, and an angle. It will then produce a cut through the data, following this “slit” until it reaches the edge of the data in each direction from the given point. Variation of the parameter PIXLEN eases comparison of (for example) TAURUS data with long-slit data. Cubic spline interpolation is used to obtain the data values. Summary of Parameters 

CUBE
(file) Name of cube for input.
OUTput
(file) This is the name of the resulting image.
YPOINT
(int) Y point on slit
XPOINT
(int) X point on slit
ANGLE
(float) pa of slit
PIXLEN
(float) Pixel length
C.8.2 VIG—Correct For Vignetting

This fits a Chebyshev polynomials to templates taken from both directions across an image, and divides the image by the product of the polynomials, normalising so that the data in the centre in unchanged. A file is produced containing the coefficients of this polynomial so that other data files can have the correction applied.

C.9 Note on Menus

Many of the programs use menus to find out what the user requires next. When a menu-type prompt is given, the answer may be abbreviated, as long as a unique match is achieved (in many cases the most abbreviated form is given in brackets). Some menus also allow numbers or additional strings to follow (or even replace) the menu options themselves.

The menu parser can accept the command “%n” to alter the prompting style. At present n can be from 0 (no menu, just menu name) to 3 (full menu, abbreviations given in square brackets). This will then apply to future calls of the menu routine (note that the parameter menus (e.g. ARC_OPTS) are dealt with separately to most of the menus, and only support option 2. Options 0 and 1 are for experienced users, especially if they are working with slow terminal lines (or slow computers!). The formats are as below:

Option 0
  Edit options [] -
Option 1
  Look,Planes,Ascending,Descending,Exit
  Edit options [] -
Option 2
(default)
  =========< E d i t   o p t i o n s >=========
  
  Look       : Look at data values
  Planes     : Move planes of results around
  Ascending  : Sort components by wavelength
  Descending : Sort components by wavelength
  Exit       : Return to main menu
  Edit options [] -
Option 3
  =========< E d i t   o p t i o n s >=========
  
  LOOK          [L] : Look at data values
  PLANES        [P] : Move planes of results around
  ASCENDING     [A] : Sort components by wavelength
  DESCENDING    [D] : Sort components by wavelength
  EXIT          [E] : Return to main menu
  Edit options [] -

For options 1 and 2 the minimum abbreviation is given in upper case.

C.10 The Defaults File

This file (at present called twodspec_defaults.sdf) is used to allow the behaviour of programs to be varied. The elements have the following meanings:

FIT_HANDLER
If this has the value 1 then a condition handler is used during the fitting (this is in addition to the FIGARO default handler). This condition handler is not available with the Sun version.
OPT_STEP
This controls the size of jump between iterations in the fitting. The value multiplies the default.
TOLS
These are the values copied to the TOLS array in the results structure when a new results structure is created. Where appropriate the values will be multiplied by the dispersion.
USEPEAK
If this is 1 then the single component fitting will default to taking the peak as the centre, for guessing.
VACUUM
This is set to 1 to indicate wavelengths are values in vacuum.
AX1_LOG
If this is 1 it indicates that the first axis has a log scale (by default).
AX1_UNITS
The default units for the first axis.
RELATIVISTIC
Type integer, if absent, or of value 1, then a full relativistic furmula is used for Doppler shifts, otherwise the non-relativistic one is used.
DEC
FITS keywords to search to find declination of object (not yet used)
COR_DEC
Mutiplier for values from DEC to convert to degrees (not yet used)
RA
FITS keywords to search to find right ascension of object (not yet used)
COR_RA
Mutiplier for values from RA to convert to hours (not yet used)
EQUINOX
FITS keywords to search to find equinox
UT
FITS keywords to search to find UT
TELESCOP
FITS keywords to search to find telescope name (in form acceptable to SLALIB)
LONG_OBS
FITS keywords to search to find longitude of observatory
COR_LONG_OBS
Mutiplier for values from LONG_OBS to convert to degrees
LAT_OBS
FITS keywords to search to find latitude of observatory
COR_LAT_OBS
Mutiplier for values from LAT_OBS to convert to degrees

If the multipliers are absent they are taken as 1.0.

An example of a defaults file is given below (as shown by Figaro exam):

  twodspec_defaults   Struct
    .FIT_HANDLER   Int     0
    .OPT_STEP      Float   1
    .TOLS[13]      Float   0.10000 3 -3 0.2000 8 1 5 1000 20 5 2.000E-3
                                                        .... 2.000E-3 3
    .USEPEAK       Int     1
    .VACUUM        Int     0
    .AX1_LOG       Int     0
    .AX1_UNITS[20]  Char   Angtroms
    .Z             Struct
      .DATA[1]     Float   0
    .COR_LAT_OBS[1]  Float 1
    .LAT_OBS[8,1]  Char    LAT_OBS
    .LONG_OBS[8,1]  Char   LONG_OBS
    .COR_LONG_OBS[1]  Float -1

In this case COR_LONG_OBS is used to correct for the value of longitude in the file’s being positive east, whereas we want positive west. Note that you can have several values in each array, which would act as a search list (at present up to 5 values).

C.11 References