%+
% Name:
%   subpix_spec_2.1.tex
%
% History:
%   2010 May 07, created (v0.1), Glenn E. Allen
%   2010 May 12, added a TBD concerning continuous-clocking mode; added a
%     comment about the size of the shift (v0.2), GEA
%   2010 May 14, added centroid as an option for the parameter pix_adj
%     (v0.3), GEA
%   2010 May 19, changed CC to CC33; modified what is done for stop=tan;
%     changed edser, centroid, randomize, and none to upper case (v1.0), GEA
%   2010 Sep 07, forbid the use of stop="det" (v1.1), GEA
%   2010 Sep 14, fixed refs.bib (v1.2), GEA
%   2012 Dec 31, added pix_adj=CENTROID, NONE, and RANDOMIZE (v2.0), GEA
%   2013 Jun 13, clarified that PHAS_ADJ should be used instead of PHAS if
%     the CTI adjustment has been performed (for the CENTROID algorithm), GEA
%-

\documentclass{article}

\usepackage{/nfs/inconceivable/d0/SRC/LATEX/STY/cxo_memo_logo}
\usepackage[dvips]{graphics}
\usepackage{epsfig}
\usepackage{/nfs/inconceivable/d0/SRC/LATEX/STY/gea}
\usepackage{pstricks}
\usepackage[sort&compress]{natbib}

\newrgbcolor{red}{1 0 0}

\renewcommand{\thefootnote}{\fnsymbol{footnote}}

\begin{document}

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

% 1. Header

\memobasic{
   Jonathan McDowell, SDS Group Leader }{
   Glenn E.\ Allen, SDS }{
   Sub-pixel event-positioning and pixel randomization spec }{
   2.1 }{
   http://space.mit.edu/CXC/docs/docs.html\#subpix }{
   /nfs/inconceivable/d0/SDS/SPECS/SUBPIX/subpix\_spec\_2.1.tex }

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

% 2. Tool name

\section{Sub-pixel event positioning}

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

% 3. Description

\subsection{ Description }

The size of the point spread function of a point source observed with the
ACIS detectors is determined by several factors:
%
(1) the size of the point spread function of the mirrors,
%
(2) the accuracy to which the pointing direction can be reconstructed,
%
(3) the size of the pixels on the ACIS CCDs, and
%
(4) ``pixel randomization.''
%
The randomization is performed by adding a uniform random deviate in the
interval $[-0.5,+0.5)$~pixel%
%
\footnote{The range used to be controlled by the parameter {\tt
rand\_pix\_size}, with the default range being $[-0.5,+0.5)$~pixel. With the
implementation of the sub-pixel event-positioning algorithm {\tt EDSER}, the
use of the parameter {\tt rand\_pix\_size} has been discontinued.  While it
is still possible to apply a pixel randomization, it is no longer possible
to control the range of the randomization.}
%
to the coordinates {\tt CHIPX} and {\tt CHIPY} before the detector
coordinates {\tt DETX} and {\tt DETY} and the sky coordinates {\tt X} and
{\tt Y} are calculated.  This randomization was introduced to avoid aliasing
effects that can produce unusual features in the shape of the image of a
point source for some observations.  The randomization is automatically
disabled if a sub-pixel event-positioning algorithm is used.

