acis_process_events

Synopsis

Produce or update the time, coordinate, pulse-height, grade, and status information in ACIS event files

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

Description

acis_process_events is part of the standard ACIS Level 1 processing pipeline. The tool can be employed to update an existing ACIS event data file by recomputing (1) the TIMEs of arrival (for continuous-clocking mode data), (2) the coordinates CHIPX_ADJ, CHIPY_ADJ, TDETX, TDETY, DETX, DETY, X, and Y (and SKY_1D for continuous-clocking mode data), (3) the pulse-height information PHAS_ADJ, PHA, PHA_RO, ENERGY and PI, (4) the FLTGRADE and GRADE, and (5) some of the bits in STATUS. For example, the tool can be used to apply or remove a sub-pixel coordinate adjustment or a coordinate randomization, apply or remove a CTI adjustment, apply or remove a time-dependent gain adjustment, disable the randomization used to compute the ENERGY and PI, identify potential background events for VFAINT mode data, apply a custom bad-pixel file, 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 that are incompatible with the calibration products.

Example 1

acis_process_events acisf00732_000N002_evt1.fits
acisf00732_999N002_evt1.fits acaofffile=pcadf079650047N002_asol1.fits
doevtgrade=no calculate_pi=no pix_adj=EDSER

In this example, the coordinates CHIPX_ADJ, CHIPY_ADJ, DETX, DETY, X, and Y are recomputed after applying a sub-pixel event-repositioning algorithm (pix_adj=EDSER). The computation includes the latest calibration files and the specified aspect solution file (acaofffile=pcadf079650047N002_asol1.fits). The pulse-height information is not changed (doevtgrade=no calculate_pi=no).

It is possible to remove the sub-pixel coordinate adjustments from CHIPX_ADJ, CHIPY_ADJ, DETX, DETY, X, and Y by using the same command shown above, except with pix_adj=NONE.

Example 2

acis_process_events acisf00732_000N002_evt1.fits
acisf00732_998N002_evt1.fits acaofffile=pcadf079650047N002_asol1.fits
doevtgrade=no calculate_pi=no pix_adj=RANDOMIZE

In this example, the coordinates CHIPX_ADJ, CHIPY_ADJ, DETX, DETY, X, and Y are recomputed after randomizing the chip coordinates. The computation includes the latest calibration files and the specified aspect solution file (acaofffile=pcadf079650047N002_asol1.fits). The pulse-height information is not changed (doevtgrade=no calculate_pi=no).

It is possible to remove the coordinate randomizations from CHIPX_ADJ, CHIPY_ADJ, DETX, DETY, X, and Y by using the same command shown above, except with pix_adj=NONE.

Example 3

acis_process_events acisf00732_000N002_evt1.fits
acisf00732_997N002_evt1.fits apply_cti=yes apply_tgain=yes
ctifile=CALDB tgainfile=CALDB mtlfile=acisf00732_000N002_mtl1.fits
doevtgrade=yes calculate_pi=yes stop=none

In this example, the values of PHA, FLTGRADE, and GRADE are recomputed after performing a temperature-dependent CTI adjustment to the values of PHAS to obtain PHAS_ADJ (apply_cti=yes ctifile=CALDB mtlfile=acisf00732_000N002_mtl1.fits doevtgrade=yes). 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).

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 with apply_cti=no and apply_tgain=no.

Example 4

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

In this example, the values of ENERGY and PI are recomputed using the latest 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 coordinates, FLTGRADE, and GRADE is disabled (stop=none and doevtgrade=no).

Example 5

acis_process_events acisf00016_000N002_evt1.fits
acisf00016_995N002_evt1.fits doevtgrade=no check_vf_pha=yes
calculate_pi=no stop=none pix_adj=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 (e.g. dmcopy "acisf00016_000N995_evt1.fits[events][status=0]" acisf00016_000N994_evt1.fits). This algorithm may be used for only VFAINT mode data. The recomputation of the coordinates, grade, and pulse-height information is disabled (stop=none doevtgrade=no calculate_pi=no).

Example 6

