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/acis_process_events.html
Hardcopy (PDF): A4 | Letter
AHELP for CIAO 3.4 acis_process_events Context: tools

Synopsis

Produce or update TIME, coordinates, PI, GRADE, and STATUS information in ACIS event files

Syntax

acis_process_events infile outfile acaofffile [apply_cti] [apply_tgain]
[alignmentfile] [obsfile] [geompar] [logfile] [gradefile] [gainfile]
[badpixfile] [threshfile] [ctifile] [tgainfile] [eventdef] [doevtgrade]
[check_vf_pha] [calc_cc_times] [trail] [spthresh] [time_offset]
[docentroid] [calculate_pi] [pi_bin_width] [pi_num_bins] [max_cti_iter]
[cti_converge] [tstart] [tstop] [clobber] [verbose] [stop] [instrume]
[rand_seed] [rand_pha] [rand_pix_size] [stdlev1] [grdlev1] [cclev1]
[ccgrdlev1]

Description

`acis_process_events' is part of the standard ACIS Level 1 processing pipeline. The tool can be employed by users to update an existing ACIS event data file by recomputing (1) the coordinates TDETX, TDETY, DETX, DETY, X, and Y (and SKY_1D for continuous-clocking mode data), (2) the pulse-height amplitude columns PHAS_ADJ (if the CTI adjustment is used), PHA (except for graded-mode data), PHA_RO (if the time-dependent gain adjustment is used), ENERGY and PI, (3) the FLTGRADE (except for graded-mode data) and GRADE, and (4) some of the bits in the column STATUS. The tool may also be used to apply or remove a CTI adjustment, apply or remove a time-dependent gain adjustment, identify potential background events for TIMED VFAINT mode data, disable the pixel randomization used to compute the coordinates DETX, DETY, X, and Y, disable the randomization used to compute the ENERGY and PI and change the number and data type of the columns that are propagated from the input event data file to the output file. `acis_process_events' has many parameters, most of which may be ignored by users. Those who wish to explore the full functionality of the tool should be cautious because it is possible to produce results that are not meaningful or compatible with the calibration products.

Example 1

acis_process_events acisf00732_000N002_evt1.fits
acisf00732_999N002_evt1.fits apply_cti=yes apply_tgain=yes
ctifile=CALDB tgainfile=CALDB doevtgrade=yes calculate_pi=yes stop=none

In this example, the values of PHA, FLTGRADE, and GRADE are recomputed after performing a CTI adjustment to the values of PHAS to obtain PHAS_ADJ (apply_cti=yes ctifile=CALDB doevtgrade=yes). Since the adjustment is computed using the unadjusted values of PHAS, it is not possible to apply the CTI adjustment more than once. If the input event-data file was CTI adjusted, then the adjusted values are discarded and recomputed. The column PHAS_ADJ is not written to the output file by default, but can be if it is included in the parameter eventdef. The values of ENERGY and PI are recomputed after performing a time-dependent gain adjustment to the values of PHA (apply_tgain=yes tgainfile=CALDB doevtgrade=yes calculate_pi=yes). The original, unadjusted values of PHA are written to the column PHA_RO. The names of the CALDB CTI and time-dependent gain files used are written to the keywords CTIFILE and TGAINFIL, respectively. The recomputation of the coordinates is disabled (stop=none).

It is possible to remove the CTI and time-dependent gain adjustments from PHA, FLTGRADE, GRADE, ENERGY and PI by using the same command shown above, except that apply_cti=no and apply_tgain=no.

Example 2

acis_process_events acisf00732_000N002_evt1.fits
acisf00732_998N002_evt1.fits gainfile=CALDB doevtgrade=no stop=none

In this example, the values of ENERGY and PI are recomputed using the most recent gain file in the calibration database (gainfile=CALDB). The CTI adjustment is neither recomputed nor removed (doevtgrade=no). The name of the CALDB gain file used is written to the keyword GAINFILE. The recomputation of the FLTGRADE, GRADE and coordinates is disabled (doevtgrade=no stop=none).

