# Read a single data set from a FITS file Read a single image (multi-dimensional array) or binary table from a FITS file. The source code `readFITS.r` is a model for creating code to read more complex FITS files. ```r readFITS(file = "R.fits", hdu = 1, maxLines = 5000, fixHdr = c('none', 'remove', 'substitute'), phdu = 1) ``` ## Arguments - `file`: Existing FITS file name, or remote file; see examples. - `hdu`: Position of Header and Data Unit (HDU) in FITS file: 1 for the first HDU, 2 for the second HDU, etc. - `maxLines`: Integer: maximum number of header lines to read. - `fixHdr`: Deal with (illegal) nonprinting characters in the header. - `phdu`: Rarely needed; see Details. ## Details `readFITS` is a simple but complete FITS file reader, automatically detecting image and binary table data extensions (random groups are not supported in this release). It reads a single Header and Data Unit (HDU) pair from a file and returns a list with data, header, and axis information. Files with more complicated structures or isolated header units can be read with an appropriate combination of `readFITSheader`, `readFITSarray`, and `readFITSbintable`. See the Example section for `readFITSimage` for a step-by-step example that includes file opening and closing. phdu = 0 forces a read of a secondary HDU in a fairly pathological case (specifically: indicating a read of a secondary HDU by setting NAXISn = 0 for n > 1, but NAXIS != 0 and NAXIS1 != 0.) This does not seem to be forbidden by the FITS standard but would be unlikely coding. ... passes additional values for file reading. The only use at present is to pass values to fixHdr in `readFITSheader`. fixHdr attempts to fix headers with non-printing characters, either by removing them with `fixHdr = 'remove'`, reading further into the file until 2880 valid characters are present, or by substituting spaces for non-printing characters with `fixHdr = 'substitute'`. This option should be used with caution, as non-printing characters should not be in the header in the first place, so this option may or may not corrupt the following data. The default is `fixHdr = 'none'`. Partial matching is allowed. Binary table complex, and array descriptor data types are not implemented in this release due to a lack of examples for testing. 8, 16, 24, and 32-bit bit arrays return as integers. Other lengths are not supported. ## Returns Return values from `readFITS` are in a list. Depending on the data type, list entries are: - **header**: Vector with input file header up to END statement. - **hdr**: Vector with `keyword = value` pairs parsed from header. - **imDat**: Data array (image). - **axDat**: Data frame with axis scaling and labels (image). - **F**: Data frame containing a table (table). - **col**: Data from each column (bintable). - **colNames**: Vector of column names, TTYPEn FITS variable (bintable, table). - **colUnits**: Vector of column units, TUNITn FITS variable (bintable, table). - **TNULLn**: Vector of undefined value definitions, FITS variable (bintable, table). - **TSCALn**: Vector of multipliers for scaling, FITS variable (bintable, table). - **TZEROn**: Vector of zeros for scaling, FITS variable (bintable, table). - **TDISPn**: Vector of format information, FITS variable (bintable). ## References Hanisch et al., **Astron.\ Astrophys.** 376, 359-380 (2001) [https://fits.gsfc.nasa.gov/](https://fits.gsfc.nasa.gov/) ## Author(s) Andrew Harris ## Note Graphical FITS viewers such as **fv** ([https://heasarc.gsfc.nasa.gov/ftools/fv/](https://heasarc.gsfc.nasa.gov/ftools/fv/)) and **SAOImage DS9** ([http://ds9.si.edu/](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 for further processing. **fv** and **SAOImage DS9** are in active development with support for unix, Windows, and Mac OS-X operating systems, and are available at no cost. See `readFrameFromFITS` to read a binary table directly into an data frame. ## See Also `readFITSarray`, `readFITSbintable`, `readFITSheader`, `readFrameFromFITS`, `modifyHeader`, `image`, `par` ## Examples ```r require(FITSio) ### Image example ## Make test image with axis information, write to disk Z <- matrix(1:15, ncol = 3) filename <- paste(tempdir(), "test.fits", sep="") writeFITSim(Z, file = filename, c1 = "Test FITS file", crpix = c(1,1), crvaln = c(10, 100), cdeltn = c(8, 2), ctypen = c("Distance", "Time"), cunitn = c("Furlongs", "Fortnights")) ## Read back in and display X <- readFITS(filename) ax1 <- axVec(1, X$axDat) # Make axis vector for image ax2 <- axVec(2, X$axDat) xlab <- X$axDat$ctype[1] ylab <- paste(X$axDat$ctype[2], " [", X$axDat$cunit[2], "]", sep = "") image(ax1, ax2, X$imDat, xlab = xlab, ylab = ylab) str(X) X$axDat # Display data frame with axis data X$hdr[1:10] # Header sample X$hdr[which(X$hdr=="BITPIX")+1] # BITPIX value from header ## No axis scale markings image(X$imDat, xlab = xlab, ylab = ylab, xaxt = "n", yaxt = "n") ## Clean up to avoid clutter unlink(filename) ### Binary table examples ## Bintable with one row and differently multi-dimensional columns ## Either download example file from ## ## and use ## Not run: filename <- "IUElwp25637mxlo.fits" ## or, for local example use filename <- system.file("fitsExamples", "IUElwp25637mxlo.fits", package = "FITSio") Y <- readFITS(filename) ## Look at contents str(Y) Y$colNames str(Y$col) Y$hdr[which(Y$hdr=="BITPIX")+1] # BITPIX value from header plot(Y$col[[5]], ylab = "Value", main = Y$colNames[5], type = "l") ### Simple flat file example filename <- system.file("fitsExamples", "2008_03_11_203150.fits", package = "FITSio") Z <- readFITS(filename) str(Z) Z$colNames str(Z$col) attach(Z) xc <- which(colNames == "DMJD") yc <- which(colNames == "TiltX") xlab <- paste(colNames[xc], " [", colUnits[xc], "]", sep = "") ylab <- paste(colNames[yc], " [", colUnits[yc], "]", sep = "") plot(col[[xc]], col[[yc]], xlab = xlab, ylab = ylab, type = "l") detach(Z) ### Read FITS file directly from URL (thanks to Bi Cheng Wu) ## Not run: require(httr) # provides RETRY() and content() require(magrittr) # provides %>% pipe operator, (part of tidyverse) # fits <- RETRY(verb="GET", url=fits_url) %>% content(type="raw") %>% rawConnection %>% readFITS ## End(Not run) ```

readFITS function