Reference

FitsHDU

is the abstract type of FITS Header Data Units which consists in a header and a data parts. Concrete instances of FitsHDU behave as vectors whose elements are FITS header records, a.k.a. FITS cards, and which can be indexed by integers or by names.

For faster access to the records of a header, consider creating a FITS header object from a HDU object:

hdr = FitsHeader(hdu::FitsHDU)

FitsError <: Exception

is the type of exceptions thrown when an error occurs in the FITSIO library used to manage FITS files.

FitsLogic()

yields a singleton object to indicate that FITS rules should be applied for some logical operation. For example:

isequal(FitsLogic(), s1, s2)

compares strings s1 and s2 according to FITS rules, that is case of letters and trailing spaces are irrelevant.

isequal(FitsLogic(), x) -> f

yields a predicate function f such that f(y) yields isequal(FitsLogic(),x,y).

EasyFITS.Header

is the (union of) type(s) that are accepted to specify a FITS header in EasyFITS package.

A header may be a vector of pairs like key => val, key => (val,com), or key => com with key the keyword name, val its value, and com its comment. The keyword name key is a string or a symbol which is automatically converted to uppercase letters and trailing spaces discarded. The syntax key => com, with com a string, is only allowed for commentary keywords COMMENT or HISTORY. For other keywords, the value is mandatory but the comment is optional, not specifying the comment is like specifying nothing for the comment; otherwise, the comment must be a string. The value val may be missing or undef to indicate that it is undefined. If the comment is too long, it is automatically split across multiple records for commentary keywords and it is truncated for other keywords. A non-commentary keyword may have units specified in square brackets at the beginning of the associated comment. Commentary keywords may appear more than once, other keywords are unique.

For example:

["VERIFIED" => true,
 "COUNT" => (42, "Fundamental number"),
 "SPEED" => (2.1, "[km/s] Speed of gizmo"),
 "USER" => "Julia",
 "AGE" => (undef, "Some undefined value."),
 "JOB" => (missing, "Another undefined value."),
 "HISTORY" => "Some historical information.",
 "COMMENT" => "Some comment.",
 "COMMENT" => "Some other comment.",
 "HISTORY" => "Some other historical information."]

defines a possible FITS header with several records: a keyword VERIFIED having a logical value and no comments, a keyword COUNT having an integer value and a comment, a keyword SPEED having a floating-point value and a comment with units, a keyword USER having a string value, keywords AGE and JOB having comments but undefined values, and a few additional commentary keywords.

A header may also be specified as a named tuple with entries key = val, key = (val,com), or key = com. The same rules apply as above except that key must be allowed as a variable symbolic name (no embedded hyphen '-').

Finally, most methods assume that nothing can be used to indicate an empty header.

EasyFITS.TableData

is the union of types that can possibly be that of FITS table data. Instances of this kind are collections of key => vals or key => (vals, units) pairs with key the column name, vals the column values, and units the optional units of these values. Such collections can be dictionaries, named tuples, vectors, or tuples.

For table data specified by dictionaries or vectors, the names of the columns must all be of the same type.

Owing to the variety of possibilities for representing column values with optional units, EasyFITS.TableData cannot be specific for the values of the pairs in the collection. The package therefore rely on error catcher methods to detect column with invalid associated data.

Another consequence is that there is a non-empty intersection between EasyFITS.TableData and EasyFITS.Header which imposes to rely on position of arguments to distinguish them.

readfits(FitsHeader, filename; ext=1, kwds...) -> hdr::FitsHeader
read(FitsHeader, filename; ext=1, kwds...) -> hdr::FitsHeader
read(filename, FitsHeader; ext=1, kwds...) -> hdr::FitsHeader

Read the header of the ext extension of the FITS file filename. See FitsFile for the possible keywords kwds....

readfits([R::Type,] filename, args...; ext=1, extended=false, kwds...) -> data

reads some data in extension ext (a Header Data Unit number or a name) in FITS file filename. Specify keyword extended = true to use CFITSIO extended filename syntax.

If R is specified, the data is returned as an object of type R. Array type parameters may be specified in R. For example, specify R = Array{Float32} to ensure that the result be a single precision floating-point array.

