STScI Logo

timsort xray.xtiming


NAME · USAGE · DESCRIPTION · PARAMETERS · EXAMPLES

NAME

timsort -- create a time-sorted xray data ( qp ) file for source and background.

USAGE

timsort image soutfile sregion boutfile bregion

DESCRIPTION

TIMSORT creates a time-sorted QPOE file. Any type of filtering can be applied to the input QPOE file, including region filtering. A time-sorted file is the necessary input to the timing package. This task allows the creation of both a source file and a background file. For timing analysis, the user is required to select the background from the same file as the source. However, both the source and background files can be generated from any spatial region of the input file. The output file will be a valid qp file. However, because this new qp file is time-sorted, it is very inefficient to apply standard spatial or spectral tasks to this file. It requires disk space TWICE the size of the input QPOE file to successfully sort. The input size is determined by the definition of the REGIONS and FILTERS applied to the input file. Also, if the input file is LONGER than ~20-25Mbytes, it will be necessary to adjust the sortsize parameter (nominally 1Mbyte). This is necessary because the Operating System won't support more than ~25 simultaneous files. So the rule of thumb would be to make sortsize equal to 1/20 of the size of the input QPOE file. Of course, your system must have sufficient memory to allocate a buffer of size sortsize. So, adjusting sortsize and finding sufficient disk space should are necessary to tune this task for large files. However, for a file >25 Mbytes we also recommend doubling pagesize and bucklen, and >50 Mbytes they should be quadrupled. This error never appears until the very end of the task.

PARAMETERS

image = prompt = input QPOE file name

Required input QPOE file name. The file must have a ".qp" extension, but may be specified with or without the extension. QPOE filters can be applied using the bracket notation to filter the input photons.

soutfile = prompt = Output source time sorted data set

The output source QPOE file name. If NULL ( "" ) is input a default filename will be generated with a name identical to the image name root, with a "_sti.qp" extension.

sregion = prompt = source region descriptor

The source region descriptor. Photons which pass the spatial region filter are copied. This is usually a circle centered on the desired source position. If NULL ("") is input, the entire field is copied. All photons are subject to the QPOE filters specified with the input file name.

boutfile = "NONE" prompt = Output bkgd time sorted data set

The output background QPOE file name. If NULL ( "" ) is input a default filename will be generated with a name identical to the image name root, with a "_bti.qp" extension.

bregion = prompt = background region descriptor

The background region descriptor. Photons which pass the spatial region filter are copied. If NULL ("") is input, the entire field is copied. All photons are subject to the QPOE filters specified with the input file name.

(exp = "NONE") [string]

The exposure mask file in PLIO format specific to the source image. If NULL ("") is input a default file name will be generated with a name identical to the image name root, with a "_exp.pl" extension. If "NONE" is input, no exposure filtering is performed.

(ethresh = 0.) [real]

The percentage of total exposure required for a given source pixel to pass the exposure filter. For example, if expthresh is 50.0, then only pixels whose exposure time is >= 50% will be used. An exposure threshold of 0% allows all photons to pass the exposure filter.

(esize = "region") [string]

The size of the QPOE file to be created. Examples of valid inputs are:

	"medium" (x,y,pi,pha,time),
	"large" (x,y,pi,pha,time,dx,dy),
	"region" (x,y,pi,pha,time,dx,dy,region), or
	"xlarge" (x,y,pi,pha,time,dx,dy,s10,s11), or
	"full"   
	"slew"   
	any unique abbreviation
There is no default. All of these files are the same size, due to implicit padding of the QPOE record.
(clobber = no) [boolean]

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

(display = 0) [int]

The display level. A display level of 0 generates no display. A display level of 1 generates a display of header information.

(ssize = 1000000) [int]

The number of bytes that are to be sorted at a time. This allows users to tailor the task to the amount of available memory. If there is a lot of memory available, sortsize should be set larger than the number of events. The task will then do an in-core sort. If only a small amount of memory is available, use a smaller number. In this case, several core loads will be sorted and written to temp files, which are then merged.

(qpi = 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 on during stand-alone debugging only.)

(psize = 1024) [int]

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

(bsize = 2048) [int]

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

(debug = 0) [int]

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

EXAMPLES

1. Create a time sorted source file for a source at position 502 513. Use the default file naming and do NOT produce a background file.


	xt> timsort
	input qpoe file name: xdata$snr.qp           
	Output time-ordered file name: .
	source region descriptor: c 502 513 24
	Output time-ordered bkgd file name (NONE):

	starting source creation - snr_sti.qp

2. Create a time sorted source file and background file using command line format.

	xt> timsort "xdata$snr.qp" "snr_sti.qp" "c 502 513 24" "snr_bti.qp" 
		"a 502 513 26 28" 
	    
	    starting source creation - snr_sti.qp
	    starting  bkgd  creation - snr_bti.qp

3. Create a time sorted source file using a filter for the first good time interval. (Type help timfilter for information concerning gti filtering)

	xt> timsort
	input qpoe file name: xdata$snr.qp[time=(79486997.99:79488826.47)]
	Output time-ordered file name: snr1
        source region descriptor: c 502 513 24
        Output time-ordered bkgd file name (NONE):

	starting source creation - snr1_sti.qp

4. Create a time sorted source file using a merged filter for all of the 
good time intervals.  (Example 2 of the TIMFILTER help file shows how
to make the input filter list "merged.tim".)
.nf

	xt> timsort
	input qpoe file name: xdata$snr.qp[@merged.tim]
        Output time-ordered file name: merg
        source region descriptor: c 502 513 24
        Output time-ordered bkgd file name (NONE):

	starting source creation - merg_sti.qp

.ih
TIME REQUIREMENTS
.ih
BUGS
        There is an IRAF bug affecting some uses of regions applied to 
non-sorted ( e.g. time-sorted) QPOE files.  If encountered, ( the task
will die with a FATAL ERROR), this problem can be worked around
by using QPCOPY first with a region and then TIMSORT with region=NONE,
or running QPSORT/TIMSORT with region=NONE.

This routine has several parameterized system requirements.  First
it needs a large memory buffer in which to do the event sorting.
Secondly it needs 2 QPOE file buffer sizes to optimally store
the sorted file.
The ssize parameter should be made as large as the memory available
on the users machine allows.  If more space is required, the
sort will be done via temporary disk files in the working directory.
There is normally a limit to the number of temporary files allowed,
probably between 20-30.  If the output file size is greater than
30 x ssize, the task will fail.  The only option is to increase
the ssize if possible, or to reduce the size of the selected region
to decrease the number of EVENTS.  
If the ssize parameter is set LARGER than the memory available, it's 
possible that the task will thrash, to the extent that it may never finish.

Also the psize and bsize parameters are related to the size of the output
QPOE file.  For files > 100Bbytes these nominal setting should be
doubled.
.ih
SEE ALSO
Documentation on region filtering (\fIhelp regions\fR) for a
description of the spatial filter user interface.

Documentation on QPOE filtering (\fIhelp qpoe\fR) for a description of
the QPOE filter user interface.

Documentation on file extensions (\fIhelp extensions\fR) for a
description of PROS file extensions.

Documentation on coordinates (\fIhelp coords\fR) for a description of
PROS coordinate conventions.
.endhelp



Search Form · STSDAS