%+
% Name:
%   deltoclk_spec_1.1.tex
%
% History:
%   2011 Jun 03, created (v1.0), Glenn E. Allen
%   2011 Jun 09, removed mention of acis_format_events; added the
%     exposure-statistics file to the list of input files; added the
%     parameter minnumframes; added the definition of a valid frame; added a
%     description of what to do if frames are missing; added a definition of
%     median for even and odd numbers of elements; added the section "TBD"
%     (v1.1), GEA
%-

\documentclass{article}

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

\newrgbcolor{blue}{0 0 1}
\newrgbcolor{red}{1 0 0}

\begin{document}

% 1. Header

\memobasic{
   Jonathan McDowell, SDS Group Leader }{
   Glenn E.\ Allen, SDS }{
   {\tt DELTOCLK} spec }{
   1.1 }{
   http://space.mit.edu/CXC/docs/docs.html\#deltoclk }{
   /nfs/cxc/h2/gea/sds/docs/memos/deltoclk\_spec\_1.1.tex }

% 2. Description

\section{ Description }

Occasionally the values of {\tt DELTOCLK} in exposure-records files are
anomalously high or anomalously low.  {\red Since inaccurate values of {\tt
DELTOCLK} lead to inaccurate pulse heights}, events that are processed using
anomalous values have a {\tt STATUS} bit set to one and are discarded from
Level 2 event-data files.

% 3. Input

\section{ Input }

\begin{enumerate}

  \item
    One or more Level 0 event-data file (acis*evt0.fits) {\red or a Level 1
    event-data file (acis*evt1.fits)}

  \item
    One or more exposure-records file (acis*exr0.fits)

  \item
    {\red An exposure-statistics file (acis*stat1.fits)}

\end{enumerate}

% 4. Output

\section{ Output }

\begin{enumerate}

  \item
    An {\red updated} event-data file

  \item
    An {\red updated} exposure-statistics file

\end{enumerate}

% 5. Parameters

\section{ Parameters }

