%+
% Name:
%    memo_acis_build_mask_3.6.tex
%
% Usage:
%    latex memo_acis_build_mask_3.6.tex
%
% Description:
%    This document describes the specification for the tool acis_build_mask.
%
% Input:
%
% Output:
%
% Notes:
%
% 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
%-

\documentclass{article}

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

\begin{document}

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

% 1. Header

\memobasic{
   Martin Elvis, SDS Group Leader }{
   Glenn E.\ Allen, SDS }{
   \abm }{
   3.6 }{
   http://space.mit.edu/CXC/docs/docs.html\#msk }{
   /nfs/cxc/h2/gea/sds/docs/memos/memo\_acis\_build\_mask\_3.6.tex }

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

% 2. Tool name

\section{\abm}

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

% 3. Description

\subsection{ Description }

A Level 1 ACIS mask file (acis*msk1.fits) for an observation contains
information about the valid ranges of CHIPX, CHIPY, and PHA for the
observation.  If a user specifies a spatial or spectral window to be used
for their observation, this information is recorded in the mask file. Level
1 ACIS bad pixel files (acis*bpix1.fits) also contain information about
which pixels or columns are valid.  One difference between a mask and a bad
pixel or column is that no events should be reported outside the valid
region of a CCD as specified in the mask file.  However, events may be
reported for the pixels and columns described in a bad pixel file.  The
contents of a bad pixel file should include only regions of a CCD that are
within the boundaries specified in the mask file. That is, the contents of a
mask file and the associated bad pixel file should be mutually exclusive.
(This condition is not true if ${\rm SAMP\_CYC} = 0$.) For example, the
edges of a CCD should be excluded using a mask file (instead of a bad pixel
file) because the onboard event detection algorithm does not report events
whose coordinates are at ${\rm CHIPX} = 1$ or 1024 or ${\rm CHIPY} = 1$ or
1024.  The node boundaries at ${\rm CHIPX = 256}$, 257, 512, 513, 768, and
769 are included in a bad pixel file (instead of a mask file) because it is
possible to have events along these columns.  The columns are considered bad
because most of the events in these columns are associated with cosmic rays.

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

% 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 that contains one extension for each active CCD.  Each
extension will have one or more rows with 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}

Since the columns WINDOW and OVERLAP, which are in older mask files, are not
necessary, they are not included here.

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

% 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=most)'' 

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

\end{enumerate}

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

% 7. Processing

\subsection{ Processing }
\label{processing}

One FITS extension is produced for every ``active'' CCD and each extension
has one or more rows.  A CCD is defined to be active if the CCD is included
in the ``PBK'' extension of the parameter block file.  One row in each
extension indicates that the entire CCD is disabled (see Table 2).
Additional rows are included as necessary.

\begin{enumerate}

\item
Verify that the specified extensions of the input files exist.  If clobber
$=$ ``no,'' 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.

\item
Add the keywords FIRSTROW and LASTROW to the header of the output file,
where
\begin{eqnarray}
{\rm FIRSTROW} 
   & =
   & {\rm STARTROW} + 1
   \\
{\rm LASTROW}
   & =
   & {\rm STARTROW} + {\rm ROWCNT} + 1
\end{eqnarray}
\begin{changebar}
However, if ${\rm FIRSTROW < 1}$ or ${\rm LASTROW > 1024}$, then do not
create the output file and exit with an error message that the keywords are
invalid.
\end{changebar}

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.]
The SHAPE is either a ``rectangle'' or ``!rectangle,'' as appropriate.

\item[b.]
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.]
If ${\rm SAMP\_CYC} \ge 1$, the permitted values of CHIPX and CHIPY are
specified to be ${\rm CHIPX[0]} \le {\rm CHIPX} \le {\rm CHIPX[1]}$ and
${\rm CHIPY[0]} \le {\rm CHIPY} \le {\rm CHIPY[1]}$. In most cases, an
entire CCD is active, ${\rm SAMP\_CYC} = 1$, and the CHIPX and CHIPY
boundaries have the default values listed in Table 1.

