hrc_process_events

Synopsis

Correct HRC event positions, times, PHA, etc.

hrc_process_events  infile outfile badpixfile acaofffile [obsfile]
[geompar] [do_ratio] [do_amp_sf_cor] [gainfile] [ADCfile] [degapfile]
[hypfile] [ampsfcorfile] [tapfile] [ampsatfile] [evtflatfile] [badfile]
[logfile] [eventdef] [badeventdef] [grid_ratio] [pha_ratio]
[wire_charge] [cfu1] [cfu2] [cfv1] [cfv2] [amp_gain] [rand_seed]
[rand_pix_size] [start] [stop] [stdlev1] [badlev1] [hsilev1] [simlev1]
[fltlev1] [clobber] [verbose]

Description

`hrc_process_events' computes detector coordinates for input HRC events. The detector position is determined by applying fine position corrections and degapping corrections to the coarse position specified in the input data (see the "SEE ALSO" section below for the actual algorithm). Raw coordinates, chip coordinates, and sum amplitude of each event are generated as by-products of the detector coordinate calculation and may be output if desired. The tool also applies aspect offset and sim alignment corrections as well as flags status bits of bad pixels when supplied with the appropriate files.

Stacks: The user may specify a single file or a list of files as input to this routine. Hrc_process_events will attempt to process all input files provided to it. If an error is detected in an input file (ie. a data dependency is not met), that file will be discarded and a message will be generated to stderr. When the debug level is greater than two, counts of the number of bad files and events will be maintained and written to the debug log file.

Dependencies: If all of the required dependencies are not met, the input file will be discarded and a message will be output to stderr. The routine will iterate to the next input file if a stack is provided as input.

General

• It is the user's responsibility to ensure that all of the parameters are correctly set. The function will not perform validity checks on the input parameter data other than verifying the existence of the axes in the eventdef list. Special care should be taken to ensure that columns are specified in the eventdef list if they are desired as output. If a column that is not computed is specified in the eventdef list, the data fields for that column in the output file will contain zero. For instance, if the stop parameter is set to 'none' and the eventdef contains sky coords, they will have a value of 0.
• It does not matter what fields the input event file contains provided that all data dependencies for the selected options are met.
• In order to perform coordinate tansformations, the following fields must exist in the input data: coarse u position, coarse v position, and the six amp values (three for the u axis, and three for the v axis). If the start parameter is set to chip, then chipx, chipy is necessary in lieu of the above mentioned columns.
• The routine will generate as output, an event file containing columns that are listed in the eventdef parameter. One row will be written for each input row (event) successfully processed. Events that are unsuccessfully processed will be placed in the bad event file and a warning message will be output. If the debug level is set to three or higher a count of the number of events that have been discarded will be written to the debug logfile.

Pulse Invarience/Gain Correction: Gain correction will only be applied when an input gain file is provided. The results of this calculation will only be propogated to the output file if the eventdef parameter contains the string "s:pi" as an entry.

Tap-ringing Correction: This correction compensates for distortions in event positions due to ringing in on-board electronics. It will be applied if the parameter "do_amp_sf_cor" is set to "yes" and calibration files containing coefficients for the amp_sf and tapringing corrections are applied. These are specified by parameters "ampsfcorfile" and "tapfile", and default to files in CALDB. In addition, HRC operating parameters RANGELEV and WIDTHRES are required. These are provided in the observation parameter file in standard processing. Alternatively, users may add them as keywords in the event list header (see Example 3, below).

Correct values of RANGELEV are given in the following table.

For WIDTHRES, the value is 3 prior to 10/5/2000 and 2 after that date, for both HRC-I and HRC-S.

For more information on HRC data products please refer to the Data Products Guide.

Examples

Example 1

hrc_process_events xh101950595_evt0.fits xh101950595_evt1.fits
degapfile=hrci_degap.fits clobber=no

Runs `hrc_process_events' to generate coordinate information using a degap file and no aspect or alignment corrections. Do not identify bad/hot pixels and do not overwrite the output file if a file named xh101950595_evt1.fits already exists.

Example 2

hrc_process_events xh103254768_evt0.fits xh103254768_evt1.fits
hrci_badpix.fits NONE NONE gainfile=hrci_gain.fits logfile=debug.txt
verbose=3 eventdef="{d:time,s:chipy,d:sky,s:pi}"

