This page was created by the IDL library routine
mk_html_help2.
Last modified: Wed Dec 20 10:37:44 2023.
NAME:
FTAB_DELROW
PURPOSE:
Delete rows of data from a FITS ASCII or binary table extension
CALLING SEQUENCE:
ftab_delrow, filename, rows, EXTEN_NO =, NEWFILE = ]
INPUTS-OUPUTS
filename - scalar string giving name of the FITS file containing an
ASCII or binary table extension.
rows - scalar or vector, specifying the row numbers to delete
First row has index 0. If a vector, it will be sorted and
duplicates will be removed
OPTIONAL KEYWORD INPUTS:
EXTEN_NO - scalar integer specifying which extension number to process
Default is to process the first extension
NEWFILE - scalar string specifying the name of the new output FITS file
FTAB_DELROW will prompt for this parameter if not supplied
EXAMPLE:
Compress the first extension of a FITS file 'test.fits' to include
only non-negative values in the 'FLUX' column
ftab_ext,'test.fits','flux',flux ;Obtain original flux vector
bad = where(flux lt 0) ;Find negative fluxes
ftab_delrow,'test.fits',bad,new='test1.fits' ;Delete specified rows
RESTRICTIONS:
Does not work for variable length binary tables
PROCEDURES USED:
FITS_CLOSE, FITS_OPEN, FITS_READ, FITS_WRITE, FTDELROW, TBDELROW
REVISION HISTORY:
Written W. Landsman STX Co. August, 1997
Converted to IDL V5.0 W. Landsman September 1997
Use COPY_LUN if V5.6 or later W. Landsman February 2003
Assume since V5.6, COPY_LUN available W. Landsman Sep 2006
(See external/astron/fits_table/ftab_delrow.pro)
NAME:
FTAB_EXT
PURPOSE:
Routine to extract columns from a FITS (binary or ASCII) table.
CALLING SEQUENCE:
FTAB_EXT, name_or_fcb, columns, v1, [v2,..,v50, ROWS=, EXTEN_NO= ]
INPUTS:
name_or_fcb - either a scalar string giving the name of a FITS file
containing a (binary or ASCII) table, or an IDL structure
containing as file control block (FCB) returned by FITS_OPEN
If FTAB_EXT is to be called repeatedly on the same file, then
it is quicker to first open the file with FITS_OPEN, and then
pass the FCB structure to FTAB_EXT
columns - table columns to extract. Can be either
(1) String with names separated by commas
(2) Scalar or vector of column numbers
OUTPUTS:
v1,...,v50 - values for the columns. Up to 50 columns can be extracted
OPTIONAL INPUT KEYWORDS:
ROWS - scalar or vector giving row number(s) to extract
Row numbers start at 0. If not supplied or set to
-1 then values for all rows are returned. This keyword
works for ASCII tables and binary tables where every column has
the same number of elements, but not for variable length
binary tables.
EXTEN_NO - Extension number to process. If not set, then data is
extracted from the first extension in the file (EXTEN_NO=1)
EXAMPLES:
Read wavelength and flux vectors from the first extension of a
FITS file, 'spec.fit'. Using FTAB_HELP,'spec.fit' we find that this
information is in columns named 'WAVELENGTH' and 'FLUX' (in columns 1
and 2). To read the data
IDL> ftab_ext,'spec.fit','wavelength,flux',w,f
or
IDL> ftab_ext,'spec.fit',[1,2],w,f
PROCEDURES CALLED:
FITS_READ, FITS_CLOSE, FTINFO, FTGET(), TBINFO, TBGET()
HISTORY:
version 1 W. Landsman August 1997
Improve speed processing binary tables W. Landsman March 2000
Use new FTINFO calling sequence W. Landsman May 2000
Don't call fits_close if fcb supplied W. Landsman May 2001
Use STRSPLIT to parse column string W. Landsman July 2002
Cleanup pointers in TBINFO structure W. Landsman November 2003
Avoid EXECUTE() if V6.1 or later W. Landsamn December 2006
Assume since V6.1 W. Landsman June 2009
Read up to 30 columns W.L. Aug 2009
Setting ROWS = -1 should work as documented, accept up to 50
columns W.L. Oct 2013
(See external/astron/fits_table/ftab_ext.pro)
NAME:
FTAB_HELP
PURPOSE:
Describe the columns of a FITS binary or ASCII table extension(s).
CALLING SEQUENCE:
FTAB_HELP, filename, [ EXTEN_No = , TEXTOUT= ]
or
FTAB_HELP, fcb, [EXTEN_No=, TEXTOUT= ]
INPUTS:
filename - scalar string giving name of the FITS file.
fcb - FITS control block returned by a previous call to FITS_OPEN
OPTIONAL KEYWORD INPUTS:
EXTEN_NO - integer scalar or vector specifying which FITS extensions
to display. Default is to display all FITS extension.
TEXTOUT - scalar number (0-7) or string (file name) determining
output device (see TEXTOPEN). Default is TEXTOUT=1, output
to the user's terminal
EXAMPLE:
Describe the columns in the second and fourth extensions of a FITS
file spec.fits and write the results to a file 'spec24.lis'
IDL> ftab_help,'spec.fits',exten=[2,4],t='spec24.lis'
SYSTEM VARIABLES:
Uses the non-standard system variables !TEXTOUT and !TEXTUNIT
which must be defined (e.g. with ASTROLIB) before compilation
NOTES:
The behavior of FTAB_HELP was changed in August 2005 to display
all extensions by default, rather than just the first extension
PROCEDURES USED:
FITS_READ, FITS_CLOSE, FITS_OPEN, FTHELP, TBHELP, TEXTOPEN, TEXTCLOSE
HISTORY:
version 1 W. Landsman August 1997
Corrected documentation W. Landsman September 1997
Don't call fits_close if fcb supplied W. Landsman May 2001
Default now is to display all extensions, EXTEN keyword can now
be a vector W. Landsman Aug 2005
(See external/astron/fits_table/ftab_help.pro)
NAME:
FTAB_PRINT
PURPOSE:
Print the contents of a FITS (binary or ASCII) table extension.
EXPLANATION:
User can specify which rows or columns to print
CALLING SEQUENCE:
FTAB_PRINT, filename, columns, rows,
[ TEXTOUT=, FMT=, EXTEN_NO= NUM_HEADER_LINES ]
INPUTS:
filename - scalar string giving name of a FITS file containing a
binary or ASCII table
columns - string giving column names, or vector giving
column numbers (beginning with 1). If a string
supplied then column names should be separated by comma's.
if not supplied, then all columns are printed.
If set to '*' then all columns are printed in table format
(1 row per line, binary tables only).
rows - (optional) vector of row numbers to print (beginning with 0).
If not supplied or set to scalar, -1, then all rows
are printed.
OPTIONAL KEYWORD INPUT:
EXTEN_NO - Extension number to read. If not set, then the first
extension is printed (EXTEN_NO=1)
FMT = Format string for print display (binary tables only). If not
supplied, then any formats in the TDISP keyword fields will be
used, otherwise IDL default formats. For ASCII tables, the
format used is always as stored in the FITS table.
NUM_HEADER_LINES - Number of lines to display the column headers (default
= 1). By setting NUM_HEADER_LINES to an integer larger than 1,
one can avoid truncation of the headers. In addition, setting
NUM_HEADER_LINES will display commented lines indicating
a FORMAT for reading the data, and a suggested call to
readfmt.pro. Works for binary tables only
NVAL_PER_LINE - The maximum number of values displayed from a
multivalued column when printing in table format. Default = 6
TEXTOUT - scalar number (0-7) or string (file name) determining
output device (see TEXTOPEN). Default is TEXTOUT=1, output
to the user's terminal
EXAMPLE:
(1) Print all rows of the first 5 columns of the first extension of the
file 'wfpc.fits'
IDL> ftab_print,'vizier.fits',indgen(5)+1
(2) Print all columns of the first row to a file 'vizier.dat' in
'table' format
IDL> ftab_print,'vizier.fits',t='vizier.dat','*',0
SYSTEM VARIABLES:
Uses the non-standard system variables !TEXTOUT and !TEXTUNIT
which must be defined (e.g. with ASTROLIB) prior to compilation.
PROCEDURES USED:
FITS_CLOSE, FITS_OPEN, FITS_READ, FTPRINT, TBPRINT
HISTORY:
version 1 W. Landsman August 1997
Check whether data exists W. Landsman Feb 2007
Check whether extension exists W. Landsman Mar 2010
Added NUM_HEADER_LINES, NVAL_PER_LINE keywords for binary tables
W. Landsman Apr 2010
(See external/astron/fits_table/ftab_print.pro)
NAME:
FTADDCOL
PURPOSE:
Routine to add a field to a FITS ASCII table
CALLING SEQUENCE:
ftaddcol, h, tab, name, idltype, [ tform, tunit, tscal, tzero, tnull ]
INPUTS:
h - FITS table header. It will be updated as appropriate
tab - FITS table array. Number of columns will be increased if
neccessary.
name - field name, scalar string
idltype - idl data type (as returned by SIZE function) for field,
For string data (type=7) use minus the string length.
OPTIONAL INPUTS:
tform - format specification 'qww.dd' where q = A, I, E, or D
tunit - string giving physical units for the column.
tscal - scale factor
tzero - zero point for field
tnull - null value for field
Use '' as the value of tform,tunit,tscal,tzero,tnull if you want
the default or no specification of them in the table header.
OUTPUTS:
h,tab - updated to allow new column of data
PROCEDURES USED:
FTINFO, FTSIZE, GETTOK(), SXADDPAR
HISTORY:
version 1 D. Lindler July, 1987
Converted to IDL V5.0 W. Landsman September 1997
Updated call to new FTINFO W. Landsman April 2000
(See external/astron/fits_table/ftaddcol.pro)
NAME:
FTCREATE
PURPOSE:
Create a new (blank) FITS ASCII table and header with specified size.
CALLING SEQUENCE:
ftcreate, maxcols, maxrows, h, tab
INPUTS:
maxcols - number of character columns allocated, integer scalar
maxrows - maximum number of rows allocated, integer scalar
OUTPUTS:
h - minimal FITS Table extension header, string array
OPTIONAL OUTPUT:
tab - empty table, byte array
HISTORY:
version 1 D. Lindler July. 87
Converted to IDL V5.0 W. Landsman September 1997
Make table creation optional, allow 1 row table, add comments to
required FITS keywords W. Landsman October 2001
(See external/astron/fits_table/ftcreate.pro)
NAME:
FTDELCOL
PURPOSE:
Delete a column of data from a FITS table
CALLING SEQUENCE:
ftdelcol, h, tab, name
INPUTS-OUPUTS
h,tab - FITS table header and data array. H and TAB will
be updated with the specified column deleted
INPUTS:
name - Either (1) a string giving the name of the column to delete
or (2) a scalar giving the column number to delete (starting with 1)
Only 1 column can be deleted at a time
EXAMPLE:
Suppose it has been determined that the F7.2 format used for a field
FLUX in a FITS table is insufficient. The old column must first be
deleted before a new column can be written with a new format.
flux = FTGET(h,tab,'FLUX') ;Save the existing values
FTDELCOL,h,tab,'FLUX' ;Delete the existing column
FTADDCOL,h,tab,'FLUX',8,'F9.2' ;Create a new column with larger format
FTPUT,h,tab,'FLUX',0,flux ;Put back the original values
REVISION HISTORY:
Written W. Landsman STX Co. August, 1988
Adapted for IDL Version 2, J. Isensee, July, 1990
Updated call to new FTINFO W. Landsman May 2000
Allow specification of column number in addition to field name
M. Nolan/W. Landsman Sep 2015
(See external/astron/fits_table/ftdelcol.pro)
NAME:
FTDELROW
PURPOSE:
Delete a row of data from a FITS table
CALLING SEQUENCE:
ftdelrow, h, tab, rows
INPUTS-OUPUTS
h,tab - FITS table header and data array. H and TAB will
be updated on output with the specified row(s) deleted.
rows - scalar or vector, specifying the row numbers to delete
This vector will be sorted and duplicates removed by FTDELROW
EXAMPLE:
Compress a table to include only non-negative flux values
flux = FTGET(h,tab,'FLUX') ;Obtain original flux vector
bad = where(flux lt 0) ;Find negative fluxes
FTDELROW,h,tab,bad ;Delete rows with negative fluxes
PROCEDURE:
Specified rows are deleted from the data array, TAB. The NAXIS2
keyword in the header is updated.
PROCEDURES USED:
sxaddpar
REVISION HISTORY:
Written W. Landsman STX Co. August, 1988
Checked for IDL Version 2, J. Isensee, July, 1990
Converted to IDL V5.0 W. Landsman September 1997
Assume since V5.4, use BREAK instead of GOTO W. Landsman April 2006
(See external/astron/fits_table/ftdelrow.pro)
NAME:
FTGET
PURPOSE:
Function to return value(s) from specified column in a FITS ASCII table
CALLING SEQUENCE
values = FTGET( h, tab, field, [ rows, nulls ] )
or
values = FTGET( ft_str, tab, field. [rows, nulls]
INPUTS:
h - FITS ASCII extension header (e.g. as returned by FITS_READ)
or
ft_str - FITS table structure extracted from FITS header by FTINFO
Use of the IDL structure will improve processing speed
tab - FITS ASCII table array (e.g. as returned by FITS_READ)
field - field name or number
OPTIONAL INPUTS:
rows - scalar or vector giving row number(s)
Row numbers start at 0. If not supplied or set to
-1 then values for all rows are returned
OUTPUTS:
the values for the row are returned as the function value.
Null values are set to 0 or blanks for strings.
OPTIONAL OUTPUT:
nulls - null value flag of same length as the returned data.
It is set to 1 at null value positions and 0 elsewhere.
If supplied then the optional input, rows, must also
be supplied.
EXAMPLE:
Read the columns labeled 'WAVELENGTH' and 'FLUX' from the second
(ASCII table) extension of a FITS file 'spectra.fit'
IDL> fits_read,'spectra.fit',tab,htab,exten=2 ;Read 2nd extension
IDL> w = ftget( htab, tab,'wavelength') ;Wavelength vector
IDL> f = ftget( htab, tab,'flux') ;Flux vector
Slightly more efficient would be to first call FTINFO
IDL> ftinfo, htab, ft_str ;Extract structure
IDL> w = ftget(ft_str, tab,'wavelength') ;Wavelength vector
IDL> f = ftget(ft_str, tab,'flux') ;Flux vector
NOTES:
(1) Use the higher-level procedure FTAB_EXT to extract vectors
directly from the FITS file.
(2) Use FTAB_HELP or FTHELP to determine the columns in a particular
ASCII table.
HISTORY:
coded by D. Lindler July, 1987
Always check for null values W. Landsman August 1990
More informative error message W. Landsman Feb. 1996
Converted to IDL V5.0 W. Landsman September 1997
Allow structure rather than FITS header W. Landsman May 2000
No case sensitivity in TTYPE name W. Landsman February 2002
(See external/astron/fits_table/ftget.pro)
NAME:
FTHELP
PURPOSE:
Routine to print a description of a FITS ASCII table extension
CALLING SEQUENCE:
FTHELP, H, [ TEXTOUT = ]
INPUTS:
H - FITS header for ASCII table extension, string array
OPTIONAL INPUT KEYWORD
TEXTOUT - scalar number (0-7) or string (file name) determining
output device (see TEXTOPEN). Default is TEXTOUT=1, output
to the user's terminal
NOTES:
FTHELP checks that the keyword XTENSION equals 'TABLE' in the FITS
header.
SYSTEM VARIABLES:
Uses the non-standard system variables !TEXTOUT and !TEXTUNIT
which must be defined (e.g. with ASTROLIB) prior to compilation.
PROCEDURES USED:
REMCHAR, SXPAR(), TEXTOPEN, TEXTCLOSE, ZPARCHECK
HISTORY:
version 1 W. Landsman Jan. 1988
Add TEXTOUT option, cleaner format W. Landsman September 1991
TTYPE value can be longer than 8 chars, W. Landsman August 1995
Remove calls to !ERR, some vectorization W. Landsman February 2000
Slightly more compact display W. Landsman August 2005
(See external/astron/fits_table/fthelp.pro)
NAME:
FTHMOD
PURPOSE:
Procedure to modify header information for a specified field
in a FITS table.
CALLING SEQUENCE:
fthmod, h, field, parameter, value
INPUT:
h - FITS header for the table
field - field name or number
parameter - string name of the parameter to modify. Choices
include:
TTYPE - field name
TUNIT - physical units for field (eg. 'ANGSTROMS')
TNULL - null value (string) for field, (eg. '***')
TFORM - format specification for the field
TSCAL - scale factor
TZERO - zero offset
User should be aware that the validity of the change is
not checked. Unless you really know what you are doing,
this routine should only be used to change field names,
units, or another user specified parameter.
value - new value for the parameter. Refer to the FITS table
standards documentation for valid values.
EXAMPLE:
Change the units for a field name "FLUX" to "Janskys" in a FITS table
header,h
IDL> FTHMOD, h, 'FLUX', 'TUNIT','Janskys'
METHOD:
The header keyword <parameter><field number> is modified
with the new value.
HISTORY:
version 1, D. Lindler July 1987
Converted to IDL V5.0 W. Landsman September 1997
Major rewrite to use new FTINFO call W. Landsman May 2000
(See external/astron/fits_table/fthmod.pro)
NAME:
FTINFO
PURPOSE:
Return an informational structure from a FITS ASCII table header.
CALLING SEQUENCE:
ftinfo,h,ft_str, [Count = ]
INPUTS:
h - FITS ASCII table header, string array
OUTPUTS:
ft_str - IDL structure with extracted info from the FITS ASCII table
header. Tags include
.tbcol - starting column position in bytes
.width - width of the field in bytes
.idltype - idltype of field.
7 - string, 4- real*4, 3-integer, 5-real*8
.tunit - string unit numbers
.tscal - scale factor
.tzero - zero point for field
.tnull - null value for the field
.tform - format for the field
.ttype - field name
OPTIONAL OUTPUT KEYWORD:
Count - Integer scalar giving number of fields in the table
PROCEDURES USED:
GETTOK(), SXPAR()
NOTES:
This procedure underwent a major revision in May 2000, and **THE
NEW CALLING SEQUENCE IS INCOMPATIBLE WITH THE OLD ONE **
HISTORY:
D. Lindler July, 1987
Converted to IDL V5.0 W. Landsman September 1997
Major rewrite, return structure W. Landsman April 2000
(See external/astron/fits_table/ftinfo.pro)
NAME: FTKEEPROW PURPOSE: Subscripts (and reorders) a FITS table. A companion piece to FTDELROW. CALLING SEQUENCE: ftkeeprow, h, tab, subs INPUT PARAMETERS: h = FITS table header array tab = FITS table data array subs = subscript array of FITS table rows. Works like any other IDL subscript array (0 based, of course). OUTPUT PARAMETERS: h and tab are modified MODIFICATION HISTORY: Written by R. S. Hill, ST Sys. Corp., 2 May 1991. Converted to IDL V5.0 W. Landsman September 1997
(See external/astron/fits_table/ftkeeprow.pro)
NAME:
FTPRINT
PURPOSE:
Procedure to print specified columns and rows of a FITS table
CALLING SEQUENCE:
FTPRINT, h, tab, columns, [ rows, TEXTOUT = ]
INPUTS:
h - Fits header for table, string array
tab - table array
columns - string giving column names, or vector giving
column numbers (beginning with 1). If string
supplied then column names should be separated by comma's.
rows - (optional) vector of row numbers to print. If
not supplied or set to scalar, -1, then all rows
are printed.
OUTPUTS:
None
OPTIONAL INPUT KEYWORDS:
TEXTOUT controls the output device; see the procedure TEXTOPEN
SYSTEM VARIABLES:
Uses nonstandard system variables !TEXTOUT and !TEXTOPEN
These will be defined (using ASTROLIB) if not already present.
Set !TEXTOUT = 3 to direct output to a disk file. The system
variable is overriden by the value of the keyword TEXTOUT
EXAMPLES:
ftprint,h,tab,'STAR ID,RA,DEC' ;print id,ra,dec for all stars
ftprint,h,tab,[2,3,4],indgen(100) ;print columns 2-4 for
;first 100 stars
ftprint,h,tab,text="stars.dat" ;Convert entire FITS table to
;an ASCII file named STARS.DAT
PROCEDURES USED:
FTSIZE, FTINFO, TEXTOPEN, TEXTCLOSE
RESTRICTIONS:
(1) Program does not check whether output length exceeds output
device capacity (e.g. 80 or 132).
(2) Column heading may be truncated to fit in space defined by
the FORMAT specified for the column
(3) Program does not check for null values
HISTORY:
version 1 D. Lindler Feb. 1987
Accept undefined values of rows, columns W. Landsman August 1997
New FTINFO calling sequence W. Landsman May 2000
Parse scalar string with STRSPLIT W. Landsman July 2002
Fix format display of row number W. Landsman March 2003
Fix format display of row number again W. Landsman May 2003
(See external/astron/fits_table/ftprint.pro)
NAME:
FTPUT
PURPOSE:
Procedure to add or update a field in an FITS ASCII table
CALLING SEQUENCE:
FTPUT, htab, tab, field, row, values, [ nulls ]
INPUTS:
htab - FITS ASCII table header string array
tab - FITS ASCII table array (e.g. as read by READFITS)
field - string field name or integer field number
row - either a non-negative integer scalar giving starting row to
update, or a non-negative integer vector specifying rows to
update. FTPUT will append a new row to a table if the value
of 'row' exceeds the number of rows in the tab array
values - value(s) to add or update. If row is a vector
then values must contain the same number of elements.
OPTIONAL INPUT:
nulls - null value flag of same length as values.
It should be set to 1 at null value positions
and 0 elsewhere.
OUTPUTS:
htab,tab will be updated as specified.
EXAMPLE:
One has a NAME and RA and Dec vectors for 500 stars with formats A6,
F9.5 and F9.5 respectively. Write this information to an ASCII table
named 'star.fits'.
IDL> FTCREATE,24,500,h,tab ;Create table header and (empty) data
IDL> FTADDCOL,h,tab,'RA',8,'F9.5','DEGREES' ;Explicity define the
IDL> FTADDCOL,h,tab,'DEC',8,'F9.5','DEGREES' ;RA and Dec columns
IDL> FTPUT,h,tab,'RA',0,ra ;Insert RA vector into table
IDL> FTPUT,h,tab,'DEC',0,dec ;Insert DEC vector into table
IDL> FTPUT, h,tab, 'NAME',0,name ;Insert NAME vector with default
IDL> WRITEFITS,'stars.fits',tab,h ;Write to a file
Note that (1) explicit formatting has been supplied for the (numeric)
RA and Dec vectors, but was not needed for the NAME vector, (2) A width
of 24 was supplied in FTCREATE based on the expected formats (6+9+9),
though the FT* will adjust this value as necessary, and (3) WRITEFITS
will create a minimal primary header
NOTES:
(1) If the specified field is not already in the table, then FTPUT will
create a new column for that field using default formatting. However,
FTADDCOL should be called prior to FTPUT for explicit formatting.
PROCEDURES CALLED
FTADDCOL, FTINFO, FTSIZE, SXADDPAR, SXPAR()
HISTORY:
version 1 D. Lindler July, 1987
Allow E format W. Landsman March 1992
Write in F format if E format will overflow April 1994
Update documentation W. Landsman January 1996
Allow 1 element vector W. Landsman March 1996
Adjust string length to maximum of input string array June 1997
Work for more than 32767 elements August 1997
Converted to IDL V5.0 W. Landsman September 1997
Updated call to the new FTINFO W. Landsman May 2000
Fix case where header does not have any columns yet W.Landsman Sep 2002
Assume since V5.2, omit fstring() call W. Landsman April 2006
(See external/astron/fits_table/ftput.pro)
NAME:
FTSIZE
PURPOSE:
Procedure to return the size of a FITS ASCII table.
CALLING SEQUENCE:
ftsize,h,tab,ncols,rows,tfields,ncols_all,nrows_all, [ERRMSG = ]
INPUTS:
h - FITS ASCII table header, string array
tab - FITS table array, 2-d byte array
OUTPUTS:
ncols - number of characters per row in table
nrows - number of rows in table
tfields - number of fields per row
ncols_all - number of characters/row allocated (size of tab)
nrows_all - number of rows allocated
OPTIONAL OUTPUT KEYWORD:
ERRMSG = If this keyword is present, then any error messages will be
returned to the user in this parameter rather than
depending on the MESSAGE routine in IDL. If no errors are
encountered, then a null string is returned.
HISTORY
D. Lindler July, 1987
Fix for 1-row table, W. Landsman HSTX, June 1994
Converted to IDL V5.0 W. Landsman September 1997
Added ERRMSG keyword W. Landsman May 2000
(See external/astron/fits_table/ftsize.pro)
NAME:
FTSORT
PURPOSE:
Sort a FITS ASCII table according to a specified field
CALLING SEQUENCE:
FTSORT,h,tab,[field, REVERSE = ] ;Sort original table header and array
or
FTSORT,h,tab,hnew,tabnew,[field, REVERSE =] ;Create new sorted header
INPUTS:
H - FITS header (string array)
TAB - FITS table (byte array) associated with H. If less than 4
parameters are supplied, then H and TAB will be updated to
contain the sorted table
OPTIONAL INPUTS:
FIELD - Field name(s) or number(s) used to sort the entire table.
If FIELD is a vector then the first element is used for the
primary sort, the second element is used for the secondary
sort, and so forth. (A secondary sort only takes effect when
values in the primary sort field are equal.) Character fields
are sorted using the ASCII collating sequence. If omitted,
the user will be prompted for the field name.
OPTIONAL OUTPUTS:
HNEW,TABNEW - Header and table containing the sorted tables
EXAMPLE:
Sort a FITS ASCII table by the 'DECLINATION' field in descending order
Assume that the table header htab, and array, tab, have already been
read (e.g. with READFITS or FITS_READ):
IDL> FTSORT, htab, tab,'DECLINATION',/REVERSE
OPTIONAL INPUT KEYWORD:
REVERSE - If set then the table is sorted in reverse order (maximum
to minimum. If FIELD is a vector, then REVERSE can also be
a vector. For example, REVERSE = [1,0] indicates that the
primary sort should be in descending order, and the secondary
sort should be in ascending order.
EXAMPLE:
SIDE EFFECTS:
A HISTORY record is added to the table header.
REVISION HISTORY:
Written W. Landsman June, 1988
Converted to IDL V5.0 W. Landsman September 1997
New FTINFO calling sequence, added REVERSE keyword, allow secondary sorts
W. Landsman May 2000
(See external/astron/fits_table/ftsort.pro)
NAME:
TBDELCOL
PURPOSE:
Delete a column of data from a FITS binary table
CALLING SEQUENCE:
TBDELCOL, h, tab, name
INPUTS-OUPUTS
h,tab - FITS binary table header and data array. H and TAB will
be updated with the specified column deleted
INPUTS:
name - Either (1) a string giving the name of the column to delete
or (2) a scalar giving the column number to delete
EXAMPLE:
Delete the column "FLUX" from FITS binary table test.fits
IDL> tab = readfits('test.fits',h,/ext) ;Read table
IDL> tbdelcol, h, tab, 'FLUX' ;Delete Flux column
IDL> modfits,'test.fits',tab,h,/ext ;Write back table
PROCEDURES USED:
SXADDPAR, TBINFO, TBSIZE
REVISION HISTORY:
Written W. Landsman STX Co. August, 1988
Use new structure returned by TBINFO, August, 1997
Use SIZE(/TNAME) instead of DATATYPE() October 2001
Use /NOSCALE in call to TBINFO, update TDISP W. Landsman March 2007
(See external/astron/fits_table/tbdelcol.pro)
NAME: TBDELROW PURPOSE: Delete specified row or rows of data from a FITS binary table CALLING SEQUENCE: TBDELROW, h, tab, rows INPUTS-OUPUTS h,tab - FITS binary table header and data array. H and TAB will be updated on output with the specified row(s) deleted. rows - scalar or vector, specifying the row numbers to delete First row has index 0. If a vector it will be sorted and duplicates removed by TBDELROW EXAMPLE: Compress a table to include only non-negative flux values flux = TBGET(h,tab,'FLUX') ;Obtain original flux vector bad = where(flux lt 0) ;Find negative fluxes TBDELROW,h,tab,bad ;Delete rows with negative fluxes PROCEDURE: Specified rows are deleted from the data array, TAB. The NAXIS2 keyword in the header is updated. REVISION HISTORY: Written W. Landsman STX Co. August, 1988 Checked for IDL Version 2, J. Isensee, July, 1990 Converted to IDL V5.0 W. Landsman September 1997
(See external/astron/fits_table/tbdelrow.pro)
NAME:
TBGET
PURPOSE:
Return value(s) from specified column in a FITS binary table
CALLING SEQUENCE
values = TBGET( h, tab, field, [ rows, nulls, /NOSCALE] )
or
values = TBGET( tb_str, tab, field, [ rows, nulls, /NOSCALE] )
INPUTS:
h - FITS binary table header, e.g. as returned by FITS_READ
or
tb_str - IDL structure extracted from FITS header by TBINFO.
Use of the IDL structure will improve processing speed
tab - FITS binary table array, e.g. as returned by FITS_READ
field - field name or number, scalar
OPTIONAL INPUTS:
rows - scalar or vector giving row number(s)
Row numbers start at 0. If not supplied or set to
-1 then values for all rows are returned
OPTIONAL KEYWORD INPUT:
/NOSCALE - If this keyword is set and nonzero, then the TSCALn and
TZEROn keywords will *not* be used to scale to physical values
Default is to perform scaling
OUTPUTS:
the values for the row are returned as the function value.
Null values are set to 0 or blanks for strings.
OPTIONAL OUTPUT:
nulls - null value flag of same length as the returned data.
Only used for integer data types, B, I, and J
It is set to 1 at null value positions and 0 elsewhere.
If supplied then the optional input, rows, must also
be supplied.
EXAMPLE:
Read the columns labeled 'WAVELENGTH' and 'FLUX' from the second
extension of a FITS file 'spectra.fits' into IDL vectors w and f
IDL> fits_read,'spectra.fits',tab,htab,exten=2 ;Read 2nd extension
IDL> w = tbget(htab,tab,'wavelength')
IDL> f = tbget(htab,tab,'flux')
NOTES:
(1) If the column is variable length ('P') format, then TBGET() will
return the longword array of pointers into the heap area. TBGET()
currently lacks the ability to actually extract the data from the
heap area.
(2) Use the higher-level procedure FTAB_EXT (which calls TBGET()) to
extract vectors directly from the FITS file.
(3) Use the procedure FITS_HELP to determine which extensions are
binary tables, and FTAB_HELP or TBHELP to determine the columns of the
table
PROCEDURE CALLS:
TBINFO, TBSIZE
HISTORY:
Written W. Landsman February, 1991
Work for string and complex W. Landsman April, 1993
Default scaling by TSCALn, TZEROn, Added /NOSCALE keyword,
Fixed nulls output, return longword pointers for variable length
binary tables, W. Landsman December 1996
Added a check for zero width column W. Landsman April, 1997
Add TEMPORARY() and REFORM() for speed W. Landsman May, 1997
Use new structure returned by TBINFO W. Landsman August 1997
Add IS_IEEE_BIG(), No subscripting when all rows requested
W. Landsman March 2000
Use SIZE(/TNAME) instead of DATATYPE() W. Landsman October 2001
Bypass IEEE_TO_HOST call for improved speed W. Landsman November 2002
Cosmetic changes to SIZE() calls W. Landsman December 2002
Added unofficial support for 64bit integers W. Landsman February 2003
Support unsigned integers, new pointer types of TSCAL and TZERO
returned by TBINFO W. Landsman April 2003
Add an i = i[0] for V6.0 compatibility W. Landsman August 2003
Use faster BYTEORDER byteswapping W. Landsman April 2006
Free pointers if FITS header supplied W. Landsman March 2007
Use V6.0 notation W. Landsman April 2014
Remove nonfunctional CONTINUE keyword W. Landsman May 2017
(See external/astron/fits_table/tbget.pro)
NAME:
TBHELP
PURPOSE:
Routine to print a description of a FITS binary table header
CALLING SEQUENCE:
TBHELP, h, [TEXTOUT = ]
INPUTS:
h - FITS header for a binary table, string array
OPTIONAL INPUT KEYWORD:
TEXTOUT - scalar number (0-7) or string (file name) controling
output device (see TEXTOPEN). Default is TEXTOUT=1, output
to the user's terminal
METHOD:
FITS Binary Table keywords NAXIS*,EXTNAME,TFIELDS,TTYPE*,TFORM*,TUNIT*,
are read from the header and displayed at the terminal
A FITS header is recognized as bein for a binary table if the keyword
XTENSION has the value 'BINTABLE' or 'A3DTABLE'
NOTES:
Certain fields may be truncated in the display
SYSTEM VARIABLES:
Uses the non-standard system variables !TEXTOUT and !TEXTUNIT. These
are automatically defined by TBHELP if they have not been defined
previously.
PROCEDURES USED:
REMCHAR, SXPAR(), TEXTCLOSE, TEXTOPEN, ZPARCHECK
HISTORY:
W. Landsman February, 1991
Parsing of a FITS binary header made more robust May, 1992
Added TEXTOUT keyword August 1997
Define !TEXTOUT if not already present W. Landsman November 2002
Slightly more compact display W. Landsman August 2005
Fix Aug 2005 error omitting TFORM display W. Landsman Sep 2005
(See external/astron/fits_table/tbhelp.pro)
NAME:
TBINFO
PURPOSE:
Return an informational IDL structure from a FITS binary table header.
CALLING SEQUENCE:
tbinfo, h, tb_str, [ERRMSG = ]
INPUTS:
h - FITS binary table header, e.g. as returned by READFITS()
OUTPUTS:
tb_str - IDL structure with extracted info from the FITS binary table
header. Tags include
.tbcol - starting column position in bytes, integer vector
.width - width of the field in bytes, integer vector
.idltype - idltype of field, byte vector
7 - string, 4- real*4, 3-integer*4, 5-real*8
.numval - repeat count, 64 bit longword vector
.tunit - string unit numbers, string vector
.tnull - integer null value for the field, stored as a string vector
so that an empty string indicates that TNULL is not present
.tform - format for the field, string vector
.ttype - field name, string vector
.maxval- maximum number of elements in a variable length array, long
vector
.tscal - pointer array giving the scale factor for converting to
physical values, default 1.0
.tzero - pointer array giving the additive offset for converting to
physical values, default 0.0
.tdisp - recommended output display format
All of the output vectors will have same number of elements, equal
to the number of columns in the binary table.
The .tscal and .tzero values are stored as pointers so as to preserve
the individual data types (e.g. float or double) which may differ
in different columns. For example, to obtain the value of TSCAL for
the third column use *tab_str.tscal[2]
OPTIONAL INPUT KEYWORD:
/NOSCALE - if set, then the TSCAL* and TZERO* keywords are not extracted
from the FITS header, and the .tscal and .tzero pointers do not
appear in the output structure.
OPTIONAL OUTPUT KEYWORD:
ERRMSG = if present, then error messages are returned in this keyword
rather than displayed using the MESSAGE facility
PROCEDURES USED:
SXPAR()
NOTES:
For variable length ('P' format) column, TBINFO returns values for
reading the 2 element longward array of pointers (numval=2,
idltype = 3, width=4)
HISTORY:
Major rewrite to return a structure W. Landsman August 1997
Added "unofficial" 64 bit integer "K" format W. Landsamn Feb. 2003
Store .tscal and .tzero tags as pointers, so as to preserve
type information W. Landsman April 2003
Treat repeat count for string as specifying string length, not number
of elements, added ERRMSG W. Landsman July 2006
Treat logical as character string 'T' or 'F' W. Landsman October 2006
Added NOSCALE keyword W. Landsman March 2007
Make .numval 64 bit for very large tables W. Landsman April 2014
Make sure XTENSION is for a FITS binary table W. Landsman May 2017
(See external/astron/fits_table/tbinfo.pro)
NAME:
TBPRINT
PURPOSE:
Procedure to print specified columns & rows of a FITS binary table
CALLING SEQUENCE:
TBPRINT, h, tab, columns, [ rows, TEXTOUT =, FMT=, NUM_HEADER= ]
or
TBPRINT,tb_str, tab, columns, [ rows, TEXTOUT =, FMT=, NUM_HEADER = ]
INPUTS:
h - FITS header for table, string array
or
tb_str - IDL structure extracted from FITS header by TBINFO, useful
when TBPRINT is called many times with the same header
tab - table array
columns - string giving column names, or vector giving
column numbers (beginning with 1). If string
supplied then column names should be separated by comma's.
If set to '*' then all columns are printed in table format
(1 row per line, binary tables only).
rows - (optional) vector of row numbers to print. If
not supplied or set to scalar, -1, then all rows
are printed.
OUTPUTS:
None
OPTIONAL INPUT KEYWORDS:
FMT = Format string for print display. If not supplied, then any
formats in the TDISP keyword fields of the table will be
used, otherwise IDL default formats.
NUM_HEADER_LINES - Number of lines to display the column headers
default = 1). By setting NUM_HEADER_LINES to an integer larger
than 1, one can avoid truncation of the column header labels.
In addition, setting NUM_HEADER_LINES will display commented
lines indicating a FORMAT for reading the data, and a
suggested call to readfmt.pro.
NVAL_PER_LINE - The maximum number of values displayed from a multivalued
column when printing in table format. Default = 6
TEXTOUT - scalar number (0-7) or string (file name) determining
output device (see TEXTOPEN). Default is TEXTOUT=1, output
to the user's terminal
SYSTEM VARIABLES:
Uses nonstandard system variables !TEXTOUT and !TEXTOPEN
Set !TEXTOUT = 3 to direct output to a disk file. The system
variable is overriden by the value of the keyword TEXTOUT
EXAMPLES:
tab = readfits('test.fits',htab,/ext) ;Read first extension into vars
tbprint,h,tab,'STAR ID,RA,DEC' ;print id,ra,dec for all stars
tbprint,h,tab,[2,3,4],indgen(100) ;print columns 2-4 for
first 100 stars
tbprint,h,tab,text="stars.dat" ;Convert entire FITS table to
;an ASCII file named 'stars.dat'
PROCEDURES USED:
GETTOK(), STRNUMBER(), TEXTOPEN, TEXTCLOSE, TBINFO
RESTRICTIONS:
(1) Program does not check whether output length exceeds output
device capacity (e.g. 80 or 132).
(2) Column heading may be truncated to fit in space defined by
the FORMAT specified for the column. Use NUM_HEADER_LINES
to avoid truncation.
(3) Program does not check for null values
(4) Does not work with variable length columns
(5) Will only the display the first value of fields with multiple values
(unless there is one row each with the same number of mulitple values)
If printing in table format (column='*') then up to 6 values
can be printed per line.
HISTORY:
version 1 D. Lindler Feb. 1987
Accept undefined values of rows,columns W. Landsman August 1997
Use new structure returned by TBINFO W. Landsman August 1997
Made formatting more robust W. Landsman March 2000
Use STRSPLIT to parse string column listing W. Landsman July 2002
Wasn't always printing last row W. Landsman Feb. 2003
Better formatting (space between columns) W. Landsman Oct. 2005
Use case-insensitive match with TTYPE, use STRJOIN W.L. June 2006
Fixed check for multiple values W.L. August 2006
Fixed bad index value in August 2006 fix W.L Aug 15 2006
Free-up pointers after calling TBINFO W.L. Mar 2007
Add table format capability W.L. Mar 2010
Add NUM_HEADER_LINE keyword P. Broos Apr 2010
(See external/astron/fits_table/tbprint.pro)
NAME:
TBSIZE
PURPOSE:
Procedure to return the size of a FITS binary table.
CALLING SEQUENCE:
tbsize, h, tab, ncols, nrows, tfields, ncols_all, nrows_all
INPUTS:
h - FITS table header
tab - FITS table array
OUTPUTS:
ncols - number of characters per row in table
nrows - number of rows in table
tfields - number of fields per row
ncols_all - number of characters/row allocated (size of tab)
nrows_all - number of rows allocated
PROCEDURES USED:
SXPAR()
HISTORY
D. Lindler July, 1987
Converted to IDL V5.0 W. Landsman September 1997
Remove obsolete !ERR call W. Landsman May 2000
(See external/astron/fits_table/tbsize.pro)