acis_process_events "acisf00732_000N002_evt1.fits[cols -status]"
acisf00732_993N002_evt1.fits badpixfile=custom_bpix1.fits doevtgrade=no
calculate_pi=no stop=none

In this example, the STATUS is updated using a custom bad pixel file (badpixfile=custom_bpix1.fits). Before reprocessing, it is necessary to remove the current set of STATUS bits (i.e. to use [cols -status]). 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 (e.g. dmcopy "acisf00732_000N993_evt1.fits[events][status=0]" acisf00732_000N992_bpix1.fits). The name of the bad pixel and column file used is written to the keyword BPIXFILE. The recomputation of the coordinate, grade, and pulse-height information is disabled (stop=none doevtgrade=no calculate_pi=no).

Parameters

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 infile that are recognized by acis_process_events are read and stored. Depending on the other parameter settings, the values of some of the input columns may be recomputed. If acis_process_events is used to apply a sub-pixel event-repositioning algorithm, then the infile should include the columns FLTGRADE and ENERGY (for pix_adj=EDSER) or PHAS (for pix_adj=CENTROID). If acis_process_events is used to recompute the coordinates TDETX, TDETY, DETX, DETY, X, and Y, then the infile should include the columns CCD_ID, CHIPX, and CHIPY. If acis_process_events is used to recompute the values of FLTGRADE and GRADE or ENERGY and PI, then the infile 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, then they should be columns read from the infile. For example, if the eventdef includes TIME, CCD_ID, EXPNO, CHIPX, or CHIPY, then the infile should contain these columns. If the infile is in the FITS format, then these columns should be in a FITS extension that has an HDUNAME of EVENTS. A stack of infiles 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 outfile is a FITS file, then 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 aspect solution file(s) used to compute the sky coordinates X and Y. The aspect files should be in chronological order. If they are not, then the coordinates will be inaccurate and a warning will be produced.

The files should include the columns 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 pcadf*_asol1.fits or acisf*_aoff1.fits may be used for this parameter, but the pcadf*asol1.fits file is recommended.

Parameter=apply_cti (boolean default=yes)

If apply_cti=yes and the parameter mtlfile is specified appropriately, then the values of PHAS are adjusted to compensate for some of the effects of the temperature-dependent charge-transfer inefficiency (CTI). Since the adjustment is always computed using the unadjusted values of PHAS, it is not possible to apply multiple adjustments. If the infile was CTI adjusted, then the adjusted values are discarded and recomputed. The adjusted values are saved in the column PHAS_ADJ. This column is not written to the outfile unless the parameter eventdef includes "f:phas_adj".

The computation involves an iterative estimate of the amount and the distribution of charge that is deposited in the detector based on the amount and the distribution of charge that reaches the read out electronics. The estimate also depends upon the location at which the charge was deposited and the temperature of the detector. 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 3 pixel x 3 pixel event island from one iteration to the next is less than the amount specified by the parameter cti_converge. The maximum number of iterations allowed is specified by the parameter max_cti_iter. If the CTI adjustment process has not converged after max_cti_iter estimates are computed, then the last set of estimated values is copied to the column PHAS_ADJ and bit 20 (of 0-31) of the STATUS is set to one. If the parameter doevtgrade=yes, then the values of FLTGRADE, GRADE, and PHA are computed using the values of PHAS_ADJ. Otherwise, the values of FLTGRADE, GRADE, and PHA remain unchanged. If the parameter calculate_pi=yes, then the values of ENERGY and PI are recomputed using the CTI adjusted pulse heights. Otherwise, the values of ENERGY and PI remain unchanged. Note that the computation of the CTI adjustment also requires an appropriate CTI file to be specified using the parameter ctifile. If apply_cti=yes, then the keyword CTI_CORR is set to T.

If apply_cti=no, then the CTI adjustment is removed, the values of PHA, ENERGY and PI are recomputed using the unadjusted pulse heights PHAS (if doevtgrade=yes and calculate_pi=yes) and the keyword CTI_CORR=F.

Parameter=apply_tgain (boolean default=yes)

