API Reference

FITS(filename::String[, mode::String = "r"]; extendedparser = true)

Open or create a FITS file. mode can be one of "r" (read-only), "r+" (read-write) or "w" (write). In "write" mode, any existing file of the same name is overwritten.

A FITS object is a collection of "Header-Data Units" (HDUs) and supports the following operations:

• f[i]: Return the i-th HDU.

• f[name] or f[name, ver]: Return the HDU containing the given the given EXTNAME (or HDUNAME) keyword (a String), and optionally the given EXTVER (or HDUVER) number (an Integer).

• Iteration:

  for hdu in f
      ...
  end

The keyword argument extendedparser may be used to enable or disable the extended filename parser. If disabled, filename is treated exactly as the name of the file and is not tokenized into parameters.

length(f::FITS)

Number of HDUs in the file.

length(hdr::FITSHeader)

Number of records in header of HDU.

length(hdu::ImageHDU)

Get total number of pixels in image (product of size(hdu)).

flush(f::FITS)

Flush the FITS file to disk. This is equivalent to closing and reopening the file.

close(f::FITS)

Close the file.

Subsequent attempts to operate on f will result in an error. FITS objects are also automatically closed when they are garbage collected.

deleteat!(f::FITS, i::Integer)

Delete the HDU at index i in the FITS file. If i == 1, this deletes the primary HDU and replaces it with a bare HDU with no data and a minimal header. If i > 1, this removes the HDU at index i and moves the following HDUs forward.

write_checksum(hdu::HDU)

Write the checksum for the HDU and the data to the header.

verify_checksum(f::HDU)

Verify the integrity of the HDU, by computing the checksum and comparing it to the stored value. This will raise an error if the checksum does not match, or if the keywords are missing in the header.

read_key(hdu::HDU, key::String) -> (value, comment)

Read the HDU header record specified by keyword and return a tuple where value is the keyword parsed value (of type String, Bool, Int, Float64 or Nothing), comment is the keyword comment (as a string). Throw an error if key is not found.

read_key(hdu::HDU, key::Integer) -> (keyname, value, comment)

Same as above but FITS card is specified by its position and returns a 3 element tuple where keyname is the keyword name (a string).

write_key(hdu::HDU, key::String, value[, comment])

Write a keyword value the HDU's header. value can be a standard header type (String, Bool, Integer, AbstractFloat) or nothing, in which case the value part of the record will be empty. If the keyword already exists, the value will be overwritten. The comment will only be overwritten if given. If the keyword does not already exist, a new record will be appended at the end of the header.

read_header(filename::AbstractString, hduindex = 1) -> FITSHeader

Convenience function to read the entire header corresponding to the HDU at index hduindex contained in the FITS file named filename. Functionally read_header(filename, hduindex) is equivalent to

FITS(filename, "r") do f
    read_header(f[hduindex])
end

read_header(hdu::HDU) -> FITSHeader

Read the entire header from the given HDU and return a FITSHeader object. The value of each header record is parsed as Int, Float64, String, Bool or nothing according to the FITS standard.

If the value cannot be parsed according to the FITS standard, the value is stored as the raw unparsed String.

read_header(hdu::HDU, String) -> String

Read the entire header from the given HDU as a single string.

FITSHeader(keys::Vector{String}, values::Vector, comments::Vector{String})

An in-memory representation of the header of an HDU. It stores the (key, value, comment) information for each 80-character "card" in a header.

Note that this structure is not linked to a FITS file in any way; it is just a convenient structure for storing the header contents after reading from a file. (This is similar to how an Array returned by read(f[1]) is not linked to the FITS file f.) Manipulating a FITSHeader will therefore have no immediate impact on any file, even if it was created by read_header(::HDU). You can, however, write a FITSHeader to a file using the write(::FITS, ...) methods that append a new HDU to a file.

Examples

julia> using FITSIO

julia> FITSHeader(["Key1", "Key2"], [1.0, "one"], ["Comment1", "Comment2"])
Key1    =                  1.0 / Comment1
Key2    = 'one     '           / Comment2

If WCS.jl is loaded, then a FITSHeader can also be constructed from a WCS.WCSTransform.

FITSHeader(cards::AbstractVector{<:NamedTuple})