If the extension is an image, args... specifies the ranges of pixels to read along the dimensions. The default is to read all pixels.

If the extension is a table, args... consist in up to 2 arguments cols and rows to select a subset of columns and of rows respectively. The default is to read all columns and rows.

readfits!(dest, filename, args...; kwds...) -> dest

overwrites destination dest with some data read from FITS file named filename. This is more efficient but is similar to:

copyto!(dest, readfits(typeof(dest), filename, args...; kwds...))

See readfits for the meaning of arguments and for possible keywords.

writefits(filename, hdr, dat, args...; overwrite = false, kwds...)

creates a new FITS file named filename whose contents is specified by hdr, dat, and args.... If the file already exists, the method fails unless keyword overwrite is true. See FitsFile for other keywords that may be specified when opening the file.

Arguments hdr and dat are the header and the data of a 1st Header Data Unit (HDU) to write. Trailing arguments args... are headers and data of optional additional HDUs.

See also writefits! and FitsFile.

writefits!(filename, args...; kwds...)

creates a new FITS file named filename whose contents is specified by args.... If the file already exists, it is (silently) overwritten. This method is equivalent to:

writefits(filename, args...; overwrite = true, kwds...)

See writefits for the meaning of args... and FitsFile for other keywords that may be specified when opening the file.

file = FitsFile(filename, mode="r"; extended=false)

Open FITS file filename for reading if mode is "r", for reading and writing if mode is "rw", or create a new file if mode is "w" or "w!".

File must not exists if mode is "w". File is overwritten if it exists and mode is "w!". The file is automatically closed when the file object is finalized, i.e.. no needs to call close(file).

Keyword extended specifies whether to use extended file name syntax featured by the CFITSIO library.

FitsFile(func::Function, filename, mode="r"; kwds...)

Execute func(file) with file the FITS file filename open for mode access and close file even though func may throw an exception. This is typically used with the do-block syntax:

FitsFile(filename, mode="r"; kwds...) do file
    ... # use file
end

pathof(file::FitsFile) -> filename

Return the name of the FITS file associated with file.

filemode(file::FitsFile)

Return :r, :rw, or :w depending whether file is open for reading only, reading and writing, or writing.

isreadonly(file::FitsFile)

Return whether file is read-only.

iswritable(file::FitsFile)

Return whether file is writable.

seek(file::FitsFile, n) -> type

moves to n-th HDU of FITS file file and returns an integer identifying the type of the HDU:

• FITS_IMAGE_HDU if the n-th HDU contains an image.

• FITS_BINARY_TABLE_HDU if the n-th HDU contains a binary table.

• FITS_ASCII_TABLE_HDU if the n-th HDU contains an ASCII table.

• FITS_ANY_HDU if the n-th HDU is undefined.

An error is thrown if the file has been closed.

See also seekstart(::FitsFile), seekend(::FitsFile), and position(::FitsFile).

seekstart(file::FitsFile) -> type

moves to the first HDU of FITS file file and returns an integer identifying the type of the HDU.

See also seek(::FitsFile).

seekend(file::FitsFile) -> type

moves to the last HDU of FITS file file and returns an integer identifying the type of the HDU.

See also seek(::FitsFile).

position(file::FitsFile) -> n

yields the current HDU number of FITS file file. An error is thrown if the file has been closed.

See also seek(::FitsFile).

flush(f::Union{FitsFile,FitsHDU})

flushes the internal data buffers of f to the associated output FITS file.

eachmatch(pat, file::FitsFile)

yields an iterator over the Header Data Units (HDUs) of FITS file matching pattern pat. Pattern pat can be a string or a regular expression to be matched against the name of the HDUs of file or a predicate function taking a HDU as argument and returning whether it matches.

For example:

for hdu in eachmatch(pat, file)
    ... # do something
end

is a shortcut for:

i = findfirst(pat, file)
while i !== nothing
    hdu = file[i]
    ... # do something
    i = findnext(pat, file, i+1)
end

while:

for hdu in reverse(eachmatch(pat, file))
    ... # do something
end

is equivalent to:

