OGIP Memo 92-009

The File Format for XSPEC Table Models

Keith A Arnaud

Code 662, NASA/GSFC, Greenbelt, MD20771

Version: 1999 Jun 25

SUMMARY

The file format used for XSPEC table model files is described.

Intended audience: users of XSPEC who wish to write their own table models.

1 INTRODUCTION

XSPEC has three models that allow a user to specify a filename from which the model spectra will be read. These models are atable for additive models, mtable for multiplicative models, and etable for exponential multiplicative models.

The basic concept of a table model is that the file contains an N-dimensional grid of model spectra with each point on the grid having been calculated for particular values of the N parameters in the model. It is up to the creator of the table model file to decide what an appropriate spacing is for each parameter. XSPEC will interpolate on the grid to get the spectrum for the parameter values required at that point in the fit. There is the option for each parameter of linear or logarithmic interpolation.

N-dimensional grids of model spectra can get rather large so a simplifying trick is available. If a parameter is decoupled from the other parameters and adds to the model spectrum in a linear fashion then it can be set up as an “additional parameter”. If there are N “interpolation” (ie standard) and M additional parameters then the grid of model spectra will be N-dimensional with each point on the grid containing M+1 model spectra. The first of these spectra is for the model with all the additional parameters being zero. The Ith spectrum (I=2,...,M+1) is the difference between the first spectrum and the spectrum from the model with the I-1th additional parameter set to one and all the other additional parameters set to zero.

An example of the use of additional parameters is a low density, collisional, plasma model where the contribution from each heavy element can be stored as a separate spectrum. In this case, there is one interpolation parameter (the temperature) and as many additional parameters as there are heavy elements in the model.

The atable model requires the table model to contain spectra in units of photons/cm^{2}/s (the standard for additive models models). XSPEC will include a normalization parameter. The mtable model requires a table model to contain multiplicative factors by which an additive model is to be modified. The etable model takes the numbers in the table model, multiplies them by -1 and exponentiates them. This is primarily intended for absorption models and is set up this way so that elemental abundances can be treated as additional parameters. For all these models XSPEC will add a redshift parameter if the REDSHIFT keyword in the table model file is set to true. If the redshift parameter is non-zero XSPEC will shift the model in energy space and divide by a (1+z) factor for time dilation.

2 A historical note

This file format supercedes the non-FITS format used in XSPEC prior to v8.6. This old format was a direct-access binary file and was not easily internally documented or transported across disparate systems. XSPEC used a different direct-access binary file format to store the model spectra tables used in the raymond model and this suffered from the same problems.

The new FITS file format described here and is used both for the table models and for the raymond model. This has the spinoff that a file created for the raymond model can be read as a table model thus providing greater flexibility for users wanting to run the raymond model using a different grid of temperatures or different energy bins.

3 The FITS file format

3.1 Primary header

The file will contain a header and a number of BINTABLE extensions. The main header will include the following information :

1. MODLNAME - the name of the model (string of 12 characters max).

2. MODLUNIT - the units for the model (string of 12 characters max).

3. REDSHIFT - whether redshift is to be a parameter (logical).

4. ADDMODEL - whether this is an additive model (logical).

It should also include the standard OGIP keywords :

HDUCLASS ’OGIP’ HDUCLAS1 ’XSPEC TABLE MODEL’ HDUVERS ’1.0.0’

3.2 PARAMETERS extension

There will be a BINTABLE extension called PARAMETERS containing the parameter definitions and tabulated values. The header keywords will be :

1. NINTPARM - the number of interpolated parameters (integer).

2. NADDPARM - the number of additional parameters (integer).

and the columns will be :

NAME 12A name of the parameter.

METHOD  J  interpolation method (0 if linear, 1 if logarithmic)
INITIAL  E  initial value in the fit for the parameter
DELTA  E  parameter delta used in fit (if negative parameter is frozen)
MINIMUM  E  hard lower limit for parameter value
BOTTOM  E  soft lower limit for parameter value
TOP  E  soft upper limit for parameter value
MAXIMUM  E  hard upper limit for parameter value
NUMBVALS  J  the number of tabulated parameter values

VALUE nE the tabulated parameter values (n is NUMBVALS)

Neither METHOD or VALUE are set for the additional parameters. The six numbers in the INITIAL vector are the start, delta, low, bottom, top, and high parameter values.

This extension should also include the standard OGIP keywords :

HDUCLASS ’OGIP’ HDUCLAS1 ’XSPEC TABLE MODEL’ HDUCLAS2 ’PARAMETERS’ HDUVERS ’1.0.0’

