%+
% Name:
%   bias_repair_3.1.tex
%
% Notes:
%   1. Describe what to do to fix regions where only a subset of a column is
%      bad
%   2. What should be done about the header keywords
%        - CCDNODES
%        - DATAMODE
%        - DEAGAIN
%        - FEP_ID
%        - FSW_VERS
%        - HISTNUM
%        - PBLOCK
%        - READMODE
%        - RUN_ID
%        - STARTBEP
%
% 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
%   2009 Oct 27, added bias repair (v3.0), GEA
%   2009 Nov 04, added some header keywords (v3.1), 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 }{
   3.1 }{
   http://space.mit.edu/CXC/docs/docs.html\#bias\_rep }{
   /nfs/cxc/h2/gea/sds/docs/memos/bias\_repair\_3.1.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.
% \footnote{Before a bias file is changed, it is important to verify that it
% is appropriate to do so.  For example, refer to the test described in
% step~\ref{step0213} of section~\ref{repl} or in step~\ref{step0312} of
% section~\ref{repa}. \label{foo01}}
If a problem affects an entire CCD, then the bias file should be replaced.
Otherwise, it may be possible to repair the bias.  This spec describes how
to use the bias for one observation to replace or repair the bias of another
observation.

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

% 3. Replacement

\section{ Replacement }
\label{repl}

If an entire bias file has problems, then the bias file should be replaced.
% $^{\ref{foo01}}$
The following steps should be performed, in sequence, to replace bias file
$B$ for an observation (\eg\ Fig.~\ref{fig01}) with a modified version of a
bias file $B'$ from another observation (\eg\ Fig.~\ref{fig02}).

\begin{enumerate}

  \item
    \label{step0201}
    %
    Identify a suitable bias file $B'$.\footnote{Peter Ford's Perl script
    search4bias.pl (/nfs/acis/h4/tools/bin/sun4/search4bias.pl on the MIT
    LAN) can be used to identify a suitable replacement file. \label{foo02}}
    The 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 ($ > 5$~days).
	% \footnote{The time difference in days can be specified with the
	% ``-d'' option of search4bias.pl.  If this option is not used, then
	% the default value of $\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.
	  \label{eqn24}
	\end{equation}
	%
	Here, $T'$ and $T$ are the mean temperatures during the intervals
	over which the data for the bias files $B'$ and $B$, respectively,
	were obtained. Again, small $\Upsilon$ are best ($ < 1$~$^{\circ}$C).
	% \footnote{The	temperature difference in degrees Celsius can be
	% specified with the ``-t'' option of search4bias.pl.  If this
	% option is not used, then the default value of $\Upsilon = 1$
	% $^{\circ}$C.  If the ``-T'' option is used, then search4bias.pl
	% compares the mean temperatures during the event data collection
	% instead of the mean temperatures during the bias data collection.}

    \end{enumerate}
    %

  \item
    Copy $B'$ to $B''$, where $B''$ will become the replacement bias file.
    The files $B$ and $B'$ remain unchanged.

  \item
    \label{step0203}
    %
    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'' = 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.

  \item
    If the value of $B' = 4094$, 4095, or 4096 for a pixel on the first
    node, then $B'' = B'$ for that pixel instead of $B'' = B' - {\tt
    INITOCLA}' + {\tt INITOCLA}$.

  \item
    \label{step0205}
    %
    If the value of $B = 4094$, 4095, or 4096 for a pixel on the first node,
    then $B'' = B$ for that pixel instead of $B'' = B' - {\tt INITOCLA}' +
    {\tt INITOCLA}$.

  \item
    Repeat steps~\ref{step0203}--\ref{step0205} 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
    Copy the header from $B'$ to $B''$.
    
  \item
    Update the value of the keyword DATE in $B''$.

  \item
    Modify the values of initial-overclock keywords such that
    %
    \begin{changebar}
    \begin{eqnarray}
      {\tt BTIMCORR}'' & = & {\tt BTIMCORR}, \label{eqn26} \\
      {\tt BTIMDRFT}'' & = & {\tt BTIMDRFT}, \\
      {\tt BTIMNULL}'' & = & {\tt BTIMNULL}, \\
      {\tt BTIMRATE}'' & = & {\tt BTIMRATE}, \\
      {\tt INITOCLA}'' & = & {\tt INITOCLA}, \\
      {\tt INITOCLB}'' & = & {\tt INITOCLB}, \\
      {\tt INITOCLC}'' & = & {\tt INITOCLC}, \\
      {\tt INITOCLD}'' & = & {\tt INITOCLD}, \\
      {\tt STARTMJF}'' & = & {\tt STARTMJF}, \\
      {\tt STARTMNF}'' & = & {\tt STARTMNF}, \\
      {\tt STARTOBT}'' & = & {\tt STARTOBT}, \\
      {\tt STOPMJF}'' & = & {\tt STOPMJF}, \\
      {\tt STOPMNF}'' & = & {\tt STOPMNF}, \\
      {\tt TSTART}'' & = & {\tt TSTART}, \\
      {\tt TSTOP}'' & = & {\tt TSTOP}, \label{eqn40}
    \end{eqnarray}
    \end{changebar}
    %
    where the keywords on the left- and right-hand sides of
    equations~\ref{eqn26}--\ref{eqn40} are keywords in the headers of the
    bias files $B''$ and $B$, respectively.

  \item
    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\ \ CXC contact person \\
      \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.
    }

  \item
    Update the values of the keywords CHECKSUM and DATASUM in $B''$.

  \item
    \label{step0212}
    %
    Reprocess the ACIS event data using the bias file $B''$.

  \item
    \label{step0213}
    %
    Examine the pulse-height information of the event data after it has been
    processed with the replacement bias (\eg\ 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 the difference between the location of the peak and 0~adu to
    every pixel on the node for the bias file $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{step0213}.} Repeat this process for the other nodes.

  \item
    Repeat steps~\ref{step0212}--\ref{step0213} until the condition
    specified in step~\ref{step0213} is satisfied.

