|AHELP for CIAO 4.5||
CrateData object types in the CRATES library.
The CRATES Library uses CrateData objects to store data values of a columm or image. There are three CrateData object types: Regular, Vector, and Virtual.
Regular CrateData objects contain values from an image array or a single table column, which can be composed of either scalar values or arrayed values.
Vector columns are two or more columns that have been grouped together under the same name, but each component column has its own name as well. For example, the vector column SKY has two components, X position and Y position. The notation for vectors in the CRATES library is
vector(cpt1, cpt2, ...)
so the sky vector is represented as
Vector CrateData objects have values which consist of two or more CrateData objects. Using the previous example, the SKY vector values point to regular columns X position and Y position.
A Virtual CrateData object has values that have been calculated via a transform from another CrateData object. For example, the virtual column RA is defined by a transform associated with the regular column X.
Vector columns can also be virtual. EQPOS is a virtual vector column comprised of two virtual column components RA and DEC. EQPOS(RA,DEC) values are determined by applying a transform to SKY(X,Y) values.
Unlike the other parts of the Crates interface, access to information in a CrateData object is restricted to the methods and fields of the Python object (i.e. there are no separate functions). The important fields are listed below.
|values||The data values, stored as a NumPy array.|
|name||The name of the object.|
|unit||The units of the value, if set.|
|desc||A description of the object, if set.|
Here we read in the X column from the file evt2.fits and inspect the CrateData object that is returned.
chips> cr = read_file("evt2.fits") chips> x = cr.get_column("x") chips> x Name: x Shape: (368303,) Unit: pixel Desc: Sky coords Eltype: Scalar chips> x.values.mean() 4263.6122540408305 chips> y = cr.get_column("y") chips> add_curve(x.values, y.values)
With the above set up, we can modify values; for instance
chips> xv = x.values chips> xv += 0.5 chips> x.values.mean() 4264.1040230462422
Note that changing the values in the xv array change the underlying CrateData object. To ensure you are working with a copy of the data (so that changes do not get propogated back to the original Crate), use the NumPy copy() method - e.g.
chips> xv = x.values.copy()
or the copy_colvals() routine from Crates. See the discussion of Copies and Views of the NumPy Tutorial for more information on how NumPy arrays can be copied and shared.
The following lines create a CrateData object storing the values from the z NumPy array and called "zcol" (the unit and description fields are not required).
chips> cd = CrateData() chips> cd.name = "zcol" chips> cd.values = z
This can then be added to a table crate using the add_col() routine from Crates.
In the following we access the SKY vector column of a Chandra events file.
chips> sky = cr.get_column("sky") chips> sky Name: sky Shape: (368303, 2) Datatype: float32 Nsets: 368303 Unit: pixel Desc: Sky coords Eltype: Vector NumCpts: 2 Cpts: ['x', 'y'] chips> sky.values.shape (368303, 2) chips> x = sky.values[:,0] chips> x.shape (368303,) chips> y = sky.values[:,1] chips> row0 = sky.values[0,:] chips> print(row0) [ 3820.85449219 3828.33813477]
There is no significant difference to handling virtual columns:
chips> msc = cr.get_column("MSC") chips> msc.is_virtual() True chips> msc Name: MSC Shape: (368303, 2) Unit: deg Desc: Eltype: Virtual Vector NumCpts: 2 Cpts: ['PHI', 'THETA']
As there's no real distinction between a column and image for the CrateData() object, the read, modify, and write sections are essentially the same as above, as shown in this example
chips> cr = read_file("evt2.fits[bin sky=::8]") chips> img = cr.get_image() chips> img Name: EVENTS_IMAGE Datatype: int16 Unit: Desc: Eltype: Array Ndim: 2 Dimarr: (1024, 1024) chips> img.values.mean() 0.35124111175537109 chips> add_image(np.log10(img.values))
although add_piximg() is used rather than add_col() to add the CrateData object to an IMAGECrate.
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.