% Time-stamp: <98/05/05 11:38:55 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{article}
\usepackage[dvips]{graphics}

\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.3in
  \evensidemargin=1in
  \marginparwidth 2.0in                           %% adjust size of margin to
  \marginparsep 0.2in                             %  give room for remarks
  }

\newcommand{\Remark}[1]{\marginpar
   {\fbox{\parbox{1.7in}{\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 %%%%%%%%%%--------------


%%%
%%% 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---xx mon 1998 % 
%Revision 1.2---xx mon 1998 % 
%Revision 1.3---xx mon 1998 % 
%Revision 1.4---xx mon 1998 % 
}}

\hyphenation{pipe-line}
\hyphenation{pipe-lines}

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

\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}{File: dph/h1/ASC/TG/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 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, John Houck & Date   \\
    & Grating Scientists, ASC Science Data Systems & \\[0.15in]
%
    Concurred: & \rule{3.5in}{0.01in} & \rule{0.75in}{0.01in} \\
    & Michael Juda & Date   \\
    & Grating Scientist, ASC Dev. \& Ops. Group & \\[0.15in]
%
    Concurred: & \rule{3.5in}{0.01in} & \rule{0.75in}{0.01in} \\
    & Panagoula Zografou & Date   \\
    & ASC Data Systems Group Leader, ASC Archives & \\[0.15in]
%
    Concurred: & \rule{3.5in}{0.01in} & \rule{0.75in}{0.01in} \\
    & F.~Seward & Date   \\
    & Group Leader, ASC User Support  & \\[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} \\
    & Fred Seibel & Date   \\
    & Manager, ASC Data Systems & \\[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
%
%
 &                           % 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 980404: Only included spectrum file, exposure map (ARF)
  extension, and region extension.

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


\end{enumerate}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%




%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%
%%% 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}).
%
\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.}


\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


%\clearpage
%
\subsection{Functional Description}

\subsubsection{Data Content Summary}

TG data sets generated by the Level~2 processing pipeline shall
consist of data files conforming to the FITS format (Applicable
Document~\ref{appdoc:fitsdef}) and further conforming to HEASARC
standards (Applicable Document~\ref{appdoc:fitsstd}) and the ASC
conventions (Applicable Document~\ref{appdoc:ascfits}). 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.

