matlab.io.fits.createTbl

Create new ASCII or binary table extension

Syntax

fptr = matlab.io.fits.createTbl(fptr,tbltype,nrows,ttype,tform,tunit,extname)

Description

fptr = matlab.io.fits.createTbl(fptr,tbltype,nrows,ttype,tform,tunit,extname) creates a new ASCII or binary table extension. Specify tbltype as either "binary" or "ascii". Specify nrows as the initial number of rows for the table (typically zero). Specify ttype as a string array or cell array of character vectors containing names for the columns of the table. Specify tunit as a string array or cell array of character vectors containing the units for each column, or an empty array if no units are desired. Optionally specify the extname argument as a string scalar or character vector containing the extension name.

The tform argument contains the format of the column, specified as a string array or cell array of character vectors. For binary tables, specify tform array elements in the form of "rt", where r is the repeat count and t is one of these letters.

Letter in Binary `tform` Array Element	Corresponding FITS Data Type
`A`	ASCII character
`B`	Byte or `uint8`
`C`	Complex (single precision)
`D`	Double precision
`E`	Single precision
`I`	`int16`
`J`	`int32`
`K`	`int64`
`L`	Logical
`M`	Complex (double precision)
`X`	Bit (`int8` zeros and ones)

You can also specify a column to have variable width by specifying elements of tform using the form "1Pt" or "1Qt", where t specifies the data type as shown in the previous table.

For ASCII tables, specify tform using one of these forms.

Form of `tform`	Corresponding FITS Data Type
`"Iw"`	`int16` column with width `w`
`"Aw"`	ASCII column with width `w`
`"Fww.dd"`	Fixed point with width `ww` and precision `dd`
`"Eww.dd"`	Single precision with width `ww` and precision `dd`
`"Dww.dd"`	Double precision with width `ww` and precision `dd`

Examples

collapse all

Create Table with Four Columns

Open Live Script

Create a new FITS file containing a binary table with columns matching these specifications:

Column 1: String of length 9
Column 2: Binary sequence of length 4
Column 3: Three-element sequence of uint8 values
Column 4: Double-precision scalar

import matlab.io.*
fptr = fits.createFile("myfile.fits");
ttype = ["Col1","Col2","Col3","Col4"];
tform = ["9A","4X","3B","1D"];
tunit = ["m/s","kg","kg/m^3","candela"];
ftpr = fits.createTbl(fptr,"binary",10,ttype,tform,tunit,"my-table");
fits.closeFile(fptr)

Examine the file metadata and then delete the file.

fitsdisp("myfile.fits")

HDU:  1 (Primary HDU)
	SIMPLE  =                    T / file does conform to FITS standard
	BITPIX  =                   16 / number of bits per data pixel
	NAXIS   =                    0 / number of data axes
	EXTEND  =                    T / FITS dataset may contain extensions
	COMMENT   FITS (Flexible Image Transport System) format is defined in 'Astronomy
	COMMENT   and Astrophysics', volume 376, page 359; bibcode: 2001A&A...376..359H

HDU:  2 
	XTENSION= 'BINTABLE'           / binary table extension
	BITPIX  =                    8 / 8-bit bytes
	NAXIS   =                    2 / 2-dimensional binary table
	NAXIS1  =                   21 / width of table in bytes
	NAXIS2  =                   10 / number of rows in table
	PCOUNT  =                    0 / size of special data area
	GCOUNT  =                    1 / one data group (required keyword)
	TFIELDS =                    4 / number of fields in each row
	TTYPE1  = 'Col1    '           / label for field   1
	TFORM1  = '9A      '           / data format of field: ASCII Character
	TUNIT1  = 'm/s     '           / physical unit of field
	TTYPE2  = 'Col2    '           / label for field   2
	TFORM2  = '4X      '           / data format of field: BIT
	TUNIT2  = 'kg      '           / physical unit of field
	TTYPE3  = 'Col3    '           / label for field   3
	TFORM3  = '3B      '           / data format of field: BYTE
	TUNIT3  = 'kg/m^3  '           / physical unit of field
	TTYPE4  = 'Col4    '           / label for field   4
	TFORM4  = '1D      '           / data format of field: 8-byte DOUBLE
	TUNIT4  = 'candela '           / physical unit of field
	EXTNAME = 'my-table'           / name of this binary table extension

delete myfile.fits

Create Table with Variable-Width Column

Open Live Script

Create a new FITS file containing a binary table with columns matching these specifications:

Column 1: Double-precision scalar
Column 2: Variable-length sequence of double-precision values

import matlab.io.*
fptr = fits.createFile("myfile2.fits");
ttype = ["Col1","Col2"];
tform = ["1D","1PD"];
fptr = fits.createTbl(fptr,"binary",0,ttype,tform);
fits.closeFile(fptr)

Examine the file metadata and then delete the file.

fitsdisp("myfile2.fits")

HDU:  1 (Primary HDU)
	SIMPLE  =                    T / file does conform to FITS standard
	BITPIX  =                   16 / number of bits per data pixel
	NAXIS   =                    0 / number of data axes
	EXTEND  =                    T / FITS dataset may contain extensions
	COMMENT   FITS (Flexible Image Transport System) format is defined in 'Astronomy
	COMMENT   and Astrophysics', volume 376, page 359; bibcode: 2001A&A...376..359H

HDU:  2 
	XTENSION= 'BINTABLE'           / binary table extension
	BITPIX  =                    8 / 8-bit bytes
	NAXIS   =                    2 / 2-dimensional binary table
	NAXIS1  =                   16 / width of table in bytes
	NAXIS2  =                    0 / number of rows in table
	PCOUNT  =                    0 / size of special data area
	GCOUNT  =                    1 / one data group (required keyword)
	TFIELDS =                    2 / number of fields in each row
	TTYPE1  = 'Col1    '           / label for field   1
	TFORM1  = '1D      '           / data format of field: 8-byte DOUBLE
	TTYPE2  = 'Col2    '           / label for field   2
	TFORM2  = '1PD     '           / data format of field: variable length array

delete myfile2.fits

Tips

This function corresponds to the fits_create_tbl (ffcrtb) function in the CFITSIO library C API.
To use this function, you must be familiar with the CFITSIO C interface. You can access the CFITSIO documentation at the CFITSIO website.

Extended Capabilities

expand all

Thread-Based Environment
Run code in the background using MATLAB® `backgroundPool` or accelerate code with Parallel Computing Toolbox™ `ThreadPool`. (since R2026a)

The matlab.io.fits.createTbl function fully supports thread-based environments. For more information, see Run MATLAB Functions in Thread-Based Environment.

Version History