%+
% Name:
%   memo_acis_build_badpix_2.0.tex
%
% History:
%   2006 Aug 16, created (v1.0), Glenn E. Allen
%   2007 Jan 22, fixed a sign error (v1.1), GEA
%   2007 Feb 01, removed specific mention of the usrfile having to be ASCII
%     and added a comment about the same pixel on multiple lines in the input
%     usrfile.
%   2008 Apr 18, made the bitflag table a little easier to read (v1.3), GEA
%   2008 Aug 14, changed the range and default value for bit 8 (v1.4), GEA
%   2008 Nov 24, changed the range for bit 9 (v1.5), GEA
%   2009 Feb 20, perform all of the steps for a pixel, not just the last one
%     in the usrfile; exclude applies only to the specified STATUS bit
%     (v1.6), GEA
%   2009 Mar 04, changed allowed values of bitflag for bit 7 to only 1;
%     added some error conditions for usrfiles with ACTION=''include'' for
%     bits 5, 6, or 9 (v1.7), GEA
%   2009 Mar 06, changed allowed values of bitflag for bit 7 back to 1-2;
%     added the error condition that bit can't equal 8, 9, or 10 in a usrfile
%     (v1.8), GEA
%   2009 Mar 13, significantly revised (v2.0), GEA
%-

\documentclass{article}

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

\begin{document}

\newcommand{\bitflag}{\tt{bitflag}\rm}
\newcommand{\usrfile}{\tt{usrfile}\rm}
\newcommand{\tool}{\tt{acis\_build\_badpix}\rm}

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

% 1. Header

\memobasic{
   Jonathan McDowell, SDS Group Leader }{
   Glenn E.\ Allen, SDS }{
   \tool }{
   2.0 }{
   http://space.mit.edu/CXC/docs/docs.html\#abb }{
   /nfs/cxc/h2/gea/sds/docs/memos/memo\_acis\_build\_badpix\_2.0.tex }

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

% 2. Introduction

\vspace*{0.3in}
%
To make it easier to customize observation-specific bad-pixel files, the
tool \tool\ includes the new parameters \bitflag\ and \usrfile. The
parameter \bitflag\ enables users to ignore selected types of bad pixels.
For example, a user can choose not to include cosmic-ray afterglows, hot
pixels, and/or node boundaries in the output bad-pixel file. The same
parameter can also be used to prevent \tool\ from identifying the neighbors
of bad pixels as bad. For example, it is possible to identify the pixels
next to bad pixels as bad, but not the columns next to bad columns.

The parameter \usrfile\ can be used to specify the name of an optional
user-created input file.  The input file contains a list of instructions
that cause \tool\ to add specific bad pixels to and/or remove specific bad
pixels from the output bad-pixel file.

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

% 3. Changes

\section{Changes to \tool}
\label{changes}

\subsection{Additional Parameters}

\begin{enumerate}

  \item
    \usrfile,f,h,``none'',,,``An optional, user-created, bad-pixel file
    (NONE | none | $<$filename$>$)''

  \item
    \bitflag,s,h,``00000000000000022221100020022222'',,,``A 32-character
    string where 0$=$exclude pixel, 1$=$ include pixel, but not its
    neighbors, and 2$=$include pixel and its neighbors''

\end{enumerate}

Each character in the parameter \bitflag\ corresponds to one of the 32
STATUS bits.  These characters are associated with bits 0 to 31, from right
to left.  The acceptable and default values for each bit are listed in
Table~\ref{tab01}.

\subsection{Additional Input}

The parameter \usrfile\ can be used to specify an optional, user-created,
input file that has one or more rows.  Each row has exactly nine
tab-delimited columns.  From left to right, these columns are

\begin{enumerate}

  \item
    CCD\_ID,

  \item
    CHIPX\_LO,

  \item
    CHIPX\_HI,

  \item
    CHIPY\_LO,

  \item
    CHIPY\_HI,

  \item
    TIME,

  \item
    TIME\_STOP,

  \item
    BIT, and

  \item
    ACTION.

\end{enumerate}

The integers CCD\_ID, CHIPX\_LO, CHIPX\_HI, CHIPY\_LO, and CHIPY\_HI specify
the region of interest.  TIME and TIME\_STOP describe the time interval
during which the specified region is affected. The ACTION string determines
whether the specified BIT is set or unset for the region during this
interval. Note that \tool\ is not sensitive to the case of the ACTION
string.

\begin{table}
  \caption{Acceptable and default \bitflag\ characters\label{tab01}}
  \begin{center}
    \begin{tabular}{cccl}
      \hline
      & Default & Valid & \\
      Bit & value & values & Comments \\
      \hline
      0--4  & 2 & 0--2 & \\
      5--6  & 0 & 0    & \begin{changebar} These are in the msk1.fits file.
                         \end{changebar} \\
      7     & 2 & 1--2 & A ``0'' would be confusing with a usrfile. \\
      8     & 0 & 0    & Specified by using a ``2'' for the other bits \\
      9--10 & 0 & 0    & Obsolete \\
      11--12& 1 & 0--2 & \\
      13--16& 2 & 0--2 & \\
      17--31& 0 & 0    & Unused \\
      \hline
    \end{tabular}
  \end{center}
\end{table}

\subsection{Processing}
\label{proc}