\subsubsection{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.

\subsubsection{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}

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.

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.


\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{Detailed Interface Specifications}

\subsection{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}.

\begin{table}\label{tab:l2prods}
\begin{tabular}{|lp{2in}p{2in}|}\hline
%
{\tt *}\_hst2.fits&
Binned spectra ({\bf h}i{\bf s}{\bf t}ogram) file&
required\\
%
{\tt *}\_arf.fits&
spectral responses&
Optional.  May be included in binned spectrum file as a vector column.\\
%
{\tt *}\_rmf.fits&
Spectral redistribution file&
optional\\
%
{\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.\\
%
{\tt *}\_sum.ps&
Postscript summary&
required\\
%
{\tt *}\_sum.html&
Hypertext summary&
TBR\\
%
{\tt *}\_TBD.gif&
GIF summary images&
TBR\\ \hline
\end{tabular}
\caption[L2 product list]{\em These are required and optional grating
  Level 2 product files. The ``*'' designates an appropriate label
  sub-string as described in the text.}
\end{table}

\subsection{Overview of Components}

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).  Since it is so source-specific for AXAF grating
  observations, we will by default include it as a column in the
  spectrum file.

  \Note{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-disperssion 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
  are produced for quick-look inspection and assessment by the
  end-user, and also by ASC validation and verification processing.
  Products are tentatively: (all TBR)
  \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.
%
\Remark{TBD by USG: summary products}
%
\end{description}
%

\subsection{Spectral Histogram Files (*\_hst2.fits)}
\Remark{TBR: What's the right ``content'' string?}

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.
%
\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}
%

%
\subsubsection{Column Specifications}

The contents of the FITS columns of the binned spectrum extension are
given in Table~\ref{tab:speccontents}.  These generally conform to the
OGIP Type II PHA definition, with some additions appropriate for AXAF
grating spectra.  Some columns are optional. The rest are mandatory
for a Level 2 TG spectral file.  

The length of the vector columns (specified by {\tt TFORM}$n$, such as
for ``COUNT'' 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.

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 header; it is implicit in the FITS standard.

\subsubsection{Un-specified 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.


\clearpage

\begin{table}[ht]\label{pg:NULLi}
\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|}{Comment}\\
 & & & & & & &\\\hline
%
 SPEC\_NUM                          % TTYPE
 &                             % TUNIT    
 & 1I                                % TFORM 
 & 1                         % TLMIN
 & 16384                              % TLMAX
 & 1                              % TDBIN
 & 0                      % TNULL
 & spectrum number    \\\hline                 % comment
%
ROWID                             % TTYPE
 &                                % TUNIT
 & 8A                             % TFORM
 & N/A                            % TLMIN
 & N/A                            % TLMAX
 & N/A                            % TDBIN
 & `'                             % TNULL
 & Arbitrary string identifier  \\\hline                     % comment
%
 TG\_M                            % TTYPE  
 &                                % TUNIT  
 & 1I                             % TFORM  
 & $-62$                          % TLMIN  
 & $62$                           % TLMAX  
 & N/A                            % TDBIN  
 & 99                             % TNULL  
 & order ($m$) \\\hline           % comment
%
 TG\_PART                         % TTYPE  
 &                                % TUNIT  
 & 1I                             % TFORM  
 & 0                              % TLMIN  
 & 99                             % TLMAX  
 & N/A                            % TDBIN  
 & N/A                            % TNULL  
 & component (HEG, MEG, LEG, \ldots) \\\hline% comments
%
 TG\_SRCID                        % TTYPE  
 &                                % TUNIT  
 & 1I                             % TFORM  
 & 1                              % TLMIN  
 & TBD                             % TLMAX  
 & N/A                            % TDBIN  
 & 0                              % TNULL  
 & source ID \\\hline             % comment
%
ANCRFILE                                % TTYPE
 &                               % TUNIT
 & 64A                               % TFORM
 & N/A                              % TLMIN
 & N/A                              % TLMAX
 & N/A                              % TDBIN
 & `'                              % TNULL
 & Ancillary response file name (ARF).  Optional; by default, the
 response itself is included as a column.  \\\hline                    % comment
%
RESPFILE                                % TTYPE
 &                               % TUNIT
 & 64A                               % TFORM
 & N/A                              % TLMIN
 & N/A                              % TLMAX
 & N/A                              % TDBIN
 & `'                              % TNULL
 & Redistribution file name (RMF)  \\\hline                    % comment
%
BACKFILE                                % TTYPE
 &                               % TUNIT
 & 64A                              % TFORM
 & N/A                              % TLMIN
 & N/A                              % TLMAX
 & N/A                              % TDBIN
 & `'                              % TNULL
 & background file; Optional  \\\hline                    % comment
%
BACKSCAL                                % TTYPE
 &                               % TUNIT
 & 1E                               % TFORM
 & TBD                              % TLMIN
 & TBD                              % TLMAX
 & N/A                              % TDBIN
 & NaN                              % TNULL
 & background scale factor (optional)  \\\hline                    % comment
%
CORRFILE                                % TTYPE
 &                               % TUNIT
 & 64A                              % TFORM
 & N/A                              % TLMIN
 & N/A                              % TLMAX
 & N/A                              % TDBIN
 & `'                              % TNULL
 & ``correction'' file (optional)  \\\hline                    % comment
%
 CORRSCAL                               % TTYPE
 &                               % TUNIT
 & 1E                              % TFORM
 & TBD                              % TLMIN
 & TBD                              % TLMAX
 & N/A                              % TDBIN
 & NaN                              % TNULL
 & ``Correction'' scale factor (optional)  \\\hline                    % comment
%
CHANNEL                                % TTYPE
 &                               % TUNIT
 & 16384I
                                % TFORM
 & 1                              % TLMIN
 & 16384                              % TLMAX
 & 1                              % TDBIN
 & 0                              % TNULL
 & vector of spectral ``channel'' numbers   \\\hline                    % comment
%
COUNT                                % TTYPE
 & count                              % TUNIT
 & 16384I                              % TFORM
 & 0                              % TLMIN
 & 16384                              % TLMAX
 & 1                              % TDBIN
 & TBD                              % TNULL
 & count vector (a spectrum)  \\\hline                    % comment
%
STAT\_ERR                                % TTYPE
 & count                               % TUNIT
 & 16384I                              % TFORM
 & 0                              % TLMIN
 & 16384                              % TLMAX
 & 1                              % TDBIN
 & TBD                              % TNULL
 & statistical uncertainty (``error'') on count column  \\\hline                    % comment
%
SYS\_ERR                                % TTYPE
 & count                              % TUNIT
 & 16384E                              % TFORM
 & 0.0                              % TLMIN
 & TBD                              % TLMAX
 & 1                              % TDBIN
 & NaN                              % TNULL
 & Systematic uncertainty on count vector column.  \\\hline                    % comment
%
QUAL                                % TTYPE
 &                               % TUNIT
 & 16384I                              % TFORM
 & 0                              % TLMIN
 & 16384                              % TLMAX
 & N/A                              % TDBIN
 & TBD                              % TNULL
 & quality flag  \\\hline                    % comment
%
GRPG                                % TTYPE
 &                               % TUNIT
 & 16384I                              % TFORM
 & -1                              % TLMIN
 & 1                              % TLMAX
 & N/A                              % TDBIN
 & TBD                              % TNULL
 & grouping vector  \\\hline                    % comment
%
BACKGND                                % TTYPE
 & count                              % TUNIT
 & 16384E                              % TFORM
 & 0.0                              % TLMIN
 & TBD                              % TLMAX
 & 1                              % TDBIN
 & NaN                              % TNULL
 & background count vector  \\\hline                    % comment
%
BINLO                                % TTYPE
 &   angstrom                            % TUNIT
 &   16384E                            % TFORM
 &  0.0                             % TLMIN
 &  400.0                             % TLMAX
 &  1.0E-04 (TBR)                             % TDBIN
 &  NaN                             % TNULL
 &  Bin boundary, low coordinate \\\hline                    % comment
%
BINHI                                % TTYPE
 & angstrom                              % TUNIT
 & 16384E                              % TFORM
 & 0.0                              % TLMIN
 & 400.0                              % TLMAX
 & 1.0E-04 (TBR)                              % TDBIN
 & NaN                              % TNULL
 & Bin boundary, high coordinate  \\\hline                    % comment
%
ARF                                % TTYPE
 & s cm**2 \newline (TBR)                              % TUNIT
 &  16384E                             % TFORM
 &  0.0                             % TLMIN
 &  10000.                             % TLMAX
 &  N/A                             % TDBIN
 &  NaN                             % TNULL
 &  Effective area (TBR units: may normalize by EXPTIM) \\\hline                    % comment
%
FLUX                                % TTYPE
 & [photon or ergs] /s /cm**2 / [angstrom or kev]                              % TUNIT
 & 16384E                              % TFORM
 & 0.0                              % TLMIN
 & TBD                              % TLMAX
 & TBD                              % TDBIN
 & NaN                              % TNULL
 & Flux. Choice of ergs or photons per angstrom or keV.  \\\hline                    % comment
%
FLUX\_ERR                                % TTYPE
 & (same as FLUX)                              % TUNIT
 & 16384E                              % TFORM
 & 0.0                              % TLMIN
 & TBD                              % TLMAX
 & TBD                              % TDBIN
 & NaN                              % TNULL
 & Uncertainty on flux.  \\\hline                    % comment
%
\end{tabular}
}   % close \small
\caption[Spectrum FITS column definitions]
{\em 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). The ``TNULL'' value
  of ``\ `'\ '' for strings represents the null-string.
}
\label{tab:speccontents}
\end{center}
\end{table}%
%
\clearpage
%

%
\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]
  {\em 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 ({\tt REGION BINTABLE}
extension)}\label{pg:regionext}


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. 

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.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%% 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
 & & & & & \\
 TTYPE
 & TUNIT
 & TFORM 
 & TLMIN
 & TLMAX
 & \multicolumn{1}{|c|}{Comment} \\
 & & & & & \\\hline
%
 {\tt SHAPE}
 & -
 & 16A
 & -
 & -
 & Shape of region: may be {\tt CIRCLE}, {\tt RECTANGLE}, {\tt
         ROTBOX}, or {\tt BOX}.\\\hline
%
 {\tt tg\_lam}
 & angstrom
 & $4E$
 & 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}. \\\hline
