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] [obsfile] [geompar] [logfile] [gradefile]
[grade_image_file] [gainfile] [badpixfile] [threshfile] [ctifile]
[tgainfile] [mtlfile] [eventdef] [doevtgrade] [check_vf_pha] [trail]
[calculate_pi] [pi_bin_width] [pi_num_bins] [max_cti_iter]
[cti_converge] [clobber] [verbose] [stop] [rand_seed] [rand_pha]
[pix_adj] [subpixfile] [stdlev1] [grdlev1] [cclev1] [cclev1a]
[ccgrdlev1] [ccgrdlev1a]

Description

acis_process_events is part of the standard Level 1 and Level 1.5 processing pipelines. The tool is also available in CIAO so that it can be used to update an existing ACIS event 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 STATUS bits. For example, the tool can be used to apply or remove a sub-pixel coordinate adjustment, 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 in the output file. acis_process_events has many parameters, most of which may be ignored. 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.

Examples

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). Note that CHIPX_ADJ and CHIPY_ADJ are used internally, but not written to the outfile by default because they are not listed in the default value of the parameter eventdef.

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

Example 3

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 gainfile used is written to the keyword GAINFILE. The recomputation of the coordinates, FLTGRADE, and GRADE is disabled (stop=none and doevtgrade=no).

Example 4

