A FITS header is a sequence of 80-character strings, formatted according to particular rules defined by the Flexible Image Transport System (FITS). FITS27 is a widely-used standard for data interchange in astronomy and has also been adopted as a data processing format in some astronomical data reduction systems. The individual 80-character strings in a FITS header are usually called cards or header cards (for entirely anachronistic reasons).
A sequence of FITS cards appears as a header at the start of every FITS data file, and sometimes also at other points within it, and is used to provide ancillary information which qualifies or describes the main array of data stored in the file. As such, FITS headers are prime territory for storing information about the coordinate systems associated with data held in FITS files.
In this section, we will examine how to store information in FITS headers directly in the form of AST Objects—a process which is supported by a specialised class of Channel called a FitsChan. Our discussion here will turn out to be a transitional step that emphasises the similarities between a FitsChan and a Channel (§15). At the same time, it will prepare us for the next section (§17), where we will examine how to use a FitsChan to tackle some of the more difficult problems that FITS headers can present.
As it turns out, we are not the first to have thought of storing WCS information in FITS headers. In fact, the original FITS standard (1981 vintage) defined a set of header keywords for this purpose which have been widely used, although they have proved too limited for many practical purposes.
At the time of writing, a number of different ways of using FITS headers for storing WCS information are in use, most (although not all) based on the original standard. We will refer to these alternative ways of storing the information as FITS encodings but will defer a discussion of their advantages and limitations until the next section (§17).
Here, we will examine how to store AST Objects directly in FITS headers. In effect, this defines a new encoding, which we will term the native encoding. This is a special kind of encoding, because not only does it allow us to associate conventional WCS calibration information with FITS data, but it also allows any other information that can be expressed in terms of AST Objects to be stored as well. In fact, the native encoding provides us with facilities roughly analogous to those of the Channel (§15)—i.e. a lossless way of transferring AST Objects from program to program—but based on FITS headers instead of free-format text.
I/O between AST Objects and FITS headers is supported by a specialised form of Channel called a FitsChan. A FitsChan contains a buffer which may hold any number, including zero, of FITS header cards. This buffer forms a workspace in which you can assemble FITS cards and manipulate them before writing them out to a file.
By default, when a FitsChan is first created, it contains no cards and there are five ways of inserting cards into it:
There are also four ways of removing cards from a FitsChan:
Note, in particular, that reading an AST Object from a FitsChan is destructive. That is, it deletes the FITS cards that describe the Object. The reason for this is explained in §17.5.
In addition to the above, you may also read individual cards from a FitsChan using the function AST_FINDFITS (which is not destructive). This is the main means of writing out FITS cards if you have not supplied a sink routine. AST_FINDFITS also provides a means of searching for particular FITS cards (by keyword, for example) and there are other facilities for overwriting cards when required (§16.13).
The FitsChan constructor function, AST_FITSCHAN, is straightforward to use:
Here, we have omitted any source or sink functions by supplying the AST_NULL routine for the first two arguments (remember to include the AST_PAR include file which contains the required EXTERNAL statement for this routine). We have also initialised the FitsChan’s Encoding attribute to NATIVE. This indicates that we will be using the native encoding (§16.1) to store and retrieve Objects. If this was left unspecified, the default would depend on the FitsChan’s contents. An attempt is made to use whatever encoding appears to have been used previously. For an empty FitsChan, the default is NATIVE, but it does no harm to be sure.
Because a FitsChan contains an ordered sequence of header cards, a mechanism is needed for addressing them. This allows you to specify where new cards are to be added, for example, or which card is to be deleted.
This role is filled by the FitsChan’s integer Card attribute, which gives the index of the current card in the FitsChan. You can nominate any card you like to be current, simply by setting a new value for the Card attribute, for example:
where ICARD contains the index of the card on which you wish to operate next. Some functions will update the Card attribute as a means of advancing through the sequence of cards, when reading them for example, or to indicate which card matches a search criterion.
The default value for Card is one, which is the index of the first card. This means that you can “rewind” a FitsChan to access its first card by clearing the Card attribute:
The total number of cards in a FitsChan is given by the integer Ncard attribute. This is a read-only attribute whose value is automatically updated as you add or remove cards. It means you can address all the cards in sequence using a loop such as the following:
However, it is usually possible to write slightly tidier loops based on the AST_FINDFITS function described later (§16.6 and §16.13).
If you set the Card attribute to a value larger than Ncard, the FitsChan is regarded as being positioned at its end-of-file. In this case there is no current card and an attempt to obtain a value for the Card attribute will always return the value Ncard 1. When a FitsChan is empty, it is always at the end-of-file.
Having created an empty FitsChan (§16.3), you can write any AST Object to it in the native encoding using the AST_WRITE function. Let us assume we are writing a SkyFrame,28 as follows:
Since we have selected the native encoding (§16.1), there are no restrictions on the class of Object we may write, so AST_WRITE should always return a value of one, unless an error occurs. Unlike a basic Channel (§15.3), this write operation will not produce any output from our program. The FITS headers produced are simply stored inside the FitsChan.
After this write operation, the Ncard attribute will be updated to reflect the number of new cards added to the FitsChan and the Card attribute will point at the card immediately after the last one written. Since our FitsChan was initially empty, the Card attribute will, in this example, point at the end-of-file (§16.4).
The FITS standard imposes a limit of 68 characters on the length of strings which may be stored in a
single header card. Sometimes, a description of an AST Object involves the use of strings which
exceed this limit (e.g. a Frame title can be of arbitrary length). If this occurs, the long string will be
split over two or more header cards. Each “continuation” card will have the keyword CONTINUE in
columns 1 to 8, and will contain a space in column 9 (instead of the usual equals sign). An ampersand
(“&”) is appended to the end of each of the strings (except the last one) to indicate that the string is
continued on the next card.
Note, this splitting of long strings over several cards only occurs when writing AST Objects to a FitsChan using the AST_WRITE routine and the native encoding. If a long string is stored in a FitsChan using (for instance) the AST_PUTFITS or AST_PUTCARDS routine, it will simply be truncated.
To examine the contents of the FitsChan after writing the SkyFrame above (§16.5), we must write a simple loop to extract each card in turn and print it out. We must also remember to rewind the FitsChan first, e.g. using AST_CLEAR. The following loop would do:
Here, we have used the AST_FINDFITS function to find a FITS card by keyword. It is given a keyword template of “%f”, which matches any FITS keyword, so it always finds the current card, which it returns. Its fourth argument is set to .TRUE., to indicate that the Card attribute should be incremented afterwards so that the following card will be found the next time around the loop. AST_FINDFITS returns .FALSE. when it reaches the end-of-file and this terminates the loop.
If we were storing the FITS headers in an output FITS file instead of printing them out, we might use a loop like this but replace the WRITE statement with a call to a suitable data access routine to store the header card. This would only be necessary if we had not provided a sink routine for the FitsChan (§16.14).
If we print out the FITS header cards describing the SkyFrame we wrote earlier (§16.5), we should obtain something like the following:
As you can see, this resembles the information that would be written to a basic Channel to describe the same SkyFrame (§15.8), except that it has been formatted into 80-character header cards according to FITS conventions.
There are also a number of other differences worth noting:
This last point is worth further comment and is necessary because the FITS standard only allows for certain keywords (such as COMMENT and HISTORY) to appear more than once. AST_WRITE therefore appends an arbitrary sequence of two characters to each new keyword it generates in order to ensure that it does not duplicate any already present in the FitsChan.
The main risk from not following this convention is that some software might ignore (say) all but the last occurrence of a keyword before passing the FITS headers on. Such an event is unlikely, but would obviously destroy the information present, so AST_WRITE enforces the uniqueness of the keywords it uses. The extra characters added are ignored when the information is read back.
As with a basic Channel, you can also suppress the comments produced in a FitsChan by setting the boolean (integer) Comment attribute to zero (§15.10). However, FITS headers are traditionally generously commented, so this is not recommended.
To insert individual cards into a FitsChan, prior to reading them back as Objects for example, you should use the AST_PUTFITS routine. You can insert a card in front of the current one as follows:
where the third argument of .FALSE. indicates that the current card should not be overwritten. Note that facilities are not provided by AST for formatting the card contents.
After inserting a card, the FitsChan’s Card attribute points at the original Card, or at the end-of-file if the FitsChan was originally empty. Entering a sequence of cards is therefore straightforward. If CARDS is an array of character strings containing FITS header cards and NCARDS is the number of cards, then a loop such as the following will insert the cards in sequence into a FitsChan:
Note that AST_PUTFITS enforces the validity of a FitsChan by rejecting any cards which do not adhere to the FITS standard. If any such cards are detected, an error will result.
If you have all your cards concatenated together into a single long string, each occupying 80 characters (with no delimiters), you can insert them into a FitsChan in a single call using AST_PUTCARDS. This call first empties the supplied FitsChan of any existing cards, then inserts the new cards, and finally rewinds the FitsChan so that a subsequent call to AST_READ will start reading from the first supplied card. The AST_PUTCARDS routine uses AST_PUTFITS internally to interpret and store each individual card, and so the caveats in §16.8 should be read.
Once you have stored a FITS header description of an Object in a FitsChan using the native encoding (§16.5), you can read it back using AST_READ in much the same way as with a basic Channel (§15.4). Similar comments about validating the Object you read also apply (§15.6). If you have just written to the FitsChan, you must remember to rewind it first:
An important feature of a FitsChan is that read operations are destructive. This means that if an Object description is found, it will be consumed by AST_READ which will remove all the cards involved, including associated COMMENT cards, from the FitsChan. Thus, if you write an Object to a FitsChan, rewind, and read the same Object back, you should end up with the original FitsChan contents. If you need to circumvent this behaviour for any reason, it is a simple matter to make a copy of a FitsChan using AST_COPY (§4.12). If you then read from the copy, the original FitsChan will remain untouched.
After a read completes, the FitsChan’s Card attribute identifies the card immediately following the last card read, or the end-of-file of there are no more cards.
Since the native encoding is being used, any long strings involved in the object description will have been split into two or more adjacent contuation cards when the Object was stored in the header using routine AST_WRITE. The AST_READ routine reverses this process by concatenating any such adjacent continuation cards to re-create the original long string.
When using the native FITS encoding, multiple Objects may be stored and all I/O operations are sequential. This means that you can simply write a sequence of Objects to a FitsChan. After each write operation, the Card attribute will be updated so that the next write appends the next Object description to the previous one.
If you then rewind the FitsChan, you can read the Objects back in the original order. Reading them back will, of course, remove their descriptions from the FitsChan (§16.10) but the behaviour of the Card attribute is such that successive reads will simply return each Object in sequence.
The only thing that may require care, given that a FitsChan can always be addressed randomly by setting its Card attribute, is to avoid writing one Object on top of another. For obvious reasons, the Object descriptions in a FitsChan must remain separate if they are to make sense when read back.
Of course, any real FITS header will contain other information besides AST Objects, if only the mandatory FITS cards that must accompany all FITS data. When FITS headers are read in from a real dataset, therefore, any native AST Object descriptions will be inter-mixed with many other cards.
Because this is the normal state of affairs, the boolean (integer) Skip attribute for a FitsChan defaults to one. This means that when you read an Object From a FitsChan, any irrelevant cards will simply be skipped over until the start of the next Object description, if any, is found. If you start reading part way through an Object description, no error will result. The remainder of the description will simply be skipped.
Setting Skip to zero will change this behaviour to resemble that of a basic Channel (§15.12), where extraneous data are not permitted by default, but this will probably rarely be useful.
You can search for, and retrieve, particular cards in a FitsChan by keyword, using the function AST_FINDFITS. This performs a search, starting at the current card, until it finds a card whose keyword matches the template you supply, or the end-of-file is reached.
If a suitable card is found, AST_FINDFITS returns the card’s contents and then sets the FitsChan’s Card attribute either to identify the card found, or the one following it. The way you want the Card attribute to be set is indicated by the fourth (logical) argument to AST_FINDFITS. A value of .TRUE. is returned to indicate success. If a suitable card cannot be found, AST_FINDFITS returns a value of .FALSE. to indicate failure and sets the FitsChan’s Card attribute to the end-of-file.
Requesting that the Card attribute be set to indicate the card that AST_FINDFITS finds is useful if you want to replace that card with a new one, as in this example:
Here, AST_FINDFITS is used to search for a card with the keyword AIRMASS. If the card is found, AST_PUTFITS then overwrites it with a new card. Otherwise, the Card attribute ends up pointing at the end-of-file and the new card is simply appended to the end of the FitsChan.
A similar approach can be used to delete selected cards from a FitsChan using AST_DELFITS, which deletes the current card:
This deletes the first card, if any, with the BSCALE keyword.
Requesting that AST_FINDFITS increments the Card attribute to identify the card following the one found is more useful when writing loops. For example, the following loop extracts each card whose keyword matches the template “CD%6d” (that is, “CD” followed by six decimal digits):
For further details of keyword templates, see the description of AST_FINDFITS in Appendix B.
The use of source and sink routines with a FitsChan is optional. This is because you can always arrange to explicitly fill a FitsChan with FITS cards (§16.8 and §16.9) and you can also extract any cards that remain and write them out yourself (§16.6) before you delete the FitsChan.
If you choose to use these routines, however, they behave in a very similar manner to those used by a Channel (§15.13 and §15.14). You supply these routines, as arguments to the constructor function AST_FITSCHAN when you create the FitsChan (§16.3). The source routine is invoked implicitly at this point to fill the FitsChan with FITS cards and the FitsChan is then rewound, so that the first card becomes current. The sink routine is automatically invoked later, when the FitsChan is deleted, in order to write out any cards that remain in it.
The only real difference between the source and sink routines for a FitsChan and a basic Channel is that FITS cards are limited in length to 80 characters, so the choice of buffer size is simplified. This affects the way the card contents are passed, so the routines themselves are slightly different. The following is therefore the FitsChan equivalent of the Channel SOURCE routine given in §15.13:
Here, the FITS card contents are returned via the CARD argument (the AST_PUTLINE routine should not be used) and the function returns 1 to indicate that a card has been read. A value of zero is returned if there are no more cards to read.
The sink routine for a FitsChan is also a little different (c.f. the SINK routine in §15.14), as follows:
The contents of the FITS card being written are passed via the CARD argument (the AST_GETLINE routine should not be used).
Of course, both of these examples assume that you are accessing text files. If this is not the case, then appropriate changes to the I/O statements would be needed. The details obviously depend on the format of the file you are handling, which need not necessarily be a true FITS file.
27http://fits.gsfc.nasa.gov/
28More probably, you would want to write a FrameSet, but for purposes of illustration a SkyFrame contains a more manageable amount of data.