Synopsis

Get the column values from a crate.

get_colvals(crate, colid);

Description

• crate - input crate
• colid - column name or number, where the first column is numbered 0

The get_colvals command retrieves an array of the values of the specified column within the crate. Allowed crate types are 'Table', 'ARF', 'PHA', and 'RMF'. The print_col_names command ("ahelp print_col_names") lists all the columns in the file with the corresponding numbers.

The get_col command ("ahelp get_col") returns a CrateData object for the column, which is useful if you are interested in the metadata associated with it.

Example 1

slsh> cr = read_file("evt2.fits");
slsh> vals = get_colvals(cr, "time");
slsh> print((vals[[0:2]]));
5.23797e+07
5.23797e+07
5.23797e+07

Retrieve the values of the "time" column from the crate "cr", then print out the first three elements of the array.

Example 2

slsh> cr = read_file("evt2.fits");
print (get_col_names (cr));
['time' 'ccd_id' 'node_id' 'expno' 'chip(chipx,chipy)'
'tdet(tdetx,tdety)'
'det(detx,dety)' 'sky(x,y)' 'pha' 'pha_ro' 'energy' 'pi' 'fltgrade'
'grade' 'status']
slsh> vals = get_colvals(cr, 7);
slsh> vals;
Float_Type[603495,2]
slsh> print(vals[[0:2],0]);
3892.52
3908.08
3849.06

The values from column number 7 - the sky(x,y) column in this file - are stored in the variable "vals".

Should I use copy_colvals or get_colvals?

The copy_colvals routine was added to Crates in CIAO 4.1. It appears similar to get_colvals, so why was it added? The return value from get_colvals reflects the contents of the Crate, so that changes to the return value also change the crate, whereas copy_colvals returns a copy of this data. This can be seen in the example below, which uses as an input file:

unix% cat tbl.dat
# x y
1  2
3  5
9  10

The steps taken below read in the file into a crate, extract the x and y column values, change the middle value of each column, check to see what values are stored in the crate, and then write out the crate to a new file. The x column is accessed using copy_colvals whereas the y column data is retrieved using get_colvals to show the difference in behavior.

slsh> cr = read_file("tbl.dat");
slsh> x = copy_colvals(cr, "x");
slsh> y = get_colvals(cr, "y");
slsh> print (x);
1
3
9
slsh> print (y);
2
5
10
slsh> x[1] = 5;
slsh> y[1] = 9;
slsh> print (x);
1
5
9
slsh> print (get_colvals(cr, "x"));
1
3
9
slsh> print (y);
2
9
10
slsh> print (get_colvals(cr, "y"));
2
9
10
slsh> write_file(cr,"tbl2.dat[opt kernel=text/simple]");

The output file contains:

unix% cat tbl2.dat
#TEXT/SIMPLE
# x y
1.0 2.0
3.0 9.0
9.0 10.0

So changing the values in the x array - which was created using copy_colvals - does not change the values stored in the crate, whereas changes to the values in the y array - which was created with get_colvals - are propogated to the crate, and hence into the output file tbl2.dat.

Note that the input file - here tbl.dat - is not changed by these operations.

It is generally going to be safer to use copy_colvals rather than get_colvals unless:

• you do want to be able to change values in the crate for either future processing or to write out to disk
• you have read in a large file and do not want to waste memory by creating another copy of the array

If the column being read in is a virtual one then the data is always going to be copied, so in this particular case there is no difference between copy_colvals and get_colvals.

Bugs

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

See Also

sl.crates

add_col, col_exists, copy_colvals, cratedata, delete_col, get_axis_transform, get_col, get_col_names, get_crate_item_type, get_crate_type, get_key, get_key_names, get_keyval, get_number_cols, get_number_rows, get_piximg, get_piximg_shape, get_piximgvals, get_transform, get_transform_matrix, is_virtual, print_col_names, set_colvals