fits_create_ascii_tbl(f::FITSFile, numrows::Integer,
                      coldefs::Union{Array{NTuple{3,String}}, Array{NTuple{2,String}}},
                      extname::Union{String, Nothing} = nothing)

Append a new HDU containing an ASCII table.

The table will have numrows rows (this parameter can be set to zero), each initialized with the default value. In order to create a table, the programmer must specify the characteristics of each column. The columns are specified by the coldefs variable, which is an array of tuples. Each tuple must have two or three string fields:

1. The name of the column.
2. The data type and the repetition count. It must be a string made by a number (the repetition count) followed by a letter specifying the type (in the example above, D stands for Float64, E stands for Float32, A stands for Char). Refer to the CFITSIO documentation for more information about the syntax of this parameter.
3. The unit of this field. This is used to set the corresponding TUNITn keywords. If coldefs is a two-tuple, the unit keywords are left unset. If the third field of a tuple is an empty string, the corresponding unit keyword is also left unset.

The value of extname sets the "extended name" of the table, i.e., a string that in some situations can be used to refer to the HDU itself. This may be omitted by setting extname to nothing (which is the default behavior).

Note that, unlike for binary tables, CFITSIO puts some limitations to the types that can be used in an ASCII table column. Refer to the CFITSIO manual for further information.

See also fits_create_binary_tbl for a similar function which creates binary tables. In general, one should pick this function for creating tables in a new HDU, as binary tables require less space on the disk and are more efficient to read and write. (Moreover, a few datatypes are not supported in ASCII tables).

Example

julia> fname = joinpath(mktempdir(), "test.fits");

julia> f = fits_create_file(fname);

julia> cols = [
                ("ID", "I6", ""),
                ("VALUE", "F10.2", "meters"),
                ("NAME", "A10", "")
            ];

julia> fits_create_ascii_tbl(f, 0, cols);

julia> fits_write_col(f, 1, 1, 1, Int32[1, 2, 3, 4, 5])

julia> fits_write_col(f, 2, 1, 1, Float64[1.1, 2.2, 3.3, 4.4, 5.5])

julia> fits_write_col(f, 3, 1, 1, ["alpha", "beta", "gamma", "delta", "epsilon"])

julia> close(f)

julia> f = fits_open_file(fname, CFITSIO.READONLY);

julia> fits_get_num_hdus(f)
2

julia> fits_movabs_hdu(f, 2)
:ascii_table

julia> nrows = fits_get_num_rows(f)
5

julia> fits_get_num_cols(f)
3

julia> fits_read_col(f, 1, 1, 1, Vector{Int32}(undef, nrows))
5-element Vector{Int32}:
 1
 2
 3
 4
 5

julia> close(f)

fits_create_binary_tbl(f::FITSFile, numrows::Integer,
                       coldefs::Union{Array{NTuple{3,String}}, Array{NTuple{2,String}}},
                       extname::Union{String, Nothing} = nothing)

Append a new HDU containing a binary table. The meaning of the parameters is the same as in a call to fits_create_ascii_tbl.

In general, one should pick this function for creating tables in a new HDU, as binary tables require less space on the disk and are more efficient to read and write. (Moreover, a few datatypes are not supported in ASCII tables).

Example

julia> fname = joinpath(mktempdir(), "test.fits");

julia> f = fits_create_file(fname);

julia> coldefs = [
           ("col1", "1J", "units"),
           ("col2", "1E", ""),
           ("col3", "1A", "m/s"),
       ];

julia> fits_create_binary_tbl(f, 0, coldefs);

julia> fits_write_col(f, 1, 1, 1, [1, 2, 3]);

julia> fits_write_col(f, 2, 1, 1, [1.0, 2.0, 3.0]);

julia> fits_write_col(f, 3, 1, 1, ["a", "b", "c"]);

julia> close(f)

julia> f = fits_open_file(fname, CFITSIO.READONLY);

julia> fits_get_num_hdus(f)
2

julia> fits_movabs_hdu(f, 2)
:binary_table

julia> fits_get_num_rows(f)
3

julia> fits_get_num_cols(f)
3

julia> fits_read_col(f, 1, 1, 1, zeros(Int32, 3))
3-element Vector{Int32}:
 1
 2
 3

julia> close(f)

fits_create_tbl(f::FITSFile, tbltype, numrows::Integer,
    ttype::Vector{String}, tform::Vector{String},
    tunit::Union{Vector{String}, Nothing} = nothing,
    extname::Union{String, Nothing} = nothing)

