Synopsis
The TABLECrate and IMAGECrate objects represent a block in a file.
Syntax
IMAGECrate(input=None, mode='rw') TABLECrate(input=None, mode='rw') If input is not None then it gives the name of the file to read in.
Description
The TABLECrate and IMAGECrate objects are used to store tables (a collection of column) or an n-dimensional vector ('image') respectively. They can be created by calling the constructors directly or, more commonly, are returned by read_file routine. Format support matches that of the CIAO Data Model, so FITS files and the ASCII flavors described in ahelp dmascii.
If you are interested in multiple blocks (also called HDUs) in a file then use the CrateDataset object, which allows you to access the various crates in a file.
Reading in a table
The read_file routine will read in an image or a table, but if you want to ensure that the 'most-interesting block' of the file is a table then you can use TABLECrate directly, since it raises a TypeError if given an image:
>>> tcr = TABLECrate('srcs.dat')Reading in an image
Conversely, IMAGECrate requires an image:
>>> icr = IMAGECrate('evt2.fits[energy=500:900][bin sky=::8]')Creating a table
When called with no input argument, the TABLECrate constructor returns an empty crate which can be filled with columns:
>>> ecr = TABLECrate() >>> ecr.name = 'LABELS' >>> set_key(ecr, 'CREATOR', 'AwesomeSauce', desc='The creator')
At this point we have a table with a single header keyword; printing out the object shows a summary of the current state of the crate:
>>> print(ecr) Crate Type: <TABLECrate> Crate Name: LABELS Ncols: 0 Nrows: 0
>>> cd1 = CrateData() >>> cd1.name = 'label' >>> cd1.values = ["one", "", "three"] >>> cd1.desc = 'The identified source label' >>> add_col(ecr, cd1)
At this point the crate summary looks like
>>> print(ecr) Crate Type: <TABLECrate> Crate Name: LABELS Ncols: 1 Nrows: 3
and there is one column, called 'label':
>>> print(ecr.get_colnames()) ['label']
A subspace entry has also been created for the column, accessible via the get_subspace_data method (here the component number is 1 since there is only one set of valid subspace filters):
>>> print(ecr.get_subspace_data(1, 'label')) Name: label Unit: Range Minimum: [] Range Maximum: [] Region String: DEFAULT
>>> cd2 = CrateData() >>> cd2.name = 'time' >>> cd2.unit = 's' >>> ts = np.asarray([1234, 212, 4824, 9845]) >>> print(ts.dtype) int64 >>> cd2.values = ts >>> add_col(ecr, cd2)
After this, the crate is expanded to fit the new data, even though the individual columns still have their original sizes:
>>> print(ecr) Crate Type: <TABLECrate> Crate Name: LABELS Ncols: 2 Nrows: 4 >>> print(ecr.get_colnames()) ['label', 'time'] >>> print(get_colvals(ecr, 'label')) ['one' '' 'three'] >>> print(get_colvals(ecr, 'time')) [1234 212 4824 9845]
The extra rows are filled in with an appropriate missing value for the datatype, in this case a space, when the file is written out (in this case the write method of the object was used but the write_file routine could also have been used).
>>> ecr.write('table.fits', clobber=True)
>>> !dmlist table.fits blocks
--------------------------------------------------------------------------------
Dataset: table.fits
--------------------------------------------------------------------------------
Block Name Type Dimensions
--------------------------------------------------------------------------------
Block 1: PRIMARY Null
Block 2: LABELS Table 2 cols x 4 rows
>>> !dmlist table.fits cols
--------------------------------------------------------------------------------
Columns for Table Block LABELS
--------------------------------------------------------------------------------
ColNo Name Unit Type Range
1 label String[5] The identified source label
2 time s Int4 -
>>> !dmlist table.fits data,clean
# label time
one 1234
212
three 4824
9845
Creating an image
As with TABLECrate, calling the IMAGECrate constructor with no arguments returns an empty crate which can be filled by an image.
>>> j, i = np.mgrid[-10:10:0.5, 20:50:0.5] >>> r2 = (i-34)**2 + (j-2)**2 >>> cdi = CrateData() >>> cdi.values = np.sqrt(r2) >>> img = IMAGECrate() >>> img.add_image(cdi) >>> img.name = 'IVALS'
A synopsis of the crate can be displayed with print:
>>> print(img) Crate Type: <IMAGECrate> Crate Name: IVALS
The NumPy mgrid routine is used to create two 2D arrays (i and j) which contain the X and Y coordinates respectively for a grid ranging over x=20 to 50 and y=-10 to 10 with a grid size of 0.5 in both dimensions. Note that the upper bounds (ie x=20 and y=10) are not included in these grids.
The i and j arrays are then used to create an image r2, where each pixel is the square of the distance of that pixel from x=34, y=2. The array stored in the crate is the square root of this value (which has to be written to a CrateData object before calling add_image).
Although the image is calculated with an X axis of 20 to 49.5 and Y axis of -10 to 9.5, the logical coordinates cover 0 to 60 in X and 0 to 40 in Y.
The image can then be written out in a similar manner to the table example:
>>> img.write('img.fits')
>>> !dmlist img.fits blocks
--------------------------------------------------------------------------------
Dataset: img.fits
--------------------------------------------------------------------------------
Block Name Type Dimensions
--------------------------------------------------------------------------------
Block 1: IVALS Image Real8(60x40)
>>> !dmstat img.fits centroid=no
IVALS
min: 0 @: ( 29 25 )
max: 19.602295784 @: ( 60 1 )
mean: 9.898211423
sigma: 3.9927530968
sum: 23755.707415
good: 2400
null: 0
Loading Crates
The Crates module is automatically imported into Sherpa sessions, otherwise use one of the following:
from pycrates import *
or
import pycrates
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
Adding columns
The add_column method of a table crate now works correctly when the column number is set to 0 (previously the new column was added to the end of the table, now it is the first column). The add_column method and add_col call now create an empty subspace entry for vector columns, accessible with the get_subspace_data method of the crate.
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, cratedata, crates, create_vector_column, create_virtual_column, delete_col, delete_key, delete_piximg, get_col, get_colvals, get_piximg, read_file, read_pha, read_rmf, write_file, write_pha, write_rmf