cratedataset

Context: crates

Synopsis

CrateDataset object types in the CRATES library.

The CRATES Library uses CrateDataset objects to store a file (dataset) which contains multiple blocks (crates). This is needed if you need to create or use data from multiple blocks in a file or want to ensure that all these blocks are retained if modifying a block. If you only need to read in data from a single block then you do not need to use the CrateDataset object and read_file() should be sufficient.

The read_pha, read_rmf, write_pha and write_rmf routines use sub-classes of the CrateDataset object - namely PHACrateDataset and RMFCrateDataset - to store all the data they need.

Creating a dataset with multiple blocks

In the following example we create a CrateDataset object and then add two blocks two it: the first an image and the second a table with one column.

import sys
import time
import numpy as np
from pycrates import *

# First block
cr1 = IMAGECrate()
cr1.name = "IMG"
cd1 = CrateData()
cd1.values = np.arange(12).reshape(4,3)
cr1.add_image(cd1)

key1 = CrateKey()
key1.name = "CREATOR"
key1.value = sys.argv[0]
key1.desc = "tool that created this output"
cr1.add_key(key1)

key2 = CrateKey()
key2.name = "DATE"
key2.value = time.asctime()
key2.desc = "Date and time of file creation"
cr1.add_key(key2)

# Second block
cr2 = TABLECrate()
cr2.name = "TBL"
cd2 = CrateData()
cd2.name = "x"
cd2.values = np.arange(20,31)
cr2.add_column(cd2)

# The dataset containing both blocks
ds = CrateDataset()
ds.add_crate(cr1)
ds.add_crate(cr2)

ds.write("out.fits", clobber=True)

which creates a file which looks like the following (assuming it's stored in a file called mds.py):

unix% python mds.py
unix% dmlist out.fits blocks
 
--------------------------------------------------------------------------------
Dataset: out.fits
--------------------------------------------------------------------------------
 
     Block Name                          Type         Dimensions
--------------------------------------------------------------------------------
Block    1: IMG                            Image      Int4(3x4)
Block    2: TBL                            Table         1 cols x 11       rows

and the table block contains:

unix% dmlist "out.fits[TBL]" cols
 
--------------------------------------------------------------------------------
Columns for Table Block TBL
--------------------------------------------------------------------------------
 
ColNo  Name                 Unit        Type             Range
   1   x                                 Int4           -

and the header of the image block is

unix% dmlist out.fits header,clean,raw
SIMPLE       = T                    / file does conform to FITS standard
BITPIX       = 32                   / number of bits per data pixel
NAXIS        = 2                    / number of data axes 
NAXIS1       = 3                    / length of data axis 
NAXIS2       = 4                    / length of data axis 
EXTEND       = T                    / FITS dataset may contain extensions
COMMENT      =   FITS (Flexible Image Transport System) format is defined in 'Astronomy /                     
COMMENT      =   and Astrophysics', volume 376, page 359; bibcode: 2001A&A...376..359H /                     
HDUNAME      = IMG                  / ASCDM block name    
CREATOR      = mds.py               / tool that created this output
DATE         = Thu Nov 17 15:09:50 2011 / Date and time of file creation

Changes in CIAO 4.4

The CrateDataset object is new in CIAO 4.4.

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.