About Chandra Archive Proposer Instruments & Calibration Newsletters Data Analysis HelpDesk Calibration Database NASA Archives & Centers Chandra Science Links

Skip the navigation links
Last modified: 31 Mar 2008
Hardcopy (PDF): A4 | Letter

Apply the Time-Dependent ACIS Gain Correction

[CIAO 3.4 Science Threads]



Overview

Last 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:

  • you are working with a -120 C ACIS observation (imaging or grating) that took place after February 2000; see the Background Information section for details. Get Started shows how to check the temperature of your observation.

  • you are working with a -110 C ACIS observation (imaging or grating) which uses the back-illuminated chips (ACIS-S1 and S3).

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.

Calibration Updates:

  • CALDB v3.4.3 (31 Mar 2008): New time-dependent gain calibration files for 01 November 2007 - 31 January 2008 (Epoch 32) were added to the CALDB. A TGAIN correction for the back-illuminated chips (S1 and S3) at the -110 C focal plane temperature has also been released for the first time. The CALDB 3.4.3 section of the CIAO release notes explains how the files will affect your analysis.
  • CALDB v3.4.2 (14 Dec 2007): New time-dependent gain calibration files for 01 August 2007 - 31 December 2007 (Epoch 31) were added to the CALDB. The CALDB 3.4.2 section of the CIAO release notes explains how the files will affect your analysis.
  • CALDB v3.4.1 (14 Sep 2007): New time-dependent gain calibration files for 01 May 2007 - 31 July 2007 (Epoch 30) were added to the CALDB. The CALDB 3.4.1 section of the CIAO release notes explains how the files will affect your analysis.
  • CALDB v3.4.0 (16 May 2007): New time-dependent gain calibration files for 01 August 2006 - 31 October 2006 (Epoch 28) and 01 February 2007 - 30 April 2007 (Epoch 29) were added to the CALDB. The CALDB 3.4.0 section of the CIAO release notes explains how the files will affect your analysis.
  • CALDB v3.3.0 (18 Dec 2006): New time-dependent gain calibration files were added to the CALDB. Only calibration for the BI chips (S1, S3) has changed in this file; calibration for the FI chips is identical to the v5 file. The How CIAO 3.4 and CALDB 3.3.0 Affect Your Analysis section of the CIAO release notes explains how the files will affect your analysis.
  • CALDB v3.2.4 (7 Nov 2006): New time-dependent gain calibration files for February-April 2006 (Epoch 25) and May-August 2006 (Epoch 26) were added to the CALDB. Three existing TGAIN files were updated as well; the How CALDB 3.2.4 Affects Your Analysis section of the CIAO release notes explains how the files will affect your analysis.
  • CALDB v3.2.2 (15 May 2006): New time-dependent gain calibration files for May to November 2005 (epochs 23 and 24) were added to the CALDB.
  • CALDB v3.2.0 (21 Nov 2005): New higher-spatial density T_GAIN corrections for all ACIS chips were released. The CIAO 3.3 release notes explain how they will affect your analysis.
  • CALDB v3.1.0 (23 Jun 2005): New time-dependent gain calibration files for August to November 2004 (epoch 20) were added to the CALDB. These files include calibration for the S0, S4, and S5 ACIS chips; prior to this release, an adjustment for those chips was unavailable.
  • CALDB v2.29 (19 Nov 2004): New time-dependent gain calibration files for February, May, and August 2004 (epochs 18 and 19) were added to the CALDB.
  • CALDB v2.27 (7 Jul 2004): The calibration files necessary to apply the time-dependent gain correction were released.

Related Links:

Proceed to the HTML or hardcopy (PDF: A4 | letter) version of the thread.




Contents



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

Return to Threads Page: Top | All | Data Prep
Hardcopy (PDF): A4 | Letter
Last modified: 31 Mar 2008


The Chandra X-Ray Center (CXC) is operated for NASA by the Smithsonian Astrophysical Observatory.
60 Garden Street, Cambridge, MA 02138 USA.    Email: cxcweb@head.cfa.harvard.edu
Smithsonian Institution, Copyright © 1998-2004. All rights reserved.