% this is a true latex file *-* % choose one of the following page styles: % aastyle = A&A Journal page style % iaufwgstyle = new IAU FITS Working Group style; like the A&A style, but % it has separate title page and no Abstract or Foreword. % onecol - used with iaufwgstyle to make one column format pages \newif\ifaastyle \newif\ifiaufwgstyle \newif\ifonecol \aastylefalse \iaufwgstyletrue \onecolfalse %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \ifiaufwgstyle \ifonecol \documentclass[onecolumn]{aa} \else \documentclass[traditabstract]{aa} \fi %LC %usepackage[T1]{fontenc} \usepackage{upquote,textcomp} %usepackage[usenames]{color} %LC replace next \usepackage[usenames,dvipsnames]{xcolor} %LC \usepackage{hyperref} %LC \usepackage{breakurl} %LC \usepackage{caption} %LC %usepackage[draftmarkpsonly]{lhelp} %LC %definecolor{draftgray}{rgb}{0.9,0.8,0.8} %LC %\usepackage[pdftex,bookmarks=true]{hyperref} \usepackage{hyperref} % default textheight = 705pt - reduce this so page numbers aren't chopped off \setlength{\topmargin}{0in} \setlength{\textheight}{682pt} \setlength{\floatsep}{10pt} \setlength{\intextsep}{14pt} \setlength{\textfloatsep}{10pt} \setlength{\dblfloatsep}{12pt} \setlength{\dbltextfloatsep}{12pt} \makeindex \fi %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \ifaastyle \documentclass[onecolumn,traditabstract]{aa} % \documentclass[traditabstract]{aa} \fi \usepackage{txfonts} \usepackage{epsf} \usepackage{natbib} \usepackage{url} % Added by RAS 2015-May for v3.1: %\usepackage{deluxetable} %LC get from http://fits.gsfc.nasa.gov/standard30/deluxetable.sty %\usepackage{caption} %\captionsetup{belowskip=0pt,aboveskip=4pt} %\newcommand{\tnm}[1] % {\tablenotemark{#1} % } % suppress the comma between the author and year in citations (the 5th argument) \bibpunct{(}{)}{;}{}{ }{,} \begin{document} %--------------------------------------------------------------------------------- % Instructions for editors of the FITS Standard % % Please use systematically the LaTeX macros defined below and listed here % instead of your own constructs. % % - A KEYWORD NAME shall normally use macro \kwd e.g. \kwd{BITPIX}. % - An INDEXED KEYWORD NAME shall use the double-argument macro \indxkw, % e.g. \indxkw{NAXIS}{n}. % - A DOUBLE-INDEXED KEYWORD NAME shall use triple-argument macro \dindxkw, % e.g. \dindxkw{i}{CTYP}{n}. % - The "alternative WCS version code" forms used in the WCS chapter are % \kwdalt, \indxkwdalt, and \dindxkwalt (the italic code "a" is appended where % appropriate). % - Keyword VALUES (including partial values, such as WCS algorithm codes, % and symbols, like those that specify date formats and table format codes) % shall use the macro \keyv for numbers (e.g. \keyv{1}, \keyv{0.0}), % logical (e.g. \keyv{T}), and literal strings, inclusive of the quote marks % (e.g. \keyv{'+'}, \keyv{'NOCOMPRESS'}). Quote marks are omitted where % a string value is not literal, which includes format codes like Fw.d, and % the CCYY-MM-DD notation for dates. % % - Binary- or ASCII-table COLUMN NAMES shall use the macro \column e.g. % \column{START}. % - The standard extensions shall use the \BINTABLE, \TABLE or \IMAGE macros. % Note they do not imply a trailing space, so this shall be explicitly added, % unless the macro is followed by punctuation. For instance, write % "an \IMAGE\ extension" but "\IMAGE-array extensions". % % - RFC~2119 verbs and verbal locutions (shall, should, shall not, etc.) shall use % macros \may, \must, \shall, \should, \mustnot, \shallnot, \shouldnot, % \optional, \recommended, \required, \notrecommended, \notrequired. % These macros do not imply a trailing space, so this shall be explicitly % added, unless the macro is followed by punctuation. For example, % "these macros \shall\ be used to indicate obligations or conditions according % to RFC~2119 but \shallnot\ be used for plain future tenses or conditional mood. % It might be \required\ or \recommended\ to do something, unless \optional." % % - FITS should appear in italics using the \FITS macro. % The FITS Standard has a capital ess. % % - Tables should be formatted such that the field columns are aligned and values % justified like the tabular column formatting. This is to make additions % easier to place in the correct location, and to make the appearance in the % source similar to that in the typeset document. Also note that there is a % small space after and before bracketing horizontal lines to avoid a cramped % appearance. % %--------------------------------------------------------------------------------- % FITS \newcommand{\FITS}{\textit{FITS}} % FITS keywords, single italicized argument. \newcommand{\keyi}[2]{\mbox{\texttt{#1}\hspace{1pt}{$#2$}\/}} \newcommand{\CRPIX}[1]{\keyi{CRPIX}{#1}} \newcommand{\CDELT}[1]{\keyi{CDELT}{#1}} \newcommand{\CRVAL}[1]{\keyi{CRVAL}{#1}} \newcommand{\CTYPE}[1]{\keyi{CTYPE}{#1}} \newcommand{\CUNIT}[1]{\keyi{CUNIT}{#1}} \newcommand{\NAXIS}[1]{\keyi{NAXIS}{#1}} \newcommand{\CROTA}[1]{\keyi{CROTA}{#1}} % FITS keywords, double italicized arguments. \newcommand{\keyii}[3]{\mbox{\texttt{#1}\hspace{1pt}{$#2$}\_{$#3$}\/}} \newcommand{\PC}[2]{\keyii{PC}{#1}{#2}} \newcommand{\CD}[2]{\keyii{CD}{#1}{#2}} \newcommand{\PV}[2]{\keyii{PV}{#1}{#2}} \newcommand{\PS}[2]{\keyii{PS}{#1}{#2}} % older ones \newcommand{\PCij}{\PC{i}{j}} \newcommand{\CDij}{\CD{i}{j}} \newcommand{\NN}[1]{\noalign{\noindent{#1}}\noalign{\vspace{4pt}}} % Definitions for formatting keywords, indexed keywords, and alternate forms \newcommand{\kwd}[1]{\mbox{\texttt{#1}}} \newcommand{\kwdalt}[1]{\mbox{\kwd{#1}\textit{a}}} \newcommand{\indxkw}[2]{\mbox{\texttt{#1}\textit{#2}}} \newcommand{\indxkwdalt}[2]{\mbox{\indxkw{#1}{#2}\textit{a}}} \newcommand{\dindxkw}[3]{\mbox{\textit{#1}\/\indxkw{#2}{#3}}} \newcommand{\dindxkwalt}[3]{\mbox{\dindxkw{#1}{#2}{#3}\textit{a}}} % Definitions for column and extension names. Although they all use % \texttt it would be easy now to switch the depiction by editing the % definitions. \newcommand{\column}[1]{\texttt{#1}} \newcommand{\BINTABLE}{\texttt{BINTABLE}} \newcommand{\TABLE}{\texttt{TABLE}} \newcommand{\IMAGE}{\texttt{IMAGE}} % FITS keyword value. \newcommand{\keyv}[1]{\mbox{\texttt{#1}}} % Added by RAS 2015-May for v3.1: \newcommand{\may}{\mbox{\em may}} \newcommand{\must}{\mbox{\em must}} \newcommand{\shall}{\mbox{\em shall}} \newcommand{\should}{\mbox{\em should}} % Augmented and \required revised by MJC for Version 4. % Note that there is no trailing space in those cases where the % instruction can be followed by punctuation. \newcommand{\mustnot}{\mbox{\em must not}} \newcommand{\notrecommended}{\mbox{\em not recommended}} \newcommand{\notrequired}{\mbox{\em not required}} \newcommand{\optional}{\mbox{\em optional}} \newcommand{\recommended}{\mbox{\em recommended}} \newcommand{\required}{\mbox{\em required}} \newcommand{\shallnot}{\mbox{\em shall not}} \newcommand{\shouldnot}{\mbox{\em should not}} %LC \newcommand{\TBW}[1]{\textcolor{magenta}{{\bf #1 \ } }} %LC \newcommand{\tbw}[1]{\textcolor{magenta}{#1}} %LC \newenvironment{redtext}{\color{red}}{\ignorespacesafterend} %LC \newenvironment{blutext}{\color{blue}}{\ignorespacesafterend} %LC \newenvironment{britext}{\color{BrickRed}}{\ignorespacesafterend} %LC \newenvironment{brotext}{\color{Brown}}{\ignorespacesafterend} %LC \newenvironment{gretext}{\color{OliveGreen}}{\ignorespacesafterend} %LC \newenvironment{viotext}{\color{Violet}}{\ignorespacesafterend} %LC \newenvironment{fuxtext}{\color{Fuchsia}}{\ignorespacesafterend} %LC \newenvironment{magtext}{\color{magenta}}{\ignorespacesafterend} %LC %##################### this section prints the IAUFWG style title page ############# \ifiaufwgstyle \begin{titlepage} \begin{center} \vspace*{4.0cm} {\huge \bf Definition of the Flexible Image Transport System \\ \vspace{0.2cm} (\FITS)} \\ {\large \vspace{5.0cm} The \FITS\ Standard \\ \vspace{0.3cm} %LCC Version 3.0: approved 2008 July 10 by the IAUFWG \\ %Version 3.1: updated 2015 July 6 by the IAUFWG \\ %Version 3.2: updated 2016 February 1 by the IAUFWG \\ %Version 3.3: updated 2016 March 18 by the IAUFWG \\ %Version 3.4: updated 2016 June 7 by the IAUFWG \\ %Version 3.5: updated 2016 July 11 by the IAUFWG \\ Version 4.0: updated 2016 July 22 by the IAUFWG \\ %Version \TBW{working draft} \\ \vspace{0.3cm} %LCC Document publication date: 2010 November 18 \\ Original document publication date: 2016 July 22 \\ Language-edited document publication date: 2018 August 13 \\ \vspace{6.0cm} \FITS\ Working Group \footnote{to be absorbed in Data Representation Working Group under new Commission B2} \\ Commission 5: Documentation and Astronomical Data \footnote{now Commission B2 Data and Documentation} \\ International Astronomical Union \\ \url{http://fits.gsfc.nasa.gov/iaufwg/} \\ } \end{center} \end{titlepage} \setcounter{page}{0} \pagestyle{empty} % print table of contents using one column format \onecolumn \cleardoublepage \setcounter{page}{1} \pagenumbering{roman} \pagestyle{headings} \addcontentsline{toc}{section}{Contents} \tableofcontents \listoftables %\pagestyle{empty} \cleardoublepage %\pagestyle{headings} % switch back to two column format, if that was selected \ifonecol \else \twocolumn \fi \setcounter{page}{1} \pagenumbering{arabic} \fi %##################### end of IAUFWG style title page ############# %########### the following prints the AA style title, Abstract, and Foreword \ifaastyle \title{Definition of the Flexible Image Transport System (\FITS), Version~3.0} \author{W. D. Pence \inst{1} \and L. Chiappetti \inst{2} \and C. G. Page \inst{3} \and R. A. Shaw \inst{4} \and E. Stobie \inst{4} } \institute{NASA Goddard Space Flight Center, Code 662, Greenbelt, MD 20771, USA \and INAF -- IASF Milano, via Bassini 15, I-20133 Milan, Italy \and Dept.\ of Physics \& Astronomy, Univ.\ of Leicester, University Road, Leicester LE1 7RH, UK \and National Optical Astronomy Observatory, 950 N.\ Cherry Avenue, Tucson, AZ 85719, USA } \date{Received; accepted} \abstract { The Flexible Image Transport System (\FITS) has been used by astronomers for over 30 years as a data interchange and archiving format; \FITS\ files are now handled by a wide range of astronomical software packages. Since the \FITS\ format definition document (the ``Standard'') was last printed in this journal in 2001, several new features have been developed and standardized, notably support for 64-bit integers in images and tables, variable-length arrays in tables, and new world-coordinate system conventions. The last provide a mapping from an element in a data array to a physical coordinate on the sky or within a spectrum. The \FITS\ Working Group of the International Astronomical Union has therefore produced this new Version~3.0 of the \FITS\ Standard, which is provided here in its entirety. In addition to describing the new features in \FITS, numerous editorial changes were made to the previous version to clarify and reorganize many of the sections. Also included are some appendices, which are not formally part of the Standard. The \FITS\ Standard is likely to undergo further evolution, in which case the latest version may be found on the \FITS\ Support Office website at \url{http://fits.gsfc.nasa.gov/}, which also provides many links to \FITS\-related resources. } \keywords{ standards -- reference systems -- instrumentation: miscellaneous -- methods: miscellaneous -- techniques: miscellaneous -- astronomical databases: miscellaneous } \maketitle %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \noindent{\large\bf Foreword} Since its inception in the late 1970s, the Flexible Image Transport System (\FITS) data format has enjoyed wide acceptance in the astronomical community. Indeed, \FITS\ is used as the archival format for most digital archives of astronomical data, \FITS\ is one of the most common run-time file formats for analysis applications, and \FITS\ is seeing continued utility as a component of data formats for the Virtual Observatory. After the initial \FITS\-definition papers appeared \citep{wells81, greisen81} the International Astronomical Union (IAU) formally endorsed the \FITS\ format in 1982 and formed the \FITS\ Working Group (FWG) in 1988 to review, approve, and maintain future extensions to \FITS. In recognition of the need for a single authoritative source on the correct usage of \FITS, a formal standard document was prepared with the support of a technical panel of the NASA/Science Office of Standards and Technology (NOST). In 2000, this \FITS\ Standard (Version~2.0) was approved by the IAUFWG and was published nearly verbatim in \cite{hanisch01}. The \FITS\ Standard has evolved in many significant ways during the last decade. In 2005 the IAUFWG approved use of the 64-bit integer data type in \FITS\ images and tables, and added support for variable-length arrays within tables. But some of the most-significant extensions to \FITS\ did not appear in the Standard document per se, but in a series of papers \citep{greisen02, calabretta02, greisen06} that described formalisms for the support of world-coordinate systems (WCSs), i.e., the mapping from a position in a data array to a physical coordinate system such as a position on the sky or within a spectrum. Although the IAUFWG officially recognized the content of these papers as a part of the Standard, they were not formally mentioned in the \FITS\ Standard document itself. In late 2006 the IAUFWG appointed a technical panel to address specific ambiguities that had been identified in the Standard over the years, to clarify the meaning of some portions of the text, and to consider how to incorporate all the approved elements of the Standard into one document. This work was completed by mid-2007, and after an extensive public comment and review process, this Version~3.0 of the \FITS\ Standard was approved by the IAU FWG in 2008, replacing all prior versions. Yet in spite of the substantial enhancements to \FITS\ that have occurred over the years, maintaining backward and forward compatibility has been a vital guiding principle: "Once \FITS, always \FITS" means that no change to the Standard will invalidate a \FITS\ file that was valid at the time it was created. This attribute is essential for long-term curation of digital data archives. \fi % table placed here, to force Latex to print it on the desired page % Table 1 MOVED FOR 2015 VERSION \ifaastyle % this is the rest of the A&A Foreword What follows is the verbatim text of the \FITS\ Version~3.0 Standard, apart from re-numbering the tables in deference to Journal style. The text also includes the Appendices, which are not formally a part of the Standard, but excludes the table of contents and the index. The first two sections review the history of \FITS\ and define the basic terms used throughout the rest of the document. The next three sections present the basics of \FITS, beginning with the overall organization of a \FITS\ file (Sect.~\ref{s:org}), which consists of a sequence of header units (Sect.~\ref{s:head}) and optional data units (Sect.~\ref{s:Drep}). This is followed by a detailed definition of the random-groups structure (Sect.~\ref{s:Rgrp}, now restricted to use with radio interferometry data), and the three standard \FITS\-extension types: image extensions (Sect.~\ref{s:image}), ASCII-table extensions (Sect.~\ref{s:ATabl}), and binary-table extensions (Sect.\ \ref{s:BTabl}). Finally, Sect.~\ref{s:WCS} provides basic information about the \FITS\ world-coordinate-system conventions. We caution that this presentation of the Standard is for the convenience of the community, and that it \may\ be superseded by newer versions. We refer the reader to the extensive set of resources on the \FITS\ Support Office at NASA/GSFC website\footnote{\url{http://fits.gsfc.nasa.gov/}}, which contains the latest version of the Standard document as well as a comprehensive collection of \FITS-related documents, software for validating and viewing \FITS\ files, and sample \FITS\ files from a variety of sources. This website also provides a registry of common \FITS\ conventions that are in use within the community. Although these conventions are not part of the official Standard, they may be helpful to designers of new \FITS\ data products. \fi % table placed here, to force Latex to print it on the desired page % Table 2 MOVED FOR 2015 VERSION \section{Introduction} % \addcontentsline{toc}{chapter}{Introduction}\markboth{}{} \begin{quote} {\em An archival format must be utterly portable and self-describing, on the assumption that, apart from the transcription device, neither the software nor the hardware that wrote the data will be available when the data are read.} {`Preserving Scientific Data on our Physical Universe,' p.\ 60.} {Steering Committee for the Study on the Long-Term Retention of Selected Scientific and Technical Records of the Federal Government, [US] National Research Council, National Academy Press 1995.} \end{quote} This document, hereafter referred to as the `Standard', describes the Flexible Image Transport System (\FITS), which is the standard archival data format for astronomical data sets. Although \FITS\ was originally designed for transporting image data on magnetic tape (which accounts for the `I' and `T' in the name), the capabilities of the \FITS\ format have expanded to accommodate more-complex data structures. The role of \FITS\ has also grown from simply a way to transport data between different analysis software systems into the preferred format for data in astronomical archives, as well as the on-line analysis format used by many software packages. This standard is intended as a formal codification of the \FITS\ format, which has been endorsed by the International Astronomical Union (IAU)\index{IAU} for the interchange of astronomical data \citep{iau83}. It is fully consistent with all actions and endorsements of the IAU \FITS\ Working\index{IAUFWG} Group (IAUFWG), which was appointed by Commission~5 of the IAU to oversee further development of the \FITS\ format. In particular, this standard defines the organization and content of the header and data units for all standard \FITS\ data structures: the primary array, the random-groups structure, the image extension, the ASCII-table extension, and the binary-table extension. It also specifies minimum structural requirements and general principles governing the creation of new extensions. For headers, it specifies the proper syntax for keyword records and defines required and reserved keywords. For data, it specifies character- and numeric-value representations and the ordering of contents within the byte stream. One important feature of the \FITS\ format is that its structure, down to the bit level, is completely specified in documents (such as this standard), many of which have been published in refereed scientific journals. Given these documents, which are readily available in hard copy form in libraries around the world as well as in electronic form on the Internet, future researchers should be able to decode the stream of bytes in any \FITS\ format data file. In contrast, many other current data formats are only implicitly defined by the software that reads and writes the files. If that software is not continually maintained so that it can be run on future computer systems, then the information encoded in those data files could be lost. \subsection{Brief history of \FITS} The \FITS\ format evolved out of the recognition that a standard format was needed for transferring astronomical images from one research institution to another. The first prototype developments of a universal interchange format that would eventually lead to the definition of the \FITS\ format began in 1976 between Don Wells at KPNO and Ron Harten at the Netherlands Foundation for Research in Astronomy (NFRA). This need for an image interchange format was raised at a meeting of the Astronomy section of the U.S. National Science Foundation in January 1979, which led to the formation of a task force to work on the problem. Most of the technical details of the first basic \FITS\ agreement (with files consisting of only a primary header followed by a data array) were subsequently developed by Don Wells and Eric Greisen (NRAO) in March 1979. After further refinements, and successful image interchange tests between observatories that used widely different types of computer systems, the first papers that defined the \FITS\ format were published in 1981 \citep{wells81, greisen81}. The \FITS\ format quickly became the de facto standard for data interchange within the astronomical community (mostly on nine-track magnetic tape at that time), and was officially endorsed by the IAU \index{IAU} in 1982 \citep{iau83}. Most national and international astronomical projects and organizations subsequently adopted the \FITS\ format for distribution and archiving of their scientific data products. Some of the highlights in the developmental history of \FITS\ are shown in Table~\ref{t:hist}. % table placed here, to force Latex to print it on the desired page % Table 1 \begin{table*} \centering \caption{Significant milestones in the development of \FITS.} \label{t:hist} \begin{tabular}{lll} \hline \hline Date & Milestone & Section \\ \hline \noalign{\smallskip} 1979 & Initial \FITS\ Agreement and first interchange of files & \\ 1981 & Published original (single HDU) definition \citep{wells81} & \\ 1981 & Published random-groups definition \citep{greisen81} & Sect.~\ref{s:Rgrp} \\ 1982 & Formally endorsed by the IAU \citep{iau83} & \\ 1988 & Defined rules for multiple extensions \citep{grosbol88} & \\ 1988 & IAU \FITS\ Working Group (IAUFWG) established & \\ 1988 & Extended to include ASCII-table extensions \citep{harten88} & Sect.~\ref{s:ATabl} \\ 1988 & Formal IAU approval of ASCII tables \citep{iau88} & Sect.~\ref{s:ATabl} \\ 1990 & Extended to include IEEE floating-point data \citep{wells90} & Sect.~\ref{s:FloatingPoint} \\ 1994 & Extended to multiple \IMAGE-array extensions \citep{ponz94} & Sect.~\ref{s:image} \\ 1995 & Extended to binary-table extensions \citep{cotton95} & Sect.~\ref{s:BTabl} \\ 1997 & Adopted four-digit-year date format \citep{bunclark97} & Sect.~\ref{s:dhist} \\ 2002 & Adopted proposals for world-coordinate systems \citep{greisen02} & Sect.~\ref{s:WCS} \\ 2002 & Adopted proposals for celestial coordinates \citep{calabretta02} & Sect.~\ref{sect:Celestkw} \\ 2004 & Adopted MIME types for \FITS\ data files \citep{rfc4047} & App.~\ref{s:MIMETypes} \\ 2005 & Extended to support variable-length arrays in binary tables & Sect.~\ref{s:app_varlen} \\ 2005 & Adopted proposals for spectral-coordinate systems \citep{greisen06} & Sect.~\ref{sect:SPECkw} \\ 2005 & Extended to include 64-bit integer data type & Sect.~\ref{s:sixtyfour} \\ %LC 2006 & Adopted WCS HEALPix projection \citep{calabretta07} & Sect.~\ref{sect:Celestkw} \\ 2006 & Established \FITS\ convention registry & \\ 2014 & Adopted proposals for time coordinates \citep{rots15} & Sect.~\ref{sect:timeReps} \\ 2016 & Adopted proposals for compressed data & Sect.~\ref{sect:CompressedForm} \\ 2016 & Adopted various registered conventions & App.~\ref{appregconv} \\ 2018 & General language editing & App.~\ref{langedit}\\ \noalign{\smallskip} \hline \end{tabular} \end{table*} % table placed here, to force Latex to print it on the desired page % Table 2 \begin{table*} \centering \caption{Version history of the Standard.} \label{t:docs} \begin{tabular}{lll} \hline \hline Version & Date & Status \\ \hline \noalign{\smallskip} NOST 100-0.1 & 1990 December & First Draft Standard \\ NOST 100-0.2 & 1991 June & Second Revised Draft Standard \\ NOST 100-0.3 & 1991 December & Third Revised Draft Standard \\ NOST 100-1.0 & 1993 June & NOST Standard \\ NOST 100-1.1 & 1995 September & NOST Standard \\ NOST 100-2.0 & 1999 March & NOST Standard \\ IAUFWG 2.1 & 2005 April & IAUFWG Standard \\ IAUFWG 2.1b & 2005 December & IAUFWG Standard \\ IAUFWG 3.0 & 2008 July & IAUFWG Standard \\ %LC %IAUFWG 3.1 & 2015 July & IAUFWG Standard \\ %IAUFWG 3.2 & 2016 February & IAUFWG Standard \\ %IAUFWG 3.3 & 2016 March & IAUFWG Standard \\ %IAUFWG 3.4 & 2016 June & IAUFWG Standard \\ %IAUFWG 3.5 & 2016 July & IAUFWG Standard \\ IAUFWG 4.0 & 2016 July & IAUFWG Standard (approved) \\ IAUFWG 4.0 & 2018 August & IAUFWG Standard (language-edited) \\ \noalign{\smallskip} \hline \end{tabular} \end{table*} \subsection{Version history of this document} \label{s:versionhist} The fundamental definition of the \FITS\ format was originally contained in a series of published papers \citep{wells81, greisen81, grosbol88, harten88}. As \FITS\ became more widely used, the need for a single document to unambiguously define the requirements of the \FITS\ format became apparent. In 1990, the NASA Science Office of Standards and Technology (NOST) at the Goddard Space Flight Center provided funding for a technical panel to develop the first version of this Standard document. As shown in Table~\ref{t:docs}, the NOST panel produced several draft versions, culminating in the first NOST standard document, NOST 100-1.0, in 1993. Although this document was developed under a NASA accreditation process, it was subsequently formally approved by the IAUFWG, \index{IAUFWG} which is the international control authority for the \FITS\ format. The small update to the Standard in 1995 (NOST 100-1.1) added a recommendation on the physical units of header keyword values. The NOST technical panel was convened a second time to make further updates and clarifications to the Standard, resulting in the NOST 100-2.0 version, which was approved by the IAUFWG\index{IAUFWG} in 1999 and published in 2001 \citep{hanisch01}. In 2005, the IAUFWG formally approved the variable-length\index{array, variable-length} array\index{variable-length array} convention in binary tables, and a short time later approved support for the 64-bit integers data type. New versions of the Standard were released to reflect both of these changes (Versions~IAUFWG~2.1 and IAUFWG~2.1b). %LCC Most recently, In early 2007 the IAUFWG \index{IAUFWG} appointed its own technical panel %LCC in early 2007 to consider further modifications and updates to the Standard. The changes proposed by this panel, which were ultimately approved in 2008 by the IAUFWG after a formal public review process, are shown in the %LCC this %LC Version~3.0 of the document, published in \cite{pence10}. %LC Since 2006 a Registry for \FITS\ conventions submitted by the community was established under the care of the IAUFWG at \url{http://fits.gsfc.nasa.gov/fits_registry.html}. The Registry was intended as a repository of documentation of usages, which, although not endorsed as part of the \FITS\ Standard, are otherwise perfectly legal usages of \FITS. In 2014 a small team was formed to evaluate the possible incorporation of some conventions within the Standard, while another small team was in charge to update the Standard document with a summary of the WCS time representation \citep{rots15}, which in the meanwhile had been voted natively as part of the \FITS\ Standard. Details on the conventions that have been incorporated into this latest version of the Standard (\kwd{CONTINUE} long-string keywords, blank header space, \kwd{CHECKSUM}, column limits, tiled image and table compression) or only briefly mentioned (keyword inheritance and Green Bank conventions) are described in Appendix~\ref{appregconv}, which also lists the corresponding affected sections of the Standard. After the approval by the IAUFWG in July 2016 the Standard was subjected to a thorough language editing (with no impact on the technical prescriptions) before the final issue in 2018. Details about the language editing changes are provided in Appendix~\ref{langedit}. The latest version of the Standard, as well as other information about the \FITS\ format, can be obtained from the \FITS\ Support Office website at \url{http://fits.gsfc.nasa.gov}. This website also contains the contact information for the Chairman of the IAUFWG, to whom any questions or comments regarding this Standard should be addressed. \subsection{Acknowledgments} The members of the three technical panels that produced this Standard are shown below. \begin{tabbing} {\bf First technical panel, 1990--1993} \\ Robert J. Hanisch (Chair) \= Space Telescope Science Inst.\\ Lee E. Brotzman \> Hughes STX \\ Edward Kemper \> Hughes STX \\ Barry M. Schlesinger \> Raytheon STX \\ Peter J. Teuben \> University of Maryland \\ Michael E. Van Steenberg \> NASA Goddard SFC \\ Wayne H. Warren Jr. \> Hughes STX \\ Richard A. White \> NASA Goddard SFC \\ \\ {\bf Second technical panel, 1994--1999} \\ Robert J. Hanisch (Chair) \> Space Telescope Science Inst.\\ Allen Farris \> Space Telescope Science Inst. \\ Eric W. Greisen \> National Radio Astr. Obs. \\ William D. Pence \> NASA Goddard SFC \\ Barry M. Schlesinger \> Raytheon STX \\ Peter J. Teuben \> University of Maryland \\ Randall W. Thompson \> Computer Sciences Corp. \\ Archibald Warnock \> A/WWW Enterprises \\ \\ {\bf Third technical panel, 2007} \\ William D. Pence (Chair) \> NASA Goddard SFC \\ Lucio Chiappetti \> IASF Milano, INAF, Italy \\ Clive G. Page \> University of Leicester, UK \\ Richard Shaw \> National Optical Astr. Obs. \\ Elizabeth Stobie \> University of Arizona \\ %LC \\ {\bf Dedicated task forces, 2013-2016} \\ % the Technical Group for long kwd names, character set etc. %\tbw{William D. Pence }\> \tbw{NASA Goddard SFC} \\ %\tbw{Lucio Chiappetti }\> \tbw{IASF Milano, INAF, Italy} \\ %\tbw{Malcolm J. Currie}\> \tbw{Joint Astronomy Centre} \\ %\tbw{Adam Dobrzycki }\> \tbw{European Southern Observatory} \\ %\tbw{Jessica Mink }\> \tbw{Harvard Smithsonian CfA} \\ %\tbw{Rob Seaman }\> \tbw{National Optical Astr. Obs.} \\ %\ Lucio Chiappetti \> IASF Milano, INAF, Italy \\ % conventions, supervising timing Steve Allen \> UCO Lick Observatory \\ % timing Adam Dobrzycki \> European Southern Observatory \\ % conventions William D. Pence~~~~~~ \> NASA Goddard SFC \\ % conventions Arnold Rots \> Harvard Smithsonian CfA \\ % timing Richard Shaw~~~~~~~ \> National Optical Astr. Obs. \\ % timing, conventions William T. Thompson \> NASA Goddard SFC \\ % conventions \\ {\bf Language editing, 2016-2018} \\ Malcolm J. Currie\> Rutherford Appleton Lab, UK\\ Lucio Chiappetti \> IASF Milano, INAF, Italy\\ \end{tabbing} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \ifiaufwgstyle %clearpage %raggedbottom %LC \fi \section{Definitions, acronyms, and symbols} \label{s:def} \subsection{Conventions used in this document} Terms or letters set in \texttt{Courier typeface} represent literal strings that appear in \FITS\ files. In the case of keyword names, such as `\indxkw{NAXIS}{n}', the lower-case letter represents a positive integer index number, generally in the range 1 to 999. The emphasized words \must, \shall, \should, \may, \recommended, \required, and \optional\ in this document are to be interpreted as described in IETF standard, RFC~2119 \citep{rfc2119}. \subsection{Defined terms} \begin{description} \item[\mbox{\texttt{\char`\ }}] Used to designate an ASCII space character. \item[\bf ANSI] American National Standards\index{ANSI} Institute. \item[\bf Array] A sequence of data values. This sequence corresponds to the elements in a rectilinear, $n$-dimensional matrix ($1 \leq n \leq 999$, or $n = 0$ in the case of a null array). \item[\bf Array value] The\index{array value} value of an element of an array in a \FITS\ file, without the application of the associated linear transformation to derive the physical\index{physical value} value. \item[\bf ASCII] American National Standard Code for Information Interchange. %\linebreak[1] Interchange. \item[\bf ASCII character] Any\index{ASCII character} member of the seven-bit ASCII character set. \item[\bf ASCII digit] One of the ten ASCII characters `0' through `9', which are represented by decimal character codes 48 through 57 (hexadecimal 30 through 39). \item[\bf ASCII NULL] The ASCII character\index{NULL, ASCII} that has all eight bits set to zero. \item[\bf ASCII space] The ASCII character for space, which is represented by decimal 32 (hexadecimal 20). \item[\bf ASCII text] The restricted set of ASCII characters\index{ASCII text} decimal 32 through 126 (hexadecimal 20 through 7E). \item[\bf Basic \textit{\textbf{FITS}}] The \FITS\ structure\index{FITS structure} consisting of the primary header\index{primary header} followed by a single primary\index{primary data array} data array. This is also known as Single Image \FITS\ (SIF), as opposed to Multi-Extension \FITS\ (MEF) files that contain one or more extensions following the primary HDU. \item[\bf Big endian] The numerical data format used in \FITS\ files in which the most-significant byte of the value is stored first followed by the remaining bytes in order of significance. \item[\bf Bit] A single binary digit. \item[\bf Byte] An ordered sequence of eight consecutive bits treated as a single entity. \item[\bf Card image] An obsolete term for an 80-character keyword record derived from the 80-column punched computer cards that were prevalent in the 1960s and 1970s. \item[\bf Character string] A sequence of one or more of the restricted set of ASCII-text characters, decimal 32 through 126 (hexadecimal 20 through 7E). \index{character string} \item[\bf Conforming extension] An extension whose keywords and organization\index{conforming extension} adhere to the requirements for conforming extensions defined in Sect.~\ref{s:genext} of this Standard.\index{extension, conforming} \item[\bf Data block] A 2880-byte \FITS\ block containing data described by the keywords in the associated header of that HDU. \item[\bf Deprecate] To express disapproval of. This term\index{deprecate} is used to refer to obsolete structures that \shouldnot\ be used in new \FITS\ files, but which \shall\ remain valid indefinitely. \item[\bf Entry] A single value in an ASCII-table or binary-table standard extension. \item[\bf Extension] A\index{extension} \FITS\ HDU appearing\index{HDU, extension} after the primary HDU in a \FITS\ file. \item[\bf Extension type name] The value of the \kwd{XTENSION} keyword\index{XTENSION}, used to identify the type\index{extension type name} of the extension. \item[\bf Field] A component of a larger entity, such as a keyword record or a row of an ASCII-table or binary-table standard extension. A field in a table-extension row consists of a set of zero-or-more table entries collectively described by a single format. \item[\bf File] A sequence of one or more records terminated by an end-of-file indicator appropriate to the medium. \item[\bf \textit{\textbf{FITS}}] Flexible Image Transport System. \item[\bf \textit{\textbf{FITS}} block] A sequence of 2880 eight-bit bytes aligned on 2880-byte boundaries in the \FITS\ file, most commonly either a header block or a data block. Special records are another infrequently used type of \FITS\ block. This block length was chosen because it is evenly divisible by the byte and word lengths of all known computer systems at the time \FITS\ was developed in 1979. \item[\bf \textit{\textbf{FITS}} file] A file with a format that conforms to the specifications in this document. \item[\bf \textit{\textbf{FITS}} structure] One\index{FITS structure} of the components of a \FITS\ file: the primary\index{HDU, primary} HDU, the random-groups\index{random groups} records, an extension\index{extension}, or, collectively, the special records\index{special records} following the last extension. \item[\bf \textit{\textbf{FITS}} Support Office] The \FITS\ information website that is maintained by the IAUFWG and is currently hosted at \url{http://fits.gsfc.nasa.gov}. \item[\bf Floating point] A computer representation of a real number. \item[\bf Fraction]The field of the mantissa (or significand) of a floating-point number that lies to the right of its implied binary point. \item[\bf Group parameter value] The\index{group parameter value} value of one of the parameters preceding a group in the random-groups structure, without the application of the associated linear transformation. \item[\bf HDU] Header and Data Unit. A data structure consisting of a header and the data the header describes. Note that an\index{HDU} HDU \may\ consist entirely of a header with no data blocks. \item[\bf Header] A series of keyword records organized within one or more header blocks that describes structures and/or data that follow it in the \FITS\ file. \item[\bf Header block] A 2880-byte \FITS\ block containing a sequence of thirty-six 80-character keyword records. \item[\bf Heap] The supplemental data area following the main data table in a\index{heap} binary-table standard extension. \item[\bf IAU] International Astronomical\index{IAU} Union. \item[\bf IAUFWG] \index{IAUFWG} International Astronomical Union \FITS\ Working Group. \item[\bf IEEE] Institute of Electrical and Electronic Engineers. \item[\bf IEEE NaN] IEEE Not-a-Number value; used to represent undefined floating-point values in \FITS\ arrays and binary tables. \item[\bf IEEE special values] Floating-point number byte patterns that have a special, reserved meaning, such as $-0$, $\pm \infty$, $\pm$underflow, $\pm$overflow, $\pm$denormalized, $\pm$NaN.\index{IEEE special values} (See Appendix~\ref{s:IEEE754}). \item[\bf Indexed keyword] A\index{keyword, indexed} keyword name that is of the form of a fixed root with an appended positive integer index number. \item[\bf Keyword name] The first eight bytes of a keyword record, which contain the ASCII name of a metadata quantity (unless it is blank). \item[\bf Keyword record] An 80-character record in a header block consisting of a keyword name in the first eight characters followed by an \optional\ value indicator, value, and comment string. The keyword record \shall\ be composed only of the restricted set of ASCII-text characters ranging from decimal 32 to 126 (hexadecimal 20 to 7E). \item[\bf Mandatory keyword] A\index{keyword, required} keyword that \must\ be used in all \FITS\ files or a keyword \required\ in conjunction with particular\index{FITS structure} \FITS\ structures. \item[\bf Mantissa] Also known as significand. The component of an IEEE floating-point number consisting of an explicit or implicit leading bit to the left of its implied binary point and a fraction field to the right. \item[\bf MEF] Multi-Extension \FITS, i.e., a \FITS\ file containing a primary HDU followed by one or more extension HDUs. \item[\bf NOST] NASA/Science Office of Standards and Technology. \item[\bf Physical value] The\index{physical value} value in physical units\index{units} represented by an element of an array and possibly derived from the array value\index{array value} using the associated, but \optional, linear transformation. \item[\bf Pixel] Short for `Picture element'; a single location within an array. \item[\bf Primary data array] The\index{primary data array} data array contained in the\index{HDU, primary} primary HDU. \item[\bf Primary HDU] The first HDU in a \FITS\ file. \item[\bf Primary header] The\index{primary header} first header in a \FITS\ file, containing information on the overall contents of the file (as well as on the primary data array, if present). \item[\bf Random Group] A \FITS\ structure consisting of a collection of `groups', where a group consists of a subarray of data and a set of associated parameter values. Random groups are deprecated for any\index{deprecate} use other than for radio interferometry data. \item[\bf Record] A sequence of bits treated as a single logical entity. \item[\bf Repeat count] The\index{repeat count} number of values represented in a field in a binary-table\index{binary table} standard extension. \item[\bf Reserved keyword] An\index{keyword, reserved} \optional\ keyword that \must\ be used only in the manner defined in this Standard. \item[\bf SIF] Single Image \FITS, i.e., a \FITS\ file containing only a primary HDU, without any extension HDUs. Also known as Basic \FITS. \item[\bf Special records] A series of one or more \FITS\ blocks following the last HDU \index{special records} whose internal structure does not otherwise conform to that for the primary HDU or to that specified for a conforming extension\index{conforming extension} in this Standard. Any use of special records requires approval from the IAU \FITS\ Working Group. \item[\bf Standard extension] A\index{standard extension} conforming\index{conforming extension} extension\index{extension, conforming} whose\index{extension, standard} header and data content are completely specified in Sect.~\ref{s:exts} of this Standard, namely, an image extension, an ASCII-table extension, or a binary-table extension. \end{description} \ifiaufwgstyle %LC %clearpage %LC %flushbottom %LC \fi %LC %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \section{\FITS\ file organization} \label{s:org} \subsection{Overall file structure} A \FITS\ file \shall\ be composed of the following \FITS\ structures\index{FITS structure}, in the order\index{order, FITS structures} listed: \begin{itemize} \item Primary header and data unit (HDU).\index{HDU, primary} \item Conforming Extensions\index{conforming extension} (\optional).\index{extension, conforming} \item Other special records (\optional, restricted).\index{special records} \end{itemize} \noindent A \FITS\ file composed of only the primary HDU is sometimes referred to as a Basic \FITS\ file, or a Single Image \FITS\ (SIF) file, and a \FITS\ file containing one or more extensions following the primary HDU is sometimes referred to as a Multi-Extension \FITS\ (MEF) file. Each \FITS\ structure\index{FITS structure} \shall\ consist of an integral number of \FITS\ blocks, which are each 2880 bytes (23040 bits) in length. The primary HDU\index{HDU, primary} \shall\ start with the first \FITS\ block of the \FITS\ file. The first \FITS\ block of each subsequent \FITS\ structure\index{FITS structure} \shall\ be the \FITS\ block immediately following the last \FITS\ block of the preceding \FITS\ structure. This Standard neither imposes a limit on the total size \index{file size} of a \FITS\ file, nor imposes a limit on the size of an individual HDU within a \FITS\ file. Software packages that read or write data according to this Standard could be limited, however, in the size of files that are supported. In particular, some software systems have historically only supported files up to $2^{31}$ bytes in size (approximately $2.1\times10^9$ bytes). \subsection {Individual \FITS\ Structures} The primary HDU and every extension\index{extension} HDU\index{HDU, extension} \shall\ consist of one or more 2880-byte header blocks immediately followed by an \optional\ sequence of associated 2880-byte data blocks. The header blocks \shall\ contain only the restricted set of ASCII-text\index{ASCII text} characters, decimal 32 through 126 (hexadecimal 20 through 7E). The ASCII control characters with decimal values less than 32 (including the null, tab, carriage return, and line-feed characters), and the delete character (decimal 127 or hexadecimal 7F) \mustnot\ appear anywhere within a header block. \subsection{Primary header and data unit} The first component of a \FITS\ file \shall\ be the primary HDU, which always contains the primary header and \may\ be followed by the primary data\index{primary data array} array. If the primary data array has zero length, as determined by the values of the \kwd{NAXIS} and\index{NAXIS} \indxkw{NAXIS}{n} keywords\index{NAXISn} in the primary header (Sect.~\ref{s:pman}), then the primary HDU \shall\ contain no data blocks. \subsubsection{Primary header} The header of a primary HDU\index{HDU, primary} \shall\ consist of one or more header blocks, each containing a series of 80-character keyword records\index{keyword record} containing only the restricted set of ASCII-text\index{ASCII text} characters. Each 2880-byte header block contains 36 keyword records. The last header block \must\ contain the \kwd{END} keyword (defined in Sect.~\ref{s:pman}), which marks the logical end of the header. Keyword records without information (e.g., following the \kwd{END} \index{END} keyword) \shall\ be filled\index{fill} with ASCII spaces (decimal 32 or hexadecimal 20). \subsubsection{Primary data array} The \label{s:pdata} primary\index{primary data array} data array, if present, \shall\ consist of a single data array with from 1 to 999~dimensions (as specified by the \kwd{NAXIS} keyword defined in Sect.~\ref{s:pman}). The random-groups convention in the primary data array is a more-complicated structure and is discussed separately in Sect.~\ref{s:Rgrp}. The entire array of data values are represented by a continuous stream of bits starting with the first bit of the first data block. Each data value \shall\ consist of a fixed number of bits that is determined by the value of the \kwd{BITPIX} keyword (Sect.~\ref{s:pman}). Arrays of more than one dimension \shall\ consist of a sequence such that the index along Axis~1 varies most rapidly, that along Axis~2 next most rapidly, and those along subsequent axes progressively less rapidly, with that along Axis~\texttt{m}, where \texttt{m} is the value of \kwd{NAXIS}\index{NAXIS}, varying least rapidly. There is no space or any other special character between the last value on a row or plane and the first value on the next row or plane of a multi-dimensional array. Except for the\index{array, multi-dimensional} location of the first element, the array structure is independent of the \FITS\ block structure. This storage order is shown schematically in Fig.~\ref{f:array} and is the same order as in multi-dimensional arrays in the Fortran \index{Fortran} programming language \citep{iso04}. The index count along each axis \shall\ begin with 1 and increment by 1 up to the value of the \indxkw{NAXIS}{n}\index{NAXISn} keyword (Sect.~\ref{s:pman}). \begin{figure}[t] \begin{center} \begin{tabular}{l} \\ A(1, 1, \ldots, 1), \\ A(2, 1, \ldots, 1), \\ \hspace{0.5in}\vdots, \\ A(\kwd{NAXIS1}, 1, \ldots, 1), \\ A(1, 2, \ldots, 1), \\ A(2, 2, \ldots, 1), \\ \hspace{0.5in}\vdots, \\ A(\kwd{NAXIS1}, 2, \ldots, 1), \\ \hspace{0.5in}\vdots, \\ A(1, \kwd{NAXIS2}, \ldots, \indxkw{NAXIS}{m}), \\ \hspace{0.5in}\vdots, \\ A(\kwd{NAXIS1}, \kwd{NAXIS2}, \ldots, \indxkw{NAXIS}{m}) \\ \end{tabular} \end{center} \caption[Array data sequence] {Arrays of more than one dimension \shall\ consist of a sequence such that the index along Axis~1 varies most rapidly and those along subsequent axes progressively less rapidly. } \label{f:array} \end{figure} If the data array does not fill the final data block, the remainder of the data block \shall\ be filled\index{fill} by setting all bits to zero. The individual data values \shall\ be stored \index{byte order} \index{order, byte} in big-endian byte order such that the byte containing the most-significant bits of the value appears first in the \FITS\ file, followed by the remaining bytes, if any, in decreasing order of significance. \subsection{Extensions} \subsubsection{Requirements for conforming extensions} \label{s:genext} All extensions\index{extension}, whether or not further described in this Standard, \shall\ fulfill the following requirements to be in conformance with this \FITS\ Standard. New extension types \should\ be created only when the organization of the information is such that it cannot be handled by one of the existing extension types. A \FITS\ file that contains extensions is commonly referred to as a multi-extension \FITS\ (MEF) file. \paragraph{3.4.1.1. Identity} \label{s:idy} \ \newline \ \newline Each extension\index{conforming extension} type\index{extension, conforming} \shall\ have a unique type name, specified in the\index{extension type name} header by the \kwd{XTENSION} keyword (Sect.~\ref{s:conf}). To preclude conflict, extension type names \must\ be registered\index{extension registration} with the\index{IAUFWG} IAUFWG\@. The current list of registered extensions is given in Appendix~\ref{s:resname}. An up-to-date list is also maintained on the \FITS\ Support Office website. \paragraph{3.4.1.2. Size specification} \ \newline \ \newline The total number of bits in the data of each extension \shall\ be specified in the header for that extension, in the manner prescribed in Sect.~\ref{s:conf}. \subsubsection{Standard extensions} A standard\index{standard extension} extension\index{extension, standard} is a conforming\index{conforming extension} extension\index{extension, conforming} whose organization and content are completely specified in Sect.~\ref{s:exts} of this Standard. Only one extension format \shall\ be approved for each type of data organization. \subsubsection{Order of extensions} An extension \may\ follow the primary HDU\index{HDU, primary} or another conforming\index{conforming extension} extension\index{extension, conforming}. Standard\index{standard extension} extensions\index{extension, standard} and other conforming extensions \may\ appear in any order\index{order, extensions} in a \FITS\ file. \subsection{Special records (restricted use)} Special records are 2880-byte \FITS\ blocks following the last HDU of the \FITS\ file that have an unspecified structure that does not meet the requirements of a conforming extension. The first eight bytes of the special records \mustnot\ contain\index{special records} the string\index{XTENSION} `\verb+XTENSION+'. It is \recommended\ that they do not contain the string\index{SIMPLE} `\verb*+SIMPLE +'. The contents of special records are not otherwise specified by this Standard. Special records were originally designed as a way for the \FITS\ format to evolve by allowing new \FITS\ structures to be implemented. Following the development of conforming extensions, which provide a general mechanism for storing different types of data structures in \FITS\ format in a well defined manner, the need for other new types of \FITS\ data structures has been greatly reduced. Consequently, further use of special records is restricted and requires the approval of the IAU \FITS\ Working Group.\index{IAUFWG} \subsection{Physical blocking} \label{s:PhysBlk} \subsubsection{Bit-stream devices} \label{s:BitDev} For bit-stream devices, including but not restricted to logical file systems, \FITS\ files \shall\ be interpreted as a sequence of one or more 2880-byte \FITS\ blocks,\index{blocking} regardless of the physical blocking structure of the underlying recording media. When writing a \FITS\ file on media with a physical block size unequal to the 2880-byte \FITS\ block length, any bytes remaining in the last physical block following the end of the {\textit FITS} file \should\ be set to zero. Similarly, when reading \FITS\ files on such media, any bytes remaining in the last physical block following the end of the \FITS\ file \shall\ be disregarded. \subsubsection{Sequential media} The \FITS\ format was originally developed for writing files on sequential magnetic-tape\index{magnetic tape} devices. The following rules on how to write to sequential media \citep{grosbol94} are now irrelevant to most current data-storage devices. If physically possible, \FITS\ files \shall\ be written on sequential media in blocks that are from one to ten integer multiples of 2880 bytes in length. If this is not possible, the \FITS\ file \shall\ be written as a bit stream using the native block size of the sequential device. Any bytes remaining in the last block following the end of the \FITS\ file \shall\ be set to zero. When reading \FITS\ files on sequential media, any files shorter than 2880 bytes in length (e.g., ANSI tape labels) are not considered part of the \FITS\ files and \should\ be disregarded. \subsection{Restrictions on changes} \label{s:Restrict} Any structure that is a valid \FITS\ structure\index{FITS structure} \shall\ remain a valid \FITS\ structure at all future times. Use of certain valid \FITS\ structures \may\ be deprecated\index{deprecate} by this or future \FITS\ Standard documents. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% %clearpage %LC \section{Headers} \label{s:head} The first two sections of this chapter define the structure and content of header keyword records. Sect.~\ref{s:Units} offers recommendations on how physical units should be expressed. The final section defines the mandatory and reserved keywords for primary arrays and conforming extensions. \subsection{Keyword records} \subsubsection{Syntax} \label{s:keysyntax} Each 80-character header keyword record\index{keyword record} \shall\ consist of a keyword name, a value indicator (only \required\ if a value is present), an \optional\ value, and an \optional\ comment. Keywords \may\ appear in any order except where specifically stated otherwise\index{order, keyword} in this Standard. It is \recommended\ that the order of the keywords in \FITS\ files be preserved during data processing operations because the designers of the \FITS\ file may have used conventions that attach particular significance to the order of certain keywords (e.g., by grouping sequences of \kwd{COMMENT} keywords\index{COMMENT} at specific locations in the header, or appending \kwd{HISTORY} keywords\index{HISTORY} in chronological order of the data processing steps %. %LC %begin{brotext} or using \kwd{CONTINUE} keywords\index{CONTINUE} to generate long-string keyword values).%end{brotext} A formal syntax, giving a complete definition of the syntax of \FITS\ keyword records, is given in Appendix~\ref{s:FormSyn}. It is intended as an aid in interpreting the text defining the Standard. %LC %begin{brotext} In earlier versions of this Standard a \FITS\ keyword, assumed as an item whose value is to be looked up by name (and presumably assigned to a variable) by a \FITS-reading program, was associated one to one to a single header keyword record. With the introduction of continued (long-string) keywords (see Sect.~\ref{s:ffch}.2), such \FITS\ keywords \may\ span more than one header keyword record, and the value \shall\ be created by concatenation as explained in Sect.~\ref{s:ffch}.2. %end{brotext} \subsubsection{Components} \paragraph{4.1.2.1. Keyword name (Bytes~1 through 8)} \label{s:keyw} \ \newline \ \newline The keyword name \shall\ be a left justified, eight-character, space-filled, ASCII\index{fill} string with no embedded spaces. All digits 0 through 9 (decimal ASCII codes 48 to 57, or hexadecimal 30 to 39) and upper case\index{case sensitivity} Latin alphabetic characters\index{keyword, valid characters} \texttt{'A'} through \texttt{'Z'} (decimal 65 to 90 or hexadecimal 41 to 5A) are permitted; lower-case characters \shallnot\ be used. The underscore\index{underscore} (\texttt{'\_'}, decimal 95 or hexadecimal 5F) and hyphen\index{hyphen} (\texttt{'-'}, decimal 45 or hexadecimal 2D) are also permitted. No other characters are permitted.\footnote{This requirement differs from the wording in the original \FITS\ papers. See Appendix~\ref{s:changes}.} For indexed\index{keyword, indexed} keyword names that have a single positive integer index counter appended to the root name, the counter \shallnot\ have leading zeros (e.g., \kwd{NAXIS1}, not \kwd{NAXIS001}). Note that keyword names that begin with (or consist solely of) any combination of hyphens, underscores, and digits are legal. %LC %% FOR THE FUTURE %% \TBW{add here about long keyword names ? \ \newline \ \newline} \paragraph{4.1.2.2. Value indicator (Bytes~9 and 10)} \label{s:ValInd} \ \newline \ \newline If the two ASCII characters \verb*+'= '+ (decimal 61 followed by decimal 32) are present in Bytes~9 and 10 of the keyword record, this indicates that the keyword has a value\index{value} field associated with it, unless it is one of the commentary keywords\index{keyword, commentary} defined in Sect.~\ref{s:comk} (i.e., a \kwd{HISTORY},\index{HISTORY} \kwd{COMMENT},\index{COMMENT} or completely blank keyword name), which, by definition, have no value. \paragraph{4.1.2.3. Value/comment (Bytes~11 through 80)} \label{s:valcomm} \ \newline \ \newline In keyword records that contain the value indicator in Bytes~9 and 10, the remaining Bytes~11 through 80 of the record \shall\ contain the value,\index{value} if any, of the keyword, followed by \optional\ comments. In keyword records without a value indicator, Bytes~9 through 80 \should\ be interpreted as commentary text, however, this does not preclude conventions that interpret the content of these bytes in other ways. The value field, when present, \shall\ contain the ASCII-text representation of a literal string constant, a logical constant, or a numerical constant, in the format specified in Sect.~\ref{s:valC}. The value field \may\ be a null field; i.e., it \may\ consist entirely of spaces, in which case the value associated with the keyword is\index{value, undefined} undefined. The mandatory \FITS\ keywords\index{keyword, mandatory} defined in this Standard \mustnot\ appear more than once within a header. All other keywords that have a value \shouldnot\ appear more than once. If a keyword does appear multiple times with different values, then the value is indeterminate. If a comment follows the value field, it \must\ be preceded by a slash (\texttt{'/'}, decimal 47 or hexadecimal 2F).\footnotemark[3] A space between the value and the slash\index{slash} is strongly \recommended. The comment \may\ contain any of the restricted set of ASCII-text\index{ASCII text} characters, decimal 32 through 126 (hexadecimal 20 through 7E). The ASCII control characters with decimal values less than 32 (including the null, tab, carriage return, and line-feed characters), and the delete character (decimal 127 or hexadecimal 7F) \mustnot\ appear anywhere within a keyword record. \subsection{Value} \label{s:valC} The structure of the value\index{value} field depends on the data type of the value. The value field represents a single value and not an array of values.\footnotemark[3] The value field \must\ be in one of two formats: fixed\index{format, fixed} or free\index{format, free}. The fixed-format is \required\ for values of mandatory\index{keyword, mandatory} keywords\index{format, keywords} and is \recommended\ for values of all other keywords. %LC \subsubsection{Character string} \label{s:ffch} %LC %begin{brotext} \paragraph{\ref{s:ffch}.1 Single-record string keywords} \paragraph{} %end{brotext} A character-string value \index{character string} \shall\ be composed only of the set of restricted ASCII-text\index{ASCII text} characters, decimal 32 through 126 (hexadecimal 20 through 7E) enclosed by single-quote characters (``\keyv{'}'', decimal 39, hexadecimal 27). A single quote is represented within a string as two successive single quotes, e.g., O'HARA = \keyv{\textquotesingle O\textquotesingle\textquotesingle HARA\textquotesingle}. Leading spaces are significant; trailing spaces are not. This Standard imposes no requirements on the case sensitivity\index{case sensitivity} of character\index{character string} string values unless explicitly stated in the definition of specific keywords. If the value is a fixed-format character string, the starting single-quote character \must\ be in Byte~11 of the keyword record and the closing single quote \must\ occur in or before Byte~80. Earlier versions of this Standard also \required\ that fixed-format characters strings \must\ be padded with space characters to at least a length of eight characters so that the closing quote character does not occur before Byte~20. This minimum character-string length is no longer \required, except for the value of the \kwd{XTENSION} keyword (e.g., {\verb*+'IMAGE '+} and {\verb*+'TABLE '+}; see Sect.~\ref{s:exts}), which \must\ be padded to a length of eight characters for backward compatibility with previous usage. Free-format\index{format, free} character strings follow the same rules as fixed-format character strings except that the starting single-quote character \may\ occur after Byte~11. Any bytes preceding the starting quote character and after Byte~10 \must\ contain the space character. Note that there is a subtle distinction between the following three keywords. \begin{verbatim} KEYWORD1= '' / null string keyword KEYWORD2= ' ' / empty string keyword KEYWORD3= / undefined keyword \end{verbatim} \noindent The value of \kwd{KEYWORD1} is a null, or zero-length string whereas the value of the \kwd{KEYWORD2} is an empty string (nominally a single space character because the first space in the string is significant, but trailing spaces are not). The value of \kwd{KEYWORD3} is undefined\index{value, undefined} and has an indeterminate data type as well, except in cases where the data type of the specified keyword is explicitly defined in this Standard. %LC The maximum length of a string value %begin{brotext} that can be represented on a single keyword record %end{brotext} is 68 characters, with the opening and closing quote characters in Bytes~11 and 80, respectively. In general, no length limit fewer than 68 is implied for character-valued keywords. %begin{brotext} Whenever a keyword value is declared `string' or said to `contain a character string', the length limits in this section apply. The next section applies when the value is declared `long-string'. %end{brotext} %LC Bill start %begin{brotext} \paragraph{\ref{s:ffch}.2 Continued string (long-string) keywords} \paragraph{} Earlier versions of this Standard only defined single-record string keywords as described in the previous section. The Standard now incorporates a convention (originally developed for use in \FITS\ files from high-energy astrophysics missions) for continuing arbitrarily long string values over a potentially unlimited sequence of multiple consecutive keyword records\index{CONTINUE} using the following procedure. \begin{enumerate} \item Divide the long-string value into a sequence of smaller substrings, each of which contains fewer than 68 characters. (Note that if the string contains any literal single-quote characters, then these \must\ be represented as a pair of single-quote characters in the \FITS-keyword value, and these two characters \must\ both be contained within a single substring). \item Append an ampersand character (\keyv{'\&'}) to the end of each substring, except for the last substring. This character serves as a flag to \FITS-reading software that this string value \may\ be continued on the following keyword in the header. \item Enclose each substring with single-quote characters. Non-significant space characters \may\ occur between the ampersand character and the closing quote character. \item Write the first substring as the value of the specified keyword. \item Write each subsequent substring, in order, to a series of keywords that all have the reserved keyword name \kwd{CONTINUE} (see Sect.~\ref{s:resk}) in Bytes~1 through 8, and have space characters in Bytes~9 and 10 of the keyword record. The substring \may\ be located anywhere in Bytes~11 through 80 of the keyword record and \may\ be preceded by non-significant space characters starting in Byte~11. A comment string \may\ follow the substring; if present, the comment string \must\ be separated from the substring by a forward-slash character (\keyv{'/'}). Also, it is {\em strongly recommended} that the slash character be preceded by a space character. \end{enumerate} The \kwd{CONTINUE} keyword \mustnot\ be used with of any of the mandatory or reserved keywords defined in this Standard unless explicitly declared of type long-string. The following keyword records illustrate a string value that is continued over multiple keyword records. (Note: the length of the substrings have been reduced to fit within the page layout.) \begin{verbatim} WEATHER = 'Partly cloudy during the evening f&' CONTINUE 'ollowed by cloudy skies overnight.&' CONTINUE ' Low 21C. Winds NNE at 5 to 10 mph.' \end{verbatim} If needed, additional space for the keyword comment field can be generated by continuing the string value with one or more null strings, as illustrated schematically below. \begin{verbatim} STRKEY = 'This keyword value is continued &' CONTINUE ' over multiple keyword records.&' CONTINUE '&' / The comment field for this CONTINUE '&' / keyword is also continued CONTINUE '' / over multiple records. \end{verbatim} \FITS-reading software can reconstruct the long-string value by following an inverse procedure of checking if the string value ends with the \keyv{'\&'} character and is immediately followed by a conforming \kwd{CONTINUE} keyword record. If both conditions are true, then concatenate the substring from the \kwd{CONTINUE} record onto the previous substring after first deleting the trailing \keyv{'\&'} character. Repeat these steps until all subsequent \kwd{CONTINUE} records have been processed. Note that if a string value ends with the \keyv{'\&'} character, but is not immediately followed by a \kwd{CONTINUE} keyword that conforms to all the previously described requirements, then the \keyv{'\&'} character \should\ be interpreted as the literal last character in the string. Also, any `orphaned' \kwd{CONTINUE} keyword records (formally not invalidating the \FITS\ file, although likely representing an error with respect to what the author of the file meant) \should\ be interpreted as containing commentary text in Bytes~9--80 (similar to a \kwd{COMMENT} keyword). %end{brotext} %LC Bill end %clearpage %LC \subsubsection{Logical} \label{s:ffl} If the value is a fixed-format logical constant, it \shall\ appear as an upper-case \keyv{T} or \keyv{F} in\index{logical value} Byte~30. A logical value is represented in free-format\index{format, free} by a single character consisting of an upper-case \keyv{T} or \keyv{F} as the first non-space character in Bytes~11 through 80. \subsubsection{Integer number} \label{s:ffi} If the value is a fixed-format integer, the ASCII representation \shall\ be right-justified in Bytes~11 through 30. An integer consists of a \keyv{'+'} (decimal 43 or hexadecimal 2B) or \keyv{'-'} (decimal 45 or hexadecimal 2D) sign, followed by one or more contiguous ASCII digits (decimal 48 to 57 or hexadecimal 30 to 39), with no embedded spaces. The leading \keyv{'+'} sign\index{sign character} is \optional. Leading zeros are permitted, but are not significant. The integer representation \shall\ always be interpreted as a signed, decimal number. This Standard does not limit the range of an integer keyword value, however, software packages that read or write data according to this Standard could be limited in the range of values that are supported (e.g., to the range that can be represented by a 32-bit or 64-bit signed binary integer). A free-format\index{format, free} integer value follows the same rules as fixed-format integers except that the ASCII representation \may\ occur anywhere within Bytes~11 through 80. \subsubsection{Real floating-point number} \label{s:ffrfp} If the value is a fixed-format real floating-point number, the ASCII\index{floating-point} representation \shall\ be right-justified in Bytes~11 through 30. A floating-point number is represented by a decimal number followed by an \optional\ exponent, with no embedded spaces. A decimal number \shall\ consist of a \keyv{'+'} (decimal 43 or hexadecimal 2B) or \keyv{'-'} (decimal 45 or hexadecimal 2D) sign, followed by a sequence of ASCII digits containing a single decimal point (\keyv{'.'}), representing an integer part and a fractional part of the floating-point number. The leading \keyv{'+'} sign\index{sign character} is \optional. At least one of the integer part or fractional part \must\ be present. If the fractional part is present, the decimal point \must\ also be present. If only the integer part is present, the decimal point \may\ be omitted, in which case the floating-point number is indistinguishable from an integer. The exponent, if present, consists of an exponent letter followed by an integer. Letters in the exponential form (\keyv{'E'} or \keyv{'D'})\footnote{The \keyv{'D'} exponent form is traditionally used when representing values that have more decimals of precision or a larger magnitude than can be represented by a single-precision 32-bit floating-point number, but otherwise there is no distinction between \keyv{'E'} or \keyv{'D'}.} \shall\ be upper case. The full precision of 64-bit values cannot be expressed over the whole range of values using the fixed-format. This Standard neither imposes an upper limit on the number of digits of precision, nor any limit on the range of floating-point keyword values. Software packages that read or write data according to this Standard could be limited, however, in the range of values and exponents that are supported (e.g., to the range that can be represented by a 32-bit or 64-bit floating-point number). A free-format\index{format, free} floating-point value follows the same rules as a fixed-format floating-point value except that the ASCII representation \may\ occur anywhere within Bytes~11 through 80. % Table 3 \begin{table} \centering \caption{IAU-recommended basic units.} \label{ta:IAUunit} \begin{tabular}{llll} \hline \hline Quantity & Unit & Meaning & Notes \\ \hline \noalign{\smallskip} % \multicolumn{4}{l}{\textit{SI base \& supplementary units}} \\ length & \verb+m+ & meter & \\ mass & \verb+kg+ & kilogram & \verb+g+ gram allowed\\ time & \verb+s+ & second & \\ plane angle & \verb+rad+ & radian & \\ solid angle & \verb+sr+ & steradian & \\ temperature & \verb+K+ & kelvin & \\ electric current & \verb+A+ & ampere & \\ amount of substance & \verb+mol+ & mole & \\ luminous intensity & \verb+cd+ & candela & \\ & & & \\ \multicolumn{4}{l}{\textit{IAU-recognized derived units}} \\ frequency & \verb+Hz+ & hertz & s$^{-1}$ \\ energy & \verb+J+ & joule & N m \\ power & \verb+W+ & watt & J s$^{-1}$ \\ electric potential & \verb+V+ & volt & J C$^{-1}$ \\ force & \verb+N+ & newton & kg m s$^{-2}$ \\ pressure, stress & \verb+Pa+ & pascal & N m$^{-2}$ \\ electric charge & \verb+C+ & coulomb & A s \\ electric resistance & \verb+Ohm+ & ohm & V A$^{-1}$\\ electric conductance & \verb+S+ & siemens & A V$^{-1}$ \\ electric capacitance & \verb+F+ & farad & C V$^{-1}$ \\ magnetic flux & \verb+Wb+ & weber & V s \\ magnetic flux density & \verb+T+ & tesla & Wb m$^{-2}$ \\ inductance & \verb+H+ & henry & Wb A$^{-1}$ \\ luminous flux & \verb+lm+ & lumen & cd sr \\ illuminance & \verb+lx+ & lux & lm m$^{-2}$ \\ \noalign{\smallskip} \hline \end{tabular} \end{table} % Table 4 \begin{table*} \renewcommand{\arraystretch}{.8} \tabcolsep 1mm \caption[Additional allowed units.]{Additional allowed units.} \begin{center} \protect\begin{tabular}{lclll} \hline \hline \multicolumn{2}{l}{Quantity} & \multicolumn{1}{l}{Unit} & \multicolumn{1}{l}{Meaning\rule[0mm]{0mm}{3mm}} & \multicolumn{1}{l}{Notes} \\ \hline \noalign{\smallskip} \rule{0mm}{3mm} plane angle & & \verb+deg+ & degree of arc & $\pi/180$ rad \\ & & \verb+arcmin+ & minute of arc & $1/60$ deg \\ & & \verb+arcsec+ & second of arc & $1/3600$ deg \\ & & \verb+mas+ & milli-second of arc & $1/3\,600\,000$ deg \\ time & & \verb+min+ & minute & 60 s \\ & & \verb+h+ & hour & 60 min = 3600 s \\ & & \verb+d+ & day & $86\,400$ s\\ & $\dag$ & \verb+a+ & year (Julian) & $31\,557\,600$ s ~(365.25 d), peta a(\verb+Pa+) forbidden\\ & $\dag$ & \verb+yr+ & year (Julian) & \verb+a+ is IAU-style \\ energy$^*$ & $\dag$ & \verb+eV+ & electron volt & $1.6021765\times10^{-19}$ J \\ & $\ddag$ & \verb+erg+ & erg & $10^{-7}$ J \\ & & \verb+Ry+ & rydberg & $\frac{1}{2}\left(\frac{2\pi e^2}{hc}\right)^2 m_ec^2 = 13.605692 $ eV \\ mass$^*$ & &\verb+solMass+ & solar mass & $1.9891\times10^{30}$ kg \\ & &\verb+u+ & unified atomic mass unit & $1.6605387\times10^{-27}$ kg \\ luminosity & & \verb+solLum+ & Solar luminosity & $3.8268\times10^{26}$ W \\ length & $\ddag$ & \verb+Angstrom+ & angstrom & $10^{-10}$ m \\ & & \verb+solRad+ & Solar radius & $6.9599\times10^8$ m \\ & & \verb+AU+ & astronomical unit & $1.49598\times10^{11}$ m \\ & & \verb+lyr+ & light year & $9.460730\times10^{15}$ m \\ & $\dag$ & \verb+pc+ & parsec & $3.0857\times10^{16}$ m \\ events & & \verb+count+ & count & \\ & & \verb+ct+ & count & \\ & & \verb+photon+ & photon & \\ & & \verb+ph+ & photon & \\ flux density & $\dag$ & \verb+Jy+ & jansky & $10^{-26}$ W m$^{-2}$ Hz$^{-1}$ \\ & $\dag$ & \verb+mag+ & (stellar) magnitude & \\ & $\dag$ & \verb+R+ & rayleigh & $10^{10}/(4\pi)$ photons\, m$^{-2}$\, s$^{-1}$\, sr$^{-1}$ \\ magnetic field &$\dag\ddag$ & \verb+G+ & gauss & $10^{-4}$ T \\ area & & \verb+pixel+ & (image/detector) pixel & \\ & & \verb+pix+ & (image/detector) pixel & \\ &$\dag\ddag$ & \verb+barn+ & barn & $10^{-28}$ m$^{2}$ \\ & & & & \\ \multicolumn{5}{l}{\textit{Miscellaneous units}\rule[-2mm]{0mm}{5mm}} \\ & & \verb+D+ & debye & $\frac{1}{3}\times 10^{-29}$ C.m \\ & & \verb+Sun+ & relative to Sun & e.g., abundances \\ & & \verb+chan+ & (detector) channel & \\ & & \verb+bin+ & numerous applications & (including the one-dimensional analog of pixel) \\ & & \verb+voxel+ & three-dimensional analog of pixel & \\ & $\dag$ & \verb+bit+ & binary information unit & \\ & $\dag$ & \verb+byte+ & (computer) byte & eight bits \\ & & \verb+adu+ & Analog-to-digital converter & \\ & & \verb+beam+ & beam area of observation & as in Jy/beam \\ \noalign{\smallskip} \hline \end{tabular} \end{center} %\tablefoot{ } {\bf Notes.} $^{(\dag)}$Addition of prefixes for decimal multiples and submultiples are allowed. $^{(\ddag)}$Deprecated \index{deprecate} in IAU Style Manual \citep{mcnally88} but still in use. $^{(*)}$Conversion factors from CODATA Internationally recommended values of the fundamental physical constants 2002 (\url{http://physics.nist.gov/cuu/Constants/}). \vspace{10pt} \label{ta:extunit} \end{table*} \subsubsection{Complex integer number} \label{s:ffci} There is no fixed-format for complex integer numbers.\footnote{This requirement differs from the wording in the original \FITS\ papers. See Appendix~\ref{s:changes}.} \index{integer, complex} \index{complex data} If the value is a complex integer number, the value \must\ be represented as a real part and an imaginary part, separated by a comma and enclosed in parentheses e.g., \keyv{(123, 45)}. Spaces \may\ precede and follow the real and imaginary parts. The real and imaginary parts are represented in the same way as integers (Sect.~\ref{s:ffi}). Such a representation is regarded as a single value for the complex integer number. This representation \may\ be located anywhere within Bytes~11 through 80. \subsubsection{Complex floating-point number} \label{s:ffcfp} There is no fixed-format for complex floating-point numbers.\footnotemark[5] If the value is a complex floating-point number, the value \must\ be represented as a real part and an \index{floating-point, complex} imaginary part, \index{complex data} separated by a comma and enclosed in parentheses, e.g., \keyv{(123.23, -45.7)}. Spaces \may\ precede and follow the real and imaginary parts. The real and imaginary parts are represented in the same way as floating-point values (Sect.~\ref{s:ffrfp}). Such a representation is regarded as a single value for the complex floating-point number. This representation \may\ be located anywhere within Bytes~11 through 80. %LC \subsubsection{Date} \label{s:wcsdate} % \begin{redtext} There is strictly no such thing as a data type for {\em date valued} keywords, however a pseudo data type of {\em datetime} is defined in Sect.~\ref{iso8601} and \must\ be used to write ISO-8601 {\em datetime} strings as character strings. If a keyword needs to express a {\em time} in JD or MJD (see Sect.~\ref{sect:timeReps}), this can be formatted as an arbitrary precision number, % \begin{redtext} %LC post vote optionally % \end{redtext} %LC post vote separating the integer and fractional part as specified in Sect.~\ref{trefval}. % \end{redtext} \subsection{Units} \label{s:Units} When a numerical keyword value represents a physical quantity, it is \recommended\ that units be provided. Units \shall\ be represented with a string of characters composed of the restricted ASCII-text character set. Unit strings can be used as values of keywords (e.g., for the reserved keywords \kwd{BUNIT}, and \indxkw{TUNIT}{n}), as an entry in a character-string column of an ASCII-table or binary-table extension, or as part of a keyword comment string (see Sect.~\ref{s:ucomment}, below). The units\index{units} of all \FITS\ header keyword values, with the exception of measurements of angles,\index{angular units} \should\ conform with the recommendations in the IAU Style Manual\index{IAU Style Manual} \citep{mcnally88}. For angular measurements given as floating-point values and specified with reserved keywords, the units \should\ be degrees (i.e., \texttt{deg}). If a requirement exists within this Standard for the units of a keyword, then those units \must\ be used. The units\index{units} for fundamental physical quantities recommended by the IAU are given in Table~\ref{ta:IAUunit}. Table~\ref{ta:extunit} lists additional units that are commonly used in astronomy. %\begin{redtext} Further specifications for time units are given in Sect.~\ref{sect:timeUnit}. %\end{redtext} %LC The recommended plain-text form for the IAU-recognized \textit{base units} are given in Column~2 of both tables.\footnote{These tables are reproduced from the first in a series of papers on world-coordinate systems \citep{greisen02}, which provides examples and expanded discussion.} % All base units strings \may\ be preceded, with no intervening spaces, by a single character (two for deca) taken from Table~\ref{ta:mulunit} and representing scale factors mostly in steps of $10^3$. Compound prefixes (e.g.,~\keyv{ZYeV} for $10^{45}$ eV) \mustnot\ be used. \subsubsection{Construction of units strings} Compound units\index{units} strings \may\ be formed by combining strings of base units (including prefixes, if any) with the recommended syntax described in Table~\ref{ta:cmpunit}. Two or more base units strings (called \texttt{str1} and \texttt{str2} in Table~\ref{ta:cmpunit}) \may\ be combined using the restricted set of (explicit or implicit) operators that provide for multiplication, division, exponentiation, raising arguments to powers, or taking the logarithm or square-root of an argument. % Note that functions such as \texttt{log} actually require dimensionless arguments, so that \texttt{log(Hz)}, for example, actually means \texttt{log(\textit{x}/1~Hz)}. The final units string is the compound string, or a compound of compounds, preceded by an \optional\ numeric multiplier of the form \texttt{10**\textit{k}}, \texttt{10\^}\textit{k}, or \texttt{10}$\pm k$ where \textit{k} is an integer, {\em optionally} surrounded by parentheses with the sign character \required\ in the third form in the absence of parentheses. Creators of \FITS\ files are encouraged to use the numeric multiplier only when the available standard scale factors of Table~\ref{ta:mulunit} will not suffice. Parentheses are used for symbol grouping and are strongly \recommended\ whenever the order of operations might be subject to misinterpretation. A space character implies multiplication, which can also be conveyed explicitly with an asterisk or a period. % % It seems dumb to include "blank" as a valid operator, and only to discourage its use! Therefore, although spaces are allowed as symbol separators, their use is discouraged. %Two examples are \texttt{'10**(46)erg/s'} and \texttt{'sqrt(erg/pixel/s/GHz)'}. Note that, per IAU convention, case is significant \index{case sensitivity} throughout. The IAU style manual\index{IAU Style Manual} forbids the use of more than one slash\index{slash} (\texttt{'/'}) character in a units string. However, since normal mathematical precedence rules apply in this context, more than one slash \may\ be used but is discouraged. % Nevertheless authors might wish to consider whether, e.g., \texttt{'sqrt(erg/(pixel.s.GHz))'} % might be more readable than \texttt{'sqrt(erg/pixel/s/GHz)'}. A unit\index{units} raised to a power is indicated by the unit string followed, with no intervening spaces, by the \optional\ symbols \verb+**+ or \verb+^+ followed by the power given as a numeric expression, called \texttt{expr} in Table~\ref{ta:cmpunit}. The power \may\ be a simple integer, with or without sign, {\em optionally} surrounded by parentheses. It \may\ also be a decimal number (e.g., \keyv{1.5}, \keyv{0.5}) or a ratio of two integers (e.g., \keyv{7/9}), with or without sign, which \must\ be surrounded by parentheses. Thus meters squared \may\ be indicated by \keyv{m**(2)}, \keyv{m**+2}, \keyv{m+2}, \keyv{m2}, \keyv{m\char`\^2}, \keyv{m\char`\^(+2)}, etc.~and per meter cubed \may\ be indicated by \keyv{m**-3}, \keyv{m-3}, \keyv{m\char`\^(-3)}, \keyv{/m3}, and so forth. Meters to the three-halves power \may\ be indicated by \keyv{m(1.5)}, \keyv{m\char`\^(1.5)}, \keyv{m**(1.5)}, \keyv{m(3/2)}, \keyv{m**(3/2)}, and \keyv{m\char`\^(3/2)}, but \textit{not} by \keyv{m\char`\^^3/2} or \keyv{m1.5}. \subsubsection{Units in comment fields} \label{s:ucomment} If the units of the keyword value are specified in the comment of the header keyword, it is \recommended\ that the units string be enclosed in square brackets (i.e., enclosed by `\keyv{[}' and `\keyv{]}') at the beginning of the comment field, separated from the\index{slash} slash (\keyv{'/'}) comment field delimiter by a single space character. An example, using a non-standard keyword, is \\ \texttt{EXPTIME = 1200. / [s] exposure time in seconds} \\ This widespread, but \optional, practice suggests that square brackets \should\ be used in comment fields only for this purpose. Nonetheless, software \shouldnot\ depend on units being expressed in this fashion within a keyword comment, and software \shouldnot\ depend on any string within square brackets in a comment field containing a proper units\index{units} string. % Table 5 \begin{table} \centering \caption{Prefixes for multiples and submultiples.} \label{ta:mulunit} \begin{tabular}{llcllc} \hline \hline Submult & Prefix & Char & Mult & Prefix & Char \\ % \hline \noalign{\smallskip} $10^{-1}$ & deci & \verb+d+ &$10$ & deca & \verb+da+ \\ $10^{-2}$ & centi & \verb+c+ &$10^{2}$ & hecto & \verb+h+ \\ $10^{-3}$ & milli & \verb+m+ &$10^{3}$ & kilo & \verb+k+ \\ $10^{-6}$ & micro & \verb+u+ &$10^{6}$ & mega & \verb+M+ \\ $10^{-9}$ & nano & \verb+n+ &$10^{9}$ & giga & \verb+G+ \\ $10^{-12}$ & pico & \verb+p+ &$10^{12}$ & tera & \verb+T+ \\ $10^{-15}$ & femto & \verb+f+ &$10^{15}$ & peta & \verb+P+ \\ $10^{-18}$ & atto & \verb+a+ &$10^{18}$ & exa & \verb+E+ \\ $10^{-21}$ & zepto & \verb+z+ &$10^{21}$ & zetta & \verb+Z+ \\ $10^{-24}$ & yocto & \verb+y+ &$10^{24}$ & yotta & \verb+Y+ \\ \noalign{\smallskip} \hline \end{tabular} \end{table} % Table 6 \begin{table} \centering \caption{Characters and strings allowed to denote mathematical operations.} \label{ta:cmpunit} \begin{tabular}{ll} \hline \hline String & Meaning \\ \hline \noalign{\smallskip} % \verb+str1 str2+\rule{0mm}{4mm} & Multiplication \\ \verb+str1*str2+ & Multiplication \\ \verb+str1.str2+ & Multiplication \\ \verb+str1/str2+ & Division \\ \verb+str1**expr+ & Raised to the power \verb+expr+ \\ \verb+str1^expr+ & Raised to the power \verb+expr+ \\ \verb+str1expr+ & Raised to the power \verb+expr+ \\ \verb+log(str1)+ & Common Logarithm (to base 10) \\ \verb+ln(str1)+ & Natural Logarithm \\ \verb+exp(str1)+ & Exponential ($e^{\verb+str1+}$) \\ \verb+sqrt(str1)+\rule[-2mm]{0mm}{3mm} & Square root \\ \noalign{\smallskip} \hline \end{tabular} \end{table} % Table 7 \begin{table} \centering \caption{Mandatory keywords for primary header.} \label{t:hdr1} \begin{tabular}{cl} \hline \hline Position & Keyword \\ \hline \noalign{\smallskip} 1 & \kwd{SIMPLE} = \keyv{T} \\ 2 & \kwd{BITPIX} \\ 3 & \kwd{NAXIS} \\ 4 & \indxkw{NAXIS}{n}, $n$ = 1, \ldots, \kwd{NAXIS} \\ & \vdots \\ & (other keywords) \\ & \vdots \\ last & \kwd{END} \\ \noalign{\smallskip} \hline \end{tabular} \end{table} % Table 8 \begin{table} \centering \caption{Interpretation of valid \kwd{BITPIX} value.} \label{t:bitpix} \begin{tabular}{rl} \hline \hline Value & Data represented \\ \hline \noalign{\smallskip} \keyv{8} & Character or unsigned binary integer \\ \keyv{16} & 16-bit two's complement binary integer \\ \keyv{32} & 32-bit two's complement binary integer \\ \keyv{64} & 64-bit two's complement binary integer \\ \keyv{$-$32} & IEEE single-precision floating point \\ \keyv{$-$64} & IEEE double-precision floating point \\ \noalign{\smallskip} \hline \end{tabular} \end{table} % \ \newline \ \newline \ \newline \ \newline \ \newline \ \newline \ \newline \ \newline % \ \newline \ \newline \ \newline \ \newline % \clearpage \subsection{Keywords} \label{s:key} \subsubsection{Mandatory keywords} Mandatory\index{keyword, mandatory} keywords are \required\ \index{keyword, required} in every HDU as described in the remainder of this subsection. They \must\ be used only as described in this Standard. \label{s:man} Values of the mandatory keywords \must\ be written in fixed-format. \paragraph{4.4.1.1. Primary header} \label{s:keyprime} \ \newline \ \newline The \kwd{SIMPLE} keyword\index{SIMPLE} is \required\ to be the first keyword in\index{primary header} the primary header of all \FITS\ files. The primary header \must\ contain the other mandatory keywords shown in Table~\ref{t:hdr1} in the order\index{keyword, order}\index{order, keyword} given. \label{s:pman} Other keywords \mustnot\ intervene between the \kwd{SIMPLE} keyword and the last \indxkw{NAXIS}{n} keyword. \paragraph{\kwd{SIMPLE} keyword.} The value field \shall\ contain a logical constant with the value \keyv{T} if the file conforms to this Standard. This keyword is mandatory for the primary header and \mustnot\ appear in extension headers.\footnote{This requirement differs from the wording in the original \FITS\ papers. See Appendix~\ref{s:changes}.} A value of \keyv{F} signifies that the file does not conform to this Standard. \index{SIMPLE} \paragraph{\kwd{BITPIX} keyword.} The value field \shall\ contain an integer. The\index{BITPIX} absolute value is used in computing the sizes of data structures. It \shall\ specify the number of bits that represent a data value in the associated data array. The only valid values of \kwd{BITPIX} are given in Table~\ref{t:bitpix}. Writers of \FITS\ arrays \should\ select a \kwd{BITPIX} data type appropriate to the form, range of values, and accuracy of the data in the array. \paragraph{\kwd{NAXIS} keyword.} The value field \shall\ contain a non-negative integer no greater than 999 representing the number of axes in the associated data\index{NAXIS} array. A value of zero signifies that no data follow the header in the\index{HDU} HDU. \paragraph{\indxkw{NAXIS}{n} keywords.} \label{s:naxisn} The \indxkw{NAXIS}{n} keywords \must\ be present for all values $n = 1$, \ldots, \kwd{NAXIS}, in increasing order of $n$, and for no other values of $n$. The value field of this indexed keyword\index{keyword, indexed} \shall\ contain a non-negative integer representing the number of elements along Axis~$n$ of a data array. A value of zero for any of the \indxkw{NAXIS}{n} signifies that no data follow the header in the\index{HDU} HDU (however, the random-groups structure described in Sect.~\ref{s:Rgrp} has \kwd{NAXIS1}~=~\keyv{0}, but will have data following the header if the other \indxkw{NAXIS}{n} keywords are non-zero). If \kwd{NAXIS} is equal to \keyv{0}, there \shallnot\ be any\index{NAXISn} \indxkw{NAXIS}{n} keywords. \paragraph{\kwd{END} keyword.} This keyword has no associated value. Bytes~9 through 80\index{END} \shall\ be filled\index{fill} with ASCII spaces (decimal 32 or hexadecimal 20). The \kwd{END} keyword marks the logical end of the header and \must\ occur in the last 2880-byte \FITS\ block of the header. \vspace{3mm} The total number of bits in the primary data array, exclusive of fill that is needed after the data to complete the last 2880-byte data block (Sect.~\ref{s:pdata}), is given by the\index{array size} following expression: \begin{eqnarray} \mbox{$N_\mathrm{bits}$} &=& |\mbox{\kwd{BITPIX}}| \times (\mbox{\kwd{NAXIS1}} \times \mbox{\kwd{NAXIS2}} \times \cdots \times \mbox{\indxkw{NAXIS}{m}}), \label{eq:prnbit} \end{eqnarray} \noindent where $N_\mathrm{bits}$ \must\ be\index{$N_\mathrm{bits}$} non-negative and is the number of bits excluding fill, \texttt{m} is the value\index{NAXIS} of \kwd{NAXIS}, and\index{BITPIX} \kwd{BITPIX} and\index{NAXISn} the \indxkw{NAXIS}{n} represent the values associated with those keywords. Note that the random-groups convention in the primary array has a more-complicated structure whose size is given by Eq.~\ref{eq:rdmgsz}. The header of the first \FITS\ extension in the file, if present, \shall\ start with the first \FITS\ block following the data block that contains the last bit of the primary data array. An example of a primary array header is shown in Table~\ref{t:simphdr}. In addition to the required keywords, it includes a few of the reserved keywords that are discussed in Sect.~\ref{s:resk}. % Table 9 \begin{table*} \centering \caption{Example of a primary array header.} \label{t:simphdr} \begin{tabular}{l} \hline \hline Keyword records \\ \hline \noalign{\smallskip} {\verb+SIMPLE = T / file does conform to FITS Standard+} \\ {\verb+BITPIX = 16 / number of bits per data pixel+} \\ {\verb+NAXIS = 2 / number of data axes+} \\ {\verb+NAXIS1 = 250 / length of data axis 1+} \\ {\verb+NAXIS2 = 300 / length of data axis 2+} \\ {\verb+OBJECT = 'Cygnus X-1'+} \\ {\verb+DATE = '2006-10-22'+} \\ {\verb+END+} \\ \noalign{\smallskip} \hline \end{tabular} \end{table*} \paragraph{4.4.1.2. Conforming extensions} \label{s:conf} \ \newline \ \newline All conforming extensions, whether or not further specified in this Standard, \must\ use the keywords\index{keyword, required} defined in Table~\ref{t:hdr2} in the order\index{order, keyword}\index{keyword, order} specified. Other keywords \mustnot\ intervene between the \kwd{XTENSION} keyword and the \kwd{GCOUNT} keyword. The \kwd{BITPIX}, \kwd{NAXIS}, \indxkw{NAXIS}{n}, and \kwd{END} keywords are defined in Sect.~\ref{s:pman}. \paragraph{\kwd{XTENSION} keyword.} The value field \shall\ contain a character string giving\index{XTENSION} the name\index{extension type name} of the extension type. This keyword is mandatory for an extension header and \mustnot\ appear in the primary header\index{primary header}.\footnotemark[7] To preclude conflict, extension type names \must\ be registered\index{extension registration} with the\index{IAUFWG} IAUFWG\@. The current list of registered extensions is given in Appendix~\ref{s:resname}. An up-to-date list is also maintained on the \FITS\ Support Office website. \paragraph{\kwd{PCOUNT} keyword.} The value field \shall\ contain an integer that \shall\ be\index{PCOUNT} used in any way appropriate to define the data structure, consistent with Eq.~\ref{eq:extbit}. In \IMAGE\ (Sect.~\ref{s:image}) and \TABLE\ (Sect.~\ref{s:ATabl}) extensions this keyword \must\ have the value \keyv{0}; in \BINTABLE\ extensions (Sect.~\ref{s:BTabl}) it is used to specify the number of bytes that follow the main data table in the supplemental data area called the heap. \index{heap} This keyword is also used in the random-groups structure (Sect.~\ref{s:Rgrp}) to specify the number of parameters preceding each array in a group. \paragraph{\kwd{GCOUNT} keyword.} The value field \shall\ contain an integer that \shall\ be\index{GCOUNT} used in any way appropriate to define the data structure, consistent with Eq.~\ref{eq:extbit}. This keyword \must\ have the value \keyv{1} in the \IMAGE, \TABLE, and \BINTABLE\ standard extensions defined in Sect.~\ref{s:exts}. This keyword is also used in the random-groups structure (Sect.~\ref{s:Rgrp}) to specify the number of random groups present. The total number of bits in the extension data array (exclusive of fill that is needed after the data to complete the last 2880-byte data block) is given by the\index{array size} following expression: \begin{eqnarray} \mbox{$N_\mathrm{bits}$} &=& |\mbox{\kwd{BITPIX}}| \times \label{eq:extbit} \mbox{\kwd{GCOUNT}} \times \nonumber \\ & & (\mbox{\kwd{PCOUNT}} + \mbox{\kwd{NAXIS1}} \times \mbox{\kwd{NAXIS2}} \times \cdots \times \mbox{\indxkw{NAXIS}{m}}), \end{eqnarray} \noindent where $N_\mathrm{bits}$ \must\ be\index{$N_\mathrm{bits}$} non-negative and is the number of bits excluding fill; \texttt{m} is the value\index{NAXIS} of \kwd{NAXIS}; and\index{BITPIX} \kwd{BITPIX}, \kwd{GCOUNT}, \kwd{PCOUNT}, and\index{NAXISn} the \indxkw{NAXIS}{n} represent\index{PCOUNT} the\index{GCOUNT} values associated with those keywords. If $N_\mathrm{bits} > 0$, then the data array \shall\ be contained in an integral number of 2880-byte \FITS\ data blocks. The header of the next \FITS\ extension in the file, if any, \shall\ start with the first \FITS\ block following the data block that contains the last bit of the current extension data array. \subsubsection{Other reserved keywords} \label{s:resk} The reserved keywords\index{keyword, reserved} described below are \optional, but if present in the header they \must\ be used only as defined in this Standard. They apply to any \FITS\ structure\index{FITS structure} with the meanings and restrictions defined below. Any \FITS\ structure \may\ further restrict the use of these keywords. \paragraph{4.4.2.1. General descriptive keywords} \label{s:dhist} \paragraph{\kwd{DATE} keyword.} The value field \shall\ contain a character string\index{DATE} giving the date on which the HDU was created,\index{time} in the form \keyv{YYYY-MM-DD}, or the date and time when the HDU was created, in the form \keyv{YYYY-MM-DDThh:mm:ss}[\keyv{.sss}\ldots], where \keyv{YYYY} \shall\ be the four-digit calendar year number, \keyv{MM} the two-digit month number with January given by 01 and December by 12, and \keyv{DD} the two-digit day of the month. When both date and time are given, the literal \keyv{T} \shall\ separate the date and time, \keyv{hh} \shall\ be the two-digit hour in the day, \keyv{mm} the two-digit number of minutes after the hour, and \keyv{ss}[\texttt{.sss}\ldots] the number of seconds (two digits followed by an \optional\ fraction) after the minute. Default values \mustnot\ be given to any portion of the date/time string, and leading zeros \mustnot\ be omitted. The decimal part of the seconds field is \optional\ and \may\ be arbitrarily long, so long as it is consistent with the rules for value formats of Sect.~\ref{s:valC}. %LC %\begin{redtext} Otherwise said, the format for \kwd{DATE} keywords written after January 1, 2000 \shall\ be the ISO-8601 {\em datetime} form described in Sect.~\ref{iso8601}. See also Sect.~\ref{sect:GlobalTime}. %\end{redtext} The value of the \kwd{DATE} keyword \shall\ always be expressed in UTC when in this format, for all data sets created on Earth. The following format \may\ appear on files written before January 1, 2000. The value\index{value} field contains a character string giving the date on which the HDU was created, in the form \keyv{DD/MM/YY}, where \keyv{DD} is the day of the month, \keyv{MM} the month number with January given by 01 and December by 12, and \keyv{YY} the last two digits of the year, the first two digits being understood to be 19. Specification of the date using Universal Time\index{time, universal} is \recommended\ but not assumed. When a newly created HDU is substantially a verbatim copy of another HDU, the value of the \kwd{DATE} keyword in the original HDU \may\ be retained in the new HDU instead of updating the value to the current date and time. % Table 10 \begin{table} \centering \caption{Mandatory keywords in conforming extensions.} \label{t:hdr2} \begin{tabular}{cl} \hline \hline Position & Keyword \\ \hline \noalign{\smallskip} 1 & \kwd{XTENSION} \\ 2 & \kwd{BITPIX} \\ 3 & \kwd{NAXIS} \\ 4 & \indxkw{NAXIS}{n}, $n$ = 1, \ldots, \kwd{NAXIS} \\ 5 & \kwd{PCOUNT} \\ 6 & \kwd{GCOUNT} \\ & \vdots \\ & (other keywords) \\ & \vdots \\ last & \kwd{END} \\ \noalign{\smallskip} \hline \end{tabular} \end{table} \paragraph{\kwd{ORIGIN} keyword.} The value field \shall\ contain a character string\index{ORIGIN} identifying the organization or institution responsible for creating the \FITS\ file. \paragraph{\kwd{EXTEND} keyword.} \label{s:ext} The value field \shall\ contain a logical value\index{EXTEND} indicating whether the \FITS\ file is allowed to contain conforming extensions following the primary HDU. This keyword \may\ only appear in the primary header and \mustnot\ appear in an extension header. If the value field is \keyv{T} then there \may\ be conforming extensions in the \FITS\ file following the primary HDU. This keyword is only advisory, so its presence with a value \keyv{T} does not require that the \FITS\ file contains extensions, nor does the absence of this keyword necessarily imply that the file does not contain extensions. Earlier versions of this Standard stated that the \kwd{EXTEND} keyword \must\ be present in the primary header if the file contained extensions, but this is no longer \required. \paragraph{\kwd{BLOCKED} keyword.} This keyword is deprecated\index{deprecate} and \shouldnot\ be used in new \FITS\ files. It is reserved primarily to prevent its use with other meanings. As previously defined, this keyword, if used, was \required\ to appear only within the first 36 keywords in the primary \label{s:block} header. Its presence with the \required\ logical value of \keyv{T} advised that the physical block size of the \FITS\ file on which it appears \may\ be an integral multiple of the \FITS\ block length and not necessarily equal to it. \paragraph{4.4.2.2. Keywords describing observations} \label{s:kobs} \paragraph{\kwd{DATE-OBS} keyword.} The format of the value field for \kwd{DATE-OBS} keywords \shall\index{DATE-OBS} follow the prescriptions for the \kwd{DATE} keyword (Sect.~\ref{s:dhist} %LC %\begin{redtext} and Sect.~\ref{iso8601} %\end{redtext}). Either the four-digit year format or the two-digit year format \may\ be used for observation dates from 1900 through 1999, although the four-digit format is \recommended. When the format with a four-digit year is used, the default interpretations for\index{time} time \should\ be UTC for dates beginning 1972-01-01 and UT before. Other date and time scales are permissible. The value of the \kwd{DATE-OBS} keyword \shall\ be expressed in the principal time system or time scale of the HDU to which it belongs; if there is any chance of ambiguity, the choice \should\ be clarified in comments. The value of \kwd{DATE-OBS} \shall\ be assumed to refer to the start of an observation, unless another interpretation is clearly explained in the comment field. Explicit specification of the time scale is \recommended. By default, times for TAI and times that run simultaneously with TAI, e.g., UTC and TT, will be assumed to be as measured at the detector (or, in practical cases, at the observatory). For coordinate times such as TCG, TCB, and TDB, the default \shall\ be to include light-time corrections to the associated spatial origin, namely the geocenter for TCG and the Solar System barycenter for the other two. Conventions \may\ be developed that use other time systems. %LC %appendix B of 3.0 did not contain the agreement (older version relic) %Appendix~\ref{s:tsys} %of this document contains the appendix to the agreement %on a four-digit year, which discusses time systems in some detail. %\begin{redtext} Time scales are now discussed in detail in Sect.~\ref{sect:timeScale} and Table~\ref{table:timescale}. %\end{redtext} When the value of \kwd{DATE-OBS} is expressed in the two-digit year form, allowed for files written before January 1, 2000 with a year in the range 1900--1999, there is no default assumption as to whether it refers to the start, middle or end of an observation. \paragraph{\kwd{DATExxxx} keywords.} The value fields for all keywords beginning with the string \kwd{DATE} whose value contains date, and {\em optionally} time,\index{time} information \shall\index{DATExxxx} follow the prescriptions for the \kwd{DATE-OBS} keyword. %LC %\begin{redtext} See also Sect.~\ref{iso8601} for the {\em datetime} format, and Sect.~\ref{sect:GlobalTime} for further global time keywords specified by the Standard. %\end{redtext} \paragraph{\kwd{TELESCOP} keyword.} The value field \shall\ contain a character string\index{TELESCOP} identifying the telescope used to acquire the data associated with the header. \paragraph{\kwd{INSTRUME} keyword.} The value field \shall\ contain a character string\index{INSTRUME} identifying the instrument used to acquire the data associated with the header. \paragraph{\kwd{OBSERVER} keyword.} The value field \shall\ contain a character string\index{OBSERVER} identifying who acquired the data associated with the header. \paragraph{\kwd{OBJECT} keyword.} The value field \shall\ contain a character string\index{OBJECT} giving a name for the object observed. \paragraph{4.4.2.3. Bibliographic keywords} \label{s:bibkeywords} \paragraph{\kwd{AUTHOR} keyword.} The value field \shall\ contain a character string\index{AUTHOR} identifying who compiled the information in the data associated with the header. This keyword is appropriate when the data originate in a published paper or are compiled from many sources. \paragraph{\kwd{REFERENC} keyword.} The value field \shall\ contain a character string\index{REFERENC} citing a reference where the data associated with the header are published. It is \recommended\ that either the 19-digit bibliographic identifier\footnote{This bibliographic convention \citep{schmitz95} was initially developed for use within NED (NASA/IPAC Extragalactic Database) and SIMBAD (operated at CDS, Strasbourg, France).} used in the Astrophysics Data System bibliographic databases (\url{http://adswww.harvard.edu/}) or the Digital Object Identifier (\url{http://doi.org}) be included in the value string, when available (e.g., \keyv{'1994A\&AS..103..135A'} or \keyv{'doi:10.1006/jmbi.1998.2354'}). %clearpage %LC \paragraph{4.4.2.4. Commentary keywords} \label{s:comk} \paragraph{} These keywords provide commentary information about the contents or history of the \FITS\ file and \may\ occur any number of times in a header. These\index{keyword, commentary} keywords \shall\ have no associated value even if the value indicator characters \verb*+`= '+ appear in Bytes~9 and 10 (hence it is \recommended\ that these keywords not contain the value indicator). Bytes~9 through 80 \may\ contain any of the restricted set of ASCII-text\index{ASCII text} characters, decimal 32 through 126 (hexadecimal 20 through 7E). %LC %begin{brotext} In earlier versions of this Standard continued string keywords (see Sect.~\ref{s:ffch}.2) could be handled as commentary keywords if the relevant convention was not supported. Now \kwd{CONTINUE} keywords \shall\ be honoured as specified in Sect.~\ref{s:ffch}.2. %end{brotext} \paragraph{\kwd{COMMENT} keyword.} This keyword \may\ be used\index{COMMENT} to supply any comments regarding the \FITS\ file. \paragraph{\kwd{HISTORY} keyword.} This keyword \should\ be used\index{HISTORY} to describe the history of steps and procedures associated with the processing of the associated data. \paragraph{Keyword field is blank.} This keyword \may\ be used to supply any comments regarding the \FITS\ file. It is frequently used for aesthetic purposes to provide a break between groups of related keywords in the header. %LC Bill start %begin{fuxtext} %clearpage % provisional separation from CONTINUE \paragraph{} A sequence of one or more entirely blank keyword records (consisting of 80 ASCII space characters) that immediately precede the \kwd{END} keyword \may\ be interpreted as non-significant fill space that \may\ be overwritten when new keywords are appended to the header. This usage convention enables an arbitrarily large amount of header space to be preallocated\index{header space, preallocation} when the \FITS\ HDU is first created, which can help mitigate the potentially time-consuming alternative of having to shift all the following data in the file by 2880 bytes to make room for a new \FITS\ header block each time space is needed for a new keyword. %end{fuxtext} %LC Bill end %clearpage %LC \paragraph{4.4.2.5. Keywords that describe arrays} \label{s:array} \ \newline \ \newline These keywords are used to describe the contents of an array, either in the primary array, in an \IMAGE\ extension (Sect.~\ref{s:image}), or in a series of random\index{random-groups} groups (Sect.~\ref{s:Rgrp}). They are \optional, but if they appear in the header describing an array or groups, they \must\ be used as defined in this section of this Standard. They \shallnot\ be used in headers describing other structures unless the meaning is the same as defined here. \paragraph{\kwd{BSCALE} keyword.} This keyword \shall\ be \index{BSCALE} used, along with the \kwd{BZERO} keyword, to linearly scale the array pixel values (i.e., the actual values stored in the \FITS\ file) to transform them into the physical\index{physical value} values that they represent using Eq.~\ref{eq:bscl}. \begin{eqnarray} \mbox{physical\_value} & = & \mbox{\kwd{BZERO}} + \mbox{\kwd{BSCALE}} \times \mbox{array\_value}. \label{eq:bscl} \end{eqnarray} The value field \shall\ contain a floating-point number representing the coefficient of the linear term in the scaling equation, the ratio of physical value to array value\index{array value} at zero offset. The default value for this keyword is \keyv{1.0}. Before support for IEEE floating-point data types was added to \FITS\ \citep{wells90}, this technique of linearly scaling integer values was the only way to represent the full range of floating-point values in a \FITS\ array. This linear scaling technique is still commonly used to reduce the size of the data array by a factor of two by representing 32-bit floating-point physical values as 16-bit scaled integers. \paragraph{\kwd{BZERO} keyword.} This keyword \shall\ be used, along with the \kwd{BSCALE} keyword, to linearly scale the array pixel values (i.e., the actual values stored in the \FITS\ file) to transform them into the physical\index{physical value} values that they represent using Eq.~\ref{eq:bscl}. The value field \shall\ contain a floating-point number representing the physical value corresponding to an array value of zero. The default value for this keyword is \keyv{0.0}. Besides its use in representing floating-point values as scaled integers (see the description of the \kwd{BSCALE} keyword), the \kwd{BZERO} keyword is also used when storing unsigned-integer values in the \FITS\ array. In this special case the \kwd{BSCALE} keyword \shall\ have the default value of \keyv{1.0}, and the \kwd{BZERO} keyword \shall\ have one of the integer values shown in Table~\ref{t:unsig1}. % Table 11 \begin{table*} \centering \caption{Usage of \kwd{BZERO} to represent non-default integer data types.} \label{t:unsig1} \begin{tabular}{rccrl} \hline \hline \kwd{BITPIX} & Native & Physical & \kwd{BZERO} & \\ & data type & data type & & \\ \hline \noalign{\smallskip} \keyv{8} & unsigned & signed byte & \keyv{-128} & ($-2^{7}$) \\ \keyv{16} & signed & unsigned 16-bit & \keyv{32768} & ($2^{15}$) \\ \keyv{32} & signed & unsigned 32-bit & \keyv{2147483648} & ($2^{31}$) \\ \keyv{64} & signed & unsigned 64-bit & \keyv{9223372036854775808} & ($2^{63}$) \\ \noalign{\smallskip} \hline \end{tabular} \end{table*} Since the \FITS\ format does not support a native unsigned\index{integer, unsigned} integer data type (except for the unsigned eight-bit byte data type), the unsigned values are stored in the \FITS\ array as native signed integers with the appropriate integer offset specified by the \kwd{BZERO} keyword value shown in the table. For the byte data type, the converse technique can be used to store signed byte values as native unsigned values with the negative \kwd{BZERO} offset. In each case, the physical value is computed by adding the offset specified by the \kwd{BZERO} keyword to the native data type value that is stored in the \FITS\ file.\footnote{A more computationally efficient method of adding or subtracting the \kwd{BZERO} values is to simply flip the most-significant bit of the binary value. For example, using eight-bit integers, the decimal value 248 minus the \kwd{BZERO} value of \keyv{128} equals 120. The binary representation of 248 is 11111000. Flipping the most-significant bit gives the binary value 01111000, which is equal to decimal 120.} \paragraph{\kwd{BUNIT} keyword.} The value field \shall\ contain a character string\index{BUNIT} describing the physical units\index{units} in which the quantities in the array, after application\index{BSCALE} of \kwd{BSCALE} and \kwd{BZERO}, are\index{BZERO} expressed. These units \must\ follow the prescriptions of Sect.~\ref{s:Units}. \paragraph{\kwd{BLANK} keyword.} This keyword \shall\ be used only in headers with\index{BLANK} positive values of\index{BITPIX} \kwd{BITPIX} (i.e., in arrays with integer data). Bytes~1 through 8 contain the string \verb*+`BLANK '+ (ASCII spaces in Bytes~6 through 8). The value field \shall\ contain an integer that specifies the value that is used within the integer array to represent pixels that have an\index{value, undefined} undefined\index{physical value} physical value. If the \kwd{BSCALE} and \kwd{BZERO} keywords\index{BSCALE} do\index{BZERO} not have the default values of \keyv{1.0} and \keyv{0.0}, respectively, then the value of the \kwd{BLANK} keyword \must\ equal the actual value in the \FITS\ data array that is used to represent an undefined pixel and not the corresponding physical value (computed from Eq.~\ref{eq:bscl}). To cite a specific, common example, {\em unsigned} 16-bit integers are represented in a {\em signed} integer \FITS\ array (with \kwd{BITPIX}~=~\keyv{16}) by setting \kwd{BZERO}~=~\keyv{32768} and \kwd{BSCALE}~=~\keyv{1}. If it is desired to use pixels that have an {\em unsigned} value (i.e., the physical value) equal to 0 to represent undefined pixels in the array, then the \kwd{BLANK} keyword \must\ be set to the value \keyv{-32768} because that is the actual value of the undefined pixels in the \FITS\ array. \paragraph{\kwd{DATAMAX} keyword.} The value field \shall\ always contain a floating-point\index{DATAMAX} number, regardless of the value of \kwd{BITPIX}. This\index{BITPIX} number \shall\ give the maximum valid physical value\index{physical value} represented by the array (from Eq.~\ref{eq:bscl}), exclusive of any\index{IEEE special values} IEEE special values. \paragraph{\kwd{DATAMIN} keyword.} The value field \shall\ always contain a floating-point\index{DATAMIN} number, regardless of the value of \kwd{BITPIX}. This number \shall\ give the minimum valid physical value represented by the array (from Eq.~\ref{eq:bscl}), exclusive of any IEEE special values. \paragraph{WCS keywords.} An extensive set of keywords have been defined to describe the world coordinates associated with an array. These keywords are discussed separately in Sect.~\ref{s:WCS}. %clearpage %LC for britext \paragraph{4.4.2.6. Extension keywords} \label{s:extkwd} \ \newline \ \newline %Although these The next three %LC keywords were originally defined for use within\index{extension} the header of a conforming extension, however %LC they also \may\ appear in the primary header with an analogous meaning. If these keywords are present, it is \recommended\ that they have a unique combination of values in each HDU of the \FITS\ file. \paragraph{\kwd{EXTNAME} keyword.} The value field \shall\ contain a character string to be\index{EXTNAME} used to distinguish\index{extension type name} among different extensions of the same\index{XTENSION} type, i.e., with the same value of \kwd{XTENSION}, in a \FITS\ file. Within this context, the primary array \should\ be considered as equivalent to an \IMAGE\ extension. \paragraph{\kwd{EXTVER} keyword.} The value field \shall\ contain an integer to be used to\index{EXTVER} distinguish among different extensions in a \FITS\ file with the same type and name, i.e., the same values for \kwd{XTENSION} and \kwd{EXTNAME}. The values need not start with \keyv{1} for the first extension with a particular value of \kwd{EXTNAME} and need not be in sequence for subsequent values. If the \kwd{EXTVER} keyword is absent, the file \should\ be treated as if the value were \keyv{1}. \paragraph{\kwd{EXTLEVEL} keyword.} The value field \shall\ contain an integer specifying the\index{EXTLEVEL} level in a hierarchy of extension levels of the extension header containing it. The value \shall\ be \keyv{1} for the highest level; levels with a higher value of this keyword \shall\ be subordinate to levels with a lower value. If the \kwd{EXTLEVEL} keyword is absent, the file \should\ be treated as if the value were \keyv{1}. %LC % saved self=contained text in inherit.tex before shortening here and moving % bulk of this to appendix K %begin{britext} \ \newline \ \newline The following keyword is \optional, but is {\em reserved} for use by the convention described in Appendix~\ref{ap:inherit}. If present it \shall\ appear in the extension header immediately after the mandatory keywords, and be used as described in the appendix. \paragraph{\kwd{INHERIT} keyword.} \index{INHERIT} The value field \shall\ contain a logical value of \keyv{T} or \keyv{F} to indicate whether or not the current extension should inherit the keywords in the primary header of the \FITS\ file. %end{britext} %LC %clearpage %LC %LC Bill %begin{magtext} \paragraph{\ref{s:resk}.7 Data-integrity keywords}\index{checksum} \paragraph{} The two keywords described here provide an integrity check on the information contained in \FITS\ HDUs. \paragraph{\kwd{DATASUM} keyword.} The value field of the \kwd{DATASUM} keyword \shall\ consist of a character string that \should\ contain the unsigned-integer value of the 32-bit ones' complement checksum of the data records in the HDU (i.e., excluding the header records). For this purpose, each 2880-byte \FITS\ logical record \should\ be interpreted as consisting of 720 32-bit unsigned integers. The four bytes in each integer \must\ be interpreted in order of decreasing significance where the most-significant byte is first, and the least-significant byte is last. Accumulate the sum of these integers using ones' complement arithmetic in which any overflow of the most-significant bit is propagated back into the least-significant bit of the sum. The \kwd{DATASUM} value is expressed as a character string (i.e., enclosed in single-quote characters) because support for the full range of 32-bit unsigned-integer keyword values is problematic in some software systems. This string \may\ be padded with non-significant leading or trailing blank characters or leading zeros. A string containing only one or more consecutive ASCII blanks \may\ be used to represent an undefined or unknown value for the \kwd{DATASUM} keyword. The \kwd{DATASUM} keyword \may\ be omitted in HDUs that have no data records, but it is preferable to include the keyword with a value of \keyv{0}. Otherwise, a missing \kwd{DATASUM} keyword asserts no knowledge of the checksum of the data records. Recording in the comment field the ISO-8601-formatted Datetime \citep{iso04b} when the value of this keyword record is created or updated is \recommended. \paragraph{\kwd{CHECKSUM} keyword.} The value field of the \kwd{CHECKSUM} keyword \shall\ consist of an ASCII character string whose value forces the 32-bit ones' complement checksum accumulated over the entire \FITS\ HDU to equal negative 0. (Note that ones's complement arithmetic has both positive and negative zero elements). %There are a vast number of possible character strings that could %satisfy this requirement, but for the sake of consistency and %uniformity It is \recommended\ that the particular 16-character string generated by the algorithm described in Appendix~\ref{ap:checksum} be used. A string containing only one or more consecutive ASCII blanks \may\ be used to represent an undefined or unknown value for the \kwd{CHECKSUM} keyword. The \kwd{CHECKSUM} keyword value \must\ be expressed in fixed format, when the algorithm in Appendix~\ref{ap:checksum} is used, otherwise the usage of fixed format is \recommended. Recording in the comment field the ISO-8601-formatted Datetime when the value of this keyword record is created or updated is \recommended. % what about DATASUM ? If the \kwd{CHECKSUM} keyword exists in the header of the HDU and the accumulated checksum is not equal to \keyv{$-$0}, or if the \kwd{DATASUM} keyword exists in the header of the HDU and its value does not match the data checksum, then this provides a strong indication that the content of the HDU has changed subsequent to the time that the respective keyword value was computed. Such an invalid checksum may indicate corruption during a prior file copy or transfer operation, or a corruption of the physical media on which the file was stored. It may alternatively reflect an intentional change to the data file by subsequent data processing if the \kwd{CHECKSUM} value was not also updated. \paragraph{} Normally both keywords will be present in the header if either is present, but this is not \required. These keywords apply {\em only} to the HDU in which they are contained. If these keywords are written in one HDU of a multi-HDU \FITS\ file then it is {\em strongly recommended} that they also be written to every other HDU in the file with values appropriate to each HDU in turn; in that case the checksum accumulated over the entire file will equal $-$0 as well. The \kwd{DATASUM} keyword \must\ be updated before the \kwd{CHECKSUM} keyword. In general updating the two checksum keywords \should\ be the final step of any update to either data or header records in a \FITS\ HDU. It is highly \recommended\ that if a \FITS\ file is intended for public distribution, then the checksum keywords, if present, \should\ contain valid values. %end{magtext} \subsubsection{Additional keywords} New keywords\index{keyword, new} \may\ be devised in addition to those described in this Standard, so long as they are consistent with the generalized rules for keywords and do not conflict with mandatory or reserved keywords.\index{keyword, new} Any keyword that refers to or depends upon the existence of other specific HDUs in the same or other files \should\ be used with caution because the persistence of those HDUs cannot always be guaranteed. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% %clearpage %LC %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \section{Data representation} \label{s:Drep} Primary and extension\index{extension} data \shall\ be represented in one of the\index{format, data} formats described in this section. \FITS\ data \shall\ be interpreted to be a byte stream. Bytes are in big-endian order\index{byte order}\index{order, byte} of decreasing significance. The byte that includes the sign bit\index{sign bit} \shall\ be first, and the byte that has the ones bit \shall\ be last. \subsection{Characters} Each character \shall\ be represented by\index{ASCII character} one byte. A character \shall\ be represented by its seven-bit ASCII \citep{ansi77} code in the low-order seven bits in the byte. The high-order bit \shall\ be zero. \subsection{Integers} \subsubsection{Eight-bit} Eight-bit integers \shall\ be unsigned binary integers, contained in one byte with decimal values ranging from 0 to 255.\index{integer, eight-bit} \subsubsection{Sixteen-bit} Sixteen-bit integers \shall\ be two's complement signed binary\index{two's complement} integers, contained in two bytes with decimal values ranging from $-$32768 to $+$32767.\index{integer, 16-bit} \subsubsection{Thirty-two-bit} Thirty-two-bit integers \shall\ be two's complement\index{two's complement} signed binary integers, contained in four\index{integer, 32-bit} bytes with decimal values ranging from $-$2147483648 to $+$2147483647. \subsubsection{Sixty-four-bit} \label{s:sixtyfour} Sixty-four-bit integers \shall\ be two's complement\index{two's complement} signed binary integers, contained in eight\index{integer, 64-bit} bytes with decimal values ranging from $-$9223372036854775808 to $+$9223372036854775807. \subsubsection{Unsigned integers} \label{s:Unsigned_Integers} The \FITS\ format does not support a native unsigned\index{integer, unsigned} integer data type (except for the unsigned 8-bit byte data type) therefore unsigned 16-bit, 32-bit, or 64-bit binary integers cannot be stored directly in a \FITS\ data array. Instead, the appropriate offset \must\ be applied to the unsigned integer to shift the value into the range of the corresponding signed integer, which is then stored in the \FITS\ file. The \kwd{BZERO} keyword \shall\ record the amount of the offset needed to restore the original unsigned value. The \kwd{BSCALE} keyword\index{BSCALE} \shall\ have the default value of \keyv{1.0} in this case, and the appropriate \kwd{BZERO} value, as a function of \kwd{BITPIX}, is specified in Table~\ref{t:unsig1}. This same technique \must\ be used when storing unsigned integers in a binary-table column of signed integers (Sect.~\ref{s:btork}). In this case the \indxkw{TSCAL}{n} keyword (analogous to \kwd{BSCALE}) \shall\ have the default value of \keyv{1.0}, and the appropriate \indxkw{TZERO}{n} value (analogous to \kwd{BZERO}) is specified in Table~\ref{t:unsig2}. \subsection{IEEE-754 floating point} \label{s:FloatingPoint} Transmission of 32- and 64-bit floating-point\index{IEEE floating-point} data within the \FITS\ format \shall\ use the\index{ANSI, IEEE} ANSI/IEEE-754 standard \citep{ieee85}. \kwd{BITPIX}~=~\keyv{-32} and \kwd{BITPIX}~=~\keyv{-64} signify 32- and 64-bit IEEE floating-point\index{IEEE floating-point} numbers, respectively; the absolute value of \kwd{BITPIX} is\index{BITPIX} used for computing the sizes of data structures. The full IEEE set of number forms is allowed for \FITS\ interchange, including all special\index{IEEE special values} values.\index{IEEE floating-point} The \kwd{BLANK} keyword\index{BLANK} \shouldnot\ be used when \kwd{BITPIX}~=~\keyv{-32} or\index{BITPIX} \keyv{-64}; rather, the IEEE NaN\index{NaN, IEEE} \should\ be used to represent an undefined\index{value, undefined} value. Use of\index{BSCALE} the \kwd{BSCALE} and \kwd{BZERO} keywords\index{BZERO} is \notrecommended. Appendix~\ref{s:IEEE754} has additional details on the IEEE format. %LC \subsection{Time} \label{s:wcstime} % \begin{redtext} There is strictly no such thing as a data type for {\em time valued} data, but rules to encode time values are given in Sect.~\ref{sect:timeReps} and in more detail in \cite{rots15}. % \end{redtext} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \section{Random-groups structure} \label{s:Rgrp} The random-groups structure allows a collection of `groups', where a group consists of a subarray of data and a set of associated parameter values, to be stored within the \FITS\ primary data array. Random groups\index{random groups} have been used almost exclusively for applications in radio interferometry; outside this field, there is little support for reading or writing data in this format. Other than the existing use for radio interferometry data, the random-groups structure is deprecated \index{deprecate} and \shouldnot\ be further used. For other applications, the binary-table \index{binary table} extension (Sect.~\ref{s:BTabl}) provides a more extensible and better documented way of associating groups of data within a single data structure. \subsection{Keywords} \label{s:rangr} \subsubsection{Mandatory keywords} The \kwd{SIMPLE} keyword\index{SIMPLE} is \required\ \index{keyword, mandatory} to be the first keyword in\index{primary header} the primary header of all \FITS\ files, including those with random-groups\index{random groups} records. If the random-groups format records follow the primary header, the\index{keyword, required} keyword records of the primary header \must\ use the keywords defined in Table~\ref{t:hdrrg} in the order\index{order, keyword}\index{keyword, order} specified. No other keywords \may\ intervene between the \kwd{SIMPLE} keyword and the last \indxkw{NAXIS}{n} keyword. % Table 12 \begin{table} \centering \caption{Mandatory keywords in primary header preceding random groups.} \label{t:hdrrg} \begin{tabular}{cl} \hline \hline Position & Keyword \\ \hline \noalign{\smallskip} 1 & \kwd{SIMPLE} = \keyv{T} \\ 2 & \kwd{BITPIX} \\ 3 & \kwd{NAXIS} \\ 4 & \kwd{NAXIS1} = \keyv{0} \\ 5 & \indxkw{NAXIS}{n}, $n$ = 2, \ldots, value of \kwd{NAXIS} \\ & \vdots \\ & (other keywords, which \must\ include \ldots) \\ & \kwd{GROUPS} = \keyv{T} \\ & \kwd{PCOUNT} \\ & \kwd{GCOUNT} \\ & \vdots \\ last & \kwd{END} \\ \noalign{\smallskip} \hline \end{tabular} \end{table} \paragraph{\kwd{SIMPLE} keyword.} The keyword record containing this keyword is structured in the\index{SIMPLE} same way as if a primary data array\index{primary data array} were present (Sect.~\ref{s:man}). \paragraph{\kwd{BITPIX} keyword.} The keyword record containing this keyword is structured as prescribed in\index{BITPIX} Sect.~\ref{s:man}. \paragraph{\kwd{NAXIS} keyword.} The value field \shall\ contain an integer ranging from 1 to\index{NAXIS} 999, representing one more than the number of axes in each data array. \paragraph{\kwd{NAXIS1} keyword.} The value field \shall\ contain the integer \keyv{0}, a signature of\index{NAXIS1} random-groups format indicating that there is no\index{primary data array} primary data array. \paragraph{\indxkw{NAXIS}{n} keywords ($n=2$, \ldots, value of \kwd{NAXIS}).} The \indxkw{NAXIS}{n} keywords \must\ be present for all values $n = 2$, \ldots, \kwd{NAXIS}, in increasing order of $n$, and for no larger values of $n$. The value field \shall\ contain an integer, representing the\index{NAXISn} number of positions along Axis $n-1$ of the data array in each group. \paragraph{\kwd{GROUPS} keyword.} The value field \shall\ contain the logical constant \keyv{T}. The\index{GROUPS} value \keyv{T} associated with this keyword implies that random-groups records are present. \paragraph{\kwd{PCOUNT} keyword.} The value field \shall\ contain an integer equal to the number\index{PCOUNT} of parameters preceding each array in a group. \paragraph{\kwd{GCOUNT} keyword.} The value field \shall\ contain an integer equal to the\index{GCOUNT} number of random groups present. \paragraph{\kwd{END} keyword.} This keyword has no associated value. Bytes~9 through 80\index{END} \shall\ contain ASCII spaces (decimal 32 or hexadecimal 20). \paragraph{} The total number of bits in the random-groups records exclusive of the fill described in Sect.~\ref{s:grdata} is given by the following\index{array size} expression: \begin{eqnarray} \mbox{$N_\mathrm{bits}$} &=& |\mbox{\kwd{BITPIX}}| \times \mbox{\kwd{GCOUNT}} \times \nonumber \\ & & (\mbox{\kwd{PCOUNT}} + \mbox{\kwd{NAXIS2}} \times \mbox{\kwd{NAXIS3}} \times \cdots \times \mbox{\indxkw{NAXIS}{m}}), \label{eq:rdmgsz} \end{eqnarray} \noindent where $N_\mathrm{bits}$ is\index{$N_\mathrm{bits}$} non-negative and the number of bits excluding fill; \texttt{m} is the value\index{NAXIS} of \kwd{NAXIS}; and\index{BITPIX} \kwd{BITPIX}, \kwd{GCOUNT}, \kwd{PCOUNT}, and\index{NAXISn} the \indxkw{NAXIS}{n} represent\index{PCOUNT} the\index{GCOUNT} values associated with those keywords. \subsubsection{Reserved keywords} \label{s:rgrrk} \paragraph{\indxkw{PTYPE}{n} keywords.} \label{s:ptyp} The\index{keyword, reserved} value field \shall\ contain a character string giving\index{PTYPEn} the name of Parameter~$n$. If the \indxkw{PTYPE}{n} keywords for more than one value of $n$ have the same associated name in the value field, then the data value for the parameter of that name is to be obtained by adding the derived data values of the corresponding parameters. This rule provides a mechanism by which a random parameter \may\ have more precision than the accompanying data array elements; for example, by summing two 16-bit values with the first scaled relative to the other such that the sum forms a number of up to 32-bit precision. \paragraph{\indxkw{PSCAL}{n} keywords.} \label{s:pscl} This keyword \shall\ be used, along\index{PSCALn} with the \indxkw{PZERO}{n} keyword, when the $n^\mathrm{th}$ \FITS\ group parameter value\index{group parameter value} is not the true physical value\index{physical value}, to transform the group parameter value to the true physical values it represents, using Eq.~\ref{eq:pscl}. The value field \shall\ contain a floating-point number representing the coefficient of the linear term in Eq.~\ref{eq:pscl}, the scaling factor between true values and group parameter values at zero offset. The default value for this keyword is \keyv{1.0}. \paragraph{\indxkw{PZERO}{n} keywords.} \label{s:pzer} This keyword \shall\ be used, along\index{PZEROn} with the \indxkw{PSCAL}{n} keyword, when the $n^\mathrm{th}$ \FITS\ group parameter value\index{group parameter value} is not the true physical value, to transform the group parameter value to the physical value. The value field \shall\ contain a floating-point number, representing the true value corresponding to a group parameter value of zero. The default value for this keyword is \keyv{0.0}. The transformation equation is as\index{scaling, data} follows: \begin{eqnarray} \mbox{physical\_value} & = & \mbox{\indxkw{PZERO}{n}} + \mbox{\indxkw{PSCAL}{n}} \times \mbox{group\_param\_value}. \label{eq:pscl} \end{eqnarray} \subsection{Data sequence} \label{s:grdata} Random-groups data \shall\ consist of a set of groups. The number of groups \shall\ be specified by the \kwd{GCOUNT} keyword in the associated header. Each group \shall\ consist of the number of\index{GCOUNT} parameters specified by the \kwd{PCOUNT} keyword\index{PCOUNT} followed by an array with the number of elements $N_\mathrm{elem}$ given\index{random-groups array} by the following\index{array size} expression: \begin{eqnarray} \mbox{$N_\mathrm{elem}$} &=& (\mbox{\kwd{NAXIS2}} \times \mbox{\kwd{NAXIS3}} \times \cdots \times \mbox{\indxkw{NAXIS}{m}}), \end{eqnarray} \noindent where $N_\mathrm{elem}$ is the number of elements in the data array in a group, \texttt{m} is the value\index{NAXIS} of \kwd{NAXIS}, and\index{NAXISn} the \indxkw{NAXIS}{n} represent the values associated with those keywords. The first parameter of the first group \shall\ appear in the first location of the first data block. The first element of each array \shall\ immediately follow the last parameter associated with that group. The first parameter of any subsequent group \shall\ immediately follow the last element of the array of the previous group. The arrays \shall\ be organized internally in the same way as an ordinary\index{primary data array} primary data array. If the groups data do not fill the final data block, the remainder of the block \shall\ be filled\index{fill} with zero values in the same way as a primary data array (Sect.~\ref{s:pdata}). If random-groups records are present, there \shall\ be no primary data array. \subsection{Data representation} Permissible data representations are those listed in Sect.~\ref{s:Drep}. Parameters and elements of associated data arrays \shall\ have the same representation. If more precision is required for an associated parameter than for an element of a data array, the parameter \shall\ be divided into two or more addends, represented by the same value\index{PTYPEn} for the \indxkw{PTYPE}{n} keyword. The value \shall\ be the sum of the physical values\index{physical value}, which \may\ have been obtained\index{scaling, data} from the group parameter values\index{group parameter value} using\index{PSCALn} the \indxkw{PSCAL}{n} and \indxkw{PZERO}{n} keywords.\index{PZEROn} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \section{Standard extensions} \label{s:exts} A standard extension is a conforming extension whose organization and content are completely specified in this Standard. The specifications for the three currently defined standard extensions, namely, \begin{enumerate} \item \IMAGE\ extensions; \item \TABLE\ ASCII-table extensions; and \item \BINTABLE\ binary-table extensions \end{enumerate} \noindent are given in the following sections. A list of other conforming extensions is given in Appendix~\ref{s:resname}. \subsection{Image extension} \label{s:image} The \FITS\ \IMAGE\ extension\index{image extension} is nearly identical in structure to the the primary HDU and is used to store an array of data. Multiple \IMAGE\ extensions can be used to store any number of arrays in a single \FITS\ file. The first keyword record in an \IMAGE\ extension \shall\ be {\kwd{XTENSION}\verb*+= 'IMAGE '+}. \subsubsection{Mandatory keywords} \label{s:imk} The \kwd{XTENSION} keyword is \required\ \index{keyword, mandatory} to be the first keyword of all \IMAGE\ extensions. The\index{keyword, required} keyword records in the header of an image extension \must\ use the keywords defined in Table~\ref{t:hdr4} in the order specified. No other keywords \may\ intervene between the \kwd{XTENSION} and \kwd{GCOUNT} keywords. % Table 13 \begin{table} \centering \caption{Mandatory keywords in \IMAGE\ extensions.} \label{t:hdr4} \begin{tabular}{cl} \hline \hline Position & Keyword \\ \hline \noalign{\smallskip} 1 & \kwd{XTENSION}\verb*+= 'IMAGE '+ \\ 2 & \kwd{BITPIX} \\ 3 & \kwd{NAXIS} \\ 4 & \indxkw{NAXIS}{n}, $n$ = 1, \ldots, \kwd{NAXIS} \\ 5 & \kwd{PCOUNT} = \keyv{0} \\ 6 & \kwd{GCOUNT} = \keyv{1} \\ & \vdots \\ & (other keywords \ldots ) \\ & \vdots \\ last & \kwd{END} \\ \noalign{\smallskip} \hline \end{tabular} \end{table} \paragraph{\kwd{XTENSION} keyword.} The\index{XTENSION} value field \shall\ contain the character\index{image extension} string \verb*+'IMAGE '+. \paragraph{\kwd{BITPIX} keyword.} The value field \shall\ contain an integer. The\index{BITPIX} absolute value is used in computing the sizes of data structures. It \shall\ specify the number of bits that represent a data value. The only valid values of \kwd{BITPIX} are given in Table~\ref{t:bitpix}. Writers of \IMAGE\ extensions \should\ select a \kwd{BITPIX} data type appropriate to the form, range of values, and accuracy of the data in the array. \paragraph{\kwd{NAXIS} keyword.} The value field \shall\ contain a non-negative integer no greater than 999, representing the number of axes in the associated data\index{NAXIS} array. If the value is zero then the \IMAGE\ extension \shallnot\ have any data blocks following the header. \paragraph{\indxkw{NAXIS}{n} keywords.} \label{s:naxisni} The \indxkw{NAXIS}{n} keywords \must\ be present for all values $n = 1$, \ldots, \kwd{NAXIS}, in increasing order of $n$, and for no other values of $n$. The value field of this indexed keyword \shall\ contain a non-negative integer, representing the number of elements along Axis~$n$ of a data array. If the value of any of the \indxkw{NAXIS}{n} keywords is zero, then the \IMAGE\ extension \shallnot\ have any data blocks following the header. If \kwd{NAXIS} is equal to \keyv{0} there \shouldnot\ be any \indxkw{NAXIS}{n} \index{NAXISn} keywords. \paragraph{\kwd{PCOUNT} keyword.} The value field \shall\ contain the integer \keyv{0}.\index{PCOUNT} \paragraph{\kwd{GCOUNT} keyword.} The value field \shall\ contain the integer \keyv{1}; each\index{GCOUNT} \IMAGE\ extension contains a single array. \paragraph{\kwd{END} keyword.} This keyword has no associated value. Bytes~9 through 80\index{END} \shall\ be filled\index{fill} with ASCII spaces (decimal 32 or hexadecimal 20). \subsubsection{Other reserved keywords} The reserved\index{keyword, reserved} keywords defined in Sect.~\ref{s:resk} (except for \kwd{EXTEND} and \kwd{BLOCKED}) \may\ appear in an image-extension header. The keywords \must\ be used as defined in that section. \subsubsection{Data sequence} The data format \shall\ be identical to that of a primary data array as\index{primary data array} described in Sect.~\ref{s:pdata}. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% % Table 14 \begin{table*} \centering \caption{Mandatory keywords in ASCII-table extensions.} \label{t:hdr3} \begin{tabular}{cl} \hline \hline Position & Keyword \\ \hline \noalign{\smallskip} 1 & \kwd{XTENSION}\verb*+= 'TABLE '+ \\ 2 & \kwd{BITPIX} = \keyv{8} \\ 3 & \kwd{NAXIS} = \keyv{2} \\ 4 & \kwd{NAXIS1} \\ 5 & \kwd{NAXIS2} \\ 6 & \kwd{PCOUNT} = \keyv{0} \\ 7 & \kwd{GCOUNT} = \keyv{1} \\ 8 & \kwd{TFIELDS} \\ & \vdots \\ & (other keywords, including (if \kwd{TFIELDS} is not zero) \ldots ) \\ & \indxkw{TTYPE}{n}, $n = \mathtt{1, 2, \ldots,}\, k$, where $k$ is the value of \kwd{TFIELDS} (\recommended) \\ & \indxkw{TBCOL}{n}, $n = \mathtt{1, 2, \ldots,}\, k$, where $k$ is the value of \kwd{TFIELDS} (\required) \\ & \indxkw{TFORM}{n}, $n = \mathtt{1, 2, \ldots,}\, k$, where $k$ is the value of \kwd{TFIELDS} (\required) \\ & \vdots \\ last & \kwd{END} \\ \noalign{\smallskip} \hline \end{tabular} \end{table*} \subsection{The ASCII-table extension} \label{s:ATabl} The ASCII-table extension\index{ASCII table} provides a means of storing catalogs and tables of astronomical data in \FITS\ format. Each row of the table consists of a fixed-length sequence of ASCII characters\index{ASCII character} divided into fields that correspond to the columns in the table. The first keyword record in an ASCII-table extension \shall\ be \kwd{XTENSION}\verb*+= 'TABLE '+. \subsubsection{Mandatory keywords} \label{s:atmk} The header of an ASCII-table extension \must\ use the keywords defined in Table~\ref{t:hdr3}. The\index{keyword, mandatory} first keyword \must\ be \kwd{XTENSION}; the seven keywords following \kwd{XTENSION} (\kwd{BITPIX} \ldots \kwd{TFIELDS}) \must\ be in the order\index{order, keyword}\index{keyword, order} specified with no intervening keywords. \paragraph{\kwd{XTENSION} keyword.} The\index{XTENSION} value field \shall\ contain the character\index{TABLE} string \verb*+'TABLE '+. \paragraph{\kwd{BITPIX} keyword.} The value field \shall\ contain the integer \keyv{8}, denoting\index{BITPIX} that the array contains ASCII\index{ASCII character} characters. \paragraph{\kwd{NAXIS} keyword.} The value field \shall\ contain the integer \keyv{2}, denoting\index{NAXIS} that the included data array is two-dimensional: rows and columns. \paragraph{\kwd{NAXIS1} keyword.} The value field \shall\ contain a non-negative integer, giving\index{NAXIS1} the number of ASCII characters in each row of the table. This includes all the characters in the defined fields plus any characters that are not included in any field. \paragraph{\kwd{NAXIS2} keyword.} The value field \shall\ contain a non-negative integer, giving\index{NAXIS2} the number of rows in the table. \paragraph{\kwd{PCOUNT} keyword.} The value field \shall\ contain the integer \keyv{0}.\index{PCOUNT} \paragraph{\kwd{GCOUNT} keyword.} The value field \shall\ contain the integer \keyv{1}; the data\index{GCOUNT} blocks contain a single table. \paragraph{\kwd{TFIELDS} keyword.} The value field \shall\ contain a non-negative integer representing\index{TFIELDS} the number of fields in each row. The maximum permissible value is 999. \paragraph{\indxkw{TBCOL}{n} keywords.} The \indxkw{TBCOL}{n} keywords \must\ be present for all values $n = 1$, \ldots, \kwd{TFIELDS} and for no other values of $n$. The value field of this indexed keyword \shall\ contain an integer\index{TBCOLn} specifying the column in which Field~$n$ starts. The first column of a row is numbered 1. \paragraph{\indxkw{TFORM}{n} keywords.} The \indxkw{TFORM}{n} keywords \must\ be present for all values $n = 1$, \ldots, \kwd{TFIELDS} and for no other values of $n$. The value field of this indexed keyword\index{TFORMn} \shall\ contain a character string describing the format in which Field~$n$ is encoded. Only the formats in Table~\ref{t:tabF}, interpreted as Fortran \citep{iso04} input\index{Fortran} formats and discussed in more detail in Sect.~\ref{s:ATEntry}, are permitted for encoding. Format codes \must\ be specified in upper case. Other format editing codes common to Fortran such as repetition, positional editing, scaling, and field termination are not permitted. All values in numeric fields have a number base of ten (i.e., they are decimal); binary, octal, hexadecimal, and other representations are not permitted. The \indxkw{TDISP}{n} keyword, defined in Sect.~\ref{s:atork}, \may\ be used to {\em recommend} that a decimal integer value in an ASCII table be displayed as the equivalent binary, octal, or hexadecimal value. % Table 15 \begin{table} \caption{Valid \indxkw{TFORM}{n} format values in \TABLE\ extensions.} \label{t:tabF} \begin{center} \begin{tabular}{rl} \hline \hline Field value & Data type \\ \hline \noalign{\smallskip} \keyv{Aw} & Character \\ \keyv{Iw} & Decimal integer \\ \keyv{Fw.d} & Floating-point, fixed decimal notation \\ \keyv{Ew.d} & Floating-point, exponential notation \\ \keyv{Dw.d} & Floating-point, exponential notation \\ \noalign{\smallskip} \hline \end{tabular} \end{center} \tablefoot{\keyv{w} is the width in characters of the field and \keyv{d} is the number of digits to the right of the decimal.} \end{table} % Table 16 \begin{table*} \centering \caption{Valid \indxkw{TDISP}{n} format values in \TABLE\ extensions.} \label{t:tableD} \begin{tabular}{rl} \hline \hline Field value & Data type \\ \hline \noalign{\smallskip} \keyv{Aw} & Character \\ \keyv{Iw.m} & Integer \\ \keyv{Bw.m} & Binary, integers only \\ \keyv{Ow.m} & Octal, integers only \\ \keyv{Zw.m} & Hexadecimal, integers only \\ \keyv{Fw.d} & Floating-point, fixed decimal notation \\ \keyv{Ew.dEe} & Floating-point, exponential notation \\ \keyv{ENw.d} & Engineering; E format with exponent multiple of three \\ \keyv{ESw.d} & Scientific; same as EN but non-zero leading digit if not zero \\ \keyv{Gw.dEe} & General; appears as F if significance not lost, else E. \\ \keyv{Dw.dEe} & Floating-point, exponential notation \\ \noalign{\smallskip} \hline \end{tabular} \tablefoot{\keyv{w} is the width in characters of displayed values, \keyv{m} is the minimum number of digits displayed, \keyv{d} is the number of digits to right of decimal, and \keyv{e} is number of digits in exponent. The \keyv{.m} and \keyv{Ee} fields are \optional.} \end{table*} \paragraph{\kwd{END} keyword.} This keyword has no associated value. Bytes~9 through 80\index{END} \shall\ contain ASCII spaces (decimal 32 or hexadecimal 20). \subsubsection{Other reserved keywords} \label{s:atork} In addition to the reserved keywords defined in Sect.~\ref{s:resk} (except for \kwd{EXTEND} and \kwd{BLOCKED}), the following other reserved keywords\index{keyword, reserved} \may\ be used to describe the structure of an ASCII-table data array. They are \optional, but if they appear within an ASCII-table extension header, they \must\ be used as defined in this section of this Standard. \paragraph{\indxkw{TTYPE}{n} keywords.} The value field for this indexed keyword \shall\ contain a\index{TTYPEn} character string giving the name of Field~$n$. It is {\em strongly recommended} that every field of the table be assigned a unique, case-insensitive \index{case sensitivity} name with this keyword, and it is \recommended\ that the character string be composed only of upper- and lower-case letters, digits, and the\index{underscore} underscore (\keyv{'\_'}, decimal 95, hexadecimal 5F) character. Use of other characters is \notrecommended\ because it may be difficult to map the column names into variables in some languages (e.g., any hyphens,\index{hyphen} \keyv{'*'} or \keyv{'+'} characters in the name may be confused with mathematical operators). String comparisons with the \indxkw{TTYPE}{n} keyword values \shouldnot\ be case sensitive (e.g., \keyv{'TIME'} and '\keyv{Time'} \should\ be interpreted as the same name). \paragraph{\indxkw{TUNIT}{n} keywords.} The value field \shall\ contain a character string\index{TUNITn} describing the physical units\index{units} in which the quantity in Field~$n$, after any application\index{TSCALn} of \indxkw{TSCAL}{n} and \indxkw{TZERO}{n}, is\index{TZEROn} expressed. Units \must\ follow the prescriptions in Sect.~\ref{s:Units}. \paragraph{\indxkw{TSCAL}{n} keywords.} This indexed keyword \shall\ be used, along with the \indxkw{TZERO}{n} keyword, to linearly scale the values in the table Field~$n$ to transform them into the physical\index{physical value} values that they represent using Eq.~\ref{eq:tscl}. The value field \shall\ contain a floating-point number representing the coefficient of the linear term in the scaling equation. The default value for this keyword is \keyv{1.0}. This keyword \mustnot\ be used for A-format fields. The transformation equation used to compute a true physical value from the quantity in Field~$n$ is\index{scaling, data} \begin{eqnarray} \mbox{physical\_value} & = & \mbox{\indxkw{TZERO}{n}} + \mbox{\indxkw{TSCAL}{n}} \times \mbox{field\_value} \label{eq:tscl} \end{eqnarray} \noindent where \texttt{field\_value} is the value that is actually stored in that table field in the \FITS\ file. \paragraph{\indxkw{TZERO}{n} keywords.} This indexed keyword \shall\ be used, along with the \indxkw{TSCAL}{n} keyword, to linearly scale the values in the table Field~$n$ to transform them into the physical\index{physical value} values that they represent using Eq.~\ref{eq:tscl}. The value field \shall\ contain a floating-point number representing the physical value corresponding to an array value\index{array value} of zero. The default value for this keyword is \keyv{0.0}. This keyword \mustnot\ be used for A-format fields. \paragraph{\indxkw{TNULL}{n} keywords.} The value field for this indexed keyword \shall\ contain the character\index{TNULLn} string that represents\index{value, undefined} an undefined value for Field~$n$. The string is implicitly space filled\index{fill} to the width of the field. \paragraph{\indxkw{TDISP}{n} keywords.} The value field of this indexed keyword \shall\ contain a\index{TDISPn} character string describing the format recommended for displaying an ASCII-text representation of of the contents of Field~$n$. This keyword overrides the default display format given by the \indxkw{TFORM}{n} keyword. If the table value has been scaled, the physical value, derived using Eq.~\ref{eq:tscl}, \shall\ be displayed. All elements in a field \shall\ be displayed with a single, repeated format. Only the format codes in Table~\ref{t:tableD}, interpreted as Fortran \citep{iso04} output\index{Fortran} formats, and discussed in more detail in Sect.~\ref{s:BinDD}, are permitted for encoding. The format codes \must\ be specified in upper case. If the \keyv{Bw.m}, \keyv{Ow.m}, and \keyv{Zw.m} formats are not readily available to the reader, the \keyv{Iw.m} display format \may\ be used instead, and if the \keyv{ENw.d} and \keyv{ESw.d} formats are not available, \keyv{Ew.d} \may\ be used. %LC Bill %begin{viotext} \paragraph{} The following four keywords \may\ be used to specify minimum and maximum values \index{min and max in columns, keywords} in numerical columns of a \FITS\ ASCII or binary table. These keywords \must\ have the same data type as the physical values in the associated column (either an integer or a floating-point number). Any undefined elements in the column \shall\ be excluded when determining the value of these keywords. \paragraph{\indxkw{TDMIN}{n} keywords.} The value field \shall\ contain a number giving the minimum physical value contained in Column~$n$ of the table. This keyword is analogous to the \kwd{DATAMIN} keyword that is defined for arrays in Sect.~\ref{s:resk}.5. \paragraph{\indxkw{TDMAX}{n} keywords.} The value field \shall\ contain a number giving the maximum physical value contained in Column~$n$ of the table. This keyword is analogous to the \kwd{DATAMAX} keyword that is defined for arrays in Sect.~\ref{s:resk}.5. \paragraph{\indxkw{TLMIN}{n} keywords.} The value field \shall\ contain a number that specifies the minimum physical value in Column~$n$ that has a valid meaning or interpretation. The column is not \required\ to actually contain any elements that have this value, and the column \may\ contain elements with physical values less than \indxkw{TLMIN}{n}, however, the interpretation of any such out-of-range column elements is not defined. \paragraph{\indxkw{TLMAX}{n} keywords.} The value field \shall\ contain a number that specifies the maximum physical value in Column~$n$ that has a valid meaning or interpretation. The column is not \required\ to actually contain any elements that have this value, and the column \may\ contain elements with physical values greater than \indxkw{TLMAX}{n}, however, the interpretation of any such out-of-range column elements is not defined. \paragraph{} The \indxkw{TLMIN}{n} and \indxkw{TLMAX}{n} keywords are commonly used when constructing histograms of the data values in a column. For example, if a table contains columns that give the $X$ and $Y$ pixel location of a list of photons that were detected by a photon-counting device, then the \indxkw{TLMIN}{n} and \indxkw{TLMAX}{n} keywords could be used respectively to specify the minimum and maximum values that the detector is capable of assigning to the $X$ and $Y$ columns. %end{viotext} \subsubsection{Data sequence} The table is constructed from a two-dimensional array of ASCII\index{ASCII character} characters. The row length and the number of rows \shall\ be those specified, respectively, by the \kwd{NAXIS1}\index{NAXIS1} and \kwd{NAXIS2}\index{NAXIS2} keywords of the associated header. The number of characters in a row and the number of rows in the table \shall\ determine the size of the character array. Every row in the array \shall\ have the same number of characters. The first character of the first row \shall\ be at the start of the data block immediately following the last header block. The first character of subsequent rows \shall\ follow immediately the character at the end of the previous row, independent of the \FITS\ block structure. The positions in the last data block after the last character of the last row of the table \shall\ be filled\index{fill} with ASCII spaces. \subsubsection{Fields} Each row in the array \shall\ consist of a sequence of from 0 to 999 fields, as specified by the \kwd{TFIELDS} keyword, with one entry in each field. For every field, the Fortran \citep{iso04} format \index{Fortran} of the information contained (given by the \indxkw{TFORM}{n} keyword), the location in the row of the beginning of the field (given by the \indxkw{TBCOL}{n} keyword), and ({\em optionally}, but {\em strongly recommended}) the field name (given by the \indxkw{TTYPE}{n} keyword), \shall\ be specified in the associated header. The location and format of fields \shall\ be the same for every row. Fields \may\ overlap, but this usage is \notrecommended. Only a limited set of ASCII character values \may\ appear within any field, depending on the field type as specified below. There \may\ be characters in a table row that are not included in any field, (e.g., between fields, or before the first field or after the last field). Any seven-bit ASCII character \index{ASCII character} \may\ occur in characters of a table row that are not included in a defined field. A common convention is to include a space character between each field for added legibility if the table row is displayed verbatim. It is also permissible to add control characters, such as a carriage return or line-feed character, following the last field in each row as a way of formatting the table if it is printed or displayed by a text-editing program. \subsubsection{Entries} \label{s:ATEntry} All data in an ASCII-table extension field \shall\ be ASCII text\index{ASCII text} in a format that conforms to the rules for fixed field input in Fortran \index{Fortran} \citep{iso04} format, as described below. The only possible formats \shall\ be those specified in Table~\ref{t:tabF}. If values of $-0$ and $+0$ need to be distinguished, then the sign character\index{sign character} \should\ appear in a separate field in character format. \indxkw{TNULL}{n} keywords\index{TNULLn} \may\ be used to specify a character string that represents\index{value, undefined} an undefined value in each field. The characters representing an undefined value \may\ differ from field to field but \must\ be the same within a field. Writers of ASCII tables \should\ select a format for each field that is appropriate to the form, range of values, and accuracy of the data in that field. This Standard does not impose an upper limit on the number of digits of precision, nor any limit on the range of numeric values. Software packages that read or write data according to this Standard could be limited, however, in the range of values and exponents that are supported (e.g., to the range that can be represented by 32-bit or 64-bit binary numbers). The value of each entry \shall\ be interpreted as described in the following paragraphs. \paragraph{Character fields.} The value of a character-formatted (\keyv{Aw\/}) field is a character string \index{character string} of width \keyv{w} containing the characters in columns \indxkw{TBCOL}{n} through \indxkw{TBCOL}{n}$\, +\, \keyv{w} - 1$. The character string \shall\ be composed of the restricted set of ASCII-text\index{ASCII text} characters with decimal values in the range 32 through 126 (hexadecimal 20 through 7E). \paragraph{Integer fields.} The value of an integer-formatted (\keyv{Iw\/}) field is a signed decimal integer contained in Columns \indxkw{TBCOL}{n} through \indxkw{TBCOL}{n}$\, +\, \keyv{w} - 1$ consisting of a\index{sign character} single \optional\ sign (\keyv{'+'} or \keyv{'-'}) followed by one or more decimal digits (\keyv{'0'} through \keyv{'9'}). Non-significant space characters \may\ precede and/or follow the integer value within the field. A blank field has value 0. All characters other than leading and trailing spaces, a contiguous string of decimal digits, and a single leading sign character are forbidden. \paragraph{Real fields.} The value of a real-formatted field (\keyv{Fw.d\/}, \keyv{Ew.d\/}, \keyv{Dw.d\/}) is a real number determined from the \keyv{w} characters from Columns \indxkw{TBCOL}{n} through \indxkw{TBCOL}{n}$\, +\, \keyv{w} - 1$. The value is formed by \begin{enumerate} \item discarding any trailing space characters in the field and right-justifying the remaining characters, \item interpreting the first non-space characters as a numeric string consisting of a single \optional\ sign (\keyv{'+'} or \keyv{'-'}) followed by one or more decimal digits (\keyv{'0'} through \keyv{'9'}) {\em optionally} containing a single decimal point (\keyv{'.'}). The numeric string is terminated by the end of the right-justified field or by the occurrence of any character other than a decimal point (\keyv{'.'}) and the decimal integers (\keyv{'0'} through \keyv{'9'}). If the string contains no explicit decimal point, then the implicit decimal point is taken as immediately preceding the rightmost $d$ digits of the string, with leading zeros assumed if necessary. The use of implicit decimal points is {\em deprecated} \index{deprecate} and is strongly discouraged because of the possibility that \FITS-reading programs will misinterpret the data value. Therefore, real-formatted fields \should\ always contain an explicit decimal point. \item If the numeric string is terminated by a \begin{enumerate} \item \keyv{'+'} or \keyv{'-'}, interpreting the following string as an exponent in the form of a signed decimal integer, or \item \keyv{'E'}, or \keyv{'D'}, interpreting the following string as an exponent of the form \keyv{E} or \keyv{D} followed by an {\em optionally} signed decimal integer constant. \end{enumerate} \item The exponent string, if present, is terminated by the end of the right-justified string. \item Characters other than those specified above, including embedded space characters, are forbidden. \end{enumerate} The numeric value of the table field is then the value of the numeric string multiplied by ten (10) to the power of the exponent string, i.e., value = numeric\_string~$\times$ $10^\mathrm{(exponent\_string)}$. The default exponent is zero and a blank field has value zero. There is no difference between the \keyv{F}, \keyv{D}, and \keyv{E} formats; the content of the string determines its interpretation. Numbers requiring more precision and/or range than the local computer can support \may\ be represented. It is good form to specify a \keyv{D} format in \indxkw{TFORM}{n} for a column of an ASCII table when that column will contain numbers that cannot be accurately represented in 32-bit IEEE binary format (see Appendix~\ref{s:IEEE754}). %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \subsection{Binary-table extension} \label{s:BTabl} The binary-table extension\index{binary table} is similar to the ASCII table in that it provides a means of storing catalogs and tables of astronomical data in \FITS\ format, however, it offers more features and provides more-efficient data storage than ASCII tables. The numerical values in binary tables are stored in more-compact binary formats rather than coded into ASCII, and each field of a binary table can contain an array of values rather than a simple scalar as in ASCII tables. The first keyword record in a binary-table extension \shall\ be {\kwd{XTENSION}\verb*+= 'BINTABLE'+}. % Table 17 \begin{table*} \centering \caption{Mandatory keywords in binary-table extensions.} \label{t:hdrbin} \begin{tabular}{cl} \hline \hline Position & Keyword \\ \hline \noalign{\smallskip} 1 & \kwd{XTENSION}\verb*+= 'BINTABLE'+ \\ 2 & \kwd{BITPIX} = \keyv{8} \\ 3 & \kwd{NAXIS} = \keyv{2} \\ 4 & \kwd{NAXIS1} \\ 5 & \kwd{NAXIS2} \\ 6 & \kwd{PCOUNT} \\ 7 & \kwd{GCOUNT} = \keyv{1} \\ 8 & \kwd{TFIELDS} \\ & \vdots \\ & (other keywords, including (if \kwd{TFIELDS} is not zero) \ldots ) \\ & \indxkw{TTYPE}{n}, $n = \mathtt{1, 2, \ldots,}\, k$, where $k$ is the value of \kwd{TFIELDS} (\recommended) \\ & \indxkw{TFORM}{n}, $n = \mathtt{1, 2, \ldots,}\, k$, where $k$ is the value of \kwd{TFIELDS} (\required) \\ & \vdots \\ last & \kwd{END} \\ \noalign{\smallskip} \hline \end{tabular} \end{table*} \subsubsection{Mandatory keywords} \label{s:btmk} The \kwd{XTENSION} keyword is the first keyword of all binary-table extensions. The seven keywords\index{keyword, required} following (\kwd{BITPIX} \ldots \kwd{TFIELDS}) \must\ be\index{keyword, mandatory} in the order specified in Table~\ref{t:hdrbin}, with no intervening keywords. \paragraph{\kwd{XTENSION} keyword.} The\index{XTENSION} value field \shall\ contain the character string \verb+'BINTABLE'+. \paragraph{\kwd{BITPIX} keyword.} The value field \shall\ contain the integer \keyv{8}, denoting\index{BITPIX} that the array is an array of eight-bit bytes. \paragraph{\kwd{NAXIS} keyword.} The value field \shall\ contain the integer \keyv{2}, denoting\index{NAXIS} that the included data array is two-dimensional: rows and columns. \paragraph{\kwd{NAXIS1} keyword.} The value field \shall\ contain a non-negative integer, giving\index{NAXIS1} the number of eight-bit bytes in each row of the table. \paragraph{\kwd{NAXIS2} keyword.} The value field \shall\ contain a non-negative integer, giving\index{NAXIS2} the number of rows in the table. \paragraph{\kwd{PCOUNT} keyword.} The value field\index{PCOUNT} \shall\ contain the number of bytes that follow the table in the supplemental data area called the heap. \index{heap} \paragraph{\kwd{GCOUNT} keyword.} The value field \shall\ contain the integer \keyv{1}; the\index{GCOUNT} data blocks contain a single table. \paragraph{\kwd{TFIELDS} keyword.} The value field \shall\ contain a non-negative integer representing\index{TFIELDS} the number of fields in each row. The maximum permissible value is 999. \paragraph{\indxkw{TFORM}{n} keywords.} The \indxkw{TFORM}{n} keywords \must\ be present for all values $n = 1$, \ldots, \kwd{TFIELDS} and for no other values of $n$. The value field of this indexed keyword \shall\ contain a\index{TFORMn} character string of the form {\em r}\keyv{T}{\em a}. The repeat count {\em r} is\index{repeat count} the ASCII representation of a non-negative integer specifying the number of elements in Field~$n$. The default value of {\em r} is \keyv{1}; the repeat count need not be present if it has the default value. A zero element count, indicating an empty\index{field, empty} field, is permitted. The data type \keyv{T} specifies the data type of the contents of Field~$n$. Only the data types in Table~\ref{t:tabBF} are\index{array descriptor} permitted. The format codes \must\ be specified in upper case. For fields of type \keyv{P} or \keyv{Q}, the only permitted repeat counts are \keyv{0} and \keyv{1}. The additional characters {\em a} are \optional\ and are not further defined in this Standard. Table~\ref{t:tabBF} lists the number of bytes each data type occupies in a table row. The first field of a row is numbered 1. The total number of bytes $n_\mathrm{row}$ in a table row is given by \begin{eqnarray} n_\mathrm{row} & = & \sum_{i=1}^{\mbox{\kwd{TFIELDS}}} {r_{i} b_{i}} \label{eq:binrow} \end{eqnarray} where $r_{i}$ is the repeat count for Field~$i$, $b_{i}$ is the number of bytes for the data type in Field~$i$, and \kwd{TFIELDS} is the value of that keyword, \must\ equal the value of\index{NAXIS1} \kwd{NAXIS1}. \paragraph{\kwd{END} keyword.} This keyword has no associated value. Bytes~9 through 80\index{END} \shall\ contain ASCII spaces (decimal 32 or hexadecimal 20). % Table 18 \begin{table} \centering \caption{Valid \indxkw{TFORM}{n} data types in \BINTABLE\ extensions.} \label{t:tabBF} \begin{tabular}{ccc} \hline \hline \indxkw{TFORM}{n} value & Description & Eight-bit Bytes \\ \hline \noalign{\smallskip} \keyv{'L'} & Logical & 1 \\ \keyv{'X'} & Bit & \dag \\ \keyv{'B'} & Unsigned byte & 1 \\ \keyv{'I'} & 16-bit integer & 2 \\ \keyv{'J'} & 32-bit integer & 4 \\ \keyv{'K'} & 64-bit integer & 8 \\ \keyv{'A'} & Character & 1 \\ \keyv{'E'} & Single-precision floating point & 4 \\ \keyv{'D'} & Double-precision floating point & 8 \\ \keyv{'C'} & Single-precision complex & 8 \\ \keyv{'M'} & Double-precision complex & $\!\!\!$16 \\ \keyv{'P'} & Array Descriptor (32-bit) & 8 \\ \keyv{'Q'} & Array Descriptor (64-bit) & $\!\!\!$16 \\ \noalign{\smallskip} \hline \end{tabular} \tablefoot{$^{(\dag)}$ Number of eight-bit bytes needed to contain all bits.} \end{table} \subsubsection{Other reserved keywords} \label{s:btork} In addition to the reserved keywords defined in Sect.~\ref{s:resk} (except for \kwd{EXTEND} and \kwd{BLOCKED}), the following other reserved keywords\index{keyword, reserved} \may\ be used to describe the structure of a binary-table data array. They are \optional, but if they appear within a binary-table extension header, they \must\ be used as defined in this section of this Standard. \paragraph{\indxkw{TTYPE}{n} keywords.} The value field for this indexed keyword \shall\ contain a\index{TTYPEn} character string giving the name of Field~$n$. It is {\em strongly recommended} that every field of the table be assigned a unique, case-insensitive \index{case sensitivity} name with this keyword, and it is \recommended\ that the character string be composed only of upper- and lower-case letters, digits, and the\index{underscore} underscore (\keyv{'\_'}, decimal 95, hexadecimal 5F) character. Use of other characters is \notrecommended\ because it may be difficult to map the column names into variables in some languages (e.g., any hyphens,\index{hyphen} \keyv{'*'} or \keyv{'+'} characters in the name may be confused with mathematical operators). String comparisons with the \indxkw{TTYPE}{n} keyword values \shouldnot\ be case sensitive (e.g., \keyv{'TIME'} and '\keyv{Time'} \should\ be interpreted as the same name). \paragraph{\indxkw{TUNIT}{n} keywords.} The value field \shall\ contain a character string\index{TUNITn} describing the physical units\index{units} in which the quantity in Field~$n$, after any application\index{TSCALn} of \indxkw{TSCAL}{n} and \indxkw{TZERO}{n}, is\index{TZEROn} expressed. Units \must\ follow the prescriptions in Sect.~\ref{s:Units}. \paragraph{\indxkw{TSCAL}{n} keywords.} This indexed keyword \shall\ be used, along with the \indxkw{TZERO}{n} keyword, to linearly scale the values in the table Field~$n$ to transform them into the physical\index{physical value} values that they represent using Eq.~\ref{eq:tscl}. It \mustnot\ be used if the format of Field~$n$ is \keyv{'A'}, \keyv{'L'}, or \keyv{'X'}. For fields with all other data types, the value field \shall\ contain a floating-point number representing the coefficient of the linear term in Eq.~\ref{eq:tscl}, which is used to compute the true physical value\index{physical value} of the field, or, in the case of the complex \index{complex data} data types \keyv{'C'} and \keyv{'M'}, of the real part of the field, with the imaginary part of the scaling factor set to zero. The default value for this keyword is \keyv{1.0}. For fields of type \keyv{'P'} or \keyv{'Q'}, the values of \indxkw{TSCAL}{n} and \indxkw{TZERO}{n} are to be applied to the values in the data array in the heap \index{heap} area, not the values of the array descriptor\index{array descriptor} (see Sect.~\ref{s:app_varlen}). \paragraph{\indxkw{TZERO}{n} keywords.} This indexed keyword \shall\ be used, along with the \indxkw{TSCAL}{n} keyword, to linearly scale the values in the table Field~$n$ to transform them into the physical\index{physical value} values that they represent using Eq.~\ref{eq:tscl}. It \mustnot\ be used if the format of Field~$n$ is \keyv{'A'}, \keyv{'L'}, or \keyv{'X'}. For fields with all other data types, the value field \shall\ contain a floating-point number representing the true physical value corresponding to a value of zero in Field~$n$ of the \FITS\ file, or, in the case of the complex data types \keyv{'C'} and \keyv{'M}, in the real part of the field, with the imaginary part set to zero. The default value for this keyword is \keyv{0.0}. Equation~\ref{eq:tscl} is used to compute\index{scaling, data} a true physical value from the quantity in Field~$n$. For fields of type \keyv{'P'} or \keyv{'Q'}, the values of \indxkw{TSCAL}{n} and \indxkw{TZERO}{n} are to be applied to the values in the data array in the heap \index{heap} area, not the values of the array descriptor\index{array descriptor} (see Sect.~\ref{s:app_varlen}). In addition to its use in representing floating-point values as scaled integers, the \indxkw{TZERO}{n} keyword is also used when storing unsigned\index{integer, unsigned} integer values in the field. In this special case the \indxkw{TSCAL}{n} keyword \shall\ have the default value of \keyv{1.0} and the \indxkw{TZERO}{n} keyword \shall\ have one of the integer values shown in Table~\ref{t:unsig2}. % Table 19 \begin{table*} \centering \caption{Usage of \indxkw{TZERO}{n} to represent non-default integer data types.} \label{t:unsig2} \begin{tabular}{cccrl} \hline \hline \indxkw{TFORM}{n} & {Native } & {Physical} & \indxkw{TZERO}{n} & \\ & data type & {data type} & & \\ \hline \noalign{\smallskip} \keyv{'B'} & unsigned & signed byte & \keyv{-128} & ($-2^{7}$) \\ \keyv{'I'} & signed & unsigned 16-bit & \keyv{32768} & ($2^{15}$) \\ \keyv{'J'} & signed & unsigned 32-bit & \keyv{2147483648} & ($2^{31}$) \\ \keyv{'K'} & signed & unsigned 64-bit & \keyv{9223372036854775808} & ($2^{63}$) \\ \noalign{\smallskip} \hline \end{tabular} \end{table*} Since the binary-table format does not support a native unsigned\index{integer, unsigned} integer data type (except for the unsigned eight-bit \keyv{'B'} column type), the unsigned values are stored in the field as native signed integers with the appropriate integer offset specified by the \indxkw{TZERO}{n} keyword value shown in the table. For the byte column type, the converse technique can be used to store signed byte values as native unsigned values with the negative \indxkw{TZERO}{n} offset. In each case, the physical value is computed by adding the offset specified by the \indxkw{TZERO}{n} keyword to the native data type value that is stored in the table field. \paragraph{\indxkw{TNULL}{n} keywords.} The value field for this indexed keyword \shall\ contain the integer\index{TNULLn} that represents\index{value, undefined} an undefined value for Field~$n$ of Data Type \keyv{B}, \keyv{I}, \keyv{J} or \keyv{K}, or \keyv{P} or \keyv{Q} array-descriptor\index{array descriptor} fields (Sect.~\ref{s:app_varlen}) that point to \keyv{B}, \keyv{I}, \keyv{J}, or \keyv{K} integer arrays. The keyword \mustnot\ be used if Field~$n$ is of any other data type. The value of this keyword corresponds to the table column values before applying any transformation indicated by the \indxkw{TSCAL}{n} and \indxkw{TZERO}{n} keywords. If the \indxkw{TSCAL}{n} and \indxkw{TZERO}{n} keywords do not have the default values of \keyv{1.0} and \keyv{0.0}, respectively, then the value of the \indxkw{TNULL}{n} keyword \must\ equal the actual value in the \FITS\ file that is used to represent an undefined element and not the corresponding physical value (computed from Eq.~\ref{eq:tscl}). To cite a specific, common example, {\em unsigned} 16-bit integers are represented in a {\em signed} integer column (with \indxkw{TFORM}{n}~=~\keyv{'I'}) by setting \indxkw{TZERO}{n}~=~\keyv{32768} and \indxkw{TSCAL}{n}~=~\keyv{1}. If it is desired to use elements that have an {\em unsigned} value (i.e., the physical value) equal to 0 to represent undefined elements in the field, then the \indxkw{TNULL}{n} keyword \must\ be set to the value \keyv{-32768} because that is the actual value stored in the \FITS\ file for those elements in the field. \paragraph{\indxkw{TDISP}{n} keywords.} The value field of this indexed keyword \shall\ contain a\index{TDISPn} character string describing the format recommended for displaying an ASCII-text representation of the contents of Field~$n$. If the table value has been scaled, the physical value, derived using Eq.~\ref{eq:tscl}, \shall\ be displayed. All elements in a field \shall\ be displayed with a single, repeated format. For purposes of display, each byte of bit (Type~\keyv{X}) and byte (Type~\keyv{B}) arrays is treated as an unsigned integer. Arrays of Type~\keyv{A} \may\ be terminated with a zero byte. Only the format codes in Table~\ref{t:tabD}, interpreted as Fortran \citep{iso04} output\index{Fortran} formats, and discussed in more detail in Sect.~\ref{s:BinDD}, are permitted for encoding. The format codes \must\ be specified in upper case. If the \keyv{Bw.m}, \keyv{Ow.m}, and \keyv{Zw.m} formats are not readily available to the reader, the \keyv{Iw.m} display format \may\ be used instead, and if the \keyv{ENw.d} and \keyv{ESw.d} formats are not available, \keyv{Ew.d} \may\ be used. In the case of fields of Type~\keyv{P} or \keyv{Q}, the \indxkw{TDISP}{n} value applies to the data array pointed to by the array descriptor\index{array descriptor} (Sect.~\ref{s:app_varlen}), not the values in the array descriptor itself. % Table 20 \begin{table*} \begin{center} \caption{Valid \indxkw{TDISP}{n} format values in \BINTABLE\ extensions.} \label{t:tabD} \begin{tabular}{rl} \hline \hline Field Value & Data type \\ \hline \noalign{\smallskip} \keyv{Aw} & Character \\ \keyv{Lw} & Logical \\ \keyv{Iw.m} & Integer \\ \keyv{Bw.m} & Binary, integers only \\ \keyv{Ow.m} & Octal, integers only \\ \keyv{Zw.m} & Hexadecimal, integers only \\ \keyv{Fw.d} & Floating-point, fixed decimal notation \\ \keyv{Ew.dEe} & Floating-point, exponential notation \\ \keyv{ENw.d} & Engineering; E format with exponent multiple of three \\ \keyv{ESw.d} & Scientific; same as EN but non-zero leading digit if not zero \\ \keyv{Gw.dEe} & General; appears as F if significance not lost, else E. \\ \keyv{Dw.dEe} & Floating-point, exponential notation \\ \noalign{\smallskip} \hline \end{tabular} \end{center} \tablefoot{ \keyv{w} is the width in characters of displayed values, \keyv{m} is the minimum number of digits displayed, \keyv{d} is the number of digits to right of decimal, and \keyv{e} is number of digits in exponent. The \keyv{.m} and \keyv{Ee} fields are {\em optional}.} \end{table*} \paragraph{\kwd{THEAP} keyword.} The value field of this\index{THEAP} keyword \shall\ contain an integer providing the separation, in bytes, between the start of the main data table and the start of a supplemental data area called the\index{heap} heap. The default value, which is also the minimum allowed value, \shall\ be the product\index{NAXIS1} of the values of \kwd{NAXIS1} and\index{NAXIS2} \kwd{NAXIS2}. This keyword \shallnot\ be used if the value of \kwd{PCOUNT} is \keyv{0}. The use of this keyword is described in in Sect.~\ref{s:app_varlen}. \paragraph{\indxkw{TDIM}{n} keywords.} \label{s:app_dim} The value field of this\index{TDIMn} indexed keyword \shall\ contain a character string describing how to interpret the contents of Field~$n$ as a multi-dimensional array\index{array, multi-dimensional} with a format of \keyv{'($l$,$m$,$n$\ldots)'}, where \keyv{$l$}, \keyv{$m$}, \keyv{$n$}, \ldots are the dimensions of the array. The data are ordered such that the array index of the first dimension given (\keyv{$l$}) is the most rapidly varying, and that of the last dimension given is the least rapidly varying. The total number of elements in the array equals the product of the dimensions specified in the \indxkw{TDIM}{n} keyword. The size \must\ be less than or equal to the repeat count in the \indxkw{TFORM}{n} keyword, or, in the case of columns that have a \keyv{'P'} or \keyv{'Q'} \indxkw{TFORM}{n} data type, less than or equal to the array length specified in the variable-length\index{array, variable-length} array\index{variable-length array} descriptor\index{array descriptor} (see Sect.~\ref{s:app_varlen}). In the special case where the variable-length array descriptor has a size of zero, then the \indxkw{TDIM}{n} keyword is not applicable. If the number of elements in the array implied by the \indxkw{TDIM}{n} is fewer than the allocated size of the array in the \FITS\ file, then the unused trailing elements \should\ be interpreted as containing undefined fill\index{fill} values. A character string \index{character string} is represented in a binary table by a one-dimensional character array, as described under `Character' in the list of data types in Sect.~\ref{s:MbinT}. For example, a Fortran \texttt{CHARACTER*20} \index{Fortran} variable could be represented in a binary table as a character array declared as \indxkw{TFORM}{n}~=~\keyv{'20A'}. Arrays of strings, i.e., multi-dimensional\index{array, multi-dimensional} character arrays, \may\ be represented using the \indxkw{TDIM}{n} notation. For example, if \indxkw{TFORM}{n}~=~\keyv{'60A'} and \indxkw{TDIM}{n}~=~\keyv{'(5,4,3)'}, then the entry consists of a $4\times 3$ array of strings each comprising five characters. %LC Bill %begin{viotext} \paragraph{} The following four keywords \may\ be used to specify minimum and maximum values \index{min and max in columns, keywords} in numerical columns of a \FITS\ ASCII or binary table. These keywords \must\ have the same data type as the physical values in the associated column (either an integer or a floating-point number). Any undefined elements in the column or any other IEEE special values in the case of floating-point columns \shall\ be excluded when determining the value of these keywords. \paragraph{\indxkw{TDMIN}{n} keywords.} The value field \shall\ contain a number giving the minimum physical value contained in Column~$n$ of the table. This keyword is analogous to the \kwd{DATAMIN} keyword that is defined for arrays in Sect.~\ref{s:resk}.5. \paragraph{\indxkw{TDMAX}{n} keywords.} The value field \shall\ contain a number giving the maximum physical value contained in Column~$n$ of the table. This keyword is analogous to the \kwd{DATAMAX} keyword that is defined for arrays in Sect.~\ref{s:resk}.5. \paragraph{\indxkw{TLMIN}{n} keywords.} The value field \shall\ contain a number that specifies the minimum physical value in Column~$n$ that has a valid meaning or interpretation. The column is not \required\ to actually contain any elements that have this value, and the column \may\ contain elements with physical values less than \indxkw{TLMIN}{n}, however, the interpretation of any such out-of-range column elements is not defined. \paragraph{\indxkw{TLMAX}{n} keywords.} The value field \shall\ contain a number that specifies the maximum physical value in Column~$n$ that has a valid meaning or interpretation. The column is not \required\ to actually contain any elements that have this value, and the column \may\ contain elements with physical values greater than \indxkw{TLMAX}{n}, however, the interpretation of any such out-of-range column elements is not defined. \paragraph{} The \indxkw{TLMIN}{n} and \indxkw{TLMAX}{n} keywords are commonly used when constructing histograms of the data values in a column. For example, if a table contains columns that give the $X$ and $Y$ pixel location of a list of photons that were detected by a photon-counting device, then the \indxkw{TLMIN}{n} and \indxkw{TLMAX}{n} keywords could be used respectively to specify the minimum and maximum values that the detector is capable of assigning to the $X$ and $Y$ columns. %end{viotext} \subsubsection{Data sequence} %LC lowercased Sequence \label{s:btds} The data in a binary-table extension \shall\ consist of a main data table, which \may, but need not, be followed by additional bytes in the supplemental data area. The positions in the last data block after the last additional byte, or, if there are no additional bytes, the last character of the last row of the main data table, \shall\ be filled\index{fill} by setting all bits to zero. \paragraph{7.3.3.1. Main data table} \label{s:MbinT} \ \newline \ \newline The table is constructed from a two-dimensional byte array. The number of bytes in a row \shall\ be specified by the value of the \kwd{NAXIS1}\index{NAXIS1} keyword and the number of rows \shall\ be specified by the \kwd{NAXIS2}\index{NAXIS2} keyword of the associated header. Within a row, fields \shall\ be stored in order of increasing column number, as determined from the $n$ of the \indxkw{TFORM}{n} keywords. The number of bytes in a row and the number of rows in the table \shall\ determine the size of the byte array. Every row in the array \shall\ have the same number of bytes. The first row \shall\ begin at the start of the data block immediately following the last header block. Subsequent rows \shall\ begin immediately following the end of the previous row, with no intervening bytes, independent of the \FITS\ block structure. Words need not be aligned along word boundaries. Each row in the array \shall\ consist of a sequence of from 0 to 999 fields as specified by the \kwd{TFIELDS} keyword. The number of elements in each field and their data type \shall\ be specified by the \indxkw{TFORM}{n} keyword in the associated header. A separate format keyword \must\ be provided for each field. The location and format of fields \shall\ be the same for every row. Fields \may\ be\index{field, empty} empty, if the repeat count\index{repeat count} specified in the value of the \indxkw{TFORM}{n} keyword of the header is \keyv{0}. Writers of binary tables \should\ select a format appropriate to the form, range of values, and accuracy of the data in the table. The following data types, and no others, are permitted. \paragraph{Logical.} If\index{TFORMn} the value of the \indxkw{TFORM}{n} keyword specifies Data Type~\keyv{'L'}, the contents of Field~$n$ \shall\ consist\index{logical value} of ASCII \texttt{T} indicating true or ASCII \texttt{F}, indicating false. A 0 byte (hexadecimal 00) indicates a NULL value. \paragraph{Bit array.} If the value of the \indxkw{TFORM}{n} keyword specifies data type \keyv{'X'}, the contents of Field~$n$ \shall\ consist of a sequence of bits starting with the most-significant bit; the bits following \shall\ be in order of decreasing significance, ending with the least significant bit. A bit array \shall\ be composed of an integral number of bytes, with those bits following the end of the data set to zero. No null value is defined for bit arrays. \paragraph{Character.} If the value of the \indxkw{TFORM}{n} keyword specifies Data Type~\keyv{'A'}, Field~$n$ \shall\ contain a character string of\index{character string} zero-or-more members, composed of\index{ASCII text} the restricted set of ASCII-text characters. This character string \may\ be terminated before the length specified by the repeat count\index{repeat count} by\index{NULL, ASCII} an ASCII NULL (hexadecimal code 00). Characters after the first ASCII NULL are not defined. A string with the number of characters specified by the repeat count is not NULL terminated. Null strings are defined by the presence of an ASCII NULL as the first character. \paragraph{Unsigned 8-Bit integer.} If\index{TFORMn} the value of the \indxkw{TFORM}{n} keyword specifies Data Type~\keyv{'B'}, the data in Field~$n$ \shall\ consist of unsigned eight-bit integers, with\index{integer, eight-bit} the most-significant bit first, and subsequent bits in order of decreasing significance. Null values are given by the value of the\index{TNULLn} associated \indxkw{TNULL}{n} keyword. Signed integers can be represented using the convention described in Sect.~\ref{s:Unsigned_Integers}. \paragraph{16-Bit integer.} If the value of the \indxkw{TFORM}{n} keyword specifies Data Type~\keyv{'I'}, the data in Field~$n$ \shall\ consist of two's complement\index{two's complement} signed 16-bit integers, contained\index{integer, 16-bit} in two bytes. The most-significant byte \shall\ be\index{byte order}\index{order, byte} first (big-endian byte order). Within each byte the most-significant bit \shall\ be first, and subsequent bits \shall\ be in order of decreasing significance. Null values are given by the value of the\index{TNULLn} associated \indxkw{TNULL}{n} keyword. Unsigned\index{integer, unsigned} integers can be represented using the convention described in Sect.~\ref{s:Unsigned_Integers}. \paragraph{32-Bit integer.} If the value of the \indxkw{TFORM}{n} keyword specifies Data Type~\keyv{'J'}, the data in Field~$n$ \shall\ consist of two's complement\index{two's complement} signed 32-bit integers, contained\index{integer, 32-bit} in four bytes. The most-significant byte \shall\ be first, and subsequent bytes \shall\ be in order of decreasing significance (big-endian byte order). Within each byte, the most-significant bit \shall\ be first, and subsequent bits \shall\ be in order of decreasing significance. Null values are given by the value of the\index{TNULLn} associated \indxkw{TNULL}{n} keyword. Unsigned\index{integer, unsigned} integers can be represented using the convention described in Sect.~\ref{s:Unsigned_Integers}. \paragraph{64-Bit integer.} If the value of the \indxkw{TFORM}{n} keyword specifies Data Type~\keyv{'K'}, the data in Field~$n$ \shall\ consist of two's complement\index{two's complement} signed 64-bit integers, contained\index{integer, 64-bit} in eight bytes. The most-significant byte \shall\ be first, and subsequent bytes \shall\ be in order of decreasing significance. Within each byte, the most-significant bit \shall\ be first, and subsequent bits \shall\ be in order of decreasing significance (big-endian byte order). Null values are given by the value of the\index{TNULLn} associated \indxkw{TNULL}{n} keyword. Unsigned\index{integer, unsigned} integers can be represented using the convention described in Sect.~\ref{s:Unsigned_Integers}. \paragraph{Single-precision floating point.} If\index{TFORMn} the value of the \indxkw{TFORM}{n} keyword specifies Data Type~\keyv{'E'}, the data in Field~$n$ \shall\ consist of\index{ANSI, IEEE} ANSI/IEEE-754 \citep{ieee85} 32-bit floating-point\index{floating-point} numbers, in big-endian byte order, as described in Appendix~\ref{s:IEEE754}. All IEEE special values\index{special values, IEEE} are recognized. The IEEE NaN is\index{NaN, IEEE} used to represent null values. \paragraph{Double-precision floating point.} If the value of the \indxkw{TFORM}{n} keyword specifies Data Type~\keyv{'D'}, the data in Field~$n$ \shall\ consist of ANSI/IEEE-754 \citep{ieee85} 64-bit double-precision floating-point\index{floating-point} numbers, in \index{byte order} \index{order, byte} big-endian byte order, as described in Appendix~\ref{s:IEEE754}. All IEEE special values\index{special values, IEEE} are recognized. The IEEE NaN is\index{NaN, IEEE} used to represent null values. \paragraph{Single precision complex.} If\index{TFORMn} the value of the \indxkw{TFORM}{n} keyword specifies Data Type~\keyv{'C'}, the data in Field~$n$ \shall\ consist of a sequence of pairs of 32-bit\index{complex data} single-precision floating-point\index{floating-point, complex} numbers. The first member of each pair \shall\ represent the real part of a complex number, and the second member \shall\ represent the imaginary part of that complex number. If either member contains an IEEE NaN, the entire complex value is null. \paragraph{Double-precision complex.} If the value of the \indxkw{TFORM}{n} keyword specifies Data Type~\keyv{'M'}, the data in Field~$n$ \shall\ consist of a sequence of pairs of 64-bit double-precision floating-point numbers. The first member of each pair \shall\ represent the real part of a complex number, and the second member of the pair \shall\ represent the imaginary part of that complex number. If either member contains an IEEE NaN,\index{NaN, IEEE} the entire complex value is null. \paragraph{Array descriptor.} The repeat count on the \keyv{P} and \keyv{Q} array-descriptor fields \must\ either have a value of \keyv{0} (denoting an empty field\index{field, empty} of zero bytes) or \keyv{1}. If\index{TFORMn} the value of the \indxkw{TFORM}{n} keyword specifies Data Type~\keyv{'1P'}, the data\index{array descriptor} in Field~$n$ \shall\ consist of one pair of\index{integer, 32-bit} 32-bit integers. If\index{TFORMn} the value of the \indxkw{TFORM}{n} keyword specifies Data Type~\keyv{'1Q'}, the data in Field~$n$ \shall\ consist of one pair of\index{integer, 64-bit} 64-bit integers. The meaning of these integers is defined in Sect.~\ref{s:app_varlen}. \paragraph{7.3.3.2. Bytes following main table} \ \newline \ \newline The main data table \may\ be followed by a supplemental data area called the heap. \index{heap} The size of the supplemental data area, in bytes, is specified by the value of the \kwd{PCOUNT} keyword. The use of this data area is described in Sect.~\ref{s:app_varlen}. \subsubsection{Data display} \label{s:BinDD} The indexed \indxkw{TDISP}{n} keyword \may\ be used to describe the recommended format for displaying an ASCII-text representation of the contents of Field~$n$. The permitted display format codes for each type of data (i.e., character strings, logical, integer, or real) are given in Table~\ref{t:tabD} and described below. \paragraph{Character data.} If the table column contains a character string (with \indxkw{TFORM}{n}~=~\keyv{'rA'}) then the \indxkw{TDISP}{n} format code \must\ be \keyv{Aw\/}, where \keyv{w} is the number of characters to display. If the character datum has length less than or equal to \keyv{w}, it is represented on output right-justified in a string of \keyv{w} characters. If the character datum has length greater than \keyv{w}, the first \keyv{w} characters of the datum are represented on output in a string of \keyv{w} characters. Character data are not surrounded by single- or double-quotation marks unless those marks are themselves part of the data value. \paragraph{Logical data.} If the table column contains logical data (with \indxkw{TFORM}{n}~=~\keyv{'rL'}) then the \indxkw{TDISP}{n} format code \must\ be \keyv{Lw\/}, where \keyv{w} is the width in characters of the display field. Logical\index{logical value} data are represented on output with the character \texttt{T} for true or \texttt{F} for false right-justified in a space-filled string of \keyv{w} characters. A null value \may\ be represented by a string of \keyv{w} space characters. \paragraph{Integer data.} If the table column contains integer data (with \indxkw{TFORM}{n}~=~\keyv{'rX'}, \keyv{'rB'}, \keyv{'rI'}, \keyv{'rJ'}, or \keyv{'rK'}) then the \indxkw{TDISP}{n} format code \may\ have any of these forms: \keyv{Iw.m\/}, \keyv{Bw.m\/}, \keyv{Ow.m\/}, or \keyv{Zw.m\/}. The default value of \keyv{m} is one and the \keyv{'.m'} is \optional. The first letter of the code specifies the number base for the encoding with \keyv{I} for decimal (10), \keyv{B} for binary (2), \keyv{O} for octal (8), and \keyv{Z} for hexadecimal (16). Hexadecimal format uses the upper-case letters A through F to represent decimal values 10 through 15. The output field consists of \keyv{w} characters containing zero-or-more leading spaces followed by a minus sign if the internal datum is negative (only in the case of decimal encoding with the \keyv{I} format code), followed by the magnitude of the internal datum in the form of an unsigned-integer constant in the specified number base, with only as many leading zeros as are needed to have at least \keyv{m} numeric digits. Note that \keyv{m} $\leq$ \keyv{w} is allowed if all values are positive, but \keyv{m} $<$ \keyv{w} is \required\ if any values are negative. If the number of digits required to represent the integer datum exceeds \keyv{w}, then the output field consists of a string of \keyv{w} asterisk (\texttt{*}) characters. \paragraph{Real data.} If the table column contains real data (with \indxkw{TFORM}{n}~=~\keyv{'rE'}, or \keyv{'rD'}) or contains integer data (with any of the \indxkw{TFORM}{n} format codes listed in the previous paragraph), which are \recommended\ to be displayed as real values (i.e., especially in cases where the integer values represent scaled physical values using Eq.~\ref{eq:tscl}), then the \indxkw{TDISP}{n} format code \may\ have any of these forms: \keyv{Fw.d\/}, \keyv{Ew.dEe\/}, \keyv{Dw.dEe\/}, \keyv{ENw.d\/}, or \keyv{ESw.d\/}. In all cases, the output is a string of \keyv{w} characters including the decimal point, any sign characters, and any exponent including the exponent's indicators, signs, and values. If the number of digits required to represent the real datum exceeds \keyv{w}, then the output field consists of a string of \keyv{w} asterisk (\texttt{*}) characters. In all cases, \keyv{d} specifies the number of digits to appear to the right of the decimal point. The \keyv{F} format code output field consists of $\keyv{w} - \keyv{d} - 1$ characters containing zero-or-more leading spaces, followed by a minus sign if the internal datum is negative, followed by the absolute magnitude of the internal datum in the form of an unsigned-integer constant. These characters are followed by a decimal point (\keyv{'.'}) and \keyv{d} characters giving the fractional part of the internal datum, rounded by the normal rules of arithmetic to \keyv{d} fractional digits. For the \keyv{E} and \keyv{D} format codes, an exponent is taken such that the fraction $0.1 \le |\mathrm{datum}| / 10^\mathrm{exponent} < 1.0$. The fraction (with appropriate sign) is output with an \keyv{F} format of width $ \keyv{w} - \keyv{e} - 2$ characters with \keyv{d} characters after the decimal followed by an \keyv{E} or \keyv{D} followed by the exponent as a signed $\keyv{e} + 1$ character integer with leading zeros as needed. The default value of \keyv{e} is \keyv{2} when the \keyv{Ee} portion of the format code is omitted. If the exponent value will not fit in $\keyv{e} + 1$ characters but will fit in $\keyv{e} + 2$ then the \keyv{E} (or \keyv{D}) is omitted and the wider field used. If the exponent value will not fit (with a sign character) in $\keyv{e} + 2$ characters, then the entire \keyv{w}-character output field is filled with asterisks (\texttt{*}). The \keyv{ES} format code is processed in the same manner as the \keyv{E} format code except that the exponent is taken so that $ 1.0 \leq \mathrm{fraction} < 10$. The \keyv{EN} format code is processed in the same manner as the \keyv{E} format code except that the exponent is taken to be an integer multiple of three and so that $ 1.0\leq \mathrm{fraction} < 1000.0$. All real format codes have number base 10. There is no difference between \keyv{E} and \keyv{D} format codes on input other than an implication with the latter of greater precision in the internal datum. The \keyv{Gw.dEe\/} format code \may\ be used with data of any type. For data of type integer, logical, or character, it is equivalent to \keyv{Iw}, \keyv{Lw}, or \keyv{Aw}, respectively. For data of type real, it is equivalent to an \keyv{F} format (with different numbers of characters after the decimal) when that format will accurately represent the value and is equivalent to an \keyv{E} format when the number (in absolute value) is either very small or very large. Specifically, for real values outside the range $0.1\,-\,0.5\!\times\! 10^{-\texttt{d}-1} \leq \mathrm{value} < 10^\texttt{d}\,-\,0.5$, it is equivalent to \keyv{Ew.dEe}. For real values within the above range, it is equivalent to \keyv{F}{$\keyv{w}^{\prime}.\keyv{d}^{\prime}\,$} followed by $2 + \keyv{e}$ spaces, where $\keyv{w}^{\prime} = \keyv{w} - \keyv{e} - 2$ and $\keyv{d}^{\prime} = \keyv{d} - k$ for $k = 0,1,\ldots,\keyv{d}$ if the real datum value lies in the range $10^{k-1} \left(1\,-\, 0.5\!\times\!10^{-\keyv{d}}\right) \leq \mathrm{value} \le 10^k \left(1\,-\, 0.5\!\times\!10^{-\keyv{d}}\right)$. \paragraph{Complex data.} If the table column contains complex data \index{complex data} (with \indxkw{TFORM}{n}~=~\keyv{'rC'}, or \keyv{'rM'}) then they \may\ be displayed with any of the real data formats as described above. The same format is used for the real and imaginary parts. It is \recommended\ that the two values be separated by a comma and enclosed in parentheses with a total field width of $2\keyv{w} + 3$. \subsubsection{Variable-length arrays} \label{s:app_varlen} One of the most attractive features of binary tables is that any field of the table can be an array. In the standard case this is a fixed-size array, i.e., a fixed amount of storage is allocated in each row for the array data---whether it is used or not. This is fine so long as the arrays are small or a fixed amount of array data will be stored in each field, but if the stored array length varies for different rows, it is necessary to impose a fixed upper limit on the size of the array that can be stored. If this upper limit is made too large excessive wasted space can result and the binary-table mechanism becomes seriously inefficient. If the limit is set too low then storing certain types of data in the table could become impossible. The variable-length array construct\index{array, variable-length} presented here\index{variable-length array} was devised to deal with this problem. Variable-length arrays are implemented in such a way that, even if a table contains such arrays, a simple reader program that does not understand variable-length arrays will still be able to read the main data table (in other words a table containing variable-length arrays conforms to the basic binary-table standard). The implementation chosen is such that the rows in the main data table remain fixed in size even if the table contains a variable-length array field, allowing efficient random access to the main data table. Variable-length arrays are logically equivalent to regular static arrays, the only differences being 1) the length of the stored array can differ for different rows, and 2) the array data are not stored directly in the main data table. Since a field of any data type can be a static array, a field of any data type can also be a variable-length array (excluding the Type~\keyv{P} and \keyv{Q} variable-length array descriptors\index{array descriptor} themselves, which are not a data type so much as a storage-class specifier). Other established \FITS\ conventions that apply to static arrays will generally apply as well to variable-length arrays. A variable-length array is declared in the table header with one of the following two special field data-type specifiers % \[ r\mbox{\texttt{P}}t\mbox{(}maxelem\mbox{)} \] \[ \keyv{$r$P$t$($e_\mathrm{max}$)} \] \[ \keyv{$r$Q$\,t$($e_\mathrm{max}$)} \] where the \keyv{'P'} or \keyv{'Q'} indicates the presence of an array descriptor (described below), the element count \keyv{$r$} \should\ be \keyv{0}, \keyv{1}, or absent, \keyv{$t$} is a character denoting the data type of the array data (\keyv{L}, \keyv{X}, \keyv{B}, \keyv{I}, \keyv{J}, \keyv{K}, etc., but not \keyv{P} or \keyv{Q}), and \keyv{$e_\mathrm{max}$} is a quantity guaranteed to be equal to or greater than the maximum number of elements of type \keyv{$t$} actually stored in any row of the table. There is no built-in upper limit on the size of a stored array (other than the fundamental limit imposed by the range of the array descriptor, defined below); \keyv{$e_\mathrm{max}$} merely reflects the size of the largest array actually stored in the table, and is provided to avoid the need to preview the table when, for example, reading a table containing variable-length elements into a database that supports only fixed-size arrays. There \may\ be additional characters in the \indxkw{TFORM}{n} keyword following\index{TFORMn} the \keyv{$e_\mathrm{max}$}. For example, \[\mbox{\texttt{TFORM8 = 'PB(1800)' / Variable byte array}} \] indicates that Field~8 of the table is a variable-length array of type byte, with a maximum stored array length not to exceed 1800 array elements (bytes in this case). The data for the variable-length arrays in a table are not stored in the main data table; they are stored in a supplemental data area, the heap\index{heap}, following the main data table. What is stored in the main data table field is an {\em array descriptor}.\index{array descriptor} This consists of two 32-bit signed integer values in the case of \keyv{'P'} array descriptors, or two 64-bit signed integer values in the case of \keyv{'Q'} array descriptors: the number of elements (array length) of the stored array, followed by the zero-indexed byte offset of the first element of the array, measured from the start of the heap area. The meaning of a negative value for either of these integers is not defined by this Standard. Storage for the array is contiguous. The array descriptor for Field~$N$ as it would appear embedded in a table row is illustrated symbolically below. \begin{center} $\ldots$ [Field~$N$--1] [(nelem,offset)] [Field~$N$+1] $\ldots$ \end{center} If the stored array length is zero, there is no array data, and the offset value is undefined (it \should\ be set to zero). The storage referenced by an array descriptor \must\ lie entirely within the heap area; negative offsets are not permitted. A binary table containing variable-length arrays consists of three principal segments, as follows. %\[ [table\_header] [row\_storage\_area] [heap\_area] \] \begin{center} [table header] [main data table] (optional gap) [heap area] \end{center} The table header consists of one or more 2880-byte header blocks with the last block indicated by the\index{END} keyword \kwd{END} somewhere in the block. The main data table begins with the first data block following the last header block and is $\mbox{\kwd{NAXIS1}} \times \mbox{\kwd{NAXIS2}}$ bytes in length. The\index{NAXIS1} zero\index{NAXIS2}-indexed byte offset to the start of the heap, measured from the start of the main data table, \may\ be given by the \kwd{THEAP} keyword\index{THEAP} in the header. If this keyword is missing then the heap begins with the byte immediately following main data table (i.e., the default value of \kwd{THEAP} is $\mbox{\kwd{NAXIS1}} \times \mbox{\kwd{NAXIS2}}$). This default value is the minimum allowed value for the \kwd{THEAP} keyword, because any smaller value would imply that the heap and the main data table overlap. If the \kwd{THEAP} keyword has a value larger than this default value, then there is a gap between the end of the main data table and the start of the heap. The total length in bytes of the supplemental data area following the main data table (gap plus heap) is given by the \kwd{PCOUNT} keyword\index{PCOUNT} in the table header. For example, suppose a table contains five rows that are each 168 bytes long, with a heap area 3000 bytes long, beginning at an offset of 2880, thereby aligning the main data table and heap areas on data block boundaries (this alignment is not necessarily recommended but is useful for this example). The data portion of the table consists of three 2880-byte data blocks: the first block contains the 840 bytes from the five rows of the main data table followed by 2040 fill\index{fill} bytes; the heap completely fills the second block; the third block contains the remaining 120 bytes of the heap followed by 2760 fill bytes. \kwd{PCOUNT} gives the total number of bytes from the end of the main data table to the end of the heap, and in this example has a value of $2040 + 2880 + 120 = 5040$. This is expressed in the table header as shown below. \begin{verbatim} NAXIS1 = 168 / Width of table row in bytes NAXIS2 = 5 / Number of rows in table PCOUNT = 5040 / Random parameter count ... THEAP = 2880 / Byte offset of heap area \end{verbatim} \vskip 1em The values\index{TSCALn} of \indxkw{TSCAL}{n} and \indxkw{TZERO}{n} for\index{TZEROn} variable-length array column entries are to be applied to the values in the data array in the heap area, not the values of the array descriptor. These keywords can be used to scale data values in either static or variable-length arrays. \subsubsection{Variable-length-array guidelines} While the above description is sufficient to define the required features of the variable-length array implementation, some hints regarding usage of the variable-length array\index{array, variable-length} facility \index{variable-length array} might also be useful. Programs that read binary tables should take care to not assume more about the physical layout of the table than is \required\ by the specification. For example, there are no requirements on the alignment of data within the heap. \index{heap} If efficient runtime access is a concern one might want to design the table so that data arrays are aligned to the size of an array element. In another case one might want to minimize storage and forgo any efforts at alignment (by careful design it is often possible to achieve both goals). Variable-length array data \may\ be stored in the heap in any order, i.e., the data for row $N$+1 are not necessarily stored at a larger offset than that for row $N$. There \may\ be gaps in the heap where no data are stored. Pointer aliasing is permitted, i.e., the array descriptors\index{array descriptor} for two or more arrays \may\ point to the same storage location (this could be used to save storage if two or more arrays are identical). Byte arrays are a special case because they can be used to store a `typeless' data sequence. Since \FITS\ is a machine-independent storage format, some form of machine-specific data conversion (byte swapping, floating-point format conversion) is implied when accessing stored data with types such as integer and floating, but byte arrays are copied to and from external storage without any form of conversion. An important feature of variable-length arrays is that it is possible that the stored array length \may\ be zero. This makes it possible to have a column of the table for which, typically, no data are present in each stored row. When data are present, the stored array can be as large as necessary. This can be useful when storing complex objects as rows in a table. Accessing a binary table stored on a random-access storage medium is straightforward. Since the rows of data in the main data table are fixed in size they can be randomly accessed given the row number, by computing the offset. Once the row has been read in, any variable-length array data can be directly accessed using the element count and offset given by the array descriptor stored in that row. Reading a binary table stored on a sequential-access storage medium requires that a table of array descriptors\index{array descriptor} be built up as the main data table rows are read in. Once all the table rows have been read, the array descriptors are sorted by the offset of the array data in the heap. As the heap data are read, arrays are extracted sequentially from the heap and stored in the affected rows using the back pointers to the row and field from the table of array descriptors. Since array aliasing is permitted, it might be necessary to store a given array in more than one field or row. Variable-length arrays\index{variable-length array} are more complicated than\index{array, variable-length} regular static arrays and might not be supported by some software systems. The producers of \FITS\ data products should consider the capabilities of the likely recipients of their files when deciding whether or not to use this format, and as a general rule should use it only in cases where it provides significant advantages over the simpler fixed-length array format. In particular, the use of variable-length arrays might present difficulties for applications that ingest the \FITS\ file via a sequential input stream, because the application cannot fully process any rows in the table until after the entire fixed-length table, and potentially the entire heap has been transmitted as outlined in the previous paragraph. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \section{World-coordinate systems} \label{s:WCS} Representations of\index{WCS} the mapping\index{coordinate systems} between image coordinates and physical (i.e., world) coordinate systems (WCSs) \may\ be represented within \FITS\ HDUs. The keywords that are used to express these mappings are now rigorously defined in a series of papers on world-coordinate systems \citep{greisen02}, celestial-coordinate systems \citep{calabretta02}, spectral-coordinate systems \citep{greisen06}, and % Added for v3.1: %\begin{redtext} time-coordinate systems \citep{rots15}. %\end{redtext} An additional spherical projection, called HEALPix, is defined in reference \citep{calabretta07}. These WCS papers have been formally approved by the IAUFWG\index{IAUFWG} and therefore are {\em incorporated by reference} as an official part of this Standard. The reader should refer to these papers for additional details and background information that cannot be included here. Various updates and corrections to the primary WCS papers have been compiled by the authors, and are reflected in this section. Therefore, where conflicts exist, the description in this Standard will prevail. \subsection{Basic concepts} Rather than store world coordinates separately for each datum, the regular lattice structure of a \FITS\ image offers the possibility of defining rules for computing world coordinates at each point. As stated in Sect.~\ref{s:pdata} and depicted in Fig.~\ref{f:array}, image array data are addressed via {\em integral array indices} that range in value from 1 to \indxkw{NAXIS}{j} on Axis~$j$. Recognizing that image data values may have an extent, for example an angular separation, spectral channel width or time span, and thus that it may make sense to interpolate between them, these integral array indices \may\ be generalized to floating-point {\em pixel coordinates}. Integral pixel-coordinate values coincide with the corresponding array indices, while fractional pixel-coordinate values lie between array indices and thus imply interpolation. Pixel-coordinate values are defined at all points within the image lattice and outside it (except along {\em conventional} axes, see Sect.~\ref{sect:ConvCoord}). They form the basis of the world-coordinate formalism in \FITS\ depicted schematically in Fig.~\ref{fig:px2wld}. The essence of representing world-coordinate systems in \FITS\ is the association of various reserved keywords with elements of a transformation (or a series of transformations), or with parameters of a projection function. The conversion from pixel coordinates in the data array to world coordinates is simply a matter of applying the specified transformations (in order) via the appropriate keyword values; conversely, defining a WCS for an image amounts to solving for the elements of the transformation matrix(es) or coefficients of the function(s) of interest and recording them in the form of WCS keyword values. The description of the WCS systems and their expression in \FITS\ HDUs is quite extensive and detailed, but is aided by a careful choice of notation. Key elements of the notation are summarized in Table~\ref{ta:Notation}, and are used throughout this section. The formal definitions of the keywords appear in the following subsections. % Table 21 \begin{table*} \centering \caption{WCS and celestial coordinates notation.} \label{ta:Notation} \begin{tabular}{lll} \hline \hline Variable(s) & {Meaning} & Related \FITS\ keywords \\ \hline \noalign{\smallskip} $i$ & Index variable for world coordinates & \\ $j$ & Index variable for pixel coordinates & \\ $a$ & Alternative WCS version code & \\ $p_j$ & Pixel coordinates & \\ $r_j$ & Reference pixel coordinates & \indxkwdalt{CRPIX}{j} \\ $m_{ij}$ & Linear-transformation matrix & \indxkwdalt{CD}{i\_j} or \indxkwdalt{PC}{i\_j} \\ $s_i$ & Coordinate scales & \indxkwdalt{CDELT}{i} \\ ($x, y$) & Projection plane coordinates & \\ ($\phi, \theta$) & Native longitude and latitude & \\ ($\alpha, \delta$) & Celestial longitude and latitude & \\ ($\phi_0, \theta_0$) & Native longitude and latitude of the fiducial point & \kwdalt{PV\textit{i}\_1}\tablefootmark{\dag}, \kwdalt{PV\textit{i}\_2}\tablefootmark{\dag} \\ ($\alpha_0, \delta_0$) & Celestial longitude and latitude of the fiducial point & \indxkwdalt{CRVAL}{i} \\ ($\alpha_p, \delta_p$) & Celestial longitude and latitude of the native pole & \\ ($\phi_p, \theta_p$) & Native longitude and latitude of the celestial pole & \kwdalt{LONPOLE} (=\kwdalt{PV\textit{i}\_3}\tablefootmark{\dag}), \\ & & \kwdalt{LATPOLE} (=\kwdalt{PV\textit{i}\_4}\tablefootmark{\dag}) \\ % \noalign{\smallskip} \hline \end{tabular} \tablefoot{ \dag \ Associated with \textit{Longitude} Axis~$i$.} \end{table*} The conversion of image pixel coordinates to world coordinates is a multi-step process, as illustrated in Fig.~\ref{fig:px2wld}. % Figure 2 \begin{figure}[t] \begin{center} %\includegraphics[scale=0.50]{WCSfig.pdf} \leavevmode \epsfysize=9.0cm \epsffile{WCSfig.eps} \caption{A schematic view of converting pixel coordinates to world coordinates.} \label{fig:px2wld} \end{center} \end{figure} % For all coordinate types, the first step is a linear transformation applied via matrix multiplication of the vector of pixel-coordinate elements, $p_j$: \begin{equation} q_i = \sum_{j=1}^{N} m_{ij} (p_j - r_j) \label{eq:pix2intpix} \end{equation} where $r_j$ are the pixel-coordinate elements of the reference point, $j$ indexes the pixel axis, and $i$ the world axis. The $m_{ij}$ matrix is a non-singular, square matrix of dimension $N\times N$, where $N$ is the number of world-coordinate axes. % Often, $N$ is given by the \kwd{NAXIS} keyword, but this will be generalized with % the discussion of the \kwd{WCSAXES} keyword, below. The elements $q_i$ of the resulting \textit{intermediate pixel coordinate} vector are offsets, in dimensionless pixel units, from the reference point along axes coincident with those of the \textit{intermediate world coordinates}. Thus, the conversion of $q_i$ to the corresponding Intermediate-world-coordinate Element $x_i$ is a simple scale: \begin{equation} x_i = s_iq_i. \label{eq:intpix2intworld} \end{equation} There are three conventions for associating \FITS\ keywords with the above transformations. In the first formalism, the matrix elements $m_{ij}$ are encoded in the \indxkw{PC}{i\_j} keywords and the scale factors $s_i$ are encoded in the \indxkw{CDELT}{i} keywords, which \must\ have non-zero values. In the second formalism Eqs.~(\ref{eq:pix2intpix}) and (\ref{eq:intpix2intworld}) are combined as \begin{equation} x_i = \sum_{j=1}^{N} (s_i m_{ij}) (p_j - r_j) \label{eq:pix2intworld} \end{equation} and the \indxkw{CD}{i\_j} keywords encode the product $s_i m_{ij}$. The third convention was widely used before the development of the two previously described conventions and uses the \indxkw{CDELT}{i} keywords to define the image scale and the \kwd{CROTA2} keyword to specify a bulk rotation of the image plane. Use of the \kwd{CROTA2} keyword is now deprecated, \index{deprecate} and instead the newer \indxkw{PC}{i\_j} or \indxkw{CD}{i\_j} keywords are \recommended\ because they allow for skewed axes and fully general rotation of multi-dimensional arrays.\index{array, multi-dimensional} The \indxkw{CDELT}{i} and \kwd{CROTA2} keywords \may\ co-exist with the \indxkw{CD}{i\_j} keywords (but the \kwd{CROTA2} \mustnot\ occur with the \indxkw{PC}{i\_j} keywords) as an aid to old \FITS\ interpreters, but these keywords \must\ be ignored by software that supports the \indxkw{CD}{i\_j} keyword convention. In all these formalisms the reference pixel coordinates $r_j$ are encoded in the \indxkw{CRPIX}{i} keywords, and the world coordinates at the reference point are encoded in the \indxkw{CRVAL}{i} keywords. For additional details, see \cite{greisen02}. The third step of the process, computing the final world coordinates, depends on the type of coordinate system, which is indicated with the value of the \indxkw{CTYPE}{i} keyword. For some simple, linear cases an appropriate choice of normalization for the scale factors allows the world coordinates to be taken directly (or by applying a constant offset) from the $x_i$ (e.g., some spectra). In other cases it is more complicated, and may require the application of some non-linear algorithm (e.g., a projection, as for celestial coordinates), which may require the specification of additional parameters. Where necessary, numeric parameter values for non-linear algorithms \must\ be specified via \indxkw{PV}{i\_m} keywords and character-valued parameters will be specified via \indxkw{PS}{i\_m} keywords, where $m$ is the parameter number. The application of these formalisms to coordinate systems of interest is discussed in the following sub-sections: Sect.~\ref{sect:WCSkw} describes general WCS representations \citep[see][]{greisen02}, Sect.~\ref{sect:Celestkw} describes celestial-coordinate systems \citep[see][]{calabretta02}), Sect.~\ref{sect:SPECkw} describes spectral-coordinate systems \citep[see][]{greisen06}, %\begin{redtext} and Sect.~\ref{sect:timeReps} describes the representation of time coordinates \citep[see][]{rots15}. %LC Dick suggested to move "Conventional coordinate types" up here %LC but suggestion was later withdrawn (mail #24 May 15) %\end{redtext} \subsection{World-coordinate-system representations}\label{sect:WCSkw} A variety of keywords have been reserved\index{keyword, reserved} for computing the coordinate values that are to be associated with any pixel location within an array. The full set is given in Table~\ref{ta:WCSkw}; those in most common usage are defined in detail below for convenience. Coordinate-system specifications \may\ appear in HDUs that contain simple images in the primary array or in an \IMAGE\ extension. Images \may\ also be stored in a multi-dimensional vector\index{array, multi-dimensional} cell of a binary table, or as a tabulated list of pixel locations (and optionally, the pixel value) in a table. In these last two types of image representations, the WCS keywords have a different naming convention, which reflects the needs of the tabular data structure and the eight-character limit for keyword lengths, but otherwise follow exactly the same rules for type, usage, and default values. See reference \cite{calabretta02} for example usage of these keywords. All forms of these reserved keywords \must\ be used only as specified in this Standard. %LC Bill start %begin{gretext} %% In the case of the binary-table vector representation, all the images contained in a %% given column of the table may not necessarily have the same coordinate-transformation %% values. For example, the pixel location of the reference point may be different for %% each image/row in the table, in which case a single \kwd{1CRPn} keyword in the header %% is not sufficient to record the individual value required for each image. In such cases, %% the keyword \must\ be replaced by a column with the same name (i.e. \indxkw{TTYPE}{m}~=~\keyv{'1CRPn'}), %% which can then be used to store the pixel location of the reference point appropriate for %% each row of the table. This convention for expanding a keyword into a table column %% (or conversely, collapsing a column of identical values into a single header keyword) %% is commonly known as part of the "Green Bank Convention''\footnote{Named after a %% meeting held in Green Bank, West Virginia, USA in 1989 to develop standards %% for the interchange of single-dish radio-astronomy data.} for \FITS\ keywords. %% \label{s:greenbank}\index{Green Bank convention} %% This usage is illustrated in the example header shown in Table 9 of %% \cite{calabretta02}, In the case of the binary-table vector representation, it is possible that the images contained in a given column of the table have different coordinate transformation values. Table 9 of \cite{calabretta02} illustrates a technique (commonly known as the ``Green Bank Convention\footnote{Named after a meeting held in Green Bank, West Virginia, USA in 1989 to develop standards for the interchange of single-dish radio-astronomy data.}''), which utilizes additional columns in the table to record the coordinate-transformation values that apply to the corresponding image in each row of the table. \label{s:greenbank}\index{Green Bank convention} More information is provided in Appendix~\ref{sect:GBC}. %end{gretext} % Modified by RAS 2015-June for v3.1+ (Time/WCS) %% Complete table of WCS reserved keywords Table "24" aka 22 %onecolumn \begin{table*} \begin{center} %begin{redtext} \caption{Reserved WCS keywords \label{ta:WCSkw} (continues on next page)} %\begin{tabular}{l l l l | l l} \begin{tabular}{l l l l l l l} \hline \hline & & & \multicolumn{2}{c}{\BINTABLE\ vector} & \multicolumn{2}{c}{Pixel list} \\ {Keyword Description} & {Global} & {Image} & {Primary} & {Alternative} & {Primary} & {Alternative} \\ \hline \noalign{\smallskip} % Start of table data Coordinate dimensionality & & \kwdalt{WCSAXES} & \multicolumn{2}{c}{\indxkwdalt{WCAX}{n}} & \multicolumn{2}{c}{\ldots} \\ Axis type & & \indxkwdalt{CTYPE}{i} & \dindxkw{i}{CTYP}{n} & \dindxkw{i}{CTY}{na} & \indxkw{TCTYP}{n} & \indxkwdalt{TCTY}{n} \\ Axis units & & \indxkwdalt{CUNIT}{i} & \dindxkw{i}{CUNI}{n} & \dindxkw{i}{CUN}{na} & \indxkw{TCUNI}{n} & \indxkwdalt{TCUN}{n} \\ Reference value & & \indxkwdalt{CRVAL}{i} & \dindxkw{i}{CRVL}{n} & \dindxkw{i}{CRV}{na} & \indxkw{TCRVL}{n} & \indxkwdalt{TCRV}{n} \\ Coordinate increment & & \indxkwdalt{CDELT}{i} & \dindxkw{i}{CDLT}{n} & \dindxkw{i}{CDE}{na} & \indxkw{TCDLT}{n} & \indxkwdalt{TCDE}{n} \\ Reference point & & \indxkwdalt{CRPIX}{j} & \dindxkw{j}{CRPX}{n} & \dindxkw{j}{CRP}{na} & \indxkw{TCRPX}{n} & \indxkwdalt{TCRP}{n} \\ Coordinate rotation\tablefootmark{1} & & \indxkw{CROTA}{i} & \dindxkw{i}{CROT}{n} & & \indxkw{TCROT}{n} & \\ Transformation matrix\tablefootmark{2} & & \indxkwdalt{PC}{i\_j} & \multicolumn{2}{c}{\dindxkwalt{ij}{PC}{n}} & \multicolumn{2}{c}{\indxkwdalt{TPC}{n\_k} or \indxkwdalt{TP}{n\_k}} \\ Transformation matrix\tablefootmark{2} & & \indxkwdalt{CD}{i\_j} & \multicolumn{2}{c}{\dindxkwalt{ij}{CD}{n}} & \multicolumn{2}{c}{\indxkwdalt{TCD}{n\_k} or \indxkwdalt{TC}{n\_k}} \\ Coordinate parameter & & \indxkwdalt{PV}{i\_m} & \multicolumn{2}{c}{\dindxkwalt{i}{PV}{n\_m} or \dindxkwalt{i}{V}{n\_m}} & \multicolumn{2}{c}{\indxkwdalt{TPV}{n\_m} or \indxkwdalt{TV}{n\_m}} \\ Coordinate parameter array & & \ldots & \multicolumn{2}{c}{\dindxkw{i}{V}{n}\kwdalt{\_X}} & \multicolumn{2}{c}{...} \\ Coordinate parameter & & \indxkwdalt{PS}{i\_m} & \multicolumn{2}{c}{\dindxkwalt{i}{PS}{n\_m} or \dindxkwalt{i}{S}{n\_m}} & \multicolumn{2}{c}{\indxkwdalt{TPS}{n\_m} or \indxkwdalt{TS}{n\_m}} \\ Coordinate name & & \kwdalt{WCSNAME} & \multicolumn{2}{c}{\indxkwdalt{WCSN}{n}} & \multicolumn{2}{c}{\indxkwdalt{WCS}{n} or \indxkwdalt{TWCS}{n}} \\ Coordinate axis name & & \indxkwdalt{CNAME}{i} & \multicolumn{2}{c}{\dindxkwalt{i}{CNA}{n}} & \multicolumn{2}{c}{\indxkwdalt{TCNA}{n}} \\ Random error & & \indxkwdalt{CRDER}{i} & \multicolumn{2}{c}{\dindxkwalt{i}{CRD}{n}} & \multicolumn{2}{c}{\indxkwdalt{TCRD}{n}} \\ Systematic error & & \indxkwdalt{CSYER}{i} & \multicolumn{2}{c}{\dindxkwalt{i}{CSY}{n}} & \multicolumn{2}{c}{\indxkwdalt{TCSY}{n}} \\ WCS cross-reference target & & \ldots & \multicolumn{2}{c}{\indxkwdalt{WCST}{n}} & \multicolumn{2}{c}{...} \\ WCS cross reference & & \ldots & \multicolumn{2}{c}{\indxkwdalt{WCSX}{n}} & \multicolumn{2}{c}{...} \\ Coordinate rotation & & \kwdalt{LONPOLE} & \multicolumn{2}{c}{\indxkwdalt{LONP}{n}} & \multicolumn{2}{c}{\indxkwdalt{LONP}{n}} \\ Coordinate rotation & & \kwdalt{LATPOLE} & \multicolumn{2}{c}{\indxkwdalt{LATP}{n}} & \multicolumn{2}{c}{\indxkwdalt{LATP}{n}} \\ Coordinate epoch & & \kwdalt{EQUINOX} & \multicolumn{2}{c}{\indxkwdalt{EQUI}{n}} & \multicolumn{2}{c}{\indxkwdalt{EQUI}{n}} \\ Coordinate epoch\tablefootmark{3} & \kwd{EPOCH} & & \multicolumn{2}{c}{\kwd{EPOCH}} & \multicolumn{2}{c}{\kwd{EPOCH}} \\ Reference frame & \kwd{RADECSYS}\tablefootmark{4} & \kwdalt{RADESYS} & \multicolumn{2}{c}{\indxkwdalt{RADE}{n}} & \multicolumn{2}{c}{\indxkwdalt{RADE}{n}} \\ Line rest frequency (Hz) & \kwd{RESTFREQ}\tablefootmark{4} & \kwdalt{RESTFRQ} & \multicolumn{2}{c}{\indxkwdalt{RFRQ}{n}} & \multicolumn{2}{c}{\indxkwdalt{RFRQ}{n}} \\ Line rest vacuum wavelength (m) & & \kwdalt{RESTWAV} & \multicolumn{2}{c}{\indxkwdalt{RWAV}{n}} & \multicolumn{2}{c}{\indxkwdalt{RWAV}{n}} \\ Spectral reference frame & & \kwdalt{SPECSYS} & \multicolumn{2}{c}{\indxkwdalt{SPEC}{n}} & \multicolumn{2}{c}{\indxkwdalt{SPEC}{n}} \\ Spectral reference frame & & \kwdalt{SSYSOBS} & \multicolumn{2}{c}{\indxkwdalt{SOBS}{n}} & \multicolumn{2}{c}{\indxkwdalt{SOBS}{n}} \\ Spectral reference frame & & \kwdalt{SSYSSRC} & \multicolumn{2}{c}{\indxkwdalt{SSRC}{n}} & \multicolumn{2}{c}{\indxkwdalt{SSRC}{n}} \\ Observation X (m) & \kwd{OBSGEO-X}\tablefootmark{5} & & \multicolumn{2}{c}{\indxkw{OBSGX}{n}} & \multicolumn{2}{c}{\indxkw{OBSGX}{n}} \\ Observation Y (m) & \kwd{OBSGEO-Y}\tablefootmark{5} & & \multicolumn{2}{c}{\indxkw{OBSGY}{n}} & \multicolumn{2}{c}{\indxkw{OBSGY}{n}} \\ Observation Z (m) & \kwd{OBSGEO-Z}\tablefootmark{5} & & \multicolumn{2}{c}{\indxkw{OBSGZ}{n}} & \multicolumn{2}{c}{\indxkw{OBSGZ}{n}} \\ Radial velocity (m s$^{-1}$) & & \kwdalt{VELOSYS} & \multicolumn{2}{c}{\indxkwdalt{VSYS}{n}} & \multicolumn{2}{c}{\indxkwdalt{VSYS}{n}} \\ Redshift of source & & \kwdalt{ZSOURCE} & \multicolumn{2}{c}{\indxkwdalt{ZSOU}{n}} & \multicolumn{2}{c}{\indxkwdalt{ZSOU}{n}} \\ Angle of true velocity & & \kwdalt{VELANGL} & \multicolumn{2}{c}{\indxkwdalt{VANG}{n}} & \multicolumn{2}{c}{\indxkwdalt{VANG}{n}} \\ \hline \multicolumn{7}{c}{Date-time related keywords (see Sect.\ref{sect:timeReps})} \\ \hline \noalign{\smallskip} % The following keywords are re-ordered from above or added for v3.1 %\cutinhead{Time WCS Keywords} Date of HDU creation & \kwd{DATE} & & & & & \\ Date/time of observation & \kwd{DATE-OBS} & & \multicolumn{2}{c}{\indxkw{DOBS}{n}} & \multicolumn{2}{c}{\indxkw{DOBS}{n}} \\ & \kwd{MJD-OBS} & & \multicolumn{2}{c}{\indxkw{MJDOB}{n}} & \multicolumn{2}{c}{\indxkw{MJDOB}{n}} \\ & \kwd{BEPOCH} & & & & & \\ & \kwd{JEPOCH} & & & & & \\ Average date/time of observation & \kwd{DATE-AVG} & & \multicolumn{2}{c}{\indxkw{DAVG}{n}} & \multicolumn{2}{c}{\indxkw{DAVG}{n}} \\ & \kwd{MJD-AVG} & & \multicolumn{2}{c}{\indxkw{MJDA}{n}} & \multicolumn{2}{c}{\indxkw{MJDA}{n}} \\ Start date/time of observation & \kwd{DATE-BEG} & & & & & \\ & \kwd{MJD-BEG} & & & & & \\ & \kwd{TSTART} & & & & & \\ End date/time of observation & \kwd{DATE-END} & & & & & \\ & \kwd{MJD-END} & & & & & \\ & \kwd{TSTOP} & & & & & \\ Net exposure duration & \kwd{XPOSURE} & & & & & \\ Wall-clock exposure duration & \kwd{TELAPSE} & & & & & \\ %%%%%%%%% Time scale & \kwd{TIMESYS} & \indxkwdalt{CTYPE}{i} & \dindxkw{i}{CTYP}{n} & \dindxkw{i}{CTY}{na} & \indxkw{TCTYP}{n} & \indxkwdalt{TCTY}{n} \\ Time zero point (MJD) & \kwd{MJDREF}\tablefootmark{6} & & & & & \\ Time zero point (JD) & \kwd{JDREF}\tablefootmark{6} & & & & & \\ Time zero point (ISO) & \kwd{DATEREF} & & & & & \\ Reference position & \kwd{TREFPOS} & & \multicolumn{2}{c}{\indxkw{TRPOS}{n}} & \multicolumn{2}{c}{\indxkw{TRPOS}{n}} \\ Reference direction & \kwd{TREFDIR} & & \multicolumn{2}{c}{\indxkw{TRDIR}{n}} & \multicolumn{2}{c}{\indxkw{TRDIR}{n}} \\ Solar System ephemeris & \kwd{PLEPHEM} & & & & & \\ Time unit & \kwd{TIMEUNIT} & \indxkwdalt{CUNIT}{i} & \dindxkw{i}{CUNI}{n} & \dindxkw{i}{CUN}{na} & \indxkw{TCUNI}{n} & \indxkwdalt{TCUN}{n} \\ Time offset & \kwd{TIMEOFFS} & & & & & \\ Time absolute error & \kwd{TIMSYER} & \indxkwdalt{CSYER}{i} & \dindxkw{i}{CSYE}{n} & \dindxkwalt{i}{CSY}{n} & \indxkw{TCSY}{n} & \indxkwdalt{TCSY}{n} \\ Time relative error & \kwd{TIMRDER} & \indxkwdalt{CRDER}{i} & \dindxkw{i}{CRDE}{n} & \dindxkwalt{i}{CRD}{n} & \indxkw{TCRD}{n} & \indxkwdalt{TCRD}{n} \\ Time resolution & \kwd{TIMEDEL} & & & & & \\ Time location in pixel & \kwd{TIMEPIXR} & & & & & \\ Phase-axis zero point & & \indxkwdalt{CZPHS}{i} & \dindxkw{i}{CZPH}{n} & \dindxkwalt{i}{CZP}{n} & \indxkw{TCZPH}{n} & \indxkwdalt{TCZP}{n} \\ Phase-axis period & & \indxkwdalt{CPERI}{i} & \dindxkw{i}{CPER}{n} & \dindxkwalt{i}{CPR}{n} & \indxkw{TCPER}{n} & \indxkwdalt{TCPR}{n} \\ \hline \end{tabular} %end{redtext} \end{center} \end{table*} \begin{table*} %begin{redtext} \caption*{Table~\ref{ta:WCSkw} (continued)} \tablefoot{The indices $j$ and $i$ are pixel and intermediate-world-coordinate axis numbers, respectively. Within a table, the index $n$ refers to a column number, and $m$ refers to a coordinate parameter number. The index $k$ also refers to a column number. The indicator $a$ is either blank (for the primary coordinate description) or a character \texttt{A} through \texttt{Z} that specifies the coordinate version. See the text.} \tablefoottext{1}{\indxkw{CROTA}{i} form is deprecated but still in use. It \mustnot\ be used with \PCij, \PV{i}{m}, and \PS{i}{m}.} \tablefoottext{2}{\indxkw{PC}{i\_j} and \indxkw{CD}{i\_j} forms of the transformation matrix are mutually exclusive, and \mustnot\ appear together in the same HDU.} \tablefoottext{3}{\kwd{EPOCH} is deprecated. Use \kwd{EQUINOX} instead.} \tablefoottext{4}{These eight-character keywords are deprecated; the seven-character forms, which can include an alternate version code letter at the end, \should\ be used instead.} \tablefoottext{5}{For the purpose of time reference position, geodetic latitude/longitude/elevation \kwd{OBSGEO-B}, \kwd{OBSGEO-L}, \kwd{OBSGEO-H} or an orbital-ephemeris keyword \kwd{OBSORBIT} can be also used (see Sect.~\ref{trefpos}).} \tablefoottext{6}{\kwd{[M]JDREF} can be split in integer and fractional values \kwd{[M]JDREFI} and \kwd{[M]JDREFF} as explained in Sect.~\ref{trefval}.} %end{redtext} \end{table*} % The keywords given below constitute a complete set of fundamental attributes for a WCS description. Although their inclusion in an HDU is optional, \FITS\ writers \should\ include a complete set of keywords when describing a WCS. In the event that some keywords are missing, default values \must\ be assumed, as specified below. \begin{description} \item \kwd{WCSAXES} -- [integer; default: \kwd{NAXIS}, or larger of WCS indices $i$ or $j$]. Number of axes in the WCS description. This keyword, if present, \must\ precede all WCS keywords except \kwd{NAXIS} in the HDU. The value of \kwd{WCSAXES} \may\ exceed the number of pixel axes for the HDU. \item \indxkw{CTYPE}{i} -- [string; indexed; default: {\verb*+' '+} (i.e.\ a linear, undefined axis)]. Type for the Intermediate-coordinate Axis~$i$. Any coordinate type that is not covered by this Standard or an officially recognized \FITS\ convention \shall\ be taken to be linear. All non-linear coordinate system names \must\ be expressed in `4--3' form: the first four characters specify the coordinate type, the fifth character is a hyphen\index{hyphen} (`\keyv{-}'), and the remaining three characters specify an algorithm code for computing the world coordinate value. Coordinate types with names of fewer than four characters are padded on the right with hyphens, and algorithm codes with fewer than three characters are padded on the right with blanks\footnote{Example: \keyv{'RA---UV~'}.}. Algorithm codes \should\ be three characters. \item \indxkw{CUNIT}{i} -- [string; indexed; default: {\verb*+' '+} (i.e., undefined)]. Physical units\index{units} of \kwd{CRVAL} and \kwd{CDELT} for Axis~$i$. Note that units \should\ always be specified (see Sect.~\ref{s:Units}). Units for celestial coordinate systems defined in this Standard \must\ be degrees. \index{angular units} \item \indxkw{CRPIX}{j} -- [floating point; indexed; default: \keyv{0.0}]. Location of the reference point in the image for Axis~$j$ corresponding to $r_j$ in Eq.~(\ref{eq:pix2intpix}). Note that the reference point \may\ lie outside the image and that the first pixel in the image has pixel coordinates $(1.0, 1.0, \ldots)$. \item \indxkw{CRVAL}{i} -- [floating point; indexed; default: \keyv{0.0}]. World-coordinate value at the reference point of Axis~$i$. \item \indxkw{CDELT}{i} -- [floating point; indexed; default: \keyv{1.0}]. Increment of the world coordinate at the reference point for Axis~$i$. The value \mustnot\ be zero. \item \indxkw{CROTA}{i} -- [floating point; indexed; default: \keyv{0.0}]. The amount of rotation from the standard coordinate system to a different coordinate system. Further use of this of this keyword is deprecated, \index{deprecate} in favor of the newer formalisms that use the \indxkw{CD}{i\_j} or \indxkw{PC}{i\_j} keywords to define the rotation. \item \indxkw{PC}{i\_j} -- [floating point; defaults: \keyv{1.0} when $i=j$, \keyv{0.0} otherwise]. Linear transformation matrix between Pixel Axes $j$ and Intermediate-coordinate Axes~$i$. The \indxkw{PC}{i\_j} matrix \mustnot\ be singular. \item \indxkw{CD}{i\_j} -- [floating point; defaults: \keyv{0.0}, but see below]. Linear transformation matrix (with scale) between Pixel Axes~$j$ and Intermediate-coordinate Axes~$i$. This nomenclature is equivalent to \indxkw{PC}{i\_j} when \indxkw{CDELT}{i} is unity. The \indxkw{CD}{i\_j} matrix \mustnot\ be singular. Note that the \indxkw{CD}{i\_j} formalism is an exclusive alternative to \indxkw{PC}{i\_j}, and the \indxkw{CD}{i\_j} and \indxkw{PC}{i\_j} keywords \mustnot\ appear together within an HDU. \end{description} \noindent In addition to the restrictions noted above, if any \indxkw{CD}{i\_j} keywords are present in the HDU, all other unspecified \indxkw{CD}{i\_j} keywords \shall\ default to zero. If no \indxkw{CD}{i\_j} keywords are present then the header \shall\ be interpreted as being in \indxkw{PC}{i\_j} form whether or not any \indxkw{PC}{i\_j} keywords are actually present in the HDU. Some non-linear algorithms that describe the transformation between pixel and intermediate-coordinate axes require parameter values. A few non-linear algorithms also require character-valued parameters, e.g., table lookups require the names of the table extension and the columns to be used. Where necessary parameter values \must\ be specified via the following keywords. \begin{description} \item \indxkw{PV}{i\_m} -- [floating point]. Numeric parameter values for Intermediate-world-coordinate Axis~$i$, where $m$ is the parameter number. Leading zeros \mustnot\ be used, and $m$ \may\ have only values in the range 0 through 99, and that are defined for the particular non-linear algorithm. \item \indxkw{PS}{i\_m} -- [string]. Character-valued parameters for Intermediate-world-coordinate Axis~$i$, where $m$ is the parameter number. Leading zeros \mustnot\ be used, and $m$ \may\ have only values in the range 0 through 99, and that are defined for the particular non-linear algorithm. \end{description} The following keywords, while not essential for a complete specification of an image WCS, can be extremely useful for readers to interpret the accuracy of the WCS representation of the image. \begin{description} \item \indxkw{CRDER}{i} -- [floating point; default: \keyv{0.0}]. Random error in Coordinate~$i$, which \must\ be non-negative. \item \indxkw{CSYER}{i} -- [floating point; default: \keyv{0.0}]. Systematic error in Coordinate~$i$, which \must\ be non-negative. \end{description} \noindent These values \should\ give a representative average value of the error over the range of the coordinate in the HDU. The total error in the coordinates would be given by summing the individual errors in quadrature. \subsubsection{Alternative WCS axis descriptions} In some cases it is useful to describe an image with more than one coordinate type\footnote{Examples include the frequency, velocity, and wavelength along a spectral axis (only one of which, of course, could be linear), or the position along an imaging detector in both meters and degrees on the sky.}. Alternative WCS descriptions \may\ be added to the header by adding the appropriate sets of WCS keywords, and appending to all keywords in each set an alphabetic code in the range \texttt{A} through \texttt{Z}. Keywords that may be used in this way to specify a coordinate system version are indicated in Table~\ref{ta:WCSkw} with the suffix \textit{a}. All implied keywords with this encoding are {\em reserved keywords},\index{keyword, reserved} and \must\ {\em only} be used in \FITS\ HDUs as specified in this Standard. The axis numbers \must\ lie in the range 1 through 99, and the coordinate parameter $m$ \must\ lie in the range 0 through 99, both with no leading zeros. %%% Celestial Coordinate projection algorithm codes Table 23 \begin{table*} \begin{center} \caption{Reserved celestial-coordinate-algorithm codes.} \label{ta:PROJcode} \begin{tabular}{lllll} \hline \hline & \multicolumn{2}{c}{Default} & & \\ %\cline{2-3} {Code} & {$\phi_0$} & {$\theta_0$} & {Properties\tablefootmark{1}} & {Projection name} \\ \hline \noalign{\smallskip} %\cutinhead{Zenithal (azimuthal) projections} \multicolumn{5}{c}{Zenithal (azimuthal) projections} \\ \keyv{AZP} & 0\degr & 90\degr & Sect.\ 5.1.1 & Zenithal perspective \\ \keyv{SZP} & 0\degr & 90\degr & Sect.\ 5.1.2 & Slant zenithal perspective \\ \keyv{TAN} & 0\degr & 90\degr & Sect.\ 5.1.3 & Gnomonic \\ \keyv{STG} & 0\degr & 90\degr & Sect.\ 5.1.4 & Stereographic \\ \keyv{SIN} & 0\degr & 90\degr & Sect.\ 5.1.5 & Slant orthographic \\ \keyv{ARC} & 0\degr & 90\degr & Sect.\ 5.1.6 & Zenithal equidistant \\ \keyv{ZPN} & 0\degr & 90\degr & Sect.\ 5.1.7 & Zenithal polynomial \\ \keyv{ZEA} & 0\degr & 90\degr & Sect.\ 5.1.8 & Zenithal equal-area \\ \keyv{AIR} & 0\degr & 90\degr & Sect.\ 5.1.9 & Airy \\ \noalign{\smallskip} \hline \noalign{\smallskip} % %\cutinhead{Cylindrical projections} \multicolumn{5}{c}{Cylindrical projections} \\ \keyv{CYP} & 0\degr & 0\degr & Sect.\ 5.2.1 & Cylindrical perspective \\ \keyv{CEA} & 0\degr & 0\degr & Sect.\ 5.2.2 & Cylindrical equal area \\ \keyv{CAR} & 0\degr & 0\degr & Sect.\ 5.2.3 & Plate carr\'ee \\ \keyv{MER} & 0\degr & 0\degr & Sect.\ 5.2.4 & Mercator \\ \noalign{\smallskip} \hline \noalign{\smallskip} % \multicolumn{5}{c}{Pseudo-cylindrical and related projections} \\ \keyv{SFL} & 0\degr & 0\degr & Sect.\ 5.3.1 & Samson-Flamsteed \\ \keyv{PAR} & 0\degr & 0\degr & Sect.\ 5.3.2 & Parabolic \\ \keyv{MOL} & 0\degr & 0\degr & Sect.\ 5.3.3 & Mollweide\\ \keyv{AIT} & 0\degr & 0\degr & Sect.\ 5.3.4 & Hammer-Aitoff \\ \noalign{\smallskip} \hline \noalign{\smallskip} % \multicolumn{5}{c}{Conic projections} \\ \keyv{COP} & 0\degr & $\theta_a$ & Sect.\ 5.4.1 & Conic perspective \\ \keyv{COE} & 0\degr & $\theta_a$ & Sect.\ 5.4.2 & Conic equal-area \\ \keyv{COD} & 0\degr & $\theta_a$ & Sect.\ 5.4.3 & Conic equidistant \\ \keyv{COO} & 0\degr & $\theta_a$ & Sect.\ 5.4.4 & Conic orthomorphic \\ \noalign{\smallskip} \hline \noalign{\smallskip} % \multicolumn{5}{c}{Polyconic and pseudoconic projections} \\ \keyv{BON} & 0\degr & 0\degr & Sect.\ 5.5.1 & Bonne's equal area \\ \keyv{PCO} & 0\degr & 0\degr & Sect.\ 5.5.2 & Polyconic \\ \noalign{\smallskip} \hline \noalign{\smallskip} % \multicolumn{5}{c}{Quad-cube projections} \\ \keyv{TSC} & 0\degr & 0\degr & Sect.\ 5.6.1 & Tangential spherical cube \\ \keyv{CSC} & 0\degr & 0\degr & Sect.\ 5.6.2 & COBE quadrilateralized spherical cube \\ \keyv{QSC} & 0\degr & 0\degr & Sect.\ 5.6.3 & Quadrilateralized spherical cube \\ \noalign{\smallskip} \hline \noalign{\smallskip} % \multicolumn{5}{c}{HEALPix grid projection} \\ \keyv{HPX} & 0\degr & 0\degr & Sect.\ 6\tablefootmark{2} & HEALPix grid \\ \noalign{\smallskip} \hline % \end{tabular} \end{center} \tablefoottext{1}{Refer to the indicated section in \cite{calabretta02} for a detailed description.} \tablefoottext{2}{This projection is defined in \cite{calabretta07}. } \end{table*} The {\em primary} version of the WCS description is that specified with \textit{a} as the blank character\footnote{There are a number of keywords (e.g. \dindxkwalt{ij}{PC}{n}) where the \textit{a} could be pushed off the eight-character keyword name for plausible values of \textit{i}, \textit{j}, \textit{k}, \textit{n}, and \textit{m}. In such cases \textit{a} is still said to be `blank' although it is not the blank character.}. Alternative axis descriptions are optional, but \mustnot\ be specified unless the primary WCS description is also specified. If an alternative WCS description is specified, all coordinate keywords for that version \must\ be given even if the values do not differ from those of the primary version. Rules for the default values of alternative coordinate descriptions are the same as those for the primary description. The alternative descriptions are computed in the same fashion as the primary coordinates. The type of coordinate depends on the value of \indxkwdalt{CTYPE}{i}, and may be linear in one of the alternative descriptions and non-linear in another. The alternative version codes are selected by the \FITS\ writer; there is no requirement that the codes be used in alphabetic sequence, nor that one coordinate version differ in its parameter values from another. An optional keyword \kwdalt{WCSNAME} is also defined to name, and otherwise document, the various versions of WCS descriptions. \begin{description} \item \kwdalt{WCSNAME} -- [string; default for \textit{a}: {\verb*+' '+} (i.e., blank, for the primary WCS, else a character \texttt{A} through \texttt{Z} that specifies the coordinate version]. Name of the world-coordinate system represented by the WCS keywords with the suffix \textit{a}. Its primary function is to provide a means by which to specify a particular WCS if multiple versions are defined in the HDU. \end{description} \subsection{Celestial-coordinate-system representations}\label{sect:Celestkw} The conversion from intermediate world coordinates $(x,y)$ in the plane of projection to celestial coordinates\index{WCS, celestial} involves two steps: a spherical projection to native longitude and latitude $(\phi, \theta)$, defined in terms of a convenient coordinate system (i.e., \textit{native spherical coordinates}), followed by a spherical rotation of these native coordinates to the required celestial coordinate system $(\alpha, \delta)$. The algorithm to be used to define the spherical projection \must\ be encoded in the \indxkw{CTYPE}{i} keyword as the three-letter algorithm code, the allowed values for which are specified in Table~\ref{ta:PROJcode} and defined in references \cite{calabretta02} and \cite{calabretta07}. The target celestial-coordinate system is also encoded into the left-most portion of the \indxkw{CTYPE}{i} keyword as the coordinate type. For the final step, the parameter \kwdalt{LONPOLE} \must\ be specified, which is the native longitude of the celestial pole, $\phi_p$. For certain projections (such as cylindricals and conics, which are less commonly used in astronomy), the additional keyword \kwdalt{LATPOLE} \must\ be used to specify the native latitude of the celestial pole. See \cite{calabretta02} for the transformation equations and other details. The accepted celestial-coordinate systems are: the standard equatorial (\keyv{RA--} and \keyv{DEC-}), and others of the form $x$\keyv{LON} and $x$\keyv{LAT} for longitude-latitude pairs, where $x$ is \keyv{G} for Galactic, \keyv{E} for ecliptic, \keyv{H} for helioecliptic and \keyv{S} for supergalactic coordinates. Since the representation of planetary-, lunar-, and solar-coordinate systems could exceed the 26 possibilities afforded by the single character $x$, pairs of the form $yz$\keyv{LN} and $yz$\keyv{LT} \may\ be used as well. \begin{description} \item \kwdalt{RADESYS} -- [string; default: \keyv{'FK4'}, \keyv{'FK5'}, or \keyv{'ICRS'}: see below]. Name of the reference frame of equatorial or ecliptic coordinates, whose value \must\ be one of those specified in Table~\ref{ta:RADESYS}. The default value is \keyv{'FK4'} if the value of \kwdalt{EQUINOX} $<1984.0$, \keyv{'FK5'} if \kwdalt{'EQUINOX'} $\geq1984.0$, or \keyv{'ICRS'} if \kwdalt{'EQUINOX'} is not given. \item \kwdalt{EQUINOX} -- [floating point; default: see below]. Epoch of the mean equator and equinox in years, whose value \must\ be non-negative. The interpretation of epoch depends upon the value of \kwdalt{RADESYS} if present: {\em Besselian} if the value is \keyv{'FK4'} or \keyv{'FK4-NO-E'}, {\em Julian} if the value is \keyv{'FK5'}; and {\em not applicable} if the value is \keyv{'ICRS'} or \keyv{'GAPPT'}. \item \kwd{EPOCH} -- [floating point]. This keyword is deprecated \index{deprecate} and \shouldnot\ be used in new \FITS\ files. It is reserved primarily to prevent its use with other meanings. The \kwd{EQUINOX} keyword\index{EQUINOX} \shall\ be used instead. The value field of this keyword was previously defined to contain a floating-point number\index{EPOCH} giving the equinox in years for the celestial-coordinate system in which positions are expressed. \item \kwd{DATE-OBS} -- [floating point]. This reserved keyword is defined in Sect.~\ref{s:kobs}. \item \kwd{MJD-OBS} -- [floating point; default: \kwd{DATE-OBS} if given, otherwise no default]. Modified Julian Date (JD $-$ 2,400,000.5) of the observation, whose value corresponds (by default) to the {\em start} of the observation, unless another interpretation is explained in the comment field. No specific time\index{time} system (e.g. UTC, TAI, etc.) is defined for this or any of the other time-related keywords. It is \recommended\ that the \kwd{TIMESYS} keyword, as defined in %begin{redtext} Sect.~\ref{sect:timeScale} %end{redtext} %LC be used to specify the time system. %\begin{redtext} See also Sect.~\ref{sect:GlobalTime}. %\end{redtext} %LC \item \kwdalt{LONPOLE} -- [floating point; default: $\phi_0$ if $\delta_0 \geq \theta_0$, $\phi_0+180\degr$ otherwise]. Longitude in the native coordinate system of the celestial system's north pole. Normally, $\phi_0$ is zero unless a non-zero value has been set for \kwdalt{PV\textit{i}\_1}, which is associated with the {\em longitude} axis. This default applies for all values of $\theta_0$, including $\theta_0=90\degr$, although the use of non-zero values of $\theta_0$ are discouraged in that case. \item \kwdalt{LATPOLE} -- [floating point; default: 90\degr, or no default if $(\theta_0,\delta_0,\phi_p-\phi_0) = (0,0,\pm90\degr)$]. Latitude in the native coordinate system of the celestial system's north pole, or equivalently, the latitude in the celestial-coordinate system of the native system's north pole. This keyword \may\ be ignored or omitted in cases where \kwdalt{LONPOLE} completely specifies the rotation to the target celestial system. \end{description} % the correct order of the tables 23 and 24, depends on which the style % Table 24 \ifaastyle \begin{table} \centering \caption{Allowed values of \kwdalt{RADESYS}.} \label{ta:RADESYS} \begin{tabular}{ll} \hline \hline Value & Definition \\ \hline \noalign{\smallskip} \keyv{'ICRS'} & International Celestial Reference System \\ \keyv{'FK5'} & Mean place, new (IAU 1984) system \\ \keyv{'FK4'}\tablefootmark{1} & Mean place, old (Bessel-Newcomb) system \\ \keyv{'FK4-NO-E'}\tablefootmark{1} & Mean place: but without eccentricity terms \\ \keyv{'GAPPT'} & Geocentric apparent place, IAU 1984 system \\ \noalign{\smallskip} \hline \end{tabular} \tablefoottext{1}{New \FITS\ files should avoid using these older reference systems.} \end{table} \fi \subsection{Spectral-coordinate-system representations}\label{sect:SPECkw} This section discusses the conversion of intermediate world coordinates to spectral\index{WCS, spectral} coordinates with common axes such as frequency, wavelength, and apparent radial velocity (represented here with the coordinate variables $\nu, \lambda$, or $v$). The key point for constructing spectral WCS in \FITS\ is that one of these coordinates \must\ be sampled linearly in the dispersion axis; the others are derived from prescribed, usually non-linear transformations. Frequency and wavelength axes \may\ also be sampled linearly in their logarithm. Following the convention for the \indxkwdalt{CTYPE}{i} keyword, when $i$ is the spectral axis the first four characters \must\ specify a code for the coordinate type; for non-linear algorithms the fifth character \must\ be a hyphen,\index{hyphen} and the next three characters \must\ specify a predefined algorithm for computing the world coordinates from the intermediate physical coordinates. The coordinate type \must\ be one of those specified in Table~\ref{ta:SPECtype}. When the algorithm is linear, the remainder of the \indxkwdalt{CTYPE}{i} keyword \must\ be blank. When the algorithm is non-linear, the three-letter algorithm code \must\ be one of those specified in Table~\ref{ta:SPECcode}. The relationships between the basic physical quantities $\nu, \lambda$, and $v$, as well as the relationships between various derived quantities are given in reference \cite{greisen06}. The generality of the algorithm for specifying the spectral-coordinate system and its representation suggests that some additional description of the coordinate may be helpful beyond what can be encoded in the first four characters of the \indxkwdalt{CTYPE}{i} keyword; \indxkwdalt{CNAME}{i} is reserved for this purpose. Note that this keyword provides a name for an axis in a particular WCS, while the \kwdalt{WCSNAME} keyword names the particular WCS as a whole. In order to convert between some form of radial velocity and either frequency or wavelength, the keywords \kwdalt{RESTFRQ} and \kwdalt{RESTWAV}, respectively, are reserved. \begin{description} \item \indxkwdalt{CNAME}{i} -- [string; default: default: {\verb*+' '+} (i.e.\ a linear, undefined axis)]. Spectral-coordinate description that \mustnot\ exceed 68 characters in length. \item \kwdalt{RESTFRQ} -- [floating point; default: none]. Rest frequency of the of the spectral feature of interest. The physical unit \must\ be Hz. \item \kwdalt{RESTWAV} -- [floating point; default: none]. Vacuum rest wavelength of the of the spectral feature of interest. The physical unit \must\ be m. \end{description} \noindent One or the other of \kwdalt{RESTFRQ} or \kwdalt{RESTWAV} \should\ be given when it is meaningful to do so. % the correct order of the tables 23 and 24, depends on which the style \ifiaufwgstyle % Table 24 \begin{table} \centering \caption{Allowed values of \kwdalt{RADESYS}.} \label{ta:RADESYS} \begin{tabular}{ll} \hline \hline Value & Definition \\ \hline \noalign{\smallskip} \keyv{'ICRS'} & International Celestial Reference System \\ \keyv{'FK5'} & Mean place, new (IAU 1984) system \\ \keyv{'FK4'}\tablefootmark{1} & Mean place, old (Bessel-Newcomb) system \\ \keyv{'FK4-NO-E'}\tablefootmark{1} & Mean place: but without eccentricity terms \\ \keyv{'GAPPT'} & Geocentric apparent place, IAU 1984 system \\ \noalign{\smallskip} \hline \end{tabular} \tablefoottext{1}{New \FITS\ files \should\ avoid using these older reference systems.} \end{table} \fi %%% Spectral Coordinate type codes Table 25 \begin{table*} \begin{center} \caption{Reserved spectral-coordinate type codes.} %LC \tablefootmark{1}.} \label{ta:SPECtype} \begin{tabular}{llccl} \hline \hline {Code}\tablefootmark{1} & {Type} & {Symbol} & {Associated} & {Default units} \\ & & & {variable} & \\ \hline \noalign{\smallskip} %\cutinhead{Zenithal (azimuthal) projections} \keyv{FREQ} & Frequency & $\nu$ & $\nu$ & Hz \\ \keyv{ENER} & Energy & $E$ & $\nu$ & J \\ \keyv{WAVN} & Wavenumber & $\kappa$ & $\nu$ & m$^{-1}$ \\ \keyv{VRAD} & Radio velocity\tablefootmark{2} & $V$ & $\nu$ & m~s$^{-1}$ \\ \keyv{WAVE} & Vacuum wavelength & $\lambda$ & $\lambda$ & m \\ \keyv{VOPT} & Optical velocity\tablefootmark{2} & $Z$ & $\lambda$ & m~s$^{-1}$ \\ \keyv{ZOPT} & Redshift & $z$ & $\lambda$ & ... \\ \keyv{AWAV} & Air wavelength & $\lambda_a$ & $\lambda_a$ & m \\ \keyv{VELO} & Apparent radial velocity & $v$ & $v$ & m~s$^{-1}$ \\ \keyv{BETA} & Beta factor ($v/c$) & $\beta$ & $v$ & ... \\ % \noalign{\smallskip} \hline \end{tabular} \end{center} %\tablefoot{ } \tablefoottext{1}{Characters 1 through 4 of the value of the keyword \indxkwdalt{CTYPE}{i}.} \tablefoottext{2}{By convention, the `radio' velocity is given by $c(\nu_0 - \nu)/\nu_0$ and the `optical' velocity is given by $c(\lambda - \lambda_0)/\lambda_0$.} \end{table*} \subsubsection{Spectral-coordinate reference frames}\label{sect:SpecRefFrame} Frequencies, wavelengths, and apparent radial velocities are always referred to some selected standard of rest (i.e., reference frame). While the spectra are obtained they are, of necessity, in the observer's rest frame. The velocity correction from topocentric (the frame in which the measurements are usually made) to standard reference frames (which \must\ be one of those given in Table~\ref{ta:SPECsys}) are dependent on the dot product with time-variable velocity vectors. That is, the velocity with respect to a standard reference frame depends upon direction, and the velocity (and frequency and wavelength) with respect to the local standard of rest is a function of the celestial coordinate within the image. The keywords \kwdalt{SPECSYS} and \kwdalt{SSYSOBS} are reserved and, if used, \must\ describe the reference frame in use for the spectral-axis coordinate(s) and the spectral reference frame that was held constant during the observation, respectively. In order to compute the velocities it is necessary to have the date and time of the observation; the keywords \kwd{DATE-AVG} and \kwd{MJD-AVG} are reserved for this purpose. %\begin{redtext} See also Sect.~\ref{sect:GlobalTime}. %\end{redtext} %LC \begin{description} \setlength\itemsep{0.05in} \item \kwd{DATE-AVG} -- [string; default: none]. Calendar date of the mid-point of the observation, expressed in the same way as the \kwd{DATE-OBS} keyword. \item \kwd{MJD-AVG} -- [floating point; default: none]. Modified Julian Date (JD $-$ 2,400,000.5) of the mid-point of the observation. \item \kwdalt{SPECSYS} -- [string; default: none]. The reference frame in use for the spectral-axis coordinate(s). Valid values are given in Table~\ref{ta:SPECsys}. \item \kwdalt{SSYSOBS} -- [string; default: \keyv{'TOPOCENT'}]. The spectral reference frame that is constant over the range of the non-spectral world coordinates. Valid values are given in Table~\ref{ta:SPECsys}. \end{description} The transformation from the rest frame of the observer to a standard reference frame requires a specification of the location on Earth\footnote{The specification of location for an instrument on a spacecraft in flight requires an ephemeris; keywords that might be required in this circumstance are not defined here.} of the instrument used for the observation in order to calculate the diurnal Doppler correction due to the Earth's rotation. The location, if specified, \shall\ be represented as a geocentric Cartesian triple with respect to a standard ellipsoidal geoid at the time of the observation. While the position can often be specified with an accuracy of a meter or better, for most purposes positional errors of several kilometers will have negligible impact on the computed velocity correction. For details, see reference \cite{greisen06}. \begin{description} % ERRATUM to 3.0 22062015 OBSGEO are \kwd not \kwdalt \setlength\itemsep{0.05in} \item \kwd{OBSGEO-X} -- [floating point; default: none]. $X-$coordinate (in meters) of a Cartesian triplet that specifies the location, with respect to a standard, geocentric terrestrial reference frame, where the observation took place. The coordinate \must\ be valid at the epoch \kwd{MJD-AVG} or \kwd{DATE-AVG}. \item \kwd{OBSGEO-Y} -- [floating point; default: none]. $Y-$coordinate (in meters) of a Cartesian triplet that specifies the location, with respect to a standard, geocentric terrestrial reference frame, where the observation took place. The coordinate \must\ be valid at the epoch \kwd{MJD-AVG} or \kwd{DATE-AVG}. \item \kwd{OBSGEO-Z} -- [floating point; default: none]. $Z-$coordinate (in meters) of a Cartesian triplet that specifies the location, with respect to a standard, geocentric terrestrial reference frame, where the observation took place. The coordinate \must\ be valid at the epoch \kwd{MJD-AVG} or \kwd{DATE-AVG}. \end{description} Information on the relative radial velocity between the observer and the selected standard of rest in the direction of the celestial reference coordinate \may\ be provided, and if so \shall\ be given by the \kwdalt{VELOSYS} keyword. The frame of rest defined with respect to the emitting source may be represented in \FITS; for this reference frame it is necessary to define the velocity with respect to some other frame of rest. The keywords \kwdalt{SPECSYS} and \kwdalt{ZSOURCE} are used to document the choice of reference frame and the value of the systemic velocity of the source, respectively. %%% Non-linear spectrum algorithm codes Table 26 \begin{table} \centering \caption{Non-linear spectral algorithm codes.} %LC \tablefootmark{1}.} \label{ta:SPECcode} \begin{tabular}{lll} \hline \hline {Code}\tablefootmark{1} & {Regularly sampled in} & {Expressed as} \\ \hline \noalign{\smallskip} \keyv{F2W} & Frequency & Wavelength \\ \keyv{F2V} & & Apparent radial velocity \\ \keyv{F2A} & & Air wavelength \\ \keyv{W2F} & Wavelength & Frequency \\ \keyv{W2V} & & Apparent radial velocity \\ \keyv{W2A} & & Air wavelength \\ \keyv{V2F} & Apparent radial vel. & Frequency \\ \keyv{V2W} & & Wavelength \\ \keyv{V2A} & & Air wavelength \\ \keyv{A2F} & Air wavelength & Frequency \\ \keyv{A2W} & & Wavelength \\ \keyv{A2V} & & Apparent radial velocity \\ % \noalign{\smallskip} \hline \noalign{\smallskip} \keyv{LOG} & Logarithm & Any four-letter type code \\ \keyv{GRI} & Detector & Any type code from Table~\ref{ta:SPECtype} \\ \keyv{GRA} & Detector & Any type code from Table~\ref{ta:SPECtype} \\ \keyv{TAB} & Not regular & Any four-letter type code \\ \noalign{\smallskip} \hline \end{tabular} \tablefoottext{1}{Characters 6 through 8 of the value of the keyword \indxkwdalt{CTYPE}{i}.} \end{table} \begin{description} \item \kwdalt{SSYSSRC} -- [string; default: none]. Reference frame for the value expressed in the \kwdalt{ZSOURCE} keyword to document the systemic velocity of the observed source. Value \must\ be one of those given in Table~\ref{ta:SPECsys} {\em except} for \keyv{'SOURCE'}. \item \kwdalt{VELOSYS} -- [floating point; default: none]. Relative radial velocity between the observer and the selected standard of rest in the direction of the celestial reference coordinate. Units\index{units} \must\ be m~s$^{-1}$. The \indxkwdalt{CUNIT}{i} keyword is not used for this purpose since the WCS Version~\textit{a} might not be expressed in velocity units. \item \kwdalt{ZSOURCE} -- [floating point; default: none]. Radial velocity with respect to an alternative frame of rest, expressed as a unitless redshift (i.e., velocity as a fraction of the speed of light in vacuum). Used in conjunction with \kwdalt{SSYSSRC} to document the systemic velocity of the observed source. \item \kwdalt{VELANGL} -- [floating point; default:$\keyv{+90.}$]. In the case of relativistic velocities (e.g., a beamed astrophysical jet) the transverse velocity component is important. This keyword \may\ be used to express the orientation of the space velocity vector with respect to the plane of the sky. See Appendix~A of reference \cite{greisen06} for further details. \end{description} %%% Spectral reference system keywords Table 27 \begin{table} \centering \caption{Spectral reference systems.} \label{ta:SPECsys} \begin{tabular}{ll} \hline \hline Value & Definition \\ \hline \noalign{\smallskip} \keyv{'TOPOCENT'} & Topocentric \\ \keyv{'GEOCENTR'} & Geocentric \\ \keyv{'BARYCENT'} & Barycentric \\ \keyv{'HELIOCEN'} & Heliocentric \\ \keyv{'LSRK'} & Local standard of rest (kinematic) \\ \keyv{'LSRD'} & Local standard of rest (dynamic) \\ \keyv{'GALACTOC'} & Galactocentric \\ \keyv{'LOCALGRP'} & Local Group \\ \keyv{'CMBDIPOL'} & Cosmic-microwave-background dipole \\ \keyv{'SOURCE'} & Source rest frame \\ % \noalign{\smallskip} \hline \end{tabular} \tablefoot{These are the allowed values of the \kwdalt{SPECSYS}, \kwdalt{SSYSOBS}, and \kwdalt{SSYSSRC} keywords.} \end{table} \subsection{Conventional-coordinate types} The \label{sect:ConvCoord} first \FITS\ paper \citep{wells81} listed a number of `suggested values' for the \indxkw{CTYPE}{i} keyword. Two of these have the attribute the associated world coordinates can assume only integer values and that the meaning of these integers is only defined by convention. The first `conventional' coordinate is \indxkwdalt{CTYPE}{i}~=~\keyv{'COMPLEX'} to specify that complex values (i.e., pairs of real and imaginary components) are stored in the data array (along with an optional weight factor). Thus, the complex axis of the data array will contain two values (or three if the weight is specified). By convention, the real component has a coordinate value of 1, the imaginary component has a coordinate value of 2, and the weight, if any, has a coordinate value of 3. Table~\ref{ta:complex} illustrates the required keywords for an array of 100 complex values (without weights). The second conventional coordinate is \indxkwdalt{CTYPE}{i}~=~\keyv{'STOKES'} to specify the polarization of the data. Conventional values, their symbols, and polarizations are given in Table~\ref{ta:stokes}. % Table 28 \begin{table} \centering \caption{Example keyword records for a 100-element array of complex values.} \label{ta:complex} \begin{tabular}{l} \hline \hline Keyword records \\ \hline \noalign{\smallskip} {\verb+SIMPLE = T+} \\ {\verb+BITPIX = -32+} \\ {\verb+NAXIS = 2+} \\ {\verb+NAXIS1 = 2+} \\ {\verb+NAXIS2 = 100+} \\ {\verb+CTYPE1 = 'COMPLEX'+} \\ {\verb+CRVAL1 = 0.+} \\ {\verb+CRPIX1 = 0.+} \\ {\verb+CDELT1 = 1.+} \\ {\verb+END+} \\ \noalign{\smallskip} \hline \end{tabular} \end{table} % Table 29 \begin{table} \centering \caption{Conventional Stokes values.} \label{ta:stokes} \begin{tabular}{rcl} \hline \hline Value & Symbol & Polarization \\ \hline \noalign{\smallskip} $1$ & \keyv{'I'} & Standard Stokes unpolarized \\ $2$ & \keyv{'Q'} & Standard Stokes linear \\ $3$ & \keyv{'U'} & Standard Stokes linear \\ $4$ & \keyv{'V'} & Standard Stokes circular \\ $-1$ & \keyv{'RR'} & Right-right circular \\ $-2$ & \keyv{'LL'} & Left-left circular \\ $-3$ & \keyv{'RL'} & Right-left cross-circular \\ $-4$ & \keyv{'LR'} & Left-right cross-circular \\ $-5$ & \keyv{'XX'} & $X$ parallel linear \\ $-6$ & \keyv{'YY'} & $Y$ parallel linear \\ $-7$ & \keyv{'XY'} & $XY$ cross linear \\ $-8$ & \keyv{'YX'} & $YX$ cross linear \\ \noalign{\smallskip} \hline \end{tabular} \end{table} %LC Dick virtually final %clearpage %LC \section{Representations of time coordinates}\label{sect:timeReps}\index{WCS, timing} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% % Time WCS Chapter for V3.1 % Added 2015-May RAShaw % %\clearpage %section{Representations of time coordinates}\label{sect:timeReps} Time\index{time} as a dimension in astronomical data presents challenges for its representation in \FITS\ files. This section formulates the representation of the time axis, or possibly multiple time axes, into the world-coordinate system (WCS) described in Sect.~\ref{s:WCS}. Much of the basic structure is employed, while extensions are developed to cope with the differences between time and spatial dimensions; notable amongst these differences is the huge dynamic range, covering the highest resolution timing relative to the age of the universe. The precision with which any time stamp conforms to any conventional time scale is highly dependent on the characteristics of the acquiring system. The definitions of many conventional time scales vary over their history along with the precision that can be attributed to any time stamp. The meaning of any time stamp may be ambiguous if a time scale is used for dates prior to its definition by a recognized authority, or for dates after that definition is abandoned. However, common sense should prevail: the precision in the description of the time coordinate \should\ be appropriate to the accuracy of the temporal information in the data. %%%%% \subsection{Time values} The three most common ways to specify time\index{time} are: ISO-8601 \citep{iso04b}\index{ISO-8601 date}, Julian Date (JD)\index{JD}, or Modified Julian Date\index{MJD} \citep[MJD = $\mathrm{JD} -2,400,000.5$; see][]{IAUmjd}. Julian Dates are counted from Julian proleptic calendar date 1~January 4713 BCE at noon, or Gregorian proleptic calendar date 24 November 4714 BCE, also at noon. For an explanation of the calendars, see \cite{rots15}. Even though it is common to think of certain representations of time as absolute, time values in \FITS\ files \shall\ all be considered relative: elapsed time since a particular reference point in time. It may help to view the ``absolute'' values as merely relative to a globally accepted zero point. For a discussion of the precision required to represent time values in floating-point numbers, see \citet{rots15}. \subsubsection{ISO-8601 \textit{datetime} strings} \label{iso8601}\index{ISO-8601 date} \FITS\ datetime strings conform to a subset of ISO-8601 (which in itself does not imply a particular time scale) for several time-related keywords \citep{bunclark97}, such as \kwd{DATE-xxxx}. Here \textit{datetime} will be used as a pseudo data type to indicate its use, although its values \must\ be written as a character string in \texttt{'A'} format. The full specification for the format of the \textit{datetime} string has been: \begin{quote} \centering \keyv{CCYY-MM-DD[{\bf T}hh:mm:ss[.s...]]} \end{quote} in which all of the time part \may\ be omitted (just leaving the date) or the decimal seconds \may\ be omitted. Leading zeros \mustnot\ be omitted and timezone designators are {\em not allowed}. % This definition is extended to allow five-digit years with a {\em mandatory} sign, in accordance with ISO-8601. That is, one \shall\ use either the {\em unsigned} four-digit year format, or the {\em signed} five-digit year format shown below. \begin{quote} \centering \keyv{[$\pm$C]CCYY-MM-DD[{\bf T}hh:mm:ss[.s...]]} \end{quote} Note the following. \begin{itemize} \item In counting years, ISO-8601 follows the convention of including Year Zero. Consequently, for negative year numbers there is an offset of one from BCE dates, which do not recognize a Year Zero. Thus Year~1 corresponds to 1 CE, Year~0 to 1 BCE, Year $-1$ to 2 BCE, and so on. \item The earliest date that may be represented in the four-digit year format is \keyv{'0000-01-01T00:00:00'} (in the year 1 BCE); the latest date is \keyv{'9999-12-31T23:59:59'}. This representation of time is tied to the Gregorian calendar. In conformance with the present ISO-8601:2004(E) standard \citep{iso04b} dates prior to 1582 \must\ be interpreted according to the proleptic application of the rules of Gregorius XIII. For dates not covered by that range the use of Modified Julian Date (MJD) or Julian Date (JD) numbers or the use of the signed five-digit year format is \recommended. \item In the five-digit year format the earliest and latest dates are \\ \keyv{'-99999-01-01T00:00:00'} (i.e., $-100\:000$ BCE) and \\ \keyv{'+99999-12-31T23:59:59'}. \item The origin of JD can be written as: \\ \keyv{'-04713-11-24T12:00:00'}. \item In the UTC time scale the integer part of the seconds field runs from 00 to 60 (in order to accommodate leap seconds); in all other time scales the range is 00 to 59. \item The ISO-8601 \textit{datetime} data type is {\em not allowed} in image-axis descriptions since \kwd{CRVAL} is \required\ to be a floating-point value. \item ISO-8601 \textit{datetime} does not imply the use of any particular time scale (see Sect.~\ref{sect:timeScale}). \item As specified by \cite{bunclark97}, time zones are explicitly not supported in \FITS\ and, consequently, appending the letter \keyv{'Z'} to a \FITS\ ISO-8601 string is {\em not allowed}. The rationale for this rule is that its role in the ISO standard is that of a time-zone indicator, not a time-scale indicator. As the concept of a time zone is not supported in \FITS, the use of time-zone indicator is inappropriate. \end{itemize} \subsubsection{Julian and Besselian epochs} \label{epochs} In a variety of contexts {\em epochs} are provided with astronomical data. Until 1976 these were commonly based on the Besselian year (see Sect.~\ref{sect:timeUnit}), with standard epochs B1900.0 and B1950.0. After 1976 the transition was made to Julian epochs based on the Julian year of 365.25 days, with the standard epoch J2000.0. They are tied to the ET and TDB time scales, respectively. Note that the Besselian epochs are scaled by the variable length of the Besselian year (see Sect.~\ref{sect:timeUnit} and its cautionary note, which also applies to this context). The Julian epochs are easier to calculate, as long as one keeps track of leap days. %%%%%% \subsection{Time coordinate frame} \subsubsection{Time scale}\label{sect:timeScale}\index{time scale} The \textit{time scale} defines the temporal reference frame, and is specified in the header in one of a few ways, depending upon the context. When recorded as a global keyword, the time scale \shall\ be specified by the following keyword. \begin{description} \item \kwd{TIMESYS}\index{TIMESYS} -- [string; default: \keyv{'UTC'}]. The value field of this keyword \shall\ contain a character-string code for the time scale of the time-related keywords. The \recommended\ values for this keyword in Table~\ref{table:timescale} have well-defined meanings, but other values \may\ be used. If this keyword is absent, \keyv{'UTC'} \must\ be assumed. \end{description} \noindent In relevant contexts (e.g., time axes in image arrays, table columns, or random groups) \kwd{TIMESYS} \may\ be overridden by a time scale recorded in \indxkwdalt{CTYPE}{i}, its binary-table equivalents, or \indxkw{PTYPE}{i} (see Table~\ref{ta:WCSkw}). The keywords \kwd{TIMESYS}, \indxkwdalt{CTYPE}{i}, \indxkw{TCTYP}{n}, and \indxkwdalt{TCTY}{n} or binary-table equivalent \may\ assume the values listed in Table~\ref{table:timescale}. In addition, for backward compatibility, all except \kwd{TIMESYS} and \indxkw{PTYPE}{i} \may\ also assume the value \keyv{'TIME'} (case-insensitive), whereupon the time scale \shall\ be that recorded in \kwd{TIMESYS} or, in its absence, its default value, \keyv{'UTC'}\index{time, universal}. As noted above, local time scales other than those listed in Table~\ref{table:timescale} \may\ be used, but their use \should\ be restricted to alternate coordinates in order that the primary coordinates will always refer to a properly recognized time scale. See \cite{rots15}, Appendix~A, for a detailed discussion of the various time scales. In cases where high-precision timing is important one \may\ append a specific realization, in parentheses, to the values in the table; e.g., \keyv{'TT(TAI)'}, \keyv{'TT(BIPM08)'}, \keyv{'UTC(NIST)'}. Note that linearity is not preserved across all time scales. Specifically, if the reference position remains unchanged (see Sect.~\ref{trefpos}), the first ten, with the exception of \keyv{'UT1'}, are linear transformations of each other (excepting leap seconds), as are \keyv{'TDB'} and \keyv{'TCB'}. On average \keyv{'TCB'} runs faster than \keyv{'TCG'} by approximately $1.6 \times 10^{-8}$, but the transformation from \keyv{'TT'} or \keyv{'TCG'} (which are linearly related) is to be achieved through a time ephemeris as provided by \citet{IF99}. The relations between coordinate time scales and their dynamical equivalents have been defined as: {\indent $T(\mathrm{TCG}) = T(\mathrm{TT}) + L_{\mathrm{G}} \times 86400 \times (JD(\mathrm{TT}) - JD_0)$} \\ {\indent $T(\mathrm{TDB}) = T(\mathrm{TCB}) - L_{\mathrm{B}} \times 86400 \times (JD(\mathrm{TCB}) - JD_0) + TDB_0$}, \noindent where: {\indent $T$ is in seconds} \\ {\indent $L_{\mathrm{G}} = 6.969290134 \times 10^{-10}$} \\ {\indent $L_{\mathrm{B}} = 1.550519768 \times 10^{-8}$} \\ {\indent $JD_0 = 2443144.5003725$} \\ {\indent $TDB_0 = -6.55 \times 10^{-5}$} s. \noindent Linearity is virtually guaranteed since images and individual table columns do not allow more than one reference position to be associated with them, and since there is no overlap between reference positions that are meaningful for the first nine time scales on the one hand, and for the barycentric ones on the other. All use of the GMT time scale in \FITS\ files \shall\ be taken to have its zero point at midnight, conformant with UT, including dates prior to 1925. For high-precision timing prior to 1972, see \citet{rots15}, Appendix~A. %%% Table of Time scale values \begin{table} \caption{Recognized Time Scale Values}\index{time scale} \label{table:timescale} \centering \begin{tabular}{r p{0.36\textwidth}} \hline\hline Value & Meaning \\ \hline \noalign{\smallskip} \keyv{'TAI'} & (International Atomic Time): atomic-time standard maintained on the rotating geoid \\ \keyv{'TT'} & (Terrestrial Time; IAU standard): defined on the rotating geoid, usually derived as TAI $+$ 32.184 s \\ \keyv{'TDT'} & (Terrestrial Dynamical Time): synonym for TT (deprecated) \\ \keyv{'ET'} & (Ephemeris Time): continuous with TT; \shouldnot\ be used for data taken after 1984-01-01 \\ \keyv{'IAT'} & synonym for TAI (deprecated) \\ \keyv{'UT1'} & (Universal Time): Earth rotation time \\ \keyv{'UTC'} & (Universal Time, Coordinated; default): runs synchronously with TAI, except for the occasional insertion of leap seconds intended to keep UTC within 0.9 s of UT1; as of %begin{redtext} %LC post vote 2015-07-01 UTC = TAI $-$ %end{redtext} %LC post vote %begin{redtext} %LC post vote 36 %end{redtext} %LC post vote s \\ \keyv{'GMT'} & (Greenwich Mean Time): continuous with UTC; its use is deprecated for dates after 1972-01-01 \\ \keyv{UT()$^1$} & (Universal Time, with qualifier): for high-precision use of radio-signal distributions between 1955 and 1972; see \citet{rots15}, Appendix~A \\ \keyv{'GPS'} & (Global Positioning System): runs (approximately) synchronously with TAI; GPS $\approx$ TAI $-$ 19 s \\ \keyv{'TCG'} & (Geocentric Coordinate Time): TT reduced to the geocenter, corrected for the relativistic effects of the Earth's rotation and gravitational potential; TCG runs faster than TT at a constant rate \\ \keyv{'TCB'} & (Barycentric Coordinate Time): derived from TCG by a four-dimensional transformation, taking into account the relativistic effects of the gravitational potential at the barycenter (relative to that on the rotating geoid) as well as velocity time-dilation variations due to the eccentricity of the Earth's orbit, thus ensuring consistency with fundamental physical constants; \citet{IF99} provide a time ephemeris \\ \keyv{'TDB'} & (Barycentric Dynamical Time): runs slower than TCB at a constant rate so as to remain approximately in step with TT; runs therefore quasi-synchronously with TT, except for the relativistic effects introduced by variations in the Earth's velocity relative to the barycenter. When referring to celestial observations, a pathlength correction to the barycenter may be needed, which requires the Time Reference Direction used in calculating the pathlength correction. \\ \keyv{'LOCAL'} & for simulation data and for free-running clocks. \\ \noalign{\smallskip} \hline & \\ %\multicolumn{2}{l}{$^1$Recognized values for \kwd{TIMESYS}, \CTYPE{ia}, \indxkw{TCTYP}{n}, \indxkwdalt{TCTY}{n}.} \\ \multicolumn{2}{l}{$^1$Specific realization codes \may\ be appended to these values, in } \\ \multicolumn{2}{l}{parentheses; see the text. For a more-detailed discussion of time } \\ \multicolumn{2}{l}{scales, see \cite{rots15}, Appendix~A. } \end{tabular} \end{table} Some time scales in use are not listed in Table~\ref{table:timescale} because they are intrinsically unreliable or ill-defined. When used, they \should\ be tied to one of the existing scales with appropriate specification of the uncertainties; the same is true for free-running clocks. However, a local time scale such as MET (Mission Elapsed Time) or OET (Observation Elapsed Time) \may\ be defined for practical reasons. In those cases the time reference value (see Sect.~\ref{trefval}) \shallnot\ be applied to the values, and it is strongly \recommended\ that such time scales be provided as alternate time scales, with a defined conversion to a recognized time scale. It is useful to note that while UT1 is, in essence, an angle (of the Earth's rotation -- {\em i.e.,} a {\em clock}), the others are SI-second counters ({\em chronometers}); UTC, by employing leap seconds, serves as a bridge between the two types of time scales. \subsubsection{Time reference value}\label{trefval}\index{time reference} The time reference value is \notrequired\ to be present in an HDU. However, if the time reference point is specified explicitly it \must\ be expressed in one of ISO-8601, JD, or MJD. These reference values \must\ {\em only} be applied to time values associated with one of the recognized time scales listed in Table~\ref{table:timescale}, and that time scale \must\ be specified explicitly or implicitly as explained in Sect.~\ref{sect:timeScale}. The reference point in time, to which all times in the HDU are relative, \shall\ be specified through one of three keywords specified below. \begin{description}\label{ktrefval} \setlength\itemsep{0.05in} \item \kwd{MJDREF} -- [floating-point]; default: \keyv{0.0}] The value field of this keyword \shall\ contain the value of the reference time in MJD. \item \kwd{JDREF} -- [floating-point; default: none] The value field of this keyword \shall\ contain the value of the reference time in JD. \item \kwd{DATEREF} -- [datetime; default: none] The value field of this keyword \shall\ contain a character-string representation of the reference time in ISO-8601 format. \end{description} \noindent \kwd{MJDREF} and \kwd{JDREF} \may, for clarity or precision reasons, be split into two keywords holding the integer and fractional parts separately. \begin{description}\label{ktrefval2} \setlength\itemsep{0.05in} \item \kwd{MJDREFI} -- [integer; default: \keyv{0}] The value field of this keyword \shall\ contain the integer part of reference time in MJD. \item \kwd{MJDREFF} -- [floating-point; default: \keyv{0.0}] The value field of this keyword \shall\ contain the fractional part of reference time in MJD. \item \kwd{JDREFI} -- [integer; default: none] The value field of this keyword \shall\ contain the integer part of reference time in JD. \item \kwd{JDREFF} -- [floating-point; default: none] The value field of this keyword \shall\ contain the fractional part of reference time in JD. \end{description} If \kwd{[M]JDREF} and both \kwd{[M]JDREFI} and \kwd{[M]JDREFF} are present, the integer and fractional values \shall\ have precedence over the single value. If the single value is present with one of the two parts, the single value \shall\ have precedence. In the following, \kwd{MJDREF} and \kwd{JDREF} refer to their literal meaning or the combination of their integer and fractional parts. % If a header contains more than one of these keywords, \kwd{JDREF} \shall\ have precedence over \kwd{DATEREF} and \kwd{MJDREF} \shall\ have precedence over both the others. If none of the three keywords is present, there is no problem as long as all times in the HDU are expressed in ISO-8601; otherwise \kwd{MJDREF}~=~\keyv{0.0} \must\ be assumed. If \kwd{TREFPOS}~=~\keyv{'CUSTOM'} (Sect.~\ref{trefpos}), it is legitimate for none of the reference-time keywords to be present, as one may assume the data are from a simulation. % Note that the {\em value} of the reference time has global validity for all time values, but it does not have a particular time scale associated with it. \subsubsection{Time reference position}\label{trefpos}\index{time reference position} An observation is an event in space-time. The reference position specifies the spatial location at which the time is valid, either where the observation was made or the point in space for which light-time corrections have been applied. When recorded as a global keyword, the time reference position \shall\ be specified by the following keyword. \begin{description} \item \kwd{TREFPOS} -- [string; default: \keyv{'TOPOCENTER'}]. The value field of this keyword \shall\ contain a character-string code for the spatial location at which the observation time is valid. The value \should\ be one of those given in Table~\ref{table:refpos}. This keyword \shall\ apply to time-coordinate axes in images as well. \end{description} In binary tables, different columns \may\ represent completely different Time Coordinate Frames. However, each column can have only one time reference position, thus guaranteeing linearity (see Sect.~\ref{sect:timeScale}). \begin{description} \item \indxkw{TRPOS}{n} -- [string; default: \keyv{'TOPOCENTER'}] The value field of this keyword \shall\ contain a character-string code for the spatial location at which the observation time is valid. This table keyword \shall\ override \kwd{TREFPOS}. \end{description} The reference position value \may\ be a standard location (such as \keyv{'GEOCENTER'} or \keyv{'TOPOCENTER'}) or a point in space defined by specific coordinates. In the latter case one should be aware that a (three-dimensional) spatial-coordinate frame needs to be defined that is likely to be different from the frame(s) with which the data are associated. Note that \keyv{'TOPOCENTER'} is only moderately informative if no observatory location is provided or indicated. % The commonly allowed standard values are shown in Table~\ref{table:refpos}. Note that for the gaseous planets the barycenters of their planetary systems, including satellites, are used for obvious reasons. While it is preferable to spell the location names out in full, in order to be consistent with the practice of \citet{greisen06} the values are allowed to be truncated to eight characters. Furthermore, in order to allow for alternative spellings, only the first three characters of all these values \shall\ be considered significant. The value of the keyword \shall\ be case-sensitive. \begin{table}[h] \caption{Standard Time Reference Position Values}\index{time reference position} \label{table:refpos} \centering \begin{tabular}{r p{0.30\textwidth}} \hline\hline Value$^1$ & Meaning \\ \hline \noalign{\smallskip} \keyv{'TOPOCENTER'} & Topocenter: the location from where the observation was made (default) \\ \keyv{'GEOCENTER'} & Geocenter \\ \keyv{'BARYCENTER'} & Barycenter of the Solar System \\ \keyv{'RELOCATABLE'} & Relocatable: to be used for simulation data only \\ \keyv{'CUSTOM'} & A position specified by coordinates that is not the observatory location \\ \noalign{\smallskip} \hline \noalign{\smallskip} \multicolumn{2}{l}{Less-common, but allowed standard values} \\ \noalign{\smallskip} \hline \noalign{\smallskip} \keyv{'HELIOCENTER'} & Heliocenter \\ \keyv{'GALACTIC'} & Galactic center \\ \keyv{'EMBARYCENTER'} & Earth-Moon barycenter \\ \keyv{'MERCURY'} & Center of Mercury \\ \keyv{'VENUS'} & Center of Venus \\ \keyv{'MARS'} & Center of Mars \\ \keyv{'JUPITER'} & Barycenter of the Jupiter system \\ \keyv{'SATURN'} & Barycenter of the Saturn system \\ \keyv{'URANUS'} & Barycenter of the Uranus system \\ \keyv{'NEPTUNE'} & Barycenter of the Neptune system \\ \noalign{\smallskip} \hline \end{tabular} \tablefoot{$^{(1)}$Recognized values for \kwd{TREFPOS}, \indxkw{TRPOS}{n}; only the first three characters of the values are significant and Solar System locations are as specified in the ephemerides. } \end{table} The reader is cautioned that time scales and reference positions cannot be combined arbitrarily if one wants a clock that runs linearly at \kwd{TREFPOS}. Table \ref{table:posscale} provides a summary of compatible combinations. \keyv{'BARYCENTER'} \should\ only be used in conjunction with time scales \keyv{'TDB'} and \keyv{'TCB'}, and \should\ be the only reference position used with these time scales. With proper care \keyv{'GEOCENTER'}, \keyv{'TOPOCENTER'}, and \keyv{'EMBARYCENTER'} are appropriate for the first ten time scales in Table~\ref{table:timescale}. However, relativistic effects introduce a (generally linear) scaling in certain combinations; highly eccentric spacecraft orbits are the exceptions. Problems will arise when using a reference position on another Solar System body (including \keyv{'HELIOCENTER'}). Therefore, it is \recommended\ to synchronize the local clock with one of the time scales defined on the Earth's surface, \keyv{'TT'}, \keyv{'TAI'}, \keyv{'GPS'}, or \keyv{'UTC'} (in the last case: beware of leap seconds). This is common practice for spacecraft clocks. Locally, such a clock will not appear to run at a constant rate, because of variations in the gravitational potential and in motions with respect to Earth, but the effects can be calculated and are probably small compared with errors introduced by the alternative: establishing a local time standard. \begin{table} \caption{Compatibility of Time Scales and Reference Positions} %LC $^{1}$} \label{table:posscale} \centering \begin{tabular}{l c c c c c} \hline\hline %Reference & TT, TDT & TCG & TDB & TCB & LOCAL \\ %Position & TAI, IAT & \\ %& GPS &\\ %& UTC, GMT &\\ Reference & \multicolumn{5}{c}{Time scale$^{1}$} \\ Position & TT, TDT & TCG & TDB & TCB & LOCAL \\ & TAI, IAT & \\ & GPS & \\ & UTC, GMT & \\ \hline \noalign{\smallskip} \keyv{'TOPOCENTER'} & t & ls & & & \\ \keyv{'GEOCENTER'} & ls & c & & & \\ \keyv{'BARYCENTER'} & & & ls & c & \\ \keyv{'RELOCATABLE'} & & & & & c \\ Other$^{2}$ & re & re & & & \\ \noalign{\smallskip} \hline \end{tabular} \tablefoot{$^{(1)}$Legend (combination is \notrecommended\ if there is no entry); {\bf c}: correct match; reference position coincides with the spatial origin of the space-time coordinates; {\bf t}: correct match on Earth's surface, otherwise usually linear scaling; {\bf ls}: linear relativistic scaling; {\bf re}: non-linear relativistic scaling. $^{(2)}$All other locations in the Solar System.} \end{table} In order to provide a complete description, \keyv{'TOPOCENTER'} requires the observatory's coordinates to be specified. There are three options: \textit{(a)} the ITRS Cartesian coordinates defined in Sect.~\ref{sect:SpecRefFrame} (\kwd{OBSGEO-X}, \kwd{OBSGEO-Y}, \kwd{OBSGEO-Z}), which are {\em strongly preferred}; \textit{(b)} a geodetic latitude/longitude/elevation triplet (defined below); or \textit{(c)} a reference to an orbit-ephemeris file. % A set of geodetic coordinates is recognized by the following keywords. %, although the ITRS Cartesian coordinates are strongly preferred. \begin{description} \setlength\itemsep{0.05in} \item \kwd{OBSGEO-B} -- [floating-point] The value field of this keyword \shall\ contain the latitude of the observation in deg, with North positive. \item \kwd{OBSGEO-L} -- [floating-point] The value field of this keyword \shall\ contain the longitude of the observation in deg, with East positive. \item \kwd{OBSGEO-H} -- [floating-point] The value field of this keyword \shall\ contain the altitude of the observation in meters. \end{description} \noindent An orbital-ephemeris file can instead be specified. \begin{description} \item \kwd{OBSORBIT} -- [string] The value field of this keyword \shall\ contain the character-string URI, URL, or the name of an orbit-ephemeris file. \end{description} Beware that only one set of coordinates is allowed in a given HDU. Cartesian ITRS coordinates are the preferred coordinate system; however, when using these in an environment requiring nanosecond accuracy, one should take care to distinguish between meters consistent with TCG or with TT. If one uses geodetic coordinates, the geodetic altitude \kwd{OBSGEO-H} is measured with respect to the IAU 1976 ellipsoid, which is defined as having a semi-major axis of $6\,378\,140$~m and an inverse flattening of 298.2577. A non-standard location indicated by \keyv{'CUSTOM'} \must\ be specified in a manner similar to the specification of the observatory location (indicated by \keyv{'TOPOCENTER'}). One should be careful with the use of the \keyv{'CUSTOM'} value and not confuse it with \keyv{'TOPOCENTER'}, as use of the latter imparts additional information on the provenance of the data. ITRS coordinates ($X$,$Y$,$Z$) may be derived from geodetic coordinates ($L$,$B$,$H$) through: \[\indent X=(N(B)+H) \cos (L) \cos (B)\] \[\indent Y=(N(B)+H) \sin (L) \cos (B)\] \[\indent Z=(N(B) (1-e^2)+H) \sin (B)\] where: \[\indent N(B)=\frac{a}{\sqrt{1-e^2 \sin^2(B)}}\] \[\indent e^2=2f - f^2\] $a$ is the semi-major axis, and $f$ is the inverse of the inverse flattening. % Isn't "the inverse of the inverse-flattening" just the flattening?? Nanosecond precision in timing requires that \kwd{OBSGEO-[BLH]} be expressed in a geodetic reference frame defined after 1984 in order to be sufficiently accurate. \subsubsection{Time reference direction}\label{sect:trefdir}\index{time reference direction} If any pathlength corrections have been applied to the time stamps (i.e., if the reference position is not \keyv{'TOPOCENTER'} for observational data), the reference direction that is used in calculating the pathlength delay \should\ be provided in order to maintain a proper analysis trail of the data. However, this is useful only if there is also information available on the location from where the observation was made (the observatory location). The direction will usually be provided in a spatial-coordinate frame that is already being used for the spatial metadata, although it is conceivable that multiple spatial frames are involved, e.g., spherical ICRS coordinates for celestial positions, and Cartesian FK5 for spacecraft ephemeris. The time reference direction does not by itself provide sufficient information to perform a fully correct transformation; however, within the context of a specific analysis environment it should suffice. The uncertainty in the reference direction affects the errors in the time stamps. A typical example is provided by barycentric corrections where the time error is related to the position error: $$t_\mathrm{err} \mathrm{(ms)} \leq 2.4\, pos_\mathrm{err} \mathrm{(arcsec)}.$$ The reference direction is indicated through a reference to specific keywords. These keywords \may\ hold the reference direction explicitly or (for data in \BINTABLE\ extensions) indicate columns holding the coordinates. In event lists where the individual photons are tagged with a spatial position, those coordinates \may\ have been used for the reference direction and the reference will point to the columns containing these coordinate values. % The time reference direction \shall\ be specified by the following keyword. \begin{description} \item \kwd{TREFDIR} -- [string] The value field of this keyword \shall\ contain a character string composed of: the name of the keyword containing the longitudinal coordinate, followed by a comma, followed by the name of the keyword containing the latitudinal coordinate. This reference direction \shall\ apply to time-coordinate axes in images as well. \end{description} In binary tables, different columns \may\ represent completely different Time Coordinate Frames. However, also in that situation the condition holds that each column can have only one Time Reference Direction. Hence, the following keyword \may\ override \kwd{TREFDIR}. \begin{description} \item \indxkw{TRDIR}{n} -- [string] The value field of this keyword \shall\ contain a character string consisting of the name of the keyword or column containing the longitudinal coordinate, followed by a comma, followed by the name of the keyword or column containing the latitudinal coordinate. This reference direction \shall\ apply to time-coordinate axes in images as well. \end{description} \subsubsection{Solar System ephemeris}\label{sect:plephem}\index{solar system ephemeris} If applicable, the Solar System ephemeris used for calculating pathlength delays \should\ be identified. This is particularly pertinent when the time scale is \keyv{'TCB'} or \keyv{'TDB'}. The ephemerides that are currently most often used are those from \cite{jpl14a, jpl14b}. The Solar System ephemeris used for the data (if required) \shall\ be indicated by the following keyword. \begin{description} \item \kwd{PLEPHEM} -- [string; default: \keyv{'DE405'}] The value field of this keyword \shall\ contain a character string % code for the name of the Solar System ephemeris, the only permitted values for which are given in %begin{redtext} that \should\ represent a recognized designation for the Solar System ephemeris. Recognized designations for JPL Solar System ephemerides that are often used are listed in %end{redtext} Table~\ref{tab:SSEphem}. \end{description} \begin{table}[h] \centering \caption{Valid Solar System ephemerides}\index{solar system ephemeris} \label{tab:SSEphem} \begin{tabular}{l p{2.6in}} \hline \hline Value & Reference \\ \hline \noalign{\smallskip} \keyv{'DE200'} & \citet{standish90}; considered obsolete, but still in use \\ \keyv{'DE405'} & \cite{standish98}; default \\ \keyv{'DE421'} & \citet{folkner09} \\ \keyv{'DE430'} & \citet{folkner14} \\ \keyv{'DE431'} & \citet{folkner14} \\ \keyv{'DE432'} & \citet{folkner14} \\ \noalign{\smallskip} \hline \end{tabular} \end{table} Future ephemerides in this series \shall\ be accepted and recognized as they are released. %begin{redtext} %LC post vote Additional ephemerides designations \may\ be recognized by the IAUFWG\index{IAUFWG} upon request. %end{redtext} %LC post vote %%%%%% \subsection{Time unit}\label{sect:timeUnit}\index{time units} When recorded as a global keyword, the unit used to express time \shall\ be specified by the following keyword. \begin{description} \item \kwd{TIMEUNIT} -- [string; default: \keyv{'s'}] The value field of this keyword \shall\ contain a character string that specifies the time unit; the value \should\ be one of those given in Table~\ref{tab:timeUnits}. This time unit \shall\ apply to all time instances and durations that do not have an implied time unit (such as is the case for JD, MJD, ISO-8601, J and B epochs). If this keyword is absent, \keyv{'s'} \shall\ be assumed. \end{description} In an appropriate context, e.g., when an image has a time axis, \kwd{TIMEUNIT} \may\ be overridden by the \indxkwdalt{CUNIT}{i} keywords and their binary-table equivalents (see Table~\ref{ta:WCSkw}). The specification of the time unit allows the values defined in \citet{greisen02}, shown in Table~\ref{tab:timeUnits}, with the addition of the century. See also Sect.~\ref{s:Units} for generalities about units. \begin{table}[h] \centering \caption{Recommended time units }\index{time units} \label{tab:timeUnits} \begin{tabular}{l p{1.5in}} \hline \hline Value & Definition \\ \hline \noalign{\smallskip} \keyv{'s'} & second (default) \\ \keyv{'d'} & day (= 86,400 s) \\ \keyv{'a'} & (Julian) year (= 365.25 d) \\ \keyv{'cy'} & (Julian) century (= 100 a) \\ \noalign{\smallskip} \hline \noalign{\smallskip} \multicolumn{2}{l}{The following values are also acceptable.} \\ \noalign{\smallskip} \hline \noalign{\smallskip} \keyv{'min'} & minute (= 60 s) \\ \keyv{'h'} & day (= 86,400 s) \\ \keyv{'yr'} & (Julian) year (= \keyv{'a'} = 365.25 d) \\ \keyv{'ta'} & tropical year \\ \keyv{'Ba'} & Besselian year \\ \noalign{\smallskip} \hline \end{tabular} \end{table} The use of \keyv{'ta'} and \keyv{'Ba'} is not encouraged, but there are data and applications that require the use of tropical years or Besselian epochs (see Sect.~\ref{epochs}). The length of the tropical year, \keyv{'ta'}, in days is: \\ \begin{eqnarray} 1 \: \mathrm{ta} & = & 365.24219040211236 - 0.00000615251349 \: T \nonumber \\ & & - 6.0921 \times 10^{-10} \: T^2 + 2.6525 \times 10^{-10} \: T^3 \; \mathrm{(d)} \nonumber \end{eqnarray} where $T$ is in Julian centuries since J2000, using time scale TDB. The length of the Besselian year in days is: $$1 \mathrm{Ba} = 365.2421987817 - 0.00000785423\hspace{2 pt} T \hspace{4 pt} \mathrm{(d)} $$ \noindent where $T$ is in Julian centuries since J1900, using time scale ET, although for these purposes the difference with TDB is negligible. Readers are cautioned that the subject of tropical and Besselian years presents a particular quandary for the specification of standards. The expressions presented here are the most accurate available, but are applicable for use when creating data files (which is strongly discouraged), rather than for interpreting existing data that are based upon these units. However, there is no guarantee that the authors of the data applied these particular definitions. Users are therefore advised to pay close attention and attempt to ascertain what the authors of the data really used. %%%%%% \subsection{Time offset, binning, and errors }\label{sect:binning} \subsubsection{Time offset} A uniform clock correction \may\ be applied in bulk with the following single keyword. \begin{description} \item \kwd{TIMEOFFS} -- [floating-point; default: \keyv{0.0}] The value field of this keyword \shall\ contain the value of the offset in time that \shall\ be added to the reference time, given by one of: \kwd{MJDREF}, \kwd{JDREF}, or \kwd{DATEREF}. \end{description} The time offset may serve to set a zero-point offset to a relative time series, allowing zero-relative times, or just higher precision, in the time stamps. Its default value is zero. The value of this keyword affects the values of \kwd{TSTART}, and \kwd{TSTOP}, as well as any time pixel values in a binary table. However, this construct \may\ only be used in tables and \mustnot\ be used in images. \subsubsection{Time resolution and binning}\index{time resolution} The resolution of the time stamps (the width of the time sampling function) \shall\ be specified by the following keyword. \begin{description} \item \kwd{TIMEDEL} -- [floating-point] The value field of this keyword \shall\ contain the value of the time resolution in the units of \kwd{TIMEUNIT}. This construct, when present, \shall\ {\em only} be used in tables and \mustnot\ be used in images. \end{description} In tables this may, for instance, be the size of the bins for time-series data or the bit precision of the time-stamp values. When data are binned in time bins (or, as a special case, events are tagged with a time stamp of finite precision) it is important to know to the position within the bin (or pixel) to which the time stamp refers. Coordinate values normally correspond to the center of all pixels (see Sect.~\ref{sect:WCSkw}); yet clock readings are effectively truncations, not rounded values, and therefore correspond to the lower bound of the pixel. \begin{description} \item \kwd{TIMEPIXR} -- [floating-point; default: \keyv{0.5}] The value field of this keyword \shall\ contain the value of the position within the pixel, from 0.0 to 1.0, to which the time-stamp refers. This construct, when present, \shall\ {\em only} be used in tables and \mustnot\ be used in images. \end{description} A value of \keyv{0.0} may be more common in certain contexts, e.g. when truncated clock readings are recorded, as is the case for almost all event lists. \subsubsection{Time errors} The absolute time error is the equivalent of a systematic error, \shall\ be given by the following keyword. \begin{description} \item \kwd{TIMSYER} -- [floating-point; default: \keyv{0.}] The value field of this keyword \shall\ contain the value of the absolute time error, in units of \kwd{TIMESYS}. \end{description} This keyword \may\ be overridden, in appropriate context (e.g., time axes in image arrays or table columns; by the \indxkw{CSYER}{ia} keywords and their binary-table equivalents (see Table \ref{ta:WCSkw}). The relative time error specifies accuracy of the time stamps relative to each other. This error will usually be much smaller than the absolute time error. This error is equivalent to a random error, and \shall\ be given by the following keyword. \begin{description} \item \kwd{TIMRDER} -- [floating-point; default: \keyv{0.}] The value field of this keyword \shall\ contain the value of the relative time error, i.e. the random error between time stamps, in units of \kwd{TIMESYS}. \end{description} This keyword \may\ be overridden, in appropriate context (e.g., time axes in image arrays or table columns; by the \indxkw{CRDER}{ia} keywords and their binary-table equivalents (see Table \ref{ta:WCSkw}). %%% \subsection{Global time keywords}\label{sect:GlobalTime}\index{time keywords} The time keywords in Table~\ref{tab:timeHdrKw} are likely to occur in headers even when there are no time axes in the data. Except for \kwd{DATE}, they provide the top-level temporal bounds of the data in the HDU. As noted before, they may also be implemented as table columns. Keywords not previously described are defined below; all are included in the summary Table~\ref{ta:WCSkw}. \begin{table}[h] \centering \caption{Keywords for global time values} \label{tab:timeHdrKw}\index{keyword, reserved} \begin{tabular}{l p{2.7in}} \hline \hline Keyword & Notes \\ \hline \noalign{\smallskip} \kwd{DATE}\index{DATE} & Defined in Sect.~\ref{s:dhist}. \\ \kwd{DATE-OBS}\index{DATE-OBS} & Defined in Sect.~\ref{s:kobs}. Keyword value was not restricted to mean the start time of an observation, and has historically also been used to indicate some form of mean observing date and time. To avoid ambiguity use \kwd{DATE-BEG} instead. \\ \kwd{DATE-BEG}\index{DATExxxx} & Defined in this section. \\ \kwd{DATE-AVG} & Defined in Sect.~\ref{sect:SpecRefFrame}. The method by which average times should be calculated is not defined by this Standard. \\ \kwd{DATE-END} & Defined in this section. \\ \kwd{MJD-OBS} & Defined in Sect.~\ref{sect:Celestkw}. \\ \kwd{MJD-BEG} & Defined in this section. \\ \kwd{MJD-AVG} & Defined in Sect.~\ref{sect:SpecRefFrame}. The method by which average times should be calculated is not defined by this Standard. \\ \kwd{MJD-END} & Defined in this section. \\ \kwd{TSTART} & Defined in this section. \\ \kwd{TSTOP} & Defined in this section. \\ \noalign{\smallskip} \hline \end{tabular} \end{table} \vspace{-6pt} % \begin{description} \setlength\itemsep{0.05in} \item \kwd{DATE-BEG} -- [datetime] The value field of this keyword \shall\ contain a character string in ISO-8601 format that specifies the start time of data acquisition in the time system specified by the \kwd{TIMESYS} keyword. \item \kwd{DATE-END} -- [datetime] The value field of this keyword \shall\ contain a character string in ISO-8601 format that specifies the stop time of data acquisition in the time system specified by the \kwd{TIMESYS} keyword. \item \kwd{MJD-BEG} -- [floating-point] The value field of this keyword \shall\ contain the value of the MJD start time of data acquisition in the time system specified by the \kwd{TIMESYS} keyword. \item \kwd{MJD-END} -- [floating-point] The value field of this keyword \shall\ contain the value of the MJD stop time of data acquisition in the time system specified by the \kwd{TIMESYS} keyword. \item \kwd{TSTART} -- [floating-point] The value field of this keyword \shall\ contain the value of the start time of data acquisition in units of \kwd{TIMEUNIT}, relative to \kwd{MJDREF}, \kwd{JDREF}, or \kwd{DATEREF} and \kwd{TIMEOFFS}, in the time system specified by the \kwd{TIMESYS} keyword. \item \kwd{TSTOP} -- [floating-point] The value field of this keyword \shall\ contain the value of the stop time of data acquisition in units of \kwd{TIMEUNIT}, relative to \kwd{MJDREF}, \kwd{JDREF}, or \kwd{DATEREF} and \kwd{TIMEOFFS}, in the time system specified by the \kwd{TIMESYS} keyword. \end{description} The alternate-axis equivalent keywords for \BINTABLE\ extensions, \indxkw{DOBS}{n}, \indxkw{MJDOB}{n}, \indxkw{DAVG}{n}, and \indxkw{MJDA}{n}, as defined in Table~\ref{ta:WCSkw}, are also allowed. Note that of the above only \kwd{TSTART} and \kwd{TSTOP} are relative to the time reference value. As in the case of the time reference value (see Sect.~\ref{trefval}), the JD values supersede DATE values, and MJD values supersede both, in cases where conflicting values are present. It should be noted that, although they do not represent global time values within an HDU, the \indxkw{CRVAL}{ia} and \indxkw{CDELT}{ia} keywords, and their binary-table equivalents (see Table~\ref{ta:WCSkw}), also represent (binary) time values. They should be handled with the same care regarding precision when combining them with the time reference value, as any other time value. Finally, Julian and Besselian epochs (see Sects.~\ref{epochs}~and~\ref{sect:timeUnit}) \may\ be expressed by these two keywords -- to be used with great caution, as their definitions are more complicated and hence their use more prone to confusion. \begin{description} \setlength\itemsep{0.05in} \item \kwd{JEPOCH} -- [floating-point] The value field of this keyword \shall\ contain the value of the Julian epoch, with an implied time scale of \keyv{'TDB'}. \item \kwd{BEPOCH} -- [floating-point] The value field of this keyword \shall\ contain the value of the Besselian epoch, with an implied time scale of \keyv{'ET'}. \end{description} When these epochs are used as time stamps in a table column, their interpretation will be clear from the context. When the keywords appear in the header without obvious context, they \must\ be regarded as equivalents of \kwd{DATE-OBS} and \kwd{MJD-OBS}, i.e., with no fixed definition as to what part of the dataset they refer. %%%%%% \subsection{Other time-coordinate axes} There are a few coordinate axes that are related to time and that are accommodated in this Standard: (temporal) {\em phase}\index{phase}, {\em timelag}\index{timelag}, and {\em frequency}. Phase results from folding a time series on a given period, and can appear in parallel with {\em time} as an alternate description of the same axis. Timelag is the coordinate of cross- and auto-correlation spectra. The temporal {\em frequency} is the Fourier transform equivalent of time and, particularly, the coordinate axis of power spectra; spectra where the dependent variable is the electromagnetic field are excluded here, but see \citet{greisen06}. These coordinate axes \shall\ be specified by giving \indxkw{CTYPE}{i} and its binary-table equivalents one of the values: \keyv{'PHASE'}, \keyv{'TIMELAG'}, or \keyv{'FREQUENCY'}. Timelag units are the regular time units, and the basic unit for frequency is \keyv{'Hz'}. Neither of these two coordinates is a linear or scaled transformation of time, and therefore cannot appear in parallel with time as an alternate description. That is, a given vector of values for an observable can be paired with a coordinate vector of time, or timelag, or frequency, but not with more than one of these; the three coordinates are orthogonal. Phase can appear in parallel with time as an alternate description of the same axis. Phase \shall\ be recorded in the following keywords. \begin{description} \item \indxkw{CZPHS}{ia} -- [floating-point] The value field of this keyword \shall\ contain the value of the time at the zero point of a phase axis. Its units \may\ be \keyv{'deg'}, \keyv{'rad'}, or \keyv{'turn'}. \item \indxkw{CPERI}{ia} -- [floating-point] The value field of this keyword, if present \shall\ contain the value of the period of a phase axis. This keyword can be used only if the period is a constant; if that is not the case, this keyword \should\ either be absent or set to zero. \end{description} % \indxkw{CZPHS}{ia} \may\ instead appear in binary-table forms \indxkw{TCZPH}{n}, \indxkw{TCZP}{na}, \dindxkw{i}{CZPH}{n}, and \dindxkw{i}{CZP}{na}. \indxkw{CPERI}{ia} \may\ instead appear in binary-table forms \indxkw{TCPER}{n}, \indxkw{TCPR}{na}, \dindxkw{i}{CPER}{n}, and \dindxkw{i}{CPR}{na}. The phase, period, and zero point \shall\ be expressed in the globally valid time reference frame and unit as defined by the global keywords (or their defaults) in the header. %%%%%% \subsection{Durations}\index{durations} There is an extensive collection of header keywords that indicate time durations, such as exposure times, but there are many pitfalls and subtleties that make this seemingly simple concept treacherous. Because of their crucial role and common use, keywords are defined below to record exposure and elapsed time. \begin{description} \setlength\itemsep{0.05in} \item \kwd{XPOSURE} -- [floating-point] The value field of this keyword \shall\ contain the value for the effective exposure duration for the data, corrected for dead time and lost time in the units of \kwd{TIMEUNIT}. If the HDU contains multiple time slices, this value \shall\ be the total accumulated exposure time over all slices. \item \kwd{TELAPSE} -- [floating-point] The value field of this keyword \shall\ contain the value for the amount of time elapsed, in the units of \kwd{TIMEUNIT}, between the start and the end of the observation or data stream. \end{description} Durations \mustnot\ be expressed in ISO-8601 format, but only as actual durations (i.e., numerical values) in the units of the specified time unit. Good-Time-Interval (GTI) tables\index{GTI tables} are common for exposures with gaps in them, particularly photon-event files, as they make it possible to distinguish time intervals with ``no signal detected'' from ``no data taken.'' GTI tables in \BINTABLE\ extensions \must\ contain two mandatory columns, \column{START} and \column{STOP}, and \may\ contain one \optional\ column, \column{WEIGHT}. The first two define the interval, the third, with a value between 0 and 1, the quality of the interval; {\em i.e.,} a weight of 0 indicates a {\em Bad}-Time-Interval. \column{WEIGHT} has a default value of 1. Any time interval not covered in the table \shall\ be considered to have a weight of zero. %%%%%% \subsection{Recommended best practices} The following guidelines should be helpful in creating data products with a complete and correct time representation. \begin{itemize} \item The presence of the informational \kwd{DATE} keyword is {\em strongly recommended} in all HDUs. \item One or more of the informational keywords \kwd{DATE-xxxx} and/or \kwd{MJD-xxxx} \should\ be present in all HDUs whenever a meaningful value can be determined. This also applies, e.g., to catalogs derived from data collected over a well-defined time range. \item The global keyword \kwd{TIMESYS} is {\em strongly recommended}. \item The global keywords \kwd{MJDREF} or \kwd{JDREF} or \kwd{DATEREF} are \recommended. \item The remaining informational and global keywords \should\ be present whenever applicable. \item All context-specific keywords \shall\ be present as needed and \required\ by the context of the data. \end{itemize} \subsubsection{Global keywords and overrides} \label{global} For reference to the keywords that are discussed here, see Table~\ref{ta:WCSkw}. The globally applicable keywords listed in Sect.~B of the table serve as default values for the corresponding \kwd{C*} and \kwd{TC*} keywords in that same section, but only when axis and column specifications (including alternate coordinate definitions) use a time scale listed in Table~\ref{table:timescale}, or when the corresponding \kwd{CTYPE} or \kwd{TTYPE} keywords are set to the value \keyv{'TIME'}. Any alternate coordinate specified in a non-recognized time scale assumes the value of the axis pixels or the column cells, optionally modified by applicable scaling and/or reference value keywords; see also Sect.~\ref{sect:timeScale}. \subsubsection{Restrictions on alternate descriptions} \label{restrictions} An image will have at most one time axis as identified by having the \indxkw{CTYPE}{i} value of \keyv{'TIME'} or one of the values listed in Table~\ref{table:timescale}. Consequently, as long as the axis is identified through \indxkw{CTYPE}{i}, there is no need to have axis-number identification on the global time-related keywords. It is expressly prohibited to specify more than one time reference position on this axis for alternate time-coordinate frames, since this would give rise to complicated model-dependent non-linear relations between these frames. Hence, time scales \keyv{'TDB'} and \keyv{'TCB'} (or \keyv{'ET'}, to its precision) \may\ be specified in the same image, but cannot be combined with any of the first nine time scales in Table~\ref{table:timescale}; those first nine can be expressed as linear transformations of each other, too, provided the reference position remains unchanged. Time scale \keyv{'LOCAL'} is by itself, intended for simulations, and \shouldnot\ be mixed with any of the others. \subsubsection{Image time axes} \label{sect:imgTime} Sect.~\ref{sect:WCSkw} requires keywords \indxkw{CRVAL}{ia} to be numeric and they cannot be expressed in ISO-8601 format. Therefore it is \required\ that \indxkw{CRVAL}{ia} contain the elapsed time in units of \kwd{TIMEUNIT} or \indxkw{CUNIT}{ia}, even if the zero point of time is specified by \kwd{DATEREF}. If the image does not use a matrix for scaling, rotation, and shear \citep{greisen02}, \indxkw{CDELT}{ia} provides the numeric value for the time interval. If the \kwd{PC} form of scaling, rotation, and shear \citep{greisen02} is used, \indxkw{CDELT}{ia} provides the numeric value for the time interval, and \indxkw{PC}{i\_j}, where $i = j =$ the index of the time axis (in the typical case of an image cube with Axis~3 being time, $i=j=3$) would take the exact value 1, the default \citep{greisen02}. When the \indxkw{CD}{i\_j} form of mapping is used, \indxkw{CD}{i\_j} provides the numeric value for the time interval. If one of the axes is time and the matrix form is used, then the treatment of the \indxkw{PC}{i\_ja} (or \indxkw{CD}{i\_ja}) matrices involves at least a Minkowsky metric and Lorentz transformations (as contrasted with Euclidean and Galilean). %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% %LC Dick, final % Added 2015-May by RAShaw for (potential inclusion in) v3.1 %clearpage %LC \section{Representations of compressed data} \label{sect:CompressedForm} Minimizing data volume is important in many contexts, particularly for publishers of large astronomical data collections. The following sections describe compressed representations of data in \FITS\ images and \BINTABLE\ extensions that preserve metadata and allow for full or partial extraction of the original data as necessary. The resulting \FITS\ file structure is independent of the specific data-compression algorithm employed. The implementation details for some compression algorithms that are widely used in astronomy are defined in Sect.~\ref{sect:comprAlg}, but other compression techniques could also be supported. See the \FITS\ convention by \citet{white13} for details of the compression techniques, but beware that the specifications in this Standard \shall\ supersede those in the registered convention. % disclaimer added post three-month re-thinking period Compression of \FITS\ files can be beneficial for sites that store or distribute large quantities of data; the present section provides a standard framework that addresses such needs. As implementation of compression/decompression codes can be quite complex, not all software for reading and writing \FITS\ is necessarily expected to support these capabilities. External utilities are available to compress and decompress \FITS\ files\footnote{e.g. \texttt{fpack}/\texttt{funpack}, see \url{https://heasarc.gsfc.nasa.gov/fitsio/fpack/}}. \subsection{Tiled image compression}\index{compressed images} The following describes the process for compressing $n-$dimensional \FITS\ images and storing the resulting byte stream in a variable-length column in a \FITS\ binary table, and for preserving the image header keywords in the table header. The general principle is to first divide the $n-$dimensional image into a rectangular grid of subimages or ``tiles." Each tile is then compressed as a block of data, and the resulting compressed byte stream is stored in a row of a variable-length column in a \FITS\ binary table (see Sect.~\ref{s:BTabl}). By dividing the image into tiles it is possible to extract and decompress subsections of the image without having to decompress the whole image. The default tiling pattern treats each row of a two-dimensional image (or higher-dimensional cube) as a tile, such that each tile contains \kwd{NAXIS1} pixels. This default may not be optimal for some applications or compression algorithms, so any other rectangular tiling pattern \may\ be defined using keywords that are defined below. In the case of relatively small images it may suffice to compress the entire image as a single tile, resulting in an output binary table containing a single row. In the case of three-dimensional data cubes, it may be advantageous to treat each plane of the cube as a separate tile if application software typically needs to access the cube on a plane-by-plane basis. \subsubsection{Required keywords}\index{keyword, required} In addition to the mandatory keywords for \BINTABLE\ extensions (see Sect.~\ref{s:btmk}) the following keywords are reserved for use in the header of a \FITS\ binary-table extension to describe the structure of a valid compressed \FITS\ image. All are mandatory. \begin{description} \setlength\itemsep{0.05in} \item \kwd{ZIMAGE} -- [logical; value \keyv{T}] The value field of this keyword \shall\ contain the logical value \keyv{T} to indicate that the \FITS\ binary-table extension contains a compressed image, and that logically this extension \should\ be interpreted as an image rather than a table. \item \kwd{ZCMPTYPE} -- [string; default: none]\index{compression algorithms} The value field of this keyword \shall\ contain a character string giving the name of the algorithm that was used to compress the image. Only the values given in Table~\ref{tab:CompTypes} are permitted; the corresponding algorithms are described in Sect.~\ref{sect:comprAlg}. Other algorithms may be added in the future. \item \kwd{ZBITPIX} -- [integer; default: none] The value field of this keyword \shall\ contain an integer that gives the value of the \kwd{BITPIX} keyword in the uncompressed \FITS\ image. \item \kwd{ZNAXIS} -- [integer; default: none] The value field of this keyword \shall\ contain an integer that gives the value of the \kwd{NAXIS} keyword (i.e., the number of axes) in the uncompressed \FITS\ image. \item \indxkw{ZNAXIS}{n} -- [integer; indexed; default: none) The value field of these keywords \shall\ contain a positive integer that gives the value of the corresponding \indxkw{NAXIS}{n} keywords (i.e., the size of Axis~$n$) in the uncompressed \FITS\ image. \end{description} The comment fields for the \kwd{BITPIX}, \kwd{NAXIS}, and \indxkw{NAXIS}{n} keywords in the uncompressed image \should\ be copied to the corresponding fields in the \kwd{ZBITPIX}, \kwd{ZNAXIS}, and \indxkw{ZNAXIS}{n} keywords. \subsubsection{Other reserved keywords}\index{keyword, reserved} The compressed image tiles \must\ be stored in the binary table in the same order that the first pixel in each tile appears in the \FITS\ image; the tile containing the first pixel in the image \must\ appear in the first row of the table, and the tile containing the last pixel in the image \must\ appear in the last row of the binary table. The following keywords are reserved for use in describing compressed images stored in \BINTABLE\ extensions; they \may\ be present in the header, and their values depend upon the type of image compression employed. \begin{description} \setlength\itemsep{0.05in} \item \indxkw{ZTILE}{n} -- [integer; indexed; default: \keyv{1} for $n > 1$] The value field of these keywords (where $n$ is a positive integer index that ranges from 1 to \kwd{ZNAXIS}) \shall\ contain a positive integer representing the number of pixels along Axis~$n$ of the compressed tiles. Each tile of pixels \must\ be compressed separately and stored in a row of a variable-length vector column in the binary table. The size of each image dimension (given by \indxkw{ZNAXIS}{n}) need not be an integer multiple of \indxkw{ZTILE}{n}, and if it is not, then the last tile along that dimension of the image will contain fewer image pixels than the other tiles. If the \indxkw{ZTILE}{n} keywords are not present then the default ``row-by-row" tiling will be assumed, i.e., \kwd{ZTILE1}~=~\kwd{ZNAXIS1}, and the value of all the other \indxkw{ZTILE}{n} keywords \must\ equal \keyv{1}. \item \indxkw{ZNAME}{i} -- [string; indexed; default: none] The value field of these keywords (where $i$ is a positive integer index starting with 1) \shall\ supply the names of up to 999 algorithm-specific parameters that are needed to compress or decompress the image. The order of the compression parameters \may\ be significant, and \may\ be defined as part of the description of the specific decompression algorithm. \item \indxkw{ZVAL}{i} -- [string; indexed; default: none] The value field of these keywords (where $i$ is a positive integer index starting with 1) \shall\ contain the values of up to 999 algorithm-specific parameters with the same index $i$. The value of \indxkw{ZVAL}{i} \may\ have any valid \FITS\ data type. \item \kwd{ZMASKCMP} -- [string; default: none] The value field of this keyword \shall\ contain the name of the image compression algorithm that was used to compress the optional null-pixel data mask. This keyword \may\ be omitted if no null-pixel data masks appear in the table. See Sect.~\ref{sect:indefPixels} for details. \item \kwd{ZQUANTIZ} -- [string; default: \keyv{'NO\_DITHER'}] The value field of this keyword \shall\ contain the name of the algorithm that was used to quantize floating-point image pixels into integer values, which were then passed to the compression algorithm as discussed further in Sect.~\ref{sect:fpQuantize}. If this keyword is not present, the default is to assume that no dithering was applied during quantization. \item \kwd{ZDITHER0} -- [integer; default: none] The value field of this keyword \shall\ contain a positive integer (that may range from 1 to 10000 inclusive) that gives the seed value for the random dithering pattern that was used when quantizing the floating-point pixel values. This keyword \may\ be absent if no dithering was applied. See Sect.~\ref{sect:fpQuantize} for further discussion. \end{description} The following keywords are reserved to preserve a verbatim copy of the {\em value and comment fields} for keywords in the original uncompressed \FITS\ image that were used to describe its structure. These optional keywords, when present, \shall\ be used when reconstructing an identical copy of the original \FITS\ HDU of the uncompressed image. They \shouldnot\ appear in the compressed image header unless the corresponding keywords were present in the uncompressed image. \begin{description} \setlength\itemsep{0.05in} \item \kwd{ZSIMPLE} -- [logical; value \keyv{T}] The value field of this keyword \must\ contain the value of the original \kwd{SIMPLE} keyword in the uncompressed image. \item \kwd{ZEXTEND} -- [string] The value field of this keyword \must\ contain the value of the original \kwd{EXTEND} keyword in the uncompressed image. \item \kwd{ZBLOCKED} -- [logical] The value field of this keyword \must\ contain the value of the original \kwd{BLOCKED} keyword in the uncompressed image. \item \kwd{ZTENSION} -- [string] The value field of this keyword \must\ contain the original \kwd{XTENSION} keyword in the uncompressed image. \item \kwd{ZPCOUNT} -- [integer] The value field of this keyword \must\ contain the original \kwd{PCOUNT} keyword in the uncompressed image. \item \kwd{ZGCOUNT} -- [integer] The value field of this keyword \must\ contain the original \kwd{GCOUNT} keyword in the uncompressed image. \item \kwd{ZHECKSUM} -- [string] The value field of this keyword \must\ contain the original \kwd{CHECKSUM} keyword (see Sect.~\ref{s:resk}.7)\index{checksum} in the uncompressed image. \item \kwd{ZDATASUM} -- [string] The value field of this keyword \must\ contain the original \kwd{DATASUM} keyword (see Sect.~\ref{s:resk}.7)\index{checksum} in the uncompressed image. \end{description} The \kwd{ZSIMPLE}, \kwd{ZEXTEND}, and \kwd{ZBLOCKED} keywords \mustnot\ be used unless the original uncompressed image was contained in the primary array of a \FITS\ file. The \kwd{ZTENSION}, \kwd{ZPCOUNT}, and \kwd{ZGCOUNT} keywords \mustnot\ be used unless the original uncompressed image was contained in an \IMAGE\ extension. The \FITS\ header of the compressed image \may\ contain other keywords. If a \FITS\ primary array or \IMAGE\ extension is compressed using the procedure described here, it is {\em strongly recommended} that all the keywords (including comment fields) in the header of the original image, except for the mandatory keywords mentioned above, be copied verbatim and in the same order into the header of the binary-table extension that contains the compressed image. All these keywords will have the same meaning and interpretation as they did in the original image, even in cases where the keyword is not normally expected to occur in the header of a binary-table extension (e.g., the \kwd{BSCALE} and \kwd{BZERO} keywords, or the world-coordinate-system keywords such as \indxkw{CTYPE}{n}, \indxkw{CRPIX}{n}, and \indxkw{CRVAL}{n}). %%%% \subsubsection{Table columns} Two columns in the \FITS\ binary table are defined below to contain the compressed image tiles; the order of the columns in the table is not significant. One of the table columns describes optional content; but when this column appears it \must\ be used as defined in this section. The column names (given by the \indxkw{TTYPE}{n} keyword) are reserved; they are shown here in upper-case letters, but case is not significant. \begin{description} \setlength\itemsep{0.05in} \item \column{COMPRESSED\_DATA} -- [variable-length; \required] Each row of this column \must\ contain the byte stream that is generated as a result of compressing the corresponding image tile. The data type of the column (as given by the \indxkw{TFORM}{n} keyword) \must\ be one of \keyv{'1PB'}, \keyv{'1PI'}, or \keyv{'1PJ'} (or the equivalent \keyv{'1QB'}, \keyv{'1QI'}, or \keyv{'1QJ'}), depending on whether the compression algorithm generates an output stream of 8-bit bytes, or integers of 16, or 32 bits respectively. \end{description} When using the quantization method to compress floating-point images that is described in Sect.~\ref{sect:fpQuantize}, it sometimes may not be possible to quantize some of the tiles (e.g., if the range of pixels values is too large or if most of the pixels have the same value and hence the calculated RMS noise level in the tile is close to zero). There also may be other rare cases where the nominal compression algorithm cannot be applied to certain tiles. In these cases, an alternate technique \may\ be used in which the raw pixel values are losslessly compressed with the Gzip algorithm. \begin{description} \item \column{GZIP\_COMPRESSED\_DATA} [variable-length; \optional] If the raw pixel values in an image tile are losslessly compressed with the Gzip algorithm, the resulting byte stream \must\ be stored in this column (with a \keyv{'1PB'} or \keyv{'1QB'} variable-length array-column format). The corresponding \column{COMPRESSED\_DATA} column for these tiles \must\ contain a null pointer (i.e., the pair of integers that constitute the descriptor for the column \must\ both have the value zero: see Sect.~\ref{s:app_varlen}). \end{description} The compressed data columns described above \may\ use either the \keyv{'1P'} or \keyv{'1Q'} variable-length array \FITS\ column format if the size of the heap in the compressed \FITS\ file is $< 2.1$ GB. If the the heap is larger than 2.1 GB, then the \keyv{'1Q'} format (which uses 64-bit pointers) \must\ be used. %% NB: omitted 'UNCOMPRESSED_DATA' column, as it has already been deprecated by the convention. When using the \optional\ quantization method described in Sect.~\ref{sect:fpQuantize} to compress floating-point images, the following columns are \required. \begin{description} \setlength\itemsep{0.05in} \item \column{ZSCALE} -- [floating-point; \optional] This column \shall\ be used to contain linear scale factors that, along with \column{ZZERO}, transform the floating-point pixel values in each tile to integers via, \begin{eqnarray} I_i = \mathrm{round}\left (\frac{F_i - \mathtt{\column{ZZERO}}} {\mathtt{\column{ZSCALE}}} \right ) \label{eq:zscale} \end{eqnarray} where $I_i$ and $F_i$ are the integer and (original) floating-point values of the image pixels, respectively, and the \texttt{round} function rounds the result to the nearest integer value. \item \column{ZZERO} -- [floating-point; optional] This column \shall\ be used to contain zero-point offsets that are used to scale the floating-point pixel values in each tile to integers via Eq.~\ref{eq:zscale}. \end{description} Do not confuse the \column{ZSCALE} and \column{ZZERO} columns with the \kwd{BSCALE} and \kwd{BZERO} keywords (defined in Sect.~\ref{s:array}) that may be present in integer \FITS\ images. Any such integer images \should\ normally be compressed without any further scaling, and the \kwd{BSCALE} and \kwd{BZERO} keywords \should\ be copied verbatim into the header of the binary table containing the compressed image. Some images contain undefined pixel values; in uncompressed floating-point images these pixels have an IEEE NaN value. However, these pixel values will be altered when using the quantization method described in Sect.~\ref{sect:fpQuantize} to compress floating-point images. The value of the undefined pixels \may\ be preserved in the following way. \begin{description} \item \column{ZBLANK} -- [integer; \optional] When present, this column \shall\ be used to store the integer value that represents undefined pixels in the scaled integer array. The \recommended\ value for \column{ZBLANK} is \texttt{$-$2147483648}, the largest negative 32-bit integer. If the same null value is used in every tile of the image, then \kwd{ZBLANK} \may\ be given in a header keyword instead of a table column; if both a keyword and a table column named \column{ZBLANK} are present, the values in the table column \must\ be used. If there are no undefined pixels in the image then \column{ZBLANK} is \notrequired\ to be present either as a table column or a keyword. \end{description} If the uncompressed image has an integer data type (\kwd{ZBITPIX} $>$ 0) then the value of undefined pixels is given by the \kwd{BLANK} keyword (see Sect.~\ref{s:FloatingPoint}), which \should\ be used instead of \column{ZBLANK}. When using some compression techniques that do not exactly preserve integer pixel values, it may be necessary to store the location of the undefined pixels prior to compressing the image. The locations \may\ be stored in an image mask, which \must\ itself be compressed and stored in a table column with the following definition. See Sect.~\ref{sect:indefPixels} for more details. \begin{description} \item \column{NULL\_PIXEL\_MASK} -- [integer array; \optional] When present, this column \shall\ be used to store, in compressed form, an image mask with the same original dimensions as the uncompressed image, that records the location of the undefined pixels. The process defined in Sect.~\ref{sect:indefPixels} \shall\ be used to construct the compressed pixel mask. \end{description} Additional columns \may\ be present in the table to supply other parameters that relate to each image tile. However, these parameters \shouldnot\ be recorded in the image HDU when the uncompressed image is restored. %%%%%% \subsection{Quantization of floating-point data}\label{sect:fpQuantize}\index{quantization of data} While floating-point format images may be losslessly compressed, noisy images often do not compress very well. Higher compression can only be achieved by removing some of this noise without losing the useful information content. One commonly used technique for reducing the noise is to scale the floating-point values into quantized integers using Eq.~\ref{eq:zscale}, and using the \column{ZSCALE} and \column{ZZERO} columns to record the two scaling coefficients that are used for each tile. Note that the absence of these two columns in a tile-compressed floating-point image is an indication that the image was not scaled, and was instead losslessly compressed. An effective scaling algorithm for preserving a specified amount of noise in each pixel value is described by \citet{white99} and by \citet{pence09}. With this method, the \column{ZSCALE} value (which is numerically equal to the spacing between adjacent quantization levels) is calculated to be some fraction, $Q$, of the RMS noise as measured in background regions of the image. \citet{pence09} shows that the number of binary bits of noise that are preserved in each pixel value is given by $log_2(Q)+1.792$. The $Q$ value directly affects the compressed file size: decreasing $Q$ by a factor of two will decrease the file size by about one bit per pixel. In order to achieve the greatest amount of compression, one should use the smallest value of $Q$ that still preserves the required amount of photometric and astrometric precision in the image. %Image quality will remain comparable regardless of the noise level. A potential problem when applying this scaling method to astronomical images, in particular, is that it can lead to a systematic bias in the measured intensities in faint parts of the image. As the image is quantized more coarsely, the measured intensity of the background regions of the sky will tend to be biased towards the nearest quantize level. One very effective technique for minimizing this potential bias is to \textsl{dither} the quantized pixel values by introducing random noise during the quantization process. So instead of simply scaling every pixel value in the same way using Eq.~\ref{eq:zscale}, the quantized levels are randomized by using this slightly modified equation: \begin{eqnarray} I_i = \mathrm{round}\left (\frac{F_i - \mathtt{\column{ZZERO}}} {\mathtt{\column{ZSCALE}}} + R_i - 0.5\right ) \label{eq:quantize} \end{eqnarray} \noindent where $R_i$ is a random number between 0.0 and 1.0, and 0.5 is subtracted so that the mean quantity equals 0. Then restoring the floating-point value, the same $R_i$ is used with the inverse formula: \begin{eqnarray} F_i = ((I_i - R_i + 0.5) * \mathtt{\column{ZSCALE}}) + \mathtt{\column{ZZERO}}. \label{eq:unquantize} \end{eqnarray} This ``subtractive dithering'' technique has the effect of dithering the zero point of the quantization grid on a pixel-by-pixel basis without adding any actual noise to the image. The net effect of this is that the mean (and median) pixel value in faint regions of the image more closely approximate the value in the original unquantized image than if all the pixels are scaled without dithering. The key requirement when using this subtractive-dithering technique is that \textit{the exact same random-number sequence} \must\ be used when quantizing the pixel values to integers, and when restoring them to floating-point values. While most computer languages supply a function for generating random numbers, these functions are not guaranteed to generate the same sequence of numbers every time. An algorithm for generating a repeatable sequence of pseudo-random numbers is given in Appendix~\ref{sect:RandomNum}; this algorithm \must\ be used when applying a subtractive dither. \subsubsection{Dithering algorithms}\label{sect:ditherAlg}\index{dithering} The \kwd{ZQUANTIZ} keyword, if present, \must\ have one of the following values to indicate the type of quantization, if any, that was applied to the floating-point image for compression. \begin{description} \setlength\itemsep{0.05in} \item \keyv{'NO\_DITHER'} -- No dithering was performed; the floating-point pixels were simply quantized using Eq.~\ref{eq:zscale}. This option \shall\ be assumed if the \kwd{ZQUANTIZ} keyword is not present in the header of the compressed floating-point image. \item \keyv{'SUBTRACTIVE\_DITHER\_1'} -- The basic subtractive dithering was performed, the algorithm for which is described below. Note that an image quantized using this technique can still be unquantized using the simple linear scaling function given by Eq.~\ref{eq:zscale}, at the cost of introducing slightly more noise in the image than if the full subtractive-dithering algorithm were applied. \item \keyv{'SUBTRACTIVE\_DITHER\_2'} -- This dithering algorithm is identical to that for \keyv{'SUBTRACTIVE\_DITHER\_1'}, except that any pixels in the floating-point image that are exactly equal to 0.0 are represented by the reserved value $-2147483647$ in the quantized integer array. When the image is subsequently decompressed and unscaled, these pixels \must\ be restored to their original value of 0.0. This dithering option is useful if the zero-valued pixels have special significance to the data analysis software, so that the value of these pixels \mustnot\ be dithered. \end{description} The process for generating a subtractive dither for a floating-point image is the following. \begin{enumerate} \item Generate a sequence of 10000 single-precision floating-point random numbers, RN, with a value between 0.0 and 1.0. Since it could be computationally expensive to generate a unique random number for every pixel of large images, simply cycle through this look-up table of random numbers. \item Choose an integer in the range 1 to 10000 to serve as an initial seed value for creating a unique sequence of random numbers from the array that was calculated in the previous step. The purpose of this is to reduce the chances of applying the same dithering pattern to two images that are subsequently subtracted from each other (or co-added), because the benefits of randomized dithering are lost if all the pixels are dithered in phase with each other. The exact method for computing this seed integer is not important as long as the value is chosen more or less randomly. \item Write the integer seed value that was selected in the previous step as the value of the \kwd{ZDITHER0} keyword in the header of the compressed image. This value is required to recompute the same dithering pattern when decompressing the image. \item Before quantizing each tile of the floating-point image, calculate an initial value for two offset parameters, $I_0$ and $I_1$, with the following formulae: \begin{eqnarray} I_0 = \mathrm{mod}( N_\mathrm{tile} - 1 + \mathtt{\kwd{ZDITHER0}}, 10000) \\ I_1 = \mathrm{INT ( RN}(I_0) * 500.) \label{eq:offset1} \end{eqnarray} \noindent where $N_\mathrm{tile}$ is the row number in the binary table that is used to store the compressed bytes for that tile, \kwd{ZDITHER0} is that value of that keyword, and RN($I_0$) is the value of the $I_0^\mathrm{th}$ random number in the sequence that was computed in the first step. Note that $I_0$ has a value in the range 0 to 9999 and $I_1$ has a value in the range 0 to 499. This method for computing $I_0$ and $I_1$ was chosen so that a different sequence of random numbers is used to compress successive tiles in the image, and so that the sequence of $I_1$ values has a length of order 100-million elements before repeating. \item Now quantize each floating-point pixel in the tile using Eq.~\ref{eq:quantize} and using random number RN($I_1$) for the first pixel. Increment the value of $I_1$ for each subsequent pixel in the tile. If $I_1$ reaches the upper limit of %begin{redtext} %LC fix post approval 500, %end{redtext} then increment the value of $I_0$ and recompute $I_1$ from Eq.~\ref{eq:offset1}. If $I_0$ also reaches the upper limit of 10000, then reset $I_0$ to 0. If the floating-point pixel has an IEEE NaN value, then it is not quantized or dithered but instead is set to the reserved integer value specified by the \kwd{ZBLANK} keyword. For consistency, the value of $I_1$ \should\ also be incremented in this case even though it is not used. \item Compress the array of quantized integers using the lossless algorithm that is specified by the \kwd{ZCMPTYPE} keyword (use \keyv{'RICE\_1'} by default). \item Write the compressed byte stream into the \column{COMPRESSED\_DATA} column in the appropriate row of the binary table corresponding to that tile. \item Write the linear scaling and zero-point values that were used in Eq.~\ref{eq:quantize} for that tile into the \column{ZSCALE} and \column{ZZERO} columns, respectively, in the same row of the binary table. \item Repeat Steps 4 through 8 for each tile of the image. \end{enumerate} %%%% \subsubsection{Preserving undefined pixels with lossy compression}\label{sect:indefPixels}\index{compression, lossy} The undefined pixels in integer images are flagged by a reserved \kwd{BLANK} value and will be preserved if a lossless compression algorithm is used. (\kwd{ZBLANK} is used for undefined pixels in floating-point images.) If the image is compressed with a lossy algorithm, then some other technique \must\ be used to identify the undefined pixels in the image. In this case it is \recommended\ that the undefined pixels be recorded with the following procedure. \begin{enumerate} \item Create an integer data mask with the same dimensions as the image tile. \item For each undefined pixel in the image, set the corresponding mask pixels to 1 and all the other pixels to 0. \item Compress the mask array using a lossless algorithm such as PLIO or Gzip, and record the name of that algorithm with the keyword \kwd{ZMASKCMP}. \item Store the compressed byte stream in a variable-length-array column called \column{NULL\_PIXEL\_MASK} in the table row corresponding to that image tile. \end{enumerate} The data mask array pixels \should\ have the shortest integer data type that is supported by the compression algorithm (i.e., usually eight-bit bytes). When decompressing the image tile, the software \must\ check if the corresponding compressed data mask exists with a length greater than 0, and if so, decompress the mask and set the corresponding undefined pixels in the image array to the value given by the \kwd{BLANK} keyword. %%%%%% %begin{redtext} \subsection{Tiled table compression} \label{sect:tiledTable}\index{compressed binary tables} The following section describes the process for compressing the content of \BINTABLE\ columns. Some additional details of \BINTABLE\ compression may be found in \citet{pence13}, but the specifications in this Standard \shall\ supersede those in the registered convention. The uncompressed table \may\ be subdivided into tiles, each containing a subset of rows, then each column of data within each tile is extracted, compressed, and stored as a variable-length array of bytes in the output compressed table. The header keywords from the uncompressed table, with only a few limited exceptions, \shall\ be copied verbatim to the header of the compressed table. The compressed table \must\ itself be a valid \FITS\ binary table (albeit one where the contents cannot be interpreted without decompressing the contents) that contains the same number and order of columns as in the uncompressed table, and that contains one row for each tile of rows in the uncompressed table. Only the compression algorithms specified in Sect.~\ref{sect:tabCompAlg} are permitted. \subsubsection{Required keywords}\index{keyword, required} With only a few exceptions noted below, all the keywords and corresponding comment fields from the uncompressed table \must\ be copied verbatim, in order, into the header of the compressed table. Note in particular that the values of the reserved column descriptor keywords \indxkw{TTYPEn}{}, \indxkw{TUNIT}{n}, \indxkw{TSCAL}{n}, \indxkw{TZERO}{n}, \indxkw{TNULL}{n}, \indxkw{TDISP}{n}, and \indxkw{TDIM}{n}, as well as all the column-specific WCS keywords defined in the \FITS\ Standard, \must\ have the same values and data types in both the original and in the compressed table, with the understanding that these keywords apply to the uncompressed data values. The only keywords that \mustnot\ be copied verbatim from the uncompressed table header to the compressed table header are the mandatory \kwd{NAXIS1}, \kwd{NAXIS2}, \kwd{PCOUNT}, and \indxkw{TFORM}{n} keywords, and the optional \kwd{CHECKSUM}, \kwd{DATASUM} %, %LC (see Sect.~\ref{s:resk}.7)\index{checksum}, and \kwd{THEAP} keywords. These keywords must necessarily describe the contents and structure of the compressed table itself. The original values of these keywords in the uncompressed table \must\ be stored in a new set of reserved keywords in the compressed table header. Note that there is no need to preserve a copy of the \kwd{GCOUNT} keyword because the value is always equal to \keyv{1} for \BINTABLE\ extensions. The complete set of keywords that have a reserved meaning within a tile-compressed binary table are given below. \begin{description} \setlength\itemsep{0.05in} \item \kwd{ZTABLE} -- [logical; value: \keyv{T}] The value field of this keyword \shall\ be \keyv{T} to indicate that the \FITS\ binary-table extension contains a compressed \BINTABLE, and that logically this extension \should\ be interpreted as a tile-compressed binary table. \item \kwd{ZNAXIS1} -- [integer; default: none] The value field of this keyword \shall\ contain an integer that gives the value of the \kwd{NAXIS1} keyword in the original uncompressed \FITS\ table header. This represents the width in bytes of each row in the uncompressed table. \item \kwd{ZNAXIS2} -- [integer; default: none] The value field of this keyword \shall\ contain an integer that gives the value of the \kwd{NAXIS2} keyword in the original uncompressed \FITS\ table header. This represents the number of rows in the uncompressed table. \item \kwd{ZPCOUNT} -- [integer; default: none] The value field of this keyword \shall\ contain an integer that gives the value of the \kwd{PCOUNT} keyword in the original uncompressed \FITS\ table header. \item \indxkw{ZFORM}{n} -- [string; indexed; default: none] The value field of these keywords \shall\ contain the character-string values of the corresponding \indxkw{TFORM}{n} keywords that defines the data type of Column~$n$ in the original uncompressed \FITS\ table. \item \indxkw{ZCTYP}{n} -- [string; indexed; default: none] The value field of these keywords \shall\ contain the character-string value mnemonic name of the algorithm that was used to compress Column~$n$ of the table. The only permitted values are given in Sect.~\ref{sect:tabCompAlg}, and the corresponding algorithms are described in Sect.~\ref{sect:comprAlg}. \item \kwd{ZTILELEN} -- [integer; default: none] The value field of this keyword \shall\ contain an integer representing the number of rows of data from the original binary table that are contained in each tile of the compressed table. The number of rows in the last tile may be fewer than in the previous tiles. Note that if the entire table is compressed as a single tile, then the compressed table will only contains a single row, and the \kwd{ZTILELEN} and \kwd{ZNAXIS2} keywords will have the same value. \end{description} \subsubsection{Procedure for table compression} The procedure for compressing a \FITS\ binary table consists of the following sequence of steps. \begin{enumerate} \setlength\itemsep{0.05in} \item{Divide table into tiles (\optional)} In order to limit the amount of data that must be managed at one time, large \FITS\ tables \may\ be divided into tiles, each containing the same number of rows (except for the last tile, which \may\ contain fewer rows). Each tile of the table is compressed in order, and each is stored in a single row in the output compressed table. There is no fixed upper limit on the allowed tile size, but for practical purposes it is \recommended\ that it not exceed 100~MB. \item{Decompose each tile into the component columns} \FITS\ binary tables are physically stored in row-by-row sequential order, such that the data values for the first row in each column are followed by the values in the second row, and so on (see Sect.~\ref{s:MbinT}). Because adjacent columns in binary tables can contain very non-homogeneous types of data, it can be challenging to efficiently compress the native stream of bytes in the \FITS\ tables. For this reason, the table is first decomposed into its component columns, and then each column of data is compressed separately. This also allows one to choose the most-efficient compression algorithm for each column. \item{Compress each column of data} Each column of data \must\ be compressed with one of the lossless compression algorithms described in Sect.~\ref{sect:comprAlg}. If the table is divided into tiles, then the same compression algorithm \must\ be applied to a given column in every tile. In the case of variable-length array columns (where the data are stored in the table heap: see Sect.~\ref{s:app_varlen}), each individual variable-length vector \must\ be compressed separately. \item{Store the compressed bytes} The compressed stream of bytes for each column \must\ be written into the corresponding column in the output table. The compressed table \must\ have exactly the same number and order of columns as the input table, however, the data type of the columns in the output table will all have a variable-length byte data type, with \indxkw{TFORM}{n}~=~\keyv{'1QB'}. Each row in the compressed table corresponds to a tile of rows in the uncompressed table. In the case of variable-length array columns, the array of descriptors that point to each compressed variable-length array, as well as the array of descriptors from the input uncompressed table, \must\ also be compressed and written into the corresponding column in the compressed table. See Sect.~\ref{sect:VLAcols} for more details. \end{enumerate} \subsubsection{Compression directive keywords}\label{compDirKwd} The following compression-directive keywords, if present in the header of the table to be compressed, are reserved to provide guidance to the compression software on how the table should be compressed. The compression software \should\ attempt to obey these directives, but if that is not possible the software \may\ disregard them and use an appropriate alternative. These keywords are optional, but \must\ be used as specified below. \begin{itemize} \setlength\itemsep{0.05in} \item \kwd{FZTILELN} -- [integer] The value field of this keyword \shall\ contain an integer that specifies the requested number of table rows in each tile that are to be compressed as a group. \item \kwd{FZALGOR} -- [string] The value field of this keyword \shall\ contain a character string giving the mnemonic name of the algorithm that is requested to be used by default to compress every column in the table. The permitted values are given in Sect.~\ref{sect:tabCompAlg}. \item \indxkw{FZALG}{n} -- [string; indexed] The value fields of these keywords \shall\ contain a character string giving the mnemonic name of the algorithm that is requested to compress Column~$n$ of the table. The current allowed values are the same as for the \kwd{FZALGOR} keyword. The \kwd{FZALGn} keyword takes precedence over \kwd{FZALGOR} in determining which algorithm to use for a particular column if both keywords are present. %If the column cannot be compressed with the requested algorithm (e.g., if it has an inappropriate data type), then a default compression algorithm will be used instead. \end{itemize} \subsubsection{Other reserved keywords}\index{keyword, reserved} The following keywords are reserved to store a verbatim copy of the value and comment fields for specific keywords in the original uncompressed \BINTABLE. These keywords, if present, \should\ be used to reconstruct an identical copy of the uncompressed \BINTABLE, and \shouldnot\ appear in the compressed table header unless the corresponding keywords were present in the uncompressed \BINTABLE. \begin{description} \setlength\itemsep{0.05in} \item \kwd{ZTHEAP} -- [integer; default: none] The value field of this keyword \shall\ contain an integer that gives the value of the \kwd{THEAP} keyword if present in the original uncompressed \FITS\ table header. \item \kwd{ZHECKSUM} -- [string; default: none] The value field of this keyword \shall\ contain a character string that gives the value of the \kwd{CHECKSUM} keyword (see Sect.~\ref{s:resk}.7)\index{checksum} in the original uncompressed \FITS\ HDU. \item \kwd{ZDATASUM} -- [string; default: none] The value field of this keyword \shall\ contain a character string that gives the value of the \kwd{DATASUM} keyword (see Sect.~\ref{s:resk}.7)\index{checksum} in the original uncompressed \FITS\ HDU. \end{description} \subsubsection{Supported compression algorithms for tables}\label{sect:tabCompAlg}\index{compression algorithms} The permitted algorithms for compressing \BINTABLE\ columns are \keyv{'RICE\_1'}, \keyv{'GZIP\_1'}, and \keyv{'GZIP\_2'} (plus \keyv{'NOCOMPRESS'}), which are lossless and are described in Sect.~\ref{sect:comprAlg}. Lossy compression could be allowed in the future once a process is defined to preserve the details of the compression. \subsubsection{Compressing variable-length array columns}\label{sect:VLAcols}\index{variable-length arrays, compression} Compression of \BINTABLE\ tiles that contain variable-length array (VLA) columns requires special consideration because the array values in these columns are not stored directly in the table, but are instead stored in a data heap, which follows the main table (see Sect.~\ref{s:app_varlen}). The VLA column in the original, uncompressed table only contains descriptors, which comprise two integers that give the size and location of the arrays in the heap. When decompressing, these descriptor values will be needed to write the decompressed VLAs back into the same location in the heap as in the original uncompressed table. Thus, the following process \must\ be followed, in order, when compressing a VLA column within a tile. Refer to \citet{pence13} for additional details. \begin{enumerate} \setlength\itemsep{0.05in} \item For each VLA in the column: \begin{itemize} \item read the array from the input table, and compress it using the algorithm specified by \kwd{ZCTYP} for this VLA column; \item write the resulting byte stream to the heap of the compressed table; and \item store (or append) the descriptors to the compressed byte stream (which \must\ be 64-bit Q-type) in a temporary array. \end{itemize} \item Append the VLA descriptors from the uncompressed table (which \may\ be either Q-type or P-type) to the temporary array of VLA descriptors for the compressed table. \item Compress the combined array of descriptors using \keyv{'GZIP\_1'}, and write that byte stream into the corresponding VLA column in the output table, so that the compressed array is appended to the heap. \end{enumerate} When decompressing a VLA column, two stages of decompression \must\ be performed in order. \begin{enumerate} \setlength\itemsep{0.05in} \item Decompress the combined array of descriptors using the Gzip algorithm. \item For each descriptor to a compressed array: \begin{itemize} \item read the compressed VLA from the compressed table, and decompress it using the algorithm specified by \kwd{ZCTYP} for this VLA column; and \item write it to the correct location in the decompressed table. \end{itemize} \end{enumerate} %end{redtext} %%%%%% \subsection{Compression algorithms}\label{sect:comprAlg}\index{compression algorithms} \begin{table}[h] \centering \caption{Valid mnemonic values for the \kwd{ZCMPTYPE} and \indxkw{ZCTYP}{n} keywords} \label{tab:CompTypes} \begin{tabular}{l c p{1.9in}} \hline \hline Value & Sect. & Compression Type \\ \hline \noalign{\smallskip} \keyv{'RICE\_1'} & \ref{Rice} & Rice algorithm for integer data \\ %\keyv{'RICE\_ONE'} & \ref{Rice} & Alias for Rice algorithm \\ % RAS: purposely omitted \keyv{'GZIP\_1'} & \ref{gzip} & Combination of the LZ77 algorithm and Huffman coding, used in GNU Gzip \\ \keyv{'GZIP\_2'} & \ref{gzip} & Like \keyv{'GZIP\_1'}, but with reshuffled byte values \\ \keyv{'PLIO\_1'} & \ref{plio} & IRAF PLIO algorithm for integer data \\ \keyv{'HCOMPRESS\_1'} & \ref{Hcompress} & H-compress algorithm for two-dimensional images \\ \keyv{'NOCOMPRESS'} & & The HDU remains uncompressed \\ \noalign{\smallskip} \hline \end{tabular} \end{table} %vspace{-12pt} The name of the permitted algorithms for compressing \FITS\ HDUs, as recorded in the \kwd{ZCMPTYPE} keyword, are listed in Table~\ref{tab:CompTypes}; if other types are later supported, they \must\ be registered with the IAUFWG to reserve the keyword values. Keywords for the parameters of supported compression algorithms have also been reserved, and are described with each algorithm in the subsections below. If alternative compression algorithms require keywords beyond those defined below, they \must\ also be registered with the IAUFWG to reserve the associated keyword names. \subsubsection{Rice compression}\label{Rice}\index{Rice compression} When \kwd{ZCMPTYPE}~=~\keyv{'RICE\_1'}, the Rice algorithm \citep{rice93} \shall\ be used for data (de)compression. When selected, the keywords in Table~\ref{tab:RiceKw} \should\ also appear in the header with one of the values indicated. If these keywords are absent, then their default values \must\ be used. The Rice algorithm is lossless, but can only be applied to integer-valued arrays. It offers a significant performance advantage over the other compression techniques \citep[see][]{white13}. \begin{table}[h] \setlength{\tabcolsep}{3pt} \centering \caption{Keyword parameters for Rice compression} \label{tab:RiceKw} \begin{tabular}{l l c p{1.5in}} \hline \hline & \multicolumn{2}{c}{Values} & \\ \cline{2-3} Keyword & Permitted & Default & Meaning \\ \hline \noalign{\smallskip} \kwd{ZNAME1} & \keyv{'BLOCKSIZE'} & $-$ & Size of block in pixels \\ \kwd{ZVAL1} & \keyv{16}, \keyv{32} & \keyv{32} & No. of pixels in a block \\ \kwd{ZNAME2} & \keyv{'BYTEPIX'} & $-$ & Size of pixel value in bytes \\ \kwd{ZVAL2} & \keyv{1}, \keyv{2}, \keyv{4}, \keyv{8} & \keyv{4} & No. of eight-bit bytes per original pixel value \\ \noalign{\smallskip} \hline \end{tabular} \end{table} \vspace{-12pt} \subsubsection{Gzip compression}\label{gzip}\index{Gzip compression} When \kwd{ZCMPTYPE}~=~\keyv{'GZIP\_1'}, the Gzip algorithm \shall\ be used for data (de)compression. There are no algorithm parameters, so the keywords \indxkw{ZNAME}{n} and \indxkw{ZVAL}{n} \shouldnot\ appear in the header. The Gzip algorithm is used in the free GNU software compression utility of the same name. It was created by J.-L. Gailly and M. Adler, based on the DEFLATE algorithm \citep{deutsch96}, which is a combination of LZ77 \citep{LZ77} and Huffman coding. The Unix \texttt{gzip} program accepts an integer parameter that provides a trade between optimization for speed (1) and compression ratio (9), which does not affect the format of the resultant data stream. The selection of this parameter is an implementation detail that is not covered by this Standard. When \kwd{ZCMPTYPE}~=~\keyv{'GZIP\_2'}, the gzip2 algorithm \shall\ be used for data (de)compression. The gzip2 algorithm is a variation on \keyv{'GZIP\_1'}. There are no algorithm parameters, so the keywords \indxkw{ZNAME}{n} and \indxkw{ZVAL}{n} \shouldnot\ appear in the header. In this case the bytes in the array of data %image pixel values are shuffled so that they are arranged in order of decreasing significance before being compressed. For example, a five-element contiguous array of two-byte (16-bit) integer values, with an original big-endian byte order of: $$A_1 A_2 B_1 B_2 C_1 C_2 D_1 D_2 E_1 E_2$$ will have the following byte order after shuffling: $$A_1 B_1 C_1 D_1 E_1 A_2 B_2 C_2 D_2 E_2,$$ where $A_1, B_1, C_1, D_1,$ and $E_1$ are the most-significant bytes from each of the integer values. Byte shuffling \shall\ {\em only} be performed for integer or floating-point numeric data types; logical, bit, and character types \mustnot\ be shuffled. \subsubsection{IRAF/PLIO compression}\label{plio}\index{PLIO compression} When \kwd{ZCMPTYPE}~=~\keyv{'PLIO\_1'}. the IRAF PLIO algorithm \shall\ be used for data (de)compression. There are no algorithm parameters, so the keywords \indxkw{ZNAME}{n} and \indxkw{ZVAL}{n} \shouldnot\ appear in the header. The PLIO algorithm was developed to store integer-valued image masks in a compressed form. The compression algorithm used is based on run-length encoding, with the ability to dynamically follow level changes in the image, in principle allowing a 16-bit encoding to be used regardless of the image depth. However, this algorithm has only been implemented in a way that supports image depths of no more than 12 bits; therefore \keyv{'PLIO\_1'} \must\ {\em only} be used for integer image types with values between 0 and $2^{24}$. The compressed line lists are stored as variable-length arrays of type short integer (16 bits per list element), regardless of the mask depth. A line list consists of a series of simple instructions, which are executed in sequence to reconstruct a line of the mask. Each 16-bit instruction consists of the sign bit (not used), a three-bit opcode, and twelve bits of data, as depicted below. \begin{verbatim} +--+--------+-------------------+ |16|15 13|12 1| +--+--------+-------------------+ | | opcode | data | +--+----------------------------+ \end{verbatim} The significance of the data depends upon the instruction. In order to reconstruct a mask line, the application executing these instructions is \required\ to keep track of two values, the current high value and the current position in the output line. The detailed operation of each instruction is given in Table~\ref{tab:PLIOinstr}. \begin{table}[h] \centering \caption{PLIO Instructions} \label{tab:PLIOinstr} \begin{tabular}{l l p{2.2in}} \hline \hline Instr. & Opcode & Meaning \\ \hline \noalign{\smallskip} \keyv{'ZN'} & \keyv{'00'} & Zero the next $N$ output pixels. \\ \keyv{'HN'} & \keyv{'04'} & Set the next $N$ output pixels to the current high value. \\ \keyv{'PN'} & \keyv{'05'} & Zero the next $N-1$ output pixels, and set Pixel~$N$ to the current high value. \\ \keyv{'SH'} & \keyv{'05'} & Set the high value (absolute rather than incremental), taking the high 15 bits from the next word in the instruction stream, and the low 12 bits from the current data value. \\ \keyv{'IH,DH'} & \keyv{'02,03'} & Increment (\keyv{'IH'}) or decrement (\keyv{'DH'}) the current high value by the data value. The current position is not affected. \\ \keyv{'IS,DS'} & \keyv{'06,07'} & Increment (\keyv{'IS'}) or decrement (\keyv{'DS'}) the current high value by the data value, and step, i.e., output one high value. \\ \noalign{\smallskip} \hline \end{tabular} \end{table} The high value \must\ be set to 1 at the beginning of a line, hence the \keyv{'IH,DH'} and \keyv{'IS,DS'} instructions are not normally needed for Boolean masks. %If the length of a line segment of constant value or the difference between two successive high values exceeds 4096 (12 bits), then multiple instructions are \required\ to describe the segment or intensity change. \subsubsection{H-Compress algorithm}\label{Hcompress}\index{H-compress algorithm} When \kwd{ZCMPTYPE}~=~\keyv{'HCOMPRESS\_1'}, the H-compress algorithm \shall\ be used for data (de)compression. The algorithm was described by \citet{white92}, and can be applied only to images with two dimensions. Briefly, the compression method is to apply, in order: \begin{enumerate} \setlength\itemsep{0.05in} \item a wavelet transform called the H-transform (a Haar transform generalized to two dimensions), followed by \item a quantization that discards noise in the image while retaining the signal on all scales, and finally \item a quadtree coding of the quantized coefficients. \end{enumerate} The H-transform is a two-dimensional generalization of the Haar transform. The H-transform is calculated for an image of size $2^N\times 2^N$ as follows. \begin{enumerate} \setlength\itemsep{0.05in} \item Divide the image up into blocks of $2\times2$ pixels. Call the four pixel values in a block $a_{00}$, $a_{10}$, $a_{01}$, and $a_{11}$. \item For each block compute four coefficients: \\ $ h_0 = (a_{11}+a_{10}+a_{01}+a_{00})/(\mathtt{SCALE} * \sigma) \\ h_x = (a_{11}+a_{10}-a_{01}-a_{00})/(\mathtt{SCALE} * \sigma) \\ h_y = (a_{11}-a_{10}+a_{01}-a_{00})/(\mathtt{SCALE} * \sigma) \\ h_c = (a_{11}-a_{10}-a_{01}+a_{00})/(\mathtt{SCALE} * \sigma) \\ $ where \texttt{SCALE} is an algorithm parameter defined below, and $\sigma$ characterizes the RMS noise in the uncompressed image. \item Construct a $2^{N-1}\times 2^{N-1}$ image from the $h_0$ values for each $2\times2$ block. Divide that image up into $2\times2$ blocks and repeat the above calculation. Repeat this process $N$ times, reducing the image in size by a factor of two at each step, until only one $h_0$ value remains. \end{enumerate} \noindent This calculation can be easily inverted to recover the original image from its transform. The transform is exactly reversible using integer arithmetic. Consequently, the program can be used for either lossy or lossless compression, with no special approach needed for the lossless case. Noise in the original image is still present in the H-transform, however. To compress noisy images, each coefficient can be divided by $\mathtt{SCALE} * \sigma$, where $\mathtt{SCALE} \sim1$ is chosen according to how much loss is acceptable. This reduces the noise in the transform to $0.5/\mathtt{SCALE}$, so that large portions of the transform are zero (or nearly zero) and the transform is highly compressible. There is one user-defined parameter associated with the H-Compress algorithm: a scale factor to the RMS noise in the image that determines the amount of compression that can be achieved. %There are two user-defined parameters associated with the H-Compress algorithm: an integer scale factor that determines the amount of compression, and a flag parameter that specifies whether the image should be smoothed during the decompression operation, to reduce residual artifacts in the image. It is not necessary to know what scale factor was used when compressing the image in order to decompress it, but it is still useful to record it. The keywords in Table~\ref{tab:HcomprKw} \should\ be recorded in the header for this purpose. \begin{table}[h] \setlength{\tabcolsep}{3pt} \centering \caption{Keyword parameters for H-compression} \label{tab:HcomprKw} \begin{tabular}{l l c p{1.6in}} \hline \hline & \multicolumn{2}{c}{Values} & \\ \cline{2-3} Keyword & Permitted & Default & Meaning \\ \hline \noalign{\smallskip} \kwd{ZNAME1} & \keyv{'SCALE'} & \keyv{'-'} & Scale factor \\ \kwd{ZVAL1} & \keyv{0.0} or larger & \keyv{0.0} & Scaling of the RMS noise; 0.0 yields lossless compression \\ %\kwd{ZNAME2} & \keyv{'SMOOTH'} & Smoothing flag \\ %\kwd{ZVAL2} & \keyv{0} (default) or \keyv{1} & Value=1 means smoothing is re\-commended \\ \noalign{\smallskip} \hline \end{tabular} \end{table} \begin{description} \setlength\itemsep{0.05in} \item \textit{Scale Factor} -- The floating-point scale parameter (whose value is stored in Keyword \kwd{ZVAL1}) determines the amount of compression; higher values result in higher compression, but with greater loss of information. \texttt{SCALE}~=~\keyv{0.0} is a special case that yields lossless compression, i.e. the decompressed image has exactly the same pixel values as the original image. $\mathtt{SCALE} > 0.0$ leads to lossy compression, where \texttt{SCALE} determines how much of the noise is discarded. %Setting scale to twice the sigma, the RMS noise in the image, usually results in compression by about a factor of 10 (i.e. the compressed image requires about 1.5 bits/pixel), while producing a decompressed image that is nearly indistinguishable from the original. %In fact, the RMS difference between the decompressed image and the original image will be only about 1/2 sigma. % %\item \textit{Smoothing Flag} -- At high compressions factors the decompressed image begins to appear blocky because of the way information is discarded. %This blockiness is greatly reduced if the image is smoothed slightly during decompression, but smoothing is only for aesthetic purposes. %When done properly, the smoothing will not affect any quantitative photometric or astrometric measurements derived from the compressed image. %The smoothing \shouldnot\ be applied when the image has been losslessly compressed. \end{description} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \ifiaufwgstyle \clearpage \fi \appendix % Appendix A \section{Syntax of keyword records} \label{s:FormSyn} {\em This appendix is not part of the \FITS\ Standard but is included for convenient reference.} \begin{tabbing} \null \hspace{0.35in} \= := \hspace{0.5in} \= means `is defined to be' \\ \>X $|$ Y \> means one of $X$ or $Y$ \\ \> \> (no ordering relation is implied) \\ \>[X] \> means that $X$ is {\em optional} \\ \>X... \> means $X$ is repeated one or more times \\ \>`B' \> means the ASCII character B \\ \>`A'--`Z' \> means one of the ASCII characters A \\ \> \> through Z in the ASCII collating \\ \> \> sequence, as shown in Appendix~\ref{s:Atxt} \\ \>\verb+\+0xnn \> means the ASCII character associated \\ \> \> with the hexadecimal code nn \\ \>\{...\} \> expresses a constraint or a comment \\ \> \> (it immediately follows the syntax rule) \\ \end{tabbing} The following statements define the formal syntax used in \FITS\ free-format\index{format, free} keyword records, as well as for long-string keywords spanning more than one keyword record). \\ FITS\_keyword := \\ \null \hspace{0.5in} single\_record\_keyword $|$ \\ \null \hspace{0.5in} long\_string\_keyword \\ single\_record\_keyword := \\ \null \hspace{0.5in} FITS\_keyword\_record \\ FITS\_keyword\_record := \\ \null \hspace{0.5in} FITS\_commentary\_keyword\_record $|$ \\ \null \hspace{0.5in} FITS\_value\_keyword\_record \\ FITS\_commentary\_keyword\_record := \\ \null \hspace{0.5in} COMMENT\_keyword [ascii\_text\_char...] $|$ \\ \null \hspace{0.5in} HISTORY\_keyword [ascii\_text\_char...] $|$ \\ \null \hspace{0.5in} BLANKFIELD\_keyword [ascii\_text\_char...] $|$ \\ \null \hspace{0.5in} keyword\_field anychar\_but\_equal \\ \null \hspace{1.0in} [ascii\_text\_char...] $|$ \\ \null \hspace{0.5in} keyword\_field `=' anychar\_but\_space \\ \null \hspace{1.0in} [ascii\_text\_char...] \\ \{Constraint: The total number of characters in a FITS\_commentary\_keyword\_record \must\ be exactly equal to 80.\} \\ FITS\_value\_keyword\_record := \\ \null \hspace{0.5in} keyword\_field value\_indicator [space...] [value] \\ \null \hspace{1.0in} [space...] [comment] \\ \{Constraint: The total number of characters in a FITS\_value\_keyword\_record \must\ be exactly equal to 80.\} \\ \{Comment: If the value field is not present, the value of the \FITS\ keyword is not defined.\} \\ long\_string\_keyword := \\ \null \hspace{0.5in} initial\_kwd\_record [continuation\_kwd\_record...] \\ \null \hspace{0.5in} last\_continuation\_record \\ \{Comment: the value of a long\_string\_keyword is reconstructed by concatenating the partial\_string\_values of the initial\_kwd\_record and of any continuation\_kwd\_records in the order they occur, and the character\_string\_value of the last\_continuation\_record.\} \\ initial\_kwd\_record := \\ \null \hspace{0.5in} keyword\_field value\_indicator [space...] \\ \null \hspace{0.5in} [partial\_string\_value] [space...] [comment] \\ \{Constraint: The total number of characters in an initial\_kwd\_record \must\ be exactly equal to 80.\} \\ continuation\_kwd\_record := \\ \null \hspace{0.5in} CONTINUE\_keyword [space...] \\ \null \hspace{0.5in} [partial\_string\_value] [space...] [comment] \\ \{Constraint: The total number of characters in a continuation\_kwd\_record \must\ be exactly equal to 80.\} \\ last\_continuation\_record := \\ \null \hspace{0.5in} CONTINUE\_keyword [space...] \\ \null \hspace{0.5in} [character\_string\_value] [space...] [comment] \\ \{Constraint: The total number of characters in a last\_continuation\_record \must\ be exactly equal to 80.\} \\ keyword\_field := \\ \null \hspace{0.5in} [keyword\_char...] [space...] \\ \{Constraint: The total number of characters in the keyword\_field \must\ be exactly equal to 8.\} \\ keyword\_char := \\ \null \hspace{0.5in} `A'--`Z' $|$ `0'--`9' $|$ `\_' $|$ `-' \\ COMMENT\_keyword := \\ \null \hspace{0.5in} `C' `O' `M' `M' `E' `N' `T' space \\ HISTORY\_keyword := \\ \null \hspace{0.5in} `H' `I' `S' `T' `O' `R' `Y' space \\ BLANKFIELD\_keyword := \\ \null \hspace{0.5in} space space space space space space space space \\ CONTINUE\_keyword := \\ \null \hspace{0.5in} `C' `O' `N' `T' `I' `N' `U' `E' \\ value\_indicator := \\ \null \hspace{0.5in} `=' space \\ space := \\ \null \hspace{0.5in} `\verb*+ +' \\ comment := \\ \null \hspace{0.5in} `/' [ascii\_text\_char...] \\ ascii\_text\_char := \\ \null \hspace{0.5in} space--`\verb+~+' \\ anychar\_but\_equal := \\ \null \hspace{0.5in} space--`$<$' $|$ `$>$'--`\verb+~+' \\ anychar\_but\_space := \\ \null \hspace{0.5in} `!'--`\verb+~+' \\ value := \\ \null \hspace{0.5in} character\_string\_value $|$ logical\_value $|$ \\ \null \hspace{0.5in} integer\_value $|$ floating\_value $|$ \\ \null \hspace{0.5in} complex\_integer\_value $|$ complex\_floating\_value \\ character\_string\_value := \\ \null \hspace{0.5in} begin\_quote [string\_text\_char...] end\_quote \\ \{Constraint: The begin\_quote and end\_quote are not part of the character-string value but only serve as delimiters. Leading spaces are significant; trailing spaces are not.\} \\ partial\_string\_value := \\ \null \hspace{0.5in} begin\_quote [string\_text\_char...] ampersand end\_quote \\ \{Constraint: The begin\_quote, end\_quote, and ampersand are not part of the character-string value but only serve respectively as delimiters or continuation indicator. %Leading spaces are significant; trailing spaces are not. \} \\ begin\_quote := \\ \null \hspace{0.5in} quote \\ end\_quote := \\ \null \hspace{0.5in} quote \\ \{Constraint: The ending quote \mustnot\ be immediately followed by a second quote.\} \\ quote := \\ \null \hspace{0.5in} \verb+\+0x27 \\ ampersand := \\ \null \hspace{0.5in} `\&' \\ string\_text\_char := \\ \null \hspace{0.5in} ascii\_text\_char \\ \{Constraint: A string\_text\_char is identical to an ascii\_text\_char except for the quote char; a quote char is represented by two successive quote chars.\} \\ logical\_value := \\ \null \hspace{0.5in} `T' $|$ `F' \\ integer\_value := \\ \null \hspace{0.5in} [sign] digit [digit...] \\ \{Comment: Such an integer value is interpreted as a signed decimal number. It \may\ contain leading zeros.\} \\ sign := \\ \null \hspace{0.5in} `-' $|$ `+' \\ digit := \\ \null \hspace{0.5in} `0'--`9' \\ floating\_value := \\ \null \hspace{0.5in} decimal\_number [exponent] decimal\_number := \\ \null \hspace{0.5in} [sign] [integer\_part] [`.' [fraction\_part]] \\ \{Constraint: At least one of the integer\_part and fraction\_part \must\ be present.\} \\ integer\_part := \\ \null \hspace{0.5in} digit $|$ [digit...] \\ fraction\_part := \\ \null \hspace{0.5in} digit $|$ [digit...] \\ exponent := \\ \null \hspace{0.5in} exponent\_letter [sign] digit [digit...] \\ exponent\_letter := \\ \null \hspace{0.5in} `E' $|$ `D' \\ complex\_integer\_value := \\ \null \hspace{0.5in} `(' [space...] real\_integer\_part [space...] `,' [space...] \\ \null \hspace{0.5in} imaginary\_integer\_part [space...] `)' \\ real\_integer\_part := \\ \null \hspace{0.5in} integer\_value \\ imaginary\_integer\_part := \\ \null \hspace{0.5in} integer\_value \\ complex\_floating\_value := \\ \null \hspace{0.5in} `(' [space...] real\_floating\_part [space...] `,' [space...] \\ \null \hspace{0.5in} imaginary\_floating\_part [space...] `)' \\ real\_floating\_part := \\ \null \hspace{0.5in} floating\_value \\ imaginary\_floating\_part := \\ \null \hspace{0.5in} floating\_value \\ %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% % Appendix B \section{Suggested time-scale specification} \label{s:tsys} % Added by RAS 2015-Apr-17 for v3.1: %\begin{redtext} {\em The content of this appendix has been superseded by Sect.~\ref{sect:timeReps} of the formal Standard, which derives from \cite{rots15}.} %\end{redtext} %\begin{enumerate} %\item Use of the keyword \kwd{TIMESYS} is suggested % as an implementation of the time\index{time} % scale specification. It sets the principal time system for time-related % keywords and data in the HDU (i.e., it does not preclude the addition of % keywords or data columns that provide information for transformations to % other time scales, such as sidereal times or barycenter corrections). % Each HDU \shall\ contain not more than one \kwd{TIMESYS} keyword. % Initially, officially allowed values are shown below. % For reference, see: % Explanatory Supplement to the Astronomical Almanac, P. K. Seidelmann, % ed., University Science Books, 1992, ISBN 0-935702-68-7, or % \begin{center} % \url{http://tycho.usno.navy.mil/systime.html} % \end{center} % % \begin{description} % \item[\bf \texttt{UTC}] -- Coordinated Universal Time; defined since 1972. % \item[\bf \texttt{UT}] -- Universal Time, equal to Greenwich Mean Time (GMT) % since 1925; the UTC equivalent before 1972; % see: Explanatory Supplement, p.\ 76. % \item[\bf \texttt{TAI}] -- International Atomic Time; `UTC without the % leap seconds'; 31 s ahead of UTC on 1997-07-01. % \item[\bf \texttt{AT}] -- International Atomic Time; deprecated synonym of TAI. % \item[\bf \texttt{ET}] -- Ephemeris Time, the predecessor of TT and TDB; valid until % 1984. % \item[\bf \texttt{TT}] -- Terrestrial Time, the IAU standard time scale since 1984; % continuous with ET and synchronous with (but 32.184 s % ahead of) TAI. % \item[\bf \texttt{TDT}] -- Terrestrial Dynamical Time; = TT. % \item[\bf \texttt{TDB}] -- Barycentric Dynamical Time. % \item[\bf \texttt{TCG}] -- Geocentric Coordinate Time; runs ahead of TT since % 1977-01-01 at a rate of approximately 22 ms/year. % \item[\bf \texttt{TCB}] -- Barycentric Coordinate Time; runs ahead of TDB since % 1977-01-01 at a rate of approximately 0.5 s/year. % \end{description} % % Use of Global Positioning Satellite (GPS) time (19 s behind TAI) is %deprecated. \index{deprecate} % %\item By default, times will be deemed to be as measured at the detector (or % at the observatory) for time scales defined on the geoid (i.e., TAI, UTC, and % TT). In the case of the coordinate times TCG, TCB, and TDB, the % observation is assumed to have been referred to the associated spatial % origin (namely the geocenter for TCG and the Solar System barycenter for % TCB and TDB) by allowing for light time. % These % defaults follow common practice; a future convention on time scale issues % in \FITS\ files \may\ allow other combinations % but \shall\ preserve this default % behavior. The rationale is that raw observational data are most likely % to be tagged by a clock that is synchronized with TAI, while a % transformation to coordinate times or TDB is usually accompanied by a % spatial transformation, as well. This implies that path length differences % have been corrected for. % Note that the same distant event recorded in a \FITS\ file in both TDB and UTC % will have times that differ by (typically) several minutes. % Also, note that when the location % is not unambiguous (such as in the case of an interferometer) precise % specification of the location is strongly encouraged in, for instance, % geocentric Cartesian coordinates. % %\item Note that \texttt{TT} is the IAU preferred standard. It can be considered % equivalent to \texttt{TDT} and \texttt{ET}, though \texttt{ET} \shouldnot\ be used % for data % taken after 1984. For reference, see: Explanatory Supplement, pp. 40-48. % %\item If the \kwd{TIMESYS} keyword is absent or has an unrecognized value, % the value \texttt{UTC} will be assumed for dates since 1972, % and \texttt{UT} for pre-1972 data. % %\item Examples. % The three legal representations of the date of October 14, 1996, %might be written as: % %Original format, means 1996 Oct 14: \\ %{\verb+DATE-OBS= '14/10/96'+} \\ %\\ %Explicit time scale specification: UTC. \\ %{\verb+TIMESYS = 'UTC '+} \\ %{\verb+DATE-OBS= '1996-10-14'+} \\ % \\ %Date of start of observation, assumed in UTC\\ %{\verb+DATE-OBS= '1996-10-14'+} \\ % \\ %Explicit time scale specification: TT. \\ %{\verb+TIMESYS = 'TT '+} \\ %{\verb+DATE-OBS= '1996-10-14T10:14:36.123'+} \\ % %\item The convention suggested in this appendix is part of the mission-specific % \FITS\ conventions adopted for, and used in, % the RXTE archive, building on % existing High Energy Astrophysics \FITS\ conventions. See % the \texttt{time\_tutorial.html} and \texttt{time.html} documents at % \url{http://heasarc.gsfc.nasa.gov/docs/xte/abc/}. % % The VLBA project has adopted a convention where the % keyword \kwd{TIMSYS}, rather than \kwd{TIMESYS}, is used, % currently allowing the values \texttt{UTC} and \texttt{IAT}. % See p.~38 and p.~39 of the \texttt{idi-format.ps} document at % \url{http://www.cv.nrao.edu/fits/documents/drafts}. %\end{enumerate} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \onecolumn % Appendix C \section{Summary of keywords} \label{s:summ} {\em This appendix is not part of the \FITS\ Standard, but is included for convenient reference.} All of the mandatory\index{keyword, mandatory} and reserved keywords\index{keyword, reserved} that are defined in the Standard, except for the reserved WCS keywords that are discussed separately in Sect.~\ref{s:WCS}, are listed in Tables~\ref{ta:mandatorykeys}, \ref{ta:reservedkeys}, and \ref{ta:generalkeys}. % New: added by RAS 2015-Apr-17: An alphabetical list of these keywords and their definitions is available online: \url{http://heasarc.gsfc.nasa.gov/docs/fcg/standard_dict.html}. \begin{table}[hbp] \begin{center} \caption[Mandatory \FITS\ keywords.] {Mandatory \FITS\ keywords for the structures described in this document.} \label{ta:mandatorykeys} \begin{tabular}{llllllll} \hline \hline \multicolumn{1}{c}{Primary} & \multicolumn{1}{c}{Conforming} & \multicolumn{1}{c}{Image} & \multicolumn{1}{c}{ASCII-table} & \multicolumn{1}{c}{Binary-table} & \multicolumn{1}{c}{Compressed} & \multicolumn{1}{c}{Compressed} & \multicolumn{1}{c}{Random-groups} \\ \multicolumn{1}{c}{HDU} & \multicolumn{1}{c}{extension} & \multicolumn{1}{c}{extension} & \multicolumn{1}{c}{extension} & \multicolumn{1}{c}{extension} & \multicolumn{1}{c}{images$^{6}$}\index{compressed images} & \multicolumn{1}{c}{tables$^{6}$}\index{compressed binary tables} & \multicolumn{1}{c}{records} \\ \hline \noalign{\smallskip} \kwd{SIMPLE} & \kwd{XTENSION} & \kwd{XTENSION}$^{1}$ & \kwd{XTENSION}$^{2}$ & \kwd{XTENSION}$^{3}$ & \kwd{ZIMAGE}\verb+ =T+ & \kwd{ZTABLE}\verb+ =T+ & \kwd{SIMPLE} \\ \kwd{BITPIX} & \kwd{BITPIX} & \kwd{BITPIX} & \kwd{BITPIX}\verb+ = 8+ & \kwd{BITPIX}\verb+ = 8+ & \kwd{ZBITPIX} & \kwd{ZNAXIS1} & \kwd{BITPIX} \\ \kwd{NAXIS} & \kwd{NAXIS} & \kwd{NAXIS} & \kwd{NAXIS}\verb+ = 2+ & \kwd{NAXIS}\verb+ = 2+ & \kwd{ZNAXIS} & \kwd{ZNAXIS2} & \kwd{NAXIS} \\ \indxkw{NAXIS}{n}$^{4}$ & \indxkw{NAXIS}{n}$^{4}$ &\indxkw{NAXIS}{n}$^{4}$ & \kwd{NAXIS1} & \kwd{NAXIS1} & \indxkw{ZNAXIS}{n} & \kwd{ZPCOUNT} & \kwd{NAXIS1}\verb+ = 0+ \\ \kwd{END } & \kwd{PCOUNT} & \kwd{PCOUNT}\verb+ = 0+ & \kwd{NAXIS2} & \kwd{NAXIS2} & \kwd{ZCMPTYPE} & \indxkw{ZFORM}{n} & \indxkw{NAXIS}{n}$^{4}$ \\ & \kwd{GCOUNT} & \kwd{GCOUNT}\verb+ = 1+ & \kwd{PCOUNT}\verb+ = 0+ & \kwd{PCOUNT} & & \indxkw{ZCTYP}{n} & \kwd{GROUPS}\verb+ = T+ \\ & \kwd{END} & \kwd{END} & \kwd{GCOUNT}\verb+ = 1+ & \kwd{GCOUNT}\verb+ = 1+ & & \kwd{ZTILELEN} & \kwd{PCOUNT} \\ & & & \kwd{TFIELDS} & \kwd{TFIELDS} & & & \kwd{GCOUNT} \\ & & & \indxkw{TFORM}{n}$^{5}$ & \indxkw{TFORM}{n}$^{5}$ & & & \kwd{END} \\ & & & \indxkw{TBCOL}{n}$^{5}$ & \kwd{END} & & & \\ & & & \kwd{END} & & & & \\ \noalign{\smallskip} \hline \end{tabular} \end{center} $^{(1)}$\kwd{XTENSION}\verb*+= 'IMAGE '+ for the image extension. $^{(2)}$\kwd{XTENSION}\verb*+= 'TABLE '+ for the ASCII-table extension. $^{(3)}$\kwd{XTENSION}\verb*+= 'BINTABLE'+ for the binary-table extension\index{binary table}. $^{(4)}$Runs from 1 through the value of \kwd{NAXIS}. $^{(5)}$Runs from 1 through the value of \kwd{TFIELDS}. %begin{redtext} $^{(6)}$Required in addition to the mandatory keywords for binary tables. %end{redtext} \end{table} %\normalsize \begin{table}[hbp] \begin{center} \caption[Reserved \FITS\ keywords.] {Reserved \FITS\ keywords for the structures described in this document.} \label{ta:reservedkeys} \begin{tabular}{llllllll} \hline \hline \multicolumn{2}{c}{All$^{1}$} & \multicolumn{1}{c}{Array$^{2}$} & \multicolumn{1}{c}{ASCII-table} & \multicolumn{1}{c}{Binary-table} & \multicolumn{1}{c}{Compressed} & \multicolumn{1}{c}{Compressed} & \multicolumn{1}{c}{Random-groups} \\ \multicolumn{2}{c}{HDUs} & \multicolumn{1}{c}{HDUs} & \multicolumn{1}{c}{extension} & \multicolumn{1}{c}{extension} & \multicolumn{1}{c}{images} & \multicolumn{1}{c}{tables} & \multicolumn{1}{c}{records} \\ \hline \noalign{\smallskip} \kwd{DATE} & \kwd{EXTNAME} & \kwd{BSCALE} & \indxkw{TSCAL}{n} & \indxkw{TSCAL}{n} & \indxkw{ZTILE}{n} & \kwd{FZTILELN} & \indxkw{PTYPE}{n} \\ \kwd{DATE-OBS} & \kwd{EXTVER} & \kwd{BZERO} & \indxkw{TZERO}{n} & \indxkw{TZERO}{n} & \indxkw{ZNAME}{i} & \kwd{FZALGOR} & \indxkw{PSCAL}{n} \\ \kwd{ORIGIN} & \kwd{EXTLEVEL} & \kwd{BUNIT} & \indxkw{TNULL}{n} & \indxkw{TNULL}{n} & \indxkw{ZVAL}{i} & \indxkw{FZALG}{n} & \indxkw{PZERO}{n} \\ \kwd{AUTHOR} & \kwd{EQUINOX} & \kwd{BLANK} & \indxkw{TTYPE}{n} & \indxkw{TTYPE}{n} & \kwd{ZMASKCMP} & & \\ \kwd{REFERENC} & \kwd{EPOCH}$^{3}$ & \kwd{DATAMAX} & \indxkw{TUNIT}{n} & \indxkw{TUNIT}{n} & \kwd{ZQUANTIZ} & & \\ \kwd{COMMENT} & \kwd{BLOCKED}$^{3}$ & \kwd{DATAMIN} & \indxkw{TDISP}{n} & \indxkw{TDISP}{n} & \kwd{ZDITHER0} & & \\ \kwd{HISTORY} & \kwd{EXTEND}$^{4}$ & & \indxkw{TDMAX}{n} & \indxkw{TDIM}{n} & \kwd{ZSIMPLE} & \kwd{ZTHEAP} & \\ \verb*+ + & \kwd{TELESCOP} & & \indxkw{TDMIN}{n} & \kwd{THEAP} & \kwd{ZEXTEND} & & \\ \kwd{OBJECT} & \kwd{INSTRUME} & & \indxkw{TLMAX}{n} & \indxkw{TDMAX}{n} & \kwd{ZBLOCKED} & & \\ \kwd{OBSERVER} & & & \indxkw{TLMIN}{n} & \indxkw{TDMIN}{n} & \kwd{ZTENSION} & & \\ \kwd{CONTINUE} & & & & \indxkw{TLMAX}{n} & \kwd{ZPCOUNT} & & \\ \kwd{INHERIT} $^{5}$ & & & & \indxkw{TLMIN}{n} & \kwd{ZGCOUNT} & & \\ \kwd{CHECKSUM} & & & & & \kwd{ZHECKSUM} & \kwd{ZHECKSUM} & \\ \kwd{DATASUM} & & & & & \kwd{ZDATASUM} & \kwd{ZDATASUM} & \\ \noalign{\smallskip} \hline \end{tabular} \end{center} $^{(1)}$These keywords are further categorized in Table~C.3. $^{(2)}$Primary HDU, \IMAGE\ extension, user-defined HDUs with same array structure. $^{(3)}$Deprecated. $^{(4)}$Only permitted in the primary HDU. $^{(5)}$Only permitted in extension HDUs, immediately following the mandatory keywords. \end{table} \begin{table}[hbp] \begin{center} \caption[General reserved \FITS\ keywords.] {General reserved \FITS\ keywords described in this document.} \label{ta:generalkeys} \begin{tabular}{llll} \hline \hline \multicolumn{1}{c}{Production} & \multicolumn{1}{c}{Bibliographic} & \multicolumn{1}{c}{Commentary} & \multicolumn{1}{c}{Observation} \\ \hline \noalign{\smallskip} \kwd{DATE} & \kwd{AUTHOR} & \kwd{COMMENT} & \kwd{DATE-OBS} \\ \kwd{ORIGIN} & \kwd{REFERENC} & \kwd{HISTORY} & \kwd{TELESCOP} \\ \kwd{BLOCKED}$^{1}$& &\verb*+ + & \kwd{INSTRUME} \\ & & & \kwd{OBSERVER} \\ & & & \kwd{OBJECT} \\ & & & \kwd{EQUINOX} \\ & & & \kwd{EPOCH}$^{1}$ \\ \noalign{\smallskip} \hline \end{tabular} \end{center} $^{(1)}$Deprecated. \end{table} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% % Appendix D \ifiaufwgstyle \clearpage \fi \section{ASCII text} \label{s:Atxt} {\em This appendix is not part of the \FITS\ Standard}; the material in it is based on the ANSI\index{ANSI} standard for ASCII \citep{ansi77} and is included here for informational purposes.) In Table~\ref{ta:ascii}, the first column is the decimal\index{ASCII character} and the second column the hexadecimal value for the character in the third column. The characters hexadecimal 20 to 7E (decimal 32 to 126) constitute the subset referred to in this document as the restricted set of ASCII-text characters.\index{ASCII text} \begin{table} \begin{center} \caption[ASCII character set]{ASCII character set.} \label{ta:ascii} \begin{tabular}{|lll||lll|lll|lll|} \hline \hline \multicolumn{3}{|c||}{ASCII control} & \multicolumn{9}{|c|}{ASCII text} \\ \hline \multicolumn{1}{|c}{dec} & \multicolumn{1}{c}{hex} & \multicolumn{1}{c||}{char} & \multicolumn{1}{|c}{dec} & \multicolumn{1}{c}{hex} & \multicolumn{1}{c}{char} & \multicolumn{1}{|c}{dec} & \multicolumn{1}{c}{hex} & \multicolumn{1}{c}{char} & \multicolumn{1}{|c}{dec} & \multicolumn{1}{c}{hex} & \multicolumn{1}{c|}{char} \\ \hline \noalign{\smallskip} 0 & 00 & NUL & 32 & 20 & SP & 64 & 40 & \verb+@+ & 96 & 60 & \verb+`+ \\ 1 & 01 & SOH & 33 & 21 & \verb+!+ & 65 & 41 & A & 97 & 61 & a \\ 2 & 02 & STX & 34 & 22 & \verb+"+ & 66 & 42 & B & 98 & 62 & b \\ 3 & 03 & ETX & 35 & 23 & \verb+#+ & 67 & 43 & C & 99 & 63 & c \\ 4 & 04 & EOT & 36 & 24 & \verb+$+ & 68 & 44 & D &100 & 64 & d \\ 5 & 05 & ENQ & 37 & 25 & \verb+%+ & 69 & 45 & E &101 & 65 & e \\ 6 & 06 & ACK & 38 & 26 & \verb+&+ & 70 & 46 & F &102 & 66 & f \\ 7 & 07 & BEL & 39 & 27 & \verb+'+ & 71 & 47 & G &103 & 67 & g \\ 8 & 08 & BS & 40 & 28 & \verb+(+ & 72 & 48 & H &104 & 68 & h \\ 9 & 09 & HT & 41 & 29 & \verb+)+ & 73 & 49 & I &105 & 69 & i \\ 10 & 0A & LF & 42 & 2A & \verb+*+ & 74 & 4A & J &106 & 6A & j \\ 11 & 0B & VT & 43 & 2B & \verb-+- & 75 & 4B & K &107 & 6B & k \\ 12 & 0C & FF & 44 & 2C & \verb+, + & 76 & 4C & L &108 & 6C & l \\ 13 & 0D & CR & 45 & 2D & \verb+-+ & 77 & 4D & M &109 & 6D & m \\ 14 & 0E & SO & 46 & 2E & \verb+.+ & 78 & 4E & N &110 & 6E & n \\ 15 & 0F & SI & 47 & 2F & \verb+/+ & 79 & 4F & O &111 & 6F & o \\ 16 & 10 & DLE & 48 & 30 & 0 & 80 & 50 & P &112 & 70 & p \\ 17 & 11 & DC1 & 49 & 31 & 1 & 81 & 51 & Q &113 & 71 & q \\ 18 & 12 & DC2 & 50 & 32 & 2 & 82 & 52 & R &114 & 72 & r \\ 19 & 13 & DC3 & 51 & 33 & 3 & 83 & 53 & S &115 & 73 & s \\ 20 & 14 & DC4 & 52 & 34 & 4 & 84 & 54 & T &116 & 74 & t \\ 21 & 15 & NAK & 53 & 35 & 5 & 85 & 55 & U &117 & 75 & u \\ 22 & 16 & SYN & 54 & 36 & 6 & 86 & 56 & V &118 & 76 & v \\ 23 & 17 & ETB & 55 & 37 & 7 & 87 & 57 & W &119 & 77 & w \\ 24 & 18 & CAN & 56 & 38 & 8 & 88 & 58 & X &120 & 78 & x \\ 25 & 19 & EM & 57 & 39 & 9 & 89 & 59 & Y &121 & 79 & y \\ 26 & 1A & SUB & 58 & 3A & \verb+:+ & 90 & 5A & Z &122 & 7A & z \\ 27 & 1B & ESC & 59 & 3B & \verb+;+ & 91 & 5B & \verb+[+ &123 & 7B & \verb+{+ \\ 28 & 1C & FS & 60 & 3C & \verb+<+ & 92 & 5C & \verb+\+ &124 & 7C & \verb+|+ \\ 29 & 1D & GS & 61 & 3D & \verb+=+ & 93 & 5D & \verb+]+ &125 & 7D & \verb+}+ \\ 30 & 1E & RS & 62 & 3E & \verb+>+ & 94 & 5E & \verb+^+ &126 & 7E & \verb+~+ \\ 31 & 1F & US & 63 & 3F & \verb+?+ & 95 & 5F & \verb+_+ &127 & 7F & DEL$^{1}$ \\ \noalign{\smallskip} \hline \end{tabular} \end{center} $^1$ Not ASCII Text \label{t:ascii} \end{table} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% % Appendix E \section{IEEE floating-point formats} \label{s:IEEE754} {\em The\index{IEEE special values} material in this appendix is not part of this Standard}; it is adapted from the IEEE-754 floating-point\index{floating-point} standard \citep{ieee85} and provided for informational purposes. It is not intended to be a comprehensive description of the IEEE formats; readers should refer to the IEEE standard.) \FITS\ recognizes all IEEE basic formats, including the special values. \subsection{Basic formats} Numbers in the single and double formats are composed of the following three fields: \begin{enumerate} \item a one-bit sign $s$, \item a biased exponent $e=E+\mbox{\textit{bias}}$, and \item a fraction $f= \bullet b_{1} b_{2} \cdots b_{p-1}$. \end{enumerate} The range of the unbiased exponent $E$ \shall\ include every integer between two values $E_{min}$ and $E_{max}$, inclusive, and also two other reserved values $E_{min}-1$ to encode $\pm 0$ and denormalized numbers, and $E_{max}$+1 to encode $\pm\infty$ and NaNs.\index{NaN, IEEE} The foregoing parameters are given in Table~\ref{t:FormParm}. Each nonzero numerical value has just one encoding. The fields are interpreted as follows. \begin{table*} \centering \caption[Summary of format parameters.]{Summary of format parameters.} \begin{tabular}{lrrrr} \hline \hline &\multicolumn{4}{c}{Format} \\ %\cline{2-5} \multicolumn{1}{c}{Parameter} & & \multicolumn{1}{c}{Single} & & \multicolumn{1}{c}{Double} \\ & Single & extended & Double & extended \\ \hline \noalign{\smallskip} $p$ & 24 & $\geq 32$ & 53 & $\geq 64$ \\ $E_{max}$ & $+127$ & $\geq +1023$ & $+1023$ & $\geq +16383$ \\ $E_{min}$ & $-126$ & $\leq -1022$ & $-1022$ & $\leq -16382$ \\ Exponent \textit{bias} & $+127$ & unspecified & $+1023$ & unspecified \\ Exponent width in bits & 8 & $\geq 11$ & 11 & $\geq 15$ \\ Format width in bits & 32 & $\geq 43$ & 64 & $\geq 79$ \\ \noalign{\smallskip} \hline \end{tabular} \label{t:FormParm} \end{table*} \subsubsection{Single} A 32-bit single-format number $X$ is divided as shown in Fig.~\ref{f:singl}. The value $v$ of $X$ is inferred from its constituent fields. \begin{enumerate} \item If $e = 255$ and $f \neq 0$, then $v$ is NaN regardless of $s$. \item If $e = 255$ and $f = 0$, then $v = (-1)^{s} \infty$. \item If $0 < e < 255$, then $v = (-1)^{s} 2^{e-127} (1 \bullet f)$. \item If $e = 0$ and $f \neq 0$, then $v = (-1)^{s} 2^{e-126} (0 \bullet f)$ (denormalized numbers). \item If $e = 0$ and $f = 0$, then $v = (-1)^{s}0$ (zero). \end{enumerate} \begin{figure*} \setlength{\unitlength}{.75cm} \caption[Single Format.]{Single Format. \texttt{msb} means \textit{most-significant bit}, \texttt{lsb} means \textit{least-significant bit}} \begin{picture}(6,3) \put(1,2){\makebox(1.0,1.0){1}\makebox(3.4,1.0){8}\makebox(5.2,1.0){23}\makebox(3,1.0){....widths}} \put(1,1){\framebox(1.0,1.0){{\em s}}\framebox(3.4,1.0){{\em e}}\framebox(5.2,1.0){{\em f}}} \put(1,0){\makebox(1.0,1.0){ }\makebox(1.0,1.0){msb}\makebox(1.4,1.0){ }\makebox(1.0,1.0){lsb} \makebox(1.0,1.0){msb}\makebox(3.2,1.0){ }\makebox(1.0,1.0){lsb} \makebox(2.6,1.0){....order}} \end{picture} \label{f:singl} \end{figure*} \subsubsection{Double} A 64-bit double-format number $X$ is divided as shown in Fig.~\ref{f:doubl}. The value $v$ of $X$ is inferred from its constituent fields. \begin{enumerate} \item If $e = 2047$ and $f \neq 0$, then $v$ is NaN regardless of $s$. \item If $e = 2047$ and $f = 0$, then $v = (-1)^{s} \infty$. \item If $0 < e < 2047$, then $v = (-1)^{s} 2^{e-1023} (1 \bullet f)$. \item If $e = 0$ and $f \neq 0$, then $v = (-1)^{s} 2^{e-1022} (0 \bullet f)$ (denormalized numbers). \item If $e = 0$ and $f = 0$, then $v = (-1)^{s}0$ (zero). \end{enumerate} \begin{figure*} \caption[Double Format.]{Double Format. \texttt{msb} means \textit{most-significant bit}, \texttt{lsb} means \textit{least-significant bit}} \setlength{\unitlength}{.75cm} \begin{picture}(6,3) \put(1,2){\makebox(1.0,1.0){1}\makebox(3.4,1.0){11}\makebox(5.2,1.0){52}\makebox(3,1.0){....widths}} \put(1,1){\framebox(1.0,1.0){{\em s}}\framebox(3.4,1.0){{\em e}}\framebox(5.2,1.0){{\em f}}} \put(1,0){\makebox(1.0,1.0){ }\makebox(1.0,1.0){msb}\makebox(1.4,1.0){ }\makebox(1.0,1.0){lsb} \makebox(1.0,1.0){msb}\makebox(3.2,1.0){ }\makebox(1.0,1.0){lsb} \makebox(2.6,1.0){....order}} \end{picture} \label{f:doubl} \end{figure*} \subsection{Byte patterns} Table~\ref{t:ieee} shows the types of IEEE floating-point value, whether regular or special, corresponding to all double- and single-precision hexadecimal byte\index{NaN, IEEE} patterns. \begin{table} \begin{center} \caption[IEEE floating-point formats.]{IEEE floating-point formats.} \label{t:ieee} \begin{tabular}{lcc} \hline \hline \multicolumn{1}{c}{IEEE value} & Double precision & Single precision \\ \hline \noalign{\smallskip} $+0$ & \texttt{0000000000000000} & \texttt{00000000} \\ denormalized & \texttt{0000000000000001} & \texttt{00000001} \\ & to & to \\ & \texttt{000FFFFFFFFFFFFF} & \texttt{007FFFFF} \\ positive underflow & \texttt{0010000000000000} & \texttt{00800000} \\ positive numbers & \texttt{0010000000000001} & \texttt{00800001} \\ & to & to \\ & \texttt{7FEFFFFFFFFFFFFE} & \texttt{7F7FFFFE} \\ positive overflow & \texttt{7FEFFFFFFFFFFFFF} & \texttt{7F7FFFFF} \\ $+\infty$ & \texttt{7FF0000000000000} & \texttt{7F800000} \\ NaN$^{1}$ & \texttt{7FF0000000000001} & \texttt{7F800001} \\ & to & to \\ & \texttt{7FFFFFFFFFFFFFFF} & \texttt{7FFFFFFF} \\ $-0$ & \texttt{8000000000000000} & \texttt{80000000} \\ negative & \texttt{8000000000000001} & \texttt{80000001} \\ denormalized & to & to \\ & \texttt{800FFFFFFFFFFFFF} & \texttt{807FFFFF} \\ negative underflow & \texttt{8010000000000000} & \texttt{80800000} \\ negative numbers & \texttt{8010000000000001} & \texttt{80800001} \\ & to & to \\ & \texttt{FFEFFFFFFFFFFFFE} & \texttt{FF7FFFFE} \\ negative overflow & \texttt{FFEFFFFFFFFFFFFF} & \texttt{FF7FFFFF} \\ $-\infty$ & \texttt{FFF0000000000000} & \texttt{FF800000} \\ NaN$^{1}$ & \texttt{FFF0000000000001} & \texttt{FF800001} \\ & to & to \\ & \texttt{FFFFFFFFFFFFFFFF} & \texttt{FFFFFFFF} \\ \noalign{\smallskip} \hline \end{tabular} \end{center} %\tablefoot{ } $^1$ Certain values \may\ be designated as {\em quiet} NaN (no diagnostic when used) or {\em signaling} (produces diagnostic when used) by particular implementations. \end{table} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \ifonecol \else \twocolumn \fi % Appendix F \section{Reserved extension type names} \label{s:resname} {\em This appendix is not part of the \FITS\ Standard, but\index{extension} is included for informational purposes}. It describes the extension type names registered as of the date this Standard was issued.) A current list is available from the \FITS\ Support Office website at \url{http://fits.gsfc.nasa.gov}. \subsection{Standard extensions} These three extension types have been approved by the IAUFWG \index{IAUFWG} and are defined in Sect.~\ref{s:exts} of this Standard document as well as in the indicated {\em Astronomy and Astrophysics} journal articles. \begin{itemize} \item \verb*+'IMAGE '+ -- This extension type provides a means of storing a multi-dimensional array\index{array, multi-dimensional} similar to that of the \FITS\ primary header and data unit. Approved as a standard extension in 1994 \citep{ponz94}. \item \verb*+'TABLE '+ -- This ASCII-table extension type contains rows and columns of data entries expressed as ASCII characters. Approved as a standard extension in 1988 \citep{harten88}. \item \verb*+'BINTABLE'+ -- This binary-table extension type provides a more-flexible and efficient means of storing data structures than is provided by the \TABLE\ extension type. The table rows can contain a mixture of numerical, logical, and character data entries. In addition, each entry is allowed to be a single-dimensioned array. Numeric data are kept in binary formats. Approved as a standard extension in 1994 \citep{cotton95}. \end{itemize} \subsection{Conforming extensions} These conventions meet the requirements for a conforming extension as defined in in Sect.~\ref{s:genext} of this Standard, however they have not been formally approved or endorsed by the IAUFWG. \begin{itemize} \item \verb*+'IUEIMAGE'+ -- This name was given to the prototype of the \IMAGE\ extension type and was primarily used in the IUE project data archive from approximately 1992 to 1994. Except for the name, the format is identical to the \IMAGE\ extension. \item \verb*+'A3DTABLE'+ -- This name was given to the prototype of the \BINTABLE\ extension type and was primarily used in the AIPS data processing system developed at NRAO from about 1987 until it was replaced by \BINTABLE\ in the early 1990s. The format is defined in the `Going AIPS' manual \citep{cotton90}, Chapter 14. It is very similar to the \BINTABLE\ type except that it does not support the variable-length\index{variable-length array}-array\index{array, variable-length} convention. \item \verb*+'FOREIGN '+ -- This extension type is used to put a \FITS\ wrapper about an arbitrary file, allowing a file or tree of files to be wrapped up in \FITS\ and later restored to disk. A full description of this extension type is given in the Registry of \FITS\ conventions on the \FITS\ Support Office website. \item \verb*+'DUMP '+ -- This extension type can be used to store a stream of binary-data values. The only known use of this extension type is to record telemetry header packets for data from the Hinode mission. The more-general \texttt{FOREIGN} extension type could also be used to store this type of data. \end{itemize} \subsection{Other suggested extension names} There have been occasional suggestions for other extension names that might be used for other specific purposes. These include a \texttt{COMPRESS} extension for storing compressed images, a \FITS\ extension for hierarchically embedding entire \FITS\ files within other \FITS\ files, and a \texttt{FILEMARK} extension for representing the equivalent of an end-of-file mark on magnetic-tape media. None of these extension types have been implemented or used in practice, therefore these names are not reserved. These extension names (or any other extension name not specifically mentioned in the previous sections of this appendix) \shouldnot\ be used in any \FITS\ file without first registering the name with the IAU \FITS\ Working Group. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \section{MIME types} \label{s:MIMETypes} {\em This appendix is not part of the \FITS\ Standard, but is included for informational purposes}. RFC 4047 \citep{rfc4047} describes the registration of the Multipurpose Internet Mail Extensions (MIME) sub-types `\texttt{application/fits}' and `\texttt{image/fits}' to be used by the international astronomical community for the interchange of \FITS\ files. The MIME type serves as a electronic tag or label that is transmitted along with the \FITS\ file that tells the receiving application what type of file is being transmitted. The remainder of this appendix has been extracted verbatim from the RFC 4047 document. The general nature of the full \FITS\ Standard requires the use of the media type `\texttt{application/fits}'. Nevertheless, the principal intent for a great many \FITS\ files is to convey a single data array in the primary HDU, and such arrays are very often two-dimensional images. Several common image viewing applications already display single-HDU \FITS\ files, and the prototypes for virtual-observatory projects specify that data provided by web services be conveyed by the data array in the primary HDU. These uses justify the registration of a second media type, namely `\texttt{image/fits}', for files that use the subset of the Standard described by the original \FITS\ Standard paper. The MIME type `\texttt{image/fits}' \may\ be used to describe \FITS\ primary HDUs that have other than two dimensions, however it is expected that most files described as `\texttt{image/fits}' will have two-dimensional (\kwd{NAXIS}~=~\keyv{2}) primary HDUs. \subsection{MIME type `\texttt{application/fits}'} A \FITS\ file described with the media type `\texttt{application/fits}' \should\ conform to the published standards for \FITS\ files as determined by convention and agreement within the international \FITS\ community. No other constraints are placed on the content of a file described as `\texttt{application/fits}'. A \FITS\ file described with the media type `\texttt{application/fits}' \may\ have an arbitrary number of conforming extension HDUs that follow its mandatory primary header and data unit. The extension HDUs \may\ be one of the standard types (\IMAGE, \TABLE, and \BINTABLE) or any other type that satisfies the `Requirements for conforming extensions' (Sect.~\ref{s:genext}). The primary HDU or any \IMAGE\ extension \may\ contain zero to 999 dimensions with zero-or-more pixels along each dimension. The primary HDU \may\ use the random-groups convention, in which the dimension of the first axis is zero and the keywords \kwd{GROUPS}. \kwd{PCOUNT} and \kwd{GCOUNT} appear in the header. \kwd{NAXIS1}~=~\keyv{0} and \kwd{GROUPS}~=~\keyv{T} is the signature of random groups; see Sect.~\ref{s:Rgrp}. \subsubsection{Recommendations for application writers} An application intended to handle `\texttt{application/fits}' \should\ be able to provide a user with a manifest of all of the HDUs that are present in the file and with all of the keyword/value pairs from each of the HDUs. An application intended to handle `\texttt{application/fits}' \should\ be prepared to encounter extension HDUs that contain either ASCII or binary tables, and to provide a user with access to their elements. An application that can modify \FITS\ files or retrieve \FITS\ files from an external service \should\ be capable of writing such files to a local storage medium. Complete interpretation of the meaning and intended use of the data in each of the HDUs typically requires the use of heuristics that attempt to ascertain which local conventions were used by the author of the \FITS\ file. As examples, files with media type `\texttt{application/fits}' might contain any of the following contents. \begin{itemize} \item An empty primary HDU (containing zero data elements) followed by a table HDU that contains a catalog of celestial objects. \item An empty primary HDU followed by a \TABLE\ HDU that encodes a series of time-tagged photon events from an exposure using an X-ray detector. \item An empty primary HDU followed by a series of \IMAGE\ HDUs containing data from an exposure taken by a mosaic of CCD detectors. \item An empty primary HDU followed by a series of \TABLE\ HDUs that contain a snapshot of the state of a relational database. \item A primary HDU containing a single image along with keyword/value pairs of metadata. \item A primary HDU with \kwd{NAXIS1}~=~\keyv{0} and \kwd{GROUPS}~=~\keyv{T} followed by random-groups data records of complex fringe visibilities. \end{itemize} \subsection{MIME type `\texttt{image/fits}'} A \FITS\ file described with the media type `\texttt{image/fits}' \should\ have a primary HDU with positive integer values for the \kwd{NAXIS} and \indxkw{NAXIS}{n} keywords, and hence \should\ contain at least one pixel. Files with four or more non-degenerate axes (\indxkw{NAXIS}{n} $>$ 1) \should\ be described as `\texttt{application/fits}', not as `\texttt{image/fits}'. (In rare cases it may be appropriate to describe a NULL image -- a dataless container for \FITS\ keywords, with \kwd{NAXIS}~=~\keyv{0} or \indxkw{NAXIS}{n}~=~\keyv{0} -- or an image with four or more non-degenerate axes as `\texttt{image/fits}' but this usage is discouraged because such files may confuse simple image-viewer applications.) \FITS\ files declared as `\texttt{image/fits}' \may\ also have one or more conforming extension HDUs following their primary HDUs. These extension HDUs \may\ contain standard, non-linear, world-coordinate system (WCS) information in the form of tables or images. The extension HDUs \may\ also contain other, non-standard metadata pertaining to the image in the primary HDU in the forms of keywords and tables. A \FITS\ file described with the media type `\texttt{image/fits}' \should\ be principally intended to communicate the single data array in the primary HDU. This means that `\texttt{image/fits}' \shouldnot\ be applied to \FITS\ files containing multi-exposure-frame mosaic images. Also, random-groups files \must\ be described as `\texttt{application/fits}' and not as `\texttt{image/fits}'. A \FITS\ file described with the media type `\texttt{image/fits}' is also valid as a file of media type `\texttt{application/fits}'. The choice of classification depends on the context and intended usage. \subsubsection{Recommendations for application writers} An application that is intended to handle `\texttt{image/fits}' \should\ be able to provide a user with a manifest of all of the HDUs that are present in the file and with all of the keyword/value pairs from each of the HDUs. An application writer \may\ choose to ignore HDUs beyond the primary HDU, but even in this case the application \should\ be able to present the user with the keyword/value pairs from the primary HDU. Note that an application intended to render `\texttt{image/fits}' for viewing by a user has significantly more responsibility than an application intended to handle, e.g., \texttt{'image/tiff'} or \texttt{'image/gif'}. \FITS\ data arrays contain elements that typically represent the values of a physical quantity at some coordinate location. Consequently they need not contain any pixel rendering information in the form of transfer functions, and there is no mechanism for color look-up tables. An application \should\ provide this functionality, either statically using a more- or less-sophisticated algorithm, or interactively allowing a user various degrees of choice. Furthermore, the elements in a \FITS\ data array \may\ be integers or floating-point numbers. The dynamic range of the data-array values may exceed that of the display medium and the eye, and their distribution may be highly non-uniform. Logarithmic, square-root, and quadratic transfer functions along with histogram-equalization techniques have proved helpful for rendering \FITS\ data arrays. Some elements of the array may have values that indicate that their data are undefined\index{value, undefined} or invalid; these \should\ be rendered distinctly. Via WCS Paper I \citep{greisen02} the Standard permits \indxkw{CTYPE}{n}~=~\keyv{'COMPLEX'} to assert that a data array contains complex numbers (future revisions might admit other elements such as quaternions or general tensors). Three-dimensional data arrays (\kwd{NAXIS}~=~\keyv{3} with \kwd{NAXIS1}, \kwd{NAXIS2}, and \kwd{NAXIS3} all greater than 1) are of special interest. Applications intended to handle `\texttt{image/fits}' \may\ default to displaying the first two-dimensional plane of such an image cube, or they \may\ default to presenting such an image in a fashion akin to that used for an animated GIF, or they \may\ present the data cube as a mosaic of `thumbnail' images. The time-lapse movie-looping display technique can be effective in many instances, and application writers \should\ consider offering it for all three-dimensional arrays. An `\texttt{image/fits}' primary HDU with \kwd{NAXIS}~=~\keyv{1} is describing a one-dimensional entity such as a spectrum or a time series. Applications intended to handle `\texttt{image/fits}' \may\ default to displaying such an image as a graphical plot rather than as a two-dimensional picture with a single row. An application that cannot handle an image with dimensionality other than two \should\ gracefully indicate its limitations to its users when it encounters \kwd{NAXIS}~=~\keyv{1} or \kwd{NAXIS}~=~\keyv{3} cases, while still providing access to the keyword/value pairs. \FITS\ files with degenerate axes (i.e., one or more \indxkw{NAXIS}{n}~=~\keyv{1}) \may\ be described as `\texttt{image/fits}', but the first axes \should\ be non-degenerate (i.e., the degenerate axes \should\ be the highest dimensions). An algorithm designed to render only two-dimensional images will be capable of displaying such an \kwd{NAXIS}~=~\keyv{3} or \kwd{NAXIS}~=~\keyv{4} \FITS\ array that has one or two of the axes consisting of a single pixel, and an application writer \should\ consider coding this capability into the application. Writers of new applications that generate \FITS\ files intended to be described as `\texttt{image/fits}' \should\ consider using the \kwd{WCSAXES} keyword \citep{greisen06} to declare the dimensionality of such degenerate axes, so that \kwd{NAXIS} can be used to convey the number of non-degenerate axes. \subsection{File extensions} The \FITS\ Standard originated in the era when files were stored and exchanged via magnetic tape; it does not prescribe any nomenclature for files on disk. Various sites within the \FITS\ community have long-established practices where files are presumed to be \FITS\ by context. File extensions used at such sites commonly indicate content of the file instead of the data format. In the absence of other information it is reasonably safe to presume that a file name ending in `\texttt{.fits}' is intended to be a \FITS\ file. Nevertheless, there are other commonly used extensions; e.g., `\texttt{.fit}', `\texttt{.fts}', and many others not suitable for listing in a media type registration. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \section{Past changes or clarifications to the formal definition of \FITS} \label{s:changes} {\em This appendix is not part of the \FITS\ Standard, but\index{extension} is included for informational purposes}. \subsection{Differences between the requirements in this Standard and the requirements in the original \FITS\ papers.} \begin{enumerate} \item Sect.~\ref{s:keyw}: The original \FITS\ definition paper \citep{wells81} disallows lower-case letters in the keyword name, but does not specify what other characters may or may not appear in the name. \item Sect.~\ref{s:valcomm}: The slash between the value and comment is `recommended' in the original paper \citep{wells81} whereas the Standard requires that it be present, which is consistent with the prescription of Fortran list-directed input. \item Sect.~\ref{s:valC}: The original paper \citep{wells81} speculated that \FITS\ would eventually support the full range of flexibility that is allowed by Fortran list-directed input, including dimensioned parameters. The Standard restricts the value field to a single value, not an array. \item Sect.~\ref{s:ffci} and Sect.~\ref{s:ffcfp}: The original paper \citep{wells81} defined a fixed format for complex keyword values, with the real part right justified in Bytes~11 through 30 and the imaginary part right justified in Bytes~31 through 50. There are no known \FITS\ files that use this fixed format. The Standard does not define a fixed format for complex keyword values. Instead, complex values are represented in conformance with the rules for Fortran list-directed input, namely, with the real and imaginary parts separated by a comma and enclosed in parentheses. \item Sect.\ 4.4.1.1 and Sect.\ 4.4.1.2: The paper that defines generalized extensions \citep{grosbol88} does not prohibit the appearance of the \kwd{SIMPLE} keyword in extensions nor the \kwd{XTENSION} keyword in the primary header. \end{enumerate} \subsection{List of modification to the \FITS\ Standard, Version~3.0} After the IAUFWG officially approved Version~3.0 of the \FITS\ Standard in 2008, the following additional corrections, clarifications, or format modifications have been made to the document. \begin{enumerate} \item Two typographical errors in Table~\ref{ta:Notation} (previously Table~8.1) were corrected. The last two lines of the third column should read `\kwdalt{LONPOLE} (= \kwdalt{PV\textit{i}\_3})' and `\kwdalt{LATPOLE} (= \kwdalt{PV\textit{i}\_4})'), instead of \kwdalt{PV\textit{i}\_1} and \kwdalt{PV\textit{i}\_2}, respectively. (October 2008) \item The \LaTeX\ text source document was reformatted to conform to the Astronomy \& Astrophysics journal page style (June 2010). The visible changes include the following. \begin{itemize} \item The tables, figures, equations, and footnotes are numbered sequentially throughout the entire the document, instead of sequentially within each chapter. \item The citations use the standard `Author (year)' format instead of being referenced by a sequential number. Also, the `Bibliography' section at the end of the document has been replaced by a `References' section in which the citations are listed alphabetically by author. \end{itemize} \item The following minor corrections or clarifications were made during the refereeing process after submitting Version~3.0 of the \FITS\ Standard for publication in the Astronomy \& Astrophysics journal (July 2010). \begin{itemize} \item A sentence was added to the end of Sect.~\ref{s:versionhist}: `This website also contains the contact information for the Chairman of the IAUFWG, to whom any questions or comments regarding this Standard should be addressed.' \item A `Section' column was added to Table~\ref{t:hist} to reference the relevant section of the document. \item The wording of the second sentence in Sect.~\ref{s:keysyntax} was revised from `Except where specifically stated otherwise in this standard, keywords may appear in any order.' to `Keywords may appear in any order except where specifically stated otherwise in this Standard.' \item A sentence was added to the end of the `Keyword name' subsection in Sect.~\ref{s:keyw}: `Note that keyword names that begin with (or consist solely of) any combination of hyphens, underscores, and digits are legal.' \item A footnote to the description of the \kwd{REFERENC} keyword in Sect.~\ref{s:bibkeywords} was added: `This bibliographic convention (Schmitz 1995) was initially developed for use within NED (NASA/IPAC Extragalactic Database) and SIMBAD (operated at CDS, Strasbourg, France).' \item In Sect.~\ref{s:BinDD}, the phrase `\indxkw{TFORM}{n} format code' was corrected to read `\indxkw{TDISP}{n} format code' (in four places). \item The wording in the `Expressed as' column in Table~\ref{ta:SPECcode} for the \keyv{LOG}, \keyv{GRI}, \keyv{GRA}, and \keyv{TAB} spectral algorithm codes was clarified. \item In Table~\ref{ta:reservedkeys} the \kwd{EXTNAME}, \kwd{EXTVER}, and \kwd{EXTLEVEL} keywords were moved under the `All HDUs' column because they are now allowed in the primary array header. \item The last paragraph of Sect.~4.1.2.3 was corrected to state that the ASCII-text characters have hexadecimal values 20 through 7E, not 41 through 7E. \end{itemize} \end{enumerate} %LC %newpage %LC \subsection{List of modifications to the latest \FITS\ Standard} \label{appregconv} \begin{enumerate} %begin{redtext} \item The representation of time coordinates\index{WCS, timing} has been incorporated by reference from \cite{rots15} and is summarized in Sect.~\ref{sect:timeReps}. Cross-references have been inserted in pre-existing sections of the Standard (namely in Sects.~\ref{s:wcsdate}, \ref{s:Units}, \ref{s:dhist}.1, \ref{s:kobs}.2 and \ref{s:wcstime}, as well as in various places of Sect.~\ref{s:WCS}, such as Sect.~\ref{sect:Celestkw} and Sect.~\ref{sect:SpecRefFrame}). New keywords are listed in a rearranged Table~\ref{ta:WCSkw}. Contextually an erratum was applied in Sect.~\ref{sect:SpecRefFrame}: keywords \kwd{OBSGEO-[XYZ]} were incorrectly marked as \kwdalt{OBSGEO-[XYZ]}; %begin{redtext} the TAI-UTC difference in Table~\ref{table:timescale} was updated with respect to \cite{rots15} taking into account the latest leap second; the possibility of introducing more sources for the Solar System ephemerides was re-worded (at the end of Sect.\ref{sect:plephem} and in Table~\ref{table:refpos}). %end{redtext} %begin{brotext} \item The continued string keywords\index{CONTINUE} described in Sect.~\ref{s:ffch}.2 were originally introduced as a \FITS\ convention during 1994, and registered in 2007. The text of the original convention is reported at \url{http://fits.gsfc.nasa.gov/registry/continue_keyword.html}. The differences with this Standard concern the following. \begin{itemize} \item In the convention, the \kwd{LONGSTRN} keyword was used to signal the possible presence of long strings in the HDU. The use of this keyword is no longer \required\ or \recommended. \item Usage of the convention was \notrecommended\ for reserved or mandatory keywords. Now it is {\em explicitly forbidden} unless keywords are explicitly declared long-string. \item To avoid ambiguities in the application of the previous clause, the declaration of string keywords in Sects.~\ref{s:WCS}, \ref{sect:timeReps} and \ref{sect:CompressedForm} has been reset from the generic `character' to `string'. \item It is also explicitly clarified there is no limit to the number of continuation records. \item The description of continued comment field is new. \end{itemize} %end{brotext} %begin{fuxtext} \item The blank header space convention\index{header space, preallocation} described in Sect.~\ref{s:resk}.4 was used from 1996, and registered in 2014. The text of the original convention is reported at \url{http://fits.gsfc.nasa.gov/registry/headerspace.html}. It included a {\em recommendation} about using the convention in a controlled environment, which does not appear in this Standard. %end{fuxtext} %clearpage %LC %\begin{britext} \item The \kwd{INHERIT} keyword\index{INHERIT} described in Sect.~\ref{s:resk}.6 was originally introduced as a \FITS\ convention in 1995, and registered in 2007. The text of the original convention is reported at \url{http://fits.gsfc.nasa.gov/registry/inherit.html}. See also references and practical considerations therein. % (or shall we quote Zarate ADASS V ?). The differences with the present document concern a more-precise RFC~2119 compliant wording in a couple of sentences in Appendix~\ref{ap:inherit}. %end{britext} %clearpage %LC %begin{magtext} \item The checksum keywords\index{checksum} described in Sect.~\ref{s:resk}.7 were originally introduced as a \FITS\ convention during 1994, and registered in 2007. The text of the original convention is reported at \url{http://fits.gsfc.nasa.gov/registry/checksum.html}. The differences with this Standard concern: \begin{itemize} \item the omission of some additional implementation guidelines, and \item the omission of a discussion on alternate algorithms and relevant additional references. \end{itemize} %end{magtext} %begin{viotext} \item The table keywords\index{min and max in columns, keywords} described in Sect.~\ref{s:atork} and \ref{s:btork} were originally introduced as a \FITS\ convention during 1993, and registered in 2006. The text of the original convention is reported at \url{http://fits.gsfc.nasa.gov/registry/colminmax.html}. The differences with this Standard are as follows. \begin{itemize} \item The exclusion of undefined or IEEE special values when computing maximum and minimum is now {\em mandatory} while it was {\em optional}. \item The original text included the possibility of using the fact \indxkw{TDMIN}{n} were greater than \indxkw{TDMAX}{n} (or \indxkw{TLMIN}{n} greater than \indxkw{TLMAX}{n}) as an indication the values were undefined. This clause has been removed \item The original text contained usage examples and additional minor explanatory details. \end{itemize} %end{viotext} %clearpage %LC %begin{gretext} \item The Green Bank convention\index{Green Bank convention}, mentioned in Sect.~\ref{sect:WCSkw} and described in Appendix~\ref{sect:GBC}, has been in use since 1989, and was registered in 2010. The text of the registered convention is reported at \url{http://fits.gsfc.nasa.gov/registry/greenbank/greenbank.pdf} %. %The differences with this Standard are the following. %\begin{itemize} %\item The original convention made reference only to binary tables, while the present Standard applies it % as well to ASCII tables. %\item The original text and contains some additional details about the history of the convention. %\end{itemize} %end{gretext} %begin{blutext} \item The conventions for compressed data described in Sect.~\ref{sect:CompressedForm}. were originally introduced as a couple of \FITS\ conventions registered in 2007 and 2013. The text of the original conventions is reported at \url{http://fits.gsfc.nasa.gov/registry/tilecompression.html} for compressed images\index{compressed images} %end{blutext} %begin{redtext} and at \url{http://fits.gsfc.nasa.gov/registry/tiletablecompression.html} for compressed binary tables\index{compressed binary tables}. %end{redtext} %begin{blutext} The differences with this Standard are listed below. %end{blutext} \begin{itemize} % %begin{redtext} \item In Sect.~\ref{compDirKwd} the original text for \indxkw{FZALG}{n} mentioned the possibility that, `If the column cannot be compressed with the requested algorithm (e.g., if it has an inappropriate data type), then a default compression algorithm will be used instead.' But there is no default algorithm. This is irrelevant for the Standard. %end{redtext} %begin{blutext} % \item In Sect.~\ref{sect:comprAlg} the alias \keyv{'RICE\_ONE'} is {\em not} adopted in the Standard as a synonym for \keyv{'RICE\_1'}. % \item In Sect.~\ref{plio} a sentence was left out about requiring additional instructions in PLIO to make it work for more then $2^{12}$ bits, since we aren't allowing this possibility in the Standard. % \item In Sect.~\ref{Hcompress} the reference to a `smoothing flag' was dropped. \item Also in Sect.~\ref{Hcompress} the {\em scale factor} is now floating point, while it was originally integer. \item In Table~\ref{tab:CompTypes} %end{blutext} %begin{redtext} (and Sect.~\ref{sect:tabCompAlg}) %end{redtext} the \keyv{'NOCOMPRESS'} algorithm is explicitly mentioned. \end{itemize} \end{enumerate} \subsection{List of modifications for language editing} \label{langedit} %A longer list of the changes done during the language-editing phase %MAY BE reported ELSEWHERE WHERE ??? also in form of latexdiff ? \begin{enumerate} \item Apply systematically \LaTeX\ macros for keyword names and values, and for RFC 2119 expressions, according to instructions reported in the \LaTeX\ source preamble (for future editors of the Standard). \item The acronym \FITS\ is always indicated in italics. \item Use italics systematically for RFC~2119 obligations and recommendations. \item Apply consistent use of italic and typewriter fonts, and \keyv{'} quotation marks around literal keyword values. Correct other minor \LaTeX\ issues. \item Apply systematic capitalization of the names of specific entities, where appropriate. These include Standard (when referring to the \FITS\ Standard document), Version (where numbered), Byte, Column, Parameter, Field, and Axis. Start some words with a lower-case letter that previously began with a capital letter. \item Address other typographical issues, such as the insertion of commas in several places, adding a few non-breaking spaces, and better handling of references to sections, etc. \item Several cases of minor rewording. \item Express small numbers in letter form (one to nine), not in numerals (1 to 9), wherever sensible. However, there is the customary exception for normalization in sentences and headings that also contain numbers greater than nine. \item Compound nouns are systematically hyphenated to highlight the correct grouping (and hence meaning) of the components. This includes the attributive references to ASCII-table, binary-table, and random-groups. \item Improve the aesthetics of some tables. \end{enumerate} %newpage %LC %LC Appendix I \section{Random-number generator} \label{sect:RandomNum}\index{quantization of data} %begin{blutext} \textit{This appendix is not part of the \FITS\ Standard, but is included for informational purposes}. The portable random-number generator algorithm below is from \cite{park88}. This algorithm repeatedly evaluates the function $$seed = (a * seed) \bmod m$$ where the values of $a$ and $m$ are shown below, but it is implemented in a way to avoid integer overflow problems. \begin{verbatim} int random_generator(void) { /* initialize an array of random numbers */ int ii; double a = 16807.0; double m = 2147483647.0; double temp, seed; float rand_value[10000]; /* initialize the random numbers */ seed = 1; for (ii = 0; ii < N_RANDOM; ii++) { temp = a * seed; seed = temp -m * ((int) (temp / m) ); /* divide by m for value between 0 and 1 */ rand_value[ii] = seed / m; } } \end{verbatim} If implemented correctly, the $10\:000^\mathrm{th}$ value of seed will equal $1\:043\:618\:065$. %end{blutext} %LC Appendix JI %clearpage \section{\kwd{CHECKSUM} implementation guidelines}\index{checksum} \label{ap:checksum} %begin{magtext} \textit{This appendix is not part of the \FITS\ Standard, but is included for informational purposes}. \subsection{Recommended \kwd{CHECKSUM} keyword implementation} The \recommended\ \kwd{CHECKSUM} keyword algorithm described here generates a 16-character ASCII string that forces the 32-bit ones' complement checksum accumulated over the entire \FITS\ HDU to equal negative 0 (all 32 bits equal to 1). In addition, this string will only contain alphanumeric characters within the ranges \mbox{0--9}, \mbox{A--Z}, and \mbox{a--z} to promote human readability and transcription. If the present algorithm is used, the \kwd{CHECKSUM} keyword value \must\ be expressed in fixed format, with the starting single-quote character in Column~11 and the ending single-quote character in Column~28 of the \FITS\ keyword record, because the relative placement of the value string within the keyword record affects the computed HDU checksum. The steps in the algorithm are as follows. \begin{enumerate} \item Write the \kwd{CHECKSUM} keyword into the HDU header with an initial value consisting of 16 ASCII zeros (\keyv{'0000000000000000'}) where the first single-quote character is in Column~11 of the \FITS\ keyword record. This specific initialization string is \required\ by the encoding algorithm described in Sect.~\ref{a:Encoding}. The final comment field of the keyword, if any, \must\ also be written at this time. It is \recommended\ that the current date and time be recorded in the comment field to document when the checksum was computed. \item Accumulate the 32-bit ones' complement checksum over the \FITS\ logical records that make up the HDU header in the same manner as was done for the data records by interpreting each 2880-byte logical record as 720 32-bit unsigned integers. \item Calculate the checksum for the entire HDU by adding (using ones' complement arithmetic) the checksum accumulated over the header records to the checksum accumulated over the data records (i.e., the previously computed \kwd{DATASUM} keyword value). \item Compute the bit-wise complement of the 32-bit total HDU checksum value by replacing all 0 bits with 1 and all 1 bits with 0. \item Encode the complement of the HDU checksum into a 16-character ASCII string using the algorithm described in Sect.~\ref{a:Encoding} \item Replace the initial \kwd{CHECKSUM} keyword value with this 16-character encoded string. The checksum for the entire HDU will now be equal to negative 0. \end{enumerate} \subsection{Recommended ASCII encoding algorithm}\index{checksum} \label{a:Encoding} The algorithm described here is used to generate an ASCII string, which, when substituted for the value of the \kwd{CHECKSUM} keyword, will force the checksum for the entire HDU to equal negative 0. It is based on a fundamental property of ones' complement arithmetic that the sum of an integer and the negation of that integer (i.e, the bitwise complement formed by replacing all 0 bits with 1s and all 1 bits with 0s) will equal negative 0 (all bits set to 1). This principle is applied here by constructing a 16-character string, which, when interpreted as a byte stream of four 32-bit integers, has a sum that is equal to the complement of the sum accumulated over the rest of the HDU. This algorithm also ensures that the 16 bytes that make up the four integers all have values that correspond to ASCII alpha-numeric characters in the range \mbox{0--9}, \mbox{A--Z}, and \mbox{a--z}. \begin{enumerate} \item Begin with the ones' complement (replace 0s with 1s and 1s with 0s) of the 32-bit checksum accumulated over all the \FITS\ records in the HDU after first initializing the \kwd{CHECKSUM} keyword with a fixed-format string consisting of 16 ASCII zeros (\keyv{'0000000000000000'}). \item Interpret this complemented 32-bit value as a sequence of four unsigned eight-bit integers, $A$, $B$, $C$, and $D$, where $A$ is the most-significant byte and $D$ is the least-significant byte. Generate a sequence of four integers, $A1$, $A2$, $A3$, $A4$, that are all equal to $A$ divided by 4 (truncated to an integer if necessary). If $A$ is not evenly divisible by 4, add the remainder to $A1$. The key property to note here is that the sum of the four new integers is equal to the original byte value (e.g., $A = A1 + A2 + A3 + A4$). Perform a similar operation on $B$, $C$, and $D$, resulting in a total of 16 integer values, four from each of the original bytes, which \should\ be rearranged in the following order: { %\begin{quote} \small \begin{verbatim} A1 B1 C1 D1 A2 B2 C2 D2 A3 B3 C3 D3 A4 B4 C4 D4. \end{verbatim} %\end{quote} } Each of these integers represents one of the 16 characters in the final \kwd{CHECKSUM} keyword value. Note that if this byte stream is interpreted as four 32-bit integers, the sum of the integers is equal to the original complemented checksum value. \item Add 48 (hex 30), which is the value of an ASCII zero character, to each of the 16 integers generated in the previous step. This places the values in the range of ASCII alphanumeric characters '0' (ASCII zero) to 'r'. This offset is effectively subtracted back out of the checksum when the initial \kwd{CHECKSUM} keyword value string of 16 ASCII 0s is replaced with the final encoded checksum value. \item To improve human readability and transcription of the string, eliminate any non-alphanumeric characters by considering the bytes a pair at a time (e.g., $A1 + A2$, $A3 + A4$, $B1 + B2$, etc.) and repeatedly increment the first byte in the pair by 1 and decrement the second byte by 1 as necessary until they both correspond to the ASCII value of the allowed alphanumeric characters \mbox{0--9}, \mbox{A--Z}, and \mbox{a--z} shown in Figure~\ref{f:ascii}. Note that this operation conserves the value of the sum of the four equivalent 32-bit integers, which is required for use in this checksum application. \begin{figure}[t] \caption{Only ASCII alpha-numeric characters are used to encode the checksum -- punctuation is excluded} \begin{center} \leavevmode \epsfxsize=3.5in \epsffile{ascii.ps} \end{center} \label{f:ascii} \end{figure} \item Cyclically shift all 16 characters in the string one place to the right, rotating the last character ($D4$) to the beginning of the string. This rotation compensates for the fact that the fixed format \FITS\ character-string values are not aligned on four-byte word boundaries in the \FITS\ file. (The first character of the string starts in Column~12 of the header card image, rather than Column~13). \item Write this string of 16 characters to the value of the \kwd{CHECKSUM} keyword, replacing the initial string of 16 ASCII zeros. \end{enumerate} To invert the ASCII encoding, cyclically shift the 16 characters in the encoded string one place to the left, subtract the hex 30 offset from each character, and calculate the checksum by interpreting the string as four 32-bit unsigned integers. This can be used, for instance, to read the value of \kwd{CHECKSUM} into the software when verifying or updating a HDU. \subsection{Encoding example}\index{checksum} This example illustrates the encoding algorithm given in Sect.~\ref{a:Encoding} Consider a \FITS\ HDU whose ones' complement checksum is 868229149, which is equivalent to hex \texttt{33C0201D}. This number was obtained by accumulating the 32-bit checksum over the header and data records using ones' complement arithmetic after first initializing the \kwd{CHECKSUM} keyword value to \keyv{'0000000000000000'}. The complement of the accumulated checksum is 3426738146, which is equivalent to hex \texttt{CC3FDFE2}. The steps needed to encode this hex value into ASCII are shown schematically below. { %\begin{quote} \scriptsize \begin{verbatim} Byte Preserve byte alignment A B C D A1 B1 C1 D1 A2 B2 C2 D2 A3 B3 C3 D3 A4 B4 C4 D4 CC 3F DF E2 -> 33 0F 37 38 33 0F 37 38 33 0F 37 38 33 0F 37 38 + remainder 0 3 3 2 = hex 33 12 3A 3A 33 0F 37 38 33 0F 37 38 33 0F 37 38 + 0 offset 30 30 30 30 30 30 30 30 30 30 30 30 30 30 30 30 = hex 63 42 6A 6A 63 3F 67 68 63 3F 67 68 63 3F 67 68 ASCII c B j j c ? g h c ? g h c ? g h Eliminate punctuation characters initial values c B j j c ? g h c ? g h c ? g h . c C j j c > g h c @ g h c > g h . c D j j c = g h c A g h c = g h . c E j j c < g h c B g h c < g h . c F j j c ; g h c C g h c ; g h . c G j j c : g h c D g h c : g h final values c H j j c 9 g h c E g h c 9 g h final string "hcHjjc9ghcEghc9g" (rotate 1 place to the right) \end{verbatim} \normalsize %\end{quote} } In this example Byte~$B1$ (originally ASCII \texttt{B}) is shifted higher (to ASCII \texttt{H}) to balance Byte~$B2$ (originally ASCII \texttt{?}) being shifted lower (to ASCII \texttt{9}). Similarly, Bytes~$B3$ and $B4$ are shifted by opposing amounts. This is possible because the two sequences of ASCII punctuation characters that can occur in encoded checksums are both preceded and followed by longer sequences of ASCII alphanumeric characters. This operation is purely for cosmetic reasons to improve readability of the final string. This is how these \kwd{CHECKSUM} and \kwd{DATASUM} keywords would appear in a \FITS\ header (with the recommended time stamp in the comment field). { %\begin{quote} \small \begin{verbatim} DATASUM = '2503531142' / 2015-06-28T18:30:45 CHECKSUM= 'hcHjjc9ghcEghc9g' / 2015-06-28T18:30:45 \end{verbatim} %\end{quote} } \subsection{Incremental updating of the checksum}\index{checksum} The symmetry of ones' complement arithmetic also means that after modifying a \FITS\ HDU, the checksum \may\ be incrementally updated using simple arithmetic without accumulating the checksum for portions of the HDU that have not changed. The new checksum is equal to the old total checksum plus the checksum accumulated over the modified records, minus the original checksum for the modified records. An incremental update provides the mechanism for end-to-end checksum verification through any number of intermediate processing steps. By {\sl calculating} rather than {\sl accumulating} the intermediate checksums, the original checksum test is propagated through to the final data file. On the other hand, if a new checksum is accumulated with each change to the HDU, no information is preserved about the HDU's original state. The recipe for updating the \kwd{CHECKSUM} keyword following some change to the HDU is: \( C' = C - m + m' \), where \( C \) and \( C' \) represent the HDU's checksum (that is, the complement of the \kwd{CHECKSUM} keyword) before and after the modification and \( m \) and \( m' \) are the corresponding checksums for the modified \FITS\ records or keywords only. Since the \kwd{CHECKSUM} keyword contains the complement of the checksum, the correspondingly complemented form of the recipe is more directly useful: \( \tilde{~}C' = \tilde{~}(C + \tilde{~}m + m') \), where \( \tilde{~} \) (tilde) denotes the (ones') complement operation. See \cite{rfc1071,rfc1141,rfc1624}. Note that the tilde on the right hand side of the equation cannot be distributed over the contents of the parentheses due to the dual nature of zero in ones' complement arithmetic \citep{rfc1624}. \subsection{Example {\sl C} code for accumulating the checksum}\index{checksum} The ones' complement checksum is simple and fast to compute. This routine assumes that the input records are a multiple of four bytes long (as is the case for {\sl \FITS\ logical records}), but it is not difficult to allow for odd length records if necessary. To use this routine, first initialize the \kwd{CHECKSUM} keyword to \keyv{'0000000000000000'} and initialize \texttt{sum32 = 0}, then step through all the \FITS\ logical records in the \FITS\ HDU. %\begin{quote} \scriptsize \begin{verbatim} void checksum ( unsigned char *buf, /* Input array of bytes to be checksummed */ /* (interpret as 4-byte unsigned ints) */ int length, /* Length of buf array, in bytes */ /* (must be multiple of 4) */ unsigned int *sum32) /* 32-bit checksum */ { /* Increment the input value of sum32 with the 1's complement sum accumulated over the input buf array. */ unsigned int hi, lo, hicarry, locarry, i; /* Accumulate the sum of the high-order 16 bits and the */ /* low-order 16 bits of each 32-bit word, separately. */ /* The first byte in each pair is the most significant. */ /* This algorithm works on both big and little endian machines.*/ hi = (*sum32 >> 16); lo = *sum32 & 0xFFFF; for (i=0; i < length; i+=4) { hi += ((buf[i] << 8) + buf[i+1]); lo += ((buf[i+2] << 8) + buf[i+3]); } /* fold carry bits from each 16 bit sum into the other sum */ hicarry = hi >> 16; locarry = lo >> 16; while (hicarry || locarry) { hi = (hi & 0xFFFF) + locarry; lo = (lo & 0xFFFF) + hicarry; hicarry = hi >> 16; locarry = lo >> 16; } /* concatenate the full 32-bit value from the 2 halves */ *sum32 = (hi << 16) + lo; } \end{verbatim} \normalsize %\end{quote} %\newpage \subsection{Example {\sl C} code for ASCII encoding}\index{checksum} This routine encodes the complement of the 32-bit HDU checksum value into a 16-character string. The byte alignment of the string is permuted one place to the right for \FITS\ to left justify the string value starting in Column~12. %\begin{quote} \scriptsize \begin{verbatim} unsigned int exclude[13] = {0x3a, 0x3b, 0x3c, 0x3d, 0x3e, 0x3f, 0x40, 0x5b, 0x5c, 0x5d, 0x5e, 0x5f, 0x60 }; int offset = 0x30; /* ASCII 0 (zero) */ unsigned long mask[4] = { 0xff000000, 0xff0000, 0xff00, 0xff }; void char_encode ( unsigned int value, /* 1's complement of the checksum */ /* value to be encoded */ char *ascii) /* Output 16-character encoded string */ { int byte, quotient, remainder, ch[4], check, i, j, k; char asc[32]; for (i=0; i < 4; i++) { /* each byte becomes four */ byte = (value & mask[i]) >> ((3 - i) * 8); quotient = byte / 4 + offset; remainder = byte % 4; for (j=0; j < 4; j++) ch[j] = quotient; ch[0] += remainder; for (check=1; check;) /* avoid ASCII punctuation */ for (check=0, k=0; k < 13; k++) for (j=0; j < 4; j+=2) if (ch[j]==exclude[k] || ch[j+1]==exclude[k]) { ch[j]++; ch[j+1]--; check++; } for (j=0; j < 4; j++) /* assign the bytes */ asc[4*j+i] = ch[j]; } for (i=0; i < 16; i++) /* permute the bytes for FITS */ ascii[i] = asc[(i+15)%16]; ascii[16] = 0; /* terminate the string */ } \end{verbatim} \normalsize %\end{quote} %end{magtext} %LC Appendix K %clearpage \section{Header inheritance convention}\index{INHERIT} \label{ap:inherit} %begin{britext} \textit{This appendix is not part of the \FITS\ Standard, but is included for informational purposes}. The reserved Boolean \kwd{INHERIT} keyword described in Sect.~\ref{s:extkwd}.6 is \optional, but if present it \shall\ appear in the extension header immediately after the mandatory keywords. The \kwd{INHERIT} keyword \mustnot\ appear in the primary header. Keyword inheritance provides a mechanism to store keywords in the primary HDU, and have them be shared by one or more extensions in the file. This mechanism minimizes duplication (and maintenance) of metadata in multi-extension \FITS\ files. %It allows keywords to be written only once, and have them be shared by %every extension in the file, when they would be duplicated with the same value %in every extension of a multi-extension \FITS\ file. It \should\ only be used in \FITS\ files that have a null primary array (e.g., with \kwd{NAXIS}~=~\keyv{0}). to avoid possible confusion if array-specific keywords (e.g., \kwd{BSCALE} and \kwd{BZERO}) were to be inherited. When an application reads an extension header with \kwd{INHERIT}~=~\keyv{T}, it \should\ merge the keywords in the current extension with the primary header keywords. The exact merging mechanism is left up to the application. The mandatory primary array keywords (e.g., \kwd{BITPIX}, \kwd{NAXIS}, and \indxkw{NAXIS}{n}) and any \kwd{COMMENT}, \kwd{HISTORY}, and blank keywords in the primary header \mustnot\ be inherited. It is assumed also that the table-specific keywords described in Sect.~\ref{s:ATabl} and \ref{s:BTabl}, and the table-specific WCS keywords described in Sect.~\ref{s:WCS}, cannot be inherited since they will never appear in the primary header. If the same keyword is present in both the primary header and the extension header, the value in the extension header \shall\ take precedence. If \kwd{INHERIT}~=~\keyv{F} in an extension header, the keywords from the primary header \shouldnot\ be inherited. An application that merely reads a \FITS\ file is authorized by \kwd{INHERIT}~=~\keyv{T} to look in the primary HDU for an expected keyword not found in the current HDU. However if the application writes out a modified file, it has to be very careful to avoid unwanted duplication of keywords, and preserve the separation of primary and extension headers. If an application modifies the value of an inherited keyword while processing an extension HDU, then it is \recommended\ to write the modified value of that keyword into the extension header, leaving the value of the keyword in the primary header unchanged. The primary array keywords \should\ only be modified when the intent is to explicitly change the value that will subsequently be inherited in the extensions. Also if the \FITS\ file is read in sequentially (e.g., from tape or Internet downloads), the reader would need to cache the primary header in case it turns out that a later extension in the file uses the \kwd{INHERIT} keyword. %end{britext} %LC Appendix L %clearpage \section{Green Bank convention}\index{Green Bank convention} \label{sect:GBC} %begin{gretext} \textit{This appendix is not part of the \FITS\ Standard, but is included for informational purposes}. The Green Bank convention was developed at a meeting in October 1989 at the US National Radio Astronomy Observatory in Green Bank, West Virginia, to discuss the use of \FITS\ for single-dish radio-astronomy data, and has since been widely used in conjunction with the SDFITS convention\footnote{\url{http://fits.gsfc.nasa.gov/registry/sdfits.html}}. It was devised primarily to record WCS keywords independently for each row of a table containing an image array column, but subsequently it has found more-general application. The basic idea is that of expanding header keywords into binary-table columns, and vice versa, of collapsing unvarying binary-table columns into header keywords. For example, the standard header keyword \kwd{DATE-OBS}, which records the date and time of observation, could be expanded into a column with \indxkw{TTYPE}{n}~=~\keyv{'DATE-OBS'} to record the date and time independently for each row of a binary table. Conversely, a binary-table column with \indxkw{TTYPE}{n}= \keyv{'HUMIDITY'} containing the same value in each row, could be collapsed into a keyword, \kwd{HUMIDITY}, that recorded the constant value. When the Green Bank convention is used (and arguably otherwise), a keyword \shouldnot\ coexist with a column of the same name within a single binary table. Should this situation occur, the column value takes precedence over the keyword. When expanding keywords into columns, the Green Bank convention applies to all \FITS\ keywords that may appear in a binary table except for the following, most of which describe the structure or identity of a binary table HDU: \kwd{XTENSION}, \kwd{BITPIX}, \kwd{NAXIS}, \indxkw{NAXIS}{n}, \kwd{PCOUNT}, \kwd{GCOUNT}, \kwd{TFIELDS}, \kwd{EXTNAME}, \kwd{EXTVER}, \kwd{EXTLEVEL}, \indxkw{TTYPE}{n}, \indxkw{TFORM}{n}, \indxkw{TUNIT}{n}, \indxkw{TSCAL}{n}, \indxkw{TZERO}{n}, \indxkw{TNULL}{n}, \indxkw{TDISP}{n}, \kwd{THEAP}, \indxkw{TDIM}{n}, \kwd{DATE}, \kwd{ORIGIN}, \kwd{COMMENT}, \kwd{HISTORY}, \kwd{CONTINUE}, and \kwd{END}. In order to collapse a column into a keyword, the name of the column (given by \indxkw{TTYPE}{n}) \must\ be a valid keyword name, and the column's constant value \must\ be amenable to representation as a valid keyvalue. Software that implements the Green Bank convention \must\ take into account the possibility that any ``keyword'' (apart from those on the proscribed list), such as \kwd{DATE-OBS}, may change value from row to row of a table. Moreover, when searching the header for a particular keyword, it must first consider the values of the \indxkw{TTYPE}{n} keywords in case the desired keyword has been expanded as a column. Likewise, it must consider each header keyword potentially as a collapsed column, so that a request for the value in a particular row or rows of the non-existent \column{HUMIDITY} column would be satisfied by the value of the \kwd{HUMIDITY} keyword. %end{gretext} %clearpage \begin{thebibliography}{9999} \addcontentsline{toc}{section}{References / Index} \bibitem[Note(2000)]{xx_note} {\bf Note:} Many of these \FITS\ references are available electronically from the NASA Astrophysics Data System (ADS) and/or the \FITS\ Support Office websites at \newline \url{http://adswww.harvard.edu} and \newline \url{http://fits.gsfc.nasa.gov/fits\_documentation.html}. \ \newline \ \newline %LC %TBW{Reminder: add things from any new convention} \bibitem[Allen \& Wells(2005)]{rfc4047} Allen, S. \& Wells, D. 2005, IETF RFC 4047, \newline \url{http://www.ietf.org/rfc/rfc4047.txt} \bibitem[ANSI(1977)]{ansi77} ANSI 1977, \textit{American National Standard for Information Processing: Code for Information Interchange}, ANSI X3.4--1977 (ISO 646) New York: American National Standards\index{ASCII, ANSI} Institute, Inc. % Added for checksum %begin{magtext} \bibitem[Braden et al. (1988)]{rfc1071} Braden, R. T., Borman, D.A., and Partridge, C. 1988 ACM Computer Communication Review, 19, no. 2, 86, IETF RFC 1071, \newline \url{https://tools.ietf.org/html/rfc1071} %end{magtext} \bibitem[Bradner(1997)]{rfc2119} Bradner, S. 1997, IETF RFC 2119, \url{http://www.ietf.org/rfc/rfc2119.txt} \bibitem[Bunclark \& Rots(1997)]{bunclark97} Bunclark, P. \& Rots, A. 1997, \textit{Precise re-definition of} \kwd{DATE-OBS} \textit{Keyword encompassing the millennium}, \newline \url{http://fits.gsfc.nasa.gov/year2000.html} \bibitem[Calabretta \& Greisen(2002)]{calabretta02} Calabretta, M. R. \& Greisen, E. W. 2002, A\&A, 395, 1077 \bibitem[Calabretta \& Roukema(2007)]{calabretta07} Calabretta, M. R. \& Roukema, B. F. 2007, MNRAS, 381, 865 \bibitem[Cotton et al.(1995)]{cotton95} Cotton, W. D., Tody, D. B., \& Pence, W. D. 1995, A\&AS, 113, 159 \bibitem[Cotton et al.(1990)]{cotton90} Cotton, W. D., et al. 1990, \textit{Going AIPS: A Programmer's Guide to the NRAO Astronomical Image Processing System}, Charlottesville: NRAO %begin{blutext} \bibitem[Deutsch(1996)]{deutsch96} Deutsch P.\ 1996, RFC 1951, Network Working Group; available online: \url{http://tools.ietf.org/html/rfc1951} %end{blutext} %\begin{redtext} % Added for v3.1, Time/WCS \bibitem[Folkner, et al.(2009)]{folkner09} Folkner, W.~M., Williams, J.~G., \& Boggs, D.~H.\ 2009, Interplanetary Network Progress Report 42-178, available online: \url{http://tmo.jpl.nasa.gov/progress\_report/42-178/178C.pdf} % Added for v3.1, Time/WCS \bibitem[Folkner, et al.(2014)]{folkner14} Folkner, W.\ M.\ et al.\ 2014, Interplanetary Network Progress Report 42-196, available online: \url{http://ipnpr.jpl.nasa.gov/progress_report/42-196/196C.pdf} %\url{http://tmo.jpl.nasa.gov/progress\_report/42-178/178C.pdf} %\end{redtext} \bibitem[Greisen \& Calabretta(2002)]{greisen02} Greisen, E. W. \& Calabretta, M. R. 2002, A\&A, 395, 1061 \bibitem[Greisen et al.(2006)]{greisen06} Greisen, E. W., Calabretta, M. R., Valdes, F. G., \& Allen, S. L. 2006, A\&A, 446, 747 \bibitem[Greisen \& Harten(1981)]{greisen81} Greisen, E. W. \& Harten, R. H. 1981, A\&AS, 44, 371 \bibitem[Grosb\o l et al.(1988)]{grosbol88} Grosb\o l, P., Harten, R. H., Greisen, E. W., \& Wells, D. C. 1988, A\&AS, 73, 359 \bibitem[Grosb\o l \& Wells(1994)]{grosbol94} Grosb\o l, P. \& Wells, D. C. 1994, \textit{Blocking of Fixed-block Sequential Media and Bitstream Devices}, \url{http://fits.gsfc.nasa.gov/blocking94.html} \bibitem[Hanisch et al.(2001)]{hanisch01} Hanisch, R., et al. 2001, A\&A, 376, 359 \bibitem[Harten et al.(1988)]{harten88} Harten, R. H., Grosb\o l, P., Greisen, E. W., \& Wells, D. C. 1988, A\&AS, 73, 365 \bibitem[IAU(1983)]{iau83} IAU 1983, \textit{Transactions of the IAU}, XVIIIB, 45 \bibitem[IAU(1988)]{iau88} IAU\index{IAU} 1988, \textit{Transactions of the IAU}, XXB, 51 %\begin{redtext} % Added for v3.1, Time/WCS \bibitem[IAU(1997)]{IAUmjd} IAU 1997, Resolution B1 of the XXIIIrd General Assembly -- Transactions of the IAU Vol.\ XXIII B, Ed.\ J.~Andersen, (Dordrecht: Kluwer). Available online: http://www.iau.org/static/resolutions/IAU1997\_French.pdf %\end{redtext} \bibitem[IEEE(1985)]{ieee85} IEEE 1985, \textit{American National Standard -- IEEE Standard for Binary Floating Point Arithmetic}, ANSI/IEEE 754--1985, New York: American National Standards Institute, Inc. %\begin{redtext} % Added for v3.1, Time/WCS \bibitem[Irwin \& Fukushima(1999)]{IF99} Irwin, A.~W.\ \& Fukushima, T.~A.\ 1999, \aap 348, 642 %\end{redtext} \bibitem[ISO(2004)]{iso04} ISO 2004, \textit{Information technology -- Programming languages -- Fortran}, \index{Fortran} ISO/ IEC 1539-1:2004, Geneva: International Organization for Standardization %\begin{redtext} % Added for v3.1, Time/WCS \bibitem[ISO(2004b)]{iso04b} ISO 2004b, International Standard ISO 8601:2004(E), {\em Data elements and interchange formats -- Information interchange -- Representation of dates and times} % Added for v3.1, Time/WCS \bibitem[JPL(2014a)]{jpl14a} NASA/JPL Planetary Ephemerides 2014a, available online: \url{http://ssd.jpl.nasa.gov/?ephemerides} % Added for v3.1, Time/WCS \bibitem[JPL(2014b)]{jpl14b} NASA/JPL Solar and Planetary Ephemerides 2014b, available online: \url{http://ssd.jpl.nasa.gov/?planet\_eph\_export} %\end{redtext} % Added for checksum %begin{magtext} \bibitem[Mallory \& Kullberg (1990)]{rfc1141} Mallory, T. \& Kullberg, A. 1990, %``Incremental Updating of the Internet Checksum'', IETF RFC 1141, \newline \url{https://tools.ietf.org/html/rfc1141} %end{magtext} \bibitem[McNally(1988)]{mcnally88} McNally, D., ed. 1988, \textit{Transactions\index{IAU Style Manual} of the IAU, Proceedings of the Twentieth General Assembly} (Dordrecht: Kluwer) %begin{blutext} % Added for v3.1, Compression \bibitem[Park \& Miller(1988)]{park88} Park, X. \& Miller, X. 1988, Comm.\ ACM, 31, Issue 10, 1192; available online: \url{http://dl.acm.org/citation.cfm?id=63042} % Added for v3.1, Compression \bibitem[Pence et al.(2009)]{pence09} Pence, W.~D., Seaman, R., \& White, R.~L. 2009, PASP, 121, 414 %end{blutext} %LC %\begin{magtext} \bibitem[Pence et al.(2010)]{pence10} Pence, W.~D., Chiappetti, L., Page, C.~G., Shaw, R.~A., \& Stobie, E.\ 2010, \aap, 524, A42 %\end{magtext} %begin{blutext} % Added for v3.1, Compression \bibitem[Pence et al.(2013)]{pence13} Pence, W.~D., Seaman, R., \& White, R.~L. 2013, \textit{Tiled Table Convention for Compressing FITS Binary Tables}, \FITS\ Support Office; available online: \url{http://fits.gsfc.nasa.gov/registry/tiletablecompression.html} %end{blutext} \bibitem[Ponz et al.(1994)]{ponz94} Ponz, J. D., Thompson, R. W., \& Mu\~{n}oz, J. R. 1994, A\&AS, 105, 53 % Added for v3.1, Compression %begin{blutext} \bibitem[Rice et al.(1993)]{rice93} Rice, R.~F., Yeh, P.-S., \& Miller, W.~H. 1993, in Proc. 9th AIAA Computing in Aerospace Conf., AIAA-93-4541-CP, American Institute of Aeronautics and Astronautics %end{blutext} % Added for checksum %begin{magtext} \bibitem[Rijsinghani (1994)]{rfc1624} Rijsinghani, A. (ed.) 1994, %``Computation of the Internet Checksum via Incremental Update'' IETF RFC 1624, \newline \url{https://tools.ietf.org/html/rfc1624} %end{magtext} % Added for v3.1, Time/WCS %\begin{redtext} \bibitem[Rots et al.(2015)]{rots15} Rots, A. H., Bunclark, P.~S., Calabretta, M.~R., Allen, S.~L., Manchester, R.~N. \& Thompson, W.~T.\ 2015, A\&A, 574, A36 %\end{redtext} \bibitem[Schmitz et al. (1995)]{schmitz95} Schmitz, M., et al. 1995, \textit{Information \& On-line data in Astronomy}, eds. D. Egret \& M. A. Albrecht (Kluwer Academic Pub.), 259 %\begin{redtext} % Added for v3.1, Time/WCS \bibitem[Standish(1990)]{standish90} Standish, E.~M.\ 1990, A\&A, 233, 252 % Added for v3.1, Time/WCS \bibitem[Standish(1998)]{standish98} Standish, E.~M.\ 1998, JPL Memo IOM 312.F-98-048 %\end{redtext} \bibitem[Wells et al.(1981)]{wells81} Wells, D. C., Greisen, E. W., \& Harten, R. H. 1981, A\&AS, 44, 363 \bibitem[Wells \& Grosb\o l(1990)]{wells90} Wells, D. C. \& Grosb\o l, P. 1990, \textit{Floating Point Agreement for\index{floating-point FITS agreement} \FITS}, \url{http://fits.gsfc.nasa.gov/fp89.txt} %begin{blutext} % Added for v3.1, Compression \bibitem[White(1992)]{white92} White, R.~L. 1992, in Proceedings of the NASA Space and Earth Science Data Compression Workshop, ed. J.~C. Tilton, Snowbird, UT; available online: \url{https://archive.org/details/nasa_techdoc_19930016742} % Added for v3.1, Compression \bibitem[White \& Greenfield(1999)]{white99} White, R.~L., \& Greenfield, P.\ 1999, in ADASS VIII, ASP Conf. Ser. 172, eds.\ D.~M.\ Mehringer, R.~L.\ Plante, \& D.~A.\ Roberts (San Francisco: ASP), 125 % Added for v3.1, Compression \bibitem[White et al.(2013)]{white13} White, R.~L., Greenfield, P., Pence, W., Tody, D. \& Seaman, R.\ 2013, \textit{Tiled Image Convention for Storing Compressed Images in \FITS\ Binary Tables}, \FITS\ Support Office; available online: \url{http://fits.gsfc.nasa.gov/registry/tilecompression.html} % Added for v3.1, Compression \bibitem[Ziv \& Lempel(1977)]{LZ77} Ziv, J., \& Lempel, A.\ 1977, IEEE Transactions on Information Theory, 23 (3), 337 %end{blutext} \end{thebibliography} \ifiaufwgstyle \input fits_standard40aa.ind \fi %\typeout{#### To make index, type "makeindex fits_standard40aa.idx"} \end{document} %