3.3 ENERGIES extension

There will be a BINTABLE extension called ENERGIES containing the energy bins. The columns ENERG LO and ENERG HI comprise the lower and upper energy of each spectral bin. Note that the bins must be contiguous (ie energ hi(i) = energ lo(i+1)).

This extension should also include the standard OGIP keywords :

HDUCLASS ’OGIP’ HDUCLAS1 ’XSPEC TABLE MODEL’ HDUCLAS2 ’ENERGIES’ HDUVERS ’1.0.0’

3.4 SPECTRA extension

The grid of spectra appear in the last extension as a BINTABLE called SPECTRA. The first element in each row is a vector of interpolation parameter values for that spectrum, the second is the spectrum, and the 3rd-(NADDPARM+2)th columns are the contributions due to the additional parameters. The parameter value column is PARAMVAL, the interpolated parameter column is INTPSPEC, and the additional parameter columns are ADDSPXXX. The spectra are ordered with the last parameter changing fastest eg if we have two parameters each of which takes three values (1,2,3) then the spectra are ordered (1,1), (1,2), (1,3), (2,1), (2,2), (2,3), (3,1), (3,2), (3,3).

This extension should also include the standard OGIP keywords :

HDUCLASS ’OGIP’ HDUCLAS1 ’XSPEC TABLE MODEL’ HDUCLAS2 ’MODEL SPECTRA’ HDUVERS ’1.0.0’

4 The WFTBMD routine

Fortran and C subroutines are available to create an output file, write the PARAMETERS and ENERGIES extensions, write the header for the SPECTRA extension, then return with the output file open in the correct place to start writing the tabulated spectra. These routine can be found in the HEAsoft source distribution as the files $XANADU/spectral/tables/wftbmd.{f,c}. The calling sequence for the Fortran subroutine is as follows...

      SUBROUTINE wftbmd(outfil, infile, modlnm, modunt, nintpm, naddpm,
     &                  qrdshf, qaddtv, addnam, addivl, intnam, intivl,
     &                  intntb, intmth, maxtab, inttab, nenerg, energy,
     &                  ounit, ierr, status, contxt)
      INTEGER nintpm, naddpm, maxtab, nenerg
      INTEGER ounit, ierr, status
      INTEGER intntb(nintpm), intmth(nintpm)
      REAL addivl(6, naddpm), intivl(6, nintpm)
      REAL inttab(maxtab, nintpm), energy(nenerg)
      CHARACTER*(*) outfil, infile, modlnm, modunt, contxt
      CHARACTER*(*) addnam(naddpm), intnam(nintpm)
      LOGICAL qrdshf, qaddtv
c Subroutine to open the FITS file and write out all the header information
c down to the point of actually writing the model spectra. At this point
c returns so that the main program can read and write one model spectrum at
c a time.
c Arguments :

c    outfil      c*(*)     i: FITS filename
c    infile      c*(*)     i: Name of original file
c    modlnm      c*(*)     i: The name of the model
c    modunt      c*(*)     i: The model units
c    nintpm      i         i: The number of interpolation parameters
c    naddpm      i         i: The number of additional parameters
c    qrdshf      l         i: Redshift flag
c    qaddtv      l         i: If true this is an additive table model
c    addnam      c*(*)     i: Names of the additional parameters
c    addivl      r         i: Initial values of the additional parameters
c    intnam      c*(*)     i: Names of the interpolation parameters
c    intivl      r         i: Initial values of the interpolation parameters
c    intntb      i         i: Number of tabulated values for interpolation params.
c    intmth      i         i: Interpolation method for interpolation parameters
c    maxtab      i         i: The size of the first dimension in inttab
c    inttab      r         i: The tabulated parameter values.
c    nenerg      i         i: Number of energies (one more than spectral bins)
c    energy      r         i: Energies
c    ounit       i         o: The I/O unit in use.
c    ierr        i         o: error
c                             1 = failed to open FITS file
c                             2 = failed to write primary header
c                             3 = failed to write parameter extension
c                             4 = failed to write energy extension
c                             5 = failed to create model spectra extension
c    status      i         o: FITSIO status
c    contxt      c*(*)     o: Error diagnostic string
c  HDUVERS1 1.0.0

5 Examples

There are two programs in the FTOOLS distribution that create XSPEC table models. These are mekal and raysmith.

5.1 A Raymond-Smith plasma emission model file

This file has one interpolation parameter, the temperature, and 14 additional parameters, the abundances of selected heavy elements.

SIMPLE  =                    T / file does conform to FITS standard