\begin{changebar}
{ \small
\begin{center}
\begin{tabular}{llcccc}
\multicolumn{6}{c}{Table 1. Default values for ${\rm SAMP\_CYC} \ge 1$}
\\
\hline
READMODE
   & DATAMODE
   & CHIPX[0]
   & CHIPX[1]
   & CHIPY[0]
   & CHIPY[1]
   \\
\hline
TIMED
   & FAINT
   & 2
   & 1023
   & 2
   & 1023
   \\
TIMED
   & FAINT\_BIAS
   & 2
   & 1023
   & 2
   & 1023
   \\
TIMED
   & GRADED
   & 2
   & 1023
   & 2
   & 1023
   \\
TIMED
   & VFAINT
   & 2
   & 1023
   & 3
   & 1022
   \\
CONTINUOUS
   & CC33\_FAINT
   & 2
   & 1023
   & 2
   & 511
   \\
\
   & \
   & 2
   & 1023
   & 514
   & 1023
   \\
CONTINUOUS
   & CC33\_GRADED
   & 2
   & 1023
   & 2
   & 511
   \\
\
   & \
   & 2
   & 1023
   & 514
   & 1023
   \\
\end{tabular}
\end{center}
}
\end{changebar}

There are cases where a CCD is active, but the entire CCD has a mask with a
sample cycle of zero. In this case, the values of ${\rm CHIPX}[0]$, ${\rm
CHIPX}[1]$, ${\rm CHIPY}[0]$, and ${\rm CHIPY}[1]$ have the default values
specified in Table~2.

{ \small
\begin{center}
\begin{tabular}{llcccc}
\multicolumn{6}{c}{Table 2. Default values for ${\rm SAMP\_CYC} = 0$}
\\
\hline
READMODE
   & DATAMODE
   & CHIPX[0]
   & CHIPX[1]
   & CHIPY[0]
   & CHIPY[1]
   \\
\hline
TIMED
   & FAINT
   & 1
   & 1024
   & 1
   & 1024
   \\
TIMED
   & FAINT\_BIAS
   & 1
   & 1024
   & 1
   & 1024
   \\
TIMED
   & GRADED
   & 1
   & 1024
   & 1
   & 1024
   \\
TIMED
   & VFAINT
   & 1
   & 1024
   & 1
   & 1024
   \\
CONTINUOUS
   & CC33\_FAINT
   & 1
   & 1024
   & 1
   & 1024
   \\
CONTINUOUS
   & CC33\_GRADED
   & 1
   & 1024
   & 1
   & 1024
\end{tabular}
\end{center}
}

More complex rectangular masks can be used, for example, to exclude the
zeroth order events for observations that use the gratings or to include
events from only a small region around a bright source such as the Crab. If
${\rm SAMP\_CYC} \ge 1$, then CHIPX[0], CHIPX[1], CHIPY[0], and CHIPY[1] are
computed using the expressions in Table 3.

\vspace*{0.5\baselineskip}
% \hspace*{-2.7in}