Create a new table HDU in the FITS file f with the specified parameters. The tbltype sets the type of the table, which can be either CFITSIO.ASCII_TBL or CFITSIO.BINARY_TBL. The numrows parameter reserves space for a specified number of rows in the table, and it can be set to zero if the table is populated later. The ttype and tform parameters specify the names and types of the columns in the table, respectively. The tunit parameter is optional and can be used to specify the units of the columns. If tunit is not provided, the units will not be set in the table. The extname parameter is also optional and can be used to set the extended name of the table. If extname is not provided, the table will not have an extended name. The ttype, tform, and tunit parameters must be vectors of the same length, where each element corresponds to a column in the table.

Example

julia> fname = joinpath(mktempdir(), "test.fits");

julia> f = fits_create_file(fname);

julia> ttype = ["col1", "col2", "col3"];

julia> tform = ["1J", "1E", "1A"];

julia> tunit = ["units1", "units2", "m/s"];

julia> fits_create_tbl(f, CFITSIO.BINARY_TBL, 0, ttype, tform, tunit);

julia> fits_write_col(f, 1, 1, 1, [1, 2, 3]);

julia> fits_write_col(f, 2, 1, 1, [1.0, 2.0, 3.0]);

julia> fits_write_col(f, 3, 1, 1, ["a", "b", "c"]);

julia> close(f);

julia> f = fits_open_file(fname, CFITSIO.READONLY);

julia> fits_get_num_hdus(f)
2

julia> fits_movabs_hdu(f, 2)
:binary_table

julia> fits_get_num_rows(f)
3

julia> fits_get_num_cols(f)
3

julia> fits_read_col(f, 1, 1, 1, zeros(Int32, 3))
3-element Vector{Int32}:
 1
 2
 3

julia> close(f);

See also fits_create_ascii_tbl and fits_create_binary_tbl for similar functions that create ASCII and binary tables, respectively.

fits_delete_col(f::FITSFile, colnum::Integer)

Delete the column at position colnum in the current HDU.

Example

julia> fname = joinpath(mktempdir(), "test.fits");

julia> f = fits_create_file(fname);

julia> fits_create_binary_tbl(f, 0, [("col1", "1J", "units"), ("col2", "1E", "units")]);

julia> fits_write_col(f, 1, 1, 1, [1, 2, 3]);

julia> fits_write_col(f, 2, 1, 1, [1.0, 2.0, 3.0]);

julia> fits_get_num_cols(f)
2

julia> fits_get_coltype(f, 1)
(41, 1, 4)

julia> fits_delete_col(f, 1); # delete the first column

julia> fits_get_num_cols(f)
1

julia> fits_get_coltype(f, 1)
(42, 1, 4)

julia> close(f)

fits_delete_rowlist(f::FITSFile, rowlist::Vector{<:Integer})

Delete a list of rows from the current HDU. The rows to be deleted are specified by the rowlist vector, which contains the row numbers to be deleted. The row numbers are 1-based, so the first row is at position 1.

Example

julia> fname = joinpath(mktempdir(), "test.fits");

julia> f = fits_create_file(fname);

julia> fits_create_binary_tbl(f, 0, [("col1", "1J", "units")]);

julia> fits_write_col(f, 1, 1, 1, [1, 2, 3, 4, 5])

julia> CFITSIO.fits_flush_file(f); # flush the file to disk

julia> fits_delete_rowlist(f, [1, 3, 5]); # delete rows 1, 3 and 5

julia> fits_read_col(f, 1, 1, 1, zeros(Int32, 2))
2-element Vector{Int32}:
 2
 4

julia> close(f);

fits_get_colnum(f::FITSFile, tmplt::String; case_sensitive::Bool = true)

Return the column number of the first column whose name matches the template tmplt. If no column matches, an error is thrown. The template can contain the * character, which matches any number of characters. The keyword argument case_sensitive determines whether the search is case-sensitive or not.

Example

julia> fname = joinpath(mktempdir(), "test.fits");

julia> f = fits_create_file(fname);

julia> fits_create_binary_tbl(f, 0, [("Count", "1J", "units"), ("Energy", "1E", "eV")]);

julia> fits_get_colnum(f, "Energy")
2

julia> fits_get_colnum(f, "e*"; case_sensitive = false)
2

julia> fits_get_colnum(f, "col")
ERROR: CFITSIO has encountered an error. Error code 219: named column not found
Detailed error message follows:
ffgcnn could not find column: col
[...]

