OGIP Memo OGIP/92-009

The File Format for XSPEC Table Models

Code 668,
NASA/GSFC,
Greenbelt, MD20771

Version: 1995 Aug 25

SUMMARY

The file format used for XSPEC table model files is described. This format supercedes the binary format previously used for table models and also the binary format used for storing the Raymond-Smith model spectra.

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

LOG OF SIGNIFICANT CHANGES

Release	Sections Changed	Brief Notes
Date

1995 Aug 25		First Public Release

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 multiplicative models that are exponentials (ie absorption).

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. These additional parameters are the abundances of the heavy elements. If we suppose the zero-abundance model at temperature T to be , the spectra for each element to be , for from 1 to M, and the abundance of element element to be $\alpha_i$ then the resultant model spectrum calculated is $S_0(T) + \sum \alpha_i S_i(T)$ .

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

The FITS file format

Summary

The FITS file format for the table model file comprises a primary header plus the following extensions :

A PARAMETERS extension containing the parameter definitions and tabulated values.
An ENERGIES extension containing the energy ranges on which the model spectra are calculated.
A SPECTRA extension containing all the model spectra.

Primary header

The primary header must include the following keywords :

MODLNAME - the name of the model (XSPEC allows a maximum of 12 characters).
MODLUNIT - the units for the model (XSPEC allows a maximum of 12 characters).
REDSHIFT - whether redshift is to be a parameter (logical).
ADDMODEL - whether this is an additive model (logical).

It should also include the standard OGIP keywords :

HDUCLASS= 'OGIP    '           / format conforms to OGIP standard
HDUDOC  = 'OGIP/92-009'        / document defining format
HDUCLAS1= 'XSPEC TABLE MODEL'  / model spectra for XSPEC
HDUVERS1= '1.0.0   '           / version of format

PARAMETERS extension

There must be a BINTABLE extension with EXTNAME='PARAMETERS' containing the parameter definitions and tabulated values. The header must include the keywords :

NINTPARM - the number of interpolated parameters (integer).
NADDPARM - the number of additional parameters (integer).

The binary table must comprise one row for each parameter, each row having ten columns with the following names :

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 (the parameter starts frozen if this number is negative)

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 need to be set for the additional parameters since additional parameters have only one parameter value and the method is assumed to be linear. The uses of the INITIAL, DELTA, MINIMUM, BOTTOM, TOP, and MAXIMUM values are given in the XSPEC manual under the section on the command newpar.

This extension should also include the standard OGIP keywords :

HDUCLASS= 'OGIP    '           / format conforms to OGIP standard
HDUCLAS1= 'XSPEC TABLE MODEL'  / model spectra for XSPEC
HDUCLAS2= 'PARAMETERS'         / extension containing parameter info
HDUVERS1= '1.0.0   '           / version of format

ENERGIES extension

There must be a BINTABLE extension with EXTNAME='ENERGIES' containing the energy bins. The table comprises two real columns called ENERG_LO and ENERG_HI, being the lower and upper energy of each spectral bin respectively. The energies must be given in keV. Note that the bins must be contiguous (ie energ_hi(i) = energ_lo(i+1)).

This extension should also include the standard OGIP keywords :

HDUCLAS1= 'XSPEC TABLE MODEL'  / model spectra for XSPEC
HDUCLAS2= 'ENERGIES'           / extension containing energy bin info
HDUVERS1= '1.0.0   '           / version of format

SPECTRA extension

There must be a BINTABLE extension with EXTNAME='SPECTRA' containing the grid of spectra. The binary table comprises NADDPARM+2 columns as follows :

PARAMVAL nE Parameter values (n is number of interpolation parameters

INTPSPEC mE Model spectrum (m is the number of energies)

ADDSP001 mE Additional parameter model spectrum

ADDSP002 mE Additional parameter model spectrum

... ... ...

PARAMVAL is a vector of the parameter values for these spectra. INTPSPEC is a vector containing the model spectrum in units of photons/cm/s, The ADDSPXXX columns are the additional spectra (also in photons/cm/s) for the additional parameters in use. Note that the spectra must be ordered so that the last interpolation parameter changes fastest (eg if there are two interpolation parameters with three values each then the six model spectra are ordered as 1,1; 1,2; 1,3; 2,1; 2,2; 2,3). Thus the number of rows of the table will be the product of the NUMBVALS from the PARAMETERS extension.

This extension should also include the standard OGIP keywords :

HDUCLAS1= 'XSPEC TABLE MODEL'  / model spectra for XSPEC
HDUCLAS2= 'MODEL SPECTRA'      / extension containing model spectra
HDUVERS1= '1.0.0   '           / version of format

The WFTBMD routine

A Fortran subroutine that opens and writes out the header and first two extensions of a FITS format table model file is available in the XANADU source distribution as the file wftbmd.f in the directory $XANADU/spectral/tables. This routine leaves the output file at the point immediately following the definition of the binary table in the SPECTRA extension. All the creator of the table file must then do is use repeated calls to FTPCLE to write out the model spectra and then close the file using FTCLOS. The calling sequence for WFTBMD 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 param
s.
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

Examples

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. The file can be found in the XANADU distribution as $XANADU/spectral/xspec/manager/raysmith.mod.

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
HDUVERS1= '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
HDUVERS1= '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
HDUVERS1= '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
HDUVERS1= '1.0.0   '           / version of format
END

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
HDUVERS1= '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
HDUVERS1= '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
HDUVERS1= '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
HDUVERS1= '1.0.0   '           / version of format
END

USEFUL LINKS TO OTHER HTML PAGES

The following useful links are available (in the HTML version of this document only):

About this document ...

This document was generated using the LaTeX2HTML translator Version 99.2beta8 (1.46)

The command line arguments were:
latex2html -t OGIP/92-009 -split 3 -image_type gif modelfiles_memo.tex

The translation was initiated by Michael Arida on 2001-06-28

SUMMARY
LOG OF SIGNIFICANT CHANGES
INTRODUCTION
An historical note
The FITS file format
The WFTBMD routine
Examples
- A Raymond-Smith plasma emission model file
- A two-parameter table model
USEFUL LINKS TO OTHER HTML PAGES
About this document ...

HEASARC home page

This file was last modified on Friday, 18-May-2007 10:27:11 EDT

This page maintained by: Michael Arida (SP Sys); arida@milkyway.gsfc.nasa.gov
HEASARC Guest Observer Facility

National Aeronautics and Space Administration

Goddard Space Flight Center

Sciences and Exploration

Search:

The File Format for XSPEC Table Models

SUMMARY

LOG OF SIGNIFICANT CHANGES

INTRODUCTION

An historical note

The FITS file format

Summary

Primary header

PARAMETERS extension

ENERGIES extension

SPECTRA extension

The WFTBMD routine

Examples

A Raymond-Smith plasma emission model file

A two-parameter table model

USEFUL LINKS TO OTHER HTML PAGES

About this document ...