STScI Logo

apply_bary xray.xtiming.timcor


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

NAME

apply_bary -- apply barycenter time corrections to the time-sorted QPOE file

USAGE

apply_bary input_qpoe corr_table eventdef output_qpoe

DESCRIPTION

apply_bary apply barycenter time corrections to the time-sorted QPOE file. The task calc_bary MUST be run before this task. The task calc_bary calculates the barycenter corrections for the orbit data and produces a table of corrected orbit times.

This task, apply_bary , reads the correction table and APPLIES the corrections to the photons and good time intervals in the QPOE file.

The input QPOE file MUST be time-sorted with TIMSORT prior to running this task.

The output QPOE times are in seconds from noon of the MJD of the start of the first OBI.

To convert the times to MJD use the following formula:

MJDREFI + MJDREFF + (photon_time / 86400)

The values MJDREFI and MJDREFF can be found in the header of the output QPOE file. (MJDREFF should be 0.5)

Since apply_bary changes these values to correspond to noon of the MJD containing the start of the first OBI, users who wish to perform timing analyses on merged qpoe files should run qpappend before running apply_bary. Otherwise, the values of XS-MJDRD and XS-MJDRF in the various qpoe files may not agree and qpappend will be unable to append them (see help qpappend for further details). In general, this will also mean merging individual ephemeris tables prior to running calc_bary. Example 2 below deals with this topic further.

PARAMETERS

input_qpoe = "" prompt = input qpoe file name

The input qpoe file name. The file must have a ".qp" extension, but may be specified with or without the extension.

tblfile = "" prompt = input correction table filename

The table file with the barycenter corrected orbit records that was produced by the task calc_bary

eventdef = "large" prompt = event definition

The event definition of the output QPOE file. If the user enters the empty string, "", the event definition will be copied from the input QPOE file. See help qpoe for information on modifying the event definition.

The default of "large" represents the following event definition:


	  {s:x,s:y,s:pha,s:pi,d:time,s:detx,s:dety}
qpoe = "" prompt = output qpoe file name

The output qpoe file name. The file must have a ".qp" extension, but may be specified with or without the extension.

(region = "")

The region descriptor. This parameter should not be changed. If the user wants to select a region, it should be applied in task TIMSORT. See BUGS below.

(scc_to_ut = "xtimingdata$scc_to_utc.tab") [string]

The table name containing the polynomial coefficents for the interpolation routine. This table DOES NOT contain the original SCC and UTC data points.

(exposure = "NONE") [string]

The PLIO mask containing exposure information for the specified source image. If the null string is input, the name will be the same root as the source image file with a "_exp.pl" extension. If "NONE" is input, no exposure filtering is performed.

(expthresh = 0.) [real]

The percentage of total exposure required for a given source pixel to pass the exposure filter, (if an exposure mask is present). 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.

(tbl_i= "IT1") [string]

The barycenter corrected orbit file produced by the task calc_bary has four columns. This string is the name of the first column which is the integer part of the UNCORRECTED orbit time. Unless the column names for the calc_bary task have been changed, this string should be left alone.

(tbl_r= "RT1") [string]

This string is the name of the second column which is the real part of the UNCORRECTED orbit time. (see comment for (tbl_i1 = "IT1") for more info)

(tbl_i= "IT2") [string]

This string is the name of the third column which is the integer part of the CORRECTED orbit time. (see comment for (tbl_i1 = "IT1") for more info)

(tbl_r= "RT2") [string]

This string is the name of the fourth column which is the real part of the CORRECTED orbit time. (see comment for (tbl_i1 = "IT1") for more info)

(clobber = yes) [boolean]

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

(display = 1) [int]

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

(sort = no) [boolean]

Flag if events are to be sorted. If true, the type of sort is determined by the sorttype parameter.

(sorttype = "position") [string]

