DPUSER - The Next Generation: Handling of FITS files
Author: Thomas Ott

# Handling of FITS files

FITS (Flexible Image Transport System) is commonly used in astronomy to store images. A very simple way to describe the format is that they contain an ASCII header describing the content of the file and the image itself in binary format. DPUSER is designed to efficiently handle this kind of files. The most common things you might want to do is reading images, writing images and editing the information in the header.
A set of functions has been optimised to deal with large files, which probably do not fit in the main memory of your computer.

## Reading FITS files

DPUSER is able to read in FITS files, including FITS binary tables. The files may be compressed with gzip, uncompressing is done on the fly. The task of reading in a FITS file can be done in two ways:

1. Use the function readfits
2. Supply the filename in single quotes
3. Use the function readfitsextension
4. Use the function readfitsall
5. Use the function readfitsbintable

### Examples

Read in a complete FITS file into a variable named `image`:
`image = readfits("filename")` or `image = 'filename'`
Read in the first image of a FITS cube:
`image = 'filename'[*,*,1]`
Read in columns 100 to 200 and rows 50 to 150 of a FITS file:
`image = 'filename'[100:200, 50:150]`

## Writing FITS files

DPUSER is able to write simple FITS files, including FITS extensions, but it cannot (yet) write FITS tables. Writing, as reading FITS files can be accomplished using two methods:

1. Use the procedure writefits
2. Assign a matrix to a filename in single quotes

DPUSER creates a new file in either way. You cannot overwrite part of an existing file.

### Examples

Write a 2-dimensional gaussian to a file named `gauss.fits`:
`writefits "gauss.fits", gauss(129,129,10)`
which is equivalent to:
`'gauss.fits' = gauss(129,129,10)`

## Editing the FITS header

Once a FITS file is read into memory, where it is represented by a matrix, it is possible to edit and display the FITS header information with a set of FITS header editing functions. These are:

header | Returns the FITS header as a string
getfitskey | Returns the value of a FITS key
setfitskey | Sets the value of a FITS key
setwcs | Sets the world coordinate system in the FITS header
copyheader | Copy a FITS header to a variable

## Optimised routines

Some data analysis tasks require the handling of huge files. The following functions have been optimised to deal with large files. To take advantage of these capabilities, use filenames in single quotes and not the function readfits.

header | Returns the FITS header as a string
cubeavg | Does an average in the 3rd dimension
cubemedian | Does a median in the 3rd dimension
ssa | Simple Shift-and-Add
ssastat | Simple Shift-and-Add statistics
sssa | Simple Shift-and-Add using statistics
wsa | Weighted Shift-and-Add
swsa | Weighted Shift-and-Add using statistics