%+
% Name:
%   subpix_spec_0.3.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
%-

\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 }{
   0.3 }{
   http://space.mit.edu/CXC/docs/docs.html\#subpix }{
   /nfs/cxc/h2/gea/sds/docs/memos/subpix\_spec\_0.3.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{\begin{changebar} 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.
\end{changebar}}
%
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.  \begin{changebar} 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}. \end{changebar}}

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 { \bf \red (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
    {\tt DATAMODE = CC\_FAINT} or {\tt CC\_GRADED}), then exit with an error
    message.  { \bf \red Other modes?}

  \item
    \begin{changebar}
    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 = CC\_FAINT}, {\tt CC\_GRADED} or {\tt GRADED}), then exit with
    an error message.  { \bf \red Other modes?}
    \end{changebar}

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

\end{itemize}

If {\tt pix\_adj = none}, then do not use \begin{changebar} a
\end{changebar} 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 \begin{changebar} greater
than or equal to $-0.5$ and less than $+0.5$~adu.$^{1}$\ \ Do not use a
\end{changebar} sub-pixel algorithm. 

\begin{changebar}
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.  
\end{changebar}

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{\begin{changebar} 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 \end{changebar} 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}. 
    %
    If {\tt pix\_adj = edser} or \begin{changebar} {\tt centroid},
    \end{changebar} then set {\tt RAND\_SKY = 0}. 
    %
    \begin{changebar}
    If {\tt pix\_adj = none} and {\tt stop = none}, {\tt chip}, {\tt tdet},
    or {\tt det} 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}.
    %
    If {\tt pix\_adj = none} and {\tt sky} { \bf \red or {\tt tan} }, then
    set {\tt RAND\_SKY = 0}.
    %
    If {\tt pix\_adj = randomize}, then set {\tt RAND\_SKY = 0.5}.
    \end{changebar}

\end{enumerate}

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

% 8. Caveats

\subsection{ Caveats }

\begin{enumerate}

  \item
    The sub-pixel event-positioning \begin{changebar} algorithms {\tt edser}
    and {\tt centroid} \end{changebar} 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.  \begin{changebar} They are not
    deconvolution algorithms. \end{changebar}

  \item
    At this time, the effects of this sub-pixel \begin{changebar} algorithms
    {\tt edser} and {\tt centroid} \end{changebar} 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 \begin{changebar} files.
    \end{changebar}

\end{enumerate}

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

% 9. ARD

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

The sub-pixel event-positioning algorithm \begin{changebar} {\tt edser}
\end{changebar} 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 \begin{changebar} a \end{changebar} 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}

