Skip to the navigation links
Last modified: December 2009

URL: http://cxc-newtest.cfa.harvard.edu/ciao4.2/copy_colvals.sl.html
AHELP for CIAO 4.2

copy_colvals

Context: sl.crates

Synopsis

Copy the column values from a crate.

Syntax

copy_colvals(crate, colid);

Description

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

The copy_colvals command retrieves an array of the values of the specified column within the crate. The data values are copied into an array and that array is returned. 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.

Example 1

slsh> cr = read_file("evt2.fits");
slsh> skyvals = copy_colvals(cr, "SKY");
slsh> yvals = copy_colvals(cr, "Y");

Use copy_colvals to get the values of vector column SKY(X,Y) from the crate "cr". Then get the "Y" component values as a separate array.

Example 2

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

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

Example 3

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 = copy_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 copied to 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, delete_col, get_col, get_col_names, get_colvals, get_number_cols, is_virtual, print_col_names, set_colvals

Last modified: December 2009