%+
% Name:
%   subpix_spec_1.0.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
%-

\documentclass{article}

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

\newrgbcolor{red}{1 0 0}

\begin{document}

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

% 1. Header

\memobasic{
   Jonathan McDowell, SDS Group Leader }{
   Glenn E.\ Allen, SDS }{
   Sub-pixel event-positioning spec }{
   1.0 }{
   http://space.mit.edu/CXC/docs/docs.html\#subpix }{
   /nfs/cxc/h2/gea/sds/docs/memos/subpix\_spec\_1.0.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
range from $-0.5$ to $+0.5$~adu%
%
\footnote{Actually, the range used to be controlled by the parameter {\tt
rand\_pix\_size}.  The default value of the parameter was 0.5.  With the
implementation of the sub-pixel event-positioning algorithm {\tt EDSER}, the
use of the parameter {\tt rand\_pix\_size} has been discontinued.  It is
still possible to apply a pixel randomization, but it is no longer possible
to control the range of the randomization.}
%
to the chip coordinates {\tt CHIPX} and {\tt CHIPY} when the detector
coordinates {\tt DETX} and {\tt DETY} are calculated. This randomization is
propagated to the sky coordinates {\tt X} and {\tt Y}. 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.  The
randomization is automatically disabled if the 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, 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 {\tt VFAINT} mode, {\tt PHAS} is a $5 \times 5$ array instead
of a $3 \times 3$. The {\tt PHAS} information is not telemetered for {\tt
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 {\tt GRADED} and non-{\tt GRADED} modes.  The sub-pixel
event-positioning algorithms ``CSDSER'' (Li \etal\ 2004) and {\tt CENTROID}
(see sec.~\ref{proc}) require {\tt PHAS}. The rest of the algorithms use
{\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
    \begin{changebar}
    { \tt pix\_adj,s,h,"EDSER",,,"Sub-pixel adjustment algorithm\ (EDSER |
    CENTROID | NONE | \\ RANDOMIZE)" }
    \end{changebar}

\end{enumerate}

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

% 7. Processing

\subsection{ Processing }
\label{proc}

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

  \item
    Verify that the {\tt infile} and {\tt subpixfile} exist.  If they do
    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
    \begin{changebar} {\tt DATAMODE = CC33\_FAINT} or {\tt CC33\_GRADED}),
    \end{changebar} 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
    \begin{changebar} {\tt DATAMODE = CC33\_FAINT}, {\tt CC33\_GRADED}
    \end{changebar} or {\tt GRADED}), then exit with an error message.

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

\end{itemize}

If {\tt pix\_adj = NONE}, then do not use a sub-pixel event-positioning
algorithm or the pixel randomization algorithm.

If {\tt pix\_adj = RANDOMIZE}, then apply the pixel randomization algorithm,
where the range of the uniform random deviate is greater than or equal to
$-0.5$ and less than $+0.5$~adu.$^{1}$\ \ Do not use a sub-pixel algorithm.

If {\tt pix\_adj = CENTROID}, then use the sub-pixel event-positioning
algorithm that used to be associated with the parameter {\tt docentroid}.%
%
\footnote{With the implementation of the sub-pixel event-positioning
algorithm {\tt EDSER}, the use of the parameter {\tt docentroid} has been
discontinued.}\ \
%
Do not apply the pixel randomization.

If {\tt pix\_adj = EDSER}, then use the sub-pixel algorithm described below.
Do not apply the pixel randomization.  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 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.%
    %
    \footnote{In no case does $| {\tt CHIPX}' - {\tt CHIPX} |$ or $| {\tt
    CHIPY}' - {\tt CHIPY} |$ 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
    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}.

  \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}.%
    %
    \footnote{This action pertains to both sub-pixel algorithms {\tt EDSER}
    and {\tt CENTROID}.  Although {\tt chipx\_adj} and {\tt chipy\_adj} are
    excluded from {\tt eventdef} by default, the data in these columns is
    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}.
    This keyword should have the same value as the parameter {\tt pix\_adj}.

  \item
    Create or update the header keyword {\tt RAND\_SKY} in the {\tt
    outfile}.

    \begin{itemize}

      \item
        If {\tt pix\_adj = EDSER} or {\tt CENTROID}, then set {\tt RAND\_SKY
	= 0}.

      \item
        If {\tt pix\_adj = NONE} and {\tt stop = NONE}, {\tt chip}, {\tt
	tdet}, \begin{changebar} {\tt det}, or {\tt tan}, \end{changebar}
	then copy the value of {\tt RAND\_SKY} from the {\tt infile} to the
	{\tt outfile}.  If the keyword does not exist in the {\tt infile},
	then set {\tt RAND\_SKY = 0}.

      \item
        If {\tt pix\_adj = NONE} and \begin{changebar} {\tt stop = sky},
        \end{changebar} then set {\tt RAND\_SKY = 0}.

      \item
        If {\tt pix\_adj = RANDOMIZE}, then set {\tt RAND\_SKY = 0.5}.

    \end{itemize}

\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.

\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{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. 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.bst}
\bibliography{/nfs/cxc/h2/gea/Src/Latex/refs}

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

% 12. Finish

\end{document}

