% Time-stamp: <98/02/20 13:58:12 dph> % MIT Directory: ~dph/h1/ASC/TG/Flight/L15_ICD/ % CfA Directory: /dev/null % File: ICD_L1.5.tex % Author: D. Huenemoerder % Original version: 971213 based on HRC L1 % % (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} } %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% % 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}%%%%%%%%%% } %%%%%%%%%%%%%%%%%%%%%% 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 Dec 1997 % my first draft, uncirculated %Revision 0.9; 23 Dec 1997 % my first draft, for circulation, after % which it will become: %Revision 1.0---02 Feb 1998 % reviewed, updated. %Revision 1.1---18 Feb 1998 % reviewed, updated. Revision 1.2---20 Feb 1998 % A.Rots; region extension, TNULLi }} \hyphenation{pipe-line} \hyphenation{pipe-lines} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \Skinny \Header{L1.5 to ASC Archive ICD /}{\Revision} \begin{document} % \putstring{x}{y}{angle}{scale}{gray}{string} % gray: 0=black, 1=white %\putstring{70}{40}{90}{40}{0.90}{D R A F T -DRAFT- D R A F T} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% %%% %%% 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 1.5 to ASC Archive Interface Control Document} ({\tt http://space.mit.edu/ASC/docs/ICD\_L1.5.ps.gz}) \vspace*{0.2in} \Revision \end{center} \vfill \begin{tabular}{lll} Submitted: & \rule{3.25in}{0.01in} & \rule{0.55in}{0.01in} \\ & David Huenemoerder & Date \\ & Grating Scientist, ASC Science Data Systems & \\[0.25in] Concurred: & \rule{3.5in}{0.01in} & \rule{0.75in}{0.01in} \\ & Michael Juda & Date \\ & Grating Scientist, ASC Dev. \& Ops. Group & \\[0.25in] Concurred: & \rule{3.5in}{0.01in} & \rule{0.75in}{0.01in} \\ & Panagoula Zografou & Date \\ & ASC Data Systems Group Leader, ASC Archives & \\[0.25in] Concurred: & \rule{3.5in}{0.01in} & \rule{0.75in}{0.01in} \\ & Janet De Ponte & Date \\ & ASC Data Systems Group Leader, L1.5 Pipelines & \\[0.25in] Concurred: & \rule{3.5in}{0.01in} & \rule{0.75in}{0.01in} \\ & Fred Seibel & Date \\ & Manager, ASC Data Systems & \\[0.25in] Concurred: & \rule{3.5in}{0.01in} & \rule{0.75in}{0.01in} \\ & Martin Elvis & Date \\ & Manager, ASC Science Data Systems & \\[0.25in] Approved: & \rule{3.5in}{0.01in} & \rule{0.75in}{0.01in} \\ & Harvey Tananbaum & Date \\ & Director, ASC & \\ \end{tabular} \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 Dec 97 &0.9 &all &Initial Draft \\\hline % 3 Feb 98 &1.0 &all &Revisions as per review by DS\\ % 18 Feb 98 &1.1 &all &Revisions as per comments of AR, JCM, JHK, AD; generic FITS material removed and referenced to ASC FITS document. Added FITS region specifications. Specified HRC columns to drop.\\ % 20 Feb 98 &1.2 &all &Minor edits, as per AR comments. Major changes to REGION section: cast as BINTABLE extension instead of a file. Added TNULL$i$ keywords to grating columns as appropriate.\\ % & & &\\\hline % \end{tabular} \end{center} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \section*{Unresolved Issues} The following is a list of unresolved, un-reviewed, or un-implemented items: \begin{enumerate} \item 980218: Format and content of summary files is TBD. (page~\pageref{pg:summary}) \item 980218: Changed ``\_grt'' to ``\_evt1'' in filename, in accordance w/ the ASC FITS ``content'' specifications. (page~\pageref{pg:evt1}) \item 980218: Use of TNULL$i$ values is new. Is 0 an appropriate NULL value for GDP? (do pixels always start at 1? would -1 be better?) (page~\pageref{pg:NULLi}) \item 980218: REGION extension specification is new. Definition of region shapes needs review for consistency w/ other definitions in ASC s/w (data-model?). Future use of {\tt ASCII} file TBR: useful implementation of format transported as {\tt FITS}? Coord sys issue: are (RA--TAN,DEC--TAN) coords degrees of arc, or real RA and distorted angles near pole? ---affects definition of a ``rectangle''. (page~\pageref{pg:regionext}) \item 980218: Are there any ACIS L1 columns which can be omitted from L1.5? (page~\pageref{pg:acispunt}) \item 980218: Sample files are needed. (page~\pageref{pg:samples}) \end{enumerate} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% %%% %%% table of contents, list of tables %%% \clearpage \tableofcontents %\clearpage \listoftables %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \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 1.5 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 1.5 processing, described in Applicable Document~\ref{appdoc:se03}, consists of event processing of HRC or ACIS Level 1 products (which are described in Applicable Documents~\ref{appdoc:hrcicd} and~\ref{appdoc:acisicd}) to add grating-specific coordinates and associated values. Level 1.5 denotes an intermediate stage between Level 1 (primarily re-formatting and coordinate transformations) and Level 2 (primarily source analysis), since some minimal analysis is necessary on grating observations before coordinate transformations can be done (e.g., source detection). This document describes the {\em additional} structure and content of the resulting event files and of region and summary files that are generated from Level 1 products during Level 1.5 processing. \subsection{Scope} This interface shall apply to all TG-specific data products that are generated by ASC Level 1.5 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 1.5 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://legacy.gsfc.nasa.gov/docs/heasarc/ofwg/}\newline {\tt docs/summary/ogip\_93\_001\_summary.html} % \item\label{appdoc:ascfits} ASC FITS File Designers' Guide\newline {\tt http://hea-www.harvard.edu/\~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 {Link to be on: \tt http://space.mit.edu/ASC/docs/docs.html} % \end{enumerate} % 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: %\clearpage % \subsection{Functional Description} \subsubsection{Data Content Summary} All TG data sets generated by the Level 1.5 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 (e.g., ASCII region files of IRAF/PROS). \subsubsection{Recipients and Utilization} The primary recipients of TG Level 1.5 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 1.5 data products for instrument calibration, instrument and/or spacecraft monitoring and trends analysis, and validation and verification of the Level 0, Level 1, and Level 1.5 software and of the data products themselves. Level 1.5 data products will also be used in Level 2 (standard data analysis) pipelines, the products of which will be used for all of the above purposes. \subsubsection{Pertinent Relationships with Other Interfaces} Changes to the definition of HRC or ACIS Level 1 data products, as described in Applicable Documents~\ref{appdoc:hrcicd} and~\ref{appdoc:acisicd}, may affect the Level 1.5 data products described in the current document. \subsection{Assumptions and Constraints} For each TG science event run reported in the AXAF telemetry stream, Level 1.5 processing shall generate a set of product files as shown in Table~\ref{tab:dataproductfiles}. The products depend upon possibly time-dependent calibration data for coordinate transformations and region definitions. The natural subdivision of TG Level 1.5 processing 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 will therefore be processed by ObI by the Level 1.5 pipeline. The pipeline will accept a list of one or more ObIs and process each independently. \subsection{Products Not Covered} TG Level 1.5 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 1.5 products (those parts of the product which are common to ACIS and HRC Level 1 products), are not currently included within the interface defined by this document. \Note{(980203) Issue: monitoring and trends and V\&V may use L1.5 products, or generate new products which are archived. Which ICD for these?} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% %\clearpage % \section{Detailed Interface Specifications} \subsection{Labeling and Identification} The data files generated by the Level 1.5 processing pipeline shall be assigned external names as shown in Table~\ref{tab:dataproductfiles}. The names obey the following convention:% % % primary modes: % % has = HETGS = HETG/ACIS-S % lhs = LETGS = LETG/HRC-S % % backup modes: % % hhi = HETG/HRC-I % lhi = LETG/HRC-I % % undesireable, but possible modes: % % hai = HETG/ACIS-I % hhs = HETG/HRC-S % lai = LETG/ACIS-I % las = LETG/ACIS-S $$GAS\_obi\_s\_{content}.{\tt fits}$$ % where $GAS$ is a mnemonic specifying the grating, array, and sub-array configuration. $G$ can have values of {\tt H} for HETG or {\tt L} for LETG. The detector array, $A$, is specified by {\tt A} for ACIS or {\tt H} for HRC. The sub-array, $S$, may be {\tt S} for spectroscopic array or {\tt I} for imaging. $obi$ will uniquely identify the ObI in which the data were taken, $s$ is an index specifying the science run number within the ObI, and {\tt{\em content}} specifies the file content (see Table~\ref{tab:dataproductfiles}). (Valid values for ``content'' are given by the ``ASC EXTNAME/HDUCLASS/CONTENT Dictionary''.) % \Remark{Get link ref for EXTNAME/etc dictionary} % % \Note{DS note: ``\_grt'' changed to ``\_evt1'', since the latter is a defined FITS ``content'' for Level 1 events.} % %%% %%% Level 1.5 data products table %%% \begin{table}[h] \label{pg:evt1} \begin{center} \begin{tabular}{|ll|}\hline \multicolumn{1}{|l}{\bf Title} & \multicolumn{1}{l|}{\bf File name}\\ Event data & {\tt *\_evt1.fits}\\ % Source regions (if ASCII)& {\tt *.reg}\\ %Source regions (if FITS)& {\tt *\_region.fits}\\ % Level 1.5 summary & {\tt *\_sum.ps}\\\hline \end{tabular} \caption{\em TG Level 1.5 Data Product Files} \label{tab:dataproductfiles} \end{center} \end{table} % \Note{Issue: region file type currently in use is ASCII, but will be deprecated in favor of a FITS extension definition.} % \Note{Issue: Current 5 pipe produces ``.ps'' summaries, but these may be deferred to Level 2 processing (after merging of ObI's and binning images and spectra) L1.5 summary is then material produced for later collection and formatting, but desireable per ObI for diagnostic inspection.} % No additional non-instrument-specific data products are output by the TG Level 1.5 processing pipeline. \subsection{Substructure Definition and Format} The ``ASC FITS Designers' Guide'' (Applicable Document~\ref{appdoc:ascfits}) defines and lists 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}). \subsubsection{Header/Trailer Description Details} Table~\ref{tab:headerkeywords} shows the associated keywords that differ from ACIS or HRC L1 files to specify the TG Level 1.5 products. % \begin{table}[h] \begin{tabular}{|l|}\hline \verb@GRATING = 'HETG ' / HETG, LETG or NONE@\\ \verb@HDUCLASS= 'ASC ' / @\\ \verb@HDUCLAS1= 'EVENTS ' / @\\ \verb@HDUCLAS2= 'ALL ' / @\\ \verb@HDUCLAS3= 'RESOLVED' / ASC definition for TG coord. events@\\ \verb@HDUSPEC = 'Grating Data Products: Level 1.5 ICD, V1.1' / ICD ref. @\\ \verb@HDUDOC = 'ASC-FITS-1.0: McDowell, Rots: ASC FITS Designers Guide' /@\\\hline \end{tabular} \caption{\em Level 1.5 - specific FITS Header Keywords} \label{tab:headerkeywords} \end{table} % The binary tables are further described by an extension header that immediately follows the keyword header (since the primary data unit is empty). In the file definition tables that follow, only the associated fields added to the Level 1 products by Level 1.5 processing or which require additional explanation are defined. % \begin{table}[h] \begin{center} \begin{tabular}{|l|}\hline % \verb@ACSYS1 = 'ASC-GDP-x.x' / (optional) grating diffraction pixel coords@\\ \verb@TCTYP1 = 'TG_GDPX ' / Grating Diffraction Pixels@ \\ \verb@TCRVL1 = 0.0 / Nominal angle@ \\ \verb@TCRPX1 = 16384.5 / Reference pixel@ \\ \verb@TCDLT1 = 1.59265544165e-5 / [degrees/pixel]@\\ \verb@TDBIN1 = 10 / default [degrees/bin]@\\ \verb@TCUNI1 = 'deg' / Unit of GDP@\\\hline % \verb@ACSYS2 = 'ASC-GDP-x.x' / (optional) grating diffraction pixel coords@\\ \verb@TCTYP2 = 'TG_GDPY ' / Grating Diffraction Pixels@ \\ \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 GDP@\\\hline % \end{tabular} \caption{\em Special Keywords for TG Columns with coordinate systems. Grating coordinates can be specified either by angle, wavelength, or pixel. The pixel system requires a coordinate system.} \label{tab:coordkeywords} \end{center} \end{table} % \subsubsection{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{\em Special Keywords describing calibration files.} \label{tab:rmfkeys} \end{center} \end{table} % \Remark{TBD: Need reference ICD for order sorting table.} \subsection{Event Data Files (*\_evt1.fits)} 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. For example, a $(TG\_R, TG\_D)$ image should only be made for a selection on $TG\_SRCID$. % \begin{description} % \item[$TG\_SRCID$ ] is the source number, as output from the detection algorithm. This is a small integer, equal or greater than 0 and less than or equal to 10. A $TG\_SRCID$ of 0 means background --- the photon has not been associated with a detected source. (The maximum of 10 was a compromise between implementation efficiency and a feasible maximum number of sources for a grating observation.) % \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\_R$: ] diffraction angle, parallel to the dispersion. For an on-axis source, the angle ranges from $-0.5$ to $+0.5$ degrees for HETGS, and about twice that for LETGS. Offset-pointing can increase the range somewhat. For background or zero-order photons, $TG\_R$ is undefined, and stored as $NaN$. % \item[$TG\_D$: ] cross-dispersion (spatial) angle. For an on-axis source, this ranges from about $-0.1$ to $0.1$ degrees for HETGS or LETGS. In practice, it is generally restricted to much less ($-0.001$ to $0.001$ degrees), though in backup modes (e.g., HETG/HRC-I), it could conceivably be as large as 1 degree. For background or zero-order photons, $TG\_D$ is undefined, and stored as $NaN$. % \item[$TG\_MLAM$: ] The diffraction order times the wavelength. This can range from about $-200$\AA\ to $200$ \AA\ for on-axis data (LETGS). Off-axis pointing theoretically allows $-400$ to $400$ \AA\ (though with a severe penalty in resolution!) For background or zero-order photons, $TG\_MLAM$ is undefined, and stored as $NaN$. % \item[$TG\_M$: ] The diffraction order, if resolved. This is a small integer, practically within $-30$ to $+30$. The value, $99$, however, 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). The physically meaningful geometric limit set by the ACIS-S array with HETG is about $\pm62$ (defined by 10 keV at maximum offset-pointing). % \item[$TG\_LAM$: ] Photon wavelength, if resolved. For LETGS events ($TG\_PART$ is 3--7), $TG\_LAM$ will be set to the first-order wavelength at that position. For background or zero-order photons, $TG\_LAM$ is undefined, and stored as $NaN$. % \item[$TG\_SMAP$: ] Source map. This is a bitmap which matches photons to multiple sources. This is partially redundant with $TG\_SRCID$, but is used in the case of multiple sources observed with HETG in which MEG and HEG parts from different sources cross. Then, if photons cannot be resolved to a specific source (e.g., it could resolve to either of two sources), the bits will indicate which sources it could belong to. The mapping of the bits to the source ID is TBD.% \Remark{TBD: specify $TG\_SMAP$ bits interpretation}% % \item[$TG\_GDPX$, $TG\_GDPY$] (optional) refer to coordinates in Grating Diffraction Pixels. These are analogous to $TG\_R$ and $TG\_D$. They are intermediate coordinates, and optional in L1.5 files. For background or zero-order photons, $TG\_GDPX$ and $TG_GDPY$ are undefined, and stored as $0$. % \end{description} % % \Note{Issue: current implementation uses 0.0 as the value for unresolved real quantities ($TG\_R$, $TG\_D$, $TG\_MLAM$, and $TG\_LAM$). This revision proposes using recognized IEEE NaN values, and the TNULL$i$ keywords. This would make interpretation unambiguous and straightforward. E.g., $TG\_D=0.0$ is valid, if $TG\_R \ne 0.0$. For pixel coords, 0 is invalid value, since convention has first pixel as 1.} \Remark{TBD: is 0 a good NULL value for GDP?} \begin{table}[ht] \label{pg:NULLi} \begin{center} {\small \begin{tabular}{|c|c|c|c|p{0.5in}|c|c|p{1.65in}|} \hline & & & & & & &\\ TTYPE & TUNIT & TFORM & TLMIN & TLMAX & TDBIN & TNULL & \multicolumn{1}{|c|}{Comment}\\ & & & & & & &\\\hline % TG\_R & deg & 1D $|$ 1E & $-2.0$ & $2.0$ & $1.593E-4$ & $NaN$ & diffraction angle \\\hline % TG\_D & deg & 1D $|$ 1E & $-2.0$ & $2.0$ & $1.593E-4$ & $NaN$ & cross-dispersion angle \\\hline % TG\_MLAM & angstrom & 1D $|$ 1E & $-400.0$ & $400.0$ & $2.0E-3$ & $NaN$ & $m\times\lambda$ \\\hline % TG\_M & 1 & 1I & $-62$ & $99$ & N/A & 99 & order ($m$) \\\hline % TG\_LAM & angstrom & 1D $|$ 1E & -400 & 400 & $2.0E-3$ & $NaN$ & wavelength ($\lambda$) \\\hline % TG\_PART & 1 & 1I & 0 & 99 & N/A & N/A & component (HEG, MEG, LEG, \ldots) \\\hline % TG\_SMAP & 1 & 1I & 0 & 32767 & N/A & N/A & source map \\\hline % TG\_SRCID & 1 & 1I & 0 & 10 & N/A & N/A & source ID \\\hline % TG\_GDPX & pixel & 1J & 1 & $2^{16}$\newline (65536) & 10 & 0 & grating diffraction pixel, dispersion direction\newline (optional)\\\hline % TG\_GDPY & pixel & 1J & 1 & $2^{15}$\newline (32768) & 10 & 0 & grating diffraction pixel, cross-dispersion\newline (optional)\\\hline % \end{tabular} } % close \small \caption{\em FITS Event Data File binary table contents (one entry per event). ``N/A'' means ``Not Applicable''. ``$NaN$'' is the IEEE standard for ``Not A Number''.} \label{tab:evtcontents} \end{center} \end{table}% % \subsubsection{Columns Dropped from Level 1 Files} There are some columns in Level 1 input files which are seldom used, so it is not necessary to carry them into Level 1.5. They will always be available in Level 1 products, if necessary. % \Remark{TBR} % \paragraph{HRC columns to omit: } {\tt \begin{tabular}{|l}\hline CRSV\\ CRSU\\ AMP\_SF\\ AV1\\ AV2\\ AV3\\ AU1\\ AU2\\ AU3\\ RAWX\\ RAWY\\ SUMAMPS\\\hline \end{tabular} } % close \tt \paragraph{ACIS columns to omit: } \label{pg:acispunt} {\tt \begin{tabular}{|l}\hline TBR\\\hline \end{tabular} } % close \tt % \Remark{ACIS deletable columns TBD.} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% %\clearpage % \subsection{Grating Spectral Region Definitions ({\tt REGION BINTABLE} extension or {\tt *.reg ASCII} file)} For each ObI, one regional mask is created for each source, as defined by the zero-order sky coordinate output from source detection and width and angle parameters. The mask is designed to be of generous dimensions, such that the L1.5 product is a superset of photons likely to be selected for analysis, thus avoiding re-running the L1.5 pipeline for alternate selection criteria. It is defined in sky $(X,Y)$ coordinates and is used to filter the events for transformation to grating diffraction coordinates. \subsubsection{{\tt *.reg} (ASCII) Region File Definition} \Note{The {\tt ASCII} file is the current implementation and is included here until replaced by the {\tt FITS} implementation. We should probably keep this anyway, since the {\tt FITS} file will be a {\tt T}ransport mechanism, and usage may remain {\tt ASCII}. } \Remark{Future use of {\tt ASCII} region file TBR.} The {\tt ASCII} region file follows the {\tt IRAF/PROS} Region File definition (ref xxx), % \Remark{get reference for IRAF/PROS regions} % with some pipeline directives added in comment fields. The coordinates are given as sky pixel values, whose coordinate system can be obtained from the event-file's ({\tt *\_evt1.fits}) extension header keywords for columns labeled {\tt X} and {\tt Y}. %%% NOTE: ftool fsaoi will convert region file to ftools file, but: %%% its output isn't a FITS file, it is case sensitive, the syntax %%% isn't the same as the L1.5 pipe (``physical'' isn't recongnized, %%% fsaoi wants something like ``BOX(3200,3200,119,5.00)'' vs %%% ``rotbox 3200 3200 119 5.0d;'' \begin{itemize} \item The first line of the {\tt *.reg} file contains a comment line of the format {\tt \#.mode} where mode is {\tt HETG, LETG, DRAKE, HEG,} or {\tt MEG}. Note that the modes {\tt HEG} and {\tt MEG} are special, in that one cannot observe in flight with them separately; they are for special processing purposes of ground-calibration data, simulations, or specially filtered flight data. % \item The second line of the file contains a comment line of the format {\tt ``\#.SRC $n$''} where $n$ is the current source id. \item For any given source, a maximum of 8 distinct parts (neglecting background) exist. These parts are: zero order, heg arm, meg arm, letg, drake 1, drake 2, drake 3, and drake 4. For any given source, not all of these parts will be listed. \item Relevant parts of a source are listed one per line. The ordering of the parts depends on the type of data The parts for each mode are, in region-file line order: \begin{tabular}{lll} HETG& 1---&Zero-order\\ & 2---&HEG\\ & 3---&MEG\\[1mm] LETG& 1---&Zero-order\\ & 2---&LEG\\[1mm] DRAKE (HESF)&1---&Zero-order\\ &2---&LEG\\ &3---&Drake 1\\ &4---&Drake 2\\ &5---&Drake 3\\ &6---&Drake 4\\[1mm] HEG& 1---&Zero-order\\ & 2---&HEG\\[1mm] MEG& 1---&Zero-order\\ & 2---&MEG\\[1mm] \end{tabular} % I don't know what the next line means: (from anastasia) % \item All source parts are defined in physical coords \item Parts that belong to a source are identified as follows: {\tt physical; ;} where {\tt } is any of the following: \begin{description} {\tt \item[BOX] xcenter ycenter xwidth yheight [angle] \item [CIRCLE] xcenter ycenter radius \item [ROTBOX] xcenter ycenter xwidth yheight angle } \end{description} \item abbreviations {\tt b, c,} or {\tt r} may also be used for {\tt BOX, CIRCLE,} and {\tt ROTBOX}, respectively. \item blank lines are ignored; they may be used to make the {\tt *.reg} more readable to users, but are not used by the code. \item a separate source comment line (e.g. {\tt \#.SRC 3}) must be supplied before each source included in the region file. A region file may specify multiple sources. \item {\tt ASCII} characters may be in upper or lowercase. \item Lines beginning with ``{\tt \#.}'' are processed as instructions by Level 1.5 software. They are treated as normal comments by other region parsers. \item Lines starting with a ``{\tt \#}'' and succeeded by any other characters other than ``{\tt .}'' are considered comments. \end{itemize} \paragraph{Example --- A single HETG source, source ID of 1:} \begin{center} \begin{tabular}{|l|}\hline \verb@#.HETG@\\ \verb@#.SRC 1 @\\ \verb@physical; circle 3200 3200 70;@\\ \verb@physical; rotbox 3200 3200 3300 119 -5.3d;@\\ \verb@physical; rotbox 3200 3200 3300 119 5.00d;@\\\hline \end{tabular} \end{center} \paragraph{Example --- Two LETG sources, source IDs of 2 and 4:} \begin{center} \begin{tabular}{|l|}\hline \verb@#.LETG@\\ \verb@#.SRC 2@\\ \verb@physical; c 2000, 2000, 100;@\\ \verb@physical; box 2000, 2000 2000 140;@\\ \verb@ @\\ \verb@#.SRC 4@\\ \verb@physical; c 4000, 4000, 100;@\\ \verb@physical; box 4000, 4000 3500 150;@\\\hline \end{tabular} \end{center} %\clearpage % \subsubsection{FITS Region Extension Definition} \label{pg:regionext} \Note{Issue: 980218 new specification.} % The generic definition of an ASC FITS region is given in the ``ASC FITS File Designers' Guide'' (Applicable Document~\ref{appdoc:ascfits}. The region HDU will be a single {\tt REGION} auxiliary extension, whose header is comprised of the mandatory {\tt REGION}-content header, table coordinate system and ranges, short configuration control, short timing, and short observation information components. 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 components described by a circle for zero-order and rotated rectangles for diffracted orders. There are generally multiple components for each spectrum and possibly multiple sources per observation. \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 '@\\ % \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{\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. What is RA--TAN? i.e., is a rectangle still a rectangle near the pole?} % \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 % SHAPE & - & 16A & - & - & Shape of region: may be CIRCLE or ROTBOX.\\\hline % X & pixel & 12J$|$12E$|$12D & 0 & 65536 & sky $X$ (RA) coordinate vector for SHAPE.\\\hline % Y & pixel & 12J$|$12E$|$12D & 0 & 65536 & sky $Y$ (Dec) coordinate vector for SHAPE.\\\hline % R & pixel & 12J$|$12E$|$12D & 0 & 65536 & radius vector for SHAPE (sky units) \\\hline % ROTANG & deg & 12J$|$12E$|$12D & 0 & 360 & Rotation angle for SHAPE, in degrees.\\\hline % COMPONENT & - & I & 1 & 6 & Component number that SHAPE belongs to (default is 1). Interpretation of this depends upon the GRATING column.\\\hline % INCLUDE & - & I & 0 & 1 & Inclusion (1; default) or exclusion (0). \\\hline % SOURCE & - & I & 0 & 10 & Source number. \\\hline % GRATING & - & 16A & - & - & Applicable grating; one of: HETG or LETG\\\hline \end{tabular} } \caption{\em FITS grating region file binary table contents.} \label{tab:ltfbintable} \end{center} \end{table} The conditional interpretation of the {\tt COMPONENT} upon {\tt GRATING} 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 & 1& Zero-order\\ & 2& HEG arm\\ & 3& MEG arm\\\hline LETG & 1& Zero-order\\ & 2& LEG arm\\ & 3& HESF (Drake Flat) region 1\\ & 4& HESF (Drake Flat) region 2\\ & 5& HESF (Drake Flat) region 3\\ & 6& HESF (Drake Flat) region 4\\\hline % \end{tabular} % \caption{\em Region table component interpretation.} \label{tab:components} % \end{center} \end{table} The interpretation of the coordinate vectors for grating region shapes, as given in the ``ASC FITS File Designers' Guide'' (Applicable Document~\ref{appdoc:ascfits}) is: % \begin{description} \item[{\tt CIRCLE: }] First element of $X$, $Y$, $R$ vectors specifies center and radius. \item[{\tt ROTBOX: }] First two element of $X$ and $Y$ vectors specify bottom-left and upper-right corners of a rectangle. The first element of {\tt ROTANG} specifies counter-clockwise rotation of the rectangle with respect to $X$ and $Y$ axese center of the rotation about the lower-left corner. \end{description} % \Note{Issue: these definitions differ from syntax of ASCII regions, which specify center of box, widths of box, and rotation about box center. } \subsubsection{Example: Full Region Extension Header} TBS. \clearpage \subsection{Level 1.5 Summary File} \label{pg:summary} \Note{Note: Summary file definition very preliminary. Summary should be hardcopy (i.e., postscript) graphs, images, and tables. Graphs and images should also be written as GIF files (TBR), wrapped in HTML interface with ASCII tables and text. Postscript version (TBR) should be gzipped. Summary tables also provided as FITS bintables? } Since Level 1.5 processing has added columns to the data, but not yet merged ObIs, binned events into images, light curves, or spectra, nor performed any measurements of the data, Level 1.5 summary will consist of a statistical summary and diagnostic observational parameters. % \subsubsection*{L1.5 processing summary parameters: } \# sources, source table, roll\_tolerance % \subsubsection*{Observational parameters:} elapsed time, total good time, roll range % \subsubsection*{Order summary: } \bigskip \begin{tabular}{|rcc|}\hline \multicolumn{3}{|c|}{Field Summary}\\\hline & rate & counts\\\hline Total: & \tt 0.0E-00 & \tt 0.0E+00\\ Background:& \tt 0.0E-00 & \tt 0.0E+00\\\hline \end{tabular} \begin{picture}(420,740) \put(-10,600){ \mbox{ \begin{tabular}{|ccc|}\hline \multicolumn{3}{|c|}{Source Summary: HETG/ACIS-S}\\\hline & rate & counts\\\hline Zero-order& 0.00& 0.00\\ $HEG+$ & 0.00& 0.00\\ $HEG-$ & 0.00& 0.00\\ $MEG+$ & 0.00& 0.00\\ $MEG-$ & 0.00& 0.00\\ $HEG+1 $ & 0.00& 0.00\\ $HEG-1 $ & 0.00& 0.00\\ $HEG+2 $ & 0.00& 0.00\\ $HEG-2 $ & 0.00& 0.00\\ $HEG+3 $ & 0.00& 0.00\\ $HEG-3 $ & 0.00& 0.00\\ $MEG+1 $ & 0.00& 0.00\\ $MEG-1 $ & 0.00& 0.00\\ $MEG+2 $ & 0.00& 0.00\\ $MEG-2 $ & 0.00& 0.00\\ $MEG+3 $ & 0.00& 0.00\\ $MEG-3 $ & 0.00& 0.00\\\hline \end{tabular} } } \put(200,680){ \mbox{ \begin{tabular}{|ccc|}\hline \multicolumn{3}{|c|}{Source Summary: LETG/HRC-S}\\\hline & rate & counts\\\hline Zero-order& 0.00& 0.00\\ $LEG+ $ & 0.00& 0.00\\ $LEG- $ & 0.00& 0.00\\\hline $HESF+$ & 0.00& 0.00\\ $HESF-$ & 0.00& 0.00\\\hline \end{tabular} } } \put(-10,400){ \mbox{ \begin{tabular}{|ccc|}\hline \multicolumn{3}{|c|}{Source Summary: HETG/HRC-I}\\\hline & rate & counts\\\hline Zero-order& 0.00& 0.00\\ $HEG+ $ & 0.00& 0.00\\ $HEG- $ & 0.00& 0.00\\ $MEG+$ & 0.00& 0.00\\ $MEG-$ & 0.00& 0.00\\\hline \end{tabular} } } \put(200,530){ \mbox{ \begin{tabular}{|ccc|}\hline \multicolumn{3}{|c|}{Source Summary: LETG/ACIS-S}\\\hline & rate & counts\\\hline Zero-order& 0.00& 0.00\\ $LEG+$ & 0.00& 0.00\\ $LEG-$ & 0.00& 0.00\\ $LEG+1 $ & 0.00& 0.00\\ $LEG-1 $ & 0.00& 0.00\\ $LEG+2 $ & 0.00& 0.00\\ $LEG-2 $ & 0.00& 0.00\\ $LEG+3 $ & 0.00& 0.00\\ $LEG-3 $ & 0.00& 0.00\\\hline \end{tabular} } } \end{picture} \clearpage \subsection{Volume, Size, and Frequency Estimates} TBD \section{Example Files} \label{pg:samples} \begin{verbatim} TBS: HETG/ACIS-S 2 src FITS events, region, summary LETG/HRC_S 2 src LETG/HESF TBD. \end{verbatim} \end{document}