\begin{changebar}
\vbox{
\hspace*{-0.50in}
\small
\begin{tabular}{llcccc}
\multicolumn{6}{c}{Table 3. ${\rm SAMP\_CYC} \ge 1$}
\\
\hline
READMODE
   & DATAMODE
   & CHIPX[0]
   & CHIPX[1]
   & CHIPY[0]
   & CHIPY[1]
   \\
\hline
TIMED
   & FAINT
   & ${\rm LL\_CCDX} + 1$
   & ${\rm LL\_CCDX} + {\rm CCDCOL} + 1$
   & ${\rm LL\_CCDY} + 2$
   & ${\rm LL\_CCDY} + {\rm CCDROW}$
   \\
TIMED
   & FAINT\_BIAS
   & ${\rm LL\_CCDX} + 1$
   & ${\rm LL\_CCDX} + {\rm CCDCOL} + 1$
   & ${\rm LL\_CCDY} + 2$
   & ${\rm LL\_CCDY} + {\rm CCDROW}$
   \\
TIMED
   & GRADED
   & ${\rm LL\_CCDX} + 1$
   & ${\rm LL\_CCDX} + {\rm CCDCOL} + 1$
   & ${\rm LL\_CCDY} + 2$
   & ${\rm LL\_CCDY} + {\rm CCDROW}$
   \\
TIMED
   & VFAINT
   & ${\rm LL\_CCDX} + 1$
   & ${\rm LL\_CCDX} + {\rm CCDCOL} + 1$
   & ${\rm LL\_CCDY} + 3$
   & ${\rm LL\_CCDY} + {\rm CCDROW} - 1$
   \\
CONTINUOUS
   & CC33\_FAINT
   & ${\rm LL\_CCDX} + 1$
   & ${\rm LL\_CCDX} + {\rm CCDCOL} + 1$
   & 2
   & 511
   \\
\
   & \
   & ${\rm LL\_CCDX} + 1$
   & ${\rm LL\_CCDX} + {\rm CCDCOL} + 1$
   & 514
   & 1023
   \\
CONTINUOUS
   & CC33\_GRADED
   & ${\rm LL\_CCDX} + 1$
   & ${\rm LL\_CCDX} + {\rm CCDCOL} + 1$
   & 2
   & 511
   \\
\
   & \
   & ${\rm LL\_CCDX} + 1$
   & ${\rm LL\_CCDX} + {\rm CCDCOL} + 1$
   & 514
   & 1023
\end{tabular}
}
\end{changebar}

\vspace*{0.5\baselineskip}
For example, consider obsid 770, an observation of the Crab nebula.  The
only active CCD is ACIS-S3 and events are excluded from all but a
rectangular region defined in the Level 0 window file by ${\rm LL\_CCDX} =
185$, ${\rm LL\_CCDY} = 10$, ${\rm CCDCOL} = 139$, and ${\rm CCDROW} = 139$.
The appropriate CHIPX and CHIPY boundaries reported in the corresponding
mask file for the observation are ${\rm CHIPX}[0] = 186$, ${\rm CHIPX}[1] =
325$, ${\rm CHIPY}[0] = 12$, and ${\rm CHIPY}[1] = 149$.  Events can only be
reported for CHIPX values as low as 186 and as high 325 and for CHIPY values
as low as 12 and as high as 149.

