read_file

Context: crates

Syntax

read_file(filename)

Description

filename - name of the input file; FITS or ASCII format

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.

The read_pha and read_rmf routines can be used when the type of the dataset is known.

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 (new in CIAO 4.4).
Crates does not retain the data subspace of the file.
Crates does not retain HISTORY or COMMENT blocks from the input file.

Example 1

>>> cr = read_file("evt2.fits")
>>> print(cr)

   Crate Type:        <TABLECrate>
   Crate Name:        EVENTS
   Crate Number:      2
   Ncols:             16
   Nrows:             248072

Example 2

>>> cr = read_file("evt2.fits[sky=circle(4096,4096,100)][bin sky=::1]")
>>> print(cr)

   Crate Type:        <IMAGECrate>
   Crate Name:        EVENTS_IMAGE
   Crate Number:      2

Example 3

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

>>> 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 ("ahelp get_col_names") can be used to find the columns in a Crate.

Example 5

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

>>> 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 into the TABLEcrate "a" (see "ahelp dmascii" for more information).

Changes in CIAO 4.4

The new CrateDataset class should be used if you need to access multiple blocks in a file. See "ahelp CrateDataset" for more information.

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.