i = findlast(pat, file)
while i !== nothing
    hdu = file[i]
    ... # do something
    i = findprev(pat, file, i-1)
end

hdu = FitsImageHDU(file::FitsFile, dims...; bitpix=...)
hdu = FitsImageHDU{T}(file::FitsFile, dims...)
hdu = FitsImageHDU{T,N}(file::FitsFile, dims...)

create a new primary array or image extension in FITS file file with a specified pixel type T and size dims.... If the FITS file is currently empty then a primary array is created, otherwise a new image extension is appended to the file. Pixel type can be specified as a numeric type T or as an integer BITPIX code bitpix.

An object to manage the new extension is returned which can be used to push header cards and then to write the data.

If the array to be written is available, the element type and dimensions can be inferred from the array itself:

hdu = FitsImageHDU{T=eltype(arr),N=ndims(arr)}(file::FitsFile, arr::AbstractArray)

For example:

hdu = FitsImageHDU(file, arr)
hdu["KEY1"] = val1             # add a 1st header record
hdu["KEY2"] = (val2, str2)     # add a 2nd header record
hdu["KEY3"] = (nothing, str3)  # add a 3rd header record
write(hdu, arr)                # write data

will create a new Header Data Unit (HDU) storing array arr with 3 additional header records: one named "KEY1" with value val1 and no comments, another named "KEY2" with value val2 and comment string str2, and yet another one named "KEY3" with no value and with comment string str3. Note that special names "COMMENT", "HISTORY", and "" indicating commentary entries have no associated, only a comment string, say str which can be specified as str or as (nothing,str).

read(R::Type = Array, hdu::FitsImageHDU[, inds...]) -> arr::R

reads the FITS image data in hdu or the rectangular sub-region defined by the indices inds... if specified.

Optional argument R is to restrict the ouput type and improve type-stability. For example:

arr = convert(Array{Float32}, read(hdu))
arr = read(Array{Float32}, hdu)
arr = read(Array{Float32,3}, hdu)

yield similar results if hdu is a 3-dimensional image extension but the 2nd example is more efficient than the 1st one as no temporary array is needed if the pixel type is not equivalent to Float32 and the 3rd example is completely type-stable.

Keywords anynull and null may be specified to deal with undefined pixel values (see documentation for read!).

read!(arr::DenseArray{<:Number}, hdu::FitsImageHDU[, inds...]) -> arr

overwrites all the elements of the array arr with pixel values read from the FITS image data in hdu and returns arr. Pixel values are converted to the element type of arr.

If inds... are specified, only the rectangular sub-region defined by inds... is read and the destination array must have the same dimensions as this region (the same rules as for sub-indexing an array are applied to determine the dimensions of the sub-region).

If inds... are not specified, the complete image is read unless another value than nothing (the default) is given to the keywords first and/or last:

• To read a rectangular sub-image, set keywords first and last with N-tuple of integers indicating the coordinates of the first and last pixels to read. Optionally, keyword step may be set to an N-tuple of integers to indicate the increment along each dimensions. Increments must be positive. Here N is the number of dimensions of the FITS image extension.

• To read consecutive pixels, specify at least one of the keywords first and/or last with an integer indicating the index of the first and/or last pixels to read.

When at least one of the keywords first and/or last is not nothing, the dimensions of the destination arr are not considered. In any case, the number of elements of arr must be equal to the number of pixels to read.

Keyword anynull may be specified with a reference to a boolean (Ref{Bool}()) to retrieve whether any of the read pixels is undefined.

Keyword null may be specified with a reference to a value of the same type as the elements of the destination arr (Ref{eltype(arr)}()) to retrieve the value of undefined pixels. Unless reading a rectangular sub-image, keyword null may be set with an array of Bool of same size as arr and which will be set to true for undefined pixels and to false elsewhere.

Output arrays arr and null must have contiguous elements, in other words, they must be dense arrays.

write(hdu::FitsImageHDU, arr::AbstractArray{<:Number}) -> hdu

