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

URL: http://cxc.harvard.edu/ciao/ahelp/cratedataset.html
AHELP for CIAO 4.9

cratedataset

Context: crates

Synopsis

The CrateDataset object is used to read and write files with multiple blocks.

Syntax

CrateDataset(input=None, mode='rw')

If input is not None then it gives the name of the file to read in.
The mode argument accepts 'r' (read-only) and 'rw' (read-write).

Description

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)

set_key(cr1, 'CREATOR', sys.argv[0],
        desc='tool that created this output')
set_key(cr1, 'DATE', time.asctime(),
        desc='Date and time of file creation')

# Second block
cr2 = TABLECrate()
cr2.name = "TBL"
cd2 = CrateData()
cd2.name = "x"
cd2.values = np.arange(20,31)
cd2.unit = 'cm'
cd2.desc = 'Average beard length'
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                    cm           Int4           -                    Average beard length

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         = Tue Nov 12 15:28:54 2013 / Date and time of file creation

Reading in dataset with multiple blocks

Using the file created above, we can read it in by saying

chips> cds = CrateDataset('out.fits')
chips> print(cds)
   Crate Dataset:
     File Name:         out.fits
     Read-Write Mode:   rw
     Number of Crates:  2
       1)     Crate Type:        <IMAGECrate>
   Crate Name:        IMG

       2)     Crate Type:        <TABLECrate>
   Crate Name:        TBL
   Ncols:             1
   Nrows:             11


and access its methods such as:

chips> msg = "{} has {} crates".format(cds.get_filename(), cds.get_ncrates())
chips> print(msg)
out.fits has 2 crates
chips> tcr = cds.get_crate('TBL')
chips> print(tcr)
   Crate Type:        <TABLECrate>
   Crate Name:        TBL
   Ncols:             1
   Nrows:             11
chips> print(tcr.get_column("x").desc)
Average beard length

Loading Crates

The Crates module is automatically imported into ChIPS and 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')

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

crates
add_crate, crates, get_crate, read_pha, read_rmf, 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:   cxchelp@head.cfa.harvard.edu Smithsonian Institution, Copyright © 1998-2017. All rights reserved.