The size of an ACIS pixel undersamples the point spread function of an
on-axis point source.  As a result, the use of the ACIS detectors can
degrade the quality of an image of a source if events are assumed to occur
only at the centers of the pixels for which they are reported.
\cite{tsu01a}, \cite{mor01a}, \cite{li03a}, and \cite{li04a} describe
algorithms that can be used to more accurately localize the centroids of
certain events based upon the distribution of charge in the ``event islands.%
%
\footnote{An event island, the quantity named {\tt PHAS} in a Level 1
event-data file, contains the pulse-height distribution in a 3~pixel
$\times$ 3~pixel region centered upon the pixel in which an event is
reported.  In {\tt VFAINT} mode, {\tt PHAS} is a $5 \times 5$ array instead
of a $3 \times 3$. While the {\tt PHAS} information is not telemetered for
{\tt GRADED} mode data, the {\tt FLTGRADE}, a scalar representation of the
distribution of charge in the central $3 \times 3$, is telemetered for {\tt
GRADED} (and non-{\tt GRADED}) mode observations.  The sub-pixel
event-positioning algorithms ``CSDSER'' (Li \etal\ 2004) and {\tt CENTROID}
(see sec.~\ref{centroid}) require {\tt PHAS}. The rest of the algorithms use
{\tt FLTGRADE}.}''

This spec describes the implementation of the energy- and {\tt
FLTGRADE}-dependent sub-pixel event-positioning algorithm (``EDSER'') of
\cite{li04a} in the tool {\tt acis\_process\_events}. Of the algorithms
described by \cite{li04a}, EDSER is the one that works best for GRADED mode
event data. It is also very good for non-GRADED mode data.  The spec also
describes the {\tt PHAS}-dependent algorithm ``CENTROID'' and the processes
to follow if {\tt pix\_adj=NONE} or {\tt RANDOMIZE}.

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

% 4. Input

\subsection{ Input }

\begin{enumerate}

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

 \item
    If {\tt pix\_adj=EDSER}, then a sub-pixel ARD file (acisD*subpix*.fits) 

\end{enumerate}

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

% 5. Output

\subsection{ Output }

\begin{enumerate}

  \item
    An event-data file in which the coordinates {\tt DETX} and {\tt DETY}
    and {\tt X} and {\tt Y} have been updated.  The coordinates {\tt CHIPX},
    {\tt CHIPY}, {\tt TDETX}, and {\tt TDETY} remain unchanged.

\end{enumerate}

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

% 6. Parameters

\subsection{ Parameters }

\begin{enumerate}

  \item
    { \tt infile,s,a,"",,,"Name of input event-data file" }

  \item
    { \tt outfile,s,a"",,,"Name of output event-data file" }

  \item
    { \tt subpixfile,s,h,"CALDB",,,"Name of input sub-pixel file (CALDB |
    NONE | none | \\ <filename>)" }

  \item
    { \tt pix\_adj,s,h,"EDSER",,,"Sub-pixel adjustment algorithm\ (EDSER |
    CENTROID | NONE | \\ RANDOMIZE)" }

\end{enumerate}

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

% 7. Processing

\subsection{ Processing }

Perform the following tests before processing begins.
%
\begin{itemize}

  \item
    Verify that the {\tt infile} exists.  If it does not, then exit with an
    error message.
    
  \item
    If {\tt pix\_adj=EDSER}, then verify that the {\tt subpixfile} exists.
    If it does not, then exit with an error message.

  \item
    If {\tt clobber=no}, then verify that the {\tt outfile} does not exist.
    If it does, then exit with an error message.

  \item
    If {\tt pix\_adj=EDSER}, then verify that {\tt DATAMODE=FAINT}, {\tt
    FAINT\_BIAS}, {\tt GRADED}, or {\tt VFAINT}.  If it does not (\eg\ if
    {\tt DATAMODE=CC33\_FAINT} or {\tt CC33\_GRADED}), then exit with an
    error message.

  \item
    If {\tt pix\_adj=CENTROID}, then verify that {\tt DATAMODE=FAINT}, {\tt
    FAINT\_BIAS}, or {\tt VFAINT}.  If it does not (\eg\ if {\tt
    DATAMODE=CC33\_FAINT}, {\tt CC33\_GRADED} or {\tt GRADED}), then exit
    with an error message.

  \item
    If {\tt pix\_adj=EDSER}, {\tt CENTROID}, or {\tt RANDOMIZE}, then verify
    that {\tt stop=sky}.  If it does not, then exit with an error message.