Construct a FITSHeader from a vector of NamedTuples with the following fields: key, value, and comment.

Examples

julia> using FITSIO

julia> FITSHeader([
           (key = "Key1", value = 1.0, comment = "Comment1"),
           (key = "Key2", value = "one", comment = "Comment2"),
       ])
Key1    =                  1.0 / Comment1
Key2    = 'one     '           / Comment2

FITSHeader(wcs::WCS.WCSTransform)

Construct a FITSHeader from a WCSTransform supplied by WCS.jl.

Examples

julia> using FITSIO, WCS

julia> wcs = WCSTransform(2;
           cdelt = [-0.066667, 0.066667],
           ctype = ["RA---AIR", "DEC--AIR"],
           crpix = [-234.75, 8.3393],
           crval = [0., -90],
           pv    = [(2, 1, 45.0)],
       )
WCSTransform(naxis=2, cdelt=[-0.066667, 0.066667], crval=[0.0, -90.0], crpix=[-234.75, 8.3393])

julia> FITSHeader(wcs)
WCSAXES = '2       '           / Number of coordinate axes
CRPIX1  = '-234.7500'          / Pixel coordinate of reference point
CRPIX2  = '8.3393  '           / Pixel coordinate of reference point
CDELT1  = '-0.066667'          / [deg] Coordinate increment at reference point
CDELT2  = '0.066667'           / [deg] Coordinate increment at reference point
CUNIT1  = 'deg     '           / Units of coordinate increment and value
CUNIT2  = 'deg     '           / Units of coordinate increment and value
CTYPE1  = 'RA---AIR'           / Right ascension, Airys zenithal projection
CTYPE2  = 'DEC--AIR'           / Declination, Airys zenithal projection
CRVAL1  = '0.0     '           / [deg] Coordinate value at reference point
CRVAL2  = '-90.0   '           / [deg] Coordinate value at reference point
PV2_1   = '45.0    '           / AIR projection parameter
LONPOLE = '180.0   '           / [deg] Native longitude of celestial pole
LATPOLE = '-90.0   '           / [deg] Native latitude of celestial pole
MJDREF  = '0.0     '           / [d] MJD of fiducial time
RADESYS = 'ICRS    '           / Equatorial coordinate system
COMMENT WCS header keyrecords produced by WCSLIB 7.7

length(hdr::FITSHeader)

Number of records in header of HDU.

haskey(hdr::FITSHeader, key::String)

Returns true if key exists in header, otherwise false.

keys(hdr::FITSHeader)

Array of keywords in header of HDU (not a copy).

values(hdr::FITSHeader)

Array of values in header of HDU (not a copy).

get_comment(hdr::FITSHeader, key_or_index::Union{String,Integer})

Get the comment based on keyword or index.

set_comment!(hdr::FITSHeader, key_or_index::Union{String,Integer}, comment::String)

Set the comment based on keyword or index.

default_header(data::AbstractArray)

Creates a default header for the given array with the SIMPLE, BITPIX, NAXIS, NAXIS*, and EXTEND entries.

read(hdu::ImageHDU)
read(hdu::ImageHDU, range...)

Read the data array or a subset thereof from disk. The first form reads the entire data array. The second form reads a slice of the array given by the specified ranges or integers. Dimensions specified by integers will be dropped in the returned array, while those specified by ranges will be retained.

read!(hdu::ImageHDU, A::StridedArray)
read!(hdu::ImageHDU, A::StridedArray, range...)

Read the data or a subset thereof from disk, and save it in a pre-allocated output array A. The first form reads the entire data from disk. The second form reads a slice of the array given by the specified ranges or integers. The array A needs to have the same length as the number of elements to be read in. Additionally A needs to be stored contiguously in memory.

fitsread(filename::AbstractString[, hduindex = 1[, arrayindices...]]; extendedparser = true)

Convenience function to read in an image corresponding to the HDU at index hduindex contained in the FITS file named filename. If arrayindices are provided, only a slice of the image corresponding to the indices is read in.

Functionally fitsread(filename, hduindex, arrayindices...; extendedparser) is equivalent to

FITS(filename, "r"; extendedparser = extendedparser) do f
    read(f[hduindex], arrayindices...)
end

