This software corrects for the time-dependent gain in ACIS CCDs I0-I3, S1,
S2, and S3.

For full documentation, please see
http://hea-www.harvard.edu/~alexey/acis/tgain

************************************************************
COMPILLATION:

apply_gain.c should be compiled with the CFITSIO library. Edit Makefile to
update the paths to CFITSIO for your system, then 'make'.

************************************************************
USAGE:

1.  SAVE YOUR DATA if needed.

cp evt2.fits evt2-save.fits

Note that by default, apply_gain will not change the PHA column in the
events file. It only computes the corrected PI and ENERGY values. Therefore,
you can run gain corrections on your file many times. However, if you want
to modify the PHA column as well, SAVE YOUR DATA AND RUN corr_tgain ONLY
ONCE!

2. FIND OUT THE OBSERVATION DATE:

 dmkeypar evt2.fits DATE-OBS ; pget dmkeypar value

 2002-02-05T22:41:52

3. SELECT THE APPROPRIATE CALIBRATION file and apply correction. The
calibration files provided with corr_tgain use the CALDB naming scheme - the
date in the file name shows when the dataset becomes valid:

% ls corrgain*.fits
corrgain2000-01-29.fits  corrgain2001-02-01.fits  corrgain2002-02-01.fits
corrgain2000-05-01.fits  corrgain2001-05-01.fits  corrgain2002-05-01.fits
corrgain2000-08-01.fits  corrgain2001-08-01.fits  corrgain2002-11-01.fits
corrgain2000-11-01.fits  corrgain2001-11-01.fits


Select the latest file still appropriate for your data. For example, for the
observation date above (February 5, 2002) the correct file is
corrgain2002-02-01.fits. The correction is performed by the following
command (in the most typical setup):

apply_gain evt2.fits -tgain corrgain2002-02-01.fits -gain ACIS_GAIN.fits

where ACIS_GAIN.fits is the gain file from CALDB. For CTI-corrected data,
for example, the following file is suitable:
$CALDB/data/chandra/acis/bcf/gain/acisD2000-01-29gain_ctiN0001.fits

5. OTHER USES OF APPLY_GAIN:

a) You can use apply_gain to re-apply a gain table to your data instead of
acis_process_events (apply_gain is faster):

apply_gain evt.fits -gain ACIS_GAIN.fits

b) To modify PHA in addition to PI and ENERGY,

apply_gain evt.fits -gain  ACIS_GAIN.fits -tgain corrgainXXXXXX.fits -changepha

c) To modify just PHA and not PI and ENERGY (equivalent to corr_tgain in
the previous release):

apply_gain evt.fits -tgain corrgainXXXXXX.fits -changepha


5. RESPONSE FILES (ARFs and RMFs) should be generated as usual from the
released calibration files.

