Home

A User's Guide for the Flexible Image Transport System FITS

1. 23 3 1 1 3 Some Hints on Keyword Usage 27 3 1 1 4 Units llle 28 3 1 2 Primary Data Array clle 29 3 1 2 1 Scaled Integers llle 30 3 1 2 2 Undefined Integers 0 30 3 1 2 3 IEEE Floating Point Data 31 3 2 Random Groups 000 eee eee ee eee 32 3 2 1 Header aaa 34 User s Guide Version 4 0 vi CONTENTS 3 2 1 1 Required Keywords 34 3 2 1 2 Random Parameter Reserved Keywords 35 3 2 2 Data Records lll len 36 3 3 Extensions 4 4 2 4 ll 4e ee 37 3 3 1 Required Keywords for an Extension Header 39 3 3 2 Reserved Keywords for Extension Headers 41 3 3 3 Creating New Extensions 42 3 4 ASCII Table Extension llle 43 3 4 1 Required Keywords for ASCII Table Extension 44 3 4 2 Reserved Keywords for ASCII Table Extension 45 3 4 3 Data Records in an ASCII Table Extension 46 3 5 The Image Extension lees 47 3 5 1 Header 2222s 47 3 5 2 Data Records a s esas eos s 48 3 6 Binary Tables llle 48 3 6 1 Required Keywords for Binary Table Extension Headers 49 3 6 2 Reserved Keywords for Binary Table Extension Header 52 3 6 3 Binary Table Extension Data Records 54 3 7 Reading FITS Format lens 56 3 8 FITS Files and Physical Media 5
2. 135 Units are seconds of arc Scale factor Residual value in DEC Start column 6 Fortran format Units are seconds of arc Scale factor User s Guide Version 4 0 136 APPENDIX A EXAMPLES OF FITS HEADERS Discussion of Example ADC FITS Table Header for AGK3 Catalog This ASCII table XTENSION keyword header was created by L Brotzman on September 15 1988 DATE keyword as an illustration of the FITS table headers that would appear on an ADC CD ROM and were distributed with a request for comments It is for the AGK3 catalog HISTORY keywords also EXTNAME as compiled by W Dieckvoss AUTHOR and collaborators HISTORY published in 1975 by the Hamburg Bergedorf Observatory REFERENC The same catalog had been used for the example header in the FITS ASCII table paper Harten et al 1988 The values of BITPIX NAXIS PCOUNT and GCOUNT are those required by the rules for ASCII tables Each row consists of 22 fields TFIELDS and is 80 characters long NAXIS1 The sum of the field sizes specified in the TFORMn keywords where n refers to the field number is 80 the same as the value of NAXIS1 thus for this table the fields fill the entire row There are 183145 rows NAXIS2 The values of the TBCOLn keywords show where each column starts the TTYPEn keywords give a column title usually explained in the comment field of the same keyword and the TFORMn keywords the FORTRAN format of the data in the field Some keywords appear i
3. 20 PM RA is a six digit integer starting in column 62 containing the annual 21 22 proper motion in right ascension in ten thousandths of seconds of time per year RA RESID is a six digit integer starting in column 68 containing the difference between the ADK3 right ascension and the ADK2 right ascension in ten thousandths of seconds of arc corrected for changes in position due to proper motion DEC RESID is a six digit integer starting in column 74 containing the difference between the ADK3 declination and the ADK2 declination in ten thousandths of seconds of arc corrected for changes in position due to proper motion User s Guide Version 4 0 140 APPENDIX A EXAMPLES OF FITS HEADERS Example 6 DIRBE FITS Headers The first two lines following are provided to help the reader determine column numbers They are not part of FITS headers 00000000011111111111222222222233333333333444444444455555555556666666666777 12345678901234567890123456789012345678901234567890123456789012345678909012 SIMPLE BITPIX NAXIS EXTEND DATE DATE MAP ORIGIN TELESCOP INSTRUME OBJECT COMMENT EQUINOX REFERENC COMMENT DATE BEG DATE END PIXRESOL COMMENT COMMENT PRODUCT VERSION WAVE9 SOLELONG APPVEC ZLREMOV COMMENT COMMENT END T file does conform to FITS standard 32 number of bits per data pixel 0 number of data axes T FITS dataset may contain extensions 28 09 94 FITS file creation date dd mm
4. T FITS TAPE WRITTEN AT KPNO 04 18 80 32 4 BYTE 2 S COMPLEMENT INTEGERS 2 NUMBER OF AXES 256 NUMBER OF PIXELS PER ROW 256 NUMBER OF ROWS 1 00000E 06 PHYSICAL INTEGER BSCALE BZERO 0 2147483648 INTEGER VALUE FOR BLANK PIXEL D 013 RASTER LFN RASTER ORDINAL N4486 NUCLEUS AND JET 4350 9 BAD PIXELS BLANKED gt 30 BITS PIXEL OF IPPS RASTER 3 700018E 02 MINIMUM VALUE IN RASTER 1 19825 MAXIMUM VALUE IN RASTER gt KPNO WFITS OF 04 17 80 18 04 80 10 11 54 DCWGE27 THIS FILE TESTS THE 32 BIT PIXEL FORMAT IT ALSO TESTS THE BLANK PIXEL CONVENTION THERE ARE 9 BLANKS IN THIS IMAGE THEY ARE DETECTOR BLEMISH AREA NOT ALL OF THE BLEMISH HAS BEEN BLANKED NGC4486 M87 AND JET MAYALLAM MAYALL 4 METER TELESCOPE AT KITT PEAK VIDEOCAM MAYALL 4M CASSEGRAIN THE KPNO VIDEO CAMERA IS AN INTEGRATING DIGITAL TELEVISION SYSTEM WHICH USES AN RCA ISIT VIDICON TUBE AND ACCUMULATES THE IMAGE IN 256 SQUARE 20 BIT RAM DURING THE INTEGRATION THIS IMAGE HAS BEEN CORRECTED FOR THE DARK CURRENT AND GAIN VARIATIONS ACROSS THE FIELD I E THE DARK IMAGE WAS SUBTRACTED AND THE FLAT FIELD IMAGE WAS DIVIDED INTO THE RAW IMAGE BECAUSE THE FLAT WAS NOT NORMALIZED IN THIS CASE THE RESULTING RATIO IMAGE IS OF ORDER UNITY THIS IS A QUANTUM NOISE LIMITED IMAGE IN RELATIVE INTENSITY UNITS THE GEOMETRY OF THIS IMAGE HAS NOT BEEN CORRECTED FOR THE PINCUSHION DISTORTION OF THE VIDEO C
5. To simplify the process of writing software to read FITS files the following fixed format is mandatory for values of the required keywords For the same reason its use is strongly recommended for other keywords Departures should be restricted to cases where use of fixed format is impossible for some reason Use of the fixed format simplifies the task of the software in determining the type of the value The structure of a fixed format value field depends upon its type Logical T or F in column 30 in or Character string A beginning in column 11 and an ending after column 20 but no later than column 80 with the string in between To include a single quote within a character string use two successive single quotes for example O Hara becomes 0 HARA Leading blanks in a string are significant trailing blanks are not e Real part integer or floating right justified ending in column 30 20 columns maximum e Imaginary part integer or floating right justified ending in column 50 20 columns maximum i e starting in column 31 or after User s Guide Version 4 0 20 SECTION 3 FITS FUNDAMENTALS The 20 columns specified in the fixed format may not always be sufficient to hold the full precision of a real floating point number or either the real or imaginary part of a complex floating point number None of the required keywords used for the primary header random groups or the ASCII table binary tabl
6. are the dimensions of the array stored in field n This size must be consistent with the repeat count specified by the value of TFORMn e THEAP integer is used by the variable length array convention section 5 2 1 For that convention its value gives the location of the start of the heap used to store variable length arrays The value is equal to the number of bytes of extension data preceding the start of the heap including the main table and any gap between the main table and the heap All keywords reserved under the generalized extensions agreement section 3 3 2 apply to binary tables 3 6 3 Binary Table Extension Data Records The data records in a binary table consist of the main data table and possibly additional data after the main table The BINTABLE main table logical data records begin with the record immediately following the last header record Each record contains 2880 8 bit bytes in the order defined by the header Table rows do not necessarily begin at the beginning of a new record The size of the main table is the product of the values of the NAXIS1 and NAXIS2 keywords The additional data begin immediately after the end of the main table they do not start at the next record The last record of the data should be zero filled past the end of the valid data with all bits cleared If there are no additional data NASA GSFC Astrophysics Data Facility 3 6 BINARY TABLES 55 after the main table this record will be th
7. Table 4 3 Reference Frames for Equatorial Coordinate Systems FK4 mean place old before the 1976 IAU system FK4 NO E mean place old system but without e terms FK5 mean place new after the 1976 IAU system GAPPT geocentric apparent place after the 1976 IAU system User s Guide Version 4 0 72 SECTION 4 WORLD COORDINATE SYSTEMS The default value is FK4 Under the FK4 the date of equinox value of the EQUINOX keyword is interpreted as a Besselian epoch and under FK5 as a Julian epoch If there is no EQUINOX keyword or EPOCH for old FITS files the equinox is assumed to be 1950 0 for FK4 and 2000 0 for FK5 e MJD OBS floating specifies the time of observation in the form of a Modified Julian Date JD 2400000 5 in the International Atomic Time time scale Whether this point refers to the starting midpoint or ending time is not defined Use comments to say Use of this keyword permits greater precision than DATE OBS Because the FK4 reference frame is not inertial there is a small but significant rotation relative to distant objects the epoch or time of observation is required to specify when the mean place was correct 4 4 Current Status In support of this proposal Calabretta has developed the WCSlib software package It is available under a GNU Public License through the NRAO FITS archive described in Section 6 2 The Greisen and Calabretta 1996 proposal is still under discussion in the FITS
8. The adoption by the IEEE of a standard format for floating point numbers and its widespread implementation by many computer systems provided the solution On December 22 1989 the IAU FITS Working Group adopted the Floating Point Agreement establishing IEEE 754 IEEE 1985 32 bit and 64 bit numbers as the standard FITS floating point data types effective January 1 1990 2 6 Physical Blocking In 1979 when FITS was originally developed the dominant medium for data storage and transport was 1 2 inch nine track magnetic tape In FITS Paper I the physical block size was set equal to the logical record size As time passed it became clear that many of the major data producers regarded this block size as inefficient in terms of both tape length used and the number of I O operations required to write data The new generation of computers with Megabyte size memory could easily read much larger blocks As a consequence FITS Paper III included a provision that there could be up to 10 logical records per physical block on 1 2 inch nine track magnetic tape New storage media such as cartridge tapes and optical disks were replacing magnetic tape Many of the new media could access data only in blocks of fixed length typically 2 bytes and the FITS 23040 bit logical record length would not correspond to an integral number of these blocks Whereas FITS had been discussed in FITS Paper I in the context of files on magnetic tape the increasing use of
9. b ELON ELAT ecliptic coordinates A 8 SLON SLAT supergalactic coordinates HLON HLAT helioecliptic coordinates Galactic coordinates as defined above are in the new system adopted by the IAU in 1950 where the origin 0 latitude and 0 longitude is in the direction of NASA GSFC Astrophysics Data Facility 4 3 COORDINATE KEYWORDS 71 the galactic center Identifications for older systems or future systems should be in the form zLAT zLON but not one of the designations used in Table 4 2 Ecliptic coordinates refer to the mean ecliptic and equinox of the date of observation in the post IAU 1976 system The values of the CTYPEn provide both the world coordinate system and the projection used For example if the data matrix contained a sky map in right ascension and declination projected on the plane using the tangent projection the CTYPEn values would be CTYPE1 RA TAN CTYPE2 DEC TAN The coordinates must be logically consistent for example RA TAN should not be paired with GLON ARC 4 3 Coordinate Keywords There are a number of standard equatorial coordinate systems HW proposed the following keywords to supplement the reserved keywords discussed in section 3 1 1 1 e RADECSYS character standing for RA Dec system specifies the reference frame for the equatorial coordinate system It should be used when the CTYPEn values are an RA xxxx DEC xxxx pair Table 4 3 shows the four values defined
10. 3 Required FITS keywords are not inherited 4 If a keyword appears both in the primary header and an extension header the value in the extension header will apply to the extension 5 The reserved commentary keywords COMMENT HISTORY and uuuuuuuu are never inherited 6 Changes to an inherited keyword appear only in the extension header not the primary header i e the inherited keyword will appear in the extension header with its new value and the primary header value remains unchanged As with any FITS convention software may allow for overriding the inheritance convention for specific purposes For example the IRAF FITS kernel has a mechanism to override the rules given in items 1 and 2 5 5 Checksum Proposal Seaman and Pence 1995 have proposed a means for embedding a checksum within a FITS files The proposal has been presented for discussion to the community as the first step in the process of seeking endorsement by the IAUFWG This section summarizes their proposal more details can be found in the paper itself The purpose of such a checksum is to verify that there has been no error in a data transmission A checksum is calculated for the data that are to be sent and then calculated in the same way where the data are received the two are then compared All checksums are calculated using ones complement arithmetic that is the result of overflow in addition in the most significant bit is carried over to the least signifi
11. EXAMPLES OF FITS HEADERS NASA GSFC Astrophysics Data Facility 155 Appendix B IEEE Formats The material in this appendix is adapted from the IEEE 754 1985 floating point standard 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 Table B 1 shows the type of IEEE floating point value regular or special for all double and single precision hexadecimal byte patterns User s Guide Version 4 0 IEEE value Double Precision Single Precision 40 0000000000000000 00000000 denormalized 0000000000000001 00000001 to to OOOFFFFFFFFFFFFF OO7FFFFF positive underflow 0010000000000000 00800000 positive numbers 0010000000000001 00800001 to to TFEFFFFFFFFFFFFE TFTFFFFE positive overflow TFEFFFFFFFFFFFFF TFTFFFFF 00 7TFFO000000000000 7F800000 NaN 7TFFO000000000001 7F800001 to to TFFFFFFFFFFFFFFF TFFFFFFF 0 8000000000000000 80000000 negative 8000000000000001 80000001 denormalized to to 800FFFFFFFFFFFFF 807FFFFF negative underflow 8010000000000000 80800000 negative numbers 8010000000000001 80800001 to to FFEFFFFFFFFFFFFE FF7FFFFE negative overflow FFEFFFFFFFFFFFFF FF7FFFFF oo FFF0000000000000 FF800000 NaN FFF0000000000001 FF800001 to to FFFFFFFFFFFFFFFF FFFFFFFF APPENDIX B IEEE FORMATS Certain values may be designated as quiet NaN no diagnostic when used or si
12. EXTVER TFORM1 TTYPE1 TFORM2 TTYPE2 TFORM3 TTYPE3 TUNIT3 TFORM4 TTYPE4 TUNIT4 TFORM5 TTYPE5 TFORM6 TTYPE6 TUNIT6 COMMENT END SPECTRUM 1J 2 gt SCAN 20A SOURCE 1D BASEFREQ HZ 2 1E 2 DELTFREQ HZ 2 11 2 NCHAN 1024E SPECTRUM JY T 8 2 4134 20 Or o FIELD 6 IS VECTOR 9 card images of ASCII blanks NASA GSFC Astrophysics Data Facility N im TR YNNN TR TR YNNN TR TR TR NS TR NS TR VSS TR BINARY TABLE EXTENSION BYTES A TABLE IS A 2D MATRIX BYTES PER ROW NUMBER OF ROWS NO PARAMETERS ONE TABLE 6 FIELDS PER ROW SAMPLE OF BINARY TABLE WITH SPECTRUM SECOND VERSION OF TABLE FIELD 1 32 BIT INTEGER SCAN NUMBER FIELD 2 20 CHARACTER STRING SOURCE NAME FIELD 3 DOUBLE PREC FLOATING POINT REFERENCE CHANNEL FREQUENCIES IN HERTZ FIELD 4 SINGLE PREC FLOATING POINT FREQUENCY INCREMENT FREQUENCIES IN HERTZ FIELD 5 16 BIT INT NUMBER OF CHANNELS FIELD 6 1024 SNGL PREC FLT PT VALUES MEASURED SPECTRUM JANSKYS 131 Discussion of Example 4 A Binary Table Containing Spectra This extension header is the one that would be used for a structure designed by D Wells to illustrate an efficient use of a binary table to hold spectra The spectrometer for this illustration has 1024 channels and the data are in floating point form This design is intentionally grossly simplified for the sole purpose of illustratio
13. Greisen and Harten 1979 suggested a method for handling multivolume unlabeled tape but this proposal has not been put into practice widely Many current programs that read FITS files will be unable to handle a multiple unit file The grouping proposal discused in section 5 3 uses tables to associate physically separated FITS HDUs into a logical unit User s Guide Version 4 0 60 SECTION 3 FITS FUNDAMENTALS NASA GSFC Astrophysics Data Facility 61 Section 4 World Coordinate Systems While every point in the FITS data array can be located in the cooordinate system determined by the array axes scientific interpretation requires knowledge of the physical or world coordinates corresponding to the index points For example in an array that represents a spectrum the relation between wavelength and index number on the wavelength axis must be known The original FITS papers reserved several keywords CTYPEn CRPIXn CRVALn CDELTn and CROTAn for use in specifying this relation While the original paper Wells Greisen and Harten 1981 defined these keywords only for linear transformations they can be also be adapted for non linear transformations using the definitions in Section 3 1 1 2 However for a non linear transformation some keywords in addition to those reserved will be required to provide a full description To create FITS arrays representing the images of objects in the sky requires projection of the celestial
14. HIERARCH appears in the first eight columns followed by one or more domain names and then the keyword The ESO Archive for example uses HIERARCH The first sample FITS header in the first FITS paper Wells Greisen and Harten 1981 illustrated this approach but it was not formally proposed or tested for interoperability at the time If a group chooses to use such a convention the header should always allow a reader unfamiliar with it to NASA GSFC Astrophysics Data Facility 5 7 KEYWORD DOMAINS 103 interpret those card images as pure comments n example of such usage appears in Example 1 of Appendix A Existing constructs in FITS provide another approach to domain definition Some reserved FITS keywords for example ORIGIN TELESCOP and INSTRUME describe natural domain limiters the installation where the FITS file was written and the telescope and instrument used to obtain the data Keywords following an ORIGIN keyword in an HDU could be understood as having the meaning defined for the particular installation given by the value of the ORIGIN keyword similarly TELESCOP and INSTRUME when present could signify that keywords following have the meaning defined for data sets from the telescope and or instrument named It is then possible to define keyword meanings specific to a particular organization telescope and or instrument and use the values of the relevant keywords to signify that such a particular set of keyword definitions
15. Suggested name by A Warnock Preliminary proposal Suggested name for binary dumps No full proposal submitted Intended for structure to represent equivalent of tape mark on other media No full proposal submitted Image extension contains an array of one or more dimensions Prototype matrix extension used for archiving IUE products superseded by IMAGE ASCII tables Reserved for possible use in supporting analog of HDF group structures under FITS Current proposal does not use separate extension type Table 5 1 Reserved Extension Type Names NASA GSFC Astrophysics Data Facility 5 2 CONVENTIONS FOR BINARY TABLES TT Table 5 2 Possible Status Levels for FITS Extensions Status Description S Standard FITS extension type accepted by the IAUFWG and endorsed by the IAU P Proposal for FITS extension type accepted by regional FITS committees but not yet by the IAUFWG D Draft proposal to be discussed in regional FITS committees and by community R Reserved FITS extension type name for which a full draft proposal has not yet been submitted L Local FITS extension type in use only by a particular group 5 2 Conventions for Binary Tables In the paper presenting the binary table extension Cotton Tody and Pence 1995 hereafter CTP three conventions are described in appendixes While these conventions were not part of the formal extension rules endorsed by the IAUFWG a number of keywords were reserved wit
16. been organized to formulate recommendations for FITS practice required for files produced by HEASARC OGIP but intended for application throughout the high energy astrophysics community 5 6 1 1 Keywords and column names In keywords and table column names HEASARC recommends use of the underscore hexadecimal 5F rather than the hyphen hexadecimal 2D The only cases where a hyphen is to be used in keywords are e where use of a hyphen is established usage as for example in the DATE OBS key word e io represent a minus negation sign NASA GSFC Astrophysics Data Facility 5 6 OTHER PROPOSED CONVENTIONS 95 This set of recommendations is similar to those in the original paper for ASCII table fields as discussed in section 3 4 2 but extends them to keywords and binary table fields Extending the rules for keywords to column names makes it possible to replace a table column heading with a keyword with the same name if the value for that column in every row of the table is the same as in the Green Bank convention section 5 2 3 2 HEASARC OGIP requires the following additional conventions for column names in all tables it produces and recommends them for others e Different columns in the same table cannot have the same name and all columns must be unique in the first 16 characters e Embedded blanks are specifically forbidden as they are for keywords e Values of the TTYPEn keyword are case insensitive as specified for ASCII
17. community and may undergo further changes The following aspects of the proposal have wide acceptance already and should be generally understood by FITS readers e Index point at the center of a pixel e Transformation matrix future applications are expected to follow the PC notation and usage although there are many existing files with the CD notation and combined rotation scaling usage e SIN TAN and ARC projections with the standard coordinates and the native coordinates locally parallel at the tangent point as in the AIPS convention e The conventions for including the name of the coordinate system and projection in the value of CTYPEn NASA GSFC Astrophysics Data Facility 4 4 CURRENT STATUS 73 e The coordinate keywords described in Section 4 3 Trial implementations and discussions will continue before a standard for world coordinates becomes part of the overall FITS standard Among the questions still under discussion are the following e Is there a way to use this formalism for spectra time series and unequally spaced data e Is the notation of section 4 2 1 the best choice for multiple WCS used for the same image e Can the pixel correction image method be implemented for complicated FITS files for example those with many images each with its own correction e Should the parallel use of the CROTAn notation continue and if so how long e Can agreement be reached on a more specific algorithm for choo
18. tables in the NOST standard described in section 6 1 2 e Column names must begin with an alphabetic character A Z a z not a digit or underscore e Column names may be up to 68 characters in length 5 6 1 2 Proposed CREATOR Keyword CREATOR character identifies the software that originally created a FITS file The value refers to the software that originally defined the FITS file structure and wrote the contents it should not be changed if the file is copied largely intact into another file Use HISTORY keywords to document such travels of the file after it has been created When appropriate the value of the CREATOR keyword should identify the specific version of the software that created the FITS file e g WRITEFITS V3 2 The AUTHOR keyword section 3 1 1 2 has sometimes been misused for this purpose but AUTHOR is reserved for the human author or compiler of a document User s Guide Version 4 0 96 SECTION 5 ADVANCED FITS 5 6 1 3 Proposed TSORTKEY Convention The purpose of this convention is to provide information on the ordering of rows in a FITS ASCII or binary table How the table has been ordered is useful information for users indeed it may be necessary for some data processing operations Usually the rows are in order of increasing values in a particular column in the table for example time or right ascension To specify the order used in a particular FITS table a new keyword is used TSORTKEY charact
19. BINARY TABLES 83 October 1989 It is designed primarily for the case where only one field is a multidimensional array or where all array fields in a row have the same dimensions The extension header keyword MAXIS integer gives the number of dimensions of the array in the table field The properties of the array would be given in columns in the table The column labels would be the names of the keywords used to describe a primary or image data array except that NAXISn would be replaced by MAXISm These labels are given by the values of the TTYPEn keywords in the binary table header Thus e TTYPEn MAXISm means that the number of elements along axis m in the array contained in the table is given in column n of the table MAXIS1 describes the most rapidly varying axis of the array e TTYPEn CTYPEm means that the name of the physical coordinate of axis m in the array contained in the table is given in column n of the table e TTYPEn CRPIXm means that the reference point for axis m in the array contained in the table is given in column n of the table e TTYPEn CRVALm means that the value of the physical coordinate for axis m at the reference point in the array contained in the table is given in column n of the table e TTYPEn CDELTm means that the rate of change of the physical coordinate along axis m per unit change in the counting index at the reference point of the array contained in the table is given in c
20. FITS files that contain combinations of new and standard extensions must be allowed in order to facilitate the transition to a new design e The presence of a new extension in a FITS file should not affect the operation of a program that does not know about the new type of extension e Any program scanning a FITS file on any medium should be able to locate the beginning of any extension and find the start of the next one This rule implies that the extension header must specify in a consistent and standardized manner the total number of data bits that are associated with it e It must be possible to devise new types of extensions without prior approval Keywords in the primary FITS header may not be used to NASA GSFC Astrophysics Data Facility 3 3 EXTENSIONS 39 announce the existence of a particular type of extension because such keywords would need to be approved by the IAUFWG e Anyone wishing to create a new extension format is free to do so Creators of new extensions should check the list of extension type names registered with the IAUFWG which is maintained on line by the FITS Support Office and register a new type name for their format e No information in either the primary header or the extension header should specify the physical block sizes of FITS blocks on tape or any other medium but see the discussion of section 3 1 1 2 about the BLOCKED keyword The detailed rules for FITS extensions implement these requir
21. Now a FITS file may include many extensions of different types Given that the order of adoption of extensions as standard cannot be predicted with certainty it would not have been wise to prescribe an order of extension types within a file Suppose standard extensions were required to appear first and the fourth extension on a data set were to become standard Then the data set would go out of conformance It was thus agreed that extensions might appear in any order in a FITS file With extensions appearing in any order those extensions a user might want to or be able to read could be separated by extensions with which the user would be unfamiliar the user might wish to read say only the third and seventh and skip all the rest The user should not have to know anything about the structure of the intervening extensions to be able to read the ones of interest To make this process possible two general rules were specified e Each type of extension must have a unique name provided in the header e The header must provide information that will allow the software reading it to calculate its size The software reading the FITS file would have a list of types of extensions that it could handle By reading the type name from a standard location in the header the software would be able to determine whether or not it could handle this extension If it couldn t it could at least calculate how many records it would have to skip to reach the begin
22. SIMPLE and have a value of T true if the file conforms to FITS standards Subsequent keywords convey the form in which array values are stored the number of dimensions in the array and the length of each axis The coordinate system scaling and other information may be given at user option Note that while the FITS required keywords will always be the same the interpretation of the associated values may be expanded For example negative values of the keyword BITPIX are now used to indicate IEEE floating point data and the PCOUNT keyword which originated in connection with random groups was then used in the generalized extensions definition and has now been adopted to describe the heap of variable length arrays logically included in a binary table Neither later usage was part of the original definition Many keywords called indexed keywords consist of an alphabetic root and a number If there is only one index the number does not have leading zeroes NAXIS1 not NAXISOO1 TTYPE11 not TTYPEO11 Such keywords are represented in this Guzde by an upper case root followed by a lower case n for example NAXISn TTYPEn If there is more than one index as in the PC matrix discussed in section 4 2 2 2 leading zeroes may be needed to delimit the indexes for example PC012001 as PC121 does not distinguish between P5 and P 3 1 1 1 Required Keywords The following keywords are required for all Basic FITS headers for all time and must appe
23. VLA conference room in the cafeteria building and worked together to produce the Basic FITS Agreement in 36 hours on March 27 28 1979 It incorporated the lessons learned from the Harten and Wells prototypes One key issue during the development process was the choice of a logical record size that would be both convenient for all machines in use at the time and would at the same time be close to filling a physical block on magnetic tape The adopted 23040 bit logical record was an integral multiple of the word sizes of all machines then in use and was close to the 30240 bit User s Guide Version 4 0 8 SECTION 2 HISTORY physical block size limit of the CDC 6000 7000 series tapes One data structure was supported an unsigned 8 bit signed 16 bit or signed 32 bit integer array with 0 999 axes However to permit future growth additional records were permitted to follow the data array as long as the logical record size was the 23040 bit standard a provision that served as the basis for the later development of extensions In May 1979 NOAO and NRAO exchanged FITS tapes thereby showing that the rules of the Basic Agreement would operate in practice The first FITS tape was written by a PL I program executing on an IBM 360 under OS MVT 32 bits twos complement and EBCDIC and was successfully read by a FORTRAN program executing on a CDC 6400 under SCOPE 60 bits ones complement and Display Code very nearly the worst possible combination of
24. a table and the columns represent the characters that make up the tabulated items Each member of the array is one character or digit Each row consists of a sequence of fields The sequence of fields is the same for all rows and all rows must have the same length Each field in the table contains one item in the table either a character string or the ASCII representation of a number in FORTRAN 77 format A particular field may consist of many columns as many as are needed to carry the full string or number The field organization is described by a series of keywords These keywords describe the initial column and number of columns for each field Other kinds of information that can be listed in the header include the units of quantities in the field scale factors between the values in the table and the physical quantities they represent analogous to the BZERO and BSCALE values of Basic FITS and the string used to represent an undefined value Fields in the table may be reserved for comments which would be skipped by automatic decoding software but may be read by simply printing the table This property allows the transfer of tables that contain a large quantity of comments Examples 3 and 5 illustrate ASCII table headers User s Guide Version 4 0 44 SECTION 3 FITS FUNDAMENTALS 3 4 1 Required Keywords for ASCII Table Extension The following keywords are required for ASCII table extensions and must appear in the first eight card i
25. and column names 94 5 6 1 2 Proposed CREATOR Keyword 95 5 6 1 3 Proposed TSORTKEY Convention 96 5 6 1 4 Maximum and Mininum Values in Table Columns 97 5 6 2 World Coordinates in Tables 99 5 6 Compression 22e 100 5 6 4 Other Reserved Type Names 100 5 6 5 Developing New Conventions 101 5 7 Keyword Domains eee eee 101 5 8 Polarization llle 104 5 9 Spectra elle 104 5 10 High Energy Astrophysics Applications 105 6 Resources 107 6 1 The FITS Support Office 004 107 6 1 1 On line Information 0 002 0004 108 6 1 2 Documents e 109 6 1 8 Software and Test Files ll 111 6 1 4 Contact Information lll 112 6 2 NRAO FITS Resources leen 113 63 HEASARC ll 115 6 4 Some Additional Software Resources 117 6 5 Other Network Resources llle 118 Appendixes A Examples of FITS Headers 121 B IEEE Formats 155 User s Guide Version 4 0 viii List of Tables List of Tables 4 1 4 2 4 3 5 1 5 2 5 3 B 1 Common Projections llle 69 Identification of Sky Coordinate Systems 70 Reference Frames for Equatorial Coordinate Systems 71 Reserved Extension Type Names 76 Possible Status Levels for FITS Ext
26. and must conform to all the requirements in that section An axis may be described by more than one label For example a spectrum may be described by frequency wavelength and velocity only one of which can be linear GC propose reserving the following additional key words e CmYPEn floating is label m for axis n CmNITn floating gives the units for axis n when label m is used e CmPIXn floating is the reference point of axis n when label m is used e CmVALn floating is the coordinate value of the reference point on axis n when label m is used NASA GSFC Astrophysics Data Facility 4 2 PROPOSED CONVENTIONS 65 The values of m may run from 2 9 the original CTYPEn CRPIXn CRVALn and CDELTn keywords are used for m 1 Note that the reference pixel need not be the same for all descriptions of an axis The values of a given pixel in the different units must be consistent e g 1420 4 MHz and 21 1 cm There are no defaults assumed for m gt 2 all of these keywords should be specified 4 2 2 Sky Images There are five steps in converting a digital array into an image on the sky 1 optional Transform from actual image pixel numbers to those that would be observed by an ideal instrument 2 Transform from the origin and axes of the instrumental coordinate matrix system to the origin and axes of a set of projected sky coordinates 3 Convert the scale along each axis from pixel to physical values still in the pr
27. binary table extension but may be used only with the meanings specified below They may appear in any order between the TFIELDS and END keywords Note that some of these keywords are the same as those for an ASCII table extension The reason is that they are used for a binary table in a way analogous to their use for an ASCII table However the allowed values and their meaning may differ somewhat from those for an ASCII table as the rows of an ASCII table are composed of characters and those of a binary table are composed of bytes e TTYPEn character has a value giving the label or heading for field n While the rules do not further prescribe the value following the recommendations for the TTYPEn keyword of ASCII tables is a good practice using letters digits and underscore but not hyphen also string comparisons involving the values should be case insensitive HEASARC has made this practice one of their internal standards section 5 6 1 1 e TUNITn character has a value giving the physical units of field n The rules should follow the prescriptions given in section 3 1 1 4 e TSCALn floating has a value providing a scale factor for use in converting stored table values for field n to physical values The default value is 1 e TZEROn floating has a value providing the offset for field n The default value is 0 Physical_value Stored value x TSCALn TZEROn 3 12 As is the case for arrays care should be taken to avoid
28. bit floating point values No other values for BITPIX are valid The name comes from the original FITS design in which the values of the array were regarded as pixels in a digital image BITs per PIXel With the use of negative values of BITPIX to signify floating point array values the number of bits per data array member is the absolute value of BITPIX NAXIS integer is for the primary header the number of axes in the data following the associated primary data array value of zero is acceptable and indicates that no data are associated with the current header The most common reason for a primary HDU with no data is that all the data in the file are extensions The maximum possible value is 999 Negative values are not allowed NAXISn n 1 NAXIS NAXIS 0 gt NAXIS1 not present integer is the number of elements along axis n of the array NAXIS1 describes the most rapidly varying index of the array NAXIS2 the second most rapidly varying etc This convention is the same as the one used in FORTRAN A value of zero for any of the NAXISn signifies that no data array is associated with the header None of the NAXISn may be negative The rules of FITS do not strictly forbid use of NAXISn keywords for values of NASA GSFC Astrophysics Data Facility 3 1 BASIC FITS 23 n gt NAXIS While some groups use such keywords for special purposes the practice is not recommended as a general rule the other keywords follow
29. by the rules of FITS Because values of keywords may contain lower case letters comparisons should not be case sensitive A FITS file may contain records after the end of the FITS primary HDU and the extensions Such special records can be recognized by the fact that they begin where FITS would begin an extension at the end of the previous extension or the primary HDU but the first 8 bytes do not contain the string XTENSION While the FITS rules do not forbid the string SIMPLE its presence would be confusing and should be avoided These records must have the standard FITS length of 23040 bits to make it easy for a FITS reader to go through them in a search for the end of file A generalized FITS reader should be prepared for them 3 8 FITS Files and Physical Media FITS is defined as a logical structure independent of the medium on which the data appear FITS files are regarded as bit byte streams with a 2880 byte logical record length Data written in FITS format can for example be on magnetic tape magnetic disk optical disk or simply on line However the reader of a FITS file must know its physical structure in order to unpack it Historically magnetic tape was the original storage medium for FITS formats The initial conventions for 1 2 inch 9 track magnetic tape were established in the original FITS paper Wells Greisen and Harten 1981 and modifications to these conventions were presented at the same time as the ru
30. defined in the formal BINTABLE rules the variable length array and string array conventions make particular interpretations and conflicting uses should be avoided to prevent confusion The following values of T are permitted L Logical value X Bit array NASA GSFC Astrophysics Data Facility 3 6 BINARY TABLES 51 A Character The substring array convention section 5 2 2 uses the characters SSTR immediately following the rA to indicate that the convention is being used to describe the substrings This usage implies that a colon and different standard character string following the rA can be used as an indicator of other conventions for describing character fields While the formal FITS rules do not prohibit other uses such conflicting usage could be confusing and is to be avoided B Unsigned 8 bit integer or byte I Signed 16 bit integer J Signed 32 bit integer E Thirty two bit IEEE floating point D Sixty four bit IEEE floating point C Complex pair of single precision floating point values M Complex pair of double precision floating point values P Sixty four bit descriptor of variable length arrays pointer The only allowed repeat counts are 0 and 1 This data type was designed to contain information on the location of data in variable length arrays section 5 2 1 When used to indicate a variable length array the value takes the form rPt maxelem where r is the repeat count t is any of the data types discussed
31. e EXTNAME character must have the value GROUPING e EXTVER integer has a value that serves as a group identification number Every HDU with EXTNAME GROUPING in a given FITS file must have a different value of EXTVER This number distinguishes the group from any other defined in the file The following keyword is not required but is strongly recommended GRPNAME character provides a name for the group table This name should contain only letters digits and underscore hexadecimal 5F decimal 95 in particular it should not contain any embedded ASCII blanks hexadecimal 20 decimal 32 The value is case insensitive NASA GSFC Astrophysics Data Facility 5 3 HIERARCHICAL GROUPING PROPOSAL 87 A group can contain any number of members The members may be a mix of HDU types in any order They may be primary HDUs extensions of types endorsed by the IAUFWG currently TABLE IMAGE and BINTABLE and other extensions that conform to the general rules for extensions provided in section 3 3 but have not been endorsed specifically by the IAUFWG Member tables may be group tables thus identifying subordinate groups Group members can be identified by the group table in two ways by reference or by position Either or both can be used Both have potential drawbacks For identification by reference the HDU is identified using the values of the XTENSION EXTNAME and EXTVER keywords A possible difficulty is that there may be more than one
32. editing during the revision process Development of the standard follows a procedure developed at the NOST that follows the common practices of other standardization bodies The technical panel develops an initial Draft Standard When the panel has reached consensus on this Draft Standard the document is made available to the astronomical community for comment typically for a period of two months Availability of the document for review is announced to the sci astro fits newsgroup and to the electronic mailing lists described in section 6 5 The American Astronomical User s Guide Version 4 0 110 SECTION 6 RESOURCES Society Executive Office also is notified Special efforts are made to ensure review by members of the IAUFWG and the regional FITS committees After the period for review is over the technical panel reviews the comments and revises the standard in reponse Replies are sent to all reviewers describing the changes made by the technical panel in response to the review and explaining the reasons when the recommended revision was not made This cycle is repeated until the number of revisions recommended by the reviewers is so small that it is evident that the astronomical community has reached consensus The document that results from this process is called a Proposed Standard This document is then submitted to a NOST accreditation panel composed of the NOST Executive Board the NOST Secretary two other members from the Space
33. electronic transport for files was leading to the concept of a FITS file as a pure bit stream without special ties to any particular medium However a set of prescriptions for the NASA GSFC Astrophysics Data Facility 2 7 IMAGE EXTENSION 13 physical expression of FITS files on different media was still needed General rules for all media and in particular for how to write FITS logical records to the 2 byte physical blocks were proposed by Wells and P Grosbgl ESO in 1991 With minor changes they were approved by the IAUFWG in the spring of 1994 They appear in section 3 8 of this Guide 2 7 Image Extension In the late 1980s there had been some discussion in the FITS community about providing a mechanism for including multidimensional arrays in extensions as well as in the primary data array The IUE group was looking for a way to include several related arrays in the same file in particular both their data and a flag array in which the flag for each element would refer to the data for that element Because the data types for the flag and the data were different they could not just add another axis and include the flag data in the primary data array J D Ponz and J R Munoz of the ESA IUE group and R Thompson CSC of the GSFC IUE group made a detailed draft available electronically early in 1992 The extension was given the name IMAGE The only significant discussion was whether or not to provide for Random Groups records afte
34. epoch equinox B1950 Start column Fortran format Units are hours Minutes RA epoch equinox B1950 Start column Fortran format Units are minutes of time Seconds RA epoch equinox B1950 Start column Fortran format Units are seconds of time Scale factor Sign DEC epoch equinox B1950 Start column Fortran format Degrees DEC epoch equinox B1950 Start column Fortran format Units are degrees Minutes DEC epoch equinox B1950 Start column Fortran format Units are minutes of arc Seconds DEC epoch equinox B1950 Start column Fortran format Units are seconds of arc Scale factor Number of photog obs used to determine pos Start column Fortran format Epoch of AGK3 position 1900 Start column Fortran format User s Guide Version 4 0 134 TUNIT13 TSCAL13 TZERO13 TTYPE14 TBCOL14 TFORM14 TUNIT14 TSCAL14 TTYPE15 TBCOL15 TFORM15 TUNIT15 TSCAL15 COMMENT COMMENT TTYPE16 TBCOL16 TFORM16 TUNIT16 TSCAL16 TTYPE17 TBCOL17 TFORM17 TTYPE18 TBCOL18 TFORM18 TNULL18 TTYPE19 TBCOL19 TFORM19 COMMENT COMMENT COMMENT TTYPE20 TBCOL20 TFORM20 TUNIT20 TSCAL20 TTYPE21 TBCOL21 TFORM21 APPENDIX A EXAMPLES OF FITS HEADERS yr 0 01 1900 0 PM RA COSD 38 I5 arcsec yr 0 001 pPM DEC 43 I5 arcsec yr 0 001 Units are years Scale factor Zero offset Annual proper motion in RA times Cos delt
35. extensions of the same type For example if there are several tables on a tape they could be distinguished by their values of EXTNAME The name may have a hierarchical structure giving its relation to other files e g mapl cleancomp Remember however that the reader should be able to retrieve the data properly using only the first eight characters of the string Conventions for hierarchical structures of extension names have not been established The distinction between the name and the type is that the type the value of XTENSION describes the structure of the extension while the value of EXTNAME provides a name for the extension but says nothing about its structure For example the header for an ASCII table containing information about Seyfert galaxies could have XTENSION TABLE and EXTNAME SEYFERTS e EXTVER integer is a version number which can be used with EXTNAME to identify an extension The default value is 1 User s Guide Version 4 0 42 SECTION 3 FITS FUNDAMENTALS e EXTLEVEL integer specifies the level of the extension in a hierarchical structure The default value for EXTLEVEL should be 1 Because the term type refers to the structure of an extension as given by the value of XTENSION user definition of a EXTTYPE keyword is not recommended though not strictly forbidden by the FITS rules As a sample application of hierarchical structure consider an observing session in which several object
36. following applications are also possible 1 A vector column in a binary table may be a multidimensional array that represents a map in the same way as a primary data array or image extension array 2 The entries in a binary table may represent objects and their positions on a map An event list would produce such a table The map axes could be for example sky positions R A Dec or locations on a detector grid x y One column in the table would be assigned to each coordinate of the positions of the objects The map coordinates and possibly the transformation between detector and sky position must be described in some way 3 The user may wish to tabulate a set of coordinate transformation keywords applying to different images for example defining how the celestial pointing of an imaging instrument changed with time Standard keywords should have a consistent usage throughout FITS The keywords reserved to describe primary arrays and images should be used to describe coordinates in these other applications only if they have they same meaning In particular they should never be used in a way that can or might lead to contradictory meanings in the same HDU In the case of a multidimensional array in a table the coordinate keywords are being used in the same way as for a data array they tell how to interpret a one dimensional array of data values in the FITS file as a multidimensional matrix If there is only one array in the table
37. foreground signal from Zodiacal dust remains in the map FEO ok sk sk ke sk 9k 9k CG SOC GR IG koh I GIG GI II I A IIE ICI I 1 a 1 9k 1 ok 3K gt K K DIRBE Pixel number resolution 9 Pixel_no entire fieldname Pixel_no 1J Sub pixel containing the mean DIRBE LOS line of sight when pixel is divided into 256 sub pixels 16x16 grid according to standard quad sphere rules PSubPos entire fieldname Pixel subpos E E 1B E User s Guide Version 4 0 142 COMMENT COMMENT COMMENT COMMENT COMMENT COMMENT TTYPES3 TUNITS3 TFORMS3 COMMENT COMMENT COMMENT COMMENT COMMENT COMMENT COMMENT COMMENT COMMENT COMMENT COMMENT COMMENT COMMENT COMMENT COMMENT COMMENT COMMENT COMMENT COMMENT COMMENT COMMENT TTYPE4 TUNIT4 TFORM4 COMMENT COMMENT COMMENT TTYPES TUNITS TFORMS COMMENT COMMENT COMMENT TTYPE6 TUNIT6 TFORM6 COMMENT COMMENT COMMENT TTYPE7 APPENDIX A EXAMPLES OF FITS HEADERS Time in TAI seconds since 01 JAN 1981 00 00 00 000 UTC This is the average time of all observations of a pixel within the time interval TSTART to TSTOP regardless of the weight assigned to a particular observation For this product not a physically meaningful quantity Time entire fieldname Time 24D Cumulative weighted average of the 140 micron photometry This average is calculated using the weighted number of observations from each Weekly Averaged Map Wt
38. illustrate how new keywords can be created for a FITS data set Note the blank lines The blanks in columns 1 8 indicate that columns 9 80 are to be treated as comment in this case they are blank NASA GSFC Astrophysics Data Facility 127 Example 3 ASCII Table Note The first two lines following are provided to help the reader determine column numbers They are not part of FITS headers 00000000011111111112222222222333333333344444444445 55b555555666666666 12345678901234567890123456789012345678901234567890123456789012345678 SIMPLE BITPIX NAXIS EXTEND DRIGIN DBJECT DATE END T 8 0 T ESO SNG CAT 27 5 84 28 card images of ASCII blanks XTENSION TABLE d BITPIX 8 NAXIS NAXIS1 98 NAXIS2 10 PCOUNT GCOUNT TFIELDS TTYPE1 IDEN d TBCOL1 1 TFORM1 E14 7 d TNULL1 d TTYPE2 RA d TBCOL2 15 TFORM2 E14 7 d TNULL2 d TTYPE3 DEC d TBCOL3 29 TFORM3 E14 7 d TNULL3 d N Ny i SNS n YN VSS STANDARD FITS FORMAT REV OCT 1981 CHARACTER INFORMATION NO IMAGE DATA ARRAY PRESENT THERE IS AN EXTENSION EUROPEAN SOUTHERN OBSERVATORY THE IDENTIFIER DATE THIS TAPE WRITTEN DD MM YY TABLE EXTENSION CHARACTER INFORMATION SIMPLE 2 D MATRIX NO OF CHARACTERS PER ROW NO OF ROWS RANDOM PARAMETER COUNT GROUP COUNT NO OF FIELDS PER ROW NAME OF ROW BEGINNING COLUMN OF THE FIELD FORMAT NULL VALUE NAME OF ROW BEGINNING COLUMN
39. legal value for column 6 Pulse Height Analyzer energy data format 2 byte INTEGER physical unit of field minimum legal value for column 7 maximum legal value for column 7 corrected X detector coordinate data format 2 byte INTEGER physical unit of field minimum legal value for column 8 maximum legal value for column 8 corrected Y detector coordinate data format 2 byte INTEGER physical unit of field minimum legal value for column 9 maximum legal value for column 9 event quality grade data format 2 byte INTEGER physical unit of field minimum legal value for column 10 maximum legal value for column 10 CCD number data forma 2 byte INTEGER minimum legal value for column 11 maximum legal value for column 11 General Descriptive Keywords EXTNAME EVENTS HDUCLASS OGIP HDUCLASi EVENTS INSTRUME SIS1 ORIGIN GSFC i OBJECT NGC 4151 OBSERVER I N Jones TELESCOP ASCA CREATOR extractor10q SEQNUM 71019020 SEQPNUM 004 PROCVER 45 1 8 Instrument mode Name of extension format conforms to OGIP GSFC conventions Extension contains Events Instrument name Origin of FITS file Name of observed object Principal Investigator Telescope mission name Program that created this FITS file Sequential number from ODB Number of times sequence processed Processing script version keywords User s Guide Version 4 0 148 MODAL_ID BIT_RATE OB
40. of the file cannot easily be marked on the hardware The name has been reserved for use in developing this concept as yet there is no detailed proposal A FITS file might contain a pure bit stream such as telemetry An extension type name DUMP has been proposed and reserved for such data Details of how this extension would be structured remain to be developed 5 6 5 Developing New Conventions The conventions that have been described in this section are not formally a part of the FITS rules and do not exclude others However since the purpose of such conventions is to develop a widely used and understood set of practices new conventions should be developed only if the existing conventions in general use will not work for new data Community comment and review should be part of development of any new convention If design of a FITS data set is constrained by project deadlines the intended users of the data and other groups that are making similar data publicly available should be consulted early in the development process Proposed data designs with new conventions should be made available for review and comment to the user community as soon as a draft is available opportunity for review should also be given to the general astronomical community to the extent possible consistent with project procedures Requests for review should emphasize any deadlines The proposed conventions should then be revised on the basis of the response before being i
41. optical astronomers were making great strides toward producing high quality digital data through the use of charge coupled devices CCDs Here too transport of data in one wavelength domain for comparison with data in another wavelength domain was required Because each installation had its own internal storage format new software was needed User s Guide Version 4 0 2 SECTION 1 THE ORIGIN AND PURPOSE OF FITS whenever two installations exchanged data for the first time An obvious substitute for all these cumbersome processes was the creation of a single standard interchange format for transporting digital images among cooperating institutions Then each institution would need only two software packages one to translate the transfer format to the internal format used by the institution and one to transform the internal format to the transfer format The Flexible Image Transport System FITS was created to provide such a transfer format From its initial applications exchange of radio astronomy images between Westerbork and the VLA and exchange of optical image data among Kitt Peak the VLA and Westerbork the use of FITS has expanded to include the entire spectrum of astronomical data It is being used for a variety of data structures from past current and future NASA supported projects for example X ray data from the Einstein High Energy Astrophysics Observatory HEAO 2 the Compton Gamma Ray Observatory and the R ntgen Satel
42. or if all the arrays in the table have the same properties the standard keywords that describe the meaning and scaling of the axes CTYPEn CRPIXn CRVALn and CDELTn can be used in the header On the other hand because they are already used in the header to define the table as a two dimensional array the NAXIS and NAXISn keywords cannot also be used to describe the member arrays The Green Bank convention described in section 5 2 3 2 avoids the problem of keyword conflict by using different keywords MAXIS and MAXISm to describe the array in the table In the other two cases the usage is different User s Guide Version 4 0 100 SECTION 5 ADVANCED FITS In array usage the location of a data value relative to the axes is associated with its position in an array In the table of positions on the other hand the location of a data value relative to one or more axes is associated with its actual value One can even imagine a case where both kinds of coordinate might appear in a table two fields giving z and y positions and another field containing an array If the same keywords could be used in both contexts it would not be clear which coordinate system was being described by the header keywords To avoid possible confusion the standard array keywords should not be used to describe a coordinate system where the values of individual table entries are located such as the coordinate system of z y positions For a table of coordinate t
43. sphere onto the array plane The original FITS papers did not specify how this process was to be carried out The first approach to this problem implemented in the Astronomical Image Processing System AIPS and described in AIPS Memo 27 Greisen 1983 has been widely used but no conventions have been formally endorsed by the IAU FITS Working Group E Greisen and M Calabretta 1996 hereafter GC have expanded the AIPS approach into a comprehensive proposal for conventions to be used in projecting spherical coordinates onto a two dimensional plane This proposal has evolved in response to considerable community discussion and is intended for formal submission to the IAUFWG Their proposal discusses a number of other World Coordinates issues as well User s Guide Version 4 0 62 SECTION 4 WORLD COORDINATE SYSTEMS The remainder of this section 4 will describe the GC proposal some other proposed conventions that are gaining acceptance and additional FITS community practices Following these conventions in creating a data set will make it easier for many others to read and understand the data In particular designers of FITS files that will be distributed outside the originating site should not adopt conventions that conflict with those described in this Guide without consulting with other members of the FITS community particularly the anticipated readers of the file In particular to prevent confusion avoid using the keywords and notat
44. tangent projection section 4 2 2 4 of the sky onto a FITS array For the X axis the right ascension at array position 640 5 that is equivalent to halfway between 640 and 641 TCRPX3 keyword is 182 744003 degrees TCRVL3 and the right ascension changes by 4 4199999 x 10 degrees for a change of 1 in the array position decreasing with increasing index number TCDELT3 For the Y axis the declination at array position 640 5 TCRPX4 keyword is 39 4291992 degrees TCRVL4 and changes by 4 4199999 x 10 degrees for a change of 1 in the array NASA GSFC Astrophysics Data Facility 153 index increasing with increasing index number TCDELT4 Columns 8 and 9 provide positions of the events in a linearized focal plane pixel coordinate system obtained by correcting the raw detector coordinates for instrument distortion FITS array member 640 5 640 5 corresponds to 0 0 of the pixel coordinate system TCRPX8 TCRVL8 TCRPX9 TCRVL9 with the scale on both axes 0 027 mm unit change in index The OPTICn keywords provide the array position of the optical axis in both linearized detector coordinates and sky coordinates and the FOV X MM and FOV Y MM keywords provide the size of the field of view at the detector 23 mm x 23 mm The FITS conventions and a discussion of the ASCA system are available on separate pages at the HEASARC sites at http heasarc gsfc nasa gov and ftp legacy gsfc nasa gov User s Guide Version 4 0 154 APPENDIX A
45. the Software item on the HEASARC menu block or directly from ftp legacy gsfc nasa gov software ftools The fv tool is available at the same location The HEASARC FITS Working Group HFWG a body within HEASARC established to support present and future multimission needs of the OGIP at NASA and in particular to ensure that the FITS formats and keywords used do not violate the FITS standards has developed a number of conventions and designs While use of these conventions and designs is required only for OGIP the high energy astrophysics community has been consulted during the development process and many of these conventions are used elsewhere for high energy astrophysics FITS files and other FITS files A number of these conventions have been described in section 5 6 1 Other conventions specify keywords and strings to be used for such information as quality flags channel boundaries exposure times and units Among the standard file formats are those for light curves and spectra Complete documentation on the recommendations and formats that have been adopted by HFWG and on those that are under consideration can be found at NASA GSFC Astrophysics Data Facility 6 4 SOME ADDITIONAL SOFTWARE RESOURCES 117 heasarc gsfc nasa gov docs heasarc ofwg ofwg_intro html on the HEASARC main Web page or directly by ftp to ftp legacy gsfc nasa gov The archive of traffic on the heafits mail exploder also is accessible from the HFWG page
46. to manipulate merge and intercompare these tables The ASCII table FITS extension Harten et al 1988 hereafter FITS Paper IV conforms to the standard FITS rules and to the generalized rules for FITS extensions The column headings are provided in an extension header that describes the contents of the table The table data are stored as a large character array Each row of the table consists of a sequence of fields Each field is described by a series of keywords specifying the field format using FORTRAN 77 notation the location in the row where it begins and possibly a column heading or other information about the field User s Guide Version 4 0 12 SECTION 2 HISTORY 2 5 Floating Point In the original FITS format the members of the data array were required to be of integer data type Non integral values or values outside the range that could be expressed as integers were stored through the use of scaling The actual physical values would be derived from the numbers in the FITS file by a linear transformation The coefficients for this transformation were stored in the header as values of keywords This method of using integers to represent floating point values has a number of limitations Only a limited dynamic range of values can be stored with precision using scaled integers Many astronomical data systems use floating point in their internal data processing conversion to integers consumes significant amounts of computer time
47. until 5 END no value The last keyword must be END This card image has no im column 9 or value field but is filled with ASCII blanks Other keywords may appear only between the last NAXISn and END keywords The remainder of the last header record should be filled with ASCII blanks These keywords prescribe the size of the primary data array in bits NBITS through equation 3 1 NBITS ABS BITPIX x NAXIS1 x NAXIS2 x x NAXISm 3 1 where m is the value of NAXIS and the keyword names represent the values of those keywords Examples 1 and 2 in Appendix A illustrate primary headers that precede data arrays 3 1 1 2 Reserved Keywords Many of the following reserved keywords were originally suggested by Wells Greisen and Harten 1981 If a reserved keyword is used the meaning and structure must be as described here Keywords other than the reserved keywords should not be used in their place to express the same concepts Reserved keywords may appear in any order between the required keywords and the END key word Some of these keywords describe the data array e BUNIT character represents the physical units of the quantity stored in the array e g Janskys magnitudes pixel The name comes from brightness units Section 3 1 1 4 discusses recommendations for choice of units e BSCALE floating is a scale factor used in converting array elements stored on the FITS data set to physical values User
48. will be outside the data array Note that the values of the CRVALn do not change between images in different regions of the same projection In the TAN tangent or gnomic geometry the projection of a point of the celestial sphere onto the plane is found by extending the line from the center of the sphere to the point on the tangent plane This projection is common in optical astronomy In the SIN sine or orthographic geometry common in radio NASA GSFC Astrophysics Data Facility 4 2 PROPOSED CONVENTIONS 69 aperture synthesis the projection point is on the perpendicular between the point on the sphere and the surface of the tangent plane In the ARC geometry the projection point is on an arc passing through the point on the sphere and the tangent plane with the center of the arc at the reference point This projection preserves angular distances It is the natural projection of Schmidt camera imagery such as the Palomar Sky Survey and is also used in single dish radio telescope mapping GC note that the NCP geometry discussed in the AIPS memo a projection onto a plane perpendicular to the North Celestial Pole used by the Westerbork Synthesis Radio Telescope and a few other east west radio interferometers can be treated as a special case of the orthographic SIN projection The SIN and TAN projections are special cases of the perspective zenithal projections which are generated from a point and carried through from the unit sphere to t
49. with the others in the FITS community who need such conventions User s Guide Version 4 0 64 SECTION 4 WORLD COORDINATE SYSTEMS 4 2 Proposed Conventions Although they have not been formally endorsed by the IAUFWG the AIPS conventions Greisen 1983 have been widely used in particular for distribution of IRAS infrared and Einstein X ray imagery A detailed discussion and analysis appears in AIPS memo 27 Greisen 1983 Hanisch and Wells 1988 hereafter HW proposed adopting these conventions as standard within FITS They also discussed a number of other conventions recommended at a meeting held in Charlottesville Virginia in January 1988 sponsored by NASA Code EZ The GC proposal marks further movement in the directions begun at Charlottesville The discussion in the remainder of section 4 of the User s Guide is based primarily upon those three documents especially GC However it does not necessarily reflect the views of all the cited authors on all points 4 2 1 Improved Axis Descriptions The original FITS Paper Wells Greisen and Harten 1981 assumed that the units of the axes would be the basic SI units appropriate to the CTYPEn axes But the choice of units may not be obvious GC propose that a new keyword be reserved for such cases CUNITn floating is the units in which both CRVALn and CDELTn for axis n are expressed Units identified using this keyword should be chosen using the principles defined in section 3 1 1 4
50. zero for NAXIS keyword and that an extension may be present T value for EXTEND keyword The comment following the EXTEND keyword notes that an extension is present The END card image is followed by 28 card images consisting of ASCII blanks to fill the record to 2880 bytes The string XTENSION TABLE at the start of the next record introduces the header of an ASCII table extension The BITPIX NAXIS PCOUNT and GCOUNT keywords have the values required for an ASCII table The NAXISn keywords show that it is ten rows long with 98 characters per row Each row consists of seven fields TFIELDS keyword all in FORTRAN format E14 7 TFORMn keywords with no blanks between TBCOLn keywords A null value in any field is represented by a blank TNULLn keywords The seven fields in each row represent a galaxy identifier right ascension declination type diameter of the galaxy at the 25 mag arcsec level inclination and radial velocity respectively TTYPEn key words User s Guide Version 4 0 130 APPENDIX A EXAMPLES OF FITS HEADERS Example 4 Binary Table Containing Spectra Note The first two lines following are provided to help the reader determine column numbers They are not part of FITS headers 000000000111111111122222222223333333333444444444455555555556666666666 123456789012345678901234567890123456789012345678901234567890123456789 XTENSION BINTABLE BITPIX NAXIS NAXIS1 NAXIS2 PCOUNT GCOUNT TFIELDS EXTNAME
51. 0E 00 HISTORY UVLOD DATA BASE CREATED BY USER 76 AT 14 JUL 1983 10 17 08 HISTORY UVLOD OUTNAME CYGA QUTCLASS XY HISTORY UVLOD DUTSEQ 1 OUTDISK 3 ORIGIN AIPSNRAO VLA VAX3 DATE 19 08 83 FILE WRITTEN ON DD MM YY HISTORY AIPS IMNAME CYGA IMCLASS IMAP IMSEQ 1 HISTORY AIPS USERNO 76 END 23 card images of ASCII blanks NASA GSFC Astrophysics Data Facility 123 Discussion of Example 1 VLA Image Header This header describes an image of 3C405 OBJECT keyword on 27 October 1982 DATE OBS keyword by an observer with the designation Perl OBSERVER keyword The data matrix has four axes right ascension declination frequency and polarization NAXISn and CTYPEn keywords The matrix here contains an image for only one frequency and polarization The sine projection from the sky sphere to the tangent plane is used The coordinates are equinox 1950 note the use of the EPOCH keyword now discouraged use EQUINOX instead Right ascension is in degrees extending from approximately 299 47779 degrees at point pixel 1 to approximately 299 3925 at point 2048 with the value 299 435165226 at point 1024 CRVAL1 CDELT1 CRPIX1 Declination in degrees runs from approximately 40 57486 to approximately 40 61848 with the value 40 5961940065 at pixel 513 CRVAL2 CDELT2 CRPIX2 The measurement is at 4866 35 MHz CRVAL3 CDELT3 is not significant here there is only one point The values are stor
52. 1 1 3 Some Hints on Keyword Usage While only the key words listed in 3 1 1 1 and 3 1 1 2 are formally reserved by the rules of FITS standard meanings for others may be adopted by general User s Guide Version 4 0 28 SECTION 3 FITS FUNDAMENTALS agreement Section 4 discusses a number of such keywords Conventions for keyword meanings can also be developed within a given discipline as has been done for high energy astrophysics radio interferometry and single dish radio observations Some of these conventions are discussed in section 5 Keywords should not be used in a way that conflicts with a generally accepted convention If the convention applies to all FITS files avoid using the keyword with a meaning other than that of the convention if the convention is discipline specific say to high energy astrophysics or radio astronomy a different meaning may apply to a different discipline Keyword meanings in conflict with widely accepted usage may confuse readers For keywords that have no value or are used to transfer text such as HISTORY COMMENT and REFERENCE the same keyword may be used repeatedly to extend text over a sequence of card images However repetition of a keyword with conflicting values may cause confusion There is no standard interpretation in such a case determining which value is to be retained as the true value of the keyword Different FITS readers may interpret the header differently Do not repeat a keyword on di
53. 6 4 Some Additional Software Resources FITS I O software written in IDL is available as part of the IDL Astronomy User s Library a central repository for general purpose astronomy procedures written in IDL including procedures to convert between spherical coordinates and plane map coordinates The library is not meant to be an integrated package but rather is a collection of procedures from which users can pick and choose for their own use Submitted procedures are given a cursory testing but are basically stored in the library as submitted The Astronomy User s Library is supported under the NASA Astrophysics Software Aids program The material is available through idlastro gsfc nasa gov home page html or at ftp idlastro gsfc nasa gov IP 128 183 57 82 The Astronomical Data Center ADC at NASA GSFC has developed a FITS Table Browser which has been tailored specifically for use with the ADC CD ROMs but may be used with other FITS ASCII tables It reads standard FITS ASCII tables and allows the user to browse through them interactively and selectively display any field or record in a table File extraction facilities permit writing all or part of the input table to disk in FITS or text file format It is available at ftp adc gsfc nasa gov pub adc software browsers ftb See the file ftb user guide txt for instructions on downloading installation and use The IUEDAC software which is written in IDL includes a FITS reader that can read pri
54. 7 World Coordinate Systems 61 4 1 Indexes and Physical Coordinates 63 4 0 Proposed Conventions a 00 se eee 64 4 2 1 Improved Axis Descriptions len 64 4 22 Sky Images clle 65 4 2 2 1 Pixel Regularization 65 4 2 2 2 Transforming to Projected Sky Coordinate 66 4 2 2 3 From Pixel to Physical Values 68 4 2 2 4 Deprojection l l a 68 4 2 2 5 Conversion to Standard Celestial Coordinates 70 4 3 Coordinate Keywords lll 71 4 4 Current Status aa a sas sas s esos sos eee 72 Advanced FTTS 75 5 1 Registered Extension Type Names 75 5 2 Conventions for Binary Tables TT 5 2 Variable Length Arrays cles 77 5 2 2 Arrays of Strings eee 80 5 2 3 Multidimensional Arrays in Binary Tables 82 5 2 3 1 TDIMn Keyword aaa a 82 NASA GSFC Astrophysics Data Facility CONTENTS vii 5 2 3 2 Green Bank Convention 82 5 2 4 Some Applications of Binary Tables 84 5 2 4 1 Replacing Random Groups 84 5 2 4 Multiple Arrays in One HDU 85 5 3 Hierarchical Grouping Proposal 85 5 4 STScI Inheritance Convention llle 89 5 5 Checksum Proposal 22e 90 5 6 Other Proposed Conventions 2 80 94 5 6 1 HEASARC nsn 94 5 6 1 1 Keywords
55. ADF NASA GSFC Astrophysics Data Facility A User s Guide for the Flexible Image Transport System FITS Version 4 0 April 14 1997 NASA GSFC Astrophysics Data Facility Code 631 NASA Goddard Space Flight Center Greenbelt MD 20771 USA Preface Since version 3 1 of A User s Guide for the Flezible Image Transport System FITS was published there have been several significant developments in the FITS community e The International Astronomical Union FITS Working Group IAUFWG has endorsed the image IMAGE and binary table BINTABLE extensions and the agreement on physical blocking e The proposal for treatment of world coordinate systems has been expanded and refined e number of conventions that are not part of the formal FITS rules have come into wide use e significant body of FITS resources has become available on the World Wide Web This new version of the User s Guide has been written to reflect those changes The discussion of the image extension and the rules for the binary table extension have been moved from section 5 Advanced FITS to section 3 FITS Fundamentals The papers describing the image and binary table extensions have now been published in the Astronomy and Astrophysics Supplement Series and are now considered to be among the fundamental FITS papers Section 4 on World Coordinates has been updated to include the refinements incorporated in the current proposals and it also discusses in greate
56. AMERA NASA GSFC Astrophysics Data Facility 125 33 card images of ASCII blanks User s Guide Version 4 0 126 APPENDIX A EXAMPLES OF FITS HEADERS Discussion of Example 2 M87 and Jet This header is based on the NRAO anonymous ftp collection of FITS files There have been some minor revisions none of which affect required or reserved keywords to bring the style into conformance with recommended practice Internal comments explain most of the keywords in detail The data following this header will consist of a 256 x 256 NAXIS1 NAXIS2 keywords matrix of 32 bit integers BITPIX keyword To derive the physical value represented the integer on the original FITS tape must be multiplied by 10 9 BSCALE keyword Array members pixels that contain a 2147483648 are to be treated as not containing real data values BLANK keyword The matrix represents KPNO video camera INSTRUME keyword pictures of M87 OBJECT keyword taken on the Mayall 4 meter telescope TELESCUP keyword The tape was created on 18 April 1980 DATE keyword The date of the observations is not given in this header if it were there would be a DATE OBS keyword Note that even though some of the character string values are more than eight characters long it is possible to obtain the essential information from reading only the first eight characters There are also five keywords that are neither required nor reserved FITS keywords those beginning with IPPS They
57. AS1 the type of data as EVENTS Examples of other types are SPECTRUM and GTI Good Time Intervals The usage of these two keywords follows OGIP HEASARC convention HDUCLASS identifies the source of the observation as one of NGC 4151 OBJECT keyword with the SIS1 instrument INSTRUME of the ASCA telescope TELESCOP with the principal investigator being I N Jones OBSERVER The ORIGIN CREATOR PROCVER SEQNUM and SEQPNUM keywords provide information on the origin of the file and User s Guide Version 4 0 152 APPENDIX A EXAMPLES OF FITS HEADERS its processing history The Instrument mode keywords provide information on the instrument and data configuration The Time Related Keywords except for the standard reserved DATE key word that identifies the file creation date as March 20 1996 give the time of observation The observation started at 57 seconds after 8 51 P M on December 5 1995 DATE OBS TIME 0BS and ended at 31 seconds after 4 06 A M on December 6 1993 DATE END TIME END Of these keywords DATE OBS is a reserved FITS keyword the others are user defined keywords but with names chosen by analogy with the reserved keyword In this case the DATE OBS keyword refers to the beginning of the observation but as noted in section 3 1 1 2 whether the DATE OBS keyword refers to the beginning middle or end of the observation is not specified by the FITS rules and must be described in the file as it is here The sta
58. AUFWG at the time this Guide is being written Also included in the table are the organization with current responsibility for the extension and its development and when available a reference describing the extension Table 5 2 explains the status codes in Table 5 1 The up to date official listing of extensions registered with the IAUFWG is available on line from the FITS Support Office at http ssdoo gsfc nasa gov astro fits xtension html or ftp nssdc gsfc nasa gov pub fits xtension lis This listing is revised as information is received from the IAUFWG about the registration of new type names or progress of a particular extension type through the approval process User s Guide Version 4 0 Type Name A3DTABLE BINTABLE COMPRESS DUMP ui iu gt FILEMARK IMAGE uu IUEIMAGE TABLE uu VGRDUPLu Status L Reference NRAO 1990 Cotton Tody and Pence 1995 Warnock et al 1990 none none Ponz Thompson and Mu oz 1994 Munoz 1989 Harten et al 1988 Jennings et al 1996 SECTION 5 Sponsor NRAO IAU GSFC A WWNW none NRAO IAU IUE IAU GSFC ADVANCED FITS Comments Prototype binary table design supported in AIPS superseded by BINTABLE which supports all A3DTABLE features Binary Tables Available at FITS Archives in files documents standards bintable for 1995 Feb 06 Note only main document excluding appendixes
59. Detector Y pixel scale mm pixel 06579102E 02 File mean optical axis X in sky coords pixels 69040405E 02 File mean optical axis Y in sky coords pixels 18277771E 02 Optical axis X in detector coords pixels 73833313E 02 Optical axis Y in detector coords pixels 23 00000000 Detector X field of view mm 23 00000000 Detector Y field of view mm 32 card images of blanks User s Guide Version 4 0 150 APPENDIX A EXAMPLES OF FITS HEADERS Discussion of Example 7 ASCA FITS Header This FITS table contains an event list of the X rays detected with the SIS1 detector on the ASCA X ray satellite during a particular pointed observation Each row contains data for a single photon and the table contains information for all the events in this particular observation Eleven different parameters are listed for each X ray event The header keywords supply additional information for deriving precise times or positions for each event This binary table XTENSION keyword BITPIX value of 8 NAXIS value of 2 GCOUNT value of 1 has 22990 rows NAXIS2 keyword consisting of 30 bytes NAXIS1 keyword distributed over 11 fields TFIELDS keyword and no variable length array heap PCOUNT In this example by contrast with examples 5 and 6 the keywords describing the structure of the table appear immediately after the required header keywords and the more general information follows The field titles TTYPEn are short upper case h
60. E on the TELESCOP keyword Cosmic Background Explorer COBE from the Cosmology Data Analysis Center ORIGIN keyword The primary header provides information that applies to all HDUs in the file There are no primary data NAXIS keyword the EXTEND keyword is set to true advising the reader that extensions may be present as indeed they are Since the primary HDU has no data the value of the BITPIX keyword does not matter as long as it is one of the permitted values This particular file was created on September 28 1994 DATE keyword but the original map file was created July 10 1994 DATE MAP keyword The map coordinates are for equinox 2000 EQUINOX keyword COBE specific keywords COMMENT show that the data cover a period from December 11 1989 DATE BEG through September 21 1990 DATE END and give the size of the region of space projected on to one pixel PIXRESOL DIRBE specific keywords COMMENT identify the PRODUCT the VERSION of the data reduction software the nominal intended wavelength WAVE9 and provide information about choices made in processing the data SOLELONG APPVEC and ZLREMOV The blank cards used as separators have an explicit COMMENT in contrast with the use of blank lines in Example 5 The COMMENT following the OBJECT keyword illustrates one approach to the problem of a keyword comment string that is longer than the 80 columns of a card image The binary table XTENSION keyword has 393216 row
61. ENDIX B IEEE FORMATS IAU 1988 Transactions of the IAU Twentieth General Assembly ed D McNally Dordrecht Kluwer IEEE 1985 American National Standard IEEE Standard for Binary Floating Point Arithmetic ANSLIEEE 754 1985 New York American National Standards Institute Inc Jennings D G Pence W D Folk M and Schlesinger B M 1996 A Hierarchical Grouping Convention for FITS preprint available electronically from http adfwww gsfc nasa gov other convert group html Munoz J R 1989 IUE data in FITS Format ESA IUE Newsletter 32 12 45 National Radio Astronomy Observatory 1990 Going AIPS Charlottesville VA National Radio Astronomy Observatory NOST 1995 Definition of the Flexible Image Transport System FITS NOST 100 1 1 Greenbelt NASA Goddard Space Flight Center Ponz J D Thompson R W and Munoz J R 1994 The FITS Image Extension Astron Astrophys Suppl 105 53 55 Seaman R and Pence W D 1995 FITS Checksum Proposal available in PostScript form at ftp iraf noao edu misc checksum checksum ps Warnock A Hill R S Pfarr B B and Wells D C 1990 An Extension of FITS for Data Compression draft preprint available electronically at http fits cv nrao edu 80 documents drafts Wells D C and Greisen E W 1979 A Flexible Image Transport System Proc 5th Colloquium Astrophysics eds G Sedmak M Capaccioli and R
62. HAT FITS IS 3 images The HDUs may be followed by special records the only restrictions on these special records are that they have the standard 23040 bit logical record size and that they not begin with the string XTENSION A FITS file is terminated by a logical end of file whose precise physical nature will depend on the medium In its original form a FITS file consisted solely of a single HDU consisting of the header and a data array that was regarded as containing a digital image This simple one HDU structure is known as Basic FITS The header card images would describe the data array the number and length of the axes and the data type of the values unsigned one byte signed two byte or four byte integers The original use of FITS to transport digital images is reflected in the Image in its name However even the data matrix of Basic FITS could be used to transmit any kind of multidimensional array not simply an image The first HDU of a FITS file called the primary HDU must still follow the Basic FITS format although it need not contain any data FITS is no longer restricted to integer arrays The array data may be Institute of Electrical and Electronics Engineers IEEE 32 bit or 64 bit floating point The Basic FITS primary HDU may be followed other HDUs called extensions containing different data structures Standard data formats include two kinds of tables tables with ASCII entries and tables with binary entries as wel
63. HDU with these keywords in a previously created data set making it impossible to identify the HDU uniquely For identification by position the numerical order of the HDU in the data set is specified Caution is required in the use of this method because the order of HDUs in a FITS file may be changed when the file is copied The location of group members not in the same file as the group table is specified by the World Wide Web Uniform Resource Identifier URI The table must specify the kind of URI being used Uniform Resource Locator URL Uniform Resource Name URN or any future form of URI The identification information is provided in columns of the group table with prescribed names given as values of the TTYPEn keyword The following keywords are used to define columns of the group table if all or some group members are identified by reference e TTYPEn MEMBER XTENSION is the heading for a column whose entries are character strings with the values of the XTENSION keyword for extensions that belong to the group For primary HDUs that are members the string PRIMARY is be used If no value is given as when the group table contains a mix of identifications by reference and by position and the HDU is identified by position an ASCII NULL hexadecimal 00 decimal 000 may be used e TTYPEn MEMBER NAME is the heading for a column whose entries are character strings with the values of the EXTNAME key word for group member extens
64. IS1 Blank columns may be included between fields a good practice that enhances readability NASA GSFC Astrophysics Data Facility 3 9 THE IMAGE EXTENSION 47 3 5 The Image Extension While multiple arrays of the same data type can be combined into a single array by adding another dimension there are cases where arrays related to the main data array may have different data types for example arrays of flags or weights Arrays of values with different data types can in principle be stored in the same file by making them different array fields in the same row of a binary table section 5 2 4 2 but in practice many find it simpler to put the arrays containing data types different from the primary data array in separate extensions For this purpose the IUE project developed the image extension type Ponz Thompson and Munoz 1994 3 5 1 Header The image extension follows the rules for required keywords in extensions stated in section 3 3 2 The first keywords of a FITS image extension header through GCOUNT must appear consecutively in the order listed below 1 XTENSION character has the value IMAGE for image extensions 2 BITPIX integer provides the number of bits per pixel value The values allowed are the same as those for the primary data array 3 NAXIS integer is for an image extension the number of axes in the extension data array A value of zero is acceptable and indicates that no data are associate
65. J Allan p 445 Wells D C Greisen E W and Harten R H 1981 FITS A Flexible Image Transport System Astron Astrophys Suppl 44 363 370 Wells D C and Grosbgl P 1990 Floating Point Agreement for FITS preprint available from FITS Support Office Zarate N and Greenfield P 1996 A FITS Image Extension Kernel for NASA GSFC Astrophysics Data Facility 159 IRAF Astronomical Data Analysis Software and Systems V eds G H Jacoby and J Barnes pp 331 334 User s Guide Version 4 0
66. MENT COMMENT COMMENT COMMENT TTYPE2 TUNIT2 TFORM2 141 393216 Number of rows Number of bytes of data following table Group count always 1 for bintable extensions Number of fields columns in the table NRO 0GIP 93 003 OGIP memo number where the convention is described The times reported in this file are atomic seconds elapsed since 00 00 00 UTC 1 January 1981 Time information is recorded in a manner consistent with the convention specified in OGIP 93 003 with the understanding that time is counted in atomic seconds and the origin of time MJDREF is quoted in ephemeris MJD 1981 00 time system same as IRAS 44605 Integer portion of ephemeris MJD corresponding to Oh UTC 1 Jan 1981 0 00059240741 Fractional portion of ephemeris MJD corresponding to Oh UTC 1 Jan 1981 s unit for TSTART TSTOP TIMEZERO seconds 282185275 611 observation start time in TIMESYS system 306753235 358 observation stop time in TIMESYS system kk kk ke ok ke ke ok ke ok ok ok ok ke ok ke ke ok ok 9k 9k 9k ooke ke ke R R ke ok 9k 9k I I 9k ICC ok ok ook ke ok a K 9k 3k ICCC FE aK R aK gt K 3K 8 Annual Average Sky Map 140 microns Mission averaged photometric measurements and cumulative Sky coverage data for DIRBE Band 9 140 microns The photometry is computed from the weighted average of all available weekly averaged maps for the entire mission up to the time when the cryogen supply was exhausted The
67. ND keywords in any order e TTYPEn character is the heading for field n The recommended characters are letters digits and underscore Upper case values are preferred but lowercase letters may be used and string comparisons involving the values of TTYPEn keywords should not be case sensitive The hyphen is permitted but not recommended While more than one field may have the same heading value of TTYPEn the practice is not recommended e TUNITn character is the physical units of field n The rules governing the units to be used in ASCII tables are the same as those for a primary data array as given in section 3 1 1 4 User s Guide Version 4 0 46 SECTION 3 FITS FUNDAMENTALS e TSCALn floating is the scale factor for field n as applied in equation 3 11 The default value is 1 0 e TZEROn floating is the offset for field n see equation 3 11 The default value is 0 0 Physical_value Stored value x TSCALn TZEROn 3 11 Note TSCALn and TZEROn may not be used for A format fields e TNULLn character is the representation of an undefined value The string chosen does not have to be readable in the format specified by TFORMn for example a null value of might be used for an 3 field If the null string given as the value of the keyword does not fill the field it is assumed to begin at the start of the field and the part of the field following the string is assumed to be filled with blanks A table wi
68. NSION 45 e TFORMn character is the FORTRAN format of field n I A E D F To repeat a field the format must be repeated using separate TFORMn and TBCOLn card images the repeat count e g 2Fx x of FORTRAN cannot be used The TFORMn values specify the width of the field and are of the form Iw Aw Fw d Ew dEe or Dw dEe integers characters single precision floating point single precision exponential and double precision exponential respectively The w is the width of the field d the number of digits after the decimal point and e is the number of digits in the exponent as in FORTRAN For integer fields if 0 needs to be distinguished from 0 e g degrees of declination the sign will have to be a separate character field It is better to use floating point TBCOLn and TFORMn keywords must be present for values of n from 1 to the value of TFIELDS END is always the last keyword the remainder of the header record is filled with ASCII blanks 3 4 2 Reserved Keywords for ASCII Table Extension These keywords may be used in addition to the required keywords described in section 3 4 1 to describe the structure of ASCII table data They are not required but if they are used in an ASCII table header they must be used as described here These keywords should not be used in other extensions unless they have a function analogous to the one they have in the ASCII table extension They may appear anywhere between the TFIELDS and E
69. Num0bs from the Weekly Averaged Map as the weight such that annual_average sum weekly_average weekly_weight sum weekly_weight The photometric measurement is given as a spectral intensity I nu in MJy sr and is quoted at the nominal wavelength for a source with nu I nu constant i e a color correction is required if the source spectrum differs from nu I nu constant Data which have been replaced by flagged values in processing have values LE 16375 Photomet entire fieldname Photometry PMJy sr 4E E The standard deviation of the weighted average photometry values StdDev entire fieldname Standard deviation PMJy sr 4E Sum of the weekly weighted number of observations that went into forming the annual averages gt WtNumObs entire fieldname Weighted_num_obs E E 1I E Sum of the total number of observations available regardless of assigned weight SunNRecs entire fieldname Sum numrecs NASA GSFC Astrophysics Data Facility 143 TUNIT7 TFORM7 1J COMMENT END 20 card images of ASCII blanks User s Guide Version 4 0 144 APPENDIX A EXAMPLES OF FITS HEADERS Discussion of Example 6 DIRBE FITS Headers These primary and binary table headers are for an all sky map OBJECT keyword from the INSTRUME keyword Diffuse Infrared Background Explorer DIRB
70. OF THE FIELD FORMAT NULL VALUE NAME OF ROW BEGINNING COLUMN OF THE FIELD FORMAT NULL NAME User s Guide Version 4 0 128 TTYPE4 TBCOL4 TFORM4 TNULL4 TTYPE5 TBCOL5 TFORMS5 TNULL5 TTYPE6 TBCOL6 TFORM6 TNULL6 TTYPE7 TBCOL7 TFORM7 TNULL7 END 35 card images of ASCII blanks TYPE E14 7 p25 7E14 7 INCL 7E14 7 RV 7E14 7 APPENDIX A EXAMPLES OF FITS HEADERS 43 57 71 85 NASA GSFC Astrophysics Data Facility SNM YOP ILI YS YNNN YNNN YNNN YNNN YNNN YNNN YNNN YNNN YNNN YNNN YNNN YN YS NAME OF RDW BEGINNING COLUMN OF THE FIELD FORMAT NULL VALUE NAME OF RDW BEGINNING OF COLUMN OF THE FIELD FORMAT NULL VALUE NAME OF RDW BEGINNING COLUMN OF THE FIELD FORMAT NULL VALUE NAME OF RDW BEGINNING COLUMN OF THE FIELD FORMAT NULL VALUE 129 Discussion of Example 3 A Galaxy Catalog in an ASCII Table This pair of headers illustrates the case where all the data are in an extension Like Example 2 it is from the NRAO ftp collection It is a catalog of galaxies probably of parent galaxies of supernovae 0BJECT keyword originating at the European Southern Observatory ORIGIN keyword and comments It was created on 27 May 1984 DATE keyword and thus may not show how ESO MIDAS would now write an ASCII table but it can still illustrate the format The primary header carries two additional pieces of information that there is no primary data array value of
71. S_MODE DATAMODE DATE DATE OBS TIME OBS DATE END TIME END MJD OBS MJDREF TIMEREF TIMESYS TIMEUNIT TSTART TSTOP TELAPSE ONTIME EXPOSURE CLOCKAPP TASSIGN TIMEDEL TIMEZERO ORBITBEG ORBITEND RADECSYS EQUINOX RA_NOM DEC_NOM RA_PNT DEC_PNT PA_PNT RA_PNTE DEC_PNTE PA_PNTE TCRPX3 TCRPX4 TCRVL3 TCRVL4 TCDLT3 TCDLT4 TCTYP3 TCTYP4 TCRPX8 TCRPX9 APPENDIX A EXAMPLES OF FITS HEADERS 1894 Modal Configuration ID gt HIGH gt Telemetry rate POINTING Observation mode BRIGHT2 file generated by FAINT Time Related Keywords 20 03 95 FITS file creation date dd mm yy 05 12 93 date of observation start dd mm yy 20 51 57 time of observation start hh mm ss 106 12 93 date of observation end 04 06 31 time of observation end 4 9326869420E 04 Modified Julian date of the data start time 48988 0 MJD corresponding to SC clock start 1993 0 LOCAL Barycentric correction not applied to times 1993 0 Time measured from 1993 Jan 1 00 00 UT s unit for time related keywords seconds 2 92783178528423011303E 07 time start 93043917384999990463E 07 time stop 60738856576979160309E 04 Elapsed time TSTOP TSTART 92793133954703807831E 03 sum of the good time intervals 92793133954703807831E 03 Exposure F Is mission time corrected for clock drift SATELLITE location of time assignment 8 0000000000E 00 time increment or time resol
72. Science Data Operations Office and one from NASA Headquarters and an outside astronomer The role of this panel is to review the process of developing the standard whether the steps taken to publicize the availability for review were adequate to reach the entire interested community whether the technical panel replies addressed all the reviewers points and whether the resulting Proposed Standard represents a consensus of the community Version 1 0 of the standard covered the rules in the first four FITS papers and the floating point agreement There were three technical panel review cycles On June 18 1993 the accreditation panel voted to approve the Definition of FITS as the NOST standard for the use of FITS Questions about the specifications of units led to the development of a revision version 1 1 There was only one review cycle the number of comments was small and the community members present at the 1995 business meeting of the Working Group on Astronomical Software agreed that this lack of comments reflected general satisfaction with these changes Version 1 1 was approved by the accreditation panel on June 14 1995 The NOST Definition has been submitted to the chair of the IAUFWG as the start of the process of seeking endorsement of the NOST document as the international standard for FITS In the ongoing electronic discussions of FITS FITS rules are frequently quoted in the form in which they are expressed in the NOST document A t
73. XTENSION character indicates the type of extension This keyword must appear on the first card image in the header With this keyword at the front any software can immediately read the extension type and determine whether or not it is a type that the software can handle BITPIX integer gives the number of bits per pixel value The values allowed are the same as those for the primary data array NAXIS integer gives the number of axes or analogous structures a value of zero is allowed which indicates there are no data records in the current extension The maximum possible value is 999 Negative values are not allowed NAXISn n 1 NAXIS integer NAXISn 0 for any n implies that the extension has no data is the number of array elements along the nth axis or its analog In order to allow FITS readers that are unfamiliar with an extension to skip it a header must specify the size of the extension in bits To do so two parameters PCOUNT and GCOUNT are defined in the header e PCOUNT integer The value may be zero Note that although this keyword originated in the Random Groups section 3 2 rules the interpretation for an extension may be different GCOUNT integer If simple image like data e g a table are being written its value will be 1 The PCOUNT and GCOUNT keywords may appear anywhere between the last NAXISn or NAXIS 0 keyword and the END keyword The best place is immediately
74. a Start column Fortran format Units are arcseconds per year Scale factor Annual proper motion in DEC Start column Fortran format Units are arcseconds per year Scale factor PM_DEC If the calculated value for PM_RA_COSD or PM_DEC exceeded the PM_DEC capacity of the field a value of 9999 is given EPOCH_DIFF 48 I4 yr H 0 01 BD H 52 AT H BD_COMP 59 I1 H 20 H pISC SUM 60 I2 H Difference in epoch AGK3 AGK2 Start column Fortran format Units are years Scale factor Bonner Durchmusterung number Start column Fortran format Numerical code for component of multiple system Start column Fortran format Null value Sum of discrepancy codes see comment Start column Fortran format DISC SUM The sum of discrepancy codes or the sum of 2 V where 0 BD number 1 PMAG and or spectral type 2 RA of DISC SUM AGK2 3 DEC of AGK2 4 RA of AGK3 5 DEC of AGK3 DISC SUM V PM RA I6 s yr RA_RESID I6 Annual proper motion in R Start column Fortran format Units are seconds of time per year Scale factor Residual value in RA Start column Fortran format NASA GSFC Astrophysics Data Facility TUNIT21 TSCAL21 TTYPE22 TBCOL22 TFORM22 TUNIT22 TSCAL22 END 1 card arcsec 0 0001 pEC RESID 74 I6 3 arcsec 0 0001 image of ASCII blanks
75. able exclusive of null or fill values e TDMINn is the minimum value in column n of a table exclusive of null or fill values e TLMAXn is the maximum permissible value in column n of a table e TLMINn is the minimum permissible value in column n of a table For example if the third column in a table of positions was declination then the following keywords might be present TTYPE3 TFORM3 TUNIT3 TLMAX3 TLMIN3 TDMAX3 TDMIN3 gt DEC d 1E DEGREES 90 00 90 00 46 00 63 10 HEASARC also recommends the following restrictions when these keywords are used e The data type of the keyword value should be the same as that of the data in the column it describes e The keywords are to refer to all elements of a vector column e As with DATAMAX and DATAMIN the keywords apply to the values after any scaling prescribed by the values of the TZEROn and TSCALn keywords has been applied e Values of TDMINn less than those of TLMINn and values of TDMAXn greater than those of TLMAXn are permissible the meaning is not defined in this convention e If the value of the keyword for the maximum is less than that of the value of that for the minimum then the values are taken to be undefined NASA GSFC Astrophysics Data Facility 5 6 OTHER PROPOSED CONVENTIONS 99 5 6 2 World Coordinates in Tables Primary data arrays and image extension arrays are not the only way in which maps may be defined in FITS files The
76. ader and data of each HDU are treated as a series of 32 bit words Checksums are calculated by adding these words using ones complement arithmetic to yield a 32 bit integer First the ones complement checksum of the data records is calculated The unsigned integer result is then formatted as a string and put in the value of the DATASUM keyword For example if the checksum of the data records is the unsigned integer 2503531142 then the DATASUM keyword in the header will appear as DATASUM u 2503531142 The checksum keyword in the header is then set to an encoded ASCII zero CHECKSUM 0000000000000000 The ones complement checksum of the header is then calculated including the CHECKSUM and DATASUM keywords with the above values and the already calculated data checksum is added to it yielding a checksum for the entire HDU The bit complement of the total which is its ones complement additive inverse is then calculated such that User s Guide Version 4 0 92 SECTION 5 ADVANCED FITS original checksum bit complement 0 This bit complement is then ASCII encoded As part of the encoding process an encoded ASCII zero is added encoded complement bit complement ASCIL zero This encoded complement replaces the original value of the checksum keyword the ASCII zero in effect subtracting it out new checksum original checksum encoded complement ASCIL zero original checksum bit complement 0 T
77. advises that a tape may be blocked with more than one logical record per physical block A value of F has no meaning Its significance is now primarily historical and is discussed further in section 3 8 However because the keyword name BLOCKED has been reserved it cannot be used for any other purpose Other keywords signal a card image with comments or other text e Columns 1 8 blank no keyword means columns 9 80 are a comment e COMMENT none means columns 9 80 are a comment e HISTORY none means columns 9 80 are a comment This keyword is intended for use when the associated text discusses the history of how the data contained in the array were processed in column 9 These keywords are the only ones without values that can have Users may define other keywords to contain comments as well For these keywords column 9 may not contain The reason this restriction does not apply to the COMMENT HISTORY and uuuuuuuu keywords is principally historical the original FITS paper defined columns 9 80 as being a comment and did not restrict the content For the COMMENT HISTORY and blank field keywords the reader will be able to tell by the keyword name that there is no value However for user defined keywords the reader has no other way of telling a priori whether the field has a value or not To minimize confusion it is best to avoid in column 9 even after COMMENT HISTORY and blank keyword fields as well 3
78. after the last NAXISn keyword the existing standard extensions require that location but otherwise software to read FITS files should not assume they will be there They may be defined in any way that along with the BITPIX NAXIS and NAXISn values gives the correct data size using the following formula to derive NBITS the number of bits excluding fill NBITS ABS BITPIX x GCOUNT x PCOUNT NAXIS1 x NAXIS2 x x NAXISm 3 9 where m is the value of NAXIS NBITS may not be negative NASA GSFC Astrophysics Data Facility 3 3 EXTENSIONS 41 The number NRECORDS of data records following the header record is then given by NRECORDS INT NBITS 23039 23040 3 10 Rules for individual extensions may place further restrictions on the position of the PCOUNT and GCOUNT keywords END is always the last keyword in a header The remainder of the record following the END keyword is filled with ASCII blanks The data begin at the start of the first record following the last record of the header 3 3 2 Reserved Keywords for Extension Headers These keywords are not required but if used must have the meaning and syntax defined here They may appear anywhere between the required keywords and the END keyword These keywords are reserved for all extension headers and need not be specifically reserved for an individual new extension e EXTNAME character can be used to give a name to the extension to distinguish it from other
79. answer questions about specific issues and problems not covered in the on line material For NASA projects the FITS office also reviews whether proposed designs for FITS data sets and software conform to the FITS rules and recommended practices designs from other organizations may be reviewed if they appear to be of wide community interest From the kinds of inquiries received the FITS office can develop a sense of the common questions about the existing standard formats the problems with them and what data structures if any these formats do not handle well This experience enables the FITS office to provide recommendations on directions for FITS development to the IAU FITS Working Group and the regional FITS committees and to work with developers of User s Guide Version 4 0 108 SECTION 6 RESOURCES potential new extensions and conventions The FITS Support Office is coordinated by Dr Barry M Schlesinger a member of the IAUFWG whose research background is in the areas of stellar structure and evolution and variations in solar radiation The FITS office can be reached by telephone at 4 1 301 286 2899 6 1 1 On line Information The FITS Support Office maintains World Wide Web and ftp sites at Goddard Space Flight Center The FITS Support Office home page is at http ssdoo gsfc nasa gov astro fits fits home html It describes the on line material available from the FITS Support office and provides links both to the available h
80. applies In this way even though a particular keyword might be used differently in different contexts the applicable context could be identified The same problem can arise in naming table column headers as when choosing keyword names different groups may use the same column headings with different meaning Again some method of defining project specific meanings for the table headings is needed The proposal to use the ORIGIN TELESCOP and INSTRUME keywords as domain limiters works here too These keywords could be either in the primary header of the file or the individual extension header Including these keywords in the extension headers has the disadvantage that they will be repeated from header to header using extra space but it has advantages the domain indicators appear as keywords in the same header as keywords giving the column labels they describe and they will remain associated with the table should for some reason the table but not the primary header be copied from the FITS data set to another say to a data set with a different primary header The additional information gained by including domain keywords in each extension thus appears worth the small extra overhead One possible problem that has been suggested for this approach is that some local software systems might rearrange keyword order when reading the FITS file into an internal format structure and so lose the domain information If this approach is used keyword order s
81. ar in the order given below All except SIMPLE must appear in other headers as well in the same order The value field must appear in the fixed format described in section 3 1 1 User s Guide Version 4 0 22 SECTION 3 FITS FUNDAMENTALS SIMPLE logical A value of T signifies that the file conforms to FITS standards A value of F is used for files that resemble FITS files but depart from the standards in some significant way One example would be files where the numbers are in the DEC VAX internal storage format rather than the standard FITS most significant byte first The FITS files produced by some hardware that contain non standard data formats such as two byte unsigned integers or give the month number before the day number in date formats are another example Such files might be convenient for internal use by a particular organization or for exchange between users with the same hardware for whom convenience is more important than standardization when they wish the files to have an overall FITS like structure No installation should use them as the standard format for communication with outside users Files with SIMPLE F should not be described as FITS files BITPIX integer describes how an array value is represented 8 ASCII characters or 8 bit unsigned integers 16 16 bit twos complement signed integers 32 32 bit twos complement signed integers 32 IEEE 32 bit floating point values 64 IEEE 64
82. ated although display is not as direct as for ASCII tables In developing the binary table design a provision was made that a particular field or entry in the table could be a vector not just a single number The resulting binary table extension Cotton Tody and Pence 1995 hereafter CTP was endorsed by the IAUFWG in 1994 Like an ASCII table a binary table contains a two dimensional data matrix mapped into the rows and columns of a table The entries the values associated with a given row and column are stored in one of several prescribed binary formats rather than coded into ASCII For each field there is a repeat count which is one for a single entry and larger if the entry is to be a vector This main table may be followed by additional data Appendixes to the paper proposed three additional conventions one to handle fields where the length of an array might vary one to allow the vector in a field to be interpreted as a multidimensional array and one for delimiting arrays of strings While the Working Group endorsement of binary tables did not include NASA GSFC Astrophysics Data Facility 3 6 BINARY TABLES 49 these conventions the rules that were adopted reserved a number of keywords and values specifically intended for use by these conventions These conventions are discussed in section 5 2 In a binary table each row consists of a series of entries in formats specified by the header keywords The header describes the size an
83. ays although the convention itself is not part of the formal proposal The basic concept is that the data for variable length arrays are not stored physically in the main table but in a heap area that follows the table This heap area takes up part of or all of the space following the main table reserved by the PCOUNT keyword in the header At the entry in the table where the array would be located there is instead an array descriptor or pointer which tells the user or software e where the data to be logically included as that entry of the table are to be found in the heap e the size of the data The data identified in the heap are treated as if actually located in that entry of the table instead of in the heap Since an array descriptor has a single standard size all rows in the main table will have the same length This structure allows software that is unable to handle variable length arrays to read the rest of the main table and then use the value of PCOUNT in the header to move on to the next extension when it has finished reading the fixed length entries in the table Variable length arrays may be of any of the data types used in binary tables except array descriptor and may be multidimensional The value of the TFORMn keyword in the header which has the form rPt maxelem identifies the data type t of the array to be logically included in field n and specifies the largest number of elements the array can have maxelem in any
84. be expected by some FITS readers the BLOCKED keyword was introduced as an indicator that there might be more than one logical record per physical block on a tapes However usage was not universal therefore absence of the BLOCKED keyword therefore did not guarantee single record blocks and by its definition its presence did not guarantee multiple record blocks It could thus not be used effectively as intended As the multiple record block became established as standard and with the rise of the concept of FITS as a purely logical structure NASA GSFC Astrophysics Data Facility 3 8 FITS FILES AND PHYSICAL MEDIA 59 the need for a BLOCKED keyword has disappeared Information describing how a tape is blocked should be sent with it and users should ask for blocking information when receiving tapes The keyword itself should no longer be used as a blocking indicator but it remains formally reserved for its original purpose and should also not be used for any other The rules for the BLOCKED keyword also were in conflict with other rules in FITS This keyword was required to be in the first logical record however if the value of NAXIS was greater than 33 or 32 when EXTEND was present it could not be put in the first record without violating the rule that the NAXISn keywords must be consecutive Conventions for writing a FITS file on more than one physical unit tape disk are only now being developed In the original FITS paper Wells
85. by the header pixel numbers increasing with the index along axis 1 varying most rapidly and the index along the last axis varying least rapidly Data are packed into the 2880 byte records with no gaps Each entry in the array immediately follows the preceding entry the first pixel of any given axis does not necessarily appear in the first word of a new record If the last member of the data array is not at the end of a record the remaining bits of the record are filled with zeroes corresponding to 0 integer or 0 0 floating point The bytes in each word are in order of decreasing significance with the sign bit first Thus INTEL and VAX machines will have to reverse the order of the bytes in 16 and 32 bit integers and make the appropriate conversions between IEEE floating point and internal storage order before writing or after reading Numbers are stored in twos complement form conversion will be required for User s Guide Version 4 0 30 SECTION 3 FITS FUNDAMENTALS ones complement machines The data type of the array members may be any type corresponding to a valid value of BITPIX unsigned eight bit integers or characters signed 16 or 32 bit integers or single or double precision IEEE floating point Proposals to add 16 and 32 bit unsigned integer types have been discussed from time to time but a consensus in favor of these proposals has not developed Data with the numerical range corresponding to unsigned integers can be
86. cant bit Three keywords are reserved for this proposal e CHECKSUM character is a 16 character string containing an ASCII encoding of the ones complement of the checksum of the HDU calculated with the value of the CHECKSUM keyword set to 0000000000000000 ASCII 0s or hexadecimal 30s before the checksum is computed NASA GSFC Astrophysics Data Facility 5 5 CHECKSUM PROPOSAL 91 e DATASUM character is a character string containing the unsigned integer value of the checksum of the data of the HDU formatted as a string The string formulation is used because FITS does not support unsigned integer keyword values If the HDU has no data the value field may be set to 0 preferred or the keyword is omitted The single digit is used in the value field to distinguish it from an actual zero data checksum Absence of a DATASUM key word implies no knowledge of the checksum of the data records e CHECKVER character is a character string that identifies the checksum algorithm used The algorithm defined by Seaman and Pence has the identification COMPLEMENT and is the default value Development of future algorithms should be coordinated within the community and governed by a registry under the IAUFWG like the one for extension type names described in section 3 3 It is recommended that this keyword appear only if an algorithm other than the default COMPLEMENT algorithm is used For purposes of calculating the checksum the he
87. cations in other areas number of these conventions are discused in Section 5 6 1 HEASARC material is available through their World Wide Web page at http heasarc gsfc nasa gov It is also available at ftp legacy gsfc nasa gov HEASARC has developed two major software packages FITSIO is a machine independent subroutine interface for reading or writing FITS files By using these subroutines the programmer can avoid having to deal directly with the internal details of the FITS file FITSIO supports all the standard FITS file formats discussed in section 3 Some of the functions performed are opening and closing files reading writing or modifying header keywords and reading or writing any element of a FITS data array or table It also includes the VERIFITS program to verify that a FITS file conforms to the FITS standard In addition to supporting the standard FITS formats VERIFITS supports the variable length array convention discussed in section 5 2 1 There are FITSIO versions in portable FORTRAN 77 and in ANSI C Both versions run on Sun DECstations VAX VMS DEC Alpha VMS and OSF 1 SGI HP NeXT IBM PCs DOS and Linux Amiga PCs and Macintosh PCs the FORTRAN version runs on Cray supercomputers and IBM mainframes as well FITSIO requires random access I O to the file and therefore does not support direct read or write access to sequential devices such as magnetic tape drives FITSIO source code and documentation are available
88. column numbers They are not part of FITS headers 00000000011111111112222222222333333333344444444445 55b555555666666666 12345678901234567890123456789012345678901234567890123456789012345678 SIMPLE T BITPIX 16 NAXIS 4 NAXIS1 2048 NAXIS2 1024 NAXIS3 1 NAXIS4 1 EXTEND T TABLES FOLLOWING MAIN IMAGE BLOCKED T FILE MAY BE BLOCKED OBJECT 3C405 SOURCE NAME TELESCOP INSTRUME OBSERVER PERL DATE OBS 27 10 82 OBSERVATION START DATE DD MM YY DATE MAP 14 07 83 DATE OF LAST PROCESSING DD MM YY BSCALE 7 04625720812E 05 REAL FITS_VALUE BSCALE BZERO User s Guide Version 4 0 122 APPENDIX A EXAMPLES OF FITS HEADERS BZERO 2 18688869476E 00 BUNIT JY BEAM UNITS OF FLUX EPOCH 1 950000000E 03 EPOCH OF RA DEC DATAMAX 4 495524406E 00 MAX PIXEL VALUE DATAMIN 1 217470840E 01 MIN PIXEL VALUE CTYPE1 RA SIN CRVAL1 2 99435165226E 02 CDELT1 4 166666986E 05 CRPIX1 1 024000000E 03 CROTA1 0 000000000E 00 CTYPE2 DEC SIN CRVAL2 4 05961940065E 01 CDELT2 4 166666986E 05 CRPIX2 5 130000000E 02 CROTA2 0 000000000E 00 CTYPE3 FREQ CRVAL3 4 86635000000E 09 CDELT3 1 250000000E 07 CRPIX3 1 000000000E 00 CROTA3 0 000000000E 00 CTYPE4 STOKES CRVAL4 1 00000000000E 00 CDELT4 1 000000000E 00 CRPIX4 1 000000000E 00 CROTA4 0 00000000
89. d the proposal any modifications have been made and the format has been successfully used for data transport the proposal is submitted for approval to the regional committees the European FITS Committee the Japanese FITS Committee and the American Astronomical Society Working Group on Astronomical Software WGAS FITS Committee Following approval by the regional committees it is submitted to the IAUFWG Approval by the Working Group establishes it as a standard extension number of aspects of this process are worth noting First FITS formats have been developed through the efforts of individuals responding to particular practical problems Although there is extensive community review most of the initial detailed development is done by the people who actually need to use a format for a particular purpose rather than by a formal committee new format must be demonstrated to work in practice through actual data transport before it can be approved as standard ensuring that the standard is not purely theoretical but has actually been used Finally the approval process occurs by community consensus as is customary in the world of standards NASA GSFC Astrophysics Data Facility 17 Section 3 FITS Fundamentals 3 1 Basic FTTS The fundamental unit of a FITS data set is the file which begins with the ASCII string SIMPLE T where the first 6 bytes of the file contain SIMPLE the is in byte 9 the T is in byte 30 and th
90. d data type of each entry and optionally provides a label units and the representation for an undefined value where applicable The length and field structure of all rows of the main table in a particular binary table extension must be the same Every row in a particular binary table contains the same number of entries although the number can vary from one binary table extension to the next in a FITS file The header is a standard FITS extension header For each table entry it specifies 1 The size and data type of the entry 2 A label optional 3 The units optional 4 The representation of an undefined value optional An entry may be omitted from the table but still defined in the header by using a zero repeat count in the value of the TFORMn keyword Examples 4 6 and 7 in Appendix A illustrate binary tables 3 6 1 Required Keywords for Binary Table Extension Headers The extension follows the rules for required keywords stated in section 3 3 2 The first eight keywords must appear consecutively in the following order 1 XTENSION character has the value BINTABLE for binary table extensions 2 BITPIX integer must have a value of 8 A binary table is an array of bytes User s Guide Version 4 0 50 SECTION 3 FITS FONDAMENTALS 3 NAXIS integer must have a value of 2 for binary table extensions As with ASCII tables the axes are the rows and columns of the table 4 NAXIS1 integer has a value eq
91. d with the current header The maximum possible value is 999 Negative values are not allowed 4 NAXISn n 1 NAXIS NAXIS 0 gt NAXIS1 not present integer is the number of elements along axis n of the array The NAXISn keywords in an image extension are governed by the same rules as those in a primary header 5 PCOUNT integer has the value 0 for image extensions 6 GCOUNT integer has the value 1 for image extensions the other keywords follow until User s Guide Version 4 0 48 SECTION 3 FITS FUNDAMENTALS END no value The last keyword must be END This card image has no in column 9 or value field but is filled with ASCII blanks The remainder of the last header record should be filled with ASCII blanks Note that while the rules for generalized extensions do not specify where the PCOUNT and GCOUNT keywords are located between the last NAXISn and the END keywords the image extension rules require that they appear immediately after the last NAXISn card image 3 5 2 Data Records The rules for the data in image extensions are the same as for the primary data array section 3 1 2 An image extension header cannot be followed by random groups records 3 6 Binary Tables With the development of the IEEE 754 standard for floating point numbers it became possible to incorporate binary values in tables Tables with binary values are more compact and the time spent converting from ASCII is elimin
92. decreasing order of significance A Character strings consist of 8 bit ASCII characters in their natural order An ASCII NULL hexadecimal 00 character may be used to terminate a character string before the length specified by the repeat count is reached Strings occupying the full length of the field are not NULL terminated An ASCII NULL as the first character signifies a NULL undefined string The printable ASCII characters that is those in the range hexadecimal 20 7E and the ASCII NULL after the last valid character are the only ones permitted User s Guide Version 4 0 56 SECTION 3 FITS FUNDAMENTALS E Single precision floating point values are in IEEE 32 bit precision format as described in section 3 1 2 3 D Double precision floating point values are in IEEE 64 bit precision format as described in section 3 1 2 3 C A complex value is composed of a pair of IEEE 32 bit floating point values the first is the real part and the second the imaginary part M A double precision complex value is composed of a pair of IEEE 64 bit floating point values the first is the real part and the second the imaginary part P An array descriptor consists of two 32 bit twos complement integer values For the floating point types E D C and M the IEEE NaN values represent undefined or null values a value with all bits set is recognized as a NaN AII IEEE special values are recognized infinity NaN and denormalized numbers If e
93. du fits This site also supports a WAIS server named nrao fits which has an index of all of the FITS related text files in the archive the file nrao fits src is available at think com and at ftp fits cv nrao edu fits wais sources nrao fits src as well as through the NRAO FITS Web site The documents directory contains a number of subdirectories with various FITS documents The formats of the documents depend upon the size Some small documents are available in ASCII text Larger documents are in PostScript and often in IATEX The largest documents will also have gzip compressed PostScript versions as well The standards subdirectory contains copies of the NOST standard described in section 6 1 2 text of the agreement on physical blocking and copies of preliminary drafts of the binary table and image extension papers The overviews subdirectory contains electronic copies of this User s Guide and some FITS history The proposals subdirectory is for proposals that are ready User s Guide Version 4 0 114 SECTION 6 RESOURCES for consideration by the FITS committees The drafts subdirectory contains drafts for extensions or conventions that may or may not be submitted to the FITS committees at a future time The wcs subdirectory contains the current draft proposal for world coordinates conventions Greisen and Calabretta 1996 draft conventions for world coordinates keywords that would be used in conjunction with this proposal some earlier d
94. e intervening bytes contain ASCII blanks This 30 character string is the signature of FITS the way in which generalized software can identify the file as FITS The string is not to be used if the file deviates from the rules for FITS in any way In such a case a value of F may be appropriate A FITS file ends with an end of file mark appropriate to the medium on which it is written A FITS file is composed of 23040 bit 2880 8 bit byte logical records organized into a sequence of header data units HDUs This logical record length was chosen because it was an integral multiple of the byte and word lengths of all computers that had been sold in the commercial market in or before 1979 the time of the original FITS agreement Each HDU consists of one or more logical records containing an ASCII header followed by zero or more records of binary data The first HDU is called the primary HDU those following are called extensions The last extension may be followed by 23040 bit special records which need not be organized as HDUs Each FITS header record consists of 36 80 byte card images written in 7 bit printable ASCII code ANSI 1977 with the sign bit set to zero The header may contain as many records as are needed for the card images The END card image is the last The remainder of the last record of the header is filled with ASCII User s Guide Version 4 0 18 SECTION 3 FITS FUNDAMENTALS blanks to its full 23040 bit length These
95. e last record of the main table if there are additional data this record will be the last record of the additional data The data types are defined as follows L A logical value consists of an ASCII T indicating true or F indicating false A null character zero byte signifies an invalid value X A bit array starts in the most significant bit of the byte and the subsequent bits are in the order of decreasing significance in the byte A bit array field in a binary table consists of an integral number of bytes with those bits that follow the array set to zero No specific null value is prescribed for bit arrays but the following three conventions are suggested e Designate one bit of the array to be a validity bit e Add a type L field to the table to indicate the validity of the bit array e Add a second bit array which contains a validity bit for each of the bits of the original array Use of any of these conventions will be a decision of an individual project or particular group of FITS users Do not expect that general software to read FITS will necessarily be able to interpret them B An unsigned 8 bit integer has the bits in decreasing order of significance By applying scaling this field may be used to store quantities whose physical values are signed I A 16 bit integer is a twos complement integer with the bits in decreasing order of significance J A 32 bit integer is a twos complement integer with the bits in
96. e or image extensions requires a floating point value and developers of new extensions might be well advised to avoid required keywords with floating point values Many reserved keywords have floating point values but there is no standard practice or recommended procedure for handling floating point values with too many digits to fit in 20 columns When the fixed format is not used the value field must be written in a notation consistent with the list directed read operations in FORTRAN 77 With the exception of complex numbers all the fixed formats follow the rules for FORTRAN 77 list directed read Such a notation has the following requirements for the different formats Logical The first non blank character in columns 11 80 is T or F e Character string Begins with a in column 11 or later and ends with a no later than column 80 with the string in between Starting in column 11 only blanks are permitted in the value field before the opening quote To include a single quote within a character string use two successive single quotes for example O Hara becomes 0 HARA Leading blanks in a string are significant trailing blanks are not e Integer May occupy any of columns 11 80 e Floating May occupy any of columns 11 80 The decimal point must always appear explicitly whether or not exponential notation is used When exponential notation is used all letters e g E indicating an exponential mu
97. e relative URI may be used instead of the absolute URI If either of the above fields is undefined the field should contain an ASCII NULL A group table may contain any number of additional user defined columns Group table columns may appear in any order The values of TTYPEn are not case sensitive To permit inclusion of HDUs from existing FITS files in groups the grouping proposal does not require any new keywords for group members Use of the EXTNAME and EXTVAL keywords defined in section 3 3 2 the rules for generalized extensions permitting identification by reference is strongly recommended Every member of a group located in a particular file should have a unique combination of XTENSION EXTNAME and EXTVER keywords Group tables that are members should have a unique combination of EXTNAME and EXTVER keywords and there should not be an ASCII group table and a binary group NASA GSFC Astrophysics Data Facility 5 4 STSCI INHERITANCE CONVENTION 89 table with the same EXTNAME EXTVER in the same file In addition the use of EXTNAME allows HDUs of a given extension type and structure to be identified by a common name Use of the following two keywords also is strongly recommended e GRPIDn integer gives the EXTVER value of the nth group table of which the HDU is a member if the member is in the same file as the group table and is the negative of the EXTVER value if the member and group table are in different files The pre
98. eadings of five characters or fewer the comment fields of the keyword card image explain the title TFORMn keywords provide the format and TUNITn keywords provide the units where appropriate All units are lowercase the case is not significant The quantity in field 11 is a pure number and the designers of this table have chosen not to have a TUNIT11 field a different approach from that of example 6 For many fields TLMAXn and TLMINn keywords are used following the HEASARC convention discussed in section 5 6 1 4 The table contains the following fields 1 TIME is a double precision floating point number containing the arrival time in seconds of the X ray photon The time system is described by the Time Related Keywords later in the file 2 PIis a 4 byte integer containing the gain corrected pulse height energy channel number of the photon The channel numbers run from 0 to 4095 3 X is a 2 byte integer containing the projection of the event sky right ascension onto the X axis of a rectangular pixel coordinate system the axis runs from 1 to 1280 TLMAX3 TLMIN3 4 Y is a 2 byte integer containing the projection of the event sky declination onto the Y axis of a rectangular pixel coordinate system the axis runs from 1 to 1280 NASA GSFC Astrophysics Data Facility 151 9 RAWX is a 2 byte integer containing the CCD X axis pixel location of the event with no corrections the axis runs from 6 to 426 6 RAWY is a 2 byte intege
99. eal exponential notation ENw d Engineering format single precision real exponential notation with exponent a multiple of 3 ESw d Scientific format single precision real exponential notation with exponent a multiple of 3 nonzero leading digit unless value is zero Gw dEe General appears as F format if significance will not be lost otherwise appears as E Dw dEe Double precision real exponential notation In these formats w is the number of characters in the displayed values m is the minimum number of digits leading zeroes may be required d is the User s Guide Version 4 0 54 SECTION 3 FITS FONDAMENTALS number of digits following the decimal point and e is the number of digits in the exponent of an exponential form Usage of this keyword in some ways parallels that of the TFORMn keyword of ASCII tables in that it provides a formatted value for the number However the format given by the TFORMn keyword in an ASCII table describes the format of the number in the FITS file but the format given by the TDISPn keyword of a binary table is different from that of the number in the file The following keywords are reserved for proposed binary table conventions e TDIMn character is used by the multidimensional array convention section 5 2 3 For that convention it has a value giving the number of dimensions of field n in the table when those dimensions are two or more The value is of form 1 j k where 2 7 k
100. early in 1987 At the beginning of 1990 NASA Headquarters specified that all NASA or NASA supported projects must make their data available in FITS format Many of the projects then in the process of developing their data plans were high energy astrophysics experiments Their data would usually appear as event lists These event tables could be very large Map arrays would contain mostly zeroes and be inefficient Binary tables would be the best format Many of the FITS files designed by the high energy astrophysics community were based on the AIPS 3D table concept This growing demand gave impetus to the development of a formal proposal for binary tables Cotton distributed an initial proposal for a standard binary table extension to be called BINTABLE in April 1991 It incorporated all the features of the original A3DTABLE extension and included a number of additional keywords and field formats that had been suggested by readers of the original A3DTABLE description In late 1989 at a meeting at Green Bank to develop a standard format for single dish data Wells had suggested the concept of including multidimensional ma rices not just vectors in the fields of binary tables The participants in the meeting had decided to adopt such a format and proceeded to discuss possible designs Subsequently a number of prospective binary table users expressed an interest in a mechanism for including arrays whose dimension might vary from row to row in the
101. eb sites may be reorganized and the URLs corresponding to an individual page may change In that case the new location can generally be found by going to the main page for the site and following appropriate links NASA GSFC Astrophysics Data Facility iil As always comments about the Guide in particular about areas that need clarification or expansion are encouraged Send questions or comments to FITS Support Office Astrophysics Data Facility Code 631 Goddard Space Flight Center Greenbelt MD 20771 USA Telephone 1 301 286 2899 Electronic Mail fits nssdca gsfc nasa gov User s Guide Version 4 0 iv NASA GSFC Astrophysics Data Facility CONTENTS v Contents Preface i 1 The Origin and Purpose of FITS 1 11 The Need for FITS a 1 12 What FITS Is lees 2 13 The Philosophy of FITS llle 4 2 History 7 2 1 The First Agreement lees 7 2 2 Random Groups 22e 8 2 3 Generalized Extensions r a s ee s e 000 9 2 4 ASCII Tables _ 2 02020000222 eee 11 2 5 Floating Point ee ee ee 12 2 6 Physical Blocking lees 12 2 7 Image Extension eee 13 2 8 Binary Tables a 13 2 9 How FITS Evolves llle 15 3 FITS Fundamentals 17 3 1 Basic FITS s sas 000 os ns nis eee 17 3 1 1 Primary Header s e o 18 3 1 1 1 Required Keywords 21 3 1 1 2 Reserved Keywords
102. echnical panel has been formed to add the IMAGE and BINTABLE extensions and the blocking agreement to the NOST standard Clarifications arising from community discussion of the FITS rules also will be made The result of this process will be Version 2 of the Definition of FITS The standard is available in both printed and electronic form Electronic copies are available in several forms flat ASCII uncompressed PostScript compressed NASA GSFC Astrophysics Data Facility 6 1 THE FITS SUPPORT OFFICE 111 PostScript and IATEX Style nost sty and index files are provided for use with the IATgX form The three forms have identical content except that the ASCII version may not preserve the font usage in the other versions The standard may be obtained from the anonymous ftp site in files of the form fits standard through links starting at the FITS Support Office home page When a Draft Standard is announced for community review it is available in the ATpXand PostScript forms a text form is sometimes available The FITS Support Office maintains and updates this User s Guide which is designed to provide a better introduction to FITS for the novice than the precise but dry standard In addition to providing the rules it explains them in more detail than the standard and discusses their motivation It discusses recommended and discouraged practices and provides hints on how to use particular structures Sample FITS headers illustrate the diff
103. econd of arc NUMOBS starts in column 32 and contains a two digit integer giving the number of photographic observations used to determine the position EPOCH starts in column 34 and contains a four digit integer giving the epoch when the measurement was made of the AGK position in User s Guide Version 4 0 138 14 15 16 1T 18 19 APPENDIX A EXAMPLES OF FITS HEADERS hundredths of years after 1900 to get the epoch the number in this field is multiplied by 0 01 and added to 1900 Because the EPOCH keyword has been used in the past to give the equinox of the coordinate system section 3 1 1 2 it generally better to use a different keyword DATE OBS MJD OBS for the time of observation PM RA COSD starts in column 38 and is a five digit integer containing the product of the annual proper motion in right ascension and the cosine of the declination in units of thousandths of arcseconds year allowing this five digit field to contain values accurate to 0 001 arcsec year Applying the scaling transformation yields values that are in units of arcseconds year the value of TUNIT14 PM DEC starts in column 43 and is a five digit integer containing the annual proper motion in declination in units of thousandths of arcseconds year allowing this five digit field to contain values accurate to 0 001 arcsec year EPOCH DIFF starts in column 48 and is a four digit integer giving the difference between the epoch of
104. ed in 16 bit integer format BITPIX keyword Values in the matrix are converted to flux in Janskys per beam BUNIT keyword by multiplying by 7 04625720812 BSCALE keyword and adding 2 18688869476 BZERO keyword corresponding to a range of data matrix values of 0 121747084 physical value or 32764 in file to 4 495524406 physical value or 32764 in file Janskys per beam The EXTEND keyword has the value T indicating that this Basic FITS unit may be followed by extensions the comment notes that it is followed by tables The use of the HISTORY key words may appear to be analogous to the HIERARCH proposal however the embedded keywords have meaning only within AIPS to the rest of the world they are comments and can be treated as such User s Guide Version 4 0 124 APPENDIX A EXAMPLES OF FITS HEADERS Example 2 M87 and Jet KPNO Note The first two lines following are provided to help the reader determine column numbers They are not part of FITS headers 000000000111111111122222222223333333333444444444455555555556666666666777 123456789012345678901234567890123456789012345678901234567890123456789012 SIMPLE BITPIX NAXIS NAXIS1 NAXIS2 BSCALE BZERO BLANK IPPS RF IPPS ID IPPS B P IPPS MIN IPPS MAX ORIGIN DATE TIME JOBNAME COMMENT COMMENT COMMENT COMMENT OBJECT TELESCOP INSTRUME COMMENT COMMENT COMMENT COMMENT COMMENT COMMENT COMMENT COMMENT COMMENT COMMENT END
105. ements Keyword syntax for extension headers is governed by the same rules as for primary headers The standards concerning data types and bit order for the main FITS data records also apply to extensions The Generalized Extensions Agreement requires the use of a single additional keyword in the main header only EXTEND logical if true T indicates that there may be extensions that conform to the generalized extension standards following the data records Its absence guarantees that there are no extensions but its presence does not guarantee that extensions are present Because extensions are not required following a primary header with EXTEND T the primary HDU alone can be copied unchanged A value of F has no meaning and should not be used The EXTEND keyword must immediately follow the last NAXISn keyword or an NAXIS keyword with a value of zero FITS data in a file may consist entirely of extensions with no primary data In such cases the primary header must still be present with EXTEND T and NAXIS 0 to indicate no primary data array Examples 3 and 6 in Appendix A illustrate FITS primary headers with no data that occur at the start of files where all the data are in extensions 3 3 1 Required Keywords for an Extension Header The first keywords of a FITS extension header from XTENSION to the last NAXISn must appear consecutively in the order listed below User s Guide Version 4 0 40 SECTION 3 FITS FUNDAMENTALS
106. ensions TT NRAO Stokes Parameters Convention 104 IEEE Floating Point Formats lens 156 NASA GSFC Astrophysics Data Facility Section 1 The Origin and Purpose of FITS 1 1 The Need for FITS In the late 1970s the Westerbork Synthesis Radio Telescope WSRT in Westerbork Holland and the Very Large Array VLA in New Mexico began producing high quality images of the radio sky Since the two groups were observing at different frequencies they wished to collaborate in constructing spectral index maps by combining data obtained from the two instruments It was clear from the outset that this process would not be trivial Two different institutions would normally structure their data in different ways Machines at the two different installations might have different architecture using a different internal representation for the same number Lacking a standard format for transporting images an astronomer taking data from an observatory to a home institution would have to create special software to convert the data to the format used at the home institution Such software would restructure the data to the format of the home institution and perform whatever bit manipulations were necessary to convert numbers from the representation in the originating machine to that for the destination machine While radio astronomers were making great strides towards producing analog images of their normally digital data
107. environments for interchange This insistence on testing the format before it was presented set a precedent for future development a practical demonstration of transfer using a proposed FITS structure is still required before it can be approved On June 8 1979 Basic FITS was presented at an International Image Processing Workshop in Trieste Italy Wells and Greisen 1979 Harten endorsed it it won immediate acceptance and within one year FITS became the worldwide de facto standard in astronomy Wells Greisen and Harten 1981 hereafter FITS Paper I published the description 2 2 Random Groups While FITS began as a means of transporting simple digitized images from machine to machine it was soon realized that FITS could provide a framework for transporting other types of data The first new FITS structure designed by Greisen and Harten during late 1979 early 1980 Greisen and Harten 1981 hereafter FITS Paper II was composed of a set of random groups each consisting of a sequence of parameters followed by a small array of data The number and meaning of the parameters and the dimensions of the array would be the same for all groups In some of the early literature this structure is described as an extension but such terminology is now inappropriate as the name extension refers to the structure described in sections 2 3 and 3 3 The principal application of this format was to radio astronomical aperture synthesis v
108. er lists the name of the primary sort column given by the value of the TTYPEn keyword followed optionally by the names of secondary sort columns The names must be separated by a comma there may be zero or more spaces between a comma and the next column name The default order for sorting in this convention is ascending order if the sort is in descending order the name of the column is preceded by a minus sign This convention prescribes the following ascending sort order for the FITS data types Integer and floating point In numerical order for both ASCII and binary tables ASCII tables are not sorted in order of the internal ASCII representation of their contents Complex In numerical order of the real component first rows with the same value of the real component are sorted in order of the imaginary component Bit Zero or unset bits precede set bits Logical False F values precede true T values Character and string In order of the ASCII collating sequence for a string first in order of the first character then in order of the second character than in order of following characters in sequence In an ascending order search null or undefined characters follow all defined values NASA GSFC Astrophysics Data Facility 5 6 OTHER PROPOSED CONVENTIONS 97 The convention also provides a sort order for vector columns If the order is not otherwise specified rows are sorted first on the order of the value of
109. erent formats Some widely used conventions that are not specified in the formal rules of FITS are described The Guide also discusses current FITS developments including proposals for new rules or conventions Copies are available in printed form and electronically in compressed or uncompressed PostScript and JATpX in files of the form users guide The style file guide sty is provided for use with the ATEX form 6 1 3 Software and Test Files The FITS Support Office has developed a simple C program called headlist to read and list all the FITS headers in a file including extension headers as well as the primary header It reads the file from standard input and writes to standard output This program is useful when presented with a new and unfamiliar file Tt does not evaluate the file and is not guaranteed to work if there are serious errors in the file for example if the size of the data in an extension is not correctly described by the values of BITPIX NAXIS the NAXISn PCOUNT and GCOUNT The FITS Support Office has a software package written in C called the FITS Product Conformance Tester FPCT which validates conformance of primary HDUs to the FITS Standard While limited to Basic FITS structures its diagnostics are more descriptive than those of other packages it is also more forgiving as it attempts to continue past errors by making its best guess at what was intended rather than terminating on the first error It is thus most u
110. f the fundamental principles of FITS no change in the rules should render old FITS files unreadable or out of conformance the principle of once FITS always FITS This philosophy is reflected in data reduction and analysis packages in which all obsolete implementations are trapped and processed in the most accurate manner possible While adherence to this principle has perpetuated some constructs that have proven with time to be awkward it is better than the alternative of requiring revision of existing FITS files Changes in the FITS rules may add new structures that old software cannot handle Revised software will be required for new standard extensions but revising a software package is a far smaller effort than updating a full data library would be As far as is possible however FITS should be expanded in such a way that the old software will still be able to process those parts of the file which it is capable of handling In such a case software should not fail or give incorrect results when confronted with the new extension or conventions it should simply ignore them and continue to process those parts of the file that it can understand FITS is defined as a logical structure not tied to the properties of any particular medium thus allowing its continued use as the technology changes Conventions for its adaptation to any medium are independent of the logical structure of FITS Because its original development was for 1 2 inch mag
111. fferent card images if the values conflict The comment field following the keyword and value provides an opportunity to explain the meanings Such comments should supply additional information Some FITS writers automatically generate comments such as Physical coordinate of axis following a CTYPEn keyword or Physical units of matrix following a BUNIT keyword Such comments provide no more information than has been given by the FITS rules and are not very helpful for the human reader Comments should provide information not available from the FITS syntax for example what the axis is right ascension declination frequency or the units of the values in the primary data array Janskys beam magnitudes arcsec The number of characters in a string value is often limited to accommodate reading software resulting in abbreviations the comment field can and should be used to explain these abbreviations in full While the meaning of an abbreviation may be obvious at the writing installation it may not be so clear to a reader 3 1 1 4 Units The units named in the IAU 1988 Style Guide are recommended for array and keyword values with the exception of measurements of angles This set of units includes the SI units and additional units that are standard in astronomy for NASA GSFC Astrophysics Data Facility 3 1 BASIC FITS 29 example magnitudes Using BUNIT and TUNITn keywords will remove any confusion similarly the comment field
112. field 8 byte DOUBLE physical unit of field seconds pulse height invariant energy of the event data format 4 byte INTEGER physical unit of field Minimum legal value of PI 4095 Maximum legal value of PI 1 projected X RA sky pixel coordinate data format 2 byte INTEGER physical unit of field minimum legal value for column 3 1280 maximum legal value for column 3 1 1280 426 Y gt 00M C projected Y Dec sky pixel coordinate data format 2 byte INTEGER physical unit of field minimum legal value for column 4 maximum legal value for column 4 raw X detector coordinate of the event data format 2 byte INTEGER physical unit of field minimum legal value for column 5 maximum legal value for column 5 raw Y detector coordinate of the event NASA GSFC Astrophysics Data Facility TFORM6 1I i TUNIT6 pixel TLMING 1 TLMAX6 422 TTYPE7 PHA i TFORM7 1I i TUNIT7 channel TLMIN7 0 TLMAX7 4095 TTYPES DETX i TFORM8 1I TUNIT8 pixel TLMINS 1 TLMAX8 1280 TTYPE9 DETY i TFORM9 1I i TUNIT9 pixel TLMIN9 1 TLMAX9 1280 TTYPE10 GRADE TFORM10 1I i TUNIT10 pixel TLMIN10 0 TLMAX10 4 TTYPE11 CCDID TFORM11 1I i TLMIN11 0 TLMAX11 3 147 data format 2 byte INTEGER physical unit of field minimum legal value for column 6 maximum
113. following CTYPEn keywords can be used to specify the units Fractional units should not be used If for example for space reasons temperatures must be listed in the file in units of tens of degrees the units specified by BUNIT should be degrees and scaling section 3 1 2 1 should be used to transform from the file values to physical values Always explicitly describe non standard units copy of the IAU Style Guide recommendations is available on the IAU World Wide Web site currently at http www lsw uni heidelberg de iau units html For celestial coordinate systems specified with the CTYPEn CRVALn CDELTn and CROTAn keywords or with the keywords used in the world coordinates conventions described in section 4 the use of decimal degrees for the angular measurements is required and degrees are recommended as the units for other angular measurements with for example the value of BUNIT deg 3 1 2 Primary Data Array In the original design of FITS the data array represented a digitized image Each array element would therefore correspond to a pixel of this image Consequently while the elements of a FITS data array are often called pixels the array does not represent an image and the term pixel may simply refer to a member of an array rather than a section of an actual image The primary data array starts at the beginning of the record following the last primary header record The data occur in the order defined
114. for the purpose of validating the software s ability to read the data The traffic directory contains archives of FITS related traffic from Usenet newsgroups and mailing list It includes all postings to sci astro fits the fitsbits mailing list and FITS related postings to other newsgroups It also includes Frequently Asked Questions FAQ from selected Usenet newsgroups FITS related mailing lists and FITS related messages from other mailing lists also are archived here W Cotton has developed a family of FITS viewers for Microsoft Windows Apple Macintosh and Unix X Windows computer systems These viewers have easy to use graphical controls and are suitable for use as external FITS image viewers for World Wide Web browsers The programs contain extensive on line NASA GSFC Astrophysics Data Facility 6 3 HEASARC 115 documentation NRAO distributes these viewers free of charge Further information on the capabilities of the software and access to it are at http www cv nrao edu bcotton fitsview html 6 3 HEASARC The High Energy Astrophysics Science Archive Research Center HEASARC at Goddard Space Flight Center has been active in the development of FITS software and data set design It has developed and continues to enhance packages of FITS subroutines and tools which are publicly available and widely used It has formulated a number of internal conventions which are primarily related to high energy astrophysics but may have appli
115. g is longer than 8 characters Each substring except the last is terminated by an ASCII BLANK decimal 032 or hexadecimal 20 the character immediately following this delimiter is the first character of the next substring The last substring is terminated by an ASCII NULL Undefined or null variable length substrings are represented by a string of zero length the first position of the substring contains the designated delimiter or an ASCII NULL if it is the last substring of the field An ASCII NULL in the first position of the field signifies that the field contains no substrings There is no corresponding representation for an undefined or null substring in an array of fixed length substrings Possibilities include a blank substring or a user defined User s Guide Version 4 0 82 SECTION 5 ADVANCED FITS substring although general FITS readers won t necessarily recognize the special meaning of either If a distinction needs to be made between undefined and blank substrings it is better to use the variable length convention A possible alternative procedure for representing arrays of fixed length substrings is through the use of the TDIMn multidimensional array convention described in section 5 2 3 The first dimension is the number of characters in a string and the remaining dimensions are those of the array This convention must be used if the array of strings is two or more dimensions CTP recommend use of the substring array convent
116. gnaling produces diagnostic when used by particular implementations Table B 1 IEEE Floating Point Formats NASA GSFC Astrophysics Data Facility 157 References ANSI 1977 American National Standard for Information Processing Code for Information Interchange ANSI X3 4 1977 ISO 646 New York American National Standards Institute Inc Cotton W D Tody D B and Pence W D 1995 Binary Table Extension to FITS Astron Astrophys Suppl 113 159 166 Greisen E W 1983 Non linear Coordinate Systems in AIPS AIPS Memo 27 Greisen E W 1986 Additional Non linear Coordinates AIPS Memo 46 Greisen E W and Calabretta M 1996 Representation of Celestial Coordinates in FITS preprint available in PostScript form at ftp fits cv nrao edu fits documents wcs wcs all ps Greisen E W and Harten R H 1981 An Extension of FITS for Small Arrays of Data Astron Astrophys Suppl A4 311 374 Grosbgl P Harten R H Greisen E W and Wells D C 1988 Generalized Extensions and Blocking Factors for FITS Astron Astrophys Suppl 13 359 364 Hanisch R J and Wells D C 1988 World Coordinate Systems Representations Within the FITS Format DRAFT preprint Harten R H Grosbgl P Greisen E W and Wells D C 1988 The FITS Tables Extension Astron Astrophys Suppl 73 365 372 IAU Information Bulletin 49 14 1983 User s Guide Version 4 0 158 APP
117. h the intention that those keywords would be used for these conventions Those keywords should not be used for any purpose inconsistent with these conventions Publication in the binary table paper means that the these conventions will be widely recognized even without formal IAUFWG endorsement Unless there is agreement by a particular community or group of FITS users on an alternative convention the goal of standardizing formats for convenient data transport will best be achieved if users adopt these conventions when formatting their data in FITS The HEASARC FITSIO and FTOOLS packages support both variable length arrays and multidimensional arrays The IUEDAC software in IDL can read both variable length and multidimensional arrays and can write multidimensional arrays but not variable length arrays 5 2 1 Variable Length Arrays In some tables the number of elements in the array contained by a particular field may vary from row to row One approach would be to set the repeat count User s Guide Version 4 0 78 SECTION 5 ADVANCED FITS equal to the largest number possible and use fill values for the remaining elements in the field when the number of actual values is smaller However if the variations from row to row are large the resulting binary table will contain a large number of fill values an inefficient use of storage The binary table rules contain provisions that support a convention for efficient storage of variable length arr
118. he BLANK keyword does not have the same meaning as filling columns 1 8 with ASCII blanks The reserved keywords permit complete specification of a linear coordinate system for any axis Other coordinate systems can be identified through the name given by CTYPEn comments and user specified keywords e CTYPEn character is the name of the physical coordinate for axis n e g frequency RA Dec e CRPIXn floating is a location along axis n called the reference pixel or reference point used in defining the range of values for the physical coordinate of axis n It is given in units of the counting index The counting index for axis n runs from 1 to the value of NAXISn incrementing by one for each pixel or array position The value of CRPIXn may be a fractional index number e g 2 5 and or be outside the limits of the NASA GSFC Astrophysics Data Facility 3 1 BASIC FITS 25 array if the array runs over index values 1 10 the reference point may still be 5 The term reference pixel originated in the days when the data array was assumed to represent a digital image The location of the index number relative to an image pixel i e center or corner is not at present specified in FITS but the World Coordinates proposal currently under consideration places it at the center following the common usage in astronomy A full discussion of this issue appears in section 4 1 e CRVALn floating is the value of the physical coordinate
119. he plane of projection The proposal adopts the notation that has been used in AIPS using the last four characters of the value field of the CTYPEn keywords to identify the projection Table 4 1 shows the codes for the projections described above Table 4 1 Common Projections TAN tangent SIN sine ARC arc GC define 25 projection codes in all including the spherical cube projection used by the COBE project CSC Many standard projections are special cases of these 25 The NCP designation of the original AIPS memo is no longer used For each projection they provide the transformation equations and a diagram The following indexed keyword is reserved under this proposal for defining projections PROJPn floating is the nth projection parameter Projection parameters are additional quantities that are must be specified in order to define the projection completely The specfic meaning of the keyword or keywords is defined separately for each projection Many projections do not need these additional parameters GC call the deprojected coordinate system that results from this step the native coordinates User s Guide Version 4 0 70 SECTION 4 WORLD COORDINATE SYSTEMS 4 2 2 5 Conversion to Standard Celestial Coordinates In the original AIPS convention the native system was required to be locally parallel to the standard celestial coordinate system at the tangent point GC relax this requirement The axes of the native sky coo
120. header records should contain all the information necessary to read and label the associated data In addition other information may be provided such as the processing history or instrument status The header records are followed by the data records The first or primary HDU is governed by special rules Its data records if present contain a matrix of data values in one of several binary formats called the primary data array The array may have no more than 999 axes There need not be data in the primary data array An empty primary data array is most likely to appear when all the data of the FITS file are found in extensions 3 1 1 Primary Header Each card image in the header is in the following form keyword value comment Keywords can be no more than eight characters long The only characters permitted for keywords are upper case capital Latin alphabetic numbers hyphen and underscore with underscore preferred over hyphen Leading and embedded blanks are forbidden There are two special classes of keywords required keywords and reserved keywords If a keyword is required then a card image with that keyword must appear in the header Some keywords are required in all FITS headers others are required only in conjunction with certain FITS structures Some structures may require certain keywords to appear in a specific order Reserved keywords do not have to appear in any header but they may be used only with the reserved mea
121. here except P and maxelemis an integer While the binary table rules do not specifically forbid the use of this data type for other purposes any use that conflicts with the variable length convention would cause confusion and is to be avoided For example TFORM4 16E gt means that the fourth field of the table will consist of 16 32 bit floating point values The repeat count represents a major enhancement over ASCII tables where a field can contain only one value The number of bytes in a row is the sum of the number of bytes in the individual fields and must equal the value of NAXIS1 Note that this rule differs from ASCII tables which allow the value of NAXIS1 to be greater than the sum of the TFORMn As with ASCII tables to distinguish 0 from 4 0 in integer format for example in degrees of declination the sign field should be declared as a separate character field This separation is unecessary for floating point User s Guide Version 4 0 52 SECTION 3 FITS FONDAMENTALS END must always be the last keyword The remainder of the last header record must be filled with ASCII blanks Note that while the rules for generalized extensions do not specify where the PCOUNT and GCOUNT keywords are located after the last NAXISn keyword the rules for binary table extensions require that they appear between the NAXIS2 and TFIELDS keywords 3 6 2 Reserved Keywords for Binary Table Extension Header These keywords are optional in a
122. hould not be critical Because they are used in domain conventions use of the keywords HIERARCH KHBEGIN and KHEND for other purposes is discouraged All keywords with important information must appear in columns 1 8 User s Guide Version 4 0 104 SECTION 5 ADVANCED FITS 5 8 Polarization No convention has been formally and universally adopted within FITS to describe polarization The convention most widely used is the one developed by NRAO that is supported in AIPS This convention has also been adopted in a proposed standard FITS form for interferometry intended to replace Random Groups When values of the Stokes parameters are mapped an axis with the CTYPEn value STOKES is used to describe which Stokes or correlator parameters are displayed in the images The values and the parameters they denote are shown in Table 5 3 Table 5 3 NRAO Stokes Parameters Convention 8 7 6 5 4 3 2 1 12 3 4 YX XY YY XX LR RL LL RR I Q U V X and Y are linear polarizations with fixed orientation relative to the antenna In the interferometry proposal X is horizontal and Y vertical R and L refer to right and left circular polarization The convention has been suggested that 2 be used to refer to left circularly polarized images and 1 to right circularly polarized images The definitions of circular polarization follow the IEEE convention right circular polarization corresponds to the electric vector of an approaching wave rota
123. hour angle and u v w User s Guide Version 4 0 34 SECTION 3 FITS FUNDAMENTALS Using the random groups structure the values of baseline hour angle and u v w would be specified as parameters before each visibility polarization frequency matrix The combination of parameters and array constitutes a group The structure of the group would be given by the form r1 72 T3 4 TN Puis P1123 Dima 3 6 corresponding in this example to u v w time baseline visibility component Stokes parameter frequency where r1 ry are random parameters 1 through N and pii pigs are pixel values in the order defined for a data matrix The value of p could in principle be as large as 998 for each axis as opposed to the 999 maximum for Basic FITS The data array pij starts immediately after the last parameter ry The storage order and internal representation of a random groups data array are the same as for a Basic FITS simple array It is interesting to note that the Basic FITS data structure is actually a subset of this more general structure with no parameters 3 2 1 Header One of the signatures of the random groups structure is that the NAXIS1 key word is set equal to zero The NAXIS and NAXISn keywords will therefore have somewhat different meanings than in Basic FITS 3 2 1 1 Required Keywords The keywords required for an ordinary array are also required for random groups in the same orde
124. hus with the encoded complement in the header the checksum of the HDU is now zero Seaman and Pence recommend an algorithm for encoding the checksum complement for inclusion as the value of the CHECKSUM keyword This scheme encodes not only the meaning of the binary data but the checksum s actual 32 bit unsigned integer value Each of the four bytes in this value is numerically divided by four and the result placed in the corresponding byte of four quotients in four successive integer aligned fields the remainder for each byte is added to the first quotient For example the first byte of the second quotient field contains a value equal to one fourth of the first byte of the original checksum value The sum of the four quotients is the original checksum in addition the byte alignment is maintained the sum of the first bytes of the four quotients is the first byte of the original checksum complement similarly with the other three An ASCII zero is then added to all the bytes thus creating a 16 character printable ASCII string To improve readability if byte values are not alphanumeric then the values will be shifted by simultaneously incrementing one byte and decrementing the corresponding byte in another of the four quotients in a systematic way until both are alphanumeric In this process the sum is not changed In accordance with the FITS fixed format rules for character strings the initial quote is in column 11 and the first byte will be i
125. ial testing began in 1992 with an exchange of IMAGE and BINTABLE files among ESO IUE and the High Energy Science Archive Research Center HEASARC at Goddard Space Flight Center In line with the evolution of FITS from a tape standard to a bit stream standard the exchange was carried out by making files available through anonymous ftp rather than through exchange of tapes Early in 1994 following the revision of BINTABLE additional tests were carried out in preparation for the votes by the FITS committees Files from the Space Telescope Science Institute STScI containing IMAGE and BINTABLE extensions were read at ESO and another set of files from ESO was read at GSFC HEASARC The successful tests allowed the two extensions to proceed to a vote On June 15 1994 Chair P Grosbgl announced that the IAUFWG had endorsed the blocking rules and the IMAGE and BINTABLE extensions As both extensions are now standard FITS they are now described in Section 3 rather than in Section 5 as was done in earlier versions of the Guide The discussion of the BINTABLE appendixes remains in Section 5 as they were not part of the proposal adopted by the IAUFWG 2 9 How FITS Evolves The history of binary tables illustrates many of the aspects of the way in which additions to the FITS format have developed in the past and are likely to continue to evolve in the future The initial concept for a structure typically arises from the designer of a data set who finds
126. ications as NASA GSFC Astrophysics Data Facility 3 2 RANDOM GROUPS 33 well It never gained acceptance outside the radio interferometry community and some FITS readers designed for other communities cannot read it In addition the random groups records are a structural anomaly in FITS as they are the only records that do not conform to the primary HDU extensions special records sequence All of the original objectives originally intended for random groups can now be achieved through the use of the now standard binary table format described in section 3 6 Even the interferometry community for whom random groups was originally intended is developing new conventions based upon binary tables Do not create FITS files using random groups use binary tables instead The description of random groups presented here is intended as a reference for those who may have to read old random groups FITS files not as an encouragement to write them A number of keywords have been reserved for the random groups structure and may not be used for any other purpose unless specifically stated in the FITS rules Also the random groups structure is the original source of the PCOUNT and GCOUNT keywords that were incorporated into the Generalized Extensions rules discussed in section 3 3 While the basic array structure of FITS can handle a data matrix when the data are distributed evenly along all axes sometimes the data may not be distributed uniformly al
127. identified by CTYPEn at the reference point on axis n e CDELTn floating is the rate of change of the physical coordinate along axis n per unit change in the counting index evaluated at the reference point e CROTAn floating is the rotation angle in degrees of actual axis n of the array from the coordinate type given by CTYPEn As there is no prescribed rule for describing such rotations the nature of the rotation should be explained in detail using comments Default values have not been defined for any of these keywords These reserved keywords from FITS Paper I allow the definition of simple rectangular coordinate systems but they do not prescribe the relation between the plane rectangular coordinate system of the FITS array and the spherical coordinate region of the sky that it represents This question along with the current comprehensive proposal under consideration by the FITS community is discussed in section 4 Part of the proposal replaces the simple CROTAn CDELTn method with a more comprehensive method of defining coordinate transformations in three dimensions e DATAMAX floating is the maximum data value in the array after any scaling transformation has been applied to the stored array value e DATAMIN floating is the minimum data value in the array after any scaling transformation has been applied to the stored array value Note that DATAMAX and DATAMIN apply to the physical values represented not to the
128. in syntax One is simply a text extract to test the behavior of the FITS reader when confronted with such a file as might occur if such a file were mistakenly retrieved instead of a FITS file An aaareadme doc file describes the contents of this subdirectory These files must be retrieved in binary format if they are to work properly Many Web browsers interpret FITS files as text by default 6 1 4 Contact Information Printed copies of documentation are obtained from the Coordinated Request and User Support Office CRUSO Electronic mail request6nssdca gsfc nasa gov Telephone 1 301 286 6695 8 00 A M 4 30 P M FAX 1 301 286 1635 Postal Coordinated Request and User Support Office NASA GSFC Astrophysics Data Facility 6 2 NRAO FITS RESOURCES 113 Code 633 National Space Science Data Center NASA Goddard Space Flight Center Greenbelt MD 20771 USA Times are U S Eastern time GMT 0500 from the last Sunday in October through the first Saturday in April 0400 the rest of the year If no one is available to answer the telephone messages can be left on voice mail Contact information for the FITS Support Office is as follows Electronic mail fits6nssdca gsfc nasa gov Telephone 1 301 286 2899 Approximate hours are 8 30 A M 5 30 P M Eastern time voice mail is available 6 2 NRAO FITS Resources An archive of FITS material is available at NR AO at http fits cv nrao edu or ftp fits cv nrao e
129. inates but does not define precisely how they are to be used AIPS uses the CROTA2 keyword to represent the angle in decimal degrees of the declination or latitude axis with respect to the 2 axis of the data array measured in the counterclockwise direction AIPS does not use the CROTA1 keyword and assumes a default value of zero for the CROTA2 keyword The CROTAn keywords are necessary only when the physical coordinates are rotated relative to the array coordinates These AIPS conventions were endorsed at the Charlottesville meeting have been widely used and will be generally understood However some individual FITS files may define the CROTAn differently Check the comments The CROTAn keywords cannot be applied in a straightforward way to more than two dimensions or to cases where the axes are not orthogonal GC define the more general pixel coordinate PC matrix P to transform between the FITS array axes f and axes in the direction of the physical coordinate system but on the array scale a Aa Y P A f 4 1 where the A signify that positions are with respect to the reference point Keywords are used to specify the elements of the PC matrix PCiiijjj floating is an multi indexed keyword giving the value of the pixel coordinate matrix element Pj in equation 4 1 The PC matrix technique permits considerable flexibility in transforming between axes including axes that are not orthogonal Some of this flexibility may be better
130. include the checksum keywords The checksum keywords should be included in all HDUs of FITS files that contain more than one HDU All HDUs of a single FITS file should use the same checksum algorithm i e the values of CHECKVER should be the same e When an HDU is modified FITS software should update the checksum keywords if present and add them if not present User s Guide Version 4 0 94 SECTION 5 ADVANCED FITS e At the very least FITS software should delete the keywords if an HDU is modified and the checksums are not recomputed The last two recommendations must be followed to avoid creating HDUs containg checksum keywords with values inconsistent with the HDU contents Seaman and Pence present a detailed example of the use of the checksum convention and the encoding described above as well as software to in both C and FORTRAN 77 to implement the encoding The C routines are adapted from the on line software for the NOAO IRAF Save the Bits archive the FORTRAN 77 routines are adapted from the FITSIO package 5 6 Other Proposed Conventions 5 6 1 HEASARC The HEASARC at Goddard Space Flight Center is responsible for archiving a considerable volume of data from many different high energy astrophysics missions including missions under the auspices of NASA and missions in which NASA has cooperated with and supported other agencies Under the Office of Guest Investigator Programs OGIP the HEASARC FITS Working Group has
131. included in a FITS file by using signed integers and then scaling for example setting BZERO equal to 32768 2 for 16 bit integers Some detector systems produce files that conform to the FITS rules except in their use of multibyte unsigned integers these files should not be described as FITS files and should not have SIMPLE set equal to T in the first card image Such files are an example of a good use for setting SIMPLE equal to F 3 1 2 1 Scaled Integers When FITS was originally developed there was no standard format for the internal representation of floating point data Only integer formats were allowed in the data array The scaling scheme using the keywords BZERO and BSCALE was devised in order to make it possible to represent inherently floating point physical values using a data array of integers The physical value of the data represented by an array member would be derived from equation 3 2 While scaling is no longer required to represent floating point numbers it remains a useful tool Representation of unsigned integer quantities is one application Be careful when attempting to scale data sets with large dynamic range If one converts such data to integers and then tries to convert back to floating point so much precision may be lost that the original data values will be irretrievable 3 1 2 2 Undefined Integers The value of the keyword BLANK is used to identify undefined integer array values which might result from da
132. ion Dieckvoss and Collaborators 1975 Warren Jr HISTORY W H 1984 NSSDC WDC A R amp S 84 06 should accompany any computer HISTORY readable version of this catalog TTYPE1 AGK3 AGK3 zone and sequential number TBCOL1 1 Start column TFORM1 A7 Fortran format TTYPE2 AGKS3 COMP Component identification TBCOL2 8 Start column TFORM2 Ai Fortran format TNULL2 0 Null value TTYPE3 PMAG Photographic magnitude TBCOL3 9 Start column TFORM3 I3 Fortran format TUNIT3 mag Units are magnitudes NASA GSFC Astrophysics Data Facility TSCAL3 TTYPE4 TBCOL4 TFORM4 TTYPES TBCOLS TFORMS TUNITS TTYPE6 TBCOL6 TFORM6 TUNIT6 TTYPE7 TBCOL7 TFORM7 TUNIT 7 TSCAL7 TTYPES TBCOLS TFORMS TTYPE9 TBCOL9 TFORM9 TUNIT9 TTYPE10 TBCOL10 TFORM10 TUNIT10 TTYPE11 TBCOL11 TFORM11 TUNIT11 TSCAL11 TTYPE12 TBCOL12 TFORM12 TTYPE13 TBCOL13 TFORM13 SPTYPE A2 RAH I2 n RAM I2 min RAS I5 g DECSIGN A1 DECD 1 I2 deg DECM I2 arcmin DECS I4 arcsec NUMOBS I2 EPOCH 114 12 14 16 18 0 001 23 24 26 28 32 34 Y gt YD 0M ss s s s s s s N N 7T 0M 0M CM s s s s s s N N 1335 Scale factor Spectral type from HD Yale or McCormick Start column Fortran format Hours RA
133. ion for a one dimensional array of strings 5 2 3 Multidimensional Arrays in Binary Tables The original binary table proposal the A3DTABLE extension introduced the concept of a table entry or field of more than one element a vector It provided this structure through the use of a repeat count However since an array of more than one dimension can be reduced to a one dimensional vector as occurs when arrays are stored in a computer the repeat count can be used to define multidimensional arrays as well To do so conventions are needed to specify how such an array is organized in the table field 5 2 3 1 TDIM Keyword CTP propose one convention using the TDIMn keyword which has been reserved for multidimensional array description The value of the TDIMn keyword i j k describes the dimensions of the array t x 7 x k x stored such that the index along the first dimension z varies most rapidly the same convention used for the primary data array The product of the dimensions must be equal to the repeat count specified in the value of the TFORMn keyword This convention is not a formal part of the proposed binary table definition Other conventions are possible and may be used 5 2 3 2 Green Bank Convention This convention was developed at a meeting to discuss standard FITS formats for interchange of single dish radio astronomy data held at Green Bank WV in NASA GSFC Astrophysics Data Facility 5 2 CONVENTIONS FOR
134. ion of the conventions described here with different meanings Because these conventions have not been formally approved as part of standard FITS data sets that use other conventions are not out of conformance However these conventions are widely used and have the best software support creators of FITS data that use different conventions will probably need to supply supporting software to their users NASA GSFC Astrophysics Data Facility 4 1 INDEXES AND PHYSICAL COORDINATES 63 4 1 Indexes and Physical Coordinates When the data matrix represents a digital image transformation between the data matrix and the physical picture requires knowledge of where in the pixel center or corner the data point is Historically astronomers have generally assumed that the index point in a FITS file represents the center of a pixel This interpretation is endorsed by GC It differs from the common practice in computer graphics of treating the center of a pixel as a half integral point GC note that the pixel in a FITS file is commonly regarded as a volume element in physical space which might be viewed from different perspectives via transposition and rotation Under such operations only the center of an element remains invariant Pending adoption of a standard convention by the astronomical community FITS writers should use appropriate comments in the comment field of the card image or the COMMENT keyword to inform readers of the file which conven
135. ion to which the array descriptor points must be located entirely within the heap In particular it may not be in the main table Reading a variable length array on a random access storage medium such as disk is straightforward When an array descriptor is encountered the User s Guide Version 4 0 80 SECTION 5 ADVANCED FITS information in it can be used immediately to find the appropriate data in the heap and read them the program can then move to the next table entry On sequential access storage media such as tape the process is more complicated As the main table is read a table of the array descriptors must be generated and stored Space is reserved in the output data set to hold the actual array based upon the specifications of the array descriptors When the main data array has been read the array descriptors are first sorted in order of appearance in the heap and then the data are read from the heap in order and stored as specified by the array descriptors If more than one field has the same stored descriptor the same heap data may be stored in more than one place Because variable length arrays are more complicated to deal with than ordinary fixed length arrays and require an extra data access per array to obtain all the data for a field they should be used only when absolutely necessary As this convention is not part of the formal rules for binary tables not all binary tables software will necessarily be able to read
136. ions The treatment of extensions with no value of EXTNAME is the same as that for the case where no value of XTENSION is available e TTYPEn MEMBER VERSION is the heading for a column whose entries are integers with the values of the EXTVER key word for group member extensions For primary headers or where the EXTVER keyword is absent the entry should be 1 User s Guide Version 4 0 88 SECTION 5 ADVANCED FITS The following keyword is used to define a column needed if all or some members are identified by position e TTYPEn MEMBER POSITION is the heading for a column of group member positions given as integers with 0 zero representing the primary HDU 1 one the first extension etc If the value is invalid or undefined the entry should contain the null value specified by the TNULLn keyword for that column The following keywords are required if some or all of the group members are not in the same file as the group table e TTYPEn MEMBER URI TYPE is the heading for a column containing the acronym for the URI type used to identify the member location Entries permitted as this is written are URN and URL other entries will become acceptable as new URI types are defined e TTYPEn MEMBER LOCATION is the heading for a column containing the URIs for the group members For group members in the same file as the group table the field may be filled with blanks for members on the same machine but in a different file th
137. is a worldwide medium of data exchange extension formats need to be coordinated under the International Astronomical Union FITS Working Group IAUFWG to prevent duplication and inconsistencies in usage and agreements should be reached governing keyword conventions in particular fields The structure under the IAUFWG provides an overall authority for the FITS standard but additions to FITS are not created by the IAUFWG but are designed by FITS users and then acted upon by the international structure Although the number of strict rules is not large there is an extensive set of recommended practices Creators of FITS files should adhere to these recommendations if at all possible in particular the rules of FITS should not be exploited to create files that try to mimic the local format and although in technical compliance with the rules depart from the NASA GSFC Astrophysics Data Facility 1 3 THE PHILOSOPHY OF FITS 5 recommendations to such an extent that they don t look like FITS files General adherence to recommended practice will simplify the task of the FITS software developers if a FITS file contains too many unconventional but permitted constructs many FITS readers may not be able to handle it Not everything that is permitted is wise Users who develop extensive libraries of FITS files need assurance that they will not have to periodically revise these files because of changes in the standard This requirement gives rise to one o
138. isibility data These data consist of small groups of arrays that occur in a NASA GSFC Astrophysics Data Facility 2 3 GENERALIZED EXTENSIONS 9 relatively random manner on one or more axes Random groups has failed to attain wide use in other areas and is now being replaced even for aperture synthesis data by binary tables Future use is discouraged At the 1982 General Assembly the IAU endorsed FITS including the Random Groups format as the recommended format for transport of binary data IAU 1983 2 3 Generalized Extensions The special records provision of the original FITS design made it possible to extend the format There were two principal reasons for wanting to extend FITS beyond the simple header array structure e to transfer new types of data structures while adhering to the basic rules of FITS e to transfer collections of related data structures thereby creating a simple hierarchical data base capability For example the table extensions have allowed tables lists etc associated with a data matrix to be written in the same FITS file as the data matrix implicitly establishing the relationship among the different pieces of information The method chosen was to define extensions HDUs which like the primary HDU are composed of a header consisting of card images in ASCII text with keyword value syntax followed by data There could be many kinds of extensions each with a different defined data forma
139. ither the real or imaginary part of a complex value contains a NaN the entire complex value is regarded as invalid Alignment may be a problem when binary tables are read Suppose the sequence 1I 1E is read directly from the I O buffer Some machines may require that the number of bytes between the start of this sequence and the start of a 4 byte floating point number in it be evenly divisible by 4 In that case the floating point number will not begin at a proper location and a data alignment error will result If alignment is important the data should be copied from the I O buffer into an aligned buffer before they are read 3 7 Reading FITS Format It is more difficult to specify and give examples of the minimum requirements to read FITS formats because reading FITS means a translation of the FITS data set into the internal format of a data analysis package Each package has its own unique requirements When developing software to read FITS format allow for the flexibility of FITS Don t assume that files will always follow practices that are recommended but not required For example don t expect that values of optional keywords will use the recommended but not mandatory fixed format be prepared to accept all formats consistent with FORTRAN 77 list directed NASA GSFC Astrophysics Data Facility 3 8 FITS FILES AND PHYSICAL MEDIA 57 read Also assume that keywords will appear in a particular order only when this order is specified
140. l a multidimensional array extension format that allows extensions to contain the same type of data that is in the primary HDU It is also possible to create non standard formats for use locally or as prototype designs for new standard formats Although its name implies image transport FITS is not a graphics format designed simply for the transfer of pictures does not incorporate FITS viewers packages for decoding the data into an image Users must develop or obtain separate software to read and display the data from the FITS file Because of its wide use FITS is supported by all the major astronomical imaging packages and a number of other packages of FITS utilities and software are publicly available The data structure is an essential part of the format and is available to the users This property distinguishes FITS from many other data standards those that are primarily labeling systems and those for which the user accesses a hidden data structure through a set of standard tools User s Guide Version 4 0 4 SECTION 1 THE ORIGIN AND PURPOSE OF FITS 1 3 The Philosophy of FITS FITS incorporates a philosophy along with the data format The underlying goal is to provide a standardized simple and extensible means to transport data between computers or image processing systems Any FITS reader should be able to cope with any FITS formatted file skipping over portions extensions and ignoring keywords that the reader does n
141. left unused In particular it is possible to transpose the axes when going from the pixel axes i j to the physical axes x y Suppose the first two axes are transposed so that axis 2 in physical space corresponds to axis 1 in pixel space and vice versa The most rapidly varying axis is axis 1 z in NASA GSFC Astrophysics Data Facility 4 2 PROPOSED CONVENTIONS 67 pixel space described by the values of NAXIS1 and CRPIX1 The corresponding physical axis is the one y described by CTYPE2 CRVAL2 and CDELT2 CTYPE1 describes the first axis in physical space which is now not the most rapidly varying If these concepts take some time to think through here imagine trying to understand them in a FITS file Such complications can be avoided if the tranformation is defined such that the diagonal terms of the PC matrix predominate Another potential application of the PC matrix that is best unused is the ability to reverse the direction of the axis GC strongly recommend that the elements of the PC matrix should be positive Use the CDELTn keywords to reverse axis directions Because the AIPS convention has been widely used new software that uses the PC matrix will still need to interpret files using the AIPS conventions Also until FITS reading software routinely includes support for the PC matrix FITS files where the PC matrix represents a rotation equivalent to that of the old CROTAn method should also include the CROTAn keyword as we
142. les for extensions Grosbgl et al 1988 The IAUFWG has since endorsed an additional set of formal rules to relate physical and logical structure for other media Each medium has its own particular rules The complete rules are as follows e For 1 2 inch 9 track magnetic tape physical blocks may contain one to ten logical records Unlabeled tapes are strongly recommended however tapes with ANSI labels are permitted Data reduction and analysis packages reading labeled tapes must count the tape label as the first file e For fixed block sequential media with a physical block size that is not an integral multiple or fraction of 2880 for example 512 the 2880 byte logical records are not tied to the physical block size but are written User s Guide Version 4 0 58 SECTION 3 FITS FONDAMENTALS independently over multiple blocks if necessary The end of the last logical record of the FITS data set will probably not correspond to the end of a physical block A short logical record extending to the end of the physical block will follow Readers should regard a record of less than 2880 bytes as the equivalent of an end of file mark Examples of media covered by these rules are optical disks accessed as a sequential set of records QIC format 1 4 inch cartridge tapes and local area networks e For bitstream devices FITS files are written with a blocking factor of one i e with a physical block size of 23040 bits the same as the logical rec
143. lite ROSAT where NASA is cooperating with Germany and the United Kingdom ultraviolet and visible from the International Ultraviolet Explorer IUE and the Hubble Space Telescope and infrared data from the Infrared Astronomical Satellite IR AS and the Cosmic Background Explorer COBE It is also the standard for ground based radio and optical observations in use by such organizations as the National Radio Astronomy Observatory NRAO National Optical Astronomy Observatories NOAO and the European Southern Observatory ESO 1 2 What FITS Is The fundamental unit of FITS is the FITS file which is composed of a sequence of Header Data Units HDUs optionally followed by a set of special records The rather prosaic name HDU was the result of over a year s community discussion and failure to find anything better The first part of each HDU is the header composed of ASCII card images containing keyword value statements that describe the size format and structure of the data that follow It may contain any information about the data set that its creator regards as important such as information about the history of the data or the file about the physical entity the data describe or about the instrument used to gather the data The data follow structured as the header specifies The size of logical records in both header and data is 23040 bits equivalent to 2880 8 bit bytes or 36 header card NASA GSFC Astrophysics Data Facility 1 2 W
144. ll as the PC matrix If 0 is the latitude angle represented by CROTAn in the AIPS convention and 6 is the value of CDELTn then Pi cos 4 2 Py 6 6 sin 0 4 3 Py 6 82 sin 8 4 4 Py cos 4 5 It is always possible to express the CROTAn rotation in the PC matrix form However not all of the more general rotations described by the PC matrix can be described using CROTAn When the coordinate transformation follows the AIPS convention the P relation can be inverted to yield two separate and equivalent expressions for 0 D tan 61 52 Pi2 Po2 4 6 tan 62 51 Po Pa 4 7 For a coordinate transformation following the AIPS convention both expressions give the same value For more general tranformations both should be computed If the difference between the two values of 6 obtained is within the expected precision use the average to reduce the round off errors If the difference is larger then the coordinate axes are not orthogonal and the CROTAn description cannot be used HW User s Guide Version 4 0 68 SECTION 4 WORLD COORDINATE SYSTEMS 4 2 2 3 From Pixel to Physical Values Application of the PC matrix yields a coordinate system in the direction of the physical axes but in pixel units Conversion to physical units is performed by applying the scaling specfied by the CDELTn In some past applications of this process steps 2 and 3 have been combined into a single s
145. ll be more efficiently read if TNULLn is specified only when null values actually exist in the field thus avoiding unnecessary string comparisons for the other fields 3 4 3 Data Records in an ASCII Table Extension The table data records begin with the record immediately following the last header record Each record contains 2880 ASCII characters in the order defined by the header The first entry of each row immediately follows the last entry of the previous row and table entries do not necessarily begin at the beginning of a new record After the end of the valid data the last record should be filled with ASCII blanks The table consists of NAXIS2 rows of length NAXIS1 Entries are in the FORTRAN 77 formats specified in the associated header A format fields should be encoded as plain text without being encoded in string quotes Numbers decoded with the I format may exceed the 16 bit integer range Blank characters in a field are not interpreted as zeroes all zeroes even trailing zeroes must be explicit This rule is equivalent to setting the FORTRAN 77 OPEN statement specifier BLANK to NULL The w in the value of TFORMn specifies the width of field n Field n begins in the position given by the value of TBCOLn and includes w characters The sum of the widths of the different columns need not equal the value of NAXIS1 the length of a row However no field may extend beyond the end of the row to column numbers greater than the value of NAX
146. lues For example if PTYPE1 GLON d PTYPE2 GLON d PSCAL1 1 0 PSCAL2 1 0E 04 where GLON stands for Galactic longitude then the value of Galactic longitude for each group is derived by adding the value of the first random parameter for that group to 1074 times the value of the second random parameter The rules governing units in random groups are the same as those for a primary data array as given in section 3 1 1 4 3 2 2 Data Records The data records begin in the first record following the last header record similarly to the way a primary data array is stored The first parameter of the first group is at the start of the first data record The first member of the array NASA GSFC Astrophysics Data Facility 3 3 EXTENSIONS 37 in each group follows the last parameter with no spaces or fill It does not start a new record Similarly each parameter array group immediately follows the previous one a new group need not begin a new record The same data types are allowed as for Basic FITS The data type for the random parameters must be the same as the data type for the data arrays 3 3 Extensions The data to be transported do not always fit conveniently into an array format Also auxiliary information associated with an image or data set may need to be saved in the same file but may not fit into the array structure To handle such cases the concept of FITS extensions has been introduced Grosbgl et al 1988 Extensio
147. mages in the following order 1 XTENSION character has the value TABLE gt for ASCII table extensions 2 BITPIX integer must have the value of 8 indicating printable ASCII characters 3 NAXIS integer must have the value of 2 for ASCII table extension headers The axes are the rows and columns of the table 4 NAXIS1 integer gives the number of characters in a table row 5 NAXIS2 integer gives the number of rows in the table The value can be 1 While a value of zero is permitted that value would indicate that no table is present 6 PCOUNT integer is required with the value of 0 for the ASCII table extension 7 GCOUNT integer is required with the value of 1 for the ASCII table extension Each extension contains one table the total number of bytes is NAXIS1 x NAXIS2 8 TFIELDS integer has a value that gives the number of fields in each table row Values from 0 to 999 are allowed Note that while the rules for generalized extensions do not specify where the PCOUNT and GCOUNT keywords appear between the last NAXISn keyword and the END keyword the ASCII table extension requires that they appear immediately after the NAXIS2 keyword The following required keywords may appear anywhere between the TFIELDS and the END keywords e TBCOLn integer is the column number of the first character in field n The first column of a row is numbered 1 NASA GSFC Astrophysics Data Facility 3 4 ASCII TABLE EXTE
148. mary HDUs and image extensions ASCII tables and binary tables including binary tables with variable length and multi dimensional arrays The accompanying FITS writer can write primary HDUs image extensions and binary tables including multi dimensional but not variable length arrays but it cannot write ASCII tables The software is available from ftp iuewww gsfc nasa gov and runs on Unix Ultrix VMS MacOS and Windows 3 1 systems User s Guide Version 4 0 118 SECTION 6 RESOURCES The National Center for Supercomputing Applications NCSA Hierarchical Data Format HDF group is developing a FITS server side browser Among the things it can do now are the following Retrieve the images from a FITS file e Allow viewing of a group of planes from a 3 D image e Get summary information from the primary or extension headers Create an HTML table from an ASCII or binary table NCSA is also developing FITS HDF conversion utilities Because this site is evolving rapidly the individual URLs have been changing but it should be possible to find the FITS material by starting at http hdf ncsa uiuc edu The three principal astronomical image processing software packages AIPS the ESO Munich Interactive Data Analysis System ESO MIDAS and IRAF incorporate substantial support for FITS New software to display FITS images continues to be developed Some nonproprietary packages are mentioned in one section of the FITS Basics and Info
149. n Wells notes that real spectral observations would probably require 50 table columns in each row in addition to the spectra The precise column labels are not part of the proposal if such a structure were to be adopted an ad hoc group would work out the details Also the data types used might vary among installations In this example the primary header is not included but as with the ASCII table extension example there must be one to start the data set Other extensions might be present as well so this extension isn t necessarily going to be the second header data unit on the data set The XTENSION BINTABLE string at the start of the record indicates that the header is for a binary table extension The BITPIX NAXIS and GCOUNT keywords have the values required for a binary table extension The value of 0 for PCOUNT shows that there are no heap or other data following the table To describe one spectrum 4134 bytes are needed NAXIS1 this particular table has 20 spectra NAXIS2 The NAXIS1 value is equal to the sum of the number of bytes required by the different fields Each row of the table can hold a 1024 channel spectrum and five additional items of information to describe it scan number source ID frequency of reference channel channel to channel difference and the total number of channels Frequencies are in Hertz TUNIT3 and TUNIT4 keywords There is room in field 6 for 1024 channels there could be fewer The title or name of
150. n column 12 In order to maintain proper byte alignment within the four byte NASA GSFC Astrophysics Data Facility 5 5 CHECKSUM PROPOSAL 93 word the final byte of the encoded checksum is permuted to column 12 thus it remains the fourth byte of a four byte word the next byte is the first and all the rest maintain proper position This value is then set in the value field of the checksum Seaman and Pence present a detailed example The string can easily be decoded by permuting the encoded string back to its original alignment subtracting the hexadecimal 30 offset and summing the four parts This algorithm is not mandated by the proposal other encodings are possible but must satisfy the following constraints e The 32 bit unsigned integer CHECKSUM value is encoded into a 16 character ASCII string e Only the ASCII alphanumberic characters 0 9 A Z and a z are permitted e The quotes enclosing the ASCII string value of the CHECKSUM keyword must be in columns 11 and 28 e The encoded ASCII value will cause the 32 bit ones complement checksum of the HDU to be zero The checksum is zero for the entire file because it is zero for each individual HDU of Requiring a zero checksum for individual HDUs rather than only for the file as a whole allows HDUs to be removed from or added to the file without altering the checksum The following strong recommendations are made regarding the usage of these key words e FITS files should
151. n only some fields TUNITn keywords provide units all in lower case in this table although no special significance is to be ascribed to the case TSCALn and TZEROn keywords show where the value in the FITS table must be transformed to yield the physical value and TNULLn gives the null string where needed Blank lines are treated as comments because the keyword field is blank The following list describes the contents of the fields as described by the header key words 1 AGK3 starts in column 1 and contains a seven character string giving the declination zone and sequence number within the zone of the star 2 AGK3_COMP consists of a single character in column 8 giving a component identification for a member of a multiple star system The string 0 zero represents a single star 3 PMAG starts in column 9 and contains a three digit integer giving the photographic magnitude of the star in units of tenths of a magnitude The NASA GSFC Astrophysics Data Facility 10 11 12 13 137 value in the field must be multiplied by 0 1 the value of TSCAL3 to obtain the physical quantity in units given by TUNIT3 SPTYPE starts in column 12 and contains a two character string giving the spectral type RAH starts in column 14 and contains a two digit integer with the hours of right ascension of the position of the star equinox 1950 Besselian RAM starts in column 16 and contains a two digit integer with the mi
152. ncorporated in data sets 5 7 Keyword Domains Keywords that are not required or reserved for the standard FITS structures might easily have different meanings for different groups Thus the significance of a keyword would depend upon the context The FITS community has looked for possible ways to define domains that would identify which keyword definitions apply The initial approach to defining keyword domains was the concept of keyword hierarchies In this method syntax in the FITS file would indicate that certain keywords were to be considered as part of a named domain Such domains might exist in a hierarchy of levels For example the highest level User s Guide Version 4 0 102 SECTION 5 ADVANCED FITS might be a particular institution and lower levels could be individual projects within the institution However consensus about what the structure should be appears unlikely The reasons for the lack of agreement become apparent from an examination of the principal approaches One approach would use the string HIERARCH in columns 1 8 of a header card image as domain indicator Domain names at progressively lower levels would follow in sequence in the card image and finally the keyword value statement would appear after the lowest level domain name Critics of this approach argue that the HIERARCH keyword and the domain names would leave little room on the card image for the actual keyword and value information or for comme
153. netic tape its structure is well adapted to that medium and the conventions are long established More recently more generalized conventions have been adopted for the expression of FITS on magnetic tape and on magnetic and optical disk Conventions can be defined for new media as they develop User s Guide Version 4 0 6 SECTION 1 THE ORIGIN AND PURPOSE OF FITS NASA GSFC Astrophysics Data Facility Section 2 History 2 1 The First Agreement In November 1976 R Harten of the Netherlands Foundation for Radio Astronomy NFRA and D Wells of the Kitt Peak National Observatory KPNO now part of NOAO began work on a solution to the problem of exchanging data between observatories In the spring of 1977 Harten and Wells each built prototype data interchange programs and they exchanged tapes During 1977 and 1978 J Dickel University of Illinois carried radio and optical imagery encoded in the two formats between Westerbork and Kitt Peak In January 1979 during the National Science Foundation NSF Image Analysis meeting at KPNO the exchange format problem was discussed P Boyce NSF the chair of the meeting urged NOAO and NRAO to come up with a solution and assigned a task force of R Burns NRAO E Groth Princeton and Wells to begin the process Burns organized a meeting at the VLA of this task force and the VLA programmers On direction from the initial session of the meeting E Greisen NRAO and Wells retired to the
154. ning if they do Users may define their own additional keywords for any FITS file The contents of the keyword field determine the structure of the value field Keywords that have values associated must contain in columns 9 and 10 otherwise columns 9 80 are regarded as comment Except for the special cases of the HISTORY and COMMENT keywords and a blank keyword field section 3 1 1 2 if a keyword does not have a value column 9 must not The name of the keyword governs whether a value is present Keyword values have one of four types logical character string integer or floating point The following notation will be used to show what type of value contain must be associated with each keyword NASA GSFC Astrophysics Data Facility 3 1 BASIC FITS 19 KEYWORD value type The discussion that follows the keyword name will describe the meaning of the value The following content is required for the first ten columns of a header card image e Keyword name beginning in column 1 ending in or before column 8 The remainder of columns 1 8 is blank filled e If the keyword has a value associated with it in column 9 followed by a blank in column 10 e If the keyword has no value and is not the reserved HISTORY COMMENT or blank field any content other than in columns 9 and 10 e For the reserved HISTORY COMMENT and blank field keywords the contents of columns 9 and 10 are not restricted
155. ning of the next extension NASA GSFC Astrophysics Data Facility 2 4 ASCII TABLES 11 A complete set of rules described as the Generalized Extensions agreement Grosbgl et al 1988 hereafter FITS Paper III was endorsed by the IAU in 1988 These rules appear in section 3 3 2 4 ASCII Tables The concept of a standard flexible format for the transfer of astronomical data was so appealing that astronomical software designers sought to apply the format to data and information structures other than simple arrays For example astronomers make extensive use of catalogs Such information would most naturally be stored as a table The wide variety of tabular information led to the development of the ASCII table extension The following three main classes of potential applications were envisioned 1 Standard catalogs such as star or source catalogs 2 Observing information such as observing logs calibration tables and intermediate tables related to the observing The results of the observations might appear as the Basic FITS matrix and the auxiliary information would follow in a table 3 Tabular results extracted from observational data by data analysis software As an example many programs automatically detect sources in digitized images and write parameters such as position flux size spectral index and polarization into output files Astronomers need to transmit these output tabular files recipients can then use software designed
156. nly for transporting radio interferometry observations The binary table structure with multidimensional arrays can be used to hold the exact same data as the random groups structure Each parameters array group corresponds to a row in the table The parameters map into single item fields and the array into a field with a multidimensional array The names and other information describing the parameters would be in the table field headings This format is more flexible than random groups The parameters in the random groups format must be of the same data type e g two byte integer double precision floating point as the members of the array NASA GSFC Astrophysics Data Facility 5 3 HIERARCHICAL GROUPING PROPOSAL 85 they precede In a binary table on the other hand the data type of the fields containing the parameters does not have such a restriction 5 2 4 2 Multiple Arrays in One HDU While a series of matrices can often be combined into a single primary data array by adding another dimension to do so is not always possible For example consider an array that consists of a digital image accompanied by an array of quality flags each of which corresponds to a pixel on the original image If the data type of the flags differs from that of the image pixels the flags cannot be combined into the primary data array One way is to have the data array and flag arrays as separate image extensions An alternative is to use binary tables Each row
157. not be broken up in the heap However different fields in the same row need not appear in the heap in the order in which they appear in the table Gaps in the heap with no data are possible If two or more table fields have identical contents the descriptors for both may point to the same area of the heap The heap need not begin at the end of the main table data The user may choose to provide a gap between the main table and the beginning of the heap The size of this gap can be found using the value of the THEAP keyword If there is no gap the value of THEAP is NAXIS1xNAXIS2 If there is the size of the gap is the difference between the value of THEAP and NAXIS1xNAXIS2 As an example suppose the main table consists of five 168 byte rows 840 bytes in all but the user wishes to have the heap begin on a new record This construct is provided for purposes of this example it is not necessarily recommended usage The value of NAXIS1 is 168 representing the length in bytes of a row in the table and the value of NAXIS2 is 5 signifying 5 rows There is then a 2880 840 or 2040 byte gap between the main table and the heap The value of THEAP representing the number of bytes between the start of the main table data and the start of the heap is 2880 Suppose further that the heap itself has a length of 5760 bytes The value of PCOUNT is equal to the size of the gap area 2040 plus the size of the heap 5760 or 7800 The storage locat
158. ns have the same overall organization as Basic FITS a header consisting of keyword value ASCII card images followed by data As in Basic FITS the header and data each consists of an integral number of 23040 bit records Except for the SIMPLE keyword which is replaced by an XTENSION keyword the header must use the keywords required for the Basic FITS primary header section 3 1 1 1 As in Basic FITS the data start in the first record following the last header record However as the data structure need not be a simple array there are additional required and reserved keywords for particular structures The developers of the extension concept realized that a set of rules was needed to prevent conflicts between a new extension and Basic FITS random groups or an existing extension The rules that were developed are called the Generalized Extensions Agreement An extension that conforms to these rules is called a conforming extension An extension that has been endorsed by the IAU FITS Working Group or other appropriate authority is called a standard extension All standard extensions are conforming extensions The detailed structure of a conforming extension does not need approval by any authority but the type name must be unique and registered with the IAUFWG A file whose extensions all conform to the rules for generalized extensions is in FITS conformance even if the extensions are not standard extensions and the SIMPLE keyword of the prima
159. nt fields Also many FITS readers would be looking in columns 1 8 to find the keyword and the keywords behind HIERARCH would be inaccessible Special parsers would need to be built The other approach would use a KHBEGIN keyword to signal the beginning of a domain the value would be the domain name Subsequent keywords beginning in column 1 would have the value for that domain A KHEND keyword would signal the end of a domain Domains could be nested Within the domains keywords would begin in column 1 as do the other FITS keywords Critics of this approach argue that the placement of the low level hierarchical keywords in columns 1 8 would mix them with other simple nonstandard FITS keywords existing FITS readers might generate incorrect results and special code would be needed to interpret the keywords properly The difference between these two approaches is not just a matter of detail it is the principle of whether keywords restricted to a particular domain should appear in the first eight columns of the card image or should start in a later column Because this issue has not been resolved by the FITS committees and resolution does not appear imminent do not assume that FITS readers will recognize either scheme For that reason neither approach is discussed further in this document Some installations have implemented a convention similar to the HIERARCH proposal in which a keyword without values such as HISTORY or even
160. numbers in the FITS file In determining the values for DATAMAX and User s Guide Version 4 0 26 SECTION 3 FITS FUNDAMENTALS DATAMIN special values such as the IEEE special values and values derived from integer array members set to the value of the BLANK keyword are not considered Some keywords provide information on the observations represented or the production of the data set e DATE character is the date the file was written dd mm yy note order UT is recommended The value may refer to the creation date of the original file rather than that of the current copy This rule allows files to be copied without changing the value of the DATE keyword Currently date month and year are always two digits with a leading zero if necessary With this format the century is ambiguous e DATE OBS character is the date of data acquisition UT recommended it tells when the observations were made dd mm yy note order Whether this value and that of DATE refers to the start midpoint or end of the relevant time interval is not specified Use comments to say With the turn of the century approaching there have been extensive discussions as to how to distinguish the century when specifying a date A proposal based on the ISO 8601 format is now under consideration by the regional FITS committees e ORIGIN character is the installation where the FITS file is being written e TELESCOP character is the data acquisition
161. nutes of time of right ascension of the position of the star to be added to the hours of the previous field equinox 1950 Besselian RAS starts in column 18 and contains a five digit integer which is 1000 times the number of seconds of time of the right ascension of the position of the star to be added to the hours and minutes of the previous fields equinox 1950 Besselian This design allows storage in integer fields of right ascension accurate to 0 001 second of time DECSIGN is a single character in column 23 giving the sign of the declination Note that as discussed in connection with the TFORMn keywords in section 3 4 1 the sign is in a separate field rather than incorporated into the value of the declination in order to express the distinction between 0 and 0 DECD starts in column 24 and contains a two digit integer with the absolute value of the number of degrees of declination of the position the star equinox 1950 Besselian DECM starts in column 26 and contains a two digit integer with the minutes of arc of the declination of the star to be added to the degrees of the previous field equinox 1950 Besselian DECS starts in column 28 and contains a four digit integer which is 100 times the number of seconds of arc of declination of the star to be added to the degrees and minutes of the previous fields equinox 1950 Besselian This design allows storage in integer fields of declination accurate to 0 01 s
162. ocuments and documents discussing map projections A directory called os support is devoted to code for various environments It contains some software as well as copies of Usenet postings and mailing list announcements discussing other software The information extends back over four years The data directory contains two subdirectories of FITS files The samples subdirectory contains a set of FITS data files from different installations covering a number of disciplines e g Hubble Space Telescope IUE ultraviolet radio VLBA and single dish measurements and illustrating FITS conventions e g world coordinates and grouping The tests subdirectory has under it two subdirectories of test files One ftt4b is a set of FITS files from the early 1980s which contains a number of images from that era designed for testing FITS files and illustrating possible applications of the format including the Mandrill to illustrate one way to store RGB One file also provides a random groups example which can be used for testing by anyone with a need to read older data in that format The other subdirectory pg93 contains test files specially designed for testing the ability of software to handle all standard FITS files including the primary data array and all standard FITS extensions In particular one file contains an array with all the IEEE special values infinity NaN and denormalized numbers The data are artificial with values specially selected
163. ojection plane 4 Determine the projection of the sky onto the coordinate plane of the digital array and deproject from the array plane onto the sky 5 Transform from sky coordinates derived by deprojection to a standard celestial coordinate system 4 2 2 1 Pixel Regularization The first step above is for the case where the array positions of the coordinate points differ from those that would result from the projection from the sky Examples are distortions of astrometric plates caused by imperfect optics or emulsion shrinkage and the effects of ionospheric refractions on radio maps GC describe how to carry out this process through the use of a Pixel Regularization Image This step involves only the correction for small distortions all aspects of the coordinate transformation between the rectangular grid and physical space should be incorporated into the subsequent steps User s Guide Version 4 0 66 SECTION 4 WORLD COORDINATE SYSTEMS 4 2 2 2 Transforming to Projected Sky Coordinate The coordinate system of the FITS file data array will in general be determined by the geometry of the instrumentation consequently the direction of the axes in the FITS file will need to be transformed to a coordinate system more natural to the physical system being measured The initial FITS paper Wells Greisen and Harten 1981 specifies use of the CROTAn keywords for describing how the axes of the FITS array are rotated to yield physical coord
164. olumn n of the table Because the array field must be the same size in all rows the values of the MAXISm will usually be the same for all rows of the table and they can then be given as header keywords instead of table columns MAXISm m 1 MAXIS integer gives the number of elements along axis m in the array contained in the table User s Guide Version 4 0 84 SECTION 5 ADVANCED FITS It is possible for array to have the same size in two rows but different numbers of elements along the axes for example 36 x 6 in one row and 24 x 9 in another In that case the number of elements along each axis must be given in a table column One field call it k will contain the actual data array For this row two keyword value pairs are required TFORMk DATA d TMATXk Il A value of F is understood for the TMATXm keyword for all other columns and need not be included explicitly It is possible to combine this convention with the use of the TDIMn keyword proposed in the binary table paper by setting TDIMk MAXIS1 MAXIS2 where the MAXISm represent the number of elements along axis m that would otherwise be the values of the MAXISm keywords The CLASS package for analysis of radio astronomical data supports the Green Bank convention 5 2 4 Some Applications of Binary Tables 5 2 4 1 Replacing Random Groups As noted in section 3 2 the random groups structure of Greisen and Harten 1981 has been used o
165. ong one or more axes The random groups structure was created to handle such situations Instead of being followed by a data array the primary header is followed by a special set of records of standard FITS 23040 bit size called random groups records These records contain a series of groups each consisting of a sequence of parameters followed by an array The parameters carry the data whose spacing is not uniform and which are not ordered i e random hence the name The number of random parameters and the dimensions of the array must be the same in all groups On application is for uv interferometric visibility data in fact random groups are sometimes referred to as UV FITS Consider a set of weighted complex fringe visibilities for the four Stokes polarizations at a sequence of evenly spaced frequencies The axes are u v w hour angle baseline fringe visibility information real part complex part and weight Stokes parameter and frequency The points along the frequency axis are evenly spaced and the fringe visibility and Stokes axes can both be handled by using evenly spaced integer index points to represent the separate components real complex and weight for the visibility and the four Stokes parameters Thus an individual observation can easily be structured as a matrix with axes of visibility components Stokes parameter and frequency However the individual matrices are at nonuniformly distributed values of baseline
166. or IAUFWG to see if an existing or developing extension can be used to organize your data Inquiries on sci astro fits section 6 2 may also be helpful If a new proposed extension type under development can be used coordinate what you do with the developer If a totally new extension is needed try to design an extension that has as general an application as possible with the eventual goal of adoption as a new standard extension The type name of any new extension NASA GSFC Astrophysics Data Facility 3 4 ASCII TABLE EXTENSION 43 must be registered with the IAUFWG and be different from any already registered The FITS Support Office maintains the current list Special purpose extensions restricted to particular projects with the exception of prototypes for more general designs should be avoided 3 4 ASCII Table Extension Astronomical data are frequently organized in tables for example a standard source catalog or the results of a series of observations Another use for tables is to hold information related to observations such as observing logs and calibration data which are more conveniently transported in a table accompanying the observations than as keywords Not surprisingly the first standard extension developed and endorsed by the IAU was that for tables Harten et al 1988 This ASCII table extension uses ASCII records to carry the information The data appear as a character array in which the rows represent the lines of
167. ord length e For variable block length sequential media such as DDS DAT 4 mm and 8 mm Exabyte cartridge tape physical blocks may contain an integral number of logical records from one to ten the same rule as for 1 2 inch 9 track magnetic tape In the case where the data system is able to generate only fixed blocks the fixed block convention is used Except where a logical record of fewer than 23040 bits serves as an end of file indicator a file should be terminated by the structure for the given medium that corresponds to the tape end of file mark If more than one FITS file appears on a physical structure the end of file indicator appropriate to the medium should separate the files appearing immediately before the start of the primary header of the next file In the original FITS specification the physical block size was set equal to the logical record length for simplicity As time passed however it became clear that a significant number of the major institutes producing data regarded this physical block size as an inefficient use of tape On a 6250 bpi tape only 5596 would contain data and 4596 would be inter record gaps consequently at the same time as the rules for extensions were developed it was agreed that physical blocks on 1 2 inch 9 track magnetic tape could contain one to ten logical records Blocks containing more than one record were called long blocks At that time because the multirecord blocks were new and might not
168. ormation as the conversion between instrument and sky coordinates zero points for temporal and spatial scales conversion between table values and physical values and the instrument configuration The table would contain such information as the coordinates in the detector reference frame of the individual events the time of an event the energy of an event and the strength or intensity of an event Example 7 in Appendix shows a different FITS header for high energy astrophysics data from the Advanced Satellite for Cosmology and Astrophysics ASCA NASA GSFC Astrophysics Data Facility 107 Section 6 Resources 6 1 The FITS Support Office NASA has established the Flexible Image Transport System Support Office to assist FITS users and work with the astronomical community on the development and documentation of FITS The FITS Support Office is a service of the Astrophysics Data Facility at NASA Goddard Space Flight Center The principal purposes of the FITS Support Office are to assist NASA projects in developing FITS data sets to provide FITS information to the astronomical community and the public and to take an active role in the evolution of FITS Toward these ends it has developed an on line library of information documents and software available either through the World Wide Web or through anonymous ftp Documents developed by the FITS Support Office are available in printed form as well The FITS Support Office also will
169. osting describing where FITS information can be obtained which is posted as well to the newsgroups sci answers and news answers and is consequently automatically available at Usenet FAQ archives The exploder dishfits nrao edu was created to facilitate discussions on the subject of FITS formats for single dish radio astronomy This exploder is now gatewayed to the newsgroup adass fits dishfits To subscribe send electronic mail to dishfits request nrao edu Traffic on this exploder is archived at the NRAO site HEASARC has set up an electronic mail listserver called heafits for FITS issues that are specific to high energy astrophysics To subscribe to the heafits list send the following one line electronic mail message to listserv legacy gsfc nasa gov subscribe heafits Your Name where Your Name is your actual first and last names Messages to the actual mailing list should be sent to heafits legacy gsfc nasa gov An archive is at http heasarc gsfc nasa gov listserv heafits maillist html There is a link to it from the HFWG page n anonymous ftp directory of FITS material is maintained at the European Southern Observatory Its address is ftphost hq eso org IP 134 171 8 4 User s Guide Version 4 0 120 SECTION 6 RESOURCES NASA GSFC Astrophysics Data Facility 121 Appendix A Examples of FITS Headers Example 1 VLA Image Header Note The first two lines following are provided to help the reader determine
170. ot and need not understand Simplicity requires that reading and writing FITS should be implemented in a fairly straightforward way on any computer used for astronomical reduction and analysis Simplicity also implies that the structure of the file should be self defining and to a large degree self documenting The first word in FITS is flexible The format needs to be flexible to facilitate extensibility for different applications Hence the number of strict rules is not large Because the files are self defining FITS can fulfill a large range of data transport needs FITS can be used not only for unambiguous transportation of n dimensional regularly spaced data arrays but also for additional information associated with such a matrix FITS can also transport arbitrary amounts of text within standard data files The history of manipulations of the data can thus easily be recorded in self documenting data files FITS is sufficiently general for a wide variety of applications The introduction of new keywords permits addition of new information as needed and the use of extensions allows almost unlimited flexibility in the type of information to be stored Thus FITS can grow with the needs of the astronomical community The great flexibility of FITS is a potential weakness as well as a strength While there is a great temptation to proliferate keywords and new extension types caution should be exercised in this process Because FITS
171. overflows when scaling floating point numbers NASA GSFC Astrophysics Data Facility 3 6 BINARY TABLES 53 For L X and A format fields the TSCALn and TZEROn keywords have no meaning and should not be used The meaning has not been formally defined for P format fields but the general understanding is that the scaling should apply to the heap data pointed to by the array descriptors e TNULLn integer has the value that signifies an undefined value for the integer data types B I and J It should not be used if the value of the corresponding TFORMn specifies any other data type Null values for other data types are discussed in section 3 6 3 e TDISPn character has a value giving the Fortran 90 format recommended for display of the contents of field n If Fortran 90 formats are not available to the software printing a table FORTRAN 77 formats may be used instead All entries in a single field are displayed with the same format If the field data are scaled the physical values derived by applying the scaling transformation are displayed For bit and byte arrays each byte is considered to be an unsigned integer for purposes of display Characters and logical values may be null zero byte terminated The following formats are allowed Lw Logical Aw Character Iw m Integer Bw m Binary integers only Ow m Octal integers only Zw m Hexadecimal integers only Fw d Single precision real no exponent Ew dEe Single precision r
172. p without repeating the HDU e It provides a means for associating HDUs that are in different files even those in different physical locations into logical groups The last feature is becoming particularly useful as the fraction of data available on line has increased and access from one computer to data on another has become routine Related data may now be stored in separate locations and accessed electronically instead of putting separate copies of all the related data on several machines Jennings et al provide an illustration of where such a convention would be useful Consider a set of observations each of which has associated with it an observation log event list derived image and calibration data and for which many observations share the same calibration data It would be possible to logically associate each log event list image calibration set into a separate group in addition the same calibration data HDU could belong to many groups but would only need to be stored once Another possible group would be one of observations of the same object at different times and these observations could be combined into a group even though they might reside on multiple FITS files n extension HDU called a group table defines a group and its members This table may be either an ASCII table extension XTENSION TABLE ora binary table XTENSION BINTABLE Group tables are required to contain the following keywords in the header
173. r 1 SIMPLE logical T indicates a file in conformance to standard FITS 2 BITPIX integer describes the representation of the values of the individual arrays and of the parameters The parameters must be of the same data type as the array members The values have the same meaning as for Basic FITS NASA GSFC Astrophysics Data Facility 3 2 RANDOM GROUPS 35 3 NAXIS integer is one more than the number of axes in each array because NAXIS1 is used as a groups indicator instead of an actual axis The largest possible value is 999 representing 998 axes 4 NAXIS1 integer is set to 0 to indicate that no primary data array follows the primary header 5 NAXISn n 2 NAXIS integer is the number of elements along axis n 1 of the array The index varies most rapidly along the n 2 axis least rapidly along the n 2NAXIS axis There must be no other keywords between the ones listed above Additional keywords follow which must include among them e GROUPS logical must have the value T to indicate that the data records following the primary data array are random groups e PCOUNT integer is the number of parameters preceding each data array e GCOUNT integer is the number of groups parameters 4 array in the random groups records e END no value is the last keyword The header is filled with ASCII blanks The PCOUNT and GCOUNT keywords tell the reader the number NBITS of bits in the random g
174. r an image extension because Random Groups have largely fallen into disuse and are not recommended for future use the decision was not to allow Random Groups records 2 8 Binary Tables One drawback of the ASCII table format was the space required by tables with a large number of entries such as gain and calibration tables because every number appeared in coded form In addition conversion of the entries in these tables to ASCII would be very time consuming Initially the ASCII form had been needed to represent floating point numbers The precise definition and general acceptance of the IEEE floating point format made it possible to include binary floating point numbers in table fields Meanwhile developers of software to write FITS files for results of the Very Long Baseline Array project found that it would be useful to be able to put vectors in table fields A design for binary tables with vector fields was developed by W Cotton NRAO Because the vector field might be thought of as a column rising out of the page it was User s Guide Version 4 0 14 SECTION 2 HISTORY imagined to be a third dimension of the table and the extension was given the type name A3DTABLE This name was chosen rather than for example 3DTABLE to signify that the extension might still undergo further development the final version would have a new name This 3 D table extension was released as part of the NRAO Astronomical Image Processing System AIPS
175. r bytes each and one double precision floating point number eight bytes for a total of 27 bytes equal to the value of the NAXIS1 keyword description of the DIRBE data products is available at http ssdoo gsfc nasa gov astro cobe dirbe products html User s Guide Version 4 0 146 APPENDIX A EXAMPLES OF FITS HEADERS Example 7 ASCA FITS Header The first two lines following are provided to help the reader determine column numbers They are not part of FITS headers 00000000011111111111222222222233333333333444444444455555555556666666666777 12345678901234567890123456789012345678901234567890123456789012345678909012 XTENSION BITPIX NAXIS NAXIS1 NAXIS2 PCOUNT GCOUNT TFIELDS TTYPE1 TFORM1 TUNITi TTYPE2 TFORM2 TUNIT2 TLMIN2 TLMAX2 TTYPE3 TFORM3 TUNIT3 TLMIN3 TLMAX3 TTYPE4 TFORM4 TUNIT4 TLMIN4 TLMAX4 TTYPES TFORMS TUNITS TLMINS TLMAX5 TTYPE6 BINTABLE TIME 1D PI 1J gt channel X 1I pixel Y 1I pixel RAWX 1I pixel RAWY N 30 22990 o NNN YN YS YS YS S 11 0 NNN binary table extension 8 bit bytes 2 dimensional binary table width of table in bytes number of rows in the table size of special data area one data group required keyword number of fields in each row arrival time of the X ray data format of the
176. r containing the CCD Y axis pixel location of the event with no corrections the axis runs from 1 to 422 7 PHA is a 2 byte integer containing the pulse height energy channel number of the data for this photon with no gain correction The channel numbers run from 0 to 4095 8 DETX is a 2 byte integer containing the X axis pixel location of the event in detector coordinates corrected for instrument distortion the axis runs from 1 to 1280 9 DETY is a 2 byte integer containing the Y axis pixel location of the event in detector coordinates corrected for instrument distortion the axis runs from 1 to 1280 10 GRADE is a 2 byte integer describing the shape of the event used as a quality indicator Grade numbers run from 0 to 4 11 CCDID is a 2 byte integer identifying the CCD number which runs from 0 to 3 Each row has nine two byte integers one four byte integer and one double precision floating point number eight bytes for a total of 30 bytes equal to the value of the NAXIS1 keyword The remaining keywords are grouped Each group is preceded by a centered descriptive heading the first eight characters are blanks and thus the headings are treated as comments Under General Descriptive Keywords are keywords that identify the extension and its content The name corresponding to a table title is EVENTS EXTNAME keyword The HDUCLASS keyword identifies the authors of the file format and conventions as OGIP and HDUCL
177. r detail how widely the different proposed conventions are used in the general community The discussion of the three proposed binary table conventions which are not part of the formal structure endorsed by the IAUFWG remains in section 5 The discussion of applications of binary tables has been significantly expanded and User s Guide Version 4 0 ii descriptions of a number of binary table and other conventions have been added Section 6 has been rewritten to emphasize network sources of FITS information and it discusses a number of sites on the World Wide Web that contain FITS documents software and sample files Many of these sites did not exist when version 3 1 of the User s Guide was written and others have been greatly expanded since Three additional sample FITS headers one using an ASCII table and two using binary tables have been added to Appendix A Appendix B lists the IEEE floating point number type corresponding to every bit pattern Thanks for comments on an earlier draft of version 4 go to M Calabretta D Jennings W Pence and R Thompson Also thanks to D Leisawitz for providing the DIRBE FITS header example 6 and W Pence for providing the ASCA FITS header example 7 To be of most use to readers a guide such as this one must go beyond the formal rules to discuss common practices that are not specified by those rules In addition users who are designing and developing FITS files need to know how FITS is likel
178. r that might be written for a simplified binary table structure for spectra proposed by D Wells 5 10 High Energy Astrophysics Applications The natural form for storing data for high energy astrophysics is as a table of events Consequently binary tables are used extensively for high energy User s Guide Version 4 0 106 SECTION 5 ADVANCED FITS astrophysics data One example of a design for such tables is that for data from the High Resolution Imager on ROSAT e The primary header in addition to the required keywords contains data set identification and history NAXIS is set to zero there is no primary data array e The first extension is a Good Time Intervals table identifying those time intervals during which the data received from the satellite can be regarded as valid measurements Each row of this table consists of two double precision floating point fields listing the start time and end time of a time interval where the data are valid e The next extension is the Events table including most of the data from the native time ordered event file e The actual columns in the ROSAT tables contain an information structure governed by the way in which the ROSAT readings are organized The kind of information obtained from any high energy experiment could be organized in a similar table The header could in addition to the card images describing the structure of the table use keyword value statements to convey such inf
179. ranformations the temptation may be to use the standard keyword names as table headers Doing so however would lead to a situation in which the same name had different meaning in the header and body for example when NAXIS 2 in the header it refers to the dimensions of the data table in the same HDU but in TTYPEn NAXIS it refers to the dimensions of arrays in a different HDU Again the standard keyword names should not be used The most recent version of the World Coordinates proposal includes a description of conventions proposed by HEASARC These conventions are available on the HEASARC and NRAO World Wide Web sites discussed in sections 6 2 and 6 3 5 6 3 Compression Proposals for ways to include compressed data in FITS files are still under development A preliminary proposal by Warnock et al 1990 is available from the NRAO ftp directories described in section 6 2 However there are some compression related questions this proposal does not address Other installations are experimenting with local schemes 5 6 4 Other Reserved Type Names In the original FITS design intended for half inch magnetic tape the end of a file could easily be identified by a tape end of file mark Not all other media support such a clear hardware delimiter D Wells has proposed the creation of a NASA GSFC Astrophysics Data Facility 5 7 KEYWORD DOMAINS 101 FILEMARK extension which would represent an end of file on media where the end
180. rdinate system derived by deprojection need not be in the same direction as those of the standard celestial coordinate system GC provide equations for the transformation The following keywords are reserved e LONGPOLEn floating for longitude of the pole is the longitude of the North Pole of the standard coordinate system in the native coordinates e LATPOLEn floating is used in special cases when two values for declination of the north pole of the native system as measured in the standard system are consistent with the projection and the value of LONGPOLE it determines which is used LONGPOLE is understood to have a default value of 0 or 180 where possible The choice depends on the latitude of the reference point in the standard system and in the native system if the latitude in the standard system is greater LONGPOLE is 0 if the latitude in the native system is greater it is 180 With this convention celestial latitude and native latitude increase in the same direction at the tangent point A detailed discussion of the transformations and the application of the reserved keywords can be found in GC and is beyond the scope of this Guide GC adopt the AIPS convention of using the first four characters of the value field of the CTYPEn keywords to identify the standard system as shown in Table 4 2 Table 4 2 Identification of Sky Coordinate Systems RA DEC equatorial coordinates a 6 GLON GLAT galactic coordinates
181. reasing significance The BLANK keyword is ignored by FITS readers when BITPIX 32 or 64 For a complete precise description of the IEEE floating point format refer to the IEEE standard The following discussion is provided to help in the interpretation of floating point data An ordinary IEEE floating point number consists of three components a sign an exponent and a fraction For regular IEEE 32 bit floating point numbers the sign is contained in bit 1 the exponent in bits 2 9 and the fraction in bits 10 32 The fraction has an implied binary point in front The value is given by value 1 8 8 x o exponent 127 x 1 fraction 3 3 For regular IEEE 64 bit floating point numbers the sign is contained in bit 1 the exponent in bits 2 12 and the fraction in bits 13 64 The fraction has an User s Guide Version 4 0 32 SECTION 3 FITS FUNDAMENTALS implied binary point in front The value is given by value 1 8gn x o exponent 1023 x 1 fraction 3 4 Fraction bytes are in order of decreasing significance i e the standard non byte swapped order For example suppose the single precision 8 bit byte pattern is 40400000 The sign bit is 0 the exponent bit pattern is 100 0000 0 or 128 and the fraction pattern is 1 followed by 22 0s with a binary point in front or 0 5 decimal The entire number is interpreted as 1 x 2028127 x 1 5 3 3 5 The IEEE standard specifies in addition a variety of
182. rmation A general discussion of software to convert between formats including FITS is in part 2 of the Graphics File Format FAQ which is periodically posted to the newsgroups comp graphics misc comp answers and news answers It is also archived at ftp rtfm mit edu pub usenet and http www cis ohio state edu hypertext faq usenet faqs The MIT site is often busy The Ohio State site is occasionally reorganized with changes in the lower level of the URL 6 5 Other Network Resources A Usenet newsgroup sci astro fits is devoted to FITS For those who prefer there is an associated fitsbits mailing list To subscribe send electronic mail to fitsbits request fits cv nrao edu This newsgroup mailing list is the principal forum for FITS discussions and announcements Developments in the evolution of new extensions will appear there reservation of type names information on where to find particular proposals discussions of the proposals NASA GSFC Astrophysics Data Facility 6 5 OTHER NETWORK RESOURCES 119 and notification of actions by the regional and international FITS bodies The FITS Support Office uses this forum to announce developments such as progress on updates to the standard or a new edition of this User s Guide Developers of publicly available FITS software packages also announce their packages here In addition to the announcements there is general discussion of FITS practices The FITS Support Office maintains a monthly p
183. roups records exclusive of fill NBITS ABS BITPIX x GCOUNT x PCOUNT NAXIS2 x NAXIS3 x x NAXISm 3 7 where m is the value of NAXIS 3 2 1 2 Random Parameter Reserved Keywords The random parameters may be labeled and scaled in a fashion similar to the members and axes of a Basic FITS array using the keywords PSCALn and PZEROn physical_value FITS_ value x PSCALn PZEROn 3 8 The following keywords are reserved for describing random parameters User s Guide Version 4 0 36 SECTION 3 FITS FUNDAMENTALS e PTYPEn character is the name of the quantity represented by the nth random parameter e PSCALn floating gives the scale factor for random parameter n If this keyword is absent the scale factor is assumed to be 1 e PZEROn floating gives the offset for random parameter n If this keyword is absent the offset is assumed to be zero Even though the random parameters must have the same data type as the array elements greater precision can be achieved in the random parameters than in the data array through the use of repeated PTYPEn keywords If more than one PTYPEn keyword has the same value then the parameters associated with all those PTYPEn keywords are being used to represent the same quantity The value of that quantity is derived by summing the true values derived for the parameters n corresponding to those PTYPEn keywords the values derived using the stored values and the PSCALn and PZEROn va
184. row of the table The maxelem value which the wording in CTP includes as an essential component of the keyword value allows software to read the table directly into a data base that supports only fixed size data arrays without first having to read the table solely to determine the size of the arrays Without it the task of the reader is more complicated The P tells the reader that the actual contents of the field in the main table will not be the data array but the descriptor For example the card image NASA GSFC Astrophysics Data Facility 5 2 CONVENTIONS FOR BINARY TABLES 79 TFORM8 PB 1800 Variable length byte array signifies that field 8 of the table should be regarded as logically containing a byte array of up to 1800 elements here bytes The actual physical contents of field 8 are two 32 bit integers The first 32 bit integer is the number of heap elements to be considered a part of the current row This value may differ from row to row but in the illustration here cannot exceed 1800 A row in the table data may have a value of zero in this field thus providing for fields where data are not present in every row The second 32 bit integer is the offset of the start of the byte array from the beginning of the heap counted in number of bytes An array starting at the beginning of the heap has an offset of zero The remaining elements of the array follow in sequence in the heap the contents of a single field of a single row can
185. rt time is also specified in Modified Julian Date form using the widely used MJD OBS intended as a standard under the World Coordinates proposal The MJDREF TIMEREF TIMESYS and TIMEUNIT keywords define the time system and scale used for the TIME column of the main table and for expressing the start and stop time of the observations using the TSTART and TSTOP keywords The ORBITBEG and ORBITEND keywords identify the orbit numbers of the start and stop of the observation The other keywords provide information on the elapsed times of observation and on defining the time scales The Position Related Keywords describe coordinate systems The RADECSYS keyword is the World Coordinates convention keyword defined in section 4 3 and identifies the coordinate system used as the FK5 the system in use since the 1976 IAU EQUINOX identifies the coordinate system as precessed to the year 2000 000000 The next eight keywords describe the direction in which the instrument points Right ascension and declination are always given in degrees The RA PNT and DEC PNT keywords are specifically listed among the standard HFWG keywords The next 14 keywords describe the coordinate systems in which the event positions of columns 3 4 and 8 9 are defined one of the cases defined in section 5 6 2 Keywords similar to the standard coordinate keywords of section 3 1 1 2 but with one intermediate letter omitted and prefaced by T are used Columns 3 and 4 describe a position in a
186. ry header should have the value T Two basic rules govern all existing extensions and serve as the foundation for the more detailed requirements for generalized extensions User s Guide Version 4 0 38 SECTION 3 FITS FUNDAMENTALS e All FITS extensions must appear after the main FITS header and its associated primary data array e Each extension begins at the start of a new 2880 byte record The generalized requirements for FITS extensions are as follows e Extensions should have the same structure as the Basic FITS HDU header plus data The extension should be self defining and the header readable both by people and machines The rules that apply to creating FITS headers also apply to extension headers they should contain a required set of standard keywords and consist of ASCII text card images While the information in an extension may be of any length the extension as a whole must be filled to an integral number of 23040 bit records e Only the binary and character coding conventions specified in the original FITS papers and the Floating Point Agreement should be used in FITS extensions e It should be possible to append any number of extensions to a primary header and its associated data array e If there is more than one type of extension in a FITS file then the extensions may appear in any order e Existing FITS formatted data including those with standard extensions must be compatible with the new extension standard
187. s No current document precisely and formally describes the structure and syntax of FITS The IAUFWG has endorsed the six FITS papers Wells Greisen and Harten 1981 Greisen and Harten 1981 Grosbgl et al 1988 Harten et al 1988 Ponz Thompson and Muiioz 1994 Cotton Tody and Pence 1995 and the floating point and blocking agreements By permission of the copyright holder the European Southern Observatory the FITS Support Office can furnish copies of the the first four FITS papers to non profit organizations The text of the Floating Point Agreement appears in section 3 1 2 3 of this Guide and the Blocking Agreement is available electronically from the FITS Support Office at ftp nssdc gsfc nasa gov pub fits blocking94 txt Largely because the format has evolved incrementally there are a number of inconsistencies and ambiguities among the FITS papers especially the first four To provide a document with a clear and unambiguous specification of the rules of FITS the NASA Science Office of Standards and Technology NOST has developed a formal FITS codification the Definition of FITS NOST 1995 This NOST standard was developed by technical panels of astronomers chaired by R Hanisch STScI chair of the Working Group on Astronomical Software of the American Astronomical Society The FITS Support Office coordinator served as secretary of the panel and the FITS office was responsible for writing the original text and for the bulk of the
188. s NAXIS2 each of which has seven fields TFIELDS which take up a total of 27 bytes per row NAXIS1 There is no heap for variable length arrays PCOUNT BITPIX and GCOUNT have the required values as described in section 3 6 1 Like the primary HDU the extension header uses a COMMENT in the keyword field for blank lines Before the table description are a number of keywords describing the time of the observation The COMMENT lines outline the meaning of the keywords and their values and provide a reference TIMVERSN with more details MJDREFI and MJDREFF give the ephemeris Modified Julian Date corresponding to the zero point of the time system also specified by TIMESYS TSTART and TSTOP give the time of the measurements in seconds TIMEUNIT after the zero point NASA GSFC Astrophysics Data Facility 145 The keywords describing the table follow Detailed explanatory comments are provided at the top and after the keywords for each field All fields have a short title TTYPEn keyword of eight characters or fewer The titles are mixed case but FITS software should not attribute any significance to the case the value is to make it easier for human readers to understand the file The COMMENTs furnish the full field titles and provide detailed explanations Other COMMENTs are used to format the table for easier examination by human readers The creators of the file have chosen to include a TUNITn keyword for every field with a blank value if
189. s Guide Version 4 0 24 SECTION 3 FITS FUNDAMENTALS physical value FITS_value x BSCALE BZERO 3 2 If this keyword is not present the scale factor is assumed to be 1 e BZERO floating is the offset the physical value corresponding to a stored array value of zero in equation 3 2 If this keyword is not present the offset is assumed to be zero Be careful about possible overflows when using BSCALE and BZERO if the array elements are floating point value of BITPIX 0 Pay attention to the likely order of magnitude of the resulting values and be prepared to trap overflows if necessary While the values of BZERO and BSCALE are floating point the rules of FITS do not specify the data type of the result of scaling as this result is not part of the FITS file Whether the result is to be considered an integer or real number depends on the physical significance of the number e BLANK integer If the text BLANK appears in columns 1 8 then the value will be stored in those elements of an integer array that have an undefined physical value The value of BLANK appears in the actual data array without scaling It should be regarded as a code not a number a scaling transformation with BSCALE and BZERO should not be applied to array members that have the value given by the BLANK keyword Do not use this keyword if the FITS data array is IEEE floating point becuse this function is performed by the IEEE floating point NaN T
190. s are observed In addition to the actual observations other information say about the observing system configuration or physical state might be present Some information might apply to the entire observing session while other information would apply only to the observations of an individual object In this case an extension at EXTLEVEL 1 could contain the information applying to the entire observing session as part of the header while some information about the observations of individual objects could appear in the associated data in a master table Each row in the master table would contain information about the observations of one object One entry in each row would be the name of a table containing observations of that object The observations would appear in separate table extensions with EXTLEVEL 2 and EXTNAME equal to the name given in the master table This concept has yet to be implemented in data for archive or distribution and any software to support it is still in the developmental stage The grouping proposal discussed in section 5 3 describes an alternative method of creating hierarchies 3 3 3 Creating New Extensions Use an existing standard extension type if you can to do so facilitates use of existing analysis packages New extension types are necessary only when information is organized in a way that existing extension types can t handle Before starting to develop a new format check with the FITS Support Office
191. seful for those new to FITS The FPCT checks the primary header of a FITS file for the presence of all required keywords and their order If it can retrieve information User s Guide Version 4 0 112 SECTION 6 RESOURCES values of BITPIX NAXIS and the NAXISn needed to read the primary data array and the data in the array are integer it will at the user s option produce an output file containing array members selected by the user If the header is in conformance it will print a message to that effect If the header is not in conformance but the software has inferred a data description it will print a warning that retrieval of the data array may not be correct with an indication of the severity of the problem If the FPCT has been unable to retrieve the information needed to read the primary data array it will print a diagnostic with information about the header errors and stop Both packages are available in the software subdirectory of the FITS anonymous ftp directories described in section 6 1 1 or can be obtained electronically by request from the FITS Support Office The FPCT is accompanied by an instructions file Read this file before using the software The errtest subdirectory contains a number of primary HDUs designed for checking the ability of FITS readers to cope with the unexpected It includes one that is in compliance with the standard and a number of others that are identical except for deliberately inserted errors
192. sence of this keyword also warns software that is changing the position of the HDU that the HDU is a member of a group naming the group table where entries used for identification by position will need to be changed e GRPLCn character gives the URI for group table n It is not necessary if the value of GRPIDn is positive An HDU may be a member of many groups H the HDU is a member of m groups then there will be GRPID1 GRPIDm keywords each identifying one of these groups If the value of a particular GRPIDn is negative it is the negative of the group identification number the value of EXTVER in the group table the group table is not in the same file as the member and there will be a GRPLCn keyword with the URI where the group table is located The Jennings e al proposal presents a number of illustrations As of this writing it is available at http wwwadf gsfc nasa gov other convert group html 5 4 STScI Inheritance Convention The rules of FITS do not specify whether or not keywords in the primary header apply to extension data in the same file STScI has adopted the following conventions governing such inheritance of keywords Zarate and Greenfield 1996 1 Primary header keywords can be inherited only if there is no primary data array User s Guide Version 4 0 90 SECTION 5 ADVANCED FITS 2 Primary header keywords apply to extensions only if the header contains the keyword INHERIT with the value set to T
193. sing the CTYPEn values to be used to identify future coordinate systems and projections e Is the description of the common projections e g SIN TAN now too complicated e Should all of the projections be included if this proposal is adopted as the standard or should only the basic projections be included with the rest as appendixes Keep up with the current discussion in the forums described in section 6 Make certain that the community has reached agreement in the areas described above before implementing any of those features in archival data sets User s Guide Version 4 0 74 SECTION 4 WORLD COORDINATE SYSTEMS NASA GSFC Astrophysics Data Facility 75 Section 5 Advanced FITS 5 1 Registered Extension Type Names Extension type names must be unique a particular type name may refer to only one structure In order to avoid duplication all extension type names must be registered with the IAU FITS Working Group even if the extension type is being used by only a single organization internally To register a FITS extension name contact either the FITS Support Office at fits nssdca gsfc nasa gov or the chair of the IAUFWG at dwells nrao edu Provide a short description and justification with the request for registration Reserve extension type names when their use is planned even though details of the structure have not been worked out Table 5 1 lists the FITS extension type names and their registered status with the I
194. special exponent and fraction values in order to support the concepts of plus and minus infinity plus and minus zero denormalized numbers and not a number NaN The BLANK keyword of the original FITS Agreement is thus unnecessary and should be omitted by FITS writers and ignored by FITS readers when BITPIX 32 or 64 the NaNs of the IEEE format will act as the blank FITS writers should not write the BLANK keyword if BITPIX 32 or 64 For denormalized numbers 1 is not added to the fraction and the offset subtracted from the exponent is one smaller than for regular numbers 126 for single precision and 1023 for double precision This convention allows IEEE floating point to represent numbers that are smaller than those represented by the regularly defined values although the number of significant digits decreases for smaller values All of these special cases are fully accepted for FITS interchange Appendix B lists the kind of value regular or special represented by all possible bit patterns The BSCALE and BZERO values should be applied by FITS readers if they differ from 1 0 and 0 0 However scaling parameters should be used carefully with floating point values because of the risk of generating overflows and underflows after scaling has been applied 3 2 Random Groups The random groups structure Greisen and Harten 1981 was originally designed for applications in radio astronomy but was intended for other appl
195. st be in capitals e Complex Consists of real and imaginary components integer or floating point anywhere in columns 11 80 separated by at least one column Any information in a character string value that the reading software needs to retrieve the data from the FITS file should be in the first eight characters for the benefit of primitive systems Users should name their strings accordingly If the string is used only to provide descriptive information or in the scientific interpretation of the file it is not critical to have the meaning clear from the first eight characters but it 1s still a good idea NASA GSFC Astrophysics Data Facility 3 1 BASIC FITS 21 Comments may be incorporated in a header card image whether or not a value is present If a value is present place a slash hexadecimal 2F between the value and comment field with at least one blank between the end of the value and the slash For the fixed format the slash and space are not required but using them when writing a FITS file will simplify the task of the reader If the fixed format is not used a slash serving as a delimiter a requirement derived from FORTRAN list directed read is required before the comment If the keyword has no associated value which is immediately apparent when column 9 does not contain then the entire content of columns 9 80 is a comment In such a case it is best to leave column 9 blank The first keyword in a header must be
196. t Structuring extensions in this way made it easy to modify software that read the FITS header for the primary array to read extension headers as well Information about the extension data would appear in the extension header in a way specified by the rules for that extension All logical records would be 23040 bits 2880 8 bit bytes as the original paper describing FITS prescribed for information following the primary HDU The HDU itself is called an extension The design is called an extension type User s Guide Version 4 0 10 SECTION 2 HISTORY The requirement that no revision to FITS could cause an existing FITS file to go out of conformance dictated a number of the basic rules governing the construction of new extensions In the original FITS data sets the Basic FITS structure of header and array appeared at the start of the file Therefore extensions would appear only after the primary Basic FITS header and array Because the initial array ended only at the end of a 23040 bit record an extension would always start a new record It was envisioned that most FITS extensions would become standard in the same way as Basic FITS through acceptance by the astronomical community and endorsement by the IAU An extension would go through a development period initially being used only by a subset of the FITS community that would refine it Other extensions might be in use only within a limited group and might never become standard at all
197. ta dropouts or from operations that are undefined like a divide by zero For 16 bit integers the most commonly used value of BLANK is 32768 but users may choose the value most appropriate for NASA GSFC Astrophysics Data Facility 3 1 BASIC FITS 31 their data The BLANK keyword is not used for floating point data where the IEEE NaN identifies undefined values 3 1 2 3 IEEE Floating Point Data FITS allows transmission of 32 and 64 bit floating point data within the FITS format using the IEEE 1985 standard This Floating Point Agreement also applies to random groups records and to any extensions for which BITPIX is not explicitly restricted e g BITPIX 8 for XTENSION TABLE Values for BITPIX of 32 and 64 indicate IEEE single and double precision floating point data respectively The text of the Floating Point Agreement Wells and Grosbgl 1990 is as follows The Basic FITS Random Groups and Generalized Extensions Agreements are revised to add IEEE 754 32 and 64 bit floating point numbers to the original set of FITS data types BITPIX 32 and BITPIX 64 signify 32 and 64 bit IEEE floating point numbers the absolute value of BITPIX is used for computing the sizes of data structures The full IEEE set of number forms are allowed for FITS interchange including all special values e g the not a number cases The order of the bytes is sign and exponent first followed by the mantissa bytes in order of dec
198. table This issue was raised by D Tody at the April 1991 European FITS Committee meeting Following discussions outside the formal sessions by a number of the participants Cotton and Tody presented a design with a pointer data type which was modified slightly in the discussion at the meeting formal text with appendixes describing possible formats for multidimensional fields and variable length arrays and incorporating the keywords and field formats to make these structures possible was released by Cotton and Tody in October 1991 As early as July 1991 W Pence GSFC HEASARC had raised questions about how an array of strings was to be distinguished from a single long string The ensuing electronic discussion led to the addition of a third appendix describing a substring array convention The revised BINTABLE proposal with this appendix added was released by Cotton Tody and Pence in May 1993 In the spring of 1994 after a few points had been clarified the IAUFWG endorsed the main NASA GSFC Astrophysics Data Facility 2 9 HOW FITS EVOLVES 15 proposal as part of standard FITS The three appendixes multidimensional arrays variable length arrays and arrays of strings were not included as part of the endorsed standard they are considered recommended but not required conventions However they have a special place in that the BINTABLE extension contains a number of provisions especially designed to make them possible Init
199. telescope e INSTRUME character is the data acquisition instrument e OBSERVER character is the observer name or other identification e OBJECT character is the object observed e AUTHOR character identifies who compiled the data associated with the header Use this keyword when the data come from a published paper or have been compiled from many sources It refers to the author of the data being carried by the FITS file not to the creator of the computer readable form It should not be used to identify the software that created the FITS file or the writer of that software The CREATOR keyword section 5 6 1 has been suggested to identify the software creating a FITS file e REFERENC character is the bibliographic reference for the data associated with the header NASA GSFC Astrophysics Data Facility 3 1 BASIC FITS 27 e EQUINOX floating is the equinox of the coordinate system in years In early FITS data sets the keyword EPOCH was used with this meaning Since the term epoch has a different meaning referring to the actual date of observation the correct term EQUINOX should be used in the future EPOCH will still be accepted with this meaning in old data sets and should not be otherwise used Software to read FITS data sets should interpret EPOCH as equivalent to EQUINOX The epoch or date of observation can be given as the value of the DATE OBS key word e BLOCKED logical deprecated when set to the value T
200. tep using a matrix that is the product of the CDELTn which may be thought of as a diagonal matrix and the PC matrix This matrix called the coordinate description CD matrix described the tranformation from the array coordinates in pixel units to the physical coordinate in physical units It was represented using keywords of the form CDi_j by the Space Telescope Science Data Analysis System Image Reduction and Analysis Facility STSDAS IRAF version 3 1 of this Guide FITS readers should be prepared to encounter it in some existing data sets 4 2 2 4 Deprojection The plane coordinates in physical units represent a projection of the celestial sphere This projection is not unique and different projections may be useful for different purposes Maps of the earth for example may be Mercator equal area or some other projection depending on the intended use In this step the projection is reversed and the plane coordinates are transformed back to the projected sphere AIPS memo 27 Greisen 1983 identified four common choices which are discussed here because of their wide use For three of these four projections the choice for the tangent point the point common to the celestial sphere and the plane on which it is projected is arbitrary AIPS adopted the convention that the reference pixel given by the values of CRPIXn is at this tangent point If the tangent point of the projection is outside the image then the values of the CRPIXn
201. that none of the existing standard or proposed FITS formats will organize the data properly proposal is developed and a name chosen for the new extension type This name must then be registered with the IAUFWG It must be different from any name previously registered The FITS Support Office maintains a list of the registered extension type names and will forward name registration requests to the IAUFWG In some cases a temporary local form of the extension with a different name will be be defined as well This local name must also be registered with the IAUFWG The local or developmental form may serve as the basis for designing data sets elsewhere while the full proposal is being developed User s Guide Version 4 0 16 SECTION 2 HISTORY as occurred with A3DTABLE During this period the developer will discuss concepts of this new extension with others interested in the format and may modify it based on this discussion Eventually a formal proposal will be made available for review by the astronomical community normally by announcing World Wide Web WWW and ftp locations where it can be obtained With the more general use of FITS and the increasing ease of electronic transmission of documents proposals are becoming available to a wider public at earlier stages than was the case during the early days of FITS Tests are run using the new format to confirm that it can be practically used for data transport After the community has reviewe
202. the table is SPECTRUM EXTNAME keyword this table could be the second version or perhaps the second spectrum in the FITS file EXTVER keyword User s Guide Version 4 0 132 APPENDIX A EXAMPLES OF FITS HEADERS Example 5 ADC FITS Table Header for AGK3 Catalog Note The first two lines following are provided to help the reader determine column numbers They are not part of FITS headers 000000000111111111122222222223333333333444444444455555555556666666666777 123456789012345678901234567890123456789012345678901234567890123456789012 XTENSION TABLE gt Table extension BITPIX 8 Character data NAXIS 2 Simple 2 D matrix NAXIS1 80 Number of characters per record NAXIS2 183145 Number of records in the table PCOUNT 0 No random parameters GCOUNT 1 Only one group TFIELDS 22 Number of data fields per record EXTNAME AGKS3 AGK3 Star Catalogue of Positions AUTHOR Dieckvoss W REFERENC 1975 Hamburg Bergedorf DATE 15 09 88 Date FITS file verified dd mm yy HISTORY Source Catalog Reference AGK3 Star Catalogue of Positions and Proper HISTORY Motions North of 2 5 Degrees Declination Dieckvoss W in HISTORY collaboration with H Kox A Guenther and E Brosterhaus 1975 HISTORY Hamburg Bergedorf HISTORY HISTORY copy of Documentation for the Machine Readable Version of the HISTORY AGK3 Star Catalogue of Positions and Proper Motions North of 2 5 HISTORY Degrees Declinat
203. the AGK3 position and the epoch of the AGK2 position in hundredths of years BD starts in column 52 and contains a seven character string giving the Bonner Durchmusterung number of the star BD COMP consists of a one digit integer in column 59 giving a numerical code identification of a component of a multiple star system The string O 1s the null value that would be in the field if the star is single As discussed in section 3 4 2 the value of the TNULL18 keyword is a character string and need not be readable in the integer format specified by the TFORM18 keyword DISC SUM is a two digit integer starting in column 60 containing a sum that expresses in one number which discrepancy codes are present A discrepancy code flags a value that is inconsistent with that in another catalog or is otherwise considered unreliable The sum is y 2 where V are the discrepancy codes for the particular position all values from 0 to 5 are possible The meaning is explained by the COMMENT key words immediately following the other column 19 keywords the DISC SUM following the COMMENT allows the text to be associated with the appropriate column even if the keywords are rearranged by the reader or a new table is created using some of the data in the current table and the column number changes You could also think of the DISC SUM as a hierarchy similar to those in the HIERARCH proposal discussed in section 5 7 NASA GSFC Astrophysics Data Facility 139
204. the data This choice has the advantage that the data format is the one most widely and easily read principal disadvantage is that the ancillary information for individual scans is separated from the results of the observations If there are not too many parameters and the individual spectrum vectors are not long ASCII tables may be a convenient format One row would correspond to an observation containing the ancillary information and the results Each wavelength would be a separate field of the table and the other fields would contain the ancillary parameters However as the spectra become longer and the number of points in a data set increases the inefficiencies in use of space by the ASCII table format become a serious problem Space can be reduced by using binary tables The binary form is more compact than the ASCII representation especially for exponential formats and numbers with many significant digits Also because many machines are now storing floating point numbers internally in IEEE format using binary tables eliminates time and cost associated with internal conversion in the machine Again one row corresponds to one observation but now the spectrum vector appears formally as a single field Parameters whose values are constant for the entire set of observations would remain in the header while those applying to a single observation matrix would appear in the same row of the table Example 4 in Appendix presents the heade
205. the first element then in order of the value of the second element and on in sequence Other columns may be used for sorting If the column ARRAY is being sorted first on element z then on element 7 and then on element k then TSORTKEY ARRAY 7 ARRAY 7 ARRAY Ek If the sorting is on consecutive columns m n then TSORTKEY ARRAY m n ARRAY k A string is treated as a vector of characters When sorting strings a blank element precedes any characters For an ascending order default sort shorter strings precede longer ones FORM precedes FORMAT This convention can be used only if the values of the TTYPEn keywords labelling the columns of the table obey the following restrictions e There must be a TTYPEn for every column and the name of every column value of TTYPEn must be unique e The first character of a column name must not be a minus sign e No column name may contain a comma hexadecimal 2C or an open or close parenthesis hexadecimal 28 and 29 e Embedded blank characters are discouraged with the underscore recommended to link separate words in a column name 5 6 1 4 Maximum and Mininum Values in Table Columns HEASARC uses the following keywords to specify the limits on data in a table column They are analogous to the DATAMAX and DATAMIN keywords used for arrays User s Guide Version 4 0 98 SECTION 5 ADVANCED FITS e TDMAXn is the maximum value in column n of a t
206. there are no units for the field To do so is not required but this choice provides a design with a consistent set of keywords for every field TFORMn keywords give the data type of each field The header keywords describe the following fields 1 Pixel no is a 32 bit integer giving the pixel number on the map 2 PSubPos is an 8 bit unsigned integer giving the pixel subposition as explained in the comments 3 Time is a double precision floating point number giving the average time for the observations of a pixel The comments note that the value is not physically meaningful for this data product Including this item allows the designers to produce a set of data products with a a common format simplifying the reading process 4 Photomet is short for Photometry and is a single precision floating point number giving a weighted average spectral intensity in MegaJanskys steradian The comments provide a precise definition and describe the weighting 5 StdDev is a single precision floating point number giving the standard deviation of the mean in the previous field in MegaJanskys steradian 6 WtNumObs is a 16 bit integer giving the sum of the weekly weighted number of observations used in deriving the annual averages 7 SumliRecs is a 32 bit integer giving the total number of observations Each row has one unsigned integer of one byte one two byte integer two four byte integers two single precision floating point numbers fou
207. through the Web from the Software item on the HEASARC menu bar or directly from User s Guide Version 4 0 116 SECTION 6 RESOURCES ftp legacy gsfc nasa gov software fitsio The other package FTOOLS is a collection of utility programs in ANSI Fortran or C that allows the user to interactively create examine or modify the contents of FITS files utilizing the FITSIO package Perl5 scripts are available for combining several FTOOLS to perform complex tasks FTOOLS supports all the standard FITS file formats discussed in Section 3 A general FITS file viewer and editor called fv is included as a standard part of the FTOOLS distribution and is available as a standalone package as well It can be used for viewing and plotting any FITS format data file It has a graphical user interface GUI written in Tcl Tk that provides spreadsheet like widgets to display and edit data in any FITS table or image a scrolling text window to display and edit FITS header keywords and an image display that uses either the Smithsonian Astrophysical Observatory The Next Generation SAOtng display tool or a custom designed Tk image widget Users can also produce line plots of the values in two or more columns of a FITS table and export the plots to a PostScript file As of this writing fv is supported on most Unix platforms support for IBM and Macintosh PCs is planned The FTOOLS package documentation and installation instructions are available from
208. ting clockwise This convention should be noted in the comments use of the opposite convention is not unknown 5 9 Spectra There is as yet no formal agreement or convention on encoding spectra from random positions on the sky in FITS format Conventions for describing the mapping between pixel number and frequency need to be developed In fact there has not even been agreement on whether frequency should be the only independent variable for spectroscopic data exchange or whether wavelength also should be used Section 4 2 1 discusses one proposal for attaching multiple labels to one axis While the resolution of these issues is outside the scope of this User s Guide it is important to recognize that they exist NASA GSFC Astrophysics Data Facility 5 10 HIGH ENERGY ASTROPHYSICS APPLICATIONS 105 Spectra can be transmitted as one dimensional arrays using the Basic FITS format with NAXIS 1 However such usage is inefficient Each spectrum would have its own header Spectroscopic observations generally need more ancillary parameters than do images The header may easily use more bytes than the data Approaches that would reduce header overhead are needed It may be possible to encode many spectra in a single array by adding a second dimension scan number Information about the entire set of observations would appear in the primary header information about the individual scans would appear in a table extension or extensions following
209. tion is being used Once the community has accepted a convention a single comment noting that the convention is being used will be sufficient The relation between array order and position in the displayed image for example whether the first pixel is at the top or bottom is also a matter of convention GC recommend that FITS writers order pixels starting in the lower left hand corner of the image with the first axis increasing to the right as in the rectangular coordinate z axis and the second increasing upward the y axis Readers may choose to use a different display as might be done when picturing how a field mapped visually would look through a telescope Use of this convention does not replace the description of the coordinate axes using CRVALn and the other keywords Although the original description of the CRPIXn CRVALn and CDELTn key words was in the context of linear transformations these keywords can be used to define non linear transformations The key point is that in such a case CDELTn must represent the rate of change in the physical coordinate per unit change in counting index a the reference point given by CRPIXn For a non linear scale the ratio between change in the physical coordinate and in the counting index could be different at other pixels Conventions for such transformations have not been established Development or use of any such convention including the definition of any new keywords should be in cooperation
210. ual to the number of 8 bit bytes in a table TOW 5 NAXIS2 integer has a value equal to the number of rows in the table Values of 0 no table and 1 one row are allowed as well as larger values 6 PCOUNT integer is equal to the number of bytes in the binary table extension data following the main table Note that this meaning is significantly different from that in the rules for random groups section 3 2 This usage was designed for the variable length convention discussed in section 5 2 1 While conflicting uses would not be against the formal FITS rules they would create confusion and should be avoided Non conflicting uses may be developed for other conventions 7 GCOUNT integer has the value of 1 for binary table extensions The total number of bytes is PCOUNT NAXIS1xNAXIS2 8 TFIELDS integer has a value equal to the number of entries fields in each row of the table Also required between the TFIELDS and END keywords are TFORMn key words for n 1 TFIELDS TFORMn character has a value specifying the width and data type of field n and is of the form rT where T is the field type and r is the repeat count that tells how many values of type T the field contains The value of r gives the number of members in the array that table item contains If the repeat count is absent it is assumed to be 1 A repeat count of zero is permitted Additional characters may follow the data type code While these characters are not
211. ution of data 0 0 offset to be applied to TIME column 93120513 beginning orbit number 93120603 ending orbit number 2 2 9 9 Position Related Keywords FK5 gt World Coordinate System 2000 000000 Equinox for coordinate system 182 74 Nominal RA 39 429 Nominal declination 182 760681 File average value of RA degrees 39 434547 File average value of DEC degrees 237 685150 File average value of ROLL degrees 0 000556 File standard deviation of RA degrees 0 000179 File standard deviation of DEC degrees 0 003630 File standard deviation of ROLL degrees 6 40500000E 02 Sky X axis reference pixel 6 40500000E 02 Sky Y axis reference pixel 1 82744003E 02 Sky X coordinate at reference pixel degrees 3 94291992E 01 Sky Y coordinate at reference pixel degrees 4 41999990E 04 Sky X pixel scale degrees pixel 4 41999990E 04 Sky Y pixel scale degrees pixel RA TAN Coordinate projection DEC TAN Coordinate projection 6 40500000E 02 Detector X ref pixel center of address space 6 40500000E 02 Detector Y ref pixel center of address space NASA GSFC Astrophysics Data Facility TCRVL8 TCRVL9 TCDLT8 TCDLT9 OPTIC3 OPTIC4 OPTIC8 OPTIC9 FOV_X_MM FOV_Y_MM END O OO On N N O O 149 00000000E 00 Detector X ref pixel value pixels 00000000E 00 Detector Y ref pixel value pixels 70000007E 02 Detector X pixel scale mm pixel 70000007E 02
212. variable length arrays except for using the value of PCOUNT to skip the heap In addition before generally distributing a file with variable length arrays be sure by means of practical tests that the file can be read on a machine other than the one used to write it 5 2 2 Arrays of Strings A user may wish to include a series of strings rather than one single string in a field of type A To distinguish the component strings from the complete string field they will be described as substrings in the remainder of this section The convention discussed in this section allows a reader to use the value of the TFORMn keyword to tell whether a character string field contains a single string or a series of substrings The convention provides for a simple fixed length case where all substrings are of the same length and a variable length option where the length of the substrings may vary The convention makes use of the fact that additional characters are permitted after the data type code in the value of TFORMn It is signaled by the presence of a string of the form rA SSTRw nnn in the value field of the TFORMn keyword with the nnn present only if the length of the substrings may vary The SSTR is the indicator that the substring array convention is in use FITS reader that is not able to process substrings under this convention can treat the entire contents of the field as a single string In a fixed length field w is the length of the indi
213. vidual substrings for example NASA GSFC Astrophysics Data Facility 5 2 CONVENTIONS FOR BINARY TABLES 81 TFORM5 40A SSTR8 Fixed length substrings tells the reader that field 5 is comprised of an array of five eight character substrings If a substring does not fill its specified subfield the remainder must be padded with ASCII blanks In the case above for example if the string in the first subfield were only six characters long then bytes 7 and 8 would be blanks If the total length of the field is not an integer multiple of the length of the substring the remainder of the field is undefined For TFORM5 14A SSTR3 Fixed length substrings field 5 contains four substrings of three bytes each followed by two undefined characters For a table field composed of substrings of variable length all substrings but the last are terminated by an ASCII text character deliminator whose decimal value which must be in the range 032 126 is provided by the nnn in the value of the TFORMn keyword Leading zeroes are included in the nnn The last substring is terminated with an ASCII NULL decimal 000 hexadecimal 00 regardless of the value of nnn The value of w is the maximum number of characters in any substring of the array not including the delimiter For example for TFORM6 100A SSTR8 032 Variable length strings field 6 is 100 characters wide and composed of substrings whose length may vary so long as no substrin
214. would contain data for one image One column would be a multidimensional array in floating point format containing the image and another would be a multidimensional array in integer format containing the flags 5 3 Hierarchical Grouping Proposal Jennings et al 1996 have proposed this convention which provides a mechanism for logically associating different HDUs that are physically separated into groups that may have a hierarchical structure It arose in part from efforts to convert between FITS and the Hierarchical Data Format HDF HDF is under continuous development at the National Center for Supercomputing Applications NCSA and current information is available from the NCSA World Wide Web site at http hdf ncsa uiuc edu The discussion in this Guide is taken from that paper Whether this convention needs to be submitted for IAUFWG endorsement or may be considered a recognized convention without being part of the formal FITS rules is still under discussion The grouping proposal provides several capabilities e It provides an alternative to EXTLEVEL for creating a hierarchical structure one that has an explicitly defined tree structure identifying the higher level groups to which each lower level group belongs e It creates a FITS structure analogous to the Vgroup structure of HDF User s Guide Version 4 0 86 SECTION 5 ADVANCED FITS e It provides a means for logically including a particular HDU in more than one grou
215. y to develop Developing a formal standard for FITS has clarified a number of points that had been unclear or ambiguous in the original FITS papers Some of the issues were regarded as not appropriate for a formal standard but deserving of further detailed discussion at the recommendation of the Technical Panel developing the NASA Science Office of Standards and Technology NOST standard they are included in this Guide Queries to the FITS Support Office and discussion on the FITS network newsgroup sci astro fits and the associated fitsbits electronic mail exploder have identified other points in need of explanation This Guide also describes a number of conventions that are widely used but have not been formally adopted by the FITS governing structure under the IAUFWG Description in this Guide of such conventions is intended neither as a NASA endorsement nor as a requirement for use of these conventions by NASA projects Where an issue is controversial this Guide attempts to provide the arguments on all sides FITS is continually expanding new conventions are proposed existing proposals are modified new issues are raised and the FITS committees act Some of this progress will occur during the period this Guide is being proofed and undergoing physical composition Thus some of these developments may unfortunately not make it into the current User s Guide To keep up with current events use the resources described in Section 6 Similarly W
216. ypertext material and to the material available at the ftp site nssdc gsfc nasa gov pub fits It also links to other FITS resources on the Web The ftp site has an aareadme doc file that can be accessed directly for those without Web connections The FITS Basics and Information page can be reached from the home page It contains the following material e An overview of FITS with a one paragraph description and a discussion of how FITS evolves e Discussion of FITS documents both those available from the FITS Support Office and those available elsewhere e Discussion of software packages including software for various platforms that can display FITS images e Discussion of other FITS resources available on line e Discussion of the FITS Support Office with contact information Where possible links are provided to the documents software and network locations described There is also a plain text version available at the ftp site It provides URLs or other access information for the material described NASA GSFC Astrophysics Data Facility 6 1 THE FITS SUPPORT OFFICE 109 The FITS Support Office maintains the official current IAUFWG list of registered extensions as its agent This list is available in both hypertext and plain text forms The FITS Support Office documentation discussed in section 6 1 2 and the software and test files described in section 6 1 3 are available from the Web page or at the ftp site 6 1 2 Document
217. yy 10 07 94 Date of original file creation dd mm yy CDAC Cosmology Data Analysis Center COBE COsmic Background Explorer satellite DIRBE COBE instrument DIRBE DMR FIRAS ALL SKY part of sky given ALL SKY WEEKLY SKY GAL SLICE 2000 0 equinox of coords in following tables DIRBE Explanatory Supplement COBE specific keywords 11 12 89 date of initial data represented dd mm yy 21 09 90 date of final data represented dd mm yy 9 Quad tree pixel resolution 6 9 DIRBE specific keywords BOO AAM Band 9 Annual Average Sky Map IPass 2B Version of Data Reduction Software 2140 microns nominal wavelength of Band 9 ALL all available solar elongations included COMBINED approach vectors combined NO signal from zodiacal dust remains in map 8 card images of ASCII blanks XTENSION BITPIX NAXIS NAXIS1 BINTABLE Extension type is Binary Table Binary data Data are in a table Number of 8 bit bytes in each row N NN NS NASA GSFC Astrophysics Data Facility NAXIS2 PCOUNT GCOUNT TFIELDS COMMENT TIMVERSN COMMENT COMMENT COMMENT COMMENT COMMENT COMMENT COMMENT TIMESYS MJDREFI COMMENT MJDREFF COMMENT TIMEUNIT TSTART TSTOP COMMENT COMMENT COMMENT COMMENT COMMENT COMMENT COMMENT COMMENT COMMENT COMMENT COMMENT COMMENT COMMENT COMMENT COMMENT COMMENT COMMENT TTYPE1 TUNITi TFORM1 COMMENT COM

A User's Guide for the Flexible Image Transport System FITS

Contents

Download Pdf Manuals

Related Search

Related Contents