julia> close(f)

fits_get_coltype(f::FITSFile, colnum::Integer)

Provided that the current HDU contains either an ASCII or binary table, return information about the column at position colnum (counting from 1).

Returns a tuple containing

• typecode: CFITSIO integer type code of the column.
• repcount: Repetition count for the column.
• width: Width of an individual element.

Example

julia> fname = joinpath(mktempdir(), "test.fits");

julia> f = fits_create_file(fname);

julia> fits_create_binary_tbl(f, 0, [("col1", "1J", "units")]);

julia> fits_get_coltype(f, 1)
(41, 1, 4)

julia> close(f)

fits_get_eqcoltype(ff::FITSFile, colnum::Integer)

Provided that the current HDU contains either an ASCII or binary table, return information about the column at position colnum (counting from 1). This returns the equivalent data type of the column.

Returns a tuple containing

• typecode: CFITSIO integer type code of the column.
• repcount: Repetition count for the column.
• width: Width of an individual element.

Example

julia> fname = joinpath(mktempdir(), "test.fits");

julia> f = fits_create_file(fname);

julia> fits_create_binary_tbl(f, 0, [("col1", "1I", "units")]); # Int16 values

julia> fits_write_key(f, "TSCAL1", 0.1, "scale factor")

julia> fits_write_key(f, "TZERO1", 0.0, "zero point")

julia> fits_get_eqcoltype(f, 1) # equivalent element type is Float32, code 42
(42, 1, 2)

julia> close(f)

fits_get_num_cols(f::FITSFile)

Return the number of columns in the current table HDU.

Example

julia> fname = joinpath(mktempdir(), "test.fits");

julia> f = fits_create_file(fname);

julia> fits_create_binary_tbl(f, 0, [("col1", "1J", "units")]);

julia> close(f)

julia> f = fits_open_file(fname, CFITSIO.READONLY);

julia> fits_movabs_hdu(f, 2);

julia> fits_get_num_cols(f)
1

julia> close(f)

fits_get_num_rows(f::FITSFile)

Return the number of rows in the current table HDU.

Example

julia> fname = joinpath(mktempdir(), "test.fits");

julia> f = fits_create_file(fname);

julia> fits_create_binary_tbl(f, 0, [("col1", "1J", "units")]);

julia> fits_get_num_rows(f)
0

julia> fits_write_col(f, 1, 1, 1, [1, 2, 3]);

julia> fits_get_num_rows(f)
3

julia> close(f)

fits_get_rowsize(f::FITSFile)

Return optimal number of rows to read or write at one time for maximum I/O efficiency.

fits_insert_col(f::FITSFile, colnum::Integer, ttype::String, tform::String)

Insert a new column at position colnum in the current table HDU. The ttype and tform parameters specify the name and type of the column, respectively.

Example

julia> fname = joinpath(mktempdir(), "test.fits");

julia> f = fits_create_file(fname);

julia> fits_create_binary_tbl(f, 0, [("col1", "1J", "units")]);

julia> fits_insert_col(f, 2, "col2", "1E");

julia> fits_write_col(f, 2, 1, 1, [1.0, 2.0, 3.0]);

julia> fits_read_col(f, 2, 1, 1, zeros(Float32, 3))
3-element Vector{Float32}:
 1.0
 2.0
 3.0

julia> close(f);

fits_insert_cols(f::FITSFile, colnum::Integer,
    ttype::Vector{String}, tform::Vector{String})

Insert a number of new columns at position colnum in the current table HDU. The ttype and tform parameters specify the names and types of the columns, respectively. The length of ttype and tform must match, as each column corresponds to one element in these vectors.

Example

julia> fname = joinpath(mktempdir(), "test.fits");

julia> f = fits_create_file(fname);

julia> fits_create_binary_tbl(f, 0, [("col1", "1J", "units")]);

julia> fits_insert_cols(f, 2, ["col2", "col3"], ["1E", "1D"]);

julia> fits_write_col(f, 2, 1, 1, [1.0, 2.0, 3.0]);

julia> fits_write_col(f, 3, 1, 1, [1.0, 2.0, 3.0]);

julia> fits_read_col(f, 2, 1, 1, zeros(Float32, 3))
3-element Vector{Float32}:
 1.0
 2.0
 3.0

julia> fits_read_col(f, 3, 1, 1, zeros(Float64, 3))
3-element Vector{Float64}:
 1.0
 2.0
 3.0

julia> close(f);

fits_insert_rows(f::FITSFile, firstrow::Integer, nrows::Integer)