%
 {\tt TG\_D}
 & deg
 & $4E$
 & -2.
 & 2.
 & Cross-dispersion coordinate vector for {\tt SHAPE}.\\\hline
%
{\tt  R} 
 & N/A
 & $4E$
 & 0
 & 2
 & radius vector for {\tt SHAPE}. The interpretation of coordinates
 and units depends upon the {\tt SHAPE}. \\\hline
%
{\tt  ROTANG} 
 & deg
 & $4E$
 & 0
 & 360
 & Rotation angle for SHAPE, in degrees.\\\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  SOURCE}
 & -
 & I
 & 1
 & TBD
 & Source identification number. \\\hline
%
{\tt  TG\_M}
 & -
 & I
 & 1
 & 62
 & Optional diffraction order. Different orders could be extracted
 from different regions. \\\hline
\end{tabular}
}
\caption[Region file column contents]
{\em 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.0in}|}\hline
%
GRATING &COMPONENT & Meaning \\\hline
%
HETG & 0& Zero-order (optional)\\
     & 1& HEG arm\\
     & 2& MEG arm\\\hline
LETG & 0& Zero-order (optional)\\
     & 3& LEG arm\\
     & 4& HESF (Drake Flat) region 1 (optional)\\
     & 5& HESF (Drake Flat) region 2 (optional)\\
     & 6& HESF (Drake Flat) region 3 (optional)\\
     & 7& HESF (Drake Flat) region 4 (optional)\\\hline
