% Time-stamp: <1998-10-22 16:29:09 dph> 
% MIT Directory: ~dph/h1/ASC/TG/Flight/L2_ICD/
% CfA Directory: /dev/null
% File: ICD_TGL2.tex
% Author: D. Huenemoerder
% Original version: 980423 based on TG L1.5
%
% (this header is ~dph/libidl/time-stamp-template.el)
% to auto-update the stamp in emacs, put this in your .emacs file:
%      (add-hook 'write-file-hooks 'time-stamp)
%====================================================================

\documentclass[twoside]{article}
\usepackage[dvips]{graphics}
\usepackage{changebar}

\textwidth=6.5in
\textheight=8.9in
\topmargin=-0.5in
\oddsidemargin=0in
\evensidemargin=0in

%%%%%%%%%%%%%%%%%%%%%% BEGIN dph useful macros %%%%%%%%%%+++++++++++++ 
%%
%%% Normally, these live in dph.sty, but to make this self-contained
%%% (mostly), I've inserted them here.

%%     suppress badness messages %%%%%%%%%%%%
\tolerance=10000 \hbadness=10000 \vbadness=10000

%%% Suppress widows and orphans! %%%
\widowpenalty=1000 \clubpenalty=1000  

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% a hack for marginal comments.
% doesn't work in certain environments (like tabular)
% easily runs out of room if margins are small

\marginparwidth 1.5in    %% adjust size of margin to give room for remarks
\marginparsep 2em                            

\newcommand{\Skinny}{
  \textwidth=5in\textheight=8.5in
  \oddsidemargin=0.5in
%  \evensidemargin=1in
%  \marginparwidth 2.0in                           %% adjust size of margin to
%  \marginparsep 0.2in                             %  give room for remarks
  \evensidemargin=1.2in
  \marginparwidth 1.5in                           %% adjust size of margin to
  \marginparsep 0.1in                             %  give room for remarks
  }