acis_process_events acisf00016_000N002_evt1.fits
acisf00016_995N002_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 (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 5

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 badpixfile 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 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 (e.g. TIME, CCD_ID, EXPNO, CHIPX, and CHIPY), then they should be columns read from the infile. 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 is produced.

Parameter=outfile (file required filetype=output)

Name of the output ACIS event 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(s) of the input aspect solution file(s) used to compute the sky coordinates X and Y. If the acaofffile(s) is not specified, then the coordinates (and the TIMEs for continuous-clocking mode) will be inaccurate. If more than one acaofffile 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 RA, DEC, and ROLL. These columns describe pointing direction and roll of the aspect camera. The ACIS data product pcadf*asol1.fits file is recommended. The name(s) of the acaofffile(s) used is written to the keyword ASOLFILE.

Parameter=apply_cti (boolean default=yes)

If apply_cti=yes, then the pulse-height data 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 pulse-height data, it is not possible to apply multiple adjustments. If the infile was CTI adjusted, then the adjusted values are discarded and recomputed.

For non-graded mode observations (e.g. CC33_FAINT, FAINT, or VFAINT mode), the computation, which requires a ctifile, involves an iterative estimate of the amount and the distribution of the charge that is deposited in the detector based on the amount and the distribution of charge that reaches the read out electronics (i.e. upon the values of PHAS). The estimate depends upon the location at which the charge was deposited and the temperature of the detector (see the parameter mtlfile). The process ends when the maximum number of iterations is reached or when the change in the amount of charge in each pixel of a 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 eventdef includes "f:phas_adj", then the values of PHAS_ADJ are written to the output file. By default, these values are not included.

For graded mode observations (e.g. CC33_GRADED or GRADED), the computation, which requires a grade_image_file, is similar to the non-graded mode algorithm. However, since the values of PHAS are not available, the initial pulse-height distribution of an event is based upon the FLTGRADE of the event. The adjustment is performed only for events that have FLTGRADEs of 2, 8, 10, 11, 16, 18, 22, 64, 72, 80, 104, or 208 (i.e. for a subset of the events with good GRADEs) and only for the parallel CTI on front-illuminated CCDs. No adjustment is performed for the back-illuminated CCDs. Instead of computing PHAS_ADJ and using these values to determine the CTI-adjusted value of PHA, the CTI-adjustment is applied directly to the value of PHA.

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.

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-height data (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. The size of the adjustment is a function of the time, location and pulse-height of an event. If the time-dependent gain adjustment is applied, then the CTI-adjustment should also be applied (apply_cti=yes), if possible, since the time-dependent gain is calibrated using CTI-adjusted data. 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=yes, then the keyword TGAINCOR=T. If apply_tgain=no or tgainfile=none, then the output pulse heights do not include the effects of a time-dependent gain adjustment (even if one had been applied), and TGAINCOR=F. 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).

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

This parameter specifies the name of an input observation parameter file (e.g. axaff*obs0a.par). 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, Level 1.5, or Level 2 ACIS event file (i.e. 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 files used to compute the coordinates TDETX, TDETY, DETX, DETY, X, and Y (and SKY_1D for continuous-clocking mode data). The default setting yields the latest set of files in the calibration database that are associated with the infile. For those interested in using some other set of files, the default file geom.par can be copied to custom_geom.par and edited accordingly. In this case, the parameter geompar=custom_geom. Alternatively, one may use, for example, the following command before executing acis_process_events.

   unix% pset geom instruments="./telD1999-07-23geomN0005.fits"

The names of the files used are written to the keywords AIMPFILE, GEOMFILE, SHELLFIL, SKYFILE, and TDETFILE.

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 and extension of the input file used to determine the values of GRADE from the values of FLTGRADE. If gradefile=CALDB, then the latest gradefile in the calibration database that is associated with the infile is used. 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 ACIS calibration products are based on data that have GRADE = 0, 2, 3, 4, or 6 (i.e. the "good" grades) for a specific mapping of FLTGRADE to GRADE. Therefore, custom gradefiles should be used cautiously. The name of the gradefile used is written to the keyword GRD_FILE.

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

This parameter specifies the name of the input file used to perform a CTI adjustment for a graded mode observation (i.e. CC33_GRADED or GRADED). If grade_image_file=CALDB, then the latest file in the calibration database that is associated with the infile is used. The name of the grade_image_file used is written to the keyword GRDIMGFL.

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 gainfile in the calibration database that is associated with the infile is used. The computation of ENERGY is performed only if the parameter calculate_pi=yes. If the infile is a Level 1, Level 1.5, or Level 2 ACIS event file (acisf*_evt1.fits, acisf*_evt1a.fits, or acisf*_evt2.fits) and if 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, some of the STATUS bits should be unset before executing acis_process_events. See the ahelp file for acis_clear_status_bits. Detailed descriptions of the meanings of the bad-pixel and event 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." If threshold=CALDB, then the latest file in the calibration database that is associated with the infile is used. The thresholds are typically 13 adu for events on back-illuminated CCDs and for timed-exposure mode events on front-illuminated CCDs. They are typically 16 adu for continuous-clocking mode events on front-illuminated CCDs. The split threshold is used during the computation of the values of FLTGRADE and PHA. Since the ACIS calibration products are based on data obtained using a specific set of split thresholds, custom threshfiles should be used cautiously. The name of the threshfile used is written to the keyword THRFILE.

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

This parameter specifies the name of the input file used to perform a CTI adjustment for non-graded mode observations (e.g. CC33_FAINT, FAINT, or VFAINT). If ctifile=CALDB, then the latest file in the calibration database that is associated with the infile is used. The name of the ctifile used is written 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). For example, CTI_APP=PPPPPBPBPP indicates that only a parallel CTI adjustment is performed for events on the front-illuminated CCDs, but both parallel and serial CTI adjustments are performed for events on the back-illuminated CCDs. If the CTI adjustment is not performed, then CTI_APP=NNNNNNNNNN.

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

This parameter specifies the name of the input file used to perform a time-dependent gain adjustment. If tgainfile=CALDB, then the latest file in the calibration database that is associated with the infile is used. The name of the tgainfile used is written to the keyword TGAINFIL.

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 mtlfile=NONE and a CTI adjustment is performed, then the adjustment will not include a temperature dependence and may be inaccurate. The name of the mtlfile used is written to the keyword MTLFILE.

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,... 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 (for continuous-clocking observations), EXPNO, CCD_ID, NODE_ID, CHIPX, CHIPY, CHIPX_ADJ, CHIPY_ADJ, CHIPY_TG (for observations using the gratings), CHIPY_ZO (for observations using the gratings), 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.

As described below, some pre-defined sets of eventdef strings are included in the parameter file: stdlev1, grdlev1, cclev1, cclev1a, ccgrdlev1, and ccgrdlev1a. 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 "f:chip_adj" is added to the eventdef. Likewise, if the CTI adjustment is performed, then the column PHAS_ADJ is not included in the outfile unless "f:phas_adj" is added to 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)