If apply_tgain=yes, then a time-dependent gain adjustment is applied to the values of PHA. Since the adjustment is performed using pulse heights that have not had a time-dependent gain adjustment applied, it is not possible to apply multiple time-dependent gain adjustments, even if the infile was adjusted for the effects of the time-dependent gain. If the time-dependent gain adjustment is applied, then 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 the 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 of FLTGRADE, GRADE, PHA, PHA_RO, ENERGY and PI are computed correctly. The computation of the time-dependent gain adjustment requires an appropriate CALDB input 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 alignmentfile is used, then the files should be in chronological order. If they are not, then the coordinates will be inaccurate and a warning will be produced. The files 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 pcadf*_asol1.fits, acisf*_aoff1.fits, or acisf*_soff1.fits may be used for this parameter, but the pcadf*_asol1.fits file is recommended. Only one outfile 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 the infile is a Level 1 or Level 2 ACIS event data file (acisf*_evt1.fits, acisf*_evt1a.fits, or acisf*_evt2.fits), then obsfile may be set to NONE because the keywords in the infile are copied to the outfile.

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

This parameter specifies the name of an input geometry 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). If a user is interested in using a specific set of files other than the latest set, then the default file geom.par can be copied to custom_geom.par and edited accordingly. In this case, the parameter geompar=custom_geom.

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

This parameter specifies the name of the destination to which the output messages are sent. If logfile=stdout, then the output is (usually) sent to the monitor. If a specific file name is used, then the messages are written to the file. The amount of messages 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 values of GRADE from the values of FLTGRADE. 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 values of FLTGRADE are required, these values are computed if they do not exist in the infile (even if the parameter doevtgrade=no). The name of the gradefile used is written to the keyword GRD_FILE. The ACIS calibration products are based on data that have GRADE = 0, 2, 3, 4, or 6 (i.e. the "good" grades) using a specific mapping of FLTGRADE to GRADE. Users should be cautious about using a custom gradefile.

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

This parameter specifies the name of the input file used to perform a temperature-dependent CTI adjustment for GRADED mode data.

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

This parameter specifies the name of the input file used to compute the values of ENERGY from the values of PHA. If gainfile=CALDB, then the latest gain file in the calibration database is used. The computation of ENERGY is performed only if the parameter calculate_pi=yes. If the infile is a Level 1 or Level 2 ACIS event data file (acisf*_evt1.fits, acisf*_evt1a.fits, or acisf*_evt2.fits) and calculate_pi=no, then the values of ENERGY in the infile are copied to the outfile. The name of the gainfile used is written to the keyword GAINFILE.

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

This parameter specifies the name of the observation-specific input file that contains a list of the bad pixels and columns. One or more of the STATUS bits are set to one for events that occur on these pixels and columns. Since it is only possible to set, not unset, bad-pixel STATUS bits while reprocessing, users should remove the STATUS column from the infile (e.g. infile="acisf00732_000N002_evt1.fits[cols -status]"). Detailed descriptions of the meanings of the bad-pixel and event data STATUS bits can be found here and here, respectively. The name of the badpixfile used is written to the keyword BPIXFILE.

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." This threshold, typically 13 adu, is used during the computation of the values of FLTGRADE and PHA. If threshfile is specified to be something other than NONE, then the contents of the threshfile supersede the value specified by the parameter spthresh. However, if threshfile=NONE, then the split threshold is specified by spthresh. The ACIS calibration products are based on data obtained using a specific split threshold. Users should be cautious about using a custom threshfile.

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 parameters ctifile and mtlfile are specified appropriately and the parameter apply_cti=yes, then the CTI adjusted values of PHAS are computed. These values are written to the column PHAS_ADJ if the eventdef includes "f:phas_adj". If ctifile=CALDB, then the latest CALDB file appropriate for the infile is used. The name of the CTI file used is copied to the keyword CTIFILE. The information in the ctifile is also used to determine the value of the keyword CTI_APP. This keyword is a 10 character string that indicates the type of CTI data that is available for each CCD. Each character is either a N (no data), P (only parallel CTI data) or B (both parallel and serial CTI data). If the CTI adjustment is not performed, then CTIFILE=NONE and CTI_APP=NNNNNNNNNN.

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, then the adjustment is applied to the values of PHA. If tgainfile=CALDB, then the latest CALDB file appropriate for the infile is used. The name of the TGAIN file used is written to the keyword TGAINFIL. If the TGAIN adjustment is not performed, then TGAINFIL=NONE.

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

