%+
% Name:
%   memo_acis_find_afterglow_1.0.tex
%
% History:
%   2008 Feb 10, created (v1.0), Glenn E. Allen
%-

\documentclass{article}

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

\newcommand{\afa}{acis\_find\_afterglow}

\begin{document}

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

% 1. Header

\memobasic{
   Jonathan McDowell, SDS Group Leader }{
   Glenn E.\ Allen, SDS }{
   \afa }{
   1.0 }{
   http://space.mit.edu/CXC/docs/docs.html\#afa }{
   /nfs/cxc/h2/gea/sds/docs/memos/memo\_acis\_find\_afterglow\_1.0.tex }

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

% 2. Tool name

\section{\afa}

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

% 3. Description

\subsection{ Description }

A cosmic-ray ``afterglow'' is produced when a large amount of charge is
deposited on a CCD by a cosmic ray. Most of the charge is clocked off of the
CCD in a single frame. However, a small amount can be captured in charge
traps, which release the charge relatively slowly. As a result, a sequence
of events can appear in a single detector pixel over a few frames as the
trapped charge is released.

To date, two algorithms have been used by the CXC to identify cosmic-ray
afterglows. The first algorithm was implemented in the CIAO tool
acis\_detect\_afterglow and used for pipeline processing from the summer of
2000 to the fall of 2004. This algorithm searches for occasions when events
are detected in two or more consecutive frames on the same CCD pixel. While
the events are flagged as potential cosmic-ray afterglows and excluded from
Level 2 event-data files, the corresponding pixels are not included in the
observation-specific bad-pixel file. This algorithm finds many afterglow
events, but at the expense of discarding X-ray events associated with real
astrophysical sources.  The fraction of the source events that are discarded
depends on the brightness and variability of the source.

In an attempt to minimize the loss of source events, another algorithm was
developed and implemented in the CIAO tool acis\_run\_hotpix, which is a
wrapper around the tools acis\_find\_hotpix, acis\_classify\_hotpix and
acis\_build\_badpix. The second algorithm searches for detector pixels that
have an unusually large number of events. Suspicious pixels are added to the
observation-specific bad-pixel file only if the neighboring pixels do not
have a significant excess of events.  This condition helps insure that
events associated with dithered sources are not discarded. Events associated
with afterglows are flagged and excluded from Level 2 event-data files. The
newer algorithm has been used for pipeline processing (and reprocessing)
since the fall of 2004. While it is relatively gentle on astrophysical
sources, it does let some afterglows ``slip through the cracks.'' The
afterglow detection efficiency depends on the number of events in the
afterglow.  The efficiency declines quickly as the number of events in an
afterglow drops below about eight.

This spec describes a third afterglow-detection algorithm that is designed
to enhance the detection efficiency for afterglows that have as few as four
events to remain gentle for real astrophysical sources. The principal change
between the second and third afterglow-detection algorithms is that the
third algorithm searches for afterglows using the events in a short, sliding
time window instead of the entire duration of an observation.

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

% 4. Input

\subsection{ Input }

\begin{enumerate}

  \item
    Level 0 or 1 event-data files (acis*evt0.fits, acis*evt1.fits)

  \item
    A Level 1 observation-specific bad-pixel file (acis*bpix1.fits)

  \item
    A Level 1 exposure statistics file (acis*stat1.fits)

\end{enumerate}

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

% 5. Output

\subsection{ Output }

\begin{enumerate}

  \item
    An updated observation-specific bad-pixel file

\end{enumerate}

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

% 6. Parameters

\subsection{ Parameters }

\begin{enumerate}

  \item
    infile,s,a,``'',,,``Name of input event-data file(s)''

  \item
    outfile,s,a``'',,,``Name of output bad-pixel file''

  \item
    badpixfile,s,a,``'',,,``Name of input bad-pixel file''

  \item
    statfile,s,a,``'',,,``Name of input exposure-statistics file''

  \item
    expnowindow,i,h,10,1,100,``Number of frames in the sliding time window''

  \item
    probthresh,r,h,0.001,1.0e-10,0.1,``Minimum post-trials significance of
    potential afterglows (1 sigma = 0.159, 2 sigma = 0.0228, and 3 sigma =
    0.00135)''

  \item
    clobber,b,h,``no'',,,``Overwrite output file if it exists?''

  \item
    verbose,i,h,0,0,5,``Amount of messages produced (0$=$none, 5$=$a lot)''

  \item
    mode,s,h,``ql'',,,

