STScI Logo

qpsim xray.xspatial


NAME · USAGE · DESCRIPTION · DEFINING_THE_DATA · GENERATING_THE_EVENTS
CREATING_THE_QPOE_FILE · PARAMETERS · EXAMPLES · SEE_ALSO

NAME

qpsim -- Generate simulated events for a ROSAT HRI field.

USAGE

qpsim srctab refqp outroot (livetime)

DESCRIPTION

qpsim generates simulated data representing a ROSAT HRI observation. The task has the capability of generating random background as well as sources of a specified intensity, postion and shape. When generating source counts, the user has a selection of two PRF shapes, either the ROSAT HRI (as described by David et al.) or a Gaussian.

The simulated data are appended to the input reference QPOE file. The default case is to append the data to a QPOE file consisting only of a header, but the user may specify a "real" observation for which to append the events.

DEFINING THE DATA

An input source table is used to describe the desired source and background properties. The source table must contain the following columns (in the specified order) :


x   y   itype   intensity   prf_type   prf_param

where the columns are described as :

	x 	  - X coordinate of source center in sky pixels

	y 	  - Y coordinate of source center in sky pixels

	itype	  - Intensity type, either "counts" or "rate"

	intensity - Source intensity, a value in units appropriate
		    to the itype specification, either counts or cts/sec 

	prf_type  - Type of PRF to use when generating the source events.
		    Choices are bkgd|roshri|gauss_sig|gauss_oaa.  See 
		    table below for the specification of prf_type and
		    prf_param.

	prf_param - A value describing the selected PRF, either offaxis
		    angle (in arc minutes) or sigma (in pixels).  If a 
		    value of INDEF is given, an offaxis angle will be
	 	    calculated using the x,y position.  See table below
		    for how to use prf_type and prf_param.


	prf_type	PRF function	      prf_param	
	---------------------------------------------------

	"bkgd"		background (no PRF)   not used

	"roshri"	ROSAT HRI 	      offaxis angle (arc min.)

	"gauss_sig"	Gaussian	      sigma value (pixels)
 
	"gauss_oaa"	Gaussian	      offaxis angle (arc min.)

The task tcreate, in the STSDAS Tables package, can be used to generate the source table from an ascii file. A sample column descriptions file is contained in xspatialdata$srclst.cd and is reproduced here for reference. See Example 1 below for more details.


	Source Table Column Descriptions File
	-------------------------------------

	x		i	i5	pixels
	y		i	i5	pixels
	itype   	ch*10	s10	
	intensity	r	f6.2	cnt/sec|cnts
	prf_type	ch*10	s10	
	prf_param	r	f6.2	oaa|sigma

A value of LIVETIME is required if "rate" is specified as the "itype" value for any of the sources in the input source table. The user may specify a value to use with the hidden parameter "livetime". If this value is zero, the value of LIVETIME is taken from the reference QPOE file. (Note that the header file xspatial$data/hdummy.qp has a LIVETIME value of zero, and therefore would require input via the hidden parameter.)

GENERATING THE EVENTS

The background is specified as a special source in the input table file (see example below). The table values of x, y, and prf_param are ignored in this case. There is no associated PRF function for the background. Event positions are randomly distributed over the whole field. The X and Y coordinates of the events are selected independently.

The point response function is assumed to be azimuthally symmetric and of the type specified by parameter prf_type. The prf radial profile is used to distribute events randomly in distance from source center. Events are distributed uniformly in azimuth. The prf may be specified as either the actual HRI prf (roshri), as measured by David et al. (sec. 3.2.3) or a Gaussian with a specified sigma (gauss_sig). For backward compatibility with the PROS LDETECT task, the prf may also be specified as a Gaussian at a given off_axis angle (gauss_oaa). In this case the prf is assumed Gaussian with a 50% power radius as shown in Fig.10 of David et al.

Note that all events, both background and source events, are screened to fall within the field size limits. For the ROSAT HRI, this is taken to be the central 4096x4096 box ([2048:6144, 2048:6144]).

CREATING THE QPOE FILE

The events are first written as an ascii list. This list is converted to a QPOE file with the qpcreate task. Finally, this QPOE file is appended to the reference QPOE file with the qpappend task, and written out to a new QPOE file whose name is derived from the "outroot" parameter.

