filter

filter

xray

filter

NAME · DESCRIPTION · EVENT_ATTRIBUTE_FILTERING · QPOE_FILTER_EXPRESSION_SYNTAX
QPOE_BLOCK_FACTORS · QPOE_KEY_SPECIFICATION · MASKS
USER_DEFINED_MACROS · IMAGE_SECTIONS · SEE_ALSO

NAME

filter -- user interface for filtering QPOE (X-ray event) files

QPOE files contain X-ray photon event data stored as lists of events and accepted time interval data stored as start and stop time records and temporal status records. Event records contain a set of data elements that are identified by name and data type. By convention, the names are always lower case.

For any QPOE file the following command will display the names of attributes available for filtering, displaying them as column headings:

	qplist xdata$rp110590.qp head- ev+ gti- last=1

For Einstein and ROSAT, the following event elements are currently implemented:


	name:	  type:	    description:

	x	  short	    x pixel position
	y	  short	    y pixel position
	pi	  short	    pulse invariant bin (energy)
	pha	  short	    pulse height analyzer channel
	time	  double    photon arrival time
	dx	  short	    raw detector x position
	dy	  short	    raw detector y position
	region	  short	    region value in mask used to make file
	detx	  short	    detector coordinates (w/ instrument corrections)
	dety	  short	    detector coordinates (w/ instrument corrections)
	rawx	  short	    uncorrected instrument coordinates
	rawy	  short	    uncorrected instrument coordinates
	status	  short	    Spatially filtered from standard processing?

EVENT attribute FILTERING

Filtering and compression are available to the user as part of the QPOE file specification. Bracket notation is used to specify QPOE filters. For example, to filter a QPOE file foo.qp by pi in the range of 4-24, specify:


		foo.qp[pi=(4:24)]

The parenthesis are optional and are mainly used when more than one value is to be given for a filter. For example:


		foo.qp[pi=(1,4,8:12,17:)]

will accept all photons with pi values 1,4,8,9,10,11,12, and >=17. In this way, the user can filter by pi, pha, time, dx, dy, detx, dety, rawx, rawy and also by x and y .

QPOE filter expression syntax

The expression on the right hand side of a filter can consist of any of the following:


	expr:		description:		      example:

	N		equality test		      pi=4
	:N		open range (<= N)	      pi=(:4)
	N:		open range (>=N)	      pi=(4:)
	M:N		range (M to N inclusive)      pi=(4:16)
	expr,expr,...	list of values or ranges      pi=(1,4:8,16:)
	! expr		not this expression	      pi=(!4:16)
	@file		get filters from file	      @foo.filter

One can also place filters in a file and specify that file in a filter specification. This is done by specifying:


		foo.qp[@filename]

Thus, if the file foo.filters contains:

		pha=1:4,pi=1:5

the specification:

		foo.qp[@foo.filters]

is equivalent to:

		foo.qp[pha=1:4,pi=1:5]

etc. This can be of great help if one maintains a standard file in an editor window, changing the filters by simply editing the file and then using the file spec as the QPOE filter, rather than the explicit filters themselves. Also, some PROS tasks can produce files containing QPOE filters, e.g. HKFILTER and TIMFILTER.

QPOE BLOCK FACTORS

A block factor allows one to compress QPOE files so that the application program "sees" an image of smaller dimension. (Again, BLOCK is NOT allowed when inputting a QPOE file, to a single-event access task). The compression is done by pixel summing. For example, to compress a 4096x4096 QPOE file into a 256x256 image, as seen by an applications task, one would use a block of 16:


		foo.qp[block=16, pi=(1,4:8,16:)]

QPOE blocking and IMAGE-SECTIONing is strongly recommended for the XSPATIAL tasks, as a means of speeding up those tasks. The task IMCNTS can also be sped up, if necessary, by blocking at the QPOE level. In general, PROS XSPATIAL tasks work most efficiently if the dimensionality of the image as seen by an applications program is 2048 or less. The task XEXAMINE generates QPOE filenames, including BLOCK and SECTION interactively with the TV DISPLAY. See help xexamine.

