/ ciao4.17 / ahelp / tg_resolve_events.html

Jump to: Description · Examples · Parameters · Bugs · See Also

AHELP for CIAO 4.17

tg_resolve_events

Synopsis

Assign grating events to spectral orders; use detector energy resolution for order separation, if available.

Syntax

tg_resolve_events  infile outfile regionfile acaofffile [logfile]
[osipfile] [osort_lo] [osort_hi] [grating_obs] [detector]
[energy_lo_adj] [energy_hi_adj] [rand_seed] [rand_pix_size] [eventdef]
[stdlev1] [stdlev1_ACIS] [stdlev1_HRC] [cclev1a] [ccgrdlev1a] [geompar]
[verbose] [clobber]

Description

"tg_resolve_events" compares event positions with 3-D locations (including PHA) at which dispersed photons can appear, given the grating equation and zero order position, and assigns them a wavelength and an order. First, grating diffraction coordinates (diffraction angle, cross-diffraction angle, and order * wavelength) are computed for each event in spatial regions assigned by the input mask (regionfile parameter) by decomposing the event coordinates into components parallel and perpendicular to the diffraction direction, as defined by the instantaneous zero order centroid location, the event location, the grating node, and the mean grating dispersion direction. If the detector has intrinsic energy resolution, an energy response table is used to assign each photon an order (cf., the one dimensional grating equation: m*lambda = P*sin(theta), where m is the order, lambda the wavelength, P the grating period, and theta the diffraction angle).

Multiple Sources

The resolution is done for each source. Regions of overlap might be unambiguously resolved. If not, then bits in an output column, tg_smap, are set to indicate the ambiguity, though only one set of coordinates are assigned.

HETG/LETG/ACIS observations in CC-mode

Calibrated event energy corrections, which depend on CHIPY, are assumed in order to do order-sorting. In CC-mode, however, the CHIPY position is not known explicitly. Event processing with tg_resolve_events provides an estimate of CHIPY for dispersed photons using the grating arm, order, and wavelength in conjunction with the instrument geometry. To utilize this to improve order sorting --- especially for HETG/ACIS --- we can conduct a second pass through acis_process_events (which uses the CHIPY estimates to improve corrections), followed by a second pass through tg_resolve_events (which uses the updated ENERGY to repeat order-sorting). It is recommended that the first pass of tg_resolve_events use parameters "osipfile=none, osort_lo=0.3, osort_hi=0.3" (see parameter descriptions below), and then the second pass can use "osipfile=CALDB". The output columns for the first pass should also be specified by the "cclev1a" or "ccgrdlev1a" eventdef parameters, so that acis_process_events has the proper input data. (This feature was introduced in CIAO 4.8).

The output columns assigned by the standard event definition are:

Name	Unit	Type	Description
tg_r	deg	Real8	Grating angular coords, along dispersion
tg_d	deg	Real8	Grating angular coords, across dispersion
tg_m		Int2	Diffraction order
tg_lam	angstrom	Real8	wavelength
tg_mlam	angstrom	Real8	Order times wavelength (m * lambda)
tg_srcid		Int2	source ID, index from tgdetect table
tg_part		Int2	component index (zero-order, HEG, MEG, LEG, regions)
tg_smap		Int2	source map; flags for up to 10 sources

Tg_part is a numeric index: 0 for zero-order, 1 for HEG spatial region, 2 for MEG spatial region, 3 for LEG region, and 99 for background.

The source map, tg_smap, will have more that one bit set only if the event is ambiguous between multiple sources. Tg_m will also be set to 99 for unresolved photons.

The additional output columns added for CC-mode processing:

Name	Unit	Type	Description
chipy_tg		Real8	Estimate of CHIPY for dispersed photons
chipy_zo		Real8	projected zeroth order centroid (which may be negative)

Examples

Example 1

tg_resolve_events acisf001_evt1.fits acisf001_evt1a.fits
acisf001_evt1a.reg acaofffile="pcad*nnn_asol1.fits" align="none"
osipfile=acisD1999-09-16osipN0004.fits

Resolve grating events in the input event file, acisf001_evt1.fits, using the spatial region filter, acisf001_evt1a.reg, the aspect solution file pcad*_asol1.fits (quotes escape unix expansion on the command-line), and use the order-sorting/integrated-probability table (osip) appropriate to observation times on or after 16 September 1999. Since the aspect-solution is used directly (*_asol1.fits), no alignemt file (*_soff1.fits) should be specified. Write the output to acisf001_evt1a.fits.