\begin{enumerate}

  \item
    \label{step01}
    %
    Verify that there are no input errors.

    \begin{itemize}

      \item[a.]
        Errors associated with the parameter \usrfile\ include rows that

        \begin{itemize}

          \item
            do not have exactly nine input values,

          \item
            have a CCD\_ID that is not one of the CCD\_IDs included in the
	    list of active CCDs in the ``PBK'' extension of the
	    parameter-block file,

          \item
            have ${\rm CHIPX\_LO} < 1$, ${\rm CHIPX\_HI} > 1024$, or ${\rm
	    CHIPX\_HI} < {\rm CHIPX\_LO}$,

          \item
            have ${\rm CHIPY\_LO} < 1$, ${\rm CHIPY\_HI} > 1024$, or ${\rm
	    CHIPY\_HI} < {\rm CHIPY\_LO}$,

          \item
            have ${\rm TIME} < 0$ or ${\rm TIME\_STOP} \le {\rm
	    TIME}$\footnote{${\rm TIME\_STOP}$ may be equal to ${\rm TIME}$
	    if and only if ${\rm TIME} = {\rm TIME\_STOP} = 0$.},

          \item
	    \begin{changebar}
	    have ${\rm BIT} < -1$\footnote{A row with ${\rm BIT} = -1$ is
	    valid if and only if ACTION $=$ ``exclude''. If ACTION $=$
	    ``include'', then BIT cannot be less than zero.}, ${\rm BIT} =
	    5$, ${\rm BIT} = 6$, ${\rm BIT} = 8$, ${\rm BIT} = 9$, ${\rm
	    BIT} = 10$, or ${\rm BIT} > 16$,
	    \end{changebar}

	  \item
	    have an ACTION other than ``include'' or ``exclude'',

	  \item
	    \begin{changebar}
	    have ACTION $=$ ``include'', but the \bitflag\ character for the
	    specified bit is ``0'',
	    \end{changebar}

          \item
	    have ${\rm BIT} = 11$ and (${\rm CHIPX\_LO} < 512$ or ${\rm
	    CHIPX\_HI} > 513$), and

	  \item
	    \begin{changebar}
	    have ${\rm BIT} = 13$ and ${\rm CHIPY\_LO} < 512$.
	    \end{changebar}

        \end{itemize}

        If there is an error with one or more rows of the \usrfile, then
	produce a warning message, ignore the entire \usrfile, and continue
	processing.

      \item[b.]
        Errors associated with the parameter \bitflag\ include

        \begin{itemize}

          \item
            a string that does not have exactly 32 characters, and

          \item
            a string where one or more characters has an invalid value.  The
	    valid values for each character are listed in Table~\ref{tab01}.

        \end{itemize}

      If there is an error with the parameter \bitflag, then exit with an
      error message.

    \end{itemize}

  \item
    As necessary, process the CALDB, bias, bias-parity error, and Level 0
    event files. However, only set the appropriate STATUS bit to one if the
    corresponding character in \bitflag\ is a ``1'' or ``2''.  At this stage
    in the processing, do not set STATUS bit 8 to one for pixels adjacent to
    bad pixels.

  \item
    If necessary, process each row of the \usrfile\ in sequence.  It is
    important to apply the instructions in order because a pixel may be
    affected by more than one row in the \usrfile.

    \begin{itemize}

      \item[a.]
        If a row has ACTION $=$ ``include'', then the specified STATUS bit
	is set to one for the pixels in the region defined by CCD\_ID,
	CHIPX\_LO, CHIPX\_HI, CHIPY\_LO, and CHIPY\_HI for the time interval
	from TIME to TIME\_STOP\footnote{If ${\rm TIME} = {\rm TIME\_STOP} =
	0$, then TIME and TIME\_STOP are the times associated with the
	beginning and end of the observation, respectively.}.  Note that the
	bit is set to one if and only if the corresponding character in
	\bitflag\ is a ``1'' or ``2''.  If the \bitflag\ character is ``0'',
	then this represents an error in the \usrfile\ (see
	step~\ref{step01}).  Note that other STATUS bits may be set to one
	for pixels in the region.  Again, do not set STATUS bit 8 to one for
	pixels adjacent to bad pixels at this stage.

      \item[b.]
        If a row has ACTION $=$ ``exclude'', then set the specified STATUS
	bit to zero\footnote{\begin{changebar}If ${\rm BIT} = -1$, then set
	all 32 STATUS bit to zero.\end{changebar}} for the pixels in the
	region defined by CCD\_ID, CHIPX\_LO, CHIPX\_HI, CHIPY\_LO, and
	CHIPY\_HI for the time interval from TIME to
	TIME\_STOP\footnotemark[3]. It does not matter what the
	corresponding \bitflag\ character is.  Note that a pixel may remain
	bad if other STATUS bits are set to one. The output may become
	complicated if the specified time interval is only a subset of the
	observation.

    \end{itemize}

  \item
    Once all of the input files have been processed, set STATUS bit 8 to one
    for all pixels that are adjacent to bad pixels provided that the
    corresponding value of \bitflag\ is ``2''.  If a bad pixel has more than
    one STATUS bit set to one and the \bitflag\ character for at least one
    of the STATUS bits is ``2'', then set STATUS bit 8 to one for the
    adjacent pixels.

\end{enumerate}

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

% 4. Finish

\end{document}

