Description

A S-Lang function in the varmm module that reads in data from a file and stores it in a S-Lang variable. The type of the input file is automatically determined; readfile() supports all file types recognised by the CXC Data Model (DM). The varmm module also provides a number of functions for writing data out to the screen and files. The most relevant functions are writecols(), writeascii(), and writefits(). The ascii2fits program may also be of interest.

The filename parameter is a string that contains the name of the data file to be read in, and can contain DM syntax to filter, select columns, or otherwise manipulate the input file before it is read (see 'ahelp dmsyntax'). Note that you cannot use DM syntax when reading ASCII files as it is not supported for that filetype. The optional parameter "cols" is a list of column names or numbers to be read, and "nskip" is the number of rows to be skipped. If used to read in an image, then the optional arguments are ignored. As examples:

  chips> e1 = readfile("evt.fits");
  chips> e2 = readfile("evt.fits[cols time,sky]");
  chips> e3 = readfile("evt.fits","1,2",10);
  chips> e4 = readfile("evt.fits",[1,2],10);

where the last two examples read in only the first two columns and skip the first ten lines in the file. If the filename contains a list of columns using the Data Model syntax - for example

evt2.fits[cols time,sky]

- then this takes precedence over the "cols" and "nskip" parameters.

Reading in a specific file type

The readfile() routine works by determining the file type and then calling one of the following routines:

If you know the type of file that is to be read in, you can use the matching function instead of readfile(). The functions readpha(), readrmf(), readarf(), and readimage() return extra information that they read from the headers of the files, examples being the names of the ARF and RMF for a pha file, and the World Coordinate System information for an image.

Note that readfile() will not read in a RDB file currently; you have to use the readrdb() function for this.

What is returned by these functions?

The functions return a structure whose fields contain the data read in from the file. If an error occurred - such as the file not being found - then NULL is returned instead. In the returned structure, metadata - e.g. the number of rows read in, the file name, or a pointer to the header information - begins with a single underscore character. These fields are stored first in the structure. Following the metadata is the actual contents of the table or image. Here we focus on those fields common to all file types; the ahelp pages for the individual functions discuss the fields specific to each function.

The fields common to both tables and images are:

The _filetype field

In CIAO 3.0 the "_filetype" field was added to indicate the type of the file from which the data was read. An integer value is used to indicate the type:

The "Symbol" column gives the name of the S-Lang variable that can be used to check the file type; for example:

  variable in = readfile(infile);
  switch ( in._filetype )
  { case ASCII: vmessage( "file=%s is an ASCII file", infile ); }
  { case ARF:   vmessage( "file=%s contains an ARF", infile ); }
  ...

The _header field

The header information of a FITS file is stored as an array of strings in the _header field of the structure: for ASCII files it is set to NULL. Each FITS card (i.e. keyword, value, and comment), is stored as one item in a string array, for example:

  chips> arf = readbintab("centre.arf")
  chips> print(arf._header)
  String_Type[170]
  chips> printarr(arf._header[0])
  XTENSION= 'BINTABLE'           / binary table extension
  chips> printarr(arf._header[[8:9]])
  EXTNAME = 'SPECRESP'           / name of this binary table extension
  HDUNAME = 'SPECRESP'           / ASCDM block name

If you do not wish headers to be read, then you can set the readheader element of the varmm state object to 0 to turn off this behaviour:

  chips> varmm.readheader = 0

Setting it to 1 will restore the default value of reading in the headers:

  chips> varmm.readheader = 1

The remaining contents of the structure depend upon the file type. See the ahelp page for the apropriate function - e.g. "ahelp readimage" for images - for details on these fields.