OUR CTI CORRECTOR TOOL HAS BEEN RETIRED.
We recommend using CIAO-derived event data and CIAO-derived response files.
PSB and LKT, 2008

ACIS CTI CORRECTION SOFTWARE and DATA PRODUCTS

Leisa Townsley and Patrick Broos
Penn State University
 

INSTALLATION OF IDL SOFTWARE

The CTI corrector code uses a number of routines from our TARA package, so you must first install that.  You must have IDL 5.4 and Wayne Landsman's IDL Astro Library (Jan 2001 or later).

Make a directory for the corrector code in an appropriate place and download the  gzipped tar file containing the CTI corrector code itself (as well as the PSU Monte Carlo CCD simulator code, as an added bonus).   Unzip and untar the tarball, e.g.
   gunzip corrector1.38.tar.gz
   tar -xvf corrector1.38.tar

Arrange for the corrector directory to be at the head of your IDL path.  The procedure for doing this may depend on how your IDL site is administered.  If you have a personal IDL startup file you could put a statement similar to this in it:

  !PATH = '+/home/my_computer/my_user_id/idl/corrector:+/home/my_computer/my_user_id/idl/tara:' + !PATH

(The various parameter files used by the corrector must stay with the .pro files.)

The IDL program correct_cti.pro is the entry point to the IDL corrector system.  However a shell script named "correctit" is also supplied to call the IDL software and to massage the output into a CIAO-compatible form.
 

INSTALLATION OF "CORRECTIT" SHELL SCRIPT

The script "correctit" uses several CIAO tools (dmcopy, dmhedit, etc.) so you must have CIAO installed. 

Make sure you have execute permission on the script:

   chmod a+x correctit

Determine the path to the shell "csh" on your computer by executing:

  which csh

If necessary, change the first line of the "correctit" script to match that path.
{FYI,  the  script specifies the option "e" to csh so that it will exit if any command returns an error, eliminating subsequent extraneous error messages.  The "f" option is also specified so that csh will not read your .cshrc configuration file -- we've found that many users' .cshrc files contain errors which cause scripts run with the "e" option to abort.}

Unfortunately the CTI corrector package must contain a little C program named "insert_table_columns.c" which is used to overwrite the data in the FITS columns recomputed by the corrector.  Executable forms of this program are distributed for the Solaris (Sun), Linux, and OS-X (Mac) operating systems under the names insert_table_columns_sunos, insert_table_columns_linux, & insert_table_columns_darwin.  Rename the appropriate binary and make sure you have execute permission on it: 

    mv insert_table_columns_darwin insert_table_columns
    chmod a+x insert_table_columns

Finally, either arrange for insert_table_columns to be in your shell's PATH, or edit the "correctit" script (near the bottom) to specify an explicit path to insert_table_columns.

If you end up using this software, send some email to Leisa Townsley and we'll try to notify you when revisions are made.
 

USAGE

Widen your terminal window; some messages are more than 80 characters.

The CTI corrector must be run on ACIS LEVEL 1 event files, not on Level 2 files, because the L2 processing applies a g02346 ASCA grade filter.  The corrector will handle 3x3 ("faint") and 5x5 ("very faint") mode data; in 5x5 mode only the central 9 pixels are retained.

CTI is temperature-dependent, thus the corrector must know the focal plane temperature of your data.  It defaults to -120C, which is appropriate for most observations obtained since 29 January 2000.  It also works at -110C, appropriate for most observations obtained from late August 1999 to 29 January 2000.

To run the corrector on a Level 1 event file named "acisf00001_001N001_evt1.fits" that had a focal plane temperature of -120C, execute the unix command:

 correctit acisf00001_001N001_evt1.fits
Any options you'd like to pass on to the IDL program correct_cti.pro can be supplied (in IDL syntax) as an optional second parameter (with a leading comma).  For example, if your dataset had a focal plane temperature of -110C, you would say:
 correctit acisf00001_001N001_evt1.fits   ",TEMPERATURE=-110"