Insert a number of rows equal to nrows after the row number firstrow.

The elements in each row are initialized to their default value: you can modify them later using fits_write_col.

Since the first row is at position 1, in order to insert rows before the first one firstrow must be equal to zero.

Example

julia> fname = joinpath(mktempdir(), "test.fits");

julia> f = fits_create_file(fname);

julia> fits_create_binary_tbl(f, 0, [("col1", "1J", "units")])

julia> fits_write_col(f, 1, 1, 1, [1, 2, 3])

julia> fits_insert_rows(f, 0, 2)

julia> fits_write_col(f, 1, 1, 1, [4, 5])

julia> fits_read_col(f, 1, 1, 1, zeros(Int32, 5))
5-element Vector{Int32}:
 4
 5
 1
 2
 3

julia> close(f)

fits_delete_rows(f::FITSFile, firstrow::integer, nrows::Integer)

Delete nrows rows, starting from the one at position firstrow. The index of the first row is 1.

Example

julia> fname = joinpath(mktempdir(), "test.fits");

julia> f = fits_create_file(fname);

julia> fits_create_binary_tbl(f, 0, [("col1", "1J", "units")]);

julia> fits_write_col(f, 1, 1, 1, [1, 2, 3]);

julia> fits_delete_rows(f, 1, 2); # delete the first two rows

julia> fits_read_col(f, 1, 1, 1, zeros(Int32, 1))
1-element Vector{Int32}:
 3

julia> close(f);

fits_read_col(f::FITSFile, colnum::Integer, firstrow::Integer, firstelem::Integer, data::Array)

Read data from one column of an ASCII/binary table into data.

Arguments

• f::FITSFile: the file to be read.
• colnum::Integer: the column number, where the value of the first column is 1.
• firstrow::Integer: the elements to be read start from this row.
• firstelem::Integer: specifies which is the first element to be read, when each cell contains more than one element (i.e., the "repetition count" of the field is greater than one).
• data::Array: at the end of the call, this will be filled with the elements read

from the column. The length of the array gives the overall number of elements.

Example

julia> fname = joinpath(mktempdir(), "test.fits");

julia> f = fits_create_file(fname);

julia> fits_create_binary_tbl(f, 0, [("col1", "1J", "units")]);

julia> fits_write_col(f, 1, 1, 1, [1, 2, 3]);

julia> fits_read_col(f, 1, 1, 1, zeros(Int32, 3))
3-element Vector{Int32}:
 1
 2
 3

julia> close(f)

fits_read_atblhdr(f::FITSFile, maxdim::Integer = 99)

Read the header of an ASCII table HDU, where maxdim represents the maximum number of columns to read. The function returns the length of a row in bytes, the number of rows, the number of columns, the column names as a Vector{String}, the byte offsets to each column, the TFORMn values as a Vector{String}, the TUNITn values as a Vector{String}, and the EXTNAME::String keyword, if any.

Example

julia> fname = joinpath(mktempdir(), "test.fits");

julia> f = fits_create_file(fname);

julia> fits_create_ascii_tbl(f, 0, [("col1", "D10"), ("col2", "F10.2")])

julia> fits_read_atblhdr(f)
(21, 0, 2, ["col1", "col2"], [1, 12], ["D10", "F10.2"], ["", ""], "")

julia> close(f)

fits_read_btblhdr(f::FITSFile, maxdim::Integer = 99)

Read the header of a binary table HDU, where maxdim represents the maximum number of columns to read. The function returns the number of rows, the number of columns, the column names as a Vector{String}, the TFORMn values as a Vector{String}, the TUNITn values as a Vector{String}, and the EXTNAME::String and PCOUNT::Int keywords.

Example

julia> fname = joinpath(mktempdir(), "test.fits");

julia> f = fits_create_file(fname);

julia> fits_create_binary_tbl(f, 0, [("col1", "1J"), ("col2", "1E")])

julia> fits_read_btblhdr(f)
(0, 2, ["col1", "col2"], ["1J", "1E"], ["", ""], "", 0)

julia> close(f)

fits_read_descript(ff::FITSFile, colnum::Integer, rownum::Integer)

Return the descriptor for a variable length column in a binary table. The descriptor consists of 2 integer parameters: the number of elements in the array and the starting offset relative to the start of the heap.

Example

julia> fname = joinpath(mktempdir(), "test.fits");

julia> f = fits_create_file(fname);

julia> fits_create_binary_tbl(f, 0, [("col1", "1PJ", "units")]) # P = variable length column