This parameter specifies the name of the observation-specific input file used to obtain the focal-plane temperature for the temperature-dependent CTI adjustment. If an appropriate file is specified and apply_cti=yes, then the CTI adjustment will include a temperature dependence. If mtlfile=NONE and apply_cti=yes, then a CTI adjustment will be applied, but the adjustment will be inaccurate. The name of the mtlfile used is written to the keyword MTLFILE. If mtlfile=NONE, then the keyword is set to NONE.

Parameter=eventdef (string default=)stdlev1)

This parameter specifies the names and data types of the columns in the outfile. 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, TIME_RO, CCD_ID, NODE_ID, EXPNO, CHIPX, CHIPY, CHIPX_ADJ, CHIPY_ADJ, TDETX, TDETY, DETX, DETY, X, Y, SKY_1D (for continuous-clocking observations), PHAS, PHAS_ADJ (for CTI-adjusted data), PHA, PHA_RO, CORN_PHA (for graded-mode observations), ENERGY, PI, FLTGRADE, GRADE, and STATUS. Note that "s:chip", "f:chip_adj", "s:tdet", "f:det", and "f:sky" are equivalent to "s:chipx,s:chipy", "f:chipx_adj,f:chipy_adj", "s:tdetx,s:tdety", "f:detx,f:dety", and "f:x,f:y", respectively. If the short-hand coordinate specifications are used, then the appropriate world coordinate system (WCS) header keyword information is included in the outfile. Four pre-defined sets of eventdef strings are included in the parameter file: stdlev1, grdlev1, cclev1, and ccgrdlev1 (see below). One of these sets may be used by specifying, for example, eventdef= ")stdlev1"" . If a sub-pixel event-repositioning algorithm is used, then the columns CHIPX_ADJ and CHIPY_ADJ are not included in the outfile unless the user specifically includes "f:chip_adj" in the eventdef. Likewise, if the CTI adjustment is performed, then the column PHAS_ADJ is not included in the outfile unless the user specifically includes "f:phas_adj" in the eventdef.

Parameter=doevtgrade (boolean default=yes)

If doevtgrade=yes, then the values of FLTGRADE and PHA are computed from the values of PHAS_ADJ if the CTI adjustment is applied or from PHAS if it is not.

Parameter=check_vf_pha (boolean default=no)

If check_vf_pha=yes, then 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, then STATUS bit 23 (of 0-31) is set to one to indicate that an event may be due to a cosmic ray. The flagged events can be removed from the outfile by using dmcopy (e.g. dmcopy "acisf00732_000N995_evt1.fits[events][status=0]" acisf00732_000N994_evt1.fits). For moderately bright or bright sources, users should be cautious when using this algorithm because a significant fraction of the source events may be identified as potential background events. The algorithm is only appropriate for VFAINT mode data. It is most applicable for analysis of extended sources.

Using this algorithm on modestly bright POINT like sources can cause good events to be removed. If there is a readout streak or any indication of pileup, then it is likely this algorithm will remove good events. Users can check which events have been tagged by this algorithm using this filter "[status=xxxxxxxx1xxxxxxxxxxxxxxxxxxxxxxx]". If the resulting image clearly shows sources then this algorithm should be turned of (check_vf_pha=no).

Parameter=calc_cc_times (boolean default=no)

If calc_cc_times=yes, then the TIMEs of arrival of the events are computed using the readout times, the aspect solution, and the coordinates of the source as specified by the keywords RA_TARG and DEC_TARG. 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. The times of arrival are written to the column TIME instead of the readout times. If the eventdef includes "d:time_ro", then the read out times are written to the column TIME_RO. The use of this algorithm is only appropriate for continuous-clocking mode data. 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)

If check_vf_pha=yes, then this parameter is used to determine the pulse-height threshold for the pixels on the top row of a 5 pixel x 5 pixel event island. The effects of the CTI cause some fraction of the charge in the central row of the event island to be "trailed" to the top row. The parameter trail specifies that fraction. Therefore, the pixels on the top row of the event island have a threshold given by the spthresh plus the specified portion of trailed charge. For the other pixels around the outside edge of the event island, the threshold is just the spthresh.

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