%
\end{tabular}
%
\caption[Region component interpretation]
{\em Region table component interpretation. Zero-order regions are
  optional.  Grating is either HETG or LETG. If Grating is LETG, then
  HESF parts are also optional. (Zero-order is generally not
  appropriate for binned spectral files.)}
\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 CIRCLE:  }] First element of $X$, $Y$, $R$ vectors
  specifies center and radius.

  \item[{\tt ROTBOX:  }] 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$).

  Other elements of $X,Y$ are undefined.  The first two elements of
  $R$ specify the full-widths of $X$ and $Y$, respectively.

\end{description}

For both grating types, component 0 is optional (e.g., if the zero-order
was not imaged onto the detector).  For the LETG, components 4--7 are
optional (e.g., the source was not imaged onto the HESF (Drake Flat)).

%


\subsection{Example: Full Region Extension Header}

\begin{figure}\label{fig:regions}
   \leavevmode{\scalebox{0.85}{\includegraphics{HETGS_parts.eps}}}
   \leavevmode{\scalebox{0.85}{\includegraphics{LETGS_parts.eps}}}

   \caption[HETG/LETG regions]{\em 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}
   

\Note{Insert a sample region header here.}

  


\clearpage

\subsection{Spectral Measurements Files}
TBS

\subsection{Redistribution Matrix File}
TBS

\subsection{Ancillary Response File}
TBS

\subsection{Summary Information Files}
TBS

\subsection{Volume, Size, and Frequency Estimates}

TBS.

\section{Example Files}
label{pg:samples}


\begin{verbatim}
TBS: HETG/ACIS-S 2 src FITS spectrum, region
     LETG/HRC_S 2 src
     LETG/HESF TBD.
\end{verbatim}


\clearpage
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Full Header: spectral histogram file}

\subsubsection{Primary Header}
\begin{verbatim}
COMMENT                        / Mandatory for HDU ------------------------- 
SIMPLE  =                    T / file does conform to FITS standard              
BITPIX  =                    8 / number of bits per data pixel                   
NAXIS   =                    2 / number of data axes                             
NAXIS1  =                    1 / length of data axis 1                           
NAXIS2  =                    1 / length of data axis 2                           
EXTEND  =                    T / FITS dataset may contain extensions             
COMMENT   FITS (Flexible Image Transport System) format defined in Astronomy and 
COMMENT   Astrophysics Supplement Series v44/p363, v44/p371, v73/p359, v73/p365. 
COMMENT   Contact the NASA Science Office of Standards and Technology for the    
COMMENT   FITS Definition document #100 and other FITS information.              

