write_file

Synopsis

Syntax

Description

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.

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.

Error handling

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

Metadata handling

As discussed in
ahelp read_file,
the Crate object does not retain all the information from the input file.
Noticeably, COMMENT and HISTORY items are not retained, which should not
impact on the use of the files with other tools but will lose
provenance and tracking information.

Examples

Example 1

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

Example 2

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.

Example 3

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 + np.random.random_sample(x.shape) - 0.5

then xrand.fits would be the same as src.fits.

Notes

Crates does not retain all the information
from the input file. In particular, other blocks and HISTORY/COMMENT
information
may be lost when using
read_file followed by write_file. The CrateDataset class should be
used to read in multi-block files.

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