[fitsbits] Questions about the 'REFERENC' keyword.

[Eric Greisen]

Joe Hourcle wrote:
> I had some questions about the REFERENC keyword:
> 
> 	http://archive.stsci.edu/fits/fits_standard/node40.html#SECTION00942320000000000000
> 
> 	REFERENC Keyword
> 
> 	The value field shall contain a character string citing a reference
> 	where the data associated with the header are published.
> 
> 
> I could see a few different interpretations of this:
> 
> 	1. It's similar to the 'FITS Serialization' in VOTable, where you
> 	   don't have the data attached, and can instead give a URL:
> 
> 	   http://www.ivoa.net/Documents/VOTable/20121205/votable.html#ToC36
> 
> 	   (although, in this case, I don't know if the URL would go to a
> 	   complete FITS file, or the data portion without the HDU)
> 
> 	2. A URL to the archive or repository are available to
> 	   download from
> 
> 	3. A reference (citation, URL, DOI or bibcode) to a published
> 	   research article that uses the data.
> 
> 	4. A URL to a website with documentation on using the
> 	   data
> 
> So, question 1 : Which one is it intended to be used for?
> 
> The only real-world examples that I've managed to find so far is
> WMAP LAMBDA, which seems to use it for a mix of 2, 3 & 4... but I don't
> know that it's valid to define it multiple times:
> 
> 	http://lambda.gsfc.nasa.gov/product/map/dr5/templates_fitshdr.cfm
> 
> And GOODS/FORS2, which gives a bibcode for the first results paper:
> 
> 	http://archive.eso.org/cms/eso-data/eso-data-products/data-submission/spectrum-header.html
> 
> 
> And question 2 is only partially related : 
> 
> As it doesn't seem to be used for use #1, is there some standard way of
> providing a complete HDU with some reference to data that's not attached? 
> 
> I have some scientists who would like to review if the data's what they
> want *before* they download really large files ... and I'd rather use
> something FITS HDU-like, so they hopefully don't have to modify their
> existing tools as much.

Since no one has responded to your question, I will give an answer of sorts.

When the keyword was invented, only one of the concepts listed above was 
even conceivable - a published article citation.  That was the authors' 
intent with the keyword and it would not rule out multiple REFERENC 
keywords with different values for multiple citations.

FITS files were and are expected to contain the data which they 
describe, so I am uncomfortable with the file containing solely some URL 
pointer.  Since URL's do not retain their value over time at all well 
the information may become obsolete anyway.   A URL should point to the 
complete FITS file that the user would want so that their reader can 
swallow it should they choose to download it.

I do understand the need for a modest sized data "catalog" to allow 
users to browse and then select the data files for downloading.  I 
suppose you could use dataless FITS files to describe each of the 
large-data FITS files.  But those dataless files would have to be 
legitimate FITS files (e.g. NAXIS=0 or NAXISj = 0) and so would not look 
precisely the same as the actual data.  However, I thought this was the 
role of the VO, or at NRAO, our own home-brew data catalog web browser.

The formal answer is that the use of this keyword is not really defined 
and you may use it in multiple instances in any way that suites your 
needs.  However, that also applies to all other FITS writers, so it may 
be dangerous the have whole applications dependent on specific meanings 
for the value of the REFERENC keyword.

Eric Greisen