Example 3

acis_process_events acisf00732_000N002_evt1.fits
acisf00732_997N002_evt1.fits acaofffile=pcadf079650047N002_asol1.fits
geompar=geom doevtgrade=no calculate_pi=no rand_pix_size=0.0

In this example, the coordinates DETX, DETY, X, and Y are recomputed using the latest CALDB geometry files (geompar=geom) and the specified aspect solution file (acaofffile=custom_asol1.fits). The pixel randomization is disabled (rand_pix_size=0.0, the default is rand_pix_size=0.5). The recomputation of the CTI adjustments and FLTGRADE, GRADE, ENERGY and PI values is disabled (doevtgrade=no calculate_pi=no).

If rand_pix_size=0.0 is excluded from the command, then the default pixel randomization (a uniform random deviate between -0.5 and +0.5 pixel) is applied.

Example 4

acis_process_events acisf00016_000N002_evt1.fits
acisf00016_999N002_evt1.fits doevtgrade=no check_vf_pha=yes
calculate_pi=no stop=none

In this example, a STATUS bit is set to one for potential background events (check_vf_pha=yes). The flagged events may be removed from the output file by using dmcopy "acisf00016_000N999_evt1.fits[events][status =0]" acisf00016_000N998_evt1.fits. This procedure may be used for only TIMED VFAINT mode data. The recomputation of the grade, pulse-height and coordinates information is disabled (doevtgrade=no calculate_pi=no stop=none).

Example 5

acis_process_events acisf00732_000N002_evt1.fits
acisf00732_996N002_evt1.fits badpixfile=custom_bpix1.fits doevtgrade=no
calculate_pi=no stop=none

In this example, the column STATUS is updated using a custom bad pixel file (badpixfile=custom_bpix1.fits). The custom file is the same as the pipeline-produced file acisf00732_000N002_bpix1.fits, except that a few more bad pixels and columns have been added. Events on these pixels and columns have STATUS bits set to one and may be removed by using dmcopy "acisf00732_000N996_evt1.fits[events][status=0]" acisf00732_000N995_bpix1.fits. The name of the bad pixel and column file used is written to the keyword BPIXFILE. The recomputation of the grade, pulse-height and coordinate information is disabled (doevtgrade=no calculate_pi=no stop=none).

Parameters

name type ftype def min max units reqd stacks
infile file input         yes yes
outfile file output         yes  
acaofffile file input NONE       yes yes
apply_cti boolean   yes          
apply_tgain boolean   yes          
alignmentfile file input )acaofffile         yes
obsfile file input NONE          
geompar file input geom          
logfile file output stdout          
gradefile file ARD CALDB          
gainfile file ARD CALDB          
badpixfile file input NONE          
threshfile file ARD CALDB          
ctifile file ARD CALDB          
tgainfile file ARD CALDB          
eventdef string   )stdlev1          
doevtgrade boolean   yes          
check_vf_pha boolean   no          
calc_cc_times boolean   no          
trail real   0.027 0 1      
spthresh integer   13 0 4095 adu    
time_offset real   0     s    
docentroid boolean   no          
calculate_pi boolean   yes          
pi_bin_width real   14.6 1.0 100.0 eV    
pi_num_bins integer   1024 256 32767      
max_cti_iter integer   15 1 20      
cti_converge real   0.1 0.1 1 adu    
tstart string   TSTART          
tstop string   TSTOP          
clobber boolean   no          
verbose integer   0 0 5      
stop string   sky chip|tdet|det|tan|sky|none        
instrume string   acis          
rand_seed integer   1 0        
rand_pha boolean   yes          
rand_pix_size real   0.5 0|0.5   pixel    
stdlev1 string              
grdlev1 string              
cclev1 string              
ccgrdlev1 string              

Detailed Parameter Descriptions

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