This parameter determines whether or not events are evaluated to determine if they may be potential cosmic-ray background events. The algorithm may only be used for VFAINT mode data. It was designed for analyses of extended sources, not point sources. If check_vf_pha=yes, then the pulse heights of the outer sixteen pixels of a 5 pixel x 5 pixel event island are compared to event-specific thresholds (see the parameter trail). If one or more of the sixteen pulse heights are greater than the corresponding threshold, then STATUS bit 23 (of 0-31) is set to one to indicate that the event may have been produced by a cosmic ray instead of an X-ray. 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, this algorithm may misidentify a significant fraction of the source events as potential cosmic-ray events. There is a Why document here that includes a description of how to determine if the algorithm removes a significant fraction of the source events.

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 split threshold plus the specified portion of trailed charge. For the other pixels around the outside edge of the event island, the threshold is just the split threshold.

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 may be computed (see the parameter doevtgrade). The value of PI is given by

   PI = int(ENERGY/pi_bin_width) + 1,

where the function int truncates (i.e. rounds down) the number in parenthesis to an integer.

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

If the value of PI is computed (see the parameter calculate_pi), 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 eV, 14.6 <= ENERGY < 29.2 eV, ... have PI = 1, 2, ...

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

If the value of PI is computed (see the parameter calculate_pi), then the parameter pi_num_bins determines the largest valid value of PI. The smallest valid value of PI is always one. For example, if pi_num_bins=1024, pi_bin_width=14.6, and the ENERGY >= 14950.4 eV, then PI=1024.

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

If a non-graded mode CTI adjustment is performed (see the parameter apply_cti), then this parameter determines the maximum number of iterations that can be performed for an event. If the adjustment has not converged after max_cti_iter iterations (see the parameter cti_converge), then the latest set of adjusted pulse heights are the values used for PHAS_ADJ for the event 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)

If a non-graded mode CTI adjustment is performed (see the parameter apply_cti), then this parameter specifies the convergence criterion. The adjustment is iterated until the change in the value of the adjusted pulse height is less than cti_converge, in adu, for every pixel in a 3 pixel x 3 pixel event island or until the maximum number of iterations is reached, whichever occurs first.

Parameter=clobber (boolean default=no)

This parameter determines whether or not an existing outfile should be overwritten. 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, if any, 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, Y, and SKY_1D (for continuous-clocking mode) are recomputed.

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 as part of the time-dependent gain adjustment (see the parameter apply_tgain). In this case, a uniform random deviate in the range [0, +1) adu is added to the real-valued, time-dependent, gain-adjusted pulse height PHA before the value of PHA is truncated (i.e. rounded down) to an integer.

A separate randomization is performed if the values of ENERGY and PI are computed (see the parameter calculate_pi). In this case, a uniform random deviate in the range [-0.5, +0.5) adu is added to the values of PHA before the ENERGY is calculated. Since the values of ENERGY are used to compute the values of PI, and since the number of PHA bins per PI bin is not a constant, this pulse-height randomization removes certain aliasing effects that would otherwise be obvious in the PI spectra of bright sources.

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)

This parameter determines which sub-pixel adjustment, if any, is used. If stop=sky, 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 CC33_FAINT, CC33_GRADED, FAINT, FAINT_BIAS, GRADED, and VFAINT 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 valid 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 if a CTI adjustment is not performed or upon PHAS_ADJ if a CTI adjustment is performed). The keywords PIX_ADJ and RAND_SKY are set to CENTROID and 0, respectively. Since this algorithm is similar to the algorithm that was used for docentroid=yes, the parameter docentroid is no longer available. The algorithm CENTROID can be used for CC33_FAINT, FAINT, FAINT_BIAS, and VFAINT mode observations.

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. The algorithm RANDOMIZE can be used for 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". The values of CHIPX_ADJ and CHIPY_ADJ are used to compute the values of the coordinates DETX, DETY, X, and Y. For continuous-clocking mode observations, the coordinate CHIPY_ADJ is used to determine the TIME of arrival of an event (i.e. The TIME is adjusted or randomized).

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 (see the parameter pix_adj). If subpixfile=CALDB, then the latest file in the calibration database that is associated with the infile is used. The name of the subpixfile used is written to the keyword SUBPIXFL.