Example 2

tg_resolve_events infile=hrcf0001_evt1.fits outfile=hrcf0001_evt1a.fits
regionfile=hrcf0001_evt1a.reg acaofffile=hrcf0001_asol1.fits

Resolve events in the event file, hrcf0001_evt1.fits using the spatial region hrcf0001_evt1a.reg defining the order locations. Apply the aspect using the offsets in files hrcf0001_asol1.fits (aspect solution). Write the output to hrcf0001_evt1a.fits overwriting any existing file with the same name.

Parameters

name	type	ftype	def	min	max	reqd
infile	file	input				yes
outfile	file	output				yes
regionfile	file					yes
acaofffile	file					yes
logfile	file		stdout
osipfile	file	ARD	CALDB
osort_lo	real		0.3	0.0	0.5
osort_hi	real		0.3	0.0	0.5
grating_obs	string		header_value
detector	string		header_value
energy_lo_adj	real		1.0	0	10
energy_hi_adj	real		1.0	0	10
rand_seed	integer		1	0	32767
rand_pix_size	real		0.0	0.0
eventdef	string		)stdlev1_ACIS
stdlev1	string		)eventdef
stdlev1_ACIS	string
stdlev1_HRC	string
cclev1a	string
ccgrdlev1a	string
geompar	file		geom
verbose	integer		0	0	5
clobber	boolean		no

Detailed Parameter Descriptions

Parameter=infile (file required filetype=input)

Input event file ("Level 1"), which must have an extension called EVENTS. The extension must have columns called:

Name	Unit	Type	Description
time	s	Real8	Spacecraft terrestrial event time
ccd_id		Int2	CCD reporting event (if ACIS)
chip_id		Int2	Chip reporting event (if HRC)
chipx	pixel	Int2	Chip coords
chipy	pixel	Int2	Chip coords
x	pixel	Real8	sky coordinates
y	pixel	Real8	sky coordinates
energy	eV	Real4	nominal energy of event (if ACIS)

Parameter=outfile (file required filetype=output)

Name of file to write. Columns are specified by the eventdef paramter.

The input region file is appended to the output as a FITS extension.

Parameter=regionfile (file required)

Grating region, in sky coordinates. The region file defines the zero-order position and size, and the dispersed region sizes and orientations, in sky coordinates. The region is used to filter events for assignment of diffraction coordinates, and events are labeled by the region part they lie in. This region file is usually created with tg_create_mask.

The input region is copied to the output as a FITS extension.

Parameter=acaofffile (file required)

Aspect Camera Assembly (ACA) offsets file, or Pointing Control and Aspect Determination (PCAD) aspect solution (asol) file. Either may be used. The former is derived from the latter via asp_calc_offsets. The aspect offsets file's columns specify the offset of the optical axis in sky pixels from the nominal right ascension and declination. The aspect solution file's columns contain both the optical axis location on the sky and the science instrument module (SIM) location relative to the optical axis.

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=logfile (file default=stdout)

File or "stdout" for diagnostic text output.

This value specifies the name of the ascii text file which this tool will generate if the verbose parameter is set to a value other than 0. If the value is set to "stdout", the output will be redirected to standard output.

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

File used for ACIS order-sorting. This parameter is formerly called rmfile. (Only requried if the input is ACIS data.)

The calibration file which contains information derived from the CCD resolution and is used for determining diffraction orders. The file contains limits versus energy, which are typically +-3*sigma about the main peak of the CCD redistribution function. The file maps the redistribution peak and resolution with position on each CCD; "OSIP" stands for Order Sorting and Integrated Probability. The integrated probability contained within the energy limits is not used here, but is used in computing the time-averaged effective area (see "ahelp mkgarf" and "ahelp fullgarf").

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

NOTE: this file is NOT the same as a CCD response matrix (RMF).

Parameter=osort_lo (real default=0.3 min=0.0 max=0.5)

Order-sorting lower bound fraction; order > (int(order) - osort_lo). (osort_lo and osort_hi will be used for order-sorting only if the input data is ACIS and the input to the osipfile parameter is "NONE".)

