text: 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.>> 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.>> cd1.values = ["one", "", "three"] >>> cd1.>> 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.>> cd2.>> 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 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
  The Crates module is automatically imported into Sherpa sessions, otherwise use one of the following:
  from pycrates import *
  or
  import pycrates')
  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, 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