\end{enumerate}

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

% 4. Repair of full columns

\section{ Repair of full columns }
\label{repa}

If only a portion of a bias file has problems, then it may be more
appropriate to repair the bias instead of replacing it.
% $^{\ref{foo01}}$
For example, suppose that every pixel in the columns from $l$--$n$ of bias
file $B$ have excess charge for an observation (\eg\ Fig.~\ref{fig04}). In
this case, the following steps should be performed, in sequence, to use data
from the bias file $B'$ of another observation to repair the bias file (\eg\
Fig.~\ref{fig05}).

\begin{enumerate}

  \item
    Identify a suitable bias file $B'$.$^{\ref{foo02}}$  The file $B'$ is suitable if the
    conditions described in item~\ref{step0201} of section~\ref{repl} are
    satisfied.

  \item
    Copy $B$ to $B''$, where $B''$ will become the repaired bias file. The
    files $B$ and $B'$ remain unchanged.

  \item
    \label{step0303}
    %
    Suppose that the range of columns from $l$--$n$ straddles a node
    boundary between columns $m$ and $m+1$ (\ie\ $l \le m < n$). For the
    columns from $l$--$m$ of bias $B''$, replace the bias values of every
    pixel $(i,j)$ of the region such that
    %
    \begin{equation}
      B_{ij}'' = B_{ij}' - M' + M,
    \end{equation}
    %
    where the the column number $i$ (\ie\ CHIPX) is in the range from
    $l$--$m$ and the row number $j$ (\ie\ CHIPY) is in the range from
    1--1024.  $M'$ is the median of the bias values $B_{ij}'$ where $i$
    includes all of the columns on the same node as columns $l$--$m$ and $j$
    is in the range from 1--1024.  The columns $i$ from $l$--$m$, the pixels
    $(i,j)$ for which $B_{ij}' = 4094$, 4095, or 4096, and the pixels
    $(i,j)$ for which $B_{ij} = 4094$, 4095, or 4096 are excluded from the
    computation of $M'$. $M$ is computed in the same manner as $M'$, except
    that the bias $B$ is used instead of $B'$.  The same set of pixels are
    used to compute $M$ and $M'$.  If the range from $l$--$n$ does not
    straddle a node boundary, then $m$ should be replaced by $n$ in the
    description of the computation of $M'$ and $M$.

  \item
    \label{step0304}
    %
    The process described in step~\ref{step0303} is repeated for the columns
    from $m+1$ to $n$.  However, if the range from $l$--$n$ does not
    straddle a node boundary, then step~\ref{step0304} is skipped.

  \item
    If the value of $B_{ij}' = 4094$, 4095, or 4096 for a pixel in the
    region where $i$ is in the range from $l$--$n$ and $j$ is in the range
    from 1--1024, then $B_{ij}'' = B_{ij}'$ for that pixel instead of
    $B_{ij}'' = B_{ij}' - M' + M$.

  \item
    If the value of $B_{ij} = 4094$, 4095, or 4096 for a pixel in the region
    where $i$ is in the range from $l$--$n$ and $j$ is in the range from
    1--1024, then $B_{ij}'' = B_{ij}$ for that pixel instead of $B_{ij}'' =
    B_{ij}' - M' + M$.

  \item
    Copy the header from $B$ to $B''$.
    
  \item
    Update the value of the keyword DATE in $B''$.

  \item
    Add appropriate history keywords to the header of $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\ \ CXC contact person \\
      \hspace*{0.15in}HISTORY \\
      \hspace*{0.15in}HISTORY\ \ This bias file was created by repairing 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.
    }

  \item
    Update the values of the keywords CHECKSUM and DATASUM in $B''$.

  \item
    \label{step0311}
    %
    Reprocess the ACIS event data using the bias file $B''$.

  \item
    \label{step0312}
    %
    Examine the pulse-height information of the event data after it has been
    processed with the repaired bias (\eg\ Fig.~\ref{fig06}).  If ${\tt
    DATAMODE} = {\tt FAINT}$, then prepare a histogram of the pulse heights
    of the 4 corner pixels for every event in the region that includes the
    columns from $l$--$n$ and the rows from 1--1024.  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 the difference between the location of the peak and 0~adu to every
    pixel in the repaired region of $B''$.

  \item
    Repeat steps~\ref{step0311}--\ref{step0312} until the condition
    specified in step~\ref{step0312} is satisfied.

