xspecxspecxspecxspecxspecxspecxspecxspecxspecxspecxspecxspecxspecxspec
 xspec                                                            xspec
 xspec			XSPEC history file format                 xspec
 xspec                                                            xspec
 xspecxspecxspecxspecxspecxspecxspecxspecxspecxspecxspecxspecxspecxspec

    Through the use of the history XSPEC sub-command, a user can produce
a binary file containing the results of his session.  This may be used
by following programs to extract, print, and plot summaries from the
run.  This is particularly useful when reducing large amounts of data
using semi-automatic or batch facilities. 

    The information is included in a history file (default extension
XHS). The file is organized as an SF (standard format) file that
includes a series of packages.  The contents of each package is produced
by a particular XSPEC command, in the order that the commands were
executed.  The following packages are currently defined, n.b. that not
all of these are ouput by the current version of XSPEC (in fact not all
are calculatable in the current version of XSPEC) as indicated by the
preceeding '*'. 
    `SF history'   - the history of the history file (creation, etc). One
		     can also be made every separate time the file is
		     appended to.
    'data files'   - the current data files.  Produced by executing the
		     'data', 'fakeit',  or 'profile' commands.
    'assoc. files' - any changes in the associated files, e.g. the
		     background, response, and correction files.  Produced
		     by the 'data', 'backgrnd', 'response', 'corfile',
		     'fakeit', or 'profile' commands.
    'channels'	   - the current number of channels, and noticed bins.
		     'data', 'ignore', 'notice', 'profile'.
    'model'	   - the current model.  'addmodel', 'model', 'profile'.
    'param def'   - the map from fit parameters and constants to model
		     parameter indices. Also the character string 
		     associated with a particular parameter. 'addmodel', 
		     'model', 'define', 'profile'.
    'param range' - the allowed range of parameters can take (as well
		     as the current values). 'newpar', 'addmodel', 'model',
		     'freeze', 'thaw', 'profile'.
    'fit'	   - the results of a fit, chisquare and fit parameter
		     values, along with their errors as estimated by the
		     correlation matrix method. 'fit'
    'steppar'	   - the values of chisquare for particular values of
		     parameters. 'steppar'
    'error'	   - the actual confidence range of one or more fit
		     parameters. 'error'
    'equiv width'  - an estimate of a models equivalent width. 'eqwidth'
    'flux'	   - current model's flux over a given range. 'flux'
    'spectrum'	   - observed and model spectrum for each bin together
		     with lower and upper energy boundaries. 'dump'
    'time'	   - elapsed time. 'time'
Other packages may be designed in the future.

    The detailed description of the packages:

'data files' have no header and will produce a subsidiary record for each
of the current number of files, in order:
    DGRPNO      i4    - the group number (currently := 1)
    NCHAN	i4    - the total number of pha channels defined for the
			detector.
    NBIN	i4    - the total number of bins in the file before any
			ignores.
    NEWFILE	L1    - the file has changed since the last time the data
			files were defined.
    FNAME	C*    - the data file name (could be as many as 72 chars).

'assoc. files' similarly have no header and will produce a subsidiary 
record for each CHANGE in the background, response, or correction files.
    INDEX	i4    - the index of the corresponding data file number, 
			i.e. the first data file has index 1.
    TYPE	c1    - the type of file, 'R' indicates response, 'B'
			a background file, and 'C' a correction file.
    FNAME	c*    - the file name (as many as 72 chars).

'channels' has a 8 byte header:
    NCHAN	i4    - the total number of unbinned channels for all
			data files (before grouping or ignores).
    NBIN	i4    - the total number of bins for all files (after
			compression/grouping and ignores).
There then follows a series of character strings of not more than 256
characters in length which when concatenated would provide a `gouping' 
card for all the data (see the description of the `grouping' package in 
DATA.DOC). 

'model' has no header, and is followed by a subsidiary record for every 
model component:
    DGRPNO	i4    - the data group number (currently := 1)
    GROUPNO	i4    - the model group number (0 for the initial
			all-multiplicative group of models applied to the
			entire set of models).
    COMPNO	i4    - the component number within a particular group
			(multiplicative models by definition have COMPNOs
			larger than all additive models of a goup).
    spare	8     - spare
    MNAME	c*    - the model name (as many as 8 chars).

'param def' has no header, and is followed by a subsidiary record for every
model parameter:
    MODIND	i4    - the index of the model, i.e. it was described by 
			the MODINDth subsidary record of the `model' 
			package.
    PARNO	i4    - the corresponding parameter no. of that model (n.b.
			that the normalization of a model has a PARNO = 0).
    FITIND	i4    - the corresponding fit parameter index.
    spare	8     - spare
    PNAME	c*    - the name of the parameter (as many as 8 chars)

'param range' has no header, and is followed by a subsidiary record for 
every fit parameter:
    FITIND	i4    - the fit parameter index.
    INIT	r4    - the initial value.
    DELTA	r4    - the step size (also indicates frozen/thawed status)
    HARDLW	r4    - the hard lower limit.
    SOFTLW	r4    - the soft lower limit.
    SOFTHI	r4    - the soft upper limit.
    HARDHI	r4    - the hard upper limit.

'fit' has a 24 byte header record containing:
    ERROR	i4    - the value of the error flag at the conclusion of 
			the fit process.
    CHISQR	r4    - the value of chi-squared.
    FUNCT	r4(3) - function values
    NFIT	i4    - number of fit parameters
      followed by 2 subsidiary records of variable length containing:
    VALUE	r4(NFIT)- the values of every fit parameter.
    ESTERR	r4(NFIT)- the estimated error (from the correlation matrix)
			  for every fit parameter.

'steppar' has a 4 byte record:
    NPAR	i4    - the number of parameters being stepped
      followed by NPAR subsidiary records of 20 bytes each
    FITIND	i4    - the fit index number
    NSTEP	i4    - the numbers of steps
    LOWPAR	r4    - the lower limit of the stepping
    HIPAR	r4    - the upper limit of the stepping
    LOG		L4    if true, the steps are logarithmic
followed by a subsidiary record for every set of trial values:
    ERRFLAG	i4    - an error flag returned by the fit routine
    CHISQR	r4    - the value of chisquared
    FUNCT	r4(3) - evaluated function values.
    PAR		r4(NPAR)- the stepped parameters values.

'error' has a 74 byte header record containing:
    ERRFLAG	i4    - indications of an error in the determination.
    CHISQR	r4    - minimum chisquared
    DELCHI	r4    - the delta chisquared defining the confidence range
    FITIND	i4    - the fit parameter no.
    BEST	r4    - the best fit value
    LOW		r4    - the lower fit value
    HIGH	r4    - the higher fit value
    DELLOW	r4    - the actual lower limit chisquared
    DELHI	r4    - the actual upper limit chisqaured
    PEGLOW	L1    - if true, the lower value is pegged 
    PEGHI	L1    - if true, the upper value is pegged
    FUNCT	r4(3) - the best fit function values
    FUNCTLW	r4(3) - the lower fit function values
    FUNCTHI	r4(3) - the upper fit function values

'equiv width' has a 40 byte header record:
    MODIND	i4    - the model index whose equivalent width is being
		        estimated.
    ECNT	r4    - the energy at which the continuum is evaluated.
    CNTPHT	r4    - the continuum photon flux at ECNT.
    ECONLW	r4    - the lower limit of the continuum integration.
    ECONHI	r4    - the upper limit of the continuum integration.
    MODPHT	r4    - the model component photon flux.
    EMODLW	r4    - the lower limit of the model integration.
    EMODHI	r4    - the upper limit of the model integration.
    EQP		r4    - the equivalent width (using photon numbers).

'flux' has a 16 byte header
    ELOW	r4    - the lower limit of the integration
    EHI		r4    - the upper limit of the integration
    PFLUX	r4    - the integrated number of model photons
    EFLUX	r4    - the integrated energy flux

'spectrum' has a 52 byte header 
    NBIN	i4    - the total number of bins after ignore and notice
			commands
    EUNITS	c24    - a character string for the energy units
    CUNITS	c24    - a character string for the units of the spectrum
followed by a subsidiary record of 16 byte for each bin.
    ELOW	r4    - lower energy boundary of the bin
    EHI		r4    - upper energy boundary of the bin
    PHAOBS	r4    - observed spectrum
    PHAMOD	r4    - model spectrum
'time'
    CTIME	c20   - a character representation of the date and time.
    DELTIM	r4    - elapsed clock time
    PERFORM     i4(5) - an array of values used to measure performance
			(e.g. CPU time, page faults, IO ops etc.)