COMMENT                        / Configuration control------------------------- 
ORIGIN  = 'ASC     '                                                             
CREATOR = 'xxx     '           / - Version 0.0                                   
CHECKSUM= 'WIFDa9CCWGCCa9CC'   / encoded HDU checksum updated on 07/04/98        
DATASUM =                    0 / Data unit checksum written in ASCII             
COMMENT                                                                          

COMMENT                        / Time information block------------------------ 
DATE    = '1998-01-01T00:00:00'/ Date and time of file creation (UTC)           
DATE-OBS= '1998-01-01T00:00:00'/ TT, with clock correction if CLOCKAPP          
DATE-END= '1998-01-01T00:00:00'/ TT, with clock correction if CLOCKAPP          
TIMESYS = 'TT      '           / AXAF time will be TT (Terrestrial Time)         
CLOCKAPP=                    T / Clock correction applied (if false)             
TIMEZERO=                  0.0 / Clock correction (if not zero)                  
TIMEUNIT= 's       '           / time unit                                       
MJDREF  =                50814 / 1998-01-01T00:00:00 (TT) expressed in MJD (TT)  
TSTART  =                  0.0 / As in the "TIME" column: raw space craft clock; 
TSTOP   =                  0.0 /   add TIMEZERO and MJDREF for absolute TT       
COMMENT                                                                          

COMMENT                        / Observation information block----------------- 
OBS_ID  = 'xxxxxxxxxxxxxxx'    / Whatever the convention is ...                  
MISSION = 'AXAF    '           / Mission is AXAF                                 
TELESCOP= 'AXAF    '           / Telescope is AXAF                               
INSTRUME= 'ACIS    '           / HRC, ACIS, EPHIN, S/C subsystems                
PHAVERSN= '1992a   '           / OGIP memo number for file format                
END                                                                              
\end{verbatim}