Currently there is no capability for simulating PHA values or event times. Therefore, the event size of the final output QPOE file is always "small". The task may issue many WARNING's assocaited with the absence of the time attribute or DEFFILT's, which the user can ignore (see examples below).

SPECIAL NOTE : The value of "outroot" is constrained to the current working directory. This is a requirement of the qpcreate task.

PARAMETERS

srctab = ""

The input source table. The individual source and background properties are described in this file.

refqp = "xspatial$data/hdummy.qp"

Reference QPOE file. The simulated data is appended to this file. The LIVETIME of the reference QPOE file may be used to calculate total source counts in the event that "rate" is used as the intensity type and the hidden parameter "livetime" is zero.

outroot = ""

Root name for output files. The user is encouraged to use a name that is unique from the root of the input source table to avoid file name conflicts. In addition, qpsim requires that the output file be written to the user's working directory.

(livetime = 0.) [real]

LIVETIME value. This value is used to calculate source counts when a count rate is specified for the source intensity. If this value is zero, the LIVETIME is taken from the header of the reference QPOE file.

(prftab = "xspatialdata$prfcoeffs.tab") [string]

PRF coefficients table. When "gauss_oaa" is used as the PRF type, this table is used to convert offaxis angle to a sigma value.

(clobber = no) [boolean]

If the output QPOE file already exists, this flag specifies whether or not it can be overwritten.

(display = 1) [int]

The level of stdout display. A setting of 0 should display no output except warnings. Settings above 3 are useful for debugging purposes.

(sort = yes) [boolean]

Flag used to indicate whether or not the events should be sorted. The value of this parameter is passed along to the qpcreate and qpappend tasks.

(ssize = 1000000) [int]

This parameter represents the number of bytes that are to be sorted at a time. The user can then tailor the task to the amount of available memory. See "help qpsort" for more details on sorting.

(qpint = yes) [boolean]

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

(psize = 4096) [int]

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

(bsize = 8192) [int]

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

(mkindex = no) [boolean]

Boolean flag to indicate whether or not an index should be made for the QPOE file. This parameter is internal to the QPOE file and should not normally be changed.

(key = "") [string]

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

(debug = 0) [int]

Debug level. A value greater than 0 will result in the preservation of some intermediate files which are useful for debugging purposes.

EXAMPLES

1. Use qpsim to create a QPOE file consisting of random background and some simulated sources. The source and background data are contained in the ascii file sample.dat.


  xs> type sample.dat
      0      0    rate               5.00 bkgd           INDEF
      5000   2500 counts           200.00 roshri         20.00
      3000   3000 counts           150.00 gauss_oaa      12.00
      2500   4000 counts           100.00 gauss_sig      15.00
      5400   4000 rate               0.45 gauss_oaa      25.00
      4096   4096 counts            75.00 roshri         INDEF
      2800   5000 counts           120.00 gauss_oaa      INDEF
      3400   5600 counts           175.00 roshri         INDEF

  xs> tcreate sample.tab xspatialdata$srclst.cd sample.dat

  xs> tprint "sample.tab"
  (row)      x      y itype         intensity prf_type   prf_param
        pixels pixels            cnt/sec|cnts            oaa|sigma

      1      0      0 rate               5.00 bkgd           INDEF
      2   5000   2500 counts           200.00 roshri         20.00
      3   3000   3000 counts           150.00 gauss_oaa      12.00
      4   2500   4000 counts           100.00 gauss_sig      15.00
      5   5400   4000 rate               0.45 gauss_oaa      25.00
      6   4096   4096 counts            75.00 roshri         INDEF
      7   2800   5000 counts           120.00 gauss_oaa      INDEF
      8   3400   5600 counts           175.00 roshri         INDEF

  xs> qpsim livetime=600
  Input source table file: sample.tab
  Reference QPOE file (xspatial$data/hdummy.qp): 
  Root name for output files: test

  ### Generating simulated data ###

  Beginning run of SIMEVT ... 

  Using LIVETIME of 600.00 seconds to determine source counts

  Generating random background events ... 

  SIMEVT all done.

  ### Creating QPOE with simulated data ###

  FITSNAME      FILENAME              DIMENS     BITPI BSCALE       BZERO    O
  test.fits     null_image            0 
    BINTABLE    test.tab              2Cx4090R   8bin
  QPEX Warning: bad attribute name `time'
  QPEX Warning: bad attribute name `time'
  QPEX Warning: bad attribute name `time'
  No GTI records in file - no TIME update done
  writing output file  - test_sim.qp

  ### Appending simulated data to reference QPOE ###

  ref file:   RA: 9:00:00.0000 Dec: 45:00:00.0000 Roll: 0.0000
  file # 2  RA: 9:00:00.0000 Dec: 45:00:00.0000 Roll: 0.0000
  offsets(arcsec):  RA: -0.0000 Dec: -0.0000 Roll: 0.0000
  file # 2  xref: 4096.0000 yref: 4097.0000 
  offsets(pixels):  xoff: 0.0000 yoff: 0.0000 
  Opening file #1 : xspatial$data/hdummy.qp 
  QPEX Warning: bad attribute name `time'
  WARNING: no TSI records found in file #: 1
  QPEX Warning: bad attribute name `time'
  No GTI records in file - no TIME update done
  No GTI records in file - no TIME update done

  file: 1 xspatial$data/hdummy.qp events: 0 times: 0.0
  QPEX Warning: bad attribute name `time'
  No GTI records in file - no TIME update done
  No GTI records in file - no TIME update done

  file: 2 test_sim.qp events: 4090 times: 0.0

  @testapp.lst2532a (; 2 files, no exp.) -> test.qp
  Creating QPOE output file: test.qp

  Renaming output file : test.qp
  xs>