BITPIX  =                    8 / number of bits per data pixel
NAXIS   =                    0 / number of data axes
EXTEND  =                    T / FITS dataset may contain extensions
COMMENT   FITS (Flexible Image Transport System) format defined in Astronomy and
COMMENT   Astrophysics Supplement Series v44/p363, v44/p371, v73/p359, v73/p365.
COMMENT   Contact the NASA Science Office of Standards and Technology for the
COMMENT   FITS Definition document #100 and other FITS information.
CONTENT = 'MODEL   '           / spectrum file contains time intervals and event
FILENAME= '/local/home/genji/kaa/MODELFILES/raysmith.mod' / File that FITS was p
ORIGIN  = 'NASA/GSFC'          / origin of FITS file
MODLNAME= 'raym smith'         / Model name
MODLUNIT= 'photons/cm^2/s'     / Model units
REDSHIFT=                    T / If true then redshift will be included as a par
ADDMODEL=                    T / If true then this is an additive table model
HDUCLASS= 'OGIP    '           / format conforms to OGIP standard
HDUCLAS1= 'XSPEC TABLE MODEL'  / model spectra for XSPEC
HDUVERS = '1.0.0   '           / version of format
END
XTENSION= 'BINTABLE'           / binary table extension
BITPIX  =                    8 / 8-bit bytes
NAXIS   =                    2 / 2-dimensional binary table
NAXIS1  =                  204 / width of table in bytes
NAXIS2  =                   13 / number of rows in table
PCOUNT  =                    0 / size of special data area
GCOUNT  =                    1 / one data group (required keyword)
TFIELDS =                   10 / number of fields in each row
TTYPE1  = 'NAME    '           / label for field   1
TFORM1  = '12A     '           / data format of the field: ASCII Character
TTYPE2  = 'METHOD  '           / label for field   2
TFORM2  = 'J       '           / data format of the field: 4-byte INTEGER
TTYPE3  = 'INITIAL '           / label for field   3
TFORM3  = 'E       '           / data format of the field: 4-byte REAL
TTYPE4  = 'DELTA   '           / label for field   4
TFORM4  = 'E       '           / data format of the field: 4-byte REAL
TTYPE5  = 'MINIMUM '           / label for field   5
TFORM5  = 'E       '           / data format of the field: 4-byte REAL
TTYPE6  = 'BOTTOM  '           / label for field   6
TFORM6  = 'E       '           / data format of the field: 4-byte REAL
TTYPE7  = 'TOP     '           / label for field   7
TFORM7  = 'E       '           / data format of the field: 4-byte REAL
TTYPE8  = 'MAXIMUM '           / label for field   8
TFORM8  = 'E       '           / data format of the field: 4-byte REAL
TTYPE9  = 'NUMBVALS'           / label for field   9
TFORM9  = 'J       '           / data format of the field: 4-byte INTEGER
TTYPE10 = 'VALUE   '           / label for field  10

TFORM10 = '40E     '           / data format of the field: 4-byte REAL
EXTNAME = 'PARAMETERS'         / name of this binary table extension
HDUCLASS= 'OGIP    '           / format conforms to OGIP standard
HDUCLAS1= 'XSPEC TABLE MODEL'  / model spectra for XSPEC
HDUCLAS2= 'PARAMETERS'         / extension containing parameter info
HDUVERS = '1.0.0   '           / version of format
NINTPARM=                    1 / Number of interpolation parameters
NADDPARM=                   12 / Number of additional parameters
END
XTENSION= 'BINTABLE'           / binary table extension
BITPIX  =                    8 / 8-bit bytes
NAXIS   =                    2 / 2-dimensional binary table
NAXIS1  =                    8 / width of table in bytes
NAXIS2  =                 1600 / number of rows in table
PCOUNT  =                    0 / size of special data area
GCOUNT  =                    1 / one data group (required keyword)
TFIELDS =                    2 / number of fields in each row
TTYPE1  = 'ENERG_LO'           / label for field   1
TFORM1  = 'E       '           / data format of the field: 4-byte REAL
TTYPE2  = 'ENERG_HI'           / label for field   2
TFORM2  = 'E       '           / data format of the field: 4-byte REAL
EXTNAME = 'ENERGIES'           / name of this binary table extension
HDUCLAS1= 'XSPEC TABLE MODEL'  / model spectra for XSPEC
HDUCLAS2= 'ENERGIES'           / extension containing energy bin info
HDUVERS = '1.0.0   '           / version of format
END
XTENSION= 'BINTABLE'           / binary table extension
BITPIX  =                    8 / 8-bit bytes
NAXIS   =                    2 / 2-dimensional binary table
NAXIS1  =                83204 / width of table in bytes
NAXIS2  =                   40 / number of rows in table
PCOUNT  =                    0 / size of special data area
GCOUNT  =                    1 / one data group (required keyword)
TFIELDS =                   14 / number of fields in each row
TTYPE1  = 'PARAMVAL'           / label for field   1
TFORM1  = '1E      '           / data format of the field: 4-byte REAL
TTYPE2  = 'INTPSPEC'           / label for field   2
TFORM2  = '1600E   '           / data format of the field: 4-byte REAL
TUNIT2  = 'photons/cm^2/s'     / physical unit of field
TTYPE3  = 'ADDSP001'           / label for field   3
TFORM3  = '1600E   '           / data format of the field: 4-byte REAL
TUNIT3  = 'photons/cm^2/s'     / physical unit of field
TTYPE4  = 'ADDSP002'           / label for field   4
TFORM4  = '1600E   '           / data format of the field: 4-byte REAL

