%+
% Name:
%   memo_apply_tgain_1.2.tex
%
% Usage:
%    latex memo_apply_tgain_1.2.tex
%
% Description:
%    This document describes how to apply the time-dependent gain adjustment.
%
% Input:
%
% Output:
%
% Notes:
%
% History:
%   20 May 03, created (v1.0), Glenn E. Allen
%-

\documentclass{article}

\usepackage{cxo-memo-logo}
\usepackage[dvips]{graphics}
\usepackage{gea}

\newcommand{\apply}{apply\_tgain}
\newcommand{\tgain}{t\_gain}

\begin{document}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

% 1. Header

\memobasic{
   Martin Elvis, SDS Group Leader }{
   Glenn E.\ Allen, SDS }{
   Applying a Time-Dependent Gain Adjustment }{
   1.2 }{
   http://space.mit.edu/CXC/docs/docs.html\#tgain\_spec }{
   /nfs/cxc/h2/gea/sds/docs/memos/memo\_apply\_tgain\_1.2.tex }

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

% 2. Tool name

\section{\ape}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

% 3. Description

\subsection{ Description }

The continuous exposure of the ACIS CCDs to particle radiation causes a
steady increase in the charge-transfer inefficiency (CTI) of the detectors.
As a result, the typical pulse height recorded for an X-ray of a given
energy is declining with time.  This kind of change in the ``gain'' of the
detectors and a change in the electronic gain of the ACIS-I1 CCD is
calibrated (for CTI-adjusted data) and recorded in a set of ``\tgain'' ARD
files.  This document describes how the information in these files is used
by \ape\ to apply a time-dependent gain adjustment to ACIS event data.  The
time-dependent gain adjustment is applied after the CTI adjustment because
the gain adjustment is calibrated using CTI-adjusted data.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

% 4. Input

\subsection{ Input }

\begin{enumerate}

  \item
  A Level 0, 1, 1.5, or 2 event data file (acis*evt0.fits, acis*evt1.fits, 
  acis*evt1a.fits, or acis*evt2.fits) 

  \item
  A ``\tgain'' ARD file (\eg\ acisD2001-05-01t\_gainN0001.fits)

\end{enumerate}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

% 5. Output

\subsection{ Output }

\begin{enumerate}

  \item
  An event data file

\end{enumerate}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

% 6. Parameters

\subsection{ Parameters }

\begin{enumerate}

  \item
  tgainfile,s,h,``CALDB'',,,``Name of input gain adjustment file
  ($\langle$filename$\rangle$ | CALDB | none | NONE)''
  
  \item
  \apply,b,h,yes,,,``Apply time-dependent gain adjustment?''

\end{enumerate}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

% 7. Processing

\subsection{ Processing }
\label{secprocess}