Name(s) of the input ACIS event data file(s). All of the columns in the event file that are recognized by acis_process_events are read and stored. Depending on the specification of the other acis_process_events parameters, the values of some of the input columns may be recomputed. If acis_process_events is used to recompute the coordinates TDETX, TDETY, DETX, DETY, X, and Y of an event, the input file should include the columns CCD_ID, CHIPX, and CHIPY. If acis_process_events is used to recompute the columns FLTGRADE and GRADE or ENERGY and PI, the input file should include the columns CCD_ID, CHIPX and CHIPY (or NODE_ID or CCDNODE), and PHAS. The columns specified by the parameter eventdef are written to the output file. If these columns are not produced by acis_process_events, they should be columns read from the input file. For example, if the output column list includes TIME, CCD_ID, EXPNO, CHIPX, or CHIPY, the input file should contain these columns. If the input data file is in the FITS format, these columns should be in a FITS extension that has an HDUNAME of EVENTS. A stack of input files may be used but only one output file in produced.

Parameter=outfile (file required filetype=output)

Name of the output ACIS event data file. If the output file is a FITS file, it has an extension with an HDUNAME of EVENTS that contains columns with the names and data types specified by the parameter eventdef.

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

Name of the input parameter file(s) used to compute the sky coordinates X and Y. If more than one input file is used, then the files should be in chronological order. The files should include columns named RA (or X_OFFSETS), DEC (or Y_OFFSETS), and ROLL (or ROLL_OFFSETS). These columns describe the coordinates of the optical axis and the roll of the telescope. Either of the ACIS data products *_asol1.fits or *_aoff1.fits may be used for this parameter, but the asol1 file is recommended.

Parameter=apply_cti (boolean default=yes)

If apply_cti=yes, the values of the column PHAS are adjusted to compensate for some of the effects of charge-transfer inefficiency (CTI). Note that it is not possible to double count the adjustment. The adjustment is always performed using the unadjusted values of PHAS. Therefore, if the input event-data file was CTI adjusted, the adjusted values are discarded and recomputed. The adjusted values are saved in the column named PHAS_ADJ. This column is not written to the output file unless it is included using the parameter eventdef.

The process involves an iterative estimate of the amount and distribution of charge deposited in the detector for an event based on the amount and distribution of charge read out for the event and the location of the event on a CCD. The maximum number of iterations allowed is specified by the parameter max_cti_iter. The process ends when the maximum number of iterations is reached or when the change in the amount of charge in each pixel of the 3x3 event island from one iteration to the next is less than the amount specified by the parameter cti_converge. If the CTI adjustment process has not converged after max_cti_iter trials are performed, then the last set of estimated values is copied to the column PHAS_ADJ and bit 20 (of 0-31) of the column STATUS is set to one. If the parameter doevtgrade=yes, the values of the columns FLTGRADE, GRADE, and PHA are computed using the values in the column PHAS_ADJ. Otherwise, the values in these columns remain unchanged. If the parameter calculate_pi=yes, the values in the columns ENERGY and PI are computed using the values in the column PHAS_ADJ. Otherwise, the values in these columns remain unchanged. The computation of the CTI adjusted values of PHAS_ADJ requires a CTI ARD file to be specified using the parameter ctifile.

If apply_cti=no, the CTI adjustment is removed. PHA, ENERGY and PI are recomputed using the unadjusted PHAS values if doevtgrade=yes and calculate_pi=yes.

Parameter=apply_tgain (boolean default=yes)

If apply_tgain=yes, a time-dependent gain adjustment is applied to the values in the column PHA. Since the adjustment is performed using unadjusted pulse heights, it is not possible to double count the time-dependent gain adjustment, even if the input event-data file was adjusted for the effects of the time-dependent gain. If the time-dependent gain adjustment is performed, the CTI-adjustment should also be applied (apply_cti=yes) since the time-dependent gain is calibrated using CTI-adjusted data. The size of the adjustment is a function of time, location and pulse-height of an event. The original, unadjusted PHA values are written to the column PHA_RO (i.e. the values of PHA_RO exclude the CTI and time-dependent gain adjustments). Since the CTI adjustment should be applied, the parameters doevtgrade and calculate_pi should be set to "yes" to insure that the values in the columns FLTGRADE, GRADE, PHA, PHA_RO, ENERGY and PI are computed correctly. The computation of the time-dependent gain adjustment requires a T_GAIN ARD file to be specified using the parameter tgainfile. If apply_tgain=no or tgainfile=none, then no adjustment is applied unless one already had been, in which case the adjustment is removed. The keyword TGAINCOR is set to T or F if apply_tgain=yes or no, respectively.

