% Time-stamp: <98/09/09 14:35:19 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\\ Instrument(s)\\ Level\\ Scientist/SDS\\ Filetype\\ Created by tool\\ Used by tool(s)\\ Sample file\\\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---9 Sep 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: 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} {\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 %% % & % 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. \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. \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 \_[\_][].} \noindent where the mnemonics are: \begin{description} \item[\tt ] Instrument: ``acis'', ``hrci", ``hrcs'', \ldots \item[\tt ] Data source: ``x'', ``f'', ``t'', ``b'', ``s'', ``u'' \item[\tt ] TSTART (integer part): ``\#\#\#\#\#\#\#\#\#'' \item[\tt ] Processing run (version): ``N\#\#\#'' \item[\tt ] Optional discriminator (e.g., an ACIS FEP Id) \item[\tt ] Contents: ``evt'', ``prf'', ``hst'', ``src'', ``win'', ``bias'', ``sum'', \ldots \item[\tt ] Processing level: single digit: ``0'', ``1'', ``2'' \item[\tt ] Sublevel: single lower case letter; e.g., 1.5 is ``1a'' \item[\tt ] Superfluous: usually ``fits'' \end{description} % Relevant default values for instrument ({\tt }) are {\tt aciss} or {\tt hrcs}; for data source ({\tt }) 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.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 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} \leavevmode{\scalebox{0.85}{\includegraphics{HETGS_parts.eps}}} \leavevmode{\scalebox{0.85}{\includegraphics{LETGS_parts.eps}}} \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}