\end{itemize}

\subsubsection{ \tt pix\_adj=CENTROID }
\label{centroid}

\begin{figure}[h]
  \hfil
  \hbox{\epsfig{file=fig01b,width=6.50in}}
  \hfil
  %
  \caption{ {\sl Left:} The relative {\tt CHIPX} and {\tt CHIPY} coordinates
    of the nine pixels ($i = 0$, {\ldots}, 8) in a 3~pixel $\times$ 3~pixel
    event island (${\tt PHAS}_{i}$). {\sl Right:} The relative {\tt CHIPX}
    and {\tt CHIPY} coordinates of the twenty-five pixels in a 5~pixel
    $\times$ 5~pixel event island.
  %
  \label{fig01}}
\end{figure}

If {\tt pix\_adj=CENTROID}, then use the sub-pixel event-positioning
algorithm described in this section.%
%
\footnote{With the implementation of the sub-pixel event-positioning
algorithm {\tt EDSER}, the use of the parameter {\tt docentroid} has been
discontinued and replaced by {\tt pix\_adj=CENTROID}.}\ \
%
This algorithm should be used after the CTI and time-dependent gain
adjustments (if any) have been applied.  Perform the following steps, in
sequence, for each event.
%
\begin{enumerate}

  \item
    Calculate the weights $w_{i}$ for each one of the nine pixels in the
    3~pixel $\times$ 3~pixel event island.  Here,
    %
    \begin{equation}
      w_{i} = 
        \left\{
          \begin{array}{ll}
	    {\tt PHAS}_{i} & {\rm if\ the\ pixel\ is\ valid} \\
	    0 & {\rm if\ the\ pixel\ is\ invalid}
	  \end{array}
	\right.
    \end{equation}
    %
    {\red If the CTI adjustment has been performed, then {\tt PHAS\_ADJ} is
    used instead of {\tt PHAS}.} For {\tt FAINT} and {\tt FAINT\_BIAS} mode
    observations, the index $i$ runs from 0 to 8, with $i = 4$ being the
    central pixel of an event island (Fig.~\ref{fig01} left). For {\tt
    VFAINT} mode observations, $i$ runs from 0 to 24.  However, use only the
    central nine pixels (i.e.\ $i = 6$, 7, 8, 11, 12, 13, 16, 17, and 18
    instead of $i = 0$, 1, 2, 3, 4, 5, 6, 7, and 8, respectively
    [Fig.~\ref{fig01} right]). Invalid pixels are those that are not
    included in the summed pulse height PHA (see the spec
    http://space.mit.edu/CXC/docs/docs.html\#grades) and those that have one
    or more of the bad-pixel {\tt STATUS} bits 0, 1, 2 (only during the
    bias-parity error), 3, 4, 11, 13 (only during the ``FEP0'' error), 14,
    15 (only during the afterglow), or 16 set to one.
  
  \item
    Calculate the normalized weights
    %
    \begin{equation}
      w_{i}'
        =
	\frac{w_{i}}{\sum_{i=0}^{8} w_{i}}.
    \end{equation}
  
  \item
    Use the expressions
    %
    \begin{equation}
      {\tt CHIPX}' 
        =
        {\tt CHIPX} -
	w_{0}' {\tt PHAS}_{0} +
	w_{2}' {\tt PHAS}_{2} -
	w_{3}' {\tt PHAS}_{3} +
	w_{5}' {\tt PHAS}_{5} -
	w_{6}' {\tt PHAS}_{6} +
	w_{8}' {\tt PHAS}_{8}
    \end{equation}
    %
    and
    %
    \begin{equation}
      {\tt CHIPY}' 
        =
	{\tt CHIPY} -
	w_{0}' {\tt PHAS}_{0} -
	w_{1}' {\tt PHAS}_{1} -
	w_{2}' {\tt PHAS}_{2} +
	w_{6}' {\tt PHAS}_{6} +
	w_{7}' {\tt PHAS}_{7} +
	w_{8}' {\tt PHAS}_{8}
    \end{equation}
    %
    to calculate the real-valued, sub-pixel coordinates ${\tt CHIPX}'$ and
    ${\tt CHIPY}'$, respectively.%
    %
    \footnote{If {\tt pix\_adj=CENTROID}, then $| {\tt CHIPX}' - {\tt CHIPX} |$
    and $| {\tt CHIPY}' - {\tt CHIPY} |$ can exceed 0.5~pixels.}

  \item
    Use the values of ${\tt CHIPX}'$ and ${\tt CHIPY}'$ to calculate the
    detector coordinates {\tt DETX} and {\tt DETY} and the sky coordinates
    {\tt X} and {\tt Y}.

  \item
    If the parameter {\tt eventdef} includes {\tt f:chipx\_adj} and/or {\tt
    f:chipy\_adj}, then write the coordinates ${\tt CHIPX}'$ and/or ${\tt
    CHIPY}'$ to the {\tt outfile}.  Although {\tt chipx\_adj} and {\tt
    chipy\_adj} are excluded from {\tt eventdef} by default, the data in
    these columns are valuable for testing purposes and may be of interest to
    some users.

  \item
    Create or update the header keyword {\tt PIX\_ADJ} in the {\tt outfile}.
    The value of this keyword should be {\tt CENTROID}.

  \item
    Create or update the header keyword {\tt RAND\_SKY} in the {\tt outfile}.
    The value of this keyword should be 0.0.

\end{enumerate}

\subsubsection{ \tt pix\_adj=EDSER }
\label{edser}

If {\tt pix\_adj=EDSER}, then use the sub-pixel, event-positioning algorithm
described in this section.  This algorithm should be used after the CTI and
time-dependent gain adjustments (if any) have been applied and after the
{\tt ENERGY} and {\tt FLTGRADE} have been computed, since the algorithm
depends upon the values of {\tt ENERGY} and {\tt FLTGRADE}. Perform the
following steps, in sequence, for each event.
%
\begin{enumerate}

  \item
    Use the value of {\tt CCD\_ID} to select the appropriate HDU in the
    sub-pixel ARD file and use the value of {\tt FLTGRADE} to select the
    appropriate row in that HDU (see sec.~\ref{ard}).

  \item
    Use the expressions
    %
    \begin{equation}
      {\tt CHIPX}'
        =
	{\tt CHIPX} +
	\left( \Delta X_{i+1} - \Delta X_{i} \right)
	\left( \frac{ E - E_{i} }{ E_{i+1} - E_{i} } \right) +
	\Delta X_{i}
    \end{equation}
    %
    and
    \begin{equation}
      {\tt CHIPY}'
        =
	{\tt CHIPY} +
	\left( \Delta Y_{i+1} - \Delta Y_{i} \right)
	\left( \frac{ E - E_{i} }{ E_{i+1} - E_{i} } \right) +
	\Delta Y_{i}
    \end{equation}
    %
    to calculate the real-valued, sub-pixel coordinates ${\tt CHIPX}'$ and
    ${\tt CHIPY}'$, respectively.%
    %
    \footnote{If {\tt pix\_adj=EDSER}, then $| {\tt CHIPX}' - {\tt CHIPX} |$ 
    and $| {\tt CHIPY}' - {\tt CHIPY} |$ cannot exceed 0.5~pixels.}\ \
    %
    Here $E$ is the {\tt ENERGY} of the event and
    %
    \begin{eqnarray}
      E_{i}
        & =
	& {\tt ENERGY}_{i},
	\label{eqn03}
	\\
      E_{i+1}
        & =
	& {\tt ENERGY}_{i+1},
	\\
      \Delta X_{i}
        & =
	& {\tt CHIPX\_OFFSET}_{i},
	\\
      \Delta X_{i+1}
        & =
	& {\tt CHIPX\_OFFSET}_{i+1},
	\\
      \Delta Y_{i}
        & =
	& {\tt CHIPY\_OFFSET}_{i},\ {\rm and}
        \\
      \Delta Y_{i+1}
        & =
	& {\tt CHIPY\_OFFSET}_{i+1},
	\label{eqn08}
    \end{eqnarray}
    %
    where the quantities on the right-hand sides of
    equations~\ref{eqn03}--\ref{eqn08} are from vectors in the ARD file (see
    sec.~\ref{ard}). The values of $i$ and $i+1$ are the ones that satisfy
    the relationship
    %
    \begin{equation}
      E_{i} \le E < E_{i+1}.
    \end{equation}
    %
    The valid ranges for $i$ and $i+1$ are from 0 to ${\tt NPOINTS}-2$ and
    from 1 to ${\tt NPOINTS}-1$, respectively.%
    %
    \footnote{{\tt NPOINTS} is the name of a column in the ARD file (see
    sec.~\ref{ard}).}
    %
    If $E > E_{{\tt NPOINTS}-1}$, then use $i = {\tt NPOINTS} - 2$ and $i+1
    = {\tt NPOINTS} -1$ (\ie\ extrapolate instead of interpolate).  Since
    $E$ should always be greater than zero and since $E_{0} = 0$, in no case
    should $i < 0$.

  \item
    Use the values of ${\tt CHIPX}'$ and ${\tt CHIPY}'$ to calculate the
    detector coordinates {\tt DETX} and {\tt DETY} and the sky coordinates
    {\tt X} and {\tt Y}.

  \item
    If the parameter {\tt eventdef} includes {\tt f:chipx\_adj} and/or {\tt
    f:chipy\_adj}, then write the coordinates ${\tt CHIPX}'$ and/or ${\tt
    CHIPY}'$ to the {\tt outfile}.  Although {\tt chipx\_adj} and {\tt
    chipy\_adj} are excluded from {\tt eventdef} by default, the data in
    these columns are valuable for testing purposes and may be of interest to
    some users.

  \item
    Create or update the header keyword {\tt PIX\_ADJ} in the {\tt outfile}.
    The value of this keyword should be {\tt EDSER}.

  \item
    Create or update the header keyword {\tt RAND\_SKY} in the {\tt
    outfile}.  The value of this keyword should be 0.0.

