%+
% 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}