%+
% Name:
%   bias_repair_2.0.tex
%
% History:
%   2009 Aug 12, created (v1.0), Glenn E. Allen
%   2009 Aug 26, added a description of the criteria used to identify a
%     replacement bias; added a reference to Peter Ford's Perl script
%     search4bias; added a change to the header keywords INITOCLx; added
%     a note to include suitable HISTORY keywords (v2.0), GEA
%-

\documentclass{article}

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

\begin{document}

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

% 1. Header

\memobasic{
   Jonathan McDowell, SDS Group Leader }{
   Glenn E.\ Allen, SDS }{
   Bias repair }{
   2.0 }{
   http://space.mit.edu/CXC/docs/docs.html\#bias\_rep }{
   /nfs/cxc/h2/gea/sds/docs/memos/bias\_repair\_2.0.tex }

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

% 2. Description

\section{ Introduction }

Biases can be adversely affected for a number of reasons, including the
interaction of charged particles in the detector, the transmission of
optical light through the optical-blocking filter (\eg\ Fig.~\ref{fig01}),
and the loss of part or all of the bias telemetry.  In order to produce the
most accurate ACIS event data possible, biases may have to be repaired or
replaced.  If a problem affects an entire CCD, then replacement of the bias
for the CCD is necessary.  This spec describes how to replace a bias for one
observation with a modified version of a bias from another observation.

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

% 3. Replacement

\section{ Replacement }

The following steps should be performed in sequence to replace bias file $B$
for an observation (\eg\ a bias file for OBS\_ID 11799, Fig.~\ref{fig01})
with bias file $B'$ from another observation (\eg\ a bias file for OBS\_ID
9345, Fig.~\ref{fig02}). 

