Synopsis
Write a crate to an output file.
Syntax
write_file(crate, filename, clobber=False, history=True)
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. |
| 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.
Error handling
An IOError will be raised if there was a problem writing out the file.
Metadata handling
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.
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
>>> 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.
Example 3
>>> 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.
Notes
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.
Example 4
>>> 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
History and Comment records
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).
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.