Runs `hrc_process_events' to generate an output file containing time, chip, sky, and pi columns. Create a log file named debug.txt with moderate detail. Use the hrci_badpix.fits badpixel file and the hrci_gain.fits gain correction file. Do not apply aspect or alignment corrections.

Example 3

dmhedit hrcf00998_000N002_evt1.fits filelist=none operation=add
key=RANGELEV value=125
dmhedit hrcf00998_000N002_evt1.fits filelist=none operation=add
key=WIDTHRES value=2
hrc_process_events hrcf00998_000N002_evt1.fits new_evt1.fits
hrcf00998_000N002_bpix1.fits.gz hrcf00998_000N002_aoff1.fits.gz
do_amp_sf_cor=yes

Runs `hrc_process_events' to generate a new level 1 event list with amp_sf and tap-ringing corrections applied. Since this is an HRC-S observation taken on 12/20/2000, RANGELEV=125 and WIDTHRES=2. These values are added to the input header using `dmhedit' prior to running hrc_process_events.

Parameters

Detailed Parameter Descriptions

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

Stack of input event files [FITS format]

The input can be a single or a stack of event file(s) from any level (L0, L1, L1.5, L2). If the input is a stack, the files listed should be in an ascending time order. For one or multiple input files, there should be only one single output file.

Parameter=outfile (file required filetype=output)

Output FITS event file

There's only one single output file from this tool.

Parameter=badpixfile (file required filetype=input default=NONE stacks=yes)

A single or a stack of existing bad pixel files

This is an auto parameter which is used to provide the tool with a list of hot/bad pixels. Events which fall on a hot/bad pixel will have a status bit set to indicate such.

Parameter=acaofffile (file required filetype=input default=NONE)

Existing aspect offsets. FITS file or NONE

Aspect solution file used to compensate for spacecraft movements during an observation. If more than one input file is used, then the files should be in chronological order. If the files are not in order, the tool will exit with an error.

Parameter=obsfile (file filetype=input default=NONE)

Existing observation parameter *.PAR file (uncompressed) or NONE.

This value specifies the name of the observation parameter file to seed the output event file header with. If the value is not "NONE", the keywords from the specified file are copied to the output file's header.

Parameter=geompar (string default=geom)

The name of the Pixlib Geometry parameter file.

Parameter=do_ratio (boolean default=yes)

yes/no

Option to either execute or omit the performance of ratio validity checks (sum of amps to pha ratio and grid charge ratio) on the processed events.

Parameter=do_amp_sf_cor (boolean default=yes)

yes/no

Option to perform amp_sf correction or not. By default this correction is turned on. In order to use it, a keyword RANGELEV needs to be present in the evt1 event header. If it's not, the program reports an error.

Parameter=gainfile (file filetype=ARD default=CALDB)

CALDB, NONE, or file name.

Filename of the gain image to use in computing the energy of an event from the PHA of an event. Users can specify "CALDB" to automatically look up the file appropriate for the observation date; the header keyword "GAINFILE" will contain the name of the file actually used.

Parameter=ADCfile (file filetype=input default=NONE)

Existing ADC correction. FITS file or NONE

This file contains the gain correction factors to apply to the amp values. If a file is provided, the correction is performed.

Parameter=degapfile (file filetype=ARD default=CALDB)

CALDB, COEFF, NONE, or file name

This parameter specifies how to apply degapping corrections. If set to NONE then values of 1 are used for the linear degap values and 0's are used for quadratic correction factors. If COEFF is specified then the values cfu1 and cfv1 are used for linear and cfu2 and cfv2 are used for quadratic correction factors. Alternatively a degap. FITS file may be provided, but it is the users responsibility to make sure that the file contains the appropriate entries for hrc-i or hrc-s data.

Users can specify "CALDB" to automatically look up the file appropriate for the observation date; the header keyword "DEGAPFILE" will contain the name of the file actually used.

Parameter=hypfile (file filetype=ARD default=CALDB)

CALDB, NONE, or file name

This file contains the coefficients for the hyperbolic test. If set to NONE then no hyperbolic test is applied.

Users can specify "CALDB" to automatically look up the file appropriate for the observation date; the header keyword "HYPFILE" will contain the name of the file actually used.

Parameter=ampsfcorfile (file filetype=ARD default=CALDB)