QPOE `KEY` SPECIFICATION

All QPOE files can be converted dynamically to IRAF IMAGES by any IRAF task that expects an IRAF IMAGE array as input. When doing the conversion for EVENT list to IMAGE array, IRAF assumes that x and y from the EVENT list are to be used as the 2 spatial axes. However, this can be specified by the user, with the use of the key command, thus allowing the QPOE file to be viewed in an alternate coordinate system. For ROSAT and Einstein, the obvious choices for alternate axes are: detx,'dety',rawx,'rawy' (or dx, dy for earlier files).

For example, to display the data on the TV, IRAF defaults to use the x and y element names for building 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 SECTIONS.

MASKS

It is also possible to apply complex spatial filtering to a QPOE file via MASKS. PROS provides a special user interface to MASKS, called REGIONS. Please see help regions for a complete description of how to use this type of filtering. This filtering is such a fundamental part of PROS, that all PROS tasks have special task parameters for specifying the REGION/MASK, rather than using the default IRAF/QPOE bracket notation. The KEY parameter specification also applies to MASKS, so it is possible to use REGION/MASKS to filter in detector coordinates, as well as the default sky coordinates. e

USER defined MACROS

A QPOE definitions file (QPDEFS) can be used to define global macros and default QPOE settings. An example of this file is kept in the xray package directory. Users who wish to use the QPDEFS file should get a copy of QPDEFS from the xray directory, edit it to suit individual needs, and then make it known to IRAF by placing the following line in their loginuser.cl file:


	xr> cd home$
	xr> copy xray$QPDEFS .
	# set the user macros and defaults file for QPOE
	reset qmfiles = "home$QPDEFS"

The QPDEFS file defines internal parameter buffer sizes for use with QPOE files. The copy in XRAY has 3 entries uncommented. If problems are encountered reading QPOE files with long filters, the user should start by doubling each of the 3 uncommented parameter values.

The QPDEFS file can also be used to define macros that can be used in the bracket specification. For example, suppose a user normally does analysis in the upper left-hand quardant of an 8192 x 8192 ROSAT qpoe file. Every task must then have a qpoe filter of the form:


	foo.qp[1:4096,4097:8192]

Instead of explicitly defining such a rect each time, however, one can define a macro in the QPDEFs file such as:


	define	ul	1:4096,4097:8192

This allows the upper left corner to be specified as:

	foo.qp[ul]

Note that QPDEFS sets global defaults, and will override the default in all QPOE files. The xray$QPDEFS file contains a list of QPOE defaults that can be overridden.

IMAGE SECTIONS

When used with IMIO-type tasks (i.e., all non-PROS tasks and all PROS tasks that begin with "im", e.g. XSPATIAL tasks), one can use the normal image section specification to described a image-section of a qpoe file. Thus,


		imcnts foo.qp[400:599,400:599]
and
		imcnts foo.imh[400:599,400:599]

make use of the same IMAGE-SECTION capability.

The image section facility greatly increases the flexibility of the IMIO interface. Image sections are specified as part of the image name input to IMOPEN, and are not visible to the applications program, which sees a somewhat smaller image, or an image of lesser dimensionality. Some examples are shown below.


        section                         refers to

        foo.imh[]                   whole image
        foo.imh[i,j]                the pixel value (scalar) at [i,j]
        foo.imh[*,*]                whole image, two dimensions
        foo.imh[*,-*]               flip y-axis
        foo.imh[*,*,b]              band B of three dimensional image
        foo.imh[*,*:s]              subsample in y by S
        foo.imh[*,l]                line L of image
        foo.imh[c,*]                column C of image
        foo.imh[i1:i2,j1:j2]        subraster of image
        foo.imh[i1:i2:sx,j1:j2:sy]  subraster with subsampling

This image-sectioning is valid only when using a QPOE as an IMAGE. It is not allowed for QPOE tasks that do single photon access (i.e., those that begin with a "qp" in PROS, e.g. XSPECTRAL and XTIMING). Instead, one normally uses a region mask to restrict the photons when performing QPOE I/O. (see help regions)