You must of course see to it that your unix shell can find the script "correctit", either by specifying its full path in the command or by placing it in a directory that's in your unix path.

The code WILL CRASH if you give it an event list that contains events on ACIS CCDs that are not supported.  The supported devices are I0, I1, I2, I3, S2, and S3, both at -110C and -120.  If you have data on other devices, use the CIAO tool dmcopy to filter the event list by device to keep only valid CCDs.

The IDL FITS I/O routines used by this package require reading the entire event list into memory, correcting it, then writing it out.  For an L1 event list with N events you'll need approximately 370*N bytes of free memory on your computer.  If you run out of memory, the  correct_cti.log file should have an error message saying that IDL was unable to allocate a data structure.  If this occurs you have two choices: find a bigger computer or split your event list into pieces.
 

CORRECTOR OUTPUT

The correctit command above produces the following files in the current directory.

correct_cti.log: The  messages produced by the IDL program correct_cti.pro.

acisf00001_001N001_evt1.recalc.fits: This event list is written by the IDL program correct_cti.pro and contains revised values for the L1 columns PHAS, PHA, ENERGY, PI, FLTGRADE, & GRADE.  The column PI is defined as ENERGY/14.6; we cannot guarantee this is the same definition used by the CXC.  The original columns CCD_ID, NODE_ID, CHIPX, CHIPY, & STATUS are copied to this file for convenience during development of the software.  The original PHA column is retained under the new name RAW_PHA for convenient comparison with the revised values.

Note that grade 5 & 7 events will often show a large difference between PHA (revised) and RAW_PHA.  This is sometimes not due to CTI effects but is instead due to differences in the PHAS->PHA algorithm used by PSU's TARA system and by the CXC L1 pipeline.  TARA uses the algorithm specified for the ACIS flight software (which needs to compute PHA for filtering and for Graded Mode telemetry); the CXC pipeline normally uses the ASCA algorithm.

acisf00001_001N001_evt1.no_cti.fits: This event list is constructed by copying the input event list and then replacing the data for columns PHA, ENERGY, PI, FLTGRADE, & GRADE with the values in the .recalc file.  The PHAS column (the event island) is removed because it was too difficult to stuff the recalc file's PHAS column, which is always 9 pixels wide, into the L1 event file's PHAS column, which is sometimes 25 pixels wide.  Since the original CXC FITS headers, GTI tables, etc. are not touched this file should be compatible with all CXC tools.  Note however that the TLMIN & TLMAX for the modified columns are not recomputed and may be somewhat inaccurate.
 

RESPONSE MATRICES AND QEU FILES

We provide PI RMFs and QEU files for the supported devices at both -110C and -120C, again as a gzipped tarfile (CTI_products.tar.gz).  These apply to all four amplifiers on each CCD, so only PI (not PHA) matrices are sensible.  Obviously, they are only for use with CTI-corrected data.  You must include this new QEU file in your ardlib.par in order for mkarf to use it when generating the ARF file for your target.  Since the ARF contains information on the telescope vignetting as well as CCD characteristics, you still have to generate an ARF for each source in the field (even if you're working on S3 and can use a single RMF). See the README file packaged with the data products for important details and instructions.

There are two sets of files, one for -110C and one for -120C.  Don't mix them up!

The following PI RMFs are provided for each device (example here is I0):

ccd0.rmf   (the full-CCD RMF)
ccd0_y1-128.rmf
ccd0_y129-256.rmf
ccd0_y257-384.rmf
ccd0_y385-512.rmf
ccd0_y513-640.rmf
ccd0_y641-768.rmf
ccd0_y769-896.rmf
ccd0_y897-1024.rmf

There is also a QEU file:
ccd0_120.qeu.

For I3, we also provide a 64-row-averaged RMF for the I-array aimpoint, called ccd3_y918-982.rmf.

These all assume ASCA g02346 grade filtering applied AFTER CTI correction.