\end{enumerate}

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

% 7. Processing

\subsection{ Processing }

\begin{enumerate}

  \item
    Verify that the input files exist.

  \item
    If clobber=``no'', then verify that the output files do not exist.

  \item
    Verify that the input event-data file has READMODE=``TIMED''.  If
    READMODE is not equal to ``TIMED'', then exit with an error message.

  \item
    Verify that the values of the parameters expnowindow and probthresh are
    in the valid ranges for these parameters.

  \item
    Create an array $A$ with dimensions $10 \times 1024 \times 1024$ to be
    used to mark suspicious pixels.  Each element of $A$ is preset to zero.

  \item
    Identify which CCDs are ``valid.'' A CCD is defined to be valid if there
    is at least one event on the CCD in the input event-data file(s).

  \item
    Loop over a sliding EXPNO window.  The first window includes the frames
    ${\rm EXPNO}_{\rm min} \le {\rm EXPNO} \le {\rm EXPNO}_{\rm min} + {\rm
    expnowindow}$.  The second window includes ${\rm EXPNO}_{\rm min} + 1
    \le {\rm EXPNO} \le {\rm EXPNO}_{\rm min} + {\rm expnowindow} + 1$. The
    last window includes ${\rm EXPNO}_{\rm max} - {\rm expnowindow} \le {\rm
    EXPNO} \le {\rm EXPNO}_{\rm max}$.

  \item
    For each sliding window, mark suspicious pixels.  A suspicious pixel is
    one on which two or more events occur in the same sliding window. That
    is, if the pixel at $({\rm CCD\_ID, CHIPX, CHIPY}) = (c,x,y)$, contains
    two or more events in a window, then set $A[c,x,y] = 1$.

  \item
    After every sliding window has been used to mark suspicious pixels, loop
    over the suspicious pixels.  For each suspicious pixel

    \begin{itemize}

      \item[i.]
        \label{step01}
	%
	Determine ${\rm EXPNO}_{\rm start}$, the first frame of the
	potential afterglow.  Loop through the events on the suspicious
	pixel.  If the difference between two consecutive events on the
	pixel
	%
	\begin{equation}
	  {\rm EXPNO}_{i+1} - {\rm EXPNO}_{i} \le 
	    {\rm expnowindow},
	\end{equation}
	%
	then ${\rm EXPNO}_{\rm start} = {\rm EXPNO}_{i}$.  Once ${\rm
	EXPNO}_{\rm start}$ has been found, stop looping over the events on
	the pixel.

      \item[ii.]
        Determine ${\rm EXPNO}_{\rm stop}$, the last frame of the potential
	afterglow.  Loop through the events on the suspicious pixel that
	have ${\rm EXPNO}$ greater than ${\rm EXPNO}_{\rm start}$.  If the
	difference between two consecutive events on the pixel 
	%
	\begin{equation}
	  {\rm EXPNO}_{i+1} - {\rm EXPNO}_{i} > 
	    {\rm expnowindow},
	\end{equation}
	%
	then ${\rm EXPNO}_{\rm stop} = {\rm EXPNO}_{i}$. Once ${\rm
	EXPNO}_{\rm stop}$ has been found, stop looping over the events on
	the pixel.  If the last event on the pixel is processed before
	equation~\ref{eqn02} is satisfied, then ${\rm EXPNO}_{\rm stop}$ is
	equal to the largest value of EXPNO for the pixel.

      \item[iii.]
        Calculate $N_{\rm evt}$, the number of events in the potential
	afterglow. If the suspicious pixel has $({\rm CCD\_ID}, {\rm CHIPX},
	{\rm CHIPY}) = (c,x,y)$, then $N_{\rm evt}$ is equal to the number
	of events that satisfy the conditions
	%
	\begin{eqnarray}
          & {\rm CCD\_ID} = c, & \\
	  & {\rm CHIPX} = x, & \\
	  & {\rm CHIPY} = y\ {\rm and} & \\
          & {\rm EXPNO}_{\rm start} \le {\rm EXPNO} \le {\rm EXPNO}_{\rm
	    stop}. & 
	\end{eqnarray}
	%

      \item[iv.]
        Calculate $N_{\rm node}$, the number of events on the same node as
	the suspicious pixel.  If the suspicious pixel has $({\rm CCD\_ID},
	{\rm NODE\_ID}) = (c,n)$, then $N_{\rm node}$ is equal to the number
	of events that satisfy the conditions
	%
	\begin{eqnarray}
          & {\rm CCD\_ID} = c\ {\rm and} & \\
          & {\rm NODE\_ID} = n. & 
	\end{eqnarray}
	%

      \item[v.]
        Determine $N_{\rm pix}$, the total number of valid pixels on the
	same node as the suspicious pixel.  
	%
	\begin{center}
	  \begin{tabular}{|c|c|c|}
	    \multicolumn{3}{c}{Table 1: Values of $N_{\rm pix}$}
	      \\
	    \hline
	    \hline
	    \
	      & \multicolumn{2}{c}{NODE\_ID}
	      \\
	    \cline{2-3}
	    DATAMODE
	      & 0 and 3
	      & 1 and 2
	      \\
	    \hline
	    FAINT
	      & 260,610
	      & 261,632
	      \\
	    FAINT\_BIAS
	      & 260,610
	      & 261,632
	      \\
	    GRADED
	      & 260,610
	      & 261,632
	      \\
	    VFAINT
	      & 260,100
	      & 261,120
	      \\
	    \hline
	  \end{tabular}
	\end{center}
	%
	$N_{\rm pix}$ includes all pixels except the outer edges at ${\rm
	CHIPX} = 1$ or 1024 and ${\rm CHIPY} = 1$ and 1024.  If the ${\rm
	DATAMODE} = {\rm VFAINT}$, then the rows at ${\rm CHIPY} = 2$ and
	1023 are also excluded. Known bad pixels and columns are included
	because these pixels and columns are searched for afterglows.

      \item[vi.]
        Calculate $N_{\rm frame}^{\rm aft}$, the number of valid frames in
	the potential afterglow.  If the suspicious pixel has ${\rm CCD\_ID}
	= c$, then $N_{\rm frame}^{\rm aft}$ is equal to the number of rows
	in the input exposure statistics file that satisfy the conditions
	%
	\begin{eqnarray}
          & {\rm CCD\_ID} = c, & \\
          & {\rm EXPNO} \ge {\rm EXPNO}_{\rm start}\ {\rm and} & \\ 
	  & {\rm EXPNO} \le {\rm EXPNO}_{\rm stop}. &
	\end{eqnarray}
	%
        If no frames are missing, then $N_{\rm frame}^{\rm aft} = {\rm
	EXPNO}_{\rm stop} - {\rm EXPNO}_{\rm start} + 1$.  Otherwise, the
	value of $N_{\rm frame}^{\rm aft}$ is smaller.

      \item[vii.]
        Calculate $N_{\rm frame}^{\rm tot}$, the total number of valid
	frames.  If the suspicious pixel has ${\rm CCD\_ID} = c$, then
	$N_{\rm frame}^{\rm tot}$ is equal to the number of rows in the
	input file that satisfy the conditions
	%
	\begin{eqnarray}
          & {\rm CCD\_ID} = c\ {\rm and} & \\
	  & {\rm EXPNO} \ge 3. &
	\end{eqnarray}
	%

      \item[viii.]
        Calculate $N_{\rm exp}$, the expected number of events on the pixel
	during the potential afterglow.
	%
	\begin{equation}
	  N_{\rm exp} =
	    \left(
	      \frac{N_{\rm node}}{N_{\rm pix}}
	    \right)
	    \left(
	      \frac{N_{\rm frame}^{\rm aft}}{N_{\rm frame}^{\rm tot}}
	    \right).
	\end{equation}
	%

      \item[ix.]
        Calculate $P_{\rm pre}$, the pre-trials probability of obtaining
	$N_{\rm evt}$ events in the potential afterglow when the expected
	number of events is $N_{\rm exp}$.
	%
	\begin{equation}
          P_{\rm pre} =
            1 -
            \left[
              \left(
                \sum_{i=0}^{N_{\rm evt}-1}
                \frac{N_{\rm exp}^{i}}{i!}
              \right) +
              \frac{1}{2}
              \frac{N_{\rm exp}^{N_{\rm evt}}}{N_{\rm evt}!}
            \right]
            e^{-N_{\rm exp}}.
        \end{equation}
	%

      \item[x.]
        Calculate $N_{\rm trial}$, the number of trials performed.  Here
	%
	\begin{equation}
	  N_{\rm trial} =
	    \left( 4 N_{\rm pix} N_{\rm ccd} \right)
	    \left(
	      N_{\rm frame}^{\rm tot} - {\rm expnowindow} + 1
	    \right),
	  \label{afa_eqn11}
	\end{equation}
	%
	where $N_{\rm ccd}$ is the number of valid CCDs. This estimate of
	$N_{\rm trial}$ is really an upper limit on the number of trials.
	The actual number of trials includes only the of ``independent''
	searches.  Adjacent windows in the sliding EXPNO window are not
	independent because they overlap.  Therefore, a lower limit on
	$N_{\rm trial}$ can be computed by considering only those windows
	that do not overlap (\ie\ $N_{\rm trial} = \left( 4 N_{\rm pix}
	N_{\rm ccd} \right) \left( N_{\rm frame}^{\rm tot} - {\rm
	expnowindow} + 1 \right) / ({\rm expnowindow} + 1)$).  Since the
	actual value of $N_{\rm trial}$ can be difficult to determine,
	equation~\ref{afa_eqn11} is used here since it is the most
	conservative (\ie\ the largest) value.
	      
      \item[xi.]
        Calculate $P_{\rm post}$, the post-trials probability of obtaining a
	value $P$ at least as small as $P_{\rm pre}$ after performing
	$N_{\rm trial}$ searches.
	%
	\begin{equation}
	  P_{\rm post} =
	    1 - \left( 1 - P_{\rm pre} \right)^{\rm N_{\rm trial}}.
	\end{equation}
	%

      \item[xii.]
        \label{step12} 
	%
	If $P_{\rm post} < {\rm probthresh}$, then write the information
	about the afterglow to the output observation-specific bad-pixel
	file. The output values of SHAPE, COMPONENT, CHIPX and CHIPY are
	consistent with their usual definitions. The output value of TIME is
	given by
	%
	\begin{equation}
	  {\rm TIME} =
	    {\rm TIME}_{\rm start} -
	    {\rm TIMEPIXR} \times
	    {\rm TIMEDEL} -
	    {\rm FLSHTIME}
	\end{equation}
	%
	(\ie\ the time at the beginning of the ${\rm EXPNO}_{\rm start}$
	frame), where ${\rm TIMEPIXR}$, ${\rm TIMEDEL}$ and ${\rm FLSHTIME}$
	are keywords in the exposure statistics file and ${\rm TIME}_{\rm
	start}$ is the TIME in the input exposure-statistics file that is
	associated with ${\rm EXPNO} = {\rm EXPNO}_{\rm start}$ and ${\rm
	CCD\_ID} = c$. The output value of TIME\_STOP is given by
	%
	\begin{equation}
	  {\rm TIME\_STOP} =
	    {\rm TIME}_{\rm stop} +
	    \left( 1 - {\rm TIMEPIXR} \right) \times
	    {\rm TIMEDEL}
	\end{equation}
	%
	(\ie\ the time at the end of the ${\rm EXPNO}_{\rm stop}$ frame),
	where ${\rm TIME}_{\rm stop}$ is the TIME in the input
	exposure-statistics file that is associated with ${\rm EXPNO} = {\rm
	EXPNO}_{\rm stop}$ and ${\rm CCD\_ID} = c$. The output value of
	STATUS has bit 15 (of 0--31) set for afterglows.  Other STATUS bits
	may be set to one as well if the pixel is bad for other reasons.

      \item[xiii.]
        Repeat steps \ref{step01} through \ref{step12}, as necessary, for
	the same suspicious pixel. That is, if there are additional events
	on the pixel that have exposure numbers ${\rm EXPNO} > {\rm
	EXPNO}_{\rm stop}$, then steps \ref{step01} through \ref{step12} are
	repeated as many times as necessary until all of the events on the
	pixel have been processed.  It is necessary to do so because one
	pixel may have more than one potential afterglow.

    \end{itemize}

\end{enumerate}

In the standard data-processing pipeline, the tool \afa\ is run after the
observation-specific bad-pixel file (acis*bpix1.fits) has already been
created because \afa\ updates this file.  After the file has been updated,
the tool acis\_build\_badpix is rerun to insure that pixels adjacent to
afterglow events are marked as ``bad,'' if appropriate.  The tool
acis\_process\_events is run after the bad-pixel file has been updated since
this file is used as input.

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

% 8. TBD

\subsection{ TBD }

\begin{enumerate}

  \item
    Modify the spec, if necessary, to insure that the algorithm does not
    discard real x-ray events.
    
  \item
    Optimize the default value of expnowindow.
  
\end{enumerate}

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

% 9. Finish

\end{document}