\clearpage
\subsubsection{Spectrum Extension Header}
\begin{verbatim}
COMMENT                        / Mandatory for HDU ------------------------- 
XTENSION= 'BINTABLE'           / binary table extension                          
BITPIX  =                    8 / 8-bit bytes                                     
NAXIS   =                    2 / 2-dimensional binary table                      
NAXIS1  =               140280 / width of table in bytes                         
NAXIS2  =                    2 / number of rows in table                         
PCOUNT  =                    0 / size of special data area                       
GCOUNT  =                    1 / one data group (required keyword)               
TFIELDS =                   23 / number of fields in each row                    
TTYPE1  = 'SPEC_NUM'           / label for field   1                             
TFORM1  = 'I       '           / data format of field: 2-byte INTEGER            
TUNIT1  = '        '           / physical unit of field                          
TTYPE2  = 'ROWID   '           / label for field   2                             
TFORM2  = '8A      '           / data format of field: ASCII Character           
TUNIT2  = '        '           / physical unit of field                          
TTYPE3  = 'TG_SRCID'           / label for field   3                             
TFORM3  = 'I       '           / data format of field: 2-byte INTEGER            
TUNIT3  = '        '           / physical unit of field                          
TTYPE4  = 'TG_PART '           / label for field   4                             
TFORM4  = 'I       '           / data format of field: 2-byte INTEGER            
TUNIT4  = '        '           / physical unit of field                          
TTYPE5  = 'TG_M    '           / label for field   5                             
TFORM5  = 'I       '           / data format of field: 2-byte INTEGER            
TUNIT5  = '        '           / physical unit of field                          
TTYPE6  = 'ANCRFILE'           / label for field   6                             
TFORM6  = '64A     '           / data format of field: ASCII Character           
TUNIT6  = '        '           / physical unit of field                          
TTYPE7  = 'RESPFILE'           / label for field   7                             
TFORM7  = '64A     '           / data format of field: ASCII Character           
TUNIT7  = '        '           / physical unit of field                          
TTYPE8  = 'BACKFILE'           / label for field   8                             
TFORM8  = '64A     '           / data format of field: ASCII Character           
TUNIT8  = '        '           / physical unit of field                          
TTYPE9  = 'BACKSCAL'           / label for field   9                             
TFORM9  = '1E      '           / data format of field: 4-byte REAL               
TUNIT9  = '        '           / physical unit of field                          
TTYPE10 = 'CORRFILE'           / label for field  10                             
TFORM10 = '64A     '           / data format of field: ASCII Character           
TUNIT10 = '        '           / physical unit of field                          
TTYPE11 = 'CORRSCAL'           / label for field  11                             
TFORM11 = '1E      '           / data format of field: 4-byte REAL               
TUNIT11 = '        '           / physical unit of field                          
TTYPE12 = 'CHANNEL '           / label for field  12                             
TFORM12 = '3500I   '           / data format of field: 2-byte INTEGER            
TUNIT12 = '        '           / physical unit of field                          
TTYPE13 = 'COUNT   '           / label for field  13                             
TFORM13 = '3500I   '           / data format of field: 2-byte INTEGER            
TUNIT13 = 'count   '           / physical unit of field                          
TTYPE14 = 'STAT_ERR'           / label for field  14                             
TFORM14 = '3500E   '           / data format of field: 4-byte REAL               
TUNIT14 = 'count   '           / physical unit of field                          
TTYPE15 = 'SYS_ERR '           / label for field  15                             
TFORM15 = '3500E   '           / data format of field: 4-byte REAL               
TUNIT15 = 'count   '           / physical unit of field                          
TTYPE16 = 'QUAL    '           / label for field  16                             
TFORM16 = '3500I   '           / data format of field: 2-byte INTEGER            
TUNIT16 = '        '           / physical unit of field                          
TTYPE17 = 'GRPG    '           / label for field  17                             
TFORM17 = '3500I   '           / data format of field: 2-byte INTEGER            
TUNIT17 = '        '           / physical unit of field                          
TTYPE18 = 'BACKGND '           / label for field  18                             
TFORM18 = '3500E   '           / data format of field: 4-byte REAL               
TUNIT18 = 'count   '           / physical unit of field                          
TTYPE19 = 'BINLO   '           / label for field  19                             
TFORM19 = '3500E   '           / data format of field: 4-byte REAL               
TUNIT19 = 'angstrom'           / physical unit of field                          
TTYPE20 = 'BINHI   '           / label for field  20                             
TFORM20 = '3500E   '           / data format of field: 4-byte REAL               
TUNIT20 = 'angstrom'           / physical unit of field                          
TTYPE21 = 'ARF     '           / label for field  21                             
TFORM21 = '3500E   '           / data format of field: 4-byte REAL               
TUNIT21 = 'cm**2   '           / physical unit of field                          
TTYPE22 = 'FLUX    '           / label for field  22                             
TFORM22 = '3500E   '           / data format of field: 4-byte REAL               
TUNIT22 = 'photon /s /cm**2 /angstrom' / physical unit of field                  
TTYPE23 = 'FLUX_ERR'           / label for field  23                             
TFORM23 = '3500E   '           / data format of field: 4-byte REAL               
TUNIT23 = 'photon /s /cm**2 /angstrom' / physical unit of field                  
EXTNAME = 'SPECTRUM'           / Extension name                                  
COMMENT                                                                          

COMMENT                        / Table Coordinate System Keywords-------------- 
COMMENT                                                                          

COMMENT                        / Configuration control------------------------- 
ORIGIN  = 'ASC     '                                                             
CREATOR = 'progname'           / v0.0.0                                          
REVISION=                    0 / Processing system revision number               
CHECKSUM= 'lnTamnSXlnSalnSU'   / encoded HDU checksum updated on 07/04/98        
DATASUM = ' 262426642'         / data unit checksum updated on 07/04/98          
CONTENT = 'SPECTRUM'           / What data product                               
HDUSPEC = 'LETG    '           / Level 2 Data Products ICD, Version 0.0  / ICD r 
HDUDOC  = 'Arnaud  '           / et al. 1992a Legacy 2  p 65  Type: II           
HDUVERS = '1.1.0   '                                                             
HDUCLASS= 'ASC     '           / format conforms to ASC Spectral standards       
HDUCLAS1= 'SPECTRUM'           / Extension contains a Spectrum                   
HDUCLAS2= 'NET     '           / Extension contains a Spectrum                   
HDUCLAS3= 'RATE    '           / Extension contains rate                         
HDUCLAS4= 'TYPE:II '           / Multiple PHA file contained                     
LONGSTRN= 'OGIP    '           / 1.0            / The OGIP long string conventio 
COMMENT    This FITS file may contain long string keyword values that are        
COMMENT    continued over multiple keywords.  This convention uses the   &       
COMMENT    character at the end of a string which is then continued              
COMMENT    on subsequent keywords whose name    CONTINUE .                       
HISTORY    Input event file: acis123456789N000_evt0.fits                         

