[bug #58363] Cite exact parts of FITS standard or CFITSIO about primary HDU

[Mohammad Akhlaghi]

URL:
  <https://savannah.gnu.org/bugs/?58363>

                 Summary: Cite exact parts of FITS standard or CFITSIO about
primary HDU
                 Project: GNU Astronomy Utilities
            Submitted by: makhlaghi
            Submitted on: Wed 13 May 2020 01:55:25 AM BST
                Category: Libraries
                Severity: 3 - Normal
              Item Group: Addition(s)
                  Status: None
                 Privacy: Public
             Assigned to: None
             Open/Closed: Open
         Discussion Lock: Any

    _______________________________________________________

Details:

It was recently mentioned in address@hidden
<https://lists.gnu.org/archive/html/bug-gnuastro/2020-05/msg00000.html> that
the statement "Gnuastro leaves the first HDU blank (with no data) and writes
the outputs in the second HDU. " is not actually recommended in the FITS
standard (as suggested when the error message).

This is the full printed message when the input only has one extension, but
the program expects data in the second extension. (of course, as mentioned in
the error message, this "expectation" can easily be changed with a '-h0'
option):

"FOOTNOTE -- When writing a new FITS file, Gnuastro leaves the first HDU blank
(with no data) and writes the outputs in the second HDU. In this way the
keywords of the the first HDU can be used as meta data of the whole file
(which may contain many extensions). This is the recommended way in the FITS
standard. As a result, Gnuastro's default HDU to read an extension in a FITS
file is the second."

I don't have too much time right now of precisely find the exact place I got
this recommendation from (I should have mentioned it when I made the
statement, but a fast look points me to these places below (from the FITS 4.0
standard <https://fits.gsfc.nasa.gov/standard40/fits_standard40aa-le.pdf>,
Language-edited document publication date: 2018 August 13):

* In Section 2 (Definitions, acronyms and symbols), for "primary header" it is
stated that: "The first header in a FITS file, containing information on *the
overall contents of the file* (as well as on the primary data array, if
present)."

* In Section G.1.1 (Recommendations for application writers), of the five
scenarios mentioned, 4 of them have an empty primary HDU. 

* In Appendix K (Header inheritance convention), where they say that if an
'INHERIT' keyword is present in a header, the application should go looking in
the primary HDU. Although its not officially in the standard, it is mentioned
here as a "convention". This again implies that the primary HDU is mainly
allocated for *all* the extensions.

I'll have to find the reference for this later, but I remember reading
somewhere that the fact that images are allowed in the primary HDU is only for
historical reasons. Later, when they added Tables to FITS, to avoid the same
mistake, they didn't allow tables in the primary HDU.

It also makes very nice sense: the primary HDU is for the meta data in all the
extensions of the file, each extension then has its own unique metadata.
Having images in the second extension, also allows a unified interface for
programs that accept tables or images (for example Gnuastro's Statistics
program
<https://www.gnu.org/software/gnuastro/manual/html_node/Invoking-aststatistics.html>.

This is filed as a bug because any user who confronts this message expects
proper citation of the standard and we should find a way to cite it clearly.




    _______________________________________________________

Reply to this item at:

  <https://savannah.gnu.org/bugs/?58363>

_______________________________________________
  Message sent via Savannah
  https://savannah.gnu.org/