Parameter=alignmentfile (file filetype=input default=)acaofffile stacks=yes)

This parameter specifies the name(s) of the input file(s) used to compute the sky coordinates X and Y. If more than one input file is used, then the files should be in chronological order. The file should include the columns DY (or STF_Y), DZ (or STF_Z), and DTHETA (or STF_ROLL). These columns describe the motion of the science instrument module (e.g. the ACIS detectors) relative to the telescope. The ACIS data products *_asol1.fits, *_aoff1.fits, or *_soff1.fits may be used for this parameter, but the asol1 file is recommended. Only one output file is produced independent of the number of acaofffiles specified.

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

This parameter specifies the name of an input observation parameter file. Some of the information in this file is used to determine the values of various FITS header keywords. If a Level 1 or Level 2 ACIS event data file (*_evt1.fits, *_evt1a.fits, or *_evt2.fits) is used as input to acis_process_events, this parameter may be specified as NONE, since the keywords in the input event data file are copied to the output event data file.

Parameter=geompar (file filetype=input default=geom)

This parameter specifies the name of an input parameter file, which contains a list of the CALDB files used to compute the coordinates TDETX, TDETY, DETX, DETY, X, and Y (and SKY_1D for continuous clocking mode data). Those interested in using a specific set of calibration files for the coordinate transformations may copy and edit the file to suit their needs.

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

This parameter specifies the name of the destination (e.g. a file or stdout) to which the output messages generated by acis_process_events are sent. If logfile=stdout, the output is generally sent to the monitor. The amount of messages produced by acis_process_events is controlled by the parameter verbose.

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

This parameter specifies the name of the input file used to determine the value of the GRADE of an event from the value of the FLTGRADE for the event. FLTGRADE is a numeric representation of the charge distribution in a 3 pixel x 3 pixel event island. The valid values of FLTGRADE range from 0 to 255. These 256 values are mapped to only eight GRADEs (i.e. 0 to 7). This mapping is similar to the mapping used for the ASCA mission. Since the computation of the column GRADE requires the column FLTGRADE, the column FLTGRADE is computed if it does not exist in the input event file (even if the parameter doevtgrade=no). The name of the grade file used is written to the keyword named GRD_FILE in the EVENTS extension of the output file. The ACIS calibration data products are based on data that have GRADE = 0, 2, 3, 4, or 6 using a specific mapping of FLTGRADE to GRADE. Therefore, users should be very cautious about using a non-standard grade-map file.

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

This parameter specifies the name of the input file used to compute the value of the ENERGY of an event from the value of the PHA of the event. If gainfile=CALDB, the most recent gain file in the calibration database is used. The calculation of ENERGY is performed only if the parameter calculate_pi=yes. If a Level 1 or Level 2 ACIS event data file (*_evt1.fits, *_evt1a.fits, or *_evt2.fits) is used as input to acis_process_events and calculate_pi=no, the values in the column ENERGY of the input file are copied to the column ENERGY of the output file. The name of the gain file used is written to the keyword named GAINFILE in the EVENTS extension of the output file.

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

This parameter specifies the name of the input file used to set the bits of the column STATUS that are associated with bad pixels and columns. If a pixel or column is included in the file, one or more of the associated bits is set to one for events that occur on the pixel or column. The memo on STATUS bits in bad pixel files contains technical details, including a description of what each STATUS bit records.

