STScI Logo

qpoe xray


NAME · DESCRIPTION_ · IMAGE_FILE_SPECIFIERS_FOR_QPOE · QPOE_FILE_SPECIFIERS
EXAMINING_QPOE_FILE_CONTENTS · EXAMPLE_OF_DETECTOR_COORDINATES
MODIFYING_THE_EVENT_DEFINITION · MISCELLANEOUS_ · BUGS · SEE_ALSO

NAME

qpoe -- user interface for QPOE (event) files

DESCRIPTION

QPOE files contain photon event data stored as lists of events. This EVENT list is the primary component of the QPOE file and IRAF will accept this EVENT list in all tasks that accept QPOE files OR IRAF/IMAGE files. Additionally, QPOE files generated in PROS/XRAY contain the accepted time interval data stored as start and stop time records and temporal status records.

IRAF will accept a QPOE file as input in any task that accepts IMAGE files. However, please remember that in such cases, the original QPOE event list has been converted according to the user specification into an IMAGE array. PROS/XRAY tasks which start with qp REQUIRE QPOE event lists, NOT IMAGE arrays. Also only tasks with the qp prefix can WRITE an output QPOE event list. (With the exception of FITS2QP/RFITS2PROS and RARC2PROS.)

IMAGE FILE SPECIFIERS for QPOE

An IMAGE file specifier consists of 3 parts:


	filename.qp[QPOE filter][IMAGE SECTION]

1. QPOE filter specification (optional) ONLY with .qp file extenstions There are 3 important types of entries for the QPOE filter specifier:

a) The block keyword specifies a compression factor for building an IMAGE array from a QPOE event list. NOTE - BLOCK is IGNORED if specified on an IMAGE filename. The blocking is done by SUMMING the counts in the specified number of pixels. e.g. block=4, sums counts in 16 pixels, and creates a new pixel whose dimensions are a factor of 4 larger than the input QPOE file pixel sizes. This operation is equivalent to the task imcompress and blkavg option=sum. (Please see KNOWN BUGS in help release_xray for a description of the coordinate error introduced when using BLOCK).

b) The key keyword specifier defines the EVENT entries that are to be used for the 2 spatial dimenions. By default, these are x and y. These 2 elements are then used to generate the equivalent IRAF IMAGE array, and for REGIONS masking. The default values, x and y can be overriden by use of the key specifier.

c) ALL EVENT attribute names can be used for filtering.

e.g.	pi=41:24
	time = (18126750:188284200)
Complete details on the use of QPOE filters can be found in help filter.

