%+
% Name:
%   subpix_spec_0.1.tex
%
% History:
%   2010 May 07, created (v0.1), Glenn E. Allen
%-

\documentclass{article}

\usepackage{changebar}
\usepackage{cxo-memo-logo}
\usepackage[dvips]{graphics}
\usepackage{epsfig}
\usepackage{gea}
\usepackage[sort&compress]{natbib}

\begin{document}

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

% 1. Header

\memobasic{
   Jonathan McDowell, SDS Group Leader }{
   Glenn E.\ Allen, SDS }{
   Sub-pixel event-positioning spec }{
   0.1 }{
   http://space.mit.edu/CXC/docs/docs.html\#subpix }{
   /nfs/cxc/h2/gea/sds/docs/memos/subpix\_spec\_0.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, which include the size of
the point spread function of the mirrors, the size of the pixels on the ACIS
CCDs, the introduction of a uniform random deviate to the CCD coordinates
when computing the detector coordinates and, subsequently, the sky
coordinates (\ie\ ``pixel randomization''), and the accuracy to which the
pointing direction can be reconstructed.

Pixel 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.  This randomization can be disabled by setting the {\tt
acis\_process\_events} parameter ${\tt rand\_pix\_size} = 0$.

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, particularly if events are
assumed to occur 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 locate 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 VFAINT mode, {\tt PHAS} is a $5 \times 5$ array instead of a
$3 \times 3$. The {\tt PHAS} information is not telemetered for GRADED mode
data. However, the {\tt FLTGRADE}, a scalar representation of the
distribution of charge in the central $3 \times 3$, is telemetered for both
GRADED and non-GRADED modes.  Only one of sub-pixel event-positioning
algorithms requires {\tt PHAS} (\ie\ the algorithm ``CSDSER'').  All of the
rest use the {\tt FLTGRADE}.}''

This spec describes the implementation of the energy-dependent sub-pixel
event-positioning algorithm (``EDSER'') of \cite{li04a} in the tool {\tt
acis\_process\_events}.  This algorithm is the one that works best for
GRADED and non-GRADED mode event data.

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

% 4. Input

\subsection{ Input }

\begin{enumerate}

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

 \item
    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,
    perhaps, {\tt X} and {\tt Y} have been updated.  Note that the
    coordinates {\tt CHIPX}, {\tt CHIPY}, {\tt TDETX}, and {\tt TDETY} are
    not modified.

\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 bad-pixel file" }

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

  \item
    { \tt apply\_subpix,b,h,"yes",,,"Apply the sub-pixel location
    adjustment? (yes | no)" }

\end{enumerate}

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

% 7. Processing

\subsection{ Processing }
\label{proc}

In the standard ACIS pipeline, the sub-pixel event-positioning algorithm
should be performed after the {\tt ENERGY} and {\tt FLTGRADE} have been
computed since the algorithm depends upon these quantities.  The calculation
should occur before the detector coordinates {\tt DETX} and {\tt DETY} are
calculated since these coordinates depend upon the results of the sub-pixel
positioning.  If the sky coordinates {\tt X} and {\tt Y} are calculated,
then the calculation should use the updated values of {\tt DETX} and {\tt
DETY}.

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

  \item
    Verify that the input files exist.  If they do not, then exit with an
    error message.

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

  \item
    Verify that the parameter ${\tt rand\_pix\_size} = 0$.  If it is not,
    then exit with an error message.

  \item
    Verify that the parameter ${\tt stop} = {\rm det}$, tan, or sky.  If it
    is not, then exit with an error message.

\end{itemize}
%

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 locations of ${\tt CHIPX}'$ and
    ${\tt CHIPY}'$, respectively.  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}).}
    %
    Therefore, 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 shall $i < 0$. 

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

\end{enumerate}

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

% 8. Caveats

\subsection{ Caveats }

\begin{enumerate}

  \item
    A sub-pixel event-positioning algorithm 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.  It is not a deconvolution algorithm.

  \item
    At this time, the point spread function for data which has had this
    sub-pixel event-positioning algorithm applied is 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 tools.

\end{enumerate}

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

% 9. ARD

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

The sub-pixel event-positioning algorithm requires input that is specified
in an ARD file.  Aside from a null primary header, the ARD file includes ten
separate HDUs (one for each CCD), with one binary table per HDU.  Each
binary table includes 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{proc}.  Only the first {\tt NPOINTS} elements in
the vectors should be used for this process. The remaining elements, if any,
contain zeroes. The information in the ARD file is based on the data in
Figure~4 of \cite{li04a}.

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

% 10. References

\bibliographystyle{/nfs/cxc/h1/houck/bibtex/jwapjbib.bst}
\bibliography{/nfs/cxc/h2/gea/Src/Latex/refs}

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

% 11. Finish

\end{document}