If events have status bits set in the input event file, then the values are always copied to the same bits in the column STATUS of the output file. If the badpixfile is set to a value other than "NONE" (the default), then only ADDITIONAL status bits can be set in the output file. The inability to unset status bits before reseting them is a known bug that will be fixed in a future release.

The name of the file used is written to the keyword named BPIXFILE in the EVENTS extension of the output file.

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

This parameter specifies the name of the input file used to determine the value of the "split threshold" of an event. This threshold is used during the computation of the values of the FLTGRADE and PHA of the event. If threshfile is specified to be something other than NONE, the contents of the threshold file supersede the value of the split threshold specified by the parameter spthresh. However, if threshfile=NONE, the split threshold is specified by spthresh. The ACIS calibration data products are based on data obtained using a specific split threshold. Therefore, users should be very cautious about using a non-standard split threshold file.

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

This parameter specifies the name of the input file used to compensate for some of the effects of the charge-transfer inefficiency (CTI). If the parameter ctifile is specified appropriately and the parameter apply_cti=yes, the CTI adjusted values of the column PHAS are computed. These values are written to the column PHAS_ADJ if the column is specified as part of the output via the parameter eventdef. If ctifile=CALDB, the most recent CALDB file appropriate for the input event file(s) is used. The name of the CTI ARD file used is copied to the keyword named CTIFILE. If the CTI adjustment is not performed, CTIFILE=NONE.

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

This parameter specifies the name of the input time-dependent gain adjustment file. If the parameter tgainfile is specified appropriately and the parameter apply_tgain=yes, the adjustment is applied to the values in the column PHA. If tgainfile=CALDB, the most recent CALDB file appropriate for the input event file(s) is used. The name of the TGAIN ARD file used is copied to the keyword named TGAINFIL. If the TGAIN adjustment is not performed, TGAINFIL=NONE.

Parameter=eventdef (string default=)stdlev1)

This parameter specifies the names and data types of the columns in the output event data file. The syntax is data_type1:column_name1,data_type2:column_name2,... (e.g. d:time,s:ccd_id,...). The data types recognized by acis_process_events include d (double-precision real), f (single-precision real), i (integer), l (long integer), s (short integer), and x (logical). The recognized column names include TIME, CCD_ID, NODE_ID, EXPNO, CHIPX, CHIPY, TDETX, TDETY, DETX, DETY, X, Y, SKY_1D (for continuous-clocking observations), PHAS, PHAS_ADJ (for CTI-adjusted data), PHA, CORN_PHA (for graded-mode observations), ENERGY, PI, FLTGRADE, GRADE, and STATUS. Note that s:chip, s:tdet, f:det, and f:sky are equivalent to s:chipx,s:chipy, s:tdetx,s:tdety, f:detx,f:dety, and f:x,f:y, respectively. If the short-hand coordinate specifications are used instead of the long-hand ones, the world coordinate system (WCS) header keyword information is included in the output file. Four pre-defined sets of eventdef strings are included in the parameter file for acis_process_events and are described below. One of these may be used by specifying eventdef=")stdlev1", ")grdlev1", ")cclev1", or ")ccgrdlev1". If the output is adjusted for the effects of CTI, the column PHAS_ADJ is not included in the output file unless it is specifically specified using "f:phas_adj" as part of the eventdef string.

Parameter=doevtgrade (boolean default=yes)

If doevtgrade=yes, the columns FLTGRADE and PHA are computed. This computation requires the input event data file to include the columns CCD_ID, NODE_ID (or CHIPX or CCDNODE), and PHAS.

Parameter=check_vf_pha (boolean default=no)

If check_vf_pha=yes, the outer sixteen pixels of a 5 pixel x 5 pixel event island are used to search for potential cosmic-ray background events. If one or more of the pixels are above a threshold, STATUS bit 23 (of 0-31) is set to one. The flagged events may be removed from the output file by using dmcopy (e.g. dmcopy "acisf00732_000N999_evt1.fits[events][status=0]" acisf00732_000N998_evt1.fits). This procedure is only appropriate for TIMED VFAINT mode data. Users should be cautious when using this procedure because a significant fraction of the source events may be flagged for moderately bright to bright sources.

