[fitsbits] Start of the ''Hierarchical Grouping' Public Comment Period

[William Pence]

Mark,

I only played a minor role in the development of this Grouping 
convention, but here is my take on the issues you raised:

Mark Calabretta wrote:
> * Some comment needs to be made on fragility of references to external
>   FITS files, especially those using http:// or ftp:// URLs.  What is
>   supposed to happen if one of these references can't be satisfied?

This is mainly an implementation issue; it is up to the application 
program to decide whether to continue in this case, or possibly abort 
with an error message.  Note that one of the routines in the sample API, 
  called fits_verify_group, will test if all group members are 
accessible.  This is an issue regardless of whether the location of the 
group member is specified by a http or ftp URL, or as an absolute or 
relative directory path on the local file system.

> * There should be some mention of the need to avoid recursive grouping;
>   i.e. a group cannot be a member of itself either directly or
>   indirectly.

Yes.  This is mentioned in the discussion of the API, but this 
restriction should be stated up front in the document.

> * Can a HDU be added more than once to a grouping table?

I don't think this is strictly prohibited, although I can't think of a 
good reason to do it.

> * In Sect. 2.2 it should be noted that EXTVER does not have to be
>   sequential.  The caption for example 2 incorrectly concludes that
>   "it is the seventh group table" on the basis that EXTVER = 7.

Yes, this should be noted.  Example 2 probably really is the seventh 
grouping table in the FITS file, but as you note, this cannot be assumed 
simply by the value of EXTVER.

> * Sect. 3, there needs to be some discussion on the meaning and use of
>   the index "n" in GRPIDn and GRPLCn.

The definition of GRPIDn says it is the "nth group table that the HDU is 
a member of" but I agree this could be made clearer.

> * If grouping table A is a member of grouping table B, and grouping
>   table B is a member of grouping table C, then should there be a
>   GRPIDn/GRPLCn in grouping table A to say that (indirectly) it is also
>   a member of grouping table C?

I think the answer to this is "no".

> * I suggest extending example 2 by illustrating a small portion of the
>   grouping table itself, i.e. in rows and columns with column headers as
>   fv would.

This probably wasn't done simply because it is hard to display the wide 
table on a single page.  There are sample FITS files available for 
people that want to see the full implementation.

> * Appendix 1 seems to define keyword values with no associated
>   keyword(s).

This appendix was provided for informational purposes and is not 
directly necessary to the grouping convention itself.  It defines a 
syntax by which any keyword value or column entry could point to the 
location of another HDU.  In simple cases, it might be desirable for a 
keyword or column to point directly to an associated HDU, rather than 
using a grouping table to associate the 2 HDUs.

> * Sect 7 (third para) has "a given HDU may be referenced by up to 999
>   grouping tables simultaneously".  Where does this limit come from?

The indices on the GRPIDn/GRPLCn keywords are limited to 3 digits.  An 
HDU could actually belong to more than 999 groups, but that HDU could 
only point back to at most 999 grouping tables of which it is a member.


Bill
-- 
____________________________________________________________________
Dr. William Pence                       pence at milkyway.gsfc.nasa.gov
NASA/GSFC Code 662       HEASARC        +1-301-286-4599 (voice)
Greenbelt MD 20771                      +1-301-286-1684 (fax)