STScI Logo

fits2qp xray.xdataio


NAME · USAGE · DESCRIPTION · PARAMETERS · EXAMPLES · PARAMETER_FILE_EXAMPLES
SCALING · TIME_REQUIREMENTS · BUGS · SEE_ALSO

NAME

fits2qp -- convert a FITS file (containing BINTABLE extensions) into an IRAF/PROS qpoe file

USAGE

fits2qp fits qpoe

DESCRIPTION

fits2qp converts a FITS file into a PROS qpoe file. The FITS files are expected to conform to the OGIP standard for EVENT FITS files. The task also converts ASCII files created in the MPE archival format(only). All parameters in the FITS file are added to the qpoe file. The parameter translation files (see below) specify name translations and actions triggered by special parameters. WCS (World coordinate system) parameters are used to create qpoe WCS information. The table specified as the event table (by the event parameter in the FITS file) is converted into the main X-ray event structure in the QPOE file.

This task is a very general utility, but for any given FITS file it may require a great deal of parameter optimization as well as translation files to produce the desired results. For all ROSAT and EINSTEIN data, specialized scripts exist that have the correct parameter settings. (See the 'see also` section below.)

The task is sufficiently general that it will try to convert almost any FITS file containing BINTABLE tables (Cotton's binary table extension). If a standard OGIP FITS file is not used as input, several parameters (naxes, axlen1, axlen2, events) must be set in the task in order to specify which table contains the event records. All other BINTABLE tables are converted to qpoe opaque header arrays.

The current implementation ignores all other types of FITS data, including images and ASCII tables, except ASCII files created in the MPE archival format. This may be changed in a future release. For now we recommend the use of the TABLES task strfits to handle these other formats. All data is assumed to be in FITS machine independent format (IEEE format) and will be converted into host format before being added to the QPOE file.

PARAMETERS

fits = "" prompt = input BINTABLE FITS file name

The input FITS file name.

qpoe = "tempqp" prompt = output IRAF/PROS QPOE file name

The output IRAF/PROS qpoe file name. If OLDQPOENAME is set below this output file name will be superceded by the filename defined inside the FITS file using a RENAME at the end of the program. If the null string is input, the name will be the same root as the fits file with a ".qp" extension. If a "." is used the name will be the same as the root input name WITHOUT the PATH. i.e. the output file will be in the current working directory.

(naxes = 0) [int]

The number of axes that the qpoe file will contain. This should be 2 for the current implementation. This parameter is only used if the FITS file does not contain the NAXES parameter, either in the main FITS header or in one of the BINTABLE headers. For standard PROS FITS files, this value is stored in the FITS file.

For MPE ASCII FITS files, set naxes = 2

(axlen= 0) [int]

The dimension of the first qpoe axis. This parameter is only used if the FITS file does not contain the AXLEN1 parameter, either in the main FITS header or in one of the BINTABLE headers, or the TLMAXnnn keywords for the default columns. For standard PROS FITS files, this value is stored in the FITS file.

For MPE ASCII FITS files, this number will depend on the instrument:
	PSPC: set axlen1 = 15360
	HRI:  set axlen1 =  8192
(axlen= 0) [int]

The dimension of the second qpoe axis. This parameter is only used if the FITS file does not contain the AXLEN2 parameter, either in the main FITS header or in one of the BINTABLE headers, or the TLMAXnnn keywords for the default columns. For standard PROS FITS files, this value is stored in the FITS file.

For MPE ASCII FITS files, this number will depend on the instrument:
        PSPC: set axlen1 = 15360
        HRI:  set axlen1 =  8192
(mpe_ascii_fits = no) [string]

If the input file is an MPE ASCII FITS table, set this boolean to "yes", else leave it as "no"

(clobber = no) [boolean]

Boolean flag specifying whether or not the qpoe file can be overwritten, if it already exists.

(oldqpoename = yes) [boolean]

Boolean flag to specify if the output file name should be generated automatically from the FITS keyword QPOENAME, overriding the output qpoe file name specified above by doing a RENAME at the end of the task. In this case the OUTPUT filename above must be a dummy name that will NOT conflict with the internal QPOENAME.

(display = 1) [int]

The display level. Not currently used.

(fits_cards = "xdataio$fits.cards") [string]

The name of the fits parameter translation file. This is internal to the task and not normally changed by the user.

(qpoe_cards = "xdataio$qpoe.cards") [string]

The name of the qpoe parameter translation file. This is internal to the task and not normally changed by the user.

(ext_cards = "xdataio$ext.cards") [string]

The name of the ext parameter translation file. This is internal to the task and not normally changed by the user.

(wcs_cards = "xdataio$wcs.cards") [string]

The name of the wcs parameter translation file. This is internal to the task and not normally changed by the user.

(old_events = "EVENTS") [string]

The name of the BINTABLE in the FITs file containing the events.

(std_events = "STDEVT") [string]

The name of the BINTABLE in the FITs file containing the events. It is the default name for the ROSAT standard event list in RDF format.

(rej_events = "REJEVT") [string]

The name of the BINTABLE in the FITs file containing the rejected events. It is the default name for the ROSAT rejected events in RDF format.

(which_events = "old") [string]

Which of the above 3 specified EVENT tables should be used to create the main QPOE event list.

(oldgti_name = "GTI") [string]

The name of the BINTABLE in the FITs file containing the standard good time intervals, corresponding to the EVENT list.

(allgti_name = "ALLGTI") [string]

The name of the BINTABLE in the FITs file containing the 'good time intervals' corresponding to ALL the events (standard+rejected).

(stdgti_name = "STDGTI") [string]

The name of the BINTABLE in the FITs file containing the 'good time intervals' corresponding to the STANDARD events for ROSAT data in RDF format.

(which_gti = "old") [string]

Which of the above 3 specified GTI tables should be used to create the main QPOE gti list.

(scale = "yes") [boolean]

Should the TSCAL and TZERO keywords be used to apply scaling to extension or event columns?

(key_x = "x") [string]

Name of the event keyword to use for the x-index of the QPOE file.

(key_y = "y") [string]

Name of the event keyword to use for the y-index of the QPOE file.

(qp_internals = yes) [boolean]

Boolean flag controlling whether the internal qpoe parameters (see below) are prompted for, or whether they are defaulted to internally hardwired values. This parameter is not usually changed by the user. (Prompting is normally turned off during stand-alone debugging only.)

(qp_pagesize = 2048) [int]

Page size for the qpoe file. This parameter is internal to qpoe and should not normally be changed.

(qp_bucketlen = 4096) [int]

Bucket length for the qpoe file. This parameter is internal to qpoe and should not normally be changed.

(qp_blockfactor = 1) [int]

Block factor for imio. This parameter is internal to qpoe and should not normally be changed.

(qp_mkindex = no) [boolean]

Boolean flag that an index should be made for the qpoe file. This parameter cannot be set unless you KNOW for sure that the input FITS files has a correctly spatially sorted EVENT list. (This was true in ROSAT PRE-RDF US processing)

(qp_key = "") [int]

Key on which to make the qpoe index. This parameter is internal to qpoe and should not normally be changed.

(qp_debug = 0) [int]

Debug level for qpoe internals. This parameter is internal to qpoe and should not normally be changed.

EXAMPLES

Convert a BINARY FITS file to a qpoe file.


cl> xray
xr> xdataio
xd> fits2qp foo.fits 
output IRAF/PROS QPOE file name: . 
Writing output QPOE file: ./foo.qp

PARAMETER FILE EXAMPLES

The following are the proper parameters for MPE ASCII FITS files:

 	For PSPC files - 

         fits = "filename.fits" input FITS file name
         qpoe = "."             output IRAF/PROS QPOE file name
       (naxes = 2)              number of axes in qpoe file
      (axlen1 = 15360)          dimension of qpoe axis #1
      (axlen2 = 15360)          dimension of qpoe axis #2
(mpe_ascii_fi = yes)            Is this an MPE ASCII FITS table?
     (clobber = yes)            delete old copy of output file
 (oldqpoename = no)             Use auto-naming from FITS QPOENAME card?
     (display = 1)              display level
  (fits_cards = "xdataio$fits.cards") definitions for FITS cards
  (qpoe_cards = "xdataio$qpoe.cards") definitions for qpoe cards
   (ext_cards = "xdataio$ext.cards") definitions for qpoe cards
   (wcs_cards = "xdataio$wcs.cards") definitions for wcs cards
  (old_events = "EVENTS")       old name of table containing event records
  (std_events = "STDEVT")       name of table containing standard event records
  (rej_events = "REJEVT")       name of table containing rejected event records
(which_events = "old")          which event table name
 (oldgti_name = "GTI")          Old FITS root for GTIs
 (allgti_name = "ALLGTI")       Rationalized FITS root for all GTIs
 (stdgti_name = "STDGTI")       Rationalized FITS root for standard GTIs
   (which_gti = "standard")     GTIs for initial deffilt
       (scale = yes)            apply TSCAL/TZERO scaling?
       (key_x = "x")            index key for x coordinate QPOE events
       (key_y = "y")            index key for y coordinate QPOE events
(qp_internals = yes)            prompt for qpoe internals?
 (qp_pagesize = 2048)           page size for qpoe file
(qp_bucketlen = 4096)           bucket length for qpoe file
(qp_blockfact = 1)              block factor for imio
  (qp_mkindex = no)             make an index on y, x
      (qp_key = "")             key on which to make index
    (qp_debug = 0)              qpoe debug level
        (mode = "ql")


        For HRI files -

         fits = "filename.fits" input FITS file name
         qpoe = "."             output IRAF/PROS QPOE file name
       (naxes = 2)              number of axes in qpoe file
      (axlen1 = 8192)           dimension of qpoe axis #1
      (axlen2 = 8192)           dimension of qpoe axis #2
(mpe_ascii_fi = yes)            Is this an MPE ASCII FITS table?
     (clobber = yes)            delete old copy of output file
 (oldqpoename = no)             Use auto-naming from FITS QPOENAME card?
     (display = 1)              display level
  (fits_cards = "xdataio$fits.cards") definitions for FITS cards
  (qpoe_cards = "xdataio$qpoe.cards") definitions for qpoe cards
   (ext_cards = "xdataio$ext.cards") definitions for qpoe cards
   (wcs_cards = "xdataio$wcs.cards") definitions for wcs cards
  (old_events = "EVENTS")       old name of table containing event records
  (std_events = "STDEVT")       name of table containing standard event records
  (rej_events = "REJEVT")       name of table containing rejected event records
(which_events = "old")          which event table name
 (oldgti_name = "GTI")          Old FITS root for GTIs
 (allgti_name = "ALLGTI")       Rationalized FITS root for all GTIs
 (stdgti_name = "STDGTI")       Rationalized FITS root for standard GTIs
   (which_gti = "old")
  (fits_cards = "xdataio$fits.cards") definitions for FITS cards
  (qpoe_cards = "xdataio$qpoe.cards") definitions for qpoe cards
   (ext_cards = "xdataio$ext.cards") definitions for qpoe cards
   (wcs_cards = "xdataio$wcs.cards") definitions for wcs cards
(qp_internals = yes)            prompt for qpoe internals?
 (qp_pagesize = 2048)           page size for qpoe file
(qp_bucketlen = 4096)           bucket length for qpoe file
(qp_blockfact = 1)              block factor for imio
  (qp_mkindex = no)             make an index on y, x
      (qp_key = "")             key on which to make index
    (qp_debug = 0)              qpoe debug level
        (mode = "ql")

SCALING

The header keywords TSCAL# and TZERO# are used to apply a scalar transformation on a particular column in an extension. For instance, the values TSCAL3=2.5 and TZERO3=-3.0 indicates that the third column should undergo the transformation new_value = (2.5*column_value)-3.0. This scaling is only performed if the parameter "scale" is set to yes.

It is possible that these keywords will promote the column type. The following describes when promotion occurs:

old column type          promotion?             
---------------          -----------
t (byte) or s (short)    Promotes to i (int) if one of TSCAL or TZERO 
                         exists.  Promotes to r (real) if both exist.
                         The x- and y-index keywords will not be pro-
                         moted.

i (int) or l (long)      Promotes to r (real) if both TSCAL and TZERO
                         exist.  No promotion if only one exists.

r (real), d (double),    No promotion.
or x(complex)        

TIME REQUIREMENTS

This task takes approximately 5 minutes on a Sun-3 to convert a fits file containing 100,000 photons. Luckily, it is run only once per image.

BUGS

This task makes a single HEADER file from multiple input FITS/BINTABLE extensions. Therefore not all the header information is preserved, especially COMMENTS and HISTORY.

It is the intention that unknown header information is written to the QPOE file ONLY IF the header is the main header or the event header. However, this task only knows that the current header is the event header after it reaches the EXTNAME card. Thus all unknown header keywords in the event header before the EXTNAME card are ignored.

If the TSCAL or TZERO keywords are applied to either the x- or y-index keywords in the events extension, the keywords should not be promoted to be a floating point. However, if the EXTNAME card appears after the TTYPE header card defining the x- or y-index, then the index type will be incorrectly promoted, causing FITS2QP to fail. The workaround is to move the EXTNAME keyword earlier in the extension.

This task requires a great many specialized parameter settings to configure it to convert various different types of FITS data files. For all standard cases, e.g. ROSAT and EINSTEIN data files automatic scripts exist (see below) The default parameters have been selected to agree with ASCA FITS data files.

When this task is run stand-alone, it is HIGHLY recommended that the qpsort task be run to produce a spatially sorted, INDEXED QPOE file, which is optimized for display, etc.

SEE ALSO

help rfits2pros for an automated routine to convert ALL US/ROSAT data files from GO tapes.

help rarc2pros for an automated routine to convert ALL ROSAT archive data files.

help efits2qp for an automated routine to convert EINSTEIN FITS files into QPOE format.

For MPE FITS files and any foreign FITS files, QPSORT may need to be run on the resultant QPOE file, to produce a spatially sorted file and INDEX. An IRAF bug may prevent the use of REGIONS with a QPOE file that has NOT been spatially sorted and indexed.


Source Code · Search Form · STSDAS