The type of sort to perform. This string consists of a list of event element names that specifies the order in which to sort the event record. For example, "y x time" will sort on the "y" element as the primary key, the "x" element as the secondary key, and "time" as the tertiary key. If sorting is not to be performed, this parameter can be used as a string that will go into the x_sort qpoe param to indicate the type of sorting of the events. For example, if the events are already sorted by time, and are not to be resorted, one can set sort to false and sorttype to "time", and the qpoe file will be indistinguishable from one whose events were sorted by time.

(sortsize = 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 large enough so that the task will do an in-core sort. (This requires knowing the approximate number of events and the byte size of each event.) 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.

(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 = 1024) [int]

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

(qp_bucketlen = 2048) [int]

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

(qp_blockfact = 1) [int]

The default 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 NOT be made for the qpoe file. This parameter is internal to qpoe and should not normally be changed.

(qp_key = "") [string]

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

1. Apply barycentric corrections to an individual, time-sorted qpoe file.

cl> xray
xr> xtiming
xt> timcor
ti> apply_bary "rp90a_sti.qp" "rp90_cor.tab" "medium" "rp90a_tcor.qp"

SCC->UTC conversion table is calibrated to SCC 110883482.0000

first qpoe gti time   = J.D. 2448062.97604379,  SCC 1606720.00000000
last qpoe gti time    = J.D. 2448062.98488638,  SCC 1607484.00000000
first corr table time = J.D. 2448062.97569444
last corr table time  = J.D. 2448063.04652778

Barycenter Corrections applied to event times in outdir$rp90a_tcor.qp
using correction table outdir$rp90_cor.tab 
with reference position at RA =  22:08:41.60, DEC =  45:44:47.30
Creating QPOE output file: rp90a_tcor.qp


NOTE: The output QPOE times are in seconds from noon of the MJD
of the start of the first OBI.

To convert the times to MJD use the following formula:

        MJDREFI + MJDREFF + (photon_time / 86400)

The values MJDREFI and MJDREFF can be found in the header of the
output QPOE file. (MJDREFF should be 0.5)

2. Apply barycentric corrections to a qpoe file merged from 3 individual qpoe files. Assume individual qpoe files seq01_sti.qp, seq02_sti.qp, and seq03_sti.qp, contained in a list file qpoes.lst. Also assume corresponding ephemeris files seq01_eph.tab, seq02_eph.tab, and seq03_eph.tab, contained in eph.lst.

First, merge the sti.qp files:

xd> qpappend @qpoes.lst "" merge.qp large
	.
	.
	.
xd>

Next, merge the corresponding ephemeris files, using the STSDAS table utility tmerge. Sort the resulting table in-place with tsort to ensure records in ascending time order.

ti> tmerge @eph.lst mergeph option=append
	.
	.
	.
ti> tsort mergeph columns="MJD_INT MJD_FRAC"
	.
	.
	.
ti>

Finally, compute barycentric corrections from merged ephemeris file and apply to merged qpoe file.

ti> calc_bary mergeph.tab merge
	.
	.
	.
ti> apply_bary merge.qp merge_cor.tab large merge_cor.qp
	.
	.
	.
ti>

TIME REQUIREMENTS

BUGS

There is a current problem using large regions with TIMSORTED QPOE files. This is an IRAF bug (it is being looked into). If you get a message such as "PLIO: reference out of bounds" or "PLIO: stack overflow", please it is necessary to use

	region = ""
The safest way to apply a region is to specify the region in timsort , and then to specify
	region = ""
in all subsequent timing tasks. This will produce a warning message about incompatible region specifiers, just to notify the user that full field was NOT available in the input file, but the full AVAILABLE field was returned to the user. This is not a problem.

SEE ALSO

Documentation on the calculate barycenter task (help calc_bary ) for more information on the barycenter routines

Documentation on region filtering (help regions ) for a description of the spatial filter user interface.

Documentation on qpoe filtering (help qpoe ) for a description of the qpoe filter user interface.


Source Code · Search Form · STSDAS