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

AHELP for CIAO 4.9


Context: crates


Read FITS or ASCII data into a crate.


read_file(filename, mode='r')


Argument Description
filename Name of the file; it can include CIAO Data Model syntax such as filters and binning values
mode Should the mode be opened for read-only ('r', the default), or for read-write access ('rw').

The read_file command loads the specified file into the appropriate crate, either a TABLECrate or an IMAGECrate. The input file may be in FITS or ASCII format.

Multiple blocks, read_pha and read_rmf

Note that this routine only reads in data from one block of the file (and any related information, such as the GTI blocks of an event file). If you wish to access multiple blocks within a file then see ahelp cratedataset, or - if appropriate - use either of the read_pha or read_rmf routines.

Differences to the CIAO Data Model

Users familiar with the CIAO Data Model should note that:

  • Crates reads one extension of the input file, not the whole dataset. The file that is written out will only contain the block which was read. If you wish to access all the blocks in the file then you need to use the CrateDataset class.
  • Crates does not retain HISTORY or COMMENT blocks from the input file.

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("evt2.fits")
>>> print(cr)
   Crate Type:        <TABLECrate>
   Crate Name:        EVENTS
   Ncols:             16
   Nrows:             248072

Example 3

>>> cr = read_file("evt2.fits[sky=circle(4096,4096,100)][bin sky=::1]")
>>> print(cr)
   Crate Type:        <IMAGECrate>
   Crate Name:        EVENTS_IMAGE

Example 4

>>> f = "evt2.fits[energy=500:7000,sky=region(src.reg)][bin sky=::1]"
>>> cr = read_file(f)
>>> s = get_piximgvals(cr).sum()
>>> print("Pixel sum={0}".format(s))
Pixel sum=2361

File names can include CIAO Data Model filtering and binning commands (e.g. see "ahelp dm"). In this case energy and spatial filters are applied to an event file before being binned into an image. The pixel values are read in and then summed up.

Example 5

>>> a = read_file("myfile.dat")
>>> x = copy_colvals(a, "col1")
>>> y = copy_colvals(a, "col2")

The read_file command is used to read the contents of the ASCII file myfile.dat into the TABLEcrate a. The copy_colvals command is used to copy the data from the columns col1 and col2 into numpy arrays.

The get_col_names routine can be used to find the columns in a Crate.

Example 6

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


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

Example 7

>>> a = read_file("myfile.dat[opt colnames=none]")

In this case, the ASCII kernel option 'opt colnames=none' tells the read_file command to skip the header information when reading the contents of the ASCII file myfile.dat. See "ahelp dmascii" for more information on the ASCII file support in CIAO.

Example 8

>>> cr = read_file("srcs.tsv[opt kernel=text/tsv]")
>>> t1 = cr.get_column("tlo").values
>>> t2 = cr.get_column("thi").values
>>> cd = CrateData()
>>> = "tmid"
>>> cd.values = (t1 + t2) / 2.0
>>> cd.desc = "Average of t1 and t2"
>>> add_col(cr, cd)
>>> cr.write("modsrcs.fits")
>>> cr.write("modsrcs.tsv[opt kernel=text/tsv]")

Here the input file is a tab-seperated file (TSV format); the correct ASCII kernel needs to be specified in this case otherwise the data is not loaded correctly.

The t1 and t2 columns are accessed using the get_column method of the crate; as this returns a CrateData object, the values field is used to extract the column data, since we are not interested in the column metadata.

A new column "tmid" is created, containing the average of the t1 and t2 columns, and added to the crate using add_col(). Finally the new file is written out as in FITS and TSV formats using the write method.

The mode argument

When a file is read in, the write permission is checked against the mode argument and, if it does not match (if mode='rw' but the user does not have write permission, or the file is a gzipped file) then a warning is displayed and the mode is set to 'r'.

When is the mode argument used?

The mode argument is only relevant if you call the write method of the crate with no arguments; that is if you say

>>> cr = read_file('tbl.dat', mode='rw')
UserWarning: File 'tbl.dat' does not have write permission. Changing to
read-only mode.
>>> cr.write()
IOError: File is not writeable.

It is not used if you want to write to a new file or one that is not write protected. That is, you can read in a file in read-only mode, change its contents, and write it out to a new file:

>>> cr = read_file('img.fits', mode='r')
>>> ivals = cr.get_image().values
>>> ivals += 1
>>> cr.write('modified.fits')

Changes in CIAO 4.8

Tri-state logical columns

The FITS convention for boolean columns supports a "null" value, which means that it can represent three states: true, false, and unknown. Any such null, or unknown, value will be converted to False when the data is read in to a Crate (e.g. when read by read_file), and so the information that this cell value was a null will be lost.


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

make_image_crate, make_table_crate, scale_image_crate, smooth_image_crate, write_arrays, write_columns
add_col, add_key, add_piximg, delete_col, delete_key, delete_piximg, read_pha, read_rmf, write_file, 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: Smithsonian Institution, Copyright © 1998-2017. All rights reserved.