This parameter specifies the value of the "split threshold." This threshold may be used during the computation of the values of FLTGRADE and PHA. However, if the parameter threshfile is specified to be something other than NONE, then the data in the threshfile are used instead of the parameter spthresh. The ACIS calibration products are based on data obtained using a specific split threshold. Users should be cautious about using a custom spthresh. Note that the FLTGRADE and PHA are computed only if doevtgrade=yes and the associated input dependencies are satisfied.

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

This parameter specifies a time difference in seconds that is added to the event times when the times are compared to the aspect data. Use of a non-zero time_offset introduces a phase shift in the dither pattern, which can result in a change in the values of the coordinates X and Y. The use of this parameter requires an infile with the column TIME. The TIMEs in the outfile are the same as the TIMEs in the infile. Users should be cautious about using a time_offset other than zero.

Parameter=calculate_pi (boolean default=yes)

If calculate_pi=yes, then the values of ENERGY and PI are computed. The computation of ENERGY requires the infile to include the columns CCD_ID, CHIPX, CHIPY, and PHA and requires an appropriate gainfile. If the column PHA is not in the infile, then it can be computed by acis_process_events (see the parameter doevtgrade). The value of PI = int(ENERGY/pi_bin_width) + 1, where the function int truncates (i.e. rounds down) the number to an integer.

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

If calculate_pi=yes (and the appropriate input dependencies are satisfied), then the parameter pi_bin_width determines the width of each PI bin in eV. For example, if pi_bin_width=14.6, then 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 dependencies are satisfied), then 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 corresponds to a PI value of 1027, then the value of PI=1024.

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 (see cti_converge). If the CTI adjustment has not converged after the maximum number of iterations, then the values of the adjusted pulse heights PHAS_ADJ are the values from the last iteration and 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 continues until the change in the value of the adjusted pulse height < cti_converge for every pixel in a 3 pixel x 3 pixel event island (or until the maximum number of iterations is reached).

Parameter=tstart (string default=TSTART)

If multiple infiles are specified, then the parameters tstart and tstop are used to determine the chronological sequence of the files. The parameter tstart specifies the name of the keyword that contains the "begin" time.

Parameter=tstop (string default=TSTOP)

If multiple infiles are specified, then the parameters tstart and tstop are used to determine the chronological sequence of the files. The parameter tstop specifies the name of the keyword that contains the "end" time.

Parameter=clobber (boolean default=no)

If clobber=yes and a file exists that has the same name as the outfile, then the existing file is overwritten. If clobber=no, then the existing file remains unchanged and acis_process_events exits with an error message.

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

This parameter determines the amount of messages that is generated. If verbose=0, then very few messages are reported. If verbose=5, then a large amount of messages is produced. The messages are sent 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. If stop=none or chip, then none of the coordinates are recomputed. If stop=tdet, then only TDETX and TDETY are recomputed. If stop=det, then TDETX, TDETY, DETX, and DETY are recomputed. If stop=sky, then CHIPX_ADJ, CHIPY_ADJ, TDETX, TDETY, DETX, DETY, X, and Y are recomputed. For continuous-clocking mode observations, 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 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)

This parameter determines the initial seed to use for randomizations (e.g. when pix_adj=RANDOMIZE or rand_pha=yes). The value should be non-negative. If rand_seed=0, then the initial seed is derived from the system clock of the computer. If acis_process_events is executed more than once with the same positive rand_seed, then the same sequence of random numbers is used.

Parameter=rand_pha (boolean default=yes)

Two separate pulse-height randomizations can be performed in acis_process_events. Both randomizations are controlled by the parameter rand_pha. One randomization is performed if rand_pha=yes, apply_tgain=yes, and doevtgrade=yes. In this case, uniform random deviates in the range [0, +1) adu are added to the real-valued, time-dependent, gain-adjusted pulse heights PHA before the values of PHA are truncated (i.e. rounded down) to integers. The integer values are written to the outfile and used to compute the values of ENERGY and PI.

