Last modified: December 2023

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

add_col

Context: crates

Synopsis

Add a column to a crate.

Syntax

add_col(crate, cratedata)

Description

Argument Description
crate The table crate.
cratedata The CrateData object containing the column data to add.

The add_col command adds the column to the crate. If the column already exists in the crate, it is replaced.

Only the crate is changed; the input file is unaffected. The write_file command can be used to save the modified crate to a file.


Examples

Example 1

>>> cr = read_file("mdl.fits")
>>> print(get_col_names(cr))
['E_MIN' 'E_MAX' 'MDLFLUX']
>>> emin = copy_colvals(cr, "E_MIN")
>>> emax = copy_colvals(cr, "E_MAX")
>>> emid = 0.5 * (emin + emax)
>>> col = CrateData()
>>> col.name = "E_MID"
>>> col.values = emid
>>> add_col(cr, col)
>>> print(get_col_names(cr))
['E_MIN' 'E_MAX' 'MDLFLUX' 'E_MID']
>>> write_file(cr, "mdl2.fits")

Here we create a column called E_MID, whose values are the mid-points of the E_MIN and E_MAX columns, and then add it to the crate. The write_file call creates a new file which includes this column.

Example 2

>>> cr = TABLECrate()
>>> cr.name = 'MUL'
>>> col1 = CrateData()
>>> col1.name = 'XY'
>>> col1.unit = 'pixel'
>>> col1.desc = 'Spatial values'
>>> rng = np.random.default_rng()
>>> x = rng.normal(5200.0, 200, 1000)
>>> y = rng.normal(-250.0, 300, 1000)
>>> col1.values = np.column_stack((x, y))
>>> add_col(cr, col1)
>>> col2 = CrateData()
>>> col2.values = (x > 0) & (y > 0)
>>> col2.name = 'POSFLAG'
>>> col2.desc = 'Positive values'
>>> add_col(cr, col2)
>>> cr.write('xy.dat[opt kernel=text/simple]')
>>> cr.write('xy.fits')

This creates a file with one array column, of 2 elements, and a boolean column, containing 1000 rows. The column_stack routine is used to combine the two 1D arrays created by the calls to the Numpy normal routine.

When written out as an ASCII file - using the simple flavor - then some metadata is lost (in this case the description and units of the columns as well as the block name):

unix% head -5 xy.dat
#TEXT/SIMPLE
# XY[2] POSFLAG
5179.111688065 -394.6172292417 F
4887.466042382 -239.7613093959 F
5171.852396207 -457.5535128818 F

This information is retained in the FITS version of the file:

unix% dmlist xy.fits blocks
 
--------------------------------------------------------------------------------
Dataset: xy.fits
--------------------------------------------------------------------------------
 
     Block Name                          Type         Dimensions
--------------------------------------------------------------------------------
Block    1: PRIMARY                        Null        
Block    2: MUL                            Table         2 cols x 1000     rows
unix% dmlist xy.fits cols
 
--------------------------------------------------------------------------------
Columns for Table Block MUL
--------------------------------------------------------------------------------
 
ColNo  Name                 Unit        Type             Range
   1   XY[2]                pixel        Real8(2)       -Inf:+Inf            Spatial values
   2   POSFLAG                           Logical                             Positive values

Note that the create_vector_column can be used to create a vector column, where the X and Y values can be accessed separately, rather than the array column approach used here.


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 of the crate.


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, make_table_crate, scale_image_crate, smooth_image_crate, write_arrays, write_columns
crates
add_key, add_piximg, col_exists, copy_colvals, cratedata, create_vector_column, create_virtual_column, delete_col, delete_key, delete_piximg, get_col, get_col_names, get_colvals, get_number_cols, get_piximg, is_virtual, read_file, read_pha, read_rmf, set_colvals, write_file, write_pha, write_rmf