          Write a crate to an output file.

write_file(crate, filename, clobber=False, history=True)

Argument
Description
crate
A Crate object such as a TABLECrate or IMAGECrate
filename
The output file name. To change the format from FITS add a kernel specifier as described in 'ahelp dmopt' and 'ahelp dmascii'.
clobber
Set to True if the output file already exists and you wish to over-write it, since the default behavior is to raise an IOError in this case.
history
Should the HISTORY and COMMENT records be written out? The default is True.

The write_file command creates an output file for the input crate, overwriting any existing file with the same name. This command may be used with any type of crate. The output file is written in FITS format unless the output filename contains a kernel specifier. The write_pha and write_rmf routines can be used when the type of the dataset is known.

An IOError will be raised if there was a problem writing out the file.

Prior to CIAO 4.11, COMMENT and HISTORY records were not supported by Crates, so would have been lost on file input. These are now retained and can also be manipulated - added or deleted - using new routines and the history module.

>>> cr = read_file("tbl.dat")
>>> write_file(cr, "tbl.out")

Read in a file tbl.dat and then write it out to tbl.out, in FITS format.

>>> cr = read_file("merged.fits")
>>> dnam = get_key(cr, "DETNAM")
>>> dnam.value = "ACIS-67"
>>> write_file(cr, "edit.fits", clobber=True)

Here we read in a file and edit the contents of the DETNAM keyword. The clobber keyword is set to ensure that any existing file will be over-written. Note that the output file does not contain all the information that the input file did, in particular additional blocks and COMMENT/HISTORY keywords. Use the CrateDataset object to read in and modify multi-block files.

>>> cr = read_file("src.fits")
>>> x = get_colvals(cr, "x")
>>> rng = np.random.default_rng()
>>> x += rng.random(x.shape) - 0.5
>>> write_file(cr, "xrand.fits")

Here we read in the x column of src.fits, add a random value between -0.5 and 0.5 to each element, then write the results out to xrand.fits.

The above only worked because we used get_colvals to access the data - so that we we working with the data stored in the crate and not a crate - and because the '+=' operator was used to update x; if we had said

>>> x = x + rng.random(x.shape) - 0.5

then xrand.fits would be the same as src.fits. More information on random-number support in NumPy can be found at https://numpy.org/doc/stable/reference/random/index.html.

Using read_file will only read in a single block of information from the file (as well as ancillary information such as GTI blocks). This means that using read_file followed by write_file will lose information about other blocks in the file. To handle multi-block files, use the CrateDataset class.

Prior to CIAO 4.11, HISTORY and COMMENT records were not guaranteed to be read in by read_file or written out by write_file.

>>> cr = read_file("tbl.dat")
>>> x = get_colvals(cr, "x")
>>> y = get_colvals(cr, "y")
>>> z = np.sqrt(x**2 + y**2)
>>> cd = CrateData()
>>> cd.name = "z"
>>> cd.values = z
>>> add_col(cr, cd)
>>> write_file(cr, "tbl2.dat[opt kernel=text/simple]")

In this example we read in the file tbl.dat, extract the x and y columns and create a new column, called z, from these values. This new column is added to the crate and then the crate is written out to the file tbl2.dat. The addition of the Data Model option "[opt kernel=text/simple]" ensures that the output is a text file (see "ahelp dmopt" and "ahelp dmascii" for more information on options and the ASCII file support in CIAO).

If the input file looked like:

unix% cat tbl.dat # x y 1 2 3 5 9 10

then the output file will look like:

unix% cat tbl2.dat #TEXT/SIMPLE # x y z 1.0 2.0 2.236067977500 3.0 5.0 5.830951894845 9.0 10.0 13.45362404707

Changes in CIAO 4.11

Crates now supports HISTORY and COMMENT records in the file header, so they will now be stored in the Crate when read in, can be added or deleted, and written out to the output file. The history module (which is also new in CIAO 4.11) can be used to create HISTORY records in the format recognized by CIAO tools (such as dmhistory).

See the bug pages on the CIAO website for an up-to-date listing of known bugs.

December 2013