\end{enumerate}

\subsubsection{ \tt pix\_adj=NONE }

If {\tt pix\_adj=NONE}, then perform the following steps, in sequence, for
each event.

\begin{enumerate}

  \item
    Use the integer-valued, read-out coordinates ${\tt CHIPX}$ and ${\tt
    CHIPY}$ to calculate the detector coordinates {\tt DETX} and {\tt DETY}
    and the sky coordinates {\tt X} and {\tt Y}.

  \item
    If the parameter {\tt eventdef} includes {\tt f:chipx\_adj} and/or {\tt
    f:chipy\_adj}, then write the coordinates ${\tt CHIPX}$ and/or ${\tt
    CHIPY}$ to the {\tt outfile}.

  \item
    Create or update the header keyword {\tt PIX\_ADJ} in the {\tt outfile}.
    The value of this keyword should be {\tt NONE}.

  \item
    Create or update the header keyword {\tt RAND\_SKY} in the {\tt outfile}.
    The value of this keyword should be 0.0.

\end{enumerate}

\subsubsection{ \tt pix\_adj=RANDOMIZE }

If {\tt pix\_adj=RANDOMIZE}, then perform the following steps, in sequence,
for each event.

\begin{enumerate}

  \item
    Use the expressions
    %
    \begin{equation}
      {\tt CHIPX}' = {\tt CHIPX} + a_{x}
    \end{equation}
    %
    and
    %
    \begin{equation}
      {\tt CHIPY}' = {\tt CHIPY} + a_{y}
    \end{equation}
    %
    to calculate the real-valued coordinates ${\tt CHIPX}'$ and ${\tt
    CHIPY}'$, respectively.  Here $a_{x}$ and $a_{y}$ are uniform random
    deviates in the interval $[-0.5,+0.5)$.

  \item
    Use the values of ${\tt CHIPX}'$ and ${\tt CHIPY}'$ to calculate the
    detector coordinates {\tt DETX} and {\tt DETY} and the sky coordinates
    {\tt X} and {\tt Y}.

  \item
    If the parameter {\tt eventdef} includes {\tt f:chipx\_adj} and/or {\tt
    f:chipy\_adj}, then write the coordinates ${\tt CHIPX}'$ and/or ${\tt
    CHIPY}'$ to the {\tt outfile}. Although {\tt chipx\_adj} and {\tt
    chipy\_adj} are excluded from {\tt eventdef} by default, the data in
    these columns are valuable for testing purposes and may be of interest to
    some users.
    
  \item
    Create or update the header keyword {\tt PIX\_ADJ} in the {\tt outfile}.
    The value of this keyword should be {\tt RANDOMIZE}.

  \item
    Create or update the header keyword {\tt RAND\_SKY} in the {\tt outfile}.
    The value of this keyword should be 0.5.

