12. XAS file format reference

• XAS uses only two types of files (and of associated Fortran i/o) : plain ASCII files with sequential access for small quantities of ancillary information, and fixed-format binary files with direct access for real and bulky data.
  A (Unix-like) STREAM_LF format is preferred for ASCII files on non Unix systems (and imposed at z_open level).
  Some additiona support is provided for ASCII tables
  The remainder of this specification covers exclusively the binary XAS data files.

• XAS binary files use the native binary representation of the operating system (OS) on which they are written.
  There is no requirements of portability of the files (one cannot read a file written on a different, uncompatible OS), but there is an interoperability requirement. The OS is identified, and an in place conversion to the local OS format (localization) is supported by a dedicated program and routines. This conversion is unidirectionally supported : a file can be imported to the local OS, but not exported to a generic OS.

• A XAS file is composed in this order by these three parts :
  • a mini-header covering one or more record with 28 bytes of useful information (more than one record only when the record length is less than 28 bytes, the rest being null-padded).
    • a 16-byte magic number in the form XAS₁PPP₂TTT₃SSS₄, where the 1..4 values at subscript position indicate binary values 1..4 (CHAR(1) to CHAR(4)), while the ASCII sequences PPP and TTT corresponds to types and subtypes described below, and SSS is the three-letter code of the operating system which wrote the file (as returned by z_op_sys, one of those stored in the SYSCOMMON common block). The mixture of ASCII and binary code is used to make unlikely that the magic number pattern be generated by chance.
    • an INTEGER RECLEN, the file record length in bytes
    • an INTEGER DATASIZE, the number of data records
    • an INTEGER HDRSIZE, the number of header records containing the header keywords (this does not include the mini-header)

  • DATASIZE data records
  • HDRSIZE header records

• There are two basic layouts for data records (images and [binary] tables) which share a common layout for header records.

• image files (magic number XAS₁IMG₂FLO₃SSS₄) store an image(nx,ny) in ny records of record length nx*4 (in the default format of REAL*4 images). INTEGER*2 images and 3-d images are supported at specification level, but their usage is not incouraged nor supported by s/w.

• response matrices files (magic number of the main file XAS₁IMG₂MAT₃SSS₄) are stored as a couple of images, a main matrix M(ne,nchan) in units of cm²keV (product of RMF * ARF * width of energy grid bins) and an associated histogram H(ne,1) with the input energy grid

• all other data files are stored as XAS binary tables

• a spectrum (magic number of XAS₁BIN₂SPE₃SSS₄) has 4 REAL columns, namely
  1. LOWER BOUNDARY
  2. UPPER BOUNDARY
  3. DATA
  4. ERROR
  5. additional columns may follow for particular, unofficially supported cases (storing fitted models or photon spectra)

• a time profile (magic number of XAS₁BIN₂TIM₃SSS₄) has n records (as many as n time bins), with a record length such to contain a selection of some of the following columns (when they appear, they do in this order, but what matter is the logical name ; those which do not appear are constructed from header keywords)
  1. TIME : the bin start time in seconds since a reference Unix time TIMEREF stored in the header, usually the 0 UT of the day containing the first data point in the observation, stored as a DOUBLE PRECISION value. May be absent for fully equispaced time profiles.
  2. BINSIZE : a REAL number indicating the bin duration. May be absent for time profiles with all equal bins (refer to keyword BINSIZE
  3. DEADTIME : a REAL 0.0-1.0 number giving the coverage fraction of the bin (optional)
  4. DATA : one value or an array of REAL data values (may be absent for the rare case file of times or time intervals)
  5. ERROR : the associate errors (optional)
  6. additional data and error columns may follow to allow parallel storage of more light curves with same time binning (but this has no support in s/w).
  
  
• for unofficially supported folded light curves TIME may be replaced by PHASE

• a photon list (magic number of XAS₁BIN₂PHO₃SSS₄) has has n records (as many as n photons or events), with a record length such to contain a selection of data columns corresponding to the data fields selected for each event.

• any other unspecified tabular file has a magic number of XAS₁BIN₂GEN₃SSS₄)
• the file header is located at the end of the file in order to be extendable (one can add new keywords) without changing the data part of the file.
• the file header is a sequence of binary-encoded keywords, stored spanning records of the same natural size used for the data. Records are null-padded which allow implicitly to generate an end-of-file keyword (this is not necessary if real keywords fill completely the header space).
  keyword handling routines read the entire header in memory and operate on such memory copy.

• keywords have a n 8-character NAME, a datatype and a length which is encoded together with the keyword value(s) in a binary data structure like this

  data type	1 byte type	1 byte length	8 bytes	length bytes
  INTEGER*2	1	2*n	NAME	n=l/2 INTEGER*2 values
  INTEGER*4	2	4*n	NAME	n=l/4 INTEGER values
  REAL*4	3	4*n	NAME	n=l/4 REAL values
  DOUBLE PRECISION	4	8*n	NAME	n=l/8 DOUBLE PRECISION values
  CHARACTER	0	2<=n<=68	NAME	one CHAR*n string
  end of file	0	0	absent	absent

  More data types with particular semantics (angle, time, date) are foreseen by the specifications but not implemented. The usage of the INTEGER*2 type, although defined, is deprecated.
  The keyword data structure can in principle reach n=255 bytes, but for reasons of FITS compatibility is limited to 68 byte character keywords (and the same limit imposed to other data types).

• There is a small number of mandatory keywords which must be present in a file in order for it to be usable. These are usually flushed to disk by the file creation routine, so that a file is usable even if no further ("documentation") keywords are added.
  The number of mandatory routines is much less than in a FITS file since some information is not useful or generated implicitly.
• For an image only BITPIX,NAXIS1 and NAXIS2 are mandatory (NAXIS if image is not 2-d)
• For a table BITPIX=8 is included for documentation, while NAXIS1, NAXIS2 and TFIELDS are mandatory, together with the TFORMn of all present columns, and the TTYPEn names of all used columns. The distinction between present and used columns is due to the need of table padding of record length to a multiple of 4.

[Previous][Next] [Up][Down]