%+
% Name:
%   memo_acis_build_badpix_1.4.tex
%
% Usage:
%
% Description:
%
% Input:
%
% Output:
%
% Notes:
%
% 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
%-

\documentclass{article}

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

\begin{document}

\newcommand{\tool}{acis\_build\_badpix}

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

% 1. Header

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

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

% 2. Introduction

\vspace*{0.3in}
%
To make it easier to customize observation-specific bad-pixel files, the
tool acis\_build\_badpix includes two enhancements.  One enhancement permits
users to ignore selected bad-pixel criteria.  For example, a user can choose
not to include cosmic-ray afterglows, hot pixels, and/or node boundaries in
the output bad-pixel file.  This functionality is embodied in the parameter
{\tt bitflag}.  The same parameter can be used to prevent the code from
identifying the neighbors of bad pixels as bad.  For example, it is possible
to prevent the code from flagging the columns next to bad columns as bad,
but still flag pixels next to other bad pixels as bad.

A second enhancement enables users to include or exclude specific regions
from the output file by preparing a supplemental file that includes a list
of the regions of interest. The name of the supplemental input file is
specified via the parameter {\tt usrfile}.

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

% 3. Changes

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

\subsection{Additional Parameters}

\begin{enumerate}

  \item
    usrfile,f,h,``none'',,,``User-specified supplemental bad-pixel file
    (NONE | none | $<$filename$>$)''

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

\end{enumerate}

\subsection{Additional Input}

The user has the option of specifying a supplemental input file which
includes one row for each pixel, column or region.  Each row has exactly
nine columns that are tab or space delimited.  The columns are, from left to
right along a row,

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

\subsection{Processing}
\label{proc}

\subsubsection{usrfile}

If the parameter {\tt usrfile} is not ``none'' or ``NONE'' and specifies an
existing file, then read each row of the file. If an error is detected in
any row of the file, then write a warning message, ignore the entire file
and continue processing.  The possible error conditions include a row that

\begin{itemize}

  \item
  does not have nine input values,

  \item
  has 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
  % has ${\rm CCD\_ID} < 0$ or ${\rm CCD\_ID} > 9$ (in case no par),
  % (This is superseded by the previous condition.)

  \item
  has a chip coordinate $<$ 1 or $>$ 1024,

  \item
  has a lower chip coordinate $>$ the corresponding upper chip coordinate,

  \item
  has a beginning or ending time $<$ 0,

  \item
  has a beginning time $>=$ the ending time,

  \item
  has BIT $<$ 0 or $>$ 31 or

  \item
  has an ACTION other than ``include'' or ``exclude.''

\end{itemize}

Note that the tool is not sensitive to the case of ACTION.  If ACTION $=$
``include,'' then modify the output bad-pixel file to include a region with
the following attributes.

\begin{itemize}

  \item
  The input CCD\_ID determines which extension is modified.

  \item
  The SHAPE is ``point'' if CHIPX\_LO $=$ CHIPX\_HI and CHIPY\_LO $=$
  CHIPY\_HI.  Otherwise, SHAPE $=$ ``rectangle.''

  \item
  The value of COMPONENT is determined in the usual manner.

  \item
  The two values in the double-valued vector column CHIPX are CHIPX\_LO and
  CHIPX\_HI.

  \item
  The two valued in the double-valued vector column CHIPY are CHIPY\_LO and
  CHIPY\_HI.

  \item
  The value of TIME is the same as the input value unless the input values
  of TIME and TIME\_STOP are both zero.  In this case, set TIME equal to the
  time associated with the beginning of the observation.

  \item
  The value of TIME\_STOP is the same as the input value unless the input
  values of TIME and TIME\_STOP are both zero.  In this case, set TIME\_STOP
  equal to the time associated with the end of the observation.

  \item
  The specified BIT of STATUS is set to one.  Note that other bits may be
  set to one for the region, if it is bad for other reasons.

\end{itemize}