\begin{enumerate}

  \item
    \begin{changebar}
    Identify\footnote{Peter Ford's Perl script
    /nfs/acis/h4/tools/bin/sun4/search4bias.pl can be used to identify a
    suitable replacement file.} and copy a suitable bias file $B'$.  The
    bias file $B'$ is suitable if the following conditions are satisfied.
    %
    \begin{enumerate}

      \item[a.]
        The bias file $B'$ is for the same CCD as the bias file $B$.

      \item[b.]
        The parameter-block keywords
	%
        \begin{eqnarray}
          {\rm BEP\_MODE}' & = & {\rm BEP\_MODE}, \label{eqn01} \\
          {\rm DEALOAD}' & = & {\rm DEALOAD}, \\
          {\rm DTYCYCLE}' & = & {\rm DTYCYCLE}, \\
          {\rm EXP\_SKIP}' & = & {\rm EXP\_SKIP}, \\
          {\rm EXPTIMEA}' & = & {\rm EXPTIMEA}, \\
          {\rm EXPTIMEB}' & = & {\rm EXPTIMEB}, \\
          {\rm FEPLOAD}' & = & {\rm FEPLOAD}, \\
          {\rm FEP\_MODE}' & = & {\rm FEP\_MODE}, \\
          {\rm NOBADCOL}' & = & {\rm NOBADCOL}, \\
          {\rm NOBADPIX}' & = & {\rm NOBADPIX}, \\
          {\rm OCLKPAIR}' & = & {\rm OCLKPAIR}, \\
          {\rm ORC\_MODE}' & = & {\rm ORC\_MODE}, \\
          {\rm ROWCNT}' & = & {\rm ROWCNT}, \\
          {\rm STARTROW}' & = & {\rm STARTROW},\ {\rm and} \\
          {\rm SUM\_2X2}' & = & {\rm SUM\_2X2}. \label{eqn15}
	\end{eqnarray}
	%
	The keywords on the left-hand sides of
	equations~\ref{eqn01}--\ref{eqn15} are from the parameter-block file
	(acisf*pbk0.fits) for the same observation as the replacement bias
	file $B'$.  The keywords on the right-hand sides of the equations
	are from the parameter-block file for the same observation as the
	bias file $B$ being replaced.

      \item[c.]
        The tabulated parameter-block data
	%
        \begin{eqnarray}
          {\rm BIASALG}' & = & {\rm BIASALG}, \label{eqn16} \\
          {\rm BIASARG0}' & = & {\rm BIASARG0}, \\
          {\rm BIASARG1}' & = & {\rm BIASARG1}, \\
          {\rm BIASARG2}' & = & {\rm BIASARG2}, \\
          {\rm BIASARG3}' & = & {\rm BIASARG3}, \\
          {\rm BIASARG4}' & = & {\rm BIASARG4},\ {\rm and} \\
          {\rm VIDRESP}' & = & {\rm VIDRESP} \label{eqn22}
	\end{eqnarray}
	%
	for the CCD associated with $B$ and $B'$. Again, the left- and
	right-hand sides of equations~\ref{eqn16}--\ref{eqn22} are from the
	parameter-block files associated with $B'$ and $B$, respectively.

      \item[d.] The time difference between $B'$ and $B$
        %
        \begin{equation}
	  \Delta t \equiv \left| t' - t \right| \le \tau.
	\end{equation}
	%
	While small $\tau$ are best, in some cases the difference may have
	to be relatively large.\footnote{The time difference can be
	specified with the ``-d'' option of search4bias.pl.  If this option
	is not used, then search4bias.pl sets $\tau = 5$ days.}

      \item[e.] The focal-plane temperature difference between $B'$ and $B$
        %
        \begin{equation}
	  \Delta T \equiv \left| T' - T \right| \le \Upsilon.
	\end{equation}
	%
	Again, small $\Upsilon$ are best.\footnote{The temperature
	difference can be specified with the ``-t'' option of
	search4bias.pl.  If this option is not used, then search4bias.pl
	sets $\Upsilon = 1$ $^{\circ}$C.  if the ``-T'' option is used, then
	search4bias.pl compares the temperatures during the event data
	collection instead of the temperatures during the bias data
	collection.}

    \end{enumerate}
    %
    \end{changebar}

  \item
    For the first node of the bias $B'$ (\ie\ columns 1--256), modify the
    values of every pixel in the node so that
    %
    \begin{equation}
      B' \rightarrow B' - {\tt INITOCLA}' + {\tt INITOCLA},
    \end{equation}
    %
    where ${\tt INITOCLA}'$ and {\tt INITOCLA} are keywords in the headers
    of the bias files $B'$ and $B$, respectively.
    %
    \label{step02}

  \item
    \begin{changebar}
    Modify the value of initial-overclock keyword ${\tt INITOCLA}'$ in $B'$
    so that
    %
    \begin{equation}
      {\tt INITOCLA}' = {\tt INITOCLA}.
    \end{equation}
    %
    \label{step03}
    \end{changebar}

  \item
    Repeat steps~\ref{step02} and \ref{step03} for the other three nodes,
    using {\tt INITOCLB}, {\tt INITOCLC}, and {\tt INITOCLD}, instead of
    {\tt INITOCLA}, for columns 257--512, 513--768, and 769--1024,
    respectively.

  \item
    \begin{changebar}
    Add appropriate history keywords to the header of the modified bias file
    $B'$.  For example:

    { \tt
      \hspace*{0.15in}HISTORY\ \ YYYY-MM-DD:HH:MM:SS \\
      \hspace*{0.15in}HISTORY\ \ The name and version number of the code
        used to produce the file \\
      \hspace*{0.15in}HISTORY \\
      \hspace*{0.15in}HISTORY\ \ This bias file was created by replacing the
        file \\
      \hspace*{0.15in}HISTORY\ \ acisf?????????N???\_?\_bias0.fits with a
        modified version of the file \\
      \hspace*{0.15in}HISTORY\ \ acisf?????????N???\_?\_bias0.fits.  The
        original file is contaminated with a \\
      \hspace*{0.15in}HISTORY\ \ light leak.
      % \hspace*{0.15in}HISTORY \\
      % \hspace*{0.15in}HISTORY\ \ For more information, please contact ????.
    }
    \end{changebar}

  \item
    Process the ACIS event data using the modified version of the bias file
    $B'$.
    %
    \label{step06}

  \item
    Examine the pulse-height information of the event data after it has been
    processed with the replacement bias (see Fig.~\ref{fig03}).  If ${\tt
    DATAMODE} = {\tt FAINT}$, then prepare a histogram of the pulse heights
    of the 4 corner pixels for every event on the first node.  If ${\tt
    DATAMODE} = {\tt VFAINT}$, then prepare a histogram using the pulse
    heights of the outer 16 pixels instead of the 4 corner pixels.  The peak
    of the distribution should be at a pulse height of 0 adu.  If it is not,
    then add or subtract the difference between the location of the peak and
    0~adu to every pixel on the node for the bias file 
    \begin{changebar}
    $B'$.\footnote{The
    value of the keyword ${\tt INITOCLA}'$ should not be changed in the same
    way.  Only the data in the bias file $B'$ is modified in
    step~\ref{step07}.}
    \end{changebar}
    Repeat this process for the other nodes.
    %
    \label{step07}

  \item
    \begin{changebar}
    Repeat steps~\ref{step06}--\ref{step07} until the condition specified in
    step~\ref{step07} is satisfied.
    \end{changebar}

