The Contents of the Twodspec Longslit Results Structure

The Twodspec applications use a unique results structure to store identifications and parameters of line fits.

COMB, ARCSDI, ARC2D and LONGSLIT create a .RES structure in which to store their results. This structure enables repeat fits etc. to be performed easily, as well as making it unnecessary to do all the fits at one time. Most of this structure is mapped and its arrays thus accessed directly from the programs. Data are mapped by the address of the first element of an array in the file's being obtained by the program. Fortran passes all arguments to subroutines and functions by giving their address, although for character data this is the address of the descriptor, which includes the address of the data. Therefore, if this address is passed to the subroutine or function--its value not address--then the called routine will treat the data as a normal array. For character data a descriptor must be constructed and passed by address. In the interests of portability it is better to use an array in common to pass the address, the element of the array at that address is passed (even though that is outside the bounds of the array). For character strings the string must be passed as string(start:end). The arrays are in common so that they can be referenced with the same offset from different subroutines.

Since COMB performs fitting of continua rather than lines, the structure for COMB is different from that for the other programs in that the arrays are dimensioned in channels where other programs would dimension them in cross-sections.

The elements of the structure are listed below :-

.RESULTS   Results
  .DATA_ARRAY[21,5,385,1]  Float 10.50 546515.9 6542.3 1.558 165959.0
                                           .... -1.701E+38 -1.701E+38
  .VARIANCE[21,5,385,1]  Float 100 2.069E+7 0.01732 0.08867 1.29E+8
                                           .... -1.701E+38 -1.701E+38
  .MORE          Struct
    .PARAMS[210]  Char   Space1_posBase      Centre_1  Width_1   Height_
    .REST_WAVE[5]  Float 6548.1 6562.8 6583.6 0 0
    .IDS[50]     Char    [NII]6548 HALPHA    [NII]6584?????????????????
    .TRAML[5]    Float   6542.0 6555.0 6575.2 0 0
    .TRAMR[5]    Float   6553.7 6568.1 6589.4 0 0
    .TWODSPEC    Struct
      .ITMASK[5,385,1]  Short 12 10 12 1 1 12 10 12 1 1 12 10 12 1 1 12
                                          .... 12 12 1 1 12 12 12 1 1
      .CONTROL[3,5,385,1]  Int 101110.0 11000 2000 101110.0 11000 3000
                                        .... 1100 101100.0 11000 1100
      .ITERATION   Short 12
      .FIT_STATUS[3,5,385,1]  Int 301114.0 11000 1000 101111.0 11000
                                          .... 11000 1000 0 0 0 0 0 0
      .SELECT[7,5]  Short 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0
                                       .... 0 0 0 0 0 0 0 0 0 0 0 0 0
      .TOLS[13]  Float   0.01899 3 -3 0.03799 1.52 0.1899 5 100000.0 20
                                           .... 5 2.000E-3 2.000E-3 3
      .OPTSTATE   Struct
        .PAR_STATUS[21]  Int 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0
                                                             .... 0 0
        .FREE_PARAMETERS[21]  Int 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0
                                                     .... 0 0 0
        .LINK_INDEX[21]  Int 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0
                                                             .... 0 0
        .LINK_CONSTANT[21]  Double 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0
                                                         .... 0 0 0 0
        .LOWER_BOUND[21]  Double 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0
                                                           .... 0 0 0
        .UPPER_BOUND[21]  Double 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0
                                                            .... 0 0 0
        .PERIODIC_PARS[21]  Int 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0
                                                             .... 0 0
        .PERIODS[21]  Double 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0
                                                             .... 0 0
        .PERIOD_START[21]  Double 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0
                                                           .... 0 0 0
      .TEMPLATE   Struct
        .DATA_ARRAY[560]  Float 0 0 0 0 0 0 0 0 0 0 -323.2 8736.9
                                            .... 7299.5 7346.9 7426.4
        .AXIS[1]   Struct
          .DATA_ARRAY[560]  Float 6513 6513.2 6513.4 6513.6 6513.8
                                            .... 6618.8 6619.0 6619.2
      .GROUPS    Struct
        .ALL     Struct
          .TYPE[20]  Char
          .NUMBER   Short 0
          .DATA_ARRAY[5]  Short 0 0 0 0 0
        .SKY     Struct
          .TYPE[20]  Char
          .NUMBER   Short 0
          .DATA_ARRAY[5]  Short 1 1 1 1 1

The .TRAML and .TRAMR arrays store the line positions, that is the limits considered for optimisation (assumed at the centre by ARC2D), the .IDS array stores the line identifications and the .REST_WAVE their wavelengths. The .ARC array is used by ARC2D to decide which lines are to be used in the evaluation of the relationship between channel number and wavelength. If the element of .ARC is 0 then the line is included under all circumstances, if it is 1 then it is included for non-`continuity corrected' data only, otherwise it is not included for any. A value of 4 indicates that no fits are present, while 10 and 11 are the values if the user manually deletes a line which previously had the value 0 or 1 respectively. If arc is 10 or 11 the fits can be `undeleted'.

The TEMPLATE structure keeps a record of the one-dimensional spectrum used for line identification. Since the axis array is also kept, it is possible to CLONE from such an array, even if the main data array has been scrunched.

The DATA_ARRAY array is used to store the results of the Gaussian fitting, and is also used by ARC2D to store the results for the continuity correction. The errors on the results are stored as variances in the VARIANCE array. The .PARAMS structure acts as an index to this (used by the program to determine where to store results). The .CONTROL array gives the fit type to be performed (in the same form as the fit status element of the .RESULTS structure). In the above example, 171 is the number of cross-sections in the image and 10 is the maximum number of lines allowed for in the structure (this can be up to 50). Originally the block number was stored, but this gave an ambiguous way of determining where the block starts and ends. Therefore the starting cross-section of the fit is now stored (it is possible to change the blocking and only alter a small number of fits).

