Introduction

Single FITS files

• FITS Scaling and Datatype
• Examples for single FITS files
• Multiple Extensions FITS files (MEF)
• IRAF filename specification
• Kernel Section parameters
• Default values for KS
• fkinit
• FITS Header blank lines
• INHERIT on the Fits Kernel
• FITS Scaling and Datatype
• IRAF tasks and MEF
• Examples for FITS extensions handling
• Non IMAGE Extension
• Shortcomings between IRAF and MEF
• FITS Standard

The IRAF FITS Kernel available within IRAF v2.11 allows applications that handle images to access directly FITS format files. IRAF will read, modify or create images in standard FITS format as either a single FITS file or as an IMAGE extension within a file.

This user guide is divided into 2 parts: Single FITS files; i.e. one image per file and Multiple Extensions FITS file (MEF) or many FITS Units per file. For single FITS files there is no need to learn all the complexities associated with having more than one unit per file. On the other hand, MEF files provide an easy way to organize associated data files.
 

Single FITS files

For IRAF a FITS file has a default file extension 'fits' which you can omit by setting the cl variable 'imtype' to the value 'fits', like:

cl> set imtype=fits

You can choose any other arbitrary alphanumeric extension of 2 to 4 characters in length but you will need to let IRAF know that it is a FITS extension by setting the cl variable 'imextn' as:

cl> reset imextn = fxf:abf,fits
cl> reset imtype = abf

FITS Scaling and Datatype

For unsigned 16 bits, the IRAF datatype is ushort and the FITS image datatype will be BITPIX 16 and BSCALE of one and BZERO of 32768.

If you are handling FITS files with BITPIX 16 or 8 and BSCALE and BZERO not the default values, the FK will create a temporary file to convert this image into floating point image. This temporary file is created in the iraf 'tmp' directory.

WARNING

If you are handling FITS files with BITPIX 16 or 8 and BSCALE and BZERO not the default values, the FK will create a temporary file to convert this image into floating point image. This temporary file is created in the working directory. If you do not have write access to the directory, an error will occur. To solve this problem in the meantime you will need to be in a writeable directory before any operation on those files is attempted.

Examples for single FITS files

1. Create a fits file from an image section of an 'imh' file.

2. List the header, 'long+' indicates long header listing

3. Using imcombine.

4.  Delete the images.

5. Read a FITS image from another machine on the IRAF network.

6. Create FITS file from other image type. The 'filef' will have the default extension 'fits' since we have set the 'imtype'to the FITS kernel (fxf) default extension (fits). The 'reset imtype' line needs to be done only once in your cl session or set it in your login.cl. If you reset it to handle another  format a 'flprc' command is required.

7. A Caveat to this example is that you cannot convert multiple files to fits files, i.e. will NOT convert the current imh files to 'fits'. This is a shortcoming of the 'imcopy' command.

8. To achieve the  above you need to use list files.

Multiple Extensions FITS files (MEF)

IRAF filename specification

root.extn[extension_number][kernel_section][im_section]
 

• root:    All but the 'root' name is required to access an image within a single FITS file. The filename must have an extension that is supported via the cl variable imextn

• extn:; 'extn' is the extension name that can be omitted only if it 'fits' or 'fit'. Other extensions are supported providing they have from 2 to 4 alphanumeric characters in length and are listed in the 'imextn' CL variable as follows:

imextn="oif:imh fxf:fits,fit plf:pl qpf:qp stf:hhh,??h"

oif, fxf, plf, qpf and stf are the names of the different image kernels supported by IRAF and their default extensions. To add new file extensions to the FITS kernel (fxf) just append them to the above. For example:

cl> reset imextn="fxf:fits,fit,z0f,caf,hwf,ag,bx"

All the rest of the kernels will have the default values.
 

• extension_number: The 'extension_number' part of the filename is a decimal specifying which FITS units you are referring to. The numbering of FITS units is zero index. Zero for the Primary unit, 1 for the second unit or first extension, 2 for third unit and so on.

• kernel_section: The 'kernel_section' part of the filename consists of a set of comma separated parameter with or without values. The general syntax is:

[no]parameter[+/-][=value]

The values in bracket are optional. Parameter name is minimum match and case insensitive. For example:

nic[3,noinherit]

refers to extension number 3 and any operation with the extension will not include the Global header (PHU). Notice that a decimal extension number can be set in the kernel_section only if it is the first item in the list.
 

• image_section: Is the general image section part; e.g. [100:230,10:20].

Kernel Section parameters

EXTNAME

[extname=]'string'. If the parameter name is not given, the string needs to start with an alphabetic character. The 'extname' parameter matches the EXTNAME FITS extension keyword. 'extname' and 'extver' are very useful to access an IMAGE extension by these values rather than the absolute extension number.

EXTVER

[extver=]integer_value. If the parameter name is not given, the integer value needs to be at the second parameter position. The 'extver' parameter matches the EXTVER FITS keyword . In general extname,extver are not duplicated among the units in a given FITS file.

APPEND

[no]append[+,-,=yes,=no]. This parameter is required to append a FITS IMAGE extension to a FITS file. If the parameter is omitted or has the 'no' value and the 'imclobber' cl variable is set to yes, the existent file will be deleted before creating the PHU.

OVERWRITE

[no]overwrite[+,-,=yes,=no]. Overwrite a FITS IMAGE unit. A temporary file is created in the working directory, copied all data before the unit, the new data then the data after the unit to be overwritten. Rename. No protection for clobbering.