julia> fits_write_col(f, 1, 1, 1, [1, 2, 3]) # write a vector to the column

julia> fits_read_descript(f, 1, 1) # read the descriptor for the first row and first column
(3, 0)

julia> fits_write_col(f, 1, 2, 1, [1, 2, 3, 4])

julia> fits_read_descript(f, 1, 2)
(4, 12)

julia> close(f)

fits_read_keys_lng(f::FITSFile, keyname::String, nstart::Integer, nmax::Integer)

Read a sequence of indexed keyword values (e.g., NAXIS1, NAXIS2, ...) as an Integer vector. Return the values of the keywords as a Vector{Clong}, as well as the number of values found.

Example

julia> fname = joinpath(mktempdir(), "test.fits");

julia> f = fits_create_file(fname);

julia> fits_create_img(f, Int32, (2, 3));

julia> fits_read_keys_lng(f, "NAXIS", 1, 2)
([2, 3], 2)

julia> close(f)

fits_read_tdim(ff::FITSFile, colnum::Integer)

Return the dimensions of a multidimensional array column in a binary table. The elements are stored contiguously in the column, and the dimensions of the array are normally provided by the TDIMn keyword. If this keyword is not present, then this routine returns [r] with r equals to the repeat count in the TFORM keyword. If the TDIMn keyword is present, it returns the dimensions as specified in that keyword. If the HDU is not a binary table, an error is thrown.

Example

julia> fname = joinpath(mktempdir(), "test.fits");

julia> f = fits_create_file(fname);

julia> fits_create_binary_tbl(f, 0, [("col1", "3E", "units")])

julia> fits_write_col(f, 1, 1, 1, [1.0 2.0 3.0])

julia> fits_read_tdim(f, 1)
1-element Vector{Int64}:
 3

julia> fits_write_tdim(f, 1, [1,3]) # specify the dimensions

julia> fits_read_key_str(f, "TDIM1")
("(1,3)", "size of the multidimensional array")

julia> fits_read_tdim(f, 1)
2-element Vector{Int64}:
 1
 3

julia> close(f)

See also fits_write_tdim for writing the dimensions of arrays stored in a column.

fits_write_col(f::FITSFile, colnum::Integer, firstrow::Integer, firstelem::Integer, data::Array)

Write some data in one column of a ASCII/binary table.

If there is no room for the elements, new rows will be created. (It is therefore useless to call fits_insert_rows if you only need to append elements to the end of a table.)

• f::FITSFile: the file in which data will be written.
• colnum::Integer: the column number, where the value of the first column is 1.
• firstrow::Integer: the data wil be written from this row onwards.
• firstelem::Integer: specifies the position in the row where the first element will be written.
• data::Array: contains the elements that are to be written to the column of the table.

Example

julia> fname = joinpath(mktempdir(), "test.fits");

julia> f = fits_create_file(fname);

julia> fits_create_binary_tbl(f, 0, [("col1", "1J", "units")]);

julia> fits_write_col(f, 1, 1, 1, [1, 2, 3]);

julia> fits_read_col(f, 1, 1, 1, zeros(Int32, 3))
3-element Vector{Int32}:
 1
 2
 3

julia> close(f)

fits_write_tdim(ff::FITSFile, colnum::Integer, naxes::Vector{Int64})

Write the dimensions of a multidimensional array column in a binary table. The data is stored contiguously in the column, and the dimensions are specified by the TDIMn keyword.

Example

julia> fname = joinpath(mktempdir(), "test.fits");

julia> f = fits_create_file(fname);

julia> fits_create_binary_tbl(f, 0, [("col1", "3E", "units")])

julia> fits_write_col(f, 1, 1, 1, [1.0 2.0 3.0])

julia> fits_write_tdim(f, 1, [3]) # interpret the data as a 1D array

julia> fits_read_key_str(f, "TDIM1")
("(3)", "size of the multidimensional array")

julia> fits_read_tdim(f, 1)
1-element Vector{Int64}:
 3

julia> fits_delete_key(f, "TDIM1") # remove the TDIM keyword

julia> fits_write_tdim(f, 1, [1,3]) # interpret the data as a 2D array

julia> fits_read_key_str(f, "TDIM1")
("(1,3)", "size of the multidimensional array")

julia> fits_read_tdim(f, 1)
2-element Vector{Int64}:
 1
 3

julia> close(f)

See also fits_read_tdim for reading the dimensions of arrays stored in a column.