Chandra X-Ray Observatory
	(CXC)
Skip to the navigation links
Last modified: December 2015

URL: http://cxc.harvard.edu/ciao/ahelp/write_file.html
Jump to: Description · Examples · Bugs · See Also


AHELP for CIAO 4.9

write_file

Context: crates

Synopsis

Write a crate to an output file.

Syntax

write_file(crate, filename, clobber=False)

Description

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.

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.

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

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 and COMMENT/HISTORY keywords. Use the CrateDataset object to read in and modify multi-block files.

Example 3

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

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

Example 4

chips> cr = read_file("tbl.dat")
chips> x = get_colvals(cr, "x")
chips> y = get_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

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

Last modified: December 2015
Smithsonian Institute Smithsonian Institute

The Chandra X-Ray Center (CXC) is operated for NASA by the Smithsonian Astrophysical Observatory. 60 Garden Street, Cambridge, MA 02138 USA.   Email:   cxchelp@head.cfa.harvard.edu Smithsonian Institution, Copyright © 1998-2017. All rights reserved.