%+
% Name:
%   memo_acis_build_mask_4.0.tex
%
% History:
%   21 Jun 02, created (v3.0), Glenn E. Allen
%   15 Aug 02, added changebars (v3.1), GEA
%   09 Sep 02, updated header (v3.1b), GEA
%   04 Dec 02, minor changes (v1.4), GEA
%   09 Oct 03, modified the PHAMIN and PHAMAX spec (v3.4), GEA
%   20 Oct 03, made a few changes (v3.5), GEA
%   21 Oct 03, changed a paragraph following table 3 (v3.6), GEA
%   22 Oct 03, added the appendix (v3.7), GEA
%   21 Nov 03, changed FIRSTROW, LASTROW, PHAMIN, PHARANGE keywords (v3.8), 
%     GEA
%   26 Apr 04, added the case SAMP_CYC=1, PHAMIN=0, PHAMAX=0 (v3.9), GEA
%   11 Aug 04, modified the notes about the window block files in appendix
%     A (v3.10), GEA
%   30 Mar 07, rotated the tables (v4.0), GEA

% April 17, 2025 -- Made the 'full window' parameter a variable that accepts a window with one less pixel along the border but treats it as 'full window' exclusion. (D. Principe)

%-

\documentclass{article}

\usepackage{graphics,graphicx}
\usepackage[breaklinks=true]{hyperref}

\setlength{\textwidth}{6.5in} 
\setlength{\textheight}{9in}
\setlength{\topmargin}{-0.0625in} 
\setlength{\oddsidemargin}{0in}
\setlength{\evensidemargin}{0in} 
\setlength{\headheight}{0in}
\setlength{\headsep}{0in} 
\setlength{\hoffset}{0in}
\setlength{\voffset}{0in}