INHERIT

[no]inheritance[+,-,=yes,=no]. Adds the Primary header (providing it has NAXIS=0) to any extension header that has the INHERIT keyword with value T. The merging is done by excluding the FITS require keywords, HISTORY and COMMENT plus any keywords that is duplicated in the extension. If an extension has INHERITANCE = T, and a new copy of this extension is created, the output inheritance value will be F. If you want inheritance on the output extension, the kernel parameter 'inherit' should be used.

DUPNAME

[no]dupname[+,-,=yes,=no]. Allows extname, extver to have either values duplicated in other headers on the MEF file.

EXPAND

[no]expand[+,-,=yes,=no]. Allows the automatic expansion of headers when they run out of space by creating a temporary file in the working directory, adjusting the size and rewriting. If expand is disabled and the user area is larger than the header in disk, truncation will result and a warning message is issued. To avoid this problem of running out of space use 'ehulines' or 'padlines'.

EHULINES

ehulines=integer. Preallocate a minimum number of header lines when creating a new image or making a new copy of one. If more lines are allocated than actual header lines, trailing space is added to the header in disk; if less, it has no effect.

PADLINES

padlines=integer. Add a number of header lines to a new copy image header. When making a new copy of an image, the application can add more header lines to the in-memory header and there is a possibility that the output header size is larger than the old one. To avoid rewriting the file to make the header larger a padlines value to cover this problem can be given.

When a FITS image specification is given to an IRAF task, the following are the default values of the kernel section:
        extname   = EOS
        extver    = INDEFI
        append    = NO
        overwrite = NO
        inherit   = YES
        dupname   = NO
        expand    = YES
        ehulines  = 0
        padlines  = 0
 

fkinit

cl> set fkinit='append,inherit'

Will make an application 'append' a FITS IMAGE extension into an existing file when new or new copy image is wanted. If reading an IMAGE extension, the application will merge the global (PHU) with the extension header (inherit). This 'inherit' value applies only to input filenames. To request 'inherit' on output you'll have to put the parameter in the output filename. See examples below.
 

FITS Header blank lines

INHERIT in the Fits KerneL

The agreement so far has been that inherit should be relevant only in the context of the local file and should not be carry to other files when copying individuals extension. Is up to the application or the user to be responsible in carrying the global header when making a copy of an extension.

There are a number of keywords that will not be copied from the global header to the combine global+extension header. These are the FITS required keywords plus the HISTORY and COMMENT keywords. A combined header will then have the required keywords and HISTORY and COMMENT from the extension header only.

As an usage note, the way to add a keyword to an extension that already exists in the global header but with a different value is to edit the extension header with the kernel section parameter 'noinherit'. This way the value of the INHERIT keyword in the extension header is preserve.
 

FITS Scaling and Datatype

For unsigned 16 bits, the IRAF datatype is ushort and the FITS image datatype will be BITPIX 16 and BSCALE of one and BZERO of 32768.
 

IRAF tasks and MEF

        imheader spec*.fits

but with a MEF file is necessary to list each extension:

        imheader spec[1],spec[2],spec[3],spec[4]

or create a list file: 'spec.lis'

        spec.fits[1]
        spec.fits[2]
        spec.fits[3]
        spec.fits[4]

and 

        imheader @spec.lis

Examples for FITS extensions handling

1. Make a copy of a subsection of dev$pix in FITS format.

2. List the header.

3. Append an image to the above file. The image extension will have the EXTNAME keyword value 'sci' and EXTVER value 1. Notice that 'append' is necesary.

we can also type

im> imcopy nicm.fits pixf[sci,1,append]

This will overwrite the input EXTNAME and EXTVER values for 'sci' and 1 respectively.
 

4. If we have a FITS file with more than one extension, is it necessary to specify which one.

or if we know that this is extension 4 we can type

im> splot spf[4]
 

5. Make a difference of 2 images and put the result in diff.fits.

Notice that the reference to the images is done by using the values of EXTNAME and EXTVER keywords.
 
6. Run imstatistics on all extension in a MEF file. Since the task can handle only one input image at a time, a small script is necessary:

cl> for (i=1;i<4;i=i+1)
    imstat ("calf.fits["//i//"]")

Or we can create a list file: "calf.lis"

    calf.fits[1]
    calf.fits[2]
    calf.fits[3]

cl> imstat @calf.lis

We can use the new task 'imextension' in the proto package to create the list file:

cl> proto
pr> imexten calf output=file > calf.list
pr> imstat @calf.lis

7. There is an external package 'fitsutil' (see below for retrieval information) that allows us to see all the extension in a file.

ta> fitsutil
fi> fxheader pixf.fits

Will list one line description per extension.

Non IMAGE Extension

Shortcomings between IRAF and MEF

• It is important to use 'imdelete' and NOT 'delete' when deleting a MEF file, since the FK has a cache of the last 10 most recently files accessed by any IRAF task. To keep the cache in sync with the files on disk, imdelete will clear the cache entry indicating that the file is no longer on disk.
• Cannot delete an IMAGE extension.

• Imdelete will delete the entire MEF file. With the present IRAF version:

• Cannot insert an image in the middle of a MEF file. The fitsutil task 'fxfinsert' will do this.
• To get a listing of all the extensions in a MEF file use 'fxfheader'.
• To copy more than one IMAGE extension from a MEF file use 'fxcopy'.

FITS Standard