write_file

Synopsis

Write a crate to an output file.

write_file(crate, filename [,clobber = False])

Description

• crate - input crate
• filename - name of the file
• clobber - should an output file be over-written if it already exists (default is False)?

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 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. This is a change from CIAO 4.3, where the routine returned 1 on success.

Metadata handling

As discussed in ahelp read_file, the Crate object does not retain all the information from the input file, which means that care should be taken when using the output from write_file() with CIAO tools. In particular, great care should be taken when editing "instrumental" files, such as event files, exposure maps, and spectra.

Example 1

chips> cr = read_file("merged.fits")
chips> dnam = get_key(cr, "DETNAM")
chips> dnam.value = "ACIS-67"
chips> 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, subspace information and some ancillary header information.

Example 2

>>> cr = read_file("src.fits")
>>> x = get_colvals(cr, "x")
>>> x += np.random.random_sample(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 + 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 sub-space information (see "ahelp subspace") may be lost when using read_file followed by write_file.

More information on random-number support in NumPy can be found at http://docs.scipy.org/doc/numpy/reference/routines.random.html.

Example 3

chips> cr = read_file("tbl.dat")
chips> x = copy_colvals(cr, "x")
chips> y = copy_colvals(cr, "y")
chips> z = np.sqrt(x**2 + y**2)
chips> cd = CrateData()
chips> cd.name = "z"
chips> cd.values = z
chips> add_col(cr, cd)
chips> 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.4

Error handling

The write_file routine now raises an error rather than returning an integer.

The clobber argument

A clobber parameter has been added - which defaults to False - to control whether existing files will be overwritten or not.

Bugs

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

Refer to the CIAO bug pages for an up-to-date listing of known issues.

See Also

contrib

make_image_crate, make_table_crate, scale_image_crate, smooth_image_crate, write_arrays, write_columns

crates

add_col, add_key, add_piximg, delete_col, delete_key, delete_piximg, read_file, read_pha, read_rmf, write_pha, write_rmf