writes all the elements of the array arr to the pixels of the FITS image extension of the header data unit hdu. The element of arr are converted to the type of the pixels. The default is to write the complete image pixels, so the size of the destination arr must be identical to the dimensions of the FITS image extension. This behavior may be changed by specifying another value than nothing for the keywords first and/or last:

• To write a rectangular sub-image, specify keywords first and last with the coordinates of the first and last pixels to write as an N-tuple of integers, with N the number of dimensions of the FITS image extension.

• To write consecutive pixels, specify at least one of the keywords first and/or last with the index of the first and/or last pixels to write as an integer.

When at least one of the keywords first and/or last is not nothing, the dimensions of arr are not considered. In any case, the number of elements of arr must be equal to the number of pixels to write.

Unless writing a rectangular sub-image, keyword null may be used to specify the value of undefined elements in arr. For integer FITS images, the FITS null value is defined by the BLANK keyword (an error is returned if the BLANK keyword doesn't exist). For floating point FITS images the special IEEE NaN (Not-a-Number) value will be written into the FITS file.

hdu = FitsTableHDU(file, cols...)

creates a new FITS table extension in FITS file file with columns defined by cols.... Each column definition is a pair name => format where name is the column name while format specifies the type of the column values and, optionally, their units and the size of the column cells. The following definitions are possible:

name => type
name => (type,)
name => (type, units)
name => (type, dims)
name => (type, units, dims)
name => (type, dims, units)

where type is either a Julia type (Number or String) or a letter (see table below), dims is an integer or a tuple of integers, and units is a string. By default, dims = (1,) and units = "".

The returned object can be used to add FITS keywords to the header of the table and, then, to write column data. Typically:

hdu = FitsTableHDU(file, cols)
push!(hdu, key1 => val1) # add a first header keyword
...                      # add other header keywords
write(hdu, col1 => arr1) # write a first column
...                      # write other columns

where key1 => val1, key2 => val2, etc. specify header cards, while col1 => arr1, col2 => arr2, etc. specify columns names and associated data. Such a table may be created in a single call:

write(file, [key1 => val1, key2 => val2, ...], [col1 => arr1, col2 => arr2, ...])

read([Dict,] hdu::FitsTableHDU[, cols[, rows]]) -> dict

reads several columns of the FITS table extension in hdu as a dictionary indexed by the column names. The columns to read can be specified by cols which may be a single column name/index, a tuple/range/vector of column names/numbers, or a colon : to read all columns (the default). Column names may be strings or symbols (not a mixture of these). The rows to read can be specified by rows as a single row index, a unit range of row numbers, or a colon : to read all rows (the default).

Keyword rename is to specify a function to change column names. If unspecified, the column names are left unchanged if keyword case is true and converted to uppercase letters otherwise.

Keyword units can be used to indicate whether to retrieve the units of the columns. If units is String, the values of the dictionary will be 2-tuples (data,units) with data the column data and units the column units as a string. Otherwise, if units is nothing (the default), the values of the dictionary will just be the columns data.

To avoid the units keyword, the following methods are provided:

read(Dict{String,Array},               hdu[, cols[, rows]])
read(Dict{String,Tuple{Array,String}}, hdu[, cols[, rows]])

to yield the same result as read(hdu,...) with respectively units=nothing and units=String.

read(Vector, hdu::FitsTableHDU[, cols[, rows]]) -> vec::Vector

reads some columns of the FITS table extension in hdu as a vector. The columns to read can be specified by cols which may be a single column name/index, a tuple/range/vector of column names/numbers, or a colon : to read all columns (the default). Column names may be strings or symbols (not a mixture of these). The rows to read can be specified by rows as a single row index, a unit range of row numbers, or a colon : to read all rows (the default). V is the type of the result.

Keyword units can be used to indicate whether to retrieve the units of the columns. If units is String, the elements of the result will be 2-tuples (data,units) with data the column data and units the column units as a string. Otherwise, if units=nothing (the default), the elements of the result will just be the columns data.

To avoid the units keyword and allow more control on the type of the result, the following 2 methods are provided:

read(Vector{<:Array},               hdu[, cols[, rows]])
read(Vector{Tuple{<:Array,String}}, hdu[, cols[, rows]])

to yield the same result as read(hdu,...) with respectively units=nothing and units=String.

read([R=Array,] hdu::FitsTableHDU, col[, rows]; kwds...) -> vals::R

reads a single column col of the FITS table extension in hdu and returns its values and, possibly, its units.

The column col may be specified by its name or by its number. If col is a string or a symbol, keyword case specifies whether the case of letters matters (case = false by default).

Optional leading argument R is to specify the type of the result which can be an array type, to only retrieve the column values, or a tuple of array and string types, to retrieve the column values and their units.

Optional argument rows is to specify which rows to read. It can be an integer to read a single row, a unit range of integers to read these rows, or a colon : to read all rows (the default). Use hdu.first_row and hdu.last_row to retrieve the first and last row numbers.

See read! for the other possible keywords.

read!(dict, hdu::FitsTableHDU[, cols[, rows]]) -> dict

merges the contents of the dictionary dict with the column(s) cols read from the FITS table extension in hdu and returns the dictionary.

Previous contents of dict is not erased, call read!(empty!(dict),hdu,...) to erase any contents prior to reading.

The case keyword specify whether to consider the case of characters in column names. By default, case = false.

The rename keyword may be specified with a function that converts the column names into dictionary keys. If unspecified, the default is to convert column names to uppercase characters if keyword case is false and to leave column names unchanged otherwise.

read!(arr::DenseArray, hdu::FitsTableHDU, col) -> arr

overwrites the elements of array arr with values of the column col of the FITS table extension in hdu and returns arr.

The column col may be specified by its name or by its number. If col is a string or a symbol, keyword case indicates whether the case of letters matters (case = false by default).

Keyword first may be specified with the index of the first row to read. By default, first = hdu.first_row and reading starts at the first row of the table.

Keyword anynull may be specified with a reference to a boolean (Ref{Bool}()) to retrieve whether any of the read values is undefined.

Keyword null may be specified with a reference to a value of the same type as the elements of the destination arr (Ref{eltype(arr)}()) to retrieve the value of undefined values. Keyword null may also be set with an array of Bool of same size as arr and which will be set to true for undefined values and to false elsewhere.

Output arrays arr and null must have contiguous elements, in other words, they must be dense arrays.

FitsHeader(hdu::FitsHDU)

reads all records of the header of hdu and returns an efficient object representing them.

nameof(hdu::FitsHDU) -> str

yields the name of the FITS header data unit hdu. The result is the value of the first keyword of "EXTNAME" or "HDUNAME" which exists and has a string value. If none of these keywords exist, the result is hdu.xtension which is the name of the FITS extension of hdu, that is "IMAGE", "TABLE", "BINTABLE", or "ANY" depending on whether hdu is an image, an ASCII table, a binary table, or anything else.

EasyFITS.is_named(hdu, pat) -> bool

yields whether pattern pat is equal to (in the FITS sense if pat is a string) or matches (if pat is a regular expression) the extension of the FITS header data unit hdu, or to the value of one of its "EXTNAME" or "HDUNAME" keywords. These are respectively given by hdu.xtension, hdu.extname, or hdu.hduname.

This method is used as a predicate for the search methods findfirst, findlast, findnext, and findprev.

The extension hdu.xtension is "IMAGE", "TABLE", "BINTABLE", or "ANY" depending on whether hdu is an image, an ASCII table, a binary table, or anything else.

EasyFITS.is_named(pat) -> pred

yields e predicate function pred that can be used to check whether pattern pat is equal to (in the FITS sense if pat is a string) or matches (if pat is a regular expression) the extension of the FITS header data units (HDUs).

s = EasyFITS.OutputCstring(len)

Build an object that can be used as an output C string with at most len characters. This object can be passed to a C function where an output string is expected via a ccall as an argument of type Cstring. On return of the C function, the object can be safely converted to a Julia string by calling String(s).

EasyFITS.cfitsio_errmsg(status) -> msg::String

Return the error message corresponding to CFITSIO status.

EasyFITS.cfitsio_errmsg() -> msg::Union{String,Nothing}

Read the oldest CFITSIO error message and discard it. nothing is returned if there are no error messages left.