TUNIT4  = 'photons/cm^2/s'     / physical unit of field
TTYPE5  = 'ADDSP003'           / label for field   5
TFORM5  = '1600E   '           / data format of the field: 4-byte REAL
TUNIT5  = 'photons/cm^2/s'     / physical unit of field
TTYPE6  = 'ADDSP004'           / label for field   6
TFORM6  = '1600E   '           / data format of the field: 4-byte REAL
TUNIT6  = 'photons/cm^2/s'     / physical unit of field
TTYPE7  = 'ADDSP005'           / label for field   7
TFORM7  = '1600E   '           / data format of the field: 4-byte REAL
TUNIT7  = 'photons/cm^2/s'     / physical unit of field
TTYPE8  = 'ADDSP006'           / label for field   8
TFORM8  = '1600E   '           / data format of the field: 4-byte REAL
TUNIT8  = 'photons/cm^2/s'     / physical unit of field
TTYPE9  = 'ADDSP007'           / label for field   9
TFORM9  = '1600E   '           / data format of the field: 4-byte REAL
TUNIT9  = 'photons/cm^2/s'     / physical unit of field
TTYPE10 = 'ADDSP008'           / label for field  10
TFORM10 = '1600E   '           / data format of the field: 4-byte REAL
TUNIT10 = 'photons/cm^2/s'     / physical unit of field
TTYPE11 = 'ADDSP009'           / label for field  11
TFORM11 = '1600E   '           / data format of the field: 4-byte REAL
TUNIT11 = 'photons/cm^2/s'     / physical unit of field
TTYPE12 = 'ADDSP010'           / label for field  12
TFORM12 = '1600E   '           / data format of the field: 4-byte REAL
TUNIT12 = 'photons/cm^2/s'     / physical unit of field
TTYPE13 = 'ADDSP011'           / label for field  13
TFORM13 = '1600E   '           / data format of the field: 4-byte REAL
TUNIT13 = 'photons/cm^2/s'     / physical unit of field
TTYPE14 = 'ADDSP012'           / label for field  14
TFORM14 = '1600E   '           / data format of the field: 4-byte REAL
TUNIT14 = 'photons/cm^2/s'     / physical unit of field
EXTNAME = 'SPECTRA '           / name of this binary table extension
HDUCLAS1= 'XSPEC TABLE MODEL'  / model spectra for XSPEC
HDUCLAS2= 'MODEL SPECTRA'      / extension containing model spectra
HDUVERS = '1.0.0   '           / version of format
END

5.2 A two-parameter table model

This file has two interpolation parameters and no additional parameters.

SIMPLE  =                    T / file does conform to FITS standard
BITPIX  =                    8 / number of bits per data pixel
NAXIS   =                    0 / number of data axes

