hrc_dtfstats

Synopsis

Calculate statistics from hrc_calc_dead_time and a GTI

Syntax

hrc_dtfstats infile outfile [gtifile] [maincol] [errcol] [chisqlim]
[clobber] [verbose]

Description

hrc_dtfstats computes the simple mean deadtime factor in an input hrc deadtime factor (dtf1) file and applies a chi-square test to the individual deadtime factors in the dtf1 to determine whether the deadtime is variable. The task can optionally use a file containing good time intervals (GTIs) to filter the dead time factor records on the GTI. If a GTI file is provided, dead time records which are not entirely included in GTIs are excluded from the statistics calculations.

This task is normally run as part of Level 1 and Level 2 processing, but users who make new event lists with different filtering criteria may wish to re-run it and use its output to update the DTCOR, LIVETIME, and EXPOSURE keywords in the new event list headers. In this case, the new HRC ONTIME is the sum of the good time intervals that pass the user-supplied filters, and the new LIVETIME is the product of the new ONTIME and the average deadtime factor from hrc_dtfstats.

Examples

Example 1

hrc_dtfstats infile="hrcf05925_000N001_dtf1.fits[DTF]"
outfile=all_dtfstats.fits maincol=DTF errcol=DTF_ERR chisqlim=5
gtifile=NONE
clobber=yes verbose=1

Compute DTF statistics from all records in the standard dtf1 file. Flag the deadtime factor as variable if the reduced chi-square about the mean is greater than 5.

Example 2

hrc_dtfstats infile="hrcf05925_000N001_dtf1.fits[DTF]"
outfile=my_dtfstats.fits maincol=DTF errcol=DTF_ERR chisqlim=5
gtifile="my_gtis.fits[FILTER]"
clobber=yes verbose=1

Compute DTF statistics from those records in the standard dtf1 file which are contained in the user-generated GTI file my_gtis.fits. Flag the deadtime factor as variable if the reduced chi-square about the mean is greater than 5.

Parameters

name	type	ftype	def	min	max	reqd	stacks	autoname
infile	file	input				yes	yes
outfile	file	output				yes		yes
gtifile	file		NONE
lookupTab	file	input
maincol	string		DTF
errcol	string		DTF_ERR
chisqlim	real		5
clobber	boolean		no
verbose	integer		0	0	5

Detailed Parameter Descriptions

Parameter=infile (file required filetype=input stacks=yes)

Input file(s)

Input file, or stack of files, containing dead time factors for an observation. The input file should be created by the hrc_calc_dead_time task. If the input FITS file has more than one extension, the appropriate FITS extension should be given, eg. xxx.fits[xxx].

If a stack of input files is used, the files are combined to create a single output file; see the "outfile" parameter for more information.

Parameter=outfile (file required filetype=output autoname=yes)

Output file

This is a FITS file that contains various statistics determined for the input Dead Time Factors file.

If a stack of input files is used, the files are combined into a single output file. All the records from all the DTF files in the stack (which pass the GTI filter in the "gtifiles" parameter) are used to compute average quantities for the output file.

If auto-naming is used (i.e. input to the outfile parameter ends with "."), the output file will have the suffix "_dtfstats".

Parameter=gtifile (file default=NONE)

File containing GTI to filter on

Input file containing a GTI subspace. The user would do best to specify the extension which the GTI applies to (usually EVENTS or FILTER), following the DM syntax, eg. xxx.fits[EVENTS] or xxx.fits[FILTER]. The GTI is applied to the dead time factors in the infile, filtering out any records that fall (in part or in full) in a bad time interval. If the user doesn't want filtering applied, they may set the value to none, NONE, or "".

Parameter=lookupTab (file filetype=input)

Lookup table for header merging

The look-up table defines the rules used to combine header keywords from multiple files, as described in "ahelp merging_rules". Set to "none" to stop the header files from being merged (so the output file will have a copy of the first input file).

Parameter=maincol (string default=DTF)

Name of the deadtime factor column

Name of the deadtime factor column in the input file. The name in the output of hrc_calc_dead_time is DTF.

Parameter=errcol (string default=DTF_ERR)

Name of the deadtime factor error column

Name of the deadtime factor error column in the input file. The name in the output of hrc_calc_dead_time is DTF_ERR.

Parameter=chisqlim (real default=5)

Limit for the variability test

Threshold value for the deadtime factor variability test. If the reduced chi square value is greater than this, then the dead time is determined to be variable.

Parameter=clobber (boolean default=no)

Clobber output file if it exists?

Parameter=verbose (integer default=0 min=0 max=5)

Debug level

Range is from 0 (nothing) to 5, which will describe in detail the processing that is occuring.

Bugs

There are no known bugs for this tool.