Last modified: November 2023

URL: https://cxc.cfa.harvard.edu/ciao/ahelp/make_table_crate.html
AHELP for CIAO 4.16

make_table_crate

Context: contrib

Synopsis

Create a TABLECrate from a set of arrays, a dictionary, or a structured array.

Syntax

make_table_crate(col1, ..., coln [, colnames=None])
make_table_crate(dictionary [, colnames=None])
make_table_crate(structarray [, colnames=None])

The return value is a TABLECrate.

Description

This routine provides a quick means of creating a TABLECrate from a set of arrays, a dictionary, or a NumPy structured array.

Loading the routine

The routine can be loaded into Python by saying:

from crates_contrib.utils import *

Column content: dictionary

If a single argument is given and it acts like a Python dictionary, then it is used to define both the column names and values (the dictionary keys and values respectively). The dictionary values are assumed to be arrays and follow the same rules as if given individually, as described in the "Column contents: separate arguments" section below.

If the colnames argument is given then it is used to determine the order of the columns in the output crate. This argument acts as a column filter on the input dictionary, since any dictionary keys not in colnames are not added to the crate.

If colnames is None then the argument of the columns is determined by the dictionary itself - i.e. the order returned by its keys() method. Use the collections.OrderedDict class if you need a specific order (or explicitly specify it using the colnames argument).

Column content: structured array

If the argument is a NumPy structured array then it is used to determine the column names and values and the order of the columns. The colnames argument can be used to re-order or subset the columns as with dictionaries.

Column content: separate arguments

The data to add to the Crate is given as the col1 to coln arguments; they can be Python arrays (e.g. [1,2,3]) or numpy arrays (e.g. np.arange(4)), can be multi-dimensional (e.g. for vector columns), and can include string vectors. Each column should contain a single datatype, and all will be padded to the length of the longest array. The padding is 0 for numeric columns and "" or "IND" for string arrays.

If the optional colnames argument is not given then the columns will be named "col1" to "coln", where n is the number of columns. To use your own names, supply an array of strings to the colnames argument. This array must match the number of columns.

Writing the data out to file

The write_file() command can be used to write the data out to file in FITS binary or ASCII formats. If you do not need to add metadata to the crate then the write_columns() routine can also be used.


Examples

Example 1

>>> a = [1, 2, 3, 4, 5]
>>> b = 2.3 * np.asarray(a)**2
>>> c = ["src a", "src b", "", "multiple sources", "x"]
>>> cr = make_table_crate(a, b, c)
>>> print(get_col_names(cr))
['col1' 'col2' 'col3']
>>> write_file(cr, "src.fits")
>>> write_file(cr, "src.dat[opt kernel=text]")

A table crate is created (cr) that contains the three arrays, stored as columns "col1", "col2", and "col3". The crate is written out to the file "src.fits", which is in binary FITS format, and "src.dat", which is in ASCII format using the TEXT/SIMPLE format (see the dmascii ahelp page for more information). The contents of src.dat are

>>> !cat src.dat
#TEXT/SIMPLE
# col1 col2 col3
1 2.300000000000 "src a"
2 9.200000000000 "src b"
3 20.70000000000 ""
4 36.80000000000 "multiple sources"
5 57.50000000000 x

and the column listing for "src.fits" is:

>>> !dmlist src.fits cols
 
-----------------------------------------------------------
Columns for Table Block TABLE
-----------------------------------------------------------
 
ColNo  Name       Unit        Type             Range
   1   col1                    Int4           -                    
   2   col2                    Real8          -Inf:+Inf            
   3   col3                    String[16]                          

Example 2

>>> cr = make_table_crate(a, b, c, colnames=['x', 'y', 'comment'])
>>> cr.name = 'SRCS'

This time the column names are set to "x", "y", and "comment" rather than "col1", "col2", and "col3". The block name is changed from 'TABLE' to 'SRCS'.

Example 3

>>> x = [1, 2, 3, 4]
>>> y = np.arange(10).reshape(5,2)
>>> cr = make_table_crate(x, y, colnames=["x", "y"])
>>> set_key(cr, 'NORMFLAG', True, desc="Is the data normalized?")
>>> write_file(cr, "example.fits")

Here we highlight

The output file looks like:

>>> !dmlist example.fits data,clean
#  x          y[2]
          1                  0 1
          2                  2 3
          3                  4 5
          4                  6 7
          0                  8 9

and the header keyword was set (the routine automatically sets the CREATOR and DATE keywords).

>>> !dmlist example.fits header,clean
CREATOR              make_table_crate               tool that created this output
DATE                 2013-11-14T09:58:51            Date and time of file creation
NORMFLAG             TRUE                           Is the data normalized?

Example 4

>>> icr = read_file("lc.fits")
>>> x = copy_colvals(icr, "time")
>>> y = copy_colvals(icr, "rate")
>>> ocr = make_table_crate({"dt": x - x[0], "rate": rate})
>>> write_file("lc2.fits")

Here we create a new table crate based on the time and rate columns of the file lc.fits. The new table has two columns, "dt" and "rate", and is written out to the file lc2.fits. Since we use a Python dictionary then the order of the columns in the crate is not guaranteed; the easiest way to force an ordering is to use the colnames option; e.g.

>>> d = {"dt": x - x[0], "rate": rate}
>>> ocr = make_table_crate(d, colnames=["dt", "rate"])

Example 5

>>> ds = CrateDataset()
>>> col1 = np.arange(1, 5)
>>> rng = np.random.default_rng()
>>> col2 = rng.integers(10, 20, size=col1.size)
>>> ivals = np.arange(12).reshape(3,4)
>>> cr1 = make_table_crate(col1, col2, colnames=['INDEX', 'RANDVAL'])
>>> cr2 = make_image_crate(ivals)
>>> add_crate(ds, cr1)
>>> add_crate(ds, cr2)
>>> write_file(ds, 'blocks.fits')

Here we use a CrateDataset object to store two blocks - a table and then an image - which is written out to blocks.fits:

>>> !dmlist blocks.fits blocks
 
--------------------------------------------------------------------------------
Dataset: blocks.fits
--------------------------------------------------------------------------------
 
     Block Name                          Type         Dimensions
--------------------------------------------------------------------------------
Block    1: PRIMARY                        Null        
Block    2: TABLE                          Table         2 cols x 4        rows
Block    3: IMAGE                          Image      Int4(4x3)

Since a FITS table can not start with a TABLE block, an empty PRIMARY block has been automatically created by the write_file command.

The NumPy integers method is used to create random integers betwen 10 and 19 (inclusive).


Adding or changing metadata

The crate has a name of 'TABLE' and contains two keywords, CREATOR and DATE. These can be changed, or other values added, using Crates routines.

>>> cr.name = 'HISTVALS'

will change the block name.

Keywords

The set_key() routine is an easy way to add or edit a keyword, while get_key() and add_key() provide a more powerful way of handling keywords. The delete_key() routine removes keywords.


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
add_colvals, make_image_crate, scale_image_crate, smooth_image_crate, write_arrays, write_columns
crates
add_col, add_key, add_piximg, delete_col, delete_key, delete_piximg, read_file, read_pha, read_rmf, write_file, write_pha, write_rmf