CALDB, NONE, or filename

A file of coefficients needed to apply a correction to the AMP_SF column in the event structure. AMP_SF is used in deciding which events to correct for the tap ringing problem.

Parameter=tapfile (file filetype=ARD default=CALDB)

CALDB, NONE, or file name

This file contains the coefficients for the tap ring correction. If set to NONE then no correction is applied.

Users can specify "CALDB" to automatically look up the file appropriate for the observation date; the header keyword "TAPFILE" will contain the name of the file actually used.

Parameter=ampsatfile (file filetype=ARD default=CALDB)

CALDB, NONE, or file name

This file contains the coefficients for the saturation test. If set to NONE then no saturation test is applied.

Users can specify "CALDB" to automatically look up the file appropriate for the observation date; the header keyword "AMPSATFILE" will contain the name of the file actually used.

Parameter=evtflatfile (file filetype=ARD default=CALDB)

CALDB, NONE, or file name

This file contains the coefficients for the flatness test. If set to NONE then no flatness testing is performed.

Users can specify "CALDB" to automatically look up the file appropriate for the observation date; the header keyword "EVTFLATFILE" will contain the name of the file actually used.

Parameter=badfile (file filetype=output)

Output bad event file [FITS format]

File name to use when generating a bad event file. Events which can not be correctly processed (ie. invalid tap positions) are output into this file.

Parameter=logfile (file filetype=output default=stdout)

Nonexistent file or 'stdout'

This hidden parameter allows the user to generate a debugging log file if the verbose parameter (see below) is set to a non zero value.

Parameter=eventdef (string)

String of form: {type:colname,type:colname} )

This hidden parameter allows the user to specify the columns that will exist in the output event file. The default valus of this parameter is a redirection to the standard level 1 hrc eventdef specified by the stdlev1 parameter.

Parameter=badeventdef (string)

String of form: {type:colname, type:colname} )

This hidden parameter allows the user to specify the columns that will exist in the output bad event file.

Parameter=grid_ratio (real default=0.5 min=0.0 max=1.0)

double precision real

charge ratio

Parameter=pha_ratio (real default=0.5 min=0.0 max=1.0)

double precision real

pha ratio

Parameter=wire_charge (integer default=0)

(-1, 0)

option to enable or disable the center wire test (-1 = off)

Parameter=cfu1 (real default=1.0)

double precision real

first order correction factor for u axis

Parameter=cfu2 (real default=0.0)

double precision real

second order correction factor for u axis

Parameter=cfv1 (real default=1.0)

double precision real

first order correction factor for v axis

Parameter=cfv2 (real default=0.0)

double precision real

second order correction factor for v axis

Parameter=amp_gain (real default=75.0)

real number

amp gain

Parameter=rand_seed (integer default=1 min=0 max=32767)

0, positive integer

This value determines the seed value for the pseudo-random generator used in integer rounding (if rand_pix_size is not 0.0). A value of 0 indicates use of clock time as the seed.

Parameter=rand_pix_size (real default=0.0)

This parameter specifies the range of the randomization values applied to the coordinate computations. The value can be either 0.0 or 0.5. If it is set to 0.0 (the default), randomization will not be performed.

Parameter=start (string default=coarse)

coarse, chip, tdet

The start of the coordinate transformations. This should be set to coarse. Chip is supported for MARX data.

Parameter=stop (string default=sky)

none, chip, tdet, det, sky

The end of the coordinate transformations. This determines the extent of the coordinate transformations that are executed by hrc_process_events. It should generally be set to sky. If a value of none is specified, coordinate transformations are not executed.

Parameter=stdlev1 (string)

This string specifies one of the pre-defined sets of column names and data types that can be used to control the information written to the output file. eventdef=")stdlev1" is equivalent to eventdef="{d:time,s:crsv,s:crsu,s:amp_sf,s:av1,s:av2,s:av3, s:au1,s:au2,s:au3,l:raw,s:chip,l:tdet,f:det,f:sky,s:pha,s:pi, s:sumamps,s:chip_id,x:status}".

Parameter=badlev1 (string)

This string specifies one of the pre-defined sets of column names and data types that can be used to control the information written to the output file. eventdef=")badlev1" is equivalent to eventdef="{d:time,s:crsu,s:crsv,s:au1,s:au2,s:au3, s:av1,s:av2,s:av3,s:pha}".

