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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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

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.

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.

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).

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.

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.

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.

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.

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.

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.

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.

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.

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.

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}".

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}".

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}".

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}".