writeFITSim {FITSio}

Write a FITS image (multi-dimensional numeric array) to disk

Description

Write a FITS image (multi-dimensional numeric array) to disk.

Usage

writeFITSim(X, file = "R.fits", type = "double",
bscale = 1, bzero = 0, c1 = NA, c2 = NA,
crpixn = NA, crvaln = NA, cdeltn = NA, ctypen = NA, cunitn = NA,
axDat = NA, header = '')

writeFITSim16i(X, file = "R.fits", ...)

Arguments

X

Multi-dimensional numeric data array; see Details.

file

Output filename.

type

Type to write: single or double precision.

bscale

Global scaling factor, FITS standard meaning.

bzero

Global shift, FITS standard meaning.

c1

Character string comment line for header.

c2

Character string comment line for header.

crpixn

Vector of reference pixel numbers for axes, FITS standard meaning.

crvaln

Vector of values at reference pixels, FITS standard meaning.

cdeltn

Vector of axis increments per pixel, FITS standard meaning.

ctypen

String vector of descriptive labels for axis, FITS standard meaning.

cunitn

String vector of physical units for axis, FITS standard meaning.

axDat

Data frame with axis data (optional), see details.

header

Header (optional) as 80-character card images.

...

Arguments as defined above, as needed, for writeFITSim16i.

Details

writeFITSim and writeFITSim16i write multi-dimensional data arrays and header information to FITS-format files. A single image is a two-dimensional array; data cubes contain two dimensions plus one additional dimension for each (often velocity) plane.

Axis data may be given as a data frame axDat, typically from readFITS or, if that is missing, by individual vectors for crpixn, crvaln, etc. axDat has priority over individual vectors. axDat may be edited easily with e.g. axDat <- edit(axDat).

Header data may be added to that the function automatically generates. No or little editing is needed if the header is taken from an existing file by e.g. readFITSheader: writeFITSim will remove reserved keywords in the header that conflict with those generated and add the END statement. See modifyHeader for functions to add to or modify the header.

writeFITSim writes integer or float data matching the data type in the input array. writeFITSim16i scales and shifts the input to write 16-bit integer data with the maximum precision allowed by word length. FITS variables BSCALE and BZERO are automatically updated to allow reconstruction of the original data values. In cases where full precision is not needed, this can reduce file sizes by a factor of about four compared with a double-precision float.

Value

FITS file written to disk.

Note

Graphical FITS viewers such as fv (https://heasarc.gsfc.nasa.gov/ftools/fv/) and SAOImage DS9 (http://ds9.si.edu/) have excellent facilities for displaying FITS data, headers, and file structure. Having one or more graphical viewers available will prove extremely useful for working with FITS files, even when the data are read into R for further processing. fv and SAOImage DS9 are in active devlopement with support for unix, Windows, and Mac OS-X operating systems, and are available at no cost.

Author(s)

Andrew Harris

References

Hanisch et al., Astron.\ Astrophys. 376, 359-380 (2001)

https://fits.gsfc.nasa.gov/

See Also

readFITS, readFITSheader, modifyHeader

Examples

## Make data array with axis information, write to disk
X <- matrix(1:15, ncol = 3)
filename <- paste(tempdir(), "test.fits", sep="")
writeFITSim(X, file = filename, c1 = "Test FITS file",
            crpixn = c(1,1), crvaln = c(10, 100), cdeltn = c(8, 2),
            ctypen = c("Distance", "Time"),
            cunitn = c("Furlongs", "Fortnights"))
## Read back in, modify data offset, header, and axis data information,
## then write modified version as new file
Z <-  readFITS(filename)
Z$imDat <- Z$imDat + 300
Z$header <- addKwv('SCALE', 1.03, 'test header mod', header=Z$header)
# Z$axDat <- edit(Z$axDat)  # interactive edits
Z$axDat$cdelt
Z$axDat$cdelt[2] <- 20
Z$axDat$cdelt
writeFITSim(Z$imDat, file=filename, axDat=Z$axDat, header=Z$header)


### 3-dimensional array example
## Write sample file
X <- array(1:210, dim = c(10, 7, 3))
writeFITSim(X, filename)
## Read back in and display plane 2, no axis scale markings
Z <-  readFITS(filename)
dim(Z$imDat[,,2])
image(Z$imDat[,,2], xaxt = "n", yaxt = "n")
str(Z)
print(Z$axDat)

## Clean up files after examples to avoid clutter
unlink(filename)

### Note: either of the writeFITSim() calls here could be replaced
###       with writeFITSim16i() calls with the identical argument.