Jump to: Description · Examples · Integer arrays · Changes in the January 2012 Release · Changes in the December 2011 Release · Bugs · See Also

AHELP for CIAO 4.5

make_table_crate

Context: contrib

Synopsis

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

Syntax

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

Description

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

Loading the routine

The routine can be loaded into a ChIPS or Sherpa session by saying:

from crates_contrib.utils import *

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.

Example 1

chips> a = [1, 2, 3, 4, 5]
chips> b = 2.3 * np.asarray(a)**2
chips> c = ["src a", "src b", "", "multiple sources", "x"]
chips> cr = make_table_crate(a, b, c)
chips> print(get_col_names(cr))
['col1' 'col2' 'col3']
chips> write_file(cr, "src.fits")
chips> 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 "ahelp dmascii" for more information). The contents of src.dat are

chips> !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:

chips> !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

chips> cr = make_table_crate(a, b, c, colnames=["x", "y", "comment"])

This time the column names are set to "x", "y", and "comment" rather than "col1", "col2", and "col3".

Example 3

chips> x = [1, 2, 3, 4]
chips> y = np.arange(10).reshape(5,2)
chips> cr = make_table_crate(x, y, colnames=["x", "y"])
chips> key = CrateKey()
chips> key.name = "NORMFLAG"
chips> key.value = True
chips> key.desc = "Is the data normalised?"
chips> add_key(cr, key)
chips> write_file(cr, "example.fits")

Here we highlight

handling multi-dimensional arrays (y),
dealing with arrays of different length (x has 4 scalars and y has 5 pairs),
and adding additional metadata to the Crate.

The output file looks like:

chips> !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).

chips> !dmlist example.fits header,clean
CREATOR              make_table_crate               tool that created this output
DATE                 2011-11-18T14:21:23            Date and time of file creation
NORMFLAG             TRUE                           Is the data normalised?

Example 4

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

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". 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.

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

Integer arrays

On 64-bit build machines, any NumPy array with a dataype of np.int32 will be converted to np.int64 before being added to the crate. This is to work around a bug in CIAO 4.4 release 1, where np.int32 columns are written out incorrectly by the write method of the crate or the write_file() routine.

chips> cr = make_table_crate(x, y, z)
chips> delete_key(cr, "DATE")
chips> delete_key(cr, "CREATOR")

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.