Synopsis
Copy the column values from a crate.
Syntax
copy_colvals(crate, colname) copy_colvals(crate, colnum)
Description
Argument | Description |
---|---|
crate | The table crate. |
colname | The column name (case insensitive). |
colnum | The column number, where the first column is numbered 0. |
The copy_colvals command retrieves a numpy array of the values of the specified column within a table crate. The data values are copied into an array and that array is returned.
The get_col_names routine can be used to find the columns in a Crate.
The get_col command returns a CrateData object for the column, which is useful if you are interested in the metadata associated with it.
Examples
Example 1
>>> cr = read_file("evt2.fits") >>> t = copy_colvals(cr, "time") >>> print(t[0:3]) [ 52379718.80918065 52379718.80918065 52379718.80918065]
Copy the values of the "time" column from the crate "cr", then print out the first three elements of the array.
Example 2
>>> 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'] >>> vals = copy_colvals(cr, 7) >>> print(vals.shape) (603495, 2) >>> print(vals[0:3]) [[ 3892.52172852 4165.99365234] [ 3908.08300781 4142.32275391] [ 3849.05786133 3993.52783203]]
The values from column number 7 - the sky(x,y) column in this file - are copied to the variable "vals".
Example 3
>>> cr = read_file("evt2.fits") >>> sky = copy_colvals(cr, "sky") >>> y = copy_colvals(cr, "Y") >>> print(sky.shape) (124940, 2) >>> print(y.shape) (124940,) >>> print(get_number_rows(cr)) 124940
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.
Should I use copy_colvals or get_colvals?
The general rule of thumb is to use copy_colvals rather than get_colvals, particularly for interactive use from the Sherpa or IPython shells.
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.
>>> cr = read_file("tbl.dat") >>> x = copy_colvals(cr, "x") >>> y = get_colvals(cr, "y") >>> print(x) [1. 3. 9.] >>> print(y) [ 2. 5. 10.] >>> x[1] = 5 >>> y[1] = 9 >>> print(x) [1. 5. 9.] >>> print(get_colvals(cr, "x")) [1. 3. 9.] >>> print(y) [ 2. 9. 10.] >>> print(get_colvals(cr, "y")) [ 2. 9. 10.] >>> 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 propagated 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.
Refer to the CIAO bug pages for an up-to-date listing of known issues.
See Also
- contrib
- add_colvals
- crates
- add_col, col_exists, delete_col, get_col, get_col_names, get_colvals, get_number_cols, is_virtual, set_colvals