The keyword argument extendedparser may be used to enable or disable the extended filename parser. If disabled, filename is treated exactly as the name of the file and is not tokenized into parameters.

See also: read

write(f::FITS, data::StridedArray{<:Real};
    header=nothing, name=nothing, ver=nothing, checksum::Bool=false)

Add a new image HDU to FITS file f with contents data. The following array element types are supported: UInt8, Int8, UInt16, Int16, UInt32, Int32, Int64, Float32, Float64. If a FITSHeader object is passed as the header keyword argument, the header will also be added to the new HDU.

The keyword argument checksum may be set to true to enable writing a checksum for the HDU. This is not enabled by default, as it can significantly slow down writing large HDUs.

write(hdu::ImageHDU, data::StridedArray{<:Real}; checksum::Bool=false)

Write data to an existing image HDU.

The keyword argument checksum may be set to true to enable writing a checksum for the HDU. This is not enabled by default, as it can significantly slow down writing large HDUs.

fitswrite(filename::AbstractString, data; extendedparser = true, kwargs...)

Convenience function to write the image array data to a file named filename.

Functionally fitswrite(filename, data; extendedparser, kwargs...) is equivalent to

FITS(filename, "w"; extendedparser = extendedparser) do f
    write(f, data; kwargs...)
end

The keyword argument extendedparser may be used to enable or disable the extended filename parser. If disabled, filename is treated exactly as the name of the file and is not tokenized into parameters.

See also: write

eltype(hdu::ImageHDU)

Return the element type of the image in hdu.

ndims(hdu::ImageHDU)

Get number of image dimensions, without reading the image into memory.

size(hdu::ImageHDU)
size(hdu::ImageHDU, i)

Get image dimensions (or ith dimension), without reading the image into memory.

length(hdu::ImageHDU)

Get total number of pixels in image (product of size(hdu)).

copy_section(hdu, dest, r...)

Copy a rectangular section of an image and write it to a new FITS primary image or image extension in FITS object dest. The new image HDU is appended to the end of dest. All the keywords in the input image will be copied to the output image. The common WCS keywords will be updated if necessary to correspond to the coordinates of the section.

Examples

Copy the lower-left 200 x 200 pixel section of the image in hdu to an open file, f

copy_section(hdu, f, 1:200, 1:200)

Same as above but only copy odd columns in y:

copy_section(hdu, f, 1:200, 1:2:200)

colnames(hdu) -> Vector{String}

Return the names of columns in a table HDU.

write(f::FITS, data::Dict;
      hdutype=TableHDU, name=nothing, ver=nothing,
      header=nothing, units=nothing, varcols=nothing,
      checksum::Bool=false)

Create a new table extension and write data to it. If the FITS file is currently empty then a dummy primary array will be created before appending the table extension to it. data should be a dictionary with String keys (giving the column names) and Array values (giving data to write to each column). The following types are supported in binary tables: UInt8, Int8, UInt16, Int16, UInt32, Int32, UInt64, Int64, Float32, Float64, Complex{Float32}, Complex{Float64}, String, Bool.

Optional inputs:

• hdutype: Type of table extension to create. Can be either TableHDU (binary table) or ASCIITableHDU (ASCII table).
• name: Name of extension.
• ver: Version of extension (Int).
• header: FITSHeader instance to write to new extension.
• units: Dictionary mapping column name to units (as a string).
• varcols: An array giving the column names or column indicies to write as "variable-length columns".
• checksum: A boolean flag to specify whether to write a checksum for the new extension. Defaults to false.

write(f::FITS, colnames, coldata;
      hdutype=TableHDU, name=nothing, ver=nothing,
      header=nothing, units=nothing, varcols=nothing,
      checksum::Bool=false)

Same as write(f::FITS, data::Dict; ...) but providing column names and column data as a separate arrays. This is useful for specifying the order of the columns. Column names must be Vector{String} and column data must be a vector of arrays.

read(hdu::TableHDU, colname; case_sensitive=true)

Read a column as an array from the given table HDU.

The column name may contain wild card characters (*, ?, or #). The * wild card character matches any sequence of characters (including zero characters) and the ? character matches any single character. The # wildcard will match any consecutive string of decimal digits (0-9). The string must match a unique column. The optional boolean keyword case_sensitive, true by default, specifies whether the column name is to be considered case sensitive.