Parameter=calc_cc_times (boolean default=no)

If calc_cc_times=yes, the TIMEs of arrival of the events are computed using the readout times, the aspect solution information, and the coordinates of the source specified by RA_TARG and DEC_TARG. The values of TIME written to the output file are the times of arrival instead of the readout times. If eventdef includes the column TIME_RO, this column in the output file contains the readout times. This option is only appropriate for continuous-clocking mode data. Users should be sure that the coordinates RA_TARG and DEC_TARG are precise to within one 0.5 arcsec before executing acis_process_events. Otherwise, the times of arrival may be inaccurate. Since the position of the source on the detector is required to compute the TIMEs of arrival, the parameter stop must be set to sky (the default), det, or tdet.

Parameter=trail (real default=0.027 min=0 max=1)

This parameter specifies the fraction of the charge in the central row of pixels of a 5 pixel x 5 pixel event island that is expected to be smeared out or "trailed" to the top row of the event island via charge-transfer inefficiency. The threshold used to determine if one of the outer sixteen pixels of an event has a significant amount of charge in it (i.e. if STATUS bit 23 for the event should be set to one) is the sum of the value specified by the parameter spthresh and the amount of charge trailed (for the top row of the event island). The default value of trail is based on some calibration work and users should be cautious about using other values.

Parameter=spthresh (integer default=13 min=0 max=4095 units=adu)

This parameter is used to determine the value of the "split threshold" of an event. This threshold is used during the computation of the values of the FLTGRADE and PHA of the event. If the parameter threshfile is specified to be something other than NONE, the contents of the threshold file supersede the value of the parameter spthresh. The ACIS calibration data products are based on data obtained using a specific split threshold. Therefore, users should be very cautious about using a non-standard split threshold. Note that the columns FLTGRADE and PHA are computed only if doevtgrade=yes and the associated input data dependencies are satisfied.

Parameter=time_offset (real default=0 units=s)

This parameter specifies a time difference in seconds that is added to the time of each event when the event times are compared to the aspect data of the telescope. That is, use of a non-zero time_offset introduces a phase shift in the dither pattern and result in a change in the values of the coordinates X and Y. The values of TIME that are written to the output file do not have the offset added to them. The TIMEs in the output file are the same as the TIMEs in the input file. The use of this parameter requires an input event data file with a column named TIME. Users should be very cautious about using a time_offset other than zero, since the values of the coordinates X and Y depend on the value of time_offset.

Parameter=docentroid (boolean default=no)

If docentroid=yes, the local maximum of an event in the coordinates CHIPX and CHIPY is computed. In this case, the input data file should include the columns CCD_ID, CHIPX, CHIPY, and PHAS. The computation also requires the specification of the split threshold. If the parameter threshfile is specified, the value of the split threshold is obtained from the file. Otherwise, the value of the split threshold is determined by the parameter spthresh. The recomputed chip coordinates are used during the computation of the coordinates TDETX, TDETY, DETX, DETY, X, and Y (and SKY_1D for continuous clocking mode data). The recomputed coordinates CHIPX and CHIPY are not written to the output file. The values of the coordinates CHIPX and CHIPY are copied from the input event file to the output event file.

Parameter=calculate_pi (boolean default=yes)

If calculate_pi=yes, the values of the ENERGY and PI (pulse-height invariant) of an event are computed. The computation of ENERGY requires the input event data file to include the columns CCD_ID, CHIPX, CHIPY, and PHA. If the column PHA is not in the input event data file, it can be computed by acis_process_events (see the parameter doevtgrade). The parameter gainfile must be specified. The value of PI = int(ENERGY/pi_bin_width) + 1.

Parameter=pi_bin_width (real default=14.6 min=1.0 max=100.0 units=eV)

