Jump to: Description · Loading Crates · The mode argument · Changes in CIAO 4.8 · Bugs · See Also

AHELP for CIAO 4.15

crate

Context: crates

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 *

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.