A separate randomization is performed if rand_pha=yes and calculate_pi=yes. In this case, uniform random deviates in the range [-0.5, +0.5) adu are added to the values of PHA and the randomized pulse heights (and the specified gainfile) are used to compute the values of ENERGY. Since the values of ENERGY are used to compute the values of PI, this pulse-height randomization removes certain aliasing effects that would otherwise be obvious in the PI spectra of bright sources. (The number of PHA bins per PI bin is not a constant.)

The value of PHA written to the outfile can include the effects of the time-dependent gain randomization, but not the effects of the PHA to ENERGY randomization. The values of ENERGY and PI can include the effects of both randomizations. The ranges of the random deviates were chosen to avoid introducing systematic gain shifts.

Parameter=pix_adj (string default=EDSER min=EDSER|CENTROID|RANDOMIZE|NONE)

If pix_adj=EDSER and an appropriate subpixfile is used, then the energy-dependent sub-pixel event-repositioning algorithm of Li et al. (2004, ApJ, 610, 1204) is used to calculate the real-valued adjusted coordinates CHIPX_ADJ and CHIPY_ADJ. The adjustments depend on the values of FLTGRADE and ENERGY. The keywords PIX_ADJ and RAND_SKY are set to EDSER and 0 respectively. The algorithm EDSER can be used for FAINT, FAINT_BIAS, GRADED, and VFAINT mode observations, but not for continuous-clocking mode observations.

If pix_adj=CENTROID, then a different sub-pixel event-repositioning adjustment is applied. The adjusted coordinates CHIPX_ADJ and CHIPY_ADJ represent the weighted mean location of the pixels in the central 3 pixel x 3 pixel event island. The weight for a pixel is based upon the amount of charge in the pixel (i.e. upon the values of PHAS). The keywords PIX_ADJ and RAND_SKY are set to CENTROID and 0, respectively. Since this algorithm is identical to the algorithm that was used for docentroid=yes, the parameter docentroid is no longer available. The algorithm CENTROID can be used for FAINT, FAINT_BIAS, and VFAINT mode observations, but not for GRADED or continuous-clocking mode observations. Since this algorithm has not been fully tested, it should be used with caution.

If pix_adj=RANDOMIZE, then the coordinates CHIPX_ADJ and CHIPY_ADJ are computed by adding uniform random deviates in the range [-0.5, +0.5) pixels to the values of CHIPX and CHIPY, respectively. The keywords PIX_ADJ and RAND_SKY are set to RANDOMIZE and 0.5, respectively. While it used to be possible to control the range of the uniform random deviate with the parameter rand_pix_size, the use of this parameter has been discontinued. Randomization can be applied to CC33_FAINT, CC33_GRADED, FAINT, FAINT_BIAS, GRADED, and VFAINT mode observations.

If pix_adj=NONE, then no coordinate adjustments are applied. The values of CHIPX_ADJ and CHIPY_ADJ are identically the same as the values of CHIPX and CHIPY, respectively. The keywords PIX_ADJ and RAND_SKY are set to NONE and 0 respectively.

Since the computation of the coordinates CHIPX_ADJ and CHIPY_ADJ always begins with the coordinates CHIPX and CHIPY and since only one parameter is used to select a sub-pixel adjustment or coordinate randomization, it is not possible to do both or to apply multiple adjustments or randomizations. Although the coordinates CHIPX_ADJ and CHIPY_ADJ are not written to the outfile by default, they will be written if the parameter eventdef includes "f:chip_adj". If stop=sky, then the values of CHIPX_ADJ and CHIPY_ADJ are used to compute the values of the coordinates DETX, DETY, X, and Y.

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

This parameter specifies the name of the input file used to apply the sub-pixel event-repositioning algorithm EDSER. If an appropriate file is specified and the parameter pix_adj=EDSER, then the energy-dependent sub-pixel event-repositioning algorithm of Li et al. (2004, ApJ, 610, 1204) is used to calculate the real-valued adjusted coordinates CHIPX_ADJ and CHIPY_ADJ. Although these coordinates are not written to the outfile by default, they will be written if the parameter eventdef includes "f:chip_adj". The values of CHIPX_ADJ and CHIPY_ADJ are used to compute the values of the coordinates DETX, DETY, X, and Y. If subpixfile=CALDB, then the latest CALDB file appropriate for the infile is used. The name of the file used is copied to the keyword SUBPIXFL.

