About Chandra Archive Proposer Instruments & Calibration Newsletters Data Analysis HelpDesk Calibration Database NASA Archives & Centers Chandra Science Links

Skip the navigation links
Last modified: December 2006

URL: http://cxc.harvard.edu/ciao3.4/tg_resolve_events.html
Hardcopy (PDF): A4 | Letter
AHELP for CIAO 3.4 tg_resolve_events Context: tools

Synopsis

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

Syntax

tg_resolve_events infile outfile regionfile acaofffile [alignmentfile]
[logfile] [osipfile] [osort_lo] [osort_hi] [grating_obs] [detector]
[energy_lo_adj] [energy_hi_adj] [time_offset] [rand_seed]
[rand_pix_size] [eventdef] [stdlev1] [stdlev1_ACIS] [stdlev1_HRC]
[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.

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.

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_aoff1.fits
alignmentfile=hrcf0001_soff1.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_aoff1.fits (aspect offsets) and hrcf0001_soff1.fits (science instrument module offsets). 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
alignmentfile file   )acaofffile      
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  
time_offset real   0      
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          
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. A region may be 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 an offsets file is given, an alignment file (SIM offsets) must also be specified. If the aspect solution file (pcad or asol) is given, then the alignmentfile parameter can be redirected to use the acaofffile input.

Aspect solution files are preferred, since they have higher time resolution and remove a need for offsets files.

If more than one input file is used, then the files should be in chronological order.

Note: this parameter name is now an anachronism, since the preferred file type is the aspect solution (``*asol1.fits''). If the input is an asol file, then the alignment file parameter should be redirected to acaofffile, since the asol file contains all information necessary.

Parameter=alignmentfile (file default=)acaofffile)

Science Instrument Module (SIM) offsets file (typically tagged with ``soff1.fits''), which contains a compressed form of the part of the aspect solution giving the position and rotation of the camera relative to the optical axis. This parameter can be redirected to use the acaofffile input (like the current default) if the aspect solution is used.

If more than one input file is used, then the files should be in chronological order.

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 (see below) 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 ``mkgarf'' and ``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 superceded 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 superceded 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=time_offset (real default=0)

Offset to add to event time to synchronize with alignment data.

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,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}

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=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 (see above).

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.

CHANGES IN CIAO 3.3

Aspect solution files

The tool checks that the aspect solution file(s) are time-ordered. An error is printed if the files are not in chronological order.

Parameter File

The kernel parameter has been removed.

CHANGES IN CIAO 3.1

Default value of rand_pix_size parameter

In CIAO 3.1, the default value of the rand_pix_size parameter was changed from 0.5 to 0.0. This means that, by default, randomization IS NOT applied to the chip pixel coordinates before diffraction coordinates are derived.

Bugs

See the bugs page for this tool on the CIAO website for an up-to-date listing of known bugs.

Hardcopy (PDF): A4 | Letter
Last modified: December 2006



The Chandra X-Ray Center (CXC) is operated for NASA by the Smithsonian Astrophysical Observatory.
60 Garden Street, Cambridge, MA 02138 USA.    Email: cxcweb@head.cfa.harvard.edu
Smithsonian Institution, Copyright © 1998-2004. All rights reserved.