\end{enumerate}

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

% 4. Caveats

\section{ Caveats }

\begin{enumerate}

  \item
     If the bias being adjusted suffers from a light leak, then some events
     near the event threshold will have been lost and cannot be recovered.

  \item
     \begin{changebar}
     %
     The algorithm described in this spec may not be appropriate for
     continuous-clocking mode observations.
     %
     \end{changebar}

\end{enumerate}

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

% 5. Figures

\begin{changebar}

\begin{figure}
  \begin{center}
    \epsfig{file=bias_repair_figs/fig01,angle=0,height=8.32in}
  \end{center}
  \vspace*{-0.25in}
  \caption{%
    An image of the bias residuals for the five CCDs used for OBS\_ID 11799.
    The median of each column has been subtracted from the bias values for
    the column.  Excess charge from an optical light leak is evident,
    particularly on ACIS-S2, -I2, and -I0.  The labels for each CCD are
    located near ${\rm (CHIPX,CHIPY) = (1,1)}$.
    %
    \label{fig01}
    }
\end{figure}

\begin{figure}
  \begin{center}
    \epsfig{file=bias_repair_figs/fig02,angle=0,height=8.32in}
  \end{center}
  \vspace*{-0.25in}
  \caption{%
    An image of the bias residuals for the five CCDs used for OBS\_ID 11799
    after the bias files were replaced with modified versions of the bias
    files for OBS\_ID 9345. The median of each column has been subtracted
    from the bias values for the column.  The labels for each CCD are
    located near ${\rm (CHIPX,CHIPY) = (1,1)}$.
    %
    \label{fig02}
    }
\end{figure}

\begin{figure}
  \begin{center}
    \epsfig{file=bias_repair_figs/fig03,angle=270,width=6.5in}
  \end{center}
  \caption{%
    Histograms of the pulse heights of the outer 16 pixels of the 5~pixel
    $\times$ 5~pixel event islands for OBS\_ID 11799.  Only events on the
    first node of ACIS-I2 are included.  The red histogram is the
    distribution obtained using the data processed with the biases
    contaminated by a light leak.  The peak of the distribution is at
    $-5$~adu, instead of zero.  The black histogram is the distribution
    obtained after the data were reprocessed using modified versions of the
    biases for OBS\_ID 9345.  The peak of the distribution is at 0~adu, as
    desired.
    %
    \label{fig03}
    }
\end{figure}

\end{changebar}

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

% 6. Finish

\end{document}

