Apply the Time-Dependent ACIS Gain Correction
[CIAO 3.4 Science Threads]
OverviewLast Update: 31 Mar 2008 - updated for CALDB 3.4.3: new -120 C TGAIN files and first -110 C TGAIN file Synopsis: The tool acis_process_events includes a time-dependent gain adjustment. This adjustment is necessary because the "effective gains" of the detectors are drifting with time as the result of an increasing CTI. The correction for this problem became part of standard data processing (SDP) in DS 7.3.1. Purpose: To generate a new level=1 event file with the time-dependent gain adjustment applied. Read this thread if:
Data taken since February 2000 may need to be reprocessed to apply newer TGAIN calibration. Read the Calibration Updates for a history of TGAIN calibration changes. Users interested in CCD spectroscopy should apply the T_GAIN adjustment. Grating spectroscopy may benefit marginally, in the form of improved order sorting. It is not necessary to apply this adjustment if you are only doing timing or imaging analysis, but it will not have a negative effect, either.
Related Links:
|
Contents
- Background Information
- Get Started
- Generate A New Level=1 Event File
- Examining the Output
- Summary
- Parameter files:
- History
Background Information
As of CALDB 3.3.0, there is CTI calibration data for the entire ACIS detector (chips I0-3 and S0-5).
As of CALDB 3.1.0, there is time-dependent gain calibration data for the entire ACIS detector (chips I0-3 and S0-5).
As of CALDB 3.4.3, there is TGAIN correction for the back-illuminated chips at the -110 C focal plane temperature. There is no CTI correction for -110 C data.
When you run acis_process_events with apply_cti=yes and apply_tgain=yes as in this thread, the CTI adjustment is done (if available) and then the time-dependent gain is calibrated.
Get Started
Sample ObsID used: 1838 (ACIS-S, G21.5-09)
File types needed: evt1; flt1; bpix1
If you created a new bad pixel file by running the Create a New ACIS Bad Pixel File: Identify ACIS Hot Pixels and Cosmic Ray Afterglows thread, use that file in this analysis. Otherwise, use the bpix1.fits file from the Archive.
This thread must be run on the level=1 event file, regardless of whether you are working with imaging or grating data. This is because one of the columns generated is PHA_RO, which is the summed value of PHA without the CTI and time-dependent gain adjustments applied.
There are several pieces of information we need to get from the file header before proceeding:
-
Focal plane temperature (FP_TEMP keyword): the gain adjustment only applies to data taken at -120 C (153 K). See this FAQ for more information on checking the temperature of your observation.
-
Observation Date (DATE-OBS keyword): since the gain adjustment is calibrated for several periods since February 2000, it may improve the quality of any observation done after that time.
-
If the CTI correction has been applied (CTI_CORR and/or CTI_APP keyword): the CTI correction may have been applied in SDP or during previous CIAO analysis. The CTI_APP header keyword was added at CIAO 3.4 and DS 7.6.10 (see the ACIS CTI Correction why topic for more information); the older CTI_CORR keyword is retained for backward-compatibility.
-
If the time-dependent gain correction has been applied (TGAINCOR keyword): if this keyword does not exist, the correction has not yet been done. Additionally, if the keyword exists, but has any value other than "T" (TRUE), the correction has not been applied. We can also check the ASCDSVER header keyword to see if the data were processed before or after this correction was added to SDP.
The tool dmkeypar is used to get the header information:
unix% dmkeypar acisf01838_000N001_evt1.fits FP_TEMP echo+ 153.446014 unix% dmkeypar acisf01838_000N001_evt1.fits DATE-OBS echo+ 2000-09-02T01:10:14 unix% dmkeypar acisf01838_000N001_evt1.fits TGAINCOR echo+ # dmkeypar (CIAO 3.4): ERROR: Keyword 'TGAINCOR' was not found in file 'acisf01838_000N001_evt1.fits'. unix% dmkeypar acisf01838_000N001_evt1.fits CTI_CORR echo+ # dmkeypar (CIAO 3.4): ERROR: Keyword 'CTI_CORR' was not found in file 'acisf01838_000N001_evt1.fits'. unix% dmkeypar acisf01838_000N001_evt1.fits CTI_APP echo+ # dmkeypar (CIAO 3.4): ERROR: Keyword 'CTI_APP' was not found in file 'acisf01838_000N001_evt1.fits'. unix% dmkeypar acisf01838_000N001_evt1.fits ASCDSVER echo+ R4CU5UPD8.2
This is a -120 C observation taken in September 2000 that has not had the time-dependent gain or CTI corrections applied to it already. Also, this observation was processed before the TGAIN correction became part of SDP, i.e. the ASCDSVER is lower than DS 7.3.0. Note that the version naming convention changed after version R4CU5UPD14 to the "DS" system, starting with DS 6.0.0.
In many cases, the TGAIN calibration has been applied to the data, but the data should still be reprocessed to apply a newer version of the calibration. Refer to the Calibration Updates for a history of TGAIN calibration changes and the relevant observation dates.
Note that although the adjustment is currently only applicable to -120 C data, there are no adverse effects to running it on other data (the outcome is the same as if apply_tgain=no).
Related acis_process_events threads
There are other threads that should be considered, since they may affect how acis_process_events is run. The Create a New Level=2 Event File thread shows how to combine all of these options into a single run of acis_process_events.
Generate A New Level=1 Event File
Determine the eventdef parameter
The eventdef parameter specifies the names and data types of the columns in the output event data file. Four predefined strings are included in the parameter file for acis_process_events:
READMODE | DATAMODE | event mode | eventdef string |
---|---|---|---|
TIMED | (V)FAINT | timed exposure (very) faint | stdlev1 |
TIMED | GRADED | timed exposure graded | grdlev1 |
CONTINUOUS | CC(33)_FAINT | continuous clocking (3x3) faint | cclev1 |
CONTINUOUS | CC(33)_GRADED | continuous clocking (3x3) graded | ccgrdlev1 |
If you are unsure of the event mode of your observation, the information can be found in the READMODE and DATAMODE values stored in the file header:
unix% dmkeypar acisf01838_000N001_evt1.fits READMODE echo+ TIMED unix% dmkeypar acisf01838_000N001_evt1.fits DATAMODE echo+ FAINT
This is a timed exposure faint observation, so the proper eventdef parameter is "stdlev1." The full parameter syntax of each eventdef string may be found in plist acis_process_events.
Run acis_process_events
Running this tool with the SDP level=1 event file as the input will produce a new level=1 event file that has the latest CALDB applied. This means that the time-dependent gain correction will be applied.
The apply_cti parameter should always be set to yes, even if the data is already CTI-corrected. If it is set to no, the existing CTI correction is removed; see the note on reapplying the CTI correction for details.
unix% punlearn acis_process_events unix% pset acis_process_events infile=acisf01838_000N001_evt1.fits unix% pset acis_process_events outfile=acis_1838_new_evt1.fits unix% pset acis_process_events badpixfile=acis_1838_new_bpix1.fits unix% pset acis_process_events eventdef=")stdlev1" unix% pset acis_process_events stop=none unix% pset acis_process_events apply_tgain=yes unix% pset acis_process_events apply_cti=yes unix% acis_process_events Input event file or stack (acisf01838_000N001_evt1.fits): Output event file name (acis_1838_new_evt1.fits): aspect offset file ( NONE | none | <filename>) (NONE):
The apply_tgain and apply_cti parameters are both "on" by default (i.e. set to "yes"); the pset commands are used for emphasis in this example.
It is important to note the unusual syntax of the eventdef parameter; the tool will not access the predefined string if the leading ")" is missing (see example 6 of ahelp parameter).
The content of the parameter file may be checked using plist acis_process_events.
You may see a warning about the number of event islands that contain one or more bad pixels:
# acis_process_events (CIAO 3.4): The following error occurred 26941 times: dsAFEBADPCNTERR -- WARNING: Event island contains 1 or more bad pixels.
It is explained in this FAQ and may be ignored.
Examining the Output
There are a few things that may be checked in order to confirm that the gain adjustment was applied. First, two new header keywords - TGAINCOR and TGAINFIL - have been created:
unix% dmlist acis_1838_new_evt1.fits header | grep TGAIN 0078 TGAINCOR T String 0123 TGAINFIL acisD2000-08-01t_gainN0006.fits String
TGAINCOR is set to "T" for true. In the TGAINFIL case, the path to the CALDB is /soft/ciao/CALDB. If either of these keywords is missing or set to a different value ("F" or "none"), the gain adjustment was not applied.
Also, a PHA_RO column should exist in the output file and contain non-zero values:
unix% dmlist acis_1838_new_evt1.fits"[cols PHA_RO]" data rows="1:5" -------------------------------------------------------------------------------- Data for Table Block EVENTS -------------------------------------------------------------------------------- ROW pha_ro 1 249 2 273 3 138 4 2445 5 3660
It is recommended that you keep this column in your data file (i.e. do not use a DM filter to remove it). These are the original (RO = readout) PHA values which are needed if you later want to rerun with new calibration.
Summary
This thread is now complete; the new level=1 event file is named acis_1838_new_evt1.fits. See the final section of the ACIS Gain Map thread to generate a new level=2 event file.
Parameters for /home/username/cxcds_param/acis_process_events.par #-------------------------------------------------------------------------- # # acis_process_events.par- Parameter file for acis_process_events program # #-------------------------------------------------------------------------- infile = acisf01838_000N001_evt1.fits Input event file or stack outfile = acis_1838_new_evt1.fits Output event file name acaofffile = NONE aspect offset file ( NONE | none | <filename>) (apply_cti = yes) Apply CTI adjustment? (apply_tgain = yes) Apply time-dependent gain adjustment? (alignmentfile = )acaofffile -> NONE) sim/fam alignment file ( NONE | none | <filename>) (obsfile = NONE) obs.par file for output file keywords ( NONE | none | <filename>) (geompar = geom) Parameter file for Pixlib Geometry files (logfile = stdout) debug log file ( STDOUT | stdout | <filename>) (gradefile = CALDB) grade mapping file ( NONE | none | CALDB | <filename>) (gainfile = CALDB) acis gain file ( NONE | none | CALDB | <filename>) (badpixfile = acis_1838_new_bpix1.fits) acis bad pixel file ( NONE | none | <filename>) (threshfile = CALDB) split threshold file ( NONE | none | CALDB | <filename>) (ctifile = CALDB) acis CTI file ( NONE | none | CALDB | <filename>) (tgainfile = CALDB) gain adjustment file ( NONE | none | CALDB | <filename>) (eventdef = )stdlev1 -> {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}) output format definition (doevtgrade = yes) Determine event flight grade? (check_vf_pha = no) Check very faint pixels? (calc_cc_times = no) Estimate the times of arrival for CC-mode observation? (trail = 0.027) Trail fraction (spthresh = 13) Default split threshold level (overridden by values in threshfile) (time_offset = 0) Offset to add to event time field to synch w/ fam data (docentroid = no) Determine pixel centroid for coord. conversion? (calculate_pi = yes) perform pha->pi conversion? (requires gain file) (pi_bin_width = 14.6) Width of Pi bin in eV (pi_num_bins = 1024) Number of values to bin energy into (max_cti_iter = 15) Maximum iterations for the CTI adjustment of each event (cti_converge = 0.1) The convergence criterion for each CTI-adjusted pixel in adu (tstart = TSTART) header key containing start/default time value (tstop = TSTOP) header key containing time of last event (clobber = no) Overwrite output event file if it already exists? (verbose = 0) level of debug detail (0=none, 5=most) (stop = none) where to end transformations (instrume = acis) axaf instrument- used for instrument parameter file (rand_seed = 1) random seed (for pixlib), 0 = use time dependent seed (rand_pha = yes) Randomize the pha value used in gain calculations (rand_pix_size = 0.5) pixel randomization width (-size..+size) 0=no randomization (stdlev1 = {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}) TE faint modes event definition string (grdlev1 = {d:time,s:ccd_id,s:node_id,i:expno,s:chip,s:tdet,f:det,f:sky,l:pha,s:corn_pha,f:energy,l:pi, s:fltgrade,s:grade,x:status}) TE graded event format definition string (cclev1 = {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}) CC faint event format definition string (ccgrdlev1 = {d:time,s:ccd_id,s:node_id,i:expno,s:chip,s:tdet,f:det,f:sky,f:sky_1d,l:pha,f:energy,l:pi, s:fltgrade,s:grade,x:status}) cc graded event format definition string (mode = ql) |
History
16 Dec 2004 | updated for CIAO 3.2; use ACIS bad pixel file (badpixfile parameter) |
01 Feb 2005 | added note about "Event island contains 1 or more bad pixels" warning |
23 Jun 2005 | CIAO 3.2.2 patch: new calibration files in CALDB 3.1.0; minor acis_process_events parameter change (default value of threshfile is CALDB instead of NONE) |
12 Dec 2005 | updated for CIAO 3.3: new time-dependent gain files in CALDB 3.2.0; output filenames include ObsID |
14 Jun 2006 | update to calibration info: new TGAIN files released in CALDB 3.2.2 |
07 Nov 2006 | update to calibration info: new TGAIN files released in CALDB 3.2.4 |
18 Dec 2006 | updated for CIAO 3.4: new calibration files in CALDB 3.3.0; include CTI_APP in keyword checks; removed use of "rand_pha=no" in acis_process_events, as most users should keep the PHA randomization (see the Apply/Remove PHA Randomization thread); CIAO version in errors |
01 May 2007 | updated for CALDB 3.4.0: TGAIN files for August 2006 - April 2007 |
21 May 2007 | need to set stop=none if aspect solution is not provided |
14 Sep 2007 | updated for CALDB 3.4.1: TGAIN files for May 2007 - July 2007 |
14 Dec 2007 | updated for CALDB 3.4.2: TGAIN files for August 2007 - October 2007 |
31 Mar 2008 | updated for CALDB 3.4.3: new -120 C TGAIN files and first -110 C TGAIN file |