This specifies fractional deviations from the integer order which will be included in order-sorting via CCD ENERGY values (PHA). eg. osort_lo=0.3, osort_hi=0.2 means that photons with real-valued orders between 0.7 < order <= 1.2 will be included in first order, 1.7 < order <= 2.2 will be second order, etc. (The real valued order is defined as the grating order*wavelength (tg_mlam) divided by the "CCD wavelength", (h*c)/ENERGY. )

This parameter and the next were introduced to bypass the OSIP file in cases when it is not appropriate or well calibrated (e.g., CC-mode, or in times when CCD temperature was changing).

Parameter=osort_hi (real default=0.3 min=0.0 max=0.5)

Order-sorting upper bound fraction; order <= (int(order) + osort_hi). (osort_lo and osort_hi will be used for order-sorting only if the input data is ACIS and the input to the osipfile parameter is "NONE".)

Specifies fractional deviations from the integer order which will be included in order-sorting via CCD ENERGY values (PHA). eg. osort_lo-0.3, osort_hi=0.2 means that photons with real-valued orders between 0.7 < order <= 1.2 will be included in first order, 1.7 < order <= 2.2 will be second order, etc.

Parameter=grating_obs (string default=header_value)

Grating in use: (HETG, HEG, MEG, LETG, header_value)

This parameter specifies the grating type so that the appropriate calibration data (such as grating period) can be read in from the calibration database. If "header_value" is specified, then use the GRATING keyword in the event header. If grating_obs is specified, it is compared with the header's value and a warning is printed if the two do not match.

Parameter=detector (string default=header_value)

Detector: (ACIS, HRC-S, HRC-I, header_value)

The detector on which this data was collected. This parameter specifies the instrument calibration data to be read. If header_value is specified, then use the DETNAM keyword in the event header. If an explicit detector name is specified, it is compared with the header's value and a warning is printed if they do not match. (Detector names must be all upper case.)

Parameter=energy_lo_adj (real default=1.0 min=0 max=10)

(NOTE: this has been superseded by osip=NONE and osort_lo, osort_hi parameters.) This should be left at 1.0, except possibly for extended sources. It is a multiplicative factor applied to the low energy limit in the spatial independent version of order-sorting table (the "irm" version). Altering this factor will alter the effective area fraction in an undetermined way. It is primarily here for back-compatibility with deprecated software versions.

Note: this parameter is ignored if the order-sorting file (input to the osipfile parameter) is the spatially dependent "osip" version.

Parameter=energy_hi_adj (real default=1.0 min=0 max=10)

(NOTE: this has been superseded by osip=NONE and osort_lo, osort_hi parameters.) This should be left at 1.0, except possibly for extended sources. It is a multiplicative factor applied to the high energy limit in the spatial independent version of order-sorting table (the "irm" version). Altering this factor will alter the effective area fraction in an undetermined way. It is primarily here for back-compatibility with deprecated software versions.

Note: this parameter is ignored if the order-sorting file (input to the osipfile parameter) is the spatially dependent "osip" version.

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

Randomization seed. If 0, then use a seed derived from the system time.

This value determines whether the seed value used for the pseudo-random number generator used in randomizing coordinate values. Setting this value to a non-zero value will allow the tool to generate the same random number sequence and thus identical results on different runs on the same system.

Parameter=rand_pix_size (real default=0.0 min=0.0)

Pixel randomization half-width. The value can be either 0.0 or 0.5. A value of 0.0 means that no explicit coordinate randomization will be done.

Randomization may be applied to the chip pixel coordinates (CHIPX, CHIPY) before diffraction coordinates are derived. This is an anti-aliasing technique which removes moire-pattern affects due to transformation of one binned grid to another, or for removing systematic affects related to the aspect. It is usually a good idea to randomize, and it can be done without substantially degrading the resolution. It should be understood that even if rand_pix_size=0, there is an implicit randomization imposed by the dither and assumption that the photon position is at the pixel center. The implicit and unavoidable randomization is that of a boxcar convolution. Rand_pix_size other than zero is effectively an additional convolution by a triangular function.

Parameter=eventdef (string default=)stdlev1_ACIS)

Specify contents of the output file.

This field allows the user to specify the contents of the output file. The value may either be set to a desired list of columns and data types by the user, or a redirect to predefined event definitions. The default value of this parameter is a redirect to the output column specifications listed in the stdlev1_ACIS parameter.

