read_pha

Context: crates

Synopsis

Load a PHA file into a PHACrateDataset.

Syntax

read_pha(filename, mode='r')

Description

Argument	Description
filename	Name of the file; it can include CIAO Data Model syntax such as filters and binning values
mode	Should the mode be opened for read-only ('r', the default), or for read-write access ('rw').

The read_pha command loads the specified PHA file into a PHACrateDataset.

Example

>>> cds = read_pha("pha2")
>>> print(cds)

The output of the print command is:

   PHA Crate Dataset:
     File Name:         pha2
     PHA Type:          2
     Read-Write Mode:   rw
     Number of Crates:  3
       1)     Crate Type:        <IMAGECrate>
   Crate Name:        PRIMARY

       2)     Crate Type:        <TABLECrate>
   Crate Name:        SPECTRUM
   Ncols:             13
   Nrows:             12

       3)     Crate Type:        <TABLECrate>
   Crate Name:        REGION
   Ncols:             10
   Nrows:             36

In this example the PHA file is a type II grating dataset and was obtained from TGCat.

The mode argument

When a file is read in, the write permission is checked against the mode argument and, if it does not match (if mode='rw' but the user does not have write permission, or the file is a gzipped file) then a warning is displayed and the mode is set to 'r'.

When is the mode argument used?

The mode argument is only relevant if you call the write method of the crate with no arguments; that is if you say

>>> cr = read_file('tbl.dat', mode='rw')
UserWarning: File 'tbl.dat' does not have write permission. Changing to
read-only mode.
...
>>> cr.write()
IOError: File is not writeable.

It is not used if you want to write to a new file or one that is not write protected. That is, you can read in a file in read-only mode, change its contents, and write it out to a new file:

>>> cr = read_file('img.fits', mode='r')
>>> ivals = cr.get_image().values
>>> ivals += 1
>>> cr.write('modified.fits')

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.