Reference

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 posibilities 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.

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)

FitsLogic()

yields a singleton object used 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).

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

opens FITS file filename for reading if mode is "r", for reading and writing if mode is "r+", or creates 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 so it is not necessary to call close(file).

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

openfits(filename, mode="r"; kwds...) -> file

opens FITS file named filename with access mode. See FitsFile for the different modes and keywords.

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

do-block syntax to open a FITS file which is automatically closed at the end of the block. See FitsFile for the different modes and keywords.

open(FitsFile, filename, mode="r"; kwds...) -> file

opens FITS file named filename with access mode. See FitsFile and openfits for the different modes and keywords.

open(f::Function, args...; kwargs....)

Apply the function f to the result of open(args...; kwargs...) and close the resulting file descriptor upon completion.

Examples

julia> open("myfile.txt", "w") do io
           write(io, "Hello world!")
       end;

julia> open(f->read(f, String), "myfile.txt")
"Hello world!"

julia> rm("myfile.txt")

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.

read(io::IO, T)

Read a single value of type T from io, in canonical binary representation.

Note that Julia does not convert the endianness for you. Use ntoh or ltoh for this purpose.

read(io::IO, String)

Read the entirety of io, as a String (see also readchomp).

Examples

julia> io = IOBuffer("JuliaLang is a GitHub organization");

julia> read(io, Char)
'J': ASCII/Unicode U+004A (category Lu: Letter, uppercase)

julia> io = IOBuffer("JuliaLang is a GitHub organization");

julia> read(io, String)
"JuliaLang is a GitHub organization"

read([R::Type,] FitsFile, filename, args...; kwds...) -> data

reads some data in FITS file filename. See readfits for the meaning of arguments and for possible keywords.

write!(FitsFile, 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.

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.

isopen(file::FitsFile)

returns whether file is open.

close(file::FitsFile)

closes the file associated with file.

pathof(file::FitsFile) -> str

yields the name of the FITS file associated with file.

filemode(file::FitsFile)

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

isreadonly(file::FitsFile)

returns whether file is read-only.

iswritable(file::FitsFile)

returns 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

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.