The default value is:

eventdef = )stdlev1_ACIS

Other parameters defined, to which the parameter may be directed, are:

stdlev1_ACIS =
{d:time,i:expno,f:rd,s:chip,s:tdet,f:det,f:sky,s:ccd_id,l:pha,s:pi,f:ene
rgy,s:grade,s:fltgrade,s:node_id,s:tg_m,f:tg_lam,f:tg_mlam,s:tg_srcid,s:
tg_part,s:tg_smap,x:status}
stdlev1_HRC =
{d:time,s:crsu,s:crsv,s:amp_sf,l:raw,f:samp,s:av1,s:av2,s:av3,s:au1,s:au
2,s:au3,s:sumamps,f:rd,s:chip,l:tdet,f:det,f:sky,s:chip_id,s:pha,s:pi,s:
tg_m,f:tg_lam,f:tg_mlam,s:tg_srcid,s:tg_part,s:tg_smap,x:status}
cclev1a =
{d:time,d:time_ro,l:expno,s:ccd_id,s:node_id,s:chip,f:chipy_tg,f:chipy_z
o,s:tdet,f:det,f:sky,f:sky_1d,s:phas,l:pha,l:pha_ro,f:energy,l:pi,s:fltg
rade,s:grade,f:rd,s:tg_m,f:tg_lam,f:tg_mlam,s:tg_srcid,s:tg_part,s:tg_sm
ap,x:status}
ccgrdlev1a =
{d:time,d:time_ro,l:expno,s:ccd_id,s:node_id,s:chip,f:chipy_tg,f:chipy_z
o,s:tdet,f:det,f:sky,f:sky_1d,l:pha,l:pha_ro,s:corn_pha,f:energy,l:pi,s:
fltgrade,s:grade,f:rd,s:tg_m,f:tg_lam,f:tg_mlam,s:tg_srcid,s:tg_part,s:t
g_smap,x:status}

Parameter=stdlev1 (string default=)eventdef)

Definition of the standard columns in an HRC or ACIS event file.

Parameter=stdlev1_ACIS (string)

Definition of the standard columns in an ACIS event file.

Parameter=stdlev1_HRC (string)

Definition of the standard columns in an HRC event file.

Parameter=cclev1a (string)

Definition of the columns for CC_FAINT mode, as required for the second pass of acis_process_events

Parameter=ccgrdlev1a (string)

Definition of the columns for CC_GRADED mode, as required for the second pass of acis_process_events

Parameter=geompar (file default=geom)

The name of the Pixlib Geometry parameter file.

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

Verbosity level: 0 - no output, 5 - maximum display.

This option allows the user to request a varying level of diagnostic output. Levels range from 0 to 5 with 0 representing no information and 5 representing the most. The log is written the value specified in the logfile parameter.

Parameter=clobber (boolean default=no)

If "yes", then an existing output file will be over-written. If "no", and the named outfile exists, exit with an error.

Bugs

Caveats

WARNING: Event chip position is outside of valid range. Grating coordinates not computed for this event.

# tg_resolve_events (CIAO): The following error occurred 38950 times:
  WARNING: Event chip position is outside of valid range. 
  Grating coordinates not computed for this event.

The warning indicates that some of the events chip coordinates are outside of the valid range, so tg_resolve_events cannot compute grating coordinates for them. It may be ignored, as long as the number of events outside the valid range 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 5866359  rows
Block    3: GTI                            Table         2 cols x 18       rows

(38950 / 5866359) * 100 = 0.663955

Since there are 5866359 events in the file, the 38950 for which grating coordinates were not computed make up just 0.66% of the total events.

dsTREUNKNOWNINCOLERR -- WARNING: Not loading data from unrecognized level 1.5 input column.

# tg_resolve_events (CIAO): The following error occurred 10000 times:
  dsTREUNKNOWNINCOLERR -- WARNING: Not loading data from unrecognized level 1.5 input column.

The tool encountered a column in the input file that it does not recognize, and it is ignoring it when reading the file. Users who have applied the ACIS time-dependent gain correction will see this warning because of the PHA_RO column that is created in the reprocessed level=1 event file. This column is not used by any tools after acis_process_events, so the warning may be safely ignored.