2. Use qpsim to inject a simulated source into an existing QPOE file.


  xs> tprint ksrc100.tab
  (row)      x      y itype         intensity prf_type   prf_param
        pixels pixels            cnt/sec|cnts            oaa|sigma

      1   4080   4080 counts           150.00 roshri         INDEF

  xs> qpsim 
  Input source table file: ksrc100.tab
  Reference QPOE file (xspatial$data/hdummy.qp): kepler.qp
  Root name for output files: kepler100

  ### Generating simulated data ###

  Beginning run of SIMEVT ... 

  SIMEVT all done.

  ### Creating QPOE with simulated data ###

  FITSNAME      FILENAME              DIMENS     BITPI BSCALE       BZERO    O

  kepler100.fit null_image            0                                        
     BINTABLE    kepler100.tab         2Cx150R    8bin

  QPEX Warning: bad attribute name `time'
  QPEX Warning: bad attribute name `time'
  QPEX Warning: bad attribute name `time'
  No GTI records in file - no TIME update done
  writing output file  - kepler100_sim.qp

  ### Appending simulated data to reference QPOE ###

  ref file:   RA: 17:30:40.7760 Dec: -21:29:24.0000 Roll: 0.0000
  file # 2  RA: 17:30:40.7760 Dec: -21:29:24.0000 Roll: 0.0000
  offsets(arcsec):  RA: -0.0000 Dec: 0.0000 Roll: 0.0000
  file # 2  xref: 4096.0000 yref: 4097.0000 
  offsets(pixels):  xoff: 0.0000 yoff: -0.0000 
  Opening file #1 : kepler.qp 
  QPEX Warning: bad attribute name `time'
  QPEX Warning: bad attribute name `time'

  file: 1 kepler.qp events: 422571 times: 0.0
  QPEX Warning: bad attribute name `time'
  No GTI records in file - no TIME update done
  No GTI records in file - no TIME update done

  file: 2 kepler100_sim.qp events: 150 times: 0.0

  @kepler100app.lst2532e (; 2 files, no exp.) -> kepler100.qp
  Creating QPOE output file: kepler100.qp

  Renaming output file : kepler100.qp
  xs>

SEE ALSO

See tcreate for details on constucting an input table from an ascii file. See qpcreate for details on how the simulated event list is converted to QPOE format. See qpappend for details on how the simulated QPOE file is appended to the reference QPOE file.

For a description of the HRI prf, see David,L.et al. 1995, "The ROSAT High Resolution Imager (HRI)", available via anonymous ftp from SAO.


Source Code · Search Form · STSDAS