\begin{changebar}
If ${\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. If ${\rm SAMP\_CYC} \ge 1$ and ${\rm CHIPX}[0] = 1$, ${\rm
CHIPX}[1] = 1024$, ${\rm CHIPY}[0] = 1$ (or $=$ 2 for TIMED VFAINT) or ${\rm
CHIPY}[1] = 1024$ (or $=$ 1023 for TIMED VFAINT), then change the value to
be consistent with Table 1.  
\end{changebar}

If ${\rm SAMP\_CYC} = 0$, then no events can be reported for the region
specified by ${\rm CHIPX}[0] \le {\rm CHIPX} \le {\rm CHIPX}[1]$ and ${\rm
CHIPY}[0] \le {\rm CHIPY} \le {\rm CHIPY}[1]$ (and the edges of a CCD),
where these coordinates are computed using the expressions in Table 4.

\vspace*{0.5\baselineskip}

\begin{changebar}
\vbox{
\hspace*{-0.50in}
\small
\begin{tabular}{llcccc}
\multicolumn{6}{c}{Table 4. ${\rm SAMP\_CYC} = 0$}
\\
\hline
READMODE
   & DATAMODE
   & CHIPX[0]
   & CHIPX[1]
   & CHIPY[0]
   & CHIPY[1]
   \\
\hline
TIMED
   & FAINT
   & ${\rm LL\_CCDX} + 1$
   & ${\rm LL\_CCDX} + {\rm CCDCOL} + 1$
   & ${\rm LL\_CCDY} + 1$
   & ${\rm LL\_CCDY} + {\rm CCDROW} + 1$
   \\
TIMED
   & FAINT\_BIAS
   & ${\rm LL\_CCDX} + 1$
   & ${\rm LL\_CCDX} + {\rm CCDCOL} + 1$
   & ${\rm LL\_CCDY} + 1$
   & ${\rm LL\_CCDY} + {\rm CCDROW} + 1$
   \\
TIMED
   & GRADED
   & ${\rm LL\_CCDX} + 1$
   & ${\rm LL\_CCDX} + {\rm CCDCOL} + 1$
   & ${\rm LL\_CCDY} + 1$
   & ${\rm LL\_CCDY} + {\rm CCDROW} + 1$
   \\
TIMED
   & VFAINT
   & ${\rm LL\_CCDX} + 1$
   & ${\rm LL\_CCDX} + {\rm CCDCOL} + 1$
   & ${\rm LL\_CCDY} + 1$
   & ${\rm LL\_CCDY} + {\rm CCDROW} + 1$
   \\
CONTINUOUS
   & CC33\_FAINT
   & ${\rm LL\_CCDX} + 1$
   & ${\rm LL\_CCDX} + {\rm CCDCOL} + 1$
   & 2
   & 511
   \\
\
   & \
   & ${\rm LL\_CCDX} + 1$
   & ${\rm LL\_CCDX} + {\rm CCDCOL} + 1$
   & 514
   & 1023
   \\
CONTINUOUS
   & CC33\_GRADED
   & ${\rm LL\_CCDX} + 1$
   & ${\rm LL\_CCDX} + {\rm CCDCOL} + 1$
   & 2
   & 511
   \\
\
   & \
   & ${\rm LL\_CCDX} + 1$
   & ${\rm LL\_CCDX} + {\rm CCDCOL} + 1$
   & 514
   & 1023
\end{tabular}
}
\end{changebar}

\vspace*{0.5\baselineskip} 
For example, obsid 1939 is a grating observation of 4U~1636$-$53. All six of
the ACIS-S CCDs are active, but the events in a rectangular region around
the zeroth order source position are excluded. This region is defined in the
Level 0 window file by ${\rm LL\_CCDX} = 180$, ${\rm LL\_CCDY} = 99$, ${\rm
CCDCOL} = 149$, and ${\rm CCDROW} = 199$.  The appropriate CHIPX and CHIPY
boundaries reported in the corresponding mask file for the observation are
${\rm CHIPX}[0] = 181$, ${\rm CHIPX}[1] = 330$, ${\rm CHIPY}[0] = 100$, and
${\rm CHIPY}[1] = 299$.  Events that land in this region will be excluded
from the telemetry for CHIPX values as low as 181 and as high 330 and for
CHIPY values as low as 100 and as high as 299.

\begin{changebar}
If ${\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.

If ${\rm LL\_CCDY} < {\rm STARTROW}$ or ${\rm LL\_CCDY} + {\rm CCDROW} >
{\rm STARTROW} + {\rm ROWCNT}$, then do not create the output file and exit
with an error message.
\end{changebar}

\item[d.]
The value of SAMP\_CYC for each component is copied from the Level 0 window
file.

\item[e.]
\begin{changebar}
The value of PHAMIN for a window (for all observing modes) 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.
\end{changebar}

\item[f.]
\begin{changebar}
The value of PHAMAX for a window (for all observing modes) 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.

For example, if ${\rm PHAMIN}_{\rm pbk} = 20$ and ${\rm PHARANGE}_{\rm pbk}
= 3750$, then ${\rm PHAMAX}_{\rm pbk} = 3769$.

If ${\rm PHAMIN}_{\rm win} = 0$ and ${\rm PHARANGE}_{\rm win} = 0$, then
ignore these values and use only the value from the parameter block file and
the value 32767. If ${\rm PHAMAX} \le {\rm PHAMIN}$, then do not create the
output file and exit with an error message.
\end{changebar}

\end{itemize}

\item
Write the output header and data to the specified output file.

\end{enumerate}

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

% 8. Finish

\end{document}