\usepackage[normalem]{ulem}
\usepackage{amsmath}
\newcommand{\stkout}[1]{\ifmmode\text{\sout{\ensuremath{#1}}}\else\sout{#1}\fi}



\usepackage{epsfig}
\usepackage{pstricks}
\usepackage{enumitem}

\newrgbcolor{blue}{0 0 1}
\newrgbcolor{red}{1 0 0}

\newcommand{\abm}{{\tt acis\_build\_mask }}
%\newcommand{\abm}{{\tt acisbuildmask}}



\begin{document}

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

% 1. Header


\hspace{-10mm}
\includegraphics[scale=0.3]{MIT_MKI_new.pdf}
\hspace{51mm}
\includegraphics[scale=0.3]{CXO_new.pdf}

\vspace{10mm}

{\hspace{-7mm}{\bf \large MEMORANDUM}

{\hspace{-7mm}April 14th, 2025

\vspace{8mm}

{\hspace{-7mm}{\bf To: }\hspace{10mm} Jonathan McDowell, SDS Group Leader

\vspace{1mm}

{\hspace{-7mm}{\bf From: }\hspace{5mm} David Principe, SDS

\vspace{1mm}

{\hspace{-7mm}{\bf Subject: } \abm  window filter definition change

\vspace{1mm}

{\hspace{-7mm}{\bf Revision: } 4.1\footnotemark}

\vspace{1mm}

{\hspace{-7mm}{\bf URL: } \nolinkurl{https://space.mit.edu/CXC/docs/docs.html#msk}
%{\hspace{-7mm}{\bf Related: } \nolinkurl{https://space.mit.edu/CXC/docs/memo_bpix\_status\_bits\_1.12.pdf}

\vspace{1mm}

{\hspace{-7mm}{\bf File: } \nolinkurl{/nfs/cxc/h4/principe/cxc_memos/memo_acis_build_mask_4.1.tex}


%{\hspace{14.3mm}\nolinkurl{https://space.mit.edu/CXC/docs/ape_spec_4.17.pdf}

\vspace{8mm}

{\hspace{-7mm}{\large \bf Summary of change:} 

\vspace{3mm}

A small modification has been made to \abm in response to two observations (obsIDs 23539 and 28052) which caused errors in processing. The \abm tool is used to produce a mask file for an observation that contains information about the valid ranges of CHIPX, CHIPY, and PHA for each CCD used for the observation. The tool has a 'full window' parameter used in specific scenarios to indicate that events from the entire CCD should be excluded in the acis mask file that \abm produces. An example of full-window exclusion is shown at the bottom of this specification in section A-3 'Notes about Window-Block Files'.  Prior to this update (\abm $<$ v 4.1), the full window parameter was defined to be:

\begin{enumerate}

\item
0-based index -- LL\_CCDX=0, LL\_CCDY=0, CCDCOL=1023, CCDROW=1023

\item
1-based index -- chipX[0]=1, chipY[0]=1 to chipX[1]=1024, chipY[1]=1024

\end{enumerate}

%When a full window is used, it is meant to indicate that the entire ccd (e.g., chipX[0]=1, chipY[0]=1 to chipX[1]=1024, chipY[1]=1024; index-1 based or LL\_CCDX=0, LL\_CCDY=0, CCDCOL=1023, CCDROW=1023; index-1 based) was either included or excluded depending on other parameters and logic still relevant in the spec below. 
 This new update (v 4.1) treats the user-supplied exclusion window parameter values for chip(x1,x2) or chip(y1,y2) of (0,1022), (1,1022) or (1, 1023) the same as 'full window' exclusion (e.g., 0,1023; 0-based index). The error in \abm in response to the above obsIDs was due to an erroneous window-block file exclusion value of '0-1022' instead of the nominal '0-1023'.  Window exclusion values with chip(x1,x2) or chip(y1,y2) of (0,1022), (1,1022) or (1, 1023) would indicate that events in the very last row/column of the CCD should {\bf not} be excluded from event files using the \abm produced mask file. However, events on the edges of the detector are not valid and should be masked (excluded) because the ACIS onboard event finding software requires that events need a complete 3x3 pixel island for detection. 

\footnotetext{The changes in this revision from the previous one are marked below  {\red in
red}. The \abm tool deviates in some places with respect to this spec.}


\newpage

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

% 2. Tool name

\section{\abm}

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

% 3. Description

\subsection{ Description }

A Level 1 ACIS mask file for an observation contains information about the
valid ranges of CHIPX, CHIPY and PHA for each CCD used for the observation.
If a user specifies one or more spatial and/or spectral window for their
observation, then this information is included in the mask file. Unlike the
pixels and columns identified as bad in a bad-pixel file, no events should
be detected in the regions identified as invalid in a mask file.  However,
there may be events with pulse heights that are slightly outside the valid
PHA range because the pulse heights are typically recomputed on the ground.
%

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

% 4. Input

\subsection{ Input }

\begin{enumerate}

\item
A Level 0 parameter block file (acis*pbk0.fits)

\item
A Level 0 window-block file (acis*win0.fits)

\item
A Level 1 event data file (acis*evt1.fits)

\end{enumerate}

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

% 5. Output

\subsection{ Output }

A Level 1 mask file (acis*msk1.fits) that contains one extension for each
active CCD.  Each extension includes a binary table with one or more rows
and the following columns.

\begin{enumerate}

\item
SHAPE

\item
COMPONENT

\item
CHIPX (a two element vector)

\item
CHIPY (a two element vector)

\item
SAMP\_CYC

\item
PHAMIN

\item
PHAMAX

\end{enumerate}

The columns WINDOW and OVERLAP, which are in older mask files, have been
dropped.  Since ${\rm WINDOW} = {\rm COMPONENT} - 1$, the column WINDOW is
redundant.  The column OVERLAP was dropped because it is not used by any
CIAO tool.

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

% 6. Parameters

\subsection{ Parameters }

\begin{enumerate}

\item
pbkfile,s,a,``'',,,``Name of input parameter-block file''

\item
pbkext,s,h,``PBK'',,,``Name of extension in parameter-block file'' 

\item
winfile,s,a,``'',,,``Name of input window-block file'' 

\item
winext,s,h,``WIN'',,,``Name of extension in window-block file'' 

\item
evtfile,s,h,``none'',,,``Name of input event file'' 

\item
outfile,s,a,``'',,,``Name of output file'' 

\item
kernel,s,h,``default'',fits|iraf|default,,``Output format type'' 

\item
clobber,b,h,``no'',,,``Overwrite output file if it exists?'' 

\item
verbose,i,h,0,0,5,``Amount of messages produced (0$=$none, 5$=$a lot)'' 

\item
mode,s,h,``ql'',,,

\end{enumerate}

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

% 7. Processing

\subsection{ Processing }
\label{processing}

One FITS extension is produced for every ``active'' CCD.  A CCD is defined
to be active if the CCD is included in the ``PBK'' extension of the
parameter-block file.  Each extension has one or more rows.  One row is used
to mark an entire CCD as invalid.  Additional rows are used, if necessary,
to mark portions of the CCD as valid.  This method insures that every CCD
has at least one row in the mask file and that the outer edge of a CCD is
marked as invalid.

\begin{enumerate}

\item
Verify that the specified extensions of the input files exist.  If clobber
$=$ ``no,'' then verify that the output file does not exist.

\item
Read the values of the keywords STARTROW, ROWCNT, and WIND\_ID in the header
of the input parameter-block file.  If ${\rm STARTROW} < 0$ or ${\rm
STARTROW} + {\rm ROWCNT} > 1023$, then do not create the output file and
exit with an error message that the keywords are invalid. If the keywords
are valid, then copy the value of the keyword WIND\_ID to a keyword of the
same name in the header of the output file.

\item
Read the contents of the window-block file.

\item
Determine the contents of the columns SHAPE, COMPONENT, CHIPX, CHIPY,
SAMP\_CYC, PHAMIN and PHAMAX in the output file as follows.

\begin{itemize}

\item[a.]
{\bf SHAPE:} \\
%
The SHAPE is either a ``rectangle'' or ``!rectangle,'' as appropriate.

\item[b.]
{\bf COMPONENT:} \\ 
%
Each rectangular component of the mask for an observation is numbered
sequentially from one.  The index number for a component is listed in the
column named COMPONENT.

\item[c.]
{\bf CHIPX and CHIPY:} \\

\begin{itemize}

\item[$i$.]
{\it ${\rm SAMP\_CYC} \ge 1$:} \\ 
%
If the ${\rm SAMP\_CYC} \ge 1$ for a region, then the region is valid and
Table~1 is used to determine the values of the boundaries for the region. 
Typically, the valid region for a CCD is the entire CCD.  In this case, the
top half of Table~1 is used to determine the values of ${\rm CHIPX[0]}$,
${\rm CHIPX[1]}$, ${\rm CHIPY[0]}$ and ${\rm CHIPY[1]}$. However, if only a
subset of a CCD is used, as has been the case for some observations of the
Crab, for example, then the formulae in the bottom half of Table~1 are used
to determine the boundaries.

If ${\rm SAMP\_CYC} \ge 1$ and ${\rm CHIPX}[0] = 1$ or ${\rm CHIPX}[1] =
1024$, then change the CHIPX boundary to be consistent with the default
value listed in Table~1.  If ${\rm SAMP\_CYC} \ge 1$ and ${\rm CHIPY}[0] =
1$ (or 2 for VFAINT) or ${\rm CHIPY}[1] = 1024$ (or 1023 for VFAINT), then
change the CHIPY boundary to be consistent with the default value listed in
Table~1. If ${\rm SAMP\_CYC} \ge 1$ and ${\rm CHIPX}[0] < 1$, ${\rm
CHIPX}[1] > 1024$, ${\rm CHIPY}[0] < 1$ or ${\rm CHIPY}[1] > 1024$, then do
not create the output file and exit with an error message. 

\begin{table}
\vspace{-10mm}
  \begin{center}
    \begin{tabular}{|l|cc|cc|}
      \multicolumn{5}{c}{Table 1. CHIPX and CHIPY values for ${\rm
        SAMP\_CYC} \ge 1$}
	\\
      \hline \hline
      DATAMODE
        & CHIPX[0]
        & CHIPX[1]
        & CHIPY[0]
        & CHIPY[1]
        \\
      \hline
      \multicolumn{5}{c}{Default values$^{a}$}
        \\
      \hline
      CC33\_FAINT$^{b}$
        & $\bigg($ \begin{minipage}{0.07in} \begin{center} 2 \\ 2
          \end{center} \end{minipage} $\bigg)$
        & $\bigg($ \begin{minipage}{0.28in} \begin{center} 1023 \\ 1023
          \end{center} \end{minipage} $\bigg)$
        & $\bigg($ \begin{minipage}{0.20in} \begin{center} 2 \\ 514
          \end{center} \end{minipage} $\bigg)$
        & $\bigg($ \begin{minipage}{0.28in} \begin{center} 511 \\ 1023
          \end{center} \end{minipage} $\bigg)$
        \\
      CC33\_GRADED$^{b}$
        & $\bigg($ \begin{minipage}{0.07in} \begin{center} 2 \\ 2
          \end{center} \end{minipage} $\bigg)$
        & $\bigg($ \begin{minipage}{0.28in} \begin{center} 1023 \\ 1023
          \end{center} \end{minipage} $\bigg)$
        & $\bigg($ \begin{minipage}{0.20in} \begin{center} 2 \\ 514
          \end{center} \end{minipage} $\bigg)$
        & $\bigg($ \begin{minipage}{0.28in} \begin{center} 511 \\ 1023
          \end{center} \end{minipage} $\bigg)$
        \\
      FAINT
        & 2
        & 1023
        & 2
        & 1023
        \\
      FAINT\_BIAS
        & 2
        & 1023
        & 2
        & 1023
        \\
      GRADED
        & 2
        & 1023
        & 2
        & 1023
        \\
      VFAINT
        & 2
        & 1023
        & 3
        & 1022
        \\
      \hline
      \multicolumn{5}{c}{General formulae$^{a}$}
        \\
      \hline
      CC33\_FAINT$^{b}$
        & $\bigg($ \begin{minipage}{0.32in} \begin{center} $x_{0} + 1$ \\
          $x_{0} + 1$ \end{center} \end{minipage} $\bigg)$
        & $\bigg($ \begin{minipage}{0.32in} \begin{center} $x_{1} + 1$ \\
          $x_{1} + 1$ \end{center} \end{minipage} $\bigg)$
        & $\bigg($ \begin{minipage}{0.20in} \begin{center} 2 \\ 514
          \end{center} \end{minipage} $\bigg)$
        & $\bigg($ \begin{minipage}{0.28in} \begin{center} 511 \\ 1023
          \end{center} \end{minipage} $\bigg)$
        \\
      CC33\_GRADED$^{b}$
        & $\bigg($ \begin{minipage}{0.32in} \begin{center} $x_{0} + 1$ \\
          $x_{0} + 1$ \end{center} \end{minipage} $\bigg)$
        & $\bigg($ \begin{minipage}{0.32in} \begin{center} $x_{1} + 1$ \\
          $x_{1} + 1$ \end{center} \end{minipage} $\bigg)$
        & $\bigg($ \begin{minipage}{0.20in} \begin{center} 2 \\ 514
          \end{center} \end{minipage} $\bigg)$
        & $\bigg($ \begin{minipage}{0.28in} \begin{center} 511 \\ 1023
          \end{center} \end{minipage} $\bigg)$
        \\
      FAINT
        & $x_{0} + 1$
        & $x_{1} + 1$
        & $y_{0} + 2$
        & $y_{1}$
        \\
      FAINT\_BIAS
        & $x_{0} + 1$
        & $x_{1} + 1$
        & $y_{0} + 2$
        & $y_{1}$
        \\
      GRADED
        & $x_{0} + 1$
        & $x_{1} + 1$
        & $y_{0} + 2$
        & $y_{1}$
        \\
      VFAINT
        & $x_{0} + 1$
        & $x_{1} + 1$
        & $y_{0} + 3$
        & $y_{1} - 1$
        \\
      \hline
      \multicolumn{5}{l}{\parbox[t]{4.1in}{$^{a}$ The valid region is the
        region defined by ${\rm CHIPX[0]} \le {\rm CHIPX} \le {\rm
        CHIPX[1]}$ and ${\rm CHIPY[0]} \le {\rm CHIPY} \le {\rm CHIPY[1]}$.}}
	\\
      \multicolumn{5}{l}{\parbox[t]{4.1in}{$^{b}$ Two rows are written for
        each CCD.  One for the top half of a CCD and one for the bottom half
        of the CCD.}} 
	\\
      \multicolumn{5}{l}{$x_{0} = {\rm LL\_CCDX}$} 
        \\
      \multicolumn{5}{l}{$x_{1} = {\rm LL\_CCDX} + {\rm CCDCOL}$}
        \\
      \multicolumn{5}{l}{ $y_{0} = {\rm max} ( {\rm LL\_CCDY}$, ${\rm
        STARTROW} )$} 
        \\
      \multicolumn{5}{l}{ $y_{1} = {\rm min} ( {\rm LL\_CCDY} + {\rm
        CCDROW}$, ${\rm STARTROW} + {\rm ROWCNT} )$} 
        \\
    \end{tabular}
  \end{center}
\end{table}

\item[$ii$.]
{\it ${\rm SAMP\_CYC} = 0$:} \\
%
If the ${\rm SAMP\_CYC} = 0$ for a region, then the region is invalid and
Table~2 is used to determine the values of the boundaries for the region. If
a CCD is ``active'', but the entire CCD has a window with a sample cycle of
zero, then the top half of Table~2 is used to determine the values of ${\rm
CHIPX}[0]$, ${\rm CHIPX}[1]$, ${\rm CHIPY}[0]$, and ${\rm CHIPY}[1]$.  If
only a subset of a CCD has a window with a ${\rm SAMP\_CYC} = 0$, as has
been the case for some grating observations where the zeroth-order events
are excluded, then the formulae in the bottom half of Table~2 are used to
determine the boundaries.

If ${\rm SAMP\_CYC} = 0$ and ${\rm CHIPX}[0] < 1$, ${\rm CHIPX}[1] > 1024$,
${\rm CHIPY}[0] < 1$ or ${\rm CHIPY}[1] > 1024$, then do not create the
output file and exit with an error message.

\end{itemize}

\item[d.]
{\bf SAMP\_CYC:} \\
%
The value of SAMP\_CYC for each component is copied from the Level 0 window
file with the following exception.  If ${\rm SAMP\_CYC} = 1$, ${\rm
PHAMIN}_{\rm win} = 0$ and ${\rm PHARANGE}_{\rm win} = 0$, then ${\rm
SAMP\_CYC} = 0$ in the output file.  (PHAMIN and PHAMAX are computed as
described below in any case.)

\item[e.]
{\bf PHAMIN:} \\
%
The value of PHAMIN for a window (for all DATAMODEs) is given by the larger
of 
%
\begin{eqnarray}
 & {\rm PHAMIN}_{\rm pbk} + 1, & \\
 & {\rm min} \left( {\rm EVT\_THR}[0], {\rm EVT\_THR}[1], {\rm EVT\_THR}[2],
   {\rm EVT\_THR}[3] \right) + 1,\ {\rm and} & \\
 & {\rm PHAMIN}_{\rm win} + 0, & 
\end{eqnarray}
%
where ${\rm PHAMIN}_{\rm pbk}$ is the value of the keyword PHAMIN in the
header of the parameter block file, ${\rm EVT\_THR}[i]$ is the value of the
event threshold for node $i$ of the appropriate CCD in the first extension
of the parameter block file and ${\rm PHAMIN}_{\rm win}$ is the value of
PHAMIN for the window in the first extension of the window-block file.

\begin{table}
  \begin{center}
    \begin{tabular}{|l|cc|cc|}
      \multicolumn{5}{c}{Table 2. CHIPX and CHIPY values for ${\rm
        SAMP\_CYC} = 0$}
	\\
      \hline \hline
      DATAMODE
        & CHIPX[0]
        & CHIPX[1]
        & CHIPY[0]
        & CHIPY[1]
        \\
      \hline
      \multicolumn{5}{c}{Default values$^{a}$}
        \\
      \hline
      CC33\_FAINT
        & 1
	& 1024
	& 1
	& 1024
        \\
      CC33\_GRADED
        & 1
	& 1024
	& 1
	& 1024
        \\
      FAINT
        & 1
	& 1024
	& 1
	& 1024
        \\
      FAINT\_BIAS
        & 1
	& 1024
	& 1
	& 1024
        \\
      GRADED
        & 1
	& 1024
	& 1
	& 1024
        \\
      VFAINT
        & 1
	& 1024
	& 1
	& 1024
        \\
      \hline
      \multicolumn{5}{c}{General formulae$^{a}$}
        \\
      \hline
      CC33\_FAINT$^{b}$
        & $\bigg($ \begin{minipage}{0.32in} \begin{center} $x_{0} + 1$ \\
          $x_{0} + 1$ \end{center} \end{minipage} $\bigg)$
        & $\bigg($ \begin{minipage}{0.32in} \begin{center} $x_{1} + 1$ \\
          $x_{1} + 1$ \end{center} \end{minipage} $\bigg)$
        & $\bigg($ \begin{minipage}{0.20in} \begin{center} 2 \\ 514
          \end{center} \end{minipage} $\bigg)$
        & $\bigg($ \begin{minipage}{0.28in} \begin{center} 511 \\ 1023
          \end{center} \end{minipage} $\bigg)$
        \\
      CC33\_GRADED$^{b}$
        & $\bigg($ \begin{minipage}{0.32in} \begin{center} $x_{0} + 1$ \\
          $x_{0} + 1$ \end{center} \end{minipage} $\bigg)$
        & $\bigg($ \begin{minipage}{0.32in} \begin{center} $x_{1} + 1$ \\
          $x_{1} + 1$ \end{center} \end{minipage} $\bigg)$
        & $\bigg($ \begin{minipage}{0.20in} \begin{center} 2 \\ 514
          \end{center} \end{minipage} $\bigg)$
        & $\bigg($ \begin{minipage}{0.28in} \begin{center} 511 \\ 1023
          \end{center} \end{minipage} $\bigg)$
        \\
      FAINT
        & $x_{0} + 1$
        & $x_{1} + 1$
        & $y_{0} + 1$
        & $y_{1} + 1$
        \\
      FAINT\_BIAS
        & $x_{0} + 1$
        & $x_{1} + 1$
        & $y_{0} + 1$
        & $y_{1} + 1$
        \\
      GRADED
        & $x_{0} + 1$
        & $x_{1} + 1$
        & $y_{0} + 1$
        & $y_{1} + 1$
        \\
      VFAINT
        & $x_{0} + 1$
        & $x_{1} + 1$
        & $y_{0} + 1$
        & $y_{1} + 1$
        \\
      \hline
      \multicolumn{5}{l}{\parbox[t]{4.1in}{$^{a}$ The invalid region is the
        region defined by ${\rm CHIPX[0]} \le {\rm CHIPX} \le {\rm
        CHIPX[1]}$ and ${\rm CHIPY[0]} \le {\rm CHIPY} \le {\rm CHIPY[1]}$.}} 
	\\
      \multicolumn{5}{l}{\parbox[t]{4.1in}{$^{b}$ Two rows are written for
        each CCD.  One for the top half of a CCD and one for the bottom half
        of the CCD.}} 
	\\
      \multicolumn{5}{l}{$x_{0} = {\rm LL\_CCDX}$} 
        \\
      \multicolumn{5}{l}{$x_{1} = {\rm LL\_CCDX} + {\rm CCDCOL}$}
        \\
      \multicolumn{5}{l}{ $y_{0} = {\rm max} ( {\rm LL\_CCDY}$, ${\rm
        STARTROW} )$}
        \\
      \multicolumn{5}{l}{ $y_{1} = {\rm min} ( {\rm LL\_CCDY} + {\rm
        CCDROW}$, ${\rm STARTROW} + {\rm ROWCNT} )$} 
        \\
    \end{tabular}
  \end{center}
\end{table}

\item[f.]
{\bf PHAMAX:} \\
%
The value of PHAMAX for a window (for all DATAMODEs) is given by the smaller
of 
%
\begin{eqnarray}
 & {\rm PHAMIN}_{\rm pbk} + {\rm PHARANGE}_{\rm pbk} - 1, & \\
 & {\rm PHAMIN}_{\rm win} + {\rm PHARANGE}_{\rm win} - 1,\ {\rm and} & \\
 & 32767, & 
\end{eqnarray}
%
where ${\rm PHARANGE}_{\rm pbk}$ is the value of the keyword PHARANGE in the
header of the parameter block file and ${\rm PHARANGE}_{\rm win}$ is the
value of PHARANGE for the window in the first extension of the window-block
file.

If ${\rm PHAMIN}_{\rm win} = 0$ and ${\rm PHARANGE}_{\rm win} = 0$, then set
${\rm PHAMIN} = {\rm PHAMIN}_{\rm pbk} + 1$ and ${\rm PHAMAX} = 32767$. If
${\rm PHAMAX} \le {\rm PHAMIN}$, then do not create the output file and exit
with an error message.

\end{itemize}

\item
Write the data to the specified output file.

\item
{\bf FIRSTROW and LASTROW:} \\
%
Add the keywords FIRSTROW and LASTROW to the header of the output file for
each CCD. FIRSTROW is the smallest value of CHIPY[0] for any masked region
on the CCD (as long as the region has ${\rm SAMP\_CYC} > 0$).  LASTROW is
largest value of CHIPY[1] for any masked region on the CCD (as long as the
region has ${\rm SAMP\_CYC} > 0$).  If ${\rm FIRSTROW} < 1$, ${\rm LASTROW}
> 1024$ or ${\rm LASTROW} < {\rm FIRSTROW}$, then do not create the output
file and exit with an error message.  If a CCD has no active region, then do
not write the keywords FIRSTROW and LASTROW to the output file for the CCD.

\item
{\bf PHAMIN and PHARANGE:} \\
%
Add the keywords PHAMIN and PHARANGE to the header of the output file for
each CCD. PHAMIN is the smallest value of PHAMIN for any masked region on
the CCD (as long as the region has ${\rm SAMP\_CYC} > 0$).  PHARANGE is
largest value of PHAMAX for any masked region on the CCD (as long as the
region has ${\rm SAMP\_CYC} > 0$) less the value of the keyword PHAMIN.  If
${\rm PHARANGE} < 1$, then do not create the output file and exit with an
error message.  If a CCD has no active region, then do not write the
keywords PHAMIN and PHARANGE to the output file for the CCD.

\end{enumerate}

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

% 8. Appendix

\subsection*{A\hspace*{0.25in}Notes about Window-Block Files}

Window-block files specify an ordered set of filters that are used to
exclude selected events from telemetry. The selection criteria can include
the location, pulse height or exposure number of an event. For
timed-exposure mode observations, the fate of event $i$ on ${\rm CCD\_ID} =
c_{i}$ at the coordinates ${\rm CCDX} = x_{i}$ and ${\rm CCDY} = y_{i}$ is
determined by the first row $r$ in the window-block file for the observation
such that
%
\begin{eqnarray}
  & {\rm CCD\_ID}_{r} = c_{i}, & \label{eqi} \\
  & {\rm LL\_CCDX}_{r} \le x_{i} \le {\rm LL\_CCDX}_{r} + {\rm CCDCOL}_{r},\
    {\rm and} & \label{eqii} \\
  & {\rm LL\_CCDY}_{r} + n \le y_{i} \le {\rm LL\_CCDY}_{r} + 
    {\rm CCDROW}_{r} - n, & \label{eqiii} 
\end{eqnarray}
%
where ${\rm CCD\_ID}_{r}$, ${\rm LL\_CCDX}_{r}$, ${\rm LL\_CCDY}_{r}$, ${\rm
CCDCOL}_{r}$ and ${\rm CCDROW}_{r}$ are the values of CCD\_ID, LL\_CCDX,
LL\_CCDY, CCDCOL and CCDROW, respectively, for row $r$ of the window-block
file and $n = 0$, 1 or 2 (see Tables~1 or 2). Event $i$ is telemetered if
all of the following conditions are true:
%
\begin{eqnarray}
  & {\rm SAMP\_CYC}_{r} > 0, & \\
  & {\rm EXPNO}_{i}\ {\rm is\ an\ integer\ multiple\ of}\ {\rm
    SAMP\_CYC}_{r},\ {\rm and} \\
  & {\rm PHAMIN}_{r} \le {\rm PHA}_{i} \le {\rm PHAMIN}_{r} + {\rm
    PHARANGE}_{r}, &
\end{eqnarray}
%
where ${\rm SAMP\_CYC}_{r}$, ${\rm PHAMIN}_{r}$ and ${\rm PHARANGE}_{r}$ are
the values of SAMP\_CYC, PHAMIN, and PHARANGE, respectively, for row $r$ of
the window-block file and ${\rm EXPNO}_{i}$ is the value of EXPNO for event
$i$. If more than one row satisfies equations~\ref{eqi}--\ref{eqiii}, then 
the values of SAMP\_CYC, PHAMIN and PHARANGE from only the first of these
rows are used. If no rows satisfy these conditions or there is no
window-block file for the observation, then all the events that satisfy the
standard pulse-height range are telemetered. PHAMIN and PHARANGE are
computed as described above. If the observation is performed in
continuous-clocking mode, then only conditions~\ref{eqi} and \ref{eqii} are
used.

{\red  Window block files with a 'full window' row to indicate that the entire CCD should be disabled ({\rm SAMP\_CYC}=0) should contain values of 
LL\_CCDX=0, LL\_CCDY=0, CCDCOL=1023, CCDROW=1023 for each relevant CCD. Since events cannot be detected on the edges of the CCDs, exclusion regions which deviate from a 'full window' by one pixel, for example, LL\_CCDX=1, LL\_CCDY=1, CCDCOL=1022, CCDROW=1022 will be treated as 'full window' exclusion.  }

The following examples illustrate some of the ways in which window-block
files are used.  The contents in the examples are the contents of the HDU
named ``WIN'' of a window-block file (i.e.,  a *win0.fits file).

\begin{enumerate}

\item
If an entire CCD is used and no pulse-height filtering is performed for the
CCD, then the window-block file does not contain an entry for the CCD.  If
these conditions are satisfied for all of the CCDs used for an observation,
then no window-block file is created for the observation.

\item
If an entire CCD is ``active,'' but disabled, the window-block file contains
a single entry for the CCD which specifies that the CCD is disabled.  For
example, the window-block file for OBS\_ID 62724 includes
\begin{verbatim}
CCD_ID   LL_CCDX   CCDCOL   SAMP_CYC   PHAMIN   PHARANGE
------   -------   ------   --------   ------   --------
   8         0      1023        0         0       24570
   9         0      1023        0         0       24570
\end{verbatim}

\item
If only a portion of a CCD is used (as is the case, for example, for some of
the observations of the Crab), then the window-block file contains two
entries for the CCD.  One entry specifies that the entire CCD is disabled.
The second entry specifies the portion of the CCD that is used. For example,
the window-block file for OBS\_ID 770 includes
\begin{verbatim}
CCD_ID   LL_CCDX   LL_CCDY   CCDCOL   CCDROW   SAMP_CYC   PHAMIN   PHARANGE
------   -------   -------   ------   ------   --------   ------   --------
   7       185        10       139      139        1        23        2270
   7         0         0      1023     1023        0         0       65535
\end{verbatim}

\item
\label{egiv}
If only a portion of a CCD is disabled (e.g.,  to block out the zeroth order
events from a bright source observed with the gratings), then the window
block file contains a single entry for the CCD.  For example, the window
block file for OBS\_ID 1939 includes
\begin{verbatim}
CCD_ID   LL_CCDX   LL_CCDY   CCDCOL   CCDROW   SAMP_CYC   PHAMIN   PHARANGE
------   -------   -------   ------   ------   --------   ------   --------
   7       180        99       149      199        0         0           0
\end{verbatim}
This entry specifies the portion of the CCD that is not used.  Although
there is no other entry for ${\rm CCD\_ID} = 7$ in the file, the rest of the
CCD is implicitly enabled (see item 1).

\item
If an entire CCD is used, but a portion of it has a sample cycle of $n > 1$
instead of one (e.g.,  to reduce the number of zeroth-order events telemetered
for a grating observation of a bright source), then the window-block file
contains a single entry for the CCD. This case is similar to
case~\ref{egiv}. For example, the window-block file for OBS\_ID 4568 includes
\begin{verbatim}
CCD_ID   LL_CCDX   CCDCOL   SAMP_CYC   PHAMIN   PHARANGE
------   -------   ------   --------   ------   --------
   7       161        99       20        25        3750
\end{verbatim}
This entry specifies the portion of the CCD that has a sample cycle of
twenty.  The rest of the CCD is implicitly enabled with a sample cycle of
one.

\end{enumerate}

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

% 9. Finish

\end{document}
