Up: Definition of the Flexible (FITS)

5 Headers

Header card images shall consist of a keyword, a value indicator (optional unless a value is present), a value (optional), and a comment (optional). Except where specifically stated otherwise in this standard, keywords may appear in any order.

A formal syntax, giving a complete definition of the syntax of FITS card images, is given in Appendix .1. It is intended as an aid in interpreting the text defining the standard.

5.1.2 Components

5.1.2.1. Keyword (bytes 1-8).

The keyword shall be a left justified, 8-character, blank-filled, ASCII string with no embedded blanks. All digits (hexadecimal 30 to 39,"0123456789'') and upper case Latin alphabetic characters (hexadecimal 41 to 5A, "ABCDEFG HIJKLMN OPQRST UVWXYZ'') are permitted; no lower case characters shall be used. The underscore (hexadecimal 5F, " $\_\_$ '') and hyphen (hexadecimal 2D, "-'') are also permitted. No other characters are permitted. For indexed keywords with a single index the counter shall not have leading zeroes.

5.1.2.2. Value indicator (bytes 9-10).

If this field contains the ASCII characters "= $\includegraphics[width=3mm,clip]{espace.eps}$ '', it indicates the presence of a value field associated with the keyword, unless it is a commentary keyword as defined in Sect. 5.4.2.4. If the value indicator is not present or if it is a commentary keyword then Cols. 9-80 may contain any ASCII text.

5.1.2.3. Value/comment (bytes 11-80).