The fit is performed on data extracted from `nwindow' cross-sections starting at `first cross-section'.

Element	Digit	Number	Name			Refer to as	Meaning
1	1	1	Absorption flag		FIT_ABS	0 - Emission
								1 - Absorption
	2	2	Profile Model		FIT_MODEL	0 - none        
	3							1 - Gaussian        
								2 - Skew Gaussian 
								3 - Cauchy/Gaussian 
								4 - Centroid
								5 - Lorentzian
	4	3	Fit type		FIT_TYPE	0 - none
	5							1 - single
								2 - double (fixed separation)
								3 - double (fixed width ratio)
								4 - double (fixed height ratio)
								5 - double (independent)
								6 - Multiple
	6	4	Number of Components	FIT_NCMP	or may act as maximum
	7	5	Profile Weight Method 	FIT_WEIGH	0 - Uniform
								1 - Variance
								2 - BIweights
								3 - Hubber - This is a Robust estimator
								4 - Cauchy
								5 - Not used
								6 - Not used
								7 - Not used
								8 - Not used
								9 - Not used
	8	6	Profile Fit Status	FIT_STAT	0 - No fit
								1 - Success
								2 - Nag error (not serious)
								3 - Nag error (serious)
								4 - Crash
								5 - Failed tols
								6 - Failed tols (non-serious Nag)
2	1	7	Manual guessing flag	FIT_MAN		0 - No manual guessing
								1 - Manual guessing (between below and fit)
	2	8	First Guess method	FIT_GUES	1 - Centroid
	3							2 - Peak
								3 - Bimodef
								4 - Inherit FORWARD
								5 - Previous answer at this place
								6 - Inherit BACKWARD
								7 - REGION (2d for TAURUS -to be defined)
								8 - ROBUST estimator
								9 - MODEL (synthetic model eg rotation curve)
								10 - P Cygni
	4	9	Optimization method	FIT_OPT		Choice of routines
	5	10	Component number contrl	FIT_STST	0 - Fit up to number of components requested
								1 - AIC after fitting
								2 - AIC, before fitting (using guesses)
	6	11	Constraints Method	FIT_CONSTR	0 - No Constraints
								1 - Bounds only
								2 - General Constraints (read from constr. struc.)
								3 - EQUATIONS  -read from equations Struct
	7	12	Dynamic weights flag	FIT_DYNWEI	0 - no dynamic weights
								1 - Use dynamic weights
	8	13	Fit group		FIT_GROUP	Number of group
	9
3	1	1	Method of Removal	BACK_REMOV	0 - subtract
								1 - divide
	4	3	Background Order	BACK_ORDER 
	5
	6	4	Weight Func. to be used	BACK_WEIGH	as for entry 5 above
	2	2	GLOBAL Backgrnd model	BACK_MODEL	0 - No base
	3							1 - Flat Base
								2 - Cubic Spline\\
								3 - Chebyshev fit NOW
								4 - FITCONT cheby
								5 - Power law
								6 - Black Body
								7 - EMPIRICAL
								8 - Black Body with Optical Depth Cutoff
	7	5	Optimization Method	BACK_OPT
	8	6	local Fit flag		BACK_LOCAL	0-9 Codes as above
	9	7	Success of FIT		BACK_STAT

For background model 3 the polynomial is fitted immediately before the line profile fitting is carried out. For background model 4 the polynomial is evaluated using coefficients previously stored in the data file and subtracted before fitting.

The FIT_STATUS array contains information as to the type of fit performed and as to the success or otherwise of the fit (see table ).

Only LONGSLIT and FIBDISP are able to fit multiple Gaussians, so ARC2D, COMB, and ARCSDI use a smaller results structure.

The last element in this direction is the density scale factor, used for scaling previous fits for use as first guesses to another fit.

The elements of the CONTROL array are the same as those of the FIT_STATUS array, except that they do not include information on the success of the fit. This array is used to set which type of fit is to be performed.

The .ITMASK array and .ITERATION are used in conjunction to prevent accidental refitting of data. Note that a check is made to prevent a fit being accidently overwritten by a simpler fit. The order of increasing complexity is: single Gaussian, skew Gaussian, Cauchy function, double Gaussian, multiple Gaussian. Both this type of checking and the checking using .MASK and .ITERATION can be overridden in MANUAL mode.

The .TOLS array provides a way of retaining the values for tolerances between successive work on the same file, and also (using the FIGARO function LET, or the CLONE COPY option in LONGSLIT), provides a way of transferring these from one file to another. This retention enables tolerances to be applied in batch, since it is much simpler to specify which tolerances to apply, rather than to list all the values to use. It is also used during multiple fitting in batch to determine the number of components to fit.

The results structure for three-dimensional data arrays used by FIBDISP is similar to the above, but has some extra elements. The VARIANT element gives the form of the relationship between the array elements of the main data array, and their actual positions. For type=`HEX' there is a .XDISP array: XDISP[IY] defines the displacement in the X direction of the .Z.DATA[IX,IY], relative to the value given by X.DATA[IX] (that is the element of the data of axis number one). ORDER (at present always `SORT') indicates whether the data are arranged with the first or the last array index varying over wavelength. SORT corresponds to the first axis being wavelength. TOTAL_INTENSITY stores the total intensity integrated along the wavelength axis, and is useful for locating interesting areas of the data.