\begin{enumerate}

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

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

  \item
    { \tt exrfile,f,a,"",,,"Name of input exposure-records file" }

  \item
    { \tt expstatsfile,f,a,"",,,"Name {\red of exposure}-statistics file" }

  \item
    { \tt expnowidth,i,h,5,3,1001,"Number of frames in the sliding time
    window {\red (must be odd)}" }

  \item
    { \tt \red minnumframes,i,h,3,3,1001,"Minimum number of frames in window
    with useful data" }

  \item
    { \tt deltoclkthresh,i,h,{\red{3}},1,4096,"Minimum offset {\red in adu
    that is considered anomalous}" }

\end{enumerate}

% 6. Processing

\section{ Processing }

\begin{enumerate}

  \item
    Verify that the {\tt infile}, {\tt exrfile}, and {\tt \red expstatsfile}
    exist.
    %
    If {\tt clobber=no}, then verify that the {\red {\tt outfile} does} not
    exist.
    %
    Verify that the values of the parameters {\tt expnowidth}, {\tt \red
    minnumframes} and {\tt deltoclkthresh} are in the valid ranges for these
    parameters.
    %
    Note that {\tt expnowidth} must be an odd number.

  \item
    {\red
    If the data are being reprocessed by a user, then perform the following
    two steps.
    %
    \begin{enumerate}

      \item
        Set {\tt STATUS} bit 10 (of 0-31) to zero (i.e.\ unset it) for all
	of the events in the {\tt outfile}.  Subsequent processing sets this
	bit to one for the appropriate events.

      \item
        Remove the contents of the HDU ``{\tt BADOCLK}'' in the {\tt
	expstatsfile}. This HDU is updated appropriately in subsequent
	processing.

    \end{enumerate}
    }

  \item
    Perform the following steps separately for each node of each CCD.
    %
    \begin{enumerate}

      \item
        For each {\red valid}%
	%
	\footnote{\red Here, a frame is valid if there is {\tt DELTOCLK} data
	available for it.  If no {\tt DELTOCLK} data are available for the
	frame, then it is considered invalid.}
	%
	frame $i$, compute the expected value $M_{i}$ of {\tt
	DELTOCLK}.  In most cases, $M_{i}$ is the median%
	%
	\footnote{\red If the number of elements in the set for which the
	median is being computed is odd, then the median is the middle value
	of the set after the set has been sorted (e.g.\ the median of
	[1,1,1,4,5,6,7] is 4).  If the number of elements is even, then the
	median is the mean of the middle two values of the sorted set.  If
	the mean is not an integer, then the mean is truncated to obtain an
	integer (e.g.\ the median of [1,1,1,4,5,6] is 2, not 2.5 or 1).}
	%
	of the values of {\tt DELTOCLK} for the frames from $i-w$ to
	$i+w${\red, inclusive}, where $w = ( {\tt expnowidth} - 1 ) / 2$.
	There are some cases that require special treatment.
	%
	\begin{enumerate}

	  \item
	    If the frames range from $i=1$ to $N$, then for the first frame
	    (i.e.\ for $i=1$) $M_{1}$ is the median value of {\tt DELTOCLK}
	    for the frames from 1 to $1+w$, for the second frame (i.e.\ for
	    $i=2$) $M_{2}$ is the median value of {\tt DELTOCLK} for the
	    frames from 1 to $2+w$, etc.

	  \item
	    If the frames range from $i=1$ to $N$, then for the last frame
	    (i.e.\ for $i=N$) $M_{N}$ is the median value of {\tt DELTOCLK}
	    for the frames from $N-w$ to $N$, for the second to the last
	    frame (i.e.\ for $i=N-1$) $M_{N-1}$ is the median value of {\tt
	    DELTOCLK} for the frames from $N-1-w$ to $N$, etc.

          \item
	    {\red If one or more frames in the range for which $M_{i}$ is
	    being computed is invalid$^{1}$ and if the total number of valid
	    frames in this range is greater than or equal to {\tt
	    minnumframes}, then perform the computation using the data for
	    the valid frames.}

          \item
	    {\red If one or more frames in the range for which $M_{i}$ is
	    being computed is invalid$^{1}$ and if the total number of valid
	    frames in this range is less than {\tt minnumframes}, then set
	    $M_{i}$ equal to the value of {\tt DELTOCLK} for frame $i$
	    (i.e.\ there is too little data to determine whether the value
	    of {\tt DELTOCLK} is anomalous).}

	\end{enumerate}

      \item
        If the value of {\tt DELTOCLK} for a frame is greater than or equal
	to $M_{i} + {\tt deltoclkthresh}$ or is less than or equal to $M_{i}
	- {\tt deltoclkthresh}$, then
	%
	\begin{enumerate}
	  \item
	    modify the {\tt outfile} to
	    set {\tt STATUS} bit 10 (of 0-31) to one for all of the events
	    in frame $i$ for the particular CCD and node in question and
	  \item
	    update the ``{\tt BADOCLK}'' HDU of the {\tt expstatsfile} to
	    include the {\tt EXPNO}, {\tt CCD\_ID}, and {\tt NODE\_ID}
	    information for the frame, CCD, and node in question.
	\end{enumerate}

    \end{enumerate}

\end{enumerate}

% 7. TBD

\section{ TBD }

{\red
\begin{enumerate}

  \item
    How should dropped frames be handled (as described here or otherwise)?
    Look at the data to get an idea.

  \item
    Should there be tests on the absolute values of the overclocks (not just
    the values of the DELTOCLKs) or should such tests be part of V\&V?

  \item
    Add some diagnostic plots (e.g.\ a histogram of ${\tt DELTOCLK} -
    M_{i}$ [for different definitions of the median?], a plot of the
    fraction of the data that satisfy the {\tt deltoclkthresh} condition as
    a function of {\tt deltoclkthresh} [separately for each node?], and a
    plot of the rate at which anomalous values of {\tt DELTOCLK} occur as a
    function of time [separately for each node?]).

\end{enumerate}
}

% 8. Finish

\end{document}

