          Add a column to a crate.

add_col(crate, cratedata)

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.

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

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

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.

See the bug pages on the CIAO website for an up-to-date listing of known bugs.

December 2023