If calculate_pi=yes (and the appropriate input data dependencies are satisfied), the parameter pi_bin_width determines the linear width of each PI bin in eV. For example, if pi_bin_width=14.6, events that have ENERGY < 14.6, 14.6 <= ENERGY < 29.2, ... yield PI = 1, 2, ...

Parameter=pi_num_bins (integer default=1024 min=256 max=32767)

If calculate_pi=yes (and the appropriate input data dependencies are satisfied), the parameter pi_num_bins determines the largest value of PI. (The first PI bin is always one.) For example, if pi_num_bins=1024 and the computed value of ENERGY for an event corresponds to a PI value of 1027, the value of PI=1024 for the event.

Parameter=max_cti_iter (integer default=15 min=1 max=20)

The maximum number of iterations to be performed when trying to satisfy the CTI convergence criterion (defined by cti_converge). If the CTI adjustment has not converged after the maximum number of iterations, STATUS bit 20 of (0-31) is set to one.

Parameter=cti_converge (real default=0.1 min=0.1 max=1 units=adu)

This parameter specifies the convergence criterion for each CTI-adjusted pixel in adu. The CTI adjustment process continues until the change in the value of PHAS_ADJ < cti_converge for every pixel of a 3 pixel x 3 pixel event island (or when the maximum number of iterations is reached).

Parameter=tstart (string default=TSTART)

The parameters tstart and tstop are used to determine the chronological sequence of the input files if multiple input files are specified. The parameter tstart specifies the name of the keyword in the input event data file that contains the "begin" time associated with an event file.

Parameter=tstop (string default=TSTOP)

The parameters tstart and tstop are used to determine the chronological sequence of the input files if multiple input files are specified. The parameter tstop specifies the name of the keyword in the input event data file that contains the "end" time associated with an event file.

Parameter=clobber (boolean default=no)

If clobber=yes and a file exists that has the name specified by the parameter outfile, the existing file is overwritten by acis_process_events. If clobber=no and a file exists that has the name specified by the parameter outfile, acis_process_events exits with an error message and the existing file is unchanged.

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

This parameter determines the amount of messages that is generated by acis_process_events. If verbose=0, essentially no messages are reported. If verbose=5, the largest amount of messages is produced. The messages are directed to the destination specified by the parameter logfile.

Parameter=stop (string default=sky min=chip|tdet|det|tan|sky|none)

This parameter determines how many of the coordinates are recomputed. The five possible options are stop=none, chip, tdet, det, and sky. If stop=none or chip, none of the coordinates are recomputed. If stop=tdet, only T mDETX and TDETY are recomputed. If stop=det, TDETX, TDETY, DETX, and DETY are recomputed. If stop=sky, TDETX, TDETY, DETX, DETY, X, and Y are recomputed. For observations performed using continuous-clocking mode, the TIMEs of arrival are computed correctly only if stop=tdet, det, or sky and SKY_1D is computed only if stop=sky.

Parameter=instrume (string default=acis)

The parameter instrume is used to determine which set of geometrical detector information is used during the computation of the coordinates TDETX, TDETY, DETX, DETY, X, and Y.

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

If the parameter rand_pix_size > 0.0, the parameter rand_seed determines the initial seed used when the CHIPX and CHIPY coordinates are randomized during the computation of the coordinates DETX and DETY. This parameter should be non-negative. If rand_seed=0, the initial seed is derived from the time of the system clock of the computer on which acis_process_events is run. If acis_process_events is used more than once on an event file, then the values of the coordinates DETX, DETY, X, and Y (and SKY_1D for continuous clocking mode data) in the output files are the same if and only if the same positive value of rand_seed is used each time the tool is executed.

Parameter=rand_pha (boolean default=yes)

If rand_pha=yes then the value of ENERGY is computed by adding a uniform random deviate on the range [-0.5,+0.5) adu to the value of PHA and using the specified gain file. Since the value of PI is a linear function of ENERGY, the effects of the randomization affect the value of PI as well. Use of this randomization removes certain aliasing effects that would otherwise be obvious in the PI spectra of bright sources. Note that the value of PHA written to the output file does not include the effects of the randomization. Only the values of ENERGY and PI are modified by the randomization.