\end{enumerate}

If a subset of the columns from $l$--$n$ includes all of the columns in a
node, then follow the process described in section~\ref{repl} for that
subset (including the change to the keyword ${\tt INITOCL}x''$, where
$x = {\tt A}$, {\tt B}, {\tt C}, or {\tt D}). For the remaining columns, use
the process described in section~\ref{repa}. If the file $B$ is for an
observation that used one of the standard subarrays or some other
user-specified subset of the rows of a CCD, then the appropriate range of
$j$ is not 1--1024.

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

% 5. Caveats

\section{ Caveats }

\begin{enumerate}

  \item
     If the portion of a bias being modified has excess charge, then events
     in that region whose pulse heights are near the event threshold may
     have been lost and cannot be recovered.

  \item
     The algorithms described in this spec were designed for timed-exposure
     mode observations and may not be appropriate for continuous-clocking
     mode observations.

\end{enumerate}

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

% 6. TBD

\section{ TBD }

\begin{enumerate}

  \item
    The algorithms described in this spec do not address systematic offsets
    at the sub-adu level.

\end{enumerate}

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

% 7. Figures

\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 the coordinates ${\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 the coordinates ${\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 shown in
    Figure.~\ref{fig01}.  The peak of the red histogram is at $-5$~adu,
    instead of zero.  The black histogram is the distribution obtained after
    the data were reprocessed using the biases shown in Figure~\ref{fig02}.
    The peak of the black histogram is at 0~adu, as desired.
    %
    \label{fig03}
    }
\end{figure}

\begin{figure}
  \begin{center}
    \epsfig{file=bias_repair_figs/fig04,angle=0,width=6.5in}
  \end{center}
  \vspace*{-0.30in}
  \caption{%
    An image of the ACIS-I1 bias residuals for OBS\_ID 9336. The median of
    each node has been subtracted from the bias values for the node.  Excess
    charge is evident in the columns from 913--961.
    %
    \label{fig04}
    }
\end{figure}

\begin{figure}
  \begin{center}
    \epsfig{file=bias_repair_figs/fig05,angle=0,width=6.5in}
  \end{center}
  \vspace*{-0.30in}
  \caption{%
    An image of the ACIS-I1 bias residuals for OBS\_ID 9336 after the data
    in the columns from 913--961 were repaired using data from a bias file
    for OBS\_ID 10811. The median of each node has been subtracted from the
    bias values for the node.
    %
    \label{fig05}
    }
\end{figure}

\begin{figure}
  \begin{center}
    \epsfig{file=bias_repair_figs/fig06,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 9336.  Only events in the
    columns from 913--961 of ACIS-I1 are included.  The red histogram is the
    distribution obtained using the data processed with the bias shown in
    Figure~\ref{fig04}. The peak of the red histogram is at $-2$~adu,
    instead of zero.  The black histogram is the distribution obtained using
    the bias shown in Figure~\ref{fig05}. The peak of the black histogram is
    at 0~adu, as desired.
    %
    \label{fig06}
    }
\end{figure}

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

% 8. Finish

\end{document}