COMMENT                        / Time information block---------------------- 
DATE    = '1998-01-01T00:00:00'/ Date and time of file creation (UTC)           
DATE-OBS= '1998-01-01T00:00:00'/ TT, with clock correction if CLOCKAPP          
DATE-END= '1998-01-01T00:00:00'/ TT, with clock correction if CLOCKAPP          
TIMESYS = 'TT      '           / AXAF time will be TT (Terrestrial Time)         
MJDREF  =                50814 / 1998-01-01T00:00:00 (TT) expressed in MJD (TT)  
COMMENT                        / MJD   JD - 2400000.5                           
TIMEZERO=                  0.0 / 0.0 is the cumulative clock correction          
TIMEUNIT= 's       '           /                                                 
BTIMNULL=                  0.0 / Basic Time offset (s)                           
BTIMRATE=                 0.25 / Basic Time clock rate (s / VCDUcount)           
BTIMDRFT=                  0.0 / Basic Time clock drift (s / VCDUcount^2)        
BTIMCORR=                  0.0 / Correction applied to Basic Time rate (s)       
TIMEREF = 'LOCAL   '           / No pathlength corrections                       
TASSIGN = 'SATELLITE'          / Spacecraft clock                                
CLOCKAPP=                    T / Clock correction applied                        
TIERRELA=               1.0E-9 / Short-term clock stability                      
TIERABSO=               1.0E-4 / Absolute precision of clock correction          
TIMVERSN= 'ASC-FITS-1.1'       / AXAF FITS design document                       
TSTART  =                  0.0 / As in the "TIME" column: raw space craft clock; 
TSTOP   =                  0.0 /   add TIMEZERO and MJDREF for absolute TT       
STARTMJF=                    0 / Major frame count at start                      
STARTMNF=                    0 / Minor frame count at start                      
STARTOBT=                    0 / On-Board MET close to STARTMJF and STARTMNF     
STOPMJF =                    0 / Major frame count at stop                       
STOPMNF =                    0 / Minor frame count at stop                       
TIMEPIXR=                  0.0 / Time stamp refers to start of bin               
TIMEDEL =                  0.0 / Time resolution of data (in seconds)            

COMMENT                        / Observation information block----------------- 
OBSERVER= '/       '           / Name of Principal Investigator/Guest Observer   
OBS_ID  = 'xxxxxxxxxxxxxxx'    / Whatever the convention is ...                  
MISSION = 'AXAF    '           / Mission is AXAF                                 
TELESCOP= 'AXAF    '           / Telescope is AXAF                               
INSTRUME= 'ACIS    '           / HRC, ACIS, EPHIN, S/C subsystems                
DETNAM  = 'ACIS-S  '           / Detector name                                   
GRATING = 'HETG    '           / Grating                                         
OBS_MODE= 'POINTING'           / Pointing, slew, or scan                         
DATAMODE= 'RAW     '           / Datamode (varies only for science instr. data)  
SIM_X   =                  0.0 / Position of SIM in mm                           
SIM_Y   =                  0.0 /                                                 
SIM_Z   =               -237.4 /                                                 
FOC_LEN =              10065.0 / Assumed focal length, mm                        
ONTIME  =                100.0 / Sum of GTIs                                     

COMMENT                        / Source information block---------------------- 
OBJECT  = 'TEST    '           / Source name                                     
RA_NOM  =               -100.0 / Nominal pointing                                
DEC_NOM =               -100.0 / Nominal pointing                                
ROLL_NOM=                -40.0 / Nominal roll angle, deg                         
EQUINOX =               2000.0 / J2000.0                                         
RADECSYS= 'ICRS    '           / Julian coordinate reference frame               
DATACLAS= 'SIMULATED'          / for real data, use  OBSERVED                    
END                                                                              
\end{verbatim}
\clearpage

\subsubsection{Region Extension Header}
\begin{verbatim}
                       TBS
\end{verbatim}

\subsection{Full Header: spectral redistribution file (RMF)}

TBS

\subsection{Full Header: spectral measurements file}

TBS


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