EXTEND  =                    T / FITS dataset may contain extensions
COMMENT   FITS (Flexible Image Transport System) format defined in Astronomy and
COMMENT   Astrophysics Supplement Series v44/p363, v44/p371, v73/p359, v73/p365.
COMMENT   Contact the NASA Science Office of Standards and Technology for the
COMMENT   FITS Definition document #100 and other FITS information.
CONTENT = 'MODEL   '           / spectrum file contains time intervals and event
FILENAME= '/home/lhea1/netzer/xmodels/slope07_c05l.at' / File that FITS was prod
ORIGIN  = 'NASA/GSFC'          / origin of FITS file
MODLNAME= 'model   '           / Model name
MODLUNIT= 'photons/cm^2/s'     / Model units
REDSHIFT=                    T / If true then redshift will be included as a par
ADDMODEL=                    T / If true then this is an additive table model
HDUCLASS= 'OGIP    '           / format conforms to OGIP standard
HDUCLAS1= 'XSPEC TABLE MODEL'  / model spectra for XSPEC
HDUVERS = '1.0.0   '           / version of format
END
XTENSION= 'BINTABLE'           / binary table extension
BITPIX  =                    8 / 8-bit bytes
NAXIS   =                    2 / 2-dimensional binary table
NAXIS1  =                  124 / width of table in bytes
NAXIS2  =                    2 / number of rows in table
PCOUNT  =                    0 / size of special data area
GCOUNT  =                    1 / one data group (required keyword)
TFIELDS =                   10 / number of fields in each row
TTYPE1  = 'NAME    '           / label for field   1
TFORM1  = '12A     '           / data format of the field: ASCII Character
TTYPE2  = 'METHOD  '           / label for field   2
TFORM2  = 'J       '           / data format of the field: 4-byte INTEGER
TTYPE3  = 'INITIAL '           / label for field   3
TFORM3  = 'E       '           / data format of the field: 4-byte REAL
TTYPE4  = 'DELTA   '           / label for field   4
TFORM4  = 'E       '           / data format of the field: 4-byte REAL
TTYPE5  = 'MINIMUM '           / label for field   5
TFORM5  = 'E       '           / data format of the field: 4-byte REAL
TTYPE6  = 'BOTTOM  '           / label for field   6
TFORM6  = 'E       '           / data format of the field: 4-byte REAL
TTYPE7  = 'TOP     '           / label for field   7
TFORM7  = 'E       '           / data format of the field: 4-byte REAL
TTYPE8  = 'MAXIMUM '           / label for field   8
TFORM8  = 'E       '           / data format of the field: 4-byte REAL
TTYPE9  = 'NUMBVALS'           / label for field   9
TFORM9  = 'J       '           / data format of the field: 4-byte INTEGER
TTYPE10 = 'VALUE   '           / label for field  10
TFORM10 = '20E     '           / data format of the field: 4-byte REAL
EXTNAME = 'PARAMETERS'         / name of this binary table extension

HDUCLASS= 'OGIP    '           / format conforms to OGIP standard
HDUCLAS1= 'XSPEC TABLE MODEL'  / model spectra for XSPEC
HDUCLAS2= 'PARAMETERS'         / extension containing parameter info
HDUVERS = '1.0.0   '           / version of format
NINTPARM=                    2 / Number of interpolation parameters
NADDPARM=                    0 / Number of additional parameters
END
XTENSION= 'BINTABLE'           / binary table extension
BITPIX  =                    8 / 8-bit bytes
NAXIS   =                    2 / 2-dimensional binary table
NAXIS1  =                    8 / width of table in bytes
NAXIS2  =                  209 / number of rows in table
PCOUNT  =                    0 / size of special data area
GCOUNT  =                    1 / one data group (required keyword)
TFIELDS =                    2 / number of fields in each row
TTYPE1  = 'ENERG_LO'           / label for field   1
TFORM1  = 'E       '           / data format of the field: 4-byte REAL
TTYPE2  = 'ENERG_HI'           / label for field   2
TFORM2  = 'E       '           / data format of the field: 4-byte REAL
EXTNAME = 'ENERGIES'           / name of this binary table extension
HDUCLAS1= 'XSPEC TABLE MODEL'  / model spectra for XSPEC
HDUCLAS2= 'ENERGIES'           / extension containing energy bin info
HDUVERS = '1.0.0   '           / version of format
END
XTENSION= 'BINTABLE'           / binary table extension
BITPIX  =                    8 / 8-bit bytes
NAXIS   =                    2 / 2-dimensional binary table
NAXIS1  =                  844 / width of table in bytes
NAXIS2  =                  300 / number of rows in table
More?[yes]
PCOUNT  =                    0 / size of special data area
GCOUNT  =                    1 / one data group (required keyword)
TFIELDS =                    2 / number of fields in each row
TTYPE1  = 'PARAMVAL'           / label for field   1
TFORM1  = '2E      '           / data format of the field: 4-byte REAL
TTYPE2  = 'INTPSPEC'           / label for field   2
TFORM2  = '209E    '           / data format of the field: 4-byte REAL
TUNIT2  = 'photons/cm^2/s'     / physical unit of field
EXTNAME = 'SPECTRA '           / name of this binary table extension
HDUCLAS1= 'XSPEC TABLE MODEL'  / model spectra for XSPEC
HDUCLAS2= 'MODEL SPECTRA'      / extension containing model spectra
HDUVERS = '1.0.0   '           / version of format
END