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 i Preface Since version 3.1 of A User’s Guide for the Flexible Image Transport System (FITS) was published, there have been several significant developments in the FITS community: • The International Astronomical Union FITS Working Group (IAUFWG) has endorsed the image (IMAGE) and binary table (BINTABLE) extensions and the agreement on physical blocking. • The proposal for treatment of world coordinate systems has been expanded and refined. • A number of conventions that are not part of the formal FITS rules have come into wide use. • A 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 greater 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 likely 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, Web 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 iii 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: fi[email protected] 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 1.1 The Need for FITS . 1 1.2 What FITS Is . 2 1.3 The Philosophy of FITS . 4 2 History 7 2.1 The First Agreement . 7 2.2 Random Groups . 8 2.3 Generalized Extensions . 9 2.4 ASCII Tables . 11 2.5 Floating Point . 12 2.6 Physical Blocking . 12 2.7 Image Extension . 13 2.8 Binary Tables . 13 2.9 How FITS Evolves . 15 3 FITS Fundamentals 17 3.1 Basic FITS . 17 3.1.1 Primary Header . 18 3.1.1.1 Required Keywords . 21 3.1.1.2 Reserved Keywords . 23 3.1.1.3 Some Hints on Keyword Usage . 28 3.1.1.4 Units . 29 3.1.2 Primary Data Array . 29 3.1.2.1 Scaled Integers . 30 3.1.2.2 Undefined Integers . 31 3.1.2.3 IEEE Floating Point Data . 31 3.2 Random Groups . 33 3.2.1 Header . 34 User’s Guide · Version 4.0 vi CONTENTS 3.2.1.1 Required Keywords . 34 3.2.1.2 Random Parameter Reserved Keywords . 36 3.2.2 Data Records . 37 3.3 Extensions . 37 3.3.1 Required Keywords for an Extension Header . 40 3.3.2 Reserved Keywords for Extension Headers . 41 3.3.3 Creating New Extensions . 42 3.4 ASCII Table Extension . 44 3.4.1 Required Keywords for ASCII Table Extension . 44 3.4.2 Reserved Keywords for ASCII Table Extension . 46 3.4.3 Data Records in an ASCII Table Extension . 47 3.5 The Image Extension . 47 3.5.1 Header . 48 3.5.2 Data Records . 49 3.6 Binary Tables . 49 3.6.1 Required Keywords for Binary Table Extension Headers . 50 3.6.2 Reserved Keywords for Binary Table Extension Header . 53 3.6.3 Binary Table Extension Data Records . 55 3.7 Reading FITS Format . 57 3.8 FITS Files and Physical Media . 58 4 World Coordinate Systems 61 4.1 Indexes and Physical Coordinates . 63 4.2 Proposed Conventions . 64 4.2.1 Improved Axis Descriptions . 64 4.2.2 Sky Images . 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 . 68 4.2.2.5 Conversion to Standard Celestial Coordinates . 70 4.3 Coordinate Keywords . 71 4.4 Current Status . 72 5 Advanced FITS 75 5.1 Registered Extension Type Names . 75 5.2 Conventions for Binary Tables . 77 5.2.1 Variable Length Arrays . 77 5.2.2 Arrays of Strings . 80 5.2.3 Multidimensional Arrays in Binary Tables . 82 5.2.3.1 TDIMn Keyword . 82 NASA/GSFC Astrophysics Data Facility CONTENTS vii 5.2.3.2 Green Bank Convention . 83 5.2.4 Some Applications of Binary Tables . 84 5.2.4.1 Replacing Random Groups . 84 5.2.4.2 Multiple Arrays in One HDU . 85 5.3 Hierarchical Grouping Proposal . 85 5.4 STScI Inheritance Convention . 90 5.5 Checksum Proposal . 90 5.6 Other Proposed Conventions . 94 5.6.1 HEASARC . 94 5.6.1.1 Keywords and column names . 95 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 98 5.6.2 World Coordinates in Tables . 99 5.6.3 Compression . 100 5.6.4 Other Reserved Type Names . 101 5.6.5 Developing New Conventions . 101 5.7 Keyword Domains . 102 5.8 Polarization . 104 5.9 Spectra . 105 5.10 High Energy Astrophysics Applications . 106 6 Resources 107 6.1 The FITS Support Office . 107 6.1.1 On-line Information . 108 6.1.2 Documents . 109 6.1.3 Software and Test Files . 111 6.1.4 Contact Information . 112 6.2 NRAO FITS Resources . 113 6.3 HEASARC . 115 6.4 Some Additional Software Resources . 117 6.5 Other Network Resources . 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 Common Projections . 69 4.2 Identification of Sky Coordinate Systems . 70 4.3 Reference Frames for Equatorial Coordinate Systems . 71 5.1 Reserved Extension Type Names . 76 5.2 Possible Status Levels for FITS Extensions . 77 5.3 NRAO Stokes Parameters Convention . 104 B.1 IEEE Floating Point Formats . 156 NASA/GSFC Astrophysics Data Facility 1 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.