Parameter=rand_pix_size (real default=0.5 min=0|0.5 max= units=pixel)

The parameter rand_pix_size specifies the maximum offset that is used to randomize the CHIPX and CHIPY coordinates during the computation of the coordinates DETX and DETY. Since the values of the coordinates X and Y (and SKY_1D for continuous clocking mode data) are computed from DETX and DETY, the values of X and Y are also randomized. If rand_pix_size=0.5, then the offset that is added to the chip coordinates is in the range from -0.5 to +0.5 pixels. If rand_pix_size=0.0, the coordinate randomization is disabled.

Parameter=stdlev1 (string)

This string specifies one of the four pre-defined sets of column names and data types that can be used to control the information written to the output file. This string is appropriate for timed exposure observations that do not use graded mode. eventdef=")stdlev1" is equivalent to eventdef="{d:time,s:ccd_id, s:node_id,i:expno,s:chip,s:tdet,f:det,f:sky,s:phas,l:pha,l:pha_ro, f:energy,l:pi,s:fltgrade,s:grade,x:status}".

Parameter=grdlev1 (string)

This string specifies one of the four pre-defined sets of column names and data types that can be used to control the information written to the output file. This string is appropriate for timed exposure observations that use graded mode. eventdef=")grdlev1" is equivalent to eventdef="{d:time,s:ccd_id,s:node_id,i:expno,s:chip, s:tdet,f:det,f:sky,l:pha,l:pha_ro,s:corn_pha,f:energy,l:pi, s:fltgrade,s:grade,x:status}".

Parameter=cclev1 (string)

This string specifies one of the four pre-defined sets of column names and data types that can be used to control the information written to the output file. This string is appropriate for continuous clocking mode observations that do not use graded mode. eventdef=")cclev1" is equivalent to eventdef="{d:time,s:ccd_id, s:node_id,i:expno,s:chip,s:tdet,f:det,f:sky,f:sky_1d,s:phas,l:pha, l:pha_ro,f:energy,l:pi,s:fltgrade,s:grade,x:status}".

Parameter=ccgrdlev1 (string)

This string specifies one of the four pre-defined sets of column names and data types that can be used to control the information written to the output file. This string is appropriate for continuous clocking mode observations that do not use graded mode. eventdef=")ccgrdlev1" is equivalent to eventdef="{d:time,s:ccd_id, s:node_id,i:expno,s:chip,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,x:status}".

CHANGES IN CIAO 3.4

Serial CTI

The CTI-adjustment algorithm now accommodates the newly calibrated serial charge-transfer inefficiency on the backside-illuminated CCDs. This is in addition to the continued support for parallel CTI.

Remove a 0.5 adu shift in the pulse heights

There was a bug in the time-dependent gain algorithm that produced a systematic -0.5 adu (about -2 eV) shift in the pulse-height values. This offset has been removed.

CHANGES IN CIAO 3.3

BPIXFILE header keyword

If you reprocess your data with a new bad pixel file, acis_process_events will update the BPIXFILE header keyword with that filename

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.

CTI correction for continuous-clocking (CC) mode data

The tool now correctly applies the CTI adjustment to CC-mode data. The Continuous Clocking Mode why topic has details about working with CC-mode data.

CHANGES IN CIAO 3.1

ACIS time-dependent gain adjustment

In the CIAO 3.1 release, this tool has been modified to include a time-dependent gain adjustment, which is now applied to all data by default. This adjustment is necessary because the "effective gains" of the detectors are drifting with time as the result of an increasing CTI. The Time-Dependent ACIS Gain Correction thread has more information.

Two new parameters have been added so that this adjustment may be applied: apply_tgain and tgainfile. In addition, the eventdefs now include "l:pha_ro". This column is required and includes the original PHA values before the CTI and time-dependent gain adjustments are applied.

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.