Parameter=hsilev1 (string)

This string specifies one of the pre-defined sets of column names and data types that can be used to control the information written to the output file. eventdef=")hsilev1" is equivalent to eventdef="{d:time,s:crsu,s:crsv,s:au1,s:au2,s:au3,s:av1, s:av2,s:av3,s:chipx,s:chipy,s:tdetx,s:tdety,s:x,s:y,l:fpz, s:pha,s:vstat,s:estat}".

Parameter=simlev1 (string)

This string specifies one of the pre-defined sets of column names and data types that can be used to control the information written to the output file. eventdef=")simlev1" is equivalent to eventdef="{l:tick,i:scifr,i:mjf,s:mnf,s:evtctr,s:crsu, s:crsv,s:au1,s:au2,s:au3,s:av1,s:av2,s:av3,s:tdetx,s:tdety, s:pha,s:vstat,s:estat}".

Parameter=fltlev1 (string)

This string specifies one of the pre-defined sets of column names and data types that can be used to control the information written to the output file. eventdef=")fltlev1" is equivalent to eventdef="{d:time,s:crsv,s:crsu,s:amp_sf,s:av1,s:av2,s:av3, s:au1,s:au2,s:au3,s:chipx,s:chipy,l:tdetx,l:tdety,s:detx, s:dety,s:x,s:y,s:pha,s:sumamps,s:chip_id,l:status}".

Parameter=clobber (boolean default=no)

Overwrite output event file if it already exists?

A value of yes indicates that the tool will overwrite an existing output file if the file already exists. A value of no causes the tool to exit with an error message if the file already exists.

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

Verbose level

Option to enable or disable the logging of debugging information to a datafile or standard output (specified by the logfile parameter). A value of zero disables the logging and nonzero numbers indicate the degree of detail to log with five being the most detailed and one the least.

Bugs

Caveats

# hrc_process_events (CIAO): The following error occurred 2482 times:
  dsHPEEVENTSEQERR -- WARNING: Out of sequence events discovered in hrc_evt1.fits.

There are occasional events that appear in the telemetry stream with time tags that make them seem to have occurred out-of-sequence. One special case where this occurs has been documented (see the Out-of-sequence HRC Time Tags memo); other occurrences are most likely to be caused by hiccups in the HRC or by double-bit errors in telemetry (single-bit errors are corrected).

This warning may be ignored in most cases, as long as the number of events flagged as out-of-sequence is a small fraction of the total number of events in the file. For example:

unix% dmlist hrc_evt1.fits blocks
 
--------------------------------------------------------------------------------
Dataset: hrc_evt1.fits blocks
--------------------------------------------------------------------------------
 
     Block Name                          Type         Dimensions
--------------------------------------------------------------------------------
Block    1: PRIMARY                        Null        
Block    2: EVENTS                         Table        20 cols x 798768   rows
Block    3: GTI                            Table         2 cols x 7        rows

(2482.0 / 798768.0) * 100 = 0.310729

Since there are 798768 events in the file, the 2482 that were flagged as out-of-sequence make up just 0.31% of the total events.

# hrc_process_events (CIAO): The following error occurred 224 times:
  WARNING: can't find a proper degap value for this raw coord. in hrc_evt1.fits.

The warning means that the new degap lookup table does not have a matched value for the given raw coordinate which most likely is out of the boundary. Events with such warning will be indicated as bad in the output status column.

This warning may be ignored in most cases, as long as the number of events flagged as out-of-sequence is a small fraction of the total number of events in the file. For example:

unix% dmlist hrc_evt1.fits blocks
 
--------------------------------------------------------------------------------
Dataset: hrc_evt1.fits blocks
--------------------------------------------------------------------------------
 
     Block Name                          Type         Dimensions
--------------------------------------------------------------------------------
Block    1: PRIMARY                        Null        
Block    2: EVENTS                         Table        20 cols x 798768   rows
Block    3: GTI                            Table         2 cols x 7        rows

(224.0 / 798768.0) * 100 = 0.0280432

Since there are 798768 events in the file, the 224 that were flagged as out-of-sequence make up just 0.03% of the total events.

See Also

chandra

eventdef

tools::hrc

hrc_build_badpix, hrc_dtfstats