Parameter=stdlev1 (string)

This string is one of the pre-defined eventdefs. It includes a set of column names and data types that is appropriate for Level 1 FAINT and VFAINT mode data sets. Using eventdef=")stdlev1" is equivalent to eventdef="{d:time,l:expno,s:ccd_id,s:node_id,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 the pre-defined eventdefs. It includes a set of column names and data types that is appropriate for Level 1 GRADED mode data sets. Using eventdef=")grdlev1" is equivalent to eventdef="{d:time,l:expno,s:ccd_id,s:node_id,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 the pre-defined eventdefs. It includes a set of column names and data types that is appropriate for Level 1 CC33_FAINT mode data sets. Using eventdef=")cclev1" is equivalent to eventdef="{d:time,d:time_ro,l:expno,s:ccd_id,s:node_id,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=cclev1a (string)

This string is one of the pre-defined eventdefs. It includes a set of column names and data types that is appropriate for Level 1.5 CC33_FAINT mode data sets. Using eventdef=")cclev1a" is equivalent to eventdef="{d:time,d:time_ro,l:expno,s:ccd_id,s:node_id,s:chip, f:chipy_tg,f:chipy_zo,s:tdet,f:det,f:sky,f:sky_1d,s:phas,l:pha, l:pha_ro,f:energy,l:pi,s:fltgrade,s:grade,f:rd,s:tg_m,f:tg_lam, f:tg_mlam,s:tg_srcid,s:tg_part,s:tg_smap,x:status}".

Parameter=ccgrdlev1 (string)

This string is one of the pre-defined eventdefs. It includes a set of column names and data types that is appropriate for Level 1 CC33_GRADED mode data sets. Using eventdef=")ccgrdlev1" is equivalent to eventdef="{d:time,d:time_ro,l:expno,s:ccd_id, s:node_id,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}".

Parameter=ccgrdlev1a (string)

This string is one of the pre-defined eventdefs. It includes a set of column names and data types that is appropriate for Level 1.5 CC33_GRADED mode data sets. Using eventdef=")ccgrdlev1a" is equivalent to eventdef="{d:time,d:time_ro,l:expno,s:ccd_id, s:node_id,s:chip,f:chipy_tg,f:chipy_zo,s:tdet,f:det,f:sky,f:sky_1d, l:pha,l:pha_ro,s:corn_pha,f:energy,l:pi,s:fltgrade,s:grade,f:rd, s:tg_m,f:tg_lam,f:tg_mlam,s:tg_srcid,s:tg_part,s:tg_smap,x:status}".

Changes in CIAO 4.17

• New CTI_TMAP keyword has been added to identify which CTI correction algorithm was applied.

• Fix for memory problem causing fatal crash on macOS Sequoia.

Bugs

using s:pha in the eventdef parameter broken

The default eventdef parameters store the PHA value as a long (32bit) integer. However, if a user changes it to a short (16bit) integer, ie s:pha the values will be stored properly; however, the TLMAX (maximum allowed value) used to describe the column values will exceed the range allowed by a short integer; causing the value to "wrap" meaning the max will be less than the min. Users should not use s:pha in the eventdef, (eg to try to save space).

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.

WARNING: problem reading ctifile, cti adjustment will not be applied. Changing apply_cti=yes to apply_cti=no.

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

dsAPEPULSEHEIGHTERR -- WARNING: pulse height is less than split threshold when performing serial CTI adjustment.

# 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

acis_build_badpix, acis_check_pha_range, acis_clear_status_bits, acis_detect_afterglow, acis_find_afterglow, acis_streak_map, acisreadcorr, destreak

tools::background

readout_bkg