\newcommand{\Remark}[1]{\marginpar
%   {\fbox{\parbox{1.7in}{\raggedright\scriptsize#1}}}}
   {\fbox{\parbox{1.33in}{\raggedright\scriptsize#1}}}}

\newcommand{\Putline}{
%  \advance\textwidth-26pt
  \rule{\the\textwidth}{1pt}
%  \advance\textwidth+26pt
  }

\newcommand{\Note}[1]{
\begin{changemargin}{0.25in}{0in}
\advance\textwidth-26pt
\parbox{\textwidth}{      % testing...
\hfill\Putline\newline
%\parbox{\textwidth}{\small\sf#1}\\
{\small\sf#1}\\            % testing...
\Putline\newline
}       % testing...
\advance\textwidth+26pt
\end{changemargin}
}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% \putstring{x}{y}{angle}{scale}{gray}{string}
% gray: 0=black, 1=white

\newcommand{\putstring}[6]{
\special{!userdict begin /bop-hook{gsave #1 #2 translate
#3 rotate /Times-Roman findfont #4 scalefont setfont
0 0 moveto #5 setgray (#6) show grestore}def end}
}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% another putstring, but using eop-hook (what's then general ps solution?)
% \eputstring{x}{y}{angle}{scale}{gray}{string}
% gray: 0=black, 1=white

\newcommand{\eputstring}[6]{
\special{!userdict begin /eop-hook{gsave #1 #2 translate
#3 rotate /Times-Roman findfont #4 scalefont setfont
0 0 moveto #5 setgray (#6) show grestore}def end}
}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%    To change the margins of a document within the document,
%    modifying the parameters listed on page 163 will not work. They
%    can only be changed in the preamble of the document, i.e, before
%    the \begin{document} statement. To adjust the margins within a
%    document we define an environment which does it:
      \newenvironment{changemargin}[2]{\begin{list}{}{
         \setlength{\topsep}{0pt}\setlength{\leftmargin}{0pt}
         \setlength{\rightmargin}{0pt}
         \setlength{\listparindent}{\parindent}
         \setlength{\itemindent}{\parindent}
         \setlength{\parsep}{0pt plus 1pt}
         \addtolength{\leftmargin}{#1}\addtolength{\rightmargin}{#2}
         }\item }{\end{list}}
%    This environment takes two arguments, and will indent the left
%    and right margins by their values, respectively. Negative values
%    will cause the margins to be widened, so
%    \begin{changemargin}{-1cm}{-1cm} widens the left and right margins
%    by 1cm.
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\newcommand{\Header}[2]{
\pagestyle{myheadings}                   %%%%%%%%%%
\markboth{\bf \qquad #1 \hfill #2 \qquad}%%%%%%%%%%
         {\bf \qquad #1 \hfill #2 \qquad}%%%%%%%%%%
}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\long\def\dataprod ASC Data Product::#1
Instrument(s)::#2
Level::#3
Scientist/SDS::#4
Filetype::#5
Created by tool::#6
Used by tool(s)::#7
Sample file::#8
\par
{
%\clearpage
%\section{#1}
\begin{center}
\begin{tabular}{|lp{2in}|}
\multicolumn{2}{c}{Data Product Summary}\\\hline
ASC Data Product&#1\\
Instrument(s)&#2\\
Level&#3\\
Scientist/SDS&#4\\
Filetype&#5\\
Created by tool&#6\\
Used by tool(s)&#7\\
Sample file&#8\\\hline
\end{tabular}
\end{center}
\par
\bigskip
}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

%%%%%%%%%%%%%%%%%%%%%% END dph useful macros %%%%%%%%%%--------------


                                %%%%%%%
                                %
%%%%%%%%%%%%%%%%%%%%%% BEGIN jhouck useful macros %%%%%%%%%%--------------
\newcommand{\detect}{{\tt line\_\-detect\_\-features}}
\newcommand{\measure}{{\tt line\_\-measure\_\-features}}
\newcommand{\identify}{{\tt line\_\-identify\_\-features}}
%%%%%%%%%%%%%%%%%%%%%% END jhouck useful macros %%%%%%%%%%--------------
                                %
                                %%%%%%%






%%%
%%% Look for occurrences of five pound characters: #####, to locate places
%%% where updates are necessary
%%%

%%%
%%% revision info
%%%
\newcommand{\Revision}{\mbox{\em%
%%%
%%% ##### Update the revision information
%%%
%Revision 0.0---23 Apr 1998 % my first draft, uncirculated; only to J.Houck
%Revision 1.0---4 May 1998 % for review
%Revision 1.1---13 July 1998 % 
Revision 1.2 (DRAFT) --- 22 Oct 1998 % 
%Revision 1.3---xx mon 1998 % 
%Revision 1.4---xx mon 1998 % 
}}

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

\Skinny
\Header{Grating L2 to ASC Archive ICD /}{\Revision}
\begin{document}

% \putstring{x}{y}{angle}{scale}{gray}{string}
% gray: 0=black, 1=white
%\putstring{70}{80}{90}{40}{0.80}{- D R A F T -}
\eputstring{90}{30}{0}{8}{0.0}{Local File: /wiwaxia/h1/dph/ASC/ICD/L2_ICD/ICD_TGL2.tex}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%
%%% title stuff, no need to change anything
%%%

\begin{titlepage}

\begin{changemargin}{-1in}{-1in}

  \begin{center}
    {\huge\bf AXAF Science Center}

    \vspace*{0.1in}
    \leavevmode{\scalebox{0.17}{\includegraphics{asc_logo.eps}}}
    \vspace*{0.1in}

    {\LARGE\bf Grating Data Products:}

    \vspace*{0.1in}
    {\LARGE\bf Level 2 to ASC Archive}
    {\LARGE\bf Interface Control Document}
    ({\tt http://space.mit.edu/ASC/docs/ICD\_TGL2.ps.gz})
    \vspace*{0.2in}

    \Revision

  \end{center}

  \vfill
  {\small
  \begin{tabular}{lll}
    Submitted: & \rule{3.25in}{0.01in} & \rule{0.55in}{0.01in} \\
%
    & David Huenemoerder & Date   \\
    & Grating Scientists, ASC Science Data Systems & \\[0.15in]
%
     & \rule{3.25in}{0.01in} & \rule{0.55in}{0.01in} \\
%
    & John Houck & Date   \\
    & Grating Scientists, ASC Science Data Systems & \\[0.15in]
%
    Concurred: & \rule{3.5in}{0.01in} & \rule{0.75in}{0.01in} \\
    & Arnold Rots & Date   \\
    & ASC Data Systems Archive Scientist, Pipelines & \\[0.15in]
%
    Concurred: & \rule{3.5in}{0.01in} & \rule{0.75in}{0.01in} \\
    & Janet De Ponte & Date   \\
    & ASC Data Systems Group Leader, Pipelines & \\[0.15in]
%
    Concurred: & \rule{3.5in}{0.01in} & \rule{0.75in}{0.01in} \\
    & Martin Elvis & Date   \\
    & Manager, ASC Science Data Systems & \\[0.15in]
%
    Approved:  & \rule{3.5in}{0.01in} & \rule{0.75in}{0.01in} \\
    & Harvey Tananbaum & Date   \\
    & Director, ASC & \\
  \end{tabular}
}  % close {\small
\end{changemargin}

\end{titlepage}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%
%%% update info
%%%
\pagenumbering{roman}\setcounter{page}{2}

%%%
%%% ##### update as necessary
%%%

\begin{center}
\begin{tabular}{|c|c|c|p{3.0in}|} \hline
\multicolumn{4}{|c|}{}\\[1mm]
\multicolumn{4}{|c|}{\bf Document and Change Control Log}\\[3mm]\hline
{\bf Date} & {\bf Version} & {\bf Section} & {\bf Status} \\ \hline
%
23 Apr 98&
0.0&
all&
Initial Draft, for review by J.Houck \\\hline
%
4 May 98&
1.0  &
all  &
Update for review  \\\hline
%
8 July 98&
1.1  &
all  &
Update for release;\newline
ARF deleted from Type II PHA file.\newline
Type II PHA header refined.\newline
Added spectral measurement products.  \\\hline
%
9 August 98 &                           % date
1.2 &                           % version
4.2, 4.5 &                           % sections
Small changes to column specifications; 
new rows in REGION extension to describe background.\\\hline                   % comment
%%
%
22 October 98 &                           % date
1.2(DRAFT) &                           % version
 &                           % sections
Added changebars.  Updated unresolved issues (pending changes).
\\\hline                   % comment
%%
% &                           % date
% &                           % version
% &                           % sections
% \\\hline                   % comment
%
\end{tabular}
\end{center}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section*{Unresolved Issues}

The following is a list of unresolved, un-reviewed, or un-implemented
items: 

\begin{enumerate}


\item 980713: Need ASC FITS guidelines for header keyword file-name
  references (e.g., to GTI file used for ARF generation).

\item 980709: Summary products deferred to USG (postscript, gif, html,
  TBD).

\item 980709: Output file names for measurement product pipeline
  applications (if any).

\item 980709: Content keywords identifying the various FITS extensions
  for measurement products.

\item 980709: Applicable document references for measurement products.



%\item 980404: Only included spectrum file, exposure map (ARF)
%  extension, and region extension.

%  To be added:  ARF (file); redistribution (RMF) (file); measurement
%  products, summary products.

\item 981022 Need to include specification of Type I PHA file. (next
  revision, 1.3). 

\item Need to specify grating redistribution matrix function (next
  revision, 1.3)


\end{enumerate}

\Note{Formatting NOTE:
  Text formatted between horizontal rules (like this block) provide
  some historical context regarding alternative choices considered, 
  which may still be debated.
}
\Remark{Items boxed in the right margin (like this) are questions to
be answered or TBD's to be replaced.}



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




%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%
%%% table of contents, list of tables
%%%

\clearpage
\tableofcontents
%\clearpage
\listoftables
\listoffigures
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\pagenumbering{arabic}
\clearpage
\section{Introduction}

This document describes the interface to be employed in transferring
the products of grating (HETG, the High Energy Transmission Grating,
or LETG, the Low Energy Transmission Grating) obervations Standard
Data Processing from the ASC Level~2 processing pipeline to the ASC
Data Archive, according to the requirements stipulated in the ``ASC
Data System Requirements'' (Applicable Document~\ref{appdoc:se03}).
%


\subsection{Purpose}

TG (generically referring to HETG and LETG Transmission Grating
instruments) Level~2 processing, described in Applicable
Document~\ref{appdoc:se03}, consists of processing TG Level~1.5 event
files and ancillary products (which are described in Applicable
Document~\ref{appdoc:tgl15icd} into a binned-spectral FITS file. This
document describes the structure and content of the
resulting files.  In addition, the Level 2 pipeline produces ancillary
calibration products (effective area and redistribution files),
measurements (feature detection and characterization), and summary
information products.


\subsection{Scope}

This interface shall apply to all TG-specific data products that are
generated by ASC Level 2 pipelines and distributed to the ASC Data
Archive (see Applicable Document~\ref{appdoc:se03} and the ``ASC Data
System Software Design,'' Applicable Document~\ref{appdoc:ds01}) 
during the course of the AXAF mission.

%\clearpage
%
\subsection{Applicable Documents}
The Applicable Documents required for background and detail on
grating Level 2 products are as follows:
\begin{enumerate}
%
%\item\label{appdoc:data-prod} 
%  AXAF Data Products Guide\newline
%  {\tt http://hea-www.harvard.edu/asclocal/sds/CDR2/dp.ps}
%%
\item\label{appdoc:coord}
 AXAF Coordinate Systems\newline
    {\tt http://hea-www.harvard.edu/$_{\verb@~@}$jcm/asc/coords}
%
\item\label{appdoc:se03}
 ASC AMO-2400 (SE03) \newline
 ASC Data System Requirements (ASC.302.93.0008)
%
\item\label{appdoc:ds01}
 ASC AMO-2401 (DS01) \newline
 ASC Data System Software Design (ASC.500.93.0006)
%
%\item\label{appdoc:fitsdef}
% NOST 100-1.1, Definition of the Flexible Image Transport System
%                    (FITS)\newline
%                    {\tt http://www.cv.nrao.edu/fits/}
%%
%\item\label{appdoc:fitsstd}
% HEASARC FITS Standards:\newline
%{\tt http://heasarc.gsfc.nasa.gov/docs/heasarc/ofwg/ofwg\_intro.html}
%%
\item\label{appdoc:ascfits}
  ASC FITS File Designers' Guide\newline
  {\tt http://hea-www.harvard.edu/$\sim$arots/asc/fits/ascfits.ps}
%
\item\label{appdoc:hrcicd} 
 HRC Data Products Guide:\newline
 Level 1 to ASC Archive Interface Control Document\newline
 {\tt http://hea-www.harvard.edu/asclocal/sds/ICD/l1icd.ps.gz}
%
\item\label{appdoc:acisicd}
 ACIS Data Products Guide:\newline 
    Level 1 to ASC Archive Interface Control Document\newline
 {\tt http://space.mit.edu/ASC/docs/acis\_l1.ps.gz}
%
\item\label{appdoc:tgl15icd}
 Grating Data Products:\newline 
    Level 1.5 to ASC Archive Interface Control Document\newline
 {\tt http://space.mit.edu/ASC/docs/ICD\_L1.5.ps.gz}
%
\item\label{appdoc:ascfiles}
 FITS File Names for the AXAF Archive:\newline 
 {\tt http://hea-www.harvard.edu/$\sim$arots/asc/archive/files.html}
%
\item\label{appdoc:regfiles}
FITS REGION Binary Table Design (ASC-FITS-REGION-1.0)\newline
{\tt http://hea-www.harvard.edu/$\sim$arots/asc/fits/region.ps}
%
\item\label{appdoc:ogipspec}
The OGIP Spectral File Format (OGIP/92-007)\newline
{\tt http://heasarc.gsfc.nasa.gov/docs/heasarc/TBD.html}
%
\end{enumerate}
\Remark{TBD: Get OGIP/92-007 URL}

% synopsis for editing purposes...
%
%   1 appdoc:data-prod AXAF Data Products Guide
%   2 appdoc:coord     AXAF Coordinate Systems
%   3 appdoc:se03      ASC AMO-2400 (SE03)
%   4 appdoc:ds01      ASC AMO-2401 (DS01)
%%   5 appdoc:fitsdef   NOST 100-1.1, Definition of the FITS
%%   6 appdoc:fitsstd   HEASARC FITS Standards:
%   7 appdoc:ascfits   ASC FITS Designers' Guide
%   8 appdoc:hrcicd    HRC Data Products Guide:
%   9 appdoc:acisicd   ACIS Data Products Guide:
%  10 appdoc:tgl15icd  TG Level 1.5 ICD
%  11 appdoc:ascfiles  filename convention
%  12 appdoc:regfiles  region file definition
%     appdoc:ogipspec   The OGIP Spectral File Format (OGIP/92-007)

%\clearpage
%

\subsection{Data Content Summary}

TG data sets generated by the Level~2 processing pipeline shall
consist of data files conforming to the FITS format coforming to 
conventions described in the ``ASC FITS File Designers' Guied''
(Applicable Document~\ref{appdoc:ascfits}, and references therein). 
These files 
contain header keyword entries and binary table (BINTABLE) extensions.
Following rules outlined in Applicable Document~\ref{appdoc:ascfits},
all these files will contain a null primary header followed by a main
binary table (the ``principal HDU'') and auxiliary extensions
(``auxiliary HDU'').

Any other types of files will either be of types in common use (e.g.,
PostScript), or fully described here.

\subsection{Recipients and Utilization}

The primary recipients of TG Level~2 data products, via distribution
from the archive, are AXAF observers, who will utilize these data
products for scientific data analysis. The ASC may also make use of
specific Level~2 data products for instrument calibration, instrument
and/or spacecraft monitoring and trends analysis, and validation and
verification of the Level 0, Level 1, Level 1.5, and Level 2 software
and of the data products themselves.

\subsection{Pertinent Relationships with Other Interfaces}

Changes to the definition of Level 1.5 data products, as described in
Applicable Document~\ref{appdoc:tgl15icd} may affect the Level 2 data
products described in the current document.

\subsection{Assumptions and Constraints}


\subsubsection{Missing or Undefined Data}

The IEEE value, ``NaN'' (Not A Number) is used for missing real
values.  Note that this is not explicitly encoded as a TNULL keyword
value in the table headers; it is implicit in the FITS standard.  

\subsubsection{Time Dependent Data}

For each TG science event run reported in the AXAF telemetry stream,
Level 2 processing shall generate a set of product files as
described in Section~\ref{sec:labeling}.  The products depend upon
possibly time-dependent calibration data for coordinate
transformations and region definitions.

\subsubsection{Observation Intervals}

The natural subdivision of TG processing prior to Level 2 is the
Observation Interval (ObI). Each ObI may span several TG science runs,
which are the atomic unit of the scientific instrument's telemetry.
TG data prior to Level 2 will be processed by ObI.  The Level 2
pipeline assumes that ObIs have been merged.  This is not a necessary
requirement, so each ObI (or other time-interval) can in principal
produce its own Level 2 products, but the pipeline will process merged
ObIs.

\subsubsection{Un-specified FITS Bintable Columns}
Any particular file {\em may} contain arbitrary additional columns,
added at other stages of processing, or by a User.  Though they are
unspecified, they are permitted.  Level 2 software (analysis tools)
should ignore them or simply pass them through to output, as directed
by Level 2 tool specifications.  Their presence should, however, {\em
  not} invalidate the product as TG Level 2.

\cbstart

\subsubsection{HDU Identifier Keywords}

Unless explicitly noted, the {\tt HDUNAME} and {\tt EXTNAME} header
keywords will be identical.

\cbend

\subsection{Products Not Covered}

TG Level 2 products that are used for maintenance and diagnostic
purposes (those that are not supplied to the user for scientific data
analysis), or which are generic AXAF Level 2 products, are
not currently included within the interface defined by this document.

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

%\clearpage
%

\section{Labeling and Identification}\label{sec:labeling}

The data files generated by the Level 2 processing pipeline shall be
assigned external names as defined by the following general convention,
(specified in ``FITS File Names for the AXAF Archive'', Applicable
Document~\ref{appdoc:ascfiles}):%

\centerline{\tt <i><s><t><v>\_[<f>\_]<c><l>[<sl>].<type>}

\noindent where the mnemonics are:

\begin{description}
\item[\tt <i>]     Instrument: ``acis'', ``hrci", ``hrcs'', \ldots
\item[\tt <s>]     Data source: ``x'', ``f'', ``t'', ``b'', ``s'', ``u''
\item[\tt <t>]     TSTART (integer part): ``\#\#\#\#\#\#\#\#\#''
\item[\tt <v>]     Processing run (version): ``N\#\#\#''
\item[\tt <f>]     Optional discriminator (e.g., an ACIS FEP Id)
\item[\tt <c>]     Contents: ``evt'', ``prf'', ``hst'', ``src'', 
                             ``win'', ``bias'', ``sum'', \ldots
\item[\tt <l>]     Processing level: single digit: ``0'', ``1'', ``2''
\item[\tt <sl>]    Sublevel: single lower case letter; e.g., 1.5 is ``1a''
\item[\tt <type>]  Superfluous: usually ``fits''
\end{description}
%

Relevant default values for instrument ({\tt <i>}) are {\tt aciss} or
{\tt hrcs}; for data source ({\tt <s>}) is ``f'' for flight (or
possibly ``s'' for simulation). The appropriate designation for the
processing level and sublevel is ``2''.  Level 2 products are listed
in Table~\ref{tab:l2prods}.

\Remark{Measurements files TBD by J.Houck}
\begin{table}[h]\label{tab:l2prods}
\begin{tabular}{|lp{2in}p{2in}|}\hline
%
{\tt *}\_pha2.fits&
Binned spectra, Level 2, contents are ``Type II `PHA' ''&
required\\
%
{\tt *}\_arf.fits&
spectral responses&
Required.  \\
%
{\tt *}\_rmf.fits&
Spectral redistribution file&
Required\\
%
{\tt *}\_reg2.fits&
Spectral extraction region&
Optional. By default, included in the FITS product as an extension.\\
%
{\tt *}\_TBD.fits& 
Spectral measurements.&
Required.  Strong features in spectrum.\\\hline
%
{\tt *}\_sum.ps&
Postscript summary&
required (TBS by USG)\\
%
{\tt *}\_sum.html&
Hypertext summary&
(TBR by USG)\\
%
{\tt *}\_TBD.gif&
GIF summary images&
(TBR by USG)\\ \hline
\end{tabular}
\caption[L2 product list]{\it These are required and optional grating
  Level 2 product files. The ``*'' designates an appropriate label
  sub-string as described in the text.}
\end{table}

\section{Overview of Files}

The ``ASC FITS Designers' Guide'' (Applicable Document
~\ref{appdoc:ascfits}) defines and lists general header components for
the primary header and for all binary table extensions.  Since grating
data are always obtained with either the HRC or ACIS detectors, file
content is also described in detail by the HRC and ACIS Level 1
Interface Control Documents (Applicable Documents~\ref{appdoc:hrcicd}
and ~\ref{appdoc:acisicd}).  Level 1.5-added content is described in
the Level 1.5 ICD (Applicable Document~\ref{appdoc:tgl15icd}).

\begin{description}
%
\item[Spectrum:  ] The basic product is a binned spectrum.  This
  product is based on the OGIP Type II PHA Spectrum (see ``The OGIP
  Spectral File Format'', Applicable Document~\ref{appdoc:ogipspec}.
  New columns have been added to describe the source, spectrum part,
  and order.  Column names have been taken from the Level 1.5
  definition.    The ACIS intrinsic energy region (PHA, or PI) is
  specified by calibration tables (named in the header) and by
  processing history (parameters).
%
\item[Spectral Response: ] The spectral response is the effective area
  times exposure time (the exposure map).  This accounts for
  variations in efficiency with position on the detector, including
  source position and position variation with time (dither) and
  detector gaps, as well as spectral order.  It depends on the
  spatial/spectral extraction region (in particular the
  cross-dispersion aperture and the PI-order-sorting region, if ACIS),
  which are accounted for in the Level 2 exposure map calculation.
  This is traditionally referred to as an Auxiliary Response File
  (ARF), which is equivalent to the exposure map divided by time
  ($\mathrm{[cm^2]}$ vs energy).  It is a source-specific functio for
  AXAF grating observations.  Since a finer grid than the counts
  spectrum is generally desired, it will be provided as a separate
  file, instead of including the information as another column in the
  spectrum file. 

  \Remark{Issue: The units of an exposure map are $[\mathrm{cm^2\,s\,
      \AA}]$.  Dividing counts by this, gives flux in units
    of $[\mathrm{photons\,cm^{-2}\,s^{-1}\,\AA^{-1}}]$.  Should we
      instead normalize the spectrum by some exposure time (e.g., sum
      of global GTI)?}
%
\item[Spectral Redistribution:  ] The redistribution describes the
  energy-dependent convolution kernel of the line-spread-function.  It
  depends on the source position via the off-axis angle.  Hence, it is
  in general different for every source, but varies slowly near the
  optical axis.  It is provided as traditional OGIP Response Matrix
  Files (RMF), each of which may includes multiple orders.
%
\item[Region: ] The binned spectra are selected from a
  spatial/spectral and PI (Pulse Invariant) region of the Level 1.5
  file.  The region is given in grating diffraction coordinates (one
  coordinate in the dispersion direction, and one in the
  cross-dispersion direction; see
  Applicable Documents~\ref{appdoc:coord} and~\ref{appdoc:tgl15icd}).    The
  spatial/spectral extraction region mask is by default encoded as a
  region  extension (see ``FITS REGION Binary Table Design
  (ASC-FITS-REGION-1.0)'', Applicable Document~\ref{appdoc:regfiles})
  in the Level 2 FITS file.  The PI region is not encoded
  explicitly, but is implicit in calibration files and processing
  history.
%
\item[Measurements:  ] The binned spectra have features such as
  emission lines, absorption lines, and edges.  Standard measurement
  products derived from these spectra will be collected into FITS bintables.
  Those spectral measurements which can be done without significant
  scientific judgement (such as strong emission line detection and
  characterization) are done automatically by the Level 2 pipeline.
  The specific quantities will evolve with experience, and are
  tentatively (all TBR):
%
\Remark{Measurement products TBD by J.Houck}
%
  \begin{itemize}
  \item line wavelength and uncertainty
  \item line flux and uncertainty
  \item line width and uncertainty
  \item line ID
  \item continuum spectrum and uncertainty
  \item edge position and uncertainty
  \item edge depth and uncertainty
  \end{itemize}
Other measurements can only be done via interactive analysis.
%
\item[Summary:  ] At the end of Level 2 processing, summary products
%
\Remark{TBD by USG: summary products}
%
  are produced for quick-look inspection and assessment by the
  end-user, and also by ASC validation and verification processing.
  Products are tentatively:
  \begin{itemize}
  \item Postscript plots and tables of spectra, images, results (e.g.,
    field image, spectral regions, PHA-position plots, binned spectra,
    total counts vs source, counts vs order vs source, fluxed spectra)
  \item HTML interface to summary products
  \item GIF versions of images and plots
  \end{itemize}
  Products may exist both as Postscript files which can be viewed or
  directly printed, and/or hypertext files for easy interactive
  viewing.
%
\end{description}
%

\clearpage
\section{Spectral Histogram Files (*\_pha2.fits)}
\dataprod ASC Data Product::Binned Spectrum
Instrument(s)::HETG, LETG
Level::2
Scientist/SDS::D.~Huenemoerder
Filetype::PHA II
Created by tool::tgextract
Used by tool(s)::various
Sample file::TBS
\par

During Level 1.5 processing, event coordinates undergo several
transformations.  Given a zero-order centroid in sky coordinates, a
region angle, and region width, events within each region are given
several new coordinates.  Proper interpretation of the spectrum
requires consistent selection on several coordinates.  These
coordinates are carried over into the Level 2 spectrum file as
attributes of the spectrum.
%
\begin{description}
%
\item[$TG\_SRCID$ ] is the source number, as output from the detection
  algorithm.  A $TG\_SRCID$ of 0 means background --- the photon has
  not been associated with a detected source.  It is permitted to
  store binned spectra from multiple sources in one Type II file.
  However, for archival use it is advantageous to split files by
  source when this can be done uniquely.  Hence, pipeline binned
  spectral products will be per source.\footnote{It must be kept in
    mind that if there are multiple sources in HETG observations the
    orders from different sources cross and photons in those regions
    may not be unambiguously resolved.  If the region is
    scientifically important, the spectra must be analyzed jointly
    starting with the Level 1.5 event-list.}
%
\item[$TG\_PART$ ] identifies the region of the spectrum of which the
  photon is a part.  This can have only specific values as follows:
  \begin{description}
  \item[0:  ] zero order;
  \item[1:  ] HEG part of the spectrum;
  \item[2:  ] MEG part;
  \item[3:  ] LETG photon;
  \item[4--7:  ] LETG/HESF parts of the spectrum;
  \item[99:  ] background.
  \end{description}
%
\item[$TG\_M$: ] The diffraction order, if resolved.  This is a small
  integer, not likely to be of absolute value greater than 10 for
  HETG/ACIS-S.  The value, $99$,
  is used as a flag for ``unresolved'' or background photons.
  
  For LETGS photons (detector is HRC, $TG\_PART$ is 3-7), $TG\_M$ will
  be either $+1$ or $-1$ (since HRC cannot resolve the orders via a
  pulse-height value).  

  The physically meaningful geometric limit set by the
  ACIS-S array with HETG is about $\pm62$.  This is for a 10 keV
  photon observed with the aim-point at one end of the ACIS-S array,
  and the detected photon at the other end.  It is not a likely
  scenario, but is used to define allowed physically conceivable data
  ranges. 
%
\end{description}
%
%

\subsection{HDU Components}

The following table (Table~\ref{tab:spechdu}) describes the file
structure by Header-Data Unit number, type, extension name, content,
and HDU classes.  An asterisk (*) denotes the principal HDU.
%
\begin{table}[h]
{\small
\noindent\begin{tabular}{|llccp{0.8in}p{1.5in}|}\hline
HDU
& Type
& EXTNAME
& CONTENT
& HDUCLASS
& Description
\\
\hline
%
1 
& NULL
& N/A
& N/A
& N/A
& 
\\
%
2 (*)
& BINTABLE
& SPECTRUM
& SPECTRUM
& ASC\newline SPECTRUM\newline TOTAL\newline COUNTS\newline TYPE:II\newline TG
& Binned spectra, vs order vs source, grid, and ancillary information.
\\
%
3
& BINTABLE
& REGION
& REGION
& ASC\newline REGION\newline TG
& Spectral-spatial region over which the spectrum was binned.
\\
%
\hline
\end{tabular}\label{tab:spechdu}
}   % close \small
\caption[Spectrum File Components]{\it The Header-Data Unit structure of
  the binned spectrum FITS file.}
\end{table}
%
The structure of the HDUs, as specified by the ASC FITS Guide
(Document~\ref{appdoc:ascfits}), is
\begin{itemize}
\item Null Primary HDU:
  \begin{itemize}
  \item image mandatory
  \item null configuration control
  \item short timing
  \item short observation
  \end{itemize}
\item Principal table HDU:
  \begin{itemize}
  \item bintable mandatory
  \item table coordinates
  \item full configuration control
  \item full observation
  \item full timing
  \end{itemize}
\item Auxiliary table HDU:
  \begin{itemize}
  \item bintable mandatory
  \item table coordinates
  \item short configuration control
  \item short timing
  \item short observation
  \end{itemize}
\end{itemize}

%
\subsection{Column Specifications}

The contents of the FITS columns of the binned spectrum extension are
given in the following tables (Table~\ref{tab:speccontents}).  These
generally conform to the ``OGIP Type II PHA'' definition (See
Document~\ref{appdoc:ogipspec}), with some additions appropriate for
AXAF grating spectra.  Some columns are optional, but are listed for
complete compatibility with the OGIP standard; those that probably
won't be used are in a separate table (Table~\ref{tab:specunused}).
Columns which are constant may be promoted to header keywords. Some
are mutually exclusive; for example, if a {\tt BACKGROUND} array
column is present, then {\tt BACKFILE} does not need to be specified.
These various conditions will be explained below.  The primary point
of following the OGIP Type II specification is to maintain
compatibility with {\sc Xspec}.

The length of the vector columns (specified by {\tt TFORM}$n$, such as
for ``COUNTS'' or ``FLUX'') is given in the table as 16384.  This is a
{\em representative maximum length}! It could in principal be longer
or shorter.  For LETGS, for example, binning at a single resolution
element per bin will give about 6700 bins, and HETGS about 3400.
Analysis tools can specify arbitrary binning.  Pipelines will default
to 0.5-1.0 resolution-element bins.  Custom analysis may produce files
only containing a few bins around lines of interest, or even
arrays discontinuous in wavelength to hold several regions of
interest. 

The pipelines will bin the events into counts {\it vs.}\ wavelength,
and fluxes into the natural units of 
$\mathrm{photons\, cm^{-2}\,  s^{-1}\, \AA{^-1}}$ {\it vs.}\ $\mathrm{\AA}$, 
and so these are the
  units and coordinates specified in the column descriptions.
  However, custom analysis may convert wavelengths to energy units in
  the Level 1.5 event list, and then bin into counts {\it vs.}\ energy.
  Likewise, analysis could produce flux in units of $\mathrm{ergs}$
  instead of photons.  These are all permitted in a spectrum file, as
  long as consistency is maintained within the grid columns ({\sc
    Binlo, Binhi}) and units column.  

\clearpage
%
\begin{table}[htb]\label{pg:NULLi}
\begin{center}
{\small
\begin{tabular}{|c|p{0.45in}|c|c|p{0.4in}|p{0.45in}|c|p{1.4in}|}
\hline
 & & & & & & &\\
\sc ttype
 & \sc tunit
 & \sc tform 
 & \sc tlmin
 & \sc tlmax
 & \sc tdbin
 & \sc tnull
 & \multicolumn{1}{|c|}{Comments}\\
 & & & & & & &\\\hline
%
\sc spec\_num                          % TTYPE
 &                             % TUNIT    
 & 1I                                % TFORM 
 & 1                         % TLMIN
 & N/A                              % TLMAX
 & N/A                              % TDBIN
 & 0                      % TNULL
 & Required. Spectrum number.    \\\hline                 % comment
%
\sc rowid                             % TTYPE
 &                                % TUNIT
 & 64A                             % TFORM
 & \sc n/a                            % TLMIN
 & \sc n/a                            % TLMAX
 & \sc n/a                            % TDBIN
 & \sc none                             % TNULL
 & Optional; Arbitrary string identifier  \\\hline                     % comment
%
\sc  tg\_m                            % TTYPE  
 &                                % TUNIT  
 & 1I                             % TFORM  
 & $-62$                          % TLMIN  
 & $62$                           % TLMAX  
 & \sc n/a                            % TDBIN  
 & 99                             % TNULL  
 & Required; diffraction order ($m$) \\\hline           % comment
%
\sc  tg\_part                         % TTYPE  
 &                                % TUNIT  
 & 1I                             % TFORM  
 & 0                              % TLMIN  
 & 99                             % TLMAX  
 & \sc n/a                            % TDBIN  
 & \sc n/a                            % TNULL  
 & Required; Spectral component (HEG, MEG, LEG, \ldots) \\\hline% comments
%
\sc  tg\_srcid                        % TTYPE  
 &                                % TUNIT  
 & 1I                             % TFORM  
 & 1                              % TLMIN  
 & \sc tbd                             % TLMAX  
 & \sc n/a                            % TDBIN  
 & 0                              % TNULL  
 & Required; source ID.  If constant (files split by source), then
 this becomes a header keyword: {\tt TG\_SRCID =  $n$}
\\\hline             % comment
%
\sc ancrfile                                % TTYPE
 &                               % TUNIT
 & 64A                               % TFORM
 & \sc n/a                              % TLMIN
 & \sc n/a                              % TLMAX
 & \sc n/a                              % TDBIN
 & \sc none                              % TNULL
 & Required; Ancillary response file name (ARF). 
\\\hline
%
\sc respfile                                % TTYPE
 &                               % TUNIT
 & 64A                               % TFORM
 & \sc n/a                              % TLMIN
 & \sc n/a                              % TLMAX
 & \sc n/a                              % TDBIN
 & \sc none                              % TNULL
 & Required.  Redistribution file name (RMF).
  \\\hline                    % comment
%
\sc backfile                                % TTYPE
 &                               % TUNIT
 & 64A                              % TFORM
 & \sc n/a                              % TLMIN
 & \sc n/a                              % TLMAX
 & \sc n/a                              % TDBIN
 & \sc none                              % TNULL
 & Optional; background file.
 \\\hline                    % comment
%
\sc channel                                % TTYPE
 &                               % TUNIT
 & 16384I
                                % TFORM
 & 1                              % TLMIN
 & 16384                              % TLMAX
 & 1                              % TDBIN
 & 0                              % TNULL
 & Required; Vector of spectral ``channel'' numbers.   \\\hline                    % comment
%
\sc counts                                % TTYPE
 & counts                              % TUNIT
 & 16384I                              % TFORM
 & 0                              % TLMIN
 & 16384                              % TLMAX
 & 1                              % TDBIN
 & -1                             % TNULL
 & Required; Counts array (a spectrum).  
  \\\hline                    % comment
%
\sc stat\_err                                % TTYPE
 & counts                               % TUNIT
 & 16384E                              % TFORM
 & 0.0                              % TLMIN
 & N/A                              % TLMAX
 & N/A                              % TDBIN
 & \sc NaN                              % TNULL
 & Optional; statistical uncertainty (``error'') on count column.
  \\\hline                    % comment
%
\sc quality                                % TTYPE
 &                               % TUNIT
 & 16384I                              % TFORM
 & 0                              % TLMIN
 & 16384                              % TLMAX
 & \sc n/a                              % TDBIN
 & \sc tbd                              % TNULL
 & Optional; Quality flag.
  \\\hline                    % comment
%
\sc grouping                                % TTYPE
 &                               % TUNIT
 & 16384I                              % TFORM
 & -1                              % TLMIN
 & 1                              % TLMAX
 & \sc n/a                              % TDBIN
 & \sc tbd                              % TNULL
 & Optional. Grouping vector. 
\\\hline                    % comment
%
\sc background                                % TTYPE
 & counts                              % TUNIT
 & 16384I                              % TFORM
 & 0                              % TLMIN
 & N/A                             % TLMAX
 & 1                              % TDBIN
 & -1                              % TNULL
 & Optional; background count vector.
 \\\hline                    % comment
%
\sc binlo                                % TTYPE
 &   angstrom                            % TUNIT
 &   16384D                            % TFORM
 &  0.0                             % TLMIN
 &  400.0                             % TLMAX
 &  1.0E-04                            % TDBIN
 &  NaN                             % TNULL
 &  Required; Bin boundary, low coordinate. \\%\hline   % comment
%%
                               % TTYPE
 &   degrees                            % TUNIT
 &   16384D                            % TFORM
 &  -2.0                             % TLMIN
 &  2.0                             % TLMAX
 &  8.0E-05                             % TDBIN
 &  NaN                             % TNULL
 & \\
%%
                               % TTYPE
 &   mm                            % TUNIT
 &   16384D                            % TFORM
 &  0.0                             % TLMIN
 &  300                             % TLMAX
 &  0.012                             % TDBIN
 &  NaN                             % TNULL
 & \\
%%
                               % TTYPE
 &   keV                            % TUNIT
 &   16384D                            % TFORM
 &  0.0                             % TLMIN
 &  14.                             % TLMAX
 &  1.0E-03                    % TDBIN
 &  NaN                             % TNULL
 &  \\
%%
                               % TTYPE
 &  pixel                            % TUNIT
 &   16384I                            % TFORM
 &  0                             % TLMIN
 &  65536                             % TLMAX
 &  1                              % TDBIN
 &  0                             % TNULL
 & 
\\\hline
%
\sc binhi                                % TTYPE
 & angstrom                              % TUNIT
 & 16384D                              % TFORM
 & 0.0                              % TLMIN
 & 400.0                              % TLMAX
 & 1.0E-04                              % TDBIN
 & NaN                              % TNULL
 & Required; Bin boundary, high coordinate  \\%\hline  % comment
%%
                               % TTYPE
 &   degrees                            % TUNIT
 &   16384D                            % TFORM
 &  -2.0                             % TLMIN
 &  2.0                             % TLMAX
 &  8.0E-05                             % TDBIN
 &  NaN                             % TNULL
 & \\
%%
                               % TTYPE
 &   mm                            % TUNIT
 &   16384D                            % TFORM
 &  0.0                             % TLMIN
 &  300                             % TLMAX
 &  0.012                             % TDBIN
 &  NaN                             % TNULL
 & \\
%%
                               % TTYPE
 &   keV                            % TUNIT
 &   16384D                            % TFORM
 &  0.0                             % TLMIN
 &  14.                             % TLMAX
 &  1.0E-03                    % TDBIN
 &  NaN                             % TNULL
 & \\
%%
                               % TTYPE
 &  pixel                            % TUNIT
 &   16384I                            % TFORM
 &  0                             % TLMIN
 &  65536                             % TLMAX
 &  1                              % TDBIN
 &  0                             % TNULL
 &   \\\hline                    % comment
%
\sc flux                                % TTYPE
 & photons /s /cm**2 / angstrom                              % TUNIT
 & 16384E                              % TFORM
 & 0.0                              % TLMIN
 & \sc tbd                              % TLMAX
 & \sc tbd                              % TDBIN
 & NaN                              % TNULL
 & Optional; Flux;  ergs or photons per angstrom.  
 \\\hline                    % comment
%
\sc flux\_err                                % TTYPE
 & (same as FLUX)                              % TUNIT
 & 16384E                              % TFORM
 & 0.0                              % TLMIN
 & \sc tbd                              % TLMAX
 & \sc tbd                              % TDBIN
 & NaN                              % TNULL
 & Optional. Uncertainty on flux.
 \\\hline                    % comment
%
\end{tabular}
}   % close \small
\caption[Spectrum FITS Required and Recommended Column Definitions]
{\it Required and Recommended FITS spectrum data file binary table
  contents for extension ``SPECTRUM'' (one entry per spectrum).
  ``N/A'' means ``Not Applicable''.  The ``TNULL'' value of ``NaN''
  stands for the IEEE ``Not A Number'' (which is not actually encoded
  into the header, but is implicit in the FITS convention). 
}
\label{tab:speccontents}
\end{center}
\end{table}%
%
%
\clearpage

                    %%%%%%%%%%               %%%%%%%%%%
\begin{table}[h]
\begin{center}
%\noindent Columns Unlikely to be Used
{\small
\begin{tabular}{|c|p{0.65in}|c|c|p{0.5in}|p{0.425in}|c|p{1.65in}|}
\hline
 & & & & & & &\\
\sc ttype
 & \sc tunit
 & \sc tform 
 & \sc tlmin
 & \sc tlmax
 & \sc tdbin
 & \sc tnull
 & \multicolumn{1}{|c|}{Comments}\\
 & & & & & & &\\\hline
%
\sc backscal                                % TTYPE
 &                               % TUNIT
 & 1E                               % TFORM
 & \sc tbd                              % TLMIN
 & \sc tbd                              % TLMAX
 & \sc n/a                              % TDBIN
 & NaN                              % TNULL
 & Optional. Background scale factor.  \\\hline                    % comment
%
\sc corrfile                                % TTYPE
 &                               % TUNIT
 & 64A                              % TFORM
 & \sc n/a                              % TLMIN
 & \sc n/a                              % TLMAX
 & \sc n/a                              % TDBIN
 & none                              % TNULL
 & Optional. ``Correction'' file.  \\\hline                    % comment
%
\sc  corrscal                               % TTYPE
 &                               % TUNIT
 & 1E                              % TFORM
 & \sc tbd                              % TLMIN
 & \sc tbd                              % TLMAX
 & \sc n/a                              % TDBIN
 & NaN                              % TNULL
 & Optional. ``Correction'' scale factor.  \\\hline                    % comment
%
\sc sys\_err                                % TTYPE
 & counts                              % TUNIT
 & 16384E                              % TFORM
 & 0.0                              % TLMIN
 & \sc tbd                              % TLMAX
 & 1                              % TDBIN
 & NaN                              % TNULL
 & Optional; Systematic uncertainty on count vector column.
  \\\hline                    % comment
%
\sc areascl                                % TTYPE
 &                               % TUNIT
 & 1E                               % TFORM
 & \sc 0.0                              % TLMIN
 & \sc n/a                              % TLMAX
 & \sc n/a                              % TDBIN
 & \sc NaN                              % TNULL
 & Optional; Area scaling factor, if {\sc ancrfile} needs a
 correction. If not present as a column, then the header will have
 {\tt AREASCL=1.0}
\\\hline
%
\end{tabular}
}   % close \small
\caption[Spectrum FITS Column Definitions: ]
{\it Spectrum FITS probably-unused data file binary table contents for
  extension ``SPECTRUM'' (one entry per spectrum). ``N/A'' means ``Not
  Applicable''.  The ``TNULL'' value of ``NaN'' stands for the IEEE
  ``Not A Number'' (which is not actually encoded into the header, but
  is implicit in the FITS convention). These are the columns defined
  by the OGIP Type II specification, but which are unlikely to be
  needed for AXAF grating spectra.}
\label{tab:specunused}
\end{center}
\end{table}%

\paragraph{Additional descriptions of table columns:}

\begin{description}
\item [\sc spec\_num]
  Required. Spectrum number.    
%
\item[\sc rowid]
  Optional; Arbitrary string identifier
%
\item[\sc  tg\_m]
  Required; diffraction order ($m$)
%
\item[\sc  tg\_part]
  Required; Spectral component (HEG, MEG, LEG, \ldots) 
%
\item[\sc  tg\_srcid]
  Required; source ID.  If the Level 1.5 file has been split by
  source, then this will be a constant for the Level 2 file, and it
  will become a header keyword ({\tt TG\_SRCID $= n$}).
%
\item[\sc ancrfile] Required; Ancillary response file name (ARF).
  This is the output of the exposure map calculation.  The file
  referred to will be an analog of this file in that each row here
  will have a corresponding row in the spectral response file.
             
%
\item[\sc respfile]
  Required.  Redistribution file name (RMF).  This is a
 redistribution from wavelength to position, and may contain one or
 more orders, and be valid for one or more sources.
             
%
\item[\sc backfile]
  Optional; background file.  Mutually exclusive with the {\sc
 Background} column. 
             
%
\item[\sc channel]
  Required; Vector of spectral ``channel'' numbers.                       
%
\item[\sc counts]
  Required; Counts array (a spectrum).  
                      
%
\item[\sc stat\_err]
  Optional; statistical uncertainty (``error'') on count column.  If
 the keyword {\sc poisserr} exists and has the value {\tt T}, then
 this column need not be present.  (Note that this condition applies to
 all rows.)
                      
%
\item[\sc quality]
  Optional; Quality flag.  The interpretation is as follows:
  \begin{description}
  \item[$0$:] Good; 
  \item[$1$:] bad -- never use; 
  \item[$2$:] dubious, recommend ignoring; 
  \item[$5$:]  user-specified as bad; 
  \item[Other values:]  spare.
  \end{description}
  If all values are $0$, then this should be promoted to a header
  keyword ({\tt QUALITY=0}) and the column deleted (note: this must be
  true for {\em all} rows).
             
%
\item[\sc grouping]
  Optional. Grouping vector.  If the data are un-grouped, then a
 header keyword is set ({\tt GROUPING = 0}) and the column is not
 present.  Otherwise, the interpretation is: 
 \begin{description}
 \item[$+1$:  ] channel starts a new group; 
\item[  $-1$:] channel is part of a continuing group; 
\item[  $0$: ] grouping is undefined. 
 \end{description}
(Note that if {\em any} row is grouped, then all rows must
 have the grouping vector present.)
             
%
\item[\sc background]
  Optional; background count vector. Mutually exclusive with the {\sc
 backfile} column.
                     
%
\item[\sc binlo]
   Required; Bin boundary, low coordinate.  By default, the bin units
   are \AA ngstroms.  Custom analysis may produce other units.
%
\item[\sc binhi]
  Required; Bin boundary, high coordinate.  Default units are \AA
  ngstroms.  Custom analysis may produce other units, but the units of
  {\sc binhi} and {\sc binlo} must be the same.
%
\item[\sc flux]
  Optional; Flux;  Default units are $\mathrm{photons\, cm^{-2}\,
  s^{-1}\, \AA^{-1}}$, but custom analysis may specify other units.
  Flux is determined by dividing the count-rate by the effective
  area. 
%
\item[\sc flux\_err]
  Optional. Uncertainty on flux. Only present if the {\sc flux}
 column is defined.
             
%
\item[\sc backscal]
  Optional; background scale factor
%
\item[\sc corrfile]
  Optional; ``correction'' file 
%
\item[\sc  corrscal]
  Optional; ``Correction'' scale factor
%
\item[\sc sys\_err]
  Optional; Systematic uncertainty on count vector column.  If
 present, these values may get added in quadrature to the statistical
 errors by processing software (such as {\sc Xspec}).
%
\item[\sc areascl] 
  This is an optional area-scaling factor.  It is most likely a
  constant and equal to 1.0, and so should be a header keyword (if
  present at all).  It is only for {\sc Xspec} compatibility.
\end{description}
%


%
\subsection{Keywords Describing Coordinate Systems}

All columns either need no coordinate system, or are already in
physical units.  There are no {\tt TCRPX$n$, TCRVL$n$}, etc., keywords
required.

%\begin{table}[h]
%\begin{center}
%\begin{tabular}{|l|}\hline
%%
%\verb@    TBD                         /                             @\\
%%
%\end{tabular}
%\caption[Special Keywords for Coordinates]{\em Special Keywords for TG
%  Columns with coordinate systems.} 
%\label{tab:coordkeywords}
%\end{center}
%\end{table}
%

\subsection{Keywords Describing Calibration Data}

Resolution of HETGS (HETG + ACIS-S) photons into diffraction orders
requires application of the calibration from wavelength to
pulse-height (PI, for Pulse-Invariant signal), and information on the
distribution of the response.  To do this, a special table is read,
which was in turn generated from the CCD response matrices (RMFs), for
a given fractional enclosed energy.  Subsequent processing will
require knowledge of this filter, so keywords are stored in the event
extension header, as defined in Table~\ref{tab:rmfkeys}.
%
\begin{table}[h]
\begin{center}
\begin{tabular}{|l|}\hline
\verb@COMMENT Order-sorting lookup tables: @\\
\verb@COMMENT   Tables of PI_min and PI_max vs E used for order-sorting, @\\ 
\verb@COMMENT   constructed for a specific fractional enclosed probability@\\
\verb@COMMENT Reference ICD for file definition is: TBD.@\\
\verb@COMMENT @\\
\verb@ACISDPIF='acis_fi_95_V0.0.fits'     /delta-PI vs energy table, FI CCD@\\
\verb@ACISDPIB='acis_bi_95_V0.0.fits'     /delta-PI vs energy table, BI CCD@\\\hline
%
\end{tabular}
\caption[Calibration Keywords]
  {\it Special Keywords describing calibration files.} 
\label{tab:rmfkeys}
\end{center}
\end{table}
%
\Remark{TBD: Need reference ICD for order sorting table.}



%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%\clearpage
%
\subsection{Grating Spectral Region Definitions}
\label{pg:regionext}\label{sec:regionext}
% ({\tt REGION BINTABLE} extension)}

During Level 1.5 processing, for each ObI, a regional mask is created
for each observation, as defined by the zero-order sky coordinates
output from source detection and width and angle parameters.  The
source regions are designed to be of generous dimensions, such that
the L1.5 product is a superset of photons likely to be selected for
analysis or Level 2 processing, thus avoiding re-running the L1.5
pipeline for alternate selection criteria.  It is defined in sky
$(X,Y)$ coordinates (typically a right-ascension and declination
tangent-plane system) and is used to filter the events for
transformation to grating diffraction coordinates.

During Level 2 processing, additional filtering may be applied to
sub-select within the Level 1.5 region, but more naturally in grating
coordinates, in which the zero-order is at the origin.

The generic definition of an ASC FITS region is given in the ``FITS
REGION Binary Table Design'' (Applicable
Document~\ref{appdoc:regfiles}).  The region HDU will be a single {\tt
  REGION} auxiliary extension, whose header is comprised of these
components: 
%
\begin{itemize}
\item mandatory {\tt REGION}-content header,
\item table coordinate system and ranges, 
\item short configuration control, 
\item short timing, and
\item short observation information.
\end{itemize}
%
The components which differ substantially from the event file's other
extensions (events, GTI) are the mandatory {\tt REGION} keywords, and
the table coordinate system.  A region specification is in general
specific to the ObI.

The {\tt REGION} definition for Level 1.5 spectral mask are comprised
of parts described by a circle for zero-order and rotated boxes
for diffracted orders.  There are generally multiple components for
each spectrum and possibly multiple sources per observation.  Level 2
processing may apply additional filtering within the Level 1.5
region.  A schematic of the HETG, LETG, and HESF regions in sky
coordinates is shown in Figure~\ref{fg:regions}.
%
\begin{figure}\label{fg:regions}
\cbstart
   \leavevmode{\scalebox{0.85}{\includegraphics{HETGS_parts.eps}}}
   \leavevmode{\scalebox{0.85}{\includegraphics{LETGS_parts.eps}}}
\cbend

   \caption[HETG/LETG regions]{\it This is a schematic representation of
   the grating region showing the different parts of the spectrum.
   On the top is the HETG specification, and on the bottom, LETG.  For
   the LETG, the parts, 4--7 are optional, only being required if the
   HESF is in the beam.  Scales are arbitrary.  There has been a small
   rotation applied, to emphasize the fact that in sky coordinates,
   the spectrum can have any orientation.  In Level 2 processing,
   region parts are obtained from a Level 1.5 event file column, and
   carried into the Level 2 product. Within each part, Level 1.5
   processing assigns dispersion and cross-dispersion coordinates.}
 \end{figure}
%
%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%% OBSOLETE! dph 980505
%%%
%\Remark{UPDATE! need $tg\_r, tg\_d$ region specification.}
%\begin{table}[h]
%\begin{center}
%\begin{tabular}{|l|}\hline
%  \verb@EXTNAME = 'REGION  '           / Region specification table@\\
%  \verb@CONTENT = 'REGION  '@\\
%  \verb@HDUCLASS= 'ASC     '@\\
%  \verb@HDUCLAS1= 'REGION  '@\\
%  \verb@HDUCLAS2= 'STANDARD'@\\
%%
%  \verb@MTYPE1  = 'pos     '@\\
%  \verb@MFORM1  = 'X,Y     '@\\\hline
%%
%  \verb@TCTYP2  = 'RA---TAN'           / sky X WCS@\\
%  \verb@TCRVL2  =                0.0   / Nominal angle@ \\
%  \verb@TCRPX2  =            16384.5   / Reference pixel@ \\
%  \verb@TCDLT2  = 1.59265544165e-5     / [degrees/pixel]@\\
%  \verb@TDBIN2  = 10                   / default [degrees/bin]@\\
%  \verb@TCUNI2  = 'deg'                / Unit of X@\\\hline
%%
%  \verb@TCTYP3  = 'DEC--TAN '          / Sky Y WCS@\\
%  \verb@TCRVL3  =                0.0   / Nominal angle@ \\
%  \verb@TCRPX3  =            16384.5   / Reference pixel@ \\
%  \verb@TCDLT3  = 1.59265544165e-5     / [degrees/pixel]@\\
%  \verb@TDBIN3  = 10                   / default [degrees/bin]@\\
%  \verb@TCUNI3  = 'deg'                / Unit of Y@\\\hline
%%
%  \verb@TCTYP4  = 'TBS      '          / Sky XY WCS - for a radius value@\\
%  \verb@TCDLT4  = 1.59265544165e-5     / [degrees/pixel]@\\
%  \verb@TDBIN4  = 10                   / default [degrees/bin]@\\
%  \verb@TCUNI4  = 'deg'                / Unit of radius@\\\hline
%%
%\end{tabular}
%\end{center}
%\caption[Region keywords]
%{\em Special Keywords for grating {\tt REGION} FITS File.  region
%  coordinates are specified in terms of sky $(X,Y)$, so that
%  coordinate system must be specified.}
%\label{tab:ltfkeywords}
%\end{table}
%%
%\Remark{Radius coord keywords TBR.  }
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%
%
\begin{table}[h]
\begin{center}
{\small
\begin{tabular}{|c|c|c|c|c|p{1.75in}|}\hline
 & & & & & \\
\sc ttype
 & \sc tunit
 & \sc tform 
 & \sc tlmin
 & \sc tlmax
 & \multicolumn{1}{|c|}{Comment} \\
 & & & & & \\\hline
%
 {\tt SHAPE}
 & -
 & 16A
 & -
 & -
 & Shape of region: must be {\tt BOX} in this case.\\\hline
%
 \tt TG\_LAM
 & angstrom
 & $1E$
 & 0
 & 400.
 & Dispersion coordinate vector for {\tt SHAPE}. 
   Note that this {\em could} be any other coordinate in the
 dispersion direction, such as {\tt TG\_R} or {\tt TG\_MLAM}, but {\tt
 tg\_lam} is the default. \\
\hline
%
 {\tt TG\_D}
 & deg
 & $1E$
 & -2.
 & 2.
 & Cross-dispersion coordinate vector for {\tt SHAPE}.\\\hline
%
{\tt  R} 
 & N/A
 & $2E$
 & 0
 & 2
 & radius vector for {\tt SHAPE}. The interpretation of coordinates
 and units depends upon the {\tt SHAPE}. \\\hline
%
{\tt  ROTANG} 
 & deg
 & $1E$
 & 0
 & 360
 & Rotation angle for SHAPE, in degrees (which is 0.0 for this
 application).\\\hline 
%%
{\tt  COMPONENT}
 & -
 & I
 & 0
 & 7
 & Component number that {\tt SHAPE} belongs to (default is 1). 
   This is equivalent to {\tt TG\_PART}. \\\hline
%
{\tt  INCLUDE} 
 & -
 & I
 & 0
 & 1
 & Inclusion (1; default) or exclusion (0). \\\hline
%
{\tt  TG\_SRCID}
 & -
 & I
 & 1
 & TBD
 & Source identification number. If constant (files split by source),
 then this becomes a header keyword: {\tt TG\_SRCID $= n$}.
\\\hline
%
{\tt  TG\_M}
 & -
 & I
 & 1
 & 62
 & Optional diffraction order. Different orders could be extracted
 from different regions. \\\hline
%
%
{\tt  SPEC\_NUM}
 & -
 & 1I
 & 1
 & N/A
 & Required; spectrum number, which points the the row in the SPECTRUM
 extension to which the region on this row applies. \\\hline
%
%
{\tt  ROWID}
 & -
 & 64A
 & N/A
 & N/A
 & Required; this indicates whether the region on this row is for the source or a
 background region of spectrum {\tt SPEC\_NUM}. Valid values are {\tt
   SOURCE}, {\tt BACKGROUND\_UP}, and {\tt BACKGROUND\_DOWN}.
 \\\hline
%
\end{tabular}
}
\caption[Region file column contents]
{\it FITS grating region file binary table contents.}
\label{tab:ltfbintable}
\end{center}
\end{table}
The interpretation of the {\tt COMPONENT} value is shown in
Table~\ref{tab:components}. 
%
%
\begin{table}[h]
\begin{center}
\begin{tabular}{|cc|p{2.75in}|}\hline
%
GRATING &COMPONENT & Meaning \\\hline
%
HETG & 0& Zero-order (optional)\\
     & 1& {\sc heg} arm\\
     & 2& {\sc meg} arm\\\hline
LETG & 0& Zero-order (optional)\\
     & 3& {\sc leg} arm\\
     & 4& {\sc hesf} (Drake Flat) region 1 (optional)\\
     & 5& {\sc hesf} (Drake Flat) region 2 (optional)\\
     & 6& {\sc hesf} (Drake Flat) region 3 (optional)\\
     & 7& {\sc hesf} (Drake Flat) region 4 (optional)\\\hline
%
\end{tabular}
%
\caption[Region component interpretation]
{\it Region table component interpretation. Grating is either HETG or
  LETG. By default, all diffracted components present are binned.}
\label{tab:components}
%
\end{center}
\end{table}
%
%
The interpretation of the coordinate vectors for grating region
shapes, as given in the FITS region specification (Applicable
Document~\ref{appdoc:regfiles}) is:
%
\begin{description}
  
\item[{\tt BOX: }] First element of each $X$ and $Y$ vectors
  specify the center of a rectangle.  The first element of {\tt
    ROTANG} specifies counter-clockwise rotation of the rectangle with
  respect to $X$ and $Y$ axes. The center of the rotation is the
  center of the rectangle (given by $X,Y$).  ROTANG is always zero for
  this specification.
  
  Other elements (if present) of $X,Y$ are undefined.  The first two
  elements of $R$ specify the full-widths of $X$ and $Y$,
  respectively. 

\end{description}
%

The diffraction coordinates must be tied to the region generic ``$X$''
and ``$Y$'' tokens so that the  {\tt SHAPE} and {\tt R} columns can be
properly interpreted.  The mechanism for this is via ``Data Model''
keywords:
%
\begin{center}
\begin{tabular}{l}
%%
  \verb@MFORMn  = 'TG_LAM, TG_D'       / wavelength vs cross-disp angle@\\
  \verb@MTYPEn  = 'wav-pos '           / Wavelength-vs-position coords@\\
%%
\end{tabular}
\end{center}
%
where $n$ is the $n^\mathrm{th}$ coordinate pair (and here would be
$1$, since there are no others).  These keywords specify that {\tt
  TG\_LAM} is to be treated as  $X$ and {\tt TG\_D} is to be treated
as $Y$, according to the region file specification.
%
\Remark{{\tt MTYPE} TBD.}
%
There are other coordinates which could be used for the dispersion,
such as {\tt TG\_R} and {\tt TG\_MLAM}. As an example with the former,
the header coordinate keywords would become:
%
\begin{center}
\begin{tabular}{l}
%%
  \verb@MFORMn  = 'TG_R, TG_D'       / wavelength vs cross-disp angle@\\
  \verb@MTYPEn  = 'pos '           / Wavelength-vs-position coords@\\
%%
\end{tabular}
\end{center}
%

   

\subsection{Volume, Size, and Frequency Estimates}

TBS.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% J. Houck file
                                %
                                %
                                %
                                %
                                %

\clearpage
\section{Spectral Measurements Files}

\input{SpecMeas}


\clearpage
\section{Ancillary Response Files (*\_arf.fits)}

\dataprod ASC Data Product::Grating Spectral Response (``ARF'')
Instrument(s)::HETG, LETG
Level::2
Scientist/SDS::D.~Huenemoerder
Filetype::ARF Type II
Created by tool::tgarfcalc
Used by tool(s)::various
Sample file::TBS
\par

The Ancillary Response File (ARF) is the effective area function, or
spectral response.  For AXAF grating data, however, we have many
responses: one for each order.  In addition, the zero-order placement
and the aspect dither conspire with the detector geometry to place
gaps and edges at different parts of the spectrum for different
lengths of time.  Hence, the ARF is really an ``exposure map''.  The
file-structure will be very similar to the binned spectrum and carry
much of the same information: we define a ``Type II ARF'' to match the
Type II PHA file.  A major difference is that the wavelength grid may
be finer than the binned spectrum's grid.

\subsection{HDU Components}

The following table (Table~\ref{tab:arfhdu}) describes the file
structure by Header-Data Unit number, type, extension name, content,
and HDU classes.  An asterisk (*) denotes the principal HDU.
%
\begin{table}[h]
{\small
\noindent\begin{tabular}{|llccp{0.8in}p{1.5in}|}\hline
HDU
& Type
& {\sc extname}
& {\sc content}
& {\sc hduclass}
& Description
\\
\hline
%
1 
& {\sc null}
& {\sc n/a}
& \sc n/a
& \sc n/a
& 
\\
%
2 (*)
& {\sc bintable}
& {\sc response}
& {\sc specresp}
& {\sc asc}\newline 
  {\sc response}\newline 
  {\sc specresp}\newline 
  {\sc  type:ii}\newline 
  {\sc tg}
& Spectral response (ARF), vs order vs source, grid, and ancillary
information. 
\\
%
3
& \sc bintable
& \sc region
& \sc region
& \sc asc\newline region\newline tg
& Spectral-spatial region over which the spectral response was averaged.
\\
%
\hline
\end{tabular}\label{tab:arfhdu}
}   % close \small
\caption[Spectral Response File Components]{\it The Header-Data Unit
  structure of   the spectral respose FITS file.}
\end{table}
%

The structure of the HDUs, as specified by the ASC FITS Guide
(Document~\ref{appdoc:ascfits}), is
\begin{itemize}
\item Null Primary HDU:
  \begin{itemize}
  \item image mandatory
  \item null configuration control
  \item short timing
  \item short observation
  \end{itemize}
\item Principal table HDU:
  \begin{itemize}
  \item bintable mandatory
  \item table coordinates
  \item full configuration control
  \item full observation
  \item full timing
  \end{itemize}
\item Auxiliary table HDU:
  \begin{itemize}
  \item bintable mandatory
  \item table coordinates
  \item short configuration control
  \item short timing
  \item short observation
  \end{itemize}
\end{itemize}

\subsection{Column Specifications}

The contents of the FITS columns of the spectral respose extension are
given in the following tables (Table~\ref{tab:arfcontents}).  These
generally are a subset of the binned spectrum columns.

The length of the vector columns (specified by {\tt TFORM}$n$, such as
for ``BINLO'' or ``SPECRESP'') is given in the table as 16384.  This
is a {\em representative maximum length}! It could in principal be
longer or shorter.  For LETGS, for example, binning at a single
resolution element per bin will give about 6700 bins, and HETGS about
3400.  Analysis tools can specify arbitrary binning.  Pipelines will
default to 0.5-1.0 resolution-element bins for the data.  Custom
analysis may produce files only containing a few bins around lines of
interest, or even arrays discontinuous in wavelength to hold several
regions of interest.  The respose should in general have smaller bins
than the data.

The spectral response will be by default calculated in units of
$[\mathrm{cm^2\, counts\, photon^{-1}}]$ {\it vs.}\ $[\mathrm{\AA}]$
(note that $[\mathrm{counts\, photon^{-1}}]$ is a unitless quantity).
Custom analysis may convert wavelengths to energy units, or analysis
could produce flux in units of $\mathrm{ergs}$ instead of photons, and
a response in commensurate units.  These are all permitted in a valid
response file as long as consistency is maintained within the grid
columns ({\sc Binlo, Binhi}) and units column.
%
\begin{table}[htb]
\begin{center}
{\small
\begin{tabular}{|c|p{0.65in}|c|c|p{0.5in}|p{0.425in}|c|p{1.65in}|}
\hline
 & & & & & & &\\
\sc ttype
 & \sc tunit
 & \sc tform 
 & \sc tlmin
 & \sc tlmax
 & \sc tdbin
 & \sc tnull
 & \multicolumn{1}{|c|}{Comments}\\
 & & & & & & &\\\hline
%
\sc resp\_num                          % TTYPE
 &                             % TUNIT    
 & 1I                                % TFORM 
 & 1                         % TLMIN
 & 16384                              % TLMAX
 & 1                              % TDBIN
 & 0                      % TNULL
 & Required. Response index.\\
\hline                 % comment
%
\sc rowid                             % TTYPE
 &                                % TUNIT
 & 64A                             % TFORM
 & \sc n/a                            % TLMIN
 & \sc n/a                            % TLMAX
 & \sc n/a                            % TDBIN
 & \sc none                             % TNULL
 & Optional; Arbitrary string identifier  \\\hline                     % comment
%
\sc  tg\_m                            % TTYPE  
 &                                % TUNIT  
 & 1I                             % TFORM  
 & $-62$                          % TLMIN  
 & $62$                           % TLMAX  
 & \sc n/a                            % TDBIN  
 & 99                             % TNULL  
 & Required; diffraction order ($m$) \\\hline           % comment
%
\sc  tg\_part                         % TTYPE  
 &                                % TUNIT  
 & 1I                             % TFORM  
 & 0                              % TLMIN  
 & 99                             % TLMAX  
 & \sc n/a                            % TDBIN  
 & \sc n/a                            % TNULL  
 & Required; Spectral component (HEG, MEG, LEG, \ldots) \\\hline% comments
%
\sc  tg\_srcid                        % TTYPE  
 &                                % TUNIT  
 & 1I                             % TFORM  
 & 1                              % TLMIN  
 & \sc tbd                             % TLMAX  
 & \sc n/a                            % TDBIN  
 & 0                              % TNULL  
 & Required; source ID of source in spectrum file to which this
 response applies.  If constant (file split on source), then this
 is promoted to a keyword.  If null-valued, then the response is for a region
 for which no source spectrum has been extracted.\\
\hline             % comment
%
\sc channel                                % TTYPE
 &                               % TUNIT
 & 16384I
                                % TFORM
 & 1                              % TLMIN
 & 16384                              % TLMAX
 & 1                              % TDBIN
 & 0                              % TNULL
 & Required; Vector of spectral ``channel'' numbers.   \\\hline                    % comment
%
\sc specresp                                % TTYPE
 & cm**2                              % TUNIT
 & 16384I                              % TFORM
 & 0                              % TLMIN
 & 16384                              % TLMAX
 & 1                              % TDBIN
 & \sc tbd                              % TNULL
 & Required; The spectral response array.  
  \\\hline                    % comment
%
\sc stat\_err                                % TTYPE
 & cm**2                               % TUNIT
 & 16384I                              % TFORM
 & 0                              % TLMIN
 & 16384                              % TLMAX
 & 1                              % TDBIN
 & \sc tbd                              % TNULL
 & Optional; statistical uncertainty (``error'') on the response array.
  \\\hline                    % comment
%
\sc binlo                                % TTYPE
 &   angstrom                            % TUNIT
 &   16384E                            % TFORM
 &  0.0                             % TLMIN
 &  400.0                             % TLMAX
 &  1.0E-04 (TBR)                             % TDBIN
 &  NaN                             % TNULL
 &  Required; Bin boundary, low coordinate. \\\hline                    % comment
%
\sc binhi                                % TTYPE
 & angstrom                              % TUNIT
 & 16384E                              % TFORM
 & 0.0                              % TLMIN
 & 400.0                              % TLMAX
 & 1.0E-04 (TBR)                              % TDBIN
 & NaN                              % TNULL
 & Required; Bin boundary, high coordinate  \\\hline                    % comment
%
%
\end{tabular}
}   % close \small
\caption[Spectral Response FITS Column Definitions]
{\it FITS spectral respose data file binary table
  contents for extension ``SPECRESP'' (one entry per spectrum).
  ``N/A'' means ``Not Applicable''.  The ``TNULL'' value of ``NaN''
  stands for the IEEE ``Not A Number'' (which is not actually encoded
  into the header, but is implicit in the FITS convention).}
\label{tab:arfcontents}
\end{center}
\end{table}%

                                %%%%%%%%%%%%%%%%%%%%%%
                                %
                                %
\subsection{Special Header Keywords}

Knowledge of the generating parameters for the spectral response are
crucial to its application to a counts spectrum.  The response is
determined by the calibration data, by the zero-order position, by the
good-time-intervals and aspect history, and by filtering conditions.
When Level 1.5 events are resolved to orders and binned, both spatial
and PHA regions are clipped, and both affect the effective area.  All
these must be accounted for in generating the response and stored in
header keywords.  These keywords ({\it cf.} Table~\ref{tab:rmfkeys} on
page~\pageref{tab:rmfkeys})
are: 
%
\begin{description}
\item[ACISDPIF: ] This is the name of the file used to define the
  PI-clipping region used in order-resolution for ACIS
  front-illuminated (FI) observations. The table gives the upper and
  lower bounds on PI vs energy for some fractionally enclosed
  probability.  (Use of one table for FI assumes that all FI CCD's
  have the same PI response.)
\item[ACISDPIB: ] This is the name of the file used to define the
  PI-clipping region used in order-resolution for ACIS
  back-illuminated (BI) observations. The table gives the upper and
  lower bounds on PI vs energy for some fractionally enclosed
  probability.  (Use of one table for FI assumes that all FI CCD's
  have the same PI response.)
\item[ASP\_FILE] Filename of aspect solution (or offsets) file used to
  generate the response.
\item[GTI\_FILE: ] Reference to the file used for Good Time
  Intervals. 
%
\end{description}

%%

\subsection{Region Extension}

Generally, the response is averaged over the same region for which a
particular spectrum has been binned.  In this case, the region
extension will match that in the binned spectrum file.  It is
possible, however, to create the response for an assumed position,
independent of any observed source.  In this case, the {\tt TG\_SRCID}
will have a null value, and we need to specify the (virtual)
zero-order reference point.  Other crucial piece of reference
information are the aspect solution and time-filter applied. We give
these with the header keywords:
\begin{center}
\begin{tabular}{l}
%%
  \verb@RA_ZO   = xxx.xxxxx    / Assumed zero-order right-ascenion (degrees)@\\
  \verb@DEC_ZO  = syy.yyyyy    / Assumed zero-order declination (degrees)@\\
  \verb@ASP_FILE= 'filename'   / Aspect solution (or offsets) filename @\\
  \verb@GTI_FILE= 'filename'   / Aspect solution (or offsets) filename @\\
%%
\end{tabular}
\end{center}
%
The region extension is otherwise as given in Section~\ref{pg:regionext}.

%

\subsection{Volume, Size, and Frequency Estimates}

TBD.

\subsection{Example Files}

TBS.


                                %
                                %
                                %
                                %
                                %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 
                                %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 
                                %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 
\clearpage
\section{Redistribution Matrix File}
TBS

\section{Summary Information Files}

TBS by USG


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

\appendix
\section{Example Header: Spectral Histogram}
TBS.
%\input example_hdrs.tex

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\end{document}