If ACTION $=$ ``exclude,'' then modify the output bad-pixel file so that any
pixel in the region specified by CCD\_ID, CHIPX\_LO, CHIPX\_HI, CHIPY\_LO
and CHIPY\_HI is not regarded as bad for the time interval from TIME to
TIME\_STOP.  (The output may become complicated if the time interval is only
a subset of the observation.) Note that the rules about TIME $=$ 0 and
TIME\_STOP $=$ 0 also apply if ACTION $=$ ``exclude.'' Although a row must
include a valid value for BIT if ACTION $=$ ``exclude,'' this information is
ignored.

If more than one row of the {\tt usrfile} describes the same pixel, then the
information on the last row supersedes the information on previous rows.

\subsubsection{bitflag}

Verify that the contents of the parameter {\tt bitflag} are valid.  This
parameter should be a thirty-two character string, where the characters
correspond to STATUS bits 0--31 from right to left.  The acceptable and
default values for each character are listed below.

\begin{center}
  \begin{tabular}{cccl}
    \hline
    & Default & Valid & \\
    Bit & value & values & Comments \\
    \hline
    0--4   & 2 & 0--2 & \\
    5--6   & 0 & 0--1 & A ``2'' doesn't make sense. \\
    7      & 2 & 1--2 & Zero would be confusing if a {\tt usrfile} is
                        specified. \\
    8$^{a}$& 0 & 0    & \begin{changebar} Adjacent pixels \end{changebar} \\
    9--10  & 0 & 0--1 & A ``2'' doesn't make sense. \\
    11--12 & 1 & 0--2 & \\
    13--16 & 2 & 0--2 & \\
    17--31 & 0 & 0    & Unused \\
    \hline
    %
    \multicolumn{4}{l}{$^{a}$ 
      \parbox[t]{4.55in}{
        \begin{changebar}
          The use of bit 8 of the parameter {\tt bitflag} is not
	  appropriate. Pixels adjacent to a bad pixel have STATUS bit 8 set
	  if and only if the corresponding {\tt bitflag} value for the pixel
	  is ``2.''
        \end{changebar}
        }
      }
    %
  \end{tabular}
\end{center}

The action associated with each character is:

\begin{itemize}

  \item[0:]
  Ignore a bad pixel or column.  Do not write such regions to the output
  file unless they satisfy another condition.  If they do satisfy another
  condition, then the STATUS bit(s) for which {\tt bitflag} $=$ ``0'' are
  set to zero.  For example, if the characters in the {\tt bitflag}
  associated with STATUS bits 14 (hot pixels) and 15 (afterglows) are ``0,''
  then exclude hot pixels and afterglows from the output bad-pixel file and
  do not set STATUS bits 14 and 15 to one for any pixels.

  \item[1:]
  Include a bad pixel or column, but not the pixels or columns adjacent to
  it. For example, if the character in the {\tt bitflag} associated with
  STATUS bit 1 (bad columns) is ``1,'' then the bad columns at CHIPX $=$ 66,
  496--8 and 738 for CCD\_ID $=$ 7 are marked as bad in the output file, but
  not the columns at CHIPX $=$ 65, 67, 495, 499, 737 and 739.  STATUS bit 8
  is set to zero for the columns at CHIPX $=$ 66, 496--8 and 738.

  \item[2:]
  Include a bad pixel or column and the pixels or columns adjacent to it.
  For example, if the character in the {\tt bitflag} associated with STATUS
  bit 1 (bad columns) is ``2,'' then the bad columns at CHIPX $=$ 66, 496--8
  and 738 for CCD\_ID $=$ 7 are marked as bad in the output file.  In
  addition, the columns at CHIPX $=$ 65--67, 495--499 and 737--739 have
  STATUS bit 8 set to one.

\end{itemize}

After the input in the {\tt usrfile} and other files has been processed, set
the adjacent bits using the standard rules, within the constraints of the
parameter {\tt bitflag}.

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

% 4. Finish

\end{document}

