Event File Specifications

SAOtng supports display of photon event data contained in raw files, similar to its support for FITS Binary Table extensions (e.g., X-ray event lists). This is useful in environments such as X-ray detector development, where raw data is being taken from an instrument and you want to process it without first having to convert to FITS. In order for SAOtng to recognize an event file as such, it is necessary to add the file template to the binary event list entry in the fileaccess.cmds file (since there is no automatic way to recognize such files). This file is in the saord bin directory. The binary event list entry looks like this:

binary event lists
*.ev *.nepr
EVENTS
fitsextract fits='$filename' xcen=$xcen ycen=$ycen xdim=$xdim ydim=$ydim block=$block option=$blocking_preference checkNaN=$donan ofits=stdout type=events mode=h 2>$errorlog
fitsheader fits='$filename' ofits=stdout type=events mode=h

Because event files do not usually contain enough information to generate an image, we have adopted some conventions for specifying how to interpret the data in these files and for how to bin rows of events into images.

To image an event file, it is first of all necessary to define the structure of the events in the event file. (In a FITS binary table, this is done with the TTYPE and TFORMnnn and TTYPEnnn header values). The record structure is specified using the "events=" keyword on the command line or the EVENTS environment variable. The format of string specifying the event record is:

    setenv EVENTS "name1:[n]type1[:dim1],name2:type2[:dim2]..."
or
    setenv EVENTS "name1:[n]type1[lodim1:hidim1]..."

• name is the name of the data element or column
• type is the FITS type (i.e., "I" for 16-bit int, "J" for 32-bit int, "F" for 32-bit float, etc.) for this column. An optional integer value n can be prefixed to the type to indicate that the element actually is an array of n values.
• dim is an optional integer designating the image axis length of this data element, in cases where this column is to be used as an axis for image binning. If only one dimension value is supplied, it is assumed to be the dimension of the image, with axis values running from 0 to dim-1. Alternatively, you can supply both the lo and high axis values, in which case the dimension is calculacted to be hidim-lodim+1.

For example, an AXAF HRC event record is defined as:

setenv EVENTS "(major:J,time:J,dsec:J,aday:I,dmsec:I,amps:6I,uraw:U:4096,vraw:U:49152,upos:U:4096,vpos:U:49152,fupos:U:4096,fvpos:U:49152,minor:B,ev:B,cp:2B,pha:B,scale:B,veto:B,stat:B,smu:B,smv:B,fmu:B,fmv:B,sum:B,pstat:B,dummy:I)"

In addition to knowing the data structure, it is necessary to know the endian ordering of the data, i.e., whether or not the data is in bigendian format, so that we can convert to the native format for this platform. This issue does not arise for FITS Binary Tables because all FITS files use big-endian ordering, regardless of platform. For example, big-endian data produced on a Sun workstation but imaged on a Linux PC needs to be byte-swapped, since PCs use little-endian ordering. To specify an ordering, use the bigendian= keyword on the command-line or the EVENTS_BIGENDIAN environment variable. The value of this variable should be "true" or "false". Thus, for example, for a PC to access data produced by a Sun, use:

  hrc.nepr[bigendian=true]
or
  setenv EVENTS_BIGENDIAN true

Once the structure of the event list is known, it is necessary to specify the two columns to be used for the 2D binning. SAOtng first looks for a "binkey=([xname[:xdim]],[yname[:ydim]])" specifier in bracket syntax, and uses the column names thus specified. For example, to bin the above-mentioned HRC event list columns "VPOS" and "UPOS", use:

  hrc.nepr[binkey=(VPOS,UPOS)]

  hrc.nepr[binkey=(VPOS:49152,UPOS:4096)]

You can set the EVENTS_BINKEY environment variable as an alternative to adding the "binkey=" specifier to each file name. (Note that this is not the same as the FITS_BINKEY environment variable used for FITS binary tables -- experience has indicated that these must be separate so that users can more easily display both kinds of files.)

If no keys are specified or the specified columns are not in the binary table, then SAOtng looks for columns named "X" and "Y". If these are not found, it looks for columns containing the characters "X" and "Y". Thus, you can bin on "DETX" and "DETX" columns if these are the only column names containing the "X" and "Y" characters.

Finally, the data type of the resulting 2D image must be specified. This can be done with the "bitpix=[n]" keyword in the bracket specification. For example:

  bintab.fits[key=(VPOS,UPOS),bitpix=-32]

Event files can have event filtering applied to the events during image extraction. This includes filtering on columns and spatial region filtering.

Last Updated March 24, 1998