2. IMAGE SECTION specifier (optional>

PLEASE note that the IMAGE SECTION is DIFFERENT from a QPOE filter and must occur in a separate set of square brackets. Also when specifying a file for use as an IRAF IMAGE the BLOCK specification is allowed, but only on QPOE (*.qp) files. BLOCK is NOT allowed (and will be IGNORED) on IMAGE (*.imh,*.hhh) files. An IMAGE SECTION specifies a sub-range of IMAGE array coordinates. PLEASE NOTE that these coordinates are relative to the file specified by


	filename.qp[qpoe filter]

so if a block was specified in the qpoe filter, the IMAGE SECTION is specified in pixel units defined by the BLOCK factor.
	e.g.	xdata$rp110590.qp[block=15,pi=41:240][256:767,256:767]
In this case a 512 x 512 IMAGE is specified using a 7.5" pixel size. The XEXAMINE task will generate these types of IMAGE file specifiers from an input QPOE filename, interactively using the TV display tool (e.g. SAOIMAGE,IMTOOL). See help sections and page imio$doc/imio.doc for a more complete description of the use of IRAF IMAGE SECTIONS.

QPOE FILE SPECIFIERS

Some tasks require an input QPOE file, rather than an IMAGE, since more than that just the 2 spatial coordinates are needed. In PROS, these tasks usually begin with a qp prefix (e.g. qpspec, qpsort, qplist). At a minimum the XSPECTRAL tasks and the XTIMING tasks require QPOE files because they use either the energy or time attributes from the QPOE file for analysis. A QPOE file name consists of only 2 parts:


	filename.qp[QPOE filter - EXCEPT  BLOCK]

A QPOE filter specification can consist of expressions using any of the EVENT data element names. The EVENT records contain a set of data elements that are identified by name and data type. By convention, the names are always lower case.

EXAMINING QPOE FILE CONTENTS

1. EVENT LIST The event list can be examined by using the qplist task as follows:

 qplist xdata$rp110590.qp events+ gti-  tsi- last=8

     x     y   pha    pi             time  detx  dety
  3944    38    21    20     1612531.9799  2410    18
  8018    44    84    85     1612130.5461   871  1578
  4099    45    14    13     1607277.3009  2430    27
  4541    55    13    13     1611920.0229  2438    28
  8818    65    78    79     1607452.6782   778  1716
  4266    76    12    11     1612466.2606  2431    30
  3752    77    28    28     1612145.3589  2480     9
  8074    88    90    91     1607224.6564  1039  1419
  4115    96    16    15     1612637.0782  2445    24

2. GOOD TIME INTERVALS

The GOOD TIME INTERVALS ( GTI ) can be examined by changing the qplist parameters. What is displayed are the start and stop times of the intervals contributing photons to the QPOE file.

xi> qplist xdata$rp110590.qp events- gti+

                        Good Time Intervals

start           end             duration
1606720.00      1607484.00      764.00
1611613.00      1612817.00      1204.00

The GTI records are implemented in the QPOE file in a special way. The time intervals are stored as a DEFAULT FILTER, in the QPOE file. This filter is automatically combined with any user filters at runtime. If the user specifies a TIME filter, the GTI time filter and the user time filter will be combined to produce the intersection of these time selections. (see help filter for details of QPOE filters.) Also, the QPOE file header entry EXPTIME dynamically sums the currently specified TIME filters, to produce a dynamically calculated EXPOSURE TIME. EXPTIME is the ONLY dynamic value in the header, and therefore is the only value that can accurately reflect the CURRENT filters. NOTE: There is currently an IRAF bug when combining filters that are too long. This bug can be avoided by ALWAYS using QPCOPY with the USER filter to produce a NEW QPOE file.

The IRAF/QPOE buffer sizes needed to manipulate these filters, in particular, the deffilt containing the GTI information, can be specified with a user configuration file, QPDEFS. By default, IRAF uses a set of default parameter settings. For observations with many time intervals the default parameters may not be large enough. Please see help filter for more information on how to override the default IRAF settings.

3. TEMPORAL STATUS INTERVALS

The TEMPORAL STATUS INTERVALS ( TSI) can be examined by changing the qplist parameters(ROSAT only). What is displayed is the status of several instrument and telescope parameters according to time.

xi> qplist xdata$rp110590.qp events- gti- tsi+

                        Temporal Status Intervals

start           duration        failed? on/off  tmb     dfb
1606667.00      53.00           2001    2081     1       8
1606720.00      764.00          0       80       1       8
1607484.00      233.00          2001    2081     1       8
1607717.00      3841.00         12001   2081     1       8
1611558.00      7.00            2061    20E1     1       8
1611565.00      48.00           2001    2081     1       8
1611613.00      1204.00         0       80       1       8
1612817.00      0.00            10000   80       1       8

Consult the DATA PRODUCTS GUIDE for a complete description of the meaning of these entries. Briefly, any row where the failed? column is zero should be included in the GTI listing, all other values for failed? indicate data exclusion.

There are PROS tasks which allow a user to convert TSI filter expressions into QPOE/time filter expressions that can then be used to filter events in all PROS tasks. See help explain_screens for information and examples on event screening.

EXAMPLE of DETECTOR COORDINATES

PROS uses the header parameter XS-EVENT to define the event definition of the current file.

	.e.g
	XS-EVENT = "{s:x,s:y,s:phi,s:pi,d:time,s:detx,s:dety}"

To display the data on the TV, IRAF defaults to use the x and y element names for builing an array for IMAGE display. However, this can be overridden by the user, using the key command. Any EVENT element of type short can be specified as one of the 2 display dimensions.

Therefore to display an IMAGE in detector coordinates, the user can override the default coordinates as follows:


	xdisplay "xdata$rp110590.qp[key=(detx,dety),bl=16][1:512,1:512]
  or
	xdisplay "xdata$rh110267.qp[key=(rawx,rawy),bl=8][1:512,1:512]

Note that the dimensions of these alternate axes are smaller than the default axes, so the block factor can be reduced. Also they fill only the upper corner of the larger field, so it is important to restrict the display to that IMAGE SECTION.

MODIFYING the EVENT DEFINITION

Most tasks in PROS which create qpoe files from other qpoe files (such as qpcopy, qpsort, qpphase, qplintran, etc.) include the "eventdef" parameter. This allows the user to modify the event definition of the output file. The event definition must be in the form: "{type:name, type:name, ...}", where name is an event element name (such as "x", "time", or "dety") and type is one of the following data types:


        s               short
        i               int
        l               long
        r               real
        d               double
        x               complex

For example,
        {s:x, s:y, s:pha, s:pi, d:time, s:detx, s:dety}
defines a record with 6 short values and 1 double.

The named elements can be anywhere in the event record, although it is encouraged that alignment be maintained. (For example, a double must be on the 0, 4, 8, 12, 16 ... short boundary, while an int must be on a 0, 2, 4, 6, 8, ... short boundary.) Several PROS tasks look up the offsets of these elements by name when manipulating these quantities.

The following aliases are recognized for event definitions:


image           peewee      {s:x,s:y}
energy          small       {s:x,s:y,s:pha,s:pi}
time            medium      {s:x,s:y,s:pha,s:pi,d:time}
detector        large       {s:x,s:y,s:pha,s:pi,d:time,s:detx,s:dety}
-----           region      {s:x,s:y,s:pha,s:pi,d:time,s:detx,s:dety,
                             s:region}
-----           full        {s:x,s:y,s:pha,s:pi,d:time,s:rawx,s:rawy,
                             s:detx,s:dety,s:status}

If the event definition in the output QPOE file has elements not contained in the input QPOE's event definition, the values in those elements will be set to zero.

MISCELLANEOUS

Qpoe files can be created from the ROSAT FITS file (using fits2qp) or from the Einstein image file (using img2qp). Pixel positions are converted to conform to IRAF coordinate conventions and the photon arrival time is converted to the start of the mission. For Einstein this means Jan. 1, 1978 as a base time, rather than the beginning of the observation (see xpr2qp ). For ROSAT this means the start of the spacecraft clock. In either case the value for the base can be found in the header as

	XS-MJDRD + XS-MJDRF
The photons records are normally stored to optimize spatial access, but can be stored in time-order using timsort or qpsort.

BUGS

Please see the KNOWN BUGS in the help release_xray for information on current problems.

SEE ALSO

See the documentation on filtering ( help filter ) for a description of the QPOE filter user interface.

See the documentation on regions ( help regions ) for a description of the QPOE region user interface.

See the documentation on coordinates (help coords ) for a description of PROS coordinate conventions.


Search Form · STSDAS