Parameter=stdlev1 (string)

This string is one of four pre-defined eventdefs. It includes a set of column names and data types that is appropriate for FAINT and VFAINT mode observations. Using 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 is one of four pre-defined eventdefs. It includes a set of column names and data types that is appropriate for GRADED mode observations. Using 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 is one of four pre-defined eventdefs. It includes a set of column names and data types that is appropriate for CC33_FAINT mode observations. Using 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 is one of four pre-defined eventdefs. It includes a set of column names and data types that is appropriate for CC33_GRADED mode observations. Using 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 4.5

• Two separate pulse-height randomizations are performed in acis_process_events. One randomization is performed when the value of PHA is calculated after the time-dependent gain adjustment is applied. The other randomization is performed when the value of ENERGY is calculated from the value of PHA. In previous versions of acis_process_events, only the second of these two randomizations was controlled by the parameter rand_pha. Now both randomizations are controlled by this parameter.

• The parameters cclev1 and ccgrdlev1, which are the default eventdefs for the regular (CC33_FAINT) and graded (CC33_GRADED) continuous-clocking modes, have been expanded to include "d:time_ro." As a result, the output event files include the read-out times (TIME_RO) in addition to the times of arrival at the detector (TIME).

• The following warning message is no longer printed at verbose=0:

  # acis_process_events: The following error occurred NNNNNN times:
  dsAFEBADPCNTERR -- WARNING: Event island contains 1 or more bad pixels.
  

  since these occurrences are routine and should not be a concern in data analysis.

• A number of warning messages have been upgraded to be more informative.

• The tool has been upgraded to support CALDB4. The changes should be transparent to the user.

Bugs

Caveats

Status bits in the input file are not reset when reprocessing data

When acis_process_events is used to reprocess event data, it does not unset status bits in the input data file. For example, acis_process_events does not recalculate the bad pixel status bits. 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. This limitation will be fixed in a future release.

The exception to this is the VFAINT background cleaning (status bit 23). As of CIAO 4.0, previously set VFAINT status bits are unset before the check is done again.

# acis_process_events (CIAO): The following error occurred 26941 times:
  dsAFEBADPCNTERR -- WARNING: Event island contains 1 or more bad pixels.

This warning is produced whenever a bad pixel file is used and may be safely ignored.

It indicates that one or more of the nine pixels in a 3x3 event island is identified as a bad pixel. The 26,941 events for which this is the case (in this example) have a STATUS bit set to one. These events can be removed from an event file by using dmcopy with status=0, as shown in the ACIS Data Preparation threads.

# acis_process_events (CIAO): WARNING: problem reading ctifile,
  cti adjustment will not be applied. Changing apply_cti=yes to apply_cti=no.

The most common cause for seeing this warning is that the observation does not contain -120C data. Since the CTI correction is primarily calibrated for this focal place temperature, it is not possible to use it on other observations. Note that this is not an error; if no CTI file is found, acis_process_events continues running as if apply_cti=no and produces a valid output file that has not been CTI-corrected.

The CTI Correction why topic has more information on the correction.

# acis_process_events (CIAO): The following error occurred 31 times: 
  dsAPEPULSEHEIGHTERR -- WARNING: pulse height is less than split
  threshold when performing serial CTI adjustment.

When the CTI adjustment is applied to events on the back-illuminated CCDs (ACIS-S1 and S3), sometimes one of the pulse heights in a 3x3 pixel event island can drop below the split threshold if it was above the threshold before the adjustment. In the end, pixels that are below the split threshold are ignored when the total pulse height and energy are computed.

If the number of times is small, then the warning may be safely ignored.

See Also

chandra

eventdef

tools

acis_build_badpix, acis_classify_hotpix, acis_clear_status_bits, acis_detect_afterglow, acis_find_afterglow, acis_find_hotpix, acis_run_hotpix, acis_streak_map, acisreadcorr, destreak