This field, when used, shall contain the value, if any, of the keyword, followed by optional comments. The value field may be a null field; i.e., it may consist entirely of spaces. If the value field is null, the value associated with the keyword is undefined. If a comment is present, it must be preceded by a slash (hexadecimal 2F, "/''). A space between the value and the slash is strongly recommended. The value shall be the ASCII text representation of a string or constant, in the format specified in Sect. 5.2. The comment may contain any ASCII text.

5.2 Value

The structure of the value field shall be determined by the type of the variable. The value field represents a single value and not an array of values. The value field must be in one of two formats: fixed or free . The fixed format is required for values of mandatory keywords and recommended for values of all others. This standard imposes no requirements on case sensitivity of character strings other than those explicitly specified.

5.2.1 Character string

If the value is a fixed format character string, Col. 11 shall contain a single quote (hexadecimal code 27, "'''); the string shall follow, starting in Col. 12, followed by a closing single quote (also hexadecimal code 27) that should not occur before Col. 20 and must occur in or before Col. 80. The character string shall be composed only of ASCII text. A single quote is represented within a string as two successive single quotes, e.g., O'HARA = 'O''HARA'. Leading blanks are significant; trailing blanks are not.

Free format character strings follow the same rules as fixed format character strings except that the starting and closing single quote characters may occur anywhere within Cols. 11-80. Any columns preceding the starting quote character and after Col. 10 must contain the space character.

Note that there is a subtle distinction between the following 3 keywords:

KEYWORD1= ''                   / null string keyword
KEYWORD2= '   '                / blank keyword
KEYWORD3=                      / undefined keyword

The value of KEYWORD1 is a null, or zero length string whereas the value of the KEYWORD2 is a blank string (nominally a single blank character because the first blank in the string is significant, but trailing blanks are not). The value of KEYWORD3 is undefined and has an indeterminate datatype as well, except in cases where the data type of the specified keyword is explicitly defined in this standard.

The maximum allowed length of a keyword string is 68 characters (with the opening and closing quote characters in Cols. 11 and 80, respectively). In general, no length limit less than 68 is implied for character-valued keywords.

5.2.2 Logical

If the value is a fixed format logical constant, it shall appear as a T or F in Col. 30. A logical value is represented in free format by a single character consisting of T or F. This character must be the first non-blank character in Cols. 11-80. The only characters that may follow this single character are spaces, or a slash followed by an optional comment (see Sect. 5.1.2.3).

5.2.3 Integer number

If the value is a fixed format integer, the ASCII representation shall be right justified in columns 11-30. An integer consists of a "+'' (hexadecimal 2B) or "-'' (hexadecimal 2D) sign, followed by one or more ASCII digits (hexadecimal 30 to 39), with no embedded spaces. The leading "+'' sign is optional. Leading zeros are permitted, but are not significant. The integer representation described here is always interpreted as a signed, decimal number.

A free format integer value follows the same rules as fixed format integers except that it may occur anywhere within Cols. 11-80.

5.2.4 Real floating point number

If the value is a fixed format real floating point number, the ASCII representation shall appear, right justified, in Cols. 11-30.

A floating point number is represented by a decimal number followed by an optional exponent, with no embedded spaces. A decimal number consists of a "+'' (hexadecimal 2B) or "-'' (hexadecimal 2D) sign, followed by a sequence of ASCII digits containing a single decimal point (".''), representing an integer part and a fractional part of the floating point number. The leading "+'' sign 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. The exponent, if present, consists of an exponent letter followed by an integer. Letters in the exponential form ("E'' or "D'') shall be upper case. Note: the full precision of 64-bit values cannot be expressed over the whole range of values using the fixed format. A free format floating point value follows the same rules as fixed format floating point values except that it may occur anywhere within Cols. 11-80.

5.2.5 Complex integer number

There is no fixed format for complex integer numbers.

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. Spaces may precede and follow the real and imaginary parts. The real and imaginary parts are represented as integers (Sect. 5.2.3). Such a representation is regarded as a single value for the complex integer number. This representation may be located anywhere within Cols. 11-80.

5.2.6 Complex floating point number

There is no fixed format for complex floating point numbers.

If the value is a complex floating point number, the value must be represented as a real part and an imaginary part, separated by a comma and enclosed in parentheses. Spaces may precede and follow the real and imaginary parts. The real and imaginary parts are represented as floating point values (Sect. 5.2.4). Such a representation is regarded as a single value for the complex floating point number. This representation may be located anywhere within Cols. 11-80.

5.3 Units

The units of all FITS header keyword values, with the exception of measurements of angles, should conform with the recommendations in the IAU Style Manual (McNally 1988). For angular measurements given as floating point values and specified with reserved keywords, degrees are the recommended units (with the units, if specified, given as 'deg').

5.4 Keywords

5.4.1 Mandatory keywords

Mandatory keywords are required in every HDU as described in the remainder of this subsection. They may be used only as described in this standard. Values of the mandatory keywords must be written in fixed format.

5.4.1.1. Principal.

The SIMPLE keyword is required to be the first keyword in the primary header of all FITS files. Principal mandatory keywords other than SIMPLE are required in all FITS headers. The card images of any primary header must contain the keywords shown in Table 1 in the order given. No other keywords may intervene between the SIMPLE keyword and the last NAXISn keyword.

Table 1: Mandatory keywords for primary header.
1 SIMPLE

2 BITPIX

3 NAXIS

4 NAXISn, n = 1, ..., NAXIS

(other keywords)

last END

**Table 1:** Mandatory keywords for primary header.
1	`SIMPLE`
2	`BITPIX`
3	`NAXIS`
4	`NAXISn`, `n` = 1, ..., `NAXIS`

	(other keywords)

last	`END`

The total number of bits in the primary data array, exclusive of fill that is needed after the data to complete the last record (Sect. 4.3.2), is given by the following expression:

$\displaystyle \mbox{\small$N_{\rm bits}$ }$

$\displaystyle \vert\mbox{\small {\tt BITPIX}}\vert \times (\mbox{\small {\tt NA... ...es \mbox{\small {\tt NAXIS2}} \times \cdots \times \mbox{\small {\tt NAXISm}}),$

(1)

where $N_{\rm bits}$ is non-negative and the number of bits excluding fill, m is the value of NAXIS, and BITPIX and the NAXISn represent the values associated with those keywords.

`SIMPLE` keyword.

The value field shall contain a logical constant with the value T if the file conforms to this standard. This keyword is mandatory for the primary header and is not permitted in extension headers. A value of F signifies that the file does not conform to this standard.

`BITPIX` keyword.

The value field shall contain an integer. The 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 BITPIX are given in Table 2.

Table 2: Interpretation of valid BITPIX value.
Value Data Represented

8 Character or unsigned binary integer

16 16-bit twos-complement binary integer

32 32-bit twos-complement binary integer

-32 IEEE single precision floating point

-64 IEEE double precision floating point

**Table 2:** Interpretation of valid `BITPIX` value.
Value	Data Represented
8	Character or unsigned binary integer
16	16-bit twos-complement binary integer
32	32-bit twos-complement binary integer
-32	IEEE single precision floating point
-64	IEEE double precision floating point

`NAXIS` keyword.

The value field shall contain a non-negative integer no greater than 999, representing the number of axes in the associated data array. A value of zero signifies that no data follow the header in the HDU.

`NAXISn` keywords.

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. The NAXISn must be present for all values n = 1,...,NAXIS, and for no other values of n. A value of zero for any of the NAXISn signifies that no data follow the header in the HDU. If NAXIS is equal to 0, there should not be any NAXISn keywords.

`END` keyword.

This keyword has no associated value. Columns 9-80 shall be filled with ASCII blanks.

5.4.1.2. Conforming extensions.

All conforming extensions must use the keywords defined in Table 3 in the order specified. No other keywords may intervene between the XTENSION keyword and the last NAXISn keyword. This organization is required for any conforming extension, whether or not further specified in this standard.

Table 3: Mandatory keywords in conforming extensions.
1 XTENSION

2 BITPIX

3 NAXIS

4 NAXISn, n = 1, ..., NAXIS

(other keywords, including ...)

PCOUNT

GCOUNT

last END

**Table 3:** Mandatory keywords in conforming extensions.
1	`XTENSION`
2	`BITPIX`
3	`NAXIS`
4	`NAXISn`, `n` = 1, ..., `NAXIS`

	(other keywords, including ...)
	`PCOUNT`
	`GCOUNT`

last	`END`

The total number of bits in the extension data array exclusive of fill that is needed after the data to complete the last record such as that for the primary data array (Sect. 4.3.2) is given by the following expression:

$\displaystyle \mbox{\small$N_{\rm bits}$ }$ = $\displaystyle \vert\mbox{\small {\tt BITPIX}}\vert \times \mbox{\small {\tt GCOUNT}} \times$
$\displaystyle (\mbox{\small {\tt PCOUNT}} + \mbox{{\tt NAXIS1}} \times \mbox{\small {\tt NAXIS2}} {\small\times \cdots \times} \mbox{\small {\tt NAXISm}}),$	(2)

where $N_{\rm bits}$ is non-negative and the number of bits excluding fill, m is the value of NAXIS, and BITPIX, GCOUNT, PCOUNT, and the NAXISn represent the values associated with those keywords.

`XTENSION` keyword.

The value field shall contain a character string giving the name of the extension type. This keyword is mandatory for an extension header and must not appear in the primary header . For an extension that is not a standard extension, the type name must not be the same as that of a standard extension.

The IAUFWG may specify additional type names that must be used only to identify specific types of extensions; the full list shall be available from the FITS Support Office.

`PCOUNT` keyword.

The value field shall contain an integer that shall be used in any way appropriate to define the data structure, consistent with Eq. (2).

`GCOUNT` keyword.

The value field shall contain an integer that shall be used in any way appropriate to define the data structure, consistent with Eq. (2).

`EXTEND` keyword.

The use of extensions necessitates a single additional keyword in the primary header of the FITS file. If the FITS file may contain extensions, a card image with the keyword EXTEND and the value field containing the logical value T must appear in the primary header immediately after the last NAXISn card image, or, if NAXIS=0, the NAXIS card image. The presence of this keyword with the value T in the primary header does not require that extensions be present.

5.4.2 Other reserved keywords

These keywords are optional but may be used only as defined in this standard. They apply to any FITS structure with the meanings and restrictions defined below. Any FITS structure may further restrict the use of these keywords.

5.4.2.1. Keywords describing the history or physical construction of the HDU

`DATE` keyword.

Starting January 1, 2000, the following format shall be used. FITS writers should commence writing the value of the DATE keyword in this format starting January 1, 1999 and before January 1, 2000. The value field shall contain a character string giving the date on which the HDU was created, in the form YYYY-MM-DD, or the date and time when the HDU was created, in the form YYYY-MM-DDThh:mm:ss[.sss...], where YYYY shall be the four-digit calendar year number, MM the two-digit month number with January given by 01 and December by 12, and DD the two-digit day of the month. When both date and time are given, the literal T shall separate the date and time, hh shall be the two-digit hour in the day, mm the two-digit number of minutes after the hour, and ss[.sss...] the number of seconds (two digits followed by an optional fraction) after the minute. No fields may be defaulted and no leading zeroes 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. 5.2.

The value of the 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 field contains a character string giving the date on which the HDU was created, in the form DD/MM/YY, where DD is the day of the month, MM the month number with January given by 01 and December by 12, and YY the last two digits of the year, the first two digits being understood to be 19. Specification of the date using Universal Time is recommended but not assumed.

Copying of a FITS file does not require changing any of the keyword values in the file's HDUs.

`ORIGIN` keyword.

The value field shall contain a character string identifying the organization or institution responsible for creating the FITS file.

`BLOCKED` keyword.

This keyword may be used only in the primary header. It shall appear within the first 36 card images of the FITS file. (Note: this keyword thus cannot appear if NAXIS is greater than 31, or if NAXIS is greater than 30 and the EXTEND keyword is present.) Its presence with the required logical value of T advises that the physical block size of the FITS file on which it appears may be an integral multiple of the logical record length, and not necessarily equal to it. Physical block size and logical record length may be equal even if this keyword is present or unequal if it is absent. It is reserved primarily to prevent its use with other meanings. Since the issuance of version 1 of this standard, the BLOCKED keyword has been deprecated .

5.4.2.2. Keywords describing observations

`DATE-OBS` keyword.

The format of the value field for DATE-OBS keywords shall follow the prescriptions for the DATE keyword (Sect. 5.4.2.1). Either the 4-digit year format or the 2-digit year format may be used for observation dates from 1900 through 1999 although the 4-digit format is preferred.

When the format with a four-digit year is used, the default interpretations for time shall be UTC for dates beginning 1972-01-01 and UT before. Other date and time scales are permissible. The value of the 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 shall be clarified in comments. The value of 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 which are tied to an unambiguous coordinate system, the default shall be time as if the observation had taken place at the origin of the coordinate time system. Conventions may be developed that use other time systems. Appendix .11 of this document contains the appendix to the agreement on a four digit year, which discusses time systems in some detail. When the value of 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.

`DATExxxx` keywords.

The value fields for all keywords beginning with the string DATE whose value contains date, and optionally time, information shall follow the prescriptions for the DATE-OBS keyword.

`TELESCOP` keyword.

The value field shall contain a character string identifying the telescope used to acquire the data associated with the header.

`INSTRUME` keyword.

The value field shall contain a character string identifying the instrument used to acquire the data associated with the header.

`OBSERVER` keyword.

The value field shall contain a character string identifying who acquired the data associated with the header.

`OBJECT` keyword.

The value field shall contain a character string giving a name for the object observed.

`EQUINOX` keyword.

The value field shall contain a floating point number giving the equinox in years for the celestial coordinate system in which positions are expressed.

`EPOCH` keyword.

The value field shall contain a floating point number giving the equinox in years for the celestial coordinate system in which positions are expressed. Starting with Version 1, this standard has deprecated the use of the EPOCH keyword and thus it shall not be used in FITS files created after the adoption of this standard; rather, the EQUINOX keyword shall be used.

5.4.2.3. Bibliographic keywords

`AUTHOR` keyword.

The value field shall contain a character string 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.

`REFERENC` keyword.

The value field shall contain a character string citing a reference where the data associated with the header are published.

5.4.2.4. Commentary keywords

`COMMENT` keyword.

This keyword shall have no associated value ; Cols. 9-80 may contain any ASCII text. Any number of COMMENT card images may appear in a header.

`HISTORY` keyword.

This keyword shall have no associated value ; Cols. 9-80 may contain any ASCII text. The text should contain a history of steps and procedures associated with the processing of the associated data. Any number of HISTORY card images may appear in a header.

Keyword hield is blank.

Columns 1-8 contain ASCII blanks. Columns 9-80 may contain any ASCII text. Any number of card images with blank keyword fields may appear in a header.

5.4.2.5. Array keywords.

These keywords are used to describe the contents of an array, either alone or in a series of random groups (Sect. 7). 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 shall not be used in headers describing other structures unless the meaning is the same as that for a primary or groups array.

`BSCALE` keyword.

This keyword shall be used, along with the BZERO keyword, when the array pixel values are not the true physical values, to transform the primary data array values to the true physical values they represent, using Eq. (3). 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 at zero offset. The default value for this keyword is 1.0.

`BZERO` keyword.

This keyword shall be used, along with the BSCALE keyword, when the array pixel values are not the true physical values, to transform the primary data array values to the true values. 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 0.0.

The transformation equation is as follows:

$\displaystyle \mbox{physical\_value}$

$\displaystyle \mbox{{\tt BZERO}} + \mbox{{\tt BSCALE}} \times \mbox{array\_value.}$

(3)

`BUNIT` keyword.

The value field shall contain a character string , describing the physical units in which the quantities in the array, after application of BSCALE and BZERO, are expressed. These units must follow the prescriptions of Sect. 5.3.

`BLANK` keyword.

This keyword shall be used only in headers with positive values of BITPIX (i.e., in arrays with integer data). Columns 1-8 contain the string, "BLANK $\includegraphics[width=3mm,clip]{espace.eps}$ $\includegraphics[width=3mm,clip]{espace.eps}$ $\includegraphics[width=3mm,clip]{espace.eps}$ '' (ASCII blanks in Cols. 6-8). The value field shall contain an integer that specifies the representation of array values whose physical values are undefined.

`CTYPEn` keywords.

The value field shall contain a character string, giving the name of the coordinate represented by axis n.

`CRPIXn` keywords.

The value field shall contain a floating point number , identifying the location of a reference point along axis n, in units of the axis index. This value is based upon a counter that runs from 1 to NAXISn with an increment of 1 per pixel. The reference point value need not be that for the center of a pixel nor lie within the actual data array. Use comments to indicate the location of the index point relative to the pixel.

`CRVALn` keywords.

The value field shall contain a floating point number , giving the value of the coordinate specified by the CTYPEn keyword at the reference point CRPIXn. Units must follow the prescriptions of Sect. 5.3.

`CDELTn` keywords.

The value field shall contain a floating point number giving the partial derivative of the coordinate specified by the CTYPEn keywords with respect to the pixel index, evaluated at the reference point CRPIXn, in units of the coordinate specified by the CTYPEn keyword. These units must follow the prescriptions of Sect. 5.3.

`CROTAn` keywords.

This keyword is used to indicate a rotation from a standard coordinate system described by the CTYPEn to a different coordinate system in which the values in the array are actually expressed. Rules for such rotations are not further specified in this standard; the rotation should be explained in comments. The value field shall contain a floating point number giving the rotation angle in degrees between axis n and the direction implied by the coordinate system defined by CTYPEn.

`DATAMAX` keyword.

The value field shall always contain a floating point number, regardless of the value of BITPIX. This number shall give the maximum valid physical value represented by the array, exclusive of any special values.

`DATAMIN` keyword.

The value field shall always contain a floating point number, regardless of the value of BITPIX. This number shall give the minimum valid physical value represented by the array, exclusive of any special values.

5.4.2.6. Extension keywords.

These keywords are used to describe an extension and should not appear in the primary header.

`EXTNAME` keyword.

The value field shall contain a character string, to be used to distinguish among different extensions of the same type, i.e., with the same value of XTENSION, in a FITS file.

`EXTVER` keyword.

The value field shall contain an integer, to be used to distinguish among different extensions in a FITS file with the same type and name, i.e., the same values for XTENSION and EXTNAME. The values need not start with 1 for the first extension with a particular value of EXTNAME and need not be in sequence for subsequent values. If the EXTVER keyword is absent, the file should be treated as if the value were 1.

`EXTLEVEL` keyword.

The value field shall contain an integer, specifying the level in a hierarchy of extension levels of the extension header containing it. The value shall be 1 for the highest level; levels with a higher value of this keyword shall be subordinate to levels with a lower value. If the EXTLEVEL keyword is absent, the file should be treated as if the value were 1.

5.4.3 Additional keywords

5.4.3.1. Requirements.

New keywords 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.

5.4.3.2. Restrictions.

No keyword in the primary header shall specify the presence of a specific extension in a FITS file; only the EXTEND keyword described in Sect. 5.4.1.2 shall be used to indicate the possible presence of extensions. No keyword in either the primary or extension header shall explicitly refer to the physical block size, other than the deprecated BLOCKED keyword of Sect. 5.4.2.1.