C Twodspec

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.

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:

where $\sigma$ is the standard deviation of the line, $x_0$ 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:

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

where $N$ is the finesse of the etalon, $\mu$ the refractive index of air, $l\left(z\right)$ the etalon spacing, $Q$ the angle to the optical axis, and $\lambda$ the wavelength of the light concerned.

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

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$, $x_0$, 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.

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.

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.

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

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.

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.

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:

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.

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.

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

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

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 s${}^{-1}$ 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).

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:

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

The line is displayed.

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

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

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

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

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:

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.

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

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

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 $10^7$, and then tolerances are applied on height, centre and width.

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!

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.

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

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.

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:

• The process of finding centroids is often less accurate than fitting Gaussians, since is is more prone to errors due to poor signal to noise, or a strong base (especially if this is not constant).
• Finding centroids provides no information on the likely error in the centre. Ideally the strongest lines should be given the highest weights. Conventional programs use unweighted polynomial fitting.
• In treating each cross-section or block separately, the fact that the line centres will vary smoothly (for “normal” data) across the image is ignored. This can give rise to steps in what should be smooth lines, for the re-binned image. If the data from successive cross-sections in blocked together then, even if all the centres lie on a smooth curve, steps will occur in the calibrated data.

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:

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

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.

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:

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.

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.

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.

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?

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

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

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

• Akaike, H., 1973, in 2nd int. Symp. Information Theory, P.267, Eds. Petrov, B. N. & Csaki, K., Akademai Kiado, Budapest
• Bailey, J., 1989, ICL — The New ADAM Command Language
• Bland, J., 1986, Ph. D. Thesis, Univ. of Sussex
• Chipperfield, A. J., 1989, SUN/35.2, ICL — Interactive Command Language: An Introduction
• Frazer, R. D. B. & Suzuki, E., 1969, Anal. Chem., 41,37
• Heckman, T. M., Miley, G. K., van Breugel, W. J. M. & Butcher, H. R., 1981, Astrophys. J., 247, 403
• Lawden, M. D., 1989, SG/4 ADAM — The Starlink Software Environment
• Meaburn J., Blundell B., Carling R., Gregory D.F., Keir D. & Wynne C.G., 1984, MNRAS, 210, 463
• Wallace, P. T., 1987, SUN/78 RV — Radial Components of Observer’s Velocity
• Wallace, P. T., 1990, SUN/67 SLALIB — a Library of Subprograms
• Whittle, M., 1982, Ph. D. Thesis, Univ. of Cambridge
• Whittle, M., 1985, MNRAS, 213, 1
• Wilkins, T. N., 1988, Ph. D. Thesis, Univ. of Manchester
• Wilkins, T. N. & Axon, D. J. 1991, Astronomical Data Analysis Software and Systems 1, Astronomical Society of the Pacific Conference Series, 25, 427