\end{enumerate}

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

% 8. Caveats

\subsection{ Caveats }

\begin{enumerate}

  \item
    The sub-pixel, event-positioning algorithms {\tt EDSER} and {\tt
    CENTROID} cannot produce a point spread function that is better than the
    point spread function produced by the mirrors and by the accuracy of the
    reconstruction of the pointing direction of the telescope.  They are not
    deconvolution algorithms.

  \item
    At this time, the effects of this sub-pixel algorithms {\tt EDSER} and
    {\tt CENTROID} on the point spread function of an astrophysical source
    are not calibrated.

  \item
    The use of a sub-pixel, event-positioning algorithm can influence the
    fraction of the events inside a source extraction region.  At present,
    this effect is not included in the response files.

  \item
    The algorithm {\tt CENTROID} can introduce a systematic offset in the
    coordinates of events.

\end{enumerate}

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

% 9. ARD

\section{Sub-pixel positioning ARD}
\label{ard}

The sub-pixel, event-positioning algorithm {\tt EDSER} requires input that is
specified in an ARD file.  Aside from a null primary header, the ARD file
includes ten separate HDUs (one HDU for each CCD).  Each HDU contains one
binary table with the following columns.
%
\begin{itemize}

  \item
    {\tt FLTGRADE}

  \item
    {\tt NPOINTS}

  \item
    {\tt ENERGY}

  \item
    {\tt CHIPX\_OFFSET}

  \item
    {\tt CHIPY\_OFFSET}

\end{itemize}
%
There is one row for each {\tt FLTGRADE}.  The columns {\tt ENERGY}, {\tt
CHIPX\_OFFSET}, and {\tt CHIPY\_OFFSET} contain vectors for each row.  These
vectors are used to perform the linear interpolation and extrapolation
described in section~\ref{edser}.  Only the first {\tt NPOINTS} elements in
the vectors should be used for this process. The remaining elements, if any,
are zero. The information in the ARD file is based on the data in Figure~4
of \cite{li04a}.

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

% 10. TBD

\section{TBD}

\begin{itemize}

  \item
    Should a sub-pixel event-positioning algorithm be applied to the spatial
    and temporal coordinates of continuous-clocking mode data?

  \item
    Should a sub-pixel algorithm be incorporated into the tool {\tt
    tg\_resolve\_events}?

\end{itemize}

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

% 11. References

\bibliographystyle{/nfs/cxc/h1/houck/bibtex/jwapjbib}
\bibliography{/nfs/inconceivable/d0/SRC/LATEX/refs}

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

% 12. Finish

\end{document}