\begin{enumerate}

  \item
  Verify that the specified input files exist.  If the parameter ${\rm
  clobber} = {\rm ``no}$,'' then verify that the output file does not exist.
  If ${\rm \apply} = {\rm ``yes}$'' and ${\rm tgainfile} = {\rm ``none}$''
  or ``NONE'' (or does not exist), then write a warning message that the
  time-dependent gain adjustment is not being applied because a valid
  calibration file is not specified.  

  \item
  \label{findrow}
  For each event $i$ in the input event data file, find the row $r$ in the
  \tgain\ ARD file that satisfies all three of the conditions
  %
  \begin{eqnarray}
  & {\rm CCD\_ID}_{r} = {\rm ccd\_id}_{i} & \\
  & {\rm CHIPX\_LO}_{r} \le {\rm chipx}_{i} \le {\rm CHIPX\_HI}_{r},\ 
    {\rm and} & \\
  & {\rm CHIPY\_LO}_{r} \le {\rm chipy}_{i} \le {\rm CHIPY\_HI}_{r}, &
  \end{eqnarray}
  %
  where ccd\_id, chipx and chipy are the names of columns in the event data
  file and CCD\_ID, CHIPX\_LO, CHIPX\_HI, CHIPY\_LO and CHIPY\_HI are the
  names of columns in the ARD file.  ccd\_id$_{i}$, chipx$_{i}$ and
  chipy$_{i}$ are the values of ccd\_id, chipx and chipy for event $i$.  
  CCD\_ID$_{r}$, CHIPX\_LO$_{r}$, CHIPX\_HI$_{r}$, CHIPY\_LO$_{r}$ and
  CHIPY\_HI$_{r}$ are the values of CCD\_ID, CHIPX\_LO, CHIPX\_HI, CHIPY\_LO
  and CHIPY\_HI for row $r$ of the \tgain\ ARD file.
  
  \item
  The values in the columns PHA, DELTPHA1 and DELTPHA2 for row $r$ of the
  ARD file are used to compute the adjustment to the value of pha for event
  $i$.  These three columns are vector columns.  The number of valid
  elements in each column for row $r$ is specified by NPOINTS$_{r}$, where
  NPOINTS is the name of a column in the ARD file.  If the number of
  elements in the vectors PHA$_{r}$, DELTPHA1$_{r}$ and DELTPHA2$_{r}$ is
  greater than NPOINTS$_{r}$, then the ends of the vectors are padded with
  zeroes.
  
  The appropriate element $n$ of the vector PHA$_{r}$ is determined by using
  the condition
  %
  \begin{equation}
    {\rm PHA}_{r} [n] \le {\rm pha}_{i} < {\rm PHA}_{r} [n+1].
  \end{equation}
  %
  Here, the first and last elements of the vector PHA$_{r}$ are denoted
  PHA$_{r}[1]$ and PHA$_{r}$[NPOINTS$_{r}$], respectively. If ${\rm pha}_{i}
  < {\rm PHA}_{r}[1]$, then $n = 1$.  If ${\rm pha}_{i} \ge {\rm
  PHA}_{r}[{\rm NPOINTS}_{r}]$, then $n = {\rm NPOINTS}_{r} - 1$ (not
  NPOINTS$_{r}$).  
  
  The value of pha$_{i}$ is the pulse height of event $i$ in the event data
  file.  If the CTI adjustment is performed, then pha$_{i}$ is the
  CTI-adjusted pulse height.  (The CTI adjustment is performed before the
  time-dependent gain adjustment.) For GRADED mode observations, pha$_{i}$
  can be either pha$_{i}$ or pha\_ro$_{i}$ (see Tables~1 and 2).
  
  \item
  The adjustment to the value of pha$_{i}$ at $t = {\rm EPOCH1}$ is computed
  by performing a linear interpolation (or extrapolation) of the values in
  the vector DELTPHA1$_{r}$:
  %
  \begin{eqnarray}
    \Delta {\rm pha1}
      & =
      & \frac{{\rm pha}_{i} - {\rm PHA}_{r}[n]}{
          {\rm PHA}_{r}[n+1] - {\rm PHA}_{r}[n]}
        \left( {\rm DELTPHA1}_{r}[n+1] - {\rm DELTPHA1}_{r}[n] \right) + 
	\nonumber \\
    \ 
      & 
      & {\rm DELTPHA1}_{r}[n].
  \end{eqnarray}
  %
  For GRADED mode observations, pha$_{i}$ can be either pha$_{i}$ or
  pha\_ro$_{i}$ (see Tables~1 and 2). EPOCH1 (and EPOCH2) are the names of
  keywords in the header of the \tgain\ file.
  
  \item
  If ${\rm EPOCH2} > {\rm EPOCH1}$ and ${\rm DELTPHA2}_{r}[{\rm
  NPOINTS}_{r}] > 0$, then the estimate of the adjustment to the value of
  pha$_{i}$ at $t = {\rm EPOCH2}$ is 
  %
  \begin{eqnarray}
    \Delta {\rm pha2}
      & =
      & \frac{{\rm pha}_{i} - {\rm PHA}_{r}[n]}{
          {\rm PHA}_{r}[n+1] - {\rm PHA}_{r}[n]}
        \left( {\rm DELTPHA2}_{r}[n+1] - {\rm DELTPHA2}_{r}[n] \right) + 
	\nonumber \\
    \ 
      & 
      & {\rm DELTPHA2}_{r}[n].
  \end{eqnarray}
  %
  For GRADED mode observations, pha$_{i}$ can be either pha$_{i}$ or
  pha\_ro$_{i}$ (see Tables~1 and 2).
  
  If ${\rm EPOCH2} \le {\rm EPOCH1}$ or ${\rm DELTPHA2}_{r}[{\rm
  NPOINTS}_{r}] \le 0$, then
  %
  \begin{eqnarray}
    & \Delta {\rm pha2} = \Delta {\rm pha1}\ {\rm and} & \\
    & {\rm EPOCH2} = {\rm EPOCH1} + 10^{7}\ {\rm s}. &
  \end{eqnarray}

  \item
  The pulse height adjustment at $t = {\rm time}_{i}$ is
  %
  \begin{equation}
    \Delta {\rm pha}
      =
      \frac{{\rm time}_{i} - {\rm EPOCH1}}{{\rm EPOCH2} - {\rm EPOCH1}}
      \left( \Delta {\rm pha2} - \Delta {\rm pha1} \right) + 
      \Delta {\rm pha1},
  \end{equation}
  %
  where ${\rm time}_{i}$ is the time associated with event $i$.

  \item
  \label{calcphaadj}
  The adjusted value of the pulse height for event $i$ is$^{1}$
  %
  \begin{equation}
    {\rm pha}_{i}' = {\rm pha}_{i} + \Delta {\rm pha} + a,
  \end{equation}
  %
  where $a$ is a uniform random deviate in the range [$-$0.5, +0.5) adu. If
  ${\rm pha}_{i}' > 32760$, then ${\rm pha}_{i}' = 32760$.  

  \item
  Steps~\ref{findrow} to \ref{calcphaadj} are performed for every event in
  the input file.
  
  \item
  The values of pha$_{i}'$ (instead of pha$_{i}$) are written to the output
  file\footnote{The content of the output file is contingent on several
  input conditions.  See Tables~1 and 2 for the details.}.
  
  \item
  The name of the \tgain\ ARD file used is written to the keyword TGAINFIL
  and the value of the keyword TGAINCOR is set to ``T'' (True)$^{1}$.
  
