cratedata

Synopsis

CrateData object types in the CRATES library.

Description

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 Objects

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

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

SKY(X,Y)

.

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.

Virtual Objects

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.

Important fields of a CrateData object

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.

Reading in a column

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)

Modifying a column

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.

Creating a column

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.

Vector columns

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]

Virtual columns

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

How about images?

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.

Changes in CIAO 4.4

The fields of a CrateData() object have changed in CIAO 4.4. The main user-visible change is that the values field is now used to get and set the data values, as shown in the comparison below:

cd = CrateData()
cd.name = "x"
cd.values = x
print("Values: {0}".format(cd.values))

cd = CrateData()
cd.name = "x"
cd.load(x, 1)
print("Values: {0}".format(cd.get_values()))

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

crates

get_col, get_colvals, get_piximg