\end{enumerate}

\begin{table}[t]
  \begin{center}
    \begin{tabular}{cccccc}
      \multicolumn{6}{c}{Table~1. Input Conditions} \\
      \hline
      \hline
      \
        & Parameter
        & Parameter
        & Keyword
        & Keyword
        & Column
        \\
      Case
        & apply\_tgain
        & doevtgrade
        & TGAINCOR
        & DATAMODE$^{a}$
	& PHA\_RO
        \\
      \hline
      1
        & yes
	& yes
	& F/missing
	& not GRADED
	& doesn't exist
	\\
      2
        & yes
	& yes
	& F/missing
	& not GRADED
	& exists
	\\
      3
        & yes
	& yes
	& F/missing
	& GRADED
	& doesn't exist
	\\
      4
        & yes
	& yes
	& F/missing
	& GRADED
	& exists
	\\
      5
        & yes
	& yes
	& T
	& not GRADED
	& doesn't exist
	\\
      6
        & yes
	& yes
	& T
	& not GRADED
	& exists
	\\
      7
        & yes
	& yes
	& T
	& GRADED
	& doesn't exist
	\\
      8
        & yes
	& yes
	& T
	& GRADED
	& exists
	\\
      9
        & yes
	& no
	& F/missing
	& not GRADED
	& doesn't exist
	\\
     10
        & yes
	& no
	& F/missing
	& not GRADED
	& exists
	\\
     11
        & yes
	& no
	& F/missing
	& GRADED
	& doesn't exist
	\\
     12
        & yes
	& no
	& F/missing
	& GRADED
	& exists
	\\
     13
        & yes
	& no
	& T
	& not GRADED
	& doesn't exist
	\\
     14
        & yes
	& no
	& T
	& not GRADED
	& exists
	\\
     15
        & yes
	& no
	& T
	& GRADED
	& doesn't exist
	\\
     16
        & yes
	& no
	& T
	& GRADED
	& exists
	\\
     17
        & no
	& yes
	& F/missing
	& not GRADED
	& doesn't exist
	\\
     18
        & no
	& yes
	& F/missing
	& not GRADED
	& exists
	\\
     19
        & no
	& yes
	& F/missing
	& GRADED
	& doesn't exist
	\\
     20
        & no
	& yes
	& F/missing
	& GRADED
	& exists
	\\
     21
        & no
	& yes
	& T
	& not GRADED
	& doesn't exist
	\\
     22
        & no
	& yes
	& T
	& not GRADED
	& exists
	\\
     23
        & no
	& yes
	& T
	& GRADED
	& doesn't exist
	\\
     24
        & no
	& yes
	& T
	& GRADED
	& exists
	\\
     25
        & no
	& no
	& F/missing
	& not GRADED
	& doesn't exist
	\\
     26
        & no
	& no
	& F/missing
	& not GRADED
	& exists
	\\
     27
        & no
	& no
	& F/missing
	& GRADED
	& doesn't exist
	\\
     28
        & no
	& no
	& F/missing
	& GRADED
	& exists
	\\
     29
        & no
	& no
	& T
	&not GRADED
	& doesn't exist
	\\
     30
        & no
	& no
	& T
	& not GRADED
	& exists
	\\
     31
        & no
	& no
	& T
	& GRADED
	& doesn't exist
	\\
     32
        & no
	& no
	& T
	& GRADED
	& exists
	\\
      \hline
      \multicolumn{6}{l}{$^{a}$ The DATAMODEs ``GRADED,'' ``GRADED\_HISTO,''
        ``CC\_GRADED,'' and} \\
      \multicolumn{6}{l}{``CC33\_GRADED'' are collectively refered to as 
	GRADED.}
    \end{tabular}
  \end{center}
\end{table}

\begin{table}[t]
  \begin{center}
    \begin{tabular}{cccccl}
      \multicolumn{6}{c}{Table~2. Output} \\
      \hline
      \hline
      \
        & Column
        & Column
        & Keyword
	& Keyword
        \\
      Case
        & PHA
        & PHA\_RO
	& TGAINCOR
	& TGAINFIL
	& Notes
        \\
      \hline
      1
	& Adjust PHA$^{a}$
	& Unadjusted PHA$^{b}$
	& T
	& $\langle {\rm t\_gain} \rangle$
	& SDP
	\\
      2
	& Adjust PHA$^{a}$
	& Unadjusted PHA$^{b}$
	& T
	& $\langle {\rm t\_gain} \rangle$
	& Recompute PHA and tgain
	\\
      3
	& Adjust PHA
	& Unadjusted PHA
	& T
	& $\langle {\rm t\_gain} \rangle$
	& SDP
	\\
      4
	& Adjust PHA\_RO$^{c}$
	& Input PHA\_RO
	& T
	& $\langle {\rm t\_gain} \rangle$
	& Compute tgain only
	\\
      5
	& Adjust PHA$^{a}$
	& Unadjusted PHA$^{b}$
	& T
	& $\langle {\rm t\_gain} \rangle$
	& Recompute PHA and tgain
	\\
      6
	& Adjust PHA$^{a}$
	& Unadjusted PHA$^{b}$
	& T
	& $\langle {\rm t\_gain} \rangle$
	& Recompute PHA and tgain
	\\
      7
	& Don't adjust$^{d}$
	& Zero
	& T
	& Copy$^{f}$
	& Error
	\\
      8
	& Adjust PHA\_RO$^{c}$
	& Input PHA\_RO
	& T
	& $\langle {\rm t\_gain} \rangle$
	& Compute tgain only
	\\
      9
	& Adjust PHA$^{e}$
	& Input PHA
	& T
	& $\langle {\rm t\_gain} \rangle$
	& Compute tgain only
	\\
     10
	& Adjust PHA\_RO$^{c}$
	& Input PHA\_RO
	& T
	& $\langle {\rm t\_gain} \rangle$
	& Compute tgain only
	\\
     11
	& Adjust PHA$^{e}$
	& Zero
	& T
	& $\langle {\rm t\_gain} \rangle$
	& Compute tgain only
	\\
     12
	& Adjust PHA\_RO$^{c}$
	& Input PHA\_RO
	& T
	& $\langle {\rm t\_gain} \rangle$
	& Compute tgain only
	\\
     13
	& Don't adjust$^{d}$
	& Input PHA\_RO
	& T
	& Copy
	& Don't apply twice
	\\
     14
	& Adjust PHA\_RO$^{c}$
	& Input PHA\_RO
	& T
	& $\langle {\rm t\_gain} \rangle$
	& Compute tgain only
	\\
     15
	& Don't adjust
	& Zero
	& T
	& Copy$^{f}$
	& Error
	\\
     16
	& Adjust PHA\_RO$^{c}$
	& Input PHA\_RO
	& T
	& $\langle {\rm t\_gain} \rangle$
	& Compute tgain only
	\\
     17
	& Don't adjust
	& PHA
	& F
	& NONE
	& Compute PHA only
	\\
     18
	& Don't adjust
	& Input PHA\_RO
	& F
	& Copy$^{f}$
	& Compute PHA only
	\\
     19
	& Don't adjust
	& PHA
	& F
	& NONE
	& Calculation disabled
	\\
     20
	& Don't adjust
	& Input PHA\_RO
	& F
	& Copy$^{f}$
	& Calculation disabled
	\\
     21
	& Don't adjust
	& PHA
	& F
	& NONE
	& Compute PHA only
	\\
     22
	& Don't adjust
	& Input PHA\_RO
	& T
	& Copy$^{f}$
	& Compute PHA only
	\\
     23
	& Don't adjust
	& Zero
	& T
	& Copy$^{f}$
	& Calculation disabled
	\\
     24
	& Don't adjust
	& Input PHA\_RO
	& T
	& Copy$^{f}$
	& Calculation disabled
	\\
     25
	& Don't adjust
	& PHA
	& F
	& NONE
	& Calculation disabled
	\\
     26
	& Don't adjust
	& Input PHA\_RO
	& F
	& Copy$^{f}$
	& Calculation disabled
	\\
     27
	& Don't adjust
	& PHA
	& F
	& NONE
	& Calculation disabled
	\\
     28
	& Don't adjust
	& Input PHA\_RO
	& F
	& Copy$^{f}$
	& Calculation disabled
	\\
     29
	& Don't adjust
	& PHA
	& F
	& NONE
	& Calculation disabled
	\\
     30
	& Don't adjust
	& Input PHA\_RO
	& T
	& Copy$^{f}$
	& Calculation disabled
	\\
     31
	& Don't adjust
	& Zero
	& T
	& Copy$^{f}$
	& Calculation disabled
	\\
     32
	& Don't adjust
	& Input PHA\_RO
	& T
	& Copy$^{f}$
	& Calculation disabled
	\\
      \hline
      \multicolumn{6}{l}{$^{a}$ Compute PHA from PHAS.} \\
      \multicolumn{6}{l}{$^{b}$ No gain adjustment applied.  CTI adjustment 
        may be applied.} \\
      \multicolumn{6}{l}{$^{c}$ Input value of PHA\_RO.} \\
      \multicolumn{6}{l}{$^{d}$ Write a warning message.} \\
      \multicolumn{6}{l}{$^{e}$ Input value of PHA.} \\
      \multicolumn{6}{l}{$^{f}$ The keyword is copied only if it exists.}
    \end{tabular}
  \end{center}
\end{table}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

% 8. Finish

\end{document}

